Merge branch 'worktree-agent-a96503bc8828fc104' into pg/foundation

This commit is contained in:
sam committed 2026-09-24 19:47:03 +10:00
commit ee0f6aecaa
265 files changed
+2273 -11384

No files matched your search

+1 -1
View File
@@ -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.** `<db_path>-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 `<db>.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. |
@@ -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/<capability>` | Implement a narrow owner-defined contract; translate at boundary. |
| NATS, PostgreSQL, forge, config decoding, external SDK adapters | `internal/infrastructure/<capability>` | 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/<assembly>` | 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. |
@@ -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
@@ -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 `<db_path>-tasks.sqlite` and conversations use `<db_path>-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 `<db_path>-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 |
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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.<task-id>.request`. |
| Full-task handoff | A whole workflow sent on core NATS subject `archie.taskrun.<task-id>` 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 `<db_path>-tasks.sqlite`; conversation state uses `<db_path>-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.<id>`. | **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 `<db_path>-tasks.sqlite`; default `~/.local/share/archie/archie.db-tasks.sqlite`. |
| Chat sessions and messages | SQLite database at `<db_path>-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 | `<work_dir>/<owner>-<repo>/issue-<number>`; default root `~/.local/share/archie/work`. |
| Identity worktree | `<work_dir>/identity-<identity>/<owner>-<repo>/issue-<number>`. |
| 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.
+4 -4
View File
@@ -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.
+3 -1
View File
@@ -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",
+6 -9
View File
@@ -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)
+3 -8
View File
@@ -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 (
+19 -13
View File
@@ -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
@@ -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)
}
})
@@ -611,7 +617,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)
}
}
+7 -9
View File
@@ -20,10 +20,9 @@ const recoveryUsage = `usage: archie-state-store <command> [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 (<db_path>-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")
+101 -425
View File
@@ -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
}
+4 -2
View File
@@ -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
@@ -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",
+10 -16
View File
@@ -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),
+10
View File
@@ -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)) }
+8 -8
View File
@@ -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
+1 -1
View File
@@ -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
+9 -9
View File
@@ -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 (`<db_path>-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.
+5 -3
View File
@@ -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
+5 -3
View File
@@ -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`.
+5 -3
View File
@@ -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
+5 -3
View File
@@ -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
+7 -8
View File
@@ -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`.
+5 -4
View File
@@ -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. |
+13 -12
View File
@@ -30,7 +30,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
@@ -101,8 +101,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.
@@ -117,7 +118,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.
@@ -126,14 +127,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
@@ -156,8 +157,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
@@ -169,8 +170,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
@@ -178,8 +179,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).
+1 -1
View File
@@ -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 (`<db_path>-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. |
+1 -1
View File
@@ -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
@@ -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.
+10 -7
View File
@@ -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.
+5 -7
View File
@@ -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
+30 -41
View File
@@ -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 `<db>.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`
+19 -19
View File
@@ -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\norLine truncated
"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\norLine truncated
},
{
"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; its event type is the binding's\n Filter // optional CEL over the mapping's parameters\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\nA binding applies to a capture when the capture arrived on `Matcher.Source`,\nwas identified as the event type its mapping belongs to, and passes its\n`Filter` (`binding.CompileFilter`, checked against the mapping's parameters on\nsave). Any number of bindings may share a source; each dispatches a capture at\nmost once, claimed in `binding_dispatches` keyed by (binding, capture) before\nits task is enqueued. An event signed with any armed binding's secret on the\nsource is authenticated.\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. A\nmapping belongs to an event type, and `mapping.CheckSchema` refuses a field\nwhose path or type the type's inferred schema lacks. Each capture a mapping\nresolves at dispatch is counted once in `mapping_matches`, read back as\n`MatchCount` and `LastMatchedAt`.\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 bindingLine truncated
"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; its event type is the binding's\n Filter // optional CEL over the mapping's parameters\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\nA binding applies to a capture when the capture arrived on `Matcher.Source`,\nwas identified as the event type its mapping belongs to, and passes its\n`Filter` (`binding.CompileFilter`, checked against the mapping's parameters on\nsave). Any number of bindings may share a source; each dispatches a capture at\nmost once, claimed in `binding_dispatches` keyed by (binding, capture) before\nits task is enqueued. An event signed with any armed binding's secret on the\nsource is authenticated.\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. A\nmapping belongs to an event type, and `mapping.CheckSchema` refuses a field\nwhose path or type the type's inferred schema lacks. Each capture a mapping\nresolves at dispatch is counted once in `mapping_matches`, read back as\n`MatchCount` and `LastMatchedAt`.\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 souLine truncated
},
{
"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 lifetiLine truncated
"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 lifetiLine truncated
},
{
"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 ideLine truncated
"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 ideLine truncated
},
{
"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,Line truncated
"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, deletionLine truncated
},
{
"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\nauthLine truncated
"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\nauthLine truncated
},
{
"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 pLine truncated
"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 pLine truncated
},
{
"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 uLine truncated
"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| --- | -Line truncated
},
{
"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- `storLine truncated
"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 concrLine truncated
},
{
"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 -- `MLine truncated
"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 -- `MLine truncated
},
{
"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 Line truncated
"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 Line truncated
},
{
"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,Line truncated
"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.ContexLine truncated
},
{
"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.gatewaLine truncated
"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- `[chaLine truncated
},
{
"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` tabLine truncated
"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-emptyLine truncated
},
{
"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, repLine truncated
"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 keyLine truncated
},
{
"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 Line truncated
"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 StoreLine truncated
},
{
"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 criterioLine truncated
"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 consuLine truncated
},
{
"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: eveLine truncated
"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` (`Line truncated
},
{
"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 Line truncated
"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 Line truncated
},
{
"url": "/dev/prds/vue-migration-checklist/",
+7 -2
View File
@@ -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.
+3 -3
View File
@@ -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.
+10 -5
View File
@@ -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
+2 -2
View File
@@ -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
+3 -3
View File
@@ -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)
+6 -1
View File
@@ -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
+2 -2
View File
@@ -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
+5 -5
View File
@@ -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;
+13 -4
View File
@@ -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
+8 -4
View File
@@ -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.
+8 -8
View File
@@ -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
+1 -17
View File
@@ -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
-51
View File
@@ -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=
+5 -5
View File
@@ -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 <<EOF > "${SYSTEMD_USER_DIR}/archie-state-store.service"
[Unit]
+10
View File
@@ -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)) }
@@ -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)
}
+3 -3
View File
@@ -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)
}
+7 -8
View File
@@ -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,
@@ -476,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
@@ -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
}
@@ -7,8 +7,8 @@ import (
"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"
"github.com/samcharles93/archie-core/internal/store"
)
func TestRemoteChatCompositionPreservesChannelTurnLedger(t *testing.T) {
@@ -17,10 +17,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)
@@ -3,11 +3,10 @@ package archied
import (
"encoding/json"
"log/slog"
"path/filepath"
"testing"
"github.com/samcharles93/archie-core/internal/config"
"github.com/samcharles93/archie-core/internal/store"
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore"
"github.com/samcharles93/archie-core/internal/webui"
)
@@ -49,10 +48,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{
+4 -14
View File
@@ -4,12 +4,11 @@ import (
"context"
"encoding/json"
"log/slog"
"path/filepath"
"testing"
"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/infrastructure/postgres/pgstore"
"github.com/samcharles93/archie-core/internal/webui"
)
@@ -19,10 +18,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 +79,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 +126,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}
@@ -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()
@@ -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 {
+2 -15
View File
@@ -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 {
+1 -1
View File
@@ -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))
+3 -8
View File
@@ -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"
@@ -139,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)
@@ -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"
}
@@ -613,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
@@ -808,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) {
+5 -18
View File
@@ -7,7 +7,6 @@ import (
"fmt"
"log/slog"
"os"
"path/filepath"
"slices"
"strings"
"sync"
@@ -28,9 +27,9 @@ 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/store"
"github.com/samcharles93/archie-core/internal/tools"
"github.com/samcharles93/archie-core/internal/worktree"
"github.com/samcharles93/archie-core/internal/worktreerpc"
@@ -528,10 +527,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 +551,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 +566,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 +817,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)
+1
View File
@@ -0,0 +1 @@
{"url":"nats://127.0.0.1:34001","token":"UTTAKZ3FQ3FSB7D6XARWKTYMUQ"}
@@ -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"}}
@@ -0,0 +1 @@
e5007a6989578acf
@@ -0,0 +1 @@
{"Created":"0001-01-01T00:00:00Z","Name":"","name":"2AiYsxvu","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"}}
@@ -0,0 +1 @@
1a41fdece74230be
@@ -0,0 +1 @@
{"Created":"0001-01-01T00:00:00Z","Name":"","name":"4ETGGNq6","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"}}
@@ -0,0 +1 @@
59023e4aa2a291e6
@@ -0,0 +1 @@
{"Created":"0001-01-01T00:00:00Z","Name":"","name":"8MNb4kc2","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"}}
@@ -0,0 +1 @@
461f1f0b33b1e704
@@ -0,0 +1 @@
{"Created":"2026-09-24T09:46:47.593915791Z","Name":"Bm6IdqYw","name":"Bm6IdqYw","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"}}
@@ -0,0 +1 @@
8b3c3f8234fa0b40
@@ -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"}}
@@ -0,0 +1 @@
fb9d97471241c535
@@ -0,0 +1 @@
{"Created":"2026-09-24T09:46:47.587065821Z","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"}}
@@ -0,0 +1 @@
{"Created":"2026-09-24T09:46:47.594292859Z","Name":"eq86DXAG","name":"eq86DXAG","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"}}
@@ -0,0 +1 @@
5ff54a1a5c91cc56
@@ -0,0 +1 @@
{"Created":"0001-01-01T00:00:00Z","Name":"","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,"inactive_threshold":5000000000,"num_replicas":0,"metadata":{"_nats.req.level":"0"}}
@@ -0,0 +1 @@
abaa43ff23e8df46
@@ -0,0 +1 @@
{"Created":"0001-01-01T00:00:00Z","Name":"","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,"inactive_threshold":5000000000,"num_replicas":0,"metadata":{"_nats.req.level":"0"}}
@@ -0,0 +1 @@
60d5c7722ea0e3a4
@@ -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"}}
@@ -0,0 +1 @@
52d9f8cea485537a
@@ -0,0 +1 @@
{"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"}}
@@ -0,0 +1 @@
218aa24a9029a5b8
Loaded 100 of 265 files, more files were not shown because too many files have changed in this diff. Show more