@fuzdev/fuz_app 0.67.0 → 0.68.0

package/dist/server/file_fact_fetcher.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Filesystem-backed `FactExternalFetcher`.
+ *
+ * Resolves `file:<shard>/<rest>` external URLs against a configured
+ * facts directory. The URL shape is the canonical relative-path scheme:
+ * 2 hex chars for the shard subdir + 62 hex chars for the rest of the
+ * blake3 hash (64 hex chars total). Files live at
+ * `<facts_dir>/<shard>/<rest>` after the writer atomically temp+renames
+ * them in.
+ *
+ * **Pre-filter regex**: `^file:[0-9a-f]{2}/[0-9a-f]{62}$`. A `..`
+ * segment can't match (`.` isn't in `[0-9a-f]`); neither can absolute
+ * paths, query strings, or any non-hex character. Defense-in-depth in
+ * front of `path.join` — the fetcher never trusts the URL came from a
+ * fact row, even though it always does in practice.
+ *
+ * The fetcher does NOT verify hash content — `PgFactStore.get` calls
+ * `fact_hash_verify(hash, bytes)` after the fetch and returns null on
+ * mismatch.
+ *
+ * Runtime: uses `node:fs/promises` + `node:fs` `createReadStream` so
+ * the same code works under Deno (via node compat) and vitest.
+ *
+ * @module
+ */
+import type { FactExternalFetcher } from '../db/fact_store.js';
+/** Construction options. */
+export interface FileFactFetcherOptions {
+    /**
+     * Absolute path to the facts directory. Files resolve to
+     * `<facts_dir>/<shard>/<rest>`.
+     */
+    facts_dir: string;
+}
+/**
+ * Build a `FactExternalFetcher` that resolves `file:` URLs against the
+ * filesystem. Throws on a malformed URL before touching the disk so
+ * `PgFactStore.get` logs the warning + returns null without an I/O
+ * round-trip on bad data.
+ */
+export declare const create_file_fact_fetcher: (options: FileFactFetcherOptions) => FactExternalFetcher;
+//# sourceMappingURL=file_fact_fetcher.d.ts.map

package/dist/server/file_fact_fetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file_fact_fetcher.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/file_fact_fetcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAOH,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,qBAAqB,CAAC;AAG7D,4BAA4B;AAC5B,MAAM,WAAW,sBAAsB;IACtC;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,GAAI,SAAS,sBAAsB,KAAG,mBA0B1E,CAAC"}

package/dist/server/file_fact_fetcher.js

@@ -0,0 +1,60 @@
+/**
+ * Filesystem-backed `FactExternalFetcher`.
+ *
+ * Resolves `file:<shard>/<rest>` external URLs against a configured
+ * facts directory. The URL shape is the canonical relative-path scheme:
+ * 2 hex chars for the shard subdir + 62 hex chars for the rest of the
+ * blake3 hash (64 hex chars total). Files live at
+ * `<facts_dir>/<shard>/<rest>` after the writer atomically temp+renames
+ * them in.
+ *
+ * **Pre-filter regex**: `^file:[0-9a-f]{2}/[0-9a-f]{62}$`. A `..`
+ * segment can't match (`.` isn't in `[0-9a-f]`); neither can absolute
+ * paths, query strings, or any non-hex character. Defense-in-depth in
+ * front of `path.join` — the fetcher never trusts the URL came from a
+ * fact row, even though it always does in practice.
+ *
+ * The fetcher does NOT verify hash content — `PgFactStore.get` calls
+ * `fact_hash_verify(hash, bytes)` after the fetch and returns null on
+ * mismatch.
+ *
+ * Runtime: uses `node:fs/promises` + `node:fs` `createReadStream` so
+ * the same code works under Deno (via node compat) and vitest.
+ *
+ * @module
+ */
+import { readFile } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
+import { Readable } from 'node:stream';
+import { join } from 'node:path';
+import { parse_file_fact_url } from './file_fact_url.js';
+/**
+ * Build a `FactExternalFetcher` that resolves `file:` URLs against the
+ * filesystem. Throws on a malformed URL before touching the disk so
+ * `PgFactStore.get` logs the warning + returns null without an I/O
+ * round-trip on bad data.
+ */
+export const create_file_fact_fetcher = (options) => {
+    const { facts_dir } = options;
+    const resolve_path = (url) => {
+        const parsed = parse_file_fact_url(url);
+        if (!parsed) {
+            throw new Error(`invalid file fact url: ${url}`);
+        }
+        return join(facts_dir, parsed.shard, parsed.rest);
+    };
+    return {
+        fetch_bytes: async (url) => {
+            const path = resolve_path(url);
+            const buf = await readFile(path);
+            return new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength);
+        },
+        // `Promise.resolve().then(...)` (rather than `async`) funnels any
+        // `resolve_path` throw into a rejection without an unused `await`.
+        fetch_stream: (url) => Promise.resolve().then(() => {
+            const path = resolve_path(url);
+            const node_stream = createReadStream(path);
+            return Readable.toWeb(node_stream);
+        }),
+    };
+};

