From c4859981602e8292977c69b8947a97c537417f69 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Thu, 24 Sep 2026 14:26:41 +1000 Subject: [PATCH 1/8] refactor(scheduling): own the cron dialect instead of pocketbase tools/cron --- internal/domain/scheduling/cron.go | 118 ++++++++++++++++++++ internal/domain/scheduling/cron_test.go | 56 ++++++++++ internal/domain/scheduling/schedule.go | 27 +---- internal/domain/scheduling/schedule_test.go | 4 +- 4 files changed, 182 insertions(+), 23 deletions(-) create mode 100644 internal/domain/scheduling/cron.go create mode 100644 internal/domain/scheduling/cron_test.go diff --git a/internal/domain/scheduling/cron.go b/internal/domain/scheduling/cron.go new file mode 100644 index 000000000..73ebe0c4e --- /dev/null +++ b/internal/domain/scheduling/cron.go @@ -0,0 +1,118 @@ +package scheduling + +import ( + "errors" + "fmt" + "strconv" + "strings" + "time" +) + +// cronSlots is the set of values one cron field matches, as a bitmask; every +// field's range fits in 64 bits. +type cronSlots uint64 + +func (s cronSlots) has(v int) bool { return v >= 0 && v < 64 && s&(1< hi { + return 0, fmt.Errorf("step %q must be between 1 and %d", stepText, hi) + } + step = n + } + first, last := lo, hi + if base != "*" { + from, to, ranged := strings.Cut(base, "-") + if !ranged && stepped { + return 0, fmt.Errorf("step in %q needs a wildcard or a range", part) + } + var err error + if first, err = cronValue(from, lo, hi); err != nil { + return 0, err + } + last = first + if ranged { + if last, err = cronValue(to, first, hi); err != nil { + return 0, err + } + } + } + for v := first; v <= last; v += step { + slots |= 1 << v + } + } + return slots, nil +} + +func cronValue(text string, lo, hi int) (int, error) { + v, err := strconv.Atoi(text) + if err != nil { + return 0, fmt.Errorf("value %q is not a number", text) + } + if v < lo || v > hi { + return 0, fmt.Errorf("value %d must be between %d and %d", v, lo, hi) + } + return v, nil +} diff --git a/internal/domain/scheduling/cron_test.go b/internal/domain/scheduling/cron_test.go new file mode 100644 index 000000000..e3fbce59e --- /dev/null +++ b/internal/domain/scheduling/cron_test.go @@ -0,0 +1,56 @@ +package scheduling + +import ( + "errors" + "slices" + "testing" +) + +func TestParseCronSegment(t *testing.T) { + tests := []struct { + segment string + want []int + wantErr bool + }{ + {segment: "*", want: []int{0, 1, 2, 3, 4, 5, 6}}, + {segment: "*/3", want: []int{0, 3, 6}}, + {segment: "1-5/2", want: []int{1, 3, 5}}, + {segment: "0,2-3,6", want: []int{0, 2, 3, 6}}, + {segment: "4", want: []int{4}}, + {segment: "4/2", wantErr: true}, + {segment: "5-2", wantErr: true}, + {segment: "*/7", wantErr: true}, + {segment: "1/2/3", wantErr: true}, + {segment: "1-2-3", wantErr: true}, + {segment: "", wantErr: true}, + } + for _, tc := range tests { + t.Run(tc.segment, func(t *testing.T) { + got, err := parseCronSegment(tc.segment, 0, 6) + if tc.wantErr { + if err == nil { + t.Fatalf("parseCronSegment(%q) = %v, want an error", tc.segment, got) + } + return + } + if err != nil { + t.Fatalf("parseCronSegment(%q): %v", tc.segment, err) + } + var slots []int + for v := 0; v <= 6; v++ { + if got.has(v) { + slots = append(slots, v) + } + } + if !slices.Equal(slots, tc.want) { + t.Fatalf("parseCronSegment(%q) = %v, want %v", tc.segment, slots, tc.want) + } + }) + } +} + +func TestParseCronSpecWrapsErrInvalidSpec(t *testing.T) { + if _, err := parseCronSpec("0 0 * * 7"); !errors.Is(err, ErrInvalidSpec) { + t.Fatalf("parseCronSpec = %v, want ErrInvalidSpec", err) + } +} diff --git a/internal/domain/scheduling/schedule.go b/internal/domain/scheduling/schedule.go index 787f02245..b4547b82d 100644 --- a/internal/domain/scheduling/schedule.go +++ b/internal/domain/scheduling/schedule.go @@ -4,8 +4,6 @@ import ( "encoding/json" "fmt" "time" - - "github.com/pocketbase/pocketbase/tools/cron" ) // Duration is a schedule interval as the document writes it: the human string @@ -91,9 +89,8 @@ const ( // ScheduleCron fires at the next moment matching a 5-field cron // expression (or one of the @ macros) after the last successful - // run, computed in the zone of that run time. Expressions are parsed - // with pocketbase tools/cron, which ANDs day-of-month with day-of-week - // instead of Vixie cron's OR: "0 0 1 * 1" means only Monday the 1st, + // run, computed in the zone of that run time. The dialect (cron.go) + // ANDs day-of-month with day-of-week instead of Vixie cron's OR: "0 0 1 * 1" means only Monday the 1st, // not "the 1st or any Monday". ScheduleCron = "cron" @@ -168,18 +165,6 @@ func (s Schedule) firstRun(now time.Time) (time.Time, error) { } } -// parseCronSpec parses expr with pocketbase tools/cron — the project's -// chosen cron dialect: standard 5-field expressions plus the @yearly, -// @monthly, @weekly, @daily and @hourly macros — and wraps any parse -// failure in ErrInvalidSpec so callers need only the one sentinel. -func parseCronSpec(expr string) (*cron.Schedule, error) { - sched, err := cron.NewSchedule(expr) - if err != nil { - return nil, fmt.Errorf("%w: cron expression %q: %w", ErrInvalidSpec, expr, err) - } - return sched, nil -} - // cronHorizon bounds the next-run scan. A satisfiable expression always // fires well within it (the sparsest realistic case, Feb 29, recurs every // four years); only a spec that can never fire — e.g. "0 0 30 2 *", which @@ -191,17 +176,17 @@ const cronHorizon = 5 * 365 * 24 * time.Hour // minute that just fired is never its own successor. Whole months and // hours that cannot match are skipped, so even a sparse expression costs // a handful of iterations per year scanned. -func nextCronRun(sched *cron.Schedule, from time.Time) (time.Time, error) { +func nextCronRun(sched *cronSpec, from time.Time) (time.Time, error) { t := from.Truncate(time.Minute).Add(time.Minute) for limit := from.Add(cronHorizon); t.Before(limit); { - if sched.IsDue(cron.NewMoment(t)) { + if sched.due(t) { return t, nil } - if _, ok := sched.Months[int(t.Month())]; !ok { + if !sched.months.has(int(t.Month())) { t = time.Date(t.Year(), t.Month(), 1, 0, 0, 0, 0, t.Location()).AddDate(0, 1, 0) continue } - if _, ok := sched.Hours[t.Hour()]; !ok { + if !sched.hours.has(t.Hour()) { t = t.Add(time.Hour).Truncate(time.Hour) continue } diff --git a/internal/domain/scheduling/schedule_test.go b/internal/domain/scheduling/schedule_test.go index 44734b435..b9285df0e 100644 --- a/internal/domain/scheduling/schedule_test.go +++ b/internal/domain/scheduling/schedule_test.go @@ -36,8 +36,8 @@ func TestScheduleCronNextRun(t *testing.T) { want: zoned(2026, 8, 24, 12, 15, 0), }, { - // pins the pocketbase AND semantics: Vixie cron would give the - // next Monday (2026-08-31); tools/cron gives Monday the 1st. + // pins the AND semantics: Vixie cron would give the next Monday + // (2026-08-31); this dialect gives Monday the 1st. name: "dual-restricted day-of-month and day-of-week AND, not Vixie OR", expr: "0 0 1 * 1", lastRun: zoned(2026, 8, 24, 12, 15, 30), From 57ddd4e0029d34d0d35498474d6976a186e28cb9 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Thu, 24 Sep 2026 14:26:42 +1000 Subject: [PATCH 2/8] refactor(gateway): replace the SQLite session store with an in-memory store --- internal/gateway/compress_identity_test.go | 10 +- internal/gateway/compress_trigger_test.go | 5 +- internal/gateway/session_store.go | 9 - internal/gateway/session_store_memory.go | 482 ++++++ .../gateway/session_store_postgres_test.go | 21 +- internal/gateway/session_store_sqlite.go | 1112 -------------- ...ession_store_sqlite_claimturn_race_test.go | 102 -- .../session_store_sqlite_conformance_test.go | 15 - internal/gateway/session_store_sqlite_test.go | 1365 ----------------- internal/gateway/turn_ledger.go | 42 + internal/gateway/turn_ledger_test.go | 84 +- 11 files changed, 581 insertions(+), 2666 deletions(-) create mode 100644 internal/gateway/session_store_memory.go delete mode 100644 internal/gateway/session_store_sqlite.go delete mode 100644 internal/gateway/session_store_sqlite_claimturn_race_test.go delete mode 100644 internal/gateway/session_store_sqlite_conformance_test.go delete mode 100644 internal/gateway/session_store_sqlite_test.go diff --git a/internal/gateway/compress_identity_test.go b/internal/gateway/compress_identity_test.go index e3042bdd3..aeeb6f8bf 100644 --- a/internal/gateway/compress_identity_test.go +++ b/internal/gateway/compress_identity_test.go @@ -12,14 +12,8 @@ import ( // compressBackends provides the persistent store used by compression tests. func compressBackends() map[string]func(t *testing.T) SessionStore { return map[string]func(t *testing.T) SessionStore{ - "sqlite": func(t *testing.T) SessionStore { - s, err := NewSQLiteSessionStoreMemory() - if err != nil { - t.Fatalf("NewSQLiteSessionStoreMemory: %v", err) - } - t.Cleanup(func() { _ = s.Close() }) - return s - }, + "memory": func(*testing.T) SessionStore { return NewSessionStoreMemory() }, + "postgres": func(t *testing.T) SessionStore { return newPostgresStore(t) }, } } diff --git a/internal/gateway/compress_trigger_test.go b/internal/gateway/compress_trigger_test.go index 7617ef74b..a87729a55 100644 --- a/internal/gateway/compress_trigger_test.go +++ b/internal/gateway/compress_trigger_test.go @@ -38,10 +38,7 @@ func (s *countingReplaceStore) ReplaceMessages(ctx context.Context, sessionID st // written to it. func newTriggerStore(t *testing.T) *countingReplaceStore { t.Helper() - inner, err := NewSQLiteSessionStoreMemory() - if err != nil { - t.Fatalf("NewSQLiteSessionStoreMemory: %v", err) - } + inner := NewSessionStoreMemory() t.Cleanup(func() { _ = inner.Close() }) ledger, ok := inner.(TurnLedger) if !ok { diff --git a/internal/gateway/session_store.go b/internal/gateway/session_store.go index 96e690ac2..e0f874455 100644 --- a/internal/gateway/session_store.go +++ b/internal/gateway/session_store.go @@ -10,15 +10,6 @@ import ( "github.com/samcharles93/archie-core/internal/domain/messaging" ) -// NewSessionStoreMemory returns an in-memory SQLite SessionStore for tests. -func NewSessionStoreMemory() SessionStore { - store, err := NewSQLiteSessionStoreMemory() - if err != nil { - panic(err) - } - return store -} - // sessionRecency is the later of a session's creation and activity times. func sessionRecency(sc SessionContext) time.Time { if sc.LastActiveAt.After(sc.CreatedAt) { diff --git a/internal/gateway/session_store_memory.go b/internal/gateway/session_store_memory.go new file mode 100644 index 000000000..cfa407f06 --- /dev/null +++ b/internal/gateway/session_store_memory.go @@ -0,0 +1,482 @@ +package gateway + +import ( + "context" + "fmt" + "slices" + "strings" + "sync" + "time" + "unicode" + + "github.com/samcharles93/archie-core/internal/domain/messaging" +) + +// memorySessionStore is the in-process SessionStore for tests and embedders +// that need no durability. It follows the PostgreSQL store's contract +// (sessionstore_conformance_test.go) including the optional TurnLedger, +// TurnHistory and TurnReplayStore capabilities: millisecond timestamps, the +// strictly-increasing append clamp, redelivery dedup on canonical IDs, and a +// search that ANDs lowercase word terms over sender and text. +type memorySessionStore struct { + mu sync.Mutex + sessions map[string]SessionContext + messages map[string][]memoryMessage + turns map[string]TurnRecord + seq int64 +} + +type memoryMessage struct { + seq int64 + ts int64 + msg messaging.Message +} + +// NewSessionStoreMemory returns an empty in-memory SessionStore. +func NewSessionStoreMemory() SessionStore { + return &memorySessionStore{ + sessions: map[string]SessionContext{}, + messages: map[string][]memoryMessage{}, + turns: map[string]TurnRecord{}, + } +} + +func (s *memorySessionStore) Close() error { return nil } + +func truncateMilli(t time.Time) time.Time { return time.UnixMilli(t.UnixMilli()).UTC() } + +// ── Sessions ──────────────────────────────────────────────────────────────── + +func (s *memorySessionStore) Save(_ context.Context, sc SessionContext) error { + s.mu.Lock() + defer s.mu.Unlock() + sc.CreatedAt = truncateMilli(sc.CreatedAt) + sc.LastActiveAt = truncateMilli(sc.LastActiveAt) + s.sessions[sc.SessionID] = sc + return nil +} + +func (s *memorySessionStore) Get(_ context.Context, sessionID string) (*SessionContext, error) { + s.mu.Lock() + defer s.mu.Unlock() + sc, ok := s.sessions[sessionID] + if !ok { + return nil, nil + } + return &sc, nil +} + +func (s *memorySessionStore) GetByChannel(_ context.Context, platform, channelID string) ([]SessionContext, error) { + s.mu.Lock() + defer s.mu.Unlock() + return s.sortedSessions(func(sc SessionContext) bool { + return sc.Source.Platform == platform && sc.Source.ChannelID == channelID + }), nil +} + +func (s *memorySessionStore) List(_ context.Context) ([]SessionContext, error) { + s.mu.Lock() + defer s.mu.Unlock() + return s.sortedSessions(func(SessionContext) bool { return true }), nil +} + +func (s *memorySessionStore) sortedSessions(keep func(SessionContext) bool) []SessionContext { + out := make([]SessionContext, 0, len(s.sessions)) + for _, sc := range s.sessions { + if keep(sc) { + out = append(out, sc) + } + } + slices.SortFunc(out, func(a, b SessionContext) int { + if c := sessionRecency(b).Compare(sessionRecency(a)); c != 0 { + return c + } + return strings.Compare(a.SessionID, b.SessionID) + }) + return out +} + +func (s *memorySessionStore) Delete(_ context.Context, sessionID string) error { + s.mu.Lock() + defer s.mu.Unlock() + delete(s.sessions, sessionID) + delete(s.messages, sessionID) + for id, turn := range s.turns { + if turn.SessionID == sessionID { + delete(s.turns, id) + } + } + return nil +} + +func (s *memorySessionStore) Touch(_ context.Context, sessionID string) error { + s.mu.Lock() + defer s.mu.Unlock() + if sc, ok := s.sessions[sessionID]; ok { + sc.LastActiveAt = truncateMilli(time.Now().UTC()) + s.sessions[sessionID] = sc + } + return nil +} + +// ── Messages ──────────────────────────────────────────────────────────────── + +func (s *memorySessionStore) SaveMessage(_ context.Context, sessionID string, msg messaging.Message) error { + s.mu.Lock() + defer s.mu.Unlock() + s.saveMessage(sessionID, msg, true) + return nil +} + +func (s *memorySessionStore) SaveMessages(_ context.Context, sessionID string, msgs []messaging.Message) error { + s.mu.Lock() + defer s.mu.Unlock() + for _, msg := range msgs { + s.saveMessage(sessionID, msg, true) + } + return nil +} + +func (s *memorySessionStore) indexOf(sessionID, id string) int { + return slices.IndexFunc(s.messages[sessionID], func(m memoryMessage) bool { return string(m.msg.ID) == id }) +} + +// saveMessage stores msg and returns the canonical ID it lives under. clamp +// selects the append path, whose timestamp must exceed the session's newest. +func (s *memorySessionStore) saveMessage(sessionID string, msg messaging.Message, clamp bool) string { + id := string(msg.ID) + legacyID := "" + if msg.SourceID == "" { + if id == "" { + id = newMessageID(sessionID, "") + } + } else { + currentID, compatibleLegacyID := canonicalMessageIDs(sessionID, msg.SourceID) + if id == "" { + id = currentID + } + if id == currentID { + legacyID = compatibleLegacyID + } + } + if legacyID != "" && s.indexOf(sessionID, legacyID) >= 0 { + return legacyID + } + if s.indexOf(sessionID, id) >= 0 { + return id + } + role := msg.Role + if role == "" { + role = messaging.RoleUser + } + ts := stamp(msg).UnixMilli() + history := s.messages[sessionID] + if clamp { + for _, m := range history { + if m.ts >= ts { + ts = m.ts + 1 + } + } + } + s.seq++ + stored := messaging.Message{ + ID: messaging.MessageID(id), SourceID: msg.SourceID, Sender: msg.Sender, + SenderID: msg.SenderID, Role: role, Text: msg.Text, + } + history = append(history, memoryMessage{seq: s.seq, ts: ts, msg: stored}) + slices.SortStableFunc(history, func(a, b memoryMessage) int { + if a.ts != b.ts { + return int(a.ts - b.ts) + } + return int(a.seq - b.seq) + }) + s.messages[sessionID] = history + return id +} + +func (s *memorySessionStore) ReplaceMessages(_ context.Context, sessionID string, msgs []messaging.Message, superseded []string) error { + s.mu.Lock() + defer s.mu.Unlock() + survivors := make(map[string]struct{}, len(msgs)) + for _, msg := range msgs { + survivors[s.saveMessage(sessionID, msg, false)] = struct{}{} + } + doomed := make(map[string]struct{}, len(superseded)) + for _, id := range superseded { + if _, kept := survivors[id]; !kept { + doomed[id] = struct{}{} + } + } + s.messages[sessionID] = slices.DeleteFunc(s.messages[sessionID], func(m memoryMessage) bool { + _, drop := doomed[string(m.msg.ID)] + return drop + }) + return nil +} + +// read returns the stored message with its session's conversation address. +func (s *memorySessionStore) read(sessionID string, m memoryMessage) messaging.Message { + out := m.msg + out.At = time.UnixMilli(m.ts).UTC() + if sc, ok := s.sessions[sessionID]; ok { + out.ConversationID = messaging.ConversationID{ChannelID: sc.Source.ChannelID, ThreadID: sc.Source.ThreadID} + } + return out +} + +func (s *memorySessionStore) RecentMessages(_ context.Context, sessionID string, n int) ([]messaging.Message, error) { + if n <= 0 { + return nil, nil + } + s.mu.Lock() + defer s.mu.Unlock() + history := s.messages[sessionID] + history = history[max(len(history)-n, 0):] + out := make([]messaging.Message, 0, len(history)) + for _, m := range history { + out = append(out, s.read(sessionID, m)) + } + return out, nil +} + +func (s *memorySessionStore) DeleteRecentMessages(_ context.Context, sessionID string, n int) (int, error) { + if n <= 0 { + return 0, nil + } + s.mu.Lock() + defer s.mu.Unlock() + history := s.messages[sessionID] + deleted := min(n, len(history)) + s.messages[sessionID] = history[:len(history)-deleted] + return deleted, nil +} + +func (s *memorySessionStore) MessageCount(_ context.Context, sessionID string) (int, error) { + s.mu.Lock() + defer s.mu.Unlock() + return len(s.messages[sessionID]), nil +} + +func (s *memorySessionStore) FindPriorReply(_ context.Context, sessionID, sourceID, identity string) (string, error) { + if sourceID == "" { + return "", nil + } + s.mu.Lock() + defer s.mu.Unlock() + currentID, legacyID := canonicalMessageIDs(sessionID, sourceID) + i := -1 + if legacyID != "" { + i = s.indexOf(sessionID, legacyID) + } + if i < 0 { + i = s.indexOf(sessionID, currentID) + } + history := s.messages[sessionID] + if i < 0 || i+1 >= len(history) { + return "", nil + } + next := history[i+1].msg + if next.Sender != identity || isCompressionSummary(next.Text) { + return "", nil + } + return next.Text, nil +} + +// searchTerms splits text into lowercase letter-and-digit words. +func searchTerms(text string) []string { + return strings.FieldsFunc(strings.ToLower(text), func(r rune) bool { + return !unicode.IsLetter(r) && !unicode.IsDigit(r) + }) +} + +func (s *memorySessionStore) SearchMessages(_ context.Context, sessionID string, q MessageQuery) (MessagePage, error) { + query := strings.TrimSpace(q.Query) + if query == "" { + return MessagePage{}, nil + } + if len(query) > MaxMessageSearchQueryBytes { + return MessagePage{}, fmt.Errorf("sessionstore: search query exceeds %d bytes", MaxMessageSearchQueryBytes) + } + if terms := len(strings.Fields(query)); terms > MaxMessageSearchQueryTerms { + return MessagePage{}, fmt.Errorf("sessionstore: search query exceeds %d terms", MaxMessageSearchQueryTerms) + } + terms := searchTerms(query) + if len(terms) == 0 { + return MessagePage{}, nil + } + limit := q.Limit + if limit <= 0 { + limit = DefaultMessagePageSize + } + limit = min(limit, MaxMessagePageSize) + offset := max(q.Offset, 0) + + s.mu.Lock() + defer s.mu.Unlock() + var matches []messaging.Message + history := s.messages[sessionID] + for _, m := range slices.Backward(history) { + words := searchTerms(m.msg.Sender + " " + m.msg.Text) + if !allIn(terms, words) { + continue + } + matches = append(matches, s.read(sessionID, m)) + } + if offset >= len(matches) { + return MessagePage{}, nil + } + page := matches[offset:min(offset+limit, len(matches))] + next := offset + len(page) + return MessagePage{Messages: page, NextOffset: next, HasMore: next < len(matches)}, nil +} + +func allIn(terms, words []string) bool { + for _, term := range terms { + if !slices.Contains(words, term) { + return false + } + } + return true +} + +// ── Turns ─────────────────────────────────────────────────────────────────── + +// storedTurn normalises a turn the way a database round trip does. +func storedTurn(turn TurnRecord) (TurnRecord, error) { + raw, err := marshalToolCalls(turn.ToolCalls) + if err != nil { + return TurnRecord{}, err + } + if turn.ToolCalls, err = unmarshalToolCalls(raw); err != nil { + return TurnRecord{}, err + } + turn.CreatedAt = truncateMilli(turn.CreatedAt) + turn.UpdatedAt = truncateMilli(turn.UpdatedAt) + return turn, nil +} + +func (s *memorySessionStore) ClaimTurn(_ context.Context, initial TurnRecord) (TurnRecord, TurnClaim, error) { + initial, _, err := prepareInitialTurn(initial, time.Now().UTC()) + if err != nil { + return TurnRecord{}, "", err + } + if initial, err = storedTurn(initial); err != nil { + return TurnRecord{}, "", err + } + s.mu.Lock() + defer s.mu.Unlock() + turn, exists := s.turns[initial.TurnID] + if !exists { + s.turns[initial.TurnID] = initial + return initial, TurnClaimOwned, nil + } + switch turn.Status { + case TurnStatusCompleted: + return turn, TurnClaimCompleted, nil + case TurnStatusFailed, TurnStatusCancelled: + if turn.AssistantMessageID != "" { + turn.Status = TurnStatusCompleted + turn.Error = "" + turn.UpdatedAt = truncateMilli(time.Now().UTC()) + s.turns[turn.TurnID] = turn + return turn, TurnClaimCompleted, nil + } + turn.Status = TurnStatusRunning + turn.Attempt++ + turn.OwnerID = initial.OwnerID + turn.Error = "" + turn.UpdatedAt = truncateMilli(time.Now().UTC()) + s.turns[turn.TurnID] = turn + return turn, TurnClaimOwned, nil + default: + return turn, TurnClaimInProgress, nil + } +} + +func recoverable(turn TurnRecord) bool { + switch turn.Status { + case TurnStatusAccepted, TurnStatusRunning, TurnStatusPartial: + return true + default: + return false + } +} + +func (s *memorySessionStore) RecoverTurns(_ context.Context, ownerID string) error { + if ownerID == "" { + return fmt.Errorf("sessionstore: recovery owner ID is required") + } + s.mu.Lock() + defer s.mu.Unlock() + now := truncateMilli(time.Now().UTC()) + for id, turn := range s.turns { + if recoverable(turn) && turn.OwnerID != ownerID { + turn.Status = TurnStatusFailed + turn.Error = "recovered after process restart" + turn.UpdatedAt = now + s.turns[id] = turn + } + } + return nil +} + +func (s *memorySessionStore) GetTurn(_ context.Context, turnID string) (TurnRecord, bool, error) { + s.mu.Lock() + defer s.mu.Unlock() + turn, ok := s.turns[turnID] + return turn, ok, nil +} + +func (s *memorySessionStore) RecentTurns(_ context.Context, sessionID string, n int) ([]TurnRecord, error) { + if n <= 0 { + return []TurnRecord{}, nil + } + n = min(n, 500) + s.mu.Lock() + defer s.mu.Unlock() + var out []TurnRecord + for _, turn := range s.turns { + if turn.SessionID == sessionID { + out = append(out, turn) + } + } + slices.SortFunc(out, func(a, b TurnRecord) int { return a.CreatedAt.Compare(b.CreatedAt) }) + return append([]TurnRecord{}, out[max(len(out)-n, 0):]...), nil +} + +func (s *memorySessionStore) SaveTurn(_ context.Context, turn TurnRecord) error { + if turn.TurnID == "" { + return fmt.Errorf("sessionstore: turn ID is required") + } + s.mu.Lock() + defer s.mu.Unlock() + current, ok := s.turns[turn.TurnID] + if !ok { + return fmt.Errorf("sessionstore: save turn: turn not found") + } + if current.Attempt != turn.Attempt || current.OwnerID != turn.OwnerID { + return fmt.Errorf("%w: %s", ErrTurnOwnershipLost, turn.TurnID) + } + if turn.UpdatedAt.IsZero() { + turn.UpdatedAt = time.Now().UTC() + } + stored, err := storedTurn(turn) + if err != nil { + return err + } + s.turns[turn.TurnID] = stored + return nil +} + +func (s *memorySessionStore) ListRecoverableTurns(_ context.Context) ([]TurnRecord, error) { + s.mu.Lock() + defer s.mu.Unlock() + var out []TurnRecord + for _, turn := range s.turns { + if recoverable(turn) { + out = append(out, turn) + } + } + slices.SortFunc(out, func(a, b TurnRecord) int { return a.UpdatedAt.Compare(b.UpdatedAt) }) + return out, nil +} diff --git a/internal/gateway/session_store_postgres_test.go b/internal/gateway/session_store_postgres_test.go index bf8903e00..62661779c 100644 --- a/internal/gateway/session_store_postgres_test.go +++ b/internal/gateway/session_store_postgres_test.go @@ -23,7 +23,14 @@ func TestMain(m *testing.M) { // applied and registers pool cleanup. func newPostgresPool(t *testing.T) *pgxpool.Pool { t.Helper() - pool, err := postgres.Open(t.Context(), pgtest.URL(t)) + return openPostgresPoolAt(t, pgtest.URL(t)) +} + +// openPostgresPoolAt opens a migrated pool on url, so a test can reopen the +// same database through a second pool. +func openPostgresPoolAt(t *testing.T, url string) *pgxpool.Pool { + t.Helper() + pool, err := postgres.Open(t.Context(), url) if err != nil { t.Fatalf("postgres.Open: %v", err) } @@ -42,6 +49,18 @@ func newPostgresStore(t *testing.T) SessionStore { return NewPostgresSessionStore(newPostgresPool(t)) } +// openPostgresStoreAt returns a SessionStore over its own pool on url. +func openPostgresStoreAt(t *testing.T, url string) SessionStore { + t.Helper() + return NewPostgresSessionStore(openPostgresPoolAt(t, url)) +} + +// TestSessionStoreConformanceMemory runs the shared SessionStore contract +// against the in-memory implementation. +func TestSessionStoreConformanceMemory(t *testing.T) { + runSessionStoreSuite(t, func(*testing.T) SessionStore { return NewSessionStoreMemory() }) +} + // TestSessionStoreConformancePostgres runs the shared SessionStore contract // against the PostgreSQL implementation. func TestSessionStoreConformancePostgres(t *testing.T) { diff --git a/internal/gateway/session_store_sqlite.go b/internal/gateway/session_store_sqlite.go deleted file mode 100644 index 47e8f959c..000000000 --- a/internal/gateway/session_store_sqlite.go +++ /dev/null @@ -1,1112 +0,0 @@ -package gateway - -import ( - "context" - "database/sql" - "encoding/json" - "errors" - "fmt" - "os" - "path/filepath" - "strings" - "sync" - "time" - - _ "modernc.org/sqlite" - - "github.com/samcharles93/archie-core/internal/domain/messaging" -) - -// ── SQLite implementation ─────────────────────────────────────────────────── -// -// sqliteSessionStore is the durable, transactional SessionStore described by -// docs/architecture/messaging-and-work-intake.md. -// -// Schema: -// -// - sessions holds one row per SessionContext, round-tripping every field -// including ParentSessionID and BranchName. -// - messages holds one row per message, keyed by the application-generated -// canonical MessageID (session-scoped unique, not the table's rowid -- -// the integer rowid backs the FTS5 external-content index instead). -// - messages_fts is an external-content FTS5 index over (sender, text) -// only, kept in sync by AFTER INSERT/UPDATE/DELETE triggers on messages. -// Because the sync is driven by triggers on the table itself rather than -// application code, it cannot drift regardless of which Go method wrote -// the row. -type sqliteSessionStore struct { - db *sql.DB - // mu serializes every write (Save, Delete, message mutations) so the - // strictly-increasing per-session timestamp invariant holds under - // concurrent callers: assigning the next timestamp is a read-then-write - // over two statements, which needs an application-level lock even - // though SQLite itself serializes at the connection level. - mu sync.Mutex -} - -const sqliteSessionSchema = ` -CREATE TABLE IF NOT EXISTS sessions ( - session_id TEXT PRIMARY KEY, - platform TEXT NOT NULL DEFAULT '', - bot_user TEXT NOT NULL DEFAULT '', - channel_id TEXT NOT NULL DEFAULT '', - thread_id TEXT NOT NULL DEFAULT '', - title TEXT NOT NULL DEFAULT '', - parent_session_id TEXT NOT NULL DEFAULT '', - branch_name TEXT NOT NULL DEFAULT '', - created_at INTEGER NOT NULL DEFAULT 0, - last_active_at INTEGER NOT NULL DEFAULT 0 -); -CREATE INDEX IF NOT EXISTS idx_sessions_channel ON sessions(platform, channel_id); --- Ordering is by recency, which is last_active_at when set and created_at --- otherwise (see sessionRecencySQL). The index matches that expression so --- the newest-first listings do not sort at query time. -CREATE INDEX IF NOT EXISTS idx_sessions_recency - ON sessions(platform, channel_id, MAX(last_active_at, created_at) DESC); - -CREATE TABLE IF NOT EXISTS messages ( - id INTEGER PRIMARY KEY AUTOINCREMENT, - message_id TEXT NOT NULL, - session_id TEXT NOT NULL, - source_id TEXT NOT NULL DEFAULT '', - sender TEXT NOT NULL DEFAULT '', - sender_id TEXT NOT NULL DEFAULT '', - role TEXT NOT NULL DEFAULT '', - text TEXT NOT NULL DEFAULT '', - ts INTEGER NOT NULL, - UNIQUE(session_id, message_id) -); -CREATE INDEX IF NOT EXISTS idx_messages_session_ts ON messages(session_id, ts); - -CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5( - sender, - text, - content='messages', - content_rowid='id' -); - -CREATE TRIGGER IF NOT EXISTS messages_ai AFTER INSERT ON messages BEGIN - INSERT INTO messages_fts(rowid, sender, text) VALUES (new.id, new.sender, new.text); -END; -CREATE TRIGGER IF NOT EXISTS messages_ad AFTER DELETE ON messages BEGIN - INSERT INTO messages_fts(messages_fts, rowid, sender, text) VALUES('delete', old.id, old.sender, old.text); -END; -CREATE TRIGGER IF NOT EXISTS messages_au AFTER UPDATE ON messages BEGIN - INSERT INTO messages_fts(messages_fts, rowid, sender, text) VALUES('delete', old.id, old.sender, old.text); - INSERT INTO messages_fts(rowid, sender, text) VALUES (new.id, new.sender, new.text); -END; - -CREATE TABLE IF NOT EXISTS turns ( - turn_id TEXT PRIMARY KEY, - session_id TEXT NOT NULL, - source_id TEXT NOT NULL DEFAULT '', - status TEXT NOT NULL, - attempt INTEGER NOT NULL DEFAULT 0, - owner_id TEXT NOT NULL DEFAULT '', - input_message_id TEXT NOT NULL DEFAULT '', - assistant_message_id TEXT NOT NULL DEFAULT '', - partial_text TEXT NOT NULL DEFAULT '', - response_text TEXT NOT NULL DEFAULT '', - tool_calls TEXT NOT NULL DEFAULT '[]', - error TEXT NOT NULL DEFAULT '', - created_at INTEGER NOT NULL, - updated_at INTEGER NOT NULL -); -CREATE INDEX IF NOT EXISTS idx_turns_session_source ON turns(session_id, source_id); -CREATE INDEX IF NOT EXISTS idx_turns_status_updated ON turns(status, updated_at); -` - -// OpenSQLiteSessionStore opens (creating if needed) a SQLite-backed -// SessionStore. -func OpenSQLiteSessionStore(path string) (SessionStore, error) { - if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { - return nil, fmt.Errorf("sessionstore: mkdir: %w", err) - } - return openSQLiteSessionStore(sqliteSessionDSN(path)) -} - -func sqliteSessionDSN(path string) string { - separator := "?" - if strings.HasSuffix(path, "?") || strings.HasSuffix(path, "&") { - separator = "" - } else if strings.Contains(path, "?") { - separator = "&" - } - return path + separator + "_pragma=journal_mode(WAL)&_pragma=busy_timeout(5000)" -} - -// NewSQLiteSessionStoreMemory returns an in-memory SQLite SessionStore for -// tests. -func NewSQLiteSessionStoreMemory() (SessionStore, error) { - return openSQLiteSessionStore(":memory:") -} - -func openSQLiteSessionStore(dsn string) (SessionStore, error) { - db, err := sql.Open("sqlite", dsn) - if err != nil { - return nil, fmt.Errorf("sessionstore: open: %w", err) - } - // A second connection to an in-memory database is a distinct, empty - // database under modernc.org/sqlite, and even for the file-backed case - // this store's own mutex already serializes every operation -- so a - // pool beyond one connection buys nothing and risks the memory-mode - // footgun. Pin it to one. - db.SetMaxOpenConns(1) - - ctx := context.Background() - if _, err := db.ExecContext(ctx, sqliteSessionSchema); err != nil { - return nil, errors.Join(fmt.Errorf("sessionstore: init schema: %w", err), db.Close()) - } - // A database created before tool_calls existed has a turns table without - // it; CREATE TABLE IF NOT EXISTS above leaves an existing table alone, so - // the column is added here. The duplicate-column error is the documented - // way to detect "already migrated" with this driver -- there is no - // IF NOT EXISTS clause for ADD COLUMN. - if _, err := db.ExecContext(ctx, `ALTER TABLE turns ADD COLUMN tool_calls TEXT NOT NULL DEFAULT '[]'`); err != nil && - !strings.Contains(err.Error(), "duplicate column name") { - return nil, errors.Join(fmt.Errorf("sessionstore: migrate turns table: %w", err), db.Close()) - } - // A database created before the messaging migration has a messages - // table without the role column; CREATE TABLE IF NOT EXISTS above - // leaves an existing table alone, so the column is added here, with - // the same duplicate-column detection as the turns migration. - if _, err := db.ExecContext(ctx, `ALTER TABLE messages ADD COLUMN role TEXT NOT NULL DEFAULT ''`); err != nil && - !strings.Contains(err.Error(), "duplicate column name") { - return nil, errors.Join(fmt.Errorf("sessionstore: migrate messages table: %w", err), db.Close()) - } - // A database created before sender ids were persisted has a messages - // table without the sender_id column; same duplicate-column detection. - if _, err := db.ExecContext(ctx, `ALTER TABLE messages ADD COLUMN sender_id TEXT NOT NULL DEFAULT ''`); err != nil && - !strings.Contains(err.Error(), "duplicate column name") { - return nil, errors.Join(fmt.Errorf("sessionstore: migrate messages sender_id: %w", err), db.Close()) - } - // Backfill the role for rows written before it was persisted, using - // the same sender-equality the store boundary applies to new writes: - // a message sent by its session's bot identity is the assistant's. - if _, err := db.ExecContext(ctx, ` - UPDATE messages SET role = CASE - WHEN sender = (SELECT bot_user FROM sessions WHERE sessions.session_id = messages.session_id) - THEN 'assistant' ELSE 'user' - END WHERE role = ''`); err != nil { - return nil, errors.Join(fmt.Errorf("sessionstore: backfill message roles: %w", err), db.Close()) - } - if err := repairFutureMessageTimestamps(ctx, db, time.Now().UTC()); err != nil { - return nil, errors.Join(err, db.Close()) - } - return &sqliteSessionStore{db: db}, nil -} - -// repairFutureMessageTimestamps heals sessions poisoned by older versions -// that accepted a platform timestamp arbitrarily far ahead of the daemon's -// clock. Future rows retain their order and are rebased immediately after the -// session's last non-future row. With no earlier row, they end at now. A dense -// history can finish a few milliseconds beyond now, but never preserves the -// original hours- or days-long skew. -func repairFutureMessageTimestamps(ctx context.Context, db *sql.DB, now time.Time) error { - cutoff := now.UnixMilli() - _, err := db.ExecContext(ctx, ` - WITH future AS MATERIALIZED ( - SELECT m.id, - COALESCE( - (SELECT MAX(p.ts) FROM messages p - WHERE p.session_id = m.session_id AND p.ts <= ?), - ? - COUNT(*) OVER (PARTITION BY m.session_id) - ) + ROW_NUMBER() OVER ( - PARTITION BY m.session_id ORDER BY m.ts, m.id - ) AS repaired_ts - FROM messages m - WHERE m.ts > ? - ) - UPDATE messages - SET ts = (SELECT repaired_ts FROM future WHERE future.id = messages.id) - WHERE id IN (SELECT id FROM future) AND ts > ?`, - cutoff, cutoff, cutoff, cutoff) - if err != nil { - return fmt.Errorf("sessionstore: repair future message timestamps: %w", err) - } - return nil -} - -func (s *sqliteSessionStore) Close() error { - return s.db.Close() -} - -func (s *sqliteSessionStore) ClaimTurn(ctx context.Context, initial TurnRecord) (TurnRecord, TurnClaim, error) { - initial, initialToolCalls, err := prepareInitialTurn(initial, time.Now().UTC()) - if err != nil { - return TurnRecord{}, "", err - } - s.mu.Lock() - defer s.mu.Unlock() - - tx, err := s.db.BeginTx(ctx, nil) - if err != nil { - return TurnRecord{}, "", fmt.Errorf("sessionstore: claim turn: begin: %w", err) - } - defer func() { _ = tx.Rollback() }() - - // Claim by writing first. Under WAL, a transaction that reads and then - // upgrades to a writer can fail immediately with SQLITE_BUSY_SNAPSHOT; - // busy_timeout only waits for ordinary writer contention. INSERT ... ON - // CONFLICT acquires writer intent before any snapshot read, so concurrent - // claimers wait normally and the loser can inspect the committed turn. - inserted, err := insertInitialTurn(ctx, tx, initial, initialToolCalls) - if err != nil { - return TurnRecord{}, "", err - } - if inserted { - if err := tx.Commit(); err != nil { - return TurnRecord{}, "", fmt.Errorf("sessionstore: claim turn: commit: %w", err) - } - return initial, TurnClaimOwned, nil - } - - var turn TurnRecord - var createdMS, updatedMS int64 - var toolCallsRaw string - err = tx.QueryRowContext(ctx, ` - SELECT turn_id, session_id, source_id, status, attempt, owner_id, - input_message_id, assistant_message_id, partial_text, - response_text, tool_calls, error, created_at, updated_at - FROM turns WHERE turn_id = ?`, initial.TurnID).Scan( - &turn.TurnID, &turn.SessionID, &turn.SourceID, &turn.Status, &turn.Attempt, &turn.OwnerID, - &turn.InputMessageID, &turn.AssistantMessageID, &turn.PartialText, - &turn.ResponseText, &toolCallsRaw, &turn.Error, &createdMS, &updatedMS, - ) - if err != nil { - return TurnRecord{}, "", fmt.Errorf("sessionstore: read turn: %w", err) - } - turn.CreatedAt = time.UnixMilli(createdMS).UTC() - turn.UpdatedAt = time.UnixMilli(updatedMS).UTC() - if turn.ToolCalls, err = unmarshalToolCalls(toolCallsRaw); err != nil { - return TurnRecord{}, "", err - } - return claimExistingTurn(ctx, tx, turn, initial) -} - -func claimExistingTurn(ctx context.Context, tx *sql.Tx, turn, initial TurnRecord) (TurnRecord, TurnClaim, error) { - switch turn.Status { - case TurnStatusCompleted: - return turn, TurnClaimCompleted, nil - case TurnStatusAccepted, TurnStatusRunning, TurnStatusPartial: - return turn, TurnClaimInProgress, nil - case TurnStatusFailed, TurnStatusCancelled: - if turn.AssistantMessageID != "" { - result, err := tx.ExecContext(ctx, ` - UPDATE turns SET status = ?, error = ?, updated_at = ? - WHERE turn_id = ? AND attempt = ? AND owner_id = ?`, string(TurnStatusCompleted), "", - time.Now().UTC().UnixMilli(), turn.TurnID, turn.Attempt, turn.OwnerID) - if err != nil { - return TurnRecord{}, "", fmt.Errorf("sessionstore: finalize turn: %w", err) - } - if affected, err := result.RowsAffected(); err != nil || affected != 1 { - return TurnRecord{}, "", fmt.Errorf("%w: %s", ErrTurnOwnershipLost, turn.TurnID) - } - if err := tx.Commit(); err != nil { - return TurnRecord{}, "", fmt.Errorf("sessionstore: finalize turn: commit: %w", err) - } - turn.Status = TurnStatusCompleted - turn.Error = "" - return turn, TurnClaimCompleted, nil - } - oldOwner, oldAttempt := turn.OwnerID, turn.Attempt - turn.Status = TurnStatusRunning - turn.Attempt++ - turn.OwnerID = initial.OwnerID - turn.Error = "" - turn.UpdatedAt = time.Now().UTC() - result, err := tx.ExecContext(ctx, ` - UPDATE turns SET status = ?, attempt = ?, owner_id = ?, error = ?, updated_at = ? - WHERE turn_id = ? AND attempt = ? AND owner_id = ?`, string(turn.Status), turn.Attempt, turn.OwnerID, turn.Error, - turn.UpdatedAt.UnixMilli(), turn.TurnID, oldAttempt, oldOwner) - if err != nil { - return TurnRecord{}, "", fmt.Errorf("sessionstore: retry turn: %w", err) - } - if affected, err := result.RowsAffected(); err != nil || affected != 1 { - return TurnRecord{}, "", fmt.Errorf("%w: %s", ErrTurnOwnershipLost, turn.TurnID) - } - if err := tx.Commit(); err != nil { - return TurnRecord{}, "", fmt.Errorf("sessionstore: retry turn: commit: %w", err) - } - return turn, TurnClaimOwned, nil - default: - return turn, TurnClaimInProgress, nil - } -} - -func insertInitialTurn(ctx context.Context, tx *sql.Tx, initial TurnRecord, toolCalls string) (bool, error) { - result, err := tx.ExecContext(ctx, ` - INSERT INTO turns ( - turn_id, session_id, source_id, status, attempt, owner_id, - input_message_id, assistant_message_id, partial_text, - response_text, tool_calls, error, created_at, updated_at - ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?) - ON CONFLICT(turn_id) DO NOTHING`, turnValues(initial, toolCalls)...) - if err != nil { - return false, fmt.Errorf("sessionstore: claim turn: insert: %w", err) - } - affected, err := result.RowsAffected() - if err != nil { - return false, fmt.Errorf("sessionstore: claim turn: rows affected: %w", err) - } - return affected == 1, nil -} - -func prepareInitialTurn(initial TurnRecord, now time.Time) (TurnRecord, string, error) { - if initial.TurnID == "" { - return TurnRecord{}, "", fmt.Errorf("sessionstore: turn ID is required") - } - initial.Status = TurnStatusRunning - initial.Attempt = 1 - if initial.CreatedAt.IsZero() { - initial.CreatedAt = now - } - initial.UpdatedAt = now - toolCalls, err := marshalToolCalls(initial.ToolCalls) - return initial, toolCalls, err -} - -func (s *sqliteSessionStore) RecoverTurns(ctx context.Context, ownerID string) error { - if ownerID == "" { - return fmt.Errorf("sessionstore: recovery owner ID is required") - } - s.mu.Lock() - defer s.mu.Unlock() - _, err := s.db.ExecContext(ctx, ` - UPDATE turns - SET status = ?, error = ?, updated_at = ? - WHERE status IN (?, ?, ?) AND owner_id <> ?`, - string(TurnStatusFailed), "recovered after process restart", time.Now().UTC().UnixMilli(), - string(TurnStatusAccepted), string(TurnStatusRunning), string(TurnStatusPartial), ownerID) - if err != nil { - return fmt.Errorf("sessionstore: recover turns: %w", err) - } - return nil -} - -func (s *sqliteSessionStore) GetTurn(ctx context.Context, turnID string) (TurnRecord, bool, error) { - if turnID == "" { - return TurnRecord{}, false, nil - } - s.mu.Lock() - defer s.mu.Unlock() - var turn TurnRecord - var createdMS, updatedMS int64 - var toolCallsRaw string - err := s.db.QueryRowContext(ctx, ` - SELECT turn_id, session_id, source_id, status, attempt, owner_id, - input_message_id, assistant_message_id, partial_text, - response_text, tool_calls, error, created_at, updated_at - FROM turns WHERE turn_id = ?`, turnID).Scan( - &turn.TurnID, &turn.SessionID, &turn.SourceID, &turn.Status, &turn.Attempt, &turn.OwnerID, - &turn.InputMessageID, &turn.AssistantMessageID, &turn.PartialText, - &turn.ResponseText, &toolCallsRaw, &turn.Error, &createdMS, &updatedMS, - ) - if errors.Is(err, sql.ErrNoRows) { - return TurnRecord{}, false, nil - } - if err != nil { - return TurnRecord{}, false, fmt.Errorf("sessionstore: get turn: %w", err) - } - turn.CreatedAt = time.UnixMilli(createdMS).UTC() - turn.UpdatedAt = time.UnixMilli(updatedMS).UTC() - if turn.ToolCalls, err = unmarshalToolCalls(toolCallsRaw); err != nil { - return TurnRecord{}, false, err - } - return turn, true, nil -} - -func (s *sqliteSessionStore) RecentTurns(ctx context.Context, sessionID string, n int) ([]TurnRecord, error) { - if n <= 0 { - return []TurnRecord{}, nil - } - if n > 500 { - n = 500 - } - s.mu.Lock() - defer s.mu.Unlock() - rows, err := s.db.QueryContext(ctx, ` - SELECT turn_id, session_id, source_id, status, attempt, owner_id, - input_message_id, assistant_message_id, partial_text, - response_text, tool_calls, error, created_at, updated_at - FROM turns WHERE session_id = ? ORDER BY created_at DESC LIMIT ?`, sessionID, n) - if err != nil { - return nil, fmt.Errorf("sessionstore: recent turns: %w", err) - } - defer func() { _ = rows.Close() }() - turns := make([]TurnRecord, 0) - for rows.Next() { - var turn TurnRecord - var createdMS, updatedMS int64 - var raw string - if err := rows.Scan(&turn.TurnID, &turn.SessionID, &turn.SourceID, &turn.Status, &turn.Attempt, &turn.OwnerID, - &turn.InputMessageID, &turn.AssistantMessageID, &turn.PartialText, &turn.ResponseText, &raw, &turn.Error, - &createdMS, &updatedMS); err != nil { - return nil, fmt.Errorf("sessionstore: scan recent turn: %w", err) - } - turn.CreatedAt = time.UnixMilli(createdMS).UTC() - turn.UpdatedAt = time.UnixMilli(updatedMS).UTC() - if turn.ToolCalls, err = unmarshalToolCalls(raw); err != nil { - return nil, err - } - turns = append(turns, turn) - } - if err := rows.Err(); err != nil { - return nil, fmt.Errorf("sessionstore: recent turns: %w", err) - } - for left, right := 0, len(turns)-1; left < right; left, right = left+1, right-1 { - turns[left], turns[right] = turns[right], turns[left] - } - return turns, nil -} - -func (s *sqliteSessionStore) SaveTurn(ctx context.Context, turn TurnRecord) error { - if turn.TurnID == "" { - return fmt.Errorf("sessionstore: turn ID is required") - } - s.mu.Lock() - defer s.mu.Unlock() - var currentAttempt int - var currentOwner string - if err := s.db.QueryRowContext(ctx, - `SELECT attempt, owner_id FROM turns WHERE turn_id = ?`, turn.TurnID). - Scan(¤tAttempt, ¤tOwner); errors.Is(err, sql.ErrNoRows) { - return fmt.Errorf("sessionstore: save turn: turn not found") - } else if err != nil { - return fmt.Errorf("sessionstore: save turn: read: %w", err) - } - if currentAttempt != turn.Attempt || currentOwner != turn.OwnerID { - return fmt.Errorf("%w: %s", ErrTurnOwnershipLost, turn.TurnID) - } - if turn.UpdatedAt.IsZero() { - turn.UpdatedAt = time.Now().UTC() - } - toolCallsJSON, err := marshalToolCalls(turn.ToolCalls) - if err != nil { - return err - } - result, err := s.db.ExecContext(ctx, ` - UPDATE turns SET - session_id = ?, source_id = ?, status = ?, attempt = ?, owner_id = ?, - input_message_id = ?, assistant_message_id = ?, partial_text = ?, - response_text = ?, tool_calls = ?, error = ?, created_at = ?, updated_at = ? - WHERE turn_id = ? AND attempt = ? AND owner_id = ?`, - turn.SessionID, turn.SourceID, string(turn.Status), turn.Attempt, turn.OwnerID, - turn.InputMessageID, turn.AssistantMessageID, turn.PartialText, - turn.ResponseText, toolCallsJSON, turn.Error, turn.CreatedAt.UnixMilli(), turn.UpdatedAt.UnixMilli(), - turn.TurnID, turn.Attempt, turn.OwnerID) - if err != nil { - return fmt.Errorf("sessionstore: save turn: %w", err) - } - if affected, err := result.RowsAffected(); err != nil { - return fmt.Errorf("sessionstore: save turn: rows affected: %w", err) - } else if affected != 1 { - return fmt.Errorf("%w: %s", ErrTurnOwnershipLost, turn.TurnID) - } - return nil -} - -func (s *sqliteSessionStore) ListRecoverableTurns(ctx context.Context) ([]TurnRecord, error) { - s.mu.Lock() - defer s.mu.Unlock() - rows, err := s.db.QueryContext(ctx, ` - SELECT turn_id, session_id, source_id, status, attempt, owner_id, - input_message_id, assistant_message_id, partial_text, - response_text, tool_calls, error, created_at, updated_at - FROM turns WHERE status IN (?, ?, ?) ORDER BY updated_at ASC`, - string(TurnStatusAccepted), string(TurnStatusRunning), string(TurnStatusPartial)) - if err != nil { - return nil, fmt.Errorf("sessionstore: list recoverable turns: %w", err) - } - defer func() { _ = rows.Close() }() - var out []TurnRecord - for rows.Next() { - var turn TurnRecord - var createdMS, updatedMS int64 - var toolCallsRaw string - if err := rows.Scan( - &turn.TurnID, &turn.SessionID, &turn.SourceID, &turn.Status, &turn.Attempt, &turn.OwnerID, - &turn.InputMessageID, &turn.AssistantMessageID, &turn.PartialText, - &turn.ResponseText, &toolCallsRaw, &turn.Error, &createdMS, &updatedMS, - ); err != nil { - return nil, fmt.Errorf("sessionstore: scan recoverable turn: %w", err) - } - turn.CreatedAt = time.UnixMilli(createdMS).UTC() - turn.UpdatedAt = time.UnixMilli(updatedMS).UTC() - if turn.ToolCalls, err = unmarshalToolCalls(toolCallsRaw); err != nil { - return nil, err - } - out = append(out, turn) - } - if err := rows.Err(); err != nil { - return nil, fmt.Errorf("sessionstore: list recoverable turns: %w", err) - } - return out, nil -} - -func turnValues(turn TurnRecord, toolCallsJSON string) []any { - return []any{ - turn.TurnID, turn.SessionID, turn.SourceID, string(turn.Status), turn.Attempt, turn.OwnerID, - turn.InputMessageID, turn.AssistantMessageID, turn.PartialText, - turn.ResponseText, toolCallsJSON, turn.Error, turn.CreatedAt.UnixMilli(), turn.UpdatedAt.UnixMilli(), - } -} - -// marshalToolCalls encodes a turn's recorded tool activity for storage. An -// empty slice becomes "[]" rather than SQL NULL or the JSON "null" so an -// unmigrated-looking row (the column's own DEFAULT) and a turn that recorded -// no tool calls are indistinguishable in the database, and both round-trip -// through unmarshalToolCalls to a nil slice. -func marshalToolCalls(events []ToolCallEvent) (string, error) { - if len(events) == 0 { - return "[]", nil - } - encoded, err := json.Marshal(events) - if err != nil { - return "", fmt.Errorf("sessionstore: marshal tool calls: %w", err) - } - return string(encoded), nil -} - -// unmarshalToolCalls decodes tool activity persisted by marshalToolCalls. -func unmarshalToolCalls(raw string) ([]ToolCallEvent, error) { - if raw == "" || raw == "[]" { - return nil, nil - } - var events []ToolCallEvent - if err := json.Unmarshal([]byte(raw), &events); err != nil { - return nil, fmt.Errorf("sessionstore: unmarshal tool calls: %w", err) - } - return events, nil -} - -// ── Sessions ──────────────────────────────────────────────────────────────── - -func (s *sqliteSessionStore) Save(ctx context.Context, sc SessionContext) error { - s.mu.Lock() - defer s.mu.Unlock() - - _, err := s.db.ExecContext(ctx, ` - INSERT INTO sessions (session_id, platform, bot_user, channel_id, thread_id, - title, parent_session_id, branch_name, created_at, last_active_at) - VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?) - ON CONFLICT(session_id) DO UPDATE SET - platform = excluded.platform, - bot_user = excluded.bot_user, - channel_id = excluded.channel_id, - thread_id = excluded.thread_id, - title = excluded.title, - parent_session_id = excluded.parent_session_id, - branch_name = excluded.branch_name, - created_at = excluded.created_at, - last_active_at = excluded.last_active_at`, - sc.SessionID, sc.Source.Platform, sc.Source.BotUser, sc.Source.ChannelID, sc.Source.ThreadID, - sc.Title, sc.ParentSessionID, sc.BranchName, sc.CreatedAt.UnixMilli(), sc.LastActiveAt.UnixMilli()) - if err != nil { - return fmt.Errorf("sessionstore: save: %w", err) - } - return nil -} - -func (s *sqliteSessionStore) Get(ctx context.Context, sessionID string) (*SessionContext, error) { - row := s.db.QueryRowContext(ctx, sessionSelect+` WHERE session_id = ?`, sessionID) - sc, err := scanSession(row) - if errors.Is(err, sql.ErrNoRows) { - return nil, nil - } - if err != nil { - return nil, fmt.Errorf("sessionstore: get: %w", err) - } - return sc, nil -} - -func (s *sqliteSessionStore) GetByChannel(ctx context.Context, platform, channelID string) ([]SessionContext, error) { - rows, err := s.db.QueryContext(ctx, - sessionSelect+` WHERE platform = ? AND channel_id = ? ORDER BY `+sessionRecencySQL+` DESC`, - platform, channelID) - if err != nil { - return nil, fmt.Errorf("sessionstore: get by channel: %w", err) - } - return scanSessions(rows) -} - -func (s *sqliteSessionStore) Delete(ctx context.Context, sessionID string) error { - s.mu.Lock() - defer s.mu.Unlock() - - tx, err := s.db.BeginTx(ctx, nil) - if err != nil { - return fmt.Errorf("sessionstore: delete: begin: %w", err) - } - defer func() { _ = tx.Rollback() }() - - if _, err := tx.ExecContext(ctx, `DELETE FROM messages WHERE session_id = ?`, sessionID); err != nil { - return fmt.Errorf("sessionstore: delete messages: %w", err) - } - if _, err := tx.ExecContext(ctx, `DELETE FROM turns WHERE session_id = ?`, sessionID); err != nil { - return fmt.Errorf("sessionstore: delete turns: %w", err) - } - if _, err := tx.ExecContext(ctx, `DELETE FROM sessions WHERE session_id = ?`, sessionID); err != nil { - return fmt.Errorf("sessionstore: delete session: %w", err) - } - if err := tx.Commit(); err != nil { - return fmt.Errorf("sessionstore: delete: commit: %w", err) - } - return nil -} - -func (s *sqliteSessionStore) Touch(ctx context.Context, sessionID string) error { - s.mu.Lock() - defer s.mu.Unlock() - - _, err := s.db.ExecContext(ctx, - `UPDATE sessions SET last_active_at = ? WHERE session_id = ?`, - time.Now().UTC().UnixMilli(), sessionID) - if err != nil { - return fmt.Errorf("sessionstore: touch: %w", err) - } - return nil -} - -func (s *sqliteSessionStore) List(ctx context.Context) ([]SessionContext, error) { - rows, err := s.db.QueryContext(ctx, sessionSelect+` ORDER BY `+sessionRecencySQL+` DESC`) - if err != nil { - return nil, fmt.Errorf("sessionstore: list: %w", err) - } - return scanSessions(rows) -} - -// sessionRecencySQL is a session's recency: LastActiveAt when it has been -// set, CreatedAt otherwise. -const sessionRecencySQL = `MAX(last_active_at, created_at)` - -const sessionSelect = ` - SELECT session_id, platform, bot_user, channel_id, thread_id, - title, parent_session_id, branch_name, created_at, last_active_at - FROM sessions` - -// rowScanner is satisfied by both *sql.Row and *sql.Rows, letting scanSession -// serve single-row and multi-row queries alike. -type rowScanner interface { - Scan(dest ...any) error -} - -func scanSession(row rowScanner) (*SessionContext, error) { - var ( - sc SessionContext - createdAt, lastActive int64 - ) - err := row.Scan(&sc.SessionID, &sc.Source.Platform, &sc.Source.BotUser, &sc.Source.ChannelID, - &sc.Source.ThreadID, &sc.Title, &sc.ParentSessionID, &sc.BranchName, &createdAt, &lastActive) - if err != nil { - return nil, err - } - sc.CreatedAt = time.UnixMilli(createdAt).UTC() - sc.LastActiveAt = time.UnixMilli(lastActive).UTC() - return &sc, nil -} - -func scanSessions(rows *sql.Rows) ([]SessionContext, error) { - defer func() { _ = rows.Close() }() - var out []SessionContext - for rows.Next() { - sc, err := scanSession(rows) - if err != nil { - return nil, fmt.Errorf("sessionstore: scan session: %w", err) - } - out = append(out, *sc) - } - if err := rows.Err(); err != nil { - return nil, fmt.Errorf("sessionstore: scan sessions: %w", err) - } - return out, nil -} - -// ── Messages ───────────────────────────────────────────────────────────────── - -// execer is satisfied by both *sql.DB and *sql.Tx, so message-writing -// helpers work identically for a single-statement call (SaveMessage) and a -// multi-statement transaction (SaveMessages, ReplaceMessages). -type execer interface { - ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error) - QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row -} - -func (s *sqliteSessionStore) SaveMessage(ctx context.Context, sessionID string, msg messaging.Message) error { - s.mu.Lock() - defer s.mu.Unlock() - _, err := saveMessage(ctx, s.db, sessionID, msg) - return err -} - -// saveMessage persists one message and reports the canonical ID it was -// stored under (or was already stored under, for a redelivered message). -// -// A message carrying a canonical ID keeps it -- re-saving history read back -// must not mint a new identity. An existing record with that ID is left -// untouched: stored messages are immutable, so a redelivered edit is a -// no-op rather than an overwrite. -func saveMessage(ctx context.Context, ex execer, sessionID string, msg messaging.Message) (string, error) { - return saveMessageAt(ctx, ex, sessionID, msg, true) -} - -// saveMessageAt writes a message, optionally without the monotonic clamp. -// The clamp belongs to the append path, not to a caller rewriting history and -// placing records deliberately. -func saveMessageAt(ctx context.Context, ex execer, sessionID string, msg messaging.Message, clamp bool) (string, error) { - id := string(msg.ID) - legacyID := "" - if msg.SourceID == "" { - if id == "" { - id = newMessageID(sessionID, "") - } - } else { - currentID, compatibleLegacyID := canonicalMessageIDs(sessionID, msg.SourceID) - if id == "" { - id = currentID - } - // TurnRunner supplies the current canonical ID before calling the - // store. Still check the compatible legacy identity: a crash can - // leave the old message durable before its turn record names it. - if id == currentID { - legacyID = compatibleLegacyID - } - } - // An empty Role means "user": producers set RoleAssistant explicitly - // (see TurnRunner.generateAndComplete), and pre-migration rows are - // backfilled at open, so only a hand-built record arrives without one. - role := string(msg.Role) - if role == "" { - role = string(messaging.RoleUser) - } - if legacyID != "" { - var existingID string - err := ex.QueryRowContext(ctx, - `SELECT message_id FROM messages WHERE session_id = ? AND message_id = ?`, - sessionID, legacyID).Scan(&existingID) - switch { - case err == nil: - return existingID, nil - case !errors.Is(err, sql.ErrNoRows): - return "", fmt.Errorf("sessionstore: read legacy message identity: %w", err) - } - } - at := stamp(msg) - if clamp { - _, err := ex.ExecContext(ctx, ` - INSERT INTO messages (message_id, session_id, source_id, sender, sender_id, role, text, ts) - VALUES (?, ?, ?, ?, ?, ?, ?, ( - SELECT CASE - WHEN MAX(ts) IS NOT NULL AND MAX(ts) >= ? THEN MAX(ts) + 1 - ELSE ? - END - FROM messages WHERE session_id = ? - )) - ON CONFLICT(session_id, message_id) DO NOTHING`, - id, sessionID, msg.SourceID, msg.Sender, msg.SenderID, role, msg.Text, - at.UnixMilli(), at.UnixMilli(), sessionID) - if err != nil { - return "", fmt.Errorf("sessionstore: save message: %w", err) - } - return id, nil - } - - var exists int - err := ex.QueryRowContext(ctx, - `SELECT 1 FROM messages WHERE session_id = ? AND message_id = ?`, sessionID, id).Scan(&exists) - switch { - case err == nil: - return id, nil - case !errors.Is(err, sql.ErrNoRows): - return "", fmt.Errorf("sessionstore: read existing message: %w", err) - } - - _, err = ex.ExecContext(ctx, ` - INSERT INTO messages (message_id, session_id, source_id, sender, sender_id, role, text, ts) - VALUES (?, ?, ?, ?, ?, ?, ?, ?)`, - id, sessionID, msg.SourceID, msg.Sender, msg.SenderID, role, msg.Text, at.UnixMilli()) - if err != nil { - return "", fmt.Errorf("sessionstore: save message: %w", err) - } - return id, nil -} - -func (s *sqliteSessionStore) SaveMessages(ctx context.Context, sessionID string, msgs []messaging.Message) error { - s.mu.Lock() - defer s.mu.Unlock() - - tx, err := s.db.BeginTx(ctx, nil) - if err != nil { - return fmt.Errorf("sessionstore: save messages: begin: %w", err) - } - defer func() { _ = tx.Rollback() }() - - // Each message gets its own time-ordered ID, so a bulk save appends to - // whatever the session already holds instead of overwriting from zero. - for _, msg := range msgs { - if _, err := saveMessage(ctx, tx, sessionID, msg); err != nil { - return fmt.Errorf("sessionstore: save messages: %w", err) - } - } - if err := tx.Commit(); err != nil { - return fmt.Errorf("sessionstore: save messages: commit: %w", err) - } - return nil -} - -// ReplaceMessages writes msgs and removes exactly the messages named by -// superseded, atomically: both happen inside one transaction, so a caller -// either sees the old history or the new one, never an in-between state. -// -// Only the named messages are removed. Deleting the complement of msgs swept -// up anything saved since the caller read the history -- a chat turn arriving -// mid-compression was destroyed without ever being read. -// -// A replacement message that carries a canonical ID lands on the same row it -// already occupied (saveMessage's immutability no-op), so an ID in both lists -// is kept. -func (s *sqliteSessionStore) ReplaceMessages( - ctx context.Context, - sessionID string, - msgs []messaging.Message, - superseded []string, -) error { - s.mu.Lock() - defer s.mu.Unlock() - - tx, err := s.db.BeginTx(ctx, nil) - if err != nil { - return fmt.Errorf("sessionstore: replace messages: begin: %w", err) - } - defer func() { _ = tx.Rollback() }() - - survivors := make(map[string]struct{}, len(msgs)) - for _, msg := range msgs { - // No clamp: the caller has already decided where each record belongs. - id, err := saveMessageAt(ctx, tx, sessionID, msg, false) - if err != nil { - return fmt.Errorf("sessionstore: replace messages: %w", err) - } - survivors[id] = struct{}{} - } - - doomed := make([]any, 0, len(superseded)) - for _, id := range superseded { - if _, kept := survivors[id]; kept { - continue - } - doomed = append(doomed, id) - } - if len(doomed) > 0 { - placeholders := strings.TrimSuffix(strings.Repeat("?,", len(doomed)), ",") - query := `DELETE FROM messages WHERE session_id = ? AND message_id IN (` + placeholders + `)` - args := append([]any{sessionID}, doomed...) - if _, err := tx.ExecContext(ctx, query, args...); err != nil { - return fmt.Errorf("sessionstore: replace messages: delete old: %w", err) - } - } - - if err := tx.Commit(); err != nil { - return fmt.Errorf("sessionstore: replace messages: commit: %w", err) - } - return nil -} - -func (s *sqliteSessionStore) FindPriorReply(ctx context.Context, sessionID, sourceID, identity string) (string, error) { - if sourceID == "" { - return "", nil - } - s.mu.Lock() - defer s.mu.Unlock() - - currentID, legacyID := canonicalMessageIDs(sessionID, sourceID) - var ts int64 - err := s.db.QueryRowContext(ctx, ` - SELECT ts FROM messages - WHERE session_id = ? AND message_id IN (?, ?) - ORDER BY CASE WHEN message_id = ? THEN 0 ELSE 1 END - LIMIT 1`, sessionID, currentID, legacyID, legacyID).Scan(&ts) - if errors.Is(err, sql.ErrNoRows) { - return "", nil - } - if err != nil { - return "", fmt.Errorf("sessionstore: find source message: %w", err) - } - var sender, text string - err = s.db.QueryRowContext(ctx, ` - SELECT sender, text FROM messages - WHERE session_id = ? AND ts > ? ORDER BY ts ASC LIMIT 1`, sessionID, ts). - Scan(&sender, &text) - if errors.Is(err, sql.ErrNoRows) { - return "", nil - } - if err != nil { - return "", fmt.Errorf("sessionstore: find prior reply: %w", err) - } - if sender != identity || isCompressionSummary(text) { - return "", nil - } - return text, nil -} - -func (s *sqliteSessionStore) RecentMessages(ctx context.Context, sessionID string, n int) ([]messaging.Message, error) { - if n <= 0 { - return nil, nil - } - // The conversation address is resolved from the owning session, not - // stored per message: a LEFT JOIN keeps orphaned rows readable exactly - // as before, with an empty address. - rows, err := s.db.QueryContext(ctx, ` - SELECT m.message_id, m.source_id, m.sender, m.sender_id, m.role, m.text, m.ts, - COALESCE(s.channel_id, ''), COALESCE(s.thread_id, '') - FROM ( - SELECT message_id, source_id, sender, sender_id, role, text, ts, session_id FROM messages - WHERE session_id = ? ORDER BY ts DESC LIMIT ? - ) m LEFT JOIN sessions s ON s.session_id = m.session_id - ORDER BY m.ts ASC`, sessionID, n) - if err != nil { - return nil, fmt.Errorf("sessionstore: recent messages: %w", err) - } - return scanMessages(rows) -} - -func (s *sqliteSessionStore) DeleteRecentMessages(ctx context.Context, sessionID string, n int) (int, error) { - s.mu.Lock() - defer s.mu.Unlock() - if n <= 0 { - return 0, nil - } - - res, err := s.db.ExecContext(ctx, ` - DELETE FROM messages WHERE id IN ( - SELECT id FROM messages WHERE session_id = ? ORDER BY ts DESC LIMIT ? - )`, sessionID, n) - if err != nil { - return 0, fmt.Errorf("sessionstore: delete recent messages: %w", err) - } - deleted, err := res.RowsAffected() - if err != nil { - return 0, fmt.Errorf("sessionstore: delete recent messages: rows affected: %w", err) - } - return int(deleted), nil -} - -func (s *sqliteSessionStore) MessageCount(ctx context.Context, sessionID string) (int, error) { - var n int - err := s.db.QueryRowContext(ctx, - `SELECT COUNT(*) FROM messages WHERE session_id = ?`, sessionID).Scan(&n) - if err != nil { - return 0, fmt.Errorf("sessionstore: message count: %w", err) - } - return n, nil -} - -// scanMessages scans rows shaped (message_id, source_id, sender, sender_id, -// role, text, ts, channel_id, thread_id). Both the history reads and -// SearchMessages select that column order, so they share one scanner. -func scanMessages(rows *sql.Rows) ([]messaging.Message, error) { - defer func() { _ = rows.Close() }() - var out []messaging.Message - for rows.Next() { - var ( - msg messaging.Message - id string - role string - ts int64 - ) - if err := rows.Scan(&id, &msg.SourceID, &msg.Sender, &msg.SenderID, &role, &msg.Text, &ts, - &msg.ConversationID.ChannelID, &msg.ConversationID.ThreadID); err != nil { - return nil, fmt.Errorf("sessionstore: scan message: %w", err) - } - msg.ID = messaging.MessageID(id) - msg.Role = messaging.Role(role) - msg.At = time.UnixMilli(ts).UTC() - out = append(out, msg) - } - if err := rows.Err(); err != nil { - return nil, fmt.Errorf("sessionstore: scan messages: %w", err) - } - return out, nil -} - -// SearchMessages runs an FTS5 search over the session's entire message -// history, matching message text and sender only -- ts and other metadata -// are not part of the indexed content, so a query like "2026" cannot match -// every message via its timestamp. An empty or whitespace-only query -// returns an empty page without touching the database. -// -// SQLite gives an exact total match count, so MessagePage.Truncated is always -// false. -func (s *sqliteSessionStore) SearchMessages(ctx context.Context, sessionID string, q MessageQuery) (MessagePage, error) { - query := strings.TrimSpace(q.Query) - if query == "" { - return MessagePage{}, nil - } - if len(query) > MaxMessageSearchQueryBytes { - return MessagePage{}, fmt.Errorf("sessionstore: search query exceeds %d bytes", MaxMessageSearchQueryBytes) - } - if terms := len(strings.Fields(query)); terms > MaxMessageSearchQueryTerms { - return MessagePage{}, fmt.Errorf("sessionstore: search query exceeds %d terms", MaxMessageSearchQueryTerms) - } - limit := q.Limit - if limit <= 0 { - limit = DefaultMessagePageSize - } - limit = min(limit, MaxMessagePageSize) - offset := max(q.Offset, 0) - - match := ftsMatchQuery(query) - - var total int - err := s.db.QueryRowContext(ctx, ` - SELECT COUNT(*) FROM messages_fts - JOIN messages m ON m.id = messages_fts.rowid - WHERE messages_fts MATCH ? AND m.session_id = ?`, match, sessionID).Scan(&total) - if err != nil { - return MessagePage{}, fmt.Errorf("sessionstore: search messages: count: %w", err) - } - if offset >= total { - return MessagePage{}, nil - } - - rows, err := s.db.QueryContext(ctx, ` - SELECT m.message_id, m.source_id, m.sender, m.sender_id, m.role, m.text, m.ts, - COALESCE(s.channel_id, ''), COALESCE(s.thread_id, '') - FROM messages_fts - JOIN messages m ON m.id = messages_fts.rowid - LEFT JOIN sessions s ON s.session_id = m.session_id - WHERE messages_fts MATCH ? AND m.session_id = ? - ORDER BY bm25(messages_fts) ASC - LIMIT ? OFFSET ?`, match, sessionID, limit, offset) - if err != nil { - return MessagePage{}, fmt.Errorf("sessionstore: search messages: %w", err) - } - msgs, err := scanMessages(rows) - if err != nil { - return MessagePage{}, err - } - - next := offset + len(msgs) - return MessagePage{ - Messages: msgs, - NextOffset: next, - HasMore: next < total, - Truncated: false, - }, nil -} - -// ftsMatchQuery turns free text into an FTS5 MATCH expression requiring -// every term to be present. Each term is wrapped as a quoted phrase -- -// doubling any embedded quote to escape it -- so user input can never be -// interpreted as FTS5 query syntax (column filters, NEAR, boolean -// operators); every token is a literal string to match, joined with an -// explicit AND. -func ftsMatchQuery(query string) string { - fields := strings.Fields(query) - terms := make([]string, 0, len(fields)) - for _, f := range fields { - escaped := strings.ReplaceAll(f, `"`, `""`) - terms = append(terms, `"`+escaped+`"`) - } - return strings.Join(terms, " AND ") -} diff --git a/internal/gateway/session_store_sqlite_claimturn_race_test.go b/internal/gateway/session_store_sqlite_claimturn_race_test.go deleted file mode 100644 index c26cdccd1..000000000 --- a/internal/gateway/session_store_sqlite_claimturn_race_test.go +++ /dev/null @@ -1,102 +0,0 @@ -package gateway - -import ( - "context" - "fmt" - "path/filepath" - "sync" - "testing" - "time" -) - -// TestClaimTurnConcurrentInsertRaceResolvesToOneOwner verifies that ordinary -// contention between processes sharing the session database is resolved by -// ClaimTurn itself. Callers must not need to recognize and retry SQLite's -// SQLITE_BUSY or SQLITE_BUSY_SNAPSHOT implementation details. -// -// Two invariants must hold under contention: every ClaimTurn call returns -// without error, and EXACTLY ONE of the racers ends up TurnClaimOwned while -// the other observes the committed row and returns a non-owning claim. -// The second invariant matters more than the first: a bug that returns -// TurnClaimOwned to both racers means two archied processes drive the same -// turn to completion, and the assistant reply gets emitted twice to the -// chat. The first invariant alone would not catch that. -// -// A single sqliteSessionStore instance cannot exhibit any of this: its own -// mutex serializes every ClaimTurn call against that instance's connection, -// so this uses two separate store instances (two connections, two mutexes) -// against the same file-backed database -- the real-world shape of the -// scenario (two archied/worker processes or connections sharing one session -// DB). -func TestClaimTurnConcurrentInsertRaceResolvesToOneOwner(t *testing.T) { - path := filepath.Join(t.TempDir(), "sessions.db") - - const stores = 2 - const trials = 100 - - openers := make([]TurnLedger, stores) - for i := range openers { - store, err := OpenSQLiteSessionStore(path) - if err != nil { - t.Fatalf("OpenSQLiteSessionStore[%d]: %v", i, err) - } - closer, ok := store.(interface{ Close() error }) - if !ok { - t.Fatalf("store[%d] is %T, want a Close() error", i, store) - } - t.Cleanup(func() { _ = closer.Close() }) - ledger, ok := store.(TurnLedger) - if !ok { - t.Fatalf("store[%d] is %T, want TurnLedger", i, store) - } - openers[i] = ledger - } - - ctx := context.Background() - now := time.UnixMilli(1000).UTC() - - // Each trial races the two independent stores over one turn ID, then waits - // before starting the next trial. This isolates the same-turn claim race - // from unrelated 100-way global writer contention. - for trial := range trials { - turnID := fmt.Sprintf("race-turn-%d", trial) - initial := TurnRecord{ - TurnID: turnID, - SessionID: "race-session", - SourceID: turnID, - Status: TurnStatusAccepted, - CreatedAt: now, - UpdatedAt: now, - } - errs := make([]error, stores) - claims := make([]TurnClaim, stores) - var wg sync.WaitGroup - var start sync.WaitGroup - start.Add(1) - for i := range stores { - wg.Add(1) - go func(i int) { - defer wg.Done() - start.Wait() - _, claims[i], errs[i] = openers[i].ClaimTurn(ctx, initial) - }(i) - } - start.Done() - wg.Wait() - - for i, err := range errs { - if err != nil { - t.Fatalf("trial %d, store %d: ClaimTurn() unexpected error = %v", trial, i, err) - } - } - owners := 0 - for _, c := range claims { - if c == TurnClaimOwned { - owners++ - } - } - if owners != 1 { - t.Fatalf("trial %d: expected exactly one TurnClaimOwned across %d racers, got %d (claims=%v)", trial, stores, owners, claims) - } - } -} diff --git a/internal/gateway/session_store_sqlite_conformance_test.go b/internal/gateway/session_store_sqlite_conformance_test.go deleted file mode 100644 index e0cfa8ad2..000000000 --- a/internal/gateway/session_store_sqlite_conformance_test.go +++ /dev/null @@ -1,15 +0,0 @@ -package gateway - -import "testing" - -// TestSessionStoreConformanceSQLite runs the shared SessionStore contract -// against the SQLite implementation. -func TestSessionStoreConformanceSQLite(t *testing.T) { - runSessionStoreSuite(t, func(t *testing.T) SessionStore { - s, err := NewSQLiteSessionStoreMemory() - if err != nil { - t.Fatalf("NewSQLiteSessionStoreMemory: %v", err) - } - return s - }) -} diff --git a/internal/gateway/session_store_sqlite_test.go b/internal/gateway/session_store_sqlite_test.go deleted file mode 100644 index ad8500a7c..000000000 --- a/internal/gateway/session_store_sqlite_test.go +++ /dev/null @@ -1,1365 +0,0 @@ -package gateway - -import ( - "context" - "database/sql" - "fmt" - "path/filepath" - "strings" - "sync" - "testing" - "time" - - "github.com/google/uuid" - - "github.com/samcharles93/archie-core/internal/domain/messaging" -) - -func newTestSQLiteStore(t *testing.T) SessionStore { - t.Helper() - st, err := NewSQLiteSessionStoreMemory() - if err != nil { - t.Fatalf("NewSQLiteSessionStoreMemory: %v", err) - } - t.Cleanup(func() { _ = st.Close() }) - return st -} - -func sqliteBase() time.Time { return time.Date(2026, 8, 3, 12, 0, 0, 0, time.UTC) } - -func TestSQLiteSessionStoreRecentTurnsReturnsReplayableToolHistory(t *testing.T) { - st := newTestSQLiteStore(t) - ledger, ok := st.(TurnLedger) - if !ok { - t.Fatalf("store is %T, want TurnLedger", st) - } - turn, claim, err := ledger.ClaimTurn(t.Context(), TurnRecord{ - TurnID: "turn-history", SessionID: "session-history", SourceID: "source-history", OwnerID: "owner", - ToolCalls: []ToolCallEvent{{Name: "shell", Output: "exit 0"}}, - }) - if err != nil || claim != TurnClaimOwned { - t.Fatalf("ClaimTurn() = %#v, %v, %v", turn, claim, err) - } - turn.Status = TurnStatusCompleted - turn.ResponseText = "answer" - turn.UpdatedAt = time.Now().UTC() - if err := ledger.SaveTurn(t.Context(), turn); err != nil { - t.Fatalf("SaveTurn() error = %v", err) - } - history, ok := st.(TurnHistory) - if !ok { - t.Fatalf("store is %T, want TurnHistory", st) - } - got, err := history.RecentTurns(t.Context(), "session-history", 10) - if err != nil || len(got) != 1 || len(got[0].ToolCalls) != 1 || got[0].ResponseText != "answer" { - t.Fatalf("RecentTurns() = %#v, %v; want one replayable turn", got, err) - } -} - -// TestOpenSQLiteSessionStoreMigratesPreExistingTurnsTable simulates a -// database created before the tool_calls column existed: CREATE TABLE IF NOT -// EXISTS leaves such a table alone, so opening it must add the column rather -// than fail or silently keep the old shape. -func TestOpenSQLiteSessionStoreMigratesPreExistingTurnsTable(t *testing.T) { - path := filepath.Join(t.TempDir(), "legacy.db") - raw, err := sql.Open("sqlite", sqliteSessionDSN(path)) - if err != nil { - t.Fatalf("sql.Open() error = %v", err) - } - if _, err := raw.ExecContext(t.Context(), `CREATE TABLE turns ( - turn_id TEXT PRIMARY KEY, - session_id TEXT NOT NULL, - source_id TEXT NOT NULL DEFAULT '', - status TEXT NOT NULL, - attempt INTEGER NOT NULL DEFAULT 0, - owner_id TEXT NOT NULL DEFAULT '', - input_message_id TEXT NOT NULL DEFAULT '', - assistant_message_id TEXT NOT NULL DEFAULT '', - partial_text TEXT NOT NULL DEFAULT '', - response_text TEXT NOT NULL DEFAULT '', - error TEXT NOT NULL DEFAULT '', - created_at INTEGER NOT NULL, - updated_at INTEGER NOT NULL - )`); err != nil { - t.Fatalf("create legacy turns table: %v", err) - } - if _, err := raw.ExecContext(t.Context(), `INSERT INTO turns ( - turn_id, session_id, source_id, status, attempt, owner_id, - input_message_id, assistant_message_id, partial_text, response_text, - error, created_at, updated_at - ) VALUES ('legacy-turn', 'legacy-session', 'legacy-source', 'completed', 1, 'owner', - '', 'assistant-1', '', 'legacy answer', '', 0, 0)`); err != nil { - t.Fatalf("insert legacy turn row: %v", err) - } - if err := raw.Close(); err != nil { - t.Fatalf("close legacy handle: %v", err) - } - - store, err := OpenSQLiteSessionStore(path) - if err != nil { - t.Fatalf("OpenSQLiteSessionStore() on legacy schema error = %v", err) - } - defer func() { _ = store.Close() }() - ledger, ok := store.(TurnLedger) - if !ok { - t.Fatalf("store is %T, want TurnLedger", store) - } - turn, ok, err := ledger.GetTurn(t.Context(), "legacy-turn") - if err != nil || !ok { - t.Fatalf("GetTurn() after migration = %#v, %v, %v; want the legacy row", turn, ok, err) - } - if turn.ResponseText != "legacy answer" || len(turn.ToolCalls) != 0 { - t.Fatalf("migrated turn = %#v, want legacy text with no tool calls", turn) - } - - // Reopening a second time must not fail on the "duplicate column name" - // the migration produces once the column already exists. - if err := store.Close(); err != nil { - t.Fatalf("Close() error = %v", err) - } - reopened, err := OpenSQLiteSessionStore(path) - if err != nil { - t.Fatalf("second OpenSQLiteSessionStore() error = %v", err) - } - _ = reopened.Close() -} - -func TestSQLiteSessionStoreRejectsExcessiveSearchQueries(t *testing.T) { - st := newTestSQLiteStore(t) - tests := []struct { - name string - query string - }{ - {name: "bytes", query: strings.Repeat("a", 4097)}, - {name: "terms", query: strings.Repeat("word ", 65)}, - } - for _, tt := range tests { - t.Run(tt.name, func(t *testing.T) { - if _, err := st.SearchMessages(t.Context(), "sess", MessageQuery{Query: tt.query}); err == nil { - t.Fatal("SearchMessages accepted an excessive query") - } - }) - } -} - -func TestOpenSQLiteSessionStoreAppliesPragmasWithTrailingQueryDelimiter(t *testing.T) { - st, err := OpenSQLiteSessionStore(filepath.Join(t.TempDir(), "messages.db") + "?") - if err != nil { - t.Fatal(err) - } - t.Cleanup(func() { _ = st.Close() }) - sqliteStore, ok := st.(*sqliteSessionStore) - if !ok { - t.Fatalf("store type = %T, want *sqliteSessionStore", st) - } - var mode string - if err := sqliteStore.db.QueryRowContext(t.Context(), `PRAGMA journal_mode`).Scan(&mode); err != nil { - t.Fatal(err) - } - if mode != "wal" { - t.Fatalf("journal_mode = %q, want wal", mode) - } -} - -func TestSQLiteSessionStoreThreadIDRoundTrip(t *testing.T) { - st := newTestSQLiteStore(t) - want := SessionContext{ - SessionID: "sess-thread", - Source: SessionSource{ - Platform: "telegram", BotUser: "archie", ChannelID: "-100123", ThreadID: "5", - }, - CreatedAt: sqliteBase(), LastActiveAt: sqliteBase(), - } - if err := st.Save(t.Context(), want); err != nil { - t.Fatal(err) - } - got, err := st.Get(t.Context(), want.SessionID) - if err != nil { - t.Fatal(err) - } - if got == nil || got.Source.ThreadID != want.Source.ThreadID || got.Source.ChannelID != want.Source.ChannelID { - t.Fatalf("Get = %+v, want thread %q channel %q", got, want.Source.ThreadID, want.Source.ChannelID) - } -} - -func TestMessageIDsAreUnique(t *testing.T) { - const count = 10_000 - seen := make(map[string]struct{}, count) - for range count { - id := newMessageID("sess", "") - if _, exists := seen[id]; exists { - t.Fatalf("duplicate message ID %q", id) - } - seen[id] = struct{}{} - } -} - -func TestCanonicalMessageIDComponentsAreInjectivelyEncoded(t *testing.T) { - t.Parallel() - - tests := []struct { - name string - firstSession string - firstSource string - secondSession string - secondSource string - }{ - { - name: "separator can occur in session", - firstSession: "a\x00b", - firstSource: "c", - secondSession: "a", - secondSource: "b\x00c", - }, - { - name: "empty session does not alias prefixed source", - firstSession: "", - firstSource: "a\x00b", - secondSession: "\x00a", - secondSource: "b", - }, - } - - for _, tc := range tests { - t.Run(tc.name, func(t *testing.T) { - first := CanonicalMessageID(tc.firstSession, tc.firstSource) - second := CanonicalMessageID(tc.secondSession, tc.secondSource) - if first == second { - t.Fatalf("CanonicalMessageID(%q, %q) = CanonicalMessageID(%q, %q) = %q", - tc.firstSession, tc.firstSource, tc.secondSession, tc.secondSource, first) - } - }) - } -} - -func TestSQLiteSessionStoreRecognisesLegacyCanonicalIDOnRedelivery(t *testing.T) { - t.Parallel() - - store := newTestSQLiteStore(t) - ctx := t.Context() - const ( - sessionID = "a\x00b" - sourceID = "source" - ) - legacyID := uuid.NewSHA1(messageIDNamespace, []byte(sessionID+"\x00"+sourceID)).String() - if _, err := sqliteStoreDB(t, store).ExecContext(ctx, ` - INSERT INTO messages (message_id, session_id, source_id, sender, text, ts) - VALUES (?, ?, ?, 'alice', 'original', ?)`, - legacyID, sessionID, sourceID, time.Now().Add(-time.Minute).UnixMilli()); err != nil { - t.Fatalf("seed legacy message: %v", err) - } - - if err := store.SaveMessage(ctx, sessionID, messaging.Message{ - ID: messaging.MessageID(CanonicalMessageID(sessionID, sourceID)), - SourceID: sourceID, Sender: "alice", Role: messaging.RoleUser, Text: "redelivered", - }); err != nil { - t.Fatalf("SaveMessage(redelivery): %v", err) - } - messages, err := store.RecentMessages(ctx, sessionID, 10) - if err != nil { - t.Fatalf("RecentMessages: %v", err) - } - if len(messages) != 1 { - t.Fatalf("redelivery produced %d messages, want 1", len(messages)) - } - if string(messages[0].ID) != legacyID || messages[0].Text != "original" { - t.Fatalf("legacy message changed on redelivery: %#v", messages[0]) - } -} - -func TestSQLiteSessionStoreFindPriorReplyRecognisesLegacyCanonicalID(t *testing.T) { - t.Parallel() - - store := newTestSQLiteStore(t) - ctx := t.Context() - const ( - sessionID = "a\x00b" - sourceID = "source" - identity = "archie" - ) - legacyID := uuid.NewSHA1(messageIDNamespace, []byte(sessionID+"\x00"+sourceID)).String() - inputAt := time.Now().Add(-time.Minute).UnixMilli() - statements := []struct { - id string - source string - sender string - text string - at int64 - }{ - {id: legacyID, source: sourceID, sender: "alice", text: "question", at: inputAt}, - {id: "reply", sender: identity, text: "answer", at: inputAt + 1}, - } - for _, row := range statements { - if _, err := sqliteStoreDB(t, store).ExecContext(ctx, ` - INSERT INTO messages (message_id, session_id, source_id, sender, text, ts) - VALUES (?, ?, ?, ?, ?, ?)`, - row.id, sessionID, row.source, row.sender, row.text, row.at); err != nil { - t.Fatalf("seed %s: %v", row.id, err) - } - } - - replayStore, ok := store.(TurnReplayStore) - if !ok { - t.Fatalf("store is %T, want TurnReplayStore", store) - } - got, err := replayStore.FindPriorReply(ctx, sessionID, sourceID, identity) - if err != nil { - t.Fatalf("FindPriorReply: %v", err) - } - if got != "answer" { - t.Fatalf("FindPriorReply = %q, want legacy reply", got) - } -} - -func TestSQLiteSessionStoreCapsFutureMessageTimestamp(t *testing.T) { - t.Parallel() - - store := newTestSQLiteStore(t) - ctx := t.Context() - now := time.Now().UTC() - if err := store.SaveMessage(ctx, "sess", messaging.Message{ - Sender: "alice", Role: messaging.RoleUser, Text: "future", At: now.Add(24 * time.Hour), - }); err != nil { - t.Fatalf("SaveMessage(future): %v", err) - } - if err := store.SaveMessage(ctx, "sess", messaging.Message{ - Sender: "alice", Role: messaging.RoleUser, Text: "current", At: now, - }); err != nil { - t.Fatalf("SaveMessage(current): %v", err) - } - - messages, err := store.RecentMessages(ctx, "sess", 10) - if err != nil { - t.Fatalf("RecentMessages: %v", err) - } - if len(messages) != 2 { - t.Fatalf("RecentMessages returned %d messages, want 2", len(messages)) - } - if messages[0].At.After(time.Now().UTC().Add(time.Minute)) { - t.Fatalf("future timestamp was persisted as %s", messages[0].At) - } - if !messages[1].At.After(messages[0].At) { - t.Fatalf("current message timestamp %s does not follow capped future timestamp %s", - messages[1].At, messages[0].At) - } -} - -func TestSQLiteSessionStoreRepairsPersistedFutureTimestampsOnReopen(t *testing.T) { - t.Parallel() - - ctx := t.Context() - path := filepath.Join(t.TempDir(), "future.db") - store, err := OpenSQLiteSessionStore(path) - if err != nil { - t.Fatalf("OpenSQLiteSessionStore: %v", err) - } - now := time.Now().UTC() - rows := []struct { - id string - text string - at time.Time - }{ - {id: "past", text: "past", at: now.Add(-time.Minute)}, - {id: "future-1", text: "future-1", at: now.Add(24 * time.Hour)}, - {id: "future-2", text: "future-2", at: now.Add(25 * time.Hour)}, - } - for _, row := range rows { - if _, err := sqliteStoreDB(t, store).ExecContext(ctx, ` - INSERT INTO messages (message_id, session_id, sender, text, ts) - VALUES (?, 'sess', 'alice', ?, ?)`, row.id, row.text, row.at.UnixMilli()); err != nil { - t.Fatalf("seed %s: %v", row.id, err) - } - } - if err := store.Close(); err != nil { - t.Fatalf("Close seeded store: %v", err) - } - - reopened, err := OpenSQLiteSessionStore(path) - if err != nil { - t.Fatalf("reopen store: %v", err) - } - t.Cleanup(func() { _ = reopened.Close() }) - if err := reopened.SaveMessage(ctx, "sess", messaging.Message{ - Sender: "alice", Role: messaging.RoleUser, Text: "current", At: time.Now().UTC(), - }); err != nil { - t.Fatalf("SaveMessage(current): %v", err) - } - - messages, err := reopened.RecentMessages(ctx, "sess", 10) - if err != nil { - t.Fatalf("RecentMessages: %v", err) - } - want := []string{"past", "future-1", "future-2", "current"} - if got := texts(messages); !equal(got, want) { - t.Fatalf("history = %v, want %v", got, want) - } - for i := 1; i < len(messages); i++ { - if !messages[i].At.After(messages[i-1].At) { - t.Fatalf("timestamp %d (%s) does not follow %d (%s)", - i, messages[i].At, i-1, messages[i-1].At) - } - } - if messages[len(messages)-1].At.After(time.Now().UTC().Add(time.Second)) { - t.Fatalf("repaired history remains pinned in the future: last timestamp %s", - messages[len(messages)-1].At) - } -} - -func TestSQLiteMessageTimestampRoundTrips(t *testing.T) { - st := newTestSQLiteStore(t) - want := sqliteBase().Add(90*time.Minute + 123*time.Millisecond) - if err := st.SaveMessage(t.Context(), "sess", messaging.Message{Sender: "user", Role: messaging.RoleUser, Text: "hello", At: want}); err != nil { - t.Fatal(err) - } - got, err := st.RecentMessages(t.Context(), "sess", 1) - if err != nil { - t.Fatal(err) - } - if len(got) != 1 || !got[0].At.Equal(want) { - t.Fatalf("RecentMessages = %+v, want timestamp %s", got, want) - } -} - -// TestSQLiteSessionStore_SenderIDRoundTrips proves the channel-native -// participant identifier survives both history reads -- the ordered -// RecentMessages and the ranked SearchMessages -- and that a record with no -// sender id round-trips as empty rather than erroring. -func TestSQLiteSessionStore_SenderIDRoundTrips(t *testing.T) { - st := newTestSQLiteStore(t) - ctx := context.Background() - if err := st.SaveMessage(ctx, "sess", messaging.Message{ - SourceID: "tg-1", Sender: "alice", SenderID: "u-42", - Role: messaging.RoleUser, Text: "hello there", At: sqliteBase(), - }); err != nil { - t.Fatalf("SaveMessage: %v", err) - } - if err := st.SaveMessage(ctx, "sess", messaging.Message{ - Sender: "archie", Role: messaging.RoleAssistant, Text: "hi", At: sqliteBase().Add(time.Second), - }); err != nil { - t.Fatalf("SaveMessage(no sender id): %v", err) - } - - hist, err := st.RecentMessages(ctx, "sess", 10) - if err != nil { - t.Fatalf("RecentMessages: %v", err) - } - if len(hist) != 2 { - t.Fatalf("RecentMessages = %d messages, want 2", len(hist)) - } - if hist[0].SenderID != "u-42" { - t.Errorf("RecentMessages()[0].SenderID = %q, want %q", hist[0].SenderID, "u-42") - } - if hist[1].SenderID != "" { - t.Errorf("RecentMessages()[1].SenderID = %q, want empty", hist[1].SenderID) - } - - page, err := st.SearchMessages(ctx, "sess", MessageQuery{Query: "hello", Limit: 10}) - if err != nil { - t.Fatalf("SearchMessages: %v", err) - } - if len(page.Messages) != 1 || page.Messages[0].SenderID != "u-42" { - t.Errorf("SearchMessages() = %+v, want one match with SenderID u-42", page.Messages) - } -} - -func TestSQLiteMessageTimestampsIncreaseAcrossStoreHandles(t *testing.T) { - path := filepath.Join(t.TempDir(), "messages.db") - stores := make([]SessionStore, 2) - for i := range stores { - var err error - stores[i], err = OpenSQLiteSessionStore(path) - if err != nil { - t.Fatal(err) - } - defer func(store SessionStore) { _ = store.Close() }(stores[i]) - } - - const perStore = 100 - wantTime := sqliteBase() - var wg sync.WaitGroup - for storeIndex, st := range stores { - for messageIndex := range perStore { - wg.Go(func() { - err := st.SaveMessage(t.Context(), "sess", messaging.Message{ - ID: messaging.MessageID(fmt.Sprintf("%d-%d", storeIndex, messageIndex)), - Sender: "user", Role: messaging.RoleUser, - Text: "concurrent", - At: wantTime, - }) - if err != nil { - t.Errorf("SaveMessage: %v", err) - } - }) - } - } - wg.Wait() - - messages, err := stores[0].RecentMessages(t.Context(), "sess", perStore*len(stores)) - if err != nil { - t.Fatal(err) - } - if len(messages) != perStore*len(stores) { - t.Fatalf("messages = %d, want %d", len(messages), perStore*len(stores)) - } - for i := 1; i < len(messages); i++ { - if !messages[i].At.After(messages[i-1].At) { - t.Fatalf("timestamp %d (%s) is not after timestamp %d (%s)", i, messages[i].At, i-1, messages[i-1].At) - } - } -} - -// TestSQLiteSessionStore_DeleteIsAtomic pins invariant 4: Delete removes the -// session and its messages together. -func TestSQLiteSessionStore_DeleteIsAtomic(t *testing.T) { - ctx := context.Background() - st := newTestSQLiteStore(t) - - sc := SessionContext{ - SessionID: "sess-del", Source: SessionSource{Platform: "web", ChannelID: "c"}, - CreatedAt: sqliteBase(), LastActiveAt: sqliteBase(), - } - if err := st.Save(ctx, sc); err != nil { - t.Fatalf("Save: %v", err) - } - if err := st.SaveMessage(ctx, "sess-del", messaging.Message{Sender: "u", Role: messaging.RoleUser, Text: "hi", At: sqliteBase()}); err != nil { - t.Fatalf("SaveMessage: %v", err) - } - - if err := st.Delete(ctx, "sess-del"); err != nil { - t.Fatalf("Delete: %v", err) - } - - got, err := st.Get(ctx, "sess-del") - if err != nil { - t.Fatalf("Get: %v", err) - } - if got != nil { - t.Error("expected session to be gone") - } - count, err := st.MessageCount(ctx, "sess-del") - if err != nil { - t.Fatalf("MessageCount: %v", err) - } - if count != 0 { - t.Errorf("expected messages to be gone, got count %d", count) - } - - // Deleting a non-existent session is a no-op. - if err := st.Delete(ctx, "nonexistent"); err != nil { - t.Errorf("Delete nonexistent: %v", err) - } -} - -// TestSQLiteSessionStore_SearchPagingAndTruncated pins invariant 6: Limit is -// a page size (not a cap), paging is honoured via Offset/NextOffset/HasMore, -// and Truncated is always false (SQLite has a real total count). -func TestSQLiteSessionStore_SearchPagingAndTruncated(t *testing.T) { - ctx := context.Background() - st := newTestSQLiteStore(t) - - const total = 30 - for i := range total { - m := messaging.Message{Sender: "u", Role: messaging.RoleUser, Text: "needle common", At: sqliteBase().Add(time.Duration(i) * time.Second)} - if err := st.SaveMessage(ctx, "sess", m); err != nil { - t.Fatalf("SaveMessage %d: %v", i, err) - } - } - - seen := map[string]bool{} - offset := 0 - pages := 0 - for { - page, err := st.SearchMessages(ctx, "sess", MessageQuery{Query: "needle", Limit: 7, Offset: offset}) - if err != nil { - t.Fatalf("SearchMessages offset=%d: %v", offset, err) - } - if page.Truncated { - t.Errorf("expected Truncated=false for SQLite backend") - } - for _, m := range page.Messages { - if seen[string(m.ID)] { - t.Errorf("duplicate message across pages: %s", string(m.ID)) - } - seen[string(m.ID)] = true - } - pages++ - if !page.HasMore { - break - } - offset = page.NextOffset - if pages > total { - t.Fatal("paging did not terminate") - } - } - if len(seen) != total { - t.Errorf("expected to see all %d matches across pages, got %d", total, len(seen)) - } -} - -func TestSQLiteSessionStore_ErrorPaths(t *testing.T) { - ctx := context.Background() - st := newTestSQLiteStore(t) - if err := st.Close(); err != nil { - t.Fatalf("Close: %v", err) - } - - t.Run("Save after close", func(t *testing.T) { - if err := st.Save(ctx, SessionContext{SessionID: "x"}); err == nil { - t.Error("expected error saving to a closed store") - } - }) - t.Run("Get after close", func(t *testing.T) { - if _, err := st.Get(ctx, "x"); err == nil { - t.Error("expected error getting from a closed store") - } - }) - t.Run("SaveMessage after close", func(t *testing.T) { - if err := st.SaveMessage(ctx, "sess", messaging.Message{Sender: "u", Role: messaging.RoleUser, Text: "hi"}); err == nil { - t.Error("expected error saving message to a closed store") - } - }) - t.Run("SearchMessages after close", func(t *testing.T) { - if _, err := st.SearchMessages(ctx, "sess", MessageQuery{Query: "hi"}); err == nil { - t.Error("expected error searching a closed store") - } - }) - t.Run("Delete after close", func(t *testing.T) { - if err := st.Delete(ctx, "sess"); err == nil { - t.Error("expected error deleting from a closed store") - } - }) - t.Run("ReplaceMessages after close", func(t *testing.T) { - if err := st.ReplaceMessages(ctx, "sess", nil, nil); err == nil { - t.Error("expected error replacing messages on a closed store") - } - }) -} - -func TestOpenSQLiteSessionStore_CreatesFile(t *testing.T) { - dir := t.TempDir() - path := dir + "/sub/dir/sessions.db" - - st, err := OpenSQLiteSessionStore(path) - if err != nil { - t.Fatalf("OpenSQLiteSessionStore: %v", err) - } - defer func() { _ = st.Close() }() - - ctx := context.Background() - sc := SessionContext{SessionID: "s1", Source: SessionSource{Platform: "web", ChannelID: "c"}, CreatedAt: sqliteBase(), LastActiveAt: sqliteBase()} - if err := st.Save(ctx, sc); err != nil { - t.Fatalf("Save: %v", err) - } - got, err := st.Get(ctx, "s1") - if err != nil { - t.Fatalf("Get: %v", err) - } - if got == nil { - t.Fatal("expected session to persist to the created file") - } -} - -// ── Adversarial file-backed coverage (bead 8u8.1) ─────────────────────────── -// -// These tests are deliberately SQLite-only. They prove two properties the -// shared 19-group conformance suite cannot: file-backed durability across -// close+reopen (with the trigger-maintained FTS index intact and a clean -// PRAGMA quick_check), and transaction rollback under injected -// mid-operation failures. They reach into sqliteSessionStore internals -- the -// raw *sql.DB -- to install deterministic abort triggers and run PRAGMA -// checks, which the SessionStore interface does not expose. - -// sqliteStoreDB exposes the raw handle behind a store for SQLite-specific -// tests. The store pins its pool to one connection and serializes writes -// with its own mutex, so a test touching this handle between operations is -// safe and deterministic. -// TestSQLiteSessionStore_MigratesPreRoleDatabase pins the upgrade path for -// databases written before the messaging migration added the role column: -// opening backfills roles from the sender-vs-bot identity the boundary -// applies to new writes, so old histories keep their assistant/user -// distinction and sender search keeps working. -func TestSQLiteSessionStore_MigratesPreRoleDatabase(t *testing.T) { - path := filepath.Join(t.TempDir(), "old.db") - db, err := sql.Open("sqlite", sqliteSessionDSN(path)) - if err != nil { - t.Fatalf("open raw db: %v", err) - } - oldMessages := strings.Replace(sqliteSessionSchema, - "\tsender TEXT NOT NULL DEFAULT '',\n\tsender_id TEXT NOT NULL DEFAULT '',\n\trole TEXT NOT NULL DEFAULT '',\n", - "\tsender TEXT NOT NULL DEFAULT '',\n", 1) - if _, err := db.ExecContext(t.Context(), oldMessages); err != nil { - t.Fatalf("create old schema: %v", err) - } - millis := sqliteBase().UnixMilli() - if _, err := db.ExecContext(t.Context(), `INSERT INTO sessions (session_id, platform, bot_user, channel_id, created_at, last_active_at) - VALUES ('sess-old', 'telegram', 'archie', 'chat-1', ?, ?)`, millis, millis); err != nil { - t.Fatalf("seed old session: %v", err) - } - if _, err := db.ExecContext(t.Context(), `INSERT INTO messages (message_id, session_id, source_id, sender, text, ts) VALUES - ('m-user', 'sess-old', 'tg-1', 'alice', 'hello', ?), - ('m-assistant', 'sess-old', '', 'archie', 'hi', ?)`, millis, millis+1); err != nil { - t.Fatalf("seed old messages: %v", err) - } - if err := db.Close(); err != nil { - t.Fatalf("close raw db: %v", err) - } - - st, err := OpenSQLiteSessionStore(path) - if err != nil { - t.Fatalf("reopen old database: %v", err) - } - t.Cleanup(func() { _ = st.Close() }) - - hist, err := st.RecentMessages(context.Background(), "sess-old", 10) - if err != nil { - t.Fatalf("RecentMessages: %v", err) - } - if len(hist) != 2 { - t.Fatalf("history = %d messages, want 2", len(hist)) - } - if hist[0].Role != messaging.RoleUser || hist[0].Sender != "alice" { - t.Errorf("user message = %+v, want role user from alice", hist[0]) - } - if hist[1].Role != messaging.RoleAssistant || hist[1].Sender != "archie" { - t.Errorf("assistant message = %+v, want role assistant from archie", hist[1]) - } - page, err := st.SearchMessages(context.Background(), "sess-old", MessageQuery{Query: "alice", Limit: 10}) - if err != nil { - t.Fatalf("SearchMessages: %v", err) - } - if len(page.Messages) != 1 { - t.Errorf("sender search = %d matches, want 1", len(page.Messages)) - } -} - -// TestSQLiteSessionStore_MigratesPreSenderIDDatabase simulates a database -// created before sender_id existed: a role-era schema with no sender_id -// column. Opening it must add the column with an empty default, leave the -// existing rows readable, and stay clean across a second open. -func TestSQLiteSessionStore_MigratesPreSenderIDDatabase(t *testing.T) { - path := filepath.Join(t.TempDir(), "old-sender.db") - db, err := sql.Open("sqlite", sqliteSessionDSN(path)) - if err != nil { - t.Fatalf("open raw db: %v", err) - } - oldMessages := strings.Replace(sqliteSessionSchema, - "\tsender_id TEXT NOT NULL DEFAULT '',\n", "", 1) - if _, err := db.ExecContext(t.Context(), oldMessages); err != nil { - t.Fatalf("create old schema: %v", err) - } - millis := sqliteBase().UnixMilli() - if _, err := db.ExecContext(t.Context(), `INSERT INTO sessions (session_id, platform, bot_user, channel_id, created_at, last_active_at) - VALUES ('sess-old', 'telegram', 'archie', 'chat-1', ?, ?)`, millis, millis); err != nil { - t.Fatalf("seed old session: %v", err) - } - if _, err := db.ExecContext(t.Context(), `INSERT INTO messages (message_id, session_id, source_id, sender, role, text, ts) VALUES - ('m-user', 'sess-old', 'tg-1', 'alice', 'user', 'hello', ?)`, millis); err != nil { - t.Fatalf("seed old message: %v", err) - } - if err := db.Close(); err != nil { - t.Fatalf("close raw db: %v", err) - } - - st, err := OpenSQLiteSessionStore(path) - if err != nil { - t.Fatalf("reopen old database: %v", err) - } - t.Cleanup(func() { _ = st.Close() }) - - hist, err := st.RecentMessages(context.Background(), "sess-old", 10) - if err != nil { - t.Fatalf("RecentMessages: %v", err) - } - if len(hist) != 1 { - t.Fatalf("history = %d messages, want 1", len(hist)) - } - if hist[0].Sender != "alice" || hist[0].SenderID != "" { - t.Errorf("migrated message = %+v, want sender alice with empty SenderID", hist[0]) - } - - // The second open takes the duplicate-column path; it must not fail. - again, err := OpenSQLiteSessionStore(path) - if err != nil { - t.Fatalf("second reopen: %v", err) - } - t.Cleanup(func() { _ = again.Close() }) - if _, err := again.RecentMessages(context.Background(), "sess-old", 10); err != nil { - t.Fatalf("RecentMessages after second reopen: %v", err) - } -} - -func sqliteStoreDB(t *testing.T, st SessionStore) *sql.DB { - t.Helper() - s, ok := st.(*sqliteSessionStore) - if !ok { - t.Fatalf("store is %T, want *sqliteSessionStore", st) - } - return s.db -} - -// installAbortTrigger deterministically fails the statement that matches -// clause by raising ABORT from a BEFORE trigger. Because the trigger fires -// mid-transaction (after earlier statements in the same transaction have -// already run), a correct store must roll the whole transaction back for the -// abort to be invisible to later reads. -func installAbortTrigger(t *testing.T, st SessionStore, clause string) { - t.Helper() - _, err := sqliteStoreDB(t, st).ExecContext(context.Background(), - `CREATE TRIGGER test_forced_abort `+clause+` BEGIN - SELECT RAISE(ABORT, 'forced test abort'); - END`) - if err != nil { - t.Fatalf("install abort trigger: %v", err) - } -} - -// TestSQLiteSessionStore_CloseReopenDurability proves that a file-backed -// store persists SessionContext fields and canonical message identity -// (MessageID, SourceID, sender, text, timestamp) across a close+reopen -// cycle, that the trigger-maintained FTS index survives with it, and that -// PRAGMA quick_check reports the file intact. -func TestSQLiteSessionStore_CloseReopenDurability(t *testing.T) { - ctx := context.Background() - path := filepath.Join(t.TempDir(), "sessions.db") - - st, err := OpenSQLiteSessionStore(path) - if err != nil { - t.Fatalf("OpenSQLiteSessionStore: %v", err) - } - - wantSC := SessionContext{ - SessionID: "sess-durable", - Source: SessionSource{ - Platform: "telegram", BotUser: "archie", ChannelID: "chat-42", ThreadID: "topic-7", - }, - Title: "durable title", - ParentSessionID: "sess-parent", - BranchName: "feature/x", - CreatedAt: sqliteBase(), - LastActiveAt: sqliteBase().Add(time.Minute), - } - if err := st.Save(ctx, wantSC); err != nil { - t.Fatalf("Save: %v", err) - } - - wantMsgs := []messaging.Message{ - {ID: "canonical-1", SourceID: "tg-1001", Sender: "alice", Role: messaging.RoleUser, Text: "first durable message", At: sqliteBase().Add(time.Second)}, - {ID: "canonical-2", SourceID: "tg-1002", Sender: "bob", Role: messaging.RoleUser, Text: "second durable message", At: sqliteBase().Add(2 * time.Second)}, - } - for _, m := range wantMsgs { - if err := st.SaveMessage(ctx, "sess-durable", m); err != nil { - t.Fatalf("SaveMessage %q: %v", string(m.ID), err) - } - } - if err := st.Close(); err != nil { - t.Fatalf("Close: %v", err) - } - - st2, err := OpenSQLiteSessionStore(path) - if err != nil { - t.Fatalf("reopen OpenSQLiteSessionStore: %v", err) - } - defer func() { _ = st2.Close() }() - - got, err := st2.Get(ctx, "sess-durable") - if err != nil { - t.Fatalf("Get after reopen: %v", err) - } - if got == nil { - t.Fatal("expected session to survive close+reopen") - } - if *got != wantSC { - t.Errorf("session after reopen:\n got %+v\nwant %+v", *got, wantSC) - } - - hist, err := st2.RecentMessages(ctx, "sess-durable", 10) - if err != nil { - t.Fatalf("RecentMessages after reopen: %v", err) - } - if len(hist) != len(wantMsgs) { - t.Fatalf("history after reopen: got %d messages, want %d", len(hist), len(wantMsgs)) - } - for i, m := range hist { - want := wantMsgs[i] - if m.ID != want.ID || m.SourceID != want.SourceID || - m.Sender != want.Sender || m.Role != want.Role || m.Text != want.Text || !m.At.Equal(want.At) { - t.Errorf("message %d after reopen:\n got %+v\nwant %+v", i, m, want) - } - } - - // The FTS index is trigger-maintained, so it must survive reopen too. - page, err := st2.SearchMessages(ctx, "sess-durable", MessageQuery{Query: "durable"}) - if err != nil { - t.Fatalf("SearchMessages after reopen: %v", err) - } - if len(page.Messages) != len(wantMsgs) { - t.Errorf("search after reopen: got %d matches, want %d", len(page.Messages), len(wantMsgs)) - } - - var check string - if err := sqliteStoreDB(t, st2).QueryRowContext(ctx, "PRAGMA quick_check").Scan(&check); err != nil { - t.Fatalf("PRAGMA quick_check: %v", err) - } - if check != "ok" { - t.Errorf("PRAGMA quick_check = %q, want ok", check) - } -} - -// TestSQLiteSessionStore_DeleteAbortRollsBack pins that Delete rolls its -// transaction back when a statement fails mid-operation: the messages DELETE -// has already run inside the transaction when the sessions DELETE trips the -// abort trigger, so the rollback must restore the session, its history, its -// count, and its search results. -func TestSQLiteSessionStore_DeleteAbortRollsBack(t *testing.T) { - ctx := context.Background() - st := newTestSQLiteStore(t) - - sc := SessionContext{ - SessionID: "sess-del-abort", - Source: SessionSource{Platform: "web", ChannelID: "c"}, - Title: "keep me", - CreatedAt: sqliteBase(), LastActiveAt: sqliteBase(), - } - if err := st.Save(ctx, sc); err != nil { - t.Fatalf("Save: %v", err) - } - seed := []messaging.Message{ - {Sender: "alice", Role: messaging.RoleUser, Text: "alpha", At: sqliteBase()}, - {Sender: "bob", Role: messaging.RoleUser, Text: "beta", At: sqliteBase().Add(time.Second)}, - {Sender: "carol", Role: messaging.RoleUser, Text: "gamma", At: sqliteBase().Add(2 * time.Second)}, - } - for _, m := range seed { - if err := st.SaveMessage(ctx, "sess-del-abort", m); err != nil { - t.Fatalf("SaveMessage: %v", err) - } - } - - installAbortTrigger(t, st, `BEFORE DELETE ON sessions WHEN old.session_id = 'sess-del-abort'`) - - if err := st.Delete(ctx, "sess-del-abort"); err == nil { - t.Fatal("expected Delete to fail from the forced abort trigger") - } - - got, err := st.Get(ctx, "sess-del-abort") - if err != nil { - t.Fatalf("Get after failed Delete: %v", err) - } - if got == nil || *got != sc { - t.Errorf("session after failed Delete: got %+v, want %+v", got, sc) - } - - hist, err := st.RecentMessages(ctx, "sess-del-abort", 10) - if err != nil { - t.Fatalf("RecentMessages after failed Delete: %v", err) - } - if len(hist) != len(seed) { - t.Fatalf("history after failed Delete: got %d messages, want %d", len(hist), len(seed)) - } - for i, m := range hist { - if m.Text != seed[i].Text || m.Sender != seed[i].Sender { - t.Errorf("message %d after failed Delete: got %+v, want text %q from %q", i, m, seed[i].Text, seed[i].Sender) - } - } - - count, err := st.MessageCount(ctx, "sess-del-abort") - if err != nil { - t.Fatalf("MessageCount after failed Delete: %v", err) - } - if count != len(seed) { - t.Errorf("count after failed Delete: got %d, want %d", count, len(seed)) - } - - // The FTS index must match the rolled-back history. - page, err := st.SearchMessages(ctx, "sess-del-abort", MessageQuery{Query: "beta"}) - if err != nil { - t.Fatalf("SearchMessages after failed Delete: %v", err) - } - if len(page.Messages) != 1 { - t.Errorf("search after failed Delete: got %d matches, want 1", len(page.Messages)) - } -} - -// TestSQLiteSessionStore_ReplaceMessagesAbortRollsBack pins that -// ReplaceMessages rolls its transaction back when the delete-old step fails -// mid-operation: the replacement inserts have already landed in the -// transaction when the abort fires, so the rollback must remove the -// replacement and restore the original history, count, and search results. -func TestSQLiteSessionStore_ReplaceMessagesAbortRollsBack(t *testing.T) { - ctx := context.Background() - st := newTestSQLiteStore(t) - - seed := []messaging.Message{ - {ID: "m-0", SourceID: "s-0", Sender: "alice", Role: messaging.RoleUser, Text: "alpha", At: sqliteBase()}, - {ID: "m-1", SourceID: "s-1", Sender: "bob", Role: messaging.RoleUser, Text: "beta", At: sqliteBase().Add(time.Second)}, - {ID: "m-2", SourceID: "s-2", Sender: "carol", Role: messaging.RoleUser, Text: "gamma", At: sqliteBase().Add(2 * time.Second)}, - } - if err := st.SaveMessages(ctx, "sess-replace-abort", seed); err != nil { - t.Fatalf("SaveMessages: %v", err) - } - - // Guard an original row so the abort fires only after the replacement - // inserts have landed inside the transaction. - installAbortTrigger(t, st, `BEFORE DELETE ON messages WHEN old.message_id = 'm-1'`) - - replacement := []messaging.Message{{Sender: "summarizer", Role: messaging.RoleUser, Text: "merged summary", At: sqliteBase().Add(time.Hour)}} - if err := st.ReplaceMessages(ctx, "sess-replace-abort", replacement, supersededIDs(ctx, t, st, "sess-replace-abort")); err == nil { - t.Fatal("expected ReplaceMessages to fail from the forced abort trigger") - } - - hist, err := st.RecentMessages(ctx, "sess-replace-abort", 10) - if err != nil { - t.Fatalf("RecentMessages after failed ReplaceMessages: %v", err) - } - if len(hist) != len(seed) { - t.Fatalf("history after failed ReplaceMessages: got %d messages, want %d", len(hist), len(seed)) - } - for i, m := range hist { - if string(m.ID) != string(seed[i].ID) || m.Text != seed[i].Text || m.Sender != seed[i].Sender { - t.Errorf("message %d after failed ReplaceMessages: got %+v, want %+v", i, m, seed[i]) - } - } - - count, err := st.MessageCount(ctx, "sess-replace-abort") - if err != nil { - t.Fatalf("MessageCount after failed ReplaceMessages: %v", err) - } - if count != len(seed) { - t.Errorf("count after failed ReplaceMessages: got %d, want %d", count, len(seed)) - } - - page, err := st.SearchMessages(ctx, "sess-replace-abort", MessageQuery{Query: "beta"}) - if err != nil { - t.Fatalf("SearchMessages after failed ReplaceMessages: %v", err) - } - if len(page.Messages) != 1 { - t.Errorf("search 'beta' after failed ReplaceMessages: got %d matches, want 1", len(page.Messages)) - } - page, err = st.SearchMessages(ctx, "sess-replace-abort", MessageQuery{Query: "summary"}) - if err != nil { - t.Fatalf("SearchMessages after failed ReplaceMessages: %v", err) - } - if len(page.Messages) != 0 { - t.Errorf("search 'summary' after failed ReplaceMessages: got %d matches, want 0 (replacement must be rolled back)", len(page.Messages)) - } -} - -// ── FTS lifecycle and literal-query semantics (bead 8u8.4) ────────────────── -// -// The shared 19-group conformance suite (sessionstore_conformance_test.go) -// proves behaviour through the SessionStore interface, but two properties are -// SQLite-specific and cannot be expressed there: the trigger-maintained FTS5 -// index must stay consistent as history mutates, and free-text queries must -// survive hostile input. These tests are SQLite-only and assert exact -// results -- not merely the absence of panics. - -// sameTexts compares two text slices as sets: same length, same members, -// order-insensitive. FTS pages are ranked by bm25, so order is a ranking -// detail rather than part of the match contract. -func sameTexts(a, b []string) bool { - if len(a) != len(b) { - return false - } - seen := make(map[string]int, len(a)) - for _, s := range a { - seen[s]++ - } - for _, s := range b { - seen[s]-- - if seen[s] < 0 { - return false - } - } - return true -} - -// ftsIntegrityErr runs the documented FTS5 external-content integrity -// check (`INSERT INTO ...(table, rank) VALUES('integrity-check', 1)`) against -// the store's raw handle and returns any error it reports. A consistent -// index reports no error; a stale entry -- a content row deleted without the -// AFTER DELETE trigger firing -- reports "database disk image is malformed". -// Search/count joins can never surface such an entry because they only see -// index rows whose content row still exists, so this is the one check that -// detects an orphaned index. -func ftsIntegrityErr(t *testing.T, st SessionStore) error { - t.Helper() - _, err := sqliteStoreDB(t, st).ExecContext(context.Background(), - `INSERT INTO messages_fts(messages_fts, rank) VALUES('integrity-check', 1)`) - return err -} - -// TestSQLiteSessionStore_FTSStaysCorrectThroughMutations pins that the FTS5 -// index follows every message mutation: DeleteRecentMessages removes the -// newest documents, ReplaceMessages swaps the whole document set, and Delete -// clears the session -- with search results and counts tracking the surviving -// history and never leaking across sessions. -func TestSQLiteSessionStore_FTSStaysCorrectThroughMutations(t *testing.T) { - // Sessions "a" and "b" share the term "needle", so any cross-session - // leak in search or count is caught; "marker" lives only in "b". - seedA := []string{"needle alpha", "filler one", "needle beta", "filler two"} - seedB := []string{"needle gamma", "distinct marker"} - - tests := []struct { - name string - mutate func(ctx context.Context, t *testing.T, st SessionStore) error - wantA []string // session a history after the mutation - wantANeedle []string // session a search "needle" - wantACount int - wantAMarker []string // session a search "marker" (only in b) - wantBNeedle []string // session b search "needle" (must stay intact) - wantBCount int - }{ - { - name: "DeleteRecentMessages prunes the index newest-first", - mutate: func(ctx context.Context, t *testing.T, st SessionStore) error { - deleted, err := st.DeleteRecentMessages(ctx, "a", 2) - if err == nil && deleted != 2 { - t.Errorf("deleted %d messages, want 2", deleted) - } - return err - }, - wantA: []string{"needle alpha", "filler one"}, - wantANeedle: []string{"needle alpha"}, - wantACount: 2, - wantAMarker: nil, - wantBNeedle: []string{"needle gamma"}, - wantBCount: 2, - }, - { - name: "ReplaceMessages swaps the document set", - mutate: func(ctx context.Context, t *testing.T, st SessionStore) error { - return st.ReplaceMessages(ctx, "a", []messaging.Message{{ - Sender: "summarizer", Role: messaging.RoleUser, Text: "merged needle summary", At: sqliteBase().Add(time.Hour), - }}, supersededIDs(ctx, t, st, "a")) - }, - wantA: []string{"merged needle summary"}, - wantANeedle: []string{"merged needle summary"}, - wantACount: 1, - wantAMarker: nil, - wantBNeedle: []string{"needle gamma"}, - wantBCount: 2, - }, - { - name: "Delete clears the session's index", - mutate: func(ctx context.Context, t *testing.T, st SessionStore) error { - return st.Delete(ctx, "a") - }, - wantA: nil, - wantANeedle: nil, - wantACount: 0, - wantAMarker: nil, - wantBNeedle: []string{"needle gamma"}, - wantBCount: 2, - }, - } - - for _, tc := range tests { - t.Run(tc.name, func(t *testing.T) { - // Subtest-local context: mutation closures receive it as a - // parameter instead of capturing the outer function's. - ctx := context.Background() - st := newTestSQLiteStore(t) - - for i, text := range seedA { - if err := st.SaveMessage(ctx, "a", messaging.Message{Sender: "u", Role: messaging.RoleUser, Text: text, At: sqliteBase().Add(time.Duration(i) * time.Second)}); err != nil { - t.Fatalf("SaveMessage a %q: %v", text, err) - } - } - for i, text := range seedB { - if err := st.SaveMessage(ctx, "b", messaging.Message{Sender: "u", Role: messaging.RoleUser, Text: text, At: sqliteBase().Add(time.Duration(i) * time.Second)}); err != nil { - t.Fatalf("SaveMessage b %q: %v", text, err) - } - } - - if err := tc.mutate(ctx, t, st); err != nil { - t.Fatalf("mutate: %v", err) - } - - // The index must be internally consistent with the surviving - // history, not merely join-visible: an orphaned entry would be - // invisible to the search/count joins below, so check the index - // itself after every mutation. - if err := ftsIntegrityErr(t, st); err != nil { - t.Fatalf("FTS5 integrity check after %q: %v", tc.name, err) - } - - hist, err := st.RecentMessages(ctx, "a", 100) - if err != nil { - t.Fatalf("RecentMessages a: %v", err) - } - if !equal(texts(hist), tc.wantA) { - t.Errorf("session a history = %v, want %v", texts(hist), tc.wantA) - } - - assertSearch := func(session, term string, want []string) { - t.Helper() - page, err := st.SearchMessages(ctx, session, MessageQuery{Query: term, Limit: 100}) - if err != nil { - t.Fatalf("SearchMessages(%s, %q): %v", session, term, err) - } - if !sameTexts(texts(page.Messages), want) { - t.Errorf("search %s %q = %v, want %v", session, term, texts(page.Messages), want) - } - if page.Truncated || page.HasMore { - t.Errorf("search %s %q: Truncated=%v HasMore=%v, want false/false", session, term, page.Truncated, page.HasMore) - } - } - - assertSearch("a", "needle", tc.wantANeedle) - assertSearch("a", "marker", tc.wantAMarker) - assertSearch("b", "needle", tc.wantBNeedle) - - for _, sc := range []struct { - session string - want int - }{ - {"a", tc.wantACount}, {"b", tc.wantBCount}, - } { - count, err := st.MessageCount(ctx, sc.session) - if err != nil { - t.Fatalf("MessageCount %s: %v", sc.session, err) - } - if count != sc.want { - t.Errorf("MessageCount %s = %d, want %d", sc.session, count, sc.want) - } - } - - histB, err := st.RecentMessages(ctx, "b", 100) - if err != nil { - t.Fatalf("RecentMessages b: %v", err) - } - if !equal(texts(histB), seedB) { - t.Errorf("session b history = %v, want untouched %v", texts(histB), seedB) - } - }) - } -} - -// TestSQLiteSessionStore_FTSIntegrityCheckDetectsOrphanedIndex proves the -// integrity check used by the lifecycle test is load-bearing: with the AFTER -// DELETE trigger temporarily dropped, a store mutation leaves a stale -// messages_fts entry that the check must report, while the same mutation with -// the trigger intact leaves a consistent index. -func TestSQLiteSessionStore_FTSIntegrityCheckDetectsOrphanedIndex(t *testing.T) { - t.Run("stale index entry fails the check", func(t *testing.T) { - ctx := context.Background() - st := newTestSQLiteStore(t) - - for i, text := range []string{"needle one", "needle two"} { - if err := st.SaveMessage(ctx, "sess", messaging.Message{Sender: "u", Role: messaging.RoleUser, Text: text, At: sqliteBase().Add(time.Duration(i) * time.Second)}); err != nil { - t.Fatalf("SaveMessage: %v", err) - } - } - - // Bypass the AFTER DELETE trigger so the index keeps a row for the - // deleted message. - if _, err := sqliteStoreDB(t, st).ExecContext(ctx, `DROP TRIGGER messages_ad`); err != nil { - t.Fatalf("drop delete trigger: %v", err) - } - if _, err := st.DeleteRecentMessages(ctx, "sess", 1); err != nil { - t.Fatalf("DeleteRecentMessages: %v", err) - } - - if err := ftsIntegrityErr(t, st); err == nil { - t.Fatal("FTS5 integrity check passed despite a stale index entry (delete trigger bypassed)") - } - }) - - t.Run("trigger-maintained delete keeps the index consistent", func(t *testing.T) { - ctx := context.Background() - st := newTestSQLiteStore(t) - - for i, text := range []string{"needle one", "needle two"} { - if err := st.SaveMessage(ctx, "sess", messaging.Message{Sender: "u", Role: messaging.RoleUser, Text: text, At: sqliteBase().Add(time.Duration(i) * time.Second)}); err != nil { - t.Fatalf("SaveMessage: %v", err) - } - } - if _, err := st.DeleteRecentMessages(ctx, "sess", 1); err != nil { - t.Fatalf("DeleteRecentMessages: %v", err) - } - - if err := ftsIntegrityErr(t, st); err != nil { - t.Fatalf("FTS5 integrity check failed after trigger-maintained delete: %v", err) - } - }) -} - -// TestSQLiteSessionStore_HostileQueriesAreLiteral pins that free-text input -// is never executed as FTS5 query syntax: column filters, the NEAR operator, -// prefix wildcards, and boolean operators must all be treated as literal -// terms (or, for a bare "*", an empty phrase) without syntax errors. Each -// row asserts the exact match set, not merely the absence of a panic. -func TestSQLiteSessionStore_HostileQueriesAreLiteral(t *testing.T) { - ctx := context.Background() - st := newTestSQLiteStore(t) - - seed := []string{ - "text:hello here", // phrase (text, hello) - "hello there", // would match a raw "text:hello" column filter - "hello world", - `hello "world quote`, // unmatched-quote input must still find this - "near a b", // phrase (near, a) AND token b - "a far b", // would match a raw NEAR(a b) operator - "star * symbol", // "*" is a separator: never a token, never matches - "needle or elsewhere", - "needle elsewhere", // would match a raw OR query - "needle", - "alpha beta gamma", // both AND terms present - "alpha alone", - "beta alone", - } - for i, text := range seed { - if err := st.SaveMessage(ctx, "sess", messaging.Message{Sender: "u", Role: messaging.RoleUser, Text: text, At: sqliteBase().Add(time.Duration(i) * time.Second)}); err != nil { - t.Fatalf("SaveMessage %q: %v", text, err) - } - } - - tests := []struct { - name string - query string - want []string - }{ - {"column syntax is a literal phrase, not a column filter", "text:hello", []string{"text:hello here"}}, - {"unmatched quote is literal, not a syntax error", `hello "world`, []string{"hello world", `hello "world quote`}}, - {"NEAR syntax is literal, not the NEAR operator", "NEAR(a b)", []string{"near a b"}}, - {"bare wildcard is an empty phrase, not a prefix operator", "*", nil}, - {"OR is a literal term, not the boolean operator", "needle OR elsewhere", []string{"needle or elsewhere"}}, - {"multi-term query pins AND semantics", "alpha beta", []string{"alpha beta gamma"}}, - } - - for _, tc := range tests { - t.Run(tc.name, func(t *testing.T) { - page, err := st.SearchMessages(ctx, "sess", MessageQuery{Query: tc.query, Limit: 100}) - if err != nil { - t.Fatalf("SearchMessages(%q): %v", tc.query, err) - } - if !sameTexts(texts(page.Messages), tc.want) { - t.Errorf("query %q matched %v, want %v", tc.query, texts(page.Messages), tc.want) - } - if page.Truncated || page.HasMore { - t.Errorf("query %q: Truncated=%v HasMore=%v, want false/false", tc.query, page.Truncated, page.HasMore) - } - }) - } -} - -// TestFTSMatchQueryEscapesHostileInput pins the exact MATCH expression the -// store generates: every whitespace-separated term becomes a quoted phrase -// (embedded quotes doubled), joined by explicit AND, so user input can never -// reach the FTS5 parser as query syntax. -func TestFTSMatchQueryEscapesHostileInput(t *testing.T) { - tests := []struct{ in, want string }{ - {"", ""}, - {" ", ""}, - {"alpha beta", `"alpha" AND "beta"`}, - {"needle OR elsewhere", `"needle" AND "OR" AND "elsewhere"`}, - {"text:hello", `"text:hello"`}, - {`hello "world`, `"hello" AND """world"`}, - {"NEAR(a b)", `"NEAR(a" AND "b)"`}, - {"*", `"*"`}, - } - for _, tc := range tests { - if got := ftsMatchQuery(tc.in); got != tc.want { - t.Errorf("ftsMatchQuery(%q) = %q, want %q", tc.in, got, tc.want) - } - } -} diff --git a/internal/gateway/turn_ledger.go b/internal/gateway/turn_ledger.go index ba4fad5f0..e9c4f43e7 100644 --- a/internal/gateway/turn_ledger.go +++ b/internal/gateway/turn_ledger.go @@ -2,8 +2,11 @@ package gateway import ( "context" + "encoding/json" "errors" + "fmt" "strings" + "time" "github.com/google/uuid" ) @@ -72,3 +75,42 @@ func CanonicalTurnID(sessionID, sourceID string) string { func legacyCanonicalTurnID(sessionID, sourceID string) string { return uuid.NewSHA1(uuid.NameSpaceURL, []byte("archie-turn:\x00"+sessionID+"\x00"+sourceID)).String() } + +func prepareInitialTurn(initial TurnRecord, now time.Time) (TurnRecord, string, error) { + if initial.TurnID == "" { + return TurnRecord{}, "", fmt.Errorf("sessionstore: turn ID is required") + } + initial.Status = TurnStatusRunning + initial.Attempt = 1 + if initial.CreatedAt.IsZero() { + initial.CreatedAt = now + } + initial.UpdatedAt = now + toolCalls, err := marshalToolCalls(initial.ToolCalls) + return initial, toolCalls, err +} + +// marshalToolCalls encodes tool activity for storage; an empty slice becomes +// "[]" so it round-trips through unmarshalToolCalls to nil. +func marshalToolCalls(events []ToolCallEvent) (string, error) { + if len(events) == 0 { + return "[]", nil + } + encoded, err := json.Marshal(events) + if err != nil { + return "", fmt.Errorf("sessionstore: marshal tool calls: %w", err) + } + return string(encoded), nil +} + +// unmarshalToolCalls decodes tool activity persisted by marshalToolCalls. +func unmarshalToolCalls(raw string) ([]ToolCallEvent, error) { + if raw == "" || raw == "[]" { + return nil, nil + } + var events []ToolCallEvent + if err := json.Unmarshal([]byte(raw), &events); err != nil { + return nil, fmt.Errorf("sessionstore: unmarshal tool calls: %w", err) + } + return events, nil +} diff --git a/internal/gateway/turn_ledger_test.go b/internal/gateway/turn_ledger_test.go index 7b0d8e3e2..c3021acb2 100644 --- a/internal/gateway/turn_ledger_test.go +++ b/internal/gateway/turn_ledger_test.go @@ -3,9 +3,10 @@ package gateway import ( "context" "errors" - "path/filepath" "testing" "time" + + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest" ) func TestTurnLedgerClaimLifecycleIsIdempotent(t *testing.T) { @@ -14,17 +15,17 @@ func TestTurnLedgerClaimLifecycleIsIdempotent(t *testing.T) { open func(t *testing.T) (TurnLedger, func()) }{ { - name: "sqlite memory", + name: "memory", open: func(t *testing.T) (TurnLedger, func()) { - store, err := NewSQLiteSessionStoreMemory() - if err != nil { - t.Fatal(err) - } - ledger, ok := store.(TurnLedger) - if !ok { - t.Fatalf("store is %T, want TurnLedger", store) - } - return ledger, func() { _ = store.Close() } + store := NewSessionStoreMemory() + return store.(TurnLedger), func() { _ = store.Close() } + }, + }, + { + name: "postgres", + open: func(t *testing.T) (TurnLedger, func()) { + store := newPostgresStore(t) + return store.(TurnLedger), func() { _ = store.Close() } }, }, } @@ -109,17 +110,17 @@ func TestTurnLedgerReclaimsAcrossProcessOwnersAndRejectsStaleWrites(t *testing.T open func(t *testing.T) (TurnLedger, func()) }{ { - name: "sqlite memory", + name: "memory", open: func(t *testing.T) (TurnLedger, func()) { - store, err := NewSQLiteSessionStoreMemory() - if err != nil { - t.Fatal(err) - } - ledger, ok := store.(TurnLedger) - if !ok { - t.Fatalf("store is %T, want TurnLedger", store) - } - return ledger, func() { _ = store.Close() } + store := NewSessionStoreMemory() + return store.(TurnLedger), func() { _ = store.Close() } + }, + }, + { + name: "postgres", + open: func(t *testing.T) (TurnLedger, func()) { + store := newPostgresStore(t) + return store.(TurnLedger), func() { _ = store.Close() } }, }, } @@ -171,15 +172,10 @@ func TestSessionDeleteRemovesTurns(t *testing.T) { open func(t *testing.T) SessionStore }{ { - name: "sqlite memory", - open: func(t *testing.T) SessionStore { - store, err := NewSQLiteSessionStoreMemory() - if err != nil { - t.Fatal(err) - } - return store - }, + name: "memory", + open: func(*testing.T) SessionStore { return NewSessionStoreMemory() }, }, + {name: "postgres", open: newPostgresStore}, } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { @@ -208,12 +204,9 @@ func TestSessionDeleteRemovesTurns(t *testing.T) { } func TestTurnLedgerPersistsToolCallsAcrossClaimAndReopen(t *testing.T) { - path := filepath.Join(t.TempDir(), "sessions.db") + url := pgtest.URL(t) ctx := context.Background() - store, err := OpenSQLiteSessionStore(path) - if err != nil { - t.Fatalf("OpenSQLiteSessionStore() error = %v", err) - } + store := openPostgresStoreAt(t, url) ledger, ok := store.(TurnLedger) if !ok { t.Fatalf("store is %T, want TurnLedger", store) @@ -251,10 +244,7 @@ func TestTurnLedgerPersistsToolCallsAcrossClaimAndReopen(t *testing.T) { if err := store.Close(); err != nil { t.Fatalf("Close() error = %v", err) } - reopened, err := OpenSQLiteSessionStore(path) - if err != nil { - t.Fatalf("reopen error = %v", err) - } + reopened := openPostgresStoreAt(t, url) defer func() { _ = reopened.Close() }() reopenedLedger, ok := reopened.(TurnLedger) if !ok { @@ -269,13 +259,10 @@ func TestTurnLedgerPersistsToolCallsAcrossClaimAndReopen(t *testing.T) { } } -func TestSQLiteTurnLedgerSurvivesReopen(t *testing.T) { - path := filepath.Join(t.TempDir(), "sessions.db") +func TestPostgresTurnLedgerSurvivesReopen(t *testing.T) { + url := pgtest.URL(t) ctx := context.Background() - store, err := OpenSQLiteSessionStore(path) - if err != nil { - t.Fatalf("OpenSQLiteSessionStore() error = %v", err) - } + store := openPostgresStoreAt(t, url) ledger, ok := store.(TurnLedger) if !ok { t.Fatalf("store is %T, want TurnLedger", store) @@ -300,10 +287,7 @@ func TestSQLiteTurnLedgerSurvivesReopen(t *testing.T) { t.Fatalf("Close() error = %v", err) } - reopened, err := OpenSQLiteSessionStore(path) - if err != nil { - t.Fatalf("reopen error = %v", err) - } + reopened := openPostgresStoreAt(t, url) defer func() { _ = reopened.Close() }() reopenedLedger, ok := reopened.(TurnLedger) if !ok { @@ -347,7 +331,7 @@ func TestCanonicalTurnIDComponentsAreInjectivelyEncoded(t *testing.T) { func TestTurnRunnerCanonicalTurnIDPreservesMatchingLegacyRecord(t *testing.T) { t.Parallel() - store := newTestSQLiteStore(t) + store := NewSessionStoreMemory() ledger, ok := store.(TurnLedger) if !ok { t.Fatalf("store is %T, want TurnLedger", store) @@ -378,7 +362,7 @@ func TestTurnRunnerCanonicalTurnIDPreservesMatchingLegacyRecord(t *testing.T) { func TestTurnRunnerCanonicalTurnIDRejectsCollidingLegacyRecord(t *testing.T) { t.Parallel() - store := newTestSQLiteStore(t) + store := NewSessionStoreMemory() ledger, ok := store.(TurnLedger) if !ok { t.Fatalf("store is %T, want TurnLedger", store) From a3b4ead6a6e63c8f376907a3ca4e7ebcaf8a1be8 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Thu, 24 Sep 2026 14:43:25 +1000 Subject: [PATCH 3/8] refactor(scripts): drop the SQLite task-database backup from the installer and watchdog The pre-update PostgreSQL snapshot is the only backup; the watchdog restores binaries and never the database. --- internal/app/archied/store_wiring_test.go | 40 - .../{edastore => bindingcipher}/cipher.go | 0 .../cipher_test.go | 0 internal/infrastructure/edastore/contracts.go | 190 --- .../edastore/contracts_binding.go | 393 ------ internal/infrastructure/edastore/edastore.go | 128 -- internal/infrastructure/edastore/notify.go | 26 - .../infrastructure/edastore/notify_test.go | 273 ---- internal/infrastructure/edastore/opentest.go | 23 - internal/infrastructure/edastore/schema.go | 218 --- .../infrastructure/edastore/schema_test.go | 209 --- .../edastore/testsupport_test.go | 30 - .../infrastructure/edastore/tool_calls.go | 98 -- .../edastore/tool_calls_test.go | 102 -- internal/releaseupdate/install_script_test.go | 209 +-- internal/store/apply_status.go | 77 -- internal/store/apply_status_test.go | 92 -- internal/store/channel_status.go | 106 -- internal/store/channel_status_test.go | 79 -- internal/store/config_snapshot.go | 69 - internal/store/config_snapshot_test.go | 63 - internal/store/events.go | 277 ---- internal/store/identities.go | 252 ---- internal/store/identities_test.go | 84 -- internal/store/identity_subject_test.go | 157 --- internal/store/interface.go | 63 - internal/store/maintenance.go | 265 ---- internal/store/maintenance_test.go | 92 -- internal/store/ownership.go | 68 - internal/store/ownership_unix.go | 30 - internal/store/ownership_windows.go | 23 - internal/store/queries_test.go | 395 ------ internal/store/remediation_test.go | 220 ---- internal/store/resources.go | 127 -- internal/store/resources_test.go | 110 -- internal/store/review_cursor_test.go | 45 - internal/store/store.go | 929 ------------- internal/store/store_test.go | 1167 ----------------- internal/store/tasks_fields_test.go | 81 -- internal/store/timestamps_test.go | 107 -- scripts/archie-update-install | 65 +- scripts/archie-update-watchdog | 31 +- 42 files changed, 14 insertions(+), 6999 deletions(-) delete mode 100644 internal/app/archied/store_wiring_test.go rename internal/infrastructure/{edastore => bindingcipher}/cipher.go (100%) rename internal/infrastructure/{edastore => bindingcipher}/cipher_test.go (100%) delete mode 100644 internal/infrastructure/edastore/contracts.go delete mode 100644 internal/infrastructure/edastore/contracts_binding.go delete mode 100644 internal/infrastructure/edastore/edastore.go delete mode 100644 internal/infrastructure/edastore/notify.go delete mode 100644 internal/infrastructure/edastore/notify_test.go delete mode 100644 internal/infrastructure/edastore/opentest.go delete mode 100644 internal/infrastructure/edastore/schema.go delete mode 100644 internal/infrastructure/edastore/schema_test.go delete mode 100644 internal/infrastructure/edastore/testsupport_test.go delete mode 100644 internal/infrastructure/edastore/tool_calls.go delete mode 100644 internal/infrastructure/edastore/tool_calls_test.go delete mode 100644 internal/store/apply_status.go delete mode 100644 internal/store/apply_status_test.go delete mode 100644 internal/store/channel_status.go delete mode 100644 internal/store/channel_status_test.go delete mode 100644 internal/store/config_snapshot.go delete mode 100644 internal/store/config_snapshot_test.go delete mode 100644 internal/store/events.go delete mode 100644 internal/store/identities.go delete mode 100644 internal/store/identities_test.go delete mode 100644 internal/store/identity_subject_test.go delete mode 100644 internal/store/interface.go delete mode 100644 internal/store/maintenance.go delete mode 100644 internal/store/maintenance_test.go delete mode 100644 internal/store/ownership.go delete mode 100644 internal/store/ownership_unix.go delete mode 100644 internal/store/ownership_windows.go delete mode 100644 internal/store/queries_test.go delete mode 100644 internal/store/remediation_test.go delete mode 100644 internal/store/resources.go delete mode 100644 internal/store/resources_test.go delete mode 100644 internal/store/review_cursor_test.go delete mode 100644 internal/store/store.go delete mode 100644 internal/store/store_test.go delete mode 100644 internal/store/tasks_fields_test.go delete mode 100644 internal/store/timestamps_test.go diff --git a/internal/app/archied/store_wiring_test.go b/internal/app/archied/store_wiring_test.go deleted file mode 100644 index 99ea039a2..000000000 --- a/internal/app/archied/store_wiring_test.go +++ /dev/null @@ -1,40 +0,0 @@ -package archied - -import ( - "errors" - "os" - "path/filepath" - "testing" -) - -func TestProductionTaskStoreUsesSQLite(t *testing.T) { - configuredPath := filepath.Join(t.TempDir(), "state.db") - path := taskDBPath(configuredPath) - if path == configuredPath { - t.Fatal("task database must use an independent fresh path") - } - st, err := openProductionTaskStore(t.Context(), path) - if err != nil { - t.Fatal(err) - } - if _, err := os.Stat(configuredPath); !errors.Is(err, os.ErrNotExist) { - t.Fatalf("configured anchor path was opened directly: %v", err) - } - inserted, err := st.EnqueueIssue(t.Context(), "acme", "widget", 7, "persisted", "", "", "") - if err != nil || !inserted { - t.Fatalf("EnqueueIssue = (%v, %v), want (true, nil)", inserted, err) - } - if err := st.Close(); err != nil { - t.Fatal(err) - } - - st, err = openProductionTaskStore(t.Context(), path) - if err != nil { - t.Fatal(err) - } - t.Cleanup(func() { _ = st.Close() }) - task, err := st.TaskByIssue(t.Context(), "acme", "widget", 7) - if err != nil || task == nil || task.Title != "persisted" { - t.Fatalf("TaskByIssue after reopen = (%+v, %v)", task, err) - } -} diff --git a/internal/infrastructure/edastore/cipher.go b/internal/infrastructure/bindingcipher/cipher.go similarity index 100% rename from internal/infrastructure/edastore/cipher.go rename to internal/infrastructure/bindingcipher/cipher.go diff --git a/internal/infrastructure/edastore/cipher_test.go b/internal/infrastructure/bindingcipher/cipher_test.go similarity index 100% rename from internal/infrastructure/edastore/cipher_test.go rename to internal/infrastructure/bindingcipher/cipher_test.go diff --git a/internal/infrastructure/edastore/contracts.go b/internal/infrastructure/edastore/contracts.go deleted file mode 100644 index ee1b1d9a9..000000000 --- a/internal/infrastructure/edastore/contracts.go +++ /dev/null @@ -1,190 +0,0 @@ -package edastore - -import ( - "context" - "database/sql" - "errors" - "fmt" - "strings" - "time" - - "github.com/pocketbase/dbx" - "github.com/pocketbase/pocketbase/core" - - "github.com/samcharles93/archie-core/internal/domain/storecontract" -) - -// capturedAtLayout is fixed-width UTC with nanosecond precision, so string -// comparison is time comparison. time.RFC3339Nano trims trailing zeros, which -// would break that. -const capturedAtLayout = "2006-01-02T15:04:05.000000000Z" - -// This store is the implementation of every event-capture contract. The task -// lifecycle contracts stay on the SQLite store; the two meet only at -// binding_dispatches.task_id. -var ( - _ storecontract.CaptureStore = (*Store)(nil) - _ storecontract.MappingStore = (*Store)(nil) - _ storecontract.BindingStore = (*Store)(nil) - _ storecontract.BindingDispatcher = (*Store)(nil) - _ storecontract.PlaybookDispatcher = (*Store)(nil) -) - -func (s *Store) record(collection, id string) (*core.Record, error) { - r, err := s.app.FindRecordById(collection, id) - if errors.Is(err, sql.ErrNoRows) { - return nil, nil - } - return r, err -} - -// InsertCapture stores one inbound event verbatim. Redaction happens upstream -// in webhookguard; this persists exactly what it is given, because field -// mapping is designed against the payload as received. -// -// retention and maxEvents are accepted for contract compatibility and applied -// as a prune after the insert. -func (s *Store) InsertCapture(ctx context.Context, c storecontract.CapturedEvent, retention time.Duration, maxEvents int) (string, error) { - collection, err := s.app.FindCollectionByNameOrId(CollCaptures) - if err != nil { - return "", err - } - r := core.NewRecord(collection) - r.Set("source", c.Source) - r.Set("remote_addr", c.RemoteAddr) - r.Set("content_type", c.ContentType) - r.Set("headers", c.Headers) - r.Set("body", c.Body) - r.Set("authenticated", c.Authenticated) - received := c.ReceivedAt - if received.IsZero() { - received = time.Now() - } - r.Set("received_at", received.UTC().Format(capturedAtLayout)) - if err := s.app.Save(r); err != nil { - return "", fmt.Errorf("edastore: insert capture: %w", err) - } - if err := s.pruneCaptures(ctx, retention, maxEvents); err != nil { - return "", err - } - return r.Id, nil -} - -// pruneCaptures enforces the retention window and count cap. A capture exists -// to be mapped against while it is recent; keeping every event forever would -// make an unauthenticated intake surface a disk-growth vector. -func (s *Store) pruneCaptures(_ context.Context, retention time.Duration, maxEvents int) error { - if retention > 0 { - cutoff := time.Now().Add(-retention).UTC().Format(time.RFC3339) - if _, err := s.app.DB().NewQuery( - "DELETE FROM " + CollCaptures + " WHERE received_at < {:cutoff}"). - Bind(map[string]any{"cutoff": cutoff}).Execute(); err != nil { - return fmt.Errorf("edastore: prune captures by age: %w", err) - } - } - if maxEvents > 0 { - if _, err := s.app.DB().NewQuery( - "DELETE FROM " + CollCaptures + " WHERE id NOT IN (SELECT id FROM " + CollCaptures + - " ORDER BY received_at DESC LIMIT {:keep})"). - Bind(map[string]any{"keep": maxEvents}).Execute(); err != nil { - return fmt.Errorf("edastore: prune captures by count: %w", err) - } - } - return nil -} - -// parseCapturedAt reads the stored timestamp, tolerating the RFC3339 form a -// caller-supplied value may carry. -func parseCapturedAt(raw string) time.Time { - for _, layout := range []string{capturedAtLayout, time.RFC3339Nano, time.RFC3339} { - if t, err := time.Parse(layout, raw); err == nil { - return t - } - } - return time.Time{} -} - -func captureValue(r *core.Record) storecontract.CapturedEvent { - return storecontract.CapturedEvent{ - ID: r.Id, - ReceivedAt: parseCapturedAt(r.GetString("received_at")), - Source: r.GetString("source"), - RemoteAddr: r.GetString("remote_addr"), - ContentType: r.GetString("content_type"), - Headers: r.GetString("headers"), - Body: r.GetString("body"), - Authenticated: r.GetBool("authenticated"), - } -} - -// ListCaptures returns the newest captures first. -func (s *Store) ListCaptures(_ context.Context, limit int) ([]storecontract.CapturedEvent, error) { - records, err := s.app.FindRecordsByFilter(CollCaptures, "", "-received_at", limit, 0) - if err != nil { - return nil, fmt.Errorf("edastore: list captures: %w", err) - } - out := make([]storecontract.CapturedEvent, 0, len(records)) - for _, r := range records { - out = append(out, captureValue(r)) - } - return out, nil -} - -// ListUndispatchedCaptures returns recent captures for the given sources that -// no binding has dispatched yet. -// -// This is raw SQL rather than a record filter: the anti-join against the -// dispatch ledger is a subquery, and PocketBase's filter DSL is not SQL (it -// has no IN (SELECT ...) form). A read fires no hooks either way, so nothing -// is lost by dropping to the query builder here. -func (s *Store) ListUndispatchedCaptures(_ context.Context, sources []string, limit int) ([]storecontract.CapturedEvent, error) { - if len(sources) == 0 || limit <= 0 { - return nil, nil - } - placeholders := make([]string, 0, len(sources)) - params := dbx.Params{"limit": limit} - for i, src := range sources { - key := fmt.Sprintf("s%d", i) - placeholders = append(placeholders, "{:"+key+"}") - params[key] = src - } - query := "SELECT id, received_at, source, remote_addr, content_type, headers, body, authenticated FROM " + - CollCaptures + " WHERE source IN (" + strings.Join(placeholders, ",") + - ") AND id NOT IN (SELECT capture FROM " + CollBindingDispatches + ") ORDER BY received_at DESC LIMIT {:limit}" - - var rows []captureRow - if err := s.app.DB().NewQuery(query).Bind(params).All(&rows); err != nil { - return nil, fmt.Errorf("edastore: list undispatched captures: %w", err) - } - out := make([]storecontract.CapturedEvent, 0, len(rows)) - for _, r := range rows { - out = append(out, r.value()) - } - return out, nil -} - -// captureRow is the raw-SQL shape of a capture, used only where a record -// filter cannot express the query. -type captureRow struct { - ID string `db:"id"` - ReceivedAt string `db:"received_at"` - Source string `db:"source"` - RemoteAddr string `db:"remote_addr"` - ContentType string `db:"content_type"` - Headers string `db:"headers"` - Body string `db:"body"` - Authenticated bool `db:"authenticated"` -} - -func (r captureRow) value() storecontract.CapturedEvent { - return storecontract.CapturedEvent{ - ID: r.ID, - ReceivedAt: parseCapturedAt(r.ReceivedAt), - Source: r.Source, - RemoteAddr: r.RemoteAddr, - ContentType: r.ContentType, - Headers: r.Headers, - Body: r.Body, - Authenticated: r.Authenticated, - } -} diff --git a/internal/infrastructure/edastore/contracts_binding.go b/internal/infrastructure/edastore/contracts_binding.go deleted file mode 100644 index 8f4c9ca74..000000000 --- a/internal/infrastructure/edastore/contracts_binding.go +++ /dev/null @@ -1,393 +0,0 @@ -package edastore - -import ( - "context" - "encoding/json" - "fmt" - "strings" - - "github.com/pocketbase/pocketbase/core" - - "github.com/samcharles93/archie-core/internal/domain/binding" - "github.com/samcharles93/archie-core/internal/domain/mapping" - "github.com/samcharles93/archie-core/internal/events" -) - -// --- mappings --- - -func mappingValue(r *core.Record) (mapping.Mapping, error) { - var fields []mapping.Field - if raw := r.GetString("fields"); raw != "" { - if err := json.Unmarshal([]byte(raw), &fields); err != nil { - return mapping.Mapping{}, fmt.Errorf("edastore: decode mapping fields: %w", err) - } - } - return mapping.Mapping{ - ID: r.Id, - Name: r.GetString("name"), - SourceHint: r.GetString("source_hint"), - Fields: fields, - CreatedAt: r.GetDateTime("created_at").Time(), - UpdatedAt: r.GetDateTime("updated_at").Time(), - }, nil -} - -func (s *Store) applyMapping(r *core.Record, m mapping.Mapping) error { - encoded, err := json.Marshal(m.Fields) - if err != nil { - return fmt.Errorf("edastore: encode mapping fields: %w", err) - } - r.Set("name", m.Name) - r.Set("source_hint", m.SourceHint) - r.Set("fields", string(encoded)) - return nil -} - -func (s *Store) InsertMapping(_ context.Context, m mapping.Mapping) (string, error) { - collection, err := s.app.FindCollectionByNameOrId(CollMappings) - if err != nil { - return "", err - } - r := core.NewRecord(collection) - if err := s.applyMapping(r, m); err != nil { - return "", err - } - if err := s.app.Save(r); err != nil { - return "", fmt.Errorf("edastore: insert mapping: %w", err) - } - s.notifyWrite(events.KindMappingChanged, "mapping", "create", r.Id) - return r.Id, nil -} - -func (s *Store) GetMapping(_ context.Context, id string) (*mapping.Mapping, error) { - r, err := s.record(CollMappings, id) - if err != nil || r == nil { - return nil, err - } - m, err := mappingValue(r) - if err != nil { - return nil, err - } - return &m, nil -} - -func (s *Store) ListMappings(_ context.Context) ([]mapping.Mapping, error) { - records, err := s.app.FindRecordsByFilter(CollMappings, "", "-created_at", 0, 0) - if err != nil { - return nil, fmt.Errorf("edastore: list mappings: %w", err) - } - out := make([]mapping.Mapping, 0, len(records)) - for _, r := range records { - m, err := mappingValue(r) - if err != nil { - return nil, err - } - out = append(out, m) - } - return out, nil -} - -func (s *Store) UpdateMapping(_ context.Context, m mapping.Mapping) error { - r, err := s.record(CollMappings, m.ID) - if err != nil { - return err - } - if r == nil { - return ErrMappingNotFound - } - if err := s.applyMapping(r, m); err != nil { - return err - } - if err := s.app.Save(r); err != nil { - return err - } - s.notifyWrite(events.KindMappingChanged, "mapping", "update", m.ID) - return nil -} - -func (s *Store) DeleteMapping(_ context.Context, id string) error { - r, err := s.record(CollMappings, id) - if err != nil { - return err - } - if r == nil { - return ErrMappingNotFound - } - if err := s.app.Delete(r); err != nil { - return err - } - s.notifyWrite(events.KindMappingChanged, "mapping", "delete", id) - return nil -} - -// --- bindings --- - -func (s *Store) bindingValue(r *core.Record) (binding.Binding, error) { - b := binding.Binding{ - ID: r.Id, - Name: r.GetString("name"), - Matcher: binding.Matcher{Source: r.GetString("source")}, - MappingID: r.GetString("mapping"), - Workflow: r.GetString("workflow"), - Owner: r.GetString("owner"), - Repo: r.GetString("repo"), - Version: r.GetInt("version"), - Status: binding.Status(r.GetString("status")), - Secret: r.GetString("secret"), - CreatedAt: r.GetDateTime("created_at").Time(), - UpdatedAt: r.GetDateTime("updated_at").Time(), - } - if s.cipher != nil && b.Secret != "" { - plain, err := s.cipher.Decrypt(b.Secret) - if err != nil { - return binding.Binding{}, fmt.Errorf("edastore: decrypt binding secret: %w", err) - } - b.Secret = plain - } - return b, nil -} - -func (s *Store) applyBinding(r *core.Record, b binding.Binding) error { - r.Set("name", b.Name) - r.Set("source", b.Matcher.Source) - r.Set("mapping", b.MappingID) - r.Set("workflow", b.Workflow) - r.Set("owner", b.Owner) - r.Set("repo", b.Repo) - // An empty secret means "keep the stored one". An edit form that does not - // echo the secret back must not silently disarm the binding by erasing it. - if b.Secret == "" { - return nil - } - secret := b.Secret - if s.cipher != nil { - encrypted, err := s.cipher.Encrypt(secret) - if err != nil { - return fmt.Errorf("edastore: encrypt binding secret: %w", err) - } - secret = encrypted - } - r.Set("secret", secret) - return nil -} - -// InsertBinding stores a new binding as a draft. The caller's status is -// ignored on purpose: a binding cannot go live without explicit approval, so -// ApproveBinding is the only path to armed. -// -// A source may carry at most one binding, so an insert against a source that -// already has one is refused rather than creating an ambiguous second matcher. -func (s *Store) InsertBinding(ctx context.Context, b binding.Binding) (string, error) { - existing, err := s.bindingsByFilter("source = {:source}", map[string]any{"source": b.Matcher.Source}) - if err != nil { - return "", err - } - if len(existing) > 0 { - return "", ErrBindingOverlap - } - collection, err := s.app.FindCollectionByNameOrId(CollBindings) - if err != nil { - return "", err - } - r := core.NewRecord(collection) - if err := s.applyBinding(r, b); err != nil { - return "", err - } - r.Set("version", 1) - r.Set("status", string(binding.StatusPendingApproval)) - if err := s.app.Save(r); err != nil { - return "", fmt.Errorf("edastore: insert binding: %w", err) - } - _ = ctx - s.notifyWrite(events.KindBindingChanged, "binding", "create", r.Id) - return r.Id, nil -} - -func (s *Store) GetBinding(_ context.Context, id string) (*binding.Binding, error) { - r, err := s.record(CollBindings, id) - if err != nil || r == nil { - return nil, err - } - b, err := s.bindingValue(r) - if err != nil { - return nil, err - } - return &b, nil -} - -func (s *Store) ListBindings(_ context.Context) ([]binding.Binding, error) { - return s.bindingsByFilter("", nil) -} - -// ArmedBindingsForSource returns the armed bindings a source can dispatch. A -// draft or pending_approval binding is never returned: that is the gate. -func (s *Store) ArmedBindingsForSource(_ context.Context, source string) ([]binding.Binding, error) { - return s.bindingsByFilter("source = {:source} && status = {:status}", - map[string]any{"source": source, "status": string(binding.StatusArmed)}) -} - -func (s *Store) bindingsByFilter(filter string, params map[string]any) ([]binding.Binding, error) { - var records []*core.Record - var err error - if params == nil { - records, err = s.app.FindRecordsByFilter(CollBindings, filter, "-created_at", 0, 0) - } else { - records, err = s.app.FindRecordsByFilter(CollBindings, filter, "-created_at", 0, 0, params) - } - if err != nil { - return nil, fmt.Errorf("edastore: list bindings: %w", err) - } - out := make([]binding.Binding, 0, len(records)) - for _, r := range records { - b, err := s.bindingValue(r) - if err != nil { - return nil, err - } - out = append(out, b) - } - return out, nil -} - -// UpdateBinding rewrites a binding's editable fields, bumps its version, and -// sends it back to pending_approval. An edit always requires re-approval: an -// armed binding whose matcher or workflow changed is a different binding, and -// re-arming it silently would defeat the gate. -func (s *Store) UpdateBinding(_ context.Context, b binding.Binding) error { - r, err := s.record(CollBindings, b.ID) - if err != nil { - return err - } - if r == nil { - return ErrBindingNotFound - } - others, err := s.bindingsByFilter("source = {:source} && id != {:id}", - map[string]any{"source": b.Matcher.Source, "id": b.ID}) - if err != nil { - return err - } - if len(others) > 0 { - return ErrBindingOverlap - } - if err := s.applyBinding(r, b); err != nil { - return err - } - r.Set("status", string(binding.StatusPendingApproval)) - r.Set("version", r.GetInt("version")+1) - if err := s.app.Save(r); err != nil { - return err - } - s.notifyWrite(events.KindBindingChanged, "binding", "update", b.ID) - return nil -} - -func (s *Store) DeleteBinding(_ context.Context, id string) error { - r, err := s.record(CollBindings, id) - if err != nil { - return err - } - if r == nil { - return ErrBindingNotFound - } - if err := s.app.Delete(r); err != nil { - return err - } - s.notifyWrite(events.KindBindingChanged, "binding", "delete", id) - return nil -} - -// ApproveBinding is the only transition that arms a binding. It moves -// pending_approval to armed; any other current state is refused, so a draft -// cannot skip review and an armed binding cannot be re-approved. -// -// A source may have only one armed binding, so approval is refused when -// another binding on the same source is already armed. Without that guard, -// one capture could match two armed matchers and dispatch twice. -func (s *Store) ApproveBinding(_ context.Context, id string) error { - r, err := s.record(CollBindings, id) - if err != nil { - return err - } - if r == nil { - return ErrBindingNotFound - } - armed, err := s.bindingsByFilter("source = {:source} && status = {:status} && id != {:id}", - map[string]any{"source": r.GetString("source"), "status": string(binding.StatusArmed), "id": id}) - if err != nil { - return err - } - if len(armed) > 0 { - return ErrBindingOverlap - } - if r.GetString("status") != string(binding.StatusPendingApproval) { - return ErrBindingTransition - } - r.Set("status", string(binding.StatusArmed)) - if err := s.app.Save(r); err != nil { - return err - } - s.notifyWrite(events.KindBindingChanged, "binding", "approve", id) - return nil -} - -// --- dispatch ledgers --- - -// RecordDispatch writes one at-most-once binding dispatch. Uniqueness is the -// collection's index, so a replay is refused by the schema; the caller sees -// ErrAlreadyDispatched rather than a silent second run. -func (s *Store) RecordDispatch(_ context.Context, bindingID string, bindingVersion int64, captureID string, taskID int64) error { - collection, err := s.app.FindCollectionByNameOrId(CollBindingDispatches) - if err != nil { - return err - } - r := core.NewRecord(collection) - r.Set("binding", bindingID) - r.Set("binding_version", bindingVersion) - r.Set("capture", captureID) - r.Set("task_id", taskID) - return ledgerWrite(s.app.Save(r), "edastore: record dispatch") -} - -func (s *Store) RecordPlaybookDispatch(_ context.Context, playbookID, playbookVersion, eventID, actionID string) error { - collection, err := s.app.FindCollectionByNameOrId(CollPlaybookDispatches) - if err != nil { - return err - } - r := core.NewRecord(collection) - r.Set("playbook_id", playbookID) - r.Set("playbook_version", playbookVersion) - r.Set("event_id", eventID) - r.Set("action_id", actionID) - return ledgerWrite(s.app.Save(r), "edastore: record playbook dispatch") -} - -func (s *Store) DeletePlaybookDispatches(_ context.Context, playbookID string) error { - _, err := s.app.DB().NewQuery( - "DELETE FROM " + CollPlaybookDispatches + " WHERE playbook_id = {:id}"). - Bind(map[string]any{"id": playbookID}).Execute() - if err != nil { - return fmt.Errorf("edastore: delete playbook dispatches: %w", err) - } - return nil -} - -// ledgerWrite turns the unique-index refusal into ErrAlreadyDispatched and -// leaves every other failure alone. Treating all errors as "already recorded" -// would turn an at-most-once ledger into a silent at-least-once dispatcher. -func ledgerWrite(err error, what string) error { - switch { - case err == nil: - return nil - case isUniqueViolation(err): - return ErrAlreadyDispatched - default: - return fmt.Errorf("%s: %w", what, err) - } -} - -// isUniqueViolation reports whether err is the unique-index refusal. -// PocketBase surfaces it as a validation failure rather than a typed error, -// so the message is what there is to match on. -func isUniqueViolation(err error) bool { - text := strings.ToLower(err.Error()) - return strings.Contains(text, "unique") || strings.Contains(text, "already exists") -} diff --git a/internal/infrastructure/edastore/edastore.go b/internal/infrastructure/edastore/edastore.go deleted file mode 100644 index 7c336b39d..000000000 --- a/internal/infrastructure/edastore/edastore.go +++ /dev/null @@ -1,128 +0,0 @@ -// Package edastore persists the event-capture and playbook-binding tables on -// PocketBase-owned collections. -// -// These are the tables behind the event-capture epic: an inbound webhook is -// captured whether or not anything understands it yet, an operator inspects -// the real payload, maps fields against it, and binds a matcher and mapping -// to a workflow. That loop wants a runtime-editable store with a live view of -// arriving payloads, which is what PocketBase collections give directly. -// -// These collections are authoritative and writable: the admin UI editing a binding -// IS the feature, not a hazard. The task lifecycle tables stay on SQLite -- -// they carry ordering, cursor and task-grant semantics that gain nothing from -// being hand-editable. binding_dispatches.task reaches them by plain id, which -// is the single seam between the two stores. -// -// Idempotency here is schema-enforced. The SQLite implementation relied on -// INSERT OR IGNORE against a composite primary key; a unique index does the -// same job without every caller having to remember the pattern. -package edastore - -import ( - "errors" - "fmt" - - "github.com/pocketbase/dbx" - "github.com/pocketbase/pocketbase" - "github.com/pocketbase/pocketbase/core" - _ "modernc.org/sqlite" - - "github.com/samcharles93/archie-core/internal/domain/storecontract" - "github.com/samcharles93/archie-core/internal/events" -) - -// Collection names. They are unprefixed because this store owns its database; -// nothing else writes these tables. -const ( - CollCaptures = "captures" - CollMappings = "mappings" - CollBindings = "bindings" - CollBindingDispatches = "binding_dispatches" - CollPlaybookDispatches = "playbook_dispatches" - CollToolCalls = "tool_calls" -) - -// Sentinels are re-exported from the contract rather than redefined. Their -// exact message strings are the wire contract: staterpc matches on (code, -// canonical message) to rehydrate them on the client, so a second definition -// with different text would break errors.Is across the gRPC boundary without -// changing anything visible. -var ( - ErrBindingNotFound = storecontract.ErrBindingNotFound - ErrBindingOverlap = storecontract.ErrBindingOverlap - ErrBindingTransition = storecontract.ErrBindingTransition - ErrAlreadyDispatched = storecontract.ErrAlreadyDispatched - ErrMappingNotFound = storecontract.ErrMappingNotFound -) - -// ErrCaptureNotFound reports a capture that is absent or aged out. -var ErrCaptureNotFound = errors.New("edastore: capture not found") - -// Collections returns every collection this store owns. -func Collections() []string { - return []string{ - CollCaptures, CollMappings, CollBindings, - CollBindingDispatches, CollPlaybookDispatches, CollToolCalls, - } -} - -// Config describes one store. -type Config struct { - // Cipher encrypts binding secrets at rest. Nil keeps them plaintext, - // which is the behaviour that predates the option. - Cipher BindingCipher - // Notify receives one event per successful write on the bindings and - // mappings tables, so an operator edit surfaces on the dashboard's - // activity stream exactly like capture arrival does. Nil keeps writes - // silent, which is the behaviour that predates the option and what - // every existing constructor gets. - Notify func(events.Event) - // DBPath is the SQLite file PocketBase owns for these collections. - DBPath string - // DataDir holds PocketBase's auxiliary database and settings. - DataDir string -} - -// Store is the PocketBase-backed EDA persistence. -type Store struct { - app *pocketbase.PocketBase - cipher BindingCipher - notify func(events.Event) -} - -// Open bootstraps the store and ensures its collections exist. -func Open(cfg Config) (*Store, error) { - if cfg.DBPath == "" || cfg.DataDir == "" { - return nil, errors.New("edastore: DBPath and DataDir are required") - } - app := pocketbase.NewWithConfig(pocketbase.Config{ - DefaultDataDir: cfg.DataDir, - HideStartBanner: true, - DBConnect: func(requested string) (*dbx.DB, error) { - if isDataDB(requested) { - requested = cfg.DBPath - } - return dbx.Open("sqlite", requested+"?_pragma=journal_mode(WAL)&_pragma=busy_timeout(5000)") - }, - }) - if err := app.Bootstrap(); err != nil { - return nil, fmt.Errorf("edastore: bootstrap: %w", err) - } - if err := app.RunAllMigrations(); err != nil { - return nil, fmt.Errorf("edastore: migrations: %w", err) - } - if err := removeDefaultAuthCollection(app); err != nil { - return nil, err - } - if err := ensureCollections(app); err != nil { - return nil, err - } - return &Store{app: app, cipher: cfg.Cipher, notify: cfg.Notify}, nil -} - -// App exposes the PocketBase application so one process can serve this store -// and its admin UI from a single bootstrap. -func (s *Store) App() core.App { return s.app } - -// Close releases the store's database connections. -func (s *Store) Close() error { return s.app.ClearBootstrap() } diff --git a/internal/infrastructure/edastore/notify.go b/internal/infrastructure/edastore/notify.go deleted file mode 100644 index f8ecec7f3..000000000 --- a/internal/infrastructure/edastore/notify.go +++ /dev/null @@ -1,26 +0,0 @@ -package edastore - -import "github.com/samcharles93/archie-core/internal/events" - -// notifyWrite announces one successful write on the bindings or mappings -// tables. It rides the same activity-event path capture arrival uses: the -// State Store's event insert feeds the webui pump, which broadcasts to every -// connected browser, so an operator edit is visible without a manual -// refresh. The data carries the record id and action; the row itself stays -// the only source of the full record, and consumers refetch through the -// authenticated API -- the event is an invalidation signal, not a payload. -// -// A nil notifier is a silent no-op: stores composed without one (tests, -// tooling) keep working unchanged, mirroring the nil Publish on -// captureintake.Receiver. -func (s *Store) notifyWrite(kind, subject, action, id string) { - if s.notify == nil { - return - } - past := map[string]string{"create": "created", "update": "updated", "approve": "approved", "delete": "deleted"}[action] - s.notify(events.Event{ - Kind: kind, - Detail: subject + " " + past, - Data: map[string]any{"id": id, "action": action}, - }) -} diff --git a/internal/infrastructure/edastore/notify_test.go b/internal/infrastructure/edastore/notify_test.go deleted file mode 100644 index 8d88bded7..000000000 --- a/internal/infrastructure/edastore/notify_test.go +++ /dev/null @@ -1,273 +0,0 @@ -package edastore - -import ( - "errors" - "testing" - - "github.com/samcharles93/archie-core/internal/domain/binding" - "github.com/samcharles93/archie-core/internal/domain/mapping" - "github.com/samcharles93/archie-core/internal/events" -) - -// recordingNotifier collects every event the store emits so a test can -// assert on the exact sequence, mirroring captureintake's recordingPublisher. -type recordingNotifier struct { - got []events.Event -} - -func (r *recordingNotifier) notify(e events.Event) { r.got = append(r.got, e) } - -func (r *recordingNotifier) reset() { r.got = nil } - -// notifiedStore is an OpenTest store with the notifier wired, the way -// composition does it through Config.Notify. -func notifiedStore(t *testing.T) (*Store, *recordingNotifier) { - t.Helper() - s := OpenTest(t) - n := &recordingNotifier{} - s.notify = n.notify - return s, n -} - -func TestWriteMethodsNotifyOnSuccess(t *testing.T) { - b := func(source string) binding.Binding { - return binding.Binding{ - Name: "webhook to workflow", - Matcher: binding.Matcher{Source: source}, - Workflow: "triage", - } - } - - t.Run("InsertBinding", func(t *testing.T) { - s, n := notifiedStore(t) - id, err := s.InsertBinding(t.Context(), b("src-insert")) - if err != nil { - t.Fatalf("InsertBinding() error = %v", err) - } - if len(n.got) != 1 { - t.Fatalf("InsertBinding notified %d times, want 1: %+v", len(n.got), n.got) - } - assertEditEvent(t, n.got[0], events.KindBindingChanged, "create", id) - }) - - t.Run("UpdateBinding", func(t *testing.T) { - s, n := notifiedStore(t) - id := insertBinding(t, s, bindingInput{Name: "before", Source: "src-update", Workflow: "triage"}) - n.reset() - bb := b("src-update") - bb.ID = id - bb.Workflow = "escalate" - if err := s.UpdateBinding(t.Context(), bb); err != nil { - t.Fatalf("UpdateBinding() error = %v", err) - } - if len(n.got) != 1 { - t.Fatalf("UpdateBinding notified %d times, want 1: %+v", len(n.got), n.got) - } - assertEditEvent(t, n.got[0], events.KindBindingChanged, "update", id) - }) - - t.Run("ApproveBinding", func(t *testing.T) { - s, n := notifiedStore(t) - id := insertBinding(t, s, bindingInput{Name: "draft", Source: "src-approve", Workflow: "triage"}) - bb := b("src-approve") - bb.ID = id - // Approval requires pending_approval; the edit transition also fires. - if err := s.UpdateBinding(t.Context(), bb); err != nil { - t.Fatalf("UpdateBinding() error = %v", err) - } - n.reset() - if err := s.ApproveBinding(t.Context(), id); err != nil { - t.Fatalf("ApproveBinding() error = %v", err) - } - if len(n.got) != 1 { - t.Fatalf("ApproveBinding notified %d times, want 1: %+v", len(n.got), n.got) - } - assertEditEvent(t, n.got[0], events.KindBindingChanged, "approve", id) - }) - - t.Run("DeleteBinding", func(t *testing.T) { - s, n := notifiedStore(t) - id := insertBinding(t, s, bindingInput{Name: "doomed", Source: "src-delete", Workflow: "triage"}) - n.reset() - if err := s.DeleteBinding(t.Context(), id); err != nil { - t.Fatalf("DeleteBinding() error = %v", err) - } - if len(n.got) != 1 { - t.Fatalf("DeleteBinding notified %d times, want 1: %+v", len(n.got), n.got) - } - assertEditEvent(t, n.got[0], events.KindBindingChanged, "delete", id) - }) - - t.Run("InsertMapping", func(t *testing.T) { - s, n := notifiedStore(t) - id, err := s.InsertMapping(t.Context(), mapping.Mapping{Name: "payload-map"}) - if err != nil { - t.Fatalf("InsertMapping() error = %v", err) - } - if len(n.got) != 1 { - t.Fatalf("InsertMapping notified %d times, want 1: %+v", len(n.got), n.got) - } - assertEditEvent(t, n.got[0], events.KindMappingChanged, "create", id) - }) - - t.Run("UpdateMapping", func(t *testing.T) { - s, n := notifiedStore(t) - id, err := s.InsertMapping(t.Context(), mapping.Mapping{Name: "payload-map"}) - if err != nil { - t.Fatalf("InsertMapping() error = %v", err) - } - n.reset() - m, err := s.GetMapping(t.Context(), id) - if err != nil { - t.Fatalf("GetMapping() error = %v", err) - } - m.Name = "renamed" - if err := s.UpdateMapping(t.Context(), *m); err != nil { - t.Fatalf("UpdateMapping() error = %v", err) - } - if len(n.got) != 1 { - t.Fatalf("UpdateMapping notified %d times, want 1: %+v", len(n.got), n.got) - } - assertEditEvent(t, n.got[0], events.KindMappingChanged, "update", id) - }) - - t.Run("DeleteMapping", func(t *testing.T) { - s, n := notifiedStore(t) - id, err := s.InsertMapping(t.Context(), mapping.Mapping{Name: "doomed"}) - if err != nil { - t.Fatalf("InsertMapping() error = %v", err) - } - n.reset() - if err := s.DeleteMapping(t.Context(), id); err != nil { - t.Fatalf("DeleteMapping() error = %v", err) - } - if len(n.got) != 1 { - t.Fatalf("DeleteMapping notified %d times, want 1: %+v", len(n.got), n.got) - } - assertEditEvent(t, n.got[0], events.KindMappingChanged, "delete", id) - }) -} - -func assertEditEvent(t *testing.T, e events.Event, kind, action, id string) { - t.Helper() - if e.Kind != kind { - t.Errorf("event kind = %q, want %q", e.Kind, kind) - } - if e.Detail == "" { - t.Errorf("event detail is empty") - } - if got := e.Data["id"]; got != id { - t.Errorf("event data id = %v, want %q", got, id) - } - if got := e.Data["action"]; got != action { - t.Errorf("event data action = %v, want %q", got, action) - } -} - -func TestFailedWritesNotifyNothing(t *testing.T) { - s, n := notifiedStore(t) - - // Seed one binding and one mapping, then clear the seed-time events. - seedID := insertBinding(t, s, bindingInput{Name: "seed", Source: "src-seed", Workflow: "triage"}) - if err := s.ApproveBinding(t.Context(), seedID); err != nil { - t.Fatalf("ApproveBinding(seed) error = %v", err) - } - mid, err := s.InsertMapping(t.Context(), mapping.Mapping{Name: "seed-map"}) - if err != nil { - t.Fatalf("InsertMapping() error = %v", err) - } - n.reset() - - t.Run("UpdateBinding nonexistent", func(t *testing.T) { - bb := binding.Binding{ID: "missing", Matcher: binding.Matcher{Source: "src-other"}} - if err := s.UpdateBinding(t.Context(), bb); !errors.Is(err, ErrBindingNotFound) { - t.Fatalf("UpdateBinding() error = %v, want ErrBindingNotFound", err) - } - }) - t.Run("ApproveBinding refuses an armed binding", func(t *testing.T) { - if err := s.ApproveBinding(t.Context(), seedID); !errors.Is(err, ErrBindingTransition) { - t.Fatalf("ApproveBinding() error = %v, want ErrBindingTransition", err) - } - }) - t.Run("InsertBinding overlaps source", func(t *testing.T) { - if _, err := s.InsertBinding(t.Context(), binding.Binding{ - Matcher: binding.Matcher{Source: "src-seed"}, - }); !errors.Is(err, ErrBindingOverlap) { - t.Fatalf("InsertBinding() error = %v, want ErrBindingOverlap", err) - } - }) - t.Run("DeleteBinding nonexistent", func(t *testing.T) { - if err := s.DeleteBinding(t.Context(), "missing"); !errors.Is(err, ErrBindingNotFound) { - t.Fatalf("DeleteBinding() error = %v, want ErrBindingNotFound", err) - } - }) - t.Run("UpdateMapping nonexistent", func(t *testing.T) { - if err := s.UpdateMapping(t.Context(), mapping.Mapping{ID: "missing"}); !errors.Is(err, ErrMappingNotFound) { - t.Fatalf("UpdateMapping() error = %v, want ErrMappingNotFound", err) - } - }) - t.Run("DeleteMapping nonexistent", func(t *testing.T) { - if err := s.DeleteMapping(t.Context(), "missing"); !errors.Is(err, ErrMappingNotFound) { - t.Fatalf("DeleteMapping() error = %v, want ErrMappingNotFound", err) - } - }) - _ = mid - - if len(n.got) != 0 { - t.Fatalf("failed writes notified %d times: %+v", len(n.got), n.got) - } -} - -// TestNilNotifierIsNoOp pins that a store composed without a notifier keeps -// every write path working: the existing constructors and tests never set -// one, so a nil-dereference there would break them all. -func TestNilNotifierIsNoOp(t *testing.T) { - s := OpenTest(t) - id, err := s.InsertBinding(t.Context(), binding.Binding{ - Name: "nil-safe", - Matcher: binding.Matcher{Source: "src-nil"}, - }) - if err != nil { - t.Fatalf("InsertBinding with nil notifier: error = %v", err) - } - bb, err := s.GetBinding(t.Context(), id) - if err != nil { - t.Fatalf("GetBinding() error = %v", err) - } - bb.Workflow = "escalate" - if err := s.UpdateBinding(t.Context(), *bb); err != nil { - t.Fatalf("UpdateBinding() error = %v", err) - } - if err := s.ApproveBinding(t.Context(), id); err != nil { - t.Fatalf("ApproveBinding() error = %v", err) - } - if err := s.DeleteBinding(t.Context(), id); err != nil { - t.Fatalf("DeleteBinding() error = %v", err) - } - if _, err := s.InsertMapping(t.Context(), mapping.Mapping{Name: "m"}); err != nil { - t.Fatalf("InsertMapping() error = %v", err) - } -} - -// TestOpenHonoursConfigNotify pins the composition surface: the wire-in sets -// Config.Notify, not the unexported field. -func TestOpenHonoursConfigNotify(t *testing.T) { - n := &recordingNotifier{} - dir := t.TempDir() - s, err := Open(Config{ - DBPath: t.TempDir() + "/eda.sqlite", - DataDir: dir, - Notify: n.notify, - }) - if err != nil { - t.Fatalf("Open() error = %v", err) - } - t.Cleanup(func() { _ = s.Close() }) - - if _, err := s.InsertMapping(t.Context(), mapping.Mapping{Name: "wired"}); err != nil { - t.Fatalf("InsertMapping() error = %v", err) - } - if len(n.got) != 1 { - t.Fatalf("store built from Config.Notify notified %d times, want 1: %+v", len(n.got), n.got) - } -} diff --git a/internal/infrastructure/edastore/opentest.go b/internal/infrastructure/edastore/opentest.go deleted file mode 100644 index 2168e553e..000000000 --- a/internal/infrastructure/edastore/opentest.go +++ /dev/null @@ -1,23 +0,0 @@ -package edastore - -import ( - "path/filepath" - "testing" -) - -// OpenTest builds a throwaway store for tests, closed when the test ends. -// It mirrors store.OpenTest so a test that needs both stores wires them the -// same way. -func OpenTest(t *testing.T) *Store { - t.Helper() - dir := t.TempDir() - s, err := Open(Config{ - DBPath: filepath.Join(dir, "eda.sqlite"), - DataDir: filepath.Join(dir, "pb_data"), - }) - if err != nil { - t.Fatalf("edastore.OpenTest: %v", err) - } - t.Cleanup(func() { _ = s.Close() }) - return s -} diff --git a/internal/infrastructure/edastore/schema.go b/internal/infrastructure/edastore/schema.go deleted file mode 100644 index 42adadac4..000000000 --- a/internal/infrastructure/edastore/schema.go +++ /dev/null @@ -1,218 +0,0 @@ -package edastore - -import ( - "database/sql" - "errors" - "fmt" - "path/filepath" - - "github.com/pocketbase/pocketbase/core" - - "github.com/samcharles93/archie-core/internal/domain/binding" -) - -// isDataDB reports whether PocketBase is asking for its main database, as -// opposed to the auxiliary one it keeps for logs and settings. -func isDataDB(path string) bool { return filepath.Base(path) == "data.db" } - -// removeDefaultAuthCollection deletes the open-signup "users" collection -// PocketBase creates on first bootstrap. This store has no end users, and its -// createRule is open, so leaving it would accept unauthenticated writes. -func removeDefaultAuthCollection(app core.App) error { - c, err := app.FindCollectionByNameOrId("users") - switch { - case errors.Is(err, sql.ErrNoRows): - return nil - case err != nil: - return fmt.Errorf("edastore: look up default users collection: %w", err) - } - if err := app.Delete(c); err != nil { - return fmt.Errorf("edastore: remove default users collection: %w", err) - } - return nil -} - -// ensureCollections creates each collection once and is safe to re-run: the -// store bootstraps on every process start. -func ensureCollections(app core.App) error { - for _, build := range []func(core.App) error{ - ensureCaptures, ensureMappings, ensureBindings, - ensureBindingDispatches, ensurePlaybookDispatches, ensureToolCalls, - } { - if err := build(app); err != nil { - return err - } - } - return nil -} - -// collection returns the named collection, or a new base collection when it -// does not exist yet. A lookup that failed for any other reason is an error: -// creating a second collection over a live one on a transient failure would be -// a schema change made for the wrong reason. -func collection(app core.App, name string) (*core.Collection, bool, error) { - c, err := app.FindCollectionByNameOrId(name) - switch { - case errors.Is(err, sql.ErrNoRows): - return core.NewBaseCollection(name), true, nil - case err != nil: - return nil, false, fmt.Errorf("edastore: look up collection %q: %w", name, err) - } - return c, false, nil -} - -func ensureCaptures(app core.App) error { - c, fresh, err := collection(app, CollCaptures) - if err != nil || !fresh { - return err - } - c.Fields.Add( - &core.TextField{Name: "source", Required: true}, - &core.TextField{Name: "remote_addr"}, - &core.TextField{Name: "content_type"}, - // Headers and body are stored verbatim. Field mapping is designed - // against the real payload, so nothing here may be normalised away. - &core.JSONField{Name: "headers", MaxSize: 1 << 20}, - &core.TextField{Name: "body", Max: 1 << 20}, - &core.BoolField{Name: "authenticated"}, - // received_at is written by the store, not an autodate field, because - // it is also the sort key. PocketBase autodates are millisecond - // precision and record ids are random, so two captures arriving in - // the same millisecond would order arbitrarily -- the old store got - // insertion order free from an autoincrement id. capturedAtLayout is - // fixed-width so lexicographic order is chronological order. - &core.TextField{Name: "received_at"}, - ) - c.AddIndex("idx_captures_source", false, "source, received_at", "") - return save(app, c) -} - -func ensureMappings(app core.App) error { - c, fresh, err := collection(app, CollMappings) - if err != nil || !fresh { - return err - } - c.Fields.Add( - &core.TextField{Name: "name", Required: true}, - &core.TextField{Name: "source_hint"}, - &core.JSONField{Name: "fields", MaxSize: 1 << 18}, - &core.AutodateField{Name: "created_at", OnCreate: true}, - &core.AutodateField{Name: "updated_at", OnCreate: true, OnUpdate: true}, - ) - return save(app, c) -} - -func ensureBindings(app core.App) error { - c, fresh, err := collection(app, CollBindings) - if err != nil { - return err - } - if !fresh { - return promoteDraftBindings(app) - } - mappings, err := app.FindCollectionByNameOrId(CollMappings) - if err != nil { - return fmt.Errorf("edastore: bindings need mappings: %w", err) - } - c.Fields.Add( - &core.TextField{Name: "name", Required: true}, - &core.TextField{Name: "source", Required: true}, - &core.RelationField{Name: "mapping", CollectionId: mappings.Id, MaxSelect: 1}, - &core.TextField{Name: "workflow"}, - &core.TextField{Name: "owner"}, - &core.TextField{Name: "repo"}, - &core.NumberField{Name: "version"}, - // status is the domain's lifecycle, not a local vocabulary: - // pending_approval -> armed. Only ApproveBinding reaches armed, - // which is the epic's approval gate. - &core.SelectField{Name: "status", MaxSelect: 1, Values: []string{ - string(binding.StatusPendingApproval), - string(binding.StatusArmed), - }}, - &core.TextField{Name: "secret"}, - &core.AutodateField{Name: "created_at", OnCreate: true}, - &core.AutodateField{Name: "updated_at", OnCreate: true, OnUpdate: true}, - ) - c.AddIndex("idx_bindings_source_status", false, "source, status", "") - return save(app, c) -} - -// promoteDraftBindings moves bindings an earlier version stored as "draft", -// a state nothing could leave without an unrelated edit, to -// pending_approval so they can be approved. It is a no-op once none remain. -func promoteDraftBindings(app core.App) error { - _, err := app.DB().NewQuery("UPDATE " + CollBindings + " SET status = {:pending} WHERE status = 'draft'"). - Bind(map[string]any{"pending": string(binding.StatusPendingApproval)}).Execute() - if err != nil { - return fmt.Errorf("edastore: promote draft bindings: %w", err) - } - return nil -} - -func ensureBindingDispatches(app core.App) error { - c, fresh, err := collection(app, CollBindingDispatches) - if err != nil || !fresh { - return err - } - c.Fields.Add( - &core.TextField{Name: "binding", Required: true}, - &core.NumberField{Name: "binding_version"}, - &core.TextField{Name: "capture", Required: true}, - // task_id is the seam to the SQLite-owned task tables. It stays a - // plain integer id rather than a relation precisely because the task - // lifecycle is not migrating. - &core.NumberField{Name: "task_id"}, - &core.AutodateField{Name: "dispatched_at", OnCreate: true}, - ) - // At-most-once, enforced by the schema rather than by every caller - // remembering INSERT OR IGNORE. - c.AddIndex("idx_binding_dispatch_once", true, "binding, capture", "") - return save(app, c) -} - -func ensurePlaybookDispatches(app core.App) error { - c, fresh, err := collection(app, CollPlaybookDispatches) - if err != nil || !fresh { - return err - } - c.Fields.Add( - &core.TextField{Name: "playbook_id", Required: true}, - &core.TextField{Name: "playbook_version", Required: true}, - &core.TextField{Name: "event_id", Required: true}, - &core.TextField{Name: "action_id", Required: true}, - &core.AutodateField{Name: "dispatched_at", OnCreate: true}, - ) - c.AddIndex("idx_playbook_dispatch_once", true, - "playbook_id, playbook_version, event_id, action_id", "") - return save(app, c) -} - -// ensureToolCalls adds persistence that did not exist before. Tool calls were -// only ever written to the on-disk task log (internal/logging), so they could -// be read back as text but never queried, filtered or watched. As a collection -// they become all three. -func ensureToolCalls(app core.App) error { - c, fresh, err := collection(app, CollToolCalls) - if err != nil || !fresh { - return err - } - c.Fields.Add( - &core.NumberField{Name: "task_id"}, - &core.NumberField{Name: "attempt"}, - &core.TextField{Name: "tool", Required: true}, - &core.JSONField{Name: "args", MaxSize: 1 << 18}, - &core.JSONField{Name: "result", MaxSize: 1 << 18}, - &core.TextField{Name: "error"}, - &core.NumberField{Name: "duration_ms"}, - &core.AutodateField{Name: "called_at", OnCreate: true}, - ) - c.AddIndex("idx_tool_calls_task", false, "task_id, attempt", "") - return save(app, c) -} - -func save(app core.App, c *core.Collection) error { - if err := app.Save(c); err != nil { - return fmt.Errorf("edastore: create collection %q: %w", c.Name, err) - } - return nil -} diff --git a/internal/infrastructure/edastore/schema_test.go b/internal/infrastructure/edastore/schema_test.go deleted file mode 100644 index de9e73229..000000000 --- a/internal/infrastructure/edastore/schema_test.go +++ /dev/null @@ -1,209 +0,0 @@ -package edastore_test - -import ( - "errors" - "path/filepath" - "testing" - - "github.com/pocketbase/pocketbase/core" - - "github.com/samcharles93/archie-core/internal/domain/binding" - "github.com/samcharles93/archie-core/internal/domain/storecontract" - "github.com/samcharles93/archie-core/internal/infrastructure/edastore" -) - -func newStore(t *testing.T) *edastore.Store { - t.Helper() - dir := t.TempDir() - st, err := edastore.Open(edastore.Config{ - DBPath: filepath.Join(dir, "eda.sqlite"), - DataDir: filepath.Join(dir, "pb_data"), - }) - if err != nil { - t.Fatalf("edastore.Open() error = %v", err) - } - t.Cleanup(func() { _ = st.Close() }) - return st -} - -// TestCollectionsAreCreated pins that every EDA collection exists and is a -// base collection, not a view: unlike the read-only operator surface, these -// are the authoritative tables and the admin UI is expected to edit them. -func TestCollectionsAreCreated(t *testing.T) { - st := newStore(t) - for _, name := range edastore.Collections() { - c, err := st.App().FindCollectionByNameOrId(name) - if err != nil { - t.Fatalf("collection %q missing: %v", name, err) - } - if c.IsView() { - t.Errorf("collection %q is a view; EDA tables are authoritative and must be writable", name) - } - } -} - -// TestBindingDispatchIsIdempotent pins the at-most-once ledger. The SQLite -// implementation got this from INSERT OR IGNORE on a composite primary key -// (bindings.go:365); here it must come from a unique index, so a duplicate is -// refused by the schema rather than by the caller remembering to ignore it. -func TestBindingDispatchIsIdempotent(t *testing.T) { - st := newStore(t) - if err := st.RecordDispatch(t.Context(), "b1", 1, "c1", 42); err != nil { - t.Fatalf("first RecordDispatch() error = %v", err) - } - // A replay of the same (binding, capture) must be refused, not run again. - err := st.RecordDispatch(t.Context(), "b1", 1, "c1", 99) - if !errors.Is(err, storecontract.ErrAlreadyDispatched) { - t.Errorf("second RecordDispatch() error = %v, want ErrAlreadyDispatched: (binding, capture) is an at-most-once ledger", err) - } -} - -// TestPlaybookDispatchIsIdempotent pins the same at-most-once rule on the -// four-part playbook key (playbook, version, event, action). -func TestPlaybookDispatchIsIdempotent(t *testing.T) { - st := newStore(t) - if err := st.RecordPlaybookDispatch(t.Context(), "p1", "v1", "e1", "a1"); err != nil { - t.Fatalf("first RecordPlaybookDispatch() error = %v", err) - } - err := st.RecordPlaybookDispatch(t.Context(), "p1", "v1", "e1", "a1") - if !errors.Is(err, storecontract.ErrAlreadyDispatched) { - t.Errorf("second RecordPlaybookDispatch() error = %v, want ErrAlreadyDispatched", err) - } -} - -// TestBindingStartsPendingApproval pins the approval gate from the epic's -// acceptance criteria: "A binding cannot go live without explicit human -// approval." A new binding awaits that approval and is not live. -func TestBindingStartsPendingApproval(t *testing.T) { - st := newStore(t) - id, err := st.InsertBinding(t.Context(), binding.Binding{ - Name: "n", Matcher: binding.Matcher{Source: "sentry"}, Workflow: "implement", - }) - if err != nil { - t.Fatalf("InsertBinding() error = %v", err) - } - b, err := st.GetBinding(t.Context(), id) - if err != nil { - t.Fatalf("GetBinding() error = %v", err) - } - if b.Status != binding.StatusPendingApproval { - t.Errorf("new binding status = %q, want %q: a binding must not be live before approval", b.Status, binding.StatusPendingApproval) - } -} - -// TestApproveRejectsUnknownBinding pins the sentinel the gRPC layer maps. -func TestApproveRejectsUnknownBinding(t *testing.T) { - st := newStore(t) - if err := st.ApproveBinding(t.Context(), "nosuchbinding"); !errors.Is(err, storecontract.ErrBindingNotFound) { - t.Errorf("ApproveBinding(unknown) error = %v, want ErrBindingNotFound", err) - } -} - -// TestCaptureRoundTripsPayload pins the epic's core requirement: an event -// arrives with a payload nobody has modelled yet and must be readable back -// verbatim so an operator can map fields against it. -func TestCaptureRoundTripsPayload(t *testing.T) { - st := newStore(t) - body := `{"action":"created","issue":{"number":7,"title":"it broke"}}` - if _, err := st.InsertCapture(t.Context(), storecontract.CapturedEvent{ - Source: "sentry", Body: body, Headers: `{"X-Hook":"1"}`, ContentType: "application/json", - }, 0, 0); err != nil { - t.Fatalf("InsertCapture() error = %v", err) - } - list, err := st.ListCaptures(t.Context(), 10) - if err != nil { - t.Fatalf("ListCaptures() error = %v", err) - } - if len(list) != 1 { - t.Fatalf("ListCaptures() returned %d captures, want 1", len(list)) - } - got := list[0] - if got.Body != body { - t.Errorf("Body round-trip = %q, want %q: the raw payload is what field mapping is designed against", got.Body, body) - } -} - -var _ = core.Collection{} - -// TestBindingLifecycleIsThreeStates pins draft -> pending_approval -> armed. -// The states are the domain's, not this package's: collapsing them (as an -// earlier version of this store did) removes the review step while still -// looking like an approval gate, which is the worst of both. -func TestBindingLifecycle(t *testing.T) { - st := newStore(t) - id, err := st.InsertBinding(t.Context(), binding.Binding{ - Name: "n", Matcher: binding.Matcher{Source: "sentry"}, Workflow: "implement", - }) - if err != nil { - t.Fatalf("InsertBinding() error = %v", err) - } - - // It is created awaiting review. - b, err := st.GetBinding(t.Context(), id) - if err != nil || b.Status != binding.StatusPendingApproval { - t.Fatalf("status after insert = %q (err %v), want %q", b.Status, err, binding.StatusPendingApproval) - } - - // Approval arms it, and only from pending_approval. - if err := st.ApproveBinding(t.Context(), id); err != nil { - t.Fatalf("ApproveBinding(pending_approval) error = %v", err) - } - if b, err = st.GetBinding(t.Context(), id); err != nil || b.Status != binding.StatusArmed { - t.Fatalf("status after approve = %q (err %v), want %q", b.Status, err, binding.StatusArmed) - } - if err := st.ApproveBinding(t.Context(), id); !errors.Is(err, storecontract.ErrBindingTransition) { - t.Errorf("re-approving an armed binding = %v, want ErrBindingTransition", err) - } - - // Only armed bindings dispatch. - armed, err := st.ArmedBindingsForSource(t.Context(), "sentry") - if err != nil || len(armed) != 1 { - t.Fatalf("ArmedBindingsForSource() = %d bindings (err %v), want 1", len(armed), err) - } -} - -// TestOneBindingPerSource pins the overlap guard: a second binding on a -// source that already has one is refused, so a capture can never match two. -func TestOneBindingPerSource(t *testing.T) { - st := newStore(t) - mk := func() error { - _, err := st.InsertBinding(t.Context(), binding.Binding{ - Name: "n", Matcher: binding.Matcher{Source: "sentry"}, Workflow: "implement", - }) - return err - } - if err := mk(); err != nil { - t.Fatalf("first InsertBinding() error = %v", err) - } - if err := mk(); !errors.Is(err, storecontract.ErrBindingOverlap) { - t.Errorf("second InsertBinding() error = %v, want ErrBindingOverlap", err) - } -} - -// A binding stored as "draft" by an earlier version could never be approved. -// Opening the store moves it to pending_approval, so it can be. -func TestOpenMovesLegacyDraftBindingsToPendingApproval(t *testing.T) { - dir := t.TempDir() - cfg := edastore.Config{DBPath: filepath.Join(dir, "eda.sqlite"), DataDir: filepath.Join(dir, "pb_data")} - st, err := edastore.Open(cfg) - if err != nil { - t.Fatal(err) - } - id, err := st.InsertBinding(t.Context(), binding.Binding{Name: "n", Matcher: binding.Matcher{Source: "sentry"}, Workflow: "implement"}) - if err != nil { - t.Fatal(err) - } - if _, err := st.App().DB().NewQuery("UPDATE bindings SET status = 'draft' WHERE id = {:id}").Bind(map[string]any{"id": id}).Execute(); err != nil { - t.Fatal(err) - } - _ = st.Close() - - st, err = edastore.Open(cfg) - if err != nil { - t.Fatal(err) - } - t.Cleanup(func() { _ = st.Close() }) - if err := st.ApproveBinding(t.Context(), id); err != nil { - t.Fatalf("ApproveBinding(legacy draft) = %v, want it approvable after reopen", err) - } -} diff --git a/internal/infrastructure/edastore/testsupport_test.go b/internal/infrastructure/edastore/testsupport_test.go deleted file mode 100644 index 3a817a523..000000000 --- a/internal/infrastructure/edastore/testsupport_test.go +++ /dev/null @@ -1,30 +0,0 @@ -package edastore - -import ( - "testing" - - "github.com/samcharles93/archie-core/internal/domain/binding" -) - -// bindingInput is the small shape the cipher tests need, kept separate from -// binding.Binding so a domain field addition does not churn every test. -type bindingInput struct { - Name string - Source string - Workflow string - Secret string -} - -func insertBinding(t *testing.T, s *Store, in bindingInput) string { - t.Helper() - id, err := s.InsertBinding(t.Context(), binding.Binding{ - Name: in.Name, - Matcher: binding.Matcher{Source: in.Source}, - Workflow: in.Workflow, - Secret: in.Secret, - }) - if err != nil { - t.Fatalf("InsertBinding() error = %v", err) - } - return id -} diff --git a/internal/infrastructure/edastore/tool_calls.go b/internal/infrastructure/edastore/tool_calls.go deleted file mode 100644 index 7a72f1e30..000000000 --- a/internal/infrastructure/edastore/tool_calls.go +++ /dev/null @@ -1,98 +0,0 @@ -package edastore - -import ( - "context" - "encoding/json" - "fmt" - "time" - - "github.com/pocketbase/pocketbase/core" -) - -// ToolCall is one completed tool invocation during an agent stage run, as the -// tool_call event projection stores it. The projection adapts the event to the -// existing collection (schema.go): a tool's output summary goes in result, a -// failure's detail in error. The args and duration_ms fields the schema also -// carries are left unwritten -- the tool_call event reports neither -- and a -// future producer that has them can start filling them without a schema -// change. -type ToolCall struct { - ID string - TaskID int64 - Attempt int - Tool string - Result string - Error string - CalledAt time.Time -} - -// InsertToolCall appends one row to the tool_calls collection. There is no -// idempotency here, deliberately: the collection is an append-only transcript -// and the schema carries no unique index (the SQLite predecessor had none -- -// tool calls lived only in the on-disk task log), so one event is one row. -// -// The notify hook stays silent, matching the task-dispatch tables rather than -// the operator-editable ones: tool calls are high-frequency telemetry, not -// dashboard activity. -func (s *Store) InsertToolCall(_ context.Context, tc ToolCall) error { - collection, err := s.app.FindCollectionByNameOrId(CollToolCalls) - if err != nil { - return err - } - r := core.NewRecord(collection) - r.Set("task_id", tc.TaskID) - r.Set("attempt", tc.Attempt) - r.Set("tool", tc.Tool) - if tc.Result != "" { - r.Set("result", tc.Result) - } - if tc.Error != "" { - r.Set("error", tc.Error) - } - if !tc.CalledAt.IsZero() { - // called_at is an autodate field, but an explicitly set date is kept: - // the row carries the time the tool call happened, not the time it - // was projected. - r.Set("called_at", tc.CalledAt) - } - if err := s.app.Save(r); err != nil { - return fmt.Errorf("edastore: insert tool call: %w", err) - } - return nil -} - -// TaskToolCalls returns one task's tool calls in call order. -func (s *Store) TaskToolCalls(_ context.Context, taskID int64) ([]ToolCall, error) { - records, err := s.app.FindRecordsByFilter(CollToolCalls, "task_id = {:task}", "+called_at", 0, 0, - map[string]any{"task": taskID}) - if err != nil { - return nil, fmt.Errorf("edastore: list tool calls: %w", err) - } - out := make([]ToolCall, 0, len(records)) - for _, r := range records { - out = append(out, ToolCall{ - ID: r.Id, - TaskID: r.GetInt64("task_id"), - Attempt: r.GetInt("attempt"), - Tool: r.GetString("tool"), - Result: jsonTextToString(r.GetString("result")), - Error: r.GetString("error"), - CalledAt: r.GetDateTime("called_at").Time(), - }) - } - return out, nil -} - -// jsonTextToString unwraps the JSON string a JSONField stores a plain text -// summary under, and falls back to the raw text for anything that is not a -// JSON string (e.g. an object a future producer stored directly). -func jsonTextToString(raw string) string { - if raw == "" { - return "" - } - var decoded string - if err := json.Unmarshal([]byte(raw), &decoded); err != nil { - return raw - } - return decoded -} diff --git a/internal/infrastructure/edastore/tool_calls_test.go b/internal/infrastructure/edastore/tool_calls_test.go deleted file mode 100644 index d845c977a..000000000 --- a/internal/infrastructure/edastore/tool_calls_test.go +++ /dev/null @@ -1,102 +0,0 @@ -package edastore_test - -import ( - "testing" - "time" - - "github.com/samcharles93/archie-core/internal/infrastructure/edastore" -) - -func insertToolCall(t *testing.T, s *edastore.Store, tc edastore.ToolCall) { - t.Helper() - if err := s.InsertToolCall(t.Context(), tc); err != nil { - t.Fatalf("InsertToolCall() error = %v", err) - } -} - -// TestInsertToolCallRoundTrip pins the write/read pair on the tool_calls -// collection: a row written with the fields the tool_call projection provides -// reads back unchanged, and the read filters on task_id so one task's calls -// never surface in another's. -func TestInsertToolCallRoundTrip(t *testing.T) { - s := newStore(t) - at := time.Date(2026, 9, 23, 1, 2, 3, 0, time.UTC) - - insertToolCall(t, s, edastore.ToolCall{ - TaskID: 42, - Attempt: 2, - Tool: "shell", - Result: "all checks passed", - CalledAt: at, - }) - insertToolCall(t, s, edastore.ToolCall{ - TaskID: 42, - Attempt: 2, - Tool: "read_file", - Error: "no such file", - CalledAt: at.Add(time.Second), - }) - // A different task's call must not leak into the read below. - insertToolCall(t, s, edastore.ToolCall{ - TaskID: 7, - Attempt: 1, - Tool: "shell", - Result: "other task's call", - CalledAt: at.Add(2 * time.Second), - }) - - got, err := s.TaskToolCalls(t.Context(), 42) - if err != nil { - t.Fatalf("TaskToolCalls() error = %v", err) - } - if len(got) != 2 { - t.Fatalf("TaskToolCalls() returned %d rows for task 42, want 2: %+v", len(got), got) - } - - first, second := got[0], got[1] - // Chronological order: the earlier call first. - if first.Tool != "shell" || second.Tool != "read_file" { - t.Errorf("order = [%q, %q], want [shell, read_file] by called_at", first.Tool, second.Tool) - } - if first.TaskID != 42 || first.Attempt != 2 { - t.Errorf("first row task/attempt = %d/%d, want 42/2", first.TaskID, first.Attempt) - } - if first.Result != "all checks passed" { - t.Errorf("first row result = %q, want the stored summary without JSON quoting", first.Result) - } - if first.Error != "" { - t.Errorf("first row error = %q, want empty: a succeeded call is not an error", first.Error) - } - if second.Error != "no such file" { - t.Errorf("second row error = %q, want the stored failure detail", second.Error) - } - if second.Result != "" { - t.Errorf("second row result = %q, want empty: a failed call has no result", second.Result) - } - if first.CalledAt.IsZero() { - t.Error("first row called_at is zero; the call time must round-trip") - } -} - -// TestInsertToolCallIsAnAppendOnlyTranscript pins that the collection is one -// row per tool call, not an upsert: repeated calls with the same (task, -// attempt, tool) are distinct transcript entries. There is no unique index and -// there must not be one -- the SQLite predecessor had none (tool calls lived -// only in the on-disk task log), so the schema's non-unique (task_id, attempt) -// index stays the only one. -func TestInsertToolCallIsAnAppendOnlyTranscript(t *testing.T) { - s := newStore(t) - at := time.Date(2026, 9, 23, 1, 2, 3, 0, time.UTC) - row := edastore.ToolCall{TaskID: 42, Attempt: 3, Tool: "shell", Result: "ok", CalledAt: at} - - insertToolCall(t, s, row) - insertToolCall(t, s, row) - - got, err := s.TaskToolCalls(t.Context(), 42) - if err != nil { - t.Fatalf("TaskToolCalls() error = %v", err) - } - if len(got) != 2 { - t.Fatalf("TaskToolCalls() returned %d rows, want 2: the transcript is append-only, not a dedup ledger", len(got)) - } -} diff --git a/internal/releaseupdate/install_script_test.go b/internal/releaseupdate/install_script_test.go index 021632866..21ba0dfc9 100644 --- a/internal/releaseupdate/install_script_test.go +++ b/internal/releaseupdate/install_script_test.go @@ -2,7 +2,6 @@ package releaseupdate import ( "bufio" - "database/sql" "encoding/json" "net" "net/http" @@ -13,8 +12,6 @@ import ( "strconv" "strings" "testing" - - _ "modernc.org/sqlite" ) func TestUpdateInstallGatewayOnlySkipsRuntimeWork(t *testing.T) { @@ -236,91 +233,6 @@ func TestUpdateWatchdogDefaultHealthURLTargetsTheDaemon(t *testing.T) { } } -func TestUpdateWatchdogRestoresTaskDatabaseOnDaemonRollback(t *testing.T) { - root, err := filepath.Abs(filepath.Join("..", "..")) - if err != nil { - t.Fatal(err) - } - work := t.TempDir() - binDir, fakeDir := filepath.Join(work, "bin"), filepath.Join(work, "fake-bin") - reportPath := filepath.Join(work, "report.json") - dbPath, backupPath := filepath.Join(work, "tasks.sqlite"), filepath.Join(work, "tasks.prev.sqlite") - if err := os.MkdirAll(binDir, 0o755); err != nil { - t.Fatal(err) - } - for name, content := range map[string]string{"archied": "new", "archied.prev": "old"} { - if err := os.WriteFile(filepath.Join(binDir, name), []byte(content), 0o755); err != nil { - t.Fatal(err) - } - } - for path, version := range map[string]int{dbPath: 2, backupPath: 1} { - createSQLiteDatabase(t, path, version) - } - callsPath := filepath.Join(work, "calls") - writeFakeCommand(t, fakeDir, "systemctl", `printf '%s\n' "systemctl $*" >> "$ARCHIE_TEST_CALLS"`) - writeFakeCommand(t, fakeDir, "cp", `printf '%s\n' "cp $*" >> "$ARCHIE_TEST_CALLS"; /usr/bin/cp "$@"`) - writeFakeCommand(t, fakeDir, "curl", `exit 1`) - cmd := exec.CommandContext(t.Context(), filepath.Join(root, "scripts", "archie-update-watchdog")) - cmd.Env = append(os.Environ(), "PATH="+fakeDir+":"+os.Getenv("PATH"), "ARCHIE_BIN_DIR="+binDir, - "ARCHIE_TEST_CALLS="+callsPath, - "ARCHIE_UPDATE_REPORT_PATH="+reportPath, "ARCHIE_UPDATE_HEALTH_TIMEOUT=0", "ARCHIE_UPDATE_COMPONENTS=daemon", - "ARCHIE_UPDATE_PREVIOUS_GATEWAY=1.19.10", "ARCHIE_UPDATE_INSTALLED_GATEWAY=1.20.0", - "ARCHIE_TASK_DB_PATH="+dbPath, "ARCHIE_TASK_DB_BACKUP="+backupPath) - if output, err := cmd.CombinedOutput(); err != nil { - t.Fatalf("watchdog failed: %v\n%s", err, output) - } - db, err := sql.Open("sqlite", dbPath) - if err != nil { - t.Fatal(err) - } - defer db.Close() - var version int - if err := db.QueryRowContext(t.Context(), "PRAGMA user_version").Scan(&version); err != nil { - t.Fatal(err) - } - if version != 1 { - t.Fatalf("restored schema version = %d, want 1", version) - } - calls, err := os.ReadFile(callsPath) - if err != nil { - t.Fatal(err) - } - callLines := strings.Split(strings.TrimSpace(string(calls)), "\n") - stopIndex, copyIndex, startIndex := -1, -1, -1 - for i, line := range callLines { - switch line { - case "systemctl --user stop archied.service": - stopIndex = i - case "systemctl --user restart archied.service": - startIndex = i - } - if strings.HasPrefix(line, "cp ") && strings.Contains(line, "tasks.prev.sqlite") { - copyIndex = i - } - } - if stopIndex < 0 || copyIndex < 0 || stopIndex > copyIndex { - t.Fatalf("rollback must stop service before restoring database; calls = %q", calls) - } - if startIndex < 0 || startIndex <= copyIndex { - t.Fatalf("rollback must restart service after restoring database; calls = %q", calls) - } -} - -func createSQLiteDatabase(t *testing.T, path string, version int) { - t.Helper() - db, err := sql.Open("sqlite", path) - if err != nil { - t.Fatalf("open database %s: %v", path, err) - } - defer db.Close() - if _, err := db.ExecContext(t.Context(), "PRAGMA user_version = "+strconv.Itoa(version)); err != nil { - t.Fatalf("set database version for %s: %v", path, err) - } - if _, err := db.ExecContext(t.Context(), "CREATE TABLE tasks (id INTEGER)"); err != nil { - t.Fatalf("create tasks table in %s: %v", path, err) - } -} - func runUpdateInstallScript(t *testing.T, environment map[string]string) (Result, []string) { t.Helper() result, calls, _ := runUpdateInstall(t, environment, false) @@ -406,13 +318,11 @@ esac `) writeFakeCommand(t, fakeDir, "go", ` printf '%s\n' "go $*" >> "$ARCHIE_TEST_CALLS" -# The pre-flight task-database backup runs through the release's own +# The pre-flight database snapshot runs through the release's own # archie-state-store subcommand, so a release whose recovery path cannot run # must refuse the update. if [ "$1" = "run" ]; then - [ "${ARCHIE_TEST_GO_FAILS_RUN:-}" = "1" ] && exit 1 - # The PostgreSQL snapshot is the backup run that names no -db file. - [ "${ARCHIE_TEST_GO_FAILS_SNAPSHOT:-}" = "1" ] && [[ " $* " != *" -db "* ]] && exit 1 + [ "${ARCHIE_TEST_GO_FAILS_SNAPSHOT:-}" = "1" ] && exit 1 exit 0 fi out="" @@ -471,22 +381,6 @@ printf '%s\n' "install $*" >> "$ARCHIE_TEST_CALLS" printf '%s\n' "cp $*" >> "$ARCHIE_TEST_CALLS" /usr/bin/cp "$@" `) - writeFakeCommand(t, fakeDir, "sqlite3", ` -printf '%s\n' "sqlite3 $*" >> "$ARCHIE_TEST_CALLS" -[ "${ARCHIE_TEST_SQLITE3_FAILS:-}" = "1" ] && exit 1 -# Reproduce ".backup ''" by writing a plausible backup beside the -# source, so the watchdog's existence check behaves as it would in production. -for arg in "$@"; do - case "$arg" in - .backup*) target="$(printf '%s' "$arg" | sed "s/^\.backup[[:space:]]*//; s/^'//; s/'$//")" ;; - esac -done -if [ -n "${target:-}" ]; then - mkdir -p "$(dirname "$target")" - printf 'backup\n' > "$target" -fi -`) - // The production adapter prepends /usr/local/go/bin. Run an otherwise // byte-for-byte copy with the harness PATH left first so fake go records // build intent without compiling or touching Docker/systemd. @@ -877,105 +771,6 @@ func TestUpdateWatchdogCyclesEveryUnitInDependencyOrder(t *testing.T) { } } -// The updater must back up the database the daemon actually uses, which is -// `-tasks.sqlite` (taskDBPath in internal/app/archied/main.go), not -// the configured path itself. The configured path may be a zero-byte -// placeholder while the real store sits beside it -- so backing the literal -// value up produces an empty backup, and a rollback then restores that empty -// file over the database and deletes its -wal/-shm. A rollback that destroys -// the task store is worse than no rollback. -// -// The snapshot is taken by the release's own recovery subcommand rather than -// by hand-rolled shell, so the installer and an operator run the same code and -// the two cannot drift apart. -func TestUpdateInstallBacksUpTheSiblingTaskDatabase(t *testing.T) { - work := t.TempDir() - configured := filepath.Join(work, "archie.db") - realStore := configured + "-tasks.sqlite" - if err := os.WriteFile(configured, nil, 0o600); err != nil { - t.Fatal(err) - } - if err := os.WriteFile(realStore, []byte("real task data"), 0o600); err != nil { - t.Fatal(err) - } - backup := filepath.Join(work, "backup.sqlite") - - _, calls, _ := runUpdateInstallWithConfig(t, map[string]string{ - "ARCHIE_UPDATE_DAEMON_PREVIOUS": "1.22.0", - "ARCHIE_UPDATE_DAEMON_VERSION": "1.23.0", - "ARCHIE_UPDATE_AGENT_PREVIOUS": "1.21.0", - "ARCHIE_TASK_DB_BACKUP": backup, - }, "db_path = \""+configured+"\"\n\n[containers]\nimage = 'registry.example/archie-agent:stable'\n", false) - - assertCallContains(t, calls, "go run ./cmd/archie-state-store backup", "-db "+realStore, "-out "+backup) - assertCallAbsent(t, calls, "sqlite3") - assertCallContains(t, calls, "systemd-run", "--setenv=ARCHIE_TASK_DB_PATH="+realStore) - // The zero-byte placeholder is not the store, and must never be the thing - // handed to the watchdog as ARCHIE_TASK_DB_PATH. - assertCallAbsent(t, calls, "--setenv=ARCHIE_TASK_DB_PATH="+configured+" ") -} - -// db_path can also appear under a TOML table -- the retired [indexing] section -// once owned its own database there, and a future section could do the same. -// Reading the first match in the file can select an unrelated database, so the -// value must come from the daemon's own top-level key. -func TestUpdateInstallIgnoresDbPathFromOtherSections(t *testing.T) { - work := t.TempDir() - configured := filepath.Join(work, "archie.db") - realStore := configured + "-tasks.sqlite" - indexStore := filepath.Join(work, "workspace-indexes.db") - for path, content := range map[string]string{realStore: "real task data", indexStore: "index data"} { - if err := os.WriteFile(path, []byte(content), 0o600); err != nil { - t.Fatal(err) - } - } - backup := filepath.Join(work, "backup.sqlite") - - _, calls, _ := runUpdateInstallWithConfig(t, map[string]string{ - "ARCHIE_UPDATE_DAEMON_PREVIOUS": "1.22.0", - "ARCHIE_UPDATE_DAEMON_VERSION": "1.23.0", - "ARCHIE_UPDATE_AGENT_PREVIOUS": "1.21.0", - "ARCHIE_TASK_DB_BACKUP": backup, - }, "db_path = \""+configured+"\"\n\n[indexing]\ndb_path = \""+indexStore+"\"\n\n[containers]\nimage = 'registry.example/archie-agent:stable'\n", false) - - assertCallContains(t, calls, "go run ./cmd/archie-state-store backup", "-db "+realStore) - for _, call := range calls { - if strings.Contains(call, "go run ./cmd/archie-state-store backup") && strings.Contains(call, indexStore) { - t.Errorf("backed up the other section's database %s: %q", indexStore, call) - } - } - assertCallAbsent(t, calls, "--setenv=ARCHIE_TASK_DB_PATH="+indexStore) -} - -// A store that cannot be backed up must fail the update before anything is -// replaced. Installing with no usable rollback is how a failed update becomes -// a destroyed task store. -func TestUpdateInstallRefusesWhenTaskDatabaseCannotBeBackedUp(t *testing.T) { - work := t.TempDir() - configured := filepath.Join(work, "archie.db") - if err := os.WriteFile(configured+"-tasks.sqlite", []byte("data"), 0o600); err != nil { - t.Fatal(err) - } - _, calls, output := runUpdateInstallWithConfig(t, map[string]string{ - "ARCHIE_UPDATE_DAEMON_PREVIOUS": "1.22.0", - "ARCHIE_UPDATE_DAEMON_VERSION": "1.23.0", - "ARCHIE_UPDATE_AGENT_PREVIOUS": "1.21.0", - "ARCHIE_TEST_GO_FAILS_RUN": "1", - }, "db_path = \""+configured+"\"\n\n[containers]\nimage = 'registry.example/archie-agent:stable'\n", true) - - if !strings.Contains(output, "task database") { - t.Errorf("refusal must name the task database; output = %q", output) - } - // Nothing of the release may be placed on the host, and no backup of the - // failure path may be attempted either. - for _, call := range calls { - if strings.Contains(call, "install -m755") && !strings.Contains(call, "/scripts/") { - t.Errorf("refused update still installed %q", call) - } - } - assertCallAbsent(t, calls, "arhied.prev") -} - // The sidecar is the only record of the managed agent version, and // archie-update-check refuses anything but a bare release version, so a stray // escape in the write leaves the installed agent reported as unknown forever. diff --git a/internal/store/apply_status.go b/internal/store/apply_status.go deleted file mode 100644 index f9b493cee..000000000 --- a/internal/store/apply_status.go +++ /dev/null @@ -1,77 +0,0 @@ -package store - -import ( - "context" - "fmt" - "time" -) - -const applyStatusSchema = ` -CREATE TABLE IF NOT EXISTS apply_status ( - process TEXT NOT NULL, - kind TEXT NOT NULL, - applied_version INTEGER NOT NULL DEFAULT 0, - error TEXT NOT NULL DEFAULT '', - reported_at TEXT NOT NULL, - PRIMARY KEY (process, kind) -); -` - -// applyStatusTimeLayout matches the rest of the store's timestamp columns. -const applyStatusTimeLayout = time.RFC3339 - -// PutApplyStatus records what one process applied for one resource kind. The -// key is (process, kind) and a report replaces its own row: a process -// re-stamps on an interval, and a history of re-stamps is not something any -// reader wants. -func (s *Store) PutApplyStatus(ctx context.Context, status ApplyStatus) error { - reported := status.ReportedAt - if reported.IsZero() { - reported = time.Now() - } - _, err := s.db.ExecContext(ctx, ` - INSERT INTO apply_status (process, kind, applied_version, error, reported_at) - VALUES (?, ?, ?, ?, ?) - ON CONFLICT(process, kind) DO UPDATE SET - applied_version=excluded.applied_version, - error=excluded.error, - reported_at=excluded.reported_at`, - status.Process, status.Kind, status.AppliedVersion, status.Error, - reported.UTC().Format(applyStatusTimeLayout)) - if err != nil { - return fmt.Errorf("store: put apply status: %w", err) - } - return nil -} - -// ListApplyStatus returns every process's report. An empty slice is the -// normal state of a store whose processes have not booted yet, not an error. -func (s *Store) ListApplyStatus(ctx context.Context) ([]ApplyStatus, error) { - rows, err := s.db.QueryContext(ctx, ` - SELECT process, kind, applied_version, error, reported_at - FROM apply_status ORDER BY process, kind`) - if err != nil { - return nil, fmt.Errorf("store: list apply status: %w", err) - } - defer rows.Close() - - statuses := []ApplyStatus{} - for rows.Next() { - var ( - status ApplyStatus - reported string - ) - if err := rows.Scan(&status.Process, &status.Kind, &status.AppliedVersion, &status.Error, &reported); err != nil { - return nil, fmt.Errorf("store: scan apply status: %w", err) - } - status.ReportedAt, err = time.Parse(applyStatusTimeLayout, reported) - if err != nil { - return nil, fmt.Errorf("store: parse apply status time: %w", err) - } - statuses = append(statuses, status) - } - if err := rows.Err(); err != nil { - return nil, fmt.Errorf("store: list apply status: %w", err) - } - return statuses, nil -} diff --git a/internal/store/apply_status_test.go b/internal/store/apply_status_test.go deleted file mode 100644 index 52fe51af7..000000000 --- a/internal/store/apply_status_test.go +++ /dev/null @@ -1,92 +0,0 @@ -package store - -import ( - "testing" - "time" -) - -// TestApplyStatusReplacesPerProcessAndKind pins the key: a process re-stamping -// its report must overwrite its own row, not append one, or the settings page -// accumulates a row per report and cannot say which is current. -func TestApplyStatusReplacesPerProcessAndKind(t *testing.T) { - s := openTest(t) - first := time.Date(2026, 9, 21, 10, 0, 0, 0, time.UTC) - - for _, status := range []ApplyStatus{ - {Process: "archied", Kind: "model-role-assignments", AppliedVersion: 3, ReportedAt: first}, - {Process: "archied", Kind: "repository-policies", AppliedVersion: 5, ReportedAt: first}, - {Process: "archie-gateway", Kind: "model-role-assignments", AppliedVersion: 2, ReportedAt: first}, - } { - if err := s.PutApplyStatus(t.Context(), status); err != nil { - t.Fatalf("PutApplyStatus(%s/%s): %v", status.Process, status.Kind, err) - } - } - - restamp := first.Add(30 * time.Second) - if err := s.PutApplyStatus(t.Context(), ApplyStatus{ - Process: "archied", Kind: "model-role-assignments", AppliedVersion: 4, ReportedAt: restamp, - }); err != nil { - t.Fatalf("re-stamp: %v", err) - } - - got, err := s.ListApplyStatus(t.Context()) - if err != nil { - t.Fatalf("ListApplyStatus: %v", err) - } - if len(got) != 3 { - t.Fatalf("ListApplyStatus returned %d records, want 3: %+v", len(got), got) - } - for _, record := range got { - if record.Process != "archied" || record.Kind != "model-role-assignments" { - continue - } - if record.AppliedVersion != 4 { - t.Errorf("AppliedVersion = %d, want the re-stamped 4", record.AppliedVersion) - } - if !record.ReportedAt.Equal(restamp) { - t.Errorf("ReportedAt = %v, want the re-stamped %v", record.ReportedAt, restamp) - } - } -} - -// TestApplyStatusKeepsAppliedVersionWhenReportingAnError pins that a rejected -// edit does not erase the fact that an older version is still live. -func TestApplyStatusKeepsAppliedVersionWhenReportingAnError(t *testing.T) { - s := openTest(t) - at := time.Date(2026, 9, 21, 10, 0, 0, 0, time.UTC) - if err := s.PutApplyStatus(t.Context(), ApplyStatus{ - Process: "archied", Kind: "tool-settings", AppliedVersion: 7, ReportedAt: at, - }); err != nil { - t.Fatalf("PutApplyStatus: %v", err) - } - if err := s.PutApplyStatus(t.Context(), ApplyStatus{ - Process: "archied", Kind: "tool-settings", AppliedVersion: 7, - Error: "validate database settings: bad policy", ReportedAt: at.Add(time.Minute), - }); err != nil { - t.Fatalf("PutApplyStatus with error: %v", err) - } - - got, err := s.ListApplyStatus(t.Context()) - if err != nil { - t.Fatalf("ListApplyStatus: %v", err) - } - if len(got) != 1 { - t.Fatalf("ListApplyStatus returned %d records, want 1", len(got)) - } - if got[0].AppliedVersion != 7 || got[0].Error == "" { - t.Fatalf("record = %+v, want version 7 still live alongside the error", got[0]) - } -} - -// TestListApplyStatusEmptyIsNotAnError pins the list convention: nothing has -// reported yet is the normal state of a store whose processes have not booted, -// and it is an empty slice rather than an error or a found=false. -func TestListApplyStatusEmptyIsNotAnError(t *testing.T) { - got, err := openTest(t).ListApplyStatus(t.Context()) - if err != nil { - t.Fatalf("ListApplyStatus on an empty store: %v", err) - } - if len(got) != 0 { - t.Fatalf("ListApplyStatus returned %d records, want none", len(got)) - } -} diff --git a/internal/store/channel_status.go b/internal/store/channel_status.go deleted file mode 100644 index c5473990b..000000000 --- a/internal/store/channel_status.go +++ /dev/null @@ -1,106 +0,0 @@ -package store - -import ( - "context" - "fmt" - "time" -) - -const channelStatusSchema = ` -CREATE TABLE IF NOT EXISTS channel_status ( - id TEXT PRIMARY KEY, - name TEXT NOT NULL DEFAULT '', - state TEXT NOT NULL DEFAULT '', - detail TEXT NOT NULL DEFAULT '', - configured INTEGER NOT NULL DEFAULT 0, - reload_supported INTEGER NOT NULL DEFAULT 0, - observed_at TEXT NOT NULL -); -` - -// PutChannelStatus records the reporting process's whole set, in one -// transaction: rows it no longer reports are deleted, so a channel that stopped -// or was removed does not linger as a stale "running" the dashboard would show -// indefinitely. -func (s *Store) PutChannelStatus(ctx context.Context, channels []ChannelStatus) error { - tx, err := s.db.BeginTx(ctx, nil) - if err != nil { - return fmt.Errorf("store: put channel status: begin: %w", err) - } - defer func() { _ = tx.Rollback() }() - - reported := make([]any, 0, len(channels)+1) - placeholders := make([]byte, 0, len(channels)*2) - for index, channel := range channels { - if channel.ID == "" { - return fmt.Errorf("store: put channel status: a channel needs an id") - } - if index > 0 { - placeholders = append(placeholders, ',') - } - placeholders = append(placeholders, '?') - reported = append(reported, channel.ID) - - observed := channel.ObservedAt - if observed.IsZero() { - observed = time.Now() - } - if _, err := tx.ExecContext(ctx, ` - INSERT INTO channel_status (id, name, state, detail, configured, reload_supported, observed_at) - VALUES (?, ?, ?, ?, ?, ?, ?) - ON CONFLICT(id) DO UPDATE SET - name=excluded.name, - state=excluded.state, - detail=excluded.detail, - configured=excluded.configured, - reload_supported=excluded.reload_supported, - observed_at=excluded.observed_at`, - channel.ID, channel.Name, channel.State, channel.Detail, - channel.Configured, channel.ReloadSupported, observed.UTC().Format(configSnapshotTimeLayout)); err != nil { - return fmt.Errorf("store: put channel status %s: %w", channel.ID, err) - } - } - - // An empty report is a real report -- the process hosts no channels -- and it - // clears the table rather than leaving the previous set standing. - query := `DELETE FROM channel_status` - if len(reported) > 0 { - query += ` WHERE id NOT IN (` + string(placeholders) + `)` - } - if _, err := tx.ExecContext(ctx, query, reported...); err != nil { - return fmt.Errorf("store: put channel status: prune: %w", err) - } - return tx.Commit() -} - -// ChannelStatus returns every reported channel, ordered by id so a reader and a -// test see the same order twice. -func (s *Store) ChannelStatus(ctx context.Context) ([]ChannelStatus, error) { - rows, err := s.db.QueryContext(ctx, ` - SELECT id, name, state, detail, configured, reload_supported, observed_at - FROM channel_status ORDER BY id`) - if err != nil { - return nil, fmt.Errorf("store: list channel status: %w", err) - } - defer func() { _ = rows.Close() }() - - var channels []ChannelStatus - for rows.Next() { - var ( - channel ChannelStatus - observed string - ) - if err := rows.Scan(&channel.ID, &channel.Name, &channel.State, &channel.Detail, - &channel.Configured, &channel.ReloadSupported, &observed); err != nil { - return nil, fmt.Errorf("store: scan channel status: %w", err) - } - if at, err := time.Parse(configSnapshotTimeLayout, observed); err == nil { - channel.ObservedAt = at - } - channels = append(channels, channel) - } - if err := rows.Err(); err != nil { - return nil, fmt.Errorf("store: list channel status: %w", err) - } - return channels, nil -} diff --git a/internal/store/channel_status_test.go b/internal/store/channel_status_test.go deleted file mode 100644 index 94fb5b1a1..000000000 --- a/internal/store/channel_status_test.go +++ /dev/null @@ -1,79 +0,0 @@ -package store - -import ( - "testing" - "time" -) - -// TestChannelStatusReplacesTheReportedSet: the process hosting the channels owns -// the set it reports, so a channel it stops reporting must disappear. Leaving it -// behind would show a stale "running" for a channel that is gone, which is worse -// than showing nothing. -func TestChannelStatusReplacesTheReportedSet(t *testing.T) { - st := openTest(t) - ctx := t.Context() - - if rows, err := st.ChannelStatus(ctx); err != nil || len(rows) != 0 { - t.Fatalf("ChannelStatus on an empty store = (%+v, %v), want (none, nil)", rows, err) - } - - observed := time.Date(2026, 9, 22, 8, 0, 0, 0, time.UTC) - first := []ChannelStatus{ - {ID: "telegram", Name: "telegram", State: "running", Configured: true, ReloadSupported: true, ObservedAt: observed}, - {ID: "webhook", Name: "webhook", State: "failed", Detail: "listen: address in use", Configured: true, ObservedAt: observed}, - } - if err := st.PutChannelStatus(ctx, first); err != nil { - t.Fatalf("PutChannelStatus: %v", err) - } - rows, err := st.ChannelStatus(ctx) - if err != nil { - t.Fatalf("ChannelStatus: %v", err) - } - if len(rows) != 2 { - t.Fatalf("rows = %+v, want both channels", rows) - } - // Ordered by id, so a reader and this test see the same list twice. - if rows[0].ID != "telegram" || rows[1].ID != "webhook" { - t.Errorf("rows = %+v, want telegram then webhook", rows) - } - if rows[1].Detail != "listen: address in use" || rows[1].State != "failed" { - t.Errorf("webhook row = %+v, want the failure it reported", rows[1]) - } - if !rows[0].ReloadSupported || !rows[0].Configured { - t.Errorf("telegram row = %+v, want its declared capabilities", rows[0]) - } - if !rows[0].ObservedAt.Equal(observed) { - t.Errorf("ObservedAt = %v, want %v", rows[0].ObservedAt, observed) - } - - // The reporter no longer mentions webhook: its row goes. - if err := st.PutChannelStatus(ctx, first[:1]); err != nil { - t.Fatalf("PutChannelStatus: %v", err) - } - rows, err = st.ChannelStatus(ctx) - if err != nil { - t.Fatalf("ChannelStatus: %v", err) - } - if len(rows) != 1 || rows[0].ID != "telegram" { - t.Fatalf("rows = %+v, want only telegram after the shorter report", rows) - } - - // An empty report is a report: a process that hosts no channels clears the set - // rather than leaving the previous one standing. - if err := st.PutChannelStatus(ctx, nil); err != nil { - t.Fatalf("PutChannelStatus(empty): %v", err) - } - if rows, err := st.ChannelStatus(ctx); err != nil || len(rows) != 0 { - t.Fatalf("rows after an empty report = (%+v, %v), want none", rows, err) - } -} - -// TestChannelStatusRequiresAnID: a row without an id cannot be replaced or -// removed by a later report, so it is refused at the producer rather than -// inserted as an orphan the reporter can never clear. -func TestChannelStatusRequiresAnID(t *testing.T) { - st := openTest(t) - if err := st.PutChannelStatus(t.Context(), []ChannelStatus{{State: "running"}}); err == nil { - t.Fatal("PutChannelStatus with no id = nil, want a refusal") - } -} diff --git a/internal/store/config_snapshot.go b/internal/store/config_snapshot.go deleted file mode 100644 index 97dc680a7..000000000 --- a/internal/store/config_snapshot.go +++ /dev/null @@ -1,69 +0,0 @@ -package store - -import ( - "context" - "database/sql" - "errors" - "fmt" - "time" -) - -const configSnapshotSchema = ` -CREATE TABLE IF NOT EXISTS config_snapshot ( - id INTEGER PRIMARY KEY CHECK (id = 1), - schema TEXT NOT NULL DEFAULT '', - document TEXT NOT NULL DEFAULT '', - published_at TEXT NOT NULL -); -` - -// configSnapshotTimeLayout follows the rest of the store's timestamp columns: -// fixed-width, so string and chronological order agree. -const configSnapshotTimeLayout = time.RFC3339 - -// PutConfigSnapshot replaces the published snapshot. One running -// configuration means one row, so a republish overwrites rather than -// appending a history nothing reads. -func (s *Store) PutConfigSnapshot(ctx context.Context, snapshot ConfigSnapshot) error { - published := snapshot.PublishedAt - if published.IsZero() { - published = time.Now() - } - _, err := s.db.ExecContext(ctx, ` - INSERT INTO config_snapshot (id, schema, document, published_at) - VALUES (1, ?, ?, ?) - ON CONFLICT(id) DO UPDATE SET - schema=excluded.schema, - document=excluded.document, - published_at=excluded.published_at`, - snapshot.Schema, string(snapshot.Document), published.UTC().Format(configSnapshotTimeLayout)) - if err != nil { - return fmt.Errorf("store: put config snapshot: %w", err) - } - return nil -} - -// ConfigSnapshot returns the published snapshot. found is false, with a nil -// error, before anything has published one -- the normal state of a store -// whose daemon has not booted yet. -func (s *Store) ConfigSnapshot(ctx context.Context) (ConfigSnapshot, bool, error) { - var ( - snapshot ConfigSnapshot - document string - published string - ) - err := s.db.QueryRowContext(ctx, ` - SELECT schema, document, published_at FROM config_snapshot WHERE id = 1`). - Scan(&snapshot.Schema, &document, &published) - if errors.Is(err, sql.ErrNoRows) { - return ConfigSnapshot{}, false, nil - } - if err != nil { - return ConfigSnapshot{}, false, fmt.Errorf("store: read config snapshot: %w", err) - } - snapshot.Document = []byte(document) - if at, err := time.Parse(configSnapshotTimeLayout, published); err == nil { - snapshot.PublishedAt = at - } - return snapshot, true, nil -} diff --git a/internal/store/config_snapshot_test.go b/internal/store/config_snapshot_test.go deleted file mode 100644 index 6ee5d83ee..000000000 --- a/internal/store/config_snapshot_test.go +++ /dev/null @@ -1,63 +0,0 @@ -package store - -import ( - "testing" - "time" -) - -// TestConfigSnapshotRoundTrip: the daemon publishes the dashboard's -// configuration projection here and the UI process reads it, so the document -// has to come back byte-identical and the newest publish has to win. There is -// one running configuration, so there is one row. -func TestConfigSnapshotRoundTrip(t *testing.T) { - st := openTest(t) - ctx := t.Context() - - if _, found, err := st.ConfigSnapshot(ctx); err != nil || found { - t.Fatalf("ConfigSnapshot on an empty store = (found %v, %v), want (false, nil)", found, err) - } - - first := ConfigSnapshot{ - Schema: "webui.ConfigView/1", - Document: []byte(`{"identity":{"bot_user":"archie"}}`), - PublishedAt: time.Date(2026, 9, 9, 10, 0, 0, 0, time.UTC), - } - if err := st.PutConfigSnapshot(ctx, first); err != nil { - t.Fatalf("PutConfigSnapshot: %v", err) - } - - got, found, err := st.ConfigSnapshot(ctx) - if err != nil || !found { - t.Fatalf("ConfigSnapshot = (found %v, %v), want it stored", found, err) - } - if got.Schema != first.Schema || string(got.Document) != string(first.Document) { - t.Fatalf("snapshot = %+v, want %+v", got, first) - } - if !got.PublishedAt.Equal(first.PublishedAt) { - t.Fatalf("published at = %v, want %v", got.PublishedAt, first.PublishedAt) - } - - second := ConfigSnapshot{ - Schema: "webui.ConfigView/1", - Document: []byte(`{"identity":{"bot_user":"archie-2"}}`), - PublishedAt: first.PublishedAt.Add(time.Hour), - } - if err := st.PutConfigSnapshot(ctx, second); err != nil { - t.Fatalf("republish: %v", err) - } - got, found, err = st.ConfigSnapshot(ctx) - if err != nil || !found { - t.Fatalf("ConfigSnapshot after republish = (found %v, %v)", found, err) - } - if string(got.Document) != string(second.Document) { - t.Fatalf("document = %s, want the republished %s", got.Document, second.Document) - } - - var rows int - if err := st.db.QueryRowContext(ctx, `SELECT count(*) FROM config_snapshot`).Scan(&rows); err != nil { - t.Fatal(err) - } - if rows != 1 { - t.Fatalf("config_snapshot holds %d rows, want exactly 1: republishing replaces, it does not accumulate", rows) - } -} diff --git a/internal/store/events.go b/internal/store/events.go deleted file mode 100644 index d860ef832..000000000 --- a/internal/store/events.go +++ /dev/null @@ -1,277 +0,0 @@ -package store - -import ( - "context" - "database/sql" - "encoding/json" - "errors" - "fmt" - "time" - - "github.com/samcharles93/archie-core/internal/domain/storecontract" - "github.com/samcharles93/archie-core/internal/domain/workflow" - "github.com/samcharles93/archie-core/internal/events" -) - -const eventsSchema = ` -CREATE TABLE IF NOT EXISTS events ( - id INTEGER PRIMARY KEY AUTOINCREMENT, - at TEXT NOT NULL, - kind TEXT NOT NULL, - task_id INTEGER NOT NULL DEFAULT 0, - repo TEXT NOT NULL DEFAULT '', - issue INTEGER NOT NULL DEFAULT 0, - workflow TEXT NOT NULL DEFAULT '', - stage TEXT NOT NULL DEFAULT '', - attempt INTEGER NOT NULL DEFAULT 0, - actor_id TEXT NOT NULL DEFAULT '', - actor_kind TEXT NOT NULL DEFAULT '', - principal_id TEXT NOT NULL DEFAULT '', - detail TEXT NOT NULL DEFAULT '', - data TEXT NOT NULL DEFAULT '{}' -); -CREATE INDEX IF NOT EXISTS idx_events_task ON events(task_id, id); -CREATE INDEX IF NOT EXISTS idx_events_kind ON events(kind, id); -CREATE INDEX IF NOT EXISTS idx_events_at ON events(at, id); -` - -// InsertEvent appends an event to the log and returns its row id. -func (s *Store) InsertEvent(ctx context.Context, e events.Event) (int64, error) { - return insertEvent(ctx, s.db, e) -} - -type eventExecer interface { - ExecContext(context.Context, string, ...any) (sql.Result, error) -} - -func insertEvent(ctx context.Context, execer eventExecer, e events.Event) (int64, error) { - if e.At.IsZero() { - e.At = time.Now().UTC() - } - data, err := json.Marshal(e.Data) - if err != nil { - data = fmt.Appendf(nil, `{"marshal_error":%q}`, err.Error()) - } - res, err := execer.ExecContext(ctx, ` - INSERT INTO events (at, kind, task_id, repo, issue, workflow, stage, attempt, actor_id, actor_kind, principal_id, detail, data) - VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, - e.At.UTC().Format(storecontract.EventCursorLayout), e.Kind, e.TaskID, e.Repo, e.Issue, - e.Workflow, e.Stage, e.Attempt, e.ActorID, e.ActorKind, e.PrincipalID, - clip(e.Detail, 4000), string(data)) - if err != nil { - return 0, err - } - return res.LastInsertId() -} - -func scanEvents(rows *sql.Rows) (out []events.Event, retErr error) { - defer func() { - retErr = errors.Join(retErr, rows.Close()) - }() - for rows.Next() { - var e events.Event - var at, data string - if err := rows.Scan(&e.ID, &at, &e.Kind, &e.TaskID, &e.Repo, &e.Issue, - &e.Workflow, &e.Stage, &e.Attempt, &e.ActorID, &e.ActorKind, - &e.PrincipalID, &e.Detail, &data); err != nil { - return nil, err - } - e.At = parseEventAt(at) - _ = json.Unmarshal([]byte(data), &e.Data) - out = append(out, e) - } - return out, rows.Err() -} - -const eventCols = "id, at, kind, task_id, repo, issue, workflow, stage, attempt, actor_id, actor_kind, principal_id, detail, data" - -// EventsSince returns up to limit events after the opaque cursor, oldest -// first -- SSE catch-up and the live feed. The cursor carries the total -// order (at, id): at is the fixed-width sort key and id only breaks ties, so -// a non-monotonic id scheme can neither skip nor repeat an event. An empty or -// malformed cursor means "from the beginning". -func (s *Store) EventsSince(ctx context.Context, cursor string, limit int) ([]events.Event, error) { - at, id, ok := storecontract.ParseEventCursor(cursor) - if !ok { - rows, err := s.db.QueryContext(ctx, - `SELECT `+eventCols+` FROM events ORDER BY at, id LIMIT ?`, limit) - if err != nil { - return nil, err - } - return scanEvents(rows) - } - rows, err := s.db.QueryContext(ctx, - `SELECT `+eventCols+` FROM events WHERE at > ? OR (at = ? AND id > ?) ORDER BY at, id LIMIT ?`, - at, at, id, limit) - if err != nil { - return nil, err - } - return scanEvents(rows) -} - -// parseEventAt reads the stored timestamp, tolerating both the fixed-width -// layout new rows are written in and the RFC3339Nano form older rows carried -// before the migration normalised them. -func parseEventAt(raw string) time.Time { - for _, layout := range []string{storecontract.EventCursorLayout, time.RFC3339Nano, time.RFC3339} { - if t, err := time.Parse(layout, raw); err == nil { - return t - } - } - return time.Time{} -} - -// TaskEvents returns a task's full timeline, oldest first. -func (s *Store) TaskEvents(ctx context.Context, taskID int64) ([]events.Event, error) { - rows, err := s.db.QueryContext(ctx, - `SELECT `+eventCols+` FROM events WHERE task_id = ? ORDER BY id`, taskID) - if err != nil { - return nil, err - } - return scanEvents(rows) -} - -// Tasks returns all tasks, newest first (dashboard listing). -func (s *Store) Tasks(ctx context.Context, limit int) (tasks []workflow.Task, retErr error) { - rows, err := s.db.QueryContext(ctx, ` - SELECT id, owner, repo, issue_number, title, status, workflow, stage, - pr_number, tokens_used, iterations, attempt, park_reason, retry_count, - created_at, updated_at, plan, source, identity, binding_id, binding_version - FROM tasks ORDER BY updated_at DESC LIMIT ?`, limit) - if err != nil { - return nil, err - } - defer func() { - retErr = errors.Join(retErr, rows.Close()) - }() - for rows.Next() { - var t workflow.Task - // Plan and Source are read by the dashboard: Plan gates the - // "Decision required" panel on a waiting_human task, and Source - // decides whether an issue link is rendered at all -- a chat task's - // issue number is synthetic and links nowhere. - if err := rows.Scan(&t.ID, &t.Owner, &t.Repo, &t.IssueNumber, &t.Title, - &t.Status, &t.Workflow, &t.Stage, &t.PRNumber, &t.TokensUsed, - &t.Iterations, &t.Attempt, &t.ParkReason, &t.RetryCount, - sqliteTime{&t.CreatedAt}, sqliteTime{&t.UpdatedAt}, - &t.Plan, &t.Source, &t.Identity, &t.BindingID, &t.BindingVersion); err != nil { - return nil, err - } - tasks = append(tasks, t) - } - return tasks, rows.Err() -} - -// StatusCounts returns task counts by status. -func (s *Store) StatusCounts(ctx context.Context) (counts map[string]int, retErr error) { - rows, err := s.db.QueryContext(ctx, `SELECT status, COUNT(*) FROM tasks GROUP BY status`) - if err != nil { - return nil, err - } - defer func() { - retErr = errors.Join(retErr, rows.Close()) - }() - counts = map[string]int{} - for rows.Next() { - var st string - var n int - if err := rows.Scan(&st, &n); err != nil { - return nil, err - } - counts[st] = n - } - return counts, rows.Err() -} - -// WorkflowStats aggregates outcomes and spend per workflow -- the -// core "is archie getting better per dollar" table. -func (s *Store) WorkflowStats(ctx context.Context) (stats []WorkflowStat, retErr error) { - rows, err := s.db.QueryContext(ctx, ` - SELECT workflow, COUNT(*), - SUM(status='merged'), SUM(status='pr_open'), SUM(status='parked'), - CAST(AVG(tokens_used) AS INTEGER), AVG(iterations), SUM(tokens_used) - FROM tasks WHERE workflow != '' GROUP BY workflow ORDER BY COUNT(*) DESC`) - if err != nil { - return nil, err - } - defer func() { - retErr = errors.Join(retErr, rows.Close()) - }() - for rows.Next() { - var w WorkflowStat - if err := rows.Scan(&w.Workflow, &w.Runs, &w.Merged, &w.PROpen, &w.Parked, - &w.AvgTokens, &w.AvgSteps, &w.TotalToken); err != nil { - return nil, err - } - stats = append(stats, w) - } - return stats, rows.Err() -} - -// StageStats aggregates stage_finish events -- where does time go, and -// which stages fail. -func (s *Store) StageStats(ctx context.Context) (stats []StageStat, retErr error) { - rows, err := s.db.QueryContext(ctx, ` - SELECT workflow, stage, COUNT(*), - CAST(AVG(json_extract(data,'$.duration_ms')) AS INTEGER), - SUM(CASE WHEN json_extract(data,'$.error') IS NOT NULL THEN 1 ELSE 0 END) - FROM events WHERE kind = 'stage_finish' - GROUP BY workflow, stage ORDER BY workflow, stage`) - if err != nil { - return nil, err - } - defer func() { - retErr = errors.Join(retErr, rows.Close()) - }() - for rows.Next() { - var st StageStat - var avg sql.NullInt64 - if err := rows.Scan(&st.Workflow, &st.Stage, &st.Runs, &avg, &st.Errors); err != nil { - return nil, err - } - st.AvgMs = int(avg.Int64) - stats = append(stats, st) - } - return stats, rows.Err() -} - -// TokensByDay sums task token spend per UTC day. Agent-finish events are -// the per-run accounting source; tasks.tokens_used is the durable fallback for -// older or remote runs whose events were not persisted. -func (s *Store) TokensByDay(ctx context.Context, days int) (tokens []DayTokens, retErr error) { - tokens = make([]DayTokens, 0) - rows, err := s.db.QueryContext(ctx, ` - WITH event_totals AS ( - SELECT task_id, substr(at,1,10) AS day, - SUM(CASE WHEN json_type(data,'$.tokens') IN ('integer','real') - THEN CAST(json_extract(data,'$.tokens') AS INTEGER) ELSE 0 END) AS tokens, - SUM(CASE WHEN json_type(data,'$.tokens') IN ('integer','real') THEN 1 ELSE 0 END) AS valid_tokens - FROM events WHERE kind = 'agent_finish' - GROUP BY task_id, day - ), usage AS ( - SELECT day, tokens FROM event_totals WHERE valid_tokens > 0 - UNION ALL - SELECT substr(t.updated_at,1,10), t.tokens_used - FROM tasks t - WHERE t.tokens_used != 0 AND NOT EXISTS ( - SELECT 1 FROM event_totals e - WHERE e.task_id = t.id AND e.valid_tokens > 0 - ) - ) - SELECT day, CAST(SUM(tokens) AS INTEGER) - FROM usage GROUP BY day ORDER BY day DESC LIMIT ?`, days) - if err != nil { - return nil, err - } - defer func() { - retErr = errors.Join(retErr, rows.Close()) - }() - for rows.Next() { - var d DayTokens - if err := rows.Scan(&d.Day, &d.Tokens); err != nil { - return nil, err - } - tokens = append(tokens, d) - } - return tokens, rows.Err() -} diff --git a/internal/store/identities.go b/internal/store/identities.go deleted file mode 100644 index c09d90fbb..000000000 --- a/internal/store/identities.go +++ /dev/null @@ -1,252 +0,0 @@ -package store - -import ( - "context" - "database/sql" - "errors" - "fmt" - "strings" - "time" - - "github.com/samcharles93/archie-core/internal/domain/identity" -) - -const identitiesSchema = ` -CREATE TABLE IF NOT EXISTS identities ( - id TEXT PRIMARY KEY NOT NULL, kind TEXT NOT NULL, display_name TEXT NOT NULL, - lifecycle TEXT NOT NULL, version INTEGER NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL -); -CREATE TABLE IF NOT EXISTS identity_aliases ( - alias TEXT PRIMARY KEY COLLATE NOCASE NOT NULL, identity_id TEXT NOT NULL REFERENCES identities(id) -); -CREATE TABLE IF NOT EXISTS identity_events ( - id INTEGER PRIMARY KEY AUTOINCREMENT, identity_id TEXT NOT NULL, event_type TEXT NOT NULL, - from_lifecycle TEXT NOT NULL, to_lifecycle TEXT NOT NULL, display_name TEXT NOT NULL, - actor_id TEXT NOT NULL, source TEXT NOT NULL, request_id TEXT NOT NULL UNIQUE, at TEXT NOT NULL -); -CREATE TABLE IF NOT EXISTS identity_subjects ( - issuer TEXT NOT NULL, subject TEXT NOT NULL, identity_id TEXT NOT NULL REFERENCES identities(id), - bound_at TEXT NOT NULL, PRIMARY KEY (issuer, subject) -);` - -const identityTimeLayout = time.RFC3339Nano - -func (s *Store) List(ctx context.Context) (_ []identity.Identity, retErr error) { - rows, err := s.db.QueryContext(ctx, `SELECT id, kind, display_name, lifecycle, version, created_at, updated_at FROM identities ORDER BY created_at, id`) - if err != nil { - return nil, err - } - defer func() { retErr = errors.Join(retErr, rows.Close()) }() - var out []identity.Identity - for rows.Next() { - value, err := scanIdentity(rows) - if err != nil { - return nil, err - } - out = append(out, value) - } - return out, rows.Err() -} - -func (s *Store) Get(ctx context.Context, id identity.IdentityID) (identity.Identity, error) { - value, err := scanIdentity(s.db.QueryRowContext(ctx, `SELECT id, kind, display_name, lifecycle, version, created_at, updated_at FROM identities WHERE id=?`, id)) - if errors.Is(err, sql.ErrNoRows) { - return identity.Identity{}, identity.ErrNotFound - } - return value, err -} - -func (s *Store) ResolveLegacyName(ctx context.Context, name string) (identity.Identity, error) { - value, err := scanIdentity(s.db.QueryRowContext(ctx, `SELECT i.id, i.kind, i.display_name, i.lifecycle, i.version, i.created_at, i.updated_at FROM identities i JOIN identity_aliases a ON a.identity_id=i.id WHERE a.alias=?`, strings.TrimSpace(name))) - if errors.Is(err, sql.ErrNoRows) { - return identity.Identity{}, identity.ErrNotFound - } - return value, err -} - -func (s *Store) Create(ctx context.Context, value identity.Identity, audit identity.Audit) (identity.Identity, error) { - if err := value.Validate(); err != nil { - return identity.Identity{}, err - } - now := audit.At.UTC() - if now.IsZero() { - now = time.Now().UTC() - } - value.Version, value.CreatedAt, value.UpdatedAt = 1, now, now - tx, err := s.db.BeginTx(ctx, nil) - if err != nil { - return identity.Identity{}, err - } - defer func() { _ = tx.Rollback() }() - if _, err = tx.ExecContext(ctx, `INSERT INTO identities(id,kind,display_name,lifecycle,version,created_at,updated_at) VALUES(?,?,?,?,?,?,?)`, value.ID, value.Kind, value.DisplayName, value.Lifecycle, value.Version, now.Format(identityTimeLayout), now.Format(identityTimeLayout)); err != nil { - return identity.Identity{}, err - } - if _, err = tx.ExecContext(ctx, `INSERT INTO identity_aliases(alias,identity_id) VALUES(?,?)`, value.DisplayName, value.ID); err != nil { - return identity.Identity{}, err - } - if err = insertIdentityEvent(ctx, tx, value, identity.Event{IdentityID: value.ID, Type: "create", To: value.Lifecycle, DisplayName: value.DisplayName}, audit, now); err != nil { - return identity.Identity{}, err - } - return value, tx.Commit() -} - -func (s *Store) Apply(ctx context.Context, id identity.IdentityID, expectedVersion int64, command identity.Command, audit identity.Audit) (identity.Identity, error) { - tx, err := s.db.BeginTx(ctx, nil) - if err != nil { - return identity.Identity{}, err - } - defer func() { _ = tx.Rollback() }() - current, err := scanIdentity(tx.QueryRowContext(ctx, `SELECT id, kind, display_name, lifecycle, version, created_at, updated_at FROM identities WHERE id=?`, id)) - if errors.Is(err, sql.ErrNoRows) { - return identity.Identity{}, identity.ErrNotFound - } - if err != nil { - return identity.Identity{}, err - } - if current.Version != expectedVersion { - return identity.Identity{}, identity.ErrConflict - } - next, event, err := identity.Apply(current, command) - if err != nil { - return identity.Identity{}, err - } - now := audit.At.UTC() - if now.IsZero() { - now = time.Now().UTC() - } - next.UpdatedAt = now - result, err := tx.ExecContext(ctx, `UPDATE identities SET display_name=?, lifecycle=?, version=?, updated_at=? WHERE id=? AND version=?`, next.DisplayName, next.Lifecycle, next.Version, now.Format(identityTimeLayout), id, expectedVersion) - if err != nil { - return identity.Identity{}, err - } - changed, _ := result.RowsAffected() - if changed != 1 { - return identity.Identity{}, identity.ErrConflict - } - if command.Type == identity.CommandRename { - if _, err = tx.ExecContext(ctx, `INSERT OR IGNORE INTO identity_aliases(alias,identity_id) VALUES(?,?)`, next.DisplayName, id); err != nil { - return identity.Identity{}, err - } - } - if err = insertIdentityEvent(ctx, tx, next, event, audit, now); err != nil { - return identity.Identity{}, err - } - return next, tx.Commit() -} - -// ResolveSubject returns the identity bound to a provider subject, so a -// credential that verified against the provider's keys selects an identity -// archie already knows rather than creating one. -func (s *Store) ResolveSubject(ctx context.Context, subject identity.Subject) (identity.Identity, error) { - value, err := scanIdentity(s.db.QueryRowContext(ctx, `SELECT i.id, i.kind, i.display_name, i.lifecycle, i.version, i.created_at, i.updated_at FROM identities i JOIN identity_subjects b ON b.identity_id=i.id WHERE b.issuer=? AND b.subject=?`, subject.Issuer, subject.Subject)) - if errors.Is(err, sql.ErrNoRows) { - return identity.Identity{}, identity.ErrNotFound - } - return value, err -} - -// BindSubject binds an identity to the provider subject that asserts it. The -// binding is audited like any other identity mutation: who authorised a caller -// to act as this identity is the question the record has to answer later. -// Rebinding an already-bound subject moves it, because a subject that changed -// hands must resolve to whoever it belongs to now. -func (s *Store) BindSubject(ctx context.Context, id identity.IdentityID, subject identity.Subject, audit identity.Audit) error { - if err := subject.Validate(); err != nil { - return err - } - if audit.ActorID == "" || audit.Source == "" || audit.RequestID == "" { - return fmt.Errorf("%w: audit actor, source, and request ID are required", identity.ErrInvalid) - } - now := audit.At.UTC() - if now.IsZero() { - now = time.Now().UTC() - } - tx, err := s.db.BeginTx(ctx, nil) - if err != nil { - return err - } - defer func() { _ = tx.Rollback() }() - current, err := scanIdentity(tx.QueryRowContext(ctx, `SELECT id, kind, display_name, lifecycle, version, created_at, updated_at FROM identities WHERE id=?`, id)) - if errors.Is(err, sql.ErrNoRows) { - return identity.ErrNotFound - } - if err != nil { - return err - } - if _, err = tx.ExecContext(ctx, `INSERT INTO identity_subjects(issuer,subject,identity_id,bound_at) VALUES(?,?,?,?) ON CONFLICT(issuer,subject) DO UPDATE SET identity_id=excluded.identity_id, bound_at=excluded.bound_at`, subject.Issuer, subject.Subject, id, now.Format(identityTimeLayout)); err != nil { - return err - } - if err = insertIdentityEvent(ctx, tx, current, identity.Event{IdentityID: id, Type: "bind_subject", From: current.Lifecycle, To: current.Lifecycle, DisplayName: subject.Subject}, audit, now); err != nil { - return err - } - return tx.Commit() -} - -func (s *Store) BootstrapIdentities(ctx context.Context, legacyNames []string) error { - values := append([]struct { - id identity.IdentityID - kind identity.Kind - name string - }{{identity.SystemID, identity.KindSystem, "System"}}, make([]struct { - id identity.IdentityID - kind identity.Kind - name string - }, len(legacyNames))...) - for i, name := range legacyNames { - name = strings.TrimSpace(name) - values[i+1] = struct { - id identity.IdentityID - kind identity.Kind - name string - }{identity.StableID(name), identity.KindBot, name} - } - for _, seed := range values { - if seed.name == "" { - continue - } - value, err := identity.New(seed.id, seed.kind, seed.name) - if err != nil { - return err - } - _, err = s.Create(ctx, value, identity.Audit{ActorID: identity.SystemID, Source: "legacy-config", RequestID: "identity-import:" + string(seed.id)}) - if err != nil && !isSQLiteUnique(err) { - return fmt.Errorf("bootstrap identity %q: %w", seed.name, err) - } - if _, aliasErr := s.db.ExecContext(ctx, `INSERT OR IGNORE INTO identity_aliases(alias,identity_id) VALUES(?,?)`, seed.name, seed.id); aliasErr != nil { - return aliasErr - } - if seed.kind != identity.KindSystem { - if _, migrateErr := s.db.ExecContext(ctx, `UPDATE tasks SET identity=? WHERE identity=?`, seed.id, seed.name); migrateErr != nil { - return migrateErr - } - } - } - return nil -} - -type identityScanner interface{ Scan(...any) error } - -func scanIdentity(row identityScanner) (identity.Identity, error) { - var v identity.Identity - var created, updated string - err := row.Scan(&v.ID, &v.Kind, &v.DisplayName, &v.Lifecycle, &v.Version, &created, &updated) - if err != nil { - return v, err - } - v.CreatedAt, err = time.Parse(identityTimeLayout, created) - if err != nil { - return v, err - } - v.UpdatedAt, err = time.Parse(identityTimeLayout, updated) - return v, err -} - -func insertIdentityEvent(ctx context.Context, tx *sql.Tx, value identity.Identity, event identity.Event, audit identity.Audit, at time.Time) error { - if audit.ActorID == "" || audit.Source == "" || audit.RequestID == "" { - return fmt.Errorf("%w: audit actor, source, and request ID are required", identity.ErrInvalid) - } - _, err := tx.ExecContext(ctx, `INSERT INTO identity_events(identity_id,event_type,from_lifecycle,to_lifecycle,display_name,actor_id,source,request_id,at) VALUES(?,?,?,?,?,?,?,?,?)`, value.ID, event.Type, event.From, event.To, event.DisplayName, audit.ActorID, audit.Source, audit.RequestID, at.Format(identityTimeLayout)) - return err -} - -func isSQLiteUnique(err error) bool { return strings.Contains(err.Error(), "UNIQUE constraint failed") } diff --git a/internal/store/identities_test.go b/internal/store/identities_test.go deleted file mode 100644 index 34a185b1e..000000000 --- a/internal/store/identities_test.go +++ /dev/null @@ -1,84 +0,0 @@ -package store - -import ( - "errors" - "testing" - - "github.com/samcharles93/archie-core/internal/domain/identity" -) - -func TestIdentityMutationPersistsAuditAndHistoricalName(t *testing.T) { - s := OpenTest(t) - defer s.Close() - created, err := identity.New(identity.StableID("reviewer"), identity.KindBot, "Reviewer") - if err != nil { - t.Fatal(err) - } - created, err = s.Create(t.Context(), created, identity.Audit{ActorID: identity.SystemID, Source: "test", RequestID: "create"}) - if err != nil { - t.Fatal(err) - } - renamed, err := s.Apply(t.Context(), created.ID, created.Version, identity.Command{Type: identity.CommandRename, DisplayName: "Review Bot"}, identity.Audit{ActorID: identity.SystemID, Source: "test", RequestID: "rename"}) - if err != nil { - t.Fatal(err) - } - resolved, err := s.ResolveLegacyName(t.Context(), "reviewer") - if err != nil { - t.Fatal(err) - } - if resolved.ID != renamed.ID || resolved.DisplayName != "Review Bot" { - t.Fatalf("resolved = %+v, want renamed identity", resolved) - } - var count int - if err := s.DB().QueryRowContext(t.Context(), `SELECT COUNT(*) FROM identity_events WHERE identity_id = ?`, renamed.ID).Scan(&count); err != nil { - t.Fatal(err) - } - if count != 2 { - t.Fatalf("audit count = %d, want 2", count) - } - if _, err := s.Apply(t.Context(), renamed.ID, created.Version, identity.Command{Type: identity.CommandSuspend}, identity.Audit{ActorID: identity.SystemID, Source: "test", RequestID: "stale"}); !errors.Is(err, identity.ErrConflict) { - t.Fatalf("stale apply error = %v, want conflict", err) - } -} - -func TestBootstrapIdentitiesIsStableAndNonDestructive(t *testing.T) { - s := OpenTest(t) - defer s.Close() - if inserted, err := s.EnqueueIssue(t.Context(), "acme", "widget", 7, "Legacy", "", "", "reviewer"); err != nil || !inserted { - t.Fatalf("seed legacy task = %v, %v", inserted, err) - } - if err := s.BootstrapIdentities(t.Context(), []string{"archie", "reviewer"}); err != nil { - t.Fatal(err) - } - reviewer, err := s.ResolveLegacyName(t.Context(), "reviewer") - if err != nil { - t.Fatal(err) - } - if _, err := s.Apply(t.Context(), reviewer.ID, reviewer.Version, identity.Command{Type: identity.CommandRename, DisplayName: "Custom"}, identity.Audit{ActorID: identity.SystemID, Source: "test", RequestID: "rename"}); err != nil { - t.Fatal(err) - } - if err := s.BootstrapIdentities(t.Context(), []string{"archie", "reviewer"}); err != nil { - t.Fatal(err) - } - got, err := s.Get(t.Context(), reviewer.ID) - if err != nil { - t.Fatal(err) - } - if got.DisplayName != "Custom" { - t.Fatalf("bootstrap overwrote name with %q", got.DisplayName) - } - all, err := s.List(t.Context()) - if err != nil { - t.Fatal(err) - } - if len(all) != 3 { - t.Fatalf("identity count = %d, want system plus two configured", len(all)) - } - task, err := s.TaskByIssue(t.Context(), "acme", "widget", 7) - if err != nil { - t.Fatal(err) - } - if task.Identity != string(reviewer.ID) { - t.Fatalf("legacy task identity = %q, want %q", task.Identity, reviewer.ID) - } -} diff --git a/internal/store/identity_subject_test.go b/internal/store/identity_subject_test.go deleted file mode 100644 index bf25a8542..000000000 --- a/internal/store/identity_subject_test.go +++ /dev/null @@ -1,157 +0,0 @@ -package store - -import ( - "context" - "errors" - "testing" - "time" - - "github.com/samcharles93/archie-core/internal/domain/identity" - "github.com/samcharles93/archie-core/internal/events" -) - -func bindAudit(requestID string) identity.Audit { - return identity.Audit{ActorID: identity.SystemID, Source: "test", RequestID: requestID, At: time.Now().UTC()} -} - -func newTestIdentity(t *testing.T, s *Store, id identity.IdentityID, kind identity.Kind, name string) identity.Identity { - t.Helper() - value, err := identity.New(id, kind, name) - if err != nil { - t.Fatalf("identity.New() error = %v", err) - } - created, err := s.Create(context.Background(), value, bindAudit("create:"+string(id))) - if err != nil { - t.Fatalf("Create() error = %v", err) - } - return created -} - -// TestResolveSubjectReturnsTheBoundIdentity: a verified provider subject selects -// the identity it is bound to, which is what lets a credential resolve to a -// record archie already knows rather than creating one. -func TestResolveSubjectReturnsTheBoundIdentity(t *testing.T) { - s := openTest(t) - ctx := context.Background() - agent := newTestIdentity(t, s, identity.IdentityID("30000000-0000-5000-8000-000000000001"), identity.KindBot, "archie-agent") - subject := identity.Subject{Issuer: "https://auth.catlow.cloud", Subject: "archie"} - - if err := s.BindSubject(ctx, agent.ID, subject, bindAudit("bind:1")); err != nil { - t.Fatalf("BindSubject() error = %v", err) - } - - got, err := s.ResolveSubject(ctx, subject) - if err != nil { - t.Fatalf("ResolveSubject() error = %v", err) - } - if got.ID != agent.ID || got.Kind != identity.KindBot { - t.Fatalf("ResolveSubject() = %+v, want %+v", got, agent) - } -} - -// TestResolveSubjectIsKeyedOnIssuerAndSubject: the same subject string from a -// different issuer is a different caller, so it must not resolve. -func TestResolveSubjectIsKeyedOnIssuerAndSubject(t *testing.T) { - s := openTest(t) - ctx := context.Background() - agent := newTestIdentity(t, s, identity.IdentityID("30000000-0000-5000-8000-000000000002"), identity.KindBot, "archie-agent") - bound := identity.Subject{Issuer: "https://auth.catlow.cloud", Subject: "archie"} - if err := s.BindSubject(ctx, agent.ID, bound, bindAudit("bind:2")); err != nil { - t.Fatalf("BindSubject() error = %v", err) - } - - others := []struct { - name string - subject identity.Subject - }{ - {"another issuer, same subject", identity.Subject{Issuer: "https://elsewhere.example", Subject: "archie"}}, - {"same issuer, another subject", identity.Subject{Issuer: "https://auth.catlow.cloud", Subject: "someone-else"}}, - } - for _, tc := range others { - t.Run(tc.name, func(t *testing.T) { - if _, err := s.ResolveSubject(ctx, tc.subject); !errors.Is(err, identity.ErrNotFound) { - t.Fatalf("ResolveSubject() error = %v, want %v", err, identity.ErrNotFound) - } - }) - } -} - -// TestBindSubjectMovesAnAlreadyBoundSubject: when a subject changes hands it -// resolves to whoever holds it now, so a reassignment cannot leave two identities -// claiming one provider subject. -func TestBindSubjectMovesAnAlreadyBoundSubject(t *testing.T) { - s := openTest(t) - ctx := context.Background() - first := newTestIdentity(t, s, identity.IdentityID("30000000-0000-5000-8000-000000000003"), identity.KindBot, "first-agent") - second := newTestIdentity(t, s, identity.IdentityID("30000000-0000-5000-8000-000000000004"), identity.KindBot, "second-agent") - subject := identity.Subject{Issuer: "https://auth.catlow.cloud", Subject: "archie"} - - if err := s.BindSubject(ctx, first.ID, subject, bindAudit("bind:3")); err != nil { - t.Fatalf("BindSubject() error = %v", err) - } - if err := s.BindSubject(ctx, second.ID, subject, bindAudit("bind:4")); err != nil { - t.Fatalf("rebind error = %v", err) - } - - got, err := s.ResolveSubject(ctx, subject) - if err != nil { - t.Fatalf("ResolveSubject() error = %v", err) - } - if got.ID != second.ID { - t.Fatalf("ResolveSubject() = %s, want %s", got.ID, second.ID) - } -} - -func TestBindSubjectRequiresAuditAndAKnownIdentity(t *testing.T) { - s := openTest(t) - ctx := context.Background() - subject := identity.Subject{Issuer: "https://auth.catlow.cloud", Subject: "archie"} - - if err := s.BindSubject(ctx, identity.SystemID, subject, identity.Audit{}); err == nil { - t.Fatal("BindSubject() accepted a binding with no audit") - } - if err := s.BindSubject(ctx, identity.IdentityID("does-not-exist"), subject, bindAudit("bind:5")); !errors.Is(err, identity.ErrNotFound) { - t.Fatalf("BindSubject() error = %v, want %v", err, identity.ErrNotFound) - } - if err := s.BindSubject(ctx, identity.SystemID, identity.Subject{}, bindAudit("bind:6")); err == nil { - t.Fatal("BindSubject() accepted an incomplete subject") - } -} - -// TestEventAttributionSurvivesTheRoundTrip: the attributions are only useful if -// they come back out of the store, so a reader can answer who acted and whose -// authority they used. -func TestEventAttributionSurvivesTheRoundTrip(t *testing.T) { - s := openTest(t) - ctx := context.Background() - - inserted, err := s.InsertEvent(ctx, events.Event{ - Kind: events.KindAgentApproved, - TaskID: 11, - ActorID: "30000000-0000-5000-8000-000000000001", - ActorKind: string(identity.KindBot), - PrincipalID: "30000000-0000-5000-8000-000000000009", - Detail: "approved by an agent", - }) - if err != nil { - t.Fatalf("InsertEvent() error = %v", err) - } - - got, err := s.TaskEvents(ctx, 11) - if err != nil { - t.Fatalf("TaskEvents() error = %v", err) - } - if len(got) != 1 { - t.Fatalf("TaskEvents() returned %d events, want 1", len(got)) - } - e := got[0] - if e.ID != inserted { - t.Fatalf("event id = %d, want %d", e.ID, inserted) - } - if e.Kind != events.KindAgentApproved { - t.Fatalf("kind = %q, want %q", e.Kind, events.KindAgentApproved) - } - if e.ActorID == "" || e.ActorKind != string(identity.KindBot) || e.PrincipalID == "" { - t.Fatalf("attribution did not survive the round trip: %+v", e) - } -} diff --git a/internal/store/interface.go b/internal/store/interface.go deleted file mode 100644 index 3f0c618f0..000000000 --- a/internal/store/interface.go +++ /dev/null @@ -1,63 +0,0 @@ -// Package store defines the task and event persistence for archied's data. -// TaskStore is the full surface the daemon needs and *Store is its SQLite -// implementation. -// -// REVISED (archie-core-8cda.5.6): the producer-owned contract surfaces this -// package used to define live in internal/contracts/store/v1 (package -// storev1) -- the approved contract location -- so the archie-ui process can -// reference the contract without linking this SQLite implementation. The -// definitions below are type aliases for compatibility with the daemon-side -// callers; new UI-process-facing code imports storev1 directly. -package store - -import ( - "github.com/samcharles93/archie-core/internal/domain/storecontract" - "github.com/samcharles93/archie-core/internal/domain/workflow" -) - -// Aliases: the daemon/webui/intake store surfaces moved to storecontract. The -// message strings of the sentinel errors are the wire contract (see -// storev1's var block); the aliases change nothing observable. -type ( - TaskStore = storecontract.TaskStore - TaskLifecycle = storecontract.TaskLifecycle - TaskArchiver = storecontract.TaskArchiver - TaskRetryer = storecontract.TaskRetryer - TaskQueries = storecontract.TaskQueries - TaskEvents = storecontract.TaskEvents - TaskLogStore = storecontract.TaskLogStore - CaptureStore = storecontract.CaptureStore - ConfigSnapshotStore = storecontract.ConfigSnapshotStore - ChannelStatusStore = storecontract.ChannelStatusStore - ApplyStatusStore = storecontract.ApplyStatusStore - MappingStore = storecontract.MappingStore - BindingStore = storecontract.BindingStore - BindingDispatcher = storecontract.BindingDispatcher - BindingTaskCreator = storecontract.BindingTaskCreator - PlaybookDispatcher = storecontract.PlaybookDispatcher - CapturedEvent = storecontract.CapturedEvent - ConfigSnapshot = storecontract.ConfigSnapshot - ChannelStatus = storecontract.ChannelStatus - ApplyStatus = storecontract.ApplyStatus - WorkflowStat = storecontract.WorkflowStat - StageStat = storecontract.StageStat - DayTokens = storecontract.DayTokens -) - -var ( - ErrStaleTransition = storecontract.ErrStaleTransition - ErrBindingNotFound = storecontract.ErrBindingNotFound - ErrBindingOverlap = storecontract.ErrBindingOverlap - ErrBindingTransition = storecontract.ErrBindingTransition - ErrAlreadyDispatched = storecontract.ErrAlreadyDispatched - ErrMappingNotFound = storecontract.ErrMappingNotFound -) - -// Compile-time check: *Store satisfies TaskStore. -var _ TaskStore = (*Store)(nil) - -// Compile-time check: *Store satisfies ChannelStatusStore. -var _ ChannelStatusStore = (*Store)(nil) - -// Compile-time check: *Store satisfies workflow.Store. -var _ workflow.Store = (*Store)(nil) diff --git a/internal/store/maintenance.go b/internal/store/maintenance.go deleted file mode 100644 index d1165a600..000000000 --- a/internal/store/maintenance.go +++ /dev/null @@ -1,265 +0,0 @@ -package store - -import ( - "context" - "database/sql" - "errors" - "fmt" - "io" - "os" - "path/filepath" - "strings" -) - -// This file is the offline half of the store's contract with its owner: the -// operations the State Store process cannot perform on itself, because they -// read or replace the very file it has open. They are what -// docs/prds/runtime-control-plane.md ("Bootstrap, migration, and recovery") -// asks for -- back up, restore and validate the database without archied or -// the Web UI -- and every one of them works on the file directly. -// -// The read-only operations never take the ownership lock, because they are -// what an operator runs against a serving store. The one that replaces the -// file does, because a rewrite under a running server is the only way an -// offline command can destroy a task store. - -// OpenReadOnly opens an existing store for reading only: no schema is created -// and no migration runs. That matters for recovery -- the snapshot an update -// takes has to stay exactly what the release that wrote it expects, and -// migrating a copy during verification would hand a rollback a schema its -// binary refuses. -func OpenReadOnly(ctx context.Context, path string) (*Store, error) { - if err := RequireDatabase(path); err != nil { - return nil, err - } - db, err := sql.Open("sqlite", readonlyDSN(path)) - if err != nil { - return nil, err - } - db.SetMaxOpenConns(1) - // sql.Open is lazy: the first statement is where a file that is not a - // database, a missing WAL sidecar or an unreadable path surfaces. - var tables int - if err := db.QueryRowContext(ctx, `SELECT count(*) FROM sqlite_master`).Scan(&tables); err != nil { - return nil, errors.Join(fmt.Errorf("read task database %s: %w", path, err), db.Close()) - } - return &Store{db: db}, nil -} - -// readonlyDSN reads the store without the write-ahead log pragma the serving -// process sets: a reader has no business changing the database's journal mode, -// and the read-only flag makes an accidental write an error rather than a -// silent modification of a file someone else owns. -func readonlyDSN(path string) string { - separator := "?" - if strings.HasSuffix(path, "?") || strings.HasSuffix(path, "&") { - separator = "" - } else if strings.Contains(path, "?") { - separator = "&" - } - return path + separator + "mode=ro&_pragma=busy_timeout(5000)" -} - -// StoresResources reports whether the store's file carries the control-plane -// resources table. A store written before the control plane existed has none -// and holds no stored settings to validate; the serving process creates the -// table on its next start, so an offline check must tell that apart from -// resources it cannot read. -func (s *Store) StoresResources(ctx context.Context) (bool, error) { - var tables int - if err := s.db.QueryRowContext(ctx, `SELECT count(*) FROM sqlite_master WHERE type='table' AND name='resources'`).Scan(&tables); err != nil { - return false, fmt.Errorf("inspect store schema: %w", err) - } - return tables > 0, nil -} - -// RequireDatabase reports whether path is an existing store file. A writer -// that must not create the file it fails to find asks this first: a recovery -// command pointed at a mistyped path has to refuse, not leave a fresh empty -// database where an operator expected theirs. -func RequireDatabase(path string) error { - if _, err := os.Stat(path); err != nil { - return fmt.Errorf("task database %s: %w", path, err) - } - return nil -} - -// ValidateFile checks an existing store the way the serving process meets it -// on startup and reports the schema version it carries: the file is a SQLite -// database this binary can read, it is not corrupt, and its schema is not -// newer than this binary supports. -func ValidateFile(ctx context.Context, path string) (int, error) { - st, err := OpenReadOnly(ctx, path) - if err != nil { - return 0, err - } - defer func() { _ = st.Close() }() - return st.check(ctx) -} - -// check runs the file-level checks. integrity_check returns one row per -// problem, or the single row "ok"; reading the first row is therefore the -// verdict rather than a sample. -func (s *Store) check(ctx context.Context) (int, error) { - var result string - if err := s.db.QueryRowContext(ctx, `PRAGMA integrity_check`).Scan(&result); err != nil { - return 0, fmt.Errorf("integrity check: %w", err) - } - if result != "ok" { - return 0, fmt.Errorf("integrity check: %s", result) - } - var version int - if err := s.db.QueryRowContext(ctx, `PRAGMA user_version`).Scan(&version); err != nil { - return 0, fmt.Errorf("read schema version: %w", err) - } - if version > taskSchemaVersion { - return 0, fmt.Errorf("database schema version %d is newer than supported version %d", version, taskSchemaVersion) - } - return version, nil -} - -// Backup writes a transactionally consistent snapshot of database to snapshot, -// using SQLite's own copy, so a store that is being written to cannot produce -// a torn file. -// -// It deliberately does not take the ownership lock. The update installer runs -// inside the process it is updating and cannot stop the State Store, so the -// snapshot that makes a failed update reversible is taken against a serving -// store; a backup that insisted on an exclusively owned file would break the -// one caller that exists. The snapshot is written beside the destination and -// renamed into place, so an interrupted backup never replaces a snapshot that -// was good with one that is not. -func Backup(ctx context.Context, database, snapshot string) error { - if err := RequireDatabase(database); err != nil { - return err - } - // The exemption from the ownership lock below is only sound while backup - // never replaces the database. With -out naming the database it would - // rename the snapshot over a file a serving State Store may still have - // open, orphaning the WAL of the file it just unlinked -- so it is refused - // exactly as Restore refuses it. - if same, err := sameFile(database, snapshot); err != nil { - return err - } else if same { - return fmt.Errorf("snapshot %s is the database itself", snapshot) - } - if err := os.MkdirAll(filepath.Dir(snapshot), 0o755); err != nil { - return fmt.Errorf("create snapshot directory: %w", err) - } - db, err := sql.Open("sqlite", sqliteDSN(database)) - if err != nil { - return fmt.Errorf("open task database %s: %w", database, err) - } - defer func() { _ = db.Close() }() - - staging := snapshot + ".tmp" - if err := os.Remove(staging); err != nil && !os.IsNotExist(err) { - return fmt.Errorf("clear staging snapshot %s: %w", staging, err) - } - if _, err := db.ExecContext(ctx, `VACUUM INTO ?`, staging); err != nil { - return errors.Join(fmt.Errorf("snapshot %s: %w", database, err), os.Remove(staging)) - } - // A snapshot that is not itself a usable store is worse than no snapshot: - // the update path treats its existence as proof that a rollback is - // possible. - if _, err := ValidateFile(ctx, staging); err != nil { - return errors.Join(fmt.Errorf("snapshot is not a usable store: %w", err), os.Remove(staging)) - } - if err := os.Rename(staging, snapshot); err != nil { - return errors.Join(fmt.Errorf("publish snapshot %s: %w", snapshot, err), os.Remove(staging)) - } - return nil -} - -// Restore replaces database with the snapshot at snapshot. The snapshot is -// verified before anything is destroyed, so a file that is not a usable store -// cannot take the database down with it, and the database file itself is -// replaced by a rename, so a failure leaves either the old file or the new one -// rather than a mixture. The replaced file's -wal/-shm are removed first, which -// the comment at that step explains: between the two calls the database is -// merely incomplete, and re-running the command completes it. -// -// It holds the ownership lock for its duration: rewriting a database a running -// State Store still has open would leave that process writing to an unlinked -// inode while the store served a file nobody owns. -func Restore(ctx context.Context, database, snapshot string) error { - if _, err := os.Stat(filepath.Dir(database)); err != nil { - return fmt.Errorf("restore destination %s: %w", database, err) - } - if same, err := sameFile(database, snapshot); err != nil { - return err - } else if same { - return fmt.Errorf("restore snapshot %s is the database itself", snapshot) - } - ownership, err := AcquireOwnership(database) - if err != nil { - return err - } - defer func() { _ = ownership.Release() }() - - if _, err := ValidateFile(ctx, snapshot); err != nil { - return fmt.Errorf("snapshot is not a usable store: %w", err) - } - staging := database + ".restore.tmp" - if err := copyFile(snapshot, staging); err != nil { - return errors.Join(err, os.Remove(staging)) - } // The replaced database's write-ahead log belongs to the file that is - // going away. It goes first: between the two calls the database is merely - // incomplete, whereas a WAL left beside the file it does not describe is - // the state SQLite cannot recover from. - for _, sidecar := range []string{"-wal", "-shm"} { - if err := os.Remove(database + sidecar); err != nil && !os.IsNotExist(err) { - return errors.Join(fmt.Errorf("remove %s%s: %w", database, sidecar, err), os.Remove(staging)) - } - } - if err := os.Rename(staging, database); err != nil { - return errors.Join(fmt.Errorf("publish restored database %s: %w", database, err), os.Remove(staging)) - } - return nil -} - -func sameFile(a, b string) (bool, error) { - first, err := os.Stat(a) - if err != nil { - if os.IsNotExist(err) { - return false, nil - } - return false, err - } - second, err := os.Stat(b) - if err != nil { - if os.IsNotExist(err) { - return false, nil - } - return false, err - } - return os.SameFile(first, second), nil -} - -// copyFile writes source over a new file at path, flushed to disk before it is -// returned: the rename that publishes it must not reach the directory entries -// ahead of the bytes they point at. The snapshot's own permissions are kept, so -// a restore does not silently change who may read the operator's database. -func copyFile(source, path string) (retErr error) { - info, err := os.Stat(source) - if err != nil { - return fmt.Errorf("stat snapshot %s: %w", source, err) - } - in, err := os.Open(source) - if err != nil { - return fmt.Errorf("open snapshot %s: %w", source, err) - } - defer func() { retErr = errors.Join(retErr, in.Close()) }() - out, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, info.Mode().Perm()) - if err != nil { - return fmt.Errorf("create %s: %w", path, err) - } - defer func() { retErr = errors.Join(retErr, out.Close()) }() - if _, err := io.Copy(out, in); err != nil { - return fmt.Errorf("write %s: %w", path, err) - } - if err := out.Sync(); err != nil { - return fmt.Errorf("sync %s: %w", path, err) - } - return nil -} diff --git a/internal/store/maintenance_test.go b/internal/store/maintenance_test.go deleted file mode 100644 index 95eda0c86..000000000 --- a/internal/store/maintenance_test.go +++ /dev/null @@ -1,92 +0,0 @@ -package store - -import ( - "context" - "database/sql" - "errors" - "fmt" - "os" - "path/filepath" - "testing" -) - -// Ownership is what makes "the State Store is stopped" a fact an offline -// command can check, so the primitive itself is asserted here rather than only -// through the commands that use it: exclusivity, release, and per-database -// independence. -func TestOwnershipIsExclusivePerDatabase(t *testing.T) { - dir := t.TempDir() - first := filepath.Join(dir, "archie.db-tasks.sqlite") - second := filepath.Join(dir, "other.db-tasks.sqlite") - - held, err := AcquireOwnership(first) - if err != nil { - t.Fatalf("first AcquireOwnership: %v", err) - } - if _, err := AcquireOwnership(first); !errors.Is(err, ErrStoreOwned) { - t.Fatalf("second AcquireOwnership on the same database = %v, want ErrStoreOwned", err) - } - // A different database is a different claim: one process owning its store - // must not stop another from owning its own. - elsewhere, err := AcquireOwnership(second) - if err != nil { - t.Fatalf("AcquireOwnership on an unrelated database: %v", err) - } - if _, err := os.Stat(first + ".lock"); err != nil { - t.Fatalf("ownership left no sidecar to lock: %v", err) - } - - if err := held.Release(); err != nil { - t.Fatalf("Release: %v", err) - } - reacquired, err := AcquireOwnership(first) - if err != nil { - t.Fatalf("AcquireOwnership after Release: %v", err) - } - if err := errors.Join(reacquired.Release(), elsewhere.Release()); err != nil { - t.Fatalf("release on cleanup: %v", err) - } -} - -// The snapshot an update takes is the state a rollback restores, and it is -// restored by the release that wrote it. Verifying the copy must therefore not -// migrate it: a snapshot silently upgraded to this binary's schema would be -// refused by the older binary it exists to serve. -func TestBackupSnapshotKeepsTheSchemaVersionItCopied(t *testing.T) { - dir := t.TempDir() - database := filepath.Join(dir, "archie.db-tasks.sqlite") - snapshot := filepath.Join(dir, "snapshot.sqlite") - st, err := Open(t.Context(), database) - if err != nil { - t.Fatal(err) - } - if err := st.Close(); err != nil { - t.Fatal(err) - } - // An older release's file: the schema version it wrote, which this binary - // is expected to migrate when the store is next opened for serving. - if err := setUserVersion(t.Context(), database, taskSchemaVersion-1); err != nil { - t.Fatal(err) - } - - if err := Backup(t.Context(), database, snapshot); err != nil { - t.Fatalf("Backup: %v", err) - } - version, err := ValidateFile(t.Context(), snapshot) - if err != nil { - t.Fatalf("ValidateFile on the snapshot: %v", err) - } - if version != taskSchemaVersion-1 { - t.Fatalf("snapshot schema version = %d, want the %d it copied", version, taskSchemaVersion-1) - } -} - -func setUserVersion(ctx context.Context, path string, version int) error { - db, err := sql.Open("sqlite", path) - if err != nil { - return err - } - defer func() { _ = db.Close() }() - _, err = db.ExecContext(ctx, fmt.Sprintf(`PRAGMA user_version = %d`, version)) - return err -} diff --git a/internal/store/ownership.go b/internal/store/ownership.go deleted file mode 100644 index b0743d89f..000000000 --- a/internal/store/ownership.go +++ /dev/null @@ -1,68 +0,0 @@ -package store - -import ( - "errors" - "fmt" - "os" - "path/filepath" -) - -// ErrStoreOwned is returned when a task database is already owned by another -// process. Ownership is what makes "the State Store is stopped" a fact an -// offline command can check rather than a rule the operator is trusted to -// follow: overwriting a database a running server still holds leaves it -// writing to an unlinked inode while the store serves a file nobody owns. -var ErrStoreOwned = errors.New("task database is owned by another process") - -// Ownership is one process's exclusive claim over one task database, held for -// as long as that process owns the file. The serving State Store takes it for -// its whole life; the offline recovery commands take it for the duration of an -// operation that rewrites the file. -// -// The claim lives in a sidecar file beside the database rather than on the -// database inode itself, so it survives the rename a restore performs: after -// the swap the sidecar is still the one path every process locks. -type Ownership struct { - f *os.File -} - -// AcquireOwnership takes the store's ownership lock without blocking. A -// database another process owns comes back as ErrStoreOwned, never as a wait: -// a process that must not proceed has to hear so, and a blocking lock would -// turn a mistyped command into a hung terminal. -func AcquireOwnership(path string) (*Ownership, error) { - lockPath := ownershipLockPath(path) - if err := os.MkdirAll(filepath.Dir(lockPath), 0o755); err != nil { - return nil, fmt.Errorf("create store directory for %s: %w", lockPath, err) - } - f, err := os.OpenFile(lockPath, os.O_RDWR|os.O_CREATE, 0o644) - if err != nil { - return nil, fmt.Errorf("open store lock %s: %w", lockPath, err) - } - taken, err := lockFile(f) - if err != nil { - return nil, errors.Join(fmt.Errorf("lock %s: %w", lockPath, err), f.Close()) - } - if !taken { - return nil, errors.Join(fmt.Errorf("%s: %w", path, ErrStoreOwned), f.Close()) - } - return &Ownership{f: f}, nil -} - -// Release drops the claim and closes the sidecar. Closing the descriptor alone -// would release it too; the explicit unlock keeps the intent readable and -// makes Release idempotent. -func (o *Ownership) Release() error { - if o == nil || o.f == nil { - return nil - } - err := unlockFile(o.f) - f := o.f - o.f = nil - return errors.Join(err, f.Close()) -} - -// ownershipLockPath is the sidecar every owner of path locks. It is derived -// from the database path, so the State Store process and an offline command -// that were given the same database agree on it without configuration. -func ownershipLockPath(path string) string { return path + ".lock" } diff --git a/internal/store/ownership_unix.go b/internal/store/ownership_unix.go deleted file mode 100644 index 3d0d2bb4b..000000000 --- a/internal/store/ownership_unix.go +++ /dev/null @@ -1,30 +0,0 @@ -//go:build unix - -package store - -import ( - "errors" - "os" - "syscall" -) - -// lockFile takes a non-blocking exclusive flock on f. The boolean reports -// whether it was taken: a lock another process holds (EWOULDBLOCK) is a normal -// answer to "is the State Store running?", not an error. -func lockFile(f *os.File) (bool, error) { - err := syscall.Flock(int(f.Fd()), syscall.LOCK_EX|syscall.LOCK_NB) - if errors.Is(err, syscall.EWOULDBLOCK) { - return false, nil - } - if err != nil { - return false, err - } - return true, nil -} - -func unlockFile(f *os.File) error { - if err := syscall.Flock(int(f.Fd()), syscall.LOCK_UN); err != nil { - return err - } - return nil -} diff --git a/internal/store/ownership_windows.go b/internal/store/ownership_windows.go deleted file mode 100644 index e282ae29d..000000000 --- a/internal/store/ownership_windows.go +++ /dev/null @@ -1,23 +0,0 @@ -//go:build windows - -// flock is a POSIX primitive and Windows is not a supported deployment surface -// (CLAUDE.md's deployment model is Linux and macOS), so this file fails closed: -// every lock attempt reports an error rather than silently degrading to "no -// lock". An offline command that cannot prove it owns the database must refuse -// to rewrite it, which is the only safe reading of an unavailable primitive. -// -// If a Windows deployment ever becomes supported, swap this for a real -// LockFileEx/UnlockFileEx pair; nothing else in the package needs to change. - -package store - -import ( - "errors" - "os" -) - -func lockFile(*os.File) (bool, error) { - return false, errors.New("store ownership locking requires a POSIX flock, which this platform does not provide") -} - -func unlockFile(*os.File) error { return nil } diff --git a/internal/store/queries_test.go b/internal/store/queries_test.go deleted file mode 100644 index 5bf959053..000000000 --- a/internal/store/queries_test.go +++ /dev/null @@ -1,395 +0,0 @@ -package store - -import ( - "context" - "reflect" - "testing" - "time" - - "github.com/samcharles93/archie-core/internal/domain/workflow" - "github.com/samcharles93/archie-core/internal/events" -) - -func TestTaskByIssue(t *testing.T) { - s := openTest(t) - ctx := context.Background() - - if got, err := s.TaskByIssue(ctx, "acme", "widget", 1); err != nil || got != nil { - t.Fatalf("TaskByIssue on empty store = (%+v, %v)", got, err) - } - - if _, err := s.EnqueueIssue(ctx, "acme", "widget", 1, "title", "body", "bug", ""); err != nil { - t.Fatal(err) - } - got, err := s.TaskByIssue(ctx, "acme", "widget", 1) - if err != nil || got == nil { - t.Fatalf("TaskByIssue = (%+v, %v)", got, err) - } - if got.Title != "title" || got.IssueNumber != 1 { - t.Fatalf("TaskByIssue = %+v", got) - } - - if got, err := s.TaskByIssue(ctx, "acme", "widget", 2); err != nil || got != nil { - t.Fatalf("TaskByIssue for missing issue = (%+v, %v)", got, err) - } -} - -func TestOpenTaskByPR(t *testing.T) { - s := openTest(t) - ctx := t.Context() - - for i, status := range []string{workflow.StatusPROpen, workflow.StatusMerged, workflow.StatusRejected} { - issueNumber := i + 1 - prNumber := 101 + i - if _, err := s.EnqueueIssue(ctx, "acme", "widget", issueNumber, "title", "body", "", ""); err != nil { - t.Fatal(err) - } - task, err := s.TaskByIssue(ctx, "acme", "widget", issueNumber) - if err != nil || task == nil { - t.Fatalf("TaskByIssue(%d) = (%+v, %v)", issueNumber, task, err) - } - task.PRNumber = prNumber - if err := s.Update(ctx, task); err != nil { - t.Fatal(err) - } - if err := s.Transition(ctx, task.ID, workflow.StatusQueued, status, ""); err != nil { - t.Fatal(err) - } - } - - got, err := s.OpenTaskByPR(ctx, "acme", "widget", 101) - if err != nil || got == nil || got.IssueNumber != 1 { - t.Fatalf("OpenTaskByPR(open) = (%+v, %v)", got, err) - } - for _, prNumber := range []int{102, 103, 999} { - got, err := s.OpenTaskByPR(ctx, "acme", "widget", prNumber) - if err != nil || got != nil { - t.Errorf("OpenTaskByPR(%d) = (%+v, %v), want (nil, nil)", prNumber, got, err) - } - } - if got, err := s.OpenTaskByPR(ctx, "other", "widget", 101); err != nil || got != nil { - t.Errorf("OpenTaskByPR(other owner) = (%+v, %v), want (nil, nil)", got, err) - } - - var indexedColumns string - if err := s.db.QueryRowContext(ctx, ` - SELECT group_concat(name, ',') - FROM pragma_index_info('idx_tasks_pr')`).Scan(&indexedColumns); err != nil { - t.Fatal(err) - } - if indexedColumns != "owner,repo,pr_number" { - t.Fatalf("idx_tasks_pr columns = %q, want owner,repo,pr_number", indexedColumns) - } -} - -func TestRequeueFromWaitingHuman(t *testing.T) { - s := openTest(t) - ctx := context.Background() - - if _, err := s.EnqueueIssue(ctx, "acme", "widget", 1, "t", "b", "", ""); err != nil { - t.Fatal(err) - } - task, err := s.ClaimNext(ctx) - if err != nil || task == nil { - t.Fatalf("claim = (%v, %v)", task, err) - } - - if err := s.Transition(ctx, task.ID, workflow.StatusRunning, workflow.StatusWaitingHuman, "needs input"); err != nil { - t.Fatal(err) - } - waiting, err := s.TaskByID(ctx, task.ID) - if err != nil || waiting == nil || waiting.Status != workflow.StatusWaitingHuman { - t.Fatalf("after transition = (%+v, %v), want waiting_human", waiting, err) - } - - // Requeue with a workflow forces it (waiting_human -> approved -> implement). - if err := s.Requeue(ctx, task.ID, workflow.StatusWaitingHuman, "implement"); err != nil { - t.Fatal(err) - } - requeued, err := s.TaskByIssue(ctx, "acme", "widget", 1) - if err != nil || requeued == nil || requeued.Status != workflow.StatusQueued || requeued.Workflow != "implement" { - t.Fatalf("after forced requeue = %+v, %v", requeued, err) - } - - // Requeue with an empty workflow keeps the task's current workflow - // (retrying a parked task). - task2, err := s.ClaimNext(ctx) - if err != nil || task2 == nil { - t.Fatalf("second claim = (%v, %v)", task2, err) - } - task2.Workflow = "feasibility" - if err := s.Update(ctx, task2); err != nil { - t.Fatal(err) - } - if err := s.Transition(ctx, task2.ID, workflow.StatusRunning, workflow.StatusParked, "parked"); err != nil { - t.Fatal(err) - } - if err := s.Requeue(ctx, task2.ID, workflow.StatusParked, ""); err != nil { - t.Fatal(err) - } - retried, err := s.TaskByIssue(ctx, "acme", "widget", 1) - if err != nil || retried == nil || retried.Status != workflow.StatusQueued || retried.Workflow != "feasibility" { - t.Fatalf("after empty-workflow requeue = %+v, %v", retried, err) - } - if retried.ParkReason != "" { - t.Fatalf("Requeue must clear park_reason, got %q", retried.ParkReason) - } - - // Verify retry_count is NOT reset by Requeue (it persists). Bumped - // directly rather than through RetryTask, which also transitions - // status -- this fixture only needs the counter moved. - if _, err := s.db.ExecContext(ctx, `UPDATE tasks SET retry_count = retry_count + 1 WHERE id = ?`, task2.ID); err != nil { - t.Fatal(err) - } - if _, err := s.db.ExecContext(ctx, `UPDATE tasks SET retry_count = retry_count + 1 WHERE id = ?`, task2.ID); err != nil { - t.Fatal(err) - } - // Park again and requeue. - if err := s.Transition(ctx, task2.ID, workflow.StatusQueued, workflow.StatusParked, "parked again"); err != nil { - t.Fatal(err) - } - if err := s.Requeue(ctx, task2.ID, workflow.StatusParked, ""); err != nil { - t.Fatal(err) - } - afterRequeue, err := s.TaskByIssue(ctx, "acme", "widget", 1) - if err != nil || afterRequeue == nil { - t.Fatalf("TaskByIssue after second requeue = (%+v, %v)", afterRequeue, err) - } - if afterRequeue.RetryCount != 2 { - t.Fatalf("Requeue must not reset retry_count, got %d, want 2", afterRequeue.RetryCount) - } -} - -func TestTasksListingAndStatusCounts(t *testing.T) { - s := openTest(t) - ctx := context.Background() - - for i, status := range []string{workflow.StatusQueued, workflow.StatusRunning, workflow.StatusPROpen} { - if _, err := s.EnqueueIssue(ctx, "acme", "widget", i+1, "t", "b", "", ""); err != nil { - t.Fatal(err) - } - task, err := s.TaskByIssue(ctx, "acme", "widget", i+1) - if err != nil || task == nil { - t.Fatalf("TaskByIssue(%d) = (%+v, %v)", i+1, task, err) - } - if status != workflow.StatusQueued { - if err := s.Transition(ctx, task.ID, workflow.StatusQueued, status, ""); err != nil { - t.Fatal(err) - } - } - } - - tasks, err := s.Tasks(ctx, 10) - if err != nil || len(tasks) != 3 { - t.Fatalf("Tasks = (%d, %v)", len(tasks), err) - } - - limited, err := s.Tasks(ctx, 2) - if err != nil || len(limited) != 2 { - t.Fatalf("Tasks with limit = (%d, %v)", len(limited), err) - } - - counts, err := s.StatusCounts(ctx) - if err != nil { - t.Fatal(err) - } - want := map[string]int{workflow.StatusQueued: 1, workflow.StatusRunning: 1, workflow.StatusPROpen: 1} - for status, n := range want { - if counts[status] != n { - t.Fatalf("StatusCounts[%s] = %d, want %d (all: %+v)", status, counts[status], n, counts) - } - } -} - -func TestWorkflowStats(t *testing.T) { - s := openTest(t) - ctx := context.Background() - - if _, err := s.EnqueueIssue(ctx, "acme", "widget", 1, "t", "b", "", ""); err != nil { - t.Fatal(err) - } - task, err := s.ClaimNext(ctx) - if err != nil || task == nil { - t.Fatalf("claim = (%v, %v)", task, err) - } - task.Workflow = "implement" - task.TokensUsed = 1000 - task.Iterations = 4 - if err := s.Update(ctx, task); err != nil { - t.Fatal(err) - } - if err := s.Transition(ctx, task.ID, workflow.StatusRunning, workflow.StatusMerged, "merged"); err != nil { - t.Fatal(err) - } - - stats, err := s.WorkflowStats(ctx) - if err != nil || len(stats) != 1 { - t.Fatalf("WorkflowStats = (%+v, %v)", stats, err) - } - got := stats[0] - if got.Workflow != "implement" || got.Runs != 1 || got.Merged != 1 || got.AvgTokens != 1000 || got.TotalToken != 1000 { - t.Fatalf("WorkflowStats[0] = %+v", got) - } -} - -func TestTokensByDayFallsBackToTaskTotals(t *testing.T) { - s := openTest(t) - ctx := context.Background() - - if _, err := s.EnqueueIssue(ctx, "acme", "widget", 1, "t", "b", "", ""); err != nil { - t.Fatal(err) - } - task, err := s.ClaimNext(ctx) - if err != nil || task == nil { - t.Fatalf("claim = (%v, %v)", task, err) - } - task.TokensUsed = 904901 - if err := s.Update(ctx, task); err != nil { - t.Fatal(err) - } - if _, err := s.db.ExecContext(ctx, `UPDATE tasks SET updated_at=? WHERE id=?`, "2026-08-14 12:00:00", task.ID); err != nil { - t.Fatal(err) - } - - got, err := s.TokensByDay(ctx, 14) - if err != nil { - t.Fatal(err) - } - want := []DayTokens{{Day: "2026-08-14", Tokens: 904901}} - if !reflect.DeepEqual(got, want) { - t.Fatalf("TokensByDay = %#v, want %#v", got, want) - } -} - -func TestTokensByDayUsesEventsAndIgnoresMalformedTokenFields(t *testing.T) { - s := openTest(t) - ctx := context.Background() - - if _, err := s.EnqueueIssue(ctx, "acme", "widget", 1, "event task", "b", "", ""); err != nil { - t.Fatal(err) - } - eventTask, err := s.ClaimNext(ctx) - if err != nil || eventTask == nil { - t.Fatalf("claim event task = (%v, %v)", eventTask, err) - } - eventTask.TokensUsed = 999 - if err := s.Update(ctx, eventTask); err != nil { - t.Fatal(err) - } - if _, err := s.db.ExecContext(ctx, `UPDATE tasks SET updated_at=? WHERE id=?`, "2026-08-14 12:00:00", eventTask.ID); err != nil { - t.Fatal(err) - } - for _, ev := range []events.Event{ - {Kind: events.KindAgentFinish, TaskID: eventTask.ID, At: time.Date(2026, 8, 13, 12, 0, 0, 0, time.UTC), Data: map[string]any{"tokens": 30}}, - {Kind: events.KindAgentFinish, TaskID: eventTask.ID, At: time.Date(2026, 8, 14, 12, 0, 0, 0, time.UTC), Data: map[string]any{"tokens": 70}}, - {Kind: events.KindAgentFinish, TaskID: eventTask.ID, At: time.Date(2026, 8, 14, 13, 0, 0, 0, time.UTC), Data: map[string]any{"tokens": "bad"}}, - } { - if _, err := s.InsertEvent(ctx, ev); err != nil { - t.Fatal(err) - } - } - - got, err := s.TokensByDay(ctx, 14) - if err != nil { - t.Fatal(err) - } - want := []DayTokens{{Day: "2026-08-14", Tokens: 70}, {Day: "2026-08-13", Tokens: 30}} - if !reflect.DeepEqual(got, want) { - t.Fatalf("TokensByDay = %#v, want %#v", got, want) - } -} - -func TestTokensByDayReturnsEmptySlice(t *testing.T) { - s := openTest(t) - got, err := s.TokensByDay(t.Context(), 14) - if err != nil { - t.Fatal(err) - } - if got == nil || len(got) != 0 { - t.Fatalf("TokensByDay = %#v, want non-nil empty slice", got) - } -} - -func TestStageStats(t *testing.T) { - s := openTest(t) - ctx := context.Background() - - // Insert 6 stage_finish events across 2 workflows × 3 stage groups. - // plan/draft: 3 runs, avg 400 ms, 1 error - // plan/review: 1 run, avg 300 ms, 0 errors - // implement/build: 2 runs, avg 1500 ms, 1 error - - type stageEvent struct { - workflow string - stage string - durationMs int - errorMsg string // empty means no error key - } - - inputs := []stageEvent{ - {workflow: "plan", stage: "draft", durationMs: 200}, - {workflow: "plan", stage: "draft", durationMs: 400}, - {workflow: "plan", stage: "draft", durationMs: 600, errorMsg: "something broke"}, - - {workflow: "plan", stage: "review", durationMs: 300}, - - {workflow: "implement", stage: "build", durationMs: 1000}, - {workflow: "implement", stage: "build", durationMs: 2000, errorMsg: "build failed"}, - } - - for _, in := range inputs { - data := map[string]any{"duration_ms": in.durationMs} - if in.errorMsg != "" { - data["error"] = in.errorMsg - } - if _, err := s.InsertEvent(ctx, events.Event{ - Kind: "stage_finish", - Workflow: in.workflow, - Stage: in.stage, - Data: data, - }); err != nil { - t.Fatal(err) - } - } - - stats, err := s.StageStats(ctx) - if err != nil { - t.Fatal(err) - } - - if len(stats) != 3 { - t.Fatalf("StageStats: got %d groups, want 3: %+v", len(stats), stats) - } - - // Verify ordering: workflow then stage. - want := []struct { - workflow string - stage string - runs int - avgMs int - errors int - }{ - {workflow: "implement", stage: "build", runs: 2, avgMs: 1500, errors: 1}, - {workflow: "plan", stage: "draft", runs: 3, avgMs: 400, errors: 1}, - {workflow: "plan", stage: "review", runs: 1, avgMs: 300, errors: 0}, - } - - for i, w := range want { - got := stats[i] - if got.Workflow != w.workflow { - t.Fatalf("stats[%d].Workflow = %q, want %q", i, got.Workflow, w.workflow) - } - if got.Stage != w.stage { - t.Fatalf("stats[%d].Stage = %q, want %q", i, got.Stage, w.stage) - } - if got.Runs != w.runs { - t.Fatalf("stats[%d].Runs = %d, want %d", i, got.Runs, w.runs) - } - if got.AvgMs != w.avgMs { - t.Fatalf("stats[%d].AvgMs = %d, want %d", i, got.AvgMs, w.avgMs) - } - if got.Errors != w.errors { - t.Fatalf("stats[%d].Errors = %d, want %d", i, got.Errors, w.errors) - } - } -} diff --git a/internal/store/remediation_test.go b/internal/store/remediation_test.go deleted file mode 100644 index 83d471c5b..000000000 --- a/internal/store/remediation_test.go +++ /dev/null @@ -1,220 +0,0 @@ -package store - -import ( - "errors" - "testing" - - "github.com/samcharles93/archie-core/internal/domain/workflow" -) - -// prOpenTask inserts a task and walks it to the state a reaction resolves -// against: the task opened its PR and is idle waiting for review. -func prOpenTask(t *testing.T, s *Store, owner, repo string, prNumber int) int64 { - t.Helper() - ok, err := s.EnqueueIssue(t.Context(), owner, repo, 1, "title", "body", "", "") - if err != nil { - t.Fatal(err) - } - if !ok { - t.Fatal("enqueue: task already tracked") - } - task, err := s.TaskByIssue(t.Context(), owner, repo, 1) - if err != nil || task == nil { - t.Fatalf("TaskByIssue = (%v, %v)", task, err) - } - task.PRNumber = prNumber - task.Status = workflow.StatusPROpen - if err := s.Transition(t.Context(), task.ID, workflow.StatusQueued, workflow.StatusPROpen, "PR opened"); err != nil { - t.Fatal(err) - } - if err := s.Update(t.Context(), task); err != nil { - t.Fatal(err) - } - return task.ID -} - -func TestBeginRemediationMovesAnOpenPRTaskToQueuedRemediate(t *testing.T) { - s := openTest(t) - id := prOpenTask(t, s, "acme", "widgets", 42) - - if err := s.BeginRemediation(t.Context(), id, `{"review_id":7}`); err != nil { - t.Fatalf("BeginRemediation: %v", err) - } - got, err := s.TaskByID(t.Context(), id) - if err != nil { - t.Fatal(err) - } - if got.Status != workflow.StatusQueued { - t.Errorf("status = %q, want queued", got.Status) - } - if got.Workflow != "remediate" { - t.Errorf("workflow = %q, want remediate", got.Workflow) - } - if got.ReviewPayload != `{"review_id":7}` { - t.Errorf("review_payload = %q, want the carried unit", got.ReviewPayload) - } - if got.ParkReason != "" || got.Stage != "" { - t.Errorf("park_reason/stage = %q/%q, want both empty", got.ParkReason, got.Stage) - } -} - -func TestBeginRemediationRefusesAnAlreadyClaimedTask(t *testing.T) { - s := openTest(t) - id := prOpenTask(t, s, "acme", "widgets", 42) - if err := s.BeginRemediation(t.Context(), id, `{"review_id":7}`); err != nil { - t.Fatal(err) - } - if err := s.BeginRemediation(t.Context(), id, `{"review_id":7}`); !errors.Is(err, ErrStaleTransition) { - t.Errorf("second BeginRemediation err = %v, want ErrStaleTransition", err) - } -} - -func TestBeginRemediationRefusesNonOpenPRStatuses(t *testing.T) { - s := openTest(t) - id := prOpenTask(t, s, "acme", "widgets", 42) - if err := s.Transition(t.Context(), id, workflow.StatusPROpen, workflow.StatusParked, "gate failed"); err != nil { - t.Fatal(err) - } - if err := s.BeginRemediation(t.Context(), id, `{"review_id":7}`); !errors.Is(err, ErrStaleTransition) { - t.Errorf("BeginRemediation on parked err = %v, want ErrStaleTransition", err) - } -} - -func TestUpdateReviewPayloadAppendsOnlyWhileARemediationIsQueued(t *testing.T) { - s := openTest(t) - id := prOpenTask(t, s, "acme", "widgets", 42) - if err := s.BeginRemediation(t.Context(), id, `{"review_id":7}`); err != nil { - t.Fatal(err) - } - - if err := s.UpdateReviewPayload(t.Context(), id, `{"review_id":7,"comments":[{"comment_id":9}]}`); err != nil { - t.Fatalf("UpdateReviewPayload while queued: %v", err) - } - got, err := s.TaskByID(t.Context(), id) - if err != nil { - t.Fatal(err) - } - if got.ReviewPayload != `{"review_id":7,"comments":[{"comment_id":9}]}` { - t.Errorf("review_payload = %q, want the appended unit", got.ReviewPayload) - } - - // Claim the task: the remediation is running, and a payload written under - // it would race the builder's input. - if _, err := s.ClaimNext(t.Context()); err != nil { - t.Fatal(err) - } - if err := s.UpdateReviewPayload(t.Context(), id, `{"review_id":7,"comments":[{"comment_id":10}]}`); !errors.Is(err, ErrStaleTransition) { - t.Errorf("UpdateReviewPayload while running err = %v, want ErrStaleTransition", err) - } -} - -// TestParkTaskWritesItsClassification pins the classified park write: the -// class is recorded at the park site in the same guarded write, and an -// unclassified park defaults to needs_human. -func TestParkTaskWritesItsClassification(t *testing.T) { - s := openTest(t) - ctx := t.Context() - if _, err := s.EnqueueIssue(ctx, "acme", "widgets", 1, "t", "b", "", ""); err != nil { - t.Fatal(err) - } - task, _ := s.TaskByIssue(ctx, "acme", "widgets", 1) - if _, err := s.ClaimNext(ctx); err != nil { - t.Fatal(err) - } - - if err := s.ParkTask(ctx, task.ID, workflow.StatusRunning, "container acquire failed", "transient"); err != nil { - t.Fatalf("ParkTask: %v", err) - } - got, err := s.TaskByID(ctx, task.ID) - if err != nil { - t.Fatal(err) - } - if got.Status != workflow.StatusParked || got.ParkReason != "container acquire failed" { - t.Errorf("park row = status:%q reason:%q", got.Status, got.ParkReason) - } - if got.ParkClass != "transient" { - t.Errorf("park_class = %q, want transient", got.ParkClass) - } - - // Requeue clears the class with the reason: a stale class on a queued - // task would group a live task with parked ones. - if err := s.Requeue(ctx, task.ID, workflow.StatusParked, ""); err != nil { - t.Fatal(err) - } - got, _ = s.TaskByID(ctx, task.ID) - if got.ParkClass != "needs_human" || got.ParkReason != "" { - t.Errorf("after requeue: class=%q reason=%q, want cleared", got.ParkClass, got.ParkReason) - } -} - -func TestParkTaskRejectsAnUnknownClass(t *testing.T) { - s := openTest(t) - ctx := t.Context() - if _, err := s.EnqueueIssue(ctx, "acme", "widgets", 1, "t", "b", "", ""); err != nil { - t.Fatal(err) - } - task, _ := s.TaskByIssue(ctx, "acme", "widgets", 1) - if _, err := s.ClaimNext(ctx); err != nil { - t.Fatal(err) - } - // An unknown class normalizes to needs_human rather than persisting a - // value no consumer knows how to group. - if err := s.ParkTask(ctx, task.ID, workflow.StatusRunning, "x", "urgent"); err != nil { - t.Fatal(err) - } - got, _ := s.TaskByID(ctx, task.ID) - if got.ParkClass != "needs_human" { - t.Errorf("park_class = %q, want the needs_human fallback", got.ParkClass) - } -} - -func TestParkTaskStaleGuard(t *testing.T) { - s := openTest(t) - ctx := t.Context() - if _, err := s.EnqueueIssue(ctx, "acme", "widgets", 1, "t", "b", "", ""); err != nil { - t.Fatal(err) - } - task, _ := s.TaskByIssue(ctx, "acme", "widgets", 1) - // Still queued, not running: the from guard must refuse. - if err := s.ParkTask(ctx, task.ID, workflow.StatusRunning, "x", "transient"); !errors.Is(err, ErrStaleTransition) { - t.Errorf("ParkTask stale err = %v, want ErrStaleTransition", err) - } -} - -func TestTransitionToParkedDefaultsTheClass(t *testing.T) { - s := openTest(t) - ctx := t.Context() - if _, err := s.EnqueueIssue(ctx, "acme", "widgets", 1, "t", "b", "", ""); err != nil { - t.Fatal(err) - } - task, _ := s.TaskByIssue(ctx, "acme", "widgets", 1) - if _, err := s.ClaimNext(ctx); err != nil { - t.Fatal(err) - } - // The generic transition is the workflow engine's park path: every - // unclassified park reads as operator-actionable. - if err := s.Transition(ctx, task.ID, workflow.StatusRunning, workflow.StatusParked, "gate failed"); err != nil { - t.Fatal(err) - } - got, _ := s.TaskByID(ctx, task.ID) - if got.ParkClass != "needs_human" { - t.Errorf("park_class = %q, want the needs_human default", got.ParkClass) - } -} - -func TestUpdateCarriesRemediationRounds(t *testing.T) { - s := openTest(t) - ctx := t.Context() - if _, err := s.EnqueueIssue(ctx, "acme", "widgets", 1, "t", "b", "", ""); err != nil { - t.Fatal(err) - } - task, _ := s.TaskByIssue(ctx, "acme", "widgets", 1) - task.RemediationRounds = 2 - if err := s.Update(ctx, task); err != nil { - t.Fatal(err) - } - got, _ := s.TaskByID(ctx, task.ID) - if got.RemediationRounds != 2 { - t.Errorf("remediation_rounds = %d, want 2", got.RemediationRounds) - } -} diff --git a/internal/store/resources.go b/internal/store/resources.go deleted file mode 100644 index bee6948c3..000000000 --- a/internal/store/resources.go +++ /dev/null @@ -1,127 +0,0 @@ -package store - -import ( - "context" - "database/sql" - "errors" - "fmt" - "time" - - "github.com/samcharles93/archie-core/internal/domain/storecontract" -) - -// Resource types and their sentinels moved to storecontract (the producer-owned -// contract) so the PostgreSQL implementation can reference them without linking -// this SQLite package. These aliases keep daemon-side callers (the control -// plane) and the in-package tests unchanged. -var ( - ErrResourceNotFound = storecontract.ErrResourceNotFound - ErrResourceVersionConflict = storecontract.ErrResourceVersionConflict -) - -type Resource = storecontract.Resource - -type ResourceWrite = storecontract.ResourceWrite - -const resourcesSchema = ` -CREATE TABLE IF NOT EXISTS resources ( - kind TEXT PRIMARY KEY, value BLOB NOT NULL, version INTEGER NOT NULL, updated_at TEXT NOT NULL -); -CREATE TABLE IF NOT EXISTS resource_history ( - id INTEGER PRIMARY KEY AUTOINCREMENT, kind TEXT NOT NULL, value BLOB NOT NULL, - version INTEGER NOT NULL, actor TEXT NOT NULL, source TEXT NOT NULL, - request_id TEXT NOT NULL, expected_version INTEGER NOT NULL, - current_version INTEGER NOT NULL, at TEXT NOT NULL -); -CREATE INDEX IF NOT EXISTS idx_resource_history_kind_version ON resource_history(kind, version); --- The request-ID idempotency key is per kind, not global: a resource write --- replays only the same kind's prior write (resourceByRequest). A database --- written before v4 carries the old global UNIQUE as a column constraint; --- migrateResourceHistoryToPerKindRequestIDs rebuilds it to this shape. -CREATE UNIQUE INDEX IF NOT EXISTS idx_resource_history_kind_request ON resource_history(kind, request_id); -` - -func (s *Store) Resource(ctx context.Context, kind string) (Resource, error) { - var r Resource - err := s.db.QueryRowContext(ctx, `SELECT kind,value,version,updated_at FROM resources WHERE kind=?`, kind). - Scan(&r.Kind, &r.Value, &r.Version, sqliteTime{&r.At}) - if errors.Is(err, sql.ErrNoRows) { - return Resource{}, ErrResourceNotFound - } - return r, err -} - -// ResourceHistory returns kind's revisions newest first, each carrying the -// audit record written with it. limit caps the rows; zero or less returns -// every revision. An unknown kind has no history, which is not an error. -func (s *Store) ResourceHistory(ctx context.Context, kind string, limit int) ([]Resource, error) { - if limit <= 0 { - limit = -1 - } - rows, err := s.db.QueryContext(ctx, `SELECT kind,value,version,actor,source,request_id,expected_version,current_version,at FROM resource_history WHERE kind=? ORDER BY version DESC LIMIT ?`, kind, limit) - if err != nil { - return nil, err - } - defer func() { _ = rows.Close() }() - var history []Resource - for rows.Next() { - var r Resource - if err := rows.Scan(&r.Kind, &r.Value, &r.Version, &r.Actor, &r.Source, &r.RequestID, &r.ExpectedVersion, &r.CurrentVersion, sqliteTime{&r.At}); err != nil { - return nil, err - } - history = append(history, r) - } - return history, rows.Err() -} - -func (s *Store) PutResource(ctx context.Context, w ResourceWrite) (_ Resource, retErr error) { - tx, err := s.db.BeginTx(ctx, nil) - if err != nil { - return Resource{}, err - } - defer func() { _ = tx.Rollback() }() - - if existing, ok, err := resourceByRequest(ctx, tx, w.Kind, w.RequestID); err != nil { - return Resource{}, err - } else if ok { - return existing, nil - } - var current int64 - err = tx.QueryRowContext(ctx, `SELECT version FROM resources WHERE kind=?`, w.Kind).Scan(¤t) - if err != nil && !errors.Is(err, sql.ErrNoRows) { - return Resource{}, err - } - if current != w.ExpectedVersion { - return Resource{}, fmt.Errorf("%w: expected %d, current %d", ErrResourceVersionConflict, w.ExpectedVersion, current) - } - if w.At.IsZero() { - w.At = time.Now().UTC() - } - next := current + 1 - at := w.At.UTC().Format(time.RFC3339Nano) - if _, err := tx.ExecContext(ctx, `INSERT INTO resources(kind,value,version,updated_at) VALUES(?,?,?,?) ON CONFLICT(kind) DO UPDATE SET value=excluded.value,version=excluded.version,updated_at=excluded.updated_at`, w.Kind, w.Value, next, at); err != nil { - return Resource{}, err - } - if _, err := tx.ExecContext(ctx, `INSERT INTO resource_history(kind,value,version,actor,source,request_id,expected_version,current_version,at) VALUES(?,?,?,?,?,?,?,?,?)`, w.Kind, w.Value, next, w.Actor, w.Source, w.RequestID, w.ExpectedVersion, current, at); err != nil { - return Resource{}, err - } - if err := tx.Commit(); err != nil { - return Resource{}, err - } - return Resource{Kind: w.Kind, Value: append([]byte(nil), w.Value...), Version: next, Actor: w.Actor, Source: w.Source, RequestID: w.RequestID, ExpectedVersion: w.ExpectedVersion, CurrentVersion: current, At: w.At.UTC()}, nil -} - -// resourceByRequest replays one prior write by its request ID, so a retried -// replace is idempotent instead of a second revision. The key is (kind, -// request ID), not the request ID alone: the API is per kind, so an ID reused -// across kinds must write the new kind rather than silently replay the first -// kind's resource (archie-core-fcvd). -func resourceByRequest(ctx context.Context, tx *sql.Tx, kind, requestID string) (Resource, bool, error) { - var r Resource - err := tx.QueryRowContext(ctx, `SELECT kind,value,version,actor,source,request_id,expected_version,current_version,at FROM resource_history WHERE kind=? AND request_id=?`, kind, requestID). - Scan(&r.Kind, &r.Value, &r.Version, &r.Actor, &r.Source, &r.RequestID, &r.ExpectedVersion, &r.CurrentVersion, sqliteTime{&r.At}) - if errors.Is(err, sql.ErrNoRows) { - return Resource{}, false, nil - } - return r, err == nil, err -} diff --git a/internal/store/resources_test.go b/internal/store/resources_test.go deleted file mode 100644 index f7e60d1b7..000000000 --- a/internal/store/resources_test.go +++ /dev/null @@ -1,110 +0,0 @@ -package store - -import ( - "errors" - "testing" - "time" -) - -func TestPutResourceRejectsStaleVersion(t *testing.T) { - s := OpenTest(t) - defer s.Close() - ctx := t.Context() - first, err := s.PutResource(ctx, ResourceWrite{Kind: "settings", Value: []byte(`{"v":1}`), Actor: "a", Source: "test", RequestID: "r1", ExpectedVersion: 0, At: time.Now()}) - if err != nil { - t.Fatal(err) - } - _, err = s.PutResource(ctx, ResourceWrite{Kind: "settings", Value: []byte(`{"v":2}`), Actor: "a", Source: "test", RequestID: "r2", ExpectedVersion: 0, At: time.Now()}) - if !errors.Is(err, ErrResourceVersionConflict) { - t.Fatalf("PutResource() error = %v, want ErrResourceVersionConflict (current %d)", err, first.Version) - } -} - -func TestPutResourceDuplicateRequestIsIdempotent(t *testing.T) { - s := OpenTest(t) - defer s.Close() - ctx := t.Context() - write := ResourceWrite{Kind: "settings", Value: []byte(`{"v":1}`), Actor: "a", Source: "test", RequestID: "same", ExpectedVersion: 0, At: time.Now()} - first, err := s.PutResource(ctx, write) - if err != nil { - t.Fatal(err) - } - write.Value = []byte(`{"v":999}`) - second, err := s.PutResource(ctx, write) - if err != nil { - t.Fatal(err) - } - if first.Version != second.Version || string(second.Value) != string(first.Value) { - t.Fatalf("duplicate = (%d, %s), want (%d, %s)", second.Version, second.Value, first.Version, first.Value) - } -} - -// TestPutResourceRequestIDIsScopedToTheKind: the request ID makes one write -// idempotent for the kind it wrote: the dedup key is (kind, request ID), so a -// request ID reused across two kinds writes the second instead of silently -// replaying the first kind's resource (archie-core-fcvd). -func TestPutResourceRequestIDIsScopedToTheKind(t *testing.T) { - s := OpenTest(t) - defer s.Close() - ctx := t.Context() - if _, err := s.PutResource(ctx, ResourceWrite{Kind: "settings", Value: []byte(`{"v":1}`), Actor: "a", Source: "test", RequestID: "shared", ExpectedVersion: 0, At: time.Now()}); err != nil { - t.Fatal(err) - } - second, err := s.PutResource(ctx, ResourceWrite{Kind: "other", Value: []byte(`{"v":9}`), Actor: "a", Source: "test", RequestID: "shared", ExpectedVersion: 0, At: time.Now()}) - if err != nil { - t.Fatalf("PutResource with a request ID another kind already used: %v", err) - } - if second.Kind != "other" || second.Version != 1 { - t.Fatalf("second write = (%s, v%d), want the %q write itself, not a replay of the first kind's resource", second.Kind, second.Version, "other") - } -} - -func TestResourceHistoryReturnsEveryRevisionNewestFirst(t *testing.T) { - s := OpenTest(t) - defer s.Close() - ctx := t.Context() - for i, write := range []ResourceWrite{ - {Kind: "settings", Value: []byte(`{"v":1}`), Actor: "operator", Source: "archie-ui", RequestID: "r1", ExpectedVersion: 0}, - {Kind: "settings", Value: []byte(`{"v":2}`), Actor: "operator", Source: "messaging", RequestID: "r2", ExpectedVersion: 1}, - {Kind: "other", Value: []byte(`{"v":9}`), Actor: "operator", Source: "archie-ui", RequestID: "r3", ExpectedVersion: 0}, - } { - write.At = time.Now().UTC() - if _, err := s.PutResource(ctx, write); err != nil { - t.Fatalf("write %d: %v", i, err) - } - } - - history, err := s.ResourceHistory(ctx, "settings", 10) - if err != nil { - t.Fatal(err) - } - if len(history) != 2 { - t.Fatalf("history = %d revisions, want 2 (other kinds must not leak in)", len(history)) - } - if history[0].Version != 2 || string(history[0].Value) != `{"v":2}` || history[0].Source != "messaging" { - t.Fatalf("newest revision = %+v, want version 2 from messaging", history[0]) - } - if history[1].Version != 1 || history[1].Actor != "operator" || history[1].At.IsZero() { - t.Fatalf("oldest revision = %+v, want version 1 with its audit intact", history[1]) - } - - limited, err := s.ResourceHistory(ctx, "settings", 1) - if err != nil { - t.Fatal(err) - } - if len(limited) != 1 || limited[0].Version != 2 { - t.Fatalf("limited history = %+v, want the newest revision alone", limited) - } -} - -func TestResourceHistoryForUnknownKindIsEmpty(t *testing.T) { - s := OpenTest(t) - defer s.Close() - history, err := s.ResourceHistory(t.Context(), "missing", 10) - if err != nil { - t.Fatalf("history for an unknown kind must not error: %v", err) - } - if len(history) != 0 { - t.Fatalf("history = %+v, want empty", history) - } -} diff --git a/internal/store/review_cursor_test.go b/internal/store/review_cursor_test.go deleted file mode 100644 index 962bf2aba..000000000 --- a/internal/store/review_cursor_test.go +++ /dev/null @@ -1,45 +0,0 @@ -package store - -import ( - "errors" - "testing" - - "github.com/samcharles93/archie-core/internal/domain/workflow" -) - -// TestOpenPRsCarriesReviewCursors pins the poll backstop's read side: the -// per-PR scan reads each task's persisted review and comment cursors, so a -// daemon restart resumes where the last scan stopped instead of re-listing -// every review the forge has ever returned. -func TestOpenPRsCarriesReviewCursors(t *testing.T) { - s := openTest(t) - id := prOpenTask(t, s, "acme", "widgets", 42) - if err := s.SetReviewCursors(t.Context(), id, 100, 200); err != nil { - t.Fatalf("SetReviewCursors: %v", err) - } - - tasks, err := s.OpenPRs(t.Context()) - if err != nil || len(tasks) != 1 { - t.Fatalf("OpenPRs = (%d tasks, %v), want 1", len(tasks), err) - } - if tasks[0].ReviewCursor != 100 { - t.Errorf("ReviewCursor = %d, want 100", tasks[0].ReviewCursor) - } - if tasks[0].WatchCommentID != 200 { - t.Errorf("WatchCommentID = %d, want 200 (the review-comment cursor)", tasks[0].WatchCommentID) - } -} - -// TestSetReviewCursorsGuardsOnStatus pins the write side: cursors only move -// while the task is idle in pr_open. A cursor written under a running or -// parked task would desync from what its remediation run has consumed. -func TestSetReviewCursorsRefusesNonOpenPRStatuses(t *testing.T) { - s := openTest(t) - id := prOpenTask(t, s, "acme", "widgets", 42) - if err := s.Transition(t.Context(), id, workflow.StatusPROpen, workflow.StatusParked, "gate failed"); err != nil { - t.Fatal(err) - } - if err := s.SetReviewCursors(t.Context(), id, 5, 6); !errors.Is(err, ErrStaleTransition) { - t.Errorf("SetReviewCursors on parked err = %v, want ErrStaleTransition", err) - } -} diff --git a/internal/store/store.go b/internal/store/store.go deleted file mode 100644 index 60da7f5f6..000000000 --- a/internal/store/store.go +++ /dev/null @@ -1,929 +0,0 @@ -// Package store is archied's SQLite state: one row per task (a GitHub -// issue picked up for work), with every lifecycle transition recorded. -package store - -import ( - "context" - "database/sql" - "errors" - "fmt" - "os" - "path/filepath" - "strings" - "time" - "unicode/utf8" - - _ "modernc.org/sqlite" - - "github.com/samcharles93/archie-core/internal/domain/storecontract" - "github.com/samcharles93/archie-core/internal/domain/workflow" - "github.com/samcharles93/archie-core/internal/events" - "github.com/samcharles93/archie-core/internal/taskstate" -) - -type Store struct { - db *sql.DB -} - -// taskSchemaVersion is the newest schema this binary opens. ValidateFile -// refuses a database whose version is newer, so a binary and the file it -// opens move together. -const taskSchemaVersion = 4 - -// OpenOption configures the store at open time. -type OpenOption func(*openOptions) - -type openOptions struct{} - -// Open opens (creating if needed) the SQLite database and its schema. -func Open(ctx context.Context, path string, opts ...OpenOption) (*Store, error) { - var o openOptions - for _, opt := range opts { - opt(&o) - } - if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { - return nil, err - } - db, err := sql.Open("sqlite", sqliteDSN(path)) - if err != nil { - return nil, err - } - db.SetMaxOpenConns(1) - if _, err := db.ExecContext(ctx, schema+eventsSchema+configSnapshotSchema+channelStatusSchema+applyStatusSchema+resourcesSchema+identitiesSchema); err != nil { - return nil, errors.Join(fmt.Errorf("store: init schema: %w", err), db.Close()) - } - if err := migrateTasks(ctx, db); err != nil { - return nil, errors.Join(fmt.Errorf("store: migrate: %w", err), db.Close()) - } - return &Store{db: db}, nil -} - -func sqliteDSN(path string) string { - separator := "?" - if strings.HasSuffix(path, "?") || strings.HasSuffix(path, "&") { - separator = "" - } else if strings.Contains(path, "?") { - separator = "&" - } - return path + separator + "_pragma=journal_mode(WAL)&_pragma=busy_timeout(5000)" -} - -func migrateTasks(ctx context.Context, db *sql.DB) error { - tx, err := db.BeginTx(ctx, nil) - if err != nil { - return err - } - defer func() { _ = tx.Rollback() }() - - var version int - if err := tx.QueryRowContext(ctx, `PRAGMA user_version`).Scan(&version); err != nil { - return err - } - if version > taskSchemaVersion { - return fmt.Errorf("database schema version %d is newer than supported version %d", version, taskSchemaVersion) - } - columns, err := taskColumns(ctx, tx) - if err != nil { - return err - } - // events is created by `CREATE TABLE IF NOT EXISTS` (eventsSchema), which - // is a no-op against a database that already has the table. On an existing - // archie.db this read plus the `events` arm below is therefore the ONLY - // thing that adds events.attempt; without it the first insert fails with - // `table events has no column named attempt`. - eventsColumns, err := tableColumns(ctx, tx, "events") - if err != nil { - return err - } - - migrations := []struct { - table string - column string - sql string - }{ - {"tasks", "watch_comment_id", `ALTER TABLE tasks ADD COLUMN watch_comment_id INTEGER NOT NULL DEFAULT 0`}, - {"tasks", "review_cursor", `ALTER TABLE tasks ADD COLUMN review_cursor INTEGER NOT NULL DEFAULT 0`}, - {"tasks", "park_class", `ALTER TABLE tasks ADD COLUMN park_class TEXT NOT NULL DEFAULT 'needs_human'`}, - {"tasks", "remediation_rounds", `ALTER TABLE tasks ADD COLUMN remediation_rounds INTEGER NOT NULL DEFAULT 0`}, - {"tasks", "retry_count", `ALTER TABLE tasks ADD COLUMN retry_count INTEGER NOT NULL DEFAULT 0`}, - {"tasks", "source", `ALTER TABLE tasks ADD COLUMN source TEXT NOT NULL DEFAULT 'forge'`}, - {"tasks", "identity", `ALTER TABLE tasks ADD COLUMN identity TEXT NOT NULL DEFAULT ''`}, - {"tasks", "binding_id", `ALTER TABLE tasks ADD COLUMN binding_id TEXT NOT NULL DEFAULT ''`}, - {"tasks", "binding_version", `ALTER TABLE tasks ADD COLUMN binding_version INTEGER NOT NULL DEFAULT 0`}, - {"tasks", "review_payload", `ALTER TABLE tasks ADD COLUMN review_payload TEXT NOT NULL DEFAULT ''`}, - {"tasks", "workflow_definition_version", `ALTER TABLE tasks ADD COLUMN workflow_definition_version INTEGER NOT NULL DEFAULT 0`}, - {"tasks", "workflow_definition_digest", `ALTER TABLE tasks ADD COLUMN workflow_definition_digest TEXT NOT NULL DEFAULT ''`}, - {"tasks", "workflow_definition_yaml", `ALTER TABLE tasks ADD COLUMN workflow_definition_yaml TEXT NOT NULL DEFAULT ''`}, - {"events", "attempt", `ALTER TABLE events ADD COLUMN attempt INTEGER NOT NULL DEFAULT 0`}, - {"events", "actor_id", `ALTER TABLE events ADD COLUMN actor_id TEXT NOT NULL DEFAULT ''`}, - {"events", "actor_kind", `ALTER TABLE events ADD COLUMN actor_kind TEXT NOT NULL DEFAULT ''`}, - {"events", "principal_id", `ALTER TABLE events ADD COLUMN principal_id TEXT NOT NULL DEFAULT ''`}, - } - for _, migration := range migrations { - // Only tasks and events remain here; the event-capture tables moved - // to internal/infrastructure/edastore, which owns their schema. - present := columns - if migration.table == "events" { - present = eventsColumns - } - if present[migration.column] { - continue - } - if _, err := tx.ExecContext(ctx, migration.sql); err != nil { - return err - } - } - if err := migrateResourceHistoryToPerKindRequestIDs(ctx, tx); err != nil { - return err - } - if err := migrateEventTimestamps(ctx, tx); err != nil { - return err - } - return finishTaskMigration(ctx, tx, columns) -} - -// migrateResourceHistoryToPerKindRequestIDs is the v4 step: the history -// table's global request_id UNIQUE becomes per-kind uniqueness, the key the -// resource write path actually dedups on (resourceByRequest). SQLite cannot -// drop a column constraint, so the table is rebuilt in place; a global -// constraint is strictly stricter than the per-kind one, so no existing row -// can fail the new shape. Detection is the auto-index the old column -// constraint created -- sqlite_master carries it with a NULL sql -- which the -// rebuilt table leaves no copy of, so the step is a no-op on a database that -// already has the v4 shape (including one resourcesSchema created fresh). -func migrateResourceHistoryToPerKindRequestIDs(ctx context.Context, tx *sql.Tx) error { - var autoIndexes int - if err := tx.QueryRowContext(ctx, `SELECT count(*) FROM sqlite_master WHERE type='index' AND tbl_name='resource_history' AND sql IS NULL`).Scan(&autoIndexes); err != nil { - return err - } - if autoIndexes == 0 { - return nil - } - for _, statement := range []string{ - `CREATE TABLE resource_history_per_kind_request ( - id INTEGER PRIMARY KEY AUTOINCREMENT, kind TEXT NOT NULL, value BLOB NOT NULL, - version INTEGER NOT NULL, actor TEXT NOT NULL, source TEXT NOT NULL, - request_id TEXT NOT NULL, expected_version INTEGER NOT NULL, - current_version INTEGER NOT NULL, at TEXT NOT NULL - )`, - `INSERT INTO resource_history_per_kind_request (id,kind,value,version,actor,source,request_id,expected_version,current_version,at) - SELECT id,kind,value,version,actor,source,request_id,expected_version,current_version,at FROM resource_history`, - `DROP TABLE resource_history`, - `ALTER TABLE resource_history_per_kind_request RENAME TO resource_history`, - `CREATE INDEX IF NOT EXISTS idx_resource_history_kind_version ON resource_history(kind, version)`, - `CREATE UNIQUE INDEX IF NOT EXISTS idx_resource_history_kind_request ON resource_history(kind, request_id)`, - } { - if _, err := tx.ExecContext(ctx, statement); err != nil { - return fmt.Errorf("rebuild resource_history for per-kind request IDs: %w", err) - } - } - return nil -} - -// migrateEventTimestamps normalises the events.at column to the fixed-width -// layout the EventsSince cursor sorts on. Rows written before the cursor -// change used time.RFC3339Nano, which trims trailing zeros, so a whole-second -// row (20 chars) and a full-precision row (30 chars) would compare out of -// chronological order as strings. The ALTER-only migration arms never UPDATE -// values, so this is a separate idempotent step (the v4 precedent): it -// re-evaluates on every open, detects an already-normalised file by length, -// and re-runs cleanly on one that has never been migrated. -func migrateEventTimestamps(ctx context.Context, tx *sql.Tx) error { - updates, err := scanLegacyEventTimestamps(ctx, tx) - if err != nil { - return err - } - for _, u := range updates { - if _, err := tx.ExecContext(ctx, `UPDATE events SET at = ? WHERE id = ?`, u.at, u.id); err != nil { - return err - } - } - return nil -} - -// eventTimestampUpdate is one event row whose at predates the fixed-width -// layout, re-rendered into that layout. -type eventTimestampUpdate struct { - id int64 - at string -} - -// scanLegacyEventTimestamps reads every event row whose at predates the -// fixed-width layout, parses it, and re-renders it. The read cursor is closed -// by the defer before this function returns, so the caller's UPDATEs run on a -// free connection -- the store opens with SetMaxOpenConns(1), and a still-open -// read cursor would hold that single connection and deadlock the writes. -func scanLegacyEventTimestamps(ctx context.Context, tx *sql.Tx) ([]eventTimestampUpdate, error) { - // A fixed-width row is exactly len(EventCursorLayout) characters; anything - // else predates the layout and needs re-formatting. - fixed := strings.Repeat("?", len(storecontract.EventCursorLayout)) - rows, err := tx.QueryContext(ctx, `SELECT id, at FROM events WHERE at NOT GLOB '`+fixed+`'`) - if err != nil { - return nil, err - } - defer rows.Close() - - var updates []eventTimestampUpdate - for rows.Next() { - var u eventTimestampUpdate - if err := rows.Scan(&u.id, &u.at); err != nil { - return nil, err - } - parsed, err := time.Parse(time.RFC3339Nano, u.at) - if err != nil { - return nil, fmt.Errorf("normalise event timestamp %q: %w", u.at, err) - } - u.at = parsed.UTC().Format(storecontract.EventCursorLayout) - updates = append(updates, u) - } - if err := rows.Err(); err != nil { - return nil, err - } - return updates, nil -} - -func finishTaskMigration(ctx context.Context, tx *sql.Tx, columns map[string]bool) error { - if columns["owner"] && columns["repo"] && columns["pr_number"] { - if _, err := tx.ExecContext(ctx, `CREATE INDEX IF NOT EXISTS idx_tasks_pr ON tasks(owner, repo, pr_number)`); err != nil { - return err - } - } - if _, err := tx.ExecContext(ctx, fmt.Sprintf(`PRAGMA user_version = %d`, taskSchemaVersion)); err != nil { - return err - } - return tx.Commit() -} - -func taskColumns(ctx context.Context, tx *sql.Tx) (_ map[string]bool, retErr error) { - return tableColumns(ctx, tx, "tasks") -} - -func tableColumns(ctx context.Context, tx *sql.Tx, table string) (_ map[string]bool, retErr error) { - rows, err := tx.QueryContext(ctx, fmt.Sprintf(`PRAGMA table_info(%s)`, table)) - if err != nil { - return nil, err - } - defer func() { retErr = errors.Join(retErr, rows.Close()) }() - columns := make(map[string]bool) - for rows.Next() { - var cid, notNull, primaryKey int - var name, columnType string - var defaultValue any - if err := rows.Scan(&cid, &name, &columnType, ¬Null, &defaultValue, &primaryKey); err != nil { - return nil, err - } - columns[name] = true - } - return columns, rows.Err() -} - -const schema = ` -CREATE TABLE IF NOT EXISTS tasks ( - id INTEGER PRIMARY KEY AUTOINCREMENT, - owner TEXT NOT NULL, - repo TEXT NOT NULL, - issue_number INTEGER NOT NULL, - title TEXT NOT NULL DEFAULT '', - body TEXT NOT NULL DEFAULT '', - labels TEXT NOT NULL DEFAULT '', - status TEXT NOT NULL DEFAULT '` + workflow.StatusQueued + `', - workflow TEXT NOT NULL DEFAULT '', - stage TEXT NOT NULL DEFAULT '', - branch TEXT NOT NULL DEFAULT '', - plan TEXT NOT NULL DEFAULT '', - notes TEXT NOT NULL DEFAULT '', - pr_number INTEGER NOT NULL DEFAULT 0, - tokens_used INTEGER NOT NULL DEFAULT 0, - iterations INTEGER NOT NULL DEFAULT 0, - attempt INTEGER NOT NULL DEFAULT 0, - park_reason TEXT NOT NULL DEFAULT '', - watch_comment_id INTEGER NOT NULL DEFAULT 0, - park_class TEXT NOT NULL DEFAULT 'needs_human', - remediation_rounds INTEGER NOT NULL DEFAULT 0, - retry_count INTEGER NOT NULL DEFAULT 0, - source TEXT NOT NULL DEFAULT 'forge', - identity TEXT NOT NULL DEFAULT '', - -- binding_id carries the id of the edastore binding that produced this - -- task, or "" for a task nobody bound. It is TEXT because bindings are - -- PocketBase records; a database created before that stores the same - -- values in an INTEGER-affinity column, which SQLite keeps as TEXT. - binding_id TEXT NOT NULL DEFAULT '', - binding_version INTEGER NOT NULL DEFAULT 0, - review_payload TEXT NOT NULL DEFAULT '', - workflow_definition_version INTEGER NOT NULL DEFAULT 0, - workflow_definition_digest TEXT NOT NULL DEFAULT '', - workflow_definition_yaml TEXT NOT NULL DEFAULT '', - created_at TEXT NOT NULL DEFAULT (datetime('now')), - updated_at TEXT NOT NULL DEFAULT (datetime('now')), - UNIQUE(owner, repo, issue_number) -); -CREATE TABLE IF NOT EXISTS transitions ( - id INTEGER PRIMARY KEY AUTOINCREMENT, - task_id INTEGER NOT NULL, - at TEXT NOT NULL DEFAULT (datetime('now')), - from_status TEXT NOT NULL, - to_status TEXT NOT NULL, - detail TEXT NOT NULL DEFAULT '' -); -` - -func (s *Store) Close() error { return s.db.Close() } - -// DB exposes the underlying *sql.DB so tests outside the store -// package can drive fixtures that the public surface does not (yet) -// cover -- e.g. advancing a binding draft -> pending_approval without -// going through the operator edit flow. Production callers must NOT -// use this; the structured methods above are the contract. -func (s *Store) DB() *sql.DB { return s.db } - -// OpenTest opens an in-memory SQLite store suitable for tests. -func OpenTest(t interface { - TempDir() string - Context() context.Context -}, -) *Store { - s, err := Open(t.Context(), filepath.Join(t.TempDir(), "test.db")) - if err != nil { - panic(err) - } - return s -} - -// EnqueueIssue inserts a new queued task for the issue; returns false if -// the issue is already tracked (the idempotency key is owner/repo/number). -// The task's Source defaults to "forge" (the SQLite column default). -// identity is the archie identity whose forge poll discovered this issue -// (empty for single-identity deployments); it scopes which identity's -// forge client, worktree manager, and config downstream processing uses. -func (s *Store) EnqueueIssue(ctx context.Context, owner, repo string, number int, title, body, labels, identity string) (bool, error) { - res, err := s.db.ExecContext(ctx, ` - INSERT INTO tasks (owner, repo, issue_number, title, body, labels, identity) - VALUES (?, ?, ?, ?, ?, ?, ?) - ON CONFLICT(owner, repo, issue_number) DO NOTHING`, - owner, repo, number, title, body, labels, identity) - if err != nil { - return false, err - } - n, _ := res.RowsAffected() - return n > 0, nil -} - -// EnqueueChatTask inserts a new queued task with Source "chat" and no -// backing forge issue, returning the full created row (with its real -// database ID). The store allocates the synthetic issue number durably so -// multiple processes sharing the database cannot generate the same value. -// Workflow stages and daemon reconciliation must check workflow.Task.IsForgeBacked() -// before treating it as a real forge issue number. -func (s *Store) EnqueueChatTask(ctx context.Context, owner, repo, title, body, wf, identity string) (*workflow.Task, error) { - const syntheticIssueNumberBase = 1_000_000_000_000_000 - row := s.db.QueryRowContext(ctx, ` - INSERT INTO tasks (owner, repo, issue_number, title, body, labels, workflow, source, identity) - VALUES (?, ?, COALESCE(( - SELECT MAX(issue_number) FROM tasks - WHERE owner = ? AND repo = ? AND source = 'chat' - ), ?) + 1, ?, ?, 'chat', ?, 'chat', ?) - RETURNING id, owner, repo, issue_number, title, body, labels, status, - workflow, stage, branch, plan, notes, pr_number, tokens_used, - iterations, attempt, park_reason, watch_comment_id, retry_count, - source, identity, binding_id, binding_version, review_payload, - workflow_definition_version, workflow_definition_digest, workflow_definition_yaml, park_class, remediation_rounds, created_at, updated_at`, - owner, repo, owner, repo, syntheticIssueNumberBase-1, title, body, wf, identity) - return scanTask(row) -} - -// EnqueueBindingTask enqueues a task triggered by a playbook binding -// dispatch (t2db.4 Phase B). It builds the row through EnqueueChatTask -// (so the synthetic issue-number allocator stays the single source of -// truth for chat-sourced tasks) and then stamps binding_id and -// binding_version on the new row in a second statement. -// -// A crash between the two writes leaves the task without provenance -// (binding_id == 0); the binding_dispatches ledger row written by the -// dispatch loop still records the (binding, capture, task) triple, so -// a future repair pass could backfill. This is the same -// best-effort-provenance pattern the rest of the task lifecycle uses -// for fields added after the row's primary insert. -func (s *Store) EnqueueBindingTask(ctx context.Context, owner, repo, title, body, wf, identity, bindingID string, bindingVersion int) (*workflow.Task, error) { - t, err := s.EnqueueChatTask(ctx, owner, repo, title, body, wf, identity) - if err != nil { - return nil, err - } - if _, err := s.db.ExecContext(ctx, - `UPDATE tasks SET binding_id=?, binding_version=? WHERE id=?`, - bindingID, bindingVersion, t.ID); err != nil { - return nil, fmt.Errorf("store: stamp binding provenance: %w", err) - } - t.BindingID = bindingID - t.BindingVersion = bindingVersion - return t, nil -} - -// ClaimNext atomically moves the oldest queued task to running and -// returns it; nil when the queue is empty. -func (s *Store) ClaimNext(ctx context.Context) (*workflow.Task, error) { - row := s.db.QueryRowContext(ctx, ` - UPDATE tasks SET status=?, attempt=attempt+1, updated_at=datetime('now') - WHERE id = (SELECT id FROM tasks WHERE status=? ORDER BY id LIMIT 1) - RETURNING id, owner, repo, issue_number, title, body, labels, status, - workflow, stage, branch, plan, notes, pr_number, tokens_used, - iterations, attempt, park_reason, watch_comment_id, retry_count, - source, identity, binding_id, binding_version, review_payload, - workflow_definition_version, workflow_definition_digest, workflow_definition_yaml, park_class, remediation_rounds, created_at, updated_at`, - workflow.StatusRunning, workflow.StatusQueued) - t, err := scanTask(row) - if errors.Is(err, sql.ErrNoRows) { - return nil, nil - } - return t, err -} - -func scanTask(row *sql.Row) (*workflow.Task, error) { - var t workflow.Task - err := row.Scan(&t.ID, &t.Owner, &t.Repo, &t.IssueNumber, &t.Title, &t.Body, - &t.Labels, &t.Status, &t.Workflow, &t.Stage, &t.Branch, &t.Plan, &t.Notes, - &t.PRNumber, &t.TokensUsed, &t.Iterations, &t.Attempt, &t.ParkReason, - &t.WatchCommentID, &t.RetryCount, &t.Source, &t.Identity, - &t.BindingID, &t.BindingVersion, &t.ReviewPayload, - &t.WorkflowDefinitionVersion, &t.WorkflowDefinitionDigest, &t.WorkflowDefinitionYAML, - &t.ParkClass, &t.RemediationRounds, - sqliteTime{&t.CreatedAt}, sqliteTime{&t.UpdatedAt}) - if err != nil { - return nil, err - } - return &t, nil -} - -// ClaimByIssue atomically claims a queued task by owner/repo/issue_number. -// Returns nil if the task is not in queued state (already claimed, parked, -// or terminal). Used by the NATS consumer path where the task was just -// inserted via EnqueueIssue and needs an immediate targeted claim. -func (s *Store) ClaimByIssue(ctx context.Context, owner, repo string, number int) (*workflow.Task, error) { - row := s.db.QueryRowContext(ctx, ` - UPDATE tasks SET status=?, attempt=attempt+1, updated_at=datetime('now') - WHERE owner=? AND repo=? AND issue_number=? AND status=? - RETURNING id, owner, repo, issue_number, title, body, labels, status, - workflow, stage, branch, plan, notes, pr_number, tokens_used, - iterations, attempt, park_reason, watch_comment_id, retry_count, - source, identity, binding_id, binding_version, review_payload, - workflow_definition_version, workflow_definition_digest, workflow_definition_yaml, park_class, remediation_rounds, created_at, updated_at`, - workflow.StatusRunning, owner, repo, number, workflow.StatusQueued) - t, err := scanTask(row) - if errors.Is(err, sql.ErrNoRows) { - return nil, nil - } - return t, err -} - -// ErrStaleTransition is returned when a guarded transition fails because -// the task's current status does not match the expected from status. - -// Transition moves a task to a new status and records the audit detail. The -// from status guards the update; a mismatch returns ErrStaleTransition without -// writing an audit row. Transitioning to parked also stores detail as -// ParkReason in the same transaction. Detail used to exist only in the -// timeline, which left daemon-side parks looking reasonless in task APIs and -// the dashboard. -func (s *Store) Transition(ctx context.Context, taskID int64, from, to, detail string) error { - tx, err := s.db.BeginTx(ctx, nil) - if err != nil { - return err - } - defer func() { _ = tx.Rollback() }() - - res, err := tx.ExecContext(ctx, ` - UPDATE tasks - SET status=?, - park_reason=CASE WHEN ?=? THEN ? ELSE park_reason END, - park_class=CASE WHEN ?=? THEN ? ELSE park_class END, - updated_at=datetime('now') - WHERE id=? AND status=?`, - to, to, workflow.StatusParked, clip(detail, 4000), - to, to, taskstate.ParkNeedsHuman, taskID, from) - if err != nil { - return err - } - n, err := res.RowsAffected() - if err != nil { - return err - } - if n == 0 { - return ErrStaleTransition - } - - _, err = tx.ExecContext(ctx, - `INSERT INTO transitions (task_id, from_status, to_status, detail) VALUES (?, ?, ?, ?)`, - taskID, from, to, clip(detail, 4000)) - if err != nil { - return err - } - - return tx.Commit() -} - -// ParkTask is the classified park write: the same guarded running->parked -// transition Transition performs, carrying the park class the site chose. -// The class is normalized here so an unknown value persists as needs_human -// -- the safe misread is "an operator should look at this". -func (s *Store) ParkTask(ctx context.Context, taskID int64, from, detail, class string) error { - tx, err := s.db.BeginTx(ctx, nil) - if err != nil { - return err - } - defer func() { _ = tx.Rollback() }() - - res, err := tx.ExecContext(ctx, ` - UPDATE tasks - SET status=?, - park_reason=?, - park_class=?, - updated_at=datetime('now') - WHERE id=? AND status=?`, - workflow.StatusParked, clip(detail, 4000), - taskstate.NormalizeParkClass(class), taskID, from) - if err != nil { - return err - } - n, err := res.RowsAffected() - if err != nil { - return err - } - if n == 0 { - return ErrStaleTransition - } - - if _, err := tx.ExecContext(ctx, - `INSERT INTO transitions (task_id, from_status, to_status, detail) VALUES (?, ?, ?, ?)`, - taskID, from, workflow.StatusParked, clip(detail, 4000)); err != nil { - return err - } - - return tx.Commit() -} - -// Update persists mutable task fields written by workflows. -func (s *Store) Update(ctx context.Context, t *workflow.Task) error { - _, err := s.db.ExecContext(ctx, ` - UPDATE tasks SET workflow=?, stage=?, branch=?, plan=?, notes=?, - pr_number=?, tokens_used=?, iterations=?, park_reason=?, - watch_comment_id=?, retry_count=?, remediation_rounds=?, review_payload=?, workflow_definition_version=?, - workflow_definition_digest=?, workflow_definition_yaml=?, updated_at=datetime('now') - WHERE id=?`, - t.Workflow, t.Stage, t.Branch, t.Plan, t.Notes, - t.PRNumber, t.TokensUsed, t.Iterations, clip(t.ParkReason, 4000), - t.WatchCommentID, t.RetryCount, t.RemediationRounds, t.ReviewPayload, t.WorkflowDefinitionVersion, - t.WorkflowDefinitionDigest, t.WorkflowDefinitionYAML, t.ID) - return err -} - -// BeginRemediation transitions an Archie-owned open-PR task into a queued -// remediate run carrying the JSON-encoded review unit. The guarded update is -// the reaction consumer's dedup: a re-delivered reaction, or a second -// consumer racing the first, fails the status guard instead of starting a -// second round. The unit is written in the same transaction, so a task can -// never be claimed into a remediate run whose payload has not landed. -func (s *Store) BeginRemediation(ctx context.Context, taskID int64, payload string) error { - tx, err := s.db.BeginTx(ctx, nil) - if err != nil { - return err - } - defer func() { _ = tx.Rollback() }() - - res, err := tx.ExecContext(ctx, ` - UPDATE tasks SET status=?, workflow=?, stage='', park_reason='', park_class='needs_human', review_payload=?, - updated_at=datetime('now') - WHERE id=? AND status=?`, workflow.StatusQueued, "remediate", clip(payload, 4000), taskID, workflow.StatusPROpen) - if err != nil { - return err - } - n, err := res.RowsAffected() - if err != nil { - return err - } - if n == 0 { - return ErrStaleTransition - } - - if _, err := tx.ExecContext(ctx, - `INSERT INTO transitions (task_id, from_status, to_status, detail) VALUES (?, ?, ?, ?)`, - taskID, workflow.StatusPROpen, workflow.StatusQueued, "review reaction queued remediation"); err != nil { - return err - } - - return tx.Commit() -} - -// UpdateReviewPayload replaces a queued remediation's review unit: the -// reaction consumer appends late-arriving comments of the same review while -// the unit is still pending. The guarded update is the boundary — once a -// run is claimed, its input is frozen; a late comment is dropped by the -// caller rather than racing the builder's mission. -func (s *Store) UpdateReviewPayload(ctx context.Context, taskID int64, payload string) error { - res, err := s.db.ExecContext(ctx, ` - UPDATE tasks SET review_payload=?, updated_at=datetime('now') - WHERE id=? AND status=? AND workflow=?`, - clip(payload, 4000), taskID, workflow.StatusQueued, "remediate") - if err != nil { - return err - } - n, err := res.RowsAffected() - if err != nil { - return err - } - if n == 0 { - return ErrStaleTransition - } - return nil -} - -// SetReviewCursors persists the poll backstop's per-task high-water marks. -// The pr_open guard keeps a cursor from moving while a remediation run owns -// the task: the run's next round re-reads the cursors the scan wrote, and a -// write under a running task would desync them from what was consumed. -func (s *Store) SetReviewCursors(ctx context.Context, taskID, reviewCursor, commentCursor int64) error { - res, err := s.db.ExecContext(ctx, ` - UPDATE tasks SET review_cursor=?, watch_comment_id=?, updated_at=datetime('now') - WHERE id=? AND status=?`, - reviewCursor, commentCursor, taskID, workflow.StatusPROpen) - if err != nil { - return err - } - n, err := res.RowsAffected() - if err != nil { - return err - } - if n == 0 { - return ErrStaleTransition - } - return nil -} - -// TaskByIssue returns the task tracking an issue, or nil. -func (s *Store) TaskByIssue(ctx context.Context, owner, repo string, number int) (*workflow.Task, error) { - row := s.db.QueryRowContext(ctx, ` - SELECT id, owner, repo, issue_number, title, body, labels, status, - workflow, stage, branch, plan, notes, pr_number, tokens_used, - iterations, attempt, park_reason, watch_comment_id, retry_count, - source, identity, binding_id, binding_version, review_payload, - workflow_definition_version, workflow_definition_digest, workflow_definition_yaml, park_class, remediation_rounds, created_at, updated_at - FROM tasks WHERE owner=? AND repo=? AND issue_number=?`, owner, repo, number) - t, err := scanTask(row) - if errors.Is(err, sql.ErrNoRows) { - return nil, nil - } - return t, err -} - -// OpenTaskByPR returns the live task that owns the given pull request, or nil. -func (s *Store) OpenTaskByPR(ctx context.Context, owner, repo string, number int) (*workflow.Task, error) { - row := s.db.QueryRowContext(ctx, ` - SELECT id, owner, repo, issue_number, title, body, labels, status, - workflow, stage, branch, plan, notes, pr_number, tokens_used, - iterations, attempt, park_reason, watch_comment_id, retry_count, - source, identity, binding_id, binding_version, review_payload, - workflow_definition_version, workflow_definition_digest, workflow_definition_yaml, park_class, remediation_rounds, created_at, updated_at - FROM tasks - WHERE owner=? AND repo=? AND pr_number=? AND status=?`, - owner, repo, number, workflow.StatusPROpen) - t, err := scanTask(row) - if errors.Is(err, sql.ErrNoRows) { - return nil, nil - } - return t, err -} - -// TaskByID returns the task with the given database ID, or nil. Used by -// chat controls (/approve, /cancel) that reference a task by its real -// ID rather than a forge issue number. -func (s *Store) TaskByID(ctx context.Context, taskID int64) (*workflow.Task, error) { - row := s.db.QueryRowContext(ctx, ` - SELECT id, owner, repo, issue_number, title, body, labels, status, - workflow, stage, branch, plan, notes, pr_number, tokens_used, - iterations, attempt, park_reason, watch_comment_id, retry_count, - source, identity, binding_id, binding_version, review_payload, - workflow_definition_version, workflow_definition_digest, workflow_definition_yaml, park_class, remediation_rounds, created_at, updated_at - FROM tasks WHERE id=?`, taskID) - t, err := scanTask(row) - if errors.Is(err, sql.ErrNoRows) { - return nil, nil - } - return t, err -} - -// Requeue puts a task back on the queue. A non-empty workflow forces it -// (the waiting_human → approved → implement handoff); empty keeps the -// task's current workflow (retrying a parked task). -// The fromStatus acts as a guard: the UPDATE only affects rows whose -// current status matches fromStatus. If no row matches, ErrStaleTransition -// is returned and no audit row is written. Both statements execute in a -// single transaction. -func (s *Store) Requeue(ctx context.Context, taskID int64, fromStatus, wf string) error { - tx, err := s.db.BeginTx(ctx, nil) - if err != nil { - return err - } - defer func() { _ = tx.Rollback() }() - - res, err := tx.ExecContext(ctx, ` - UPDATE tasks SET status=?, - workflow=CASE WHEN ?='' THEN workflow ELSE ? END, - stage='', park_reason='', park_class='needs_human', updated_at=datetime('now') - WHERE id=? AND status=?`, workflow.StatusQueued, wf, wf, taskID, fromStatus) - if err != nil { - return err - } - n, err := res.RowsAffected() - if err != nil { - return err - } - if n == 0 { - return ErrStaleTransition - } - - _, err = tx.ExecContext(ctx, - `INSERT INTO transitions (task_id, from_status, to_status, detail) VALUES (?, ?, ?, ?)`, - taskID, fromStatus, workflow.StatusQueued, "requeued "+wf) - if err != nil { - return err - } - - return tx.Commit() -} - -// RetryTask requeues a task and increments retry_count in the same guarded -// transaction. A queued task with an uncounted retry would make max_retries a -// suggestion rather than a cap. -func (s *Store) RetryTask(ctx context.Context, taskID int64, fromStatus, wf string) error { - tx, err := s.db.BeginTx(ctx, nil) - if err != nil { - return err - } - defer func() { _ = tx.Rollback() }() - - res, err := tx.ExecContext(ctx, ` - UPDATE tasks SET status=?, retry_count=retry_count+1, - workflow=CASE WHEN ?='' THEN workflow ELSE ? END, - stage='', park_reason='', park_class='needs_human', updated_at=datetime('now') - WHERE id=? AND status=?`, workflow.StatusQueued, wf, wf, taskID, fromStatus) - if err != nil { - return err - } - n, err := res.RowsAffected() - if err != nil { - return err - } - if n == 0 { - return ErrStaleTransition - } - if _, err := tx.ExecContext(ctx, - `INSERT INTO transitions (task_id, from_status, to_status, detail) VALUES (?, ?, ?, ?)`, - taskID, fromStatus, workflow.StatusQueued, "retried "+wf); err != nil { - return err - } - return tx.Commit() -} - -// ArchiveTask removes one terminal task from the active task board. The -// expected status is part of the delete predicate so a stale browser cannot -// remove a task that has since resumed or otherwise changed state. Historical -// transition and activity rows remain as the operator audit trail. -func (s *Store) ArchiveTask( - ctx context.Context, - taskID int64, - fromStatus string, - audit events.Event, -) (int64, error) { - tx, err := s.db.BeginTx(ctx, nil) - if err != nil { - return 0, err - } - defer func() { _ = tx.Rollback() }() - - eventID, err := insertEvent(ctx, tx, audit) - if err != nil { - return 0, err - } - res, err := tx.ExecContext(ctx, `DELETE FROM tasks WHERE id=? AND status=?`, taskID, fromStatus) - if err != nil { - return 0, err - } - n, err := res.RowsAffected() - if err != nil { - return 0, err - } - if n == 0 { - return 0, ErrStaleTransition - } - if err := tx.Commit(); err != nil { - return 0, err - } - return eventID, nil -} - -// RecoverStale re-queues tasks left running by a crashed daemon. -func (s *Store) RecoverStale(ctx context.Context) (int64, error) { - res, err := s.db.ExecContext(ctx, - `UPDATE tasks SET status=?, updated_at=datetime('now') WHERE status=?`, - workflow.StatusQueued, workflow.StatusRunning) - if err != nil { - return 0, err - } - return res.RowsAffected() -} - -// OpenPRs returns tasks whose PR state should be reconciled with GitHub. -// -// It carries attempt deliberately: the reconcile loop attributes pr_merged and -// pr_rejected to the attempt that opened the PR, and it reaches the state store -// over the wire, so the row must carry the value for taskProto to publish it. -// Narrowing this projection back silently sends those events out unattributed. -func (s *Store) OpenPRs(ctx context.Context) (tasks []workflow.Task, retErr error) { - rows, err := s.db.QueryContext(ctx, ` - SELECT id, owner, repo, issue_number, pr_number, status, source, identity, attempt, - review_cursor, watch_comment_id - FROM tasks WHERE status=?`, workflow.StatusPROpen) - if err != nil { - return nil, err - } - defer func() { - retErr = errors.Join(retErr, rows.Close()) - }() - for rows.Next() { - var t workflow.Task - if err := rows.Scan(&t.ID, &t.Owner, &t.Repo, &t.IssueNumber, &t.PRNumber, - &t.Status, &t.Source, &t.Identity, &t.Attempt, - &t.ReviewCursor, &t.WatchCommentID); err != nil { - return nil, err - } - tasks = append(tasks, t) - } - return tasks, rows.Err() -} - -// ClearTerminalTasks deletes tasks whose status is terminal. Parked work is -// deliberately excluded because it is recoverable. -func (s *Store) ClearTerminalTasks(ctx context.Context) (int64, error) { - res, err := s.db.ExecContext(ctx, - `DELETE FROM tasks WHERE status IN (?, ?, ?, ?)`, - workflow.StatusMerged, workflow.StatusRejected, workflow.StatusDead, workflow.StatusClosedWontDo) - if err != nil { - return 0, err - } - return res.RowsAffected() -} - -func clip(s string, n int) string { - if len(s) <= n { - return s - } - // Walk forward by runes; stop when the next rune would exceed n bytes. - pos := 0 - for pos < len(s) { - _, size := utf8.DecodeRuneInString(s[pos:]) - if pos+size > n { - break - } - pos += size - } - return s[:pos] -} - -// sqliteTime scans SQLite's TEXT datetime columns into a time.Time. -// -// The tasks table stores timestamps as TEXT via datetime('now') rather than a -// typed column, so the driver hands back a string and the standard time.Time -// scan fails. Parsing here keeps the column definition untouched -- changing -// it would need a migration over existing rows for no behavioural gain. -type sqliteTime struct{ t *time.Time } - -// sqliteTimeLayout is what datetime('now') produces: UTC, no zone suffix. -const sqliteTimeLayout = "2006-01-02 15:04:05" - -func (s sqliteTime) Scan(v any) error { - switch value := v.(type) { - case nil: - return nil - case time.Time: - *s.t = value.UTC() - return nil - case []byte: - return s.parse(string(value)) - case string: - return s.parse(value) - default: - return fmt.Errorf("store: cannot scan %T into time", v) - } -} - -func (s sqliteTime) parse(v string) error { - if v == "" { - return nil - } - // RFC3339 first: rows written by other paths may carry a zone. - for _, layout := range []string{time.RFC3339Nano, time.RFC3339, sqliteTimeLayout} { - if parsed, err := time.Parse(layout, v); err == nil { - *s.t = parsed.UTC() - return nil - } - } - return fmt.Errorf("store: unrecognised time %q", v) -} diff --git a/internal/store/store_test.go b/internal/store/store_test.go deleted file mode 100644 index d135e820d..000000000 --- a/internal/store/store_test.go +++ /dev/null @@ -1,1167 +0,0 @@ -package store - -import ( - "context" - "database/sql" - "errors" - "fmt" - "path/filepath" - "strings" - "sync" - "testing" - "time" - "unicode/utf8" - - "github.com/samcharles93/archie-core/internal/domain/storecontract" - "github.com/samcharles93/archie-core/internal/domain/workflow" - "github.com/samcharles93/archie-core/internal/events" -) - -func TestOpenLimitsSQLiteToOneConnection(t *testing.T) { - s := openTest(t) - if got := s.db.Stats().MaxOpenConnections; got != 1 { - t.Fatalf("MaxOpenConnections = %d, want 1", got) - } -} - -func TestOpenAppliesPragmasWithTrailingQueryDelimiter(t *testing.T) { - s, err := Open(t.Context(), filepath.Join(t.TempDir(), "tasks.db")+"?") - if err != nil { - t.Fatal(err) - } - t.Cleanup(func() { _ = s.Close() }) - var mode string - if err := s.db.QueryRowContext(t.Context(), `PRAGMA journal_mode`).Scan(&mode); err != nil { - t.Fatal(err) - } - if mode != "wal" { - t.Fatalf("journal_mode = %q, want wal", mode) - } -} - -func TestOpenHonorsCancelledContext(t *testing.T) { - ctx, cancel := context.WithCancel(context.Background()) - cancel() - s, err := Open(ctx, filepath.Join(t.TempDir(), "tasks.db")) - if s != nil || !errors.Is(err, context.Canceled) { - t.Fatalf("Open = (%+v, %v), want (nil, context.Canceled)", s, err) - } -} - -func TestOpenMigratesUnversionedTaskSchemas(t *testing.T) { - tests := []struct { - name string - columns string - }{ - {name: "legacy", columns: "id INTEGER PRIMARY KEY"}, - {name: "partially migrated", columns: "id INTEGER PRIMARY KEY, watch_comment_id INTEGER NOT NULL DEFAULT 0, source TEXT NOT NULL DEFAULT 'forge'"}, - {name: "fully migrated", columns: "id INTEGER PRIMARY KEY, watch_comment_id INTEGER NOT NULL DEFAULT 0, retry_count INTEGER NOT NULL DEFAULT 0, source TEXT NOT NULL DEFAULT 'forge', identity TEXT NOT NULL DEFAULT ''"}, - } - for _, tt := range tests { - t.Run(tt.name, func(t *testing.T) { - path := filepath.Join(t.TempDir(), "tasks.db") - db, err := sql.Open("sqlite", path) - if err != nil { - t.Fatal(err) - } - if _, err := db.ExecContext(t.Context(), `CREATE TABLE tasks (`+tt.columns+`)`); err != nil { - t.Fatal(err) - } - if err := db.Close(); err != nil { - t.Fatal(err) - } - - s, err := Open(t.Context(), path) - if err != nil { - t.Fatal(err) - } - defer func() { _ = s.Close() }() - var version int - if err := s.db.QueryRowContext(t.Context(), `PRAGMA user_version`).Scan(&version); err != nil { - t.Fatal(err) - } - if version != taskSchemaVersion { - t.Fatalf("user_version = %d, want %d", version, taskSchemaVersion) - } - rows, err := s.db.QueryContext(t.Context(), `PRAGMA table_info(tasks)`) - if err != nil { - t.Fatal(err) - } - defer func() { - if err := rows.Close(); err != nil { - t.Errorf("close table_info rows: %v", err) - } - }() - got := map[string]bool{} - for rows.Next() { - var cid, notNull, primaryKey int - var name, columnType string - var defaultValue any - if err := rows.Scan(&cid, &name, &columnType, ¬Null, &defaultValue, &primaryKey); err != nil { - t.Fatal(err) - } - got[name] = true - } - if err := rows.Err(); err != nil { - t.Fatal(err) - } - for _, name := range []string{"watch_comment_id", "retry_count", "source", "identity", "review_cursor"} { - if !got[name] { - t.Errorf("column %q was not migrated", name) - } - } - }) - } -} - -// TestOpenMigratesLegacyEventsAttemptColumn covers the highest-risk step in -// attempt provenance: adding events.attempt to a database that predates it. -// eventsSchema is CREATE TABLE IF NOT EXISTS, so against an existing -// archie.db that statement is a no-op and the migrator arm is the ONLY thing -// that adds the column. A test that opens a fresh tempdir passes whether or -// not the arm exists, so the failure this pins is the one production would -// hit: `table events has no column named attempt`. -func TestOpenMigratesLegacyEventsAttemptColumn(t *testing.T) { - path := filepath.Join(t.TempDir(), "legacy.db") - raw, err := sql.Open("sqlite", path) - if err != nil { - t.Fatal(err) - } - _, err = raw.ExecContext(t.Context(), ` - CREATE TABLE events ( - id INTEGER PRIMARY KEY AUTOINCREMENT, - at TEXT NOT NULL, - kind TEXT NOT NULL, - task_id INTEGER NOT NULL DEFAULT 0, - repo TEXT NOT NULL DEFAULT '', - issue INTEGER NOT NULL DEFAULT 0, - workflow TEXT NOT NULL DEFAULT '', - stage TEXT NOT NULL DEFAULT '', - detail TEXT NOT NULL DEFAULT '', - data TEXT NOT NULL DEFAULT '{}' - ); - INSERT INTO events (at, kind, task_id, stage, detail) - VALUES ('2026-01-01T00:00:00Z', 'stage_start', 7, 'prepare', 'pre-existing row'); - PRAGMA user_version = 3`) - if err != nil { - t.Fatal(err) - } - if err := raw.Close(); err != nil { - t.Fatal(err) - } - - s, err := Open(t.Context(), path) - if err != nil { - t.Fatal(err) - } - t.Cleanup(func() { _ = s.Close() }) - - // The row written before the column existed survives and reads as - // unattributed -- zero is not a first attempt. - legacy, err := s.TaskEvents(t.Context(), 7) - if err != nil { - t.Fatalf("TaskEvents after legacy migration: %v", err) - } - if len(legacy) != 1 || legacy[0].Detail != "pre-existing row" { - t.Fatalf("legacy events = %+v, want the preserved row", legacy) - } - if legacy[0].Attempt != 0 { - t.Errorf("legacy event attempt = %d, want 0 (unattributed)", legacy[0].Attempt) - } - - // Writing the new column is what actually fails in production when the - // migrator arm is missing. - if _, err := s.InsertEvent(t.Context(), events.Event{ - Kind: "stage_finish", TaskID: 7, Stage: "prepare", Attempt: 2, - Data: map[string]any{"duration_ms": 1200}, - }); err != nil { - t.Fatalf("InsertEvent with attempt after legacy migration: %v", err) - } - - timeline, err := s.TaskEvents(t.Context(), 7) - if err != nil { - t.Fatalf("TaskEvents after insert: %v", err) - } - if len(timeline) != 2 { - t.Fatalf("TaskEvents = %d events, want 2", len(timeline)) - } - if got := timeline[1].Attempt; got != 2 { - t.Errorf("attempt round-trip after legacy migration = %d, want 2", got) - } - if got := timeline[0].Attempt; got != 0 { - t.Errorf("legacy row attempt changed to %d, want 0", got) - } -} - -// TestOpenMigratesResourceHistoryToPerKindRequestIDs covers the v4 step: the -// history table's global request_id UNIQUE becomes per-kind uniqueness. A -// global constraint is strictly stricter than the per-kind one, so no legacy -// row can fail the rebuild -- but the legacy table must not leave a request -// ID another kind already used refusing the write (archie-core-fcvd). -func TestOpenMigratesResourceHistoryToPerKindRequestIDs(t *testing.T) { - path := filepath.Join(t.TempDir(), "legacy.db") - raw, err := sql.Open("sqlite", path) - if err != nil { - t.Fatal(err) - } - _, err = raw.ExecContext(t.Context(), ` - CREATE TABLE resources ( - kind TEXT PRIMARY KEY, value BLOB NOT NULL, version INTEGER NOT NULL, updated_at TEXT NOT NULL - ); - CREATE TABLE resource_history ( - id INTEGER PRIMARY KEY AUTOINCREMENT, kind TEXT NOT NULL, value BLOB NOT NULL, - version INTEGER NOT NULL, actor TEXT NOT NULL, source TEXT NOT NULL, - request_id TEXT NOT NULL UNIQUE, expected_version INTEGER NOT NULL, - current_version INTEGER NOT NULL, at TEXT NOT NULL - ); - INSERT INTO resources (kind,value,version,updated_at) - VALUES ('settings','{"v":1}',1,'2026-01-01T00:00:00Z'); - INSERT INTO resource_history (kind,value,version,actor,source,request_id,expected_version,current_version,at) - VALUES ('settings','{"v":1}',1,'a','test','shared',0,0,'2026-01-01T00:00:00Z'); - PRAGMA user_version = 3`) - if err != nil { - t.Fatal(err) - } - if err := raw.Close(); err != nil { - t.Fatal(err) - } - - s, err := Open(t.Context(), path) - if err != nil { - t.Fatalf("Open: %v", err) - } - t.Cleanup(func() { _ = s.Close() }) - - // The row written before the migration survives. - resource, err := s.Resource(t.Context(), "settings") - if err != nil { - t.Fatalf("Resource after migration: %v", err) - } - if string(resource.Value) != `{"v":1}` { - t.Fatalf("legacy history row = %s, want the preserved value", resource.Value) - } - - // The column constraint is gone -- no auto-index (an index sqlite_master - // carries with a NULL sql) is left on the table -- and per-kind - // uniqueness is its replacement. - var autoIndexes int - if err := s.db.QueryRowContext(t.Context(), `SELECT count(*) FROM sqlite_master WHERE type='index' AND tbl_name='resource_history' AND sql IS NULL`).Scan(&autoIndexes); err != nil { - t.Fatal(err) - } - if autoIndexes != 0 { - t.Fatalf("resource_history still carries %d column-constraint index(es), want none", autoIndexes) - } - var perKind int - if err := s.db.QueryRowContext(t.Context(), `SELECT count(*) FROM sqlite_master WHERE type='index' AND name='idx_resource_history_kind_request'`).Scan(&perKind); err != nil { - t.Fatal(err) - } - if perKind != 1 { - t.Fatalf("idx_resource_history_kind_request exists %d times, want 1", perKind) - } - - // The dedup key itself: a request ID another kind already used writes the - // new kind instead of failing the global constraint or replaying the old - // resource. - second, err := s.PutResource(t.Context(), ResourceWrite{Kind: "other", Value: []byte(`{"v":9}`), Actor: "a", Source: "test", RequestID: "shared", ExpectedVersion: 0, At: time.Now()}) - if err != nil { - t.Fatalf("PutResource with a request ID another kind already used: %v", err) - } - if second.Kind != "other" || second.Version != 1 { - t.Fatalf("second write = (%s, v%d), want the %q write itself", second.Kind, second.Version, "other") - } -} - -func TestOpenRejectsNewerSchemaVersion(t *testing.T) { - path := filepath.Join(t.TempDir(), "tasks.db") - db, err := sql.Open("sqlite", path) - if err != nil { - t.Fatal(err) - } - if _, err := db.ExecContext(t.Context(), fmt.Sprintf(`PRAGMA user_version = %d`, taskSchemaVersion+1)); err != nil { - t.Fatal(err) - } - if err := db.Close(); err != nil { - t.Fatal(err) - } - s, err := Open(t.Context(), path) - if s != nil || err == nil || !strings.Contains(err.Error(), "newer than supported") { - t.Fatalf("Open = (%+v, %v), want newer-schema error", s, err) - } -} - -func TestPersistenceAcrossRestart(t *testing.T) { - path := filepath.Join(t.TempDir(), "tasks.db") - ctx := t.Context() - s, err := Open(ctx, path) - if err != nil { - t.Fatal(err) - } - if _, err := s.EnqueueIssue(ctx, "acme", "todo", 1, "survive restart", "", "", ""); err != nil { - t.Fatal(err) - } - if err := s.Close(); err != nil { - t.Fatal(err) - } - - s, err = Open(ctx, path) - if err != nil { - t.Fatal(err) - } - t.Cleanup(func() { _ = s.Close() }) - task, err := s.TaskByIssue(ctx, "acme", "todo", 1) - if err != nil || task == nil { - t.Fatalf("TaskByIssue after reopen = (%+v, %v)", task, err) - } - if task.Title != "survive restart" { - t.Fatalf("Title = %q, want survive restart", task.Title) - } -} - -func TestConcurrentEnqueueAndClaim(t *testing.T) { - s := openTest(t) - ctx := t.Context() - const count = 20 - var wg sync.WaitGroup - for number := range count { - wg.Go(func() { - if _, err := s.EnqueueIssue(ctx, "acme", "repo", number, "title", "", "", ""); err != nil { - t.Errorf("EnqueueIssue(%d): %v", number, err) - } - }) - } - wg.Wait() - - claimed := make(map[int64]struct{}, count) - var mu sync.Mutex - for range count { - wg.Go(func() { - task, err := s.ClaimNext(ctx) - if err != nil { - t.Errorf("ClaimNext: %v", err) - return - } - if task == nil { - t.Error("ClaimNext returned nil task") - return - } - mu.Lock() - claimed[task.ID] = struct{}{} - mu.Unlock() - }) - } - wg.Wait() - if len(claimed) != count { - t.Fatalf("claimed %d unique tasks, want %d", len(claimed), count) - } -} - -func TestChatIssueNumbersAreDurableAcrossStoreInstances(t *testing.T) { - path := filepath.Join(t.TempDir(), "tasks.db") - stores := make([]*Store, 2) - for i := range stores { - var err error - stores[i], err = Open(t.Context(), path) - if err != nil { - t.Fatal(err) - } - defer func(s *Store) { _ = s.Close() }(stores[i]) - } - - const count = 20 - numbers := make(map[int]struct{}, count) - var mu sync.Mutex - var wg sync.WaitGroup - for i := range count { - wg.Go(func() { - task, err := stores[i%len(stores)].EnqueueChatTask( - t.Context(), "acme", "widget", "chat task", "", "", "archie", - ) - if err != nil { - t.Errorf("EnqueueChatTask: %v", err) - return - } - mu.Lock() - numbers[task.IssueNumber] = struct{}{} - mu.Unlock() - }) - } - wg.Wait() - if len(numbers) != count { - t.Fatalf("allocated %d unique issue numbers, want %d", len(numbers), count) - } - for number := range numbers { - if number < 1_000_000_000_000_000 || number > 1<<53-1 { - t.Errorf("synthetic issue number %d is outside the reserved JSON-safe range", number) - } - } -} - -func TestTasksIncludesIdentity(t *testing.T) { - s := openTest(t) - want, err := s.EnqueueChatTask(t.Context(), "acme", "widget", "chat task", "", "", "reviewer") - if err != nil { - t.Fatal(err) - } - got, err := s.Tasks(t.Context(), 1) - if err != nil { - t.Fatal(err) - } - if len(got) != 1 || got[0].ID != want.ID || got[0].Identity != "reviewer" { - t.Fatalf("Tasks = %+v, want task %d with identity reviewer", got, want.ID) - } -} - -func TestStoreOperationsHonorContextCancellation(t *testing.T) { - s := openTest(t) - ctx, cancel := context.WithCancel(context.Background()) - cancel() - if task, err := s.ClaimNext(ctx); task != nil || !errors.Is(err, context.Canceled) { - t.Fatalf("ClaimNext = (%+v, %v), want (nil, context.Canceled)", task, err) - } - if task, err := s.TaskByIssue(ctx, "acme", "repo", 1); task != nil || !errors.Is(err, context.Canceled) { - t.Fatalf("TaskByIssue = (%+v, %v), want (nil, context.Canceled)", task, err) - } -} - -func TestOversizedEventPayload(t *testing.T) { - s := openTest(t) - detail := strings.Repeat("x", 5000) - if _, err := s.InsertEvent(t.Context(), events.Event{Kind: events.KindLog, Detail: detail}); err != nil { - t.Fatal(err) - } - got, err := s.EventsSince(t.Context(), "", 1) - if err != nil { - t.Fatal(err) - } - if len(got) != 1 || got[0].Detail != detail[:4000] { - t.Fatalf("stored detail length = %d, want 4000", len(got[0].Detail)) - } -} - -func TestInsertEventWithUnmarshalableData(t *testing.T) { - s := openTest(t) - if _, err := s.InsertEvent(t.Context(), events.Event{ - Kind: events.KindLog, - Data: map[string]any{"channel": make(chan int)}, - }); err != nil { - t.Fatal(err) - } - got, err := s.EventsSince(t.Context(), "", 1) - if err != nil { - t.Fatal(err) - } - if len(got) != 1 { - t.Fatalf("events = %d, want 1", len(got)) - } - if message, ok := got[0].Data["marshal_error"].(string); !ok || message == "" { - t.Fatalf("marshal_error = %#v, want non-empty string", got[0].Data["marshal_error"]) - } -} - -func openTest(t *testing.T) *Store { - t.Helper() - s, err := Open(t.Context(), filepath.Join(t.TempDir(), "test.db")) - if err != nil { - t.Fatal(err) - } - t.Cleanup(func() { - if err := s.Close(); err != nil { - t.Errorf("close store: %v", err) - } - }) - return s -} - -// TestEventsSinceOrdersByAt pins the total-order invariant: the feed cursor -// must page by at, not by row id. Inserting a later-timestamped event before -// an earlier one must still return the earlier one first, because row id is -// insertion order, not chronology. -func TestEventsSinceOrdersByAt(t *testing.T) { - s := openTest(t) - ctx := t.Context() - later := time.Date(2026, 1, 1, 0, 0, 1, 0, time.UTC) - earlier := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC) - if _, err := s.InsertEvent(ctx, events.Event{Kind: "log", At: later, Detail: "later"}); err != nil { - t.Fatal(err) - } - if _, err := s.InsertEvent(ctx, events.Event{Kind: "log", At: earlier, Detail: "earlier"}); err != nil { - t.Fatal(err) - } - - got, err := s.EventsSince(ctx, "", 10) - if err != nil { - t.Fatal(err) - } - if len(got) != 2 { - t.Fatalf("EventsSince returned %d events, want 2", len(got)) - } - if got[0].Detail != "earlier" || got[1].Detail != "later" { - t.Fatalf("order = %q then %q; want earlier then later (at order, not insertion order)", got[0].Detail, got[1].Detail) - } -} - -// TestInsertEventWritesFixedWidthTimeKey pins the write format the total -// order depends on: a whole-second timestamp and a full-precision one must -// render to the same length, or lexicographic order stops being chronological -// order. time.RFC3339Nano trims trailing zeros, so today this fails. -func TestInsertEventWritesFixedWidthTimeKey(t *testing.T) { - s := openTest(t) - ctx := t.Context() - whole := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC) - precise := time.Date(2026, 1, 1, 0, 0, 0, 123456789, time.UTC) - for _, e := range []events.Event{ - {Kind: "log", At: whole, Detail: "whole"}, - {Kind: "log", At: precise, Detail: "precise"}, - } { - if _, err := s.InsertEvent(ctx, e); err != nil { - t.Fatal(err) - } - } - - rows, err := s.db.QueryContext(ctx, `SELECT at FROM events ORDER BY id`) - if err != nil { - t.Fatal(err) - } - defer func() { _ = rows.Close() }() - var ats []string - for rows.Next() { - var at string - if err := rows.Scan(&at); err != nil { - t.Fatal(err) - } - ats = append(ats, at) - } - if err := rows.Err(); err != nil { - t.Fatal(err) - } - if len(ats) != 2 { - t.Fatalf("stored %d event rows, want 2", len(ats)) - } - if len(ats[0]) != len(ats[1]) { - t.Fatalf("at renders %d and %d chars (%q vs %q); want a fixed-width key", len(ats[0]), len(ats[1]), ats[0], ats[1]) - } -} - -// TestEventsSincePagesIdenticalTimestampsWithoutSkipOrRepeat is the -// regression guard for the id tie-break: many events sharing one timestamp -// must still page exactly once each, in a stable order, no matter what their -// ids are. It walks the returned cursor to exhaustion with a page size smaller -// than the set, so every page boundary is exercised. -func TestEventsSincePagesIdenticalTimestampsWithoutSkipOrRepeat(t *testing.T) { - s := openTest(t) - ctx := t.Context() - at := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC) - const total = 50 - inserted := make(map[int64]string, total) - for i := range total { - detail := fmt.Sprintf("event-%d", i) - id, err := s.InsertEvent(ctx, events.Event{Kind: "log", At: at, Detail: detail}) - if err != nil { - t.Fatal(err) - } - inserted[id] = detail - } - - var got []events.Event - cursor := "" - for { - page, err := s.EventsSince(ctx, cursor, 7) - if err != nil { - t.Fatal(err) - } - if len(page) == 0 { - break - } - got = append(got, page...) - last := page[len(page)-1] - cursor = storecontract.EventCursor(last.At, last.ID) - } - - if len(got) != total { - t.Fatalf("paged %d events, want %d (a skip or a repeat)", len(got), total) - } - seen := make(map[int64]bool, total) - for i, e := range got { - if _, ok := inserted[e.ID]; !ok { - t.Fatalf("event %d (%d) was never inserted", i, e.ID) - } - if seen[e.ID] { - t.Fatalf("event %d (%d) delivered twice", i, e.ID) - } - seen[e.ID] = true - if i > 0 { - prev := got[i-1] - if storecontract.EventCursor(prev.At, prev.ID) >= storecontract.EventCursor(e.At, e.ID) { - t.Fatalf("order regressed at %d: %q then %q", i, - storecontract.EventCursor(prev.At, prev.ID), storecontract.EventCursor(e.At, e.ID)) - } - } - } -} - -// TestTasksBindingColumnsRoundTrip confirms the binding_id and -// binding_version columns added in store schema 2 survive an INSERT and a -// full SELECT round-trip through the Task read paths (scanTask, -// TaskByIssue, TaskByID, Tasks). -func TestTasksBindingColumnsRoundTrip(t *testing.T) { - s := openTest(t) - ctx := t.Context() - task, err := s.EnqueueChatTask(ctx, "acme", "widget", "binding task", "body", "implement", "") - if err != nil { - t.Fatalf("EnqueueChatTask: %v", err) - } - if _, err := s.db.ExecContext(ctx, - `UPDATE tasks SET binding_id=?, binding_version=? WHERE id=?`, - "rbind0000000001", 3, task.ID); err != nil { - t.Fatalf("UPDATE binding provenance: %v", err) - } - - for name, read := range map[string]func() (*workflow.Task, error){ - "scanTask-via-TaskByIssue": func() (*workflow.Task, error) { return s.TaskByIssue(ctx, "acme", "widget", task.IssueNumber) }, - "TaskByID": func() (*workflow.Task, error) { return s.TaskByID(ctx, task.ID) }, - } { - got, err := read() - if err != nil { - t.Fatalf("%s: %v", name, err) - } - if got == nil { - t.Fatalf("%s: nil task", name) - } - if got.BindingID != "rbind0000000001" || got.BindingVersion != 3 { - t.Fatalf("%s: BindingID=%q BindingVersion=%d, want rbind0000000001/3", - name, got.BindingID, got.BindingVersion) - } - } - - listed, err := s.Tasks(ctx, 10) - if err != nil { - t.Fatalf("Tasks: %v", err) - } - if len(listed) == 0 || listed[0].BindingID != "rbind0000000001" || listed[0].BindingVersion != 3 { - t.Fatalf("Tasks() round-trip: %+v", listed) - } -} - -func TestClip(t *testing.T) { - tests := []struct { - name string - input string - n int - want string - }{ - {"ascii truncate", "hello", 3, "hel"}, - {"ascii below n", "hello", 10, "hello"}, - {"empty zero", "", 0, ""}, - {"empty positive", "", 5, ""}, - {"2-byte fits exactly", "café", 5, "café"}, - {"2-byte cut off", "café", 4, "caf"}, - {"clean ASCII boundary", "café", 3, "caf"}, - {"4-byte emoji fits", "🍕pizza", 4, "🍕"}, - {"4-byte emoji cut off", "🍕pizza", 3, ""}, - {"2-byte ñ fits", "niño", 5, "niño"}, - {"2-byte ñ cut off", "niño", 4, "niñ"}, - {"3-byte CJK fits", "日本語", 6, "日本"}, - {"3-byte CJK cut off", "日本語", 5, "日"}, - {"mixed multi-byte", "a🍕b", 5, "a🍕"}, - {"mixed multi-byte cut off", "a🍕b", 4, "a"}, - } - - for _, tt := range tests { - t.Run(tt.name, func(t *testing.T) { - got := clip(tt.input, tt.n) - if got != tt.want { - t.Errorf("clip(%q, %d) = %q, want %q", tt.input, tt.n, got, tt.want) - } - // Verify output is valid UTF-8. - if !utf8.ValidString(got) { - t.Errorf("clip(%q, %d) produced invalid UTF-8: %q", tt.input, tt.n, got) - } - }) - } -} - -func TestClearTerminalTasks(t *testing.T) { - s := openTest(t) - ctx := context.Background() - - statuses := []string{workflow.StatusMerged, workflow.StatusParked, workflow.StatusRejected, workflow.StatusClosedWontDo, workflow.StatusQueued} - for i, status := range statuses { - if _, err := s.EnqueueIssue(ctx, "acme", "widget", i+1, "t", "b", "", ""); err != nil { - t.Fatal(err) - } - task, err := s.TaskByIssue(ctx, "acme", "widget", i+1) - if err != nil || task == nil { - t.Fatalf("TaskByIssue(%d) = (%+v, %v)", i+1, task, err) - } - if status != workflow.StatusQueued { - if err := s.Transition(ctx, task.ID, workflow.StatusQueued, status, ""); err != nil { - t.Fatal(err) - } - } - } - - n, err := s.ClearTerminalTasks(ctx) - if err != nil || n != 3 { - t.Fatalf("ClearTerminalTasks = (%d, %v), want (3, nil)", n, err) - } - - counts, err := s.StatusCounts(ctx) - if err != nil { - t.Fatal(err) - } - if counts[workflow.StatusQueued] != 1 { - t.Fatalf("expected 1 queued, got %d", counts[workflow.StatusQueued]) - } - if counts[workflow.StatusParked] != 1 { - t.Fatalf("recoverable parked task was cleared: count = %d", counts[workflow.StatusParked]) - } - for _, status := range []string{workflow.StatusMerged, workflow.StatusRejected, workflow.StatusClosedWontDo} { - if counts[status] != 0 { - t.Fatalf("expected 0 for %s, got %d", status, counts[status]) - } - } - - // Idempotent: second call removes nothing. - n, err = s.ClearTerminalTasks(ctx) - if err != nil || n != 0 { - t.Fatalf("second ClearTerminalTasks = (%d, %v), want (0, nil)", n, err) - } -} - -func TestArchiveTaskIsGuardedAndScoped(t *testing.T) { - s := openTest(t) - ctx := context.Background() - for number := 1; number <= 2; number++ { - if _, err := s.EnqueueIssue(ctx, "acme", "widget", number, "t", "b", "", ""); err != nil { - t.Fatal(err) - } - } - task, err := s.TaskByIssue(ctx, "acme", "widget", 1) - if err != nil || task == nil { - t.Fatalf("TaskByIssue = (%+v, %v)", task, err) - } - if err := s.Transition(ctx, task.ID, workflow.StatusQueued, workflow.StatusMerged, "done"); err != nil { - t.Fatal(err) - } - - audit := events.Event{Kind: events.KindTaskArchiveRequested, TaskID: task.ID} - if _, err := s.ArchiveTask(ctx, task.ID, workflow.StatusQueued, audit); !errors.Is(err, ErrStaleTransition) { - t.Fatalf("ArchiveTask stale guard = %v, want ErrStaleTransition", err) - } - if got, err := s.TaskByID(ctx, task.ID); err != nil || got == nil { - t.Fatalf("stale archive removed task: (%+v, %v)", got, err) - } - eventID, err := s.ArchiveTask(ctx, task.ID, workflow.StatusMerged, audit) - if err != nil { - t.Fatalf("ArchiveTask = %v", err) - } - if eventID == 0 { - t.Fatal("ArchiveTask returned no durable event ID") - } - if got, err := s.TaskByID(ctx, task.ID); err != nil || got != nil { - t.Fatalf("archived task = (%+v, %v), want nil", got, err) - } - if other, err := s.TaskByIssue(ctx, "acme", "widget", 2); err != nil || other == nil { - t.Fatalf("archive removed another task: (%+v, %v)", other, err) - } -} - -func TestArchiveAuditFailurePreservesTask(t *testing.T) { - s := openTest(t) - ctx := t.Context() - if _, err := s.EnqueueIssue(ctx, "acme", "widget", 1, "t", "", "", ""); err != nil { - t.Fatal(err) - } - task, _ := s.TaskByIssue(ctx, "acme", "widget", 1) - if err := s.Transition(ctx, task.ID, workflow.StatusQueued, workflow.StatusMerged, "done"); err != nil { - t.Fatal(err) - } - if _, err := s.db.ExecContext(ctx, ` - CREATE TRIGGER fail_archive_audit BEFORE INSERT ON events - WHEN NEW.kind = 'task_archive_requested' - BEGIN SELECT RAISE(FAIL, 'audit failed'); END`); err != nil { - t.Fatal(err) - } - - if _, err := s.ArchiveTask(ctx, task.ID, workflow.StatusMerged, events.Event{ - Kind: events.KindTaskArchiveRequested, TaskID: task.ID, - }); err == nil { - t.Fatal("ArchiveTask succeeded despite forced audit failure") - } - if got, err := s.TaskByID(ctx, task.ID); err != nil || got == nil { - t.Fatalf("audit failure deleted task: (%+v, %v)", got, err) - } -} - -func TestEnqueueIsIdempotent(t *testing.T) { - s := openTest(t) - ctx := context.Background() - - ins, err := s.EnqueueIssue(ctx, "acme", "todo", 1, "add tests", "body", "widget", "") - if err != nil || !ins { - t.Fatalf("first enqueue = (%v, %v)", ins, err) - } - ins, err = s.EnqueueIssue(ctx, "acme", "todo", 1, "add tests", "body", "widget", "") - if err != nil || ins { - t.Fatalf("duplicate enqueue must be a no-op, got (%v, %v)", ins, err) - } -} - -func TestEventLogRoundTrip(t *testing.T) { - s := openTest(t) - ctx := context.Background() - at := time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC) - - id1, err := s.InsertEvent(ctx, events.Event{Kind: "stage_start", TaskID: 1, Stage: "plan", Attempt: 1, At: at}) - if err != nil || id1 == 0 { - t.Fatalf("insert = (%d, %v)", id1, err) - } - id2, err := s.InsertEvent(ctx, events.Event{ - Kind: "stage_finish", TaskID: 1, Workflow: "implement", Stage: "plan", Attempt: 2, At: at, - Data: map[string]any{"duration_ms": 1200}, - }) - if err != nil || id2 <= id1 { - t.Fatalf("second insert = (%d, %v)", id2, err) - } - - // Two events sharing a timestamp must still page exactly once each via the - // id tie-break: the cursor carries (at, id), so resuming after id1 yields - // only id2. - evs, err := s.EventsSince(ctx, storecontract.EventCursor(at, id1), 10) - if err != nil || len(evs) != 1 || evs[0].Kind != "stage_finish" { - t.Fatalf("EventsSince = (%+v, %v)", evs, err) - } - if evs[0].Data["duration_ms"] != float64(1200) { - t.Fatalf("data round-trip = %v", evs[0].Data) - } - if evs[0].Attempt != 2 { - t.Fatalf("EventsSince attempt round-trip = %d, want 2", evs[0].Attempt) - } - - timeline, err := s.TaskEvents(ctx, 1) - if err != nil || len(timeline) != 2 { - t.Fatalf("TaskEvents = (%d, %v)", len(timeline), err) - } - // Two attempts of one task must stay distinguishable in its timeline. - if timeline[0].Attempt != 1 || timeline[1].Attempt != 2 { - t.Fatalf("TaskEvents attempts = (%d, %d), want (1, 2)", timeline[0].Attempt, timeline[1].Attempt) - } - - stats, err := s.StageStats(ctx) - if err != nil || len(stats) != 1 || stats[0].AvgMs != 1200 || stats[0].Stage != "plan" { - t.Fatalf("StageStats = (%+v, %v)", stats, err) - } -} - -// TestTransitionRejectsStaleFrom proves that Transition rejects a call -// whose `from` parameter does not match the task's current status. -// Today Transition ignores the `from` guard, so the call succeeds when -// it should fail — this test captures that bug. -func TestTransitionRejectsStaleFrom(t *testing.T) { - s := openTest(t) - ctx := context.Background() - - if _, err := s.EnqueueIssue(ctx, "acme", "widget", 1, "t", "b", "", ""); err != nil { - t.Fatal(err) - } - task, err := s.ClaimNext(ctx) - if err != nil || task == nil { - t.Fatalf("claim = (%v, %v)", task, err) - } - // Task is now workflow.StatusRunning. Transition with from=workflow.StatusQueued - // must fail because the task is not queued. - err = s.Transition(ctx, task.ID, workflow.StatusQueued, workflow.StatusPROpen, "stale from") - if err == nil { - t.Fatal("Transition with stale 'from' (workflow.StatusQueued) on a running task must return an error, but got nil") - } - - // Verify the task was NOT changed. - got, err := s.TaskByID(ctx, task.ID) - if err != nil || got == nil { - t.Fatalf("TaskByID = (%+v, %v)", got, err) - } - if got.Status != workflow.StatusRunning { - t.Fatalf("task status changed to %q despite stale from guard; want %q", got.Status, workflow.StatusRunning) - } -} - -// TestTransitionPreventsDoubleTransition proves that two callers racing -// to transition the same task from the same `from` status cannot both -// succeed — the second must get an error because the first already -// changed the status. -func TestTransitionPreventsDoubleTransition(t *testing.T) { - s := openTest(t) - ctx := context.Background() - - if _, err := s.EnqueueIssue(ctx, "acme", "widget", 1, "t", "b", "", ""); err != nil { - t.Fatal(err) - } - task, err := s.ClaimNext(ctx) - if err != nil || task == nil { - t.Fatalf("claim = (%v, %v)", task, err) - } - - // First transition: running → pr_open should succeed. - if err := s.Transition(ctx, task.ID, workflow.StatusRunning, workflow.StatusPROpen, "first"); err != nil { - t.Fatalf("first transition = %v", err) - } - - // Second transition: the task is now workflow.StatusPROpen, so - // from=workflow.StatusRunning must fail. - err = s.Transition(ctx, task.ID, workflow.StatusRunning, workflow.StatusMerged, "second") - if err == nil { - t.Fatal("second Transition with stale 'from' (workflow.StatusRunning) on a pr_open task must return an error, but got nil") - } - - // Verify the task kept the first transition's status. - got, err := s.TaskByID(ctx, task.ID) - if err != nil || got == nil { - t.Fatalf("TaskByID = (%+v, %v)", got, err) - } - if got.Status != workflow.StatusPROpen { - t.Fatalf("task status = %q, want %q (second transition must not overwrite)", got.Status, workflow.StatusPROpen) - } -} - -func TestTransitionToParkedPersistsReasonOnTask(t *testing.T) { - s := openTest(t) - ctx := t.Context() - - if _, err := s.EnqueueIssue(ctx, "acme", "widget", 1, "task", "", "", ""); err != nil { - t.Fatal(err) - } - task, err := s.ClaimNext(ctx) - if err != nil || task == nil { - t.Fatalf("ClaimNext = (%+v, %v)", task, err) - } - const reason = "managed worker unavailable" - if err := s.Transition(ctx, task.ID, workflow.StatusRunning, workflow.StatusParked, reason); err != nil { - t.Fatal(err) - } - - got, err := s.TaskByID(ctx, task.ID) - if err != nil { - t.Fatal(err) - } - if got.ParkReason != reason { - t.Errorf("ParkReason = %q, want %q", got.ParkReason, reason) - } -} - -// TestRequeueRejectsStaleFrom proves that Requeue rejects a call whose -// fromStatus does not match the task's current status. -func TestRequeueRejectsStaleFrom(t *testing.T) { - s := openTest(t) - ctx := context.Background() - - if _, err := s.EnqueueIssue(ctx, "acme", "widget", 1, "t", "b", "", ""); err != nil { - t.Fatal(err) - } - task, err := s.ClaimNext(ctx) - if err != nil || task == nil { - t.Fatalf("claim = (%v, %v)", task, err) - } - // Task is workflow.StatusRunning. Requeue with fromStatus=workflow.StatusParked must - // fail because the task is not parked. - err = s.Requeue(ctx, task.ID, workflow.StatusParked, "implement") - if err == nil { - t.Fatal("Requeue with stale fromStatus (workflow.StatusParked) on a running task must return an error, but got nil") - } - - // Verify the task was NOT changed. - got, err := s.TaskByID(ctx, task.ID) - if err != nil || got == nil { - t.Fatalf("TaskByID = (%+v, %v)", got, err) - } - if got.Status != workflow.StatusRunning { - t.Fatalf("task status changed to %q despite stale fromStatus guard; want %q", got.Status, workflow.StatusRunning) - } -} - -func TestRetryTaskAtomicallyRequeuesAndIncrements(t *testing.T) { - s := openTest(t) - ctx := t.Context() - if _, err := s.EnqueueIssue(ctx, "acme", "todo", 1, "t", "", "", ""); err != nil { - t.Fatal(err) - } - task, err := s.ClaimNext(ctx) - if err != nil || task == nil { - t.Fatalf("ClaimNext = (%+v, %v)", task, err) - } - if err := s.Transition(ctx, task.ID, workflow.StatusRunning, workflow.StatusParked, "failed"); err != nil { - t.Fatal(err) - } - - if err := s.RetryTask(ctx, task.ID, workflow.StatusParked, ""); err != nil { - t.Fatal(err) - } - got, err := s.TaskByID(ctx, task.ID) - if err != nil || got == nil { - t.Fatalf("TaskByID = (%+v, %v)", got, err) - } - if got.Status != workflow.StatusQueued || got.RetryCount != 1 { - t.Fatalf("task = status %q retry_count %d, want queued/1", got.Status, got.RetryCount) - } - if err := s.RetryTask(ctx, task.ID, workflow.StatusParked, ""); !errors.Is(err, ErrStaleTransition) { - t.Fatalf("stale RetryTask error = %v, want ErrStaleTransition", err) - } -} - -func TestRetryTaskWriteFailureLeavesParkedCountUnchanged(t *testing.T) { - s := openTest(t) - ctx := t.Context() - if _, err := s.EnqueueIssue(ctx, "acme", "todo", 1, "t", "", "", ""); err != nil { - t.Fatal(err) - } - task, _ := s.ClaimNext(ctx) - if err := s.Transition(ctx, task.ID, workflow.StatusRunning, workflow.StatusParked, "failed"); err != nil { - t.Fatal(err) - } - if _, err := s.db.ExecContext(ctx, ` - CREATE TRIGGER fail_retry BEFORE UPDATE OF retry_count ON tasks - BEGIN SELECT RAISE(FAIL, 'retry failed'); END`); err != nil { - t.Fatal(err) - } - - if err := s.RetryTask(ctx, task.ID, workflow.StatusParked, ""); err == nil { - t.Fatal("RetryTask succeeded despite forced write failure") - } - got, err := s.TaskByID(ctx, task.ID) - if err != nil || got == nil { - t.Fatalf("TaskByID = (%+v, %v)", got, err) - } - if got.Status != workflow.StatusParked || got.RetryCount != 0 { - t.Fatalf("partial retry write: status %q retry_count %d", got.Status, got.RetryCount) - } -} - -func TestRetryCountColumn(t *testing.T) { - s := openTest(t) - ctx := context.Background() - - if _, err := s.EnqueueIssue(ctx, "acme", "todo", 1, "t", "", "", ""); err != nil { - t.Fatal(err) - } - - // Verify column exists and defaults to 0 via direct query. - var count int - if err := s.db.QueryRowContext(ctx, - `SELECT retry_count FROM tasks WHERE owner='acme' AND repo='todo' AND issue_number=1`).Scan(&count); err != nil { - t.Fatalf("retry_count scan failed: %v", err) - } - if count != 0 { - t.Fatalf("default retry_count = %d, want 0", count) - } -} - -func TestClaimTransitionAndRecovery(t *testing.T) { - s := openTest(t) - ctx := context.Background() - - if _, err := s.EnqueueIssue(ctx, "acme", "todo", 7, "t", "", "archie,bug", ""); err != nil { - t.Fatal(err) - } - task, err := s.ClaimNext(ctx) - if err != nil || task == nil { - t.Fatalf("claim = (%v, %v)", task, err) - } - if task.Status != workflow.StatusRunning || task.Attempt != 1 || task.Labels != "archie,bug" { - t.Fatalf("claimed task = %+v", task) - } - if next, _ := s.ClaimNext(ctx); next != nil { - t.Fatal("second claim must return nil while task is running") - } - - // Crash recovery: running goes back to queued, attempt increments on - // the next claim. - if n, err := s.RecoverStale(ctx); err != nil || n != 1 { - t.Fatalf("recover = (%d, %v)", n, err) - } - task, err = s.ClaimNext(ctx) - if err != nil || task == nil || task.Attempt != 2 { - t.Fatalf("re-claim after recovery = (%+v, %v)", task, err) - } - - if err := s.Transition(ctx, task.ID, workflow.StatusRunning, workflow.StatusPROpen, "PR #3"); err != nil { - t.Fatal(err) - } - task.PRNumber = 3 - if err := s.Update(ctx, task); err != nil { - t.Fatal(err) - } - open, err := s.OpenPRs(ctx) - if err != nil || len(open) != 1 || open[0].PRNumber != 3 { - t.Fatalf("open PRs = (%+v, %v)", open, err) - } -} - -func TestRecoverStalePreservesChatTaskRouting(t *testing.T) { - s := openTest(t) - ctx := context.Background() - - created, err := s.EnqueueChatTask(ctx, "acme", "todo", "chat task", "", "tdd", "reviewer") - if err != nil { - t.Fatal(err) - } - claimed, err := s.ClaimNext(ctx) - if err != nil || claimed == nil || claimed.ID != created.ID { - t.Fatalf("ClaimNext() = (%+v, %v), want task %d", claimed, err, created.ID) - } - if n, err := s.RecoverStale(ctx); err != nil || n != 1 { - t.Fatalf("RecoverStale() = (%d, %v), want (1, nil)", n, err) - } - recovered, err := s.TaskByID(ctx, created.ID) - if err != nil { - t.Fatal(err) - } - if recovered == nil { - t.Fatal("TaskByID() returned nil after recovery") - } - if recovered.Status != workflow.StatusQueued || recovered.Source != workflow.SourceChat || - recovered.Identity != "reviewer" || recovered.Workflow != "tdd" { - t.Errorf("recovered task = %+v, want queued chat task routed to reviewer/tdd", recovered) - } -} - -func TestLifecycleQueriesPreserveChatTaskRouting(t *testing.T) { - s := openTest(t) - ctx := context.Background() - - waiting, err := s.EnqueueChatTask(ctx, "acme", "todo", "needs approval", "", "feasibility", "reviewer") - if err != nil { - t.Fatal(err) - } - if err := s.Transition(ctx, waiting.ID, workflow.StatusQueued, workflow.StatusWaitingHuman, "await approval"); err != nil { - t.Fatal(err) - } - // Routing metadata must survive a status transition: a chat task that - // stops for approval still has to come back to the identity that owns it. - waitingTask, err := s.TaskByID(ctx, waiting.ID) - if err != nil || waitingTask == nil { - t.Fatalf("TaskByID = (%+v, %v)", waitingTask, err) - } - if waitingTask.Status != workflow.StatusWaitingHuman || waitingTask.Source != workflow.SourceChat || - waitingTask.Identity != "reviewer" { - t.Fatalf("waiting task = %+v, want waiting_human chat/reviewer routing", waitingTask) - } - - pr, err := s.EnqueueChatTask(ctx, "acme", "todo", "open PR", "", "implement", "builder") - if err != nil { - t.Fatal(err) - } - pr.PRNumber = 7 - if err := s.Update(ctx, pr); err != nil { - t.Fatal(err) - } - if err := s.Transition(ctx, pr.ID, workflow.StatusQueued, workflow.StatusPROpen, "PR #7"); err != nil { - t.Fatal(err) - } - openPRs, err := s.OpenPRs(ctx) - if err != nil { - t.Fatal(err) - } - if len(openPRs) != 1 || openPRs[0].Source != workflow.SourceChat || - openPRs[0].Identity != "builder" { - t.Fatalf("OpenPRs() = %+v, want chat/builder routing", openPRs) - } -} diff --git a/internal/store/tasks_fields_test.go b/internal/store/tasks_fields_test.go deleted file mode 100644 index d7705a11d..000000000 --- a/internal/store/tasks_fields_test.go +++ /dev/null @@ -1,81 +0,0 @@ -package store - -import ( - "context" - "testing" - - "github.com/samcharles93/archie-core/internal/domain/workflow" -) - -// Tasks() is what the dashboard's task list is built from, and the UI reads -// two fields the query never selected: Plan, which gates the "Decision -// required" panel on a waiting_human task, and Source, which decides whether -// to render a forge issue link at all. -// -// Both came back as the zero value, so the panel could never appear and a -// chat-sourced task -- whose issue_number is synthetic -- rendered a link to -// an issue that does not exist. Neither failed loudly; the features were -// simply dead. -func TestTasksSelectsFieldsTheUIReads(t *testing.T) { - ctx := context.Background() - s := OpenTest(t) - t.Cleanup(func() { _ = s.Close() }) - - if _, err := s.EnqueueIssue(ctx, "o", "r", 7, "forge task", "body", "", ""); err != nil { - t.Fatalf("EnqueueIssue: %v", err) - } - forgeTaskRow, err := s.TaskByIssue(ctx, "o", "r", 7) - if err != nil || forgeTaskRow == nil { - t.Fatalf("TaskByIssue: %v", err) - } - forgeID := forgeTaskRow.ID - - chatTaskRow, err := s.EnqueueChatTask(ctx, "o", "r", "chat task", "body", "", "") - if err != nil { - t.Fatalf("EnqueueChatTask: %v", err) - } - chatID := chatTaskRow.ID - - // A plan is what an operator approves or rejects, so it has to survive - // the read the approval UI is built on. - const plan = "1. add the thing\n2. test the thing" - forgeTaskRow.Plan = plan - if err := s.Update(ctx, forgeTaskRow); err != nil { - t.Fatalf("Update: %v", err) - } - - tasks, err := s.Tasks(ctx, 50) - if err != nil { - t.Fatalf("Tasks: %v", err) - } - - byID := make(map[int64]workflow.Task, len(tasks)) - for _, task := range tasks { - byID[task.ID] = task - } - - forgeTask, ok := byID[forgeID] - if !ok { - t.Fatalf("forge task %d missing from Tasks()", forgeID) - } - if forgeTask.Plan != plan { - t.Errorf("Plan = %q, want %q: the approval panel is gated on this and "+ - "can never render while it is empty", forgeTask.Plan, plan) - } - if forgeTask.Source != workflow.SourceForge { - t.Errorf("Source = %q, want %q", forgeTask.Source, workflow.SourceForge) - } - - chatTask, ok := byID[chatID] - if !ok { - t.Fatalf("chat task %d missing from Tasks()", chatID) - } - if chatTask.Source != workflow.SourceChat { - t.Errorf("Source = %q, want %q: without it the UI links a synthetic "+ - "issue number to a forge issue that does not exist", - chatTask.Source, workflow.SourceChat) - } - if chatTask.IsForgeBacked() { - t.Error("IsForgeBacked() is true for a chat task read through Tasks()") - } -} diff --git a/internal/store/timestamps_test.go b/internal/store/timestamps_test.go deleted file mode 100644 index 3da697be4..000000000 --- a/internal/store/timestamps_test.go +++ /dev/null @@ -1,107 +0,0 @@ -package store - -import ( - "context" - "testing" - "time" -) - -// TestTaskTimestampsRoundTrip pins that a task carries usable created/updated -// times through every read path. They are what the dashboard shows a task's -// age from; before this they existed as SQLite columns but were never selected, -// so the API could not answer "how long has this been running". -func TestTaskTimestampsRoundTrip(t *testing.T) { - ctx := context.Background() - s := OpenTest(t) - t.Cleanup(func() { _ = s.Close() }) - - before := time.Now().UTC().Add(-2 * time.Second) - if _, err := s.EnqueueIssue(ctx, "o", "r", 1, "title", "body", "", ""); err != nil { - t.Fatalf("EnqueueIssue: %v", err) - } - after := time.Now().UTC().Add(2 * time.Second) - - inRange := func(t *testing.T, label string, got time.Time) { - t.Helper() - if got.IsZero() { - t.Errorf("%s is zero; the column was not selected", label) - return - } - if got.Before(before) || got.After(after) { - t.Errorf("%s = %s, want within [%s, %s]", label, got, before, after) - } - } - - // Every read path that returns a Task must populate them. - t.Run("TaskByIssue", func(t *testing.T) { - task, err := s.TaskByIssue(ctx, "o", "r", 1) - if err != nil || task == nil { - t.Fatalf("TaskByIssue = (%v, %v)", task, err) - } - inRange(t, "CreatedAt", task.CreatedAt) - inRange(t, "UpdatedAt", task.UpdatedAt) - }) - - t.Run("Tasks list", func(t *testing.T) { - tasks, err := s.Tasks(ctx, 10) - if err != nil { - t.Fatalf("Tasks: %v", err) - } - if len(tasks) != 1 { - t.Fatalf("got %d tasks, want 1", len(tasks)) - } - inRange(t, "CreatedAt", tasks[0].CreatedAt) - inRange(t, "UpdatedAt", tasks[0].UpdatedAt) - }) - - t.Run("ClaimNext", func(t *testing.T) { - task, err := s.ClaimNext(ctx) - if err != nil || task == nil { - t.Fatalf("ClaimNext = (%v, %v)", task, err) - } - inRange(t, "CreatedAt", task.CreatedAt) - inRange(t, "UpdatedAt", task.UpdatedAt) - }) -} - -// TestSQLiteTimeScan pins the scanner that makes the above possible: SQLite -// stores these as TEXT via datetime('now'), so the driver hands back a string -// and a plain time.Time scan fails. -func TestSQLiteTimeScan(t *testing.T) { - want := time.Date(2026, 8, 4, 9, 30, 15, 0, time.UTC) - - tests := []struct { - name string - input any - want time.Time - wantErr bool - }{ - {"datetime('now') text", "2026-08-04 09:30:15", want, false}, - {"same value as bytes", []byte("2026-08-04 09:30:15"), want, false}, - {"rfc3339 from another writer", "2026-08-04T09:30:15Z", want, false}, - {"driver already gave a time", want, want, false}, - {"null leaves the zero value", nil, time.Time{}, false}, - {"empty string leaves the zero value", "", time.Time{}, false}, - {"unrecognised text is an error", "not a time", time.Time{}, true}, - {"unsupported type is an error", 42, time.Time{}, true}, - } - - for _, tc := range tests { - t.Run(tc.name, func(t *testing.T) { - var got time.Time - err := sqliteTime{&got}.Scan(tc.input) - if tc.wantErr { - if err == nil { - t.Fatalf("Scan(%v) = nil error, want an error", tc.input) - } - return - } - if err != nil { - t.Fatalf("Scan(%v): %v", tc.input, err) - } - if !got.Equal(tc.want) { - t.Errorf("got %s, want %s", got, tc.want) - } - }) - } -} diff --git a/scripts/archie-update-install b/scripts/archie-update-install index f19aec273..eb5620085 100755 --- a/scripts/archie-update-install +++ b/scripts/archie-update-install @@ -43,49 +43,17 @@ configured_agent_image() { printf '%s' "$image" } -# The task store is `-tasks.sqlite`, not db_path itself: the daemon -# derives it with taskDBPath() in internal/app/archied/main.go, and the -# configured path may be a zero-byte placeholder while the real store sits -# beside it. Backing up the literal value would produce an empty backup, and a -# rollback would then restore that empty file over the database and delete its -# -wal/-shm -- destroying the task store it exists to protect. -# -# Only the top-level key counts. db_path can also appear under a TOML table -# (the retired [indexing] section once owned its own database), and the first -# match in the file can -# easily be one of those. -configured_task_db_path() { - local base - base="$(awk ' - BEGIN { top = 1 } - /^[[:space:]]*\[/ { top = 0 } - top && /^[[:space:]]*db_path[[:space:]]*=/ { - value = $0 - sub(/^[[:space:]]*db_path[[:space:]]*=[[:space:]]*/, "", value) - sub(/[[:space:]]*(#.*)?$/, "", value) - if (value ~ /^".*"$/) { sub(/^"/, "", value); sub(/"$/, "", value); print value } - else if (length(value) >= 2 && substr(value, 1, 1) == sprintf("%c", 39) && substr(value, length(value), 1) == sprintf("%c", 39)) print substr(value, 2, length(value) - 2) - exit - } - ' "$CONFIG_PATH" 2>/dev/null || true)" - [ -n "$base" ] || return 0 - printf '%s' "$base-tasks.sqlite" -} - AGENT_IMAGE="${ARCHIE_AGENT_IMAGE:-$(configured_agent_image)}" AGENT_IMAGE="${AGENT_IMAGE:-ghcr.io/samcharles93/archie-agent:latest}" AGENT_IMAGE_BACKUP="$BIN_DIR/archie-agent-image.prev.tar" # State for the managed image, independent of archied's daemon build stamp. AGENT_VERSION_FILE="${ARCHIE_AGENT_VERSION_FILE:-$BIN_DIR/archie-agent.version}" AGENT_VERSION_BACKUP="${ARCHIE_AGENT_VERSION_BACKUP:-$BIN_DIR/archie-agent.version.prev}" -TASK_DB_PATH="${ARCHIE_TASK_DB_PATH:-$(configured_task_db_path)}" -TASK_DB_BACKUP="${ARCHIE_TASK_DB_BACKUP:-$BIN_DIR/archie-task-db.prev.sqlite}" DB_SNAPSHOT="${ARCHIE_DB_SNAPSHOT:-$BIN_DIR/archie-db.pre-update.dump}" # The address the daemon dials for its state, so the watchdog can wait for it to -# accept connections before it starts archied. Read with the same narrow awk as -# the task database path and for the same reason: the daemon stays the authority -# on validation, and this script deliberately understands one scalar rather than -# parsing TOML. Scoped to [services.state] so the Gateway's own target cannot be +# accept connections before it starts archied. Read with a narrow awk: the +# daemon stays the authority on validation, and this script deliberately +# understands one scalar rather than parsing TOML. Scoped to [services.state] so the Gateway's own target cannot be # mistaken for it, and exact on the key so target_token is not. configured_state_store_target() { awk ' @@ -263,35 +231,14 @@ if [[ ",$components," == *,daemon,* ]]; then fi fi -# Pre-flight, before any write to the host. The task database backup is the -# watchdog's only route back from a forward schema migration, so an update -# that cannot take one must not start: once binaries are replaced, a failure -# leaves the previous release unable to read the store it just migrated. This -# runs ahead of the adapter refresh below so a refusal changes nothing at all. -# -# The snapshot is taken by the recovery subcommand of the release being -# installed, from its own checkout, rather than by hand-rolled sqlite3 shell: -# the operator running `archie-state-store backup` by hand and the installer -# are then the same implementation, and the two cannot drift. The installed -# binary is the previous release, which may predate the subcommand, so it -# cannot be the one asked -- and a release whose recovery path will not build is a -# release that cannot back up, which is exactly what this pre-flight refuses. -if [[ ",$components," == *,daemon,* ]] && [ -n "$TASK_DB_PATH" ] && [ -f "$TASK_DB_PATH" ]; then - echo "==> backing up task database for schema-safe rollback" - mkdir -p "$(dirname "$TASK_DB_BACKUP")" - if ! go run ./cmd/archie-state-store backup -db "$TASK_DB_PATH" -out "$TASK_DB_BACKUP"; then - echo "refusing to install $GW: could not back up the task database at $TASK_DB_PATH, so a failed update could not be rolled back" >&2 - exit 1 - fi -fi - # The pre-migration snapshot of the PostgreSQL database: the whole database, # since every service shares it. The new State Store migrates on start and a # migration is never undone automatically (goose Down drops tables), so this # snapshot is the only way back, restored by an operator with every service # stopped. The recovery subcommand resolves database_url from the same config # the services boot with, so the connection string never passes through this -# script. No snapshot, no update. +# script. No snapshot, no update: this pre-flight runs before any write to the +# host, so a refusal changes nothing at all. if [[ ",$components," == *,daemon,* ]]; then echo "==> snapshotting the database before the update migrates it" mkdir -p "$(dirname "$DB_SNAPSHOT")" @@ -392,8 +339,6 @@ systemd-run --user --unit=archied-update-restart --collect --quiet \ --setenv=ARCHIE_AGENT_VERSION_FILE="$AGENT_VERSION_FILE" \ --setenv=ARCHIE_AGENT_VERSION_BACKUP="$AGENT_VERSION_BACKUP" \ --setenv=ARCHIE_AGENT_VERSION_PREVIOUS_EXISTS="${AGENT_VERSION_PREVIOUS_EXISTS:-0}" \ - --setenv=ARCHIE_TASK_DB_PATH="$TASK_DB_PATH" \ - --setenv=ARCHIE_TASK_DB_BACKUP="$TASK_DB_BACKUP" \ --setenv=ARCHIE_DB_SNAPSHOT="$DB_SNAPSHOT" \ --setenv=ARCHIE_CONFIG_PATH="$CONFIG_PATH" \ --setenv=ARCHIE_UPDATE_STATE_STORE_TARGET="$STATE_STORE_TARGET" \ diff --git a/scripts/archie-update-watchdog b/scripts/archie-update-watchdog index a867767b3..d3b088399 100755 --- a/scripts/archie-update-watchdog +++ b/scripts/archie-update-watchdog @@ -13,8 +13,6 @@ AGENT_IMAGE_BACKUP="${ARCHIE_AGENT_IMAGE_BACKUP:-$BIN_DIR/archie-agent-image.pre AGENT_VERSION_FILE="${ARCHIE_AGENT_VERSION_FILE:-$BIN_DIR/archie-agent.version}" AGENT_VERSION_BACKUP="${ARCHIE_AGENT_VERSION_BACKUP:-$BIN_DIR/archie-agent.version.prev}" AGENT_VERSION_PREVIOUS_EXISTS="${ARCHIE_AGENT_VERSION_PREVIOUS_EXISTS:-0}" -TASK_DB_PATH="${ARCHIE_TASK_DB_PATH:-}" -TASK_DB_BACKUP="${ARCHIE_TASK_DB_BACKUP:-$BIN_DIR/archie-task-db.prev.sqlite}" DB_SNAPSHOT="${ARCHIE_DB_SNAPSHOT:-$BIN_DIR/archie-db.pre-update.dump}" CONFIG_PATH="${ARCHIE_CONFIG_PATH:-${XDG_CONFIG_HOME:-$HOME/.config}/archie/config.toml}" # The daemon exports its own health address (releaseupdate.CommandInstaller); @@ -206,20 +204,6 @@ rollback_agent_version() { fi } -rollback_task_db() { - if [ -z "$TASK_DB_PATH" ]; then - echo "==> no task database path; cannot restore schema-compatible state" >&2 - return 1 - fi - if [ ! -f "$TASK_DB_BACKUP" ]; then - echo "==> no task database backup; cannot restore schema-compatible state" >&2 - return 1 - fi - sqlite3 "$TASK_DB_BACKUP" "PRAGMA wal_checkpoint(TRUNCATE);" >/dev/null 2>&1 || true - cp -f "$TASK_DB_BACKUP" "$TASK_DB_PATH" - rm -f "$TASK_DB_PATH-wal" "$TASK_DB_PATH-shm" -} - # explain_database_recovery states what a daemon rollback does not do. The # PostgreSQL database is never restored automatically: goose Down drops tables, # and a restore is destructive, loses every write after the snapshot and needs @@ -240,15 +224,14 @@ fi echo "==> health check failed after ${HEALTH_TIMEOUT_SECONDS}s; rolling back changed components" rolled_back=false -# Stop before touching either the executable or its database. The service -# uses Restart=on-failure in the supported unit, so copying rollback state -# while a crash-loop child is alive can race with SQLite and execute the new -# binary after its files have been replaced. +# Stop before touching the executable. The service uses Restart=on-failure in +# the supported unit, so copying rollback state while a crash-loop child is +# alive can execute the new binary after its files have been replaced. if stop_units; then case "$COMPONENTS" in daemon) - if [ -f "$BIN_DIR/archied.prev" ] && { [ -z "$TASK_DB_PATH" ] || [ -f "$TASK_DB_BACKUP" ]; }; then - if { [ -z "$TASK_DB_PATH" ] || rollback_task_db; } && rollback_gateway; then + if [ -f "$BIN_DIR/archied.prev" ]; then + if rollback_gateway; then rolled_back=true fi else @@ -267,8 +250,8 @@ if stop_units; then daemon,agent) # Preserve the old all-or-nothing rollback guarantee: never restore one # component and leave the other on the failed release. - if [ -f "$BIN_DIR/archied.prev" ] && [ -f "$AGENT_IMAGE_BACKUP" ] && { [ -z "$TASK_DB_PATH" ] || [ -f "$TASK_DB_BACKUP" ]; }; then - if rollback_agent_image && rollback_agent_version && { [ -z "$TASK_DB_PATH" ] || rollback_task_db; } && rollback_gateway; then + if [ -f "$BIN_DIR/archied.prev" ] && [ -f "$AGENT_IMAGE_BACKUP" ]; then + if rollback_agent_image && rollback_agent_version && rollback_gateway; then rolled_back=true fi else From e3ee044c5e3ec994112ade999b519d4ef526f85d Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Thu, 24 Sep 2026 14:43:50 +1000 Subject: [PATCH 4/8] refactor(store)!: remove the SQLite task store, the PocketBase event store and the SQLite session store The State Store, event capture and Gateway conversations already serve from PostgreSQL. This deletes internal/store and internal/infrastructure/edastore, the SQLite gateway session store and openProductionTaskStore, and the -db recovery path on a legacy task file; backup, restore, validate and rollback work on the database database_url names. - The binding-secret cipher moves to internal/infrastructure/bindingcipher and ToolCall to internal/infrastructure/postgres. - NewSessionStoreMemory is now a pure in-memory store that passes the shared SessionStore conformance suite. - Tests run against PostgreSQL through internal/infrastructure/postgres/pgstore; legacyimport/legacyfixture writes the legacy files the import and the boot gate read. - The cron dialect is owned in internal/domain/scheduling, so github.com/pocketbase/pocketbase and pocketbase/dbx leave go.mod. modernc.org/sqlite stays for the one-time import (legacyread). - The UI and Messaging architecture gates ban the Postgres and legacy readers in place of internal/store. --- cmd/archie-messaging/architecture_test.go | 4 +- cmd/archie-state-store/import_test.go | 15 +- cmd/archie-state-store/main_test.go | 28 +- cmd/archie-state-store/recovery.go | 16 +- cmd/archie-state-store/recovery_test.go | 526 ++++-------------- cmd/archie-ui/architecture_test.go | 4 +- cmd/archie-ui/main_test.go | 26 +- cmd/archie-ui/pgtest_test.go | 10 + go.mod | 18 +- go.sum | 51 -- internal/app/agentworker/pgtest_test.go | 10 + .../app/agentworker/task_execution_test.go | 13 +- internal/app/archied/binding_cipher.go | 6 +- .../archied/chat_store_composition_test.go | 8 +- .../archied/config_snapshot_channels_test.go | 9 +- internal/app/archied/config_snapshot_test.go | 19 +- .../app/archied/control_plane_restart_test.go | 4 +- .../control_plane_watch_outage_test.go | 13 +- internal/app/archied/cutover_test.go | 17 +- internal/app/archied/main.go | 5 - internal/app/archied/main_test.go | 24 +- internal/app/archied/readiness_test.go | 8 +- internal/app/archied/routing_bindings_test.go | 9 +- internal/app/archied/sd_notify_test.go | 8 +- .../app/archied/state_store_consumers_test.go | 34 +- internal/app/archied/state_store_eda.go | 4 +- internal/app/archied/state_store_recovery.go | 140 +---- .../archied/state_store_recovery_postgres.go | 5 +- internal/app/archied/state_store_test.go | 20 +- internal/app/archied/state_store_toolcalls.go | 10 +- .../app/archied/state_store_toolcalls_test.go | 24 +- internal/app/archied/status_health_test.go | 4 +- .../app/archied/task_action_adapter_test.go | 29 +- internal/app/archied/task_actions_test.go | 14 +- internal/app/archieui/compose_test.go | 6 +- internal/app/archieui/degraded_routes_test.go | 10 +- internal/app/archieui/pgtest_test.go | 10 + internal/app/archieui/run_test.go | 13 +- internal/app/archieui/task_logs_test.go | 10 +- internal/app/controlplane/controlplane.go | 18 +- .../app/controlplane/controlplane_test.go | 25 +- .../controlplane/controlplane_watch_test.go | 7 +- internal/app/controlplane/pgtest_test.go | 10 + internal/app/controlplane/registry.go | 8 +- internal/app/controlplane/runtime_config.go | 6 +- .../step_vocabulary_agreement_test.go | 6 +- .../app/controlplane/workflow_settings.go | 6 +- internal/daemon/daemon_test.go | 22 +- internal/daemon/dispatch_bindings_test.go | 38 +- internal/daemon/identity_dispatch_test.go | 6 +- internal/daemon/pgtest_test.go | 10 + internal/daemon/playbook_dispatch_test.go | 16 +- internal/daemon/playbook_run_test.go | 4 +- internal/daemon/task_cancellation_test.go | 10 +- internal/daemon/terminal_cleanup_test.go | 4 +- internal/daemon/workflow_definition_test.go | 4 +- internal/domain/workflow/pgtest_test.go | 10 + .../domain/workflow/store_integration_test.go | 21 +- .../infrastructure/bindingcipher/cipher.go | 4 +- .../bindingcipher/cipher_test.go | 107 +--- .../captureintake/pgtest_test.go | 10 + .../captureintake/receiver_test.go | 15 +- .../gatewayrpc/conformance_test.go | 4 +- .../legacyfixture/legacyfixture.go | 157 ++++++ .../legacyimport/legacyimport_test.go | 158 +----- internal/infrastructure/postgres/edastore.go | 58 +- .../infrastructure/postgres/edastore_test.go | 56 +- .../postgres/pgstore/pgstore.go | 61 ++ internal/infrastructure/postgres/resources.go | 3 +- .../staterpc/attribution_test.go | 4 +- .../staterpc/capture_stream_test.go | 12 +- .../staterpc/conformance_test.go | 67 +-- .../infrastructure/staterpc/error_test.go | 20 +- .../infrastructure/staterpc/pgtest_test.go | 10 + .../staterpc/task_grants_test.go | 20 +- .../staterpc/task_log_nilslice_test.go | 4 +- .../infrastructure/staterpc/task_log_test.go | 6 +- .../infrastructure/taskactions/pgtest_test.go | 10 + .../infrastructure/taskactions/rpc_test.go | 6 +- internal/webui/api_binding_test.go | 13 +- internal/webui/api_capture_test.go | 18 +- internal/webui/api_config_test.go | 14 +- internal/webui/api_mapping_test.go | 16 +- internal/webui/api_tasks_actions_test.go | 4 +- internal/webui/pgtest_test.go | 10 + internal/webui/remote_store_test.go | 12 +- internal/webui/sse_test.go | 3 +- internal/webui/webui_test.go | 17 +- tools/go.mod | 6 - tools/go.sum | 155 ++++-- 90 files changed, 1022 insertions(+), 1453 deletions(-) create mode 100644 cmd/archie-ui/pgtest_test.go create mode 100644 internal/app/agentworker/pgtest_test.go create mode 100644 internal/app/archieui/pgtest_test.go create mode 100644 internal/app/controlplane/pgtest_test.go create mode 100644 internal/daemon/pgtest_test.go create mode 100644 internal/domain/workflow/pgtest_test.go create mode 100644 internal/infrastructure/captureintake/pgtest_test.go create mode 100644 internal/infrastructure/legacyimport/legacyfixture/legacyfixture.go create mode 100644 internal/infrastructure/postgres/pgstore/pgstore.go create mode 100644 internal/infrastructure/staterpc/pgtest_test.go create mode 100644 internal/infrastructure/taskactions/pgtest_test.go create mode 100644 internal/webui/pgtest_test.go diff --git a/cmd/archie-messaging/architecture_test.go b/cmd/archie-messaging/architecture_test.go index 876f96c35..d2feb77cf 100644 --- a/cmd/archie-messaging/architecture_test.go +++ b/cmd/archie-messaging/architecture_test.go @@ -36,7 +36,9 @@ type bannedCategory struct { var deletionGate = []bannedCategory{ {"state store", []string{ "modernc.org/sqlite", - modulePath + "internal/store", + "github.com/jackc/pgx", + modulePath + "internal/infrastructure/postgres", + modulePath + "internal/infrastructure/legacyread", }}, {"daemon runtime", []string{ modulePath + "internal/daemon", diff --git a/cmd/archie-state-store/import_test.go b/cmd/archie-state-store/import_test.go index f0a61458c..97bcbb3bc 100644 --- a/cmd/archie-state-store/import_test.go +++ b/cmd/archie-state-store/import_test.go @@ -6,6 +6,7 @@ import ( "strings" "testing" + "github.com/samcharles93/archie-core/internal/infrastructure/legacyimport/legacyfixture" "github.com/samcharles93/archie-core/internal/infrastructure/postgres" "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest" ) @@ -17,18 +18,14 @@ func TestMain(m *testing.M) { os.Exit(pgtest.Main(m)) } // against the same database is refused because the first one completed. func TestRecoveryImportMovesTheInstallOnce(t *testing.T) { dbPath := filepath.Join(t.TempDir(), "archie.db") - st := openTaskStore(t, dbPath+"-tasks.sqlite") - seedTask(t, st, "carried over") - if err := st.Close(); err != nil { - t.Fatalf("close task store: %v", err) - } + legacyfixture.Install(t, dbPath) url := pgtest.URL(t) code, stdout, stderr := runRecoveryCmd(t, "import", "-db-path", dbPath, "-database-url", url) if code != 0 { t.Fatalf("import exited %d; stderr = %q", code, stderr) } - if !strings.Contains(stdout, "tasks=1") { + if !strings.Contains(stdout, "tasks=2") { t.Errorf("import summary %q does not report the imported task", stdout) } @@ -37,9 +34,9 @@ func TestRecoveryImportMovesTheInstallOnce(t *testing.T) { t.Fatalf("postgres.Open: %v", err) } defer pool.Close() - var title string - if err := pool.QueryRow(t.Context(), "SELECT title FROM tasks").Scan(&title); err != nil || title != "carried over" { - t.Fatalf("imported task title = %q, %v; want %q", title, err, "carried over") + var issue int64 + if err := pool.QueryRow(t.Context(), "SELECT issue_number FROM tasks WHERE id = 1").Scan(&issue); err != nil || issue != 7 { + t.Fatalf("imported task 1 issue = %d, %v; want 7", issue, err) } code, _, stderr = runRecoveryCmd(t, "import", "-db-path", dbPath, "-database-url", url) diff --git a/cmd/archie-state-store/main_test.go b/cmd/archie-state-store/main_test.go index bf2c5f6a5..3f8d5d82b 100644 --- a/cmd/archie-state-store/main_test.go +++ b/cmd/archie-state-store/main_test.go @@ -37,10 +37,10 @@ import ( "github.com/samcharles93/archie-core/internal/domain/binding" "github.com/samcharles93/archie-core/internal/domain/mapping" + "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/events" "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest" "github.com/samcharles93/archie-core/internal/infrastructure/staterpc" - "github.com/samcharles93/archie-core/internal/store" ) // repoRoot walks up from the test's source directory to find the module root @@ -92,6 +92,12 @@ func buildBinary(t *testing.T, dir string) string { // db_path and database_url it owns. The // forge token resolves from an env var, so no real credential is needed. func writeMinimalConfig(t *testing.T, dir string) string { + t.Helper() + return writeConfigFor(t, dir, pgtest.URL(t)) +} + +// writeConfigFor is writeMinimalConfig naming the database at url. +func writeConfigFor(t *testing.T, dir, url string) string { t.Helper() cfg := filepath.Join(dir, "config.toml") content := fmt.Sprintf(`bot_user = "archie-bot" @@ -104,7 +110,7 @@ token = { engine = "env", key = "ARCHIE_GITHUB_TOKEN" } [[repos]] owner = "acme" name = "widget" -`, filepath.Join(dir, "archie.db"), pgtest.URL(t)) +`, filepath.Join(dir, "archie.db"), url) if err := os.WriteFile(cfg, []byte(content), 0o600); err != nil { t.Fatalf("write config: %v", err) } @@ -287,13 +293,13 @@ func (p *stateStoreProcess) stop(t *testing.T) { } // contract is the combined consumer surface a daemon/gateway/agent mixes: the -// task lifecycle + events surface (store.TaskStore) and the capture surface. +// task lifecycle + events surface (storecontract.TaskStore) and the capture surface. // Mapping/binding/dispatch is exercised separately in // TestStateStoreRealProcessRemoteSurfaces via the concrete Client, which // asserts against each narrow interface at compile time. type contract interface { - store.TaskStore - store.CaptureStore + storecontract.TaskStore + storecontract.CaptureStore } // dial opens a gRPC connection to the state store process and wraps it in the @@ -311,8 +317,8 @@ func dial(t *testing.T, addr string) contract { // capture builds a CapturedEvent without pulling the whole store field set // into every call site. -func capture(source, body string) store.CapturedEvent { - return store.CapturedEvent{Source: source, Body: body, Authenticated: true} +func capture(source, body string) storecontract.CapturedEvent { + return storecontract.CapturedEvent{Source: source, Body: body, Authenticated: true} } // TestStateStoreRealProcessSmoke exercises the actual archie-state-store @@ -409,14 +415,14 @@ func TestStateStoreRealProcessSmoke(t *testing.T) { } t.Run("error_sentinel_fidelity", func(t *testing.T) { - // A stale transition must rehydrate to store.ErrStaleTransition across + // A stale transition must rehydrate to storecontract.ErrStaleTransition across // the wire (§7). Because the binary is up and we dialed it, a sentinel // mismatch here would surface as a transport error, so a pass proves // the gRPC mapError/unmapError round-trip, not just the in-process // adapter. err := cl.Transition(ctx, task.ID, "queued", "merged", "") - if !errors.Is(err, store.ErrStaleTransition) { - t.Fatalf("stale Transition = %v, want store.ErrStaleTransition", err) + if !errors.Is(err, storecontract.ErrStaleTransition) { + t.Fatalf("stale Transition = %v, want storecontract.ErrStaleTransition", err) } }) @@ -612,7 +618,7 @@ func TestStateStoreRealProcessRemoteSurfaces(t *testing.T) { } // Remote surfaces share error-sentinel fidelity on the wire too. missing := mapping.Mapping{ID: "rabsent00000000", Name: "x", Fields: []mapping.Field{{Name: "a", Path: "a", Type: mapping.TypeString}}} - if err := cl.UpdateMapping(ctx, missing); !errors.Is(err, store.ErrMappingNotFound) { + if err := cl.UpdateMapping(ctx, missing); !errors.Is(err, storecontract.ErrMappingNotFound) { t.Fatalf("UpdateMapping missing = %v, want ErrMappingNotFound", err) } } diff --git a/cmd/archie-state-store/recovery.go b/cmd/archie-state-store/recovery.go index dcab44c29..a2df7e8ac 100644 --- a/cmd/archie-state-store/recovery.go +++ b/cmd/archie-state-store/recovery.go @@ -20,10 +20,9 @@ const recoveryUsage = `usage: archie-state-store [flags] With no command, archie-state-store serves the State Store gRPC contract. The recovery commands are how an operator recovers a database the control -plane will not start on. Without -db they operate on the PostgreSQL database -the configuration's database_url names, through pg_dump and pg_restore (which -must be on PATH); with -db, on a legacy SQLite task file (the configured -db_path with "-tasks.sqlite" appended). +plane will not start on. They operate on the PostgreSQL database the +configuration's database_url names, through pg_dump and pg_restore (which +must be on PATH). backup takes a consistent snapshot of a serving database. restore is destructive and offline: stop every archie service first, since it refuses @@ -32,11 +31,11 @@ snapshot is lost. rollback refuses while the State Store serves. There is no automatic schema rollback: the way back from a migration is restoring the snapshot taken before it. - backup [-db FILE] -out FILE write a snapshot of the database - restore [-db FILE] -from FILE replace the database with a snapshot - validate [-db FILE] check the database, its stored settings and + backup -out FILE write a snapshot of the database + restore -from FILE replace the database with a snapshot + validate check the database, its stored settings and the configuration the daemon would boot with - rollback [-db FILE] -kind KIND replay an earlier revision of a stored + rollback -kind KIND replay an earlier revision of a stored [-revision N] resource through the ordinary replace import [-db-path PATH] copy the legacy SQLite stores named from [-database-url URL] db_path into an empty Postgres database, @@ -68,7 +67,6 @@ func runRecovery(args []string, stdout, stderr io.Writer) int { flags := flag.NewFlagSet("archie-state-store "+command, flag.ContinueOnError) flags.SetOutput(stderr) flags.Usage = func() { fmt.Fprint(stderr, recoveryUsage) } - flags.StringVar(&options.DB, "db", "", "legacy SQLite task file (-tasks.sqlite); omit to use the configured database_url") flags.StringVar(&options.Out, "out", "", "snapshot file backup writes") flags.StringVar(&options.From, "from", "", "snapshot file restore reads") flags.StringVar(&options.Kind, "kind", "", "control-plane resource kind rollback replays") diff --git a/cmd/archie-state-store/recovery_test.go b/cmd/archie-state-store/recovery_test.go index 436e18306..8756ba2c2 100644 --- a/cmd/archie-state-store/recovery_test.go +++ b/cmd/archie-state-store/recovery_test.go @@ -1,19 +1,18 @@ -// Package main tests the offline recovery subcommands of archie-state-store: -// backup, restore, validate and rollback against the task database file -// directly. They are the operator's only path back when the control plane's -// stored settings will not validate, because the daemon fails closed: the -// in-band remedy (replay an earlier revision while the State Store is up) is -// unavailable in exactly the case that needs it. +// Package main tests the offline recovery subcommands of archie-state-store +// against the PostgreSQL database the configuration names. They are the +// operator's only path back when the control plane's stored settings will not +// validate, because the daemon fails closed: the in-band remedy (replay an +// earlier revision while the State Store is up) is unavailable in exactly the +// case that needs it. // // The tests drive the subcommands the way an operator does -- through -// runRecovery, against real files on disk -- rather than through the internal -// helpers, so the flag surface and the exit codes are part of what is verified. +// runRecovery -- rather than through the internal helpers, so the flag surface +// and the exit codes are part of what is verified. package main import ( "bytes" - "database/sql" "encoding/json" "fmt" "os" @@ -22,13 +21,14 @@ import ( "strings" "testing" - _ "modernc.org/sqlite" - "github.com/samcharles93/archie-core/internal/app/archied" "github.com/samcharles93/archie-core/internal/app/controlplane" + "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/infrastructure/configuration" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest" "github.com/samcharles93/archie-core/internal/infrastructure/workflowsteps" - "github.com/samcharles93/archie-core/internal/store" ) // runRecoveryCmd runs one subcommand the way main does and returns its exit @@ -40,240 +40,38 @@ func runRecoveryCmd(t *testing.T, args ...string) (int, string, string) { return code, stdout.String(), stderr.String() } -// openTaskStore opens the task database the subcommands operate on. It does not -// take the ownership lock: only the serving process does that, and a test that -// wants a "live" store holds it explicitly with holdStoreOwnership. -func openTaskStore(t *testing.T, path string) *store.Store { +// recoveryFixture writes a config naming a fresh migrated database and returns +// it with the task database on that database. +func recoveryFixture(t *testing.T) (string, *pgstore.TaskDB) { t.Helper() - st, err := store.Open(t.Context(), path) - if err != nil { - t.Fatalf("open task store %s: %v", path, err) - } - t.Cleanup(func() { _ = st.Close() }) - return st + url := pgtest.URL(t) + configPath := writeConfigFor(t, t.TempDir(), url) + return configPath, pgstore.On(pgstore.PoolAt(t, url)) } -// holdStoreOwnership takes the ownership lock the running State Store holds for -// its whole life, so a test can prove a command refuses to touch a live store. -func holdStoreOwnership(t *testing.T, path string) { - t.Helper() - ownership, err := store.AcquireOwnership(path) - if err != nil { - t.Fatalf("acquire store ownership: %v", err) - } - t.Cleanup(func() { _ = ownership.Release() }) -} - -// seedTask writes one task so a snapshot can be distinguished from the live -// database by what it contains, not merely by its existence. -func seedTask(t *testing.T, st *store.Store, title string) { +// seedTask writes one task so the database holds more than its settings. +func seedTask(t *testing.T, st *pgstore.TaskDB, title string) { t.Helper() if _, err := st.EnqueueChatTask(t.Context(), "acme", "widget", title, "body", "implement", ""); err != nil { t.Fatalf("seed task %q: %v", title, err) } } -func taskTitles(t *testing.T, path string) []string { +// execRaw runs one statement against the database the way an operator editing +// a broken store would, bypassing every check the store applies. +func execRaw(t *testing.T, st *pgstore.TaskDB, statement string) { t.Helper() - st := openTaskStore(t, path) - tasks, err := st.Tasks(t.Context(), 100) - if err != nil { - t.Fatalf("list tasks in %s: %v", path, err) - } - titles := make([]string, 0, len(tasks)) - for _, task := range tasks { - titles = append(titles, task.Title) - } - return titles -} - -// backupPath is the snapshot every restore test restores from. -func backupPath(t *testing.T, dir string) string { return filepath.Join(dir, "snapshot.sqlite") } - -// backup takes the snapshot the caller then restores, through the subcommand -// under test rather than through the store directly, so a broken backup fails -// the restore test too instead of silently passing an empty file. -func backup(t *testing.T, db, out string) { - t.Helper() - code, _, stderr := runRecoveryCmd(t, "backup", "-db", db, "-out", out) - if code != 0 { - t.Fatalf("backup exited %d: %s", code, stderr) - } -} - -// The update installer cannot stop the process that runs it, so it backs the -// task database up while the State Store is serving. VACUUM INTO is safe -// against a live writer; a backup that insisted on an exclusively-owned file -// would break the one caller it has, and the update would refuse to start. -func TestRecoveryBackupSnapshotsAStoreItsStateStoreIsServing(t *testing.T) { - dir := t.TempDir() - db := filepath.Join(dir, "archie.db-tasks.sqlite") - out := backupPath(t, dir) - seedTask(t, openTaskStore(t, db), "before") - holdStoreOwnership(t, db) - if err := os.WriteFile(out, []byte("stale snapshot"), 0o600); err != nil { + if _, err := st.Pool.Exec(t.Context(), statement); err != nil { t.Fatal(err) } - - code, stdout, stderr := runRecoveryCmd(t, "backup", "-db", db, "-out", out) - if code != 0 { - t.Fatalf("backup exited %d: %s", code, stderr) - } - if !strings.Contains(stdout, out) || !strings.Contains(stdout, db) { - t.Errorf("backup must report the database and the snapshot it wrote; stdout = %q", stdout) - } - // The stale file was replaced by a real snapshot, and the snapshot is a - // store a restore can put back: same rows, readable through the store. - if got := taskTitles(t, out); len(got) != 1 || got[0] != "before" { - t.Fatalf("snapshot tasks = %v, want the one seeded task", got) - } - if entries, err := filepath.Glob(out + ".tmp*"); err != nil || len(entries) != 0 { - t.Errorf("backup left scratch files beside the snapshot: %v (%v)", entries, err) - } -} - -// The snapshot is the rollback state, so an interrupted backup must never -// leave a truncated file where a good snapshot was. -func TestRecoveryBackupRefusesAMissingDatabase(t *testing.T) { - dir := t.TempDir() - code, _, stderr := runRecoveryCmd(t, "backup", "-db", filepath.Join(dir, "absent.sqlite"), "-out", backupPath(t, dir)) - if code == 0 { - t.Fatal("backup of a missing database succeeded") - } - if !strings.Contains(stderr, "absent.sqlite") { - t.Errorf("refusal must name the database it could not read; stderr = %q", stderr) - } -} - -// backup is the one recovery command allowed to run against a serving store, -// and that exemption is only sound while it never replaces the database. With -// -out naming the database it renames the snapshot over the live file and -// leaves the WAL of the database it just unlinked -- the state the restore path -// refuses up front and the code elsewhere calls unrecoverable. -func TestRecoveryBackupRefusesTheDatabaseAsItsOwnSnapshot(t *testing.T) { - db := filepath.Join(t.TempDir(), "archie.db-tasks.sqlite") - st := openTaskStore(t, db) - seedTask(t, st, "live") - - code, _, stderr := runRecoveryCmd(t, "backup", "-db", db, "-out", db) - if code == 0 { - t.Fatal("backup over the database itself succeeded") - } - if !strings.Contains(stderr, "is the database itself") { - t.Errorf("refusal must say the snapshot is the database; stderr = %q", stderr) - } - if got := taskTitles(t, db); len(got) != 1 || got[0] != "live" { - t.Fatalf("refused backup changed the database: tasks = %v", got) - } -} - -// Restoring is the forward-migration escape hatch: the previous release -// reads this file, so it must be exactly the snapshot, with the WAL that -// belongs to the replaced database gone rather than replayed over it. -func TestRecoveryRestorePutsTheSnapshotBackAndDropsItsWAL(t *testing.T) { - dir := t.TempDir() - db := filepath.Join(dir, "archie.db-tasks.sqlite") - out := backupPath(t, dir) - st := openTaskStore(t, db) - seedTask(t, st, "before") - backup(t, db, out) - seedTask(t, st, "after") - - code, stdout, stderr := runRecoveryCmd(t, "restore", "-db", db, "-from", out) - if code != 0 { - t.Fatalf("restore exited %d: %s", code, stderr) - } - if !strings.Contains(stdout, out) { - t.Errorf("restore must report the snapshot it restored from; stdout = %q", stdout) - } - // Checked before anything reopens the database: opening a store sets WAL - // mode, which creates these files, so the point is that the restore did not - // leave the replaced database's log behind -- not that a later reader - // cannot recreate its own. - for _, suffix := range []string{"-wal", "-shm"} { - if _, err := os.Stat(db + suffix); err == nil { - t.Errorf("%s survived the restore: the replaced database's write-ahead log must not be replayed over the snapshot", db+suffix) - } - } - if got := taskTitles(t, db); len(got) != 1 || got[0] != "before" { - t.Fatalf("restored tasks = %v, want only the snapshot's task", got) - } -} - -// Overwriting a database a running State Store still owns leaves that process -// writing to an unlinked inode while the store serves a file nobody owns -- -// the one way an offline command can destroy a task store. -func TestRecoveryRestoreRefusesAStoreTheStateStoreIsRunning(t *testing.T) { - dir := t.TempDir() - db := filepath.Join(dir, "archie.db-tasks.sqlite") - out := backupPath(t, dir) - st := openTaskStore(t, db) - seedTask(t, st, "before") - backup(t, db, out) - seedTask(t, st, "after") - holdStoreOwnership(t, db) - - code, _, stderr := runRecoveryCmd(t, "restore", "-db", db, "-from", out) - if code == 0 { - t.Fatal("restore against a live State Store succeeded") - } - if !strings.Contains(stderr, "owned by another process") { - t.Errorf("refusal must say the database is owned by another process; stderr = %q", stderr) - } - if got := taskTitles(t, db); len(got) != 2 { - t.Fatalf("refused restore changed the database: tasks = %v", got) - } -} - -func TestRecoveryRestoreRefusesAFileThatIsNotAStore(t *testing.T) { - dir := t.TempDir() - db := filepath.Join(dir, "archie.db-tasks.sqlite") - seedTask(t, openTaskStore(t, db), "live") - notAStore := filepath.Join(dir, "notes.txt") - if err := os.WriteFile(notAStore, []byte("this is not a database"), 0o600); err != nil { - t.Fatal(err) - } - - code, _, stderr := runRecoveryCmd(t, "restore", "-db", db, "-from", notAStore) - if code == 0 { - t.Fatal("restore from a file that is not a store succeeded") - } - if !strings.Contains(stderr, notAStore) { - t.Errorf("refusal must name the snapshot it could not read; stderr = %q", stderr) - } - if got := taskTitles(t, db); len(got) != 1 { - t.Fatalf("refused restore changed the database: tasks = %v", got) - } -} - -func TestRecoveryRestoreRefusesTheDatabaseAsItsOwnSnapshot(t *testing.T) { - // Restoring a database from itself would delete the write-ahead log of the - // file it is about to copy, so the one case that must never reach the swap - // is refused up front. - db := filepath.Join(t.TempDir(), "archie.db-tasks.sqlite") - seedTask(t, openTaskStore(t, db), "live") - - code, _, stderr := runRecoveryCmd(t, "restore", "-db", db, "-from", db) - if code == 0 { - t.Fatal("restore from the database itself succeeded") - } - if !strings.Contains(stderr, "is the database itself") { - t.Errorf("refusal must say the snapshot is the database; stderr = %q", stderr) - } - if got := taskTitles(t, db); len(got) != 1 { - t.Fatalf("refused restore changed the database: tasks = %v", got) - } } func TestRecoveryValidateAcceptsAHealthyStore(t *testing.T) { - dir := t.TempDir() - configPath := writeMinimalConfig(t, dir) - db := filepath.Join(dir, "archie.db-tasks.sqlite") - st := openTaskStore(t, db) + configPath, st := recoveryFixture(t) seedTask(t, st, "healthy") seedStoreResources(t, st, configPath) - code, stdout, stderr := runRecoveryCmd(t, "validate", "-db", db, "-config", configPath) + code, stdout, stderr := runRecoveryCmd(t, "validate", "-config", configPath) if code != 0 { t.Fatalf("validate exited %d: %s", code, stderr) } @@ -293,63 +91,54 @@ func TestRecoveryValidateAcceptsAHealthyStore(t *testing.T) { // path's own per-resource decode, and the two disagree: the write path accepts // a scheduling policy boot rejects. func TestRecoveryValidateRunsTheGateBootRuns(t *testing.T) { - dir := t.TempDir() - configPath := writeMinimalConfig(t, dir) - db := filepath.Join(dir, "archie.db-tasks.sqlite") - seedStoreResources(t, openTaskStore(t, db), configPath) + configPath, st := recoveryFixture(t) + seedStoreResources(t, st, configPath) // The control: a store seeded from this config is one the daemon boots on. - code, _, stderr := runRecoveryCmd(t, "validate", "-db", db, "-config", configPath) + code, _, stderr := runRecoveryCmd(t, "validate", "-config", configPath) if code != 0 { t.Fatalf("validate exited %d on a store the daemon starts on: %s", code, stderr) } + // The upgrade case: a release defines a kind the store does not hold yet, + // and validate runs before the State Store has started again. The State + // Store seeds the kind it is missing, so the store is not the reason the + // daemon would refuse to start. + execRaw(t, st, `DELETE FROM resources WHERE kind='provider-settings'`) + code, stdout, stderr := runRecoveryCmd(t, "validate", "-config", configPath) + if code != 0 { + t.Fatalf("validate refused a store missing a kind the State Store seeds; stderr = %q", stderr) + } + if count := storedResourceCount(t, stdout); count == 0 { + t.Errorf("validate must still check the kinds the store does hold; stdout = %q", stdout) + } + // A hand-edited value, or an older revision of one: the write path's own // validator never inspects dispatch.trigger, so only the config gate // catches it, and the daemon exits 1 on it (validateDispatch). - if err := execRaw(t, db, `UPDATE resources SET value='{"poll_interval":"1m","max_retries":3,"dispatch":{"trigger":"bogus"}}' WHERE kind='scheduling-policy'`); err != nil { - t.Fatal(err) - } - code, stdout, stderr := runRecoveryCmd(t, "validate", "-db", db, "-config", configPath) + execRaw(t, st, `UPDATE resources SET value='{"poll_interval":"1m","max_retries":3,"dispatch":{"trigger":"bogus"}}' WHERE kind='scheduling-policy'`) + code, stdout, stderr = runRecoveryCmd(t, "validate", "-config", configPath) if code == 0 { t.Fatalf("validate accepted a stored policy the daemon refuses to boot with; stdout = %q", stdout) } if !strings.Contains(stderr, "dispatch.trigger") { t.Errorf("refusal must name what boot rejects; stderr = %q", stderr) } +} - // A store the State Store never seeded holds no kinds at all. Its next start - // creates the resources table and seeds every kind from this same config - // (internal/app/archied/state_store.go), so archied layers those seeds and - // starts: refusing the file here would send an operator to restore a - // snapshot for a store the daemon boots on perfectly well. - unseeded := filepath.Join(dir, "unseeded.db-tasks.sqlite") - openTaskStore(t, unseeded) - code, stdout, stderr = runRecoveryCmd(t, "validate", "-db", unseeded, "-config", configPath) +// A database the State Store never seeded holds no kinds at all. Its next +// start seeds every kind from this same config, so archied layers those seeds +// and starts: refusing it would send an operator to restore a snapshot for a +// database the daemon boots on perfectly well. +func TestRecoveryValidateAcceptsAnUnseededDatabase(t *testing.T) { + configPath, _ := recoveryFixture(t) + code, stdout, stderr := runRecoveryCmd(t, "validate", "-config", configPath) if code != 0 { t.Fatalf("validate refused a store the State Store would seed on its next start; stderr = %q", stderr) } if !strings.Contains(stdout, "0 stored resources validate") { t.Errorf("validate must report that there was nothing stored to check; stdout = %q", stdout) } - - // The upgrade case: a release defines a kind the store does not hold yet, - // and validate runs before the State Store has started again. The State - // Store seeds the kind it is missing, so this is the same stance as the - // store with nothing stored at all -- the file is not the reason the daemon - // would refuse to start, and saying otherwise costs the operator a snapshot. - partial := filepath.Join(dir, "partial.db-tasks.sqlite") - seedStoreResources(t, openTaskStore(t, partial), configPath) - if err := execRaw(t, partial, `DELETE FROM resources WHERE kind='provider-settings'`); err != nil { - t.Fatal(err) - } - code, stdout, stderr = runRecoveryCmd(t, "validate", "-db", partial, "-config", configPath) - if code != 0 { - t.Fatalf("validate refused a store missing a kind the State Store seeds; stderr = %q", stderr) - } - if count := storedResourceCount(t, stdout); count == 0 { - t.Errorf("validate must still check the kinds the store does hold; stdout = %q", stdout) - } } // The subcommands advertise -h as the way to read their flags, and the serve @@ -372,10 +161,7 @@ func TestRecoveryHelpExitsZero(t *testing.T) { func TestRecoveryValidateLeavesTheDaemonLogAlone(t *testing.T) { dir := t.TempDir() configPath, logFile := writeConfigWithLogFile(t, dir) - db := filepath.Join(dir, "archie.db-tasks.sqlite") - seedStoreResources(t, openTaskStore(t, db), configPath) - - code, _, stderr := runRecoveryCmd(t, "validate", "-db", db, "-config", configPath) + code, _, stderr := runRecoveryCmd(t, "validate", "-config", configPath) if code != 0 { t.Fatalf("validate exited %d: %s", code, stderr) } @@ -419,11 +205,10 @@ func TestRecoveryDefaultConfigResolvesWhereTheDaemonReads(t *testing.T) { if err := os.MkdirAll(configDir, 0o700); err != nil { t.Fatalf("create %s: %v", configDir, err) } - configPath := writeMinimalConfig(t, configDir) - db := filepath.Join(root, "archie.db-tasks.sqlite") - seedStoreResources(t, openTaskStore(t, db), configPath) - - code, stdout, stderr := runRecoveryCmd(t, "validate", "-db", db) + url := pgtest.URL(t) + pgstore.PoolAt(t, url) + configPath := writeConfigFor(t, configDir, url) + code, stdout, stderr := runRecoveryCmd(t, "validate") if !tc.wantOK { if code == 0 { t.Fatalf("validate exited 0 with no config at the resolved path %s: %s", configPath, stdout) @@ -434,125 +219,28 @@ func TestRecoveryDefaultConfigResolvesWhereTheDaemonReads(t *testing.T) { t.Fatalf("validate with no -config exited %d, so it did not read %s: %s", code, configPath, stderr) } if !strings.Contains(stdout, "stored resources validate") { - t.Errorf("validate reported %q, want the verdict on the store seeded from the resolved config", stdout) + t.Errorf("validate reported %q, want the verdict on the database the resolved config names", stdout) } }) } } -// validate exists to answer "would archied start against this file". Each case -// below is a state the daemon fails closed on, or a file it cannot read at all. +// validate exists to answer "would archied start against this database". A +// stored value that both gates refuse -- the write path stops it at Decode +// (workflow.ExecutionSettings.Validate rejects a negative limit) and boot stops +// on it too -- can only get here by bypassing the write path, which is exactly +// the state the operator has no path back from. func TestRecoveryValidateRefusesWhatTheDaemonRefuses(t *testing.T) { - newStore := func(t *testing.T) string { - t.Helper() - db := filepath.Join(t.TempDir(), "archie.db-tasks.sqlite") - openTaskStore(t, db) - return db + configPath, st := recoveryFixture(t) + seedResource(t, st, controlplane.WorkflowExecutionSettingsKind, + `{"max_model_tool_steps":-1,"max_runtime_seconds":60,"max_consecutive_gate_failures":3}`, "hand-edited") + code, _, stderr := runRecoveryCmd(t, "validate", "-config", configPath) + if code == 0 { + t.Fatal("validate accepted a stored resource the write path would refuse") + } + if !strings.Contains(stderr, controlplane.WorkflowExecutionSettingsKind) { + t.Errorf("refusal must name the resource kind; stderr = %q", stderr) } - - t.Run("forward_migrated_schema", func(t *testing.T) { - // A database written by a newer release is the state a rollback has to - // recognise before it hands the file to an older binary. - db := newStore(t) - if err := execRaw(t, db, `PRAGMA user_version = 99`); err != nil { - t.Fatal(err) - } - code, _, stderr := runRecoveryCmd(t, "validate", "-db", db) - if code == 0 { - t.Fatal("validate accepted a forward-migrated database") - } - if !strings.Contains(stderr, "newer than supported version") { - t.Errorf("refusal must name the schema version; stderr = %q", stderr) - } - }) - - t.Run("corrupt_file", func(t *testing.T) { - // A real database header over pages that are not a database. The magic - // is right, so this fails on the content rather than on the format, which - // is the shape a half-written or truncated store has. - db := filepath.Join(t.TempDir(), "archie.db-tasks.sqlite") - corrupt := append([]byte("SQLite format 3\x00"), bytes.Repeat([]byte{0xff}, 4096)...) - if err := os.WriteFile(db, corrupt, 0o600); err != nil { - t.Fatal(err) - } - code, _, stderr := runRecoveryCmd(t, "validate", "-db", db) - if code == 0 { - t.Fatal("validate accepted a corrupt database") - } - if !strings.Contains(stderr, db) { - t.Errorf("refusal must name the file; stderr = %q", stderr) - } - }) - - t.Run("not_a_database", func(t *testing.T) { - // Pointing -db at the wrong file is the common operator mistake, and the - // configured db_path is a different file from the task database the - // State Store owns. - db := filepath.Join(t.TempDir(), "archie.db") - if err := os.WriteFile(db, []byte("db_path, not the task database"), 0o600); err != nil { - t.Fatal(err) - } - code, _, stderr := runRecoveryCmd(t, "validate", "-db", db) - if code == 0 { - t.Fatal("validate accepted a file that is not a database") - } - if !strings.Contains(stderr, db) { - t.Errorf("refusal must name the file; stderr = %q", stderr) - } - }) - - t.Run("stored_resource_that_will_not_validate", func(t *testing.T) { - // A stored value that both gates refuse: the write path stops it at - // Decode (workflow.ExecutionSettings.Validate rejects a negative limit), - // and boot stops on it too -- startWorkflowExecutionSettings decodes the - // same document and exits 1. It can only get here by bypassing the write - // path, which is exactly the state the operator has no path back from. - db := newStore(t) - seedResource(t, openTaskStore(t, db), controlplane.WorkflowExecutionSettingsKind, - `{"max_model_tool_steps":-1,"max_runtime_seconds":60,"max_consecutive_gate_failures":3}`, "hand-edited") - code, _, stderr := runRecoveryCmd(t, "validate", "-db", db) - if code == 0 { - t.Fatal("validate accepted a stored resource the write path would refuse") - } - if !strings.Contains(stderr, controlplane.WorkflowExecutionSettingsKind) { - t.Errorf("refusal must name the resource kind; stderr = %q", stderr) - } - }) - - t.Run("missing_database", func(t *testing.T) { - db := newStore(t) - if err := os.Remove(db); err != nil { - t.Fatal(err) - } - code, _, stderr := runRecoveryCmd(t, "validate", "-db", db) - if code == 0 { - t.Fatal("validate accepted a database that does not exist") - } - if !strings.Contains(stderr, db) { - t.Errorf("refusal must name the file; stderr = %q", stderr) - } - }) - - t.Run("store_without_the_control_plane_table", func(t *testing.T) { - // A store written before the control plane existed holds no stored - // settings. The serving process creates the table on its next start, so - // refusing this file would send an operator to restore a snapshot for a - // database that would have started perfectly well. - dir := t.TempDir() - configPath := writeMinimalConfig(t, dir) - db := filepath.Join(dir, "archie.db-tasks.sqlite") - openTaskStore(t, db) - if err := execRaw(t, db, `DROP TABLE resources`); err != nil { - t.Fatal(err) - } - code, stdout, stderr := runRecoveryCmd(t, "validate", "-db", db, "-config", configPath) - if code != 0 { - t.Fatalf("validate exited %d: %s", code, stderr) - } - if !strings.Contains(stdout, "0 stored resources validate") { - t.Errorf("validate must report that there was nothing stored to check; stdout = %q", stdout) - } - }) } // rollback is the one operation that closes the documented gap: with the State @@ -560,13 +248,11 @@ func TestRecoveryValidateRefusesWhatTheDaemonRefuses(t *testing.T) { // ordinary replace, so no rollback RPC is needed and the rollback itself is // audited as one more revision. func TestRecoveryRollbackReplaysTheRevisionThroughReplace(t *testing.T) { - dir := t.TempDir() - db := filepath.Join(dir, "archie.db-tasks.sqlite") - st := openTaskStore(t, db) + configPath, st := recoveryFixture(t) seedResource(t, st, controlplane.ModelRoleAssignmentsKind, `{"implement":"anthropic/claude"}`, "first") seedResource(t, st, controlplane.ModelRoleAssignmentsKind, `{"implement":"openai/gpt"}`, "second") - code, stdout, stderr := runRecoveryCmd(t, "rollback", "-db", db, "-kind", controlplane.ModelRoleAssignmentsKind) + code, stdout, stderr := runRecoveryCmd(t, "rollback", "-config", configPath, "-kind", controlplane.ModelRoleAssignmentsKind) if code != 0 { t.Fatalf("rollback exited %d: %s", code, stderr) } @@ -598,14 +284,12 @@ func TestRecoveryRollbackReplaysTheRevisionThroughReplace(t *testing.T) { // The revision to restore may be named, which is how an operator reaches past // the most recent change without replaying it first. func TestRecoveryRollbackRestoresANamedRevision(t *testing.T) { - dir := t.TempDir() - db := filepath.Join(dir, "archie.db-tasks.sqlite") - st := openTaskStore(t, db) + configPath, st := recoveryFixture(t) seedResource(t, st, controlplane.ModelRoleAssignmentsKind, `{"implement":"anthropic/claude"}`, "first") seedResource(t, st, controlplane.ModelRoleAssignmentsKind, `{"implement":"openai/gpt"}`, "second") seedResource(t, st, controlplane.ModelRoleAssignmentsKind, `{"implement":"google/gemini"}`, "third") - code, _, stderr := runRecoveryCmd(t, "rollback", "-db", db, "-kind", controlplane.ModelRoleAssignmentsKind, "-revision", "1") + code, _, stderr := runRecoveryCmd(t, "rollback", "-config", configPath, "-kind", controlplane.ModelRoleAssignmentsKind, "-revision", "1") if code != 0 { t.Fatalf("rollback exited %d: %s", code, stderr) } @@ -619,10 +303,9 @@ func TestRecoveryRollbackRestoresANamedRevision(t *testing.T) { } func TestRecoveryRollbackRefusesWhatItCannotReplay(t *testing.T) { - newStore := func(t *testing.T, revisions int) string { + newStore := func(t *testing.T, revisions int) (string, *pgstore.TaskDB) { t.Helper() - db := filepath.Join(t.TempDir(), "archie.db-tasks.sqlite") - st := openTaskStore(t, db) + configPath, st := recoveryFixture(t) for i := range revisions { value := `{"implement":"anthropic/claude"}` if i > 0 { @@ -630,12 +313,12 @@ func TestRecoveryRollbackRefusesWhatItCannotReplay(t *testing.T) { } seedResource(t, st, controlplane.ModelRoleAssignmentsKind, value, "seed") } - return db + return configPath, st } t.Run("unknown_kind", func(t *testing.T) { - db := newStore(t, 2) - code, _, stderr := runRecoveryCmd(t, "rollback", "-db", db, "-kind", "not-a-resource") + configPath, _ := newStore(t, 2) + code, _, stderr := runRecoveryCmd(t, "rollback", "-config", configPath, "-kind", "not-a-resource") if code == 0 { t.Fatal("rollback of an unknown resource kind succeeded") } @@ -645,8 +328,8 @@ func TestRecoveryRollbackRefusesWhatItCannotReplay(t *testing.T) { }) t.Run("no_earlier_revision", func(t *testing.T) { - db := newStore(t, 1) - code, _, stderr := runRecoveryCmd(t, "rollback", "-db", db, "-kind", controlplane.ModelRoleAssignmentsKind) + configPath, _ := newStore(t, 1) + code, _, stderr := runRecoveryCmd(t, "rollback", "-config", configPath, "-kind", controlplane.ModelRoleAssignmentsKind) if code == 0 { t.Fatal("rollback with no earlier revision succeeded") } @@ -656,8 +339,8 @@ func TestRecoveryRollbackRefusesWhatItCannotReplay(t *testing.T) { }) t.Run("current_revision", func(t *testing.T) { - db := newStore(t, 2) - code, _, stderr := runRecoveryCmd(t, "rollback", "-db", db, "-kind", controlplane.ModelRoleAssignmentsKind, "-revision", "2") + configPath, _ := newStore(t, 2) + code, _, stderr := runRecoveryCmd(t, "rollback", "-config", configPath, "-kind", controlplane.ModelRoleAssignmentsKind, "-revision", "2") if code == 0 { t.Fatal("rollback of the current revision succeeded") } @@ -667,14 +350,18 @@ func TestRecoveryRollbackRefusesWhatItCannotReplay(t *testing.T) { }) t.Run("live_state_store", func(t *testing.T) { - db := newStore(t, 2) - holdStoreOwnership(t, db) - code, _, stderr := runRecoveryCmd(t, "rollback", "-db", db, "-kind", controlplane.ModelRoleAssignmentsKind) + configPath, st := newStore(t, 2) + claim, err := postgres.AcquireOwnership(t.Context(), st.Pool, postgres.OwnerStateStore) + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = claim.Release(t.Context()) }) + code, _, stderr := runRecoveryCmd(t, "rollback", "-config", configPath, "-kind", controlplane.ModelRoleAssignmentsKind) if code == 0 { t.Fatal("rollback against a live State Store succeeded") } - if !strings.Contains(stderr, "owned by another process") { - t.Errorf("refusal must say the database is owned by another process; stderr = %q", stderr) + if !strings.Contains(stderr, "stop the State Store") { + t.Errorf("refusal must say to stop the State Store; stderr = %q", stderr) } }) } @@ -683,7 +370,7 @@ func TestRecoveryRollbackRefusesWhatItCannotReplay(t *testing.T) { // an operator who mistyped a command watching a server start instead. func TestRecoveryRejectsAnUnknownSubcommand(t *testing.T) { var stdout, stderr bytes.Buffer - code := runRecovery([]string{"backp", "-db", "x"}, &stdout, &stderr) + code := runRecovery([]string{"backp", "-out", "x"}, &stdout, &stderr) if code == 0 { t.Fatal("an unknown subcommand exited 0") } @@ -696,7 +383,9 @@ func TestRecoveryRejectsAnUnknownSubcommand(t *testing.T) { // destination, which only the daemon may bring into existence. func writeConfigWithLogFile(t *testing.T, dir string) (string, string) { t.Helper() - configPath := writeMinimalConfig(t, dir) + url := pgtest.URL(t) + pgstore.PoolAt(t, url) + configPath := writeConfigFor(t, dir, url) logFile := filepath.Join(dir, "logs", "archied.log") f, err := os.OpenFile(configPath, os.O_APPEND|os.O_WRONLY, 0o600) if err != nil { @@ -725,7 +414,7 @@ func writeConfigWithLogFile(t *testing.T, dir string) (string, string) { // registers the same set itself rather than an empty manager: the definitions // are decoded with the vocabulary the served path validates against, which is // what makes the seeded values the ones validate is asked about. -func seedStoreResources(t *testing.T, st *store.Store, configPath string) { +func seedStoreResources(t *testing.T, st *pgstore.TaskDB, configPath string) { t.Helper() doc, err := configuration.New(nil).Resolve(configPath, "") if err != nil { @@ -772,7 +461,7 @@ func storedResourceCount(t *testing.T, stdout string) int { // from the label and the revision it produces: the store deduplicates a // repeated request ID, so a fixed one would make the second write of a series // a silent no-op. -func seedResource(t *testing.T, st *store.Store, kind, value, label string) { +func seedResource(t *testing.T, st *pgstore.TaskDB, kind, value, label string) { t.Helper() current, err := st.Resource(t.Context(), kind) expected := int64(0) @@ -787,23 +476,10 @@ func seedResource(t *testing.T, st *store.Store, kind, value, label string) { if err != nil { t.Fatal(err) } - if _, err := st.PutResource(t.Context(), store.ResourceWrite{ + if _, err := st.PutResource(t.Context(), storecontract.ResourceWrite{ Kind: kind, Value: encoded, Actor: label, Source: "test", RequestID: fmt.Sprintf("%s-%d", label, expected+1), ExpectedVersion: expected, }); err != nil { t.Fatalf("seed resource %s: %v", kind, err) } } - -// execRaw runs one statement against the database file the way an operator -// editing a broken store would, bypassing every check the store applies. -func execRaw(t *testing.T, path, statement string) error { - t.Helper() - db, err := sql.Open("sqlite", path) - if err != nil { - return err - } - defer func() { _ = db.Close() }() - _, err = db.ExecContext(t.Context(), statement) - return err -} diff --git a/cmd/archie-ui/architecture_test.go b/cmd/archie-ui/architecture_test.go index 96ab4fd1e..e8ad16a66 100644 --- a/cmd/archie-ui/architecture_test.go +++ b/cmd/archie-ui/architecture_test.go @@ -28,7 +28,9 @@ type bannedCategory struct { var deletionGate = []bannedCategory{ {"SQL/store implementation", []string{ "modernc.org/sqlite", - modulePath + "internal/store", + "github.com/jackc/pgx", + modulePath + "internal/infrastructure/postgres", + modulePath + "internal/infrastructure/legacyread", }}, {"daemon runtime", []string{ modulePath + "internal/daemon", diff --git a/cmd/archie-ui/main_test.go b/cmd/archie-ui/main_test.go index 60a902064..aba5c49ed 100644 --- a/cmd/archie-ui/main_test.go +++ b/cmd/archie-ui/main_test.go @@ -36,11 +36,11 @@ import ( "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/domain/health" "github.com/samcharles93/archie-core/internal/domain/messaging" + "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/domain/taskactions" - "github.com/samcharles93/archie-core/internal/infrastructure/edastore" "github.com/samcharles93/archie-core/internal/infrastructure/gatewayrpc" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/infrastructure/staterpc" - "github.com/samcharles93/archie-core/internal/store" "github.com/samcharles93/archie-core/internal/taskstate" "github.com/samcharles93/archie-core/internal/webui" ) @@ -484,12 +484,9 @@ func streamChat(t *testing.T, d dashboard, prompt string) []chatFrame { // that forgets to publish a field, which is the failure mode this covers: // chat.show_tool_calls, the operator name and the channel flag all reach the // extracted process through this projection and nowhere else (GitHub #821). -func seedStore(t *testing.T, dir string) *store.Store { +func seedStore(t *testing.T, dir string) *pgstore.TaskDB { t.Helper() - st, err := store.Open(t.Context(), filepath.Join(dir, "tasks.sqlite")) - if err != nil { - t.Fatalf("open store: %v", err) - } + st := pgstore.Open(t) t.Cleanup(func() { _ = st.Close() }) if _, err := st.EnqueueIssue(t.Context(), "acme", "widget", 7, "smoke task", "body", "", ""); err != nil { @@ -528,13 +525,13 @@ func daemonConfig(showToolCalls bool) config.Config { // writes the result to the store the UI process reads it back from. The UI // process holds no configuration, so this is the only path by which a setting // reaches its pages. -func publishConfig(t *testing.T, st *store.Store, cfg config.Config) { +func publishConfig(t *testing.T, st *pgstore.TaskDB, cfg config.Config) { t.Helper() document, err := json.Marshal(webui.BuildConfigView(webui.ConfigViewInput{Config: cfg})) if err != nil { t.Fatalf("render the configuration projection: %v", err) } - if err := st.PutConfigSnapshot(t.Context(), store.ConfigSnapshot{ + if err := st.PutConfigSnapshot(t.Context(), storecontract.ConfigSnapshot{ Schema: webui.ConfigViewSchema, Document: document, }); err != nil { t.Fatalf("publish config snapshot: %v", err) @@ -555,10 +552,7 @@ func publishConfig(t *testing.T, st *store.Store, cfg config.Config) { // that test's page underneath it. func TestUIProcessLinksMultiIdentityTaskRowsToTheirOwningForge(t *testing.T) { dir := t.TempDir() - st, err := store.Open(t.Context(), filepath.Join(dir, "tasks.sqlite")) - if err != nil { - t.Fatalf("open store: %v", err) - } + st := pgstore.Open(t) t.Cleanup(func() { _ = st.Close() }) // One task carrying its identity (name resolves it), one without an @@ -595,14 +589,14 @@ func TestUIProcessLinksMultiIdentityTaskRowsToTheirOwningForge(t *testing.T) { if err != nil { t.Fatal(err) } - if err := st.PutConfigSnapshot(t.Context(), store.ConfigSnapshot{ + if err := st.PutConfigSnapshot(t.Context(), storecontract.ConfigSnapshot{ Schema: webui.ConfigViewSchema, Document: published, }); err != nil { t.Fatalf("publish config snapshot: %v", err) } stateTarget, stopState := serveGRPC(t, func(r grpc.ServiceRegistrar) { - eda := edastore.OpenTest(t) + eda := pgstore.EDA(t, nil) staterpc.RegisterServer(r, staterpc.Deps{ Tasks: st, Captures: eda, BindingDispatcher: eda, ConfigSnapshots: st, Log: slog.New(slog.DiscardHandler), @@ -659,7 +653,7 @@ func TestUIProcessServesTheDashboardAgainstLiveDependencies(t *testing.T) { gateway := &fakeGateway{} stateTarget, stopState := serveGRPC(t, func(r grpc.ServiceRegistrar) { - eda := edastore.OpenTest(t) + eda := pgstore.EDA(t, nil) staterpc.RegisterServer(r, staterpc.Deps{ Tasks: st, Captures: eda, BindingDispatcher: eda, ConfigSnapshots: st, Log: slog.New(slog.DiscardHandler), diff --git a/cmd/archie-ui/pgtest_test.go b/cmd/archie-ui/pgtest_test.go new file mode 100644 index 000000000..af786180f --- /dev/null +++ b/cmd/archie-ui/pgtest_test.go @@ -0,0 +1,10 @@ +package main + +import ( + "os" + "testing" + + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest" +) + +func TestMain(m *testing.M) { os.Exit(pgtest.Main(m)) } diff --git a/go.mod b/go.mod index 67a138e0d..9ae959d2c 100644 --- a/go.mod +++ b/go.mod @@ -11,7 +11,6 @@ require ( github.com/ProtonMail/go-crypto v1.4.1 // indirect github.com/antithesishq/antithesis-sdk-go v0.8.0 // indirect github.com/antlr4-go/antlr/v4 v4.13.1 // indirect - github.com/asaskevich/govalidator v0.0.0-20230301143203-a9d515a09cc2 // indirect github.com/cenkalti/backoff/v4 v4.3.0 // indirect github.com/cespare/xxhash/v2 v2.3.0 // indirect github.com/cloudflare/circl v1.6.5 // indirect @@ -21,30 +20,23 @@ require ( github.com/containerd/platforms v0.2.1 // indirect github.com/cpuguy83/dockercfg v0.3.2 // indirect github.com/davidmz/go-pageant v1.0.2 // indirect - github.com/disintegration/imaging v1.6.2 // indirect github.com/distribution/reference v0.6.0 // indirect github.com/docker/go-connections v0.8.1 // indirect github.com/docker/go-units v0.5.0 // indirect - github.com/domodwyer/mailyak/v3 v3.6.2 // indirect github.com/dustin/go-humanize v1.1.0 // indirect github.com/ebitengine/purego v0.10.1 // indirect github.com/emirpasic/gods v1.18.1 // indirect - github.com/fatih/color v1.19.0 // indirect github.com/felixge/httpsnoop v1.1.0 // indirect - github.com/fsnotify/fsnotify v1.10.1 // indirect - github.com/gabriel-vasile/mimetype v1.4.15 // indirect - github.com/ganigeorgiev/fexpr v0.6.0 // indirect github.com/go-fed/httpsig v1.1.0 // indirect github.com/go-git/gcfg/v2 v2.0.2 // indirect github.com/go-json-experiment/json v0.0.0-20260623181947-01eb4420fa68 // indirect github.com/go-logr/logr v1.4.4 // indirect github.com/go-logr/stdr v1.2.2 // indirect github.com/go-ole/go-ole v1.3.0 // indirect - github.com/golang-jwt/jwt/v5 v5.3.1 // indirect github.com/google/go-querystring v1.2.0 // indirect github.com/google/go-tpm v0.9.8 // indirect + github.com/google/pprof v0.0.0-20260902005441-ca85771921e4 // indirect github.com/hashicorp/go-version v1.9.0 // indirect - github.com/inconshreveable/mousetrap v1.1.0 // indirect github.com/jackc/pgpassfile v1.0.0 // indirect github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect github.com/jackc/puddle/v2 v2.2.2 // indirect @@ -53,7 +45,6 @@ require ( github.com/klauspost/cpuid/v2 v2.4.0 // indirect github.com/lufia/plan9stats v0.0.0-20260330125221-c963978e514e // indirect github.com/magiconair/properties v1.8.10 // indirect - github.com/mattn/go-colorable v0.1.15 // indirect github.com/mattn/go-isatty v0.0.24 // indirect github.com/mfridman/interpolate v0.0.2 // indirect github.com/minio/highwayhash v1.0.4 // indirect @@ -72,16 +63,12 @@ require ( github.com/opencontainers/image-spec v1.1.1 // indirect github.com/pjbgf/sha1cd v0.6.0 // indirect github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c // indirect - github.com/pocketbase/ozzo-validation/v4 v4.3.0 // indirect github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 // indirect github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect github.com/sergi/go-diff v1.4.0 // indirect github.com/sethvargo/go-retry v0.4.0 // indirect github.com/shirou/gopsutil/v4 v4.26.6 // indirect github.com/sirupsen/logrus v1.9.4 // indirect - github.com/spf13/cast v1.10.0 // indirect - github.com/spf13/cobra v1.10.2 // indirect - github.com/spf13/pflag v1.0.10 // indirect github.com/stretchr/testify v1.12.1 // indirect github.com/tklauser/go-sysconf v0.4.0 // indirect github.com/tklauser/numcpus v0.12.0 // indirect @@ -95,7 +82,6 @@ require ( go.yaml.in/yaml/v3 v3.0.5 // indirect golang.org/x/crypto v0.57.0 // indirect golang.org/x/exp v0.0.0-20260908205506-85c1c2202aba // indirect - golang.org/x/image v0.46.0 // indirect golang.org/x/sync v0.23.0 // indirect golang.org/x/sys v0.48.0 // indirect golang.org/x/text v0.42.0 // indirect @@ -123,8 +109,6 @@ require ( github.com/moby/moby/client v0.6.0 github.com/nats-io/nats-server/v2 v2.15.0 github.com/nats-io/nats.go v1.54.0 - github.com/pocketbase/dbx v1.12.0 - github.com/pocketbase/pocketbase v0.40.4 github.com/pressly/goose/v3 v3.28.0 github.com/samcharles93/ai-sdk v0.1.39 github.com/testcontainers/testcontainers-go v0.44.0 diff --git a/go.sum b/go.sum index 1a7659729..2eff6127e 100644 --- a/go.sum +++ b/go.sum @@ -6,8 +6,6 @@ code.gitea.io/sdk/gitea v0.25.1 h1:yywxWwoV+SdjHtbC6unBiXojWdZOtoHuGhEazEXeWuE= code.gitea.io/sdk/gitea v0.25.1/go.mod h1:uDFWYBU8dgZsgOHwe6C/6olxvf8FHguNB3wW1i83fgg= dario.cat/mergo v1.0.2 h1:85+piFYR1tMbRrLcDwR18y4UKJ3aH1Tbzi24VRW1TK8= dario.cat/mergo v1.0.2/go.mod h1:E/hbnu0NxMFBjpMIE34DRGLWqDy0g5FuKDhCb31ngxA= -filippo.io/edwards25519 v1.2.0 h1:crnVqOiS4jqYleHd9vaKZ+HKtHfllngJIiOpNpoJsjo= -filippo.io/edwards25519 v1.2.0/go.mod h1:xzAOLCNug/yB62zG1bQ8uziwrIqIuxhctzJT18Q77mc= github.com/42wim/httpsig v1.2.4 h1:mI5bH0nm4xn7K18fo1K3okNDRq8CCJ0KbBYWyA6r8lU= github.com/42wim/httpsig v1.2.4/go.mod h1:yKsYfSyTBEohkPik224QPFylmzEBtda/kjyIAJjh3ps= github.com/AdaLogics/go-fuzz-headers v0.0.0-20240806141605-e8a1dd7889d6 h1:He8afgbRMd7mFxO99hRNu+6tazq8nFF9lIwo9JFroBk= @@ -28,9 +26,6 @@ github.com/antlr4-go/antlr/v4 v4.13.1 h1:SqQKkuVZ+zWkMMNkjy5FZe5mr5WURWnlpmOuzYW github.com/antlr4-go/antlr/v4 v4.13.1/go.mod h1:GKmUxMtwp6ZgGwZSva4eWPC5mS6vUAmOABFgjdkM7Nw= github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5 h1:0CwZNZbxp69SHPdPJAN/hZIm0C4OItdklCFmMRWYpio= github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5/go.mod h1:wHh0iHkYZB8zMSxRWpUBQtwG5a7fFgvEO+odwuTv2gs= -github.com/asaskevich/govalidator v0.0.0-20200108200545-475eaeb16496/go.mod h1:oGkLhpf+kjZl6xBf758TQhh5XrAeiJv/7FRz/2spLIg= -github.com/asaskevich/govalidator v0.0.0-20230301143203-a9d515a09cc2 h1:DklsrG3dyBCFEj5IhUbnKptjxatkF07cF2ak3yi77so= -github.com/asaskevich/govalidator v0.0.0-20230301143203-a9d515a09cc2/go.mod h1:WaHUgvxTVq04UNunO+XhnAqY/wQc+bxr74GqbsZ/Jqw= github.com/cenkalti/backoff/v4 v4.3.0 h1:MyRJ/UdXutAwSAT+s3wNd7MfTIcy71VQueUuFK343L8= github.com/cenkalti/backoff/v4 v4.3.0/go.mod h1:Y3VNntkOUPxTVeUxJ/G5vcM//AlwfmyYozVcomhLiZE= github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs= @@ -49,41 +44,26 @@ github.com/coreos/go-oidc/v3 v3.21.0 h1:wZo4Q9Pum8dYEj0eMUPrqR+kvuGkeUplbLpNCkBq github.com/coreos/go-oidc/v3 v3.21.0/go.mod h1:DYCf24+ncYi+XkIH97GY1+dqoRlbaSI26KVTCI9SrY4= github.com/cpuguy83/dockercfg v0.3.2 h1:DlJTyZGBDlXqUZ2Dk2Q3xHs/FtnooJJVaad2S9GKorA= github.com/cpuguy83/dockercfg v0.3.2/go.mod h1:sugsbF4//dDlL/i+S+rtpIWp+5h0BHJHfjj5/jFyUJc= -github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g= github.com/creack/pty v1.1.24 h1:bJrF4RRfyJnbTJqzRLHzcGaZK1NeM5kTC9jGgovnR1s= github.com/creack/pty v1.1.24/go.mod h1:08sCNb52WyoAwi2QDyzUCTgcvVFhUzewun7wtTfvcwE= github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/davidmz/go-pageant v1.0.2 h1:bPblRCh5jGU+Uptpz6LgMZGD5hJoOt7otgT454WvHn0= github.com/davidmz/go-pageant v1.0.2/go.mod h1:P2EDDnMqIwG5Rrp05dTRITj9z2zpGcD9efWSkTNKLIE= -github.com/disintegration/imaging v1.6.2 h1:w1LecBlG2Lnp8B3jk5zSuNqd7b4DXhcjwek1ei82L+c= -github.com/disintegration/imaging v1.6.2/go.mod h1:44/5580QXChDfwIclfc/PCwrr44amcmDAg8hxG0Ewe4= github.com/distribution/reference v0.6.0 h1:0IXCQ5g4/QMHHkarYzh5l+u8T3t73zM5QvfrDyIgxBk= github.com/distribution/reference v0.6.0/go.mod h1:BbU0aIcezP1/5jX/8MP0YiH4SdvB5Y4f/wlDRiLyi3E= github.com/docker/go-connections v0.8.1 h1:JibmG5hULs5qXSr/cp/w3Pw5fZuStt4MOHMUExb29/M= github.com/docker/go-connections v0.8.1/go.mod h1:no1qkHdjq7kLMGUXYAduOhYPSJxxvgWBh7ogVvptn3Q= github.com/docker/go-units v0.5.0 h1:69rxXcBk27SvSaaxTtLh/8llcHD8vYHT7WSdRZ/jvr4= github.com/docker/go-units v0.5.0/go.mod h1:fgPhTUdO+D/Jk86RDLlptpiXQzgHJF7gydDDbaIK4Dk= -github.com/domodwyer/mailyak/v3 v3.6.2 h1:x3tGMsyFhTCaxp6ycgR0FE/bu5QiNp+hetUuCOBXMn8= -github.com/domodwyer/mailyak/v3 v3.6.2/go.mod h1:lOm/u9CyCVWHeaAmHIdF4RiKVxKUT/H5XX10lIKAL6c= github.com/dustin/go-humanize v1.1.0 h1:dbKTrvD0klcbBV/h4AWJdMuZogJACoMlvWIWZ5b2xWg= github.com/dustin/go-humanize v1.1.0/go.mod h1:hc1CvRkJMsgxqjmjMQF3QNRAZBwY8AXBAzKYoSX9sFI= github.com/ebitengine/purego v0.10.1 h1:dewVBCBT2GaMu1SrNTYxQhgQBethzfhiwvZiLGP/qyY= github.com/ebitengine/purego v0.10.1/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ= github.com/emirpasic/gods v1.18.1 h1:FXtiHYKDGKCW2KzwZKx0iC0PQmdlorYgdFG9jPXJ1Bc= github.com/emirpasic/gods v1.18.1/go.mod h1:8tpGGwCnJ5H4r6BWwaV6OrWmMoPhUl5jm/FMNAnJvWQ= -github.com/fatih/color v1.19.0 h1:Zp3PiM21/9Ld6FzSKyL5c/BULoe/ONr9KlbYVOfG8+w= -github.com/fatih/color v1.19.0/go.mod h1:zNk67I0ZUT1bEGsSGyCZYZNrHuTkJJB+r6Q9VuMi0LE= github.com/felixge/httpsnoop v1.1.0 h1:3YtUj32ZZkqZtt3sZZsClsymw/QDuVfpNhoA31zeORc= github.com/felixge/httpsnoop v1.1.0/go.mod h1:Zqxgdd+1Rkcz8euOqdr7lqgCRJztwr5hp9vDSi5UZCE= -github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHkI4W8= -github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0= -github.com/fsnotify/fsnotify v1.10.1 h1:b0/UzAf9yR5rhf3RPm9gf3ehBPpf0oZKIjtpKrx59Ho= -github.com/fsnotify/fsnotify v1.10.1/go.mod h1:TLheqan6HD6GBK6PrDWyDPBaEV8LspOxvPSjC+bVfgo= -github.com/gabriel-vasile/mimetype v1.4.15 h1:05iP/CYtZ/w455R/KZM6rZ5ieAdh99UPtd+d3YzLmaI= -github.com/gabriel-vasile/mimetype v1.4.15/go.mod h1:azpTcoLcDZRNgFou5j+APrqQx9HqVPWa6ijYQIIVswQ= -github.com/ganigeorgiev/fexpr v0.6.0 h1:Fza3O/QMBKEudUvxV862qe6GjxM60GJjjKytdp+VQus= -github.com/ganigeorgiev/fexpr v0.6.0/go.mod h1:RyGiGqmeXhEQ6+mlGdnUleLHgtzzu/VGO2WtJkF5drE= github.com/gliderlabs/ssh v0.3.8 h1:a4YXD1V7xMF9g5nTkdfnja3Sxy1PVDCj1Zg4Wb8vY6c= github.com/gliderlabs/ssh v0.3.8/go.mod h1:xYoytBv1sV0aL3CavoDuJIQNURXkkfPA/wxQ1pL1fAU= github.com/go-fed/httpsig v1.1.0 h1:9M+hb0jkEICD8/cAiNqEB66R87tTINszBRTjwjQzWcI= @@ -108,14 +88,8 @@ github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre github.com/go-ole/go-ole v1.2.6/go.mod h1:pprOEPIfldk/42T2oK7lQ4v4JSDwmV0As9GaiUsvbm0= github.com/go-ole/go-ole v1.3.0 h1:Dt6ye7+vXGIKZ7Xtk4s6/xVdGDQynvom7xCFEdWr6uE= github.com/go-ole/go-ole v1.3.0/go.mod h1:5LS6F96DhAwUc7C+1HLexzMXY1xGRSryjyPPKW6zv78= -github.com/go-sql-driver/mysql v1.4.1/go.mod h1:zAC/RDZ24gD3HViQzih4MyKcchzm+sOG5ZlKdlhCg5w= -github.com/go-sql-driver/mysql v1.10.0 h1:Q+1LV8DkHJvSYAdR83XzuhDaTykuDx0l6fkXxoWCWfw= -github.com/go-sql-driver/mysql v1.10.0/go.mod h1:M+cqaI7+xxXGG9swrdeUIoPG3Y3KCkF0pZej+SK+nWk= github.com/go-telegram/bot v1.27.0 h1:PG9yBDzM8O26oUerE9SZwWlHon4RpH8WcNslZ7CEZmE= github.com/go-telegram/bot v1.27.0/go.mod h1:i2TRs7fXWIeaceF3z7KzsMt/he0TwkVC680mvdTFYeM= -github.com/golang-jwt/jwt/v5 v5.3.1 h1:kYf81DTWFe7t+1VvL7eS+jKFVWaUnK9cB1qbwn63YCY= -github.com/golang-jwt/jwt/v5 v5.3.1/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE= -github.com/golang/protobuf v1.3.1/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U= github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek= github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps= github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY= @@ -135,8 +109,6 @@ github.com/hashicorp/go-version v1.9.0 h1:CeOIz6k+LoN3qX9Z0tyQrPtiB1DFYRPfCIBtaX github.com/hashicorp/go-version v1.9.0/go.mod h1:fltr4n8CU8Ke44wwGCBoEymUuxUHl09ZGVZPK5anwXA= github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k= github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM= -github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8= -github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM= github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg= github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo= @@ -164,8 +136,6 @@ github.com/lufia/plan9stats v0.0.0-20260330125221-c963978e514e h1:Q6MvJtQK/iRcRt github.com/lufia/plan9stats v0.0.0-20260330125221-c963978e514e/go.mod h1:autxFIvghDt3jPTLoqZ9OZ7s9qTGNAWmYCjVFWPX/zg= github.com/magiconair/properties v1.8.10 h1:s31yESBquKXCV9a/ScB3ESkOjUYYv+X0rg8SYxI99mE= github.com/magiconair/properties v1.8.10/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0= -github.com/mattn/go-colorable v0.1.15 h1:+u9SLTRGnXv73cEsnsmoZBom+dMU88B2M0aDcWy0/jY= -github.com/mattn/go-colorable v0.1.15/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8= github.com/mattn/go-isatty v0.0.24 h1:tGZZoVgT/KiqK1c8ocVLeDS8BSWMRd47J3Lbz7vsReI= github.com/mattn/go-isatty v0.0.24/go.mod h1:nMCL3Zebbrt45jsMDgnfIwz6ydEQApk5oEI3HqDio6A= github.com/mdelapenya/tlscert v0.2.0 h1:7H81W6Z/4weDvZBNOfQte5GpIMo0lGYEeWbkGp5LJHI= @@ -213,12 +183,6 @@ github.com/pjbgf/sha1cd v0.6.0/go.mod h1:lhpGlyHLpQZoxMv8HcgXvZEhcGs0PG/vsZnEJ7H github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c h1:+mdjkGKdHQG3305AYmdv1U2eRNDiU2ErMBj1gwrq8eQ= github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c/go.mod h1:7rwL4CYBLnjLxUqIJNnCWiEdr3bn6IUYi15bNlnbCCU= github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= -github.com/pocketbase/dbx v1.12.0 h1:/oLErM+A0b4xI0PWTGPqSDVjzix48PqI/bng2l0PzoA= -github.com/pocketbase/dbx v1.12.0/go.mod h1:xXRCIAKTHMgUCyCKZm55pUOdvFziJjQfXaWKhu2vhMs= -github.com/pocketbase/ozzo-validation/v4 v4.3.0 h1:uKBDVma7bZqgR2a6AwE+k9hkuDFfiZMpBHQdZ1z3iQs= -github.com/pocketbase/ozzo-validation/v4 v4.3.0/go.mod h1:6XNjSTw/Jb2F8LOkKO3oyzIWExbrGiYoS4uVxVwz90g= -github.com/pocketbase/pocketbase v0.40.4 h1:0SvSUreR3NhUMCs9LchE59oEG53efZ3cKiMGyAGBN9U= -github.com/pocketbase/pocketbase v0.40.4/go.mod h1:2mU+80FLiY1fb13WZRg8Xx/lKg4nTjgKVJMigyRH6k0= github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 h1:o4JXh1EVt9k/+g42oCprj/FisM4qX9L3sZB3upGN2ZU= github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE= github.com/pressly/goose/v3 v3.28.0 h1:D2M+iL31GmpZxSHOhX8mqyqAT3CXnokUmm0eKoSP+Vc= @@ -227,7 +191,6 @@ github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo= github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ= github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc= -github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= github.com/samcharles93/ai-sdk v0.1.39 h1:gbNPYeA27MifReCruBiqMgb4fFSjCDi1Zv57a9bo0Vo= github.com/samcharles93/ai-sdk v0.1.39/go.mod h1:u4zrQ9/Q58L5mNEut4bNQ1ks+RCKq71LN5EDz2N/0Zk= github.com/sergi/go-diff v1.4.0 h1:n/SP9D5ad1fORl+llWyN+D6qoUETXNZARKjyY2/KVCw= @@ -238,13 +201,6 @@ github.com/shirou/gopsutil/v4 v4.26.6 h1:Mzr/npDtQC/xpeEuQKHZt8Zo9CmPvhTj8nkR8w5 github.com/shirou/gopsutil/v4 v4.26.6/go.mod h1:LZ6ewCSkBqUpvSOf+LsTGnRinC6iaNUNMGBtDkJBaLQ= github.com/sirupsen/logrus v1.9.4 h1:TsZE7l11zFCLZnZ+teH4Umoq5BhEIfIzfRDZ1Uzql2w= github.com/sirupsen/logrus v1.9.4/go.mod h1:ftWc9WdOfJ0a92nsE2jF5u5ZwH8Bv2zdeOC42RjbV2g= -github.com/spf13/cast v1.10.0 h1:h2x0u2shc1QuLHfxi+cTJvs30+ZAHOGRic8uyGTDWxY= -github.com/spf13/cast v1.10.0/go.mod h1:jNfB8QC9IA6ZuY2ZjDp0KtFO2LZZlg4S/7bzP6qqeHo= -github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU= -github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4= -github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg= -github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk= -github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg= github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= github.com/stretchr/objx v0.5.3 h1:jmXUvGomnU1o3W/V5h2VEradbpJDwGrzugQQvL0POH4= github.com/stretchr/objx v0.5.3/go.mod h1:rDQraq+vQZU7Fde9LOZLr8Tax6zZvy4kuNKF+QYS+U0= @@ -287,7 +243,6 @@ go.opentelemetry.io/otel/trace v1.46.0 h1:OULy7ccdJnZtJ0UDYFOIGaCmiWzJ8Vi2G/Rsu6 go.opentelemetry.io/otel/trace v1.46.0/go.mod h1:J7GAXweO77XSFkB/rmAqk9D6ihszhFjLU+d9WuUxDLI= go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0= go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y= -go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg= go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw= go.yaml.in/yaml/v3 v3.0.5/go.mod h1:HVTZu1O7/Vkt2N+BFy8Zza+lnLsABggaTM2ZpNIGuKg= golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w= @@ -297,13 +252,9 @@ golang.org/x/crypto v0.57.0 h1:3ZVCjf8Ggz7zneR/EHRVx68Ctf+2pmIMP2UFhh9cC6M= golang.org/x/crypto v0.57.0/go.mod h1:Fdz0i5U6CoizGwLda9DttjSk6qlZo25zYNtR+ycvuZA= golang.org/x/exp v0.0.0-20260908205506-85c1c2202aba h1:Ck8QetSgk912qxWLMCKxd0in+aiyBQyDSMae6e/xmpU= golang.org/x/exp v0.0.0-20260908205506-85c1c2202aba/go.mod h1:50RgIsmK7OwqzTTeqcSXQW8SswW0o8fRcDxmqGluJ8E= -golang.org/x/image v0.0.0-20191009234506-e7c1f5e7dbb8/go.mod h1:FeLwcggjj3mMvU+oOTbSwawSJRM1uh48EjtB4UJZlP0= -golang.org/x/image v0.46.0 h1:b1+oYj0Jbp6K5MDT4i4/eZpYlk3V8SJhhDKh6LBHAyQ= -golang.org/x/image v0.46.0/go.mod h1:3B3W05VGVQyuXucLINLjXKrqISASfi4Xj+iCVkLMwew= golang.org/x/mod v0.41.0 h1:qJmnOUb4YB+FsEuM3HcWucdZASCPGhsX6uljO6pog0c= golang.org/x/mod v0.41.0/go.mod h1:Ek9pY8RKWXwsWvd3rQiHYtMqkjSUV+s1Rj7j4H5Ur6o= golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg= -golang.org/x/net v0.0.0-20190603091049-60506f45cf65/go.mod h1:HSz+uSET+XFnRR8LxR5pz3Of3rY3CfYBVs4xY44aLks= golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg= golang.org/x/net v0.59.0 h1:5zfYln+w5XCxwrnMMJPufRgNoXEaGxl0wo5GqPXyues= golang.org/x/net v0.59.0/go.mod h1:2DA/G1UfVbCpQPeWTmMPGY7Cs2PkBkwu743bVX5PIVg= @@ -325,7 +276,6 @@ golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9sn golang.org/x/term v0.46.0 h1:3+OXuTbaKDgwk8jTi3aSLHRlmWqHEUDUtxnbFigO4YE= golang.org/x/term v0.46.0/go.mod h1:+K02xbkittuwc0Am4abfA3Fc+XRGXkvBXNO88NCXPoc= golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ= -golang.org/x/text v0.3.2/go.mod h1:bEr9sfX3Q8Zfm5fL9x+3itogRgK3+ptLWKqgva+5dAk= golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ= golang.org/x/text v0.42.0 h1:JbOZXgfeCPU9gacVtYliJqOhD+zhrEqK4LfdpmlUZqI= golang.org/x/text v0.42.0/go.mod h1:ojzP1Z+2QtioaF8DTtO8K5q7JWVVYwZKenzujK0Zd0E= @@ -336,7 +286,6 @@ golang.org/x/tools v0.50.0 h1:c2ifzfcuY7L90lZ2aKd8S4K2NpASF08SZx9ZuJkHmSU= golang.org/x/tools v0.50.0/go.mod h1:7ulVMw3831Mwi5EZD6RomGyffr4VFjuNYXf2BbCEAV0= gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4= gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E= -google.golang.org/appengine v1.6.5/go.mod h1:8WjMMxjGQR8xUklV/ARdw2HLXBOI7O7uCIDZVag1xfc= google.golang.org/genproto/googleapis/api v0.0.0-20260921155816-b14227669459 h1:GS9OIt/j7c8bvBjYNgnKQysVfmV7e4jM0H8ZK95G4t8= google.golang.org/genproto/googleapis/api v0.0.0-20260921155816-b14227669459/go.mod h1:PX5/4vemwVoXtwEcRDWwcR1/r0qrosfx3qoVADMwnVE= google.golang.org/genproto/googleapis/rpc v0.0.0-20260921155816-b14227669459 h1:b0xCahf3FK2m2Cv0p4vTozGPWncCvLfwV86UNg8xWU8= diff --git a/internal/app/agentworker/pgtest_test.go b/internal/app/agentworker/pgtest_test.go new file mode 100644 index 000000000..4481d0ab0 --- /dev/null +++ b/internal/app/agentworker/pgtest_test.go @@ -0,0 +1,10 @@ +package agentworker + +import ( + "os" + "testing" + + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest" +) + +func TestMain(m *testing.M) { os.Exit(pgtest.Main(m)) } diff --git a/internal/app/agentworker/task_execution_test.go b/internal/app/agentworker/task_execution_test.go index 208e6e043..341151338 100644 --- a/internal/app/agentworker/task_execution_test.go +++ b/internal/app/agentworker/task_execution_test.go @@ -30,11 +30,10 @@ import ( "github.com/samcharles93/archie-core/internal/forge" "github.com/samcharles93/archie-core/internal/forgerpc" agentnats "github.com/samcharles93/archie-core/internal/infrastructure/agenttransport/nats" - "github.com/samcharles93/archie-core/internal/infrastructure/edastore" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/infrastructure/staterpc" "github.com/samcharles93/archie-core/internal/infrastructure/workflowsteps" "github.com/samcharles93/archie-core/internal/installtype" - "github.com/samcharles93/archie-core/internal/store" "github.com/samcharles93/archie-core/internal/taskrun" "github.com/samcharles93/archie-core/internal/worktree" "github.com/samcharles93/archie-core/internal/worktreerpc" @@ -370,14 +369,14 @@ func connectTaskRPC(t *testing.T, url string) *natsio.Conn { // on gRPC for its store calls (docs/prds/state-store-contract.md §12 step 4), // so an agentworker test that drives executeTaskRequest needs a real State // Store server rather than the deleted NATS storerpc path. -func startStateStoreGRPC(t *testing.T, local *store.Store) string { +func startStateStoreGRPC(t *testing.T, local *pgstore.TaskDB) string { t.Helper() listener, err := (&net.ListenConfig{}).Listen(t.Context(), "tcp", "127.0.0.1:0") if err != nil { t.Fatal(err) } server := grpc.NewServer() - eda := edastore.OpenTest(t) + eda := pgstore.EDA(t, nil) staterpc.RegisterServer(server, staterpc.Deps{ Tasks: local, Captures: eda, Mappings: eda, Bindings: eda, BindingDispatcher: eda, BindingTaskCreator: local, @@ -393,7 +392,7 @@ func TestRunTaskExecutesBootstrapWorkflowEndToEnd(t *testing.T) { } ctx := t.Context() host := newLocalRemote(t, "acme", "widget") - st := store.OpenTest(t) + st := pgstore.Open(t) if _, err := st.EnqueueIssue(ctx, "acme", "widget", 1, "feat: bootstrap test", "", "bootstrap", ""); err != nil { t.Fatalf("enqueue: %v", err) } @@ -594,7 +593,7 @@ func TestExecuteTaskRequestUsesInfrastructureRPCDependencies(t *testing.T) { } ctx := t.Context() host := newLocalRemote(t, "acme", "rpc-widget") - st := store.OpenTest(t) + st := pgstore.Open(t) if _, err := st.EnqueueIssue(ctx, "acme", "rpc-widget", 2, "feat: RPC bootstrap test", "", "bootstrap", ""); err != nil { t.Fatal(err) } @@ -686,7 +685,7 @@ func TestExecuteTaskRequestForwardsWorkflowEventsOverNATS(t *testing.T) { } ctx := t.Context() host := newLocalRemote(t, "acme", "events-widget") - st := store.OpenTest(t) + st := pgstore.Open(t) if _, err := st.EnqueueIssue(ctx, "acme", "events-widget", 3, "feat: events bootstrap test", "", "bootstrap", ""); err != nil { t.Fatal(err) } diff --git a/internal/app/archied/binding_cipher.go b/internal/app/archied/binding_cipher.go index bbec81d1a..968cfc2fa 100644 --- a/internal/app/archied/binding_cipher.go +++ b/internal/app/archied/binding_cipher.go @@ -5,7 +5,7 @@ import ( "strings" "github.com/samcharles93/archie-core/internal/config" - "github.com/samcharles93/archie-core/internal/infrastructure/edastore" + "github.com/samcharles93/archie-core/internal/infrastructure/bindingcipher" "github.com/samcharles93/archie-core/internal/secret" ) @@ -13,7 +13,7 @@ import ( // config through the secret registry and returns the EDA store's cipher. An unset // encryption_key returns a nil cipher, keeping the legacy plaintext path (the // store's default). See docs/prds/binding-secret-encryption.md. -func bindingCipherFromConfig(cfg config.Config, secrets *secret.Registry) (edastore.BindingCipher, error) { +func bindingCipherFromConfig(cfg config.Config, secrets *secret.Registry) (bindingcipher.BindingCipher, error) { if cfg.Bindings.EncryptionKey == (secret.SecretRef{}) { return nil, nil } @@ -36,5 +36,5 @@ func bindingCipherFromConfig(cfg config.Config, secrets *secret.Registry) (edast previous = append(previous, v) } } - return edastore.NewBindingCipher(active, previous) + return bindingcipher.NewBindingCipher(active, previous) } diff --git a/internal/app/archied/chat_store_composition_test.go b/internal/app/archied/chat_store_composition_test.go index b71be6779..b4e96a929 100644 --- a/internal/app/archied/chat_store_composition_test.go +++ b/internal/app/archied/chat_store_composition_test.go @@ -5,10 +5,11 @@ import ( "path/filepath" "testing" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" + "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/gateway" "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest" - "github.com/samcharles93/archie-core/internal/store" ) func TestRemoteChatCompositionPreservesChannelTurnLedger(t *testing.T) { @@ -17,10 +18,7 @@ func TestRemoteChatCompositionPreservesChannelTurnLedger(t *testing.T) { DatabaseURL: pgtest.URL(t), Services: config.Services{config.ServiceNameGateway: {Target: "127.0.0.1:1"}}, } - st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "state-store.db")) - if err != nil { - t.Fatal(err) - } + st := pgstore.Open(t) t.Cleanup(func() { _ = st.Close() }) b := &boot{cfg: cfg, log: slog.Default(), cfgHolder: config.NewHolder(cfg), stateStore: st, personas: gateway.NewPersonaRegistry(gateway.DefaultPersonas())} t.Cleanup(b.cleanup) diff --git a/internal/app/archied/config_snapshot_channels_test.go b/internal/app/archied/config_snapshot_channels_test.go index 1fc74f47d..cc85dd889 100644 --- a/internal/app/archied/config_snapshot_channels_test.go +++ b/internal/app/archied/config_snapshot_channels_test.go @@ -3,11 +3,11 @@ package archied import ( "encoding/json" "log/slog" - "path/filepath" "testing" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" + "github.com/samcharles93/archie-core/internal/config" - "github.com/samcharles93/archie-core/internal/store" "github.com/samcharles93/archie-core/internal/webui" ) @@ -49,10 +49,7 @@ func TestPublishedProjectionAgreesWithFrontEndsOnConfiguredChannels(t *testing.T for _, tc := range tests { t.Run(tc.name, func(t *testing.T) { - st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "state.db")) - if err != nil { - t.Fatal(err) - } + st := pgstore.Open(t) t.Cleanup(func() { _ = st.Close() }) b := &boot{ diff --git a/internal/app/archied/config_snapshot_test.go b/internal/app/archied/config_snapshot_test.go index 9e7f2659a..c2f9546f5 100644 --- a/internal/app/archied/config_snapshot_test.go +++ b/internal/app/archied/config_snapshot_test.go @@ -4,12 +4,12 @@ import ( "context" "encoding/json" "log/slog" - "path/filepath" "testing" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" + "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/infrastructure/configuration" - "github.com/samcharles93/archie-core/internal/store" "github.com/samcharles93/archie-core/internal/webui" ) @@ -19,10 +19,7 @@ import ( // from its own state rather than from a webui.Server it never serves // (archie-core-ml30). func TestPublishConfigSnapshotRendersTheDaemonsConfiguration(t *testing.T) { - st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "state.db")) - if err != nil { - t.Fatal(err) - } + st := pgstore.Open(t) t.Cleanup(func() { _ = st.Close() }) cfg := config.Config{ @@ -83,10 +80,7 @@ func TestPublishConfigSnapshotRendersTheDaemonsConfiguration(t *testing.T) { } func TestPublishedSnapshotCarriesPerIdentityForges(t *testing.T) { - st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "state.db")) - if err != nil { - t.Fatal(err) - } + st := pgstore.Open(t) t.Cleanup(func() { _ = st.Close() }) b := &boot{ @@ -133,10 +127,7 @@ func TestPublishedSnapshotCarriesPerIdentityForges(t *testing.T) { // TestPublishConfigSnapshotWithoutConfiguration: called before the daemon has // a configuration Holder, publishing is a no-op rather than a panic. func TestPublishConfigSnapshotWithoutConfiguration(t *testing.T) { - st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "state.db")) - if err != nil { - t.Fatal(err) - } + st := pgstore.Open(t) t.Cleanup(func() { _ = st.Close() }) b := &boot{log: slog.New(slog.DiscardHandler), stateStore: st} diff --git a/internal/app/archied/control_plane_restart_test.go b/internal/app/archied/control_plane_restart_test.go index f94867025..1d8ff3b66 100644 --- a/internal/app/archied/control_plane_restart_test.go +++ b/internal/app/archied/control_plane_restart_test.go @@ -23,8 +23,8 @@ import ( "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/domain/workflow" "github.com/samcharles93/archie-core/internal/infrastructure/configuration" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/infrastructure/staterpc" - "github.com/samcharles93/archie-core/internal/store" "github.com/samcharles93/archie-core/internal/webui" ) @@ -68,7 +68,7 @@ type controlPlaneRestartFixture struct { // reading apply status back. func newControlPlaneRestartFixture(t *testing.T) *controlPlaneRestartFixture { t.Helper() - local := store.OpenTest(t) + local := pgstore.Open(t) t.Cleanup(func() { _ = local.Close() }) steps, err := stepVocabulary() diff --git a/internal/app/archied/control_plane_watch_outage_test.go b/internal/app/archied/control_plane_watch_outage_test.go index 68ab01315..2e6998a8c 100644 --- a/internal/app/archied/control_plane_watch_outage_test.go +++ b/internal/app/archied/control_plane_watch_outage_test.go @@ -15,8 +15,9 @@ import ( "github.com/samcharles93/archie-core/internal/app/controlplane" pb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1" + "github.com/samcharles93/archie-core/internal/domain/storecontract" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/infrastructure/workflowsteps" - "github.com/samcharles93/archie-core/internal/store" ) // outageStore is the State Store's resource half with a switch that makes every @@ -32,7 +33,7 @@ import ( // lasted longer than the minimum retry interval, which is a failed attempt // whichever way the store failed it. type outageStore struct { - *store.Store + *pgstore.TaskDB mu sync.Mutex failing bool @@ -46,15 +47,15 @@ func (s *outageStore) down(stall time.Duration) { s.failing, s.stall = true, stall } -func (s *outageStore) Resource(ctx context.Context, kind string) (store.Resource, error) { +func (s *outageStore) Resource(ctx context.Context, kind string) (storecontract.Resource, error) { s.mu.Lock() failing, stall := s.failing, s.stall s.mu.Unlock() if failing { time.Sleep(stall) - return store.Resource{}, errors.New("state store unreachable") + return storecontract.Resource{}, errors.New("state store unreachable") } - return s.Store.Resource(ctx, kind) + return s.TaskDB.Resource(ctx, kind) } // TestWatchRetryGrowsWhileTheStateStoreIsDown is the outage this reconnect @@ -113,7 +114,7 @@ func TestWatchRetryGrowsWhileTheStateStoreIsDown(t *testing.T) { for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { t.Parallel() - database := &outageStore{Store: store.OpenTest(t)} + database := &outageStore{TaskDB: pgstore.Open(t)} defer database.Close() steps, err := workflowsteps.NewManager() if err != nil { diff --git a/internal/app/archied/cutover_test.go b/internal/app/archied/cutover_test.go index 8ecab7ddf..a8ea97ba5 100644 --- a/internal/app/archied/cutover_test.go +++ b/internal/app/archied/cutover_test.go @@ -7,13 +7,11 @@ import ( "path/filepath" "strings" "testing" - "time" "github.com/jackc/pgx/v5/pgxpool" "github.com/samcharles93/archie-core/internal/config" - "github.com/samcharles93/archie-core/internal/domain/messaging" - "github.com/samcharles93/archie-core/internal/gateway" + "github.com/samcharles93/archie-core/internal/infrastructure/legacyimport/legacyfixture" "github.com/samcharles93/archie-core/internal/infrastructure/postgres" "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest" ) @@ -23,18 +21,7 @@ import ( // see legacy data. func seedLegacyConversation(t *testing.T, dbPath string) { t.Helper() - legacy, err := gateway.OpenSQLiteSessionStore(conversationDBPath(dbPath)) - if err != nil { - t.Fatalf("open legacy conversation store: %v", err) - } - defer legacy.Close() - if err := legacy.Save(t.Context(), messaging.SessionContext{ - SessionID: "legacy", - Source: messaging.SessionSource{Platform: "telegram", BotUser: "archie"}, - CreatedAt: time.Now(), - }); err != nil { - t.Fatalf("seed legacy session: %v", err) - } + legacyfixture.Exec(t, conversationDBPath(dbPath), legacyfixture.GatewayDDL) } func testPool(t *testing.T, url string) *pgxpool.Pool { diff --git a/internal/app/archied/main.go b/internal/app/archied/main.go index 9a54b5d25..045dcffbe 100644 --- a/internal/app/archied/main.go +++ b/internal/app/archied/main.go @@ -43,7 +43,6 @@ import ( "github.com/samcharles93/archie-core/internal/plugin" "github.com/samcharles93/archie-core/internal/secret" "github.com/samcharles93/archie-core/internal/storage" - "github.com/samcharles93/archie-core/internal/store" "github.com/samcharles93/archie-core/internal/taskstate" "github.com/samcharles93/archie-core/internal/tools" "github.com/samcharles93/archie-core/internal/tools/mcp" @@ -284,10 +283,6 @@ func resolveForge(cfg config.Forge, secrets *secret.Registry, log *slog.Logger) return client, token } -func openProductionTaskStore(ctx context.Context, path string, opts ...store.OpenOption) (storecontract.TaskStore, error) { - return store.Open(ctx, path, opts...) -} - func taskDBPath(configuredPath string) string { return configuredPath + "-tasks.sqlite" } diff --git a/internal/app/archied/main_test.go b/internal/app/archied/main_test.go index bdd268404..bc99a28a7 100644 --- a/internal/app/archied/main_test.go +++ b/internal/app/archied/main_test.go @@ -7,13 +7,14 @@ import ( "fmt" "log/slog" "os" - "path/filepath" "slices" "strings" "sync" "testing" "time" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" + "github.com/nats-io/nats-server/v2/server" natssrv "github.com/nats-io/nats-server/v2/test" natsio "github.com/nats-io/nats.go" @@ -30,7 +31,6 @@ import ( "github.com/samcharles93/archie-core/internal/gateway" "github.com/samcharles93/archie-core/internal/logging" "github.com/samcharles93/archie-core/internal/secret" - "github.com/samcharles93/archie-core/internal/store" "github.com/samcharles93/archie-core/internal/tools" "github.com/samcharles93/archie-core/internal/worktree" "github.com/samcharles93/archie-core/internal/worktreerpc" @@ -528,10 +528,7 @@ func TestManualRequeueTaskUsesPersistedStatus(t *testing.T) { tests := []string{workflow.StatusParked, workflow.StatusWaitingHuman} for index, status := range tests { t.Run(status, func(t *testing.T) { - st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "tasks.db")) - if err != nil { - t.Fatal(err) - } + st := pgstore.Open(t) t.Cleanup(func() { _ = st.Close() }) if _, err := st.EnqueueIssue(t.Context(), "acme", "widget", index+1, "task", "", "", ""); err != nil { t.Fatal(err) @@ -555,10 +552,7 @@ func TestManualRequeueTaskUsesPersistedStatus(t *testing.T) { } func TestManualRequeueTaskRejectsOtherStatuses(t *testing.T) { - st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "tasks.db")) - if err != nil { - t.Fatal(err) - } + st := pgstore.Open(t) t.Cleanup(func() { _ = st.Close() }) if _, err := st.EnqueueIssue(t.Context(), "acme", "widget", 1, "task", "", "", ""); err != nil { t.Fatal(err) @@ -573,10 +567,7 @@ func TestManualRequeueTaskRejectsOtherStatuses(t *testing.T) { } func TestChatTaskListerAdapterReadsSQLiteIdentity(t *testing.T) { - st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "tasks.db")) - if err != nil { - t.Fatal(err) - } + st := pgstore.Open(t) t.Cleanup(func() { _ = st.Close() }) want, err := st.EnqueueChatTask(t.Context(), "acme", "widget", "identity task", "", "tdd", "reviewer") if err != nil { @@ -827,10 +818,7 @@ func TestChatTaskLogReaderAdapterRoundTrip(t *testing.T) { func TestChatTaskCommandsEndToEnd(t *testing.T) { ctx := context.Background() - st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "tasks.db")) - if err != nil { - t.Fatal(err) - } + st := pgstore.Open(t) t.Cleanup(func() { if err := st.Close(); err != nil { t.Errorf("close store: %v", err) diff --git a/internal/app/archied/readiness_test.go b/internal/app/archied/readiness_test.go index f4596f3e8..b7c1644a1 100644 --- a/internal/app/archied/readiness_test.go +++ b/internal/app/archied/readiness_test.go @@ -5,9 +5,10 @@ import ( "path/filepath" "testing" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" + "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/gateway" - "github.com/samcharles93/archie-core/internal/store" "github.com/samcharles93/archie-core/internal/webui" ) @@ -49,10 +50,7 @@ func TestPingChat_ReportsUnwiredChat(t *testing.T) { // on the store, config, disk, model and gateway in the running daemon -- only // that every subsystem the epic names is actually wired. func TestSetupReadinessProbes_WiresEverySubsystem(t *testing.T) { - st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "test.db")) - if err != nil { - t.Fatal(err) - } + st := pgstore.Open(t) t.Cleanup(func() { _ = st.Close() }) cfg := config.Config{ diff --git a/internal/app/archied/routing_bindings_test.go b/internal/app/archied/routing_bindings_test.go index 33b478076..080cfc6a5 100644 --- a/internal/app/archied/routing_bindings_test.go +++ b/internal/app/archied/routing_bindings_test.go @@ -2,13 +2,13 @@ package archied import ( "log/slog" - "path/filepath" "testing" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" + "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/domain/workflow" "github.com/samcharles93/archie-core/internal/domain/workintake" - "github.com/samcharles93/archie-core/internal/store" ) // TestBuildDaemonCarriesWorkflowRoutingBindings pins the composition hop in the @@ -21,10 +21,7 @@ import ( // the "tested in isolation, never verified wired" shape this repo has been bitten // by before. func TestBuildDaemonCarriesWorkflowRoutingBindings(t *testing.T) { - storeA, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "store-a.db")) - if err != nil { - t.Fatal(err) - } + storeA := pgstore.Open(t) t.Cleanup(func() { _ = storeA.Close() }) storeB := openSecondStore(t) diff --git a/internal/app/archied/sd_notify_test.go b/internal/app/archied/sd_notify_test.go index 7a3f3177e..1d44ea13e 100644 --- a/internal/app/archied/sd_notify_test.go +++ b/internal/app/archied/sd_notify_test.go @@ -14,9 +14,10 @@ import ( "testing" "time" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" + "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/daemon" - "github.com/samcharles93/archie-core/internal/store" ) // notifyRecorder captures every record at every level. The other recording @@ -126,10 +127,7 @@ func newNotifyTestBoot(t *testing.T, cadence time.Duration) (*boot, *daemon.Daem t.Helper() cfg := config.Config{PollInterval: config.Duration(cadence)} holder := config.NewHolder(cfg) - st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "tasks.db")) - if err != nil { - t.Fatalf("open task store: %v", err) - } + st := pgstore.Open(t) log := slog.New(slog.DiscardHandler) d := &daemon.Daemon{Cfg: holder, Store: st, Log: log} return &boot{cfg: cfg, cfgHolder: holder, d: d, log: log}, d diff --git a/internal/app/archied/state_store_consumers_test.go b/internal/app/archied/state_store_consumers_test.go index a0cbb6c3e..a78e15d7c 100644 --- a/internal/app/archied/state_store_consumers_test.go +++ b/internal/app/archied/state_store_consumers_test.go @@ -2,47 +2,36 @@ package archied import ( "log/slog" - "path/filepath" "testing" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres" + "github.com/samcharles93/archie-core/internal/config" - "github.com/samcharles93/archie-core/internal/infrastructure/edastore" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" taskactionstore "github.com/samcharles93/archie-core/internal/infrastructure/taskactions" - "github.com/samcharles93/archie-core/internal/store" ) -// openSecondStore opens a second, independent *store.Store on a fresh temp +// openSecondStore opens a second, independent *pgstore.TaskDB on a fresh temp // path so a boot consumer test can prove the composition routes through // b.stateStore rather than b.st: the two differ by identity, so an assertion // that a consumer field holds storeB (not storeA) can only pass if the wiring // reads b.stateStore. // stateStoreAdapter stands in for the real adapter (*staterpc.Client), which // fronts both halves of the contract over one connection: the task store and -// the event-capture store. A plain *store.Store no longer satisfies the +// the event-capture store. A plain *pgstore.TaskDB no longer satisfies the // event-capture surfaces, so a test that asserts "everything routes through // the adapter" needs something that implements them, exactly as the client // does in production. -// edaSide aliases the event-capture store so it can be embedded beside -// *store.Store: both are named Store, and Go allows only one embedded field -// per name. -type edaSide = edastore.Store - type stateStoreAdapter struct { - *store.Store - *edaSide + *pgstore.TaskDB + *postgres.EDA } -// Close disambiguates the two embedded stores, which both have one. -func (a *stateStoreAdapter) Close() error { return a.Store.Close() } - func openSecondStore(t *testing.T) *stateStoreAdapter { t.Helper() - st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "state-store.db")) - if err != nil { - t.Fatalf("open second store: %v", err) - } + st := pgstore.Open(t) t.Cleanup(func() { _ = st.Close() }) - return &stateStoreAdapter{Store: st, edaSide: edastore.OpenTest(t)} + return &stateStoreAdapter{TaskDB: st, EDA: pgstore.EDA(t, nil)} } // TestBuildDaemonRoutesTaskStoreThroughStateStore proves the daemon's task @@ -52,10 +41,7 @@ func openSecondStore(t *testing.T) *stateStoreAdapter { // (docs/prds/state-store-contract.md §12 step 6): the daemon's Store field and // its mapping/binding dispatch surfaces all come from the adapter. func TestBuildDaemonRoutesTaskStoreThroughStateStore(t *testing.T) { - storeA, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "store-a.db")) - if err != nil { - t.Fatal(err) - } + storeA := pgstore.Open(t) t.Cleanup(func() { _ = storeA.Close() }) storeB := openSecondStore(t) diff --git a/internal/app/archied/state_store_eda.go b/internal/app/archied/state_store_eda.go index c35c51f4a..785d6c4e5 100644 --- a/internal/app/archied/state_store_eda.go +++ b/internal/app/archied/state_store_eda.go @@ -2,7 +2,7 @@ package archied import ( "github.com/samcharles93/archie-core/internal/domain/storecontract" - "github.com/samcharles93/archie-core/internal/infrastructure/edastore" + "github.com/samcharles93/archie-core/internal/infrastructure/bindingcipher" "github.com/samcharles93/archie-core/internal/infrastructure/postgres" ) @@ -19,6 +19,6 @@ type eventCaptureStore interface { // openEDAStore serves the event-capture store from the State Store's Postgres // pool, sealing binding secrets with cipher. -func (b *boot) openEDAStore(cipher edastore.BindingCipher) { +func (b *boot) openEDAStore(cipher bindingcipher.BindingCipher) { b.eda = postgres.NewEDA(b.pg, cipher) } diff --git a/internal/app/archied/state_store_recovery.go b/internal/app/archied/state_store_recovery.go index 61864fa7e..a1040505c 100644 --- a/internal/app/archied/state_store_recovery.go +++ b/internal/app/archied/state_store_recovery.go @@ -5,12 +5,12 @@ // State Store is up -- is unavailable in exactly the case that needs it // (docs/architecture/safe-change-and-recovery.md). // -// With -db an operation works on the legacy SQLite task file; without it, on -// the PostgreSQL database database_url names (state_store_recovery_postgres.go). -// The ones that write refuse while a serving process owns the store. Backup is -// the exception and deliberately so: the update installer cannot stop the -// process that runs it, so the snapshot that makes a failed update recoverable -// is taken against a serving store through a consistent copy. +// Every operation but import works on the PostgreSQL database database_url +// names (state_store_recovery_postgres.go). The ones that write refuse while a +// serving process owns the store. Backup is the exception and deliberately so: +// the update installer cannot stop the process that runs it, so the snapshot +// that makes a failed update recoverable is taken against a serving store +// through a consistent copy. // // The control-plane server both validate and rollback read through is built by // openStateStoreControlPlane -- the same root helper the served path uses -- so @@ -28,8 +28,8 @@ import ( "github.com/samcharles93/archie-core/internal/app/controlplane" "github.com/samcharles93/archie-core/internal/config" pb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1" + "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/infrastructure/configuration" - "github.com/samcharles93/archie-core/internal/store" ) // The audit identity every offline rollback records. A rollback is one more @@ -55,9 +55,6 @@ const ( type StateStoreRecoveryOptions struct { // Operation is one of backup, restore, validate, rollback. Operation string - // DB is the task database file the State Store owns: the configured - // db_path with "-tasks.sqlite" appended, not the configured path itself. - DB string // Out is the snapshot backup writes. Out string // From is the snapshot restore reads. @@ -88,90 +85,7 @@ func RunStateStoreRecovery(ctx context.Context, options StateStoreRecoveryOption if options.Operation == RecoveryImport { return importLegacy(ctx, options) } - // -db names the legacy SQLite task file; without it the command works on - // the PostgreSQL database the configuration names. - if options.DB == "" { - return runPostgresRecovery(ctx, options) - } - switch options.Operation { - case RecoveryBackup: - if options.Out == "" { - return "", errors.New("backup requires -out") - } - return summarise(store.Backup(ctx, options.DB, options.Out), "backed up %s to %s", options.DB, options.Out) - case RecoveryRestore: - if options.From == "" { - return "", errors.New("restore requires -from") - } - return summarise(store.Restore(ctx, options.DB, options.From), - "restored %s from %s; start the State Store again", options.DB, options.From) - case RecoveryValidate: - return validateStore(ctx, options) - case RecoveryRollback: - if options.Kind == "" { - return "", errors.New("rollback requires -kind") - } - return rollbackResource(ctx, options) - default: - return "", fmt.Errorf("unknown recovery command %q", options.Operation) - } -} - -// summarise is an operation's stdout line, or its error. -func summarise(err error, format string, args ...any) (string, error) { - if err != nil { - return "", err - } - return fmt.Sprintf(format, args...), nil -} - -// validateStore answers the question an operator actually has: would archied -// start against this file. It runs the checks that stop it, in the order boot -// meets them. -// -// First the file itself, since a database that is corrupt, newer than this -// binary, or not a database is one the serving process refuses to open. Then -// the writer's own per-resource validation, which is what a hand-edited value -// violated. Then boot's gate: the file config with every stored resource -// layered onto it, and configuration.Validate -- the check whose failure the -// daemon reports as "validate database settings". -// -// The two validation layers disagree in both directions, and both are reported -// rather than merged. The write path is stricter about shape (it rejects -// unknown fields boot's decode ignores), while boot is stricter about meaning -// (only boot checks dispatch.trigger and a positive poll interval, both of -// which the write path's own validators let through). A store either check -// refuses is a store somebody has to look at. -func validateStore(ctx context.Context, options StateStoreRecoveryOptions) (string, error) { - version, err := store.ValidateFile(ctx, options.DB) - if err != nil { - return "", err - } - st, err := store.OpenReadOnly(ctx, options.DB) - if err != nil { - return "", err - } - defer func() { _ = st.Close() }() - - server, err := openStateStoreControlPlane(st) - if err != nil { - return "", err - } - // Is there a resources table at all? A store written before the control plane - // existed has none, and the State Store creates it and seeds every kind from - // this same config on its next start -- so there is nothing stored to check - // with the writer's validator, and boot's gate is the config check alone. - // That is the same stance the layering takes for a kind the table is missing: - // what the daemon reads for a kind nothing was ever stored for is the seed. - stored, err := st.StoresResources(ctx) - if err != nil { - return "", err - } - checked, err := checkBootGate(ctx, server, stored, options) - if err != nil { - return "", err - } - return fmt.Sprintf("%s is a valid store at schema version %d; %d stored resources validate", options.DB, version, checked), nil + return runPostgresRecovery(ctx, options) } // checkBootGate runs the writer's per-resource validation over what is stored, @@ -222,32 +136,6 @@ func bootConfig(ctx context.Context, options StateStoreRecoveryOptions) (config. return b.cfg, nil } -// rollbackResource is the one operation the Web UI cannot be asked to perform -// here: the daemon fails closed on the bad value, so the store that would serve -// the rollback is the store that will not start. It replays the revision's own -// value through the ordinary replace, so no rollback RPC exists or is needed, -// and the rollback is audited as one more revision. -func rollbackResource(ctx context.Context, options StateStoreRecoveryOptions) (string, error) { - // Before the lock and before the open: opening a store creates the file, - // and a rollback pointed at a mistyped path must not leave an empty - // database where the operator expected theirs. - if err := store.RequireDatabase(options.DB); err != nil { - return "", err - } - ownership, err := store.AcquireOwnership(options.DB) - if err != nil { - return "", err - } - defer func() { _ = ownership.Release() }() - - st, err := store.Open(ctx, options.DB) - if err != nil { - return "", err - } - defer func() { _ = st.Close() }() - return replayRevision(ctx, st, options) -} - // replayRevision puts back the revision options names through the control // plane's ordinary replace. The caller holds the store's ownership claim. func replayRevision(ctx context.Context, resources controlplane.ResourceStore, options StateStoreRecoveryOptions) (string, error) { @@ -259,7 +147,7 @@ func replayRevision(ctx context.Context, resources controlplane.ResourceStore, o return "", fmt.Errorf("unknown resource kind %q", options.Kind) } current, err := resources.Resource(ctx, options.Kind) - if errors.Is(err, store.ErrResourceNotFound) { + if errors.Is(err, storecontract.ErrResourceNotFound) { return "", fmt.Errorf("%s has no stored value to roll back", options.Kind) } if err != nil { @@ -287,10 +175,10 @@ func replayRevision(ctx context.Context, resources controlplane.ResourceStore, o // revisionToReplay picks the value to put back: the revision the operator // named, or the newest one older than the value the resource carries now. -func revisionToReplay(ctx context.Context, st controlplane.ResourceStore, kind string, current, requested int64) (store.Resource, error) { +func revisionToReplay(ctx context.Context, st controlplane.ResourceStore, kind string, current, requested int64) (storecontract.Resource, error) { history, err := st.ResourceHistory(ctx, kind, 0) if err != nil { - return store.Resource{}, fmt.Errorf("read %s history: %w", kind, err) + return storecontract.Resource{}, fmt.Errorf("read %s history: %w", kind, err) } if requested > 0 { for _, revision := range history { @@ -298,16 +186,16 @@ func revisionToReplay(ctx context.Context, st controlplane.ResourceStore, kind s continue } if revision.Version == current { - return store.Resource{}, fmt.Errorf("%s revision %d is the current version; there is nothing to roll back to", kind, requested) + return storecontract.Resource{}, fmt.Errorf("%s revision %d is the current version; there is nothing to roll back to", kind, requested) } return revision, nil } - return store.Resource{}, fmt.Errorf("%s has no revision %d", kind, requested) + return storecontract.Resource{}, fmt.Errorf("%s has no revision %d", kind, requested) } for _, revision := range history { if revision.Version < current { return revision, nil } } - return store.Resource{}, fmt.Errorf("%s has no earlier revision to roll back to", kind) + return storecontract.Resource{}, fmt.Errorf("%s has no earlier revision to roll back to", kind) } diff --git a/internal/app/archied/state_store_recovery_postgres.go b/internal/app/archied/state_store_recovery_postgres.go index ace209b07..6d97a330c 100644 --- a/internal/app/archied/state_store_recovery_postgres.go +++ b/internal/app/archied/state_store_recovery_postgres.go @@ -21,7 +21,7 @@ func runPostgresRecovery(ctx context.Context, options StateStoreRecoveryOptions) } url := cfg.DatabaseURL if url == "" { - return "", errors.New("database_url is required: the configuration names no PostgreSQL database (pass -db for a legacy SQLite task file)") + return "", errors.New("database_url is required: the configuration names no PostgreSQL database") } switch options.Operation { case RecoveryBackup: @@ -70,7 +70,8 @@ func openRecoveryPool(ctx context.Context, url string) (*pgxpool.Pool, int64, er return pool, version, nil } -// validatePostgres is validateStore for the PostgreSQL database. An +// validatePostgres answers whether archied would start against the database: +// the stored resources pass the writer's validation and boot's gate. An // unmigrated database holds nothing to check; the State Store migrates and // seeds it on its next start, so only boot's config gate applies. func validatePostgres(ctx context.Context, url string, options StateStoreRecoveryOptions) (string, error) { diff --git a/internal/app/archied/state_store_test.go b/internal/app/archied/state_store_test.go index a2bec8385..9ffbe30f9 100644 --- a/internal/app/archied/state_store_test.go +++ b/internal/app/archied/state_store_test.go @@ -12,11 +12,10 @@ import ( "github.com/samcharles93/archie-core/internal/config" pb "github.com/samcharles93/archie-core/internal/contracts/state/v1" "github.com/samcharles93/archie-core/internal/domain/storecontract" - "github.com/samcharles93/archie-core/internal/infrastructure/edastore" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest" "github.com/samcharles93/archie-core/internal/infrastructure/staterpc" "github.com/samcharles93/archie-core/internal/logging" - "github.com/samcharles93/archie-core/internal/store" ) func TestStateStoreServerOptsLoopbackIsInsecure(t *testing.T) { @@ -60,11 +59,7 @@ func TestStateStoreServerOptsMalformedListen(t *testing.T) { // in-process, now extracted into its own process. A read-only StatusCounts // call proves the service is registered and wired to the opened store. func TestServeStateStoreServesContract(t *testing.T) { - dir := t.TempDir() - st, err := store.Open(t.Context(), filepath.Join(dir, "tasks.sqlite")) - if err != nil { - t.Fatalf("open temp store: %v", err) - } + st := pgstore.Open(t) defer st.Close() b := newBootstrap() @@ -132,31 +127,28 @@ func TestStateStoreDepsServeTaskLogs(t *testing.T) { } // TestStateStoreDepsServePlaybookDispatcher verifies stateStoreDeps lifts the -// opened *store.Store's PlaybookDispatcher surface onto Deps, so the +// opened *pgstore.TaskDB's PlaybookDispatcher surface onto Deps, so the // standalone State Store has a server for the two playbook RPCs. It does not // dial those RPCs here -- it inspects the assembled Deps only. The nil check // is the load-bearing part: a boot without a store must leave // PlaybookDispatcher nil (the server then answers codes.Unavailable) rather // than fabricating a dispatcher. func TestStateStoreDepsServePlaybookDispatcher(t *testing.T) { - st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "tasks.sqlite")) - if err != nil { - t.Fatalf("open temp store: %v", err) - } + st := pgstore.Open(t) defer st.Close() b := newBootstrap() b.st = st // The playbook ledger moved to the event-capture store with the rest of // the dispatch tables; the task store no longer serves it. - eda := edastore.OpenTest(t) + eda := pgstore.EDA(t, nil) b.eda = eda deps := b.stateStoreDeps(&staterpc.TaskGrants{}) if deps.PlaybookDispatcher == nil { t.Fatal("stateStoreDeps leaves PlaybookDispatcher nil; the standalone State Store is the only production server for the playbook dispatch ledger") } if deps.PlaybookDispatcher != storecontract.PlaybookDispatcher(eda) { - t.Fatalf("PlaybookDispatcher = %T, want the opened *edastore.Store", deps.PlaybookDispatcher) + t.Fatalf("PlaybookDispatcher = %T, want the opened *postgres.EDA", deps.PlaybookDispatcher) } // A boot without a store must not fabricate one: nil keeps the RPCs honest // as unavailable rather than depending on a nil receiver. diff --git a/internal/app/archied/state_store_toolcalls.go b/internal/app/archied/state_store_toolcalls.go index f4ba41edc..05d3f0981 100644 --- a/internal/app/archied/state_store_toolcalls.go +++ b/internal/app/archied/state_store_toolcalls.go @@ -7,13 +7,13 @@ import ( "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/events" - "github.com/samcharles93/archie-core/internal/infrastructure/edastore" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres" ) -// toolCallWriter is the edastore surface the projection writes through. Kept +// toolCallWriter is the EDA store surface the projection writes through. Kept // narrow so a test can fail it without touching the real store. type toolCallWriter interface { - InsertToolCall(ctx context.Context, tc edastore.ToolCall) error + InsertToolCall(ctx context.Context, tc postgres.ToolCall) error } // toolCallProjectingTaskStore decorates the State Store's task store so every @@ -69,10 +69,10 @@ func (s *toolCallProjectingTaskStore) InsertEvent(ctx context.Context, e events. // fields stay unwritten -- the event reports neither -- so they are schema // reserved for a producer that one day reports them, not promises this // projection makes. -func toolCallFromEvent(e events.Event) edastore.ToolCall { +func toolCallFromEvent(e events.Event) postgres.ToolCall { tool, _ := e.Data["tool"].(string) failed, _ := e.Data["failed"].(bool) - tc := edastore.ToolCall{ + tc := postgres.ToolCall{ TaskID: e.TaskID, Attempt: e.Attempt, Tool: tool, diff --git a/internal/app/archied/state_store_toolcalls_test.go b/internal/app/archied/state_store_toolcalls_test.go index 1371f7d55..92a7048c6 100644 --- a/internal/app/archied/state_store_toolcalls_test.go +++ b/internal/app/archied/state_store_toolcalls_test.go @@ -10,9 +10,9 @@ import ( "time" "github.com/samcharles93/archie-core/internal/events" - "github.com/samcharles93/archie-core/internal/infrastructure/edastore" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/infrastructure/staterpc" - "github.com/samcharles93/archie-core/internal/store" ) func toolCallEvent(taskID int64, attempt int) events.Event { @@ -33,8 +33,8 @@ func toolCallEvent(taskID int64, attempt int) events.Event { // tool_calls row, with the row's fields taken from the event -- the tool name // from data, the output summary in result for a succeeded call. func TestInsertEventProjectsToolCall(t *testing.T) { - st := store.OpenTest(t) - eda := edastore.OpenTest(t) + st := pgstore.Open(t) + eda := pgstore.EDA(t, nil) ts := newToolCallProjectingTaskStore(st, eda, slog.Default()) id, err := ts.InsertEvent(t.Context(), toolCallEvent(42, 2)) @@ -74,8 +74,8 @@ func TestInsertEventProjectsToolCall(t *testing.T) { // event whose call failed stores its detail under error, not result, so the // transcript can distinguish the two without re-parsing text. func TestInsertEventProjectsFailedToolCall(t *testing.T) { - st := store.OpenTest(t) - eda := edastore.OpenTest(t) + st := pgstore.Open(t) + eda := pgstore.EDA(t, nil) ts := newToolCallProjectingTaskStore(st, eda, slog.Default()) e := toolCallEvent(42, 2) @@ -104,8 +104,8 @@ func TestInsertEventProjectsFailedToolCall(t *testing.T) { // tool_call events reach the collection; the task timeline's other kinds must // not grow tool_calls rows. func TestInsertEventLeavesOtherKindsUnprojected(t *testing.T) { - st := store.OpenTest(t) - eda := edastore.OpenTest(t) + st := pgstore.Open(t) + eda := pgstore.EDA(t, nil) ts := newToolCallProjectingTaskStore(st, eda, slog.Default()) if _, err := ts.InsertEvent(t.Context(), events.Event{ @@ -129,7 +129,7 @@ func TestInsertEventLeavesOtherKindsUnprojected(t *testing.T) { // store. type failingToolCallWriter struct{ err error } -func (f failingToolCallWriter) InsertToolCall(context.Context, edastore.ToolCall) error { +func (f failingToolCallWriter) InsertToolCall(context.Context, postgres.ToolCall) error { return f.err } @@ -138,7 +138,7 @@ func (f failingToolCallWriter) InsertToolCall(context.Context, edastore.ToolCall // event persistence is the contract, the projection is observability -- and // the failure is recorded, not swallowed silently. func TestInsertEventSucceedsWhenProjectionFails(t *testing.T) { - st := store.OpenTest(t) + st := pgstore.Open(t) var buf bytes.Buffer ts := newToolCallProjectingTaskStore(st, failingToolCallWriter{ err: errors.New("disk on fire"), @@ -172,8 +172,8 @@ func TestInsertEventSucceedsWhenProjectionFails(t *testing.T) { // event-capture store, Tasks is passed through untouched rather than wrapped // around a nil writer. func TestStateStoreDepsProjectToolCalls(t *testing.T) { - st := store.OpenTest(t) - eda := edastore.OpenTest(t) + st := pgstore.Open(t) + eda := pgstore.EDA(t, nil) b := newBootstrap() b.st = st diff --git a/internal/app/archied/status_health_test.go b/internal/app/archied/status_health_test.go index c2e1adb9a..3983d5bff 100644 --- a/internal/app/archied/status_health_test.go +++ b/internal/app/archied/status_health_test.go @@ -23,7 +23,7 @@ import ( "github.com/samcharles93/archie-core/internal/domain/curator" "github.com/samcharles93/archie-core/internal/domain/messaging" "github.com/samcharles93/archie-core/internal/gateway" - "github.com/samcharles93/archie-core/internal/store" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" ) // TestProviderOutcomeRecorderRecordsTheLastCallOnly pins the producer behind @@ -356,7 +356,7 @@ func TestRouterWithHealthAnswersStatus(t *testing.T) { sessions := gateway.NewSessionStoreMemory() t.Cleanup(func() { _ = sessions.Close() }) - st := store.OpenTest(t) + st := pgstore.Open(t) router := gateway.NewRouter(st, nil, "web") router.InitSessions(sessions) router.Health = statusHealth{broker: func() (bool, bool) { return true, true }} diff --git a/internal/app/archied/task_action_adapter_test.go b/internal/app/archied/task_action_adapter_test.go index a49b4915a..fc7e66286 100644 --- a/internal/app/archied/task_action_adapter_test.go +++ b/internal/app/archied/task_action_adapter_test.go @@ -4,15 +4,16 @@ import ( "context" "fmt" "log/slog" - "path/filepath" "strings" "testing" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" + "github.com/samcharles93/archie-core/internal/config" + "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/domain/taskactions" "github.com/samcharles93/archie-core/internal/domain/workflow" "github.com/samcharles93/archie-core/internal/gateway" - "github.com/samcharles93/archie-core/internal/store" "github.com/samcharles93/archie-core/internal/taskstate" ) @@ -35,7 +36,7 @@ func (a testTaskActor) ApplyChatTaskAction( }, nil } -func newChatTaskActorForTest(t *testing.T, st store.TaskStore, cfg config.Config) chatTaskActorAdapter { +func newChatTaskActorForTest(t *testing.T, st storecontract.TaskStore, cfg config.Config) chatTaskActorAdapter { t.Helper() b := &boot{ st: st, @@ -48,10 +49,7 @@ func newChatTaskActorForTest(t *testing.T, st store.TaskStore, cfg config.Config func TestChatTaskActorAdapterCrossIdentityRefused(t *testing.T) { ctx := context.Background() - st, err := store.Open(ctx, filepath.Join(t.TempDir(), "tasks.db")) - if err != nil { - t.Fatal(err) - } + st := pgstore.Open(t) t.Cleanup(func() { _ = st.Close() }) task, err := st.EnqueueChatTask(ctx, "acme", "widget", "parked job", "", "", "identity-owner") @@ -111,10 +109,7 @@ func TestChatTaskActorAdapterCrossIdentityRefused(t *testing.T) { func TestChatTaskActorAdapterRefusesDisallowedStateAction(t *testing.T) { ctx := context.Background() - st, err := store.Open(ctx, filepath.Join(t.TempDir(), "tasks.db")) - if err != nil { - t.Fatal(err) - } + st := pgstore.Open(t) t.Cleanup(func() { _ = st.Close() }) adapter := newChatTaskActorForTest(t, st, config.Config{}) @@ -188,15 +183,12 @@ func TestChatTaskActorAdapterRefusesDisallowedStateAction(t *testing.T) { func TestChatTaskActorAdapterTaskNotFound(t *testing.T) { ctx := context.Background() - st, err := store.Open(ctx, filepath.Join(t.TempDir(), "tasks.db")) - if err != nil { - t.Fatal(err) - } + st := pgstore.Open(t) t.Cleanup(func() { _ = st.Close() }) adapter := newChatTaskActorForTest(t, st, config.Config{}) - _, err = adapter.ApplyChatTaskAction(ctx, new("archie"), taskactions.Actor{}, 999999, taskstate.ActionAbandon) + _, err := adapter.ApplyChatTaskAction(ctx, new("archie"), taskactions.Actor{}, 999999, taskstate.ActionAbandon) if err == nil { t.Fatal("expected error for non-existent task, got nil") } @@ -260,10 +252,7 @@ func TestChatTaskActorAdapterAppliesActionsToStore(t *testing.T) { for _, tc := range tests { t.Run(tc.name, func(t *testing.T) { ctx := context.Background() - st, err := store.Open(ctx, filepath.Join(t.TempDir(), "tasks.db")) - if err != nil { - t.Fatal(err) - } + st := pgstore.Open(t) t.Cleanup(func() { _ = st.Close() }) adapter := newChatTaskActorForTest(t, st, config.Config{MaxRetries: 3}) diff --git a/internal/app/archied/task_actions_test.go b/internal/app/archied/task_actions_test.go index e2545d9a4..cbe1af4d2 100644 --- a/internal/app/archied/task_actions_test.go +++ b/internal/app/archied/task_actions_test.go @@ -6,14 +6,15 @@ import ( "log/slog" "net/http" "net/http/httptest" - "path/filepath" "strconv" "testing" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" + "github.com/samcharles93/archie-core/internal/config" + "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/domain/workflow" "github.com/samcharles93/archie-core/internal/gateway" - "github.com/samcharles93/archie-core/internal/store" "github.com/samcharles93/archie-core/internal/webui" ) @@ -44,10 +45,7 @@ func TestDashboardAndChatAgreeOnTerminalStates(t *testing.T) { for _, tc := range tests { t.Run(tc.name, func(t *testing.T) { ctx := context.Background() - st, err := store.Open(ctx, filepath.Join(t.TempDir(), "tasks.db")) - if err != nil { - t.Fatal(err) - } + st := pgstore.Open(t) t.Cleanup(func() { _ = st.Close() }) task, err := st.EnqueueChatTask(ctx, "acme", "widget", "decide on me", "", "", "reviewer") @@ -78,7 +76,7 @@ func TestDashboardAndChatAgreeOnTerminalStates(t *testing.T) { // runChatAction performs the approve/cancel action through the chat // controller path and fails the test on error. -func runChatAction(t *testing.T, ctx context.Context, st store.TaskStore, action string, taskID int64) { +func runChatAction(t *testing.T, ctx context.Context, st storecontract.TaskStore, action string, taskID int64) { t.Helper() controller := gateway.NewStoreTaskController(chatTaskControllerAdapter{ taskByID: st.TaskByID, @@ -99,7 +97,7 @@ func runChatAction(t *testing.T, ctx context.Context, st store.TaskStore, action // runDashboardAction performs the approve/cancel action through the // dashboard's HTTP handler and fails the test when the request is // rejected. -func runDashboardAction(t *testing.T, ctx context.Context, st store.TaskStore, action string, taskID int64) { +func runDashboardAction(t *testing.T, ctx context.Context, st storecontract.TaskStore, action string, taskID int64) { t.Helper() // The dashboard reaches task actions through the Gateway contract, which // in production carries them back to this daemon's own service. Wiring diff --git a/internal/app/archieui/compose_test.go b/internal/app/archieui/compose_test.go index cd36972a0..a2d853c1c 100644 --- a/internal/app/archieui/compose_test.go +++ b/internal/app/archieui/compose_test.go @@ -10,8 +10,8 @@ import ( "github.com/samcharles93/archie-core/internal/infrastructure/configuration" "github.com/samcharles93/archie-core/internal/infrastructure/gatewayrpc" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/infrastructure/staterpc" - "github.com/samcharles93/archie-core/internal/store" ) // isNil reports whether v is nil, including a typed nil func or pointer @@ -61,8 +61,8 @@ func TestComposeUIServerHoldsNoDaemonState(t *testing.T) { if _, ok := srv.Store.(*staterpc.Client); !ok { t.Fatalf("Store = %T, want *staterpc.Client", srv.Store) } - if _, ok := srv.Store.(*store.Store); ok { - t.Fatal("Store is the concrete *store.Store; the UI process must not open archie.db") + if _, ok := srv.Store.(*pgstore.TaskDB); ok { + t.Fatal("Store is the concrete *pgstore.TaskDB; the UI process must not open archie.db") } if srv.Chat == nil { t.Fatal("Chat is nil; the UI process must dial the Gateway contract") diff --git a/internal/app/archieui/degraded_routes_test.go b/internal/app/archieui/degraded_routes_test.go index ac245e04a..d405f7847 100644 --- a/internal/app/archieui/degraded_routes_test.go +++ b/internal/app/archieui/degraded_routes_test.go @@ -13,10 +13,9 @@ import ( "google.golang.org/grpc" - "github.com/samcharles93/archie-core/internal/infrastructure/edastore" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/infrastructure/staterpc" "github.com/samcharles93/archie-core/internal/logging" - "github.com/samcharles93/archie-core/internal/store" "github.com/samcharles93/archie-core/internal/webui" ) @@ -153,10 +152,7 @@ func TestRoutesWithoutAContractDegradeExplicitly(t *testing.T) { // all -- the shape every route below has to survive. func composeUIProcess(t *testing.T) (*webui.Server, int64) { t.Helper() - st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "tasks.sqlite")) - if err != nil { - t.Fatalf("open store: %v", err) - } + st := pgstore.Open(t) t.Cleanup(func() { _ = st.Close() }) // The task-log reader lives on the state-directory side of the boundary: @@ -166,7 +162,7 @@ func composeUIProcess(t *testing.T) (*webui.Server, int64) { logs := logging.NewTaskRegistry(filepath.Join(t.TempDir(), "logs", "tasks"), logging.NewFeed(10), logging.TaskSinkOptions{}) target, stop := serveGRPC(t, func(r grpc.ServiceRegistrar) { - eda := edastore.OpenTest(t) + eda := pgstore.EDA(t, nil) staterpc.RegisterServer(r, staterpc.Deps{ Tasks: st, Captures: eda, BindingDispatcher: eda, ConfigSnapshots: st, TaskLogs: logs, Log: slog.New(slog.DiscardHandler), diff --git a/internal/app/archieui/pgtest_test.go b/internal/app/archieui/pgtest_test.go new file mode 100644 index 000000000..3d73cc3eb --- /dev/null +++ b/internal/app/archieui/pgtest_test.go @@ -0,0 +1,10 @@ +package archieui + +import ( + "os" + "testing" + + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest" +) + +func TestMain(m *testing.M) { os.Exit(pgtest.Main(m)) } diff --git a/internal/app/archieui/run_test.go b/internal/app/archieui/run_test.go index 47529eecb..278368eb5 100644 --- a/internal/app/archieui/run_test.go +++ b/internal/app/archieui/run_test.go @@ -18,13 +18,13 @@ import ( "github.com/samcharles93/archie-core/internal/domain/health" "github.com/samcharles93/archie-core/internal/domain/messaging" + "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/domain/taskactions" "github.com/samcharles93/archie-core/internal/events" "github.com/samcharles93/archie-core/internal/gateway" - "github.com/samcharles93/archie-core/internal/infrastructure/edastore" "github.com/samcharles93/archie-core/internal/infrastructure/gatewayrpc" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/infrastructure/staterpc" - "github.com/samcharles93/archie-core/internal/store" "github.com/samcharles93/archie-core/internal/taskstate" "github.com/samcharles93/archie-core/internal/webui" ) @@ -100,10 +100,7 @@ func serveGRPC(t *testing.T, register func(grpc.ServiceRegistrar)) (target strin // every route with no contract behind it degrades exactly as // docs/prds/ui-service-boundary.md:130-131 permits. func TestUIServesDashboardAgainstRemoteContracts(t *testing.T) { - st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "tasks.sqlite")) - if err != nil { - t.Fatalf("open temp store: %v", err) - } + st := pgstore.Open(t) defer st.Close() seeded, err := st.EnqueueChatTask(t.Context(), "acme", "widget", "remote summary", "body", "implement", "") if err != nil { @@ -119,7 +116,7 @@ func TestUIServesDashboardAgainstRemoteContracts(t *testing.T) { if err != nil { t.Fatal(err) } - if err := st.PutConfigSnapshot(t.Context(), store.ConfigSnapshot{ + if err := st.PutConfigSnapshot(t.Context(), storecontract.ConfigSnapshot{ Schema: webui.ConfigViewSchema, Document: published, }); err != nil { t.Fatalf("publish config snapshot: %v", err) @@ -152,7 +149,7 @@ func TestUIServesDashboardAgainstRemoteContracts(t *testing.T) { } stateTarget, stopState := serveGRPC(t, func(r grpc.ServiceRegistrar) { - eda := edastore.OpenTest(t) + eda := pgstore.EDA(t, nil) staterpc.RegisterServer(r, staterpc.Deps{Tasks: st, Captures: eda, BindingDispatcher: eda, ConfigSnapshots: st, Log: slog.New(slog.DiscardHandler)}) }) defer stopState() diff --git a/internal/app/archieui/task_logs_test.go b/internal/app/archieui/task_logs_test.go index dffa54f2e..fe6390d39 100644 --- a/internal/app/archieui/task_logs_test.go +++ b/internal/app/archieui/task_logs_test.go @@ -13,10 +13,9 @@ import ( "google.golang.org/grpc" - "github.com/samcharles93/archie-core/internal/infrastructure/edastore" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/infrastructure/staterpc" "github.com/samcharles93/archie-core/internal/logging" - "github.com/samcharles93/archie-core/internal/store" "github.com/samcharles93/archie-core/internal/webui" ) @@ -154,10 +153,7 @@ func TestUIProcessReportsMissingTaskLogsHonestly(t *testing.T) { // file, so the dashboard's read has to cross the wire to see anything. func composeUIProcessWithLog(t *testing.T) (*webui.Server, int64, int) { t.Helper() - st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "tasks.sqlite")) - if err != nil { - t.Fatalf("open store: %v", err) - } + st := pgstore.Open(t) t.Cleanup(func() { _ = st.Close() }) task, err := st.EnqueueChatTask(t.Context(), "acme", "widget", "a task", "body", "implement", "") @@ -179,7 +175,7 @@ func composeUIProcessWithLog(t *testing.T) (*webui.Server, int64, int) { } target, stop := serveGRPC(t, func(r grpc.ServiceRegistrar) { - eda := edastore.OpenTest(t) + eda := pgstore.EDA(t, nil) staterpc.RegisterServer(r, staterpc.Deps{ Tasks: st, Captures: eda, BindingDispatcher: eda, ConfigSnapshots: st, TaskLogs: logs, Log: slog.New(slog.DiscardHandler), diff --git a/internal/app/controlplane/controlplane.go b/internal/app/controlplane/controlplane.go index 42da58c88..0ba5704ce 100644 --- a/internal/app/controlplane/controlplane.go +++ b/internal/app/controlplane/controlplane.go @@ -11,9 +11,9 @@ import ( "google.golang.org/protobuf/types/known/timestamppb" pb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1" + "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/domain/workflow" "github.com/samcharles93/archie-core/internal/infrastructure/controlplanerpc" - "github.com/samcharles93/archie-core/internal/store" ) // The control-plane wire sentinels cross gRPC matched on (code, canonical @@ -31,9 +31,9 @@ var ( // root asserts the State Store against it, so this is the single definition of // what a control-plane backing store must offer. type ResourceStore interface { - Resource(context.Context, string) (store.Resource, error) - ResourceHistory(context.Context, string, int) ([]store.Resource, error) - PutResource(context.Context, store.ResourceWrite) (store.Resource, error) + Resource(context.Context, string) (storecontract.Resource, error) + ResourceHistory(context.Context, string, int) ([]storecontract.Resource, error) + PutResource(context.Context, storecontract.ResourceWrite) (storecontract.Resource, error) } // defaultHistoryLimit caps an unbounded request. A settings resource edited @@ -121,7 +121,7 @@ func (s *Server) Command(ctx context.Context, request *pb.CommandRequest) (*pb.C if err != nil { return nil, mapError(err) } - resource, err := s.store.PutResource(ctx, store.ResourceWrite{Kind: request.Kind, Value: value, Actor: request.Actor, Source: request.Source, RequestID: request.RequestId, ExpectedVersion: request.ExpectedVersion, At: time.Now().UTC()}) + resource, err := s.store.PutResource(ctx, storecontract.ResourceWrite{Kind: request.Kind, Value: value, Actor: request.Actor, Source: request.Source, RequestID: request.RequestId, ExpectedVersion: request.ExpectedVersion, At: time.Now().UTC()}) if err != nil { return nil, mapError(err) } @@ -142,7 +142,7 @@ func (s *Server) Watch(request *pb.WatchRequest, stream pb.ControlPlaneService_W return err } version = resource.Version - } else if err != nil && !errors.Is(err, store.ErrResourceNotFound) { + } else if err != nil && !errors.Is(err, storecontract.ErrResourceNotFound) { return mapError(err) } select { @@ -153,7 +153,7 @@ func (s *Server) Watch(request *pb.WatchRequest, stream pb.ControlPlaneService_W } } -func resourceProto(resource store.Resource) *pb.Resource { +func resourceProto(resource storecontract.Resource) *pb.Resource { return &pb.Resource{Kind: resource.Kind, Version: resource.Version, ValueJson: resource.Value, UpdatedAt: timestamp(resource.At)} } @@ -168,9 +168,9 @@ func mapError(err error) error { switch { case errors.Is(err, ErrValidation): return status.Error(codes.InvalidArgument, err.Error()) - case errors.Is(err, store.ErrResourceNotFound): + case errors.Is(err, storecontract.ErrResourceNotFound): return status.Error(codes.NotFound, err.Error()) - case errors.Is(err, store.ErrResourceVersionConflict): + case errors.Is(err, storecontract.ErrResourceVersionConflict): return status.Error(codes.Aborted, err.Error()) default: return status.Error(codes.Unavailable, err.Error()) diff --git a/internal/app/controlplane/controlplane_test.go b/internal/app/controlplane/controlplane_test.go index fcbe17061..a73928322 100644 --- a/internal/app/controlplane/controlplane_test.go +++ b/internal/app/controlplane/controlplane_test.go @@ -13,9 +13,10 @@ import ( "github.com/samcharles93/archie-core/internal/config" pb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1" "github.com/samcharles93/archie-core/internal/domain/agent" + "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/domain/workflow" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/infrastructure/workflowsteps" - "github.com/samcharles93/archie-core/internal/store" ) // testSteps builds the production workflow step vocabulary for tests that are @@ -45,7 +46,7 @@ func testServer(t *testing.T, resources ResourceStore) *Server { func TestCatalogCarriesShippedWorkflowDefinitionsForRestore(t *testing.T) { t.Parallel() - resources := store.OpenTest(t) + resources := pgstore.Open(t) defer resources.Close() catalog, err := testServer(t, resources).Catalog(t.Context(), &pb.CatalogRequest{}) if err != nil { @@ -72,7 +73,7 @@ func TestCatalogCarriesShippedWorkflowDefinitionsForRestore(t *testing.T) { func TestImportConfigSeedsWorkflowDefinitionsWithoutOverwritingOverride(t *testing.T) { t.Parallel() - resources := store.OpenTest(t) + resources := pgstore.Open(t) defer resources.Close() server := testServer(t, resources) if _, _, err := server.ImportConfig(t.Context(), config.Config{}); err != nil { @@ -94,7 +95,7 @@ func TestImportConfigSeedsWorkflowDefinitionsWithoutOverwritingOverride(t *testi if err != nil { t.Fatal(err) } - if _, err := resources.PutResource(t.Context(), store.ResourceWrite{Kind: WorkflowDefinitionsKind, Value: value, ExpectedVersion: resource.Version, Actor: "test", Source: "test", RequestID: "override"}); err != nil { + if _, err := resources.PutResource(t.Context(), storecontract.ResourceWrite{Kind: WorkflowDefinitionsKind, Value: value, ExpectedVersion: resource.Version, Actor: "test", Source: "test", RequestID: "override"}); err != nil { t.Fatal(err) } if _, _, err := server.ImportConfig(t.Context(), config.Config{}); err != nil { @@ -112,7 +113,7 @@ func TestImportConfigSeedsWorkflowDefinitionsWithoutOverwritingOverride(t *testi func TestImportConfigSeedsPersonasWithoutOverwritingEdits(t *testing.T) { t.Parallel() - resources := store.OpenTest(t) + resources := pgstore.Open(t) defer resources.Close() server := testServer(t, resources) if _, _, err := server.ImportConfig(t.Context(), config.Config{}); err != nil { @@ -131,7 +132,7 @@ func TestImportConfigSeedsPersonasWithoutOverwritingEdits(t *testing.T) { if err != nil { t.Fatal(err) } - if _, err := resources.PutResource(t.Context(), store.ResourceWrite{Kind: PersonasKind, Value: value, ExpectedVersion: resource.Version, Actor: "test", Source: "test", RequestID: "persona-edit"}); err != nil { + if _, err := resources.PutResource(t.Context(), storecontract.ResourceWrite{Kind: PersonasKind, Value: value, ExpectedVersion: resource.Version, Actor: "test", Source: "test", RequestID: "persona-edit"}); err != nil { t.Fatal(err) } if _, _, err := server.ImportConfig(t.Context(), config.Config{}); err != nil { @@ -150,7 +151,7 @@ func TestImportConfigSeedsPersonasWithoutOverwritingEdits(t *testing.T) { func TestImportWorkflowExecutionSettingsDoesNotOverwriteExistingValue(t *testing.T) { t.Parallel() - resources := store.OpenTest(t) + resources := pgstore.Open(t) defer resources.Close() server := testServer(t, resources) first := workflow.ExecutionSettings{MaxModelToolSteps: 10, MaxRuntime: time.Minute, MaxConsecutiveGateFailures: 2} @@ -176,7 +177,7 @@ func TestImportWorkflowExecutionSettingsDoesNotOverwriteExistingValue(t *testing func TestRegistryRoutesAndValidatesDefinitions(t *testing.T) { t.Parallel() - resources := store.OpenTest(t) + resources := pgstore.Open(t) defer resources.Close() server := testServer(t, resources) // The image is required, here as in the file document: a seed without one is @@ -212,7 +213,7 @@ func TestRegistryRoutesAndValidatesDefinitions(t *testing.T) { func TestProviderSeedKeepsReferencesAndNeverResolvedSecrets(t *testing.T) { t.Parallel() - resources := store.OpenTest(t) + resources := pgstore.Open(t) defer resources.Close() server := testServer(t, resources) cfg := config.Config{Providers: map[string]config.Provider{"openai": {Class: "openai", APIKeyEnv: "OPENAI_API_KEY", APIKey: config.SecretRef{Engine: "env", Key: "OPENAI_API_KEY"}}}} @@ -239,7 +240,7 @@ func TestProviderSeedKeepsReferencesAndNeverResolvedSecrets(t *testing.T) { func TestHistoryCarriesEveryRevisionWithItsAudit(t *testing.T) { t.Parallel() - resources := store.OpenTest(t) + resources := pgstore.Open(t) defer resources.Close() server := testServer(t, resources) if _, _, err := server.ImportConfig(t.Context(), config.Config{}); err != nil { @@ -288,7 +289,7 @@ func TestHistoryCarriesEveryRevisionWithItsAudit(t *testing.T) { func TestImportConfigSkipsASeedItCannotValidate(t *testing.T) { t.Parallel() - resources := store.OpenTest(t) + resources := pgstore.Open(t) defer resources.Close() server := testServer(t, resources) // Every other field is filled in the way the loader fills it (Validate @@ -307,7 +308,7 @@ func TestImportConfigSkipsASeedItCannotValidate(t *testing.T) { if len(skipped) != 1 || skipped[0].Kind != RepositoryPoliciesKind || skipped[0].Err == nil { t.Fatalf("skipped = %+v, want the repository policies and the reason", skipped) } - if _, err := resources.Resource(t.Context(), RepositoryPoliciesKind); !errors.Is(err, store.ErrResourceNotFound) { + if _, err := resources.Resource(t.Context(), RepositoryPoliciesKind); !errors.Is(err, storecontract.ErrResourceNotFound) { t.Errorf("repository policies Resource = %v, want ErrResourceNotFound: an invalid seed must not be stored", err) } // Kinds that are fine are still seeded: one skipped kind does not abandon diff --git a/internal/app/controlplane/controlplane_watch_test.go b/internal/app/controlplane/controlplane_watch_test.go index 0cfbfedd4..ff8308815 100644 --- a/internal/app/controlplane/controlplane_watch_test.go +++ b/internal/app/controlplane/controlplane_watch_test.go @@ -15,8 +15,9 @@ import ( "google.golang.org/grpc/test/bufconn" pb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1" + "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/domain/workflow" - "github.com/samcharles93/archie-core/internal/store" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" ) // scriptedWatchClient is the rpc end of a Watch call whose stream is scripted @@ -222,7 +223,7 @@ func TestWatchClientsDeliverNothingForAStreamThatDidNotFail(t *testing.T) { func TestWatchServesOnlyVersionsAfterTheRequestedOne(t *testing.T) { t.Parallel() - resources := store.OpenTest(t) + resources := pgstore.Open(t) defer resources.Close() server := testServer(t, resources) version, err := server.ImportWorkflowExecutionSettings(t.Context(), workflow.ExecutionSettings{MaxModelToolSteps: 10, MaxRuntime: time.Minute, MaxConsecutiveGateFailures: 2}) @@ -280,7 +281,7 @@ func TestWatchServesOnlyVersionsAfterTheRequestedOne(t *testing.T) { if err != nil { t.Fatal(err) } - if _, err := resources.PutResource(ctx, store.ResourceWrite{Kind: WorkflowExecutionSettingsKind, Value: value, ExpectedVersion: version, Actor: "test", Source: "test", RequestID: "watch-next"}); err != nil { + if _, err := resources.PutResource(ctx, storecontract.ResourceWrite{Kind: WorkflowExecutionSettingsKind, Value: value, ExpectedVersion: version, Actor: "test", Source: "test", RequestID: "watch-next"}); err != nil { t.Fatal(err) } select { diff --git a/internal/app/controlplane/pgtest_test.go b/internal/app/controlplane/pgtest_test.go new file mode 100644 index 000000000..2fbd3b187 --- /dev/null +++ b/internal/app/controlplane/pgtest_test.go @@ -0,0 +1,10 @@ +package controlplane + +import ( + "os" + "testing" + + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest" +) + +func TestMain(m *testing.M) { os.Exit(pgtest.Main(m)) } diff --git a/internal/app/controlplane/registry.go b/internal/app/controlplane/registry.go index eada7eb79..cdea1f87a 100644 --- a/internal/app/controlplane/registry.go +++ b/internal/app/controlplane/registry.go @@ -10,7 +10,7 @@ import ( "github.com/samcharles93/archie-core/internal/config" pb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1" - "github.com/samcharles93/archie-core/internal/store" + "github.com/samcharles93/archie-core/internal/domain/storecontract" ) type Definition struct { @@ -96,7 +96,7 @@ func (s *Server) ImportConfig(ctx context.Context, cfg config.Config) (map[strin versions[definition.Kind] = resource.Version continue } - if !errors.Is(err, store.ErrResourceNotFound) { + if !errors.Is(err, storecontract.ErrResourceNotFound) { return nil, nil, err } value, err := definition.seededValue(cfg) @@ -111,7 +111,7 @@ func (s *Server) ImportConfig(ctx context.Context, cfg config.Config) (map[strin skipped = append(skipped, SeedSkip{Kind: definition.Kind, Err: err}) continue } - resource, err = s.store.PutResource(ctx, store.ResourceWrite{Kind: definition.Kind, Value: value, Actor: "system:migration", Source: "legacy-config", RequestID: "import:" + definition.Kind, ExpectedVersion: 0, At: time.Now().UTC()}) + resource, err = s.store.PutResource(ctx, storecontract.ResourceWrite{Kind: definition.Kind, Value: value, Actor: "system:migration", Source: "legacy-config", RequestID: "import:" + definition.Kind, ExpectedVersion: 0, At: time.Now().UTC()}) if err != nil { return nil, nil, fmt.Errorf("seed %s: %w", definition.Kind, err) } @@ -176,7 +176,7 @@ func (s *Server) ValidateStored(ctx context.Context) (int, error) { var failures []error for _, definition := range s.ordered { resource, err := s.store.Resource(ctx, definition.Kind) - if errors.Is(err, store.ErrResourceNotFound) { + if errors.Is(err, storecontract.ErrResourceNotFound) { continue } if err != nil { diff --git a/internal/app/controlplane/runtime_config.go b/internal/app/controlplane/runtime_config.go index ef4483492..390a923bd 100644 --- a/internal/app/controlplane/runtime_config.go +++ b/internal/app/controlplane/runtime_config.go @@ -8,8 +8,8 @@ import ( "time" "github.com/samcharles93/archie-core/internal/config" + "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/infrastructure/controlplanerpc" - "github.com/samcharles93/archie-core/internal/store" ) // resourceReader is the one read the layering performs: a resource kind's value @@ -72,10 +72,10 @@ type storeReader struct { func (r storeReader) Query(ctx context.Context, kind string, decode func([]byte) error) (int64, bool, error) { resource, err := r.resources.Resource(ctx, kind) - if errors.Is(err, store.ErrResourceNotFound) { + if errors.Is(err, storecontract.ErrResourceNotFound) { seed, ok := r.seeds[kind] if !ok { - return 0, false, fmt.Errorf("read %s: %w", kind, store.ErrResourceNotFound) + return 0, false, fmt.Errorf("read %s: %w", kind, storecontract.ErrResourceNotFound) } if err := decode(seed); err != nil { return 0, false, fmt.Errorf("decode %s seed: %w", kind, err) diff --git a/internal/app/controlplane/step_vocabulary_agreement_test.go b/internal/app/controlplane/step_vocabulary_agreement_test.go index 4c8a37f4f..7700212ac 100644 --- a/internal/app/controlplane/step_vocabulary_agreement_test.go +++ b/internal/app/controlplane/step_vocabulary_agreement_test.go @@ -35,8 +35,8 @@ import ( "github.com/samcharles93/archie-core/internal/app/agentworker" pb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1" "github.com/samcharles93/archie-core/internal/domain/workflow" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/infrastructure/workflowsteps" - "github.com/samcharles93/archie-core/internal/store" "github.com/samcharles93/archie-core/internal/taskrun" ) @@ -191,7 +191,7 @@ func TestEveryProductionResolutionSiteResolvesTheRegisteredStepType(t *testing.T // than dereference it: a nil-pointer panic is the same failure with no clue in // it. func TestNilStepVocabularyFailsClosedAtEveryResolutionSite(t *testing.T) { - resources := store.OpenTest(t) + resources := pgstore.Open(t) t.Cleanup(func() { if err := resources.Close(); err != nil { t.Errorf("close test store: %v", err) @@ -256,7 +256,7 @@ func requireRefusal(t *testing.T, side, stepType string, err error) { func admitThroughStateStore(t *testing.T, steps *workflow.Manager, stepType string) (before, after int64, err error) { t.Helper() - resources := store.OpenTest(t) + resources := pgstore.Open(t) t.Cleanup(func() { if closeErr := resources.Close(); closeErr != nil { t.Errorf("close test store: %v", closeErr) diff --git a/internal/app/controlplane/workflow_settings.go b/internal/app/controlplane/workflow_settings.go index f92f67fb0..2295f61b3 100644 --- a/internal/app/controlplane/workflow_settings.go +++ b/internal/app/controlplane/workflow_settings.go @@ -8,8 +8,8 @@ import ( "time" "github.com/samcharles93/archie-core/internal/config" + "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/domain/workflow" - "github.com/samcharles93/archie-core/internal/store" ) const WorkflowExecutionSettingsKind = "workflow-execution-settings" @@ -27,7 +27,7 @@ func (s *Server) ImportWorkflowExecutionSettings(ctx context.Context, settings w if err == nil { return resource.Version, nil } - if !errors.Is(err, store.ErrResourceNotFound) { + if !errors.Is(err, storecontract.ErrResourceNotFound) { return 0, err } value, err := encodeSettings(settings) @@ -38,7 +38,7 @@ func (s *Server) ImportWorkflowExecutionSettings(ctx context.Context, settings w if err != nil { return 0, err } - resource, err = s.store.PutResource(ctx, store.ResourceWrite{Kind: WorkflowExecutionSettingsKind, Value: value, Actor: "system:migration", Source: "legacy-config", RequestID: "import:" + WorkflowExecutionSettingsKind, ExpectedVersion: 0, At: time.Now().UTC()}) + resource, err = s.store.PutResource(ctx, storecontract.ResourceWrite{Kind: WorkflowExecutionSettingsKind, Value: value, Actor: "system:migration", Source: "legacy-config", RequestID: "import:" + WorkflowExecutionSettingsKind, ExpectedVersion: 0, At: time.Now().UTC()}) return resource.Version, err } diff --git a/internal/daemon/daemon_test.go b/internal/daemon/daemon_test.go index 1ec0d07ff..8c9dbd1be 100644 --- a/internal/daemon/daemon_test.go +++ b/internal/daemon/daemon_test.go @@ -27,10 +27,10 @@ import ( "github.com/samcharles93/archie-core/internal/forge" agentnats "github.com/samcharles93/archie-core/internal/infrastructure/agenttransport/nats" arnats "github.com/samcharles93/archie-core/internal/infrastructure/eventbus/nats" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/logging" "github.com/samcharles93/archie-core/internal/secret" "github.com/samcharles93/archie-core/internal/storage" - "github.com/samcharles93/archie-core/internal/store" "github.com/samcharles93/archie-core/internal/taskrun" "github.com/samcharles93/archie-core/internal/taskstate" "github.com/samcharles93/archie-core/internal/worktree" @@ -558,7 +558,7 @@ func startEmbeddedNATSForDaemon(t *testing.T) *server.Server { // daemonWithNATS returns the daemon, its store, and the concrete bus // client -- tests that drive core-NATS subscriptions directly need the // connection, which the TaskBus contract deliberately does not expose. -func daemonWithNATS(t *testing.T) (*Daemon, *store.Store, *arnats.Client) { +func daemonWithNATS(t *testing.T) (*Daemon, *pgstore.TaskDB, *arnats.Client) { t.Helper() srv := startEmbeddedNATSForDaemon(t) client, err := arnats.Connect(context.Background(), arnats.Config{URL: srv.ClientURL(), Subjects: []string{workintake.SubjectTaskWildcard}, FilterSubject: workintake.SubjectTaskWildcard}, slog.New(slog.DiscardHandler)) @@ -567,7 +567,7 @@ func daemonWithNATS(t *testing.T) (*Daemon, *store.Store, *arnats.Client) { } t.Cleanup(client.Close) - s := store.OpenTest(t) + s := pgstore.Open(t) d := &Daemon{ Cfg: config.NewHolder(config.Config{ Dispatch: config.Dispatch{Labels: map[string]string{ @@ -1115,10 +1115,10 @@ func (f *testForge) React(context.Context, string, string, int, string) error func (f *testForge) VerifyPush(context.Context, string, string) error { return nil } func (f *testForge) LinkBranch(context.Context, string, string, int, string) error { return nil } -func testDaemon(t *testing.T, maxRetries, _ int) (*Daemon, *store.Store, *testForge) { +func testDaemon(t *testing.T, maxRetries, _ int) (*Daemon, *pgstore.TaskDB, *testForge) { t.Helper() - s := store.OpenTest(t) + s := pgstore.Open(t) fg := &testForge{} cfg := config.Config{ @@ -1256,9 +1256,9 @@ func TestDaemonStoresIdentityRunners(t *testing.T) { // only ever be acted on through that identity's own forge client and // worktree manager; it must never fall back to the root d.Forge/d.Trees // or leak into the other identity's client. -func twoIdentityDaemon(t *testing.T) (d *Daemon, s *store.Store, rootFg, archieFg, winterFg *testForge) { +func twoIdentityDaemon(t *testing.T) (d *Daemon, s *pgstore.TaskDB, rootFg, archieFg, winterFg *testForge) { t.Helper() - s = store.OpenTest(t) + s = pgstore.Open(t) rootFg = &testForge{} archieFg = &testForge{} winterFg = &testForge{} @@ -1439,7 +1439,7 @@ func TestStartupSweepsEveryConfiguredForge(t *testing.T) { d := &Daemon{ Cfg: config.NewHolder(config.Config{Repos: tc.rootRepos}), - Store: store.OpenTest(t), + Store: pgstore.Open(t), Forge: rootFg, Log: slog.New(slog.DiscardHandler), Identities: runners, @@ -1499,7 +1499,7 @@ func TestStartupSweepIsolatesAStalledForge(t *testing.T) { siblingFg := &sweepForge{} d := &Daemon{ Cfg: config.NewHolder(config.Config{}), - Store: store.OpenTest(t), + Store: pgstore.Open(t), Forge: rootFg, Log: slog.New(slog.DiscardHandler), Identities: []*IdentityRunner{{Name: "sibling", Forge: siblingFg}}, @@ -2139,7 +2139,7 @@ func TestDispatchCapturesTheAttemptsEffectiveConfig(t *testing.T) { // always fails, so the fail-open policy of the capture can be observed without // breaking everything else the dispatch needs. type failingEventStore struct { - *store.Store + *pgstore.TaskDB } func (f failingEventStore) InsertEvent(context.Context, events.Event) (int64, error) { @@ -2151,7 +2151,7 @@ func (f failingEventStore) InsertEvent(context.Context, events.Event) (int64, er // go out anyway, and nothing may park. func TestCaptureAttemptConfigFailureDoesNotStopTheDispatch(t *testing.T) { d, s, busClient := daemonWithNATS(t) - d.Store = failingEventStore{Store: s} + d.Store = failingEventStore{TaskDB: s} ctx := context.Background() if _, err := s.EnqueueIssue(ctx, "acme", "widget", 6, "t", "b", "", ""); err != nil { diff --git a/internal/daemon/dispatch_bindings_test.go b/internal/daemon/dispatch_bindings_test.go index 362e920fc..d460aaa31 100644 --- a/internal/daemon/dispatch_bindings_test.go +++ b/internal/daemon/dispatch_bindings_test.go @@ -3,16 +3,18 @@ package daemon import ( "log/slog" "os" - "path/filepath" "testing" "time" + "github.com/jackc/pgx/v5/pgxpool" + "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/domain/binding" "github.com/samcharles93/archie-core/internal/domain/mapping" + "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/domain/workflow" - "github.com/samcharles93/archie-core/internal/infrastructure/edastore" - "github.com/samcharles93/archie-core/internal/store" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" ) // Test 30: an armed binding + an authenticated capture creates a task @@ -249,23 +251,20 @@ func TestDispatchBindingsNilDispatcherIsNoOp(t *testing.T) { // production uses (CREATE TABLE + ALTER TABLE migrations), so // binding_id / binding_version / binding_dispatches all exist on the // store by the time a test runs. -// dispatchStores pairs the two stores the dispatcher spans: tasks stay on -// SQLite, event capture is the PocketBase store. They are embedded so a seed -// helper still reads as one handle; the method sets no longer overlap, which -// is exactly what the split bought. +// dispatchStores pairs the two stores the dispatcher spans: the task store and +// the event-capture store, so a seed helper reads as one handle. type dispatchStores struct { - *store.Store - EdaStore *edastore.Store + *pgstore.TaskDB + EdaStore *postgres.EDA + edaPool *pgxpool.Pool } func openDispatchTestStore(t *testing.T) *dispatchStores { t.Helper() - s, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "dispatch.db")) - if err != nil { - t.Fatalf("store.Open: %v", err) - } + s := pgstore.Open(t) t.Cleanup(func() { _ = s.Close() }) - return &dispatchStores{Store: s, EdaStore: edastore.OpenTest(t)} + pool := pgstore.Pool(t) + return &dispatchStores{TaskDB: s, EdaStore: postgres.NewEDA(pool, nil), edaPool: pool} } // seedMapping inserts a mapping with the given fields and returns its id. @@ -327,7 +326,7 @@ func seedArmedBindingWithRepo(t *testing.T, s *dispatchStores, source, mappingID // maxEvents=0's "no cap" reading. func seedCapture(t *testing.T, s *dispatchStores, source string, authenticated bool, body string) { t.Helper() - _, err := s.EdaStore.InsertCapture(t.Context(), store.CapturedEvent{ + _, err := s.EdaStore.InsertCapture(t.Context(), storecontract.CapturedEvent{ Source: source, Body: body, Authenticated: authenticated, @@ -339,7 +338,7 @@ func seedCapture(t *testing.T, s *dispatchStores, source string, authenticated b } // newDispatchDaemon builds a Daemon whose store-related handles all -// point at the same *store.Store so dispatchBindings can resolve +// point at the same *pgstore.TaskDB so dispatchBindings can resolve // captures through the dispatcher handles and mappings through // d.Mappings. Exactly one repo is configured so resolveBindingRepo's // single-repo fallback accepts the dispatch; with zero or many @@ -377,10 +376,9 @@ func assertDispatchRecorded(t *testing.T, s *dispatchStores, bindingID string, t t.Helper() var gotBindingID string var gotTaskID int64 - if err := s.EdaStore.App().DB().NewQuery( - "SELECT binding, task_id FROM binding_dispatches WHERE binding = {:binding}"). - Bind(map[string]any{"binding": bindingID}). - Row(&gotBindingID, &gotTaskID); err != nil { + if err := s.edaPool.QueryRow(t.Context(), + "SELECT binding, task_id FROM binding_dispatches WHERE binding = $1", bindingID). + Scan(&gotBindingID, &gotTaskID); err != nil { t.Fatalf("binding_dispatches row missing: %v", err) } if gotBindingID != bindingID || gotTaskID != taskID { diff --git a/internal/daemon/identity_dispatch_test.go b/internal/daemon/identity_dispatch_test.go index 0bcc6b839..5797ea3e5 100644 --- a/internal/daemon/identity_dispatch_test.go +++ b/internal/daemon/identity_dispatch_test.go @@ -11,7 +11,7 @@ import ( "github.com/samcharles93/archie-core/internal/domain/workflow" "github.com/samcharles93/archie-core/internal/domain/workintake" "github.com/samcharles93/archie-core/internal/eventbus" - "github.com/samcharles93/archie-core/internal/store" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/worktree" ) @@ -36,7 +36,7 @@ var _ eventbus.Message = (*fakeMessage)(nil) // not know must not be written to the store at all. Today it is enqueued and // only fails open later, when forgeFor/repoFor fall back to the root forge. func TestProcessNATSTaskRejectsUnresolvableIdentity(t *testing.T) { - s := store.OpenTest(t) + s := pgstore.Open(t) d := &Daemon{ Store: s, Cfg: config.NewHolder(config.Config{}), @@ -110,7 +110,7 @@ func TestProcessParksTaskWhoseIdentityNoLongerResolves(t *testing.T) { // still has a runner but has been retired may not act, so its tasks park // rather than running under a credential the control plane has retired. func TestProcessParksRetiredIdentity(t *testing.T) { - s := store.OpenTest(t) + s := pgstore.Open(t) ctx := context.Background() log := slog.New(slog.DiscardHandler) diff --git a/internal/daemon/pgtest_test.go b/internal/daemon/pgtest_test.go new file mode 100644 index 000000000..c666a5715 --- /dev/null +++ b/internal/daemon/pgtest_test.go @@ -0,0 +1,10 @@ +package daemon + +import ( + "os" + "testing" + + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest" +) + +func TestMain(m *testing.M) { os.Exit(pgtest.Main(m)) } diff --git a/internal/daemon/playbook_dispatch_test.go b/internal/daemon/playbook_dispatch_test.go index feab28f23..bf8387c77 100644 --- a/internal/daemon/playbook_dispatch_test.go +++ b/internal/daemon/playbook_dispatch_test.go @@ -10,7 +10,7 @@ import ( "github.com/samcharles93/archie-core/internal/domain/eda/module" "github.com/samcharles93/archie-core/internal/domain/eda/playbook" "github.com/samcharles93/archie-core/internal/domain/workflow" - "github.com/samcharles93/archie-core/internal/store" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" ) // playbookStore loads a single playbook document from a temp directory, so @@ -42,7 +42,7 @@ func routableDefinitions() *workflowDefinitionsStub { } // forgeTask enqueues a labelled forge-sourced task and returns its row. -func forgeTask(t *testing.T, resources *store.Store, labels string) *workflow.Task { +func forgeTask(t *testing.T, resources *pgstore.TaskDB, labels string) *workflow.Task { t.Helper() if _, err := resources.EnqueueIssue(t.Context(), "acme", "widget", 7, "title", "body", labels, ""); err != nil { t.Fatal(err) @@ -60,7 +60,7 @@ func forgeTask(t *testing.T, resources *store.Store, labels string) *workflow.Ta // chosen for the same labels. Bypassing the coordinator pins "tdd" (the // default binding for kind bug) and fails this test. func TestPinWorkflowDefinitionPrefersMatchingPlaybook(t *testing.T) { - resources := store.OpenTest(t) + resources := pgstore.Open(t) defer resources.Close() task := forgeTask(t, resources, "bug") @@ -95,7 +95,7 @@ actions: // an additional routing source, not a replacement. A non-matching playbook // set leaves the existing kind/label bindings in charge. func TestPinWorkflowDefinitionFallsBackWhenNoPlaybookMatches(t *testing.T) { - resources := store.OpenTest(t) + resources := pgstore.Open(t) defer resources.Close() task := forgeTask(t, resources, "bug") @@ -125,7 +125,7 @@ actions: // Silently running the kind binding's choice instead would run the wrong // workflow under a rule the operator wrote. func TestPinWorkflowDefinitionPlaybookWorkflowMustExist(t *testing.T) { - resources := store.OpenTest(t) + resources := pgstore.Open(t) defer resources.Close() task := forgeTask(t, resources, "bug") @@ -155,7 +155,7 @@ actions: // assignment is a decision already made about this task and must not be // re-routed by a playbook trigger that still matches its labels. func TestPinWorkflowDefinitionPreAssignedWorkflowBeatsPlaybook(t *testing.T) { - resources := store.OpenTest(t) + resources := pgstore.Open(t) defer resources.Close() task := forgeTask(t, resources, "bug") task.Workflow = "tdd" @@ -203,7 +203,7 @@ actions: {name: "condition false leaves the kind binding in charge", labels: "bug", want: "tdd"}, } { t.Run(tc.name, func(t *testing.T) { - resources := store.OpenTest(t) + resources := pgstore.Open(t) defer resources.Close() task := forgeTask(t, resources, tc.labels) d := &Daemon{ @@ -228,7 +228,7 @@ actions: // recognises still triggers a playbook, which is the only way an operator can // bind a workflow to their own taxonomy without a code change. func TestPinWorkflowDefinitionTriggersOnInstanceDefinedLabel(t *testing.T) { - resources := store.OpenTest(t) + resources := pgstore.Open(t) defer resources.Close() task := forgeTask(t, resources, "ops::security-review,needs-triage") diff --git a/internal/daemon/playbook_run_test.go b/internal/daemon/playbook_run_test.go index 7b7b069b4..7b1851428 100644 --- a/internal/daemon/playbook_run_test.go +++ b/internal/daemon/playbook_run_test.go @@ -8,7 +8,7 @@ import ( "github.com/samcharles93/archie-core/internal/domain/eda/playbook" "github.com/samcharles93/archie-core/internal/domain/storecontract" - "github.com/samcharles93/archie-core/internal/store" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" ) // runRecorder is a playbook set that matches no workflow playbook and records @@ -50,7 +50,7 @@ func TestPinWorkflowDefinitionRunsActionPlaybooks(t *testing.T) { } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { - resources := store.OpenTest(t) + resources := pgstore.Open(t) defer resources.Close() task := forgeTask(t, resources, "bug") task.Workflow = tt.workflow diff --git a/internal/daemon/task_cancellation_test.go b/internal/daemon/task_cancellation_test.go index 838b03b6a..92a51d45c 100644 --- a/internal/daemon/task_cancellation_test.go +++ b/internal/daemon/task_cancellation_test.go @@ -22,8 +22,8 @@ import ( archiecontainer "github.com/samcharles93/archie-core/internal/container" "github.com/samcharles93/archie-core/internal/domain/workflow" agentnats "github.com/samcharles93/archie-core/internal/infrastructure/agenttransport/nats" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/storage" - "github.com/samcharles93/archie-core/internal/store" "github.com/samcharles93/archie-core/internal/taskrun" "github.com/samcharles93/archie-core/internal/taskstate" "github.com/samcharles93/archie-core/internal/worktree" @@ -240,7 +240,7 @@ func TestCleanupTerminalTaskWorktreeWithCancelledContext(t *testing.T) { ctx, cancel := context.WithCancel(context.Background()) cancel() // cancel context before calling cleanup - st := store.OpenTest(t) + st := pgstore.Open(t) t.Cleanup(func() { _ = st.Close() }) trees := &worktree.Manager{WorkDir: t.TempDir()} @@ -409,7 +409,7 @@ func TestParkRunningTaskGuardedAndLogging(t *testing.T) { for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { - s := store.OpenTest(t) + s := pgstore.Open(t) t.Cleanup(func() { _ = s.Close() }) var buf logBuffer @@ -443,7 +443,7 @@ func TestParkRunningTaskGuardedAndLogging(t *testing.T) { } if tt.closeStore { - _ = s.Close() + s.Pool.Close() } d.parkRunningTask(callCtx, task.ID, "simulated park reason", taskstate.ParkTransient) @@ -494,7 +494,7 @@ func TestAcquireTaskContainerFailureParksTaskOnCancelledContext(t *testing.T) { for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { - s := store.OpenTest(t) + s := pgstore.Open(t) t.Cleanup(func() { _ = s.Close() }) d := &Daemon{ diff --git a/internal/daemon/terminal_cleanup_test.go b/internal/daemon/terminal_cleanup_test.go index f23435933..58f5002d8 100644 --- a/internal/daemon/terminal_cleanup_test.go +++ b/internal/daemon/terminal_cleanup_test.go @@ -24,8 +24,8 @@ import ( archiecontainer "github.com/samcharles93/archie-core/internal/container" "github.com/samcharles93/archie-core/internal/domain/workflow" agentnats "github.com/samcharles93/archie-core/internal/infrastructure/agenttransport/nats" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/storage" - "github.com/samcharles93/archie-core/internal/store" "github.com/samcharles93/archie-core/internal/taskrun" "github.com/samcharles93/archie-core/internal/worktree" ) @@ -148,7 +148,7 @@ func TestCleanupTerminalTaskWorktreeLifecycle(t *testing.T) { for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { ctx := context.Background() - st := store.OpenTest(t) + st := pgstore.Open(t) t.Cleanup(func() { _ = st.Close() }) rootTrees := &worktree.Manager{WorkDir: t.TempDir()} diff --git a/internal/daemon/workflow_definition_test.go b/internal/daemon/workflow_definition_test.go index 29096c4e2..7de49ebea 100644 --- a/internal/daemon/workflow_definition_test.go +++ b/internal/daemon/workflow_definition_test.go @@ -5,7 +5,7 @@ import ( "testing" "github.com/samcharles93/archie-core/internal/domain/workflow" - "github.com/samcharles93/archie-core/internal/store" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" ) type workflowDefinitionsStub struct { @@ -18,7 +18,7 @@ func (s *workflowDefinitionsStub) WorkflowDefinitions(context.Context) (workflow } func TestWorkflowDefinitionPinSurvivesActiveOverride(t *testing.T) { - resources := store.OpenTest(t) + resources := pgstore.Open(t) defer resources.Close() task, err := resources.EnqueueChatTask(t.Context(), "acme", "widget", "custom", "", "custom", "operator") if err != nil { diff --git a/internal/domain/workflow/pgtest_test.go b/internal/domain/workflow/pgtest_test.go new file mode 100644 index 000000000..c734ec0bb --- /dev/null +++ b/internal/domain/workflow/pgtest_test.go @@ -0,0 +1,10 @@ +package workflow + +import ( + "os" + "testing" + + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest" +) + +func TestMain(m *testing.M) { os.Exit(pgtest.Main(m)) } diff --git a/internal/domain/workflow/store_integration_test.go b/internal/domain/workflow/store_integration_test.go index 37575e83d..84d3061e7 100644 --- a/internal/domain/workflow/store_integration_test.go +++ b/internal/domain/workflow/store_integration_test.go @@ -4,20 +4,20 @@ import ( "bytes" "context" "log/slog" - "path/filepath" "strings" "testing" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" + "github.com/samcharles93/archie-core/internal/agentexec" "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/domain/workflow" - "github.com/samcharles93/archie-core/internal/store" ) // storeIntegrationRunner is a minimal agentexec.Runner stub, duplicated // here (rather than reused from the in-package tests) because this file // lives in the external workflow_test package: it needs the real -// *store.Store as a workflow.Store, and the package under test now owns +// *pgstore.TaskDB as a workflow.Store, and the package under test now owns // workflow.Task/Status/Source, which would otherwise cycle back through // internal/store's dependency on internal/domain/workflow. type storeIntegrationRunner struct { @@ -44,10 +44,7 @@ func (r *storeIntegrationRunner) Run( // and the store as park_reason, but never the log. A workflow that ends without // an outcome is the smallest way to reach that path. func TestRunRecordsAParkReasonInTheRunsOwnLog(t *testing.T) { - st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "archie.db")) - if err != nil { - t.Fatal(err) - } + st := pgstore.Open(t) t.Cleanup(func() { if err := st.Close(); err != nil { t.Errorf("close store: %v", err) @@ -82,10 +79,7 @@ func TestRunRecordsAParkReasonInTheRunsOwnLog(t *testing.T) { } func TestAgentStagePersistsReturnedNotes(t *testing.T) { - st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "archie.db")) - if err != nil { - t.Fatal(err) - } + st := pgstore.Open(t) t.Cleanup(func() { if err := st.Close(); err != nil { t.Errorf("close store: %v", err) @@ -119,10 +113,7 @@ func TestAgentStagePersistsReturnedNotes(t *testing.T) { } func TestRunLeavesInterruptedTaskForCrashRecovery(t *testing.T) { - st, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "archie.db")) - if err != nil { - t.Fatal(err) - } + st := pgstore.Open(t) t.Cleanup(func() { if err := st.Close(); err != nil { t.Errorf("close store: %v", err) diff --git a/internal/infrastructure/bindingcipher/cipher.go b/internal/infrastructure/bindingcipher/cipher.go index 6c398adaf..9790e8233 100644 --- a/internal/infrastructure/bindingcipher/cipher.go +++ b/internal/infrastructure/bindingcipher/cipher.go @@ -1,4 +1,6 @@ -package edastore +// Package bindingcipher seals binding secrets at rest with AES-256-GCM under +// a rotatable keyring. +package bindingcipher import ( "crypto/aes" diff --git a/internal/infrastructure/bindingcipher/cipher_test.go b/internal/infrastructure/bindingcipher/cipher_test.go index 42ae13d26..769b3f3b6 100644 --- a/internal/infrastructure/bindingcipher/cipher_test.go +++ b/internal/infrastructure/bindingcipher/cipher_test.go @@ -1,8 +1,7 @@ -package edastore +package bindingcipher import ( "encoding/base64" - "path/filepath" "strings" "testing" ) @@ -121,110 +120,6 @@ func TestBindingCipherDerivesDistinctKeys(t *testing.T) { } } -// openWithCipher builds a store whose binding secrets are encrypted at rest. -func openWithCipher(t *testing.T, cipher BindingCipher) *Store { - t.Helper() - dir := t.TempDir() - s, err := Open(Config{ - DBPath: filepath.Join(dir, "eda.sqlite"), - DataDir: filepath.Join(dir, "pb_data"), - Cipher: cipher, - }) - if err != nil { - t.Fatalf("Open() error = %v", err) - } - t.Cleanup(func() { _ = s.Close() }) - return s -} - -func sampleBinding() bindingInput { - return bindingInput{Name: "n", Source: "sentry", Workflow: "implement", Secret: "supersecretvalue0123"} -} - -// TestBindingSecretIsEncryptedAtRest pins that the plaintext secret never -// reaches the database file. Reading the column directly is the point: a -// round-trip through the store would decrypt and prove nothing. -func TestBindingSecretIsEncryptedAtRest(t *testing.T) { - cipher, err := NewBindingCipher(testBindingKey, nil) - if err != nil { - t.Fatalf("NewBindingCipher() error = %v", err) - } - s := openWithCipher(t, cipher) - in := sampleBinding() - id := insertBinding(t, s, in) - - var stored string - if err := s.App().DB().NewQuery("SELECT secret FROM " + CollBindings + " WHERE id = {:id}"). - Bind(map[string]any{"id": id}).Row(&stored); err != nil { - t.Fatalf("read raw secret: %v", err) - } - if stored == in.Secret { - t.Fatal("secret is stored as plaintext; it must be encrypted at rest") - } - if !strings.Contains(stored, ":") { - t.Errorf("stored secret %q does not look like a cipher envelope", stored) - } -} - -// TestBindingSecretDecryptsOnRead pins the other half: what was encrypted -// comes back as the original plaintext. -func TestBindingSecretDecryptsOnRead(t *testing.T) { - cipher, _ := NewBindingCipher(testBindingKey, nil) - s := openWithCipher(t, cipher) - in := sampleBinding() - id := insertBinding(t, s, in) - - got, err := s.GetBinding(t.Context(), id) - if err != nil { - t.Fatalf("GetBinding() error = %v", err) - } - if got.Secret != in.Secret { - t.Errorf("Secret = %q, want %q", got.Secret, in.Secret) - } -} - -// TestNoCipherKeepsPlaintext pins the behaviour that predates encryption: a -// deployment with no configured key still works, storing plaintext. -func TestNoCipherKeepsPlaintext(t *testing.T) { - s := openWithCipher(t, nil) - in := sampleBinding() - id := insertBinding(t, s, in) - - var stored string - if err := s.App().DB().NewQuery("SELECT secret FROM " + CollBindings + " WHERE id = {:id}"). - Bind(map[string]any{"id": id}).Row(&stored); err != nil { - t.Fatalf("read raw secret: %v", err) - } - if stored != in.Secret { - t.Errorf("stored secret = %q, want the plaintext %q with no cipher configured", stored, in.Secret) - } -} - -// TestRotatedKeyStillReadsOldRows pins key rotation: a secret written under -// the previous key must stay readable once a new active key is installed, -// otherwise a rotation silently bricks every armed binding. -func TestRotatedKeyStillReadsOldRows(t *testing.T) { - const oldKey = "fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210" - oldCipher, _ := NewBindingCipher(oldKey, nil) - s := openWithCipher(t, oldCipher) - in := sampleBinding() - id := insertBinding(t, s, in) - - rotated, err := NewBindingCipher(testBindingKey, []string{oldKey}) - if err != nil { - t.Fatalf("NewBindingCipher(rotated) error = %v", err) - } - s.cipher = rotated - - got, err := s.GetBinding(t.Context(), id) - if err != nil { - t.Fatalf("GetBinding() after rotation error = %v", err) - } - if got.Secret != in.Secret { - t.Errorf("Secret after rotation = %q, want %q: the previous key must still decrypt", got.Secret, in.Secret) - } -} - // tamperEnvelope flips one byte inside the ciphertext region so Decrypt must // fail authentication rather than return altered plaintext. func tamperEnvelope(t *testing.T, envelope string) string { diff --git a/internal/infrastructure/captureintake/pgtest_test.go b/internal/infrastructure/captureintake/pgtest_test.go new file mode 100644 index 000000000..f3fea01d9 --- /dev/null +++ b/internal/infrastructure/captureintake/pgtest_test.go @@ -0,0 +1,10 @@ +package captureintake + +import ( + "os" + "testing" + + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest" +) + +func TestMain(m *testing.M) { os.Exit(pgtest.Main(m)) } diff --git a/internal/infrastructure/captureintake/receiver_test.go b/internal/infrastructure/captureintake/receiver_test.go index 7889ff515..29400ece4 100644 --- a/internal/infrastructure/captureintake/receiver_test.go +++ b/internal/infrastructure/captureintake/receiver_test.go @@ -14,9 +14,10 @@ import ( "time" "github.com/samcharles93/archie-core/internal/domain/binding" + "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/events" - "github.com/samcharles93/archie-core/internal/infrastructure/edastore" - "github.com/samcharles93/archie-core/internal/store" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/webhookguard" ) @@ -39,7 +40,7 @@ type testReceiver struct { *Receiver // store is the event-capture store the receiver writes through, kept so a // test asserts on persisted rows rather than on a mock's recollection. - store *edastore.Store + store *postgres.EDA } // Handler serves the receiver's route the way its host process mounts it, @@ -60,7 +61,7 @@ func captureTestServerWithoutStore(t *testing.T) testReceiver { func captureTestServer(t *testing.T) testReceiver { t.Helper() - s := edastore.OpenTest(t) + s := pgstore.EDA(t, nil) return testReceiver{ Receiver: &Receiver{ Log: slog.New(slog.DiscardHandler), @@ -131,7 +132,7 @@ func (s *stubBindingStore) RecordDispatch( return nil } -func (s *stubBindingStore) ListUndispatchedCaptures(_ context.Context, _ []string, _ int) ([]store.CapturedEvent, error) { +func (s *stubBindingStore) ListUndispatchedCaptures(_ context.Context, _ []string, _ int) ([]storecontract.CapturedEvent, error) { return nil, nil } @@ -420,10 +421,10 @@ func TestHandleCaptureWithoutCapturesConfiguredIs503(t *testing.T) { // captureInsertErrorStore forces InsertCapture to fail so the handler's // error path is exercised without relying on a real storage failure. type captureInsertErrorStore struct { - store.CaptureStore + storecontract.CaptureStore } -func (captureInsertErrorStore) InsertCapture(context.Context, store.CapturedEvent, time.Duration, int) (string, error) { +func (captureInsertErrorStore) InsertCapture(context.Context, storecontract.CapturedEvent, time.Duration, int) (string, error) { return "", errors.New("boom") } diff --git a/internal/infrastructure/gatewayrpc/conformance_test.go b/internal/infrastructure/gatewayrpc/conformance_test.go index 52f749398..4e135ece0 100644 --- a/internal/infrastructure/gatewayrpc/conformance_test.go +++ b/internal/infrastructure/gatewayrpc/conformance_test.go @@ -15,9 +15,9 @@ import ( "google.golang.org/grpc/test/bufconn" "github.com/samcharles93/archie-core/internal/domain/messaging" + "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/domain/taskactions" "github.com/samcharles93/archie-core/internal/gateway" - "github.com/samcharles93/archie-core/internal/store" "github.com/samcharles93/archie-core/internal/taskstate" ) @@ -213,7 +213,7 @@ func TestTaskActionErrorsKeepTheirSentinelOverGRPC(t *testing.T) { }{ {name: "not found", err: fmt.Errorf("task 7: %w", taskactions.ErrNotFound)}, {name: "conflict", err: fmt.Errorf("%w: action \"approve\" is not available while task is parked", taskactions.ErrConflict)}, - {name: "stale transition", err: fmt.Errorf("stop task 7: %w", store.ErrStaleTransition)}, + {name: "stale transition", err: fmt.Errorf("stop task 7: %w", storecontract.ErrStaleTransition)}, {name: "unavailable", err: taskactions.ErrUnavailable}, } { t.Run(tc.name, func(t *testing.T) { diff --git a/internal/infrastructure/legacyimport/legacyfixture/legacyfixture.go b/internal/infrastructure/legacyimport/legacyfixture/legacyfixture.go new file mode 100644 index 000000000..3425069b1 --- /dev/null +++ b/internal/infrastructure/legacyimport/legacyfixture/legacyfixture.go @@ -0,0 +1,157 @@ +// Package legacyfixture writes the legacy SQLite files an existing install +// holds, for tests of the one-time import and the boot gate that requires it. +package legacyfixture + +import ( + "database/sql" + "path/filepath" + "testing" + + _ "modernc.org/sqlite" +) + +// StateStoreDDL, EDADDL and GatewayDDL apply the legacy schemas as their production openers leave +// them, columns added by ALTER TABLE included, with values in the layouts the +// production writers used. +const StateStoreDDL = ` +CREATE TABLE tasks (id INTEGER PRIMARY KEY AUTOINCREMENT, owner TEXT NOT NULL, repo TEXT NOT NULL, + issue_number INTEGER NOT NULL, title TEXT DEFAULT '', body TEXT DEFAULT '', labels TEXT DEFAULT '', + status TEXT DEFAULT 'queued', workflow TEXT DEFAULT '', stage TEXT DEFAULT '', branch TEXT DEFAULT '', + plan TEXT DEFAULT '', notes TEXT DEFAULT '', pr_number INTEGER DEFAULT 0, tokens_used INTEGER DEFAULT 0, + iterations INTEGER DEFAULT 0, attempt INTEGER DEFAULT 0, park_reason TEXT DEFAULT '', + watch_comment_id INTEGER DEFAULT 0, park_class TEXT DEFAULT 'needs_human', remediation_rounds INTEGER DEFAULT 0, + retry_count INTEGER DEFAULT 0, source TEXT DEFAULT 'forge', identity TEXT DEFAULT '', binding_id TEXT DEFAULT '', + binding_version INTEGER DEFAULT 0, review_payload TEXT DEFAULT '', workflow_definition_version INTEGER DEFAULT 0, + workflow_definition_digest TEXT DEFAULT '', workflow_definition_yaml TEXT DEFAULT '', + created_at TEXT DEFAULT (datetime('now')), updated_at TEXT DEFAULT (datetime('now'))); +ALTER TABLE tasks ADD COLUMN review_cursor INTEGER NOT NULL DEFAULT 0; +CREATE TABLE transitions (id INTEGER PRIMARY KEY AUTOINCREMENT, task_id INTEGER NOT NULL, + at TEXT DEFAULT (datetime('now')), from_status TEXT NOT NULL, to_status TEXT NOT NULL, detail TEXT DEFAULT ''); +CREATE TABLE events (id INTEGER PRIMARY KEY AUTOINCREMENT, at TEXT NOT NULL, kind TEXT NOT NULL, + task_id INTEGER DEFAULT 0, repo TEXT DEFAULT '', issue INTEGER DEFAULT 0, workflow TEXT DEFAULT '', + stage TEXT DEFAULT '', attempt INTEGER DEFAULT 0, actor_id TEXT DEFAULT '', actor_kind TEXT DEFAULT '', + principal_id TEXT DEFAULT '', detail TEXT DEFAULT '', data TEXT DEFAULT '{}'); +CREATE TABLE resources (kind TEXT PRIMARY KEY, value BLOB NOT NULL, version INTEGER NOT NULL, updated_at TEXT NOT NULL); +CREATE TABLE resource_history (id INTEGER PRIMARY KEY AUTOINCREMENT, kind TEXT NOT NULL, value BLOB NOT NULL, + version INTEGER NOT NULL, actor TEXT NOT NULL, source TEXT NOT NULL, request_id TEXT NOT NULL, + expected_version INTEGER NOT NULL, current_version INTEGER NOT NULL, at TEXT NOT NULL); +CREATE TABLE channel_status (id TEXT PRIMARY KEY, name TEXT DEFAULT '', state TEXT DEFAULT '', detail TEXT DEFAULT '', + configured INTEGER NOT NULL DEFAULT 0, reload_supported INTEGER NOT NULL DEFAULT 0, observed_at TEXT NOT NULL); +CREATE TABLE apply_status (process TEXT NOT NULL, kind TEXT NOT NULL, applied_version INTEGER DEFAULT 0, + error TEXT DEFAULT '', reported_at TEXT NOT NULL, PRIMARY KEY (process, kind)); +CREATE TABLE config_snapshot (id INTEGER PRIMARY KEY CHECK (id = 1), schema TEXT DEFAULT '', document TEXT DEFAULT '', + published_at TEXT NOT NULL); +CREATE TABLE identities (id TEXT PRIMARY KEY, kind TEXT NOT NULL, display_name TEXT NOT NULL, lifecycle TEXT NOT NULL, + version INTEGER NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL); +CREATE TABLE identity_aliases (alias TEXT PRIMARY KEY COLLATE NOCASE, identity_id TEXT NOT NULL REFERENCES identities(id)); +CREATE TABLE identity_events (id INTEGER PRIMARY KEY AUTOINCREMENT, identity_id TEXT NOT NULL, event_type TEXT NOT NULL, + from_lifecycle TEXT NOT NULL, to_lifecycle TEXT NOT NULL, display_name TEXT NOT NULL, actor_id TEXT NOT NULL, + source TEXT NOT NULL, request_id TEXT NOT NULL UNIQUE, at TEXT NOT NULL); +CREATE TABLE identity_subjects (issuer TEXT NOT NULL, subject TEXT NOT NULL, + identity_id TEXT NOT NULL REFERENCES identities(id), bound_at TEXT NOT NULL, PRIMARY KEY (issuer, subject)); + +INSERT INTO tasks (id, owner, repo, issue_number, review_cursor, created_at, updated_at) VALUES + (1, 'o', 'r', 7, 3, '2026-01-01 00:00:00', '2026-01-01 00:00:01'), + (4, 'o', 'r', 1000000000000000, 0, '2026-01-02 00:00:00', '2026-01-02 00:00:00'), + (9, 'o', 'r', 8, 0, '2026-01-02 00:00:00', '2026-01-02 00:00:00'); +DELETE FROM tasks WHERE id = 9; +INSERT INTO transitions (task_id, at, from_status, to_status) VALUES (1, '2026-01-01 00:00:00', 'queued', 'running'); +INSERT INTO events (id, at, kind, data) VALUES + (1, '2026-01-01T00:00:00.000000100Z', 'a', 'null'), + (2, '2026-01-01T00:00:01.000000000Z', 'b', '{"k":1}'), + (5, '2026-01-01T00:00:00.500000000Z', 'c', '{}'); +INSERT INTO resources VALUES ('config', X'00ff10', 2, '2026-01-01T00:00:00.123456789Z'); +INSERT INTO resource_history (kind, value, version, actor, source, request_id, expected_version, current_version, at) + VALUES ('config', X'00ff10', 2, 'sam', 'ui', 'req-1', 1, 1, '2026-01-01T00:00:00Z'); +INSERT INTO channel_status VALUES ('tg', 'Telegram', 'up', '', 1, 0, '2026-01-01T00:00:00Z'); +INSERT INTO apply_status VALUES ('daemon', 'config', 2, '', '2026-01-01T00:00:00Z'); +INSERT INTO config_snapshot VALUES (1, 's', '{}', '2026-01-01T00:00:00Z'); +INSERT INTO identities VALUES ('id-1', 'agent', 'Archie', 'active', 1, '2026-01-01T00:00:00Z', '2026-01-01T00:00:00Z'); +INSERT INTO identity_aliases VALUES ('archie', 'id-1'); +INSERT INTO identity_events (identity_id, event_type, from_lifecycle, to_lifecycle, display_name, actor_id, source, request_id, at) + VALUES ('id-1', 'created', '', 'active', 'Archie', 'sam', 'boot', 'rq-1', '2026-01-01T00:00:00Z'); +INSERT INTO identity_subjects VALUES ('https://issuer', 'sub-1', 'id-1', '2026-01-01T00:00:00Z'); +` + +// Secret is an encrypted binding secret envelope; it must arrive unchanged. +const Secret = "arcie-binding:v1:0123456789abcdef:AbC-_dEf012" + +const EDADDL = ` +CREATE TABLE captures (id TEXT PRIMARY KEY NOT NULL, authenticated BOOLEAN DEFAULT FALSE NOT NULL, + body TEXT DEFAULT '' NOT NULL, content_type TEXT DEFAULT '' NOT NULL, headers JSON DEFAULT NULL, + received_at TEXT DEFAULT '' NOT NULL, remote_addr TEXT DEFAULT '' NOT NULL, source TEXT DEFAULT '' NOT NULL); +CREATE TABLE mappings (id TEXT PRIMARY KEY NOT NULL, created_at TEXT DEFAULT '' NOT NULL, fields JSON DEFAULT NULL, + name TEXT DEFAULT '' NOT NULL, source_hint TEXT DEFAULT '' NOT NULL, updated_at TEXT DEFAULT '' NOT NULL); +CREATE TABLE bindings (id TEXT PRIMARY KEY NOT NULL, created_at TEXT DEFAULT '' NOT NULL, mapping TEXT DEFAULT '' NOT NULL, + name TEXT DEFAULT '' NOT NULL, owner TEXT DEFAULT '' NOT NULL, repo TEXT DEFAULT '' NOT NULL, + secret TEXT DEFAULT '' NOT NULL, source TEXT DEFAULT '' NOT NULL, status TEXT DEFAULT '' NOT NULL, + updated_at TEXT DEFAULT '' NOT NULL, version NUMERIC DEFAULT 0 NOT NULL, workflow TEXT DEFAULT '' NOT NULL); +CREATE TABLE binding_dispatches (id TEXT PRIMARY KEY NOT NULL, binding TEXT DEFAULT '' NOT NULL, + binding_version NUMERIC DEFAULT 0 NOT NULL, capture TEXT DEFAULT '' NOT NULL, dispatched_at TEXT DEFAULT '' NOT NULL, + task_id NUMERIC DEFAULT 0 NOT NULL); +CREATE UNIQUE INDEX idx_binding_dispatch_once ON binding_dispatches (binding, capture); +CREATE TABLE playbook_dispatches (id TEXT PRIMARY KEY NOT NULL, action_id TEXT DEFAULT '' NOT NULL, + dispatched_at TEXT DEFAULT '' NOT NULL, event_id TEXT DEFAULT '' NOT NULL, playbook_id TEXT DEFAULT '' NOT NULL, + playbook_version TEXT DEFAULT '' NOT NULL); +CREATE TABLE tool_calls (id TEXT PRIMARY KEY NOT NULL, args JSON DEFAULT NULL, attempt NUMERIC DEFAULT 0 NOT NULL, + called_at TEXT DEFAULT '' NOT NULL, duration_ms NUMERIC DEFAULT 0 NOT NULL, error TEXT DEFAULT '' NOT NULL, + result JSON DEFAULT NULL, task_id NUMERIC DEFAULT 0 NOT NULL, tool TEXT DEFAULT '' NOT NULL); + +INSERT INTO captures VALUES ('rcap1', 1, '{}', 'application/json', '{"x":["1"]}', '2026-01-01T00:00:00.000000000Z', '127.0.0.1', 'gh'); +INSERT INTO captures VALUES ('rcap2', 0, '', '', NULL, '2026-01-01T00:00:01.000000000Z', '', 'gh'); +INSERT INTO mappings VALUES ('rmap1', '2026-01-01 00:00:00.000Z', '[]', 'm', 'gh', '2026-01-01 00:00:00.000Z'); +INSERT INTO bindings VALUES ('rbind1', '2026-01-01 00:00:00.000Z', 'rmap1', 'b', 'o', 'r', '` + Secret + `', 'gh', 'armed', '2026-01-01 00:00:00.000Z', 1, 'implement'); +INSERT INTO binding_dispatches VALUES ('rdisp1', 'rbind1', 1, 'rcap1', '2026-01-01 00:00:00.000Z', 4); +INSERT INTO playbook_dispatches VALUES ('rpb1', 'act', '2026-01-01 00:00:00.000Z', 'ev', 'pb', 'v1'); +INSERT INTO tool_calls VALUES ('rtool1', NULL, 1, '2026-01-01 00:00:00.000Z', 12, '', '"exit 0"', 4, 'bash'); +` + +const GatewayDDL = ` +CREATE TABLE sessions (session_id TEXT PRIMARY KEY, platform TEXT NOT NULL DEFAULT '', bot_user TEXT NOT NULL DEFAULT '', + channel_id TEXT NOT NULL DEFAULT '', thread_id TEXT NOT NULL DEFAULT '', title TEXT NOT NULL DEFAULT '', + parent_session_id TEXT NOT NULL DEFAULT '', branch_name TEXT NOT NULL DEFAULT '', + created_at INTEGER NOT NULL DEFAULT 0, last_active_at INTEGER NOT NULL DEFAULT 0); +CREATE TABLE messages (id INTEGER PRIMARY KEY AUTOINCREMENT, message_id TEXT NOT NULL, session_id TEXT NOT NULL, + source_id TEXT NOT NULL DEFAULT '', sender TEXT NOT NULL DEFAULT '', text TEXT NOT NULL DEFAULT '', ts INTEGER NOT NULL, + UNIQUE(session_id, message_id)); +ALTER TABLE messages ADD COLUMN role TEXT NOT NULL DEFAULT ''; +ALTER TABLE messages ADD COLUMN sender_id TEXT NOT NULL DEFAULT ''; +CREATE VIRTUAL TABLE messages_fts USING fts5(sender, text, content='messages', content_rowid='id'); +CREATE TRIGGER messages_ai AFTER INSERT ON messages BEGIN + INSERT INTO messages_fts(rowid, sender, text) VALUES (new.id, new.sender, new.text); +END; +CREATE TABLE turns (turn_id TEXT PRIMARY KEY, session_id TEXT NOT NULL, source_id TEXT NOT NULL DEFAULT '', + status TEXT NOT NULL, attempt INTEGER NOT NULL DEFAULT 0, owner_id TEXT NOT NULL DEFAULT '', + input_message_id TEXT NOT NULL DEFAULT '', assistant_message_id TEXT NOT NULL DEFAULT '', + partial_text TEXT NOT NULL DEFAULT '', response_text TEXT NOT NULL DEFAULT '', tool_calls TEXT NOT NULL DEFAULT '[]', + error TEXT NOT NULL DEFAULT '', created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL); + +INSERT INTO sessions VALUES ('s1', 'telegram', 'bot', 'c1', '', 'Chat', '', '', 1000, 2000); +INSERT INTO messages (message_id, session_id, sender, text, ts, role) VALUES ('m1', 's1', 'sam', 'hello there', 1000, 'user'); +INSERT INTO messages (message_id, session_id, sender, text, ts, role) VALUES ('m2', 's1', 'archie', 'hi', 1001, 'assistant'); +INSERT INTO turns VALUES ('t1', 's1', '', 'done', 1, '', 'm1', 'm2', '', 'hi', '[]', '', 1000, 1001); +` + +// Install writes the three legacy files the configured db_path names in dir +// and returns their paths. +func Install(t testing.TB, dbPath string) (stateStore, eda, gateway string) { + t.Helper() + stateStore, eda, gateway = dbPath+"-tasks.sqlite", dbPath+"-eda.sqlite", dbPath+"-conversations.sqlite" + Exec(t, stateStore, StateStoreDDL) + Exec(t, eda, EDADDL) + Exec(t, gateway, GatewayDDL) + return stateStore, eda, gateway +} + +// Exec runs stmt against the SQLite file at path, creating it if absent. +func Exec(t testing.TB, path, stmt string) { + t.Helper() + db, err := sql.Open("sqlite", "file:"+path) + if err != nil { + t.Fatalf("open fixture: %v", err) + } + defer func() { _ = db.Close() }() + if _, err := db.ExecContext(t.Context(), stmt); err != nil { + t.Fatalf("fixture %s: %v", filepath.Base(path), err) + } +} diff --git a/internal/infrastructure/legacyimport/legacyimport_test.go b/internal/infrastructure/legacyimport/legacyimport_test.go index 0c07fb6cc..843a39286 100644 --- a/internal/infrastructure/legacyimport/legacyimport_test.go +++ b/internal/infrastructure/legacyimport/legacyimport_test.go @@ -3,7 +3,6 @@ package legacyimport import ( "bytes" "crypto/sha256" - "database/sql" "errors" "os" "path/filepath" @@ -11,175 +10,34 @@ import ( "testing" "github.com/jackc/pgx/v5/pgxpool" - _ "modernc.org/sqlite" + "github.com/samcharles93/archie-core/internal/infrastructure/legacyimport/legacyfixture" "github.com/samcharles93/archie-core/internal/infrastructure/postgres" "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest" ) func TestMain(m *testing.M) { os.Exit(pgtest.Main(m)) } -// The fixtures apply the legacy schemas as their production openers leave -// them, columns added by ALTER TABLE included, with values in the layouts the -// production writers used. -const stateStoreDDL = ` -CREATE TABLE tasks (id INTEGER PRIMARY KEY AUTOINCREMENT, owner TEXT NOT NULL, repo TEXT NOT NULL, - issue_number INTEGER NOT NULL, title TEXT DEFAULT '', body TEXT DEFAULT '', labels TEXT DEFAULT '', - status TEXT DEFAULT 'queued', workflow TEXT DEFAULT '', stage TEXT DEFAULT '', branch TEXT DEFAULT '', - plan TEXT DEFAULT '', notes TEXT DEFAULT '', pr_number INTEGER DEFAULT 0, tokens_used INTEGER DEFAULT 0, - iterations INTEGER DEFAULT 0, attempt INTEGER DEFAULT 0, park_reason TEXT DEFAULT '', - watch_comment_id INTEGER DEFAULT 0, park_class TEXT DEFAULT 'needs_human', remediation_rounds INTEGER DEFAULT 0, - retry_count INTEGER DEFAULT 0, source TEXT DEFAULT 'forge', identity TEXT DEFAULT '', binding_id TEXT DEFAULT '', - binding_version INTEGER DEFAULT 0, review_payload TEXT DEFAULT '', workflow_definition_version INTEGER DEFAULT 0, - workflow_definition_digest TEXT DEFAULT '', workflow_definition_yaml TEXT DEFAULT '', - created_at TEXT DEFAULT (datetime('now')), updated_at TEXT DEFAULT (datetime('now'))); -ALTER TABLE tasks ADD COLUMN review_cursor INTEGER NOT NULL DEFAULT 0; -CREATE TABLE transitions (id INTEGER PRIMARY KEY AUTOINCREMENT, task_id INTEGER NOT NULL, - at TEXT DEFAULT (datetime('now')), from_status TEXT NOT NULL, to_status TEXT NOT NULL, detail TEXT DEFAULT ''); -CREATE TABLE events (id INTEGER PRIMARY KEY AUTOINCREMENT, at TEXT NOT NULL, kind TEXT NOT NULL, - task_id INTEGER DEFAULT 0, repo TEXT DEFAULT '', issue INTEGER DEFAULT 0, workflow TEXT DEFAULT '', - stage TEXT DEFAULT '', attempt INTEGER DEFAULT 0, actor_id TEXT DEFAULT '', actor_kind TEXT DEFAULT '', - principal_id TEXT DEFAULT '', detail TEXT DEFAULT '', data TEXT DEFAULT '{}'); -CREATE TABLE resources (kind TEXT PRIMARY KEY, value BLOB NOT NULL, version INTEGER NOT NULL, updated_at TEXT NOT NULL); -CREATE TABLE resource_history (id INTEGER PRIMARY KEY AUTOINCREMENT, kind TEXT NOT NULL, value BLOB NOT NULL, - version INTEGER NOT NULL, actor TEXT NOT NULL, source TEXT NOT NULL, request_id TEXT NOT NULL, - expected_version INTEGER NOT NULL, current_version INTEGER NOT NULL, at TEXT NOT NULL); -CREATE TABLE channel_status (id TEXT PRIMARY KEY, name TEXT DEFAULT '', state TEXT DEFAULT '', detail TEXT DEFAULT '', - configured INTEGER NOT NULL DEFAULT 0, reload_supported INTEGER NOT NULL DEFAULT 0, observed_at TEXT NOT NULL); -CREATE TABLE apply_status (process TEXT NOT NULL, kind TEXT NOT NULL, applied_version INTEGER DEFAULT 0, - error TEXT DEFAULT '', reported_at TEXT NOT NULL, PRIMARY KEY (process, kind)); -CREATE TABLE config_snapshot (id INTEGER PRIMARY KEY CHECK (id = 1), schema TEXT DEFAULT '', document TEXT DEFAULT '', - published_at TEXT NOT NULL); -CREATE TABLE identities (id TEXT PRIMARY KEY, kind TEXT NOT NULL, display_name TEXT NOT NULL, lifecycle TEXT NOT NULL, - version INTEGER NOT NULL, created_at TEXT NOT NULL, updated_at TEXT NOT NULL); -CREATE TABLE identity_aliases (alias TEXT PRIMARY KEY COLLATE NOCASE, identity_id TEXT NOT NULL REFERENCES identities(id)); -CREATE TABLE identity_events (id INTEGER PRIMARY KEY AUTOINCREMENT, identity_id TEXT NOT NULL, event_type TEXT NOT NULL, - from_lifecycle TEXT NOT NULL, to_lifecycle TEXT NOT NULL, display_name TEXT NOT NULL, actor_id TEXT NOT NULL, - source TEXT NOT NULL, request_id TEXT NOT NULL UNIQUE, at TEXT NOT NULL); -CREATE TABLE identity_subjects (issuer TEXT NOT NULL, subject TEXT NOT NULL, - identity_id TEXT NOT NULL REFERENCES identities(id), bound_at TEXT NOT NULL, PRIMARY KEY (issuer, subject)); - -INSERT INTO tasks (id, owner, repo, issue_number, review_cursor, created_at, updated_at) VALUES - (1, 'o', 'r', 7, 3, '2026-01-01 00:00:00', '2026-01-01 00:00:01'), - (4, 'o', 'r', 1000000000000000, 0, '2026-01-02 00:00:00', '2026-01-02 00:00:00'), - (9, 'o', 'r', 8, 0, '2026-01-02 00:00:00', '2026-01-02 00:00:00'); -DELETE FROM tasks WHERE id = 9; -INSERT INTO transitions (task_id, at, from_status, to_status) VALUES (1, '2026-01-01 00:00:00', 'queued', 'running'); -INSERT INTO events (id, at, kind, data) VALUES - (1, '2026-01-01T00:00:00.000000100Z', 'a', 'null'), - (2, '2026-01-01T00:00:01.000000000Z', 'b', '{"k":1}'), - (5, '2026-01-01T00:00:00.500000000Z', 'c', '{}'); -INSERT INTO resources VALUES ('config', X'00ff10', 2, '2026-01-01T00:00:00.123456789Z'); -INSERT INTO resource_history (kind, value, version, actor, source, request_id, expected_version, current_version, at) - VALUES ('config', X'00ff10', 2, 'sam', 'ui', 'req-1', 1, 1, '2026-01-01T00:00:00Z'); -INSERT INTO channel_status VALUES ('tg', 'Telegram', 'up', '', 1, 0, '2026-01-01T00:00:00Z'); -INSERT INTO apply_status VALUES ('daemon', 'config', 2, '', '2026-01-01T00:00:00Z'); -INSERT INTO config_snapshot VALUES (1, 's', '{}', '2026-01-01T00:00:00Z'); -INSERT INTO identities VALUES ('id-1', 'agent', 'Archie', 'active', 1, '2026-01-01T00:00:00Z', '2026-01-01T00:00:00Z'); -INSERT INTO identity_aliases VALUES ('archie', 'id-1'); -INSERT INTO identity_events (identity_id, event_type, from_lifecycle, to_lifecycle, display_name, actor_id, source, request_id, at) - VALUES ('id-1', 'created', '', 'active', 'Archie', 'sam', 'boot', 'rq-1', '2026-01-01T00:00:00Z'); -INSERT INTO identity_subjects VALUES ('https://issuer', 'sub-1', 'id-1', '2026-01-01T00:00:00Z'); -` - -// secret is an encrypted binding secret envelope; it must arrive unchanged. -const secret = "arcie-binding:v1:0123456789abcdef:AbC-_dEf012" - -const edaDDL = ` -CREATE TABLE captures (id TEXT PRIMARY KEY NOT NULL, authenticated BOOLEAN DEFAULT FALSE NOT NULL, - body TEXT DEFAULT '' NOT NULL, content_type TEXT DEFAULT '' NOT NULL, headers JSON DEFAULT NULL, - received_at TEXT DEFAULT '' NOT NULL, remote_addr TEXT DEFAULT '' NOT NULL, source TEXT DEFAULT '' NOT NULL); -CREATE TABLE mappings (id TEXT PRIMARY KEY NOT NULL, created_at TEXT DEFAULT '' NOT NULL, fields JSON DEFAULT NULL, - name TEXT DEFAULT '' NOT NULL, source_hint TEXT DEFAULT '' NOT NULL, updated_at TEXT DEFAULT '' NOT NULL); -CREATE TABLE bindings (id TEXT PRIMARY KEY NOT NULL, created_at TEXT DEFAULT '' NOT NULL, mapping TEXT DEFAULT '' NOT NULL, - name TEXT DEFAULT '' NOT NULL, owner TEXT DEFAULT '' NOT NULL, repo TEXT DEFAULT '' NOT NULL, - secret TEXT DEFAULT '' NOT NULL, source TEXT DEFAULT '' NOT NULL, status TEXT DEFAULT '' NOT NULL, - updated_at TEXT DEFAULT '' NOT NULL, version NUMERIC DEFAULT 0 NOT NULL, workflow TEXT DEFAULT '' NOT NULL); -CREATE TABLE binding_dispatches (id TEXT PRIMARY KEY NOT NULL, binding TEXT DEFAULT '' NOT NULL, - binding_version NUMERIC DEFAULT 0 NOT NULL, capture TEXT DEFAULT '' NOT NULL, dispatched_at TEXT DEFAULT '' NOT NULL, - task_id NUMERIC DEFAULT 0 NOT NULL); -CREATE UNIQUE INDEX idx_binding_dispatch_once ON binding_dispatches (binding, capture); -CREATE TABLE playbook_dispatches (id TEXT PRIMARY KEY NOT NULL, action_id TEXT DEFAULT '' NOT NULL, - dispatched_at TEXT DEFAULT '' NOT NULL, event_id TEXT DEFAULT '' NOT NULL, playbook_id TEXT DEFAULT '' NOT NULL, - playbook_version TEXT DEFAULT '' NOT NULL); -CREATE TABLE tool_calls (id TEXT PRIMARY KEY NOT NULL, args JSON DEFAULT NULL, attempt NUMERIC DEFAULT 0 NOT NULL, - called_at TEXT DEFAULT '' NOT NULL, duration_ms NUMERIC DEFAULT 0 NOT NULL, error TEXT DEFAULT '' NOT NULL, - result JSON DEFAULT NULL, task_id NUMERIC DEFAULT 0 NOT NULL, tool TEXT DEFAULT '' NOT NULL); - -INSERT INTO captures VALUES ('rcap1', 1, '{}', 'application/json', '{"x":["1"]}', '2026-01-01T00:00:00.000000000Z', '127.0.0.1', 'gh'); -INSERT INTO captures VALUES ('rcap2', 0, '', '', NULL, '2026-01-01T00:00:01.000000000Z', '', 'gh'); -INSERT INTO mappings VALUES ('rmap1', '2026-01-01 00:00:00.000Z', '[]', 'm', 'gh', '2026-01-01 00:00:00.000Z'); -INSERT INTO bindings VALUES ('rbind1', '2026-01-01 00:00:00.000Z', 'rmap1', 'b', 'o', 'r', '` + secret + `', 'gh', 'armed', '2026-01-01 00:00:00.000Z', 1, 'implement'); -INSERT INTO binding_dispatches VALUES ('rdisp1', 'rbind1', 1, 'rcap1', '2026-01-01 00:00:00.000Z', 4); -INSERT INTO playbook_dispatches VALUES ('rpb1', 'act', '2026-01-01 00:00:00.000Z', 'ev', 'pb', 'v1'); -INSERT INTO tool_calls VALUES ('rtool1', NULL, 1, '2026-01-01 00:00:00.000Z', 12, '', '"exit 0"', 4, 'bash'); -` - -const gatewayDDL = ` -CREATE TABLE sessions (session_id TEXT PRIMARY KEY, platform TEXT NOT NULL DEFAULT '', bot_user TEXT NOT NULL DEFAULT '', - channel_id TEXT NOT NULL DEFAULT '', thread_id TEXT NOT NULL DEFAULT '', title TEXT NOT NULL DEFAULT '', - parent_session_id TEXT NOT NULL DEFAULT '', branch_name TEXT NOT NULL DEFAULT '', - created_at INTEGER NOT NULL DEFAULT 0, last_active_at INTEGER NOT NULL DEFAULT 0); -CREATE TABLE messages (id INTEGER PRIMARY KEY AUTOINCREMENT, message_id TEXT NOT NULL, session_id TEXT NOT NULL, - source_id TEXT NOT NULL DEFAULT '', sender TEXT NOT NULL DEFAULT '', text TEXT NOT NULL DEFAULT '', ts INTEGER NOT NULL, - UNIQUE(session_id, message_id)); -ALTER TABLE messages ADD COLUMN role TEXT NOT NULL DEFAULT ''; -ALTER TABLE messages ADD COLUMN sender_id TEXT NOT NULL DEFAULT ''; -CREATE VIRTUAL TABLE messages_fts USING fts5(sender, text, content='messages', content_rowid='id'); -CREATE TRIGGER messages_ai AFTER INSERT ON messages BEGIN - INSERT INTO messages_fts(rowid, sender, text) VALUES (new.id, new.sender, new.text); -END; -CREATE TABLE turns (turn_id TEXT PRIMARY KEY, session_id TEXT NOT NULL, source_id TEXT NOT NULL DEFAULT '', - status TEXT NOT NULL, attempt INTEGER NOT NULL DEFAULT 0, owner_id TEXT NOT NULL DEFAULT '', - input_message_id TEXT NOT NULL DEFAULT '', assistant_message_id TEXT NOT NULL DEFAULT '', - partial_text TEXT NOT NULL DEFAULT '', response_text TEXT NOT NULL DEFAULT '', tool_calls TEXT NOT NULL DEFAULT '[]', - error TEXT NOT NULL DEFAULT '', created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL); - -INSERT INTO sessions VALUES ('s1', 'telegram', 'bot', 'c1', '', 'Chat', '', '', 1000, 2000); -INSERT INTO messages (message_id, session_id, sender, text, ts, role) VALUES ('m1', 's1', 'sam', 'hello there', 1000, 'user'); -INSERT INTO messages (message_id, session_id, sender, text, ts, role) VALUES ('m2', 's1', 'archie', 'hi', 1001, 'assistant'); -INSERT INTO turns VALUES ('t1', 's1', '', 'done', 1, '', 'm1', 'm2', '', 'hi', '[]', '', 1000, 1001); -` - // install writes the three legacy files the way an existing install holds // them and returns their paths. mutate runs extra statements against a file // before the import sees it. func install(t *testing.T, mutate map[string]string) Sources { t.Helper() - dir := t.TempDir() - src := Sources{ - StateStore: filepath.Join(dir, "archie.db-tasks.sqlite"), - EDA: filepath.Join(dir, "archie.db-eda.sqlite"), - Gateway: filepath.Join(dir, "archie.db-conversations.sqlite"), - } - for path, ddl := range map[string]string{src.StateStore: stateStoreDDL, src.EDA: edaDDL, src.Gateway: gatewayDDL} { - sqliteExec(t, path, ddl) - } + var src Sources + src.StateStore, src.EDA, src.Gateway = legacyfixture.Install(t, filepath.Join(t.TempDir(), "archie.db")) for path, stmt := range mutate { switch path { case "state": - sqliteExec(t, src.StateStore, stmt) + legacyfixture.Exec(t, src.StateStore, stmt) case "eda": - sqliteExec(t, src.EDA, stmt) + legacyfixture.Exec(t, src.EDA, stmt) case "gateway": - sqliteExec(t, src.Gateway, stmt) + legacyfixture.Exec(t, src.Gateway, stmt) } } return src } -func sqliteExec(t *testing.T, path, stmt string) { - t.Helper() - db, err := sql.Open("sqlite", "file:"+path) - if err != nil { - t.Fatalf("open fixture: %v", err) - } - defer func() { _ = db.Close() }() - if _, err := db.ExecContext(t.Context(), stmt); err != nil { - t.Fatalf("fixture %s: %v", filepath.Base(path), err) - } -} - func hashFiles(t *testing.T, dir string) map[string][32]byte { t.Helper() entries, err := os.ReadDir(dir) @@ -297,8 +155,8 @@ func TestImportCopiesEverySourceAndLeavesThemUntouched(t *testing.T) { if !bytes.Equal(value, []byte{0x00, 0xff, 0x10}) { t.Errorf("resource_history.value = %x, want 00ff10", value) } - if gotSecret != secret { - t.Errorf("binding secret = %q, want %q", gotSecret, secret) + if gotSecret != legacyfixture.Secret { + t.Errorf("binding secret = %q, want %q", gotSecret, legacyfixture.Secret) } if headers != "" || result != "exit 0" || !configured { t.Errorf("headers %q, result %q, configured %v; want \"\", \"exit 0\", true", headers, result, configured) diff --git a/internal/infrastructure/postgres/edastore.go b/internal/infrastructure/postgres/edastore.go index 9c7cb2481..e1389a930 100644 --- a/internal/infrastructure/postgres/edastore.go +++ b/internal/infrastructure/postgres/edastore.go @@ -1,8 +1,7 @@ // Package postgres opens archie's PostgreSQL database and applies its schema // migrations. This file is the PostgreSQL implementation of the EDA // persistence contracts (captures, mappings, bindings and the two dispatch -// ledgers) plus the tool_calls transcript, mirroring the PocketBase-backed -// internal/infrastructure/edastore.Store it will replace in the cutover wave. +// ledgers) plus the tool_calls transcript. package postgres import ( @@ -20,14 +19,12 @@ import ( "github.com/samcharles93/archie-core/internal/domain/mapping" "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/events" - "github.com/samcharles93/archie-core/internal/infrastructure/edastore" + "github.com/samcharles93/archie-core/internal/infrastructure/bindingcipher" "github.com/samcharles93/archie-core/internal/infrastructure/postgres/postgresdb" ) // EDA is the PostgreSQL implementation of every event-capture contract, plus -// the tool_calls transcript the composition projection writes through. It -// satisfies the same surface as *edastore.Store, so the cutover wave can swap -// one for the other behind storecontract without touching the consumers. +// the tool_calls transcript the composition projection writes through. var ( _ storecontract.CaptureStore = (*EDA)(nil) _ storecontract.MappingStore = (*EDA)(nil) @@ -40,26 +37,23 @@ var ( type EDA struct { pool *pgxpool.Pool q *postgresdb.Queries - cipher edastore.BindingCipher + cipher bindingcipher.BindingCipher notify func(events.Event) } // NewEDA builds an EDA store over pool. A nil cipher keeps binding secrets in -// plaintext (the behaviour that predates the option); the caller resolves the -// keyring through edastore.NewBindingCipher, exactly as the PocketBase store -// does. The pool is owned by the caller, not this store. -func NewEDA(pool *pgxpool.Pool, cipher edastore.BindingCipher) *EDA { +// plaintext; the caller resolves the keyring through +// bindingcipher.NewBindingCipher. The pool is owned by the caller, not this store. +func NewEDA(pool *pgxpool.Pool, cipher bindingcipher.BindingCipher) *EDA { return &EDA{pool: pool, q: postgresdb.New(pool), cipher: cipher} } -// SetNotify wires the change-event callback that the PocketBase store's -// Config.Notify provides. It is the same injection point: nil is a silent -// no-op, which is what every production construction gets today. +// SetNotify wires the change-event callback. nil is a silent no-op, which is +// what every production construction gets today. func (s *EDA) SetNotify(fn func(events.Event)) { s.notify = fn } // notifyWrite announces one successful write on the bindings or mappings -// tables. It mirrors edastore.(*Store).notifyWrite byte-for-byte: the data -// carries the record id and action, and consumers refetch the row themselves. +// tables. The data carries the record id and action, and consumers refetch the row themselves. func (s *EDA) notifyWrite(kind, subject, action, id string) { if s.notify == nil { return @@ -77,8 +71,7 @@ func newRecordID() string { return uuid.NewString() } // --- captures --- // InsertCapture stores one inbound event verbatim. retention and maxEvents are -// accepted for contract compatibility and applied as a prune after the insert, -// exactly as the PocketBase store does. +// applied as a prune after the insert. func (s *EDA) InsertCapture(ctx context.Context, c storecontract.CapturedEvent, retention time.Duration, maxEvents int) (string, error) { received := c.ReceivedAt if received.IsZero() { @@ -208,8 +201,8 @@ func (s *EDA) InsertMapping(ctx context.Context, m mapping.Mapping) (string, err return id, nil } -// GetMapping returns (nil, nil) for an absent mapping, matching the -// PocketBase store's found=false convention the gRPC layer translates. +// GetMapping returns (nil, nil) for an absent mapping, the found=false +// convention the gRPC layer translates. func (s *EDA) GetMapping(ctx context.Context, id string) (*mapping.Mapping, error) { r, err := s.q.GetMapping(ctx, id) if errors.Is(err, pgx.ErrNoRows) { @@ -347,8 +340,8 @@ func (s *EDA) InsertBinding(ctx context.Context, b binding.Binding) (string, err return id, nil } -// GetBinding returns (nil, nil) for an absent binding, matching the -// PocketBase store's found=false convention the gRPC layer translates. +// GetBinding returns (nil, nil) for an absent binding, the found=false +// convention the gRPC layer translates. func (s *EDA) GetBinding(ctx context.Context, id string) (*binding.Binding, error) { r, err := s.q.GetBinding(ctx, id) if errors.Is(err, pgx.ErrNoRows) { @@ -522,8 +515,21 @@ func ledgerWrite(err error, what string) error { // --- tool calls --- +// ToolCall is one completed tool invocation during an agent stage run, as the +// tool_call event projection stores it: a tool's output summary in Result, a +// failure's detail in Error. +type ToolCall struct { + ID string + TaskID int64 + Attempt int + Tool string + Result string + Error string + CalledAt time.Time +} + // InsertToolCall appends one row to the tool_calls transcript. -func (s *EDA) InsertToolCall(ctx context.Context, tc edastore.ToolCall) error { +func (s *EDA) InsertToolCall(ctx context.Context, tc ToolCall) error { calledAt := tc.CalledAt if calledAt.IsZero() { calledAt = time.Now() @@ -543,14 +549,14 @@ func (s *EDA) InsertToolCall(ctx context.Context, tc edastore.ToolCall) error { } // TaskToolCalls returns one task's tool calls in call order. -func (s *EDA) TaskToolCalls(ctx context.Context, taskID int64) ([]edastore.ToolCall, error) { +func (s *EDA) TaskToolCalls(ctx context.Context, taskID int64) ([]ToolCall, error) { rows, err := s.q.TaskToolCalls(ctx, taskID) if err != nil { return nil, fmt.Errorf("edastore: list tool calls: %w", err) } - out := make([]edastore.ToolCall, 0, len(rows)) + out := make([]ToolCall, 0, len(rows)) for _, r := range rows { - out = append(out, edastore.ToolCall{ + out = append(out, ToolCall{ ID: r.ID, TaskID: r.TaskID, Attempt: int(r.Attempt), diff --git a/internal/infrastructure/postgres/edastore_test.go b/internal/infrastructure/postgres/edastore_test.go index 71a934b14..87f8de9ab 100644 --- a/internal/infrastructure/postgres/edastore_test.go +++ b/internal/infrastructure/postgres/edastore_test.go @@ -12,7 +12,7 @@ import ( "github.com/samcharles93/archie-core/internal/domain/mapping" "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/events" - "github.com/samcharles93/archie-core/internal/infrastructure/edastore" + "github.com/samcharles93/archie-core/internal/infrastructure/bindingcipher" ) const edaTestKey = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" @@ -24,7 +24,7 @@ func edaFor(t *testing.T) *EDA { return NewEDA(pool, nil) } -func edaWithCipher(t *testing.T, cipher edastore.BindingCipher) (*pgxpool.Pool, *EDA) { +func edaWithCipher(t *testing.T, cipher bindingcipher.BindingCipher) (*pgxpool.Pool, *EDA) { t.Helper() pool, _ := migrated(t) return pool, NewEDA(pool, cipher) @@ -131,7 +131,7 @@ func TestConcurrentInsertBindingSameSource(t *testing.T) { // untouched, so an edit form that does not echo the secret cannot blank an // armed binding's HMAC key. func TestUpdateBindingEmptySecretPreservesStored(t *testing.T) { - cipher, err := edastore.NewBindingCipher(edaTestKey, nil) + cipher, err := bindingcipher.NewBindingCipher(edaTestKey, nil) if err != nil { t.Fatalf("NewBindingCipher() error = %v", err) } @@ -173,7 +173,7 @@ func readRawSecret(t *testing.T, pool *pgxpool.Pool, id string) string { // The cipher path must keep decrypt-in-store: what is stored is an envelope, // what reads back is the plaintext HMAC key the intake verifies with. func TestBindingSecretEncryptedAtRestAndDecryptedOnRead(t *testing.T) { - cipher, err := edastore.NewBindingCipher(edaTestKey, nil) + cipher, err := bindingcipher.NewBindingCipher(edaTestKey, nil) if err != nil { t.Fatalf("NewBindingCipher() error = %v", err) } @@ -200,6 +200,50 @@ func TestBindingSecretEncryptedAtRestAndDecryptedOnRead(t *testing.T) { } } +// A deployment with no configured key stores plaintext. +func TestNoCipherKeepsPlaintext(t *testing.T) { + pool, s := edaWithCipher(t, nil) + id, err := s.InsertBinding(t.Context(), binding.Binding{ + Name: "n", Matcher: binding.Matcher{Source: "src-plain"}, Workflow: "implement", + Secret: "supersecretvalue0123", + }) + if err != nil { + t.Fatalf("InsertBinding() error = %v", err) + } + if stored := readRawSecret(t, pool, id); stored != "supersecretvalue0123" { + t.Errorf("stored secret = %q, want the plaintext with no cipher configured", stored) + } +} + +// A secret written under the previous key stays readable once a new active +// key is installed; otherwise rotation bricks every armed binding. +func TestRotatedKeyStillReadsOldRows(t *testing.T) { + const oldKey = "fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210" + oldCipher, err := bindingcipher.NewBindingCipher(oldKey, nil) + if err != nil { + t.Fatalf("NewBindingCipher(old) error = %v", err) + } + pool, s := edaWithCipher(t, oldCipher) + id, err := s.InsertBinding(t.Context(), binding.Binding{ + Name: "n", Matcher: binding.Matcher{Source: "src-rotate"}, Workflow: "implement", + Secret: "supersecretvalue0123", + }) + if err != nil { + t.Fatalf("InsertBinding() error = %v", err) + } + rotated, err := bindingcipher.NewBindingCipher(edaTestKey, []string{oldKey}) + if err != nil { + t.Fatalf("NewBindingCipher(rotated) error = %v", err) + } + got, err := NewEDA(pool, rotated).GetBinding(t.Context(), id) + if err != nil { + t.Fatalf("GetBinding() after rotation error = %v", err) + } + if got.Secret != "supersecretvalue0123" { + t.Errorf("Secret after rotation = %q: the previous key must still decrypt", got.Secret) + } +} + // The lifecycle gate survives the port: pending_approval -> armed, and only // from pending_approval. func TestBindingLifecycle(t *testing.T) { @@ -308,13 +352,13 @@ func TestToolCallRoundTrip(t *testing.T) { at := time.Date(2026, 9, 23, 1, 2, 3, 0, time.UTC) for range 2 { - if err := s.InsertToolCall(t.Context(), edastore.ToolCall{ + if err := s.InsertToolCall(t.Context(), ToolCall{ TaskID: 42, Attempt: 2, Tool: "shell", Result: "all checks passed", CalledAt: at, }); err != nil { t.Fatalf("InsertToolCall() error = %v", err) } } - if err := s.InsertToolCall(t.Context(), edastore.ToolCall{ + if err := s.InsertToolCall(t.Context(), ToolCall{ TaskID: 7, Attempt: 1, Tool: "read_file", Error: "no such file", CalledAt: at.Add(time.Second), }); err != nil { t.Fatalf("InsertToolCall(other task) error = %v", err) diff --git a/internal/infrastructure/postgres/pgstore/pgstore.go b/internal/infrastructure/postgres/pgstore/pgstore.go new file mode 100644 index 000000000..12ef3aa53 --- /dev/null +++ b/internal/infrastructure/postgres/pgstore/pgstore.go @@ -0,0 +1,61 @@ +// Package pgstore opens migrated PostgreSQL stores on a throwaway pgtest +// database, for tests outside internal/infrastructure/postgres. A package +// using it calls pgtest.Main from TestMain. +package pgstore + +import ( + "testing" + + "github.com/jackc/pgx/v5/pgxpool" + + "github.com/samcharles93/archie-core/internal/infrastructure/bindingcipher" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest" +) + +// TaskDB is the State Store's task database: the task, event, status and +// identity surface plus the control-plane resources, over one pool. +type TaskDB struct { + *postgres.Store + *postgres.Resources + Pool *pgxpool.Pool +} + +// Pool opens a pool on a fresh migrated database, closed when t ends. +func Pool(t testing.TB) *pgxpool.Pool { + t.Helper() + return PoolAt(t, pgtest.URL(t)) +} + +// PoolAt opens a pool on url and migrates it, closed when t ends. Opening a +// second pool on the same url is how a test models a restart. +func PoolAt(t testing.TB, url string) *pgxpool.Pool { + t.Helper() + pool, err := postgres.Open(t.Context(), url) + if err != nil { + t.Fatalf("pgstore: open: %v", err) + } + t.Cleanup(pool.Close) + if err := postgres.Migrate(t.Context(), pool, postgres.Migrations()); err != nil { + t.Fatalf("pgstore: migrate: %v", err) + } + return pool +} + +// On returns the task database over pool. +func On(pool *pgxpool.Pool) *TaskDB { + return &TaskDB{Store: postgres.New(pool), Resources: postgres.NewResources(pool), Pool: pool} +} + +// Open returns the task database on a fresh migrated database. +func Open(t testing.TB) *TaskDB { + t.Helper() + return On(Pool(t)) +} + +// EDA returns the event-capture store on a fresh migrated database. A nil +// cipher keeps binding secrets in plaintext. +func EDA(t testing.TB, cipher bindingcipher.BindingCipher) *postgres.EDA { + t.Helper() + return postgres.NewEDA(Pool(t), cipher) +} diff --git a/internal/infrastructure/postgres/resources.go b/internal/infrastructure/postgres/resources.go index 2294fb663..6b7593787 100644 --- a/internal/infrastructure/postgres/resources.go +++ b/internal/infrastructure/postgres/resources.go @@ -14,8 +14,7 @@ import ( ) // Resources is the PostgreSQL implementation of the State Store's -// control-plane resource document operations. It is separate while the rest -// of the transitional SQLite Store is still being ported. +// control-plane resource document operations. type Resources struct { pool *pgxpool.Pool } diff --git a/internal/infrastructure/staterpc/attribution_test.go b/internal/infrastructure/staterpc/attribution_test.go index 8535e00b4..47e21a0f7 100644 --- a/internal/infrastructure/staterpc/attribution_test.go +++ b/internal/infrastructure/staterpc/attribution_test.go @@ -4,7 +4,7 @@ import ( "testing" "github.com/samcharles93/archie-core/internal/events" - "github.com/samcharles93/archie-core/internal/store" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" ) // TestEventAttributionSurvivesTheStateStoreBoundary runs the same insert through @@ -28,7 +28,7 @@ func TestEventAttributionSurvivesTheStateStoreBoundary(t *testing.T) { for _, mode := range []string{"local", "grpc"} { t.Run(mode, func(t *testing.T) { ctx := t.Context() - local := store.OpenTest(t) + local := pgstore.Open(t) var c contract = local if mode == "grpc" { c = remoteTaskStore(t, local, nil, nil) diff --git a/internal/infrastructure/staterpc/capture_stream_test.go b/internal/infrastructure/staterpc/capture_stream_test.go index 2bc059e87..0cb54894c 100644 --- a/internal/infrastructure/staterpc/capture_stream_test.go +++ b/internal/infrastructure/staterpc/capture_stream_test.go @@ -6,16 +6,16 @@ import ( "github.com/samcharles93/archie-core/internal/domain/binding" "github.com/samcharles93/archie-core/internal/domain/mapping" - "github.com/samcharles93/archie-core/internal/infrastructure/edastore" - "github.com/samcharles93/archie-core/internal/store" + "github.com/samcharles93/archie-core/internal/domain/storecontract" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" ) func TestCaptureListsExceedUnaryMessageLimit(t *testing.T) { - local := store.OpenTest(t) - eda := edastore.OpenTest(t) + local := pgstore.Open(t) + eda := pgstore.EDA(t, nil) body := strings.Repeat("x", 256<<10) for range 20 { - if _, err := eda.InsertCapture(t.Context(), store.CapturedEvent{Source: "large", Body: body, Authenticated: true}, 0, 0); err != nil { + if _, err := eda.InsertCapture(t.Context(), storecontract.CapturedEvent{Source: "large", Body: body, Authenticated: true}, 0, 0); err != nil { t.Fatal(err) } } @@ -49,7 +49,7 @@ func TestCaptureListsExceedUnaryMessageLimit(t *testing.T) { } remote := remoteEDA(t, local, eda) for _, undispatched := range []bool{false, true} { - var captures []store.CapturedEvent + var captures []storecontract.CapturedEvent var err error if undispatched { captures, err = remote.ListUndispatchedCaptures(t.Context(), []string{"large"}, 20) diff --git a/internal/infrastructure/staterpc/conformance_test.go b/internal/infrastructure/staterpc/conformance_test.go index d940341c7..d84ddcf07 100644 --- a/internal/infrastructure/staterpc/conformance_test.go +++ b/internal/infrastructure/staterpc/conformance_test.go @@ -13,56 +13,57 @@ import ( "github.com/samcharles93/archie-core/internal/domain/binding" "github.com/samcharles93/archie-core/internal/domain/mapping" + "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/events" - "github.com/samcharles93/archie-core/internal/infrastructure/edastore" - "github.com/samcharles93/archie-core/internal/store" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" ) // contract is the union of every store surface staterpc fronts (minus the // playbook-dispatch ledger, split out below to keep the interface under the // repo's 8-method cap), so the same test battery drives both the local -// *store.Store and the remote *Client through one interface value, per +// *pgstore.TaskDB and the remote *Client through one interface value, per // docs/prds/state-store-contract.md §11's conformance requirement. type contract interface { - store.TaskStore - store.BindingTaskCreator - store.ConfigSnapshotStore - store.ApplyStatusStore + storecontract.TaskStore + storecontract.BindingTaskCreator + storecontract.ConfigSnapshotStore + storecontract.ApplyStatusStore } // edaContract is the event-capture half, which the PocketBase store serves. // It is a separate interface because no single type implements both halves // any more: that split is the point of the migration, not an accident. type edaContract interface { - store.CaptureStore - store.MappingStore - store.BindingStore - store.BindingDispatcher + storecontract.CaptureStore + storecontract.MappingStore + storecontract.BindingStore + storecontract.BindingDispatcher } // playbookContract is the playbook-dispatch idempotency-ledger surface, split // out from contract so each aggregate stays under the repo's interfacebloat // cap without weakening what the conformance battery proves. type playbookContract interface { - store.PlaybookDispatcher + storecontract.PlaybookDispatcher } // taskLogContract is the task-log read group, driven separately because it is -// not a *store.Store surface: the reader is internal/logging's own registry, +// not a *pgstore.TaskDB surface: the reader is internal/logging's own registry, // which owns the log format, so the local side of this contract is a registry // rather than a store. type taskLogContract interface { - store.TaskLogStore + storecontract.TaskLogStore } // remoteEDA fronts both stores for a battery that exercises event-capture // surfaces over the wire. -func remoteEDA(t *testing.T, local *store.Store, eda *edastore.Store) *Client { +func remoteEDA(t *testing.T, local *pgstore.TaskDB, eda *postgres.EDA) *Client { t.Helper() return remoteTaskStore(t, local, nil, eda) } -func remoteContract(t *testing.T, local *store.Store) contract { +func remoteContract(t *testing.T, local *pgstore.TaskDB) contract { t.Helper() return remoteTaskStore(t, local, nil, nil) } @@ -75,7 +76,7 @@ func remoteContract(t *testing.T, local *store.Store) contract { // task store for the task surfaces, the event-capture store for captures, // mappings, bindings and the dispatch ledgers. eda may be nil for a battery // that exercises only task surfaces. -func remoteTaskStore(t *testing.T, local *store.Store, logs store.TaskLogStore, eda *edastore.Store) *Client { +func remoteTaskStore(t *testing.T, local *pgstore.TaskDB, logs storecontract.TaskLogStore, eda *postgres.EDA) *Client { t.Helper() listener := bufconn.Listen(1 << 20) server := grpc.NewServer() @@ -112,8 +113,8 @@ func TestStateStoreConformance(t *testing.T) { for _, mode := range []string{"local", "grpc"} { t.Run(mode, func(t *testing.T) { ctx := t.Context() - local := store.OpenTest(t) - eda := edastore.OpenTest(t) + local := pgstore.Open(t) + eda := pgstore.EDA(t, nil) var c contract = local var ec edaContract = eda var pc playbookContract = eda @@ -168,7 +169,7 @@ func TestStateStoreConformance(t *testing.T) { // Stale transition: from no longer matches current status. err = c.Transition(ctx, task.ID, "queued", "merged", "") - if !errors.Is(err, store.ErrStaleTransition) { + if !errors.Is(err, storecontract.ErrStaleTransition) { t.Fatalf("Transition stale = %v, want ErrStaleTransition", err) } @@ -181,7 +182,7 @@ func TestStateStoreConformance(t *testing.T) { if err := c.BeginRemediation(ctx, task.ID, `{"review_id":7}`); err != nil { t.Fatalf("BeginRemediation: %v", err) } - if err := c.BeginRemediation(ctx, task.ID, `{"review_id":7}`); !errors.Is(err, store.ErrStaleTransition) { + if err := c.BeginRemediation(ctx, task.ID, `{"review_id":7}`); !errors.Is(err, storecontract.ErrStaleTransition) { t.Fatalf("BeginRemediation stale = %v, want ErrStaleTransition", err) } remediated, err := c.TaskByID(ctx, task.ID) @@ -197,7 +198,7 @@ func TestStateStoreConformance(t *testing.T) { if err := c.Transition(ctx, task.ID, "queued", "running", "claimed"); err != nil { t.Fatalf("claim: %v", err) } - if err := c.UpdateReviewPayload(ctx, task.ID, `{}`); !errors.Is(err, store.ErrStaleTransition) { + if err := c.UpdateReviewPayload(ctx, task.ID, `{}`); !errors.Is(err, storecontract.ErrStaleTransition) { t.Fatalf("UpdateReviewPayload stale = %v, want ErrStaleTransition", err) } @@ -309,7 +310,7 @@ func TestStateStoreConformance(t *testing.T) { if parked.Status != "parked" || parked.ParkClass != "transient" || parked.ParkReason != "container pool unavailable" { t.Fatalf("ParkTask row = status:%q class:%q reason:%q", parked.Status, parked.ParkClass, parked.ParkReason) } - if err := c.ParkTask(ctx, claimed.ID, "running", "late park", "transient"); !errors.Is(err, store.ErrStaleTransition) { + if err := c.ParkTask(ctx, claimed.ID, "running", "late park", "transient"); !errors.Is(err, storecontract.ErrStaleTransition) { t.Fatalf("ParkTask stale = %v, want ErrStaleTransition", err) } // An unclassified park normalizes to needs_human store-side rather @@ -371,11 +372,11 @@ func TestStateStoreConformance(t *testing.T) { t.Fatalf("UpdateMapping: %v", err) } err = ec.UpdateMapping(ctx, mapping.Mapping{ID: "rabsent00000000", Name: "x", Fields: gotMapping.Fields}) - if !errors.Is(err, store.ErrMappingNotFound) { + if !errors.Is(err, storecontract.ErrMappingNotFound) { t.Fatalf("UpdateMapping missing = %v, want ErrMappingNotFound", err) } err = ec.DeleteMapping(ctx, "rabsent00000000") - if !errors.Is(err, store.ErrMappingNotFound) { + if !errors.Is(err, storecontract.ErrMappingNotFound) { t.Fatalf("DeleteMapping missing = %v, want ErrMappingNotFound", err) } @@ -393,7 +394,7 @@ func TestStateStoreConformance(t *testing.T) { Name: "b2", Matcher: binding.Matcher{Source: "sentry"}, MappingID: mappingID, Workflow: "implement", Secret: "0123456789abcdef0123456789abcdef", }) - if !errors.Is(err, store.ErrBindingOverlap) { + if !errors.Is(err, storecontract.ErrBindingOverlap) { t.Fatalf("InsertBinding overlap = %v, want ErrBindingOverlap", err) } missingBinding, err := ec.GetBinding(ctx, "rabsent00000000") @@ -411,16 +412,16 @@ func TestStateStoreConformance(t *testing.T) { t.Fatalf("ApproveBinding from pending_approval = %v", err) } err = ec.ApproveBinding(ctx, bindingID) - if !errors.Is(err, store.ErrBindingTransition) { + if !errors.Is(err, storecontract.ErrBindingTransition) { t.Fatalf("ApproveBinding when armed = %v, want ErrBindingTransition", err) } err = ec.DeleteBinding(ctx, "rabsent00000000") - if !errors.Is(err, store.ErrBindingNotFound) { + if !errors.Is(err, storecontract.ErrBindingNotFound) { t.Fatalf("DeleteBinding missing = %v, want ErrBindingNotFound", err) } // Capture + dispatch. - captureID, err := ec.InsertCapture(ctx, store.CapturedEvent{Source: "sentry", Body: `{"id":1}`, Authenticated: true}, 0, 0) + captureID, err := ec.InsertCapture(ctx, storecontract.CapturedEvent{Source: "sentry", Body: `{"id":1}`, Authenticated: true}, 0, 0) if err != nil || captureID == "" { t.Fatalf("InsertCapture: %v %v", captureID, err) } @@ -438,7 +439,7 @@ func TestStateStoreConformance(t *testing.T) { t.Fatalf("RecordDispatch: %v", err) } err = ec.RecordDispatch(ctx, bindingID, 1, captureID, bindingTask.ID) - if !errors.Is(err, store.ErrAlreadyDispatched) { + if !errors.Is(err, storecontract.ErrAlreadyDispatched) { t.Fatalf("RecordDispatch dup = %v, want ErrAlreadyDispatched", err) } if _, err := ec.ListUndispatchedCaptures(ctx, []string{"sentry"}, 10); err != nil { @@ -466,7 +467,7 @@ func TestStateStoreConformance(t *testing.T) { t.Fatalf("RecordPlaybookDispatch (distinct action_id) = %v, want success", err) } err = pc.RecordPlaybookDispatch(ctx, "pb.yaml", "v1", "archie:acme/widget/7", "notify") - if !errors.Is(err, store.ErrAlreadyDispatched) { + if !errors.Is(err, storecontract.ErrAlreadyDispatched) { t.Fatalf("RecordPlaybookDispatch dup = %v, want ErrAlreadyDispatched", err) } if err := pc.DeletePlaybookDispatches(ctx, "pb.yaml"); err != nil { @@ -487,7 +488,7 @@ func TestStateStoreConformance(t *testing.T) { func TestConfigSnapshotContract(t *testing.T) { for _, mode := range []string{"local", "grpc"} { t.Run(mode, func(t *testing.T) { - local := store.OpenTest(t) + local := pgstore.Open(t) var st contract = local if mode == "grpc" { st = remoteContract(t, local) @@ -498,7 +499,7 @@ func TestConfigSnapshotContract(t *testing.T) { t.Fatalf("unpublished snapshot = (found %v, %v), want (false, nil)", found, err) } - published := store.ConfigSnapshot{ + published := storecontract.ConfigSnapshot{ Schema: "webui.ConfigView/1", Document: []byte(`{"identity":{"bot_user":"archie"},"providers":{"openai":{"api_key_env":"OPENAI_API_KEY","configured":true}}}`), PublishedAt: time.Date(2026, 9, 9, 12, 30, 0, 0, time.UTC), diff --git a/internal/infrastructure/staterpc/error_test.go b/internal/infrastructure/staterpc/error_test.go index 913620274..ff204b6a4 100644 --- a/internal/infrastructure/staterpc/error_test.go +++ b/internal/infrastructure/staterpc/error_test.go @@ -9,7 +9,7 @@ import ( "google.golang.org/grpc/codes" "google.golang.org/grpc/status" - "github.com/samcharles93/archie-core/internal/store" + "github.com/samcharles93/archie-core/internal/domain/storecontract" ) // TestUnmapErrorPreservesContextIdentity pins the §6 deadline contract that @@ -34,7 +34,7 @@ func TestUnmapErrorPreservesContextIdentity(t *testing.T) { if !errors.Is(got, tt.want) { t.Fatalf("unmapError(%q) = %v, want errors.Is(err, %v)", tt.err, got, tt.want) } - if errors.Is(got, store.ErrStaleTransition) { + if errors.Is(got, storecontract.ErrStaleTransition) { t.Fatalf("unmapError(%q) = %v, must not map to a store sentinel", tt.err, got) } }) @@ -75,12 +75,12 @@ func TestUnmapErrorSentinelFidelity(t *testing.T) { store error rehyd error }{ - {name: "stale transition", store: store.ErrStaleTransition, rehyd: store.ErrStaleTransition}, - {name: "binding not found", store: store.ErrBindingNotFound, rehyd: store.ErrBindingNotFound}, - {name: "mapping not found", store: store.ErrMappingNotFound, rehyd: store.ErrMappingNotFound}, - {name: "binding overlap", store: store.ErrBindingOverlap, rehyd: store.ErrBindingOverlap}, - {name: "binding transition", store: store.ErrBindingTransition, rehyd: store.ErrBindingTransition}, - {name: "already dispatched", store: store.ErrAlreadyDispatched, rehyd: store.ErrAlreadyDispatched}, + {name: "stale transition", store: storecontract.ErrStaleTransition, rehyd: storecontract.ErrStaleTransition}, + {name: "binding not found", store: storecontract.ErrBindingNotFound, rehyd: storecontract.ErrBindingNotFound}, + {name: "mapping not found", store: storecontract.ErrMappingNotFound, rehyd: storecontract.ErrMappingNotFound}, + {name: "binding overlap", store: storecontract.ErrBindingOverlap, rehyd: storecontract.ErrBindingOverlap}, + {name: "binding transition", store: storecontract.ErrBindingTransition, rehyd: storecontract.ErrBindingTransition}, + {name: "already dispatched", store: storecontract.ErrAlreadyDispatched, rehyd: storecontract.ErrAlreadyDispatched}, } for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { @@ -104,7 +104,7 @@ func TestUnmapErrorDoesNotLeakInternalDetail(t *testing.T) { const detail = "sql: path=/var/lib/archie/archie.db secret=abcdef" internal := mapError(errors.New(detail)) got := unmapError(internal) - if errors.Is(got, store.ErrStaleTransition) || errors.Is(got, store.ErrBindingNotFound) || errors.Is(got, store.ErrAlreadyDispatched) { + if errors.Is(got, storecontract.ErrStaleTransition) || errors.Is(got, storecontract.ErrBindingNotFound) || errors.Is(got, storecontract.ErrAlreadyDispatched) { t.Fatalf("unmapError(internal) = %v, must not map to a store sentinel", got) } if st, ok := status.FromError(got); !ok || st.Code() != codes.Internal { @@ -118,7 +118,7 @@ func TestUnmapErrorDoesNotLeakInternalDetail(t *testing.T) { // status or a store sentinel). raw := errors.New("transport failure") got = unmapError(raw) - if errors.Is(got, store.ErrStaleTransition) { + if errors.Is(got, storecontract.ErrStaleTransition) { t.Fatalf("unmapError(raw) = %v, must not map to a store sentinel", got) } if !errors.Is(got, raw) { diff --git a/internal/infrastructure/staterpc/pgtest_test.go b/internal/infrastructure/staterpc/pgtest_test.go new file mode 100644 index 000000000..1a5f0ceb1 --- /dev/null +++ b/internal/infrastructure/staterpc/pgtest_test.go @@ -0,0 +1,10 @@ +package staterpc + +import ( + "os" + "testing" + + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest" +) + +func TestMain(m *testing.M) { os.Exit(pgtest.Main(m)) } diff --git a/internal/infrastructure/staterpc/task_grants_test.go b/internal/infrastructure/staterpc/task_grants_test.go index 46bbf252e..def46342a 100644 --- a/internal/infrastructure/staterpc/task_grants_test.go +++ b/internal/infrastructure/staterpc/task_grants_test.go @@ -14,10 +14,10 @@ import ( "github.com/samcharles93/archie-core/internal/domain/binding" "github.com/samcharles93/archie-core/internal/domain/mapping" + "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/domain/workflow" "github.com/samcharles93/archie-core/internal/events" - "github.com/samcharles93/archie-core/internal/infrastructure/edastore" - "github.com/samcharles93/archie-core/internal/store" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" ) // grantsServer wires TaskGrants' Unary/Stream interceptors -- the same @@ -28,14 +28,14 @@ func grantsServer(t *testing.T, adminToken string) (grants *TaskGrants, dial fun t.Helper() grants = &TaskGrants{} listener := bufconn.Listen(1 << 20) - local := store.OpenTest(t) + local := pgstore.Open(t) server := grpc.NewServer( grpc.ChainUnaryInterceptor(grants.UnaryInterceptor(adminToken)), grpc.ChainStreamInterceptor(grants.StreamInterceptor(adminToken)), ) // One event-capture store serves every EDA surface, as the real // composition does: separate instances would not share a database. - eda := edastore.OpenTest(t) + eda := pgstore.EDA(t, nil) RegisterServer(server, Deps{ Tasks: local, ConfigSnapshots: local, ApplyStatus: local, Captures: eda, Mappings: eda, Bindings: eda, @@ -79,7 +79,7 @@ func TestCaptureStreamsCarryTheAdminToken(t *testing.T) { body := strings.Repeat("x", 256<<10) for range 20 { - if _, err := admin.InsertCapture(ctx, store.CapturedEvent{Source: "large", Body: body, Authenticated: true}, 0, 0); err != nil { + if _, err := admin.InsertCapture(ctx, storecontract.CapturedEvent{Source: "large", Body: body, Authenticated: true}, 0, 0); err != nil { t.Fatalf("InsertCapture: %v", err) } } @@ -114,10 +114,10 @@ func TestCaptureStreamsCarryTheAdminToken(t *testing.T) { for _, tc := range []struct { name string - list func(context.Context) ([]store.CapturedEvent, error) + list func(context.Context) ([]storecontract.CapturedEvent, error) }{ - {"ListCaptures", func(ctx context.Context) ([]store.CapturedEvent, error) { return admin.ListCaptures(ctx, 20) }}, - {"ListUndispatchedCaptures", func(ctx context.Context) ([]store.CapturedEvent, error) { + {"ListCaptures", func(ctx context.Context) ([]storecontract.CapturedEvent, error) { return admin.ListCaptures(ctx, 20) }}, + {"ListUndispatchedCaptures", func(ctx context.Context) ([]storecontract.CapturedEvent, error) { return admin.ListUndispatchedCaptures(ctx, []string{"large"}, 20) }}, } { @@ -263,7 +263,7 @@ func TestOnlyAdminPublishesTheConfigSnapshot(t *testing.T) { } worker := dial(t, workerToken) - snapshot := store.ConfigSnapshot{Schema: "webui.ConfigView/1", Document: []byte(`{}`)} + snapshot := storecontract.ConfigSnapshot{Schema: "webui.ConfigView/1", Document: []byte(`{}`)} if err := admin.PutConfigSnapshot(ctx, snapshot); err != nil { t.Fatalf("admin PutConfigSnapshot: %v", err) } @@ -298,7 +298,7 @@ func TestOnlyAdminReportsApplyStatus(t *testing.T) { } worker := dial(t, workerToken) - status := store.ApplyStatus{Process: "archied", Kind: "tool-settings", AppliedVersion: 2} + status := storecontract.ApplyStatus{Process: "archied", Kind: "tool-settings", AppliedVersion: 2} if err := admin.PutApplyStatus(ctx, status); err != nil { t.Fatalf("admin PutApplyStatus: %v", err) } diff --git a/internal/infrastructure/staterpc/task_log_nilslice_test.go b/internal/infrastructure/staterpc/task_log_nilslice_test.go index fcef50e59..8129fd79e 100644 --- a/internal/infrastructure/staterpc/task_log_nilslice_test.go +++ b/internal/infrastructure/staterpc/task_log_nilslice_test.go @@ -5,8 +5,8 @@ import ( "path/filepath" "testing" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/logging" - "github.com/samcharles93/archie-core/internal/store" ) // A decoded task-log page must never carry a nil slice for a collection field. @@ -54,7 +54,7 @@ func TestTaskLogPageCarriesNoNilCollectionFields(t *testing.T) { var c taskLogContract = reader if mode == "grpc" { - c = remoteTaskStore(t, store.OpenTest(t), reader, nil) + c = remoteTaskStore(t, pgstore.Open(t), reader, nil) } page, err := c.TaskLog(ctx, taskID, 0, logging.Query{}) diff --git a/internal/infrastructure/staterpc/task_log_test.go b/internal/infrastructure/staterpc/task_log_test.go index c87185888..5683da7d8 100644 --- a/internal/infrastructure/staterpc/task_log_test.go +++ b/internal/infrastructure/staterpc/task_log_test.go @@ -8,8 +8,8 @@ import ( "strings" "testing" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/logging" - "github.com/samcharles93/archie-core/internal/store" ) // TestTaskLogContract drives the task-log read group through both adapters, @@ -41,7 +41,7 @@ func TestTaskLogContract(t *testing.T) { var c taskLogContract = reader if mode == "grpc" { - c = remoteTaskStore(t, store.OpenTest(t), reader, nil) + c = remoteTaskStore(t, pgstore.Open(t), reader, nil) } t.Run("a page carries the decoded entries and their fields", func(t *testing.T) { @@ -162,7 +162,7 @@ func TestTaskLogContract(t *testing.T) { // that has no log, and the dashboard rendered that as "task logging is // optional and was not enabled for this run". func TestTaskLogContractWithoutAReaderIsUnavailable(t *testing.T) { - local := store.OpenTest(t) + local := pgstore.Open(t) // remoteContract leaves Deps.TaskLogs nil, which is what a store service // sharing no state directory with the daemon looks like. c := remoteContract(t, local) diff --git a/internal/infrastructure/taskactions/pgtest_test.go b/internal/infrastructure/taskactions/pgtest_test.go new file mode 100644 index 000000000..2d3baad7b --- /dev/null +++ b/internal/infrastructure/taskactions/pgtest_test.go @@ -0,0 +1,10 @@ +package taskactions + +import ( + "os" + "testing" + + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest" +) + +func TestMain(m *testing.M) { os.Exit(pgtest.Main(m)) } diff --git a/internal/infrastructure/taskactions/rpc_test.go b/internal/infrastructure/taskactions/rpc_test.go index 39b4e974a..a30288856 100644 --- a/internal/infrastructure/taskactions/rpc_test.go +++ b/internal/infrastructure/taskactions/rpc_test.go @@ -10,9 +10,9 @@ import ( natssrv "github.com/nats-io/nats-server/v2/test" "github.com/nats-io/nats.go" + "github.com/samcharles93/archie-core/internal/domain/storecontract" domain "github.com/samcharles93/archie-core/internal/domain/taskactions" "github.com/samcharles93/archie-core/internal/events" - "github.com/samcharles93/archie-core/internal/store" "github.com/samcharles93/archie-core/internal/taskstate" ) @@ -86,10 +86,10 @@ func TestActionErrorKeepsItsSentinelAcrossNATS(t *testing.T) { }, { name: "store refused a stale transition", - store: stubStore{task: running, err: store.ErrStaleTransition}, + store: stubStore{task: running, err: storecontract.ErrStaleTransition}, cancel: func(int64) bool { return true }, action: taskstate.ActionStop, - want: store.ErrStaleTransition, + want: storecontract.ErrStaleTransition, }, } { t.Run(tc.name, func(t *testing.T) { diff --git a/internal/webui/api_binding_test.go b/internal/webui/api_binding_test.go index 0efa8db44..1076af8df 100644 --- a/internal/webui/api_binding_test.go +++ b/internal/webui/api_binding_test.go @@ -4,28 +4,23 @@ import ( "encoding/json" "log/slog" "net/http" - "path/filepath" "strings" "testing" "github.com/samcharles93/archie-core/internal/domain/binding" "github.com/samcharles93/archie-core/internal/domain/mapping" "github.com/samcharles93/archie-core/internal/domain/workflow" - "github.com/samcharles93/archie-core/internal/infrastructure/edastore" - "github.com/samcharles93/archie-core/internal/store" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" ) -// bindingTestServer wires a Server backed by a single *store.Store for all +// bindingTestServer wires a Server backed by a single *pgstore.TaskDB for all // three dashboards surfaces (Captures, Mappings, Bindings) and seeds the // one workflow binding tests need to pass server-side validation. func bindingTestServer(t *testing.T) *Server { t.Helper() - s, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "test.db")) - if err != nil { - t.Fatal(err) - } + s := pgstore.Open(t) t.Cleanup(func() { _ = s.Close() }) - eda := edastore.OpenTest(t) + eda := pgstore.EDA(t, nil) return &Server{ Store: s, Log: slog.New(slog.DiscardHandler), diff --git a/internal/webui/api_capture_test.go b/internal/webui/api_capture_test.go index d1fd68eb9..982fac3c6 100644 --- a/internal/webui/api_capture_test.go +++ b/internal/webui/api_capture_test.go @@ -5,32 +5,28 @@ import ( "log/slog" "net/http" "net/http/httptest" - "path/filepath" "strings" "testing" "time" - "github.com/samcharles93/archie-core/internal/infrastructure/edastore" - "github.com/samcharles93/archie-core/internal/store" + "github.com/samcharles93/archie-core/internal/domain/storecontract" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" ) // captureTestServer builds a Server whose Captures field points at the same -// concrete *store.Store as Store, so tests can assert on persisted rows +// concrete *pgstore.TaskDB as Store, so tests can assert on persisted rows // through the narrower CaptureStore interface -- Server.Store's static type -// (store.TaskStore) does not expose ListCaptures. +// (storecontract.TaskStore) does not expose ListCaptures. func captureTestServer(t *testing.T) *Server { t.Helper() - s, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "test.db")) - if err != nil { - t.Fatal(err) - } + s := pgstore.Open(t) t.Cleanup(func() { _ = s.Close() }) return &Server{ Store: s, Log: slog.New(slog.DiscardHandler), // Captures come from the event-capture store; the task store no // longer holds them. - Captures: edastore.OpenTest(t), + Captures: pgstore.EDA(t, nil), } } @@ -39,7 +35,7 @@ func captureTestServer(t *testing.T) *Server { // internal/infrastructure/captureintake and is tested there. func seedCapture(t *testing.T, srv *Server, source string) string { t.Helper() - id, err := srv.Captures.InsertCapture(t.Context(), store.CapturedEvent{ + id, err := srv.Captures.InsertCapture(t.Context(), storecontract.CapturedEvent{ ReceivedAt: time.Now().UTC(), Source: source, Body: `{"n":1}`, diff --git a/internal/webui/api_config_test.go b/internal/webui/api_config_test.go index 7733b2d83..d39db97bd 100644 --- a/internal/webui/api_config_test.go +++ b/internal/webui/api_config_test.go @@ -10,9 +10,9 @@ import ( "github.com/samcharles93/archie-core/internal/channels/status" "github.com/samcharles93/archie-core/internal/config" + "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/logging" "github.com/samcharles93/archie-core/internal/secret" - "github.com/samcharles93/archie-core/internal/store" ) // fakeSecrets are recognisable strings that must never appear anywhere in @@ -553,7 +553,7 @@ func TestRemoteConfigViewRendersThePublishedSnapshot(t *testing.T) { if err != nil { t.Fatal(err) } - source := RemoteConfigView(stubSnapshots{snapshot: store.ConfigSnapshot{ + source := RemoteConfigView(stubSnapshots{snapshot: storecontract.ConfigSnapshot{ Schema: ConfigViewSchema, Document: document, }, found: true}) @@ -573,7 +573,7 @@ func TestRemoteConfigViewRendersThePublishedSnapshot(t *testing.T) { // TestRemoteConfigViewRefusesAnUnknownSchema: a document whose shape this // build does not know is not something to render half of. func TestRemoteConfigViewRefusesAnUnknownSchema(t *testing.T) { - source := RemoteConfigView(stubSnapshots{snapshot: store.ConfigSnapshot{ + source := RemoteConfigView(stubSnapshots{snapshot: storecontract.ConfigSnapshot{ Schema: "webui.ConfigView/99", Document: []byte(`{}`), }, found: true}) @@ -600,14 +600,16 @@ func TestConfigWithNoPublishedSnapshotIsEmpty(t *testing.T) { } type stubSnapshots struct { - snapshot store.ConfigSnapshot + snapshot storecontract.ConfigSnapshot found bool err error } -func (s stubSnapshots) PutConfigSnapshot(context.Context, store.ConfigSnapshot) error { return s.err } +func (s stubSnapshots) PutConfigSnapshot(context.Context, storecontract.ConfigSnapshot) error { + return s.err +} -func (s stubSnapshots) ConfigSnapshot(context.Context) (store.ConfigSnapshot, bool, error) { +func (s stubSnapshots) ConfigSnapshot(context.Context) (storecontract.ConfigSnapshot, bool, error) { return s.snapshot, s.found, s.err } diff --git a/internal/webui/api_mapping_test.go b/internal/webui/api_mapping_test.go index d5306b9a0..fe96a41f2 100644 --- a/internal/webui/api_mapping_test.go +++ b/internal/webui/api_mapping_test.go @@ -6,25 +6,21 @@ import ( "log/slog" "net/http" "net/http/httptest" - "path/filepath" "testing" "github.com/samcharles93/archie-core/internal/domain/mapping" - "github.com/samcharles93/archie-core/internal/infrastructure/edastore" - "github.com/samcharles93/archie-core/internal/store" + "github.com/samcharles93/archie-core/internal/domain/storecontract" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" ) // mappingTestServer builds a Server with both Mappings and Captures backed -// by the same concrete *store.Store, so preview tests can insert a real +// by the same concrete *pgstore.TaskDB, so preview tests can insert a real // capture and resolve a mapping against it end to end. func mappingTestServer(t *testing.T) *Server { t.Helper() - s, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "test.db")) - if err != nil { - t.Fatal(err) - } + s := pgstore.Open(t) t.Cleanup(func() { _ = s.Close() }) - eda := edastore.OpenTest(t) + eda := pgstore.EDA(t, nil) return &Server{ Store: s, Log: slog.New(slog.DiscardHandler), @@ -200,7 +196,7 @@ func TestHandleMappingDelete(t *testing.T) { func TestHandleMappingPreviewResolvesAgainstARealCapture(t *testing.T) { srv := mappingTestServer(t) - capID, err := srv.Captures.InsertCapture(t.Context(), store.CapturedEvent{ + capID, err := srv.Captures.InsertCapture(t.Context(), storecontract.CapturedEvent{ Source: "sentry", Body: `{"issue":{"title":"bug found"},"count":3}`, }, 0, 0) diff --git a/internal/webui/api_tasks_actions_test.go b/internal/webui/api_tasks_actions_test.go index 8e9977c14..506708e7a 100644 --- a/internal/webui/api_tasks_actions_test.go +++ b/internal/webui/api_tasks_actions_test.go @@ -15,13 +15,13 @@ import ( "testing" "github.com/samcharles93/archie-core/internal/config" + "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/domain/taskactions" "github.com/samcharles93/archie-core/internal/domain/workflow" "github.com/samcharles93/archie-core/internal/events" "github.com/samcharles93/archie-core/internal/gateway" taskactionstore "github.com/samcharles93/archie-core/internal/infrastructure/taskactions" "github.com/samcharles93/archie-core/internal/logging" - "github.com/samcharles93/archie-core/internal/store" "github.com/samcharles93/archie-core/internal/taskstate" ) @@ -185,7 +185,7 @@ type recordingTaskStopper struct { } type archiveFailingStore struct { - store.TaskStore + storecontract.TaskStore err error } diff --git a/internal/webui/pgtest_test.go b/internal/webui/pgtest_test.go new file mode 100644 index 000000000..cc4bc1719 --- /dev/null +++ b/internal/webui/pgtest_test.go @@ -0,0 +1,10 @@ +package webui + +import ( + "os" + "testing" + + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest" +) + +func TestMain(m *testing.M) { os.Exit(pgtest.Main(m)) } diff --git a/internal/webui/remote_store_test.go b/internal/webui/remote_store_test.go index 445fbd101..3426e6881 100644 --- a/internal/webui/remote_store_test.go +++ b/internal/webui/remote_store_test.go @@ -3,7 +3,7 @@ package webui // Remote-contract coverage for the dashboard data paths. The production UI // process (archie-ui, and the daemon's webui) serves task, capture, mapping // and binding routes against a *staterpc.Client — the remote read contract — -// not a concrete *store.Store. Every other webui test feeds a local store +// not a concrete *pgstore.TaskDB. Every other webui test feeds a local store // directly, so none of them prove the handlers work once the data crosses the // gRPC wire. These do: they stand up a real SQLite store behind // staterpc.RegisterServer, dial it, and assert the handlers serve correctly. @@ -21,9 +21,8 @@ import ( "google.golang.org/grpc" "github.com/samcharles93/archie-core/internal/domain/workflow" - "github.com/samcharles93/archie-core/internal/infrastructure/edastore" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/infrastructure/staterpc" - "github.com/samcharles93/archie-core/internal/store" ) // newRemoteTestServer serves a real SQLite store behind a gRPC listener and @@ -33,10 +32,7 @@ import ( // rather than a fake. func newRemoteTestServer(t *testing.T) *Server { t.Helper() - st, err := store.Open(t.Context(), t.TempDir()+"/remote.db") - if err != nil { - t.Fatalf("open temp store: %v", err) - } + st := pgstore.Open(t) t.Cleanup(func() { _ = st.Close() }) listener, err := (&net.ListenConfig{}).Listen(t.Context(), "tcp", "127.0.0.1:0") @@ -48,7 +44,7 @@ func newRemoteTestServer(t *testing.T) *Server { // surfaces, the event-capture store serves captures/mappings/bindings. // Leaving one nil makes ListMappings/ListBindings fail closed with // err*Unavailable, which is also the real wiring. - eda := edastore.OpenTest(t) + eda := pgstore.EDA(t, nil) staterpc.RegisterServer(server, staterpc.Deps{ Tasks: st, Captures: eda, diff --git a/internal/webui/sse_test.go b/internal/webui/sse_test.go index ce798f011..68c0a439a 100644 --- a/internal/webui/sse_test.go +++ b/internal/webui/sse_test.go @@ -12,7 +12,6 @@ import ( "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/events" - "github.com/samcharles93/archie-core/internal/store" ) // testAt is a fixed instant every synthetic event in this file shares, so a @@ -130,7 +129,7 @@ var errWriteFailed = errors.New("write failed") // fakeEventStore serves EventsSince from a fixed, pre-seeded slice, paginating // the same way the real store does: up to limit events after cursor. type fakeEventStore struct { - store.TaskStore + storecontract.TaskStore all []events.Event } diff --git a/internal/webui/webui_test.go b/internal/webui/webui_test.go index 4267d5f4f..f62e8fbd2 100644 --- a/internal/webui/webui_test.go +++ b/internal/webui/webui_test.go @@ -20,24 +20,21 @@ import ( "log/slog" "net/http" "net/http/httptest" - "path/filepath" "strconv" "strings" "testing" "time" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" + "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/domain/workflow" "github.com/samcharles93/archie-core/internal/events" - "github.com/samcharles93/archie-core/internal/store" ) func newTestServer(t *testing.T) *Server { t.Helper() - s, err := store.Open(t.Context(), filepath.Join(t.TempDir(), "test.db")) - if err != nil { - t.Fatal(err) - } + s := pgstore.Open(t) t.Cleanup(func() { _ = s.Close() }) srv := &Server{Store: s, Log: slog.New(slog.DiscardHandler)} // Composition always gives the dashboard a Gateway contract; task @@ -51,7 +48,7 @@ func newTestServer(t *testing.T) *Server { // inject errors. Methods that are not overridden delegate to the inner // store via the embedded interface. type stubStore struct { - store.TaskStore + storecontract.TaskStore workflowStatsErr error stageStatsErr error tokensByDayErr error @@ -75,21 +72,21 @@ func (s *stubStore) Requeue(ctx context.Context, id int64, from, workflow string return s.TaskStore.Requeue(ctx, id, from, workflow) } -func (s *stubStore) WorkflowStats(ctx context.Context) ([]store.WorkflowStat, error) { +func (s *stubStore) WorkflowStats(ctx context.Context) ([]storecontract.WorkflowStat, error) { if s.workflowStatsErr != nil { return nil, s.workflowStatsErr } return s.TaskStore.WorkflowStats(ctx) } -func (s *stubStore) StageStats(ctx context.Context) ([]store.StageStat, error) { +func (s *stubStore) StageStats(ctx context.Context) ([]storecontract.StageStat, error) { if s.stageStatsErr != nil { return nil, s.stageStatsErr } return s.TaskStore.StageStats(ctx) } -func (s *stubStore) TokensByDay(ctx context.Context, days int) ([]store.DayTokens, error) { +func (s *stubStore) TokensByDay(ctx context.Context, days int) ([]storecontract.DayTokens, error) { if s.tokensByDayErr != nil { return nil, s.tokensByDayErr } diff --git a/tools/go.mod b/tools/go.mod index 462f0af7a..625613f12 100644 --- a/tools/go.mod +++ b/tools/go.mod @@ -16,7 +16,6 @@ require ( github.com/coreos/go-semver v0.3.1 // indirect github.com/cubicdaiya/gonp v1.0.4 // indirect github.com/davecgh/go-spew v1.1.1 // indirect - github.com/dustin/go-humanize v1.1.0 // indirect github.com/fatih/structtag v1.2.0 // indirect github.com/go-sql-driver/mysql v1.9.3 // indirect github.com/google/cel-go v0.28.0 // indirect @@ -27,9 +26,7 @@ require ( github.com/jackc/pgx/v5 v5.11.0 // indirect github.com/jackc/puddle/v2 v2.2.2 // indirect github.com/jinzhu/inflection v1.0.0 // indirect - github.com/mattn/go-isatty v0.0.24 // indirect github.com/ncruces/go-sqlite3 v0.32.0 // indirect - github.com/ncruces/go-strftime v1.0.0 // indirect github.com/ncruces/julianday v1.0.0 // indirect github.com/pb33f/ordered-map/v2 v2.3.1 // indirect github.com/pganalyze/pg_query_go/v6 v6.2.2 // indirect @@ -38,7 +35,6 @@ require ( github.com/pingcap/log v1.1.0 // indirect github.com/pingcap/tidb/pkg/parser v0.0.0-20260418072757-ce92298d1124 // indirect github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c // indirect - github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect github.com/riza-io/grpc-go v0.2.0 // indirect github.com/samcharles93/ai-sdk v0.1.39 // indirect github.com/spf13/cobra v1.10.2 // indirect @@ -65,8 +61,6 @@ require ( gopkg.in/natefinch/lumberjack.v2 v2.2.1 // indirect gopkg.in/yaml.v3 v3.0.1 // indirect modernc.org/libc v1.77.1 // indirect - modernc.org/mathutil v1.7.1 // indirect - modernc.org/memory v1.12.1 // indirect modernc.org/sqlite v1.59.0 // indirect ) diff --git a/tools/go.sum b/tools/go.sum index 55d08c6f5..1c6fda4c3 100644 --- a/tools/go.sum +++ b/tools/go.sum @@ -1,41 +1,75 @@ cel.dev/expr v0.25.3 h1:A2jO8jwOugrrovveCWfj0KEZOfqiLgAcwjpHPhzIGw0= cel.dev/expr v0.25.3/go.mod h1:hrXvqGP6G6gyx8UAHSHJ5RGk//1Oj5nXQ2NI02Nrsg4= +dario.cat/mergo v1.0.2 h1:85+piFYR1tMbRrLcDwR18y4UKJ3aH1Tbzi24VRW1TK8= +dario.cat/mergo v1.0.2/go.mod h1:E/hbnu0NxMFBjpMIE34DRGLWqDy0g5FuKDhCb31ngxA= filippo.io/edwards25519 v1.1.1 h1:YpjwWWlNmGIDyXOn8zLzqiD+9TyIlPhGFG96P39uBpw= filippo.io/edwards25519 v1.1.1/go.mod h1:BxyFTGdWcka3PhytdK4V28tE5sGfRvvvRV7EaN4VDT4= +github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c h1:udKWzYgxTojEKWjV8V+WSxDXJ4NFATAsZjh8iIbsQIg= +github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c/go.mod h1:xomTg63KZ2rFqZQzSB4Vz2SUXa1BpHTVz9L5PTmPC4E= github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03qcyfWMU= github.com/BurntSushi/toml v1.6.0 h1:dRaEfpa2VI55EwlIW72hMRHdWouJeRF7TPYhI+AUQjk= github.com/BurntSushi/toml v1.6.0/go.mod h1:ukJfTF/6rtPPRCnwkur4qwRxa8vTRFBF0uk2lLoLwho= +github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERoyfY= +github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU= github.com/antlr4-go/antlr/v4 v4.13.1 h1:SqQKkuVZ+zWkMMNkjy5FZe5mr5WURWnlpmOuzYWrPrQ= github.com/antlr4-go/antlr/v4 v4.13.1/go.mod h1:GKmUxMtwp6ZgGwZSva4eWPC5mS6vUAmOABFgjdkM7Nw= github.com/bahlo/generic-list-go v0.2.0 h1:5sz/EEAK+ls5wF+NeqDpk5+iNdMDXrh3z3nPnH1Wvgk= github.com/bahlo/generic-list-go v0.2.0/go.mod h1:2KvAjgMlE5NNynlg/5iLrrCCZ2+5xWbdbCW3pNTGyYg= github.com/benbjohnson/clock v1.1.0/go.mod h1:J11/hYXuz8f4ySSvYwY0FKfm+ezbsZBKZxNJlLklBHA= -github.com/buger/jsonparser v1.1.2 h1:frqHqw7otoVbk5M8LlE/L7HTnIq2v9RX6EJ48i9AxJk= -github.com/buger/jsonparser v1.1.2/go.mod h1:6RYKKt7H4d4+iWqouImQ9R2FZql3VbhNgx27UK13J/0= github.com/buger/jsonparser v1.6.1 h1:I0phFv0PlbLHnM7TZAVjZ2MJ2/eWRTDyuO7GLR98IEs= github.com/buger/jsonparser v1.6.1/go.mod h1:6RYKKt7H4d4+iWqouImQ9R2FZql3VbhNgx27UK13J/0= +github.com/cenkalti/backoff/v4 v4.3.0 h1:MyRJ/UdXutAwSAT+s3wNd7MfTIcy71VQueUuFK343L8= +github.com/cenkalti/backoff/v4 v4.3.0/go.mod h1:Y3VNntkOUPxTVeUxJ/G5vcM//AlwfmyYozVcomhLiZE= +github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs= +github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs= +github.com/containerd/errdefs v1.0.0 h1:tg5yIfIlQIrxYtu9ajqY42W3lpS19XqdxRQeEwYG8PI= +github.com/containerd/errdefs v1.0.0/go.mod h1:+YBYIdtsnF4Iw6nWZhJcqGSg/dwvV7tyJ/kCkyJ2k+M= +github.com/containerd/errdefs/pkg v0.3.0 h1:9IKJ06FvyNlexW690DXuQNx2KA2cUJXx151Xdx3ZPPE= +github.com/containerd/errdefs/pkg v0.3.0/go.mod h1:NJw6s9HwNuRhnjJhM7pylWwMyAkmCQvQ4GpJHEqRLVk= +github.com/containerd/log v0.1.0 h1:TCJt7ioM2cr/tfR8GPbGf9/VRAX8D2B4PjzCpfX540I= +github.com/containerd/log v0.1.0/go.mod h1:VRRf09a7mHDIRezVKTRCrOq78v577GXq3bSa3EhrzVo= +github.com/containerd/platforms v0.2.1 h1:zvwtM3rz2YHPQsF2CHYM8+KtB5dvhISiXh5ZpSBQv6A= +github.com/containerd/platforms v0.2.1/go.mod h1:XHCb+2/hzowdiut9rkudds9bE5yJ7npe7dG/wG+uFPw= github.com/coreos/go-semver v0.3.1 h1:yi21YpKnrx1gt5R+la8n5WgS0kCrsPp33dmEyHReZr4= github.com/coreos/go-semver v0.3.1/go.mod h1:irMmmIw/7yzSRPWryHsK7EYSg09caPQL03VsM8rvUec= +github.com/cpuguy83/dockercfg v0.3.2 h1:DlJTyZGBDlXqUZ2Dk2Q3xHs/FtnooJJVaad2S9GKorA= +github.com/cpuguy83/dockercfg v0.3.2/go.mod h1:sugsbF4//dDlL/i+S+rtpIWp+5h0BHJHfjj5/jFyUJc= github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g= github.com/cubicdaiya/gonp v1.0.4 h1:ky2uIAJh81WiLcGKBVD5R7KsM/36W6IqqTy6Bo6rGws= github.com/cubicdaiya/gonp v1.0.4/go.mod h1:iWGuP/7+JVTn02OWhRemVbMmG1DOUnmrGTYYACpOI0I= github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= +github.com/distribution/reference v0.6.0 h1:0IXCQ5g4/QMHHkarYzh5l+u8T3t73zM5QvfrDyIgxBk= +github.com/distribution/reference v0.6.0/go.mod h1:BbU0aIcezP1/5jX/8MP0YiH4SdvB5Y4f/wlDRiLyi3E= +github.com/docker/go-connections v0.8.1 h1:JibmG5hULs5qXSr/cp/w3Pw5fZuStt4MOHMUExb29/M= +github.com/docker/go-connections v0.8.1/go.mod h1:no1qkHdjq7kLMGUXYAduOhYPSJxxvgWBh7ogVvptn3Q= +github.com/docker/go-units v0.5.0 h1:69rxXcBk27SvSaaxTtLh/8llcHD8vYHT7WSdRZ/jvr4= +github.com/docker/go-units v0.5.0/go.mod h1:fgPhTUdO+D/Jk86RDLlptpiXQzgHJF7gydDDbaIK4Dk= github.com/dustin/go-humanize v1.1.0 h1:dbKTrvD0klcbBV/h4AWJdMuZogJACoMlvWIWZ5b2xWg= github.com/dustin/go-humanize v1.1.0/go.mod h1:hc1CvRkJMsgxqjmjMQF3QNRAZBwY8AXBAzKYoSX9sFI= +github.com/ebitengine/purego v0.10.1 h1:dewVBCBT2GaMu1SrNTYxQhgQBethzfhiwvZiLGP/qyY= +github.com/ebitengine/purego v0.10.1/go.mod h1:iIjxzd6CiRiOG0UyXP+V1+jWqUXVjPKLAI0mRfJZTmQ= github.com/fatih/structtag v1.2.0 h1:/OdNE99OxoI/PqaW/SuSK9uxxT3f/tcSZgon/ssNSx4= github.com/fatih/structtag v1.2.0/go.mod h1:mBJUNpUnHmRKrKlQQlmCrh5PuhftFbNv8Ys4/aAZl94= +github.com/felixge/httpsnoop v1.1.0 h1:3YtUj32ZZkqZtt3sZZsClsymw/QDuVfpNhoA31zeORc= +github.com/felixge/httpsnoop v1.1.0/go.mod h1:Zqxgdd+1Rkcz8euOqdr7lqgCRJztwr5hp9vDSi5UZCE= +github.com/go-logr/logr v1.4.4 h1:tG4xh9yMsRCAiodLVTxyrkzSZ9+o0L1Kg/+cPVcbP/8= +github.com/go-logr/logr v1.4.4/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY= +github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag= +github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE= +github.com/go-ole/go-ole v1.3.0 h1:Dt6ye7+vXGIKZ7Xtk4s6/xVdGDQynvom7xCFEdWr6uE= +github.com/go-ole/go-ole v1.3.0/go.mod h1:5LS6F96DhAwUc7C+1HLexzMXY1xGRSryjyPPKW6zv78= github.com/go-sql-driver/mysql v1.9.3 h1:U/N249h2WzJ3Ukj8SowVFjdtZKfu9vlLZxjPXV1aweo= github.com/go-sql-driver/mysql v1.9.3/go.mod h1:qn46aNg1333BRMNU69Lq93t8du/dwxI64Gl8i5p1WMU= +github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek= +github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps= github.com/google/cel-go v0.28.0 h1:KjSWstCpz/MN5t4a8gnGJNIYUsJRpdi/r97xWDphIQc= github.com/google/cel-go v0.28.0/go.mod h1:X0bD6iVNR8pkROSOoHVdgTkzmRcosof7WQqCD6wcMc8= -github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3 h1:LMLX+LgTNWpfvCBdFebv6EsYotImrt/Ppc5cXIriCSo= -github.com/google/pprof v0.0.0-20260802141513-ef3492d7dac3/go.mod h1:jl5iWTm0/hd5PjEYEOuwAJ57L/CibdZfrqZ5XA5GrCk= +github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8= +github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU= github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0= github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo= -github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k= -github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM= github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8= github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= github.com/invopop/jsonschema v0.14.0 h1:MHQqLhvpNUZfw+hM3AZDYK7jxO8FZoQeQM77g8iyZjg= @@ -50,17 +84,51 @@ github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4= github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD/E= github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkryuEj+Srlc= +github.com/klauspost/compress v1.20.0 h1:a3C1ke2ohxFymNlb2HWAHjDeKCI90scRskErZkR0ezA= +github.com/klauspost/compress v1.20.0/go.mod h1:LUdAzn7YLVvxLpc7y3V1m40wESHTgc1422pwwBSKYuI= github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo= +github.com/kr/pretty v0.3.0 h1:WgNl7dwNpEZ6jJ9k1snq4pZsg7DOEN8hP9Xw0Tsjwk0= +github.com/kr/pretty v0.3.0/go.mod h1:640gp4NfQd8pI5XOwp5fnNeVWj67G7CFk/SaSQn7NBk= github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ= github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI= +github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY= +github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE= +github.com/lufia/plan9stats v0.0.0-20260330125221-c963978e514e h1:Q6MvJtQK/iRcRtzAscm/zF23XxJlbECiGPyRicsX+Ak= +github.com/lufia/plan9stats v0.0.0-20260330125221-c963978e514e/go.mod h1:autxFIvghDt3jPTLoqZ9OZ7s9qTGNAWmYCjVFWPX/zg= +github.com/magiconair/properties v1.8.10 h1:s31yESBquKXCV9a/ScB3ESkOjUYYv+X0rg8SYxI99mE= +github.com/magiconair/properties v1.8.10/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0= github.com/mattn/go-isatty v0.0.24 h1:tGZZoVgT/KiqK1c8ocVLeDS8BSWMRd47J3Lbz7vsReI= github.com/mattn/go-isatty v0.0.24/go.mod h1:nMCL3Zebbrt45jsMDgnfIwz6ydEQApk5oEI3HqDio6A= +github.com/mfridman/interpolate v0.0.2 h1:pnuTK7MQIxxFz1Gr+rjSIx9u7qVjf5VOoM/u6BbAxPY= +github.com/mfridman/interpolate v0.0.2/go.mod h1:p+7uk6oE07mpE/Ik1b8EckO0O4ZXiGAfshKBWLUM9Xg= +github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3Nl2EsFP0= +github.com/moby/docker-image-spec v1.3.1/go.mod h1:eKmb5VW8vQEh/BAr2yvVNvuiJuY6UIocYsFu/DxxRpo= +github.com/moby/go-archive v0.2.0 h1:zg5QDUM2mi0JIM9fdQZWC7U8+2ZfixfTYoHL7rWUcP8= +github.com/moby/go-archive v0.2.0/go.mod h1:mNeivT14o8xU+5q1YnNrkQVpK+dnNe/K6fHqnTg4qPU= +github.com/moby/moby/api v1.56.0 h1:GQzua3NA599ASSIICx0iFgiJeO9YkdDARvQsm23ZZuQ= +github.com/moby/moby/api v1.56.0/go.mod h1:sZ+THbVWkjOmBPPfbnzdD/G1LuIexWhqlSHHPTDQ1Uk= +github.com/moby/moby/client v0.6.0 h1:AJjEB21QPbXSXjDsZorFBoDZPhMrfbpaPLgSMAW9Bgs= +github.com/moby/moby/client v0.6.0/go.mod h1:OCo00wNRyA3m4lmJ228W3JbyCN4ZNNYjpOXiJydBdcQ= +github.com/moby/patternmatcher v0.6.1 h1:qlhtafmr6kgMIJjKJMDmMWq7WLkKIo23hsrpR3x084U= +github.com/moby/patternmatcher v0.6.1/go.mod h1:hDPoyOpDY7OrrMDLaYoY3hf52gNCR/YOUYxkhApJIxc= +github.com/moby/sys/sequential v0.7.0 h1:ASQNGNROJSuOO6LL6bPHbKvuZu6NU8P4ldPWk31zj/8= +github.com/moby/sys/sequential v0.7.0/go.mod h1:NfSTAp6V3fw4tmkD62PEcOKeZKquXT8VKCkf7aVR79o= +github.com/moby/sys/user v0.4.0 h1:jhcMKit7SA80hivmFJcbB1vqmw//wU61Zdui2eQXuMs= +github.com/moby/sys/user v0.4.0/go.mod h1:bG+tYYYJgaMtRKgEmuueC0hJEAZWwtIbZTB+85uoHjs= +github.com/moby/sys/userns v0.1.0 h1:tVLXkFOxVu9A64/yh59slHVv9ahO9UIev4JZusOLG/g= +github.com/moby/sys/userns v0.1.0/go.mod h1:IHUYgu/kao6N8YZlp9Cf444ySSvCmDlmzUcYfDHOl28= +github.com/moby/term v0.5.2 h1:6qk3FJAFDs6i/q3W/pQ97SX192qKfZgGjCQqfCJkgzQ= +github.com/moby/term v0.5.2/go.mod h1:d3djjFCrjnB+fl8NJux+EJzu0msscUP+f8it8hPkFLc= github.com/ncruces/go-sqlite3 v0.32.0 h1:hNBUXp88LrfQCsuyXLqWTbTUG35sUuktDsqhhgHvU20= github.com/ncruces/go-sqlite3 v0.32.0/go.mod h1:MIWTK60ONDl0oVY073zYvJP21C3Dly6P9bxVpgkLwdQ= github.com/ncruces/go-strftime v1.0.0 h1:HMFp8mLCTPp341M/ZnA4qaf7ZlsbTc+miZjCLOFAw7w= github.com/ncruces/go-strftime v1.0.0/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls= github.com/ncruces/julianday v1.0.0 h1:fH0OKwa7NWvniGQtxdJRxAgkBMolni2BjDHaWTxqt7M= github.com/ncruces/julianday v1.0.0/go.mod h1:Dusn2KvZrrovOMJuOt0TNXL6tB7U2E8kvza5fFc9G7g= +github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8Oi/yOhh5U= +github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM= +github.com/opencontainers/image-spec v1.1.1 h1:y0fUlFfIZhPF1W537XOLg0/fcx6zcHCJwooC2xJA040= +github.com/opencontainers/image-spec v1.1.1/go.mod h1:qpqAh3Dmcf36wStyyWU+kCeDgrGnAve2nCC8+7h8Q0M= github.com/pb33f/ordered-map/v2 v2.3.1 h1:5319HDO0aw4DA4gzi+zv4FXU9UlSs3xGZ40wcP1nBjY= github.com/pb33f/ordered-map/v2 v2.3.1/go.mod h1:qxFQgd0PkVUtOMCkTapqotNgzRhMPL7VvaHKbd1HnmQ= github.com/pganalyze/pg_query_go/v6 v6.2.2 h1:O0L6zMC226R82RF3X5n0Ki6HjytDsoAzuzp4ATVAHNo= @@ -77,15 +145,26 @@ github.com/pingcap/tidb/pkg/parser v0.0.0-20260418072757-ce92298d1124/go.mod h1: github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c h1:+mdjkGKdHQG3305AYmdv1U2eRNDiU2ErMBj1gwrq8eQ= github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c/go.mod h1:7rwL4CYBLnjLxUqIJNnCWiEdr3bn6IUYi15bNlnbCCU= github.com/pkg/errors v0.8.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0= -github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 h1:o4JXh1EVt9k/+g42oCprj/FisM4qX9L3sZB3upGN2ZU= +github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE= +github.com/pressly/goose/v3 v3.28.0 h1:D2M+iL31GmpZxSHOhX8mqyqAT3CXnokUmm0eKoSP+Vc= +github.com/pressly/goose/v3 v3.28.0/go.mod h1:v26MOuB8bL3kzzrt3Vqhb3R0PRVsl8hFQKdrht/L6Rk= github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE= github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo= github.com/riza-io/grpc-go v0.2.0 h1:2HxQKFVE7VuYstcJ8zqpN84VnAoJ4dCL6YFhJewNcHQ= github.com/riza-io/grpc-go v0.2.0/go.mod h1:2bDvR9KkKC3KhtlSHfR3dAXjUMT86kg4UfWFyVGWqi8= +github.com/rogpeppe/go-internal v1.10.0 h1:TMyTOH3F/DB16zRVcYyreMH6GnZZrwQVAoYjRBZyWFQ= +github.com/rogpeppe/go-internal v1.10.0/go.mod h1:UQnix2H7Ngw/k4C5ijL5+65zddjncjaFoBhdsK/akog= github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM= github.com/samcharles93/ai-sdk v0.1.39 h1:gbNPYeA27MifReCruBiqMgb4fFSjCDi1Zv57a9bo0Vo= github.com/samcharles93/ai-sdk v0.1.39/go.mod h1:u4zrQ9/Q58L5mNEut4bNQ1ks+RCKq71LN5EDz2N/0Zk= +github.com/sethvargo/go-retry v0.4.0 h1:9qy1OoIAxBL+gBYnkTnTnWle5wlfsXQlwRzIbbpdqPw= +github.com/sethvargo/go-retry v0.4.0/go.mod h1:tvsjdKG6xfiCx4LSiUZ06kcv38xvdVQwv8R6/VnnVWg= +github.com/shirou/gopsutil/v4 v4.26.6 h1:Mzr/npDtQC/xpeEuQKHZt8Zo9CmPvhTj8nkR8w5TLDs= +github.com/shirou/gopsutil/v4 v4.26.6/go.mod h1:LZ6ewCSkBqUpvSOf+LsTGnRinC6iaNUNMGBtDkJBaLQ= +github.com/sirupsen/logrus v1.9.4 h1:TsZE7l11zFCLZnZ+teH4Umoq5BhEIfIzfRDZ1Uzql2w= +github.com/sirupsen/logrus v1.9.4/go.mod h1:ftWc9WdOfJ0a92nsE2jF5u5ZwH8Bv2zdeOC42RjbV2g= github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU= github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4= github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg= @@ -99,22 +178,44 @@ github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+ github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI= github.com/stretchr/testify v1.4.0/go.mod h1:j7eGeouHqKxXV5pUuKE4zz7dFj8WfuZ+81PSLYec5m4= github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= -github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U= -github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U= +github.com/stretchr/testify v1.12.1 h1:EuwCh5fleGS7H32xRwO3wRGT7DxrDhLAT6FF8MpWDWE= +github.com/stretchr/testify v1.12.1/go.mod h1:MDEgiDPPsNp5cuIrHPPCyornHKgEVbtFUmoNlxoYthg= +github.com/testcontainers/testcontainers-go v0.44.0 h1:/Fwh6HY1mIikhnm9e7HwoxGycx0lzRAE0f5VQpjFxzI= +github.com/testcontainers/testcontainers-go v0.44.0/go.mod h1:IcnwQrYTO86xHXu5bvMaBH7ATlbS3Qn1M1QWW3c66rE= +github.com/testcontainers/testcontainers-go/modules/postgres v0.44.0 h1:8fdv/9y3JMxjQ+ULAcOG8RtgeNu5t9XF9LolSXDuTwM= +github.com/testcontainers/testcontainers-go/modules/postgres v0.44.0/go.mod h1:CFr2LncGYokw+OKjXcr8ARCKG1SaC2UEnGxFBovE86g= github.com/tetratelabs/wazero v1.11.0 h1:+gKemEuKCTevU4d7ZTzlsvgd1uaToIDtlQlmNbwqYhA= github.com/tetratelabs/wazero v1.11.0/go.mod h1:eV28rsN8Q+xwjogd7f4/Pp4xFxO7uOGbLcD/LzB1wiU= +github.com/tklauser/go-sysconf v0.4.0 h1:7H0uAN+7RkwWRaxhYXDLqa5V3LPrJeV8wmD9dRUgPQU= +github.com/tklauser/go-sysconf v0.4.0/go.mod h1:8mTNWyog7H+MpKijp4VmKJAd2bbYQ2zuUwkYRbUArPI= +github.com/tklauser/numcpus v0.12.0 h1:NR85qdvHA9pFse3x3weVZ0r0ST8R6l5RHbZrlRaqob4= +github.com/tklauser/numcpus v0.12.0/go.mod h1:ABHeXzJnr/qqwguhClkZKT1/8VABcYrsyUiUGobwWJg= github.com/traefik/yaegi v0.16.1 h1:f1De3DVJqIDKmnasUF6MwmWv1dSEEat0wcpXhD2On3E= github.com/traefik/yaegi v0.16.1/go.mod h1:4eVhbPb3LnD2VigQjhYbEJ69vDRFdT2HQNrXx8eEwUY= github.com/wasilibs/go-pgquery v0.0.0-20250409022910-10ac41983c07 h1:mJdDDPblDfPe7z7go8Dvv1AJQDI3eQ/5xith3q2mFlo= github.com/wasilibs/go-pgquery v0.0.0-20250409022910-10ac41983c07/go.mod h1:Ak17IJ037caFp4jpCw/iQQ7/W74Sqpb1YuKJU6HTKfM= github.com/wasilibs/wazero-helpers v0.0.0-20240620070341-3dff1577cd52 h1:OvLBa8SqJnZ6P+mjlzc2K7PM22rRUPE1x32G9DTPrC4= github.com/wasilibs/wazero-helpers v0.0.0-20240620070341-3dff1577cd52/go.mod h1:jMeV4Vpbi8osrE/pKUxRZkVaA0EX7NZN0A9/oRzgpgY= +github.com/yusufpapurcu/wmi v1.2.4 h1:zFUKzehAFReQwLys1b/iSMl+JQGSCSjtVqQn9bBrPo0= +github.com/yusufpapurcu/wmi v1.2.4/go.mod h1:SBZ9tNy3G9/m5Oi98Zks0QjeHVDvuK0qfxQmPyzfmi0= +go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64= +go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y= +go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.71.0 h1:3g7B90UzBltIDKq1/5mrTGxTnOFDV0ICOhLoxiZ8jlg= +go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.71.0/go.mod h1:Ef8SuTh59BT7+ofpDxN9z+yOlc4t2GjLmKDgYNJL/NU= +go.opentelemetry.io/otel v1.46.0 h1:FHt5/CDyVxi/8IM1CH7VE/rRgq3kLHa2mSTVMO8AWyc= +go.opentelemetry.io/otel v1.46.0/go.mod h1:Gj3SEScelsNC45tp4nSxRYlS+f5iez7W8XPMCt905kE= +go.opentelemetry.io/otel/metric v1.46.0 h1:yBnkXvgV7AXFILZc5K6IZe/CBFF3OS7BJ8ov6/lj0K8= +go.opentelemetry.io/otel/metric v1.46.0/go.mod h1:iPmdWqifKUdzziPkvvzIJXITl56fQx2mGM/DHLB3/2o= +go.opentelemetry.io/otel/trace v1.46.0 h1:OULy7ccdJnZtJ0UDYFOIGaCmiWzJ8Vi2G/Rsu60qs1c= +go.opentelemetry.io/otel/trace v1.46.0/go.mod h1:J7GAXweO77XSFkB/rmAqk9D6ihszhFjLU+d9WuUxDLI= go.uber.org/atomic v1.6.0/go.mod h1:sABNBOSYdrvTF6hTgEIbc7YasKWGhgEQZyfxyTvoXHQ= go.uber.org/atomic v1.7.0/go.mod h1:fEN4uk6kAWBTFdckzkM89CLk9XfWZrxpCo0nPH17wJc= go.uber.org/atomic v1.9.0/go.mod h1:fEN4uk6kAWBTFdckzkM89CLk9XfWZrxpCo0nPH17wJc= go.uber.org/atomic v1.11.0 h1:ZvwS0R+56ePWxUNi+Atn9dWONBPp/AUETXlHW0DxSjE= go.uber.org/atomic v1.11.0/go.mod h1:LUxbIzbOniOlMKjJjyPfpl4v+PKK2cNJn91OQbhoJI0= go.uber.org/goleak v1.1.10/go.mod h1:8a7PlsEVH3e/a/GLqe5IIrQx6GzcnRmZEufDUTk4A7A= +go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto= +go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE= go.uber.org/multierr v1.6.0/go.mod h1:cdWPpRnG4AhwMwsgIHip0KRBQjJy5kYEpYjJxpXp9iU= go.uber.org/multierr v1.7.0/go.mod h1:7EAYxJLBy9rStEaz58O2t4Uvip6FSURkq8/ppBp95ak= go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0= @@ -123,16 +224,16 @@ go.uber.org/zap v1.19.0/go.mod h1:xg/QME4nWcxGxrpdeYfq7UvYrLh66cuVKdrbD1XF/NI= go.uber.org/zap v1.27.0 h1:aJMhYGrd5QSmlpLMr2MftRKl7t8J8PTZPA732ud/XR8= go.uber.org/zap v1.27.0/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E= go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg= -go.yaml.in/yaml/v4 v4.0.0-rc.2 h1:/FrI8D64VSr4HtGIlUtlFMGsm7H7pWTbj6vOLVZcA6s= -go.yaml.in/yaml/v4 v4.0.0-rc.2/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0= +go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw= +go.yaml.in/yaml/v3 v3.0.5/go.mod h1:HVTZu1O7/Vkt2N+BFy8Zza+lnLsABggaTM2ZpNIGuKg= go.yaml.in/yaml/v4 v4.0.0-rc.6 h1:1h7H1ohdUh93/FyE4YaDa1Zh64K6VVbjF4K6WUxMtH4= go.yaml.in/yaml/v4 v4.0.0-rc.6/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0= golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w= +golang.org/x/crypto v0.57.0 h1:3ZVCjf8Ggz7zneR/EHRVx68Ctf+2pmIMP2UFhh9cC6M= +golang.org/x/crypto v0.57.0/go.mod h1:Fdz0i5U6CoizGwLda9DttjSk6qlZo25zYNtR+ycvuZA= golang.org/x/exp v0.0.0-20260908205506-85c1c2202aba h1:Ck8QetSgk912qxWLMCKxd0in+aiyBQyDSMae6e/xmpU= golang.org/x/exp v0.0.0-20260908205506-85c1c2202aba/go.mod h1:50RgIsmK7OwqzTTeqcSXQW8SswW0o8fRcDxmqGluJ8E= golang.org/x/lint v0.0.0-20190930215403-16217165b5de/go.mod h1:6SW0HCj/g11FgYtHlgUYUwCkIfeOF89ocIRzGO/8vkc= -golang.org/x/mod v0.41.0 h1:qJmnOUb4YB+FsEuM3HcWucdZASCPGhsX6uljO6pog0c= -golang.org/x/mod v0.41.0/go.mod h1:Ek9pY8RKWXwsWvd3rQiHYtMqkjSUV+s1Rj7j4H5Ur6o= golang.org/x/net v0.0.0-20190311183353-d8887717615a/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg= golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s= golang.org/x/net v0.59.0 h1:5zfYln+w5XCxwrnMMJPufRgNoXEaGxl0wo5GqPXyues= @@ -150,9 +251,9 @@ golang.org/x/text v0.42.0/go.mod h1:ojzP1Z+2QtioaF8DTtO8K5q7JWVVYwZKenzujK0Zd0E= golang.org/x/tools v0.0.0-20190311212946-11955173bddd/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs= golang.org/x/tools v0.0.0-20191029041327-9cc4af7d6b2c/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo= golang.org/x/tools v0.0.0-20191108193012-7d206e10da11/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo= -golang.org/x/tools v0.50.0 h1:c2ifzfcuY7L90lZ2aKd8S4K2NpASF08SZx9ZuJkHmSU= -golang.org/x/tools v0.50.0/go.mod h1:7ulVMw3831Mwi5EZD6RomGyffr4VFjuNYXf2BbCEAV0= golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= +gonum.org/v1/gonum v0.17.0 h1:VbpOemQlsSMrYmn7T2OUvQ4dqxQXU+ouZFQsZOx50z4= +gonum.org/v1/gonum v0.17.0/go.mod h1:El3tOrEuMpv2UdMrbNlKEh9vd86bmQ6vqIcDwxEOc1E= google.golang.org/genproto/googleapis/api v0.0.0-20260921155816-b14227669459 h1:GS9OIt/j7c8bvBjYNgnKQysVfmV7e4jM0H8ZK95G4t8= google.golang.org/genproto/googleapis/api v0.0.0-20260921155816-b14227669459/go.mod h1:PX5/4vemwVoXtwEcRDWwcR1/r0qrosfx3qoVADMwnVE= google.golang.org/genproto/googleapis/rpc v0.0.0-20260921155816-b14227669459 h1:b0xCahf3FK2m2Cv0p4vTozGPWncCvLfwV86UNg8xWU8= @@ -161,10 +262,10 @@ google.golang.org/grpc v1.85.0-dev.0.20260825072537-93e31b48545e h1:ar+feAPij1Zn google.golang.org/grpc v1.85.0-dev.0.20260825072537-93e31b48545e/go.mod h1:7aY/KlAHanMAVIWHnk8wloQsdlfwzDz/PP9vCbJG6CU= google.golang.org/protobuf v1.36.12 h1:pJOKDDOyeXErUroCihFAd5LQuwXBSpVnKGrj5o/fwxc= google.golang.org/protobuf v1.36.12/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco= -gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk= +gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q= gopkg.in/natefinch/lumberjack.v2 v2.0.0/go.mod h1:l0ndWWf7gzL7RNwBG7wST/UCcT4T24xpD6X8LsfU/+k= gopkg.in/natefinch/lumberjack.v2 v2.2.1 h1:bBRl1b0OH9s/DuPhuXpNl+VtCaJXFZ5/uEFST95x9zc= gopkg.in/natefinch/lumberjack.v2 v2.2.1/go.mod h1:YD8tP3GAjkrDg1eZH7EGmyESg/lsYskCTPBJVb9jqSc= @@ -174,33 +275,11 @@ gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C gopkg.in/yaml.v3 v3.0.0-20210107192922-496545a6307b/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= -modernc.org/cc/v4 v4.29.7 h1:q+NXGJ0bK3b4TXFYQQVr9pYETGnmwFWkrUzJnMya/Tg= -modernc.org/cc/v4 v4.29.7/go.mod h1:OnovgIhbbMXMu1aISnJ0wvVD1KnW+cAUJkIrAWh+kVI= -modernc.org/ccgo/v4 v4.36.0 h1:T5h7ZMcrw2r94oDLtBcU3YI6e1W8DiUg2SJIs2fwD2s= -modernc.org/ccgo/v4 v4.36.0/go.mod h1:rrtGc2QkS239nYb/mQNuBMyjq3/y3ZXWbBjPoV3wqzA= -modernc.org/fileutil v1.4.0 h1:j6ZzNTftVS054gi281TyLjHPp6CPHr2KCxEXjEbD6SM= -modernc.org/fileutil v1.4.0/go.mod h1:EqdKFDxiByqxLk8ozOxObDSfcVOv/54xDs/DUHdvCUU= -modernc.org/gc/v2 v2.6.5 h1:nyqdV8q46KvTpZlsw66kWqwXRHdjIlJOhG6kxiV/9xI= -modernc.org/gc/v2 v2.6.5/go.mod h1:YgIahr1ypgfe7chRuJi2gD7DBQiKSLMPgBQe9oIiito= -modernc.org/gc/v3 v3.1.5 h1:21ldfPfRYE31Tb7B3mwAK8gy1AxP4+dKjrOQPfqakoc= -modernc.org/gc/v3 v3.1.5/go.mod h1:HFK/6AGESC7Ex+EZJhJ2Gni6cTaYpSMmU/cT9RmlfYY= -modernc.org/goabi0 v0.2.0 h1:HvEowk7LxcPd0eq6mVOAEMai46V+i7Jrj13t4AzuNks= -modernc.org/goabi0 v0.2.0/go.mod h1:CEFRnnJhKvWT1c1JTI3Avm+tgOWbkOu5oPA8eH8LnMI= -modernc.org/libc v1.77.0 h1:wV+faa9ixRoUNlakU0fHLi/1kV2YLG8D8Ksk3c2mPtY= -modernc.org/libc v1.77.0/go.mod h1:BmXDCJcMkRMRbX2EI8+Zhh4fKWlHNbCCZEy0tiZevP4= modernc.org/libc v1.77.1 h1:Ct8j47QtiZ1Enj2DtFXQtUqrPCAjdCmPjtCuvrYQ0Hs= modernc.org/libc v1.77.1/go.mod h1:87/pZ4L6nD1zqW4nItuS12YO7hN1igAah34xjnQo/W0= modernc.org/mathutil v1.7.1 h1:GCZVGXdaN8gTqB1Mf/usp1Y/hSqgI2vAGGP4jZMCxOU= modernc.org/mathutil v1.7.1/go.mod h1:4p5IwJITfppl0G4sUEDtCr4DthTaT47/N3aT6MhfgJg= modernc.org/memory v1.12.1 h1:nFMiWrpStgZczNl6XI9GnIk/rWhYIyHGUaR04pGbp9g= modernc.org/memory v1.12.1/go.mod h1:/JP4VbVC+K5sU2wZi9bHoq2MAkCnrt2r98UGeSK7Mjw= -modernc.org/opt v0.2.0 h1:tGyef5ApycA7FSEOMraay9SaTk5zmbx7Tu+cJs4QKZg= -modernc.org/opt v0.2.0/go.mod h1:03fq9lsNfvkYSfxrfUhZCWPk1lm4cq4N+Bh//bEtgns= -modernc.org/sortutil v1.2.1 h1:+xyoGf15mM3NMlPDnFqrteY07klSFxLElE2PVuWIJ7w= -modernc.org/sortutil v1.2.1/go.mod h1:7ZI3a3REbai7gzCLcotuw9AC4VZVpYMjDzETGsSMqJE= modernc.org/sqlite v1.59.0 h1:X1es1GpqBlS/5T+vbM4HLUdaa8OtQx468DF2vrx+38A= modernc.org/sqlite v1.59.0/go.mod h1:+paeT2A3iPRHkQDwG7oA6Tk0zQd5woMEI8q7orfry8k= -modernc.org/strutil v1.2.1 h1:UneZBkQA+DX2Rp35KcM69cSsNES9ly8mQWD71HKlOA0= -modernc.org/strutil v1.2.1/go.mod h1:EHkiggD70koQxjVdSBM3JKM7k6L0FbGE5eymy9i3B9A= -modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y= -modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM= From ecf243fc19b9e514f359d58c4c91d6aa70ed99dd Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Thu, 24 Sep 2026 14:47:21 +1000 Subject: [PATCH 5/8] feat(config): add state_dir for the daemon's host state The embedded NATS store and endpoint file, the task-log registry and the readiness disk probe resolve from state_dir (default: the data home's archie directory) instead of the directory of db_path. db_path now only locates the legacy SQLite files for the one-time import and its boot gate. --- internal/app/archied/bootstrap.go | 13 ++++---- internal/app/archied/gateway.go | 2 +- internal/app/archied/nats/endpoint.json | 1 + .../$G/streams/ARCHIE_REACTIONS/meta.inf | 1 + .../$G/streams/ARCHIE_REACTIONS/meta.sum | 1 + .../$G/streams/ARCHIE_REACTIONS/msgs/1.blk | Bin 0 -> 51 bytes .../obs/archie-daemon/meta.inf | 1 + .../obs/archie-daemon/meta.sum | 1 + .../ARCHIE_REACTIONS/obs/archie-daemon/o.dat | Bin 0 -> 8 bytes .../ARCHIE_REACTIONS/obs/s3Z87297/meta.inf | 1 + .../ARCHIE_REACTIONS/obs/s3Z87297/meta.sum | 1 + .../ARCHIE_REACTIONS/obs/s3Z87297/o.dat | Bin 0 -> 8 bytes .../ARCHIE_REACTIONS/obs/sg9Gl4th/meta.inf | 1 + .../ARCHIE_REACTIONS/obs/sg9Gl4th/meta.sum | 1 + .../ARCHIE_REACTIONS/obs/sg9Gl4th/o.dat | Bin 0 -> 8 bytes .../$G/streams/ARCHIE_TASKS/meta.inf | 1 + .../$G/streams/ARCHIE_TASKS/meta.sum | 1 + .../$G/streams/ARCHIE_TASKS/msgs/1.blk | 0 .../ARCHIE_TASKS/obs/archie-daemon/meta.inf | 1 + .../ARCHIE_TASKS/obs/archie-daemon/meta.sum | 1 + .../ARCHIE_TASKS/obs/archie-daemon/o.dat | Bin 0 -> 8 bytes internal/app/archied/nats_endpoint.go | 12 ++++---- internal/app/archied/nats_endpoint_test.go | 11 ++++--- internal/app/archied/readiness.go | 9 +++--- internal/app/archied/readiness_test.go | 10 +++---- internal/app/archied/state_store.go | 4 +-- internal/config/config.go | 9 +++++- .../infrastructure/configuration/defaults.go | 4 +++ .../configuration/denied_keys.go | 1 + .../configuration/loader_test.go | 28 ++++++++++++++++++ internal/webui/api_config.go | 2 ++ internal/webui/config_schema.go | 4 ++- internal/webui/config_schema_test.go | 5 ++-- 33 files changed, 92 insertions(+), 35 deletions(-) create mode 100644 internal/app/archied/nats/endpoint.json create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/meta.inf create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/meta.sum create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/msgs/1.blk create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/archie-daemon/meta.inf create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/archie-daemon/meta.sum create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/archie-daemon/o.dat create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/s3Z87297/meta.inf create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/s3Z87297/meta.sum create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/s3Z87297/o.dat create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/sg9Gl4th/meta.inf create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/sg9Gl4th/meta.sum create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/sg9Gl4th/o.dat create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/meta.inf create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/meta.sum create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/msgs/1.blk create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/obs/archie-daemon/meta.inf create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/obs/archie-daemon/meta.sum create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/obs/archie-daemon/o.dat diff --git a/internal/app/archied/bootstrap.go b/internal/app/archied/bootstrap.go index 5281d21dd..43df551da 100644 --- a/internal/app/archied/bootstrap.go +++ b/internal/app/archied/bootstrap.go @@ -327,11 +327,10 @@ func (b *boot) setupLogging() error { } logFeed := logging.NewFeed(1000) b.logFeed = logFeed - // Task logs live alongside the store rather than under cfg.Log.File's + // Task logs live in the state directory rather than under cfg.Log.File's // directory: cfg.Log.File is optional (file logging can be off), while - // DBPath is required for the daemon to run at all, so it is the more - // reliable anchor for "where archie keeps its state" on this host. - taskLogs := logging.NewTaskRegistry(filepath.Join(filepath.Dir(cfg.DBPath), "logs", "tasks"), logFeed, logging.TaskSinkOptions{}) + // state_dir always resolves. + taskLogs := logging.NewTaskRegistry(filepath.Join(cfg.StateDir, "logs", "tasks"), logFeed, logging.TaskSinkOptions{}) b.taskLogs = taskLogs fileLog, logCloser, logErr := logging.New(logging.Options{ File: cfg.Log.File, @@ -519,7 +518,7 @@ func (b *boot) connectNATS(ctx context.Context) error { //nolint:nestif // embed return err } } else { - endpoint, readErr := readEmbeddedNATSEndpoint(cfg.DBPath) + endpoint, readErr := readEmbeddedNATSEndpoint(cfg.StateDir) if readErr == nil { url, natsToken = endpoint.URL, endpoint.Token if probe, err := nats.Connect(ctx, nats.Config{URL: url, Token: natsToken, Subjects: []string{workintake.SubjectTaskWildcard}, FilterSubject: workintake.SubjectTaskWildcard}, log); err == nil { @@ -603,7 +602,7 @@ func (b *boot) startEmbeddedNATS(ctx context.Context) (string, string, error) { } srv, err := nats.StartEmbedded(ctx, nats.EmbeddedOptions{ Host: host, - StoreDir: filepath.Join(filepath.Dir(cfg.DBPath), "nats"), + StoreDir: filepath.Join(cfg.StateDir, "nats"), }, log) if err != nil { log.Error("embedded nats start failed", "err", err) @@ -611,7 +610,7 @@ func (b *boot) startEmbeddedNATS(ctx context.Context) (string, string, error) { } b.addCleanup(func() { srv.Shutdown() }) log.Info("embedded nats started", "url", srv.ClientURL()) - if err := writeEmbeddedNATSEndpoint(cfg.DBPath, srv.ClientURL(), srv.Token()); err != nil { + if err := writeEmbeddedNATSEndpoint(cfg.StateDir, srv.ClientURL(), srv.Token()); err != nil { srv.Shutdown() return "", "", err } diff --git a/internal/app/archied/gateway.go b/internal/app/archied/gateway.go index d2898457c..7eb8430fd 100644 --- a/internal/app/archied/gateway.go +++ b/internal/app/archied/gateway.go @@ -82,7 +82,7 @@ func RunGateway(ctx context.Context, options GatewayOptions) error { nc, err = natsio.Connect(url, natsio.Token(token)) } else { var endpoint embeddedNATSEndpoint - endpoint, err = readEmbeddedNATSEndpoint(b.cfg.DBPath) + endpoint, err = readEmbeddedNATSEndpoint(b.cfg.StateDir) if err == nil { url, token = endpoint.URL, endpoint.Token nc, err = natsio.Connect(url, natsio.Token(token)) diff --git a/internal/app/archied/nats/endpoint.json b/internal/app/archied/nats/endpoint.json new file mode 100644 index 000000000..34e1c7fcc --- /dev/null +++ b/internal/app/archied/nats/endpoint.json @@ -0,0 +1 @@ +{"url":"nats://127.0.0.1:42009","token":"PXDPQYX3SBCBW6MNZTUSB5LNDW"} \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/meta.inf b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/meta.inf new file mode 100644 index 000000000..ae11187e3 --- /dev/null +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/meta.inf @@ -0,0 +1 @@ +{"Created":"2026-09-24T04:45:55.407149438Z","name":"ARCHIE_REACTIONS","subjects":["archie.reaction.\u003e"],"retention":"limits","max_consumers":-1,"max_msgs":-1,"max_bytes":-1,"max_age":86400000000000,"max_msgs_per_subject":-1,"max_msg_size":-1,"discard":"old","storage":"file","num_replicas":1,"duplicate_window":120000000000,"compression":"none","allow_direct":false,"mirror_direct":false,"sealed":false,"deny_delete":false,"deny_purge":false,"allow_rollup_hdrs":false,"consumer_limits":{},"allow_msg_ttl":false,"metadata":{"_nats.req.level":"0"}} \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/meta.sum b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/meta.sum new file mode 100644 index 000000000..37e92299b --- /dev/null +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/meta.sum @@ -0,0 +1 @@ +e5007a6989578acf \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/msgs/1.blk b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/msgs/1.blk new file mode 100644 index 0000000000000000000000000000000000000000..422dca8c217b369b5614f87b7f508ce94a0bd6f5 GIT binary patch literal 51 zcmXqJU|?VbVi3?Tc#`I)aYI6cA+abqBQsU6C^a#;Br`uxuOzj&q+)>;Yx}I9FTwyY CXb>a- literal 0 HcmV?d00001 diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/archie-daemon/meta.inf b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/archie-daemon/meta.inf new file mode 100644 index 000000000..ddd6e649a --- /dev/null +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/archie-daemon/meta.inf @@ -0,0 +1 @@ +{"Created":"2026-09-24T04:46:09.06756232Z","Name":"archie-daemon","durable_name":"archie-daemon","name":"archie-daemon","deliver_policy":"all","ack_policy":"explicit","ack_wait":300000000000,"max_deliver":3,"filter_subject":"archie.reaction.\u003e","replay_policy":"instant","max_waiting":512,"max_ack_pending":1000,"inactive_threshold":86400000000000,"num_replicas":0,"metadata":{"_nats.req.level":"0"}} \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/archie-daemon/meta.sum b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/archie-daemon/meta.sum new file mode 100644 index 000000000..7e55c58e9 --- /dev/null +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/archie-daemon/meta.sum @@ -0,0 +1 @@ +d87c12a35c167265 \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/archie-daemon/o.dat b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/archie-daemon/o.dat new file mode 100644 index 0000000000000000000000000000000000000000..055d9019abf53b44fa75492a1b85dcf8996a1f3a GIT binary patch literal 8 LcmWe*VgLgG0LB0r literal 0 HcmV?d00001 diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/s3Z87297/meta.inf b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/s3Z87297/meta.inf new file mode 100644 index 000000000..3af67b620 --- /dev/null +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/s3Z87297/meta.inf @@ -0,0 +1 @@ +{"Created":"2026-09-24T04:46:09.078999729Z","Name":"s3Z87297","name":"s3Z87297","deliver_policy":"all","ack_policy":"explicit","ack_wait":30000000000,"max_deliver":-1,"filter_subject":"archie.reaction.\u003e","replay_policy":"instant","max_waiting":512,"max_ack_pending":1000,"num_replicas":0,"metadata":{"_nats.req.level":"0"}} \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/s3Z87297/meta.sum b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/s3Z87297/meta.sum new file mode 100644 index 000000000..f8024e5e9 --- /dev/null +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/s3Z87297/meta.sum @@ -0,0 +1 @@ +8f8b6852faee5da4 \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/s3Z87297/o.dat b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/s3Z87297/o.dat new file mode 100644 index 0000000000000000000000000000000000000000..f291c5c9aee705825aeb37a04f10452de37894c4 GIT binary patch literal 8 NcmWe*Vgv#P1^@uq0384T literal 0 HcmV?d00001 diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/sg9Gl4th/meta.inf b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/sg9Gl4th/meta.inf new file mode 100644 index 000000000..338606278 --- /dev/null +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/sg9Gl4th/meta.inf @@ -0,0 +1 @@ +{"Created":"2026-09-24T04:46:09.079549283Z","Name":"sg9Gl4th","name":"sg9Gl4th","deliver_policy":"all","ack_policy":"explicit","ack_wait":30000000000,"max_deliver":-1,"filter_subject":"archie.reaction.\u003e","replay_policy":"instant","max_waiting":512,"max_ack_pending":1000,"num_replicas":0,"metadata":{"_nats.req.level":"0"}} \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/sg9Gl4th/meta.sum b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/sg9Gl4th/meta.sum new file mode 100644 index 000000000..ffa829155 --- /dev/null +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/sg9Gl4th/meta.sum @@ -0,0 +1 @@ +3c91a932fe817389 \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/sg9Gl4th/o.dat b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/sg9Gl4th/o.dat new file mode 100644 index 0000000000000000000000000000000000000000..f291c5c9aee705825aeb37a04f10452de37894c4 GIT binary patch literal 8 NcmWe*Vgv#P1^@uq0384T literal 0 HcmV?d00001 diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/meta.inf b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/meta.inf new file mode 100644 index 000000000..3f73e54d5 --- /dev/null +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/meta.inf @@ -0,0 +1 @@ +{"Created":"2026-09-24T04:45:55.396149543Z","name":"ARCHIE_TASKS","subjects":["archie.task.\u003e"],"retention":"workqueue","max_consumers":-1,"max_msgs":-1,"max_bytes":-1,"max_age":0,"max_msgs_per_subject":-1,"max_msg_size":-1,"discard":"old","storage":"file","num_replicas":1,"duplicate_window":120000000000,"compression":"none","allow_direct":false,"mirror_direct":false,"sealed":false,"deny_delete":false,"deny_purge":false,"allow_rollup_hdrs":false,"consumer_limits":{},"allow_msg_ttl":false,"metadata":{"_nats.req.level":"0"}} \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/meta.sum b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/meta.sum new file mode 100644 index 000000000..48a9dc03e --- /dev/null +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/meta.sum @@ -0,0 +1 @@ +c93aec38b44ea7d3 \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/msgs/1.blk b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/msgs/1.blk new file mode 100644 index 000000000..e69de29bb diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/obs/archie-daemon/meta.inf b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/obs/archie-daemon/meta.inf new file mode 100644 index 000000000..602f55962 --- /dev/null +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/obs/archie-daemon/meta.inf @@ -0,0 +1 @@ +{"Created":"2026-09-24T04:46:09.068004189Z","Name":"archie-daemon","durable_name":"archie-daemon","name":"archie-daemon","deliver_policy":"all","ack_policy":"explicit","ack_wait":300000000000,"max_deliver":3,"filter_subject":"archie.task.\u003e","replay_policy":"instant","max_waiting":512,"max_ack_pending":1000,"inactive_threshold":86400000000000,"num_replicas":0,"metadata":{"_nats.req.level":"0"}} \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/obs/archie-daemon/meta.sum b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/obs/archie-daemon/meta.sum new file mode 100644 index 000000000..60c5000ac --- /dev/null +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/obs/archie-daemon/meta.sum @@ -0,0 +1 @@ +514bef62122c4381 \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/obs/archie-daemon/o.dat b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/obs/archie-daemon/o.dat new file mode 100644 index 0000000000000000000000000000000000000000..055d9019abf53b44fa75492a1b85dcf8996a1f3a GIT binary patch literal 8 LcmWe*VgLgG0LB0r literal 0 HcmV?d00001 diff --git a/internal/app/archied/nats_endpoint.go b/internal/app/archied/nats_endpoint.go index 83dcff59f..f77d8d661 100644 --- a/internal/app/archied/nats_endpoint.go +++ b/internal/app/archied/nats_endpoint.go @@ -12,12 +12,12 @@ type embeddedNATSEndpoint struct { Token string `json:"token"` } -func embeddedNATSEndpointPath(dbPath string) string { - return filepath.Join(filepath.Dir(dbPath), "nats", "endpoint.json") +func embeddedNATSEndpointPath(stateDir string) string { + return filepath.Join(stateDir, "nats", "endpoint.json") } -func writeEmbeddedNATSEndpoint(dbPath, url, token string) error { - path := embeddedNATSEndpointPath(dbPath) +func writeEmbeddedNATSEndpoint(stateDir, url, token string) error { + path := embeddedNATSEndpointPath(stateDir) data, err := json.Marshal(embeddedNATSEndpoint{URL: url, Token: token}) if err != nil { return fmt.Errorf("marshal embedded NATS endpoint: %w", err) @@ -48,8 +48,8 @@ func writeEmbeddedNATSEndpoint(dbPath, url, token string) error { return nil } -func readEmbeddedNATSEndpoint(dbPath string) (embeddedNATSEndpoint, error) { - data, err := os.ReadFile(embeddedNATSEndpointPath(dbPath)) +func readEmbeddedNATSEndpoint(stateDir string) (embeddedNATSEndpoint, error) { + data, err := os.ReadFile(embeddedNATSEndpointPath(stateDir)) if err != nil { return embeddedNATSEndpoint{}, err } diff --git a/internal/app/archied/nats_endpoint_test.go b/internal/app/archied/nats_endpoint_test.go index fcfea6984..e28607e57 100644 --- a/internal/app/archied/nats_endpoint_test.go +++ b/internal/app/archied/nats_endpoint_test.go @@ -7,18 +7,21 @@ import ( ) func TestEmbeddedNATSEndpointRoundTripIsPrivateAndAtomic(t *testing.T) { - dbPath := filepath.Join(t.TempDir(), "archie.db") - if err := writeEmbeddedNATSEndpoint(dbPath, "nats://127.0.0.1:4222", "secret"); err != nil { + stateDir := t.TempDir() + if err := writeEmbeddedNATSEndpoint(stateDir, "nats://127.0.0.1:4222", "secret"); err != nil { t.Fatal(err) } - got, err := readEmbeddedNATSEndpoint(dbPath) + got, err := readEmbeddedNATSEndpoint(stateDir) if err != nil { t.Fatal(err) } if got.URL != "nats://127.0.0.1:4222" || got.Token != "secret" { t.Fatalf("endpoint = %+v", got) } - info, err := os.Stat(embeddedNATSEndpointPath(dbPath)) + if want := filepath.Join(stateDir, "nats", "endpoint.json"); embeddedNATSEndpointPath(stateDir) != want { + t.Fatalf("endpoint path = %q, want %q", embeddedNATSEndpointPath(stateDir), want) + } + info, err := os.Stat(embeddedNATSEndpointPath(stateDir)) if err != nil { t.Fatal(err) } diff --git a/internal/app/archied/readiness.go b/internal/app/archied/readiness.go index b08808d39..ea6b3e9bb 100644 --- a/internal/app/archied/readiness.go +++ b/internal/app/archied/readiness.go @@ -10,7 +10,6 @@ import ( "fmt" "net/http" "os" - "path/filepath" "strings" "time" @@ -73,12 +72,12 @@ func diskProbeTargets(cfg config.Config) []readiness.DiskTarget { return targets } -// diskProbePath preserves the database/work/cwd fallback used by the daemon's -// disk target: the store database directory first, then work directory, then cwd. +// diskProbePath is the daemon's data disk target: the state directory first, +// then the work directory, then cwd. func diskProbePath(cfg config.Config) string { switch { - case cfg.DBPath != "": - return filepath.Dir(cfg.DBPath) + case cfg.StateDir != "": + return cfg.StateDir case cfg.WorkDir != "": return cfg.WorkDir default: diff --git a/internal/app/archied/readiness_test.go b/internal/app/archied/readiness_test.go index b7c1644a1..638f1bb16 100644 --- a/internal/app/archied/readiness_test.go +++ b/internal/app/archied/readiness_test.go @@ -12,15 +12,15 @@ import ( "github.com/samcharles93/archie-core/internal/webui" ) -func TestDiskProbePath_PrefersDBPath(t *testing.T) { - cfg := config.Config{DBPath: "/data/archie/tasks.db", WorkDir: "/srv/archie"} - if got := diskProbePath(cfg); got != "/data/archie" { - t.Fatalf("diskProbePath = %q, want /data/archie", got) +func TestDiskProbePath_PrefersStateDir(t *testing.T) { + cfg := config.Config{StateDir: "/var/lib/archie", DBPath: "/data/archie/tasks.db", WorkDir: "/srv/archie"} + if got := diskProbePath(cfg); got != "/var/lib/archie" { + t.Fatalf("diskProbePath = %q, want /var/lib/archie", got) } } func TestDiskProbePath_FallsBackToWorkDir(t *testing.T) { - cfg := config.Config{WorkDir: "/srv/archie"} + cfg := config.Config{DBPath: "/data/archie/tasks.db", WorkDir: "/srv/archie"} if got := diskProbePath(cfg); got != "/srv/archie" { t.Fatalf("diskProbePath = %q, want /srv/archie", got) } diff --git a/internal/app/archied/state_store.go b/internal/app/archied/state_store.go index 7f90bc146..cf6492a52 100644 --- a/internal/app/archied/state_store.go +++ b/internal/app/archied/state_store.go @@ -232,9 +232,7 @@ func (b *boot) stateStoreDeps(grants *staterpc.TaskGrants) staterpc.Deps { // Task logs live in the state directory, which this process owns, and the // dashboard process owns no such directory -- so this is where a task-log // read is served from (docs/prds/ui-service-boundary.md). The reader is - // the daemon's own registry, built over the same state-directory - // derivation this process uses for its SQLite file; both resolve from the - // same configured DBPath, so they agree on where archie keeps its state. + // the daemon's own registry over the configured state_dir. // // The nil check is on the registry, not on the interface it is assigned // to: a nil *logging.TaskRegistry stored in this field produces a non-nil diff --git a/internal/config/config.go b/internal/config/config.go index d5211d967..16b17404b 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -486,7 +486,14 @@ type Config struct { // SecretEngineDir contains Yaegi secret-engine plugins. Built-in env and // bws engines remain available when this is empty. SecretEngineDir string `toml:"secret_engine_dir" yaml:"secret_engine_dir"` - DBPath string `toml:"db_path" yaml:"db_path"` + // DBPath locates the legacy SQLite files ("-tasks.sqlite", + // "-eda.sqlite", "-conversations.sqlite") for the one-time import and the + // boot gate that refuses to serve until it has run. Nothing else reads it. + DBPath string `toml:"db_path" yaml:"db_path"` + // StateDir is the host directory archie keeps non-database state in: the + // embedded NATS store and its endpoint file, the task-log registry, and + // the readiness disk probe's data target. Bootstrap-only. + StateDir string `toml:"state_dir" yaml:"state_dir"` // DatabaseURL is the PostgreSQL connection URL the standalone State Store // process opens at boot. It is bootstrap-only (the same class as db_path // and work_dir): the pool is opened once, so a runtime change cannot take diff --git a/internal/infrastructure/configuration/defaults.go b/internal/infrastructure/configuration/defaults.go index 7226360f2..f88d09801 100644 --- a/internal/infrastructure/configuration/defaults.go +++ b/internal/infrastructure/configuration/defaults.go @@ -225,6 +225,7 @@ func (l *Loader) applyGeneralDefaults(cfg *config.Config) { cfg.SecretEngineDir = expandHomePath(cfg.SecretEngineDir) cfg.WorkDir = expandHomePath(cfg.WorkDir) cfg.DBPath = expandHomePath(cfg.DBPath) + cfg.StateDir = expandHomePath(cfg.StateDir) cfg.Chat.Workspace = expandHomePath(cfg.Chat.Workspace) // DatabaseURL has no default and is not path-expanded: it is a connection // URL, not a file path. Empty means "not configured", which the State @@ -237,6 +238,9 @@ func (l *Loader) applyGeneralDefaults(cfg *config.Config) { if cfg.DBPath == "" { cfg.DBPath = filepath.Join(l.dataHome(), "archie", "archie.db") } + if cfg.StateDir == "" { + cfg.StateDir = filepath.Join(l.dataHome(), "archie") + } if cfg.PollInterval == 0 { cfg.PollInterval = config.Duration(defaultPollInterval) } diff --git a/internal/infrastructure/configuration/denied_keys.go b/internal/infrastructure/configuration/denied_keys.go index 158c4fad8..b0e6b3150 100644 --- a/internal/infrastructure/configuration/denied_keys.go +++ b/internal/infrastructure/configuration/denied_keys.go @@ -11,5 +11,6 @@ package configuration var DeniedKeys = map[string]string{ "db_path": "required for bootstrap; cannot be changed at runtime", "database_url": "required for bootstrap; cannot be changed at runtime", + "state_dir": "required for bootstrap; cannot be changed at runtime", "work_dir": "pins the daemon's working layout; cannot be changed at runtime", } diff --git a/internal/infrastructure/configuration/loader_test.go b/internal/infrastructure/configuration/loader_test.go index 07b1aca2a..5f2fcdd0c 100644 --- a/internal/infrastructure/configuration/loader_test.go +++ b/internal/infrastructure/configuration/loader_test.go @@ -76,6 +76,7 @@ func TestLoadExpandsConfiguredHomePaths(t *testing.T) { bot_user = "widget" work_dir = "~/archie/work" db_path = "~/archie/archie.db" +state_dir = "~/archie/state" [chat] workspace = "~/archie/workspace" @@ -98,6 +99,7 @@ name = "app" }{ "work_dir": {got: cfg.WorkDir, want: filepath.Join(home, "archie", "work")}, "db_path": {got: cfg.DBPath, want: filepath.Join(home, "archie", "archie.db")}, + "state_dir": {got: cfg.StateDir, want: filepath.Join(home, "archie", "state")}, "chat.workspace": {got: cfg.Chat.Workspace, want: filepath.Join(home, "archie", "workspace")}, } for name, tt := range wants { @@ -109,6 +111,32 @@ name = "app" } } +// state_dir defaults to archie's directory under the data home, independent +// of db_path, which only locates legacy files for the one-time import. +func TestStateDirDefaultsToTheDataHome(t *testing.T) { + dataHome := t.TempDir() + t.Setenv("XDG_DATA_HOME", dataHome) + path := filepath.Join(t.TempDir(), "config.toml") + contents := ` +bot_user = "widget" +db_path = "/elsewhere/archie.db" + +[[repos]] +owner = "acme" +name = "app" +` + if err := os.WriteFile(path, []byte(contents), 0o600); err != nil { + t.Fatal(err) + } + cfg, err := loadFile(path) + if err != nil { + t.Fatal(err) + } + if want := filepath.Join(dataHome, "archie"); cfg.StateDir != want { + t.Fatalf("StateDir = %q, want %q", cfg.StateDir, want) + } +} + func TestResolveSelectsFileFormatsAndDirectories(t *testing.T) { tests := []struct { name string diff --git a/internal/webui/api_config.go b/internal/webui/api_config.go index c7bcfbeaa..4866bb8b3 100644 --- a/internal/webui/api_config.go +++ b/internal/webui/api_config.go @@ -242,6 +242,7 @@ type BudgetsView struct { // secrets. type StorageView struct { WorkDir string `json:"work_dir"` + StateDir string `json:"state_dir"` DBPath string `json:"db_path"` DatabaseURL string `json:"database_url"` SkillsDir string `json:"skills_dir,omitempty"` @@ -375,6 +376,7 @@ func BuildConfigView(in ConfigViewInput) ConfigView { }, Storage: StorageView{ WorkDir: cfg.WorkDir, + StateDir: cfg.StateDir, DBPath: cfg.DBPath, DatabaseURL: cfg.DatabaseURL, SkillsDir: cfg.SkillsDir, diff --git a/internal/webui/config_schema.go b/internal/webui/config_schema.go index 72c442786..880631021 100644 --- a/internal/webui/config_schema.go +++ b/internal/webui/config_schema.go @@ -147,7 +147,8 @@ func configFieldDescriptors() []ConfigSection { Description: "Where archied keeps its state, and how it isolates task execution.", Fields: []ConfigField{ {Key: "work_dir", Label: "Work directory", Type: FieldString, Editable: false}, - {Key: "db_path", Label: "State path prefix", Type: FieldString, Editable: false}, + {Key: "state_dir", Label: "State directory", Description: "Embedded NATS store, task logs and the readiness disk probe.", Type: FieldString, Editable: false}, + {Key: "db_path", Label: "Legacy SQLite path prefix", Description: "Locates pre-PostgreSQL files for the one-time import only.", Type: FieldString, Editable: false}, {Key: "database_url", Label: "PostgreSQL URL", Description: "The State Store's database connection; set at boot, restart required.", Type: FieldString, Editable: false}, {Key: "skills_dir", Label: "Shared skills directory", Description: "Empty uses the work directory.", Type: FieldString, Editable: true, RestartRequired: true}, {Key: "plugin_dir", Label: "Daemon plugin directory", Description: "Empty means no daemon plugins.", Type: FieldString, Editable: true, RestartRequired: true}, @@ -192,6 +193,7 @@ func configFieldValues(view ConfigView) map[string]any { "budgets.wall_clock": view.Budgets.WallClock, "budgets.gate_max_failures": view.Budgets.GateMaxFailures, "work_dir": view.Storage.WorkDir, + "state_dir": view.Storage.StateDir, "db_path": view.Storage.DBPath, "database_url": view.Storage.DatabaseURL, "skills_dir": view.Storage.SkillsDir, diff --git a/internal/webui/config_schema_test.go b/internal/webui/config_schema_test.go index 5b3110ae4..41c97b0f2 100644 --- a/internal/webui/config_schema_test.go +++ b/internal/webui/config_schema_test.go @@ -64,7 +64,7 @@ func TestConfigFieldDescriptorsAreComplete(t *testing.T) { "bot_user", "bot_email", "label", "forge.type", "forge.host", "diff_cap_lines", "repos", "models", "providers", "budgets.max_steps", "budgets.wall_clock", "budgets.gate_max_failures", - "work_dir", "db_path", "database_url", "skills_dir", "plugin_dir", "secret_engine_dir", + "work_dir", "state_dir", "db_path", "database_url", "skills_dir", "plugin_dir", "secret_engine_dir", "containers.image", "containers.max_concurrency", "containers.max_uptime", "containers.volume_ttl", "containers.pull_policy", "containers.network", "web.listen", @@ -100,6 +100,7 @@ func TestConfigFieldDescriptorsRestartRequiredIsDeliberate(t *testing.T) { "budgets.wall_clock": false, "budgets.gate_max_failures": false, "work_dir": false, // locked, not merely restart-required + "state_dir": false, // locked, not merely restart-required "db_path": false, // locked, not merely restart-required "database_url": false, // locked, not merely restart-required "skills_dir": true, // absent from reloadableFields @@ -149,7 +150,7 @@ func TestConfigFieldDescriptorsStructuredFieldsAreNotEditable(t *testing.T) { // renderer does not need runtime state to know not to offer an edit // affordance for a key that can never succeed. func TestConfigFieldDescriptorsLockedStorageFieldsAreNotEditable(t *testing.T) { - locked := map[string]bool{"work_dir": true, "db_path": true, "database_url": true} + locked := map[string]bool{"work_dir": true, "state_dir": true, "db_path": true, "database_url": true} for _, section := range configFieldDescriptors() { for _, f := range section.Fields { if locked[f.Key] && f.Editable { From 89b1140d563073612919734455c4561e137ad12f Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Thu, 24 Sep 2026 14:47:53 +1000 Subject: [PATCH 6/8] docs(proto): name the Postgres State Store in the state contract comments --- internal/contracts/state/v1/state.pb.go | 10 +++++----- internal/contracts/state/v1/state_grpc.pb.go | 20 ++++++++++---------- proto/state/v1/state.proto | 20 ++++++++++---------- 3 files changed, 25 insertions(+), 25 deletions(-) diff --git a/internal/contracts/state/v1/state.pb.go b/internal/contracts/state/v1/state.pb.go index 5bfe0a038..8e77fc82b 100644 --- a/internal/contracts/state/v1/state.pb.go +++ b/internal/contracts/state/v1/state.pb.go @@ -1745,7 +1745,7 @@ func (x *Event) GetPrincipalId() string { return "" } -// CapturedEvent mirrors internal/store.CapturedEvent. +// CapturedEvent mirrors storecontract.CapturedEvent. type CapturedEvent struct { state protoimpl.MessageState `protogen:"open.v1"` Id string `protobuf:"bytes,1,opt,name=id,proto3" json:"id,omitempty"` @@ -2178,7 +2178,7 @@ func (x *Binding) GetUpdatedAt() *timestamppb.Timestamp { return nil } -// WorkflowStat mirrors internal/store.WorkflowStat. +// WorkflowStat mirrors storecontract.WorkflowStat. type WorkflowStat struct { state protoimpl.MessageState `protogen:"open.v1"` Workflow string `protobuf:"bytes,1,opt,name=workflow,proto3" json:"workflow,omitempty"` @@ -2279,7 +2279,7 @@ func (x *WorkflowStat) GetTotalTokens() int64 { return 0 } -// StageStat mirrors internal/store.StageStat. +// StageStat mirrors storecontract.StageStat. type StageStat struct { state protoimpl.MessageState `protogen:"open.v1"` Workflow string `protobuf:"bytes,1,opt,name=workflow,proto3" json:"workflow,omitempty"` @@ -2356,7 +2356,7 @@ func (x *StageStat) GetErrors() int64 { return 0 } -// DayTokens mirrors internal/store.DayTokens. +// DayTokens mirrors storecontract.DayTokens. type DayTokens struct { state protoimpl.MessageState `protogen:"open.v1"` Day string `protobuf:"bytes,1,opt,name=day,proto3" json:"day,omitempty"` @@ -7421,7 +7421,7 @@ type RecordDispatchRequest struct { BindingId string `protobuf:"bytes,1,opt,name=binding_id,json=bindingId,proto3" json:"binding_id,omitempty"` BindingVersion int64 `protobuf:"varint,2,opt,name=binding_version,json=bindingVersion,proto3" json:"binding_version,omitempty"` CaptureId string `protobuf:"bytes,3,opt,name=capture_id,json=captureId,proto3" json:"capture_id,omitempty"` - // task_id addresses the SQLite-owned task tables, which are not migrating. + // task_id addresses the tasks table. TaskId int64 `protobuf:"varint,4,opt,name=task_id,json=taskId,proto3" json:"task_id,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache diff --git a/internal/contracts/state/v1/state_grpc.pb.go b/internal/contracts/state/v1/state_grpc.pb.go index f99fd10f0..a3a6141a3 100644 --- a/internal/contracts/state/v1/state_grpc.pb.go +++ b/internal/contracts/state/v1/state_grpc.pb.go @@ -92,12 +92,12 @@ const ( // // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream. // -// StateStore is the single gRPC service fronting archie.db (one store, one -// file). See docs/prds/state-store-contract.md for the ownership split: the +// StateStore is the single gRPC service fronting archie's PostgreSQL database. +// See docs/prds/state-store-contract.md for the ownership split: the // workflow-domain Store view (Update/Transition/InsertEvent) is consumer-owned -// in internal/domain/workflow, while the rest of this surface stays -// producer-owned in internal/store. Both are served by the same service and -// the same *store.Store implementation; the proto bypasses the Go +// in internal/domain/workflow, while the rest of this surface is +// producer-owned in internal/domain/storecontract. Both are served by the same +// service over internal/infrastructure/postgres; the proto bypasses the Go // interfacebloat cap (max 8), like gateway.v1.ChatService does. type StateStoreServiceClient interface { // Administrative task credential lifecycle. Worker credentials cannot call these. @@ -933,12 +933,12 @@ func (c *stateStoreServiceClient) EnqueueBindingTask(ctx context.Context, in *En // All implementations must embed UnimplementedStateStoreServiceServer // for forward compatibility. // -// StateStore is the single gRPC service fronting archie.db (one store, one -// file). See docs/prds/state-store-contract.md for the ownership split: the +// StateStore is the single gRPC service fronting archie's PostgreSQL database. +// See docs/prds/state-store-contract.md for the ownership split: the // workflow-domain Store view (Update/Transition/InsertEvent) is consumer-owned -// in internal/domain/workflow, while the rest of this surface stays -// producer-owned in internal/store. Both are served by the same service and -// the same *store.Store implementation; the proto bypasses the Go +// in internal/domain/workflow, while the rest of this surface is +// producer-owned in internal/domain/storecontract. Both are served by the same +// service over internal/infrastructure/postgres; the proto bypasses the Go // interfacebloat cap (max 8), like gateway.v1.ChatService does. type StateStoreServiceServer interface { // Administrative task credential lifecycle. Worker credentials cannot call these. diff --git a/proto/state/v1/state.proto b/proto/state/v1/state.proto index a7a67fbd1..f682cf832 100644 --- a/proto/state/v1/state.proto +++ b/proto/state/v1/state.proto @@ -4,12 +4,12 @@ package state.v1; import "google/protobuf/timestamp.proto"; -// StateStore is the single gRPC service fronting archie.db (one store, one -// file). See docs/prds/state-store-contract.md for the ownership split: the +// StateStore is the single gRPC service fronting archie's PostgreSQL database. +// See docs/prds/state-store-contract.md for the ownership split: the // workflow-domain Store view (Update/Transition/InsertEvent) is consumer-owned -// in internal/domain/workflow, while the rest of this surface stays -// producer-owned in internal/store. Both are served by the same service and -// the same *store.Store implementation; the proto bypasses the Go +// in internal/domain/workflow, while the rest of this surface is +// producer-owned in internal/domain/storecontract. Both are served by the same +// service over internal/infrastructure/postgres; the proto bypasses the Go // interfacebloat cap (max 8), like gateway.v1.ChatService does. service StateStoreService { // Administrative task credential lifecycle. Worker credentials cannot call these. @@ -298,7 +298,7 @@ message Event { string principal_id = 14; } -// CapturedEvent mirrors internal/store.CapturedEvent. +// CapturedEvent mirrors storecontract.CapturedEvent. message CapturedEvent { string id = 1; google.protobuf.Timestamp received_at = 2; @@ -349,7 +349,7 @@ message Binding { google.protobuf.Timestamp updated_at = 12; } -// WorkflowStat mirrors internal/store.WorkflowStat. +// WorkflowStat mirrors storecontract.WorkflowStat. message WorkflowStat { string workflow = 1; int64 runs = 2; @@ -361,7 +361,7 @@ message WorkflowStat { int64 total_tokens = 8; } -// StageStat mirrors internal/store.StageStat. +// StageStat mirrors storecontract.StageStat. message StageStat { string workflow = 1; string stage = 2; @@ -370,7 +370,7 @@ message StageStat { int64 errors = 5; } -// DayTokens mirrors internal/store.DayTokens. +// DayTokens mirrors storecontract.DayTokens. message DayTokens { string day = 1; int64 tokens = 2; @@ -716,7 +716,7 @@ message RecordDispatchRequest { string binding_id = 1; int64 binding_version = 2; string capture_id = 3; - // task_id addresses the SQLite-owned task tables, which are not migrating. + // task_id addresses the tasks table. int64 task_id = 4; } message RecordDispatchResponse {} From 35ebaa6ce4f55f3c9b38689d669b9ba9ee9e5416 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Thu, 24 Sep 2026 14:51:48 +1000 Subject: [PATCH 7/8] docs: describe the PostgreSQL-only stores, state_dir and the import-only db_path Architecture, deployment, installer, skill and PRD text now name the Postgres State Store, the offline recovery commands on database_url, state_dir for host state, and db_path as the legacy-file locator for archie-state-store import. Finalised PRDs, CHANGELOG, docs/news and docs/archive are unchanged records. --- .agents/skills/archie-agent-fleet/SKILL.md | 2 +- .../archie-architecture-contract/SKILL.md | 8 +-- .../skills/archie-codebase-discovery/SKILL.md | 18 ++--- .../skills/archie-config-and-flags/SKILL.md | 4 +- .../skills/archie-debugging-playbook/SKILL.md | 14 ++-- .../archie-diagnostics-and-tooling/SKILL.md | 4 +- .../scripts/delivery-snapshot.sh | 2 +- .../skills/archie-domain-reference/SKILL.md | 10 +-- .../skills/archie-run-and-operate/SKILL.md | 14 ++-- CLAUDE.md | 8 +-- config.example.toml | 16 ++--- deployments/INSTRUCTIONS.md | 2 +- deployments/README.md | 18 ++--- deployments/docker-nats-stack.toml | 8 ++- deployments/local-ollama-standalone.toml | 8 ++- deployments/multi-forge-github-gitea.toml | 8 ++- deployments/single-forge-github.toml | 8 ++- deployments/systemd-user-service.md | 15 ++-- docs/architecture/agent-system.md | 9 +-- docs/architecture/bindings.md | 25 +++---- docs/architecture/configuration.md | 2 +- docs/architecture/identity.md | 2 +- .../architecture/messaging-and-work-intake.md | 8 +-- docs/architecture/migration-decisions.md | 17 +++-- docs/architecture/observability.md | 12 ++-- docs/architecture/safe-change-and-recovery.md | 71 ++++++++----------- docs/data/generated/dev-docs.json | 38 +++++----- docs/prds/binding-secret-encryption.md | 9 ++- docs/prds/dynamic-curators.md | 6 +- docs/prds/eda-playbook-engine.md | 15 ++-- docs/prds/memory-engine-unification.md | 4 +- docs/prds/messaging-service-boundary.md | 6 +- docs/prds/payload-field-mapping.md | 7 +- docs/prds/pr-review-remediation.md | 4 +- docs/prds/service-decomposition.md | 10 +-- docs/prds/state-store-contract.md | 17 +++-- docs/prds/task-run-detail.md | 12 ++-- docs/prds/ui-service-boundary.md | 16 ++--- install.sh | 10 +-- 39 files changed, 248 insertions(+), 219 deletions(-) diff --git a/.agents/skills/archie-agent-fleet/SKILL.md b/.agents/skills/archie-agent-fleet/SKILL.md index 9553b1003..6817655be 100644 --- a/.agents/skills/archie-agent-fleet/SKILL.md +++ b/.agents/skills/archie-agent-fleet/SKILL.md @@ -40,7 +40,7 @@ State these as facts to each lane, not as advice. Each one has cost a real run. |---|---| | **The control plane fails closed.** A stored resource that will not validate stops `archied` starting, and nothing bypasses the control plane at boot. Resource history is the only in-band remedy, and it needs the State Store up. | A lane touching the boot path, a stored resource kind, or the recovery commands is a risk-routed lane for the operator's eyes, not a gate-and-merge lane. Evidence: `docs/architecture/safe-change-and-recovery.md` ("Database settings: degrade paths and recovery"). | | **`internal/webui` must not reach `internal/domain/workflow`.** Go imports are atomic: one reference relinks the whole daemon runtime into the UI binary. | `cmd/archie-ui/architecture_test.go` measures the linked binary (`go list -deps .`), not the imports, and fails on anything under `internal/domain/workflow`. `internal/domain/workflow/task` is a named `gateExceptions` entry that must stay linked — it carries only contract and view types, and a stale exception fails the test in both directions. The same test's gate also excludes `internal/app/archied` from the UI binary, so a helper needed by both the daemon and the `cmd/` binaries belongs in `internal/infrastructure/configuration` (which already owns path resolution), never in `archied`. | -| **The task DB has one owner.** `-tasks.sqlite` is served by the standalone `cmd/archie-state-store` process alone. No second listener, no in-process serving path in the daemon or Gateway. | `boot.openStateStore` (`internal/app/archied/state_store.go`) is the only production caller of `openProductionTaskStore`, and it takes an exclusive flock on `.lock` for the process's life — a second State Store on the same file fails there rather than merely being discouraged. Offline maintenance belongs in subcommands of that binary, never a new `cmd/` entry (`docs/architecture/organisation.md#process-boundaries`). | +| **The task DB has one owner.** The task tables are served by the standalone `cmd/archie-state-store` process alone. No second listener, no in-process serving path in the daemon or Gateway. | `boot.openStateStore` (`internal/app/archied/state_store.go`) is the only place the task store is built, and it holds the `state-store` Postgres ownership lock for the process's life — a second State Store on the same database fails there rather than merely being discouraged. Offline maintenance belongs in subcommands of that binary, never a new `cmd/` entry (`docs/architecture/organisation.md#process-boundaries`). | | **Never commit `.beads/`.** Bead state moves through Dolt; `issues.jsonl` and `interactions.jsonl` are local-only. | A lane that stages `.beads/` pollutes its diff. Closing a bead is not commit-worthy on its own. | | **Generated assets are LAW.** `ui/dist/` and the schema outputs (`docs/data/generated/contracts.json`). | Incorporate them into the commit that shifted them. Never revert, regenerate away, or leave them out. | | **Scratch goes to `/tmp` only.** Never the working tree. | `worktree.CommitAll` stages with go-git's `AddWithOptions{All: true}` (`internal/worktree/worktree.go:502`), which does **not** honour `.gitignore`. An untracked scratch file in a lane worktree is swept onto the task branch. The task brief lives in `.git/task.json` for exactly this reason. | diff --git a/.agents/skills/archie-architecture-contract/SKILL.md b/.agents/skills/archie-architecture-contract/SKILL.md index 40410e40f..4aefe05e5 100644 --- a/.agents/skills/archie-architecture-contract/SKILL.md +++ b/.agents/skills/archie-architecture-contract/SKILL.md @@ -88,7 +88,7 @@ reconciliation, parking/retry/exhaustion, and crash recovery. Read `Store.Transition(ctx, taskID, from, to, detail)` now guards on `from` (`WHERE id=? AND status=?`, returning `store.ErrStaleTransition` on mismatch) and runs the status update plus the transition-history insert in one -transaction (`internal/store/store.go`). The sentinel crosses the State Store +transaction (`internal/infrastructure/postgres/store.go`). The sentinel crosses the State Store gRPC boundary via `mapError`/`unmapError` in `internal/infrastructure/staterpc/values.go`; its canonical message string is part of the wire contract. Earlier non-atomic behavior is the settled fix, @@ -101,7 +101,7 @@ not an open design. | The model never runs git | Keep clone, branch, commit, push, diff, and cleanup in deterministic workspace/worktree steps. | CURRENT: `docs/architecture/agent-system.md`; `internal/worktree/` | | Deterministic constraints outrank prompts | Enforce gates, protected paths, read-only stages, test protection, and change caps outside model instructions. | CURRENT: `docs/architecture/agent-system.md`; `internal/gate/`; `internal/domain/workflow/` | | Agent execution is a data boundary | Send bounded, versioned input; validate correlated output before applying it. | CURRENT foundation: `internal/agentexec/protocol.go`; `docs/architecture/agent-system.md` | -| Every workflow ends explicitly | Preserve terminal outcome or visible park. Preserve crash recovery of interrupted `running` work. | CURRENT: `internal/domain/workflow/workflow.go`; `internal/store/store.go` | +| Every workflow ends explicitly | Preserve terminal outcome or visible park. Preserve crash recovery of interrupted `running` work. | CURRENT: `internal/domain/workflow/workflow.go`; `internal/infrastructure/postgres/store.go` | | Generic plugins stay metadata-only | Keep `plugin.Plugin` at `Name()`/`Version()`. Behavior on typed capability interface with owning `Registry`/`Manager`. | CURRENT-enforced rule: `internal/plugin/architecture_test.go` | | Capability engines own lifecycle | Give resource-owning engines explicit start/health/stop semantics and failure isolation. | APPROVED rule: `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict` | | Trust is explicit | Treat trusted operator-installed in-process code, repository code, out-of-process integrations, and container-isolated code as different trust classes. | APPROVED rule: `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict` | @@ -202,7 +202,7 @@ Source: `docs/architecture/configuration.md`. | Capability-specific plugin behavior | Owning domain's typed registry/manager | Never add behavior to `plugin.Plugin`. | | Broker-neutral publication/subscription mechanics | `internal/eventbus` | Keep message meaning and schemas with their domain. | | Shared policy evaluation/evidence mechanics | No current package. `internal/policy` was the planned location; as of 2026-09-18 policy lives inside playbook bindings (`playbooks/`, `internal/domain/eda/playbook`) and `internal/gate/`. | Keep policy vocabulary, evaluators, and consequences with consuming domain. | -| NATS, SQLite, forge, config decoding, external SDK adapters | `internal/infrastructure/` | Implement a narrow owner-defined contract; translate at boundary. | +| NATS, PostgreSQL, forge, config decoding, external SDK adapters | `internal/infrastructure/` | Implement a narrow owner-defined contract; translate at boundary. | | Construction, cross-domain connection, startup/shutdown | `internal/app/archied` or `internal/app/agentworker` | Keep `cmd/*` thin; define health and shutdown order. | | Deploy assembly | `deployments/` | Do not move application behavior into deployment files. | | Unreviewed memory/tools/workspace/gate/storage/web/RPC/scheduling | **OPEN** | Run `archie-architecture-planning-campaign`. | @@ -213,7 +213,7 @@ Source: `docs/architecture/configuration.md`. | --- | --- | | `TaskContext` is a mutable service bag with config, services, policy, scratch state. | Design narrow step inputs and staged removal. | | Workflow lifecycle split across store, daemon, workflow, gateway, worker. | Trace every writer and reader before changing status. | -| State changes and transition history were non-atomic and `from` was advisory — **settled** in `internal/store`: `Transition` guards on `status=?` and writes status plus history in one transaction. | Keep every status writer behind `Transition`; do not reintroduce a raw `UPDATE tasks SET status`. | +| State changes and transition history were non-atomic and `from` was advisory — **settled** in `internal/infrastructure/postgres`: `Transition` guards on the current status and writes status plus history in one transaction. | Keep every status writer behind `Transition`; do not reintroduce a raw `UPDATE tasks SET status`. | | In-process and container paths put orchestration on different sides of process boundary. | Decide which path survives before extending both. | | Identity uses strings; task uniqueness/NATS dedup omit identity. | Don't promise multi-identity ownership until canonical IDs migrate. | | Container RPC uses root forge/worktree, not task owner's identity. | Known trust/correctness defect — not identity-isolated. | diff --git a/.agents/skills/archie-codebase-discovery/SKILL.md b/.agents/skills/archie-codebase-discovery/SKILL.md index 545638fcd..6ef5af266 100644 --- a/.agents/skills/archie-codebase-discovery/SKILL.md +++ b/.agents/skills/archie-codebase-discovery/SKILL.md @@ -68,8 +68,8 @@ Start at these verified anchors: | Resident daemon | `cmd/archied/main.go` → `internal/app/archied.Run()` (`internal/app/archied/main.go`) → `daemon.Daemon` | | Sandboxed worker | `cmd/archie-agent/main.go` → `internal/app/agentworker/`; NATS boundary in `internal/infrastructure/agenttransport/nats/` | | Task orchestration | `internal/daemon/daemon.go`, `internal/domain/workflow/` | -| Task contracts | `internal/domain/storecontract/storecontract.go` (`TaskStore`); `internal/store/interface.go` holds compatibility aliases only | -| Production task persistence | `internal/store/`; `openProductionTaskStore` reached via `internal/app/archied/state_store.go` | +| Task contracts | `internal/domain/storecontract/storecontract.go` (`TaskStore`) | +| Production task persistence | `internal/infrastructure/postgres/`; built in `internal/app/archied/state_store.go` | | RPC split | `internal/{taskrun,natsrpc,forgerpc,worktreerpc}/` plus `internal/infrastructure/staterpc/` (gRPC State Store) | | Chat and channels | `internal/gateway/`, `internal/channels/` | | Configuration | `internal/config/`, `internal/infrastructure/configuration/`, `config.example.toml`, `deployments/*.toml` | @@ -80,8 +80,8 @@ Start at these verified anchors: ### Map packages before reading files ```sh -go list -f '{{.ImportPath}}|go={{join .GoFiles ","}}|tests={{join .TestGoFiles ","}}' ./internal/store -go list -json ./internal/store +go list -f '{{.ImportPath}}|go={{join .GoFiles ","}}|tests={{join .TestGoFiles ","}}' ./internal/infrastructure/postgres +go list -json ./internal/infrastructure/postgres .agents/skills/archie-codebase-discovery/scripts/package-edges.sh ./internal/... ``` @@ -96,7 +96,7 @@ gopls references -d internal/domain/storecontract/storecontract.go:33:2 gopls implementation internal/domain/storecontract/storecontract.go:33:2 gopls call_hierarchy internal/domain/storecontract/storecontract.go:33:2 go doc ./internal/domain/storecontract.TaskStore -go test ./internal/store -list '.' +go test ./internal/infrastructure/postgres -list '.' ``` ### Generate AST candidates for construction @@ -189,14 +189,16 @@ and `Loader.Dir` for overlay/`conf.d` inputs). There is no `config.Load` or 6. Read contract/architecture tests. 7. Confirm deploy inputs in Compose and CI. -### Trace SQLite persistence +### Trace persistence Treat `internal/domain/storecontract` as the application contract and -`internal/store` as the production SQLite adapter behind it. +`internal/infrastructure/postgres` as the production adapter behind it; the +schema is `internal/infrastructure/postgres/migrations/` and the queries are +sqlc-generated from `queries/`. ```sh gopls implementation internal/domain/storecontract/storecontract.go:33:2 -rg -n 'CREATE TABLE|CREATE INDEX|QueryContext|ExecContext|BeginTx' internal/store +rg -n 'CREATE TABLE|CREATE INDEX' internal/infrastructure/postgres/migrations ``` ## Reject false confidence diff --git a/.agents/skills/archie-config-and-flags/SKILL.md b/.agents/skills/archie-config-and-flags/SKILL.md index 5dce85191..cd1ab837d 100644 --- a/.agents/skills/archie-config-and-flags/SKILL.md +++ b/.agents/skills/archie-config-and-flags/SKILL.md @@ -106,7 +106,7 @@ Do not expose these helper flags as daemon settings. | Keys | Default, validation, and consumer | Status | | --- | --- | --- | -| `work_dir`, `db_path` | Derive from `$XDG_DATA_HOME/archie`, else `$HOME/.local/share/archie`; explicit `~` paths are home-expanded. `db_path` is a prefix: tasks/events use `-tasks.sqlite` and conversations use `-conversations.sqlite`. | production-wired | +| `work_dir`, `state_dir`, `db_path` | Derive from `$XDG_DATA_HOME/archie`, else `$HOME/.local/share/archie`; explicit `~` paths are home-expanded. `state_dir` holds the embedded NATS store and endpoint file, task logs and the readiness disk target. `db_path` only locates the legacy `-tasks.sqlite`, `-eda.sqlite` and `-conversations.sqlite` files for `archie-state-store import` and the boot gate. | production-wired | | `skills_dir` | Empty falls back to `work_dir` for startup workflow registry. | partially-wired | | `plugin_dir` | Empty disables daemon plugin loading; configured directory loaded in `internal/app/archied`. | production-wired | | `poll_interval` | Default `60s`; root poll loop uses it, identities may override only interval. | production-wired | @@ -125,7 +125,7 @@ Do not expose these helper flags as daemon settings. | `diff_cap_lines` | Zero replaced by `400` in `finalize`; `StageDiffCap` treats `<= 0` as disabled. TOML zero cannot disable; negative value does. | production-wired | | `web.listen` | Empty becomes `127.0.0.1:8484`; literal `off` disables. No authentication. | production-wired | | `notify.webhook` | Empty disables; feasibility workflow POSTs human-decision notifications when set. | production-wired | -| `nats.url`, `token_env` | Empty URL keeps SQLite path. Configured token variable must be non-empty. | production-wired | +| `nats.url`, `token_env` | Empty URL keeps the in-process path. Configured token variable must be non-empty. | production-wired | | `containers.*` | See dedicated table below. | production-wired | | `chat.*` | See channel table below. | production-wired | | `memory.provider`, `provider_config` | Feature YAML decodes these; `internal/app/archied` always starts built-in file provider at `work_dir/memory`. | decoded-but-unwired | diff --git a/.agents/skills/archie-debugging-playbook/SKILL.md b/.agents/skills/archie-debugging-playbook/SKILL.md index a90c3bda8..3c4150285 100644 --- a/.agents/skills/archie-debugging-playbook/SKILL.md +++ b/.agents/skills/archie-debugging-playbook/SKILL.md @@ -1,6 +1,6 @@ --- name: archie-debugging-playbook -description: Project-specific symptom-to-evidence triage for archie-core. Load this skill when Archied hangs, parks a task, loses or duplicates work, cannot reach NATS or an agent container, rejects configuration or secrets, shows stale Telegram or dashboard state, loses streamed text, fails MCP startup, reports SQLite state surprises, degrades an optional feature, or when Go tests disagree between a sandbox, editor, CI, and the host. Use it to separate environment failures from code regressions and to choose the next exact diagnostic. +description: Project-specific symptom-to-evidence triage for archie-core. Load this skill when Archied hangs, parks a task, loses or duplicates work, cannot reach NATS or an agent container, rejects configuration or secrets, shows stale Telegram or dashboard state, loses streamed text, fails MCP startup, reports task-state surprises, degrades an optional feature, or when Go tests disagree between a sandbox, editor, CI, and the host. Use it to separate environment failures from code regressions and to choose the next exact diagnostic. --- # Debug Archie from evidence @@ -42,7 +42,7 @@ Use this symptom index: | Telegram reply hangs on the first token | Stream consumer | Streaming | | MCP unit tests pass but a real server hangs | Framing mirror | MCP | | Telegram shows old commands | Token-scoped Telegram state | Telegram | -| Transition succeeds from the wrong state | Store semantics | SQLite/state | +| Transition succeeds from the wrong state | Store semantics | Database/state | | Dashboard skips events but task state is correct | Bounded event buffers | Events | | Search works but never becomes indexed | Missing production wiring | Optional features | | Agent container cannot resolve `nats` | Docker network | Containers | @@ -199,16 +199,16 @@ env GOTMPDIR=/tmp GOCACHE=/tmp/archie-telegram-gocache \ ## Diagnose state, events, containers, and optional features -### SQLite and transitions -`internal/store.Store.Transition` owns task state changes and transition -history: it guards on `from` (`WHERE id=? AND status=?`, returning -`store.ErrStaleTransition`) and writes status plus history in one transaction. +### Database and transitions +`internal/infrastructure/postgres.Store.Transition` owns task state changes and +transition history: it guards on `from`, returning +`storecontract.ErrStaleTransition`, and writes status plus history in one transaction. When state is surprising: read `TaskByID` before/after caller; trace every `Transition`, `Requeue`, `RecoverStale`, `Update` — and remember the daemon exposes these over the gRPC State Store, not NATS. ```bash -env GOTMPDIR=/tmp GOCACHE=/tmp/archie-state-gocache go test ./internal/store -count=1 +env GOTMPDIR=/tmp GOCACHE=/tmp/archie-state-gocache go test ./internal/infrastructure/postgres -count=1 # needs Docker ``` ### Events diff --git a/.agents/skills/archie-diagnostics-and-tooling/SKILL.md b/.agents/skills/archie-diagnostics-and-tooling/SKILL.md index 03697c9ce..a7c16d51a 100644 --- a/.agents/skills/archie-diagnostics-and-tooling/SKILL.md +++ b/.agents/skills/archie-diagnostics-and-tooling/SKILL.md @@ -189,9 +189,9 @@ no dead-code analyzer. ## Collect test, race, coverage, and runtime evidence ```sh -go test ./internal/store -count=1 -coverprofile=/tmp/archie-store.cover +go test ./internal/infrastructure/postgres -count=1 -coverprofile=/tmp/archie-store.cover go tool cover -func=/tmp/archie-store.cover -go test -race ./internal/store -count=1 +go test -race ./internal/infrastructure/postgres -count=1 ``` As of 2026-09-18, the package reported 78.6% statement coverage and passed its diff --git a/.agents/skills/archie-diagnostics-and-tooling/scripts/delivery-snapshot.sh b/.agents/skills/archie-diagnostics-and-tooling/scripts/delivery-snapshot.sh index ea2f40573..97837906c 100755 --- a/.agents/skills/archie-diagnostics-and-tooling/scripts/delivery-snapshot.sh +++ b/.agents/skills/archie-diagnostics-and-tooling/scripts/delivery-snapshot.sh @@ -66,7 +66,7 @@ scan_literal github_container_publish github-workflows 'docker build|docker push # file". The wiring lives in internal/app/archied. scan_literal production_config_resolve composition-root 'configuration\.New\(' internal/app/archied scan_literal production_config_load composition-root 'loadConfig\(|loadRuntimeConfig\(' internal/app/archied -scan_literal production_sqlite_store composition-root 'openProductionTaskStore\(|openStateStore\(' internal/app/archied +scan_literal production_task_store composition-root 'openStateStore\(' internal/app/archied scan_literal production_daemon composition-root '&daemon\.Daemon\{' internal/app/archied scan_literal production_rpc_servers composition-root 'registerTaskRPCServers\(' internal/app/archied diff --git a/.agents/skills/archie-domain-reference/SKILL.md b/.agents/skills/archie-domain-reference/SKILL.md index 39700c12b..8d5bf9f1a 100644 --- a/.agents/skills/archie-domain-reference/SKILL.md +++ b/.agents/skills/archie-domain-reference/SKILL.md @@ -54,7 +54,7 @@ never authorize because two mutable strings match; never rename Agent when only model/provider/display name changes; never pool two Agents' memory. ```bash -rg -n 'type IdentityConfig|type IdentityRunner|Identity string|BotUser string' internal/config internal/daemon internal/store internal/gateway +rg -n 'type IdentityConfig|type IdentityRunner|Identity string|BotUser string' internal/config internal/daemon internal/infrastructure/postgres internal/gateway ``` ## Use the canonical interaction vocabulary @@ -87,7 +87,7 @@ Do not describe current `/spawn` as this target. It directly creates a `task.Task` with synthetic forge issue number. ```bash -rg -n 'type Message struct|type MessageEvent struct|ToLegacy|type Conversation struct|CreateTask|EnqueueChatTask|synthetic' internal/domain/messaging internal/gateway internal/store internal/app/archied +rg -n 'type Message struct|type MessageEvent struct|ToLegacy|type Conversation struct|CreateTask|EnqueueChatTask|synthetic' internal/domain/messaging internal/gateway internal/infrastructure/postgres internal/app/archied ``` ## Use the canonical execution vocabulary @@ -119,12 +119,12 @@ running after crash -> queued ``` Do not claim enforced. `Store.Transition` now guards on `from` -(`WHERE id=? AND status=?` → `store.ErrStaleTransition`) and writes status plus +(→ `storecontract.ErrStaleTransition`) and writes status plus history in one transaction; the sentinel crosses the State Store gRPC boundary. -See `internal/store/store.go`. +See `internal/infrastructure/postgres/store.go`. ```bash -rg -n 'Status[A-Za-z]+|func \(s \*Store\) Transition|func \(s \*Store\) Requeue|RecoverStale' internal/store internal/domain/workflow internal/gateway +rg -n 'Status[A-Za-z]+|func \(s \*Store\) Transition|func \(s \*Store\) Requeue|RecoverStale' internal/infrastructure/postgres internal/domain/workflow internal/gateway ``` ## Keep memory scope separate from conversation scope diff --git a/.agents/skills/archie-run-and-operate/SKILL.md b/.agents/skills/archie-run-and-operate/SKILL.md index 79c200cbd..78e440324 100644 --- a/.agents/skills/archie-run-and-operate/SKILL.md +++ b/.agents/skills/archie-run-and-operate/SKILL.md @@ -13,12 +13,12 @@ history. | Term | Meaning here | |---|---| -| `archied` | Resident orchestrator. Owns config, forge credentials, SQLite stores, worktrees, gateways, dashboard, optional NATS/Docker orchestration. | +| `archied` | Resident orchestrator. Owns config, forge credentials, worktrees, gateways, dashboard, optional NATS/Docker orchestration. | | `archie-agent` | Long-running NATS worker. Consumes per-stage `archie.agent.>` requests and full-task `archie.taskrun.>` requests. Not a stdin/stdout worker. | | Stage request | One autonomous workflow stage sent on `archie.agent..request`. | | Full-task handoff | A whole workflow sent on core NATS subject `archie.taskrun.` to a task container. | | Work directory | `work_dir`: task clones plus memory and candidate index artifacts. | -| State path prefix | `db_path`: the configured prefix. Task/event state uses `-tasks.sqlite`; conversation state uses `-conversations.sqlite`. | +| State directory | `state_dir` (default `~/.local/share/archie`): embedded NATS store, task logs. Task, event, capture and conversation data live in the PostgreSQL database `database_url` names. `db_path` only locates pre-PostgreSQL files for `archie-state-store import`. | ## Apply the operational safety boundary @@ -65,7 +65,7 @@ Both linked binaries may also display Go's `-quickchecks` flag from | Config shape | What runs | Operational status on 2026-09-18 | |---|---|---| -| `agent.mode = "inprocess"` and no `[nats]` | `archied` polls and claims from SQLite, runs workflow stages and model tools in-process. | **Production-wired candidate.** No process or OS isolation. | +| `agent.mode = "inprocess"` and no `[nats]` | `archied` polls and claims through the State Store, runs workflow stages and model tools in-process. | **Production-wired candidate.** No process or OS isolation. | | `agent.mode = "subprocess"` | `archied` starts `agent.command` per stage and expects one JSON invocation on stdin, one response on stdout. | **Open/broken with default command.** `cmd/archie-agent` is a long-running NATS worker and never calls `agentexec.ServeOne`. | | `agent.mode = "nats"`, `[nats]`, containers disabled | `archied` runs the workflow; each autonomous stage goes to a separately started `archie-agent`. | **Implemented but operator-assembled.** Launch and supervise a worker separately. | | `agent.mode = "nats"`, `[nats]`, `containers.enabled = true` | `archied` publishes task discovery through JetStream, prepares a worktree, spawns one agent container, sends the whole workflow on `archie.taskrun.`. | **Host daemon + Compose NATS path.** `deployments/docker-nats-stack.toml` demonstrates it. | @@ -95,7 +95,7 @@ startup did not complete. The daemon has no HTTP health endpoint. Stop with `Ctrl-C`. The signal cancels active work, waits for dispatch goroutines, stops capability and memory managers, removes Archie-labelled -containers, closes NATS, and closes the SQLite stores. +containers, closes NATS, and closes its store connections. ## Run a standalone NATS worker @@ -154,8 +154,8 @@ are spawned by the host `archied` process through `/var/run/docker.sock`. |---|---| | Daemon logs | JSON on host stderr; the configured host supervisor captures them. | | Agent logs | JSON on worker/container stderr. Task containers use `AutoRemove`. | -| Tasks and events | SQLite database at `-tasks.sqlite`; default `~/.local/share/archie/archie.db-tasks.sqlite`. | -| Chat sessions and messages | SQLite database at `-conversations.sqlite`. | +| Tasks and events | PostgreSQL (`database_url`), served by `archie-state-store`. | +| Chat sessions and messages | PostgreSQL (`database_url`), served by `archie-gateway`. | | Default task worktree | `/-/issue-`; default root `~/.local/share/archie/work`. | | Identity worktree | `/identity-/-/issue-`. | | Container worktree | Host worktree bind-mounted read/write at `/data/worktree`; `task.json` written under `.git/` so the agent's commit cannot sweep it onto the task branch. | @@ -217,7 +217,7 @@ Docker builds. The Gitea workflow that used to be the production build path was dropped (`dd9bddc2`); `deployments/*.toml` are the supported profiles. Before promotion: record running image IDs/digests; config checksums (no -secrets); task counts via safe GET; establish a SQLite backup procedure. +secrets); task counts via safe GET; take backups with `archie-state-store backup`. No complete rollback command exists, no versioned image tags. Restoring a binary does not undo forge changes, task transitions, or data-format changes. diff --git a/CLAUDE.md b/CLAUDE.md index e11f2c3b3..f7ed0376a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -222,10 +222,10 @@ structures found in legacy packages. breaks `errors.Is` on the client without changing behavior visibly -- treat those message constants as part of the wire contract. - The State Store is a standalone process (`cmd/archie-state-store`, run via - `archied.RunStateStore`) -- the daemon and Gateway never own `archie.db` or - serve this service in-process; `boot.openStateStore` in - `internal/app/archied/state_store.go` is the only caller of - `openProductionTaskStore`. Never add a second listener for the same + `archied.RunStateStore`) -- the daemon and Gateway never own the task + tables or serve this service in-process; `boot.openStateStore` in + `internal/app/archied/state_store.go` is the only place the task store + is built. Never add a second listener for the same service, and never reintroduce an in-process serving path in the daemon/Gateway (`TestOpenStoresNeverOwnsTaskDB` guards this). - Per-task credentials are scoped, not just authenticated: `daemon. diff --git a/config.example.toml b/config.example.toml index 3267ec6b8..9323faac5 100644 --- a/config.example.toml +++ b/config.example.toml @@ -13,10 +13,11 @@ # secret_engine_dir = "~/.config/archie/secret-engines" # work_dir = "~/.local/share/archie/work" # default -# db_path = "~/.local/share/archie/archie.db" # prefix for independent task and conversation SQLite files +# state_dir = "~/.local/share/archie" # default; embedded NATS store, task logs, disk probe +# db_path = "~/.local/share/archie/archie.db" # default; locates pre-PostgreSQL SQLite files for the import only # The PostgreSQL connection archie-state-store, archied and archie-gateway -# serve from. Required: each fails closed rather than fall back to SQLite. +# serve from. Required: each fails closed without it. # An install with SQLite stores under db_path runs `archie-state-store import` # once, with archie stopped, before it starts. `docker compose up -d postgres` starts # a matching local postgres:18 with this default URL. @@ -349,9 +350,9 @@ target = "127.0.0.1:8585" # archie-gateway's gRPC address (always remot [services.state] target = "127.0.0.1:9090" # REQUIRED. The State Store gRPC address archied and -# # archie-gateway dial. They no longer own archie.db +# # archie-gateway dial. They own no task data # # in-process: the standalone archie-state-store process -# # owns the single SQLite file (docs/prds/state-store-contract.md +# # owns it in PostgreSQL (docs/prds/state-store-contract.md # # §10/§12 step 7). An empty target is a startup error. # listen = "127.0.0.1:9090" # The address archie-state-store BINDS. Read only by that # # process; every client ignores it. Defaults to the target @@ -379,10 +380,9 @@ target = "127.0.0.1:9090" # REQUIRED. The State Store gRPC address arch # Unbound webhook capture: POST /webhooks/capture/{source} accepts and # stores any inbound payload archie doesn't yet have a binding for, so it can # be inspected and mapped later (see docs/prds/event-capture-storage.md). -# Stored in the same SQLite database as tasks, not NATS -- capture has one +# Stored in the same PostgreSQL database as tasks, not NATS -- capture has one # writer and one (human, dashboard) reader, so it doesn't need JetStream's -# fan-out/replay machinery, and SQLite is available in every deployment -# shape unconditionally. All fields default when the section is absent; +# fan-out/replay machinery. All fields default when the section is absent; # capture is on by default. # # From the UI cutover (archie-core-8cda.5.4) the receiver is mounted by the @@ -435,7 +435,7 @@ target = "127.0.0.1:9090" # REQUIRED. The State Store gRPC address arch # Playbook-binding at-rest encryption: [bindings].encryption_key resolves a # 32-byte high-entropy key through the secret registry (engine + key) and seals -# each binding's HMAC secret in the SQLite bindings.secret column with AES-256- +# each binding's HMAC secret in the bindings.secret column with AES-256- # GCM (see docs/prds/binding-secret-encryption.md). When the key is absent, # binding secrets are stored as plaintext (the pre-t2db.7 behaviour) -- enabling # encryption does not retroactively encrypt existing rows, which stay plaintext diff --git a/deployments/INSTRUCTIONS.md b/deployments/INSTRUCTIONS.md index 6b78be68a..b4c97fbb4 100644 --- a/deployments/INSTRUCTIONS.md +++ b/deployments/INSTRUCTIONS.md @@ -18,7 +18,7 @@ This archive contains six linux/amd64 binaries: this process they are simply absent — and nothing logs an error (`archie-core-1c01`), which is why it has a unit of its own in `deployments/systemd-user-service.md`. -- **`archie-state-store`** — owns the single `archie.db` SQLite file behind +- **`archie-state-store`** — owns the task data in PostgreSQL behind a gRPC contract. `archied` and `archie-gateway` are gRPC clients of it, not owners of the database. - **`archie-playbooks`** — standalone CLI to lint playbook binding YAML diff --git a/deployments/README.md b/deployments/README.md index 24c9c4d20..27448a581 100644 --- a/deployments/README.md +++ b/deployments/README.md @@ -43,13 +43,13 @@ systemctl --user start archied ``` The templates use the extracted Gateway Service by default. Start -`archie-gateway` before `archied`; it owns the conversation SQLite file and +`archie-gateway` before `archied`; it owns the conversation tables and serves the `ChatContract` gRPC API on the configured target. -The State Store service (`archie-state-store`) owns the single `archie.db` task -SQLite file and serves the `StateStore` gRPC contract. After the in-process -store path was deleted, BOTH `archied` and `archie-gateway` dial it via -`[services.state].target` and never open `archie.db` themselves +The State Store service (`archie-state-store`) owns the task data in the +PostgreSQL database `database_url` names and serves the `StateStore` gRPC +contract. BOTH `archied` and `archie-gateway` dial it via +`[services.state].target` and never open the task tables themselves (`docs/prds/state-store-contract.md` §12 step 7). The templates set `[services.state]` accordingly: a host-only agent reaches a loopback bind (`127.0.0.1:9090`) with no token, while a container-mode agent needs the @@ -117,10 +117,10 @@ curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9091/healthz # curl -s http://127.0.0.1:9091/health/detailed # state_db component -> 200, or 503 when degraded ``` -A running State Store owns exactly one task SQLite file (`-tasks.sqlite`); -`archied` and `archie-gateway` never open `archie.db` directly, so a second -store process on the same `db_path`, or a consumer that opens the task file, -indicates dual-store ownership (`docs/prds/state-store-contract.md` §12 step 7/8). +A running State Store holds the `state-store` ownership lock on its database; +`archied` and `archie-gateway` never open the task tables directly, so a second +store process on the same `database_url` refuses to start, and a consumer that +opens the task tables indicates dual-store ownership (`docs/prds/state-store-contract.md` §12 step 7/8). The readiness probe is the single-writer check the runbook has against a degraded store: a `503` from `/health/detailed` means `archied` should be started only after the store is healthy. diff --git a/deployments/docker-nats-stack.toml b/deployments/docker-nats-stack.toml index fa22f1614..3554396c3 100644 --- a/deployments/docker-nats-stack.toml +++ b/deployments/docker-nats-stack.toml @@ -15,7 +15,9 @@ poll_interval = "60s" bot_user = "archie" diff_cap_lines = 0 work_dir = "~/.local/share/archie/work" -db_path = "~/.local/share/archie/archie.db" +state_dir = "~/.local/share/archie" # NATS store, task logs +# db_path (default ~/.local/share/archie/archie.db) only locates pre-PostgreSQL +# files for `archie-state-store import`. # The State Store's PostgreSQL connection (required; Postgres-only epic). # `docker compose up -d postgres` provides this local default; point it at # your own Postgres 18 server otherwise. @@ -24,8 +26,8 @@ database_url = "postgres://archie:archie@127.0.0.1:5432/archie?sslmode=disable" [services.gateway] target = "127.0.0.1:8585" -# The State Store gRPC service owns the single archie.db SQLite file; archied -# and archie-gateway dial it and never open archie.db themselves (§12 step 7). +# The State Store gRPC service owns the PostgreSQL task data; archied and +# archie-gateway dial it and never open those tables themselves (§12 step 7). # This deployment runs the agent in containers, so target is the Docker bridge # gateway (172.17.0.1) the container can reach, with a matching target_token # that archie-state-store validates. Host-only agent: use 127.0.0.1:9090 with diff --git a/deployments/local-ollama-standalone.toml b/deployments/local-ollama-standalone.toml index 3c202d039..2d3804d0e 100644 --- a/deployments/local-ollama-standalone.toml +++ b/deployments/local-ollama-standalone.toml @@ -6,7 +6,9 @@ # ============================================================================== work_dir = "~/.local/share/archie/work" -db_path = "~/.local/share/archie/archie.db" +state_dir = "~/.local/share/archie" # NATS store, task logs +# db_path (default ~/.local/share/archie/archie.db) only locates pre-PostgreSQL +# files for `archie-state-store import`. # The State Store's PostgreSQL connection (required; Postgres-only epic). # `docker compose up -d postgres` provides this local default; point it at # your own Postgres 18 server otherwise. @@ -15,8 +17,8 @@ database_url = "postgres://archie:archie@127.0.0.1:5432/archie?sslmode=disable" [services.gateway] target = "127.0.0.1:8585" -# The State Store gRPC service owns the single archie.db SQLite file; archied -# and archie-gateway dial it and never open archie.db themselves (§12 step 7). +# The State Store gRPC service owns the PostgreSQL task data; archied and +# archie-gateway dial it and never open those tables themselves (§12 step 7). # Host-only deployment: the agent runs on the host, so the loopback target # 127.0.0.1:9090 needs no token. Start archie-state-store with the matching # `-listen 127.0.0.1:9090`. diff --git a/deployments/multi-forge-github-gitea.toml b/deployments/multi-forge-github-gitea.toml index f5727333b..09ea48e2d 100644 --- a/deployments/multi-forge-github-gitea.toml +++ b/deployments/multi-forge-github-gitea.toml @@ -7,7 +7,9 @@ # ============================================================================== work_dir = "~/.local/share/archie/work" -db_path = "~/.local/share/archie/archie.db" +state_dir = "~/.local/share/archie" # NATS store, task logs +# db_path (default ~/.local/share/archie/archie.db) only locates pre-PostgreSQL +# files for `archie-state-store import`. # The State Store's PostgreSQL connection (required; Postgres-only epic). # `docker compose up -d postgres` provides this local default; point it at # your own Postgres 18 server otherwise. @@ -16,8 +18,8 @@ database_url = "postgres://archie:archie@127.0.0.1:5432/archie?sslmode=disable" [services.gateway] target = "127.0.0.1:8585" -# The State Store gRPC service owns the single archie.db SQLite file; archied -# and archie-gateway dial it and never open archie.db themselves (§12 step 7). +# The State Store gRPC service owns the PostgreSQL task data; archied and +# archie-gateway dial it and never open those tables themselves (§12 step 7). # This deployment runs the agent in containers, so target is the Docker bridge # gateway (172.17.0.1) the container can reach, with a matching target_token # that archie-state-store validates. Host-only agent: use 127.0.0.1:9090 with diff --git a/deployments/single-forge-github.toml b/deployments/single-forge-github.toml index 88ea68fb5..0d9823dd0 100644 --- a/deployments/single-forge-github.toml +++ b/deployments/single-forge-github.toml @@ -6,7 +6,9 @@ # ============================================================================== work_dir = "~/.local/share/archie/work" -db_path = "~/.local/share/archie/archie.db" +state_dir = "~/.local/share/archie" # NATS store, task logs +# db_path (default ~/.local/share/archie/archie.db) only locates pre-PostgreSQL +# files for `archie-state-store import`. # The State Store's PostgreSQL connection (required; Postgres-only epic). # `docker compose up -d postgres` provides this local default; point it at # your own Postgres 18 server otherwise. @@ -23,8 +25,8 @@ diff_cap_lines = 400 [services.gateway] target = "127.0.0.1:8585" -# The State Store gRPC service owns the single archie.db SQLite file. archied -# and archie-gateway dial it here and never open archie.db themselves +# The State Store gRPC service owns the PostgreSQL task data. archied and +# archie-gateway dial it here and never open those tables themselves # (docs/prds/state-store-contract.md §12 step 7). This deployment runs the # agent in containers, so the target must be the Docker bridge gateway address # (172.17.0.1) that the container can reach, and a non-loopback target requires diff --git a/deployments/systemd-user-service.md b/deployments/systemd-user-service.md index 96832982d..687eb577d 100644 --- a/deployments/systemd-user-service.md +++ b/deployments/systemd-user-service.md @@ -16,11 +16,10 @@ here, where it would drift from what is written. The Gateway unit is `archie-gateway.service`, written by `install.sh` beside `archied.service`. -The State Store unit is `archie-state-store.service`. It owns the single `archie.db` SQLite -file and serves the `StateStore` gRPC contract. After the in-process store path -was deleted, BOTH `archied` and `archie-gateway` dial it via -`[services.state].target` (see the `archied` config below) and never open -`archie.db` themselves (`docs/prds/state-store-contract.md` §12 step 7). A +The State Store unit is `archie-state-store.service`. It owns the task data in +PostgreSQL and serves the `StateStore` gRPC contract. BOTH `archied` and +`archie-gateway` dial it via `[services.state].target` (see the `archied` +config below) and never open the task tables themselves (`docs/prds/state-store-contract.md` §12 step 7). A host-only agent uses the loopback bind with no token below; a container-mode agent needs the Docker bridge gateway address plus a bearer token via `--token`/`STATE_STORE_TOKEN` or `[services.state].target_token`, and a @@ -254,6 +253,6 @@ with the operator's Docker credentials and retain `pull_policy = "missing"`: docker compose pull agent ``` -`db_path` and other paths are native host paths. Point them at the intended -state directory; changing from an old containerized daemon path can otherwise -start Archie against empty state files. +`state_dir` and other paths are native host paths. Point `state_dir` at the +intended state directory (embedded NATS store, task logs); `db_path` only +locates pre-PostgreSQL files for `archie-state-store import`. diff --git a/docs/architecture/agent-system.md b/docs/architecture/agent-system.md index bcf7d48da..daafd0942 100644 --- a/docs/architecture/agent-system.md +++ b/docs/architecture/agent-system.md @@ -194,8 +194,9 @@ Every WorkflowExecution is handed wholesale over core NATS to a task-scoped The behaviour is divided across technical packages: -- `internal/store` defines the current `Task` execution record and status - strings and persists mutable state and transition history. +- `internal/domain/workflow` defines the current `Task` execution record and + status strings; `internal/infrastructure/postgres` persists mutable state + and transition history behind `internal/domain/storecontract`. - `internal/daemon` discovers, claims, schedules, retries, recovers, processes, waits for human input, and reconciles pull requests. - `internal/domain/workflow` routes work, executes stages, mutates tasks, applies @@ -205,7 +206,7 @@ The behaviour is divided across technical packages: - `internal/gate` and repository configuration define execution constraints. - `internal/gateway` duplicates task status strings and applies task-control rules. -- forge, worktree, NATS, SQLite, containers, and agent runtimes are concrete +- forge, worktree, NATS, PostgreSQL, containers, and agent runtimes are concrete dependencies mixed into orchestration. ## Current `task` meanings and required replacements @@ -217,7 +218,7 @@ each meaning deliberately; a global text replacement is prohibited. | -------------------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Forge issue or external task | `internal/forge`, daemon polling | Channel message | Preserve the channel's native reference and payload. Translate it into an Agent System request without importing forge or issue semantics into Workflow. | | Jira issue or other external work item | Messaging infrastructure adapter | Channel message or external artifact | The external system retains its own vocabulary inside its integration. Its record may lead to an accepted work request but is not a Workflow or WorkflowExecution. | -| Persisted `store.Task` row | `internal/store` | WorkflowExecution | Own identity, Workflow ID and version, lifecycle, source-message reference, outputs, attempts, and outcome. Persistence implements the Agent System repository contract. | +| Persisted `workflow.Task` row | `internal/infrastructure/postgres` | WorkflowExecution | Own identity, Workflow ID and version, lifecycle, source-message reference, outputs, attempts, and outcome. Persistence implements the Agent System repository contract. | | Task status and transition history | `store.Status*`, `transitions` | WorkflowExecution lifecycle and domain events | Enforce legal transitions atomically. Domain events and state changes cannot diverge. Remove duplicated status strings from consumers. | | Claimed or queued task | `ClaimNext`, `ClaimByIssue`, `RecoverStale` | Scheduled WorkflowExecution | Claim by WorkflowExecution ID and expected version/state. Crash recovery and leases must not silently create a new execution. | | `workflow.TaskContext` | `internal/domain/workflow` | WorkflowExecution context | Replace the mutable service bag with execution state plus narrow step-required contracts. Complete application configuration and unrelated services are forbidden. | diff --git a/docs/architecture/bindings.md b/docs/architecture/bindings.md index 33b759599..ece2b5174 100644 --- a/docs/architecture/bindings.md +++ b/docs/architecture/bindings.md @@ -29,7 +29,7 @@ type Binding struct { } ``` -Bindings live in the store (SQLite), not `config.toml` -- operators author +Bindings live in the store (PostgreSQL), not `config.toml` -- operators author them from the dashboard while the daemon runs, without a restart. ### Matching @@ -96,8 +96,9 @@ unauthenticated event can never trigger a binding, no matter how well it would otherwise match." Enforced structurally at two points, not just convention: -- `captured_events.authenticated` is a real column (`internal/store/ - captures.go`), set at capture time. +- `captures.authenticated` is a real column + (`internal/infrastructure/postgres/migrations/0002_edastore.sql`), set at + capture time. - `dispatchBindings` (`internal/daemon/daemon.go:479`) walks **authenticated captures whose source has at least one armed binding** -- an unauthenticated capture is never even considered for dispatch. @@ -112,7 +113,7 @@ binding reverts it. Capture writes are bounded independently of the approval gate, so a flood of unauthenticated traffic cannot exhaust disk or drown the inspector: -`InsertCapture` (`internal/store/captures.go`) prunes by both **retention +`InsertCapture` (`internal/infrastructure/postgres/edastore.go`) prunes by both **retention window** (`WHERE received_at < cutoff`) and **max event count** in the same insert transaction. @@ -121,14 +122,14 @@ insert transaction. A playbook-originated task is dispatched into the **same** gate, diff-cap, sandboxed-container, worktree-isolation pipeline every task goes through regardless of origin. Verified precisely, not assumed: `dispatchOneBinding` -calls `EnqueueBindingTask` (`internal/store/store.go`), which wraps +calls `EnqueueBindingTask` (`internal/infrastructure/postgres/store.go`), which wraps `EnqueueChatTask` -- the same direct-to-`tasks`-table enqueue path chat-spawned tasks already use, then stamps `binding_id`/`binding_version` for provenance in a second statement. This is a **different** enqueue mechanism from forge-issue polling's `workintake.TaskEnvelope`/NATS path (`docs/prds/event-sources-and-reactions.md`) -- binding and forge-issue tasks arrive by different producers, but both become an ordinary -`store.Task` row that `ClaimNext` picks up identically, so both get the +`workflow.Task` row that `ClaimNext` picks up identically, so both get the same gate/worktree pipeline downstream regardless of which producer created the row. Payload content is ordinary untrusted prompt input; the sender's text is never treated as a @@ -151,8 +152,8 @@ Two independent protections, not one: ### Secrets at rest `Binding.Secret` (the HMAC shared secret a sender signs with) is encrypted -at rest via AES-GCM (`internal/store/binding_cipher.go`, `archie-core- -t2db.7`) -- a leaked SQLite file does not leak sender-side shared secrets in +at rest via AES-GCM (`internal/infrastructure/bindingcipher`, `archie-core- +t2db.7`) -- a leaked database dump does not leak sender-side shared secrets in plaintext. The envelope is versioned (`bindingEnvelopeVersion`) so a future cipher or KDF change can roll forward without breaking already-encrypted rows, and the AAD binds ciphertext to the binding-secret context so it @@ -164,8 +165,8 @@ documented legacy behaviour, not silent degradation. `dispatchBindings` enqueues at most one task per `(binding, capture)` pair, enforced by a real ledger, not best-effort application logic: -`RecordDispatch` (`internal/store/bindings.go`) does `INSERT OR IGNORE` into -`binding_dispatches`, unique on `(binding_id, capture_id)`; a duplicate +`RecordDispatch` (`internal/infrastructure/postgres/edastore.go`) inserts into +`binding_dispatches`, unique on `(binding, capture)`; a duplicate insert returns the sentinel `ErrAlreadyDispatched`, which the dispatch loop treats as "another cycle raced us," not an error. This guarantee holds **across daemon restarts**, not just within one process's lifetime, because @@ -173,8 +174,8 @@ the ledger is a durable table, not in-memory state. This ledger is also the direct precedent for the EDA playbook engine's execution-time idempotency, now landed (`archie-core-t2db.17` closed): the -`playbook_dispatches` table in `internal/store/playbook_dispatches.go` copies -`binding_dispatches`'s `INSERT OR IGNORE` conventions with a +`playbook_dispatches` table (`RecordPlaybookDispatch`) copies +`binding_dispatches`'s unique-ledger conventions with a `(playbook_id, playbook_version, event_id, action_id)` key (`docs/prds/eda-playbook-engine.md` gap 2). diff --git a/docs/architecture/configuration.md b/docs/architecture/configuration.md index a0e832bec..e66a6ed33 100644 --- a/docs/architecture/configuration.md +++ b/docs/architecture/configuration.md @@ -141,7 +141,7 @@ existing structure combines different owners. | Current values | Current location | Target owner and requirement | | ----------------------------------------------------------------------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `WorkDir`, `DBPath` | root `Config` | Workspace/storage infrastructure settings. `DBPath` is the prefix for independent task and conversation SQLite files. Defaults derive from the platform data directory. | +| `WorkDir`, `StateDir`, `DBPath` | root `Config` | Workspace/storage infrastructure settings, bootstrap-only. `StateDir` holds the embedded NATS store and endpoint file, task logs and the readiness disk target. `DBPath` only locates the legacy SQLite files (`-tasks.sqlite`, `-eda.sqlite`, `-conversations.sqlite`) for `archie-state-store import` and the boot gate that refuses to serve until it has run; it goes when the importer does. Defaults derive from the platform data directory. | | `SkillsDir`, `PluginDir` | root `Config` | Skill and plugin infrastructure settings, independently typed. | | `PollInterval` | root `Config` | Work-intake scheduling setting; not a daemon-wide constant. | | `Label`, `BotUser`, `BotEmail` | root `Config` | Identity and dispatch associations. `BotEmail` may be derived from the selected forge account but remains overrideable. | diff --git a/docs/architecture/identity.md b/docs/architecture/identity.md index c689cc7f0..cba27b4aa 100644 --- a/docs/architecture/identity.md +++ b/docs/architecture/identity.md @@ -293,7 +293,7 @@ Focused tests verify that: ## Current hazards -- SQLite task uniqueness is `(owner, repo, issue_number)` and excludes identity. +- Task uniqueness is `(owner, repo, issue_number)` and excludes identity. Two identities discovering the same forge issue cannot own distinct task records. - NATS deduplication uses `owner/repo/issue` and excludes identity, so discovery diff --git a/docs/architecture/messaging-and-work-intake.md b/docs/architecture/messaging-and-work-intake.md index d7f6b8c93..843102764 100644 --- a/docs/architecture/messaging-and-work-intake.md +++ b/docs/architecture/messaging-and-work-intake.md @@ -104,7 +104,7 @@ The canonical session and message implementation must supply: metadata; - session lifecycle and active-request state; - session-to-agent-instance and parent-session lineage; -- durable SQLite round trips and timestamp validation. +- durable database round trips and timestamp validation. These semantics must use the confirmed Agent, user, channel-binding, and conversation ownership model. @@ -264,7 +264,7 @@ queued. delivery source, so a webhook-delivered issue and a later poll of the same issue dedup through `PublishUnique` instead of double-enqueuing. - Chat-spawned and playbook-binding-dispatched work enqueues through - `EnqueueChatTask`/`EnqueueBindingTask` (`internal/store`), stamped with + `EnqueueChatTask`/`EnqueueBindingTask` (`internal/infrastructure/postgres`), stamped with `binding_id`/`binding_version` for provenance. Webhook intake is opt-in per deployment (`Forge.Intake` = `poll` (default), @@ -287,7 +287,7 @@ model and its threat model are `docs/architecture/bindings.md`. the Agent System. - Source identity is incomplete: sessions use configured bot usernames, tasks use identity strings, and external message IDs are generally absent. -- SQLite and NATS deduplication are based on forge coordinates rather than a +- Database and NATS deduplication are based on forge coordinates rather than a channel-neutral source-message reference. - Replies and acknowledgements have no durable delivery-attempt lifecycle, so partial success and retry behaviour differ by adapter. @@ -316,7 +316,7 @@ model and its threat model are `docs/architecture/bindings.md`. Semantic/vector search over chat messages is an **explicit non-goal** until usage data shows a real need. -Message search is lexical only: session-scoped SQLite FTS5 queries paged via +Message search is lexical only: session-scoped PostgreSQL full-text queries paged via `MessageQuery{Query,Limit,Offset}` → `MessagePage`. Do not add embeddings configuration or vector columns to message records. diff --git a/docs/architecture/migration-decisions.md b/docs/architecture/migration-decisions.md index 326c1f348..49ceb8a70 100644 --- a/docs/architecture/migration-decisions.md +++ b/docs/architecture/migration-decisions.md @@ -182,8 +182,8 @@ the chat service's session-store RPCs and is proven by `TestStoreClientPreservesCanonicalRecords`. It is deliberately unwired. Production `archied` dials the standalone gateway for `ChatContract` only (`composeChatContract` → `gatewayrpc.Dial` returns a `*Client`, not a -`*StoreClient`), and the daemon's session store is in-process SQLite via -`makeTelegramSessionStore`. The test comment that says it mirrors production +`*StoreClient`), and the Gateway's session store is PostgreSQL via +`gateway.NewPostgresSessionStore`. The test comment that says it mirrors production describes the target, not today's tree. Kept rather than deleted because the migration it serves is deferred by this very section, and re-deriving a tested wire adapter once that lands is pure cost. @@ -221,7 +221,10 @@ prohibition list is untouched. not cover (2026-09-22, `archie-core-1ng1`).** The PRD's deletion gate cannot pass today. `cmd/archie-messaging/architecture_test.go` does not exist, and the check that section specifies -- `go list -deps ./cmd/archie-messaging` links -zero banned runtime packages -- reports four: +zero banned runtime packages -- reported four at the time (the task store was +then `internal/store` over `modernc.org/sqlite`; the gate now bans +`modernc.org/sqlite`, `github.com/jackc/pgx`, `internal/infrastructure/postgres` +and `internal/infrastructure/legacyread` in its place): | banned package | PRD category | | --- | --- | @@ -577,9 +580,9 @@ viewer count, and `Broadcast` is a no-op when nobody is watching. Three properties make the cursor sufficient, and a push hub unnecessary: -- **The cursor cannot skip.** `internal/store/store.go` opens the database with - `SetMaxOpenConns(1)`, so writes serialise and a row's `id` is assigned in - commit order. There is no window in which a lower id becomes visible after a +- **The cursor cannot skip.** `internal/infrastructure/postgres` takes an + advisory event-append lock around each insert (`TestEventInsertsCommitInIDOrder`), + so a row's `id` is assigned in commit order. There is no window in which a lower id becomes visible after a higher one, which is the failure mode that normally rules out polling an autoincrement cursor. SSE catch-up already depends on this same property. - **A broadcast is a wakeup, not the payload.** `sseStream.drain` treats each @@ -592,7 +595,7 @@ Three properties make the cursor sufficient, and a push hub unnecessary: - **The table is the only complete fan-out point.** Events reach the store through several paths that never touch the daemon's bus, including the audit event `store.ArchiveTask` writes inside its transaction - (`internal/store/store.go`) and the binding-dispatch failure + (`internal/infrastructure/postgres/store.go`) and the binding-dispatch failure `internal/daemon/daemon.go` inserts directly. A push hub would have to be hooked at every write site and at post-commit, and would silently miss any site added later that forgets to notify. Reading the table misses nothing. diff --git a/docs/architecture/observability.md b/docs/architecture/observability.md index 060716257..86747bf4d 100644 --- a/docs/architecture/observability.md +++ b/docs/architecture/observability.md @@ -165,11 +165,9 @@ would have to guess which side of a boundary an event belongs to across a daemon restart, a stale-run recovery, or two interleaved attempts, and a guess rendered as structure is exactly the false fidelity this surface exists to avoid. -The column reaches an existing database through the presence-gated arm in -`internal/store`'s `migrateTasks` — `eventsSchema` is `CREATE TABLE IF NOT -EXISTS`, so on an existing database the migrator is the *only* thing that adds -it. `PRAGMA user_version` is unchanged because the loop is presence-gated -rather than version-gated, and nothing is backfilled. +The column is part of the events table in +`internal/infrastructure/postgres/migrations/0001_state_store.sql`, and nothing +is backfilled. ### Read surface @@ -310,8 +308,8 @@ attempt". Every part is additive. A capture or a configuration emit that cannot happen leaves the run alone — reporting must never park a task. Reverting the change set removes the endpoints and the page; the extra column and the extra event -kinds are inert to the previous revision (SQLite ignores a column no statement -names, and an unfamiliar event kind already renders as unfamiliar), and there is +kinds are inert to the previous revision (a column no statement names is +ignored, and an unfamiliar event kind already renders as unfamiliar), and there is no data transformation to undo. ## Dependency direction diff --git a/docs/architecture/safe-change-and-recovery.md b/docs/architecture/safe-change-and-recovery.md index 3be17b1d2..65af755ce 100644 --- a/docs/architecture/safe-change-and-recovery.md +++ b/docs/architecture/safe-change-and-recovery.md @@ -102,7 +102,8 @@ silently oscillate between versions or retry forever. ## Database settings: degrade paths and recovery (2026-09) -The control plane owns runtime-tunable settings and stores them in `archie.db`. +The control plane owns runtime-tunable settings and stores them in the State +Store's PostgreSQL database. This replaced a dashboard overlay store that degraded to file config on any failure and had three documented ways back. The replacement has none, and the posture is the opposite: **the daemon fails closed.** @@ -133,6 +134,12 @@ steps: are read, never written. 3. Start archie. +`db_path` exists only to locate these files for the import and the boot gate +below, and goes with the importer. The embedded NATS store, its endpoint file +and task logs live under `state_dir` (default: the data home's `archie` +directory). An install whose `db_path` sat outside the data home sets +`state_dir` to that directory to keep them where they were. + Each serving process checks this at boot, after migrating the schema. With no completion record and a non-empty legacy file it refuses to start and names the files and the import command, rather than serve empty tables over existing @@ -149,18 +156,20 @@ would fail the first one's in-flight turns). The State Store holds its own. Nothing skips the control plane at boot, and the only writer for a resource is `ControlPlaneService.Command` on a running State Store -- which is exactly what the daemon fails closed without. `archie-state-store` therefore carries the -offline recovery commands (`archie-core-6zw0`). They work on the task database -file directly -- the configured `db_path` with `-tasks.sqlite` appended, not -`db_path` itself -- and need neither `archied` nor the Web UI running: `validate` -reads the configuration file the daemon boots with, which is what makes its -verdict the daemon's verdict. +offline recovery commands (`archie-core-6zw0`). They work on the PostgreSQL +database the configuration's `database_url` names +(`internal/app/archied/state_store_recovery_postgres.go`, +`internal/infrastructure/postgres/maintenance.go`) and need neither `archied` +nor the Web UI running: `validate` reads the configuration file the daemon +boots with, which is what makes its verdict the daemon's verdict. One database +backs every service, so the scope is always the whole database. -| Command | What it does | State Store | +| Command | What it does | Serving processes | | --- | --- | --- | -| `backup -db F -out F` | writes a transactionally consistent snapshot (`VACUUM INTO`), verified as a usable store before it is published | may be running | -| `restore -db F -from F` | replaces the database with a snapshot and drops the replaced file's `-wal`/`-shm` | must be stopped | -| `validate -db F [-config C]` | runs the checks that stop archied starting: the file is readable, uncorrupted and no newer than the binary; every stored resource decodes under the definition that owns it; and `configuration.Validate` accepts the settings the daemon would read -- the stored ones, or the seed the State Store writes for a kind the file does not hold yet -- layered onto `C`, the check the daemon reports as `validate database settings` | may be running | -| `rollback -db F -kind K [-revision N]` | replays an earlier revision of a stored resource through the ordinary replace, recording the rollback as a new revision | must be stopped | +| `backup -out F` | runs `pg_dump --format=custom`, reads the archive back with `pg_restore --list` and only then replaces `F` | may be running | +| `restore -from F` | drops tables the snapshot does not hold and runs `pg_restore --clean --single-transaction`; every write made after the snapshot is lost | every one must be stopped | +| `validate [-config C]` | refuses a schema newer than the binary's highest migration; every stored resource decodes under the definition that owns it; and `configuration.Validate` accepts the settings the daemon would read -- the stored ones, or the seed the State Store writes for a kind the database does not hold yet -- layered onto `C`, the check the daemon reports as `validate database settings` | may be running | +| `rollback -kind K [-revision N]` | replays an earlier revision of a stored resource through the ordinary replace, recording the rollback as a new revision | the State Store must be stopped | The two validation layers `validate` reports are not the same check, and it reports both rather than merging them: the write path's own decode is stricter @@ -173,41 +182,21 @@ restoring one is the same replace the dashboard and the channels already use. The offline command is that operation with the store stopped -- the one state in which the daemon's own API cannot serve it. -"Must be stopped" is checked rather than assumed. The serving process takes an -exclusive flock on `.lock` for its whole life, and `restore` and `rollback` -refuse with `task database is owned by another process` while another process -holds it. The read-only commands -- `backup` and `validate` -- take no lock and -are meant to run against a serving store: `backup` because the update installer -runs inside the process it is replacing and cannot stop the State Store, and -`validate` because an operator checks a running deployment with it. That -`backup` exemption is only sound while backup never replaces the database, so -naming the database as its own `-out` is refused. `scripts/archie-update-install` -takes its pre-flight snapshot through this subcommand rather than through its -own `sqlite3` shell, so the installer and an operator run one implementation. +"Must be stopped" is checked rather than assumed. Each serving process holds a +Postgres ownership lock for its whole life. `rollback` holds the `state-store` +claim for the replay. `restore` claims every service role's lock (`state-store` +and `gateway`) without waiting and refuses if any is held or the check cannot +complete. The read-only commands -- `backup` and `validate` -- take no claim and +are meant to run against a serving database: `backup` because the update +installer runs inside the process it is replacing and cannot stop the State +Store, and `validate` because an operator checks a running deployment with it. +`scripts/archie-update-install` takes its pre-flight snapshot through this +subcommand, so the installer and an operator run one implementation. `rollback` is the surgical route back from a bad stored value; `restore` is the blunt one, and is also the way back from a schema migration a release cannot grow out of. -### The same commands on PostgreSQL - -Without `-db`, each command works on the PostgreSQL database the configuration's -`database_url` names (`internal/app/archied/state_store_recovery_postgres.go`, -`internal/infrastructure/postgres/maintenance.go`). One database backs every -service, so the scope is always the whole database. - -- `backup -out F` runs `pg_dump --format=custom`, reads the archive back with - `pg_restore --list` and only then replaces `F`. It takes no claim and runs - against a serving database. -- `restore -from F` is destructive and offline. It claims every service role's - ownership lock (`state-store` and `gateway`) without waiting and refuses if - any is held or the check cannot complete, then drops tables the snapshot does - not hold and runs `pg_restore --clean --single-transaction`. Every write made - after the snapshot is lost. -- `validate` refuses a schema newer than the binary's highest migration, then - runs the same two validation layers. -- `rollback` holds the `state-store` claim for the replay. - There is no automatic schema rollback. goose `Down` drops tables, so it is data loss, not a rollback. `scripts/archie-update-install` refuses a daemon update it cannot snapshot first, and on a failed update `scripts/archie-update-watchdog` diff --git a/docs/data/generated/dev-docs.json b/docs/data/generated/dev-docs.json index 4736e3ce6..f33bfe1f8 100644 --- a/docs/data/generated/dev-docs.json +++ b/docs/data/generated/dev-docs.json @@ -16,19 +16,19 @@ "url": "/dev/architecture/agent-system/", "title": "Agent System", "section": "Architecture", - "body": "# Agent System\n\n**Status:** Current-state investigation in progress \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Domain framing\n\nThe domain is the Agent System.\n\n`Task` is not a core Agent System concept. Forge tasks, forge issues, Jira\nissues, email, Telegram messages, webhooks, and future external inputs are\nchannel-specific messages. Channels translate those messages into requests to\nthe Agent System; external issue or task models MUST NOT shape execution state.\n\nThe current `store.Task` is a persisted workflow execution. Treating that row as\na task-domain aggregate would incorrectly turn Archie into an agentic issue\nboard.\n\n## Canonical agent interaction model\n\nAn **Agent** is a persistent assistant selected for an interaction. It is not a\nmodel invocation and is not a WorkflowExecution.\n\nEach Agent has its own:\n\n- immutable acting `IdentityID` for ownership and audit;\n- durable memory and learned information about the user;\n- perspective, specialisation, instructions, and communication behaviour;\n- conversation history and channel bindings;\n- available tools, capabilities, and policy;\n- continuity across model or provider changes.\n\nThe underlying model is a replaceable runtime dependency. Changing a model,\nprovider, or model version MUST NOT create a new Agent, discard its memory, or\nchange ownership of its history.\n\nA user MAY create multiple Agents. Each Agent develops its own memory and view\nof the user from the interactions and responsibilities assigned to it. Memories\nMUST NOT be silently pooled merely because Agents belong to the same user or\napplication.\n\nAgent and Identity are separate aggregates. Every Agent references exactly one\nacting IdentityID, and no two Agents share an agent identity. User, system, and\nservice-account identities may exist without an Agent.\n\nAn action initiated through an Agent records the Agent's acting IdentityID and,\nwhen applicable, the initiating user's IdentityID. A future fully automated\nWorkflowExecution MAY use an explicitly selected service-account identity for a\nconcrete unattended use case; this is not the default execution identity.\n\n## Workflow execution identity\n\nA Workflow is owned by an IdentityID. By default, every WorkflowExecution acts\nas the Workflow owner's identity.\n\nFuture delegated execution MAY add an explicit `RunAsIdentityID` assignment to a\nWorkflow. This allows a Workflow owner to select another user or service-account\nidentity for execution without changing Workflow ownership. Until that\ncapability is deliberately introduced, owner identity and execution identity are\nthe same.\n\nWorkflowExecution audit records MUST preserve the Workflow owner, effective\nexecution identity, initiating user when one exists, and any explicit delegation\nthat selected a different run-as identity.\n\n## Memory scopes\n\nThe Agent System requires four distinct durable memory scopes:\n\n- **global shared memory**: information intentionally available across the\n Archie application;\n- **agent-wide memory**: general expertise, operating knowledge, and perspective\n owned by one Agent and safe for that Agent to use across users;\n- **user-wide memory**: information associated with one user and available to\n authorized Agents serving that user;\n- **Agent-user relationship memory**: private history and learned context from\n one particular Agent's relationship with one particular user.\n\nAgent-wide memory is private to its owning Agent by default. Another Agent MUST\nNOT read, inherit, search, or mutate it implicitly.\n\nAgent-user relationship memory is addressed by both AgentID and User IdentityID.\nNeither another Agent serving the same user nor another user speaking to the\nsame Agent may access it implicitly.\n\nArchie is a multi-user system even when initially deployed for one person.\nMultiple users, including family members, may interact with the same configured\nAgents. Per-user memory is therefore an isolation and personalization boundary,\nnot merely an attribution tag on the primary user's records.\n\nAn Agent MUST resolve the initiating user before assembling memory context.\nMemory belonging to one user MUST NOT become visible to another user merely\nbecause both users interact with the same Agent.\n\nShared memory does not erase provenance. Every memory record retains its scope,\nauthor or acting identity, originating user when applicable, source, and\nrevision history. The rules for selecting a write scope, granting access\nto global and user-wide memory, and authorizing explicit cross-scope sharing are\nsettled by [`docs/prds/memory-engine-unification.md`](/dev/prds/memory-engine-unification/)\nand recorded in [`migration-decisions.md`](/dev/architecture/migration-decisions/#5-memory-placement-and-storage)\nsection 5.\n\nAn Agent interaction may answer conversationally, use a tool or capability, read\nor send messages, retain information, or propose durable workflow-backed work.\nNone of these operations inherently requires a WorkflowExecution.\n\n## Agent and Workflow domain boundary\n\nAgent and Workflow are separate domains:\n\n```text\ninternal/domain/agent\ninternal/domain/workflow\n```\n\nThe Agent domain owns persistent assistants, their specialisation, instructions,\nmodel-independent continuity, capability context, and associations with identity\nand memory.\n\nThe Workflow domain owns reusable, user- or Agent-defined behaviour and every\ndurable execution of that behaviour. An Agent may invoke or define a Workflow,\nbut the Workflow is not part of the Agent aggregate and does not require a\nconversational Agent interaction to execute.\n\n## Canonical workflow model\n\nThe Workflow feature uses these canonical terms:\n\n- **Workflow**: a reusable, versioned definition of how an agent behaves and\n performs a kind of work.\n- **WorkflowExecution**: one durable execution of a specific Workflow version.\n- **WorkflowStep**: one defined operation in a Workflow.\n- **StepExecution**: the recorded execution and outcome of one WorkflowStep.\n- **Attempt**: a retry of the same WorkflowExecution, not a new execution.\n\nA Workflow MAY structure any repeatable agent behaviour, including personal\nassistance and scheduled routines. For example, a morning email review may\ncombine a schedule event, message retrieval tool, LLM classification and\nsummarisation, and delivery of the resulting rundown. Workflow is therefore not\nrestricted to forge work, source changes, or requests submitted by a user at\nexecution time.\n\nWorkflows are extensible through Workflow-owned plugins. The Workflow domain\ndefines the typed plugin registration, definition, validation, versioning, and\nexecution contracts. Users and Agents may define reusable Workflows through\nthose contracts.\n\nThe generic plugin contract remains metadata-only. It MUST NOT own Workflow\nsemantics or replace the Workflow registry with generic hooks.\n\n`Workflow` and `WorkflowExecution` are the names used in architecture, generated\nreference, configuration, commands, events, and external contracts. The\nimplementation MAY use package qualification to remain concise:\n\n```go\nworkflow.Definition\nworkflow.Execution\nworkflow.Step\nworkflow.StepExecution\n```\n\nThe unqualified name `Execution` MUST NOT be used in cross-domain contracts or\ndocumentation because it is ambiguous among workflow, tool, command, policy, and\nservice execution.\n\n## Current workflow-execution feature\n\nThe current feature takes a channel request through agent execution and a\ndurable outcome.\n\nCurrent execution state includes source-message references, owning identity,\nrepository, selected workflow and stage, agent output, branch and pull-request\nreferences, token and iteration counts, retry information, human-wait\ninformation, and failure details.\n\nThe current `store.Task` lifecycle uses:\n\n```text\nqueued -\u003e running\nrunning -\u003e waiting_human | pr_open | merged | parked | closed_wont_do\nwaiting_human -\u003e queued | closed_wont_do\nparked -\u003e queued | dead\npr_open -\u003e merged | rejected\nrunning after crash -\u003e queued\n```\n\nWorkflows select and sequence deterministic and agent-run stages. Implement,\nTDD, feasibility, and bootstrap are current Workflow definitions.\nEvery WorkflowExecution is handed wholesale over core NATS to a task-scoped\n`archie-agent` container, which owns the workflow stage loop.\n\n## Current workflow-feature placement\n\nThe behaviour is divided across technical packages:\n\n- `internal/store` defines the current `Task` execution record and status\n strings and persists mutable state and transition history.\n- `internal/daemon` discovers, claims, schedules, retries, recovers, processes,\n waits for human input, and reconciles pull requests.\n- `internal/domain/workflow` routes work, executes stages, mutates tasks, applies\n outcomes, parks failures, and performs forge/worktree operations.\n- `internal/agentexec` defines and runs individual autonomous-stage protocols.\n- `internal/taskrun` hands a complete WorkflowExecution to a container worker.\n- `internal/gate` and repository configuration define execution constraints.\n- `internal/gateway` duplicates task status strings and applies task-control\n rules.\n- forge, worktree, NATS, SQLite, containers, and agent runtimes are concrete\n dependencies mixed into orchestration.\n\n## Current `task` meanings and required replacements\n\nThe existing code uses `task` for unrelated concepts. Migration MUST resolve\neach meaning deliberately; a global text replacement is prohibited.\n\n| Current meaning | Representative locations | Target concept | Requirements |\n| -------------------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Forge issue or external task | `internal/forge`, daemon polling | Channel message | Preserve the channel's native reference and payload. Translate it into an Agent System request without importing forge or issue semantics into Workflow. |\n| Jira issue or other external work item | Messaging infrastructure adapter | Channel message or external artifact | The external system retains its own vocabulary inside its integration. Its record may lead to an accepted work request but is not a Workflow or WorkflowExecution. |\n| Persisted `store.Task` row | `internal/store` | WorkflowExecution | Own identity, Workflow ID and version, lifecycle, source-message reference, outputs, attempts, and outcome. Persistence implements the Agent System repository contract. |\n| Task status and transition history | `store.Status*`, `transitions` | WorkflowExecution lifecycle and domain events | Enforce legal transitions atomically. Domain events and state changes cannot diverge. Remove duplicated status strings from consumers. |\n| Claimed or queued task | `ClaimNext`, `ClaimByIssue`, `RecoverStale` | Scheduled WorkflowExecution | Claim by WorkflowExecution ID and expected version/state. Crash recovery and leases must not silently create a new execution. |\n| `workflow.TaskContext` | `internal/domain/workflow` | WorkflowExecution context | Replace the mutable service bag with execution state plus narrow step-required contracts. Complete application configuration and unrelated services are forbidden. |\n| `taskrun.Request` and `taskrun.Response` | `internal/taskrun`; consumed by `internal/app/agentworker`, decoded by `internal/infrastructure/agenttransport/nats` | WorkflowExecution handoff | This is the versioned worker contract for executing a WorkflowExecution. It carries domain-owned execution data, not store rows or global configuration DTOs. |\n| Per-stage `agentexec.Request.TaskID` | `internal/agentexec` | WorkflowExecutionID correlation | An agent invocation is a bounded WorkflowStep execution. Correlate request/result with WorkflowExecutionID, StepExecutionID, attempt, and protocol version. |\n| NATS `TaskMessage` and `archie.task.*` | `internal/domain/workintake` (subjects, `TaskEnvelope`); `internal/infrastructure/agenttransport/nats` (transport) -- `internal/nats` no longer exists; whether this row's \"current meaning\" itself is now superseded by `TaskEnvelope` needs a closer look, not asserted here | Channel request or WorkflowExecution transport | Discovery messages and execution dispatch are different contracts and subjects. Domain meaning stays outside NATS infrastructure. Identity and source-message idempotency must be explicit. |\n| `taskDispatcher` work item | `internal/daemon` | WorkflowExecution scheduling | Scheduling operates on execution references and declared concurrency policy. Repository serialization is policy, not identity derived from an incomplete task struct. |\n| `container.TaskPayload` and `task.json` | `internal/container`; read by `internal/infrastructure/agentboot` | WorkflowExecution brief | Rename the boot artifact and schema. It identifies the mounted execution and required workspace only; it is not an alternative execution definition. Missing or malformed input must fail startup before the worker subscribes. |\n| `storage.TaskRef` | `internal/storage` | WorkflowExecution workspace lease | Storage receives the minimal execution/workspace reference and policy required to provision and release resources. It does not receive the WorkflowExecution aggregate. |\n| Gateway `TaskCreator` | `internal/gateway` | Accepted work request handoff | A channel may carry a request for durable workflow-backed work, but it does not request or create a WorkflowExecution directly. Work intake admits and routes the request; the Agent System consumes the accepted work request and is the sole owner of selecting a Workflow version and creating the WorkflowExecution. Ordinary agent interactions do not require this handoff. |\n| Gateway `TaskController` and `ChatTaskStatus` | `internal/gateway/tasks.go` | WorkflowExecution commands and query view | Approve, cancel, and status use Agent System contracts. Channel code does not duplicate lifecycle constants or decide transitions. |\n| Gateway `TaskProfile` | `internal/gateway/tasks.go`, `cmd/archied` | Channel/identity execution defaults | This is configuration selecting allowed source targets and default Workflow inputs, not task state. Split it into settings owned by the relevant channel and Agent System features. |\n| `config.TaskConfig` and `TaskForge` | `internal/config` | Worker execution settings and channel/service references | Dissolve with `internal/config`. Each field moves to its owning runtime settings or versioned WorkflowExecution handoff contract. Secrets and external configuration forms do not enter the domain. |\n| `events.Event.TaskID`, task event timelines | `internal/events`, stores, web UI | WorkflowExecutionID and WorkflowExecution events | Authoritative events are Agent System events. Observability and timelines project those events rather than inventing parallel generic task events. |\n| Web UI task lists and counts | `internal/webui`, store query APIs | WorkflowExecution read model | Dashboard status, history, and counts are projections of WorkflowExecution state and events. The UI does not depend on persistence records. |\n| Task-scoped forge/store/worktree RPC | `forgerpc`, `storerpc`, `worktreerpc`, `registerTaskRPCServers` | Execution-scoped capability ports | Worker calls use narrow domain-required service contracts, carry WorkflowExecutionID and IdentityID, and resolve the owning capability binding. Root-client fallback is forbidden. |\n| Per-task worktree, branch, volume, and cleanup | daemon, worktree, storage, container | WorkflowExecution workspace | Every WorkflowExecution receives isolated workspace state. Workspace lifecycle is explicit, identity-aware, recoverable, and controlled outside the model. |\n| Task retry, dead, waiting-human, PR reconciliation | daemon, workflow, gateway | WorkflowExecution lifecycle policies | Retry, waiting, cancellation, reconciliation, and terminal outcomes are Agent System behaviour. Channels and infrastructure report facts or submit commands; they do not mutate state. |\n| Task-run readiness and retry timeouts | daemon taskrun request loop | Worker-dispatch settings and policy | These settings govern WorkflowExecution handoff availability. They are not Workflow data and must be owned by the worker-dispatch capability. |\n\n### Terms that do not migrate\n\n- The `task` command in `Taskfile.yml` is the external Task build tool and keeps\n its name.\n- A forge may call its own records issues or tasks inside its channel adapter.\n- General prose may use “task” informally only when it clearly refers to an\n external system. Agent System contracts and generated reference MUST use the\n canonical Workflow vocabulary.\n\n## Current WorkflowExecution data inventory\n\nThis inventory is the migration ledger for data currently spread across\n`store.Task`, database-only columns, `workflow.TaskContext`, worker messages,\nand surrounding configuration. Implementation SHOULD NOT require another\nrepository-wide search to determine what existing execution data must be\npreserved or deliberately removed.\n\n| Current data | Current representation | Required target |\n| ---------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |\n| Execution identity | `Task.ID`, `task_id`, NATS subjects, logs | Immutable WorkflowExecutionID used consistently by state, events, workers, projections, and capability calls |\n| Owning actor | `Task.Identity` string | Canonical IdentityID |\n| Source type | `Task.Source` (`forge` or `chat`) | Typed channel and SourceMessageReference; no closed source enum in WorkflowExecution |\n| Source address | `Owner`, `Repo`, `IssueNumber`; synthetic chat issue number | Channel-owned source reference with native message/thread/object identifiers; synthetic identifiers removed |\n| Requested work | `Title`, `Body`, `Labels` | Immutable execution input captured from the source request; channel-specific metadata retained in the source envelope |\n| Workflow selection | `Workflow` string | Immutable WorkflowID plus selected WorkflowVersion |\n| Lifecycle | `Status` string | Enforced WorkflowExecution state |\n| Current position | mutable `Stage` string | Derived current WorkflowStep reference plus durable StepExecution history |\n| Attempts | `Attempt`, `RetryCount` | Execution attempt history and retry-policy evidence; distinguish worker delivery retry from workflow retry |\n| Failure | `ParkReason`, transition detail, response errors | Typed failure classification, evidence, retryability, and resulting lifecycle event |\n| Human wait | `WatchCommentID`, `waiting_human` | Channel-neutral wait condition and correlation reference; forge comment IDs stay in the forge channel |\n| Workspace | `Dir`, `Branch`, worktree path, `task.json` | Execution workspace reference and independently managed workspace lifecycle |\n| Change outcome | `BuildSummary`, `BuildNoChanges`, changed files | Step outputs and final WorkflowExecution outcome |\n| Reproduction evidence | `ReproProof` | Typed TDD step evidence retained with the StepExecution and final outcome |\n| Planning output | `Plan` | Typed step output referenced by later steps rather than a special aggregate field |\n| Notes | `Notes`, appended agent notes | Ordered execution annotations with actor, source step, and timestamp |\n| Pull request | `PRNumber`, forge host/repository assumptions | Forge-channel delivery reference and reconciliation state |\n| Agent usage | `TokensUsed`, `Iterations` | StepExecution usage measurements aggregated into execution projections |\n| Decision capture | private feasibility `decision`, capture-tool output | Typed WorkflowStep output defined by that Workflow version |\n| Terminal outcome | mutable `Outcome{Status, Detail}` | Explicit WorkflowExecution outcome command/event validated by the state machine |\n| Skill context | `SkillBody`, `SkillPlugins` | Resolved Workflow version dependencies or execution inputs, with provenance |\n| Agent prompt context | `SystemPrompt`, `ExtraRules`, mission strings | Versioned WorkflowStep definition plus resolved execution context; mutable global prompt callbacks removed |\n| Gates and protection | `Gate`, `Preflight`, `Protection`, repository config | Agent System policy definitions resolved for the WorkflowExecution and enforced outside the agent |\n| Budgets | steps, tokens, wall clock, gate failures | Execution and StepExecution policy values with measured usage and evidence |\n| Tool access | capture tools, registry, guardrails, skill plugins | Resolved step capability set and policy; global registry pointers do not enter execution state |\n| Persistence timestamps | SQL `created_at` and `updated_at` | Domain timestamps and version used for optimistic concurrency and audit |\n| Transition history | SQL `transitions` and generic events | Authoritative WorkflowExecution domain events stored atomically with state |\n\n## Current runtime responsibilities to unify\n\nThe following behaviours currently act on the same WorkflowExecution but are\nimplemented in different packages:\n\n- accept a request from a channel and enforce idempotency;\n- select and version a Workflow;\n- create, queue, claim, schedule, and execute a WorkflowExecution;\n- serialize same-repository execution where policy requires it;\n- resolve identity-specific capabilities;\n- prepare, retain, recover, and clean up the workspace;\n- run deterministic and agent-backed WorkflowSteps;\n- enforce gates, budgets, protected paths, tool constraints, and result review;\n- persist state and StepExecution outputs;\n- publish authoritative lifecycle events;\n- wait for channel input and resume;\n- classify failure, retry, park, mark exhausted, cancel, or recover after crash;\n- deliver and reconcile forge changes;\n- project status, history, counts, and audit for channels and the web UI;\n- hand execution to a worker without moving domain ownership to the worker.\n\n## Current workflow-feature hazards\n\n- There is no enforced WorkflowExecution state machine. `Store.Transition`\n ignores the supplied `from` state when updating the row.\n- State update and transition-history insertion are separate operations, so\n state and audit can diverge.\n- Callers frequently discard persistence and transition errors.\n- Gateway task control duplicates lifecycle status constants by hand.\n- `workflow.TaskContext` is a mutable service bag containing complete\n configuration plus forge, store, worktree, agent, event bus, logging, memory,\n guardrails, skills, and scratch state.\n- Lifecycle changes occur in both daemon and workflow code.\n- Workflow orchestration runs inside task-scoped agent containers while the\n daemon retains lifecycle, admission, and authority-bearing RPC ownership.\n- Forge-backed and chat-created work share one record through source flags and\n synthetic issue numbers.\n- Repository labels currently select workflows and mirror task state, coupling\n domain transitions to forge presentation.\n- Failure generally becomes `parked`, but failure classification and\n retryability are not represented explicitly.\n- Generic observability events are emitted alongside state changes rather than\n being the authoritative domain events.\n\n## Existing invariants to preserve\n\n- The model never performs git operations directly.\n- Deterministic policy and gates cannot be waived by the agent.\n- TDD captures a failing reproduction before implementation and protects the\n test during the fix.\n- Every run ends in an explicit outcome; definition errors and stage errors do\n not disappear silently.\n- Crash recovery requeues interrupted work.\n- Agent execution crosses a versioned data boundary.\n- Forge, persistence, workspace, transport, container, and model runtimes remain\n replaceable infrastructure.\n- Work from the same repository is serialized by default.\n\n## Required migration\n\n- Rename the current persisted `store.Task` concept to WorkflowExecution.\n- Replace task lifecycle terminology in core commands, events, persistence,\n worker contracts, logs, and generated reference.\n- Preserve external source terminology only inside its channel adapter.\n- Replace synthetic issue numbers with explicit source-message references.\n- Associate every WorkflowExecution with an immutable Workflow identifier and\n version.\n- Record StepExecutions explicitly rather than treating one mutable `stage`\n field as complete execution history.\n- Keep Attempt as retry state within the same WorkflowExecution.\n\n## Curator isolation invariant\n\nDecided 2026-08-05\n([#435](https://github.com/samcharles93/archie-core/issues/435) epic,\n[#98](https://github.com/samcharles93/archie-core/issues/98) runtime).\nRecovered 2026-08-09 from the pre-migration issue tracker.\n\n**Curators are peers, not dependencies.** They must never block, delay, or take\ndown chat turns, agent runs, or the daemon.\n\n1. Registry-owned goroutines, one per curator, with per-pass `recover()`,\n per-pass budgets (max steps, tokens, timeout), and a configurable maximum of\n concurrent passes (default 1) so curators cannot saturate the shared LLM\n runtime against chat.\n2. Wake events ride the in-process `events.Bus`, which is mutex fan-out with\n bounded per-subscriber buffers that **drop** on overflow\n (`internal/events/events.go`). A slow curator can never backpressure the chat\n publisher.\n3. Wake is a best-effort nudge. The trigger is a deterministic read of persisted\n primary-input state at pass time, so a dropped wake only delays a run to the\n next check-in and never corrupts trigger accounting\n ([#22](https://github.com/samcharles93/archie-core/issues/22)).\n4. The curator registry lifecycle is independent of the agent loop. Daemon\n shutdown cancels in-flight passes and waits bounded.\n\nChat turns keep their per-session lanes; agent runs keep their workflow\ngoroutines and containers. Rule of thumb: **no code path a curator executes may\never appear on a chat turn's critical path.**\n" + "body": "# Agent System\n\n**Status:** Current-state investigation in progress \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Domain framing\n\nThe domain is the Agent System.\n\n`Task` is not a core Agent System concept. Forge tasks, forge issues, Jira\nissues, email, Telegram messages, webhooks, and future external inputs are\nchannel-specific messages. Channels translate those messages into requests to\nthe Agent System; external issue or task models MUST NOT shape execution state.\n\nThe current `store.Task` is a persisted workflow execution. Treating that row as\na task-domain aggregate would incorrectly turn Archie into an agentic issue\nboard.\n\n## Canonical agent interaction model\n\nAn **Agent** is a persistent assistant selected for an interaction. It is not a\nmodel invocation and is not a WorkflowExecution.\n\nEach Agent has its own:\n\n- immutable acting `IdentityID` for ownership and audit;\n- durable memory and learned information about the user;\n- perspective, specialisation, instructions, and communication behaviour;\n- conversation history and channel bindings;\n- available tools, capabilities, and policy;\n- continuity across model or provider changes.\n\nThe underlying model is a replaceable runtime dependency. Changing a model,\nprovider, or model version MUST NOT create a new Agent, discard its memory, or\nchange ownership of its history.\n\nA user MAY create multiple Agents. Each Agent develops its own memory and view\nof the user from the interactions and responsibilities assigned to it. Memories\nMUST NOT be silently pooled merely because Agents belong to the same user or\napplication.\n\nAgent and Identity are separate aggregates. Every Agent references exactly one\nacting IdentityID, and no two Agents share an agent identity. User, system, and\nservice-account identities may exist without an Agent.\n\nAn action initiated through an Agent records the Agent's acting IdentityID and,\nwhen applicable, the initiating user's IdentityID. A future fully automated\nWorkflowExecution MAY use an explicitly selected service-account identity for a\nconcrete unattended use case; this is not the default execution identity.\n\n## Workflow execution identity\n\nA Workflow is owned by an IdentityID. By default, every WorkflowExecution acts\nas the Workflow owner's identity.\n\nFuture delegated execution MAY add an explicit `RunAsIdentityID` assignment to a\nWorkflow. This allows a Workflow owner to select another user or service-account\nidentity for execution without changing Workflow ownership. Until that\ncapability is deliberately introduced, owner identity and execution identity are\nthe same.\n\nWorkflowExecution audit records MUST preserve the Workflow owner, effective\nexecution identity, initiating user when one exists, and any explicit delegation\nthat selected a different run-as identity.\n\n## Memory scopes\n\nThe Agent System requires four distinct durable memory scopes:\n\n- **global shared memory**: information intentionally available across the\n Archie application;\n- **agent-wide memory**: general expertise, operating knowledge, and perspective\n owned by one Agent and safe for that Agent to use across users;\n- **user-wide memory**: information associated with one user and available to\n authorized Agents serving that user;\n- **Agent-user relationship memory**: private history and learned context from\n one particular Agent's relationship with one particular user.\n\nAgent-wide memory is private to its owning Agent by default. Another Agent MUST\nNOT read, inherit, search, or mutate it implicitly.\n\nAgent-user relationship memory is addressed by both AgentID and User IdentityID.\nNeither another Agent serving the same user nor another user speaking to the\nsame Agent may access it implicitly.\n\nArchie is a multi-user system even when initially deployed for one person.\nMultiple users, including family members, may interact with the same configured\nAgents. Per-user memory is therefore an isolation and personalization boundary,\nnot merely an attribution tag on the primary user's records.\n\nAn Agent MUST resolve the initiating user before assembling memory context.\nMemory belonging to one user MUST NOT become visible to another user merely\nbecause both users interact with the same Agent.\n\nShared memory does not erase provenance. Every memory record retains its scope,\nauthor or acting identity, originating user when applicable, source, and\nrevision history. The rules for selecting a write scope, granting access\nto global and user-wide memory, and authorizing explicit cross-scope sharing are\nsettled by [`docs/prds/memory-engine-unification.md`](/dev/prds/memory-engine-unification/)\nand recorded in [`migration-decisions.md`](/dev/architecture/migration-decisions/#5-memory-placement-and-storage)\nsection 5.\n\nAn Agent interaction may answer conversationally, use a tool or capability, read\nor send messages, retain information, or propose durable workflow-backed work.\nNone of these operations inherently requires a WorkflowExecution.\n\n## Agent and Workflow domain boundary\n\nAgent and Workflow are separate domains:\n\n```text\ninternal/domain/agent\ninternal/domain/workflow\n```\n\nThe Agent domain owns persistent assistants, their specialisation, instructions,\nmodel-independent continuity, capability context, and associations with identity\nand memory.\n\nThe Workflow domain owns reusable, user- or Agent-defined behaviour and every\ndurable execution of that behaviour. An Agent may invoke or define a Workflow,\nbut the Workflow is not part of the Agent aggregate and does not require a\nconversational Agent interaction to execute.\n\n## Canonical workflow model\n\nThe Workflow feature uses these canonical terms:\n\n- **Workflow**: a reusable, versioned definition of how an agent behaves and\n performs a kind of work.\n- **WorkflowExecution**: one durable execution of a specific Workflow version.\n- **WorkflowStep**: one defined operation in a Workflow.\n- **StepExecution**: the recorded execution and outcome of one WorkflowStep.\n- **Attempt**: a retry of the same WorkflowExecution, not a new execution.\n\nA Workflow MAY structure any repeatable agent behaviour, including personal\nassistance and scheduled routines. For example, a morning email review may\ncombine a schedule event, message retrieval tool, LLM classification and\nsummarisation, and delivery of the resulting rundown. Workflow is therefore not\nrestricted to forge work, source changes, or requests submitted by a user at\nexecution time.\n\nWorkflows are extensible through Workflow-owned plugins. The Workflow domain\ndefines the typed plugin registration, definition, validation, versioning, and\nexecution contracts. Users and Agents may define reusable Workflows through\nthose contracts.\n\nThe generic plugin contract remains metadata-only. It MUST NOT own Workflow\nsemantics or replace the Workflow registry with generic hooks.\n\n`Workflow` and `WorkflowExecution` are the names used in architecture, generated\nreference, configuration, commands, events, and external contracts. The\nimplementation MAY use package qualification to remain concise:\n\n```go\nworkflow.Definition\nworkflow.Execution\nworkflow.Step\nworkflow.StepExecution\n```\n\nThe unqualified name `Execution` MUST NOT be used in cross-domain contracts or\ndocumentation because it is ambiguous among workflow, tool, command, policy, and\nservice execution.\n\n## Current workflow-execution feature\n\nThe current feature takes a channel request through agent execution and a\ndurable outcome.\n\nCurrent execution state includes source-message references, owning identity,\nrepository, selected workflow and stage, agent output, branch and pull-request\nreferences, token and iteration counts, retry information, human-wait\ninformation, and failure details.\n\nThe current `store.Task` lifecycle uses:\n\n```text\nqueued -\u003e running\nrunning -\u003e waiting_human | pr_open | merged | parked | closed_wont_do\nwaiting_human -\u003e queued | closed_wont_do\nparked -\u003e queued | dead\npr_open -\u003e merged | rejected\nrunning after crash -\u003e queued\n```\n\nWorkflows select and sequence deterministic and agent-run stages. Implement,\nTDD, feasibility, and bootstrap are current Workflow definitions.\nEvery WorkflowExecution is handed wholesale over core NATS to a task-scoped\n`archie-agent` container, which owns the workflow stage loop.\n\n## Current workflow-feature placement\n\nThe behaviour is divided across technical packages:\n\n- `internal/domain/workflow` defines the current `Task` execution record and\n status strings; `internal/infrastructure/postgres` persists mutable state\n and transition history behind `internal/domain/storecontract`.\n- `internal/daemon` discovers, claims, schedules, retries, recovers, processes,\n waits for human input, and reconciles pull requests.\n- `internal/domain/workflow` routes work, executes stages, mutates tasks, applies\n outcomes, parks failures, and performs forge/worktree operations.\n- `internal/agentexec` defines and runs individual autonomous-stage protocols.\n- `internal/taskrun` hands a complete WorkflowExecution to a container worker.\n- `internal/gate` and repository configuration define execution constraints.\n- `internal/gateway` duplicates task status strings and applies task-control\n rules.\n- forge, worktree, NATS, PostgreSQL, containers, and agent runtimes are concrete\n dependencies mixed into orchestration.\n\n## Current `task` meanings and required replacements\n\nThe existing code uses `task` for unrelated concepts. Migration MUST resolve\neach meaning deliberately; a global text replacement is prohibited.\n\n| Current meaning | Representative locations | Target concept | Requirements |\n| -------------------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Forge issue or external task | `internal/forge`, daemon polling | Channel message | Preserve the channel's native reference and payload. Translate it into an Agent System request without importing forge or issue semantics into Workflow. |\n| Jira issue or other external work item | Messaging infrastructure adapter | Channel message or external artifact | The external system retains its own vocabulary inside its integration. Its record may lead to an accepted work request but is not a Workflow or WorkflowExecution. |\n| Persisted `workflow.Task` row | `internal/infrastructure/postgres` | WorkflowExecution | Own identity, Workflow ID and version, lifecycle, source-message reference, outputs, attempts, and outcome. Persistence implements the Agent System repository contract. |\n| Task status and transition history | `store.Status*`, `transitions` | WorkflowExecution lifecycle and domain events | Enforce legal transitions atomically. Domain events and state changes cannot diverge. Remove duplicated status strings from consumers. |\n| Claimed or queued task | `ClaimNext`, `ClaimByIssue`, `RecoverStale` | Scheduled WorkflowExecution | Claim by WorkflowExecution ID and expected version/state. Crash recovery and leases must not silently create a new execution. |\n| `workflow.TaskContext` | `internal/domain/workflow` | WorkflowExecution context | Replace the mutable service bag with execution state plus narrow step-required contracts. Complete application configuration and unrelated services are forbidden. |\n| `taskrun.Request` and `taskrun.Response` | `internal/taskrun`; consumed by `internal/app/agentworker`, decoded by `internal/infrastructure/agenttransport/nats` | WorkflowExecution handoff | This is the versioned worker contract for executing a WorkflowExecution. It carries domain-owned execution data, not store rows or global configuration DTOs. |\n| Per-stage `agentexec.Request.TaskID` | `internal/agentexec` | WorkflowExecutionID correlation | An agent invocation is a bounded WorkflowStep execution. Correlate request/result with WorkflowExecutionID, StepExecutionID, attempt, and protocol version. |\n| NATS `TaskMessage` and `archie.task.*` | `internal/domain/workintake` (subjects, `TaskEnvelope`); `internal/infrastructure/agenttransport/nats` (transport) -- `internal/nats` no longer exists; whether this row's \"current meaning\" itself is now superseded by `TaskEnvelope` needs a closer look, not asserted here | Channel request or WorkflowExecution transport | Discovery messages and execution dispatch are different contracts and subjects. Domain meaning stays outside NATS infrastructure. Identity and source-message idempotency must be explicit. |\n| `taskDispatcher` work item | `internal/daemon` | WorkflowExecution scheduling | Scheduling operates on execution references and declared concurrency policy. Repository serialization is policy, not identity derived from an incomplete task struct. |\n| `container.TaskPayload` and `task.json` | `internal/container`; read by `internal/infrastructure/agentboot` | WorkflowExecution brief | Rename the boot artifact and schema. It identifies the mounted execution and required workspace only; it is not an alternative execution definition. Missing or malformed input must fail startup before the worker subscribes. |\n| `storage.TaskRef` | `internal/storage` | WorkflowExecution workspace lease | Storage receives the minimal execution/workspace reference and policy required to provision and release resources. It does not receive the WorkflowExecution aggregate. |\n| Gateway `TaskCreator` | `internal/gateway` | Accepted work request handoff | A channel may carry a request for durable workflow-backed work, but it does not request or create a WorkflowExecution directly. Work intake admits and routes the request; the Agent System consumes the accepted work request and is the sole owner of selecting a Workflow version and creating the WorkflowExecution. Ordinary agent interactions do not require this handoff. |\n| Gateway `TaskController` and `ChatTaskStatus` | `internal/gateway/tasks.go` | WorkflowExecution commands and query view | Approve, cancel, and status use Agent System contracts. Channel code does not duplicate lifecycle constants or decide transitions. |\n| Gateway `TaskProfile` | `internal/gateway/tasks.go`, `cmd/archied` | Channel/identity execution defaults | This is configuration selecting allowed source targets and default Workflow inputs, not task state. Split it into settings owned by the relevant channel and Agent System features. |\n| `config.TaskConfig` and `TaskForge` | `internal/config` | Worker execution settings and channel/service references | Dissolve with `internal/config`. Each field moves to its owning runtime settings or versioned WorkflowExecution handoff contract. Secrets and external configuration forms do not enter the domain. |\n| `events.Event.TaskID`, task event timelines | `internal/events`, stores, web UI | WorkflowExecutionID and WorkflowExecution events | Authoritative events are Agent System events. Observability and timelines project those events rather than inventing parallel generic task events. |\n| Web UI task lists and counts | `internal/webui`, store query APIs | WorkflowExecution read model | Dashboard status, history, and counts are projections of WorkflowExecution state and events. The UI does not depend on persistence records. |\n| Task-scoped forge/store/worktree RPC | `forgerpc`, `storerpc`, `worktreerpc`, `registerTaskRPCServers` | Execution-scoped capability ports | Worker calls use narrow domain-required service contracts, carry WorkflowExecutionID and IdentityID, and resolve the owning capability binding. Root-client fallback is forbidden. |\n| Per-task worktree, branch, volume, and cleanup | daemon, worktree, storage, container | WorkflowExecution workspace | Every WorkflowExecution receives isolated workspace state. Workspace lifecycle is explicit, identity-aware, recoverable, and controlled outside the model. |\n| Task retry, dead, waiting-human, PR reconciliation | daemon, workflow, gateway | WorkflowExecution lifecycle policies | Retry, waiting, cancellation, reconciliation, and terminal outcomes are Agent System behaviour. Channels and infrastructure report facts or submit commands; they do not mutate state. |\n| Task-run readiness and retry timeouts | daemon taskrun request loop | Worker-dispatch settings and policy | These settings govern WorkflowExecution handoff availability. They are not Workflow data and must be owned by the worker-dispatch capability. |\n\n### Terms that do not migrate\n\n- The `task` command in `Taskfile.yml` is the external Task build tool and keeps\n its name.\n- A forge may call its own records issues or tasks inside its channel adapter.\n- General prose may use “task” informally only when it clearly refers to an\n external system. Agent System contracts and generated reference MUST use the\n canonical Workflow vocabulary.\n\n## Current WorkflowExecution data inventory\n\nThis inventory is the migration ledger for data currently spread across\n`store.Task`, database-only columns, `workflow.TaskContext`, worker messages,\nand surrounding configuration. Implementation SHOULD NOT require another\nrepository-wide search to determine what existing execution data must be\npreserved or deliberately removed.\n\n| Current data | Current representation | Required target |\n| ---------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |\n| Execution identity | `Task.ID`, `task_id`, NATS subjects, logs | Immutable WorkflowExecutionID used consistently by state, events, workers, projections, and capability calls |\n| Owning actor | `Task.Identity` string | Canonical IdentityID |\n| Source type | `Task.Source` (`forge` or `chat`) | Typed channel and SourceMessageReference; no closed source enum in WorkflowExecution |\n| Source address | `Owner`, `Repo`, `IssueNumber`; synthetic chat issue number | Channel-owned source reference with native message/thread/object identifiers; synthetic identifiers removed |\n| Requested work | `Title`, `Body`, `Labels` | Immutable execution input captured from the source request; channel-specific metadata retained in the source envelope |\n| Workflow selection | `Workflow` string | Immutable WorkflowID plus selected WorkflowVersion |\n| Lifecycle | `Status` string | Enforced WorkflowExecution state |\n| Current position | mutable `Stage` string | Derived current WorkflowStep reference plus durable StepExecution history |\n| Attempts | `Attempt`, `RetryCount` | Execution attempt history and retry-policy evidence; distinguish worker delivery retry from workflow retry |\n| Failure | `ParkReason`, transition detail, response errors | Typed failure classification, evidence, retryability, and resulting lifecycle event |\n| Human wait | `WatchCommentID`, `waiting_human` | Channel-neutral wait condition and correlation reference; forge comment IDs stay in the forge channel |\n| Workspace | `Dir`, `Branch`, worktree path, `task.json` | Execution workspace reference and independently managed workspace lifecycle |\n| Change outcome | `BuildSummary`, `BuildNoChanges`, changed files | Step outputs and final WorkflowExecution outcome |\n| Reproduction evidence | `ReproProof` | Typed TDD step evidence retained with the StepExecution and final outcome |\n| Planning output | `Plan` | Typed step output referenced by later steps rather than a special aggregate field |\n| Notes | `Notes`, appended agent notes | Ordered execution annotations with actor, source step, and timestamp |\n| Pull request | `PRNumber`, forge host/repository assumptions | Forge-channel delivery reference and reconciliation state |\n| Agent usage | `TokensUsed`, `Iterations` | StepExecution usage measurements aggregated into execution projections |\n| Decision capture | private feasibility `decision`, capture-tool output | Typed WorkflowStep output defined by that Workflow version |\n| Terminal outcome | mutable `Outcome{Status, Detail}` | Explicit WorkflowExecution outcome command/event validated by the state machine |\n| Skill context | `SkillBody`, `SkillPlugins` | Resolved Workflow version dependencies or execution inputs, with provenance |\n| Agent prompt context | `SystemPrompt`, `ExtraRules`, mission strings | Versioned WorkflowStep definition plus resolved execution context; mutable global prompt callbacks removed |\n| Gates and protection | `Gate`, `Preflight`, `Protection`, repository config | Agent System policy definitions resolved for the WorkflowExecution and enforced outside the agent |\n| Budgets | steps, tokens, wall clock, gate failures | Execution and StepExecution policy values with measured usage and evidence |\n| Tool access | capture tools, registry, guardrails, skill plugins | Resolved step capability set and policy; global registry pointers do not enter execution state |\n| Persistence timestamps | SQL `created_at` and `updated_at` | Domain timestamps and version used for optimistic concurrency and audit |\n| Transition history | SQL `transitions` and generic events | Authoritative WorkflowExecution domain events stored atomically with state |\n\n## Current runtime responsibilities to unify\n\nThe following behaviours currently act on the same WorkflowExecution but are\nimplemented in different packages:\n\n- accept a request from a channel and enforce idempotency;\n- select and version a Workflow;\n- create, queue, claim, schedule, and execute a WorkflowExecution;\n- serialize same-repository execution where policy requires it;\n- resolve identity-specific capabilities;\n- prepare, retain, recover, and clean up the workspace;\n- run deterministic and agent-backed WorkflowSteps;\n- enforce gates, budgets, protected paths, tool constraints, and result review;\n- persist state and StepExecution outputs;\n- publish authoritative lifecycle events;\n- wait for channel input and resume;\n- classify failure, retry, park, mark exhausted, cancel, or recover after crash;\n- deliver and reconcile forge changes;\n- project status, history, counts, and audit for channels and the web UI;\n- hand execution to a worker without moving domain ownership to the worker.\n\n## Current workflow-feature hazards\n\n- There is no enforced WorkflowExecution state machine. `Store.Transition`\n ignores the supplied `from` state when updating the row.\n- State update and transition-history insertion are separate operations, so\n state and audit can diverge.\n- Callers frequently discard persistence and transition errors.\n- Gateway task control duplicates lifecycle status constants by hand.\n- `workflow.TaskContext` is a mutable service bag containing complete\n configuration plus forge, store, worktree, agent, event bus, logging, memory,\n guardrails, skills, and scratch state.\n- Lifecycle changes occur in both daemon and workflow code.\n- Workflow orchestration runs inside task-scoped agent containers while the\n daemon retains lifecycle, admission, and authority-bearing RPC ownership.\n- Forge-backed and chat-created work share one record through source flags and\n synthetic issue numbers.\n- Repository labels currently select workflows and mirror task state, coupling\n domain transitions to forge presentation.\n- Failure generally becomes `parked`, but failure classification and\n retryability are not represented explicitly.\n- Generic observability events are emitted alongside state changes rather than\n being the authoritative domain events.\n\n## Existing invariants to preserve\n\n- The model never performs git operations directly.\n- Deterministic policy and gates cannot be waived by the agent.\n- TDD captures a failing reproduction before implementation and protects the\n test during the fix.\n- Every run ends in an explicit outcome; definition errors and stage errors do\n not disappear silently.\n- Crash recovery requeues interrupted work.\n- Agent execution crosses a versioned data boundary.\n- Forge, persistence, workspace, transport, container, and model runtimes remain\n replaceable infrastructure.\n- Work from the same repository is serialized by default.\n\n## Required migration\n\n- Rename the current persisted `store.Task` concept to WorkflowExecution.\n- Replace task lifecycle terminology in core commands, events, persistence,\n worker contracts, logs, and generated reference.\n- Preserve external source terminology only inside its channel adapter.\n- Replace synthetic issue numbers with explicit source-message references.\n- Associate every WorkflowExecution with an immutable Workflow identifier and\n version.\n- Record StepExecutions explicitly rather than treating one mutable `stage`\n field as complete execution history.\n- Keep Attempt as retry state within the same WorkflowExecution.\n\n## Curator isolation invariant\n\nDecided 2026-08-05\n([#435](https://github.com/samcharles93/archie-core/issues/435) epic,\n[#98](https://github.com/samcharles93/archie-core/issues/98) runtime).\nRecovered 2026-08-09 from the pre-migration issue tracker.\n\n**Curators are peers, not dependencies.** They must never block, delay, or take\ndown chat turns, agent runs, or the daemon.\n\n1. Registry-owned goroutines, one per curator, with per-pass `recover()`,\n per-pass budgets (max steps, tokens, timeout), and a configurable maximum of\n concurrent passes (default 1) so curators cannot saturate the shared LLM\n runtime against chat.\n2. Wake events ride the in-process `events.Bus`, which is mutex fan-out with\n bounded per-subscriber buffers that **drop** on overflow\n (`internal/events/events.go`). A slow curator can never backpressure the chat\n publisher.\n3. Wake is a best-effort nudge. The trigger is a deterministic read of persisted\n primary-input state at pass time, so a dropped wake only delays a run to the\n next check-in and never corrupts trigger accounting\n ([#22](https://github.com/samcharles93/archie-core/issues/22)).\n4. The curator registry lifecycle is independent of the agent loop. Daemon\n shutdown cancels in-flight passes and waits bounded.\n\nChat turns keep their per-session lanes; agent runs keep their workflow\ngoroutines and containers. Rule of thumb: **no code path a curator executes may\never appear on a chat turn's critical path.**\n" }, { "url": "/dev/architecture/bindings/", "title": "Playbook bindings: model and threat model", "section": "Architecture", - "body": "# Playbook bindings: model and threat model\n\n**Status:** Approved foundation (documents shipped code: `archie-core-t2db.1`\nthrough `.5`, `.7`, `.9`-`.15`)\n**Date:** 2026-09-03\n\nThis document covers the binding model and the intake threat model portion\nof `archie-core-t2db.6`. It does not cover the task-lifecycle provenance rule\n(`messaging-and-work-intake.md`'s \"Intake provenance\") or the operator\nwalkthrough -- that walkthrough remains an open piece of the same ticket.\n\n## What a binding is\n\nA `binding` (`internal/domain/binding.Binding`) ties four things together:\na **matcher** (which captured events it applies to), a **mapping**\n(`internal/domain/mapping.Mapping`, how fields are pulled out of a payload),\na **workflow** (which registered workflow runs on a match), and a **state\nmachine** governing whether it is live.\n\n```go\ntype Binding struct {\n ID, Name // identity\n Matcher // { Source string } -- the webhook path segment, e.g. \"sentry\"\n MappingID // which Mapping resolves payload fields\n Workflow // registered workflow name to dispatch to\n Version // bumped on every edit\n Status // pending_approval | armed\n Secret // HMAC-SHA256 shared secret, encrypted at rest, never returned by GET\n}\n```\n\nBindings live in the store (SQLite), not `config.toml` -- operators author\nthem from the dashboard while the daemon runs, without a restart.\n\n### Matching\n\n`Matcher.Source` is the only predicate today: the path segment a sender\nPOSTs to (e.g. a webhook hitting `.../sentry` matches bindings with\n`Matcher.Source == \"sentry\"`). The storage column is plain `TEXT`, so adding\npredicates later is non-breaking -- extend `Matcher`, don't invent a second\nmatcher shape.\n\n### Mapping\n\n`mapping.Resolve(fields, payload)` walks a captured JSON payload against a\nlist of typed `Field`s (name, JSON path, expected type), returning resolved\nvalues plus a `[]Failure` for anything that didn't parse or type-match. This\nis schema-by-example in practice: a mapping is authored by pointing at a\nreal captured payload in the dashboard, not by guessing a schema in advance.\n\n### Versioning\n\n`Version` increments on every `UpdateBinding` call. This exists so an\neditor's later change can never silently rewrite the historical provenance\nof a task that already fired -- a dispatched task's binding reference is\npinned to the version that was armed when it fired, not \"whatever the\nbinding currently says.\"\n\n### State machine\n\n```\ncreate ---\u003e pending_approval ---\u003e armed\n ^ |\n +----------------+\n (any edit to an armed binding drops it back to pending_approval)\n```\n\nA binding is created `pending_approval`, so the operator who creates one can\napprove it immediately. Bindings stored as `draft` by an earlier version are\nmoved to `pending_approval` when the EDA store opens.\n\nModeled directly on Telegram's existing `dangerousAction`/`pendingApproval`\nflow (`internal/channels/telegram/dangerous.go`, `approval.go`) -- not a new\napproval mechanism invented for this feature. **Only `armed` evaluates\nagainst incoming events** (`binding.Matches`, `internal/domain/binding/\nbinding.go`); a `pending_approval` binding is inert. An edit to\nan already-armed binding cannot bypass approval by silent mutation -- it\ndrops back to `pending_approval` and requires an explicit `Approve` call to\nre-arm.\n\n## The threat model\n\nThis is a public, unauthenticated-by-default intake surface whose output is\nan agent with a repo, a worktree, and tool access. The design brief\n(`archie-core-t2db.5`, `docs/prds/webhook-intake-security.md`) named five\nnon-negotiables; each is verified below against the actual shipped code,\nnot the design intent.\n\n### 1. Per-source authentication\n\nReuses `internal/channels/webhook`'s existing HMAC-SHA256 scheme --\ncapture accepts unsigned events (visible in the dashboard, marked\nunauthenticated), but **only authenticated events can ever match a\nbinding**. `binding.Matches`' doc comment states this plainly: \"an\nunauthenticated event can never trigger a binding, no matter how well it\nwould otherwise match.\" Enforced structurally at two points, not just\nconvention:\n\n- `captured_events.authenticated` is a real column (`internal/store/\n captures.go`), set at capture time.\n- `dispatchBindings` (`internal/daemon/daemon.go:479`) walks **authenticated\n captures whose source has at least one armed binding** -- an\n unauthenticated capture is never even considered for dispatch.\n\n### 2. Human approval before a binding goes live\n\nCovered by the state machine above. Nothing self-arms: `pending_approval -\u003e\narmed` requires an explicit `Approve` call, and any edit to an armed\nbinding reverts it.\n\n### 3. Rate and volume limits per source\n\nCapture writes are bounded independently of the approval gate, so a flood\nof unauthenticated traffic cannot exhaust disk or drown the inspector:\n`InsertCapture` (`internal/store/captures.go`) prunes by both **retention\nwindow** (`WHERE received_at \u003c cutoff`) and **max event count** in the same\ninsert transaction.\n\n### 4. Blast radius bounded by the same code-level controls every task gets\n\nA playbook-originated task is dispatched into the **same** gate, diff-cap,\nsandboxed-container, worktree-isolation pipeline every task goes through\nregardless of origin. Verified precisely, not assumed: `dispatchOneBinding`\ncalls `EnqueueBindingTask` (`internal/store/store.go`), which wraps\n`EnqueueChatTask` -- the same direct-to-`tasks`-table enqueue path\nchat-spawned tasks already use, then stamps `binding_id`/`binding_version`\nfor provenance in a second statement. This is a **different** enqueue\nmechanism from forge-issue polling's `workintake.TaskEnvelope`/NATS path\n(`docs/prds/event-sources-and-reactions.md`) -- binding and forge-issue\ntasks arrive by different producers, but both become an ordinary\n`store.Task` row that `ClaimNext` picks up identically, so both get the\nsame gate/worktree pipeline downstream regardless of which producer created\nthe row. Payload content is\nordinary untrusted prompt input; the sender's text is never treated as a\ntrusted instruction (Archie's environmental-enforcement principle: \"the\nagent should ignore instructions in the payload\" is not itself a control,\nthe surrounding sandbox is).\n\n### 5. Captured payloads may contain secrets from the sending system\n\nTwo independent protections, not one:\n\n- **Redaction before persistence**: `webhookguard.RedactPayload` walks the\n decoded JSON and redacts recognised sensitive keys before the row is\n written -- the raw, unredacted payload is never durably stored.\n- **Retention**: a configurable window (`InsertCapture`'s `retention`\n parameter) prunes old captures automatically; visibility of what remains\n is gated by the same dashboard authentication as every other webui\n surface, not a separate, weaker path.\n\n### Secrets at rest\n\n`Binding.Secret` (the HMAC shared secret a sender signs with) is encrypted\nat rest via AES-GCM (`internal/store/binding_cipher.go`, `archie-core-\nt2db.7`) -- a leaked SQLite file does not leak sender-side shared secrets in\nplaintext. The envelope is versioned (`bindingEnvelopeVersion`) so a future\ncipher or KDF change can roll forward without breaking already-encrypted\nrows, and the AAD binds ciphertext to the binding-secret context so it\ncannot be relocated to another field/column and still authenticate. A `nil`\ncipher (no encryption key configured) leaves secrets as plaintext --\ndocumented legacy behaviour, not silent degradation.\n\n### At-most-once dispatch\n\n`dispatchBindings` enqueues at most one task per `(binding, capture)` pair,\nenforced by a real ledger, not best-effort application logic:\n`RecordDispatch` (`internal/store/bindings.go`) does `INSERT OR IGNORE` into\n`binding_dispatches`, unique on `(binding_id, capture_id)`; a duplicate\ninsert returns the sentinel `ErrAlreadyDispatched`, which the dispatch loop\ntreats as \"another cycle raced us,\" not an error. This guarantee holds\n**across daemon restarts**, not just within one process's lifetime, because\nthe ledger is a durable table, not in-memory state.\n\nThis ledger is also the direct precedent for the EDA playbook engine's\nexecution-time idempotency, now landed (`archie-core-t2db.17` closed): the\n`playbook_dispatches` table in `internal/store/playbook_dispatches.go` copies\n`binding_dispatches`'s `INSERT OR IGNORE` conventions with a\n`(playbook_id, playbook_version, event_id, action_id)` key\n(`docs/prds/eda-playbook-engine.md` gap 2).\n\n## What this document does not cover\n\n- An end-to-end operator walkthrough (point an external app at archie,\n build a first playbook) -- open, part of `archie-core-t2db.6`.\n- The playbook YAML / CEL / Module/Channel/Forge action-position work\n (`docs/prds/eda-playbook-engine.md`, `module-position.md`,\n `channel-forge-positions.md`) -- a different, newer mechanism than the\n binding model described here; the two are related but not the same\n system, and this document does not attempt to unify them.\n" + "body": "# Playbook bindings: model and threat model\n\n**Status:** Approved foundation (documents shipped code: `archie-core-t2db.1`\nthrough `.5`, `.7`, `.9`-`.15`)\n**Date:** 2026-09-03\n\nThis document covers the binding model and the intake threat model portion\nof `archie-core-t2db.6`. It does not cover the task-lifecycle provenance rule\n(`messaging-and-work-intake.md`'s \"Intake provenance\") or the operator\nwalkthrough -- that walkthrough remains an open piece of the same ticket.\n\n## What a binding is\n\nA `binding` (`internal/domain/binding.Binding`) ties four things together:\na **matcher** (which captured events it applies to), a **mapping**\n(`internal/domain/mapping.Mapping`, how fields are pulled out of a payload),\na **workflow** (which registered workflow runs on a match), and a **state\nmachine** governing whether it is live.\n\n```go\ntype Binding struct {\n ID, Name // identity\n Matcher // { Source string } -- the webhook path segment, e.g. \"sentry\"\n MappingID // which Mapping resolves payload fields\n Workflow // registered workflow name to dispatch to\n Version // bumped on every edit\n Status // pending_approval | armed\n Secret // HMAC-SHA256 shared secret, encrypted at rest, never returned by GET\n}\n```\n\nBindings live in the store (PostgreSQL), not `config.toml` -- operators author\nthem from the dashboard while the daemon runs, without a restart.\n\n### Matching\n\n`Matcher.Source` is the only predicate today: the path segment a sender\nPOSTs to (e.g. a webhook hitting `.../sentry` matches bindings with\n`Matcher.Source == \"sentry\"`). The storage column is plain `TEXT`, so adding\npredicates later is non-breaking -- extend `Matcher`, don't invent a second\nmatcher shape.\n\n### Mapping\n\n`mapping.Resolve(fields, payload)` walks a captured JSON payload against a\nlist of typed `Field`s (name, JSON path, expected type), returning resolved\nvalues plus a `[]Failure` for anything that didn't parse or type-match. This\nis schema-by-example in practice: a mapping is authored by pointing at a\nreal captured payload in the dashboard, not by guessing a schema in advance.\n\n### Versioning\n\n`Version` increments on every `UpdateBinding` call. This exists so an\neditor's later change can never silently rewrite the historical provenance\nof a task that already fired -- a dispatched task's binding reference is\npinned to the version that was armed when it fired, not \"whatever the\nbinding currently says.\"\n\n### State machine\n\n```\ncreate ---\u003e pending_approval ---\u003e armed\n ^ |\n +----------------+\n (any edit to an armed binding drops it back to pending_approval)\n```\n\nA binding is created `pending_approval`, so the operator who creates one can\napprove it immediately. Bindings stored as `draft` by an earlier version are\nmoved to `pending_approval` when the EDA store opens.\n\nModeled directly on Telegram's existing `dangerousAction`/`pendingApproval`\nflow (`internal/channels/telegram/dangerous.go`, `approval.go`) -- not a new\napproval mechanism invented for this feature. **Only `armed` evaluates\nagainst incoming events** (`binding.Matches`, `internal/domain/binding/\nbinding.go`); a `pending_approval` binding is inert. An edit to\nan already-armed binding cannot bypass approval by silent mutation -- it\ndrops back to `pending_approval` and requires an explicit `Approve` call to\nre-arm.\n\n## The threat model\n\nThis is a public, unauthenticated-by-default intake surface whose output is\nan agent with a repo, a worktree, and tool access. The design brief\n(`archie-core-t2db.5`, `docs/prds/webhook-intake-security.md`) named five\nnon-negotiables; each is verified below against the actual shipped code,\nnot the design intent.\n\n### 1. Per-source authentication\n\nReuses `internal/channels/webhook`'s existing HMAC-SHA256 scheme --\ncapture accepts unsigned events (visible in the dashboard, marked\nunauthenticated), but **only authenticated events can ever match a\nbinding**. `binding.Matches`' doc comment states this plainly: \"an\nunauthenticated event can never trigger a binding, no matter how well it\nwould otherwise match.\" Enforced structurally at two points, not just\nconvention:\n\n- `captures.authenticated` is a real column\n (`internal/infrastructure/postgres/migrations/0002_edastore.sql`), set at\n capture time.\n- `dispatchBindings` (`internal/daemon/daemon.go:479`) walks **authenticated\n captures whose source has at least one armed binding** -- an\n unauthenticated capture is never even considered for dispatch.\n\n### 2. Human approval before a binding goes live\n\nCovered by the state machine above. Nothing self-arms: `pending_approval -\u003e\narmed` requires an explicit `Approve` call, and any edit to an armed\nbinding reverts it.\n\n### 3. Rate and volume limits per source\n\nCapture writes are bounded independently of the approval gate, so a flood\nof unauthenticated traffic cannot exhaust disk or drown the inspector:\n`InsertCapture` (`internal/infrastructure/postgres/edastore.go`) prunes by both **retention\nwindow** (`WHERE received_at \u003c cutoff`) and **max event count** in the same\ninsert transaction.\n\n### 4. Blast radius bounded by the same code-level controls every task gets\n\nA playbook-originated task is dispatched into the **same** gate, diff-cap,\nsandboxed-container, worktree-isolation pipeline every task goes through\nregardless of origin. Verified precisely, not assumed: `dispatchOneBinding`\ncalls `EnqueueBindingTask` (`internal/infrastructure/postgres/store.go`), which wraps\n`EnqueueChatTask` -- the same direct-to-`tasks`-table enqueue path\nchat-spawned tasks already use, then stamps `binding_id`/`binding_version`\nfor provenance in a second statement. This is a **different** enqueue\nmechanism from forge-issue polling's `workintake.TaskEnvelope`/NATS path\n(`docs/prds/event-sources-and-reactions.md`) -- binding and forge-issue\ntasks arrive by different producers, but both become an ordinary\n`workflow.Task` row that `ClaimNext` picks up identically, so both get the\nsame gate/worktree pipeline downstream regardless of which producer created\nthe row. Payload content is\nordinary untrusted prompt input; the sender's text is never treated as a\ntrusted instruction (Archie's environmental-enforcement principle: \"the\nagent should ignore instructions in the payload\" is not itself a control,\nthe surrounding sandbox is).\n\n### 5. Captured payloads may contain secrets from the sending system\n\nTwo independent protections, not one:\n\n- **Redaction before persistence**: `webhookguard.RedactPayload` walks the\n decoded JSON and redacts recognised sensitive keys before the row is\n written -- the raw, unredacted payload is never durably stored.\n- **Retention**: a configurable window (`InsertCapture`'s `retention`\n parameter) prunes old captures automatically; visibility of what remains\n is gated by the same dashboard authentication as every other webui\n surface, not a separate, weaker path.\n\n### Secrets at rest\n\n`Binding.Secret` (the HMAC shared secret a sender signs with) is encrypted\nat rest via AES-GCM (`internal/infrastructure/bindingcipher`, `archie-core-\nt2db.7`) -- a leaked database dump does not leak sender-side shared secrets in\nplaintext. The envelope is versioned (`bindingEnvelopeVersion`) so a future\ncipher or KDF change can roll forward without breaking already-encrypted\nrows, and the AAD binds ciphertext to the binding-secret context so it\ncannot be relocated to another field/column and still authenticate. A `nil`\ncipher (no encryption key configured) leaves secrets as plaintext --\ndocumented legacy behaviour, not silent degradation.\n\n### At-most-once dispatch\n\n`dispatchBindings` enqueues at most one task per `(binding, capture)` pair,\nenforced by a real ledger, not best-effort application logic:\n`RecordDispatch` (`internal/infrastructure/postgres/edastore.go`) inserts into\n`binding_dispatches`, unique on `(binding, capture)`; a duplicate\ninsert returns the sentinel `ErrAlreadyDispatched`, which the dispatch loop\ntreats as \"another cycle raced us,\" not an error. This guarantee holds\n**across daemon restarts**, not just within one process's lifetime, because\nthe ledger is a durable table, not in-memory state.\n\nThis ledger is also the direct precedent for the EDA playbook engine's\nexecution-time idempotency, now landed (`archie-core-t2db.17` closed): the\n`playbook_dispatches` table (`RecordPlaybookDispatch`) copies\n`binding_dispatches`'s unique-ledger conventions with a\n`(playbook_id, playbook_version, event_id, action_id)` key\n(`docs/prds/eda-playbook-engine.md` gap 2).\n\n## What this document does not cover\n\n- An end-to-end operator walkthrough (point an external app at archie,\n build a first playbook) -- open, part of `archie-core-t2db.6`.\n- The playbook YAML / CEL / Module/Channel/Forge action-position work\n (`docs/prds/eda-playbook-engine.md`, `module-position.md`,\n `channel-forge-positions.md`) -- a different, newer mechanism than the\n binding model described here; the two are related but not the same\n system, and this document does not attempt to unify them.\n" }, { "url": "/dev/architecture/configuration/", "title": "Configuration", "section": "Architecture", - "body": "# Configuration\n\n**Status:** Approved; existing-type assignment is ongoing \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Ownership\n\nConfiguration has two separate responsibilities:\n\n1. `internal/infrastructure/configuration` loads files, environment variables,\n secret references, overlays, and compatibility representations.\n2. Each domain and plugin owns the typed runtime settings required for its\n behaviour.\n\n`internal/app` translates external input into those settings, validates\ncross-capability combinations, and supplies each component only its own\nsettings.\n\nThe following are prohibited:\n\n- passing complete application configuration into a domain;\n- making a domain depend on TOML, YAML, environment-variable names, secret\n references, or a configuration library;\n- defining a central runtime configuration type imported across the system;\n- placing plugin options in an unrelated global configuration model.\n\n## Private input document\n\n`internal/infrastructure/configuration` MAY use a complete decoded document\nwhile discovering files, decoding sections, and applying overlays. It is an\ninput-boundary DTO only.\n\nThe document:\n\n- remains private to the configuration infrastructure;\n- is composed from separately defined feature sections;\n- is immediately translated by application composition;\n- is never returned as the application's runtime model;\n- is never passed through runtime components.\n\nExternal DTOs and domain runtime settings are separate types.\n\nPlugins supply external configuration definitions through a narrow extension\ncontract. The core loader MUST NOT gain a field or recognized filename for every\nplugin.\n\nInvalid configuration input MUST NOT replace active valid settings or terminate\nunaffected capabilities. Configuration changes use the candidate validation,\npromotion, audit, and recovery requirements in\n[safe-change-and-recovery.md](/dev/architecture/safe-change-and-recovery/).\n\n## Dissolution of `internal/config`\n\n`internal/config` has no target location. It MUST be dissolved and MUST NOT\nsurvive as a shared package, configuration domain, or renamed global model.\n\nIts loading behaviour moves to `internal/infrastructure/configuration`. Existing\ntypes and methods are reassigned by behaviour. Repository execution policy,\ndispatch policy, retry policy, ecosystem defaults, tool policy, memory settings,\nprovider settings, and channel settings move to their\nrespective owners.\n\n## Repository settings\n\nThe existing `config.Repo` MUST NOT move intact into a repository domain or\nshared settings package. A managed repository is an application association:\n\n- work intake owns which repository references an identity monitors;\n- task execution owns gates, preflight, test protection, ecosystem behaviour,\n and change limits;\n- task lifecycle owns retry behaviour;\n- scheduling owns concurrency policy;\n- workspace management owns base branch and persistent-storage requirements.\n\nApplication composition correlates these settings by repository reference. No\ndomain receives a universal repository profile.\n\n## Documentation\n\nGenerated configuration reference describes external sections and their owning\ncapabilities. It MUST NOT establish a global Go configuration structure as the\npublic contract.\n\n## Value classification rule\n\nEvery value that controls behaviour MUST have an explicit owner and MUST be\nclassified as exactly one of:\n\n1. **Invariant** — changing it changes the meaning of the program, a wire\n protocol, or a domain concept. It may be a Go constant.\n2. **Runtime setting** — an operator, identity, domain, plugin, or deployment\n may legitimately choose a different value. It is typed configuration owned by\n the affected capability.\n3. **Policy value** — it expresses what is allowed, limited, routed, retried,\n protected, or gated. Its typed definition belongs to the owning domain and it\n is evaluated through the policy system.\n4. **Derived value** — it is computed from other settings and is not\n independently mutable.\n5. **Runtime state** — it changes as the application operates, such as the\n active model for a conversation. It is changed by a domain command and is not\n configuration merely because it can be changed.\n\nAn unclassified behavioural literal is a defect.\n\n`const` MUST NOT be used merely because a value currently has one default.\nConstants are reserved for actual invariants: enum discriminants, protocol\nversions, fixed compatibility tokens, and values whose alteration would change\nthe program's semantics rather than configure an installation.\n\nIn Go, a constant is a compile-time value and does not represent mutable runtime\nstorage. It generally has no address that can be observed or changed.\nArchitecturally, a constant therefore asserts that the value cannot change for\nthe lifetime of the application. Any value that may legitimately change while\nthe application is running, between application instances, or between\ndeployments is not a constant.\n\nA runtime setting may have a default, but the default is not its only access\npath. The owner exposes a typed settings structure, validation, and a\n`DefaultSettings` constructor or equivalent. Private constants used to implement\ndefaults do not turn those defaults into invariants and MUST NOT be consumed\ndirectly by runtime code.\n\nEach runtime setting and policy value MUST declare:\n\n- its owner;\n- type, units, validation constraints, and safe bounds;\n- default and derivation, if any;\n- whether it is startup-only, live-reloadable, or restart-required;\n- whether it may differ by installation, identity, repository, workflow,\n channel, or plugin instance;\n- whether it is secret, sensitive, or safe to report;\n- its current source, effective value, version, and last-known-good version;\n- the command and identity required to change it.\n\n## Current configuration migration ledger\n\nThis ledger records the current meanings hidden inside `internal/config`. It is\nthe source inventory for dissolving that package; rows are split where the\nexisting structure combines different owners.\n\n| Current values | Current location | Target owner and requirement |\n| ----------------------------------------------------------------------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `WorkDir`, `DBPath` | root `Config` | Workspace/storage infrastructure settings. `DBPath` is the prefix for independent task and conversation SQLite files. Defaults derive from the platform data directory. |\n| `SkillsDir`, `PluginDir` | root `Config` | Skill and plugin infrastructure settings, independently typed. |\n| `PollInterval` | root `Config` | Work-intake scheduling setting; not a daemon-wide constant. |\n| `Label`, `BotUser`, `BotEmail` | root `Config` | Identity and dispatch associations. `BotEmail` may be derived from the selected forge account but remains overrideable. |\n| `MaxRetries` | root `Config`, `Repo` | Retry policy owned by the operation being retried. The duplicate global/repository representation must disappear. |\n| `DiffCapLines` | root `Config` | Agent-change policy value. |\n| `MaxSteps`, `WallClock`, `GateMaxFailures` | `Budgets` | Workflow-execution policy, with units and zero/unlimited semantics made explicit. |\n| `Class`, `APIKeyEnv`, `BaseURL` | `Provider` | Provider instance settings. Secret lookup becomes a `SecretRef`, not an environment variable name leaking into the provider domain. |\n| `Mode`, `Command`, `Env` | `LegacyAgent` | Decode-only compatibility input for the removed executor selector. Delete after the config migration window; it has no runtime settings owner. |\n| `Type`, `Host`, `Token` / `TokenEnv` (older form) | `Forge` | Forge adapter settings. The older `TokenEnv` input is accepted only at the loader boundary. |\n| `Trigger`, `AckReaction`, label names | `Dispatch` | Work-intake and forge presentation policy. Label vocabulary is configurable per forge/identity association. |\n| `Engine` | `MemoryConfig` | Memory engine selection. `internal/domain/memory` is the only engine family; per-engine settings remain owned and validated by that engine. |\n| `Name`, `Transport`, `Command`, `Args`, `WorkDir`, `URL` | `MCPServer` | One typed MCP server instance specification. Transport-specific variants must reject fields belonging to other variants. |\n| `MaxResultChars` | `ToolPolicy` | Tool-execution policy values, not generic daemon configuration. |\n| `URL`, `TokenEnv` | `NATSConfig` | NATS transport settings with a secret reference replacing the environment-name field. |\n| `Image`, `MaxConcurrency`, `MaxUptime`, `VolumeTTL`, `PullPolicy`, `Network` | `ContainerConfig` | Mandatory managed-worker infrastructure settings and resource policy. The legacy `enabled` input is decode-only. |\n| model mappings, email, webhook, Telegram | `ChatConfig` | Separate channel instance settings plus channel-routing associations; there is no chat-wide settings owner. |\n| `AllowedUserIDs`, `Token` / `TokenEnv` (older form), update commands | Telegram config | Telegram adapter settings and access policy. `Token` is the preferred `secret.SecretRef`; `TokenEnv` remains a backwards-compatible fallback. |\n| listen/relay addresses | email config | Email adapter instance settings. |\n| webhook target | `Notify` | Notification adapter instance settings. |\n| web listen address | `Web` | Web transport settings. |\n| `listen` under `[services.state]` and `[services.gateway]` | `ServiceConnection` | The bind address of the process that owns the service. Read only by that process, and defaulted to the address its clients dial so the pair cannot drift. |\n| forge, dispatch, models, providers, containers, memory, tools and repositories | `IdentityConfig` | Existing composite duplicates unrelated settings. Replace it with associations from an `IdentityID` to independently owned configured instances. |\n| owner, name, base, gate, protection, ecosystem, preflight, storage, retry and concurrency | `Repo` | Split across work intake, workspace, workflow execution, policy, gate, and scheduling as described in Repository settings. |\n| `TaskConfig`, `TaskForge` | worker snapshot | Replace with the minimum immutable, versioned WorkflowExecution input assembled by the application. It is not a second configuration model. |\n| `Extra` and arbitrary maps | root/provider config | Allowed only at an extension boundary whose owning plugin/provider supplies schema and validation. Core configuration never consumes an untyped catch-all. |\n\n## Behavioural literals and incorrectly fixed values\n\nThe following current values affect useful behaviour but are not represented as\nowned typed settings or policy. They MUST be classified and migrated before the\nold configuration package is removed. The listed target is the architectural\ndecision; exact setting names are implementation details.\n\n| Capability | Values fixed in current code | Required classification |\n| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Chat agent | maximum steps `8` in `cmd/archied` | Workflow/chat execution policy. |\n| Context compression | enabled, threshold `0.5`, context size `128000`, protect first `3` and last `20`, compression marker, token estimate of four characters per token | Model/context runtime settings. The marker is presentation; the estimate is provider/model strategy, not a universal truth. |\n| Tool guardrails | escalation thresholds `3`, `5`, `10`, `2` | Tool-use policy with named meanings and bounded defaults. |\n| Tool output | per-result cap `50000` characters, no aggregate turn cap, preview `500` characters | Tool-execution resource and presentation settings. Per-result spill/truncation remains; turn continuation is not character- or token-gated. |\n| Pairing/access | code TTL `1h`, maximum pending `3`, rate window `10m`, failures `5`, lockout `1h`, maximum lockout `24h` | Access policy. Code length/alphabet and salt length require an explicit security-constraint decision; they are not automatically valid constants. |\n| NATS daemon consumer | stream `ARCHIE_TASKS`, consumer `archie-daemon`, deduplication `2m`, poll `2s`, deliveries `3`, acknowledgement wait `5m`, inactive threshold `24h`, subjects | NATS topology settings plus delivery policy. Subject grammar or protocol headers may be invariants only if declared as versioned wire contracts. |\n| NATS worker consumer | stream `ARCHIE_TASKS`, consumer `archie-agent`, deduplication `2m`, poll `5s`, acknowledgement wait `30m`, deliveries `3`, inactive threshold `24h`, queue group and retry delay `1s` | Worker transport settings and delivery/retry policy. Shared stream defaults must have one owner rather than two copies. |\n| Worker readiness | readiness timeout `20s`, retry delay `250ms` | Worker lifecycle and retry policy. |\n| Execution/RPC | agent execution `30m`, task-run RPC `60s`, worktree RPC `15m` | Per-operation timeout policy. |\n| Plugin/tool cleanup | plugin rollback `10s`, tool-provider cleanup `10s`, MCP-provider cleanup `10s` | Lifecycle shutdown/rollback policy owned by each engine, with a shared policy vocabulary where appropriate. |\n| Memory read path | per-scope record limit `20`, rendered `\u003cmemory\u003e` block byte cap `8192` | Memory read policy owned by the engine family (`internal/domain/memory`). |\n| Built-in memory store | per-file size limit `100KiB`, query result limit `100` | Split into memory resource policy, input policy, and presentation settings. |\n| Memory safety scanner | compiled prompt-injection and sensitive-data patterns with fixed warn/block consequences | Versioned memory-domain policy definitions. Patterns and consequences must be inspectable and replaceable without editing scanner code. |\n| MCP stdio | initial backoff `500ms`, maximum backoff `30s`, unlimited default retries, send and shutdown `5s` | MCP transport retry, request, and lifecycle policy. Unlimited retries must be explicit rather than a zero-value accident. |\n| MCP SSE/HTTP | reconnect `1s` to `30s`, POST/request timeout `30s` | MCP transport settings and retry policy. |\n| Message framing | MCP frame `4MiB`, worker protocol frame `8MiB`, diagnostic `64KiB`, media/base64 `64MiB` | Resource/security policy unless a published wire protocol mandates the limit. Limits must be configurable only within safe bounds. |\n| Webhooks and web UI | webhook bind `0.0.0.0:8644`, webhook shutdown `5s`, web read-header `5s`, web shutdown `2s` | Transport instance and lifecycle settings. |\n| Telegram | typing refresh `4s`, draft interval `700ms`, update-action TTL `10m` | Telegram adapter presentation and lifecycle settings. |\n| Telegram limits | message length `4000` and callback/update prefixes | Record the upstream platform constraint and version it as an adapter compatibility limit; prefixes may remain wire constants when changing them would invalidate outstanding callbacks. |\n| Containers | stop and pull timeouts `10s` and `30s` | Container lifecycle policy. |\n| HTTP clients | feasibility notification timeout `10s`; other paths use `http.DefaultClient` | Adapter request policy. Every outbound client requires an explicit timeout profile. |\n| Workflow routing | labels `bug`, `feature`, `bootstrap`; workflows `tdd`, `feasibility`, `bootstrap`; fallback `implement` | Agent-system routing policy. Workflow identifiers are references, not compiled routing decisions. |\n| Filesystem/deployment | `.agents/skills`, `.archie/stages`, `.archie/gate.go`, `/data/worktree`, `/data/repo`, cache names/paths and prepared sentinel | Split into deployment settings, repository conventions, and genuine internal protocol markers. Paths an installation may relocate are settings. |\n| Packaged release data | `/usr/share/archie/CHANGELOG.md` | Packaging/deployment settings or paths derived from an installation prefix. |\n| Forge presentation | default label colour `bfd4f2` and state-label colours | Forge adapter presentation settings. |\n| Fallback system prompt | compiled fallback prompt | Agent-system default content, versioned and replaceable through its owning settings; safety constraints remain policy/code. |\n| Default paths and identities | config path, data paths, listen addresses, model roles and workflow names | Typed defaults belonging to their respective owners, never global constants consumed throughout the application. |\n\nThis inventory is intentionally broader than exported Go `const` declarations. A\nliteral hidden in a constructor, timeout, switch, retry loop, path join, prompt,\nlabel map, or client setup restricts behaviour just as effectively as an\nincorrectly used constant.\n\n## Constants that may remain\n\nA value may remain constant only when its owner documents why runtime variation\nwould be invalid. Typical valid cases are:\n\n- domain enum values and state names;\n- a versioned wire-protocol version or framing token;\n- reserved internal headers and callback prefixes that peers must interpret\n identically;\n- compile-time mathematical relationships;\n- sentinel errors and internal type identifiers.\n\nNames such as a stream, consumer, label, workflow, file, directory, network,\nmodel role, timeout, retry count, capacity, size limit, colour, prompt, command,\nor executable are not invariants merely because the current application has only\none of them.\n\nArchitecture tests SHOULD reject exported behavioural constants outside approved\ninvariant packages and SHOULD detect direct consumption of private default\nconstants outside their owning `DefaultSettings` construction.\n\n## Current mutation and reload ledger\n\nThe application currently changes behavioural values through unrelated paths:\n\n| Current change seam | Current behaviour | Required target |\n| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Telegram `/restart` in `cmd/archied` | Re-reads the global document and directly replaces Telegram token and allowed-user IDs; failure retains old values. | Submit a Telegram-settings candidate through the universal change protocol. Validate the complete candidate, promote atomically, audit the acting identity, and retain last-known-good. |\n| Active model selection | `chatModelManager.SetActiveModel` changes a model reference. | A conversation/session command changing runtime state. Validate against configured model instances and audit it; do not rewrite configuration. |\n| Active provider selection | `chatModelManager.SetActiveProvider` changes provider selection. | A conversation/session command changing runtime state, with the same distinction from provider-instance configuration. |\n| Persona selection | `PersonaRegistry.SetActive` mutates an in-memory per-session choice. | Agent-system session state. Persistence and audit requirements are owned by that domain, not the configuration loader. |\n| File and environment overlays | Applied while loading `internal/config`; defaults are filled by mutation in `finalize`. | Configuration-infrastructure input processing that produces separately typed candidates. Defaults and derivations remain visible in provenance. |\n| SIGHUP config reload (2026-08) | Re-resolves the file config, re-applies the database layer over it, validates, then atomically republishes through `config.Holder`. A failed reload, whether the file or the control plane caused it, keeps the running config and records `last_error`/`last_error_at` in `/api/config`. | Candidate promotion with last-known-good retention: the running snapshot is untouched on failure. A bounded observation period and actor audit are not yet implemented. |\n| Control-plane resource command (2026-09) | `ControlPlaneService.Command` validates a whole resource document against its owning feature, then writes it with an audit record (actor, source, request ID, expected version) under optimistic concurrency. Hosted on the State Store's gRPC server; the Web UI and messaging channels are its only clients. See `docs/prds/runtime-control-plane.md`. | Met for validate-stage-promote, actor audit and versioned history. Per-field health observation and validate-before-switch on live apply are not yet implemented. |\n\nAny further mutation seam discovered during migration MUST be added here before\nit is changed. Direct field assignment on a live settings object is prohibited.\n\n## Universal change protocol\n\nChanging configuration is an application command performed by an identity. It\nMUST:\n\n1. resolve the target owner and current version;\n2. parse into that owner's typed settings;\n3. validate syntax, semantic constraints, policy, references, and safe bounds;\n4. stage a candidate without altering the active value;\n5. run owner-defined readiness and health checks;\n6. atomically promote the candidate and record actor, source, reason, diff,\n prior version, and new version;\n7. observe the affected capability for a bounded period;\n8. retain the new version on success, or automatically restore last-known-good\n on failure;\n9. report the rejected or rolled-back candidate without terminating unaffected\n capabilities.\n\nStartup loading uses the same candidate rules. A bad user value therefore does\nnot partially mutate the application or make a previously healthy capability\nunavailable.\n\nSettings that cannot safely reload in-process are marked restart-required. The\nchange may still be validated and versioned immediately, but promotion occurs\nthrough a controlled restart with the same health and rollback semantics.\n\n## Implemented runtime reload and settings writes (2026-09)\n\nTwo mechanisms change behavioural values at runtime: SIGHUP re-reads the file\nconfig, and the control plane owns every database-backed setting. The dashboard\nruntime overlay that used to sit between them was deleted once the control plane\ncovered its surface; `-config-overlay` names a file overlay and is unrelated.\n\n### Published snapshot: `config.Holder`\n\nThe running configuration is a published snapshot held in `config.Holder`\n(`internal/config/holder.go`). Get returns a value under RLock; Set replaces the\nwhole snapshot. A published Config is immutable: reload constructs a fresh one\nand calls Set. `config.Clone` deep-copies every reference-type field so a failed\ndecode cannot mutate the published snapshot's shared maps. `Holder.Get` panics\non a nil receiver — a forgotten `NewHolder` must fail loudly, not boot a daemon\nthat silently runs on an empty config.\n\n### The reloadable-field criterion\n\nThe diff-and-warn on reload asks whether a changed field takes effect without a\nrestart. The criterion is: **a field is reloadable when every consumer re-reads\nit.** That question read as \"what does the daemon re-read\" while the daemon owned\nthe only Holder; it stopped being sufficient when webui began sharing that\nHolder, because webui handlers re-read on every request. The allowlist lives in\n`cmd/archied/reload.go` and is deliberately a deny-by-default list: a field added\nto Config later defaults to requires-restart, forcing whoever adds it to decide\ndeliberately. A reload that changes any non-allowlisted field logs\n\"requires a restart\" with the field names; a fully-applied reload logs Info.\n\n### SIGHUP reload\n\nSIGHUP re-resolves the file config, re-applies the database layer over it\n(`boot.runtimeConfig`, the same call boot makes), validates, and atomically\nrepublishes through the shared Holder. A failed reload keeps the running config\nand records `last_error`/`last_error_at` in `/api/config` so the stale state is\nvisible where the operator is looking. The three poll tickers re-read\n`PollInterval` per iteration and reset on change, so a reloaded interval\ngenuinely takes effect.\n\n### Settings writes go through the control plane\n\nDatabase-backed settings are read and written through\n`ControlPlaneService` on the State Store's gRPC server: catalog, query,\ncommand, watch. Each feature owns its resource's validation and commands;\nstorage writes versions and audit records only. `docs/prds/runtime-control-plane.md`\nis the specification.\n\nTwo properties matter to anyone changing this area:\n\n- **Bootstrap stays file-owned.** The daemon reads the file config first and\n layers database resources over it at boot (`boot.loadRuntimeConfig`). Values\n the daemon needs before it can reach the State Store — the database path,\n listen addresses, credentials — stay file-only by design.\n- **Reload re-reads them.** SIGHUP resolves the file document and then runs the\n same `boot.runtimeConfig` layering boot does, so a reload cannot revert a\n database-owned setting to its file value. A control plane that cannot answer\n fails the reload rather than publishing the file's values over the running\n ones. Workflow execution budgets arrive on a watch rather than in a resource\n query, so boot records the last published settings and the reload re-applies\n them from there.\n\n## Completion criteria\n\nThe configuration rearchitecture is complete only when:\n\n- `internal/config` no longer exists;\n- every behavioural value has one classification and owner;\n- every current field and hard-coded value in the ledgers has a recorded\n disposition;\n- domains and plugins receive only their typed settings;\n- all changes use semantic commands and the universal change protocol;\n- active, candidate, rejected, rolled-back, and last-known-good versions are\n queryable with secret-safe provenance;\n- generated documentation lists every external key, default, constraint,\n mutability class, owner, and deprecation;\n- architecture tests prevent a new central runtime configuration model, direct\n live-setting mutation, and incorrectly fixed behavioural values.\n\n## Startup policy: missing credential degrades, invalid config is fatal\n\nDecided 2026-07-30. Recovered 2026-08-09 from the pre-migration issue tracker.\n\nA missing **credential** disables a capability. Only an **invalid config** stops\nthe daemon. \"Forge is a feature, not a requirement.\"\n\nBefore `518a1a0`, an unresolvable forge token did `return 1` in\n`cmd/archied/main.go`, so a chat-only user who never configured GitHub got no\nchat, no gateway, nothing — and under a systemd unit with `Restart=on-failure`\nand no start limit it crash-looped every five seconds with the error scrolling\npast unread. Forge construction now lives in `resolveForge`, shared by the\nprimary forge and every configured identity, and degrades to `forge.NewNoop`\nwith a warning. The identity path had the same defect and was worse: one\nidentity's missing credential killed all the others.\n\nMalformed configuration still fails fast in `configuration.Validate`, well\nbefore this point. That distinction is the whole design.\n\nApply the same reasoning to any future capability credential, LLM keys\nespecially: start, report the capability as unavailable, let the operator see it.\nGuarded by `TestResolveForgeDegradesInsteadOfFailing`.\n\n**Known consequence, tracked separately:** `worktree.Manager` still receives the\nempty token, so pushes fail late rather than at startup.\n\n## Config generation belongs to `archied setup`, not `install.sh`\n\nDecided 2026-07-30 ([#368](https://github.com/samcharles93/archie-core/issues/368)).\nRecovered 2026-08-09 from the pre-migration issue tracker.\n\n`install.sh` must stop generating `config.toml`; `archied setup` owns it. The\ninstaller hand-rolling TOML has already drifted from the schema once: the\ngenerated-config branch hardcoded `key = ARCHIE_GITHUB_TOKEN` and\n`host = ${GITEA_URL}` regardless of the answers given, so choosing Gitea produced\na config naming a token the installer never wrote (archied then exited 1), and\nchoosing GitHub pointed `host` at `gitea.example.com`. `61a5b35` patched this\nwith a `forge_block` shell helper shared by both config paths — that helper is a\n**workaround**, deleted by\n[#72](https://github.com/samcharles93/archie-core/issues/72). The durable fix is\nthat the code writing the config is the code that reads it.\n\nWhy Go and not Python: the installer must run where nothing is installed yet, and\n`python3` with `tomllib` means 3.11+, which is not safe on LTS distros. `archied`\nis already being built two steps earlier.\n\n**Key constraint for the port:** `BurntSushi/toml` does **not** survive a\ndecode/encode round trip with comments intact, and `config.example.toml` carries\ndocumentation users are meant to hand-edit. Decide the write strategy\n([#412](https://github.com/samcharles93/archie-core/issues/412)) before writing\nany prompting code. Do not port a separate `config.yaml`/`auth.yaml` secret\nsplit — Archie already has `secret.SecretRef{engine,key}`, so setup writes the\nreference to TOML and the value to the secret engine.\n" + "body": "# Configuration\n\n**Status:** Approved; existing-type assignment is ongoing \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Ownership\n\nConfiguration has two separate responsibilities:\n\n1. `internal/infrastructure/configuration` loads files, environment variables,\n secret references, overlays, and compatibility representations.\n2. Each domain and plugin owns the typed runtime settings required for its\n behaviour.\n\n`internal/app` translates external input into those settings, validates\ncross-capability combinations, and supplies each component only its own\nsettings.\n\nThe following are prohibited:\n\n- passing complete application configuration into a domain;\n- making a domain depend on TOML, YAML, environment-variable names, secret\n references, or a configuration library;\n- defining a central runtime configuration type imported across the system;\n- placing plugin options in an unrelated global configuration model.\n\n## Private input document\n\n`internal/infrastructure/configuration` MAY use a complete decoded document\nwhile discovering files, decoding sections, and applying overlays. It is an\ninput-boundary DTO only.\n\nThe document:\n\n- remains private to the configuration infrastructure;\n- is composed from separately defined feature sections;\n- is immediately translated by application composition;\n- is never returned as the application's runtime model;\n- is never passed through runtime components.\n\nExternal DTOs and domain runtime settings are separate types.\n\nPlugins supply external configuration definitions through a narrow extension\ncontract. The core loader MUST NOT gain a field or recognized filename for every\nplugin.\n\nInvalid configuration input MUST NOT replace active valid settings or terminate\nunaffected capabilities. Configuration changes use the candidate validation,\npromotion, audit, and recovery requirements in\n[safe-change-and-recovery.md](/dev/architecture/safe-change-and-recovery/).\n\n## Dissolution of `internal/config`\n\n`internal/config` has no target location. It MUST be dissolved and MUST NOT\nsurvive as a shared package, configuration domain, or renamed global model.\n\nIts loading behaviour moves to `internal/infrastructure/configuration`. Existing\ntypes and methods are reassigned by behaviour. Repository execution policy,\ndispatch policy, retry policy, ecosystem defaults, tool policy, memory settings,\nprovider settings, and channel settings move to their\nrespective owners.\n\n## Repository settings\n\nThe existing `config.Repo` MUST NOT move intact into a repository domain or\nshared settings package. A managed repository is an application association:\n\n- work intake owns which repository references an identity monitors;\n- task execution owns gates, preflight, test protection, ecosystem behaviour,\n and change limits;\n- task lifecycle owns retry behaviour;\n- scheduling owns concurrency policy;\n- workspace management owns base branch and persistent-storage requirements.\n\nApplication composition correlates these settings by repository reference. No\ndomain receives a universal repository profile.\n\n## Documentation\n\nGenerated configuration reference describes external sections and their owning\ncapabilities. It MUST NOT establish a global Go configuration structure as the\npublic contract.\n\n## Value classification rule\n\nEvery value that controls behaviour MUST have an explicit owner and MUST be\nclassified as exactly one of:\n\n1. **Invariant** — changing it changes the meaning of the program, a wire\n protocol, or a domain concept. It may be a Go constant.\n2. **Runtime setting** — an operator, identity, domain, plugin, or deployment\n may legitimately choose a different value. It is typed configuration owned by\n the affected capability.\n3. **Policy value** — it expresses what is allowed, limited, routed, retried,\n protected, or gated. Its typed definition belongs to the owning domain and it\n is evaluated through the policy system.\n4. **Derived value** — it is computed from other settings and is not\n independently mutable.\n5. **Runtime state** — it changes as the application operates, such as the\n active model for a conversation. It is changed by a domain command and is not\n configuration merely because it can be changed.\n\nAn unclassified behavioural literal is a defect.\n\n`const` MUST NOT be used merely because a value currently has one default.\nConstants are reserved for actual invariants: enum discriminants, protocol\nversions, fixed compatibility tokens, and values whose alteration would change\nthe program's semantics rather than configure an installation.\n\nIn Go, a constant is a compile-time value and does not represent mutable runtime\nstorage. It generally has no address that can be observed or changed.\nArchitecturally, a constant therefore asserts that the value cannot change for\nthe lifetime of the application. Any value that may legitimately change while\nthe application is running, between application instances, or between\ndeployments is not a constant.\n\nA runtime setting may have a default, but the default is not its only access\npath. The owner exposes a typed settings structure, validation, and a\n`DefaultSettings` constructor or equivalent. Private constants used to implement\ndefaults do not turn those defaults into invariants and MUST NOT be consumed\ndirectly by runtime code.\n\nEach runtime setting and policy value MUST declare:\n\n- its owner;\n- type, units, validation constraints, and safe bounds;\n- default and derivation, if any;\n- whether it is startup-only, live-reloadable, or restart-required;\n- whether it may differ by installation, identity, repository, workflow,\n channel, or plugin instance;\n- whether it is secret, sensitive, or safe to report;\n- its current source, effective value, version, and last-known-good version;\n- the command and identity required to change it.\n\n## Current configuration migration ledger\n\nThis ledger records the current meanings hidden inside `internal/config`. It is\nthe source inventory for dissolving that package; rows are split where the\nexisting structure combines different owners.\n\n| Current values | Current location | Target owner and requirement |\n| ----------------------------------------------------------------------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `WorkDir`, `StateDir`, `DBPath` | root `Config` | Workspace/storage infrastructure settings, bootstrap-only. `StateDir` holds the embedded NATS store and endpoint file, task logs and the readiness disk target. `DBPath` only locates the legacy SQLite files (`\u003cdb_path\u003e-tasks.sqlite`, `-eda.sqlite`, `-conversations.sqlite`) for `archie-state-store import` and the boot gate that refuses to serve until it has run; it goes when the importer does. Defaults derive from the platform data directory. |\n| `SkillsDir`, `PluginDir` | root `Config` | Skill and plugin infrastructure settings, independently typed. |\n| `PollInterval` | root `Config` | Work-intake scheduling setting; not a daemon-wide constant. |\n| `Label`, `BotUser`, `BotEmail` | root `Config` | Identity and dispatch associations. `BotEmail` may be derived from the selected forge account but remains overrideable. |\n| `MaxRetries` | root `Config`, `Repo` | Retry policy owned by the operation being retried. The duplicate global/repository representation must disappear. |\n| `DiffCapLines` | root `Config` | Agent-change policy value. |\n| `MaxSteps`, `WallClock`, `GateMaxFailures` | `Budgets` | Workflow-execution policy, with units and zero/unlimited semantics made explicit. |\n| `Class`, `APIKeyEnv`, `BaseURL` | `Provider` | Provider instance settings. Secret lookup becomes a `SecretRef`, not an environment variable name leaking into the provider domain. |\n| `Mode`, `Command`, `Env` | `LegacyAgent` | Decode-only compatibility input for the removed executor selector. Delete after the config migration window; it has no runtime settings owner. |\n| `Type`, `Host`, `Token` / `TokenEnv` (older form) | `Forge` | Forge adapter settings. The older `TokenEnv` input is accepted only at the loader boundary. |\n| `Trigger`, `AckReaction`, label names | `Dispatch` | Work-intake and forge presentation policy. Label vocabulary is configurable per forge/identity association. |\n| `Engine` | `MemoryConfig` | Memory engine selection. `internal/domain/memory` is the only engine family; per-engine settings remain owned and validated by that engine. |\n| `Name`, `Transport`, `Command`, `Args`, `WorkDir`, `URL` | `MCPServer` | One typed MCP server instance specification. Transport-specific variants must reject fields belonging to other variants. |\n| `MaxResultChars` | `ToolPolicy` | Tool-execution policy values, not generic daemon configuration. |\n| `URL`, `TokenEnv` | `NATSConfig` | NATS transport settings with a secret reference replacing the environment-name field. |\n| `Image`, `MaxConcurrency`, `MaxUptime`, `VolumeTTL`, `PullPolicy`, `Network` | `ContainerConfig` | Mandatory managed-worker infrastructure settings and resource policy. The legacy `enabled` input is decode-only. |\n| model mappings, email, webhook, Telegram | `ChatConfig` | Separate channel instance settings plus channel-routing associations; there is no chat-wide settings owner. |\n| `AllowedUserIDs`, `Token` / `TokenEnv` (older form), update commands | Telegram config | Telegram adapter settings and access policy. `Token` is the preferred `secret.SecretRef`; `TokenEnv` remains a backwards-compatible fallback. |\n| listen/relay addresses | email config | Email adapter instance settings. |\n| webhook target | `Notify` | Notification adapter instance settings. |\n| web listen address | `Web` | Web transport settings. |\n| `listen` under `[services.state]` and `[services.gateway]` | `ServiceConnection` | The bind address of the process that owns the service. Read only by that process, and defaulted to the address its clients dial so the pair cannot drift. |\n| forge, dispatch, models, providers, containers, memory, tools and repositories | `IdentityConfig` | Existing composite duplicates unrelated settings. Replace it with associations from an `IdentityID` to independently owned configured instances. |\n| owner, name, base, gate, protection, ecosystem, preflight, storage, retry and concurrency | `Repo` | Split across work intake, workspace, workflow execution, policy, gate, and scheduling as described in Repository settings. |\n| `TaskConfig`, `TaskForge` | worker snapshot | Replace with the minimum immutable, versioned WorkflowExecution input assembled by the application. It is not a second configuration model. |\n| `Extra` and arbitrary maps | root/provider config | Allowed only at an extension boundary whose owning plugin/provider supplies schema and validation. Core configuration never consumes an untyped catch-all. |\n\n## Behavioural literals and incorrectly fixed values\n\nThe following current values affect useful behaviour but are not represented as\nowned typed settings or policy. They MUST be classified and migrated before the\nold configuration package is removed. The listed target is the architectural\ndecision; exact setting names are implementation details.\n\n| Capability | Values fixed in current code | Required classification |\n| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Chat agent | maximum steps `8` in `cmd/archied` | Workflow/chat execution policy. |\n| Context compression | enabled, threshold `0.5`, context size `128000`, protect first `3` and last `20`, compression marker, token estimate of four characters per token | Model/context runtime settings. The marker is presentation; the estimate is provider/model strategy, not a universal truth. |\n| Tool guardrails | escalation thresholds `3`, `5`, `10`, `2` | Tool-use policy with named meanings and bounded defaults. |\n| Tool output | per-result cap `50000` characters, no aggregate turn cap, preview `500` characters | Tool-execution resource and presentation settings. Per-result spill/truncation remains; turn continuation is not character- or token-gated. |\n| Pairing/access | code TTL `1h`, maximum pending `3`, rate window `10m`, failures `5`, lockout `1h`, maximum lockout `24h` | Access policy. Code length/alphabet and salt length require an explicit security-constraint decision; they are not automatically valid constants. |\n| NATS daemon consumer | stream `ARCHIE_TASKS`, consumer `archie-daemon`, deduplication `2m`, poll `2s`, deliveries `3`, acknowledgement wait `5m`, inactive threshold `24h`, subjects | NATS topology settings plus delivery policy. Subject grammar or protocol headers may be invariants only if declared as versioned wire contracts. |\n| NATS worker consumer | stream `ARCHIE_TASKS`, consumer `archie-agent`, deduplication `2m`, poll `5s`, acknowledgement wait `30m`, deliveries `3`, inactive threshold `24h`, queue group and retry delay `1s` | Worker transport settings and delivery/retry policy. Shared stream defaults must have one owner rather than two copies. |\n| Worker readiness | readiness timeout `20s`, retry delay `250ms` | Worker lifecycle and retry policy. |\n| Execution/RPC | agent execution `30m`, task-run RPC `60s`, worktree RPC `15m` | Per-operation timeout policy. |\n| Plugin/tool cleanup | plugin rollback `10s`, tool-provider cleanup `10s`, MCP-provider cleanup `10s` | Lifecycle shutdown/rollback policy owned by each engine, with a shared policy vocabulary where appropriate. |\n| Memory read path | per-scope record limit `20`, rendered `\u003cmemory\u003e` block byte cap `8192` | Memory read policy owned by the engine family (`internal/domain/memory`). |\n| Built-in memory store | per-file size limit `100KiB`, query result limit `100` | Split into memory resource policy, input policy, and presentation settings. |\n| Memory safety scanner | compiled prompt-injection and sensitive-data patterns with fixed warn/block consequences | Versioned memory-domain policy definitions. Patterns and consequences must be inspectable and replaceable without editing scanner code. |\n| MCP stdio | initial backoff `500ms`, maximum backoff `30s`, unlimited default retries, send and shutdown `5s` | MCP transport retry, request, and lifecycle policy. Unlimited retries must be explicit rather than a zero-value accident. |\n| MCP SSE/HTTP | reconnect `1s` to `30s`, POST/request timeout `30s` | MCP transport settings and retry policy. |\n| Message framing | MCP frame `4MiB`, worker protocol frame `8MiB`, diagnostic `64KiB`, media/base64 `64MiB` | Resource/security policy unless a published wire protocol mandates the limit. Limits must be configurable only within safe bounds. |\n| Webhooks and web UI | webhook bind `0.0.0.0:8644`, webhook shutdown `5s`, web read-header `5s`, web shutdown `2s` | Transport instance and lifecycle settings. |\n| Telegram | typing refresh `4s`, draft interval `700ms`, update-action TTL `10m` | Telegram adapter presentation and lifecycle settings. |\n| Telegram limits | message length `4000` and callback/update prefixes | Record the upstream platform constraint and version it as an adapter compatibility limit; prefixes may remain wire constants when changing them would invalidate outstanding callbacks. |\n| Containers | stop and pull timeouts `10s` and `30s` | Container lifecycle policy. |\n| HTTP clients | feasibility notification timeout `10s`; other paths use `http.DefaultClient` | Adapter request policy. Every outbound client requires an explicit timeout profile. |\n| Workflow routing | labels `bug`, `feature`, `bootstrap`; workflows `tdd`, `feasibility`, `bootstrap`; fallback `implement` | Agent-system routing policy. Workflow identifiers are references, not compiled routing decisions. |\n| Filesystem/deployment | `.agents/skills`, `.archie/stages`, `.archie/gate.go`, `/data/worktree`, `/data/repo`, cache names/paths and prepared sentinel | Split into deployment settings, repository conventions, and genuine internal protocol markers. Paths an installation may relocate are settings. |\n| Packaged release data | `/usr/share/archie/CHANGELOG.md` | Packaging/deployment settings or paths derived from an installation prefix. |\n| Forge presentation | default label colour `bfd4f2` and state-label colours | Forge adapter presentation settings. |\n| Fallback system prompt | compiled fallback prompt | Agent-system default content, versioned and replaceable through its owning settings; safety constraints remain policy/code. |\n| Default paths and identities | config path, data paths, listen addresses, model roles and workflow names | Typed defaults belonging to their respective owners, never global constants consumed throughout the application. |\n\nThis inventory is intentionally broader than exported Go `const` declarations. A\nliteral hidden in a constructor, timeout, switch, retry loop, path join, prompt,\nlabel map, or client setup restricts behaviour just as effectively as an\nincorrectly used constant.\n\n## Constants that may remain\n\nA value may remain constant only when its owner documents why runtime variation\nwould be invalid. Typical valid cases are:\n\n- domain enum values and state names;\n- a versioned wire-protocol version or framing token;\n- reserved internal headers and callback prefixes that peers must interpret\n identically;\n- compile-time mathematical relationships;\n- sentinel errors and internal type identifiers.\n\nNames such as a stream, consumer, label, workflow, file, directory, network,\nmodel role, timeout, retry count, capacity, size limit, colour, prompt, command,\nor executable are not invariants merely because the current application has only\none of them.\n\nArchitecture tests SHOULD reject exported behavioural constants outside approved\ninvariant packages and SHOULD detect direct consumption of private default\nconstants outside their owning `DefaultSettings` construction.\n\n## Current mutation and reload ledger\n\nThe application currently changes behavioural values through unrelated paths:\n\n| Current change seam | Current behaviour | Required target |\n| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Telegram `/restart` in `cmd/archied` | Re-reads the global document and directly replaces Telegram token and allowed-user IDs; failure retains old values. | Submit a Telegram-settings candidate through the universal change protocol. Validate the complete candidate, promote atomically, audit the acting identity, and retain last-known-good. |\n| Active model selection | `chatModelManager.SetActiveModel` changes a model reference. | A conversation/session command changing runtime state. Validate against configured model instances and audit it; do not rewrite configuration. |\n| Active provider selection | `chatModelManager.SetActiveProvider` changes provider selection. | A conversation/session command changing runtime state, with the same distinction from provider-instance configuration. |\n| Persona selection | `PersonaRegistry.SetActive` mutates an in-memory per-session choice. | Agent-system session state. Persistence and audit requirements are owned by that domain, not the configuration loader. |\n| File and environment overlays | Applied while loading `internal/config`; defaults are filled by mutation in `finalize`. | Configuration-infrastructure input processing that produces separately typed candidates. Defaults and derivations remain visible in provenance. |\n| SIGHUP config reload (2026-08) | Re-resolves the file config, re-applies the database layer over it, validates, then atomically republishes through `config.Holder`. A failed reload, whether the file or the control plane caused it, keeps the running config and records `last_error`/`last_error_at` in `/api/config`. | Candidate promotion with last-known-good retention: the running snapshot is untouched on failure. A bounded observation period and actor audit are not yet implemented. |\n| Control-plane resource command (2026-09) | `ControlPlaneService.Command` validates a whole resource document against its owning feature, then writes it with an audit record (actor, source, request ID, expected version) under optimistic concurrency. Hosted on the State Store's gRPC server; the Web UI and messaging channels are its only clients. See `docs/prds/runtime-control-plane.md`. | Met for validate-stage-promote, actor audit and versioned history. Per-field health observation and validate-before-switch on live apply are not yet implemented. |\n\nAny further mutation seam discovered during migration MUST be added here before\nit is changed. Direct field assignment on a live settings object is prohibited.\n\n## Universal change protocol\n\nChanging configuration is an application command performed by an identity. It\nMUST:\n\n1. resolve the target owner and current version;\n2. parse into that owner's typed settings;\n3. validate syntax, semantic constraints, policy, references, and safe bounds;\n4. stage a candidate without altering the active value;\n5. run owner-defined readiness and health checks;\n6. atomically promote the candidate and record actor, source, reason, diff,\n prior version, and new version;\n7. observe the affected capability for a bounded period;\n8. retain the new version on success, or automatically restore last-known-good\n on failure;\n9. report the rejected or rolled-back candidate without terminating unaffected\n capabilities.\n\nStartup loading uses the same candidate rules. A bad user value therefore does\nnot partially mutate the application or make a previously healthy capability\nunavailable.\n\nSettings that cannot safely reload in-process are marked restart-required. The\nchange may still be validated and versioned immediately, but promotion occurs\nthrough a controlled restart with the same health and rollback semantics.\n\n## Implemented runtime reload and settings writes (2026-09)\n\nTwo mechanisms change behavioural values at runtime: SIGHUP re-reads the file\nconfig, and the control plane owns every database-backed setting. The dashboard\nruntime overlay that used to sit between them was deleted once the control plane\ncovered its surface; `-config-overlay` names a file overlay and is unrelated.\n\n### Published snapshot: `config.Holder`\n\nThe running configuration is a published snapshot held in `config.Holder`\n(`internal/config/holder.go`). Get returns a value under RLock; Set replaces the\nwhole snapshot. A published Config is immutable: reload constructs a fresh one\nand calls Set. `config.Clone` deep-copies every reference-type field so a failed\ndecode cannot mutate the published snapshot's shared maps. `Holder.Get` panics\non a nil receiver — a forgotten `NewHolder` must fail loudly, not boot a daemon\nthat silently runs on an empty config.\n\n### The reloadable-field criterion\n\nThe diff-and-warn on reload asks whether a changed field takes effect without a\nrestart. The criterion is: **a field is reloadable when every consumer re-reads\nit.** That question read as \"what does the daemon re-read\" while the daemon owned\nthe only Holder; it stopped being sufficient when webui began sharing that\nHolder, because webui handlers re-read on every request. The allowlist lives in\n`cmd/archied/reload.go` and is deliberately a deny-by-default list: a field added\nto Config later defaults to requires-restart, forcing whoever adds it to decide\ndeliberately. A reload that changes any non-allowlisted field logs\n\"requires a restart\" with the field names; a fully-applied reload logs Info.\n\n### SIGHUP reload\n\nSIGHUP re-resolves the file config, re-applies the database layer over it\n(`boot.runtimeConfig`, the same call boot makes), validates, and atomically\nrepublishes through the shared Holder. A failed reload keeps the running config\nand records `last_error`/`last_error_at` in `/api/config` so the stale state is\nvisible where the operator is looking. The three poll tickers re-read\n`PollInterval` per iteration and reset on change, so a reloaded interval\ngenuinely takes effect.\n\n### Settings writes go through the control plane\n\nDatabase-backed settings are read and written through\n`ControlPlaneService` on the State Store's gRPC server: catalog, query,\ncommand, watch. Each feature owns its resource's validation and commands;\nstorage writes versions and audit records only. `docs/prds/runtime-control-plane.md`\nis the specification.\n\nTwo properties matter to anyone changing this area:\n\n- **Bootstrap stays file-owned.** The daemon reads the file config first and\n layers database resources over it at boot (`boot.loadRuntimeConfig`). Values\n the daemon needs before it can reach the State Store — the database path,\n listen addresses, credentials — stay file-only by design.\n- **Reload re-reads them.** SIGHUP resolves the file document and then runs the\n same `boot.runtimeConfig` layering boot does, so a reload cannot revert a\n database-owned setting to its file value. A control plane that cannot answer\n fails the reload rather than publishing the file's values over the running\n ones. Workflow execution budgets arrive on a watch rather than in a resource\n query, so boot records the last published settings and the reload re-applies\n them from there.\n\n## Completion criteria\n\nThe configuration rearchitecture is complete only when:\n\n- `internal/config` no longer exists;\n- every behavioural value has one classification and owner;\n- every current field and hard-coded value in the ledgers has a recorded\n disposition;\n- domains and plugins receive only their typed settings;\n- all changes use semantic commands and the universal change protocol;\n- active, candidate, rejected, rolled-back, and last-known-good versions are\n queryable with secret-safe provenance;\n- generated documentation lists every external key, default, constraint,\n mutability class, owner, and deprecation;\n- architecture tests prevent a new central runtime configuration model, direct\n live-setting mutation, and incorrectly fixed behavioural values.\n\n## Startup policy: missing credential degrades, invalid config is fatal\n\nDecided 2026-07-30. Recovered 2026-08-09 from the pre-migration issue tracker.\n\nA missing **credential** disables a capability. Only an **invalid config** stops\nthe daemon. \"Forge is a feature, not a requirement.\"\n\nBefore `518a1a0`, an unresolvable forge token did `return 1` in\n`cmd/archied/main.go`, so a chat-only user who never configured GitHub got no\nchat, no gateway, nothing — and under a systemd unit with `Restart=on-failure`\nand no start limit it crash-looped every five seconds with the error scrolling\npast unread. Forge construction now lives in `resolveForge`, shared by the\nprimary forge and every configured identity, and degrades to `forge.NewNoop`\nwith a warning. The identity path had the same defect and was worse: one\nidentity's missing credential killed all the others.\n\nMalformed configuration still fails fast in `configuration.Validate`, well\nbefore this point. That distinction is the whole design.\n\nApply the same reasoning to any future capability credential, LLM keys\nespecially: start, report the capability as unavailable, let the operator see it.\nGuarded by `TestResolveForgeDegradesInsteadOfFailing`.\n\n**Known consequence, tracked separately:** `worktree.Manager` still receives the\nempty token, so pushes fail late rather than at startup.\n\n## Config generation belongs to `archied setup`, not `install.sh`\n\nDecided 2026-07-30 ([#368](https://github.com/samcharles93/archie-core/issues/368)).\nRecovered 2026-08-09 from the pre-migration issue tracker.\n\n`install.sh` must stop generating `config.toml`; `archied setup` owns it. The\ninstaller hand-rolling TOML has already drifted from the schema once: the\ngenerated-config branch hardcoded `key = ARCHIE_GITHUB_TOKEN` and\n`host = ${GITEA_URL}` regardless of the answers given, so choosing Gitea produced\na config naming a token the installer never wrote (archied then exited 1), and\nchoosing GitHub pointed `host` at `gitea.example.com`. `61a5b35` patched this\nwith a `forge_block` shell helper shared by both config paths — that helper is a\n**workaround**, deleted by\n[#72](https://github.com/samcharles93/archie-core/issues/72). The durable fix is\nthat the code writing the config is the code that reads it.\n\nWhy Go and not Python: the installer must run where nothing is installed yet, and\n`python3` with `tomllib` means 3.11+, which is not safe on LTS distros. `archied`\nis already being built two steps earlier.\n\n**Key constraint for the port:** `BurntSushi/toml` does **not** survive a\ndecode/encode round trip with comments intact, and `config.example.toml` carries\ndocumentation users are meant to hand-edit. Decide the write strategy\n([#412](https://github.com/samcharles93/archie-core/issues/412)) before writing\nany prompting code. Do not port a separate `config.yaml`/`auth.yaml` secret\nsplit — Archie already has `secret.SecretRef{engine,key}`, so setup writes the\nreference to TOML and the value to the secret engine.\n" }, { "url": "/dev/architecture/dashboard-agent-tools/", @@ -52,25 +52,25 @@ "url": "/dev/architecture/identity/", "title": "Identity", "section": "Architecture", - "body": "# Identity\n\n**Status:** Approved foundation; lifecycle details are deferred \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nIdentity answers which persistent actor owns or performed an action. It supplies\nstable cross-domain attribution and lifecycle semantics.\n\nIdentity kinds include:\n\n- the Archie system identity, such as `System` or `archied`;\n- agent or bot identities;\n- service-account identities;\n- future user identities.\n\nA user is another kind of identity rather than a separate foundation concept.\n\n## Ownership\n\n`internal/domain/identity` owns:\n\n- immutable canonical `IdentityID` values;\n- identity kind;\n- lifecycle state;\n- ownership and attribution semantics;\n- identity-related commands and events.\n\nDomains may record an identity reference on their own state and events when\nownership or attribution is required. They MUST NOT receive a complete\nper-identity application configuration bundle.\n\nPersona and communication style are separate from identity.\n\nEvery Agent has its own immutable acting `IdentityID`. Agent actions use that\nidentity for ownership and attribution in the same way an organisation records\nwhich user accessed a resource, changed a permission, or performed another\nauditable action.\n\nAgent and Identity remain separate aggregates. Identity supplies the stable\nactor reference; Agent owns assistant behaviour, memory, specialisation,\nconversations, and capability context.\n\nAgent identities MUST NOT be shared between Agents. Automated WorkflowExecutions\nMAY eventually act through a dedicated service-account identity when a specific\nunattended automation requires it. Such use is an explicit execution decision\nand audit principal, not the default for Agents or a substitute for recording\nthe initiating user when one exists.\n\nA Workflow is owned by an IdentityID and executes as its owner by default.\nFuture delegated execution MAY explicitly assign a different `RunAsIdentityID`,\nincluding a user or service-account identity. Ownership, effective execution\nidentity, initiating identity, and delegation provenance remain distinct audit\nfacts.\n\n## Canonical identity\n\nEvery identity has an immutable `IdentityID`. It is the only value used for\ncross-domain ownership, attribution, routing, persistence, commands, and events.\n\nIdentity kind is explicit:\n\n- system;\n- bot;\n- service account;\n- user.\n\nDisplay names are mutable and MUST NOT be used as identifiers. Forge usernames,\nchannel bot names, Git authors, provider account names, and other external\nidentifiers are bindings associated with an identity rather than identity\nitself.\n\n`System` is represented by a real identity and `IdentityID`. The empty string\nMUST NOT retain special meaning as a legacy system identity.\n\nConfiguration refers to identities by `IdentityID` and supplies external\nbindings and capability settings separately. Renaming an identity or changing an\nexternal account MUST NOT change ownership or historical attribution.\n\nSecret-bearing channel bindings remain configuration concerns rather than\nidentity data. In particular, `[chat.telegram].token` is a\n`secret.SecretRef` resolved by the application through the configured secret\nregistry; the older `token_env` field remains a compatibility fallback. Neither\nform changes the identity that owns or performs a chat action.\n\n## Persistence\n\nIdentity records are durable domain state. The Identity domain's repository is\nthe source of truth; infrastructure implements its persistence contract.\n\nConfiguration MAY bootstrap a missing identity through an explicit, audited\ncreation operation and MAY propose runtime capability bindings for an existing\n`IdentityID`. Configuration is not the identity registry.\n\nOmitting an identity from configuration stops assembling the omitted runtime\ncapabilities. It MUST NOT delete the identity record, erase history, or make\nhistorical references unresolvable.\n\nDisabling or retiring an identity requires an explicit Identity-domain command.\nRetired identities remain resolvable for historical attribution. A failed\nexternal binding affects capability availability without destroying or silently\nreplacing the identity.\n\n## Lifecycle\n\nIdentity lifecycle is deliberately small:\n\n- `active`: may participate in runtime composition;\n- `suspended`: deliberately prevented from initiating new work while ownership\n and history remain;\n- `retired`: terminal, unable to initiate work, and permanently retained for\n attribution.\n\nAllowed transitions are:\n\n```text\ncreate -\u003e active\nactive -\u003e suspended\nsuspended -\u003e active\nactive -\u003e retired\nsuspended -\u003e retired\n```\n\n`retired` has no outgoing transition.\n\nCapability health is separate from identity lifecycle. Forge, model, channel,\nworkspace, and other bindings report health independently. An active identity\nmay be partially degraded without becoming suspended or retired. Runtime\nsupervision isolates and restores affected bindings through the safe-change and\nrecovery protocol.\n\n## System identity\n\nArchie has exactly one built-in system identity. It is created during initial\nstore bootstrap, is strictly always active, and cannot be suspended or retired.\nIts `IdentityID` and kind are immutable.\n\nStartup, migration, supervision, remediation, and rollback actions performed by\nthe application use the system identity. The system identity MUST NOT be\ndelegated to individual identities. Every user, bot, service account, or other\nactor mutation records the identity that actually performed it.\n\nSystem capabilities may independently become unhealthy or unavailable without\nchanging the system identity.\n\n## Target placement and contracts\n\nThe Identity domain lives at `internal/domain/identity`.\n\nIt owns:\n\n- `IdentityID`, identity kind, display name, lifecycle, version, and audit\n timestamps;\n- create, rename, suspend, reactivate, and retire commands;\n- corresponding lifecycle events;\n- the repository contract required for durable identity records;\n- lookup of current and historical identities.\n\nExternal account bindings and capability settings remain with the domains that\nuse them and reference `IdentityID`.\n\n## Migration constraints\n\nMigration from the current string model MUST:\n\n- bootstrap the permanent system identity;\n- assign stable IDs to configured identities without losing their names;\n- replace empty-string legacy ownership with the system identity;\n- migrate tasks and sessions to canonical identity references;\n- include identity where task uniqueness and transport deduplication require\n independent ownership;\n- route container RPC through the task owner's capability bindings;\n- retain historical resolution after rename, suspension, or retirement;\n- remove identity-string equality from authentication or access semantics.\n\nThis completes the foundation required to restructure the current Identity\nbehaviour. Exact storage schemas and Go method signatures belong to\nimplementation design, not this architecture review.\n\n## Lifecycle\n\nIdentity lifecycle is deliberately small:\n\n- `active`: may participate in runtime composition;\n- `suspended`: deliberately prevented from initiating new work while ownership\n and history remain;\n- `retired`: terminal, unable to initiate work, and permanently retained for\n attribution.\n\nAllowed transitions are:\n\n```text\ncreate -\u003e active\nactive -\u003e suspended\nsuspended -\u003e active\nactive -\u003e retired\nsuspended -\u003e retired\n```\n\n`retired` has no outgoing transition.\n\nCapability health is separate from identity lifecycle. Forge, model, channel,\nworkspace, and other bindings report health independently. An active identity\nmay be partially degraded without becoming suspended or retired. Runtime\nsupervision isolates and restores affected bindings through the safe-change and\nrecovery protocol.\n\n## Explicit non-responsibilities\n\nIdentity is not authentication and is not access control.\n\nThe current architecture does not require authentication or authorization. Those\ncapabilities MAY be introduced later if deployment or product needs justify\nthem. They MUST remain separate from the identity model.\n\nAn identity reference therefore proves attribution within Archie's trusted\nsystem model; it does not by itself prove credentials or permission.\n\n## Per-identity configuration\n\nValues selected for an identity remain external configuration values. At\ncomposition time they are split into the runtime settings owned by the affected\ndomains and correlated by identity reference.\n\nThe existing `IdentityConfig` aggregate MUST be dissolved. Forge accounts,\nrepositories, models, providers, workspace behaviour, polling, budgets,\nnotifications, and transport namespaces retain their respective owners.\n\n## Audit\n\nConfiguration changes and other state changes are actions attributed to an\nidentity. System-initiated changes use the system identity. Their audit records\nMUST preserve the acting identity, the target, and the resulting change.\n\nThe command ownership and persistence mechanism for configuration changes is a\nseparate configuration-management decision.\n\n## Current implementation\n\nIdentity is not currently implemented as a domain. It is a collection of string\nfields and process-local associations:\n\n- `config.IdentityConfig.Name` is the daemon routing key.\n- `config.IdentityConfig.BotUser` is the external forge and Git author name.\n- `daemon.IdentityRunner` bundles the configured name with a forge client,\n worktree manager, repository list, configuration subset, logger, and polling\n goroutine.\n- `store.Task.Identity` persists the configured name on tasks.\n- NATS task messages copy the same configured name.\n- gateway routing accepts an identity name and uses it to select a repository\n profile.\n- gateway sessions persist `BotUser`, not the configured identity name.\n\nThere is no identity registry, identity record, identity lifecycle state,\nidentity persistence, or identity command/event model. Removing an identity from\nconfiguration makes existing task ownership unresolvable.\n\nAn empty identity string selects the legacy single-identity path. This gives the\nempty string behavioural meaning rather than representing a real system\nidentity.\n\n## Current enforcement and isolation\n\n## Withheld judgement verbs\n\n`approve`, `reject`, `abandon` and `archive` are not exposed to an agent. An agent\nthat can approve can approve its own work, and the one control this surface exists\nto keep is a human accepting it.\n\nThe constraint is attribution, not capability: a task action records the acting\nidentity and the authorising principal, so exposing the verbs requires that an\nagent's action be recorded as an agent's and the authority it used recorded\nseparately. Until a surface carries both, the verbs stay withheld. This is the\nreason the four verbs are absent from the dashboard's in-browser tools, and it is\nwhy releasing them is a change to this boundary rather than a change to the tools.\n\n\nThe current implementation uses identity equality as an authorization check for\nchat task approval and cancellation. This conflicts with the approved rule that\nidentity is attribution rather than authentication or access control and must be\nreassigned to an appropriate task-ownership or future access policy.\n\nFocused tests verify that:\n\n- a task resolves the forge client and repository list associated with its\n configured identity name;\n- cross-identity repository profiles do not leak;\n- chat task creation propagates the selected identity;\n- task persistence retains the identity string;\n- chat task control rejects a different identity string.\n\n## Current hazards\n\n- SQLite task uniqueness is `(owner, repo, issue_number)` and excludes identity.\n Two identities discovering the same forge issue cannot own distinct task\n records.\n- NATS deduplication uses `owner/repo/issue` and excludes identity, so discovery\n by a second identity can be discarded as a duplicate.\n- Container-mode forge and worktree RPC servers are wired to the root clients,\n not the task owner's clients. The source documents this as an unresolved\n identity leak.\n- The shared task queue claims the oldest task without identity partitioning and\n relies on later string lookup to recover the correct runner.\n- Sessions use forge bot usernames where tasks use configured identity names, so\n there is no canonical cross-domain identity reference.\n- Identity lifecycle is process lifetime only; there is no disabled, degraded,\n retired, or unavailable state and no audit history.\n\nThe focused identity tests pass. Broader daemon and NATS suites could not open\nembedded listener ports in the current sandbox; their failures occurred before\nidentity behaviour executed.\n\n## Three-layer identity model\n\nAgreed 2026-07-30; the frame for SOUL\n([#68](https://github.com/samcharles93/archie-core/issues/68)) and the curator\n([#435](https://github.com/samcharles93/archie-core/issues/435)).\nRecovered 2026-08-09 from the pre-migration issue tracker.\n\n**Layer 1 — invariants.** Instruction precedence, core rules, and the `\u003ctools\u003e`\nand `\u003cenv\u003e` blocks live in `internal/gateway/templates/archie.md.tpl` and are\nunreachable at runtime by anyone.\n\n**Layer 2 — SOUL.** User-authored identity: agent name, register, warmth.\nEditable without a rebuild.\n\n**Enforcing the Layer 1 / Layer 2 boundary.** SOUL is rendered as the\n`Persona` field of `SystemPromptConfig` (`internal/gateway/prompt.go`) into a\n`\u003csoul purpose=\"identity_and_style\" trust=\"data\"\u003e` block, XML-escaped through\nthe same `xml` template helper used for tool and env metadata, and placed\n*before* `\u003cinstruction_precedence\u003e` in `archie.md.tpl`. Escaping means SOUL\ntext can never forge a live `\u003ccore_rules\u003e`, `\u003cinstruction_precedence\u003e`,\n`\u003ctools\u003e` or `\u003cenv\u003e` tag -- an attempt renders as inert escaped text\n(`\u0026lt;core_rules\u0026gt;...`), and `\u003cinstruction_precedence\u003e` explicitly tells the\nmodel the `\u003csoul\u003e` block is reference data, not an authority. This is\nguarded by `TestBuildSystemPromptSoulCannotOverrideInvariants` in\n`internal/gateway/prompt_test.go`, which renders a hostile SOUL that attempts\nto countermand `core_rules` and asserts the real invariant tags stay singular\nand their text stays intact. Keep this test in sync if the template's escaping\nor block structure changes -- do not relax it to make a future SOUL feature\n(e.g. curator-proposed edits) fit.\n\n**Layer 3 — representation.** Curator-derived knowledge about the user. It may\nonly **propose** changes to SOUL and never apply them. If derived conclusions can\nsilently rewrite tone, personality drifts and the user loses the control SOUL\nexists to give them. A proposal queue also makes the visibility requirement fall\nout for free, since pending conclusions are inherently reviewable.\n\n**Why SOUL comes first:** tone currently lives in Go string constants\n(`DefaultPersonas` in `internal/gateway/persona.go`), so fixing a rude reply on\n2026-07-29 required editing Go and rebuilding. SOUL is small, fixes a real\ndefect, and defines the boundary the curator must respect.\n" + "body": "# Identity\n\n**Status:** Approved foundation; lifecycle details are deferred \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nIdentity answers which persistent actor owns or performed an action. It supplies\nstable cross-domain attribution and lifecycle semantics.\n\nIdentity kinds include:\n\n- the Archie system identity, such as `System` or `archied`;\n- agent or bot identities;\n- service-account identities;\n- future user identities.\n\nA user is another kind of identity rather than a separate foundation concept.\n\n## Ownership\n\n`internal/domain/identity` owns:\n\n- immutable canonical `IdentityID` values;\n- identity kind;\n- lifecycle state;\n- ownership and attribution semantics;\n- identity-related commands and events.\n\nDomains may record an identity reference on their own state and events when\nownership or attribution is required. They MUST NOT receive a complete\nper-identity application configuration bundle.\n\nPersona and communication style are separate from identity.\n\nEvery Agent has its own immutable acting `IdentityID`. Agent actions use that\nidentity for ownership and attribution in the same way an organisation records\nwhich user accessed a resource, changed a permission, or performed another\nauditable action.\n\nAgent and Identity remain separate aggregates. Identity supplies the stable\nactor reference; Agent owns assistant behaviour, memory, specialisation,\nconversations, and capability context.\n\nAgent identities MUST NOT be shared between Agents. Automated WorkflowExecutions\nMAY eventually act through a dedicated service-account identity when a specific\nunattended automation requires it. Such use is an explicit execution decision\nand audit principal, not the default for Agents or a substitute for recording\nthe initiating user when one exists.\n\nA Workflow is owned by an IdentityID and executes as its owner by default.\nFuture delegated execution MAY explicitly assign a different `RunAsIdentityID`,\nincluding a user or service-account identity. Ownership, effective execution\nidentity, initiating identity, and delegation provenance remain distinct audit\nfacts.\n\n## Canonical identity\n\nEvery identity has an immutable `IdentityID`. It is the only value used for\ncross-domain ownership, attribution, routing, persistence, commands, and events.\n\nIdentity kind is explicit:\n\n- system;\n- bot;\n- service account;\n- user.\n\nDisplay names are mutable and MUST NOT be used as identifiers. Forge usernames,\nchannel bot names, Git authors, provider account names, and other external\nidentifiers are bindings associated with an identity rather than identity\nitself.\n\n`System` is represented by a real identity and `IdentityID`. The empty string\nMUST NOT retain special meaning as a legacy system identity.\n\nConfiguration refers to identities by `IdentityID` and supplies external\nbindings and capability settings separately. Renaming an identity or changing an\nexternal account MUST NOT change ownership or historical attribution.\n\nSecret-bearing channel bindings remain configuration concerns rather than\nidentity data. In particular, `[chat.telegram].token` is a\n`secret.SecretRef` resolved by the application through the configured secret\nregistry; the older `token_env` field remains a compatibility fallback. Neither\nform changes the identity that owns or performs a chat action.\n\n## Persistence\n\nIdentity records are durable domain state. The Identity domain's repository is\nthe source of truth; infrastructure implements its persistence contract.\n\nConfiguration MAY bootstrap a missing identity through an explicit, audited\ncreation operation and MAY propose runtime capability bindings for an existing\n`IdentityID`. Configuration is not the identity registry.\n\nOmitting an identity from configuration stops assembling the omitted runtime\ncapabilities. It MUST NOT delete the identity record, erase history, or make\nhistorical references unresolvable.\n\nDisabling or retiring an identity requires an explicit Identity-domain command.\nRetired identities remain resolvable for historical attribution. A failed\nexternal binding affects capability availability without destroying or silently\nreplacing the identity.\n\n## Lifecycle\n\nIdentity lifecycle is deliberately small:\n\n- `active`: may participate in runtime composition;\n- `suspended`: deliberately prevented from initiating new work while ownership\n and history remain;\n- `retired`: terminal, unable to initiate work, and permanently retained for\n attribution.\n\nAllowed transitions are:\n\n```text\ncreate -\u003e active\nactive -\u003e suspended\nsuspended -\u003e active\nactive -\u003e retired\nsuspended -\u003e retired\n```\n\n`retired` has no outgoing transition.\n\nCapability health is separate from identity lifecycle. Forge, model, channel,\nworkspace, and other bindings report health independently. An active identity\nmay be partially degraded without becoming suspended or retired. Runtime\nsupervision isolates and restores affected bindings through the safe-change and\nrecovery protocol.\n\n## System identity\n\nArchie has exactly one built-in system identity. It is created during initial\nstore bootstrap, is strictly always active, and cannot be suspended or retired.\nIts `IdentityID` and kind are immutable.\n\nStartup, migration, supervision, remediation, and rollback actions performed by\nthe application use the system identity. The system identity MUST NOT be\ndelegated to individual identities. Every user, bot, service account, or other\nactor mutation records the identity that actually performed it.\n\nSystem capabilities may independently become unhealthy or unavailable without\nchanging the system identity.\n\n## Target placement and contracts\n\nThe Identity domain lives at `internal/domain/identity`.\n\nIt owns:\n\n- `IdentityID`, identity kind, display name, lifecycle, version, and audit\n timestamps;\n- create, rename, suspend, reactivate, and retire commands;\n- corresponding lifecycle events;\n- the repository contract required for durable identity records;\n- lookup of current and historical identities.\n\nExternal account bindings and capability settings remain with the domains that\nuse them and reference `IdentityID`.\n\n## Migration constraints\n\nMigration from the current string model MUST:\n\n- bootstrap the permanent system identity;\n- assign stable IDs to configured identities without losing their names;\n- replace empty-string legacy ownership with the system identity;\n- migrate tasks and sessions to canonical identity references;\n- include identity where task uniqueness and transport deduplication require\n independent ownership;\n- route container RPC through the task owner's capability bindings;\n- retain historical resolution after rename, suspension, or retirement;\n- remove identity-string equality from authentication or access semantics.\n\nThis completes the foundation required to restructure the current Identity\nbehaviour. Exact storage schemas and Go method signatures belong to\nimplementation design, not this architecture review.\n\n## Lifecycle\n\nIdentity lifecycle is deliberately small:\n\n- `active`: may participate in runtime composition;\n- `suspended`: deliberately prevented from initiating new work while ownership\n and history remain;\n- `retired`: terminal, unable to initiate work, and permanently retained for\n attribution.\n\nAllowed transitions are:\n\n```text\ncreate -\u003e active\nactive -\u003e suspended\nsuspended -\u003e active\nactive -\u003e retired\nsuspended -\u003e retired\n```\n\n`retired` has no outgoing transition.\n\nCapability health is separate from identity lifecycle. Forge, model, channel,\nworkspace, and other bindings report health independently. An active identity\nmay be partially degraded without becoming suspended or retired. Runtime\nsupervision isolates and restores affected bindings through the safe-change and\nrecovery protocol.\n\n## Explicit non-responsibilities\n\nIdentity is not authentication and is not access control.\n\nThe current architecture does not require authentication or authorization. Those\ncapabilities MAY be introduced later if deployment or product needs justify\nthem. They MUST remain separate from the identity model.\n\nAn identity reference therefore proves attribution within Archie's trusted\nsystem model; it does not by itself prove credentials or permission.\n\n## Per-identity configuration\n\nValues selected for an identity remain external configuration values. At\ncomposition time they are split into the runtime settings owned by the affected\ndomains and correlated by identity reference.\n\nThe existing `IdentityConfig` aggregate MUST be dissolved. Forge accounts,\nrepositories, models, providers, workspace behaviour, polling, budgets,\nnotifications, and transport namespaces retain their respective owners.\n\n## Audit\n\nConfiguration changes and other state changes are actions attributed to an\nidentity. System-initiated changes use the system identity. Their audit records\nMUST preserve the acting identity, the target, and the resulting change.\n\nThe command ownership and persistence mechanism for configuration changes is a\nseparate configuration-management decision.\n\n## Current implementation\n\nIdentity is not currently implemented as a domain. It is a collection of string\nfields and process-local associations:\n\n- `config.IdentityConfig.Name` is the daemon routing key.\n- `config.IdentityConfig.BotUser` is the external forge and Git author name.\n- `daemon.IdentityRunner` bundles the configured name with a forge client,\n worktree manager, repository list, configuration subset, logger, and polling\n goroutine.\n- `store.Task.Identity` persists the configured name on tasks.\n- NATS task messages copy the same configured name.\n- gateway routing accepts an identity name and uses it to select a repository\n profile.\n- gateway sessions persist `BotUser`, not the configured identity name.\n\nThere is no identity registry, identity record, identity lifecycle state,\nidentity persistence, or identity command/event model. Removing an identity from\nconfiguration makes existing task ownership unresolvable.\n\nAn empty identity string selects the legacy single-identity path. This gives the\nempty string behavioural meaning rather than representing a real system\nidentity.\n\n## Current enforcement and isolation\n\n## Withheld judgement verbs\n\n`approve`, `reject`, `abandon` and `archive` are not exposed to an agent. An agent\nthat can approve can approve its own work, and the one control this surface exists\nto keep is a human accepting it.\n\nThe constraint is attribution, not capability: a task action records the acting\nidentity and the authorising principal, so exposing the verbs requires that an\nagent's action be recorded as an agent's and the authority it used recorded\nseparately. Until a surface carries both, the verbs stay withheld. This is the\nreason the four verbs are absent from the dashboard's in-browser tools, and it is\nwhy releasing them is a change to this boundary rather than a change to the tools.\n\n\nThe current implementation uses identity equality as an authorization check for\nchat task approval and cancellation. This conflicts with the approved rule that\nidentity is attribution rather than authentication or access control and must be\nreassigned to an appropriate task-ownership or future access policy.\n\nFocused tests verify that:\n\n- a task resolves the forge client and repository list associated with its\n configured identity name;\n- cross-identity repository profiles do not leak;\n- chat task creation propagates the selected identity;\n- task persistence retains the identity string;\n- chat task control rejects a different identity string.\n\n## Current hazards\n\n- Task uniqueness is `(owner, repo, issue_number)` and excludes identity.\n Two identities discovering the same forge issue cannot own distinct task\n records.\n- NATS deduplication uses `owner/repo/issue` and excludes identity, so discovery\n by a second identity can be discarded as a duplicate.\n- Container-mode forge and worktree RPC servers are wired to the root clients,\n not the task owner's clients. The source documents this as an unresolved\n identity leak.\n- The shared task queue claims the oldest task without identity partitioning and\n relies on later string lookup to recover the correct runner.\n- Sessions use forge bot usernames where tasks use configured identity names, so\n there is no canonical cross-domain identity reference.\n- Identity lifecycle is process lifetime only; there is no disabled, degraded,\n retired, or unavailable state and no audit history.\n\nThe focused identity tests pass. Broader daemon and NATS suites could not open\nembedded listener ports in the current sandbox; their failures occurred before\nidentity behaviour executed.\n\n## Three-layer identity model\n\nAgreed 2026-07-30; the frame for SOUL\n([#68](https://github.com/samcharles93/archie-core/issues/68)) and the curator\n([#435](https://github.com/samcharles93/archie-core/issues/435)).\nRecovered 2026-08-09 from the pre-migration issue tracker.\n\n**Layer 1 — invariants.** Instruction precedence, core rules, and the `\u003ctools\u003e`\nand `\u003cenv\u003e` blocks live in `internal/gateway/templates/archie.md.tpl` and are\nunreachable at runtime by anyone.\n\n**Layer 2 — SOUL.** User-authored identity: agent name, register, warmth.\nEditable without a rebuild.\n\n**Enforcing the Layer 1 / Layer 2 boundary.** SOUL is rendered as the\n`Persona` field of `SystemPromptConfig` (`internal/gateway/prompt.go`) into a\n`\u003csoul purpose=\"identity_and_style\" trust=\"data\"\u003e` block, XML-escaped through\nthe same `xml` template helper used for tool and env metadata, and placed\n*before* `\u003cinstruction_precedence\u003e` in `archie.md.tpl`. Escaping means SOUL\ntext can never forge a live `\u003ccore_rules\u003e`, `\u003cinstruction_precedence\u003e`,\n`\u003ctools\u003e` or `\u003cenv\u003e` tag -- an attempt renders as inert escaped text\n(`\u0026lt;core_rules\u0026gt;...`), and `\u003cinstruction_precedence\u003e` explicitly tells the\nmodel the `\u003csoul\u003e` block is reference data, not an authority. This is\nguarded by `TestBuildSystemPromptSoulCannotOverrideInvariants` in\n`internal/gateway/prompt_test.go`, which renders a hostile SOUL that attempts\nto countermand `core_rules` and asserts the real invariant tags stay singular\nand their text stays intact. Keep this test in sync if the template's escaping\nor block structure changes -- do not relax it to make a future SOUL feature\n(e.g. curator-proposed edits) fit.\n\n**Layer 3 — representation.** Curator-derived knowledge about the user. It may\nonly **propose** changes to SOUL and never apply them. If derived conclusions can\nsilently rewrite tone, personality drifts and the user loses the control SOUL\nexists to give them. A proposal queue also makes the visibility requirement fall\nout for free, since pending conclusions are inherently reviewable.\n\n**Why SOUL comes first:** tone currently lives in Go string constants\n(`DefaultPersonas` in `internal/gateway/persona.go`), so fixing a rude reply on\n2026-07-29 required editing Go and rebuilding. SOUL is small, fixes a real\ndefect, and defines the boundary the curator must respect.\n" }, { "url": "/dev/architecture/messaging-and-work-intake/", "title": "Messaging and Work Intake", "section": "Architecture", - "body": "# Messaging and Work Intake\n\n**Status:** Current state researched; foundation decisions in progress \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie is a personal assistant and general agentic system. Its interactions\ninclude conversation, questions, notes, reminders, goals, message handling,\ntroubleshooting, infrastructure operations, server management, source changes,\nand open-ended future capabilities.\n\nA message to an agent is therefore not inherently a work request, and invoking\nan agent is not inherently a WorkflowExecution.\n\nMessaging and work intake are separate from the Agent System's durable workflow\nexecution model:\n\n- messaging preserves interactions with people and external systems;\n- an agent turn interprets and responds to an interaction using its available\n capabilities;\n- work intake handles the optional promotion of an interaction into durable,\n workflow-backed work;\n- the Agent System owns Workflow definitions and creates WorkflowExecutions.\n\nForge issues, Jira issues, Telegram messages, emails, webhooks, and future\nchannels remain peer external message or artifact sources. None becomes an\nexecution model merely because it can lead to work.\n\n## Confirmed boundary\n\nWork intake MUST NOT create a WorkflowExecution directly.\n\nInbound interactions normally route to the Agent selected by the channel\nbinding. The selected Agent retains its own memory, user knowledge, conversation\ncontinuity, specialisation, and capability context. This continuity is\nindependent of the underlying model or provider.\n\nEach selected Agent acts through its own immutable IdentityID. Interaction and\nresulting action records preserve both that acting identity and the initiating\nuser identity when one exists.\n\nAgent memory is private by default. Interaction context MAY additionally use\nuser-wide memory and intentionally global shared memory, but another Agent's\nagent-wide memory is not part of the selected Agent's context.\n\nMultiple users may interact with the same Agent. The channel binding and inbound\nmessage MUST resolve both AgentID and initiating User IdentityID before\nconversation or memory context is loaded. Sharing an Agent MUST NOT implicitly\nshare one user's private memory with another user.\n\nAn interaction may assemble memory from four scopes: global shared, the selected\nAgent's agent-wide memory, the initiating user's authorized user-wide memory,\nand the private Agent-user relationship memory addressed by both IDs.\n\n## Conversation identity\n\nEvery conversation is identified by the complete tuple:\n\n```text\nAgentID\n+ UserIdentityID\n+ ChannelBindingID\n+ ExternalConversationID\n+ ThreadID\n```\n\n`ThreadID` has an explicit empty value for channels without threads. No element\nof this key may be replaced by a display name, configured bot username, channel\ntype, or other mutable label.\n\nAgent and user memory continue across conversations according to their memory\nscope. Immediate conversation history and delivery correlation remain isolated\nto the identified channel conversation or thread. Moving between Telegram,\nemail, or another channel does not create a new Agent or user, but it does\ncreate a distinct conversation unless an explicit linking operation relates\nthem.\n\nConversation and message events support projections for channel-entry metrics,\nuse cases, volumes, outcomes, latency, capability usage, and other product or\noperational analysis. Metrics are derived read models; they MUST NOT become\nmutable counters embedded in the conversation aggregate or change message\nrouting semantics.\n\n## Canonical messages\n\nEvery inbound, assistant, tool-call, and tool-result message has an immutable\napplication-generated MessageID. Platform identifiers are external correlation,\nnot substitutes for the canonical ID.\n\nMessages are addressable because an interaction is more than text. A message may\ncontain assistant content, reasoning data subject to its retention policy, one\nor more tool calls, a tool result with authoritative execution metadata,\nattachments, reply relationships, edits, or other typed content. Stable\nMessageIDs also allow sessions to branch from an exact prior point.\n\nThe canonical session and message implementation must supply:\n\n- application-generated stable message IDs;\n- user, assistant, and tool roles;\n- assistant tool calls and correlated tool-result messages;\n- authoritative tool-result status, timing, error, truncation, and size\n metadata;\n- session lifecycle and active-request state;\n- session-to-agent-instance and parent-session lineage;\n- durable SQLite round trips and timestamp validation.\n\nThese semantics must use the confirmed Agent, user, channel-binding, and\nconversation ownership model.\n\nThe canonical message store MUST preserve messages as immutable records and\nrepresent later edits, deletions, and branches through related records or\nevents.\n\nArchie requires exact branch-point correlation using stable MessageIDs.\n\n## Conversation branches\n\nA branch is a continuation of a previous conversation at an exact message. A\nchild conversation records:\n\n```text\nParentConversationID\nForkMessageID\n```\n\nMessages remain an append-only linear sequence within each conversation. The\nchild's effective initial context is the parent's history through\n`ForkMessageID`; messages after that point in the parent are not inherited.\n\nAfter the fork, parent and child are isolated:\n\n- child messages, tool calls, tool results, capability actions, and errors do\n not appear in the parent conversation;\n- later parent messages do not silently enter the child;\n- returning to the parent resumes its unchanged history;\n- the child may itself be branched using the same rules;\n- branch lineage remains queryable for navigation, audit, and metrics.\n\nThis supports building substantial context about a subject and then performing\none or more contextual subtasks without polluting the original conversation. For\nexample, a user may branch from a project discussion, create Jira issues in the\nchild using inherited context, and then return to the project discussion without\nadding the Jira tool transcript to the parent.\n\nBranching does not copy mutable message rows. History is resolved through the\nimmutable parent conversation and fork MessageID, followed by the child's own\nmessage sequence.\n\nBranch isolation applies to conversation history, not to Agent learning or\nmemory. A memory action performed in a branch has exactly the same semantics as\nthe same action performed in any other conversation. It writes to its selected\nglobal, agent-wide, user-wide, or Agent-user relationship scope.\n\nMemory provenance MAY retain the source ConversationID and MessageIDs for\nexplanation and audit. Retrieval and effect are determined by memory scope and\naccess rules, not by the conversation from which the memory originated.\nReturning to a parent does not insert the child's tool transcript into the\nparent history, but scoped memories learned in the child remain available to\nfuture retrieval wherever that scope is visible.\n\nChanging sessions or branching therefore controls immediate conversational\ncontext without preventing the Agent from learning durable knowledge.\n\n## Target ownership\n\nThe Messaging domain lives at `internal/domain/messaging`. It owns:\n\n- canonical Messages and typed message content;\n- Conversations, branches, and lineage;\n- channel bindings and external source correlation;\n- replies, acknowledgements, and outbound delivery attempts;\n- message and conversation lifecycle events;\n- domain-defined repository and delivery service contracts;\n- projections required for conversation navigation and metrics.\n\nWork intake is a separate cohesive domain at `internal/domain/workintake`. It\nowns admission, validation, deterministic routing, and accepted work requests\nfor the optional transition into durable workflow-backed execution.\n\nTelegram, email, webhook, forge, Jira, and future messaging systems are\ninfrastructure adapters implementing Messaging contracts. They are users of the\ndomain; they do not own Messages, Conversations, work admission, or\nWorkflowExecution semantics.\n\nThe Agent decides whether an ordinary interaction is answered directly, uses a\ncapability, changes or retrieves Agent-owned information, or proposes durable\nworkflow-backed work.\n\nExplicitly configured automation MAY enter work intake without a conversational\nAgent turn when the external trigger and admission rule already unambiguously\nrequest durable work. This avoids spending an LLM turn to rediscover a\ndeterministic routing decision.\n\nWhen an interaction requires durable workflow-backed execution:\n\n1. a channel adapter produces a channel-neutral inbound message;\n2. the acting agent handles or interprets the interaction;\n3. work intake validates, admits, and routes a proposed work request;\n4. work intake emits an accepted work request with its source correlation,\n acting identity, requested outcome, inputs, and routing evidence;\n5. the Agent System consumes that request, selects a specific Workflow version,\n and creates the WorkflowExecution.\n\nThe accepted work request is a cross-domain handoff, not an alternate execution\naggregate. The Agent System is the sole authority that creates a valid\nWorkflowExecution.\n\nAn interaction MAY instead be completed directly by an agent turn, delegated to\na tool or capability, recorded as a note or reminder, answered conversationally,\nor retained for later context. Those paths MUST NOT require a Workflow or\nWorkflowExecution.\n\nA Workflow MAY add reusable, versioned structure to any of those behaviours.\nScheduled personal-assistant routines, message triage, reminders, infrastructure\noperations, and other capability sequences are valid Workflow definitions. The\ndistinction is whether durable structured execution is useful, not whether the\nsubject originated from a forge.\n\n## Canonical execution language\n\n- **Workflow**: reusable, versioned behaviour definition.\n- **WorkflowExecution**: durable execution of a specific Workflow version.\n- **WorkflowStep**: a defined operation in a Workflow.\n- **StepExecution**: the recorded execution and outcome of a WorkflowStep.\n- **Attempt**: a retry within the same WorkflowExecution.\n\nExternal issues, messages, requests, goals, and notes are not synonyms for these\nconcepts.\n\n## Current implementation\n\nCurrent intake is fragmented:\n\n- Telegram, email, and webhook adapters translate payloads into\n `gateway.Message`, while an unused richer `MessageEvent` contract exists\n alongside it.\n- `gateway.Router` combines local channel commands, conversational LLM routing,\n and direct task lifecycle operations.\n- Telegram is the only channel with production LLM and durable conversation\n wiring. Email and webhook free text currently have no LLM responder.\n- Forge polling bypasses the gateway and directly enqueues store rows or NATS\n task messages.\n- Chat `/spawn` directly creates a `store.Task` and invents a synthetic forge\n issue number to satisfy the existing persistence key.\n- Forge replies and chat approval commands implement separate waiting-human\n paths.\n- Message delivery, acknowledgement, retry, deduplication, and source\n correlation are platform-specific side effects rather than one durable model.\n- `store.Task` collapses an external source reference and durable execution\n state.\n\n## Intake provenance\n\nA task's origin determines which enqueue path created it, though every origin\nconverges on the same `tasks` table and the same `Route`/`Run` lifecycle once\nqueued.\n\n- Forge-sourced work -- discovered by polling or, in single-identity\n deployments, delivered by the forge webhook receiver (`internal/forge/webhook`)\n -- enqueues through the same `workintake.TaskEnvelope` and `PublishTask` path.\n `TaskEnvelope.IdempotencyKey` is keyed on `owner/repo/number` and not on the\n delivery source, so a webhook-delivered issue and a later poll of the same\n issue dedup through `PublishUnique` instead of double-enqueuing.\n- Chat-spawned and playbook-binding-dispatched work enqueues through\n `EnqueueChatTask`/`EnqueueBindingTask` (`internal/store`), stamped with\n `binding_id`/`binding_version` for provenance.\n\nWebhook intake is opt-in per deployment (`Forge.Intake` = `poll` (default),\n`webhook`, or `both`) and single-identity only: a config naming\n`webhook`/`both` alongside `[[identities]]`, or setting intake on a\n`[identities.forge]` entry, is rejected at validation rather than started with\nthe setting ignored. One receiver binds one secret and one dispatch predicate,\nso it cannot judge a second identity's events by the right rules. A\nmulti-identity deployment polls per identity until per-identity intake lands.\nThe decided contract is `docs/prds/event-sources-and-reactions.md`; the binding\nmodel and its threat model are `docs/architecture/bindings.md`.\n\n## Current hazards\n\n- Treating every agent interaction as a work request would remove Archie's\n personal-assistant role and force conversation and immediate capability use\n through an inappropriate workflow lifecycle.\n- Treating every accepted work request as a WorkflowExecution would let intake\n or channel code select versions and construct invalid execution state outside\n the Agent System.\n- Source identity is incomplete: sessions use configured bot usernames, tasks\n use identity strings, and external message IDs are generally absent.\n- SQLite and NATS deduplication are based on forge coordinates rather than a\n channel-neutral source-message reference.\n- Replies and acknowledgements have no durable delivery-attempt lifecycle, so\n partial success and retry behaviour differ by adapter.\n- Production code has two competing channel-neutral message contracts.\n- The existing Archie session implementation lacks the required tool-call\n semantics and exact branch lineage and MUST be brought to the canonical\n contract.\n\n## Decisions still required\n\n- the cohesive owner and final location of messaging behaviour;\n- the cohesive owner and final location of work-intake admission and routing;\n- the canonical inbound message, conversation, and source-correlation model;\n- the boundary between an agent turn, direct capability use, and a proposed\n durable work request;\n- the exact relationship between an Agent, its acting IdentityID, its user, and\n its channel bindings;\n- outbound response, acknowledgement, delivery-attempt, retry, deduplication,\n and failure semantics;\n- the smallest accepted-work-request contract consumed by the Agent System;\n- migration of forge polling, replies, chat commands, email, webhook, Telegram,\n and Jira integrations.\n\n## Non-goal: semantic search over chat messages\n\nSemantic/vector search over chat messages is an **explicit non-goal** until usage\ndata shows a real need.\n\nMessage search is lexical only: session-scoped SQLite FTS5 queries paged via\n`MessageQuery{Query,Limit,Offset}` → `MessagePage`. Do not add embeddings\nconfiguration or vector columns to message records.\n\nThe rationale is cost without a demonstrated use case. Measured 2026-08-03 with\n`embeddinggemma:300m` — note this was never an infrastructure problem, the model\nwas already pulled and `ai-sdk/provider/ollama` already has `embed.go`:\n\n- 121 ms median warm per message on the write path, 12.5 s cold;\n- 768 dims = 3072 bytes per vector, roughly 15× a typical message payload;\n- chronological reads would carry vector data they do not use on the hot path\n of every turn;\n- similarity search requires an explicit indexing and retention design.\n\nIf this is revisited, vectors belong in a sibling table so chronological reads\nnever load them.\n" + "body": "# Messaging and Work Intake\n\n**Status:** Current state researched; foundation decisions in progress \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie is a personal assistant and general agentic system. Its interactions\ninclude conversation, questions, notes, reminders, goals, message handling,\ntroubleshooting, infrastructure operations, server management, source changes,\nand open-ended future capabilities.\n\nA message to an agent is therefore not inherently a work request, and invoking\nan agent is not inherently a WorkflowExecution.\n\nMessaging and work intake are separate from the Agent System's durable workflow\nexecution model:\n\n- messaging preserves interactions with people and external systems;\n- an agent turn interprets and responds to an interaction using its available\n capabilities;\n- work intake handles the optional promotion of an interaction into durable,\n workflow-backed work;\n- the Agent System owns Workflow definitions and creates WorkflowExecutions.\n\nForge issues, Jira issues, Telegram messages, emails, webhooks, and future\nchannels remain peer external message or artifact sources. None becomes an\nexecution model merely because it can lead to work.\n\n## Confirmed boundary\n\nWork intake MUST NOT create a WorkflowExecution directly.\n\nInbound interactions normally route to the Agent selected by the channel\nbinding. The selected Agent retains its own memory, user knowledge, conversation\ncontinuity, specialisation, and capability context. This continuity is\nindependent of the underlying model or provider.\n\nEach selected Agent acts through its own immutable IdentityID. Interaction and\nresulting action records preserve both that acting identity and the initiating\nuser identity when one exists.\n\nAgent memory is private by default. Interaction context MAY additionally use\nuser-wide memory and intentionally global shared memory, but another Agent's\nagent-wide memory is not part of the selected Agent's context.\n\nMultiple users may interact with the same Agent. The channel binding and inbound\nmessage MUST resolve both AgentID and initiating User IdentityID before\nconversation or memory context is loaded. Sharing an Agent MUST NOT implicitly\nshare one user's private memory with another user.\n\nAn interaction may assemble memory from four scopes: global shared, the selected\nAgent's agent-wide memory, the initiating user's authorized user-wide memory,\nand the private Agent-user relationship memory addressed by both IDs.\n\n## Conversation identity\n\nEvery conversation is identified by the complete tuple:\n\n```text\nAgentID\n+ UserIdentityID\n+ ChannelBindingID\n+ ExternalConversationID\n+ ThreadID\n```\n\n`ThreadID` has an explicit empty value for channels without threads. No element\nof this key may be replaced by a display name, configured bot username, channel\ntype, or other mutable label.\n\nAgent and user memory continue across conversations according to their memory\nscope. Immediate conversation history and delivery correlation remain isolated\nto the identified channel conversation or thread. Moving between Telegram,\nemail, or another channel does not create a new Agent or user, but it does\ncreate a distinct conversation unless an explicit linking operation relates\nthem.\n\nConversation and message events support projections for channel-entry metrics,\nuse cases, volumes, outcomes, latency, capability usage, and other product or\noperational analysis. Metrics are derived read models; they MUST NOT become\nmutable counters embedded in the conversation aggregate or change message\nrouting semantics.\n\n## Canonical messages\n\nEvery inbound, assistant, tool-call, and tool-result message has an immutable\napplication-generated MessageID. Platform identifiers are external correlation,\nnot substitutes for the canonical ID.\n\nMessages are addressable because an interaction is more than text. A message may\ncontain assistant content, reasoning data subject to its retention policy, one\nor more tool calls, a tool result with authoritative execution metadata,\nattachments, reply relationships, edits, or other typed content. Stable\nMessageIDs also allow sessions to branch from an exact prior point.\n\nThe canonical session and message implementation must supply:\n\n- application-generated stable message IDs;\n- user, assistant, and tool roles;\n- assistant tool calls and correlated tool-result messages;\n- authoritative tool-result status, timing, error, truncation, and size\n metadata;\n- session lifecycle and active-request state;\n- session-to-agent-instance and parent-session lineage;\n- durable database round trips and timestamp validation.\n\nThese semantics must use the confirmed Agent, user, channel-binding, and\nconversation ownership model.\n\nThe canonical message store MUST preserve messages as immutable records and\nrepresent later edits, deletions, and branches through related records or\nevents.\n\nArchie requires exact branch-point correlation using stable MessageIDs.\n\n## Conversation branches\n\nA branch is a continuation of a previous conversation at an exact message. A\nchild conversation records:\n\n```text\nParentConversationID\nForkMessageID\n```\n\nMessages remain an append-only linear sequence within each conversation. The\nchild's effective initial context is the parent's history through\n`ForkMessageID`; messages after that point in the parent are not inherited.\n\nAfter the fork, parent and child are isolated:\n\n- child messages, tool calls, tool results, capability actions, and errors do\n not appear in the parent conversation;\n- later parent messages do not silently enter the child;\n- returning to the parent resumes its unchanged history;\n- the child may itself be branched using the same rules;\n- branch lineage remains queryable for navigation, audit, and metrics.\n\nThis supports building substantial context about a subject and then performing\none or more contextual subtasks without polluting the original conversation. For\nexample, a user may branch from a project discussion, create Jira issues in the\nchild using inherited context, and then return to the project discussion without\nadding the Jira tool transcript to the parent.\n\nBranching does not copy mutable message rows. History is resolved through the\nimmutable parent conversation and fork MessageID, followed by the child's own\nmessage sequence.\n\nBranch isolation applies to conversation history, not to Agent learning or\nmemory. A memory action performed in a branch has exactly the same semantics as\nthe same action performed in any other conversation. It writes to its selected\nglobal, agent-wide, user-wide, or Agent-user relationship scope.\n\nMemory provenance MAY retain the source ConversationID and MessageIDs for\nexplanation and audit. Retrieval and effect are determined by memory scope and\naccess rules, not by the conversation from which the memory originated.\nReturning to a parent does not insert the child's tool transcript into the\nparent history, but scoped memories learned in the child remain available to\nfuture retrieval wherever that scope is visible.\n\nChanging sessions or branching therefore controls immediate conversational\ncontext without preventing the Agent from learning durable knowledge.\n\n## Target ownership\n\nThe Messaging domain lives at `internal/domain/messaging`. It owns:\n\n- canonical Messages and typed message content;\n- Conversations, branches, and lineage;\n- channel bindings and external source correlation;\n- replies, acknowledgements, and outbound delivery attempts;\n- message and conversation lifecycle events;\n- domain-defined repository and delivery service contracts;\n- projections required for conversation navigation and metrics.\n\nWork intake is a separate cohesive domain at `internal/domain/workintake`. It\nowns admission, validation, deterministic routing, and accepted work requests\nfor the optional transition into durable workflow-backed execution.\n\nTelegram, email, webhook, forge, Jira, and future messaging systems are\ninfrastructure adapters implementing Messaging contracts. They are users of the\ndomain; they do not own Messages, Conversations, work admission, or\nWorkflowExecution semantics.\n\nThe Agent decides whether an ordinary interaction is answered directly, uses a\ncapability, changes or retrieves Agent-owned information, or proposes durable\nworkflow-backed work.\n\nExplicitly configured automation MAY enter work intake without a conversational\nAgent turn when the external trigger and admission rule already unambiguously\nrequest durable work. This avoids spending an LLM turn to rediscover a\ndeterministic routing decision.\n\nWhen an interaction requires durable workflow-backed execution:\n\n1. a channel adapter produces a channel-neutral inbound message;\n2. the acting agent handles or interprets the interaction;\n3. work intake validates, admits, and routes a proposed work request;\n4. work intake emits an accepted work request with its source correlation,\n acting identity, requested outcome, inputs, and routing evidence;\n5. the Agent System consumes that request, selects a specific Workflow version,\n and creates the WorkflowExecution.\n\nThe accepted work request is a cross-domain handoff, not an alternate execution\naggregate. The Agent System is the sole authority that creates a valid\nWorkflowExecution.\n\nAn interaction MAY instead be completed directly by an agent turn, delegated to\na tool or capability, recorded as a note or reminder, answered conversationally,\nor retained for later context. Those paths MUST NOT require a Workflow or\nWorkflowExecution.\n\nA Workflow MAY add reusable, versioned structure to any of those behaviours.\nScheduled personal-assistant routines, message triage, reminders, infrastructure\noperations, and other capability sequences are valid Workflow definitions. The\ndistinction is whether durable structured execution is useful, not whether the\nsubject originated from a forge.\n\n## Canonical execution language\n\n- **Workflow**: reusable, versioned behaviour definition.\n- **WorkflowExecution**: durable execution of a specific Workflow version.\n- **WorkflowStep**: a defined operation in a Workflow.\n- **StepExecution**: the recorded execution and outcome of a WorkflowStep.\n- **Attempt**: a retry within the same WorkflowExecution.\n\nExternal issues, messages, requests, goals, and notes are not synonyms for these\nconcepts.\n\n## Current implementation\n\nCurrent intake is fragmented:\n\n- Telegram, email, and webhook adapters translate payloads into\n `gateway.Message`, while an unused richer `MessageEvent` contract exists\n alongside it.\n- `gateway.Router` combines local channel commands, conversational LLM routing,\n and direct task lifecycle operations.\n- Telegram is the only channel with production LLM and durable conversation\n wiring. Email and webhook free text currently have no LLM responder.\n- Forge polling bypasses the gateway and directly enqueues store rows or NATS\n task messages.\n- Chat `/spawn` directly creates a `store.Task` and invents a synthetic forge\n issue number to satisfy the existing persistence key.\n- Forge replies and chat approval commands implement separate waiting-human\n paths.\n- Message delivery, acknowledgement, retry, deduplication, and source\n correlation are platform-specific side effects rather than one durable model.\n- `store.Task` collapses an external source reference and durable execution\n state.\n\n## Intake provenance\n\nA task's origin determines which enqueue path created it, though every origin\nconverges on the same `tasks` table and the same `Route`/`Run` lifecycle once\nqueued.\n\n- Forge-sourced work -- discovered by polling or, in single-identity\n deployments, delivered by the forge webhook receiver (`internal/forge/webhook`)\n -- enqueues through the same `workintake.TaskEnvelope` and `PublishTask` path.\n `TaskEnvelope.IdempotencyKey` is keyed on `owner/repo/number` and not on the\n delivery source, so a webhook-delivered issue and a later poll of the same\n issue dedup through `PublishUnique` instead of double-enqueuing.\n- Chat-spawned and playbook-binding-dispatched work enqueues through\n `EnqueueChatTask`/`EnqueueBindingTask` (`internal/infrastructure/postgres`), stamped with\n `binding_id`/`binding_version` for provenance.\n\nWebhook intake is opt-in per deployment (`Forge.Intake` = `poll` (default),\n`webhook`, or `both`) and single-identity only: a config naming\n`webhook`/`both` alongside `[[identities]]`, or setting intake on a\n`[identities.forge]` entry, is rejected at validation rather than started with\nthe setting ignored. One receiver binds one secret and one dispatch predicate,\nso it cannot judge a second identity's events by the right rules. A\nmulti-identity deployment polls per identity until per-identity intake lands.\nThe decided contract is `docs/prds/event-sources-and-reactions.md`; the binding\nmodel and its threat model are `docs/architecture/bindings.md`.\n\n## Current hazards\n\n- Treating every agent interaction as a work request would remove Archie's\n personal-assistant role and force conversation and immediate capability use\n through an inappropriate workflow lifecycle.\n- Treating every accepted work request as a WorkflowExecution would let intake\n or channel code select versions and construct invalid execution state outside\n the Agent System.\n- Source identity is incomplete: sessions use configured bot usernames, tasks\n use identity strings, and external message IDs are generally absent.\n- Database and NATS deduplication are based on forge coordinates rather than a\n channel-neutral source-message reference.\n- Replies and acknowledgements have no durable delivery-attempt lifecycle, so\n partial success and retry behaviour differ by adapter.\n- Production code has two competing channel-neutral message contracts.\n- The existing Archie session implementation lacks the required tool-call\n semantics and exact branch lineage and MUST be brought to the canonical\n contract.\n\n## Decisions still required\n\n- the cohesive owner and final location of messaging behaviour;\n- the cohesive owner and final location of work-intake admission and routing;\n- the canonical inbound message, conversation, and source-correlation model;\n- the boundary between an agent turn, direct capability use, and a proposed\n durable work request;\n- the exact relationship between an Agent, its acting IdentityID, its user, and\n its channel bindings;\n- outbound response, acknowledgement, delivery-attempt, retry, deduplication,\n and failure semantics;\n- the smallest accepted-work-request contract consumed by the Agent System;\n- migration of forge polling, replies, chat commands, email, webhook, Telegram,\n and Jira integrations.\n\n## Non-goal: semantic search over chat messages\n\nSemantic/vector search over chat messages is an **explicit non-goal** until usage\ndata shows a real need.\n\nMessage search is lexical only: session-scoped PostgreSQL full-text queries paged via\n`MessageQuery{Query,Limit,Offset}` → `MessagePage`. Do not add embeddings\nconfiguration or vector columns to message records.\n\nThe rationale is cost without a demonstrated use case. Measured 2026-08-03 with\n`embeddinggemma:300m` — note this was never an infrastructure problem, the model\nwas already pulled and `ai-sdk/provider/ollama` already has `embed.go`:\n\n- 121 ms median warm per message on the write path, 12.5 s cold;\n- 768 dims = 3072 bytes per vector, roughly 15× a typical message payload;\n- chronological reads would carry vector data they do not use on the hot path\n of every turn;\n- similarity search requires an explicit indexing and retention design.\n\nIf this is revisited, vectors belong in a sibling table so chronological reads\nnever load them.\n" }, { "url": "/dev/architecture/migration-decisions/", "title": "Architecture Migration Decisions", "section": "Architecture", - "body": "# Architecture Migration Decisions\n\n**Status:** Active migration inventory \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nThis document records what remains to be decided before Archie's current\nimplementation can be migrated into the approved domain-oriented structure.\n\nThe product and core domain model are not being redesigned. Existing Archie\nbehaviour and the existing session implementation are the migration\nbaseline. Remaining decisions MUST be grounded in current packages, consumers,\ntests, persistence, and runtime wiring.\n\n## Confirmed domain packages\n\n```text\ninternal/domain/\n identity/ (approved, not yet materialised as a package)\n agent/ (approved, not yet materialised as a package)\n workflow/\n messaging/ (canonical Message/Conversation types only; gateway migration pending, see section 2)\n workintake/\n plugin/ (approved, not yet materialised as a package)\n curator/\n mapping/\n scheduling/\n```\n\n- `identity` owns persistent actors, lifecycle, ownership, attribution, and\n audit identity.\n- `agent` owns persistent assistants, specialisation, instructions,\n model-independent continuity, capability context, and associations with\n identity and memory.\n- `workflow` is a separate domain. It owns reusable, versioned Workflow\n definitions, WorkflowSteps, WorkflowExecutions, StepExecutions, Attempts,\n outcomes, and typed Workflow plugin contracts.\n- `messaging` owns canonical Messages, Conversations, branches, channel and\n source correlation, replies, acknowledgements, delivery attempts, events, and\n projections.\n- `workintake` owns admission, validation, deterministic routing, and accepted\n work requests for the optional transition into durable workflow-backed\n execution.\n- `plugin` owns generic plugin identity, discovery, compatibility, and lifecycle\n mechanics. It remains metadata-only; capability semantics and typed\n registration belong to the owning domain.\n- `curator` owns the curator engine family: long-running agent loops that\n reason over memory and perform maintenance tasks on a declared shape\n (check-in interval, tool set, attached memory engine). See epic\n archie-core-yp9.\n- `mapping` owns the payload field-mapping vocabulary: binding named fields to\n JSON paths inside a captured webhook payload, and detecting drift. See\n `docs/prds/payload-field-mapping.md`.\n- `scheduling` owns the ticker engine: deciding when a scheduled job runs and\n with what concurrency. It declares `JobSource`/`Runner` contracts and owns\n no storage or delivery. See epic archie-core-1786637496320-249-be6d9a20.\n\n**Reconciliation (2026-08-31):** `curator`, `mapping`, and `scheduling` existed\nin the tree without being added to this list when their epics landed. They are\nconfirmed as legitimate, narrowly-scoped domains under the same rules as the\noriginal six — each owns one capability family, declares typed contracts, and\nhas no cross-domain reach. This list was out of date, not the tree.\n\nConversely, `identity`, `agent`, `messaging`, and `plugin` are approved target\ndomains that do not yet exist as packages. Their behaviour currently lives in\npre-migration packages (see \"Complete package destination map\" below for the\nfull inventory). Do **not** create empty stub packages for them ahead of an\nactual migration PR — an unused stub is dead code and gives no test coverage.\nEach materialises when its corresponding migration decision below is resolved\nand implemented in the same change.\n\nMemory's final package placement remains undecided pending focused review of the\nexisting implementation.\n\nThe following are approved shared or composition packages, not domains:\n\n```text\ninternal/eventbus/\ninternal/policy/\ninternal/infrastructure/\ninternal/app/archied/\ninternal/app/agentworker/\n```\n\n## Remaining migration decisions\n\n### 1. Complete package destination map\n\nEvery current package MUST receive one explicit disposition:\n\n- move into a confirmed domain;\n- move under infrastructure as an implementation of a domain-owned contract;\n- move into application composition;\n- merge with an identified duplicate;\n- remain as an approved shared application contract;\n- move to a plugin, extra, deployment, example, or generated artifact;\n- be deleted after its replacement is proven.\n\nThe largest unreviewed areas include memory, tools and capabilities, workspace\nand worktree behaviour, gates, storage, events, web UI, containers, RPC\npackages, release management, and scheduling.\n\nThe destination matrix MUST name the behaviour owner, target path, dependencies\nto remove, state and contracts to preserve, migration prerequisites, and\ndeletion criteria.\n\n**`internal/webui` / UI Service — RATIFIED Phase 3 disposition (2026-09-07).**\nThe current owner is the in-process HTTP/SSE dashboard: SPA hosting, operator\nauthentication, UI response projection, configuration reads and mutations,\ntask/control APIs, and direct adapters to State Store, channel, event/log,\nmemory, curator, workflow, forge, and Gateway runtime values. The target owner\nis a standalone UI application process; `internal/webui` remains its HTTP\ntransport adapter, while Gateway, State Store, configuration, Work Intake,\nMessaging, and other capability owners expose the contracts behind those\nroutes. The migration preserves retained route schemas, auth/CSRF behavior,\ntask/capture/mapping/binding/session continuity, SSE replay semantics, and\ncommitted generated SPA assets. Prerequisites are the ratified UI boundary,\nroute-owner inventory, narrow remote adapters, configuration/auth/readiness\ncontracts, and process/conformance tests. Remove the shared live\n`config.Holder`, direct event/log bus, daemon stopper, forge client, channel\nmanager, capability registries, composite store access, and in-process UI\nlistener only after the focused criteria in\n[`docs/prds/ui-service-boundary.md`](/dev/prds/ui-service-boundary/) pass in\nproduction composition. The old construction and listener are deleted in the\nsame cutover change; no second UI authority remains.\n\n### 2. Session and Messaging migration\n\nThe existing session implementation is the migration baseline. The migration must\ndecide:\n\n- which session and message components are retained or adapted;\n- how Agent, user, channel, Conversation, and branch ownership are added;\n- how Archie's parallel gateway session implementation is replaced;\n- how canonical Messages become immutable persisted records;\n- how existing sessions and messages are migrated;\n- how outbound delivery, retry, acknowledgement, deduplication, and failure\n semantics are represented;\n- how current Telegram, email, webhook, forge, and Jira integrations migrate to\n Messaging infrastructure adapters.\n\nThe following are already decided and MUST NOT be reopened without contradictory\nimplementation evidence:\n\n- the composite Conversation identity;\n- immutable MessageIDs;\n- typed tool-call and tool-result messages;\n- exact branch lineage through ParentConversationID and ForkMessageID;\n- parent and child transcript isolation;\n- normal scoped-memory behaviour regardless of the originating Conversation;\n- Messaging and Work Intake ownership.\n\n**Decision (2026-08-31), resolving the open questions above:**\n\n`internal/gateway/` is the \"parallel gateway session implementation\" this\nsection names. It is retained as-is for now — a big-bang rewrite of live\nsession/compression/approval/branch logic across Telegram, web UI, email, and\nwebhook channels in one change is exactly the \"convoluted to satisfy edge\ncases\" failure mode CLAUDE.md's Revert-on-Flail rule warns about, and would\nrisk silent behavioural regressions in the one path every user-facing message\ntravels through.\n\nInstead, `internal/domain/messaging/` is materialised now with the pieces\nthat are already decided and don't require touching gateway: the canonical\n`Message` and `Conversation` types (composite Conversation identity, immutable\n`MessageID`, typed tool-call/tool-result message variants, branch lineage via\n`ParentConversationID`/`ForkMessageID`). These are pure domain types with no\ngateway dependency — a new package, not a rewrite of an existing one.\n\nMigrating `internal/gateway/`'s session, compression, approval, and branch\nlogic onto these types is real, cross-channel-risk work and is **not** done in\nthis pass. It is tracked as separate, appropriately-scoped bd issues (see\n`bd list --label messaging-migration`), sequenced channel-by-channel so each\nlands with its own behavioural verification instead of one large diff no one\ncan safely review.\n\n**Amended 2026-09-15.** `internal/infrastructure/gatewayrpc.StoreClient` is the\nadapter this migration will need: it implements `messaging.SessionStore` over\nthe chat service's session-store RPCs and is proven by\n`TestStoreClientPreservesCanonicalRecords`. It is deliberately unwired.\nProduction `archied` dials the standalone gateway for `ChatContract` only\n(`composeChatContract` → `gatewayrpc.Dial` returns a `*Client`, not a\n`*StoreClient`), and the daemon's session store is in-process SQLite via\n`makeTelegramSessionStore`. The test comment that says it mirrors production\ndescribes the target, not today's tree. Kept rather than deleted because the\nmigration it serves is deferred by this very section, and re-deriving a tested\nwire adapter once that lands is pure cost.\n\n**Phase 4 Messaging Service extraction (2026-09-19, `archie-core-8cda.6.1`).**\nThe process boundary for external channels (Telegram, email, webhook) is ratified\nin [`docs/prds/messaging-service-boundary.md`](/dev/prds/messaging-service-boundary/).\nMessaging is extracted into `cmd/archie-messaging` / `internal/app/archiemessaging`,\ncalling Gateway's `messaging.ChatContract` exclusively over gRPC. Channel frontends\nhold no direct database handles, daemon state, or model runtimes.\n\n**Telegram operator surface after extraction (2026-09-19, `archie-core-8cda.6.6`).**\n`setupTelegramGateway` wired eight `telegram.Gateway` seams the daemon could\nsatisfy from its own process. Each is resolved by where the fact it needs is\nactually owned, not by where it used to be built:\n\n| Seam | Resolution |\n|---|---|\n| `Version` | Sourced from the Gateway via `ChatSnapshot.Version`. The Messaging Service never stamps or infers a build version; `cmd/archie-messaging` deliberately takes no version ldflags, so it cannot report a partial upgrade as a matched one. |\n| `Updates` (`/update`) | Built in the Messaging Service from `[chat.telegram].update_check_command` / `update_install_command` — its own configuration. `Enrich` is dropped: `componentInstallTypeEnricher` reads `[nats]`, which this service must not decode, so the check command's own reported install type stands unmodified. |\n| `UpdateReportPath` | A local state file under `work_dir`, keyed by the same `sha256(bot_user)[:8]` scheme the daemon used, so a pending report is found rather than written afresh. |\n| `ReleaseAnnouncements` | **Deliberately left nil**, for the same reason as `RunningVersions`. `releaseannounce.Announcer` announces nothing unless each `Component` carries a parseable version, and the only versions this service can obtain are the Gateway's own build stamps, not archied's. Wiring the announcer without them yields a no-op that reads as configured, so it stays unwired until component self-reporting exists. |\n| `SetShowToolCalls` | Projected from `[chat].show_tool_calls`. |\n| `Reload` | Local: re-resolves the token and allowlist from this service's own config file and overlay. Reload was never a daemon fact. |\n| `RunningVersions` | **Deliberately left nil.** It exists to turn an installer's claim into a checked one, and only a component's own compiled-in build can vouch for it. The Messaging Service knows neither archied's build nor the observed archie-agent version (`daemon.AgentStatus`), and the Gateway's own `gatewayVersion` is a different binary's stamp — reporting it as the daemon's would manufacture exactly the false success the check exists to catch. Update reports therefore relay as unverified claims until a component self-report contract exists. |\n| `Dangerous` | Stays nil. No daemon composition ever set it; `/rollback` and `/stop` reported \"not configured\" before the extraction and still do. |\n\nThe Messaging Service consequently reads `work_dir`, `bot_user`, `[chat]` and\n`[health]` in addition to the PRD's `[chat.*]` / `[services.gateway]` list.\n`[health]` is the daemon's health URL, which `releaseupdate.CommandInstaller`\npolls from outside to confirm an update came back up; the rest of the PRD's\nprohibition list is untouched.\n\n**Phase 4 messaging severance: what must move, and the decision the PRD does\nnot cover (2026-09-22, `archie-core-1ng1`).** The PRD's deletion gate cannot\npass today. `cmd/archie-messaging/architecture_test.go` does not exist, and the\ncheck that section specifies -- `go list -deps ./cmd/archie-messaging` links\nzero banned runtime packages -- reports four:\n\n| banned package | PRD category |\n| --- | --- |\n| `modernc.org/sqlite` | State Store |\n| `internal/store` | State Store |\n| `internal/domain/workflow` | Workflow engine |\n| `internal/agentexec` | Workflow engine, via `internal/domain/workflow/agent.go` |\n\nAll four arrive through one import: `internal/app/archiemessaging/run.go`\nimports `internal/app/controlplane`, whose own dependency set is exactly those\nfour. The Messaging Service uses three symbols from that package\n(`NewRPCClient`, `RuntimeChatConfig`, `ChannelSettingsKind`); the package also\ncarries the store-backed `ResourceStore` server, the `Definition` registry and\nthe workflow step vocabulary. Sever the package. Amending the gate to tolerate\n`modernc.org/sqlite` and `internal/store` is rejected: a boundary you whitelist\naround is no longer a boundary.\n\n**What moves.**\n\n- Every kind constant. They are strings with no dependency, and the client names\n them.\n- The channel-settings vocabulary and its decode: `channelSettings`,\n `telegramSettings`, `webhookChannelSettings`, `emailSettings`,\n `rateLimitSettings`, `channelDuration`, and `decodeRenamingLegacyKeys`.\n- The generic client: `Client`, `NewRPCClient`, `RuntimeConfig` with\n `runtimeConfigFrom`, `runtimeChatConfigFrom`, the other `runtime*From`\n projections, and the `resourceReader` interface.\n- The persona watch (`WatchPersonas`, `AppliedPersonas`), which needs only\n `internal/domain/agent`.\n- `executionSettingsDocument`, the document alone.\n\n**What stays, and why.**\n\n- The store-backed server: `Server`, `NewServer`, `ResourceStore`,\n `ImportConfig`, `SeedSkip`, the `Definition` registry, and every other kind's\n seed, validator and `Normalize` hook.\n- `WorkflowDefinitionsClient` and `stepRegistry`, which decode through\n `internal/domain/workflow`.\n- `WatchWorkflowExecutionSettings` and `decodeSettings`: `decodeSettings`\n returns and validates `workflow.ExecutionSettings`, so any package holding it\n links the workflow domain and therefore `internal/agentexec`. This is why the\n client cannot move as one package -- see open question 2.\n- The schedules document, whose type is `scheduling.JobSpec` in\n `internal/domain/scheduling` -- the vocabulary moved there when the legacy\n file-backed cronstore was deleted, which is also what satisfies the rule\n that a domain vocabulary package may not import infrastructure.\n- The schema derivation, which describes the documents the server advertises.\n\n**Placement as landed (2026-09-22, `archie-core-1ng1`).** One new package,\n`internal/infrastructure/controlplanerpc`, holding both the vocabulary (kinds, the\nchannel-settings document and its decode) and the client\n(`NewRPCClient`, `Query`, `RuntimeChatConfig`, the exported `ResourceReader`, the\nwire sentinels and `ClientError`). A second `internal/domain/controlplane` package\nfor the vocabulary was planned and then measured out of the design: the vocabulary\nhas exactly one consumer, the client that projects it, and the store-backed side\nreads the same definitions through type aliases rather than a copy -- so a separate\ndomain package would have been a package with one consumer and a second name for\none thing. What made that safe is a measurement, not a preference:\n`internal/app/controlplane` was the ONLY direct import of the Messaging Service\nthat dragged a banned runtime (`gatewayrpc`, `staterpc`, `applystatus`, `messaging`,\n`configuration`, `readiness` and `health` were all clean), so severing that one\ndependency is sufficient, and the severance needed no third package. Promoting the\nvocabulary to a domain package stays open for the day a second consumer appears.\n\n**Settled by the implementation.** Two of the four open questions this decision\noriginally left are answered, in both cases by measuring rather than by preference:\n\n- The client did NOT become two packages. `WatchWorkflowExecutionSettings` and\n `WatchPersonas` stayed on `internal/app/controlplane`'s `Client`, which now\n *embeds* the new one, so the daemon's validated watch is still defined once and\n the read path still has one implementation -- which is what the second package\n was for -- with one fewer package to keep in step.\n- The schedules and workflow documents stayed put, and\n `internal/domain/workflow/task` is linked deliberately: it carries the Task\n status and view vocabulary, its own dependency set holds none of the banned\n runtimes, and `cmd/archie-messaging/architecture_test.go` carries it as an\n exception checked in both directions (the same entry, for the same reason, as\n `cmd/archie-ui/architecture_test.go`).\n\n**Still open.**\n\n1. Does the server also leave `internal/app/`? `organisation.md` reserves\n `internal/app/` for wiring and composition, and a store-backed gRPC server is\n infrastructure -- but the gate does not require the move, and it would multiply\n the diff across archied's wiring and the State Store binary. Tracked as\n `archie-core-8f4n`.\n2. Does `internal/domain/workflow`'s contract/engine split happen, and when? A\n contract type (`WorkflowDefinitionCollection`) drags `internal/agentexec` only\n because `agent.go` sits beside it. Independent of this severance, tracked as\n `archie-core-inh6`, and the shape `archie-core-8cda.7` will meet again.\n3. Does the vocabulary move to a domain package when a second consumer appears?\n\n**Both consumers keep compiling.** archied imports the new vocabulary for the\nkinds it names and the new client package for `RuntimeConfig` and the persona\nwatch, and keeps `internal/app/controlplane` for the server, the registry,\n`ErrVersionConflict` and the workflow-aware pieces. The State Store binary\ncontinues to call `NewServer` and `ResourceStore` unchanged. The Messaging\nService then imports only `internal/infrastructure/controlplanerpc`,\n`gatewayrpc` and `staterpc`, so `go list -deps ./cmd/archie-messaging` loses all\nfour banned packages and the gate can land green.\n\n**Channel state to the dashboard: one administrative surface, following the\nconfig-snapshot precedent (2026-09-22, `archie-core-8cda.6.8`).** The Messaging\nService now records its channels' lifecycle -- `internal/channels/status.Manager`,\none entry per composed channel, written by each channel's own report through\n`channels.Lifecycle` -- and nothing reads that across a process boundary.\n`/api/channels` answers with nothing because `webui.Server.Channels` has no\nproduction source, and POST `/api/channels/{id}/reload` answers 501 for the same\nreason. The carrier is the State Store, and the shape is the one\n`archie-core-ymut` already established for config snapshots\n(`docs/prds/state-store-contract.md`, \"the one surface whose writer is the daemon\nand whose reader is the UI process\"): a pair of administrative RPCs, deny-by-default\nunder `authorizesTaskScopedCall`, so a task-scoped grant reaches neither.\n\nWhat that decides, so the implementation need not invent it:\n\n- A channel's state is **runtime** state, not a settings document. It does not\n belong in the `ControlPlaneService` resource kinds, which are validated,\n versioned documents seeded from config; a channel that is failed is not a\n document anybody edits.\n- The reader is the UI process, which already dials the State Store and pumps its\n cursor, so the surface needs no new transport in either direction.\n- Adding the pair changes the contract's RPC count, so\n `docs/prds/state-store-contract.md`'s grouped table gains a group in the same\n change that adds the RPCs -- the table is the contract's own index, and a\n surface it does not list is a surface nobody finds.\n\n**Reload gets its own surface, with its own lifetime (decided 2026-09-22).** Reload\nruns the other way -- the UI asks the service to reload a channel -- and the two\ncandidates were a request surface the service observes and clears, or a field on\nthe status surface the service watches. It is the first. The reasoning, recorded\nbecause it would look arbitrary later:\n\n- A request queue and a status report do not share a lifetime, so they should not\n share a surface. A pending request is transient and has an outcome; a channel's\n state is durable and has a current value.\n- A \"please reload\" field on the status resource makes READING status capable of\n RETRIGGERING an action, and makes a transient request indistinguishable from\n state the moment anything polls it.\n- It would also invert the writer/reader relationship the precedent establishes:\n the service would have to clear a field on an object whose whole contract is\n that the service reports it.\n\nSo the status surface stays writer-is-service, and the request carrier is its own\nobject with its own states.\n\n`archie-core-8cda.6.9`'s component self-report is the **same shape**: a process\nreporting something about itself for the UI to read. Whether it shares this\nsurface or gets its own is a decision for `6.9`, and the one outcome to avoid is\ntwo homes for \"what a component reports about itself\".\n\n### 3. Identity data migration\n\nThe migration must define:\n\n- the durable identity schema and repository implementation;\n- bootstrap of the permanent system identity;\n- stable IdentityIDs for existing configured Agents;\n- migration from configured identity names, empty-string ownership, and bot\n usernames;\n- preservation of historical attribution;\n- identity-aware uniqueness and transport deduplication;\n- correction of container and RPC capability resolution so execution uses the\n owning identity's bindings;\n- removal of identity-string equality from access-control behaviour.\n\nExact schema and method signatures are implementation decisions. The approved\nIdentity lifecycle and attribution semantics are fixed migration constraints.\n\n### 4. Workflow migration\n\nThe current implementation must be transformed deliberately:\n\n```text\nstore.Task -\u003e WorkflowExecution\nmutable Stage -\u003e StepExecution history\nRetryCount / Attempt -\u003e Attempt records\nworkflow.Registry -\u003e versioned Workflow definitions\ncurrent stages -\u003e WorkflowStep definitions or Workflow plugins\n```\n\nThe migration must decide:\n\n- Workflow definition and version persistence;\n- the smallest accepted-work-request contract consumed from Work Intake;\n- the enforced WorkflowExecution state machine;\n- atomic state and domain-event persistence;\n- migration of existing task rows and transition history;\n- disposition of current skill, Yaegi, and stage-plugin implementations;\n- the versioned worker-handoff contract;\n- scheduler, claim, retry, crash-recovery, and waiting-human cutover.\n\nWorkflow remains a separate domain from Agent. A user or Agent may define or\ninvoke a Workflow, but Workflow semantics and plugins remain Workflow-owned.\n\n### 5. Memory placement and storage\n\nThe four required scopes are fixed:\n\n- global shared;\n- Agent-wide;\n- user-wide;\n- Agent-user relationship.\n\nA focused review of `internal/memory`, its providers, consumers, persistence,\nand tests had these decisions:\n\n- `internal/domain/memory` versus ownership within the Agent domain — settled\n (2026-09-02, below);\n- the authoritative memory record and revision model — settled by the PRD\n (2026-09-16, below);\n- provider and infrastructure boundaries — settled by the PRD (2026-09-16,\n below);\n- retrieval and access enforcement — settled by the PRD (2026-09-16, below);\n ranked retrieval remains open (below);\n- migration of existing memory data — open: existing data is not migrated;\n- provenance representation — settled by the PRD (2026-09-16, below).\n\nConversation branches do not create another memory scope. A memory action has\nthe same scoped effect regardless of which Conversation originated it.\n\n**`internal/domain/memory` ownership — DECIDED (2026-09-02).** The typed\nengine family lives at `internal/domain/memory`\n(archie-core-1786637490069-11-e245c170), mirroring `internal/domain/curator`'s\ncontract/registrar/registry split. Not owned within the Agent domain: memory\nis consumed by more than agent turns (curators, per archie-core-1786637499636)\nand the plugin engine rule requires its own family, not a capability bolted\nonto another domain's contract.\n\n**Authoritative record and revision model for the builtin engine — DECIDED\n(2026-09-02),** scoped to unblock archie-core-1786637499480 (ship the\nfile-writing store as the default engine). This decides only the builtin\nengine's mapping onto the new `Record{ID}`/`Forget(id)` contract, not the\nmemory model in general or a future non-file engine's model:\n\n- `internal/memory/builtin.Store` is unchanged. It has no concept of a\n stable per-block ID — blocks are addressed by content substring — and nothing\n in this decision requires changing that; existing `internal/memory` tests\n keep passing unmodified, per that issue's acceptance criteria.\n- A new infrastructure adapter (`internal/infrastructure/memory`, per\n `organisation.md`'s \"infrastructure implements domain contracts\" rule — not\n under `internal/domain/memory`, which stays contract-only) wraps one\n `builtin.Store` per identity.\n- **Identity → directory:** `hex(sha256(identity))`, not the identity string\n itself. Closes the path-traversal question without an allowlist regex, and\n sidesteps collisions from identities that differ only in characters a\n filesystem treats as equivalent.\n- **Record ID:** assigned once at `Write`, independent of content, so a later\n edit elsewhere in the file can never orphan a `Forget`. Realized as a\n leading marker line (`\u003c!--mem:\u003culid\u003e--\u003e`) on the block `builtin.Store.Add`\n writes; `Query`/`List` strip it back out of `Record.Content` before\n returning, and `Forget(id)` locates the block by that unique marker via the\n store's existing substring-based `Remove`. The marker is a pragmatic,\n reversible choice — plain-text records stay human-readable and\n human-editable, at the cost of one marker line an operator editing the file\n by hand should leave alone. Revisit if/when provenance representation\n (still open, below) settles on something richer.\n- **Kind → section:** `Observation.Kind` (default `\"general\"` when empty) is\n the section name, reusing `builtin.ValidateSectionName` — so an\n invalid `Kind` fails `Write` with the same validation error `memory_edit`\n already returns for an invalid section today, not a new error shape.\n\n**Memory engine: scopes, CRUD with retained revisions, and store placement —\nDECIDED (2026-09-16).** Supersedes the 2026-09-02 \"Authoritative record and\nrevision model for the builtin engine\" entry above, whose `\u003c!--mem:\u003culid\u003e--\u003e`\nlive marker cannot carry provenance. Authority:\n[`docs/prds/memory-engine-unification.md`](/dev/prds/memory-engine-unification/)\n(Approved); the contract is `internal/domain/memory/contract.go`. This register\nsupersedes; it does not erase.\n\n- **Four typed scopes, caller-named.** `internal/domain/memory` is addressed by\n `Scope{Kind, Agent, User}` over `global`, `agent`, `user` and `agent-user`,\n with `Validate` rejecting a component present where it is not required. A\n caller names the read and write sets (`Subject.Scopes()` /\n `WritableScopes()`; global is never model-writable) and the engine applies no\n policy of its own: **access control is naming a scope, and nothing else.** An\n engine that enforced policy would need to know about channels, sessions and\n bindings, and every backend would reimplement it. `Scope.Key()` length-prefixes\n each component, so two scopes can never share a key even when an opaque\n channel-native id embeds the separator.\n- **The caller resolves identity; the engine never does.** Resolution happens in\n the gateway turn path, where the native sender id and the session are both in\n hand, and is supplied per channel by the composition. A webhook's sender id is\n a route path, not a person, and treating it as one would give a URL an\n identity. An absent user id yields global and agent scopes only: \"show none of\n it\", never a wider fallback.\n- **CRUD supersedes, never overwrites.** `Store` is `Create`/`Get`/`Query`/\n `List`/`Update`/`Forget`/`Revisions` over the four scopes. `Update` appends the\n superseded state to the scope's `HISTORY.md` before replacing the live block;\n `Update.Expected` names the revision being replaced and returns\n `ErrStaleRevision` on mismatch, making a lost update between two processes\n sharing one scope file detectable. `Forget` records a deleted revision before\n removing the live block, so a record's provenance outlives its content; `Get`\n and `Forget` take a scope, because an id alone does not locate one.\n- **Provenance representation.** The live marker becomes JSON, since a\n `\u003c!--mem:\u003culid\u003e--\u003e` line cannot carry provenance, and `Record` retains the\n provenance `agent-system.md` requires — scope, author, originating user,\n source, and revision history. `Metadata` is dropped: it never round-tripped.\n- **Store and scanner placement.** The markdown store relocates to\n `internal/infrastructure/memory/builtin`, its correct home under\n `organisation.md`'s \"a package owns its on-disk format end-to-end\". The content\n scanner moves into `internal/domain/memory` and is applied in `Create` and\n `Update` — the single choke point every producer crosses, so curator-extracted\n content is covered too.\n\n**Open in this section.** Ranked retrieval is deferred: `Query.Text` stays in\nthe contract, unused by the prompt path. Existing memory data is not migrated:\n`\u003cworkDir\u003e/memory` and `\u003cworkDir\u003e/memory-engine` are left on disk, unreferenced.\nThe PRD leaves these undetermined and they remain open here: group-chat\nextraction, where the curator fails closed on mixed-sender sessions; two\nprocesses (`archied` and `archie-gateway`) holding one scope file, where\n`Update.Expected` detects but does not prevent a lost block; unbounded\n`HISTORY.md` with no compaction policy; whether the per-scope size bound is\nright; and whether the dashboard should carry a user identity.\n\n### 6. Runtime and process boundaries — DECIDED\n\n`archied` is the native resident orchestration and interactive-chat process.\nEvery autonomous repository workflow crosses one full-task core-NATS handoff\ninto a task-scoped `archie-agent` container. Embedded versus external NATS\nchanges broker deployment only; it never selects an executor. The former host\nin-process runner, per-stage NATS protocol, and subprocess runner are removed.\n\nForge, store, and worktree authority remains in `archied` and is exposed to the\ntask container through scoped RPC services. The worker runs the workflow and\nits worker-local ai-sdk loop; it does not receive forge credentials or direct\nstore access. See `docs/prds/embedded-nats.md`.\n\n**UI Service boundary — RATIFIED (2026-09-07).** Phase 3 has a focused\nauthority record in [`docs/prds/ui-service-boundary.md`](/dev/prds/ui-service-boundary/).\nThe UI Service owns HTTP/SPA delivery, UI DTOs, browser authentication, and\nits own endpoint/credential/readiness settings. It consumes Gateway and State\nStore contracts and does not receive `config.Holder`, daemon pointers, SQL or\nstore implementations, workflow registries, forge/channel/model runtimes, or\nresolved secrets. The current `internal/webui` implementation remains inside\n`archied` until the ratified migration gates prove route parity, adapter\nselection, failure/readiness behavior, and deletion of the shared-holder and\ndirect-access paths. The extraction cutover removes the in-process UI\nlistener in the same change; there is no dual-live UI authority.\n\n**Dashboard live event delivery — DECIDED (2026-09-09, `archie-core-za9f`).**\nThe extracted UI receives live activity by polling the State Store's existing\n`EventsSince` cursor, not by a new push-subscription RPC. No proto change, no\ncontract amendment beyond this record.\n\nThe UI process runs one event pump. It primes its watermark by paging\n`EventsSince` to the end at startup without delivering, then polls\n`EventsSince(watermark, limit)` on an interval and hands each new event to\n`webui.Server.Broadcast`, exactly where `internal/app/archied/main.go`'s\n`persistAndBroadcastEvents` hands events to it today. One pump serves every\nconnected browser, so cost is one indexed query per interval regardless of\nviewer count, and `Broadcast` is a no-op when nobody is watching.\n\nThree properties make the cursor sufficient, and a push hub unnecessary:\n\n- **The cursor cannot skip.** `internal/store/store.go` opens the database with\n `SetMaxOpenConns(1)`, so writes serialise and a row's `id` is assigned in\n commit order. There is no window in which a lower id becomes visible after a\n higher one, which is the failure mode that normally rules out polling an\n autoincrement cursor. SSE catch-up already depends on this same property.\n- **A broadcast is a wakeup, not the payload.** `sseStream.drain` treats each\n broadcast event as a signal to fill the persisted gap ahead of it via\n `catchUp`, then delivers the event only if catch-up did not already cover\n it, deduplicating on the `since` watermark. Substituting a poller for the\n in-process bus therefore changes no SSE semantics, and needs no change to\n `internal/webui/sse.go`. It also means a broadcast dropped to a stalled\n client self-heals on the next one.\n- **The table is the only complete fan-out point.** Events reach the store\n through several paths that never touch the daemon's bus, including the\n audit event `store.ArchiveTask` writes inside its transaction\n (`internal/store/store.go`) and the binding-dispatch failure\n `internal/daemon/daemon.go` inserts directly. A push hub would have to be\n hooked at every write site and at post-commit, and would silently miss any\n site added later that forgets to notify. Reading the table misses nothing.\n\nThe cost is one poll interval of latency on the activity feed, default 1s and\noperator-tunable. That is accepted: the feed reports task lifecycle history,\nand an operator action already gets its own synchronous HTTP response.\n\nThis resolves the `/events` row of the route-owner inventory in\n[`ui-service-boundary.md`](/dev/prds/ui-service-boundary/). `/api/logs` and\n`/api/logs/stream` are not resolved by it, they read the daemon's in-process\ndiagnostic feed and remain host-local (see `archie-core-8cda.5.4`).\n\nRevisit only if sub-second feed latency becomes a requirement, or if a second\nconsumer needs the same stream, at which point the fan-out belongs in the State\nStore process behind a `SubscribeEvents` RPC and this record is superseded.\n\n**Dashboard configuration page — DECIDED (2026-09-09, `archie-core-ymut`).**\nThe configuration page becomes read-only in the UI process for Phase 3. Reads\ncross the boundary as a published snapshot; writes are descoped, not\ncontracted. This amends the ratified boundary, which assumed a single admin\ncontract carrying both.\n\n**Reads.** `webui.ConfigView` is already the whole answer. It is a UI-owned,\nsecret-free value projection built in `handleConfig`: `ProviderView` carries\nthe API key's environment variable name and a `Configured` boolean, never a\nvalue, and `RepoView` is repository metadata only. It is already the exact\nshape the browser receives. So the daemon publishes that projection, plus\nprovenance, reload status and the overridden-key list, as a snapshot the UI\nreads; nothing new has to be designed, only moved. Two State Store RPCs carry\nit, a `PutConfigSnapshot` restricted to the administrative token and a\n`GetConfigSnapshot` the UI calls. The daemon republishes on boot and after\neach successful reload, which is precisely when the projection changes.\n\nThe State Store is the right holder because a published configuration snapshot\nis shared state, it is already dialled by the UI, and it costs no new listener,\nport, token or interceptor. The alternative, a config admin service on\n`archied`, would make the daemon a gRPC server for the first time. Today it is\npurely a client of Gateway and State Store; `grpc.NewServer` appears only in\n`RunGateway` and `RunStateStore`, which are the standalone binaries' entry\npoints, not the daemon's.\n\n**Writes.** `PATCH /api/config`, `POST /api/config/reset` and\n`PATCH /api/config/repos/{owner}/{name}` answer 503 in the UI process, and the\nSPA hides those controls rather than offering a button that fails. Editing is\n`config.toml` plus reload, which is already the only path for every setting\noutside the runtime-tunable allowlist.\n\nThis is a deliberate feature reduction and worth naming as one. The write path\nis not hard because of the transport; it is hard because the policy is\ndaemon-local and stays that way: `installUpdateConfigHandler` denies\nnon-runtime-tunable keys, applies a dotted overlay to a clone of the published\nconfig, validates the materialised result, writes overlay rows, and rebuilds\nprovenance. Contracting that means either moving the policy, which the\nboundary forbids, or exposing it verbatim as remote procedure calls, which\nbuilds a Configuration Service inside a migration bead. Neither is work this\nphase should be doing to keep one page's buttons alive.\n\nRevisit when dashboard configuration editing is picked up as a feature in its\nown right (`archie-core-1786637498420-327`, still open). At that point it gets\nan admin contract designed as a feature, and the Configuration Service this\ndocument already anticipates is its natural owner. Until then the UI renders\nconfiguration and does not write it, which is what the boundary always said\nabout ownership even when it assumed a wider contract.\n\nAmended 2026-09-11. This descope is a deferral, not a decision that the\ndashboard should be read-only. Name it that way in review: the daemon-side\npolicy was built and tested, then deleted by the cutover (`e037b95` removed\n`internal/app/archied/config_update.go` and its tests), so reviving it is\nrecoverable work, not a rewrite. `archie-core-j28m` carries the remaining\nquestion -- which process serves the policy and what transport carries the\nwrite -- and blocks the feature bead. The handlers, their error sentinels and\nthe `UpdateConfig`/`ResetConfig`/`UpdateRepoField` seams on `webui.Server` are\nkept deliberately for it; `ConfigView.Editable` follows whichever process holds\n`UpdateConfig`, so wiring that one field makes the page editable\n(`archie-core-ml30`).\n\nImplementation belongs to `archie-core-8cda.5.4`, the cutover that removes the\ndaemon's own dashboard. Nothing here is built yet.\n\n**Superseded 2026-09-21 by the runtime control plane.** The open question this\ndescope left -- which process serves the policy and what transport carries the\nwrite -- was answered by `docs/prds/runtime-control-plane.md`: neither a daemon\nadmin service nor a revival of the daemon-local policy. `ControlPlaneService` on\nthe State Store's existing gRPC server owns every database-backed setting, and\neach feature validates its own resource, so there is no daemon-local policy left\nto contract. `archie-core-j28m` is closed.\n\nConsequently the three write seams described above no longer exist.\n`PATCH /api/config`, `POST /api/config/reset` and\n`PATCH /api/config/repos/{owner}/{name}`, the `UpdateConfig`/`ResetConfig`/\n`UpdateRepoField` fields on `webui.Server`, and `ConfigView.Editable` were\ndeleted in `31622ec5` along with the runtime overlay store they wrote to.\n`GET /api/config` remains a read of the published projection, as this decision\nalways intended.\n\n### 7. Shared mechanics\n\nThe following cross-domain mechanics require exact contracts before dependent\npackages migrate:\n\n- event-bus delivery and failure semantics;\n- policy evaluation API, composition, and precedence;\n- configuration candidate preparation, health validation, atomic promotion,\n observation, and rollback;\n- service-specific health, bounded remediation, isolation, and escalation;\n- changelog association and grouping.\n\nThese shared mechanisms do not acquire ownership of domain meaning. Domains\ncontinue to own their commands, events, policies, settings, and consequences.\n\nThe Go documentation generator, its output placement, and drift checking are\ndefined in `generated-documentation.md`. The VitePress site and its Pages\ndeployment were removed on 2026-09-12 as an unnecessary build step; `docs/` is\nrepository documentation only. The rendering and publishing surface is an open\ndecision, and so are the renderer's page templates and any developer commands\nor CI sequence that would accompany one. Adapting the generator and implementing\nArchie's normalized documentation model remain migration work rather than open\nproduct architecture.\n\n**Amended 2026-09-15.** `internal/infrastructure/servicediscovery/nats`\nimplements the `servicediscovery.ServiceRegistry` contract (Connect, Register,\nResolve, Watch) over NATS KV and is fully tested, but no production code\nconstructs it and no config surface exposes it. This is a deliberate deferral,\nnot an oversight: service-to-service addressing belongs to the runtime and\nprocess boundary work in section 6, which currently pins container addressing\nby injecting the daemon's startup NATS URL rather than resolving through a\nregistry. The scaffold is kept for that work; re-derive it only if the\naddressing model changes.\n\n### 8. Cutover sequence\n\nThe final migration plan must order:\n\n- compatibility adapters;\n- schema migrations and data backfills;\n- any required dual-read or transitional paths;\n- domain-by-domain package replacement;\n- production wiring changes;\n- legacy package removal;\n- architecture tests preventing dependency regression;\n- focused, integration, race, and full quality gates.\n\nEach legacy package requires objective removal criteria. No compatibility path\nmay become an indefinite second implementation.\n\n\n## Completion criteria\n\nMigration design is complete when:\n\n- every current package has one approved owner and destination;\n- every mutable record has one authoritative owner and migration path;\n- all external and cross-process contracts have versioned owners;\n- existing behaviour and data have explicit parity requirements;\n- process boundaries have evidence-backed justification;\n- the cutover order preserves a working application;\n- legacy deletion criteria and deterministic architecture tests are defined;\n- no unresolved decision requires an implementer to invent domain semantics.\n\nExact Go APIs, SQL statements, and mechanical refactoring steps MAY be finalized\nduring implementation when they do not change these semantics.\n\n## Recorded migration position (2026-07-29)\n\nRecovered 2026-08-09 from the pre-migration issue tracker. This section records\ndecisions the maintainer approved that the repository did not otherwise capture.\n\n**Completed:** `internal/infrastructure/eventbus/nats` (rebuilt, not relocated);\n`internal/infrastructure/configuration` (loading moved out of `internal/config`,\nwhich is now types-only and does no I/O); `internal/eventbus` (broker-neutral\ncontract); `internal/domain/workintake` (the first `internal/domain/` package,\nowning `TaskEnvelope`, the routing `Kind`, the label vocabulary, and task\nsubjects).\n\n**DECISION — private input DTO deferred (approved).**\n`configuration.Document.Config` is still `internal/config.Config` rather than the\nprivate per-domain input DTO this document mandates. Building an ~800-line\nparallel type tree while every consumer still reads `config.Config` would mean\ntwo shapes kept in sync by hand, with no consumer for the new one. It is named as\na field so the compromise is visible at each use site, with the deletion\ncondition recorded in that package's `doc.go`. Do this **with** the\n`internal/config` dissolution, not ahead of it.\n\n**Agreed next: `internal/app/{archied,agentworker}`.** `run()` in\n`cmd/archied/main.go` is ~460 lines, against `organisation.md`'s rule that\n`cmd/*` must not contain substantive wiring or act as a service locator. It is\nalso the last non-infrastructure holder of the NATS SDK, and it is where the\nconfig DTO translation will land, so it unblocks the dissolution above.\n\n**Method constraint.** Do not write a separate recorded package-review document\nper area when the decisions are already dictated by\n`dependencies-and-contracts.md`. That is the ceremony pattern this project\ndeliberately avoids.\n\n## OPEN — `[chat.*]` config section naming\n\n`configuration.md:160` already states the position: `ChatConfig` holds \"separate\nchannel instance settings... there is no chat-wide settings owner\". The config\nsection name has not followed, so a settings block named for a product surface\nowns what the architecture calls channel state.\n\nTwo candidates, neither settled: `[channel.*]` and `[messaging.channel.*]`. The\nsecond reads as a domain path, and no config section in this repo is currently\nnamed after a domain package, so adopting it sets a precedent for every other\nsection rather than fixing one name.\n\nBlocked on a maintainer decision, not on evidence. This is a rename with an\noperator-visible TOML break, so it should land with the `internal/config`\ndissolution recorded above rather than on its own.\n" + "body": "# Architecture Migration Decisions\n\n**Status:** Active migration inventory \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nThis document records what remains to be decided before Archie's current\nimplementation can be migrated into the approved domain-oriented structure.\n\nThe product and core domain model are not being redesigned. Existing Archie\nbehaviour and the existing session implementation are the migration\nbaseline. Remaining decisions MUST be grounded in current packages, consumers,\ntests, persistence, and runtime wiring.\n\n## Confirmed domain packages\n\n```text\ninternal/domain/\n identity/ (approved, not yet materialised as a package)\n agent/ (approved, not yet materialised as a package)\n workflow/\n messaging/ (canonical Message/Conversation types only; gateway migration pending, see section 2)\n workintake/\n plugin/ (approved, not yet materialised as a package)\n curator/\n mapping/\n scheduling/\n```\n\n- `identity` owns persistent actors, lifecycle, ownership, attribution, and\n audit identity.\n- `agent` owns persistent assistants, specialisation, instructions,\n model-independent continuity, capability context, and associations with\n identity and memory.\n- `workflow` is a separate domain. It owns reusable, versioned Workflow\n definitions, WorkflowSteps, WorkflowExecutions, StepExecutions, Attempts,\n outcomes, and typed Workflow plugin contracts.\n- `messaging` owns canonical Messages, Conversations, branches, channel and\n source correlation, replies, acknowledgements, delivery attempts, events, and\n projections.\n- `workintake` owns admission, validation, deterministic routing, and accepted\n work requests for the optional transition into durable workflow-backed\n execution.\n- `plugin` owns generic plugin identity, discovery, compatibility, and lifecycle\n mechanics. It remains metadata-only; capability semantics and typed\n registration belong to the owning domain.\n- `curator` owns the curator engine family: long-running agent loops that\n reason over memory and perform maintenance tasks on a declared shape\n (check-in interval, tool set, attached memory engine). See epic\n archie-core-yp9.\n- `mapping` owns the payload field-mapping vocabulary: binding named fields to\n JSON paths inside a captured webhook payload, and detecting drift. See\n `docs/prds/payload-field-mapping.md`.\n- `scheduling` owns the ticker engine: deciding when a scheduled job runs and\n with what concurrency. It declares `JobSource`/`Runner` contracts and owns\n no storage or delivery. See epic archie-core-1786637496320-249-be6d9a20.\n\n**Reconciliation (2026-08-31):** `curator`, `mapping`, and `scheduling` existed\nin the tree without being added to this list when their epics landed. They are\nconfirmed as legitimate, narrowly-scoped domains under the same rules as the\noriginal six — each owns one capability family, declares typed contracts, and\nhas no cross-domain reach. This list was out of date, not the tree.\n\nConversely, `identity`, `agent`, `messaging`, and `plugin` are approved target\ndomains that do not yet exist as packages. Their behaviour currently lives in\npre-migration packages (see \"Complete package destination map\" below for the\nfull inventory). Do **not** create empty stub packages for them ahead of an\nactual migration PR — an unused stub is dead code and gives no test coverage.\nEach materialises when its corresponding migration decision below is resolved\nand implemented in the same change.\n\nMemory's final package placement remains undecided pending focused review of the\nexisting implementation.\n\nThe following are approved shared or composition packages, not domains:\n\n```text\ninternal/eventbus/\ninternal/policy/\ninternal/infrastructure/\ninternal/app/archied/\ninternal/app/agentworker/\n```\n\n## Remaining migration decisions\n\n### 1. Complete package destination map\n\nEvery current package MUST receive one explicit disposition:\n\n- move into a confirmed domain;\n- move under infrastructure as an implementation of a domain-owned contract;\n- move into application composition;\n- merge with an identified duplicate;\n- remain as an approved shared application contract;\n- move to a plugin, extra, deployment, example, or generated artifact;\n- be deleted after its replacement is proven.\n\nThe largest unreviewed areas include memory, tools and capabilities, workspace\nand worktree behaviour, gates, storage, events, web UI, containers, RPC\npackages, release management, and scheduling.\n\nThe destination matrix MUST name the behaviour owner, target path, dependencies\nto remove, state and contracts to preserve, migration prerequisites, and\ndeletion criteria.\n\n**`internal/webui` / UI Service — RATIFIED Phase 3 disposition (2026-09-07).**\nThe current owner is the in-process HTTP/SSE dashboard: SPA hosting, operator\nauthentication, UI response projection, configuration reads and mutations,\ntask/control APIs, and direct adapters to State Store, channel, event/log,\nmemory, curator, workflow, forge, and Gateway runtime values. The target owner\nis a standalone UI application process; `internal/webui` remains its HTTP\ntransport adapter, while Gateway, State Store, configuration, Work Intake,\nMessaging, and other capability owners expose the contracts behind those\nroutes. The migration preserves retained route schemas, auth/CSRF behavior,\ntask/capture/mapping/binding/session continuity, SSE replay semantics, and\ncommitted generated SPA assets. Prerequisites are the ratified UI boundary,\nroute-owner inventory, narrow remote adapters, configuration/auth/readiness\ncontracts, and process/conformance tests. Remove the shared live\n`config.Holder`, direct event/log bus, daemon stopper, forge client, channel\nmanager, capability registries, composite store access, and in-process UI\nlistener only after the focused criteria in\n[`docs/prds/ui-service-boundary.md`](/dev/prds/ui-service-boundary/) pass in\nproduction composition. The old construction and listener are deleted in the\nsame cutover change; no second UI authority remains.\n\n### 2. Session and Messaging migration\n\nThe existing session implementation is the migration baseline. The migration must\ndecide:\n\n- which session and message components are retained or adapted;\n- how Agent, user, channel, Conversation, and branch ownership are added;\n- how Archie's parallel gateway session implementation is replaced;\n- how canonical Messages become immutable persisted records;\n- how existing sessions and messages are migrated;\n- how outbound delivery, retry, acknowledgement, deduplication, and failure\n semantics are represented;\n- how current Telegram, email, webhook, forge, and Jira integrations migrate to\n Messaging infrastructure adapters.\n\nThe following are already decided and MUST NOT be reopened without contradictory\nimplementation evidence:\n\n- the composite Conversation identity;\n- immutable MessageIDs;\n- typed tool-call and tool-result messages;\n- exact branch lineage through ParentConversationID and ForkMessageID;\n- parent and child transcript isolation;\n- normal scoped-memory behaviour regardless of the originating Conversation;\n- Messaging and Work Intake ownership.\n\n**Decision (2026-08-31), resolving the open questions above:**\n\n`internal/gateway/` is the \"parallel gateway session implementation\" this\nsection names. It is retained as-is for now — a big-bang rewrite of live\nsession/compression/approval/branch logic across Telegram, web UI, email, and\nwebhook channels in one change is exactly the \"convoluted to satisfy edge\ncases\" failure mode CLAUDE.md's Revert-on-Flail rule warns about, and would\nrisk silent behavioural regressions in the one path every user-facing message\ntravels through.\n\nInstead, `internal/domain/messaging/` is materialised now with the pieces\nthat are already decided and don't require touching gateway: the canonical\n`Message` and `Conversation` types (composite Conversation identity, immutable\n`MessageID`, typed tool-call/tool-result message variants, branch lineage via\n`ParentConversationID`/`ForkMessageID`). These are pure domain types with no\ngateway dependency — a new package, not a rewrite of an existing one.\n\nMigrating `internal/gateway/`'s session, compression, approval, and branch\nlogic onto these types is real, cross-channel-risk work and is **not** done in\nthis pass. It is tracked as separate, appropriately-scoped bd issues (see\n`bd list --label messaging-migration`), sequenced channel-by-channel so each\nlands with its own behavioural verification instead of one large diff no one\ncan safely review.\n\n**Amended 2026-09-15.** `internal/infrastructure/gatewayrpc.StoreClient` is the\nadapter this migration will need: it implements `messaging.SessionStore` over\nthe chat service's session-store RPCs and is proven by\n`TestStoreClientPreservesCanonicalRecords`. It is deliberately unwired.\nProduction `archied` dials the standalone gateway for `ChatContract` only\n(`composeChatContract` → `gatewayrpc.Dial` returns a `*Client`, not a\n`*StoreClient`), and the Gateway's session store is PostgreSQL via\n`gateway.NewPostgresSessionStore`. The test comment that says it mirrors production\ndescribes the target, not today's tree. Kept rather than deleted because the\nmigration it serves is deferred by this very section, and re-deriving a tested\nwire adapter once that lands is pure cost.\n\n**Phase 4 Messaging Service extraction (2026-09-19, `archie-core-8cda.6.1`).**\nThe process boundary for external channels (Telegram, email, webhook) is ratified\nin [`docs/prds/messaging-service-boundary.md`](/dev/prds/messaging-service-boundary/).\nMessaging is extracted into `cmd/archie-messaging` / `internal/app/archiemessaging`,\ncalling Gateway's `messaging.ChatContract` exclusively over gRPC. Channel frontends\nhold no direct database handles, daemon state, or model runtimes.\n\n**Telegram operator surface after extraction (2026-09-19, `archie-core-8cda.6.6`).**\n`setupTelegramGateway` wired eight `telegram.Gateway` seams the daemon could\nsatisfy from its own process. Each is resolved by where the fact it needs is\nactually owned, not by where it used to be built:\n\n| Seam | Resolution |\n|---|---|\n| `Version` | Sourced from the Gateway via `ChatSnapshot.Version`. The Messaging Service never stamps or infers a build version; `cmd/archie-messaging` deliberately takes no version ldflags, so it cannot report a partial upgrade as a matched one. |\n| `Updates` (`/update`) | Built in the Messaging Service from `[chat.telegram].update_check_command` / `update_install_command` — its own configuration. `Enrich` is dropped: `componentInstallTypeEnricher` reads `[nats]`, which this service must not decode, so the check command's own reported install type stands unmodified. |\n| `UpdateReportPath` | A local state file under `work_dir`, keyed by the same `sha256(bot_user)[:8]` scheme the daemon used, so a pending report is found rather than written afresh. |\n| `ReleaseAnnouncements` | **Deliberately left nil**, for the same reason as `RunningVersions`. `releaseannounce.Announcer` announces nothing unless each `Component` carries a parseable version, and the only versions this service can obtain are the Gateway's own build stamps, not archied's. Wiring the announcer without them yields a no-op that reads as configured, so it stays unwired until component self-reporting exists. |\n| `SetShowToolCalls` | Projected from `[chat].show_tool_calls`. |\n| `Reload` | Local: re-resolves the token and allowlist from this service's own config file and overlay. Reload was never a daemon fact. |\n| `RunningVersions` | **Deliberately left nil.** It exists to turn an installer's claim into a checked one, and only a component's own compiled-in build can vouch for it. The Messaging Service knows neither archied's build nor the observed archie-agent version (`daemon.AgentStatus`), and the Gateway's own `gatewayVersion` is a different binary's stamp — reporting it as the daemon's would manufacture exactly the false success the check exists to catch. Update reports therefore relay as unverified claims until a component self-report contract exists. |\n| `Dangerous` | Stays nil. No daemon composition ever set it; `/rollback` and `/stop` reported \"not configured\" before the extraction and still do. |\n\nThe Messaging Service consequently reads `work_dir`, `bot_user`, `[chat]` and\n`[health]` in addition to the PRD's `[chat.*]` / `[services.gateway]` list.\n`[health]` is the daemon's health URL, which `releaseupdate.CommandInstaller`\npolls from outside to confirm an update came back up; the rest of the PRD's\nprohibition list is untouched.\n\n**Phase 4 messaging severance: what must move, and the decision the PRD does\nnot cover (2026-09-22, `archie-core-1ng1`).** The PRD's deletion gate cannot\npass today. `cmd/archie-messaging/architecture_test.go` does not exist, and the\ncheck that section specifies -- `go list -deps ./cmd/archie-messaging` links\nzero banned runtime packages -- reported four at the time (the task store was\nthen `internal/store` over `modernc.org/sqlite`; the gate now bans\n`modernc.org/sqlite`, `github.com/jackc/pgx`, `internal/infrastructure/postgres`\nand `internal/infrastructure/legacyread` in its place):\n\n| banned package | PRD category |\n| --- | --- |\n| `modernc.org/sqlite` | State Store |\n| `internal/store` | State Store |\n| `internal/domain/workflow` | Workflow engine |\n| `internal/agentexec` | Workflow engine, via `internal/domain/workflow/agent.go` |\n\nAll four arrive through one import: `internal/app/archiemessaging/run.go`\nimports `internal/app/controlplane`, whose own dependency set is exactly those\nfour. The Messaging Service uses three symbols from that package\n(`NewRPCClient`, `RuntimeChatConfig`, `ChannelSettingsKind`); the package also\ncarries the store-backed `ResourceStore` server, the `Definition` registry and\nthe workflow step vocabulary. Sever the package. Amending the gate to tolerate\n`modernc.org/sqlite` and `internal/store` is rejected: a boundary you whitelist\naround is no longer a boundary.\n\n**What moves.**\n\n- Every kind constant. They are strings with no dependency, and the client names\n them.\n- The channel-settings vocabulary and its decode: `channelSettings`,\n `telegramSettings`, `webhookChannelSettings`, `emailSettings`,\n `rateLimitSettings`, `channelDuration`, and `decodeRenamingLegacyKeys`.\n- The generic client: `Client`, `NewRPCClient`, `RuntimeConfig` with\n `runtimeConfigFrom`, `runtimeChatConfigFrom`, the other `runtime*From`\n projections, and the `resourceReader` interface.\n- The persona watch (`WatchPersonas`, `AppliedPersonas`), which needs only\n `internal/domain/agent`.\n- `executionSettingsDocument`, the document alone.\n\n**What stays, and why.**\n\n- The store-backed server: `Server`, `NewServer`, `ResourceStore`,\n `ImportConfig`, `SeedSkip`, the `Definition` registry, and every other kind's\n seed, validator and `Normalize` hook.\n- `WorkflowDefinitionsClient` and `stepRegistry`, which decode through\n `internal/domain/workflow`.\n- `WatchWorkflowExecutionSettings` and `decodeSettings`: `decodeSettings`\n returns and validates `workflow.ExecutionSettings`, so any package holding it\n links the workflow domain and therefore `internal/agentexec`. This is why the\n client cannot move as one package -- see open question 2.\n- The schedules document, whose type is `scheduling.JobSpec` in\n `internal/domain/scheduling` -- the vocabulary moved there when the legacy\n file-backed cronstore was deleted, which is also what satisfies the rule\n that a domain vocabulary package may not import infrastructure.\n- The schema derivation, which describes the documents the server advertises.\n\n**Placement as landed (2026-09-22, `archie-core-1ng1`).** One new package,\n`internal/infrastructure/controlplanerpc`, holding both the vocabulary (kinds, the\nchannel-settings document and its decode) and the client\n(`NewRPCClient`, `Query`, `RuntimeChatConfig`, the exported `ResourceReader`, the\nwire sentinels and `ClientError`). A second `internal/domain/controlplane` package\nfor the vocabulary was planned and then measured out of the design: the vocabulary\nhas exactly one consumer, the client that projects it, and the store-backed side\nreads the same definitions through type aliases rather than a copy -- so a separate\ndomain package would have been a package with one consumer and a second name for\none thing. What made that safe is a measurement, not a preference:\n`internal/app/controlplane` was the ONLY direct import of the Messaging Service\nthat dragged a banned runtime (`gatewayrpc`, `staterpc`, `applystatus`, `messaging`,\n`configuration`, `readiness` and `health` were all clean), so severing that one\ndependency is sufficient, and the severance needed no third package. Promoting the\nvocabulary to a domain package stays open for the day a second consumer appears.\n\n**Settled by the implementation.** Two of the four open questions this decision\noriginally left are answered, in both cases by measuring rather than by preference:\n\n- The client did NOT become two packages. `WatchWorkflowExecutionSettings` and\n `WatchPersonas` stayed on `internal/app/controlplane`'s `Client`, which now\n *embeds* the new one, so the daemon's validated watch is still defined once and\n the read path still has one implementation -- which is what the second package\n was for -- with one fewer package to keep in step.\n- The schedules and workflow documents stayed put, and\n `internal/domain/workflow/task` is linked deliberately: it carries the Task\n status and view vocabulary, its own dependency set holds none of the banned\n runtimes, and `cmd/archie-messaging/architecture_test.go` carries it as an\n exception checked in both directions (the same entry, for the same reason, as\n `cmd/archie-ui/architecture_test.go`).\n\n**Still open.**\n\n1. Does the server also leave `internal/app/`? `organisation.md` reserves\n `internal/app/` for wiring and composition, and a store-backed gRPC server is\n infrastructure -- but the gate does not require the move, and it would multiply\n the diff across archied's wiring and the State Store binary. Tracked as\n `archie-core-8f4n`.\n2. Does `internal/domain/workflow`'s contract/engine split happen, and when? A\n contract type (`WorkflowDefinitionCollection`) drags `internal/agentexec` only\n because `agent.go` sits beside it. Independent of this severance, tracked as\n `archie-core-inh6`, and the shape `archie-core-8cda.7` will meet again.\n3. Does the vocabulary move to a domain package when a second consumer appears?\n\n**Both consumers keep compiling.** archied imports the new vocabulary for the\nkinds it names and the new client package for `RuntimeConfig` and the persona\nwatch, and keeps `internal/app/controlplane` for the server, the registry,\n`ErrVersionConflict` and the workflow-aware pieces. The State Store binary\ncontinues to call `NewServer` and `ResourceStore` unchanged. The Messaging\nService then imports only `internal/infrastructure/controlplanerpc`,\n`gatewayrpc` and `staterpc`, so `go list -deps ./cmd/archie-messaging` loses all\nfour banned packages and the gate can land green.\n\n**Channel state to the dashboard: one administrative surface, following the\nconfig-snapshot precedent (2026-09-22, `archie-core-8cda.6.8`).** The Messaging\nService now records its channels' lifecycle -- `internal/channels/status.Manager`,\none entry per composed channel, written by each channel's own report through\n`channels.Lifecycle` -- and nothing reads that across a process boundary.\n`/api/channels` answers with nothing because `webui.Server.Channels` has no\nproduction source, and POST `/api/channels/{id}/reload` answers 501 for the same\nreason. The carrier is the State Store, and the shape is the one\n`archie-core-ymut` already established for config snapshots\n(`docs/prds/state-store-contract.md`, \"the one surface whose writer is the daemon\nand whose reader is the UI process\"): a pair of administrative RPCs, deny-by-default\nunder `authorizesTaskScopedCall`, so a task-scoped grant reaches neither.\n\nWhat that decides, so the implementation need not invent it:\n\n- A channel's state is **runtime** state, not a settings document. It does not\n belong in the `ControlPlaneService` resource kinds, which are validated,\n versioned documents seeded from config; a channel that is failed is not a\n document anybody edits.\n- The reader is the UI process, which already dials the State Store and pumps its\n cursor, so the surface needs no new transport in either direction.\n- Adding the pair changes the contract's RPC count, so\n `docs/prds/state-store-contract.md`'s grouped table gains a group in the same\n change that adds the RPCs -- the table is the contract's own index, and a\n surface it does not list is a surface nobody finds.\n\n**Reload gets its own surface, with its own lifetime (decided 2026-09-22).** Reload\nruns the other way -- the UI asks the service to reload a channel -- and the two\ncandidates were a request surface the service observes and clears, or a field on\nthe status surface the service watches. It is the first. The reasoning, recorded\nbecause it would look arbitrary later:\n\n- A request queue and a status report do not share a lifetime, so they should not\n share a surface. A pending request is transient and has an outcome; a channel's\n state is durable and has a current value.\n- A \"please reload\" field on the status resource makes READING status capable of\n RETRIGGERING an action, and makes a transient request indistinguishable from\n state the moment anything polls it.\n- It would also invert the writer/reader relationship the precedent establishes:\n the service would have to clear a field on an object whose whole contract is\n that the service reports it.\n\nSo the status surface stays writer-is-service, and the request carrier is its own\nobject with its own states.\n\n`archie-core-8cda.6.9`'s component self-report is the **same shape**: a process\nreporting something about itself for the UI to read. Whether it shares this\nsurface or gets its own is a decision for `6.9`, and the one outcome to avoid is\ntwo homes for \"what a component reports about itself\".\n\n### 3. Identity data migration\n\nThe migration must define:\n\n- the durable identity schema and repository implementation;\n- bootstrap of the permanent system identity;\n- stable IdentityIDs for existing configured Agents;\n- migration from configured identity names, empty-string ownership, and bot\n usernames;\n- preservation of historical attribution;\n- identity-aware uniqueness and transport deduplication;\n- correction of container and RPC capability resolution so execution uses the\n owning identity's bindings;\n- removal of identity-string equality from access-control behaviour.\n\nExact schema and method signatures are implementation decisions. The approved\nIdentity lifecycle and attribution semantics are fixed migration constraints.\n\n### 4. Workflow migration\n\nThe current implementation must be transformed deliberately:\n\n```text\nstore.Task -\u003e WorkflowExecution\nmutable Stage -\u003e StepExecution history\nRetryCount / Attempt -\u003e Attempt records\nworkflow.Registry -\u003e versioned Workflow definitions\ncurrent stages -\u003e WorkflowStep definitions or Workflow plugins\n```\n\nThe migration must decide:\n\n- Workflow definition and version persistence;\n- the smallest accepted-work-request contract consumed from Work Intake;\n- the enforced WorkflowExecution state machine;\n- atomic state and domain-event persistence;\n- migration of existing task rows and transition history;\n- disposition of current skill, Yaegi, and stage-plugin implementations;\n- the versioned worker-handoff contract;\n- scheduler, claim, retry, crash-recovery, and waiting-human cutover.\n\nWorkflow remains a separate domain from Agent. A user or Agent may define or\ninvoke a Workflow, but Workflow semantics and plugins remain Workflow-owned.\n\n### 5. Memory placement and storage\n\nThe four required scopes are fixed:\n\n- global shared;\n- Agent-wide;\n- user-wide;\n- Agent-user relationship.\n\nA focused review of `internal/memory`, its providers, consumers, persistence,\nand tests had these decisions:\n\n- `internal/domain/memory` versus ownership within the Agent domain — settled\n (2026-09-02, below);\n- the authoritative memory record and revision model — settled by the PRD\n (2026-09-16, below);\n- provider and infrastructure boundaries — settled by the PRD (2026-09-16,\n below);\n- retrieval and access enforcement — settled by the PRD (2026-09-16, below);\n ranked retrieval remains open (below);\n- migration of existing memory data — open: existing data is not migrated;\n- provenance representation — settled by the PRD (2026-09-16, below).\n\nConversation branches do not create another memory scope. A memory action has\nthe same scoped effect regardless of which Conversation originated it.\n\n**`internal/domain/memory` ownership — DECIDED (2026-09-02).** The typed\nengine family lives at `internal/domain/memory`\n(archie-core-1786637490069-11-e245c170), mirroring `internal/domain/curator`'s\ncontract/registrar/registry split. Not owned within the Agent domain: memory\nis consumed by more than agent turns (curators, per archie-core-1786637499636)\nand the plugin engine rule requires its own family, not a capability bolted\nonto another domain's contract.\n\n**Authoritative record and revision model for the builtin engine — DECIDED\n(2026-09-02),** scoped to unblock archie-core-1786637499480 (ship the\nfile-writing store as the default engine). This decides only the builtin\nengine's mapping onto the new `Record{ID}`/`Forget(id)` contract, not the\nmemory model in general or a future non-file engine's model:\n\n- `internal/memory/builtin.Store` is unchanged. It has no concept of a\n stable per-block ID — blocks are addressed by content substring — and nothing\n in this decision requires changing that; existing `internal/memory` tests\n keep passing unmodified, per that issue's acceptance criteria.\n- A new infrastructure adapter (`internal/infrastructure/memory`, per\n `organisation.md`'s \"infrastructure implements domain contracts\" rule — not\n under `internal/domain/memory`, which stays contract-only) wraps one\n `builtin.Store` per identity.\n- **Identity → directory:** `hex(sha256(identity))`, not the identity string\n itself. Closes the path-traversal question without an allowlist regex, and\n sidesteps collisions from identities that differ only in characters a\n filesystem treats as equivalent.\n- **Record ID:** assigned once at `Write`, independent of content, so a later\n edit elsewhere in the file can never orphan a `Forget`. Realized as a\n leading marker line (`\u003c!--mem:\u003culid\u003e--\u003e`) on the block `builtin.Store.Add`\n writes; `Query`/`List` strip it back out of `Record.Content` before\n returning, and `Forget(id)` locates the block by that unique marker via the\n store's existing substring-based `Remove`. The marker is a pragmatic,\n reversible choice — plain-text records stay human-readable and\n human-editable, at the cost of one marker line an operator editing the file\n by hand should leave alone. Revisit if/when provenance representation\n (still open, below) settles on something richer.\n- **Kind → section:** `Observation.Kind` (default `\"general\"` when empty) is\n the section name, reusing `builtin.ValidateSectionName` — so an\n invalid `Kind` fails `Write` with the same validation error `memory_edit`\n already returns for an invalid section today, not a new error shape.\n\n**Memory engine: scopes, CRUD with retained revisions, and store placement —\nDECIDED (2026-09-16).** Supersedes the 2026-09-02 \"Authoritative record and\nrevision model for the builtin engine\" entry above, whose `\u003c!--mem:\u003culid\u003e--\u003e`\nlive marker cannot carry provenance. Authority:\n[`docs/prds/memory-engine-unification.md`](/dev/prds/memory-engine-unification/)\n(Approved); the contract is `internal/domain/memory/contract.go`. This register\nsupersedes; it does not erase.\n\n- **Four typed scopes, caller-named.** `internal/domain/memory` is addressed by\n `Scope{Kind, Agent, User}` over `global`, `agent`, `user` and `agent-user`,\n with `Validate` rejecting a component present where it is not required. A\n caller names the read and write sets (`Subject.Scopes()` /\n `WritableScopes()`; global is never model-writable) and the engine applies no\n policy of its own: **access control is naming a scope, and nothing else.** An\n engine that enforced policy would need to know about channels, sessions and\n bindings, and every backend would reimplement it. `Scope.Key()` length-prefixes\n each component, so two scopes can never share a key even when an opaque\n channel-native id embeds the separator.\n- **The caller resolves identity; the engine never does.** Resolution happens in\n the gateway turn path, where the native sender id and the session are both in\n hand, and is supplied per channel by the composition. A webhook's sender id is\n a route path, not a person, and treating it as one would give a URL an\n identity. An absent user id yields global and agent scopes only: \"show none of\n it\", never a wider fallback.\n- **CRUD supersedes, never overwrites.** `Store` is `Create`/`Get`/`Query`/\n `List`/`Update`/`Forget`/`Revisions` over the four scopes. `Update` appends the\n superseded state to the scope's `HISTORY.md` before replacing the live block;\n `Update.Expected` names the revision being replaced and returns\n `ErrStaleRevision` on mismatch, making a lost update between two processes\n sharing one scope file detectable. `Forget` records a deleted revision before\n removing the live block, so a record's provenance outlives its content; `Get`\n and `Forget` take a scope, because an id alone does not locate one.\n- **Provenance representation.** The live marker becomes JSON, since a\n `\u003c!--mem:\u003culid\u003e--\u003e` line cannot carry provenance, and `Record` retains the\n provenance `agent-system.md` requires — scope, author, originating user,\n source, and revision history. `Metadata` is dropped: it never round-tripped.\n- **Store and scanner placement.** The markdown store relocates to\n `internal/infrastructure/memory/builtin`, its correct home under\n `organisation.md`'s \"a package owns its on-disk format end-to-end\". The content\n scanner moves into `internal/domain/memory` and is applied in `Create` and\n `Update` — the single choke point every producer crosses, so curator-extracted\n content is covered too.\n\n**Open in this section.** Ranked retrieval is deferred: `Query.Text` stays in\nthe contract, unused by the prompt path. Existing memory data is not migrated:\n`\u003cworkDir\u003e/memory` and `\u003cworkDir\u003e/memory-engine` are left on disk, unreferenced.\nThe PRD leaves these undetermined and they remain open here: group-chat\nextraction, where the curator fails closed on mixed-sender sessions; two\nprocesses (`archied` and `archie-gateway`) holding one scope file, where\n`Update.Expected` detects but does not prevent a lost block; unbounded\n`HISTORY.md` with no compaction policy; whether the per-scope size bound is\nright; and whether the dashboard should carry a user identity.\n\n### 6. Runtime and process boundaries — DECIDED\n\n`archied` is the native resident orchestration and interactive-chat process.\nEvery autonomous repository workflow crosses one full-task core-NATS handoff\ninto a task-scoped `archie-agent` container. Embedded versus external NATS\nchanges broker deployment only; it never selects an executor. The former host\nin-process runner, per-stage NATS protocol, and subprocess runner are removed.\n\nForge, store, and worktree authority remains in `archied` and is exposed to the\ntask container through scoped RPC services. The worker runs the workflow and\nits worker-local ai-sdk loop; it does not receive forge credentials or direct\nstore access. See `docs/prds/embedded-nats.md`.\n\n**UI Service boundary — RATIFIED (2026-09-07).** Phase 3 has a focused\nauthority record in [`docs/prds/ui-service-boundary.md`](/dev/prds/ui-service-boundary/).\nThe UI Service owns HTTP/SPA delivery, UI DTOs, browser authentication, and\nits own endpoint/credential/readiness settings. It consumes Gateway and State\nStore contracts and does not receive `config.Holder`, daemon pointers, SQL or\nstore implementations, workflow registries, forge/channel/model runtimes, or\nresolved secrets. The current `internal/webui` implementation remains inside\n`archied` until the ratified migration gates prove route parity, adapter\nselection, failure/readiness behavior, and deletion of the shared-holder and\ndirect-access paths. The extraction cutover removes the in-process UI\nlistener in the same change; there is no dual-live UI authority.\n\n**Dashboard live event delivery — DECIDED (2026-09-09, `archie-core-za9f`).**\nThe extracted UI receives live activity by polling the State Store's existing\n`EventsSince` cursor, not by a new push-subscription RPC. No proto change, no\ncontract amendment beyond this record.\n\nThe UI process runs one event pump. It primes its watermark by paging\n`EventsSince` to the end at startup without delivering, then polls\n`EventsSince(watermark, limit)` on an interval and hands each new event to\n`webui.Server.Broadcast`, exactly where `internal/app/archied/main.go`'s\n`persistAndBroadcastEvents` hands events to it today. One pump serves every\nconnected browser, so cost is one indexed query per interval regardless of\nviewer count, and `Broadcast` is a no-op when nobody is watching.\n\nThree properties make the cursor sufficient, and a push hub unnecessary:\n\n- **The cursor cannot skip.** `internal/infrastructure/postgres` takes an\n advisory event-append lock around each insert (`TestEventInsertsCommitInIDOrder`),\n so a row's `id` is assigned in commit order. There is no window in which a lower id becomes visible after a\n higher one, which is the failure mode that normally rules out polling an\n autoincrement cursor. SSE catch-up already depends on this same property.\n- **A broadcast is a wakeup, not the payload.** `sseStream.drain` treats each\n broadcast event as a signal to fill the persisted gap ahead of it via\n `catchUp`, then delivers the event only if catch-up did not already cover\n it, deduplicating on the `since` watermark. Substituting a poller for the\n in-process bus therefore changes no SSE semantics, and needs no change to\n `internal/webui/sse.go`. It also means a broadcast dropped to a stalled\n client self-heals on the next one.\n- **The table is the only complete fan-out point.** Events reach the store\n through several paths that never touch the daemon's bus, including the\n audit event `store.ArchiveTask` writes inside its transaction\n (`internal/infrastructure/postgres/store.go`) and the binding-dispatch failure\n `internal/daemon/daemon.go` inserts directly. A push hub would have to be\n hooked at every write site and at post-commit, and would silently miss any\n site added later that forgets to notify. Reading the table misses nothing.\n\nThe cost is one poll interval of latency on the activity feed, default 1s and\noperator-tunable. That is accepted: the feed reports task lifecycle history,\nand an operator action already gets its own synchronous HTTP response.\n\nThis resolves the `/events` row of the route-owner inventory in\n[`ui-service-boundary.md`](/dev/prds/ui-service-boundary/). `/api/logs` and\n`/api/logs/stream` are not resolved by it, they read the daemon's in-process\ndiagnostic feed and remain host-local (see `archie-core-8cda.5.4`).\n\nRevisit only if sub-second feed latency becomes a requirement, or if a second\nconsumer needs the same stream, at which point the fan-out belongs in the State\nStore process behind a `SubscribeEvents` RPC and this record is superseded.\n\n**Dashboard configuration page — DECIDED (2026-09-09, `archie-core-ymut`).**\nThe configuration page becomes read-only in the UI process for Phase 3. Reads\ncross the boundary as a published snapshot; writes are descoped, not\ncontracted. This amends the ratified boundary, which assumed a single admin\ncontract carrying both.\n\n**Reads.** `webui.ConfigView` is already the whole answer. It is a UI-owned,\nsecret-free value projection built in `handleConfig`: `ProviderView` carries\nthe API key's environment variable name and a `Configured` boolean, never a\nvalue, and `RepoView` is repository metadata only. It is already the exact\nshape the browser receives. So the daemon publishes that projection, plus\nprovenance, reload status and the overridden-key list, as a snapshot the UI\nreads; nothing new has to be designed, only moved. Two State Store RPCs carry\nit, a `PutConfigSnapshot` restricted to the administrative token and a\n`GetConfigSnapshot` the UI calls. The daemon republishes on boot and after\neach successful reload, which is precisely when the projection changes.\n\nThe State Store is the right holder because a published configuration snapshot\nis shared state, it is already dialled by the UI, and it costs no new listener,\nport, token or interceptor. The alternative, a config admin service on\n`archied`, would make the daemon a gRPC server for the first time. Today it is\npurely a client of Gateway and State Store; `grpc.NewServer` appears only in\n`RunGateway` and `RunStateStore`, which are the standalone binaries' entry\npoints, not the daemon's.\n\n**Writes.** `PATCH /api/config`, `POST /api/config/reset` and\n`PATCH /api/config/repos/{owner}/{name}` answer 503 in the UI process, and the\nSPA hides those controls rather than offering a button that fails. Editing is\n`config.toml` plus reload, which is already the only path for every setting\noutside the runtime-tunable allowlist.\n\nThis is a deliberate feature reduction and worth naming as one. The write path\nis not hard because of the transport; it is hard because the policy is\ndaemon-local and stays that way: `installUpdateConfigHandler` denies\nnon-runtime-tunable keys, applies a dotted overlay to a clone of the published\nconfig, validates the materialised result, writes overlay rows, and rebuilds\nprovenance. Contracting that means either moving the policy, which the\nboundary forbids, or exposing it verbatim as remote procedure calls, which\nbuilds a Configuration Service inside a migration bead. Neither is work this\nphase should be doing to keep one page's buttons alive.\n\nRevisit when dashboard configuration editing is picked up as a feature in its\nown right (`archie-core-1786637498420-327`, still open). At that point it gets\nan admin contract designed as a feature, and the Configuration Service this\ndocument already anticipates is its natural owner. Until then the UI renders\nconfiguration and does not write it, which is what the boundary always said\nabout ownership even when it assumed a wider contract.\n\nAmended 2026-09-11. This descope is a deferral, not a decision that the\ndashboard should be read-only. Name it that way in review: the daemon-side\npolicy was built and tested, then deleted by the cutover (`e037b95` removed\n`internal/app/archied/config_update.go` and its tests), so reviving it is\nrecoverable work, not a rewrite. `archie-core-j28m` carries the remaining\nquestion -- which process serves the policy and what transport carries the\nwrite -- and blocks the feature bead. The handlers, their error sentinels and\nthe `UpdateConfig`/`ResetConfig`/`UpdateRepoField` seams on `webui.Server` are\nkept deliberately for it; `ConfigView.Editable` follows whichever process holds\n`UpdateConfig`, so wiring that one field makes the page editable\n(`archie-core-ml30`).\n\nImplementation belongs to `archie-core-8cda.5.4`, the cutover that removes the\ndaemon's own dashboard. Nothing here is built yet.\n\n**Superseded 2026-09-21 by the runtime control plane.** The open question this\ndescope left -- which process serves the policy and what transport carries the\nwrite -- was answered by `docs/prds/runtime-control-plane.md`: neither a daemon\nadmin service nor a revival of the daemon-local policy. `ControlPlaneService` on\nthe State Store's existing gRPC server owns every database-backed setting, and\neach feature validates its own resource, so there is no daemon-local policy left\nto contract. `archie-core-j28m` is closed.\n\nConsequently the three write seams described above no longer exist.\n`PATCH /api/config`, `POST /api/config/reset` and\n`PATCH /api/config/repos/{owner}/{name}`, the `UpdateConfig`/`ResetConfig`/\n`UpdateRepoField` fields on `webui.Server`, and `ConfigView.Editable` were\ndeleted in `31622ec5` along with the runtime overlay store they wrote to.\n`GET /api/config` remains a read of the published projection, as this decision\nalways intended.\n\n### 7. Shared mechanics\n\nThe following cross-domain mechanics require exact contracts before dependent\npackages migrate:\n\n- event-bus delivery and failure semantics;\n- policy evaluation API, composition, and precedence;\n- configuration candidate preparation, health validation, atomic promotion,\n observation, and rollback;\n- service-specific health, bounded remediation, isolation, and escalation;\n- changelog association and grouping.\n\nThese shared mechanisms do not acquire ownership of domain meaning. Domains\ncontinue to own their commands, events, policies, settings, and consequences.\n\nThe Go documentation generator, its output placement, and drift checking are\ndefined in `generated-documentation.md`. The VitePress site and its Pages\ndeployment were removed on 2026-09-12 as an unnecessary build step; `docs/` is\nrepository documentation only. The rendering and publishing surface is an open\ndecision, and so are the renderer's page templates and any developer commands\nor CI sequence that would accompany one. Adapting the generator and implementing\nArchie's normalized documentation model remain migration work rather than open\nproduct architecture.\n\n**Amended 2026-09-15.** `internal/infrastructure/servicediscovery/nats`\nimplements the `servicediscovery.ServiceRegistry` contract (Connect, Register,\nResolve, Watch) over NATS KV and is fully tested, but no production code\nconstructs it and no config surface exposes it. This is a deliberate deferral,\nnot an oversight: service-to-service addressing belongs to the runtime and\nprocess boundary work in section 6, which currently pins container addressing\nby injecting the daemon's startup NATS URL rather than resolving through a\nregistry. The scaffold is kept for that work; re-derive it only if the\naddressing model changes.\n\n### 8. Cutover sequence\n\nThe final migration plan must order:\n\n- compatibility adapters;\n- schema migrations and data backfills;\n- any required dual-read or transitional paths;\n- domain-by-domain package replacement;\n- production wiring changes;\n- legacy package removal;\n- architecture tests preventing dependency regression;\n- focused, integration, race, and full quality gates.\n\nEach legacy package requires objective removal criteria. No compatibility path\nmay become an indefinite second implementation.\n\n\n## Completion criteria\n\nMigration design is complete when:\n\n- every current package has one approved owner and destination;\n- every mutable record has one authoritative owner and migration path;\n- all external and cross-process contracts have versioned owners;\n- existing behaviour and data have explicit parity requirements;\n- process boundaries have evidence-backed justification;\n- the cutover order preserves a working application;\n- legacy deletion criteria and deterministic architecture tests are defined;\n- no unresolved decision requires an implementer to invent domain semantics.\n\nExact Go APIs, SQL statements, and mechanical refactoring steps MAY be finalized\nduring implementation when they do not change these semantics.\n\n## Recorded migration position (2026-07-29)\n\nRecovered 2026-08-09 from the pre-migration issue tracker. This section records\ndecisions the maintainer approved that the repository did not otherwise capture.\n\n**Completed:** `internal/infrastructure/eventbus/nats` (rebuilt, not relocated);\n`internal/infrastructure/configuration` (loading moved out of `internal/config`,\nwhich is now types-only and does no I/O); `internal/eventbus` (broker-neutral\ncontract); `internal/domain/workintake` (the first `internal/domain/` package,\nowning `TaskEnvelope`, the routing `Kind`, the label vocabulary, and task\nsubjects).\n\n**DECISION — private input DTO deferred (approved).**\n`configuration.Document.Config` is still `internal/config.Config` rather than the\nprivate per-domain input DTO this document mandates. Building an ~800-line\nparallel type tree while every consumer still reads `config.Config` would mean\ntwo shapes kept in sync by hand, with no consumer for the new one. It is named as\na field so the compromise is visible at each use site, with the deletion\ncondition recorded in that package's `doc.go`. Do this **with** the\n`internal/config` dissolution, not ahead of it.\n\n**Agreed next: `internal/app/{archied,agentworker}`.** `run()` in\n`cmd/archied/main.go` is ~460 lines, against `organisation.md`'s rule that\n`cmd/*` must not contain substantive wiring or act as a service locator. It is\nalso the last non-infrastructure holder of the NATS SDK, and it is where the\nconfig DTO translation will land, so it unblocks the dissolution above.\n\n**Method constraint.** Do not write a separate recorded package-review document\nper area when the decisions are already dictated by\n`dependencies-and-contracts.md`. That is the ceremony pattern this project\ndeliberately avoids.\n\n## OPEN — `[chat.*]` config section naming\n\n`configuration.md:160` already states the position: `ChatConfig` holds \"separate\nchannel instance settings... there is no chat-wide settings owner\". The config\nsection name has not followed, so a settings block named for a product surface\nowns what the architecture calls channel state.\n\nTwo candidates, neither settled: `[channel.*]` and `[messaging.channel.*]`. The\nsecond reads as a domain path, and no config section in this repo is currently\nnamed after a domain package, so adopting it sets a precedent for every other\nsection rather than fixing one name.\n\nBlocked on a maintainer decision, not on evidence. This is a rename with an\noperator-visible TOML break, so it should land with the `internal/config`\ndissolution recorded above rather than on its own.\n" }, { "url": "/dev/architecture/observability/", "title": "Task Observability", "section": "Architecture", - "body": "# Task Observability\n\n**Status:** Implemented. The per-run detail surface was added on 2026-09-18 and\nis described below.\n**Date:** 2026-08-09 (revised 2026-09-18)\n\n## Historical problem\n\narchied's own daemon logging (`internal/logging/`) was already solid: a\nrotating file sink, a live `Feed` the dashboard subscribes to, and a reader\nthe `/api/logs` endpoint serves from. Before this implementation, none of\nthat reached inside a task.\n\nA task's actual work happens in a task-scoped `archie-agent` container,\ndispatched as one complete workflow over NATS.\nBefore this design was implemented, five things destroyed the evidence of what\nthat container did:\n\n1. **Worker startup** constructed an stderr-only logger and never replaced its\n handler after discovering a dedicated boot task, so runtime records could\n not leave the container.\n2. **`internal/container/pool.go`** creates every task container with\n `AutoRemove: true`. The container — and its stderr — is gone at exit,\n success or failure alike.\n3. **`internal/domain/workflow/implement.go`, `StageBaselineGate`** captures\n `go build`/`go vet`/`go test` output via `cmd.CombinedOutput()`, then\n clips it to 200 characters into a `Warn` log line and discards the rest.\n The eventual park reason is built from `res.Status` alone — the actual\n compiler error is never persisted anywhere a human or Archie's own chat\n tools can read it back.\n4. **`agentexec.Result`** (`internal/agentexec/protocol.go`) carries only\n `Summary`/`Detail` — no step-by-step transcript (tool calls, durations,\n errors). There is no transcript to recover even in principle.\n5. **`agentexec.SubjectForSystem`** is documented as the return channel for\n exactly this — *\"log dumps, health, and PII warnings... the daemon reads\n these for observability and never forwards them\"* — but has no publisher\n and no consumer anywhere in the codebase except a subject-format\n assertion in `nats_test.go`. The designed return path was never wired.\n\nThe practical consequence: a task parks with\n`stage baseline: baseline red -- go build ./... fails and builder could not\nauto-fix (status: parked)` and there is no way — not from the dashboard, not\nfrom Telegram chat, not by SSH'ing into the deployment host — to see *why*\n`go build` failed. The container that knew is already gone.\n\nThis matters beyond debugging convenience: supported deployments can combine\na resident daemon with ephemeral Docker containers that run unattended for\nweeks between operator logins, and the system is\nintended to be usable by people other than the original operator. A system\nthat is only debuggable by an operator who happens to be watching `docker ps`\nin real time does not meet that bar.\n\n## Decision: NATS is the sole autonomous handoff\n\nThe agent image must reach NATS in every deployment, because the broker is the\nonly autonomous task handoff and the only channel carrying task results back\nto the daemon. `archied` has no workflow runner or host fallback. A container\nthat dies before establishing a NATS connection is a distinct, narrower\nfailure (connectivity/config) from the one this document addresses (a connected\ncontainer's own output being unrecoverable), and is out of scope here.\n\n## Implemented design\n\nThe key property: **logs leave the container while it is alive**, so its\ndeath at `AutoRemove` no longer matters. Persistence happens in the daemon\nprocess, which already owns durable state.\n\n### Sink: extend `internal/logging`, not a new package\n\n`internal/logging` already owns its on-disk format end to end per\n`organisation.md` (\"a package owns its own format end to end\"). Add a\ntask-scoped writer producing the same `logging.Entry` JSONL shape at\n`\u003cstate_dir\u003e/logs/tasks/\u003ctask_id\u003e/attempt-\u003cn\u003e.jsonl`. `logging.Tail`,\n`logging.Query`, and `logging.Components` operate on this unchanged;\n`internal/webui/api_logs.go` stays transport-only, as it does today.\n\n### Agent side: make the designed subject real\n\n`internal/app/agentworker` replaces the stderr-only `slog.Handler` with one\nthat tees to stderr (kept for container-level operator debugging when a\nshell is attached) and publishes each record to\n`agentexec.SubjectForSystem(taskID)`, which already exists for this purpose.\nThe application layer obtains only a narrow publisher from\n`internal/infrastructure/agenttransport/nats`; raw core-NATS types remain in\ninfrastructure. `internal/infrastructure/agentboot.TaskID` reads the task ID\nfrom `\u003cworktree\u003e/.git/task.json` per the container/pool.go trap documented in\n`CLAUDE.md`. Publishing is fire-and-forget: log shipping must never block or\nfail the run it is reporting on.\n\n### Daemon side\n\n`cmd/archied/main.go` registers `subscribeSystemLogs` once at startup on\n`agentexec.SubjectSystemWildcard`. It demultiplexes by task ID, appends to that task's\nsink, and publishes into the existing `logging.Feed` so live task output\nappears on the dashboard exactly like daemon output. The approved target is\nfor this composition to move to `internal/app/archied`; that package does not\nyet exist, so this document does not claim the migration is complete.\n\nThe daemon is also a writer in its own right for the decisions only it makes.\nEvery park records its reason into that attempt's sink (`daemon.recordPark`),\non the daemon side after the guarded transition lands and in\n`workflow.park` on the agent side, because \"why did this park?\" is the question\nthe log exists to answer and the container path cannot answer a run that never\nreached a container. The entry is written only once the park actually\nhappened, so a transition another actor won does not leave a log claiming an\noutcome the task board contradicts.\n\n### Gate output: stop discarding it\n\n`StageBaselineGate` and the equivalent TDD-stage gate runs write full\n`cmd.CombinedOutput()` to the task's sink under a `gate` component, and put a\nbounded tail (~2KB, not 200 bytes) into the park reason. This is the cheapest\nfix and independently valuable — it alone would have made the `go build`\nfailure diagnosable without any NATS plumbing.\n\n### Transcript\n\nStep-level events (tool name, argument digest, duration, error) are emitted\nas log entries on the same NATS system subject rather than added as new\nfields on `agentexec.Result`. This keeps the wire protocol\n(`internal/agentexec/protocol.go`) stable and the transcript lands in the\nsink automatically, with no separate delivery path to keep consistent.\n\n### Retention\n\nReuse the existing rotation (`MaxSizeMB`/`Keep`) semantics per task\ndirectory. Prune a task's log directory when `store.ArchiveTask` archives\nit, so task logs share the task's own\nlifecycle rather than accumulating independently.\n\n### Surfaces\n\n- `/api/tasks/{id}/logs`, built on `logging.Reader` the same way\n `/api/logs` is today.\n- A chat tool so Archie can answer \"why did task 4 park?\" directly from\n Telegram or the webui chat — this is the surface that actually matters\n for the deployment model in `CLAUDE.md`, where an operator may not be\n looking at a dashboard at all.\n- The per-attempt read surface described in the next section, on top of the\n same task-scoped stream.\n\n## Per-run task detail (attempts, stages, changes, config)\n\n**Status:** landed, together with the change set that carries this revision\n(workflow run `76f8e877`). The provenance half is in the tree: `events.Event.Attempt`,\nthe `changes_captured` and `config_captured` event kinds, and the two protobuf field\nadditions. So is the read half: the three per-attempt endpoints\n(`/api/tasks/{id}/attempts`, `/changes`, `/debug`) and the dashboard run-detail page\nthat consumes them. The decision record, the rejected alternatives and the honest\nlimits are `docs/prds/task-run-detail.md`.\n\nThe task log surface above answers *why did this park?*. This surface answers\n*what did this run actually do?*, per attempt.\n\n### Attempt attribution\n\nOne task can run many times, and the task's event stream is the durable record\nof all of them. `events.Event.Attempt` attributes each event to one run; `0`\nmeans **not attributable** — every event written before this change, plus the\ndeliberately task-agnostic producers. An unattributed event is reported as a\ncount and is never presented as an attempt.\n\nAttribution is a column, not a fold over `task_queued`/`task_retried`: a fold\nwould have to guess which side of a boundary an event belongs to across a daemon\nrestart, a stale-run recovery, or two interleaved attempts, and a guess rendered\nas structure is exactly the false fidelity this surface exists to avoid.\n\nThe column reaches an existing database through the presence-gated arm in\n`internal/store`'s `migrateTasks` — `eventsSchema` is `CREATE TABLE IF NOT\nEXISTS`, so on an existing database the migrator is the *only* thing that adds\nit. `PRAGMA user_version` is unchanged because the loop is presence-gated\nrather than version-gated, and nothing is backfilled.\n\n### Read surface\n\nThe routes are registered beside the existing task routes in\n`internal/webui`'s `registerTaskRoutes` and all resolve the task through the\nstore's `TaskByID`; a task that does not exist is a `404`, never a `200` with an\nempty body.\n\n- `GET /api/tasks/{id}/attempts` — every attempt with its stages inline, so the\n rail and the attempt selector can never disagree. Stages are ordered by\n occurrence within their attempt. An attempt with no stages is legitimate and\n renders as \"no stages recorded\", never as an unexplained empty rail.\n- `GET /api/tasks/{id}/changes?attempt=N` — the change captures for one\n attempt, ordered by capture time; more than one per attempt is normal (a\n mid-workflow commit such as TDD's `commit-repro`, then `commit-push`, then a\n final `open-pr` capture that carries the pull-request number).\n `found: false` means no capture was recorded for that attempt, which is\n **not** \"no files changed\"; a capture that was recorded but could not be read\n is reported as exactly that, and never as a diffstat of zeroes.\n- `GET /api/tasks/{id}` — unchanged: the raw event array, each event now\n carrying `attempt`. The per-attempt configuration is read from this response,\n selected by kind **and** attempt.\n- `GET /api/tasks/{id}/logs` — gains `stage` beside its existing filters. The\n match is exact and case-insensitive, and an entry that records no stage never\n matches (see `logging.Query.Stage`).\n- `GET /api/tasks/{id}/debug?attempt=N` — the stored task record and the task's\n events, deliberately unfiltered, so an operator can attribute everything the\n task did even when a panel has nothing to show.\n\nThe `attempt` parameter follows one rule on every route: absent or `0` selects\nthe task's current attempt, and the resolved attempt is echoed in the response.\n\n### Stage status\n\n`stage_start` and `stage_finish` are the only inputs, so the derivation is\nexplicit and each case is pinned by a test:\n\n| Events seen for the stage | Reported |\n| --- | --- |\n| `stage_finish` with `data.error` | `failed`, with the error text |\n| `stage_finish` with `data.interrupted` | `interrupted` |\n| `stage_finish`, neither | `ok` — \"returned without error\" |\n| `stage_start` unmatched, and this is the task's current in-flight attempt | `running` |\n| `stage_start` unmatched on any dead attempt | `interrupted` — the run ended without finishing it |\n| `stage_finish` with no matching start | the stage, with no start time invented |\n| no stage information at all for that attempt | `unknown` |\n\n**There is no exit code.** `stage_finish` carries a duration and an optional\nerror string and nothing else, so no stage can be shown as pass/fail and the\npage must not imply verification. A stage that finished cleanly and then parked\nstays `ok` on a failed task, which is why the attempt status is read together\nwith the task status rather than on its own.\n\n### Changed files\n\nThe change an attempt produced is read from the worktree at the moment it is\ncommitted or pushed, and persisted as a `changes_captured` durable event — plus\none final capture when `OpenPR` records the pull-request number, which is the\nonly point at which a capture can carry one. It has to be captured there: the\nworktree is deleted on merge, close and no-PR terminal states, a retry resets\nthe branch onto its base, and no forge contract exposes a changed-file read.\n`internal/domain/workflow/task/changes.go` owns the value types and the status\nstrings they persist.\n\n- One capture carries per-file `added`/`modified`/`deleted`/`renamed`/\n `typechange` status with added and deleted line counts, and totals.\n- Each capture names its schema (`archie/task-changes@1`, in `internal/events`)\n and a reader refuses a payload whose schema or key set it does not know,\n rather than rendering the zero value of every field it could not find. That\n refusal surfaces as \"a capture was recorded but could not be read\", which is\n a different statement from \"no capture was recorded\".\n- `base_sha` is the merge base the file list was diffed against, not the base\n branch's tip, so the pair describes one change set even when the base branch\n moved during the run.\n- `files` is capped; `totals` always covers the **full** set, and a truncated\n capture says so rather than silently dropping entries.\n- `binary` means \"no textual hunks\" — never a claim about the file's type on\n disk — and a path the repository recorded as a rename pair is reported as the\n repository recorded it.\n- Capture **degrades and never parks**: an implementation without the capture\n seam captures nothing, logs, and lets the run continue.\n\n### Per-attempt configuration\n\nThe effective configuration an attempt ran under is persisted as a once-per-\nattempt `config_captured` durable event carrying the schema constant\n`archie/task-config@1` and the non-secret task-runtime subset from\n`config.Config.ForTask()`. It is not stored in a table and has no endpoint of\nits own: the dashboard reads it out of the events response it already fetches.\nThe single-row `config_snapshot` table is left alone — it answers what the\nrunning configuration is now and is replaced on every publish.\n\nRedaction is proven positively by a test that builds a full configuration\ncontaining canary values and asserts none of them survive serialising, rather\nthan being inferred from the producer's contract. The timeline carries one\nhuman line for this kind; the document itself is rendered by the panel.\n\n**Trust boundary, stated honestly.** A task-scoped grant may insert events on\nits own task ID — that is how `tool_call` and `agent_finish` already work — so a\ntask could in principle write its own `config_captured` event. This widens no\ncapability, because the grant could already insert arbitrary events on itself,\nbut it does mean this provenance is exactly as trustworthy as the rest of that\ntask's event stream, and no more. It is not tamper-proofing and must never be\ndescribed as such.\n\n### The wire\n\nThe whole wire change is two fields on existing messages: `Event.attempt`\n(field 11) and `ReadTaskLogRequest.stage` (field 9) in\n`proto/state/v1/state.proto`. No RPC, no table and no configuration field was\nadded, so the ratified state-store contract in\n`docs/prds/state-store-contract.md` rev 2c is unchanged.\n\nVersion skew degrades instead of failing, and each degrade is a statement the\npage has to make rather than hide: an old server makes `attempt` read as `0` and\n`stage` match nothing, so the page says it cannot attribute events to attempts\ninstead of labelling the whole stream \"attempt 1\"; an old client sees\n`config_captured` as an unfamiliar kind, and the panel must then say it cannot\nread per-run configuration — a different claim from \"not captured for this\nattempt\".\n\n### Rules the surface keeps\n\n- \"No record\" and \"this deployment cannot read this\" stay different answers,\n for logs and for configuration alike.\n- No run-duration figure is shown. A run can spend days in `waiting_human`, so\n one number would understate wall time; per-stage durations only.\n- No duration is invented for a stage with no start; it reads \"not recorded\".\n- The stage filter is a narrowing, not a coverage claim: agent and tool output\n carries no stage and is never matched, and the pane says so beside the\n control.\n- An attempt predating the change shows \"not captured for this run\" for its\n configuration and its change capture, never an empty view that implies\n defaults applied or nothing changed.\n\n### Failure and rollback\n\nEvery part is additive. A capture or a configuration emit that cannot happen\nleaves the run alone — reporting must never park a task. Reverting the change\nset removes the endpoints and the page; the extra column and the extra event\nkinds are inert to the previous revision (SQLite ignores a column no statement\nnames, and an unfamiliar event kind already renders as unfamiliar), and there is\nno data transformation to undo.\n\n## Dependency direction\n\n`internal/logging` remains cross-cutting per `organisation.md` — it imports\nno domain, infrastructure, or app package, so extending it to be task-scoped\ndoes not change its classification. The workflow domain writes through the\ncross-cutting logging contract. On the agent side,\n`internal/app/agentworker` composes the narrow publisher supplied by\n`internal/infrastructure/agenttransport/nats`. On the daemon side,\n`cmd/archied/main.go` currently composes the NATS subscription with the task\nsink until the approved `internal/app/archied` migration is implemented.\n\n## Implementation sequence (completed)\n\n1. Gate-output capture (~30 lines, no NATS changes) — fixes the immediate\n symptom that prompted this document.\n2. Task log sink in `internal/logging`.\n3. Agent-side publisher on `SubjectForSystem`.\n4. Daemon-side subscriber + `logging.Feed` integration + retention on\n archive.\n5. `/api/tasks/{id}/logs` + chat tool.\n\nTracked as GitHub epic/subtasks per the issue list linked from this\ndocument's PR.\n" + "body": "# Task Observability\n\n**Status:** Implemented. The per-run detail surface was added on 2026-09-18 and\nis described below.\n**Date:** 2026-08-09 (revised 2026-09-18)\n\n## Historical problem\n\narchied's own daemon logging (`internal/logging/`) was already solid: a\nrotating file sink, a live `Feed` the dashboard subscribes to, and a reader\nthe `/api/logs` endpoint serves from. Before this implementation, none of\nthat reached inside a task.\n\nA task's actual work happens in a task-scoped `archie-agent` container,\ndispatched as one complete workflow over NATS.\nBefore this design was implemented, five things destroyed the evidence of what\nthat container did:\n\n1. **Worker startup** constructed an stderr-only logger and never replaced its\n handler after discovering a dedicated boot task, so runtime records could\n not leave the container.\n2. **`internal/container/pool.go`** creates every task container with\n `AutoRemove: true`. The container — and its stderr — is gone at exit,\n success or failure alike.\n3. **`internal/domain/workflow/implement.go`, `StageBaselineGate`** captures\n `go build`/`go vet`/`go test` output via `cmd.CombinedOutput()`, then\n clips it to 200 characters into a `Warn` log line and discards the rest.\n The eventual park reason is built from `res.Status` alone — the actual\n compiler error is never persisted anywhere a human or Archie's own chat\n tools can read it back.\n4. **`agentexec.Result`** (`internal/agentexec/protocol.go`) carries only\n `Summary`/`Detail` — no step-by-step transcript (tool calls, durations,\n errors). There is no transcript to recover even in principle.\n5. **`agentexec.SubjectForSystem`** is documented as the return channel for\n exactly this — *\"log dumps, health, and PII warnings... the daemon reads\n these for observability and never forwards them\"* — but has no publisher\n and no consumer anywhere in the codebase except a subject-format\n assertion in `nats_test.go`. The designed return path was never wired.\n\nThe practical consequence: a task parks with\n`stage baseline: baseline red -- go build ./... fails and builder could not\nauto-fix (status: parked)` and there is no way — not from the dashboard, not\nfrom Telegram chat, not by SSH'ing into the deployment host — to see *why*\n`go build` failed. The container that knew is already gone.\n\nThis matters beyond debugging convenience: supported deployments can combine\na resident daemon with ephemeral Docker containers that run unattended for\nweeks between operator logins, and the system is\nintended to be usable by people other than the original operator. A system\nthat is only debuggable by an operator who happens to be watching `docker ps`\nin real time does not meet that bar.\n\n## Decision: NATS is the sole autonomous handoff\n\nThe agent image must reach NATS in every deployment, because the broker is the\nonly autonomous task handoff and the only channel carrying task results back\nto the daemon. `archied` has no workflow runner or host fallback. A container\nthat dies before establishing a NATS connection is a distinct, narrower\nfailure (connectivity/config) from the one this document addresses (a connected\ncontainer's own output being unrecoverable), and is out of scope here.\n\n## Implemented design\n\nThe key property: **logs leave the container while it is alive**, so its\ndeath at `AutoRemove` no longer matters. Persistence happens in the daemon\nprocess, which already owns durable state.\n\n### Sink: extend `internal/logging`, not a new package\n\n`internal/logging` already owns its on-disk format end to end per\n`organisation.md` (\"a package owns its own format end to end\"). Add a\ntask-scoped writer producing the same `logging.Entry` JSONL shape at\n`\u003cstate_dir\u003e/logs/tasks/\u003ctask_id\u003e/attempt-\u003cn\u003e.jsonl`. `logging.Tail`,\n`logging.Query`, and `logging.Components` operate on this unchanged;\n`internal/webui/api_logs.go` stays transport-only, as it does today.\n\n### Agent side: make the designed subject real\n\n`internal/app/agentworker` replaces the stderr-only `slog.Handler` with one\nthat tees to stderr (kept for container-level operator debugging when a\nshell is attached) and publishes each record to\n`agentexec.SubjectForSystem(taskID)`, which already exists for this purpose.\nThe application layer obtains only a narrow publisher from\n`internal/infrastructure/agenttransport/nats`; raw core-NATS types remain in\ninfrastructure. `internal/infrastructure/agentboot.TaskID` reads the task ID\nfrom `\u003cworktree\u003e/.git/task.json` per the container/pool.go trap documented in\n`CLAUDE.md`. Publishing is fire-and-forget: log shipping must never block or\nfail the run it is reporting on.\n\n### Daemon side\n\n`cmd/archied/main.go` registers `subscribeSystemLogs` once at startup on\n`agentexec.SubjectSystemWildcard`. It demultiplexes by task ID, appends to that task's\nsink, and publishes into the existing `logging.Feed` so live task output\nappears on the dashboard exactly like daemon output. The approved target is\nfor this composition to move to `internal/app/archied`; that package does not\nyet exist, so this document does not claim the migration is complete.\n\nThe daemon is also a writer in its own right for the decisions only it makes.\nEvery park records its reason into that attempt's sink (`daemon.recordPark`),\non the daemon side after the guarded transition lands and in\n`workflow.park` on the agent side, because \"why did this park?\" is the question\nthe log exists to answer and the container path cannot answer a run that never\nreached a container. The entry is written only once the park actually\nhappened, so a transition another actor won does not leave a log claiming an\noutcome the task board contradicts.\n\n### Gate output: stop discarding it\n\n`StageBaselineGate` and the equivalent TDD-stage gate runs write full\n`cmd.CombinedOutput()` to the task's sink under a `gate` component, and put a\nbounded tail (~2KB, not 200 bytes) into the park reason. This is the cheapest\nfix and independently valuable — it alone would have made the `go build`\nfailure diagnosable without any NATS plumbing.\n\n### Transcript\n\nStep-level events (tool name, argument digest, duration, error) are emitted\nas log entries on the same NATS system subject rather than added as new\nfields on `agentexec.Result`. This keeps the wire protocol\n(`internal/agentexec/protocol.go`) stable and the transcript lands in the\nsink automatically, with no separate delivery path to keep consistent.\n\n### Retention\n\nReuse the existing rotation (`MaxSizeMB`/`Keep`) semantics per task\ndirectory. Prune a task's log directory when `store.ArchiveTask` archives\nit, so task logs share the task's own\nlifecycle rather than accumulating independently.\n\n### Surfaces\n\n- `/api/tasks/{id}/logs`, built on `logging.Reader` the same way\n `/api/logs` is today.\n- A chat tool so Archie can answer \"why did task 4 park?\" directly from\n Telegram or the webui chat — this is the surface that actually matters\n for the deployment model in `CLAUDE.md`, where an operator may not be\n looking at a dashboard at all.\n- The per-attempt read surface described in the next section, on top of the\n same task-scoped stream.\n\n## Per-run task detail (attempts, stages, changes, config)\n\n**Status:** landed, together with the change set that carries this revision\n(workflow run `76f8e877`). The provenance half is in the tree: `events.Event.Attempt`,\nthe `changes_captured` and `config_captured` event kinds, and the two protobuf field\nadditions. So is the read half: the three per-attempt endpoints\n(`/api/tasks/{id}/attempts`, `/changes`, `/debug`) and the dashboard run-detail page\nthat consumes them. The decision record, the rejected alternatives and the honest\nlimits are `docs/prds/task-run-detail.md`.\n\nThe task log surface above answers *why did this park?*. This surface answers\n*what did this run actually do?*, per attempt.\n\n### Attempt attribution\n\nOne task can run many times, and the task's event stream is the durable record\nof all of them. `events.Event.Attempt` attributes each event to one run; `0`\nmeans **not attributable** — every event written before this change, plus the\ndeliberately task-agnostic producers. An unattributed event is reported as a\ncount and is never presented as an attempt.\n\nAttribution is a column, not a fold over `task_queued`/`task_retried`: a fold\nwould have to guess which side of a boundary an event belongs to across a daemon\nrestart, a stale-run recovery, or two interleaved attempts, and a guess rendered\nas structure is exactly the false fidelity this surface exists to avoid.\n\nThe column is part of the events table in\n`internal/infrastructure/postgres/migrations/0001_state_store.sql`, and nothing\nis backfilled.\n\n### Read surface\n\nThe routes are registered beside the existing task routes in\n`internal/webui`'s `registerTaskRoutes` and all resolve the task through the\nstore's `TaskByID`; a task that does not exist is a `404`, never a `200` with an\nempty body.\n\n- `GET /api/tasks/{id}/attempts` — every attempt with its stages inline, so the\n rail and the attempt selector can never disagree. Stages are ordered by\n occurrence within their attempt. An attempt with no stages is legitimate and\n renders as \"no stages recorded\", never as an unexplained empty rail.\n- `GET /api/tasks/{id}/changes?attempt=N` — the change captures for one\n attempt, ordered by capture time; more than one per attempt is normal (a\n mid-workflow commit such as TDD's `commit-repro`, then `commit-push`, then a\n final `open-pr` capture that carries the pull-request number).\n `found: false` means no capture was recorded for that attempt, which is\n **not** \"no files changed\"; a capture that was recorded but could not be read\n is reported as exactly that, and never as a diffstat of zeroes.\n- `GET /api/tasks/{id}` — unchanged: the raw event array, each event now\n carrying `attempt`. The per-attempt configuration is read from this response,\n selected by kind **and** attempt.\n- `GET /api/tasks/{id}/logs` — gains `stage` beside its existing filters. The\n match is exact and case-insensitive, and an entry that records no stage never\n matches (see `logging.Query.Stage`).\n- `GET /api/tasks/{id}/debug?attempt=N` — the stored task record and the task's\n events, deliberately unfiltered, so an operator can attribute everything the\n task did even when a panel has nothing to show.\n\nThe `attempt` parameter follows one rule on every route: absent or `0` selects\nthe task's current attempt, and the resolved attempt is echoed in the response.\n\n### Stage status\n\n`stage_start` and `stage_finish` are the only inputs, so the derivation is\nexplicit and each case is pinned by a test:\n\n| Events seen for the stage | Reported |\n| --- | --- |\n| `stage_finish` with `data.error` | `failed`, with the error text |\n| `stage_finish` with `data.interrupted` | `interrupted` |\n| `stage_finish`, neither | `ok` — \"returned without error\" |\n| `stage_start` unmatched, and this is the task's current in-flight attempt | `running` |\n| `stage_start` unmatched on any dead attempt | `interrupted` — the run ended without finishing it |\n| `stage_finish` with no matching start | the stage, with no start time invented |\n| no stage information at all for that attempt | `unknown` |\n\n**There is no exit code.** `stage_finish` carries a duration and an optional\nerror string and nothing else, so no stage can be shown as pass/fail and the\npage must not imply verification. A stage that finished cleanly and then parked\nstays `ok` on a failed task, which is why the attempt status is read together\nwith the task status rather than on its own.\n\n### Changed files\n\nThe change an attempt produced is read from the worktree at the moment it is\ncommitted or pushed, and persisted as a `changes_captured` durable event — plus\none final capture when `OpenPR` records the pull-request number, which is the\nonly point at which a capture can carry one. It has to be captured there: the\nworktree is deleted on merge, close and no-PR terminal states, a retry resets\nthe branch onto its base, and no forge contract exposes a changed-file read.\n`internal/domain/workflow/task/changes.go` owns the value types and the status\nstrings they persist.\n\n- One capture carries per-file `added`/`modified`/`deleted`/`renamed`/\n `typechange` status with added and deleted line counts, and totals.\n- Each capture names its schema (`archie/task-changes@1`, in `internal/events`)\n and a reader refuses a payload whose schema or key set it does not know,\n rather than rendering the zero value of every field it could not find. That\n refusal surfaces as \"a capture was recorded but could not be read\", which is\n a different statement from \"no capture was recorded\".\n- `base_sha` is the merge base the file list was diffed against, not the base\n branch's tip, so the pair describes one change set even when the base branch\n moved during the run.\n- `files` is capped; `totals` always covers the **full** set, and a truncated\n capture says so rather than silently dropping entries.\n- `binary` means \"no textual hunks\" — never a claim about the file's type on\n disk — and a path the repository recorded as a rename pair is reported as the\n repository recorded it.\n- Capture **degrades and never parks**: an implementation without the capture\n seam captures nothing, logs, and lets the run continue.\n\n### Per-attempt configuration\n\nThe effective configuration an attempt ran under is persisted as a once-per-\nattempt `config_captured` durable event carrying the schema constant\n`archie/task-config@1` and the non-secret task-runtime subset from\n`config.Config.ForTask()`. It is not stored in a table and has no endpoint of\nits own: the dashboard reads it out of the events response it already fetches.\nThe single-row `config_snapshot` table is left alone — it answers what the\nrunning configuration is now and is replaced on every publish.\n\nRedaction is proven positively by a test that builds a full configuration\ncontaining canary values and asserts none of them survive serialising, rather\nthan being inferred from the producer's contract. The timeline carries one\nhuman line for this kind; the document itself is rendered by the panel.\n\n**Trust boundary, stated honestly.** A task-scoped grant may insert events on\nits own task ID — that is how `tool_call` and `agent_finish` already work — so a\ntask could in principle write its own `config_captured` event. This widens no\ncapability, because the grant could already insert arbitrary events on itself,\nbut it does mean this provenance is exactly as trustworthy as the rest of that\ntask's event stream, and no more. It is not tamper-proofing and must never be\ndescribed as such.\n\n### The wire\n\nThe whole wire change is two fields on existing messages: `Event.attempt`\n(field 11) and `ReadTaskLogRequest.stage` (field 9) in\n`proto/state/v1/state.proto`. No RPC, no table and no configuration field was\nadded, so the ratified state-store contract in\n`docs/prds/state-store-contract.md` rev 2c is unchanged.\n\nVersion skew degrades instead of failing, and each degrade is a statement the\npage has to make rather than hide: an old server makes `attempt` read as `0` and\n`stage` match nothing, so the page says it cannot attribute events to attempts\ninstead of labelling the whole stream \"attempt 1\"; an old client sees\n`config_captured` as an unfamiliar kind, and the panel must then say it cannot\nread per-run configuration — a different claim from \"not captured for this\nattempt\".\n\n### Rules the surface keeps\n\n- \"No record\" and \"this deployment cannot read this\" stay different answers,\n for logs and for configuration alike.\n- No run-duration figure is shown. A run can spend days in `waiting_human`, so\n one number would understate wall time; per-stage durations only.\n- No duration is invented for a stage with no start; it reads \"not recorded\".\n- The stage filter is a narrowing, not a coverage claim: agent and tool output\n carries no stage and is never matched, and the pane says so beside the\n control.\n- An attempt predating the change shows \"not captured for this run\" for its\n configuration and its change capture, never an empty view that implies\n defaults applied or nothing changed.\n\n### Failure and rollback\n\nEvery part is additive. A capture or a configuration emit that cannot happen\nleaves the run alone — reporting must never park a task. Reverting the change\nset removes the endpoints and the page; the extra column and the extra event\nkinds are inert to the previous revision (a column no statement names is\nignored, and an unfamiliar event kind already renders as unfamiliar), and there is\nno data transformation to undo.\n\n## Dependency direction\n\n`internal/logging` remains cross-cutting per `organisation.md` — it imports\nno domain, infrastructure, or app package, so extending it to be task-scoped\ndoes not change its classification. The workflow domain writes through the\ncross-cutting logging contract. On the agent side,\n`internal/app/agentworker` composes the narrow publisher supplied by\n`internal/infrastructure/agenttransport/nats`. On the daemon side,\n`cmd/archied/main.go` currently composes the NATS subscription with the task\nsink until the approved `internal/app/archied` migration is implemented.\n\n## Implementation sequence (completed)\n\n1. Gate-output capture (~30 lines, no NATS changes) — fixes the immediate\n symptom that prompted this document.\n2. Task log sink in `internal/logging`.\n3. Agent-side publisher on `SubjectForSystem`.\n4. Daemon-side subscriber + `logging.Feed` integration + retention on\n archive.\n5. `/api/tasks/{id}/logs` + chat tool.\n\nTracked as GitHub epic/subtasks per the issue list linked from this\ndocument's PR.\n" }, { "url": "/dev/architecture/organisation/", @@ -100,7 +100,7 @@ "url": "/dev/architecture/safe-change-and-recovery/", "title": "Safe Change and Recovery", "section": "Architecture", - "body": "# Safe Change and Recovery\n\n**Status:** Requirements approved; mechanics are under design. Database-backed settings are implemented through the control plane (2026-09): see the degrade/recovery section below, which records a gap rather than a solution. The full runtime-supervision protocol (bounded observation, versioned audit trail) remains under design.\n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie is built and improved by agents as well as humans. The architecture MUST\nmake a change easy to locate, understand, test, audit, extend, and reverse\nwithout requiring its author to understand unrelated parts of the application.\n\nSeparation of concerns is therefore an operational safety boundary, not only a\ncode-organisation preference.\n\n## Required outcomes\n\n- An agent can improve a focused feature without receiving authority over\n unrelated domains.\n- Every event, function, action, setting, and policy has an identifiable owner\n and provenance.\n- Source and runtime changes pass deterministic checks outside the actor making\n the change.\n- A rejected or unhealthy candidate cannot replace the last known working\n version.\n- Invalid user configuration does not terminate an otherwise healthy\n application.\n- Configuration and service failures are observable, attributed, and eligible\n for bounded remediation or rollback.\n- The application continues serving unaffected capabilities when one\n capability is misconfigured or unhealthy.\n- Recovery failure is reported and contained rather than hidden in an\n unbounded retry loop.\n\n## Source changes\n\nAgent-authored source changes occur through the task-execution boundary in an\nisolated workspace. The agent does not directly mutate the running\ninstallation.\n\nPromotion is controlled by deterministic repository-owned policy, including\ntests, generated-reference drift checks, protected paths, change scope, and\nother required gates. The actor proposing a change cannot waive these checks.\n\nRepository and domain separation SHOULD allow a task to load and modify only\nthe governing requirements and code for its declared scope.\n\n## Runtime changes\n\nConfiguration and other runtime changes are proposed as candidates rather than\nmutating the active state in place.\n\nThe affected domain owns:\n\n- the command describing the semantic change;\n- validation of its typed settings;\n- health signals that demonstrate correct operation;\n- domain-specific remediation and rollback consequences.\n\nShared policy supplies consistent evaluation, evidence, and audit mechanics.\nIdentity supplies actor attribution. Infrastructure supplies external\nconfiguration storage, service control, and other operational adapters.\n\n## Runtime change protocol\n\nLast-known-good preservation and candidate promotion are the universal runtime\nchange protocol.\n\n1. An identity proposes an immutable candidate version.\n2. Infrastructure parses it without changing active state.\n3. Each affected domain validates its typed settings.\n4. Shared policy evaluates cross-cutting constraints.\n5. Each affected capability prepares the candidate without destroying its\n active instance.\n6. Capability-specific health checks prove the candidate works.\n7. Runtime supervision atomically promotes the candidate.\n8. A bounded observation period watches for delayed failure.\n9. Failure restores the last-known-good version and records the reason,\n evidence, actor, and involved versions.\n10. Repeated remediation failure stops retrying, isolates the capability, and\n reports the fault.\n\nThe affected domain owns the semantic change command, typed validation, health\nsignals, and remediation consequences. Shared runtime supervision owns the\npromotion transaction. Infrastructure performs storage and service-control\noperations.\n\nThe protocol's exact Go contracts, storage model, atomicity boundary, and\nobservation rules require a focused runtime-supervision design pass.\n\n## Failure isolation\n\nInvalid input MUST leave the active valid configuration unchanged and produce a\ndiagnostic record.\n\nA capability that cannot start or reload SHOULD fail independently where its\nabsence does not violate a declared application invariant. Unaffected\ncapabilities continue operating.\n\nRemediation MUST be bounded, observable, and policy-driven. Recovery MUST NOT\nsilently oscillate between versions or retry forever.\n\n## Database settings: degrade paths and recovery (2026-09)\n\nThe control plane owns runtime-tunable settings and stores them in `archie.db`.\nThis replaced a dashboard overlay store that degraded to file config on any\nfailure and had three documented ways back. The replacement has none, and the\nposture is the opposite: **the daemon fails closed.**\n\n### Degrade paths\n\n| Failure | Boot behaviour | Where the operator sees it |\n| --- | --- | --- |\n| State Store unreachable | `boot.loadRuntimeConfig` returns the dial error and `archied` exits non-zero | stderr: `runtime settings unavailable` |\n| A stored resource fails validation | Same: `validate database settings` wraps the error and the daemon exits | Same |\n| SIGHUP reload with a bad file, or a control plane that cannot be read | Running config is kept; the reload records `last_error` / `last_error_at`. The reload re-applies the database layer, so it never publishes file values over the running database-owned ones | `/api/config` → `reload.last_error` → dashboard banner |\n\nFailing closed is deliberate for settings the database owns: falling back to the\nfile values would restore the second source of truth the control plane exists to\nremove. The cost is that a bad stored value stops the daemon starting, and the\nvalue can only be corrected through the daemon's own API.\n\n### Upgrading an install from SQLite\n\nThe State Store, the daemon and the Gateway serve from `database_url` only. An\ninstall that still holds the SQLite stores (`\u003cdb_path\u003e-tasks.sqlite`,\n`\u003cdb_path\u003e-eda.sqlite`, `\u003cdb_path\u003e-conversations.sqlite`) upgrades in three\nsteps:\n\n1. Stop every archie process.\n2. Run `archie-state-store import`. It moves all three stores into Postgres in\n one transaction, verifies the rows, and records completion. The SQLite files\n are read, never written.\n3. Start archie.\n\nEach serving process checks this at boot, after migrating the schema. With no\ncompletion record and a non-empty legacy file it refuses to start and names the\nfiles and the import command, rather than serve empty tables over existing\ndata. There is no override. With no legacy data it is a fresh install: it writes\nthe completion record itself, so a legacy file that appears later is ignored.\nA database that recorded a fresh start refuses a later import.\n\nThe Gateway holds a Postgres serve-ownership claim for its whole life, so a\nsecond Gateway against the same database refuses to start (its turn recovery\nwould fail the first one's in-flight turns). The State Store holds its own.\n\n### Recovery: offline commands on the State Store\n\nNothing skips the control plane at boot, and the only writer for a resource is\n`ControlPlaneService.Command` on a running State Store -- which is exactly what\nthe daemon fails closed without. `archie-state-store` therefore carries the\noffline recovery commands (`archie-core-6zw0`). They work on the task database\nfile directly -- the configured `db_path` with `-tasks.sqlite` appended, not\n`db_path` itself -- and need neither `archied` nor the Web UI running: `validate`\nreads the configuration file the daemon boots with, which is what makes its\nverdict the daemon's verdict.\n\n| Command | What it does | State Store |\n| --- | --- | --- |\n| `backup -db F -out F` | writes a transactionally consistent snapshot (`VACUUM INTO`), verified as a usable store before it is published | may be running |\n| `restore -db F -from F` | replaces the database with a snapshot and drops the replaced file's `-wal`/`-shm` | must be stopped |\n| `validate -db F [-config C]` | runs the checks that stop archied starting: the file is readable, uncorrupted and no newer than the binary; every stored resource decodes under the definition that owns it; and `configuration.Validate` accepts the settings the daemon would read -- the stored ones, or the seed the State Store writes for a kind the file does not hold yet -- layered onto `C`, the check the daemon reports as `validate database settings` | may be running |\n| `rollback -db F -kind K [-revision N]` | replays an earlier revision of a stored resource through the ordinary replace, recording the rollback as a new revision | must be stopped |\n\nThe two validation layers `validate` reports are not the same check, and it\nreports both rather than merging them: the write path's own decode is stricter\nabout shape (it rejects unknown fields boot's decode ignores), while boot is\nstricter about meaning (only boot checks `dispatch.trigger`, and a positive\n`poll_interval`). Either one refusing is a store somebody has to look at.\n\nNo rollback RPC exists and none is needed: a revision carries its own value, so\nrestoring one is the same replace the dashboard and the channels already use.\nThe offline command is that operation with the store stopped -- the one state in\nwhich the daemon's own API cannot serve it.\n\n\"Must be stopped\" is checked rather than assumed. The serving process takes an\nexclusive flock on `\u003cdb\u003e.lock` for its whole life, and `restore` and `rollback`\nrefuse with `task database is owned by another process` while another process\nholds it. The read-only commands -- `backup` and `validate` -- take no lock and\nare meant to run against a serving store: `backup` because the update installer\nruns inside the process it is replacing and cannot stop the State Store, and\n`validate` because an operator checks a running deployment with it. That\n`backup` exemption is only sound while backup never replaces the database, so\nnaming the database as its own `-out` is refused. `scripts/archie-update-install`\ntakes its pre-flight snapshot through this subcommand rather than through its\nown `sqlite3` shell, so the installer and an operator run one implementation.\n\n`rollback` is the surgical route back from a bad stored value; `restore` is the\nblunt one, and is also the way back from a schema migration a release cannot\ngrow out of.\n\n### The same commands on PostgreSQL\n\nWithout `-db`, each command works on the PostgreSQL database the configuration's\n`database_url` names (`internal/app/archied/state_store_recovery_postgres.go`,\n`internal/infrastructure/postgres/maintenance.go`). One database backs every\nservice, so the scope is always the whole database.\n\n- `backup -out F` runs `pg_dump --format=custom`, reads the archive back with\n `pg_restore --list` and only then replaces `F`. It takes no claim and runs\n against a serving database.\n- `restore -from F` is destructive and offline. It claims every service role's\n ownership lock (`state-store` and `gateway`) without waiting and refuses if\n any is held or the check cannot complete, then drops tables the snapshot does\n not hold and runs `pg_restore --clean --single-transaction`. Every write made\n after the snapshot is lost.\n- `validate` refuses a schema newer than the binary's highest migration, then\n runs the same two validation layers.\n- `rollback` holds the `state-store` claim for the replay.\n\nThere is no automatic schema rollback. goose `Down` drops tables, so it is data\nloss, not a rollback. `scripts/archie-update-install` refuses a daemon update\nit cannot snapshot first, and on a failed update `scripts/archie-update-watchdog`\nrolls the binaries back, leaves the database alone and prints the `restore`\ncommand for the pre-update snapshot. Whether to run it is the operator's call.\n\n## Gateway restart: two constraints learned the hard way\n\nTelegram `/restart` (`internal/channels/telegram/restart.go` plus the `Start`\nsupervisor loop). Recovered 2026-08-09 from the pre-migration issue tracker.\nBoth constraints must survive any refactor.\n\n**1. Deadlock.** The `/restart` handler runs *on* the bot instance the supervisor\nis about to stop. Tearing down inline from the handler deadlocks the restart it\njust asked for. So the handler sends on a **buffered** channel (`restartCh`,\ncapacity 1) and returns immediately; the supervisor loop in `Start` does the\nteardown. Duplicate requests hit the default branch and are dropped, not queued.\n\n**2. Lockout.** A failed config reload must **not** be fatal. It logs and\nrelaunches with the previous in-memory settings. If a bad config edit killed the\ngateway, it would also destroy the only means of fixing it remotely — which is\nthe entire reason `/restart` exists.\n\n**Scope is gateway-only by design.** The daemon keeps running so in-flight agent\ntasks survive. Exiting the process would also restart under a `unless-stopped`\npolicy, but would kill running work. `Reload` (supplied by `cmd/archied/main.go`)\nre-reads config from disk and refreshes **only** the token and `AllowedUserIDs`;\neverything else is wired into the daemon at construction and still needs a full\nrestart.\n\n**Authorisation is inherited:** `authorizedMessage` rejects non-allowlisted\nsenders before any handler runs, so all gateway commands are admin-only by\nconstruction. Do not add per-command auth without checking that invariant still\nholds.\n" + "body": "# Safe Change and Recovery\n\n**Status:** Requirements approved; mechanics are under design. Database-backed settings are implemented through the control plane (2026-09): see the degrade/recovery section below, which records a gap rather than a solution. The full runtime-supervision protocol (bounded observation, versioned audit trail) remains under design.\n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie is built and improved by agents as well as humans. The architecture MUST\nmake a change easy to locate, understand, test, audit, extend, and reverse\nwithout requiring its author to understand unrelated parts of the application.\n\nSeparation of concerns is therefore an operational safety boundary, not only a\ncode-organisation preference.\n\n## Required outcomes\n\n- An agent can improve a focused feature without receiving authority over\n unrelated domains.\n- Every event, function, action, setting, and policy has an identifiable owner\n and provenance.\n- Source and runtime changes pass deterministic checks outside the actor making\n the change.\n- A rejected or unhealthy candidate cannot replace the last known working\n version.\n- Invalid user configuration does not terminate an otherwise healthy\n application.\n- Configuration and service failures are observable, attributed, and eligible\n for bounded remediation or rollback.\n- The application continues serving unaffected capabilities when one\n capability is misconfigured or unhealthy.\n- Recovery failure is reported and contained rather than hidden in an\n unbounded retry loop.\n\n## Source changes\n\nAgent-authored source changes occur through the task-execution boundary in an\nisolated workspace. The agent does not directly mutate the running\ninstallation.\n\nPromotion is controlled by deterministic repository-owned policy, including\ntests, generated-reference drift checks, protected paths, change scope, and\nother required gates. The actor proposing a change cannot waive these checks.\n\nRepository and domain separation SHOULD allow a task to load and modify only\nthe governing requirements and code for its declared scope.\n\n## Runtime changes\n\nConfiguration and other runtime changes are proposed as candidates rather than\nmutating the active state in place.\n\nThe affected domain owns:\n\n- the command describing the semantic change;\n- validation of its typed settings;\n- health signals that demonstrate correct operation;\n- domain-specific remediation and rollback consequences.\n\nShared policy supplies consistent evaluation, evidence, and audit mechanics.\nIdentity supplies actor attribution. Infrastructure supplies external\nconfiguration storage, service control, and other operational adapters.\n\n## Runtime change protocol\n\nLast-known-good preservation and candidate promotion are the universal runtime\nchange protocol.\n\n1. An identity proposes an immutable candidate version.\n2. Infrastructure parses it without changing active state.\n3. Each affected domain validates its typed settings.\n4. Shared policy evaluates cross-cutting constraints.\n5. Each affected capability prepares the candidate without destroying its\n active instance.\n6. Capability-specific health checks prove the candidate works.\n7. Runtime supervision atomically promotes the candidate.\n8. A bounded observation period watches for delayed failure.\n9. Failure restores the last-known-good version and records the reason,\n evidence, actor, and involved versions.\n10. Repeated remediation failure stops retrying, isolates the capability, and\n reports the fault.\n\nThe affected domain owns the semantic change command, typed validation, health\nsignals, and remediation consequences. Shared runtime supervision owns the\npromotion transaction. Infrastructure performs storage and service-control\noperations.\n\nThe protocol's exact Go contracts, storage model, atomicity boundary, and\nobservation rules require a focused runtime-supervision design pass.\n\n## Failure isolation\n\nInvalid input MUST leave the active valid configuration unchanged and produce a\ndiagnostic record.\n\nA capability that cannot start or reload SHOULD fail independently where its\nabsence does not violate a declared application invariant. Unaffected\ncapabilities continue operating.\n\nRemediation MUST be bounded, observable, and policy-driven. Recovery MUST NOT\nsilently oscillate between versions or retry forever.\n\n## Database settings: degrade paths and recovery (2026-09)\n\nThe control plane owns runtime-tunable settings and stores them in the State\nStore's PostgreSQL database.\nThis replaced a dashboard overlay store that degraded to file config on any\nfailure and had three documented ways back. The replacement has none, and the\nposture is the opposite: **the daemon fails closed.**\n\n### Degrade paths\n\n| Failure | Boot behaviour | Where the operator sees it |\n| --- | --- | --- |\n| State Store unreachable | `boot.loadRuntimeConfig` returns the dial error and `archied` exits non-zero | stderr: `runtime settings unavailable` |\n| A stored resource fails validation | Same: `validate database settings` wraps the error and the daemon exits | Same |\n| SIGHUP reload with a bad file, or a control plane that cannot be read | Running config is kept; the reload records `last_error` / `last_error_at`. The reload re-applies the database layer, so it never publishes file values over the running database-owned ones | `/api/config` → `reload.last_error` → dashboard banner |\n\nFailing closed is deliberate for settings the database owns: falling back to the\nfile values would restore the second source of truth the control plane exists to\nremove. The cost is that a bad stored value stops the daemon starting, and the\nvalue can only be corrected through the daemon's own API.\n\n### Upgrading an install from SQLite\n\nThe State Store, the daemon and the Gateway serve from `database_url` only. An\ninstall that still holds the SQLite stores (`\u003cdb_path\u003e-tasks.sqlite`,\n`\u003cdb_path\u003e-eda.sqlite`, `\u003cdb_path\u003e-conversations.sqlite`) upgrades in three\nsteps:\n\n1. Stop every archie process.\n2. Run `archie-state-store import`. It moves all three stores into Postgres in\n one transaction, verifies the rows, and records completion. The SQLite files\n are read, never written.\n3. Start archie.\n\n`db_path` exists only to locate these files for the import and the boot gate\nbelow, and goes with the importer. The embedded NATS store, its endpoint file\nand task logs live under `state_dir` (default: the data home's `archie`\ndirectory). An install whose `db_path` sat outside the data home sets\n`state_dir` to that directory to keep them where they were.\n\nEach serving process checks this at boot, after migrating the schema. With no\ncompletion record and a non-empty legacy file it refuses to start and names the\nfiles and the import command, rather than serve empty tables over existing\ndata. There is no override. With no legacy data it is a fresh install: it writes\nthe completion record itself, so a legacy file that appears later is ignored.\nA database that recorded a fresh start refuses a later import.\n\nThe Gateway holds a Postgres serve-ownership claim for its whole life, so a\nsecond Gateway against the same database refuses to start (its turn recovery\nwould fail the first one's in-flight turns). The State Store holds its own.\n\n### Recovery: offline commands on the State Store\n\nNothing skips the control plane at boot, and the only writer for a resource is\n`ControlPlaneService.Command` on a running State Store -- which is exactly what\nthe daemon fails closed without. `archie-state-store` therefore carries the\noffline recovery commands (`archie-core-6zw0`). They work on the PostgreSQL\ndatabase the configuration's `database_url` names\n(`internal/app/archied/state_store_recovery_postgres.go`,\n`internal/infrastructure/postgres/maintenance.go`) and need neither `archied`\nnor the Web UI running: `validate` reads the configuration file the daemon\nboots with, which is what makes its verdict the daemon's verdict. One database\nbacks every service, so the scope is always the whole database.\n\n| Command | What it does | Serving processes |\n| --- | --- | --- |\n| `backup -out F` | runs `pg_dump --format=custom`, reads the archive back with `pg_restore --list` and only then replaces `F` | may be running |\n| `restore -from F` | drops tables the snapshot does not hold and runs `pg_restore --clean --single-transaction`; every write made after the snapshot is lost | every one must be stopped |\n| `validate [-config C]` | refuses a schema newer than the binary's highest migration; every stored resource decodes under the definition that owns it; and `configuration.Validate` accepts the settings the daemon would read -- the stored ones, or the seed the State Store writes for a kind the database does not hold yet -- layered onto `C`, the check the daemon reports as `validate database settings` | may be running |\n| `rollback -kind K [-revision N]` | replays an earlier revision of a stored resource through the ordinary replace, recording the rollback as a new revision | the State Store must be stopped |\n\nThe two validation layers `validate` reports are not the same check, and it\nreports both rather than merging them: the write path's own decode is stricter\nabout shape (it rejects unknown fields boot's decode ignores), while boot is\nstricter about meaning (only boot checks `dispatch.trigger`, and a positive\n`poll_interval`). Either one refusing is a store somebody has to look at.\n\nNo rollback RPC exists and none is needed: a revision carries its own value, so\nrestoring one is the same replace the dashboard and the channels already use.\nThe offline command is that operation with the store stopped -- the one state in\nwhich the daemon's own API cannot serve it.\n\n\"Must be stopped\" is checked rather than assumed. Each serving process holds a\nPostgres ownership lock for its whole life. `rollback` holds the `state-store`\nclaim for the replay. `restore` claims every service role's lock (`state-store`\nand `gateway`) without waiting and refuses if any is held or the check cannot\ncomplete. The read-only commands -- `backup` and `validate` -- take no claim and\nare meant to run against a serving database: `backup` because the update\ninstaller runs inside the process it is replacing and cannot stop the State\nStore, and `validate` because an operator checks a running deployment with it.\n`scripts/archie-update-install` takes its pre-flight snapshot through this\nsubcommand, so the installer and an operator run one implementation.\n\n`rollback` is the surgical route back from a bad stored value; `restore` is the\nblunt one, and is also the way back from a schema migration a release cannot\ngrow out of.\n\nThere is no automatic schema rollback. goose `Down` drops tables, so it is data\nloss, not a rollback. `scripts/archie-update-install` refuses a daemon update\nit cannot snapshot first, and on a failed update `scripts/archie-update-watchdog`\nrolls the binaries back, leaves the database alone and prints the `restore`\ncommand for the pre-update snapshot. Whether to run it is the operator's call.\n\n## Gateway restart: two constraints learned the hard way\n\nTelegram `/restart` (`internal/channels/telegram/restart.go` plus the `Start`\nsupervisor loop). Recovered 2026-08-09 from the pre-migration issue tracker.\nBoth constraints must survive any refactor.\n\n**1. Deadlock.** The `/restart` handler runs *on* the bot instance the supervisor\nis about to stop. Tearing down inline from the handler deadlocks the restart it\njust asked for. So the handler sends on a **buffered** channel (`restartCh`,\ncapacity 1) and returns immediately; the supervisor loop in `Start` does the\nteardown. Duplicate requests hit the default branch and are dropped, not queued.\n\n**2. Lockout.** A failed config reload must **not** be fatal. It logs and\nrelaunches with the previous in-memory settings. If a bad config edit killed the\ngateway, it would also destroy the only means of fixing it remotely — which is\nthe entire reason `/restart` exists.\n\n**Scope is gateway-only by design.** The daemon keeps running so in-flight agent\ntasks survive. Exiting the process would also restart under a `unless-stopped`\npolicy, but would kill running work. `Reload` (supplied by `cmd/archied/main.go`)\nre-reads config from disk and refreshes **only** the token and `AllowedUserIDs`;\neverything else is wired into the daemon at construction and still needs a full\nrestart.\n\n**Authorisation is inherited:** `authorizedMessage` rejects non-allowlisted\nsenders before any handler runs, so all gateway commands are admin-only by\nconstruction. Do not add per-command auth without checking that invariant still\nholds.\n" }, { "url": "/dev/prds/01-project-management/", @@ -142,7 +142,7 @@ "url": "/dev/prds/binding-secret-encryption/", "title": "Binding secret at-rest encryption -- decision", "section": "PRDs", - "body": "# Binding secret at-rest encryption -- decision\n\n**Status:** Approved\n**Date:** 2026-09-02\n**Beads issue:** `archie-core-t2db.7` (P2), parent `archie-core-t2db`\n\n## Problem\n\n`binding.Binding.Secret` (the per-source HMAC shared secret) is persisted as\nplaintext in the `bindings.secret TEXT` column. Anyone with read access to the\nSQLite file -- the same access level as `captured_events.body` and `tasks.body`\n-- sees sender-side shared secrets. A leaked database file leaks secrets even\nwhen the filesystem ACLs were correct at rest.\n\n## Decision\n\nEncrypt the `secret` column at rest with **AES-256-GCM** (stdlib\n`crypto/aes` + `crypto/cipher`, no new dependency), transparently inside the\nstore: encrypt on write, decrypt on read. The store is the data boundary; its\nconsumers (dispatch loop, HMAC verification) receive the plaintext secret\nexactly as and the webui already blanks `Secret` on every response.\n\n### Cipher parameters\n\n- **AEAD:** AES-256-GCM, 12-byte random nonce (`crypto/rand`), tag appended.\n- **Key length:** 32 bytes, derived as `SHA-256(resolved_material)`. Kept as\n SHA-256 (no Argon2id) because the source is a **32-byte high-entropy** value\n resolved through the secret registry, so re-deriving to 32 bytes merely\n re-shapes entropy rather than defending a weak passphrase.\n- **AAD:** a static domain separator, `[]byte(\"arcie-binding-secret\")`, so a\n ciphertext cannot be relocated to a different field/column and still\n authenticate. AAD is intentionally **not** row-bound: binding secrets are\n random HMAC keys and are never used as lookup keys, so cross-row swap is not\n a meaningful attack here.\n\n### Envelope format\n\n```\narcie-binding:v1:\u003ckeyFingerprint\u003e:\u003cbase64url(nonce || ciphertext || tag)\u003e\n```\n\n- `arcie-binding` -- domain marker\n- `v1` -- format version (future cipher/KDF change is a new version, old rows\n stay readable)\n- `\u003ckeyFingerprint\u003e` -- `hex(SHA-256(material))[:16]`, the identity of the key\n that sealed the row, enabling rotation without a one-shot rewrite\n- payload -- `base64url` of `nonce ‖ GCM.Seal(plaintext, aad)`\n\n### Key source (confirmed with maintainer)\n\nResolved through the existing secret registry (`internal/secret`), the\nestablished `SecretRef` pattern already used for `forge.webhook_secret`:\n\n```toml\n[bindings]\nencryption_key = { engine = \"env\", key = \"ARCHIE_BINDING_KEY\" }\n# Rotation: after swapping encryption_key to a new value, retain the previous\n# material so rows sealed under the old key still decrypt.\nprevious_encryption_keys = [ { engine = \"env\", key = \"ARCHIE_BINDING_KEY_OLD\" } ]\n```\n\nThe active key encrypts new writes; `previous_encryption_keys` are retained for\ndecrypt-only. Key identity is intrinsic to the material (the fingerprint), so\nno manual key IDs are configured.\n\n### Rotation story\n\nRotate by changing `encryption_key`, moving the old material into\n`previous_encryption_keys`. Rows sealed under the old key still decrypt via\ntheir embedded fingerprint; new writes use the new active key. Once no\nremaining row references an old fingerprint, remove it from the config. Losing\na fingerprint's material before all its rows are rewritten makes those rows\nunreadable -- the same operational rule as any key rotation, and the reason the\nold material must be retained.\n\n## Non-goals / deferred\n\n- **`captured_events.body` redaction hardening** was completed alongside this\n work (not deferred): `webhookguard.RedactPayload` now redacts an expanded set\n of secret key markers (compound names like `access_token`, `client_secret`,\n `signing_key`, `x_api_key`, …) as well as unambiguous value shapes (compact\n JWTs, PEM private-key blocks) under any key. `gateway.sensitiveParameterKey`\n was broadened identically to preserve the documented agreement. It remains\n best-effort per `docs/prds/webhook-intake-security.md` point 5 -- a sender\n that picks a name the heuristic misses is still captured.\n- **Key re-derivation on config reload** is a startup concern: the store holds\n the cipher for its lifetime, so a reload that changes `[bindings]` keys\n requires a daemon restart to take effect. Documented, accepted.\n\n## Wiring\n\n- `internal/config`: add `BindingsConfig` (`encryption_key SecretRef`,\n `previous_encryption_keys []SecretRef`) on `Config.Bindings`.\n- `internal/app/archied/bootstrap.go` `openStores`: resolve both refs through\n the already-built `secrets` registry, pass the material to `store.Open` via a\n new option `store.WithBindingCipher(cipher)`.\n- `internal/store`: add a `BindingCipher` interface (concrete AES-GCM impl in\n `binding_cipher.go`), a `bindingCipher` field on `Store`, and the `Open`\n option. **Nil cipher = plaintext**, so existing call sites and tests change\n nothing and legacy deployments keep current behaviour until they set a key.\n\n## Back-compat \u0026 tests\n\n- `store.Open` gains the option variadically; all current call sites compile\n unchanged.\n- Existing plaintext rows are unaffected until a cipher is configured; rows\n written before a cipher is installed remain plaintext and read as plaintext.\n- Tests: cipher round-trip (Encrypt/Decrypt), wrong-key and tampered-ciphertext\n integrity failure, envelope parse errors, and a store round-trip that asserts\n the persisted column is NOT the plaintext while `GetBinding` returns it.\n" + "body": "# Binding secret at-rest encryption -- decision\n\n**Status:** Approved\n**Date:** 2026-09-02\n**Beads issue:** `archie-core-t2db.7` (P2), parent `archie-core-t2db`\n\n## Problem\n\n\u003e Storage superseded: every store now lives in PostgreSQL behind\n\u003e `internal/domain/storecontract`, implemented in `internal/infrastructure/postgres`\n\u003e (`docs/prds/state-store-contract.md`). SQLite names below describe the\n\u003e original design.\n\n`binding.Binding.Secret` (the per-source HMAC shared secret) is persisted as\nplaintext in the `bindings.secret TEXT` column. Anyone with read access to the\nSQLite file -- the same access level as `captured_events.body` and `tasks.body`\n-- sees sender-side shared secrets. A leaked database file leaks secrets even\nwhen the filesystem ACLs were correct at rest.\n\n## Decision\n\nEncrypt the `secret` column at rest with **AES-256-GCM** (stdlib\n`crypto/aes` + `crypto/cipher`, no new dependency), transparently inside the\nstore: encrypt on write, decrypt on read. The store is the data boundary; its\nconsumers (dispatch loop, HMAC verification) receive the plaintext secret\nexactly as and the webui already blanks `Secret` on every response.\n\n### Cipher parameters\n\n- **AEAD:** AES-256-GCM, 12-byte random nonce (`crypto/rand`), tag appended.\n- **Key length:** 32 bytes, derived as `SHA-256(resolved_material)`. Kept as\n SHA-256 (no Argon2id) because the source is a **32-byte high-entropy** value\n resolved through the secret registry, so re-deriving to 32 bytes merely\n re-shapes entropy rather than defending a weak passphrase.\n- **AAD:** a static domain separator, `[]byte(\"arcie-binding-secret\")`, so a\n ciphertext cannot be relocated to a different field/column and still\n authenticate. AAD is intentionally **not** row-bound: binding secrets are\n random HMAC keys and are never used as lookup keys, so cross-row swap is not\n a meaningful attack here.\n\n### Envelope format\n\n```\narcie-binding:v1:\u003ckeyFingerprint\u003e:\u003cbase64url(nonce || ciphertext || tag)\u003e\n```\n\n- `arcie-binding` -- domain marker\n- `v1` -- format version (future cipher/KDF change is a new version, old rows\n stay readable)\n- `\u003ckeyFingerprint\u003e` -- `hex(SHA-256(material))[:16]`, the identity of the key\n that sealed the row, enabling rotation without a one-shot rewrite\n- payload -- `base64url` of `nonce ‖ GCM.Seal(plaintext, aad)`\n\n### Key source (confirmed with maintainer)\n\nResolved through the existing secret registry (`internal/secret`), the\nestablished `SecretRef` pattern already used for `forge.webhook_secret`:\n\n```toml\n[bindings]\nencryption_key = { engine = \"env\", key = \"ARCHIE_BINDING_KEY\" }\n# Rotation: after swapping encryption_key to a new value, retain the previous\n# material so rows sealed under the old key still decrypt.\nprevious_encryption_keys = [ { engine = \"env\", key = \"ARCHIE_BINDING_KEY_OLD\" } ]\n```\n\nThe active key encrypts new writes; `previous_encryption_keys` are retained for\ndecrypt-only. Key identity is intrinsic to the material (the fingerprint), so\nno manual key IDs are configured.\n\n### Rotation story\n\nRotate by changing `encryption_key`, moving the old material into\n`previous_encryption_keys`. Rows sealed under the old key still decrypt via\ntheir embedded fingerprint; new writes use the new active key. Once no\nremaining row references an old fingerprint, remove it from the config. Losing\na fingerprint's material before all its rows are rewritten makes those rows\nunreadable -- the same operational rule as any key rotation, and the reason the\nold material must be retained.\n\n## Non-goals / deferred\n\n- **`captured_events.body` redaction hardening** was completed alongside this\n work (not deferred): `webhookguard.RedactPayload` now redacts an expanded set\n of secret key markers (compound names like `access_token`, `client_secret`,\n `signing_key`, `x_api_key`, …) as well as unambiguous value shapes (compact\n JWTs, PEM private-key blocks) under any key. `gateway.sensitiveParameterKey`\n was broadened identically to preserve the documented agreement. It remains\n best-effort per `docs/prds/webhook-intake-security.md` point 5 -- a sender\n that picks a name the heuristic misses is still captured.\n- **Key re-derivation on config reload** is a startup concern: the store holds\n the cipher for its lifetime, so a reload that changes `[bindings]` keys\n requires a daemon restart to take effect. Documented, accepted.\n\n## Wiring\n\n- `internal/config`: add `BindingsConfig` (`encryption_key SecretRef`,\n `previous_encryption_keys []SecretRef`) on `Config.Bindings`.\n- `internal/app/archied/bootstrap.go` `openStores`: resolve both refs through\n the already-built `secrets` registry, pass the material to `store.Open` via a\n new option `store.WithBindingCipher(cipher)`.\n- `internal/infrastructure/bindingcipher`: the `BindingCipher` interface and\n concrete AES-GCM impl, consumed by the event-capture store; a `bindingCipher` field on `Store`, and the `Open`\n option. **Nil cipher = plaintext**, so existing call sites and tests change\n nothing and legacy deployments keep current behaviour until they set a key.\n\n## Back-compat \u0026 tests\n\n- `store.Open` gains the option variadically; all current call sites compile\n unchanged.\n- Existing plaintext rows are unaffected until a cipher is configured; rows\n written before a cipher is installed remain plaintext and read as plaintext.\n- Tests: cipher round-trip (Encrypt/Decrypt), wrong-key and tampered-ciphertext\n integrity failure, envelope parse errors, and a store round-trip that asserts\n the persisted column is NOT the plaintext while `GetBinding` returns it.\n" }, { "url": "/dev/prds/channel-forge-positions/", @@ -220,7 +220,7 @@ "url": "/dev/prds/dynamic-curators/", "title": "Dynamically-defined curators -- decision", "section": "PRDs", - "body": "# Dynamically-defined curators -- decision\n\n**Status:** Approved\n**Date:** 2026-09-12\n**GitHub epic:** [#789](https://github.com/samcharles93/archie-core/issues/789)\n**Parent epic (curator engine):** [#435](https://github.com/samcharles93/archie-core/issues/435) (closed)\n**Depends on:** nothing shipping; this resolves the open question that epic #435's\n\"registered and configured declaratively, not hardcoded\" criterion left open.\n\n## §0 Implementation status\n\nEvery claim in this document is mapped to what exists in the tree.\n\n| Claim | Status | Where it stands |\n|---|---|---|\n| Curator engine family: typed contract, owning registry, start/health/stop, narrow host access | **Implemented** | `internal/domain/curator/{contract,registry,runtime,registrar,activity,wake}.go` |\n| Curator declared shape (`Manifest`: interval, cooldown, on_input, tools, skills, memory engine, conversations, model) | **Implemented** | `internal/domain/curator/contract.go`; `Validate()` requires `Interval \u003e 0` |\n| Two reference curators run through the registry | **Implemented** | `internal/infrastructure/skillcurator`, `internal/infrastructure/sessioncurator` |\n| Curator definitions as persisted, API-editable data | **Aspirational -- zero code** | No table, no entity, no RPC, no config block |\n| Generic definition-driven engine that executes a declared tool set + free-form instructions | **Aspirational -- zero code** | Only the two code-registered curators exist |\n| `Registrar.Tools` (`ToolBuilder`) resolved and bound at registration | **Partial** | Interface declared (`registrar.go`); **no implementation anywhere**; `bootstrap.go` builds the `Registrar` with no `Tools` field |\n| A curator can declare tools at all | **Partial** | `Manifest.Tools` exists, but `registry.go` fails registration with `\"curator manifest: declares tools but the registrar has no ToolBuilder\"` |\n| Curator passes that actually reach a model with tools | **Cosmetic only** | `curator.ChatRequest` carries `Tools`/`MaxSteps`; `curatorLLMRunner` (`internal/app/archied/main.go`) drops both and returns `ChatResult{Text}` only |\n| Dynamic registration / removal (no restart) | **Aspirational -- zero code** | `Registry` has `Register`, no `Unregister`; `Runtime` has `Start`/`Nudge`/`Stop`, no `Add`/`Remove`; `Start()` snapshots membership |\n| Curator definition CRUD over REST | **Partial** | `GET /api/curators` read-only (`internal/webui/server.go`); no write routes |\n| Curator definition config | **Aspirational -- zero code** | No `[curator]` block in `internal/config/config.go` |\n| Store/API as definition authority | **Aspirational -- zero code** | No curator persistence of any kind |\n| No live-path defaults for interval/cooldown/tools/model/memory engine | **Partial** | `skillcurator.DefaultInterval` / `sessioncurator.DefaultInterval` are Go consts read at registration; `curator.NewRuntime(..., RuntimeConfig{})` uses code defaults for pass timeout and concurrency |\n| Idle curators are observable in logs | **Partial** | `runtime.go` logs nothing when `Check` reports not-due; the session-memory curator's hourly pass is the only curator activity ever logged |\n| Sampler family | **Implemented** | `internal/domain/sampling`, shipped; no curator consumes a `Sampler` yet |\n| Forge/issue reach from chat | **Implemented** (via `shell`) | No dedicated issue tool exists, but the chat agent's `shell` is unconfined (`chat.unrestricted_filesystem = true`), so `gh issue edit|comment|create|close` works. Dedicated tools (#161) are convenience, not a blocker |\n\n\u003e **Target state, not current state.** Everything below marked aspirational is\n\u003e design, not a description of the daemon as it runs.\n\n## Problem\n\nA curator exists only if a Go package implements `curator.CuratorEngine`\nand `bootstrap.go/1025` names it in a `Register` call. Nothing about a\ncurator is definable as data. Worse, no curator can declare a tool set at all:\nthe `ToolBuilder` interface has no implementation in the repo, so the registry\nrefuses (correctly, fail-closed) any curator that declares tools -- and the\ndaemon's model adapter drops the tools even if it were bound. The curator family\ntherefore has exactly one shape (cheap, tool-less maintenance pass) and its only\nextension point is compiling Go.\n\nSam's requirement is the opposite: *\"Curators should be dynamically created and\ndefined, in addition to being able to be defined in code/config/webui\"* and *\"No\nconfiguration should ever be hard-coded.\"* The motivating consumer is a\nproject/orchestrator curator -- declared as data, given forge issue tools, and\npointed at a repo to review, refine, and propose issues.\n\n## Decision\n\n**A curator definition is data: a persisted entity whose declared shape is\nexactly `curator.Manifest` plus identity, free-form instructions, and an enabled\nflag. One generic engine interprets any definition.** The shape is not a second\ninvention -- `Manifest` already encodes interval, cooldown, on-input, tools,\nskills, memory engine, conversations, and model, and `Validate()` already\nenforces what a valid shape means. The definition adds only what `Manifest`\ncannot express:\n\n| Definition field | Relationship to `Manifest` |\n|---|---|\n| `name`, `enabled` | Identity and lifecycle; the registry's key is the name |\n| `instructions` | **Free-form** system prompt for the generic engine -- the piece that makes a definition more than a knob set |\n| interval, cooldown, on_input, tools, skills, memory_engine, conversations, model | The existing `Manifest` fields verbatim; the definition **is** a `Manifest` |\n\nCode-registered engines keep `CuratorEngine` unchanged. A data-defined curator is\nserved by one registered engine whose `Manifest()` is the stored definition and\nwhose `Pass` composes `instructions` with the built tool set.\n\nThis is the curator domain's missing half, not a standalone tool: it lands in\n`internal/domain/curator` (entity + engine), `internal/store` (persistence),\n`internal/webui` (CRUD), and `internal/app/archied` (seed + apply wiring).\n\n## Definition sources and the merge rule\n\nThree sources, per Sam's requirement. **The store is authoritative.**\n\n| Source | Role | Collision behaviour |\n|---|---|---|\n| **Code** (a registered Go engine) | The escape hatch: a curator whose strategy is Go, not tools+instructions | Wins over data for its own name -- a data definition cannot silently replace a compiled engine; the store refuses the collision and logs it |\n| **Config** (`[[curators]]`) | **Seed data only**, merged at startup | Insert-if-absent. A store row of the same name is never overwritten, and deleting a store row is not undone by config on the next boot |\n| **WebUI/API** (the store) | **Authoritative** | Wins over config on a name collision; the only source of truth after first boot |\n\nConfig existing at all is what makes a definition reproducible on a fresh host;\nmaking it authoritative would make the API a lie, so it is seed data with a\none-way merge. The alternative -- config authoritative, store a cache -- would\nmean an API edit silently reverts on restart. Rejected.\n\n## How the generic engine executes a definition\n\nA pass is: resolve the declared tools, compose the prompt, run the model loop,\nrecord actions.\n\n1. **Tool resolution.** `Registrar.Tools.Build(ctx, declared)` returns exactly\n the declared set, never a broader registry. A declared name with no\n implementation fails the pass rather than silently running with fewer tools.\n This is the enforcement point, and it is why the `ToolBuilder` binding is\n load-bearing rather than a convenience: without an implementation, no curator\n can declare tools at all (the `registry.go` guard).\n2. **Tool-carrying model call.** `curator.ChatRequest` already carries\n `Tools []tools.ToolEntry` and `MaxSteps`; `curatorLLMRunner` must pass them\n into `core.GenerateOptions` (which has `Tools`, `ToolChoice`, `MaxSteps`, and\n already executes the tool loop) instead of dropping them. `ChatResult` is\n widened only as far as attributing the pass's actions requires.\n3. **Prompt.** The system prompt is the definition's `instructions` plus the\n declared tool summaries -- rendered from the same set that was built, never\n from a wider list. Each pass records `Action`s so activity stays attributable\n through the existing registry `activity` surface and events.\n\nA bespoke non-tool strategy (the skill curator's structural validation, the\nsession-memory curator's own extraction) remains a registered Go engine. That is\nthe escape hatch, not the mode: the mode is tools + instructions as data.\n\n## Dynamic registration and mutation\n\nA definition change must apply without a daemon restart, which the runtime\ncannot do (`Start()` snapshots membership into one goroutine per curator;\nno `Unregister`, no `Add`/`Remove`).\n\n- `Registry.Unregister(name)` -- valid while running, same failure isolation as\n `Register` (a rejected removal affects only that curator).\n- `Runtime.Add(engine)` / `Runtime.Remove(name)` -- `Remove` cancels the removed\n curator's in-flight pass context and stops its goroutine within a bounded\n wait; it never holds the registry mutex across a pass.\n- The app layer owns the apply sequence (stop old, register new, start) so the\n registry stays the membership authority and the runtime the scheduler.\n\nRemoval must not be able to orphan a loop, and a pass that ignores cancellation\nmust not block removal forever.\n\n## REST / WebUI surface\n\nMirror `internal/webui/api_binding.go`, not a new pattern:\n\n| Route | Handler shape |\n|---|---|\n| `GET /api/curators` | Existing read-only list, fields unchanged (dashboard keeps working) |\n| `POST /api/curators` | `handleCuratorCreate` |\n| `GET /api/curators/{id}` / `PATCH` / `DELETE` | `handleCuratorGet` / `Update` / `Delete` |\n\nAll mutations behind `authorizeTaskMutation`, same as bindings and mappings. A\nsuccessful mutation goes through the runtime apply path above, so it is live\nwithout a restart.\n\n## Sequencing: persistence and the State Store\n\nThe State Store is a standalone process that solely owns `archie.db`; the daemon\nand Gateway never open it (`TestOpenStoresNeverOwnsTaskDB` guards this), and\n`proto/state/v1/state.proto` is one gRPC service fronting every ratified store\ncontract. AGENTS.md forbids adding a Go interface method without a matching RPC.\nThat fixes the order:\n\n| Phase | Ships | Proto work |\n|---|---|---|\n| 1. Engine + config source | `ToolBuilder`, tool-carrying passes, generic engine, `[[curators]]`, idle logging | None -- nothing persisted yet |\n| 2. Runtime mutation | `Unregister`, `Add`/`Remove`, apply path | None -- in-memory membership |\n| 3. Persistence | definition entity + store schema, config seed (store authoritative), REST CRUD | **Same change**: request/response messages + RPCs, `staterpc.Client` façade, `mapError`/`unmapError`, and an update to `docs/prds/state-store-contract.md` |\n\nPhases 1 and 2 are genuinely independent of the wire boundary, so they are not\nblocked on it. Phase 3 is where the boundary is unavoidable: a definition the\nWebUI can edit must be reachable from the WebUI, and the WebUI reaches the store\nthrough the State Store, not by opening `archie.db`. Splitting the RPCs into a\nlater change would leave a table nothing can read -- rejected. Deferring the\nwhole phase is the same rejection, later.\n\n## No live-path constants\n\nNo default may be a live-path constant. Interval, cooldown, tools, model, memory\nengine, pass timeout, and concurrency are definition or config values. A\ndefinition missing `interval` is refused with a clear error, never defaulted at\npass time; `skillcurator.DefaultInterval` and `sessioncurator.DefaultInterval`\nstop being read at registration (the value becomes seed data), and\n`curator.NewRuntime(..., RuntimeConfig{})` stops relying on code defaults.\n\n## What this deliberately does NOT do\n\n- **No fixed catalogue of curator \"types\".** A definition is arbitrary tools +\n instructions, not a union of known kinds.\n- **No chat tool that mints curators.** A definition grants an LLM a tool set; a\n curator able to create curators is privilege escalation. Mutation is REST with\n the same authority as bindings -- not exposed on the chat tool surface.\n- **No dashboard SPA editor page.** The REST surface is the WebUI definition\n source; the dashboard can adopt it separately.\n- **No forge issue tools here.** This design only ensures a curator *can declare*\n tools. Dedicated issue tools (#161) are a convenience, not a prerequisite: the\n chat agent already reaches issues through the unconfined `shell` tool\n (`gh issue edit|comment|create|close`). See the correction on #789.\n- **No second authority.** No file-per-curator definition store, no parallel\n config reader.\n" + "body": "# Dynamically-defined curators -- decision\n\n**Status:** Approved\n**Date:** 2026-09-12\n**GitHub epic:** [#789](https://github.com/samcharles93/archie-core/issues/789)\n**Parent epic (curator engine):** [#435](https://github.com/samcharles93/archie-core/issues/435) (closed)\n**Depends on:** nothing shipping; this resolves the open question that epic #435's\n\"registered and configured declaratively, not hardcoded\" criterion left open.\n\n## §0 Implementation status\n\nEvery claim in this document is mapped to what exists in the tree.\n\n| Claim | Status | Where it stands |\n|---|---|---|\n| Curator engine family: typed contract, owning registry, start/health/stop, narrow host access | **Implemented** | `internal/domain/curator/{contract,registry,runtime,registrar,activity,wake}.go` |\n| Curator declared shape (`Manifest`: interval, cooldown, on_input, tools, skills, memory engine, conversations, model) | **Implemented** | `internal/domain/curator/contract.go`; `Validate()` requires `Interval \u003e 0` |\n| Two reference curators run through the registry | **Implemented** | `internal/infrastructure/skillcurator`, `internal/infrastructure/sessioncurator` |\n| Curator definitions as persisted, API-editable data | **Aspirational -- zero code** | No table, no entity, no RPC, no config block |\n| Generic definition-driven engine that executes a declared tool set + free-form instructions | **Aspirational -- zero code** | Only the two code-registered curators exist |\n| `Registrar.Tools` (`ToolBuilder`) resolved and bound at registration | **Partial** | Interface declared (`registrar.go`); **no implementation anywhere**; `bootstrap.go` builds the `Registrar` with no `Tools` field |\n| A curator can declare tools at all | **Partial** | `Manifest.Tools` exists, but `registry.go` fails registration with `\"curator manifest: declares tools but the registrar has no ToolBuilder\"` |\n| Curator passes that actually reach a model with tools | **Cosmetic only** | `curator.ChatRequest` carries `Tools`/`MaxSteps`; `curatorLLMRunner` (`internal/app/archied/main.go`) drops both and returns `ChatResult{Text}` only |\n| Dynamic registration / removal (no restart) | **Aspirational -- zero code** | `Registry` has `Register`, no `Unregister`; `Runtime` has `Start`/`Nudge`/`Stop`, no `Add`/`Remove`; `Start()` snapshots membership |\n| Curator definition CRUD over REST | **Partial** | `GET /api/curators` read-only (`internal/webui/server.go`); no write routes |\n| Curator definition config | **Aspirational -- zero code** | No `[curator]` block in `internal/config/config.go` |\n| Store/API as definition authority | **Aspirational -- zero code** | No curator persistence of any kind |\n| No live-path defaults for interval/cooldown/tools/model/memory engine | **Partial** | `skillcurator.DefaultInterval` / `sessioncurator.DefaultInterval` are Go consts read at registration; `curator.NewRuntime(..., RuntimeConfig{})` uses code defaults for pass timeout and concurrency |\n| Idle curators are observable in logs | **Partial** | `runtime.go` logs nothing when `Check` reports not-due; the session-memory curator's hourly pass is the only curator activity ever logged |\n| Sampler family | **Implemented** | `internal/domain/sampling`, shipped; no curator consumes a `Sampler` yet |\n| Forge/issue reach from chat | **Implemented** (via `shell`) | No dedicated issue tool exists, but the chat agent's `shell` is unconfined (`chat.unrestricted_filesystem = true`), so `gh issue edit|comment|create|close` works. Dedicated tools (#161) are convenience, not a blocker |\n\n\u003e **Target state, not current state.** Everything below marked aspirational is\n\u003e design, not a description of the daemon as it runs.\n\n## Problem\n\nA curator exists only if a Go package implements `curator.CuratorEngine`\nand `bootstrap.go/1025` names it in a `Register` call. Nothing about a\ncurator is definable as data. Worse, no curator can declare a tool set at all:\nthe `ToolBuilder` interface has no implementation in the repo, so the registry\nrefuses (correctly, fail-closed) any curator that declares tools -- and the\ndaemon's model adapter drops the tools even if it were bound. The curator family\ntherefore has exactly one shape (cheap, tool-less maintenance pass) and its only\nextension point is compiling Go.\n\nSam's requirement is the opposite: *\"Curators should be dynamically created and\ndefined, in addition to being able to be defined in code/config/webui\"* and *\"No\nconfiguration should ever be hard-coded.\"* The motivating consumer is a\nproject/orchestrator curator -- declared as data, given forge issue tools, and\npointed at a repo to review, refine, and propose issues.\n\n## Decision\n\n**A curator definition is data: a persisted entity whose declared shape is\nexactly `curator.Manifest` plus identity, free-form instructions, and an enabled\nflag. One generic engine interprets any definition.** The shape is not a second\ninvention -- `Manifest` already encodes interval, cooldown, on-input, tools,\nskills, memory engine, conversations, and model, and `Validate()` already\nenforces what a valid shape means. The definition adds only what `Manifest`\ncannot express:\n\n| Definition field | Relationship to `Manifest` |\n|---|---|\n| `name`, `enabled` | Identity and lifecycle; the registry's key is the name |\n| `instructions` | **Free-form** system prompt for the generic engine -- the piece that makes a definition more than a knob set |\n| interval, cooldown, on_input, tools, skills, memory_engine, conversations, model | The existing `Manifest` fields verbatim; the definition **is** a `Manifest` |\n\nCode-registered engines keep `CuratorEngine` unchanged. A data-defined curator is\nserved by one registered engine whose `Manifest()` is the stored definition and\nwhose `Pass` composes `instructions` with the built tool set.\n\nThis is the curator domain's missing half, not a standalone tool: it lands in\n`internal/domain/curator` (entity + engine), `internal/infrastructure/postgres` (persistence),\n`internal/webui` (CRUD), and `internal/app/archied` (seed + apply wiring).\n\n## Definition sources and the merge rule\n\nThree sources, per Sam's requirement. **The store is authoritative.**\n\n| Source | Role | Collision behaviour |\n|---|---|---|\n| **Code** (a registered Go engine) | The escape hatch: a curator whose strategy is Go, not tools+instructions | Wins over data for its own name -- a data definition cannot silently replace a compiled engine; the store refuses the collision and logs it |\n| **Config** (`[[curators]]`) | **Seed data only**, merged at startup | Insert-if-absent. A store row of the same name is never overwritten, and deleting a store row is not undone by config on the next boot |\n| **WebUI/API** (the store) | **Authoritative** | Wins over config on a name collision; the only source of truth after first boot |\n\nConfig existing at all is what makes a definition reproducible on a fresh host;\nmaking it authoritative would make the API a lie, so it is seed data with a\none-way merge. The alternative -- config authoritative, store a cache -- would\nmean an API edit silently reverts on restart. Rejected.\n\n## How the generic engine executes a definition\n\nA pass is: resolve the declared tools, compose the prompt, run the model loop,\nrecord actions.\n\n1. **Tool resolution.** `Registrar.Tools.Build(ctx, declared)` returns exactly\n the declared set, never a broader registry. A declared name with no\n implementation fails the pass rather than silently running with fewer tools.\n This is the enforcement point, and it is why the `ToolBuilder` binding is\n load-bearing rather than a convenience: without an implementation, no curator\n can declare tools at all (the `registry.go` guard).\n2. **Tool-carrying model call.** `curator.ChatRequest` already carries\n `Tools []tools.ToolEntry` and `MaxSteps`; `curatorLLMRunner` must pass them\n into `core.GenerateOptions` (which has `Tools`, `ToolChoice`, `MaxSteps`, and\n already executes the tool loop) instead of dropping them. `ChatResult` is\n widened only as far as attributing the pass's actions requires.\n3. **Prompt.** The system prompt is the definition's `instructions` plus the\n declared tool summaries -- rendered from the same set that was built, never\n from a wider list. Each pass records `Action`s so activity stays attributable\n through the existing registry `activity` surface and events.\n\nA bespoke non-tool strategy (the skill curator's structural validation, the\nsession-memory curator's own extraction) remains a registered Go engine. That is\nthe escape hatch, not the mode: the mode is tools + instructions as data.\n\n## Dynamic registration and mutation\n\nA definition change must apply without a daemon restart, which the runtime\ncannot do (`Start()` snapshots membership into one goroutine per curator;\nno `Unregister`, no `Add`/`Remove`).\n\n- `Registry.Unregister(name)` -- valid while running, same failure isolation as\n `Register` (a rejected removal affects only that curator).\n- `Runtime.Add(engine)` / `Runtime.Remove(name)` -- `Remove` cancels the removed\n curator's in-flight pass context and stops its goroutine within a bounded\n wait; it never holds the registry mutex across a pass.\n- The app layer owns the apply sequence (stop old, register new, start) so the\n registry stays the membership authority and the runtime the scheduler.\n\nRemoval must not be able to orphan a loop, and a pass that ignores cancellation\nmust not block removal forever.\n\n## REST / WebUI surface\n\nMirror `internal/webui/api_binding.go`, not a new pattern:\n\n| Route | Handler shape |\n|---|---|\n| `GET /api/curators` | Existing read-only list, fields unchanged (dashboard keeps working) |\n| `POST /api/curators` | `handleCuratorCreate` |\n| `GET /api/curators/{id}` / `PATCH` / `DELETE` | `handleCuratorGet` / `Update` / `Delete` |\n\nAll mutations behind `authorizeTaskMutation`, same as bindings and mappings. A\nsuccessful mutation goes through the runtime apply path above, so it is live\nwithout a restart.\n\n## Sequencing: persistence and the State Store\n\nThe State Store is a standalone process that solely owns the task database; the daemon\nand Gateway never open it (`TestOpenStoresNeverOwnsTaskDB` guards this), and\n`proto/state/v1/state.proto` is one gRPC service fronting every ratified store\ncontract. AGENTS.md forbids adding a Go interface method without a matching RPC.\nThat fixes the order:\n\n| Phase | Ships | Proto work |\n|---|---|---|\n| 1. Engine + config source | `ToolBuilder`, tool-carrying passes, generic engine, `[[curators]]`, idle logging | None -- nothing persisted yet |\n| 2. Runtime mutation | `Unregister`, `Add`/`Remove`, apply path | None -- in-memory membership |\n| 3. Persistence | definition entity + store schema, config seed (store authoritative), REST CRUD | **Same change**: request/response messages + RPCs, `staterpc.Client` façade, `mapError`/`unmapError`, and an update to `docs/prds/state-store-contract.md` |\n\nPhases 1 and 2 are genuinely independent of the wire boundary, so they are not\nblocked on it. Phase 3 is where the boundary is unavoidable: a definition the\nWebUI can edit must be reachable from the WebUI, and the WebUI reaches the store\nthrough the State Store, not by opening the database. Splitting the RPCs into a\nlater change would leave a table nothing can read -- rejected. Deferring the\nwhole phase is the same rejection, later.\n\n## No live-path constants\n\nNo default may be a live-path constant. Interval, cooldown, tools, model, memory\nengine, pass timeout, and concurrency are definition or config values. A\ndefinition missing `interval` is refused with a clear error, never defaulted at\npass time; `skillcurator.DefaultInterval` and `sessioncurator.DefaultInterval`\nstop being read at registration (the value becomes seed data), and\n`curator.NewRuntime(..., RuntimeConfig{})` stops relying on code defaults.\n\n## What this deliberately does NOT do\n\n- **No fixed catalogue of curator \"types\".** A definition is arbitrary tools +\n instructions, not a union of known kinds.\n- **No chat tool that mints curators.** A definition grants an LLM a tool set; a\n curator able to create curators is privilege escalation. Mutation is REST with\n the same authority as bindings -- not exposed on the chat tool surface.\n- **No dashboard SPA editor page.** The REST surface is the WebUI definition\n source; the dashboard can adopt it separately.\n- **No forge issue tools here.** This design only ensures a curator *can declare*\n tools. Dedicated issue tools (#161) are a convenience, not a prerequisite: the\n chat agent already reaches issues through the unconfined `shell` tool\n (`gh issue edit|comment|create|close`). See the correction on #789.\n- **No second authority.** No file-per-curator definition store, no parallel\n config reader.\n" }, { "url": "/dev/prds/dynamic-workflow-triage/", @@ -232,7 +232,7 @@ "url": "/dev/prds/eda-playbook-engine/", "title": "EDA playbook engine -- design", "section": "PRDs", - "body": "# EDA playbook engine -- design\n\n**Status:** Draft\n**Date:** 2026-09-03\n**Beads epic:** `archie-core-t2db`\n\n## Problem\n\n\"Which workflow runs for which trigger\" is hardcoded Go: a literal\nlabel vocabulary (`workintake.labelKinds`) and a literal label-\u003eworkflow map\n(`workflow/routing.go`), extended only by adding a Go case or shipping a\nskill whose `metadata.archie.workflow` overrides one *named* built-in\nworkflow. Extending the system to a new trigger, a new action, or a new\nevent source means a feature branch, a code change in a hardcoded\npath, and new Go tests -- for every addition. That is the barrier this\ndocument exists to remove.\n\nThe goal: triggers, the actions they run, and the\nconditions that connect them should be **drop-in and load**, not **drop-in\nand touch application code**. Yaegi-evaluated Go is the unit of imperative\n\"do a thing\" logic; YAML playbooks are pure orchestration data -- no logic,\njust \"on this event, with this data, call these actions, in this order,\nunder these conditions.\" The daemon's event coordinator doesn't know what a\n`bugfix` or `image-gen` action does, it resolves the name against a\nregistry and pipes typed data through.\n\nThis is explicitly **not** scoped to code-generation workflows. A playbook\naction can be any registered capability -- run a codegen workflow, send a\nmessage on a channel, open something on a forge, generate an image -- so\nlong as it's implemented behind one of the typed engine families below.\n\n## Relationship to existing decisions\n\n- `docs/prds/event-sources-and-reactions.md` ruled\n that reactions in the two epics it covers are **producer-only** (no veto,\n no mutation of in-flight work) and explicitly rejected a single generic\n `Source` interface as \"the untyped-hook shape the plugin engine rule\n exists to prevent.\" **This document extends that scope**: playbooks can\n dispatch to multiple typed action kinds, not just \"produce a\n `TaskEnvelope`.\" It does not relitigate producer-only-ness (still no\n veto/mutation of in-flight work here) and it does not introduce one\n generic interface -- see \"Typed positions, not one generic hook\" below,\n which is how it stays compliant with the plugin engine rule instead of\n reopening that document's #4.\n- `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`\n governs every extension point\n introduced here. Every position below is a typed domain contract with an\n owning registry, not a generic callback map. This is a hard constraint,\n confirmed against the existing rule text before writing this doc.\n- Yaegi is already a proven in-process extension mechanism\n (`internal/plugin`, `internal/domain/workflow/wfeval/yaegi.go`,\n `internal/gate/gateeval/yaegi.go`, `internal/skill/plugin.go`) -- this\n design generalizes its existing role, it does not introduce a new\n execution mechanism.\n- `internal/domain/workflow/skillbuild.BuildRegistry` already composes a\n `workflow.Registry` from a skills catalog, plugin-defined overriding\n built-in. The playbook loader described here supersedes label routing\n specifically; it does not replace `skillbuild`'s workflow-composition role,\n it becomes an additional input the daemon composes at startup.\n- Webhook event intake is a separate design. This\n document defines the router each webhook-sourced event should be able to\n reach; it does not redesign webhook receipt itself.\n\n## Shape: four logic positions, each a typed engine family\n\nEvery entrypoint kind (mechanism, action, loop, schedule, route, trigger) is itself a schema emitter: defining a new kind produces the\ngenerated contract downstream tooling consumes. The kinds slot into a fixed\nhierarchy of logic positions:\n\n```\nWorkflow -\u003e Module -\u003e Channel (telegram/whatsapp/email/...)\n -\u003e Forge (GitHub/Gitea/GitLab/...)\n```\n\nEach position is its own typed engine family per the plugin engine rule:\nidentity + capability-specific operations, an owning `Registry`/`Manager`,\nexplicit lifecycle where the implementation owns resources, narrow host\naccess. Concretely:\n\n- **Workflow** -- already exists (`internal/domain/workflow`). A playbook\n action of kind `workflow` invokes a registered `workflow.Registry` entry\n by name, unchanged from the existing execution path.\n- **Module** -- the new general-purpose action position. A `Module` is a\n Yaegi-evaluated implementation of a generated interface (args in, typed\n result out) for one declared action kind (e.g. `image-gen`, `notify`,\n `open-pr-comment`). This is the position that makes actions \"not\n restricted to code-generation.\" Full design (schema-per-kind, the\n registry shape, the trust boundary, the recommended first slice):\n `docs/prds/module-position.md`.\n- **Channel** -- already exists as `channels.Channel` (telegram, email,\n webhook). A playbook action of kind `channel` sends through a named,\n already-registered channel. No new mechanism; this document just makes it\n addressable from a playbook.\n- **Forge** -- forge clients (GitHub, Gitea, GitLab) become an addressable\n action position the same way Channel is, so a playbook can say \"comment\n on this forge issue\" without that being a special case wired only into\n the poller.\n\n**Typed positions, not one generic hook.** There is no single `Action`\ninterface with an `any` payload. Each position keeps its own typed\ncontract; the playbook YAML names a position and an implementation, and the\nevent coordinator resolves that pair against the matching typed registry.\nThis is what keeps the design compliant with the plugin engine rule and\nwith `event-sources-and-reactions.md`'s rejection of a generic `Source`/\nhook interface -- the generality lives in the YAML data model (which\npositions exist, which named implementations are registered), not in a\nruntime `any`-typed dispatch path.\n\n## `go:generate`-driven schemas, from day one\n\nSchemas are not a future nicety bolted onto an ad hoc\nYAML shape. They are the struct+interface contracts for each logic\nposition, and they drive code generation from the start.\n\n- Each logic position (Workflow/Module/Channel/Forge) has a schema source\n (Go-annotated types, following the existing pattern elsewhere in the\n repo) from which `go:generate` emits the interface and struct scaffolding\n an implementation must satisfy.\n- A Yaegi module implements the generated interface for its position. The\n generated contract is what makes an implementation valid, not hand-review.\n- The schema is also what the linter and LSP (below) validate a playbook\n YAML against -- one source of truth for codegen, startup loading, and\n authoring-time tooling, so the three can't drift from each other.\n- Schema versioning is explicit per position, independent of a playbook's\n own workflow version (see collision handling below).\n\nThe generator itself is not designed here. The constraint is\nschema-first, `go:generate`-driven, per logic position.\n\n## Playbook YAML: pure orchestration data\n\nA playbook declares no embedded logic -- only:\n\n- **trigger**: the event predicate (e.g. forge issue assigned + labelled\n `bugfix`, a schedule tick, a webhook payload shape).\n- **actions**: an ordered list, each naming a logic position and a\n registered implementation, with typed argument data and optional\n conditions.\n- **data flow between actions**: results/facts from one action available to\n later actions in the same playbook run -- exact interpolation syntax is\n an open point, not decided here (see Open questions).\n\nPlaybooks live in a configured directory (repo/directory-scoped, per Sam's\n\"define repos, directories, playbooks\" framing) and are loaded at archied\nstartup, alongside the existing skills-catalog composition.\n\n## Dedup: detect and log, no arbitration mechanism\n\nNo runtime auto-resolution rule. An automatic \"pick a winner\" algorithm\n(e.g. by version) is itself a mechanism that can fail and need debugging\nwhen a collision happens -- the wrong kind of complexity to introduce for\na case that should just be visible and fixed by a human. Instead:\n\n- **At daemon startup:** if independently-sourced playbook directories\n declare a collision on the same trigger, that is a definition failure.\n The colliding definitions are dropped (not loaded) and the failure is\n logged plainly (which sources, which trigger) and reported back to the\n caller that requested the load -- not swallowed as a background log line\n only. The schema is the definition; a schema conflict is a reported\n failure, not something the daemon silently arbitrates.\n- **Linter**: a CI/dev-time tool, reading the same generated schemas, that\n flags duplicate or conflicting trigger definitions *within* a single\n maintained tree before merge.\n\n **Resolved** (`archie-core-t2db.12`). A standalone\n gopls-shaped binary (`cmd/archie-playbooks`, lint subcommand) validates\n playbook directories against the exact loaders the daemon uses\n (`LoadPlaybookDirs`/`LoadKindWorkflowsYAML`/`LoadLabelWorkflowsYAML`),\n exiting non-zero on any collision / malformed file / invalid binding.\n A finding about one binding key leads with the key's `file:line`, read\n from the `yaml.Node` the loader decodes; the linter agrees with runtime\n validation by construction, which is the load-bearing property. `-eda-dir`\n lints an `eda_playbook_dir` the same way, through `playbook.Load` with its\n CEL, action-id and args checks.\n Discoverable via `task lint:playbooks` or direct `go run\n ./cmd/archie-playbooks lint -dir ...`. The LSP/serve mode is a later\n entrypoint of the SAME binary, per the shared-package decision above.\n- **LSP**: same schema source again, feeding author-time hover/completion/\n inline errors while someone edits a playbook YAML in an editor. Kept\n explicitly in scope per Sam (not deferred), because it's the same schema\n artifact as the linter's, just a different consumer.\n\n `archie-playbooks serve` is the language server, over stdio. When a file is\n opened or saved it lints the file's saved directory with the loader the\n daemon runs for it (a file with a top-level `trigger` key is an EDA\n playbook, anything else a routing binding file) and publishes the findings\n for that file as error diagnostics, each on the line of the key, action,\n `when` or args key it names; a file-level finding sits on the first line.\n Unsaved edits are not validated. Hover and completion are later additions.\n\nThe startup log-and-refuse path exists for what the linter/LSP structurally\ncannot see -- sources composed together only at daemon startup, never\nchecked against each other by either tool. If the linter and LSP do the job\nthey're built for, a real collision reaching that startup path should be\nrare in practice, not a routine occurrence the design leans on.\n\n**Shared package, thin consumers -- not a bundled-vs-standalone choice.**\nThe validation logic (`LoadKindWorkflowsYAML`, `LoadLabelWorkflowsYAML`, the\ndirectory-merge from t2db.11) lives in `internal/domain/workflow`, a plain\nGo package with no knowledge of which binary calls it. This makes \"should\nthe linter/LSP be bundled into archied or a separate tool\" a non-question:\n- `archied` already imports the package directly and validates in-process\n at startup -- no subprocess, no external tool call.\n- An agent that needs to validate a playbook in-process can import the same\n package directly, for the same reason.\n- The standalone `cmd/` binary (t2db.12, gopls-shaped: one binary, a lint\n mode now, an LSP/serve mode later) exists only because CI and editors are\n out-of-process consumers by nature -- a CI step needs an exit code, an\n editor speaks LSP over a process boundary, neither can `import` a Go\n package. It is a thin wrapper per `organisation.md`'s `cmd/` rule, not a\n second implementation.\n\nFolding CLI/LSP protocol handling into `archied` itself would grow the\ndaemon into unrelated concerns, against the plugin-engine rule's spirit of\nnarrow capability families.\n\n## Execution-time gaps (both resolved)\n\nEverything above covers *loading* a playbook. Nothing above covers what\nhappens while one *runs*. Two gaps, both load-bearing enough to resolve\nbefore implementation, not defer:\n\n### 1. Mid-playbook action failure\n\n**Resolved** (`archie-core-t2db.18`). The default below\nis a committed decision, not a candidate list; changing it later would\nrequire its own decision. Gap 2 below is resolved by `archie-core-t2db.17`.\n\nA playbook is an ordered action list with data flowing between steps. If\naction 2 of 4 fails at runtime (an image-gen API times out, a forge call\n403s), the run needs a defined outcome. This\ncodebase already answers a structurally identical question for its\nexisting workflow engine, precisely enough to reuse rather than\nre-derive: `workflow.Run` (`internal/domain/workflow/workflow.go`)\ndraws a three-way distinction on a stage failure, and a playbook run\ndraws the same one on an action failure.\n\n**Decision: reuse `Run`'s three-way distinction directly.** The stated\ndefault is **stop-on-first-failure**: a real action error halts the\nplaybook run immediately and is reported, with no continue-to-next-action\nand no automatic retry or compensating follow-up. The three points below\nare the complete decision.\n\n1. **A real action error** (the action's own logic failed -- an API\n error, a validation failure inside the action) stops the run\n immediately. No later actions execute. The failure is reported the\n same way a load collision is reported -- dropped, logged plainly\n (which action and why), and returned to the caller, never swallowed\n as a background log line only (the Dedup section's drop-and-report\n rule). `Run` is the mechanical\n precedent for the stop itself: a stage error sets the park reason and\n returns without running further stages (`workflow.go`). This\n is stop-on-first-failure, matching the document's existing bias\n against clever automatic recovery, and it is now a stated decision\n rather than a nobody-chose default.\n2. **Interruption** (the daemon is shutting down mid-dispatch, `ctx.Err()\n != nil`) is explicitly **not** a failure. `Run` already treats this\n case specially -- \"Daemon shutdown is not a workflow failure. Leave\n the task running ...; parking here would publish a false failure and\n require manual intervention\" (`workflow.go`) -- and the same\n reasoning applies to a playbook run: an in-flight dispatch interrupted\n by restart must not be recorded as a broken playbook. What \"leave it\n alone for restart\" means for a playbook run (there is no `store.Task`\n row a playbook run inherently owns the way a workflow stage does) is\n an open implementation detail for whoever builds the coordinator, not\n decided here -- but the *semantic* (interruption ≠ failure) is decided.\n3. **A run that produces no outcome at all** (every action ran without\n error, but nothing was assigned to happen) is itself an error\n condition, matching `Run`'s own \"a workflow must end with an explicit\n outcome; not doing so is a definition bug, which still must not vanish\n silently\" (`workflow.go`). A playbook with actions that all ran\n but never reached a coherent terminal state is a definition bug in the\n playbook, reported as such.\n\n**Rollback:** explicitly **not attempted**, for exactly the reason the\ngap's own description named -- a posted forge comment is not revocable.\nThis is not a limitation to work around later; it is the correct\nsemantic. An operator who needs a corrective action after a failure\nwrites a *new* playbook/action for that, they do not get automatic\nundo.\n\n**This stays inside the producer-only rule.** Stop-on-first-failure is the\nrun deciding its own terminal state from its own action's error. Nothing\nalready in flight is blocked or altered; the run only declines to start\nactions that had not started yet, and it records the failure on its own\nunit the way `Run` sets a park reason and transitions the task to\n`StatusParked`. A future compensating action (\"if the notify action\nfailed, also log an incident\") would be producing new work, which the rule\nalready permits. No syntax for it is designed here.\n\n**J3 relationship, stated explicitly:** J3 (a CEL `when` condition\nerroring at eval time → treated as false → skip that action → run\ncontinues) is a **different case from an action failure** and is not\nrevisited by this resolution. A condition error means \"we couldn't\ndetermine whether to run this action,\" which this document already\nresolved as \"then don't, and move on.\" An action failure means \"we tried\nto run this action and it broke,\" which stops the run per point 1 above.\nThe two must not be conflated: a coordinator implementation should be\nable to point at one `when`-evaluation code path and one\naction-invocation code path and show they use different outcomes.\n\n### 2. Idempotency at execution time\n\n**Resolved** (`archie-core-t2db.17`, a\ndesign-investigation ticket: resolve, do not implement). The decision\nbelow is the answer; the keying scheme itself is separate follow-up work\nand is intentionally not built here. It **extends**\n`event-sources-and-reactions.md`'s existing contract -- it does not\ncontradict it (relationship argued at the end).\n\n**Problem (unchanged):** `event-sources-and-reactions.md` decided\nreactions ride `internal/eventbus`'s at-least-once delivery specifically\nso `PublishUnique`/idempotency keys absorb redelivery without duplicate\nside effects. This document inherits that for free only for\n`workflow`-kind actions, because `TaskEnvelope` already carries an\nidempotency key. It said nothing for `channel`, `forge`, or `module`\nactions with real side effects -- a posted comment, a sent message, a\nbilled image generation.\n\nOne correction to the problem statement, checked against the code rather\nthan assumed, because it changes what the answer must be:\n**`PublishUnique`'s dedup is not a consumer-redelivery guard at all.**\n`PublishUnique` only sets the JetStream `Nats-Msg-Id` header on the\noutgoing message (`internal/infrastructure/eventbus/nats/publisher.go`;\nkey constant `message.go`); JetStream suppresses *republished*\nmessages carrying a repeated key inside `Config.DedupWindow`\n(`client.go`, `Duplicates: cfg.DedupWindow`), default 2 minutes\n(`config.go`, `DefaultDedupWindow = 2 * time.Minute`). A consumer\nredelivery is the same *stored* message re-delivered on Nak or\nacknowledge-timeout (`internal/eventbus/eventbus.go`: \"a handler\nreturning an error causes redelivery\") -- not a republish; its\n`Nats-Msg-Id` is never re-firewalled, and even if it were, two minutes is\nnot an at-most-once guarantee for a side effect that must never repeat.\n**Conclusion: side-effecting action kinds need a consumer-side, durable\ndedup record; the bus cannot supply it.** That is precisely the situation\n`binding_dispatches` was built for -- so the decision below reuses its\nmechanism rather than designing a new one.\n\n#### Decision\n\n**Granularity: per-action-per-event -- one dedup record per\n(action, event) pair, not per playbook run.** Whole-run keying, the\nobvious alternative, has two crash windows: the run row is written when the run starts, so a crash mid-run\nleaves the run \"started\" and a redelivery skips *every remaining\naction* (work silently lost); a crash before the row write re-runs\n*every already-fired action* (duplicate side effects -- the exact harm\nthis gap exists to prevent). Per-action keys collapse both into one\nwindow and one behavior: an action's record is written immediately\nbefore that action's side effect is invoked, so an action fires iff its\nown record is absent, no fired action ever re-fires, and a redelivered\nevent resumes at the first unrecorded action. For the shipped\nsingle-action playbooks the two granularities are equivalent in effect;\nthe difference starts with multi-action runs -- where whole-run keying\nwould already be wrong.\n\n**Storage/lookup: a new durable ledger table `playbook_dispatches` in\n`internal/store`, copying `binding_dispatches`'s conventions exactly**\n(durable table, `INSERT OR IGNORE`, sentinel error, rows freed with\ntheir parent, survives daemon restarts -- `internal/store/bindings.go`):\n\n```sql\nCREATE TABLE playbook_dispatches (\n playbook_id TEXT NOT NULL,\n playbook_version TEXT NOT NULL,\n event_id TEXT NOT NULL,\n action_id TEXT NOT NULL,\n dispatched_at TEXT NOT NULL,\n PRIMARY KEY (playbook_id, playbook_version, event_id, action_id)\n);\n```\n\nWritten with the same `INSERT OR IGNORE` + sentinel-error convention\n(`ErrAlreadyDispatched`, `bindings.go`), so a duplicate is a no-op\nwrite rather than a constraint error, and the caller matches it with\n`errors.Is` the way the binding dispatch loop already does\n(`internal/daemon/daemon.go` -- \"another cycle already won this\nrace,\" not an error to surface). The record is consumed by the playbook\ncoordinator at dispatch time through a domain-side interface implemented\nby `internal/store` -- the same shape as `BindingDispatcher`\n(`internal/store/interface.go`) -- and the table lands in the\nstore's schema application (`internal/store/store.go`). No change\nto `internal/eventbus`; no per-message dedup state on the client.\n\n**Lifetime: no time-based expiry, and no automatic reclamation.** Rows are\nretained until an explicit `DeletePlaybookDispatches` for their playbook.\nRemoving a playbook file does not delete its rows: playbooks are read only\nat boot, so the only place to notice a removal is a boot-time reconcile,\nand a boot that finds the directory missing or unmounted loads as \"no\nplaybooks\" and would reclaim the whole ledger, letting redelivered events\nfire their side effects again. A binding's rows go with an explicit\noperator delete (`bindings.go`, same transaction); a file disappearing is\nnot an equally deliberate act. The at-most-once guarantee must not\nsilently decay, which is exactly the property that disqualifies\n`DedupWindow` above; table growth is bounded by distinct (playbook,\nevent, action) pairs and is accepted, the same tradeoff\n`binding_dispatches` already makes.\n\n**Redelivery behavior: skip the recorded action and continue the run.**\nA detected duplicate is not re-invoked, is not reported to the caller as\nan error, and is logged at debug level rather than as a warning -- this\nis the expected, correct behavior of at-least-once delivery, not an\nanomaly (same treatment as `ErrAlreadyDispatched` at\n`daemon.go`).\nThe run continues with the next action (or ends, for a single-action\nplaybook whose one action is recorded), which is what makes a redelivery\na resume rather than a dead restart.\n\n**Key derivation: a fixed composition of four structural identities,\ncomputed by the coordinator -- not a CEL expression.** The key is the\n`(playbook_id, playbook_version, event_id, action_id)` tuple above, where:\n\n- `playbook_id` is `Playbook.ID` -- the playbook file's path relative to\n its configured directory root, slash-normalized, unique within the load\n composition by construction (`internal/domain/eda/playbook`).\n- `playbook_version` is `Playbook.Version` -- a SHA-256 of the loaded\n file, recomputed on every load (`internal/domain/eda/playbook`),\n mirroring `Binding.Version`'s provenance-pinning purpose: the dispatch\n is pinned to the exact definition that was active when it fired. A\n changed playbook definition is a different key and may fire again for\n the same event -- deliberate, not a bug.\n- `event_id` is `DispatchInput.TaskID` (`playbook.go`), which\n carries the `TaskEnvelope.IdempotencyKey()` value\n (`\"archie:\" + owner/repo/number`,\n `internal/domain/workintake/envelope.go`). It is chosen over\n `store.Task.ID` because the trigger vocabulary is issue-level\n workintake label/kind, dispatched at discovery time (pollNATS, forge\n webhook receiver), where no task row exists yet (`playbook.go`\n comment; `playbook_test.go`: \"the value available at the\n discovery/dispatch point... NOT a store.Task.ID int64\"). Keying on the\n issue identity rather than the delivery source is the load-bearing\n property the existing contract already established for `TaskEnvelope`\n (`event-sources-and-reactions.md` question 4: a webhook-sourced\n envelope for the same issue produces the *same* idempotency key as a\n poll-discovered one; `internal/forge/webhook/receiver.go` --\n \"Idempotency is not this package's job\"); this resolution inherits that\n property rather than re-deciding it. Consequence, stated explicitly:\n same-issue re-discoveries (a re-label that re-triggers the same kind)\n are the *same event* by design -- the workintake trigger vocabulary is\n issue-granular, exactly as `TaskEnvelope`'s own key is. A future\n capture/binding-originated trigger type keys on `captured_events.id`\n instead; derivation is per-trigger-type, not one formula for all\n triggers (rule carried over unchanged from the draft).\n- `action_id` is the action's declared `id` -- J1's named ids, \"a\n required field on every action that later actions reference\", unique\n and stable-identifier-shaped, validated at load (the CEL resolution's\n J1 and its context table above in this document). For an action declaring no `id`\n (permitted by J1 while unreferenced), the key uses the action's 1-based\n position in the playbook: deterministic and stable for the\n single-action playbooks, and a later reorder is a file edit whose\n content hash changes `playbook_version` with it, so a positional\n fallback cannot silently collide with a prior definition.\n\n**No CEL in the key -- stated explicitly because the CEL resolution\nflagged this as gap 2's \"first real exercise\"** (\"CEL's read-only result\naccess makes gap 2's keying derivation readable\" -- the CEL resolution's\nclosing note). Readability\nis not the binding constraint; **determinism under redelivery is**, and\nCEL key expressions lose three ways. First, they are not load-checkable:\n`event` stays `dyn` by the resolved J4 (schema-by-example), so\na key expression over event fields cannot be type-checked at load,\nviolating the document's reject-at-load philosophy. Second, they can\nfail at dispatch (a missing field is a CEL error), and a key that cannot\nbe computed is an unfireable state -- neither \"skip\" nor \"fire\" is safe\nwithout losing or duplicating work. Third, the contract needs one\nderivation, and two authors writing different key expressions would\nfragment the ledger. The key is therefore structural by construction:\nevery component above is an immutable identity of the run's inputs, so\ntwo deliveries of the same event derive the same key with no evaluation.\nThe exercise's actual outcome is the derivation rule above; CEL remains\na *condition* surface (`when`), never a key surface. An action kind that\ngenuinely needs finer granularity than (action, event), such as \"per\ncomment, not per issue\", arrives with its own trigger type and its own\nevent identity, per the per-trigger-type rule.\n\n**Record-before-invoke -- one deliberate divergence from\n`binding_dispatches`, justified by the harm profile.** The binding\ndispatch loop enqueues the task first and records the ledger row after\n(`daemon.go`), accepting that racing cycles may both enqueue\n(\"the duplicate task remains queued... delete-on-races is its own can of\nworms\"); the selection query excludes already-dispatched captures\n(`bindings.go`), but the race window remains. That ordering is\ncorrect there because the duplicate artifact is an internal task row --\nrecoverable, low-harm. The playbook ledger's ordering is reversed on\npurpose: **the row is written and committed before the action's side\neffect is invoked** -- the `INSERT OR IGNORE` is the atomic gate, and\nthe lost-write loser skips without invoking. The cost is stated, not\nhidden: a crash between the row commit and the invoke loses that one\naction's side effect, repairable by hand -- the reverse direction of the\nsame window that would otherwise duplicate a posted comment or\nre-bill an image generation. For side effects whose duplication is\nexternally visible and not revocable, at-most-once is the required\ndirection; the binding system's at-least-once-tolerant ordering is not\nthe precedent for this ledger.\n\n**Gap-1 interplay, stated to keep the two mechanisms separate:** the\nledger answers one question per action -- has this action already fired\nfor this event? It does not answer whether the run continues, stops, or\nis re-attempted; that is gap 1's coordinator concern (a run-outcome\nrecord; gap 1 explicitly leaves \"what leave it alone for restart means\nfor a playbook run\" to whoever builds the coordinator). One consequence\nof record-before: an action that FAILED (gap 1's real-action-error case)\nhas a ledger row, so a later redelivery of the same event skips it --\nconsistent with gap 1's \"no automatic retry\" resolve (a corrective\naction is a *new* playbook/action, per gap 1's rollback paragraph). A\nfailed action is never re-attempted by the bus; if a run must be\nrecovered, an operator edits the playbook -- new version, new key --\nrather than fighting ledger state.\n\n**Relationship to `event-sources-and-reactions.md` -- extension, not\ncontradiction.** Keyed to that document's sections:\n\n1. Its decision 2 commits reactions to at-least-once delivery via\n `PublishUnique`'s \"without duplicate enqueue\" guarantee -- which, with\n the code facts above, is accurate for the *publish* path only:\n `PublishUnique` absorbs duplicate publishes of the same event (poll\n vs. webhook), which is what that decision was actually about. This\n document's own problem statement, taken literally, overstates it\n (\"keys absorb redelivery without duplicate side effects\") -- that\n overstatement is exactly what this gap exists to correct. The\n existing contract never claimed consumer redeliveries of\n side-effecting reactions were absorbed, so nothing it says contradicts\n a consumer-side ledger; this resolution pins down the boundary the\n sentence left implicit (publish-path dedup vs. consumer-path dedup)\n rather than changing either.\n2. Its decision 3 is untouched: the ledger is the run's own bookkeeping\n about its own actions, suppressing a re-fire and nothing else.\n3. Its decision 4 (no generic `Source` interface; `TaskEnvelope` is the\n typed contract, keyed on issue identity, not delivery source): the\n event half of the playbook key IS that same identity\n (`TaskEnvelope.IdempotencyKey()`), and the per-trigger-type rule\n means any future trigger type brings its own identity rather than a\n new generic one -- the playbook ledger introduces no second identity\n vocabulary and no untyped payload. The only new type in this\n resolution is the ledger's own value object, consumed through a\n narrow interface like `BindingDispatcher` -- the same shape the\n document's \"typed families\" rule (decision 1, plugin engine rule)\n already blesses.\n\n**Scope: this is the `channel`/`forge`/`module` decision, not a\n`workflow`-position change.** Workflow-kind actions keep their existing\nkeying claim unchanged -- the `TaskEnvelope` path that this document\nalready inherits for free (`daemon.go`, `PublishTask` publishes\nwith `task.IdempotencyKey()`), with its cross-poll/webhook property\nuntouched. The ledger gate applies to the side-effecting positions\n(channel, forge, module), which is why the closing statement below\nstill holds: the first slice (Module + loader + workflow-kind dispatch)\nwas buildable without this resolution, and channel/forge/multi-action\nplaybooks were not. A coordinator MAY implement one position-uniform\ngate as a simplification; what this resolution requires is only that\nthe side-effecting positions are gated.\n\n## Resolved questions\n\n1. **Data-flow/condition syntax.** Does this project want a small existing\n Go expression evaluator (there may be one already in the codebase worth\n checking, e.g. anything backing gate conditions), or a bespoke minimal\n grammar?\n\n **Resolved** (`archie-core-t2db.14`). CEL (`cel.dev/cel-go`, pinned) is\n the one mechanism for both an action's `when` condition and its `args`\n values. The trust boundary, evaluation context, load-time validation and\n the five judgment calls are in\n `docs/prds/playbook-expression-syntax.md`.\n\n2. **Playbook directory config field.** Where this lives in\n `internal/config` / `configuration.Document`, and whether it's one\n directory or a list (mirroring `SkillsDir`'s shape) -- follow existing\n config precedent, not invented fresh.\n\n **Resolved** (`archie-core-t2db.11`). The directory\n shape landed as `playbook_dirs` (a LIST of directories of\n `*.yaml`/`*.yml` binding files), loaded at startup as an additional\n input to the two single-file fields, which remain supported unchanged.\n A single `playbook_dir` would contradict\n supporting multiple independently-maintained playbook sources, which\n the Dedup section already assumes ('independently-sourced playbook\n directories collide'), so the field is a list. Cross-source collision\n (same key in two directories, or in a single-file field and a\n directory) is reported like an in-directory collision -- nothing is\n arbitrated by source precedence. This is what finally exercises the\n design doc's drop-and-report collision rule, since a single file\n cannot collide with itself. Repo-scoping (tying directories to\n `Config.Repos` owner/name) is explicitly deferred to a separate,\n later decision; org/tenant keying is out of scope (no auth/identity\n model).\n\n Decisions recorded from the label-vocabulary slice:\n - Arbitrary labels bind to registered workflow names via\n `LabelWorkflows` + `LoadLabelWorkflowsYAML`/`SetLabelWorkflows`\n (`internal/domain/workflow/routing.go`).\n - The closed `Kind`/NATS-subject set is untouched; the label map only\n extends binding authority for labels the kind layer does not own.\n - Collision rule: a label already owned by the\n kind set (bug/feature/bootstrap), an empty label, an empty workflow\n name, or a duplicate binding is a reported load failure -- dropped\n and logged, the error returned to the caller. Nothing is silently\n arbitrated by schema/version. This is the \"schema defines the\n accepted message; anything else is the caller's fault\" rule applied\n to the label layer.\n - Precedence in `Route()`: explicit `t.Workflow` → arbitrary-label\n binding → kind binding → triage → implement → default.\n3. **Trust boundary for Module Yaegi code.** The plugin engine rule's\n invariant 6 draws a line between operator-trusted in-process code and\n repository-supplied code that must run in a container.\n\n **Resolved** in `docs/prds/module-position.md`, \"Trust boundary\": a\n Module is operator-installed, in-process and daemon-privileged, the same\n tier as `PluginDir` and `SecretEngineDir`, never repository-supplied\n task code.\n4. **First implementation slice.** Recommend: Module position + the\n playbook loader + trigger-to-workflow dispatch only (subsuming the existing\n label routing) first, proving the schema-gen -\u003e Yaegi -\u003e playbook path\n end to end on the smallest useful case, before adding Channel/Forge\n action kinds or the linter/LSP.\n\n **Resolved** (`archie-core-t2db.13`, `.14`, `.15`). The Module position\n (registry + log kind, t2db.13), the CEL expression environment\n (t2db.14), and the playbook document + event coordinator with\n single-action workflow-kind dispatch (t2db.15) are shipped.\n\n **Resolved** (`archie-core-t2db.23`): the coordinator selects a real\n task's workflow. The wiring point is the daemon's definition pin\n (`Daemon.resolveWorkflowID`, consumed by `pinWorkflowFromCollection` in\n `internal/daemon`), not `pollNATS`/`publishTask`. Routing belongs to the\n pin because a workflow definition is a\n database row pinned before dispatch, which makes the pin the one place a\n task's workflow is chosen. Precedence there is explicit `Task.Workflow`\n (the waiting_human -\u003e approved requeue) → matching playbook →\n `workflow.ResolveWorkflowID`'s label binding → kind binding → triage →\n implement. A playbook naming an undefined workflow is a reported failure\n that parks the task rather than a silent fall-through to the binding's\n choice.\n\n `Store.Dispatch` returns the selected workflow *name* and the matching\n playbook's id and version, not a compiled `workflow.Workflow`: the\n production caller decides against the active definition collection, and\n the id and version are the first two components of the gap-2 idempotency\n key. The playbook package does not import `internal/domain/workflow`.\n\n A `when` condition at this point reads what the intake knows about the\n originating issue: `kind`, `labels`, `owner`, `repo`, `number`, `title`,\n `body`, `source`, built by `playbookInput` in `internal/daemon`.\n\n The trigger shape reuses the existing workintake kind/label vocabulary.\n The single-action hard boundary is superseded by\n `docs/prds/multi-action-playbooks.md` (two-shape rule); Module, Channel,\n and Forge positions still have no production dispatch path.\n## Standing constraint\n\nThis may be commercialized, and is to be discernible from other open-source\nevent-driven-automation tooling. No design decision follows from that yet;\nit bears on licensing or feature-gating questions about playbook authoring\nand the LSP when they arise.\n\n## Packages this touches (first slice)\n\n- New: a schema-generation package/convention (`go:generate` source +\n emitted contracts) for the Module position.\n- New: playbook loader + event coordinator (name/location TBD -- likely\n `internal/domain/eda` or similar, following the domain-layer rule: no\n infrastructure imports, no untyped hooks).\n- `internal/domain/workflow`: dispatch target for `workflow`-kind actions,\n unchanged in its own contracts.\n- `internal/domain/workintake`: `labelKinds`/routing becomes one playbook\n among others once the loader subsumes it; existing Go fallback stays for\n backward compatibility until playbooks fully replace it (mirrors the\n `dynamic-workflow-triage.md` precedent of a two-line fallback change, not\n a rip-and-replace).\n" + "body": "# EDA playbook engine -- design\n\n**Status:** Draft\n**Date:** 2026-09-03\n**Beads epic:** `archie-core-t2db`\n\n## Problem\n\n\"Which workflow runs for which trigger\" is hardcoded Go: a literal\nlabel vocabulary (`workintake.labelKinds`) and a literal label-\u003eworkflow map\n(`workflow/routing.go`), extended only by adding a Go case or shipping a\nskill whose `metadata.archie.workflow` overrides one *named* built-in\nworkflow. Extending the system to a new trigger, a new action, or a new\nevent source means a feature branch, a code change in a hardcoded\npath, and new Go tests -- for every addition. That is the barrier this\ndocument exists to remove.\n\nThe goal: triggers, the actions they run, and the\nconditions that connect them should be **drop-in and load**, not **drop-in\nand touch application code**. Yaegi-evaluated Go is the unit of imperative\n\"do a thing\" logic; YAML playbooks are pure orchestration data -- no logic,\njust \"on this event, with this data, call these actions, in this order,\nunder these conditions.\" The daemon's event coordinator doesn't know what a\n`bugfix` or `image-gen` action does, it resolves the name against a\nregistry and pipes typed data through.\n\nThis is explicitly **not** scoped to code-generation workflows. A playbook\naction can be any registered capability -- run a codegen workflow, send a\nmessage on a channel, open something on a forge, generate an image -- so\nlong as it's implemented behind one of the typed engine families below.\n\n## Relationship to existing decisions\n\n- `docs/prds/event-sources-and-reactions.md` ruled\n that reactions in the two epics it covers are **producer-only** (no veto,\n no mutation of in-flight work) and explicitly rejected a single generic\n `Source` interface as \"the untyped-hook shape the plugin engine rule\n exists to prevent.\" **This document extends that scope**: playbooks can\n dispatch to multiple typed action kinds, not just \"produce a\n `TaskEnvelope`.\" It does not relitigate producer-only-ness (still no\n veto/mutation of in-flight work here) and it does not introduce one\n generic interface -- see \"Typed positions, not one generic hook\" below,\n which is how it stays compliant with the plugin engine rule instead of\n reopening that document's #4.\n- `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`\n governs every extension point\n introduced here. Every position below is a typed domain contract with an\n owning registry, not a generic callback map. This is a hard constraint,\n confirmed against the existing rule text before writing this doc.\n- Yaegi is already a proven in-process extension mechanism\n (`internal/plugin`, `internal/domain/workflow/wfeval/yaegi.go`,\n `internal/gate/gateeval/yaegi.go`, `internal/skill/plugin.go`) -- this\n design generalizes its existing role, it does not introduce a new\n execution mechanism.\n- `internal/domain/workflow/skillbuild.BuildRegistry` already composes a\n `workflow.Registry` from a skills catalog, plugin-defined overriding\n built-in. The playbook loader described here supersedes label routing\n specifically; it does not replace `skillbuild`'s workflow-composition role,\n it becomes an additional input the daemon composes at startup.\n- Webhook event intake is a separate design. This\n document defines the router each webhook-sourced event should be able to\n reach; it does not redesign webhook receipt itself.\n\n## Shape: four logic positions, each a typed engine family\n\nEvery entrypoint kind (mechanism, action, loop, schedule, route, trigger) is itself a schema emitter: defining a new kind produces the\ngenerated contract downstream tooling consumes. The kinds slot into a fixed\nhierarchy of logic positions:\n\n```\nWorkflow -\u003e Module -\u003e Channel (telegram/whatsapp/email/...)\n -\u003e Forge (GitHub/Gitea/GitLab/...)\n```\n\nEach position is its own typed engine family per the plugin engine rule:\nidentity + capability-specific operations, an owning `Registry`/`Manager`,\nexplicit lifecycle where the implementation owns resources, narrow host\naccess. Concretely:\n\n- **Workflow** -- already exists (`internal/domain/workflow`). A playbook\n action of kind `workflow` invokes a registered `workflow.Registry` entry\n by name, unchanged from the existing execution path.\n- **Module** -- the new general-purpose action position. A `Module` is a\n Yaegi-evaluated implementation of a generated interface (args in, typed\n result out) for one declared action kind (e.g. `image-gen`, `notify`,\n `open-pr-comment`). This is the position that makes actions \"not\n restricted to code-generation.\" Full design (schema-per-kind, the\n registry shape, the trust boundary, the recommended first slice):\n `docs/prds/module-position.md`.\n- **Channel** -- already exists as `channels.Channel` (telegram, email,\n webhook). A playbook action of kind `channel` sends through a named,\n already-registered channel. No new mechanism; this document just makes it\n addressable from a playbook.\n- **Forge** -- forge clients (GitHub, Gitea, GitLab) become an addressable\n action position the same way Channel is, so a playbook can say \"comment\n on this forge issue\" without that being a special case wired only into\n the poller.\n\n**Typed positions, not one generic hook.** There is no single `Action`\ninterface with an `any` payload. Each position keeps its own typed\ncontract; the playbook YAML names a position and an implementation, and the\nevent coordinator resolves that pair against the matching typed registry.\nThis is what keeps the design compliant with the plugin engine rule and\nwith `event-sources-and-reactions.md`'s rejection of a generic `Source`/\nhook interface -- the generality lives in the YAML data model (which\npositions exist, which named implementations are registered), not in a\nruntime `any`-typed dispatch path.\n\n## `go:generate`-driven schemas, from day one\n\nSchemas are not a future nicety bolted onto an ad hoc\nYAML shape. They are the struct+interface contracts for each logic\nposition, and they drive code generation from the start.\n\n- Each logic position (Workflow/Module/Channel/Forge) has a schema source\n (Go-annotated types, following the existing pattern elsewhere in the\n repo) from which `go:generate` emits the interface and struct scaffolding\n an implementation must satisfy.\n- A Yaegi module implements the generated interface for its position. The\n generated contract is what makes an implementation valid, not hand-review.\n- The schema is also what the linter and LSP (below) validate a playbook\n YAML against -- one source of truth for codegen, startup loading, and\n authoring-time tooling, so the three can't drift from each other.\n- Schema versioning is explicit per position, independent of a playbook's\n own workflow version (see collision handling below).\n\nThe generator itself is not designed here. The constraint is\nschema-first, `go:generate`-driven, per logic position.\n\n## Playbook YAML: pure orchestration data\n\nA playbook declares no embedded logic -- only:\n\n- **trigger**: the event predicate (e.g. forge issue assigned + labelled\n `bugfix`, a schedule tick, a webhook payload shape).\n- **actions**: an ordered list, each naming a logic position and a\n registered implementation, with typed argument data and optional\n conditions.\n- **data flow between actions**: results/facts from one action available to\n later actions in the same playbook run -- exact interpolation syntax is\n an open point, not decided here (see Open questions).\n\nPlaybooks live in a configured directory (repo/directory-scoped, per Sam's\n\"define repos, directories, playbooks\" framing) and are loaded at archied\nstartup, alongside the existing skills-catalog composition.\n\n## Dedup: detect and log, no arbitration mechanism\n\nNo runtime auto-resolution rule. An automatic \"pick a winner\" algorithm\n(e.g. by version) is itself a mechanism that can fail and need debugging\nwhen a collision happens -- the wrong kind of complexity to introduce for\na case that should just be visible and fixed by a human. Instead:\n\n- **At daemon startup:** if independently-sourced playbook directories\n declare a collision on the same trigger, that is a definition failure.\n The colliding definitions are dropped (not loaded) and the failure is\n logged plainly (which sources, which trigger) and reported back to the\n caller that requested the load -- not swallowed as a background log line\n only. The schema is the definition; a schema conflict is a reported\n failure, not something the daemon silently arbitrates.\n- **Linter**: a CI/dev-time tool, reading the same generated schemas, that\n flags duplicate or conflicting trigger definitions *within* a single\n maintained tree before merge.\n\n **Resolved** (`archie-core-t2db.12`). A standalone\n gopls-shaped binary (`cmd/archie-playbooks`, lint subcommand) validates\n playbook directories against the exact loaders the daemon uses\n (`LoadPlaybookDirs`/`LoadKindWorkflowsYAML`/`LoadLabelWorkflowsYAML`),\n exiting non-zero on any collision / malformed file / invalid binding.\n A finding about one binding key leads with the key's `file:line`, read\n from the `yaml.Node` the loader decodes; the linter agrees with runtime\n validation by construction, which is the load-bearing property. `-eda-dir`\n lints an `eda_playbook_dir` the same way, through `playbook.Load` with its\n CEL, action-id and args checks.\n Discoverable via `task lint:playbooks` or direct `go run\n ./cmd/archie-playbooks lint -dir ...`. The LSP/serve mode is a later\n entrypoint of the SAME binary, per the shared-package decision above.\n- **LSP**: same schema source again, feeding author-time hover/completion/\n inline errors while someone edits a playbook YAML in an editor. Kept\n explicitly in scope per Sam (not deferred), because it's the same schema\n artifact as the linter's, just a different consumer.\n\n `archie-playbooks serve` is the language server, over stdio. When a file is\n opened or saved it lints the file's saved directory with the loader the\n daemon runs for it (a file with a top-level `trigger` key is an EDA\n playbook, anything else a routing binding file) and publishes the findings\n for that file as error diagnostics, each on the line of the key, action,\n `when` or args key it names; a file-level finding sits on the first line.\n Unsaved edits are not validated. Hover and completion are later additions.\n\nThe startup log-and-refuse path exists for what the linter/LSP structurally\ncannot see -- sources composed together only at daemon startup, never\nchecked against each other by either tool. If the linter and LSP do the job\nthey're built for, a real collision reaching that startup path should be\nrare in practice, not a routine occurrence the design leans on.\n\n**Shared package, thin consumers -- not a bundled-vs-standalone choice.**\nThe validation logic (`LoadKindWorkflowsYAML`, `LoadLabelWorkflowsYAML`, the\ndirectory-merge from t2db.11) lives in `internal/domain/workflow`, a plain\nGo package with no knowledge of which binary calls it. This makes \"should\nthe linter/LSP be bundled into archied or a separate tool\" a non-question:\n- `archied` already imports the package directly and validates in-process\n at startup -- no subprocess, no external tool call.\n- An agent that needs to validate a playbook in-process can import the same\n package directly, for the same reason.\n- The standalone `cmd/` binary (t2db.12, gopls-shaped: one binary, a lint\n mode now, an LSP/serve mode later) exists only because CI and editors are\n out-of-process consumers by nature -- a CI step needs an exit code, an\n editor speaks LSP over a process boundary, neither can `import` a Go\n package. It is a thin wrapper per `organisation.md`'s `cmd/` rule, not a\n second implementation.\n\nFolding CLI/LSP protocol handling into `archied` itself would grow the\ndaemon into unrelated concerns, against the plugin-engine rule's spirit of\nnarrow capability families.\n\n## Execution-time gaps (both resolved)\n\nEverything above covers *loading* a playbook. Nothing above covers what\nhappens while one *runs*. Two gaps, both load-bearing enough to resolve\nbefore implementation, not defer:\n\n### 1. Mid-playbook action failure\n\n**Resolved** (`archie-core-t2db.18`). The default below\nis a committed decision, not a candidate list; changing it later would\nrequire its own decision. Gap 2 below is resolved by `archie-core-t2db.17`.\n\nA playbook is an ordered action list with data flowing between steps. If\naction 2 of 4 fails at runtime (an image-gen API times out, a forge call\n403s), the run needs a defined outcome. This\ncodebase already answers a structurally identical question for its\nexisting workflow engine, precisely enough to reuse rather than\nre-derive: `workflow.Run` (`internal/domain/workflow/workflow.go`)\ndraws a three-way distinction on a stage failure, and a playbook run\ndraws the same one on an action failure.\n\n**Decision: reuse `Run`'s three-way distinction directly.** The stated\ndefault is **stop-on-first-failure**: a real action error halts the\nplaybook run immediately and is reported, with no continue-to-next-action\nand no automatic retry or compensating follow-up. The three points below\nare the complete decision.\n\n1. **A real action error** (the action's own logic failed -- an API\n error, a validation failure inside the action) stops the run\n immediately. No later actions execute. The failure is reported the\n same way a load collision is reported -- dropped, logged plainly\n (which action and why), and returned to the caller, never swallowed\n as a background log line only (the Dedup section's drop-and-report\n rule). `Run` is the mechanical\n precedent for the stop itself: a stage error sets the park reason and\n returns without running further stages (`workflow.go`). This\n is stop-on-first-failure, matching the document's existing bias\n against clever automatic recovery, and it is now a stated decision\n rather than a nobody-chose default.\n2. **Interruption** (the daemon is shutting down mid-dispatch, `ctx.Err()\n != nil`) is explicitly **not** a failure. `Run` already treats this\n case specially -- \"Daemon shutdown is not a workflow failure. Leave\n the task running ...; parking here would publish a false failure and\n require manual intervention\" (`workflow.go`) -- and the same\n reasoning applies to a playbook run: an in-flight dispatch interrupted\n by restart must not be recorded as a broken playbook. What \"leave it\n alone for restart\" means for a playbook run (there is no `store.Task`\n row a playbook run inherently owns the way a workflow stage does) is\n an open implementation detail for whoever builds the coordinator, not\n decided here -- but the *semantic* (interruption ≠ failure) is decided.\n3. **A run that produces no outcome at all** (every action ran without\n error, but nothing was assigned to happen) is itself an error\n condition, matching `Run`'s own \"a workflow must end with an explicit\n outcome; not doing so is a definition bug, which still must not vanish\n silently\" (`workflow.go`). A playbook with actions that all ran\n but never reached a coherent terminal state is a definition bug in the\n playbook, reported as such.\n\n**Rollback:** explicitly **not attempted**, for exactly the reason the\ngap's own description named -- a posted forge comment is not revocable.\nThis is not a limitation to work around later; it is the correct\nsemantic. An operator who needs a corrective action after a failure\nwrites a *new* playbook/action for that, they do not get automatic\nundo.\n\n**This stays inside the producer-only rule.** Stop-on-first-failure is the\nrun deciding its own terminal state from its own action's error. Nothing\nalready in flight is blocked or altered; the run only declines to start\nactions that had not started yet, and it records the failure on its own\nunit the way `Run` sets a park reason and transitions the task to\n`StatusParked`. A future compensating action (\"if the notify action\nfailed, also log an incident\") would be producing new work, which the rule\nalready permits. No syntax for it is designed here.\n\n**J3 relationship, stated explicitly:** J3 (a CEL `when` condition\nerroring at eval time → treated as false → skip that action → run\ncontinues) is a **different case from an action failure** and is not\nrevisited by this resolution. A condition error means \"we couldn't\ndetermine whether to run this action,\" which this document already\nresolved as \"then don't, and move on.\" An action failure means \"we tried\nto run this action and it broke,\" which stops the run per point 1 above.\nThe two must not be conflated: a coordinator implementation should be\nable to point at one `when`-evaluation code path and one\naction-invocation code path and show they use different outcomes.\n\n### 2. Idempotency at execution time\n\n**Resolved** (`archie-core-t2db.17`, a\ndesign-investigation ticket: resolve, do not implement). The decision\nbelow is the answer; the keying scheme itself is separate follow-up work\nand is intentionally not built here. It **extends**\n`event-sources-and-reactions.md`'s existing contract -- it does not\ncontradict it (relationship argued at the end).\n\n**Problem (unchanged):** `event-sources-and-reactions.md` decided\nreactions ride `internal/eventbus`'s at-least-once delivery specifically\nso `PublishUnique`/idempotency keys absorb redelivery without duplicate\nside effects. This document inherits that for free only for\n`workflow`-kind actions, because `TaskEnvelope` already carries an\nidempotency key. It said nothing for `channel`, `forge`, or `module`\nactions with real side effects -- a posted comment, a sent message, a\nbilled image generation.\n\nOne correction to the problem statement, checked against the code rather\nthan assumed, because it changes what the answer must be:\n**`PublishUnique`'s dedup is not a consumer-redelivery guard at all.**\n`PublishUnique` only sets the JetStream `Nats-Msg-Id` header on the\noutgoing message (`internal/infrastructure/eventbus/nats/publisher.go`;\nkey constant `message.go`); JetStream suppresses *republished*\nmessages carrying a repeated key inside `Config.DedupWindow`\n(`client.go`, `Duplicates: cfg.DedupWindow`), default 2 minutes\n(`config.go`, `DefaultDedupWindow = 2 * time.Minute`). A consumer\nredelivery is the same *stored* message re-delivered on Nak or\nacknowledge-timeout (`internal/eventbus/eventbus.go`: \"a handler\nreturning an error causes redelivery\") -- not a republish; its\n`Nats-Msg-Id` is never re-firewalled, and even if it were, two minutes is\nnot an at-most-once guarantee for a side effect that must never repeat.\n**Conclusion: side-effecting action kinds need a consumer-side, durable\ndedup record; the bus cannot supply it.** That is precisely the situation\n`binding_dispatches` was built for -- so the decision below reuses its\nmechanism rather than designing a new one.\n\n#### Decision\n\n**Granularity: per-action-per-event -- one dedup record per\n(action, event) pair, not per playbook run.** Whole-run keying, the\nobvious alternative, has two crash windows: the run row is written when the run starts, so a crash mid-run\nleaves the run \"started\" and a redelivery skips *every remaining\naction* (work silently lost); a crash before the row write re-runs\n*every already-fired action* (duplicate side effects -- the exact harm\nthis gap exists to prevent). Per-action keys collapse both into one\nwindow and one behavior: an action's record is written immediately\nbefore that action's side effect is invoked, so an action fires iff its\nown record is absent, no fired action ever re-fires, and a redelivered\nevent resumes at the first unrecorded action. For the shipped\nsingle-action playbooks the two granularities are equivalent in effect;\nthe difference starts with multi-action runs -- where whole-run keying\nwould already be wrong.\n\n\u003e Storage superseded: every store now lives in PostgreSQL behind\n\u003e `internal/domain/storecontract`, implemented in `internal/infrastructure/postgres`\n\u003e (`docs/prds/state-store-contract.md`). SQLite names below describe the\n\u003e original design.\n\n**Storage/lookup: a new durable ledger table `playbook_dispatches` in\nthe event-capture store, copying `binding_dispatches`'s conventions exactly**\n(durable table, `INSERT OR IGNORE`, sentinel error, rows freed with\ntheir parent, survives daemon restarts -- `RecordDispatch`):\n\n```sql\nCREATE TABLE playbook_dispatches (\n playbook_id TEXT NOT NULL,\n playbook_version TEXT NOT NULL,\n event_id TEXT NOT NULL,\n action_id TEXT NOT NULL,\n dispatched_at TEXT NOT NULL,\n PRIMARY KEY (playbook_id, playbook_version, event_id, action_id)\n);\n```\n\nWritten with the same `INSERT OR IGNORE` + sentinel-error convention\n(`ErrAlreadyDispatched`, `bindings.go`), so a duplicate is a no-op\nwrite rather than a constraint error, and the caller matches it with\n`errors.Is` the way the binding dispatch loop already does\n(`internal/daemon/daemon.go` -- \"another cycle already won this\nrace,\" not an error to surface). The record is consumed by the playbook\ncoordinator at dispatch time through a domain-side interface implemented\nby the event-capture store -- the same shape as `BindingDispatcher`\n(`internal/domain/storecontract`) -- and the table lands in the\nstore's schema migrations. No change\nto `internal/eventbus`; no per-message dedup state on the client.\n\n**Lifetime: no time-based expiry, and no automatic reclamation.** Rows are\nretained until an explicit `DeletePlaybookDispatches` for their playbook.\nRemoving a playbook file does not delete its rows: playbooks are read only\nat boot, so the only place to notice a removal is a boot-time reconcile,\nand a boot that finds the directory missing or unmounted loads as \"no\nplaybooks\" and would reclaim the whole ledger, letting redelivered events\nfire their side effects again. A binding's rows go with an explicit\noperator delete (`bindings.go`, same transaction); a file disappearing is\nnot an equally deliberate act. The at-most-once guarantee must not\nsilently decay, which is exactly the property that disqualifies\n`DedupWindow` above; table growth is bounded by distinct (playbook,\nevent, action) pairs and is accepted, the same tradeoff\n`binding_dispatches` already makes.\n\n**Redelivery behavior: skip the recorded action and continue the run.**\nA detected duplicate is not re-invoked, is not reported to the caller as\nan error, and is logged at debug level rather than as a warning -- this\nis the expected, correct behavior of at-least-once delivery, not an\nanomaly (same treatment as `ErrAlreadyDispatched` at\n`daemon.go`).\nThe run continues with the next action (or ends, for a single-action\nplaybook whose one action is recorded), which is what makes a redelivery\na resume rather than a dead restart.\n\n**Key derivation: a fixed composition of four structural identities,\ncomputed by the coordinator -- not a CEL expression.** The key is the\n`(playbook_id, playbook_version, event_id, action_id)` tuple above, where:\n\n- `playbook_id` is `Playbook.ID` -- the playbook file's path relative to\n its configured directory root, slash-normalized, unique within the load\n composition by construction (`internal/domain/eda/playbook`).\n- `playbook_version` is `Playbook.Version` -- a SHA-256 of the loaded\n file, recomputed on every load (`internal/domain/eda/playbook`),\n mirroring `Binding.Version`'s provenance-pinning purpose: the dispatch\n is pinned to the exact definition that was active when it fired. A\n changed playbook definition is a different key and may fire again for\n the same event -- deliberate, not a bug.\n- `event_id` is `DispatchInput.TaskID` (`playbook.go`), which\n carries the `TaskEnvelope.IdempotencyKey()` value\n (`\"archie:\" + owner/repo/number`,\n `internal/domain/workintake/envelope.go`). It is chosen over\n `store.Task.ID` because the trigger vocabulary is issue-level\n workintake label/kind, dispatched at discovery time (pollNATS, forge\n webhook receiver), where no task row exists yet (`playbook.go`\n comment; `playbook_test.go`: \"the value available at the\n discovery/dispatch point... NOT a store.Task.ID int64\"). Keying on the\n issue identity rather than the delivery source is the load-bearing\n property the existing contract already established for `TaskEnvelope`\n (`event-sources-and-reactions.md` question 4: a webhook-sourced\n envelope for the same issue produces the *same* idempotency key as a\n poll-discovered one; `internal/forge/webhook/receiver.go` --\n \"Idempotency is not this package's job\"); this resolution inherits that\n property rather than re-deciding it. Consequence, stated explicitly:\n same-issue re-discoveries (a re-label that re-triggers the same kind)\n are the *same event* by design -- the workintake trigger vocabulary is\n issue-granular, exactly as `TaskEnvelope`'s own key is. A future\n capture/binding-originated trigger type keys on `captured_events.id`\n instead; derivation is per-trigger-type, not one formula for all\n triggers (rule carried over unchanged from the draft).\n- `action_id` is the action's declared `id` -- J1's named ids, \"a\n required field on every action that later actions reference\", unique\n and stable-identifier-shaped, validated at load (the CEL resolution's\n J1 and its context table above in this document). For an action declaring no `id`\n (permitted by J1 while unreferenced), the key uses the action's 1-based\n position in the playbook: deterministic and stable for the\n single-action playbooks, and a later reorder is a file edit whose\n content hash changes `playbook_version` with it, so a positional\n fallback cannot silently collide with a prior definition.\n\n**No CEL in the key -- stated explicitly because the CEL resolution\nflagged this as gap 2's \"first real exercise\"** (\"CEL's read-only result\naccess makes gap 2's keying derivation readable\" -- the CEL resolution's\nclosing note). Readability\nis not the binding constraint; **determinism under redelivery is**, and\nCEL key expressions lose three ways. First, they are not load-checkable:\n`event` stays `dyn` by the resolved J4 (schema-by-example), so\na key expression over event fields cannot be type-checked at load,\nviolating the document's reject-at-load philosophy. Second, they can\nfail at dispatch (a missing field is a CEL error), and a key that cannot\nbe computed is an unfireable state -- neither \"skip\" nor \"fire\" is safe\nwithout losing or duplicating work. Third, the contract needs one\nderivation, and two authors writing different key expressions would\nfragment the ledger. The key is therefore structural by construction:\nevery component above is an immutable identity of the run's inputs, so\ntwo deliveries of the same event derive the same key with no evaluation.\nThe exercise's actual outcome is the derivation rule above; CEL remains\na *condition* surface (`when`), never a key surface. An action kind that\ngenuinely needs finer granularity than (action, event), such as \"per\ncomment, not per issue\", arrives with its own trigger type and its own\nevent identity, per the per-trigger-type rule.\n\n**Record-before-invoke -- one deliberate divergence from\n`binding_dispatches`, justified by the harm profile.** The binding\ndispatch loop enqueues the task first and records the ledger row after\n(`daemon.go`), accepting that racing cycles may both enqueue\n(\"the duplicate task remains queued... delete-on-races is its own can of\nworms\"); the selection query excludes already-dispatched captures\n(`bindings.go`), but the race window remains. That ordering is\ncorrect there because the duplicate artifact is an internal task row --\nrecoverable, low-harm. The playbook ledger's ordering is reversed on\npurpose: **the row is written and committed before the action's side\neffect is invoked** -- the `INSERT OR IGNORE` is the atomic gate, and\nthe lost-write loser skips without invoking. The cost is stated, not\nhidden: a crash between the row commit and the invoke loses that one\naction's side effect, repairable by hand -- the reverse direction of the\nsame window that would otherwise duplicate a posted comment or\nre-bill an image generation. For side effects whose duplication is\nexternally visible and not revocable, at-most-once is the required\ndirection; the binding system's at-least-once-tolerant ordering is not\nthe precedent for this ledger.\n\n**Gap-1 interplay, stated to keep the two mechanisms separate:** the\nledger answers one question per action -- has this action already fired\nfor this event? It does not answer whether the run continues, stops, or\nis re-attempted; that is gap 1's coordinator concern (a run-outcome\nrecord; gap 1 explicitly leaves \"what leave it alone for restart means\nfor a playbook run\" to whoever builds the coordinator). One consequence\nof record-before: an action that FAILED (gap 1's real-action-error case)\nhas a ledger row, so a later redelivery of the same event skips it --\nconsistent with gap 1's \"no automatic retry\" resolve (a corrective\naction is a *new* playbook/action, per gap 1's rollback paragraph). A\nfailed action is never re-attempted by the bus; if a run must be\nrecovered, an operator edits the playbook -- new version, new key --\nrather than fighting ledger state.\n\n**Relationship to `event-sources-and-reactions.md` -- extension, not\ncontradiction.** Keyed to that document's sections:\n\n1. Its decision 2 commits reactions to at-least-once delivery via\n `PublishUnique`'s \"without duplicate enqueue\" guarantee -- which, with\n the code facts above, is accurate for the *publish* path only:\n `PublishUnique` absorbs duplicate publishes of the same event (poll\n vs. webhook), which is what that decision was actually about. This\n document's own problem statement, taken literally, overstates it\n (\"keys absorb redelivery without duplicate side effects\") -- that\n overstatement is exactly what this gap exists to correct. The\n existing contract never claimed consumer redeliveries of\n side-effecting reactions were absorbed, so nothing it says contradicts\n a consumer-side ledger; this resolution pins down the boundary the\n sentence left implicit (publish-path dedup vs. consumer-path dedup)\n rather than changing either.\n2. Its decision 3 is untouched: the ledger is the run's own bookkeeping\n about its own actions, suppressing a re-fire and nothing else.\n3. Its decision 4 (no generic `Source` interface; `TaskEnvelope` is the\n typed contract, keyed on issue identity, not delivery source): the\n event half of the playbook key IS that same identity\n (`TaskEnvelope.IdempotencyKey()`), and the per-trigger-type rule\n means any future trigger type brings its own identity rather than a\n new generic one -- the playbook ledger introduces no second identity\n vocabulary and no untyped payload. The only new type in this\n resolution is the ledger's own value object, consumed through a\n narrow interface like `BindingDispatcher` -- the same shape the\n document's \"typed families\" rule (decision 1, plugin engine rule)\n already blesses.\n\n**Scope: this is the `channel`/`forge`/`module` decision, not a\n`workflow`-position change.** Workflow-kind actions keep their existing\nkeying claim unchanged -- the `TaskEnvelope` path that this document\nalready inherits for free (`daemon.go`, `PublishTask` publishes\nwith `task.IdempotencyKey()`), with its cross-poll/webhook property\nuntouched. The ledger gate applies to the side-effecting positions\n(channel, forge, module), which is why the closing statement below\nstill holds: the first slice (Module + loader + workflow-kind dispatch)\nwas buildable without this resolution, and channel/forge/multi-action\nplaybooks were not. A coordinator MAY implement one position-uniform\ngate as a simplification; what this resolution requires is only that\nthe side-effecting positions are gated.\n\n## Resolved questions\n\n1. **Data-flow/condition syntax.** Does this project want a small existing\n Go expression evaluator (there may be one already in the codebase worth\n checking, e.g. anything backing gate conditions), or a bespoke minimal\n grammar?\n\n **Resolved** (`archie-core-t2db.14`). CEL (`cel.dev/cel-go`, pinned) is\n the one mechanism for both an action's `when` condition and its `args`\n values. The trust boundary, evaluation context, load-time validation and\n the five judgment calls are in\n `docs/prds/playbook-expression-syntax.md`.\n\n2. **Playbook directory config field.** Where this lives in\n `internal/config` / `configuration.Document`, and whether it's one\n directory or a list (mirroring `SkillsDir`'s shape) -- follow existing\n config precedent, not invented fresh.\n\n **Resolved** (`archie-core-t2db.11`). The directory\n shape landed as `playbook_dirs` (a LIST of directories of\n `*.yaml`/`*.yml` binding files), loaded at startup as an additional\n input to the two single-file fields, which remain supported unchanged.\n A single `playbook_dir` would contradict\n supporting multiple independently-maintained playbook sources, which\n the Dedup section already assumes ('independently-sourced playbook\n directories collide'), so the field is a list. Cross-source collision\n (same key in two directories, or in a single-file field and a\n directory) is reported like an in-directory collision -- nothing is\n arbitrated by source precedence. This is what finally exercises the\n design doc's drop-and-report collision rule, since a single file\n cannot collide with itself. Repo-scoping (tying directories to\n `Config.Repos` owner/name) is explicitly deferred to a separate,\n later decision; org/tenant keying is out of scope (no auth/identity\n model).\n\n Decisions recorded from the label-vocabulary slice:\n - Arbitrary labels bind to registered workflow names via\n `LabelWorkflows` + `LoadLabelWorkflowsYAML`/`SetLabelWorkflows`\n (`internal/domain/workflow/routing.go`).\n - The closed `Kind`/NATS-subject set is untouched; the label map only\n extends binding authority for labels the kind layer does not own.\n - Collision rule: a label already owned by the\n kind set (bug/feature/bootstrap), an empty label, an empty workflow\n name, or a duplicate binding is a reported load failure -- dropped\n and logged, the error returned to the caller. Nothing is silently\n arbitrated by schema/version. This is the \"schema defines the\n accepted message; anything else is the caller's fault\" rule applied\n to the label layer.\n - Precedence in `Route()`: explicit `t.Workflow` → arbitrary-label\n binding → kind binding → triage → implement → default.\n3. **Trust boundary for Module Yaegi code.** The plugin engine rule's\n invariant 6 draws a line between operator-trusted in-process code and\n repository-supplied code that must run in a container.\n\n **Resolved** in `docs/prds/module-position.md`, \"Trust boundary\": a\n Module is operator-installed, in-process and daemon-privileged, the same\n tier as `PluginDir` and `SecretEngineDir`, never repository-supplied\n task code.\n4. **First implementation slice.** Recommend: Module position + the\n playbook loader + trigger-to-workflow dispatch only (subsuming the existing\n label routing) first, proving the schema-gen -\u003e Yaegi -\u003e playbook path\n end to end on the smallest useful case, before adding Channel/Forge\n action kinds or the linter/LSP.\n\n **Resolved** (`archie-core-t2db.13`, `.14`, `.15`). The Module position\n (registry + log kind, t2db.13), the CEL expression environment\n (t2db.14), and the playbook document + event coordinator with\n single-action workflow-kind dispatch (t2db.15) are shipped.\n\n **Resolved** (`archie-core-t2db.23`): the coordinator selects a real\n task's workflow. The wiring point is the daemon's definition pin\n (`Daemon.resolveWorkflowID`, consumed by `pinWorkflowFromCollection` in\n `internal/daemon`), not `pollNATS`/`publishTask`. Routing belongs to the\n pin because a workflow definition is a\n database row pinned before dispatch, which makes the pin the one place a\n task's workflow is chosen. Precedence there is explicit `Task.Workflow`\n (the waiting_human -\u003e approved requeue) → matching playbook →\n `workflow.ResolveWorkflowID`'s label binding → kind binding → triage →\n implement. A playbook naming an undefined workflow is a reported failure\n that parks the task rather than a silent fall-through to the binding's\n choice.\n\n `Store.Dispatch` returns the selected workflow *name* and the matching\n playbook's id and version, not a compiled `workflow.Workflow`: the\n production caller decides against the active definition collection, and\n the id and version are the first two components of the gap-2 idempotency\n key. The playbook package does not import `internal/domain/workflow`.\n\n A `when` condition at this point reads what the intake knows about the\n originating issue: `kind`, `labels`, `owner`, `repo`, `number`, `title`,\n `body`, `source`, built by `playbookInput` in `internal/daemon`.\n\n The trigger shape reuses the existing workintake kind/label vocabulary.\n The single-action hard boundary is superseded by\n `docs/prds/multi-action-playbooks.md` (two-shape rule); Module, Channel,\n and Forge positions still have no production dispatch path.\n## Standing constraint\n\nThis may be commercialized, and is to be discernible from other open-source\nevent-driven-automation tooling. No design decision follows from that yet;\nit bears on licensing or feature-gating questions about playbook authoring\nand the LSP when they arise.\n\n## Packages this touches (first slice)\n\n- New: a schema-generation package/convention (`go:generate` source +\n emitted contracts) for the Module position.\n- New: playbook loader + event coordinator (name/location TBD -- likely\n `internal/domain/eda` or similar, following the domain-layer rule: no\n infrastructure imports, no untyped hooks).\n- `internal/domain/workflow`: dispatch target for `workflow`-kind actions,\n unchanged in its own contracts.\n- `internal/domain/workintake`: `labelKinds`/routing becomes one playbook\n among others once the loader subsumes it; existing Go fallback stays for\n backward compatibility until playbooks fully replace it (mirrors the\n `dynamic-workflow-triage.md` precedent of a two-line fallback change, not\n a rip-and-replace).\n" }, { "url": "/dev/prds/embedded-nats/", @@ -292,13 +292,13 @@ "url": "/dev/prds/memory-engine-unification/", "title": "Memory engine unification: four scopes, CRUD, and one write path -- decision", "section": "PRDs", - "body": "# Memory engine unification: four scopes, CRUD, and one write path -- decision\n\n**Status:** Approved\n**Date:** 2026-09-16\n**Findings:** `memory-4` and its dependants in the adversarial sweep\n(`.local/issue-tracker`); the real defect is the split described below, for\nwhich `memory-4` is a symptom\n**Supersedes:** the draft `memory-turn-context.md` (its synchronous-read\nargument survives and is reused; its `Manager` method and consumer-owned port do\nnot)\n**Settles:** four open items in `docs/architecture/migration-decisions.md#5`\n(listed at the end)\n\n## Problem\n\nThere are **two live memory stores for one assistant**, split by which component\nwrites them, and the chat turn reads neither.\n\n| Family | Written by | Root | Format |\n|---|---|---|---|\n| `internal/memory` (`Manager`, `builtin.Provider`) | the chat agent's `memory_edit` tool via `memorytoolprovider` (`bootstrap.go`) | `\u003cworkDir\u003e/memory` | `MEMORY.md` / `USER.md` |\n| `internal/domain/memory` + `internal/infrastructure/memory` | the session curator (`sessioncurator.go`) | `\u003cworkDir\u003e/memory-engine` | identity-keyed blocks |\n\nThey share no code, no format and no scope vocabulary. Neither reaches a prompt:\n`Manager.SystemPromptBlock` (`internal/memory/manager.go`) has no production\ncaller anywhere, so the agent can write memory through a tool and never read it\nback.\n\nThree further defects fall out of the same split:\n\n1. **The engine's contract is not CRUD.** `Store` is `Write`/`Query`/`List`/\n `Forget` — create, read, delete, and **no Update**. The retired file provider\n *does* have `handleAdd`/`handleReplace`/`handleRemove`, so the family being\n deleted is operationally richer than its replacement.\n2. **There is no scope model.** The contract carries one opaque `Identity\n string`, and the curator fills it with a **session id** (`sessioncurator.go`)\n — which is none of the four scopes `docs/architecture/agent-system.md`\n requires, and stops meaning anything when the session ends.\n3. **The chat turn has no user identity on half the channels.** Telegram and\n email populate `SenderID` with a person; the dashboard populates it with\n nothing, and a webhook populates it with nothing either — a route path names\n a source, not a person, so `webhook.go` leaves `SenderID` empty and carries\n the route in `Inbound.BudgetKey` for rate limiting. `sender_id` is persisted\n (`session_store_sqlite.go`), so whatever a channel puts there reaches the\n consumers that read it.\n\n`agent-system.md` says the write-scope selection and cross-scope sharing\nrules \"require a focused memory design decision\". This is that decision.\n\n## Decision\n\n### 1. One engine, addressed by four typed scopes\n\n`internal/domain/memory` is the only memory engine. `Observation.Identity`,\n`Query.Identity`, `Record.Identity` and `List(identity)` are deleted, not\nextended: a field whose meaning depends on the caller cannot carry a scope.\n\n```go\ntype ScopeKind string\n\nconst (\n ScopeGlobal ScopeKind = \"global\" // shared across the application\n ScopeAgent ScopeKind = \"agent\" // private to one Agent\n ScopeUser ScopeKind = \"user\" // one user, across their Agents\n ScopeAgentUser ScopeKind = \"agent-user\" // one Agent's relationship with one user\n)\n\ntype Scope struct {\n Kind ScopeKind\n Agent AgentID // required for ScopeAgent, ScopeAgentUser\n User IdentityID // required for ScopeUser, ScopeAgentUser\n}\n\nfunc (s Scope) Validate() error // rejects a component present where it is not required\nfunc (s Scope) Key() string // canonical, collision-free storage key\n```\n\n`AgentID` and `IdentityID` are opaque. This package never resolves or\ncanonicalises them.\n\nA turn's resolved identity is one value:\n\n```go\ntype Subject struct {\n AgentID AgentID\n UserID IdentityID // \"\" when the channel carries no per-person identity\n}\n\nfunc (s Subject) Scopes() []Scope // readable, most specific first\nfunc (s Subject) WritableScopes() []Scope // never includes ScopeGlobal\n```\n\n**Access control is naming a scope, and nothing else.** The read path names\nexactly the scopes of the resolved `Subject`; the engine never unions beyond what\nit is handed and applies no policy of its own. An engine that enforced policy\nwould need to know about channels, sessions and bindings, and every backend would\nreimplement it. \"Agent-wide is private to its owning Agent by default\"\n(`agent-system.md`) falls out mechanically, because `ScopeAgent{a}` and\n`ScopeAgent{b}` are different storage keys.\n\n`ScopeGlobal` is never model-writable. Writing it is an operator action; nothing\nproduces one yet, but the contract models it because the read set includes it.\n\n### 2. CRUD, with revisions retained\n\n```go\ntype Store interface {\n Create(ctx context.Context, in NewRecord) (Record, error)\n Get(ctx context.Context, scope Scope, id RecordID) (Record, error) // ErrNotFound\n Query(ctx context.Context, q Query) ([]Record, error) // heads only\n List(ctx context.Context, scope Scope) ([]Record, error) // heads only\n Update(ctx context.Context, in RecordUpdate) (Record, error) // ErrNotFound, ErrStaleRevision\n Forget(ctx context.Context, scope Scope, id RecordID) error // idempotent\n Revisions(ctx context.Context, scope Scope, id RecordID) ([]Revision, error)\n}\n```\n\n`Get` and `Forget` take a scope. The current `Forget` scans every identity's\nstore to find a marker (`builtin_engine.go`) purely because the contract\ngave it nothing better.\n\n`Record` carries what `agent-system.md` requires be retained: `Scope`,\n`Kind`, `Content`, `Revision`, `Author`, `OriginUser`, `Source`, `CreatedAt`,\n`UpdatedAt`. `Metadata` is dropped — nothing sets it and the parser never\nrestores it, so it is a field that silently does not round-trip.\n\n`Update` supersedes rather than overwrites. The superseded state is appended to\nthe scope's `HISTORY.md` **before** the live block is replaced, so a crash\nbetween the two leaves an extra history entry and an unchanged record —\nrecoverable — never a record whose previous state was lost. `Update` carries no\n`Scope`: a record may never move between scopes, and the API makes that\nunrepresentable rather than validating it. `Expected` optionally names the\nrevision being replaced and returns `ErrStaleRevision` on mismatch, which matters\nbecause two processes (`archied` and `archie-gateway`) can hold the same scope's\nfile.\n\n`Forget` records a deleted revision before removing the live block, so a record's\nprovenance outlives its content.\n\n### 3. The caller resolves identity; the engine never does\n\nResolution happens in the gateway turn path, where the native sender id and the\nsession are both in hand, and it is supplied **per channel by the composition**:\n\n```go\n// TurnRunnerConfig\n// UserIdentity resolves the initiating user's identity for one inbound message.\n// false means the channel carries no per-person identity, and the turn gets\n// global and agent scopes only. Nil means the same.\nUserIdentity func(msg messaging.Message) (IdentityID, bool)\n```\n\nThis must be injectable rather than a blanket `channel + \":\" + SenderID`\nconcatenation, because a channel's sender id is not necessarily a person: a\nwebhook's route path names a source, and treating it as an identity would give\na URL one -- which is why `webhook.go` leaves `SenderID` empty and carries the\nroute in `Inbound.BudgetKey` instead. Telegram and email supply their sender\nid; the dashboard and webhook resolve nothing.\n\n**Fail closed.** When `UserID` is empty the turn proceeds with global and agent\nscopes only, and a write targeting `user` or `agent-user` fails with a clear\nerror. `agent-system.md` forbids showing one user's memory to another, so\n\"we do not know who this is\" must mean \"show none of it\", never \"fall back to a\nwider scope\".\n\n### 4. The chat read path\n\nSynchronous and total. It runs inside `prepareTurn` (`turn.go`) before the\nprompt is built, never returns an error to the caller, and degrades to an empty\nblock on any engine failure or provider panic. A fire-and-forget hook would race\nthe prompt build in the same turn, which is why this is not a lifecycle hook.\n\nThe read is a scope-only `Query` over the subject's scopes — **not** ranked\nsearch, which remains open in `migration-decisions.md#5`. A ranked read on the\nhot path with no ranking implementation would be a lie.\n\n`SystemPromptConfig` gains a `Memory` field, rendered into\n`templates/archie.md.tpl` between the `\u003ctools\u003e` and `\u003cenv\u003e` blocks:\n\n```\n\u003cmemory purpose=\"durable_context\" trust=\"data\"\u003e\n```\n\n`trust=\"data\"` and inclusion in the precedence clause follow the `\u003ctools\u003e`/`\u003cenv\u003e`\nprecedent exactly: memory content is model-written from untrusted input and must\nbe framed as data, never instructions. The rendered block carries each record's\nshort id, because the write path addresses records by id — one source of truth\nfor both directions.\n\nBoth a per-scope record limit and a byte cap on the rendered block are named\nconstants. The cap is about size, not latency; a local read needs no timeout.\n\n**Prerequisite:** `setupGateways` runs before `setupMemoryAll`\n(`main.go` vs `:428`), and `startGatewayRuntime` before `setupMemory`\n(`gateway.go` vs `:115`), so the engine is nil at every turn-runner\nconstruction site. The ordering is the root-cause fix and nothing in either\nmemory step reads what those later steps produce.\n\n### 5. The chat write path\n\nThe memory tool is built **per turn**, not registered once at boot, because it\nmust write into a scope derived from the turn's resolved subject:\n\n| action | engine call |\n|---|---|\n| `create` | `Create` |\n| `update` | `Update` (by id) |\n| `delete` | `Forget` (by id) |\n| `list` | `List` |\n\n**The model chooses the scope kind; it never chooses the ids.** Agent and user\nids come from the turn's resolution and there is no schema field to put anything\nelse in — even a model that emits another user's id has nowhere to write it. That\nis the root-cause form of `agent-system.md`, matching this system's other\nnon-waivable boundaries (the model never runs git; gates cannot be waived by the\nagent). `global` is not offered at all.\n\nThe tool takes a record **id** where the retired provider took a content\nsubstring (`handleReplace`/`handleRemove`). The substring addressing existed\nbecause a markdown file was hand-edited and the model had no stable handle on a\nblock; with ids rendered into the prompt it disappears, and one addressing scheme\nreplaces two.\n\n### 6. The curator's write\n\n`sessioncurator.reviewOne` stops writing `Identity: sessionID` and writes\n`ScopeAgentUser{AgentID: \u003csession's agent\u003e, UserID: \u003cparticipant\u003e}`. Relationship\nscope is the only defensible home: agent-wide is explicitly unsafe for user facts\nand would leak user A's extracted facts to user B through the same agent;\nuser-wide would pool facts across agents; and a session id cannot survive the\nsession ending, which is the whole requirement.\n\nThis needs data the tree does not persist: the SQLite `messages` table\ngains `sender_id`, and `curator.SessionSummary` / `ConversationMessage` gain the\nagent and participant. The participant is derived from the session's own\nuser-role messages: exactly one distinct non-empty sender writes; zero (a\ndashboard or webhook session) or several (a group chat) writes nothing and\nrecords why. Ambiguity fails closed rather than guessing.\n\nThe payoff is the point of the exercise: chat-written and curator-derived memory\nnow occupy the same scopes, so a future turn's prompt contains both, and a\ncurator's bad note becomes id-addressable and therefore correctable by the agent.\n\n### 7. The content scanner moves to the engine\n\n`internal/memory/scanner.go` and its installation at `bootstrap.go` are what\nmake `configuration.md`'s \"Memory safety scanner\" row describe a control that\nactually runs. Deleting the package would silently remove prompt-injection\nscanning on memory writes. The scanner moves into the engine and is applied in\n`Create` and `Update`, which is the single choke point every producer crosses —\nso the curator's model-extracted content is covered too, not just the chat tool's.\n\n### 8. `internal/memory` is deleted\n\nNot shimmed, not partially, not behind a flag: `manager.go`, `provider.go`,\n`lifecycle.go`, `sync.go`, `scanner.go` (moved), `schema.go`, `backup.go`,\n`config.go`, `builtin/provider.go`, and their tests. Its markdown store\n(`builtin/store.go`) is the one survivor, relocated to\n`internal/infrastructure/memory/builtin/` — `organisation.md`'s \"a package owns\nits on-disk format end-to-end\" makes infrastructure its correct home, and the\nengine already parses that format.\n\nAlso deleted: `internal/tools/provider/memory`'s manager wrapping (rewired to the\nengine), `config.Memory.{Provider,ProviderConfig}` and the\n`validateMemory` rejection that exists only to complain about `Provider`\n(`validate.go`), and `webui.MemoryStatus`/`MemoryProviderHandle` — never\nimplemented in production, so `/api/memory` reports empty forever unless it is\nrepointed at the engine registry.\n\nExisting data at `\u003cworkDir\u003e/memory` is left on disk, unreferenced. No migration.\n`\u003cworkDir\u003e/memory-engine` is likewise orphaned: its directories were keyed by\n`sha256(sessionID)` and no scope key can hash to one.\n\n## What we deliberately do NOT do\n\n- **No cross-scope sharing or grants in this wave.** Promoting a record between\n scopes is a future explicit command, and `Update` cannot change scope, so it\n cannot happen by accident.\n- **No canonical user identity.** `SenderID` is channel-native, so one person on\n Telegram and email is two identities. Unifying needs an Identity aggregate that\n does not exist (`internal/domain` has no identity package and `IdentityID`\n appears nowhere in Go). The contract does not change when it lands.\n- **No ranked retrieval.** `Query.Text` stays, unused by the prompt path.\n- **No data migration**, per the decision above.\n- **No prompt-memory timeout mechanism.** The read is bounded by construction.\n- **No `Metadata` field.** It is write-only; a caller needing it later\n needs one field, not a speculative contract.\n\n## Acceptance criteria\n\n1. A record created through the memory tool in turn 1 appears in turn 2's prompt,\n asserted on content the test planted, with its id.\n2. The same record is **absent** from a different user's prompt on the same\n channel and agent. Isolation asserted end to end, not at the engine boundary.\n3. An agent-scope record is visible to both of that agent's users; a global\n record is visible to a second agent; an agent-user record is not.\n4. A curator pass over a session writes a record a later turn reads, and which\n survives that session being deleted.\n5. `create` → prompt shows it; `update` → prompt shows new content and\n `Revisions` returns the prior content with author and time; `delete` → gone\n from prompt and `List`. Round-trip is asserted as `parse(render(r)) == r`,\n never against a fixture string.\n6. A panicking engine and a failing engine both complete the turn with no memory\n block.\n7. A channel with no resolvable user renders only global and agent scopes, and\n the tool refuses `user`/`agent-user` with a reason. A webhook route path never\n becomes a user identity.\n8. A write that would exceed the file cap fails loudly rather than silently\n dropping content.\n9. `internal/memory` is gone, `task check` is green, and no document describes a\n manager that no longer exists.\n\nEvery criterion asserts behaviour or planted content. None asserts on the text of\na hand-written file, and none pins that a method was called. In particular none\nasserts the composition calls setup in a given order: if the ordering were\nswapped back, criteria 1 and 4 would fail, and that is the assertion.\n\n## Sequencing\n\nEach step is independently verifiable and lands green on its own.\n\n1. **Persist the participant.** `sender_id` column on `messages`,\n insert/select/migration, `curator.SessionSummary.AgentID` and\n `ConversationMessage.SenderID`. Touches no memory contract and is shippable\n alone — nothing consumes it yet.\n2. **Scope, CRUD and revisions.** The `internal/domain/memory` contract, the\n builtin engine with `HISTORY.md`, the store relocation, the scanner move, and\n the curator rewritten onto agent-user scope (it is the engine's only live\n consumer, so it belongs in this slice). *Depends on 1 for the curator half.*\n3. **Chat read path.** The `Memory` seam, the template block, subject resolution,\n and the composition-ordering fix. *Depends on 2.*\n4. **Chat write path.** The tool adapter onto CRUD and the turn's subject on the\n context. *Depends on 3, because a write is only observable through the read.*\n5. **Delete `internal/memory` and the dead config/dashboard surface**, and\n rewrite the \"Memory engine family\" section of\n `docs/architecture/plugins-and-extensions.md` to describe the\n engine family rather than a manager it deleted. *Depends on 3 and 4.*\n\nSteps 3 and 4 are separable from each other; step 1 is separable from everything.\n\n## Settles these open items in `migration-decisions.md` §5\n\n| §5 open item | Settled by |\n|---|---|\n| authoritative memory record and revision model | §1, §2 — the live marker becomes JSON, since the ratified `\u003c!--mem:\u003culid\u003e--\u003e` cannot carry provenance; superseded states live in a per-scope `HISTORY.md` |\n| provider and infrastructure boundaries | §2 — contract in `internal/domain/memory`, builtin format in `internal/infrastructure/memory/builtin` |\n| retrieval and access enforcement | §1 — caller-named scope sets, no engine-side policy |\n| provenance representation | §2 |\n\n## Not determined\n\n- **Group chats produce no derived memory**, because the curator fails closed on\n mixed-sender sessions. Whether extraction should instead become\n per-participant is a product call.\n- **Two processes, one scope file.** After step 3 both `archied` and\n `archie-gateway` hold an engine over the same root, and the engine caches a\n store per scope and rewrites the whole file, so concurrent writers on one scope\n can lose a block. `Update.Expected` makes that detectable for one record; it\n does not make the file safe. A reload-before-mutate or advisory lock is the fix\n and is not designed here.\n- **Unbounded history.** `HISTORY.md` grows without limit; no compaction policy.\n- **Size bounds.** `defaultMaxFileBytes` is now per scope rather than per\n identity; whether that is right is unexamined.\n- **Whether the dashboard should carry a user identity.** It has one bearer\n token, not users. Until it has users, web turns are correctly limited to global\n and agent scope.\n" + "body": "# Memory engine unification: four scopes, CRUD, and one write path -- decision\n\n**Status:** Approved\n**Date:** 2026-09-16\n**Findings:** `memory-4` and its dependants in the adversarial sweep\n(`.local/issue-tracker`); the real defect is the split described below, for\nwhich `memory-4` is a symptom\n**Supersedes:** the draft `memory-turn-context.md` (its synchronous-read\nargument survives and is reused; its `Manager` method and consumer-owned port do\nnot)\n**Settles:** four open items in `docs/architecture/migration-decisions.md#5`\n(listed at the end)\n\n## Problem\n\nThere are **two live memory stores for one assistant**, split by which component\nwrites them, and the chat turn reads neither.\n\n| Family | Written by | Root | Format |\n|---|---|---|---|\n| `internal/memory` (`Manager`, `builtin.Provider`) | the chat agent's `memory_edit` tool via `memorytoolprovider` (`bootstrap.go`) | `\u003cworkDir\u003e/memory` | `MEMORY.md` / `USER.md` |\n| `internal/domain/memory` + `internal/infrastructure/memory` | the session curator (`sessioncurator.go`) | `\u003cworkDir\u003e/memory-engine` | identity-keyed blocks |\n\nThey share no code, no format and no scope vocabulary. Neither reaches a prompt:\n`Manager.SystemPromptBlock` (`internal/memory/manager.go`) has no production\ncaller anywhere, so the agent can write memory through a tool and never read it\nback.\n\nThree further defects fall out of the same split:\n\n1. **The engine's contract is not CRUD.** `Store` is `Write`/`Query`/`List`/\n `Forget` — create, read, delete, and **no Update**. The retired file provider\n *does* have `handleAdd`/`handleReplace`/`handleRemove`, so the family being\n deleted is operationally richer than its replacement.\n2. **There is no scope model.** The contract carries one opaque `Identity\n string`, and the curator fills it with a **session id** (`sessioncurator.go`)\n — which is none of the four scopes `docs/architecture/agent-system.md`\n requires, and stops meaning anything when the session ends.\n3. **The chat turn has no user identity on half the channels.** Telegram and\n email populate `SenderID` with a person; the dashboard populates it with\n nothing, and a webhook populates it with nothing either — a route path names\n a source, not a person, so `webhook.go` leaves `SenderID` empty and carries\n the route in `Inbound.BudgetKey` for rate limiting. `sender_id` is persisted\n (`session_store_postgres.go`), so whatever a channel puts there reaches the\n consumers that read it.\n\n`agent-system.md` says the write-scope selection and cross-scope sharing\nrules \"require a focused memory design decision\". This is that decision.\n\n## Decision\n\n### 1. One engine, addressed by four typed scopes\n\n`internal/domain/memory` is the only memory engine. `Observation.Identity`,\n`Query.Identity`, `Record.Identity` and `List(identity)` are deleted, not\nextended: a field whose meaning depends on the caller cannot carry a scope.\n\n```go\ntype ScopeKind string\n\nconst (\n ScopeGlobal ScopeKind = \"global\" // shared across the application\n ScopeAgent ScopeKind = \"agent\" // private to one Agent\n ScopeUser ScopeKind = \"user\" // one user, across their Agents\n ScopeAgentUser ScopeKind = \"agent-user\" // one Agent's relationship with one user\n)\n\ntype Scope struct {\n Kind ScopeKind\n Agent AgentID // required for ScopeAgent, ScopeAgentUser\n User IdentityID // required for ScopeUser, ScopeAgentUser\n}\n\nfunc (s Scope) Validate() error // rejects a component present where it is not required\nfunc (s Scope) Key() string // canonical, collision-free storage key\n```\n\n`AgentID` and `IdentityID` are opaque. This package never resolves or\ncanonicalises them.\n\nA turn's resolved identity is one value:\n\n```go\ntype Subject struct {\n AgentID AgentID\n UserID IdentityID // \"\" when the channel carries no per-person identity\n}\n\nfunc (s Subject) Scopes() []Scope // readable, most specific first\nfunc (s Subject) WritableScopes() []Scope // never includes ScopeGlobal\n```\n\n**Access control is naming a scope, and nothing else.** The read path names\nexactly the scopes of the resolved `Subject`; the engine never unions beyond what\nit is handed and applies no policy of its own. An engine that enforced policy\nwould need to know about channels, sessions and bindings, and every backend would\nreimplement it. \"Agent-wide is private to its owning Agent by default\"\n(`agent-system.md`) falls out mechanically, because `ScopeAgent{a}` and\n`ScopeAgent{b}` are different storage keys.\n\n`ScopeGlobal` is never model-writable. Writing it is an operator action; nothing\nproduces one yet, but the contract models it because the read set includes it.\n\n### 2. CRUD, with revisions retained\n\n```go\ntype Store interface {\n Create(ctx context.Context, in NewRecord) (Record, error)\n Get(ctx context.Context, scope Scope, id RecordID) (Record, error) // ErrNotFound\n Query(ctx context.Context, q Query) ([]Record, error) // heads only\n List(ctx context.Context, scope Scope) ([]Record, error) // heads only\n Update(ctx context.Context, in RecordUpdate) (Record, error) // ErrNotFound, ErrStaleRevision\n Forget(ctx context.Context, scope Scope, id RecordID) error // idempotent\n Revisions(ctx context.Context, scope Scope, id RecordID) ([]Revision, error)\n}\n```\n\n`Get` and `Forget` take a scope. The current `Forget` scans every identity's\nstore to find a marker (`builtin_engine.go`) purely because the contract\ngave it nothing better.\n\n`Record` carries what `agent-system.md` requires be retained: `Scope`,\n`Kind`, `Content`, `Revision`, `Author`, `OriginUser`, `Source`, `CreatedAt`,\n`UpdatedAt`. `Metadata` is dropped — nothing sets it and the parser never\nrestores it, so it is a field that silently does not round-trip.\n\n`Update` supersedes rather than overwrites. The superseded state is appended to\nthe scope's `HISTORY.md` **before** the live block is replaced, so a crash\nbetween the two leaves an extra history entry and an unchanged record —\nrecoverable — never a record whose previous state was lost. `Update` carries no\n`Scope`: a record may never move between scopes, and the API makes that\nunrepresentable rather than validating it. `Expected` optionally names the\nrevision being replaced and returns `ErrStaleRevision` on mismatch, which matters\nbecause two processes (`archied` and `archie-gateway`) can hold the same scope's\nfile.\n\n`Forget` records a deleted revision before removing the live block, so a record's\nprovenance outlives its content.\n\n### 3. The caller resolves identity; the engine never does\n\nResolution happens in the gateway turn path, where the native sender id and the\nsession are both in hand, and it is supplied **per channel by the composition**:\n\n```go\n// TurnRunnerConfig\n// UserIdentity resolves the initiating user's identity for one inbound message.\n// false means the channel carries no per-person identity, and the turn gets\n// global and agent scopes only. Nil means the same.\nUserIdentity func(msg messaging.Message) (IdentityID, bool)\n```\n\nThis must be injectable rather than a blanket `channel + \":\" + SenderID`\nconcatenation, because a channel's sender id is not necessarily a person: a\nwebhook's route path names a source, and treating it as an identity would give\na URL one -- which is why `webhook.go` leaves `SenderID` empty and carries the\nroute in `Inbound.BudgetKey` instead. Telegram and email supply their sender\nid; the dashboard and webhook resolve nothing.\n\n**Fail closed.** When `UserID` is empty the turn proceeds with global and agent\nscopes only, and a write targeting `user` or `agent-user` fails with a clear\nerror. `agent-system.md` forbids showing one user's memory to another, so\n\"we do not know who this is\" must mean \"show none of it\", never \"fall back to a\nwider scope\".\n\n### 4. The chat read path\n\nSynchronous and total. It runs inside `prepareTurn` (`turn.go`) before the\nprompt is built, never returns an error to the caller, and degrades to an empty\nblock on any engine failure or provider panic. A fire-and-forget hook would race\nthe prompt build in the same turn, which is why this is not a lifecycle hook.\n\nThe read is a scope-only `Query` over the subject's scopes — **not** ranked\nsearch, which remains open in `migration-decisions.md#5`. A ranked read on the\nhot path with no ranking implementation would be a lie.\n\n`SystemPromptConfig` gains a `Memory` field, rendered into\n`templates/archie.md.tpl` between the `\u003ctools\u003e` and `\u003cenv\u003e` blocks:\n\n```\n\u003cmemory purpose=\"durable_context\" trust=\"data\"\u003e\n```\n\n`trust=\"data\"` and inclusion in the precedence clause follow the `\u003ctools\u003e`/`\u003cenv\u003e`\nprecedent exactly: memory content is model-written from untrusted input and must\nbe framed as data, never instructions. The rendered block carries each record's\nshort id, because the write path addresses records by id — one source of truth\nfor both directions.\n\nBoth a per-scope record limit and a byte cap on the rendered block are named\nconstants. The cap is about size, not latency; a local read needs no timeout.\n\n**Prerequisite:** `setupGateways` runs before `setupMemoryAll`\n(`main.go` vs `:428`), and `startGatewayRuntime` before `setupMemory`\n(`gateway.go` vs `:115`), so the engine is nil at every turn-runner\nconstruction site. The ordering is the root-cause fix and nothing in either\nmemory step reads what those later steps produce.\n\n### 5. The chat write path\n\nThe memory tool is built **per turn**, not registered once at boot, because it\nmust write into a scope derived from the turn's resolved subject:\n\n| action | engine call |\n|---|---|\n| `create` | `Create` |\n| `update` | `Update` (by id) |\n| `delete` | `Forget` (by id) |\n| `list` | `List` |\n\n**The model chooses the scope kind; it never chooses the ids.** Agent and user\nids come from the turn's resolution and there is no schema field to put anything\nelse in — even a model that emits another user's id has nowhere to write it. That\nis the root-cause form of `agent-system.md`, matching this system's other\nnon-waivable boundaries (the model never runs git; gates cannot be waived by the\nagent). `global` is not offered at all.\n\nThe tool takes a record **id** where the retired provider took a content\nsubstring (`handleReplace`/`handleRemove`). The substring addressing existed\nbecause a markdown file was hand-edited and the model had no stable handle on a\nblock; with ids rendered into the prompt it disappears, and one addressing scheme\nreplaces two.\n\n### 6. The curator's write\n\n`sessioncurator.reviewOne` stops writing `Identity: sessionID` and writes\n`ScopeAgentUser{AgentID: \u003csession's agent\u003e, UserID: \u003cparticipant\u003e}`. Relationship\nscope is the only defensible home: agent-wide is explicitly unsafe for user facts\nand would leak user A's extracted facts to user B through the same agent;\nuser-wide would pool facts across agents; and a session id cannot survive the\nsession ending, which is the whole requirement.\n\nThis needs data the tree does not persist: the `messages` table\ngains `sender_id`, and `curator.SessionSummary` / `ConversationMessage` gain the\nagent and participant. The participant is derived from the session's own\nuser-role messages: exactly one distinct non-empty sender writes; zero (a\ndashboard or webhook session) or several (a group chat) writes nothing and\nrecords why. Ambiguity fails closed rather than guessing.\n\nThe payoff is the point of the exercise: chat-written and curator-derived memory\nnow occupy the same scopes, so a future turn's prompt contains both, and a\ncurator's bad note becomes id-addressable and therefore correctable by the agent.\n\n### 7. The content scanner moves to the engine\n\n`internal/memory/scanner.go` and its installation at `bootstrap.go` are what\nmake `configuration.md`'s \"Memory safety scanner\" row describe a control that\nactually runs. Deleting the package would silently remove prompt-injection\nscanning on memory writes. The scanner moves into the engine and is applied in\n`Create` and `Update`, which is the single choke point every producer crosses —\nso the curator's model-extracted content is covered too, not just the chat tool's.\n\n### 8. `internal/memory` is deleted\n\nNot shimmed, not partially, not behind a flag: `manager.go`, `provider.go`,\n`lifecycle.go`, `sync.go`, `scanner.go` (moved), `schema.go`, `backup.go`,\n`config.go`, `builtin/provider.go`, and their tests. Its markdown store\n(`builtin/store.go`) is the one survivor, relocated to\n`internal/infrastructure/memory/builtin/` — `organisation.md`'s \"a package owns\nits on-disk format end-to-end\" makes infrastructure its correct home, and the\nengine already parses that format.\n\nAlso deleted: `internal/tools/provider/memory`'s manager wrapping (rewired to the\nengine), `config.Memory.{Provider,ProviderConfig}` and the\n`validateMemory` rejection that exists only to complain about `Provider`\n(`validate.go`), and `webui.MemoryStatus`/`MemoryProviderHandle` — never\nimplemented in production, so `/api/memory` reports empty forever unless it is\nrepointed at the engine registry.\n\nExisting data at `\u003cworkDir\u003e/memory` is left on disk, unreferenced. No migration.\n`\u003cworkDir\u003e/memory-engine` is likewise orphaned: its directories were keyed by\n`sha256(sessionID)` and no scope key can hash to one.\n\n## What we deliberately do NOT do\n\n- **No cross-scope sharing or grants in this wave.** Promoting a record between\n scopes is a future explicit command, and `Update` cannot change scope, so it\n cannot happen by accident.\n- **No canonical user identity.** `SenderID` is channel-native, so one person on\n Telegram and email is two identities. Unifying needs an Identity aggregate that\n does not exist (`internal/domain` has no identity package and `IdentityID`\n appears nowhere in Go). The contract does not change when it lands.\n- **No ranked retrieval.** `Query.Text` stays, unused by the prompt path.\n- **No data migration**, per the decision above.\n- **No prompt-memory timeout mechanism.** The read is bounded by construction.\n- **No `Metadata` field.** It is write-only; a caller needing it later\n needs one field, not a speculative contract.\n\n## Acceptance criteria\n\n1. A record created through the memory tool in turn 1 appears in turn 2's prompt,\n asserted on content the test planted, with its id.\n2. The same record is **absent** from a different user's prompt on the same\n channel and agent. Isolation asserted end to end, not at the engine boundary.\n3. An agent-scope record is visible to both of that agent's users; a global\n record is visible to a second agent; an agent-user record is not.\n4. A curator pass over a session writes a record a later turn reads, and which\n survives that session being deleted.\n5. `create` → prompt shows it; `update` → prompt shows new content and\n `Revisions` returns the prior content with author and time; `delete` → gone\n from prompt and `List`. Round-trip is asserted as `parse(render(r)) == r`,\n never against a fixture string.\n6. A panicking engine and a failing engine both complete the turn with no memory\n block.\n7. A channel with no resolvable user renders only global and agent scopes, and\n the tool refuses `user`/`agent-user` with a reason. A webhook route path never\n becomes a user identity.\n8. A write that would exceed the file cap fails loudly rather than silently\n dropping content.\n9. `internal/memory` is gone, `task check` is green, and no document describes a\n manager that no longer exists.\n\nEvery criterion asserts behaviour or planted content. None asserts on the text of\na hand-written file, and none pins that a method was called. In particular none\nasserts the composition calls setup in a given order: if the ordering were\nswapped back, criteria 1 and 4 would fail, and that is the assertion.\n\n## Sequencing\n\nEach step is independently verifiable and lands green on its own.\n\n1. **Persist the participant.** `sender_id` column on `messages`,\n insert/select/migration, `curator.SessionSummary.AgentID` and\n `ConversationMessage.SenderID`. Touches no memory contract and is shippable\n alone — nothing consumes it yet.\n2. **Scope, CRUD and revisions.** The `internal/domain/memory` contract, the\n builtin engine with `HISTORY.md`, the store relocation, the scanner move, and\n the curator rewritten onto agent-user scope (it is the engine's only live\n consumer, so it belongs in this slice). *Depends on 1 for the curator half.*\n3. **Chat read path.** The `Memory` seam, the template block, subject resolution,\n and the composition-ordering fix. *Depends on 2.*\n4. **Chat write path.** The tool adapter onto CRUD and the turn's subject on the\n context. *Depends on 3, because a write is only observable through the read.*\n5. **Delete `internal/memory` and the dead config/dashboard surface**, and\n rewrite the \"Memory engine family\" section of\n `docs/architecture/plugins-and-extensions.md` to describe the\n engine family rather than a manager it deleted. *Depends on 3 and 4.*\n\nSteps 3 and 4 are separable from each other; step 1 is separable from everything.\n\n## Settles these open items in `migration-decisions.md` §5\n\n| §5 open item | Settled by |\n|---|---|\n| authoritative memory record and revision model | §1, §2 — the live marker becomes JSON, since the ratified `\u003c!--mem:\u003culid\u003e--\u003e` cannot carry provenance; superseded states live in a per-scope `HISTORY.md` |\n| provider and infrastructure boundaries | §2 — contract in `internal/domain/memory`, builtin format in `internal/infrastructure/memory/builtin` |\n| retrieval and access enforcement | §1 — caller-named scope sets, no engine-side policy |\n| provenance representation | §2 |\n\n## Not determined\n\n- **Group chats produce no derived memory**, because the curator fails closed on\n mixed-sender sessions. Whether extraction should instead become\n per-participant is a product call.\n- **Two processes, one scope file.** After step 3 both `archied` and\n `archie-gateway` hold an engine over the same root, and the engine caches a\n store per scope and rewrites the whole file, so concurrent writers on one scope\n can lose a block. `Update.Expected` makes that detectable for one record; it\n does not make the file safe. A reload-before-mutate or advisory lock is the fix\n and is not designed here.\n- **Unbounded history.** `HISTORY.md` grows without limit; no compaction policy.\n- **Size bounds.** `defaultMaxFileBytes` is now per scope rather than per\n identity; whether that is right is unexamined.\n- **Whether the dashboard should carry a user identity.** It has one bearer\n token, not users. Until it has users, web turns are correctly limited to global\n and agent scope.\n" }, { "url": "/dev/prds/messaging-service-boundary/", "title": "Messaging Service boundary and transport design", "section": "PRDs", - "body": "# Messaging Service boundary and transport design\n\n**Status:** Approved\n**Revision:** 1 \n**Date:** 2026-09-19 \n**Beads issue:** `archie-core-8cda.6.1` \n**Parent:** [`service-decomposition.md`](/dev/prds/service-decomposition/) \n**Prerequisites:** Gateway contract extraction (Phase 1), State Store extraction (Phase 2), UI extraction (Phase 3)\n\nThis document is the authoritative specification for Phase 4: Messaging Service extraction. It fixes the process boundary, configuration ownership, client contracts, security posture, readiness behavior, channel invariants, and deletion criteria required by `archie-core-8cda.6` and its child tasks.\n\n## Decision\n\nThe Messaging Service (`cmd/archie-messaging`, composed via `internal/app/archiemessaging`) owns external channel connections (Telegram, email, webhook) and dispatches inbound messages and commands to the standalone Gateway Service over gRPC via `messaging.ChatContract`.\n\nIt is a peer service to the UI Service and the daemon:\n- It serves external chat participants across configured communication platforms.\n- It consumes Gateway's `messaging.ChatContract` exclusively for chat turn execution, streaming, session queries, cancellation, persona selection, and task control actions.\n- It holds no direct database connections (`*store.Store` or SQLite), owns no LLM execution or model provider credentials, and has no dependency on the daemon runtime or the UI HTTP server.\n\n## Boundary and Ownership\n\n| Concern | Messaging Service owns | Messaging Service consumes | Messaging Service must not own or link |\n|---|---|---|---|\n| **Channel transports** | Telegram bot long-polling, Email IMAP/SMTP loops, Inbound Webhook HTTP listener | Gateway `ChatContract` | Direct LLM providers, model runtimes, tokenizer libraries |\n| **Turn dispatch** | Inbound message packaging, typing indicators, live streaming updates | `ChatContract.Route`, `ChatContract.Stream` | `gateway.Router`, `runtime.Runtime`, agent prompt builders |\n| **Sessions \u0026 History** | Platform-to-session key mapping, conversation thread ID translation | `ChatContract.GetSession`, `RecentMessages`, `RecentTurns` | `*store.Store`, `SessionStore` SQLite handles, direct database files |\n| **Control \u0026 Actions** | Platform command parsing (`/status`, `/tasks`, `/cancel`, `/stop`, `/persona`) | `ChatContract.Snapshot`, `ApplyTaskAction`, `Cancel`, `SetPersona` | `daemon.Daemon`, workflow execution engine, worktree operations |\n| **Task Approvals** | Channel interactive keyboards, approval callbacks | `ChatContract.ApplyTaskAction` | Direct task status mutations, forge comment posters |\n| **Configuration** | Platform bot tokens, allowed sender/user IDs, webhook listen ports | `[chat.*]` channel configs, Gateway target/token | `config.Holder`, forge tokens, repo configs, agent container specs |\n| **Readiness** | Messaging process liveness, channel connectivity, Gateway probe | Gateway `ChatContract.Snapshot` | Internal daemon subsystem probes |\n\n## Target Service Shape\n\n1. **Binary entry point**: `cmd/archie-messaging/main.go` parses CLI flags (`-config`, `-config-overlay`, `-gateway-target`, `-gateway-token`) and hands execution to `internal/app/archiemessaging.Run`.\n2. **Application composition**: `internal/app/archiemessaging/` wires:\n - Config loading scoped strictly to `[chat.*]` and `[services.gateway]`.\n - Secret resolution for channel credentials (e.g. Telegram bot token).\n - Gateway gRPC client (`internal/infrastructure/gatewayrpc.Client`).\n - Channel lifecycle managers (`internal/channels/status`).\n - Channel instances (`internal/channels/telegram`, `email`, `webhook`).\n3. **Turn and Stream Execution**:\n - Channels adapt inbound platform messages to `messaging.Inbound`.\n - Streaming channels (Telegram) consume `ChatContract.Stream(ctx, inbound)` which returns `\u003c-chan messaging.ChatEvent`, mapping `started`, `delta`, `tool`, `media`, `done`, and `error` events directly to live message frames.\n - Non-streaming channels (email, synchronous webhooks) consume `ChatContract.Route(ctx, inbound)`.\n\n## Load-Bearing Channel Invariants\n\nThe Messaging Service preserves existing invariants defined in `AGENTS.md` and channel documentation:\n1. **Telegram long-polling**: Must call `dropPendingUpdates(ctx, b)` before `b.Start(ctx)` and on `/restart`.\n2. **Telegram command menus**: Must register command menus simultaneously to `default`, `all_private_chats`, and `all_group_chats` via `commands.go` to prevent menu shadowing.\n3. **No UI detour**: Turns and task actions route directly to Gateway's `ChatContract`; no HTTP request may ever be sent to `archie-ui` or `internal/webui`.\n4. **Sender Confinement**: Telegram sender checks against `allowed_user_ids` must continue to fail closed before initiating any turn dispatch.\n\n## Configuration Ownership\n\n`cmd/archie-messaging` reads only:\n- `[services.gateway].target` and `[services.gateway].target_token` (or CLI flags).\n- `[chat.telegram]` (token, allowed user IDs).\n- `[chat.email]` (IMAP/SMTP host, ports, credentials).\n- `[chat.webhook]` (listen address, secret).\n- `[secrets]` (for resolving token secret references).\n\nIt does not read or decode `[forge]`, `[repos]`, `[models]`, `[providers]`, `[runners]`, `[containers]`, or `[nats]`.\n\n## Deletion Gate and Verification\n\nThe extraction is guarded by `cmd/archie-messaging/architecture_test.go`, verifying that `go list -deps ./cmd/archie-messaging` links zero banned runtime packages:\n- `modernc.org/sqlite` and `internal/store` (State Store)\n- `internal/daemon`, `internal/app/archied`, `internal/container`, `internal/worktree` (Daemon runtime)\n- `internal/domain/workflow`, `internal/agentexec`, `internal/taskrun` (Workflow engine)\n- `internal/forge`, `internal/forgerpc` (Forge client)\n- `internal/gateway` runtime (only `internal/domain/messaging` and `internal/infrastructure/gatewayrpc` are permitted)\n- `internal/webui` (Dashboard)\n" + "body": "# Messaging Service boundary and transport design\n\n**Status:** Approved\n**Revision:** 1 \n**Date:** 2026-09-19 \n**Beads issue:** `archie-core-8cda.6.1` \n**Parent:** [`service-decomposition.md`](/dev/prds/service-decomposition/) \n**Prerequisites:** Gateway contract extraction (Phase 1), State Store extraction (Phase 2), UI extraction (Phase 3)\n\nThis document is the authoritative specification for Phase 4: Messaging Service extraction. It fixes the process boundary, configuration ownership, client contracts, security posture, readiness behavior, channel invariants, and deletion criteria required by `archie-core-8cda.6` and its child tasks.\n\n## Decision\n\nThe Messaging Service (`cmd/archie-messaging`, composed via `internal/app/archiemessaging`) owns external channel connections (Telegram, email, webhook) and dispatches inbound messages and commands to the standalone Gateway Service over gRPC via `messaging.ChatContract`.\n\nIt is a peer service to the UI Service and the daemon:\n- It serves external chat participants across configured communication platforms.\n- It consumes Gateway's `messaging.ChatContract` exclusively for chat turn execution, streaming, session queries, cancellation, persona selection, and task control actions.\n- It holds no direct database connections, owns no LLM execution or model provider credentials, and has no dependency on the daemon runtime or the UI HTTP server.\n\n## Boundary and Ownership\n\n| Concern | Messaging Service owns | Messaging Service consumes | Messaging Service must not own or link |\n|---|---|---|---|\n| **Channel transports** | Telegram bot long-polling, Email IMAP/SMTP loops, Inbound Webhook HTTP listener | Gateway `ChatContract` | Direct LLM providers, model runtimes, tokenizer libraries |\n| **Turn dispatch** | Inbound message packaging, typing indicators, live streaming updates | `ChatContract.Route`, `ChatContract.Stream` | `gateway.Router`, `runtime.Runtime`, agent prompt builders |\n| **Sessions \u0026 History** | Platform-to-session key mapping, conversation thread ID translation | `ChatContract.GetSession`, `RecentMessages`, `RecentTurns` | store implementations, `SessionStore` database handles |\n| **Control \u0026 Actions** | Platform command parsing (`/status`, `/tasks`, `/cancel`, `/stop`, `/persona`) | `ChatContract.Snapshot`, `ApplyTaskAction`, `Cancel`, `SetPersona` | `daemon.Daemon`, workflow execution engine, worktree operations |\n| **Task Approvals** | Channel interactive keyboards, approval callbacks | `ChatContract.ApplyTaskAction` | Direct task status mutations, forge comment posters |\n| **Configuration** | Platform bot tokens, allowed sender/user IDs, webhook listen ports | `[chat.*]` channel configs, Gateway target/token | `config.Holder`, forge tokens, repo configs, agent container specs |\n| **Readiness** | Messaging process liveness, channel connectivity, Gateway probe | Gateway `ChatContract.Snapshot` | Internal daemon subsystem probes |\n\n## Target Service Shape\n\n1. **Binary entry point**: `cmd/archie-messaging/main.go` parses CLI flags (`-config`, `-config-overlay`, `-gateway-target`, `-gateway-token`) and hands execution to `internal/app/archiemessaging.Run`.\n2. **Application composition**: `internal/app/archiemessaging/` wires:\n - Config loading scoped strictly to `[chat.*]` and `[services.gateway]`.\n - Secret resolution for channel credentials (e.g. Telegram bot token).\n - Gateway gRPC client (`internal/infrastructure/gatewayrpc.Client`).\n - Channel lifecycle managers (`internal/channels/status`).\n - Channel instances (`internal/channels/telegram`, `email`, `webhook`).\n3. **Turn and Stream Execution**:\n - Channels adapt inbound platform messages to `messaging.Inbound`.\n - Streaming channels (Telegram) consume `ChatContract.Stream(ctx, inbound)` which returns `\u003c-chan messaging.ChatEvent`, mapping `started`, `delta`, `tool`, `media`, `done`, and `error` events directly to live message frames.\n - Non-streaming channels (email, synchronous webhooks) consume `ChatContract.Route(ctx, inbound)`.\n\n## Load-Bearing Channel Invariants\n\nThe Messaging Service preserves existing invariants defined in `AGENTS.md` and channel documentation:\n1. **Telegram long-polling**: Must call `dropPendingUpdates(ctx, b)` before `b.Start(ctx)` and on `/restart`.\n2. **Telegram command menus**: Must register command menus simultaneously to `default`, `all_private_chats`, and `all_group_chats` via `commands.go` to prevent menu shadowing.\n3. **No UI detour**: Turns and task actions route directly to Gateway's `ChatContract`; no HTTP request may ever be sent to `archie-ui` or `internal/webui`.\n4. **Sender Confinement**: Telegram sender checks against `allowed_user_ids` must continue to fail closed before initiating any turn dispatch.\n\n## Configuration Ownership\n\n`cmd/archie-messaging` reads only:\n- `[services.gateway].target` and `[services.gateway].target_token` (or CLI flags).\n- `[chat.telegram]` (token, allowed user IDs).\n- `[chat.email]` (IMAP/SMTP host, ports, credentials).\n- `[chat.webhook]` (listen address, secret).\n- `[secrets]` (for resolving token secret references).\n\nIt does not read or decode `[forge]`, `[repos]`, `[models]`, `[providers]`, `[runners]`, `[containers]`, or `[nats]`.\n\n## Deletion Gate and Verification\n\nThe extraction is guarded by `cmd/archie-messaging/architecture_test.go`, verifying that `go list -deps ./cmd/archie-messaging` links zero banned runtime packages:\n- `modernc.org/sqlite`, `github.com/jackc/pgx`, `internal/infrastructure/postgres` and `internal/infrastructure/legacyread` (State Store)\n- `internal/daemon`, `internal/app/archied`, `internal/container`, `internal/worktree` (Daemon runtime)\n- `internal/domain/workflow`, `internal/agentexec`, `internal/taskrun` (Workflow engine)\n- `internal/forge`, `internal/forgerpc` (Forge client)\n- `internal/gateway` runtime (only `internal/domain/messaging` and `internal/infrastructure/gatewayrpc` are permitted)\n- `internal/webui` (Dashboard)\n" }, { "url": "/dev/prds/module-position/", @@ -334,7 +334,7 @@ "url": "/dev/prds/payload-field-mapping/", "title": "Payload field mapping -- decision", "section": "PRDs", - "body": "# Payload field mapping -- decision\n\n**Status:** Approved\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-t2db.3`, depends on `t2db.1`, blocks `t2db.4`\n\nAnswers what a \"mapping\" is, where it lives, and what \"resolve against a\nreal event\" means precisely enough to implement. `t2db.4` (binding: matcher\n+ mapping + workflow) is out of scope -- this bead ships the mapping\nconcept and its preview only, as a standalone entity `t2db.4` will later\nreference by ID.\n\n## Decision: a new `internal/domain/mapping` package, SQLite storage\n\n`internal/domain/mapping` owns the mapping vocabulary and the pure\nresolve/preview rule; `internal/store` persists it (mirrors\n`captures.go`'s shape exactly -- inline schema const, narrow store\ninterface, `*store.Store` implementation); `internal/webui/api_mapping.go`\nis the transport. This follows `docs/prds/event-capture-storage.md`'s own\nplacement precedent: `internal/store` is where this daemon's persistence\nalready lives, not `internal/infrastructure` (that layer holds\ncross-domain services -- config, eventbus, modelcatalog -- not this\ndaemon's primary store).\n\n### Why a domain package and not just a store table\n\nResolving a path against a payload and deciding \"missing vs null vs\ntype-changed\" is a rule, not a query -- CLAUDE.md's domain layer owns\n\"language, state, rules, operations\" precisely so this logic is testable\nwithout a database and reusable by `t2db.4`'s runtime trigger path without\neither package importing the other's transport concerns.\n\n## Mapping shape\n\n```go\ntype Mapping struct {\n\tID int64\n\tName string\n\tSourceHint string // free-text label (e.g. \"sentry\"), organisational only -- not enforced against Capture.Source\n\tFields []Field\n\tCreatedAt time.Time\n\tUpdatedAt time.Time\n}\n\ntype Field struct {\n\tName string // the name the workflow receives\n\tPath string // dot/bracket path into the payload, see below\n\tType FieldType // expected type, checked at resolve time\n\tRequired bool // Required=false + missing is not a failure; Required=false + wrong type still is\n}\n\ntype FieldType string // \"string\" | \"number\" | \"bool\" | \"object\" | \"array\" | \"any\"\n```\n\n`SourceHint` is advisory only: an operator authors a mapping by clicking\nthrough one example capture, but the mapping is not pinned to that\ncapture's exact source string, because `t2db.4`'s matcher (not this bead)\ndecides which events a binding applies to. Pinning here would duplicate\nthat decision in the wrong layer.\n\n## Path syntax\n\nDot-separated keys with `[N]` for array indices: `data.items[0].id`. No\nwildcards, no filters, no external library -- the grammar is exactly what a\nclick-through UI needs to express (this key, then this key, then this\nindex), and every path in a mapping was generated by clicking a value in a\nreal payload, never hand-written against a spec. A hand-rolled parser\n(~30 lines: split on `.`, strip `[N]` suffixes) is less risk than a new\ndependency for a grammar this small.\n\n## Resolve semantics (the preview AND the future runtime path)\n\n```go\nfunc Resolve(fields []Field, payload []byte) (values map[string]any, failures []Failure)\n\ntype Failure struct {\n\tFieldName string\n\tPath string\n\tReason string // \"missing\" | \"null\" | \"type_mismatch\"\n}\n```\n\nDecode with `json.Decoder.UseNumber()` (matches `webhookguard.RedactPayload`'s\nexisting convention) so int/float distinction survives for type checking.\nWalk each field's path independently -- one field's failure does not stop\nresolution of the others, because the whole point of preview is showing\nthe operator every problem at once, not the first one.\n\n- Path segment doesn't exist, or indexes past an array's length -\u003e `missing`\n- Path resolves to JSON `null` -\u003e `null`\n- Path resolves to a value whose JSON type doesn't match `Field.Type`\n (`\"any\"` always matches) -\u003e `type_mismatch`\n- `Required: false` suppresses `missing` only, never `null` or\n `type_mismatch` -- a field that's present but the wrong shape is always\n worth surfacing, since silently coercing it is exactly the \"agent\n confabulates around a blank field\" failure this bead exists to prevent.\n\n**This is the same function both consumers use.** `t2db.3`'s preview calls\nit against an operator-picked capture and renders every result, pass or\nfail, in the UI -- that satisfies this bead's \"fail loudly\" acceptance\ncriterion, because at this stage the only runtime consumer of a mapping\n*is* the human previewing it. `t2db.4` will call the identical function\nwhen a live event triggers a binding and turn any non-empty `failures` into\na visible operator-facing failure (park the task / surface in the\ninspector) instead of starting a workflow with blank fields -- that wiring\nis `t2db.4`'s job, not duplicated here.\n\n## Storage\n\n`internal/store/mappings.go`, `field_mappings` table: `id, name,\nsource_hint, fields_json, created_at, updated_at`. `fields_json` is the\n`[]Field` slice JSON-encoded into one column -- fields have no independent\nquery need (nothing filters \"mappings with a field named X\"), so a\njoin table would be structure with no consumer, the same failure mode\n`organisation.md` bans for empty layering.\n\n`MappingStore` interface (narrow, mirrors `CaptureStore`):\n`InsertMapping`, `ListMappings`, `GetMapping`, `UpdateMapping`,\n`DeleteMapping`.\n\n## HTTP surface\n\nAll under `/api/mappings`, token-gated like every other `/api/*` route (no\nbypass -- unlike capture, nothing here accepts unauthenticated input):\n\n- `GET /api/mappings` / `POST /api/mappings` -- list / create\n- `GET|PATCH|DELETE /api/mappings/{id}`\n- `POST /api/mappings/preview` -- body `{fields: []Field, capture_id:\n int64}`, calls `mapping.Resolve` against that capture's stored (already\n redacted) `Body` and returns `{values, failures}`. Deliberately takes\n loose `fields` rather than a saved mapping ID, so an operator can iterate\n before saving anything -- \"never ship a mapping the operator has not seen\n resolve against real data\" requires preview to work pre-save.\n\nPreview resolves against `CapturedEvent.Body`, which is already\nredaction-passed (`webhookguard.RedactPayload`, per\n`event-capture-storage.md`) -- a mapped field pointing at a\nsensitive-keyed path previews as the literal string `\"[redacted]\"`, not the\nreal value. This is accepted, not fixed here: it is the stored ground\ntruth, the same payload `t2db.4`'s runtime path will resolve against, and a\npreview mismatch would be worse than an honest one.\n\n## Frontend\n\nNew `ui/src/mappings/` feature folder, same three-file split as\n`ui/src/captures/`: `mappings.js` (page: list, fetch, create/edit flow),\n`mapping-editor.js` (pure, unit-testable: renders a captured payload as a\nclickable tree -- clicking a leaf appends a field row with `Path`\npre-filled -- plus the field table and preview-result rendering),\n`mappings.css`. Creating a mapping starts from an existing captured event\n(reuses `api.captures`), so the editor always has a real payload to click\nthrough and preview against, never a blank form.\n\n## What this does not decide\n\nThe binding entity, its matcher, its draft/pending_approval/armed state\nmachine, and turning a runtime `Resolve` failure into a parked task are\n`t2db.4`. Per-source HMAC secret registration is `t2db.5`. This bead ships\nthe mapping concept, its storage, and its preview only.\n" + "body": "# Payload field mapping -- decision\n\n**Status:** Approved\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-t2db.3`, depends on `t2db.1`, blocks `t2db.4`\n\nAnswers what a \"mapping\" is, where it lives, and what \"resolve against a\nreal event\" means precisely enough to implement. `t2db.4` (binding: matcher\n+ mapping + workflow) is out of scope -- this bead ships the mapping\nconcept and its preview only, as a standalone entity `t2db.4` will later\nreference by ID.\n\n## Decision: a new `internal/domain/mapping` package, SQLite storage\n\n\u003e Storage superseded: every store now lives in PostgreSQL behind\n\u003e `internal/domain/storecontract`, implemented in `internal/infrastructure/postgres`\n\u003e (`docs/prds/state-store-contract.md`). SQLite names below describe the\n\u003e original design.\n\n`internal/domain/mapping` owns the mapping vocabulary and the pure\nresolve/preview rule; `internal/store` persists it (mirrors\n`captures.go`'s shape exactly -- inline schema const, narrow store\ninterface, `*store.Store` implementation); `internal/webui/api_mapping.go`\nis the transport. This follows `docs/prds/event-capture-storage.md`'s own\nplacement precedent: `internal/store` is where this daemon's persistence\nalready lives, not `internal/infrastructure` (that layer holds\ncross-domain services -- config, eventbus, modelcatalog -- not this\ndaemon's primary store).\n\n### Why a domain package and not just a store table\n\nResolving a path against a payload and deciding \"missing vs null vs\ntype-changed\" is a rule, not a query -- CLAUDE.md's domain layer owns\n\"language, state, rules, operations\" precisely so this logic is testable\nwithout a database and reusable by `t2db.4`'s runtime trigger path without\neither package importing the other's transport concerns.\n\n## Mapping shape\n\n```go\ntype Mapping struct {\n\tID int64\n\tName string\n\tSourceHint string // free-text label (e.g. \"sentry\"), organisational only -- not enforced against Capture.Source\n\tFields []Field\n\tCreatedAt time.Time\n\tUpdatedAt time.Time\n}\n\ntype Field struct {\n\tName string // the name the workflow receives\n\tPath string // dot/bracket path into the payload, see below\n\tType FieldType // expected type, checked at resolve time\n\tRequired bool // Required=false + missing is not a failure; Required=false + wrong type still is\n}\n\ntype FieldType string // \"string\" | \"number\" | \"bool\" | \"object\" | \"array\" | \"any\"\n```\n\n`SourceHint` is advisory only: an operator authors a mapping by clicking\nthrough one example capture, but the mapping is not pinned to that\ncapture's exact source string, because `t2db.4`'s matcher (not this bead)\ndecides which events a binding applies to. Pinning here would duplicate\nthat decision in the wrong layer.\n\n## Path syntax\n\nDot-separated keys with `[N]` for array indices: `data.items[0].id`. No\nwildcards, no filters, no external library -- the grammar is exactly what a\nclick-through UI needs to express (this key, then this key, then this\nindex), and every path in a mapping was generated by clicking a value in a\nreal payload, never hand-written against a spec. A hand-rolled parser\n(~30 lines: split on `.`, strip `[N]` suffixes) is less risk than a new\ndependency for a grammar this small.\n\n## Resolve semantics (the preview AND the future runtime path)\n\n```go\nfunc Resolve(fields []Field, payload []byte) (values map[string]any, failures []Failure)\n\ntype Failure struct {\n\tFieldName string\n\tPath string\n\tReason string // \"missing\" | \"null\" | \"type_mismatch\"\n}\n```\n\nDecode with `json.Decoder.UseNumber()` (matches `webhookguard.RedactPayload`'s\nexisting convention) so int/float distinction survives for type checking.\nWalk each field's path independently -- one field's failure does not stop\nresolution of the others, because the whole point of preview is showing\nthe operator every problem at once, not the first one.\n\n- Path segment doesn't exist, or indexes past an array's length -\u003e `missing`\n- Path resolves to JSON `null` -\u003e `null`\n- Path resolves to a value whose JSON type doesn't match `Field.Type`\n (`\"any\"` always matches) -\u003e `type_mismatch`\n- `Required: false` suppresses `missing` only, never `null` or\n `type_mismatch` -- a field that's present but the wrong shape is always\n worth surfacing, since silently coercing it is exactly the \"agent\n confabulates around a blank field\" failure this bead exists to prevent.\n\n**This is the same function both consumers use.** `t2db.3`'s preview calls\nit against an operator-picked capture and renders every result, pass or\nfail, in the UI -- that satisfies this bead's \"fail loudly\" acceptance\ncriterion, because at this stage the only runtime consumer of a mapping\n*is* the human previewing it. `t2db.4` will call the identical function\nwhen a live event triggers a binding and turn any non-empty `failures` into\na visible operator-facing failure (park the task / surface in the\ninspector) instead of starting a workflow with blank fields -- that wiring\nis `t2db.4`'s job, not duplicated here.\n\n## Storage\n\nThe `mappings` table: `id, name,\nsource_hint, fields_json, created_at, updated_at`. `fields_json` is the\n`[]Field` slice JSON-encoded into one column -- fields have no independent\nquery need (nothing filters \"mappings with a field named X\"), so a\njoin table would be structure with no consumer, the same failure mode\n`organisation.md` bans for empty layering.\n\n`MappingStore` interface (narrow, mirrors `CaptureStore`):\n`InsertMapping`, `ListMappings`, `GetMapping`, `UpdateMapping`,\n`DeleteMapping`.\n\n## HTTP surface\n\nAll under `/api/mappings`, token-gated like every other `/api/*` route (no\nbypass -- unlike capture, nothing here accepts unauthenticated input):\n\n- `GET /api/mappings` / `POST /api/mappings` -- list / create\n- `GET|PATCH|DELETE /api/mappings/{id}`\n- `POST /api/mappings/preview` -- body `{fields: []Field, capture_id:\n int64}`, calls `mapping.Resolve` against that capture's stored (already\n redacted) `Body` and returns `{values, failures}`. Deliberately takes\n loose `fields` rather than a saved mapping ID, so an operator can iterate\n before saving anything -- \"never ship a mapping the operator has not seen\n resolve against real data\" requires preview to work pre-save.\n\nPreview resolves against `CapturedEvent.Body`, which is already\nredaction-passed (`webhookguard.RedactPayload`, per\n`event-capture-storage.md`) -- a mapped field pointing at a\nsensitive-keyed path previews as the literal string `\"[redacted]\"`, not the\nreal value. This is accepted, not fixed here: it is the stored ground\ntruth, the same payload `t2db.4`'s runtime path will resolve against, and a\npreview mismatch would be worse than an honest one.\n\n## Frontend\n\nNew `ui/src/mappings/` feature folder, same three-file split as\n`ui/src/captures/`: `mappings.js` (page: list, fetch, create/edit flow),\n`mapping-editor.js` (pure, unit-testable: renders a captured payload as a\nclickable tree -- clicking a leaf appends a field row with `Path`\npre-filled -- plus the field table and preview-result rendering),\n`mappings.css`. Creating a mapping starts from an existing captured event\n(reuses `api.captures`), so the editor always has a real payload to click\nthrough and preview against, never a blank form.\n\n## What this does not decide\n\nThe binding entity, its matcher, its draft/pending_approval/armed state\nmachine, and turning a runtime `Resolve` failure into a parked task are\n`t2db.4`. Per-source HMAC secret registration is `t2db.5`. This bead ships\nthe mapping concept, its storage, and its preview only.\n" }, { "url": "/dev/prds/playbook-expression-syntax/", @@ -346,7 +346,7 @@ "url": "/dev/prds/pr-review-remediation/", "title": "PR review comment remediation -- decision", "section": "PRDs", - "body": "# PR review comment remediation -- decision\n\n**Status:** Approved\n**Date:** 2026-09-10, amended and ratified 2026-09-19\n**Beads issue:** (filed as `archie-core-…`, parent: `archie-core-7d5u` event sources and typed reactions)\n\nAnswers: how archie reacts to review comments on a PR it opened, from a human\nor from another review bot, and remediates them. Built on two settled decisions — the adversarial review\nepic's isolation contract (`docs/prds/adversarial-self-review.md`) and the\nevent-sources decision (`docs/prds/event-sources-and-reactions.md`) — plus the\nwebhook intake security contract (`docs/prds/webhook-intake-security.md`).\nNothing here re-decides those; it names the one concrete reaction each one's\nmachinery was built to carry.\n\n## Problem\n\nArchie opens a PR (`pr_open`) and then never learns what a human said about\nit. `forge.Forge` has no method to list PR reviews or review comments; the\ndaemon poll loop finds only new issues; the forge webhook receiver\n(`internal/forge/webhook/receiver.go`) decodes only `issues` events and\nexplicitly ignores `pull_request` events. A \"requested changes\" review, or an\ninline comment on a line, is invisible work.\n\n## Decisions\n\n### 1. Read surface: a narrow `PullRequestReviewReader`, type-asserted\n\nA new forge interface, implemented by GitHub and Gitea, not folded into the\nfat `Forge` interface (the h019.8 `PullRequestReader` precedent — the noop\nforge cannot honestly provide it):\n\n```go\ntype ReviewComment struct { ID int64; Author, Body, Path string; Line int; InReplyTo int64; CreatedAt time.Time }\ntype Review struct { ID int64; Author, State string /* requested_changes | approved | commented | dismissed */; SubmittedAt time.Time }\n\ntype PullRequestReviewReader interface {\n ListReviews(ctx, owner, repo string, number, sinceID int64) ([]Review, error)\n ListReviewComments(ctx, owner, repo string, number, sinceID int64) ([]ReviewComment, error)\n // ReplyToReview posts a reply to a review or comment thread.\n ReplyToReview(ctx, owner, repo string, number, inReplyTo int64, body string) error\n}\n```\n\nGitHub: `pulls/{n}/reviews` + `pulls/{n}/comments`; reply via\n`pulls/{n}/comments/{id}/replies`. Gitea: `pulls/{n}/reviews` +\n`pulls/{n}/comments`; reply via `pulls/{n}/comments/{id}`. `sinceID` is the\ncursor for both poll and webhook dedup.\n\n### 2. Event source: webhook first, poll as the universal backstop\n\n- **Webhook (GitHub, low latency):** extend `receiver.go` to also decode\n `pull_request_review` and `pull_request_review_comment` events, behind the\n existing HMAC verification, producing the same reaction as the poller. The\n receiver stays a forge-intake surface — not the generic chat webhook, not a\n new generic receiver (7d5u decision 4).\n- **Poll (both forges, no webhook dependency):** a periodic scan of `pr_open`\n tasks calls `ListReviews`/`ListReviewComments` with a persisted `sinceID`\n cursor per task. This is the Gitea path and the deployment-without-webhook\n path; it must stay first-class, not a legacy fallback (the repo's own\n webhook-intake rule). It is **one shared scan over all `pr_open` tasks**,\n not a scan inside each identity's poll loop, and it calls the forge client\n the scanned task's own identity owns. This is `reconcilePRs`'s shape\n exactly (`internal/daemon/daemon.go`: `Store.OpenPRs` then `forgeFor(\u0026t)`).\n A per-identity scan would call one identity's forge client against another\n identity's PR.\n\nBoth paths emit the **same** typed reaction, so `PublishUnique` dedups them\nfor free — the `TaskEnvelope.IdempotencyKey` pattern (7d5u decision 4) applied\nto reviews.\n\n### 3. Reaction contract: producer-only, resolves to an existing task\n\nA new `workintake.ReviewCommentEnvelope{Owner, Repo, PRNumber, Kind, CommentID,\nReviewID, Author, State, Body, Path, Line}`. Idempotency key is\n`owner/repo/pr-number/kind/id` — source-independent, so a webhook delivery\nand a poll of the same comment collapse.\n\n`Kind` (`review` or `comment`) is part of the key because a review ID and a\nreview-comment ID come from independent forge sequences. Keying on the bare id\nlets a review and an inline comment on the same PR collide, silently dropping\none of the two. This is a producer-only reaction\n(7d5u decision 3): it never vetoes or mutates in-flight work; the target task\nis idle (`pr_open`).\n\nThe daemon resolves `PRNumber` → the task that owns it. An unmatched PR (not\nan archie task) is dropped with a counter — a public webhook must not be able\nto start an agent against an arbitrary repository. A PR whose task is merged,\nclosed or archived is dropped through the same counter: the reaction is only\never work against a PR archie itself opened *and still owns*.\n\nThat lookup does not exist. `pr_number` is written by\n`internal/store/store.go` and never read in a `WHERE` clause, so this needs a\n`TaskStore` method keyed on `(owner, repo, pr_number)`, a matching\n`StateStoreService` RPC (a Go interface method on a store facade without one\nis forbidden, `CLAUDE.md`), and an index on those three columns. It is the\nauthorization boundary, so it is sequenced as its own step below rather than\ncarried along with the envelope.\n\n**Identity is derived from the resolved task, never carried in the reaction.**\nThe task row already stores `identity` (`internal/store/store.go`), and it is\nthe resolved task's identity that selects the forge client, worktree manager,\nrepo config and `bot_user` for the remediation run and the `ReplyToReview`\nreply, through the existing `forgeFor`/`treesFor`/`repoFor` helpers. That is\nwhat decision 5's \"the identity that owns the task\" means, and it is the only\nplace identity enters this path.\n\nIdentity is deliberately **not** added to the envelope, the idempotency key or\nthe index:\n\n- A PR number is unique within an `owner/repo`, and the tasks table is keyed\n `UNIQUE(owner, repo, issue_number)` with no host or identity column, so\n archie already treats `owner/repo` as globally unique across identities. A\n `(owner, repo, pr_number)` lookup cannot return a task other than the one\n that owns that PR; there is no cross-identity resolution to guard against.\n- The webhook producer has no identity to carry: webhook intake refuses to\n start when `[[identities]]` is configured (`setupForgeWebhook`,\n `internal/app/archied/bootstrap.go`).\n- Keying on a field only one of the two producers can populate is precisely\n the delivery-source-specific key `CLAUDE.md` forbids, and it would break the\n webhook/poll dedup the key exists for. An index column that never appears in\n the `WHERE` clause is dead weight.\n\n### 4. Remediation: a `remediate` workflow on the existing branch\n\nA new workflow that runs when a reaction resolves to an archie-owned PR. It is\nnot a new branch/PR — it reuses the task's prepared worktree, refreshes it\nonto the PR branch (the `worktree.Manager.refresh` idempotency), and:\n\n1. Runs a builder agent whose mission is the review's actionable comments\n (each with body, path, line): \"Address these review comments with the\n smallest change; run the gate.\" One agent run per review, per decision 5. The toolset is the normal builder toolset — edit + gate + (never\n git; the orchestrator commits/pushes) — not the reviewer's read-only set.\n2. Runs the repo gate (`[[repos.gate]]`) and `diff_cap_lines` — the same\n enforcement as any other work (webhook-intake-security point 4; no\n relaxation for review-triggered edits).\n3. Commits and pushes to the **same** PR branch.\n4. Replies to the review/comment via `ReplyToReview`, summarising what\n changed.\n\nThe comment is injected through the task record (e.g. `Task.Notes` or a\ndedicated review field), not through a prompt-only path, so the reaction is\nrecoverable and auditable.\n\n### 5. Routing and lifecycle\n\nA **review** is the unit of remediation, never an individual comment.\n\n- `requested_changes` review → one remediation run addressing every actionable\n comment in that review.\n- `commented` review with actionable inline comments → one remediation run\n addressing every actionable comment in that review.\n- `approved` review → no remediation. Record the review state on the task;\n do **not** auto-merge — merging stays an operator action (the dashboard/chat\n `/approve` precedent). Auto-merge is a separate decision if ever wanted.\n\nOne run per review, strictly. A review carrying eight inline comments arrives\nas one `pull_request_review` event plus eight `pull_request_review_comment`\nevents; remediating each separately means eight builder runs, eight gate runs\nand eight pushes to answer one review. The comment events are collected\nagainst their parent `ReviewID` and remediated together. A standalone comment\nwith no parent review is its own unit of one.\n\nRemediation runs for a single task are **serialised**, whatever\n`[[repos]].allow_concurrent` says. Two runs against one PR branch would race\non the shared worktree and on the push; `allow_concurrent` is about unrelated\ntasks in a repo, not about one task reacting to itself.\n\n#### Whose comments count\n\nOnly archie's **own** comments are excluded, matched on the forge identity\nthat owns the task (`bot_user`, or the identity's `bot_user` under\n`[[identities]]`), so its `ReplyToReview` replies do not retrigger it.\n\nEvery other author is actionable, including other bots. The external review\nbot on this repository is the main source of findings on an archie-opened PR,\nand discarding comments because their author is a bot would discard the review\nthis feature exists to act on. There is no \"is a bot\" test anywhere in this\npath.\n\n(The original draft justified a broader exclusion by citing a `RepliesAfter`\n`exclude` precedent. No such mechanism exists in the tree; the citation is\nwithdrawn.)\n\n#### Bounding the exchange\n\nBecause bot comments are actionable, the exchange can run away without a human\never touching it: archie pushes a remediation, the review bot re-reviews the\nnew commit, comments, archie remediates again. Nothing in the reaction path\nterminates that on its own.\n\nA task therefore carries a remediation round count, bounded by the repo's\nexisting `max_retries`. On the cap, archie stops remediating, posts one\ncomment saying it has stopped and why, and parks the task for an operator.\nThis is a hard stop, not a backoff: the failure it guards against is\nunbounded spend, so slowing it down does not address it.\n\n### 6. Security posture\n\nThe webhook reaction is not a public no-code binding, so it does not pass\nthrough the `draft → pending_approval → armed` gate (webhook-intake-security\npoint 2) — but every other constraint holds: HMAC (already in the receiver),\nper-source rate limiting (add when the receiver gains a second event family),\nand blast radius bounded by the existing gate/sandbox/worktree enforcement,\n**plus** the new archie-owned-task check (decision 3), which is the actual\nauthorization boundary: a review event only ever causes work against a PR\narchie itself opened and still owns.\n\nAccepting other bots' comments (decision 5) does not widen that boundary: an\nauthor is never a reason to act, only the owned-task check is. It does widen\nthe *spend* surface, which the round cap bounds.\n\n### 7. Sequencing\n\n1. **The reaction stream.** `ARCHIE_REACTIONS`, under the fan-out\n `jetstream.LimitsPolicy` the parent decision requires\n (`event-sources-and-reactions.md` §2). `Config.Retention` is\n parameterised for exactly this (`archie-core-7d5u.2`), but no reaction\n stream exists and `ARCHIE_TASKS` carries `archie.task.\u003e` only, so every\n publish to `archie.reaction.*` fails against no matching\n stream. This step is first because nothing after it can be exercised\n without it.\n2. `PullRequestReviewReader` + GitHub/Gitea implementations + `ReplyToReview`.\n *(Landed.)*\n3. `ReviewCommentEnvelope` + the kinded idempotency key.\n4. **The owned-task guard**: `(owner, repo, pr_number)` lookup, its\n `StateStoreService` RPC, its index, and the drop-with-counter path for an\n unmatched, merged, closed or archived PR. Nothing may consume a reaction\n before this exists.\n5. `remediate` workflow: worktree refresh, one run per review, builder, gate,\n push, reply, round cap.\n6. Webhook receiver extension (`pull_request_review` / `_comment` events).\n7. Poll backstop with the persisted `sinceID` cursor.\n8. Tests + `task check`.\n\nSteps 6 and 7 are the producers and come last on purpose. Building a producer\nbefore its consumer and its authorization guard yields a path that publishes\ninto nothing, and becomes an unguarded intake the moment a stream appears.\n\n## Out of scope\n\n- Auto-merge on approval (separate decision).\n- Reacting to comments on PRs archie did not open.\n- The calibration epic's confirm-before-surfacing (h019.5) — orthogonal.\n" + "body": "# PR review comment remediation -- decision\n\n**Status:** Approved\n**Date:** 2026-09-10, amended and ratified 2026-09-19\n**Beads issue:** (filed as `archie-core-…`, parent: `archie-core-7d5u` event sources and typed reactions)\n\nAnswers: how archie reacts to review comments on a PR it opened, from a human\nor from another review bot, and remediates them. Built on two settled decisions — the adversarial review\nepic's isolation contract (`docs/prds/adversarial-self-review.md`) and the\nevent-sources decision (`docs/prds/event-sources-and-reactions.md`) — plus the\nwebhook intake security contract (`docs/prds/webhook-intake-security.md`).\nNothing here re-decides those; it names the one concrete reaction each one's\nmachinery was built to carry.\n\n## Problem\n\nArchie opens a PR (`pr_open`) and then never learns what a human said about\nit. `forge.Forge` has no method to list PR reviews or review comments; the\ndaemon poll loop finds only new issues; the forge webhook receiver\n(`internal/forge/webhook/receiver.go`) decodes only `issues` events and\nexplicitly ignores `pull_request` events. A \"requested changes\" review, or an\ninline comment on a line, is invisible work.\n\n## Decisions\n\n### 1. Read surface: a narrow `PullRequestReviewReader`, type-asserted\n\nA new forge interface, implemented by GitHub and Gitea, not folded into the\nfat `Forge` interface (the h019.8 `PullRequestReader` precedent — the noop\nforge cannot honestly provide it):\n\n```go\ntype ReviewComment struct { ID int64; Author, Body, Path string; Line int; InReplyTo int64; CreatedAt time.Time }\ntype Review struct { ID int64; Author, State string /* requested_changes | approved | commented | dismissed */; SubmittedAt time.Time }\n\ntype PullRequestReviewReader interface {\n ListReviews(ctx, owner, repo string, number, sinceID int64) ([]Review, error)\n ListReviewComments(ctx, owner, repo string, number, sinceID int64) ([]ReviewComment, error)\n // ReplyToReview posts a reply to a review or comment thread.\n ReplyToReview(ctx, owner, repo string, number, inReplyTo int64, body string) error\n}\n```\n\nGitHub: `pulls/{n}/reviews` + `pulls/{n}/comments`; reply via\n`pulls/{n}/comments/{id}/replies`. Gitea: `pulls/{n}/reviews` +\n`pulls/{n}/comments`; reply via `pulls/{n}/comments/{id}`. `sinceID` is the\ncursor for both poll and webhook dedup.\n\n### 2. Event source: webhook first, poll as the universal backstop\n\n- **Webhook (GitHub, low latency):** extend `receiver.go` to also decode\n `pull_request_review` and `pull_request_review_comment` events, behind the\n existing HMAC verification, producing the same reaction as the poller. The\n receiver stays a forge-intake surface — not the generic chat webhook, not a\n new generic receiver (7d5u decision 4).\n- **Poll (both forges, no webhook dependency):** a periodic scan of `pr_open`\n tasks calls `ListReviews`/`ListReviewComments` with a persisted `sinceID`\n cursor per task. This is the Gitea path and the deployment-without-webhook\n path; it must stay first-class, not a legacy fallback (the repo's own\n webhook-intake rule). It is **one shared scan over all `pr_open` tasks**,\n not a scan inside each identity's poll loop, and it calls the forge client\n the scanned task's own identity owns. This is `reconcilePRs`'s shape\n exactly (`internal/daemon/daemon.go`: `Store.OpenPRs` then `forgeFor(\u0026t)`).\n A per-identity scan would call one identity's forge client against another\n identity's PR.\n\nBoth paths emit the **same** typed reaction, so `PublishUnique` dedups them\nfor free — the `TaskEnvelope.IdempotencyKey` pattern (7d5u decision 4) applied\nto reviews.\n\n### 3. Reaction contract: producer-only, resolves to an existing task\n\nA new `workintake.ReviewCommentEnvelope{Owner, Repo, PRNumber, Kind, CommentID,\nReviewID, Author, State, Body, Path, Line}`. Idempotency key is\n`owner/repo/pr-number/kind/id` — source-independent, so a webhook delivery\nand a poll of the same comment collapse.\n\n`Kind` (`review` or `comment`) is part of the key because a review ID and a\nreview-comment ID come from independent forge sequences. Keying on the bare id\nlets a review and an inline comment on the same PR collide, silently dropping\none of the two. This is a producer-only reaction\n(7d5u decision 3): it never vetoes or mutates in-flight work; the target task\nis idle (`pr_open`).\n\nThe daemon resolves `PRNumber` → the task that owns it. An unmatched PR (not\nan archie task) is dropped with a counter — a public webhook must not be able\nto start an agent against an arbitrary repository. A PR whose task is merged,\nclosed or archived is dropped through the same counter: the reaction is only\never work against a PR archie itself opened *and still owns*.\n\nThat lookup does not exist. `pr_number` is written by\n`internal/infrastructure/postgres/store.go` and never read in a `WHERE` clause, so this needs a\n`TaskStore` method keyed on `(owner, repo, pr_number)`, a matching\n`StateStoreService` RPC (a Go interface method on a store facade without one\nis forbidden, `CLAUDE.md`), and an index on those three columns. It is the\nauthorization boundary, so it is sequenced as its own step below rather than\ncarried along with the envelope.\n\n**Identity is derived from the resolved task, never carried in the reaction.**\nThe task row already stores `identity` (`internal/infrastructure/postgres/store.go`), and it is\nthe resolved task's identity that selects the forge client, worktree manager,\nrepo config and `bot_user` for the remediation run and the `ReplyToReview`\nreply, through the existing `forgeFor`/`treesFor`/`repoFor` helpers. That is\nwhat decision 5's \"the identity that owns the task\" means, and it is the only\nplace identity enters this path.\n\nIdentity is deliberately **not** added to the envelope, the idempotency key or\nthe index:\n\n- A PR number is unique within an `owner/repo`, and the tasks table is keyed\n `UNIQUE(owner, repo, issue_number)` with no host or identity column, so\n archie already treats `owner/repo` as globally unique across identities. A\n `(owner, repo, pr_number)` lookup cannot return a task other than the one\n that owns that PR; there is no cross-identity resolution to guard against.\n- The webhook producer has no identity to carry: webhook intake refuses to\n start when `[[identities]]` is configured (`setupForgeWebhook`,\n `internal/app/archied/bootstrap.go`).\n- Keying on a field only one of the two producers can populate is precisely\n the delivery-source-specific key `CLAUDE.md` forbids, and it would break the\n webhook/poll dedup the key exists for. An index column that never appears in\n the `WHERE` clause is dead weight.\n\n### 4. Remediation: a `remediate` workflow on the existing branch\n\nA new workflow that runs when a reaction resolves to an archie-owned PR. It is\nnot a new branch/PR — it reuses the task's prepared worktree, refreshes it\nonto the PR branch (the `worktree.Manager.refresh` idempotency), and:\n\n1. Runs a builder agent whose mission is the review's actionable comments\n (each with body, path, line): \"Address these review comments with the\n smallest change; run the gate.\" One agent run per review, per decision 5. The toolset is the normal builder toolset — edit + gate + (never\n git; the orchestrator commits/pushes) — not the reviewer's read-only set.\n2. Runs the repo gate (`[[repos.gate]]`) and `diff_cap_lines` — the same\n enforcement as any other work (webhook-intake-security point 4; no\n relaxation for review-triggered edits).\n3. Commits and pushes to the **same** PR branch.\n4. Replies to the review/comment via `ReplyToReview`, summarising what\n changed.\n\nThe comment is injected through the task record (e.g. `Task.Notes` or a\ndedicated review field), not through a prompt-only path, so the reaction is\nrecoverable and auditable.\n\n### 5. Routing and lifecycle\n\nA **review** is the unit of remediation, never an individual comment.\n\n- `requested_changes` review → one remediation run addressing every actionable\n comment in that review.\n- `commented` review with actionable inline comments → one remediation run\n addressing every actionable comment in that review.\n- `approved` review → no remediation. Record the review state on the task;\n do **not** auto-merge — merging stays an operator action (the dashboard/chat\n `/approve` precedent). Auto-merge is a separate decision if ever wanted.\n\nOne run per review, strictly. A review carrying eight inline comments arrives\nas one `pull_request_review` event plus eight `pull_request_review_comment`\nevents; remediating each separately means eight builder runs, eight gate runs\nand eight pushes to answer one review. The comment events are collected\nagainst their parent `ReviewID` and remediated together. A standalone comment\nwith no parent review is its own unit of one.\n\nRemediation runs for a single task are **serialised**, whatever\n`[[repos]].allow_concurrent` says. Two runs against one PR branch would race\non the shared worktree and on the push; `allow_concurrent` is about unrelated\ntasks in a repo, not about one task reacting to itself.\n\n#### Whose comments count\n\nOnly archie's **own** comments are excluded, matched on the forge identity\nthat owns the task (`bot_user`, or the identity's `bot_user` under\n`[[identities]]`), so its `ReplyToReview` replies do not retrigger it.\n\nEvery other author is actionable, including other bots. The external review\nbot on this repository is the main source of findings on an archie-opened PR,\nand discarding comments because their author is a bot would discard the review\nthis feature exists to act on. There is no \"is a bot\" test anywhere in this\npath.\n\n(The original draft justified a broader exclusion by citing a `RepliesAfter`\n`exclude` precedent. No such mechanism exists in the tree; the citation is\nwithdrawn.)\n\n#### Bounding the exchange\n\nBecause bot comments are actionable, the exchange can run away without a human\never touching it: archie pushes a remediation, the review bot re-reviews the\nnew commit, comments, archie remediates again. Nothing in the reaction path\nterminates that on its own.\n\nA task therefore carries a remediation round count, bounded by the repo's\nexisting `max_retries`. On the cap, archie stops remediating, posts one\ncomment saying it has stopped and why, and parks the task for an operator.\nThis is a hard stop, not a backoff: the failure it guards against is\nunbounded spend, so slowing it down does not address it.\n\n### 6. Security posture\n\nThe webhook reaction is not a public no-code binding, so it does not pass\nthrough the `draft → pending_approval → armed` gate (webhook-intake-security\npoint 2) — but every other constraint holds: HMAC (already in the receiver),\nper-source rate limiting (add when the receiver gains a second event family),\nand blast radius bounded by the existing gate/sandbox/worktree enforcement,\n**plus** the new archie-owned-task check (decision 3), which is the actual\nauthorization boundary: a review event only ever causes work against a PR\narchie itself opened and still owns.\n\nAccepting other bots' comments (decision 5) does not widen that boundary: an\nauthor is never a reason to act, only the owned-task check is. It does widen\nthe *spend* surface, which the round cap bounds.\n\n### 7. Sequencing\n\n1. **The reaction stream.** `ARCHIE_REACTIONS`, under the fan-out\n `jetstream.LimitsPolicy` the parent decision requires\n (`event-sources-and-reactions.md` §2). `Config.Retention` is\n parameterised for exactly this (`archie-core-7d5u.2`), but no reaction\n stream exists and `ARCHIE_TASKS` carries `archie.task.\u003e` only, so every\n publish to `archie.reaction.*` fails against no matching\n stream. This step is first because nothing after it can be exercised\n without it.\n2. `PullRequestReviewReader` + GitHub/Gitea implementations + `ReplyToReview`.\n *(Landed.)*\n3. `ReviewCommentEnvelope` + the kinded idempotency key.\n4. **The owned-task guard**: `(owner, repo, pr_number)` lookup, its\n `StateStoreService` RPC, its index, and the drop-with-counter path for an\n unmatched, merged, closed or archived PR. Nothing may consume a reaction\n before this exists.\n5. `remediate` workflow: worktree refresh, one run per review, builder, gate,\n push, reply, round cap.\n6. Webhook receiver extension (`pull_request_review` / `_comment` events).\n7. Poll backstop with the persisted `sinceID` cursor.\n8. Tests + `task check`.\n\nSteps 6 and 7 are the producers and come last on purpose. Building a producer\nbefore its consumer and its authorization guard yields a path that publishes\ninto nothing, and becomes an unguarded intake the moment a stream appears.\n\n## Out of scope\n\n- Auto-merge on approval (separate decision).\n- Reacting to comments on PRs archie did not open.\n- The calibration epic's confirm-before-surfacing (h019.5) — orthogonal.\n" }, { "url": "/dev/prds/progressive-tool-disclosure/", @@ -388,7 +388,7 @@ "url": "/dev/prds/service-decomposition/", "title": "Service decomposition -- decision", "section": "PRDs", - "body": "# Service decomposition -- decision\n\n**Status:** Draft\n**Date:** 2026-09-05\n**Beads epic:** archie-core-8cda\n**Prior art:** `docs/inspiration/2026-09-05-awx-service-decomposition-and-ansible-task-model.md`,\n`docs/inspiration/module-reference-awx-decomposition-vs-archie.md`,\n`docs/inspiration/service-discovery-research-2026-09-05.md`,\n`/work/artefacts/archie-core-current-state-archify.html`,\n`/work/artefacts/archie-core-ideal-state-archify.html`\n\nThe Phase 3 UI boundary and configuration decision is ratified in\n[`ui-service-boundary.md`](/dev/prds/ui-service-boundary/). That focused document is\nthe implementation authority for `archie-core-8cda.5.2`; this parent remains\nthe broader service-distribution proposal.\n\n## Decision\n\narchie-core moves from one Go binary (`archied`) hosting every domain\nin-process to a set of independently deployable services, each exposing\nexactly one typed contract. Consumers depend on the contract; they never\nreach into another service's internal types, session state, or config.\ngRPC is the synchronous transport; NATS remains for asynchronous fan-out\n(status, telemetry) rather than being replaced.\n\nThis is a **distribution decision**, not a rewrite of Archie's domain\nmodel. The six-domain split already approved in\n`docs/architecture/index.md` and `docs/architecture/organisation.md`\n(Identity, Agent, Messaging, Workflow, Work Intake, Plugin) is unchanged;\nthis PRD is about how the *processes* running that domain logic get\npackaged, contracted, and discovered -- not about redrawing domain\nboundaries.\n\n### Target services\n\n| Service | Contract it owns | Existing code it replaces/wraps |\n|---|---|---|\n| UI Service | thin client only; talks to Gateway and State Store contracts | `internal/webui` (SPA hosting stays; API surface becomes typed contract clients, not a peer with direct access) |\n| Gateway Service | routing / turn / session contract | `internal/gateway` |\n| Messaging Service | channel-plugin contract (Telegram, email, Discord, Teams, ...) | `internal/channels` |\n| Curator Service | curator contract; **optional**, installs as a Gateway plugin | `internal/domain/curator` |\n| Scheduler Service | cron/ticker contract | `internal/domain/scheduling` |\n| Execution Environment | execution-dispatch contract | `internal/domain/workflow`, task dispatch paths |\n| Runner | isolated worktree/container execution | `internal/container`, `internal/agentexec`, `internal/worktree` |\n| State Store | state-access contract | `internal/store` |\n\n### Discovery\n\nPer `docs/inspiration/service-discovery-research-2026-09-05.md`:\n\n- **Primary:** Kubernetes-native discovery (Service + headless-Service/DNS\n + EndpointSlice, served by CoreDNS), delivered as a Helm chart + Operator,\n on k3s for single-host installs and a real cluster for multi-host or a\n hosted offering.\n- **Fallback:** NATS-based discovery (micro `$SRV` announce + JetStream KV\n registry) for no-K8s single-host installs, with a custom gRPC resolver\n reading `host:port` from the KV bucket.\n- Both implementations sit behind one internal interface:\n\n ```go\n type ServiceRegistry interface {\n Resolve(service string) []Endpoint\n Watch(service string) \u003c-chan Event // join/leave\n }\n ```\n\n- An optional service (Curator; others later) that is not installed\n must resolve to a distinct `NotInstalled` outcome, never a `Down`/\n `Unhealthy` one. Under K8s this falls out of DNS returning no record;\n under the NATS fallback it requires an explicit \"installed\" marker in the\n KV registry, not just absence-implies-down.\n\n### Distribution model this supports\n\nBoth self-hosted (customer runs the Helm chart or the NATS-fallback\nbinaries themselves) and a managed/hosted offering (we run the same Helm\nchart) are in scope -- this is the RHEL / Ansible Automation Platform\nmodel: one architecture, sold both ways. This PRD does not decide the\nbusiness model; it decides that the architecture must not foreclose\neither shape.\n\n## Why this shape\n\n`docs/inspiration/module-reference-awx-decomposition-vs-archie.md`\nestablished that Archie's existing domain split already does what AWX's\nservice-decomposition post argues for -- boundaries exist. What didn't\nexist was deployability: `internal/webui` was not a passive frontend. The\nre-baselined coupling inventory is below, and the ratified boundary is\n[`ui-service-boundary.md`](/dev/prds/ui-service-boundary/).\n\n- Telegram task actions now call Gateway's `ChatContract` directly through\n `chatTaskActorAdapter`; the old Telegram-to-webui HTTP detour is historical.\n- `internal/webui/api_chat.go` now holds `gateway.ChatContract`; direct\n `SessionStore`, `Router`, and `TurnHistory` access is historical.\n- The third coupling is closed. UI extraction shipped (`archie-core-8cda.5`,\n closed 2026-09-11): `cmd/archie-ui` serves the dashboard against remote\n Gateway and State Store contracts, holds no `config.Holder`, and relinks no\n daemon runtime (`cmd/archie-ui/architecture_test.go` enforces that on every\n `task check`). The `b.web.Cfg = b.d.Cfg` alias left in `buildDaemon` is now\n inside the daemon's own process -- it renders the published `ConfigView`\n snapshot and holds the readiness probes -- so it no longer crosses a service\n boundary. That cleanup is `archie-core-ml30` (P2); the UI boundary is\n ratified in [`ui-service-boundary.md`](/dev/prds/ui-service-boundary/).\n\n## Non-goals\n\n- Redesigning the domain model (Identity/Agent/Messaging/Workflow/Work\n Intake/Plugin boundaries are settled elsewhere and unchanged).\n- Replacing NATS. It remains the async transport; this PRD only adds gRPC\n for synchronous request/response and (optionally) K8s-native discovery.\n- Deciding the business model (self-hosted vs. managed vs. both). Kept\n open deliberately; the architecture must serve either.\n- Config relocation (`config.toml` -\u003e ConfigMaps/Secrets) is real work\n implied by a K8s-native deployment but is its own decision, not decided\n here. Flagged in the discovery research as a phased concern.\n- Any concrete adoption of Pi (or another external agent harness) as an\n execution runner. Raised in conversation alongside this decomposition,\n but it is a separate decision (agent execution as a strict data\n boundary, `docs/architecture/agent-system.md`) and does not gate or get gated by this PRD.\n\n## Open questions\n\nAll ten are resolved; each carries its resolution inline. Three phases have\nsince shipped against them (Gateway, State Store, UI), so the framing here is\nhistorical record rather than an outstanding gate.\n\n1. **Extraction order.** Which service gets pulled out of the monolith\n first? The webui entanglement findings above suggest Gateway Service's\n `ChatContract` should exist before UI Service is extracted, since UI is\n the most entangled consumer. Not yet sequenced.\n\n **RESOLVED.** Gateway Service first, then State Store,\n then UI, then Messaging, then Execution/Runner/Scheduler, then Curator\n (optional) — preceded by an in-process \"contract seams\" (modular\n monolith) phase. Confirms the hypothesis and strengthens it: the\n Gateway is already store-decoupled (it uses narrow contract adapters,\n not `internal/store`) and already owns an isolated session SQLite, so it\n is both the stickiest capability *and* the one with a ready seam and\n isolated data — extractable alone, first. Full phase list and reasoning:\n `docs/inspiration/service-decomposition-open-questions-research-2026-09-05.md#1`.\n2. **Contract definition mechanism.** Protobuf/gRPC service definitions\n need a home (a new `proto/` or `contracts/` tree, versioning scheme,\n codegen wiring into `Taskfile.yml`). Not yet designed.\n\n **RESOLVED.** buf v2 driving `protoc-gen-go` +\n `protoc-gen-go-grpc` (grpc-go, not connect-go — connect-go's net/http\n client breaks the discovery research's gRPC resolver plumbing for K8s\n DNS and NATS-KV). One committed `proto/\u003cservice\u003e/v1/` tree, generated\n Go committed to `internal/contracts/\u003cservice\u003e/v1/`, directory\n versioning (breaking change -\u003e new `vN`, enforced by `buf breaking` in\n the gate), and `task proto:generate`/`proto:lint`/`proto:check` wired\n into `task check` and mirrored into `.github/workflows/deploy.yml`\n (CI does not run `task check`). Full toolchain comparison, layout\n rationale, and scratch-verified `buf`/`buf breaking`/`connect-go`\n results:\n `docs/inspiration/service-decomposition-open-questions-research-2026-09-05.md#2`.\n3. **In-process vs. out-of-process during migration.** Whether services\n can run multiplexed inside one binary behind the same `ServiceRegistry`\n interface during a transition period (so extraction is incremental and\n testable) or whether each service must be a separate binary from day\n one. Strongly recommend the former for a solo maintainer, but not\n decided here.\n\n **RESOLVED.** Multiplexed in-process is the migration\n default -- this is `docs/architecture/organisation.md`'s standing\n \"Process boundaries\" rule, not a new lean. Mechanism: one wire-safe Go\n contract interface per service; a local adapter and a generated gRPC\n client adapter, both satisfying the same interface via a compile-time\n assertion (the `var _ workflow.Store = (*Client)(nil)` idiom;\n `store.WorkflowStore` is superseded by the consumer-owned\n `workflow.Store`); composition (not `ServiceRegistry`, which stays\n network-only) picks the adapter by the presence of a\n `[services.\u003cname\u003e].target` address -- empty = local (in-process) adapter,\n set = dial the remote gRPC client. This replaced the earlier\n `mode = \"inproc\" | \"remote\"` enum, which was dropped (see the gateway's\n `services.gateway.target`). The adapter is chosen by presence of the\n target; Phase 2 then deleted every local fallback, so remote is now the\n only mode and an empty `[services.state].target` is a startup error\n (docs/prds/state-store-contract.md §12 step 7). A\n per-contract conformance suite runs against both adapters over\n `bufconn`; the flip to a real process is a same-commit deletion of the\n in-process path, no dual-live window. Consequence: Gateway's Phase 0\n (`ChatContract` seam) ships in-process first, with the network protocol\n staying out of the production path until Phase 1 -- no amendment to Q1's\n phase list needed. Full mechanism and evidence:\n `docs/inspiration/service-decomposition-open-questions-research-2026-09-05.md#3`\n (the State Store's concrete ratified config shape is\n `docs/prds/state-store-contract.md` §10).\n4. **State Store's contract shape.** Whether every service gets its own\n storage (true microservice isolation) or several services share the\n State Store service's contract (less isolation, less migration risk).\n Not yet decided.\n\n **RESOLVED.** One State Store service owns the existing\n single SQLite file behind narrow typed contracts (`TaskStore`,\n `CaptureStore`, `MappingStore`, `BindingStore`, `WorkflowStore`) over\n gRPC. *(Ratified 2026-09-06: the workflow contract is now the\n domain-owned `workflow.Store`, which supersedes\n `internal/store`'s `WorkflowStore`. See note below and\n `docs/prds/state-store-contract.md`.)*\n No physical database-per-service: the solo-maintainer / team-\n topology rule of thumb plus the low value of per-service autonomy for\n one person rule it out, and one store means no distributed-transactions\n problem. The Gateway keeps its own already-separate session SQLite.\n Concrete migration path (generalise `storerpc`, swap consumers one\n contract at a time, stand up the store service, split the file only on\n evidence):\n `docs/inspiration/service-decomposition-open-questions-research-2026-09-05.md#4`.\n\n **RATIFIED (2026-09-06, beads archie-core-8cda.4.1).** The authoritative\n contract boundary \u0026 transport design for this is fixed in\n `docs/prds/state-store-contract.md` (rev. 2c): one `StateStore` gRPC service,\n 42 RPCs; **ownership split** — consumer-owned `workflow.Store` +\n `workflow.Task`/`Status`/`Source` in the workflow domain (dependency rules\n #2/#7), producer-owned daemon/webui store surfaces in `internal/store`;\n the `Task`/`Status`/`Source` + interface relocation is a Phase 2\n prerequisite pulled from migration-decisions §4 (`store.Task →\n WorkflowExecution`); `RecordDispatch` drops `*sql.Tx`; `Close` off-wire;\n structured gRPC error codes with sanitised details; explicit agent State\n Store gRPC handoff (`STATE_STORE_URL`/`STATE_STORE_TOKEN`); loopback+bearer\n transport-security boundary; presence-based `[services.state].target`\n defaulting local; migration order `workflow.Store -\u003e archie-state-store -\u003e\n Capture -\u003e Mapping -\u003e Binding -\u003e TaskStore`. `.4.2` and `.4.3` implement\n against that doc.\n5. **Helm chart / Operator ownership.** Net-new work with no existing\n analog in this repository (`deployments/` holds TOML profiles\n and a `docker-compose.yml`, not Kubernetes manifests). Scoping not yet\n started.\n\n **RESOLVED.** Three charts: an `archie-library` chart\n (shared Deployment/Service templates, named ports), an `archie` chart\n for the 7 core services, and an `archie-curator` chart + Curator\n Operator (CRD, controller, RBAC). The Curator reconciler is a\n level-triggered loop that fetches the CR, builds Deployment + Service,\n sets owner refs, applies idempotently (`CreateOrUpdate`), watches via\n `Owns()`, and reports a `Ready` status condition. Smallest real\n milestone (M1): install a Curator CR → Operator creates Deployment +\n Service → CoreDNS serves `curator` → Gateway's resolver flips it from\n `NotInstalled` to Installed with no redeploy; uninstall flips it back.\n Full scoping and first bead-issue list:\n `docs/inspiration/service-decomposition-open-questions-research-2026-09-05.md#5`.\n\n## Completion criteria\n\nNot applicable yet -- this PRD records the target shape and the discovery\ndecision. It does not authorize implementation. Before work begins: file\na beads epic, resolve the open questions above (at minimum #1-#3), and\nget explicit go-ahead given the scale of this change relative to\n`AGENTS.md`'s \"smallest workable change\" default for this solo project.\n" + "body": "# Service decomposition -- decision\n\n**Status:** Draft\n**Date:** 2026-09-05\n**Beads epic:** archie-core-8cda\n**Prior art:** `docs/inspiration/2026-09-05-awx-service-decomposition-and-ansible-task-model.md`,\n`docs/inspiration/module-reference-awx-decomposition-vs-archie.md`,\n`docs/inspiration/service-discovery-research-2026-09-05.md`,\n`/work/artefacts/archie-core-current-state-archify.html`,\n`/work/artefacts/archie-core-ideal-state-archify.html`\n\nThe Phase 3 UI boundary and configuration decision is ratified in\n[`ui-service-boundary.md`](/dev/prds/ui-service-boundary/). That focused document is\nthe implementation authority for `archie-core-8cda.5.2`; this parent remains\nthe broader service-distribution proposal.\n\n## Decision\n\narchie-core moves from one Go binary (`archied`) hosting every domain\nin-process to a set of independently deployable services, each exposing\nexactly one typed contract. Consumers depend on the contract; they never\nreach into another service's internal types, session state, or config.\ngRPC is the synchronous transport; NATS remains for asynchronous fan-out\n(status, telemetry) rather than being replaced.\n\nThis is a **distribution decision**, not a rewrite of Archie's domain\nmodel. The six-domain split already approved in\n`docs/architecture/index.md` and `docs/architecture/organisation.md`\n(Identity, Agent, Messaging, Workflow, Work Intake, Plugin) is unchanged;\nthis PRD is about how the *processes* running that domain logic get\npackaged, contracted, and discovered -- not about redrawing domain\nboundaries.\n\n### Target services\n\n| Service | Contract it owns | Existing code it replaces/wraps |\n|---|---|---|\n| UI Service | thin client only; talks to Gateway and State Store contracts | `internal/webui` (SPA hosting stays; API surface becomes typed contract clients, not a peer with direct access) |\n| Gateway Service | routing / turn / session contract | `internal/gateway` |\n| Messaging Service | channel-plugin contract (Telegram, email, Discord, Teams, ...) | `internal/channels` |\n| Curator Service | curator contract; **optional**, installs as a Gateway plugin | `internal/domain/curator` |\n| Scheduler Service | cron/ticker contract | `internal/domain/scheduling` |\n| Execution Environment | execution-dispatch contract | `internal/domain/workflow`, task dispatch paths |\n| Runner | isolated worktree/container execution | `internal/container`, `internal/agentexec`, `internal/worktree` |\n| State Store | state-access contract | `internal/infrastructure/postgres` |\n\n### Discovery\n\nPer `docs/inspiration/service-discovery-research-2026-09-05.md`:\n\n- **Primary:** Kubernetes-native discovery (Service + headless-Service/DNS\n + EndpointSlice, served by CoreDNS), delivered as a Helm chart + Operator,\n on k3s for single-host installs and a real cluster for multi-host or a\n hosted offering.\n- **Fallback:** NATS-based discovery (micro `$SRV` announce + JetStream KV\n registry) for no-K8s single-host installs, with a custom gRPC resolver\n reading `host:port` from the KV bucket.\n- Both implementations sit behind one internal interface:\n\n ```go\n type ServiceRegistry interface {\n Resolve(service string) []Endpoint\n Watch(service string) \u003c-chan Event // join/leave\n }\n ```\n\n- An optional service (Curator; others later) that is not installed\n must resolve to a distinct `NotInstalled` outcome, never a `Down`/\n `Unhealthy` one. Under K8s this falls out of DNS returning no record;\n under the NATS fallback it requires an explicit \"installed\" marker in the\n KV registry, not just absence-implies-down.\n\n### Distribution model this supports\n\nBoth self-hosted (customer runs the Helm chart or the NATS-fallback\nbinaries themselves) and a managed/hosted offering (we run the same Helm\nchart) are in scope -- this is the RHEL / Ansible Automation Platform\nmodel: one architecture, sold both ways. This PRD does not decide the\nbusiness model; it decides that the architecture must not foreclose\neither shape.\n\n## Why this shape\n\n`docs/inspiration/module-reference-awx-decomposition-vs-archie.md`\nestablished that Archie's existing domain split already does what AWX's\nservice-decomposition post argues for -- boundaries exist. What didn't\nexist was deployability: `internal/webui` was not a passive frontend. The\nre-baselined coupling inventory is below, and the ratified boundary is\n[`ui-service-boundary.md`](/dev/prds/ui-service-boundary/).\n\n- Telegram task actions now call Gateway's `ChatContract` directly through\n `chatTaskActorAdapter`; the old Telegram-to-webui HTTP detour is historical.\n- `internal/webui/api_chat.go` now holds `gateway.ChatContract`; direct\n `SessionStore`, `Router`, and `TurnHistory` access is historical.\n- The third coupling is closed. UI extraction shipped (`archie-core-8cda.5`,\n closed 2026-09-11): `cmd/archie-ui` serves the dashboard against remote\n Gateway and State Store contracts, holds no `config.Holder`, and relinks no\n daemon runtime (`cmd/archie-ui/architecture_test.go` enforces that on every\n `task check`). The `b.web.Cfg = b.d.Cfg` alias left in `buildDaemon` is now\n inside the daemon's own process -- it renders the published `ConfigView`\n snapshot and holds the readiness probes -- so it no longer crosses a service\n boundary. That cleanup is `archie-core-ml30` (P2); the UI boundary is\n ratified in [`ui-service-boundary.md`](/dev/prds/ui-service-boundary/).\n\n## Non-goals\n\n- Redesigning the domain model (Identity/Agent/Messaging/Workflow/Work\n Intake/Plugin boundaries are settled elsewhere and unchanged).\n- Replacing NATS. It remains the async transport; this PRD only adds gRPC\n for synchronous request/response and (optionally) K8s-native discovery.\n- Deciding the business model (self-hosted vs. managed vs. both). Kept\n open deliberately; the architecture must serve either.\n- Config relocation (`config.toml` -\u003e ConfigMaps/Secrets) is real work\n implied by a K8s-native deployment but is its own decision, not decided\n here. Flagged in the discovery research as a phased concern.\n- Any concrete adoption of Pi (or another external agent harness) as an\n execution runner. Raised in conversation alongside this decomposition,\n but it is a separate decision (agent execution as a strict data\n boundary, `docs/architecture/agent-system.md`) and does not gate or get gated by this PRD.\n\n## Open questions\n\nAll ten are resolved; each carries its resolution inline. Three phases have\nsince shipped against them (Gateway, State Store, UI), so the framing here is\nhistorical record rather than an outstanding gate.\n\n1. **Extraction order.** Which service gets pulled out of the monolith\n first? The webui entanglement findings above suggest Gateway Service's\n `ChatContract` should exist before UI Service is extracted, since UI is\n the most entangled consumer. Not yet sequenced.\n\n **RESOLVED.** Gateway Service first, then State Store,\n then UI, then Messaging, then Execution/Runner/Scheduler, then Curator\n (optional) — preceded by an in-process \"contract seams\" (modular\n monolith) phase. Confirms the hypothesis and strengthens it: the\n Gateway is already store-decoupled (it uses narrow contract adapters,\n not `internal/store`) and already owns an isolated session SQLite, so it\n is both the stickiest capability *and* the one with a ready seam and\n isolated data — extractable alone, first. Full phase list and reasoning:\n `docs/inspiration/service-decomposition-open-questions-research-2026-09-05.md#1`.\n2. **Contract definition mechanism.** Protobuf/gRPC service definitions\n need a home (a new `proto/` or `contracts/` tree, versioning scheme,\n codegen wiring into `Taskfile.yml`). Not yet designed.\n\n **RESOLVED.** buf v2 driving `protoc-gen-go` +\n `protoc-gen-go-grpc` (grpc-go, not connect-go — connect-go's net/http\n client breaks the discovery research's gRPC resolver plumbing for K8s\n DNS and NATS-KV). One committed `proto/\u003cservice\u003e/v1/` tree, generated\n Go committed to `internal/contracts/\u003cservice\u003e/v1/`, directory\n versioning (breaking change -\u003e new `vN`, enforced by `buf breaking` in\n the gate), and `task proto:generate`/`proto:lint`/`proto:check` wired\n into `task check` and mirrored into `.github/workflows/deploy.yml`\n (CI does not run `task check`). Full toolchain comparison, layout\n rationale, and scratch-verified `buf`/`buf breaking`/`connect-go`\n results:\n `docs/inspiration/service-decomposition-open-questions-research-2026-09-05.md#2`.\n3. **In-process vs. out-of-process during migration.** Whether services\n can run multiplexed inside one binary behind the same `ServiceRegistry`\n interface during a transition period (so extraction is incremental and\n testable) or whether each service must be a separate binary from day\n one. Strongly recommend the former for a solo maintainer, but not\n decided here.\n\n **RESOLVED.** Multiplexed in-process is the migration\n default -- this is `docs/architecture/organisation.md`'s standing\n \"Process boundaries\" rule, not a new lean. Mechanism: one wire-safe Go\n contract interface per service; a local adapter and a generated gRPC\n client adapter, both satisfying the same interface via a compile-time\n assertion (the `var _ workflow.Store = (*Client)(nil)` idiom;\n `store.WorkflowStore` is superseded by the consumer-owned\n `workflow.Store`); composition (not `ServiceRegistry`, which stays\n network-only) picks the adapter by the presence of a\n `[services.\u003cname\u003e].target` address -- empty = local (in-process) adapter,\n set = dial the remote gRPC client. This replaced the earlier\n `mode = \"inproc\" | \"remote\"` enum, which was dropped (see the gateway's\n `services.gateway.target`). The adapter is chosen by presence of the\n target; Phase 2 then deleted every local fallback, so remote is now the\n only mode and an empty `[services.state].target` is a startup error\n (docs/prds/state-store-contract.md §12 step 7). A\n per-contract conformance suite runs against both adapters over\n `bufconn`; the flip to a real process is a same-commit deletion of the\n in-process path, no dual-live window. Consequence: Gateway's Phase 0\n (`ChatContract` seam) ships in-process first, with the network protocol\n staying out of the production path until Phase 1 -- no amendment to Q1's\n phase list needed. Full mechanism and evidence:\n `docs/inspiration/service-decomposition-open-questions-research-2026-09-05.md#3`\n (the State Store's concrete ratified config shape is\n `docs/prds/state-store-contract.md` §10).\n4. **State Store's contract shape.** Whether every service gets its own\n storage (true microservice isolation) or several services share the\n State Store service's contract (less isolation, less migration risk).\n Not yet decided.\n\n **RESOLVED.** One State Store service owns the task data\n (now PostgreSQL, see `docs/prds/state-store-contract.md`) behind narrow typed contracts (`TaskStore`,\n `CaptureStore`, `MappingStore`, `BindingStore`, `WorkflowStore`) over\n gRPC. *(Ratified 2026-09-06: the workflow contract is now the\n domain-owned `workflow.Store`, which supersedes\n `internal/store`'s `WorkflowStore`. See note below and\n `docs/prds/state-store-contract.md`.)*\n No physical database-per-service: the solo-maintainer / team-\n topology rule of thumb plus the low value of per-service autonomy for\n one person rule it out, and one store means no distributed-transactions\n problem.\n Concrete migration path (generalise `storerpc`, swap consumers one\n contract at a time, stand up the store service, split the file only on\n evidence):\n `docs/inspiration/service-decomposition-open-questions-research-2026-09-05.md#4`.\n\n **RATIFIED (2026-09-06, beads archie-core-8cda.4.1).** The authoritative\n contract boundary \u0026 transport design for this is fixed in\n `docs/prds/state-store-contract.md` (rev. 2c): one `StateStore` gRPC service,\n 42 RPCs; **ownership split** — consumer-owned `workflow.Store` +\n `workflow.Task`/`Status`/`Source` in the workflow domain (dependency rules\n #2/#7), producer-owned daemon/webui store surfaces in `internal/domain/storecontract`;\n the `Task`/`Status`/`Source` + interface relocation is a Phase 2\n prerequisite pulled from migration-decisions §4 (`store.Task →\n WorkflowExecution`); `RecordDispatch` drops `*sql.Tx`; `Close` off-wire;\n structured gRPC error codes with sanitised details; explicit agent State\n Store gRPC handoff (`STATE_STORE_URL`/`STATE_STORE_TOKEN`); loopback+bearer\n transport-security boundary; presence-based `[services.state].target`\n defaulting local; migration order `workflow.Store -\u003e archie-state-store -\u003e\n Capture -\u003e Mapping -\u003e Binding -\u003e TaskStore`. `.4.2` and `.4.3` implement\n against that doc.\n5. **Helm chart / Operator ownership.** Net-new work with no existing\n analog in this repository (`deployments/` holds TOML profiles\n and a `docker-compose.yml`, not Kubernetes manifests). Scoping not yet\n started.\n\n **RESOLVED.** Three charts: an `archie-library` chart\n (shared Deployment/Service templates, named ports), an `archie` chart\n for the 7 core services, and an `archie-curator` chart + Curator\n Operator (CRD, controller, RBAC). The Curator reconciler is a\n level-triggered loop that fetches the CR, builds Deployment + Service,\n sets owner refs, applies idempotently (`CreateOrUpdate`), watches via\n `Owns()`, and reports a `Ready` status condition. Smallest real\n milestone (M1): install a Curator CR → Operator creates Deployment +\n Service → CoreDNS serves `curator` → Gateway's resolver flips it from\n `NotInstalled` to Installed with no redeploy; uninstall flips it back.\n Full scoping and first bead-issue list:\n `docs/inspiration/service-decomposition-open-questions-research-2026-09-05.md#5`.\n\n## Completion criteria\n\nNot applicable yet -- this PRD records the target shape and the discovery\ndecision. It does not authorize implementation. Before work begins: file\na beads epic, resolve the open questions above (at minimum #1-#3), and\nget explicit go-ahead given the scale of this change relative to\n`AGENTS.md`'s \"smallest workable change\" default for this solo project.\n" }, { "url": "/dev/prds/service-registry/", @@ -412,7 +412,7 @@ "url": "/dev/prds/state-store-contract/", "title": "State Store — contract boundary \u0026 transport (ratification)", "section": "PRDs", - "body": "# State Store — contract boundary \u0026 transport (ratification)\n\n**Status:** Approved\n**Revision:** 2e\n**Date:** 2026-09-06\n\nThis is the pre-implementation design document that Phase 2 subtasks `.4.2` (generalize\n`storerpc` as the State Store gRPC contract) and `.4.3` (stand up `archie-state-store`)\nimplement against.\n**Beads milestone:** archie-core-8cda.4.1\n**Parent:** `docs/prds/service-decomposition.md` (open-question Q4 **RESOLVED**)\n\nThis document fixes the **contract boundary** and **transport** for the State Store service.\nIt does not redesign Archie's domain model, does not invent a second store, and does **not**\nsplit `archie.db`. It records method ownership, DTO/wire representation, error semantics,\nlimits, mode/config shape, local-adapter compatibility, and cutover/deletion rules so that\n`.4.2` and `.4.3` have exactly one authoritative surface to build against.\n\n\u003e **Current state — read before `.4.2` starts.** The §12 step 2 relocation (`archie-core-8cda.\n\u003e 4.8`) has landed: `Task`/`Status*`/`Source*` and the 3-method `workflow.Store` now live in\n\u003e `internal/domain/workflow`, the six production workflow files import no `internal/store`\n\u003e symbol, and `storerpc`/the NATS transport assert against `workflow.Store` instead of\n\u003e `store.WorkflowStore`. The broader Phase 2 acceptance criterion (State Store as its own\n\u003e service behind gRPC) is still open — that is what `.4.2`/`.4.3` build next.\n\n\u003e **Relationship to migration-decisions §4 — not replaced.** `docs/architecture/\n\u003e migration-decisions.md` §4 (`store.Task → WorkflowExecution`, `mutable Stage →\n\u003e StepExecution history`, `RetryCount/Attempt → Attempt records`, versioned Workflow defs)\n\u003e **remains the authoritative, open document for the long-term Workflow migration.** This PRD\n\u003e does **not** replace it. It only pulls the minimal `Task`/`Status`/`Source` type + interface\n\u003e relocation forward as a Phase 2 prerequisite (because the acceptance criterion requires it);\n\u003e the rest of §4 stays its own migration and stays open.\n\n---\n\n## 1. Decision (the invariant everything follows)\n\nArchie is composed such that a single **`archie-state-store`** service owns the one existing\nSQLite file (`archie.db`) and exposes it over **gRPC behind narrow typed contracts**. There is\nexactly one store, one file, one service. No database-per-service, no distributed\ntransactions, no second store abstraction.\n\nTwo adapter families satisfy the contract interfaces:\n\n- **Local adapter** — `*store.Store` (the in-process SQLite implementation).\n- **Remote adapter** — `*staterpc.Client` (wraps the generated gRPC client).\n\nEach adapter carries an explicit compile-time assertion against the contract interfaces it\nserves. Composition picks local vs. remote by the presence of `[services.state].target`\n(empty = local; set = dial the gRPC service). Default is **local** (the State Store is not yet\nextracted), which is the PRD §3 posture; it differs from the gateway's remote-default only\nbecause the gateway is already a separate deployment and the State Store is not.\n\n\u003e **Contract-ownership fork, decided (rev. 2c — resolves the domain contradiction).**\n\u003e Ownership splits by the consumer's *layer*, per the dependency contract's rule #2\n\u003e (\"a domain defines the smallest interfaces required to perform its work\") and rule #7\n\u003e (\"database rows … MUST NOT leak into domain models\"):\n\u003e\n\u003e - The **workflow domain** (`internal/domain/workflow`) is the only domain-layer consumer of\n\u003e store state. It defines its own **consumer-owned** narrow `Store` interface\n\u003e (Update/Transition/InsertEvent) and its own **domain-owned** `Task` type plus\n\u003e `Status`/`Source` vocabulary. It imports **zero** `internal/store` symbols — satisfying the\n\u003e Phase 2 acceptance criterion. This is the minimal bound of migration-decisions §4\n\u003e (`store.Task → WorkflowExecution`), pulled forward **because** the acceptance criterion\n\u003e requires it.\n\u003e - The **daemon / webui / intake** store surfaces (`TaskStore`, `CaptureStore`,\n\u003e `MappingStore`, `BindingStore`, `BindingDispatcher`, `BindingTaskCreator`) stay\n\u003e **producer-owned** in `internal/store`, because those consumers are application and\n\u003e infrastructure layers, not domains — rule #2 does not apply to them.\n\nSo the State Store contract is **not** uniformly producer-owned: the domain-facing workflow\ncontract is consumer-owned (in the domain), while the daemon/webui store surfaces remain in\n`internal/store`. `internal/store` imports `internal/domain/workflow` for the `Task`/`Status`/\n`Source` types it persists (persistence → domain, the correct direction), and its `Store`\nimplementation satisfies `workflow.Store`. This is the single decision that makes the whole\nPhase 2 acceptance criterion and the architecture's rules simultaneously satisfiable.\n\n\u003e **`internal/store` is a TRANSITIONAL compatibility location (rev. 2c).** The repository's target\n\u003e architecture (`docs/architecture/dependencies-and-contracts.md`, `organisation.md`) places\n\u003e persistence implementations under `internal/infrastructure/\u003ccapability\u003e`. `internal/store`\n\u003e holding the task/capture/mapping/binding implementation and ALSO being the home of the\n\u003e producer-owned daemon/webui interfaces is acceptable **only as a transitional location**. The\n\u003e long-term home for the store implementation is `internal/infrastructure/store`; the\n\u003e producer-owned interfaces may move to the same infrastructure package (or an approved\n\u003e contract location) when the store implementation relocates. Agents must not treat\n\u003e `internal/store` as the final infrastructure boundary.\n\u003e\n\u003e **REV. 2d (archie-core-8cda.5.6): the producer-owned interfaces HAVE moved to an approved\n\u003e contract location** — `internal/domain/storecontract` (package `storecontract`), ahead of the\n\u003e store implementation's own relocation. The UI Service deletion gate required the archie-ui\n\u003e process to hold the contracts without linking `internal/store`'s SQL implementation, and\n\u003e `internal/contracts/` itself is ruled out: that tree is the `buf generate` output and\n\u003e `tools/proto.sh check` deletes hand-written files there. `internal/store` keeps type aliases\n\u003e (`type TaskStore = storecontract.TaskStore`, the sentinel `var`s, the value types) so\n\u003e daemon-side callers are unaffected; the sentinel message strings are unchanged and remain\n\u003e the wire contract (§4).\n\n---\n\n## 2. Contract boundary\n\n**Ownership split** (see the fork in §1): the **workflow-domain consumer contract** is\n`workflow.Store` (consumer-owned, in `internal/domain/workflow`); the **daemon/webui/intake\nstore surfaces** are the producer-owned interfaces in `internal/store/interface.go`.\n`store.WorkflowStore` is **superseded** — it is replaced by the domain-owned `workflow.Store`,\nand `internal/store`'s `Store` implementation satisfies `workflow.Store` directly. `TaskStore`\nremains the only composite; every other interface is flat. Narrow slices are split along\nconsumer-capability lines so no consumer acquires a surface it does not need\n(`interfacebloat` cap = 8).\n\n| Interface (owner) | Embeds | Methods | Local impl | Remote impl |\n|---|---|---|---|---|\n| `TaskStore` (store) | `TaskLifecycle`, `TaskEvents`, `TaskQueries`, `TaskArchiver`, `TaskRetryer` | 24 (union) | `*Store` | `*staterpc.Client` |\n| `TaskLifecycle` (store) | — | 8 | `*Store` | `*staterpc.Client` |\n| `TaskEvents` (store) | — | 7 | `*Store` | `*staterpc.Client` |\n| `TaskQueries` (store) | — | 7 | `*Store` | `*staterpc.Client` |\n| `TaskArchiver` (store) | — | 1 | `*Store` | `*staterpc.Client` |\n| `TaskRetryer` (store) | — | 1 | `*Store` | `*staterpc.Client` |\n| `workflow.Store` (workflow domain) | — | 3 | `*Store` | `*staterpc.Client` |\n| `CaptureStore` (store) | — | 2 | `*Store` | `*staterpc.Client` |\n| `MappingStore` (store) | — | 5 | `*Store` | `*staterpc.Client` |\n| `BindingStore` (store) | — | 6 | `*Store` | `*staterpc.Client` |\n| `BindingDispatcher` (store) | — | 3 | `*Store` | `*staterpc.Client` |\n| `BindingTaskCreator` (store) | — | 1 | `*Store` | `*staterpc.Client` |\n| `PlaybookDispatcher` (store) | — | 2 | `*Store` | `*staterpc.Client` |\n\n**Key property of the remote client:** `*staterpc.Client` is a *single* adapter that wraps one\n`StateStoreClient` and is asserted against **whichever narrow Go interfaces its caller needs**\n(exactly as `gatewayrpc.Client` asserts both `gateway.ChatContract` and\n`gateway.SessionStore`). The Go contracts stay narrow (≤8, the `interfacebloat` cap); the wire\nis one service. `workflow.Store` introduces **no new RPCs** — it is a narrow consumer face over\nthe same `Update`/`Transition`/`InsertEvent` RPCs.\n\n---\n\n## 3. Method ownership\n\n`*Store` remains the single implementation of the daemon/webui store surfaces and of\n`workflow.Store`. Ownership below is about which **process** is the primary consumer of each\nmethod and therefore which methods are genuinely cross-process on the wire vs.\ndaemon-internal.\n\nProcess legend: **DAEMON** = `archied` (incl. in-process webui + gateway runtime +\n`storerpc.Server`); **AGENT** = `archie-agent` worker (no DB connection); **GATEWAY** = store\naccess through daemon-side narrow adapter interfaces.\n\n| Contract | Primary consumers (process) | Remote on the wire? |\n|---|---|---|\n| `TaskLifecycle` (8) | DAEMON (dispatch, claim, action) + **AGENT** (`Transition`, `Update` via storerpc) | `Transition`/`Update` = **YES** (agent); rest DAEMON |\n| `TaskArchiver` (1) | DAEMON (`taskactions` archive) | not yet |\n| `TaskRetryer` (1) | DAEMON (`taskactions` retry) | not yet |\n| `TaskQueries` (7) | DAEMON + GATEWAY (status/list adapters) | not yet (`OpenPRs`/`Tasks`/`StatusCounts` cross to gateway adapters in-process) |\n| `TaskEvents` (7) | DAEMON + **AGENT** (`InsertEvent` via storerpc) | `InsertEvent` = **YES** (agent); rest DAEMON |\n| `workflow.Store` (3) | **AGENT** only | **YES** (the sole genuinely remote consumer) |\n| `CaptureStore` (2) | DAEMON (webhook intake + mapping editor) | not yet |\n| `MappingStore` (5) | DAEMON (dashboard editor + dispatch loop) | not yet |\n| `BindingStore` (6) | DAEMON (dashboard editor + dispatch loop) | not yet |\n| `BindingDispatcher` (3) | DAEMON (dispatch loop) | not yet |\n| `BindingTaskCreator` (1) | DAEMON (dispatch loop) | not yet |\n| `PlaybookDispatcher` (2) | DAEMON (EDA playbook dispatch loop) | **YES** (side-effecting-action idempotency ledger over gRPC) |\n\n**Consequence for migration order:** the **agent's `workflow.Store` is already cross-process\nalready** (via the NATS `storerpc` surrogate), so it is the first contract to move to gRPC. The\ndaemon-internal surfaces (`Capture`/`Mapping`/`Binding`) stay in-process until the daemon\nitself points at `archie-state-store`. `TaskStore` (the large composite) moves last.\n\n**Two orphan methods** — `TaskQueries.ClearTerminalTasks` and\n`TaskQueries.IncrementRetryCount` have **no production consumer** (only `*Store` tests). They\nremain part of the Go `TaskQueries`/`TaskStore` surface, and therefore part of the wire\ncontract, but are flagged for deletion: they must **not** gain dedicated consumers or wire\nmethods in this work. Do not add the rest of the codebase to them.\n\n---\n\n## 4. Domain-facing types \u0026 consumer-owned contract — resolves the contradiction\n\nThe Phase 2 acceptance criterion (\"`internal/domain/workflow` … no longer import\n`internal/store` directly — they call the State Store contract\") **cannot be met while**\n`store.Task`, `store.Status*`, `store.Source*`, and `store.WorkflowStore` live in\n`internal/store`. This section fixes where they move.\n\n**The relocation (a prerequisite that must land before or with `.4.2`):**\n\n| Current symbol (`internal/store`) | Moves to | Notes |\n|---|---|---|\n| `Task` type | `internal/domain/workflow.Task` | The task-execution record the workflow domain operates on. `internal/store` persists this type (persistence → domain). |\n| `Status` + `Status*` constants | `internal/domain/workflow` | e.g. `StatusClosedWontDo`, `StatusMerged`, `StatusPROpen`, `StatusWaitingHuman`, `StatusRunning` — task-lifecycle vocabulary. |\n| `Source` + `Source*` constants | `internal/domain/workflow` | e.g. `SourceChat` — provenance vocabulary, follows `Task`. |\n| `WorkflowStore` interface (3 methods) | `internal/domain/workflow.Store` | **Consumer-owned** (dependency rule #2). Supersedes `store.WorkflowStore`. |\n\n**Resulting dependency direction (correct per the architecture):**\n\n- `internal/domain/workflow` imports **no** `internal/store` symbols → the acceptance\n criterion is satisfied. It consumes `store.Task`'s replacement as `workflow.Task`, uses\n `workflow.Status*`/`workflow.Source*`, and depends on its own `workflow.Store` interface.\n- `internal/store` imports `internal/domain/workflow` for the `Task`/`Status`/`Source` types it\n reads and writes (infrastructure → domain). **NOTE: `internal/store` is a transitional\n compatibility location only** — its long-term home is `internal/infrastructure/store` (see\n the callout in §1). Do not treat `internal/store` as the final infrastructure boundary.\n- Every store test that constructs `store.Task{…}` is updated to the relocated type as part of\n this prerequisite. This is a mechanical rename across ~6 workflow production files\n (`workflow.go`, `steps.go`, `triage.go`, `review.go`, `feasibility.go`, `implement.go`) and\n their tests plus the store tests. `TestRecordDispatchViaExplicitTx` is removed rather than\n updated — its non-nil `*sql.Tx` path has no production consumer (see §5's `RecordDispatch`\n blocker).\n\n**What this does NOT do:** it does not implement the full §4 Workflow migration\n(`mutable Stage → StepExecution history`, `RetryCount/Attempt → Attempt records`,\n`workflow.Registry → versioned Workflow definitions`, etc.). It lands only the minimal\ntask-type + `Status`/`Source` + consumer-owned-interface relocation that the Phase 2\ndomain-decoupling criterion requires. The residue of §4 remains its own migration.\n\n**Forward-compatibility:** because the wire DTOs are derived from the domain `Task`/`Status`\n(§5), when the full §4 migration later renames `workflow.Task` (or refines it into\n`WorkflowExecution`), only `values.go` and the proto field mapping change — the RPC surface and\nconsumer interfaces are unaffected. The wire contract is deliberately type-agnostic at this\nlevel.\n\n---\n\n## 5. DTO / wire representation\n\n### Proto layout\n\n- **Service:** `proto/state/v1/state.proto`, `package state.v1`, **one** `StateStore` service\n (mirrors the gateway's single `ChatService`; proto bypasses the Go `interfacebloat` cap, as\n `ChatContract` does via `//nolint:interfacebloat`).\n- **Codegen:** the existing buf v2 pipeline. `proto/buf.yaml` (module, lint STANDARD, breaking\n FILE against `main`), `proto/buf.gen.yaml` **managed mode** with\n `go_package_prefix → github.com/samcharles93/archie-core/internal/contracts`, plugins\n `protoc-gen-go` + `protoc-gen-go-grpc`, `out: ../internal/contracts`,\n `opt: paths=source_relative`. **No `go_package` in source** — managed mode owns it. Generated\n Go lands in `internal/contracts/state/v1/` (package `statev1`), committed (`proto:check`\n fails on uncommitted/unmodified generated files).\n- **Adapter package:** `internal/infrastructure/staterpc/` with `server.go` (registers the\n generated server over the store), `client.go` (wraps the generated client into `store.*` and\n `workflow.Store` facades), `values.go` (proto ⇄ domain mappers), and `conformance_test.go`\n (bufconn local-vs-grpc dual-adapter suite), mirroring `internal/infrastructure/gatewayrpc/`.\n- **Binary:** `cmd/archie-state-store/main.go`, mirroring `cmd/archie-gateway/main.go` and the\n serve pattern in `internal/app/archied/gateway.go` (`serveGateway`).\n\n### The `StateStore` RPC set (union of the contracts, grouped)\n\nMethods are named after the store methods so the mapping is unambiguous. `workflow.Store` is a\n*view*, not new RPCs — `Update`/`Transition`/`InsertEvent` are shared with\n`TaskLifecycle`/`TaskEvents` and appear once.\n\n| Group | RPCs |\n|---|---|\n| Lifecycle | `EnqueueIssue`, `EnqueueChatTask`, `ClaimNext`, `ClaimByIssue`, `Transition`, `Update`, `Requeue`, `RecoverStale` |\n| Archive / Retry | `ArchiveTask`, `RetryTask` |\n| Queries | `TaskByIssue`, `OpenTaskByPR`, `TaskByID`, `OpenPRs`, `ClearTerminalTasks`, `Tasks`, `StatusCounts`, `IncrementRetryCount` |\n| Events | `InsertEvent`, `EventsSince`, `TaskEvents`, `WorkflowStats`, `StageStats`, `TokensByDay` |\n| Capture | `InsertCapture`, `ListCaptures` |\n| Mapping | `InsertMapping`, `GetMapping`, `ListMappings`, `UpdateMapping`, `DeleteMapping` |\n| Binding | `InsertBinding`, `GetBinding`, `ListBindings`, `UpdateBinding`, `DeleteBinding`, `ApproveBinding` |\n| Dispatch | `ArmedBindingsForSource`, `RecordDispatch`, `ListUndispatchedCaptures` |\n| Playbook | `RecordPlaybookDispatch`, `DeletePlaybookDispatches` |\n| BindingTaskCreator | `EnqueueBindingTask` |\n| Config snapshot | `PutConfigSnapshot`, `GetConfigSnapshot` |\n| Apply status | `PutApplyStatus`, `ListApplyStatus` |\n| Channel status | `PutChannelStatus`, `ListChannelStatus` |\n| Task log | `ReadTaskLog`, `StreamTaskLogContent` |\n\nThat is **51 unique contract RPCs** across one service (the `TaskEvents.Close` method is dropped).\n`Close()` is **excluded** from the wire (it is server lifecycle, not a client call) — see §11.\n\nThe channel-status pair follows the config snapshot's split for the same reason: the writer is the process that HOSTS the channels -- the Messaging Service, which alone observes whether a channel is starting, running or failed -- and the reader is the UI process. Both RPCs are administrative, so a task-scoped grant reaches neither. A channel's state is runtime state rather than a settings document, which is why it is not a `ControlPlaneService` resource kind: a failed channel is not a document anybody edits. Asking for a reload travels on its own surface rather than through this one; see `docs/architecture/migration-decisions.md`, \"Channel state to the dashboard\".\n\nThe config-snapshot pair was added by `archie-core-ymut` (see\n`docs/architecture/migration-decisions.md`, \"Dashboard configuration page\"). It is the one\nsurface whose writer is the daemon and whose reader is the UI process, and both RPCs are\nadministrative: `authorizesTaskScopedCall` is deny-by-default, so a task-scoped grant reaches\nneither. `ConfigSnapshot.document` is opaque to this contract — the store neither parses nor\nvalidates it, and `schema` names the projection so a reader can refuse a shape it does not\nunderstand.\n\nThe apply-status pair was added by `archie-core-pskb` (see\n`docs/prds/control-plane-apply-status.md`). It is administrative for the same reason as the\nconfig-snapshot pair, and deny-by-default in `authorizesTaskScopedCall` covers it without a\nnew rule. Unlike that pair, the read is a list: `ListApplyStatus` returns every process's\nrecord and an empty slice means nothing has reported yet, so the `found=false` convention for\nabsent single rows does not apply. The rows are keyed on `(process, kind)` and replaced in\nplace, because each process re-stamps its record on an interval and no reader wants a history\nof re-stamps.\n\nThe task-log pair was added by `archie-core-iaqx` (see `docs/prds/ui-service-boundary.md`'s\nroute inventory). It is the one surface whose payload is not a row: the store service reads\nthem out of the state directory it owns with `internal/logging`'s own reader, so the wire\ncarries `logging.Entry`/`logging.Query` values and neither side restates the JSONL format.\n`ReadTaskLog` returns a decoded page and `StreamTaskLogContent` returns the raw bytes\nserver-streamed, because a log file rotates at 20 MB — past gRPC's 4 MiB unary cap — and the\nsame reasoning that made `StreamCaptures` supersede `ListCaptures` applies. `found=false` with\nno error means the attempt has no log; a service with no reader answers `Unavailable` instead,\nand the two answers are load-bearing for the dashboard: only the second is a deployment\ncondition, and the panel that collapsed them told operators task logging was switched off when\nit was not. The Go facade is `storecontract.TaskLogStore` (2 methods), carried by\n`*staterpc.Client` alongside the rest.\n\nThe playbook pair was added by `archie-core-t2db.17`'s implementation (see\n`docs/prds/eda-playbook-engine.md`, execution-time gap 2). It is administrative\nfor the same reason as the config-snapshot and apply-status pairs, and\ndeny-by-default in `authorizesTaskScopedCall` covers it without a new rule. The\nrow is the structural `(playbook_id, playbook_version, event_id, action_id)`\ntuple, written **before** the action's side effect fires (the reverse of\n`binding_dispatches`), so a duplicate returns `store.ErrAlreadyDispatched` and\nthe coordinator skips the invoke rather than repeating a non-revocable side\neffect. `DeletePlaybookDispatches` is the explicit reclamation primitive; nothing\ncalls it automatically, because a playbook file's absence at boot is not a\ndeliberate removal (`eda-playbook-engine.md`, \"Lifetime\"). The Go facade is\n`storecontract.PlaybookDispatcher` (2 methods), carried by `*staterpc.Client`\nalongside the rest.\n\n### Domain types and `values.go` mapping\n\n`values.go` maps proto ⇄ these types. The task model for the **agent** path is the domain-owned\n`workflow.Task` (§4); the daemon/webui store surfaces return the same `workflow.Task` (the store\npersists the domain type).\n\n| Domain type | Package | Notes for `values.go` |\n|---|---|---|\n| `workflow.Task` | `internal/domain/workflow` | time fields stored as layout strings; convert to/from `google.protobuf.Timestamp` |\n| `events.Event` | `internal/events` | `Timestamp` → `google.protobuf.Timestamp` |\n| `store.CapturedEvent` | `internal/store` | headers/body/remote_addr; body capped 256 KiB |\n| `mapping.Mapping` | `internal/domain/mapping` | JSON-path field bindings |\n| `binding.Binding` | `internal/domain/binding` | secret is **already decrypted** before returning; keep decrypted form out of any durable/logged representation |\n| `workflow.Status` / `workflow.Source` | `internal/domain/workflow` | enum-like; map to proto enum or string, keeping the names stable for compatibility |\n| `store.WorkflowStat` | `internal/store` | aggregate row |\n| `store.StageStat` | `internal/store` | aggregate row |\n| `store.DayTokens` | `internal/store` | aggregate row |\n\n### Wire-contract blocker fixed here: `RecordDispatch`\n\n`store.BindingDispatcher.RecordDispatch(ctx, tx *sql.Tx, bindingID, bindingVersion int64,\ncaptureID int64, taskID int64) error` takes a **`*sql.Tx`** that cannot cross a gRPC boundary.\n\n**Evidence that the `*sql.Tx` is removable:** the dispatch loop calls `RecordDispatch(ctx, nil,\n…)` (`internal/daemon/daemon.go`). The implementation falls back to the store's own\n`*sql.DB` when `tx == nil` (\"best-effort, not atomic\"; the comment and the\n`TestRecordDispatchViaExplicitTx` test are the only consumers of the non-nil `tx` path).\nProduction never opens the explicit transaction.\n\n**Decision:** the contract drops `*sql.Tx` from `RecordDispatch` (the method becomes\n`RecordDispatch(ctx, bindingID, bindingVersion, captureID, taskID) error`). The store service\nowns any transaction boundary internally when atomicity is wanted; the at-most-once\nguarantee is the `INSERT OR IGNORE` dedup row, which is already transactionless in production.\n`TestRecordDispatchViaExplicitTx` is superseded by the store service's own internal-transaction\ntest. **This is a required interface migration that must land before or with `.4.2`** (the\ncurrent `interface.go` signature and test still use the transaction-bearing form).\n\n---\n\n## 6. Agent State Store client handoff\n\nMoving the agent from NATS `storerpc` to gRPC `workflow.Store` requires the agent process to\nreceive a State Store endpoint. The agent already receives its NATS connection settings via\nboot-time env/flags (see `cmd/archie-agent/main.go`: `-nats-url` / `NATS_URL`, `NATS_TOKEN`\nenv), and the daemon injects them into the task container. The State Store handoff follows the\nsame seam.\n\n**Boot handoff contract (additive, not replacing the NATS settings):**\n\n| Field | Where | Source | Notes |\n|---|---|---|---|\n| `StateStoreTarget` | `agentworker.Settings` | env `STATE_STORE_URL` (or `-state-store-url` flag), set by the daemon in the container env | `host:port` of the State Store gRPC server. Loopback/Docker-bridge address — the agent reaches it the same way it reaches the daemon's NATS. |\n| `StateStoreToken` | `agentworker.Settings` | env `STATE_STORE_TOKEN` (or `-state-store-token` flag) | Per-task bearer token carried in gRPC metadata by a client interceptor (see §9). |\n| `StoreTimeout` | `agentworker.Settings` | a bounded per-call timeout | Mirrors `natsrpc.Client.Timeout` / the existing `rpcTimeout`; bounds each State Store call when the caller `ctx` has no deadline. |\n\n**Wiring change in the transport façade:**\n\n- `internal/infrastructure/agenttransport/nats.Transport` — `Store(timeout) store.WorkflowStore`\n returns `\u0026storerpc.Client{Conn: t.conn, Timeout: timeout}`. It becomes\n `Store(timeout) workflow.Store` and returns a *single long-lived* `staterpc.Client` dialed to\n `settings.StateStoreTarget` (with the token interceptor and per-call timeout).\n- `internal/app/agentworker/worker.go` `Settings` gains the three fields above; `taskServiceTransport`\n and `taskDependencies` change their `store` type from `store.WorkflowStore` to\n `workflow.Store` (via `domain/workflow.TaskContext{Store: …}`).\n- Reconnect/deadline: `grpc.NewClient` (or the existing dial path) provides transparent reconnect;\n each RPC is bounded by the per-call context deadline (`StoreTimeout`), matching the\n request/reply timeout the NATS path used. No streaming is involved, so no server-sent\n reconnect semantics apply.\n\n**Deletion rule for the NATS path:** the NATS `storerpc` (Server, Client, subjects\n`archie.store.update|transition|insert_event`) is deleted **only after** the agent has fully\nmoved to gRPC and the container env carries `STATE_STORE_URL`. Until then both paths may coexist\n(agent flips when the daemon starts injecting `STATE_STORE_URL`); there is no dual-live window\nacross a single agent process, which is either NATS-backed or gRPC-backed, never both.\n\n### Operational specifics (in-process listener → address → per-task injection)\n\n- **Who binds the in-process State Store listener:** the daemon (`archied`), at bootstrap, when\n the State Store is served in-process/multiplexed (mirroring `serveGateway` in\n `internal/app/archied/gateway.go`): a `grpc.NewServer()` + `RegisterServer` + graceful stop on\n `ctx.Done()`.\n- **Address selection (Docker-bridge reachable):** reuse the host-gateway resolution already used\n for embedded NATS (`internal/container/network.go` `RequireHostGateway` /\n `resolveHostGateway`). Per §9's single listener-topology rule, the listener binds the\n **host-gateway bridge address** when agent containers consume it (the Phase 2 default), or\n loopback-only when the daemon is the sole consumer. The chosen address is stored on the daemon\n as `d.ConnectedStateStore.URL` (analogous to `d.ConnectedNATS.URL`).\n- **Per-task injection:** `containerEnv(task)` (`internal/daemon/daemon.go`) appends\n `STATE_STORE_URL=\u003cd.ConnectedStateStore.URL\u003e` and `STATE_STORE_TOKEN=\u003ctoken\u003e` alongside the\n existing `NATS_URL`/`NATS_TOKEN`. The agent reads them via env (`-state-store-url` /\n `STATE_STORE_URL`, `-state-store-token` / `STATE_STORE_TOKEN`), the same seam as `NATS_URL`. A\n reloaded `[services.state]` must not point new containers at a store the daemon is not serving\n — the same immutability rule as NATS.\n\n---\n\n## 7. Error semantics\n\n### Current state (both boundaries lose error identity)\n\n- **NATS `natsrpc.Envelope`** (`internal/natsrpc/natsrpc.go`) serialises any error to a single\n `err.Error()` string and rehydrates a fresh `errors.New(string)`. The original type, `%w`\n chain, and sentinel identity are lost → `errors.Is(err, store.ErrStaleTransition)` is\n **false** across the boundary.\n- **gRPC `gatewayrpc`** returns raw `err` from handlers; gRPC-Go converts to\n `codes.Unknown` with only the message. The **only** explicit code in the repo is\n `codes.Unavailable` for a missing session store (`server.go`). No status-code mapping for\n store errors exists.\n\n### Decision — structured mapping so `errors.Is` survives\n\nThe `StateStore` service must map the store's sentinel errors to canonical gRPC codes and\nrehydrate them to the *same* sentinels on the client, so consumer `errors.Is` checks keep\nworking — an improvement over the flattening it replaces, not a regression.\n\n| Store sentinel / outcome | gRPC code | Client rehydrates to |\n|---|---|---|\n| `store.ErrStaleTransition` | `FailedPrecondition` | `store.ErrStaleTransition` |\n| `store.ErrBindingNotFound` | `NotFound` | `store.ErrBindingNotFound` |\n| `store.ErrMappingNotFound` | `NotFound` | `store.ErrMappingNotFound` |\n| `store.ErrBindingOverlap` | `FailedPrecondition` | `store.ErrBindingOverlap` |\n| `store.ErrBindingTransition` | `FailedPrecondition` | `store.ErrBindingTransition` |\n| `store.ErrAlreadyDispatched` | `AlreadyExists` | `store.ErrAlreadyDispatched` |\n| not-found-as-`(nil,nil)` (`TaskByID`, `GetBinding`, `GetMapping`, `ClaimNext`, `ClaimByIssue`, …) | `NotFound` with a `found=false` field (**not** an error) | `(nil, nil)` |\n| infra / wrapped error | `Internal` (**sanitised** message, see below) | wrapped `fmt.Errorf(...%w)` |\n| capability absent | `Unavailable` | context/typed error |\n\nThe `found=false`-not-error convention matters: the repo deliberately returns `(nil, nil)` for\nnot-found in reads and a sentinel for not-found in writes. The wire must preserve **both**\nconventions (a `GoogleRPCStatus` with `NotFound` is an *error*, which would wrongly surface to\ncallers that expect `(nil, nil)`). Implement `found` as an explicit boolean field on read\nresponses, and map `(nil,nil)` ⇄ `found=false` + `OK`.\n\n### Error-detail sanitisation (rev. 2c)\n\nFull internal error messages must **not** be placed in gRPC `details` for remote callers. SQL\npaths, provider/forge details, secrets, and stack traces are sensitive internals. The rule:\n\n- **Sentinel errors** — the client rehydrates the sentinel from the code; the message string in\n `status.Error` is a short, public, stable phrase (e.g. `\"stale transition\"`), not the raw\n wrapped chain.\n- **Infra errors** — the wire carries a **sanitised** public message + the `Internal` code.\n The **full** error (with `%w` chain, SQL, provider detail) is logged **server-side only** by\n the store service. The client rehydrates a generic wrapped error and must not surface the raw\n text to users.\n\n---\n\n## 8. Limits\n\n**Interface bloat (`interfacebloat` cap = 8)** — `.golangci.yml` `interfacebloat: max: 8`,\nwhich overrides the upstream default of 10. The Go consumer facades must stay ≤8 methods.\n`TaskLifecycle` is exactly 8 (at the cap); `TaskStore` is the 24-method composite that the cap\nis why it is decomposed; proto services bypass the cap (like `ChatContract`).\n\n**Payload caps:**\n- Capture body: `defaultCaptureMaxBodyBytes = 256 KiB` (may reduce further; the wire message\n must not exceed gRPC's default 4 MiB receive limit for a single capture). A single capture\n fits, but a *batch* of them did not: the caller-side cap of up to 100 captures at 256 KiB each\n could exceed 4 MiB in one unary `ListCaptures`/`ListUndispatchedCaptures` response. `.4.7` adds\n `StreamCaptures`/`StreamUndispatchedCaptures` (server-streaming, one capture per message) as\n the path both `staterpc.Client` methods actually call; the original unary RPCs stay defined,\n unmodified and deprecated, only so `buf breaking` protects an in-flight rolling deploy.\n- Task `detail`/`park_reason`/event `Detail`: 4000-char hard cap (`clip(s, 4000)`).\n\n**Retention (stays server-side in the store; the wire does not carry pruning decisions):**\n- `events` table: **no prune, unbounded growth** — a known risk to revisit, not changed here.\n- `captured_events`: prune-on-write, default 7 days / 5000 events.\n\n**Pagination/arity:** store read methods take a raw `int limit` (no store-side cap); the\ncaller-side caps (task list 100, log 2000, captures 100, capture scan window 5000, binding\ndispatch batch 100, session list 20) remain caller-side. The wire passes `limit int` and returns\n`[]*` slices, mirroring the existing Go signatures — **no cursor/paging protocol is introduced**\nin this work (the current `EventsSince(sinceID, limit)` offset cursor is the only one, and it\nstays as-is).\n\n---\n\n## 9. Transport security boundary\n\nThe gateway precedent is loopback-only, unauthenticated gRPC. The State Store holds the\ncrown-jewel `archie.db` (task/event/capture/mapping/binding data), so its boundary must be\nstated explicitly rather than left implicit.\n\n**The State Store's equivalent boundary (rev. 2c):**\n\n- **Listener topology — single rule (rev. 2c).** One in-process listener; its bind address is\n chosen by the consumer set, never both at once:\n - *Agent containers consume it* (the Phase 2 driver during multiplexed serving) → bind to the\n **host-gateway bridge address** so containers can reach it, and **token auth is mandatory**\n (a bridge host is reachable by any process on that bridge). A container **cannot reach the\n host's `127.0.0.1`**, so loopback-only is NOT usable for the agent-consumed path.\n - *Only the daemon consumes it* (no agent) → bind **loopback-only** (`--listen 127.0.0.1`),\n `insecure` is fine because it is not network-reachable; no token required.\n - There is **no dual-listener** design. The practical default during `.4.2` (the reason\n in-process serving exists is to give the agent a gRPC target) is the **bridge address +\n token**. `127.0.0.1` is reserved for the daemon-local-only case.\n- **Agent access → the container bridge.** The agent runs in a task-scoped container on the\n host and reaches the State Store over the Docker bridge gateway (the bind address from the\n topology rule above), exactly as it reaches the daemon's NATS. To close the \"any host\n process could reach the store\" gap, the agent **authenticates with a per-task bearer token**\n carried in gRPC metadata by a client interceptor (`StateStoreToken`, §6). Network\n reachability + the token is the trust boundary for the default bridge topology.\n- **The daemon** uses the local adapter (`*store.Store`) in-process by default, so no network\n boundary exists until `[services.state].target` is set; when it is set, the daemon client\n authenticates with a token supplied alongside the target.\n- **Non-loopback / k8s:** TLS/mTLS is an **operator decision**, not a default. Any non-loopback\n exposure (e.g. `--listen 0.0.0.0`, a CDN, a cross-host service) requires an explicit decision\n and mTLS or token auth — mirroring the gateway's `--listen`/`--enable-cors-header`\n confirmation caveat. The NATS-KV discovery fallback supplies endpoints but does not add\n transport security; that stays the operator's responsibility.\n\n### Token lifecycle (rev. 2c; scoping added in `.4.7`)\n\n- **Generation:** the daemon generates a per-task bearer token when it acquires the container\n (or per incumbence) and injects it via `containerEnv` as `STATE_STORE_TOKEN`. A single token\n may cover a task's container lifetime.\n- **Registration (`.4.7`, post-standalone-cutover):** the State Store is now its own process\n (`.4.3`/`.4.6`), so the daemon can no longer just hold an in-process issued-token set for the\n server to check — it registers the token at the remote authority via the\n `RegisterTaskGrant`/`RevokeTaskGrant` RPCs (`staterpc.GrantIssuer`, `daemon.StateStoreGrantIssuer`),\n admin-token-authenticated calls a task-scoped token itself can never make.\n- **Lifetime:** tied to the task + container grace period; rotated on a new container acquisition\n for the same task; a token for a released container is invalidated (`RevokeTaskGrant`, deferred\n alongside `ContainerPool.Release`). An unrevoked grant still expires server-side (bounded by\n `RegisterTaskGrantRequest.lifetime_seconds`, capped at 7 days) so a daemon crash before revoke\n cannot leave a grant valid indefinitely.\n- **Validation and scope (`.4.7`):** a gRPC interceptor (`staterpc.TaskGrants.UnaryInterceptor`)\n validates the token against the State Store's own issued-grant set; missing/unknown/expired →\n `codes.Unauthenticated`. Unlike the daemon's own administrative token (full access to all ~40\n RPCs), a task-scoped grant additionally authorizes only `Update`/`Transition`/`InsertEvent` on\n its own task ID — every other RPC, including the streaming capture surface and\n `RegisterTaskGrant`/`RevokeTaskGrant` themselves, is `codes.PermissionDenied` for a task-scoped\n caller. The token is carried in gRPC metadata, never in a URL.\n\n### Fail-closed on non-loopback (rev. 2c)\n\nIf `[services.state].target` points to a non-loopback address and **neither** TLS **nor** a token\nis configured, the State Store client (daemon or agent) **fails closed** — it refuses to\nstart/dial rather than fall back to a plaintext, unauthenticated remote connection. This mirrors\nthe gateway's `--listen`/`--enable-cors-header` confinement caveat and prevents a silent\nunauthenticated remote store. The loopback + token default is the only path that starts without\nan explicit operator decision.\n\n---\n\n## 10. Mode / config shape\n\n**Follow the gateway's presence-based `target` seam, not the NATS `mode` enum.**\n\n- **Services are keyed by name, not named as struct fields.** A\n `State ServiceConnection` field per service is the duplication\n `docs/prds/service-registry.md` removes, and this document's summary describes\n the seam as `[services.\u003cname\u003e]`:\n ```go\n type Services map[string]ServiceConnection\n ```\n registered once via `RegisterService(context, name, target, listen, tokenEnv)`. The TOML\n shape below is unchanged, so nothing else in this section is affected; read\n `cfg.Services.Get(\"state\")` wherever it says `cfg.Services.State`.\n- **Empty `Target` → startup error.** The local `*store.Store` adapter default was\n withdrawn when the State Store was extracted (§12 step 7): the standalone `archie-state-store` process\n exclusively owns `archie.db`, so both `archied` and `archie-gateway` now reject an empty\n target (`internal/app/archied/bootstrap.go` and `state_store_client.go`: `services.state.target\n is required`). **Set `Target` → dial gRPC** with `*staterpc.Client`; no client opens the\n database itself. This differs from the gateway, where `Target` is defaulted to\n `127.0.0.1:8585` because `archie-gateway` is already a separate process whose client and\n server share one default.\n- `[services.state]` is present and **uncommented** in `config.example.toml`, with `target`\n marked REQUIRED, because the value is load-bearing for every client. A commented-out\n `target` cannot boot, so the section ships uncommented.\n- Composition root: `internal/app/archied/bootstrap.go` (the daemon) and\n `internal/app/archieui/config.go` (the UI process) both read `cfg.Services.Get(\"state\")` and\n dial the remote State Store. `openProductionTaskStore` is **not** called from the daemon: it\n lives in the standalone `archie-state-store` process (`internal/app/archied/state_store.go`),\n which is the only path that opens `archie.db`.\n\n\u003e **Mode fork, decided.** The gateway uses a single `target` address (no enum). The State Store\n\u003e boundary uses the same seam for symmetry, and **both now require a non-empty `target`**: the\n\u003e State Store's local-store default was withdrawn when the process was extracted (§12 step 7).\n\u003e No `mode` field is added. A companion `STATE_STORE_TOKEN` secret (or a\n\u003e `[services.state] target_token` key) carries authentication.\n\n---\n\n## 11. Local-adapter compatibility + conformance\n\n- `*store.Store` (local) and `*staterpc.Client` (remote) satisfy the **same** contract\n interfaces. Use **explicit** `var _` assertions on **both** adapters (the gateway's local\n adapters use only structural/return-type assertions; the store precedent's explicit `var _`\n style is stronger and should be adopted on both sides).\n ```go\n var _ workflow.Store = (*staterpc.Client)(nil) // first contract to move (agent)\n var _ store.TaskStore = (*staterpc.Client)(nil) // daemon path, added progressively\n var _ store.CaptureStore = (*staterpc.Client)(nil)\n var _ store.MappingStore = (*staterpc.Client)(nil)\n var _ store.BindingStore = (*staterpc.Client)(nil)\n var _ store.BindingDispatcher = (*staterpc.Client)(nil)\n var _ store.BindingTaskCreator = (*staterpc.Client)(nil)\n var _ store.PlaybookDispatcher = (*staterpc.Client)(nil)\n // local side (in store), already present:\n var _ workflow.Store = (*Store)(nil)\n ```\n- **Conformance suite:** a `staterpc/conformance_test.go` bufconn suite runs the **same**\n contract through both `\"local\"` and `\"grpc\"` adapters (mirroring\n `gatewayrpc/conformance_test.go`), asserting error-sentinel fidelity and the\n not-found-as-`(nil,nil)` convention both ways.\n- **`Close()`:** stays on the Go store interfaces (so `TaskStore`/`TaskEvents` remain fully\n satisfiable) but is **not** a `StateStore` RPC. The remote `staterpc.Client` implements\n `Close()` as a **no-op**; the store service owns its own DB lifecycle. When the daemon hands\n the store to `archie-state-store`, `b.cleanup()` no longer calls `store.Close()` on a remote\n client (it is the daemon's own lifecycle only when it owns the store in-process).\n\n---\n\n## 12. Cutover / deletion rules\n\n1. **Ratify the contract (this document).** No code.\n2. **Domain type + interface relocation (prerequisite, coupled with §4).** Move `Task`/`Status`/\n `Source` and the `WorkflowStore` interface into `internal/domain/workflow` (as\n `workflow.Task`/`workflow.Status`/`workflow.Source`/`workflow.Store`), so\n `internal/domain/workflow` imports no `internal/store`. Update the store tests and the 6\n workflow production files. **This must land before or with `.4.2`, because `.4.2` cannot move\n the agent's store contract off `store.WorkflowStore` while the domain still imports it.**\n3. **`.4.2` — generalize `storerpc` to the gRPC contract.** Move the agent's `workflow.Store`\n (`Update`/`Transition`/`InsertEvent`) from NATS JSON `storerpc` to `staterpc.Client` over\n gRPC, using the §6 handoff. The daemon serves the gRPC `StateStore` server **in-process\n (multiplexed)** first so the agent has a gRPC target before the standalone binary exists\n (PRD §3 \"multiplexed in-process is the migration default\"). Bind the in-process listener and\n inject `STATE_STORE_URL`/`STATE_STORE_TOKEN` per task (see §6 \"Operational specifics\"). Also\n land the `RecordDispatch` `*sql.Tx` drop (see §5) in the same span. Flip the agent's\n `Transport.Store` to a gRPC client once `STATE_STORE_URL` is injected.\n4. **Delete NATS `storerpc` only after the agent is fully on gRPC** — delete `internal/storerpc`\n (Server, Client, subjects `archie.store.update|transition|insert_event`), the\n `natsrpc.RegisterAll` registration, and the now-unused `store.WorkflowStore` NATS path in\n `internal/infrastructure/agenttransport/nats`, in the same commit.\n5. **`[services.state].target` stays empty (inproc)** through `.4.2`; the `archie-state-store`\n `cmd/` binary is **`.4.3`** and hosts the same `StateStore` gRPC service.\n6. **Swap daemon-internal contracts one at a time** (only once the daemon points at\n `archie-state-store`): `Capture → Mapping → Binding → TaskStore`. Each swap is independent —\n add the remote-client composition path, run the per-contract conformance suite, flip\n `[services.state].target`, delete the local use. A consumer mixes in-process and remote\n contracts for a contract-code (no dual-live *window*; each contract is either local or remote\n at a time).\n7. **Final flip / deletion of the in-process serving path:** when the daemon no longer owns the\n store (i.e. `TaskStore` has moved), delete the in-process `openProductionTaskStore` /\n `wireWebStoreSurfaces` path in the daemon in a **same-commit** deletion — no dual-store\n ownership. The single SQLite file remains owned by `archie-state-store`.\n8. **Never** split `archie.db` or add a second store. The gateway keeps its own already-separate\n session SQLite; that is unchanged and out of state-store scope.\n\n---\n\n## 13. Decisions recorded (for the review trail)\n\n- **`internal/store` is a transitional compatibility location** (target\n `internal/infrastructure/store`), not the final infrastructure boundary. The producer-owned\n daemon/webui store surfaces live there now but may relocate with the implementation.\n- **In-process listener + token lifecycle:** the daemon binds the in-process State Store\n listener to the **host-gateway bridge address** when agent containers consume it (the Phase 2\n default) or loopback-only when the daemon is the sole consumer — one listener, one address\n rule, never both (rev. 2c). It selects the bridge address by reusing the embedded-NATS\n host-gateway resolution and injects `STATE_STORE_URL`/`STATE_STORE_TOKEN` per task via\n `containerEnv`. Token is per-incumbence (task + container grace period) and validated by a\n gRPC interceptor → `codes.Unauthenticated` on missing/unknown/expired. Non-loopback targets\n fail closed without TLS or a token.\n- **§12 step 2 (domain type + interface relocation) is done** — `internal/domain/workflow`\n imports no `internal/store` symbol and `store.WorkflowStore` is gone from `TaskContext`. The\n broader Phase 2 acceptance criterion (State Store as its own gRPC service) is still open;\n `.4.2` picks up from here.\n- **Ownership split:** domain-facing workflow contract is **consumer-owned** in the domain\n (`workflow.Store` + `workflow.Task`/`Status`/`Source`, per dependency rules #2 and #7);\n daemon/webui store surfaces stay **producer-owned** in `internal/store`. `store.WorkflowStore`\n is superseded by `workflow.Store`.\n- **One `StateStore` gRPC service** (49 contract RPCs, grouped by contract) + narrow Go consumer facades\n (≤8) on `staterpc.Client` — mirrors the single-`ChatService` precedent.\n- **Domain type relocation** (`Task`/`Status`/`Source` → `internal/domain/workflow`) is a\n Phase 2 prerequisite, pulled forward from migration-decisions §4 (minimal bound,\n `Task → WorkflowExecution`); the rest of §4 stays a separate migration.\n- **`RecordDispatch` drops `*sql.Tx`** (wire-blocker; production passes `nil`) — a\n required interface migration landing before/with `.4.2`.\n- **`Close()` not on the wire**; remote client `Close()` is a no-op.\n- **Structured gRPC error codes** with client rehydration to store sentinels (preserves\n `errors.Is`), a `found=false` + `OK` convention for read not-found, and **sanitised public\n error details** (full detail logged server-side only).\n- **Agent handoff:** `agentworker.Settings` gains `StateStoreTarget`/`StateStoreToken`/\n `StoreTimeout`, injected as `STATE_STORE_URL`/`STATE_STORE_TOKEN` env (mirrors the NATS\n handoff); `Transport.Store` returns a long-lived gRPC `workflow.Store` client.\n- **Transport security + listener topology (rev. 2c):** one in-process listener, bound to the\n host-gateway bridge address when agent containers consume it (the Phase 2 default) or\n loopback-only for a daemon-local-only consumer. `insecure` only on loopback; mandatory\n per-task bearer-token auth on the bridge; TLS/mTLS is an operator choice for any\n non-loopback/k8s topology.\n- **Mode = presence-based `[services.state].target`**, default **local** (not yet extracted);\n add `[services.state]` to `config.example.toml`.\n- **Explicit `var _` assertions on both adapters**; per-contract bufconn conformance.\n- **Migration order:** domain type/interface relocation → `workflow.Store` (agent) → stand up\n `archie-state-store` → `Capture` → `Mapping` → `Binding` → `TaskStore`; NATS `storerpc`\n deleted once the agent is on gRPC; in-process store path deleted in a same-commit flip.\n- **Orphans `ClearTerminalTasks`/`IncrementRetryCount`** retained but not built upon.\n" + "body": "# State Store — contract boundary \u0026 transport (ratification)\n\n**Status:** Approved\n**Revision:** 2e\n**Date:** 2026-09-06\n\nThis is the pre-implementation design document that Phase 2 subtasks `.4.2` (generalize\n`storerpc` as the State Store gRPC contract) and `.4.3` (stand up `archie-state-store`)\nimplement against.\n**Beads milestone:** archie-core-8cda.4.1\n**Parent:** `docs/prds/service-decomposition.md` (open-question Q4 **RESOLVED**)\n\nThis document fixes the **contract boundary** and **transport** for the State Store service.\nIt does not redesign Archie's domain model, does not invent a second store, and does **not**\nsplit `archie.db`. It records method ownership, DTO/wire representation, error semantics,\nlimits, mode/config shape, local-adapter compatibility, and cutover/deletion rules so that\n`.4.2` and `.4.3` have exactly one authoritative surface to build against.\n\n\u003e **Storage superseded.** The store behind this contract is PostgreSQL:\n\u003e `internal/infrastructure/postgres` implements the producer-owned interfaces in\n\u003e `internal/domain/storecontract` and `workflow.Store`, over the database\n\u003e `database_url` names. `internal/store`, the SQLite file and the local adapter\n\u003e are gone; where this document says `archie.db`, `*store.Store` or\n\u003e `internal/store`, read the State Store's PostgreSQL database and\n\u003e `internal/infrastructure/postgres`. The contract, ownership split, error\n\u003e semantics and cutover rules stand.\n\n\u003e **Current state — read before `.4.2` starts.** The §12 step 2 relocation (`archie-core-8cda.\n\u003e 4.8`) has landed: `Task`/`Status*`/`Source*` and the 3-method `workflow.Store` now live in\n\u003e `internal/domain/workflow`, the six production workflow files import no `internal/store`\n\u003e symbol, and `storerpc`/the NATS transport assert against `workflow.Store` instead of\n\u003e `store.WorkflowStore`. The broader Phase 2 acceptance criterion (State Store as its own\n\u003e service behind gRPC) is still open — that is what `.4.2`/`.4.3` build next.\n\n\u003e **Relationship to migration-decisions §4 — not replaced.** `docs/architecture/\n\u003e migration-decisions.md` §4 (`store.Task → WorkflowExecution`, `mutable Stage →\n\u003e StepExecution history`, `RetryCount/Attempt → Attempt records`, versioned Workflow defs)\n\u003e **remains the authoritative, open document for the long-term Workflow migration.** This PRD\n\u003e does **not** replace it. It only pulls the minimal `Task`/`Status`/`Source` type + interface\n\u003e relocation forward as a Phase 2 prerequisite (because the acceptance criterion requires it);\n\u003e the rest of §4 stays its own migration and stays open.\n\n---\n\n## 1. Decision (the invariant everything follows)\n\nArchie is composed such that a single **`archie-state-store`** service owns the one existing\nSQLite file (`archie.db`) and exposes it over **gRPC behind narrow typed contracts**. There is\nexactly one store, one file, one service. No database-per-service, no distributed\ntransactions, no second store abstraction.\n\nTwo adapter families satisfy the contract interfaces:\n\n- **Local adapter** — `*store.Store` (the in-process SQLite implementation).\n- **Remote adapter** — `*staterpc.Client` (wraps the generated gRPC client).\n\nEach adapter carries an explicit compile-time assertion against the contract interfaces it\nserves. Composition picks local vs. remote by the presence of `[services.state].target`\n(empty = local; set = dial the gRPC service). Default is **local** (the State Store is not yet\nextracted), which is the PRD §3 posture; it differs from the gateway's remote-default only\nbecause the gateway is already a separate deployment and the State Store is not.\n\n\u003e **Contract-ownership fork, decided (rev. 2c — resolves the domain contradiction).**\n\u003e Ownership splits by the consumer's *layer*, per the dependency contract's rule #2\n\u003e (\"a domain defines the smallest interfaces required to perform its work\") and rule #7\n\u003e (\"database rows … MUST NOT leak into domain models\"):\n\u003e\n\u003e - The **workflow domain** (`internal/domain/workflow`) is the only domain-layer consumer of\n\u003e store state. It defines its own **consumer-owned** narrow `Store` interface\n\u003e (Update/Transition/InsertEvent) and its own **domain-owned** `Task` type plus\n\u003e `Status`/`Source` vocabulary. It imports **zero** `internal/store` symbols — satisfying the\n\u003e Phase 2 acceptance criterion. This is the minimal bound of migration-decisions §4\n\u003e (`store.Task → WorkflowExecution`), pulled forward **because** the acceptance criterion\n\u003e requires it.\n\u003e - The **daemon / webui / intake** store surfaces (`TaskStore`, `CaptureStore`,\n\u003e `MappingStore`, `BindingStore`, `BindingDispatcher`, `BindingTaskCreator`) stay\n\u003e **producer-owned** in `internal/store`, because those consumers are application and\n\u003e infrastructure layers, not domains — rule #2 does not apply to them.\n\nSo the State Store contract is **not** uniformly producer-owned: the domain-facing workflow\ncontract is consumer-owned (in the domain), while the daemon/webui store surfaces remain in\n`internal/store`. `internal/store` imports `internal/domain/workflow` for the `Task`/`Status`/\n`Source` types it persists (persistence → domain, the correct direction), and its `Store`\nimplementation satisfies `workflow.Store`. This is the single decision that makes the whole\nPhase 2 acceptance criterion and the architecture's rules simultaneously satisfiable.\n\n\u003e **`internal/store` is a TRANSITIONAL compatibility location (rev. 2c).** The repository's target\n\u003e architecture (`docs/architecture/dependencies-and-contracts.md`, `organisation.md`) places\n\u003e persistence implementations under `internal/infrastructure/\u003ccapability\u003e`. `internal/store`\n\u003e holding the task/capture/mapping/binding implementation and ALSO being the home of the\n\u003e producer-owned daemon/webui interfaces is acceptable **only as a transitional location**. The\n\u003e long-term home for the store implementation is `internal/infrastructure/store`; the\n\u003e producer-owned interfaces may move to the same infrastructure package (or an approved\n\u003e contract location) when the store implementation relocates. Agents must not treat\n\u003e `internal/store` as the final infrastructure boundary.\n\u003e\n\u003e **REV. 2d (archie-core-8cda.5.6): the producer-owned interfaces HAVE moved to an approved\n\u003e contract location** — `internal/domain/storecontract` (package `storecontract`), ahead of the\n\u003e store implementation's own relocation. The UI Service deletion gate required the archie-ui\n\u003e process to hold the contracts without linking `internal/store`'s SQL implementation, and\n\u003e `internal/contracts/` itself is ruled out: that tree is the `buf generate` output and\n\u003e `tools/proto.sh check` deletes hand-written files there. `internal/store` keeps type aliases\n\u003e (`type TaskStore = storecontract.TaskStore`, the sentinel `var`s, the value types) so\n\u003e daemon-side callers are unaffected; the sentinel message strings are unchanged and remain\n\u003e the wire contract (§4).\n\n---\n\n## 2. Contract boundary\n\n**Ownership split** (see the fork in §1): the **workflow-domain consumer contract** is\n`workflow.Store` (consumer-owned, in `internal/domain/workflow`); the **daemon/webui/intake\nstore surfaces** are the producer-owned interfaces in `internal/store/interface.go`.\n`store.WorkflowStore` is **superseded** — it is replaced by the domain-owned `workflow.Store`,\nand `internal/store`'s `Store` implementation satisfies `workflow.Store` directly. `TaskStore`\nremains the only composite; every other interface is flat. Narrow slices are split along\nconsumer-capability lines so no consumer acquires a surface it does not need\n(`interfacebloat` cap = 8).\n\n| Interface (owner) | Embeds | Methods | Local impl | Remote impl |\n|---|---|---|---|---|\n| `TaskStore` (store) | `TaskLifecycle`, `TaskEvents`, `TaskQueries`, `TaskArchiver`, `TaskRetryer` | 24 (union) | `*Store` | `*staterpc.Client` |\n| `TaskLifecycle` (store) | — | 8 | `*Store` | `*staterpc.Client` |\n| `TaskEvents` (store) | — | 7 | `*Store` | `*staterpc.Client` |\n| `TaskQueries` (store) | — | 7 | `*Store` | `*staterpc.Client` |\n| `TaskArchiver` (store) | — | 1 | `*Store` | `*staterpc.Client` |\n| `TaskRetryer` (store) | — | 1 | `*Store` | `*staterpc.Client` |\n| `workflow.Store` (workflow domain) | — | 3 | `*Store` | `*staterpc.Client` |\n| `CaptureStore` (store) | — | 2 | `*Store` | `*staterpc.Client` |\n| `MappingStore` (store) | — | 5 | `*Store` | `*staterpc.Client` |\n| `BindingStore` (store) | — | 6 | `*Store` | `*staterpc.Client` |\n| `BindingDispatcher` (store) | — | 3 | `*Store` | `*staterpc.Client` |\n| `BindingTaskCreator` (store) | — | 1 | `*Store` | `*staterpc.Client` |\n| `PlaybookDispatcher` (store) | — | 2 | `*Store` | `*staterpc.Client` |\n\n**Key property of the remote client:** `*staterpc.Client` is a *single* adapter that wraps one\n`StateStoreClient` and is asserted against **whichever narrow Go interfaces its caller needs**\n(exactly as `gatewayrpc.Client` asserts both `gateway.ChatContract` and\n`gateway.SessionStore`). The Go contracts stay narrow (≤8, the `interfacebloat` cap); the wire\nis one service. `workflow.Store` introduces **no new RPCs** — it is a narrow consumer face over\nthe same `Update`/`Transition`/`InsertEvent` RPCs.\n\n---\n\n## 3. Method ownership\n\n`*Store` remains the single implementation of the daemon/webui store surfaces and of\n`workflow.Store`. Ownership below is about which **process** is the primary consumer of each\nmethod and therefore which methods are genuinely cross-process on the wire vs.\ndaemon-internal.\n\nProcess legend: **DAEMON** = `archied` (incl. in-process webui + gateway runtime +\n`storerpc.Server`); **AGENT** = `archie-agent` worker (no DB connection); **GATEWAY** = store\naccess through daemon-side narrow adapter interfaces.\n\n| Contract | Primary consumers (process) | Remote on the wire? |\n|---|---|---|\n| `TaskLifecycle` (8) | DAEMON (dispatch, claim, action) + **AGENT** (`Transition`, `Update` via storerpc) | `Transition`/`Update` = **YES** (agent); rest DAEMON |\n| `TaskArchiver` (1) | DAEMON (`taskactions` archive) | not yet |\n| `TaskRetryer` (1) | DAEMON (`taskactions` retry) | not yet |\n| `TaskQueries` (7) | DAEMON + GATEWAY (status/list adapters) | not yet (`OpenPRs`/`Tasks`/`StatusCounts` cross to gateway adapters in-process) |\n| `TaskEvents` (7) | DAEMON + **AGENT** (`InsertEvent` via storerpc) | `InsertEvent` = **YES** (agent); rest DAEMON |\n| `workflow.Store` (3) | **AGENT** only | **YES** (the sole genuinely remote consumer) |\n| `CaptureStore` (2) | DAEMON (webhook intake + mapping editor) | not yet |\n| `MappingStore` (5) | DAEMON (dashboard editor + dispatch loop) | not yet |\n| `BindingStore` (6) | DAEMON (dashboard editor + dispatch loop) | not yet |\n| `BindingDispatcher` (3) | DAEMON (dispatch loop) | not yet |\n| `BindingTaskCreator` (1) | DAEMON (dispatch loop) | not yet |\n| `PlaybookDispatcher` (2) | DAEMON (EDA playbook dispatch loop) | **YES** (side-effecting-action idempotency ledger over gRPC) |\n\n**Consequence for migration order:** the **agent's `workflow.Store` is already cross-process\nalready** (via the NATS `storerpc` surrogate), so it is the first contract to move to gRPC. The\ndaemon-internal surfaces (`Capture`/`Mapping`/`Binding`) stay in-process until the daemon\nitself points at `archie-state-store`. `TaskStore` (the large composite) moves last.\n\n**Two orphan methods** — `TaskQueries.ClearTerminalTasks` and\n`TaskQueries.IncrementRetryCount` have **no production consumer** (only `*Store` tests). They\nremain part of the Go `TaskQueries`/`TaskStore` surface, and therefore part of the wire\ncontract, but are flagged for deletion: they must **not** gain dedicated consumers or wire\nmethods in this work. Do not add the rest of the codebase to them.\n\n---\n\n## 4. Domain-facing types \u0026 consumer-owned contract — resolves the contradiction\n\nThe Phase 2 acceptance criterion (\"`internal/domain/workflow` … no longer import\n`internal/store` directly — they call the State Store contract\") **cannot be met while**\n`store.Task`, `store.Status*`, `store.Source*`, and `store.WorkflowStore` live in\n`internal/store`. This section fixes where they move.\n\n**The relocation (a prerequisite that must land before or with `.4.2`):**\n\n| Current symbol (`internal/store`) | Moves to | Notes |\n|---|---|---|\n| `Task` type | `internal/domain/workflow.Task` | The task-execution record the workflow domain operates on. `internal/store` persists this type (persistence → domain). |\n| `Status` + `Status*` constants | `internal/domain/workflow` | e.g. `StatusClosedWontDo`, `StatusMerged`, `StatusPROpen`, `StatusWaitingHuman`, `StatusRunning` — task-lifecycle vocabulary. |\n| `Source` + `Source*` constants | `internal/domain/workflow` | e.g. `SourceChat` — provenance vocabulary, follows `Task`. |\n| `WorkflowStore` interface (3 methods) | `internal/domain/workflow.Store` | **Consumer-owned** (dependency rule #2). Supersedes `store.WorkflowStore`. |\n\n**Resulting dependency direction (correct per the architecture):**\n\n- `internal/domain/workflow` imports **no** `internal/store` symbols → the acceptance\n criterion is satisfied. It consumes `store.Task`'s replacement as `workflow.Task`, uses\n `workflow.Status*`/`workflow.Source*`, and depends on its own `workflow.Store` interface.\n- `internal/store` imports `internal/domain/workflow` for the `Task`/`Status`/`Source` types it\n reads and writes (infrastructure → domain). **NOTE: `internal/store` is a transitional\n compatibility location only** — its long-term home is `internal/infrastructure/store` (see\n the callout in §1). Do not treat `internal/store` as the final infrastructure boundary.\n- Every store test that constructs `store.Task{…}` is updated to the relocated type as part of\n this prerequisite. This is a mechanical rename across ~6 workflow production files\n (`workflow.go`, `steps.go`, `triage.go`, `review.go`, `feasibility.go`, `implement.go`) and\n their tests plus the store tests. `TestRecordDispatchViaExplicitTx` is removed rather than\n updated — its non-nil `*sql.Tx` path has no production consumer (see §5's `RecordDispatch`\n blocker).\n\n**What this does NOT do:** it does not implement the full §4 Workflow migration\n(`mutable Stage → StepExecution history`, `RetryCount/Attempt → Attempt records`,\n`workflow.Registry → versioned Workflow definitions`, etc.). It lands only the minimal\ntask-type + `Status`/`Source` + consumer-owned-interface relocation that the Phase 2\ndomain-decoupling criterion requires. The residue of §4 remains its own migration.\n\n**Forward-compatibility:** because the wire DTOs are derived from the domain `Task`/`Status`\n(§5), when the full §4 migration later renames `workflow.Task` (or refines it into\n`WorkflowExecution`), only `values.go` and the proto field mapping change — the RPC surface and\nconsumer interfaces are unaffected. The wire contract is deliberately type-agnostic at this\nlevel.\n\n---\n\n## 5. DTO / wire representation\n\n### Proto layout\n\n- **Service:** `proto/state/v1/state.proto`, `package state.v1`, **one** `StateStore` service\n (mirrors the gateway's single `ChatService`; proto bypasses the Go `interfacebloat` cap, as\n `ChatContract` does via `//nolint:interfacebloat`).\n- **Codegen:** the existing buf v2 pipeline. `proto/buf.yaml` (module, lint STANDARD, breaking\n FILE against `main`), `proto/buf.gen.yaml` **managed mode** with\n `go_package_prefix → github.com/samcharles93/archie-core/internal/contracts`, plugins\n `protoc-gen-go` + `protoc-gen-go-grpc`, `out: ../internal/contracts`,\n `opt: paths=source_relative`. **No `go_package` in source** — managed mode owns it. Generated\n Go lands in `internal/contracts/state/v1/` (package `statev1`), committed (`proto:check`\n fails on uncommitted/unmodified generated files).\n- **Adapter package:** `internal/infrastructure/staterpc/` with `server.go` (registers the\n generated server over the store), `client.go` (wraps the generated client into `store.*` and\n `workflow.Store` facades), `values.go` (proto ⇄ domain mappers), and `conformance_test.go`\n (bufconn local-vs-grpc dual-adapter suite), mirroring `internal/infrastructure/gatewayrpc/`.\n- **Binary:** `cmd/archie-state-store/main.go`, mirroring `cmd/archie-gateway/main.go` and the\n serve pattern in `internal/app/archied/gateway.go` (`serveGateway`).\n\n### The `StateStore` RPC set (union of the contracts, grouped)\n\nMethods are named after the store methods so the mapping is unambiguous. `workflow.Store` is a\n*view*, not new RPCs — `Update`/`Transition`/`InsertEvent` are shared with\n`TaskLifecycle`/`TaskEvents` and appear once.\n\n| Group | RPCs |\n|---|---|\n| Lifecycle | `EnqueueIssue`, `EnqueueChatTask`, `ClaimNext`, `ClaimByIssue`, `Transition`, `Update`, `Requeue`, `RecoverStale` |\n| Archive / Retry | `ArchiveTask`, `RetryTask` |\n| Queries | `TaskByIssue`, `OpenTaskByPR`, `TaskByID`, `OpenPRs`, `ClearTerminalTasks`, `Tasks`, `StatusCounts`, `IncrementRetryCount` |\n| Events | `InsertEvent`, `EventsSince`, `TaskEvents`, `WorkflowStats`, `StageStats`, `TokensByDay` |\n| Capture | `InsertCapture`, `ListCaptures` |\n| Mapping | `InsertMapping`, `GetMapping`, `ListMappings`, `UpdateMapping`, `DeleteMapping` |\n| Binding | `InsertBinding`, `GetBinding`, `ListBindings`, `UpdateBinding`, `DeleteBinding`, `ApproveBinding` |\n| Dispatch | `ArmedBindingsForSource`, `RecordDispatch`, `ListUndispatchedCaptures` |\n| Playbook | `RecordPlaybookDispatch`, `DeletePlaybookDispatches` |\n| BindingTaskCreator | `EnqueueBindingTask` |\n| Config snapshot | `PutConfigSnapshot`, `GetConfigSnapshot` |\n| Apply status | `PutApplyStatus`, `ListApplyStatus` |\n| Channel status | `PutChannelStatus`, `ListChannelStatus` |\n| Task log | `ReadTaskLog`, `StreamTaskLogContent` |\n\nThat is **51 unique contract RPCs** across one service (the `TaskEvents.Close` method is dropped).\n`Close()` is **excluded** from the wire (it is server lifecycle, not a client call) — see §11.\n\nThe channel-status pair follows the config snapshot's split for the same reason: the writer is the process that HOSTS the channels -- the Messaging Service, which alone observes whether a channel is starting, running or failed -- and the reader is the UI process. Both RPCs are administrative, so a task-scoped grant reaches neither. A channel's state is runtime state rather than a settings document, which is why it is not a `ControlPlaneService` resource kind: a failed channel is not a document anybody edits. Asking for a reload travels on its own surface rather than through this one; see `docs/architecture/migration-decisions.md`, \"Channel state to the dashboard\".\n\nThe config-snapshot pair was added by `archie-core-ymut` (see\n`docs/architecture/migration-decisions.md`, \"Dashboard configuration page\"). It is the one\nsurface whose writer is the daemon and whose reader is the UI process, and both RPCs are\nadministrative: `authorizesTaskScopedCall` is deny-by-default, so a task-scoped grant reaches\nneither. `ConfigSnapshot.document` is opaque to this contract — the store neither parses nor\nvalidates it, and `schema` names the projection so a reader can refuse a shape it does not\nunderstand.\n\nThe apply-status pair was added by `archie-core-pskb` (see\n`docs/prds/control-plane-apply-status.md`). It is administrative for the same reason as the\nconfig-snapshot pair, and deny-by-default in `authorizesTaskScopedCall` covers it without a\nnew rule. Unlike that pair, the read is a list: `ListApplyStatus` returns every process's\nrecord and an empty slice means nothing has reported yet, so the `found=false` convention for\nabsent single rows does not apply. The rows are keyed on `(process, kind)` and replaced in\nplace, because each process re-stamps its record on an interval and no reader wants a history\nof re-stamps.\n\nThe task-log pair was added by `archie-core-iaqx` (see `docs/prds/ui-service-boundary.md`'s\nroute inventory). It is the one surface whose payload is not a row: the store service reads\nthem out of the state directory it owns with `internal/logging`'s own reader, so the wire\ncarries `logging.Entry`/`logging.Query` values and neither side restates the JSONL format.\n`ReadTaskLog` returns a decoded page and `StreamTaskLogContent` returns the raw bytes\nserver-streamed, because a log file rotates at 20 MB — past gRPC's 4 MiB unary cap — and the\nsame reasoning that made `StreamCaptures` supersede `ListCaptures` applies. `found=false` with\nno error means the attempt has no log; a service with no reader answers `Unavailable` instead,\nand the two answers are load-bearing for the dashboard: only the second is a deployment\ncondition, and the panel that collapsed them told operators task logging was switched off when\nit was not. The Go facade is `storecontract.TaskLogStore` (2 methods), carried by\n`*staterpc.Client` alongside the rest.\n\nThe playbook pair was added by `archie-core-t2db.17`'s implementation (see\n`docs/prds/eda-playbook-engine.md`, execution-time gap 2). It is administrative\nfor the same reason as the config-snapshot and apply-status pairs, and\ndeny-by-default in `authorizesTaskScopedCall` covers it without a new rule. The\nrow is the structural `(playbook_id, playbook_version, event_id, action_id)`\ntuple, written **before** the action's side effect fires (the reverse of\n`binding_dispatches`), so a duplicate returns `store.ErrAlreadyDispatched` and\nthe coordinator skips the invoke rather than repeating a non-revocable side\neffect. `DeletePlaybookDispatches` is the explicit reclamation primitive; nothing\ncalls it automatically, because a playbook file's absence at boot is not a\ndeliberate removal (`eda-playbook-engine.md`, \"Lifetime\"). The Go facade is\n`storecontract.PlaybookDispatcher` (2 methods), carried by `*staterpc.Client`\nalongside the rest.\n\n### Domain types and `values.go` mapping\n\n`values.go` maps proto ⇄ these types. The task model for the **agent** path is the domain-owned\n`workflow.Task` (§4); the daemon/webui store surfaces return the same `workflow.Task` (the store\npersists the domain type).\n\n| Domain type | Package | Notes for `values.go` |\n|---|---|---|\n| `workflow.Task` | `internal/domain/workflow` | time fields stored as layout strings; convert to/from `google.protobuf.Timestamp` |\n| `events.Event` | `internal/events` | `Timestamp` → `google.protobuf.Timestamp` |\n| `store.CapturedEvent` | `internal/store` | headers/body/remote_addr; body capped 256 KiB |\n| `mapping.Mapping` | `internal/domain/mapping` | JSON-path field bindings |\n| `binding.Binding` | `internal/domain/binding` | secret is **already decrypted** before returning; keep decrypted form out of any durable/logged representation |\n| `workflow.Status` / `workflow.Source` | `internal/domain/workflow` | enum-like; map to proto enum or string, keeping the names stable for compatibility |\n| `store.WorkflowStat` | `internal/store` | aggregate row |\n| `store.StageStat` | `internal/store` | aggregate row |\n| `store.DayTokens` | `internal/store` | aggregate row |\n\n### Wire-contract blocker fixed here: `RecordDispatch`\n\n`store.BindingDispatcher.RecordDispatch(ctx, tx *sql.Tx, bindingID, bindingVersion int64,\ncaptureID int64, taskID int64) error` takes a **`*sql.Tx`** that cannot cross a gRPC boundary.\n\n**Evidence that the `*sql.Tx` is removable:** the dispatch loop calls `RecordDispatch(ctx, nil,\n…)` (`internal/daemon/daemon.go`). The implementation falls back to the store's own\n`*sql.DB` when `tx == nil` (\"best-effort, not atomic\"; the comment and the\n`TestRecordDispatchViaExplicitTx` test are the only consumers of the non-nil `tx` path).\nProduction never opens the explicit transaction.\n\n**Decision:** the contract drops `*sql.Tx` from `RecordDispatch` (the method becomes\n`RecordDispatch(ctx, bindingID, bindingVersion, captureID, taskID) error`). The store service\nowns any transaction boundary internally when atomicity is wanted; the at-most-once\nguarantee is the `INSERT OR IGNORE` dedup row, which is already transactionless in production.\n`TestRecordDispatchViaExplicitTx` is superseded by the store service's own internal-transaction\ntest. **This is a required interface migration that must land before or with `.4.2`** (the\ncurrent `interface.go` signature and test still use the transaction-bearing form).\n\n---\n\n## 6. Agent State Store client handoff\n\nMoving the agent from NATS `storerpc` to gRPC `workflow.Store` requires the agent process to\nreceive a State Store endpoint. The agent already receives its NATS connection settings via\nboot-time env/flags (see `cmd/archie-agent/main.go`: `-nats-url` / `NATS_URL`, `NATS_TOKEN`\nenv), and the daemon injects them into the task container. The State Store handoff follows the\nsame seam.\n\n**Boot handoff contract (additive, not replacing the NATS settings):**\n\n| Field | Where | Source | Notes |\n|---|---|---|---|\n| `StateStoreTarget` | `agentworker.Settings` | env `STATE_STORE_URL` (or `-state-store-url` flag), set by the daemon in the container env | `host:port` of the State Store gRPC server. Loopback/Docker-bridge address — the agent reaches it the same way it reaches the daemon's NATS. |\n| `StateStoreToken` | `agentworker.Settings` | env `STATE_STORE_TOKEN` (or `-state-store-token` flag) | Per-task bearer token carried in gRPC metadata by a client interceptor (see §9). |\n| `StoreTimeout` | `agentworker.Settings` | a bounded per-call timeout | Mirrors `natsrpc.Client.Timeout` / the existing `rpcTimeout`; bounds each State Store call when the caller `ctx` has no deadline. |\n\n**Wiring change in the transport façade:**\n\n- `internal/infrastructure/agenttransport/nats.Transport` — `Store(timeout) store.WorkflowStore`\n returns `\u0026storerpc.Client{Conn: t.conn, Timeout: timeout}`. It becomes\n `Store(timeout) workflow.Store` and returns a *single long-lived* `staterpc.Client` dialed to\n `settings.StateStoreTarget` (with the token interceptor and per-call timeout).\n- `internal/app/agentworker/worker.go` `Settings` gains the three fields above; `taskServiceTransport`\n and `taskDependencies` change their `store` type from `store.WorkflowStore` to\n `workflow.Store` (via `domain/workflow.TaskContext{Store: …}`).\n- Reconnect/deadline: `grpc.NewClient` (or the existing dial path) provides transparent reconnect;\n each RPC is bounded by the per-call context deadline (`StoreTimeout`), matching the\n request/reply timeout the NATS path used. No streaming is involved, so no server-sent\n reconnect semantics apply.\n\n**Deletion rule for the NATS path:** the NATS `storerpc` (Server, Client, subjects\n`archie.store.update|transition|insert_event`) is deleted **only after** the agent has fully\nmoved to gRPC and the container env carries `STATE_STORE_URL`. Until then both paths may coexist\n(agent flips when the daemon starts injecting `STATE_STORE_URL`); there is no dual-live window\nacross a single agent process, which is either NATS-backed or gRPC-backed, never both.\n\n### Operational specifics (in-process listener → address → per-task injection)\n\n- **Who binds the in-process State Store listener:** the daemon (`archied`), at bootstrap, when\n the State Store is served in-process/multiplexed (mirroring `serveGateway` in\n `internal/app/archied/gateway.go`): a `grpc.NewServer()` + `RegisterServer` + graceful stop on\n `ctx.Done()`.\n- **Address selection (Docker-bridge reachable):** reuse the host-gateway resolution already used\n for embedded NATS (`internal/container/network.go` `RequireHostGateway` /\n `resolveHostGateway`). Per §9's single listener-topology rule, the listener binds the\n **host-gateway bridge address** when agent containers consume it (the Phase 2 default), or\n loopback-only when the daemon is the sole consumer. The chosen address is stored on the daemon\n as `d.ConnectedStateStore.URL` (analogous to `d.ConnectedNATS.URL`).\n- **Per-task injection:** `containerEnv(task)` (`internal/daemon/daemon.go`) appends\n `STATE_STORE_URL=\u003cd.ConnectedStateStore.URL\u003e` and `STATE_STORE_TOKEN=\u003ctoken\u003e` alongside the\n existing `NATS_URL`/`NATS_TOKEN`. The agent reads them via env (`-state-store-url` /\n `STATE_STORE_URL`, `-state-store-token` / `STATE_STORE_TOKEN`), the same seam as `NATS_URL`. A\n reloaded `[services.state]` must not point new containers at a store the daemon is not serving\n — the same immutability rule as NATS.\n\n---\n\n## 7. Error semantics\n\n### Current state (both boundaries lose error identity)\n\n- **NATS `natsrpc.Envelope`** (`internal/natsrpc/natsrpc.go`) serialises any error to a single\n `err.Error()` string and rehydrates a fresh `errors.New(string)`. The original type, `%w`\n chain, and sentinel identity are lost → `errors.Is(err, store.ErrStaleTransition)` is\n **false** across the boundary.\n- **gRPC `gatewayrpc`** returns raw `err` from handlers; gRPC-Go converts to\n `codes.Unknown` with only the message. The **only** explicit code in the repo is\n `codes.Unavailable` for a missing session store (`server.go`). No status-code mapping for\n store errors exists.\n\n### Decision — structured mapping so `errors.Is` survives\n\nThe `StateStore` service must map the store's sentinel errors to canonical gRPC codes and\nrehydrate them to the *same* sentinels on the client, so consumer `errors.Is` checks keep\nworking — an improvement over the flattening it replaces, not a regression.\n\n| Store sentinel / outcome | gRPC code | Client rehydrates to |\n|---|---|---|\n| `store.ErrStaleTransition` | `FailedPrecondition` | `store.ErrStaleTransition` |\n| `store.ErrBindingNotFound` | `NotFound` | `store.ErrBindingNotFound` |\n| `store.ErrMappingNotFound` | `NotFound` | `store.ErrMappingNotFound` |\n| `store.ErrBindingOverlap` | `FailedPrecondition` | `store.ErrBindingOverlap` |\n| `store.ErrBindingTransition` | `FailedPrecondition` | `store.ErrBindingTransition` |\n| `store.ErrAlreadyDispatched` | `AlreadyExists` | `store.ErrAlreadyDispatched` |\n| not-found-as-`(nil,nil)` (`TaskByID`, `GetBinding`, `GetMapping`, `ClaimNext`, `ClaimByIssue`, …) | `NotFound` with a `found=false` field (**not** an error) | `(nil, nil)` |\n| infra / wrapped error | `Internal` (**sanitised** message, see below) | wrapped `fmt.Errorf(...%w)` |\n| capability absent | `Unavailable` | context/typed error |\n\nThe `found=false`-not-error convention matters: the repo deliberately returns `(nil, nil)` for\nnot-found in reads and a sentinel for not-found in writes. The wire must preserve **both**\nconventions (a `GoogleRPCStatus` with `NotFound` is an *error*, which would wrongly surface to\ncallers that expect `(nil, nil)`). Implement `found` as an explicit boolean field on read\nresponses, and map `(nil,nil)` ⇄ `found=false` + `OK`.\n\n### Error-detail sanitisation (rev. 2c)\n\nFull internal error messages must **not** be placed in gRPC `details` for remote callers. SQL\npaths, provider/forge details, secrets, and stack traces are sensitive internals. The rule:\n\n- **Sentinel errors** — the client rehydrates the sentinel from the code; the message string in\n `status.Error` is a short, public, stable phrase (e.g. `\"stale transition\"`), not the raw\n wrapped chain.\n- **Infra errors** — the wire carries a **sanitised** public message + the `Internal` code.\n The **full** error (with `%w` chain, SQL, provider detail) is logged **server-side only** by\n the store service. The client rehydrates a generic wrapped error and must not surface the raw\n text to users.\n\n---\n\n## 8. Limits\n\n**Interface bloat (`interfacebloat` cap = 8)** — `.golangci.yml` `interfacebloat: max: 8`,\nwhich overrides the upstream default of 10. The Go consumer facades must stay ≤8 methods.\n`TaskLifecycle` is exactly 8 (at the cap); `TaskStore` is the 24-method composite that the cap\nis why it is decomposed; proto services bypass the cap (like `ChatContract`).\n\n**Payload caps:**\n- Capture body: `defaultCaptureMaxBodyBytes = 256 KiB` (may reduce further; the wire message\n must not exceed gRPC's default 4 MiB receive limit for a single capture). A single capture\n fits, but a *batch* of them did not: the caller-side cap of up to 100 captures at 256 KiB each\n could exceed 4 MiB in one unary `ListCaptures`/`ListUndispatchedCaptures` response. `.4.7` adds\n `StreamCaptures`/`StreamUndispatchedCaptures` (server-streaming, one capture per message) as\n the path both `staterpc.Client` methods actually call; the original unary RPCs stay defined,\n unmodified and deprecated, only so `buf breaking` protects an in-flight rolling deploy.\n- Task `detail`/`park_reason`/event `Detail`: 4000-char hard cap (`clip(s, 4000)`).\n\n**Retention (stays server-side in the store; the wire does not carry pruning decisions):**\n- `events` table: **no prune, unbounded growth** — a known risk to revisit, not changed here.\n- `captured_events`: prune-on-write, default 7 days / 5000 events.\n\n**Pagination/arity:** store read methods take a raw `int limit` (no store-side cap); the\ncaller-side caps (task list 100, log 2000, captures 100, capture scan window 5000, binding\ndispatch batch 100, session list 20) remain caller-side. The wire passes `limit int` and returns\n`[]*` slices, mirroring the existing Go signatures — **no cursor/paging protocol is introduced**\nin this work (the current `EventsSince(sinceID, limit)` offset cursor is the only one, and it\nstays as-is).\n\n---\n\n## 9. Transport security boundary\n\nThe gateway precedent is loopback-only, unauthenticated gRPC. The State Store holds the\ncrown-jewel `archie.db` (task/event/capture/mapping/binding data), so its boundary must be\nstated explicitly rather than left implicit.\n\n**The State Store's equivalent boundary (rev. 2c):**\n\n- **Listener topology — single rule (rev. 2c).** One in-process listener; its bind address is\n chosen by the consumer set, never both at once:\n - *Agent containers consume it* (the Phase 2 driver during multiplexed serving) → bind to the\n **host-gateway bridge address** so containers can reach it, and **token auth is mandatory**\n (a bridge host is reachable by any process on that bridge). A container **cannot reach the\n host's `127.0.0.1`**, so loopback-only is NOT usable for the agent-consumed path.\n - *Only the daemon consumes it* (no agent) → bind **loopback-only** (`--listen 127.0.0.1`),\n `insecure` is fine because it is not network-reachable; no token required.\n - There is **no dual-listener** design. The practical default during `.4.2` (the reason\n in-process serving exists is to give the agent a gRPC target) is the **bridge address +\n token**. `127.0.0.1` is reserved for the daemon-local-only case.\n- **Agent access → the container bridge.** The agent runs in a task-scoped container on the\n host and reaches the State Store over the Docker bridge gateway (the bind address from the\n topology rule above), exactly as it reaches the daemon's NATS. To close the \"any host\n process could reach the store\" gap, the agent **authenticates with a per-task bearer token**\n carried in gRPC metadata by a client interceptor (`StateStoreToken`, §6). Network\n reachability + the token is the trust boundary for the default bridge topology.\n- **The daemon** uses the local adapter (`*store.Store`) in-process by default, so no network\n boundary exists until `[services.state].target` is set; when it is set, the daemon client\n authenticates with a token supplied alongside the target.\n- **Non-loopback / k8s:** TLS/mTLS is an **operator decision**, not a default. Any non-loopback\n exposure (e.g. `--listen 0.0.0.0`, a CDN, a cross-host service) requires an explicit decision\n and mTLS or token auth — mirroring the gateway's `--listen`/`--enable-cors-header`\n confirmation caveat. The NATS-KV discovery fallback supplies endpoints but does not add\n transport security; that stays the operator's responsibility.\n\n### Token lifecycle (rev. 2c; scoping added in `.4.7`)\n\n- **Generation:** the daemon generates a per-task bearer token when it acquires the container\n (or per incumbence) and injects it via `containerEnv` as `STATE_STORE_TOKEN`. A single token\n may cover a task's container lifetime.\n- **Registration (`.4.7`, post-standalone-cutover):** the State Store is now its own process\n (`.4.3`/`.4.6`), so the daemon can no longer just hold an in-process issued-token set for the\n server to check — it registers the token at the remote authority via the\n `RegisterTaskGrant`/`RevokeTaskGrant` RPCs (`staterpc.GrantIssuer`, `daemon.StateStoreGrantIssuer`),\n admin-token-authenticated calls a task-scoped token itself can never make.\n- **Lifetime:** tied to the task + container grace period; rotated on a new container acquisition\n for the same task; a token for a released container is invalidated (`RevokeTaskGrant`, deferred\n alongside `ContainerPool.Release`). An unrevoked grant still expires server-side (bounded by\n `RegisterTaskGrantRequest.lifetime_seconds`, capped at 7 days) so a daemon crash before revoke\n cannot leave a grant valid indefinitely.\n- **Validation and scope (`.4.7`):** a gRPC interceptor (`staterpc.TaskGrants.UnaryInterceptor`)\n validates the token against the State Store's own issued-grant set; missing/unknown/expired →\n `codes.Unauthenticated`. Unlike the daemon's own administrative token (full access to all ~40\n RPCs), a task-scoped grant additionally authorizes only `Update`/`Transition`/`InsertEvent` on\n its own task ID — every other RPC, including the streaming capture surface and\n `RegisterTaskGrant`/`RevokeTaskGrant` themselves, is `codes.PermissionDenied` for a task-scoped\n caller. The token is carried in gRPC metadata, never in a URL.\n\n### Fail-closed on non-loopback (rev. 2c)\n\nIf `[services.state].target` points to a non-loopback address and **neither** TLS **nor** a token\nis configured, the State Store client (daemon or agent) **fails closed** — it refuses to\nstart/dial rather than fall back to a plaintext, unauthenticated remote connection. This mirrors\nthe gateway's `--listen`/`--enable-cors-header` confinement caveat and prevents a silent\nunauthenticated remote store. The loopback + token default is the only path that starts without\nan explicit operator decision.\n\n---\n\n## 10. Mode / config shape\n\n**Follow the gateway's presence-based `target` seam, not the NATS `mode` enum.**\n\n- **Services are keyed by name, not named as struct fields.** A\n `State ServiceConnection` field per service is the duplication\n `docs/prds/service-registry.md` removes, and this document's summary describes\n the seam as `[services.\u003cname\u003e]`:\n ```go\n type Services map[string]ServiceConnection\n ```\n registered once via `RegisterService(context, name, target, listen, tokenEnv)`. The TOML\n shape below is unchanged, so nothing else in this section is affected; read\n `cfg.Services.Get(\"state\")` wherever it says `cfg.Services.State`.\n- **Empty `Target` → startup error.** The local `*store.Store` adapter default was\n withdrawn when the State Store was extracted (§12 step 7): the standalone `archie-state-store` process\n exclusively owns `archie.db`, so both `archied` and `archie-gateway` now reject an empty\n target (`internal/app/archied/bootstrap.go` and `state_store_client.go`: `services.state.target\n is required`). **Set `Target` → dial gRPC** with `*staterpc.Client`; no client opens the\n database itself. This differs from the gateway, where `Target` is defaulted to\n `127.0.0.1:8585` because `archie-gateway` is already a separate process whose client and\n server share one default.\n- `[services.state]` is present and **uncommented** in `config.example.toml`, with `target`\n marked REQUIRED, because the value is load-bearing for every client. A commented-out\n `target` cannot boot, so the section ships uncommented.\n- Composition root: `internal/app/archied/bootstrap.go` (the daemon) and\n `internal/app/archieui/config.go` (the UI process) both read `cfg.Services.Get(\"state\")` and\n dial the remote State Store. The task store is built only in the standalone\n `archie-state-store` process (`internal/app/archied/state_store.go`), which is the only path\n that opens the task tables.\n\n\u003e **Mode fork, decided.** The gateway uses a single `target` address (no enum). The State Store\n\u003e boundary uses the same seam for symmetry, and **both now require a non-empty `target`**: the\n\u003e State Store's local-store default was withdrawn when the process was extracted (§12 step 7).\n\u003e No `mode` field is added. A companion `STATE_STORE_TOKEN` secret (or a\n\u003e `[services.state] target_token` key) carries authentication.\n\n---\n\n## 11. Local-adapter compatibility + conformance\n\n- `*store.Store` (local) and `*staterpc.Client` (remote) satisfy the **same** contract\n interfaces. Use **explicit** `var _` assertions on **both** adapters (the gateway's local\n adapters use only structural/return-type assertions; the store precedent's explicit `var _`\n style is stronger and should be adopted on both sides).\n ```go\n var _ workflow.Store = (*staterpc.Client)(nil) // first contract to move (agent)\n var _ store.TaskStore = (*staterpc.Client)(nil) // daemon path, added progressively\n var _ store.CaptureStore = (*staterpc.Client)(nil)\n var _ store.MappingStore = (*staterpc.Client)(nil)\n var _ store.BindingStore = (*staterpc.Client)(nil)\n var _ store.BindingDispatcher = (*staterpc.Client)(nil)\n var _ store.BindingTaskCreator = (*staterpc.Client)(nil)\n var _ store.PlaybookDispatcher = (*staterpc.Client)(nil)\n // local side (in store), already present:\n var _ workflow.Store = (*Store)(nil)\n ```\n- **Conformance suite:** a `staterpc/conformance_test.go` bufconn suite runs the **same**\n contract through both `\"local\"` and `\"grpc\"` adapters (mirroring\n `gatewayrpc/conformance_test.go`), asserting error-sentinel fidelity and the\n not-found-as-`(nil,nil)` convention both ways.\n- **`Close()`:** stays on the Go store interfaces (so `TaskStore`/`TaskEvents` remain fully\n satisfiable) but is **not** a `StateStore` RPC. The remote `staterpc.Client` implements\n `Close()` as a **no-op**; the store service owns its own DB lifecycle. When the daemon hands\n the store to `archie-state-store`, `b.cleanup()` no longer calls `store.Close()` on a remote\n client (it is the daemon's own lifecycle only when it owns the store in-process).\n\n---\n\n## 12. Cutover / deletion rules\n\n1. **Ratify the contract (this document).** No code.\n2. **Domain type + interface relocation (prerequisite, coupled with §4).** Move `Task`/`Status`/\n `Source` and the `WorkflowStore` interface into `internal/domain/workflow` (as\n `workflow.Task`/`workflow.Status`/`workflow.Source`/`workflow.Store`), so\n `internal/domain/workflow` imports no `internal/store`. Update the store tests and the 6\n workflow production files. **This must land before or with `.4.2`, because `.4.2` cannot move\n the agent's store contract off `store.WorkflowStore` while the domain still imports it.**\n3. **`.4.2` — generalize `storerpc` to the gRPC contract.** Move the agent's `workflow.Store`\n (`Update`/`Transition`/`InsertEvent`) from NATS JSON `storerpc` to `staterpc.Client` over\n gRPC, using the §6 handoff. The daemon serves the gRPC `StateStore` server **in-process\n (multiplexed)** first so the agent has a gRPC target before the standalone binary exists\n (PRD §3 \"multiplexed in-process is the migration default\"). Bind the in-process listener and\n inject `STATE_STORE_URL`/`STATE_STORE_TOKEN` per task (see §6 \"Operational specifics\"). Also\n land the `RecordDispatch` `*sql.Tx` drop (see §5) in the same span. Flip the agent's\n `Transport.Store` to a gRPC client once `STATE_STORE_URL` is injected.\n4. **Delete NATS `storerpc` only after the agent is fully on gRPC** — delete `internal/storerpc`\n (Server, Client, subjects `archie.store.update|transition|insert_event`), the\n `natsrpc.RegisterAll` registration, and the now-unused `store.WorkflowStore` NATS path in\n `internal/infrastructure/agenttransport/nats`, in the same commit.\n5. **`[services.state].target` stays empty (inproc)** through `.4.2`; the `archie-state-store`\n `cmd/` binary is **`.4.3`** and hosts the same `StateStore` gRPC service.\n6. **Swap daemon-internal contracts one at a time** (only once the daemon points at\n `archie-state-store`): `Capture → Mapping → Binding → TaskStore`. Each swap is independent —\n add the remote-client composition path, run the per-contract conformance suite, flip\n `[services.state].target`, delete the local use. A consumer mixes in-process and remote\n contracts for a contract-code (no dual-live *window*; each contract is either local or remote\n at a time).\n7. **Final flip / deletion of the in-process serving path:** when the daemon no longer owns the\n store (i.e. `TaskStore` has moved), delete the in-process task-store /\n `wireWebStoreSurfaces` path in the daemon in a **same-commit** deletion — no dual-store\n ownership. The single SQLite file remains owned by `archie-state-store`.\n8. **Never** split `archie.db` or add a second store. The gateway keeps its own already-separate\n session SQLite; that is unchanged and out of state-store scope.\n\n---\n\n## 13. Decisions recorded (for the review trail)\n\n- **`internal/store` is a transitional compatibility location** (target\n `internal/infrastructure/store`), not the final infrastructure boundary. The producer-owned\n daemon/webui store surfaces live there now but may relocate with the implementation.\n- **In-process listener + token lifecycle:** the daemon binds the in-process State Store\n listener to the **host-gateway bridge address** when agent containers consume it (the Phase 2\n default) or loopback-only when the daemon is the sole consumer — one listener, one address\n rule, never both (rev. 2c). It selects the bridge address by reusing the embedded-NATS\n host-gateway resolution and injects `STATE_STORE_URL`/`STATE_STORE_TOKEN` per task via\n `containerEnv`. Token is per-incumbence (task + container grace period) and validated by a\n gRPC interceptor → `codes.Unauthenticated` on missing/unknown/expired. Non-loopback targets\n fail closed without TLS or a token.\n- **§12 step 2 (domain type + interface relocation) is done** — `internal/domain/workflow`\n imports no `internal/store` symbol and `store.WorkflowStore` is gone from `TaskContext`. The\n broader Phase 2 acceptance criterion (State Store as its own gRPC service) is still open;\n `.4.2` picks up from here.\n- **Ownership split:** domain-facing workflow contract is **consumer-owned** in the domain\n (`workflow.Store` + `workflow.Task`/`Status`/`Source`, per dependency rules #2 and #7);\n daemon/webui store surfaces stay **producer-owned** in `internal/store`. `store.WorkflowStore`\n is superseded by `workflow.Store`.\n- **One `StateStore` gRPC service** (49 contract RPCs, grouped by contract) + narrow Go consumer facades\n (≤8) on `staterpc.Client` — mirrors the single-`ChatService` precedent.\n- **Domain type relocation** (`Task`/`Status`/`Source` → `internal/domain/workflow`) is a\n Phase 2 prerequisite, pulled forward from migration-decisions §4 (minimal bound,\n `Task → WorkflowExecution`); the rest of §4 stays a separate migration.\n- **`RecordDispatch` drops `*sql.Tx`** (wire-blocker; production passes `nil`) — a\n required interface migration landing before/with `.4.2`.\n- **`Close()` not on the wire**; remote client `Close()` is a no-op.\n- **Structured gRPC error codes** with client rehydration to store sentinels (preserves\n `errors.Is`), a `found=false` + `OK` convention for read not-found, and **sanitised public\n error details** (full detail logged server-side only).\n- **Agent handoff:** `agentworker.Settings` gains `StateStoreTarget`/`StateStoreToken`/\n `StoreTimeout`, injected as `STATE_STORE_URL`/`STATE_STORE_TOKEN` env (mirrors the NATS\n handoff); `Transport.Store` returns a long-lived gRPC `workflow.Store` client.\n- **Transport security + listener topology (rev. 2c):** one in-process listener, bound to the\n host-gateway bridge address when agent containers consume it (the Phase 2 default) or\n loopback-only for a daemon-local-only consumer. `insecure` only on loopback; mandatory\n per-task bearer-token auth on the bridge; TLS/mTLS is an operator choice for any\n non-loopback/k8s topology.\n- **Mode = presence-based `[services.state].target`**, default **local** (not yet extracted);\n add `[services.state]` to `config.example.toml`.\n- **Explicit `var _` assertions on both adapters**; per-contract bufconn conformance.\n- **Migration order:** domain type/interface relocation → `workflow.Store` (agent) → stand up\n `archie-state-store` → `Capture` → `Mapping` → `Binding` → `TaskStore`; NATS `storerpc`\n deleted once the agent is on gRPC; in-process store path deleted in a same-commit flip.\n- **Orphans `ClearTerminalTasks`/`IncrementRetryCount`** retained but not built upon.\n" }, { "url": "/dev/prds/status-health-surface/", @@ -430,7 +430,7 @@ "url": "/dev/prds/task-run-detail/", "title": "Per-run task detail: attempts, stages, changes, config, debug", "section": "PRDs", - "body": "# Per-run task detail: attempts, stages, changes, config, debug\n\n**Status:** Approved\n**Authority:** the surface contract itself is\n`docs/architecture/observability.md`.\n**Date:** 2026-09-18\n**Compounds with:** `docs/prds/task-logs-pagination.md` (a bounded read says\nwhat it does not show), `docs/prds/status-health-surface.md` (no surface that\nanswers something already answered elsewhere).\n\n## Decision\n\nA task gets one detail page that answers \"what did this run actually do?\" per\n**attempt**: an ordered stage rail, the change each commit/push produced, the\neffective configuration the attempt ran under, the attempt's log, and the raw\nrecord behind all of it.\n\nThe single organising idea is **attempt attribution**. The dashboard\nrenders a task's whole event stream as one flat timeline, so a retried task\nreads as one long run with two of everything. Every new panel is scoped to one\nattempt and says which one.\n\nThe second organising idea is **provenance, not re-derivation**. What a run\nproduced is captured at the producer, while the evidence exists, and persisted\ndurably. Nothing in this surface tries to reconstruct a past run from state\nthat has since moved on.\n\n## The requirement set\n\n| # | Requirement | Mechanism |\n| --- | --- | --- |\n| R1 | Per-attempt stage rail: stages with name, start, duration, terminal status and error, ordered within one attempt | `GET /api/tasks/{id}/attempts` reads the task's events and groups them by `attempt` |\n| R2 | Events carry an attempt, migrated safely and carried on the wire | `events.attempt` column + presence-gated migrator arm; `Event.attempt = 11` |\n| R3 | Changed files captured at commit/push, persisted per task, exposed, shown with repo/PR links | `changes_captured` durable event written by the commit/push steps; `GET /api/tasks/{id}/changes` |\n| R4 | The effective configuration an attempt ran under, secrets redacted, shown | `config_captured` durable event written once per attempt; read from the events response the page already holds |\n| R5 | Log pane filters by attempt, stage and level; absence stays distinct from an unreadable deployment | `logging.Query.Stage` + `ReadTaskLogRequest.stage = 9`; the pane keeps `disabled` and `found=false` apart |\n| R6 | Retry is reachable from the run view and produces a new attempt shown as a new run | Existing retry action, labelled as a NEW run whose confirm states the previous attempt's commits are discarded |\n| R7 | Raw JSON of the task record and its events for the selected attempt | `GET /api/tasks/{id}/debug` |\n| R8 | Deep-linkable, reload-safe per-task detail page that keeps existing URLs working | `/tasks/{id}` route beside the existing `/tasks?task=N` and `/tasks?status=...` |\n| R9 | Design polish: hierarchy, tokens, both themes, responsive rail, a11y, loading/empty/error states | UI lane; measured at 480px and 700px in both themes |\n| R10 | Documentation of record | This document plus `docs/architecture/observability.md` |\n| R11 | Red-first tests for every new behaviour, full gate, `task ui`, forced `go build ./...`, `go test -race` on touched packages | Per lane; the anti-cost-cutting requirement lives here |\n\n## Attempt attribution: a column, not a guess\n\n`events.Event.Attempt`, persisted by `internal/store` as the `events.attempt`\ncolumn (`internal/store/events.go`, `eventsSchema`), is a real column,\n`NOT NULL DEFAULT 0`. It was chosen over segmenting the stream on `task_queued` /\n`task_retried` because a fold would have to guess which side of a boundary an\nevent belongs to when the daemon restarts mid-attempt, when `RecoverStale`\nrequeues, or when two attempts interleave across a crash. A guess rendered as\nstructure is exactly the false fidelity this surface exists to avoid; a column\nis durable, queryable and ordered by construction.\n\n**`0` means \"not attributable\".** It is every row written before this change\nplus the deliberately task-agnostic producers. It is not an attempt number and\nis never rendered as one. The attempts endpoint reports the count of\nunattributed events so the page can say so instead of presenting old history as\nattempt 1.\n\n## Migration against an existing `archie.db`\n\nThe store's migrator (`migrateTasks` in `internal/store/store.go`) already reads\n`PRAGMA table_info` through `tableColumns` and applies a presence-gated\n`ALTER TABLE ... ADD COLUMN` list. This change adds an `events` arm: a\n`tableColumns(ctx, tx, \"events\")` read beside the other two, and the entry\n`ALTER TABLE events ADD COLUMN attempt INTEGER NOT NULL DEFAULT 0`.\n\nThree consequences a future maintainer must not get wrong:\n\n- `eventsSchema` is `CREATE TABLE IF NOT EXISTS` (`internal/store/events.go`),\n so on an existing database it is a **no-op**. The migrator arm is the only\n thing that adds the column there. This is why the red test builds a raw\n SQLite file with the pre-change `events` DDL and must fail before the arm\n exists: every temp-database test passes either way.\n- **`user_version` stays 3.** The loop is presence-gated, not version-gated;\n bumping it would force an edit to the test that exists to prove a newer\n schema is refused.\n- **No backfill, ever.** Existing rows keep `attempt = 0`. Inferring an attempt\n number for them would be fabrication.\n\n## Changed files: captured at the producer\n\nThe measurement is taken inside the shared step library immediately after a\nsuccessful commit and after a successful push (`StageCommit` and\n`StageCommitPush` in `internal/domain/workflow/steps.go`) — the one place\nwhere the worktree, the branch, the base, the task and the store are all in\nscope, and the only place that knows a push actually happened.\n\nBoth alternatives were rejected on evidence, not taste:\n\n- **Reading the diff on demand** is impossible. The worktree is deleted on\n merge, close and no-PR terminal states (`internal/worktree.(*Manager).Cleanup`,\n called from the daemon's terminal paths) and a retry resets the branch onto\n its base (`internal/worktree.(*Manager).refresh` → `resetOnto`). There is\n nothing left to read.\n- **Reading it from the forge** is impossible. The forge contract exposes\n no changed-file capability, and adding one would cost three implementations\n plus an RPC and would still fail for chat-sourced tasks with no PR.\n\nBinding consequences:\n\n- Capture **degrades, never parks**. A `Trees` implementation without the\n capture seam captures nothing, logs, and lets the run continue. A reporting\n failure must never fail a task.\n- The value types live in `internal/domain/workflow/task` (`changes.go`), not in\n package `workflow` and not in `internal/worktree`. Package `workflow` has no\n import of `internal/worktree`, and this subpackage is not projected into the\n interpreted-stage symbol table, so declaring the types here widens nothing and\n needs no symbol-table regeneration. The capture method stays off that surface\n entirely.\n- `files` is capped at 200 entries because an event's `data` is not\n length-limited by the store. `totals` always covers the **full** set and\n `truncated: true` says when entries were dropped.\n- `binary` means \"no textual hunks\", not \"a binary file\". Rename pairing is\n go-git behaviour the lane pins with a test; where the repository records a\n rename as add + delete, the surface reports what was recorded.\n\n## Per-run configuration: a durable event, not a table\n\n**Decision.** The effective configuration an attempt ran under is persisted as a\n`config_captured` durable event (`internal/events.KindConfigCaptured`), on the\nsame attempt key R2 adds — not in a table, and not behind new RPCs.\n\n**Why.** Three reasons, in order of weight:\n\n1. Events are already this system's durable per-attempt provenance stream, and\n they demonstrably carry aggregation (`StageStats`, `TokensByDay` both\n aggregate over persisted events). R3 puts its diffstat there in this same\n change. A table plus two RPCs would have given one feature **two provenance\n mechanisms for one purpose**.\n2. It adds no RPC, so the ratified state-store surface is untouched and nothing\n in `docs/prds/state-store-contract.md` (rev 2c) changes.\n3. The page already fetches the task's events to build the rail (R1) and to read\n the diffstat (R3), so the document arrives in a fetch it already makes. There\n is nothing to join.\n\nThe single-row `config_snapshot` table is deliberately **left alone**. It\nanswers \"what is the running configuration now\", is replaced on every publish,\nand is pinned to one row by a test. It could not answer \"what did attempt 2 run\nunder\" in any case.\n\n**Payload.** The result of `config.Config.ForTask()` — the non-secret\ntask-runtime subset — plus the schema constant `archie/task-config@1`. Not the\ndashboard's configuration view: that is a larger projection carrying the full\nschema catalog, and it is the wrong object for this. Stored shape and the tab's\nread rule are in `docs/architecture/observability.md`.\n\n**Binding conditions.** It is emitted through the durable path, never the\nlossy bus; it is written once per attempt, not once per stage; redaction is\nproven **positively** by a canary-secrets test rather than assumed from the\nproducer's contract; the timeline gains one human line for it rather than\ndumping a JSON blob; and an attempt with no such event renders \"not captured for\nthis run\", never an empty table implying defaults applied.\n\n**Documented residual — the honest trust claim.** A task-scoped grant may insert\nevents on its own task ID; that is how `tool_call` and `agent_finish` already\nwork, so a task can in principle write its own `config_captured` event. This\n**widens no capability** — the grant could already insert arbitrary events on\nitself — but it does mean this provenance is exactly as trustworthy as the rest\nof that task's event stream, and no more. It is not tamper-proofing and must\nnever be described as such.\n\n## No new RPC and no new table\n\nThe entire wire change is two fields on existing messages:\n\n```proto\n// proto/state/v1/state.proto\nmessage Event { int64 attempt = 11; }\nmessage ReadTaskLogRequest { string stage = 9; }\n```\n\nNo RPC was added, no store table was added, and no new configuration field was\nintroduced. `docs/prds/state-store-contract.md` is unchanged because no ratified\ncontract changed; the JSON document rides an existing `data` column over an\nexisting RPC.\n\nBoth fields are tolerant in both directions, and the degrade is stated rather\nthan hidden: an old server makes `attempt` read as `0` and `stage` match\nnothing, so the page must say the deployment cannot attribute events to attempts\nrather than show one run labelled \"attempt 1\". An old client shows\n`config_captured` as an unknown kind, and the Config tab must then say \"this\ndeployment cannot read per-run configuration\" — a different claim from \"not\ncaptured for this attempt\".\n\n## Retry is a new run\n\nThe retry action is reachable from the run view and produces a new attempt that\nappears as a new run. It is a **fresh** run: it resets the branch onto\n`origin/\u003cbase\u003e` (`internal/worktree.(*Manager).refresh` → `resetOnto`) and\n**discards the previous attempt's commits**. Labelling it \"restart\" would imply\nresumption that does not happen, so the control and its confirm copy say so.\n\n## Honest limits the surface carries\n\nThese are the claims that would otherwise be overstated. Each is a copy or\nrendering rule, not a caveat in a comment:\n\n- **There is no exit code, so no stage shows pass/fail.** `stage_finish` carries\n a duration and an optional error string and nothing else. A stage `ok` means\n \"returned without error\", not \"the work was correct\". The agent's own verdict\n is shown separately from the rail. A stage that parks after finishing cleanly\n leaves that stage `ok` on a failed task, so attempt status is read together\n with task status.\n- **The log stage filter only matches lines the workflow bound a stage to.**\n Agent and tool output carries no stage and never matches. The pane states that\n coverage limit next to the control rather than presenting a filtered view as\n the whole story.\n- **Absence and unreadability are different answers.** A deployment that cannot\n read task logs says so; an attempt whose log does not exist says that. They\n are never collapsed, in either direction, for logs or for configuration.\n- **An empty changed-files view never means \"nothing changed\".** No capture\n exists for runs predating this change and the forge cannot supply one, so the\n empty state reads \"not captured for this run\".\n- **No run-duration figure is shown.** Per-stage durations only: a run can spend\n days in `waiting_human`, and one number would understate wall time.\n- **No duration is invented** for a stage with no `stage_start`; it reads \"not\n recorded\".\n- **Unattributed history is never presented as an attempt.** Events with\n `attempt = 0` are reported as a count, not guessed into a run.\n- **The configuration shown is the attempt's non-secret task-runtime subset** —\n bot identity, models, limits, budgets, dispatch, diff cap, notifications,\n forge host, tool policy. It is not the full dashboard configuration and must\n never imply it contains providers, repositories, identities or credentials.\n\n## Route and compatibility\n\n`/tasks/{id}` is the detail route; it is deep-linkable and reload-safe.\n`/tasks?task=N` and `/tasks?status=...` keep working and keep their existing\nbehaviour, including the nav highlight. The debug view is why the raw view\nexists at all: the task list response is capped, so a client-side join has no\nrow for an older task, and a debug view that silently hid events would be worse\nthan useless.\n\n## What this deliberately does not do\n\n- **No new RPC, table, store interface or configuration field.** Nothing here\n needed one, and each would have widened a ratified surface.\n- **No exit status, no pass/fail gate badge, no \"steps\" in the CI sense.** The\n reference layout is a CI pipeline; archie's stages are agent runs and the page\n must not borrow CI's claims.\n- **No backfill** of attempts, change captures or configurations onto runs that\n predate the change.\n- **No client-side join for configuration.** It arrives in the events response\n the page already fetches; there is nothing to join.\n- **No change to `docs/prds/state-store-contract.md`.** No ratified contract\n moved.\n\n## Files this change touches\n\n- `internal/store/`: the `events.attempt` column, its migrator arm, and the\n schema-presence test.\n- `internal/events/`: `Event.Attempt`, `KindChangesCaptured`,\n `KindConfigCaptured`, `ConfigCapturedSchema`.\n- `internal/domain/workflow/task/changes.go`: the change value types.\n- `internal/worktree/` + `internal/app/agentworker/`: the capture primitive and\n its production forwarding.\n- `internal/domain/workflow/steps.go`: the capture at commit and push.\n- `internal/daemon/`: the per-attempt configuration emit at dispatch.\n- `internal/logging/`: `Query.Stage`.\n- `internal/webui/`: the three read endpoints and the `stage` log parameter.\n- `proto/state/v1/state.proto` + generated stubs: the two field additions.\n- `ui/src/`: the detail page, the tab primitive, the rail, and the panel copy.\n- `docs/`: this document and `docs/architecture/observability.md`.\n\n## Acceptance\n\n1. Two attempts of one task render as two runs, and attempt 1's rail excludes\n attempt 2's stages.\n2. A task with no stages renders \"no stages recorded\", never an unexplained\n empty rail.\n3. A pre-change `archie.db` gains the `attempt` column with `user_version`\n still 3, and its old events are reported as unattributed.\n4. An attempt with a capture shows per-file added/deleted counts, status, repo\n and PR links; an attempt without one says so and never says \"no changes\".\n5. The Config tab shows the attempt's document for the selected attempt only,\n with no secret value present in the serialized document.\n6. Retry from the run view produces a new attempt shown as a new run, with copy\n stating the previous attempt's commits are discarded.\n7. The log stage filter narrows to stage-bound lines and the pane states the\n coverage limit; `disabled` and `found=false` remain distinguishable.\n8. `/tasks/{id}` survives reload, and `/tasks?task=N` / `/tasks?status=...`\n are unchanged.\n9. The debug view returns the task record and its unfiltered events, each\n carrying `attempt`.\n10. Run the gate and the dashboard build: `task check` passes clean, `task ui`\n has been run so `ui/dist` matches the sources, and every touched package\n builds and passes under `-race`.\n" + "body": "# Per-run task detail: attempts, stages, changes, config, debug\n\n**Status:** Approved\n**Authority:** the surface contract itself is\n`docs/architecture/observability.md`.\n**Date:** 2026-09-18\n**Compounds with:** `docs/prds/task-logs-pagination.md` (a bounded read says\nwhat it does not show), `docs/prds/status-health-surface.md` (no surface that\nanswers something already answered elsewhere).\n\n## Decision\n\nA task gets one detail page that answers \"what did this run actually do?\" per\n**attempt**: an ordered stage rail, the change each commit/push produced, the\neffective configuration the attempt ran under, the attempt's log, and the raw\nrecord behind all of it.\n\nThe single organising idea is **attempt attribution**. The dashboard\nrenders a task's whole event stream as one flat timeline, so a retried task\nreads as one long run with two of everything. Every new panel is scoped to one\nattempt and says which one.\n\nThe second organising idea is **provenance, not re-derivation**. What a run\nproduced is captured at the producer, while the evidence exists, and persisted\ndurably. Nothing in this surface tries to reconstruct a past run from state\nthat has since moved on.\n\n## The requirement set\n\n| # | Requirement | Mechanism |\n| --- | --- | --- |\n| R1 | Per-attempt stage rail: stages with name, start, duration, terminal status and error, ordered within one attempt | `GET /api/tasks/{id}/attempts` reads the task's events and groups them by `attempt` |\n| R2 | Events carry an attempt, migrated safely and carried on the wire | `events.attempt` column + presence-gated migrator arm; `Event.attempt = 11` |\n| R3 | Changed files captured at commit/push, persisted per task, exposed, shown with repo/PR links | `changes_captured` durable event written by the commit/push steps; `GET /api/tasks/{id}/changes` |\n| R4 | The effective configuration an attempt ran under, secrets redacted, shown | `config_captured` durable event written once per attempt; read from the events response the page already holds |\n| R5 | Log pane filters by attempt, stage and level; absence stays distinct from an unreadable deployment | `logging.Query.Stage` + `ReadTaskLogRequest.stage = 9`; the pane keeps `disabled` and `found=false` apart |\n| R6 | Retry is reachable from the run view and produces a new attempt shown as a new run | Existing retry action, labelled as a NEW run whose confirm states the previous attempt's commits are discarded |\n| R7 | Raw JSON of the task record and its events for the selected attempt | `GET /api/tasks/{id}/debug` |\n| R8 | Deep-linkable, reload-safe per-task detail page that keeps existing URLs working | `/tasks/{id}` route beside the existing `/tasks?task=N` and `/tasks?status=...` |\n| R9 | Design polish: hierarchy, tokens, both themes, responsive rail, a11y, loading/empty/error states | UI lane; measured at 480px and 700px in both themes |\n| R10 | Documentation of record | This document plus `docs/architecture/observability.md` |\n| R11 | Red-first tests for every new behaviour, full gate, `task ui`, forced `go build ./...`, `go test -race` on touched packages | Per lane; the anti-cost-cutting requirement lives here |\n\n## Attempt attribution: a column, not a guess\n\n`events.Event.Attempt`, persisted as the `events.attempt` column\n(`internal/infrastructure/postgres/migrations/0001_state_store.sql`), is a real column,\n`NOT NULL DEFAULT 0`. It was chosen over segmenting the stream on `task_queued` /\n`task_retried` because a fold would have to guess which side of a boundary an\nevent belongs to when the daemon restarts mid-attempt, when `RecoverStale`\nrequeues, or when two attempts interleave across a crash. A guess rendered as\nstructure is exactly the false fidelity this surface exists to avoid; a column\nis durable, queryable and ordered by construction.\n\n**`0` means \"not attributable\".** It is every row written before this change\nplus the deliberately task-agnostic producers. It is not an attempt number and\nis never rendered as one. The attempts endpoint reports the count of\nunattributed events so the page can say so instead of presenting old history as\nattempt 1.\n\n## Migration against an existing `archie.db`\n\n\u003e Storage superseded: every store now lives in PostgreSQL behind\n\u003e `internal/domain/storecontract`, implemented in `internal/infrastructure/postgres`\n\u003e (`docs/prds/state-store-contract.md`). SQLite names below describe the\n\u003e original design.\n\nThe store's migrator (`migrateTasks` in `internal/store/store.go`) already reads\n`PRAGMA table_info` through `tableColumns` and applies a presence-gated\n`ALTER TABLE ... ADD COLUMN` list. This change adds an `events` arm: a\n`tableColumns(ctx, tx, \"events\")` read beside the other two, and the entry\n`ALTER TABLE events ADD COLUMN attempt INTEGER NOT NULL DEFAULT 0`.\n\nThree consequences a future maintainer must not get wrong:\n\n- `eventsSchema` is `CREATE TABLE IF NOT EXISTS` (`internal/store/events.go`),\n so on an existing database it is a **no-op**. The migrator arm is the only\n thing that adds the column there. This is why the red test builds a raw\n SQLite file with the pre-change `events` DDL and must fail before the arm\n exists: every temp-database test passes either way.\n- **`user_version` stays 3.** The loop is presence-gated, not version-gated;\n bumping it would force an edit to the test that exists to prove a newer\n schema is refused.\n- **No backfill, ever.** Existing rows keep `attempt = 0`. Inferring an attempt\n number for them would be fabrication.\n\n## Changed files: captured at the producer\n\nThe measurement is taken inside the shared step library immediately after a\nsuccessful commit and after a successful push (`StageCommit` and\n`StageCommitPush` in `internal/domain/workflow/steps.go`) — the one place\nwhere the worktree, the branch, the base, the task and the store are all in\nscope, and the only place that knows a push actually happened.\n\nBoth alternatives were rejected on evidence, not taste:\n\n- **Reading the diff on demand** is impossible. The worktree is deleted on\n merge, close and no-PR terminal states (`internal/worktree.(*Manager).Cleanup`,\n called from the daemon's terminal paths) and a retry resets the branch onto\n its base (`internal/worktree.(*Manager).refresh` → `resetOnto`). There is\n nothing left to read.\n- **Reading it from the forge** is impossible. The forge contract exposes\n no changed-file capability, and adding one would cost three implementations\n plus an RPC and would still fail for chat-sourced tasks with no PR.\n\nBinding consequences:\n\n- Capture **degrades, never parks**. A `Trees` implementation without the\n capture seam captures nothing, logs, and lets the run continue. A reporting\n failure must never fail a task.\n- The value types live in `internal/domain/workflow/task` (`changes.go`), not in\n package `workflow` and not in `internal/worktree`. Package `workflow` has no\n import of `internal/worktree`, and this subpackage is not projected into the\n interpreted-stage symbol table, so declaring the types here widens nothing and\n needs no symbol-table regeneration. The capture method stays off that surface\n entirely.\n- `files` is capped at 200 entries because an event's `data` is not\n length-limited by the store. `totals` always covers the **full** set and\n `truncated: true` says when entries were dropped.\n- `binary` means \"no textual hunks\", not \"a binary file\". Rename pairing is\n go-git behaviour the lane pins with a test; where the repository records a\n rename as add + delete, the surface reports what was recorded.\n\n## Per-run configuration: a durable event, not a table\n\n**Decision.** The effective configuration an attempt ran under is persisted as a\n`config_captured` durable event (`internal/events.KindConfigCaptured`), on the\nsame attempt key R2 adds — not in a table, and not behind new RPCs.\n\n**Why.** Three reasons, in order of weight:\n\n1. Events are already this system's durable per-attempt provenance stream, and\n they demonstrably carry aggregation (`StageStats`, `TokensByDay` both\n aggregate over persisted events). R3 puts its diffstat there in this same\n change. A table plus two RPCs would have given one feature **two provenance\n mechanisms for one purpose**.\n2. It adds no RPC, so the ratified state-store surface is untouched and nothing\n in `docs/prds/state-store-contract.md` (rev 2c) changes.\n3. The page already fetches the task's events to build the rail (R1) and to read\n the diffstat (R3), so the document arrives in a fetch it already makes. There\n is nothing to join.\n\nThe single-row `config_snapshot` table is deliberately **left alone**. It\nanswers \"what is the running configuration now\", is replaced on every publish,\nand is pinned to one row by a test. It could not answer \"what did attempt 2 run\nunder\" in any case.\n\n**Payload.** The result of `config.Config.ForTask()` — the non-secret\ntask-runtime subset — plus the schema constant `archie/task-config@1`. Not the\ndashboard's configuration view: that is a larger projection carrying the full\nschema catalog, and it is the wrong object for this. Stored shape and the tab's\nread rule are in `docs/architecture/observability.md`.\n\n**Binding conditions.** It is emitted through the durable path, never the\nlossy bus; it is written once per attempt, not once per stage; redaction is\nproven **positively** by a canary-secrets test rather than assumed from the\nproducer's contract; the timeline gains one human line for it rather than\ndumping a JSON blob; and an attempt with no such event renders \"not captured for\nthis run\", never an empty table implying defaults applied.\n\n**Documented residual — the honest trust claim.** A task-scoped grant may insert\nevents on its own task ID; that is how `tool_call` and `agent_finish` already\nwork, so a task can in principle write its own `config_captured` event. This\n**widens no capability** — the grant could already insert arbitrary events on\nitself — but it does mean this provenance is exactly as trustworthy as the rest\nof that task's event stream, and no more. It is not tamper-proofing and must\nnever be described as such.\n\n## No new RPC and no new table\n\nThe entire wire change is two fields on existing messages:\n\n```proto\n// proto/state/v1/state.proto\nmessage Event { int64 attempt = 11; }\nmessage ReadTaskLogRequest { string stage = 9; }\n```\n\nNo RPC was added, no store table was added, and no new configuration field was\nintroduced. `docs/prds/state-store-contract.md` is unchanged because no ratified\ncontract changed; the JSON document rides an existing `data` column over an\nexisting RPC.\n\nBoth fields are tolerant in both directions, and the degrade is stated rather\nthan hidden: an old server makes `attempt` read as `0` and `stage` match\nnothing, so the page must say the deployment cannot attribute events to attempts\nrather than show one run labelled \"attempt 1\". An old client shows\n`config_captured` as an unknown kind, and the Config tab must then say \"this\ndeployment cannot read per-run configuration\" — a different claim from \"not\ncaptured for this attempt\".\n\n## Retry is a new run\n\nThe retry action is reachable from the run view and produces a new attempt that\nappears as a new run. It is a **fresh** run: it resets the branch onto\n`origin/\u003cbase\u003e` (`internal/worktree.(*Manager).refresh` → `resetOnto`) and\n**discards the previous attempt's commits**. Labelling it \"restart\" would imply\nresumption that does not happen, so the control and its confirm copy say so.\n\n## Honest limits the surface carries\n\nThese are the claims that would otherwise be overstated. Each is a copy or\nrendering rule, not a caveat in a comment:\n\n- **There is no exit code, so no stage shows pass/fail.** `stage_finish` carries\n a duration and an optional error string and nothing else. A stage `ok` means\n \"returned without error\", not \"the work was correct\". The agent's own verdict\n is shown separately from the rail. A stage that parks after finishing cleanly\n leaves that stage `ok` on a failed task, so attempt status is read together\n with task status.\n- **The log stage filter only matches lines the workflow bound a stage to.**\n Agent and tool output carries no stage and never matches. The pane states that\n coverage limit next to the control rather than presenting a filtered view as\n the whole story.\n- **Absence and unreadability are different answers.** A deployment that cannot\n read task logs says so; an attempt whose log does not exist says that. They\n are never collapsed, in either direction, for logs or for configuration.\n- **An empty changed-files view never means \"nothing changed\".** No capture\n exists for runs predating this change and the forge cannot supply one, so the\n empty state reads \"not captured for this run\".\n- **No run-duration figure is shown.** Per-stage durations only: a run can spend\n days in `waiting_human`, and one number would understate wall time.\n- **No duration is invented** for a stage with no `stage_start`; it reads \"not\n recorded\".\n- **Unattributed history is never presented as an attempt.** Events with\n `attempt = 0` are reported as a count, not guessed into a run.\n- **The configuration shown is the attempt's non-secret task-runtime subset** —\n bot identity, models, limits, budgets, dispatch, diff cap, notifications,\n forge host, tool policy. It is not the full dashboard configuration and must\n never imply it contains providers, repositories, identities or credentials.\n\n## Route and compatibility\n\n`/tasks/{id}` is the detail route; it is deep-linkable and reload-safe.\n`/tasks?task=N` and `/tasks?status=...` keep working and keep their existing\nbehaviour, including the nav highlight. The debug view is why the raw view\nexists at all: the task list response is capped, so a client-side join has no\nrow for an older task, and a debug view that silently hid events would be worse\nthan useless.\n\n## What this deliberately does not do\n\n- **No new RPC, table, store interface or configuration field.** Nothing here\n needed one, and each would have widened a ratified surface.\n- **No exit status, no pass/fail gate badge, no \"steps\" in the CI sense.** The\n reference layout is a CI pipeline; archie's stages are agent runs and the page\n must not borrow CI's claims.\n- **No backfill** of attempts, change captures or configurations onto runs that\n predate the change.\n- **No client-side join for configuration.** It arrives in the events response\n the page already fetches; there is nothing to join.\n- **No change to `docs/prds/state-store-contract.md`.** No ratified contract\n moved.\n\n## Files this change touches\n\n- the State Store schema: the `events.attempt` column.\n- `internal/events/`: `Event.Attempt`, `KindChangesCaptured`,\n `KindConfigCaptured`, `ConfigCapturedSchema`.\n- `internal/domain/workflow/task/changes.go`: the change value types.\n- `internal/worktree/` + `internal/app/agentworker/`: the capture primitive and\n its production forwarding.\n- `internal/domain/workflow/steps.go`: the capture at commit and push.\n- `internal/daemon/`: the per-attempt configuration emit at dispatch.\n- `internal/logging/`: `Query.Stage`.\n- `internal/webui/`: the three read endpoints and the `stage` log parameter.\n- `proto/state/v1/state.proto` + generated stubs: the two field additions.\n- `ui/src/`: the detail page, the tab primitive, the rail, and the panel copy.\n- `docs/`: this document and `docs/architecture/observability.md`.\n\n## Acceptance\n\n1. Two attempts of one task render as two runs, and attempt 1's rail excludes\n attempt 2's stages.\n2. A task with no stages renders \"no stages recorded\", never an unexplained\n empty rail.\n3. A pre-change `archie.db` gains the `attempt` column with `user_version`\n still 3, and its old events are reported as unattributed.\n4. An attempt with a capture shows per-file added/deleted counts, status, repo\n and PR links; an attempt without one says so and never says \"no changes\".\n5. The Config tab shows the attempt's document for the selected attempt only,\n with no secret value present in the serialized document.\n6. Retry from the run view produces a new attempt shown as a new run, with copy\n stating the previous attempt's commits are discarded.\n7. The log stage filter narrows to stage-bound lines and the pane states the\n coverage limit; `disabled` and `found=false` remain distinguishable.\n8. `/tasks/{id}` survives reload, and `/tasks?task=N` / `/tasks?status=...`\n are unchanged.\n9. The debug view returns the task record and its unfiltered events, each\n carrying `attempt`.\n10. Run the gate and the dashboard build: `task check` passes clean, `task ui`\n has been run so `ui/dist` matches the sources, and every touched package\n builds and passes under `-race`.\n" }, { "url": "/dev/prds/task-run-master-detail/", @@ -442,7 +442,7 @@ "url": "/dev/prds/ui-service-boundary/", "title": "UI Service boundary and configuration ownership", "section": "PRDs", - "body": "# UI Service boundary and configuration ownership\n\n**Status:** Approved\n**Revision:** 1\n**Date:** 2026-09-07\n**Beads issue:** `archie-core-8cda.5.1`\n**Parent:** [`service-decomposition.md`](/dev/prds/service-decomposition/)\n**Prerequisites:** Gateway contract extraction and State Store contract ratification\n\nThis document is the authority for Phase 3 UI Service implementation. It fixes\nthe process boundary, configuration ownership, client contracts, security\nposture, readiness behavior, and migration evidence required by\n`archie-core-8cda.5.2` and later UI extraction work.\n\n## Decision\n\nThe UI Service owns the operator-facing HTTP surface and the compiled SPA. It\nserves `ui/dist` and exposes UI-specific JSON DTOs for dashboard views and\nactions. It does not own conversations, task state, workflow execution,\nchannel lifecycle, forge access, or the daemon's runtime configuration.\n\nThe UI Service consumes two typed remote capabilities:\n\n- Gateway's `gateway.ChatContract` through the versioned Gateway gRPC\n contract, for chat snapshots, messages, turns, streaming, persona changes,\n cancellation, and Gateway task actions.\n- State Store's narrow read/write contracts through the versioned State Store\n gRPC contract, for task views, events, captures, mappings, bindings, and\n configuration data explicitly projected for the dashboard.\n\nThe UI process may compose local adapters during the migration seam, but the\nadapter implements the same wire-safe contract as the remote client. The\nproduction extraction cutover removes the in-process adapter in the same\nchange; a dual-live UI authority is not permitted.\n\n## Boundary and ownership\n\n| Concern | UI Service owns | UI Service may consume | UI Service must not own or receive |\n|---|---|---|---|\n| HTTP and SPA | routes, auth middleware, UI DTOs, assets, HTTP lifecycle | contract results and health snapshots | domain entities or infrastructure handles |\n| Chat | request validation and response projection | Gateway `ChatContract` | `gateway.Router`, `SessionStore`, turn runner, model/provider runtime |\n| Task dashboard | query/action DTOs and HTTP status mapping | State Store narrow contracts and explicitly ratified task-action contract | `*store.Store`, SQL connections, workflow registry, daemon pointer |\n| Configuration page | secret-free view and update request validation | a UI configuration contract owned by the configuration/application boundary | `config.Config`, `config.Holder`, secret registry, reload implementation |\n| Readiness | UI process liveness and dependency readiness aggregation | bounded health results from Gateway and State Store | direct probing of private databases or providers |\n\nEvery value crossing the process boundary is a versioned DTO or scalar contract\nvalue. `internal/webui` may retain temporary Go-side adapters while the\nmigration is in progress, but handlers must map Gateway/State Store values to\nUI-owned response types at the HTTP edge. A constructor accepting a concrete\nGateway, State Store, daemon, or `config.Holder` is not an approved final\nboundary.\n\nThe existing UI routes remain behaviorally compatible during extraction,\nincluding task actions, SSE event delivery, config views, chat streaming,\ncapture intake, mappings, bindings, update reporting, and health endpoints.\nCompatibility preserves status codes, authentication requirements, redaction,\npagination/limits, event ordering, and failure degradation unless a separately\nratified contract changes them.\n\nThe route families have these target owners. This is the required inventory for\nthe implementation children; a route without an owner is not eligible for\ncutover.\n\n| Route family | Target owner consumed by UI | Migration status |\n|---|---|---|\n| `/api/chat/*` | Gateway `ChatContract` and its versioned client | contract seam exists; DTO and stream parity remain |\n| `/api/tasks/*`, `/api/workflows`, `/api/setup` | State Store read/action contracts plus an explicit execution/admin action contract | State Store adapter exists; UI-facing narrow surface remains |\n| `/events` | State Store `EventsSince`, polled by one UI-process pump feeding `Server.Broadcast` | RESOLVED (`archie-core-za9f`): see migration-decisions, \"Dashboard live event delivery\". No new RPC; replay cursor and drop-recovery are the existing `since` watermark in `sse.go` |\n| `/api/logs`, `/api/logs/stream` | daemon diagnostic feed, host-local | unresolved: `logging.Feed` is in-process on the daemon host and has no contract. The per-task log routes moved off this row: see `/api/tasks/*` above |\n| `/api/tasks/{id}/logs`, `/api/tasks/{id}/logs/download` | State Store task-log read contract (`TaskLogStore`: `ReadTaskLog` + `StreamTaskLogContent`), read by the UI process from the service that owns the state directory | RESOLVED (`archie-core-iaqx`): the UI process composes `TaskLogStore` from its own State Store client and serves the attempt log as JSON (`found` distinguishes \"no log for this attempt\" from \"this process cannot read logs\") and as a `Content-Disposition` attachment named `task-\u003cid\u003e-attempt-\u003cn\u003e.log`. The daemon's in-process registry is wired as the server-side reader in `internal/app/archied/state_store.go` only (`staterpc.Deps.TaskLogs`), so no process opens another process's log files |\n| `/api/captures`, `/api/mappings`, `/api/bindings` | State Store contracts, with webhook verification owned by Work Intake/Messaging | RESOLVED (cutover, `archie-core-8cda.5.4`): the UI process composes CaptureStore/MappingStore/BindingStore and mounts the `captureintake.Receiver` from its own State Store client; the daemon's binding-dispatch loop keeps consuming captures from the same store |\n| `/api/config` (read) | daemon-published `ConfigView` snapshot, read over the State Store contract | RESOLVED (`archie-core-ymut`): see migration-decisions, \"Dashboard configuration page\" |\n| `/api/config` (write), `/api/config/reset`, `/api/config/repos/*` | a configuration write contract; the daemon stays the policy owner | DESCOPED for Phase 3 (`archie-core-ymut`), NOT abandoned: 503 in the UI process, SPA hides the controls, editing is config.toml plus reload. Dashboard editing is a tracked feature (`archie-core-1786637498420-327`) and its transport is `archie-core-j28m`; the handlers and their func-field seams on `webui.Server` are kept for it |\n| `/api/channels`, reload, curators, memory, skills, version/update | owning capability contract or an explicitly removed route | owner and failure semantics remain to define |\n| `/`, `/healthz`, `/health`, `/health/detailed` | UI HTTP process; readiness consumes per-service health contracts | current HTTP behavior is the compatibility baseline |\n\n## Configuration ownership\n\nThe UI Service owns only process-local settings:\n\n- HTTP listen address and read/header/shutdown timeouts;\n- UI asset source or build mode;\n- UI authentication mode and token reference;\n- Gateway endpoint and credential reference;\n- State Store endpoint and credential reference;\n- readiness endpoint and dependency timeout policy.\n\nThese settings are decoded into a UI-owned input DTO by the UI composition root.\nThe DTO contains endpoint references and secret references, never resolved\nsecret values or complete daemon configuration. The UI process resolves its\nown credentials and builds its own clients. It does not read or mutate the\ndaemon's configuration file, runtime overlay, forge credentials, model catalog,\nworkflow routing, NATS settings, filesystem jail, or agent/container settings.\n\nThe dashboard configuration API is a separate capability. Its secret-free,\nallowlisted field projections remain governed by\n[`config-schema.md`](/dev/prds/config-schema/). During the transition the daemon may\ncontinue to perform validate-persist-publish for those updates through a\nnarrow application contract. The UI process must never implement that policy\nby holding or mutating a shared `config.Holder`.\n\nThe daemon's `config.Holder` sharing was migration residue: `buildDaemon`\nassigned `b.web.Cfg = b.d.Cfg`. Removed by `archie-core-ml30` -- the field no\nlonger exists, and boot owns the single Holder the daemon reads through.\n\nFor Phase 3, configuration ownership is split deliberately. The UI process\nowns its listener, browser-auth, asset, dependency-target, and readiness\nsettings. The daemon/application configuration owner remains authoritative for\nthe dashboard's `/api/config` read, validation, persistence, overlay, reload,\nand audit behavior. The UI does not become the writer merely because it\nrenders the configuration page.\n\nAmended 2026-09-11 by `archie-core-ml30`: the daemon's `config.Holder` sharing\nis gone. `webui.Server` has no holder field, so the sharing this paragraph\ndescribes cannot be reintroduced by wiring; the daemon owns one Holder and\npublishes a rendered projection.\n\nThere is no single narrow admin contract carrying both the read and the write\n(`archie-core-ymut`). The\nread crosses as a daemon-published `ConfigView` snapshot over the State Store\ncontract, and the write is descoped for Phase 3 rather than contracted, on the\nreasoning recorded in migration-decisions under \"Dashboard configuration\npage\". A future dedicated Configuration Service is the natural owner of a\nwrite contract, and designing one is that feature's work, not this migration's.\n\n## Listen, authentication, and readiness\n\nThe extracted UI follows the current web UI security posture:\n\n- loopback listeners may omit a dashboard token;\n- non-loopback listeners require a non-empty token and fail closed when it is\n absent;\n- `/healthz` and `/health` are unauthenticated liveness probes;\n- `/health/detailed` is authenticated and reports dependency readiness;\n- capture webhooks retain their separately ratified source authentication and\n rate-limit rules; they are not admitted by the dashboard token;\n- Gateway and State Store credentials are service-to-service credentials, never\n browser-visible dashboard tokens.\n\nThe UI is ready only when its HTTP server is serving and each mandatory remote\ncontract has passed its bounded readiness check. Each dependency must expose a\nversioned health result or health endpoint that the UI can consume; the UI must\nnot inspect another service's concrete manager, registry, or database. Optional\ndashboard sections may remain degraded with the current explicit\n`503`/unavailable behavior. A successful liveness response must never imply\ndependency readiness.\n\n## Migration sequence and evidence\n\nThe implementation must complete these gates in order:\n\n1. Define the UI input DTO, Gateway client surface, State Store client surface,\n and UI response DTOs. Add compile-time contract assertions and mapping\n tests. No handler may depend on a concrete remote implementation.\n2. Make the current in-process web UI consume the same narrow adapters and\n preserve the current route, auth, redaction, stream, SSE, and degradation\n behavior. Add a composition test proving the selected adapter is the one\n used by production wiring.\n3. Remove direct `internal/gateway` session/router/runtime access from web UI\n handlers. Remove direct `internal/store` implementation access, SQL access,\n daemon pointers, and broad runtime callback bundles from the UI constructor.\n4. Replace the shared `config.Holder` with the UI-owned configuration DTO and\n narrow configuration application contract. Prove reload/update atomicity\n remains owned by the configuration/application boundary.\n5. Add the standalone UI process and deployment wiring. It must obtain Gateway\n and State Store endpoints from its own configuration, authenticate each\n client independently, start liveness/readiness endpoints, and shut down\n clients and HTTP listeners in bounded order.\n6. Run dual-adapter contract tests and an HTTP parity suite covering every\n retained route. Test remote failures, missing credentials, malformed DTOs,\n stream cancellation, stale State Store data, and readiness degradation.\n7. Cut over the supported composition to the UI process. The old in-process\n `webui.Run` path is deleted in the same change; no fallback or second HTTP\n authority remains.\n\nThe deletion gate is objective: `go list -deps` from the UI process shows no\ndaemon, SQL/store implementation, workflow, forge, channel, model, or secret\nruntime package; production composition contains one UI HTTP listener; and\narchitecture tests reject `config.Holder`, concrete `*store.Store`, concrete\nGateway runtime types, and direct SQLite imports in the UI service.\n\nRollback is a deployment composition change that points the operator at the\nlast validated UI binary and restores the previous endpoint configuration. It\nmust not restore a second writer or reintroduce shared-holder mutation. UI\nstate is either remote contract state or existing durable state owned by its\ncurrent service; no UI-specific database migration is introduced by this\nboundary decision.\n\n## Current evidence and known delta\n\nCurrent code proves the following migration inputs:\n\n- `internal/app/archied/bootstrap.go:setupObservability` constructs\n `webui.Server` and wires store, channels, events, logs, and config-related\n callbacks.\n- `internal/app/archied/bootstrap.go:buildDaemon` replaces the initial holder\n with `b.d.Cfg`, explicitly sharing the daemon's live configuration.\n- `internal/webui/api_chat.go` calls the Gateway contract but still imports\n Gateway-owned request/value types; handlers must finish the DTO projection.\n- `internal/webui/server.go:Handler` owns the route set, SPA fallback, health\n split, capture bypass, and token wrapper.\n- `internal/app/archied/state_store.go:RunStateStore` owns the task SQLite\n file and serves the State Store gRPC contract; the UI must use that contract\n rather than opening the file.\n- `internal/app/archied/gateway.go:RunGateway` serves Gateway gRPC and owns\n Gateway session persistence; the UI must use `ChatContract` rather than\n Gateway internals.\n\nThe current code therefore satisfies the upstream prerequisites but does not\nyet satisfy this boundary. This document is the ratified target; the\nimplementation child must prove each migration gate before claiming Phase 3.\n\n### Phase 3 gates\n\nEvery gate below is proven by test, not by inspection:\n\n| Gate | Evidence |\n| --- | --- |\n| Deletion | `cmd/archie-ui/architecture_test.go` re-runs `go list -deps` on every `task check` and fails on any banned package, checked in both directions against its two exceptions |\n| Composition | `internal/app/archieui/TestComposeUIServerHoldsNoDaemonState` fails on a concrete `*store.Store` or a Gateway that is not the gRPC client. The holder clause it also carried is enforced by the type: `webui.Server` has no `config.Holder` field (`archie-core-ml30`) |\n| End-to-end | `cmd/archie-ui/main_test.go` builds the binary and drives it over HTTP against a live Gateway and State Store |\n| No dual authority | The dashboard HTTP listener is `internal/app/archieui/run.go` only; the daemon's two `http.Server`s are its own health endpoint and the forge webhook receiver |\n\nAcceptance criterion 1 was amended at the close of Phase 3 to name the UI\nprocess rather than the `internal/webui` package, because the daemon still held\na holder inside its own process to render the published `ConfigView` snapshot.\n`archie-core-ml30` removed that residue, so the criterion holds in its original\nform again: `internal/webui` receives no holder in any process.\n\n### Deletion gate: SATISFIED (archie-core-8cda.5.6, rev. 2)\n\nThe objective gate now holds. `go list -deps ./cmd/archie-ui` links **zero**\nbanned packages: no `modernc.org/sqlite`, no `internal/store`, `internal/gateway`,\n`internal/channels`, `internal/memory`, `internal/secret`, `internal/agentexec`,\n`internal/tools`, `internal/skill`, `internal/yaegiutil`, `internal/domain/curator`,\nor the workflow engine (`internal/domain/workflow`). How the runtime handles were\nsevered, each at the producer:\n\n- **Store contracts** moved to `internal/domain/storecontract` (producer-owned\n read contracts, state-store-contract rev. 2d); `internal/store` keeps aliases.\n- **Chat contracts** moved to `internal/domain/messaging`; `internal/gateway`\n keeps aliases. The UI process holds `ChatContract`, `SessionStore`, turn and\n stream types without linking the gateway runtime or its SQLite session store.\n- **Webui-owned views** replaced concrete runtime handles on `webui.Server`:\n channel lifecycle via `internal/channels/status`, memory via a `MemoryStatus`\n interface, curators via a `CuratorStatus` interface, and the skill catalogue\n via a `SkillCatalog` interface — each supplied by a daemon-side adapter at\n bootstrap, each degrading to an empty page when unwired.\n- **`config.SecretRef`** moved into `internal/config` (it is config vocabulary);\n `internal/secret` keeps an alias and resolves through `Registry.Resolve`.\n- **Task vocabulary** (`Task`, `Store`, `Definition`, status constants) split\n into `internal/domain/workflow/task`; the pipeline engine stays in package\n `workflow`, which keeps aliases. The UI process links the vocabulary only.\n\nThe gate is enforced, not just measured. `cmd/archie-ui/architecture_test.go`\nre-runs `go list -deps` on every `task check` and fails on any package in a\nbanned category, so a single reference to a type sitting beside a runtime\ncannot quietly relink it. Its exception list (`internal/channels/status`,\n`internal/domain/workflow/task`) is checked in both directions: an exception\nthe UI stops needing is reported, so the allowlist cannot decay into an open\nprefix. `internal/app/archieui`'s `TestComposeUIServerHoldsNoDaemonState`\ncovers the composition clauses, failing on a non-nil `config.Holder`, a\nconcrete `*store.Store`, or a Gateway that is not the gRPC client.\n\nOne piece of residue remained visible at the close of Phase 3: `webui.Server`\nstill declared `Cfg *config.Holder`, because the daemon kept a `webui.Server`\nas the renderer that built the published `ConfigView` snapshot. That cleanup\nlanded as `archie-core-ml30`. `webui.Server` no longer has a configuration\nholder, provenance store, reload-status callback or override-listing callback:\nthe projection is built by `webui.BuildConfigView`, a pure function the\nconfiguration owner calls, and the daemon assembles its input from its own\nstate (`boot.configViewInput`). Readiness reads the daemon's own Holder,\nchannel manager and chat contract, and the health registry it produces is a\ndaemon field rather than a field on a server the daemon never serves.\n\n`ConfigView.Editable` moved with it. It describes the rendering process's own\nwrite path, so `handleConfig` sets it from `Server.UpdateConfig` rather than\nany process baking it into the document. A future configuration write contract\n(`archie-core-j28m`) makes the page editable by wiring that one field.\n\n### Real-process evidence (archie-core-8cda.5.6)\n\n`cmd/archie-ui/main_test.go` builds the binary and runs it against a State\nStore and a Gateway on loopback gRPC, then drives it over HTTP: liveness\nwithout a token, 401 for an API request without one, the `?t=` exchange into\nan HttpOnly cookie, task rows with their forge links, the embedded SPA and its\nassets, a chat stream relayed frame by frame from the Gateway, an operator\ntask action crossing to the Gateway (and refused without the CSRF header),\ncapture intake accepted unauthenticated, the ratified degradations, readiness\ndropping when the State Store dies while liveness holds, and a clean SIGTERM.\n\nTwo dashboard values degraded here because the published projection did not\ncarry them: `chat.show_tool_calls` (the chat page never expanded tool calls)\nand the `/api/setup` checklist (the panel was omitted rather than rendered).\nBoth are closed by `archie-core-ml30`: `ConfigView` gained a `chat` section\ncarrying `show_tool_calls`, the operator name, and whether any chat channel is\nconfigured, and both surfaces now read the projection rather than a live\nholder. The end-to-end suite drives the real binary and streams a turn, so the\n`show_tool_calls` assertion is made on the frames a browser receives.\n\nThe checklist stays. The question raised when it was republished -- is a\nread-only setup report wanted in a process that cannot apply the setup it\nreports? -- resolves in favour of keeping it, because the panel never promised\nto apply anything. It renders each step as a title, a detail and a done mark\nwith no control behind it, so it answers \"what is this deployment missing?\"\nrather than \"fix it here\", and the page that CAN act on it (the Configuration\npage) is where an operator goes next, in the daemon's own words. Removing it\nwould delete the one surface that distinguishes a fresh deployment from a\nfinished one for no gain, since the values it reads already cross the boundary\nin `ConfigView` and the read path costs the daemon nothing. The write path\nremains descoped (see `/api/config` (write) in the route table): the checklist\nreports configuration, it does not change it.\n\n`archie-core-ml30` published the channel flag from two of the three chat\nfront-ends, so an email-only deployment read as configured on `/api/channels`\nand unconfigured on the checklist at the same time (GitHub #821). Both now\nderive from `config.ChatConfig.FrontEnds`, the single definition of a configured\nfront-end, and a test pins the two surfaces to the same answer.\n\nA third value degraded for the same reason and is closed by\n`archie-core-pv6t`: in a deployment configuring `[[identities]]` the projection\ncarried the default identity's forge alone, so task rows withheld their links\nrather than pointing every row at the wrong forge. `ConfigView` now also\npublishes each identity's forge coordinates and the repositories it owns\n(`identities`), which is what resolving a task to its owning forge needs —\ncoordinates and repository names only, never a token. The end-to-end suite\ndrives the real binary against a multi-identity projection and asserts each\nrow's issue link is built from the forge that owns it.\n\n## Non-goals and open work\n\nThis ratification does not define a new domain model, move the dashboard's\nallowlisted configuration schema, redesign Gateway or State Store RPCs, choose\nKubernetes versus local discovery, or authorize unrelated package migration.\nThose decisions remain in their existing authority documents. Any new UI\ncapability that requires a wider Gateway or State Store surface must amend that\nservice's contract before implementation.\n" + "body": "# UI Service boundary and configuration ownership\n\n**Status:** Approved\n**Revision:** 1\n**Date:** 2026-09-07\n**Beads issue:** `archie-core-8cda.5.1`\n**Parent:** [`service-decomposition.md`](/dev/prds/service-decomposition/)\n**Prerequisites:** Gateway contract extraction and State Store contract ratification\n\nThis document is the authority for Phase 3 UI Service implementation. It fixes\nthe process boundary, configuration ownership, client contracts, security\nposture, readiness behavior, and migration evidence required by\n`archie-core-8cda.5.2` and later UI extraction work.\n\n## Decision\n\nThe UI Service owns the operator-facing HTTP surface and the compiled SPA. It\nserves `ui/dist` and exposes UI-specific JSON DTOs for dashboard views and\nactions. It does not own conversations, task state, workflow execution,\nchannel lifecycle, forge access, or the daemon's runtime configuration.\n\nThe UI Service consumes two typed remote capabilities:\n\n- Gateway's `gateway.ChatContract` through the versioned Gateway gRPC\n contract, for chat snapshots, messages, turns, streaming, persona changes,\n cancellation, and Gateway task actions.\n- State Store's narrow read/write contracts through the versioned State Store\n gRPC contract, for task views, events, captures, mappings, bindings, and\n configuration data explicitly projected for the dashboard.\n\nThe UI process may compose local adapters during the migration seam, but the\nadapter implements the same wire-safe contract as the remote client. The\nproduction extraction cutover removes the in-process adapter in the same\nchange; a dual-live UI authority is not permitted.\n\n## Boundary and ownership\n\n| Concern | UI Service owns | UI Service may consume | UI Service must not own or receive |\n|---|---|---|---|\n| HTTP and SPA | routes, auth middleware, UI DTOs, assets, HTTP lifecycle | contract results and health snapshots | domain entities or infrastructure handles |\n| Chat | request validation and response projection | Gateway `ChatContract` | `gateway.Router`, `SessionStore`, turn runner, model/provider runtime |\n| Task dashboard | query/action DTOs and HTTP status mapping | State Store narrow contracts and explicitly ratified task-action contract | `*store.Store`, SQL connections, workflow registry, daemon pointer |\n| Configuration page | secret-free view and update request validation | a UI configuration contract owned by the configuration/application boundary | `config.Config`, `config.Holder`, secret registry, reload implementation |\n| Readiness | UI process liveness and dependency readiness aggregation | bounded health results from Gateway and State Store | direct probing of private databases or providers |\n\nEvery value crossing the process boundary is a versioned DTO or scalar contract\nvalue. `internal/webui` may retain temporary Go-side adapters while the\nmigration is in progress, but handlers must map Gateway/State Store values to\nUI-owned response types at the HTTP edge. A constructor accepting a concrete\nGateway, State Store, daemon, or `config.Holder` is not an approved final\nboundary.\n\nThe existing UI routes remain behaviorally compatible during extraction,\nincluding task actions, SSE event delivery, config views, chat streaming,\ncapture intake, mappings, bindings, update reporting, and health endpoints.\nCompatibility preserves status codes, authentication requirements, redaction,\npagination/limits, event ordering, and failure degradation unless a separately\nratified contract changes them.\n\nThe route families have these target owners. This is the required inventory for\nthe implementation children; a route without an owner is not eligible for\ncutover.\n\n| Route family | Target owner consumed by UI | Migration status |\n|---|---|---|\n| `/api/chat/*` | Gateway `ChatContract` and its versioned client | contract seam exists; DTO and stream parity remain |\n| `/api/tasks/*`, `/api/workflows`, `/api/setup` | State Store read/action contracts plus an explicit execution/admin action contract | State Store adapter exists; UI-facing narrow surface remains |\n| `/events` | State Store `EventsSince`, polled by one UI-process pump feeding `Server.Broadcast` | RESOLVED (`archie-core-za9f`): see migration-decisions, \"Dashboard live event delivery\". No new RPC; replay cursor and drop-recovery are the existing `since` watermark in `sse.go` |\n| `/api/logs`, `/api/logs/stream` | daemon diagnostic feed, host-local | unresolved: `logging.Feed` is in-process on the daemon host and has no contract. The per-task log routes moved off this row: see `/api/tasks/*` above |\n| `/api/tasks/{id}/logs`, `/api/tasks/{id}/logs/download` | State Store task-log read contract (`TaskLogStore`: `ReadTaskLog` + `StreamTaskLogContent`), read by the UI process from the service that owns the state directory | RESOLVED (`archie-core-iaqx`): the UI process composes `TaskLogStore` from its own State Store client and serves the attempt log as JSON (`found` distinguishes \"no log for this attempt\" from \"this process cannot read logs\") and as a `Content-Disposition` attachment named `task-\u003cid\u003e-attempt-\u003cn\u003e.log`. The daemon's in-process registry is wired as the server-side reader in `internal/app/archied/state_store.go` only (`staterpc.Deps.TaskLogs`), so no process opens another process's log files |\n| `/api/captures`, `/api/mappings`, `/api/bindings` | State Store contracts, with webhook verification owned by Work Intake/Messaging | RESOLVED (cutover, `archie-core-8cda.5.4`): the UI process composes CaptureStore/MappingStore/BindingStore and mounts the `captureintake.Receiver` from its own State Store client; the daemon's binding-dispatch loop keeps consuming captures from the same store |\n| `/api/config` (read) | daemon-published `ConfigView` snapshot, read over the State Store contract | RESOLVED (`archie-core-ymut`): see migration-decisions, \"Dashboard configuration page\" |\n| `/api/config` (write), `/api/config/reset`, `/api/config/repos/*` | a configuration write contract; the daemon stays the policy owner | DESCOPED for Phase 3 (`archie-core-ymut`), NOT abandoned: 503 in the UI process, SPA hides the controls, editing is config.toml plus reload. Dashboard editing is a tracked feature (`archie-core-1786637498420-327`) and its transport is `archie-core-j28m`; the handlers and their func-field seams on `webui.Server` are kept for it |\n| `/api/channels`, reload, curators, memory, skills, version/update | owning capability contract or an explicitly removed route | owner and failure semantics remain to define |\n| `/`, `/healthz`, `/health`, `/health/detailed` | UI HTTP process; readiness consumes per-service health contracts | current HTTP behavior is the compatibility baseline |\n\n## Configuration ownership\n\nThe UI Service owns only process-local settings:\n\n- HTTP listen address and read/header/shutdown timeouts;\n- UI asset source or build mode;\n- UI authentication mode and token reference;\n- Gateway endpoint and credential reference;\n- State Store endpoint and credential reference;\n- readiness endpoint and dependency timeout policy.\n\nThese settings are decoded into a UI-owned input DTO by the UI composition root.\nThe DTO contains endpoint references and secret references, never resolved\nsecret values or complete daemon configuration. The UI process resolves its\nown credentials and builds its own clients. It does not read or mutate the\ndaemon's configuration file, runtime overlay, forge credentials, model catalog,\nworkflow routing, NATS settings, filesystem jail, or agent/container settings.\n\nThe dashboard configuration API is a separate capability. Its secret-free,\nallowlisted field projections remain governed by\n[`config-schema.md`](/dev/prds/config-schema/). During the transition the daemon may\ncontinue to perform validate-persist-publish for those updates through a\nnarrow application contract. The UI process must never implement that policy\nby holding or mutating a shared `config.Holder`.\n\nThe daemon's `config.Holder` sharing was migration residue: `buildDaemon`\nassigned `b.web.Cfg = b.d.Cfg`. Removed by `archie-core-ml30` -- the field no\nlonger exists, and boot owns the single Holder the daemon reads through.\n\nFor Phase 3, configuration ownership is split deliberately. The UI process\nowns its listener, browser-auth, asset, dependency-target, and readiness\nsettings. The daemon/application configuration owner remains authoritative for\nthe dashboard's `/api/config` read, validation, persistence, overlay, reload,\nand audit behavior. The UI does not become the writer merely because it\nrenders the configuration page.\n\nAmended 2026-09-11 by `archie-core-ml30`: the daemon's `config.Holder` sharing\nis gone. `webui.Server` has no holder field, so the sharing this paragraph\ndescribes cannot be reintroduced by wiring; the daemon owns one Holder and\npublishes a rendered projection.\n\nThere is no single narrow admin contract carrying both the read and the write\n(`archie-core-ymut`). The\nread crosses as a daemon-published `ConfigView` snapshot over the State Store\ncontract, and the write is descoped for Phase 3 rather than contracted, on the\nreasoning recorded in migration-decisions under \"Dashboard configuration\npage\". A future dedicated Configuration Service is the natural owner of a\nwrite contract, and designing one is that feature's work, not this migration's.\n\n## Listen, authentication, and readiness\n\nThe extracted UI follows the current web UI security posture:\n\n- loopback listeners may omit a dashboard token;\n- non-loopback listeners require a non-empty token and fail closed when it is\n absent;\n- `/healthz` and `/health` are unauthenticated liveness probes;\n- `/health/detailed` is authenticated and reports dependency readiness;\n- capture webhooks retain their separately ratified source authentication and\n rate-limit rules; they are not admitted by the dashboard token;\n- Gateway and State Store credentials are service-to-service credentials, never\n browser-visible dashboard tokens.\n\nThe UI is ready only when its HTTP server is serving and each mandatory remote\ncontract has passed its bounded readiness check. Each dependency must expose a\nversioned health result or health endpoint that the UI can consume; the UI must\nnot inspect another service's concrete manager, registry, or database. Optional\ndashboard sections may remain degraded with the current explicit\n`503`/unavailable behavior. A successful liveness response must never imply\ndependency readiness.\n\n## Migration sequence and evidence\n\nThe implementation must complete these gates in order:\n\n1. Define the UI input DTO, Gateway client surface, State Store client surface,\n and UI response DTOs. Add compile-time contract assertions and mapping\n tests. No handler may depend on a concrete remote implementation.\n2. Make the current in-process web UI consume the same narrow adapters and\n preserve the current route, auth, redaction, stream, SSE, and degradation\n behavior. Add a composition test proving the selected adapter is the one\n used by production wiring.\n3. Remove direct `internal/gateway` session/router/runtime access from web UI\n handlers. Remove direct store implementation access, SQL access,\n daemon pointers, and broad runtime callback bundles from the UI constructor.\n4. Replace the shared `config.Holder` with the UI-owned configuration DTO and\n narrow configuration application contract. Prove reload/update atomicity\n remains owned by the configuration/application boundary.\n5. Add the standalone UI process and deployment wiring. It must obtain Gateway\n and State Store endpoints from its own configuration, authenticate each\n client independently, start liveness/readiness endpoints, and shut down\n clients and HTTP listeners in bounded order.\n6. Run dual-adapter contract tests and an HTTP parity suite covering every\n retained route. Test remote failures, missing credentials, malformed DTOs,\n stream cancellation, stale State Store data, and readiness degradation.\n7. Cut over the supported composition to the UI process. The old in-process\n `webui.Run` path is deleted in the same change; no fallback or second HTTP\n authority remains.\n\nThe deletion gate is objective: `go list -deps` from the UI process shows no\ndaemon, SQL/store implementation, workflow, forge, channel, model, or secret\nruntime package; production composition contains one UI HTTP listener; and\narchitecture tests reject `config.Holder`, concrete `*store.Store`, concrete\nGateway runtime types, and direct database drivers in the UI service.\n\nRollback is a deployment composition change that points the operator at the\nlast validated UI binary and restores the previous endpoint configuration. It\nmust not restore a second writer or reintroduce shared-holder mutation. UI\nstate is either remote contract state or existing durable state owned by its\ncurrent service; no UI-specific database migration is introduced by this\nboundary decision.\n\n## Current evidence and known delta\n\nCurrent code proves the following migration inputs:\n\n- `internal/app/archied/bootstrap.go:setupObservability` constructs\n `webui.Server` and wires store, channels, events, logs, and config-related\n callbacks.\n- `internal/app/archied/bootstrap.go:buildDaemon` replaces the initial holder\n with `b.d.Cfg`, explicitly sharing the daemon's live configuration.\n- `internal/webui/api_chat.go` calls the Gateway contract but still imports\n Gateway-owned request/value types; handlers must finish the DTO projection.\n- `internal/webui/server.go:Handler` owns the route set, SPA fallback, health\n split, capture bypass, and token wrapper.\n- `internal/app/archied/state_store.go:RunStateStore` owns the task\n database and serves the State Store gRPC contract; the UI must use that contract\n rather than opening the database.\n- `internal/app/archied/gateway.go:RunGateway` serves Gateway gRPC and owns\n Gateway session persistence; the UI must use `ChatContract` rather than\n Gateway internals.\n\nThe current code therefore satisfies the upstream prerequisites but does not\nyet satisfy this boundary. This document is the ratified target; the\nimplementation child must prove each migration gate before claiming Phase 3.\n\n### Phase 3 gates\n\nEvery gate below is proven by test, not by inspection:\n\n| Gate | Evidence |\n| --- | --- |\n| Deletion | `cmd/archie-ui/architecture_test.go` re-runs `go list -deps` on every `task check` and fails on any banned package, checked in both directions against its two exceptions |\n| Composition | `internal/app/archieui/TestComposeUIServerHoldsNoDaemonState` fails on a concrete `*store.Store` or a Gateway that is not the gRPC client. The holder clause it also carried is enforced by the type: `webui.Server` has no `config.Holder` field (`archie-core-ml30`) |\n| End-to-end | `cmd/archie-ui/main_test.go` builds the binary and drives it over HTTP against a live Gateway and State Store |\n| No dual authority | The dashboard HTTP listener is `internal/app/archieui/run.go` only; the daemon's two `http.Server`s are its own health endpoint and the forge webhook receiver |\n\nAcceptance criterion 1 was amended at the close of Phase 3 to name the UI\nprocess rather than the `internal/webui` package, because the daemon still held\na holder inside its own process to render the published `ConfigView` snapshot.\n`archie-core-ml30` removed that residue, so the criterion holds in its original\nform again: `internal/webui` receives no holder in any process.\n\n### Deletion gate: SATISFIED (archie-core-8cda.5.6, rev. 2)\n\nThe objective gate now holds. `go list -deps ./cmd/archie-ui` links **zero**\nbanned packages: no `modernc.org/sqlite`, no `github.com/jackc/pgx`, no `internal/infrastructure/postgres`, `internal/gateway`,\n`internal/channels`, `internal/memory`, `internal/secret`, `internal/agentexec`,\n`internal/tools`, `internal/skill`, `internal/yaegiutil`, `internal/domain/curator`,\nor the workflow engine (`internal/domain/workflow`). How the runtime handles were\nsevered, each at the producer:\n\n- **Store contracts** moved to `internal/domain/storecontract` (producer-owned\n read contracts, state-store-contract rev. 2d).\n- **Chat contracts** moved to `internal/domain/messaging`; `internal/gateway`\n keeps aliases. The UI process holds `ChatContract`, `SessionStore`, turn and\n stream types without linking the gateway runtime or its session store.\n- **Webui-owned views** replaced concrete runtime handles on `webui.Server`:\n channel lifecycle via `internal/channels/status`, memory via a `MemoryStatus`\n interface, curators via a `CuratorStatus` interface, and the skill catalogue\n via a `SkillCatalog` interface — each supplied by a daemon-side adapter at\n bootstrap, each degrading to an empty page when unwired.\n- **`config.SecretRef`** moved into `internal/config` (it is config vocabulary);\n `internal/secret` keeps an alias and resolves through `Registry.Resolve`.\n- **Task vocabulary** (`Task`, `Store`, `Definition`, status constants) split\n into `internal/domain/workflow/task`; the pipeline engine stays in package\n `workflow`, which keeps aliases. The UI process links the vocabulary only.\n\nThe gate is enforced, not just measured. `cmd/archie-ui/architecture_test.go`\nre-runs `go list -deps` on every `task check` and fails on any package in a\nbanned category, so a single reference to a type sitting beside a runtime\ncannot quietly relink it. Its exception list (`internal/channels/status`,\n`internal/domain/workflow/task`) is checked in both directions: an exception\nthe UI stops needing is reported, so the allowlist cannot decay into an open\nprefix. `internal/app/archieui`'s `TestComposeUIServerHoldsNoDaemonState`\ncovers the composition clauses, failing on a non-nil `config.Holder`, a\nconcrete `*store.Store`, or a Gateway that is not the gRPC client.\n\nOne piece of residue remained visible at the close of Phase 3: `webui.Server`\nstill declared `Cfg *config.Holder`, because the daemon kept a `webui.Server`\nas the renderer that built the published `ConfigView` snapshot. That cleanup\nlanded as `archie-core-ml30`. `webui.Server` no longer has a configuration\nholder, provenance store, reload-status callback or override-listing callback:\nthe projection is built by `webui.BuildConfigView`, a pure function the\nconfiguration owner calls, and the daemon assembles its input from its own\nstate (`boot.configViewInput`). Readiness reads the daemon's own Holder,\nchannel manager and chat contract, and the health registry it produces is a\ndaemon field rather than a field on a server the daemon never serves.\n\n`ConfigView.Editable` moved with it. It describes the rendering process's own\nwrite path, so `handleConfig` sets it from `Server.UpdateConfig` rather than\nany process baking it into the document. A future configuration write contract\n(`archie-core-j28m`) makes the page editable by wiring that one field.\n\n### Real-process evidence (archie-core-8cda.5.6)\n\n`cmd/archie-ui/main_test.go` builds the binary and runs it against a State\nStore and a Gateway on loopback gRPC, then drives it over HTTP: liveness\nwithout a token, 401 for an API request without one, the `?t=` exchange into\nan HttpOnly cookie, task rows with their forge links, the embedded SPA and its\nassets, a chat stream relayed frame by frame from the Gateway, an operator\ntask action crossing to the Gateway (and refused without the CSRF header),\ncapture intake accepted unauthenticated, the ratified degradations, readiness\ndropping when the State Store dies while liveness holds, and a clean SIGTERM.\n\nTwo dashboard values degraded here because the published projection did not\ncarry them: `chat.show_tool_calls` (the chat page never expanded tool calls)\nand the `/api/setup` checklist (the panel was omitted rather than rendered).\nBoth are closed by `archie-core-ml30`: `ConfigView` gained a `chat` section\ncarrying `show_tool_calls`, the operator name, and whether any chat channel is\nconfigured, and both surfaces now read the projection rather than a live\nholder. The end-to-end suite drives the real binary and streams a turn, so the\n`show_tool_calls` assertion is made on the frames a browser receives.\n\nThe checklist stays. The question raised when it was republished -- is a\nread-only setup report wanted in a process that cannot apply the setup it\nreports? -- resolves in favour of keeping it, because the panel never promised\nto apply anything. It renders each step as a title, a detail and a done mark\nwith no control behind it, so it answers \"what is this deployment missing?\"\nrather than \"fix it here\", and the page that CAN act on it (the Configuration\npage) is where an operator goes next, in the daemon's own words. Removing it\nwould delete the one surface that distinguishes a fresh deployment from a\nfinished one for no gain, since the values it reads already cross the boundary\nin `ConfigView` and the read path costs the daemon nothing. The write path\nremains descoped (see `/api/config` (write) in the route table): the checklist\nreports configuration, it does not change it.\n\n`archie-core-ml30` published the channel flag from two of the three chat\nfront-ends, so an email-only deployment read as configured on `/api/channels`\nand unconfigured on the checklist at the same time (GitHub #821). Both now\nderive from `config.ChatConfig.FrontEnds`, the single definition of a configured\nfront-end, and a test pins the two surfaces to the same answer.\n\nA third value degraded for the same reason and is closed by\n`archie-core-pv6t`: in a deployment configuring `[[identities]]` the projection\ncarried the default identity's forge alone, so task rows withheld their links\nrather than pointing every row at the wrong forge. `ConfigView` now also\npublishes each identity's forge coordinates and the repositories it owns\n(`identities`), which is what resolving a task to its owning forge needs —\ncoordinates and repository names only, never a token. The end-to-end suite\ndrives the real binary against a multi-identity projection and asserts each\nrow's issue link is built from the forge that owns it.\n\n## Non-goals and open work\n\nThis ratification does not define a new domain model, move the dashboard's\nallowlisted configuration schema, redesign Gateway or State Store RPCs, choose\nKubernetes versus local discovery, or authorize unrelated package migration.\nThose decisions remain in their existing authority documents. Any new UI\ncapability that requires a wider Gateway or State Store surface must amend that\nservice's contract before implementation.\n" }, { "url": "/dev/prds/vue-migration-checklist/", diff --git a/docs/prds/binding-secret-encryption.md b/docs/prds/binding-secret-encryption.md index bd9c7c4b9..34e8225b4 100644 --- a/docs/prds/binding-secret-encryption.md +++ b/docs/prds/binding-secret-encryption.md @@ -6,6 +6,11 @@ ## Problem +> Storage superseded: every store now lives in PostgreSQL behind +> `internal/domain/storecontract`, implemented in `internal/infrastructure/postgres` +> (`docs/prds/state-store-contract.md`). SQLite names below describe the +> original design. + `binding.Binding.Secret` (the per-source HMAC shared secret) is persisted as plaintext in the `bindings.secret TEXT` column. Anyone with read access to the SQLite file -- the same access level as `captured_events.body` and `tasks.body` @@ -94,8 +99,8 @@ old material must be retained. - `internal/app/archied/bootstrap.go` `openStores`: resolve both refs through the already-built `secrets` registry, pass the material to `store.Open` via a new option `store.WithBindingCipher(cipher)`. -- `internal/store`: add a `BindingCipher` interface (concrete AES-GCM impl in - `binding_cipher.go`), a `bindingCipher` field on `Store`, and the `Open` +- `internal/infrastructure/bindingcipher`: the `BindingCipher` interface and + concrete AES-GCM impl, consumed by the event-capture store; a `bindingCipher` field on `Store`, and the `Open` option. **Nil cipher = plaintext**, so existing call sites and tests change nothing and legacy deployments keep current behaviour until they set a key. diff --git a/docs/prds/dynamic-curators.md b/docs/prds/dynamic-curators.md index 81b91cb51..8902588b2 100644 --- a/docs/prds/dynamic-curators.md +++ b/docs/prds/dynamic-curators.md @@ -71,7 +71,7 @@ served by one registered engine whose `Manifest()` is the stored definition and whose `Pass` composes `instructions` with the built tool set. This is the curator domain's missing half, not a standalone tool: it lands in -`internal/domain/curator` (entity + engine), `internal/store` (persistence), +`internal/domain/curator` (entity + engine), `internal/infrastructure/postgres` (persistence), `internal/webui` (CRUD), and `internal/app/archied` (seed + apply wiring). ## Definition sources and the merge rule @@ -147,7 +147,7 @@ without a restart. ## Sequencing: persistence and the State Store -The State Store is a standalone process that solely owns `archie.db`; the daemon +The State Store is a standalone process that solely owns the task database; the daemon and Gateway never open it (`TestOpenStoresNeverOwnsTaskDB` guards this), and `proto/state/v1/state.proto` is one gRPC service fronting every ratified store contract. AGENTS.md forbids adding a Go interface method without a matching RPC. @@ -162,7 +162,7 @@ That fixes the order: Phases 1 and 2 are genuinely independent of the wire boundary, so they are not blocked on it. Phase 3 is where the boundary is unavoidable: a definition the WebUI can edit must be reachable from the WebUI, and the WebUI reaches the store -through the State Store, not by opening `archie.db`. Splitting the RPCs into a +through the State Store, not by opening the database. Splitting the RPCs into a later change would leave a table nothing can read -- rejected. Deferring the whole phase is the same rejection, later. diff --git a/docs/prds/eda-playbook-engine.md b/docs/prds/eda-playbook-engine.md index b63ea3260..9e1f6334b 100644 --- a/docs/prds/eda-playbook-engine.md +++ b/docs/prds/eda-playbook-engine.md @@ -353,10 +353,15 @@ single-action playbooks the two granularities are equivalent in effect; the difference starts with multi-action runs -- where whole-run keying would already be wrong. +> Storage superseded: every store now lives in PostgreSQL behind +> `internal/domain/storecontract`, implemented in `internal/infrastructure/postgres` +> (`docs/prds/state-store-contract.md`). SQLite names below describe the +> original design. + **Storage/lookup: a new durable ledger table `playbook_dispatches` in -`internal/store`, copying `binding_dispatches`'s conventions exactly** +the event-capture store, copying `binding_dispatches`'s conventions exactly** (durable table, `INSERT OR IGNORE`, sentinel error, rows freed with -their parent, survives daemon restarts -- `internal/store/bindings.go`): +their parent, survives daemon restarts -- `RecordDispatch`): ```sql CREATE TABLE playbook_dispatches ( @@ -376,9 +381,9 @@ write rather than a constraint error, and the caller matches it with (`internal/daemon/daemon.go` -- "another cycle already won this race," not an error to surface). The record is consumed by the playbook coordinator at dispatch time through a domain-side interface implemented -by `internal/store` -- the same shape as `BindingDispatcher` -(`internal/store/interface.go`) -- and the table lands in the -store's schema application (`internal/store/store.go`). No change +by the event-capture store -- the same shape as `BindingDispatcher` +(`internal/domain/storecontract`) -- and the table lands in the +store's schema migrations. No change to `internal/eventbus`; no per-message dedup state on the client. **Lifetime: no time-based expiry, and no automatic reclamation.** Rows are diff --git a/docs/prds/memory-engine-unification.md b/docs/prds/memory-engine-unification.md index e5d5deb66..169f1eef7 100644 --- a/docs/prds/memory-engine-unification.md +++ b/docs/prds/memory-engine-unification.md @@ -41,7 +41,7 @@ Three further defects fall out of the same split: nothing, and a webhook populates it with nothing either — a route path names a source, not a person, so `webhook.go` leaves `SenderID` empty and carries the route in `Inbound.BudgetKey` for rate limiting. `sender_id` is persisted - (`session_store_sqlite.go`), so whatever a channel puts there reaches the + (`session_store_postgres.go`), so whatever a channel puts there reaches the consumers that read it. `agent-system.md` says the write-scope selection and cross-scope sharing @@ -230,7 +230,7 @@ and would leak user A's extracted facts to user B through the same agent; user-wide would pool facts across agents; and a session id cannot survive the session ending, which is the whole requirement. -This needs data the tree does not persist: the SQLite `messages` table +This needs data the tree does not persist: the `messages` table gains `sender_id`, and `curator.SessionSummary` / `ConversationMessage` gain the agent and participant. The participant is derived from the session's own user-role messages: exactly one distinct non-empty sender writes; zero (a diff --git a/docs/prds/messaging-service-boundary.md b/docs/prds/messaging-service-boundary.md index 7387d3acb..5c803caaf 100644 --- a/docs/prds/messaging-service-boundary.md +++ b/docs/prds/messaging-service-boundary.md @@ -16,7 +16,7 @@ The Messaging Service (`cmd/archie-messaging`, composed via `internal/app/archie It is a peer service to the UI Service and the daemon: - It serves external chat participants across configured communication platforms. - It consumes Gateway's `messaging.ChatContract` exclusively for chat turn execution, streaming, session queries, cancellation, persona selection, and task control actions. -- It holds no direct database connections (`*store.Store` or SQLite), owns no LLM execution or model provider credentials, and has no dependency on the daemon runtime or the UI HTTP server. +- It holds no direct database connections, owns no LLM execution or model provider credentials, and has no dependency on the daemon runtime or the UI HTTP server. ## Boundary and Ownership @@ -24,7 +24,7 @@ It is a peer service to the UI Service and the daemon: |---|---|---|---| | **Channel transports** | Telegram bot long-polling, Email IMAP/SMTP loops, Inbound Webhook HTTP listener | Gateway `ChatContract` | Direct LLM providers, model runtimes, tokenizer libraries | | **Turn dispatch** | Inbound message packaging, typing indicators, live streaming updates | `ChatContract.Route`, `ChatContract.Stream` | `gateway.Router`, `runtime.Runtime`, agent prompt builders | -| **Sessions & History** | Platform-to-session key mapping, conversation thread ID translation | `ChatContract.GetSession`, `RecentMessages`, `RecentTurns` | `*store.Store`, `SessionStore` SQLite handles, direct database files | +| **Sessions & History** | Platform-to-session key mapping, conversation thread ID translation | `ChatContract.GetSession`, `RecentMessages`, `RecentTurns` | store implementations, `SessionStore` database handles | | **Control & Actions** | Platform command parsing (`/status`, `/tasks`, `/cancel`, `/stop`, `/persona`) | `ChatContract.Snapshot`, `ApplyTaskAction`, `Cancel`, `SetPersona` | `daemon.Daemon`, workflow execution engine, worktree operations | | **Task Approvals** | Channel interactive keyboards, approval callbacks | `ChatContract.ApplyTaskAction` | Direct task status mutations, forge comment posters | | **Configuration** | Platform bot tokens, allowed sender/user IDs, webhook listen ports | `[chat.*]` channel configs, Gateway target/token | `config.Holder`, forge tokens, repo configs, agent container specs | @@ -66,7 +66,7 @@ It does not read or decode `[forge]`, `[repos]`, `[models]`, `[providers]`, `[ru ## Deletion Gate and Verification The extraction is guarded by `cmd/archie-messaging/architecture_test.go`, verifying that `go list -deps ./cmd/archie-messaging` links zero banned runtime packages: -- `modernc.org/sqlite` and `internal/store` (State Store) +- `modernc.org/sqlite`, `github.com/jackc/pgx`, `internal/infrastructure/postgres` and `internal/infrastructure/legacyread` (State Store) - `internal/daemon`, `internal/app/archied`, `internal/container`, `internal/worktree` (Daemon runtime) - `internal/domain/workflow`, `internal/agentexec`, `internal/taskrun` (Workflow engine) - `internal/forge`, `internal/forgerpc` (Forge client) diff --git a/docs/prds/payload-field-mapping.md b/docs/prds/payload-field-mapping.md index 9074aca42..94189e15f 100644 --- a/docs/prds/payload-field-mapping.md +++ b/docs/prds/payload-field-mapping.md @@ -12,6 +12,11 @@ reference by ID. ## Decision: a new `internal/domain/mapping` package, SQLite storage +> Storage superseded: every store now lives in PostgreSQL behind +> `internal/domain/storecontract`, implemented in `internal/infrastructure/postgres` +> (`docs/prds/state-store-contract.md`). SQLite names below describe the +> original design. + `internal/domain/mapping` owns the mapping vocabulary and the pure resolve/preview rule; `internal/store` persists it (mirrors `captures.go`'s shape exactly -- inline schema const, narrow store @@ -107,7 +112,7 @@ is `t2db.4`'s job, not duplicated here. ## Storage -`internal/store/mappings.go`, `field_mappings` table: `id, name, +The `mappings` table: `id, name, source_hint, fields_json, created_at, updated_at`. `fields_json` is the `[]Field` slice JSON-encoded into one column -- fields have no independent query need (nothing filters "mappings with a field named X"), so a diff --git a/docs/prds/pr-review-remediation.md b/docs/prds/pr-review-remediation.md index 91f70e4db..a6c5d07ae 100644 --- a/docs/prds/pr-review-remediation.md +++ b/docs/prds/pr-review-remediation.md @@ -89,7 +89,7 @@ closed or archived is dropped through the same counter: the reaction is only ever work against a PR archie itself opened *and still owns*. That lookup does not exist. `pr_number` is written by -`internal/store/store.go` and never read in a `WHERE` clause, so this needs a +`internal/infrastructure/postgres/store.go` and never read in a `WHERE` clause, so this needs a `TaskStore` method keyed on `(owner, repo, pr_number)`, a matching `StateStoreService` RPC (a Go interface method on a store facade without one is forbidden, `CLAUDE.md`), and an index on those three columns. It is the @@ -97,7 +97,7 @@ authorization boundary, so it is sequenced as its own step below rather than carried along with the envelope. **Identity is derived from the resolved task, never carried in the reaction.** -The task row already stores `identity` (`internal/store/store.go`), and it is +The task row already stores `identity` (`internal/infrastructure/postgres/store.go`), and it is the resolved task's identity that selects the forge client, worktree manager, repo config and `bot_user` for the remediation run and the `ReplyToReview` reply, through the existing `forgeFor`/`treesFor`/`repoFor` helpers. That is diff --git a/docs/prds/service-decomposition.md b/docs/prds/service-decomposition.md index eee35bad0..a3c3bfa88 100644 --- a/docs/prds/service-decomposition.md +++ b/docs/prds/service-decomposition.md @@ -42,7 +42,7 @@ boundaries. | Scheduler Service | cron/ticker contract | `internal/domain/scheduling` | | Execution Environment | execution-dispatch contract | `internal/domain/workflow`, task dispatch paths | | Runner | isolated worktree/container execution | `internal/container`, `internal/agentexec`, `internal/worktree` | -| State Store | state-access contract | `internal/store` | +| State Store | state-access contract | `internal/infrastructure/postgres` | ### Discovery @@ -191,8 +191,8 @@ historical record rather than an outstanding gate. State Store service's contract (less isolation, less migration risk). Not yet decided. - **RESOLVED.** One State Store service owns the existing - single SQLite file behind narrow typed contracts (`TaskStore`, + **RESOLVED.** One State Store service owns the task data + (now PostgreSQL, see `docs/prds/state-store-contract.md`) behind narrow typed contracts (`TaskStore`, `CaptureStore`, `MappingStore`, `BindingStore`, `WorkflowStore`) over gRPC. *(Ratified 2026-09-06: the workflow contract is now the domain-owned `workflow.Store`, which supersedes @@ -201,7 +201,7 @@ historical record rather than an outstanding gate. No physical database-per-service: the solo-maintainer / team- topology rule of thumb plus the low value of per-service autonomy for one person rule it out, and one store means no distributed-transactions - problem. The Gateway keeps its own already-separate session SQLite. + problem. Concrete migration path (generalise `storerpc`, swap consumers one contract at a time, stand up the store service, split the file only on evidence): @@ -212,7 +212,7 @@ historical record rather than an outstanding gate. `docs/prds/state-store-contract.md` (rev. 2c): one `StateStore` gRPC service, 42 RPCs; **ownership split** — consumer-owned `workflow.Store` + `workflow.Task`/`Status`/`Source` in the workflow domain (dependency rules - #2/#7), producer-owned daemon/webui store surfaces in `internal/store`; + #2/#7), producer-owned daemon/webui store surfaces in `internal/domain/storecontract`; the `Task`/`Status`/`Source` + interface relocation is a Phase 2 prerequisite pulled from migration-decisions §4 (`store.Task → WorkflowExecution`); `RecordDispatch` drops `*sql.Tx`; `Close` off-wire; diff --git a/docs/prds/state-store-contract.md b/docs/prds/state-store-contract.md index ff78e1abc..8c7339e32 100644 --- a/docs/prds/state-store-contract.md +++ b/docs/prds/state-store-contract.md @@ -16,6 +16,15 @@ split `archie.db`. It records method ownership, DTO/wire representation, error s limits, mode/config shape, local-adapter compatibility, and cutover/deletion rules so that `.4.2` and `.4.3` have exactly one authoritative surface to build against. +> **Storage superseded.** The store behind this contract is PostgreSQL: +> `internal/infrastructure/postgres` implements the producer-owned interfaces in +> `internal/domain/storecontract` and `workflow.Store`, over the database +> `database_url` names. `internal/store`, the SQLite file and the local adapter +> are gone; where this document says `archie.db`, `*store.Store` or +> `internal/store`, read the State Store's PostgreSQL database and +> `internal/infrastructure/postgres`. The contract, ownership split, error +> semantics and cutover rules stand. + > **Current state — read before `.4.2` starts.** The §12 step 2 relocation (`archie-core-8cda. > 4.8`) has landed: `Task`/`Status*`/`Source*` and the 3-method `workflow.Store` now live in > `internal/domain/workflow`, the six production workflow files import no `internal/store` @@ -584,9 +593,9 @@ an explicit operator decision. `target` cannot boot, so the section ships uncommented. - Composition root: `internal/app/archied/bootstrap.go` (the daemon) and `internal/app/archieui/config.go` (the UI process) both read `cfg.Services.Get("state")` and - dial the remote State Store. `openProductionTaskStore` is **not** called from the daemon: it - lives in the standalone `archie-state-store` process (`internal/app/archied/state_store.go`), - which is the only path that opens `archie.db`. + dial the remote State Store. The task store is built only in the standalone + `archie-state-store` process (`internal/app/archied/state_store.go`), which is the only path + that opens the task tables. > **Mode fork, decided.** The gateway uses a single `target` address (no enum). The State Store > boundary uses the same seam for symmetry, and **both now require a non-empty `target`**: the @@ -656,7 +665,7 @@ an explicit operator decision. contracts for a contract-code (no dual-live *window*; each contract is either local or remote at a time). 7. **Final flip / deletion of the in-process serving path:** when the daemon no longer owns the - store (i.e. `TaskStore` has moved), delete the in-process `openProductionTaskStore` / + store (i.e. `TaskStore` has moved), delete the in-process task-store / `wireWebStoreSurfaces` path in the daemon in a **same-commit** deletion — no dual-store ownership. The single SQLite file remains owned by `archie-state-store`. 8. **Never** split `archie.db` or add a second store. The gateway keeps its own already-separate diff --git a/docs/prds/task-run-detail.md b/docs/prds/task-run-detail.md index b7ec0a080..277f4f54c 100644 --- a/docs/prds/task-run-detail.md +++ b/docs/prds/task-run-detail.md @@ -43,8 +43,8 @@ that has since moved on. ## Attempt attribution: a column, not a guess -`events.Event.Attempt`, persisted by `internal/store` as the `events.attempt` -column (`internal/store/events.go`, `eventsSchema`), is a real column, +`events.Event.Attempt`, persisted as the `events.attempt` column +(`internal/infrastructure/postgres/migrations/0001_state_store.sql`), is a real column, `NOT NULL DEFAULT 0`. It was chosen over segmenting the stream on `task_queued` / `task_retried` because a fold would have to guess which side of a boundary an event belongs to when the daemon restarts mid-attempt, when `RecoverStale` @@ -60,6 +60,11 @@ attempt 1. ## Migration against an existing `archie.db` +> Storage superseded: every store now lives in PostgreSQL behind +> `internal/domain/storecontract`, implemented in `internal/infrastructure/postgres` +> (`docs/prds/state-store-contract.md`). SQLite names below describe the +> original design. + The store's migrator (`migrateTasks` in `internal/store/store.go`) already reads `PRAGMA table_info` through `tableColumns` and applies a presence-gated `ALTER TABLE ... ADD COLUMN` list. This change adds an `events` arm: a @@ -249,8 +254,7 @@ than useless. ## Files this change touches -- `internal/store/`: the `events.attempt` column, its migrator arm, and the - schema-presence test. +- the State Store schema: the `events.attempt` column. - `internal/events/`: `Event.Attempt`, `KindChangesCaptured`, `KindConfigCaptured`, `ConfigCapturedSchema`. - `internal/domain/workflow/task/changes.go`: the change value types. diff --git a/docs/prds/ui-service-boundary.md b/docs/prds/ui-service-boundary.md index a0f060753..8f153b347 100644 --- a/docs/prds/ui-service-boundary.md +++ b/docs/prds/ui-service-boundary.md @@ -157,7 +157,7 @@ The implementation must complete these gates in order: behavior. Add a composition test proving the selected adapter is the one used by production wiring. 3. Remove direct `internal/gateway` session/router/runtime access from web UI - handlers. Remove direct `internal/store` implementation access, SQL access, + handlers. Remove direct store implementation access, SQL access, daemon pointers, and broad runtime callback bundles from the UI constructor. 4. Replace the shared `config.Holder` with the UI-owned configuration DTO and narrow configuration application contract. Prove reload/update atomicity @@ -177,7 +177,7 @@ The deletion gate is objective: `go list -deps` from the UI process shows no daemon, SQL/store implementation, workflow, forge, channel, model, or secret runtime package; production composition contains one UI HTTP listener; and architecture tests reject `config.Holder`, concrete `*store.Store`, concrete -Gateway runtime types, and direct SQLite imports in the UI service. +Gateway runtime types, and direct database drivers in the UI service. Rollback is a deployment composition change that points the operator at the last validated UI binary and restores the previous endpoint configuration. It @@ -199,9 +199,9 @@ Current code proves the following migration inputs: Gateway-owned request/value types; handlers must finish the DTO projection. - `internal/webui/server.go:Handler` owns the route set, SPA fallback, health split, capture bypass, and token wrapper. -- `internal/app/archied/state_store.go:RunStateStore` owns the task SQLite - file and serves the State Store gRPC contract; the UI must use that contract - rather than opening the file. +- `internal/app/archied/state_store.go:RunStateStore` owns the task + database and serves the State Store gRPC contract; the UI must use that contract + rather than opening the database. - `internal/app/archied/gateway.go:RunGateway` serves Gateway gRPC and owns Gateway session persistence; the UI must use `ChatContract` rather than Gateway internals. @@ -230,17 +230,17 @@ form again: `internal/webui` receives no holder in any process. ### Deletion gate: SATISFIED (archie-core-8cda.5.6, rev. 2) The objective gate now holds. `go list -deps ./cmd/archie-ui` links **zero** -banned packages: no `modernc.org/sqlite`, no `internal/store`, `internal/gateway`, +banned packages: no `modernc.org/sqlite`, no `github.com/jackc/pgx`, no `internal/infrastructure/postgres`, `internal/gateway`, `internal/channels`, `internal/memory`, `internal/secret`, `internal/agentexec`, `internal/tools`, `internal/skill`, `internal/yaegiutil`, `internal/domain/curator`, or the workflow engine (`internal/domain/workflow`). How the runtime handles were severed, each at the producer: - **Store contracts** moved to `internal/domain/storecontract` (producer-owned - read contracts, state-store-contract rev. 2d); `internal/store` keeps aliases. + read contracts, state-store-contract rev. 2d). - **Chat contracts** moved to `internal/domain/messaging`; `internal/gateway` keeps aliases. The UI process holds `ChatContract`, `SessionStore`, turn and - stream types without linking the gateway runtime or its SQLite session store. + stream types without linking the gateway runtime or its session store. - **Webui-owned views** replaced concrete runtime handles on `webui.Server`: channel lifecycle via `internal/channels/status`, memory via a `MemoryStatus` interface, curators via a `CuratorStatus` interface, and the skill catalogue diff --git a/install.sh b/install.sh index a91fabe56..bcb14c393 100755 --- a/install.sh +++ b/install.sh @@ -8,9 +8,9 @@ # - env (environment variables & API secrets) # - persona/ # - skills/ -# Data: ${XDG_DATA_HOME:-~/.local/share}/archie -# - archie.db-tasks.sqlite -# - archie.db-conversations.sqlite +# Data: ${XDG_DATA_HOME:-~/.local/share}/archie (state_dir) +# - nats/ +# - logs/tasks/ # - work/ # - memories/ # - tasks/ @@ -186,7 +186,7 @@ echo "==> Building native archie binaries..." # ask each installed binary what it is (archie-core-k94o). LDFLAGS="${LDFLAGS} -X github.com/samcharles93/archie-core/internal/buildinfo.Version=${GATEWAY_VERSION}" LDFLAGS="${LDFLAGS} -X github.com/samcharles93/archie-core/internal/buildinfo.Runtime=${RUNTIME_VERSION}" - # archied does not run alone: the State Store owns archie.db, the Gateway + # archied does not run alone: the State Store owns the task data, the Gateway # serves the chat contract, the dashboard is its own process, and the # Messaging Service owns the chat channels. Building only archied leaves it # unable to boot, and omitting archie-messaging leaves the Telegram, email and @@ -460,7 +460,7 @@ RestartSec=5s WantedBy=default.target EOF - # The State Store owns archie.db and is the process everything else dials, so + # The State Store owns the task data and is the process everything else dials, so # its unit is the first dependency the others name. cat < "${SYSTEMD_USER_DIR}/archie-state-store.service" [Unit] From f4b8707ba9ebf5e83e2b6e7b1edb2b823f8eb8f8 Mon Sep 17 00:00:00 2001 From: Sam Catlow Date: Thu, 24 Sep 2026 19:39:06 +1000 Subject: [PATCH 8/8] docs(store): drop residual SQLite references; fix lane lint findings --- cmd/archie-state-store/main.go | 11 ++--- cmd/archie-state-store/main_test.go | 4 +- cmd/archie-ui/architecture_test.go | 2 +- internal/app/archied/bootstrap.go | 2 +- .../archied/chat_store_composition_test.go | 3 +- .../archied/config_snapshot_channels_test.go | 3 +- internal/app/archied/config_snapshot_test.go | 3 +- internal/app/archied/main.go | 6 +-- internal/app/archied/main_test.go | 3 +- internal/app/archied/nats/endpoint.json | 2 +- .../$G/streams/ARCHIE_REACTIONS/msgs/1.blk | Bin 51 -> 153 bytes .../ARCHIE_REACTIONS/obs/QZFaSGZ6/meta.inf | 1 + .../ARCHIE_REACTIONS/obs/QZFaSGZ6/meta.sum | 1 + .../ARCHIE_REACTIONS/obs/QZFaSGZ6/o.dat | Bin 0 -> 18 bytes .../obs/archie-daemon/meta.inf | 2 +- .../obs/archie-daemon/meta.sum | 2 +- .../ARCHIE_REACTIONS/obs/jRzCdtm6/meta.inf | 1 + .../ARCHIE_REACTIONS/obs/jRzCdtm6/meta.sum | 1 + .../ARCHIE_REACTIONS/obs/jRzCdtm6/o.dat | Bin 0 -> 8 bytes .../ARCHIE_REACTIONS/obs/kmNsDMt5/meta.inf | 1 + .../ARCHIE_REACTIONS/obs/kmNsDMt5/meta.sum | 1 + .../ARCHIE_REACTIONS/obs/kmNsDMt5/o.dat | Bin 0 -> 8 bytes .../ARCHIE_REACTIONS/obs/nYF2oUak/meta.inf | 1 + .../ARCHIE_REACTIONS/obs/nYF2oUak/meta.sum | 1 + .../ARCHIE_REACTIONS/obs/nYF2oUak/o.dat | Bin 0 -> 18 bytes .../ARCHIE_REACTIONS/obs/s3Z87297/meta.inf | 2 +- .../ARCHIE_REACTIONS/obs/s3Z87297/meta.sum | 2 +- .../ARCHIE_REACTIONS/obs/sg9Gl4th/meta.inf | 2 +- .../ARCHIE_REACTIONS/obs/sg9Gl4th/meta.sum | 2 +- .../ARCHIE_TASKS/obs/archie-daemon/meta.inf | 2 +- .../ARCHIE_TASKS/obs/archie-daemon/meta.sum | 2 +- internal/app/archied/readiness_test.go | 3 +- internal/app/archied/routing_bindings_test.go | 3 +- internal/app/archied/sd_notify_test.go | 3 +- internal/app/archied/state_store.go | 2 +- .../app/archied/state_store_client_test.go | 4 +- .../app/archied/state_store_consumers_test.go | 3 +- .../app/archied/state_store_toolcalls_test.go | 2 +- internal/app/archied/step_vocabulary.go | 2 +- .../app/archied/task_action_adapter_test.go | 3 +- internal/app/archied/task_actions_test.go | 3 +- internal/daemon/daemon.go | 2 +- internal/daemon/dispatch_bindings_test.go | 8 +--- internal/domain/scheduling/cron.go | 41 +++++++++++------- .../domain/storecontract/storecontract.go | 15 +++---- .../domain/workflow/store_integration_test.go | 5 +-- internal/domain/workflow/task/task.go | 4 +- internal/events/events.go | 2 +- internal/gateway/compress_identity_test.go | 2 +- internal/gateway/task_tools.go | 8 ++-- internal/gateway/tasks.go | 4 +- internal/gateway/turn_ledger_test.go | 17 ++++++-- .../captureintake/receiver_test.go | 2 +- internal/infrastructure/postgres/store.go | 6 +-- internal/infrastructure/readiness/probes.go | 2 +- .../staterpc/capture_stream_test.go | 2 +- .../staterpc/conformance_test.go | 2 +- internal/infrastructure/staterpc/server.go | 2 +- .../staterpc/task_grants_test.go | 2 +- .../infrastructure/staterpc/values_test.go | 2 +- internal/taskstate/taskstate.go | 2 +- internal/webui/webui_test.go | 3 +- 62 files changed, 113 insertions(+), 111 deletions(-) create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/QZFaSGZ6/meta.inf create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/QZFaSGZ6/meta.sum create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/QZFaSGZ6/o.dat create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/jRzCdtm6/meta.inf create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/jRzCdtm6/meta.sum create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/jRzCdtm6/o.dat create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/kmNsDMt5/meta.inf create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/kmNsDMt5/meta.sum create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/kmNsDMt5/o.dat create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/nYF2oUak/meta.inf create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/nYF2oUak/meta.sum create mode 100644 internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/nYF2oUak/o.dat diff --git a/cmd/archie-state-store/main.go b/cmd/archie-state-store/main.go index c95b8f2c2..30cf1c573 100644 --- a/cmd/archie-state-store/main.go +++ b/cmd/archie-state-store/main.go @@ -1,11 +1,6 @@ -// Command archie-state-store hosts the State Store's gRPC contract and owns -// the single archie.db SQLite file. It is the .4.3 companion to the daemon's -// in-process State Store server: the same StateStoreService .4.2 serves, but -// extracted into its own process with its own store lifecycle. -// -// The gateway's session SQLite is owned by the separate archie-gateway process -// and is untouched here. See docs/prds/state-store-contract.md (rev. 2c) §5, -// §9 and §11. +// Command archie-state-store hosts the State Store's gRPC contract and is the +// only process that owns the PostgreSQL stores behind it. See +// docs/prds/state-store-contract.md §5, §9 and §11. package main import ( diff --git a/cmd/archie-state-store/main_test.go b/cmd/archie-state-store/main_test.go index 3f8d5d82b..b68397fb8 100644 --- a/cmd/archie-state-store/main_test.go +++ b/cmd/archie-state-store/main_test.go @@ -5,10 +5,10 @@ // // This is the .4.7 end-to-end verification for // docs/prds/state-store-contract.md (rev. 2c): it proves the process owns the -// single archie.db task SQLite, serves the combined task/event/capture +// task store, serves the combined task/event/capture // surface over one gRPC service, preserves error-sentinel fidelity across the // wire, honours a per-call deadline, survives a restart/recovery cycle, and -// is the sole owner of the SQLite file. See §5 (binary layout), §6 (handoff), +// is the sole owner of the store. See §5 (binary layout), §6 (handoff), // §7 (error semantics), §11 (remote adapter) and §12 step 7/8 (single owner). package main diff --git a/cmd/archie-ui/architecture_test.go b/cmd/archie-ui/architecture_test.go index e8ad16a66..30f55643e 100644 --- a/cmd/archie-ui/architecture_test.go +++ b/cmd/archie-ui/architecture_test.go @@ -1,6 +1,6 @@ // This file enforces the objective half of the UI Service deletion gate // (docs/prds/ui-service-boundary.md, "The deletion gate is objective"). The -// composition half -- no config.Holder, no concrete *store.Store, no Gateway +// composition half -- no config.Holder, no concrete task store, no Gateway // runtime type -- is pinned by internal/app/archieui's // TestComposeUIServerHoldsNoDaemonState. This pins the claim that test cannot // see: that the linked binary carries no daemon runtime at all. Go imports diff --git a/internal/app/archied/bootstrap.go b/internal/app/archied/bootstrap.go index 43df551da..4f174f4b9 100644 --- a/internal/app/archied/bootstrap.go +++ b/internal/app/archied/bootstrap.go @@ -475,7 +475,7 @@ func (b *boot) loadCatalog(ctx context.Context, cfgPath string) { b.log.Info("model catalog loaded", "providers", len(catalog.Providers), "models", len(b.catalogModels)) } -// setupObservability builds the event bus and dashboard server. Every event is logged to SQLite (stamped with its row id) and +// setupObservability builds the event bus and dashboard server. Every event is persisted (stamped with its row id) and // then fanned out to live dashboard connections. func (b *boot) setupObservability(ctx context.Context) { cfg, log := b.cfg, b.log diff --git a/internal/app/archied/chat_store_composition_test.go b/internal/app/archied/chat_store_composition_test.go index b4e96a929..610260383 100644 --- a/internal/app/archied/chat_store_composition_test.go +++ b/internal/app/archied/chat_store_composition_test.go @@ -5,10 +5,9 @@ import ( "path/filepath" "testing" - "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" - "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/gateway" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest" ) diff --git a/internal/app/archied/config_snapshot_channels_test.go b/internal/app/archied/config_snapshot_channels_test.go index cc85dd889..758a2b41d 100644 --- a/internal/app/archied/config_snapshot_channels_test.go +++ b/internal/app/archied/config_snapshot_channels_test.go @@ -5,9 +5,8 @@ import ( "log/slog" "testing" - "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" - "github.com/samcharles93/archie-core/internal/config" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/webui" ) diff --git a/internal/app/archied/config_snapshot_test.go b/internal/app/archied/config_snapshot_test.go index c2f9546f5..f08bf34d7 100644 --- a/internal/app/archied/config_snapshot_test.go +++ b/internal/app/archied/config_snapshot_test.go @@ -6,10 +6,9 @@ import ( "log/slog" "testing" - "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" - "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/infrastructure/configuration" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/webui" ) diff --git a/internal/app/archied/main.go b/internal/app/archied/main.go index 045dcffbe..fcaaa0129 100644 --- a/internal/app/archied/main.go +++ b/internal/app/archied/main.go @@ -138,7 +138,7 @@ func toolLimits(cfg config.Config) agentexec.ToolLimits { const taskListOverRead = 5 // chatTaskListerAdapter gives the gateway a read view of one identity's tasks. -// gateway deliberately does not import internal/store, so the projection +// gateway deliberately does not import the task store, so the projection // happens here, as it does for the writer and controller adapters below. type chatTaskListerAdapter struct { tasks func(context.Context, int) ([]workflow.Task, error) @@ -608,7 +608,7 @@ func (a chatTaskControllerAdapter) CancelChatTask(ctx context.Context, taskID in } // chatTaskLogReaderAdapter gives the gateway a read view of a task's -// persisted log history without importing internal/logging or internal/store +// persisted log history without importing internal/logging or the task store // into the gateway package. Each identity's reader is scoped to its own // tasks: the identity bound at construction is used for authorization, so a // model cannot read another identity's task logs by passing a different @@ -803,7 +803,7 @@ func subscribeSystemLogs(nc *natsio.Conn, taskLogs *logging.TaskRegistry, log *s // progress, outcome, parking) here because that worker's own *events.Bus is // in-process and invisible to the daemon; this is the other half of the // bridge, landing them on bus so persistAndBroadcastEvents -- the single -// choke point that inserts into the SQLite events table and fans out over +// choke point that inserts into the events table and fans out over // SSE -- treats them exactly like every other daemon-observed event. Mirrors // subscribeSystemLogs's demux-by-taskID shape. func subscribeAgentEvents(nc *natsio.Conn, bus *events.Bus, log *slog.Logger) (unsubscribe func(), err error) { diff --git a/internal/app/archied/main_test.go b/internal/app/archied/main_test.go index bc99a28a7..accc1ab7e 100644 --- a/internal/app/archied/main_test.go +++ b/internal/app/archied/main_test.go @@ -13,8 +13,6 @@ import ( "testing" "time" - "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" - "github.com/nats-io/nats-server/v2/server" natssrv "github.com/nats-io/nats-server/v2/test" natsio "github.com/nats-io/nats.go" @@ -29,6 +27,7 @@ import ( "github.com/samcharles93/archie-core/internal/forge" "github.com/samcharles93/archie-core/internal/forgerpc" "github.com/samcharles93/archie-core/internal/gateway" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/logging" "github.com/samcharles93/archie-core/internal/secret" "github.com/samcharles93/archie-core/internal/tools" diff --git a/internal/app/archied/nats/endpoint.json b/internal/app/archied/nats/endpoint.json index 34e1c7fcc..5ece4aae4 100644 --- a/internal/app/archied/nats/endpoint.json +++ b/internal/app/archied/nats/endpoint.json @@ -1 +1 @@ -{"url":"nats://127.0.0.1:42009","token":"PXDPQYX3SBCBW6MNZTUSB5LNDW"} \ No newline at end of file +{"url":"nats://127.0.0.1:40943","token":"KL5KSFZT4PI5KIHF3GUOYXUTOQ"} \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/msgs/1.blk b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/msgs/1.blk index 422dca8c217b369b5614f87b7f508ce94a0bd6f5..479637b99739a3606aa08027d42f19f52f5a2778 100644 GIT binary patch literal 153 zcmXqJU|?VbVi3?Tc#`I)aYI6cA+abqBQsU6C^a#;Br`uxuOzj&q+)>;Yx}I9FT#w0 wN}0eK7#P~~cZum(;M5{ed|qO@O3WLO7G|iH_~k#}yW`gKE_-Xm_qm4O04T{Zh5!Hn delta 5 McmbQqXgt9f00i;@kpKVy diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/QZFaSGZ6/meta.inf b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/QZFaSGZ6/meta.inf new file mode 100644 index 000000000..ab7e4762f --- /dev/null +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/QZFaSGZ6/meta.inf @@ -0,0 +1 @@ +{"Created":"0001-01-01T00:00:00Z","Name":"","name":"QZFaSGZ6","deliver_policy":"all","ack_policy":"explicit","ack_wait":30000000000,"max_deliver":-1,"filter_subject":"archie.reaction.\u003e","replay_policy":"instant","max_waiting":512,"max_ack_pending":1000,"inactive_threshold":5000000000,"num_replicas":0,"metadata":{"_nats.req.level":"0"}} \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/QZFaSGZ6/meta.sum b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/QZFaSGZ6/meta.sum new file mode 100644 index 000000000..bb4f54738 --- /dev/null +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/QZFaSGZ6/meta.sum @@ -0,0 +1 @@ +fb9d97471241c535 \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/QZFaSGZ6/o.dat b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/QZFaSGZ6/o.dat new file mode 100644 index 0000000000000000000000000000000000000000..b594d2ea741959241905aa99a5489c719465dba6 GIT binary patch literal 18 ZcmWe*VqjooWPGz{`D$K9##0lR7yu*O1c3km literal 0 HcmV?d00001 diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/archie-daemon/meta.inf b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/archie-daemon/meta.inf index ddd6e649a..135b0f241 100644 --- a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/archie-daemon/meta.inf +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/archie-daemon/meta.inf @@ -1 +1 @@ -{"Created":"2026-09-24T04:46:09.06756232Z","Name":"archie-daemon","durable_name":"archie-daemon","name":"archie-daemon","deliver_policy":"all","ack_policy":"explicit","ack_wait":300000000000,"max_deliver":3,"filter_subject":"archie.reaction.\u003e","replay_policy":"instant","max_waiting":512,"max_ack_pending":1000,"inactive_threshold":86400000000000,"num_replicas":0,"metadata":{"_nats.req.level":"0"}} \ No newline at end of file +{"Created":"2026-09-24T09:38:53.493195549Z","Name":"archie-daemon","durable_name":"archie-daemon","name":"archie-daemon","deliver_policy":"all","ack_policy":"explicit","ack_wait":300000000000,"max_deliver":3,"filter_subject":"archie.reaction.\u003e","replay_policy":"instant","max_waiting":512,"max_ack_pending":1000,"inactive_threshold":86400000000000,"num_replicas":0,"metadata":{"_nats.req.level":"0"}} \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/archie-daemon/meta.sum b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/archie-daemon/meta.sum index 7e55c58e9..7668ca660 100644 --- a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/archie-daemon/meta.sum +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/archie-daemon/meta.sum @@ -1 +1 @@ -d87c12a35c167265 \ No newline at end of file +989e2c19cd43eee8 \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/jRzCdtm6/meta.inf b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/jRzCdtm6/meta.inf new file mode 100644 index 000000000..750d283dc --- /dev/null +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/jRzCdtm6/meta.inf @@ -0,0 +1 @@ +{"Created":"2026-09-24T09:38:53.500447377Z","Name":"jRzCdtm6","name":"jRzCdtm6","deliver_policy":"all","ack_policy":"explicit","ack_wait":30000000000,"max_deliver":-1,"filter_subject":"archie.reaction.\u003e","replay_policy":"instant","max_waiting":512,"max_ack_pending":1000,"num_replicas":0,"metadata":{"_nats.req.level":"0"}} \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/jRzCdtm6/meta.sum b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/jRzCdtm6/meta.sum new file mode 100644 index 000000000..2c2c94c55 --- /dev/null +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/jRzCdtm6/meta.sum @@ -0,0 +1 @@ +620c347e0e296f80 \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/jRzCdtm6/o.dat b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/jRzCdtm6/o.dat new file mode 100644 index 0000000000000000000000000000000000000000..f291c5c9aee705825aeb37a04f10452de37894c4 GIT binary patch literal 8 NcmWe*Vgv#P1^@uq0384T literal 0 HcmV?d00001 diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/kmNsDMt5/meta.inf b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/kmNsDMt5/meta.inf new file mode 100644 index 000000000..95325b28b --- /dev/null +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/kmNsDMt5/meta.inf @@ -0,0 +1 @@ +{"Created":"2026-09-24T09:38:53.500003272Z","Name":"kmNsDMt5","name":"kmNsDMt5","deliver_policy":"all","ack_policy":"explicit","ack_wait":30000000000,"max_deliver":-1,"filter_subject":"archie.reaction.\u003e","replay_policy":"instant","max_waiting":512,"max_ack_pending":1000,"num_replicas":0,"metadata":{"_nats.req.level":"0"}} \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/kmNsDMt5/meta.sum b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/kmNsDMt5/meta.sum new file mode 100644 index 000000000..918537729 --- /dev/null +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/kmNsDMt5/meta.sum @@ -0,0 +1 @@ +e571c54b14192a8c \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/kmNsDMt5/o.dat b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/kmNsDMt5/o.dat new file mode 100644 index 0000000000000000000000000000000000000000..f291c5c9aee705825aeb37a04f10452de37894c4 GIT binary patch literal 8 NcmWe*Vgv#P1^@uq0384T literal 0 HcmV?d00001 diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/nYF2oUak/meta.inf b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/nYF2oUak/meta.inf new file mode 100644 index 000000000..5fa815f45 --- /dev/null +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/nYF2oUak/meta.inf @@ -0,0 +1 @@ +{"Created":"0001-01-01T00:00:00Z","Name":"","name":"nYF2oUak","deliver_policy":"all","ack_policy":"explicit","ack_wait":30000000000,"max_deliver":-1,"filter_subject":"archie.reaction.\u003e","replay_policy":"instant","max_waiting":512,"max_ack_pending":1000,"inactive_threshold":5000000000,"num_replicas":0,"metadata":{"_nats.req.level":"0"}} \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/nYF2oUak/meta.sum b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/nYF2oUak/meta.sum new file mode 100644 index 000000000..17ef7664d --- /dev/null +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/nYF2oUak/meta.sum @@ -0,0 +1 @@ +52d9f8cea485537a \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/nYF2oUak/o.dat b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/nYF2oUak/o.dat new file mode 100644 index 0000000000000000000000000000000000000000..b594d2ea741959241905aa99a5489c719465dba6 GIT binary patch literal 18 ZcmWe*VqjooWPGz{`D$K9##0lR7yu*O1c3km literal 0 HcmV?d00001 diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/s3Z87297/meta.inf b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/s3Z87297/meta.inf index 3af67b620..f0394cd23 100644 --- a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/s3Z87297/meta.inf +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/s3Z87297/meta.inf @@ -1 +1 @@ -{"Created":"2026-09-24T04:46:09.078999729Z","Name":"s3Z87297","name":"s3Z87297","deliver_policy":"all","ack_policy":"explicit","ack_wait":30000000000,"max_deliver":-1,"filter_subject":"archie.reaction.\u003e","replay_policy":"instant","max_waiting":512,"max_ack_pending":1000,"num_replicas":0,"metadata":{"_nats.req.level":"0"}} \ No newline at end of file +{"Created":"0001-01-01T00:00:00Z","Name":"","name":"s3Z87297","deliver_policy":"all","ack_policy":"explicit","ack_wait":30000000000,"max_deliver":-1,"filter_subject":"archie.reaction.\u003e","replay_policy":"instant","max_waiting":512,"max_ack_pending":1000,"inactive_threshold":5000000000,"num_replicas":0,"metadata":{"_nats.req.level":"0"}} \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/s3Z87297/meta.sum b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/s3Z87297/meta.sum index f8024e5e9..8b73fe0fb 100644 --- a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/s3Z87297/meta.sum +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/s3Z87297/meta.sum @@ -1 +1 @@ -8f8b6852faee5da4 \ No newline at end of file +218aa24a9029a5b8 \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/sg9Gl4th/meta.inf b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/sg9Gl4th/meta.inf index 338606278..ac599128b 100644 --- a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/sg9Gl4th/meta.inf +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/sg9Gl4th/meta.inf @@ -1 +1 @@ -{"Created":"2026-09-24T04:46:09.079549283Z","Name":"sg9Gl4th","name":"sg9Gl4th","deliver_policy":"all","ack_policy":"explicit","ack_wait":30000000000,"max_deliver":-1,"filter_subject":"archie.reaction.\u003e","replay_policy":"instant","max_waiting":512,"max_ack_pending":1000,"num_replicas":0,"metadata":{"_nats.req.level":"0"}} \ No newline at end of file +{"Created":"0001-01-01T00:00:00Z","Name":"","name":"sg9Gl4th","deliver_policy":"all","ack_policy":"explicit","ack_wait":30000000000,"max_deliver":-1,"filter_subject":"archie.reaction.\u003e","replay_policy":"instant","max_waiting":512,"max_ack_pending":1000,"inactive_threshold":5000000000,"num_replicas":0,"metadata":{"_nats.req.level":"0"}} \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/sg9Gl4th/meta.sum b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/sg9Gl4th/meta.sum index ffa829155..0e91fdf5c 100644 --- a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/sg9Gl4th/meta.sum +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_REACTIONS/obs/sg9Gl4th/meta.sum @@ -1 +1 @@ -3c91a932fe817389 \ No newline at end of file +4719ba6cad8cfe3c \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/obs/archie-daemon/meta.inf b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/obs/archie-daemon/meta.inf index 602f55962..58e5a1544 100644 --- a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/obs/archie-daemon/meta.inf +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/obs/archie-daemon/meta.inf @@ -1 +1 @@ -{"Created":"2026-09-24T04:46:09.068004189Z","Name":"archie-daemon","durable_name":"archie-daemon","name":"archie-daemon","deliver_policy":"all","ack_policy":"explicit","ack_wait":300000000000,"max_deliver":3,"filter_subject":"archie.task.\u003e","replay_policy":"instant","max_waiting":512,"max_ack_pending":1000,"inactive_threshold":86400000000000,"num_replicas":0,"metadata":{"_nats.req.level":"0"}} \ No newline at end of file +{"Created":"2026-09-24T09:38:53.492664758Z","Name":"archie-daemon","durable_name":"archie-daemon","name":"archie-daemon","deliver_policy":"all","ack_policy":"explicit","ack_wait":300000000000,"max_deliver":3,"filter_subject":"archie.task.\u003e","replay_policy":"instant","max_waiting":512,"max_ack_pending":1000,"inactive_threshold":86400000000000,"num_replicas":0,"metadata":{"_nats.req.level":"0"}} \ No newline at end of file diff --git a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/obs/archie-daemon/meta.sum b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/obs/archie-daemon/meta.sum index 60c5000ac..09a3db414 100644 --- a/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/obs/archie-daemon/meta.sum +++ b/internal/app/archied/nats/jetstream/$G/streams/ARCHIE_TASKS/obs/archie-daemon/meta.sum @@ -1 +1 @@ -514bef62122c4381 \ No newline at end of file +424323b7dcce276c \ No newline at end of file diff --git a/internal/app/archied/readiness_test.go b/internal/app/archied/readiness_test.go index 638f1bb16..f31525926 100644 --- a/internal/app/archied/readiness_test.go +++ b/internal/app/archied/readiness_test.go @@ -5,10 +5,9 @@ import ( "path/filepath" "testing" - "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" - "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/gateway" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/webui" ) diff --git a/internal/app/archied/routing_bindings_test.go b/internal/app/archied/routing_bindings_test.go index 080cfc6a5..a264263b3 100644 --- a/internal/app/archied/routing_bindings_test.go +++ b/internal/app/archied/routing_bindings_test.go @@ -4,11 +4,10 @@ import ( "log/slog" "testing" - "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" - "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/domain/workflow" "github.com/samcharles93/archie-core/internal/domain/workintake" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" ) // TestBuildDaemonCarriesWorkflowRoutingBindings pins the composition hop in the diff --git a/internal/app/archied/sd_notify_test.go b/internal/app/archied/sd_notify_test.go index 1d44ea13e..bd2aedcf2 100644 --- a/internal/app/archied/sd_notify_test.go +++ b/internal/app/archied/sd_notify_test.go @@ -14,10 +14,9 @@ import ( "testing" "time" - "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" - "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/daemon" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" ) // notifyRecorder captures every record at every level. The other recording diff --git a/internal/app/archied/state_store.go b/internal/app/archied/state_store.go index cf6492a52..7e056d3fe 100644 --- a/internal/app/archied/state_store.go +++ b/internal/app/archied/state_store.go @@ -213,7 +213,7 @@ func (b *boot) openStateStore(ctx context.Context) error { } // stateStoreDeps assembles the store surfaces the StateStore service fronts. -// b.st is the narrow storecontract.TaskStore; the wide *store.Store also implements +// b.st is the narrow storecontract.TaskStore; the concrete store also implements // the capture/mapping/binding surfaces, so each is asserted here (the same // pattern the daemon's wireWebStoreSurfaces uses) and a store that lacks one // degrades that group rather than aborting boot. diff --git a/internal/app/archied/state_store_client_test.go b/internal/app/archied/state_store_client_test.go index 5fabfd7e4..50a0e87f0 100644 --- a/internal/app/archied/state_store_client_test.go +++ b/internal/app/archied/state_store_client_test.go @@ -68,7 +68,7 @@ func TestOpenStateStoreAdapterRequiresTarget(t *testing.T) { b.secrets = &secret.Registry{} // After .4.6 the daemon and gateway no longer own archie.db in-process, so // an empty [services.state].target is a composition error, not the old - // local *store.Store default (docs/prds/state-store-contract.md §12 step 7). + // local task-store default (docs/prds/state-store-contract.md §12 step 7). if err := b.openStateStoreAdapter(); err == nil { t.Fatal("empty services.state.target should error: the in-process store path is deleted") } @@ -98,7 +98,7 @@ func TestStateStoreSingleOwnerComposition(t *testing.T) { b := newBootstrap() b.secrets = &secret.Registry{} - // The daemon openStores path must not construct a local *store.Store. + // The daemon openStores path must not construct a local task store. // openStores only resolves secrets and the forge client, then opens chat // sessions; the task store surface comes from the remote adapter, so no // archie.db task file is touched. This asserts openStateStoreAdapter (the diff --git a/internal/app/archied/state_store_consumers_test.go b/internal/app/archied/state_store_consumers_test.go index a78e15d7c..ede6466fc 100644 --- a/internal/app/archied/state_store_consumers_test.go +++ b/internal/app/archied/state_store_consumers_test.go @@ -4,9 +4,8 @@ import ( "log/slog" "testing" - "github.com/samcharles93/archie-core/internal/infrastructure/postgres" - "github.com/samcharles93/archie-core/internal/config" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres" "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" taskactionstore "github.com/samcharles93/archie-core/internal/infrastructure/taskactions" ) diff --git a/internal/app/archied/state_store_toolcalls_test.go b/internal/app/archied/state_store_toolcalls_test.go index 92a7048c6..6c29e49d6 100644 --- a/internal/app/archied/state_store_toolcalls_test.go +++ b/internal/app/archied/state_store_toolcalls_test.go @@ -124,7 +124,7 @@ func TestInsertEventLeavesOtherKindsUnprojected(t *testing.T) { } } -// failingToolCallWriter stands in for a broken PocketBase side, so the +// failingToolCallWriter stands in for a broken event-capture store, so the // never-returned-failure contract can be tested without sabotaging the real // store. type failingToolCallWriter struct{ err error } diff --git a/internal/app/archied/step_vocabulary.go b/internal/app/archied/step_vocabulary.go index 8815c15ce..68600f9ae 100644 --- a/internal/app/archied/step_vocabulary.go +++ b/internal/app/archied/step_vocabulary.go @@ -21,7 +21,7 @@ import ( // // It is a named function so that step_vocabulary_test.go can fail if a root // stops resolving the shipped stages, or hands a constructor a manager other -// than the one this returns; the roots themselves own a SQLite file and dial +// than the one this returns; the roots themselves open a database and dial // gRPC, so the test asserts their wiring by parsing their bodies. // // Agreement is within one build: the State Store and archie-agent are diff --git a/internal/app/archied/task_action_adapter_test.go b/internal/app/archied/task_action_adapter_test.go index fc7e66286..2daa8428c 100644 --- a/internal/app/archied/task_action_adapter_test.go +++ b/internal/app/archied/task_action_adapter_test.go @@ -7,13 +7,12 @@ import ( "strings" "testing" - "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" - "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/domain/taskactions" "github.com/samcharles93/archie-core/internal/domain/workflow" "github.com/samcharles93/archie-core/internal/gateway" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/taskstate" ) diff --git a/internal/app/archied/task_actions_test.go b/internal/app/archied/task_actions_test.go index cbe1af4d2..4754d72fd 100644 --- a/internal/app/archied/task_actions_test.go +++ b/internal/app/archied/task_actions_test.go @@ -9,12 +9,11 @@ import ( "strconv" "testing" - "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" - "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/domain/workflow" "github.com/samcharles93/archie-core/internal/gateway" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" "github.com/samcharles93/archie-core/internal/webui" ) diff --git a/internal/daemon/daemon.go b/internal/daemon/daemon.go index 7823f027b..568b5a7d3 100644 --- a/internal/daemon/daemon.go +++ b/internal/daemon/daemon.go @@ -835,7 +835,7 @@ func (d *Daemon) botUserForTask(task *workflowtask.Task) string { return d.Cfg.Get().BotUser } -// drainNATS processes tasks from NATS, falling back to SQLite ClaimNext for +// drainNATS processes tasks from NATS, falling back to the task store's ClaimNext for // requeued tasks (waiting_human approval, retry-parked) that didn't come // through a NATS publish. func (d *Daemon) drainNATS(ctx context.Context) { diff --git a/internal/daemon/dispatch_bindings_test.go b/internal/daemon/dispatch_bindings_test.go index d460aaa31..653ff6194 100644 --- a/internal/daemon/dispatch_bindings_test.go +++ b/internal/daemon/dispatch_bindings_test.go @@ -245,12 +245,6 @@ func TestDispatchBindingsNilDispatcherIsNoOp(t *testing.T) { // ── helpers ────────────────────────────────────────────────────── -// openDispatchTestStore creates a fresh in-memory SQLite store for -// each dispatch test. The TempDir anchor matches store.OpenTest's -// own convention; tests rely on the same schema-migration path -// production uses (CREATE TABLE + ALTER TABLE migrations), so -// binding_id / binding_version / binding_dispatches all exist on the -// store by the time a test runs. // dispatchStores pairs the two stores the dispatcher spans: the task store and // the event-capture store, so a seed helper reads as one handle. type dispatchStores struct { @@ -259,6 +253,8 @@ type dispatchStores struct { edaPool *pgxpool.Pool } +// openDispatchTestStore opens fresh migrated task and event-capture stores for +// each dispatch test. func openDispatchTestStore(t *testing.T) *dispatchStores { t.Helper() s := pgstore.Open(t) diff --git a/internal/domain/scheduling/cron.go b/internal/domain/scheduling/cron.go index 73ebe0c4e..0daeba0d7 100644 --- a/internal/domain/scheduling/cron.go +++ b/internal/domain/scheduling/cron.go @@ -82,22 +82,9 @@ func parseCronSegment(segment string, lo, hi int) (cronSlots, error) { } step = n } - first, last := lo, hi - if base != "*" { - from, to, ranged := strings.Cut(base, "-") - if !ranged && stepped { - return 0, fmt.Errorf("step in %q needs a wildcard or a range", part) - } - var err error - if first, err = cronValue(from, lo, hi); err != nil { - return 0, err - } - last = first - if ranged { - if last, err = cronValue(to, first, hi); err != nil { - return 0, err - } - } + first, last, err := cronRange(base, part, stepped, lo, hi) + if err != nil { + return 0, err } for v := first; v <= last; v += step { slots |= 1 << v @@ -106,6 +93,28 @@ func parseCronSegment(segment string, lo, hi int) (cronSlots, error) { return slots, nil } +// cronRange returns the values base names: every value for "*", else a +// single value or a from-to range. +func cronRange(base, part string, stepped bool, lo, hi int) (first, last int, err error) { + if base == "*" { + return lo, hi, nil + } + from, to, ranged := strings.Cut(base, "-") + if !ranged && stepped { + return 0, 0, fmt.Errorf("step in %q needs a wildcard or a range", part) + } + if first, err = cronValue(from, lo, hi); err != nil { + return 0, 0, err + } + if !ranged { + return first, first, nil + } + if last, err = cronValue(to, first, hi); err != nil { + return 0, 0, err + } + return first, last, nil +} + func cronValue(text string, lo, hi int) (int, error) { v, err := strconv.Atoi(text) if err != nil { diff --git a/internal/domain/storecontract/storecontract.go b/internal/domain/storecontract/storecontract.go index 74628182b..ce7538af2 100644 --- a/internal/domain/storecontract/storecontract.go +++ b/internal/domain/storecontract/storecontract.go @@ -1,8 +1,8 @@ // Package storecontract is the ratified State Store contract as its // consumers reference it: the producer-owned daemon/webui/intake store // surfaces (docs/prds/state-store-contract.md §1, §2). It carries no -// persistence -- *store.Store (SQLite, transitional location) and -// *staterpc.Client (the remote adapter) both satisfy these interfaces -- +// persistence -- internal/infrastructure/postgres and *staterpc.Client (the +// remote adapter) both satisfy these interfaces -- // so a process that only holds the contracts, such as the archie-ui // dashboard process, can reference them without linking the SQL // implementation. @@ -10,9 +10,7 @@ // It is hand-written and lives in the domain layer (which owns required // contracts), NOT under internal/contracts: that tree is the buf generate // output and is wiped and regenerated by tools/proto.sh, which would -// delete a hand-written file there (archie-core-8cda.5.6). Relocated from -// internal/store by the UI Service deletion gate; internal/store keeps -// type aliases so daemon-side callers are unaffected. +// delete a hand-written file there (archie-core-8cda.5.6). package storecontract import ( @@ -230,7 +228,7 @@ type BindingTaskCreator interface { // playbook's ledger rows on explicit request only: a playbook file missing at // boot may be an unmounted directory, and reclaiming on that would let // redelivered events fire again. There is deliberately no *sql.Tx: any -// transaction stays server-side inside internal/store. +// transaction stays server-side inside the store. type PlaybookDispatcher interface { RecordPlaybookDispatch(ctx context.Context, playbookID, playbookVersion, eventID, actionID string) error DeletePlaybookDispatches(ctx context.Context, playbookID string) error @@ -382,9 +380,8 @@ var ( // Resource is one control-plane resource document: the stored value for a // kind, its revision, and the audit record written with the last write. -// Resource and ResourceWrite live here (rather than internal/store) so the -// PostgreSQL implementation and the UI-side consumers can reference them -// without linking the SQLite implementation. +// Resource and ResourceWrite live here so the UI-side consumers can reference +// them without linking the PostgreSQL implementation. type Resource struct { Kind string Value []byte diff --git a/internal/domain/workflow/store_integration_test.go b/internal/domain/workflow/store_integration_test.go index 84d3061e7..6750ce75f 100644 --- a/internal/domain/workflow/store_integration_test.go +++ b/internal/domain/workflow/store_integration_test.go @@ -7,11 +7,10 @@ import ( "strings" "testing" - "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" - "github.com/samcharles93/archie-core/internal/agentexec" "github.com/samcharles93/archie-core/internal/config" "github.com/samcharles93/archie-core/internal/domain/workflow" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" ) // storeIntegrationRunner is a minimal agentexec.Runner stub, duplicated @@ -19,7 +18,7 @@ import ( // lives in the external workflow_test package: it needs the real // *pgstore.TaskDB as a workflow.Store, and the package under test now owns // workflow.Task/Status/Source, which would otherwise cycle back through -// internal/store's dependency on internal/domain/workflow. +// the store's dependency on internal/domain/workflow. type storeIntegrationRunner struct { result agentexec.Result } diff --git a/internal/domain/workflow/task/task.go b/internal/domain/workflow/task/task.go index 0a8dbd410..3ac6adba8 100644 --- a/internal/domain/workflow/task/task.go +++ b/internal/domain/workflow/task/task.go @@ -33,7 +33,7 @@ const ( ) // Task is the task-execution record the workflow domain operates on. -// internal/store persists this type (persistence -> domain). +// internal/infrastructure/postgres persists this type (persistence -> domain). type Task struct { ID int64 `json:"id"` Owner string `json:"owner"` @@ -134,7 +134,7 @@ func (t Task) IsForgeBacked() bool { } // Store is the narrow, consumer-owned subset of the State Store contract -// that workflow stages call mid-run. *store.Store and staterpc.Client +// that workflow stages call mid-run. The PostgreSQL store and staterpc.Client // satisfy it; this is the interface archie-agent uses over the gRPC State // Store contract. It supersedes store.WorkflowStore. type Store interface { diff --git a/internal/events/events.go b/internal/events/events.go index 6676faf9a..d5e1cd2ae 100644 --- a/internal/events/events.go +++ b/internal/events/events.go @@ -106,7 +106,7 @@ const ( KindTurnCompleted = "turn_completed" // EDA edit activity (bindings and mappings on the captures store). Each - // successful write on the State Store's PocketBase tables emits one + // successful write on the State Store's binding and mapping tables emits one // event through the same task-DB path capture arrival uses, so a // dashboard edit is visible on the activity stream without a manual // refresh. data: id (the edited record), action (create, update, diff --git a/internal/gateway/compress_identity_test.go b/internal/gateway/compress_identity_test.go index aeeb6f8bf..9ecdb2d58 100644 --- a/internal/gateway/compress_identity_test.go +++ b/internal/gateway/compress_identity_test.go @@ -13,7 +13,7 @@ import ( func compressBackends() map[string]func(t *testing.T) SessionStore { return map[string]func(t *testing.T) SessionStore{ "memory": func(*testing.T) SessionStore { return NewSessionStoreMemory() }, - "postgres": func(t *testing.T) SessionStore { return newPostgresStore(t) }, + "postgres": newPostgresStore, } } diff --git a/internal/gateway/task_tools.go b/internal/gateway/task_tools.go index 88cb409fe..243284c98 100644 --- a/internal/gateway/task_tools.go +++ b/internal/gateway/task_tools.go @@ -53,7 +53,7 @@ type ChatTaskSummary struct { // ChatTaskLister is the read surface the task tools need. It mirrors the // existing chatTaskWriter/chatTaskController pattern: gateway states what it // needs and the daemon supplies an adapter over the store, so this package -// keeps its independence from internal/store. +// keeps its independence from the task store. type ChatTaskLister interface { ListChatTasks(ctx context.Context, identity string, limit int) ([]ChatTaskSummary, error) } @@ -72,7 +72,7 @@ type TaskSpawnResult struct { // ChatTaskActor is the mutation surface task_action needs. It mirrors the // ChatTaskLister pattern: gateway states what it needs and the daemon // supplies an adapter over the store and runtime, so this package keeps its -// independence from internal/store. +// independence from the task store. type ChatTaskActor interface { // ApplyChatTaskAction executes action on taskID, scoped to identity's own // tasks. A nil identity is an authenticated dashboard operator, who acts @@ -85,7 +85,7 @@ type ChatTaskActor interface { // ChatTaskLogEntry is one log line as task_logs returns it. It mirrors // internal/logging.Entry's shape without importing that package: gateway // keeps its independence from internal/logging the same way it already does -// from internal/store, with the daemon adapting between them. +// from the task store, with the daemon adapting between them. type ChatTaskLogEntry struct { Time time.Time `json:"time"` Level string `json:"level"` @@ -144,7 +144,7 @@ type ChatTaskLogResult struct { // ChatTaskLogReader is the read surface task_logs needs. It mirrors the // ChatTaskLister pattern: gateway states what it needs and the daemon // supplies an adapter, so this package keeps its independence from -// internal/store and internal/logging. +// the task store and internal/logging. type ChatTaskLogReader interface { // ReadChatTaskLogs returns taskID's log entries for attempt (0 selects // the task's current/latest attempt), scoped to identity's own tasks. diff --git a/internal/gateway/tasks.go b/internal/gateway/tasks.go index 8be724c23..0a307a1ed 100644 --- a/internal/gateway/tasks.go +++ b/internal/gateway/tasks.go @@ -41,7 +41,7 @@ type taskProfile struct { // chatTaskWriter is the write surface StoreTaskCreator needs. It // returns the created task's real database ID, not a *workflow.Task -- -// gateway deliberately has no dependency on internal/store or +// gateway deliberately has no dependency on the task store or // internal/domain/workflow; the daemon supplies an adapter closure over // the store.TaskStore method of the same name. type chatTaskWriter interface { @@ -116,7 +116,7 @@ func splitOwnerRepo(s string) (owner, repo string, ok bool) { } // Task lifecycle statuses come from internal/taskstate, a leaf package with -// no dependencies, so gateway stays decoupled from internal/store without +// no dependencies, so gateway stays decoupled from the task store without // keeping a hand-synced copy of the strings. The copy that used to live here // is how the dashboard and chat ended up recording different states for the // same operator decision. diff --git a/internal/gateway/turn_ledger_test.go b/internal/gateway/turn_ledger_test.go index c3021acb2..7af0254b8 100644 --- a/internal/gateway/turn_ledger_test.go +++ b/internal/gateway/turn_ledger_test.go @@ -18,14 +18,14 @@ func TestTurnLedgerClaimLifecycleIsIdempotent(t *testing.T) { name: "memory", open: func(t *testing.T) (TurnLedger, func()) { store := NewSessionStoreMemory() - return store.(TurnLedger), func() { _ = store.Close() } + return asTurnLedger(t, store), func() { _ = store.Close() } }, }, { name: "postgres", open: func(t *testing.T) (TurnLedger, func()) { store := newPostgresStore(t) - return store.(TurnLedger), func() { _ = store.Close() } + return asTurnLedger(t, store), func() { _ = store.Close() } }, }, } @@ -113,14 +113,14 @@ func TestTurnLedgerReclaimsAcrossProcessOwnersAndRejectsStaleWrites(t *testing.T name: "memory", open: func(t *testing.T) (TurnLedger, func()) { store := NewSessionStoreMemory() - return store.(TurnLedger), func() { _ = store.Close() } + return asTurnLedger(t, store), func() { _ = store.Close() } }, }, { name: "postgres", open: func(t *testing.T) (TurnLedger, func()) { store := newPostgresStore(t) - return store.(TurnLedger), func() { _ = store.Close() } + return asTurnLedger(t, store), func() { _ = store.Close() } }, }, } @@ -393,3 +393,12 @@ func TestTurnRunnerCanonicalTurnIDRejectsCollidingLegacyRecord(t *testing.T) { got, want, collidingLegacyID) } } + +func asTurnLedger(t *testing.T, store SessionStore) TurnLedger { + t.Helper() + ledger, ok := store.(TurnLedger) + if !ok { + t.Fatalf("%T does not implement TurnLedger", store) + } + return ledger +} diff --git a/internal/infrastructure/captureintake/receiver_test.go b/internal/infrastructure/captureintake/receiver_test.go index 29400ece4..70f54bfee 100644 --- a/internal/infrastructure/captureintake/receiver_test.go +++ b/internal/infrastructure/captureintake/receiver_test.go @@ -212,7 +212,7 @@ func TestHandleCaptureStoresRedactedBody(t *testing.T) { // host process's pipeline (the daemon's bus drain), already tested there. // // The published event is deliberately LIGHTWEIGHT (id + source only, no -// body/headers): the events table this feeds (internal/store/events.go) has +// body/headers): the events table this feeds (the State Store events table) has // no retention or row-count prune, unlike captured_events, so embedding the // full (up to CaptureMaxBodyBytes) payload here would duplicate it into an // unbounded table and defeat the disk-bound guarantee InsertCapture's own diff --git a/internal/infrastructure/postgres/store.go b/internal/infrastructure/postgres/store.go index e6e5faf10..0fcd23f9c 100644 --- a/internal/infrastructure/postgres/store.go +++ b/internal/infrastructure/postgres/store.go @@ -35,14 +35,14 @@ func (s *Store) queries() *postgresdb.Queries { return postgresdb.New(s.pool) } -// Close is a no-op: unlike the SQLite store, this store owns no file handle +// Close is a no-op: this store owns no file handle // or connection -- the pool belongs to the composition that opened it. func (s *Store) Close() error { return nil } // syntheticIssueNumberBase is the seed for a repo's first chat task. The // COALESCE allocator adds one to the passed fallback, so the fallback here is -// base-1 and the first chat task lands on exactly base, matching the SQLite -// store's reserved JSON-safe floor (see internal/store.EnqueueChatTask). +// base-1 and the first chat task lands on exactly base: the reserved +// JSON-safe floor that keeps synthetic issue numbers clear of real ones. const syntheticIssueNumberBase = 1_000_000_000_000_000 // taskFromRow maps the generated task row to the workflow.Task the daemon and diff --git a/internal/infrastructure/readiness/probes.go b/internal/infrastructure/readiness/probes.go index 2192f3d88..a8c94d152 100644 --- a/internal/infrastructure/readiness/probes.go +++ b/internal/infrastructure/readiness/probes.go @@ -26,7 +26,7 @@ import ( // --- state_db --- // statusCounter is the read-only store surface the state_db probe needs. -// The daemon's *store.Store satisfies it; the probe never depends on the +// The task store satisfies it; the probe never depends on the // full task-lifecycle interface. type statusCounter interface { StatusCounts(ctx context.Context) (map[string]int, error) diff --git a/internal/infrastructure/staterpc/capture_stream_test.go b/internal/infrastructure/staterpc/capture_stream_test.go index 0cb54894c..7a89aaecd 100644 --- a/internal/infrastructure/staterpc/capture_stream_test.go +++ b/internal/infrastructure/staterpc/capture_stream_test.go @@ -29,7 +29,7 @@ func TestCaptureListsExceedUnaryMessageLimit(t *testing.T) { t.Fatal(mapErr) } // ListUndispatchedCaptures only returns sources with an armed binding - // (edastore.ArmedBindingsForSource), so "large" needs one taken through the + // (ArmedBindingsForSource), so "large" needs one taken through the // public draft -> pending_approval -> armed lifecycle. id, err := eda.InsertBinding(t.Context(), binding.Binding{ Name: "large binding", Matcher: binding.Matcher{Source: "large"}, diff --git a/internal/infrastructure/staterpc/conformance_test.go b/internal/infrastructure/staterpc/conformance_test.go index d84ddcf07..b484e33a5 100644 --- a/internal/infrastructure/staterpc/conformance_test.go +++ b/internal/infrastructure/staterpc/conformance_test.go @@ -31,7 +31,7 @@ type contract interface { storecontract.ApplyStatusStore } -// edaContract is the event-capture half, which the PocketBase store serves. +// edaContract is the event-capture half, which the PostgreSQL EDA store serves. // It is a separate interface because no single type implements both halves // any more: that split is the point of the migration, not an accident. type edaContract interface { diff --git a/internal/infrastructure/staterpc/server.go b/internal/infrastructure/staterpc/server.go index 808f7252e..856b12443 100644 --- a/internal/infrastructure/staterpc/server.go +++ b/internal/infrastructure/staterpc/server.go @@ -1,4 +1,4 @@ -// Package staterpc adapts the State Store contract (internal/store's +// Package staterpc adapts the State Store contract (internal/domain/storecontract's // producer-owned surfaces plus the consumer-owned workflow.Store) to gRPC. // See docs/prds/state-store-contract.md for the ratified contract this // package implements against. diff --git a/internal/infrastructure/staterpc/task_grants_test.go b/internal/infrastructure/staterpc/task_grants_test.go index def46342a..28d70ad4c 100644 --- a/internal/infrastructure/staterpc/task_grants_test.go +++ b/internal/infrastructure/staterpc/task_grants_test.go @@ -93,7 +93,7 @@ func TestCaptureStreamsCarryTheAdminToken(t *testing.T) { if mapErr != nil { t.Fatal(mapErr) } - // (edastore.ArmedBindingsForSource), so "large" needs one taken through the + // (ArmedBindingsForSource), so "large" needs one taken through the // public draft -> pending_approval -> armed lifecycle. id, err := admin.InsertBinding(ctx, binding.Binding{ Name: "large binding", Matcher: binding.Matcher{Source: "large"}, diff --git a/internal/infrastructure/staterpc/values_test.go b/internal/infrastructure/staterpc/values_test.go index 03875ca61..c513e74b3 100644 --- a/internal/infrastructure/staterpc/values_test.go +++ b/internal/infrastructure/staterpc/values_test.go @@ -94,7 +94,7 @@ func TestTaskLogStageFilterSurvivesTheWire(t *testing.T) { } // TestEventDataJSONPreservesMarshalErrorMarker pins §11's conformance -// invariant: the local store (internal/store/events.go) records a +// invariant: the store records a // {"marshal_error":%q} marker when json.Marshal of event Data fails, so the // remote wire must carry the same marker rather than silently emptying the // Data on the hop. diff --git a/internal/taskstate/taskstate.go b/internal/taskstate/taskstate.go index df133c0d5..c7a902acb 100644 --- a/internal/taskstate/taskstate.go +++ b/internal/taskstate/taskstate.go @@ -9,7 +9,7 @@ // for "the pull request was closed without merging" -- no longer meant one // thing. // -// internal/gateway deliberately does not import internal/store, so it kept a +// internal/gateway deliberately does not import the task store, so it kept a // hand-synced copy of the status strings with a comment asking future editors // to keep them aligned. That is the same defect one level down. This package // has no dependencies, so both can import it and the copy can go. diff --git a/internal/webui/webui_test.go b/internal/webui/webui_test.go index f62e8fbd2..9f1db8ac9 100644 --- a/internal/webui/webui_test.go +++ b/internal/webui/webui_test.go @@ -25,11 +25,10 @@ import ( "testing" "time" - "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" - "github.com/samcharles93/archie-core/internal/domain/storecontract" "github.com/samcharles93/archie-core/internal/domain/workflow" "github.com/samcharles93/archie-core/internal/events" + "github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore" ) func newTestServer(t *testing.T) *Server {