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:
1 parent
0ddc43081e
commit
4ece064026
11 files changed
+2054
No files matched your search
@@ -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.
|
||||
@@ -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
|
||||
}
|
||||
@@ -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)
|
||||
}
|
||||
}
|
||||
@@ -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) }
|
||||
@@ -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
|
||||
}
|
||||
@@ -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)
|
||||
}
|
||||
@@ -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,
|
||||
})
|
||||
}
|
||||
}
|
||||
@@ -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")
|
||||
}
|
||||
}
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user