create-substrat 0.8.4 → 0.8.6

package/index.js

@@ -36,11 +36,11 @@ 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.95.0';
-const ENGINE_WORKORDER = '^0.10.3';
-const ENGINE_INVOICING = '^0.9.11';
-const BOUNDARY_LINT = '^0.3.0';
-const DEV_ISSUER = '^0.1.9';
+const SUBSTRAT = '^0.98.0';
+const ENGINE_WORKORDER = '^0.10.6';
+const ENGINE_INVOICING = '^0.9.14';
+const BOUNDARY_LINT = '^0.4.0';
+const DEV_ISSUER = '^0.1.13';
 
 const DOCS = 'https://substrat.net';
 

package/package.json

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

package/template/.substrat/playbook.md

@@ -104,6 +104,15 @@ Imported directly; their in-scope functions run in **your** transaction. Read ea
 - **`engine-invites`** — how a person joins an org they are not in. Identifiers stored
   hashed and never returned; an invitation confers nothing until accepted. Reach for it
   before hand-rolling any invite flow.
+- **`engine-absence`** — leave and absence: leave types, requests that are decided rather
+  than simply written, and the balance they draw down (`requestAbsence`, `decideAbsence`,
+  `balanceAsOf`, `availability`). Which days count and which year a balance belongs to is
+  calendar policy, and calendar policy is yours.
+- **`engine-metering`** — metered usage: meters, usage recorded against them, and periods
+  closed over them (`configureMeter`, `recordUsage`, `closePeriod`, `usageTotal`). By call
+  rather than by event on purpose — you record usage inside the same transaction as the
+  work that produced it, so the ledger row and the work commit or roll back together.
+  Reach for it before adding a `usage` table and a monthly `SUM` of your own.
 
 ### Tier 2 — engines you feed by event
 
@@ -363,11 +372,44 @@ operations + the `ModuleRegistration`. Keep the split — the linter and tests e
   the customer.
 - Migrations: `SqlMigration[]`, tables prefixed `<vertical>_`, TEXT ids, ISO-8601 TEXT
   timestamps, money/decimals as TEXT. **Append-only forever after first ship.**
-- Operations: first line is always `assertAllowed(await ctx.check(PERM))`. Parse inputs
-  with Zod. `ctx.link(child, parent)` when creating related entities.
+- Operations: first line is always `assertAllowed(await ctx.check(PERM))`.
+  `ctx.link(child, parent)` when creating related entities.
+- **Handlers do not hand-parse their input.** The module passes
+  `operationInputs: operationInputsOf(<vertical>Operations)` beside its `operations`, and
+  the host parses every invocation against the declared schema before the guards and the
+  handler run — on every path in (HTTP, test, seed, schedule). The reference module already
+  does this; keep it. An inline `z.object(…).parse(input)` at the top of a handler is a
+  second description of a schema the model already declares, and it only covers the paths
+  that happen to reach that handler.
+- **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
+  invocation, so your rows and the events announcing them agree about when.
 - **The pricing moment is the pattern to copy**: read the engine's reported lines with
   `getReportedLines(ctx, orderId)` → apply the vertical's price list → call the engine's
   `completeWorkOrder`. One transaction, invariants intact.
+- **Swallowing an engine error requires `ctx.atomic`.** An engine call composed inside your
+  transaction has no boundary of its own, so a `catch` that handles the failure and carries
+  on leaves you holding its partial writes — the rows its invariants were protecting — and
+  then commits them. Wrap it instead:
+
+  ```ts
+  try {
+    await ctx.atomic(() => completeWorkOrder(ctx, { orderId, billable }));
+  } catch {
+    // the engine's rows, events, links and grants are all gone; your own writes
+    // survive, and the operation still commits once
+  }
+  ```
+
+  A succeeded `ctx.atomic` is still provisional: if the operation later throws, its writes
+  go too. Sub-transactions nest but must not interleave — starting two concurrently throws.
+  The line is whether the failure still reaches the caller. A catch that **swallows** an
+  engine error — one that does not rethrow — is what needs the boundary, and outside
+  `ctx.atomic` `boundary-lint` rejects it with no escape hatch. A catch that always
+  rethrows (`catch (e) { log(e); throw e }`) needs nothing, and neither does
+  `try`/`finally` with no `catch`: the operation still fails and the whole transaction
+  rolls back, which is already the outcome the rule protects. Reach for `ctx.atomic` when
+  you intend to *continue* past the failure.
 - Portal listing: iterate and `ctx.check(perm, entityRef)` **per entity** — a proof walk,
   not UI filtering.
 - **An entity's history is `readTimeline(ctx, entity, input)` from `@substrat-run/kernel`** —

