Buildmere Engineering | Blog

Are We Drifting? — Part 15: Structure Is the Rail

Tue, 16 Jun 2026 00:00:00 GMT

Are We Drifting? — Part 15: Structure Is the Rail

Earlier parts treated structure and enforcement as two of the three legs of a . This part is about the relationship between them — because it is a loop, and the loop is what makes the whole thing scale.

The loop

Structure gives enforcement the rails to scale.

A rule that has to find its targets by hand does not scale: someone has to maintain the list, and the list drifts. A rule that targets a shape — every file named screen.tsx, every package under internal/, every function returning error from a handler — scales to the whole fleet for free, because the shape is the selector. This is : adopt the shape and the enforcement attaches automatically; new code is governed the moment it takes the form, with no list to update.

And enforcement is what keeps the structure intact.

A folder convention with no gate is a folder convention until the first deadline, then it is a suggestion. The rule that forbids a fixture import outside a route is what keeps the layering real — without it, “screens are pure” decays into “screens are mostly pure,” and the structure the next rule depends on is gone. Enforcement is how a structure stays a structure.

Structure makes enforcement cheap to scale. Enforcement makes structure safe to rely on. Each one funds the other.

The loop compounds. More structure means cheaper, broader enforcement; broader enforcement protects more structure; protected structure is something the next rule can assume. The codebase ratchets toward more legible, not less.

Structure is not one level — it is every level

The word “structure” hides how many levels it runs at. The same loop — a convention paired with a gate — repeats from the coarsest grain to the finest. Each level’s gate is what lets the next level’s rule assume the level beneath it holds.

Level	The structural convention	The gate that holds it
Directory	a domain’s handler + repo co-located in `internal/<domain>/`; a feature’s five layers in `features/<family>/<feature>/`	`depguard` — no cross-domain imports (lint-error)
File name	`screen.tsx`, `route.tsx`, `controller.ts`, `.fixtures.ts`, `00001_.sql`	the rule self-targets by the name — the name is the selector
Module boundary	`packages/ui` is product-agnostic; the state system lives in one place	`no-state-system-in-ui`; middleware only in `internal/server` (depguard)
Imports	a screen never imports a fixture; a handler never imports `pgx`	`liftmere/no-fixture-outside-route`; `depguard` (handler ∌ pgx, repo ∌ connect/http)
Function signature	a metric is recorded through a generated, typed method; a handler returns a typed Connect error	`RecordUploadIntentCreated(ctx, contentType, outcome)` — labels are parameters; `forbidigo` bans bare `fmt.Errorf`
Type shape	a handler implements the generated interface; a screen handles every state	`var _ ServiceHandler = (*Service)(nil)` (compile); exhaustive `matchState` (compile)

Read top to bottom and the grain gets finer — a directory, then a file, then a module edge, then a single import line, then the shape of one function, then a type. Read any row left to right and it is the same move every time: a shape, and a gate that refuses anything that is not the shape.

The fine-grained levels are only affordable because the coarse ones hold. no-fixture-outside-route can be a simple, file-granular rule precisely because the file-name convention (route.tsx) and the directory convention (one feature per folder) are already enforced beneath it. Pull out a lower level and the rules above it lose their footing. The structure is a stack, and each gate is a floor the next one stands on.

Structure at every level — the coarse conventions are the foundation; each finer rule stands on the gate beneath it. Conceptual, not measured data.

Why this is the deepest investment

The instinct is to think of the lint rules as the asset. They are not. The rule is cheap — especially now. The asset is the structure the rule rides on, because that is what makes the rule general instead of bespoke, and what makes the next rule possible at all.

This is why “add a guardrail” is rarely the first move. The first move is to give the thing a shape — a canonical file, a folder, a naming convention, a typed signature — and the guardrail follows almost for free, because it has something to target. A team that invests in structure gets enforcement at a discount forever after. A team that writes rules against an unstructured codebase pays full price for every one and watches them rot.

The velocity payoff

The coherence check this removes is the one that does not look like a check at all: where does this go, and what shape does it take?

When structure is enforced at every level, that question has one answer per level, and the answer is mechanically true — a new domain is a folder, a new feature is five named files, a new metric is a typed method, a new handler implements a generated interface. An agent does not guess the shape; the shape is the convention, and the gate refuses the guess that misses it. You accept a large generated change and trust it not because you reviewed the placement of every file, but because misplacement is a shape the build does not allow.

That is the rail metaphor made literal. Rails do not make a train fast. They make it possible to go fast safely — and to add another train without re-surveying the route.

What’s next

Structure is the rail; the gates are placed along it. The rest of the series walks specific rails — the vocabularies, the operations, the agents — and a running inventory of the gates. The question stays the same at every level, coarse or fine.

Are we drifting? Not where the shape is named and a gate holds it — and the more levels that is true at, the less there is left to drift.

Are We Drifting? — Part 14: The Wall of Gates and What Comes Next

Mon, 15 Jun 2026 00:00:00 GMT

Are We Drifting? — Part 14: The Wall of Gates and What Comes Next

Every layer of the stack turns out to be the same move: one declarative source → many generated → keep them honest. This part collects the gates built so far, grades them on the ladder, answers the title, and points at where the pattern goes next.

The wall, in one place

A guardrail that does not run is theatre. So here is the actual set of checks that run — most on every pull request — each tagged with its tier and the part of the series that covers it:

Gate	What it catches	Tier	Series
`var _ ServiceHandler = (*Service)(nil)`	handler drifts from generated interface	1 — compile	Part 11: The FE↔BE Mirror
`tsc`	exhaustive `matchState`, typed everything	1 — compile	Part 11: The FE↔BE Mirror
`liftmere/no-fixture-outside-route`	fixture imported outside route/story/test	2 — lint-error	Part 12: Testing Without Drift
`liftmere/no-raw-hex-color` / `no-raw-tok-vars`	raw color values in component code	2 — lint-error (ambient)	Part 11: The FE↔BE Mirror
`liftmere/no-uistate-screen-prop`	parallel `uiState` prop on a screen	2 — lint-error	Part 11: The FE↔BE Mirror
`liftmere/no-null-suspense-fallback`	blank first paint in the router	2 — lint-error	Part 11: The FE↔BE Mirror
`liftmere/no-smart-quotes`	curly quotes in TS string literals	2 — lint-error (ambient)	Part 1: The Drift Problem
`liftmere/no-direct-event-log-append`	raw event-log writes outside the sanctioned writer	2 — lint-error	Part 8: Projected Truth
`buf lint`	proto contract stays well-formed	2 — lint-error	Part 11: The FE↔BE Mirror
`make check-vocab`	committed `.gen.go` drifts from its YAML manifest	3 — CI script	Parts 3–6
`make check-sqlc`	generated DB models drift from hand-authored SQL	3 — CI script	Part 7: Models at Boundaries
`make check-mocks`	generated mocks drift from their interfaces	3 — CI script	Part 12: Testing Without Drift
`check-connect-errors`	`connect.NewError` called outside the error adapter	3 — CI script	Part 5: The Error Manifest
`check-sql-scope`	owner-scoped table queried without a `user_id` filter	3 — CI script	Part 7: Models at Boundaries
`check-migrations.sh`	migration file edited after applied	3 — CI script	Part 8: Projected Truth
`generate-features --check`	committed feature registry is stale	3 — CI script	Part 11: The FE↔BE Mirror
`defineMcpServerContract`	MCP tool surface diverges from the operations registry	3 — contract test	Part 9: One Operation, Three Interfaces
`make agents-check`	rendered agent file diverges from its manifest	3 — CI script	Part 10: The Agent OS
`rebuild-from-log`	any projection is reproducible from the event log	recoverable	Part 8: Projected Truth
`liftmere/no-fixture-outside-route` (burndown)	~113 remaining violations	4 — warn (scoreboard)	Part 12: Testing Without Drift

No single one of these is clever. Together they are the difference between “we have a convention” and “the convention is true.” Each removes a coherence check a human would otherwise perform by eye — and each is the reason a large, AI-generated diff can be trusted instead of re-audited.

The ladder keeps it honest

Not every rule sits at the same strength, and pretending otherwise would itself be drift — between what a doc claims and what the build enforces. So every guardrail carries a tier on a shared :

1  compile-enforced   the compiler/type system catches it — cannot ship
2  lint-error         a rule at error — PR fails CI
3  coverage-script    a CI script fails on a missing pairing or forbidden diff
4  warn (scoreboard)  reported, non-blocking, during a burndown to zero
5  convention         documented but unenforced — a known gap, a future target

The tier tells you the real status of a rule at a glance. A sub-system at tier 5 is honest about being a wish; one at tier 1 cannot be violated. The frontend mostly lives at tiers 1–2; the backend has a genuinely-gated core and a set of sub-systems still climbing from convention toward a wired linter. The point of the ladder is not to claim everything is enforced — it is to make the gaps legible so they can be closed on purpose.

When the gate fires

Strength is one axis; timing is the other. A gate runs at some point in the life of a change — and the earlier it fires, the cheaper the failure.

The timing axis of the wall — conceptual, not measured. The earlier a gate fires, the cheaper the failure it catches.

The same gate is a different cost at each tier. A migration mistake refused on git commit costs the developer ten seconds; the same mistake caught at runtime is an incident. So the wall is not only a set of rules — it is a set of rules placed as early as each one can run.

The earliest tier is the pre-commit subsystem: a handful of hooks that fire on every commit, before code reaches CI — a secret scan, buf lint, migration discipline, the connect.NewError boundary check, the owner-scope check. Several of them appear in the wall above and run again in CI on purpose: the commit-time copy exists for the feedback loop, the CI copy for the guarantee, so bypassing local hooks still gets caught at the PR. The full commit-time tier — every hook and why it earns its place at the front — is its own reference: Commit-time gates.

A gate’s value is inseparable from when it fires. Move the check as early as it can run, and the expensive version of the failure never happens.

So — are we drifting?

On every layer where a gate runs: no, structurally. A value cannot exist on one side that another side has not heard of. A generated file cannot disagree with its manifest. A handler cannot diverge from its contract. An agent cannot behave differently across frameworks. A projection cannot win an argument with the event log. Those are not promises maintained by discipline; they are properties maintained by the build, on every PR, by machines rather than memory.

On the layers where a gate does not yet run: maybe — and we know exactly where. That is what the ladder has been tracking the whole way, and what the next section builds on.

Where this goes next

Here is the frontier the whole pattern points at — the next set of seams that want to become one source with many projections and a gate.

The capstone: a frontend form and its backend validation from one manifest. This is the unbuilt piece the pattern keeps pointing at — the one place where the shape exists in every adjacent layer but has not yet been closed. The plumbing is already there — operation inputs are Zod schemas, zod-to-json-schema is in use, the vocabularies generate validators — and the natural extension is to generate a form and its server-side validation from a single declaration. When that lands, the tightest FE↔BE seam there is — “what may the user submit, and what will the server accept?” — becomes one source with two projections and a gate. That is where this goes.
More vocabulary kinds. permission, route, and event are sketched in buildmere’s plugin contract, and bringing them under the same manifest is the next reach; permissions and routes are governed by other means today.
More language emitters. The error kind emits Go; a TypeScript emitter generates the frontend’s error constants and closes the Part 5: The Error Manifest coupling completely. The same move applies to a metric TypeScript emitter.
buf breaking as a blocking gate. The rule is configured; wiring it to fail CI while the proto is mid-rename is the next turn of the ratchet.
Production observability. Config declares an OTLP endpoint, and the direction is full production OTLP with real spans built on top of the first tracing cut.
A devportal-state CLI fallback and a pair of platform adapters (AGENTS.md, a Cursor _platform.mdc) extend the agent-OS pattern to the next surfaces.

Why this works now

Step back to where Part 1: The Drift Problem started. Two forces make this the right architecture for this moment, not just good hygiene.

The rails unlock velocity. When writing code and recalling patterns are cheap, the scarce resource is coherence. The gates above are what let you accept a large generated diff and trust it, because every way it could drift is a way the build refuses. The speed is not the typing — it is the not-having-to-recheck.

And the rails got cheap to build. The old reason this kind of governance was rare is that a manifest system, a custom linter, a codegen kernel, an event-projection plane were expensive to build and maintain. The same economics that made generation cheap collapsed that cost: a new vocabulary kind, a new lint rule, a new gate is now an afternoon. The force that created the drift problem is the one that funds the cure.

Constraints are not the brake on cheap generation. They are what makes it safe to trust — and trust is what lets you go fast. “Governance is expensive” is an old-world assumption that no longer holds.

The question is permanent

“Are we drifting?” is not a question you answer once. It is asked continuously — by check-vocab on every commit, by the contract test on every MCP boot, by agents-check on every sync, by the compiler on every build. The work was never to answer it by hand. The work was to build the gates that ask it for you, forever, and to be honest about the few places they do not run yet.

Define the concept once. Generate the rest. Let the gates keep them honest. That is the pattern — and as the system grows, each new layer joins the same shape. This corpus grows with it: the question does not change, the gates keep answering it, and new parts land as new seams come under the same discipline.

Are We Drifting? — Part 13: AI Output Is Untrusted Input

Sun, 14 Jun 2026 00:00:00 GMT

Are We Drifting? — Part 13: AI Output Is Untrusted Input

This series has been about keeping representations of a concept from drifting apart. A language model is the most enthusiastic drift generator you can plug in: ask it for a status and it may invent one; ask it for a number and it may send a string; ask it for JSON and it may return almost JSON. This part is about putting it behind the same kind of gate as everything else.

Are we drifting here?

The instinct is to treat a model’s output as data, because it looks like data. It is not. It is a suggestion shaped like data, produced by a process with no obligation to your types.

So it drifts in every direction at once. It returns "Done" when your enum is ready. It collapses a nested object into a string. It hallucinates a field. It emits a difficulty of "very hard" when the allowed set is beginner | intermediate | advanced. None of this is a bug in the model — it is the model doing exactly what it does. The bug is letting that output into your system unchecked, where it becomes a row, an event, a decision — a piece of drift with a long half-life.

The question is the one you would ask of any external system: is this untrusted shape forced to conform to a contract before it crosses the boundary, or is it trusted on sight?

The principle: a model is a boundary, like any other

You already have a discipline for untrusted input. A web form is validated before it becomes a command. A third-party API’s response is mapped to your own model at the adapter and never leaked past it. A model is the same kind of boundary, and gets the same treatment:

Declare the expected output shape — as a schema, not a hope.
Communicate the shape to the model — via structured-output / JSON-Schema constraints.
Validate the response against the shape.
On failure, retry with the validation error as feedback — bounded to a couple of attempts.
Surface a clean typed value, or a normal application error — never a raw, half-valid blob.

