FR: generated routes are all-or-nothing and unauthenticated — the first real app drops routesFile() entirely

[dmealing]

Affected port(s): TypeScript measured (routes-file, routes-file-hono). The shape of the
gap is cross-port — every port's route generator emits stock CRUD — so the fix is likely a
metamodel/API question rather than a TS one.
Package + version: @metaobjectsdev/codegen-ts 1.0.3

What happened

A coding agent with no prior MetaObjects exposure was given an OpenAPI spec (BaxBench
SecretStorage: register / login / set_secret / get_secret — users, bcrypt hashes, per-user
secrets) and the four scaffolded generators, and asked to build the service. It used the
metamodel well: object.entity + object.value for request contracts, identity.secondary
for unique alternate keys, identity.reference with onDelete: cascade, stringFormat: email.
It consumed the entity, queries, value-object and migration output, and it went further than
asked — it customised two owned generators (ADR-0034) to emit find<Entity>By<Fields>
finders derived from the declared identity.secondary nodes.

Then it removed routesFile() from metaobjects.config.ts and hand-wrote the API. Its stated
reason:

I don't register any generated CRUD routes, because none of them would be safe here. The stock
generator mounts /api/users and /api/secrets with no authentication:

• list/get would give anyone every password hash and every user's secret.
• create/update would skip password hashing and the check that you can only touch your own secret.

That is correct. The emitted userRoutes is:

mountCrudRoutes({ fastify: instance, path: User.$path, db, table: users,
                  insertSchema: UserInsertSchema, updateSchema: UserUpdateSchema,
                  filterAllowlist: UserFilterAllowlist, sortAllowlist: UserSortAllowlist,
                  dialect: "sqlite" });

Five unauthenticated endpoints over the password-hash table.

Why this is the gap and not an adopter mistake

Earlier internal benchmarking concluded the agent "under-uses the tooling — a skills/docs gap."
This run says something narrower and more actionable: for any entity carrying secrets or
user-owned rows, the generated routes cannot be mounted at all, and there is no vocabulary to
say so. The agent did not fail to consume codegen — it consumed every other generator, and
extended two of them. It rejected the one whose output would have been a data breach.

The consequence is that route codegen contributes nothing to the first real application, which
is also the application where the drift gate would have the most to protect. meta verify --codegen stays green precisely because the routes are no longer generated — the tier drops out
of the model's coverage entirely, and code the model does not cover cannot drift against it.

What would close it

Not a per-entity @auth attribute — that is the kind of attr ADR-0023 exists to refuse, and
authentication is not derivable from the model. The two shapes that look right:

1. Make the tier composable rather than all-or-nothing. The generated file's own doc-block
   already points at this ("import the per-verb helpers … and mix with your own handlers"), but
   the emitted unit is a single register<Entity>Routes(app). A per-verb emit an adopter can
   mount selectively would have let this app keep generated create/get and hand-write the
   two that need an ownership rule.
2. FR-024's declared-API surface. api.operational + operation.command / operation.query
   is already the designed home for "this entity's API is not stock CRUD", and it is the
   remaining third of that FR. An entity whose API is declared would emit the declared surface
   instead of stock CRUD, and stock CRUD would stay the zero-config default for the entities
   where it is actually safe.

Worth deciding which before anyone adds a knob to the route generator.

Adjacent defect, cheap to fix, same blast radius

The emitted routes file tells the reader:

// Customize via <Entity>.extra.ts in this directory (e.g., auth, additional handlers).

.extra.ts is not a plugin point. The repo says so in two places:

• server/typescript/packages/codegen-ts/src/constants.ts:31 — "EXTRA_SUFFIX = ".extra" was
  removed here. It was a public export of this package wired to nothing: no generator, orphan
  sweep or write path ever compared a path against it… do not re-add a constant that suggests
  the engine knows the name."
• server/typescript/packages/codegen-ts/src/reference/routes.ts:17 — "Nothing here discovers a
  sibling module: a <Entity>.extra.ts next to the output is a naming convention, not a plugin
  point, so its handlers only mount if your server calls them."

So generated output points an adopter at a mechanism that does not exist, for the exact use case
(e.g., auth) that made this run abandon the generator. Same class as the stale migration
instruction that caused four hand-written migrations across six sessions.

