create-substrat 0.0.0 → 0.1.0

package/template/AGENTS.md

@@ -0,0 +1,116 @@
+# Building on Substrat — agent instructions
+
+This project is a **Substrat vertical**: a multi-tenant business app built on the
+Substrat kernel and its engines. This file is the always-on constitution — the rules
+that hold no matter what you touch. It is read by every AI tool (Claude Code, Cursor,
+opencode); do not duplicate it into tool-specific config.
+
+The full build flow — interview, coverage map, scaffold, run, checkpoints — is a
+**playbook**, not always-on context. Invoke it when you start or extend a vertical:
+
+- **Claude Code**: `/substrat`
+- **Cursor / opencode**: the `new-vertical` command, or read [`.substrat/playbook.md`](.substrat/playbook.md)
+
+Read the playbook before scaffolding. This file is what a session already mid-build
+must never violate.
+
+## The mental model
+
+Three layers. You only own the third.
+
+1. **Kernel — free, always.** Tenancy (one scope = one isolated database; there is no
+   cross-tenant API), permissions (roles, grants, and a proof path for every decision),
+   events + audit (every mutation emits a kernel-stamped event you cannot mislabel),
+   migrations (journaled per module, applied lazily per scope).
+2. **Engines — compose or feed.** Headless, own invariants that cannot be violated
+   (state machines that can't skip states, append-only entries). You either **compose**
+   an engine (import it; its in-scope functions run in *your* transaction) or **feed** it
+   (emit a fat event; it consumes — no import). Engines never import each other. Read an
+   engine's real surface from `node_modules/@substrat-run/engine-*/dist/index.d.ts` —
+   never guess at it.
+3. **Your vertical — everything a user touches.** Vocabulary, price list, extra fields,
+   roles, screens. If your core noun isn't something an engine already owns, this is most
+   of the app — a normal, supported outcome.
+
+## Project layout
+
+The linter and tests expect this shape. `manifest`/`migrations`/`module` are **module
+code** (the rules below bind them); `seed`/`server` are **harness** (exempt).
+
+```
+src/manifest.ts        moduleManifest.parse({…}) + PERM consts   ← module code
+src/migrations.ts      the SqlMigration[]                         ← module code
+src/module.ts          imports both; operations + registration    ← module code
+src/seed.ts            host, tenants, roles, grants, seed world    ← harness
+src/server.ts          thin wrapper, one route per operation       ← harness
+test/scenario.test.ts  the scenario — including the denials
+```
+
+## 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.
+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
+   of this rule — it has an answer.
+3. **Never write `_substrat_*` tables.** Reads are fine (timelines are projections);
+   writes forge the audit spine.
+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
+   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))`
+   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
+   line wrong — that's design feedback, not a coding problem.
+8. **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
+    `@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.
+
+## Declare every link edge
+
+`entityRelations` in the manifest must declare every edge you traverse — both your own
+(`bike → customer`) and the ones an engine makes on your behalf (`workorder → bike`). The
+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.
+
+## The gates — run them, believe them
+
+```sh
+npm test                        # the scenario, including the denials
+npx @substrat-run/boundary-lint # the layer rules (1–4)
+npm run typecheck
+```
+
+`boundary-lint` exits non-zero if it *couldn't do its job* (no module code found, no
+engines resolvable) — a pass that checked nothing is worse than no linter. Never wave that
+through; fix the setup until it can see your code.
+
+A green scenario test does **not** mean the app works: the test calls operations directly
+and never exercises `server.ts`, its routes, or the principal picker. Before calling a
+vertical done, boot the server and drive the real flow over HTTP as two personas — one who
+should succeed and one who should be denied — and confirm the denial arrives as a denial
+(not a generic error).
+
+## Two human checkpoints — you may never self-approve
+
+Present these and stop:
+
+1. **Migration diff** — every new `SqlMigration`, verbatim. Migrations are append-only
+   forever once shipped, so this is the last cheap moment to change your mind.
+2. **Permission diff** — a table: key → description → which roles hold it → why. Walk the
+   reviewer through it in their own vocabulary until they can answer *who can now see the
+   money, and who can see other tenants' data?* A permission diff nobody understands is
+   theater — it reproduces the exact failure Substrat exists to prevent.

