cursedbelt 2.7.0 → 3.0.0

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

@@ -1,161 +0,0 @@
-/**
- * The boot moment (02 §4) — the disposition that differs from every other caller.
- *
- * Export blocks and CI gates; boot DEGRADES. These tests pin the three outcomes
- * that distinction produces: serve live on success, serve last-good with a
- * visible error page on failure, and refuse to invent a surface when there is no
- * last-good bundle at all.
- */
-import { describe, expect, it } from 'bun:test';
-import { mountStaticAssets } from './staticAssets';
-import { probeHostCapabilities } from './hostCapabilities';
-import { renderBootErrorPage, resolveBootManifest } from './bootManifest';
-import { toFrozenManifest, readFrozenManifest, serializeFrozenManifest } from '../../verify/frozenManifest';
-import { verifyAppConfig } from '../../verify/pipeline';
-
-const GOOD = {
-  configVersion: 1,
-  app: { id: 'boot-demo', title: 'Boot Demo' },
-  profile: 'local',
-  engines: ['knowledge'],
-  instances: [{ engine: 'knowledge', id: 'notes', features: { notes: true }, routes: [{ path: '/notes', view: 'notes' }] }],
-};
-
-/** `privateMedia` without `guard` — the V0 cross-engine dependency (J2-1). */
-const BAD = {
-  configVersion: 1,
-  app: { id: 'boot-demo', title: 'Boot Demo' },
-  profile: 'local',
-  engines: ['asset'],
-  instances: [{ engine: 'asset', id: 'gallery', features: { privateMedia: true } }],
-};
-
-const frozenGood = async () => {
-  const result = await verifyAppConfig({ config: GOOD, moment: 'export', capabilities: {} });
-  if (!result.manifest) throw new Error('fixture failed to compile');
-  return readFrozenManifest(JSON.parse(serializeFrozenManifest(result.manifest)));
-};
-
-describe('resolveBootManifest', () => {
-  it('serves the LIVE manifest when the config verifies against this machine', async () => {
-    const resolved = await resolveBootManifest({ config: GOOD, lastGood: await frozenGood(), capabilities: {} });
-    expect(resolved.ok).toBe(true);
-    expect(resolved.servedLastGood).toBe(false);
-    expect(resolved.manifest.moment).toBe('boot');
-    expect(resolved.manifest.appId).toBe('boot-demo');
-  });
-
-  it('keeps serving the last-good bundle when the live config breaks', async () => {
-    const lastGood = await frozenGood();
-    const resolved = await resolveBootManifest({ config: BAD, lastGood, capabilities: {} });
-    expect(resolved.ok).toBe(false);
-    expect(resolved.servedLastGood).toBe(true);
-    // The surface actually served is the previous one, unchanged.
-    expect(resolved.manifest.bundleKey).toBe(lastGood.bundleKey);
-    expect(resolved.manifest.engines).toEqual(['knowledge']);
-    expect(resolved.diagnostics.some((d) => d.code === 'engine-dependency-missing')).toBe(true);
-  });
-
-  it('refuses to fabricate a surface when there is no last-good bundle', async () => {
-    await expect(resolveBootManifest({ config: BAD, capabilities: {} })).rejects.toThrow(
-      /BOOT_CONFIG_UNSERVABLE|no last-good/,
-    );
-  });
-
-  it('probes the live machine when no capability profile is injected', async () => {
-    const resolved = await resolveBootManifest({
-      config: GOOD,
-      probe: { hasExecutable: (name) => name === 'git', hasAiDriver: false },
-    });
-    expect(resolved.capabilities.git).toBe(true);
-    expect(resolved.capabilities.ffmpeg).toBe(false);
-    expect(resolved.capabilities.aiProvider).toBe(false);
-  });
-});
-
-describe('probeHostCapabilities', () => {
-  it('never guesses aiProvider — the host that wired the driver declares it', () => {
-    expect(probeHostCapabilities({ hasExecutable: () => true }).aiProvider).toBe(false);
-    expect(probeHostCapabilities({ hasExecutable: () => true, hasAiDriver: true }).aiProvider).toBe(true);
-  });
-
-  it('answers "no" rather than crashing when PATH inspection is denied', () => {
-    // A hardened container that refuses PATH inspection must degrade the
-    // affected features, never turn the boot into a crash loop.
-    const caps = probeHostCapabilities({
-      hasExecutable: () => {
-        throw new Error('sandbox');
-      },
-    });
-    expect(caps.ffmpeg).toBe(false);
-    expect(caps.git).toBe(false);
-    expect(caps.diskIndex).toBe(true);
-  });
-
-  it('lets a host override a probed value', () => {
-    const caps = probeHostCapabilities({ hasExecutable: () => false, overrides: { ffmpeg: true } });
-    expect(caps.ffmpeg).toBe(true);
-  });
-});
-
-describe('renderBootErrorPage', () => {
-  it('renders the exact corpus diagnostic codes an operator can search for', async () => {
-    const resolved = await resolveBootManifest({ config: BAD, lastGood: await frozenGood(), capabilities: {} });
-    const html = renderBootErrorPage(resolved);
-    expect(html).toContain('engine-dependency-missing');
-    expect(html).toContain('Boot Demo');
-    // The pinned CSP forbids inline script; an error page that violated it would
-    // render blank in the browser it exists to inform.
-    expect(html).not.toMatch(/<script/i);
-  });
-
-  it('escapes diagnostic text rather than injecting it into the page', async () => {
-    const resolved = await resolveBootManifest({ config: BAD, lastGood: await frozenGood(), capabilities: {} });
-    const html = renderBootErrorPage({
-      manifest: { ...resolved.manifest, title: '<img src=x onerror=alert(1)>' },
-      diagnostics: resolved.diagnostics,
-    });
-    expect(html).not.toContain('<img src=x');
-    expect(html).toContain('&lt;img src=x');
-  });
-});
-
-describe('mountStaticAssets — the degraded HTML route (V7.6)', () => {
-  it('serves the error page with 503 while degraded, and never for /api paths', async () => {
-    const { Hono } = await import('hono');
-    const app = new Hono();
-    app.get('/api/core/health', (c) => c.json({ ok: true }));
-    let degraded: string | null = 'DEGRADED PAGE';
-    mountStaticAssets({
-      app: app as never,
-      root: '/nonexistent-client-dist',
-      errorPage: () => degraded,
-    });
-
-    const html = await app.fetch(new Request('http://localhost/'));
-    expect(html.status).toBe(503);
-    expect(await html.text()).toContain('DEGRADED PAGE');
-
-    // A deep client link renders the same shell/error page…
-    expect((await app.fetch(new Request('http://localhost/notes/abc'))).status).toBe(503);
-    // …but an unmatched API path stays a 404, never an HTML 200.
-    expect((await app.fetch(new Request('http://localhost/api/nope'))).status).toBe(404);
-    // The real API route is untouched.
-    expect((await app.fetch(new Request('http://localhost/api/core/health'))).status).toBe(200);
-
-    degraded = null;
-    const recovered = await app.fetch(new Request('http://localhost/'));
-    // No build present ⇒ a loud 500, not a silent blank page.
-    expect(recovered.status).toBe(500);
-    expect(await recovered.text()).toContain('index.html is missing');
-  });
-});
-
-describe('frozen manifest ⇄ boot', () => {
-  it('the frozen artifact is what boot falls back to, byte-for-byte on the served fields', async () => {
-    const result = await verifyAppConfig({ config: GOOD, moment: 'export', capabilities: {} });
-    const frozen = toFrozenManifest(result.manifest!);
-    const resolved = await resolveBootManifest({ config: BAD, lastGood: readFrozenManifest(JSON.parse(JSON.stringify(frozen))), capabilities: {} });
-    expect(resolved.manifest.instances[0]?.routes).toEqual(result.manifest!.instances[0]!.routes);
-  });
-});

