Commit Graph
14 Commits
Author SHA1 Message Date
sam 07e39144e2 docs(architecture): record the NATS scaffolds as deliberate deferrals
servicediscovery/nats and gatewayrpc.StoreClient are implemented and fully
tested, but neither has a production caller and no config surface exposes
either. Both were previously unrecorded, which made them indistinguishable
from oversight. The register now names them: StoreClient under the session
migration that will consume it, service discovery under shared mechanics,
alongside the runtime boundary that pins container addressing by injected NATS
URL instead. Kept rather than deleted because re-deriving tested wire code
later is pure cost.
2026-09-15 16:54:12 +10:00
sam de150f2068 chore(docs): remove the VitePress site and its build step
The docs site was never published: GitHub Pages is not configured for this
repository, so the workflow built and uploaded a site nobody served. docs/ is
repository documentation — Markdown read in the repository, an editor, or the
forge's file view — and does not need a renderer.

Removed:

- docs/.vitepress/config.mts, docs/package.json, docs/pnpm-lock.yaml (1620
  lines), docs/pnpm-workspace.yaml
- docs/index.md (the site's landing page)
- .github/workflows/docs.yml (pnpm install, VitePress build, Pages deploy)
- the docs build-artefact ignores from .gitignore

Kept and corrected:

- docs/prds/01-project-management.md linked its decision documents with
  VitePress root-absolute paths (/architecture/...), which only resolve under a
  site build. Repointed to repository-relative paths.
- docs/architecture/generated-documentation.md named VitePress as the renderer
  throughout. Now records the renderer and publishing surface as an open
  decision, with the consequences stated: reference pages unrendered, no link
  checker, no authoring server. Also corrected three claims that were never
  true — the docsgen all/check subcommands and the docs:* tasks do not exist,
  and no pre-commit hook is installed.
- .agents skills: build-and-env and docs-and-writing no longer describe a docs
  site to build; the diagnostics scripts drop .vitepress skip rules and the
  dead github_docs_build scan.

Generated output is unchanged: docs/data/generated/contracts.json and the
docsgen toolchain are untouched, and tools/ remains its own module.
2026-09-12 01:01:12 +10:00
sam 03afd2e8ad refactor(webui): take configuration off the dashboard server
webui.Server declared Cfg *config.Holder with eight read sites, none of
which ran in the UI process: composition leaves it nil there. The field
survived because the daemon kept a webui.Server it never served, using it
to render the published ConfigView snapshot and to hold the readiness
probes (archie-core-ml30).

Split at the producer. LocalConfigView becomes webui.BuildConfigView, a
pure function over a ConfigViewInput the configuration owner assembles;
the DTO and its schema stay where the UI renders them. The daemon builds
that input from its own state (boot.configViewInput) and publishes the
result. Readiness reads the daemon's Holder, channel manager and chat
contract, and the registry it produces is a daemon field, not a field on
a server with no listener. Boot now owns one Holder instead of seeding a
second and replacing it in buildDaemon; operator retry caps read it too,
so they follow a reload rather than a boot-time snapshot.

Server loses Cfg, ConfigProvenance, LastReload, ConfigOverrides and
SetProvenance. The nil-guarded branches they fed went with them, each
checked first against what the UI process actually serves:

- chat.show_tool_calls and the /api/setup checklist were degraded, not
  dead. ConfigView gains a chat section carrying show_tool_calls, the
  operator name and whether a channel is configured, and both surfaces
  read the projection. The end-to-end suite asserts the checklist renders
  from the published snapshot.
- /api/logs takes its path as a process-local option. The history is on
  the daemon's disk, so a dashboard elsewhere cannot read it by learning
  the path; that route still needs a contract.
- handleChannels drops its config-derived fallback, superseded by the
  status manager, which already carries the descriptions and detail.
- trustForwardedHeaders keeps only the process's own setting, which the
  UI process already sets.
- resolveForge keeps the published-projection path it already had.

ConfigView.Editable moves to handleConfig, decided by whether this
process holds UpdateConfig. It describes the writer, not the document, so
the write contract (archie-core-j28m) makes the page editable by wiring
one field. The write handlers and their seams stay for it.

overlay.Store gains Keys: Snapshot nests dotted keys for decoding, so the
overridden-key list was publishing section names ("budgets") where the
dashboard marks and resets rows by stored key ("budgets.max_steps").

Multi-identity forge links move to archie-core-pv6t: forgeConfigForTask
resolved a task's forge from config.Config, had no reachable caller once
the holder was gone, and belongs in the projection rather than the
rendering package.
2026-09-11 23:57:38 +10:00
sam d6fc2b3f1e docs(architecture): make the dashboard configuration page read-only for Phase 3
archie-core-ymut. The ratified boundary assumed one narrow admin contract
carrying both the configuration read and the write. It splits.

Read: webui.ConfigView is already a UI-owned, secret-free value projection
(ProviderView carries the API key's env var name and a Configured bool, never
a value; RepoView is metadata only) and is already the exact shape the browser
receives. The daemon publishes it, plus provenance, reload status and the
overridden-key list, as a snapshot the UI reads over two new State Store RPCs.
Nothing is designed, only moved.

Rejected a config admin service on archied. That would make the daemon a gRPC
server for the first time: grpc.NewServer appears only in RunGateway and
RunStateStore, which are the standalone binaries' entry points, not the
daemon's, so it costs a new listener, port, token and interceptor.

Write: PATCH /api/config, POST /api/config/reset and the repo-field route
answer 503 in the UI process, and the SPA hides the controls. This is a
deliberate feature reduction. The update policy is daemon-local
(installUpdateConfigHandler denies non-runtime-tunable keys, applies a dotted
overlay to a clone, validates the materialised config, writes overlay rows and
rebuilds provenance); contracting it verbatim would build a Configuration
Service inside a migration bead. Revisit with archie-core-1786637498420-327,
where it is a feature rather than migration residue.

Implementation is assigned to archie-core-8cda.5.4, the cutover that removes
the daemon's dashboard. Nothing is built here.
2026-09-09 03:00:56 +10:00
sam eafb58e1c0 feat(webui): deliver live dashboard events by polling the State Store cursor
archie-core-za9f. The UI process owns no event bus, so after the .5.4 cutover
the activity feed would show history at page load and then go silent: live
delivery is a Server.Broadcast call made only from the daemon's bus
subscription.

Decided against the push-subscription RPC the bead assumed, on three findings:

* store.Open sets SetMaxOpenConns(1), so writes serialise and the event id is
  assigned in commit order. The gap-skipping failure that normally rules out
  polling an autoincrement cursor cannot happen here, and SSE catch-up already
  depends on the same property.
* sseStream.drain treats a broadcast as a wakeup, not a payload: it fills the
  persisted gap via catchUp and delivers the event only if catch-up missed it,
  deduplicating on the since watermark. A poller substitutes for the bus with
  no change to sse.go and no new SSE semantics.
* The events table is the only complete fan-out point. ArchiveTask writes an
  audit event inside its transaction and daemon.go inserts binding-dispatch
  failures directly, neither touching the bus. A push hub needs a hook at every
  write site and misses any added later.

So: no proto change, no new auth surface, no backpressure policy. The pump
primes past existing history (a client's own catch-up serves that), then ticks
EventsSince into Broadcast. One pump serves every browser. A failed fetch
leaves the watermark intact, so a State Store restart costs latency, not
events.

Wired into archieui.Run in the background so priming a large events table
cannot delay the listener, with -event-poll-interval (default 1s).

Decision recorded in migration-decisions.md; ui-service-boundary.md's /events
route-owner row moves to RESOLVED, and /api/logs splits out of it as still
unresolved and host-local.
2026-09-09 02:53:32 +10:00
sam 63a54e0850 docs(architecture): ratify UI service boundary 2026-09-07 18:29:42 +10:00
sam 7b39f7bd0c feat(memory): builtin engine implementing the domain/memory contract
Part of archie-core-1786637499480 (ship the file-writing store as the
default memory engine).

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

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

internal/memory/builtin is untouched -- confirmed via git status and its
own test suite passing unmodified, per this issue's acceptance
criterion. This engine is not yet wired into daemon bootstrap or the
config surface (archie-core-1786637490043); it proves the contract
holds for the builtin store the same way curator's reference
implementations prove the curator contract, and registers/runs cleanly
through domain/memory.Registry (TestBuiltinEngineRegistersAndRuns
ThroughTheRegistry).
2026-09-02 02:36:10 +10:00
sam 932a8b0680 docs(architecture): reconcile domain package map, add domain/messaging types
- migration-decisions.md: confirm curator/mapping/scheduling as
  legitimate domains that were never added to the confirmed list;
  document identity/agent/messaging/plugin as approved-but-unmaterialised
  targets rather than creating dead stub packages.
- Resolve the open Session/Messaging decision (section 2): keep
  internal/gateway as-is rather than risk a big-bang rewrite of live
  session/compression/approval/branch logic; materialise
  internal/domain/messaging with the already-settled canonical
  Message/Conversation/ToolCall/ToolResult types. Actual gateway
  migration onto these types is tracked as sequenced follow-up bd
  issues (label messaging-migration).
- ARCHITECTURE.md: add internal/gateway, internal/tools, internal/memory,
  internal/secret, internal/plugin, internal/skill to the Package Map.
2026-08-31 21:26:06 +10:00
sam 5ce821b561 chore: update issue tracker, remove ai-sdk ADR 2026-08-28 22:28:49 +10:00
sam 3b8ac3e8d1 docs: record ai-sdk to goai migration decision 2026-08-28 22:28:26 +10:00
sam 5d00ec7b0c refactor(agentexec): remove legacy execution paths
Autonomous workflows now have exactly one production boundary: a task-scoped archie-agent receives a full-task core-NATS request and runs the worker-local stage loop. The legacy [agent] section remains decode-only for migration; it no longer selects runtime behavior.
2026-08-24 14:56:57 +10:00
sam 61b4b7b0cf refactor(store): replace legacy persistence with SQLite
Task and event persistence now uses a dedicated SQLite sidecar derived from the configured state prefix, matching the independently persisted conversation store. The configured path now means a state-path prefix rather than a database file so fresh SQLite state never attempts to interpret the previous storage format.

Remove the retired implementation and dependency completely, strengthen SQLite migrations and concurrency behavior, restore backend-neutral coverage, and align configuration, operational guidance, UI labels, and deployment documentation with the new storage and host-daemon topology.
2026-08-09 22:27:25 +10:00
sam fd4420a038 docs(architecture): record decisions recovered from the pre-migration tracker
Eight approved decisions existed only as beads memories and were lost when
the tracker was removed. Recovered from a backup taken six minutes before
8bf0f6b and folded into the docs that own them, rather than a new document.

- migration-decisions: recorded position as of 2026-07-29, the deferred
  private-input-DTO compromise, and the agreed internal/app/{archied,
  agentworker} next step
- configuration: missing credential degrades a capability, only invalid
  config is fatal; config generation moves from install.sh to archied setup
- identity: the three-layer invariants/SOUL/representation model, and why
  a curator may only propose SOUL changes
- agent-system: the curator isolation invariant (curators are peers, never
  on a chat turn's critical path)
- messaging-and-work-intake: semantic search over messages is an explicit
  non-goal, with the measurements behind it
- safe-change-and-recovery: the /restart deadlock and lockout constraints
- plugins-and-extensions: dates the surprisal deferral

Also replaces the dead `**Beads issue:** archie-core-5d7` frontmatter across
all 12 documents with the GitHub issue it migrated to (#73), and rewrites
every other beads identifier to its issue number.
2026-08-09 18:10:12 +10:00
sam 69640b5216 docs: consolidate into a single docs/ tree
Fold the old docs/ into the VitePress site and rename docs-2 -> docs.
The 12 architecture PRDs become first-class pages at docs/architecture/
with sidebar nav, rather than being buried under an archive path.
Historical material stays at docs/archive/. Rewrites every docs-2 and
docs/prds/architecture reference across the repo. Site builds clean.
2026-07-29 03:17:42 +10:00