package/dist/server/file_fact_url.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Canonical filesystem-fact URL shape.
+ *
+ * `external_url` on the generic `facts` row is `string | null` because the
+ * `FactStore` interface stays federation-friendly (future
+ * `https://...` / `s3://...` shapes). Filesystem-minted URLs are exactly
+ * `file:<shard>/<rest>` where `<shard>` is the first 2 hex chars of the
+ * blake3 digest and `<rest>` the remaining 62 — files land at
+ * `<facts_dir>/<shard>/<rest>` after the writer atomically temp+renames
+ * them in.
+ *
+ * Centralizing the regex keeps the shape in one place: the `serve_fact_route`
+ * defense-in-depth check and the `file_fact_fetcher` resolver both validate
+ * against it, so federation work that loosens or extends the shape (e.g.,
+ * admitting `https://`) updates one place, not several.
+ *
+ * Defense-in-depth: a `..` segment can't match (`.` isn't in `[0-9a-f]`),
+ * neither can absolute paths, query strings, or any non-hex character.
+ * Used in front of `path.join` so the resolver never trusts the URL came
+ * from a fact row, even though it always does in practice.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/** Anchored, capture-group form: `^file:(<shard>)/(<rest>)$`. */
+export declare const FILE_FACT_URL_PATTERN: RegExp;
+/**
+ * Branded URL form. Construct only via `parse_file_fact_url` or
+ * `mint_file_fact_url` — those are the validated boundaries. Direct
+ * string literals don't satisfy the brand.
+ */
+export declare const FileFactUrl: z.core.$ZodBranded<z.ZodString, "FileFactUrl", "out">;
+export type FileFactUrl = z.infer<typeof FileFactUrl>;
+/** Type guard. Useful when discriminating a `string | null` column. */
+export declare const is_file_fact_url: (s: string) => s is FileFactUrl;
+/**
+ * Validate a string against the canonical shape. Returns the branded URL
+ * plus its parsed parts, or `null` on shape mismatch — callers decide
+ * whether that's a 404 (read), a skip (GC), or a hard reject (write).
+ */
+export declare const parse_file_fact_url: (url: string) => {
+    url: FileFactUrl;
+    shard: string;
+    rest: string;
+} | null;
+/**
+ * Construct a canonical `file:<shard>/<rest>` URL. The writer side
+ * (`server/fact_write.ts`) assembles the shape from a freshly-computed
+ * hash; this helper centralizes the literal so a future shape change is
+ * a single edit.
+ */
+export declare const mint_file_fact_url: (shard: string, rest: string) => FileFactUrl;
+//# sourceMappingURL=file_fact_url.d.ts.map

package/dist/server/file_fact_url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file_fact_url.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/file_fact_url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,iEAAiE;AACjE,eAAO,MAAM,qBAAqB,QAAyC,CAAC;AAE5E;;;;GAIG;AACH,eAAO,MAAM,WAAW,uDAA+D,CAAC;AACxF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,uEAAuE;AACvE,eAAO,MAAM,gBAAgB,GAAI,GAAG,MAAM,KAAG,CAAC,IAAI,WAA4C,CAAC;AAE/F;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAC/B,KAAK,MAAM,KACT;IAAC,GAAG,EAAE,WAAW,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAC,GAAG,IAIpD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,EAAE,MAAM,MAAM,KAAG,WAC1B,CAAC"}

package/dist/server/file_fact_url.js

