syntaxai/tdd.md · main · content / blog / sama-empirical-c21-split.md

sama-empirical-c21-split.md 169 lines · 6613 bytes raw · source

When the verifier said "split this": one Atomic-700 hit, four handler files, the build stayed green

tdd.md ships under its own discipline. Every push to main goes through the SAMA verifier (bun scripts/sama-cli.ts check) before the deploy script runs. Sorted, Architecture, Modeled, Atomic — four mechanical grep-based checks the source has to pass.

This post is the receipt for one of them firing.

What the verifier said

After the Fase-2b admin block-editor landed in src/, the verifier printed this:

SAMA verify · (local)/src · (working tree)
  examined 63 SAMA files / 12 tests / 66 src files

  S — Sorted: ✓ pass (63 files)
  A — Architecture: ✓ pass (63 files)
  M — Modeled: ✗ 4 violations (51 files) [pre-existing]
  A — Atomic: ✗ 1 violation (63 files)
     · c21_app.ts — 761 lines (over the 700-line split threshold —
       split per UI/data domain)

✗ 2 of 4 checks failed

One file. One line. A 60-line overrun on the route table, because the admin port added four new /admin/* route bodies plus the /admin/assets/blockeditor.js bundle handler. No mystery, no intermediate report — the grep counted, the count was over, the build broke.

What I did about it

The verifier's hint is "split per UI/data domain" — not "delete some lines" or "extract a helper." It's pointing at the existing pattern in the repo: c21_handlers_reports.ts, c21_handlers_sama.ts, c21_handlers_admin.ts are already domain-grouped handler files. The route table in c21_app.ts had picked up four clusters that hadn't been pulled out yet:

  • The Bun.serve fetch fallback — regex-matched routes that the declarative table can't express (multi-segment admin slugs, /GIT/:owner/:repo/{tree,blob,raw}/<path>, the bare /<owner>/<repo>.git redirect, the git smart/dumb-HTTP proxy)
  • The /projects cluster — landing, register, detail
  • The agent-facing JSON API — /api/judge and /api/agents/:name/visibility, both bearer-token-gated
  • The Forgejo push webhook — HMAC-verified, fires judge() in the background

Four new files, one commit:

 src/c21_handlers_fallback.ts      | 131 ++++++++
 src/c21_handlers_projects.ts      | 114 ++++++
 src/c21_handlers_api_agents.ts    |  95 ++++++
 src/c21_handlers_webhook.ts       |  41 +++
 src/c21_app.ts                    | 308 +---------------
 5 files changed, 398 insertions(+), 325 deletions(-)

c21_app.ts: 761 → 452 LOC. Net delta on the codebase: +73 LOC of import-boilerplate and per-file headers. That's the price of Atomic being "one concept per file" — it costs you some imports.

What the verifier saw next

Re-run after the split:

SAMA verify · (local)/src · (working tree)
  examined 67 SAMA files / 12 tests / 70 src files

  S — Sorted: ✓ pass (67 files)
  A — Architecture: ✓ pass (67 files)
  M — Modeled: ✗ 4 violations (55 files) [pre-existing, out of scope]
  A — Atomic: ✓ pass (67 files)

Four files added (67 vs. 63), Atomic flipped green. The Modeled violations are pre-existing: four c32_*.ts files without sibling tests that have been overdue since before this work started. They weren't introduced by this split and they weren't fixed by it — that's a different commit.

Why this matters as evidence

A coding standard is only worth something if it can catch a real violation in a real codebase and tell you what to do about it. SAMA's claim is that it does that mechanically: a grep-based verifier, no language server, no ML, no judgement calls. The flagged-detail string is the entire instruction.

The empirical sequence here:

  1. The verifier detected the overrun. Not the linter, not the compiler, not code review — a 60-line grep ran in CI and said "this file is over budget."
  2. The detail told me where to look. "split per UI/data domain" is the same phrase that appears in content/sama/atomic.md. The verifier and the doc are aligned because the verifier is the doc executed.
  3. Following the hint took ~45 minutes. Four files, three of which were extractions of contiguous code blocks. The fourth (c21_handlers_fallback.ts) needed slightly more thought because appFetch reaches into several lower-layer handlers, but each call site was a one-line delegation in the new file.
  4. Nothing else broke. 138/138 unit tests stayed green, 49/49 end-to-end tests against live stayed green, the deploy went out clean. The SAMA verifier's other three checks (Sorted, Architecture, Modeled) didn't shift — they were already green and the split didn't disturb them.
  5. The bare-repo proof still holds. The git-native-proof e2e test logs in as admin, saves an edit through the web editor, and confirms the resulting commit lands in /home/scri/repos/tdd.md.git on the deploy host — not via a Forgejo HTTP round-trip. That test passed before the split and passed after. The route table moved; the commit pipeline didn't notice.

The shape of the proof

This is what "SAMA can be enforced mechanically" looks like as a sequence of artifacts a reviewer can replay:

$ git log --oneline -2
c9e085a SAMA Atomic: split c21_app.ts per-domain ...
3cbd955 Smoke: expect SAMA in homepage title, not tdd.md

$ bun scripts/sama-cli.ts check
  S — Sorted: ✓ pass (67 files)
  A — Architecture: ✓ pass (67 files)
  M — Modeled: ✗ 4 violations [pre-existing]
  A — Atomic: ✓ pass (67 files)

$ bun test
 138 pass, 0 fail

$ bun x playwright test
 49 passed, 1 skipped

The split is one commit. The verdict is one command. The proof is in the git log, not in this post. You can clone the repo and run the same three commands.

What this doesn't prove

It doesn't prove SAMA scales to 100k LOC, or to teams of ten, or to languages other than TypeScript. It proves one thing: on a ~7k-LOC TypeScript codebase, the verifier caught a real Atomic violation introduced by a real feature, told the operator exactly which axis the violation was on, and the fix followed a documented pattern that didn't disturb the rest of the build.

That's the smallest unit of "this standard works." Bigger units come later — the Fase 2b admin block-editor that triggered this overrun shipped in the same week, and the verifier stayed green through both. The next post is about that port: a 6k-LOC migration of a podman-based CMS into SAMA's layer conventions, and what the c31_image_resize.ts → c14_image_resize.ts correction taught us about how the Architecture axis interacts with I/O.

Until then: the case study is one commit, four handlers, one verifier going green. The empirical record is the receipt.