create-substrat 0.0.1 → 0.1.0

package/template/src/seed.ts

@@ -0,0 +1,265 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+  platformActorId,
+  principalId,
+  scopeId,
+  tenantId,
+  type PermissionKey,
+  type PrincipalId,
+  type RoleDefinition,
+  type ScopeId,
+  type TenantId,
+} from '@substrat-run/contracts';
+import { ulid } from '@substrat-run/kernel';
+import { SqliteScopeHost } from '@substrat-run/adapter-sqlite';
+import { workorderModule, PERM as WO } from '@substrat-run/engine-workorder';
+import { invoicingModule, INVOICING_PERM as INV } from '@substrat-run/engine-invoicing';
+import { bikeShopModule } from './module.js';
+import { SHOP_PERM } from './manifest.js';
+
+// ============================================================================
+// The seeded world. TWO tenants on purpose: the first is the shop the scenario
+// exercises; the second exists only so the scenario can watch the tenant
+// boundary turn its admin away when he reaches across (a cross-tenant attacker
+// is the cheapest possible proof that isolation is real).
+// ============================================================================
+
+export interface BikeShopWorld {
+  t1: TenantId; // the shop under test
+  s1: ScopeId; //   its workshop scope
+  t2: TenantId; // a second, unrelated shop
+  s2: ScopeId; //   its workshop scope
+  greta: PrincipalId; // workshop-admin @ t1
+  mans: PrincipalId; // mechanic @ t1
+  lisbeth: PrincipalId; // portal customer @ t1 (owns a bike)
+  otto: PrincipalId; // portal customer @ t1 (owns a different bike)
+  rutger: PrincipalId; // workshop-admin @ t2 — the cross-tenant attacker
+  lisbethId: string; // customer record ids (filled on first seed)
+  ottoId: string;
+  crescentId: string; // Lisbeth's bike
+  bianchiId: string; // Otto's bike
+}
+
+/**
+ * The modules this vertical composes, in registration order. Exported so the
+ * permission checkpoint (`pnpm lint:permissions`) renders from the same array
+ * the running host registers — the artifact can never drift from reality.
+ */
+export const MODULES = [workorderModule, invoicingModule, bikeShopModule];
+
+const adminPerms: PermissionKey[] = [
+  SHOP_PERM.customerManage,
+  SHOP_PERM.bikeManage,
+  WO.create,
+  WO.read,
+  WO.assign,
+  WO.report,
+  WO.complete,
+  WO.close,
+  INV.read,
+  INV.export,
+];
+
+/**
+ * This vertical's role table — identical in every tenant, so it is a plain
+ * constant the permission snapshot can render without naming a tenant. Exported
+ * for the same reason as MODULES.
+ */
+export const ROLES: RoleDefinition[] = [
+  { key: 'workshop-admin', permissions: adminPerms, source: 'vertical' },
+  { key: 'mechanic', permissions: [WO.read, WO.report], source: 'vertical' },
+];
+
+/** What a portal customer receives, narrowed to their own customer record. */
+const portalPerms: PermissionKey[] = [WO.read];
+
+/**
+ * Entity-narrowed grant SHAPES. The grants themselves are per-principal and
+ * minted at runtime, so they can never be a build artifact; their shape is what
+ * tells a reviewer which keys are reachable outside the role table.
+ */
+export const ENTITY_GRANTS: { entityType: string; permissions: PermissionKey[] }[] = [
+  { entityType: 'customer', permissions: portalPerms },
+];
+
+export function buildBikeShopHost(dir: string): SqliteScopeHost {
+  const host = new SqliteScopeHost({ dir });
+  for (const m of MODULES) host.registerModule(m);
+  return host;
+}
+
+/**
+ * Provision ONE tenant of this vertical: tenant, entitlements for every module
+ * it runs, an active scope, the role table, and the owner holding workshop-admin.
+ * This is what an instantiate button would call — no demo cast, no fixtures.
+ */
+async function provisionShop(
+  host: SqliteScopeHost,
+  input: { tenantId: TenantId; scopeId: ScopeId; owner: PrincipalId; slug: string; name: string },
+): Promise<void> {
+  const staff = platformActorId.parse(ulid());
+  await host.admin.createTenant(staff, { id: input.tenantId, slug: input.slug, name: input.name });
+  // Entitlements are default-deny: the SKU flag for each module this vertical
+  // runs must be granted before any of its operations resolve.
+  for (const key of ['workorder', 'invoicing', 'bikeshop']) {
+    await host.admin.grantEntitlement(staff, input.tenantId, key);
+  }
+  await host.provisionScope(staff, {
+    tenantId: input.tenantId,
+    scopeId: input.scopeId,
+    jurisdiction: 'global',
+  });
+  // Provisioning writes the scope as `provisioning`; nothing may use it until it
+  // is active (here the platform and the vertical are one process, so the
+  // confirmation is immediate).
+  await host.admin.activateScope(staff, input.tenantId, input.scopeId);
+  for (const role of ROLES) await host.admin.defineRole(staff, input.tenantId, role);
+  await host.admin.assignRole(staff, {
+    principalId: input.owner,
+    roleKey: 'workshop-admin',
+    node: { tenantId: input.tenantId, scopeId: null },
+  });
+}
+
+/**
+ * Idempotent seed. Everything that mutates the control plane runs only on a
+ * FRESH data dir (guarded by cast.json); on restart the tenants, roles, grants
+ * and entities are already in the SQLite files, so we just rebuild the handle
+ * object. Safe to call on every server start and on every test.
+ */
+export async function seedBikeShop(host: SqliteScopeHost, dir: string): Promise<BikeShopWorld> {
+  const castPath = join(dir, 'cast.json');
+  if (existsSync(castPath)) {
+    const raw = JSON.parse(readFileSync(castPath, 'utf8')) as Record<string, string>;
+    return {
+      t1: tenantId.parse(raw.t1),
+      s1: scopeId.parse(raw.s1),
+      t2: tenantId.parse(raw.t2),
+      s2: scopeId.parse(raw.s2),
+      greta: principalId.parse(raw.greta),
+      mans: principalId.parse(raw.mans),
+      lisbeth: principalId.parse(raw.lisbeth),
+      otto: principalId.parse(raw.otto),
+      rutger: principalId.parse(raw.rutger),
+      lisbethId: raw.lisbethId!,
+      ottoId: raw.ottoId!,
+      crescentId: raw.crescentId!,
+      bianchiId: raw.bianchiId!,
+    };
+  }
+
+  const staff = platformActorId.parse(ulid());
+  const world: BikeShopWorld = {
+    t1: tenantId.parse(ulid()),
+    s1: scopeId.parse(ulid()),
+    t2: tenantId.parse(ulid()),
+    s2: scopeId.parse(ulid()),
+    greta: principalId.parse(ulid()),
+    mans: principalId.parse(ulid()),
+    lisbeth: principalId.parse(ulid()),
+    otto: principalId.parse(ulid()),
+    rutger: principalId.parse(ulid()),
+    lisbethId: '',
+    ottoId: '',
+    crescentId: '',
+    bianchiId: '',
+  };
+
+  // The shop under test, and a second unrelated shop whose admin will attack it.
+  await provisionShop(host, {
+    tenantId: world.t1,
+    scopeId: world.s1,
+    owner: world.greta,
+    slug: 'kedja-kugghjul',
+    name: 'Kedja & Kugghjul Cykelverkstad',
+  });
+  await provisionShop(host, {
+    tenantId: world.t2,
+    scopeId: world.s2,
+    owner: world.rutger,
+    slug: 'trampolin',
+    name: 'Trampolin Cykel',
+  });
+
+  // The rest of t1's cast.
+  await host.admin.assignRole(staff, {
+    principalId: world.mans,
+    roleKey: 'mechanic',
+    node: { tenantId: world.t1, scopeId: world.s1 },
+  });
+
+  // Seed entities go through the operations (NEVER raw SQL): the seed exercises
+  // the same permission checks and event spine the app does.
+  const greta = await host.getScope(world.greta, world.t1, world.s1);
+  const lisbethCustomer = await greta.invoke<{ id: string }>('shop/create-customer', {
+    number: '2001',
+    name: 'Lisbeth Sandell',
+    phone: '070-123 45 67',
+  });
+  const ottoCustomer = await greta.invoke<{ id: string }>('shop/create-customer', {
+    number: '2002',
+    name: 'Otto Vinge',
+  });
+  const crescent = await greta.invoke<{ id: string }>('shop/register-bike', {
+    customerId: lisbethCustomer.id,
+    label: 'Crescent Elina 3-vxl',
+    frameNo: 'CR-88412',
+  });
+  const bianchi = await greta.invoke<{ id: string }>('shop/register-bike', {
+    customerId: ottoCustomer.id,
+    label: 'Bianchi Oltre XR3',
+  });
+  await greta.invoke('shop/upsert-price', {
+    article: 'labor',
+    description: 'Mechanic time',
+    unit: 'hour',
+    priceAmount: '495',
+    minQty: '0.5',
+  });
+  await greta.invoke('shop/upsert-price', {
+    article: 'shop-supplies',
+    description: 'Workshop supplies',
+    unit: 'ea',
+    priceAmount: '15',
+    internal: true,
+  });
+  await greta.invoke('shop/upsert-price', {
+    article: 'tube-28',
+    description: 'Inner tube 28"',
+    unit: 'ea',
+    priceAmount: '89',
+  });
+  await greta.invoke('shop/upsert-price', {
+    article: 'chain-9s',
+    description: 'Chain, 9-speed',
+    unit: 'ea',
+    priceAmount: '249',
+  });
+
+  world.lisbethId = lisbethCustomer.id;
+  world.ottoId = ottoCustomer.id;
+  world.crescentId = crescent.id;
+  world.bianchiId = bianchi.id;
+
+  // Portal grants: entity-narrowed per customer (ENTITY_GRANTS). Lisbeth and
+  // Otto each hold workorder:read on their OWN customer record only — the walk
+  // workorder → bike → customer does the rest.
+  for (const [principal, customerId] of [
+    [world.lisbeth, world.lisbethId],
+    [world.otto, world.ottoId],
+  ] as const) {
+    for (const permission of portalPerms) {
+      await host.admin.grant(staff, {
+        principalId: principal,
+        permission,
+        node: { tenantId: world.t1, scopeId: world.s1 },
+        entity: { entityType: 'customer', entityId: customerId },
+        grantedBy: world.greta,
+      });
+    }
+  }
+
+  writeFileSync(castPath, JSON.stringify(world, null, 2));
+  return world;
+}

