create-substrat 0.7.0 → 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.83.0';
-const ENGINE_WORKORDER = '^0.7.3';
-const ENGINE_INVOICING = '^0.8.3';
-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';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-substrat",
-  "version": "0.7.0",
+  "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

@@ -87,10 +87,15 @@ 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
@@ -102,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
@@ -128,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/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.