§2How it works · engineering codename SQ5
A person describes what they want in plain English. An AI calls a small, fixed set of MCP tools that each stage one structural edit — nothing is written until the whole batch commits atomically. A single Go binary validates, versions, materializes, and renders the result.
01The pipeline
Each tool call — createNode, updateNode, deleteNode, connect, disconnect, reorder — stages one small structural edit against a normalized graph with stable IDs. Nothing is written yet; preview can diff the pending batch without committing.
commit checks every staged op together against the current spec. An invalid batch writes nothing and returns a structured rejection — {code, closure} — with exactly the pointer a one-step fix needs: which op, which id, which name collided.
A new spec version is inserted — the previous one is never overwritten — and the batch is appended to an insert-only op-log: a full, replayable history of every edit ever made.
$ sq5 console apply --app jobs-tracker --ops … --deterministic
{"ok": true, "version": {"id": "ver_000001", "seq": 1, "createdAt": "2026-07-22T12:00:00Z"}}
The per-tenant SQLite database is materialized: tables and columns are created or altered, named t_<entityID> / c_<fieldID> — so a later rename is a spec-only edit, never a schema migration.
$ sq5 console schema
t_ent_000001: id · created_at · updated_at · version · created_by · updated_by
tenant · deleted_at · c_fld_000001 · c_fld_000002 · c_fld_000003 · c_fld_000004
The same single-page app interprets every spec — lists, boards, calendars, dashboards, workflows. No app-specific code was written anywhere in this path.
02The tool surface
The stdio MCP server advertises exactly these tools — the entire write surface to app structure. Read tools inspect; staging tools queue ops; commit is the only door to the spec.
list the node types, field types, and edge kinds available.
list all entities with field counts.
get one entity's fields and config by id.
get one workflow's ordered steps and config by id.
find nodes by type and/or name substring.
stage creating a node (entity or field).
stage updating a node's props.
stage deleting a node (and its edges).
stage connecting two nodes via a named edge.
stage removing an edge.
stage reordering an edge's children to an exact order.
preview the pending batch without committing — diff + migration plan + risk flags.
validate + apply the pending batch atomically as a new immutable version.
discard all staged, uncommitted ops.
03The invariants
(state, ops, clock, gen). Clock and ID generation are always injected — never time.Now() or rand inside the engine — so every apply is replayable byte-for-byte. It's also what makes the metrics gate below deterministic.04Metrics methodology
First-pass-green: from a cold build prompt, the AI generates both a spec and tests for it; the run is green only if that spec passes its own tests on the first commit — no retries counted. Flat-drift: after an unrelated edit to the same app, the percentage of held-out tests that stopped being green. Code generation accumulates drift as apps grow; a fixed op surface shouldn't — that's the falsifiable part.
| Phase / scope | Model | Green% | Drift% | Verdict |
|---|---|---|---|---|
| P0 — 8 entity+field apps | claude-sonnet-4-6 | 100% (8/8) | 0% | PASS |
| P1 — booking, orders | claude-sonnet-4-6 | 100% (2/2) | 0% | PASS |
| P2 — full gate, incl. team-tasks perms | claude-sonnet-4-6 | 90.9% (10/11) | 0% | PASS booking borderline cold, fixed |
| P3 — logic prompts | claude-sonnet-4-6 | 100% (3/3) | 0% | PASS |
| P4 — first slice (agentStep) | claude-sonnet-4-6 | 100% (1/1) | 0% | PASS |
| Current gate — deterministic | — | 25/25 = 100% | 0% | PASS held flat through every P5 slice |
05The stack
./sq5 is the server, the console, the MCP surface, and the migration engine.Designed and built by Ahmed ElBatanony. Go · ~95,000 lines · 924 tests · 618 commits.
Need this built for your business? See the offer →