package/template/src/server.ts

@@ -0,0 +1,145 @@
+import { mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { serve } from '@hono/node-server';
+import { Hono } from 'hono';
+import type { Context } from 'hono';
+import { PermissionDenied, type ScopeStub } from '@substrat-run/kernel';
+import type { PrincipalId } from '@substrat-run/contracts';
+import { buildBikeShopHost, seedBikeShop, type BikeShopWorld } from './seed.js';
+
+// ============================================================================
+// A deliberately THIN dev API. Each route authenticates (a dev principal picker
+// via the `x-principal` header — a real deployment swaps in a session), gets the
+// scope, and invokes ONE operation. There is no business logic here: every rule
+// lives in an operation or an engine.
+// ============================================================================
+
+const dataDir = join(dirname(fileURLToPath(import.meta.url)), '..', '.data');
+mkdirSync(dataDir, { recursive: true });
+
+const host = buildBikeShopHost(dataDir);
+const world: BikeShopWorld = await seedBikeShop(host, dataDir);
+
+// The dev cast, keyed by the `x-principal` header value. Every entry is a real
+// principal with real tuples — nothing here is a bypass.
+const CAST: Record<string, { name: string; principal: PrincipalId }> = {
+  greta: { name: 'Greta (workshop-admin)', principal: world.greta },
+  mans: { name: 'Måns (mechanic)', principal: world.mans },
+  lisbeth: { name: 'Lisbeth (portal customer)', principal: world.lisbeth },
+  otto: { name: 'Otto (portal customer)', principal: world.otto },
+  rutger: { name: 'Rutger (other shop — attacker)', principal: world.rutger },
+};
+
+function principalOf(c: Context): PrincipalId {
+  const who = c.req.header('x-principal') ?? 'greta';
+  const entry = CAST[who];
+  if (!entry) throw new PermissionDenied(`unknown principal: ${who}`);
+  return entry.principal;
+}
+
+function stub(c: Context): Promise<ScopeStub> {
+  return host.getScope(principalOf(c), world.t1, world.s1);
+}
+
+const app = new Hono();
+
+app.onError((err, c) => {
+  const message = err instanceof Error ? err.message : String(err);
+  if (err instanceof PermissionDenied) return c.json({ error: message }, 403);
+  if (/invalid transition|immutable|already/.test(message)) return c.json({ error: message }, 409);
+  if (/not found|unknown scope|unknown operation/.test(message)) return c.json({ error: message }, 404);
+  return c.json({ error: message }, 400);
+});
+
+app.get('/api/cast', (c) => c.json(CAST));
+
+// Customers, bikes, price list (the vertical's own tables).
+app.get('/api/customers', async (c) => c.json(await (await stub(c)).invoke('shop/list-customers')));
+app.post('/api/customers', async (c) =>
+  c.json(await (await stub(c)).invoke('shop/create-customer', await c.req.json())),
+);
+app.post('/api/customers/:id/bikes', async (c) =>
+  c.json(
+    await (await stub(c)).invoke('shop/register-bike', {
+      customerId: c.req.param('id'),
+      ...(await c.req.json<Record<string, unknown>>()),
+    }),
+  ),
+);
+app.get('/api/prices', async (c) => c.json(await (await stub(c)).invoke('shop/price-list')));
+app.post('/api/prices', async (c) =>
+  c.json(await (await stub(c)).invoke('shop/upsert-price', await c.req.json())),
+);
+
+// Repairs — the vertical's create/complete/close wrap the engine; assign/start/
+// report/get/list are the engine's own operations, invoked directly.
+app.get('/api/repairs', async (c) =>
+  c.json(await (await stub(c)).invoke('workorder/list', { status: c.req.query('status') })),
+);
+app.post('/api/repairs', async (c) =>
+  c.json(await (await stub(c)).invoke('shop/create-repair', await c.req.json())),
+);
+app.get('/api/repairs/:id', async (c) =>
+  c.json(await (await stub(c)).invoke('workorder/get', { orderId: c.req.param('id') })),
+);
+app.get('/api/repairs/:id/timeline', async (c) =>
+  c.json(
+    await (await stub(c)).invoke('shop/timeline', {
+      entityType: 'workorder',
+      entityId: c.req.param('id'),
+    }),
+  ),
+);
+app.post('/api/repairs/:id/assign', async (c) =>
+  c.json(
+    await (await stub(c)).invoke('workorder/assign', {
+      orderId: c.req.param('id'),
+      ...(await c.req.json<Record<string, unknown>>()),
+    }),
+  ),
+);
+app.post('/api/repairs/:id/start', async (c) =>
+  c.json(await (await stub(c)).invoke('workorder/start', { orderId: c.req.param('id') })),
+);
+app.post('/api/repairs/:id/time', async (c) =>
+  c.json(
+    await (await stub(c)).invoke('workorder/report-time', {
+      orderId: c.req.param('id'),
+      ...(await c.req.json<Record<string, unknown>>()),
+    }),
+  ),
+);
+app.post('/api/repairs/:id/material', async (c) =>
+  c.json(
+    await (await stub(c)).invoke('workorder/report-material', {
+      orderId: c.req.param('id'),
+      ...(await c.req.json<Record<string, unknown>>()),
+    }),
+  ),
+);
+app.post('/api/repairs/:id/complete', async (c) =>
+  c.json(await (await stub(c)).invoke('shop/complete-repair', { orderId: c.req.param('id') })),
+);
+app.post('/api/repairs/:id/close', async (c) =>
+  c.json(await (await stub(c)).invoke('shop/close-repair', { orderId: c.req.param('id') })),
+);
+
+// The customer portal — the per-entity proof walk.
+app.get('/api/portal/repairs', async (c) =>
+  c.json(await (await stub(c)).invoke('shop/portal-repairs')),
+);
+
+// Invoicing (the sibling engine, fed by event).
+app.get('/api/invoicing', async (c) => c.json(await (await stub(c)).invoke('invoicing/list')));
+app.get('/api/invoicing/:id', async (c) =>
+  c.json(await (await stub(c)).invoke('invoicing/get', { underlagId: c.req.param('id') })),
+);
+app.post('/api/invoicing/:id/export', async (c) =>
+  c.json(await (await stub(c)).invoke('invoicing/export', { underlagId: c.req.param('id') })),
+);
+
+const PORT = Number(process.env.PORT ?? 8873);
+serve({ fetch: app.fetch, port: PORT });
+console.log(`Bike-shop API on http://localhost:${PORT} — data in ${dataDir}`);
+console.log(`Pick a principal with the "x-principal" header: ${Object.keys(CAST).join(', ')}`);

package/template/test/scenario.test.ts

@@ -0,0 +1,249 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+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 type { ScopeStub } from '@substrat-run/kernel';
+import type { SqliteScopeHost } from '@substrat-run/adapter-sqlite';
+import type { WorkOrder, BillableLine } from '@substrat-run/engine-workorder';
+import { buildBikeShopHost, seedBikeShop, type BikeShopWorld } from '../src/seed.js';
+
+// ============================================================================
+// The bike-shop scenario, replayed headlessly against a temp dir: a repair's
+// full lifecycle (create → assign → start → report → priced completion) drives
+// the invoicing engine BY EVENT, then every door that should be shut is proven
+// shut — each denial pinned to its message and paired with a control that a
+// neighbouring door is open, so a green test can never be a silently-broken one.
+// ============================================================================
+
+describe('bike-shop scenario', () => {
+  let dir: string;
+  let host: SqliteScopeHost;
+  let w: BikeShopWorld;
+  let greta: ScopeStub;
+  let mans: ScopeStub;
+  let repairId: string;
+
+  beforeAll(async () => {
+    dir = mkdtempSync(join(tmpdir(), 'substrat-bikeshop-'));
+    host = buildBikeShopHost(dir);
+    w = await seedBikeShop(host, dir);
+    greta = await host.getScope(w.greta, w.t1, w.s1);
+    mans = await host.getScope(w.mans, w.t1, w.s1);
+  });
+
+  afterAll(async () => {
+    await host.close();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('1. provisions and applies all three module journals', () => {
+    const db = new Database(join(dir, `${w.t1}__${w.s1}.sqlite`), { readonly: true });
+    const rows = db
+      .prepare('SELECT DISTINCT module_id FROM _substrat_migrations ORDER BY module_id')
+      .all() as { module_id: string }[];
+    db.close();
+    expect(rows.map((r) => r.module_id)).toEqual([
+      '@substrat-run/engine-invoicing',
+      '@substrat-run/engine-workorder',
+      'bikeshop',
+    ]);
+  });
+
+  it("2. greta opens a repair for Lisbeth's Crescent", async () => {
+    const repair = await greta.invoke<WorkOrder>('shop/create-repair', {
+      bikeId: w.crescentId,
+      kind: 'puncture',
+      title: 'Rear puncture, gears skipping',
+    });
+    repairId = repair.id;
+    expect(repair.number).toBe(1);
+    expect(repair.status).toBe('planned');
+    expect(repair.facility).toEqual({ entityType: 'bike', entityId: w.crescentId });
+    expect(repair.customer.entityId).toBe(w.lisbethId);
+
+    const timeline = await greta.invoke<{ type: string }[]>('shop/timeline', {
+      entityType: 'workorder',
+      entityId: repairId,
+    });
+    expect(timeline.map((e) => e.type)).toContain('workorder.created');
+  });
+
+  it('3. assign → start → report time and parts', async () => {
+    await greta.invoke('workorder/assign', { orderId: repairId, technician: w.mans });
+    await mans.invoke('workorder/start', { orderId: repairId });
+    await mans.invoke('workorder/report-time', { orderId: repairId, hours: '0.25' });
+    await mans.invoke('workorder/report-material', { orderId: repairId, article: 'tube-28', qty: '1' });
+    await mans.invoke('workorder/report-material', {
+      orderId: repairId,
+      article: 'shop-supplies',
+      qty: '1',
+    });
+    const detail = await mans.invoke<{ order: WorkOrder; time: unknown[]; material: unknown[] }>(
+      'workorder/get',
+      { orderId: repairId },
+    );
+    expect(detail.order.status).toBe('in_progress');
+    expect(detail.time).toHaveLength(1);
+    expect(detail.material).toHaveLength(2);
+  });
+
+  it('4. every shut door is shut — pinned messages, each paired with an open one', async () => {
+    // A mechanic cannot assign…
+    await expect(
+      mans.invoke('workorder/assign', { orderId: repairId, technician: w.mans }),
+    ).rejects.toThrow(/permission denied/);
+    // …but the neighbouring door IS open: the same mechanic can report time.
+    await expect(
+      mans.invoke('workorder/report-time', { orderId: repairId, hours: '0.1' }),
+    ).resolves.toBeTruthy();
+
+    // A portal customer cannot report time…
+    const lisbeth = await host.getScope(w.lisbeth, w.t1, w.s1);
+    await expect(
+      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);
+
+    // The cross-tenant attacker: claiming t1's scope under his OWN tenant fails
+    // the (tenant, scope) pair check…
+    await expect(host.getScope(w.rutger, w.t2, w.s1)).rejects.toThrow(/unknown scope/);
+    // …the control: his own (t2, s2) pair resolves.
+    await expect(host.getScope(w.rutger, w.t2, w.s2)).resolves.toBeTruthy();
+    // With the correct pair he can mint a stub but holds no tuples in t1 — every
+    // privileged operation is denied by the owning scope's evaluation…
+    const rutger = await host.getScope(w.rutger, w.t1, w.s1);
+    await expect(rutger.invoke('workorder/list')).rejects.toThrow(/permission denied/);
+    await expect(rutger.invoke('shop/list-customers')).rejects.toThrow(/permission denied/);
+    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([]);
+  });
+
+  it('5. priced completion: the half-hour minimum bills, internal dropped, math exact', async () => {
+    const result = await greta.invoke<{ billable: BillableLine[]; total: { amount: string } }>(
+      'shop/complete-repair',
+      { orderId: repairId },
+    );
+
+    // Expected totals are computed with the SAME money helpers the operation
+    // uses — never hand-derived. 0.35h reported (0.25 + 0.1) < 0.5 min → the
+    // minimum bills; shop-supplies is internal and dropped.
+    const laborUnit = moneyOf('495', 'SEK');
+    const expectedLabor = mulMoney('0.5', laborUnit); // 0.5 × 495
+    const expectedTube = mulMoney('1', moneyOf('89', 'SEK'));
+    const expectedTotal = addMoney(expectedLabor, expectedTube);
+
+    expect(result.billable).toHaveLength(2);
+    const labor = result.billable.find((b) => b.article === 'labor')!;
+    expect(labor.qty).toBe('0.5');
+    expect(labor.lineTotal.amount).toBe(expectedLabor.amount);
+    const tube = result.billable.find((b) => b.article === 'tube-28')!;
+    expect(tube.lineTotal.amount).toBe(expectedTube.amount);
+    expect(result.total.amount).toBe(expectedTotal.amount);
+    expect(expectedTotal.amount).toBe('336.5'); // and the human-checkable number
+
+    // Completed is immutable: the engine refuses a further report.
+    await expect(
+      greta.invoke('workorder/report-time', { orderId: repairId, hours: '1' }),
+    ).rejects.toThrow(/invalid transition/);
+  });
+
+  it('6. star topology: the invoicing engine consumed workorder.completed', async () => {
+    const underlag = await greta.invoke<{ 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');
+
+    const detail = await greta.invoke<{ lines: { source_id: string; source_type: string }[] }>(
+      'invoicing/get',
+      { underlagId: underlag[0]!.id },
+    );
+    expect(detail.lines).toHaveLength(2);
+    expect(detail.lines.every((l) => l.source_type === 'workorder' && l.source_id === repairId)).toBe(
+      true,
+    );
+  });
+
+  it('7. portal isolation: Lisbeth sees her repair, Otto sees nothing', async () => {
+    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([]);
+
+    // Lisbeth reads her repair's timeline via the same entity walk…
+    await expect(
+      lisbeth.invoke<{ type: string }[]>('shop/timeline', {
+        entityType: 'workorder',
+        entityId: repairId,
+      }),
+    ).resolves.toBeTruthy();
+    // …but invoicing is not a portal concern: denied.
+    await expect(lisbeth.invoke('invoicing/list')).rejects.toThrow(/permission denied/);
+  });
+
+  it('8. export makes the underlag immutable; the next completion opens a new one', async () => {
+    const [underlag] = await greta.invoke<{ id: string }[]>('invoicing/list');
+    await greta.invoke('invoicing/export', { underlagId: underlag!.id });
+    await expect(greta.invoke('invoicing/export', { underlagId: underlag!.id })).rejects.toThrow(
+      /immutable/,
+    );
+
+    const repair2 = await greta.invoke<WorkOrder>('shop/create-repair', {
+      bikeId: w.crescentId,
+      kind: 'service',
+      title: 'Annual service, new chain',
+    });
+    await greta.invoke('workorder/start', { orderId: repair2.id });
+    await greta.invoke('workorder/report-time', { orderId: repair2.id, hours: '1' });
+    await greta.invoke('workorder/report-material', {
+      orderId: repair2.id,
+      article: 'chain-9s',
+      qty: '1',
+    });
+    await greta.invoke('shop/complete-repair', { orderId: repair2.id });
+
+    const all = await greta.invoke<{ 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);
+    // 1h ≥ 0.5 min → 1 × 495 + chain 249 = 744.
+    const expectedTotal = addMoney(mulMoney('1', moneyOf('495', 'SEK')), mulMoney('1', moneyOf('249', 'SEK')));
+    expect(all.find((u) => u.status === 'open')!.total).toBe(expectedTotal.amount);
+    expect(expectedTotal.amount).toBe('744');
+  });
+
+  it('9. the engine state machine cannot be skipped', async () => {
+    const repair = await greta.invoke<WorkOrder>('shop/create-repair', {
+      bikeId: w.bianchiId,
+      kind: 'service',
+      title: 'Brake adjustment',
+    });
+    // planned → completed is not a legal step (needs in_progress)…
+    await expect(greta.invoke('shop/complete-repair', { orderId: repair.id })).rejects.toThrow(
+      /invalid transition/,
+    );
+    // …nor planned → closed (needs completed).
+    await expect(greta.invoke('shop/close-repair', { orderId: repair.id })).rejects.toThrow(
+      /invalid transition/,
+    );
+
+    // The control: walked one legal step at a time, the same doors open.
+    await greta.invoke('workorder/start', { orderId: repair.id });
+    await greta.invoke('workorder/report-time', { orderId: repair.id, hours: '0.5' });
+    await greta.invoke('shop/complete-repair', { orderId: repair.id });
+    const closed = await greta.invoke<WorkOrder>('shop/close-repair', { orderId: repair.id });
+    expect(closed.status).toBe('closed');
+    // And once closed, the machine refuses to close again.
+    await expect(greta.invoke('shop/close-repair', { orderId: repair.id })).rejects.toThrow(
+      /invalid transition/,
+    );
+  });
+});