feat(curator): engine family contract, registry, and runtime (archie-core-rfp, archie-core-89x)

internal/curator is a conforming engine family per the strict plugin
engine rule: typed CuratorEngine contract (Lifecycle + domain ops),
owning Registry (registration, discovery, start/health/stop with
failure isolation, reverse-order shutdown, ctx-bounded stop), and a
narrow typed Registrar — each curator receives a capability-filtered
view of the host at Bind, never the daemon.

Runtime: one loop per curator on an injectable clock (fake-clock
testable), best-effort wake nudges with the trigger decision kept in
Check (a dropped nudge only delays to the next check-in, never
corrupts accounting), per-pass timeout and a max-concurrent-passes
slot so curator bursts cannot starve chat turns, per-pass panic
recovery, and bounded shutdown even when a pass ignores cancellation.
curator_run / curator_action / curator_error ride the in-process
event bus so activity stays attributable.

Wired in cmd/archied/main.go (constructed beside memory, Start after
daemon startup, shutdown ordered before memory/LLM teardown) and
exposed as daemon.Daemon.Curators.
This commit is contained in:
sam committed 2026-08-05 14:54:12 +10:00
1 parent 0ddc43081e
commit 4ece064026
11 files changed
+2054

No files matched your search

+49
View File
@@ -29,6 +29,7 @@ import (
"github.com/samcharles93/archie-core/internal/channels/webhook"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/container"
"github.com/samcharles93/archie-core/internal/curator"
"github.com/samcharles93/archie-core/internal/daemon"
"github.com/samcharles93/archie-core/internal/domain/workintake"
"github.com/samcharles93/archie-core/internal/events"
@@ -639,6 +640,38 @@ func run() int {
}()
log.Info("memory manager started", "dir", memDir)
// ── Curator engine family ────────────────────────────────────────
// The registry owns curator registration, lifecycle and shutdown
// ordering. The runtime loop (archie-core-89x) and the reference
// curators (archie-core-i7i, gs8) are wired by their issues; until
// then the registry is empty and Stop is a no-op. The event sink
// rides the in-process bus, whose bounded dropping per-subscriber
// buffers guarantee curator activity can never backpressure the
// daemon or a chat turn.
curatorRegistry := curator.NewRegistry(curator.Registrar{
Events: curatorEventSink{bus},
})
// The runtime owns the per-curator loops (archie-core-89x): one
// goroutine per curator, wake nudges, per-pass budgets, panic
// recovery, bounded shutdown. Stop order at shutdown: runtime first
// (cancels in-flight passes, then stops curator lifecycle), then the
// registry's own Stop below, which is a no-op by then.
curatorRuntime := curator.NewRuntime(curatorRegistry, curator.RuntimeConfig{})
defer func() {
stopCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
if err := curatorRuntime.Stop(stopCtx); err != nil {
log.Error("curator runtime shutdown", "err", err)
}
}()
defer func() {
stopCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
if err := curatorRegistry.Stop(stopCtx); err != nil {
log.Error("curator registry shutdown", "err", err)
}
}()
// ── Guardrail engine ───────────────────────────────────────────────
gc := tools.DefaultGuardrailConfig()
guardrails := tools.NewGuardrailEngine(gc)
@@ -722,6 +755,7 @@ func run() int {
Memory: memManager,
Guardrails: guardrails,
ToolRegistry: toolReg,
Curators: curatorRegistry,
Identities: identityRunners,
}
@@ -753,6 +787,9 @@ func run() int {
log.Error("startup", "err", err)
return 1
}
if err := curatorRuntime.Start(ctx); err != nil {
log.Error("curator runtime startup", "err", err)
}
for _, startGateway := range startGateways {
startGateway()
}
@@ -769,6 +806,18 @@ func run() int {
return 0
}
// curatorEventSink adapts the in-process event bus to the curator family's
// narrow emission contract. Bus publish is non-blocking with bounded,
// dropping per-subscriber buffers, so curator activity can never
// backpressure the daemon or a chat turn.
type curatorEventSink struct {
b *events.Bus
}
func (s curatorEventSink) Emit(kind, detail string, data map[string]any) {
s.b.Publish(events.Event{Kind: kind, Detail: detail, Data: data})
}
type chatTaskWriterAdapter struct {
enqueue func(
ctx context.Context,
@@ -40,3 +40,34 @@ A plugin:
Plugins may be internally cohesive like small services. They do not become
network services without a concrete security or operational reason.
## Curator surprisal sampling (deferred)
The curator engine family (epic `archie-core-yp9`) selects which memories
deserve agentic attention via surprisal-based sampling: score memories by how
surprising they are and spend the sampled reasoner's agentic budget on the
most surprising items. Wave 1 of the epic ships the `Sampler` strategy seam in
`internal/curator` with cheap, embedding-free strategies (recency, random,
all, and a staleness proxy). The embedding-backed strategy is a documented
extension point and is gated behind an embedding capability Archie does not
yet have — **any surprisal-style sampling is gated behind adding one**.
Requirements for the deferred work, so it can be picked up without
re-deriving the design (tracked as `archie-core-yp9.1` embeddings capability,
then `archie-core-yp9.2` surprisal strategies):
- A `Sampler` implementation behind the same interface as the cheap
strategies; selection deterministic given fixed inputs.
- Algorithm: sample up to a candidate cap; build a k-NN graph over embedding
vectors; row-normalize the adjacency with self-loops; power-iterate to the
stationary distribution; surprisal = −log(stationary probability of the
nearest point); select the highest-surprisal items.
- Degradation: content without an embedding is skipped; an embedding failure
aborts sampling and falls back to free exploration — a sampling failure
must never fail or crash a curator pass.
- Cost bound: the graph build is quadratic in the candidate cap; the cap must
be a named constant with a documented bound.
- The embedding capability itself: a narrow typed client usable by in-process
components, config-driven provider/model, credential-missing degrades to
"capability unavailable" (daemon still starts), timeouts on network calls,
tests via httptest only.
+147
View File
@@ -0,0 +1,147 @@
// Package curator is the curator engine family: long-running agent loops
// that reason over memory and perform small maintenance tasks, rather than
// one hardcoded background job. See epic archie-core-yp9.
//
// A curator is defined by a declared shape (check-in interval, tool set,
// attached memory engine), runs persistently while there is input, and backs
// off to a cooldown when idle. The family follows the strict plugin engine
// rule: a typed contract (CuratorEngine), an owning registry (Registry) with
// start/health/stop and shutdown ordering, and narrow typed host access
// (Registrar) — a curator never receives the daemon or an untyped hook map.
package curator
import (
"context"
"errors"
"strings"
"time"
)
// HealthStatus is a curator's point-in-time health.
type HealthStatus string
const (
HealthHealthy HealthStatus = "healthy"
HealthDegraded HealthStatus = "degraded"
HealthUnhealthy HealthStatus = "unhealthy"
)
// Health is a point-in-time curator health report.
type Health struct {
Status HealthStatus
Message string
}
// Manifest is a curator's declared shape: what input wakes it, how often it
// runs, which tools it may reach, and which memory engine it uses. The
// registry validates the manifest at registration, so a curator can never
// discover capabilities it did not declare.
type Manifest struct {
// Interval is the check-in cadence: how often a pass is eligible when
// there is no pending input. Must be positive.
Interval time.Duration
// Cooldown is the backoff after a pass that found nothing to do. Zero
// lets the runtime pick a multiple of Interval.
Cooldown time.Duration
// OnInput marks the curator as input-driven: primary input (e.g. a
// completed chat turn) wakes it before the next interval. Wake events
// are best-effort nudges; the trigger decision is a deterministic
// state read at pass time (archie-core-035).
OnInput bool
// Tools is the declared tool set: the only tools a pass may reach.
// Enforcement is mechanical — the pass's tool set is built from this
// list, never from a broader registry.
Tools []string
// Skills declares the skill-maintenance capability (skill curator,
// archie-core-i7i). The registrar must carry a SkillStore for a
// curator that declares it.
Skills bool
// MemoryEngine names the attached memory engine once the memory engine
// family exists (archie-core-pek). Empty means the curator does not
// use memory; a memory operation without a declared engine is
// rejected.
MemoryEngine string
// Model is the model reference ("provider/model") passes use. Empty
// uses the registrar's default.
Model string
}
// Validate checks the declared shape. It is called by the registry at
// registration; a curator with an invalid manifest is refused.
func (m Manifest) Validate() error {
if m.Interval <= 0 {
return errors.New("curator manifest: interval must be positive")
}
for _, tool := range m.Tools {
if strings.TrimSpace(tool) == "" {
return errors.New("curator manifest: tool names must be non-empty")
}
}
return nil
}
// Lifecycle is the start/health/stop contract every curator implements. The
// registry drives it with shutdown ordering and failure isolation; a
// curator's Health must never panic the daemon.
type Lifecycle interface {
Start(ctx context.Context) error
Health(ctx context.Context) Health
Stop(ctx context.Context) error
}
// CuratorEngine is the typed contract every curator implements. Name/Version
// are identity, Manifest declares the shape, Check/Pass are the domain
// operations, Bind receives the narrow host access, and Lifecycle carries
// start/health/stop.
type CuratorEngine interface {
Lifecycle
Name() string
Version() string
Manifest() Manifest
// Check reports whether a pass should run now. It must be cheap: no
// model calls, no work a chat turn would wait on. The runtime calls it
// when deciding whether to run a pass early.
Check(ctx context.Context) (bool, error)
// Pass runs one maintenance pass. The runtime guarantees at most one
// in-flight pass per curator, bounds it with context cancellation and
// per-pass budgets, and recovers panics so a failing pass never takes
// down another curator, a chat turn, or the daemon.
Pass(ctx context.Context, in PassInput) (PassResult, error)
// Bind attaches the curator's narrow host access. The registry calls
// Bind exactly once, at registration, with a view filtered to the
// curator's declared capabilities.
Bind(host Registrar)
}
// PassInput carries why a pass runs and the input horizon it may consume.
type PassInput struct {
// Reason describes why this pass runs (e.g. "20 primary turns since
// last pass" or "daily check-in"). It is recorded on actions and
// events so curator activity stays attributable.
Reason string
// Since is the input horizon: primary input at or after this time is
// this pass's material. Zero means the curator decides.
Since time.Time
// LastPass is when the previous pass started; zero for the first pass.
LastPass time.Time
}
// PassResult reports what a pass did. Every action is attributable: the
// registry emits them as events and they are inspectable at runtime
// (archie-core-114).
type PassResult struct {
// Actions records what this pass changed and why.
Actions []Action
// NextCheckIn lets a pass suggest the next eligible time (e.g. a
// longer backoff when there was nothing to do). Zero means the
// runtime uses the manifest interval and cooldown.
NextCheckIn time.Time
}
// Action records one change a curator made and why.
type Action struct {
At time.Time
Type string // e.g. "skill.updated", "memory.written"
Detail string // what changed, human-readable
Reason string // why it happened
}
+72
View File
@@ -0,0 +1,72 @@
package curator
import (
"testing"
"time"
)
func TestManifestValidate(t *testing.T) {
t.Parallel()
tests := []struct {
name string
manifest Manifest
wantErr bool
}{
{
name: "valid minimal",
manifest: Manifest{Interval: time.Hour},
},
{
name: "valid full",
manifest: Manifest{
Interval: time.Hour,
Cooldown: time.Minute,
OnInput: true,
Tools: []string{"skills.list", "skills.write"},
Skills: true,
MemoryEngine: "builtin",
Model: "provider/model",
},
},
{
name: "zero interval",
manifest: Manifest{},
wantErr: true,
},
{
name: "negative interval",
manifest: Manifest{Interval: -time.Hour},
wantErr: true,
},
{
name: "empty tool name",
manifest: Manifest{Interval: time.Hour, Tools: []string{""}},
wantErr: true,
},
{
name: "blank tool name",
manifest: Manifest{Interval: time.Hour, Tools: []string{" "}},
wantErr: true,
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
t.Parallel()
err := tt.manifest.Validate()
if (err != nil) != tt.wantErr {
t.Fatalf("Validate() error = %v, wantErr %v", err, tt.wantErr)
}
})
}
}
func TestManifestValidateRejectsDuplicateTools(t *testing.T) {
t.Parallel()
m := Manifest{Interval: time.Hour, Tools: []string{"skills.list", "skills.list"}}
if err := m.Validate(); err != nil {
t.Fatalf("Validate() = %v, want nil (duplicates are the builder's problem)", err)
}
}
+113
View File
@@ -0,0 +1,113 @@
package curator
import (
"context"
"time"
"github.com/samcharles93/archie-core/internal/tools"
)
// Registrar is the narrow typed host access a curator receives at
// registration. Only the services the curator's declared shape requires are
// ever populated in the view the registry binds (see Registry.filter); the
// daemon itself is never part of it. Fields are typed contracts declared
// here — this package never names who implements them.
type Registrar struct {
// Model is the default model reference ("provider/model") for
// curators whose manifest leaves Model empty.
Model string
// LLM provides model access for agentic passes. Bound when the curator
// declares an agentic capability (tools, skills, or a memory engine).
LLM LLMRunner
// Tools resolves the declared tool names into a runnable tool set.
// Resolution is the enforcement point: a pass receives exactly the
// declared set, never a broader registry. Bound when tools are
// declared.
Tools ToolBuilder
// Skills is the skill-maintenance capability (skill curator,
// archie-core-i7i). Bound when the curator declares Skills.
Skills SkillStore
// Events publishes curator activity. Implementations must be
// non-blocking and bounded (drop on overflow), so a curator can never
// apply backpressure to a chat turn or the daemon. Always bound.
Events EventSink
// Clock is injectable time. Always bound; nil at construction is
// replaced with the system clock.
Clock Clock
}
// LLMRunner is the model access a curator needs for a pass. The app layer
// adapts the shared runtime to this narrow contract.
type LLMRunner interface {
Chat(ctx context.Context, req ChatRequest) (ChatResult, error)
}
// ChatRequest is one model call: messages plus the runnable tool set.
type ChatRequest struct {
Model string
Messages []Message
Tools []tools.ToolEntry
MaxSteps int
}
// Message is one conversation message.
type Message struct {
Role string // e.g. "system", "user", "assistant", "tool"
Content string
}
// ChatResult is the model's final answer.
type ChatResult struct {
Text string
}
// ToolBuilder resolves declared tool names into a runnable tool set. A
// declared name with no implementation fails the pass rather than silently
// running with fewer tools, and no tool outside the declared set is
// returned.
type ToolBuilder interface {
Build(ctx context.Context, declared []string) ([]tools.ToolEntry, error)
}
// SkillStore is the skill-maintenance capability. The implementation owns
// the on-disk format and catalog reload rules (archie-core-i7i).
type SkillStore interface {
List(ctx context.Context) ([]SkillRef, error)
Read(ctx context.Context, name string) (Skill, error)
Write(ctx context.Context, s Skill) error
Delete(ctx context.Context, name string) error
}
// SkillRef identifies one skill on disk.
type SkillRef struct {
Name string
Path string
}
// Skill is one skill definition.
type Skill struct {
Name string
Content string
Description string
}
// EventSink publishes curator activity (what ran, what changed, why). It is
// the emission side only; wake signals arrive through the runtime's own
// subscription (archie-core-89x). Implementations MUST be non-blocking and
// bounded, matching the in-process event bus semantics.
type EventSink interface {
Emit(kind, detail string, data map[string]any)
}
// Clock is injectable time: Now for timestamps and After for loop sleeps.
// The runtime's loop timing is tested with a fake clock, never wall-clock
// sleeps (archie-core-89x); the real implementation is the system clock.
type Clock interface {
Now() time.Time
After(d time.Duration) <-chan time.Time
}
type systemClock struct{}
func (systemClock) Now() time.Time { return time.Now() }
func (systemClock) After(d time.Duration) <-chan time.Time { return time.After(d) }
+287
View File
@@ -0,0 +1,287 @@
package curator
import (
"context"
"errors"
"fmt"
"reflect"
"slices"
"sync"
)
// Registry errors.
var (
// ErrDuplicate is returned when a curator name is already registered.
ErrDuplicate = errors.New("duplicate curator")
// ErrStarted is returned when registration or lifecycle is attempted
// after the registry has started.
ErrStarted = errors.New("curator registry already started")
)
type registryState uint8
const (
stateIdle registryState = iota
stateRunning
stateStopped
)
type curatorStatus struct {
started bool
startErr error
}
// Registry is the curator family owner: it controls registration and
// discovery, lifecycle (start/health/stop), shutdown ordering, and failure
// isolation. A curator failure — a rejected registration, a failing Start, a
// blocking Stop, even a panicking Bind — affects only that curator and is
// reported, never fatal to the daemon or to other curators.
type Registry struct {
mu sync.Mutex
host Registrar
curators map[string]CuratorEngine
status map[string]curatorStatus
order []string
state registryState
}
// NewRegistry builds the family registry. A nil Clock is replaced with the
// system clock; every other nil service is valid until a curator declares
// the capability that requires it.
func NewRegistry(host Registrar) *Registry {
if host.Clock == nil {
host.Clock = systemClock{}
}
return &Registry{
host: host,
curators: make(map[string]CuratorEngine),
status: make(map[string]curatorStatus),
}
}
// Register validates the curator's declared shape against the registrar and
// adds it, binding the curator to a host view filtered to its declared
// capabilities. Registration fails on nil engines, invalid manifests,
// duplicate names, a declared capability with no host service behind it, or
// a panicking Bind — and a failure affects only that curator.
func (r *Registry) Register(c CuratorEngine) error {
if isNilEngine(c) {
return errors.New("curator: nil engine")
}
m := c.Manifest()
if err := m.Validate(); err != nil {
return err
}
if err := r.validateDeclared(m); err != nil {
return err
}
r.mu.Lock()
defer r.mu.Unlock()
if r.state != stateIdle {
return ErrStarted
}
if _, dup := r.curators[c.Name()]; dup {
return fmt.Errorf("%w: %s", ErrDuplicate, c.Name())
}
if err := bindSafely(c, r.filter(m)); err != nil {
return err
}
r.curators[c.Name()] = c
r.order = append(r.order, c.Name())
return nil
}
// validateDeclared enforces "only the host services a curator's declared
// shape requires": a declared capability must have a host service behind it.
// A curator can never discover the daemon or an untyped hook map here — the
// registrar is the only channel.
func (r *Registry) validateDeclared(m Manifest) error {
if len(m.Tools) > 0 && r.host.Tools == nil {
return errors.New("curator manifest: declares tools but the registrar has no ToolBuilder")
}
if m.Skills && r.host.Skills == nil {
return errors.New("curator manifest: declares the skills capability but the registrar has no SkillStore")
}
return nil
}
// filter returns the registrar view narrowed to the curator's declared
// capabilities. Events and Clock are always present (activity must stay
// attributable and time is universal); model access is present only for
// agentic curators; every capability service is present only when declared.
func (r *Registry) filter(m Manifest) Registrar {
v := r.host
if !agentic(m) {
v.LLM = nil
}
if len(m.Tools) == 0 {
v.Tools = nil
}
if !m.Skills {
v.Skills = nil
}
return v
}
func agentic(m Manifest) bool {
return len(m.Tools) > 0 || m.Skills || m.MemoryEngine != ""
}
// bindSafely isolates a panicking Bind: a curator that panics while
// receiving its host access is refused without taking the registry down.
func bindSafely(c CuratorEngine, host Registrar) (err error) {
defer func() {
if p := recover(); p != nil {
err = fmt.Errorf("curator %s: bind panic: %v", c.Name(), p)
}
}()
c.Bind(host)
return nil
}
// Host returns the raw registrar bundle the registry was built with — the
// shared services (events, clock, model) the runtime and future surfaces
// use. It is narrow typed; the daemon itself is never part of it.
func (r *Registry) Host() Registrar {
r.mu.Lock()
defer r.mu.Unlock()
return r.host
}
// Get returns the registered curator by name.
func (r *Registry) Get(name string) (CuratorEngine, bool) {
r.mu.Lock()
defer r.mu.Unlock()
c, ok := r.curators[name]
return c, ok
}
// Names returns the registered curator names in sorted order.
func (r *Registry) Names() []string {
r.mu.Lock()
defer r.mu.Unlock()
names := make([]string, 0, len(r.curators))
for name := range r.curators {
names = append(names, name)
}
slices.Sort(names)
return names
}
// Start starts every registered curator in registration order. A curator
// whose Start fails (error or panic) is marked unhealthy and skipped; the
// rest start regardless, and all failures are joined into the returned
// error. This is the family's failure-isolation boundary for lifecycle.
func (r *Registry) Start(ctx context.Context) error {
r.mu.Lock()
if r.state != stateIdle {
r.mu.Unlock()
return ErrStarted
}
r.state = stateRunning
order := slices.Clone(r.order)
r.mu.Unlock()
var errs []error
for _, name := range order {
c := r.curators[name]
err := startSafely(ctx, c)
r.mu.Lock()
if err != nil {
r.status[name] = curatorStatus{startErr: err}
errs = append(errs, fmt.Errorf("curator %s: %w", name, err))
} else {
r.status[name] = curatorStatus{started: true}
}
r.mu.Unlock()
}
return errors.Join(errs...)
}
func startSafely(ctx context.Context, c CuratorEngine) (err error) {
defer func() {
if p := recover(); p != nil {
err = fmt.Errorf("start panic: %v", p)
}
}()
return c.Start(ctx)
}
// Health reports every registered curator's health. A curator whose Start
// failed is reported unhealthy with the failure; otherwise the curator's own
// Health is used. A panicking Health is reported unhealthy, not propagated.
func (r *Registry) Health(ctx context.Context) map[string]Health {
r.mu.Lock()
defer r.mu.Unlock()
out := make(map[string]Health, len(r.curators))
for name, c := range r.curators {
if st, ok := r.status[name]; ok && st.startErr != nil {
out[name] = Health{Status: HealthUnhealthy, Message: st.startErr.Error()}
continue
}
out[name] = healthSafely(ctx, c)
}
return out
}
func healthSafely(ctx context.Context, c CuratorEngine) (h Health) {
defer func() {
if p := recover(); p != nil {
h = Health{Status: HealthUnhealthy, Message: fmt.Sprintf("health panic: %v", p)}
}
}()
return c.Health(ctx)
}
// Stop stops every started curator in reverse registration order. Curators
// whose Start failed are skipped; the call is bounded by ctx — a curator
// that ignores cancellation cannot hang the daemon's shutdown beyond the
// caller's deadline, and its error is joined into the result. Stopping a
// registry that never started is a no-op.
func (r *Registry) Stop(ctx context.Context) error {
r.mu.Lock()
if r.state == stateIdle || r.state == stateStopped {
r.mu.Unlock()
return nil
}
r.state = stateStopped
order := slices.Clone(r.order)
r.mu.Unlock()
var errs []error
for i := len(order) - 1; i >= 0; i-- {
name := order[i]
r.mu.Lock()
st, ok := r.status[name]
r.mu.Unlock()
if !ok || !st.started {
continue
}
c := r.curators[name]
if err := stopSafely(ctx, c); err != nil {
errs = append(errs, fmt.Errorf("curator %s: %w", name, err))
}
}
return errors.Join(errs...)
}
func stopSafely(ctx context.Context, c CuratorEngine) (err error) {
defer func() {
if p := recover(); p != nil {
err = fmt.Errorf("stop panic: %v", p)
}
}()
return c.Stop(ctx)
}
func isNilEngine(c CuratorEngine) bool {
v := reflect.ValueOf(c)
switch v.Kind() {
case reflect.Invalid:
return true
case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Pointer, reflect.Slice:
return v.IsNil()
}
return false
}
+577
View File
@@ -0,0 +1,577 @@
package curator
import (
"context"
"errors"
"slices"
"sync"
"sync/atomic"
"testing"
"time"
"github.com/samcharles93/archie-core/internal/tools"
)
// --- host-service fakes -----------------------------------------------------
type testLLM struct{ calls int }
func (l *testLLM) Chat(_ context.Context, _ ChatRequest) (ChatResult, error) {
l.calls++
return ChatResult{Text: "ok"}, nil
}
type testBuilder struct{ built [][]string }
func (b *testBuilder) Build(_ context.Context, declared []string) ([]tools.ToolEntry, error) {
b.built = append(b.built, declared)
return nil, nil
}
type testStore struct{}
func (testStore) List(context.Context) ([]SkillRef, error) { return nil, nil }
func (testStore) Read(context.Context, string) (Skill, error) { return Skill{}, nil }
func (testStore) Write(context.Context, Skill) error { return nil }
func (testStore) Delete(context.Context, string) error { return nil }
type testSink struct {
mu sync.Mutex
kinds []string
}
func (s *testSink) Emit(kind, _ string, _ map[string]any) {
s.mu.Lock()
defer s.mu.Unlock()
s.kinds = append(s.kinds, kind)
}
func (s *testSink) kindsOf() []string {
s.mu.Lock()
defer s.mu.Unlock()
return slices.Clone(s.kinds)
}
func (s *testSink) count(kind string) int {
n := 0
for _, k := range s.kindsOf() {
if k == kind {
n++
}
}
return n
}
type testClock struct{ now time.Time }
func (c testClock) Now() time.Time { return c.now }
func (c testClock) After(d time.Duration) <-chan time.Time {
return time.After(d)
}
// --- fake curator ------------------------------------------------------------
type fakeCurator struct {
name string
manifest Manifest
events []string
recorder *[]string // shared lifecycle log; nil means record to events
startErr error
stopErr error
stopBlock chan struct{}
bindPanic bool
view Registrar
// pass/check control (runtime tests).
checkResult bool
checkErr error
checkPanic bool
checkCalls atomic.Int32
passResult PassResult
passErr error
passPanic bool
passBlock chan struct{} // if set, Pass blocks until closed or ctx done
passIgnoreCtx bool // if true, Pass ignores ctx while blocked
passCalls atomic.Int32
inputMu sync.Mutex
inputs []PassInput
}
func newFake(name string, manifest Manifest) *fakeCurator {
return &fakeCurator{name: name, manifest: manifest}
}
func (f *fakeCurator) record(e string) {
if f.recorder != nil {
*f.recorder = append(*f.recorder, e)
} else {
f.events = append(f.events, e)
}
}
func (f *fakeCurator) Name() string { return f.name }
func (f *fakeCurator) Version() string { return "test" }
func (f *fakeCurator) Manifest() Manifest { return f.manifest }
func (f *fakeCurator) Bind(host Registrar) {
f.view = host
f.record("bind:" + f.name)
if f.bindPanic {
panic("bind boom")
}
}
func (f *fakeCurator) Check(context.Context) (bool, error) {
f.checkCalls.Add(1)
if f.checkPanic {
panic("check boom")
}
if f.checkErr != nil {
return false, f.checkErr
}
return f.checkResult, nil
}
func (f *fakeCurator) Pass(ctx context.Context, in PassInput) (PassResult, error) {
f.passCalls.Add(1)
f.inputMu.Lock()
f.inputs = append(f.inputs, in)
f.inputMu.Unlock()
if f.passPanic {
panic("pass boom")
}
if f.passBlock != nil {
if f.passIgnoreCtx {
<-f.passBlock
} else {
select {
case <-f.passBlock:
case <-ctx.Done():
return PassResult{}, ctx.Err()
}
}
}
if f.passErr != nil {
return PassResult{}, f.passErr
}
return f.passResult, nil
}
func (f *fakeCurator) Start(context.Context) error {
if f.startErr != nil {
return f.startErr
}
f.record("start:" + f.name)
return nil
}
func (f *fakeCurator) Health(context.Context) Health { return Health{Status: HealthHealthy} }
func (f *fakeCurator) Stop(ctx context.Context) error {
if f.stopBlock != nil {
select {
case <-f.stopBlock:
case <-ctx.Done():
return ctx.Err()
}
}
if f.stopErr != nil {
return f.stopErr
}
f.record("stop:" + f.name)
return nil
}
// --- registry behavior -------------------------------------------------------
func TestRegistryRegisterAndDiscover(t *testing.T) {
t.Parallel()
r := NewRegistry(Registrar{})
a := newFake("a", Manifest{Interval: time.Hour})
b := newFake("b", Manifest{Interval: time.Hour})
if err := r.Register(a); err != nil {
t.Fatalf("Register(a) = %v, want nil", err)
}
if err := r.Register(b); err != nil {
t.Fatalf("Register(b) = %v, want nil", err)
}
got, ok := r.Get("a")
if !ok || got != a {
t.Fatalf("Get(a) = (%v, %v), want (a, true)", got, ok)
}
if _, ok := r.Get("missing"); ok {
t.Fatal("Get(missing) = true, want false")
}
if got := r.Names(); len(got) != 2 || got[0] != "a" || got[1] != "b" {
t.Fatalf("Names() = %v, want [a b]", got)
}
}
func TestRegistryRegisterDuplicateRejected(t *testing.T) {
t.Parallel()
r := NewRegistry(Registrar{})
a := newFake("a", Manifest{Interval: time.Hour})
if err := r.Register(a); err != nil {
t.Fatalf("Register(a) = %v, want nil", err)
}
err := r.Register(newFake("a", Manifest{Interval: time.Hour}))
if !errors.Is(err, ErrDuplicate) {
t.Fatalf("Register(dup) = %v, want ErrDuplicate", err)
}
if got := r.Names(); len(got) != 1 {
t.Fatalf("Names() = %v, want only the first registration", got)
}
}
func TestRegistryRegisterNilEngineRejected(t *testing.T) {
t.Parallel()
r := NewRegistry(Registrar{})
if err := r.Register(nil); err == nil {
t.Fatal("Register(nil) = nil, want error")
}
}
func TestRegistryRegisterTypedNilEngineRejected(t *testing.T) {
t.Parallel()
r := NewRegistry(Registrar{})
var c *fakeCurator
if err := r.Register(c); err == nil {
t.Fatal("Register(typed nil) = nil, want error")
}
}
func TestRegistryRegisterInvalidManifestRejected(t *testing.T) {
t.Parallel()
r := NewRegistry(Registrar{})
if err := r.Register(newFake("bad", Manifest{})); err == nil {
t.Fatal("Register(zero interval) = nil, want error")
}
if got := r.Names(); len(got) != 0 {
t.Fatalf("Names() = %v, want empty after rejected registration", got)
}
}
func TestRegistryRegisterAfterStartRejected(t *testing.T) {
t.Parallel()
r := NewRegistry(Registrar{})
if err := r.Register(newFake("a", Manifest{Interval: time.Hour})); err != nil {
t.Fatalf("Register(a) = %v, want nil", err)
}
if err := r.Start(context.Background()); err != nil {
t.Fatalf("Start() = %v, want nil", err)
}
err := r.Register(newFake("b", Manifest{Interval: time.Hour}))
if !errors.Is(err, ErrStarted) {
t.Fatalf("Register after Start = %v, want ErrStarted", err)
}
}
func TestRegistryDeclaredCapabilitiesRequireHostServices(t *testing.T) {
t.Parallel()
tests := []struct {
name string
host Registrar
manifest Manifest
wantErr bool
}{
{
name: "tools declared, no builder",
host: Registrar{},
manifest: Manifest{Interval: time.Hour, Tools: []string{"skills.list"}},
wantErr: true,
},
{
name: "tools declared, builder present",
host: Registrar{Tools: &testBuilder{}},
manifest: Manifest{Interval: time.Hour, Tools: []string{"skills.list"}},
},
{
name: "skills declared, no store",
host: Registrar{},
manifest: Manifest{Interval: time.Hour, Skills: true},
wantErr: true,
},
{
name: "skills declared, store present",
host: Registrar{Skills: testStore{}},
manifest: Manifest{Interval: time.Hour, Skills: true},
},
{
name: "nothing declared, empty host",
host: Registrar{},
manifest: Manifest{Interval: time.Hour},
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
t.Parallel()
r := NewRegistry(tt.host)
err := r.Register(newFake("c", tt.manifest))
if (err != nil) != tt.wantErr {
t.Fatalf("Register() = %v, wantErr %v", err, tt.wantErr)
}
})
}
}
func TestRegistryBindFiltersToDeclaredCapabilities(t *testing.T) {
t.Parallel()
host := Registrar{
Model: "provider/default",
LLM: &testLLM{},
Tools: &testBuilder{},
Skills: testStore{},
Events: &testSink{},
Clock: testClock{now: time.Unix(0, 0)},
}
// A curator declaring nothing agentic receives no model access and no
// capability services, but always receives events and time.
r := NewRegistry(host)
plain := newFake("plain", Manifest{Interval: time.Hour})
if err := r.Register(plain); err != nil {
t.Fatalf("Register(plain) = %v, want nil", err)
}
if plain.view.LLM != nil {
t.Error("view.LLM = non-nil for a curator declaring no agentic capability")
}
if plain.view.Tools != nil {
t.Error("view.Tools = non-nil for a curator declaring no tools")
}
if plain.view.Skills != nil {
t.Error("view.Skills = non-nil for a curator not declaring skills")
}
if plain.view.Events == nil {
t.Error("view.Events = nil; activity must always be attributable")
}
if plain.view.Clock == nil {
t.Error("view.Clock = nil; time is always available")
}
// A curator declaring tools and skills receives exactly those, plus the
// model access an agentic pass needs.
toolsy := newFake("toolsy", Manifest{Interval: time.Hour, Tools: []string{"skills.list"}, Skills: true})
if err := r.Register(toolsy); err != nil {
t.Fatalf("Register(toolsy) = %v, want nil", err)
}
if toolsy.view.LLM == nil {
t.Error("view.LLM = nil for a curator declaring agentic capabilities")
}
if toolsy.view.Tools == nil {
t.Error("view.Tools = nil for a curator declaring tools")
}
if toolsy.view.Skills == nil {
t.Error("view.Skills = nil for a curator declaring skills")
}
// A curator declaring only a memory engine still needs model access to
// reason over memory.
mem := newFake("mem", Manifest{Interval: time.Hour, MemoryEngine: "builtin"})
if err := r.Register(mem); err != nil {
t.Fatalf("Register(mem) = %v, want nil", err)
}
if mem.view.LLM == nil {
t.Error("view.LLM = nil for a curator declaring a memory engine")
}
if mem.view.Tools != nil {
t.Error("view.Tools = non-nil for a curator declaring no tools")
}
}
func TestRegistryBindPanicIsolated(t *testing.T) {
t.Parallel()
r := NewRegistry(Registrar{})
panicky := newFake("panicky", Manifest{Interval: time.Hour})
panicky.bindPanic = true
if err := r.Register(panicky); err == nil {
t.Fatal("Register(panicking Bind) = nil, want error")
}
if got := r.Names(); len(got) != 0 {
t.Fatalf("Names() = %v, want empty after a panicking Bind", got)
}
// The registry survives and still accepts healthy curators.
if err := r.Register(newFake("ok", Manifest{Interval: time.Hour})); err != nil {
t.Fatalf("Register(ok) after panicking Bind = %v, want nil", err)
}
}
func TestRegistryStartStopOrdering(t *testing.T) {
t.Parallel()
r := NewRegistry(Registrar{})
var log []string
a := newFake("a", Manifest{Interval: time.Hour})
a.recorder = &log
b := newFake("b", Manifest{Interval: time.Hour})
b.recorder = &log
c := newFake("c", Manifest{Interval: time.Hour})
c.recorder = &log
for _, cur := range []*fakeCurator{a, b, c} {
if err := r.Register(cur); err != nil {
t.Fatalf("Register(%s) = %v, want nil", cur.name, err)
}
}
if err := r.Start(context.Background()); err != nil {
t.Fatalf("Start() = %v, want nil", err)
}
if err := r.Stop(context.Background()); err != nil {
t.Fatalf("Stop() = %v, want nil", err)
}
want := []string{
"bind:a", "bind:b", "bind:c",
"start:a", "start:b", "start:c",
"stop:c", "stop:b", "stop:a",
}
if got := log; !equalStrings(got, want) {
t.Fatalf("lifecycle events = %v, want %v (start in registration order, stop reversed)", got, want)
}
}
func TestRegistryStartIsolatesFailure(t *testing.T) {
t.Parallel()
r := NewRegistry(Registrar{})
var log []string
a := newFake("a", Manifest{Interval: time.Hour})
a.recorder = &log
bad := newFake("bad", Manifest{Interval: time.Hour})
bad.recorder = &log
bad.startErr = errBoom
c := newFake("c", Manifest{Interval: time.Hour})
c.recorder = &log
for _, cur := range []*fakeCurator{a, bad, c} {
if err := r.Register(cur); err != nil {
t.Fatalf("Register(%s) = %v, want nil", cur.name, err)
return
}
}
err := r.Start(context.Background())
if !errors.Is(err, errBoom) {
t.Fatalf("Start() error = %v, want the failing curator's error", err)
}
// The healthy curators started; the failing one never became started.
if !logHas(log, "start:a") || !logHas(log, "start:c") {
t.Fatalf("healthy curators did not start: %v", log)
}
if logHas(log, "start:bad") {
t.Fatalf("failing curator started despite Start error: %v", log)
}
health := r.Health(context.Background())
if health["bad"].Status != HealthUnhealthy {
t.Fatalf("Health(bad).Status = %v, want unhealthy", health["bad"].Status)
}
if health["a"].Status != HealthHealthy {
t.Fatalf("Health(a).Status = %v, want healthy", health["a"].Status)
}
// Stop skips the curator that never started and stops the rest in
// reverse registration order.
if err := r.Stop(context.Background()); err != nil {
t.Fatalf("Stop() = %v, want nil", err)
}
want := []string{"bind:a", "bind:bad", "bind:c", "start:a", "start:c", "stop:c", "stop:a"}
if got := log; !equalStrings(got, want) {
t.Fatalf("lifecycle events = %v, want %v", got, want)
}
}
func TestRegistryStopBoundedByContext(t *testing.T) {
t.Parallel()
r := NewRegistry(Registrar{})
blocked := newFake("blocked", Manifest{Interval: time.Hour})
blocked.stopBlock = make(chan struct{})
if err := r.Register(blocked); err != nil {
t.Fatalf("Register(blocked) = %v, want nil", err)
}
if err := r.Start(context.Background()); err != nil {
t.Fatalf("Start() = %v, want nil", err)
}
ctx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond)
defer cancel()
start := time.Now()
err := r.Stop(ctx)
elapsed := time.Since(start)
if !errors.Is(err, context.DeadlineExceeded) {
t.Fatalf("Stop() error = %v, want context.DeadlineExceeded", err)
}
if elapsed > 2*time.Second {
t.Fatalf("Stop() took %v; a blocking curator must not hang shutdown", elapsed)
}
}
func TestRegistryStopBeforeStartIsNoop(t *testing.T) {
t.Parallel()
r := NewRegistry(Registrar{})
if err := r.Register(newFake("a", Manifest{Interval: time.Hour})); err != nil {
t.Fatalf("Register(a) = %v, want nil", err)
}
if err := r.Stop(context.Background()); err != nil {
t.Fatalf("Stop() before Start = %v, want nil no-op", err)
}
}
func TestRegistryStartTwiceRejected(t *testing.T) {
t.Parallel()
r := NewRegistry(Registrar{})
if err := r.Start(context.Background()); err != nil {
t.Fatalf("Start() = %v, want nil", err)
}
if err := r.Start(context.Background()); !errors.Is(err, ErrStarted) {
t.Fatalf("second Start() = %v, want ErrStarted", err)
}
}
func TestRegistryHealthReportsEveryCurator(t *testing.T) {
t.Parallel()
r := NewRegistry(Registrar{})
if err := r.Register(newFake("a", Manifest{Interval: time.Hour})); err != nil {
t.Fatalf("Register(a) = %v, want nil", err)
}
health := r.Health(context.Background())
if len(health) != 1 || health["a"].Status != HealthHealthy {
t.Fatalf("Health() = %v, want one healthy entry for a", health)
}
}
// --- helpers -----------------------------------------------------------------
var errBoom = errors.New("boom")
func equalStrings(a, b []string) bool {
if len(a) != len(b) {
return false
}
for i := range a {
if a[i] != b[i] {
return false
}
}
return true
}
func logHas(log []string, want string) bool {
return slices.Contains(log, want)
}
+311
View File
@@ -0,0 +1,311 @@
package curator
import (
"context"
"errors"
"fmt"
"sync"
"time"
"github.com/samcharles93/archie-core/internal/events"
)
const (
defaultPassTimeout = 10 * time.Minute
defaultWakeBuffer = 64
// minPassGap is the minimum time between the end of one pass and the
// start of the next. It exists so a curator that suggests a past or
// immediate NextCheckIn cannot hot-spin the loop; nudges still wake a
// loop early, so pending input is never delayed by it.
minPassGap = time.Second
)
// RuntimeConfig tunes the curator runtime. All fields are optional; zero
// values use the documented defaults.
type RuntimeConfig struct {
// PassTimeout bounds a single pass via context deadline. Zero uses
// defaultPassTimeout (10m).
PassTimeout time.Duration
// MaxConcurrentPasses caps simultaneous passes across all curators.
// Zero uses 1: passes serialize behind a shared slot so a pass burst
// can never saturate the model runtime against chat turns.
MaxConcurrentPasses int
}
// Runtime runs the registered curators' loops: one goroutine per curator,
// timing driven by the registry's clock (fake-clock testable), waking on
// best-effort nudges (the trigger decision belongs to the curator's Check),
// with per-pass timeouts, panic recovery, and bounded shutdown.
//
// Curators are peers, never dependencies: nothing a curator does — a
// blocking pass, a panic, a burst of nudges — can block a chat turn, an
// agent run, or the daemon. Wake events are accelerations; the trigger is a
// deterministic state read at pass time (archie-core-035), so a dropped
// nudge only delays a run to the next check-in.
type Runtime struct {
registry *Registry
cfg RuntimeConfig
mu sync.Mutex
started bool
cancel context.CancelFunc
wg sync.WaitGroup
nudges map[string]chan struct{}
sem chan struct{}
}
// NewRuntime builds a runtime over the registry. The runtime shares the
// registry's clock (so loop timing is fake-clock testable) and event sink
// (so every run and action stays attributable).
func NewRuntime(registry *Registry, cfg RuntimeConfig) *Runtime {
if cfg.PassTimeout <= 0 {
cfg.PassTimeout = defaultPassTimeout
}
if cfg.MaxConcurrentPasses <= 0 {
cfg.MaxConcurrentPasses = 1
}
return &Runtime{
registry: registry,
cfg: cfg,
nudges: make(map[string]chan struct{}),
sem: make(chan struct{}, cfg.MaxConcurrentPasses),
}
}
// Start launches one loop per registered curator and starts the curators'
// lifecycle. A curator whose Start fails is skipped by the registry and
// reported in the joined error; every other curator still runs. Starting an
// already-started runtime is an error.
func (rt *Runtime) Start(ctx context.Context) error {
rt.mu.Lock()
if rt.started {
rt.mu.Unlock()
return errors.New("curator runtime already started")
}
rt.started = true
loopCtx, cancel := context.WithCancel(ctx)
rt.cancel = cancel
for _, name := range rt.registry.Names() {
c, _ := rt.registry.Get(name)
if c.Manifest().OnInput {
rt.nudges[name] = make(chan struct{}, defaultWakeBuffer)
}
}
rt.mu.Unlock()
startErr := rt.registry.Start(ctx)
for _, name := range rt.registry.Names() {
c, _ := rt.registry.Get(name)
rt.wg.Add(1)
go rt.runLoop(loopCtx, name, c)
}
return startErr
}
// Nudge is a best-effort wake: input-driven curators check their trigger
// early instead of waiting for the next interval. A full channel or an
// unknown name drops the nudge — waking is an acceleration, never the
// source of truth. An empty curator name nudges every input-driven curator.
func (rt *Runtime) Nudge(curator string) {
rt.mu.Lock()
defer rt.mu.Unlock()
for name, ch := range rt.nudges {
if curator != "" && curator != name {
continue
}
select {
case ch <- struct{}{}:
default:
}
}
}
// Stop cancels every loop, waits for in-flight passes to unwind (bounded by
// ctx), then stops the curators' lifecycle in reverse registration order.
// A pass that ignores cancellation cannot hang shutdown beyond ctx: Stop
// returns ctx.Err once the deadline passes. Stopping a runtime that never
// started is a no-op.
func (rt *Runtime) Stop(ctx context.Context) error {
rt.mu.Lock()
if !rt.started {
rt.mu.Unlock()
return nil
}
rt.started = false
cancel := rt.cancel
rt.cancel = nil
rt.mu.Unlock()
cancel()
done := make(chan struct{})
go func() {
rt.wg.Wait()
close(done)
}()
select {
case <-done:
case <-ctx.Done():
return fmt.Errorf("curator runtime shutdown: %w", ctx.Err())
}
return rt.registry.Stop(ctx)
}
// runLoop is one curator's lifetime: sleep until eligible or nudged, ask
// Check whether input is pending, run a bounded pass when it is, and back
// off to the cooldown after an idle or failed pass. Panics in Check and
// Pass are recovered here; the loop survives them.
func (rt *Runtime) runLoop(ctx context.Context, name string, c CuratorEngine) {
defer rt.wg.Done()
m := c.Manifest()
cooldown := m.Cooldown
if cooldown <= 0 {
cooldown = 2 * m.Interval
}
clock := rt.registry.Host().Clock
wakeCh := rt.nudges[name] // nil for non-input curators: the case never fires
var next time.Time // zero means immediately eligible
var lastPass time.Time
for {
now := clock.Now()
reason := "check-in"
if !next.IsZero() && now.Before(next) {
woke, done := waitNext(ctx, wakeCh, clock.After(next.Sub(now)))
if done {
return
}
if woke {
reason = "wake"
}
}
due, err := rt.safeCheck(ctx, c)
if err != nil {
rt.fail(name, "check", err)
next = clock.Now().Add(cooldown)
continue
}
if !due {
next = clock.Now().Add(m.Interval)
continue
}
if !rt.acquire(ctx) {
return // shutting down while waiting for a pass slot
}
passCtx, cancel := context.WithTimeout(ctx, rt.cfg.PassTimeout)
result, perr := rt.safePass(passCtx, c, PassInput{Reason: reason, LastPass: lastPass})
cancel()
rt.release()
now = clock.Now()
lastPass = now
if perr != nil {
rt.fail(name, "pass", perr)
next = now.Add(cooldown)
} else {
next = scheduleNext(now, m, cooldown, result)
rt.emitRun(name, now, result)
}
}
}
// waitNext blocks until a nudge, the sleep timer, or shutdown. woke means
// a nudge fired — re-check the trigger now; done means the context was
// cancelled — exit the loop.
func waitNext(ctx context.Context, wakeCh <-chan struct{}, timer <-chan time.Time) (woke, done bool) {
select {
case <-ctx.Done():
return false, true
case <-wakeCh:
return true, false
case <-timer:
return false, false
}
}
// scheduleNext computes the next eligible time after a successful pass. A
// curator-suggested NextCheckIn in the past (or immediate) would hot-spin
// the loop, so it is clamped to the minimum pass gap; an idle pass (no
// actions) backs off to the cooldown.
func scheduleNext(now time.Time, m Manifest, cooldown time.Duration, result PassResult) time.Time {
switch {
case !result.NextCheckIn.IsZero():
next := result.NextCheckIn
if earliest := now.Add(minPassGap); next.Before(earliest) {
next = earliest
}
return next
case len(result.Actions) == 0:
return now.Add(cooldown)
default:
return now.Add(m.Interval)
}
}
func (rt *Runtime) acquire(ctx context.Context) bool {
select {
case rt.sem <- struct{}{}:
return true
case <-ctx.Done():
return false
}
}
func (rt *Runtime) release() { <-rt.sem }
func (rt *Runtime) safeCheck(ctx context.Context, c CuratorEngine) (due bool, err error) {
defer func() {
if p := recover(); p != nil {
err = fmt.Errorf("check panic: %v", p)
}
}()
return c.Check(ctx)
}
func (rt *Runtime) safePass(ctx context.Context, c CuratorEngine, in PassInput) (result PassResult, err error) {
defer func() {
if p := recover(); p != nil {
err = fmt.Errorf("pass panic: %v", p)
}
}()
return c.Pass(ctx, in)
}
// fail records a Check/Pass failure on the event stream. The event bus is
// non-blocking by contract (bounded dropping buffers), so even a failing
// curator cannot backpressure anything.
func (rt *Runtime) fail(name, phase string, err error) {
if sink := rt.registry.Host().Events; sink != nil {
sink.Emit(events.KindCuratorError, name, map[string]any{
"curator": name,
"phase": phase,
"err": err.Error(),
})
}
}
// emitRun publishes one run summary plus one event per action, so what ran,
// when, what it changed, and why all stay attributable (archie-core-114).
func (rt *Runtime) emitRun(name string, at time.Time, result PassResult) {
sink := rt.registry.Host().Events
if sink == nil {
return
}
sink.Emit(events.KindCuratorRun, name, map[string]any{
"curator": name,
"actions": len(result.Actions),
"at": at,
})
for _, a := range result.Actions {
sink.Emit(events.KindCuratorAction, name, map[string]any{
"curator": name,
"type": a.Type,
"detail": a.Detail,
"reason": a.Reason,
"at": a.At,
})
}
}
+455
View File
@@ -0,0 +1,455 @@
package curator
import (
"context"
"errors"
"slices"
"sync"
"testing"
"time"
"github.com/samcharles93/archie-core/internal/events"
)
// --- fake clock ---------------------------------------------------------------
// fakeClock is the runtime's injectable clock: Now plus clock-driven timers
// that fire when Advance moves past their deadline. Loop timing is tested
// with this, never wall-clock sleeps.
type fakeClock struct {
mu sync.Mutex
now time.Time
timers []*fakeTimer
}
type fakeTimer struct {
c chan time.Time
at time.Time
}
func newFakeClock(start time.Time) *fakeClock { return &fakeClock{now: start} }
func (fc *fakeClock) Now() time.Time {
fc.mu.Lock()
defer fc.mu.Unlock()
return fc.now
}
func (fc *fakeClock) After(d time.Duration) <-chan time.Time {
fc.mu.Lock()
defer fc.mu.Unlock()
t := &fakeTimer{c: make(chan time.Time, 1), at: fc.now.Add(d)}
fc.timers = append(fc.timers, t)
return t.c
}
// Advance moves the clock forward and fires every timer whose deadline has
// passed, returning how many fired.
func (fc *fakeClock) Advance(d time.Duration) int {
fc.mu.Lock()
fc.now = fc.now.Add(d)
var fired []*fakeTimer
remain := fc.timers[:0]
for _, t := range fc.timers {
if !t.at.After(fc.now) {
fired = append(fired, t)
} else {
remain = append(remain, t)
}
}
fc.timers = remain
fc.mu.Unlock()
for _, t := range fired {
select {
case t.c <- t.at:
default:
}
}
return len(fired)
}
// --- helpers ------------------------------------------------------------------
func waitFor(t *testing.T, timeout time.Duration, what string, cond func() bool) {
t.Helper()
deadline := time.Now().Add(timeout)
for time.Now().Before(deadline) {
if cond() {
return
}
time.Sleep(time.Millisecond)
}
t.Fatalf("timed out waiting for %s", what)
}
func newRuntimeTestEnv(t *testing.T, clock Clock, cfg RuntimeConfig, curators ...*fakeCurator) (*Registry, *Runtime, *testSink) {
t.Helper()
sink := &testSink{}
reg := NewRegistry(Registrar{Clock: clock, Events: sink})
for _, c := range curators {
if err := reg.Register(c); err != nil {
t.Fatalf("Register(%s) = %v, want nil", c.name, err)
}
}
return reg, NewRuntime(reg, cfg), sink
}
const testInterval = 10 * time.Minute
// --- loop behavior -------------------------------------------------------------
func TestRuntimeWakeRunsPendingPassImmediately(t *testing.T) {
t.Parallel()
clock := newFakeClock(time.Unix(0, 0))
c := newFake("c", Manifest{Interval: testInterval, OnInput: true})
c.checkResult = true
c.passResult = PassResult{Actions: []Action{{Type: "test", Reason: "r"}}}
_, rt, _ := newRuntimeTestEnv(t, clock, RuntimeConfig{}, c)
if err := rt.Start(context.Background()); err != nil {
t.Fatalf("Start() = %v, want nil", err)
}
t.Cleanup(func() { _ = rt.Stop(context.Background()) })
// Pending input at start: the first pass runs without any clock advance.
waitFor(t, 2*time.Second, "first pass", func() bool { return c.passCalls.Load() == 1 })
// A nudge before the next interval wakes the curator early: a second
// pass runs without advancing the clock past the interval.
rt.Nudge("c")
waitFor(t, 2*time.Second, "pass on nudge", func() bool { return c.passCalls.Load() == 2 })
if got := clock.Now(); got.After(time.Unix(0, 0).Add(testInterval)) {
t.Fatalf("clock advanced to %v; wake must not wait for the interval", got)
}
}
func TestRuntimeIdleCuratorSleepsUntilInterval(t *testing.T) {
t.Parallel()
clock := newFakeClock(time.Unix(0, 0))
c := newFake("c", Manifest{Interval: testInterval})
c.checkResult = false // nothing pending
_, rt, _ := newRuntimeTestEnv(t, clock, RuntimeConfig{}, c)
if err := rt.Start(context.Background()); err != nil {
t.Fatalf("Start() = %v, want nil", err)
}
t.Cleanup(func() { _ = rt.Stop(context.Background()) })
// Initial check only; nothing due before the interval.
waitFor(t, 2*time.Second, "initial check", func() bool { return c.checkCalls.Load() >= 1 })
if c.passCalls.Load() != 0 {
t.Fatalf("passCalls = %d, want 0 while idle", c.passCalls.Load())
}
clock.Advance(testInterval - time.Second)
time.Sleep(50 * time.Millisecond)
if got := c.checkCalls.Load(); got != 1 {
t.Fatalf("checkCalls = %d after %v, want 1 (idle curator must not wake early)", got, testInterval-time.Second)
}
clock.Advance(time.Second)
waitFor(t, 2*time.Second, "check at interval", func() bool { return c.checkCalls.Load() >= 2 })
if c.passCalls.Load() != 0 {
t.Fatalf("passCalls = %d, want 0 (Check said nothing pending)", c.passCalls.Load())
}
}
func TestRuntimeCooldownAfterIdlePass(t *testing.T) {
t.Parallel()
clock := newFakeClock(time.Unix(0, 0))
c := newFake("c", Manifest{Interval: testInterval, Cooldown: 30 * time.Minute})
c.checkResult = true
c.passResult = PassResult{} // no actions: the pass was idle
_, rt, _ := newRuntimeTestEnv(t, clock, RuntimeConfig{}, c)
if err := rt.Start(context.Background()); err != nil {
t.Fatalf("Start() = %v, want nil", err)
}
t.Cleanup(func() { _ = rt.Stop(context.Background()) })
waitFor(t, 2*time.Second, "idle pass", func() bool { return c.passCalls.Load() == 1 })
// The cooldown (30m) outranks the interval (10m): nothing runs at
// +10m...
clock.Advance(testInterval)
time.Sleep(50 * time.Millisecond)
if got := c.checkCalls.Load(); got != 1 {
t.Fatalf("checkCalls = %d at +interval, want 1 (cooldown must apply after an idle pass)", got)
}
// ...and the next pass runs at +30m.
clock.Advance(20 * time.Minute)
waitFor(t, 2*time.Second, "pass after cooldown", func() bool { return c.passCalls.Load() == 2 })
}
func TestRuntimeNextCheckInOverride(t *testing.T) {
t.Parallel()
clock := newFakeClock(time.Unix(0, 0))
c := newFake("c", Manifest{Interval: testInterval})
c.checkResult = true
c.passResult = PassResult{NextCheckIn: time.Unix(0, 0).Add(5 * time.Minute)}
_, rt, _ := newRuntimeTestEnv(t, clock, RuntimeConfig{}, c)
if err := rt.Start(context.Background()); err != nil {
t.Fatalf("Start() = %v, want nil", err)
}
t.Cleanup(func() { _ = rt.Stop(context.Background()) })
waitFor(t, 2*time.Second, "first pass", func() bool { return c.passCalls.Load() == 1 })
// The pass suggested +5m; neither the 10m interval nor anything else
// fires before it.
clock.Advance(4 * time.Minute)
time.Sleep(50 * time.Millisecond)
if got := c.checkCalls.Load(); got != 1 {
t.Fatalf("checkCalls = %d before NextCheckIn, want 1", got)
}
clock.Advance(time.Minute)
waitFor(t, 2*time.Second, "pass at NextCheckIn", func() bool { return c.passCalls.Load() == 2 })
// The second pass suggests the same absolute time, now in the past.
// The runtime clamps it to the minimum gap instead of hot-spinning.
clock.Advance(500 * time.Millisecond)
time.Sleep(50 * time.Millisecond)
if got := c.passCalls.Load(); got != 2 {
t.Fatalf("passCalls = %d before the clamp gap elapses, want 2 (past NextCheckIn must not hot-spin)", got)
}
clock.Advance(500 * time.Millisecond)
waitFor(t, 2*time.Second, "pass after clamp gap", func() bool { return c.passCalls.Load() == 3 })
if got := c.checkCalls.Load(); got > 10 {
t.Fatalf("checkCalls = %d; a clamped NextCheckIn must not produce a check burst", got)
}
}
func TestRuntimeNudgeIgnoredForNonInputCurator(t *testing.T) {
t.Parallel()
clock := newFakeClock(time.Unix(0, 0))
c := newFake("c", Manifest{Interval: testInterval}) // OnInput false
c.checkResult = true
_, rt, _ := newRuntimeTestEnv(t, clock, RuntimeConfig{}, c)
if err := rt.Start(context.Background()); err != nil {
t.Fatalf("Start() = %v, want nil", err)
}
t.Cleanup(func() { _ = rt.Stop(context.Background()) })
waitFor(t, 2*time.Second, "first pass", func() bool { return c.passCalls.Load() == 1 })
rt.Nudge("c")
time.Sleep(50 * time.Millisecond)
if got := c.passCalls.Load(); got != 1 {
t.Fatalf("passCalls = %d after nudge, want 1 (non-input curator ignores nudges)", got)
}
// A nudge for an unknown curator is dropped without panicking.
rt.Nudge("missing")
}
func TestRuntimePassPanicRecovered(t *testing.T) {
t.Parallel()
clock := newFakeClock(time.Unix(0, 0))
c := newFake("c", Manifest{Interval: testInterval, Cooldown: 5 * time.Minute})
c.checkResult = true
c.passPanic = true
_, rt, sink := newRuntimeTestEnv(t, clock, RuntimeConfig{}, c)
if err := rt.Start(context.Background()); err != nil {
t.Fatalf("Start() = %v, want nil", err)
}
t.Cleanup(func() { _ = rt.Stop(context.Background()) })
waitFor(t, 2*time.Second, "panicking pass", func() bool { return c.passCalls.Load() == 1 })
waitFor(t, 2*time.Second, "error event", func() bool { return sink.count(events.KindCuratorError) >= 1 })
// The loop survives the panic: the next check-in still happens.
clock.Advance(5 * time.Minute)
waitFor(t, 2*time.Second, "pass after panic", func() bool { return c.passCalls.Load() == 2 })
}
func TestRuntimeCheckPanicRecovered(t *testing.T) {
t.Parallel()
clock := newFakeClock(time.Unix(0, 0))
c := newFake("c", Manifest{Interval: testInterval, Cooldown: 5 * time.Minute})
c.checkPanic = true
_, rt, sink := newRuntimeTestEnv(t, clock, RuntimeConfig{}, c)
if err := rt.Start(context.Background()); err != nil {
t.Fatalf("Start() = %v, want nil", err)
}
t.Cleanup(func() { _ = rt.Stop(context.Background()) })
waitFor(t, 2*time.Second, "error event", func() bool { return sink.count(events.KindCuratorError) >= 1 })
clock.Advance(5 * time.Minute)
waitFor(t, 2*time.Second, "check after panic", func() bool { return c.checkCalls.Load() >= 2 })
}
func TestRuntimeShutdownCancelsInFlightPass(t *testing.T) {
t.Parallel()
clock := newFakeClock(time.Unix(0, 0))
c := newFake("c", Manifest{Interval: testInterval})
c.checkResult = true
c.passBlock = make(chan struct{})
_, rt, _ := newRuntimeTestEnv(t, clock, RuntimeConfig{}, c)
if err := rt.Start(context.Background()); err != nil {
t.Fatalf("Start() = %v, want nil", err)
}
waitFor(t, 2*time.Second, "blocked pass", func() bool { return c.passCalls.Load() == 1 })
stopCtx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()
start := time.Now()
if err := rt.Stop(stopCtx); err != nil {
t.Fatalf("Stop() = %v, want nil (in-flight pass must be cancelled via context)", err)
}
if elapsed := time.Since(start); elapsed > 2*time.Second {
t.Fatalf("Stop() took %v; shutdown must be bounded", elapsed)
}
}
func TestRuntimeShutdownBoundedDespiteStuckPass(t *testing.T) {
t.Parallel()
clock := newFakeClock(time.Unix(0, 0))
c := newFake("c", Manifest{Interval: testInterval})
c.checkResult = true
c.passBlock = make(chan struct{})
c.passIgnoreCtx = true // violates the contract on purpose: Pass ignores ctx
_, rt, _ := newRuntimeTestEnv(t, clock, RuntimeConfig{}, c)
if err := rt.Start(context.Background()); err != nil {
t.Fatalf("Start() = %v, want nil", err)
}
waitFor(t, 2*time.Second, "stuck pass", func() bool { return c.passCalls.Load() == 1 })
t.Cleanup(func() { close(c.passBlock) }) // unstick the goroutine at test end
stopCtx, cancel := context.WithTimeout(context.Background(), 30*time.Millisecond)
defer cancel()
start := time.Now()
err := rt.Stop(stopCtx)
if !errors.Is(err, context.DeadlineExceeded) {
t.Fatalf("Stop() error = %v, want context.DeadlineExceeded", err)
}
if elapsed := time.Since(start); elapsed > 2*time.Second {
t.Fatalf("Stop() took %v; a stuck pass must not hang shutdown", elapsed)
}
}
func TestRuntimeMaxConcurrentPasses(t *testing.T) {
t.Parallel()
clock := newFakeClock(time.Unix(0, 0))
a := newFake("a", Manifest{Interval: testInterval, OnInput: true})
a.checkResult = true
a.passBlock = make(chan struct{})
b := newFake("b", Manifest{Interval: testInterval, OnInput: true})
b.checkResult = true
_, rt, _ := newRuntimeTestEnv(t, clock, RuntimeConfig{MaxConcurrentPasses: 1}, a, b)
if err := rt.Start(context.Background()); err != nil {
t.Fatalf("Start() = %v, want nil", err)
}
closed := false
t.Cleanup(func() {
if !closed {
close(a.passBlock)
}
_ = rt.Stop(context.Background())
})
// a holds the single pass slot, blocked.
waitFor(t, 2*time.Second, "a's blocked pass", func() bool { return a.passCalls.Load() == 1 })
// b is woken, but the slot is taken: b's pass count cannot advance
// past its initial run while a is in flight.
before := b.passCalls.Load()
for i := 0; i < 5; i++ {
rt.Nudge("b")
}
time.Sleep(100 * time.Millisecond)
if got := b.passCalls.Load(); got != before {
t.Fatalf("b.passCalls = %d while a is blocked (was %d); max concurrent passes = 1", got, before)
}
// a finishes; b's queued pass runs.
close(a.passBlock)
closed = true
waitFor(t, 2*time.Second, "b's pass after slot freed", func() bool {
return b.passCalls.Load() > before
})
}
func TestRuntimeEmitsRunAndActionEvents(t *testing.T) {
t.Parallel()
clock := newFakeClock(time.Unix(0, 0))
c := newFake("c", Manifest{Interval: testInterval})
c.checkResult = true
c.passResult = PassResult{Actions: []Action{
{Type: "skill.updated", Detail: "d1", Reason: "stale"},
{Type: "skill.pruned", Detail: "d2", Reason: "unused"},
}}
_, rt, sink := newRuntimeTestEnv(t, clock, RuntimeConfig{}, c)
if err := rt.Start(context.Background()); err != nil {
t.Fatalf("Start() = %v, want nil", err)
}
t.Cleanup(func() { _ = rt.Stop(context.Background()) })
waitFor(t, 2*time.Second, "run event", func() bool { return sink.count(events.KindCuratorRun) == 1 })
waitFor(t, 2*time.Second, "action events", func() bool { return sink.count(events.KindCuratorAction) == 2 })
}
func TestRuntimeLifecycleGuards(t *testing.T) {
t.Parallel()
clock := newFakeClock(time.Unix(0, 0))
_, rt, _ := newRuntimeTestEnv(t, clock, RuntimeConfig{})
if err := rt.Stop(context.Background()); err != nil {
t.Fatalf("Stop() before Start = %v, want nil no-op", err)
}
if err := rt.Start(context.Background()); err != nil {
t.Fatalf("Start() = %v, want nil", err)
}
t.Cleanup(func() { _ = rt.Stop(context.Background()) })
if err := rt.Start(context.Background()); err == nil {
t.Fatal("second Start() = nil, want error")
}
}
func TestRuntimePassInputRecordsReasonAndLastPass(t *testing.T) {
t.Parallel()
clock := newFakeClock(time.Unix(0, 0))
c := newFake("c", Manifest{Interval: testInterval, OnInput: true})
c.checkResult = true
_, rt, _ := newRuntimeTestEnv(t, clock, RuntimeConfig{}, c)
if err := rt.Start(context.Background()); err != nil {
t.Fatalf("Start() = %v, want nil", err)
}
t.Cleanup(func() { _ = rt.Stop(context.Background()) })
waitFor(t, 2*time.Second, "first pass", func() bool { return c.passCalls.Load() == 1 })
rt.Nudge("c")
waitFor(t, 2*time.Second, "nudged pass", func() bool { return c.passCalls.Load() == 2 })
c.inputMu.Lock()
inputs := slices.Clone(c.inputs)
c.inputMu.Unlock()
if len(inputs) != 2 {
t.Fatalf("pass inputs = %d, want 2", len(inputs))
}
if inputs[1].LastPass.IsZero() {
t.Error("second pass LastPass is zero; want the previous pass time")
}
}
+5
View File
@@ -17,6 +17,7 @@ import (
"github.com/samcharles93/archie-core/internal/agentexec"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/container"
"github.com/samcharles93/archie-core/internal/curator"
"github.com/samcharles93/archie-core/internal/domain/workintake"
"github.com/samcharles93/archie-core/internal/eventbus"
"github.com/samcharles93/archie-core/internal/events"
@@ -92,6 +93,10 @@ type Daemon struct {
// composition root (cmd/archied) to wfeval.Discover; nil disables
// discovery.
CustomStages func(dir string) ([]workflow.Stage, error)
// Curators is the curator engine family registry (epic archie-core-yp9).
// The runtime loop (archie-core-89x) and reference curators (i7i, gs8)
// are driven through it; nil when the family is not composed.
Curators *curator.Registry
// Identities holds per-identity runner state for multi-identity mode.
// When non-empty, Run() starts one goroutine per identity instead of
// using the single-identity Forge/Trees/Cfg.Repos path.
+7
View File
@@ -29,6 +29,13 @@ const (
KindHumanRejected = "human_rejected"
KindTaskRetried = "task_retried"
KindLog = "log" // data: level, msg
// Curator family activity (epic archie-core-yp9). Curator runs ride
// the same bus so background agents mutating memory stay observable:
// what ran, when, what changed, and why (archie-core-114).
KindCuratorRun = "curator_run" // data: curator, actions, at
KindCuratorAction = "curator_action" // data: curator, type, detail, reason
KindCuratorError = "curator_error" // data: curator, phase, err
)
// Event is the single wire type: task lifecycle, stage progress, agent