What the factory is
The factory builds software from a written brief. [180] A customer states an outcome in plain words. [98] The factory writes a contract, builds the product, and proves each line. [102] No person approves a step in the path. [78]
The work runs on one bus and one graph in one Postgres database. [s05a] Every message, launch, and verdict is a row in that record. [169] A reader can replay any run from the record alone. [161]
The finish line is a stranger's brief carried to a released site. [78] The run must need no human help and must stay under a known cost. [78] Three live runs have tested that line so far. [129]
The orchestration diagram
The customer talks to the Foreman seat. [126] The Foreman writes the brief and the contract. [98] Lanes build inside cells, one claim per seat. [112] Panels try to refute the built work. [176] The engine merges only after the panels and checks pass. [s57]
The boxes
Each box names one mechanism of the factory. [180] The text of each box comes from the architecture page of the record. [119]
factoryd engine F18 · s56 s70 s71
One daemon wires the stage services together. Its patrol ticks every 30 s. At boot and on each tick it reconciles lane containers that are gone (s70). Every sweep (flow driver, reconcile, digests, packs, C5 verify, drift, operate, studio hook) first asks servesChannel , so a channel the engine does not serve is never read, written or launched into (s71). Evidence freshness is scoped to the story set it is asked about (s56, F17).
Phase driver s62 · d1
Reads the phase from node_state of the project node; there is no eng/phase key. transition() appends phase.entered in one transaction with its system message, only when the gate decision is proceed (or retry at operate→build), is about the project node, starts at the current phase, and has not been consumed. It then opens the next stage channel and posts the gate line.
gate-policy I7 · s58 · d3 d34 d36 d37 d40
Computes proceed, retry, escalate, stuck or stop from evidence rows. Policy m1-local is an overlay on gates.json, registered as a policy_version and stamped on every gate decision it governs; it shadows only traceability and security_rules , and panels and mutation_kill stay blocking (d3). Gate decisions are append-only per tree, lap and harness (d40).
rpc and records s61 · d2
Foreman's judgment arrives as rpc frames on POST /lane/v1/rpc , accepted only from the project's seat-holding foreman. contract.propose and decision.propose validate with zod and refuse with {code, path, next} . The factory writes every decision row.
Claims and integrator s60 s65 · d23 d24
Each claim-bound ask runs on that claim's full clone of the project repo, mounted at /work ; a claim-bound ask never uses the shared channel directory. Tests and shared claims open at idb/integration , story claims at storyBase . The post-exit snapshot pushes claim/<id> into the project's local bare repo, never a remote.
Wake and launcher s74 s75 s76 · d15 d38 d52
The engine turns asks into lane launches. Each launch has a 30-minute window today. s74 replaces it with a per-ask budget_ms : near the limit the engine commits the claim, records a checkpoint and relaunches the same member with --resume . s75 pauses a lane waiting on a ruling. s76 wakes the Foreman on replies, and once merged it supersedes decision 15's per-tick inbox poll (d52).
Postgres: idb and idb_app d43 d47 · pipeline §3.1
idb is the control DB: bus tables, graph, contracts, decisions, claims, evidence, gate decisions and the ledger. Each writer is a Postgres role ( idb_bus , idb_checks , idb_engine , idb_actuator ). idb_app is the application DB as a separate database (its own instance on the cluster, F21), named by IDB_APP_DATABASE_URL . checkd creates a disposable per-run schema there, never on the control DB, and drops it afterwards (d43). The candidate and its twin eval_<project>_r<N> also live there (s66, d14).
idb bus s57 · d2 d38 · DESIGN §2
Switchboard's pinned behaviours re-expressed on Postgres: asks, replies ( done , progress , blocked ) and reports. Only the engine stores decision and system messages; a customer posts chat and asks only the Foreman (s57). Each project has a project channel plus one stage channel per phase. The engine sends every phase-step ask (d2). Asks cite the record (PLAN row, frozen test hashes, commit shas, decision numbers) and never a summary of it (d38).
Foreman seat (fable) s61 s72 s73 · d15 d18 d42
The engine seats the Foreman in the launch transaction, with an orchestrator:<project> runtime lease released on exit (d18). It writes contracts and decisions only through rpc and keeps bus_ask for research. It polls its own inbox each tick (d15). Before reading a verifier's report it records its own expectation, and each ruling cites one fact it checked itself (d42). F19 gives it a task roster (s72) and ask steering (s73).
Shadow Foreman s78 · d44 d52
A second foreman seat ( foreman-shadow ) on a different lab. On each judgment event it records its own expectation and ruling from the record before it can see the primary's, then posts a report comparing the two. It holds no seat and writes no decisions (negative line shadow_wrote_decision ). Later evidence settles the score into a per-lab scorecard. When the shadow outscores the primary over a window, the seats swap by recorded decision through decision 18's handoff.
Plan-steward s79 · s77 pattern
A standing seat that never builds, verifies or rules. It wakes on commits to PLAN.md or the coherence brief, on each recorded decision, and weekly. A fresh-context lane on a lab other than the editor's answers four fixed questions and writes docs/plan-conformance/<sha>.md . Findings reach the Foreman's inbox as non-blocking asks and run under the s77 orchestration-tax budget. The steward also maintains this page.
Lanes as docker cells d7 d8 d20 d55 · DESIGN §8.1
Each launch gets its own container on the factoryd host, with a per-account uid, read-only root, cap-drop ALL , the claim clone at /work and the account home. The build roster is claude, muse, kimi and cursor by recorded override (d7); independent stories go to distinct harnesses. kimi's lab is other . cursor's lab is resolved per launch and pinned outside {xai, google} (d55). codex-1 writes every frozen test. grok-1 and agy-1 verify (d8). A seat's lab is read from the launch's resolution_id .
checkd sandbox runs I2 · d11 d27 d31 d32 d43
Every check runs in a fresh container: a distinct uid, a fresh clone at tree_sha , no home, no token, and a per-run network. checkd writes report.json itself into a host directory no container mounts. Extra read-only mounts carry the freeze spec at /spec (hashed, spec_tampered on mismatch) and dependencies at /deps (d27). Scratch clones borrow the template's installed node_modules read-only and never install (d32). C1/C2 checks (d11) and governing checks per claim (d31) also run here.
Local docker actuator s66 s68 · d4 d14 d47
Builds the candidate from git archive <tree_sha> of the stamped tree, not from the template. The candidate migrator writes the template's schema_migrations ledger, so the container's boot migrate is a no-op. Each file runs under the canary.json lock and statement timeouts. s68 promotes, rolls back to the previous revision (or to r0, which is image evidence and not a release row, d4) and starts operate.
Ledger s10 s80 · d19 d46 d54
s10 reserves holds for launches, checks, panels and operate, then settles them against plan and stage shares. The project budget is the workspace plan's cap less posted and held amounts (d19). s80 lands in the M1b wave and writes one usage row per model call, keyed by account, lab, model, effort, project, plan row, claim, launch, ask, turn, task class and phase. Each row is priced by price_list_version , and subscription lanes carry window share plus the equivalent API price (d46). Estimates and measurements are never summed.
Builder labs and verifier labs I3 · d8 d51 d55
The builders are every seat whose code is in the sha, the tester included. The verifiers are every refuter and judge seat, and a seat that shares a builder's lab is refused. F18 stories are verified by grok-1 or agy-1. Codex never verifies. The plan's V column names the refuter, whose reply is a claim plus a line on what it could not exercise. Merges follow the gate decision, never a lane's PASS (d51).
The tests lane and frozen tests I4 · d25 d56
codex-1 is the only writer of frozen tests. The frozen closure is what the tests reach: tests, their imports, the runner config and the lockfile (d25). If anyone else edits it, that is drift and the claim is reset. The only way to unfreeze is a tests-lane reissue backed by a checkd reproduction. s24's 5-seat floor may refute a reissue but never authorise one (d56).
Foreman and lanes d2 d38 d57
The Foreman decides through rpc and records an override when it departs from a default. Until s82, it dispatches the factory's own features over the bus, with the B/V columns as defaults (d57). Lane-to-lane asks are read-only questions. Anything that changes work, such as a reissue or a scope change, goes through the Foreman's inbox (d38).
Explain-back before a milestone merge d42 d49 · s77
Before the M1 merge, the Foreman dispatches by hand a fresh-context lane from a lab outside every F18 builder. That lane explains the changed system back from the record. Its questions and the Foreman's answers are recorded on the merge's gate decision (d49). From M1b, s77 automates this: explain_back_failed becomes a gates.json row with checkd-produced evidence.
Gates d69
Before M1b's live runs: S1 hotfix to s66, s93, s95, s20/s57 bounds and redaction, F19 s72-s76, s80. Before M1c: s94, s84/s90 home isolation, s57/s54 message immutability, R5 circuit breaker, s97, s98, s99. Before M5: s96, F21, s100. The M1 live run itself requires S1, since it releases a candidate.
Usage truth
Each vendor pool is a row with observations from its own surface. The usage_truth view derives headroom per pool. A pool with no read-back is unmetered. (decision 156, s49)
Panels and judge calibration
Panels vote on claims from the record. The owner's rulings on real panels form the calibration set. A judge change ships at Cohen's kappa 0.6 or better. (decision 176, s118, s121)