Files
archie/internal/domain/memory/contract.go
T
sam 708233a538 fix(webhook): keep a route path out of the sender identity
A webhook set SenderID to its configured route path. The turn path reads that
field through a per-channel resolver which refuses webhook, but the session
curator derives its participant from the raw field with no channel filter, so a
webhook session with exactly one distinct sender and one extracted fact wrote
agent-user memory addressed to User: "/hooks/...". Nothing reads it, and every
pass added more, because the facts are identical strings with no dedup.
docs/prds/memory-engine-unification.md criterion 7 requires that a route path
never become a user identity.

Clear it at the producer rather than teaching every consumer which channels are
lying: a route path is a source, not a person, so it no longer enters SenderID.
It still keys the inbound rate limit, where it is the documented per-source
budget for webhooks (config.RateLimitConfig), so it travels in the new
transport-only Inbound.BudgetKey -- carried on the wire beside Page, never
persisted, and never read as an identity.

pb.Message gains budget_key (field 9) for the same reason page (field 7) exists:
transport context that rides with an inbound message and is deliberately absent
from storedProto's rendering of a canonical record.

The curator needs no change. An empty SenderID already fails closed as an
unidentified user message, which is the path a dashboard session takes, and
sessionParticipant's existing skip covers it; the test name now says so.
2026-09-22 03:18:59 +10:00

418 lines
16 KiB
Go

