cursedbelt 2.7.0 → 3.0.0

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

@@ -1,358 +0,0 @@
-/**
- * `search-reindex-converges` — the search tier through the REAL stack (08 §2 Gates).
- *
- * Spec 08 §2 asks for this as a corpus fixture. It is landed here instead, for
- * the same reason the object-store round-trip was: the golden corpus drives
- * `config → diagnostics`, and this scenario is about bytes in two databases
- * converging. A fixture shaped like the corpus could only assert that a config
- * declaring search verifies — which proves nothing about whether the index ends
- * up equal to the source. Acceptance bar #4 (a probe that exercises a throwaway
- * primitive instead of the composed system is not coverage) points the other
- * way: drive production composition.
- *
- * So everything under the assertions is real: real `verifyAppConfig` manifest,
- * real `createCcRuntime` (which is what attaches the CDC → search tap), real
- * `createLocalStorageProvider` over real SQLite handles, real
- * `createSqliteSearchProvider` over a real migrated `search.db`, real
- * repositories, real HTTP through the composed server.
- *
- * The three things it has to prove, because each is a distinct way for a
- * derived index to be wrong:
- *
- *   1. A rebuild makes the index EQUAL the source — including deleting entries
- *      whose source rows are gone. "Indexed everything that exists" is the easy
- *      half; the sweep is the half that converges.
- *   2. Steady state follows the DATABASE, not the service. Writes that never
- *      touch `KnowledgeService` — a job applying proposals through the
- *      repository layer — are indexed anyway, because the tap is on CDC.
- *   3. A cancelled rebuild deletes NOTHING. A sweep after a partial pass would
- *      wipe every document the job had not reached.
- */
-import { Database } from 'bun:sqlite';
-import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
-import { KNOWLEDGE_MIGRATIONS, KNOWLEDGE_NAMESPACE, SEARCH_MIGRATIONS, SEARCH_NAMESPACE } from 'cwip/domains';
-import { createRecord, deleteRecord, type RepoScope, updateRecord } from 'cwip/repositories';
-import { createSqliteSearchProvider, type SqliteSearchProvider } from 'cwip/search-provider';
-import { assertCcPragmas, getTxnLifetimeGuard, runNamespacedMigrations } from 'cwip/sqlite';
-import { createLocalStorageProvider, type StorageProvider } from 'cwip/storage';
-import type { TelemetryWriter } from 'cwip/telemetry';
-import { createCognitiveGateway, createMemoryJobResultStore, createSaasJobBroker, type JobBroker } from '../drivers';
-import { createSessionSigner, type SessionSigner } from '../guard/sessionSigner';
-import {
-  createKnowledgeReindexSource,
-  createKnowledgeService,
-  createSearchJobHandlers,
-  createSystemService,
-} from '../services';
-import { KNOWLEDGE_CORPUS } from '../stream';
-import type { EffectiveManifest } from '../../verify/types';
-import { verifyAppConfig } from '../../verify/pipeline';
-import { createCcRuntime, type CcRuntime } from './createCcRuntime';
-
-const APP_CONFIG = {
-  configVersion: 1,
-  app: { id: 'search-demo', title: 'Search Demo' },
-  profile: 'local',
-  engines: ['knowledge', 'system'],
-  instances: [
-    { engine: 'knowledge', id: 'notes', features: { notes: true, todos: true, ragChat: true } },
-    { engine: 'system', id: 'utils', features: { notifications: true } },
-  ],
-} as const;
-
-const SCOPE: RepoScope = { tenantId: 't_local', userId: 'u_local' };
-
-const noopTelemetry = (): TelemetryWriter =>
-  ({
-    recordApiCall: () => undefined,
-    recordMeterEvent: () => ({ eventUuid: 'evt', durable: 'table' }),
-    flush: async () => ({ apiCalls: 0, meterEvents: 0, dropped: 0 }),
-    drainSpill: async () => 0,
-    hasPendingSpill: () => false,
-    stats: () => ({ queued: 0, dropped: 0, spilled: 0, flushed: 0 }),
-    close: async () => undefined,
-  }) as unknown as TelemetryWriter;
-
-const stubBroker = (): JobBroker =>
-  createSaasJobBroker({
-    queue: {
-      async add() {
-        return 'job_1';
-      },
-      async remove() {},
-    },
-    results: createMemoryJobResultStore(),
-    logger: { info() {}, warn() {}, error() {}, debug() {} },
-  });
-
-const jobContext = (signal: AbortSignal = new AbortController().signal) => ({
-  jobId: 'job_reindex',
-  tenantId: SCOPE.tenantId,
-  instanceId: 'notes',
-  signal,
-  logger: { info() {}, warn() {}, error() {}, debug() {} },
-});
-
-let knowledge: Database;
-let system: Database;
-let searchDb: Database;
-let storage: StorageProvider;
-let search: SqliteSearchProvider;
-let runtime: CcRuntime;
-let signer: SessionSigner;
-
-const buildManifest = async (): Promise<EffectiveManifest> => {
-  // `ragChat` declares a capability dependency on `aiProvider` (verify/engines.ts),
-  // and V-stage pruning turns an undeclared capability into a disabled feature —
-  // which would silently drop the very route this suite is about.
-  const result = await verifyAppConfig({
-    config: APP_CONFIG,
-    moment: 'boot',
-    capabilities: { aiProvider: true, diskIndex: true },
-  });
-  if (!result.manifest) throw new Error(`fixture config failed to verify: ${JSON.stringify(result.diagnostics)}`);
-  return result.manifest;
-};
-
-/** Wait for CDC delivery — the tap is deliberately off the writer's stack. */
-const settleIndex = async (): Promise<void> => {
-  await storage.domain('knowledge').drainMutations();
-  // One more turn: `indexOnMutation` resolves the row and indexes it in a
-  // promise chain started by the delivery, not inside it.
-  for (let i = 0; i < 5; i += 1) await Bun.sleep(1);
-};
-
-const seed = async (count: number, prefix: string): Promise<string[]> => {
-  const domain = storage.domain('knowledge');
-  const ids: string[] = [];
-  for (let i = 0; i < count; i += 1) {
-    const record = await domain.exec(
-      createRecord(SCOPE, { type: 'note', title: `${prefix} ${i}`, bodyMd: `body of ${prefix} number ${i}` }),
-    );
-    ids.push(record.id);
-  }
-  return ids;
-};
-
-beforeEach(async () => {
-  knowledge = new Database(':memory:');
-  system = new Database(':memory:');
-  searchDb = new Database(':memory:');
-  for (const db of [knowledge, system, searchDb]) assertCcPragmas(db);
-  runNamespacedMigrations(knowledge, KNOWLEDGE_MIGRATIONS, { namespace: KNOWLEDGE_NAMESPACE });
-  runNamespacedMigrations(system, [], { namespace: 'system' });
-  runNamespacedMigrations(searchDb, SEARCH_MIGRATIONS, { namespace: SEARCH_NAMESPACE });
-
-  storage = createLocalStorageProvider({ handles: { knowledge, system } });
-  search = createSqliteSearchProvider({ db: searchDb });
-  signer = createSessionSigner({ ttlSeconds: 300 });
-  const broker = stubBroker();
-  const telemetry = noopTelemetry();
-
-  runtime = createCcRuntime({
-    manifest: await buildManifest(),
-    storage,
-    guard: signer,
-    gateway: createCognitiveGateway({ appId: 'search-demo', drivers: {}, telemetry }),
-    broker,
-    telemetry,
-    allowedOrigins: ['http://localhost:4747'],
-    // The WRITE side: the runtime taps CDC into the index.
-    search,
-    services: {
-      // The READ side: the service queries the same provider.
-      knowledge: createKnowledgeService({ storage, broker, search }),
-      system: createSystemService({ storage }),
-    },
-    meterSpillDrainIntervalMs: 0,
-  });
-});
-
-afterEach(async () => {
-  await runtime.stop();
-  for (const db of [knowledge, system, searchDb]) {
-    getTxnLifetimeGuard(db)?.dispose();
-    db.close();
-  }
-});
-
-const reindex = (signal?: AbortSignal) =>
-  createSearchJobHandlers({
-    search,
-    sources: [createKnowledgeReindexSource(storage)],
-    pageSize: 50,
-    epochSettleMs: 2,
-  }).reindex!({ corpus: KNOWLEDGE_CORPUS }, jobContext(signal) as never) as Promise<{
-    indexed: number;
-    swept: number;
-    pages: number;
-  }>;
-
-describe('search-reindex-converges — the index equals the source', () => {
-  it('rebuilds a 500-row corpus and then converges after out-of-band drift', async () => {
-    const ids = await seed(500, 'Note');
-    await settleIndex();
-
-    // The CDC tap already indexed all 500 during the seed. A rebuild is
-    // idempotent over that, and must not duplicate a single document.
-    const first = await reindex();
-    expect(first.indexed).toBe(500);
-    expect(first.swept).toBe(0);
-    // 500 rows at 50/page: `listRecords` only hands back a cursor when a next
-    // page exists, so the rebuild costs 10 reads, not 11 with an empty tail.
-    expect(first.pages).toBe(10);
-    await expect(search.count(KNOWLEDGE_CORPUS, SCOPE.tenantId)).resolves.toBe(500);
-
-    // Now DRIFT: delete 50 rows with the tap detached, exactly as a restore, a
-    // crashed worker or a maintenance script would. The index still holds them.
-    await runtime.stop();
-    const domain = storage.domain('knowledge');
-    for (const id of ids.slice(0, 50)) await domain.exec(deleteRecord(SCOPE, id));
-    await expect(search.count(KNOWLEDGE_CORPUS, SCOPE.tenantId)).resolves.toBe(500);
-
-    const second = await reindex();
-    expect(second.indexed).toBe(450);
-    expect(second.swept).toBe(50);
-    await expect(search.count(KNOWLEDGE_CORPUS, SCOPE.tenantId)).resolves.toBe(450);
-
-    // Equal, not merely the same size: no deleted id is still searchable.
-    const ghost = await search.query('"Note 0"', { tenantId: SCOPE.tenantId, limit: 10 });
-    expect(ghost.map((hit) => hit.id)).not.toContain(ids[0]);
-  });
-
-  it('never sweeps another tenant’s or another corpus’s documents', async () => {
-    await seed(5, 'Mine');
-    await settleIndex();
-    await search.index({ corpus: KNOWLEDGE_CORPUS, id: 'x1', tenantId: 't_other', title: 'Theirs', body: 'theirs' });
-    await search.index({ corpus: 'media', id: 'm1', tenantId: SCOPE.tenantId, title: 'Asset', body: 'asset' });
-
-    await reindex();
-
-    await expect(search.count(KNOWLEDGE_CORPUS, 't_other')).resolves.toBe(1);
-    await expect(search.count('media', SCOPE.tenantId)).resolves.toBe(1);
-  });
-
-  it('refuses a corpus it has no source for instead of reporting a successful no-op', async () => {
-    const handlers = createSearchJobHandlers({ search, sources: [createKnowledgeReindexSource(storage)] });
-    await expect(handlers.reindex!({ corpus: 'media' }, jobContext() as never)).rejects.toMatchObject({
-      code: 'REINDEX_CORPUS_UNKNOWN',
-    });
-    await expect(handlers.reindex!({}, jobContext() as never)).rejects.toMatchObject({
-      code: 'REINDEX_CORPUS_MISSING',
-    });
-  });
-
-  it('a cancelled rebuild deletes nothing — the sweep never runs on a partial pass', async () => {
-    await seed(20, 'Keep');
-    await settleIndex();
-    await expect(search.count(KNOWLEDGE_CORPUS, SCOPE.tenantId)).resolves.toBe(20);
-
-    const controller = new AbortController();
-    controller.abort();
-    await expect(reindex(controller.signal)).rejects.toMatchObject({ code: 'JOB_CANCELLED' });
-
-    // Every document survives: a cancelled rebuild is a no-op, not a truncation.
-    await expect(search.count(KNOWLEDGE_CORPUS, SCOPE.tenantId)).resolves.toBe(20);
-  });
-});
-
-describe('the CDC tap indexes the database, not the service', () => {
-  it('follows a write that never went through KnowledgeService', async () => {
-    const domain = storage.domain('knowledge');
-    const record = await domain.exec(createRecord(SCOPE, { type: 'note', title: 'Direct', bodyMd: 'unmediated' }));
-    await settleIndex();
-
-    const hits = await search.query('unmediated', { tenantId: SCOPE.tenantId });
-    expect(hits.map((hit) => hit.id)).toEqual([record.id]);
-  });
-
-  it('follows an update made by a job through the repository layer', async () => {
-    const domain = storage.domain('knowledge');
-    const record = await domain.exec(createRecord(SCOPE, { type: 'note', title: 'Before', bodyMd: 'stale text' }));
-    await settleIndex();
-
-    // Exactly what `createKnowledgeJobHandlers`' applyProposals does — and the
-    // path the old service-level hook could not see.
-    await domain.exec(updateRecord(SCOPE, record.id, { title: 'After' }));
-    await settleIndex();
-
-    await expect(search.query('Before', { tenantId: SCOPE.tenantId })).resolves.toEqual([]);
-    const hits = await search.query('After', { tenantId: SCOPE.tenantId });
-    expect(hits.map((hit) => hit.title)).toEqual(['After']);
-  });
-
-  it('tombstones a delete so the index cannot resurrect a removed row', async () => {
-    const domain = storage.domain('knowledge');
-    const record = await domain.exec(createRecord(SCOPE, { type: 'note', title: 'Doomed', bodyMd: 'doomed' }));
-    await settleIndex();
-    await expect(search.query('doomed', { tenantId: SCOPE.tenantId })).resolves.toHaveLength(1);
-
-    await domain.exec(deleteRecord(SCOPE, record.id));
-    await settleIndex();
-
-    await expect(search.query('doomed', { tenantId: SCOPE.tenantId })).resolves.toEqual([]);
-  });
-
-  it('an index failure never reaches the writer', async () => {
-    const failures: unknown[] = [];
-    const broken = createCcRuntime({
-      manifest: await buildManifest(),
-      storage,
-      guard: signer,
-      gateway: createCognitiveGateway({ appId: 'search-demo', drivers: {}, telemetry: noopTelemetry() }),
-      broker: stubBroker(),
-      telemetry: noopTelemetry(),
-      allowedOrigins: ['http://localhost:4747'],
-      search: {
-        async index() {
-          throw new Error('index backend is down');
-        },
-        async remove() {},
-        async query() {
-          return [];
-        },
-      },
-      onSearchIndexError: (error) => failures.push(error),
-      services: { knowledge: createKnowledgeService({ storage, broker: stubBroker() }), system: createSystemService({ storage }) },
-      meterSpillDrainIntervalMs: 0,
-    });
-
-    try {
-      // The write MUST succeed even though its indexer throws.
-      const record = await storage
-        .domain('knowledge')
-        .exec(createRecord(SCOPE, { type: 'note', title: 'Survives', bodyMd: 'survives' }));
-      await settleIndex();
-      expect(record.title).toBe('Survives');
-      expect(failures.length).toBeGreaterThan(0);
-    } finally {
-      await broken.stop();
-    }
-  });
-});
-
-describe('KnowledgeService.search over the real index', () => {
-  it('returns ranked hits through the composed server instead of the LIKE fallback', async () => {
-    const domain = storage.domain('knowledge');
-    await domain.exec(createRecord(SCOPE, { type: 'note', title: 'Sourdough', bodyMd: 'rye starter feeding' }));
-    await domain.exec(createRecord(SCOPE, { type: 'note', title: 'Unrelated', bodyMd: 'nothing about bread' }));
-    await settleIndex();
-
-    const token = signer.mint({
-      tenantId: SCOPE.tenantId,
-      userId: SCOPE.userId,
-      role: 'OWNER',
-      permissions: [],
-      privateScope: true,
-    }).token;
-
-    const response = await runtime.app.fetch(
-      new Request('http://localhost/api/knowledge/search?q=rye', {
-        headers: { authorization: `Bearer ${token}` },
-      }),
-    );
-    expect(response.status).toBe(200);
-    const body = (await response.json()) as { items: { title: string }[] };
-    expect(body.items.map((item) => item.title)).toEqual(['Sourdough']);
-  });
-});