package/template/CLAUDE.md

@@ -0,0 +1,8 @@
+@AGENTS.md
+
+<!--
+Claude Code reads CLAUDE.md, not AGENTS.md. This one-line @-import pulls the shared
+constitution in verbatim, so there is a single source of truth every tool reads.
+Add Claude-only notes below this line if you ever need them; keep the shared rules in
+AGENTS.md so Cursor and opencode see them too.
+-->

package/template/src/manifest.ts

@@ -0,0 +1,48 @@
+import { moduleManifest, permissionKey } from '@substrat-run/contracts';
+
+// ============================================================================
+// The vertical's MANIFEST — the reviewable contract the kernel reads at
+// registration. A minimal bike-repair shop composed onto two engines:
+//
+//   engine-workorder  — the repair's state machine and append-only lines
+//   engine-invoicing  — turns a completed repair into an invoice basis, by EVENT
+//
+// This vertical owns only vocabulary (customers, bikes, a price list) and the
+// PRICING MOMENT. Every invariant that matters — a repair can't skip states,
+// a completed repair is immutable, every mutation emits an event — lives in the
+// engine. Read CLAUDE.md / AGENTS.md before you touch it.
+// ============================================================================
+
+/** The vertical's own permission keys (the engines declare their own). */
+export const SHOP_PERM = {
+  customerManage: permissionKey.parse('customer:manage'),
+  bikeManage: permissionKey.parse('bike:manage'),
+};
+
+export const bikeShopManifest = moduleManifest.parse({
+  id: 'bikeshop',
+  version: '0.0.1',
+  kernelContract: '^0.0.1',
+  permissions: [
+    { key: 'customer:manage', description: 'Manage customers and the workshop price list' },
+    { key: 'bike:manage', description: "Register and manage customers' bikes" },
+  ],
+  // The vertical emits and consumes no events of its own: the invoicing engine
+  // consumes the WORKORDER engine's `workorder.completed` directly (star
+  // topology — engines cooperate by event, never by import).
+  events: { emits: [], consumes: [] },
+  migrations: { journalDir: './migrations', compatibleFrom: '0.0.1' },
+  attachmentTargets: [
+    { entityType: 'customer', readPermission: 'customer:manage' },
+    { entityType: 'bike', readPermission: 'bike:manage' },
+  ],
+  // The portal permission walk is workorder → bike → customer. The engine links
+  // workorder → <facility ref>; in this vertical that facility ref IS a bike, so
+  // the vertical declares BOTH of its own edges. An entity-narrowed
+  // `workorder:read` grant on a customer then resolves all the way up.
+  entityRelations: [
+    { entityType: 'bike', parentType: 'customer' },
+    { entityType: 'workorder', parentType: 'bike' },
+  ],
+  entitlementKey: 'bikeshop',
+});

package/template/src/migrations.ts

