Three defects the first sweep left behind, each caught by a rule the guard did not yet have. Statuses. RULES.md gives three; the tree had 25 values, and the free-text ones were carrying progress. "Implemented (wiring landed)" and "Ratified (rev. 2e). Rev. 2e adds the OpenTaskByPR lookup. Rev. 2d revised section 10..." were both changelogs living in the one field the other rules exempt. Every PRD now declares Draft, Approved or Finalised and nothing else; five that declared nothing now declare one. A revision number moves to **Revision:**, a pointer to the authoritative document to **Authority:**, and what a past revision changed to git. CLAUDE.md's citation of state-store-contract rev. 2e still resolves. Stale cross-references. "Supersedes the 2026-09-03 open question", "this bullet previously said", "an earlier draft of this document claimed" all point at text the reader cannot see, because it was replaced. A supersede marker survives only when it names a file, a section or a symbol that can be found. Temporal hedges. 100 uses of today, currently and right now across 31 files. Each dates its sentence to the day it was written: "[notify] today is one webhook URL, read in one place" stops being true the moment this design lands, while still reading as the premise it rests on. The header-field exemption was also too wide. "**Date:** 2026-09-03, Channel resolved 2026-09-22" smuggled a dated status into the one line the rules did not read; the exemption is now a Date holding only a date and a Status holding only one of the three.
9.0 KiB
Curator sampler wave 1: Sampler interface + four cheap strategies -- decision
Status: Approved
Date: 2026-09-05
Beads issue: bead archie-core-1786637500776-416-600a66e5 / GitHub #437
covers the embedding-backed follow-on strategy only. This PRD covers the
prerequisite interface and the cheap strategies.
Parent epic: archie-core-1786637500725 (curator engine)
Depends on: nothing shipped (this is itself a prerequisite)
Blocks: the embedding-backed surprisal strategy (GitHub #437), which
implements this same interface once the embeddings capability
(internal/domain/embedding, this change) lands
Problem
A future curator that reviews a large body of content (memories, sessions,
skills) cannot always afford to run its agentic budget over every candidate
every pass. It needs to pick a bounded subset first. GitHub #437's acceptance
criteria requires that subset-picking to sit "behind a Sampler interface
that wave 1 of the curator epic ships (cheap strategies: recency, random,
all, staleness proxy)" and that the embedding-backed strategy implement "the
same interface" later. No such interface, and none of the four cheap
strategies, exist anywhere in the codebase (bead 434e5bb9's closure
without a linked PR was the tracker being wrong, not the code existing) --
this PRD is the one-page settled design for it, per this repo's Scope
Discipline rule.
Decision
A Sampler is a pure, call-scoped selection function: given a fixed slice of
candidates and a request, it returns a subset. No lifecycle, no host access,
no I/O for the four wave-1 strategies -- they are computation only, so they
live directly in internal/domain/sampling (a domain package, not
internal/infrastructure/*) alongside the contract, the same way
curator/activity.go's pure ring buffer sits next to curator/contract.go
rather than in an infrastructure package.
// Package sampling is the curator sampler family: given a bounded set of
// candidates, pick a subset to spend a curator pass's agentic budget on.
// See docs/prds/curator-sampler-wave1.md.
package sampling
// Candidate is one item eligible for sampling. It is deliberately narrow:
// an opaque identifier, the timestamp the timestamp-based strategies score
// against, and an open Metadata bag for whatever a future strategy needs
// (e.g. the embedding-backed surprisal strategy's vector) without widening
// this struct for every strategy that comes after wave 1.
type Candidate struct {
ID string
At time.Time
Metadata map[string]any
}
// Request carries the knobs every strategy shares: a selection cap and a
// deterministic seed. Both are optional -- Cap 0 means unlimited (the "all"
// strategy relies on this), Seed 0 is a valid seed, not "unset".
type Request struct {
Cap int
Seed int64
}
// Sampler selects a subset of candidates to spend a curator pass's agentic
// budget on. Every implementation -- the four here and the future
// embedding-backed surprisal strategy (GitHub #437) -- must be
// deterministic given the same candidates and Request: same inputs, same
// output, every time. That is what makes a pass reproducible and testable,
// and is GitHub #437's stated acceptance criterion for the strategy it
// adds behind this same interface.
type Sampler interface {
// Name identifies the strategy for logging/attribution (e.g.
// "recency", "random", "all", "staleness", later "surprisal").
Name() string
// Sample selects from candidates per req. Implementations must not
// mutate candidates or rely on anything but candidates and req --
// determinism depends on that.
Sample(ctx context.Context, candidates []Candidate, req Request) ([]Candidate, error)
}
The four wave-1 strategies
All four are internal/domain/sampling types constructed with NewX(...),
each implementing Sampler:
recency(NewRecency()): sorts candidates newest-At-first (stable sort, ties keep input order so output is deterministic even when two candidates share a timestamp), then truncates toreq.Cap(0 = all).staleness(NewStaleness()): the mirror of recency -- sorts oldest-At-first, then truncates toreq.Cap. This is explicitly a proxy: "hasn't been touched in the longest time" using whatever timestamp the caller populatedCandidate.Atwith (created, updated, or last-reviewed -- the caller's choice, not this package's), never the embedding-based surprisal calculation GitHub #437 owns.all(NewAll()): no filtering. Returns candidates in input order, truncated toreq.Cap(0 = every candidate). Input order is the only order this strategy has an opinion about, and preserving it is what makes it deterministic.random(NewRandom()): a uniform-random subset, sized toreq.Cap(0 = every candidate, order-shuffled). Determinism comes fromreq.Seed:math/rand/v2'srand.New(rand.NewPCG(seed, seed))seeded per call (not a package-level or struct-level generator), so the same(candidates, req)pair always produces the same permutation regardless of call order or concurrent callers -- required for GitHub #437's determinism criterion and for this package's own tests.
Why one shared Request and not one options struct per strategy
The embedding-backed strategy (GitHub #437) is deferred, but its stated
shape -- "sample up to a candidate cap," a seed for reproducible tie-
breaking in the power-iteration -- already fits Request{Cap, Seed}
without modification. A per-strategy options type would mean GitHub #437
either reuses this one (proving it was unnecessary to split) or grows its
own incompatible shape that the Sampler interface can't express without a
breaking change later. One shared, small Request is the smallest thing
that already accommodates the known future consumer.
Why Candidate.Metadata map[string]any instead of a typed field per strategy
Only ID and At are used by any wave-1 strategy. Metadata exists solely
so GitHub #437 can carry an embedding vector (or whatever else the k-NN/
power-iteration step needs) through the same Candidate type without this
package importing internal/domain/embedding or growing a Vector field
that every non-surprisal strategy ignores. Untyped and optional, exactly
like image.GenerateRequest.Options and curator.Action.Detail's existing
"provider-specific overflow" convention elsewhere in this codebase.
What we deliberately do NOT do
- No curator-family wiring.
curator.Registrargains noSamplerfield and no curator declares one in this change. Nothing ininternal/domain/curatorconsumessampling.Sampleryet -- there is no curator that samples anything. Wiring a sampler into a real curator'sPassis that future curator's job, not this prerequisite's. - No embedding-backed strategy. That is GitHub #437, explicitly
deferred behind the embeddings capability this same change also adds
(
internal/domain/embedding) -- see that issue for the k-NN graph / power-iteration / surprisal-scoring algorithm. This package only guarantees the interface shape GitHub #437 must implement. - No persistence, no candidate discovery.
Sampler.Sampletakescandidatesas a plain slice; where they come from (a memory store, a session list, a skill directory) is entirely the caller's concern, same boundarycurator.Registrar'sSkillStore/ConversationSourcealready draw between "the curator finds candidates" and "the curator engine acts on them." - No configuration surface. Strategy selection (which
Samplera curator uses) is a future curator's constructor argument, not a new[curator]config section -- no curator exists yet to configure.
Acceptance criteria
Samplerinterface plusCandidate/Requesttypes exist ininternal/domain/sampling, importing nothing frominternal/infrastructure/*orinternal/app/*(domain-layer rule).- Four
Samplerimplementations (recency,random,all,staleness) with table-driven tests proving: correct selection per strategy,Captruncation (includingCaplarger than the candidate count, andCap0 meaning unlimited), and -- forrandom-- that the same(candidates, req)produces the same output across repeated calls (determinism), while a differentreq.Seedcan produce a different permutation. - Every strategy's
Sampleleaves the inputcandidatesslice unmodified (verified by a shared test helper across all four). - The interface shape is reviewed against GitHub #437's stated
acceptance criteria ("a
Samplergiven fixed inputs producing deterministic selection," "sample up to a candidate cap") and accommodates them without a breaking change -- this document's "Why one sharedRequest" section is that review.
Files this change adds
internal/domain/sampling/contract.go--Sampler,Candidate,Requestinternal/domain/sampling/recency.go,staleness.go,all.go,random.go-- the four strategiesinternal/domain/sampling/*_test.go-- table-driven tests per strategy plus the shared non-mutation test helper