@@ -0,0 +1,52 @@
+/**
+ * Canonical filesystem-fact URL shape.
+ *
+ * `external_url` on the generic `facts` row is `string | null` because the
+ * `FactStore` interface stays federation-friendly (future
+ * `https://...` / `s3://...` shapes). Filesystem-minted URLs are exactly
+ * `file:<shard>/<rest>` where `<shard>` is the first 2 hex chars of the
+ * blake3 digest and `<rest>` the remaining 62 — files land at
+ * `<facts_dir>/<shard>/<rest>` after the writer atomically temp+renames
+ * them in.
+ *
+ * Centralizing the regex keeps the shape in one place: the `serve_fact_route`
+ * defense-in-depth check and the `file_fact_fetcher` resolver both validate
+ * against it, so federation work that loosens or extends the shape (e.g.,
+ * admitting `https://`) updates one place, not several.
+ *
+ * Defense-in-depth: a `..` segment can't match (`.` isn't in `[0-9a-f]`),
+ * neither can absolute paths, query strings, or any non-hex character.
+ * Used in front of `path.join` so the resolver never trusts the URL came
+ * from a fact row, even though it always does in practice.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/** Anchored, capture-group form: `^file:(<shard>)/(<rest>)$`. */
+export const FILE_FACT_URL_PATTERN = /^file:([0-9a-f]{2})\/([0-9a-f]{62})$/;
+/**
+ * Branded URL form. Construct only via `parse_file_fact_url` or
+ * `mint_file_fact_url` — those are the validated boundaries. Direct
+ * string literals don't satisfy the brand.
+ */
+export const FileFactUrl = z.string().regex(FILE_FACT_URL_PATTERN).brand('FileFactUrl');
+/** Type guard. Useful when discriminating a `string | null` column. */
+export const is_file_fact_url = (s) => FILE_FACT_URL_PATTERN.test(s);
+/**
+ * Validate a string against the canonical shape. Returns the branded URL
+ * plus its parsed parts, or `null` on shape mismatch — callers decide
+ * whether that's a 404 (read), a skip (GC), or a hard reject (write).
+ */
+export const parse_file_fact_url = (url) => {
+    const m = FILE_FACT_URL_PATTERN.exec(url);
+    if (!m)
+        return null;
+    return { url: url, shard: m[1], rest: m[2] };
+};
+/**
+ * Construct a canonical `file:<shard>/<rest>` URL. The writer side
+ * (`server/fact_write.ts`) assembles the shape from a freshly-computed
+ * hash; this helper centralizes the literal so a future shape change is
+ * a single edit.
+ */
+export const mint_file_fact_url = (shard, rest) => `file:${shard}/${rest}`;

package/dist/server/serve_fact_route.d.ts

@@ -0,0 +1,78 @@
+/**
+ * `GET /api/facts/:hash` — content-addressed fact serving.
+ *
+ * Resolves a fact hash to the bytes referenced by at least one viewable
+ * cell. Embedded facts stream from the `facts.bytes` PG column;
+ * external facts (filesystem-backed `file:<shard>/<rest>` URLs) either
+ * return an `X-Accel-Redirect` header pointing into nginx's internal
+ * facts location (production) or stream from disk via the filesystem
+ * `FactExternalFetcher` (dev / tests). The runtime mode is selected by
+ * the optional `x_accel_redirect_prefix` factory option — set in prod,
+ * unset in dev.
+ *
+ * REST, not RPC: binary responses don't fit the JSON-RPC envelope.
+ *
+ * ## Authorization
+ *
+ * Auth is `{account: 'none', actor: 'none'}` — the dispatcher's
+ * authorization phase is skipped for pure-public routes, so this handler
+ * builds the `RequestContext` itself from `c.var.account_id` (populated
+ * by the `/api/*` session middleware) by resolving the caller's single
+ * actor and loading their role_grants. Unauthed callers pass through
+ * with `req_ctx: null`. Viewers are admitted via `can_view_cell` over
+ * **every** active cell that references the hash. Multi-actor accounts
+ * fall through with `req_ctx: null` — there's no `acting?` slot on a
+ * pure-public route, so multi-actor callers are treated as anonymous
+ * (admitted only by the public-visibility branch). A fact is viewable iff
+ * at least one referencing cell admits the caller; unauthenticated callers
+ * are admitted only via a referencing cell with `cell.visibility ===
+ * 'public'`. Facts with no referencing active cell are unreachable here —
+ * orphan-fact GC reaps them separately.
+ *
+ * 404 is the universal "not viewable" response: missing fact, missing
+ * referencing cell, all referencing cells private to other actors. We
+ * deliberately don't distinguish 403 from 404 — the existence of a
+ * private hash should not leak through the public surface.
+ *
+ * ## Defense-in-depth
+ *
+ * The `external_url` regex is re-validated before issuing
+ * `X-Accel-Redirect` even though `PgFactStore.put_ref` only writes
+ * `file:<shard>/<rest>`-shaped URLs. A future row-injection bug
+ * upstream would otherwise hand nginx an attacker-controlled path.
+ *
+ * @module
+ */
+import type { Logger } from '@fuzdev/fuz_util/log.js';
+import { type RouteSpec } from '../http/route_spec.js';
+import type { AppDeps } from '../auth/deps.js';
+export interface CreateServeFactRouteSpecOptions {
+    /**
+     * App deps reference. Currently unused at handler time (cell + fact
+     * tables are read via `RouteContext.db`); kept on the factory
+     * signature for symmetry with sibling route factories and to give
+     * future role_grant-scoped viewer extensions somewhere to read other
+     * deps without changing the public shape.
+     */
+    deps: AppDeps;
+    /** Absolute path of the facts directory. Used for the dev/test streaming path. */
+    facts_dir: string;
+    /**
+     * When set, external facts return an `X-Accel-Redirect` pointing at
+     * `${prefix}<shard>/<rest>` — nginx's internal facts location serves
+     * the bytes. When unset, external facts stream from
+     * `<facts_dir>/<shard>/<rest>` directly. Production sets this (e.g.
+     * `/_facts/`); tests + dev leave it unset.
+     */
+    x_accel_redirect_prefix?: string;
+    log: Logger;
+}
+/**
+ * Build the `GET /api/facts/:hash` `RouteSpec`.
+ *
+ * Pure-public auth — the handler builds the per-request `RequestContext`
+ * from `c.var.account_id` and enforces visibility per-fact via the
+ * cell-walk above.
+ */
+export declare const create_serve_fact_route_spec: (options: CreateServeFactRouteSpecOptions) => RouteSpec;
+//# sourceMappingURL=serve_fact_route.d.ts.map

