cursedbelt 2.8.0 → 3.0.1

package/src/server/runtime/saasHost.ts

@@ -1,432 +0,0 @@
-/**
- * The SAAS profile's host plumbing (04 §1) — the analog of `localHost.ts`, and
- * the thing whose absence made "SaaS" a set of unit-proven parts rather than a
- * runtime.
- *
- * Every saas seam already existed and every one of them had **zero production
- * construction sites**: `createSaasStorageProvider`, `createBullmqQueueAdapter`
- * and `runSaasJobWorker` were reachable only from tests, `bootEngineApp` threw
- * `SAAS_STORAGE_UNWIRED` / `SAAS_BROKER_UNWIRED` unless a host injected a
- * fully-built provider and broker, and the generated saas `host.ts` shipped
- * them as `null` — so a freshly generated saas app died at boot before serving
- * a byte. That is the exact shape of an orphan seam (law #1): a far side with
- * no near side.
- *
- * This is the near side, once, as a tested unit. It owns what a deployment owns
- * and a library must not:
- *
- *   1. **The ONE pool.** Every repository routes through a single registered
- *      pool; a second is a V6 ERROR (`unpooled-saas-connection`), because the
- *      classic per-request client exhausts Postgres' socket limit under load
- *      and takes the whole instance down.
- *   2. **The queue.** BullMQ's three primitives are INJECTED (cursedbelt must
- *      never depend on `bullmq` — it would force Redis onto a laptop), so the
- *      adapter is constructed here from what the deployment hands in.
- *   3. **The two SHARED control-plane stores** — the durable job-outcome log and
- *      the revoked-jti denylist. These are the reason 04 §1 was blocked: both
- *      interfaces admitted only per-node implementations until `JobResultStore`
- *      became async (owner decision E17), and a per-node completion log makes
- *      the multi-node story the saas broker exists for silently false.
- *
- *   4. **The identity tier** — `tenants`/`users`/`memberships`/`invitations` on
- *      the same pool, with the same HMAC row-signing (owner decision E18/D10).
- *      Until this landed, `createRegistryIdentityStore` was `bun:sqlite`-only
- *      and every saas branch in the codebase was unit-tested and UNBOOTABLE: V2
- *      refuses a saas config without the `guard` engine, and `guard` needs a
- *      `resolveIdentity` that no saas host could construct.
- *
- * **What this host does NOT do, and says so loudly:** it does not open a socket
- * (the pool is injected — law #8, a library never learns a connection string),
- * and it does not issue DDL against the shared database on a process start (see
- * `ensureSaasControlPlaneSchema` and `ensureSaasIdentitySchema` — a shared
- * database has ONE schema owner, and a library issuing DDL on every process
- * start would be N of them racing).
- *
- * The identity store is built here but is NOT spread into `bootEngineApp`
- * directly: it belongs to `guardDeps.identity`, because the guard engine owns
- * the seam and a host that also had to know how a session becomes claims would
- * be a second place that knows. {@link assertSaasHostWiring} still refuses at
- * boot when the guard engine is active and `guardDeps` is absent.
- */
-import {
-  createSaasStorageProvider,
-  type SaasPool,
-  type SaasPoolConfig,
-  type StatementExecutor,
-  type StorageProvider,
-} from 'cwip/storage';
-import type { RegistryIdentityStore, RegistryIdentityStoreOptions } from 'cwip/cc-registry';
-import { createStatementMeterUsageReader } from 'cwip/telemetry';
-import { AppError } from '../errors';
-import type { AsyncRevocationStore } from '../guard/revocationStore';
-import {
-  createBullmqQueueAdapter,
-  createSaasJobBroker,
-  createPgIdentityStore,
-  createPgJobResultStore,
-  createPooledControlExecutor,
-  createPgRevocationStore,
-  type BullmqAdapterDeps,
-  type JobResultStore,
-  type SaasJobBroker,
-  type SaasQueueBackend,
-} from '../drivers';
-import type { JobLogger } from '../jobs/types';
-import { createPgSearchProvider } from '../search/pgSearchProvider';
-import type { EngineAppHost, SearchTierFactory, SharedMeterTier } from './recipe';
-import type { EffectiveManifest } from '../../verify';
-
-export interface SaasHostOptions {
-  /**
-   * The deployment's connection pool — `withConnection` around
-   * `pool.connect()` + `client.release()` for `pg`, or the Turso equivalent.
-   * Injected rather than built here: a library that reads a connection string
-   * has put the deployment's topology back inside the library.
-   */
-  readonly pool: SaasPool;
-  /** Socket ceiling + a human label for diagnostics. */
-  readonly poolConfig: SaasPoolConfig;
-  /**
-   * BullMQ's three primitives, already bound to this deployment's Redis. Absent
-   * ⇒ no broker is built and {@link SaasHostServices.broker} is undefined,
-   * which is correct for a process that only reads (a migration runner, a
-   * one-shot CLI) and is refused at boot for a server.
-   */
-  readonly queue?: BullmqAdapterDeps;
-  /** Wall-clock ceiling per repository op. A hung query holds a pooled socket. */
-  readonly opTimeoutMs?: number;
-  readonly logger?: JobLogger;
-  /**
-   * Row-signing options for the identity tier. Absent ⇒ no identity store is
-   * built, which is correct for a process that has no guard surface (a
-   * migration runner, the worker) and is refused at boot for a server with the
-   * guard engine active.
-   *
-   * The signer is REQUIRED rather than defaulted because the integrity key is
-   * deployment key custody: a host that minted one silently would give every
-   * node a different key, and every row written by one node would fail
-   * verification on every other — an outage that reads as data corruption.
-   */
-  readonly identity?: RegistryIdentityStoreOptions;
-  /**
-   * The search tier (04 §3). Absent ⇒ no provider is built, which is correct
-   * for a process with no knowledge surface and is refused at boot for a server
-   * whose manifest activates the `knowledge` engine.
-   *
-   * `embed` is INJECTED here rather than derived, for the same reason it is on
-   * the local profile: a host that has wired an embedding driver gets the vector
-   * tier, and a host that has not gets an honestly keyword-only one. The
-   * generated `server.ts` routes it through the `CognitiveGateway`, so an
-   * embedding call is metered and telemetered like any other AI call.
-   */
-  readonly search?: SaasSearchOptions;
-  /**
-   * The SHARED billing meter (04 item 4e, owner decision D26 Option A). Absent ⇒
-   * no meter tier is built, which is correct for a migration runner and is
-   * REFUSED at boot for a saas server (`reportSaasHostWiring`).
-   *
-   * Its only input is this node's own identity — everything else rides the pool.
-   */
-  readonly meter?: SaasMeterOptions;
-}
-
-/** What the shared meter needs beyond the pool it shares with everything else. */
-export interface SaasMeterOptions {
-  /**
-   * A stable identity for THIS node — the pod name, the machine id, whatever the
-   * deployment already has. REQUIRED and never defaulted: it is the key the
-   * rollup resumes from, so two nodes sharing one would make the node with fewer
-   * local rows skip its own backlog permanently. A hostname default is exactly
-   * how that happens (two pods, one StatefulSet name).
-   */
-  readonly nodeId: string;
-}
-
-/**
- * The shared-meter tier — see {@link SharedMeterTier}, which is where the type
- * lives because `EngineAppHost` carries it. Aliased here so a host reading this
- * file sees the name its own option produces.
- *
- * The tier's ROLLUP half is built by the generated `server.ts` rather than here,
- * because it needs the node's own telemetry handle — which
- * `createLocalHostServices` owns and this host does not. That is the same
- * asymmetry `plans`/`billing` already has, for the same reason.
- */
-export type SaasMeterTier = SharedMeterTier;
-
-/** What the saas search tier needs beyond the pool it shares with everything else. */
-export interface SaasSearchOptions {
-  /**
-   * Override the recipe's embedder. Normally OMITTED: the recipe passes its own
-   * gateway-routed one, which is what makes an embedding call metered and
-   * telemetered like any other AI call. Supplying one here is a deliberate
-   * choice to run embeddings OUTSIDE the app's metering, and should be rare.
-   */
-  embed?(text: string, tenantId: string): Promise<Float32Array>;
-  /** Override the model id recorded per chunk. Normally omitted — see `embed`. */
-  embedModel?: string;
-  vectorCandidateLimit?: number;
-  onVectorTruncated?(detail: { tenantId: string; corpora: readonly string[]; scanned: number }): void;
-  onVectorError?(error: unknown, phase: 'index' | 'query'): void;
-}
-
-export interface SaasHostServices {
-  /** The pooled provider `bootEngineApp({ storage })` needs. */
-  readonly storage: StorageProvider;
-  /** The queue backend the worker leases from. Absent iff no `queue` was given. */
-  readonly queueBackend?: SaasQueueBackend;
-  /** The cross-process broker. Absent iff no `queue` was given. */
-  readonly broker?: SaasJobBroker;
-  /** The SHARED outcome log — the same rows on every node. */
-  readonly jobResults: JobResultStore;
-  /** The SHARED jti denylist — a revoke on node A is a 401 on node B. */
-  readonly revocationStore: AsyncRevocationStore;
-  /**
-   * An executor for the SHARED audit trail, over the same pool.
-   *
-   * Shared is the whole point: a write on node A must be readable from node B,
-   * or the trail is N partial trails and "prove what changed" cannot be answered
-   * from any one of them. It is a CONTROL-plane executor — the audit table's
-   * maintenance verbs (retention sweeps) are cross-tenant by design, and the
-   * tenant predicate on every read is REQUIRED rather than optional, which is
-   * the law `createStatementAuditTrailStore` enforces in its own `read`.
-   *
-   * Pass it to `createGovernanceTier({ auditTrail: { executor } })`, and run
-   * `ensureAuditTrailSchema` ONCE from the deployment's migration step.
-   */
-  readonly auditExecutor: StatementExecutor;
-  /**
-   * The SHARED accounts — sign up on node A, log in on node B. Absent iff no
-   * `identity` options were given. Goes to `guardDeps.identity`, not into
-   * `bootEngineApp` directly.
-   */
-  readonly identity?: RegistryIdentityStore;
-  /**
-   * The SHARED search index — indexed on node A, found on node B. Absent iff no
-   * `search` options were given. Goes to `bootEngineApp({ search })`.
-   *
-   * A FACTORY rather than a built provider, and the reason is metering: the
-   * embedder must route through the app's ONE `CognitiveGateway`, which
-   * `bootEngineApp` constructs AFTER this host has already run. So the recipe
-   * calls this with the gateway-routed `embed` and gets the tier back. A host
-   * that built the provider here would either have no vector tier or a second,
-   * UNMETERED AI path.
-   */
-  readonly search?: SearchTierFactory;
-  /**
-   * The SHARED billing meter — metered on node A, counted on node B. Absent iff
-   * no `meter` options were given. Goes to `bootEngineApp({ meter })`, and the
-   * generated `server.ts` reads both halves off it.
-   *
-   * Run `ensureSharedMeterSchema` ONCE from the deployment's migration step,
-   * beside `ensureSaasControlPlaneSchema`.
-   */
-  readonly meter?: SharedMeterTier;
-  /** Release what this host constructed. The POOL is the caller's to close. */
-  close(): Promise<void>;
-}
-
-/**
- * Construct every saas seam from what the deployment supplies.
- *
- * The result is spread straight into `bootEngineApp`, which is what makes the
- * generated `host.ts` a four-line call instead of the twenty lines each
- * deployment would otherwise write differently.
- */
-export const createSaasHostServices = (options: SaasHostOptions): SaasHostServices => {
-  const storage = createSaasStorageProvider({
-    pool: options.pool,
-    config: options.poolConfig,
-    ...(options.opTimeoutMs === undefined ? {} : { opTimeoutMs: options.opTimeoutMs }),
-  });
-
-  // Both stores read and write through the SAME pool the repositories use.
-  // A second pool for the control plane would be a second socket budget nobody
-  // sized — and the V6 `unpooled-saas-connection` gate exists because that is
-  // the classic way a deployment falls over under load.
-  const jobResults = createPgJobResultStore(options.pool);
-  // Per-statement checkout — an executor bound to one already-returned
-  // connection is a use-after-release. See `createPooledControlExecutor`. ONE
-  // executor serves every control-plane table (the trail, the shared meter):
-  // they share a pool, a dialect and a checkout discipline, and a second
-  // executor would be a second thing to keep in step for no property.
-  const controlExecutor = createPooledControlExecutor(options.pool);
-  const auditExecutor = controlExecutor;
-  const revocationStore = createPgRevocationStore(options.pool);
-  const identity = options.identity === undefined ? undefined : createPgIdentityStore(options.pool, options.identity);
-
-  // The search tier rides the SAME pool — see `jobResults` above. A search index
-  // on its own connection budget is the same mistake in a different table.
-  const searchOptions = options.search;
-  const search: SearchTierFactory | undefined =
-    searchOptions === undefined
-      ? undefined
-      : (deps) =>
-          createPgSearchProvider({
-            pool: options.pool,
-            // The recipe's gateway-routed embedder first; an explicit override
-            // second. Spread order is the policy: a host that names its own
-            // `embed` means it.
-            ...(deps.embed ? { embed: deps.embed } : {}),
-            ...(deps.embedModel ? { embedModel: deps.embedModel } : {}),
-            ...searchOptions,
-          });
-
-  // The shared meter rides the SAME pool, over the SAME per-statement checkout
-  // the audit trail uses — see `createPooledControlExecutor`. It is a control
-  // plane table for the same reason the others are: the rollup writes rows for
-  // every tenant a node served, and the reader is scoped in the query.
-  const meter: SharedMeterTier | undefined =
-    options.meter === undefined
-      ? undefined
-      : {
-          nodeId: options.meter.nodeId,
-          executor: controlExecutor,
-          usage: createStatementMeterUsageReader(controlExecutor),
-        };
-
-  const queueBackend = options.queue === undefined ? undefined : createBullmqQueueAdapter(options.queue);
-  const broker =
-    queueBackend === undefined
-      ? undefined
-      : createSaasJobBroker({
-          queue: queueBackend,
-          // THE point of this whole module: the broker records into the shared
-          // store, so a waiter on any node reads an outcome produced on any
-          // other. Handing it a per-node store would compile and would quietly
-          // restore the single-heap behavior the saas broker replaced.
-          results: jobResults,
-          ...(options.logger === undefined ? {} : { logger: options.logger }),
-        });
-
-  return {
-    storage,
-    ...(queueBackend === undefined ? {} : { queueBackend }),
-    ...(broker === undefined ? {} : { broker }),
-    jobResults,
-    revocationStore,
-    auditExecutor,
-    ...(identity === undefined ? {} : { identity }),
-    ...(search === undefined ? {} : { search }),
-    ...(meter === undefined ? {} : { meter }),
-    async close() {
-      broker?.close();
-      await storage.close?.();
-      // The pool is NOT closed here. It was injected, it may be shared with a
-      // migration runner or a second entrypoint in the same process, and a
-      // library closing a handle it did not open is how a shutdown ends up
-      // racing the thing that owns it.
-    },
-  };
-};
-
-/* ------------------------------------------------------- the early gate (1c) */
-
-/** Every host field a saas app needs, missing at once rather than one per boot. */
-export interface SaasWiringReport {
-  readonly missing: readonly string[];
-  readonly ok: boolean;
-}
-
-export interface AssertSaasHostWiringInput {
-  readonly manifest: EffectiveManifest;
-  readonly host: EngineAppHost;
-}
-
-/**
- * What a saas app's host must supply, derived from the MANIFEST rather than
- * from a restated list — a new engine that needs a seam is caught by what its
- * instances declare, not by whether someone remembered to extend a constant.
- */
-export const reportSaasHostWiring = (input: AssertSaasHostWiringInput): SaasWiringReport => {
-  const { manifest, host } = input;
-  if (manifest.profile !== 'saas') return { missing: [], ok: true };
-
-  const engines = new Set<string>(manifest.engines);
-  const missing: string[] = [];
-
-  if (!host.storage) missing.push('storage — createSaasHostServices({ pool, poolConfig }).storage');
-  if (!host.broker) missing.push('broker — createSaasHostServices({ …, queue }).broker');
-  if (!host.jobResults)
-    missing.push('jobResults — createSaasHostServices(…).jobResults (the broker records into it)');
-  // A per-node denylist under saas means a revoked session stays valid on every
-  // other node until it expires. Missing it is not a degraded mode; it is the
-  // security property `revokeUser` exists to provide, silently absent.
-  if (!host.revocationStore)
-    missing.push('revocationStore — createSaasHostServices(…).revocationStore (a Map is per-node)');
-  // The saas profile composes the billing mixin UNCONDITIONALLY
-  // (`composeServer`), so a saas app with no BillingService cannot boot — it
-  // died with `MIXIN_DEPENDENCY_MISSING` several hundred lines further into
-  // `createCcRuntime`, after the pool was open and the queue was connected. That
-  // is the same class of late failure this gate exists to end, and it was the
-  // last thing standing between the shipped `host.ts` and a booting saas app.
-  if (!host.billing)
-    missing.push('billing — a plan resolver: `plans: (tenantId) => PlanDefinition` in host.ts (server.ts builds the service over your meter), or a BillingService of your own');
-  // 04 item 4e / D26. Without it, `BillingService` falls back to the node's OWN
-  // `meter_events` and every plan ceiling is enforced once PER NODE — two API
-  // nodes let a 100 GB tenant use 200 GB, and the quota gate inherits the same
-  // number. Nothing about that failure is visible: both nodes return plausible
-  // usage. So it is refused here rather than degraded, exactly like the
-  // per-node revocation denylist above.
-  if (!host.meter)
-    missing.push(
-      'meter — createSaasHostServices({ …, meter: { nodeId } }).meter (without it, billing counts THIS node\'s meter_events only, so every plan ceiling is enforced once per node)',
-    );
-  // Symmetry with the local profile (1c): the object-store gate fires at boot
-  // there and only surfaced through `requireDeps` mid-request here — same
-  // wiring mistake, two different failure moments, and the saas one landed on a
-  // user instead of on a deploy.
-  if (engines.has('asset') && !host.objects)
-    missing.push('objects — an S3 ObjectStore (createS3ObjectStore); the fs store is a local-profile path');
-  // The message changed with E18: the identity tier IS buildable now, so the
-  // fix is a one-liner rather than "write your own store". Naming the exact call
-  // is the difference between a gate someone satisfies and a gate someone works
-  // around by turning the guard engine off.
-  // A saas knowledge app with no search tier is not "search-less": `reindex`
-  // fails on every run and `KnowledgeService.search` silently takes its `LIKE`
-  // fallback, which returns results and looks like it works. That is the shape
-  // of failure this gate exists for — the ones that produce output.
-  if (engines.has('knowledge') && host.enableSearch !== false && !host.search)
-    missing.push(
-      'search — createSaasHostServices({ …, search: { embed } }).search (the recipe builds a search tier only from local SQLite handles, so under saas there is none)',
-    );
-  if (engines.has('guard') && !host.guardDeps)
-    missing.push(
-      'guardDeps — build it from createSaasHostServices({ …, identity: { signer } }).identity, then pass { identity, currentClaims } (02 §1b, 04 §1a)',
-    );
-
-  // `vaultReaper.tenants` is deliberately NOT checked here. It already has a
-  // specific typed gate further into the boot (`VAULT_REAPER_UNWIRED`, 05 §A2),
-  // and restating it would make that one unreachable — trading a precise,
-  // documented error code for a generic one is a regression in diagnosability,
-  // not a tightening. This function covers the seams that had NO gate at all
-  // (storage/broker/jobResults/revocationStore) or only a local-profile one
-  // (objects).
-
-  return { missing, ok: missing.length === 0 };
-};
-
-/**
- * Refuse an incompletely-wired saas app with ONE error naming everything.
- *
- * The value is not the check — each of these would eventually fail on its own.
- * It is that they fail TOGETHER, at the start, naming the call that supplies
- * each one. The previous behavior was a boot that got one error further per
- * attempt, with the last two (`objects`, `vaultReaper`) not surfacing until a
- * request hit them in production.
- *
- * @throws {AppError} `SAAS_HOST_UNWIRED`
- */
-export const assertSaasHostWiring = (input: AssertSaasHostWiringInput): void => {
-  const report = reportSaasHostWiring(input);
-  if (report.ok) return;
-  throw new AppError(
-    `This saas app's host wiring is incomplete. Supply, in host.ts:\n  • ${report.missing.join('\n  • ')}`,
-    {
-      code: 'SAAS_HOST_UNWIRED',
-      status: 500,
-      isOperational: false,
-      context: { profile: input.manifest.profile, missing: report.missing },
-    },
-  );
-};