package/src/server/runtime/serveCcApp.ts

@@ -1,77 +0,0 @@
-/**
- * `Bun.serve` for a composed cc app, with the shutdown discipline the framework
- * already assumes elsewhere.
- *
- * Three things happen on the way down, in this order, and the order is the
- * point:
- *
- *   1. **Stop accepting**, so no new request enters a runtime that is tearing
- *      down its storage.
- *   2. **Sweep the ExecutionDriver's children.** A killed dev server that leaves
- *      a tracked child alive leaves it squatting the port it claimed — the
- *      zombie-port state 04 §5.7 calls structurally impossible only because
- *      something actually runs the sweep.
- *   3. **Flush telemetry, then release the runtime.** Metrics still in the queue
- *      are lost otherwise, and `meter_events` may never be dropped (01 §4.1).
- */
-import type { TelemetryWriter } from 'cwip/telemetry';
-import type { ExecutionDriver } from '../drivers';
-import type { CcRuntime } from './createCcRuntime';
-
-export interface ServeCcAppOptions {
-  runtime: CcRuntime;
-  port: number;
-  hostname?: string;
-  /** Swept on shutdown. Pass the same driver the runtime was given. */
-  exec?: ExecutionDriver;
-  telemetry?: TelemetryWriter;
-  /**
-   * Install SIGINT/SIGTERM handlers. Default true — a server that does not clean
-   * up on Ctrl-C is how zombie children accumulate during development.
-   */
-  bindSignals?: boolean;
-  /** Bun.serve seam, for tests. */
-  serve?: (options: { port: number; hostname?: string; fetch: (request: Request) => Response | Promise<Response> }) => {
-    port: number;
-    stop: (closeActiveConnections?: boolean) => void;
-  };
-}
-
-export interface CcServer {
-  port: number;
-  /** Idempotent. Safe to call from a signal handler and again from a test. */
-  stop(): Promise<void>;
-}
-
-export function serveCcApp(options: ServeCcAppOptions): CcServer {
-  const serve =
-    options.serve ??
-    ((init) =>
-      (Bun.serve as unknown as (arg: typeof init) => { port: number; stop: (force?: boolean) => void })(init));
-
-  const server = serve({
-    port: options.port,
-    hostname: options.hostname,
-    fetch: (request: Request) => options.runtime.app.fetch(request),
-  });
-
-  let stopped = false;
-  const stop = async (): Promise<void> => {
-    if (stopped) return;
-    stopped = true;
-    server.stop(true);
-    options.exec?.sweep();
-    await options.telemetry?.flush?.();
-    await options.runtime.stop();
-  };
-
-  if (options.bindSignals !== false) {
-    const onSignal = (): void => {
-      void stop().finally(() => process.exit(0));
-    };
-    process.once('SIGINT', onSignal);
-    process.once('SIGTERM', onSignal);
-  }
-
-  return { port: server.port, stop };
-}

