create-substrat 0.9.1 → 0.9.3

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.100.0';
-const ENGINE_WORKORDER = '^0.10.8';
-const ENGINE_INVOICING = '^0.9.16';
+const SUBSTRAT = '^0.105.0';
+const ENGINE_WORKORDER = '^0.11.4';
+const ENGINE_INVOICING = '^0.9.21';
 const BOUNDARY_LINT = '^0.4.2';
-const DEV_ISSUER = '^0.1.15';
+const DEV_ISSUER = '^0.1.20';
 
 const DOCS = 'https://substrat.net';
 

package/package.json

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

package/template/.claude/launch.json

@@ -18,7 +18,7 @@
         "run",
         "server"
       ],
-      "port": 8873,
+      "port": 8891,
       "autoPort": false
     }
   ]

package/template/.substrat/playbook.md

@@ -472,7 +472,7 @@ Build confidence in this order, and **show the user the output of each**:
 pnpm install
 pnpm test                        # the scenario, including the denials
 npx @substrat-run/boundary-lint  # the layer rules
-pnpm dev                         # API on :8871 (PORT=… WEB_PORT=… to move it)
+pnpm dev                         # API on :8891 (PORT=… WEB_PORT=… to move it)
 ```
 
 Then **actually exercise it** — don't just report that the server started. A green scenario
@@ -519,7 +519,7 @@ Two more that each fail silently:
   `notFoundHandling: "single-page-application"`, a missing `/api/*` entry answers every API
   call with `index.html` — the app then reports parse errors instead of denials.
 - **The app calls its own origin** (`fetch('/api' + path)`), never a baked base URL. The Vite
-  `proxy` block is a dev-only convenience; `VITE_API_URL` or `localhost:8871` works on the
+  `proxy` block is a dev-only convenience; `VITE_API_URL` or `localhost:8891` works on the
   author's machine and reaches nothing from a phone.
 
 `substrat push` refuses an `app/` that nothing would serve, so this cannot reach a hostname

package/template/AGENTS.md

@@ -39,9 +39,11 @@ The linter and tests expect this shape. `manifest`/`migrations`/`module` are **m
 code** (the rules below bind them); `seed`/`server` are **harness** (exempt).
 
 ```
+src/entities.ts        defineEntities — WHAT EXISTS                ← module code
+src/operations.ts      defineOperations — the declared surface     ← module code
 src/manifest.ts        moduleManifest.parse({…}) + PERM consts   ← module code
 src/migrations.ts      the SqlMigration[]                         ← module code
-src/module.ts          imports both; operations + registration    ← module code
+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
@@ -91,6 +93,84 @@ tenant no matter what any of them saved. Declare a setting once, in
 `src/manifest.ts` (`SHOP_ENV`) — `src/provision.ts` re-exports it as `envSpec`,
 which is what `substrat push` uploads; package.json carries no copy.
 
+## Declare what exists, then implement it
+
+A vertical declares its **entities** and its **operations** in two typed modules, and
+the compiler checks the joins between them. This is not documentation of the code —
+it is the code's other half, and the reason a whole class of mistake stops being
+something a reviewer has to catch.
+
+`src/entities.ts` says what exists. Each entry names the table, the row shape as
+`ctx.sql` returns it (snake_case included — a prettier second naming is exactly the
+second description this removes), its natural `key`, its `parents` (the permission
+walk), and which fields are `erasable`:
+
+```ts
+export const bikeShopEntities = defineEntities({
+  customer: {
+    table: 'shop_customers',
+    fields: z.object({ id: z.string(), number: z.string(), name: z.string(), … }),
+    key: ['number'],
+    erasable: ['name', 'phone'],
+  },
+  bike: { table: 'shop_bikes', fields: …, parents: ['customer'] },
+});
+```
+
+Not every table is an entity. An entity is a thing the platform can point AT —
+attachments hang off one, grants narrow to one, events are about one. `shop_price_list`
+is keyed by article, has no id and is never the subject of an `EntityRef`, so it is
+deliberately absent and its shape lives beside the operations that return it.
+
+`src/operations.ts` says what each operation accepts, answers with, and is gated by —
+against those entities and a declared list of permission keys:
+
+```ts
+export const bikeShopOperations = defineOperations(bikeShopEntities, SHOP_PERMISSIONS)({
+  'shop/create-customer': {
+    summary: 'Register a workshop customer',
+    permission: 'customer:manage',
+    input: z.object({ number: z.string().min(1), name: z.string().min(1) }),
+    output: bikeShopEntities.customer.fields,   // from the registry, not restated
+  },
+});
+```
+
+Then `src/module.ts` holds only the **bodies**, bound to that declaration:
+
+```ts
+} satisfies OperationImpl<typeof bikeShopOperations, OperationContext>;
+```
+
+Four things are now compile errors at the exact method: a handler whose input
+disagrees with the declared `input`, one whose return disagrees with `output`, an
+operation declared and not implemented, and one implemented and not declared. The
+same object feeds `operationInputs: operationInputsOf(bikeShopOperations)`, so the
+schemas the host parses with are the ones the declaration states — they cannot drift,
+because there is only one of them.
+
+**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
+endpoint returning the whole table is a bug with a delay on it: it passes review, it
+passes tests, and then one tenant's table gets large. Declare the **entry** as
+`output` and let `paged` wrap it; the handler returns `Page<Entry>`, which `pageOf`
+builds. Either the kernel composes the walk (`paged: { over: { entity: 'customer',
+sortable: ['number'] } }`) or, where it cannot — a kernel table, a per-row permission
+walk, a table the registry does not carry — the handler composes its own and names the
+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
+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.
+
 ## The rules (non-negotiable)
 
 **Module code** = everything reachable from a `ModuleRegistration` (operations,

package/template/src/entities.ts

@@ -0,0 +1,83 @@
+import { defineEntities, emitModel, z } from '@substrat-run/contracts';
+
+// ============================================================================
+// The bike shop's ENTITY REGISTRY — what this vertical declares exists.
+//
+// This is the first half of the declared model: the entities, and then
+// `src/operations.ts` declares the operations against them. The compiler checks
+// the joins between the two, so an operation narrowing to an entity that does
+// not exist, or emitting about a field the output does not carry, is a build
+// error rather than something a reviewer has to notice.
+//
+// Field names mirror the SQL columns verbatim, snake_case included. They are the
+// row shape as `ctx.sql` returns it, not a prettier domain model — a second
+// naming would be exactly the second description this exists to remove.
+// ============================================================================
+
+/**
+ * NOT every table is an entity. `shop_price_list` is a table — keyed by article,
+ * no id, never the subject of an `EntityRef`, never a node in a permission walk
+ * — so it is deliberately absent here, and its row shape lives beside the
+ * operations that return it instead.
+ *
+ * An entity is a thing the platform can point AT: attachments hang off one,
+ * grants narrow to one, events are about one. The price list is data those
+ * things operate on.
+ */
+export const bikeShopEntities = defineEntities({
+  customer: {
+    table: 'shop_customers',
+    fields: z.object({
+      id: z.string(),
+      number: z.string(),
+      name: z.string(),
+      phone: z.string().nullable(),
+      created_at: z.string(),
+    }),
+    /** `number` is UNIQUE in 0001-init — the natural key a human quotes. */
+    key: ['number'],
+    /**
+     * A workshop customer is usually a private person, so their name and phone
+     * are erasure-reachable. Declaring it is what keeps an event payload from
+     * ever carrying them: an immutable event is the one place in a scope an
+     * erasure cannot reach, and the compiler enforces the omission.
+     */
+    erasable: ['name', 'phone'],
+  },
+  bike: {
+    table: 'shop_bikes',
+    fields: z.object({
+      id: z.string(),
+      customer_id: z.string(),
+      label: z.string(),
+      frame_no: z.string().nullable(),
+      created_at: z.string(),
+    }),
+    /**
+     * Permission flows bike → customer, which is the first hop of the portal
+     * walk (workorder → bike → customer). The manifest declares the same edge
+     * for `ctx.link`; this is the model's half of it.
+     */
+    parents: ['customer'],
+    /**
+     * A frame number identifies a bike, and a bike identifies its owner — it is
+     * the serial a police report quotes. Pseudonymous rather than direct, which
+     * is exactly why it is easy to leave out: an erasure that kept it would
+     * leave a pointer to the person it just erased. Declaring it here is what
+     * keeps a future `bike.*` event payload from carrying it, since an immutable
+     * event is the one place in a scope an erasure cannot reach.
+     */
+    erasable: ['frame_no'],
+  },
+});
+
+/**
+ * The artifact of record, emitted from the declaration above.
+ *
+ * A scaffolded project is not in this repo's `demos/`, so nothing here re-emits
+ * a `model.json` for it — `pnpm lint:model` walks `demos/` and `engines/`. What
+ * this export is for in a scaffold is the same thing it is for in the reference
+ * verticals: one object downstream reads, so the authoring notation stays
+ * swappable.
+ */
+export const bikeShopModel = emitModel(bikeShopEntities);