// Package memory is the memory engine family: the authoritative store for
// durable observations, addressed by typed scope. See
// docs/prds/memory-engine-unification.md for the decision this contract
// implements.
//
// One engine, four scopes. A caller names the scopes it may read or write
// (Scope, Subject) and the engine applies no policy of its own: an engine
// that enforced access would need to know about channels, sessions and
// bindings, and every backend would reimplement it. Isolation then falls out
// mechanically, because ScopeAgent{a} and ScopeAgent{b} are different
// storage keys.
//
// The family follows the strict plugin engine rule: a typed contract
// (MemoryEngine) with real domain operations (create, read, update, delete,
// revisions — not just Name/Version), an owning registry (Registry) with
// start/health/stop and shutdown ordering, and narrow typed host access
// (Registrar) — an engine never receives the daemon or an untyped hook map.
//
// This package owns the contract and the family's policy that is independent
// of any backend (the content scanner). internal/memory's MemoryProvider and
// Manager predate the domain migration and are the legacy runtime path,
// deleted in slice 5 of the same PRD; nothing here depends on them.
package memory
import (
"context"
"errors"
"fmt"
"strconv"
"time"
)
// HealthStatus is an engine's point-in-time health.
type HealthStatus string
const (
HealthHealthy HealthStatus = "healthy"
HealthDegraded HealthStatus = "degraded"
HealthUnhealthy HealthStatus = "unhealthy"
)
// Health is a point-in-time engine health report.
type Health struct {
Status HealthStatus
Message string
}
// Manifest is an engine's declared shape. RequiresNetwork marks an engine
// that calls an external service, so a caller can size timeouts and
// failure-isolation expectations accordingly: a non-default engine's
// failure must degrade to a reported error, never take down a turn.
type Manifest struct {
RequiresNetwork bool
}
// Validate checks the declared shape. It is called by the registry at
// registration; present for symmetry with the curator family and as the
// seam for future required fields, even though no field is required yet.
func (m Manifest) Validate() error { return nil }
// Lifecycle is the start/health/stop contract every engine implements. The
// registry drives it with shutdown ordering and failure isolation; an
// engine'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
}
// ScopeKind names one of the four durable memory scopes
// (docs/architecture/agent-system.md, "Memory scopes").
type ScopeKind string
const (
// ScopeGlobal is shared across the application. Never model-writable:
// writing it is an operator action. It is part of the contract because
// the read set includes it.
ScopeGlobal ScopeKind = "global"
// ScopeAgent is private to one Agent. Agent-wide is not a synonym for
// shared; ScopeAgent{a} and ScopeAgent{b} are different keys.
ScopeAgent ScopeKind = "agent"
// ScopeUser is one user, across every Agent serving them.
ScopeUser ScopeKind = "user"
// ScopeAgentUser is one Agent's relationship with one user: the only
// home for relationship facts, and the scope the session curator
// writes.
ScopeAgentUser ScopeKind = "agent-user"
)
// AgentID and IdentityID are opaque. This package never resolves them,
// canonicalises them, or invents one from a channel: resolution happens
// where the channel's native identity is in hand (the gateway turn path),
// because a channel's sender id is not necessarily a person -- treating one
// as a person would give a URL an identity.
type (
AgentID string
IdentityID string
)
// Scope addresses one region of memory. Which components are required is a
// function of Kind, and Validate is the only place that rule lives.
type Scope struct {
Kind ScopeKind
Agent AgentID
User IdentityID
}
// Validate rejects an unknown kind, a missing component, and — just as
// importantly — a component present where it is not required, so no two
// spellings address the same region.
func (s Scope) Validate() error {
switch s.Kind {
case ScopeGlobal:
if s.Agent != "" || s.User != "" {
return fmt.Errorf("memory scope global: takes no agent or user, got agent %q user %q", s.Agent, s.User)
}
case ScopeAgent:
if s.Agent == "" {
return errors.New("memory scope agent: agent must not be empty")
}
if s.User != "" {
return fmt.Errorf("memory scope agent: takes no user, got %q", s.User)
}
case ScopeUser:
if s.User == "" {
return errors.New("memory scope user: user must not be empty")
}
if s.Agent != "" {
return fmt.Errorf("memory scope user: takes no agent, got %q", s.Agent)
}
case ScopeAgentUser:
if s.Agent == "" || s.User == "" {
return fmt.Errorf("memory scope agent-user: agent and user both required, got agent %q user %q", s.Agent, s.User)
}
default:
return fmt.Errorf("memory scope: unknown kind %q", s.Kind)
}
return nil
}
// Key returns the scope's canonical storage key. Each component is
// length-prefixed, so two different scopes can never share a key even when
// an id embeds the separator byte — which matters because AgentID and
// IdentityID are opaque and come from channels this package does not
// control.
//
// An invalid scope returns "", which a storage key can never legitimately
// be: callers must Validate first. Every engine path does.
func (s Scope) Key() string {
switch s.Kind {
case ScopeGlobal:
return "global"
case ScopeAgent:
return "agent:" + lengthPrefixed(string(s.Agent))
case ScopeUser:
return "user:" + lengthPrefixed(string(s.User))
case ScopeAgentUser:
return "agent-user:" + lengthPrefixed(string(s.Agent)) + ":" + lengthPrefixed(string(s.User))
default:
return ""
}
}
// String renders the scope for logs and error messages in Key's canonical
// form.
func (s Scope) String() string { return s.Key() }
// lengthPrefixed renders s as "<byteLen>:<s>", so a component containing ':'
// (or any other byte) cannot be confused with the boundary between
// components.
func lengthPrefixed(s string) string {
return strconv.Itoa(len(s)) + ":" + s
}
// Subject is a turn's resolved identity: one value, supplied by the
// composition per channel, never inferred by the engine.
type Subject struct {
// AgentID is the Agent serving the turn. Required in practice; an empty
// AgentID simply yields no agent-addressed scopes.
AgentID AgentID
// UserID is the initiating user's identity. Empty when the channel
// carries no per-person identity (the dashboard, a webhook) — which
// means "show none of it", never "fall back to a wider scope".
UserID IdentityID
}
// Scopes returns the scopes a read for this subject names, narrowest first:
// agent-user, agent, user, then global last, because global is the only
// scope every subject shares.
//
// The read path hands exactly this set to the engine and the engine unions
// nothing beyond it.
func (s Subject) Scopes() []Scope {
return append(s.WritableScopes(), Scope{Kind: ScopeGlobal})
}
// WritableScopes returns the scopes a write for this subject may name —
// Scopes() minus global, which is never model-writable. A component the
// subject does not carry removes every scope that requires it.
func (s Subject) WritableScopes() []Scope {
var scopes []Scope
if s.AgentID != "" && s.UserID != "" {
scopes = append(scopes, Scope{Kind: ScopeAgentUser, Agent: s.AgentID, User: s.UserID})
}
if s.AgentID != "" {
scopes = append(scopes, Scope{Kind: ScopeAgent, Agent: s.AgentID})
}
if s.UserID != "" {
scopes = append(scopes, Scope{Kind: ScopeUser, User: s.UserID})
}
return scopes
}
// Store is the real domain operations every memory backend implements.
// Split out from MemoryEngine so the two concerns (storage vs.
// identity/lifecycle) stay separately named and independently testable.
//
// Every method that touches one record takes the record's Scope: a record id
// alone does not locate a scope, and an engine that had to search for one
// would be reimplementing the caller's addressing.
type Store interface {
// Create records one new memory and returns the stored Record,
// including the identifier Get/Update/Forget/Revisions later need.
Create(ctx context.Context, in NewRecord) (Record, error)
// Get returns one record by id within scope. A missing record is
// ErrNotFound.
Get(ctx context.Context, scope Scope, id RecordID) (Record, error)
// Query returns the live records of q.Scopes, grouped in the order
// those scopes were named and ordered within a scope by the engine
// (most recent first is the expected choice). Heads only: superseded
// states are Revisions.
Query(ctx context.Context, q Query) ([]Record, error)
// List returns every live record of one scope, for inspection and
// deletion flows rather than relevance-ranked recall. Heads only.
List(ctx context.Context, scope Scope) ([]Record, error)
// Update supersedes a record's content and returns the new state. The
// superseded state is retained and readable through Revisions.
// Unaddressed, or already superseded when RecordUpdate.Expected is
// set, returns ErrNotFound or ErrStaleRevision respectively.
Update(ctx context.Context, in RecordUpdate) (Record, error)
// Forget removes one record's live state, retaining a deleted revision
// so its provenance outlives its content. Forgetting a record that
// does not exist is not an error: the end state (id absent) already
// holds.
Forget(ctx context.Context, scope Scope, id RecordID) error
// Revisions returns one record's retained states, oldest first,
// including the deleted revision Forget records. A record that never
// existed is not an error: the result is empty.
Revisions(ctx context.Context, scope Scope, id RecordID) ([]Revision, error)
}
// MemoryEngine is the typed contract every memory backend implements.
// Name/Version are identity, Manifest declares the shape, Store carries
// the real domain operations, Bind receives narrow host access, and
// Lifecycle carries start/health/stop.
type MemoryEngine interface {
Lifecycle
Store
Name() string
Version() string
Manifest() Manifest
// Bind attaches the engine's narrow host access. The registry calls
// Bind exactly once, at registration.
Bind(host Registrar)
}
// RecordID identifies one record within its scope, stable for the record's
// whole life: assigned once at Create, independent of content, so an edit
// somewhere else can never orphan an id.
type RecordID string
// NewRecord is one memory submitted for creation. Revision, timestamps and
// id are stamped by the engine; Scope is what the record will be addressed
// by for the rest of its life.
type NewRecord struct {
Scope Scope
Kind string
Content string
// Author is the acting identity that wrote the record — an agent id, or
// a producer's own name ("operator", "session-memory curator"). Free
// text: the engine retains it, it does not interpret it.
Author string
// OriginUser is the user whose interaction produced the record, when
// one is known. Distinct from Scope.User: a curator writing
// agent-user scope has both, but a record about a user may be written
// into agent scope by an operator.
OriginUser IdentityID
// Source is the producer's own label for where the record came from
// (a tool name, a curator pass, a session id). Free text.
Source string
}
// Validate checks what every engine needs before writing: an addressable
// scope and content. Kind's format belongs to the backend (the builtin
// engine maps it to a section name), so it is validated there.
//
// Implementations must also scan Content before persisting it — see
// ScanContent and docs/prds/memory-engine-unification.md §7.
func (n NewRecord) Validate() error {
if err := n.Scope.Validate(); err != nil {
return err
}
if n.Content == "" {
return errors.New("memory record: content must not be empty")
}
return nil
}
// Query asks an engine to recall records within the caller-named scopes.
type Query struct {
// Scopes is the read set, narrowest first (Subject.Scopes()). The
// engine unions exactly these and applies no policy of its own.
Scopes []Scope
// Text filters by content substring when non-empty. It stays unused by
// the prompt path; ranked retrieval is a deliberately open question.
Text string
// Limit bounds the number of records returned. Zero lets the engine
// choose a default; there is no way to request "unlimited" — List
// exists for that.
Limit int
}
// Validate rejects an empty or invalid read set, and a negative limit.
func (q Query) Validate() error {
if len(q.Scopes) == 0 {
return errors.New("memory query: at least one scope is required")
}
for _, scope := range q.Scopes {
if err := scope.Validate(); err != nil {
return fmt.Errorf("memory query: %w", err)
}
}
if q.Limit < 0 {
return fmt.Errorf("memory query: limit must not be negative, got %d", q.Limit)
}
return nil
}
// RecordUpdate supersedes one record's content. It deliberately cannot name
// a Scope: a record may never move between scopes, so the API makes that
// unrepresentable rather than validating it.
type RecordUpdate struct {
// Scope and ID address the record being superseded.
Scope Scope
ID RecordID
// Content replaces the live content. Required.
Content string
// Expected optionally names the revision this update supersedes. Zero
// means "whatever is live". A mismatch returns ErrStaleRevision, which
// matters because two processes (archied and archie-gateway) can hold
// the same scope's file.
Expected int
// Author and Source are refreshed on the new revision, with the same
// meaning as in NewRecord.
Author string
Source string
}
// Validate checks the address and the replacement content.
func (u RecordUpdate) Validate() error {
if err := u.Scope.Validate(); err != nil {
return err
}
if u.ID == "" {
return errors.New("memory record update: id must not be empty")
}
if u.Content == "" {
return errors.New("memory record update: content must not be empty")
}
if u.Expected < 0 {
return fmt.Errorf("memory record update: expected revision must not be negative, got %d", u.Expected)
}
return nil
}
// Record is one stored memory as returned by Create, Get, Query, List or
// Update. It carries the provenance agent-system.md requires be retained:
// scope, kind, content, revision, author, originating user, source, and
// timestamps.
type Record struct {
ID RecordID
Scope Scope
Kind string
Content string
Revision int
Author string
OriginUser IdentityID
Source string
CreatedAt time.Time
UpdatedAt time.Time
}
// Revision is one retained state of a record: a state that was live and has
// been superseded, or the deletion marker Forget records. The record's own
// Revision field is the revision this state carried while live.
type Revision struct {
Record Record
// SupersededAt is when this state stopped being live (replaced by an
// Update, or removed by a Forget).
SupersededAt time.Time
// Deleted marks the revision Forget recorded: Record.Content is the
// last live content, retained so provenance outlives it.
Deleted bool
}
// Store errors. Both cross a producer/consumer boundary, and both are
// expected conditions rather than failures: a missing record and a losing
// race between two processes holding one scope.
var (
// ErrNotFound is returned when a record does not exist in the named
// scope. Get and Update return it; Forget and Revisions do not, because
// their end state already holds.
ErrNotFound = errors.New("memory record not found")
// ErrStaleRevision is returned when RecordUpdate.Expected names a
// revision that is no longer live.
ErrStaleRevision = errors.New("memory record revision is stale")
)