@@ -0,0 +1,39 @@
+import type { SqlMigration } from '@substrat-run/kernel';
+
+// ============================================================================
+// The vertical's OWN tables, prefixed `shop_` so they can never collide with an
+// engine's. Ids are TEXT (ULIDs), timestamps ISO-8601 TEXT, money/decimals TEXT
+// — never a float, never a native DATE. Migrations are append-only and ordered:
+// once a version has shipped, you add a new one, you never edit it.
+// ============================================================================
+
+export const bikeShopMigrations: SqlMigration[] = [
+  {
+    version: '0001-init',
+    sql: `
+      CREATE TABLE shop_customers (
+        id          TEXT PRIMARY KEY,
+        number      TEXT NOT NULL UNIQUE,
+        name        TEXT NOT NULL,
+        phone       TEXT,
+        created_at  TEXT NOT NULL
+      );
+      CREATE TABLE shop_bikes (
+        id          TEXT PRIMARY KEY,
+        customer_id TEXT NOT NULL REFERENCES shop_customers(id),
+        label       TEXT NOT NULL,
+        frame_no    TEXT,
+        created_at  TEXT NOT NULL
+      );
+      CREATE TABLE shop_price_list (
+        article      TEXT PRIMARY KEY,
+        description  TEXT NOT NULL,
+        unit         TEXT NOT NULL,
+        price_amount TEXT NOT NULL,
+        currency     TEXT NOT NULL DEFAULT 'SEK',
+        min_qty      TEXT,
+        internal     INTEGER NOT NULL DEFAULT 0
+      );
+    `,
+  },
+];

package/template/src/module.ts