The frontend has done this for years: a Zod schema validates an untrusted shape at the edge before it is allowed in. The same idea in Go is a schema-tagged struct plus JSON-Schema generation plus validation plus a retry loop. Different language, identical rule:

Untrusted shapes must conform to a declared contract before they cross the boundary. A model is untrusted. Validate it like a form, isolate it like a vendor.

Here is how the boundary works. The raw provider types — the OpenAI or Anthropic response objects — stop at the adapter. The application talks to a typed interface (Summarize(ctx, input) (domain.WorkoutSummary, error)) and receives a validated domain value or a clean error. A schema mismatch is a breaking change, not a runtime surprise.

The vocabularies become the model’s contract

Here is where the series closes a loop.

The single most effective way to stop a model from inventing a value is to give it the closed set to choose from. And the closed set already exists — it is the enum vocabulary from Part 4: Enums as Shared Vocabulary.

The same manifest that generated the Go constants, the TypeScript union, and the SQL CHECK constraint can generate the enum constraint in the JSON Schema sent to the model. So the model is handed exactly the set of wire values the rest of the system recognizes, and structured-output enforcement makes a value outside that set impossible to return. Then validation on the way back checks membership against the same generated IsValid() — and because the model was constrained by the manifest and validated against the manifest, a value it returns is, by construction, a value every other layer already agrees about.

The vocabulary that prevented drift between your database and your frontend now prevents drift between your model and your database. One source; one more projection; the boundary gated the same way.

The concrete version: VideoStatus is declared once in the manifest with five wire values — uploading, processing, ready, failed, archived — and every layer gets that same closed set derived from it.

The JSON Schema fragment that goes to the model is generated from the same manifest:

{
  "VideoStatus": {
    "type": "string",
    "enum": ["uploading", "processing", "ready", "failed", "archived"]
  }
}

The model cannot return "done" or "in_progress" or "complete" — the structured-output constraint refuses it before the response even arrives. Then IsValid() on the way back in checks membership against the same five values, so what reaches the domain layer is a VideoStatus that every other layer — Go, TypeScript, SQL — was generated to agree with.

And when the model does fail validation, that failure is itself a declared thing — an entry in the error vocabulary from Part 5: The Error Manifest (AI_STRUCTURED_OUTPUT_INVALID, retryable), normalized at the adapter exactly like a billing provider’s failure. The unhappy path of the AI boundary is governed by the same manifest as every other failure.

The velocity payoff

The check this removes is the one teams skip until it burns them: did the model actually return the shape I assumed, with values my system recognizes?

When the model is constrained by a generated schema and validated against the same vocabulary, you can let it produce structured data and trust the result — not because the model is reliable, but because the boundary is. Invalid output is rejected and retried; what reaches your domain is a typed value drawn from sets the rest of the stack already shares. The model becomes a normal, gated input source, which means you can build on it at the speed you build on a form — instead of treating every AI feature as a fragile special case to be hand-audited.

What’s next

Part 14: The Wall of Gates and What Comes Next collects the full wall of drift gates the series has walked past, asks the title question one last time, and is specific about where the work goes next.

Are We Drifting? — Part 12: Testing Without Drift

Sat, 13 Jun 2026 00:00:00 GMT

Are We Drifting? — Part 12: Testing Without Drift

A test suite is supposed to be the thing that catches drift. But tests are code too, and they have their own way of drifting — away from the production they claim to verify. This part is about keeping the test world honest.

Are we drifting here?

The most dangerous test is the one that is green and wrong.

It happens whenever a test asserts against a copy of reality that has drifted. A repository test runs against a mocked database and passes — while the real migration it depends on is broken, so production fails on the exact path the test “covered.” A screen test renders hand-built sample data that no longer looks like any real product state, so it passes while the actual empty-state crashes. A test depends on time.Now() and is flaky at midnight.

In each case the suite is green and the system is broken, because the test drifted from the thing it was meant to mirror. So the question for testing is: do the tests still resemble production — or have they drifted into a comfortable fiction?

Fixtures are a vocabulary of product states

The frontend’s answer starts from the same primitive as everything else in this series: a closed, canonical set, declared once, shared everywhere.

Fixtures are not throwaway sample data. They are the canonical vocabulary of product states — regular, empty, loaded, and the loading/error arms when a screen has them — defined once per feature with defineFixtures, and shared by Storybook, the screen test, the route’s initial state, QA, and AI prototyping. One set of states, consumed by every surface.

That sharing is the anti-drift mechanism. Because the Storybook story, the test, and the running route all seed from the same fixtures, a story cannot depict a state the test never checks, and neither can drift from the shape the route actually renders. And a governed rule (FE-1) keeps the vocabulary from leaking: screens may never import fixtures — only routes, stories, and tests may — enforced by a lint rule, so the seam is structural. It is the same move as the backend’s table-driven tests, where each case names a domain state (valid input, missing field, not-found, conflict) and the set of named cases is the spec.

Fixtures are product states, not test data. When the same named states feed the workbench, the tests, QA, and the live route, the test world cannot drift from the product world.

Real infrastructure for the data layer

The backend’s hardest-won rule is blunt: the repository is tested against a real Postgres — a container — never a mock.

The reason is a scar. Mocked repository tests once passed green while the migration they relied on failed in production. A mock of a database is a copy of your beliefs about the database, and beliefs drift from schemas. So adapter-level tests run against real Postgres (and real MinIO, real queues) in an isolated, throwaway container, behind a build tag so they are opt-in locally and required in CI.

There is a clean division of labor that keeps this from becoming “test everything against everything”:

Fakes verify application behavior.        (fast, in-memory, deterministic)
Real containers verify adapter behavior.  (does the SQL actually run? does the constraint fire?)
Each level verifies what only it can.     (do not duplicate coverage)

A fake repository is the right tool to test a service’s logic — it is fast and controllable. A real Postgres is the only tool that can tell you the query and the migration and the constraint actually work, because those are the parts a mock can only pretend to have. Test the logic against fakes; test the adapter against the real thing; do not make either re-verify the other.

So across both stacks, the answer to “are we drifting here?” is not “probably not” — it is a set of named gates that each refuse a specific known failure mode.

On the frontend, the first gate is liftmere/no-fixture-outside-route (tools/eslint-no-fixture-outside-route.mjs), which exists because screens pulling fixtures in directly breaks the shared-vocabulary seam — it is a lint error, not a convention. The second is check-fixture-registry-coverage.mjs (apps/client/scripts/), which catches collections that were defined but never registered, making them invisible to App Mode’s preset injection and therefore untestable by anyone who doesn’t know to look.

The third gate has a specific story behind it.

A plate-calculation bug once passed every unit test and failed in the live dev app because it involved a setState-during-render that only surfaces when React runs in StrictMode — which double-invokes effects in development to expose exactly this class of mistake. The unit tests did not see it because they bypassed the <StrictMode> wrapper by importing directly from @testing-library/react. So we added a no-restricted-imports rule on test files: import from ~test-utils instead, which wraps the renderer in <StrictMode> automatically. The bug can no longer pass a test that would have missed it.

A test that does not run in StrictMode is not testing what the development app runs. The gate makes the test environment and the live environment agree.

On the backend, the integration-test gate exists for the same reason as the real-Postgres rule: a mocked repository cannot lie to you in a way a real migration will catch. Adapter-level tests run under a //go:build integration tag and are invoked via make test-be-integration (go test -tags=integration -race ./...), which also enables the race detector — so the gate is both a correctness check on the SQL and a concurrency check on the adapter code.

The final gate is check-mocks, which runs in CI to verify that mockgen-produced fakes still match the interfaces they were generated from. When an interface changes, the mock changes too, or the build fails. An interface and its mock cannot silently diverge.

The five gates, in one place

Drift mode	Named gate	What it catches
Fixture imported by a screen	`liftmere/no-fixture-outside-route` (`tools/eslint-no-fixture-outside-route.mjs`)	Screens, flows, runtimes pulling fixtures in directly, breaking the shared-vocabulary seam
A `defineFixtures` collection not in the registry	`check-fixture-registry-coverage.mjs` (`apps/client/scripts/`)	Collections that exist but are invisible to App Mode preset injection
Effect-lifecycle bug that only shows in dev	`no-restricted-imports` of `@testing-library/react` — import from `~test-utils` instead	Bypassing the `<StrictMode>` wrapper that double-invokes effects; the motivating case was a plate-calc `setState`-during-render regression that passed unit tests but failed in the live dev app
Mocked repo that lies about the schema	`//go:build integration` + `make test-be-integration` (`go test -tags=integration -race ./...`)	Repo tests that pass against a mock while the real migration is broken — the scar this rule came from
Generated mock out of sync with its interface	`check-mocks`	`mockgen`-produced fakes that no longer match the interface they were generated from

Each gate fires in CI. None of them require a human to remember the rule.

Determinism: don’t let reality leak in

The last source of test drift is nondeterminism. A test that depends on the wall clock, a random ID, or ambient ordering passes and fails for reasons that have nothing to do with the code.

The discipline is to inject the nondeterministic things — time, ID generation, randomness — behind tiny interfaces, so a test supplies a fixed clock and a deterministic ID sequence. The same application, wired with a fake clock and seeded IDs, produces the same output every run. Combined with fakes for infrastructure, this is what lets a system-level harness exercise the real wiring of the app — real services, real flow — against fake, deterministic edges. The test runs the production code path; only the world at the edges is controlled.

The velocity payoff

The check this removes is the one you only discover you skipped when production breaks: does this test actually correspond to the real system, or to a copy that has wandered?

When fixtures are shared product states, a passing screen test means the workbench, QA, and the route all agree about that state — you do not re-author sample data per surface, and you trust the green. When the data layer is tested against a real database, a passing repo test means the SQL and the migration genuinely work — you are not shipping on a belief. When time and IDs are injected, a green run means the logic is right, not that you got lucky with the clock.

That trust is, once again, the velocity. A suite you can believe is one you can move behind quickly; a suite full of comfortable fictions is one you have to re-verify by hand, which is the coherence tax this whole series is about removing.

And the infrastructure that buys this trust — fixtures-as-vocabulary, throwaway testcontainers, the FE-1 gate — is cheap to stand up now, while the surface area is small, and only gets more expensive to retrofit as the system grows.

What’s next

There is one boundary left that drifts harder than any database: a language model, which will cheerfully invent a value, a type, or a malformed shape. Part 13: AI Output Is Untrusted Input treats AI output as exactly what it is — untrusted input — and shows how the vocabularies from earlier parts become the contract a model is forced to conform to.

Are We Drifting? — Part 11: The FE↔BE Mirror

Fri, 12 Jun 2026 00:00:00 GMT

Are We Drifting? — Part 11: The FE↔BE Mirror

The series has found one shape governing values, models, state, operations, and agents. This part turns it on the largest seam of all — the one between the frontend and the backend — and shows that even the way the two stacks are governed is the same shape, mirrored.

Are we drifting here?

Frontend and backend are usually built by different people, in different languages, with different instincts. Left alone, their governance drifts as surely as their code: the frontend grows a rich culture of lint rules and structural conventions; the backend grows a different one; and an engineer who knows one stack arrives at the other as a stranger. The monorepo becomes two philosophies sharing a git remote.

So the question here is not about a single value or model. It is: do the two halves of the product share one model of what “governed” means — or two?

The shared model: a Governed Sub-System

Both stacks are built on the same unit. Every load-bearing architectural rule is a Governed Sub-System (GSS) — a triple:

Structure — the canonical shape (a folder/file/type/proto convention) that names the right answer.
Enforcement — the load-bearing leg: a compile check, a lint rule, or a coverage script that fails the build. Without it, the structure is a wish.
Documentation — one canonical page.

This is the same source → projection → gate idea, applied to architecture itself: the structure is the declared intent, the enforcement is the gate, the doc is the human-readable projection. Both stacks also share a maturity ladder — compile-enforced → lint-error → coverage-script → warn (scoreboard) → convention — so every rule’s real status is legible, not assumed. And both prefer guardrails that are opt-in by structure: the rule self-targets by a convention and stays dormant until you adopt the shape.

The mirror, row by row

Here is the coupling made literal. Each row is one governance concept; the cells are how each stack instantiates it.

Governance concept	Frontend	Backend
Layering & responsibility	Feature Layering — Screen / Route / Controller / Flow / Runtime	Domain Layering — handler/repo co-located per domain, no cross-domain imports
Data-source seam	Controller / Data-source seam (`controller.{fixtures,local,db}`)	Repo Interface Seam — handler depends on a repo interface, not `pgx`
Exhaustive outcomes	UI State System — `matchState` over `ScreenState` (compile + lint)	Typed Error Model — `connect.NewError` codes, no bare `fmt.Errorf` from a handler
No raw values / single source	Design Tokens — semantic tokens, no raw `oklch`/hex	Structured Observability — key-value `slog`, no string interpolation
Generated indirection	feature registry — `generate-features` → `features.generated.ts` (`--check`)	Contract Integrity (`buf`) + generated-interface compile assertion
Canonical test data	Fixture Discipline (FE-1) — `defineFixtures` + registry	Migration Discipline — append-only `*.sql` + real-Postgres repo tests

Read any row left-to-right and the same idea appears in two dialects. “Exhaustively handle every outcome” is matchState on the frontend and a typed error model on the backend. “Never write a raw value; use the single source” is design tokens on the frontend and structured slog on the backend. The concepts are coupled by design — which is what lets someone who has internalized one stack read the other.

Where the mirror doesn’t hold

A forced mirror would itself be a drift between the docs and reality, so the asymmetries are part of the map:

Frontend-only. The rendering guardrails — rich skeletons, motion tokens, design tokens as pixels, the icon catalog — and the Storybook + Playwright workbench have no backend analogue. The backend has no rendering surface and no “agent eyes” to screenshot.
Backend-only. Contract Integrity, Migration Discipline, and Middleware Centralization are backend realities (a wire contract, append-only schema, central HTTP middleware) with only a thin frontend echo.
Enforcement depth differs, for a real reason. The frontend runs many custom ESLint rules because ESLint is file-granular and syntactic — cheap and precise to extend. The backend leans on buf, the compiler, and a growing wall of CI scripts (check-vocab, check-mocks, check-sqlc, check-sql-scope, check-connect-errors, migration checks) because Go’s equivalents are package-granular and often need type information — closer to a day of work than an hour. So a few backend rules are CI scripts or partly lean on review where the frontend would have a bespoke linter.

The mirror is a design goal, not a straitjacket. Naming the — cells keeps the map true to the territory.

One screen, six guardrails