package/dist/server/serve_fact_route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve_fact_route.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/serve_fact_route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAKH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAOpD,OAAO,EAAmB,KAAK,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAEvE,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,iBAAiB,CAAC;AAoB7C,MAAM,WAAW,+BAA+B;IAC/C;;;;;;OAMG;IACH,IAAI,EAAE,OAAO,CAAC;IACd,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;OAMG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,GAAG,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;GAMG;AACH,eAAO,MAAM,4BAA4B,GACxC,SAAS,+BAA+B,KACtC,SAgIF,CAAC"}

package/dist/server/serve_fact_route.js

@@ -0,0 +1,205 @@
+/**
+ * `GET /api/facts/:hash` — content-addressed fact serving.
+ *
+ * Resolves a fact hash to the bytes referenced by at least one viewable
+ * cell. Embedded facts stream from the `facts.bytes` PG column;
+ * external facts (filesystem-backed `file:<shard>/<rest>` URLs) either
+ * return an `X-Accel-Redirect` header pointing into nginx's internal
+ * facts location (production) or stream from disk via the filesystem
+ * `FactExternalFetcher` (dev / tests). The runtime mode is selected by
+ * the optional `x_accel_redirect_prefix` factory option — set in prod,
+ * unset in dev.
+ *
+ * REST, not RPC: binary responses don't fit the JSON-RPC envelope.
+ *
+ * ## Authorization
+ *
+ * Auth is `{account: 'none', actor: 'none'}` — the dispatcher's
+ * authorization phase is skipped for pure-public routes, so this handler
+ * builds the `RequestContext` itself from `c.var.account_id` (populated
+ * by the `/api/*` session middleware) by resolving the caller's single
+ * actor and loading their role_grants. Unauthed callers pass through
+ * with `req_ctx: null`. Viewers are admitted via `can_view_cell` over
+ * **every** active cell that references the hash. Multi-actor accounts
+ * fall through with `req_ctx: null` — there's no `acting?` slot on a
+ * pure-public route, so multi-actor callers are treated as anonymous
+ * (admitted only by the public-visibility branch). A fact is viewable iff
+ * at least one referencing cell admits the caller; unauthenticated callers
+ * are admitted only via a referencing cell with `cell.visibility ===
+ * 'public'`. Facts with no referencing active cell are unreachable here —
+ * orphan-fact GC reaps them separately.
+ *
+ * 404 is the universal "not viewable" response: missing fact, missing
+ * referencing cell, all referencing cells private to other actors. We
+ * deliberately don't distinguish 403 from 404 — the existence of a
+ * private hash should not leak through the public surface.
+ *
+ * ## Defense-in-depth
+ *
+ * The `external_url` regex is re-validated before issuing
+ * `X-Accel-Redirect` even though `PgFactStore.put_ref` only writes
+ * `file:<shard>/<rest>`-shaped URLs. A future row-injection bug
+ * upstream would otherwise hand nginx an attacker-controlled path.
+ *
+ * @module
+ */
+import { createReadStream } from 'node:fs';
+import { Readable } from 'node:stream';
+import { join } from 'node:path';
+import { FactHashSchema } from '@fuzdev/fuz_util/fact_hash.js';
+import { z } from 'zod';
+import { build_request_context } from '../auth/request_context.js';
+import { ACCOUNT_ID_KEY } from '../hono_context.js';
+import { query_actors_by_account } from '../auth/account_queries.js';
+import { get_route_params } from '../http/route_spec.js';
+import { ERROR_INVALID_ROUTE_PARAMS } from '../http/error_schemas.js';
+import { query_get_fact, query_get_fact_meta } from '../db/fact_queries.js';
+import { query_cell_list_by_ref } from '../db/cell_queries.js';
+import { query_cell_grant_list_for_cell } from '../db/cell_grant_queries.js';
+import { can_view_cell } from '../auth/cell_authorize.js';
+import { parse_file_fact_url } from './file_fact_url.js';
+/** `Cache-Control` for fact responses — 5 min revocation window. */
+const CACHE_CONTROL = 'private, max-age=300';
+/**
+ * Path-param schema. Matching the canonical fact-hash form here pushes
+ * malformed-hash 400s through the framework's standard params-validation
+ * error shape (`ERROR_INVALID_ROUTE_PARAMS`), which the round-trip
+ * validator expects.
+ */
+const params_schema = z.strictObject({
+    hash: FactHashSchema,
+});
+/**
+ * Build the `GET /api/facts/:hash` `RouteSpec`.
+ *
+ * Pure-public auth — the handler builds the per-request `RequestContext`
+ * from `c.var.account_id` and enforces visibility per-fact via the
+ * cell-walk above.
+ */
+export const create_serve_fact_route_spec = (options) => {
+    const { facts_dir, x_accel_redirect_prefix, log } = options;
+    return {
+        method: 'GET',
+        path: '/api/facts/:hash',
+        auth: { account: 'none', actor: 'none' },
+        description: 'Serve content-addressed fact bytes. 404 unless at least one referencing cell admits the caller via can_view_cell.',
+        params: params_schema,
+        input: z.null(),
+        // The body is a binary stream; no JSON output schema applies.
+        output: z.null(),
+        errors: {
+            // Tighten the auto-derived 400 from `ApiError` (`error: string`) to
+            // the actual literal emitted by `create_params_validation`, so
+            // `assert_error_schema_tightness` reads the surface as specific
+            // rather than generic.
+            400: z.looseObject({
+                error: z.literal(ERROR_INVALID_ROUTE_PARAMS),
+                issues: z.array(z.unknown()),
+            }),
+        },
+        handler: async (c, route) => {
+            const { hash } = get_route_params(c);
+            const meta = await query_get_fact_meta({ db: route.db }, hash);
+            if (!meta) {
+                return c.body(null, 404);
+            }
+            // Pure-public route — dispatcher skips the authorization phase, so
+            // build the `RequestContext` here from the session-middleware-set
+            // account id. Multi-actor accounts fall through with `null` (no
+            // `acting?` slot on a public route to disambiguate); single-actor
+            // accounts resolve their actor and role_grants for owner / grant /
+            // admin admission paths.
+            const account_id = c.get(ACCOUNT_ID_KEY);
+            let req_ctx = null;
+            if (account_id) {
+                const actors = await query_actors_by_account({ db: route.db }, account_id);
+                if (actors.length === 1) {
+                    req_ctx = await build_request_context({ db: route.db }, account_id, actors[0].id);
+                }
+            }
+            // `include_grant_count: false` — the authz walk only reads
+            // `can_view_cell`-relevant fields, so skip the per-row grant
+            // COUNT subquery. Cheap to begin with; even cheaper now.
+            const referencing_cells = await query_cell_list_by_ref({ db: route.db }, hash, {
+                include_grant_count: false,
+            });
+            // Sequential walk with early break on first admit — preserves
+            // the original `.some()` short-circuit. Unauthenticated callers
+            // skip the grant fetch entirely since no grant can admit a null
+            // req_ctx (the only admit path is the public-visibility branch
+            // in `can_view_cell`, which doesn't need grants). Authenticated
+            // callers eat one `cell_grant` lookup per referencing cell up
+            // to the first admit; acceptable at MVP fact-serve scale.
+            // TODO: if profiling shows this hot, batch grants in one query
+            // across all referencing cells, or push the predicate into SQL.
+            let viewable = false;
+            for (const cell of referencing_cells) {
+                const grants = req_ctx
+                    ? await query_cell_grant_list_for_cell({ db: route.db }, cell.id)
+                    : null;
+                if (can_view_cell(req_ctx, cell, grants)) {
+                    viewable = true;
+                    break;
+                }
+            }
+            if (!viewable) {
+                // 404 (not 403) so existence of private hashes doesn't leak
+                // through the public surface. Same response shape as a
+                // genuinely missing fact.
+                return c.body(null, 404);
+            }
+            const content_type = meta.content_type ?? 'application/octet-stream';
+            const size = String(meta.size);
+            if (meta.external_url === null) {
+                // Embedded — bytes live in the PG row.
+                const row = await query_get_fact({ db: route.db }, hash);
+                if (!row || row.bytes === null) {
+                    // Race: meta said embedded but bytes vanished. Treat as not-found.
+                    log.warn(`serve_fact: embedded bytes missing for ${hash} (meta said embedded, row=${row ? 'present' : 'null'})`);
+                    return c.body(null, 404);
+                }
+                const bytes = to_uint8(row.bytes);
+                return c.body(bytes, 200, {
+                    'Content-Type': content_type,
+                    'Content-Length': size,
+                    'Cache-Control': CACHE_CONTROL,
+                });
+            }
+            // External — defense-in-depth re-validate the URL before trusting it
+            // to address the filesystem.
+            const parsed = parse_file_fact_url(meta.external_url);
+            if (!parsed) {
+                log.error(`serve_fact: rejecting malformed external_url for ${hash}: ${meta.external_url}`);
+                return c.body(null, 404);
+            }
+            const { shard, rest } = parsed;
+            if (x_accel_redirect_prefix !== undefined) {
+                // Production: hand off to nginx via the internal facts location.
+                return c.body(null, 200, {
+                    'Content-Type': content_type,
+                    'Content-Length': size,
+                    'Cache-Control': CACHE_CONTROL,
+                    'X-Accel-Redirect': `${x_accel_redirect_prefix}${shard}/${rest}`,
+                });
+            }
+            // Dev / tests: stream from disk. `createReadStream` errors land on the
+            // returned ReadableStream, which Hono surfaces as a 500 to the client.
+            const file_path = join(facts_dir, shard, rest);
+            const node_stream = createReadStream(file_path);
+            const web_stream = Readable.toWeb(node_stream);
+            return c.body(web_stream, 200, {
+                'Content-Type': content_type,
+                'Content-Length': size,
+                'Cache-Control': CACHE_CONTROL,
+            });
+        },
+    };
+};
+/**
+ * Coerce whatever the driver returns for BYTEA into a `Uint8Array`. Same
+ * shape as the helper in `PgFactStore.get` — `pg` returns a `Buffer`
+ * (`Uint8Array` subclass), `pglite` already returns `Uint8Array`.
+ */
+const to_uint8 = (value) => value instanceof Uint8Array && value.constructor === Uint8Array
+    ? value
+    : new Uint8Array(value.buffer, value.byteOffset, value.byteLength);

