Files
archie/internal/domain/memory/contract.go
T

375 lines
13 KiB
Go

// Package memory defines the memory engine contract: durable records in
// typed scopes, plus the content scanner. Engines apply no access policy.
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
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.
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 length-prefixed storage key, or "" for an invalid
// scope.
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 subject's readable scopes, narrowest first: agent-user,
// agent, user, global.
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 a memory backend's record operations. Each takes the record's
// Scope.
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.
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")
)