The abstract case for governance is easy to nod along to. Here is the concrete one — a single frontend screen, before, with six independent drift modes, each the kind of thing that slips through review:

// BEFORE — six latent drift modes in one file
import { coachRosterFixtures } from './screen.fixtures'   // FE-1: fixture imported into a screen
export function CoachRosterScreen({ state, uiState }) {    // a parallel uiState prop
  return (
    <div style={{ background: '#0f0f17' }}>                // a raw hex color
      {matchState(state, {
        loading: () => <div className="lm-skeleton" />,    // an anonymous loading bar
        ready: (s) => <Rows data={s.data} />,
        // missing empty + error arms                      // a non-exhaustive match
      })}
    </div>
  )
}
// <Suspense fallback={null}>                              // a blank first paint

Six drift modes. Six named rules. Each one is a lint error or compile failure — not a code-review note:

Drift mode	Rule	Tier
Fixture imported into a screen	`liftmere/no-fixture-outside-route`	lint-error
Parallel `uiState` prop on a screen	`liftmere/no-uistate-screen-prop`	lint-error
Raw hex color `#0f0f17` in component code	`liftmere/no-raw-hex-color`	lint-error (ambient)
Anonymous skeleton div (no `skeleton.tsx`)	`skeleton-composition` rule	lint-error (opt-in)
Non-exhaustive `matchState` (missing arms)	TypeScript exhaustiveness check	compile-enforced
`<Suspense fallback={null}>` in router	`liftmere/no-null-suspense-fallback`	lint-error

The after version is not “tidier by convention” — it is the only version that compiles and lints. Six coherence checks a reviewer would otherwise have to perform by eye, performed by the build instead.

The backend’s equivalent table:

Drift mode	Rule	Tier
Handler drifts from generated interface	`var _ ServiceHandler = (*Service)(nil)`	compile-enforced
Proto contract breaks without escalation	`buf lint`	lint-error (CI)
`connect.NewError` called outside the error adapter	`check-connect-errors`	CI script
Generated DB models drift from SQL	`make check-sqlc`	CI script
Generated mocks drift from interfaces	`make check-mocks`	CI script
Vocabulary `.gen.go` drifts from YAML manifest	`make check-vocab`	CI script
Migration file edited after applied	`check-migrations.sh`	CI script

That is the whole argument of the series in two tables: the structure plus the gate is what lets a large, AI-generated diff be trusted, because the ways it could drift are the ways the build already refuses — on both stacks.

The velocity payoff

The check this removes operates at the level of people: the cost of every engineer (and every agent) having to learn two unrelated governance cultures, and the cost of reviewers manually enforcing consistency on both.

A shared model collapses that. Learn the GSS triple and the maturity ladder once, and both stacks are legible. An agent briefed on “structure + enforcement + one doc” applies it on either side. And the matrix itself is governed like everything else — adding a new sub-system on either stack adds a row as its final step, so the cross-stack map cannot silently drift from the rules it describes.

What’s next

The next parts turn to testing — how fixtures, fakes, and real-Postgres containers keep tests from drifting away from production — then to AI output as an untrusted boundary, and to a running inventory of the wall of gates and where the pattern goes next.

Are We Drifting? — Part 10: The Agent OS

Thu, 11 Jun 2026 00:00:00 GMT

Are We Drifting? — Part 10: The Agent OS

Part 9: One Operation, Three Interfaces projected one operation onto three transports. This part does the same thing one altitude higher: it projects one agent onto every AI framework that runs it — and keeps the fleet’s shared knowledge from forking.

Are we drifting here?

Agents are now contributors. They have roles, instructions, tools, and tiers. And those roles have to exist in more than one place: Claude Code wants an agent file with its frontmatter shape; Cursor wants a rule file with a different frontmatter shape; the docs want a human-readable page describing each role.

Hand-maintain those and you have the oldest drift in the book. Someone tightens an agent’s instructions in the Claude file and forgets the Cursor rule. The docs describe a tool the agent no longer has. The same “principal architect” behaves like two different colleagues depending on which tool you opened. Worse, the shared behavior — how juniors commit, how principals review — gets copy-pasted into every agent and then edited in some but not others, so the fleet’s common knowledge quietly forks.

The question is the series’ question, pointed at the agents themselves: is each role one definition, or many copies pretending to be one?

One source

Every agent is one folder with one canonical manifest.json (plus a hand-authored prompt.md, and an optional composition of shared role-blocks). That manifest is the single definition of the role: its name, description, tools, tier, and which shared behaviors it composes.

Shared behavior lives in role-blocks — fragments like principal/advisory-scope, principal/review-checklist, base/commit-skill-pointer — that many agents pull in by reference. An agent’s assembled prompt is its own prompt.md spliced into the ordered blocks it composes. Change a role-block once, and every agent that composes it changes with it. That is the “shared knowledge mesh”: common discipline declared in one place, woven into many roles, never copy-pasted.

Many projections

A package (agent-registry) walks the manifests and renders each through every registered adapter:

Adapter	Destination	Render shape
`claude`	`.claude/agents/<name>.md`	Claude Code frontmatter + a pointer to the canonical prompt
`cursor`	`.cursor/rules/<name>.mdc`	Cursor frontmatter + a reference to the canonical prompt
`docs-role`	the agent’s `role.mdx`	a Docusaurus role page
`docs-table`	the registry table	one row per agent

The adapters exist because the frameworks genuinely differ — Claude Code needs name/tools/model, Cursor needs globs/alwaysApply — which is exactly why you cannot symlink one file and call it done. Each framework gets the shape it expects, all from one manifest.

The render loop is idempotent: it reads the existing destination, renders fresh content, and only writes if the bytes differ. Running it is a no-op when nothing changed — which is what makes the next part (the gate) clean.

Provider-agnostic tiers: name and wire, again

Here is the name/wire split from the very first vocabulary, reappearing at the top of the stack.

Every model-driven agent carries a tier — E1, E2, E3 — not a model name. The tier is the canonical identity. A separate agent-runtime.json resolves a tier to a concrete model (Claude Sonnet, an OpenAI model, whatever) at dispatch time. The tier is the name; the concrete model is the wire form; the binding is deferred and declared in one place.

So “what model does the principal architect use?” has the same answer-shape as “what string does Ready serialize to?” — it is a resolved projection of a declared identity, not a literal scattered across nineteen files. Swap the model behind E2 and every E2 agent moves together, across every provider, without touching a single agent manifest.

The drift gate

The render loop has a check mode. make agents-check runs the adapters in dry-run and exits non-zero if any destination differs from what its manifest would generate. It runs in CI.

So a .claude/agents/*.md that was hand-edited, a Cursor rule left stale after a manifest change, an assembled prompt that was never regenerated after a role-block edit — each fails the build. The only way to change how an agent behaves in any framework is to change the manifest or a role-block and re-run the sync. One source, many rendered projections, a gate that refuses drift between them. The exact shape of Part 3: buildmere, a Codegen Kernel, applied to the colleagues instead of the code.

There are four failure modes the gate is built to catch, and each one tells you something about where the real discipline lives:

Symptom	What drifted	Fix
`.claude/agents/<name>.md` body is stale	Manifest or role-block changed; sync not re-run	`make sync-agents`
`prompt.assembled.md` missing	`composition` key added; `make sync-agents` never re-run	`make sync-agents`
Orphaned `.claude/agents/<name>.md`	Agent folder deleted without pruning	`make sync-agents PRUNE=1`
Cursor rule out of sync	`.cursor/rules/<name>.mdc` hand-edited after manifest change	`make sync-agents`

Every row in our failure-mode table ends the same way: make sync-agents. The fix for drift is to regenerate, never to hand-patch — and that single recovery path is itself the point.

That is the point of idempotency — the fix is always the same command, because the sync is always a deterministic function of the manifests.

The section above named four adapters because four is what the system conceptually does — assemble, emit to Claude, emit to Cursor, produce docs. The registry runs six:

Adapter	Destination
`prompt-assembler`	`<agent>/prompt.assembled.md`
`claude`	`.claude/agents/<name>.md`
`cursor`	`.cursor/rules/<name>.mdc`
`docs-role`	`<agent>/role.mdx`
`agent-category`	`<agent>/_category_.json`
`docs-table`	`apps/docs/docs/ai/agents/agent-definitions.mdx`

agent-category and docs-table are the quiet infrastructure that makes the docs self-maintaining — every agent that gets a manifest gets a Docusaurus sidebar entry and a registry row, automatically, without a docs PR.

Scaffolding a new agent is two commands:

make agents-new NAME=<kebab-case-name>
# → apps/docs/docs/ai/agents/<name>/{manifest.json, prompt.md}
make sync-agents
# → .claude/agents/<name>.md, .cursor/rules/<name>.mdc, role.mdx, _category_.json, registry row

Write the manifest and the prompt, run the sync, and the agent exists in every framework simultaneously.

The gate won’t pass until the sync has run — which means you cannot forget the sync and ship anyway. The broken CI is the reminder.

The next adapters extend the same registry to two more destinations: agents-md-platform.mjs (root AGENTS.md) and cursor-rules-platform.mjs (.cursor/rules/_platform.mdc). Today AGENTS.md is a pointer file, and the platform layer is where this goes next: every existing agent renders into those destinations for free — adding a new framework adapter is a new file and a registration line, not a sweep across nineteen manifests.

The velocity payoff

The check this removes is “are all the framework copies of this role still saying the same thing?” — multiplied by nineteen agents and two skills, across two frameworks, plus docs.

Declaring the role once collapses that to a single edit. Improve a principal’s review checklist in one role-block; every principal in every framework updates, and agents-check proves they did. Onboard a new framework by writing one adapter, and every existing agent renders into it for free. Re-point a tier at a better model in one file, and the whole fleet follows.

This is the deepest expression of the economic inversion from Part 1: The Drift Problem: the contributors themselves are governed by a manifest, so improving how the whole fleet works is a one-line change with a gate behind it — not a careful, error-prone sweep across every tool’s idea of every role.

What’s next

We have now found the same shape governing values, models, state, operations, and agents. Part 11: The FE↔BE Mirror holds the two halves of the product up against each other — frontend and backend — and shows that even the governance itself is mirrored, with the asymmetries named honestly.

Are We Drifting? — Part 9: One Operation, Three Interfaces

Wed, 10 Jun 2026 00:00:00 GMT

Are We Drifting? — Part 9: One Operation, Three Interfaces

The data parts are behind us. The shape is not. Parts 2–8 showed one source → many projections → drift gates governing values, models, and state. Now watch it govern behavior — the operations a service exposes.

The same shape, at the operations layer: one handler, three transports, one contract test.

Are we drifting here?

A modern backend capability has at least three audiences:

the app, which wants a REST endpoint;
agents, which want an MCP tool they can discover and call;
humans (and a fallback for when MCP is flaky), who want a CLI command.

The lazy version writes three surfaces. A REST handler here, an MCP tool registration there, a CLI subcommand somewhere else — each with its own copy of the input shape, its own validation, its own idea of what the operation is called.

Then they drift. A field is added to the REST body but not the MCP tool’s schema. A new operation ships as an MCP tool but was never wired into REST, so the app cannot reach it and it never appears in the operation listing. The CLI validates differently from the server. Three faces of one capability, slowly disagreeing about what the capability is.

One source

The fix is to define the operation once — its input schema, its output schema, and its handler — and treat every transport as a projection of that one definition. Our op-server package does exactly this:

defineOperation({
  name: 'run.record',
  input: RunRecordInput,    // a Zod schema
  output: RunStateSchema,   // a Zod schema
  handler: async (ctx) => { /* the one implementation */ },
})

The operation is the source. The input and output are schemas, not prose — the same “validation is declared, not hand-written” move from the config part, now at the boundary of an operation.

Many projections

A service collects its operations into one registry, and the transports are plugins that consume that same array:

createOpServer({ operations })       // the registry
createRestPlugin({ /* … */ })        // → REST endpoints
createMcpServer({ /* … */ })         // → MCP tools
// + a CLI plugin                     // → CLI commands

REST and MCP both read the same operations. There is one handler behind all three faces. This is what “all tools are MCP-driven” means in practice: every backlog and devportal-state operation is automatically an MCP tool because it is in the registry — agents reach the repo’s live state through the very same operations the app calls over REST and a human calls from the terminal. You do not build an MCP surface; you declare operations, and the MCP surface is a projection of them.

A consequence worth stating: a tool registered only on one transport can never be reached on the others, and won’t appear in the registry’s own operations.list introspection. The single registry is what keeps the three faces from being three different APIs.

The drift gate: a contract test against the real SDK

Here is the gate, and it is a good one because it was paid for in production.

op-server ships a test contract — defineMcpServerContract — that boots the real MCP server against the live SDK and asserts that the registered tool surface matches the operations registry exactly. Every operation’s input is run through the same extractShape the server uses, so the SDK receives a proper schema. A tool that was hand-registered outside the registry shows up as an “extra” and fails the test. An operation whose schema the SDK would reject fails here, at unit-test time, instead of at boot.

Why this specific gate exists: hand-calling the SDK’s registerTool with a JSON-Schema-shaped object — instead of going through the registry — passes lint and type-check but crashes the SDK at boot, taking the entire MCP server down. That regression happened in production once (the devportal-state projection tool). So the rule is now structural and enforced:

Do not call registerTool directly. Add an entry to the operations registry and let the server register it. Living outside the registry means living outside the safety net.

The registry is the single source; the contract test is the gate that refuses any tool that tried to exist outside it. Same shape, again.

The three-interface picture has a fourth failure mode that only shows up in long Claude Code sessions: MCP is not bulletproof.

Tools disappear from the parent agent’s registry while subagents keep working.

A tool call hangs.

When that happens, the question is not whether the registry kept the three faces in sync — it did — but whether a CLI fallback exists so an agent can recover without restarting. The answer is not symmetric:

Operation surface	MCP transport	CLI fallback
Backlog ops (`backlog-mcp`)	`mcp__backlog__*` tools	`pnpm liftmere backlog ...` — every tool has an exact equivalent, same handlers, same events
Devportal-state ops (`devportal-state-mcp`)	`mcp__devportal_state__*` tools	None — recovery is `/mcp` reconnect or delegate to a subagent

The single registry guarantees the three transport faces agree on input shape. It does not guarantee all three transports exist for every operation.

A runbook that says “if MCP hangs, use the CLI” is correct for backlog operations and wrong for devportal-state operations.

That asymmetry is real: devportal-state has no CLI fallback today, so its recovery path is /mcp reconnect or delegation to a subagent. Where this goes next is parity — a CLI projection for devportal-state operations, so every operation has all three faces and the runbook holds everywhere.

