Files
archie/internal/infrastructure/memory/builtin_engine.go
T
sam 7b39f7bd0c feat(memory): builtin engine implementing the domain/memory contract
Part of archie-core-1786637499480 (ship the file-writing store as the
default memory engine).

Records the missing design decision first (migration-decisions.md#5,
"authoritative memory record and revision model" was explicitly open):
internal/memory/builtin.Store addresses blocks by content substring with
no stable per-block ID, which the new Record{ID}/Forget(id) contract
needs. Decided and implemented: an ID assigned once at Write via a
leading `<!--mem:<uuid>-->` marker line, stripped back out of
Record.Content on read, located by that marker (not content) for
Forget -- so an unrelated edit can never orphan a Forget. Identity maps
to a directory named hex(sha256(identity)), not the identity string, so
an arbitrary identity can never traverse outside the configured root.
Kind maps to a builtin section name via the store's own
ValidateSectionName, so an invalid Kind fails the same way an invalid
section already does.

internal/infrastructure/memory.BuiltinEngine wraps one builtin.Store per
identity and implements domain/memory.MemoryEngine end to end
(Write/Query/List/Forget, Lifecycle, Manifest). Lives under
internal/infrastructure per organisation.md ("infrastructure implements
domain contracts"), not internal/domain/memory, which stays
contract-only.

internal/memory/builtin is untouched -- confirmed via git status and its
own test suite passing unmodified, per this issue's acceptance
criterion. This engine is not yet wired into daemon bootstrap or the
config surface (archie-core-1786637490043); it proves the contract
holds for the builtin store the same way curator's reference
implementations prove the curator contract, and registers/runs cleanly
through domain/memory.Registry (TestBuiltinEngineRegistersAndRuns
ThroughTheRegistry).
2026-09-02 02:36:10 +10:00

230 lines
6.9 KiB
Go

// Package memory implements domain/memory.MemoryEngine against concrete
// backends. See docs/architecture/migration-decisions.md#5-memory-placement-and-storage
// for the record/identity model this package's builtin engine follows.
package memory
import (
"context"
"crypto/sha256"
"encoding/hex"
"errors"
"fmt"
"os"
"path/filepath"
"strings"
"sync"
"github.com/google/uuid"
domainmemory "github.com/samcharles93/archie-core/internal/domain/memory"
"github.com/samcharles93/archie-core/internal/memory/builtin"
)
// EngineName is the name BuiltinEngine registers under and the default the
// config surface (archie-core-1786637490043) resolves to when no engine is
// configured.
const EngineName = "builtin"
// markerPrefix opens the leading line every block written through this
// engine carries, embedding the record's stable ID. See the migration
// decision this package implements: an ID assigned once at Write, never
// derived from content, so a later edit elsewhere in the file can never
// orphan a Forget.
const (
markerPrefix = "<!--mem:"
markerSuffix = "-->"
)
// defaultSectionName is the section an Observation with an empty Kind is
// written to.
const defaultSectionName = "general"
// BuiltinEngine implements domain/memory.MemoryEngine over one
// internal/memory/builtin.Store per identity. internal/memory/builtin is
// unchanged by this package -- see the migration decision this
// implements for why.
type BuiltinEngine struct {
root string
maxFileBytes int
mu sync.Mutex
stores map[string]*builtin.Store // keyed by identity, lazily created
}
// NewBuiltinEngine builds an engine that persists each identity's
// observations under its own subdirectory of root, named
// hex(sha256(identity)) -- never the identity string itself, so an
// arbitrary identity can never traverse outside root and two identities
// differing only in filesystem-equivalent characters can never collide.
// maxFileBytes <= 0 uses the store's own default.
func NewBuiltinEngine(root string, maxFileBytes int) *BuiltinEngine {
return &BuiltinEngine{root: root, maxFileBytes: maxFileBytes, stores: make(map[string]*builtin.Store)}
}
func (e *BuiltinEngine) Name() string { return EngineName }
func (e *BuiltinEngine) Version() string { return "1" }
func (e *BuiltinEngine) Manifest() domainmemory.Manifest {
return domainmemory.Manifest{RequiresNetwork: false}
}
func (e *BuiltinEngine) Bind(domainmemory.Registrar) {}
func (e *BuiltinEngine) Start(context.Context) error { return nil }
func (e *BuiltinEngine) Health(context.Context) domainmemory.Health {
return domainmemory.Health{Status: domainmemory.HealthHealthy}
}
func (e *BuiltinEngine) Stop(context.Context) error { return nil }
// storeFor returns the identity's store, creating and caching it on first
// use.
func (e *BuiltinEngine) storeFor(identity string) (*builtin.Store, error) {
e.mu.Lock()
defer e.mu.Unlock()
if s, ok := e.stores[identity]; ok {
return s, nil
}
dir := filepath.Join(e.root, identityDir(identity))
if err := os.MkdirAll(dir, 0o755); err != nil {
return nil, fmt.Errorf("memory: builtin engine: identity directory %s unusable: %w", dir, err)
}
s, err := builtin.NewStore(filepath.Join(dir, "OBSERVATIONS.md"), e.maxFileBytes)
if err != nil {
return nil, err
}
e.stores[identity] = s
return s, nil
}
// identityDir maps an identity to a filesystem-safe, collision-resistant
// directory name.
func identityDir(identity string) string {
sum := sha256.Sum256([]byte(identity))
return hex.EncodeToString(sum[:])
}
// sectionFor returns the section an Observation's Kind maps to, and
// validates it the same way builtin already validates any section name --
// so an invalid Kind fails with the same error shape memory_edit already
// returns for an invalid section, not a new one.
func sectionFor(kind string) (string, error) {
if kind == "" {
kind = defaultSectionName
}
if err := builtin.ValidateSectionName(kind); err != nil {
return "", err
}
return kind, nil
}
func (e *BuiltinEngine) Write(_ context.Context, obs domainmemory.Observation) (domainmemory.Record, error) {
if err := obs.Validate(); err != nil {
return domainmemory.Record{}, err
}
section, err := sectionFor(obs.Kind)
if err != nil {
return domainmemory.Record{}, err
}
s, err := e.storeFor(obs.Identity)
if err != nil {
return domainmemory.Record{}, err
}
id := uuid.NewString()
marked := markerPrefix + id + markerSuffix + "\n" + obs.Content
if _, err := s.Add(section, marked); err != nil {
return domainmemory.Record{}, err
}
return domainmemory.Record{
ID: id,
Identity: obs.Identity,
Kind: section,
Content: obs.Content,
At: obs.At,
Metadata: obs.Metadata,
}, nil
}
func (e *BuiltinEngine) Query(ctx context.Context, q domainmemory.Query) ([]domainmemory.Record, error) {
if err := q.Validate(); err != nil {
return nil, err
}
all, err := e.List(ctx, q.Identity)
if err != nil {
return nil, err
}
if q.Text == "" {
return limitRecords(all, q.Limit), nil
}
var matched []domainmemory.Record
for _, r := range all {
if strings.Contains(r.Content, q.Text) {
matched = append(matched, r)
}
}
return limitRecords(matched, q.Limit), nil
}
func limitRecords(records []domainmemory.Record, limit int) []domainmemory.Record {
if limit > 0 && len(records) > limit {
return records[:limit]
}
return records
}
func (e *BuiltinEngine) List(_ context.Context, identity string) ([]domainmemory.Record, error) {
if identity == "" {
return nil, errors.New("memory: builtin engine: identity must not be empty")
}
s, err := e.storeFor(identity)
if err != nil {
return nil, err
}
return parseRecords(identity, s.Render()), nil
}
func (e *BuiltinEngine) Forget(_ context.Context, id string) error {
if id == "" {
return errors.New("memory: builtin engine: id must not be empty")
}
marker := markerPrefix + id + markerSuffix
e.mu.Lock()
stores := make([]*builtin.Store, 0, len(e.stores))
for _, s := range e.stores {
stores = append(stores, s)
}
e.mu.Unlock()
// Forgetting an id that does not exist is not an error (contract.go's
// Forget doc): the end state -- id absent -- already holds whether or
// not any store ever had it, so checking every known identity's store
// and returning nil regardless of a miss is correct, not a fallback
// masking a real failure.
for _, s := range stores {
section, ok := sectionOf(s.Render(), id)
if !ok {
continue
}
if _, err := s.Remove(section, marker, true); err != nil {
return err
}
return nil
}
return nil
}
// sectionOf finds which section of rendered carries a block whose marker
// names id, so Forget can call Store.Remove with the section it actually
// requires without a mutating probe. ok is false if no block does.
func sectionOf(rendered, id string) (section string, ok bool) {
for _, rec := range parseRecords("", rendered) {
if rec.ID == id {
return rec.Kind, true
}
}
return "", false
}