create-substrat 0.1.1 → 0.2.0

package/index.js

@@ -20,9 +20,11 @@ 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.net';
@@ -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,

package/package.json

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

package/template/.substrat/playbook.md

@@ -103,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
 
@@ -178,7 +180,11 @@ plain language, so nothing there is a surprise:
    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.
+   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).
@@ -355,10 +361,15 @@ and who can see other tenants' data?* A permission diff nobody understands is th
 
 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)

package/template/AGENTS.md

@@ -42,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"]
+}