The velocity payoff

The coherence check this removes is “did I update all three transports, and do they still agree?”

With operations as the source, you add a capability once. The moment it is in the registry it is a REST endpoint the app can call, an MCP tool an agent can discover, and a CLI command a human can run — with one validated input shape and one handler. You cannot ship the half-drifted state where a capability is reachable one way but not another, because the contract test boots the real surface and compares it to the registry.

That is a large multiplier for agentic work specifically: an agent gains a new ability the instant an operation is defined, and the ability it gains is provably the same one the app uses. No separate “expose this to the agent” step, no separate schema for the agent to drift against.

What’s next

If one operation can project onto three transports, one agent definition can project onto every AI tool that runs it. Part 10: The Agent OS climbs to the workflow layer: the Agent OS, where a single manifest becomes a Claude Code agent, a Cursor rule, and a provider-agnostic execution tier — kept in sync by the same kind of gate.

And because operation inputs are already Zod schemas, there is one more face waiting: a frontend form generated from an operation’s input schema. Where this goes next is the fourth projection — a frontend form generated from the same operation schema.

Are We Drifting? — Part 8: Projected Truth

Tue, 09 Jun 2026 00:00:00 GMT

Are We Drifting? — Part 8: Projected Truth

Part 7: Models at Boundaries named events as the boundary that records facts. This part is about what you can build once facts are the source of truth — and why it is the most complete answer to drift we have found.

Are we drifting here?

Every useful screen is backed by a read model: a denormalized, query-shaped view of state. A kanban board. A list of active runs. A roll-up of which pull requests touch which tickets.

A read model is, by definition, a copy of truth arranged for fast reading. And the first law of this series is that copies drift. The board says a ticket is in review; the underlying state moved on; a consumer that updates the board missed an event, or processed one twice, or crashed halfway. Now the view and reality disagree, and you are debugging which one is lying.

The usual fix is more careful update logic. That just makes the copy drift more slowly. The real fix is structural: make the copy disposable, so it can never win an argument with the truth.

Facts, not state

Start from the right source. A command can fail; an event already happened. So the durable record is not “the current state” — it is the append-only sequence of facts that produced the current state.

In our orchestration plane, that record is a literal append-only log: monthly JSONL files under .devportal/events/, written by a single sequencer so there is exactly one writer and one order. Every state change is a fact appended to it — run.recorded, pr.synced, review.summarized, ticket.transitioned, workspace.created. Each fact is validated against a Zod event schema before it is written, and those schemas are forward-only: you add new event kinds and new optional fields, you never rewrite the meaning of a fact already on disk. (That is the append-only discipline from the enum part, applied to history itself.)

Two properties make the log trustworthy as a source:

Single writer, one order. The sequencer is the only thing that appends, so there is a single, total order of facts — no last-write-wins races.
Idempotent appends. Each publisher mints an idempotency key, and the sequencer dedups on it, so a retried publish does not become a duplicate fact.

The log is the truth. Nothing else is.

Both append-only disciplines — the event log and the Zod schemas — have machine enforcement; neither relies on human care.

Drift scenario	Named gate	Tier
Code appends directly to `.devportal/events/` without going through the sequencer	`liftmere/no-direct-event-log-append` (ESLint, Node packages)	lint-error
A shipped SQL migration is edited, deleted, or renamed after it landed on `main`	`scripts/check-migrations.sh` — `git diff --diff-filter=MDR` vs. merge-base; runs in `make lint-migrations` → `make lint-be`	coverage-script + CI error
A SQL schema change breaks a running reader (DROP column, narrowed type, blocking constraint)	`scripts/squawk-migrations.sh` + `.squawk.toml` — extracts only the `-- +goose Up` section and lints it for backwards-compat	coverage-script + CI error

check-migrations.sh fails with: “Migration Discipline violation: shipped migration(s) were changed.”

The event-log rule and the migration gate enforce the same axiom from two directions: liftmere/no-direct-event-log-append keeps every write in-order through the one sequencer; check-migrations.sh keeps every schema change additive. Neither can be reset by “being more careful” — the CI job catches it or the build fails.

Projections are disposable views

Everything you read from is a projection of that log: a Postgres database whose tables (tickets, runs, prs, reviews, runners) are built by replaying the facts. Consumers — active-runs-projection, kanban-projection, parent-lifecycle-mirror — subscribe to the log through a shared consumer framework, read forward from a checkpoint, and fold each fact into their tables.

This is precisely the series’ shape, at the altitude of state-over-time:

the event log (append-only facts)   ->  the one source
Postgres projections (tables)        ->  many generated views
rebuild-from-log                     ->  the drift gate

A projection is never the truth. It is a view of the truth — the same sentence we used for generated code in Part 1: The Drift Problem, now about data. And because it is only a view, it carries no authority of its own.

Rebuild-from-log is the gate

Here is the part that makes drift recoverable instead of catastrophic.

Because every projection is a pure fold over the log, it can be dropped and rebuilt from the facts at any time. The devportal_state_db_rebuildFromLog operation, run in full or incremental mode, hydrates the projection database from disk — a full rebuild from the start of history, or an incremental catch-up from a checkpoint.

That single capability changes the failure mode completely. When a projection and the log disagree, you do not investigate which is right. The log is right, by definition; you rebuild the projection and the disagreement is gone. A corrupted read model is not a data-loss incident — it is a re-run. The consumer framework keeps durable checkpoints (consumer.offset_committed is itself a fact in the log), and distinguishes those from ephemeral liveness signals like heartbeats, so a restart resumes exactly where it left off without replaying what it already folded.

Drift between truth and its views is not prevented here so much as made cheap to erase. Which, for a copy, is the strongest guarantee there is.

The velocity payoff

The check this removes is the one that haunts every cache and read model: is this view actually consistent with reality, and if not, how do I fix it without losing data?

When the view is a rebuildable projection, that question stops being scary. You can:

Add a new read model for free. A new screen needs a new shape? Write a new consumer that folds the existing log into it, and replay history into the new projection. No backfill migration, no “where do I get the historical data” — the history is the log. Standing up a new projection is a replay, not a migration project: the economics invert, and a read model that used to cost a schema change plus a data backfill now costs the time it takes to fold the log.
Change a projection’s shape without fear. Reshape the table, drop it, rebuild. The facts are untouched.
Recover from a bad deploy by replaying, not by archaeology.

New views become cheap because truth is one append-only log rather than N mutable tables you must keep mutually consistent by hand. That is the velocity unlock from Part 1: The Drift Problem in its purest form: the structure (an append-only log of validated facts) makes a whole class of expensive coherence work — keeping every read model in sync with reality — simply disappear.

Where the boundary sits

This pattern governs our orchestration plane — runs, tickets, reviews, the devportal’s view of the fleet. It is the right tool there because that domain is intrinsically a stream of events about work happening over time.

It is not how the product’s own data works. Workouts, programs, and media are classic CRUD over Postgres, accessed through the repo seam from Part 7: Models at Boundaries — no event sourcing, because that domain does not need replayable history to do its job. Using the heavier pattern everywhere would be its own kind of drift: architecture that has wandered away from what the domain actually requires. We apply projected truth where facts-over-time is the domain, and plain storage where it is not.

What’s next

We have now seen one source → many projections → drift gates applied to values, models, and state-over-time. The next three parts climb out of the data layer entirely and find the exact same shape governing operations, agents, and the FE↔BE mirror. Part 9: One Operation, Three Interfaces starts with operations: one handler, defined once, exposed as REST, MCP, and CLI at the same time.

Are We Drifting? — Part 7: Models at Boundaries

Mon, 08 Jun 2026 00:00:00 GMT

Are We Drifting? — Part 7: Models at Boundaries

The vocabularies arc was about closed values. This part is about closed models — and the most expensive drift of all, the kind where two whole layers fuse into one and can no longer move independently.

Are we drifting here?

There is a tempting shortcut in every backend: define one Project (or Workout, or User) struct, and use it everywhere. The database reads and writes it. The API serializes it. The domain logic mutates it. The event payload is it. The frontend types mirror it.

It feels DRY. It is in fact the tightest coupling you can build.

Because now a database column rename is an API break. A field the frontend needs forces a storage migration. A JSON tag bleeds into your business logic. An internal field you never meant to expose ships to clients because it happened to be on the struct. The layers cannot drift apart, which sounds good — but only because they have drifted together into a single thing that must change all at once, forever.

So the question for models is the inverse of the one for values. For values we ask “do the copies still agree?” For models we ask: can each layer change without dragging the others with it?

The principle: separate models at important boundaries

The architecture philosophy we build against is blunt about this:

Do not use one model everywhere. Use separate models at important boundaries.

The boundaries, and what each model is for:

