create-substrat 0.4.1 → 0.4.2

package/index.js

@@ -20,13 +20,16 @@ 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.
-// 0.45.0 is the release that ships `@substrat-run/vertical-host` (#510) — the
-// mountPlatformSurface the template's worker mounts — so this pin and that release
-// move together (it also covers `defineScopeSweeperDO`, #461, from 0.40.0).
-const SUBSTRAT = '^0.45.0';
-// Engines version on their own line (0.3.x), independent of the kernel/contracts line.
-const ENGINES = '^0.3.37';
-const BOUNDARY_LINT = '^0.0.5';
+// The runtime packages release together off one version line, so one constant is right
+// for all of them.
+const SUBSTRAT = '^0.71.0';
+// Engines do NOT share a line — each one versions on its own, so a single ENGINES
+// constant silently stops resolving the moment any engine crosses a minor. It did:
+// this file pinned `^0.3.37` while workorder had moved to 0.4.x and invoicing to 0.6.x,
+// so a freshly scaffolded project could not install. One pin per engine, deliberately.
+const ENGINE_WORKORDER = '^0.4.3';
+const ENGINE_INVOICING = '^0.6.2';
+const BOUNDARY_LINT = '^0.0.7';
 
 const DOCS = 'https://substrat.net';
 
@@ -95,8 +98,8 @@ function packageJson(name) {
         '@substrat-run/adapter-sqlite': SUBSTRAT,
         '@substrat-run/adapter-cloudflare': SUBSTRAT,
         '@substrat-run/vertical-host': SUBSTRAT,
-        '@substrat-run/engine-workorder': ENGINES,
-        '@substrat-run/engine-invoicing': ENGINES,
+        '@substrat-run/engine-workorder': ENGINE_WORKORDER,
+        '@substrat-run/engine-invoicing': ENGINE_INVOICING,
         hono: '^4.6.0',
         '@hono/node-server': '^1.13.0',
         'better-sqlite3': '^13.0.3',

package/package.json

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

package/template/.substrat/playbook.md

@@ -222,7 +222,62 @@ Approval of the design is what unlocks Step 5. Until you have it, you are still
 
 ---
 
-## Step 5 — Reshape the reference
+## Step 5 — Declare the model
+
+The design is approved. Before reshaping any code, declare **what exists** in
+`spec/model.ts`: entities, the operations over them, and the permissions those operations
+check. One TypeScript module, and the compiler checks the joins between them.
+
+```ts
+import { defineEntities, defineOperations, emitModel } from '@substrat-run/contracts';
+import { z } from '@substrat-run/contracts';
+
+export const entities = defineEntities({
+  customer: {
+    table: 'acme_customers',
+    fields: z.object({ id: z.string(), number: z.string(), name: z.string() }),
+    key: ['number'],
+    erasable: ['name'],
+  },
+  site: { table: 'acme_sites', fields: z.object({ id: z.string(), customer_id: z.string() }), parents: ['customer'] },
+});
+
+export const PERMISSIONS = ['customer:manage'] as const;
+
+export const operations = defineOperations(entities, PERMISSIONS)({
+  'acme/create-customer': {
+    summary: 'Register a customer',
+    permission: 'customer:manage',
+    input: z.object({ number: z.string(), name: z.string() }),
+    output: entities.customer.fields,
+    emits: { entity: 'customer', entityIdFrom: 'id', type: 'acme.customer-created', schemaVersion: 1, piiClass: 'none' },
+  },
+});
+
+export const model = emitModel(entities);
+```
+
+These are compile errors, not lints: a `parents` naming no entity, a `permission` that is
+not declared, an `entityIdFrom` naming no field of that operation's `output`, a `payload`
+carrying a field the entity marks `erasable`, a `{var}` in an HTTP path that names no input
+field. All before a handler exists.
+
+Field names mirror the SQL columns, snake_case included — a prettier naming here is a second
+description of the same rows. Not every table is an entity: an entity is something the
+platform can point at (attachments hang off one, grants narrow to one, events are about one).
+
+Behaviour stays prose in `DESIGN.md`. Inventing a way to declare a state *transition* means
+the boundary slipped.
+
+Full reference: https://substrat.net/concepts/model
+
+**Do not edit `spec/model.ts` while reshaping the code.** If a handler cannot return what the
+model declares, that is real information — say so and stop, rather than reshaping the model
+to make the build pass.
+
+---
+
+## Step 6 — Reshape the reference
 
 The design is approved. The scaffold already contains a working vertical in `src/` + `test/` —
 the bike-repair shop. **Read it first** (it's your Callout: the real, green implementation of
@@ -314,7 +369,7 @@ closed-door assertion with a control proving a neighbouring door is still open.
 
 ---
 
-## Step 6 — Run it
+## Step 7 — Run it
 
 Build confidence in this order, and **show the user the output of each**:
 
@@ -336,7 +391,7 @@ and typed wrappers over the routes. Ask first — it roughly doubles the work.
 
 ---
 
-## Step 7 — The two checkpoints. STOP HERE.
+## Step 8 — The two checkpoints. STOP HERE.
 
 **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.
@@ -357,7 +412,7 @@ and who can see other tenants' data?* A permission diff nobody understands is th
 
 ---
 
-## Step 8 — Deploy (optional)
+## Step 9 — Deploy (optional)
 
 Only if the user asks. Local-first is a legitimate stopping point.
 
@@ -389,7 +444,7 @@ cross-tenant hole with a UI.
 
 ---
 
-## Step 9 — Leave the project competent
+## Step 10 — 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