Files
archie/docs/prds/curator-sampler-wave1.md
T
sam e832b8ef0c docs(prds): normalise statuses and remove writing dated to its own day
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.
2026-09-22 00:38:35 +10:00

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 to req.Cap (0 = all).
  • staleness (NewStaleness()): the mirror of recency -- sorts oldest- At-first, then truncates to req.Cap. This is explicitly a proxy: "hasn't been touched in the longest time" using whatever timestamp the caller populated Candidate.At with (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 to req.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 to req.Cap (0 = every candidate, order-shuffled). Determinism comes from req.Seed: math/rand/v2's rand.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.Registrar gains no Sampler field and no curator declares one in this change. Nothing in internal/domain/curator consumes sampling.Sampler yet -- there is no curator that samples anything. Wiring a sampler into a real curator's Pass is 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.Sample takes candidates as a plain slice; where they come from (a memory store, a session list, a skill directory) is entirely the caller's concern, same boundary curator.Registrar's SkillStore/ConversationSource already draw between "the curator finds candidates" and "the curator engine acts on them."
  • No configuration surface. Strategy selection (which Sampler a curator uses) is a future curator's constructor argument, not a new [curator] config section -- no curator exists yet to configure.

Acceptance criteria

  1. Sampler interface plus Candidate/Request types exist in internal/domain/sampling, importing nothing from internal/infrastructure/* or internal/app/* (domain-layer rule).
  2. Four Sampler implementations (recency, random, all, staleness) with table-driven tests proving: correct selection per strategy, Cap truncation (including Cap larger than the candidate count, and Cap 0 meaning unlimited), and -- for random -- that the same (candidates, req) produces the same output across repeated calls (determinism), while a different req.Seed can produce a different permutation.
  3. Every strategy's Sample leaves the input candidates slice unmodified (verified by a shared test helper across all four).
  4. The interface shape is reviewed against GitHub #437's stated acceptance criteria ("a Sampler given fixed inputs producing deterministic selection," "sample up to a candidate cap") and accommodates them without a breaking change -- this document's "Why one shared Request" section is that review.

Files this change adds

  • internal/domain/sampling/contract.go -- Sampler, Candidate, Request
  • internal/domain/sampling/recency.go, staleness.go, all.go, random.go -- the four strategies
  • internal/domain/sampling/*_test.go -- table-driven tests per strategy plus the shared non-mutation test helper