create-substrat 0.7.3 → 0.8.1

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.86.0';
-const ENGINE_WORKORDER = '^0.8.2';
-const ENGINE_INVOICING = '^0.9.2';
-const BOUNDARY_LINT = '^0.1.2';
-const DEV_ISSUER = '^0.1.0';
+const SUBSTRAT = '^0.91.1';
+const ENGINE_WORKORDER = '^0.9.2';
+const ENGINE_INVOICING = '^0.9.7';
+const BOUNDARY_LINT = '^0.2.0';
+const DEV_ISSUER = '^0.1.5';
 
 const DOCS = 'https://substrat.net';
 

package/package.json

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

package/template/.substrat/playbook.md

@@ -71,7 +71,13 @@ Every vertical gets this whether or not it uses a single engine:
 - **Tenancy** — tenants and scopes, isolated at the database level. A scope is one
   SQLite/DO database. Cross-tenant access is not a bug you avoid; there is no API for it.
 - **Permissions** — roles, grants, entity-narrowed grants, and every decision carries a
-  proof path (why it was allowed).
+  proof path (why it was allowed). **Sharing is a kernel verb, not a table you design**:
+  an operation narrows a permission it already holds onto one entity, and withdraws it,
+  with `ctx.grant(principal, perm, entityRef)` / `ctx.revoke(principal, perm, entityRef)`
+  — entity-required, delegating (re-checks the caller's own decision), transactional with
+  the operation. Neither alternative is this: a `ctx.link` edge is permanent (not
+  revocable at all), and org membership is revocable but coarse-grained. Never mint an
+  org per domain row to get a revoke.
 - **Events + audit** — every mutation emits a kernel-stamped event. Origin fields (tenant,
   scope, actor, time) are stamped by the kernel; your code cannot mislabel one.
 - **Migrations** — journaled per module, applied lazily per scope.
@@ -363,6 +369,21 @@ operations + the `ModuleRegistration`. Keep the split — the linter and tests e
   `completeWorkOrder`. One transaction, invariants intact.
 - 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`** —
+  not a `SELECT` against `_substrat_outbox`. Reading the spine is allowed (writes to
+  `_substrat_*` are not); hand-writing the query is what goes wrong. It returns
+  `{ entries, nextCursor }` with `{ id, type, occurredAt, actor }` per entry, and it exists
+  to close two traps: `actor` is stored as JSON over a union — a principal is `"01J…"`
+  *with quotes*, so a raw `SELECT actor` is a string that resolves against no one — and
+  the cursor must be the event `id`, never `occurred_at`, which is identical across every
+  event a single operation emits. Your permission check stays your line, above the call.
+  `readHistory` is the same walk plus the payload, the permissions that authorized the
+  write — each with the grant it resolved through, `null` for a row written before that
+  was recorded, which is not the same fact as `[]` — and the PII classification,
+  `piiClass` with the `subjectId` it is keyed by, so a renderer can decide whether an
+  entry is safe to show before it shows it. `subjectId` is null when `piiClass` is
+  `none`, and the payload is `null` after that subject's erasure, which is a supported
+  answer to render rather than an error.
 
 ### `src/seed.ts`
 
@@ -377,7 +398,10 @@ await host.provisionScope(actor, { tenantId: tenant, scopeId: scope, jurisdictio
 
 Define roles **per tenant** from the engines' `PERM` + your keys, assign them, create seed
 entities via `stub.invoke` (**never raw SQL**), give portal principals entity-narrowed
-grants. Make it idempotent.
+grants. Make it idempotent. Seed-time grants are the platform actor's verb; sharing a
+**user** initiates at runtime is `ctx.grant` / `ctx.revoke` inside an operation (see the
+`AGENTS.md` section on sharing, and the [todo demo](https://github.com/substrat-run/substrat/tree/main/demos/todo)'s
+`src/module.ts` for the two calls in place).
 
 ### `test/scenario.test.ts`
 

package/template/AGENTS.md

@@ -142,6 +142,28 @@ consumers). Rules 1–5 are enforced mechanically by `boundary-lint`.
 adapter **rejects** a `ctx.link` for an undeclared edge, so a missing one fails loudly.
 This is also what lets a portal permission-walk reach the owner.
 
+## Sharing is `ctx.grant` / `ctx.revoke`, not a table
+
+When a person shares their own record with another person — and takes them off it again —
+the operation narrows a permission it already holds onto that one entity:
+
+```ts
+await ctx.grant(principal, PERM.listContribute, listRef(listId));   // share
+await ctx.revoke(principal, PERM.listContribute, listRef(listId));  // un-share
+```
+
+Entity-required (module code can never write a scope- or tenant-wide grant), delegating
+(the caller's own decision on that entity is re-checked, so an operation can never hand out
+more than it holds), and transactional with the operation. Every later `ctx.check` reads
+the grant, so nothing else has to remember who may touch what.
+
+Neither alternative is this, so you can tell a real absence from this one: a `ctx.link`
+edge is **not revocable at all** — it is permanent — and org membership is revocable but
+coarse-grained — a whole org, not one record. Never mint an org per domain row, or a
+membership table consulted by hand in every handler, to get a revoke. The two-line
+reference is the [todo demo](https://github.com/substrat-run/substrat/tree/main/demos/todo)
+(`src/module.ts`, `todo/share-list` and `todo/revoke-share`).
+
 ## The gates — run them, believe them
 
 ```sh

package/template/src/routes.ts

@@ -1,5 +1,5 @@
 import type { Context, Hono } from 'hono';
-import { classifyError } from '@substrat-run/vertical-host';
+import { problemResponse } from '@substrat-run/vertical-host';
 import type { ScopeStub } from '@substrat-run/kernel';
 
 /**
@@ -28,21 +28,24 @@ export function mountApi(app: Hono<any, any, any>, resolveStub: ResolveStub): vo
   const body = (c: Context) => c.req.json<Record<string, unknown>>();
 
   /**
-   * One error vocabulary, shared with the platform surface: `classifyError`
-   * (@substrat-run/vertical-host) is the same function `mountPlatformSurface` uses, so a
-   * permission denial is 403, a missing thing 404, a broken invariant 409, a runtime
-   * fault 502 — identically on both hosts. "No opinion" becomes the caller's 400.
+   * One error vocabulary, shared with the platform surface: `problemResponse`
+   * (@substrat-run/vertical-host) is built on the same `classifyError` that
+   * `mountPlatformSurface` uses, so a permission denial is 403, a missing thing 404, a
+   * broken invariant 409, a runtime fault 502 — identically on both hosts. "No opinion"
+   * becomes the caller's 400.
+   *
+   * The body is RFC 9457 `application/problem+json`: a `code` from the closed taxonomy
+   * when your throw declared one (`substratError('conflict', …)`), `about:blank` when it
+   * did not. `{ error }` rides along for one deprecation window, so a client reading it
+   * keeps working while you move to `code`.
    *
    * In `worker.ts` this handler is REPLACED: Hono keeps only the last-registered
    * `onError`, and `mountPlatformSurface` installs its own. That is harmless precisely
-   * because both are built on `classifyError` — same input, same answer. Registering it
-   * here is what gives `server.ts`, which mounts no platform surface, the same behaviour.
+   * because both are built on the same vocabulary — same input, same answer. Registering
+   * it here is what gives `server.ts`, which mounts no platform surface, the same
+   * behaviour.
    */
-  app.onError((err, c) => {
-    const seen = classifyError(err);
-    if (seen) return c.json({ error: seen.message }, seen.status);
-    return c.json({ error: err instanceof Error ? err.message : String(err) }, 400);
-  });
+  app.onError((err, c) => problemResponse(c, err));
 
   // -- generic invoke ---------------------------------------------------------
   // The kernel checks a permission inside EVERY operation, so a generic route is