create-substrat 0.1.0 → 0.2.0

package/index.js

@@ -20,12 +20,14 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 const TEMPLATE = join(HERE, 'template');
 
 // Published today; Substrat is 0.x, so these are caret ranges on the current minor.
-const SUBSTRAT = '^0.29.0';
+// 0.40.0 is the release that ships `defineScopeSweeperDO` (#461), which the
+// template's worker imports — this pin and that adapter release move together.
+const SUBSTRAT = '^0.40.0';
 // Engines version on their own line (0.3.x), independent of the kernel/contracts line.
-const ENGINES = '^0.3.27';
+const ENGINES = '^0.3.37';
 const BOUNDARY_LINT = '^0.0.5';
 
-const DOCS = 'https://substrat.ahlstrand.es';
+const DOCS = 'https://substrat.net';
 
 function fail(message) {
   process.stderr.write(`\n  create-substrat: ${message}\n\n`);
@@ -64,17 +66,33 @@ function packageJson(name) {
       version: '0.0.0',
       private: true,
       type: 'module',
+      // What `substrat push` reads: the permission surface (the registry the
+      // promotion checkpoint diffs) and the runtime needs the deploy config is
+      // derived from — you never author wrangler config (src/worker.ts is the
+      // entry; ScopeDO is the store it exports).
+      substrat: {
+        permissions: 'src/provision.ts',
+        runtimeNeeds: {
+          entry: 'src/worker.ts',
+          stores: [
+            { binding: 'SCOPE', class: 'ScopeDO' },
+            // The scope-local sweep singleton — the deployment's own timer (#461).
+            { binding: 'SWEEPER', class: 'SweeperDO' },
+          ],
+        },
+      },
       scripts: {
         dev: 'tsx watch src/server.ts',
         server: 'tsx src/server.ts',
         test: 'vitest run',
-        typecheck: 'tsc --noEmit',
+        typecheck: 'tsc --noEmit && tsc -p tsconfig.worker.json --noEmit',
         'lint:boundaries': 'substrat-boundary-lint',
       },
       dependencies: {
         '@substrat-run/kernel': SUBSTRAT,
         '@substrat-run/contracts': SUBSTRAT,
         '@substrat-run/adapter-sqlite': SUBSTRAT,
+        '@substrat-run/adapter-cloudflare': SUBSTRAT,
         '@substrat-run/engine-workorder': ENGINES,
         '@substrat-run/engine-invoicing': ENGINES,
         hono: '^4.6.0',
@@ -83,7 +101,9 @@ function packageJson(name) {
       },
       devDependencies: {
         '@substrat-run/boundary-lint': BOUNDARY_LINT,
+        '@cloudflare/workers-types': '^4.20250109.0',
         '@types/better-sqlite3': '^7.6.0',
+        '@types/node': '^22.0.0',
         concurrently: '^9.0.0',
         tsx: '^4.19.0',
         typescript: '^5.6.0',
@@ -112,6 +132,9 @@ 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'],
   },
   null,
   2,
@@ -167,9 +190,13 @@ pnpm typecheck
 
 function main() {
   const target = process.argv[2];
-  if (!target || target === '-h' || target === '--help') {
+  if (target === '-h' || target === '--help') {
+    usage();
+    process.exit(0);
+  }
+  if (!target) {
     usage();
-    process.exit(target ? 0 : 1);
+    fail('a target directory is required — e.g. `npm create substrat my-app` (or `.` for here).');
   }
 
   const dest = resolve(target);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-substrat",
-  "version": "0.1.0",
-  "description": "Scaffold a Substrat vertical — `npm create substrat`. Placeholder reserving the entry point; the initializer is not released yet.",
+  "version": "0.2.0",
+  "description": "Scaffold a Substrat vertical — `npm create substrat <dir>`.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/template/.substrat/playbook.md

@@ -1,21 +1,33 @@
 # Playbook — build a vertical on Substrat
 
 The always-on rules live in [`AGENTS.md`](../AGENTS.md); read them first. This playbook is
-the **flow**: interview the user, tell them honestly how much of their app already exists,
-then build and run the part that doesn't. Read the whole thing before starting — the
-checkpoint in Step 6 is a hard stop.
+the **flow**: interview the user, tell them honestly how much of their app already exists, and
+**land a design document they can review and approve before a line of code is written** — then
+reshape the reference into it. Read the whole thing before starting — both the design gate
+(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
+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.
 
 This project ships with a small **working reference vertical** — a bike-repair shop on
-`engine-workorder` + `engine-invoicing`, green out of the box (`npm test`). It is your
-worked example and your starting point: you **reshape** it into the user's domain rather
-than building from an empty directory. Work in the project root.
+`engine-workorder` + `engine-invoicing`, green out of the box (`npm test`). It is your worked
+example and your build starting point: once the design is approved you **reshape** it into the
+user's domain rather than building from an empty directory. Work in the project root.
 
 ---
 
 ## Step 1 — Interview
 
-Ask, don't assume. **Three to five questions, conversational, one message.** You are
-learning the *shape* of the domain, not writing a spec.
+Ask, don't assume. **Three to five questions, conversational, one message.** You are learning
+the *shape* of the domain — the answers become the design document (Step 3), so listen for
+vocabulary, the cast, and who must be denied what, not just features. **Adapt depth to the
+user**: someone who already knows their domain cold needs fewer, sharper questions; someone
+thinking out loud needs you to draw the shape out. One flow, not branching tracks — read the
+room and dial the teaching up or down.
 
 1. **What are you building, and who uses it?** (the firm, the cast)
 2. **What's the thing that moves through the system?** A job, a repair, an inspection, an
@@ -34,8 +46,10 @@ detail, skip to Step 2 and confirm your reading of it instead of re-asking.
 ## Step 2 — The coverage map
 
 **This is the most valuable thing you do, and the easiest to get wrong by being
-flattering.** Tell the user what already exists and what they are actually signing up to
-build. Be specific and honest.
+flattering.** Work out what already exists and what the user is actually signing up to build.
+Be specific and honest. This analysis is the analytical core of the design document (Step 3) —
+sections 3 ("what already exists vs. what's yours") and 4 ("who is denied what") are this map,
+written down.
 
 **First, list the engines that actually exist. Do not trust any hard-coded list:**
 
@@ -89,10 +103,12 @@ Imported directly; their in-scope functions run in **your** transaction. Read ea
 **No import.** You emit; they consume. This is the star topology.
 
 - **`engine-invoicing`** — invoice basis and lines, immutable after export. Consumes
-  `workorder.completed` and `commerce.order-placed`, so a vertical that imports zero engines
-  still gets invoicing by emitting an event. Its consumer find-or-creates the customer's
-  *open* basis and appends. It has **no tax/VAT concept** — say so before an EU user
-  discovers it.
+  `workorder.completed`, `commerce.order-placed` **and** `timesheet.period-closed` (a
+  closed/approved period of reported time — `closeId`/`customer`/`period`/`billable`/
+  `total`, deduped on `closeId`), so an e-commerce or time-reporting vertical that imports
+  zero engines still gets invoicing by emitting an event. Its consumer find-or-creates the
+  customer's *open* basis and appends. It has **no tax/VAT concept** — say so before an EU
+  user discovers it.
 
 ### Tier 2b — connectors, for anything off-box
 
@@ -128,25 +144,90 @@ stop. Do not scaffold.
 
 ---
 
-## Step 3 — Decisions
+## Step 3 — Write the design document
 
-Short. Recommend a default and move.
+**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
+platform docs. Someone who has never heard of Substrat must be able to read it and recognise
+their own business.
 
-- **Auth.** Local dev uses an `x-principal` header — a dev seam, not a login. Offer to wire
-  a real login now if they want it; otherwise default to the dev header and say it **must**
-  be replaced before anything real. Real auth gates *exposing* the app, not *building* it.
-- **The cast.** Confirm the personas and their roles (e.g. `office-admin`, `technician`,
-  `portal-customer`). Roles are the user's vocabulary — name them for the persona.
-- **Two tenants, always.** Seed a second tenant that exists to be attacked. This is how the
-  isolation gets proven rather than claimed.
+**Top line, verbatim** — the house marker for a pre-code design:
+
+```
+Status: draft v0.1 · Last updated: <date> · For review before any code
+```
+
+**The template** — the coverage map (Step 2) is sections 3–4, already done; the rest is the
+interview written down. Two sections deliberately *preview* the code checkpoints of Step 7 in
+plain language, so nothing there is a surprise:
+
+1. **What we're building & who uses it** — the firm and the cast, one paragraph.
+2. **The thing that moves through the system** — the core noun and its lifecycle
+   (the states it passes through, and which transitions must not be skippable).
+3. **What already exists vs. what's yours** — the coverage map as tiers: the kernel
+   (free), the engines you compose, the connectors, and the Tier-3 vocabulary/pricing/
+   screens that are yours. If it's a **bad fit, this is where the honest no lands** — say
+   so and stop; do not write the rest.
+4. **Who is denied what** — the load-bearing section, and a plain-language *preview of the
+   permission diff*: each role and what it can and cannot see. Make two answers impossible
+   to miss — **who can see the money, and who can see other customers' data.**
+5. **Money & sign-off** — invoice / quote / receipt / none; anything gated on a signature
+   or a check before a step can happen.
+6. **The cast, roles, and tenancy** — the named roles per persona (roles are the user's
+   vocabulary — name them for the persona: `workshop-admin`, not `role_1`). **Two tenants,
+   always** — the second exists to be attacked, which is how isolation gets proven rather
+   than claimed.
+7. **The data we'll store** — the vertical's own tables and fields in plain terms. This
+   *previews the migration diff*; migrations are **append-only forever after first ship**,
+   so this is the cheap moment to get the shape right. **Every human-readable string the
+   design promises on an output artifact needs a named source here** — if §8 shows an
+   invoice line saying "Konsulttid Anna", some table in §7 must own that name, because
+   principals are ULIDs. A promised name with no source table is a missing table,
+   discovered at build time instead of in this review.
+8. **The scenario the test will replay** — the happy path plus the denials that prove
+   isolation (wrong role denied, customer A sees theirs and customer B sees nothing, a
+   cross-tenant attacker gets nothing).
+9. **Open decisions** — each with a **recommended default**, so the user chooses rather
+   than specifies:
+   - **Auth.** Local dev uses an `x-principal` header — a dev seam, not a login. Default to
+     it and note it must be replaced before anything real; offer to wire a real login (the
+     bike-shop reference shows the Better Auth pattern) now if they want it. Real auth gates
+     *exposing* the app, not *building* it.
+   - **Deploy or stay local.** Local-first is a legitimate endpoint; default to it.
+10. **Out of scope / deferred** — what you are deliberately not building, so the review is
+    about a bounded thing.
+
+End with a short **"Review questions for the human"** block (2–3 questions) — the things the
+user must actively confirm, not rubber-stamp.
+
+---
+
+## Step 4 — The design gate. STOP HERE.
+
+**Present the design document and wait for approval. Do not reshape the reference, do not
+write code.**
+
+This is a *human* gate, and it is the whole point: it happens **before** any code, upstream of
+the two implementation checkpoints in Step 7. Walk the user through section 4 ("who is denied
+what") in **their own vocabulary** until they can answer, without your help: *who can see the
+money, and who can see other customers' data?*
+
+**A gate assumes a competent reviewer.** If the user cannot evaluate the permission preview,
+say so rather than letting them wave it through — a design nobody understands is theater, and
+reproduces exactly the failure Substrat exists to prevent. Iterate the document until they
+can, and only then take explicit approval.
+
+Approval of the design is what unlocks Step 5. Until you have it, you are still in design.
 
 ---
 
-## Step 4 — Reshape the reference
+## Step 5 — Reshape the reference
 
-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 interview:
+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`:
 
 - **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
@@ -159,7 +240,7 @@ step describes), then reshape it into the user's domain from the interview:
 - **Drop what the domain doesn't need, add its own tables** for anything the engines don't
   own. If the user's core noun *isn't* work-order-shaped, you may replace more of `src/` —
   but the seed/server/test scaffolding and the layout still hold.
-- **Re-run the gates as you go** (Step 5) — the reference is green, so any red is something
+- **Re-run the gates as you go** (Step 6) — the reference is green, so any red is something
   you just changed.
 
 The dependencies are already wired in `package.json` (the `@substrat-run/*` packages, `hono`,
@@ -233,7 +314,7 @@ closed-door assertion with a control proving a neighbouring door is still open.
 
 ---
 
-## Step 5 — Run it
+## Step 6 — Run it
 
 Build confidence in this order, and **show the user the output of each**:
 
@@ -255,9 +336,10 @@ and typed wrappers over the routes. Ask first — it roughly doubles the work.
 
 ---
 
-## Step 6 — The two checkpoints. STOP HERE.
+## Step 7 — The two checkpoints. STOP HERE.
 
-**You may never self-approve these. Present them and wait.**
+**You may never self-approve these. Present them and wait.** The design gate (Step 4) already
+took the user's approval of *what* to build; these confirm that the code matches it.
 
 1. **Migration diff** — every new `SqlMigration`, verbatim. Append-only forever once
    shipped, so this is the last cheap moment to change your mind.
@@ -275,14 +357,19 @@ and who can see other tenants' data?* A permission diff nobody understands is th
 
 ---
 
-## Step 7 — Deploy (optional)
+## Step 8 — Deploy (optional)
 
 Only if the user asks. Local-first is a legitimate stopping point.
 
-Substrat runs on Cloudflare via `@substrat-run/adapter-cloudflare` (Durable Objects). A
-vertical declares what it needs at runtime with a `substrat.runtimeNeeds` block in
-`package.json` (stores, node-compat, build). The deploy path is the authenticated CLI, and
-the author never holds a Cloudflare token:
+Substrat runs on Cloudflare via `@substrat-run/adapter-cloudflare` (Durable Objects).
+**This starter is pushable as scaffolded**: `src/worker.ts` is the deploy entry (the
+sandbox-clean shape, with the platform's `/internal/*` management contract already
+mounted), and package.json already carries the `substrat.runtimeNeeds` block the CLI
+derives the deploy config from (stores, node-compat, build) — you never author wrangler
+config. When you reshape the vertical, keep `src/provision.ts` the single source of
+MODULES/ROLES: both the dev server and the worker register from it, so a module added
+only in seed.ts would run locally and silently not deploy. The deploy path is the
+authenticated CLI, and the author never holds a Cloudflare token:
 
 - `substrat login` / `substrat whoami` — authenticate against the control plane.
 - `substrat push` — push the vertical; the version auto-bumps. A **private** (tenant-owned)
@@ -301,7 +388,7 @@ cross-tenant hole with a UI.
 
 ---
 
-## Step 8 — Leave the project competent
+## Step 9 — Leave the project competent
 
 The next session — in any tool — starts cold. The scaffold already ships `AGENTS.md`,
 `CLAUDE.md`, and the Cursor/opencode command stubs, so the rules and this flow survive. Your

package/template/AGENTS.md

@@ -5,8 +5,9 @@ Substrat kernel and its engines. This file is the always-on constitution — the
 that hold no matter what you touch. It is read by every AI tool (Claude Code, Cursor,
 opencode); do not duplicate it into tool-specific config.
 
-The full build flow — interview, coverage map, scaffold, run, checkpoints — is a
-**playbook**, not always-on context. Invoke it when you start or extend a vertical:
+The full build flow — interview, coverage map, a reviewed design document you approve
+before any code, then reshape, run, and the checkpoints — is a **playbook**, not always-on
+context. Invoke it when you start or extend a vertical:
 
 - **Claude Code**: `/substrat`
 - **Cursor / opencode**: the `new-vertical` command, or read [`.substrat/playbook.md`](.substrat/playbook.md)
@@ -41,11 +42,22 @@ code** (the rules below bind them); `seed`/`server` are **harness** (exempt).
 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/seed.ts            host, tenants, roles, grants, seed world    ← harness
+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
 test/scenario.test.ts  the scenario — including the denials
 ```
 
+`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
+modules defined anywhere else will run locally and silently not deploy.
+`worker.ts` carries the platform's `/internal/*` management contract 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.
+
 ## The rules (non-negotiable)
 
 **Module code** = everything reachable from a `ModuleRegistration` (operations,

package/template/src/provision.ts

@@ -0,0 +1,76 @@
+import {
+  definePermissions,
+  type PermissionKey,
+  type RoleDefinition,
+} from '@substrat-run/contracts';
+import { workorderModule, PERM as WO } from '@substrat-run/engine-workorder';
+import { invoicingModule, INVOICING_PERM as INV } from '@substrat-run/engine-invoicing';
+import { bikeShopModule } from './module.js';
+import { SHOP_PERM } from './manifest.js';
+
+// ============================================================================
+// The vertical's PROVISIONING surface — everything a deployment needs to know
+// about modules, roles and grant shapes, with NO node imports. Split from
+// seed.ts (which pulls in node:fs + the SQLite adapter) so the Cloudflare
+// worker (src/worker.ts) can bundle it, and so `substrat push` can read the
+// permission registry from it (package.json `substrat.permissions`).
+// ============================================================================
+
+/**
+ * The modules this vertical composes, in registration order. Registered by
+ * BOTH hosts (the dev server's SqliteScopeHost and the worker's ScopeDO), and
+ * read by the permission checkpoint — the artifact can never drift from what
+ * actually runs.
+ */
+export const MODULES = [workorderModule, invoicingModule, bikeShopModule];
+
+/** Entitlements are default-deny: one SKU key per module this vertical runs. */
+export const ENTITLEMENT_KEYS = ['workorder', 'invoicing', 'bikeshop'];
+
+const adminPerms: PermissionKey[] = [
+  SHOP_PERM.customerManage,
+  SHOP_PERM.bikeManage,
+  WO.create,
+  WO.read,
+  WO.assign,
+  WO.report,
+  WO.complete,
+  WO.close,
+  INV.read,
+  INV.export,
+];
+
+/**
+ * This vertical's role table — identical in every tenant, so it is a plain
+ * constant the permission snapshot can render without naming a tenant.
+ */
+export const ROLES: RoleDefinition[] = [
+  { key: 'workshop-admin', permissions: adminPerms, source: 'vertical' },
+  { key: 'mechanic', permissions: [WO.read, WO.report], source: 'vertical' },
+];
+
+/** Which role the installing owner holds — what /internal/provision assigns. */
+export const OWNER_ROLE_KEY = 'workshop-admin';
+
+/** What a portal customer receives, narrowed to their own customer record. */
+export const portalPerms: PermissionKey[] = [WO.read];
+
+/**
+ * Entity-narrowed grant SHAPES. The grants themselves are per-principal and
+ * minted at runtime, so they can never be a build artifact; their shape is what
+ * tells a reviewer which keys are reachable outside the role table.
+ */
+export const ENTITY_GRANTS: { entityType: string; permissions: PermissionKey[] }[] = [
+  { entityType: 'customer', permissions: portalPerms },
+];
+
+/**
+ * The single typed source for this vertical's permission surface — what the
+ * permission checkpoint and `substrat push` read (via package.json
+ * `substrat.permissions`).
+ */
+export const permissions = definePermissions({
+  modules: MODULES,
+  roles: ROLES,
+  entityGrants: ENTITY_GRANTS,
+});

package/template/src/seed.ts

@@ -5,18 +5,18 @@ import {
   principalId,
   scopeId,
   tenantId,
-  type PermissionKey,
   type PrincipalId,
-  type RoleDefinition,
   type ScopeId,
   type TenantId,
 } from '@substrat-run/contracts';
 import { ulid } from '@substrat-run/kernel';
 import { SqliteScopeHost } from '@substrat-run/adapter-sqlite';
-import { workorderModule, PERM as WO } from '@substrat-run/engine-workorder';
-import { invoicingModule, INVOICING_PERM as INV } from '@substrat-run/engine-invoicing';
-import { bikeShopModule } from './module.js';
-import { SHOP_PERM } from './manifest.js';
+import { ENTITLEMENT_KEYS, MODULES, OWNER_ROLE_KEY, portalPerms, ROLES } from './provision.js';
+
+// The provisioning surface (modules, roles, grant shapes) lives in
+// provision.ts — node-free so the worker bundles it and `substrat push` reads
+// it. Re-exported here for callers that treat seed.ts as the world's front door.
+export { ENTITY_GRANTS, MODULES, permissions, ROLES } from './provision.js';
 
 // ============================================================================
 // The seeded world. TWO tenants on purpose: the first is the shop the scenario
@@ -41,48 +41,6 @@ export interface BikeShopWorld {
   bianchiId: string; // Otto's bike
 }
 
-/**
- * The modules this vertical composes, in registration order. Exported so the
- * permission checkpoint (`pnpm lint:permissions`) renders from the same array
- * the running host registers — the artifact can never drift from reality.
- */
-export const MODULES = [workorderModule, invoicingModule, bikeShopModule];
-
-const adminPerms: PermissionKey[] = [
-  SHOP_PERM.customerManage,
-  SHOP_PERM.bikeManage,
-  WO.create,
-  WO.read,
-  WO.assign,
-  WO.report,
-  WO.complete,
-  WO.close,
-  INV.read,
-  INV.export,
-];
-
-/**
- * This vertical's role table — identical in every tenant, so it is a plain
- * constant the permission snapshot can render without naming a tenant. Exported
- * for the same reason as MODULES.
- */
-export const ROLES: RoleDefinition[] = [
-  { key: 'workshop-admin', permissions: adminPerms, source: 'vertical' },
-  { key: 'mechanic', permissions: [WO.read, WO.report], source: 'vertical' },
-];
-
-/** What a portal customer receives, narrowed to their own customer record. */
-const portalPerms: PermissionKey[] = [WO.read];
-
-/**
- * Entity-narrowed grant SHAPES. The grants themselves are per-principal and
- * minted at runtime, so they can never be a build artifact; their shape is what
- * tells a reviewer which keys are reachable outside the role table.
- */
-export const ENTITY_GRANTS: { entityType: string; permissions: PermissionKey[] }[] = [
-  { entityType: 'customer', permissions: portalPerms },
-];
-
 export function buildBikeShopHost(dir: string): SqliteScopeHost {
   const host = new SqliteScopeHost({ dir });
   for (const m of MODULES) host.registerModule(m);
@@ -102,7 +60,7 @@ async function provisionShop(
   await host.admin.createTenant(staff, { id: input.tenantId, slug: input.slug, name: input.name });
   // Entitlements are default-deny: the SKU flag for each module this vertical
   // runs must be granted before any of its operations resolve.
-  for (const key of ['workorder', 'invoicing', 'bikeshop']) {
+  for (const key of ENTITLEMENT_KEYS) {
     await host.admin.grantEntitlement(staff, input.tenantId, key);
   }
   await host.provisionScope(staff, {
@@ -117,7 +75,7 @@ async function provisionShop(
   for (const role of ROLES) await host.admin.defineRole(staff, input.tenantId, role);
   await host.admin.assignRole(staff, {
     principalId: input.owner,
-    roleKey: 'workshop-admin',
+    roleKey: OWNER_ROLE_KEY,
     node: { tenantId: input.tenantId, scopeId: null },
   });
 }

package/template/src/worker.ts

@@ -0,0 +1,345 @@
+/**
+ * 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.
+ *
+ * `substrat push` derives the deploy config from `substrat.runtimeNeeds` in
+ * package.json (entry = this file, stores = the DO classes exported here) —
+ * you never author wrangler config.
+ *
+ * ── THE AUTH SEAM ────────────────────────────────────────────────────────────
+ * This starter resolves a caller ONLY through the `x-principal` dev header,
+ * gated on ALLOW_DEV_HEADER — an impersonation bypass by design, for local
+ * `wrangler dev` and smoke tests. In production the gate is off and every
+ * /api/* call is 401 until you wire real auth into `authenticatedPrincipal`
+ * below (a session/bearer verifier that maps a login → PrincipalId — see
+ * @substrat-run/vertical-auth, the platform's pluggable AuthProvider +
+ * per-tenant identity DO, for the intended shape). Deploying with the dev
+ * header enabled is a cross-tenant hole with a UI. ──────────────────────────
+ */
+import { Hono } from 'hono';
+import type { Context } from 'hono';
+import { HTTPException } from 'hono/http-exception';
+import {
+  entitlementGrant,
+  principalId,
+  projectedIdentityLink,
+  queryScopeInput,
+  readScopeTableInput,
+  scopeId,
+  tenantId,
+  z,
+  type PrincipalId,
+  type ScopeId,
+  type TenantId,
+} from '@substrat-run/contracts';
+import {
+  CloudflareScopeHost,
+  defineScopeDO,
+  defineScopeSweeperDO,
+  SCOPE_SWEEPER_NAME,
+  type ScopeSweeperDo,
+} from '@substrat-run/adapter-cloudflare';
+import {
+  assertPlatformCall,
+  PlatformCallError,
+  readRoutedNode,
+  RouterAssertionError,
+  type ScopeStub,
+} from '@substrat-run/kernel';
+import { MODULES, OWNER_ROLE_KEY, ROLES } from './provision.js';
+
+/** The scope-DO class = the app binary: kernel + engines + this vertical, bundled. */
+export const ScopeDO = defineScopeDO(MODULES, {});
+
+/**
+ * The deployment's own timer (#461): a roster-keeping singleton whose alarm runs
+ * each provisioned scope's due recurring work — executor retries and any
+ * `manifest.schedules` your modules declare — with no control plane anywhere.
+ * `/internal/provision` and `/internal/reconcile` add scopes to the roster;
+ * `/internal/delete-scope` removes them. Costs nothing while the roster is empty.
+ */
+export const SweeperDO = defineScopeSweeperDO<Env>({
+  intervalMs: 120_000,
+  host: hostFor,
+});
+
+/** The sweeper singleton's stub — one roster and one alarm per deployment. */
+function sweeper(env: Env): DurableObjectStub & ScopeSweeperDo {
+  return env.SWEEPER.get(
+    env.SWEEPER.idFromName(SCOPE_SWEEPER_NAME),
+  ) as DurableObjectStub & ScopeSweeperDo;
+}
+
+interface Node {
+  tenantId: TenantId;
+  scopeId: ScopeId;
+}
+
+// A fixed dev node (valid ULIDs) — ONLY the fallback for local `wrangler dev`,
+// where there is no router to assert one; gated on ALLOW_DEV_HEADER (never set
+// in prod).
+const DEV_NODE: Node = {
+  tenantId: tenantId.parse('01JZ00000000000000000DEV01'),
+  scopeId: scopeId.parse('01JZ00000000000000000DEV02'),
+};
+
+interface Env {
+  /** One DO per scope — the vertical's only durable store (sandbox-clean). */
+  SCOPE: DurableObjectNamespace;
+  /** The roster-keeping sweep singleton — the deployment's own timer (#461). */
+  SWEEPER: 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). */
+  ROUTER_SECRET?: string;
+  /** Shared secret the platform presents on /internal/* calls. */
+  PLATFORM_SECRET?: string;
+}
+
+/** The routed (tenant, scope) — from the router assertion, or the dev node. */
+function nodeFor(req: Request, env: Env): Node {
+  let routed;
+  try {
+    routed = readRoutedNode(req.headers, { expectedSecret: env.ROUTER_SECRET });
+  } catch (e) {
+    if (e instanceof RouterAssertionError) throw new HTTPException(400, { message: e.message });
+    throw e;
+  }
+  if (routed) return { tenantId: routed.tenantId, scopeId: routed.scopeId };
+  if (env.ALLOW_DEV_HEADER === 'true') return DEV_NODE;
+  throw new HTTPException(503, { message: 'no scope was asserted for this request (missing router assertion)' });
+}
+
+function hostFor(env: Env): CloudflareScopeHost {
+  const host = new CloudflareScopeHost({ scope: env.SCOPE });
+  for (const m of MODULES) host.registerModule(m);
+  return host;
+}
+
+/**
+ * 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
+ * before exposing this worker to users — the dev header is dev-only.
+ */
+async function authenticatedPrincipal(req: Request, env: Env): Promise<PrincipalId | null> {
+  if (env.ALLOW_DEV_HEADER === 'true') {
+    const parsed = principalId.safeParse(req.headers.get('x-principal') ?? '');
+    if (parsed.success) return parsed.data;
+  }
+  return null; // ← wire real auth here
+}
+
+/** Resolve caller + routed node → a scope stub. 401 if nobody. */
+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' });
+  return hostFor(c.env).getScope(principal, node.tenantId, node.scopeId);
+}
+
+const app = new Hono<{ Bindings: Env }>();
+
+app.onError((err, c) => {
+  if (err instanceof HTTPException) return err.getResponse();
+  const m = err instanceof Error ? err.message : String(err);
+  if (/permission denied/i.test(m)) return c.json({ error: m }, 403);
+  if (/not found|unknown scope/i.test(m)) return c.json({ error: m }, 404);
+  if (/invalid transition|immutable/i.test(m)) return c.json({ error: m }, 409);
+  return c.json({ error: m }, 400);
+});
+
+// Who am I — resolves the caller without invoking anything.
+app.get('/api/me', async (c) => {
+  const principal = await authenticatedPrincipal(c.req.raw, c.env);
+  if (!principal) return c.json({ error: 'unauthorized' }, 401);
+  return c.json({ principal });
+});
+
+// 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);
+});
+
+// ── /internal/* — the platform-gated management contract ────────────────────
+// The control plane provisions, heals, inspects and restores installs through
+// these routes. A vertical without them cannot be installed or repaired, so
+// keep the FULL set even though your app code never calls them.
+
+function gatePlatform(c: { env: Env; req: { raw: Request } }): void {
+  try {
+    assertPlatformCall(c.req.raw.headers, { expectedSecret: c.env.PLATFORM_SECRET });
+  } catch (e) {
+    if (e instanceof PlatformCallError) throw new HTTPException(403, { message: e.message });
+    throw e;
+  }
+}
+
+const provisionBody = z.object({
+  tenantId,
+  scopeId,
+  owner: principalId,
+  slug: z.string().min(1),
+  name: z.string().min(1),
+  entitlements: z.array(entitlementGrant).optional(),
+  identityLinks: z.array(projectedIdentityLink).optional(),
+});
+
+// Provision ONE scope on the platform's instruction, CP-lessly: migrate the
+// modules, project this vertical's roles + the tenant's entitlements locally,
+// grant the owner their role at scope level. Platform-secret gated; idempotent.
+app.post('/internal/provision', async (c) => {
+  gatePlatform(c);
+  const body = provisionBody.parse(await c.req.json());
+  await hostFor(c.env).provisionScopeLocal({
+    tenantId: body.tenantId,
+    scopeId: body.scopeId,
+    owner: body.owner,
+    roles: ROLES,
+    ownerRoleKey: OWNER_ROLE_KEY,
+    entitlements: body.entitlements,
+    identityLinks: body.identityLinks,
+  });
+  // Provision is where the deployment learns a scope exists — put it on the
+  // sweep roster so its declared schedules run. (Never note a snapshot fork:
+  // recurring side effects must not fire off a preview copy, and fork-ness is
+  // only knowable platform-side — which is why this rides provision/reconcile,
+  // not request traffic.)
+  await sweeper(c.env).noteScope(body.tenantId, body.scopeId);
+  return c.json({ tenantId: body.tenantId, scopeId: body.scopeId, owner: body.owner }, 201);
+});
+
+// Repair (reconcile): re-deliver roles/entitlements/identity links to a scope.
+// This starter has no durable owner-of-record store (that lives with real auth
+// — the auth seam), so the owner must be re-supplied; without one the refusal
+// names the remedy instead of healing wrongly.
+const reconcileBody = provisionBody.partial({ owner: true, slug: true, name: true });
+app.post('/internal/reconcile', async (c) => {
+  gatePlatform(c);
+  const body = reconcileBody.parse(await c.req.json());
+  if (!body.owner) {
+    throw new HTTPException(409, {
+      message:
+        'no owner of record: this starter keeps none (an identity store — the auth seam — owns it). ' +
+        'Re-run the full install, or wire auth and record the owner durably.',
+    });
+  }
+  await hostFor(c.env).provisionScopeLocal({
+    tenantId: body.tenantId,
+    scopeId: body.scopeId,
+    owner: body.owner,
+    roles: ROLES,
+    ownerRoleKey: OWNER_ROLE_KEY,
+    entitlements: body.entitlements,
+    identityLinks: body.identityLinks,
+  });
+  // Reconcile is the roster's backfill: scopes provisioned before the sweeper
+  // shipped join it on their next platform repair.
+  await sweeper(c.env).noteScope(body.tenantId, body.scopeId);
+  return c.json({ tenantId: body.tenantId, scopeId: body.scopeId, owner: body.owner });
+});
+
+// Read-only scope-table introspection (console/dashboard Data view).
+app.get('/internal/tables', async (c) => {
+  gatePlatform(c);
+  return c.json(await hostFor(c.env).introspectScopeTables(scopeId.parse(c.req.query('scopeId'))));
+});
+app.get('/internal/tables/:table', async (c) => {
+  gatePlatform(c);
+  const scope = scopeId.parse(c.req.query('scopeId'));
+  const input = readScopeTableInput.parse({
+    table: c.req.param('table'),
+    limit: c.req.query('limit') ? Number(c.req.query('limit')) : undefined,
+    offset: c.req.query('offset') ? Number(c.req.query('offset')) : undefined,
+  });
+  return c.json(await hostFor(c.env).introspectScopeTable(scope, input));
+});
+// The SQL console: one read-only statement, enforced in the DO.
+app.post('/internal/query', async (c) => {
+  gatePlatform(c);
+  const body = queryScopeInput.extend({ scopeId }).parse(await c.req.json());
+  try {
+    return c.json(await hostFor(c.env).introspectScopeQuery(body.scopeId, { sql: body.sql }));
+  } catch (e) {
+    if (e instanceof Error && e.message.includes('read-only console')) {
+      throw new HTTPException(400, { message: e.message });
+    }
+    throw e;
+  }
+});
+
+// Platform-intent drain surface: the control plane PULLS pending intents from
+// this deployment's scope DOs and journals outcomes back.
+app.get('/internal/platform-requests', async (c) => {
+  gatePlatform(c);
+  const t = tenantId.parse(c.req.query('tenantId'));
+  const s = scopeId.parse(c.req.query('scopeId'));
+  return c.json(await hostFor(c.env).listPlatformRequests(t, s));
+});
+
+// Scope-storage lifecycle: snapshot/delete/export/restore/bookmarks/rewind —
+// what `substrat scope pull`/`restore` and the in-place update backout use.
+app.post('/internal/snapshot', async (c) => {
+  gatePlatform(c);
+  const body = z.object({ sourceScopeId: scopeId, newScopeId: scopeId }).parse(await c.req.json());
+  return c.json(await hostFor(c.env).snapshotScopeLocal(body.sourceScopeId, body.newScopeId), 201);
+});
+app.post('/internal/delete-scope', async (c) => {
+  gatePlatform(c);
+  const body = z.object({ scopeId }).parse(await c.req.json());
+  await hostFor(c.env).deleteScopeLocal(body.scopeId);
+  // Off the sweep roster too — a deleted scope must not be woken by the alarm.
+  await sweeper(c.env).forgetScope(body.scopeId);
+  return c.json({ deleted: body.scopeId });
+});
+app.get('/internal/export', async (c) => {
+  gatePlatform(c);
+  return c.json(await hostFor(c.env).exportScopeLocal(scopeId.parse(c.req.query('scopeId'))));
+});
+app.post('/internal/restore', async (c) => {
+  gatePlatform(c);
+  const body = z
+    .object({
+      tenantId: tenantId.optional(),
+      scopeId,
+      tables: z.array(
+        z.object({ name: z.string(), ddl: z.string(), columns: z.array(z.string()), rows: z.array(z.array(z.unknown())) }),
+      ),
+    })
+    .parse(await c.req.json());
+  const host = hostFor(c.env);
+  const result = await host.restoreScopeLocal(body.scopeId, body.tables);
+  // Re-project role definitions after an import — a dump may carry tuples but
+  // no role definitions; roles are code-defined, so re-projecting is always safe.
+  if (body.tenantId) await host.projectRolesLocal(body.tenantId, body.scopeId, ROLES);
+  return c.json(result);
+});
+app.get('/internal/bookmarks', async (c) => {
+  gatePlatform(c);
+  return c.json(await hostFor(c.env).migrationBookmarksLocal(scopeId.parse(c.req.query('scopeId'))));
+});
+app.post('/internal/rewind', async (c) => {
+  gatePlatform(c);
+  const body = z
+    .object({ scopeId, bookmark: z.string().min(1), force: z.boolean().optional() })
+    .parse(await c.req.json());
+  return c.json(await hostFor(c.env).rewindScopeLocal(body.scopeId, body.bookmark, { force: body.force }));
+});
+
+// Unmatched /api/* fails as JSON; everything else gets a pointer, not a UI —
+// this starter ships no SPA (add one and inline it at build time when you do).
+app.all('/api/*', (c) => c.json({ error: `unknown route: ${new URL(c.req.raw.url).pathname}` }, 404));
+app.all('*', (c) =>
+  c.json({
+    service: 'substrat vertical',
+    api: 'POST /api/invoke { op, input }',
+    docs: 'https://substrat.net',
+  }),
+);
+
+export default app;

package/template/tsconfig.worker.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "types": ["@cloudflare/workers-types"],
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src/worker.ts", "src/provision.ts", "src/manifest.ts", "src/migrations.ts", "src/module.ts"]
+}