create-substrat 0.7.0 → 0.7.2

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.85.0';
+const ENGINE_WORKORDER = '^0.8.1';
+const ENGINE_INVOICING = '^0.9.1';
+const BOUNDARY_LINT = '^0.1.1';
 
 const DOCS = 'https://substrat.net';
 

package/package.json

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

@@ -3,15 +3,18 @@ import {
   compareDecimal,
   moneyOf,
   mulMoney,
+  pageVisible,
   z,
   type EntityRef,
   type Money,
+  type Page,
 } from '@substrat-run/contracts';
 import {
   assertAllowed,
   ulid,
   type ModuleRegistration,
   type OperationHandler,
+  type PageParams,
 } from '@substrat-run/kernel';
 import {
   closeWorkOrder,
@@ -71,7 +74,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 +104,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.
@@ -244,15 +247,25 @@ const closeRepairOp: OperationHandler<{ orderId: string }, WorkOrder> = async (c
  * PER-ENTITY check per repair. A portal customer holds an entity-narrowed grant
  * on their own customer record, so the walk workorder → bike → customer lets
  * them through for their own repairs and no one else's.
+ *
+ * Paged by OVER-FETCHING, which is what a permission-filtered walk needs: a page
+ * of 20 rows read from the table can leave 3 standing after the proof walk, so the
+ * fetch size and the page size are not the same number and cannot be made the same
+ * number. `pageVisible` does the over-fetch and advances the cursor by the last row
+ * EXAMINED — advancing by the last row RETURNED would re-examine every rejected row
+ * on the next request, and a page the walk rejects entirely would never advance at
+ * all. So a SHORT page does not end this walk; only a null `nextCursor` does.
  */
-const portalRepairsOp: OperationHandler<undefined, WorkOrder[]> = async (ctx) => {
-  const visible: WorkOrder[] = [];
-  for (const order of listOrders(ctx)) {
-    const decision = await ctx.check(WO.read, { entityType: 'workorder', entityId: order.id });
-    if (decision.allowed) visible.push(order);
-  }
-  return visible;
-};
+const portalRepairsOp: OperationHandler<PageParams | undefined, Page<WorkOrder>> = async (
+  ctx,
+  input,
+) =>
+  pageVisible(
+    (p) => listOrders(ctx, { ...input, ...p }),
+    input,
+    async (order) =>
+      (await ctx.check(WO.read, { entityType: 'workorder', entityId: order.id })).allowed,
+  );
 
 const timelineInput = z.object({
   entityType: z.string().min(1),

package/template/test/scenario.test.ts

@@ -3,7 +3,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import Database from 'better-sqlite3';
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { addMoney, moneyOf, mulMoney } from '@substrat-run/contracts';
+import { addMoney, moneyOf, mulMoney, type Page } from '@substrat-run/contracts';
 import type { ScopeStub } from '@substrat-run/kernel';
 import type { SqliteScopeHost } from '@substrat-run/adapter-sqlite';
 import type { WorkOrder, BillableLine } from '@substrat-run/engine-workorder';
@@ -105,7 +105,8 @@ describe('bike-shop scenario', () => {
       lisbeth.invoke('workorder/report-time', { orderId: repairId, hours: '1' }),
     ).rejects.toThrow(/permission denied/);
     // …but she CAN see her own repair through the portal walk.
-    await expect(lisbeth.invoke<WorkOrder[]>('shop/portal-repairs')).resolves.toHaveLength(1);
+    const lisbethSees = await lisbeth.invoke<Page<WorkOrder>>('shop/portal-repairs');
+    expect(lisbethSees.entries).toHaveLength(1);
 
     // The cross-tenant attacker: claiming t1's scope under his OWN tenant fails
     // the (tenant, scope) pair check…
@@ -120,7 +121,8 @@ describe('bike-shop scenario', () => {
     await expect(rutger.invoke('invoicing/list')).rejects.toThrow(/permission denied/);
     // …the control: the per-entity portal walk resolves for him too, and returns
     // exactly nothing — an open door onto an empty room, not a denial.
-    await expect(rutger.invoke<WorkOrder[]>('shop/portal-repairs')).resolves.toEqual([]);
+    const rutgerSees = await rutger.invoke<Page<WorkOrder>>('shop/portal-repairs');
+    expect(rutgerSees.entries).toEqual([]);
   });
 
   it('5. priced completion: the half-hour minimum bills, internal dropped, math exact', async () => {
@@ -153,9 +155,9 @@ describe('bike-shop scenario', () => {
   });
 
   it('6. star topology: the invoicing engine consumed workorder.completed', async () => {
-    const underlag = await greta.invoke<{ id: string; status: string; total: string }[]>(
-      'invoicing/list',
-    );
+    const { entries: underlag } = await greta.invoke<
+      Page<{ id: string; status: string; total: string }>
+    >('invoicing/list');
     expect(underlag).toHaveLength(1);
     expect(underlag[0]!.status).toBe('open');
     expect(underlag[0]!.total).toBe('336.5');
@@ -178,9 +180,10 @@ describe('bike-shop scenario', () => {
     const lisbeth = await host.getScope(w.lisbeth, w.t1, w.s1);
     const otto = await host.getScope(w.otto, w.t1, w.s1);
 
-    const hers = await lisbeth.invoke<WorkOrder[]>('shop/portal-repairs');
-    expect(hers.map((o) => o.id)).toEqual([repairId]);
-    await expect(otto.invoke<WorkOrder[]>('shop/portal-repairs')).resolves.toEqual([]);
+    const hers = await lisbeth.invoke<Page<WorkOrder>>('shop/portal-repairs');
+    expect(hers.entries.map((o) => o.id)).toEqual([repairId]);
+    const ottos = await otto.invoke<Page<WorkOrder>>('shop/portal-repairs');
+    expect(ottos.entries).toEqual([]);
 
     // Lisbeth reads her repair's timeline via the same entity walk…
     await expect(
@@ -194,7 +197,9 @@ describe('bike-shop scenario', () => {
   });
 
   it('8. export makes the underlag immutable; the next completion opens a new one', async () => {
-    const [underlag] = await greta.invoke<{ id: string }[]>('invoicing/list');
+    const {
+      entries: [underlag],
+    } = await greta.invoke<Page<{ id: string }>>('invoicing/list');
     await greta.invoke('invoicing/export', { underlagId: underlag!.id });
     await expect(greta.invoke('invoicing/export', { underlagId: underlag!.id })).rejects.toThrow(
       /immutable/,
@@ -214,7 +219,9 @@ describe('bike-shop scenario', () => {
     });
     await greta.invoke('shop/complete-repair', { orderId: repair2.id });
 
-    const all = await greta.invoke<{ status: string; total: string }[]>('invoicing/list');
+    const { entries: all } = await greta.invoke<Page<{ status: string; total: string }>>(
+      'invoicing/list',
+    );
     expect(all).toHaveLength(2);
     expect(all.filter((u) => u.status === 'open')).toHaveLength(1);
     expect(all.filter((u) => u.status === 'exported')).toHaveLength(1);