package/template/AGENTS.md

@@ -136,12 +136,46 @@ consumers). Rules 1–5 are enforced mechanically by `boundary-lint`.
    (`moneyOf`, `mulMoney`, `addDecimal`, `compareDecimal`) — never floats.
 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
+11. **Parse, don't trust** — and the **host** is what parses. A module passes
+    `operationInputs: operationInputsOf(ops)` beside its `operations`, and every invocation
+    is parsed against the declared schema before the guards and the handler, on every path
+    in (HTTP, test, seed, schedule). Handlers do not hand-parse; a declared input nobody
+    parses stops being possible rather than merely discouraged. 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
     cause.
 
+## Swallowing an engine error requires `ctx.atomic`
+
+An engine call composed inside your transaction has no boundary of its own. A `catch` that
+handles the failure and carries on therefore leaves you holding the engine's partial
+writes — the rows its invariants were protecting — and then commits them. Give the call a
+boundary instead:
+
+```ts
+try {
+  await ctx.atomic(() => completeWorkOrder(ctx, { orderId, billable }));
+} catch {
+  // the engine's rows, events, links and grants are all gone; your own writes
+  // survive, and the operation still commits once
+}
+```
+
+A succeeded `ctx.atomic` is still provisional: if the operation later throws, its writes go
+too. Sub-transactions nest but must not interleave — starting two concurrently throws.
+
+The line is whether the failure still reaches the caller. A catch that **swallows** an
+engine error — one that does not rethrow — is what needs the boundary, and outside
+`ctx.atomic` `boundary-lint` rejects it with **no** escape hatch. A catch that always
+rethrows (`catch (e) { log(e); throw e }`) needs nothing, and neither does `try`/`finally`
+with no `catch`: the operation still fails and the whole transaction rolls back, which is
+already the outcome the rule protects. `ctx.atomic` is what you reach for when you intend
+to *continue* past the failure.
+
+"Always rethrows" is read literally — the catch's last statement is the `throw`. A `throw`
+buried in an `if` block is not that, because the catch runs on past it.
+
 ## Declare every link edge
 
 `entityRelations` in the manifest must declare every edge you traverse — both your own
@@ -189,6 +223,21 @@ vertical done, boot the server and drive the real flow over HTTP as two personas
 should succeed and one who should be denied — and confirm the denial arrives as a denial
 (not a generic error).
 
+## When it breaks — symptom → fix
+
+Six failures that have each cost someone a day. What makes them expensive is that none of
+them names its own cause: the symptom points somewhere other than the fix, so an agent
+debugging from first principles walks away from the answer.
+
+| Symptom | Fix |
+|---|---|
+| `expected a Zod schema` at runtime, pointing nowhere useful | Two copies of Zod. Never add `zod` to `package.json` — import `z` from `@substrat-run/contracts`, so the schema you build and the one the host validates with are the same class. |
+| Killing the dev server kills unrelated ones too | `pkill -f 'tsx src/server.ts'` matches every Substrat project running on the machine, not just yours. Kill by port instead: `kill $(lsof -ti :<port>)`. |
+| Green locally, red in CI, with nothing in the diff that explains it | A warm build output hides it. Delete `dist`, reinstall from the lockfile (`--frozen-lockfile`), and re-run the gates before believing a local green. |
+| Green test suite, broken app | The scenario calls operations directly and never reaches `server.ts`, its routes, or the principal picker. Boot the server and drive the flow over HTTP as two personas — one who should succeed and one who should be denied. |
+| Permission denied after you widened a role | Roles are projected into a scope when that scope is provisioned, from `ROLES` in `src/provision.ts`. An existing scope keeps the projection it was born with — re-provision it (or re-seed onto a fresh data directory), then present the permission diff below. |
+| `pnpm install` dies compiling `better-sqlite3` | Take `better-sqlite3` out of `pnpm.onlyBuiltDependencies`. Since 13.x it ships prebuilt binaries and no install script, but it still ships a `binding.gyp` — so an allowlist entry makes pnpm run a `node-gyp rebuild` that nothing here needs. |
+
 ## Two human checkpoints — you may never self-approve
 
 Present these and stop: