create-substrat 0.8.3 → 0.8.5

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.94.0';
-const ENGINE_WORKORDER = '^0.10.2';
-const ENGINE_INVOICING = '^0.9.10';
-const BOUNDARY_LINT = '^0.2.1';
-const DEV_ISSUER = '^0.1.8';
+const SUBSTRAT = '^0.97.0';
+const ENGINE_WORKORDER = '^0.10.5';
+const ENGINE_INVOICING = '^0.9.13';
+const BOUNDARY_LINT = '^0.3.0';
+const DEV_ISSUER = '^0.1.12';
 
 const DOCS = 'https://substrat.net';
 

package/package.json

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

@@ -108,7 +108,14 @@ consumers). Rules 1–5 are enforced mechanically by `boundary-lint`.
    handler that runs outside the transaction. An integration is never impossible because
    of this rule — it has an answer.
 3. **Never write `_substrat_*` tables.** Reads are fine (timelines are projections);
-   writes forge the audit spine.
+   writes forge the audit spine. Do the read with `readTimeline` / `readHistory` from
+   `@substrat-run/kernel` rather than a `SELECT` of your own: both take an `EntityRef`,
+   page like a list read, and decode the envelope for you. `readHistory` also returns the
+   payload, the authorization chain (which checks the operation passed, and under which
+   grant), the impersonation stamp and the PII class. On the first three, a `null` is a
+   *fact* rather than data you failed to fetch — the payload was erased, the row predates
+   authorization recording, nobody was impersonating — so render it as that. Neither
+   helper checks a permission; you do, before you call it.
 4. **Another module's tables are private.** Never `SELECT` from `workorder_*` etc. — use
    the engine's exported in-scope functions. This is the rule with no runtime equivalent:
    the shortcut *works* and silently welds you to an engine's private schema forever. Need
@@ -129,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