Files
archie/docs/prds/curator-sampler-wave1.md
T
sam 65e6b2f65b 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

178 lines
9.0 KiB
Markdown

# 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.
```go
// 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