@@ -0,0 +1,297 @@
+import {
+  addDecimal,
+  compareDecimal,
+  moneyOf,
+  mulMoney,
+  z,
+  type EntityRef,
+  type Money,
+} from '@substrat-run/contracts';
+import {
+  assertAllowed,
+  ulid,
+  type ModuleRegistration,
+  type OperationHandler,
+} from '@substrat-run/kernel';
+import {
+  closeWorkOrder,
+  completeWorkOrder,
+  createWorkOrder,
+  getReportedLines,
+  listOrders,
+  PERM as WO,
+  type BillableLine,
+  type WorkOrder,
+} from '@substrat-run/engine-workorder';
+import { bikeShopManifest, SHOP_PERM } from './manifest.js';
+import { bikeShopMigrations } from './migrations.js';
+
+// ============================================================================
+// The bike-shop operations. Each is either:
+//   - a thin custodian of the vertical's own tables (customers, bikes, prices),
+//     OR
+//   - a COMPOSITION that wraps an engine's in-scope function inside the same
+//     transaction and adds the vertical's policy (the pricing moment).
+//
+// Every operation's FIRST line is the permission check. Data access is
+// `ctx.sql` only. No `fetch`, no `node:*`, no other engine's tables.
+// ============================================================================
+
+export interface CustomerRow {
+  id: string;
+  number: string;
+  name: string;
+  phone: string | null;
+  created_at: string;
+}
+
+export interface BikeRow {
+  id: string;
+  customer_id: string;
+  label: string;
+  frame_no: string | null;
+  created_at: string;
+}
+
+export interface PriceRow {
+  article: string;
+  description: string;
+  unit: string;
+  price_amount: string;
+  currency: string;
+  min_qty: string | null;
+  internal: number;
+}
+
+const createCustomerOp: OperationHandler<
+  { number: string; name: string; phone?: string },
+  CustomerRow
+> = async (ctx, input) => {
+  assertAllowed(await ctx.check(SHOP_PERM.customerManage));
+  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()],
+  );
+  return ctx.sql.query<CustomerRow>('SELECT * FROM shop_customers WHERE id = ?', [id])[0]!;
+};
+
+const listCustomersOp: OperationHandler<undefined, (CustomerRow & { bikes: BikeRow[] })[]> = async (
+  ctx,
+) => {
+  assertAllowed(await ctx.check(SHOP_PERM.customerManage));
+  const customers = ctx.sql.query<CustomerRow>('SELECT * FROM shop_customers ORDER BY number');
+  return customers.map((c) => ({
+    ...c,
+    bikes: ctx.sql.query<BikeRow>('SELECT * FROM shop_bikes WHERE customer_id = ? ORDER BY label', [
+      c.id,
+    ]),
+  }));
+};
+
+const registerBikeOp: OperationHandler<
+  { customerId: string; label: string; frameNo?: string },
+  BikeRow
+> = async (ctx, input) => {
+  assertAllowed(await ctx.check(SHOP_PERM.bikeManage));
+  const customer = ctx.sql.query<CustomerRow>('SELECT * FROM shop_customers WHERE id = ?', [
+    input.customerId,
+  ])[0];
+  if (!customer) throw new Error(`customer not found: ${input.customerId}`);
+  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()],
+  );
+  // Record the bike → customer edge the manifest declared, so the portal walk
+  // (workorder → bike → customer) can resolve an entity-narrowed grant.
+  ctx.link({ entityType: 'bike', entityId: id }, { entityType: 'customer', entityId: customer.id });
+  return ctx.sql.query<BikeRow>('SELECT * FROM shop_bikes WHERE id = ?', [id])[0]!;
+};
+
+const upsertPriceOp: OperationHandler<
+  {
+    article: string;
+    description: string;
+    unit: string;
+    priceAmount: string;
+    currency?: string;
+    minQty?: string;
+    internal?: boolean;
+  },
+  PriceRow
+> = async (ctx, input) => {
+  assertAllowed(await ctx.check(SHOP_PERM.customerManage));
+  ctx.sql.exec(
+    `INSERT OR REPLACE INTO shop_price_list
+       (article, description, unit, price_amount, currency, min_qty, internal)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`,
+    [
+      input.article,
+      input.description,
+      input.unit,
+      input.priceAmount,
+      input.currency ?? 'SEK',
+      input.minQty ?? null,
+      input.internal ? 1 : 0,
+    ],
+  );
+  return ctx.sql.query<PriceRow>('SELECT * FROM shop_price_list WHERE article = ?', [
+    input.article,
+  ])[0]!;
+};
+
+const priceListOp: OperationHandler<undefined, PriceRow[]> = async (ctx) => {
+  assertAllowed(await ctx.check(SHOP_PERM.customerManage));
+  return ctx.sql.query<PriceRow>('SELECT * FROM shop_price_list ORDER BY article');
+};
+
+/**
+ * Open a repair: a vertical operation that composes the engine's `createWorkOrder`.
+ * The vertical resolves its own vocabulary (a bike, its owner) into the engine's
+ * `facility`/`customer` refs; the engine owns the number, the state, the event.
+ */
+const createRepairOp: OperationHandler<
+  { bikeId: string; kind: string; title: string; description?: string },
+  WorkOrder
+> = async (ctx, input) => {
+  assertAllowed(await ctx.check(WO.create));
+  const bike = ctx.sql.query<BikeRow>('SELECT * FROM shop_bikes WHERE id = ?', [input.bikeId])[0];
+  if (!bike) throw new Error(`bike not found: ${input.bikeId}`);
+  return createWorkOrder(ctx, {
+    facility: { entityType: 'bike', entityId: bike.id },
+    customer: { entityType: 'customer', entityId: bike.customer_id },
+    kind: input.kind,
+    title: input.title,
+    ...(input.description !== undefined ? { description: input.description } : {}),
+  });
+};
+
+/**
+ * THE PRICING MOMENT — the whole reason a vertical exists. Read the engine's
+ * reported time and material, price them against the vertical's OWN price list
+ * (labor bills at least its minimum quantity; internal articles are dropped),
+ * then hand the priced lines back to the engine's `completeWorkOrder`. One
+ * transaction: the engine's invariant stays intact and pricing is 100% vertical.
+ * The engine's `workorder.completed` event carries these lines, and the
+ * invoicing engine consumes it — no import between the two.
+ */
+const completeRepairOp: OperationHandler<
+  { orderId: string },
+  { order: WorkOrder; billable: BillableLine[]; total: Money }
+> = async (ctx, input) => {
+  assertAllowed(await ctx.check(WO.complete));
+  const reported = getReportedLines(ctx, input.orderId);
+  const prices = new Map<string, PriceRow>(
+    ctx.sql.query<PriceRow>('SELECT * FROM shop_price_list').map((p) => [p.article, p]),
+  );
+
+  const billable: BillableLine[] = [];
+
+  // Labor: sum reported hours, then bill at least the minimum quantity.
+  const laborPrice = prices.get('labor');
+  const reportedHours = reported.time.reduce((sum, t) => addDecimal(sum, t.hours), '0');
+  if (laborPrice && compareDecimal(reportedHours, '0') > 0) {
+    const minQty = laborPrice.min_qty ?? '0';
+    const qty = compareDecimal(reportedHours, minQty) >= 0 ? reportedHours : minQty;
+    const unitPrice = moneyOf(laborPrice.price_amount, laborPrice.currency);
+    billable.push({
+      article: 'labor',
+      description: laborPrice.description,
+      qty,
+      unit: laborPrice.unit,
+      unitPrice,
+      lineTotal: mulMoney(qty, unitPrice),
+      sourceType: 'time',
+      sourceId: input.orderId,
+    });
+  }
+
+  // Parts: one billable line per reported material; internal articles dropped.
+  for (const m of reported.material) {
+    const price = prices.get(m.article);
+    if (!price) throw new Error(`no price for article: ${m.article}`);
+    if (price.internal) continue;
+    const unitPrice = moneyOf(price.price_amount, price.currency);
+    billable.push({
+      article: m.article,
+      description: price.description,
+      qty: m.qty,
+      unit: price.unit,
+      unitPrice,
+      lineTotal: mulMoney(m.qty, unitPrice),
+      sourceType: 'material',
+      sourceId: m.id,
+    });
+  }
+
+  const result = completeWorkOrder(ctx, { orderId: input.orderId, billable });
+  return { order: result.order, billable, total: result.total };
+};
+
+/**
+ * Pickup: hand the bike back (completed → closed). A thin composition of the
+ * engine's in-scope `closeWorkOrder`; the vertical owns the vocabulary
+ * ("pickup"), the engine owns the transition.
+ */
+const closeRepairOp: OperationHandler<{ orderId: string }, WorkOrder> = async (ctx, input) => {
+  assertAllowed(await ctx.check(WO.close));
+  return closeWorkOrder(ctx, { orderId: input.orderId });
+};
+
+/**
+ * The customer PORTAL listing. A proof walk: no blanket `workorder:read`, one
+ * 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.
+ */
+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 timelineInput = z.object({
+  entityType: z.string().min(1),
+  entityId: z.string().min(1),
+});
+
+/**
+ * An entity's event timeline, read straight off the spine (a read of `_substrat_*`
+ * for a projection is allowed; writing it is not). Gated by a per-entity
+ * `workorder:read` check, so it obeys the same walk as the portal.
+ */
+const timelineOp: OperationHandler<
+  z.infer<typeof timelineInput>,
+  { type: string; occurred_at: string; actor: string }[]
+> = async (ctx, rawInput) => {
+  const entity: EntityRef = timelineInput.parse(rawInput);
+  assertAllowed(await ctx.check(WO.read, entity));
+  // Append order is authoritative — rowid, not ULID (ids minted in the same
+  // millisecond are not mutually ordered).
+  return ctx.sql.query(
+    `SELECT type, occurred_at, actor FROM _substrat_outbox
+     WHERE entity_type = ? AND entity_id = ? ORDER BY rowid`,
+    [entity.entityType, entity.entityId],
+  );
+};
+
+export const bikeShopModule: ModuleRegistration = {
+  manifest: bikeShopManifest,
+  migrations: bikeShopMigrations,
+  operations: {
+    'shop/create-customer': createCustomerOp as never,
+    'shop/list-customers': listCustomersOp as never,
+    'shop/register-bike': registerBikeOp as never,
+    'shop/upsert-price': upsertPriceOp as never,
+    'shop/price-list': priceListOp as never,
+    'shop/create-repair': createRepairOp as never,
+    'shop/complete-repair': completeRepairOp as never,
+    'shop/close-repair': closeRepairOp as never,
+    'shop/portal-repairs': portalRepairsOp as never,
+    'shop/timeline': timelineOp as never,
+  },
+};