The design language below the screen: one doc per concern, what a module or app should do about it and why, with the instance that taught us. Law with reasoning attached; a module deviates with a stated reason and the deviation becomes an instance finding.
Start with 00-overview.md, the concerns matrix. Each numbered doc takes one
row or a cluster of rows.
| Doc | Covers | Status |
|---|---|---|
00-overview.md | the 38 concerns, how each instance answers them, where the contract stands | written 2026-08-17 |
01-runner-and-payload.md | the seam, stated as a rule, three witnesses, the runner's minimum verb set | written 2026-08-17 |
02-identity-and-tenancy.md | caller identity, credentials and revocation, tenant on every job, scopes vs roles | written 2026-08-17 |
03-jobs-and-state.md | the job lifecycle, states and transitions, who owns state (module / caller / mirrored), derived vs stored, results reporting, completion signalling | written 2026-08-17 |
04-dispatch-and-workers.md | queues behind a port, concurrency, retry budget, heartbeat, cancel, checkpoint/resume, idempotency, outbound rate limits | written 2026-08-17 |
05-storage-and-persistence.md | inputs, outcomes, artifacts, retention, the "no state table" condition | written 2026-08-17 |
06-caching.md | result caching keyed by input, cross-service cache, Redis on Render, TTLs | written 2026-08-17 |
07-observability.md | per-job and per-item logs a caller can read, tracing (Langfuse), stage summaries, cost attribution | written 2026-08-17 |
08-usage-and-credits.md | metering shape (idempotent ledger, dead-letter), cost per item, limits: module reports, app enforces | written 2026-08-17 |
09-config-and-secrets.md | one typed config, defaults for local, reference-injected secrets, never printed | written 2026-08-17 |
10-human-in-the-loop.md | "needs review" as an outcome, the queue belongs to the app, resolve/waive re-enters the runner | written 2026-08-17 |
11-capability-manifest.md | discovery, versioning (contract, module, schema), payload schemas | written 2026-08-17 |
12-deployment-and-environments.md | branch to environment mapping, per-env identity, provisioning as a script, build identity | written 2026-08-17 |
13-local-dev-and-debugging.md | in-process mode with zero env, the debug path as a contract concern, "works on my machine" | written 2026-08-17 |
14-graceful-degradation.md | multiple versions of one capability at once, swapping, degrading, feature flags | written 2026-08-17 |
15-outputs-and-transforms.md | outcomes are the record, outputs are a declared transform over it; M from N, partial reads, edits live in the app | written 2026-08-18 |
Evidence marker#
Each canon doc opens with an Evidence: line: the count of file:line witnesses in it (a mechanical count, rg over the doc), a confidence word (high at ten or more, partial at three to nine, derived below three), and what would change it. A derived doc is not weaker as a design; it is weaker as a claim about the estate, so a builder obeys a high doc and argues with a derived one. Re-count when a doc is edited. Added on the tree-wide review v2's J2 (2026-08-18).