package/src/server/runtime/bootManifest.ts

@@ -1,172 +0,0 @@
-/**
- * The BOOT moment of the pipeline (02 §4) — the third of four callers.
- *
- * The pipeline had two real callers (tests and the CI corpus CLI) and two
- * specified ones. This is the boot caller, and its disposition is the one that
- * differs most from the others: **export blocks, CI gates, boot degrades.**
- *
- * The reasoning is operational rather than aesthetic. A running app re-verifies
- * its config against the machine it actually booted on, because a host loses
- * capabilities between builds — the container without ffmpeg, the laptop whose
- * `git` moved. If that re-verification fails, the least-bad outcome is NOT to
- * exit: an app that dies on a config edit takes a working product offline over a
- * typo. It keeps serving the **last-good frozen manifest** the export wrote and
- * makes the failure impossible to miss on the HTML route (V7.6
- * `last-good-not-served`; the error page is `renderBootErrorPage`).
- *
- * There is exactly one case where boot is fatal: a failed verification with NO
- * last-good bundle to fall back to. There is nothing to serve, and inventing a
- * manifest would fabricate a surface nobody declared.
- */
-import { AppError } from '../errors';
-import type { CCHookInterceptor } from 'cwip/storage';
-import { verifyAppConfig } from '../../verify/pipeline';
-import { withInterceptorEdges } from '../../verify/interceptorGraph';
-import type {
-  CapabilityProfile,
-  CodeContractDeclarations,
-  ConfigProvenance,
-  Diagnostic,
-  EffectiveManifest,
-  SourceDecl,
-  StorageContract,
-} from '../../verify/types';
-import { errorsOf } from '../../verify/types';
-import { probeHostCapabilities, type ProbeHostCapabilitiesOptions } from './hostCapabilities';
-
-export interface ResolveBootManifestOptions {
-  /** The live `app-config.json`, parsed. The pipeline owns the parse (V0). */
-  readonly config: unknown;
-  /**
-   * The frozen `manifest.gen.json` (already re-hydrated by `readFrozenManifest`).
-   * Absent ⇒ a failed verification is fatal, because there is nothing to serve.
-   */
-  readonly lastGood?: EffectiveManifest | null;
-  /** Live machine probe. Default: {@link probeHostCapabilities}. */
-  readonly capabilities?: CapabilityProfile;
-  /** Forwarded to the probe when `capabilities` is not supplied. */
-  readonly probe?: ProbeHostCapabilitiesOptions;
-  readonly sources?: readonly SourceDecl[];
-  readonly storage?: StorageContract;
-  readonly code?: CodeContractDeclarations;
-  /**
-   * Registered interceptors (05 §B2), folded into `code.eventHandlers` for the
-   * V4 cycle audit.
-   *
-   * Passing the SAME registry the storage provider got is what makes a cyclic
-   * pair of hooks a boot failure instead of a runaway mutation loop discovered
-   * in production. It is an option here rather than a caller-side spread on
-   * purpose: the two edge sources have to land in ONE array, and a walk over
-   * either list alone cannot see the most likely real cycle there is — engine
-   * subscriber → interceptor → engine subscriber.
-   */
-  readonly interceptors?: readonly CCHookInterceptor[];
-  readonly provenance?: ConfigProvenance;
-}
-
-export interface ResolvedBootManifest {
-  /** The manifest to actually serve — live on success, last-good on failure. */
-  readonly manifest: EffectiveManifest;
-  /** True ⇒ the live config did NOT verify and the frozen bundle is being served. */
-  readonly servedLastGood: boolean;
-  readonly diagnostics: readonly Diagnostic[];
-  /** Whether the LIVE config verified clean (false while degraded). */
-  readonly ok: boolean;
-  /** The capability profile the verification actually ran against. */
-  readonly capabilities: CapabilityProfile;
-}
-
-/**
- * Verify the live config against this machine and decide what to serve.
- * Never throws for a config-level problem when a last-good bundle exists — that
- * is the whole point of the boot disposition.
- */
-export async function resolveBootManifest(options: ResolveBootManifestOptions): Promise<ResolvedBootManifest> {
-  const capabilities = options.capabilities ?? probeHostCapabilities(options.probe);
-  const result = await verifyAppConfig({
-    config: options.config,
-    moment: 'boot',
-    capabilities,
-    sources: options.sources,
-    storage: options.storage,
-    code:
-      options.interceptors && options.interceptors.length > 0
-        ? { ...options.code, eventHandlers: withInterceptorEdges(options.code?.eventHandlers, options.interceptors) }
-        : options.code,
-    provenance: options.provenance,
-  });
-
-  if (result.ok && result.manifest)
-    return { manifest: result.manifest, servedLastGood: false, diagnostics: result.diagnostics, ok: true, capabilities };
-
-  const lastGood = options.lastGood ?? null;
-  if (!lastGood)
-    throw new AppError(
-      `The app config failed verification at boot and there is no last-good manifest to fall back to (${errorsOf(result.diagnostics).length} error(s)). Fix the config, or regenerate the app so a frozen manifest.gen.json exists.`,
-      {
-        code: 'BOOT_CONFIG_UNSERVABLE',
-        status: 500,
-        isOperational: false,
-        context: { codes: errorsOf(result.diagnostics).map((d) => d.code) },
-      },
-    );
-
-  return { manifest: lastGood, servedLastGood: true, diagnostics: result.diagnostics, ok: false, capabilities };
-}
-
-const escapeHtml = (value: string): string =>
-  value.replace(/[&<>"']/g, (ch) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[ch] as string);
-
-/**
- * The page the HTML route serves while the app is degraded. It renders the
- * diagnostics rather than a generic apology: the operator reading it is the
- * person who just broke the config, and the corpus diagnostic code is the exact
- * string they can search for.
- *
- * No inline `<script>` — the pinned CSP forbids it (`script-src 'self'`), and an
- * error page that itself violates the policy would render blank in the browser
- * it is meant to inform.
- */
-export function renderBootErrorPage(resolved: Pick<ResolvedBootManifest, 'manifest' | 'diagnostics'>): string {
-  const errors = errorsOf(resolved.diagnostics);
-  const rows = errors
-    .map((d) => {
-      const where = [d.instanceId, d.port, d.path].filter(Boolean).join(' ');
-      return [
-        '<li>',
-        `<code>${escapeHtml(d.code)}</code>${where ? ` <span class="where">${escapeHtml(where)}</span>` : ''}`,
-        `<p>${escapeHtml(d.message)}</p>`,
-        d.fix ? `<p class="fix">fix: ${escapeHtml(d.fix)}</p>` : '',
-        '</li>',
-      ].join('');
-    })
-    .join('\n');
-
-  return `<!doctype html>
-<html lang="en">
-<head>
-<meta charset="utf-8" />
-<meta name="viewport" content="width=device-width, initial-scale=1" />
-<title>${escapeHtml(resolved.manifest.title)} — config error</title>
-<style>
-  body { font: 14px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace; margin: 0; padding: 2rem; background: #12121a; color: #e8e8f0; }
-  h1 { font-size: 1.1rem; margin: 0 0 .25rem; }
-  .sub { color: #9a9ab0; margin: 0 0 1.5rem; }
-  ul { list-style: none; padding: 0; margin: 0; }
-  li { border-left: 3px solid #e0576b; background: #1b1b26; padding: .75rem 1rem; margin-bottom: .75rem; }
-  code { color: #e0576b; font-weight: 600; }
-  .where { color: #9a9ab0; }
-  p { margin: .35rem 0 0; }
-  .fix { color: #6fd3a0; }
-</style>
-</head>
-<body>
-<h1>${escapeHtml(resolved.manifest.title)} is serving its last-good bundle</h1>
-<p class="sub">The live <code>app-config.json</code> failed verification, so the previously exported manifest (<code>${escapeHtml(resolved.manifest.bundleKey)}</code>) is still being served. The API is up; this page replaces the app until the config verifies.</p>
-<ul>
-${rows}
-</ul>
-</body>
-</html>
-`;
-}

package/src/server/runtime/createCcRuntime.ts

@@ -1,241 +0,0 @@
-/**
- * The production entrypoint (03 §2.1) — the non-harness caller of
- * `composeServer` that the audit found missing.
- *
- * Before this, `composeServer` was called from exactly one place: the verify
- * harness. Everything it orbits — the mixins, the guards, the CSP, the instance
- * index, the drivers — was proven at the contract level and nowhere else,
- * because no code path bound real repositories to the mixins and served a
- * request. This is that path.
- *
- * What it will NOT do is open a database. Handle injection (01 §1.1.3) is a law:
- * hosts open the files (paths declared in the generated app's `package.json` →
- * `cursed.app.storage`) and inject them. A runtime that opened its own would put
- * the storage layout back inside the library, where a generated app could never
- * change it.
- *
- * Boot is deliberately loud. Every check below is a startup failure rather than
- * a 500 on the first request that happens to need the missing piece:
- *
- *   * an active `guard` engine with no argon2id binding registered
- *     (`assertArgon2idReady` — the gate that converts a first-user 500 into a
- *     boot failure, §1.2);
- *   * a missing engine service or `ExecutionDriver` (`composeServer` throws);
- *   * a saas profile with no `BillingService`.
- */
-import { assertArgon2idReady } from 'cwip/guard';
-import type { DomainName } from 'cwip/domains';
-import type { SearchProvider } from 'cwip/search-provider';
-import type { AuditTrailSink, StatementExecutor, StorageProvider } from 'cwip/storage';
-import type { TelemetryWriter } from 'cwip/telemetry';
-import type { CognitiveGateway, ExecutionDriver, JobBroker } from '../drivers';
-import { AppError } from '../errors';
-import type { BillingService } from '../mixins/billing.mixin';
-import { buildInstanceIndex, composeServer } from '../mixins';
-import type { EngineServices } from '../mixins/services';
-import type { CCHono, GuardVerifier, MixinContext } from '../mixins/types';
-import { createEngineOpHandlers, type EngineOpsOptions } from '../ops';
-import { bridgeCdcToPush, bridgeCdcToSearch, createServerPushHub, type ServerPushHub } from '../stream';
-import type { EffectiveManifest } from '../../verify/types';
-
-export interface CcRuntimeOptions {
-  /** The V2 output. The route table derives from this and nothing else. */
-  manifest: EffectiveManifest;
-  /** Built by the host over ITS injected handles (01 §1.1.3). */
-  storage: StorageProvider;
-  /** Per-request token verification — `createSessionSigner()` in production. */
-  guard: GuardVerifier;
-  gateway: CognitiveGateway;
-  broker: JobBroker;
-  telemetry: TelemetryWriter;
-  services: EngineServices;
-  /** Origins `ccCorsPolicy` admits. Wildcards are banned (03 §2.3). */
-  allowedOrigins: readonly string[];
-  /** Required iff `engines[]` contains `dev` (J3-4). */
-  exec?: ExecutionDriver;
-  /** Required iff `profile === 'saas'`. */
-  billing?: BillingService;
-  /**
-   * The audit trail's READ side (D25) — `createGovernanceTier(…).auditTrail`.
-   * Present ⇒ the guard mixin mounts `GET /api/guard/audit`.
-   */
-  auditTrail?: AuditTrailSink;
-  /**
-   * The site-copy store's executor (D36). Present + `guard.features.siteCopy`
-   * on ⇒ the guard mixin mounts `/api/guard/site-copy*`.
-   */
-  siteCopy?: StatementExecutor;
-  /** Domains to tap for CDC push. Defaults to those the active engines own. */
-  cdcDomains?: readonly DomainName[];
-  /**
-   * The ranked-retrieval tier (08 §2). Present ⇒ the runtime taps CDC into it,
-   * so knowledge writes update `search_docs` with no component involvement
-   * (01 §2.6).
-   *
-   * This is the WRITE side. The same provider must also be passed to
-   * `createKnowledgeService` for the read side — the service queries it, the
-   * runtime fills it, and wiring only one of the two is the misconfiguration
-   * this comment exists to name.
-   */
-  search?: SearchProvider;
-  /** Reported for every row the search index could not follow. */
-  onSearchIndexError?: (error: unknown, record: { table: string; rowId: string }) => void;
-  /** Extra/overriding op handlers, merged over the generated table. */
-  ops?: Partial<Pick<EngineOpsOptions, 'commands' | 'utilities' | 'outboundGuard'>> & {
-    handlers?: Readonly<Record<string, import('../mixins/instance.mixin').OpHandler>>;
-  };
-  /** Reuse an existing app (the generated server mounts static assets on it). */
-  app?: CCHono;
-  /**
-   * Reuse an existing push hub instead of constructing one. `bootEngineApp`
-   * passes the SAME hub it handed the deploy job handler, so a long job's
-   * progress frames fan out on the very channel the `/stream` routes serve —
-   * a second hub would publish into a void nothing is subscribed to.
-   */
-  push?: ServerPushHub;
-  /**
-   * Skip the argon2id boot gate. For a host that genuinely has no GuardEngine
-   * surface (a headless worker composing only `knowledge`). Setting it with an
-   * active `guard` engine re-opens exactly the failure the gate exists to catch.
-   */
-  skipKdfReadinessGate?: boolean;
-  /**
-   * How often to replay spilled meter events (08 §5). `0` disables the timer —
-   * for a test, or a host that drives `drainSpill()` from its own scheduler.
-   */
-  meterSpillDrainIntervalMs?: number;
-}
-
-export interface CcRuntime {
-  app: CCHono;
-  ctx: MixinContext;
-  /** The live fan-out behind the `/stream` routes. */
-  push: ServerPushHub;
-  /** Detach CDC taps and close the push hub. Does NOT close injected handles. */
-  stop(): Promise<void>;
-}
-
-/** Default meter-spill replay cadence (08 §5). Jittered ±20% at schedule time. */
-const DEFAULT_SPILL_DRAIN_MS = 30_000;
-
-export function createCcRuntime(options: CcRuntimeOptions): CcRuntime {
-  const { manifest } = options;
-
-  // The boot gate. A misconfigured GuardEngine dies HERE, at startup, instead of
-  // looking healthy until the first user tries to unlock in production (§1.2).
-  if (manifest.engines.includes('guard') && options.skipKdfReadinessGate !== true) assertArgon2idReady();
-
-  if (manifest.profile === 'saas' && !options.billing)
-    throw new AppError('The saas profile composes the billing mixin, but no BillingService was provided.', {
-      code: 'MIXIN_DEPENDENCY_MISSING',
-      status: 500,
-      context: { profile: manifest.profile },
-    });
-
-  const push = options.push ?? createServerPushHub();
-
-  const ctx: MixinContext = {
-    manifest,
-    // Frozen once (J3-1). Building it per request was an O(N) scan that also
-    // tempted `instances[0]` shortcuts — the first-instance-wins bug C28 pinned.
-    instanceIndex: buildInstanceIndex(manifest),
-    storage: options.storage,
-    guard: options.guard,
-    gateway: options.gateway,
-    broker: options.broker,
-    telemetry: options.telemetry,
-    allowedOrigins: options.allowedOrigins,
-    push,
-  };
-
-  // CDC → per-instance streams. Without this the client's dirty ledger only ever
-  // reflects changes the same tab made (03 §6.2).
-  const detachCdc = bridgeCdcToPush({
-    storage: options.storage,
-    hub: push,
-    manifest,
-    domains: options.cdcDomains,
-  });
-
-  // CDC → the search index (08 §2b). Same stream, second consumer: the index
-  // follows every writer, not only the ones that remembered to call `index()`.
-  const detachSearch =
-    options.search !== undefined
-      ? bridgeCdcToSearch({
-          storage: options.storage,
-          search: options.search,
-          onError: options.onSearchIndexError,
-        })
-      : undefined;
-
-  const handlers = {
-    ...createEngineOpHandlers({
-      services: options.services,
-      broker: options.broker,
-      exec: options.exec,
-      push,
-      commands: options.ops?.commands,
-      utilities: options.ops?.utilities,
-      outboundGuard: options.ops?.outboundGuard,
-    }),
-    // Host overrides last: a generated app may add an op the framework table
-    // knows nothing about, or replace one with its own implementation.
-    ...(options.ops?.handlers ?? {}),
-  };
-
-  const app = composeServer({
-    app: options.app,
-    ctx,
-    services: options.services,
-    exec: options.exec,
-    instance: { handlers },
-    billing: options.billing,
-    auditTrail: options.auditTrail,
-    siteCopy: options.siteCopy,
-  });
-
-  // Spilled meter events are DURABLE but not yet BILLABLE: they sit in the
-  // journal until something replays them into `meter_events`, and until then
-  // `BillingService.usage` under-reports — which also means the 11 §4 plan gate
-  // compares against a number that is quietly too low. `drainSpill` existed with
-  // nothing scheduling it (08 §5); this is the scheduler.
-  //
-  // Jittered, so a fleet that restarts together does not converge on one instant
-  // and stampede the telemetry database's write lock.
-  const drainIntervalMs = options.meterSpillDrainIntervalMs ?? DEFAULT_SPILL_DRAIN_MS;
-  const spillTimer =
-    drainIntervalMs > 0
-      ? setInterval(
-          () => {
-            try {
-              // Cheap guard first: the common case is an empty journal, and
-              // `hasPendingSpill` avoids opening it at all.
-              if (!options.telemetry.hasPendingSpill?.()) return;
-              options.telemetry.drainSpill();
-            } catch {
-              // A drain failure is not fatal — the journal is the durable
-              // record and the next tick retries. Throwing here would take down
-              // a healthy server over a transient database lock.
-            }
-          },
-          drainIntervalMs + Math.floor(Math.random() * drainIntervalMs * 0.2),
-        )
-      : null;
-  // Never hold the process open on this timer alone.
-  spillTimer?.unref?.();
-
-  return {
-    app,
-    ctx,
-    push,
-    async stop() {
-      if (spillTimer) clearInterval(spillTimer);
-      detachCdc();
-      detachSearch?.();
-      // Subscribers get a `close` frame, so a browser reconnects on its jittered
-      // schedule rather than hanging on a socket the server already abandoned.
-      push.close();
-      await options.storage.close();
-    },
-  };
-}