cursedbelt 2.8.0 → 3.0.0

package/src/server/runtime/recipe.ts

@@ -1,1527 +0,0 @@
-/**
- * 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;
-};