package/dist/testing/CLAUDE.md

@@ -149,7 +149,7 @@ Key module-scope values:
 
 - `stub_password_deps` — `PasswordHashDeps` hashing via `stub_hash_${password}` and verifying by equality. Deterministic, no Argon2 cost — use for every test not specifically exercising password hashing.
 - `TEST_COOKIE_SECRET` — 64-hex-char deterministic cookie secret. Produces a valid `Keyring` via `create_validated_keyring`. Never used in production — the stub guard plus fixed value is the contract.
-- `fallback_pglite_factory` — module-level PGlite factory `create_test_app_server` uses when no `db` is passed. Reuses the WASM cache via `create_pglite_factory`.
+- `fallback_pglite_factory` — module-level auth-only PGlite factory `create_test_app_server` uses when no `db` is passed. Reuses the WASM cache via `create_pglite_factory`. When `migration_namespaces` is supplied, a memoized sibling factory (keyed by namespace set) migrating `[auth_migration_ns, ...migration_namespaces]` is used instead — same shared WASM, extra tables.
 
 Two helpers share the "insert account + actor + roles + API token + session +
 cookie" flow, split by intent:
@@ -167,7 +167,7 @@ pre-keeper, lock unflipped), use `create_test_app_for_bootstrap` — pair with
 Types:
 
 - `TestAppServer extends AppBackend` — adds `account`, `actor`, `api_token`, `session_cookie`, `keyring`, `cleanup()`.
