* test(state-store): real-process smoke + deadline/sentinel error contract Add end-to-end verification for archie-core-8cda.4.7, the .4.7 State Store verification stage against docs/prds/state-store-contract.md (rev. 2c): - Real-process smoke coverage: build ./cmd/archie-state-store, run it against a minimal config on loopback, poll the readiness surface, and drive the State Store gRPC contract through staterpc.NewClient exactly as a consumer does. Covers the combined task/event/capture view, error-sentinel fidelity across the wire, the found=false-not-error convention, single-owner SQLite (the binary owns the one archie.db file; the consumer never opens a store file), per-call deadline behaviour, restart/recovery (SIGTERM + reopen on the same db), and the remote capture/mapping/binding surfaces. - Fix a real deadline-identity gap in unmapError: a cancelled or deadline-exceeded context surfaced by gRPC-Go as a *status.Error was re-wrapped into a sanitised internal-style error, breaking errors.Is(err, context.Canceled/DeadlineExceeded). The agent's deadlineStore bounds each Store call with context.WithTimeout and the workflow consumer (workflow.go) uses errors.Is(err, context.DeadlineExceeded) to mark a stage interrupted rather than failed, so the re-wrap would wrongly park an interrupted task. Unmap Canceled/DeadlineExceeded codes back to the standard context sentinels. - Pin the error-mapping contract in staterpc: context-identity preservation, sentinel round-trip fidelity for every store sentinel, and the sanitisation rule (an Internal error must not leak raw detail or map to a sentinel). * test(state-store): assert single-owner SQLite composition (daemon/gateway require target) The single-owner invariant (docs/prds/state-store-contract.md §12 step 7/8) is that only archie-state-store opens archie.db; the daemon and gateway resolve their task-store surface from openStateStoreAdapter, which requires [services.state].target and opens no local store. This test pins that composition root so a future change cannot silently reintroduce a local *store.Store in the daemon or gateway path (dual-store ownership). * test(state-store): skip real-process smoke tests under -short The smoke tests build and exec the real archie-state-store binary, which is slow enough that a -short run (e.g. a focused edit loop) should skip them. task check (go test ./... -count=1) does not use -short, so they still run in the full gate. * test(state-store): fix subprocess log race under -race The smoke test captured the subprocess's stdout/stderr in a strings.Builder that the os/exec writer goroutine and the test reader goroutine touched concurrently, racing under -race. Replace it with a mutex-guarded buffer, the standard pattern for reading a running subprocess's output. * test(state-store): satisfy lint (noctx, errorlint) on new tests - exec.Command -> exec.CommandContext, http.Get -> NewRequestWithContext + Client.Do, so the subprocess and readiness polling honour the test context (noctx). - errorlint: compare the raw non-status error via errors.Is rather than != on a wrapped error. * docs(deployments): document State Store readiness verification and single-owner invariant The deployment runbook described how to launch archie-state-store but not how to verify it is healthy before starting archied. Document the -ready-addr readiness surface (/healthz, /health/detailed state_db component) and the single-owner invariant: one task SQLite file owned by archie-state-store, with archied/archie-gateway never opening archie.db directly (state-store-contract §12 step 7/8). * fix(state-store): preserve context deadline/cancel identity in mapError The symmetric server-side gap to the unmapError fix: if a store query fails because the caller's context expires mid-call (§6 StoreTimeout), the handler's mapError folded context.Canceled/DeadlineExceeded into codes.Internal. The client would receive a sanitised internal error with no deadline identity, so the agent's workflow consumer (errors.Is(err, context.DeadlineExceeded)) could not distinguish an interrupted stage from a failed one. Map a context cancel/deadline error to its matching gRPC code so unmapError rehydrates it back to the standard context sentinel, completing the §6/§7 round-trip. Pin both directions with TestMapErrorPreservesContextIdentity.
Archie Core Deployment Examples
This directory contains configuration templates and guides for different deployment scenarios of Archie Core.
Directory Structure
-
single-forge-github.toml: Standard single-forge deployment managing multiple GitHub repositories under a single bot account and GitHub token. -
multi-forge-github-gitea.toml: Multi-identity deployment running GitHub and a self-hosted Gitea instance simultaneously with distinct bot accounts, tokens, and repository sets. -
local-ollama-standalone.toml: Self-hosted deployment running local LLM models via Ollama (e.g.,llama3,qwen2.5) with optional standalone (forge-disabled) operation. -
docker-nats-stack.toml: Host-runarchiedorchestrating sandboxedarchie-agentcontainers over the repository's Compose-managed NATS service. Copy to~/.config/archie/config.toml, start NATS with Compose, then startarchiedon the host. -
systemd-user-service.md: Operational runbook for runningarchiedas a persistent 24/7 background service via systemd user units andloginctl enable-linger.
Usage
Copy any scenario template to your XDG configuration directory (${XDG_CONFIG_HOME:-~/.config}/archie/config.toml):
mkdir -p ~/.config/archie
cp deployments/single-forge-github.toml ~/.config/archie/config.toml
Edit API keys in ~/.config/archie/env or directly in config.toml, then launch Archie Core:
archie-gateway -config ~/.config/archie/config.toml -listen 127.0.0.1:8585 &
archie-state-store -config ~/.config/archie/config.toml -listen 127.0.0.1:9090 &
archied -config ~/.config/archie/config.toml
# or via systemd:
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
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
(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
Docker bridge gateway address plus a matching bearer token (target_token /
--token / STATE_STORE_TOKEN), because a container cannot reach the host's
loopback.
# loopback (host-only agent)
archie-state-store -config ~/.config/archie/config.toml -listen 127.0.0.1:9090
# or container-mode: bind the bridge gateway with a token
archie-state-store -config ~/.config/archie/config.toml -listen 172.17.0.1:9090 -token <token>
Verifying the State Store
archie-state-store exposes an optional HTTP readiness surface when launched
with -ready-addr (the systemd unit uses 127.0.0.1:9091). Use it to confirm
the process is up and the store is healthy before starting archied:
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9091/healthz # 200 = process up
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).
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.