create-substrat 0.9.5 → 0.9.7

package/index.js

@@ -36,11 +36,11 @@ const TEMPLATE = join(HERE, 'template');
 // The runtime packages release together off one version line (the changesets `fixed`
 // group), so one constant is right for all of them. Engines do NOT share a line —
 // each versions on its own, so one pin per engine, deliberately.
-const SUBSTRAT = '^0.110.0';
-const ENGINE_WORKORDER = '^0.11.9';
-const ENGINE_INVOICING = '^0.10.0';
+const SUBSTRAT = '^0.112.0';
+const ENGINE_WORKORDER = '^0.11.11';
+const ENGINE_INVOICING = '^0.10.2';
 const BOUNDARY_LINT = '^0.4.2';
-const DEV_ISSUER = '^0.1.25';
+const DEV_ISSUER = '^0.1.27';
 
 const DOCS = 'https://substrat.net';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-substrat",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "description": "Scaffold a Substrat vertical — `npm create substrat <dir>`.",
   "license": "Apache-2.0",
   "repository": {

package/template/.substrat/hooks/session-start.mjs

@@ -20,7 +20,7 @@
  * not in `.claude/`. `.claude/settings.json` is a three-line adapter that runs it,
  * and any other client that grows a session hook binds the same way. It also
  * means the plugin distribution (#753) ships this script unchanged rather than
- * forking it: `plugin/substrat/scripts/session-start.mjs` is emitted from this
+ * forking it: `plugin/substrat/scripts/session-start.generated.mjs` is emitted from this
  * file byte-for-byte, and `pnpm lint:plugin --check` fails if the two diverge.
  *
  * The plugin copy is what reaches a project scaffolded before this hook existed.

package/template/.substrat/playbook.md

@@ -324,7 +324,7 @@ to make the build pass.
 ## Step 6 — Reshape the reference
 
 The design is approved. The scaffold already contains a working vertical in `src/` + `test/` —
-the bike-repair shop. **Read it first** (it's your Callout: the real, green implementation of
+the bike-repair shop. **Read it first** (it is your reference: the real, green implementation of
 every pattern this step describes), then reshape it into the user's domain from the approved
 `spec/concept.md`:
 

package/template/AGENTS.md

@@ -46,20 +46,29 @@ src/migrations.ts      the SqlMigration[]                         ← module cod
 src/module.ts          the handlers, bound to the declaration      ← module code
 src/provision.ts       MODULES, ROLES, grant shapes — node-free    ← module code
 src/seed.ts            host, tenants, demo cast, seed world        ← harness
-src/routes.ts          the HTTP route table — BOTH hosts mount it   ← harness
+src/personas.ts        the dev cast, read by the issuer and the seed ← harness
+src/routes.ts          the routes, DERIVED from the operations     ← harness
 src/server.ts          the dev entrypoint (node + persona picker)   ← harness
 src/worker.ts          the deployable Cloudflare worker             ← harness
 src/config-do.ts       per-instance config store (Cloudflare only)  ← harness
 test/scenario.test.ts  the scenario — including the denials
+test/entities.test.ts  the registry, held to the tables it migrates
 ```
 
-**A new route goes in `src/routes.ts`, never in an entrypoint.** Both `server.ts`
-and `worker.ts` mount that one table, so a route added there is live on both — and
-a route added to only one is a surface that works in dev and 404s in production
+**A new route is an `http` declaration on its operation, never a handler in an
+entrypoint.** `src/routes.ts` holds no table: `mountOperations` (from
+`@substrat-run/vertical-host`) derives one from the `http` each operation in
+`src/operations.ts` declares — method, path, and which input fields the path
+carries, compile-checked there — and both `server.ts` and `worker.ts` mount that
+one derivation, so a route is live on both the moment it is declared. A route
+added to only one entrypoint is a surface that works in dev and 404s in production
 (or the reverse), which nothing catches until you deploy: the scenario tests call
-operations directly and never boot either host. What an entrypoint may still own
-is only what is genuinely its own — building a host, resolving a caller, and its
-own auth-shaped route (`/api/cast` in dev, `/api/me` in the worker).
+operations directly and never boot either host. A composed engine's operations
+carry no `http` of their own (an engine does not own a URL shape), so the vertical
+binds them with `defineEngineRoutes` beside its own declarations. What an
+entrypoint may still own is only what is genuinely its own — building a host,
+resolving a caller, and its own auth-shaped routes (`/api/auth/*` and `/api/me`
+in dev, `/api/me` in the worker).
 
 `provision.ts` is deliberately node-free: both hosts register from it (the dev
 server's SQLite host and the worker's `ScopeDO`), and `substrat push` reads the
@@ -149,6 +158,12 @@ same object feeds `operationInputs: operationInputsOf(bikeShopOperations)`, so t
 schemas the host parses with are the ones the declaration states — they cannot drift,
 because there is only one of them.
 
+The permission list works the same way. `SHOP_PERMISSIONS`, the array handed to
+`defineOperations`, is also the `keys` that `src/provision.ts` hands
+`definePermissions({ modules, roles, entityGrants, keys })` — and `definePermissions`
+throws at module load if those keys and `MODULES` disagree in either direction. Hand
+both readers the same array; a second copy is a list that drifts.
+
 **A list read must declare `paged`.** `defineOperations` refuses a bare-array `output`
 that does not, and it refuses it at module load — so it fires in every build, every
 test and every dev server rather than in a lint tool that has to find you. A list
@@ -161,15 +176,17 @@ walk, a table the registry does not carry — the handler composes its own and n
 field the cursor walks (`paged: { sortKey: 'article' }`). Keyset, never offset: on
 live data an offset shifts between requests, so pages drop and duplicate rows.
 
-**A paged read has an HTTP half, and this route table is hand-written.** The
+**A paged read has an HTTP half, and the derived route does it for you.** The
 operation answers with a `Page<T>` — it is transport-agnostic, and a test or a seed
-must be able to walk a list with no response to read headers off — so `src/routes.ts`
-does the projection at the edge: it forwards the page trio in (`pageInput`) and hands
-the entries back as the body with the walk in a `Link` header (`pageJson`). Forget the
-first and the endpoint is pinned to page one no matter what the operation supports;
-forget the second and it answers with an envelope where it used to answer with an
-array. Both helpers are already in `src/routes.ts` — use them for every route that
-invokes a paged operation, the engines' list reads included.
+must be able to walk a list with no response to read headers off — so the projection
+happens at the edge: `mountOperations` forwards the page trio in (`limit`, `cursor`,
+`order`, parsed with the platform's own defaults and ceiling) and hands the entries
+back as the body with the walk in a `Link` header. Declare `http` on the paged
+operation and both halves are there; hand-mount a paged read yourself and you have
+to do both by hand — forget the first and the endpoint is pinned to page one no
+matter what the operation supports, forget the second and it answers with an
+envelope where it used to answer with an array. That is the case for not
+hand-mounting anything an operation can declare.
 
 ## The rules (non-negotiable)
 

package/template/src/operations.ts

@@ -1,10 +1,17 @@
-import { defineOperations, money, timelineEntry, z } from '@substrat-run/contracts';
-import { billableLine, workOrder, workorderEntities } from '@substrat-run/engine-workorder';
+import { defineEngineRoutes, defineOperations, money, timelineEntry, z } from '@substrat-run/contracts';
+import { invoicingOperations } from '@substrat-run/engine-invoicing';
+import {
+  billableLine,
+  workOrder,
+  workorderEntities,
+  workorderOperations,
+} from '@substrat-run/engine-workorder';
 import { bikeShopEntities } from './entities.js';
 
 // ============================================================================
 // The bike shop's DECLARED OPERATION SURFACE — what each operation accepts,
-// what it answers with, and which permission gates it.
+// what it answers with, which permission gates it, and where it lives in the
+// HTTP API.
 //
 // This is one declaration, not documentation of another one. `src/module.ts`
 // binds its handlers to this object with `satisfies OperationImpl<…>`, so four
@@ -12,7 +19,10 @@ import { bikeShopEntities } from './entities.js';
 // disagrees with `input`, one whose return disagrees with `output`, an
 // operation declared and not implemented, and one implemented and not declared.
 // `operationInputsOf(bikeShopOperations)` hands the host the same schemas, so
-// every invocation is parsed before the guards and the handler.
+// every invocation is parsed before the guards and the handler — and
+// `mountOperations` (src/routes.ts) derives the route table from the `http`
+// each operation declares, so a `{var}` in a path that names no input field is
+// a compile error too, and there is no second list of routes to drift.
 // ============================================================================
 
 /**
@@ -100,10 +110,12 @@ export const bikeShopOperations = defineOperations(
     }),
     // The row shape comes from the registry — not restated here.
     output: bikeShopEntities.customer.fields,
+    http: { method: 'POST', path: '/customers' },
   },
   'shop/list-customers': {
     summary: 'List customers with the bikes they have registered',
     permission: 'customer:manage',
+    http: { method: 'GET', path: '/customers' },
     // The ENTRY, not the envelope — `paged` wraps it. The page also BOUNDS the
     // hydration: one bikes query per customer ON THE PAGE, where an unpaged read
     // ran one per customer in the scope.
@@ -124,6 +136,8 @@ export const bikeShopOperations = defineOperations(
       frameNo: z.string().min(1).optional(),
     }),
     output: bikeShopEntities.bike.fields,
+    // `{customerId}` must name an input field, and the compiler checks that it does.
+    http: { method: 'POST', path: '/customers/{customerId}/bikes' },
   },
   'shop/upsert-price': {
     summary: 'Create or update a price-list article',
@@ -138,11 +152,13 @@ export const bikeShopOperations = defineOperations(
       internal: z.boolean().optional(),
     }),
     output: priceRow,
+    http: { method: 'POST', path: '/prices' },
   },
   'shop/price-list': {
     summary: 'The workshop price list',
     permission: 'customer:manage',
     output: priceRow,
+    http: { method: 'GET', path: '/prices' },
     // Handler-composed rather than `over`: `shop_price_list` is value-keyed and
     // deliberately not a declared entity, so the registry has no table for the
     // kernel to index. It still pages, and still carries a cursor.
@@ -163,18 +179,21 @@ export const bikeShopOperations = defineOperations(
     // and NOT the row: the engine stores `facility_type`/`facility_id` as two
     // snake_case columns and publishes one `EntityRef` in camelCase.
     output: workOrder,
+    http: { method: 'POST', path: '/repairs' },
   },
   'shop/complete-repair': {
     summary: 'Complete a repair and price its billable lines',
     permission: 'workorder:complete',
     input: z.object({ orderId: z.string().min(1) }),
     output: z.object({ order: workOrder, billable: z.array(billableLine), total: money }),
+    http: { method: 'POST', path: '/repairs/{orderId}/complete' },
   },
   'shop/close-repair': {
     summary: 'Hand the bike back — completed to closed',
     permission: 'workorder:close',
     input: z.object({ orderId: z.string().min(1) }),
     output: workOrder,
+    http: { method: 'POST', path: '/repairs/{orderId}/close' },
   },
   'shop/portal-repairs': {
     summary: 'The repairs visible to the calling portal customer',
@@ -195,6 +214,7 @@ export const bikeShopOperations = defineOperations(
     // compose. It pages by OVER-fetching, so a SHORT page does not end the walk
     // — only an absent cursor does.
     paged: { sortKey: 'id' },
+    http: { method: 'GET', path: '/portal/repairs' },
   },
   'shop/timeline': {
     summary: 'The event timeline for one repair',
@@ -213,5 +233,46 @@ export const bikeShopOperations = defineOperations(
     // The cursor is `id` — the event's ULID, which IS this entity's version at
     // that point.
     paged: { sortKey: 'id' },
+    // The path carries `entityId` alone. `entityType` is the literal above, and
+    // `mountOperations` PINS a literal — it goes into the payload before anything
+    // the caller sent, so a caller cannot talk this route into another entity type.
+    http: { method: 'GET', path: '/repairs/{entityId}/timeline' },
   },
 });
+
+/**
+ * Where the composed engines' operations live in this vertical's API.
+ *
+ * An engine declares no `http`, and should not: it is entity-agnostic and does
+ * not own a URL shape — this shop calls a work order a repair, and the path is
+ * the shop's decision. A binding is a name and a path; the summary, the input
+ * schema and the return shape all come from the engine, so nothing here
+ * restates anything. Bind a `{var}` the engine's input does not accept and it
+ * does not compile; bind a name the engine does not have and it throws when the
+ * module loads.
+ *
+ * `workorder/complete` and `workorder/close` are deliberately NOT bound: the
+ * shop wraps them (`shop/complete-repair` owns the pricing moment,
+ * `shop/close-repair` the handback) and a route straight to the engine would
+ * skip that. Which operations are the vertical's and which are the engine's,
+ * invoked directly, is the composition boundary — visible right here.
+ */
+export const bikeShopEngineRoutes = defineEngineRoutes(workorderOperations)({
+  'workorder/list': { method: 'GET', path: '/repairs' },
+  'workorder/get': { method: 'GET', path: '/repairs/{orderId}' },
+  'workorder/assign': { method: 'POST', path: '/repairs/{orderId}/assign' },
+  'workorder/start': { method: 'POST', path: '/repairs/{orderId}/start' },
+  'workorder/report-time': { method: 'POST', path: '/repairs/{orderId}/time' },
+  'workorder/report-material': { method: 'POST', path: '/repairs/{orderId}/material' },
+});
+
+/**
+ * The invoicing engine's operations (the sibling engine, fed by event). All
+ * three, because this engine's callable surface is reads and one export — there
+ * is nothing to create, so there is no constant for the shop to pin.
+ */
+export const bikeShopInvoicingRoutes = defineEngineRoutes(invoicingOperations)({
+  'invoicing/list': { method: 'GET', path: '/invoicing' },
+  'invoicing/get': { method: 'GET', path: '/invoicing/{underlagId}' },
+  'invoicing/export': { method: 'POST', path: '/invoicing/{underlagId}/export' },
+});

package/template/src/routes.ts

@@ -1,92 +1,53 @@
 import type { Context, Hono } from 'hono';
-import { problemResponse } from '@substrat-run/vertical-host';
-import {
-  isPage,
-  listPageQuery,
-  LIST_SORT_PARAM,
-  nextPageLink,
-  PAGE_LINK_HEADER,
-  PAGE_TOTAL_HEADER,
-} from '@substrat-run/contracts';
-import type { ScopeStub } from '@substrat-run/kernel';
+import { mountOperations, problemResponse, type ResolveStub } from '@substrat-run/vertical-host';
+import { bikeShopEngineRoutes, bikeShopInvoicingRoutes, bikeShopOperations } from './operations.js';
 
 /**
- * The bike shop's HTTP API — ONE route table, adapter- and auth-agnostic.
+ * The bike shop's HTTP API — derived from the declared operations, adapter- and
+ * auth-agnostic.
  *
  * Both entrypoints mount this: `server.ts` (node, pure-SQLite adapter, OIDC against the
  * local dev issuer) and `worker.ts` (Cloudflare, Durable-Object adapter, the auth seam). Each
  * supplies a `resolveStub` that authenticates the caller its own way and returns a
- * capability `ScopeStub`; every route here is a thin wrapper over ONE operation, with
- * no business logic — the rules live in an operation or an engine.
+ * capability `ScopeStub`; every route is a thin wrapper over ONE operation, with no
+ * business logic — the rules live in an operation or an engine.
  *
  * Sharing the table is the point. A route added to only one entrypoint is a surface
  * that exists in dev and 404s in production (or the reverse), and nothing catches it
  * until deploy: the scenario tests call operations directly and never boot either host.
- * Add a route HERE and it is live on both.
- *
  * What each entrypoint still owns is only what is genuinely its own: how it builds a
- * host, how it resolves a caller, and its own auth-shaped routes (`/api/cast` in dev,
- * `/api/me` in the worker) — those answer "who am I on THIS host" and cannot be shared.
- */
-export type ResolveStub = (c: Context) => Promise<ScopeStub>;
-
-/**
- * The page trio, off the query string — what a route hands a PAGED operation.
+ * host, how it resolves a caller, and its own auth-shaped routes (`/api/auth/*` and
+ * `/api/me` in dev, `/api/me` in the worker) — those answer "who am I on THIS host"
+ * and cannot be shared.
  *
- * A paged read takes `limit`/`cursor` (and, where its declaration offers them,
- * `order`/`sort`) as ordinary input, so a route that forwards nothing pins its
- * endpoint to page one forever: the operation still pages, the caller just has
- * no way to say which page it wants. Parsed with the platform's own
- * `listPageQuery`, so this endpoint's default page size and its ceiling are the
- * same numbers every other list read on the platform uses — a hand-written route
- * table is not a licence to invent a second convention.
+ * ## Why there is no table here
  *
- * `order` and `sort` travel only when asked for, so the DECLARATION's own
- * defaults stay the answer when a caller says nothing.
+ * There was one, and every line of it restated something the operations already
+ * declare: the method, the path, which input fields the path carries, and — for a
+ * paged read — that the page trio must be forwarded in and the entries handed back
+ * as the body with the walk in a `Link` header. Two helpers held that last part
+ * together by hand, and every route that invoked a paged operation had to remember
+ * to call both. `mountOperations` derives all of it from the `http` each operation
+ * declares in `src/operations.ts`: it orders static path segments ahead of their
+ * parameter siblings, coerces query values per the declared shape, pins a
+ * `z.literal` input the caller must not choose, projects a `Page<T>` onto the wire,
+ * and turns the kernel's own refusals into their status. A new operation is on
+ * both hosts the moment it declares `http`, and there is no second list to drift.
  */
-function pageInput(c: Context): Record<string, unknown> {
-  const q = c.req.query();
-  const page = listPageQuery.parse({ limit: q['limit'], cursor: q['cursor'], order: q['order'] });
-  return {
-    limit: page.limit,
-    ...(page.cursor === undefined ? {} : { cursor: page.cursor }),
-    ...(page.order === undefined ? {} : { order: page.order }),
-    ...(q[LIST_SORT_PARAM] === undefined ? {} : { sort: q[LIST_SORT_PARAM] }),
-  };
-}
+export type { ResolveStub };
 
-/**
- * A page's answer on the WIRE: the entries are the body, the walk rides in
- * headers (`Link: <…?cursor=…>; rel="next"`, RFC 8288).
- *
- * The operation's own shape stays `Page<T>` — a test, a seed or another
- * operation must be able to walk a list with no HTTP response to read headers
- * off — so this is a projection at the edge, not a change to what the operation
- * returns. Adopting paging then costs a client nothing: a list endpoint returns
- * the array it always returned and gains a walk it did not have.
- *
- * `isPage` is CHECKED rather than assumed, so an operation that has not adopted
- * `pageOf` yet reaches the client unchanged instead of being emptied into a body
- * of `undefined`.
- *
- * This is the same projection `mountOperations` (@substrat-run/vertical-host)
- * performs for a declared surface. This route table is hand-written, so it does
- * it here — one helper, used by every paged read below.
- */
-function pageJson(c: Context, result: unknown): Response {
-  if (!isPage(result)) return c.json(result as never);
-  const link = nextPageLink(c.req.url, result.nextCursor);
-  if (link) c.header(PAGE_LINK_HEADER, link);
-  const total = (result as { total?: unknown }).total;
-  if (typeof total === 'number') c.header(PAGE_TOTAL_HEADER, String(total));
-  return c.json(result.entries as never);
-}
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function mountApi(app: Hono<any, any, any>, resolveStub: ResolveStub): void {
-  const S = resolveStub;
-  const body = (c: Context) => c.req.json<Record<string, unknown>>();
+/** Every operation that carries a URL: this vertical's own, and the two engines it composes. */
+const ROUTED = {
+  ...bikeShopOperations,
+  ...bikeShopEngineRoutes,
+  ...bikeShopInvoicingRoutes,
+};
 
+export function mountApi(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  app: Hono<any, any, any>,
+  resolveStub: ResolveStub,
+): { operation: string; method: string; path: string }[] {
   /**
    * One error vocabulary, shared with the platform surface: `problemResponse`
    * (@substrat-run/vertical-host) is built on the same `classifyError` that
@@ -105,115 +66,21 @@ export function mountApi(app: Hono<any, any, any>, resolveStub: ResolveStub): vo
    * it here is what gives `server.ts`, which mounts no platform surface, the same
    * behaviour.
    */
-  app.onError((err, c) => problemResponse(c, err));
+  app.onError((err, c: Context) => problemResponse(c, err));
 
-  // -- generic invoke ---------------------------------------------------------
-  // The kernel checks a permission inside EVERY operation, so a generic route is
-  // exactly as safe as one route per operation. It is the escape hatch that keeps a
-  // new operation reachable before it has a named route — on BOTH hosts, deliberately.
+  // The one hand-written route, registered BEFORE the derived table so the
+  // exception always wins. The kernel checks a permission inside EVERY operation,
+  // so a generic route is exactly as safe as one route per operation — and it is
+  // what keeps an operation reachable that has no URL of its own: an engine
+  // operation this vertical deliberately did not bind (`workorder/complete`, which
+  // `shop/complete-repair` wraps) is still callable here, on BOTH hosts.
   app.post('/api/invoke', async (c) => {
     const { op, input } = await c.req.json<{ op: string; input?: unknown }>();
-    return c.json((await (await S(c)).invoke(op, input)) ?? null);
+    return c.json((await (await resolveStub(c)).invoke(op, input)) ?? null);
   });
 
-  // -- customers, bikes, price list (the vertical's own tables) ---------------
-  app.get('/api/customers', async (c) =>
-    pageJson(c, await (await S(c)).invoke('shop/list-customers', pageInput(c))),
-  );
-  app.post('/api/customers', async (c) =>
-    c.json(await (await S(c)).invoke('shop/create-customer', await c.req.json())),
-  );
-  app.post('/api/customers/:id/bikes', async (c) =>
-    c.json(
-      await (await S(c)).invoke('shop/register-bike', {
-        customerId: c.req.param('id'),
-        ...(await body(c)),
-      }),
-    ),
-  );
-  app.get('/api/prices', async (c) =>
-    pageJson(c, await (await S(c)).invoke('shop/price-list', pageInput(c))),
-  );
-  app.post('/api/prices', async (c) =>
-    c.json(await (await S(c)).invoke('shop/upsert-price', await c.req.json())),
-  );
-
-  // -- repairs ---------------------------------------------------------------
-  // create/complete/close are the VERTICAL's operations (they wrap the engine and own
-  // the pricing moment); assign/start/report/get/list are the ENGINE's own, invoked
-  // directly. Which is which is the composition boundary, visible right here.
-  app.get('/api/repairs', async (c) =>
-    pageJson(
-      c,
-      await (await S(c)).invoke('workorder/list', {
-        status: c.req.query('status'),
-        ...pageInput(c),
-      }),
-    ),
-  );
-  app.post('/api/repairs', async (c) =>
-    c.json(await (await S(c)).invoke('shop/create-repair', await c.req.json())),
-  );
-  app.get('/api/repairs/:id', async (c) =>
-    c.json(await (await S(c)).invoke('workorder/get', { orderId: c.req.param('id') })),
-  );
-  app.get('/api/repairs/:id/timeline', async (c) =>
-    pageJson(
-      c,
-      await (await S(c)).invoke('shop/timeline', {
-        entityType: 'workorder',
-        entityId: c.req.param('id'),
-        ...pageInput(c),
-      }),
-    ),
-  );
-  app.post('/api/repairs/:id/assign', async (c) =>
-    c.json(
-      await (await S(c)).invoke('workorder/assign', {
-        orderId: c.req.param('id'),
-        ...(await body(c)),
-      }),
-    ),
-  );
-  app.post('/api/repairs/:id/start', async (c) =>
-    c.json(await (await S(c)).invoke('workorder/start', { orderId: c.req.param('id') })),
-  );
-  app.post('/api/repairs/:id/time', async (c) =>
-    c.json(
-      await (await S(c)).invoke('workorder/report-time', {
-        orderId: c.req.param('id'),
-        ...(await body(c)),
-      }),
-    ),
-  );
-  app.post('/api/repairs/:id/material', async (c) =>
-    c.json(
-      await (await S(c)).invoke('workorder/report-material', {
-        orderId: c.req.param('id'),
-        ...(await body(c)),
-      }),
-    ),
-  );
-  app.post('/api/repairs/:id/complete', async (c) =>
-    c.json(await (await S(c)).invoke('shop/complete-repair', { orderId: c.req.param('id') })),
-  );
-  app.post('/api/repairs/:id/close', async (c) =>
-    c.json(await (await S(c)).invoke('shop/close-repair', { orderId: c.req.param('id') })),
-  );
-
-  // -- the customer portal (the per-entity proof walk) ------------------------
-  app.get('/api/portal/repairs', async (c) =>
-    pageJson(c, await (await S(c)).invoke('shop/portal-repairs', pageInput(c))),
-  );
-
-  // -- invoicing (the sibling engine, fed by event) ---------------------------
-  app.get('/api/invoicing', async (c) =>
-    pageJson(c, await (await S(c)).invoke('invoicing/list', pageInput(c))),
-  );
-  app.get('/api/invoicing/:id', async (c) =>
-    c.json(await (await S(c)).invoke('invoicing/get', { underlagId: c.req.param('id') })),
-  );
-  app.post('/api/invoicing/:id/export', async (c) =>
-    c.json(await (await S(c)).invoke('invoicing/export', { underlagId: c.req.param('id') })),
-  );
+  // Returns what it mounted, in registration order — a test pins the complete
+  // method/path set, so a derived table that mounted nothing, moved a path or
+  // changed a verb fails loudly rather than passing over an empty app.
+  return mountOperations(app, ROUTED, resolveStub);
 }

package/template/src/worker.ts

@@ -314,7 +314,7 @@ app.all('/api/*', (c) => c.json({ error: `unknown route: ${new URL(c.req.raw.url
 app.all('*', (c) =>
   c.json({
     service: 'substrat vertical',
-    api: 'POST /api/invoke { op, input } — plus the named routes in src/routes.ts',
+    api: 'POST /api/invoke { op, input } — plus the routes declared on the operations in src/operations.ts',
     docs: 'https://substrat.net',
   }),
 );

package/template/test/scenario.test.ts

@@ -355,13 +355,43 @@ describe('bike-shop scenario', () => {
 
   // ROUTE-LEVEL, and it has to be: everything above calls operations through a
   // `ScopeStub`, where a paged read's answer IS the `Page`. On the wire it is not
-  // — the entries are the body and the walk rides in a `Link` header — and this
-  // template's route table is hand-written, so nothing else holds the two halves
-  // together. A route that forwarded no cursor would pass every assertion above
-  // and still pin its endpoint to page one forever.
+  // — the entries are the body and the walk rides in a `Link` header. The route
+  // table is derived from the operations' `http` declarations, so this is the
+  // one place that proves the derivation reached every route: a table that
+  // silently mounted nothing, or a paged read that forwarded no cursor, would
+  // pass every assertion above and still be broken in a browser.
   it('12. the HTTP routes forward the page and hand back a Link to the next one', async () => {
     const app = new Hono();
-    mountApi(app, async () => greta);
+    const mounted = mountApi(app, async () => greta);
+
+    // Ten of this vertical's own, six of the work-order engine's, three of the
+    // invoicing engine's — every operation that declares a URL, and no more.
+    // Pinned as the complete method/path set rather than a count: this table is
+    // the public route table the hand-written one used to publish, and a count
+    // would let a wrong verb or a moved path leave nineteen entries and every
+    // walk below green. A derived table that mounted nothing would otherwise
+    // 404 its way through those walks with the same message for every route.
+    expect(mounted.map((r) => `${r.method} ${r.path}`).sort()).toEqual([
+      'GET /api/customers',
+      'GET /api/invoicing',
+      'GET /api/invoicing/:underlagId',
+      'GET /api/portal/repairs',
+      'GET /api/prices',
+      'GET /api/repairs',
+      'GET /api/repairs/:entityId/timeline',
+      'GET /api/repairs/:orderId',
+      'POST /api/customers',
+      'POST /api/customers/:customerId/bikes',
+      'POST /api/invoicing/:underlagId/export',
+      'POST /api/prices',
+      'POST /api/repairs',
+      'POST /api/repairs/:orderId/assign',
+      'POST /api/repairs/:orderId/close',
+      'POST /api/repairs/:orderId/complete',
+      'POST /api/repairs/:orderId/material',
+      'POST /api/repairs/:orderId/start',
+      'POST /api/repairs/:orderId/time',
+    ]);
 
     const nextOf = (res: Response): string | null => {
       // `<http://localhost/api/prices?limit=1&cursor=labor>; rel="next"` — the
@@ -389,9 +419,11 @@ describe('bike-shop scenario', () => {
     expect(next).toBeNull();
     expect(walked).toEqual(['chain-9s', 'labor', 'shop-supplies', 'tube-28']);
 
-    // The other hand-written paged routes forward the trio the same way. The
-    // customer list is the one with its own keyset SQL; the timeline is the
-    // kernel's own read, reached through a per-entity permission check.
+    // The other paged routes forward the trio the same way. The customer list is
+    // the one with its own keyset SQL; the timeline is the kernel's own read,
+    // reached through a per-entity permission check — and its route supplies
+    // `entityType` from the declared literal, which is why the URL carries only
+    // the id.
     const customers = await app.request('/api/customers?limit=1');
     expect(((await customers.json()) as { number: string }[]).map((c) => c.number)).toEqual([
       '2001',