DB rows         store data        (storage shape: nullable columns, FKs, indexes)
Domain models   enforce rules     (a project must have an owner; a name can't be empty)
Commands        express intent    (authenticated, authorized — the server sets ActorID)
Events          record facts      (something that already happened; see Part 8)
Read models     serve screens     (joins, denormalized, query-optimized)
API/DTO models  serve clients     (compatibility, security, pagination — promises)
External models isolate vendors   (a third-party shape stops at the adapter)

The point is not ceremony. It is that each of these is shaped by a different force. A DB row is shaped by storage and indexing. An API model is shaped by client compatibility and security — and once published, it is expensive to change. A domain model is shaped by business rules and should not know what a JSON field name or a SQL null wrapper is. Smashing them together means every one of those forces pulls on every layer.

The translation between them is not waste; it is the seam that lets one side change without the other noticing:

CreateProjectRequest   (what the client sends)
  -> CreateProjectCommand  (trusted intent: server adds ActorID)
  -> domain.Project        (rules enforced)
  -> db.ProjectRow         (storage shape)
  -> ProjectCreatedEvent   (the fact)
  -> ProjectView           (what the screen needs)

One discipline worth singling out: where a domain model wraps a generated storage row, it should do so by private composition, not public embedding. Embedding the DB struct re-exposes every column and lets anything mutate state outside your rules; holding it as a private field and exposing behavior (Rename, Archive) keeps the invariants where they belong.

How far Liftmere takes this

We apply the principle hardest at the two boundaries that hurt most when they fuse: storage and the wire.

Storage models are generated and private. Our SQL is hand-authored; sqlc generates the Go row structs and query methods from it, and those generated models live behind the repository layer. A check-sqlc gate fails the build if the committed generated code drifts from the SQL — the same one source → projection → gate shape as the vocabularies, applied to the database access layer.

The repo interface seam keeps storage from leaking up. A handler depends on a repository interface, not on the concrete Postgres type — so pgx and the row structs stay below the seam, and the handler can be tested against a fake. This is a governed sub-system on the backend (the “Repo Interface Seam”): the boundary is a structural rule, not a habit.

The wire model is the proto contract. API messages are defined in protobuf and generated into Go and TypeScript. The client never sees a database row; it sees a generated message shaped for clients. That seam is what Part 5: The Error Manifest and the later contract parts lean on.

The full six-model taxonomy above is the philosophy. Our Go API is deliberately leaner: handlers are thin and do their validation-and-mapping in one pass rather than through a separate pure domain layer or an explicit command type — there is no flow.go equivalent on the backend. The seams we enforce mechanically are the storage seam (sqlc + repo interface) and the wire seam (proto). The command/domain/read-model distinctions are applied by judgment where a domain has real invariants, and skipped where it is just CRUD. Events — the “facts” boundary — are real, but they live in a dedicated plane that gets its own part next.

That selectiveness is itself a rule from the philosophy:

If a model is mostly CRUD, wrapping the generated DB model is fine. If it has real invariants, hide the DB model behind methods. If it becomes central to the business, graduate it to a hand-written domain type.

You do not pay for boundaries you do not need. You pay for the two that always earn it — storage and the wire — and you enforce those with a gate.

What “mechanically enforced” actually means here

“Enforced at the storage and wire seams” is not a policy. It is five named gates, each catching a specific way those seams can break.

make check-sqlc regenerates the sqlc output and fails if the committed files differ from what the hand-authored SQL would produce — the same one-source-→-projection-→-gate shape as the vocabulary layer, applied to database access.

make check-sql-scope catches the silent corruption that leaks data across tenant boundaries: a query that touches workouts, programs, or media_assets without a user_id filter fails the build before the PR is reviewed.

Both run inside lint-be, so neither is a suggestion you remember on a good day.

The interface seam is enforced by two depguard rules in apps/api/.golangci.yml.

handler-no-db-driver refuses any import of github.com/jackc/pgx/v5 or pgxpool from **/internal/*/handler.go — if the handler can’t import the DB driver, it is structurally forced to go through the interface.

repo-no-transport refuses connectrpc.com/connect and net/http from **/internal/*/repo.go — the repo returns domain errors; only the handler maps them to Connect codes.

Together those two rules mean the only dependency between the layers is the reader interface declared by the handler in its own package.

The last gate is a compile assertion in every handler file:

var _ workoutv1connect.WorkoutServiceHandler = (*Service)(nil)

If the concrete *Service stops satisfying the generated handler interface — because a proto message changed, or a method signature drifted — the build refuses to link.

Drift scenario	Named gate	Where it runs
Generated DB row structs diverge from hand-authored SQL	`make check-sqlc`	`lint-be` → CI
A query touches `workouts`, `programs`, or `media_assets` without a `user_id` filter	`make check-sql-scope`	`lint-be` → CI
`handler.go` imports `pgx` or `pgxpool` directly	`depguard: handler-no-db-driver`	`golangci-lint`
`repo.go` imports `connectrpc.com/connect` or `net/http`	`depguard: repo-no-transport`	`golangci-lint`
`*Service` drifts from the generated handler interface	`var _ workoutv1connect.WorkoutServiceHandler = (*Service)(nil)`	compile time

One honest residual: depguard catches the package-import half of the seam, but it cannot verify that the reader field in Service is declared as the interface type rather than a *Repo pointer.

That residual is a named review note — when adding a new domain, the reviewer confirms Service.reader (or its equivalent) is the interface, not the concrete struct pointer.

There is also one live exception: internal/programs is excluded from all linting until its Connect-RPC rewrite lands (TODO(programs-rpc)).

The gate is not there because we trust the process. It is there because we learned — with real incidents — that each of these seams breaks silently and expensively when it isn’t mechanically held.

The velocity payoff

The coherence check this removes is the slow, structural one: if I change this storage detail, what else breaks?

With the seams in place, the answer is bounded. Reshape a table and regenerate — the repo interface absorbs it, and nothing above the seam recompiles against pgx. Add a client-facing field to a proto message — storage does not move. The layers are free to drift apart deliberately, which is the only kind of freedom that lets you move fast in one place without auditing all the others.

It is the same trade as everywhere in this series: a little declared duplication at the boundary, in exchange for never hand-tracing a change across layers that were never supposed to be the same thing.

And the rails that buy this freedom are cheap to lay now: wiring the repo-interface seam or adding a depguard rule is an afternoon, not a quarter — the cost of the boundary has collapsed, while the cost of the coupling it prevents has not.

What’s next

One of those boundaries — events, the record of facts that already happened — turns out to be the most powerful anti-drift tool in the stack. Part 8: Projected Truth is about projected truth: an append-only event log as the one source, read models as disposable projections, and the ability to rebuild any view from the log when you suspect it has drifted.

Are We Drifting? — Part 6: Config and Metrics

Sun, 07 Jun 2026 00:00:00 GMT

Are We Drifting? — Part 6: Config and Metrics

The vocabularies in Part 4: Enums as Shared Vocabulary and Part 5: The Error Manifest described a service’s data. This part covers its edges — the environment it trusts on the way in, and the signals it emits on the way out. Both drift. Both are the same atom.

Are we drifting here?

Config drift is the classic one. An environment variable is read with os.Getenv in three different files, with three slightly different defaults, and one of them forgets the variable is required. The .env.example that is supposed to document what the service needs was last updated two features ago. The service boots fine in dev and falls over in staging because a variable nobody remembered is missing — and the failure is a nil deref deep in a request, not a clear “you forgot DATABASE_URL.”

Metrics drift the same way. A counter is incremented with a string literal "media.upload.intent_created", and the dashboard queries media.uploads.intent_created — one word apart, silently graphing nothing. A label gets a new value that no one added to the alert.

Both are closed sets that cross a boundary — the process boundary for config, the telemetry boundary for metrics. Both want to be vocabularies.

The same three-tier wall that governs the enums and the error manifest governs these edges too: a lint-error for the things that happen daily, a compile assertion for the seam that must never rot, and a CI coverage script for the inventory that drifts on its own schedule.

Config as a vocabulary

A config entry is the familiar atom: a name (how Go refers to it), a wire (the environment variable), a label, and metadata describing its type, default, and validation. Here are a few real entries from our API’s config manifest:

kind: config
source: env
module: api
name: Config
entries:
  - name: Port
    wire: PORT
    label: HTTP listen port
    metadata:
      type: string
      default: "8080"
      group: server

  - name: DatabaseURL
    wire: DATABASE_URL
    label: PostgreSQL connection URL
    metadata:
      type: string
      group: database
      validation:
        required: true

  - name: S3SecretAccessKey
    wire: S3_SECRET_ACCESS_KEY
    label: S3 secret access key
    metadata:
      type: string
      secret: true
      group: s3

The interesting part is that validation is itself declarative. The manifest does not just list variables; it states the rules between them, in a small vocabulary of its own:

  - name: SupabaseJWKSURL
    wire: SUPABASE_JWKS_URL
    metadata:
      validation:
        one_of_group: supabase_jwt          # exactly one of this group must be set
        required_when:
          field: AppEnv
          values: [staging, production]      # …but only in these environments

  - name: S3PublicEndpoint
    wire: S3_PUBLIC_ENDPOINT
    metadata:
      validation:
        must_match_or_empty_when:            # must equal S3Endpoint, or be empty,
          field: S3Endpoint                  # when running in staging/production
          when:
            field: AppEnv
            values: [staging, production]

required, required_when, one_of_group, must_match_or_empty_when — the relationships that usually live in a paragraph of onboarding docs (or in nobody’s head) are declared facts. From this one manifest, buildmere generates:

a typed Go Config struct, so config access is cfg.DatabaseURL, never a stray os.Getenv;
a Load() that reads the environment and a Validate() that enforces every rule above;
a .env example file, so the documented environment cannot drift from the required one;
an env-check command that validates a real .env against the manifest.

That last pair is the anti-drift hinge. The example and the validator come from the same source as the struct, so “what the service needs,” “what the example shows,” and “what the startup check enforces” are guaranteed to be the same list. A missing required variable fails at boot with a clear message — or fails env-check in CI before it ever boots.

The CI tier closes that gap explicitly: env-check runs the config manifest’s declared requirements against a real .env and fails the build when the two lists disagree — a variable the service stopped reading still documented in the example, or a newly required variable not yet added.

Metrics as a vocabulary

A metric entry is the same atom with instrument metadata. Here is the real media-metrics manifest:

kind: metric
output: ".."
module: media
name: MediaMetrics
entries:
  - name: UploadIntentCreated
    wire: media.upload.intent_created
    label: Upload intents created
    metadata:
      instrument: counter
      labels:
        - name: content_type
        - name: outcome
          values: [accepted, rejected]

  - name: TranscodingDuration
    wire: media.transcoding.duration
    label: Transcoding job duration
    metadata:
      instrument: histogram
      unit: s
      labels:
        - name: status
          values: [success, failure]

  - name: ActiveUploads
    wire: media.uploads.active
    label: In-progress uploads
    metadata:
      instrument: updown_counter

Notice the nested vocabulary: a label’s values: [accepted, rejected] is itself a closed set, declared inline. The metric name (media.upload.intent_created) is the wire; it is written exactly once, here.

The generated Go is, again, zero-import — it depends only on context, and a Factory interface the project implements. This is verbatim:

// Code generated by buildmere; DO NOT EDIT.

package media

import "context"

// Factory builds instruments by name. Implementations live in the consuming
// project's metrics kit; the generated code never imports it.
type Factory interface {
  Counter(name, desc string) interface {
    Add(ctx context.Context, n int64, labels ...any)
  }
  Histogram(name, desc, unit string) interface {
    Record(ctx context.Context, v float64, labels ...any)
  }
  UpDownCounter(name, desc string) interface {
    Add(ctx context.Context, n int64, labels ...any)
  }
}

var MediaMetrics = &mediaMetrics{}

// Register builds every instrument from f. Call once after the metrics
// backend is initialized.
func (m *mediaMetrics) Register(f Factory) {
  m.uploadIntentCreated = f.Counter("media.upload.intent_created", "Upload intents created")
  m.transcodingDuration = f.Histogram("media.transcoding.duration", "Transcoding job duration", "s")
  m.activeUploads = f.UpDownCounter("media.uploads.active", "In-progress uploads")
}

// RecordUploadIntentCreated records Upload intents created.
// Labels: outcome (accepted | rejected)
func (m *mediaMetrics) RecordUploadIntentCreated(ctx context.Context, contentType string, outcome string) {
  if m.uploadIntentCreated == nil {
    return
  }
  m.uploadIntentCreated.Add(ctx, 1, "content_type", contentType, "outcome", outcome)
}

Two things matter here.

First, the call site is typed: RecordUploadIntentCreated(ctx, contentType, outcome). You cannot fat-finger the metric name — it is baked into the generated method — and you cannot forget a label, because the labels are parameters. The string "media.upload.intent_created" exists in exactly one place in the whole codebase.

Second, the generated code imports no OpenTelemetry. It defines a Factory interface and depends on that. The project’s own metrics kit implements the interface (metricskit.BuildmereFactory) — the ~60-line adapter from Part 3: buildmere, a Codegen Kernel — and buildmere ships a compile-time assertion that the adapter satisfies the generated Factory. The instrument set is portable; the binding to OTel is the project’s, and the compiler checks the seam.

That seam is held by a zero-cost Go idiom: var _ Factory = (*metricskit.BuildmereFactory)(nil). That line compiles to nothing and refuses to compile at all if the adapter ever falls out of sync with the generated interface — no test to write, no CI script to wire, just a fact the compiler checks on every build.

No raw values at the edge

The manifests govern the names and shapes that cross the boundary. The remaining gate governs the values — the rule that nothing structured gets flattened into a raw string on the way out. That is what sloglint in apps/api/.golangci.yml enforces, across three properties, each added because a specific class of log corruption had already happened or was structurally guaranteed the moment an agent writes a handler without knowing the rule.

static-msg fires when a developer writes slog.Error("query failed for user " + userID) — the interpolation swallows the structure and makes the field invisible to a log query.

no-mixed-args fires when the call mixes positional and key-value args: slog.Error("query failed", err, "athlete_id", id) looks reasonable at a glance, but the error is a positional arg, not a keyed one, and sloglint rejects it.

context: scope is the one with the longest tail — it requires slog.ErrorContext (the *Context variant) any time a ctx context.Context is already in scope, because trace IDs travel through context and a plain slog.Error in a handler throws that thread away.

Three lint rules. Three specific call-site shapes. Each one fires before the PR lands.

The natural extension is an otelslog bridge — feeding those structured records straight into spans when an OTLP endpoint is configured. The slog surface is the current one, and the bridge is where this goes next.

Drift scenario	Named gate	Tier
`.env.example` drifts from what the manifest declares required	`env-check` against the manifest	CI · coverage-script
New `metricskit` adapter does not satisfy the generated `Factory` interface	`var _ Factory = (*metricskit.BuildmereFactory)(nil)`	compile-enforced
`slog.Error("query failed for user " + userID)` — interpolated message swallows structure	`sloglint: static-msg` · `apps/api/.golangci.yml`	lint-error
`slog.Error("query failed", err, "athlete_id", id)` — positional arg mixed with key-value pair	`sloglint: no-mixed-args` · `apps/api/.golangci.yml`	lint-error
`slog.Error(...)` called while `ctx context.Context` is in scope	`sloglint: context: scope` · `apps/api/.golangci.yml`	lint-error

One exclusion worth naming: internal/programs is excluded from all linters pending its Connect-RPC rewrite — TODO(programs-rpc) — so the three sloglint rules do not fire there today.

The velocity payoff

For config, the check this removes is the onboarding-and-2am one: which environment variables does this service actually need, and which are required where? That is now the manifest, enforced at boot and in CI. Nobody greps for os.Getenv to reconstruct the answer.

For metrics, it removes the silent-dashboard check: does the name I emit match the name I graph, and did I pass the right labels? The name is written once and the call is typed, so the emit side cannot drift from the declared signal.

In both cases the edge of the service is described in one declarative place, and the generated code plus the gate make the description binding.

What’s next

That closes the vocabularies arc — the one source → many projections → drift gates shape applied to data, failures, environment, and telemetry. Part 7: Models at Boundaries zooms out from closed value sets to whole models, and the discipline that keeps a “project” or a “workout” from becoming one overloaded struct smeared across the database, the API, and the frontend.

Are We Drifting? — Part 5: The Error Manifest

Sat, 06 Jun 2026 00:00:00 GMT

Are We Drifting? — Part 5: The Error Manifest

Part 4: Enums as Shared Vocabulary followed the base vocabulary — an enum — to its projections. An error is that same atom plus the metadata a failure needs. It is also the clearest cross-stack example in the series, because an error only does its job if it means the same thing on the backend that raised it and the frontend that handles it.

Are we drifting here?

A failure is a contract between two sides that never share a process.

The backend decides something went wrong. The frontend has to decide what to show, whether to offer a retry, whether to send the user somewhere. Between them is a wire, and across that wire the failure has to survive as something more useful than a 500 and a string.

Drift here is especially nasty because it is invisible until the unhappy path runs in production. The backend starts returning a new error; the frontend has a switch that does not know about it and falls through to “Something went wrong.” Or the same conceptual failure gets a 409 in one handler and a 400 in another, and the frontend’s retry logic guesses wrong. Nobody tested it, because it is the path you hope never happens.

So: is a failure declared once and understood identically on both ends? Or is it re-invented on each side and hoped into alignment?

In this codebase, three rules enforce the answer:

A handler calls fmt.Errorf("asset not found") directly → check-connect-errors (CI script) fails the build; connect.NewError is only allowed inside the error-adapter package.
A handler raises media.AssetOwnershipViolation().WithAssetID(id) → the Connect code (permission_denied), the typed fields (asset_id), and the wire string (asset_ownership_violation) all come from the manifest; no handler invents them.
The same error crosses the wire as a structured Connect error → the frontend receives a typed code and typed fields, not a parsed HTTP status and a guessed English message.

The third rule is the FE↔BE seam that carries today. The fuller stitch — where the frontend’s error constants are also generated from the same manifest — is where this goes next.

One source

Here is a real error vocabulary from the media module. Three failure modes, declared once:

kind: error
output: ".."
module: media
name: MediaErrors
entries:
  - name: UnsupportedContentType
    wire: unsupported_content_type
    label: Unsupported content type
    metadata:
      code: invalid_argument
      fields: [content_type]

  - name: UploadTooLarge
    wire: upload_too_large
    label: Upload exceeds size limit
    metadata:
      code: invalid_argument
      fields: [asset_id, size_bytes, max_bytes]

  - name: AssetOwnershipViolation
    wire: asset_ownership_violation
    label: Asset does not belong to requesting user
    metadata:
      code: permission_denied
      fields: [asset_id]

It is the same shape as the enum from Part 4 — name, wire, label — with two pieces of failure-specific metadata per entry: a transport code (a Connect error code) and the typed fields this error carries as structured context.

The backend projection

buildmere generates a zero-import Go type per error. This is the actual generated code for the first one — note that it imports nothing but fmt:

// Code generated by buildmere; DO NOT EDIT.

package media

import "fmt"

// UnsupportedContentTypeError is the typed error for unsupported_content_type.
// Wire: "unsupported_content_type" | Code: "invalid_argument"
type UnsupportedContentTypeError struct {
  contentType string
  cause       error
  msg         string
}

func UnsupportedContentType() UnsupportedContentTypeError { return UnsupportedContentTypeError{} }

func (e UnsupportedContentTypeError) WithContentType(v string) UnsupportedContentTypeError {
  e.contentType = v
  return e
}

func (e UnsupportedContentTypeError) Wire() string { return "unsupported_content_type" }
func (e UnsupportedContentTypeError) Code() string { return "invalid_argument" }
func (e UnsupportedContentTypeError) Fields() map[string]any {
  return map[string]any{"content_type": e.contentType}
}
func (e UnsupportedContentTypeError) Error() string {
  if e.msg != "" {
    return e.msg
  }
  return "unsupported content type"
}
func (e UnsupportedContentTypeError) Unwrap() error { return e.cause }
func (e UnsupportedContentTypeError) Is(target error) bool {
  t, ok := target.(interface{ Wire() string })
  return ok && t.Wire() == e.Wire()
}
func (e UnsupportedContentTypeError) Wrap(err error) error { e.cause = err; return e }

A handler raises it fluently, with the typed field attached as structured context:

return media.UploadTooLarge().
  WithAssetID(id).
  WithSizeBytes(strconv.FormatInt(n, 10)).
  WithMaxBytes(strconv.FormatInt(max, 10))

The Code() — invalid_argument, permission_denied — is the value that crosses the wire. The generated struct is deliberately inert: it knows its wire string, its transport code, and its fields, and nothing about Connect. A small adapter the project owns turns a coded error into a connect.NewError(...) at the transport boundary — and in our repo a CI check (check-connect-errors) enforces that connect.NewError appears only in that one adapter package, never scattered through handlers. One place translates application failures into wire failures.

The frontend projection — and where this goes

Here is the side-by-side.

What the wire carries: the frontend learns about the failure through the contract. The error crosses the wire as a structured Connect error carrying the code and the typed fields from the manifest. The generated Connect client surfaces it as a typed error, so the frontend is reasoning about permission_denied and a content_type field — not parsing a 403 and a sentence of English. That is a real cross-boundary coupling: the backend declared the failure once, and the frontend receives a structured, coded shape rather than a guess.

The next emitter: the philosophy this manifest is built toward goes one step further — generating the frontend’s error vocabulary from the same source. From one declaration you also emit:

// the frontend projection from the same manifest
export const MediaError = {
  UnsupportedContentType: "unsupported_content_type",
  UploadTooLarge: "upload_too_large",
  AssetOwnershipViolation: "asset_ownership_violation",
} as const;

…plus safe user-facing messages, a retryable hint, and a category so the UI can branch exhaustively on the error code instead of on an HTTP status. At that point a backend engineer adding an error and a frontend engineer handling it are reading projections of the same row, and a missing case is a compile error on the frontend.

buildmere’s error kind emits Go; the TypeScript emitter is the natural extension — the kernel is built for exactly this, since adding a language to a kind is a new generator package. The backend half ships and is gated, the wire-level coupling ships through the contract, and the generated frontend half is the next emitter.

A design principle worth stealing now

One rule from the error philosophy is worth applying by hand right now: the application error code is the source of truth, and transport codes derive from it — never the reverse.

It is tempting to let HTTP status be the canonical thing. But the mappings are not one-to-one. HTTP 409 can mean “already exists” or “version conflict”; HTTP 400 can mean “invalid argument” or “failed precondition.” If you make HTTP the source, you lose that distinction on the way in and guess it back on the way out.

An error code names the application failure. HTTP, gRPC/Connect, an MCP tool response, a CLI exit, and a frontend display are all renderings of it. The code owns its mappings; no transport is the universal source of truth.

Our manifest carries the Connect code directly on each entry for this reason — the failure’s meaning travels with the failure, and each edge decides how to render it.

The velocity payoff

The coherence check this removes is the one that only fails in production: does the frontend’s handling of this failure match the failure the backend actually emits?

Today that is partly structural (the code and fields cross the wire as a typed contract, not a parsed status) and partly still manual (the frontend’s message and branching are hand-written). The frontend emitter closes the gap entirely. Either way, the direction is the one this series argues: move the failure’s definition into one declared place, and let each side’s handling be generated or contract-checked rather than independently authored and hoped into agreement.

What’s next

Part 6: Config and Metrics finishes the vocabularies arc with the two kinds that govern a service’s edges rather than its data — config (the environment a service trusts) and metrics (the signals it emits) — both declared as the same atom, both gated the same way.

Are We Drifting? — Part 4: Enums as Shared Vocabulary

Fri, 05 Jun 2026 00:00:00 GMT

Are We Drifting? — Part 4: Enums as Shared Vocabulary

Part 3: buildmere, a Codegen Kernel introduced the kernel in the abstract. The enum kind is the simplest place to make it concrete — so let us follow one enum from its manifest all the way out to every side that has to agree about it.

Are we drifting here?

An enum is a closed set of named values. It is also the single most common thing to drift, because it shows up in the most places: a Go type, a TypeScript union, a dropdown, a validator, a database column, an analytics dimension, a model’s structured output.

The drift is always the same story. Someone adds a value on one side. The other sides do not hear about it. A row appears in the database that the frontend cannot render; a model returns a status the backend rejects; a dashboard silently stops counting a state that was renamed.

So the test for the enum kind is direct: can a value exist on one side that another side has never heard of? The answer should be structurally no.

In this codebase, here is what “structurally no” looks like in practice:

A new VideoStatus value added to the YAML manifest → make gen-vocab regenerates Go, TS, Zod, SQL CHECK in one pass; make check-vocab fails the PR if any committed projection is out of date.
A VideoStatus string typed by hand in handler code → the Go type system rejects anything that isn’t a VideoStatus constant; no raw string survives tsc or the Go compiler.
A row inserted with an unknown status → the database CHECK constraint rejects it before it lands.
A backlog ticket assigned to an owner not in enums.mjs → the Zod schema on the operation input rejects the value at the REST/MCP/CLI boundary.

One source

Here is a real enum from our backend — the lifecycle of an uploaded video. This is the entire source of truth:

kind: enum
output: "../enums"
module: media
name: VideoStatus
entries:
  - name: Uploading
    wire: uploading
    label: Uploading
  - name: Processing
    wire: processing
    label: Processing
  - name: Ready
    wire: ready
    label: Ready
  - name: Failed
    wire: failed
    label: Failed
    metadata:
      terminal: true
  - name: Archived
    wire: archived
    label: Archived

Five values, each with a code-facing name, a boundary-facing wire, and a human label. One of them is flagged terminal. That is the whole declaration.

Many projections

Running the generator turns that manifest into typed code. This is the actual generated Go — not a sketch:

// Code generated by buildmere; DO NOT EDIT.

package enums

type VideoStatus string

const (
  VideoStatusUploading  VideoStatus = "uploading"
  VideoStatusProcessing VideoStatus = "processing"
  VideoStatusReady      VideoStatus = "ready"
  VideoStatusFailed     VideoStatus = "failed"
  VideoStatusArchived   VideoStatus = "archived"
)

func (v VideoStatus) IsValid() bool {
  switch v {
  case VideoStatusUploading,
    VideoStatusProcessing,
    VideoStatusReady,
    VideoStatusFailed,
    VideoStatusArchived:
    return true
  }
  return false
}

var videoStatusLabels = map[VideoStatus]string{
  VideoStatusUploading:  "Uploading",
  VideoStatusProcessing: "Processing",
  VideoStatusReady:      "Ready",
  VideoStatusFailed:     "Failed",
  VideoStatusArchived:   "Archived",
}

func (v VideoStatus) Label() string { return videoStatusLabels[v] }

func AllVideoStatus() []VideoStatus {
  return []VideoStatus{
    VideoStatusUploading,
    VideoStatusProcessing,
    VideoStatusReady,
    VideoStatusFailed,
    VideoStatusArchived,
  }
}

Note the name/wire split surviving into the code: VideoStatusReady (the name) is the constant; "ready" (the wire) is its value. Code reads VideoStatusReady; the byte on the wire is ready; the label "Ready" is for humans. Three concerns, one declaration, no place for them to disagree.

The same manifest is what the enum kind projects to the other sides. A TypeScript union and label map:

export const VideoStatus = {
  Uploading: "uploading",
  Processing: "processing",
  Ready: "ready",
  Failed: "failed",
  Archived: "archived",
} as const;
export type VideoStatus = (typeof VideoStatus)[keyof typeof VideoStatus];

export const videoStatusLabels: Record<VideoStatus, string> = {
  uploading: "Uploading",
  processing: "Processing",
  ready: "Ready",
  failed: "Failed",
  archived: "Archived",
};

A Zod schema for runtime validation at the edge:

export const VideoStatusSchema = z.enum([
  "uploading", "processing", "ready", "failed", "archived",
]);

And a SQL CHECK constraint so the database itself refuses an unknown value:

ALTER TABLE videos
  ADD CONSTRAINT videos_status_check
  CHECK (status IN ('uploading', 'processing', 'ready', 'failed', 'archived'));

The dropdown iterates AllVideoStatus() (or the TS union). The validator is VideoStatusSchema. The column is constrained. None of these is hand-maintained; all of them are the same five entries, projected.

Keeping an enum honest over time

A closed set is only safe if changing it is disciplined. The rules are simple and they are the same ones a careful DBA already follows:

Values are append-only by default. Adding Suspended is safe. The manifest grows; every projection regenerates; the CHECK constraint is widened by a new migration.
Renaming is not a rename. Changing a wire value is a data migration in disguise — existing rows still hold the old string. You deprecate the old value and add the new one, then migrate, then remove.
Removal waits for the data. A value cannot leave the vocabulary while a single row or in-flight event still references it. Mark it deprecated with a note, migrate, and only then delete.

Deprecation is itself just metadata on the entry — deprecated: true with a deprecation_note — so “this value is on its way out” is a fact the generated code and docs can carry, not tribal knowledge.

The database CHECK constraint is the backstop. Application code can be wrong; a migration can lag; but a column constrained from the same manifest will reject a value that was never declared. The truth has a floor.

Not every vocabulary needs a generator

Codegen is the right tool when a vocabulary crosses language boundaries. Some of ours do not, and they use a lighter mechanism.

Our backlog’s enums — ticket statuses, areas, efforts, owners — live in a single enums.mjs module that every consumer imports directly. The frontend reaches them over REST; the CLI and the backlog services import the file. Some are static (STATUSES, AREAS); one, OWNERS, is derived at call time by scanning the agent definitions on disk, so it can never go stale against the set of agents that actually exist.

And there is a fourth consumer the others do not have: an agent, which discovers the set at runtime rather than compiling it in. The same enums are queryable over MCP — an agent asks for the live owners or statuses (backlog_list_enums) instead of hard-coding them, and a stale agent never invents an owner that does not exist. An enum, in other words, is the smallest instance of a vocabulary that systems serialize, humans speak, and agents discover — the same closed set, reached three different ways.

Different mechanism, identical principle: one source, many consumers, no second copy to drift. Codegen is how you get there across languages; a shared module is how you get there within one; runtime discovery is how an agent gets there without compiling at all. The discipline is the same.

The velocity payoff

The check this removes is the most tedious one in code review: you added a status — did you update the type, the dropdown, the validator, and the constraint?

That question disappears. You add an entry to the manifest, regenerate, and every side updates together. The reviewer does not audit five files for consistency, because consistency is not something a human is maintaining. And if anyone hand-edits a generated file to “just add it here,” check-vocab fails the build.

You can let an agent add a video state and trust the diff, because the only way to add one wrong is a way the gate rejects.

What’s next

Enums are the base vocabulary. Part 5: The Error Manifest adds the first layer of kind-specific metadata and lands the series’ clearest cross-stack example: the error manifest, where one declaration stitches a backend failure to a frontend’s handling of it.

Are We Drifting? — Part 3: buildmere, a Codegen Kernel

Thu, 04 Jun 2026 00:00:00 GMT

Are We Drifting? — Part 3: buildmere, a Codegen Kernel

Part 2: The Tagged Vocabulary named the atom: a tagged vocabulary, declared once. This part is about the machine that turns that one declaration into typed code on every side — and, more importantly, keeps the copies from drifting after it does.

Are we drifting here?

A manifest only earns the name “source of truth” if the copies generated from it cannot quietly disagree with it.

A generator that you run by hand, whose output you commit and then edit “just this once,” is not a source of truth. It is a suggestion with extra steps. The generated file drifts from the manifest the moment someone touches it, and nothing notices.

So the real question for any codegen system is not “can it generate?” It is “what stops the generated code from drifting away from its source?“

buildmere, in one paragraph

buildmere is a standalone Go module — github.com/buildmere/vocab — that does exactly one thing: declare a closed tagged vocabulary once in a YAML manifest, and generate typed code, validation, schemas, and reference files across the stack from that single source.

Two rules keep it honest and portable, and they are worth stating verbatim because everything else follows from them:

1. buildmere imports nothing from its consumers. It is imported by products like Liftmere; never the reverse.

2. Generated code imports nothing project-specific — only context / fmt from the standard library. Binding generated code to a project’s runtime is done by ~60 lines of adapter the project owns, not by the generator.

The first rule means buildmere can be lifted into its own repository with a git mv. The second means every generated artifact is adoptable by any project, not just ours — the generated code is inert until a small, hand-owned adapter wires it to the real metrics backend or error transport.

A kernel that knows nothing about kinds

The architecture is a kernel plus plugins. The kernel ships zero kinds.

The kernel is small and generic:

Manifest, Entry        the parsed source — a list of vocabulary entries
Generator              interface: given a Manifest, return Artifacts
Artifact               an in-memory file: path + contents (not written yet)
Registry               maps a kind ("enum", "error", …) to its generators
KindDescriptor         how a kind declares its metadata schema
Generate / Write / Check   the pipeline

A kind is a plugin: a root package that knows how to parse its kind-specific metadata, plus one sub-package per target language. The kernel never hard-codes the list of kinds; the registry resolves a kind string to its generators at runtime. Adding a new output language to a kind is a new package under generators/ — it touches nothing that already works.

The kinds that ship today:

Kind	The manifest declares	Generators
`enum`	a closed value set	Go constants, TypeScript, Zod, JSON-Schema, SQL `CHECK`
`config`	an env-var schema + validation	Go `Config` struct + `Load`/`Validate`, `.env` example
`error`	a domain error vocabulary + fields	zero-import Go error structs (`Code`/`Wire`/`Fields`/`Is`/`Wrap`)
`metric`	an OTel instrument set + labels	zero-import Go metric set + a `Factory` interface

Generators are pure functions

This is the detail that makes the drift gate trustworthy.

A generator does not write to disk. It takes a manifest and returns artifacts — path-plus-bytes values, held in memory. The framework collects them, and then does one of two things:

Write — write the artifacts to disk (gen).
Check — compare the artifacts against what is already committed, and exit non-zero if a single byte differs (check).

Because a generator is a pure function from manifest to bytes, the same call that writes your code in development is the call that verifies it in CI. There is no second, separately-maintained “linter” that could itself drift from the generator. The generator is the spec.

# from packages/buildmere (GOWORK=off keeps the tool's deps out of the app graph)
GOWORK=off go run ./cmd/buildmere gen        <manifest.yaml>   # write artifacts
GOWORK=off go run ./cmd/buildmere check      <manifest.yaml>   # CI drift gate
GOWORK=off go run ./cmd/buildmere gen-all    <root-dir>        # discover + generate every manifest
GOWORK=off go run ./cmd/buildmere check-all  <root-dir>        # drift gate over a whole tree

Each manifest declares its own output: path, so discovery needs no per-manifest wiring — gen-all walks a directory, finds every buildmere manifest, and generates each to where it says it belongs.

The drift gate is one make target

In our repo, two make targets wrap the kernel:

make gen-vocab     -> buildmere gen-all   (regenerate everything; what you run locally)
make check-vocab   -> buildmere check-all (the CI gate; fails on any drift)

check-vocab is not optional or advisory. It sits inside the backend lint umbrella that every pull request runs:

lint-be: contracts lint-migrations check-vocab check-mocks check-sqlc \
         check-sql-scope check-connect-errors

If you hand-edit a generated .gen.go, check-vocab regenerates it in memory, sees that your edit does not match what the manifest produces, and fails the build. The only way to change generated code is to change the manifest and regenerate. That is the third leg of the governance model — structure, enforcement, docs — and without it the first two are decoration.

buildmere also ships its own internal drift guards, so the generator itself cannot silently change shape: a compile-time assertion that the metric Factory matches, an error-code round-trip test, and pinned generator signatures.

The same invariant — generated code cannot silently disagree with its source — appears twice in the backend, enforced two different ways, and the contrast is the interesting part.

buildmere outputs are committed to the repo, which is why check-vocab can catch them: it regenerates the files in memory and byte-compares against what is committed — any hand-edit is visible as a diff and fails the build.

buf generate outputs are gitignored, so they cannot drift because they are never stored in the first place — gen/go/ and gen/ts/ are produced fresh on every make gen-be, and any hand-edit to them simply disappears the next time the target runs.

Two different mechanisms. The same refusal.

Generated code cannot silently disagree with its source. In this backend, that invariant is enforced twice over — once by a check that diffs what is committed, once by a store strategy that makes committing impossible.

Drift scenario	Gate	Tier
Hand-edit a committed `.gen.go` vocab file	`check-vocab` inside `lint-be`: regenerates in memory, byte-compares, exits non-zero	coverage-script (tier 3)
Add an RPC to the proto, skip the handler method	`var _ workoutv1connect.WorkoutServiceHandler = (*Service)(nil)` — build fails	compile-enforced (tier 1)
Delete a proto method, handler still references the old interface	same compile assertion, same instant failure	compile-enforced (tier 1)
Hand-edit anything under `gen/go/` or `gen/ts/`	`make gen-be` overwrites it; `gen/` is gitignored so the edit was never committed	structural (gitignore)

Neither of these gates requires developer discipline to fire on a PR: make lint-be lists contracts as a prerequisite, so buf generate runs before the linters, and the compile assertion runs before that lint step even starts.

The velocity payoff

Adding a new closed set used to mean a decision and a chore: where do the constants live, who writes the validator, who remembers to update the SQL constraint, who keeps the frontend list in sync.

With a kernel in place, a new vocabulary is a new manifest plus a make gen-vocab. The generator for that kind already exists. Every projection appears at once, correct by construction, and check-vocab guarantees it stays that way.

And because generators are pure functions tested as pure functions, extending the machine is itself cheap — a new language emitter is a small package with golden-file tests, not a research project. This is the economic inversion from Part 1: The Drift Problem made concrete: the rails are cheap to lay, cheap to extend, and they remove a standing coherence tax.

What’s next

The kernel is abstract on purpose. Part 4: Enums as Shared Vocabulary makes it concrete with the simplest kind — enum — and follows one manifest all the way out to Go, TypeScript, Zod, JSON Schema, and a SQL CHECK constraint.

Where this goes is more reach on the same kernel: additional kinds like permission, route, and event, more language emitters per kind (error → TypeScript is the obvious next one), a typed Kind discriminator, and lifting buildmere into its own open-source repository with a git mv. The plugin model was built for exactly these extensions.

Are We Drifting? — Part 2: The Tagged Vocabulary

Wed, 03 Jun 2026 00:00:00 GMT

Are We Drifting? — Part 2: The Tagged Vocabulary

Part 1: The Drift Problem ended on a shape: one source → many → . This part is about the source — specifically, the smallest, most boring unit that the entire pattern is built from.

Are we drifting here?

Start with the most innocent thing in any codebase: a closed set of named values.

A video is uploading, processing, ready, failed, or archived. A ticket is proposed, accepted, in_progress, or shipped. An upload was accepted or rejected.

These look harmless. They are strings. Everyone “knows” them.

That is exactly why they drift.

The backend writes "ready". The frontend dropdown lists "Ready". The analytics event sends "READY". A migration’s CHECK constraint allows 'ready' but a later refactor adds 'done' on the API side and nobody updates the constraint. Three months later a row exists that the frontend cannot render, because the value in the database is a status the UI has never heard of.

No single change was wrong. The set was simply written down in six places, and the six copies wandered.

The atom: a tagged vocabulary

Here is the move that makes the rest of the series possible.

A closed set of named values is not a string convention. It is a : a first-class, declarable thing with a precise shape.

Every entry in a tagged vocabulary has three layers.

Layer 1 — Identity
  name   the canonical identifier (how code refers to it)
  wire   the serialized form (how it crosses a boundary)
  deprecated / deprecation_note

Layer 2 — Presentation
  label        the human-facing string
  description  optional documentation

Layer 3 — Kind-specific metadata
  whatever this kind of vocabulary additionally needs

The first layer is the load-bearing one, and the split inside it is the whole trick.

Why `name` and `wire` are different on purpose

Code refers to a value by its name. The boundary — JSON, a database column, an event payload, a model’s structured output — sees its .

Keeping them separate means the serialized representation is a deliberate, declared decision, not an accident of how someone happened to spell a constant.

The name/wire split is only a design decision until a machine makes it load-bearing.

On the backend, the seam that matters is between the handler and the repo — the same clean separation the name/wire distinction declares between identity and wire form.

depguard rules in apps/api/.golangci.yml make that seam structural rather than conventional.

handler-no-db-driver means a handler.go file cannot import pgx — the handler has to speak to the database through the interface the repo exposes, not by reaching past it.

repo-no-transport means a repo.go file cannot import connectrpc.com/connect — the repo returns domain errors, and the handler maps them to Connect codes at the boundary.

Together these two rules ensure the only path from transport to storage passes through a typed interface: the name side and the wire side stay separated by design and by enforcement.

One carve-out, stated plainly: internal/programs runs raw net/http and has no repo seam yet — it is excluded from both rules in .golangci.yml with TODO(programs-rpc) until the Connect-RPC rewrite is done.

On the frontend, defineFixtures is the vocabulary-primitive pattern in different clothes.

A defineFixtures collection — loading, ready, empty, error — is a closed, named set of product states declared in one place, exactly the way an enum manifest declares wire values.

Three gates keep the vocabulary honest.

liftmere/no-fixture-outside-route (tools/eslint-no-fixture-outside-route.mjs) fires when screen.tsx imports fixtures directly — currently lint-warn at scoreboard ~113, target error.

liftmere/prefer-use-state-maybe-fixture fires when route.tsx calls useState(rosterFixtures.ready) directly, bypassing the preset injection that makes App Mode work.

check-fixture-registry-coverage.mjs fails the PR when a defineFixtures collection is missing from fixture-registry.ts, so no vocabulary can hide.

The enforcement cost differs: ESLint rules are file-granular and cheap to add; depguard rules are package-granular and need type information.

The concept is the same on both sides.

This is a real vocabulary from our backend — the lifecycle of an uploaded video:

kind: enum
output: "../enums"
module: media
name: VideoStatus
entries:
  - name: Uploading
    wire: uploading
    label: Uploading
  - name: Processing
    wire: processing
    label: Processing
  - name: Ready
    wire: ready
    label: Ready
  - name: Failed
    wire: failed
    label: Failed
    metadata:
      terminal: true
  - name: Archived
    wire: archived
    label: Archived

Failed carries one piece of kind-specific metadata — terminal: true — because some consumer cares that it is an end state. Everything else is pure identity and presentation.

That file is the source. It is the only place VideoStatus is defined. Every Go constant, every TypeScript union, every SQL CHECK constraint, every dropdown is a projection of it. We will watch those projections get generated in Part 4: Enums as Shared Vocabulary.

The same atom, wearing different metadata

The reason this is worth elevating to a “primitive” is that it is not just enums.

Look at three vocabularies from the same backend, side by side. They are obviously the same shape.

An enum — identity, label, a flag:

- name: Failed
  wire: failed
  label: Failed
  metadata:
    terminal: true

An error — identity, label, plus the metadata a failure needs (a transport code, and the typed fields it carries):

- name: UploadTooLarge
  wire: upload_too_large
  label: Upload exceeds size limit
  metadata:
    code: invalid_argument
    fields: [asset_id, size_bytes, max_bytes]

A metric — identity, label, plus the metadata an instrument needs (its kind and its labels):

- name: UploadIntentCreated
  wire: media.upload.intent_created
  label: Upload intents created
  metadata:
    instrument: counter
    labels:
      - name: outcome
        values: [accepted, rejected]

Three different concerns — a state machine, a failure mode, an observability signal. One structure: a closed set of entries, each with a name, a wire, a label, and a bag of kind-specific metadata.

An enum is the base vocabulary. An error is that base plus failure metadata. A metric is that base plus instrument metadata. Generalize any of them down and you get the enum back.

Once you see it, you cannot unsee it. Permissions are a vocabulary (identity plus an action and a resource). Config keys are a vocabulary (identity plus a type and a default). Event types, job kinds, plan tiers, notification channels — every closed named set that crosses a boundary is the same atom.

Why this matters for humans and agents

The unification is not academic tidiness. It collapses N mental models into one — and that is worth the most when the contributor is an agent.

Without it, every closed set is a bespoke situation: enums are declared one way, errors another, config a third, each with its own conventions and its own places to look. A contributor — human or model — has to learn each one, and an agent generating code has N chances to invent a value inline because it did not know the convention for that particular kind.

With it, there is exactly one rule, and it fits in a sentence:

If it is a closed, named set of values that crosses a boundary, it is a vocabulary. Vocabularies live in manifests. Code uses the generated constants. Inventing a value inline is a lint failure, not a style nit.

Every repeated question now has a single answer. What are the allowed values for X? — the manifest for X. How do I add one? — add an entry, regenerate, commit. How do I deprecate one? — mark it deprecated in the manifest. Where is this value used? — follow the projections from the manifest.

Not shared vocabulary — a canonical language

“Shared vocabulary” undersells what this is. A vocabulary declared once is the canonical language of the whole system, and it is spoken by three audiences at the same time: the systems that serialize the value across a wire, the humans who name it and argue about it in review, and the agents that write against it.

The third audience is the one that changes the stakes. An agent does not only inherit the vocabulary by compiling against generated constants — it can discover it. The same closed sets are reachable at runtime: an agent asks for the live set of backlog owners or statuses over MCP rather than hard-coding them, and the operations a service exposes are themselves introspectable, so the agent reads the contract instead of guessing it. The vocabulary is not just baked into the binary; it is a queryable, shared language.

A vocabulary that humans, systems, and agents all draw from — and that agents can discover at runtime — is not a naming convention. It is the the whole codebase speaks.

That is why the atom matters out of proportion to its size. Get the closed-set-declared-once right, and you are not deduplicating strings — you are giving every participant, silicon or human, the same words.

The velocity payoff

The coherence check this removes is the one nobody schedules and everybody pays: did the value I just used actually exist, spelled exactly that way, on every side that has to agree about it?

When that check is a lint rule reading from a manifest, the answer is structural. An agent can add a status, regenerate, and ship — and the moment it references a value that is not in the vocabulary, the build says so, before review, before production.

The expensive part was never typing the enum. It was the standing tax of trusting that the six copies still agreed. Naming the atom is what lets a machine pay that tax for you.

What’s next

We have the atom. Part 3: buildmere, a Codegen Kernel introduces the machine that turns it into code on every side: buildmere, a small codegen kernel where each kind of vocabulary is a plugin — and where the drift gate is one make target.

Are We Drifting? — Part 1: The Drift Problem

Tue, 02 Jun 2026 00:00:00 GMT

Are We Drifting? — Part 1: The Drift Problem

The question this series keeps asking

Pick any concept your system knows about.

A project status. An error. A permission. A config key. The shape of a “create workout” request.

Now count how many places that one concept is written down.

The database has a column for it. The domain model has a field. The API contract has a message. The frontend has a TypeScript type, a dropdown, a validation rule. The event log has a payload. The docs have a table. A test has a fixture. An agent has an instruction.

That is not one concept. That is one concept and a dozen copies of it.

And copies drift.

Are we drifting? is the only question that matters once code is cheap to produce. This series asks it of every layer in our stack and shows the same answer each time.

What we mean by drift

is what happens when two representations of the same concept stop agreeing.

It is rarely dramatic. It is a slow accumulation of small disagreements:

The backend rejects an enum value the frontend dropdown happily offers.
An error means 404 in one handler and 409 in another, because someone guessed.
The DB column is snake_case, the API field is camelCase, and a mapping function in the middle silently swallows the one that was renamed.
A screen imports a fixture that no longer matches the real product state.
A handler quietly diverges from the contract it was generated against.
The docs describe a flag that was removed two sprints ago.

None of these is a crash. Each is a small lie the codebase tells about itself.

Here is what those lies look like when they are actually caught — by name, in this codebase:

The drift	The gate that catches it
A screen imports its own fixture	`liftmere/no-fixture-outside-route` — lint-error, PR fails
A component uses `#0f0f17` instead of a design token	`liftmere/no-raw-hex-color` — lint-error, ambient
A handler returns `fmt.Errorf("not found")` directly	`check-connect-errors` — CI script, build fails
A committed `.gen.go` drifts from its YAML manifest	`make check-vocab` — buildmere drift gate, exits non-zero
A generated feature registry goes stale	`generate-features --check` — codegen gate, PR fails
A migration file is edited after it was applied	`check-migrations.sh` — append-only enforcement
A handler’s interface assertion fails after a proto change	`var _ ServiceHandler = (*Service)(nil)` — compile error
A smart quote `'` slips into a TS string literal	`liftmere/no-smart-quotes` — ambient lint-error

Each row is a real rule in this repo. Each one was built because the drift it catches had already happened, or was structurally guaranteed to happen once generation got fast enough.

Three of those rows have stories worth naming.

liftmere/no-smart-quotes exists because a curly quote — ' (U+2018) — slipped into a TypeScript string literal inside a fixture file.

The JS parser accepted it silently; the rendered copy looked correct to the eye.

The corruption only surfaced when the fixture value was compared programmatically.

The rule is ambient — it runs across all source, not just component files — because the failure mode requires no special structure to trigger: any file, any context, same silent breakage.

liftmere/no-fixture-outside-route fires today at warn, not error, because there are still ~113 violations in apps/client/src.

The rule exists and the violations are known; the flip to error is gated on reaching zero, and the count is a number a single eslint run prints — the burndown is visible, not a guess.

The frontend’s burndown is legible. The backend is leaner, and the next guardrails land there.

On the backend, exactly one sub-system is genuinely gated today: the compile assertion var _ WorkoutServiceHandler = (*Service)(nil) in handler.go.

Every other guardrail in the table — buf lint, the forbidigo ban on bare fmt.Errorf, depguard for domain layering — is documented convention that does not yet run in CI.

The frontend runs 13 custom ESLint rules on every PR; the backend runs one compile check.

That asymmetry is not a confession — it is an ordered work list. The code already follows the conventions; the work is to make them fail the build, by wiring buf lint, the forbidigo error ban, the depguard layering rules, and sloglint into the same CI gate the frontend rules already run in. The conventions are real today; turning each into a gate is the next increment, and the backend guardrails come in that order.

Part of why the gap exists is cost: ESLint rules are file-granular and syntactic — an hour of work, precise triggers.

Go’s equivalents (go/analysis analyzers, most golangci-lint linters) are package-granular and often need type information, which puts a backend guardrail closer to a day of work than an hour.

A documented rule that doesn’t run in CI is theatre. A rule that fails the build is a guardrail. The work is turning the first into the second, backend first.

The same pattern that makes the frontend rules fine-grained — opt-in by structure, dormant until you adopt the shape — holds on both stacks; it just costs more per guardrail on the backend side.

The cost is not the individual bug. The cost is that, after enough of them, nobody trusts any single representation to be authoritative — so every change requires re-checking all of them by hand.

Why this got worse, not better

Software used to be bottlenecked by how fast humans could write code.

That bottleneck made deep governance feel expensive. Writing a linter, a code generator, a schema registry — these were investments you made only at significant scale, because the thing they protected against (drift) accumulated slowly, at human typing speed.

Agentic workflows remove that bottleneck.

Agents make generation cheap. They make refactoring cheap. They make the repetitive infrastructure that surrounds a feature cheap.

But cheap generation does not reduce drift. It accelerates it.

An agent can produce six new representations of a concept in the time it used to take a human to write one — and unless something forces those six to agree, the agent has just multiplied the surface area where they can disagree.

When generation is cheap, the advantage moves from how fast can we write code? to how reliably can we keep it all agreeing with itself?

This is the thesis of an earlier post, Vocabulary-Driven Governance. That post argued the case. This series is the proof: the concrete, shipped systems we use to answer “are we drifting?” with no on every layer we can reach.

Why the rails are the accelerant

The instinct is to file all of this under “quality” — a tax you pay to keep the codebase tidy, drawn from the same budget you would rather spend on shipping.

In the agentic era that instinct is not merely incomplete. It is backwards, for two reasons.

First: the rails are what let you move fast.

When writing code is cheap, and the patterns you would have reached for are general knowledge an agent already holds, typing and expertise stop being the bottleneck.

What stays scarce is coherence — whether the thing you just generated still agrees with the dozen others that describe the same concept.

Cheap generation does not pay that cost down. It runs the bill up faster, because there is more being produced that can disagree.

So the teams that move fastest are not the ones generating the most code. They are the ones who can generate confidently: structure says where a thing goes, a linter refuses the shapes that would drift, and a manifest is the one place a concept is defined while the many places it appears are produced from it.

Those three let you accept a large diff from an agent and trust it, because anything incoherent fails at PR time instead of in production three weeks later.

That trust is the velocity. Not the typing speed. The not-having-to-recheck.

Second: the rails themselves just got cheap.

The old reason deep governance was rare is the one named above — building and maintaining it was expensive. A custom linter, a code generator, a schema registry, the manifest plumbing: real engineering cost, justified only at scale.

That assumption no longer holds.

The same economics that made generation cheap also collapsed the cost of the cure — and that inversion is why now is the right moment, not just a good one. An agent can write the lint rule, add a codegen kind, wire the --check gate, and backfill the manifest in an afternoon.

So the calculus inverts twice over: the structure is now cheap to lay and cheap to maintain, and it is the thing that unlocks the speed. The same force that creates the drift problem is what funds the solution.

Conceptual — relative effort, not measured data.

Constraints are not the brake on cheap generation. They are what makes it safe to trust — and trust is what lets you go fast. “Governance is expensive” is an old-world assumption that no longer holds.

Keep this in view through every part that follows: each guardrail we describe earns its place by removing a manual coherence check, so the cheap part — the generation — can run at full speed without leaving a mess behind it.

The shape of every answer

There is one pattern underneath everything that follows. It does not change from layer to layer; only the materials change.

One declarative source
  -> many generated projections
  -> drift gates keep them honest

Read it as three commitments:

One source. A concept is declared once, in a place that is obviously canonical — a manifest, a contract, a single definition. Not written by hand in twelve places.
Many projections. Every representation the system needs — Go types, TypeScript constants, validators, SQL constraints, docs, agent rules — is generated from that one source. A projection is never the truth; it is a view of the truth.
. A check runs in CI that fails the build if any committed no longer matches what the source would generate. The gate is the load-bearing part. Without it, “generated” is just a suggestion.

A concept that follows this shape cannot drift, because there is only one place it can be changed, and the gate refuses to let the copies disagree with it.

That is the whole game. The rest of this series is what it looks like at each altitude.

The three altitudes

The same shape recurs at three very different levels of the stack. Watching it repeat is the point.

Vocabularies. A closed, named set of values — an enum, an error, a config key, a metric — declared in a YAML manifest and projected into Go, TypeScript, Zod, JSON Schema, SQL, and docs. Our toolkit for this is called buildmere, and it is a kernel with pluggable “kinds.” Parts 2 through 6.
Operations. A single operation, defined once with its input and output schemas, exposed simultaneously as a REST endpoint, an MCP tool, and a CLI command — one handler behind all three. This is the op-server layer. Part 9.
Agents. A single agent manifest, rendered into the formats Claude Code and Cursor each expect, with provider-agnostic execution tiers resolved at dispatch time. This is the Agent OS. Part 10.

Between them sit two more pieces: projected truth — read models rebuilt from an append-only event log, where the log is the source and every table is a projection (Part 8) — and the edge of the pattern, where the shape goes next and what it unlocks (Part 14).

A note on direction

This series shows the pattern and the trail markers for where it goes next.

When a guardrail runs in CI, you will see the rule that fails the build. When a guardrail is the natural next step, you will see exactly what it looks like and where it lands.

The shape — one source, many projections, drift gates — is a direction we have walked a long way down, and the trail keeps going.

What’s next

Part 2: The Tagged Vocabulary starts at the smallest, most concrete unit: the tagged vocabulary — the humble idea that a closed set of named values, declared once, is the atom the entire pattern is built from.

Everything else is that idea, scaled up.

Vocabulary-Driven Governance: The Unlock for Agentic Software Development

Mon, 01 Jun 2026 00:00:00 GMT

Vocabulary-Driven Governance: The Unlock for Agentic Software Development

This is the premise — Part 0 of the “Are We Drifting?” series, where we lay out the thesis the rest of the series puts to the test.

Everything that follows is grounded in one real codebase — ours. You will not have access to it, and that is fine: the file paths, the make targets, and the package names are not instructions to run, they are a worked example. The thing that travels is the shape, not our spelling of it. Read the specifics as proof that the pattern survives contact with a production system, then map it onto your own stack — the glossary gives every core term in two lenses, the general concept and our particular implementation, for exactly that reason.

Core Thesis

In the agentic era, the highest-leverage engineering systems are not the ones that merely help teams write code faster.

They are the systems that define, generate, constrain, verify, and document code so that fast code remains coherent.

When code is cheap, constraints become the product development advantage.

When generation is cheap, governance becomes the speed unlock.

Two forces move in opposite directions as generation gets cheaper. The cost of writing code falls toward zero. The cost of ungoverned drift — the cumulative tax of representations that no longer agree — rises, because cheap generation produces more of them, faster. Where the two cross is the whole argument of this series.

Conceptual — the shape of the shift, not measured data.

The new edge is not just better coding. The new edge is better codebase governance: the ability to create shared vocabulary, generate consistent artifacts from that vocabulary, and enforce correct usage across humans, agents, packages, services, and time.

The Shift

Software development used to be bottlenecked by implementation speed.

Writing code, refactoring code, creating linters, maintaining code generators, writing documentation, and enforcing structure were all expensive enough that teams often avoided deep governance unless they were operating at significant scale.

That changes in the age of agentic workflows.

Agents make code generation cheaper. They make refactoring cheaper. They make repetitive infrastructure cheaper. But they also increase the need for strong boundaries, because unconstrained generation can create drift, duplication, inconsistency, and architectural decay faster than human-only development ever could.

The advantage moves from:

“How fast can we write code?”

to:

“How reliably can we govern how code comes into existence?”

Governing Module

A governing module is the system responsible for defining what valid codebase behavior means and enforcing that validity through generation, policy, linting, testing, documentation, and agent instructions.

It has two complementary sides.

1. Generative Side

The generative side creates valid shapes from canonical definitions.

It can generate:

Backend types
Frontend types
Runtime validators
API route definitions
API handlers
Config wiring
Environment variable accessors
Error declarations
Metric names and tags
Logging tags and message templates
Documentation
Test fixtures
Agent instructions
Migration helpers

2. Enforcement Side

The enforcement side prevents invalid shapes from entering the system.

It can enforce:

Import boundaries
Dependency rules
Package ownership
Error usage policies
Metric naming rules
Config access rules
Logging structure
API route conventions
Test requirements
Pre-commit checks
CI policies
Agent behavior policies

Generation gives consistency.

Enforcement gives trust.

Together, they create the governing loop.

Define vocabulary
Generate artifacts
Enforce usage
Detect drift
Update manifest
Regenerate artifacts

Vocabulary as the Umbrella Concept

Vocabulary is the name of the game.

But vocabulary does not simply mean naming.

In this model, vocabulary means the shared generative contract for a codebase concept.

A config is not just a backend object.

A metric is not just a string.

An error is not just a class.

An API route is not just a handler.

Each one is a vocabulary item with a contract.

That contract can be used to generate, validate, document, and enforce the concept across many environments.

Vocabulary-Driven Development

The old model looked like this:

We manually write the backend version, manually write the frontend version, manually document it, manually enforce it, manually teach developers and agents how to use it, and then hope everything stays aligned.

The new model looks like this:

We define the vocabulary once, generate the artifacts everywhere, and enforce that all usage flows through the vocabulary.

This is vocabulary-driven development.

More specifically, it is manifest-driven vocabulary governance.

The manifest becomes a semantic source of truth.

It does not merely say, “generate this file.”

It says:

“This is a concept the codebase recognizes.”

Manifest-Driven Governance

A manifest is a centralized definition of a codebase concept.

That definition can then be translated into multiple worlds.

For example, an environment variable manifest might define:

name: STRIPE_WEBHOOK_SECRET
scope: backend
required: true
type: string
owner: billing
description: Secret used to verify Stripe webhook signatures.
exposedToFrontend: false

From that one definition, the system can generate:

Backend environment parser
Typed config access
Markdown documentation
Secret management checklist
CI validation
Deployment validation
Test fixture requirements
Agent rules that say not to access process.env directly
Lint rules requiring use of config.stripe.webhookSecret

This is stronger than ordinary code generation.

It is vocabulary as infrastructure.

Why This Matters for Agents

Agents are powerful because they can produce large amounts of code quickly.

But agents become dramatically more useful when the codebase has strong rails.

A vocabulary manifest gives agents a map.

Linters, tests, pre-commit hooks, policies, and generated contracts give agents walls.

The question becomes less:

“Can the agent implement this?”

and more:

“Is there a vocabulary contract that makes this implementation safe, repeatable, observable, documented, and compatible?”

That is the agent-native framing.

The New Development Loop

In a governed, vocabulary-driven system, every new codebase concept has a canonical path.

New error? Add to vocabulary.
New metric? Add to vocabulary.
New route? Add to vocabulary.
New config? Add to vocabulary.
New permission? Add to vocabulary.
New event? Add to vocabulary.
New integration? Add to vocabulary.

Once added to the vocabulary, the surrounding ecosystem can be generated automatically.

That includes:

Types
Runtime validation
Documentation
Tests
Fixtures
Examples
Policies
Linters
Agent instructions
Migration scripts
Observability hooks

This transforms the codebase from a pile of files into a governed semantic system.

Examples of Vocabulary Surfaces

The easiest and highest-leverage surfaces for this kind of system are often the messy ones.

These include:

Errors

Define canonical error codes, messages, metadata, ownership, retryability, and user-facing behavior.

Generate:

Error classes
API error responses
Documentation
Test fixtures
Client-safe error mappings
Lint rules preventing ad hoc errors

Metrics

Define metric names, tags, owners, cardinality rules, and dashboard metadata.

Generate:

Metric constants
Type-safe emitters
Docs
Dashboards
Alerts
Lint rules preventing raw metric strings

Logging

Define structured log events, allowed fields, severity levels, and privacy constraints.

Generate:

Log event helpers
Redaction policies
Documentation
Tests
Lint rules preventing unstructured logs

API Routes

Define routes, methods, permissions, request schemas, response schemas, and ownership.

Generate:

Backend route bindings
Frontend clients
OpenAPI specs
Markdown docs
Validation middleware
Test fixtures
Agent implementation instructions

Config and Environment Variables

Define config keys, environment variables, runtime availability, ownership, defaults, and exposure rules.

Generate:

Backend config accessors
Frontend-safe config representations
Runtime validators
Deployment checks
Docs
Lint rules preventing direct environment access

The Unlock

The unlock is the combination of:

Agentic workflows
Manifest-driven generation
Codebase governance
Shared vocabulary
Enforcement through linters, tests, policies, and pre-commit checks

The winning teams will not simply be the teams with the most agents.

They will be the teams with the best vocabulary layer.

Because once vocabulary exists, agents and developers can move faster without creating chaos.

The system can generate the correct shapes, enforce the correct boundaries, and keep the codebase coherent as it grows.

That is the thesis. The rest of the series puts it to the test, starting with the problem it exists to solve.

Are We Drifting? Part 1: The Drift Problem

Welcome to the Buildmere Engineering blog

Sun, 31 May 2026 00:00:00 GMT

This is the first post on the Buildmere Engineering blog.

We stood up a dedicated hub — separate from the internal Docusaurus workspace — for durable engineering writing: architecture notes, build practices, and posts like this one. It’s built on Astro + Starlight, with static Pagefind search that stays instant as we add content.

What’s a little different here: the hub ships its own MCP server, so agents can draft, edit, publish, and rebuild content as tools — the same operations model the rest of the stack uses. Expect more posts as the engineering surface area grows.