package/src/server/runtime/staticAssets.ts

@@ -1,205 +0,0 @@
-/**
- * The generated app's static tier (02 §1.3) — the client bundle and `index.html`
- * served under the SAME pinned CSP as the API.
- *
- * The requirement reads "one `buildCsp` source shared by the API middleware and
- * the static server so they cannot drift". The strongest way to satisfy that is
- * not to share a function — it is to **share the middleware**: these routes mount
- * onto the runtime's OWN Hono app, so `coreMixin`'s exit middleware (which sets
- * the CSP after `next()` returns, unconditionally) stamps the HTML response with
- * the identical header string it stamps on `/api/core/health`. There is no second
- * call to `buildCsp` anywhere in the static path, so there is nothing to drift.
- *
- * That matters concretely: the compiled `connect-src` allowlist carries the saas
- * ObjectStore public host and every declared model endpoint. If the HTML shell
- * were served with a hand-written policy, presigned media URLs and AI calls would
- * be blocked in the browser at first use, while every server-side test passed.
- *
- * Two more properties are encoded here:
- *
- *   * **SPA fallback, never API fallback.** A request under `/api/` that matched
- *     no route must stay a 404. Falling back to `index.html` there turns a typo'd
- *     endpoint into a 200 of HTML, which clients parse as "success" and report as
- *     a bizarre JSON error three layers away.
- *   * **Degraded boot serves the error page** (02 §4 / V7.6). When the live config
- *     failed verification and the app is running its last-good bundle, the HTML
- *     route renders diagnostics instead of the app. The API stays up — the running
- *     surface is still the last-good one, and taking it down would punish users
- *     for an operator's typo.
- */
-import path from 'node:path';
-import {
-  type CacheOverrides,
-  cacheControlFor as fleetCacheControlFor,
-  isNotModified,
-  notModifiedResponse,
-  strongEtag,
-} from 'cwip/http';
-import { resolveWithinRoot } from 'cwip/node';
-import type { CCHono } from '../mixins/types';
-
-export interface MountStaticAssetsOptions {
-  /**
-   * The runtime's app. Mounting HERE (rather than on a second Hono) is what makes
-   * the static CSP identical to the API CSP by construction.
-   */
-  readonly app: CCHono;
-  /** Directory holding the built client (`index.html`, `assets/*`). */
-  readonly root: string;
-  /**
-   * Rendered on the HTML route instead of `index.html` while the app is degraded.
-   * A function so the caller can re-render as the state changes.
-   */
-  readonly errorPage?: () => string | null;
-  /** Path prefix that must NEVER fall back to the SPA shell. Default `/api/`. */
-  readonly apiPrefix?: string;
-  /** File reader seam (tests). Default: `Bun.file`. */
-  readonly readFile?: (file: string) => { exists(): Promise<boolean>; text(): Promise<string>; type: string; stream(): ReadableStream };
-  /**
-   * This app's deviations from the fleet static-cache policy, keyed by CLASS.
-   * Keyed by class rather than by path on purpose: a path-keyed override is a
-   * fourth copy of the classifier, which is the drift this file just stopped
-   * contributing to.
-   */
-  readonly cacheOverrides?: CacheOverrides;
-  /**
-   * SHA-256 of a served file's bytes, hex — the source of the strong ETag that
-   * makes the `no-cache` tier cost a 304 instead of a full body.
-   *
-   * 🔴 Optional, and absent means "no ETag", never "refuse the file". A generated
-   * app that has no manifest keeps exactly today's behaviour. The satellites
-   * supply this from the build's `.asset-manifest.json`; see
-   * `cwip/node`'s `staticManifest.ts`.
-   */
-   readonly contentHash?: (urlPath: string) => string | null;
-}
-
-/** Extension → content type for the handful a client bundle actually emits. */
-const CONTENT_TYPES: Readonly<Record<string, string>> = {
-  '.html': 'text/html; charset=utf-8',
-  '.js': 'text/javascript; charset=utf-8',
-  '.mjs': 'text/javascript; charset=utf-8',
-  '.css': 'text/css; charset=utf-8',
-  '.json': 'application/json; charset=utf-8',
-  '.svg': 'image/svg+xml',
-  '.png': 'image/png',
-  '.jpg': 'image/jpeg',
-  '.jpeg': 'image/jpeg',
-  '.webp': 'image/webp',
-  '.ico': 'image/x-icon',
-  '.woff2': 'font/woff2',
-  '.map': 'application/json; charset=utf-8',
-};
-
-/**
- * 🔴 The rule that makes a deploy VISIBLE — now the FLEET's rule, not this file's.
- *
- * This tier used to send no `Cache-Control` at all, and "no header" does not
- * mean "not cached" once a CDN is in front: Cloudflare applied its default
- * 4-hour Browser Cache TTL by extension, so `/main.js` was served from the edge
- * for up to four hours after a deploy. `index.html` stayed uncached (`DYNAMIC`),
- * which produced the worst possible pairing — the NEW shell requesting the OLD
- * entry chunk. Measured on app.cursedalchemy.com: a fresh deploy's own smoke
- * passed (it reads the origin) while the site served the previous bundle, and a
- * `?cb=` cache-buster returned a completely different `main-*.js` graph.
- *
- * The fix — split hashed emits from entry files, by name and not by luck — was
- * right, and it was also written THREE TIMES: here as a `-<hash>.<ext>` regex,
- * in `@satellites/satellite-kit` as an `/assets/` PREFIX test, and a third time
- * inside satellite-kit's Cloudflare `_headers` writer. They had already drifted,
- * and the drift cost real money: the prefix rule sent every unhashed byte a
- * satellite served — 46 MB of libretro cores, every sprite, every font — into
- * the revalidate bucket, where Cloudflare refused to cache it at all.
- *
- * So on 2026-08-23 the rule moved down to `cwip/http`, the layer both consumers
- * already import from — the same treatment the duplicated `resolveWithinRoot`
- * got on 2026-08-02, and for the same reason. This function is now a named
- * pass-through so existing importers keep working; the classes, the windows and
- * the evidence for each live in `cwip/src/core/http/staticCache.ts`.
- *
- * What changed for THIS tier as a result: an unhashed `.woff2`/`.png`/`.wasm` is
- * no longer `no-cache` — it is `durable` (a short browser ttl, a long shared one
- * backed by a deploy-time purge), while `index.html` and any unhashed `.js`/
- * `.css` still revalidate exactly as before.
- */
-export const cacheControlFor = (urlPath: string, overrides?: CacheOverrides): string =>
-  fleetCacheControlFor(urlPath, overrides);
-
-/**
- * Resolve a URL path to a file inside `root`, or null when it escapes.
- *
- * The traversal guard itself now lives ONCE, in `cwip/node`'s `resolveWithinRoot` —
- * this repo and `@satellites/satellite-kit` each had their own copy until 2026-08-02,
- * which is one copy too many for the check that decides whether `/etc/passwd` is
- * servable. `requireFile: false` keeps this function's contract: it answers "is this
- * path legal", and {@link mountStaticAssets} decides whether the file is actually
- * there (it reads through an injectable `readFile`, so it must not stat the real disk
- * here).
- */
-export function resolveStaticFile(root: string, urlPath: string): string | null {
-  return resolveWithinRoot(root, urlPath, { requireFile: false });
-}
-
-export function mountStaticAssets(options: MountStaticAssetsOptions): void {
-  const { app, root } = options;
-  const apiPrefix = options.apiPrefix ?? '/api/';
-  const overrides = options.cacheOverrides;
-  const cacheControl = (urlPath: string): string => cacheControlFor(urlPath, overrides);
-  // A strong ETag when the caller can supply the bytes' hash, nothing otherwise.
-  // `no-cache` is only a good deal when the revalidation can end in a 304; a tier
-  // that answers a conditional request with the whole body has bought a round
-  // trip and saved nothing. See cwip's `staticValidators.ts` for the measurement.
-  const validatorsFor = (urlPath: string): { etag?: string } => {
-    const hash = options.contentHash?.(urlPath) ?? null;
-    return hash ? { etag: strongEtag(hash) } : {};
-  };
-  const readFile = options.readFile ?? ((file: string) => Bun.file(file) as unknown as ReturnType<NonNullable<MountStaticAssetsOptions['readFile']>>);
-
-  const html = async (): Promise<Response> => {
-    const degraded = options.errorPage?.() ?? null;
-    if (degraded !== null)
-      // 503: the app is NOT serving what the config asked for. A 200 here would
-      // let a deploy health check call a degraded app healthy.
-      return new Response(degraded, {
-        status: 503,
-        headers: { 'Content-Type': CONTENT_TYPES['.html'] as string, 'Cache-Control': 'no-store' },
-      });
-    const index = readFile(path.join(path.resolve(root), 'index.html'));
-    if (!(await index.exists()))
-      return new Response('index.html is missing from the client build — run the generator with --build-client.', {
-        status: 500,
-        headers: { 'Content-Type': 'text/plain; charset=utf-8' },
-      });
-    return new Response(await index.text(), {
-      headers: { 'Content-Type': CONTENT_TYPES['.html'] as string, 'Cache-Control': cacheControl('/index.html') },
-    });
-  };
-
-  app.get('*', async (c) => {
-    const urlPath = new URL(c.req.url).pathname;
-    // An unmatched API path is a 404, never the SPA shell.
-    if (urlPath === apiPrefix.replace(/\/$/, '') || urlPath.startsWith(apiPrefix)) return c.notFound();
-    if (urlPath === '/' || urlPath === '/index.html') return html();
-
-    const file = resolveStaticFile(root, urlPath);
-    if (file === null) return c.notFound();
-    const asset = readFile(file);
-    if (await asset.exists()) {
-      const validators = validatorsFor(urlPath);
-      const cc = cacheControl(urlPath);
-      // The whole point: a client that still holds these bytes pays a header
-      // exchange rather than the body.
-      if (validators.etag && isNotModified(c.req.raw.headers, validators)) return notModifiedResponse(validators, cc);
-      const type = CONTENT_TYPES[path.extname(file).toLowerCase()] ?? asset.type ?? 'application/octet-stream';
-      const headers = new Headers({ 'Content-Type': type, 'Cache-Control': cc });
-      if (validators.etag) headers.set('ETag', validators.etag);
-      // Declared or not, these bodies vary by encoding; a shared cache that does
-      // not know it may hand a gzip body to a client that never asked for one.
-      headers.set('Vary', 'accept-encoding');
-      return new Response(asset.stream(), { headers });
-    }
-    // Deep links (`/notes/abc`, `/go/<locator>`) are client routes: the shell
-    // resolves them, so an unknown non-file path renders the SPA.
-    return html();
-  });
-}