package/template/src/module.ts

@@ -1,20 +1,24 @@
 import {
   addDecimal,
   compareDecimal,
+  listLimitOf,
   moneyOf,
   mulMoney,
   operationInputsOf,
+  pageOf,
   pageVisible,
   z,
-  type Money,
-  type Page,
+  type HandlerInput,
+  type HandlerOutput,
+  type OperationImpl,
 } from '@substrat-run/contracts';
 import {
   assertAllowed,
+  readTimeline,
   ulid,
   type ModuleRegistration,
+  type OperationContext,
   type OperationHandler,
-  type PageParams,
 } from '@substrat-run/kernel';
 import {
   closeWorkOrder,
@@ -24,13 +28,14 @@ import {
   listOrders,
   PERM as WO,
   type BillableLine,
-  type WorkOrder,
 } from '@substrat-run/engine-workorder';
+import { bikeShopEntities } from './entities.js';
+import { bikeShopOperations, priceRow } from './operations.js';
 import { bikeShopManifest, SHOP_PERM } from './manifest.js';
 import { bikeShopMigrations } from './migrations.js';
 
 // ============================================================================
-// The bike-shop operations. Each is either:
+// The bike-shop HANDLERS. Each is either:
 //   - a thin custodian of the vertical's own tables (customers, bikes, prices),
 //     OR
 //   - a COMPOSITION that wraps an engine's in-scope function inside the same
@@ -38,48 +43,33 @@ import { bikeShopMigrations } from './migrations.js';
 //
 // Every operation's FIRST line is the permission check. Data access is
 // `ctx.sql` only. No `fetch`, no `node:*`, no other engine's tables.
+//
+// WHAT EACH OPERATION IS is declared in `src/operations.ts`, against the
+// entities in `src/entities.ts` — this file holds only the bodies. The binding
+// at the bottom is `satisfies OperationImpl<…>`, so a handler that disagrees
+// with its declaration is a compile error at the exact method.
 // ============================================================================
 
-export interface CustomerRow {
-  id: string;
-  number: string;
-  name: string;
-  phone: string | null;
-  created_at: string;
-}
-
-export interface BikeRow {
-  id: string;
-  customer_id: string;
-  label: string;
-  frame_no: string | null;
-  created_at: string;
-}
-
-export interface PriceRow {
-  article: string;
-  description: string;
-  unit: string;
-  price_amount: string;
-  currency: string;
-  min_qty: string | null;
-  internal: number;
-}
+/** The row shapes, read off the registry so there is one description of each. */
+export type CustomerRow = z.infer<typeof bikeShopEntities.customer.fields>;
+export type BikeRow = z.infer<typeof bikeShopEntities.bike.fields>;
+export type PriceRow = z.infer<typeof priceRow>;
 
-// Every operation that takes an input declares it as a Zod object here, and the
-// handler's input type is `z.infer` of that object — one description of the
-// shape, so the schema and the type cannot drift apart. `bikeShopOperations` at
-// the bottom of this file hands the whole set to the host.
-const createCustomerInput = z.object({
-  number: z.string().min(1),
-  name: z.string().min(1),
-  phone: z.string().min(1).optional(),
-});
+/**
+ * One handler's signature, derived from its declaration.
+ *
+ * `HandlerInput` resolves what the host will hand in — the declared `input`,
+ * plus the page trio when the operation is `paged` — and `HandlerOutput`
+ * resolves what it must answer with, wrapping the declared entry in a `Page`
+ * for a paged read. Neither is restated here, so a change to `operations.ts`
+ * lands on the handler as a type error rather than as a silent disagreement.
+ */
+type Op<K extends keyof typeof bikeShopOperations> = OperationHandler<
+  HandlerInput<(typeof bikeShopOperations)[K]>,
+  HandlerOutput<(typeof bikeShopOperations)[K]>
+>;
 
-const createCustomerOp: OperationHandler<z.infer<typeof createCustomerInput>, CustomerRow> = async (
-  ctx,
-  input,
-) => {
+const createCustomerOp: Op<'shop/create-customer'> = async (ctx, input) => {
   assertAllowed(await ctx.check(SHOP_PERM.customerManage));
   const id = ulid();
   ctx.sql.exec(
@@ -89,29 +79,34 @@ const createCustomerOp: OperationHandler<z.infer<typeof createCustomerInput>, Cu
   return ctx.sql.query<CustomerRow>('SELECT * FROM shop_customers WHERE id = ?', [id])[0]!;
 };
 
-const listCustomersOp: OperationHandler<undefined, (CustomerRow & { bikes: BikeRow[] })[]> = async (
-  ctx,
-) => {
+/**
+ * The customer list, hydrated with each customer's bikes.
+ *
+ * Handler-composed keyset paging over `number`, the customer's natural key —
+ * keyset and never offset, because on live data an offset shifts between
+ * requests and pages then drop and duplicate rows. The page also BOUNDS the
+ * hydration: one bikes query per customer ON THE PAGE, where the unpaged read
+ * this replaced ran one per customer in the whole scope.
+ */
+const listCustomersOp: Op<'shop/list-customers'> = async (ctx, input) => {
   assertAllowed(await ctx.check(SHOP_PERM.customerManage));
-  const customers = ctx.sql.query<CustomerRow>('SELECT * FROM shop_customers ORDER BY number');
-  return customers.map((c) => ({
+  const limit = listLimitOf(input?.limit);
+  const customers = input?.cursor
+    ? ctx.sql.query<CustomerRow>(
+        'SELECT * FROM shop_customers WHERE number > ? ORDER BY number LIMIT ?',
+        [input.cursor, limit],
+      )
+    : ctx.sql.query<CustomerRow>('SELECT * FROM shop_customers ORDER BY number LIMIT ?', [limit]);
+  const hydrated = customers.map((c) => ({
     ...c,
     bikes: ctx.sql.query<BikeRow>('SELECT * FROM shop_bikes WHERE customer_id = ? ORDER BY label', [
       c.id,
     ]),
   }));
+  return pageOf(hydrated, limit, (row) => row.number);
 };
 
-const registerBikeInput = z.object({
-  customerId: z.string().min(1),
-  label: z.string().min(1),
-  frameNo: z.string().min(1).optional(),
-});
-
-const registerBikeOp: OperationHandler<z.infer<typeof registerBikeInput>, BikeRow> = async (
-  ctx,
-  input,
-) => {
+const registerBikeOp: Op<'shop/register-bike'> = async (ctx, input) => {
   assertAllowed(await ctx.check(SHOP_PERM.bikeManage));
   const customer = ctx.sql.query<CustomerRow>('SELECT * FROM shop_customers WHERE id = ?', [
     input.customerId,
@@ -128,20 +123,7 @@ const registerBikeOp: OperationHandler<z.infer<typeof registerBikeInput>, BikeRo
   return ctx.sql.query<BikeRow>('SELECT * FROM shop_bikes WHERE id = ?', [id])[0]!;
 };
 
-const upsertPriceInput = z.object({
-  article: z.string().min(1),
-  description: z.string().min(1),
-  unit: z.string().min(1),
-  priceAmount: z.string().min(1),
-  currency: z.string().min(1).optional(),
-  minQty: z.string().min(1).optional(),
-  internal: z.boolean().optional(),
-});
-
-const upsertPriceOp: OperationHandler<z.infer<typeof upsertPriceInput>, PriceRow> = async (
-  ctx,
-  input,
-) => {
+const upsertPriceOp: Op<'shop/upsert-price'> = async (ctx, input) => {
   assertAllowed(await ctx.check(SHOP_PERM.customerManage));
   ctx.sql.exec(
     `INSERT OR REPLACE INTO shop_price_list
@@ -162,9 +144,21 @@ const upsertPriceOp: OperationHandler<z.infer<typeof upsertPriceInput>, PriceRow
   ])[0]!;
 };
 
-const priceListOp: OperationHandler<undefined, PriceRow[]> = async (ctx) => {
+/**
+ * The price list, paged. Handler-composed (see the declaration): a value-keyed
+ * table the entity registry deliberately does not carry, so there is no indexed
+ * entity for the kernel to walk. Keyset over `article`, its natural key.
+ */
+const priceListOp: Op<'shop/price-list'> = async (ctx, input) => {
   assertAllowed(await ctx.check(SHOP_PERM.customerManage));
-  return ctx.sql.query<PriceRow>('SELECT * FROM shop_price_list ORDER BY article');
+  const limit = listLimitOf(input?.limit);
+  const rows = input?.cursor
+    ? ctx.sql.query<PriceRow>(
+        'SELECT * FROM shop_price_list WHERE article > ? ORDER BY article LIMIT ?',
+        [input.cursor, limit],
+      )
+    : ctx.sql.query<PriceRow>('SELECT * FROM shop_price_list ORDER BY article LIMIT ?', [limit]);
+  return pageOf(rows, limit, (row) => row.article);
 };
 
 /**
@@ -172,17 +166,7 @@ const priceListOp: OperationHandler<undefined, PriceRow[]> = async (ctx) => {
  * The vertical resolves its own vocabulary (a bike, its owner) into the engine's
  * `facility`/`customer` refs; the engine owns the number, the state, the event.
  */
-const createRepairInput = z.object({
-  bikeId: z.string().min(1),
-  kind: z.string().min(1),
-  title: z.string().min(1),
-  description: z.string().optional(),
-});
-
-const createRepairOp: OperationHandler<z.infer<typeof createRepairInput>, WorkOrder> = async (
-  ctx,
-  input,
-) => {
+const createRepairOp: Op<'shop/create-repair'> = async (ctx, input) => {
   assertAllowed(await ctx.check(WO.create));
   const bike = ctx.sql.query<BikeRow>('SELECT * FROM shop_bikes WHERE id = ?', [input.bikeId])[0];
   if (!bike) throw new Error(`bike not found: ${input.bikeId}`);
@@ -204,12 +188,7 @@ const createRepairOp: OperationHandler<z.infer<typeof createRepairInput>, WorkOr
  * The engine's `workorder.completed` event carries these lines, and the
  * invoicing engine consumes it — no import between the two.
  */
-const repairIdInput = z.object({ orderId: z.string().min(1) });
-
-const completeRepairOp: OperationHandler<
-  z.infer<typeof repairIdInput>,
-  { order: WorkOrder; billable: BillableLine[]; total: Money }
-> = async (ctx, input) => {
+const completeRepairOp: Op<'shop/complete-repair'> = async (ctx, input) => {
   assertAllowed(await ctx.check(WO.complete));
   const reported = getReportedLines(ctx, input.orderId);
   const prices = new Map<string, PriceRow>(
@@ -264,10 +243,7 @@ const completeRepairOp: OperationHandler<
  * engine's in-scope `closeWorkOrder`; the vertical owns the vocabulary
  * ("pickup"), the engine owns the transition.
  */
-const closeRepairOp: OperationHandler<z.infer<typeof repairIdInput>, WorkOrder> = async (
-  ctx,
-  input,
-) => {
+const closeRepairOp: Op<'shop/close-repair'> = async (ctx, input) => {
   assertAllowed(await ctx.check(WO.close));
   return closeWorkOrder(ctx, { orderId: input.orderId });
 };
@@ -286,10 +262,7 @@ const closeRepairOp: OperationHandler<z.infer<typeof repairIdInput>, WorkOrder>
  * on the next request, and a page the walk rejects entirely would never advance at
  * all. So a SHORT page does not end this walk; only a null `nextCursor` does.
  */
-const portalRepairsOp: OperationHandler<PageParams | undefined, Page<WorkOrder>> = async (
-  ctx,
-  input,
-) =>
+const portalRepairsOp: Op<'shop/portal-repairs'> = async (ctx, input) =>
   pageVisible(
     (p) => listOrders(ctx, { ...input, ...p }),
     input,
@@ -297,70 +270,61 @@ const portalRepairsOp: OperationHandler<PageParams | undefined, Page<WorkOrder>>
       (await ctx.check(WO.read, { entityType: 'workorder', entityId: order.id })).allowed,
   );
 
-const timelineInput = z.object({
-  entityType: z.string().min(1),
-  entityId: z.string().min(1),
-});
-
 /**
  * An entity's event timeline, read straight off the spine (a read of `_substrat_*`
  * for a projection is allowed; writing it is not). Gated by a per-entity
  * `workorder:read` check, so it obeys the same walk as the portal.
  *
- * No `.parse` in here: the host already parsed `entity` against
- * `timelineInput` before this line ran, on whichever path the call came in by.
+ * `readTimeline` rather than a `SELECT` of our own: it takes an `EntityRef`,
+ * pages like a list read, and DECODES the envelope — `actor` comes back as the
+ * union the spine recorded, where `SELECT actor` returns a string that looks
+ * usable and is not. It checks no permission; we do, above, as always.
+ *
+ * No `.parse` in here: the host already parsed `entity` against `timelineInput`
+ * before this line ran, on whichever path the call came in by.
  */
-const timelineOp: OperationHandler<
-  z.infer<typeof timelineInput>,
-  { type: string; occurred_at: string; actor: string }[]
-> = async (ctx, entity) => {
+const timelineOp: Op<'shop/timeline'> = async (ctx, input) => {
+  // The operation is `paged`, so the host hands the page trio in on the SAME
+  // object as the entity's two fields. An `EntityRef` is exactly those two, so
+  // name them rather than passing the whole input — `ctx.check` and
+  // `readTimeline` should be given a ref, not a ref with a cursor stuck to it.
+  const entity = { entityType: input.entityType, entityId: input.entityId };
   assertAllowed(await ctx.check(WO.read, entity));
-  // Append order is authoritative — rowid, not ULID (ids minted in the same
-  // millisecond are not mutually ordered).
-  return ctx.sql.query(
-    `SELECT type, occurred_at, actor FROM _substrat_outbox
-     WHERE entity_type = ? AND entity_id = ? ORDER BY rowid`,
-    [entity.entityType, entity.entityId],
-  );
+  return readTimeline(ctx, entity, input);
 };
 
 /**
- * What each operation accepts. A complete census of the ten below: an entry with
- * no `input` takes nothing, and `paged: true` is how the portal read says the
- * platform supplies the page trio (`limit`/`cursor`/`order`/`sort`) — declaring
- * those four by hand is how the two descriptions of one page come to disagree.
+ * The handlers, bound to `bikeShopOperations`. `satisfies` is the drift
+ * detector: change a declared input or return and tsc names the method whose
+ * handler no longer agrees. An operation declared but not implemented, or
+ * implemented but not declared, is an error here too.
  */
-const bikeShopOperations = {
-  'shop/create-customer': { input: createCustomerInput },
-  'shop/list-customers': {},
-  'shop/register-bike': { input: registerBikeInput },
-  'shop/upsert-price': { input: upsertPriceInput },
-  'shop/price-list': {},
-  'shop/create-repair': { input: createRepairInput },
-  'shop/complete-repair': { input: repairIdInput },
-  'shop/close-repair': { input: repairIdInput },
-  'shop/portal-repairs': { paged: true },
-  'shop/timeline': { input: timelineInput },
-};
+const declaredOperations = {
+  'shop/create-customer': createCustomerOp,
+  'shop/list-customers': listCustomersOp,
+  'shop/register-bike': registerBikeOp,
+  'shop/upsert-price': upsertPriceOp,
+  'shop/price-list': priceListOp,
+  'shop/create-repair': createRepairOp,
+  'shop/complete-repair': completeRepairOp,
+  'shop/close-repair': closeRepairOp,
+  'shop/portal-repairs': portalRepairsOp,
+  'shop/timeline': timelineOp,
+} satisfies OperationImpl<typeof bikeShopOperations, OperationContext>;
 
 export const bikeShopModule: ModuleRegistration = {
   manifest: bikeShopManifest,
   migrations: bikeShopMigrations,
-  // The host parses every invocation against these before the guards, the
-  // permission check and the handler — so "parse, don't trust" holds on every
-  // path in (HTTP, test, seed, schedule) rather than in the handlers that
-  // remembered to do it themselves.
+  // The host parses every invocation against the DECLARED input schemas before
+  // the guards, the permission check and the handler — so "parse, don't trust"
+  // holds on every path in (HTTP, test, seed, schedule) rather than in the
+  // handlers that remembered to do it themselves.
   operationInputs: operationInputsOf(bikeShopOperations),
   operations: {
-    'shop/create-customer': createCustomerOp as never,
-    'shop/list-customers': listCustomersOp as never,
-    'shop/register-bike': registerBikeOp as never,
-    'shop/upsert-price': upsertPriceOp as never,
-    'shop/price-list': priceListOp as never,
-    'shop/create-repair': createRepairOp as never,
-    'shop/complete-repair': completeRepairOp as never,
-    'shop/close-repair': closeRepairOp as never,
-    'shop/portal-repairs': portalRepairsOp as never,
-    'shop/timeline': timelineOp as never,
+    // All ten bound to the declaration: input and return are checked against
+    // `bikeShopOperations` at the exact method. The `as never` casts this map
+    // used to carry were never necessary — `OperationHandler<never, unknown>`
+    // accepts any handler by contravariance — they simply threw the types away.
+    ...(declaredOperations as Record<string, OperationHandler<never, unknown>>),
   },
 };

package/template/src/operations.ts

@@ -0,0 +1,201 @@
+import { defineOperations, money, timelineEntry, z } from '@substrat-run/contracts';
+import { billableLine, workOrder, workorderEntities } 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.
+//
+// This is one declaration, not documentation of another one. `src/module.ts`
+// binds its handlers to this object with `satisfies OperationImpl<…>`, so four
+// things become compile errors at the exact method: a handler whose input
+// 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.
+// ============================================================================
+
+/**
+ * The permission keys an operation here may name.
+ *
+ * Two of them are this vertical's own (they mirror `SHOP_PERM` in
+ * `src/manifest.ts`); the other four are the WORKORDER ENGINE's. An engine key
+ * is listed because a vertical operation may be gated by one — this is the
+ * vocabulary a `permission` may draw on, not a second declaration of who owns
+ * the key. The engine still declares them.
+ */
+export const SHOP_PERMISSIONS = [
+  'customer:manage',
+  'bike:manage',
+  'workorder:create',
+  'workorder:read',
+  'workorder:complete',
+  'workorder:close',
+] as const;
+
+/**
+ * The engine entity registries this vertical composes — `defineOperations`'s
+ * third argument, and what lets `shop/timeline` narrow its check to a
+ * `workorder` rather than settling for a node-level check on a key of its own.
+ */
+const SHOP_ENGINE_ENTITIES = [workorderEntities] as const;
+
+/**
+ * A price-list row. A TABLE, not an entity (see `src/entities.ts`), so its shape
+ * is declared here rather than in the registry.
+ */
+export const priceRow = z.object({
+  article: z.string(),
+  description: z.string(),
+  unit: z.string(),
+  price_amount: z.string(),
+  currency: z.string(),
+  min_qty: z.string().nullable(),
+  internal: z.number(),
+});
+
+/**
+ * Shop policy: a timeline is read for a repair. Declared once here and parsed by
+ * the host — the handler never re-parses it, which is the point of the model
+ * being TypeScript rather than prose.
+ *
+ * `entityType` is a literal rather than an open string. The handler is genuinely
+ * entity-agnostic — `ctx.check` is handed whatever ref the caller names — but
+ * "any entity at all" was never what the vertical meant, and an open string
+ * would cost the permission declaration below its accuracy.
+ */
+export const timelineInput = z.object({
+  entityType: z.literal('workorder'),
+  entityId: z.string().min(1),
+});
+
+export const bikeShopOperations = defineOperations(
+  bikeShopEntities,
+  SHOP_PERMISSIONS,
+  SHOP_ENGINE_ENTITIES,
+)({
+  'shop/create-customer': {
+    summary: 'Register a workshop customer',
+    permission: 'customer:manage',
+    input: z.object({
+      number: z.string().min(1),
+      name: z.string().min(1),
+      phone: z.string().min(1).optional(),
+    }),
+    // The row shape comes from the registry — not restated here.
+    output: bikeShopEntities.customer.fields,
+  },
+  'shop/list-customers': {
+    summary: 'List customers with the bikes they have registered',
+    permission: 'customer:manage',
+    // 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.
+    output: bikeShopEntities.customer.fields.extend({
+      bikes: z.array(bikeShopEntities.bike.fields),
+    }),
+    // Handler-composed, keyset over the customer's natural key. A list read that
+    // answered with the whole table would be a bug with a delay on it: it passes
+    // review, it passes tests, and then one workshop's table gets large.
+    paged: { sortKey: 'number' },
+  },
+  'shop/register-bike': {
+    summary: 'Register a bike against a customer',
+    permission: 'bike:manage',
+    input: z.object({
+      customerId: z.string().min(1),
+      label: z.string().min(1),
+      frameNo: z.string().min(1).optional(),
+    }),
+    output: bikeShopEntities.bike.fields,
+  },
+  'shop/upsert-price': {
+    summary: 'Create or update a price-list article',
+    permission: 'customer:manage',
+    input: z.object({
+      article: z.string().min(1),
+      description: z.string().min(1),
+      unit: z.string().min(1),
+      priceAmount: z.string().min(1),
+      currency: z.string().min(1).optional(),
+      minQty: z.string().min(1).optional(),
+      internal: z.boolean().optional(),
+    }),
+    output: priceRow,
+  },
+  'shop/price-list': {
+    summary: 'The workshop price list',
+    permission: 'customer:manage',
+    output: priceRow,
+    // 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.
+    paged: { sortKey: 'article' },
+  },
+  'shop/create-repair': {
+    summary: 'Open a repair against a bike',
+    // An ENGINE key: the vertical owns the word "repair", the engine owns the
+    // work order it is.
+    permission: 'workorder:create',
+    input: z.object({
+      bikeId: z.string().min(1),
+      kind: z.string().min(1),
+      title: z.string().min(1),
+      description: z.string().optional(),
+    }),
+    // The engine's published type, not a transcription of it. Note `workOrder`
+    // and NOT the row: the engine stores `facility_type`/`facility_id` as two
+    // snake_case columns and publishes one `EntityRef` in camelCase.
+    output: workOrder,
+  },
+  '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 }),
+  },
+  'shop/close-repair': {
+    summary: 'Hand the bike back — completed to closed',
+    permission: 'workorder:close',
+    input: z.object({ orderId: z.string().min(1) }),
+    output: workOrder,
+  },
+  'shop/portal-repairs': {
+    summary: 'The repairs visible to the calling portal customer',
+    /**
+     * No node-level permission, stated rather than left as an absence: a portal
+     * customer holds an entity-narrowed `workorder:read` on their own customer
+     * record and nothing at the node, so a blanket check would deny every one of
+     * them. Visibility is decided per row by the proof walk instead.
+     */
+    narrows: {
+      reason: 'a portal customer sees their own repairs, not a denial',
+      // Walks on `workorder:read` alone — an engine key, declared by the engine.
+      checks: [],
+    },
+    output: workOrder,
+    // Handler-composed, and it has to be: visibility here is decided by a
+    // per-row walk, not by a column, so there is no `WHERE` the kernel could
+    // compose. It pages by OVER-fetching, so a SHORT page does not end the walk
+    // — only an absent cursor does.
+    paged: { sortKey: 'id' },
+  },
+  'shop/timeline': {
+    summary: 'The event timeline for one repair',
+    /**
+     * `workorder:read` ON THE ENTITY named, not at the node. A `mechanic` holds
+     * `workorder:read` and a portal customer holds it narrowed to their own
+     * customer record; both reach a repair's timeline through the walk
+     * (workorder → bike → customer), and neither would pass a node check.
+     */
+    permission: { key: 'workorder:read', entity: 'workorder', idFrom: 'entityId' },
+    input: timelineInput,
+    // The KERNEL's shape, not a fourth copy of it: `readTimeline` decodes the
+    // envelope, and `actor` is a union the spine recorded rather than the raw
+    // string a hand-rolled `SELECT actor` returns.
+    output: timelineEntry,
+    // The cursor is `id` — the event's ULID, which IS this entity's version at
+    // that point.
+    paged: { sortKey: 'id' },
+  },
+});

package/template/src/routes.ts

@@ -1,5 +1,13 @@
 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';
 
 /**
@@ -22,6 +30,58 @@ import type { ScopeStub } from '@substrat-run/kernel';
  */
 export type ResolveStub = (c: Context) => Promise<ScopeStub>;
 
+/**
+ * The page trio, off the query string — what a route hands a PAGED operation.
+ *
+ * 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.
+ *
+ * `order` and `sort` travel only when asked for, so the DECLARATION's own
+ * defaults stay the answer when a caller says nothing.
+ */
+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] }),
+  };
+}
+
+/**
+ * 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;
@@ -57,7 +117,9 @@ export function mountApi(app: Hono<any, any, any>, resolveStub: ResolveStub): vo
   });
 
   // -- customers, bikes, price list (the vertical's own tables) ---------------
-  app.get('/api/customers', async (c) => c.json(await (await S(c)).invoke('shop/list-customers')));
+  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())),
   );
@@ -69,7 +131,9 @@ export function mountApi(app: Hono<any, any, any>, resolveStub: ResolveStub): vo
       }),
     ),
   );
-  app.get('/api/prices', async (c) => c.json(await (await S(c)).invoke('shop/price-list')));
+  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())),
   );
@@ -79,7 +143,13 @@ export function mountApi(app: Hono<any, any, any>, resolveStub: ResolveStub): vo
   // 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) =>
-    c.json(await (await S(c)).invoke('workorder/list', { status: c.req.query('status') })),
+    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())),
@@ -88,10 +158,12 @@ export function mountApi(app: Hono<any, any, any>, resolveStub: ResolveStub): vo
     c.json(await (await S(c)).invoke('workorder/get', { orderId: c.req.param('id') })),
   );
   app.get('/api/repairs/:id/timeline', async (c) =>
-    c.json(
+    pageJson(
+      c,
       await (await S(c)).invoke('shop/timeline', {
         entityType: 'workorder',
         entityId: c.req.param('id'),
+        ...pageInput(c),
       }),
     ),
   );
@@ -130,10 +202,14 @@ export function mountApi(app: Hono<any, any, any>, resolveStub: ResolveStub): vo
   );
 
   // -- the customer portal (the per-entity proof walk) ------------------------
-  app.get('/api/portal/repairs', async (c) => c.json(await (await S(c)).invoke('shop/portal-repairs')));
+  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) => c.json(await (await S(c)).invoke('invoicing/list')));
+  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') })),
   );

package/template/src/server.ts

@@ -57,6 +57,11 @@ const staffActor = platformActorId.parse(ulid());
 // Both ports are bound in THIS file so they move together: `substrat.devServers` names
 // it for the API and for the issuer alike, and `ISSUER_PORT=… PORT=… pnpm dev` shifts the
 // pair without either end losing track of the other.
+//
+// The issuer default is 8879 because that is `@substrat-run/dev-issuer`'s OWN default —
+// the `issuer` script passes no `--port`, so this number and the one the issuer actually
+// binds have to be the same or the login round-trip points at nothing. Change one and you
+// must change the other; `ISSUER_PORT=…` moves both at once, which is the supported way.
 const ISSUER_PORT = Number(process.env.ISSUER_PORT ?? 8879);
 const login = devLogin({
   directory: host.admin,
@@ -87,7 +92,11 @@ async function stub(c: Context): Promise<ScopeStub> {
 // Everything else — including `/api/invoke` and the shared error envelope.
 mountApi(app, stub);
 
-const PORT = Number(process.env.PORT ?? 8873);
+// 8891, not 8873. The `887x`/`527x` block is reserved for this monorepo's own demos
+// (CLAUDE.md, "Commands"), and 8873 is the shop demo's API — so a scaffolded project used
+// to refuse to boot beside the demo it was read from. A scaffold has no claim on that
+// block; `PORT=…` moves this one.
+const PORT = Number(process.env.PORT ?? 8891);
 serve({ fetch: app.fetch, port: PORT });
 console.log(`Bike-shop API on http://localhost:${PORT} — data in ${dataDir}`);
 console.log(`Sign in at http://localhost:${PORT}/api/auth/login — issuer: ${login.issuer}`);

package/template/test/entities.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from 'vitest';
+import { bikeShopEntities, bikeShopModel } from '../src/entities.js';
+import { bikeShopMigrations } from '../src/migrations.js';
+import { bikeShopManifest } from '../src/manifest.js';
+
+// ============================================================================
+// The registry and the migration journal are TWO DESCRIPTIONS OF ONE SCHEMA.
+//
+// `src/entities.ts` declares the row shape as `ctx.sql` returns it; `0001-init`
+// creates the table it returns rows from. Nothing derives one from the other
+// yet, so nothing stops them drifting: rename a column in the journal, add its
+// migration, and the registry goes stale while `tsc` stays green and every
+// scenario assertion above still passes — the declaration would then be wrong
+// about the very thing it exists to state.
+//
+// This is the check that makes that a red build. It is also the one worth
+// copying when you replace the bike shop with your own domain: every entity you
+// declare should be held to the table it names.
+// ============================================================================
+
+const journalSql = bikeShopMigrations.map((m) => m.sql).join('\n');
+
+/** The columns each `CREATE TABLE` actually leaves behind, plus any `ADD COLUMN`. */
+function columnsFromJournal(): Map<string, Set<string>> {
+  const tables = new Map<string, Set<string>>();
+  for (const [, table, body] of journalSql.matchAll(
+    /CREATE TABLE (?:IF NOT EXISTS )?([a-z_][a-z0-9_]*)\s*\(([\s\S]*?)\n\s*\);/gi,
+  )) {
+    if (!table || !body) continue;
+    const cols = new Set<string>();
+    for (const raw of body.split('\n')) {
+      const line = raw.trim();
+      // Table constraints are not columns, and neither is a comment.
+      if (!line || line.startsWith('--') || /^(PRIMARY|FOREIGN|UNIQUE|CHECK|CONSTRAINT)\b/i.test(line))
+        continue;
+      const name = /^([a-z_][a-z0-9_]*)\b/i.exec(line)?.[1];
+      if (name) cols.add(name);
+    }
+    tables.set(table, cols);
+  }
+  for (const [, table, col] of journalSql.matchAll(
+    /ALTER TABLE ([a-z_][a-z0-9_]*)\s+ADD COLUMN\s+([a-z_][a-z0-9_]*)/gi,
+  )) {
+    if (table && col) tables.get(table)?.add(col);
+  }
+  return tables;
+}
+
+describe('the registry agrees with the migration journal', () => {
+  const journal = columnsFromJournal();
+
+  it('parsed the journal at all', () => {
+    // A comparison that silently parsed nothing would pass everything under it,
+    // which is the one way this file could be worse than not existing.
+    expect(journal.size).toBe(3);
+    expect(journal.get('shop_customers')?.size).toBeGreaterThan(1);
+  });
+
+  for (const [name, entity] of Object.entries(bikeShopEntities)) {
+    it(`${name} → ${entity.table}: the declared fields ARE the table's columns`, () => {
+      const actual = journal.get(entity.table);
+      expect(actual, `no CREATE TABLE for '${entity.table}'`).toBeDefined();
+      expect(Object.keys(entity.fields.shape).sort()).toEqual([...(actual ?? [])].sort());
+    });
+  }
+
+  it('leaves the price list out — a table, not an entity', () => {
+    // Stated as an assertion rather than an absence, so deleting the entity that
+    // should not exist is a decision somebody made and not one that rotted away.
+    expect(journal.has('shop_price_list')).toBe(true);
+    expect(Object.values(bikeShopEntities).map((e) => e.table)).not.toContain('shop_price_list');
+  });
+});
+
+describe('the declared model and the manifest describe one walk', () => {
+  it('emits every declared entity, deterministically', () => {
+    expect(Object.keys(bikeShopModel.entities)).toEqual(['bike', 'customer']);
+    expect(bikeShopModel.entities.bike?.parents).toEqual(['customer']);
+  });
+
+  it("keeps the model's local edge and the manifest's in step", () => {
+    // `entityRelations` is what `ctx.link` and the portal walk resolve against;
+    // `parents` is the model's half of the same edge. Two spellings of one fact,
+    // until the manifest is derived from the registry.
+    expect(bikeShopManifest.entityRelations).toContainEqual({
+      entityType: 'bike',
+      parentType: 'customer',
+    });
+    // The hop the shop's own registry cannot produce: `workorder` is the ENGINE's
+    // entity, and the portal walk (workorder → bike → customer) needs it.
+    expect(bikeShopManifest.entityRelations).toContainEqual({
+      entityType: 'workorder',
+      parentType: 'bike',
+    });
+  });
+
+  it('declares the identifying bike field erasable', () => {
+    // A frame number points at its owner. An erasure that kept it would leave
+    // that pointer behind, and an event payload carrying it could not be reached
+    // at all — so the declaration is what keeps it out of one.
+    expect(bikeShopEntities.bike.erasable).toContain('frame_no');
+    expect(bikeShopEntities.customer.erasable).toEqual(['name', 'phone']);
+  });
+});

package/template/test/scenario.test.ts

@@ -2,12 +2,20 @@ import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import Database from 'better-sqlite3';
+import { Hono } from 'hono';
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { addMoney, moneyOf, mulMoney, type Page } from '@substrat-run/contracts';
+import {
+  addMoney,
+  moneyOf,
+  mulMoney,
+  type Page,
+  type TimelineEntry,
+} from '@substrat-run/contracts';
 import type { ScopeStub } from '@substrat-run/kernel';
 import type { SqliteScopeHost } from '@substrat-run/adapter-sqlite';
 import type { WorkOrder, BillableLine } from '@substrat-run/engine-workorder';
 import { buildBikeShopHost, seedBikeShop, type BikeShopWorld } from '../src/seed.js';
+import { mountApi } from '../src/routes.js';
 
 // ============================================================================
 // The bike-shop scenario, replayed headlessly against a temp dir: a repair's
@@ -63,11 +71,14 @@ describe('bike-shop scenario', () => {
     expect(repair.facility).toEqual({ entityType: 'bike', entityId: w.crescentId });
     expect(repair.customer.entityId).toBe(w.lisbethId);
 
-    const timeline = await greta.invoke<{ type: string }[]>('shop/timeline', {
+    // A page, not a bare array: every list read on this surface is declared
+    // `paged`, so the envelope is `{ entries, nextCursor }` and a caller with
+    // more rows than one page walks the cursor rather than assuming it saw all.
+    const timeline = await greta.invoke<Page<TimelineEntry>>('shop/timeline', {
       entityType: 'workorder',
       entityId: repairId,
     });
-    expect(timeline.map((e) => e.type)).toContain('workorder.created');
+    expect(timeline.entries.map((e) => e.type)).toContain('workorder.created');
   });
 
   it('3. assign → start → report time and parts', async () => {
@@ -280,4 +291,116 @@ describe('bike-shop scenario', () => {
       rutger.invoke('shop/create-customer', { number: '9001', name: 'x' }),
     ).rejects.toThrow(/permission denied/);
   });
+
+  // Every list read on this surface is DECLARED `paged` in src/operations.ts, and
+  // `defineOperations` refuses a bare-array output that is not — so an unbounded
+  // list read cannot be added here without the declaration going red.
+  //
+  // Asserting the envelope alone would not be worth much: the interesting half is
+  // that the keyset cursor actually WALKS. A cursor that returns the same page
+  // forever, or skips a row at the page boundary, produces a perfectly
+  // well-shaped `Page` every time — so the walk is driven at `limit: 1`, where
+  // every boundary is a boundary, and checked against the whole set.
+  it('11. the list reads answer with a page, and the cursor walks every row', async () => {
+    const prices = await greta.invoke<Page<{ article: string }>>('shop/price-list');
+    expect(prices.entries.map((p) => p.article)).toEqual([
+      'chain-9s',
+      'labor',
+      'shop-supplies',
+      'tube-28',
+    ]);
+
+    const walked: string[] = [];
+    let cursor: string | null = null;
+    // Bounded so a non-advancing cursor fails the assertion below rather than
+    // hanging the suite — a test that hangs reports nothing.
+    for (let hop = 0; hop < 10; hop += 1) {
+      const page: Page<{ article: string }> = await greta.invoke('shop/price-list', {
+        limit: 1,
+        ...(cursor === null ? {} : { cursor }),
+      });
+      walked.push(...page.entries.map((p) => p.article));
+      cursor = page.nextCursor;
+      if (cursor === null) break;
+    }
+    expect(cursor).toBeNull();
+    expect(walked).toEqual(['chain-9s', 'labor', 'shop-supplies', 'tube-28']);
+
+    // The customer list has its OWN hand-written keyset SQL, so it gets its own
+    // walk rather than being trusted because the price list's worked. Its entries
+    // still carry the hydrated bikes — the page bounds that hydration rather than
+    // removing it.
+    type CustomerEntry = { number: string; bikes: { id: string }[] };
+    const first = await greta.invoke<Page<CustomerEntry>>('shop/list-customers', { limit: 1 });
+    expect(first.entries).toHaveLength(1);
+    expect(first.nextCursor).toBe(first.entries[0]!.number);
+    expect(Array.isArray(first.entries[0]!.bikes)).toBe(true);
+
+    const seen: string[] = [];
+    let at: string | null = null;
+    for (let hop = 0; hop < 10; hop += 1) {
+      const page: Page<CustomerEntry> = await greta.invoke('shop/list-customers', {
+        limit: 1,
+        ...(at === null ? {} : { cursor: at }),
+      });
+      seen.push(...page.entries.map((c) => c.number));
+      at = page.nextCursor;
+      if (at === null) break;
+    }
+    expect(at).toBeNull();
+    // Every seeded customer, once, in the order the cursor walks — a boundary
+    // that repeated or skipped a row would show up here and nowhere else.
+    expect(seen).toEqual(['2001', '2002']);
+  });
+
+  // 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.
+  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 nextOf = (res: Response): string | null => {
+      // `<http://localhost/api/prices?limit=1&cursor=labor>; rel="next"` — the
+      // page size and every filter ride along, which is why a client FOLLOWS the
+      // link instead of assembling one.
+      const url = /<([^>]+)>;\s*rel="next"/.exec(res.headers.get('Link') ?? '')?.[1];
+      if (url === undefined) return null;
+      const parsed = new URL(url);
+      return `${parsed.pathname}${parsed.search}`;
+    };
+
+    const walked: string[] = [];
+    let next: string | null = '/api/prices?limit=1';
+    for (let hop = 0; hop < 10 && next !== null; hop += 1) {
+      const res = await app.request(next);
+      expect(res.status).toBe(200);
+      // The BODY is the entries — the same array this endpoint answered with
+      // before it was paged, which is what makes adopting the page cost a client
+      // nothing.
+      const body = (await res.json()) as { article: string }[];
+      expect(Array.isArray(body)).toBe(true);
+      walked.push(...body.map((p) => p.article));
+      next = nextOf(res);
+    }
+    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.
+    const customers = await app.request('/api/customers?limit=1');
+    expect(((await customers.json()) as { number: string }[]).map((c) => c.number)).toEqual([
+      '2001',
+    ]);
+    expect(nextOf(customers)).toBe('/api/customers?limit=1&cursor=2001');
+
+    const timeline = await app.request(`/api/repairs/${repairId}/timeline?limit=1`);
+    expect(timeline.status).toBe(200);
+    expect((await timeline.json()) as unknown[]).toHaveLength(1);
+    expect(nextOf(timeline)).toMatch(/^\/api\/repairs\/.+\/timeline\?limit=1&cursor=.+$/);
+  });
 });