create-substrat 0.6.4 → 0.7.1

package/index.js

@@ -35,10 +35,10 @@ 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.79.0';
-const ENGINE_WORKORDER = '^0.6.6';
-const ENGINE_INVOICING = '^0.7.6';
-const BOUNDARY_LINT = '^0.0.8';
+const SUBSTRAT = '^0.84.0';
+const ENGINE_WORKORDER = '^0.8.0';
+const ENGINE_INVOICING = '^0.9.0';
+const BOUNDARY_LINT = '^0.1.0';
 
 const DOCS = 'https://substrat.net';
 
@@ -93,8 +93,27 @@ function packageJson(name) {
             { binding: 'SCOPE', class: 'ScopeDO' },
             // The scope-local sweep singleton — the deployment's own timer (#461).
             { binding: 'SWEEPER', class: 'SweeperDO' },
+            // Per-instance config delivered by the platform (/internal/configure) —
+            // one DO per tenant, rows per scope. Without it the app cannot receive
+            // the settings the dashboard offers its users.
+            { binding: 'CONFIG', class: 'ConfigDO' },
           ],
         },
+        // The declared per-instance settings — MIRRORED from src/manifest.ts
+        // (`SHOP_ENV`), because `substrat push` reads JSON, not TS. The dashboard
+        // renders its Settings form from this; keep the two in sync.
+        envSpec: [
+          {
+            key: 'SHOP_NAME',
+            label: 'Workshop name',
+            description: 'The workshop name shown to customers. Set per install.',
+            placeholder: 'Söder Cykel & Service',
+            default: 'Substrat Bike Shop',
+            required: false,
+            secret: false,
+            group: 'General',
+          },
+        ],
         devServers: DEV_SERVERS,
       },
       scripts: {
@@ -150,9 +169,11 @@ const TSCONFIG = `${JSON.stringify(
       types: ['node'],
     },
     include: ['src', 'test'],
-    // The worker compiles against workers-types under its own config
-    // (tsconfig.worker.json) — the node config must not see it.
-    exclude: ['src/worker.ts'],
+    // The worker and its Cloudflare-only stores compile against workers-types
+    // under their own config (tsconfig.worker.json) — the node config must not
+    // see them. `src/routes.ts` is deliberately NOT excluded: the shared route
+    // table must typecheck under both, which is what keeps it host-agnostic.
+    exclude: ['src/worker.ts', 'src/config-do.ts'],
   },
   null,
   2,

package/package.json

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

package/template/.substrat/playbook.md

@@ -7,8 +7,8 @@ reshape the reference into it. Read the whole thing before starting — both the
 (Step 4) and the checkpoints (Step 7) are hard stops.
 
 **The target is a reviewed design, not running code.** Steps 1–2 learn the domain and map it
-onto what already exists; Step 3 writes a checked-in `DESIGN.md` in the user's own vocabulary;
-Step 4 is a **hard stop** where the user reads and approves it. Only then does Step 5 reshape
+onto what already exists; Step 3 writes a checked-in `spec/concept.md` in the user's own
+vocabulary; Step 4 is a **hard stop** where the user reads and approves it. Only then does Step 5 reshape
 the reference into their domain. The design gate (Step 4) is *upstream* of the two code
 checkpoints (Step 7) — a user with zero Substrat knowledge gets to say "yes, that's the app I
 want" before implementation, not after.
@@ -147,8 +147,9 @@ stop. Do not scaffold.
 ## Step 3 — Write the design document
 
 **This is the deliverable.** Everything before now was learning; this is where it lands
-somewhere the user can hold. Write a **checked-in `DESIGN.md`** in the project root, in the
-user's own vocabulary — no Substrat internals, no decision refs, no cross-references to
+somewhere the user can hold. Write a **checked-in `spec/concept.md`** — beside
+`spec/model.ts`, which is this same design one rung more concrete — in the user's own
+vocabulary — no Substrat internals, no decision refs, no cross-references to
 platform docs. Someone who has never heard of Substrat must be able to read it and recognise
 their own business.
 
@@ -291,8 +292,8 @@ and event subjects all need one id, so naming such an entity in `parents`,
 compile error. It is still a full model member with migrations and a row type. A
 single-column key that is not called `id` stays fully pointable.
 
-Behaviour stays prose in `DESIGN.md`. Inventing a way to declare a state *transition* means
-the boundary slipped.
+Behaviour stays prose in `spec/concept.md`. Inventing a way to declare a state *transition*
+means the boundary slipped.
 
 Full reference: https://substrat.net/concepts/model
 
@@ -307,7 +308,7 @@ to make the build pass.
 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
 every pattern this step describes), then reshape it into the user's domain from the approved
-`DESIGN.md`:
+`spec/concept.md`:
 
 - **Rename the vocabulary** — `shop_customers`/`shop_bikes` → the user's nouns, the `shop/*`
   operation names, the roles, the price-list shape. If the user's core noun maps onto a work

package/template/AGENTS.md

@@ -44,11 +44,21 @@ src/migrations.ts      the SqlMigration[]                         ← module cod
 src/module.ts          imports both; operations + registration    ← module code
 src/provision.ts       MODULES, ROLES, grant shapes — node-free    ← module code
 src/seed.ts            host, tenants, demo cast, seed world        ← harness
-src/server.ts          thin wrapper, one route per operation       ← harness
-src/worker.ts          the deployable Cloudflare worker            ← harness
+src/routes.ts          the HTTP route table — BOTH hosts mount it   ← 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
 ```
 
+**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
+(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).
+
 `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
 permission registry from it (package.json `substrat.permissions`). Roles or
@@ -56,18 +66,36 @@ modules defined anywhere else will run locally and silently not deploy.
 `worker.ts` **mounts** the platform's `/internal/*` management contract via
 `mountPlatformSurface` from `@substrat-run/vertical-host` (one call — the routes
 and the `{ error }` envelope are authored there, not here, so they can't drift or
-ship half-done). What `worker.ts` still owns is your app routes and **the auth
-seam** — the dev `x-principal` header is the only caller resolution until you wire
-real auth there; deploying with `ALLOW_DEV_HEADER` set is a cross-tenant hole with
-a UI.
+ship half-done). What `worker.ts` still owns is **the auth seam** — the dev
+`x-principal` header is the only caller resolution until you wire real auth there;
+deploying with `ALLOW_DEV_HEADER` set is a cross-tenant hole with a UI.
+
+Among the hooks it passes, **`onConfigure` is the one you must not drop.** It is
+how per-instance settings reach the running app: the dashboard's Settings → Env
+and Identity tabs POST to `/internal/configure`, and a vertical that supplies no
+hook answers **501** to that call for its whole life — the setting is saved, the
+dashboard reports `delivered: false`, and the app never sees it. That includes the
+`substrat:auth` issuer choice, i.e. the difference between a working login and
+401-on-everything. The starter stores deliveries in `config-do.ts` and reads them
+back through `resolveScopedEnvSpec` (`instanceConfig`). Read settings that way and
+never off `env` directly: an `envSpec` default rides as a worker binding shared by
+every install of one serving script, so `env.FOO` is the same string for every
+tenant no matter what any of them saved. Declare a setting in **both**
+`src/manifest.ts` (`SHOP_ENV`) and package.json `substrat.envSpec` — `substrat
+push` reads the JSON, not the TypeScript.
 
 ## The rules (non-negotiable)
 
 **Module code** = everything reachable from a `ModuleRegistration` (operations,
-consumers). Rules 1–4 are enforced mechanically by `boundary-lint`.
-
-1. **Data access is `ctx.sql` only.** Never import `better-sqlite3`, an adapter, or
-   `node:*` in module code.
+consumers). Rules 1–5 are enforced mechanically by `boundary-lint`.
+
+1. **Data access is `ctx.sql` only.** Never import `better-sqlite3`, an adapter,
+   `node:*`, or `cloudflare:workers` in module code. That last one is not a style rule:
+   it exports an ambient `env`, so a single import hands module code every binding and
+   secret your worker declares — including its own `SCOPE` Durable Object namespace,
+   which reaches *another scope's* data. `ctx.sql` is closed over one scope and cannot.
+   Capabilities arrive on `ctx`; `DurableObject` is imported in harness code
+   (`worker.ts`, `*-do.ts`), never here.
 2. **No `fetch` / network in module code.** It would hold the scope's transaction open on
    a third party. The sanctioned path is a **connector**: emit a fat event, register a
    handler that runs outside the transaction. An integration is never impossible because
@@ -79,16 +107,22 @@ consumers). Rules 1–4 are enforced mechanically by `boundary-lint`.
    the shortcut *works* and silently welds you to an engine's private schema forever. Need
    extra data on an engine entity? Add **your own side table keyed by the engine's id** —
    never a column upstream.
-5. **Every operation checks a permission first.** `assertAllowed(await ctx.check(PERM))`
+5. **Time comes from `ctx.now()`.** Module code has no other clock — `new Date()` and
+   `Date.now()` are banned exactly like `node:*`. It is the same instant for the whole
+   operation, so your rows and the events announcing them agree about when. Store it as
+   ISO text, never an epoch integer. Because the host injects the clock, a scenario can
+   test elapsed time (`manualClock` from `@substrat-run/kernel`) instead of sleeping or
+   shrinking the window to zero — the workaround that proves nothing.
+6. **Every operation checks a permission first.** `assertAllowed(await ctx.check(PERM))`
    is the first line.
-6. **Every mutation emits a fat event** — a consumer must never need a cross-module read.
-7. **Never fork an engine.** Extend by composition. If you must fork, the engine drew its
+7. **Every mutation emits a fat event** — a consumer must never need a cross-module read.
+8. **Never fork an engine.** Extend by composition. If you must fork, the engine drew its
    line wrong — that's design feedback, not a coding problem.
-8. **IDs are `ulid()`. Money is strings** via `@substrat-run/contracts` helpers
+9. **IDs are `ulid()`. Money is strings** via `@substrat-run/contracts` helpers
    (`moneyOf`, `mulMoney`, `addDecimal`, `compareDecimal`) — never floats.
-9. **Web-standard APIs always** — `globalThis.crypto`, `TextEncoder`, `URL`. Never
-   hand-roll a hash to dodge an import ban.
-10. **Parse, don't trust.** Zod at every boundary — but import `z` from
+10. **Web-standard APIs always** — `globalThis.crypto`, `TextEncoder`, `URL`. Never
+    hand-roll a hash to dodge an import ban.
+11. **Parse, don't trust.** Zod at every boundary — but import `z` from
     `@substrat-run/contracts`, **never from `zod`**. Zod schemas don't compose across
     copies or majors; composing a contracts schema into one built from a separate `zod`
     fails at *runtime* (`expected a Zod schema`) with an error pointing nowhere near the
@@ -105,7 +139,7 @@ This is also what lets a portal permission-walk reach the owner.
 
 ```sh
 npm test                        # the scenario, including the denials
-npx @substrat-run/boundary-lint # the layer rules (1–4)
+npx @substrat-run/boundary-lint # the layer rules (1–5)
 npm run typecheck
 ```
 

package/template/src/config-do.ts

@@ -0,0 +1,86 @@
+import { DurableObject } from 'cloudflare:workers';
+
+/**
+ * The key the platform delivers a scope's identity-provider choice under.
+ *
+ * It lives HERE rather than in `worker.ts` for a runtime reason worth knowing: workerd
+ * requires every named export of the entry module to be a handler or a Durable Object
+ * class, so exporting a plain constant from `worker.ts` makes the whole worker fail to
+ * boot — with a `tsc`-clean tree and a green test suite. Config vocabulary belongs with
+ * the config store anyway.
+ */
+export const AUTH_CONFIG_KEY = 'substrat:auth';
+
+/**
+ * The vertical's own per-instance CONFIG store — the durable half of
+ * `/internal/configure`.
+ *
+ * The platform delivers per-install settings (the dashboard's Settings → Env and
+ * Identity tabs) by POSTing them to `/internal/configure` on this worker. A vertical
+ * that supplies no `onConfigure` hook answers 501 to that call for its whole life:
+ * the dashboard records the setting, reports `delivered: false`, and the running app
+ * never sees it. This DO is what makes the hook answerable.
+ *
+ * It is a HARNESS store, not module code — the config a scope runs on is not domain
+ * data, and it must survive a scope-DO storage wipe (a restore, a rebind), so it
+ * deliberately lives outside the scope's own DO. One DO per TENANT, rows keyed by
+ * scope; the table matches `scope_config` in `@substrat-run/vertical-auth`'s
+ * `IdentityDO` exactly, so a project that later adopts vertical-auth for real logins
+ * swaps the binding and keeps its rows.
+ *
+ * Sandbox-clean (D-18): this is one of the deployment's OWN Durable Object classes,
+ * declared in package.json `substrat.runtimeNeeds.stores`. No control-plane binding,
+ * no service binding — the platform refuses those.
+ */
+export class ConfigDO extends DurableObject<Record<string, never>> {
+  private ready = false;
+
+  /** Lazily create the table — cheaper than a blockConcurrencyWhile on every wake. */
+  private init(): void {
+    if (this.ready) return;
+    this.ctx.storage.sql.exec(
+      `CREATE TABLE IF NOT EXISTS scope_config (
+         scope_id TEXT NOT NULL, key TEXT NOT NULL, value TEXT NOT NULL,
+         PRIMARY KEY (scope_id, key))`,
+    );
+    this.ready = true;
+  }
+
+  /**
+   * Upsert config delivered for one scope. Key-by-key rather than a replace, so a
+   * partial delivery composes with what is already there; idempotent, so the
+   * platform's reconciliation sweep can re-run it safely.
+   */
+  async setScopeConfig(scopeId: string, entries: Array<{ key: string; value: string }>): Promise<void> {
+    this.init();
+    for (const { key, value } of entries) {
+      this.ctx.storage.sql.exec(
+        'INSERT OR REPLACE INTO scope_config (scope_id, key, value) VALUES (?, ?, ?)',
+        scopeId, key, value,
+      );
+    }
+  }
+
+  /**
+   * The config delivered to one scope, as a plain map — exactly the `delivered`
+   * argument of `resolveScopedEnvSpec(spec, env, delivered)`. Reading it back is what
+   * keeps the hook from being write-only: an env-spec key set per install must be
+   * overlaid here, because env-spec defaults ride as worker bindings SHARED by every
+   * install of one serving script, so reading `env` alone always yields the shared
+   * default no matter what the tenant saved.
+   */
+  async getScopeConfig(scopeId: string): Promise<Record<string, string>> {
+    this.init();
+    const config: Record<string, string> = {};
+    for (const row of this.ctx.storage.sql.exec('SELECT key, value FROM scope_config WHERE scope_id = ?', scopeId)) {
+      config[row.key as string] = row.value as string;
+    }
+    return config;
+  }
+}
+
+/** The typed stub surface — what `worker.ts` calls across the DO boundary. */
+export interface ConfigDo {
+  setScopeConfig(scopeId: string, entries: Array<{ key: string; value: string }>): Promise<void>;
+  getScopeConfig(scopeId: string): Promise<Record<string, string>>;
+}

package/template/src/manifest.ts

@@ -1,4 +1,4 @@
-import { moduleManifest, permissionKey } from '@substrat-run/contracts';
+import { moduleManifest, permissionKey, type EnvVarSpec } from '@substrat-run/contracts';
 
 // ============================================================================
 // The vertical's MANIFEST — the reviewable contract the kernel reads at
@@ -19,6 +19,32 @@ export const SHOP_PERM = {
   bikeManage: permissionKey.parse('bike:manage'),
 };
 
+/**
+ * The vertical's DECLARED per-instance settings — the allow-list of config keys this
+ * app consumes, and what the dashboard renders a form from. A key not declared here is
+ * a key the app cannot read, however it is delivered.
+ *
+ * Read them with `resolveScopedEnvSpec(SHOP_ENV, env, delivered)` (never `env.FOO`
+ * directly): precedence is delivered > env > default, and only that overlay sees a
+ * value one tenant saved for one install — a spec `default` rides as a worker binding
+ * shared by every install of the serving script.
+ *
+ * MIRRORED in package.json `substrat.envSpec` (what `substrat push` carries — it reads
+ * JSON, not TS); keep the two in sync.
+ */
+export const SHOP_ENV: EnvVarSpec[] = [
+  {
+    key: 'SHOP_NAME',
+    label: 'Workshop name',
+    description: 'The workshop name shown to customers. Set per install.',
+    placeholder: 'Söder Cykel & Service',
+    default: 'Substrat Bike Shop',
+    required: false,
+    secret: false,
+    group: 'General',
+  },
+];
+
 export const bikeShopManifest = moduleManifest.parse({
   id: 'bikeshop',
   version: '0.0.1',
@@ -44,5 +70,6 @@ export const bikeShopManifest = moduleManifest.parse({
     { entityType: 'bike', parentType: 'customer' },
     { entityType: 'workorder', parentType: 'bike' },
   ],
+  envSpec: SHOP_ENV,
   entitlementKey: 'bikeshop',
 });

package/template/src/module.ts

@@ -71,7 +71,7 @@ const createCustomerOp: OperationHandler<
   const id = ulid();
   ctx.sql.exec(
     `INSERT INTO shop_customers (id, number, name, phone, created_at) VALUES (?, ?, ?, ?, ?)`,
-    [id, input.number, input.name, input.phone ?? null, new Date().toISOString()],
+    [id, input.number, input.name, input.phone ?? null, ctx.now()],
   );
   return ctx.sql.query<CustomerRow>('SELECT * FROM shop_customers WHERE id = ?', [id])[0]!;
 };
@@ -101,7 +101,7 @@ const registerBikeOp: OperationHandler<
   const id = ulid();
   ctx.sql.exec(
     `INSERT INTO shop_bikes (id, customer_id, label, frame_no, created_at) VALUES (?, ?, ?, ?, ?)`,
-    [id, customer.id, input.label, input.frameNo ?? null, new Date().toISOString()],
+    [id, customer.id, input.label, input.frameNo ?? null, ctx.now()],
   );
   // Record the bike → customer edge the manifest declared, so the portal walk
   // (workorder → bike → customer) can resolve an entity-narrowed grant.

package/template/src/routes.ts

@@ -0,0 +1,140 @@
+import type { Context, Hono } from 'hono';
+import { classifyError } from '@substrat-run/vertical-host';
+import type { ScopeStub } from '@substrat-run/kernel';
+
+/**
+ * The bike shop's HTTP API — ONE route table, adapter- and auth-agnostic.
+ *
+ * Both entrypoints mount this: `server.ts` (node, pure-SQLite adapter, `x-principal`
+ * dev auth) 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.
+ *
+ * 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>;
+
+// 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>>();
+
+  /**
+   * One error vocabulary, shared with the platform surface: `classifyError`
+   * (@substrat-run/vertical-host) is the same function `mountPlatformSurface` uses, so a
+   * permission denial is 403, a missing thing 404, a broken invariant 409, a runtime
+   * fault 502 — identically on both hosts. "No opinion" becomes the caller's 400.
+   *
+   * In `worker.ts` this handler is REPLACED: Hono keeps only the last-registered
+   * `onError`, and `mountPlatformSurface` installs its own. That is harmless precisely
+   * because both are built on `classifyError` — same input, same answer. Registering it
+   * here is what gives `server.ts`, which mounts no platform surface, the same behaviour.
+   */
+  app.onError((err, c) => {
+    const seen = classifyError(err);
+    if (seen) return c.json({ error: seen.message }, seen.status);
+    return c.json({ error: err instanceof Error ? err.message : String(err) }, 400);
+  });
+
+  // -- 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.
+  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);
+  });
+
+  // -- 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.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) => c.json(await (await S(c)).invoke('shop/price-list')));
+  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) =>
+    c.json(await (await S(c)).invoke('workorder/list', { status: c.req.query('status') })),
+  );
+  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) =>
+    c.json(
+      await (await S(c)).invoke('shop/timeline', {
+        entityType: 'workorder',
+        entityId: c.req.param('id'),
+      }),
+    ),
+  );
+  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) => c.json(await (await S(c)).invoke('shop/portal-repairs')));
+
+  // -- 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/: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') })),
+  );
+}

