cursedbelt 0.0.0 → 2.3.0

package/src/server/runtime/recipe.spec.ts

@@ -0,0 +1,1478 @@
+/**
+ * The runtime recipe (02 §2), over real SQLite.
+ *
+ * This proves the keystone's structural claims behaviorally, not by inspection:
+ *   * `bootEngineApp` composes a manifest into an app that actually serves and
+ *     actually round-trips a write through a real repository (like
+ *     `runtime.spec.ts`, but through the ONE wiring function a generated app
+ *     calls rather than a hand-wired harness).
+ *   * The search provider is dual-wired: a write through the composed app fills
+ *     the SAME index a second reader opens over the same handle — the
+ *     highest-risk footgun of the refactor, closed structurally.
+ *   * `assertJobKindsHandled` refuses a manifest whose surface can enqueue a
+ *     kind with no handler (audit G8), and the built map has no gaps.
+ *   * `buildDrivers` fails the boot for an AI-effective manifest with no driver
+ *     (mirror of `assertArgon2idReady`), rather than 503-ing at first request.
+ */
+import { Database } from 'bun:sqlite';
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { assertCcPragmas, getTxnLifetimeGuard, runNamespacedMigrations } from 'cwip/sqlite';
+import { createSqliteSearchProvider } from 'cwip/search-provider';
+import { createFsObjectStore, type ObjectStore } from 'cwip/storage';
+import type { TelemetryWriter } from 'cwip/telemetry';
+import {
+  type Argon2idDeriver,
+  createRowSigner,
+  createSecretEnvelopeManager,
+  mintEnvelopeSalt,
+  mintMachineIntegrityKey,
+  SecureKey,
+  setArgon2idDeriver,
+} from 'cwip/guard';
+import {
+  CC_REGISTRY_MIGRATIONS,
+  claimPort,
+  createRegistryIdentityStore,
+  createRegistrySecretsStore,
+} from 'cwip/cc-registry';
+import {
+  createLocalExecutionDriver,
+  createMemoryJobResultStore,
+  type JobResultStore,
+  type ManifestCommand,
+  safeArgSchema,
+} from '../drivers';
+import { createFakeSpawn } from '../../verify/runtime/verifyContext';
+import { createMemoryAsyncRevocationStore } from '../guard/revocationStore';
+import { createLocalDevServices } from './localHost';
+import { createSessionSigner, type SessionSigner } from '../guard/sessionSigner';
+import type { EffectiveManifest } from '../../verify/types';
+import { verifyAppConfig } from '../../verify/pipeline';
+import {
+  assertJobKindsHandled,
+  bootEngineApp,
+  type BootedEngineApp,
+  buildDrivers,
+  buildEngineServices,
+  buildJobHandlers,
+  enqueueableKindsFor,
+  manifestNeedsAi,
+  openDomainHandles,
+  resolveManagedDomains,
+} from './recipe';
+
+// ── fakes (the runtime.spec.ts patterns) ────────────────────────────────────
+
+const memoryObjectStore = (): ObjectStore & { objects: Map<string, string> } => {
+  const objects = new Map<string, string>();
+  return {
+    objects,
+    async put(key, body) {
+      const text = await new Response(body).text();
+      objects.set(key, text);
+      return { key, size: text.length, modifiedAt: new Date().toISOString() };
+    },
+    async get(key) {
+      const value = objects.get(key);
+      return value === undefined ? null : new Response(value).body;
+    },
+    async stat(key) {
+      const value = objects.get(key);
+      return value === undefined ? null : { key, size: value.length, modifiedAt: new Date().toISOString() };
+    },
+    async delete(key) {
+      return objects.delete(key);
+    },
+    async signedUrl(key) {
+      return `memory://${key}`;
+    },
+  };
+};
+
+const countingTelemetry = (): TelemetryWriter =>
+  ({
+    recordApiCall: () => undefined,
+    recordMeterEvent: () => ({ eventUuid: 'evt', durable: 'table' }),
+    flush: async () => ({ apiCalls: 0, meterEvents: 0, dropped: 0 }),
+    drainSpill: async () => 0,
+    stats: () => ({ queued: 0, dropped: 0, spilled: 0, flushed: 0 }),
+    close: async () => undefined,
+  }) as unknown as TelemetryWriter;
+
+/** A broker that queues nothing — for boots where the queue is upstream noise. */
+const stubBroker = () => ({
+  enqueue: async () => 'job_1',
+  onComplete: () => {},
+  awaitCompletion: async () => ({ jobId: 'job_1', ok: true }),
+  cancel: async () => {},
+  status: async () => ({ jobId: 'job_1', ok: null }),
+});
+
+/** True iff `fn` throws an AppError carrying exactly `code` (codes live on `.code`, not the message). */
+const throwsCode = (fn: () => unknown, code: string): boolean => {
+  try {
+    fn();
+  } catch (error) {
+    return (error as { code?: string }).code === code;
+  }
+  return false;
+};
+
+const buildManifest = async (
+  config: Record<string, unknown>,
+  capabilities: Record<string, boolean> = {},
+): Promise<EffectiveManifest> => {
+  const result = await verifyAppConfig({ config, moment: 'boot', capabilities });
+  if (!result.manifest) throw new Error(`config failed to verify: ${JSON.stringify(result.diagnostics)}`);
+  return result.manifest;
+};
+
+const LOCAL_APP = {
+  configVersion: 1,
+  app: { id: 'recipe-demo', title: 'Recipe Demo' },
+  profile: 'local',
+  engines: ['asset', 'knowledge', 'system'],
+  instances: [
+    { engine: 'asset', id: 'gallery', features: { gallery: true, video: false, hls: false, privateMedia: false } },
+    { engine: 'knowledge', id: 'notes', features: { notes: true, todos: true } },
+    { engine: 'system', id: 'utils', features: { notifications: true } },
+  ],
+} as const;
+
+// ── openDomainHandles ────────────────────────────────────────────────────────
+
+describe('recipe — openDomainHandles', () => {
+  it('opens exactly the domains the active engines own (knowledge ⇒ + search)', async () => {
+    const manifest = await buildManifest(LOCAL_APP);
+    expect(new Set(resolveManagedDomains(manifest))).toEqual(new Set(['knowledge', 'media', 'search', 'system']));
+
+    const handles = {
+      knowledge: new Database(':memory:'),
+      media: new Database(':memory:'),
+      search: new Database(':memory:'),
+      system: new Database(':memory:'),
+    };
+    const opened = openDomainHandles(manifest, { handles });
+    expect(new Set(Object.keys(opened.handles))).toEqual(new Set(['knowledge', 'media', 'search', 'system']));
+    expect(opened.searchDb).toBe(handles.search);
+    await opened.close(); // injected handles are the caller's to close
+    for (const db of Object.values(handles)) {
+      getTxnLifetimeGuard(db)?.dispose();
+      db.close();
+    }
+  });
+
+  it('refuses the saas profile (dialect repos not yet runnable — 03 §2)', async () => {
+    const manifest = { ...(await buildManifest(LOCAL_APP)), profile: 'saas' as const };
+    expect(() => openDomainHandles(manifest, { root: '/tmp/nope' })).toThrow(/SAAS_STORAGE_UNWIRED|inject a StorageProvider/);
+  });
+
+  it('refuses to invent a path when neither root nor handle is given', async () => {
+    const manifest = await buildManifest(LOCAL_APP);
+    expect(() => openDomainHandles(manifest, {})).toThrow(/DOMAIN_ROOT_MISSING|never derives a path/);
+  });
+});
+
+// ── the CDC runtime auditor (05 §A3) ─────────────────────────────────────────
+
+describe('recipe — auditCdc reaches the storage provider', () => {
+  const handlesFor = () => ({
+    knowledge: new Database(':memory:'),
+    media: new Database(':memory:'),
+    search: new Database(':memory:'),
+    system: new Database(':memory:'),
+  });
+
+  const dispose = async (opened: { close(): Promise<void> }, handles: Record<string, Database>) => {
+    await opened.close();
+    for (const db of Object.values(handles)) {
+      getTxnLifetimeGuard(db)?.dispose();
+      db.close();
+    }
+  };
+
+  /**
+   * The auditor's whole job: a committed write with no `ctx.emit` throws instead
+   * of silently starving search/audit/billing/the client cache. Driving it needs
+   * an op that deliberately breaks the pairing — the static sweep refuses one in
+   * the repository tier, which is exactly why the runtime belt is separate.
+   */
+  const unEmittingOp = {
+    name: 'spec.writeWithoutEmit',
+    async run(ctx: { driver: unknown }) {
+      // Through `.query(sql).run()` — the ONE path the statement executor uses,
+      // and therefore the only one the auditor instruments.
+      (ctx as { driver: Database })
+        .driver.query(
+          "INSERT INTO k_items (id, tenant_id, user_id, item_type, title) VALUES ('itm_x', 't_local', 'u', 'note', 'x')",
+        )
+        .run();
+    },
+  };
+
+  it('is OFF by default — production runs the un-audited path byte for byte', async () => {
+    const manifest = await buildManifest(LOCAL_APP);
+    const handles = handlesFor();
+    const opened = openDomainHandles(manifest, { handles });
+    await expect(opened.storage.domain('knowledge').exec(unEmittingOp as never)).resolves.toBeUndefined();
+    await dispose(opened, handles);
+  });
+
+  it('refuses an un-emitted write when the generated app turns it on', async () => {
+    const manifest = await buildManifest(LOCAL_APP);
+    const handles = handlesFor();
+    const opened = openDomainHandles(manifest, { handles, auditCdc: true });
+    await expect(opened.storage.domain('knowledge').exec(unEmittingOp as never)).rejects.toMatchObject({
+      code: 'CDC_EMIT_MISSING',
+    });
+    await dispose(opened, handles);
+  });
+
+  it('bootEngineApp threads the flag through to the provider it builds', async () => {
+    const manifest = await buildManifest(LOCAL_APP);
+    const handles = handlesFor();
+    const booted = bootEngineApp({
+      manifest,
+      handles,
+      objects: memoryObjectStore(),
+      telemetry: countingTelemetry(),
+      allowedOrigins: ['http://localhost:4747'],
+      meterSpillDrainIntervalMs: 0,
+      auditCdc: true,
+    });
+    await expect(booted.ctx.storage.domain('knowledge').exec(unEmittingOp as never)).rejects.toMatchObject({
+      code: 'CDC_EMIT_MISSING',
+    });
+    await booted.stop();
+    for (const db of Object.values(handles)) {
+      getTxnLifetimeGuard(db)?.dispose();
+      db.close();
+    }
+  });
+});
+
+// ── the stale-upload reaper is WIRED, not merely written (05 §A2) ────────────
+
+describe('recipe — the vault reaper is constructed by bootEngineApp', () => {
+  const VAULT_APP = {
+    configVersion: 1,
+    app: { id: 'vault-app', title: 'Vault App' },
+    profile: 'local',
+    engines: ['asset'],
+    instances: [{ engine: 'asset', id: 'vault', features: { gallery: true, vaultSource: true } }],
+  };
+
+  const handlesFor = () => ({ media: new Database(':memory:') });
+
+  it('a vault app boots and stops cleanly with the reaper running', async () => {
+    const manifest = await buildManifest(VAULT_APP);
+    const handles = handlesFor();
+    const booted = bootEngineApp({
+      manifest,
+      handles,
+      objects: memoryObjectStore(),
+      telemetry: countingTelemetry(),
+      allowedOrigins: ['http://localhost:4747'],
+      meterSpillDrainIntervalMs: 0,
+      // A long interval so the timer never fires inside the test; `stop()` is
+      // what is under test — an unstopped interval keeps the process alive.
+      vaultReaper: { intervalMs: 3_600_000 },
+    });
+    expect((await booted.app.fetch(new Request('http://localhost/api/asset/health'))).status).toBe(200);
+    await booted.stop();
+    for (const db of Object.values(handles)) {
+      getTxnLifetimeGuard(db)?.dispose();
+      db.close();
+    }
+  });
+
+  /**
+   * The loud half. Enumerating tenants is an unscoped read RLS forbids, so a
+   * multi-tenant vault app must NAME them — and shipping one with no reaper is
+   * how the leak 05 §A2 closes came back. It fails at BOOT, not at the first
+   * tick an hour later.
+   */
+  it('REFUSES a saas vault app that names no tenants', async () => {
+    const manifest = { ...(await buildManifest(VAULT_APP)), profile: 'saas' as const };
+    const handles = handlesFor();
+    const opened = openDomainHandles({ ...manifest, profile: 'local' }, { handles });
+    expect(
+      throwsCode(
+        () =>
+          bootEngineApp({
+            manifest,
+            // Injected, because openDomainHandles refuses the saas profile
+            // outright, and a saas boot builds neither a queue nor a storage
+            // provider for itself. Both are upstream of the reaper check.
+            storage: opened.storage,
+            broker: stubBroker(),
+            objects: memoryObjectStore(),
+            // The SHARED control-plane seams (04 §1). They are supplied here not
+            // because this test is about them, but because `assertSaasHostWiring`
+            // now refuses an incompletely-wired saas app BEFORE the boot gets
+            // this far — which is the point of the layering: the shallow gate
+            // catches the whole host at once, and this test is about the deeper,
+            // more specific refusal that sits behind it.
+            jobResults: createMemoryJobResultStore(),
+            revocationStore: createMemoryAsyncRevocationStore(),
+            // Same reason as the two above: the saas profile composes the
+            // billing mixin unconditionally, so `assertSaasHostWiring` names it
+            // too (04 §1a) and would answer first.
+            billing: { usage: async () => [], plan: async () => ({ id: 'test', title: 'Test', limits: {} }) },
+            // And the shared meter behind it (04 item 4e), for the same reason:
+            // a saas app whose billing reads this node's own `meter_events`
+            // enforces every plan ceiling once per node, so the gate names it
+            // and would answer before the reaper does.
+            meter: { usage: { totals: async () => [] }, executor: {} as never, nodeId: 'test-node' },
+            telemetry: countingTelemetry(),
+            allowedOrigins: ['http://localhost:4747'],
+            meterSpillDrainIntervalMs: 0,
+          }),
+        'VAULT_REAPER_UNWIRED',
+      ),
+    ).toBe(true);
+    await opened.close();
+    for (const db of Object.values(handles)) {
+      getTxnLifetimeGuard(db)?.dispose();
+      db.close();
+    }
+  });
+});
+
+// ── job kinds ────────────────────────────────────────────────────────────────
+
+describe('recipe — job kinds (audit G8)', () => {
+  it('derives the enqueueable kinds from the active engines', async () => {
+    const manifest = await buildManifest(LOCAL_APP);
+    // asset ⇒ reindex/transcode/ocr, knowledge ⇒ reindex/organize/import.
+    expect(new Set(enqueueableKindsFor(manifest))).toEqual(new Set(['reindex', 'transcode', 'ocr', 'organize', 'import']));
+  });
+
+  it('builds a handler for EVERY enqueueable kind — no gaps', async () => {
+    const manifest = await buildManifest(LOCAL_APP);
+    const handles = { knowledge: new Database(':memory:'), media: new Database(':memory:'), search: new Database(':memory:'), system: new Database(':memory:') };
+    const { storage, searchDb } = openDomainHandles(manifest, { handles });
+    const gateway = { completeStructured: async () => ({}) } as never;
+    const search = createSqliteSearchProvider({ db: searchDb! });
+    const { handlers, enqueueableKinds } = buildJobHandlers({ manifest, storage, gateway, search });
+    for (const kind of enqueueableKinds) expect(handlers[kind]).toBeDefined();
+    // The assert passes on the full map…
+    expect(() => assertJobKindsHandled({ enqueueableKinds, handlers })).not.toThrow();
+    // …and fails on a synthetic kind with no handler.
+    expect(() => assertJobKindsHandled({ enqueueableKinds: [...enqueueableKinds, 'ghost'], handlers })).toThrow(
+      /JOB_KIND_UNHANDLED|ghost/,
+    );
+    await storage.close();
+    for (const db of Object.values(handles)) {
+      getTxnLifetimeGuard(db)?.dispose();
+      db.close();
+    }
+  });
+
+  it('transcode/ocr are loud-unimplemented WITHOUT an ObjectStore (no asset bytes to work on)', async () => {
+    const manifest = await buildManifest(LOCAL_APP);
+    const handles = { knowledge: new Database(':memory:'), media: new Database(':memory:'), search: new Database(':memory:'), system: new Database(':memory:') };
+    const { storage, searchDb } = openDomainHandles(manifest, { handles });
+    const search = createSqliteSearchProvider({ db: searchDb! });
+    // No `objects` ⇒ the asset handlers cannot be real (an ObjectStore is their
+    // whole substrate), so both fall to the loud 501 placeholder, not a no-op.
+    const { handlers } = buildJobHandlers({ manifest, storage, gateway: {} as never, search });
+    expect(() => (handlers.transcode as (p: unknown, c: unknown) => unknown)({}, {})).toThrow(/JOB_HANDLER_UNIMPLEMENTED|transcode/);
+    expect(() => (handlers.ocr as (p: unknown, c: unknown) => unknown)({}, {})).toThrow(/JOB_HANDLER_UNIMPLEMENTED|ocr/);
+    await storage.close();
+    for (const db of Object.values(handles)) {
+      getTxnLifetimeGuard(db)?.dispose();
+      db.close();
+    }
+  });
+
+  it('transcode/ocr become REAL handlers once an ObjectStore is wired (04 §2d)', async () => {
+    const manifest = await buildManifest(LOCAL_APP);
+    const handles = { knowledge: new Database(':memory:'), media: new Database(':memory:'), search: new Database(':memory:'), system: new Database(':memory:') };
+    const { storage, searchDb } = openDomainHandles(manifest, { handles });
+    const search = createSqliteSearchProvider({ db: searchDb! });
+    const gateway = { completeStructured: async () => ({}) } as never;
+    const { handlers } = buildJobHandlers({ manifest, storage, gateway, search, objects: memoryObjectStore() });
+    const jobCtx = { jobId: 'j', tenantId: 't_local', signal: new AbortController().signal, logger: { info() {}, warn() {}, error() {}, debug() {} } };
+    // A real handler validates its payload (missing id/fileId) rather than throwing
+    // the placeholder's "not yet implemented" — proof it is the §2d handler.
+    await expect((handlers.transcode as (p: unknown, c: unknown) => Promise<unknown>)({}, jobCtx)).rejects.toThrow(
+      /missing a media file id/,
+    );
+    await expect((handlers.ocr as (p: unknown, c: unknown) => Promise<unknown>)({}, jobCtx)).rejects.toThrow(/missing fileId/);
+    await storage.close();
+    for (const db of Object.values(handles)) {
+      getTxnLifetimeGuard(db)?.dispose();
+      db.close();
+    }
+  });
+
+  it('deploy is a REAL handler when the dev engine has exec + a plan, loud otherwise (03 §4b)', async () => {
+    const devConfig = {
+      configVersion: 1,
+      app: { id: 'dev-demo', title: 'Dev Demo' },
+      profile: 'local',
+      engines: ['dev'],
+      instances: [{ engine: 'dev', id: 'devtools', features: { pipelines: true } }],
+    };
+    const manifest = await buildManifest(devConfig);
+    expect(enqueueableKindsFor(manifest)).toContain('deploy');
+    const storage = { domain: () => ({}) } as never;
+
+    // No exec/plan ⇒ the loud placeholder (a deploy with nothing to run must not
+    // report success).
+    const bare = buildJobHandlers({ manifest, storage, gateway: {} as never });
+    expect(() => (bare.handlers.deploy as (p: unknown, c: unknown) => unknown)({ appId: 'x' }, {})).toThrow(
+      /not yet implemented/,
+    );
+
+    // exec + plan ⇒ the real handler. A fake driver whose one step exits 0.
+    let ran = 0;
+    const exec = {
+      async run() {
+        ran += 1;
+        return { handleId: 'h1', commandId: 'c', pid: 1, startedAt: 0 };
+      },
+      async status() {
+        return { handleId: 'h1', state: 'exited', exitCode: 0, startedAt: 0, endedAt: 1 };
+      },
+      async kill() {},
+      trackedPids: () => [],
+      sweep() {},
+    } as never;
+    const wired = buildJobHandlers({
+      manifest,
+      storage,
+      gateway: {} as never,
+      exec,
+      deployPlan: async () => [{ commandId: 'deploy.run', label: 'run' }],
+    });
+    const ctx = { jobId: 'j', tenantId: 't1', instanceId: 'devtools', signal: new AbortController().signal, logger: { info() {}, warn() {}, error() {}, debug() {} } };
+    const out = (await (wired.handlers.deploy as (p: unknown, c: unknown) => Promise<unknown>)({ appId: 'x' }, ctx)) as {
+      appId: string;
+    };
+    expect(out.appId).toBe('x');
+    expect(ran).toBe(1);
+    // Either way, the boot inventory assert is satisfied — deploy is handled.
+    expect(() => assertJobKindsHandled({ enqueueableKinds: wired.enqueueableKinds, handlers: wired.handlers })).not.toThrow();
+  });
+});
+
+// ── drivers boot gate ────────────────────────────────────────────────────────
+
+describe('recipe — buildDrivers (AI boot gate, G2/03 §1d)', () => {
+  it('fails the boot for an AI-effective manifest with no driver', async () => {
+    const aiConfig = {
+      configVersion: 1,
+      app: { id: 'ai-demo', title: 'AI Demo' },
+      profile: 'local',
+      engines: ['knowledge'],
+      instances: [{ engine: 'knowledge', id: 'brain', features: { ragChat: true } }],
+    };
+    const manifest = await buildManifest(aiConfig, { aiProvider: true });
+    expect(manifestNeedsAi(manifest)).toBe(true);
+    expect(throwsCode(() => buildDrivers(manifest, { drivers: {} }), 'AI_DRIVER_UNAVAILABLE')).toBe(true);
+  });
+
+  it('passes a manifest with no AI feature, wiring an empty driver map', async () => {
+    const manifest = await buildManifest(LOCAL_APP);
+    expect(manifestNeedsAi(manifest)).toBe(false);
+    expect(() => buildDrivers(manifest, { drivers: {} })).not.toThrow();
+  });
+
+  it('constructs a declared provider and folds its endpoint into the CSP allowlist', async () => {
+    const manifest = await buildManifest(LOCAL_APP);
+    const built = buildDrivers(manifest, { providers: { ollama: { endpoint: 'http://127.0.0.1:11434' } } });
+
+    expect(built.drivers.ollama?.provider).toBe('ollama');
+    // The reason to DECLARE rather than hand-construct: a hand-built driver's
+    // endpoint is invisible to the export moment's `cspConnectAllowlist`.
+    expect(built.cspEndpoints).toContain('http://127.0.0.1:11434');
+  });
+
+  it('fails the boot for a declared provider whose credential is missing', async () => {
+    const manifest = await buildManifest(LOCAL_APP);
+    // A driver constructed with `apiKey: undefined` is a 401 on the first user
+    // request, hours later, on a machine nobody is watching.
+    expect(throwsCode(() => buildDrivers(manifest, { providers: { anthropic: {} } }), 'AI_DRIVER_UNAVAILABLE')).toBe(
+      true,
+    );
+  });
+
+  it('fails the boot when a CONFIGURED model names a provider nobody wired', async () => {
+    const manifest = await buildManifest(LOCAL_APP);
+    expect(
+      throwsCode(
+        () => buildDrivers(manifest, { providers: { ollama: {} }, requiredProviders: ['openai'] }),
+        'AI_DRIVER_UNAVAILABLE',
+      ),
+    ).toBe(true);
+    expect(() => buildDrivers(manifest, { providers: { ollama: {} }, requiredProviders: ['ollama'] })).not.toThrow();
+  });
+
+  it('lets an explicitly-constructed driver win over the same declared provider', async () => {
+    const manifest = await buildManifest(LOCAL_APP);
+    const explicit = { provider: 'ollama' as const, complete: async () => ({ text: '', tokensIn: 0, tokensOut: 0 }) };
+    const built = buildDrivers(manifest, { providers: { ollama: {} }, drivers: { ollama: explicit } });
+    expect(built.drivers.ollama).toBe(explicit);
+  });
+});
+
+// ── buildEngineServices boot-loud ────────────────────────────────────────────
+
+describe('recipe — buildEngineServices', () => {
+  it('refuses to build the asset service with no ObjectStore (OBJECT_STORE_MISSING)', async () => {
+    const manifest = await buildManifest(LOCAL_APP);
+    const handles = { knowledge: new Database(':memory:'), media: new Database(':memory:'), search: new Database(':memory:'), system: new Database(':memory:') };
+    const { storage } = openDomainHandles(manifest, { handles });
+    expect(
+      throwsCode(
+        () =>
+          buildEngineServices({
+            manifest,
+            storage,
+            broker: {} as never,
+            telemetry: countingTelemetry(),
+            signer: createSessionSigner({ ttlSeconds: 60 }),
+            // objects deliberately omitted
+          }),
+        'OBJECT_STORE_MISSING',
+      ),
+    ).toBe(true);
+    await storage.close();
+    for (const db of Object.values(handles)) {
+      getTxnLifetimeGuard(db)?.dispose();
+      db.close();
+    }
+  });
+});
+
+// ── bootEngineApp end to end ──────────────────────────────────────────────────
+
+describe('bootEngineApp — a composed app over real SQLite', () => {
+  let booted: BootedEngineApp;
+  let handles: Record<string, Database>;
+  let signer: SessionSigner;
+
+  const boot = async (): Promise<void> => {
+    const manifest = await buildManifest(LOCAL_APP);
+    handles = {
+      knowledge: new Database(':memory:'),
+      media: new Database(':memory:'),
+      search: new Database(':memory:'),
+      system: new Database(':memory:'),
+    };
+    signer = createSessionSigner({ ttlSeconds: 300 });
+    booted = bootEngineApp({
+      manifest,
+      handles,
+      objects: memoryObjectStore(),
+      telemetry: countingTelemetry(),
+      signer,
+      allowedOrigins: ['http://localhost:4747'],
+      meterSpillDrainIntervalMs: 0,
+    });
+  };
+
+  afterEach(async () => {
+    await booted.stop();
+    for (const db of Object.values(handles)) {
+      getTxnLifetimeGuard(db)?.dispose();
+      db.close();
+    }
+  });
+
+  const fetchApp = (path: string, init: RequestInit = {}): Promise<Response> =>
+    Promise.resolve(booted.app.fetch(new Request(`http://localhost${path}`, init)));
+
+  const ownerToken = (): string =>
+    signer.mint({ tenantId: 't_local', userId: 'u_local', role: 'OWNER', permissions: ['infra:write'], privateScope: true }).token;
+
+  it('serves the active engines and 404s the inactive ones', async () => {
+    await boot();
+    const health = (await (await fetchApp('/api/core/health')).json()) as { appId: string };
+    expect(health.appId).toBe('recipe-demo');
+    expect((await fetchApp('/api/knowledge/health')).status).toBe(200);
+    expect((await fetchApp('/api/dev/health')).status).toBe(404);
+    expect((await fetchApp('/api/guard/health')).status).toBe(404);
+  });
+
+  it('round-trips a write through a real repository', async () => {
+    await boot();
+    const created = await fetchApp('/api/knowledge/records', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', authorization: `Bearer ${ownerToken()}` },
+      body: JSON.stringify({ type: 'note', title: 'Recipe wrote this' }),
+    });
+    expect(created.status).toBe(201);
+    const row = handles.knowledge.query('SELECT title FROM k_items LIMIT 1').get() as { title: string } | null;
+    expect(row?.title).toBe('Recipe wrote this');
+  });
+
+  it('DUAL-WIRES search: a composed write fills the index a second reader opens', async () => {
+    await boot();
+    await fetchApp('/api/knowledge/records', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', authorization: `Bearer ${ownerToken()}` },
+      body: JSON.stringify({ type: 'note', title: 'Searchable pelican note' }),
+    });
+    // CDC → search write tap (bridgeCdcToSearch) runs off the mutation stream.
+    await booted.ctx.storage.domain('knowledge').drainMutations();
+
+    // A SECOND provider over the SAME search handle sees the indexed document —
+    // proof the runtime's write side and the service's read side share ONE index.
+    const reader = createSqliteSearchProvider({ db: handles.search });
+    const hits = await reader.query('pelican', { tenantId: 't_local', limit: 10 });
+    expect(hits.length).toBeGreaterThan(0);
+    expect(hits[0]?.title).toContain('pelican');
+  });
+
+  it('exposes the resolved drivers + merged job-handler map for the worker to reuse', async () => {
+    await boot();
+    expect(booted.jobHandlers.reindex).toBeDefined();
+    expect(booted.jobHandlers.organize).toBeDefined();
+    expect(booted.drivers).toEqual({});
+  });
+
+  it("adopts an INJECTED store's own verifySignedUrl — the store serves what it signed", async () => {
+    // The single-box saas shape (launch spec D34 = A): a host injects
+    // `createFsObjectStore(...)` as `host.objects`. Before this branch existed
+    // the injected store passed the `objects` boot gate and then silently lost
+    // the serving route — `readSignedObject` only exists when a verifier is
+    // wired, so every URL the store itself signed 404'd. The store carries its
+    // verifier ON the store precisely so signer and verifier cannot disagree;
+    // the recipe must adopt it.
+    const objectRoot = mkdtempSync(path.join(tmpdir(), 'cc-recipe-fsstore-'));
+    try {
+      const manifest = await buildManifest(LOCAL_APP);
+      handles = {
+        knowledge: new Database(':memory:'),
+        media: new Database(':memory:'),
+        search: new Database(':memory:'),
+        system: new Database(':memory:'),
+      };
+      signer = createSessionSigner({ ttlSeconds: 300 });
+      const fsStore = createFsObjectStore({ root: objectRoot, signingKey: new Uint8Array(32).fill(7) });
+      booted = bootEngineApp({
+        manifest,
+        handles,
+        objects: fsStore,
+        telemetry: countingTelemetry(),
+        signer,
+        allowedOrigins: ['http://localhost:4747'],
+        meterSpillDrainIntervalMs: 0,
+      });
+
+      await fsStore.put(
+        't_local/hello.txt',
+        new Response('signed bytes came back').body as ReadableStream<Uint8Array>,
+        { contentType: 'text/plain' },
+      );
+      const url = await fsStore.signedUrl('t_local/hello.txt');
+      const served = await fetchApp(url);
+      expect(served.status).toBe(200);
+      expect(await served.text()).toBe('signed bytes came back');
+
+      // The negative control: a tampered signature must still be a 404 — the
+      // adopted verifier is a verifier, not a pass-through.
+      const forged = url.replace(/sig=[^&]+/, 'sig=deadbeef');
+      expect((await fetchApp(forged)).status).toBe(404);
+    } finally {
+      rmSync(objectRoot, { recursive: true, force: true });
+    }
+  });
+});
+
+// ── the guard engine, turned on for real (02 §1b) ─────────────────────────────
+//
+// The inversion that proves the identity seam is consumed: EVERY prior test
+// asserts `/api/guard/health` → 404 because `resolveIdentity` had no value and no
+// app supplied `guardDeps`, so `createGuardService` was never constructed. Here a
+// guard-active manifest boots with a REAL manager/secrets/identity store and the
+// recipe's default resolver (the bootstrap OWNER) — and health answers 200.
+
+/** A deterministic, PASSWORD-SENSITIVE argon2id stand-in — the login path is only
+ * meaningful if a wrong password derives a different key. */
+const stubArgon2id: Argon2idDeriver = ({ password, salt, keyLength }) => {
+  const out = new Uint8Array(keyLength);
+  for (let i = 0; i < keyLength; i += 1)
+    out[i] = ((password[i % password.length] ?? 0) ^ (salt[i % salt.length] ?? 0) ^ (i & 0xff)) & 0xff;
+  return out;
+};
+
+describe('bootEngineApp — the guard engine consumes resolveIdentity (02 §1b)', () => {
+  const GUARD_APP = {
+    configVersion: 1,
+    app: { id: 'guard-demo', title: 'Guard Demo' },
+    profile: 'local',
+    engines: ['guard'],
+    instances: [{ engine: 'guard', id: 'guard-main', features: {} }],
+  } as const;
+
+  let registry: Database;
+  let booted: BootedEngineApp;
+
+  beforeEach(() => {
+    // The guard engine's boot gate (assertArgon2idReady) refuses to serve without a
+    // registered KDF binding — the same gate a real host satisfies in host.ts.
+    setArgon2idDeriver(stubArgon2id);
+  });
+
+  afterEach(async () => {
+    await booted?.stop();
+    getTxnLifetimeGuard(registry)?.dispose();
+    registry.close();
+    setArgon2idDeriver(null); // process-wide seam — never leak the stub into other suites
+  });
+
+  const bootGuard = async (over: Record<string, unknown> = {}, appConfig: Record<string, unknown> = GUARD_APP): Promise<void> => {
+    const manifest = await buildManifest(appConfig);
+    registry = new Database(':memory:');
+    assertCcPragmas(registry);
+    runNamespacedMigrations(registry, CC_REGISTRY_MIGRATIONS, { namespace: 'registry' });
+    const rowSigner = createRowSigner({ integrityKey: mintMachineIntegrityKey() });
+    const identity = createRegistryIdentityStore(registry, { signer: rowSigner });
+    const manager = createSecretEnvelopeManager({ salt: mintEnvelopeSalt(), deriver: stubArgon2id });
+    const secrets = createRegistrySecretsStore(registry, { manager, signer: rowSigner });
+    booted = bootEngineApp({
+      manifest,
+      handles: {},
+      telemetry: countingTelemetry(),
+      signer: createSessionSigner({ ttlSeconds: 300 }),
+      allowedOrigins: ['http://localhost:4747'],
+      meterSpillDrainIntervalMs: 0,
+      // resolveIdentity deliberately OMITTED — the recipe defaults it from `identity`.
+      guardDeps: { manager, secrets, identity },
+      ...over,
+    });
+  };
+
+  const fetchApp = (path: string, init: RequestInit = {}): Promise<Response> =>
+    Promise.resolve(booted.app.fetch(new Request(`http://localhost${path}`, init)));
+
+  it('serves /api/guard/health 200 when the guard engine is turned on (was 404 for the whole arc)', async () => {
+    await bootGuard();
+    expect((await fetchApp('/api/guard/health')).status).toBe(200);
+  });
+
+  it('unlock resolves the bootstrap OWNER through the default resolver and mints an OWNER session', async () => {
+    await bootGuard();
+    // Exercises the WHOLE seam: unlock → the recipe's default AccountService(local)
+    // resolver → bootstrapLocalIdentity → signer.mint. The minted claims carry the
+    // OWNER role + infra:write, and the reserved membership is now in the registry.
+    const res = await fetchApp('/api/guard/unlock', {
+      method: 'POST',
+      body: (new Uint8Array([1, 2, 3, 4])).buffer as ArrayBuffer, // the body IS the passphrase (custody law)
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { privateMode: { claims: { role: string; permissions: string[] } } };
+    expect(body.privateMode.claims.role).toBe('OWNER');
+    expect(body.privateMode.claims.permissions).toContain('infra:write');
+
+    const owner = registry.query("SELECT role FROM memberships WHERE user_id = 'u_local'").get() as
+      | { role: string }
+      | null;
+    expect(owner?.role).toBe('OWNER');
+  });
+
+  it('fails the boot LOUDLY when guard is active but neither resolveIdentity nor an identity store is wired', async () => {
+    const manifest = await buildManifest(GUARD_APP);
+    registry = new Database(':memory:');
+    assertCcPragmas(registry);
+    runNamespacedMigrations(registry, CC_REGISTRY_MIGRATIONS, { namespace: 'registry' });
+    const rowSigner = createRowSigner({ integrityKey: mintMachineIntegrityKey() });
+    const manager = createSecretEnvelopeManager({ salt: mintEnvelopeSalt(), deriver: stubArgon2id });
+    const secrets = createRegistrySecretsStore(registry, { manager, signer: rowSigner });
+    expect(() =>
+      bootEngineApp({
+        manifest,
+        handles: {},
+        telemetry: countingTelemetry(),
+        signer: createSessionSigner({ ttlSeconds: 300 }),
+        allowedOrigins: ['http://localhost:4747'],
+        meterSpillDrainIntervalMs: 0,
+        guardDeps: { manager, secrets }, // no identity, no resolveIdentity
+      }),
+    ).toThrow(/GUARD_IDENTITY_UNWIRED|identity store was provided/);
+  });
+
+  // ── 02 §2 — the loginable milestone: signup/login/password over the real pipeline ──
+  const pw = (value: string): Uint8Array => new TextEncoder().encode(value);
+
+  it('signup → login → authenticated request: a REAL minted token authenticates (02 §2, Law #4)', async () => {
+    await bootGuard();
+    const signup = await fetchApp('/api/guard/accounts?email=ann@home.test', { method: 'POST', body: (pw('sup3r-secret')).buffer as ArrayBuffer });
+    expect(signup.status).toBe(201);
+    const created = (await signup.json()) as { account: { userId: string; tenantId: string; role: string } };
+    expect(created.account.tenantId).toBe('t_local'); // local signup joins the machine tenant
+    expect(created.account.role).toBe('MEMBER');
+
+    const login = await fetchApp('/api/guard/login?email=ann@home.test', { method: 'POST', body: (pw('sup3r-secret')).buffer as ArrayBuffer });
+    expect(login.status).toBe(200);
+    const body = (await login.json()) as { session: { token: string; claims: { role: string; userId: string } } };
+    expect(body.session.claims.userId).toBe(created.account.userId);
+    expect(body.session.claims.role).toBe('MEMBER'); // the REAL membership role, minted server-side
+
+    // The minted token authenticates through guardVerify on a protected route.
+    const locked = await fetchApp('/api/guard/lock', {
+      method: 'POST',
+      headers: { authorization: `Bearer ${body.session.token}` },
+    });
+    expect(locked.status).toBe(200);
+  });
+
+  it('login with a wrong password is a typed 401 (02 §2)', async () => {
+    await bootGuard();
+    await fetchApp('/api/guard/accounts?email=ann@home.test', { method: 'POST', body: (pw('right-secret')).buffer as ArrayBuffer });
+    const login = await fetchApp('/api/guard/login?email=ann@home.test', { method: 'POST', body: (pw('wrong-secret')).buffer as ArrayBuffer });
+    expect(login.status).toBe(401);
+  });
+
+  // The exact refusal point is the contract, not an incidental. It survived the
+  // 2026-08-02 swap of the fixed-window lockout for the shared exponential/global
+  // throttle only because `guard.mixin.ts` states `threshold: 4` — the shared default
+  // counts one attempt more leniently. If someone deletes that argument to "use the
+  // default", this test is what tells them they loosened a security control.
+  it('login is throttled per account: N failed attempts → 429 (L5 — the limiter is now in the product path)', async () => {
+    await bootGuard();
+    await fetchApp('/api/guard/accounts?email=ann@home.test', { method: 'POST', body: (pw('right-secret')).buffer as ArrayBuffer });
+    for (let i = 0; i < 5; i += 1) {
+      const bad = await fetchApp('/api/guard/login?email=ann@home.test', { method: 'POST', body: (pw('bad-guess-here')).buffer as ArrayBuffer });
+      expect(bad.status).toBe(401);
+    }
+    const throttled = await fetchApp('/api/guard/login?email=ann@home.test', { method: 'POST', body: (pw('bad-guess-here')).buffer as ArrayBuffer });
+    expect(throttled.status).toBe(429);
+    // …and the refusal carries a Retry-After the client can honor.
+    expect(Number(throttled.headers.get('Retry-After'))).toBeGreaterThan(0);
+  });
+
+  // Case-varying the email must not mint a fresh per-account budget — the hole the
+  // satellites' copy of this throttle had before the two were consolidated.
+  it('the per-account throttle is case-insensitive on the email', async () => {
+    await bootGuard();
+    await fetchApp('/api/guard/accounts?email=ann@home.test', { method: 'POST', body: (pw('right-secret')).buffer as ArrayBuffer });
+    for (let i = 0; i < 5; i += 1)
+      await fetchApp('/api/guard/login?email=ann@home.test', { method: 'POST', body: (pw('bad-guess-here')).buffer as ArrayBuffer });
+    const evaded = await fetchApp('/api/guard/login?email=ANN@Home.TEST', { method: 'POST', body: (pw('bad-guess-here')).buffer as ArrayBuffer });
+    expect(evaded.status).toBe(429);
+  });
+
+  it('unlock is rate-limited per IP: N attempts → 429 (L5 — /api/guard/unlock is no longer unthrottled)', async () => {
+    await bootGuard();
+    let last = 200;
+    for (let i = 0; i < 11; i += 1)
+      last = (await fetchApp('/api/guard/unlock', { method: 'POST', body: (new Uint8Array([1, 2, 3, 4])).buffer as ArrayBuffer })).status;
+    expect(last).toBe(429);
+  });
+
+  it('accounts-off ⇒ no login/signup routes exist (404, not a stub)', async () => {
+    await bootGuard({}, { ...GUARD_APP, instances: [{ engine: 'guard', id: 'guard-main', features: { accounts: false } }] });
+    expect((await fetchApp('/api/guard/login?email=x@y.z', { method: 'POST', body: (pw('pw')).buffer as ArrayBuffer })).status).toBe(404);
+    expect((await fetchApp('/api/guard/accounts?email=x@y.z', { method: 'POST', body: (pw('pw')).buffer as ArrayBuffer })).status).toBe(404);
+  });
+
+  // ── 02 §3 — tenant lifecycle + RBAC admin, end to end through REAL tokens ──
+  //
+  // `rbac-viewer-403` is the gate this whole file exists to make honest: not a
+  // unit test of a permission comparison, but a VIEWER created through the real
+  // invite path, logging in for a REAL minted token, being refused by the real
+  // knowledge route — then promoted through the real admin route and succeeding.
+  // Nothing here hand-forges a claim.
+
+  /** rbac ON: `knowledge:write` is enforced, which is what makes 403 possible. */
+  const RBAC_APP = {
+    configVersion: 1,
+    app: { id: 'rbac-demo', title: 'RBAC Demo' },
+    profile: 'local',
+    engines: ['guard', 'knowledge'],
+    instances: [
+      { engine: 'guard', id: 'guard-main', features: { rbac: true } },
+      { engine: 'knowledge', id: 'notes', features: { notes: true } },
+    ],
+  } as const;
+
+  const bearer = (token: string): RequestInit => ({ headers: { authorization: `Bearer ${token}` } });
+  const asJson = (token: string, body: unknown): RequestInit => ({
+    method: 'POST',
+    headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  });
+
+  /** The machine OWNER's session, minted by a REAL unlock through the pipeline. */
+  const unlockOwner = async (): Promise<string> => {
+    const res = await fetchApp('/api/guard/unlock', { method: 'POST', body: (new Uint8Array([1, 2, 3, 4])).buffer as ArrayBuffer });
+    expect(res.status).toBe(200);
+    return ((await res.json()) as { privateMode: { token: string } }).privateMode.token;
+  };
+
+  /** Invite `email` at `role`, then sign it up on the invitation — the real path. */
+  const inviteAndSignup = async (
+    ownerToken: string,
+    email: string,
+    role: string,
+  ): Promise<{ userId: string; token: string }> => {
+    const invited = await fetchApp('/api/guard/tenants/t_local/invitations', asJson(ownerToken, { email, role }));
+    expect(invited.status).toBe(201);
+    const { invitation } = (await invited.json()) as { invitation: { token: string } };
+
+    const signup = await fetchApp(`/api/guard/accounts?email=${encodeURIComponent(email)}`, {
+      method: 'POST',
+      // The invite is a bearer secret, so it rides a header, never the query.
+      headers: { 'x-cc-invitation': invitation.token },
+      body: (pw('viewer-secret-1')).buffer as ArrayBuffer,
+    });
+    expect(signup.status).toBe(201);
+    const created = (await signup.json()) as { account: { userId: string; role: string } };
+    expect(created.account.role).toBe(role); // the INVITATION decided it
+
+    const login = await fetchApp(`/api/guard/login?email=${encodeURIComponent(email)}`, {
+      method: 'POST',
+      body: (pw('viewer-secret-1')).buffer as ArrayBuffer,
+    });
+    expect(login.status).toBe(200);
+    return { userId: created.account.userId, token: ((await login.json()) as { session: { token: string } }).session.token };
+  };
+
+  it('rbac-viewer-403 → promote → 200, through the REAL grant path and REAL minted tokens (02 §3, Law #4)', async () => {
+    await bootGuard({ handles: { knowledge: new Database(':memory:'), search: new Database(':memory:') } }, RBAC_APP);
+    const owner = await unlockOwner();
+    const vic = await inviteAndSignup(owner, 'vic@home.test', 'VIEWER');
+
+    // A VIEWER's token carries no `knowledge:write`, and the route enforces it
+    // because rbac is on. This is `rbac-viewer-403`.
+    const refused = await fetchApp('/api/knowledge/records', asJson(vic.token, { type: 'note', title: 'nope' }));
+    expect(refused.status).toBe(403);
+    expect(((await refused.json()) as { error: { code: string } }).error.code).toBe('PERMISSION_DENIED');
+
+    // Promote through the real admin route.
+    const promoted = await fetchApp(`/api/guard/tenants/t_local/members/${vic.userId}`, {
+      method: 'PATCH',
+      headers: { authorization: `Bearer ${owner}`, 'content-type': 'application/json' },
+      body: JSON.stringify({ role: 'MEMBER' }),
+    });
+    expect(promoted.status).toBe(200);
+    expect(((await promoted.json()) as { member: { permissions: string[] } }).member.permissions).toContain('knowledge:write');
+
+    // The OLD token is dead the instant the grant changed — authorization reads
+    // the token's claims, so leaving it alive would mean the promotion (and, far
+    // worse, a demotion) had not happened.
+    expect((await fetchApp('/api/knowledge/records', bearer(vic.token))).status).toBe(401);
+
+    // Re-login picks up the new grant, and the SAME request now succeeds.
+    const relogin = await fetchApp('/api/guard/login?email=vic%40home.test', { method: 'POST', body: (pw('viewer-secret-1')).buffer as ArrayBuffer });
+    const fresh = ((await relogin.json()) as { session: { token: string } }).session.token;
+    const wrote = await fetchApp('/api/knowledge/records', asJson(fresh, { type: 'note', title: 'now allowed' }));
+    expect(wrote.status).toBe(201);
+  });
+
+  it('refuses privilege escalation and cross-tenant administration through the real routes (02 §3)', async () => {
+    await bootGuard({ handles: { knowledge: new Database(':memory:'), search: new Database(':memory:') } }, RBAC_APP);
+    const owner = await unlockOwner();
+    const vic = await inviteAndSignup(owner, 'vic@home.test', 'VIEWER');
+
+    // A VIEWER cannot reach the admin surface at all…
+    expect((await fetchApp('/api/guard/tenants/t_local/members', bearer(vic.token))).status).toBe(403);
+    // …and cannot promote themselves.
+    const selfPromote = await fetchApp(`/api/guard/tenants/t_local/members/${vic.userId}`, {
+      method: 'PATCH',
+      headers: { authorization: `Bearer ${vic.token}`, 'content-type': 'application/json' },
+      body: JSON.stringify({ role: 'OWNER' }),
+    });
+    expect(selfPromote.status).toBe(403);
+    expect(((await selfPromote.json()) as { error: { code: string } }).error.code).toBe('ROLE_REQUIRED');
+
+    // An unauthenticated caller gets 401, not a 403 that would confirm the route.
+    expect((await fetchApp('/api/guard/tenants/t_local/members')).status).toBe(401);
+
+    // The OWNER's own surface works — the members panel lists both accounts.
+    const listed = await fetchApp('/api/guard/tenants/t_local/members', bearer(owner));
+    expect(listed.status).toBe(200);
+    const { members } = (await listed.json()) as { members: { userId: string; role: string }[] };
+    expect(members.map((m) => m.userId).sort()).toEqual(['u_local', vic.userId].sort());
+  });
+
+  // ── 02 §4 — multi-device sessions over the real routes ────────────────────
+
+  /** Log `email` in as a NAMED device, the way a browser does. */
+  const loginAs = async (email: string, password: string, device: string): Promise<{ token: string; jti: string }> => {
+    const res = await fetchApp(`/api/guard/login?email=${encodeURIComponent(email)}`, {
+      method: 'POST',
+      headers: { 'x-cc-device': device },
+      body: (pw(password)).buffer as ArrayBuffer,
+    });
+    expect(res.status).toBe(200);
+    const { session } = (await res.json()) as { session: { token: string; claims: { jti: string } } };
+    return { token: session.token, jti: session.claims.jti };
+  };
+
+  it('two devices: listing, ending one, then logging out everywhere (02 §4)', async () => {
+    await bootGuard({ handles: { knowledge: new Database(':memory:'), search: new Database(':memory:') } }, RBAC_APP);
+    const owner = await unlockOwner();
+    await inviteAndSignup(owner, 'vic@home.test', 'MEMBER');
+    const laptop = await loginAs('vic@home.test', 'viewer-secret-1', 'laptop');
+    const phone = await loginAs('vic@home.test', 'viewer-secret-1', 'phone');
+
+    const listed = await fetchApp('/api/guard/sessions', bearer(laptop.token));
+    expect(listed.status).toBe(200);
+    const { sessions } = (await listed.json()) as {
+      sessions: { jti: string; deviceLabel?: string; current: boolean }[];
+    };
+    expect(sessions.map((s) => s.deviceLabel).sort()).toEqual(['laptop', 'phone']);
+    expect(sessions.find((s) => s.current)?.jti).toBe(laptop.jti);
+
+    // Ending the phone from the laptop closes exactly one session.
+    const ended = await fetchApp(`/api/guard/sessions/${phone.jti}`, { method: 'DELETE', ...bearer(laptop.token) });
+    expect(ended.status).toBe(200);
+    expect((await fetchApp('/api/guard/sessions', bearer(phone.token))).status).toBe(401);
+    expect((await fetchApp('/api/guard/sessions', bearer(laptop.token))).status).toBe(200);
+
+    // …and "log out everywhere" closes the clicking device too, or it is not
+    // everywhere.
+    const all = await fetchApp('/api/guard/logout-all', { method: 'POST', ...bearer(laptop.token) });
+    expect(all.status).toBe(200);
+    // Two live sessions were left: the laptop and the one `inviteAndSignup`
+    // minted. The phone was already ended, so it is not counted twice.
+    expect((await all.json()) as { revoked: number }).toMatchObject({ revoked: 2 });
+    expect((await fetchApp('/api/guard/sessions', bearer(laptop.token))).status).toBe(401);
+  });
+
+  it('refresh exchanges a live token for a fresh one; the old one is dead, a revoked one cannot refresh (02 §4)', async () => {
+    await bootGuard({ handles: { knowledge: new Database(':memory:'), search: new Database(':memory:') } }, RBAC_APP);
+    const owner = await unlockOwner();
+    const vic = await inviteAndSignup(owner, 'vic@home.test', 'VIEWER');
+    const laptop = await loginAs('vic@home.test', 'viewer-secret-1', 'laptop');
+
+    const refreshed = await fetchApp('/api/guard/session/refresh', { method: 'POST', ...bearer(laptop.token) });
+    expect(refreshed.status).toBe(200);
+    const next = ((await refreshed.json()) as { session: { token: string } }).session.token;
+    expect(next).not.toBe(laptop.token);
+    // The new token works, the exchanged one does not.
+    expect((await fetchApp('/api/guard/sessions', bearer(next))).status).toBe(200);
+    expect((await fetchApp('/api/guard/sessions', bearer(laptop.token))).status).toBe(401);
+    // The device keeps its name across the exchange.
+    const { sessions } = (await (await fetchApp('/api/guard/sessions', bearer(next))).json()) as {
+      sessions: { deviceLabel?: string; current: boolean }[];
+    };
+    expect(sessions.find((s) => s.current)?.deviceLabel).toBe('laptop');
+
+    // A role change revokes the target's sessions (§3) — so the denylist, not a
+    // special case in refresh, is what stops a role-changed session refreshing.
+    await fetchApp(`/api/guard/tenants/t_local/members/${vic.userId}`, {
+      method: 'PATCH',
+      headers: { authorization: `Bearer ${owner}`, 'content-type': 'application/json' },
+      body: JSON.stringify({ role: 'MEMBER' }),
+    });
+    expect((await fetchApp('/api/guard/session/refresh', { method: 'POST', ...bearer(next) })).status).toBe(401);
+
+    // And logout ends THIS device without needing private mode configured on.
+    const again = await loginAs('vic@home.test', 'viewer-secret-1', 'laptop');
+    expect((await fetchApp('/api/guard/logout', { method: 'POST', ...bearer(again.token) })).status).toBe(200);
+    expect((await fetchApp('/api/guard/sessions', bearer(again.token))).status).toBe(401);
+  });
+});
+
+/* ------------------------------------------------- the dev engine can BOOT */
+
+/**
+ * Until 03 §2c the dev engine was unbootable in any real app: `devDeps.snapshot`
+ * was REQUIRED, and the domain handles a snapshot must read are opened INSIDE
+ * `bootEngineApp` — so there was nothing a host could correctly pass. The
+ * migrator found it on the first real app (`plugin-app-info` → `dev.appRegistry`).
+ */
+describe('recipe — the dev engine boots with only a registry handle (03 §2c)', () => {
+  const DEV_APP = {
+    configVersion: 1,
+    app: { id: 'dev-boot', title: 'Dev Boot' },
+    profile: 'local',
+    engines: ['dev', 'knowledge'],
+    instances: [
+      { engine: 'dev', id: 'devtools', features: { appRegistry: true, dbAdmin: true } },
+      { engine: 'knowledge', id: 'notes', features: { notes: true } },
+    ],
+  };
+
+  const withDevApp = async (
+    run: (fetchApp: (p: string, init?: RequestInit) => Promise<Response>, root: string) => Promise<void>,
+  ): Promise<void> => {
+    const manifest = await buildManifest(DEV_APP);
+    const root = mkdtempSync(path.join(tmpdir(), 'cc-dev-boot-'));
+    const registry = new Database(':memory:');
+    assertCcPragmas(registry);
+    runNamespacedMigrations(registry, CC_REGISTRY_MIGRATIONS, { namespace: 'registry' });
+    // `ports` is a signed table and `DevService` verifies what it serves (05 §A5).
+    const portSigner = createRowSigner({
+      integrityKey: SecureKey.adopt(new Uint8Array(32).fill(9), 'recipe-spec-integrity'),
+    });
+    const devSigner = createSessionSigner({ ttlSeconds: 300 });
+
+    // No exec driver: `appRegistry`/`dbAdmin` shell out nowhere, and requiring
+    // one for them is what made this app unbootable.
+    const booted = bootEngineApp({
+      manifest,
+      root,
+      telemetry: countingTelemetry(),
+      signer: devSigner,
+      allowedOrigins: ['http://localhost:4747'],
+      meterSpillDrainIntervalMs: 0,
+      // Exactly what `createLocalDevServices` hands back — no snapshot, no root.
+      devDeps: { registry, portSigner },
+    });
+    const token = devSigner.mint({
+      tenantId: 't_local',
+      userId: 'u_local',
+      role: 'OWNER',
+      permissions: ['infra:write'],
+      privateScope: true,
+    }).token;
+    try {
+      await run(
+        (p, init = {}) =>
+          Promise.resolve(
+            booted.app.fetch(
+              new Request(`http://localhost${p}`, {
+                ...init,
+                headers: { authorization: `Bearer ${token}`, ...(init.headers ?? {}) },
+              }),
+            ),
+          ),
+        root,
+      );
+    } finally {
+      await booted.stop();
+      registry.close();
+      rmSync(root, { recursive: true, force: true });
+    }
+  };
+
+  it('serves the dev board with no ExecutionDriver wired', async () => {
+    await withDevApp(async (fetchApp) => {
+      expect((await fetchApp('/api/dev/health')).status).toBe(200);
+      const board = (await (await fetchApp('/api/dev/apps')).json()) as { success: boolean; apps: unknown[] };
+      // A truthful empty board — the registry is real and migrated, it just has
+      // no rows. That is not the same as a route that does not exist.
+      expect(board).toEqual({ success: true, apps: [] });
+    });
+  });
+
+  it('defaults the snapshot seam to VACUUM INTO over the handles it just opened', async () => {
+    await withDevApp(async (fetchApp, root) => {
+      const response = await fetchApp('/api/dev/db/knowledge/export', { method: 'POST' });
+      expect(response.status).toBe(200);
+      const { snapshotPath } = (await response.json()) as { snapshotPath: string };
+
+      // A real file, inside the defaulted root, that opens as a database — not a
+      // path string the service invented and never wrote.
+      expect(snapshotPath.startsWith(path.join(root, 'snapshots'))).toBe(true);
+      expect(existsSync(snapshotPath)).toBe(true);
+      const snapshot = new Database(snapshotPath, { readonly: true });
+      const tables = snapshot.query("SELECT name FROM sqlite_master WHERE type = 'table'").all() as { name: string }[];
+      expect(tables.some((t) => t.name === 'k_items')).toBe(true);
+      snapshot.close();
+    });
+  });
+
+  it('refuses a domain this app does not open, rather than snapshotting nothing', async () => {
+    await withDevApp(async (fetchApp) => {
+      // `media` is exportable in principle, but no active engine opens it here.
+      const response = await fetchApp('/api/dev/db/media/export', { method: 'POST' });
+      expect(response.status).toBe(404);
+      expect(((await response.json()) as { error?: { code?: string } }).error?.code).toBe('SNAPSHOT_DOMAIN_INACTIVE');
+    });
+  });
+});
+
+/* --------------------------- the five DEV views have a far side (03 §1e) --- */
+
+/**
+ * The claim 03 §1e's second half makes: `app-detail`, `docs`, `pipelines`,
+ * `screenshots` and `orchestration` were the last unbacked studio views, and the
+ * gap was a SERVER one — `dev.mixin.ts` mounted nothing behind any of them, so a
+ * shell would have been an affordance whose every use was a 404.
+ *
+ * These drive the composed server over real HTTP rather than calling the service,
+ * because the thing that was missing was the ROUTE. Both directions are asserted:
+ * a feature-on view answers, and a feature-off one does not exist (R-3).
+ */
+describe('recipe — the five DEV views answer over HTTP (03 §1e)', () => {
+  const DEV_SURFACES_APP = {
+    configVersion: 1,
+    app: { id: 'dev-surfaces', title: 'Dev Surfaces' },
+    profile: 'local',
+    engines: ['dev'],
+    instances: [
+      {
+        engine: 'dev',
+        id: 'devtools',
+        features: {
+          appRegistry: true,
+          docs: true,
+          pipelines: true,
+          orchestration: true,
+          // screenshots stays OFF — the R-3 half of the claim.
+          screenshots: false,
+        },
+      },
+    ],
+  };
+
+  const DEV_COMMANDS: Readonly<Record<string, ManifestCommand>> = {
+    'echo-ok': { id: 'echo-ok', argv: ['echo', 'ok'], cwdRoot: '/tmp' },
+    'sleep-short': {
+      id: 'sleep-short',
+      argv: ['sleep', '{seconds}'],
+      argSchema: { seconds: safeArgSchema() },
+      cwdRoot: '/tmp',
+    },
+  };
+
+  const withSurfaces = async (
+    run: (
+      fetchApp: (p: string, init?: RequestInit) => Promise<Response>,
+      context: { registry: Database; appRoot: string; jobResults: JobResultStore },
+    ) => Promise<void>,
+  ): Promise<void> => {
+    // `pipelines` declares a `shell` capability dep, so the host must actually
+    // offer one or V5 strips the feature (and with it the route).
+    const manifest = await buildManifest(DEV_SURFACES_APP, { shell: true });
+    const root = mkdtempSync(path.join(tmpdir(), 'cc-dev-surfaces-'));
+    const appRoot = path.join(root, 'registered-app');
+    mkdirSync(path.join(appRoot, 'docs'), { recursive: true });
+    writeFileSync(path.join(appRoot, 'README.md'), '# Registered\n');
+    writeFileSync(path.join(appRoot, '.env'), 'SECRET=nope\n');
+
+    const registry = new Database(':memory:');
+    assertCcPragmas(registry);
+    runNamespacedMigrations(registry, CC_REGISTRY_MIGRATIONS, { namespace: 'registry' });
+    registry
+      .query(
+        'INSERT INTO apps (app_id, kind, title, local_path, manifest, boot_pid) VALUES (?, ?, ?, ?, ?, ?)',
+      )
+      .run(
+        'registered',
+        'app',
+        'Registered App',
+        appRoot,
+        JSON.stringify({ schemaVersion: 1, app: { commands: { start: 'start' }, docs: ['README.md'] } }),
+        null,
+      );
+    // A REAL claim through the production write path — `ports` is signed, and
+    // `DevService` verifies every row it serves (05 §A5), so a literal 'sig'
+    // would (correctly) be refused as tampering.
+    const portSigner = createRowSigner({
+      integrityKey: SecureKey.adopt(new Uint8Array(32).fill(9), 'recipe-spec-integrity'),
+    });
+    claimPort(registry, 'registered', 3013, { signer: portSigner, probe: () => false, maxTries: 1 });
+
+    const jobResults = createMemoryJobResultStore();
+    await jobResults.record({ jobId: 'job_done', ok: true, tenantId: 't_local', at: '2026-07-25T10:00:00.000Z' });
+    await jobResults.record({ jobId: 'job_theirs', ok: true, tenantId: 't_other', at: '2026-07-25T11:00:00.000Z' });
+
+    const exec = createLocalExecutionDriver({
+      commands: DEV_COMMANDS,
+      spawn: createFakeSpawn(),
+      installSignalHooks: false,
+    });
+    const signer = createSessionSigner({ ttlSeconds: 300 });
+    const booted = bootEngineApp({
+      manifest,
+      root,
+      telemetry: countingTelemetry(),
+      signer,
+      allowedOrigins: ['http://localhost:4747'],
+      meterSpillDrainIntervalMs: 0,
+      exec,
+      jobResults,
+      devDeps: { registry, portSigner },
+    });
+    const token = signer.mint({
+      tenantId: 't_local',
+      userId: 'u_local',
+      role: 'OWNER',
+      permissions: ['infra:write'],
+      privateScope: true,
+    }).token;
+    try {
+      await run(
+        (p, init = {}) =>
+          Promise.resolve(
+            booted.app.fetch(
+              new Request(`http://localhost${p}`, {
+                ...init,
+                headers: { authorization: `Bearer ${token}`, ...(init.headers ?? {}) },
+              }),
+            ),
+          ),
+        { registry, appRoot, jobResults },
+      );
+    } finally {
+      await booted.stop();
+      exec.sweep();
+      registry.close();
+      rmSync(root, { recursive: true, force: true });
+    }
+  };
+
+  it('app-detail: one app in full, and a typed 404 for an id nobody registered', async () => {
+    await withSurfaces(async (fetchApp, { appRoot }) => {
+      const response = await fetchApp('/api/dev/apps/registered');
+      expect(response.status).toBe(200);
+      const { app } = (await response.json()) as { app: Record<string, unknown> };
+      expect(app.appId).toBe('registered');
+      expect(app.localPath).toBe(appRoot);
+      expect(app.ports).toEqual([3013]);
+      expect(app.docs).toEqual(['README.md']);
+
+      const missing = await fetchApp('/api/dev/apps/ghost');
+      expect(missing.status).toBe(404);
+      expect(((await missing.json()) as { error?: { code?: string } }).error?.code).toBe('APP_NOT_REGISTERED');
+    });
+  });
+
+  it('docs: lists the declared set, reads one, and refuses everything else', async () => {
+    await withSurfaces(async (fetchApp) => {
+      const listed = (await (await fetchApp('/api/dev/docs')).json()) as {
+        docs: { appId: string; appTitle: string; path: string }[];
+      };
+      expect(listed.docs).toEqual([{ appId: 'registered', appTitle: 'Registered App', path: 'README.md' }]);
+
+      const read = await fetchApp('/api/dev/docs/registered?path=README.md');
+      expect(read.status).toBe(200);
+      expect(((await read.json()) as { doc: { text: string } }).doc.text).toBe('# Registered\n');
+
+      // `.env` sits beside README.md INSIDE the app root, so a containment check
+      // that only asked "did it escape?" would have served it.
+      const env = await fetchApp('/api/dev/docs/registered?path=.env');
+      expect(env.status).toBe(404);
+      expect(((await env.json()) as { error?: { code?: string } }).error?.code).toBe('DOC_NOT_DECLARED');
+    });
+  });
+
+  it('pipelines: the whitelist and the run log, with a run through the OP', async () => {
+    await withSurfaces(async (fetchApp) => {
+      const { pipelines } = (await (await fetchApp('/api/dev/pipelines')).json()) as {
+        pipelines: { id: string; params: string[] }[];
+      };
+      expect(pipelines).toEqual([
+        { id: 'echo-ok', params: [] },
+        { id: 'sleep-short', params: ['seconds'] },
+      ]);
+      // No host paths reach the client: `pipelines` is not a privileged feature.
+      expect(JSON.stringify(pipelines)).not.toContain('/tmp');
+
+      const before = (await (await fetchApp('/api/dev/pipelines/runs')).json()) as { runs: unknown[] };
+      expect(before.runs).toEqual([]);
+
+      // Starting one is an OP — the V2 allowlist path, not a bespoke POST.
+      const started = await fetchApp('/api/instance/devtools/ops/run-pipeline', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ commandId: 'echo-ok', args: {} }),
+      });
+      expect(started.status).toBe(200);
+
+      const after = (await (await fetchApp('/api/dev/pipelines/runs')).json()) as {
+        runs: { commandId: string }[];
+      };
+      expect(after.runs.map((run) => run.commandId)).toEqual(['echo-ok']);
+    });
+  });
+
+  it('orchestration: the caller tenant’s job outcomes and nobody else’s', async () => {
+    await withSurfaces(async (fetchApp) => {
+      const { jobs } = (await (await fetchApp('/api/dev/jobs')).json()) as { jobs: { jobId: string }[] };
+      expect(jobs.map((job) => job.jobId)).toEqual(['job_done']);
+    });
+  });
+
+  it('a feature-off view has NO route at all, not a 403 (R-3)', async () => {
+    await withSurfaces(async (fetchApp) => {
+      // `screenshots: false`, so composition never mounted it. The distinction
+      // matters: a mounted-but-refusing route tells a caller the surface exists.
+      expect((await fetchApp('/api/dev/screenshots')).status).toBe(404);
+      expect((await fetchApp('/api/dev/screenshots/home.png/bytes')).status).toBe(404);
+    });
+  });
+});
+
+/**
+ * The `screenshots` surface with the LOCAL source wired — the one dev route that
+ * turns a URL segment into a file handle, so both halves of its containment are
+ * driven over real HTTP against a real directory.
+ */
+describe('recipe — screenshots over the local capture source (03 §1e)', () => {
+  const SHOTS_APP = {
+    configVersion: 1,
+    app: { id: 'dev-shots', title: 'Dev Shots' },
+    profile: 'local',
+    engines: ['dev'],
+    instances: [{ engine: 'dev', id: 'devtools', features: { screenshots: true } }],
+  };
+
+  const PNG = new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+  it('lists and serves a capture, and refuses anything the listing did not publish', async () => {
+    const manifest = await buildManifest(SHOTS_APP);
+    const root = mkdtempSync(path.join(tmpdir(), 'cc-dev-shots-'));
+    const shots = path.join(root, 'screenshots');
+    mkdirSync(shots, { recursive: true });
+    writeFileSync(path.join(shots, 'home.png'), PNG);
+    // Two files the source must NOT publish: a non-image, and a dotfile.
+    writeFileSync(path.join(shots, 'notes.txt'), 'not an image');
+    writeFileSync(path.join(shots, '.env'), 'SECRET=nope');
+
+    const registry = new Database(':memory:');
+    assertCcPragmas(registry);
+    runNamespacedMigrations(registry, CC_REGISTRY_MIGRATIONS, { namespace: 'registry' });
+    const dev = createLocalDevServices({ root, registryDb: registry, screenshotRoot: shots });
+    const signer = createSessionSigner({ ttlSeconds: 300 });
+    const booted = bootEngineApp({
+      manifest,
+      root,
+      telemetry: countingTelemetry(),
+      signer,
+      allowedOrigins: ['http://localhost:4747'],
+      meterSpillDrainIntervalMs: 0,
+      devDeps: dev.deps,
+    });
+    const token = signer.mint({
+      tenantId: 't_local',
+      userId: 'u_local',
+      role: 'OWNER',
+      permissions: ['infra:write'],
+      privateScope: true,
+    }).token;
+    const fetchApp = (p: string): Promise<Response> =>
+      Promise.resolve(
+        booted.app.fetch(new Request(`http://localhost${p}`, { headers: { authorization: `Bearer ${token}` } })),
+      );
+
+    try {
+      const { screenshots } = (await (await fetchApp('/api/dev/screenshots')).json()) as {
+        screenshots: { name: string; contentType: string; bytes: number }[];
+      };
+      // Only publishable extensions — a `.txt` and a dotfile in the same folder
+      // are not captures, and the source must never turn into a file server.
+      expect(screenshots.map((shot) => shot.name)).toEqual(['home.png']);
+      expect(screenshots[0]?.contentType).toBe('image/png');
+      expect(screenshots[0]?.bytes).toBe(PNG.byteLength);
+
+      const bytes = await fetchApp('/api/dev/screenshots/home.png/bytes');
+      expect(bytes.status).toBe(200);
+      expect(bytes.headers.get('content-type')).toBe('image/png');
+      expect(bytes.headers.get('x-content-type-options')).toBe('nosniff');
+      expect(new Uint8Array(await bytes.arrayBuffer())).toEqual(PNG);
+
+      // Not published ⇒ not readable, by either route shape.
+      expect((await fetchApp('/api/dev/screenshots/notes.txt/bytes')).status).toBe(404);
+      expect((await fetchApp(`/api/dev/screenshots/${encodeURIComponent('../.env')}/bytes`)).status).toBe(404);
+    } finally {
+      await booted.stop();
+      dev.close();
+      registry.close();
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});