Skip to content

UCCA engine — technical orientation, 2026-07-03

The headline: the engine is off disk. As of 2026-07-03 the input-path spine is deployed to Cloudflare and ran a real job end-to-end (gate → queue → container → GLM-5.2 → assembled, signed UCCO envelope in R2). Proof job 0dda7509-595f-414f-b727-82c12bfea3ce. ADR-0002 (remedy) and ADR-0004 are minted. What's not yet good: the generated content quality (see Open Items). Read on.

1. What this is

A legislative-compliance engine: it receives a Triumvirate-shaped job (outcome spec + criteria), generates content that traces coverage by construction, and returns a hashed, signed, immutable UCCO envelope. It "raises hands, never signs" — the seal attests provenance only, never a verdict on fitness (that's the client's human judgement). Atomic: one unit in, one envelope out.

2. Architecture — the deployed spine

POST /v1/jobs → GATE (edge Worker, structural checks only) → Queue (ucca-jobs, pointer-only)
                         │                                          │
                    payload → R2                         REASONER (container, queue consumer)
                                                          run_engine → generator (GLM via the throat)
                                                          → assemble → §5 validate → sign → R2 envelope
                                                          → job row: completed | failed (D1)
GET /v1/jobs/{id} → status + envelope (on complete)
Two rulings shape the container (Tim, 2026-07-03), both LIVE: - (a) No tokens in the container. The container reaches D1/R2/AI/keys ONLY through Cloudflare outboundByHost handlers on the shim Worker — it fetches http://jobs.db, http://artefacts.r2, http://provider.svc, http://keys.svc; the shim translates each into a binding call with Worker-side credentials. The container image carries zero secrets. - (b) One throat for cognition. All LLM calls route through provider.svc (GLM-5.2 via the AI binding; Anthropic/Z.ai direct-wire, no AI Gateway). The generator takes an injected completion fn; it holds no SDK/key.

3. What is LIVE right now (account e5a98302 — "Admin@ucca.online's Account")

Component Name Version Notes
Gate Worker ucca-gate 7afd429c https://ucca-gate.round-union-555d.workers.dev; queue producer
Reasoner ucca-reasoner df946c75 container ucca-reasoner-reasoner (standard-1, cap 2); DO class Reasoner
Keys ucca-keys 61aa8427 keys.ucca.online; /v1/sign (RSA-PSS-SHA256) now returns content_hash
D1 ucca-input-path a1fa9d09-6e20-46c0-a387-a4bb8f936639 jobs · cognitive_cost (insert-only, triggers) · gate_rejects
R2 ucca-artefacts (loc oc) {locus}/payloads/, /envelopes/, /diagnostics/
Queue ucca-jobs eb43044a… producer ucca-gate, consumer ucca-reasoner

Repos: engine ~/projects/ucca-project/engine/ucca-engine (git uccaonline/ucca-engine, HEAD ~7d25214); docs ~/projects/ucca-project/docs/ucca-docs (uccaonline/ucca-docs). RTOpacks is a separate repo + separate CF account (~/projects/rtopacks-project/, account f95d4537 — never touch it).

4. Engine code layout (engine/ucca-engine/)

  • workers/gate/src/index.js — the gate (7 GATE_* structural checks, POST/GET /v1/jobs).
  • reasoner/src/consumer-shim.js — the shim Worker: queue consumer + container manager + the outboundByHost binding handlers + the provider throat. The linchpin of ruling (a).
  • reasoner/consumer.py — container body: HTTP server on :8080, the 5-state machine, run_engine (payload → generator seam), the D1/R2 store helpers via bindings.py.
  • reasoner/bindings.py — tokenless HTTP client to the sentinel hosts.
  • reasoner/adapter/providers.py — the adapter (client to the throat; usage capture).
  • reasoner/assembler.py — run bundle → four surfaces → §5 validate → hash+sign (via keys.svc).
  • reasoner/schemas/ucca-content-payload-schema-v1.json — the frozen v1 content schema (vendored).
  • generator/course_generator.py — the content generator (course-era; takes an injected completion_fn).
  • db/input-path/schema.sql — the D1 schema (authoritative).
  • INPUT-PATH-BUILD.md — the build log (step 1, step 2, golden §8.1, all the decisions).

