--- title: "The Creator — Architecture & How It Works" description: "One line: the Creator is Terraform for capcom's control plane — the single door through which every new worker, service, scheduled service, helper, work surface and LV service is born. Live since 2026-09-20; it has…" created: 2026-09-20 updated: 2026-09-21 authors: ThinkingCap R&D topics: [CapCom] status: published canonical: https://console.thinkingcap.com/rd/CapCom/creator-architecture date: 2026-09-20 --- # The Creator — Architecture & How It Works **One line:** the Creator is Terraform for capcom's control plane — the single door through which every new worker, service, scheduled service, helper, work surface and LV service is born. Live since 2026-09-20; it has already birthed and retired its first proofs. **The rule it answers (DOUG-0726, proposed):** *"Workers, services, scheduled services, helpers, work surfaces, LV services — all of it is made by a request to the Creator. You do not build these by hand; you ask, and the Creator births them."* --- ## 1. The model — Declare → Plan → Apply → State Terraform's loop, specialized to the estate: 1. **DECLARE** — an AI (loom, agent, Claude) or a human says what should exist: `{kind, name, spec}`. Six kinds: `worker`, `service`, `scheduled-service`, `helper`, `work-surface`, `lv-service`. 2. **PLAN** — the Creator computes the ordered provisioning steps for that kind and checks collisions (name regexes, port uniqueness, the dev/live image-name SEVERE gate, existing rows). Planning is free, read-only, and available to every door. 3. **APPLY** — executes the steps idempotently, recording each one in a step ledger; resume-safe after failure. **There is no approval gate** (Douglas, 2026-09-20: "no controls. nothing they create goes live without a human anyway"). Safety is structural — see §6. 4. **STATE** — one table, `creator_resources`, remembers everything the Creator birthed: spec, plan, per-step results, and an **operator digest** (the exact commands/SQL for anything that still needs a human). This is the teardown breadcrumb trail and the audit log in one. ## 2. The island The Creator is itself a textbook estate island (the tc-svc-book pattern): - **Repo:** `tc-svc-creator` (bare `/srv/git/tc-svc-creator.git`, clone `/srv/tc-repos/tc-svc-creator`), vendored, own Dockerfile, no capcom imports. - **Runs:** container `capcom-svc-creator` on **both** capcom nodes (capcom + capcomaux — DOUG-0011: no production singletons), host networking, port **3200**, `--mount type=bind,source=/srv/git,target=/srv/git` (rw — this mount IS the birth authority, see §5), env from `/etc/capcom/patch.env`. - **Guard:** `GET /health` is open; everything else requires `x-creator-service-key`. Unkeyed → 401. - **Kill switch:** `app_settings.creator_enabled = false` → mutating routes 503 `{disabled:true}`; planning and reads stay up. - **Heartbeats:** `creator` / `creator_aux` rows in `system_monitors`, 60s. - **Registry rows:** `scheduled_services` (`mode='paired'`, `handler_kind='creator_http'`) + `service_placements` ×2 (`managed=false`). - **Its own birth was the last hand-birth in the estate** — bare, clone, rows, key, NSG and first bake were done by hand on 2026-09-20. Every service born after it comes through the door. ## 3. The engine ~450 lines of TypeScript (`server/engine.ts` + `server/modules/*`). The unit of work is a **Step**: ``` { key, title, run(ctx) → {ok, detail?, digest?}, verify(ctx) → bool } ``` Apply walks the plan in order: - **verify() first.** Already true → record `already present` and move on. Re-applying an existing resource is therefore safe and cheap (idempotent resume — the tc-svc-onboarding precedent). - **run() then verify() again.** All ok → next step. - **Failure → stop.** Resource marked `failed`, the failing detail recorded, and a note filed in the digest. A later fix + re-apply resumes from the first unverified step. - **The degrade rule** — the design idea that made v0 runnable on day one: a step that lacks live authority does NOT fail. It completes as `deferred to operator` and writes the **exact command, SQL or code block** an operator would run into the resource's digest. Steps light up for real as authority is granted — no big-bang permissions, ever. ## 4. The six archetypes | Kind | Status | What APPLY materializes | |---|---|---| | `service` | **LIVE** | bare + island scaffold, `scheduled_services` row, port, `service_placements` ×2, descriptor drop, operator digest | | `scheduled-service` | **LIVE** | the same minus port/NSG, plus cron-XOR-interval validation and the `svc.` flags seed | | `work-surface` | stub | scaffold, bare, `work_surfaces` + `surface_build_targets`, worker pair + env scopes, permission rule, console-api descriptor drop | | `lv-service` | stub | scaffold, bare, `surfaces.config.json` pin drop, 20 generated `worker_types` rows + 60 env scopes, `lv_settings` nav defaults | | `helper` | stub | `helpers` row (`proposed`) + CLI scaffold per HELPER-CONTRACT, dropped to agent-ops | | `worker` | stub | wraps `POST /api/workers/onboard` with local-source defaults | Stubs fail loud (`module not yet built`) so a request can never half-materialize. Build order: work-surface → lv-service → helper → worker. ## 5. Anatomy of a birth (kind=service, measured live) `POST /resources {"kind":"service","name":"creator-selftest2"}` — **applied in 158 ms**, six steps: 1. **bareBirth** — `git init --bare --initial-branch=main /srv/git/tc-svc-.git`, clone to tmp, materialize the vendored island scaffold (Dockerfile, service skeleton, heartbeats, kill switch, README — `__NAME__`/`__PORT__` substituted), one commit *"Birth of tc-svc-\ (Creator)"*, push to main, settle `HEAD → refs/heads/main`, then **`chown -R` to the `/srv/git` owner** — Creator-born bares belong to the estate, never to root. Authority: init + seed **only**, never rewrite — after birth, DOUG-0725 applies and every later write is a Bakery drop. 2. **scheduledServicesRow** — defensive upsert (`enabled=true` so the baker discovers and builds it; go-live is gated elsewhere). 3. **portAlloc** — a free host port on the capcom pair, recorded in the spec (the scaffold bakes the same port — allocation is deterministic). 4. **placementsRows** — `service_placements` on capcom + capcomaux, **`managed=false`**: the reconciler observes but cannot act. 5. **descriptorDrop** — the `svc()` line that puts the service on Releases → Services, filed as a Bakery drop to capcom main (degrades to the exact snippet when no drop key is present). 6. **operatorDigest** — the NSG rule, the `patch.env` keys, and the first-run/cutover runbook, filed in the digest. One tick later the baker's fs-scan registers the new bare in `drop_targets`; its discovery pass sees the `scheduled_services` row and **builds the image without anyone asking** (measured: under 2 minutes). ## 6. What the Creator deliberately does NOT do The *converge* side of the estate was already sovereign and stays that way: - **Builds** — the build-baker owns every image (discovery, bake, push). - **Fleet placement** — Maestro owns workers; the placement reconciler owns service rolls. - **Go-live is human.** Everything the Creator births is dormant: workers `enabled=false` until an operator Deploy/Promote; services sit `managed=false` until cutover; surfaces' permission rules default `manual`; every deploy route is operator-only. **Creation is free; activation is Douglas.** That is the whole safety model. - **Azure-side primitives** (queues, NSG writes, VM stand-up) stay out-of-band — the digest hands the operator the exact commands. ## 7. The doors - **Island API** — `http://:3200` behind `x-creator-service-key`: `POST /plan` (free), `POST /resources` (declare+plan+apply), `GET /resources[/?kind&status]`, `GET /resources/:id` (full ledger + digest). - **capcom-mcp `creator_*`** (the AI door, live): `creator_plan` and `creator_status` read-only; `creator_request` confirm-gated (preview without `confirm:true`, execute with it). - **capcom proxy** `/api/creator/*` — on main, goes live with the next operator web Deploy (session auth, `requested_by` stamped from the session). - **No human page.** Douglas, 2026-09-20: "this is used by ai not humans." ## 8. The Book around it - **DOUG-0725** (writes belong to the Bakery) governs everything after birth; the Bakery's checkpoint Book-judges each drop as one intent. - **DOUG-0726** (proposed) makes the Creator the only door for new things. - With the Creator embodying the mechanics, the hand-lore was struck from the Book: DOUG-0210, 0306, 0348, 0350, 0480 — agents no longer learn *how*; they ask, and the registry is the reality. ## 9. Ops reference - **Key:** `~/agent-ops/.creator-service-key` (600) = `CREATOR_SERVICE_KEY` in `/etc/capcom/patch.env` on both nodes (plus `CREATOR_PORT`, `CREATOR_SERVICE_URL`, `CREATOR_SERVICE_PEER_URL`). - **NSG:** `creator-pair-3200-pub` + `creator-devvm-3200` on both capcom NSGs. - **Roll the island:** pull the new tag, recreate with `--mount type=bind,source=/srv/git,target=/srv/git`, **then verify `docker inspect … .Mounts`** (a `-v` flag was once eaten silently by the run-command bridge — a mountless Creator degrades every birth). - **Ledger:** `SELECT kind, name, status, requested_by, created_at FROM creator_resources ORDER BY created_at DESC;` - **Retire a proof:** delete its `scheduled_services` + `service_placements` rows, remove the bare (doug can — Creator-born bares are doug-owned), mark the resource `retired`, purge the image. Full retire automation is v2. ## 10. State & roadmap - **Live:** v0.1 on both nodes (`svc-20260920-190325-0aaa823`), modules service + scheduled-service, MCP door, proxy on main. - **Pending:** Douglas's pen on DOUG-0726; operator web Deploy (proxy + descriptor); modules 3–6 on his go. - **v2 candidates:** teardown/retire flows, worksurfaces stand-up via run-on-vm, Azure queue creation, `creator_request` via the proxy for humans who want curl. *Built, bootstrapped and proven 2026-09-20. Spec (with the design decisions and their rulings): `/media/shared/For Douglas/creator-service-spec.md`.*