Commit Graph
71 Commits
Author SHA1 Message Date
sam 13546c23f3 fix(tools): stop silently truncating tracker titles in reachaudit output
The whole-package section hard-truncated tracker hit text to 56 chars
with no ellipsis, so long issue titles cut off mid-word (e.g. "...neither
re"). Switch to the same indented-list format already used for the
in-package section instead of a fixed-width single line.
2026-09-19 17:55:22 +10:00
sam 5eaf1d0887 feat(tools): surface half-wired symbols inside shipped packages in reachaudit
reachaudit classified whole unreachable packages but explicitly skipped
findings inside packages already in the cmd closure ("reported separately
as live-package findings" -- never implemented). That's the more common
half-built-feature shape: the package ships, one symbol at its call site
doesn't (crondelivery.ChatCourier, eda/playbook.Store.Dispatch,
gatewayrpc.StoreClient). Add a second in-package-* report section using
the same tracked/untracked/dynamic classification. Also wires the --md
flag, which was accepted but never written.
2026-09-19 17:37:20 +10:00
sam cd9399f705 chore(deps): refresh go modules and tidy the tools module
Direct bumps:
- github.com/nats-io/nats-server/v2    v2.14.6 -> v2.15.0
- github.com/nats-io/nats.go           v1.53.1 -> v1.54.0
- github.com/samcharles93/ai-sdk       v0.1.32 -> v0.1.39
- google.golang.org/grpc               v1.83.2 -> v1.84.0
- modernc.org/sqlite                   v1.58.0 -> v1.59.0
- golang.org/x/net                     v0.58.0 -> v0.59.0
- golang.org/x/term                    v0.45.0 -> v0.46.0

Indirect: go-humanize, x/crypto, x/exp, x/sync, x/sys, x/text, x/time,
genproto/googleapis{,/api,/rpc}, modernc.org/libc.

tools/ is a separate module and needs its own tidy to match the root's
ai-sdk and sqlite bumps. docs:check runs it with -mod=readonly, so a
stale tools/go.mod fails loudly there rather than being rewritten.
2026-09-19 10:56:22 +10:00
sam ea7a054a45 docs(docsgen): drop a duplicated line in the obsoleteArtifacts comment 2026-09-19 03:07:38 +10:00
sam 7bf9d120f9 chore(tools): make unreachable-code analysis runnable from the Taskfile
Add `task deadcode` (whole-program RTA from ./cmd/...) and `task reachaudit`
(the existing classifier on top of it). Neither joins `task check`: both
report a standing backlog, so gating on them fails every run until that
backlog is zero, same as `task vuln`.

`task deadcode` shells to `go run ...@latest` rather than a local binary on
purpose. A deadcode built against an older Go than this module exits non-zero
and prints nothing, which reads as "no dead code" instead of "analysis
failed" -- the locally installed copy was built against 1.26 against a 1.27
module and had been silently reporting an empty tree.

reachaudit had two traps that made it answer confidently from nothing:
its --repo default pointed at a path that does not exist on either machine,
and it reused /tmp/reachaudit-deadcode.txt with no staleness check, so it
would serve a previous tree's analysis indefinitely. Key the cache on HEAD
and refuse it outright when the tree is dirty.

Also lands the design for tools/symbolrefs, the type-resolved reference
index that covers what reachability cannot: RTA treats every address-taken
function as live, so every reflect.ValueOf entry in the *extract tables
launders a dead symbol into a reachable-looking one, and deadcode reports
functions only, leaving dead package vars unrepresentable.
2026-09-18 13:15:26 +10:00
sam 5efa8645e7 fix(docsgen): address three review findings on the check mode
All three Greptile findings were valid against the code; each is fixed at its
cause rather than at the symptom, and each fix is covered by a test that
fails when the fix is reverted.

**Check could silently write.** `check` was matched only as the first
argument, and leftover positional arguments were never inspected. So
`docsgen --repo-root .. check` — and any misspelled subcommand — fell
through to the write path and overwrote the artifact the check promises not
to touch. That is the exact guarantee the mode exists to provide, so the
failure was silent and in the wrong direction.

Extracted argument handling into a testable `parseOptions` and made a leftover
positional argument an error with usage text. Switched the flag set from
`ExitOnError` to `ContinueOnError` so the error surfaces as a value rather
than a process exit, which is what makes it testable.

**Obsolete detection claimed files it does not own.** It treated every
sibling `.json` as docsgen's and reported it obsolete, so checking an
artifact in a mixed-use directory produced a false stale result, and the
documented target layout — which anticipates further named artifacts in
`docs/data/generated/` (catalog.json, AsyncAPI output) — would have been
reported stale as soon as a second artifact legitimately existed.

Ownership is now declared rather than inferred: `generatedArtifacts` maps each
directory docsgen owns end-to-end to the names it produces there, and a
directory docsgen does not own is never judged. A new unit test pins both
halves — the orphan inside an owned directory is still caught, and a foreign
`.json` in an arbitrary `--out` directory is not.

**Provenance traversal stopped at one level.** Refs were walked only inside
the top-level contract schemas, so a definition reachable solely through
another definition resolved to "no authoritative definition found" — the
diagnostic lying about the code it points at. Replaced the single pass with a
breadth-first walk that follows discovered definitions transitively, seeded
with every published contract first so a definition reachable from several
contracts is attributed to the alphabetically first rather than to whichever
the walk happened to reach. `walkSchemaRefs` now iterates map keys in sorted
order for the same reason.

`schemaProvenance` takes its roots as a parameter, which is what makes the
transitive case testable without real types.

Verified by mutation: with each fix reverted in turn, its test fails —
`parseOptions(["--repo-root" ".." "check"]) returned nil error`,
`obsoleteArtifacts() = [...someone-elses.json is obsolete...]`, and
`provenance[Leaf] = ""`. Control run passes unmutated, and the file is
byte-identical after restoration.

Also confirmed end to end that the previously silent invocation now exits
non-zero with usage instead of writing, and that the committed artifact is
untouched by it.

`task check`: exit 0, 0 failures.
2026-09-18 13:00:30 +10:00
sam 1f975f37ad feat(docsgen): add a non-destructive check mode for generated drift
`docs/data/generated/contracts.json` sat stale since 4b340d2b with nothing
to notice: no task, no test, and no CI step regenerates or compares it, so
the committed contract reference quietly drifted from the Go types it
claims to describe. It was only found by hand-running the generator.

Implements Step 6 of docs/architecture/generated-documentation.md, which
already specified this command and closed the gap filed in
docs/prds/contract-conformance-audit.md ("`docsgen check` is documented and
does not exist"):

1. generates into a temporary directory;
2. normalizes line endings;
3. compares the schema trees with the committed output;
4. reports missing, changed, and obsolete files;
5. names the authoritative definition behind each mismatch;
6. exits non-zero without modifying the working tree.

The check never writes to the working tree, so the author applies the
regenerated bytes rather than the gate silently doing it. That is why this
is a `check` and not a CI auto-update: the code change that shifted the
contract surface should be reviewed with its regenerated artifact in one
commit, and a bot commit would bless an unintended contract change with no
reviewer ever seeing it. Step 9 states the same prohibition directly.

Diagnostics name the Go type, so a failure says where to look:

    docs/data/generated/contracts.json is stale; regenerate it with:
    go -C tools run ./docsgen --repo-root ..
      schema "AgentExecutionResult" changed (authoritative definition:
        github.com/samcharles93/archie-core/internal/agentexec.Result)
      schema "MediaAttachment" changed (authoritative definition:
        reached from .../internal/gateway.MessageEvent)

Nested definitions are attributed through the published contract that
references them, iterated in sorted order so the diagnostic is
deterministic when several contracts share a definition.

Usage: `go -C tools run ./docsgen check --repo-root ..`, plus the existing
`--out` to compare an arbitrary artifact.

Reuses the write path rather than reimplementing encoding, so check and
generate cannot disagree about the expected bytes.

Tests cover: the committed artifact is current (the regression guard that
would have caught this), changed/removed/missing/obsolete detection, and
that a failing check leaves the artifact's bytes, mode, and directory
contents untouched.

`task docs:check` wiring into `task check` is deliberately not in this
commit: Taskfile.yml is being edited concurrently in this working tree.

Verified with `task check` (green).
2026-09-18 12:46:21 +10:00
sam 8c4a10d6d0 chore(fmt): adopt gofumpt wrapping in contractaudit
task fmt reformatted this file's fmt.Fprintf call; committing it rather than
letting it ride in the release commit, so the release diff stays the changelogs
alone. AGENTS.md: formatter changes are adopted verbatim.
2026-09-17 07:10:03 +00:00
sam c15d14557c fix(tools): stop testing on the text of other files, and ungate contractaudit
Six tests asserted on the wording and formatting of source and config files
rather than on behaviour: four injected text into fixtures and checked that a
regex noticed, and two asserted on api.jsx's contents. They break on an extra
space, a newline, a rename, or a comment that merely mentions the token -- the
single-fetch check had already false-positived on a comment, and I patched it
with a comment-stripper instead of deleting it. A test that cannot tell "the
code is wrong" from "the file is formatted differently" tests the wrong thing,
and the maintenance cost is permanent.

Deleted: tools/contractaudit/negative_test.go in full, and the source-scanning
"api.jsx holds exactly one fetch call" check with its stripComments helper. The
dashboard suite still asserts the browser mutation contract behaviourally, per
method, by inspecting the request each one makes -- which is where the real
defect was found. 142 UI tests pass; the 45 methods remain fully covered by the
two inventories and the completeness check.

The tool's own decoding is now testable without a file: parseDeclarations takes
an io.Reader, so its rules are exercised with in-memory input, and only the
absent-file branch still touches a path (which is never created).

contractaudit is no longer part of task check. Its surfaces are discovered by
scanning source text, so a rename or reformat elsewhere can change its output
with nothing actually wrong -- it reported 16 live routes as unconsumed once,
when the dashboard's request helper was renamed. A check that can fail for
reasons unrelated to what it measures must not be able to break a build. It now
matches tools/reachaudit: advisory, run by hand, --strict available on request.

Also removes five unused indirect requires from tools/go.mod (go mod tidy).
They were residue from the reflection-based first implementation of the RPC
scan, which was replaced by text scanning without tidying. -mod=readonly cannot
catch a superfluous require, so nothing would ever have found them.

Rewrites docs/prds/contract-conformance-audit.md, which claimed RPC coverage was
derived by reflection over the exported client type -- it never was -- listed
surface sizes of 43/12/52 against real counts of 45/21/49, described three
classification classes where the code has four, invented a five-surface Shape
with files that were never written, and blamed raw fetch calls for a 401 defect
that did not exist. Each false claim is now recorded in an errata section rather
than quietly dropped, and the document states plainly that the audit has found
nothing actionable: the 415 refusals and the duplicated client plumbing were
both found by reading the handler and reproducing the request.

Testing rule added to the document, since this is the second time: assert on the
observable effect, never on the content or formatting of generated or
hand-authored text and config files.
2026-09-15 14:17:53 +10:00
sam 22cb0c6de5 fix(tools): stop contractaudit crediting dead paths as live consumers
Renaming the dashboard's request helper from req( to request( broke the
consumer extractor: it matched the call by name, so 16 live routes were
reported unconsumed. The extractor now keys on the call argument instead,
which survives a rename.

The first attempt at that fix was worse than the bug, and is recorded here
because the direction of the error is the whole point. Crediting any quoted
/api/... literal meant a comment, a retired-route array, or a display label
counted as proof a route was reachable -- so deleting every real request
still reported the surface as healthy. A false "unconsumed" is a loud,
fixable failure; a false "consumed" is a silent hole in the gate, which is
worse than having no gate at all.

A path now counts as a consumer only when it is the first argument of a call
in code. That excludes bare constants, dead arrays, object properties, and
commented-out calls, while still accepting any function name. Both halves are
pinned by tests: TestScanFileCreditsAnyCallSignature and
TestScanFileIgnoresNonCallLiterals, plus a surface-level
TestNegativeCommentedOutCallIsStillReported that the vacuous version fails.
Re-injecting either half of the bug fails the suite.

Requiring a call lost no real consumer: internal/webui still reads 49/49.
The remaining limits (path must be the first argument; template
interpolations unseen; routes credited per path rather than per verb) are
declared in docs/contract-declarations.json and the PRD rather than left
implicit.

Also corrects a measurement I had quoted inconsistently: proto/state/v1
declares 45 RPCs, not 43 or 46.
2026-09-15 13:49:47 +10:00
sam e537447333 feat(tools): add contractaudit for standing contract-conformance reporting
Reachability (tools/reachaudit, epic archie-core-06ag) answers "is this code
in a shipped binary?". It cannot answer the complementary question: "does
every declared contract surface have a consumer, or a declaration that it
has none?". ratelimit was in the binary closure and called by nothing, which
reachability could not see.

tools/contractaudit classifies each subject of each declared surface as
CONSUMED, DECLARED-UNCONSUMED, UNDECLARED-UNCONSUMED, or STALE-DECLARATION,
and only the last two are findings. The declaration allowlist must match
reality exactly: a missing entry fails and so does an entry that outlived
its subject, because a stale allowlist is how a gate quietly stops checking
anything.

Surfaces: the two gRPC services, whose consumption is derived by scanning
adapter bodies for calls through the generated client, and the dashboard
HTTP API, matched between the registerXRoutes call sites and the path
literals the bundled client calls.

Findings on the current tree, all deliberate and now declared:
ListCaptures and ListUndispatchedCaptures are superseded by their streaming
variants -- staterpc's client calls StreamCaptures -- so no production
client reaches the unary RPCs.

Three bugs this tool found in itself, each recorded because each is the
class of error that makes a conformance check worse than none:

- Joining RPCs to adapter methods by name silently reported live RPCs as
  unconsumed, because adapters do not map one-to-one: StoreClient.Get calls
  GetSession, List calls ListSessions.
- Reflecting over the client value rather than the pointer reported zero
  methods, hence the whole surface unconsumed.
- Treating the asset mount and the health probes as dashboard API routes
  reported four healthy routes as undeclared; they have different consumers
  and are out of scope for this surface.

The consumer extractor fails loudly on a call shape it cannot parse rather
than under-reporting, and every check is negative-tested: a route, an RPC,
and a removed consumer are each injected, confirmed to fail for the right
reason, and reverted. The declaration staleness rule is tested too.

Advisory when run directly; task check runs it -strict. See
docs/prds/contract-conformance-audit.md.
2026-09-15 09:41:20 +10:00
sam 66171f16ec fix(tools): tidy the tools module against the root module
tools/go.mod replaces the root module, so its build list must satisfy the
root module's requirements. The root had moved on, leaving the tools module
unbuildable under -mod=readonly and silently self-repairing otherwise.

go 1.26.5 -> 1.27.0, ai-sdk v0.1.25 -> v0.1.32, modernc.org/libc
v1.74.4 -> v1.75.7, memory v1.11.0 -> v1.12.1, sqlite v1.56.0 -> v1.58.0.
2026-09-13 15:00:28 +10:00
sam 02b47e3cee chore(tools): add reachaudit reachability report tool
Reports completion state rather than intent: walks the tree, finds
code no shipped binary can reach, and attributes each finding to its
package with provenance and tracker status, so "is it implemented?"
and "is it reachable?" are separately answerable.

Advisory only; it never proposes deletion.

Also ignore .local/ (gh CLI state created inside the tree).
2026-09-13 14:48:17 +10:00
sam dd2d3db1b2 docs(deploy): UI Service deployment, auth, and operations profiles
Bead archie-core-8cda.5.5:

- task dev now runs archie-ui (dev:dashboard) on :8484 -- after the
  cutover archied binds no dashboard listener, and Vite's /api,/events
  proxy needs a live receiver there. dev:mobile starts archie-ui with a
  LAN bind and -token-file (reusing the pre-cutover token path) instead
  of a mobile archied overlay; dev:ui's summary points at archie-ui.
- deployments/dev.toml documents itself as the archie-ui overlay and
  states the [services.gateway] target explicitly.
- systemd-user-service.md: the auth gap is now the documented posture --
  archie-ui has no secret registry, resolves GATEWAY_TOKEN/
  STATE_STORE_TOKEN from its process environment only, so the starter
  (EnvironmentFile) exports them; worked env-file example added, plus
  /healthz as the token-free liveness probe.
- INSTRUCTIONS.md ships five binaries with archie-ui in the quickstart
  and the token story; README.md carries the auth note; the
  docker-nats-stack profile notes archie-ui binds [web] and dials the
  same [services.*] targets.
- release tooling: archied's component closure extends with
  cmd/archie-ui and internal/app/archieui, so a UI-process-only commit
  can no longer fall between the two changelogs; RELEASING.md documents
  that the UI Service ships inside the archied release.
2026-09-10 01:14:14 +10:00
sam 3d7666002c feat(contracts): add gateway service seams and protobuf toolchain 2026-09-05 22:57:45 +10:00
sam 4b340d2b56 fix: harden task and chat execution
Task runs now preserve real model context limits, provider usage, baseline-repair spend, commit identity, durable agent-finish telemetry, and useful timeline details without imposing a token cap. Dashboard forge links are canonical per owning GitHub or Gitea identity. Chat turn claims acquire SQLite writer intent before reading, eliminating the concurrent SQLITE_BUSY snapshot race.
2026-08-25 05:48:17 +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 c91f373879 chore: add task release for changelog generation and tagging
The changelogs said 1.1.0 while 116 commits sat untagged on main, and
the deploy workflow stamps images 'dev' when no tag points at HEAD.

Two steps, so generated notes can be edited before a tag freezes them:
release:prepare writes them, release commits and tags. Which commits
land in which changelog is decided by each binary's package closure
(go list -deps), so a change to a package archied does not import
cannot show up in archied's changelog.
2026-07-31 01:33:08 +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
sam d1bbd37d95 chore: cleanup 2026-07-29 02:10:44 +10:00
sam 65aa5b462d chore: cleanup 2026-07-28 18:46:50 +10:00