package/template/src/server.ts

@@ -7,12 +7,14 @@ import type { Context } from 'hono';
 import { PermissionDenied, type ScopeStub } from '@substrat-run/kernel';
 import type { PrincipalId } from '@substrat-run/contracts';
 import { buildBikeShopHost, seedBikeShop, type BikeShopWorld } from './seed.js';
+import { mountApi } from './routes.js';
 
 // ============================================================================
-// A deliberately THIN dev API. Each route authenticates (a dev principal picker
-// via the `x-principal` header — a real deployment swaps in a session), gets the
-// scope, and invokes ONE operation. There is no business logic here: every rule
-// lives in an operation or an engine.
+// The DEV entrypoint. It owns exactly three things — a SQLite host on disk, the
+// `x-principal` persona picker, and the port — and then mounts `routes.ts`, the
+// same route table `worker.ts` mounts. There is no business logic here and no
+// route here either: a route added to this file would exist in dev and 404 in
+// production, which is the one failure this split exists to prevent.
 // ============================================================================
 
 const dataDir = join(dirname(fileURLToPath(import.meta.url)), '..', '.data');
@@ -44,100 +46,13 @@ function stub(c: Context): Promise<ScopeStub> {
 
 const app = new Hono();
 
-app.onError((err, c) => {
-  const message = err instanceof Error ? err.message : String(err);
-  if (err instanceof PermissionDenied) return c.json({ error: message }, 403);
-  if (/invalid transition|immutable|already/.test(message)) return c.json({ error: message }, 409);
-  if (/not found|unknown scope|unknown operation/.test(message)) return c.json({ error: message }, 404);
-  return c.json({ error: message }, 400);
-});
-
+// The persona picker — genuinely dev-only, so it stays out of the shared table.
+// Its ABSENCE in the worker is how a client can tell it is talking to a real
+// deployment; the worker answers `/api/me` instead.
 app.get('/api/cast', (c) => c.json(CAST));
 
-// Customers, bikes, price list (the vertical's own tables).
-app.get('/api/customers', async (c) => c.json(await (await stub(c)).invoke('shop/list-customers')));
-app.post('/api/customers', async (c) =>
-  c.json(await (await stub(c)).invoke('shop/create-customer', await c.req.json())),
-);
-app.post('/api/customers/:id/bikes', async (c) =>
-  c.json(
-    await (await stub(c)).invoke('shop/register-bike', {
-      customerId: c.req.param('id'),
-      ...(await c.req.json<Record<string, unknown>>()),
-    }),
-  ),
-);
-app.get('/api/prices', async (c) => c.json(await (await stub(c)).invoke('shop/price-list')));
-app.post('/api/prices', async (c) =>
-  c.json(await (await stub(c)).invoke('shop/upsert-price', await c.req.json())),
-);
-
-// Repairs — the vertical's create/complete/close wrap the engine; assign/start/
-// report/get/list are the engine's own operations, invoked directly.
-app.get('/api/repairs', async (c) =>
-  c.json(await (await stub(c)).invoke('workorder/list', { status: c.req.query('status') })),
-);
-app.post('/api/repairs', async (c) =>
-  c.json(await (await stub(c)).invoke('shop/create-repair', await c.req.json())),
-);
-app.get('/api/repairs/:id', async (c) =>
-  c.json(await (await stub(c)).invoke('workorder/get', { orderId: c.req.param('id') })),
-);
-app.get('/api/repairs/:id/timeline', async (c) =>
-  c.json(
-    await (await stub(c)).invoke('shop/timeline', {
-      entityType: 'workorder',
-      entityId: c.req.param('id'),
-    }),
-  ),
-);
-app.post('/api/repairs/:id/assign', async (c) =>
-  c.json(
-    await (await stub(c)).invoke('workorder/assign', {
-      orderId: c.req.param('id'),
-      ...(await c.req.json<Record<string, unknown>>()),
-    }),
-  ),
-);
-app.post('/api/repairs/:id/start', async (c) =>
-  c.json(await (await stub(c)).invoke('workorder/start', { orderId: c.req.param('id') })),
-);
-app.post('/api/repairs/:id/time', async (c) =>
-  c.json(
-    await (await stub(c)).invoke('workorder/report-time', {
-      orderId: c.req.param('id'),
-      ...(await c.req.json<Record<string, unknown>>()),
-    }),
-  ),
-);
-app.post('/api/repairs/:id/material', async (c) =>
-  c.json(
-    await (await stub(c)).invoke('workorder/report-material', {
-      orderId: c.req.param('id'),
-      ...(await c.req.json<Record<string, unknown>>()),
-    }),
-  ),
-);
-app.post('/api/repairs/:id/complete', async (c) =>
-  c.json(await (await stub(c)).invoke('shop/complete-repair', { orderId: c.req.param('id') })),
-);
-app.post('/api/repairs/:id/close', async (c) =>
-  c.json(await (await stub(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) =>
-  c.json(await (await stub(c)).invoke('shop/portal-repairs')),
-);
-
-// Invoicing (the sibling engine, fed by event).
-app.get('/api/invoicing', async (c) => c.json(await (await stub(c)).invoke('invoicing/list')));
-app.get('/api/invoicing/:id', async (c) =>
-  c.json(await (await stub(c)).invoke('invoicing/get', { underlagId: c.req.param('id') })),
-);
-app.post('/api/invoicing/:id/export', async (c) =>
-  c.json(await (await stub(c)).invoke('invoicing/export', { underlagId: c.req.param('id') })),
-);
+// Everything else — including `/api/invoke` and the shared error envelope.
+mountApi(app, stub);
 
 const PORT = Number(process.env.PORT ?? 8873);
 serve({ fetch: app.fetch, port: PORT });

package/template/src/worker.ts

@@ -2,9 +2,10 @@
  * This vertical as a deployable Cloudflare Worker — SANDBOX-CLEAN and
  * control-plane-less: the shape `substrat push` deploys into the platform's
  * dispatch namespace. Its only durable stores are its OWN DO classes — `SCOPE`
- * (kernel + engines + this vertical, bundled) and `SWEEPER` (the deployment's
- * own timer, #461); no CONTROL_PLANE binding, no service bindings, no ASSETS
- * binding — the platform refuses those.
+ * (kernel + engines + this vertical, bundled), `SWEEPER` (the deployment's own
+ * timer, #461) and `CONFIG` (per-instance settings delivered by the platform);
+ * no CONTROL_PLANE binding, no service bindings, no ASSETS binding — the
+ * platform refuses those.
  *
  * `substrat push` derives the deploy config from `substrat.runtimeNeeds` in
  * package.json (entry = this file, stores = the DO classes exported here) —
@@ -25,8 +26,10 @@ import type { Context } from 'hono';
 import { HTTPException } from 'hono/http-exception';
 import {
   principalId,
+  resolveScopedEnvSpec,
   scopeId,
   tenantId,
+  z,
   type PrincipalId,
   type ScopeId,
   type TenantId,
@@ -41,10 +44,21 @@ import {
 import { readRoutedNode, RouterAssertionError, type ScopeStub } from '@substrat-run/kernel';
 import { mountPlatformSurface } from '@substrat-run/vertical-host';
 import { MODULES, OWNER_ROLE_KEY, ROLES } from './provision.js';
+import { SHOP_ENV } from './manifest.js';
+import { mountApi } from './routes.js';
+import { AUTH_CONFIG_KEY, ConfigDO, type ConfigDo } from './config-do.js';
 
 /** The scope-DO class = the app binary: kernel + engines + this vertical, bundled. */
 export const ScopeDO = defineScopeDO(MODULES, {});
 
+/**
+ * The per-instance config store (`config-do.ts`) — one per tenant, rows keyed by scope.
+ * Declared as a store in package.json `substrat.runtimeNeeds.stores`, like `ScopeDO`
+ * above and `SweeperDO` below. Re-exported because workerd resolves a DO class from the
+ * ENTRY module's exports; defining it in another file is fine, hiding it here is not.
+ */
+export { ConfigDO };
+
 /**
  * The deployment's own timer (#461): a roster-keeping singleton whose alarm runs
  * each provisioned scope's due recurring work — executor retries and any
@@ -82,6 +96,8 @@ interface Env {
   SCOPE: DurableObjectNamespace;
   /** The roster-keeping sweep singleton — the deployment's own timer (#461). */
   SWEEPER: DurableObjectNamespace;
+  /** Per-instance config delivered by the platform (`/internal/configure`). */
+  CONFIG: DurableObjectNamespace;
   /** Local dev only: when 'true', trust the `x-principal` header. NEVER set in prod. */
   ALLOW_DEV_HEADER?: string;
   /** Shared secret the router presents (how this worker knows the asserted node is real). */
@@ -110,6 +126,49 @@ function hostFor(env: Env): CloudflareScopeHost {
   return host;
 }
 
+/** This tenant's config DO — one per tenant, holding a row set per scope. */
+function configDo(env: Env, node: Node): DurableObjectStub & ConfigDo {
+  return env.CONFIG.get(env.CONFIG.idFromName(node.tenantId)) as DurableObjectStub & ConfigDo;
+}
+
+/**
+ * The scope's delivered auth choice. Parsed LENIENTLY on purpose: an absent or
+ * malformed entry means "nothing delivered", never a throw, so a bad delivery can
+ * never lock an instance out of its own login.
+ */
+const authChoice = z.object({
+  mode: z.literal('oidc'),
+  issuer: z.string().min(1),
+  clientId: z.string().min(1).optional(),
+  clientSecret: z.string().min(1).optional(),
+});
+
+/**
+ * Everything this instance was configured with, in ONE DO hop: the ordinary declared
+ * settings (`SHOP_ENV`) resolved delivered > env > default, and the structured
+ * `substrat:auth` choice the dashboard's Identity tab sends.
+ *
+ * Reading settings THROUGH this — rather than off `env` — is the whole reason the
+ * `/internal/configure` hook exists: a spec `default` rides as a worker binding shared
+ * by every install of one serving script, so `env.SHOP_NAME` is the same string for
+ * every tenant no matter what any of them saved.
+ */
+async function instanceConfig(env: Env, node: Node) {
+  const delivered = await configDo(env, node).getScopeConfig(node.scopeId);
+  const settings = resolveScopedEnvSpec(SHOP_ENV, env as unknown as Record<string, unknown>, delivered).values;
+  let identity: z.infer<typeof authChoice> | null = null;
+  const raw = delivered[AUTH_CONFIG_KEY];
+  if (raw) {
+    try {
+      const parsed = authChoice.safeParse(JSON.parse(raw));
+      identity = parsed.success ? parsed.data : null;
+    } catch {
+      identity = null;
+    }
+  }
+  return { settings, identity };
+}
+
 /**
  * THE AUTH SEAM (see the header comment): resolve the caller to a PrincipalId,
  * or null for nobody. Replace the body with a real session/bearer verifier
@@ -127,25 +186,49 @@ async function authenticatedPrincipal(req: Request, env: Env): Promise<Principal
 async function stub(c: Context<{ Bindings: Env }>): Promise<ScopeStub> {
   const node = nodeFor(c.req.raw, c.env);
   const principal = await authenticatedPrincipal(c.req.raw, c.env);
-  if (!principal) throw new HTTPException(401, { message: 'unauthorized' });
+  if (!principal) throw new HTTPException(401, { message: await unauthorizedReason(c.env, node) });
   return hostFor(c.env).getScope(principal, node.tenantId, node.scopeId);
 }
 
+/**
+ * Why the caller is nobody — a DIAGNOSIS, not a bare "unauthorized".
+ *
+ * The expensive case to debug is the one that looks like a platform bug and is not:
+ * a tenant picks an identity provider in the dashboard, the platform delivers it here
+ * successfully, and every request is still 401 — because this starter ships no auth.
+ * Saying so, and naming the seam, is the difference between a five-minute fix and a
+ * support thread. Only runs on the failure path, so it costs a DO hop on 401s alone.
+ */
+async function unauthorizedReason(env: Env, node: Node): Promise<string> {
+  try {
+    const { identity } = await instanceConfig(env, node);
+    if (identity) {
+      return `unauthorized — this instance has an identity provider configured (${identity.issuer}), but this vertical has not wired it up yet: implement \`authenticatedPrincipal\` in src/worker.ts (the auth seam)`;
+    }
+  } catch {
+    // The config store is unreachable — that is not the caller's problem to hear about.
+  }
+  return 'unauthorized';
+}
+
 const app = new Hono<{ Bindings: Env }>();
 
-// Who am I — resolves the caller without invoking anything.
+// Who am I, and what instance am I on — resolves the caller without invoking
+// anything. Auth-shaped and host-specific, so it stays OUT of the shared table:
+// the dev server answers `/api/cast` instead, and a client can tell the two apart.
 app.get('/api/me', async (c) => {
+  const node = nodeFor(c.req.raw, c.env);
   const principal = await authenticatedPrincipal(c.req.raw, c.env);
-  if (!principal) return c.json({ error: 'unauthorized' }, 401);
-  return c.json({ principal });
+  if (!principal) return c.json({ error: await unauthorizedReason(c.env, node) }, 401);
+  const { settings, identity } = await instanceConfig(c.env, node);
+  return c.json({ principal, settings, identity: identity ? { issuer: identity.issuer } : null });
 });
 
-// Generic invoke: the kernel checks a permission inside EVERY operation, so a
-// generic route is exactly as safe as one route per operation.
-app.post('/api/invoke', async (c) => {
-  const { op, input } = await c.req.json<{ op: string; input?: unknown }>();
-  return c.json((await (await stub(c)).invoke(op, input)) ?? null);
-});
+// ── The vertical's API — the SAME table `server.ts` mounts (src/routes.ts) ───
+// Including `/api/invoke`. Mounted BEFORE the platform surface: Hono keeps only the
+// last-registered `onError`, so the platform's envelope wins for the whole app — which
+// is harmless because both handlers classify through the same `classifyError`.
+mountApi(app, stub);
 
 // ── /internal/* — the platform-gated management contract ────────────────────
 // The control plane provisions, heals, inspects and restores installs through
@@ -173,6 +256,15 @@ mountPlatformSurface<Env>(app, {
   onDeleteScope: async (env, s) => {
     await sweeper(env).forgetScope(s);
   },
+  // Per-instance config delivery (the dashboard's Settings → Env and Identity tabs).
+  // WITHOUT this hook `/internal/configure` answers 501 for the life of the app: the
+  // dashboard saves the setting, reports `delivered: false`, and the running worker
+  // never sees it — including the `substrat:auth` issuer choice that is the difference
+  // between a working login and 401-on-everything. Store it; `instanceConfig` reads it
+  // back. Idempotent, so the platform's reconciliation sweep can re-deliver safely.
+  onConfigure: async (env, b) => {
+    await configDo(env, { tenantId: b.tenantId, scopeId: b.scopeId }).setScopeConfig(b.scopeId, b.entries);
+  },
 });
 
 // Unmatched /api/* fails as JSON; everything else gets a pointer, not a UI —
@@ -181,7 +273,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 }',
+    api: 'POST /api/invoke { op, input } — plus the named routes in src/routes.ts',
     docs: 'https://substrat.net',
   }),
 );

package/template/tsconfig.worker.json

@@ -9,5 +9,5 @@
     "skipLibCheck": true,
     "noEmit": true
   },
-  "include": ["src/worker.ts", "src/provision.ts", "src/manifest.ts", "src/migrations.ts", "src/module.ts"]
+  "include": ["src/worker.ts", "src/routes.ts", "src/config-do.ts", "src/provision.ts", "src/manifest.ts", "src/migrations.ts", "src/module.ts"]
 }