Real, running services broken down against the canon. This is the reality check: every canon rule cites at least one of these, and when a rule and an instance disagree, the disagreement is written down here as a finding rather than smoothed over.
Same idea as versable-builder/docs/breakdowns/: one doc per instance, same
headings every time, so two instances can be read side by side.
The template#
Every instance doc has these sections, in this order:
- What it is: one paragraph, stack, where it runs, who calls it.
- Shape of the runner: one paragraph and a diagram.
- Concern by concern: the matrix rows from
../canon/00-overview.mdas a table, mechanism plusfile:line, and whether it is vendor-specific. - Runner vs payload: which files are which, and whether the seam is clean, with the leaks named.
- Deliberate decisions: what it chose on purpose and what that buys.
- Lapses: where it falls short of canon, honestly. A lapse is not a bug report; it is input to the canon.
- Unproven: what was inferred rather than read.
Instances#
| Instance | Stack | Doc | Raw evidence |
|---|---|---|---|
versable-runner (services-api, runner-service, runner-service-dev) | Python, Cloud Run, Cloud Tasks, GCS | versable-runner.md | ../evidence/20260817-runner-architecture.md, 20260817-runner-blueprint-approach.md, 20260817-runner-four-file-diff.md, 20260818-services-api-git-source.md; source at /Users/alcatraz627/Code/Versable/services-api pinned at f46d894, with /Users/alcatraz627/Code/Versable/gcp/src/ kept as the deployed baseline 2026-08-17 = 23a0240 |
| foundry-runner (the first module on the contract, V1 co-hosted) | Python FastAPI, extracted from services-api; local first | foundry-runner.md (skeleton, filled as the CLI runs) | ../PLAN.md forge-1 |
| speedway | TypeScript, React Router SSR, Firestore, GCS, Cloud Tasks | speedway.md | ../evidence/20260817-speedway-recon.md |
| walmart-mvp | Python FastAPI, Postgres, Redis + arq, GCS | walmart-mvp.md | ../evidence/20260817-walmart-recon.md |
extraction (extractor, extractor-webserver, extractor-regression) | Python; a Compute Engine VM running systemd units, and a separate Cloud Run pair with Postgres, Redis and a pgbouncer sidecar | extraction.md | live GCP state; local checkouts; versable-git/knowledge-base (stale 2026-07-10) |
| enhancement-product (App V5) | Python on Render + Vercel; Postgres 16, Redis, S3, and Mongo present in-tree | enhancement-product.md (first pass, thin) | versable-git/knowledge-base deployment page (2026-06-26), local checkout |
Note on extraction.md: two live deployments share that name and only the older
is documented anywhere. Which serves extraction.versable.ai is unresolved, and
the doc says so rather than picking.
The recon reports in ../evidence/ already follow most of the template and
are citable as-is. The instance docs will be the same content re-cut against
the matrix rows, plus a Lapses section written against the canon rather than
against nothing.