Skip to content

UCCA — Technical Time Machine — 2026-07-02

Read me with the narrative TM. That one holds the arc and the rulings; this one holds the repo states, the file paths, the build entry points, and the traps. Nothing here is code yet — the input-path build has not started. This is the technical launch pad for it.

1. Repo states (verify live — git -C <repo> rev-parse --short HEAD)

Repo Path HEAD @ 2026-07-02 State
ucca-docs docs/ucca-docs/ 2dd8f27 main, in sync. All canon/contract/crossings filed + pushed.
ucca-engine engine/ucca-engine/ e4f992b main, in sync. Last commit = INGEST.md legacy stamp. No input-path code yet.
rtopacks (other house) ~/projects/rtopacks-project/ — Fence rule: do not read for UCCA decisions; relay only via Tim.

Workspace root ~/projects/ucca-project/ is not a git repo (holds the sub-repos + .credentials/).

2. What exists on disk in the engine repo

Input-contract primitives (present, the raw material the gate will use): - engine/triumvirate/ — schema.py, ddl.sql — the triumvirate input schema (v1.0). The gate validates against this. - engine/envelope.py — the UCCO envelope (/ns/ucco/v1); also renderer/vc.py (W3C verifiable credential) and workers/keys/ (keys.ucca.online — signing/verification reference; the CLAUDE.md security reference impl). - human_runs/UCCA-CARE-100-001__CHCPRT025__2026-03-09*/ — the validated run bundles. Their outputs/course_data.json is what the frozen §4.1 schema was intent-typed from. - generator/course_generator.py — the forward-direction generator (proven).

Existing FastAPI backend (NOT the gate — RTOpacks-era product endpoints): backend/app/routers/ = catalogue · composer · dockets · identity · internal · onboarding · packs · portal. The input-path gate + /v1/jobs is a new surface; none of these is it.

ADR-0002 residue (the violation the build must sever — DoD): worlds/ (115M), tga_data/ (8K), tga_pdfs/ (188K) still live inside the engine repo. The engine no longer ingests, but the code is still folded in. Severing worlds/ from the engine is half of ADR-0002's mint event.

Dev-only, not production (do not depend on): backend/jobs/poller.py — the Mac-Mini poller, explicitly temporary per CLAUDE.md. The Mac Mini is never an operational dependency.

3. The thing to build — input path, against the FROZEN contract

Spec: docs-site/docs/strategy/ucca-input-path-contract-pack-v0.1.md (v1.0 FROZEN) + ucca-content-payload-schema-v1.json. Build notes in the pack's §10, expanded into the full step-by-step UCCA-INPUT-PATH-BUILD-BRIEF-01 (5 reviewable steps + 3 DoD legs + 5 flagged v1.1 gaps). In one screen:

  • Gate at the Cloudflare edge — structural verification ONLY (no domain knowledge): auth, triumvirate schema version, structure, adapter signature, structural reference integrity, validation-block-present, size/rate. Reject codes GATE_*; malformed bounces WHOLE. Semantics are the conformer's warranty, never re-checked here.
  • Async job model — POST /v1/jobs → 202 {job_id, status:"accepted"}; GET /v1/jobs/{id} → status + UCCO envelope on complete; POST /v1/webhooks optional. No sync call, no SLA. job_type: generation live; diagnosis = honest 501 stub with full gate checks running.
  • Reasoner behind the gate (skin/body split — gate at edge, reasoner in its real runtime).
  • UCCO envelope out — four parsed surfaces (content payload = the v1 schema; trace map at source_ref granularity; provenance block passing Q-A3 completeness; signatures). Machine signatures attest provenance only — never a human compliance signature. Output vocabulary speaks about material, never persons/verdicts (§4.4 — testable).
  • Payload IDs module/block/question, stable within artefact version only; regeneration = new version + new IDs. Blocks encoded modules[].blocks[] (open confirmation — see §5).
  • Definition of Done = ADR-0002 proof event: input path live + a conformed job exercised gate→engine→envelope to terminal effect + worlds/ severed. On that day the register flips ADR-0002's remedy ruled (B, pre-proof) → minted.
  • Drift-check every decision: "does this only work because the client is VET?" → adapter, not gate.

4. Infra / access (from UCCA-SEED-01 — WHICH IS NOT FILED; re-verify everything)

  • SEED-01 is the access-state source of record and it is not in this repo (oldest unfiled reference — register flags it). Treat all infra state below as unverified until SEED lands or you re-check live.
  • Two Cloudflare accounts (ADR-0003): UCCA account (engine/Authority) vs RTOpacks account. Verify the account ID before ANY wrangler/D1 action — cross-account is a data-isolation breach.
  • Three standing traps (from SEED): the CF_ACCOUNT_ID pin, export-don't-source, wire-by-UUID. Re-verify tokens before any cloud action.
  • D1 UUIDs (per CLAUDE.md, may be stale — memory notes an RTOpacks-account DB migration): engine-db 0efa8970-…, ops-db 00daba3d-…. Confirm against current state, not this line.

5. Open at the fence (the two questions the next head must ask Tim)

  1. Block-encoding confirmation. The stamped pack + v1 schema crossed to RTOpacks 2026-07-02. Their conformer builds against modules[].blocks[]. Has their confirmation (or a v1.1 clarification request) come back? As of this writing: nothing received — no drop, fence quiet. A divergence is a v1.1 clarification, not a re-freeze.
  2. Has Alex broken ground on the input path, and is pack §10 a sufficient spec or does he need the build brief expanded? As of this writing: no input-path/gate code exists (grep clean); §10 is a thin build-notes section — offer to expand it into a full build brief if he wants one.

6. Gotchas (carry these)

  • worlds/ is 115M inside the engine — severing it is a real diff; do it as its own reviewed step.
  • --strict mkdocs build has one PRE-EXISTING warning (governance/contributing.md → missing CODE_OF_CONDUCT.md) unrelated to canon — don't chase it as yours; it predates this work.
  • Received copies have the RECEIVED COPY header ABOVE frontmatter — so their frontmatter doesn't strict-parse as YAML but Material renders fine. Never edit them to "fix" it (respond-never-redline).
  • Two docs have strict-YAML-invalid frontmatter by design (a mid-value colon / #): sent UCCA-RESPONSE-CONTENT-PAYLOAD-01, received RTOPACKS-*. Verbatim = leave them.
  • Every canon change went through: feature branch → git diff main HEAD --stat review → ff-merge → push. Keep that; it caught nothing bad because it was followed.

7. Pointers

  • Frozen contract + schema: docs-site/docs/strategy/.
  • Canon/register/ADRs/fossils: knowledge-site/docs/canon/ + .../decisions/canon/.
  • Every crossing artefact: knowledge-site/docs/canon/sent/ + .../received/.
  • The narrative baton: ground/UCCA-TM-2026-07-02.md.
  • Staged outbound (already crossed): ~/Downloads/ucca-stamp-crossing-2026-07-02/.

Technical baton. No code yet — a frozen spec, a clean repo, a 115M residue to cut, and a definition of done. Verify the SHAs and the account ID before you touch anything; the fence and the drift-check are not optional. Build the input path; mint ADR-0002.