5. How to operate it (do this, don't rediscover it)

Full raw commands + the runbook seed: ground/UCCA-DEPLOY-NOTE-SPINE-01.md. Essentials: - Auth, every wrangler command: set -a; . ~/projects/ucca-project/.credentials/cloudflare.env; set +a (the vault CLOUDFLARE_API_TOKEN is UCCA-scoped → e5a98302). The wrangler OAuth default was re-pointed to admin@ucca.online this session, so a stray command now falls to UCCA, not RTOpacks — but SOURCE THE TOKEN anyway. - Deploy: cd reasoner && npx wrangler deploy (needs Docker daemon up; token needs Containers:Edit). - Submit a job: POST https://ucca-gate.…workers.dev/v1/jobs with {job_type:"generation", triumvirate:{triumvirate_schema_version:"1.0", validation:{…}, source_code, title, application, outcomes:[…]}}. Poll GET /v1/jobs/{id}. - Debug: npx wrangler tail ucca-reasoner --format=pretty; failures stash to R2 default/diagnostics/{id}/failure.json; cost rows in D1 cognitive_cost.

6. Build state

  • Step 1 (engine-call wiring) + Step 2 (envelope crypto): DONE, green. Golden §8.1 green vs the frozen CHCPRT025 bytes. Proof job completed live. See INPUT-PATH-BUILD.md.
  • ADR-0002 remedy + ADR-0004: MINTED 2026-07-03 (proof job). ADR-0005: the v1 content shape is the client's shape (ADAPTER, NOT GATE) — the course-shaped schema is deliberate, not a gate violation.

7. Open technical items (what to work on next)

  1. ⚠ Content quality (the real gap). The proof envelope's content is fallback-degraded — empty description/learning_outcomes, generic module body, no quiz. GLM-5.2's output doesn't parse into the generator's Claude-tuned JSON structure. The spine is proven; the generation needs GLM output-format tuning (or a different model). This is the highest-value next build.
  2. Provenance follow-ups (honest, non-blocking): cost-ledger model field logs the generator's config default (claude-sonnet-4), not the actual GLM that ran — thread the real model into ledger.record. Neurons not captured from the Workers AI usage.
  3. Footprint: the container still installs anthropic (unused) via the shared requirements — a reasoner-local requirements would drop it. Ruling (a) holds regardless (no key).
  4. Retirement unit (UCCA-RETIREMENT-UNIT-BRIEF-01 §A): shrunk to code residue only (config workers, qual-enrichment, docs-proxy, ops-v2 CUT + dangling bindings; ucca-backup is live infra, OFF the list; DBs/exports are a phantom). Waits on RTOpacks' C-6 answer. Then UCCA-TERRAFORM-RECONCILE-BRIEF-01 (queued behind it).
  5. INTAKE-01: both ⟨TIM⟩ closed; READY FOR RATIFICATION on Tim's word.

8. Landmines & gotchas (learned the hard way — see reference-engine-deploy-prereqs memory)

  • Account isolation is non-negotiable. UCCA e5a98302; RTOpacks f95d4537 — never touched. Verify the account before every wrangler/API command. Two client-pointing default creds exist on Tim's machine (the wrangler OAuth — now re-pointed to UCCA; and the Claude-app connector — permanently client-bound, never use).
  • Container wiring gotchas (all fixed, commit ea8ba3f): shim must export { ContainerProxy }; register handlers as Reasoner.outboundByHost = {…} AFTER the class (a static field shadows the base setter → requests escape to the internet = error 1016); enableInternet = false (base defaults TRUE); force the GLM model in the throat (the generator's claude-sonnet-4 isn't hosted by the AI binding); validate with a jsonschema validator instance (the frozen schema's $id had a fragment that check_schema rejects — now fixed to a valid URI).
  • Token scopes: the ucca-deploy token needs Containers:Edit to push the image. "Access: Audit Logs" is the Zero-Trust log, NOT the account resource audit log (D1 deletes live in the latter — dashboard-only).
  • The two drift-checks, on every build decision (canon UCCA-FENCE-ADOPTION-01): Domain — "does this only work because the client is VET?" → adapter, not gate. Purpose — "does this serve the reasoner, or is it a fossil of the course-creation engine?" Fossils get yellow-tape + ledger, never silent deletion; nothing course-shaped enters the spine's contracts.
  • The fence (FENCE-PROTOCOL-01): RTOpacks and UCCA are separate houses. Artefacts cross only through Tim, verbatim, digest-pinned. Never edit canon/received/. Never reach into the RTOpacks repo.

9. How to navigate the docs

  • The register (canon/canon-register.md) is the living index — status of every canon/ground/ decision doc. Start there.
  • Layers: canon/ (rate-of-change: the constitution), ground/ (true-today: briefs, TMs, findings), decisions/canon/ (ADRs + rulings), canon/sent|received/ (fence crossings).
  • ADR lifecycle: ruled (binds on Tim's word) → minted (verified/ratified). Minting is an honesty marker about proof, not a permission gate.
  • Discipline: never claim ✓ without a filed artefact; "prepared from project memory" is a warning label, not a source; testimony is valid only when labelled + dated + filed.

10. First moves for a new session

  1. Read the register; skim this TM's §3 (what's live) and §7 (open items).
  2. If building: the content-quality gap (§7.1) is the highest-value work — inspect the proof envelope (~/Downloads/UCCA-proof-0dda7509/signed-envelope.json) to see the degradation, then tune the generator's GLM prompt/parse path.
  3. If deploying: UCCA-DEPLOY-NOTE-SPINE-01 + source the vault token, always.
  4. Confirm the account (e5a98302) before any wrangler command. Apply both drift-checks. Respect the fence.

The engine gets to alive by passing its own test — and it did, live, on 2026-07-03. Now make the content as good as the plumbing.