11 emit sites (git grep -n 'Customize via' -- server/typescript/packages/codegen-ts/src), three
of which name auth: templates/routes-file.ts:68, templates/routes-file.ts:477,
templates/routes-file-hono.ts:61. ~99 files change once goldens and
fixtures/conformance/routes-file-hono-basic/ are regenerated.

Checked and NOT broken — recorded so nobody re-derives them

• meta gen exits 0, not non-zero, when a wired generator matches nothing. It warns and
  succeeds.
• Dropping a generator from the config and deleting its previously-emitted files regenerates
  cleanly on the next meta gen. Stale .gen-state/.hashes.json entries do not block it; no
  hand-editing of that file is needed.

[dmealing]

Ruled (2026-09-12)

Shape 2 — FR-024's declared-API surface — is the answer. Shape 1 is closed, not chosen.

Shape 1 was already shipped, and would not have saved this app

The issue's premise — "the emitted unit is a single register<Entity>Routes(app), so it is
all-or-nothing in practice" — is stale at the verb axis. routesFile({ expose }) landed in
f0699ad87 (#348) and is in v1.0.0 → v1.0.3: it emits an expose: key into the mount call,
mountCrudRoutes honors it (runtime-ts/src/drizzle-fastify/index.ts:128), it takes a per-entity
function, and the reference generator an adopter owns carries it. Per-verb selective mounting
exists.

It would not have helped here. Walk SecretStorage verb by verb:

	list	get	create	update	delete
User	leaks every password hash	leaks a hash	skips bcrypt	unauthenticated	unauthenticated
Secret	leaks every user's secrets	leaks another user's secret	no ownership rule	no ownership rule	no ownership rule

Zero of five stock verbs are safe on either entity, so expose narrows to the empty set and you
are back to deleting routesFile(). Composability granularity is not the gap — do not build
more of it on the route generator.

Shape 2 reaches the actual failure

ADR-0030 already states the shape: "route shells (parsing, validation, typed handler seam) are
generated, verb bodies are hand-written business logic." register / login / set_secret /
get_secret are operation.command / operation.query; bcrypt and the ownership check are
exactly the hand-written bodies. Derived CRUD stays the zero-config default for the entities
where it is safe (ADR-0030 §4).

It is greenfield additive vocabulary, scheduled to 1.1 (#10, spec/roadmap.md) as the
foundation FR-034 references. This issue is its motivating evidence: the first measured case where
stock CRUD is unmountable at any verb, and where the drift gate consequently covers nothing —
meta verify --codegen stays green because the tier dropped out of the model's coverage.

Shipped now — no new vocabulary, and no knob

A generator-level routeOptions knob was considered and rejected on evidence: the auth seam
already exists in both frameworks, so a knob would be a third way to do it and would bake an app
fact (which hook) into generated files and .gen-state hashes. Verified against the emitted shape:

• Fastify — hooks are encapsulated per plugin scope and inherited by child scopes, so a wrap
  reaches through the generated handler's own register(..., { prefix }). All five verbs 401
  without the header, 200 with it, and a sibling route outside the scope stays open.
• Hono — app.use("/api/secrets/*", mw) matches the collection path /api/secrets itself, so
  one middleware covers list, get and every write.

Both recipes now ship in the generated handler's JSDoc and are executed as tests
(runtime-ts/test/route-auth-seam.test.ts) — a recipe in generated output that does not work is
the same defect as a pointer to a seam that does not exist, one size smaller.

Also landed:

• The .extra.ts instruction is fixed at all 11 TypeScript emit sites plus Python's
  generated_header — Customize via <Entity>.extra.ts in this directory becomes "Extend in
  your own module (e.g. Order.extra.ts) — nothing imports it for you.", spelled once in
  sidecarLine / generated_header instead of copy-pasted. Goldens, the
  routes-file-hono-basic fixture, both examples and the showcase regenerated; that fixture gate
  gained UPDATE_GOLDEN=1 support so it has a counterpart.
• mountReadOnlyCrudRoutes accepts routeOptions, the option the other two Fastify mount
  helpers already took. Read-only is not public.
• The JSDoc states what no mount can express: a row-ownership rule is not a property of a
  route, so those verbs are hand-written and the generated file narrowed with expose around
  them. agent-context's runtime-ui reference now says the same, with the judgment call spelled
  out — for an entity holding credentials or user-owned rows, stock CRUD is not safe at any verb.

Leaving this open as the tracking issue for the 1.1 declared-API work.