-- `TestAppServerOptions` — `session_options` (required), optional `db`, `db_type`, `password`, `username`, `password_value`, `roles`, `audit_factory`. The optional `audit_factory` defaults to `default_audit_factory` (no-listener `create_audit_emitter` over the test backend's `{db, log}`); pass a custom factory to compose `on_audit_event` / `audit_log_config`, wrap with `emit_decorator` (via `create_emit_ordering_audit_factory`), or otherwise replace the emitter. Mirrors `CreateAppBackendOptions` end-to-end — the previous `on_audit_event` / `audit_log_config` sugar was removed alongside the production rename.
+- `TestAppServerOptions` — `session_options` (required), optional `db`, `db_type`, `migration_namespaces`, `password`, `username`, `password_value`, `roles`, `audit_factory`. `migration_namespaces` runs extra namespaces after auth in the auto-created PGlite (mirrors `create_app_backend`); mutually exclusive with `db` (caller-migrated) — passing both throws. The optional `audit_factory` defaults to `default_audit_factory` (no-listener `create_audit_emitter` over the test backend's `{db, log}`); pass a custom factory to compose `on_audit_event` / `audit_log_config`, wrap with `emit_decorator` (via `create_emit_ordering_audit_factory`), or otherwise replace the emitter. Mirrors `CreateAppBackendOptions` end-to-end — the previous `on_audit_event` / `audit_log_config` sugar was removed alongside the production rename.
 - `CreateTestAppOptions extends TestAppServerOptions` — adds `create_route_specs` (required), `rpc_endpoints?: RpcEndpointsSuiteOption` (top-level only — single source of truth, symmetric with the suite-level option), `bootstrap?: BootstrapServerOptions` (top-level only — same precedent as `rpc_endpoints`), and `app_options?: SuiteAppOptions` (`Partial<AppServerOptions>` excluding the five fields the helper manages: `backend`, `session_options`, `create_route_specs`, `rpc_endpoints`, `bootstrap`).
 - `TestAccount` — `{account, actor, session_cookie, api_token, create_session_headers, create_bearer_headers}`.
 - `TestApp` — `{app, backend, surface_spec, surface, route_specs, create_session_headers, create_bearer_headers, create_daemon_token_headers, create_account, cleanup}`.
@@ -799,7 +799,11 @@ source of truth for wire-shape conformance.
 
 - `testing/cross_backend/setup.ts` — `SetupTest` / `TestFixture` /
   `TestAccountFixture` / `CreateTestAccountOptions` types,
-  `default_in_process_setup(options)` (wraps `create_test_app`), and
+  `default_in_process_setup(options)` (wraps `create_test_app`; pass
+  `migration_namespaces` for suites needing tables beyond the auth-only
+  default — the cell parity suite passes `[CELL_MIGRATION_NS]`, and
+  `create_test_app` provisions a per-test fresh db migrating
+  `[auth_migration_ns, ...migration_namespaces]`), and
   `default_in_process_suite_options(options)` (emits the full Tier 1 suite
   options bag: the `{setup_test, surface_source, capabilities}` triple plus
   `session_options` / `create_route_specs` / `rpc_endpoints` pass-through;
@@ -842,8 +846,16 @@ source of truth for wire-shape conformance.
 
 - `testing/cross_backend/capabilities.ts` — `BackendCapabilities` vocabulary
   (`bearer_auth` / `trusted_proxy` / `login_rate_limit` / `ws` / `sse` /
-  `in_process_only`), `test_if(cond, name, fn)` for capability-gated cases,
-  and `in_process_capabilities` preset.
+  `cell_crud` / `cell_relations` / `account_lifecycle` / `in_process_only`),
+  `test_if(cond, name, fn)`
+  for capability-gated cases, and `in_process_capabilities` preset. `cell_crud`
+  gates the CRUD parity suite, `cell_relations` the relation / ACL / audit
+  parity suite — both `true` on every backend that live-mounts the full cell
+  surface (TS spine binary, in-process app, Rust stub). A backend mounting only
+  plain CRUD would declare `cell_crud: true, cell_relations: false`.
+  `account_lifecycle` gates `describe_account_lifecycle_cross_tests` (the
+  `account_delete` / `account_undelete` / `account_purge` parity suite) — also
+  off the declared surface like cells, `true` on every spine.
 
 ### `cross_backend/standard.ts` — `describe_standard_cross_process_tests`
 
@@ -925,6 +937,47 @@ only — wire from a `*.cross.test.ts`. fuz_app's own wiring is
 `src/test/cross_backend/sse.cross.test.ts`; only the TS spines advertise
 `sse` (they wire `audit_log_sse`), so the Rust `spine_stub` cases `.skip`.
 
+### `cross_backend/cell_crud.ts` + `cell_relations.ts` — cell parity suites
+
+The cell-layer parity coverage is split across two sibling suites. Cells
+can't ride the generic `describe_rpc_round_trip_tests` (stateful verbs need a
+real id threaded across calls; `cell_get` has a top-level `.refine()`), so —
+like ws/sse — the full cell surface **live-mounts** on the spine RPC path but
+stays **off** `create_spine_surface_spec`, and these dedicated suites are the
+cell validators (`describe_standard_cross_process_tests`' generic round-trip
+never sees them). Both parse every success response against the verb's Zod
+**output** schema, so a TS↔Rust envelope drift fails the suite — not just a
+payload-field drift. Call-site primitives (`rpc_call` / `error_reason` /
+`expect_output` + the shared `CellCrossTestOptions`) live in
+`cross_backend/cell_cross_helpers.ts`.
+
+- **`describe_cell_crud_cross_tests`** (gates on `capabilities.cell_crud`) —
+  the create → get → update → delete → list lifecycle threading the id, plus
+  the CRUD authz matrix (owner CRUD; anon-public-only / private-404; non-owner
+  edit/read/delete → 404 IDOR mask; admin reaches any; dup active `path` → 409;
+  `path` write by non-admin → 403 on create + update; `cell_get` with no
+  id/path → `invalid_params`; null-auth `cell_list` `created_by` →
+  `invalid_params`).
+- **`describe_cell_relations_cross_tests`** (gates on
+  `capabilities.cell_relations`) — the verbs beyond CRUD: grant lifecycle
+  (actor-shaped editor grant enables edit, manage-tier `cell_grant_list`,
+  revoke), the now-reachable `cell_visibility_manage_only` 403 (editor-grant
+  holder can't flip visibility), field set / forward+reverse list / idempotent
+  delete, item insert / ordered forward+reverse list / move / idempotent
+  delete, clone shallow (shares edges) vs deep (clones children), and
+  manage-tier `cell_audit_list` (owner reads the timeline; a viewer-grant
+  holder who can `cell_get` still gets the IDOR 404). Only **actor-shaped**
+  grants are exercised — role-shaped principals need a closed role registry the
+  Rust spine deliberately lacks.
+
+Both gate `true` on TS + Rust (cells run on both, no `.skip`). Cross-process
+wiring is `src/test/cross_backend/cell.cross.test.ts` (both suites); the
+in-process legs (plain `gro test`) are `src/test/auth/cell_crud_parity.db.test.ts`
+
+- `cell_relations_parity.db.test.ts`, sharing the full-surface
+  `create_cell_parity_setup` (`cell_parity_helpers.ts`) which mounts every cell
+  verb and registers `cell_audit_events` through the audit factory.
+
 ### Cross-process plumbing (consumed by `*.cross.test.ts` suites)
 
 - `testing/cross_backend/backend_config.ts` — `BackendConfig` +

package/dist/testing/app_server.d.ts

@@ -18,6 +18,7 @@ import { type Keyring } from '../auth/keyring.js';
 import type { Db, DbType } from '../db/db.js';
 import type { PasswordHashDeps } from '../auth/password.js';
 import { type SessionOptions } from '../auth/session_cookie.js';
+import { type MigrationNamespace } from '../db/migrate.js';
 import { type AppBackend, type AuditFactory } from '../server/app_backend.js';
 import { type AppServerOptions, type AppServerContext, type BootstrapServerOptions, type BootstrapLiveOptions } from '../server/app_server.js';
 import type { AppSurface, AppSurfaceSpec } from '../http/surface.js';
@@ -146,6 +147,17 @@ export interface TestAppServerOptions {
     db?: Db;
     /** Database driver type — only used when `db` is provided. Default: `'pglite-memory'`. */
     db_type?: DbType;
+    /**
+     * Extra migration namespaces run after the builtin auth namespace in the
+     * auto-created in-memory PGlite, mirroring `create_app_backend`'s
+     * `migration_namespaces`. For suites whose backend needs tables beyond
+     * auth — the cell parity suite passes `[CELL_MIGRATION_NS]`. The harness
+     * builds + caches a fresh-per-test factory migrating
+     * `[auth_migration_ns, ...migration_namespaces]`; the reset-on-`create`
+     * gives the same fresh-db isolation as the auth-only default. Mutually
+     * exclusive with `db` (which assumes the caller already migrated).
+     */
+    migration_namespaces?: ReadonlyArray<MigrationNamespace>;
     /** Password implementation. Default: `stub_password_deps`. Pass `argon2_password_deps` for tests that exercise login. */
     password?: PasswordHashDeps;
     /** Username for the bootstrapped account. Default: `'keeper'`. */