# docs/architecture

An observation of Maven as built, read at `5cae33a` on 2026-08-25. It describes
what the code does today. It proposes nothing.

This directory is a build output plus its sources. `index.html`,
`maven-architecture.json`, `anchors.md` and `diagrams/*.svg` are generated.

## Read it

| file | what it is |
|---|---|
| `index.html` | the viewer. Open it from the filesystem, no server needed. Five views, the rendered diagram above each, click a component for its record. |
| `findings.md` | the analysis. Kept apart from the facts on purpose. |
| `maven-architecture.json` | the inventory. 160 components, 204 relations. The factual source for everything else. |
| `anchors.md` | every symbol the inventory names, resolved to `path:line` with the line quoted. |
| `diagrams/*.mmd` | the five views as Mermaid source. `03a`, `03b` and `03c` are the three traced requests. |
| `diagrams/*.svg` | the same, rendered. |

## Rebuild it

```sh
python3 docs/architecture/build_inventory.py   # → maven-architecture.json
python3 docs/architecture/verify_anchors.py    # → anchors.md, exit 1 if stale
sh      docs/architecture/render.sh            # → diagrams/*.svg, then index.html
python3 docs/architecture/build_viewer.py      # → index.html alone
```

`render.sh` drives mermaid-cli through the system chromium rather than letting
puppeteer download its own. It is also the only syntax check this repo has for a
`.mmd`.

## What is verified, and what is not

**Verified mechanically.** `verify_anchors.py` resolves all 692 claimed symbols
against the files their component names. Current state: 681 resolved to a line
and 0 unresolved, with 0 missing files. The other 11 are config keys and make
targets rather than Go identifiers, so they are skipped. The script exits
non-zero on any failure, which makes it a staleness gate.

Writing it caught 29 symbols filed under the wrong component and seven names
that were wrong outright. Two examples: `Store.RecordEvent` for what is really
`Store.CreateEvent`, and `media.Keeper` for what is really `media.Store`.

**Not verified.** That a symbol means what its `responsibility` says. An anchor
proves the identifier is on that line and nothing more. Judgements about
ownership, coupling and enforcement are readings of the code. A reading can be
wrong in a way grep cannot catch.

**Marked, not resolved.** Relations carry a `confidence` field. `medium` means
the wiring is in the source and the call path was not traced end to end. `low`
means it was inferred from one reference. The viewer can hide both. Four
relations are `medium` and one is `low`.

**Deployment-specific.** Sixteen components are `configured-off` against
`deploy/mavend.json` as it stood on the day, and that file was dirty in the
working tree. A different config makes different components live. `status` says
which, per component.

## The one thing to check first

`findings.md` 6.3 through 6.3d. They say the system has no single point that
decides whether an origin may cause an effect, and that the pieces which look
like that point are each answering a different question.

Revised on 2026-08-25 after an independent second pass. Four readings changed
and one earlier statement was wrong. Section 6.3 marks the corrections.

Start at `internal/tool/tool.go:181`, `cmd/mavend/ecosystem_acts.go:158` and
`internal/router/claim.go:38`.

## The evidence pack

`sh docs/architecture/pack_evidence.sh` builds `maven-evidence.zip` at the repo
root: this directory, the structural context, and whole source files for the
architectural seams. Whole files, never snippets, because a cut-down file loses
the call path that makes a claim checkable.

The path list is an allowlist, not an exclusion list. A denylist ships whatever
nobody thought to exclude, and this tree has a database key in it.

`architecture-evidence.txt` is the reviewer's index. It resolves a named symbol
list against the checkout and says plainly when a requested name does not exist.
It also re-runs the probe under every contradiction, so a claim and its grep
cannot drift apart.

One file is not verbatim. `docker-compose.yml` carries an uptime-kuma API key,
so a redacted copy ships in its place with that one value replaced. The script
diffs the two and aborts if anything else changed.

The scan at the end refuses to build on a credential-shaped hit rather than
printing a warning. Both of its first two versions were wrong in instructive
ways. The name filter deleted `internal/router/singletoken.go` for matching
`*token*`. The value scan flagged docker volume lines that name where a secret
would live and contain none.

## The authorization function as implemented

The reconstruction, at the one decision point that gates an act
(`internal/tool/tool.go:156`):

```
permit(tool, confirmed) =
      row.status == "enabled"                          tool.go:164
  AND tier != irreversible                             risk.go:74  VoiceMayRun:false
  AND (tier == safe OR confirmed)                      risk.go:72,76
```

`tier` is `RiskOf(row)`. The reach is not an input: `Executor.Exec` takes
`(ctx, name, args, confirmed)` and no surface.

`confirmed` is unproven at this boundary too. The invariant that a confirmation
binds one capability, one target and an expiry lives in `pendingAct` and
`resolveConfirm`. `Exec` trusts the boolean.

The expression covers two of the three act paths. Hexis reuses it deliberately
(`cmd/mavend/ecosystem_acts.go:768`). The Praxis lifecycle path has no tier and
no confirm turn: `praxisItemAction.handle` calls straight through at
`ecosystem_acts.go:158`.

Behind the IPC boundary, `auth.Can(method, scope, params)` runs with
`scope.Surface` always `SurfaceCoreProcess` (`internal/auth/enrollment.go:65`)
and step-up held as one global timestamp that ignores `Scope`
(`internal/webauthn/session.go:38` and `:62`).

`auth` answers who may carry what authority. `tool` answers what effect a
capability has and what proof it demands. Those are orthogonal, not competing.
The decision combining them does not exist.

Two representations of reach exist and both are ignored. `server.go:198` only
defaults an empty `p.Surface`, so a client-asserted one survives and nothing
reads it. `server.go:148` hardcodes `Session.Surface`. Since `req.Surface` is
request payload on an unauthenticated wire, it must not become an authorization
input as it stands.