cursedbelt 0.0.0 → 2.3.0

package/src/server/runtime/recipe.ts

@@ -0,0 +1,1527 @@
+/**
+ * The runtime recipe — ONE wiring point (spec 02 §2, the keystone).
+ *
+ * Before this file, `createCcRuntime` was invoked by tests and nothing else: a
+ * production entrypoint with no caller. The generated app (02 §1) is a ~30-line
+ * shell that calls `bootEngineApp` here; every real host — the generator's
+ * `server.ts` and the saas `worker.ts` — routes through this ONE tested library
+ * function rather than re-hand-wiring the tier N times into N subtly divergent
+ * hosts.
+ *
+ * This file is where the binding laws become MECHANICAL rather than aspirational:
+ *
+ *   * **Law #9 (wire both halves in one place).** The two standing footguns of
+ *     the refactor — search dual-wiring (read side to `createKnowledgeService`,
+ *     write side to `createCcRuntime`) and job-kind/handler drift — die here
+ *     structurally. The search provider is constructed ONCE and handed to every
+ *     consumer; the job-handler map is assembled beside the enqueueable-kind
+ *     inventory and reconciled by `assertJobKindsHandled` before anything serves.
+ *
+ *   * **Law #1 (no orphan seams).** A platform service the recipe does not
+ *     construct is visibly unreachable in review — this is the file where "does
+ *     anything call it?" has one answer to check.
+ *
+ *   * **Law #3 (boot-loud on wiring).** A missing driver for an effective AI
+ *     feature, a missing ObjectStore for an effective asset engine, or an
+ *     enqueueable job kind with no handler is a startup failure here, never a
+ *     500 (or a 202 into a void) on the first request that needs the piece.
+ *
+ * Construction order (there is NO cycle, despite appearances):
+ *   job handlers ── depend on storage/gateway/search only
+ *        └─► broker ── depends on the handler map
+ *              └─► engine services ── depend on the broker
+ *                    └─► createCcRuntime ── depends on services + broker + search
+ *
+ * `buildJobHandlers` (jobs seam) and `buildEngineServices` (services seam) are
+ * split so that ordering is honest: the spec sketched a single
+ * `buildEngineServices` returning both, but the broker sits between the two
+ * halves, so folding them into one call would have required either building the
+ * broker twice or passing a broker that did not yet know its own handlers. Two
+ * clearly-named seam functions, composed by `bootEngineApp`, is the faithful
+ * realization of law #9.
+ */
+import { Database } from 'bun:sqlite';
+import { mkdirSync } from 'node:fs';
+import path from 'node:path';
+import {
+  KNOWLEDGE_MIGRATIONS,
+  KNOWLEDGE_NAMESPACE,
+  MEDIA_MIGRATIONS,
+  MEDIA_NAMESPACE,
+  SEARCH_MIGRATIONS,
+  SEARCH_NAMESPACE,
+  STAGING_MIGRATIONS,
+  STAGING_NAMESPACE,
+  SYSTEM_MIGRATIONS,
+  SYSTEM_NAMESPACE,
+  LOCAL_TENANT_ID,
+  type DomainName,
+} from 'cwip/domains';
+import {
+  createFsObjectStore,
+  createLocalStorageProvider,
+  type AuditTrailSink,
+  type FsObjectStore,
+  type InterceptorPipeline,
+  type ObjectStore,
+  type StatementExecutor,
+  type StorageProvider,
+} from 'cwip/storage';
+import { createSqliteSearchProvider, type RebuildableSearchProvider } from 'cwip/search-provider';
+import {
+  assertCcPragmas,
+  createSqliteBackupService,
+  getTxnLifetimeGuard,
+  runNamespacedMigrations,
+  type NamespacedMigration,
+  type SqliteWritableDatabase,
+} from 'cwip/sqlite';
+import type { MeterUsageReader, TelemetryWriter } from 'cwip/telemetry';
+import type {
+  CognitiveDriver,
+  CognitiveGateway,
+  CognitiveProvider,
+  ExecutionDriver,
+  JobBroker,
+  JobHandler,
+  JobResultStore,
+  ModelConfig,
+} from '../drivers';
+import { createCognitiveGateway, createLocalJobBroker, createSqliteJobResultStore } from '../drivers';
+import { assertSaasHostWiring } from './saasHost';
+import {
+  createProviderDriver,
+  type DriverFactoryDeps,
+  PROVIDER_DEFAULT_ENDPOINT,
+  type ProviderCredentials,
+} from '../drivers/providers';
+import { createPlanEnforcer } from '../mixins/enforcement';
+import { AppError } from '../errors';
+import type { AsyncRevocationStore } from '../guard/revocationStore';
+import { createSessionSigner, type SessionSigner } from '../guard/sessionSigner';
+import type { BillingService } from '../mixins/billing.mixin';
+import type { PlanDefinition } from '../services/billingService';
+import type { GovernanceTier } from './governance';
+import type { EngineServices } from '../mixins/services';
+import { effectiveSignupMode } from '../../config/appConfig';
+import { createServerPushHub, DOMAIN_OWNER_ENGINE, type ServerPushHub } from '../stream';
+import {
+  createAssetJobHandlers,
+  createAccountService,
+  createAssetService,
+  createVaultMediaSource,
+  createDevJobHandlers,
+  createDevService,
+  createGuardService,
+  createKnowledgeJobHandlers,
+  createKnowledgeReindexSource,
+  createKnowledgeService,
+  createSearchJobHandlers,
+  createSystemService,
+  createVaultUploadReaper,
+  type AccountService,
+  type AssetServiceOptions,
+  type ConfigStore,
+  type VaultUploadReaper,
+  type DeployPlan,
+  type DiskUsageFn,
+  type ScreenshotSource,
+  type SnapshotFn,
+  type UnlockedIdentity,
+} from '../services';
+import type { CCUserClaims } from '../../core/session/claims';
+import type { RegistryIdentityStore, RegistrySecretsStore } from 'cwip/cc-registry';
+import type { RowSigner } from 'cwip/guard';
+import type { Argon2idDeriver, SecretEnvelopeManager } from 'cwip/guard';
+import { createCcRuntime, type CcRuntime, type CcRuntimeOptions } from './createCcRuntime';
+import type { EffectiveManifest } from '../../verify/types';
+
+// ---------------------------------------------------------------------------
+// Domain → migration chain table (the ONE place a domain becomes a schema).
+// ---------------------------------------------------------------------------
+
+interface DomainChain {
+  readonly namespace: string;
+  readonly migrations: readonly NamespacedMigration[];
+}
+
+/**
+ * What the recipe can hand a host-built search tier (04 §3).
+ *
+ * Both fields are absent when no `embedModel` was declared, and their absence is
+ * the signal: a provider built with no `embed` has no vector tier at all and
+ * `search_chunks` stays honestly empty, rather than filling with fabricated
+ * vectors that rank by noise.
+ */
+export interface SearchTierDeps {
+  /** Metered + telemetered through the app's ONE `CognitiveGateway`. */
+  embed?(text: string, tenantId: string): Promise<Float32Array>;
+  /** `provider:model` — recorded per chunk, and a query predicate. */
+  embedModel?: string;
+}
+
+/** A host-supplied search tier that wants the recipe's gateway-routed embedder. */
+export type SearchTierFactory = (deps: SearchTierDeps) => RebuildableSearchProvider;
+
+/**
+ * The SHARED billing meter (04 item 4e, owner decision D26 Option A) — ONE
+ * field, because it has TWO consumers that fail differently when only one is
+ * wired.
+ *
+ * `usage` is what `BillingService` counts; `executor` is what this node's rollup
+ * ships its own `meter_events` INTO. A deployment that wired the reader alone
+ * would read a table nothing fills — every tenant at zero usage, every ceiling
+ * admitting everything, no error anywhere. One that wired the rollup alone would
+ * ship faithfully into a table nothing reads. Neither is distinguishable from
+ * working without looking at an invoice, which is exactly why they are not two
+ * fields — the same lesson `host.governance` records.
+ *
+ * `createSaasHostServices({ …, meter: { nodeId } }).meter` builds it.
+ */
+export interface SharedMeterTier {
+  /** Every node's contribution, summed once, scoped to one tenant per read. */
+  readonly usage: MeterUsageReader;
+  /** The shared control-plane executor the per-node rollup writes through. */
+  readonly executor: StatementExecutor;
+  /** This node's identity — the key the rollup resumes from. Never defaulted. */
+  readonly nodeId: string;
+}
+
+/**
+ * Resolve `host.search` against a gateway — the ONE place a factory is called.
+ *
+ * Exported because there are TWO processes that build a handler map: this recipe
+ * (the API node) and the generated `worker.ts`. A worker that resolved the tier
+ * differently — or, as it did before 04 §3, not at all — would lease a `reindex`
+ * job off the shared queue and run the loud placeholder against it, so the job
+ * the API node enqueued would fail on the other side of Redis with an error
+ * about a seam the API node has. Both callers now go through this.
+ */
+export const resolveSearchTier = (
+  search: RebuildableSearchProvider | SearchTierFactory | undefined,
+  deps: { gateway: CognitiveGateway; embedModel?: ModelConfig },
+): RebuildableSearchProvider | undefined => {
+  if (search === undefined) return undefined;
+  if (typeof search !== 'function') return search;
+  const { embedModel } = deps;
+  return search(
+    embedModel
+      ? {
+          embed: (text: string, tenantId: string) => deps.gateway.embed({ text, model: embedModel, tenantId }),
+          embedModel: `${embedModel.provider}:${embedModel.model}`,
+        }
+      : {},
+  );
+};
+
+const DOMAIN_CHAINS: Readonly<Record<DomainName, DomainChain>> = Object.freeze({
+  knowledge: { namespace: KNOWLEDGE_NAMESPACE, migrations: KNOWLEDGE_MIGRATIONS },
+  media: { namespace: MEDIA_NAMESPACE, migrations: MEDIA_MIGRATIONS },
+  search: { namespace: SEARCH_NAMESPACE, migrations: SEARCH_MIGRATIONS },
+  system: { namespace: SYSTEM_NAMESPACE, migrations: SYSTEM_MIGRATIONS },
+  staging: { namespace: STAGING_NAMESPACE, migrations: STAGING_MIGRATIONS },
+});
+
+/**
+ * The domains a manifest's active engines own. `search` is owned by `knowledge`
+ * but only opened when search is actually consumed (default: `knowledge`
+ * active); `staging` is a dev sandbox never present in an export, so it is
+ * excluded unless a caller explicitly opts in.
+ */
+export function resolveManagedDomains(
+  manifest: EffectiveManifest,
+  options: { readonly enableSearch?: boolean; readonly includeStaging?: boolean } = {},
+): DomainName[] {
+  const engines = new Set<string>(manifest.engines);
+  const enableSearch = options.enableSearch ?? engines.has('knowledge');
+  const includeStaging = options.includeStaging ?? false;
+  return (Object.keys(DOMAIN_CHAINS) as DomainName[]).filter((domain) => {
+    if (!engines.has(DOMAIN_OWNER_ENGINE[domain])) return false;
+    if (domain === 'search') return enableSearch;
+    if (domain === 'staging') return includeStaging;
+    return true;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// 2a. openDomainHandles — the ONE place a path becomes a handle.
+// ---------------------------------------------------------------------------
+
+export interface OpenDomainHandlesOptions {
+  /**
+   * Where the per-domain SQLite files live (host-resolved, e.g. an
+   * `instances/<appId>/` directory under the host's own app-data root).
+   * Required unless every needed domain is supplied via `handles` — the
+   * library never invents a path from env (handle-injection law).
+   */
+  readonly root?: string;
+  /**
+   * Pre-opened handles injected by the host or a test (`:memory:` DBs). Pragmas
+   * and migrations are (idempotently) re-applied so an injected handle is
+   * indistinguishable from a freshly opened one.
+   */
+  readonly handles?: Partial<Record<DomainName, Database>>;
+  /** Override the domain set (defaults to {@link resolveManagedDomains}). */
+  readonly domains?: readonly DomainName[];
+  readonly enableSearch?: boolean;
+  readonly includeStaging?: boolean;
+  /** Seam for opening a file handle. Defaults to `new Database(path)`. */
+  readonly openDatabase?: (file: string) => Database;
+  /**
+   * Turn the CDC runtime auditor on (05 §A3) — the BELT to `cdcEmitSweep`'s
+   * braces. A committed write whose op emitted no `MutationRecord` throws
+   * `CDC_EMIT_MISSING` instead of silently starving search, audit, billing and
+   * the client cache.
+   *
+   * Off by default so production runs the byte-for-byte-unchanged path. The
+   * GENERATED app turns it on outside production, which is what law #10 asks
+   * for: CDC independence enforced in a real app, not only in six test suites.
+   */
+  readonly auditCdc?: boolean;
+  /**
+   * The aspect pipeline (05 §B2), threaded into the provider it hangs on. A
+   * host that registers interceptors and does NOT pass them here has registered
+   * nothing — the choke point is inside the provider, so the provider is the
+   * only thing that can invoke them.
+   */
+  readonly interceptors?: InterceptorPipeline;
+}
+
+export interface OpenedDomainHandles {
+  readonly storage: StorageProvider;
+  readonly handles: Partial<Record<DomainName, Database>>;
+  /** The search DB handle, present iff `search` was among the opened domains. */
+  readonly searchDb?: Database;
+  /** Close the handles this call OWNS (disposes txn guards first). */
+  close(): Promise<void>;
+}
+
+/**
+ * Open exactly the domain DBs the manifest's active engines own, apply the
+ * pragma profile and the namespaced migration chain per handle, and return the
+ * local `StorageProvider` built over them. The saas variant is a gated seam:
+ * until the dialect repositories (03 §2) can execute against Postgres, a saas
+ * profile must inject its own `StorageProvider` upstream (`bootEngineApp`'s
+ * `storage` option) rather than have this function open sockets it cannot yet
+ * run repositories through.
+ */
+export function openDomainHandles(manifest: EffectiveManifest, options: OpenDomainHandlesOptions = {}): OpenedDomainHandles {
+  if (manifest.profile === 'saas') {
+    throw new AppError(
+      'openDomainHandles builds the LOCAL sqlite provider only. Under saas, inject a StorageProvider built over the pooled connection (03 §2) via bootEngineApp({ storage }).',
+      { code: 'SAAS_STORAGE_UNWIRED', status: 500, isOperational: false, context: { profile: manifest.profile } },
+    );
+  }
+
+  const domains =
+    options.domains ??
+    resolveManagedDomains(manifest, { enableSearch: options.enableSearch, includeStaging: options.includeStaging });
+  const openDatabase = options.openDatabase ?? ((file: string) => new Database(file));
+
+  const handles: Partial<Record<DomainName, Database>> = {};
+  const owned: Database[] = [];
+  for (const domain of domains) {
+    const injected = options.handles?.[domain];
+    let db: Database;
+    if (injected) {
+      db = injected;
+    } else {
+      if (options.root === undefined)
+        throw new AppError(
+          `No root and no injected handle for domain "${domain}". A host resolves the storage root and passes it — the library never derives a path from env (handle-injection law).`,
+          { code: 'DOMAIN_ROOT_MISSING', status: 500, isOperational: false, context: { domain } },
+        );
+      db = openDatabase(path.join(options.root, `${domain}.db`));
+      owned.push(db);
+    }
+    assertCcPragmas(db);
+    const chain = DOMAIN_CHAINS[domain];
+    runNamespacedMigrations(db, chain.migrations, { namespace: chain.namespace });
+    handles[domain] = db;
+  }
+
+  const storage = createLocalStorageProvider({
+    handles,
+    ...(options.auditCdc ? { auditCdc: true } : {}),
+    ...(options.interceptors ? { interceptors: options.interceptors } : {}),
+  });
+  return {
+    storage,
+    handles,
+    searchDb: handles.search,
+    async close() {
+      // Only close what we opened — an injected handle stays the host's to close.
+      for (const db of owned) {
+        getTxnLifetimeGuard(db)?.dispose();
+        db.close();
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The job-kind ↔ handler inventory assert (closes audit G8 for every kind).
+// ---------------------------------------------------------------------------
+
+/**
+ * The kinds each engine's ops table + services can enqueue. Derived from
+ * `OP_JOB_KINDS` (`engineOps.ts`) plus the service-enqueued kinds (`organize`,
+ * `ocr`): asset ops enqueue media `reindex`/`transcode` and the service `ocr`;
+ * knowledge ops enqueue `reindex`/`import` and the service `organize`; dev ops
+ * enqueue `deploy`.
+ */
+const ENGINE_ENQUEUEABLE_KINDS: Readonly<Record<string, readonly string[]>> = Object.freeze({
+  asset: ['reindex', 'transcode', 'ocr'],
+  knowledge: ['reindex', 'organize', 'import'],
+  dev: ['deploy'],
+  guard: [],
+  system: [],
+});
+
+/** Every job kind the manifest's active engines can put on the broker. */
+export function enqueueableKindsFor(manifest: EffectiveManifest): string[] {
+  const kinds = new Set<string>();
+  for (const engine of manifest.engines) for (const kind of ENGINE_ENQUEUEABLE_KINDS[engine] ?? []) kinds.add(kind);
+  return [...kinds];
+}
+
+export interface AssertJobKindsHandledOptions {
+  readonly enqueueableKinds: readonly string[];
+  readonly handlers: Readonly<Record<string, JobHandler>>;
+}
+
+/**
+ * The boot assert (audit G8, forever): a kind the active surface can enqueue
+ * with no registered handler is a startup failure on BOTH the server and the
+ * saas worker — never a 202 into a void. `bootEngineApp` calls it before
+ * `createCcRuntime`; the generated `worker.ts` calls it against its own map.
+ */
+export function assertJobKindsHandled(options: AssertJobKindsHandledOptions): void {
+  const missing = options.enqueueableKinds.filter((kind) => !(kind in options.handlers));
+  if (missing.length > 0)
+    throw new AppError(
+      `Job kinds are enqueueable with no registered handler: ${missing.join(', ')}. A kind that can be enqueued must have a handler on both the server and the worker (law #9); register a real handler or an explicit unimplemented one — silent absence is banned.`,
+      { code: 'JOB_KIND_UNHANDLED', status: 500, isOperational: false, context: { missing } },
+    );
+}
+
+// ---------------------------------------------------------------------------
+// 2b (jobs half). buildJobHandlers — the merged handler map for every kind the
+// active surface can enqueue. Real handlers where they exist (reindex, organize),
+// explicit LOUD-failing handlers where the vertical is not yet built (03/04).
+// ---------------------------------------------------------------------------
+
+export interface BuildJobHandlersOptions {
+  readonly manifest: EffectiveManifest;
+  readonly storage: StorageProvider;
+  readonly gateway: CognitiveGateway;
+  /**
+   * The search provider (dual-wired) — enables the real `reindex` handler.
+   *
+   * Typed on the REBUILDABLE seam rather than on the SQLite class: the saas far
+   * side (`createPgSearchProvider`) satisfies the same contract, and a type that
+   * named one implementation structurally excluded the other from the one job
+   * that exists to drive it.
+   */
+  readonly search?: RebuildableSearchProvider;
+  /**
+   * The object store — present ⇒ the real asset `transcode`/`ocr` handlers (04
+   * §2d). Always resolved when the asset engine is active (boot fails with
+   * `OBJECT_STORE_MISSING` otherwise), so absence here means "no asset engine".
+   */
+  readonly objects?: ObjectStore;
+  /**
+   * The model the `organize` pass runs against. Present ⇒ the real handler;
+   * absent ⇒ an unimplemented handler (organize only enqueues under
+   * `aiOrganizer`, which is itself boot-gated by `buildDrivers` until 03 §1).
+   */
+  readonly jobModel?: ModelConfig;
+  readonly applyProposals?: boolean;
+  readonly reindexPageSize?: number;
+  /**
+   * The whitelisted execution driver — present ⇒ the real `deploy` handler
+   * (03 §4b). Absent ⇒ the loud-unimplemented placeholder, because a deploy with
+   * no driver has nothing to run.
+   */
+  readonly exec?: ExecutionDriver;
+  /** How a deploy of an app expands into ordered whitelisted steps (host wiring). */
+  readonly deployPlan?: DeployPlan;
+  /** Live progress channel for long jobs (deploy). The runtime's push hub. */
+  readonly push?: ServerPushHub;
+}
+
+export interface BuiltJobHandlers {
+  readonly handlers: Readonly<Record<string, JobHandler>>;
+  readonly enqueueableKinds: readonly string[];
+}
+
+/** A handler that fails a job LOUDLY for a kind whose vertical is not yet built. */
+function unimplementedHandler(kind: string, owner: string): JobHandler {
+  return () => {
+    throw new AppError(`Job kind "${kind}" is enqueueable but its handler is not yet implemented (${owner}).`, {
+      code: 'JOB_HANDLER_UNIMPLEMENTED',
+      status: 501,
+      isOperational: true,
+      context: { kind, owner },
+    });
+  };
+}
+
+export function buildJobHandlers(options: BuildJobHandlersOptions): BuiltJobHandlers {
+  const { manifest, storage, gateway, search } = options;
+  const engines = new Set<string>(manifest.engines);
+  const enqueueableKinds = enqueueableKindsFor(manifest);
+
+  const handlers: Record<string, JobHandler> = {};
+
+  // reindex — real when a search provider is wired (steady-state CDC indexing
+  // works regardless; this is the bulk rebuild path). Knowledge is the landed
+  // reindex source; media's is 04 §2, so a media reindex over this handler is a
+  // no-op until then (documented, not silent — the source list is explicit).
+  if ((engines.has('knowledge') || engines.has('asset')) && search) {
+    const sources = engines.has('knowledge') ? [createKnowledgeReindexSource(storage)] : [];
+    Object.assign(handlers, createSearchJobHandlers({ search, sources, pageSize: options.reindexPageSize }));
+  }
+
+  // organize — real when a model is wired; else loud-unimplemented.
+  if (engines.has('knowledge')) {
+    if (options.jobModel)
+      Object.assign(
+        handlers,
+        createKnowledgeJobHandlers({ storage, gateway, model: options.jobModel, applyProposals: options.applyProposals }),
+      );
+  }
+
+  // deploy — real when the dev engine has both an execution driver and a plan
+  // (03 §4b). Either missing ⇒ the loud placeholder below, never a silent no-op.
+  if (engines.has('dev') && options.exec && options.deployPlan) {
+    Object.assign(handlers, createDevJobHandlers({ exec: options.exec, plan: options.deployPlan, push: options.push }));
+  }
+
+  // transcode + ocr (04 §2d) — real whenever the asset engine is active, which
+  // guarantees an ObjectStore (boot fails OBJECT_STORE_MISSING without one). OCR
+  // feeds knowledge, so its sink is present only when that engine is too.
+  if (engines.has('asset') && options.objects) {
+    Object.assign(
+      handlers,
+      createAssetJobHandlers({
+        storage,
+        objects: options.objects,
+        gateway,
+        hasKnowledge: engines.has('knowledge'),
+        // OCR's optional titling pass reuses the app's job model when one is wired.
+        ocrModel: options.jobModel,
+      }),
+    );
+  }
+
+  // Every remaining enqueueable kind gets an explicit loud handler so a stray
+  // enqueue fails visibly in the job result rather than silently vanishing.
+  const ownerOf: Readonly<Record<string, string>> = {
+    reindex: 'search reindex needs a wired SearchProvider',
+    organize: 'knowledge organize needs a wired jobModel (03 §1 AI drivers)',
+    transcode: 'asset transcode handler — 04 §2',
+    ocr: 'asset ocr handler — 04 §2',
+    import: 'knowledge lists import handler — 04',
+    deploy: 'dev deploy needs an ExecutionDriver (exec) and a deployPlan wired (03 §4b)',
+  };
+  for (const kind of enqueueableKinds) if (!(kind in handlers)) handlers[kind] = unimplementedHandler(kind, ownerOf[kind] ?? 'not yet built');
+
+  return { handlers: Object.freeze(handlers), enqueueableKinds };
+}
+
+// ---------------------------------------------------------------------------
+// 2b (services half). buildEngineServices — one service per active engine.
+// ---------------------------------------------------------------------------
+
+/** Injected primitives the GuardEngine service needs (05 owns the data layer). */
+export interface GuardServiceDeps {
+  readonly manager: SecretEnvelopeManager;
+  readonly secrets: RegistrySecretsStore;
+  /**
+   * The opened identity store (handle injection — the host owns the registry db).
+   * When present and `resolveIdentity` is omitted, the recipe defaults the
+   * resolver from it via `AccountService` (02 §1b): the bootstrap OWNER under
+   * `local`. Under `saas` an explicit `resolveIdentity` is required (the account
+   * resolver needs a per-request session accessor the recipe cannot invent).
+   */
+  readonly identity?: RegistryIdentityStore;
+  /**
+   * The concrete `resolveIdentity` the guard service consumes. Optional now:
+   * omit it and pass `identity` to take the recipe's local default (02 §1b).
+   * An explicit resolver always wins (the saas account-backed resolver, or a test).
+   */
+  readonly resolveIdentity?: () => Promise<UnlockedIdentity | null>;
+  /**
+   * saas only: the verified claims of the in-flight request, for the account-backed
+   * `resolveIdentity` (02 §2). When `identity` is present and this is supplied, the
+   * recipe defaults the saas resolver from `AccountService` — no explicit
+   * `resolveIdentity` needed. The server sets this per request off the token the
+   * signer already verified.
+   */
+  readonly currentClaims?: () => CCUserClaims | null;
+  /**
+   * The argon2id deriver for the account service's password verifiers (02 §2).
+   * Omitted ⇒ the process-wide one registered at boot (`setArgon2idDeriver`).
+   */
+  readonly deriver?: Argon2idDeriver;
+  readonly onLocked?: (claims: unknown) => void;
+}
+
+/** What the recipe builds for the guard engine: the resolver + (when an identity store is wired) the account surface. */
+interface GuardIdentityWiring {
+  resolveIdentity: () => Promise<UnlockedIdentity | null>;
+  account?: AccountService;
+}
+
+/**
+ * Wire the guard engine's identity (02 §1b/§2): build ONE `AccountService` over
+ * the injected identity store (it backs both the `resolveIdentity` seam AND the
+ * mixin's login/signup/password routes), and pick the resolver:
+ *
+ *   - an explicit `deps.resolveIdentity` always wins (a test, or an exotic host);
+ *   - else default from the account service — the bootstrap OWNER under `local`,
+ *     or the request-session resolver under `saas` WHEN a `currentClaims` accessor
+ *     was supplied (the saas server sets it per request);
+ *   - else a boot failure (loud, not a silent "guard never turns on"): saas with
+ *     neither a resolver nor a session accessor cannot resolve anyone.
+ *
+ * When no identity store is wired at all, only an explicit resolver is possible
+ * (no account routes) — anything else is `GUARD_IDENTITY_UNWIRED`.
+ */
+function resolveGuardIdentity(
+  deps: GuardServiceDeps,
+  manifest: EffectiveManifest,
+  signer: SessionSigner,
+): GuardIdentityWiring {
+  const profile = manifest.profile;
+  if (deps.identity) {
+    const account = createAccountService({
+      identity: deps.identity,
+      profile,
+      signer,
+      currentClaims: deps.currentClaims,
+      deriver: deps.deriver,
+      // The launch gate (D33): the manifest's strictest configured value, so the
+      // service refuses what the config closed even for a caller that bypasses
+      // the mixin's own short-circuit.
+      signupMode: effectiveSignupMode(manifest.instances),
+    });
+    if (deps.resolveIdentity) return { resolveIdentity: deps.resolveIdentity, account };
+    if (profile === 'local' || deps.currentClaims) return { resolveIdentity: account.resolveIdentity, account };
+    // saas with an identity store but no way to read the request session, and no
+    // explicit resolver — the account routes exist but nobody can be resolved.
+    throw new AppError(
+      'The guard engine is active under saas with an identity store but no currentClaims accessor and no explicit resolveIdentity — the recipe cannot invent a per-request session accessor (02 §2).',
+      { code: 'GUARD_IDENTITY_UNWIRED', status: 500, isOperational: false, context: { profile } },
+    );
+  }
+  if (deps.resolveIdentity) return { resolveIdentity: deps.resolveIdentity };
+  throw new AppError(
+    'The guard engine is active but neither resolveIdentity nor an identity store was provided to guardDeps (02 §1b).',
+    { code: 'GUARD_IDENTITY_UNWIRED', status: 500, isOperational: false, context: { profile } },
+  );
+}
+
+/** Injected primitives the DevStudio service needs. */
+export interface DevServiceDeps {
+  readonly registry: SqliteWritableDatabase;
+  /**
+   * The row signer the registry's `ports` rows were written with (05 §A5).
+   *
+   * REQUIRED, like the handle beside it. `ports` is signed; the fleet board used
+   * to read it with a raw `SELECT` and would have rendered a row edited outside
+   * the app without tripping `SECURITY_INTEGRITY_VIOLATION`. `createLocalDevServices`
+   * builds it from the SAME persisted machine key the guard and telemetry tiers
+   * sign with, so a host that uses the local seam supplies nothing.
+   */
+  readonly portSigner: RowSigner;
+  /**
+   * Where `exportDatabase` writes snapshots. OPTIONAL since 03 §2c: the recipe
+   * defaults it to `<root>/snapshots`, because a host that does not own the
+   * domain files cannot name a better directory than the one the recipe just
+   * opened them from.
+   */
+  readonly snapshotRoot?: string;
+  /**
+   * How a domain database becomes a snapshot file. OPTIONAL since 03 §2c: when
+   * the recipe opened the domain handles itself (every local app), it defaults
+   * this to `VACUUM INTO` over the handle it already holds.
+   *
+   * It has to default, or the dev engine is unbootable in practice. `devDeps` is
+   * an INPUT to `bootEngineApp`, and the handles a snapshot must read are opened
+   * INSIDE it — so a host wiring this by hand would have to re-derive the active
+   * domain set and open a second connection per file, which is two write locks
+   * on one WAL database and a second txn-lifetime guard fighting the first. A
+   * host that genuinely owns its files (it injected `storage`/`handles`) still
+   * supplies both fields, and must: there is nothing for the recipe to default
+   * from.
+   */
+  readonly snapshot?: SnapshotFn;
+  readonly config?: ConfigStore;
+  readonly diskUsage?: DiskUsageFn;
+  readonly isProcessAlive?: (pid: number) => boolean;
+  /**
+   * Where the `screenshots` surface reads captures from (03 §1e). A host
+   * decision — a library cannot know which directory or bucket an operator's
+   * captures live in. Absent with the feature on ⇒ the route answers a typed
+   * `SCREENSHOT_SOURCE_MISSING` 501 naming the wiring, never an empty gallery
+   * that reads as "nothing captured yet".
+   */
+  readonly screenshots?: ScreenshotSource;
+  /**
+   * How a deploy of an app expands into ordered whitelisted steps (03 §4b).
+   * Present (with an `exec` driver) ⇒ the real `deploy` job handler; absent ⇒ the
+   * loud-unimplemented placeholder. The framework knows how to RUN a pipeline,
+   * not which commands make up a given app's deploy — that is host wiring.
+   */
+  readonly deployPlan?: DeployPlan;
+}
+
+export interface BuildEngineServicesOptions {
+  readonly manifest: EffectiveManifest;
+  readonly storage: StorageProvider;
+  readonly broker: JobBroker;
+  readonly telemetry: TelemetryWriter;
+  /** Required iff `asset` is active. */
+  readonly objects?: ObjectStore;
+  /** Verifier for local-signed object URLs (fs store). */
+  readonly verifySignedUrl?: (claim: { key: string; expiresAt: number; signature: string }) => boolean;
+  /** Read-side search (same instance the runtime taps for the write side). */
+  readonly search?: RebuildableSearchProvider;
+  /** The session signer — the SAME instance `createCcRuntime` verifies with. */
+  readonly signer: SessionSigner;
+  /** Required iff `guard` is active. */
+  readonly guardDeps?: GuardServiceDeps;
+  /** Required iff `dev` is active. */
+  readonly devDeps?: DevServiceDeps;
+  /**
+   * The domain handles the caller opened, so an unwired `devDeps.snapshot` can
+   * default to `VACUUM INTO` over them. Absent (an injected `StorageProvider`)
+   * means the host owns its files and must supply the snapshot seam itself.
+   */
+  readonly domainHandles?: Partial<Record<DomainName, Database>>;
+  /** Default `devDeps.snapshotRoot` — the recipe passes `<root>/snapshots`. */
+  readonly snapshotRoot?: string;
+  /**
+   * The SAME execution driver `composeServer` puts on the dev mixin context.
+   * `DevService.pipelines` lists this driver's whitelist and run log, so handing
+   * it a second instance would show a vocabulary nothing runs from.
+   */
+  readonly exec?: ExecutionDriver;
+  /**
+   * The durable job-result store the broker records into — the `orchestration`
+   * surface's read side. The recipe constructs it beside the local broker and
+   * passes the same instance to both.
+   */
+  readonly jobResults?: JobResultStore;
+  readonly mintId?: () => string;
+  /** Reported when an object the vault meant to reclaim survived (05 §A2). */
+  readonly onOrphanedObject?: AssetServiceOptions['onOrphanedObject'];
+}
+
+/**
+ * `VACUUM INTO` over the handle the recipe already holds (01 §6.1). Copying a
+ * live `.db` with a `-wal` beside it silently loses the most recent committed
+ * transactions, which is why a file copy is a V6 ERROR and this is the only
+ * snapshot path.
+ */
+function defaultSnapshotFn(handles: Partial<Record<DomainName, Database>>): SnapshotFn {
+  const backups = createSqliteBackupService();
+  return (domain: string, destination: string) => {
+    const db = handles[domain as DomainName];
+    if (!db)
+      throw new AppError(`Cannot snapshot domain "${domain}": this app's active engines do not open it.`, {
+        code: 'SNAPSHOT_DOMAIN_INACTIVE',
+        status: 404,
+        context: { domain },
+      });
+    // The snapshot root is a defaulted path, so nothing has created it yet — and
+    // `VACUUM INTO` reports a missing directory as an opaque "unable to open
+    // database file" against the DESTINATION, which reads like source corruption.
+    mkdirSync(path.dirname(destination), { recursive: true });
+    backups.snapshot(db as unknown as SqliteWritableDatabase, destination, { overwrite: true });
+  };
+}
+
+function requireDeps<T>(value: T | undefined, engine: string, code: string): T {
+  if (value === undefined)
+    throw new AppError(`The "${engine}" engine is active but its injected dependencies were not provided to buildEngineServices.`, {
+      code,
+      status: 500,
+      isOperational: false,
+      context: { engine },
+    });
+  return value;
+}
+
+/**
+ * Construct each active engine's service. Absent engines get no service;
+ * `composeServer` throws on a required missing one (boot-loud). The search
+ * provider passed here is the READ side — the SAME instance must reach
+ * `createCcRuntime` for the write tap, which `bootEngineApp` guarantees by
+ * threading one value to both.
+ */
+export function buildEngineServices(options: BuildEngineServicesOptions): EngineServices {
+  const { manifest, storage, broker, telemetry } = options;
+  const engines = new Set<string>(manifest.engines);
+  const services: EngineServices = {};
+
+  if (engines.has('asset'))
+    services.asset = createAssetService({
+      storage,
+      objects: requireDeps(options.objects, 'asset', 'OBJECT_STORE_MISSING'),
+      broker,
+      telemetry,
+      verifySignedUrl: options.verifySignedUrl,
+      mintId: options.mintId,
+      onOrphanedObject: options.onOrphanedObject,
+      // Register the vault as an extra source so its `mv_assets` appear through
+      // the asset engine (§2b) — AssetStudio then replaces Media Vault.
+      sources: manifestHasVaultSource(manifest) ? [createVaultMediaSource(storage)] : undefined,
+    });
+
+  if (engines.has('knowledge')) services.knowledge = createKnowledgeService({ storage, broker, search: options.search });
+
+  if (engines.has('system')) services.system = createSystemService({ storage });
+
+  if (engines.has('guard')) {
+    const deps = requireDeps(options.guardDeps, 'guard', 'GUARD_DEPS_MISSING');
+    const wiring = resolveGuardIdentity(deps, manifest, options.signer);
+    services.guard = createGuardService({
+      manager: deps.manager,
+      secrets: deps.secrets,
+      signer: options.signer,
+      appId: manifest.appId,
+      resolveIdentity: wiring.resolveIdentity,
+      onLocked: deps.onLocked,
+    });
+    // The account surface backs the guard mixin's login/signup/password routes
+    // (02 §2). Present only when an identity store was wired.
+    services.account = wiring.account;
+  }
+
+  if (engines.has('dev')) {
+    const deps = requireDeps(options.devDeps, 'dev', 'DEV_DEPS_MISSING');
+    const snapshotRoot = deps.snapshotRoot ?? options.snapshotRoot;
+    const snapshot = deps.snapshot ?? (options.domainHandles ? defaultSnapshotFn(options.domainHandles) : undefined);
+    if (snapshotRoot === undefined || snapshot === undefined)
+      throw new AppError(
+        'The dev engine is active but its snapshot seam is unwired: no devDeps.snapshot/snapshotRoot, and the caller injected its own StorageProvider so there are no handles to default from.',
+        { code: 'DEV_SNAPSHOT_UNWIRED', status: 500, isOperational: false, context: { engine: 'dev' } },
+      );
+    services.dev = createDevService({
+      registry: deps.registry,
+      portSigner: deps.portSigner,
+      broker,
+      snapshotRoot,
+      snapshot,
+      config: deps.config,
+      diskUsage: deps.diskUsage,
+      isProcessAlive: deps.isProcessAlive,
+      // The three 03 §1e read-side seams. Each is optional here and required by
+      // its own feature at request time: the service throws a typed 501 naming
+      // the missing wiring rather than answering an empty list, so "the surface
+      // is unwired" and "nothing has happened yet" stay different screens.
+      exec: options.exec,
+      jobResults: options.jobResults,
+      screenshots: deps.screenshots,
+    });
+  }
+
+  return services;
+}
+
+// ---------------------------------------------------------------------------
+// 2c. buildDrivers — declared providers → constructed drivers + CSP endpoints,
+// with the AI boot gate (mirror of assertArgon2idReady).
+// ---------------------------------------------------------------------------
+
+/** Effective feature keys that require an AI driver to run at all. */
+const AI_FEATURE_KEYS: ReadonlySet<string> = new Set([
+  'aiOrganizer',
+  'ragChat',
+  'ragDiskIndexing',
+  'oralHistory',
+  'imageStudio',
+]);
+
+export interface BuildDriversOptions {
+  /**
+   * Providers this app declares, with the credentials the HOST resolved from
+   * GuardEngine secrets (a driver never reads env). Each is constructed through
+   * the provider registry, and its endpoint joins the CSP allowlist — which is
+   * the reason to declare rather than hand-construct: a hand-built driver's
+   * endpoint is invisible to the export moment.
+   */
+  readonly providers?: Readonly<Partial<Record<CognitiveProvider, ProviderCredentials>>>;
+  /** Dependencies the registry injects into constructed drivers (ObjectStore, fetch). */
+  readonly deps?: DriverFactoryDeps;
+  /**
+   * Pre-constructed drivers keyed by provider. Wins over `providers` for the
+   * same key — the seam a test fakes and a host with an exotic provider uses.
+   */
+  readonly drivers?: Readonly<Partial<Record<CognitiveProvider, CognitiveDriver>>>;
+  /** Extra declared model endpoints — folded into V2's `cspConnectAllowlist` at export. */
+  readonly modelEndpoints?: readonly string[];
+  /**
+   * Providers the manifest's configured models actually name (e.g. the
+   * `jobModel`'s). Each MUST resolve to a driver: an app whose configured model
+   * points at a provider nobody wired is broken at boot, and finding that out on
+   * the first organize job — hours later, on an unattended machine — is exactly
+   * the failure mode this gate exists to convert into a startup crash.
+   */
+  readonly requiredProviders?: readonly CognitiveProvider[];
+}
+
+export interface BuiltDrivers {
+  readonly drivers: Readonly<Partial<Record<CognitiveProvider, CognitiveDriver>>>;
+  /** Endpoints the export moment adds to `cspConnectAllowlist` (02 §2c). */
+  readonly cspEndpoints: readonly string[];
+}
+
+/**
+ * Whether any effective feature in the manifest needs a cognitive driver.
+ *
+ * Note the interaction with capability downgrade, because it decides which of two
+ * behaviors an app gets: when the boot probe reports no AI provider, verification
+ * downgrades AI features to effective-OFF, so their routes are never composed and
+ * this returns false — a missing local model takes the AI SURFACE away rather than
+ * taking the app down. The gate below therefore fires exactly when an effective AI
+ * feature SURVIVES with no driver behind it (a last-good bundle compiled on a
+ * capable machine, or an explicitly configured model), which is the case where
+ * serving would mean shipping a route with nothing behind it.
+ */
+export function manifestNeedsAi(manifest: EffectiveManifest): boolean {
+  return manifest.instances.some((instance) =>
+    Object.entries(instance.effective).some(([key, value]) => AI_FEATURE_KEYS.has(key) && value === true),
+  );
+}
+
+/**
+ * Whether any asset instance has the `vaultSource` feature effective-on — the
+ * signal to register the content-addressed vault as an AssetService source (04
+ * §2b), which is what lets AssetStudio replace `plugin-media-vault`. Absent ⇒ the
+ * asset service is the file catalogue alone, exactly as before.
+ */
+export function manifestHasVaultSource(manifest: EffectiveManifest): boolean {
+  return manifest.instances.some((instance) => instance.engine === 'asset' && instance.effective.vaultSource === true);
+}
+
+export function buildDrivers(manifest: EffectiveManifest, options: BuildDriversOptions = {}): BuiltDrivers {
+  const declared = options.providers ?? {};
+  const drivers: Partial<Record<CognitiveProvider, CognitiveDriver>> = {};
+  const cspEndpoints = new Set<string>(options.modelEndpoints ?? []);
+
+  for (const [provider, credentials] of Object.entries(declared) as [CognitiveProvider, ProviderCredentials][]) {
+    // Construction throws AI_DRIVER_UNAVAILABLE for a missing key or a missing
+    // ObjectStore — at boot, naming the piece, rather than at first request.
+    drivers[provider] = createProviderDriver(provider, credentials, options.deps);
+    cspEndpoints.add(credentials.endpoint ?? PROVIDER_DEFAULT_ENDPOINT[provider]);
+  }
+  // Explicit drivers win: a host that constructed one itself meant it.
+  Object.assign(drivers, options.drivers ?? {});
+
+  if (manifestNeedsAi(manifest) && Object.keys(drivers).length === 0)
+    throw new AppError(
+      'The manifest has an effective AI feature but no cognitive driver is wired. Declare a provider (host.ts `providers`) or pass a constructed driver — an AI feature with no driver is a boot failure, not a first-request 503.',
+      { code: 'AI_DRIVER_UNAVAILABLE', status: 500, isOperational: false, context: { profile: manifest.profile } },
+    );
+
+  const unwired = [...new Set(options.requiredProviders ?? [])].filter((provider) => !drivers[provider]);
+  if (unwired.length > 0)
+    throw new AppError(
+      `Configured models name cognitive providers with no driver: ${unwired.join(', ')}. Declare each provider in host.ts, or stop configuring a model against it.`,
+      {
+        code: 'AI_DRIVER_UNAVAILABLE',
+        status: 500,
+        isOperational: false,
+        context: { profile: manifest.profile, unwired },
+      },
+    );
+
+  return { drivers, cspEndpoints: [...cspEndpoints] };
+}
+
+// ---------------------------------------------------------------------------
+// 2d. bootEngineApp — the composition the generated server.ts calls.
+// ---------------------------------------------------------------------------
+
+export interface BootEngineAppOptions {
+  readonly manifest: EffectiveManifest;
+
+  // ── storage ────────────────────────────────────────────────────────────
+  /** Domain DB root (host-resolved). Required for the file path unless `handles`/`storage` supplied. */
+  readonly root?: string;
+  /** Pre-opened domain handles (tests / a host that owns the files). */
+  readonly handles?: Partial<Record<DomainName, Database>>;
+  /** Inject a fully-built StorageProvider (the required path under saas until 03 §2). */
+  readonly storage?: StorageProvider;
+  /** Force search on/off. Default: `knowledge` engine active. */
+  readonly enableSearch?: boolean;
+  /**
+   * Turn the CDC runtime auditor on (05 §A3). The generated `server.ts` passes
+   * `process.env.NODE_ENV !== 'production'`, so a dev-mode app throws
+   * `CDC_EMIT_MISSING` on a forgotten emit at RUNTIME — the belt law #10 asks
+   * for, which until now ran in six test suites and no real app. Ignored when a
+   * `storage` provider is injected: that provider was built by the host, and the
+   * auditor is a property of how it was constructed.
+   */
+  readonly auditCdc?: boolean;
+  /**
+   * The aspect pipeline (05 §B2). Threaded into the local provider this recipe
+   * builds; IGNORED when a `storage` provider is injected, for the same reason
+   * `auditCdc` is — that provider was constructed by the host, and the pipeline
+   * is a property of how it was constructed. A saas host passes its pipeline to
+   * `createSaasStorageProvider` directly.
+   *
+   * The STATIC half rides `resolveBootManifest({ interceptors })`, which folds
+   * the same registry's edges into the V4 cycle audit — so a cyclic pair of
+   * hooks is a boot failure rather than a runaway transaction in production.
+   */
+  readonly interceptors?: InterceptorPipeline;
+  /**
+   * The audit trail's READ side (D25) — `createGovernanceTier(…).auditTrail`.
+   *
+   * Separate from {@link interceptors} because the two halves genuinely go to
+   * different places: the pipeline is a property of the storage provider, and
+   * this is a route. Passing the pipeline and forgetting this is the state the
+   * previous landing shipped in — a trail written continuously that nothing
+   * could read — so the generated `server.ts` passes both from one tier.
+   *
+   * Mounted on the guard mixin (`GET /api/guard/audit`, `infra:write`), which
+   * means an app with no guard engine records a trail it cannot serve. That is
+   * the right failure: the read is the most sensitive one in the product and
+   * there is no other engine that authenticates.
+   */
+  readonly auditTrail?: AuditTrailSink;
+  /**
+   * The site-copy store's executor (D36) — where marketing-copy overrides
+   * persist. The generated local server passes its governance executor (one
+   * more table in the same control-plane-ish file); a saas host passes the
+   * pooled control-plane executor whose schema `ensureSaasControlPlaneSchema`
+   * already creates. Absent ⇒ the `/api/guard/site-copy*` routes do not mount,
+   * even with the feature on — same presence rule as {@link auditTrail}.
+   */
+  readonly siteCopy?: StatementExecutor;
+
+  // ── object store ────────────────────────────────────────────────────────
+  /** Inject the ObjectStore. Default (local): a signed-URL fs store under `objectStoreRoot`. */
+  readonly objects?: ObjectStore;
+  readonly objectStoreRoot?: string;
+  readonly objectStoreSigningKey?: string | Uint8Array;
+
+  // ── security / identity ──────────────────────────────────────────────────
+  /** The per-request verifier + session signer. Default: `createSessionSigner()`. */
+  readonly signer?: SessionSigner;
+  readonly sessionTtlSeconds?: number;
+  /**
+   * The cross-node revocation denylist (03 §4a). Under saas a `lock()` on one
+   * node must close the token on every node, so a host injects the shared store
+   * (Redis or the shared Postgres) here and the default signer writes through to
+   * it. Local leaves it undefined — one process, one Map is enough. Ignored when
+   * a fully-built `signer` is injected (that signer owns its own store).
+   */
+  readonly revocationStore?: AsyncRevocationStore;
+  readonly guardDeps?: GuardServiceDeps;
+  readonly devDeps?: DevServiceDeps;
+
+  // ── drivers / AI ─────────────────────────────────────────────────────────
+  /** Declared providers + host-resolved credentials; constructed by the registry (03 §1d). */
+  readonly providers?: Readonly<Partial<Record<CognitiveProvider, ProviderCredentials>>>;
+  /** Pre-constructed drivers. Win over `providers` for the same key. */
+  readonly drivers?: Readonly<Partial<Record<CognitiveProvider, CognitiveDriver>>>;
+  readonly modelEndpoints?: readonly string[];
+  readonly jobModel?: ModelConfig;
+  /**
+   * The embedding model backing `SearchProvider.embed` — the vector half of the
+   * search tier. Present ⇒ the search provider gets a real embedder routed
+   * through the gateway (so embedding calls are metered and telemetered like any
+   * other AI call); absent ⇒ `embed` stays absent, which is what keeps
+   * `search_chunks` honestly empty rather than full of fake vectors.
+   */
+  readonly embedModel?: ModelConfig;
+  /**
+   * Inject a fully-built search tier — the required path under saas (04 §3).
+   *
+   * The recipe can BUILD one only on the local profile, because the SQLite
+   * provider needs a `search.db` handle and a host that injects `storage` opens
+   * no handles at all. So a saas deployment constructs
+   * `createPgSearchProvider` (through `createSaasHostServices`) and passes it
+   * here, and {@link reportSaasHostWiring} refuses a saas app with the knowledge
+   * engine active and no search tier — because the alternative is not "no
+   * search", it is a `reindex` job that fails on every run and a search box that
+   * silently falls back to `LIKE`.
+   *
+   * Wins over the recipe's own construction when both are possible, so a local
+   * app can also substitute one.
+   *
+   * **Pass a FACTORY when you want the vector tier metered.** The embedder has to
+   * route through the `CognitiveGateway` — that is what makes an embedding call
+   * billable and telemetered like any other AI call — and the gateway is
+   * constructed by this function, after a host has already run. A host that
+   * built its own embedder to get around that would have a second, unmetered AI
+   * path, which is the exact hole `METERED_CALLS` exists to close. So the recipe
+   * hands the factory the gateway-routed `embed` (present iff `embedModel` was
+   * declared) and the host decides what to do with it.
+   */
+  readonly search?: RebuildableSearchProvider | SearchTierFactory;
+  readonly applyProposals?: boolean;
+
+  // ── jobs ──────────────────────────────────────────────────────────────────
+  /** Inject a broker. Default (local): `createLocalJobBroker` over `jobsDb`. */
+  readonly broker?: JobBroker;
+  /** The bun:sqlite handle backing the default local broker's queue. */
+  readonly jobsDb?: Database;
+  /**
+   * The durable outcome store. Defaulted (local) to a SQLite store over
+   * `jobsDb`, which the recipe hands to BOTH the broker and the dev engine's
+   * `orchestration` surface. A host that injects its own `broker` must pass the
+   * store that broker records into, or the surface has nothing to read.
+   */
+  readonly jobResults?: JobResultStore;
+
+  // ── platform seams ─────────────────────────────────────────────────────────
+  readonly telemetry: TelemetryWriter;
+  readonly exec?: ExecutionDriver;
+  readonly billing?: BillingService;
+  /**
+   * The SHARED cross-node billing meter (04 item 4e, owner decision D26).
+   *
+   * Declared here and CONSUMED HERE only by `assertSaasHostWiring`, which
+   * refuses a saas boot without it — deliberately, and worth saying plainly
+   * because an option a function ignores is normally a smell. The tier's two
+   * products go to the generated `server.ts` (the rollup needs the node's own
+   * telemetry HANDLE, which `createLocalHostServices` owns and this recipe is
+   * never given; billing is built there for exactly the same reason). What the
+   * recipe can do is make its ABSENCE loud, because the failure it prevents is
+   * silent: without a shared meter, `BillingService` counts one node's
+   * `meter_events` and every plan ceiling is enforced once per node.
+   */
+  readonly meter?: SharedMeterTier;
+  readonly allowedOrigins: readonly string[];
+  readonly meterSpillDrainIntervalMs?: number;
+  readonly onSearchIndexError?: CcRuntimeOptions['onSearchIndexError'];
+  readonly mintId?: () => string;
+  /**
+   * The stale-upload reaper (05 §A2), started whenever an asset instance has
+   * `vaultSource` effective-on.
+   *
+   * `tenants` is the ONE thing the recipe cannot decide under saas: enumerating
+   * tenants is an unscoped read, which RLS forbids by design. Under the LOCAL
+   * profile the recipe supplies `[LOCAL_TENANT_ID]` — a fact about that profile,
+   * not a guess — so a local host passes nothing. Under saas, a vault app that
+   * wires no `tenants` is refused at boot (`VAULT_REAPER_UNWIRED`): shipping a
+   * multi-tenant vault with no reaper is how the leak this closes came back.
+   */
+  readonly vaultReaper?: {
+    readonly tenants?: () => readonly string[] | Promise<readonly string[]>;
+    readonly intervalMs?: number;
+    readonly olderThanMs?: number;
+    readonly limit?: number;
+    readonly onError?: (error: unknown, tenantId: string) => void;
+  };
+  /** Reported when an object the vault meant to reclaim survived (05 §A2). */
+  readonly onOrphanedObject?: AssetServiceOptions['onOrphanedObject'];
+}
+
+export interface BootedEngineApp extends CcRuntime {
+  /** The drivers boot-gate resolved (for a worker sharing the same wiring). */
+  readonly drivers: Readonly<Partial<Record<CognitiveProvider, CognitiveDriver>>>;
+  /** The merged job-handler map — the worker entrypoint reuses it. */
+  readonly jobHandlers: Readonly<Record<string, JobHandler>>;
+}
+
+/**
+ * Compose an EffectiveManifest into a running runtime. The one audited file
+ * where every seam is wired; a new platform service that this function does not
+ * construct is visibly unreachable (law #1).
+ */
+export function bootEngineApp(options: BootEngineAppOptions): BootedEngineApp {
+  const { manifest, telemetry } = options;
+  const engines = new Set<string>(manifest.engines);
+  const enableSearch = options.enableSearch ?? engines.has('knowledge');
+
+  // ── the saas readiness gate (04 §1c) ───────────────────────────────────────
+  // FIRST, and all at once. Each of these seams fails on its own eventually,
+  // but they used to fail one per boot attempt — and the last two only when a
+  // request reached them, which under saas meant in front of a user rather than
+  // in front of a deploy. A no-op under the local profile.
+  assertSaasHostWiring({ manifest, host: options });
+
+  // ── storage (2a) ─────────────────────────────────────────────────────────
+  let storage: StorageProvider;
+  let searchDb: Database | undefined;
+  let closeHandles: (() => Promise<void>) | undefined;
+  // Kept so the dev engine's snapshot seam can VACUUM INTO the handles this
+  // call already holds instead of a host opening a second connection per file.
+  let domainHandles: Partial<Record<DomainName, Database>> | undefined;
+  if (options.storage) {
+    storage = options.storage;
+  } else {
+    const opened = openDomainHandles(manifest, {
+      root: options.root,
+      handles: options.handles,
+      enableSearch,
+      ...(options.auditCdc ? { auditCdc: true } : {}),
+      ...(options.interceptors ? { interceptors: options.interceptors } : {}),
+    });
+    storage = opened.storage;
+    searchDb = opened.searchDb;
+    closeHandles = opened.close;
+    domainHandles = opened.handles;
+  }
+
+  // ── object store (2d) ──────────────────────────────────────────────────────
+  let objects: ObjectStore | undefined = options.objects;
+  let verifySignedUrl: BuildEngineServicesOptions['verifySignedUrl'];
+  /**
+   * An INJECTED store that carries its own verifier (the fs store exposes
+   * `verifySignedUrl` on the store precisely so signer and verifier can never
+   * disagree about the key) gets that verifier wired automatically. Without
+   * this, a host that injects `createFsObjectStore(...)` — the single-box saas
+   * shape, D34 = A — passed the `objects` boot gate and then silently lost the
+   * object-serving route: `readSignedObject` only exists when a verifier is
+   * present, so every URL the store signed 404'd. An S3 store exposes no
+   * verifier (its presigned URLs never reach the app), so this stays unset
+   * there, exactly as before.
+   */
+  if (objects !== undefined) {
+    const injectedVerifier = (objects as Partial<Pick<FsObjectStore, 'verifySignedUrl'>>).verifySignedUrl;
+    if (typeof injectedVerifier === 'function') verifySignedUrl = injectedVerifier.bind(objects);
+  }
+  if (!objects && engines.has('asset') && manifest.profile === 'local') {
+    if (options.objectStoreRoot === undefined || options.objectStoreSigningKey === undefined)
+      throw new AppError(
+        'The asset engine is active but no ObjectStore (nor objectStoreRoot+objectStoreSigningKey) was provided. A file product with no object store is a boot failure (OBJECT_STORE_MISSING).',
+        { code: 'OBJECT_STORE_MISSING', status: 500, isOperational: false, context: { profile: manifest.profile } },
+      );
+    const fsStore = createFsObjectStore({ root: options.objectStoreRoot, signingKey: options.objectStoreSigningKey });
+    objects = fsStore;
+    verifySignedUrl = fsStore.verifySignedUrl;
+  }
+
+  // ── drivers (2c) + gateway ──────────────────────────────────────────────────
+  // Constructed BEFORE the search provider: search's optional embedder routes
+  // through the gateway, so the gateway cannot depend on search in turn.
+  const { drivers } = buildDrivers(manifest, {
+    providers: options.providers,
+    drivers: options.drivers,
+    deps: { objects },
+    modelEndpoints: options.modelEndpoints,
+    // Every model this app is CONFIGURED to use must have a driver — a stricter
+    // gate than "some driver exists", and the one that catches a jobModel
+    // pointing at a provider the host forgot to declare.
+    requiredProviders: [options.jobModel?.provider, options.embedModel?.provider].filter(
+      (provider): provider is CognitiveProvider => provider !== undefined,
+    ),
+  });
+  const gateway = createCognitiveGateway({
+    appId: manifest.appId,
+    drivers,
+    telemetry,
+    // Defense in depth (03 §1d): the SAME enforcer the routes use, so AI work
+    // that never crossed a route — a job handler, internal automation — is held
+    // to the identical ceiling. Undefined under local, where there is no plan.
+    enforce: options.billing ? createPlanEnforcer(options.billing).assert : undefined,
+  });
+
+  // ── search provider (dual-wired: read + write from ONE instance) ───────────
+  //
+  // An injected provider WINS. It has to: under saas the recipe opens no
+  // `search.db` (the host injected `storage`), so `searchDb` is undefined and
+  // the branch below produces nothing — which is exactly how the saas profile
+  // came to have no search tier at all. `createSaasHostServices(…).search`
+  // supplies the far side, and `reportSaasHostWiring` refuses a saas knowledge
+  // app without it rather than letting `reindex` fail per run.
+  // The gateway-routed embedder, built once and shared by both construction
+  // paths so a metered embedding call means the same thing on both profiles.
+  const gatewayEmbed = options.embedModel
+    ? (text: string, tenantId: string): Promise<Float32Array> =>
+        gateway.embed({ text, model: options.embedModel as ModelConfig, tenantId })
+    : undefined;
+  const embedModelId = options.embedModel
+    ? `${options.embedModel.provider}:${options.embedModel.model}`
+    : undefined;
+
+  const search: RebuildableSearchProvider | undefined =
+    resolveSearchTier(options.search, {
+      gateway,
+      ...(options.embedModel ? { embedModel: options.embedModel } : {}),
+    }) ??
+    (enableSearch && searchDb
+      ? createSqliteSearchProvider({
+          db: searchDb,
+          // The vector half, real only when a host declares an embedding model.
+          // Routed through the gateway rather than straight at a driver so an
+          // embedding call is metered and telemetered exactly like a completion.
+          ...(gatewayEmbed ? { embed: gatewayEmbed } : {}),
+          // Recorded on every chunk and used as a query predicate: vectors from
+          // two models are not comparable even at the same width.
+          ...(embedModelId ? { embedModel: embedModelId } : {}),
+        })
+      : undefined);
+
+  // The ONE push hub for this runtime: constructed here (not inside
+  // createCcRuntime) so a long job handler — deploy — can publish progress onto
+  // the exact channel the `/stream` routes serve. Passed to both the handler map
+  // and the runtime below.
+  const push = createServerPushHub();
+
+  // ── job handlers (jobs seam) + the inventory assert (G8) ────────────────────
+  const { handlers: jobHandlers, enqueueableKinds } = buildJobHandlers({
+    manifest,
+    storage,
+    gateway,
+    search,
+    objects,
+    jobModel: options.jobModel,
+    applyProposals: options.applyProposals,
+    // deploy (03 §4b): real when the dev engine has an execution driver AND a
+    // host-supplied plan; the recipe keeps the loud placeholder otherwise.
+    exec: options.exec,
+    deployPlan: options.devDeps?.deployPlan,
+    push,
+  });
+  assertJobKindsHandled({ enqueueableKinds, handlers: jobHandlers });
+
+  // ── broker (depends on the handler map) ──────────────────────────────────────
+  let broker: JobBroker;
+  let stopBroker: (() => Promise<void>) | undefined;
+  // The durable outcome log. Constructed HERE rather than left to the broker's
+  // own default so the `orchestration` surface reads the very rows the broker
+  // records (03 §1e) — a second store over the same file would be a second DDL
+  // owner and an empty read.
+  let jobResults: JobResultStore | undefined = options.jobResults;
+  if (options.broker) {
+    broker = options.broker;
+  } else if (manifest.profile === 'local') {
+    const jobsDb = options.jobsDb ?? new Database(options.root ? path.join(options.root, 'jobs.db') : ':memory:');
+    jobResults ??= createSqliteJobResultStore(jobsDb);
+    const local = createLocalJobBroker({ db: jobsDb, handlers: jobHandlers, results: jobResults });
+    local.start();
+    broker = local;
+    stopBroker = async () => {
+      await local.stop();
+      if (!options.jobsDb) jobsDb.close();
+    };
+  } else {
+    throw new AppError(
+      'A saas profile must inject its cross-process broker (createSaasJobBroker over the queue backend). bootEngineApp does not construct a queue connection.',
+      { code: 'SAAS_BROKER_UNWIRED', status: 500, isOperational: false, context: { profile: manifest.profile } },
+    );
+  }
+
+  // ── engine services (services seam) ──────────────────────────────────────────
+  const signer =
+    options.signer ??
+    createSessionSigner({
+      ttlSeconds: options.sessionTtlSeconds ?? 3600,
+      // Under saas the host passes the shared store; under local it is undefined
+      // and the signer's in-process Map is the whole denylist (03 §4a).
+      revocationStore: options.revocationStore,
+    });
+  const services = buildEngineServices({
+    manifest,
+    storage,
+    broker,
+    telemetry,
+    objects,
+    verifySignedUrl,
+    search,
+    signer,
+    guardDeps: options.guardDeps,
+    devDeps: options.devDeps,
+    ...(domainHandles ? { domainHandles } : {}),
+    ...(options.root === undefined ? {} : { snapshotRoot: path.join(options.root, 'snapshots') }),
+    // The SAME driver `createCcRuntime` puts on the dev mixin context below, and
+    // the SAME result store the broker records into — the `pipelines` and
+    // `orchestration` surfaces read exactly what the app runs (03 §1e).
+    ...(options.exec === undefined ? {} : { exec: options.exec }),
+    ...(jobResults === undefined ? {} : { jobResults }),
+    mintId: options.mintId,
+    onOrphanedObject: options.onOrphanedObject,
+  });
+
+  // ── the stale-upload reaper (05 §A2) ────────────────────────────────────────
+  // An `mv_uploads` row is opened before a byte moves, so a killed process or a
+  // store error after the object settled strands it in `processing` with an
+  // unreferenced object behind it. Nothing swept those, and nothing ever would
+  // have: the sweep is the ONE piece the vault replacement dropped from
+  // `plugin-media-vault`. Started here rather than in a host because a seam no
+  // host constructs is an orphan (law #1) — which is the shape this same file
+  // has already been caught in twice (`devDeps`, `resolveIdentity`).
+  let vaultReaper: VaultUploadReaper | undefined;
+  if (services.asset && manifestHasVaultSource(manifest)) {
+    const tenants =
+      options.vaultReaper?.tenants ??
+      (manifest.profile === 'local'
+        ? () => [LOCAL_TENANT_ID]
+        : () => {
+            throw new AppError(
+              'This app has the vault source on under the saas profile but wired no vaultReaper.tenants. Enumerating tenants is an unscoped read RLS forbids, so the host must name them — otherwise every abandoned upload leaks an object forever (05 §A2).',
+              { code: 'VAULT_REAPER_UNWIRED', status: 500, isOperational: false, context: { profile: manifest.profile } },
+            );
+          });
+    // Fail at BOOT, not at the first tick an hour later: a refusal nobody is
+    // watching for is not a refusal.
+    if (manifest.profile !== 'local' && options.vaultReaper?.tenants === undefined) void tenants();
+    vaultReaper = createVaultUploadReaper({
+      assets: services.asset,
+      tenants,
+      ...(options.vaultReaper?.intervalMs === undefined ? {} : { intervalMs: options.vaultReaper.intervalMs }),
+      ...(options.vaultReaper?.olderThanMs === undefined ? {} : { olderThanMs: options.vaultReaper.olderThanMs }),
+      ...(options.vaultReaper?.limit === undefined ? {} : { limit: options.vaultReaper.limit }),
+      ...(options.vaultReaper?.onError === undefined ? {} : { onError: options.vaultReaper.onError }),
+    });
+  }
+
+  // ── the runtime — search on BOTH sides, exec iff dev, billing iff saas ───────
+  const runtime = createCcRuntime({
+    manifest,
+    storage,
+    guard: signer,
+    gateway,
+    broker,
+    telemetry,
+    services,
+    allowedOrigins: options.allowedOrigins,
+    exec: options.exec,
+    billing: options.billing,
+    // The trail's READ side. Passed beside the pipeline rather than derived from
+    // it: the pipeline hangs on the storage provider and this backs a route, and
+    // a host that wires one without the other gets a trail nothing can read.
+    ...(options.auditTrail ? { auditTrail: options.auditTrail } : {}),
+    ...(options.siteCopy ? { siteCopy: options.siteCopy } : {}),
+    search,
+    onSearchIndexError: options.onSearchIndexError,
+    meterSpillDrainIntervalMs: options.meterSpillDrainIntervalMs,
+    // The SAME hub the deploy handler publishes progress onto.
+    push,
+  });
+
+  return {
+    ...runtime,
+    drivers,
+    jobHandlers,
+    async stop() {
+      vaultReaper?.stop();
+      await runtime.stop();
+      await stopBroker?.();
+      await closeHandles?.();
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The generated app's hand-owned wiring hook (02 §1).
+// ---------------------------------------------------------------------------
+
+/**
+ * What a generated app's `host.ts` exports — the ONE seam where a developer
+ * supplies what the machine cannot generate: concrete AI drivers, an
+ * ExecutionDriver, the GuardEngine's identity deps, a saas broker or object
+ * store.
+ *
+ * It is deliberately a subset of {@link BootEngineAppOptions} rather than a new
+ * shape: every field means exactly what it means in the recipe, so there is no
+ * second vocabulary to keep in sync, and adding a recipe option automatically
+ * makes it host-overridable. `server.ts` stays generated and never hand-edited;
+ * `host.ts` is written once and never overwritten.
+ */
+export type EngineAppHost = Partial<
+  Pick<
+    BootEngineAppOptions,
+    | 'applyProposals'
+    // The trail's READ side, mounted on the guard mixin. A host that overrides
+    // the generated governance wiring passes its own — otherwise the app writes
+    // a trail no route can serve.
+    | 'auditTrail'
+    | 'billing'
+    | 'broker'
+    | 'devDeps'
+    | 'drivers'
+    | 'embedModel'
+    | 'enableSearch'
+    | 'exec'
+    | 'guardDeps'
+    // The GOVERNANCE pipeline (05 §B2's product consumers): the audit trail and
+    // the quota gate. Host-owned because both need a decision only a deployment
+    // can make — where a post-commit observer failure goes, which ops draw on
+    // which ceiling, and whether an access trail is worth its volume.
+    // `createGovernanceTier(...).interceptors` is what belongs here.
+    | 'interceptors'
+    | 'jobModel'
+    // A host that injects its own `broker` MUST pass the store that broker
+    // records into, or the `orchestration` surface reads a log nothing fills.
+    // Its absence here was an omission, not a policy — this type's own
+    // docstring says a recipe option is automatically host-overridable.
+    | 'jobResults'
+    // The SHARED billing meter (04 item 4e, D26). `createSaasHostServices(…).meter`
+    // is what belongs here; a saas boot without it is refused, because the
+    // alternative is per-node plan ceilings that look exactly like working ones.
+    | 'meter'
+    | 'modelEndpoints'
+    | 'objects'
+    | 'providers'
+    | 'revocationStore'
+    // The saas search tier (04 §3). `bootEngineApp` builds the SQLite provider
+    // from handles it does not open when `storage` is injected, so under saas a
+    // host that does not pass one has NO search tier — `reindex` falls through
+    // to its loud placeholder and every knowledge search takes the `LIKE`
+    // fallback. `createSaasHostServices(…).search` is the one that belongs here.
+    | 'search'
+    | 'sessionTtlSeconds'
+    | 'signer'
+    // The marketing-copy store (D36). Under saas the generated wiring cannot
+    // reach a control-plane executor (the host owns the pool), so the host
+    // passes one — the same executor family `ensureSaasControlPlaneSchema`
+    // already migrates. The generated LOCAL server wires its governance
+    // executor itself; this seam is for saas and for hosts that override.
+    | 'siteCopy'
+    | 'storage'
+    // Under saas the reaper's tenants cannot be discovered (an unscoped read is
+    // what RLS forbids), so naming them is a HOST job — and boot refuses a saas
+    // vault app without them (`VAULT_REAPER_UNWIRED`). Unreachable from
+    // `host.ts` until now, which made that gate impossible to satisfy.
+    | 'vaultReaper'
+  >
+> & {
+  /** Extra CORS origins beyond the app's own. Wildcards are banned (03 §2.3). */
+  readonly allowedOrigins?: readonly string[];
+  /**
+   * saas only — which plan a tenant is on (04 §1a). Read by the generated
+   * `server.ts`, not by the recipe, which is why it lives beside
+   * `allowedOrigins` rather than in the `Pick` above.
+   *
+   * The saas profile composes the billing mixin unconditionally, so a saas app
+   * cannot boot without a {@link BillingService}. Building one needs the
+   * telemetry handle `meter_events` lives in — which the HOST does not own and
+   * `createLocalHostServices` does. So the split is: the deployment supplies the
+   * only part it alone knows (a tenant's plan, from its subscription store), and
+   * the generated server constructs the service over its own meter. A host that
+   * would rather supply the whole service still can — `billing` wins outright.
+   */
+  readonly plans?: (tenantId: string) => PlanDefinition | Promise<PlanDefinition>;
+  /**
+   * The whole governance tier (05 §B2, owner decision D25) — the ONE field to
+   * set rather than the three places it is used.
+   *
+   * `createGovernanceTier` returns a pipeline, a sink and a registration list,
+   * and those go to three DIFFERENT consumers: the pipeline to the storage
+   * provider, the sink to the guard mixin's read route, and the registrations to
+   * `resolveBootManifest`'s V4 cycle audit. A host that wires one and forgets
+   * the others gets no error — it gets a trail nothing can read, or a cyclic
+   * hook pair that is a runaway transaction in production instead of a boot
+   * failure. So the generated `server.ts` reads all three off this one field.
+   *
+   * Set it under saas, where the tier must be built beside the POOLED executor
+   * (a per-node sqlite audit file would make the multi-node story silently
+   * false). Under local the generated `server.ts` builds one itself and this
+   * stays unset.
+   *
+   * Read by the generated `server.ts`, not by the recipe — which is why it lives
+   * here beside `plans` rather than in the `Pick` above.
+   */
+  readonly governance?: GovernanceTier;
+};