@fuzdev/fuz_app 0.67.0 → 0.68.0

package/dist/db/fact_queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fact_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/fact_queries.ts"],"names":[],"mappings":"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"}

package/dist/db/fact_queries.js

@@ -0,0 +1,161 @@
+/**
+ * Raw queries against the `facts` and `fact_refs` tables.
+ *
+ * Convention: `deps: QueryDeps` first, no audit side effects, mutations are
+ * idempotent (`ON CONFLICT DO NOTHING`) so the same hash can be written by
+ * two callers without the second observing an error.
+ *
+ * Higher-level lifecycle (verify-on-read, JSON ref auto-extraction,
+ * embedded-vs-referenced selection) lives in `db/fact_store.ts`. Queries
+ * here are deliberately mechanical.
+ *
+ * @module
+ */
+/**
+ * Idempotently insert a fact row.
+ *
+ * `bytes` xor `external_url` per the `facts_storage_present` CHECK
+ * constraint; the caller is responsible for satisfying it (the queries
+ * layer does not second-guess). Returns `true` when a new row was
+ * inserted, `false` when a row already existed (caller can use this to
+ * decide whether to also write `fact_refs`).
+ */
+export const query_put_fact = async (deps, input) => {
+    const row = await deps.db.query_one(`INSERT INTO facts (hash, bytes, external_url, content_type, size)
+		 VALUES ($1, $2, $3, $4, $5)
+		 ON CONFLICT (hash) DO NOTHING
+		 RETURNING hash`, [input.hash, input.bytes, input.external_url, input.content_type, input.size]);
+    return row !== undefined;
+};
+/**
+ * Idempotently insert declared refs for a fact. No-ops on `(source_hash,
+ * target_hash)` collisions and skips the round trip entirely when
+ * `target_hashes` is empty.
+ */
+export const query_put_fact_refs = async (deps, source_hash, target_hashes) => {
+    if (target_hashes.length === 0)
+        return;
+    await deps.db.query(`INSERT INTO fact_refs (source_hash, target_hash)
+		 SELECT $1::text, unnest($2::text[])
+		 ON CONFLICT (source_hash, target_hash) DO NOTHING`, [source_hash, target_hashes]);
+};
+/**
+ * Fetch a fact's full row (including embedded `bytes`). Use this from
+ * `FactStore.get`; cheaper accessors live below.
+ */
+export const query_get_fact = async (deps, hash) => {
+    const row = await deps.db.query_one(`SELECT hash, bytes, external_url, content_type, size, created_at
+		 FROM facts WHERE hash = $1`, [hash]);
+    return row ?? null;
+};
+/**
+ * Fetch metadata only — skips the (potentially large) `bytes` column.
+ */
+export const query_get_fact_meta = async (deps, hash) => {
+    const row = await deps.db.query_one(`SELECT hash, external_url, content_type, size, created_at
+		 FROM facts WHERE hash = $1`, [hash]);
+    return row ?? null;
+};
+/**
+ * Cheap existence check. Backed by the `facts` PK index.
+ */
+export const query_has_fact = async (deps, hash) => {
+    const row = await deps.db.query_one(`SELECT EXISTS(SELECT 1 FROM facts WHERE hash = $1) AS exists`, [hash]);
+    return row?.exists ?? false;
+};
+/**
+ * List declared targets for a source fact. Order is unspecified; callers
+ * that need stable ordering should sort.
+ */
+export const query_get_fact_refs = async (deps, source_hash) => {
+    const rows = await deps.db.query(`SELECT target_hash FROM fact_refs WHERE source_hash = $1`, [source_hash]);
+    return rows.map((r) => r.target_hash);
+};
+/**
+ * Drop a fact row. Cascades `fact_refs` rows via the `ON DELETE CASCADE`
+ * FK on `source_hash`. Returns the deleted row's `(size, external_url)`
+ * so the caller can unlink the disk file (if any) and tally freed bytes,
+ * or `null` when no row matched (idempotent: deleting an absent fact is
+ * not an error).
+ *
+ * NOTE: this is a low-level primitive — callers MUST verify the fact is
+ * truly orphan (no referencing cell) before calling. The orphan check
+ * lives in `query_orphan_facts_*` below; the lifecycle wrapper in
+ * `PgFactStore.delete` handles the disk-file unlink.
+ */
+export const query_delete_fact = async (deps, hash) => {
+    const row = await deps.db.query_one(`DELETE FROM facts WHERE hash = $1
+		 RETURNING size, external_url`, [hash]);
+    if (!row)
+        return null;
+    return { size: Number(row.size), external_url: row.external_url };
+};
+/**
+ * Compute the "orphan facts" set: rows in `facts` where no active
+ * (non-tombstone) `cell.refs` array contains the hash.
+ *
+ * The `cell` join is deliberately app-coupled — `facts` lives in the
+ * `fuz_facts` namespace and `cell.refs` lives in `fuz_cell`, but the
+ * orphan predicate only makes sense in apps that route content through
+ * cells. When a non-cell fact consumer ever appears (signed memo
+ * outputs? external fact mirrors?) the predicate moves to a generic
+ * `fact_consumers` registry; today the cell layer is the only consumer.
+ *
+ * The `older_than` filter applies to `facts.created_at`. Pass `null`
+ * to skip the filter (used by the list-summary preview); the delete
+ * handler always passes a non-null cutoff (default 0, meaning "any
+ * orphan").
+ *
+ * @param deps - query deps
+ * @param older_than - filter to facts created before this Date (or null
+ *   to skip)
+ * @param sample_limit - row cap for the returned `sample`
+ */
+export const query_orphan_facts_list = async (deps, older_than, sample_limit) => {
+    const summary = await deps.db.query_one(`SELECT COUNT(*)::bigint AS count, COALESCE(SUM(size), 0)::bigint AS total
+		 FROM facts f
+		 WHERE NOT EXISTS (
+		   SELECT 1 FROM cell c
+		   WHERE c.refs @> ARRAY[f.hash]::text[]
+		     AND c.deleted_at IS NULL
+		 )
+		 AND ($1::timestamptz IS NULL OR f.created_at < $1::timestamptz)`, [older_than]);
+    const sample_rows = await deps.db.query(`SELECT hash, size, created_at, external_url
+		 FROM facts f
+		 WHERE NOT EXISTS (
+		   SELECT 1 FROM cell c
+		   WHERE c.refs @> ARRAY[f.hash]::text[]
+		     AND c.deleted_at IS NULL
+		 )
+		 AND ($1::timestamptz IS NULL OR f.created_at < $1::timestamptz)
+		 ORDER BY f.created_at ASC
+		 LIMIT $2`, [older_than, sample_limit]);
+    return {
+        count: Number(summary?.count ?? 0),
+        total_size_bytes: Number(summary?.total ?? 0),
+        sample: sample_rows.map((r) => ({
+            hash: r.hash,
+            size: Number(r.size),
+            created_at: typeof r.created_at === 'string' ? r.created_at : r.created_at.toISOString(),
+            external_url: r.external_url,
+        })),
+    };
+};
+/**
+ * Select the orphan-fact hashes for deletion. Returns the rows directly
+ * (no row-count limit) — callers iterate to unlink disk files. The
+ * `older_than` cutoff is required (non-null) here: bulk delete should
+ * always be operator-scoped to a time window. A "delete all" sweep
+ * passes a far-future cutoff, not `null`.
+ */
+export const query_orphan_facts_select_for_delete = async (deps, older_than) => {
+    const rows = await deps.db.query(`SELECT hash, size, external_url
+		 FROM facts f
+		 WHERE NOT EXISTS (
+		   SELECT 1 FROM cell c
+		   WHERE c.refs @> ARRAY[f.hash]::text[]
+		     AND c.deleted_at IS NULL
+		 )
+		 AND f.created_at < $1::timestamptz`, [older_than]);
+    return rows.map((r) => ({ hash: r.hash, size: Number(r.size), external_url: r.external_url }));
+};

package/dist/db/fact_store.d.ts

@@ -0,0 +1,112 @@
+/**
+ * PG-backed `FactStore` implementation.
+ *
+ * Wraps the raw queries in `db/fact_queries.ts` with the lifecycle the
+ * `FactStore` interface promises:
+ *
+ * - sync hash on `put`, stream hash on `put_ref` (counting bytes against
+ *   the caller-supplied `size`)
+ * - idempotent insert (`ON CONFLICT DO NOTHING` in the queries layer)
+ * - JSON ref auto-extraction when `content_type` signals JSON and the
+ *   caller didn't pass an explicit `refs` array
+ * - verify-on-read for external content; embedded reads skip verify
+ *   because PG storage IS the hash table
+ * - mismatched external bytes return `null` + log warning (treat as
+ *   unavailable; GC / repair is a separate concern)
+ *
+ * Embedded vs referenced split: callers route by size. `put` rejects
+ * `bytes.length > embedded_threshold` so oversized content takes the
+ * `put_ref` path explicitly. Auto-split inside `put` is a future option.
+ *
+ * Wired with a filesystem `file:`-URL fetcher (`create_file_fact_fetcher`)
+ * at server assembly: bytes ≤ threshold embed via `put`, larger bytes go
+ * through atomic temp+rename onto disk then `put_ref('file:<shard>/<rest>',
+ * size)` for verified registration.
+ *
+ * @module
+ */
+import type { QueryDeps } from './query_deps.js';
+import type { Logger } from '@fuzdev/fuz_util/log.js';
+import { type FactHash } from '@fuzdev/fuz_util/fact_hash.js';
+import type { FactMeta, FactPutOptions, FactStore } from '@fuzdev/fuz_util/fact_store.js';
+/** Default embedded-vs-referenced cutoff (1 MiB). */
+export declare const FACT_EMBEDDED_THRESHOLD_DEFAULT: number;
+/** Fetcher abstraction so tests can stub external URL retrieval. */
+export interface FactExternalFetcher {
+    fetch_stream: (url: string) => Promise<ReadableStream<Uint8Array>>;
+    fetch_bytes: (url: string) => Promise<Uint8Array>;
+}
+/** Default fetcher backed by `globalThis.fetch`. */
+export declare const create_default_fetcher: () => FactExternalFetcher;
+/**
+ * Construction-time deps for `PgFactStore`.
+ *
+ * `embedded_threshold` (bytes) is the inline-vs-external cutoff: payloads
+ * at or under it store embedded in the `facts` row, larger ones route to
+ * the external fetcher. Defaults to `FACT_EMBEDDED_THRESHOLD_DEFAULT`
+ * (1 MiB). Consumers tune it per workload — e.g. a much lower bound
+ * (~16 KiB) keeps only small JSON inline and routes image originals +
+ * thumbnails external. `fetcher` defaults to a `globalThis.fetch`-backed
+ * implementation; tests inject a stub. `log` is optional — the only call
+ * site is the verify-mismatch warning path.
+ */
+export interface PgFactStoreDeps {
+    deps: QueryDeps;
+    embedded_threshold?: number;
+    fetcher?: FactExternalFetcher;
+    log?: Logger;
+}
+/**
+ * PG-backed `FactStore`. Delegates to `db/fact_queries.ts` for I/O and adds
+ * the lifecycle layer described in the module doc.
+ */
+export declare class PgFactStore implements FactStore {
+    #private;
+    constructor(options: PgFactStoreDeps);
+    /**
+     * Store small bytes embedded in PG. Rejects oversized content so the
+     * caller routes it through `put_ref` explicitly — implicit splitting
+     * hides the size decision from the caller.
+     */
+    put(bytes: Uint8Array, options?: FactPutOptions): Promise<FactHash>;
+    /**
+     * Stream-hash external content and record `(hash, external_url, size)`.
+     * Throws when the streamed byte count disagrees with the caller's
+     * declared `size` — a size mismatch usually means the upload was
+     * truncated or the URL points at the wrong content.
+     */
+    put_ref(url: string, size: number, options?: FactPutOptions): Promise<FactHash>;
+    /**
+     * Retrieve bytes. Embedded reads return PG bytes directly; external
+     * reads fetch + verify and return `null` (with a warning log) when
+     * the bytes don't match the stored hash.
+     */
+    get(hash: FactHash): Promise<Uint8Array | null>;
+    has(hash: FactHash): Promise<boolean>;
+    get_meta(hash: FactHash): Promise<FactMeta | null>;
+    get_refs(hash: FactHash): Promise<Array<FactHash>>;
+    /**
+     * Drop a fact row. `fact_refs` rows referencing this hash as a source
+     * cascade via the FK; `fact_refs` targeting this hash do **not** —
+     * they remain as dangling pointers, consistent with the federation
+     * model where `target_hash` is intentionally not a FK.
+     *
+     * Idempotent: deleting an absent fact returns `null`. The store does
+     * NOT verify the fact is unreferenced — that policy lives one layer
+     * up (the orphan-fact admin surface in the consumer; a future GC walker).
+     *
+     * External-URL unlink is the caller's responsibility — the store
+     * doesn't know how to resolve `file:` / `s3:` / etc. URLs to a
+     * deletable handle. Caller iterates the returned `external_url`
+     * (when non-null) and dispatches to the appropriate cleanup
+     * routine. Mirrors the read-side `FactExternalFetcher` split.
+     *
+     * @returns `{size, external_url}` for the deleted row, or `null` if
+     *   no row matched the hash.
+     */
+    delete(hash: FactHash): Promise<{
+        size: number;
+        external_url: string | null;
+    } | null>;
+}
+//# sourceMappingURL=fact_store.d.ts.map

package/dist/db/fact_store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fact_store.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/fact_store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAC/C,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,EAKN,KAAK,QAAQ,EACb,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAC,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAC,MAAM,gCAAgC,CAAC;AAYxF,qDAAqD;AACrD,eAAO,MAAM,+BAA+B,QAAc,CAAC;AAE3D,oEAAoE;AACpE,MAAM,WAAW,mBAAmB;IACnC,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC,CAAC;IACnE,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CAClD;AAED,oDAAoD;AACpD,eAAO,MAAM,sBAAsB,QAAO,mBAkBxC,CAAC;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,SAAS,CAAC;IAChB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,qBAAa,WAAY,YAAW,SAAS;;gBAMhC,OAAO,EAAE,eAAe;IAOpC;;;;OAIG;IACG,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;IAoBzE;;;;;OAKG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;IAqBrF;;;;OAIG;IACG,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IA4B/C,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrC,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAWlD,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAIxD;;;;;;;;;;;;;;;;;;OAkBG;IACG,MAAM,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;KAAC,GAAG,IAAI,CAAC;CAGzF"}

package/dist/db/fact_store.js

@@ -0,0 +1,225 @@
+/**
+ * PG-backed `FactStore` implementation.
+ *
+ * Wraps the raw queries in `db/fact_queries.ts` with the lifecycle the
+ * `FactStore` interface promises:
+ *
+ * - sync hash on `put`, stream hash on `put_ref` (counting bytes against
+ *   the caller-supplied `size`)
+ * - idempotent insert (`ON CONFLICT DO NOTHING` in the queries layer)
+ * - JSON ref auto-extraction when `content_type` signals JSON and the
+ *   caller didn't pass an explicit `refs` array
+ * - verify-on-read for external content; embedded reads skip verify
+ *   because PG storage IS the hash table
+ * - mismatched external bytes return `null` + log warning (treat as
+ *   unavailable; GC / repair is a separate concern)
+ *
+ * Embedded vs referenced split: callers route by size. `put` rejects
+ * `bytes.length > embedded_threshold` so oversized content takes the
+ * `put_ref` path explicitly. Auto-split inside `put` is a future option.
+ *
+ * Wired with a filesystem `file:`-URL fetcher (`create_file_fact_fetcher`)
+ * at server assembly: bytes ≤ threshold embed via `put`, larger bytes go
+ * through atomic temp+rename onto disk then `put_ref('file:<shard>/<rest>',
+ * size)` for verified registration.
+ *
+ * @module
+ */
+import { fact_hash_bytes, fact_hash_stream, fact_hash_verify, fact_hash_extract_refs, } from '@fuzdev/fuz_util/fact_hash.js';
+import { query_delete_fact, query_get_fact, query_get_fact_meta, query_get_fact_refs, query_has_fact, query_put_fact, query_put_fact_refs, } from './fact_queries.js';
+/** Default embedded-vs-referenced cutoff (1 MiB). */
+export const FACT_EMBEDDED_THRESHOLD_DEFAULT = 1024 * 1024;
+/** Default fetcher backed by `globalThis.fetch`. */
+export const create_default_fetcher = () => ({
+    fetch_stream: async (url) => {
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(`fact fetch failed: ${response.status} ${url}`);
+        }
+        if (!response.body) {
+            throw new Error(`fact fetch returned no body: ${url}`);
+        }
+        return response.body;
+    },
+    fetch_bytes: async (url) => {
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(`fact fetch failed: ${response.status} ${url}`);
+        }
+        return new Uint8Array(await response.arrayBuffer());
+    },
+});
+/**
+ * PG-backed `FactStore`. Delegates to `db/fact_queries.ts` for I/O and adds
+ * the lifecycle layer described in the module doc.
+ */
+export class PgFactStore {
+    #deps;
+    #embedded_threshold;
+    #fetcher;
+    #log;
+    constructor(options) {
+        this.#deps = options.deps;
+        this.#embedded_threshold = options.embedded_threshold ?? FACT_EMBEDDED_THRESHOLD_DEFAULT;
+        this.#fetcher = options.fetcher ?? create_default_fetcher();
+        this.#log = options.log;
+    }
+    /**
+     * Store small bytes embedded in PG. Rejects oversized content so the
+     * caller routes it through `put_ref` explicitly — implicit splitting
+     * hides the size decision from the caller.
+     */
+    async put(bytes, options) {
+        if (bytes.length > this.#embedded_threshold) {
+            throw new Error(`fact bytes exceed embedded threshold (${bytes.length} > ${this.#embedded_threshold}); use put_ref for external storage`);
+        }
+        const hash = fact_hash_bytes(bytes);
+        const inserted = await query_put_fact(this.#deps, {
+            hash,
+            bytes,
+            external_url: null,
+            content_type: options?.content_type ?? null,
+            size: bytes.length,
+        });
+        if (inserted) {
+            await query_put_fact_refs(this.#deps, hash, resolve_refs(bytes, options));
+        }
+        return hash;
+    }
+    /**
+     * Stream-hash external content and record `(hash, external_url, size)`.
+     * Throws when the streamed byte count disagrees with the caller's
+     * declared `size` — a size mismatch usually means the upload was
+     * truncated or the URL points at the wrong content.
+     */
+    async put_ref(url, size, options) {
+        const stream = await this.#fetcher.fetch_stream(url);
+        const { hash, byte_count } = await hash_counted_stream(stream);
+        if (byte_count !== size) {
+            throw new Error(`fact size mismatch for ${url}: caller declared ${size}, streamed ${byte_count}`);
+        }
+        const inserted = await query_put_fact(this.#deps, {
+            hash,
+            bytes: null,
+            external_url: url,
+            content_type: options?.content_type ?? null,
+            size,
+        });
+        if (inserted && options?.refs && options.refs.length > 0) {
+            await query_put_fact_refs(this.#deps, hash, options.refs);
+        }
+        return hash;
+    }
+    /**
+     * Retrieve bytes. Embedded reads return PG bytes directly; external
+     * reads fetch + verify and return `null` (with a warning log) when
+     * the bytes don't match the stored hash.
+     */
+    async get(hash) {
+        const row = await query_get_fact(this.#deps, hash);
+        if (!row)
+            return null;
+        if (row.bytes !== null) {
+            return to_uint8(row.bytes);
+        }
+        if (row.external_url === null) {
+            return null;
+        }
+        let bytes;
+        try {
+            bytes = await this.#fetcher.fetch_bytes(row.external_url);
+        }
+        catch (err) {
+            this.#log?.warn(`PgFactStore.get fetch failed for ${hash} at ${row.external_url}:`, err instanceof Error ? err.message : String(err));
+            return null;
+        }
+        if (!fact_hash_verify(hash, bytes)) {
+            this.#log?.warn(`PgFactStore.get verify mismatch for ${hash} at ${row.external_url}; treating as not-found`);
+            return null;
+        }
+        return bytes;
+    }
+    async has(hash) {
+        return query_has_fact(this.#deps, hash);
+    }
+    async get_meta(hash) {
+        const row = await query_get_fact_meta(this.#deps, hash);
+        if (!row)
+            return null;
+        return {
+            content_type: row.content_type,
+            size: Number(row.size),
+            created_at: row.created_at,
+            external: row.external_url !== null,
+        };
+    }
+    async get_refs(hash) {
+        return query_get_fact_refs(this.#deps, hash);
+    }
+    /**
+     * Drop a fact row. `fact_refs` rows referencing this hash as a source
+     * cascade via the FK; `fact_refs` targeting this hash do **not** —
+     * they remain as dangling pointers, consistent with the federation
+     * model where `target_hash` is intentionally not a FK.
+     *
+     * Idempotent: deleting an absent fact returns `null`. The store does
+     * NOT verify the fact is unreferenced — that policy lives one layer
+     * up (the orphan-fact admin surface in the consumer; a future GC walker).
+     *
+     * External-URL unlink is the caller's responsibility — the store
+     * doesn't know how to resolve `file:` / `s3:` / etc. URLs to a
+     * deletable handle. Caller iterates the returned `external_url`
+     * (when non-null) and dispatches to the appropriate cleanup
+     * routine. Mirrors the read-side `FactExternalFetcher` split.
+     *
+     * @returns `{size, external_url}` for the deleted row, or `null` if
+     *   no row matched the hash.
+     */
+    async delete(hash) {
+        return query_delete_fact(this.#deps, hash);
+    }
+}
+/**
+ * Resolve refs for a `put` call: explicit `refs` win; otherwise auto-extract
+ * from JSON content; otherwise no refs.
+ */
+const resolve_refs = (bytes, options) => {
+    if (options?.refs !== undefined)
+        return options.refs;
+    if (options?.content_type !== 'application/json')
+        return [];
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        // Malformed JSON — caller mislabeled content_type. Fall back to no refs;
+        // the alternative (throwing) would surprise callers who set
+        // content_type advisorially.
+        return [];
+    }
+    return fact_hash_extract_refs(value);
+};
+/** Hash a stream while counting bytes. Lets `put_ref` verify size in one pass. */
+const hash_counted_stream = async (stream) => {
+    let byte_count = 0;
+    const counting = new TransformStream({
+        transform(chunk, controller) {
+            byte_count += chunk.length;
+            controller.enqueue(chunk);
+        },
+    });
+    const piped = stream.pipeThrough(counting);
+    const hash = await fact_hash_stream(piped);
+    return { hash, byte_count };
+};
+/**
+ * Coerce whatever the driver returns for BYTEA into a `Uint8Array`.
+ *
+ * `pg` returns `Buffer` (a `Uint8Array` subclass), `pglite` already returns
+ * `Uint8Array`. Wrapping `Buffer` in a fresh `Uint8Array` keeps the
+ * downstream type honest without a copy.
+ */
+const to_uint8 = (value) => value instanceof Uint8Array && value.constructor === Uint8Array
+    ? value
+    : new Uint8Array(value.buffer, value.byteOffset, value.byteLength);

package/dist/server/env.d.ts

@@ -35,6 +35,8 @@ export declare const BaseServerEnv: z.ZodObject<{
     SMTP_HOST: z.ZodOptional<z.ZodString>;
     SMTP_USER: z.ZodOptional<z.ZodUnion<readonly [z.ZodEmail, z.ZodLiteral<"">]>>;
     SMTP_PASSWORD: z.ZodOptional<z.ZodString>;
+    FUZ_FACTS_DIR: z.ZodDefault<z.ZodString>;
+    FUZ_FACTS_X_ACCEL_REDIRECT_PREFIX: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type BaseServerEnv = z.infer<typeof BaseServerEnv>;
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"env.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,EAA2B,KAAK,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAG1E;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;kBAkCxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,IAAI,CAAC;IACT,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,wBAAwB,GAAG,qBAAqB,CAAC;IACxD,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACtB;AAED,MAAM,MAAM,sBAAsB,GAAG,gBAAgB,GAAG,qBAAqB,CAAC;AAE9E;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,aAAa,KAAG,sBA4BxD,CAAC"}
+{"version":3,"file":"env.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB,OAAO,EAA2B,KAAK,OAAO,EAAC,MAAM,oBAAoB,CAAC;AAG1E;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;kBAwCxB,CAAC;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,EAAE,EAAE,IAAI,CAAC;IACT,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC/B,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACrC,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,wBAAwB,GAAG,qBAAqB,CAAC;IACxD,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACtB;AAED,MAAM,MAAM,sBAAsB,GAAG,gBAAgB,GAAG,qBAAqB,CAAC;AAE9E;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,aAAa,KAAG,sBA4BxD,CAAC"}

package/dist/server/env.js

@@ -53,6 +53,12 @@ export const BaseServerEnv = z.strictObject({
         .string()
         .optional()
         .meta({ description: 'SMTP authentication password', sensitivity: 'secret' }),
+    FUZ_FACTS_DIR: z.string().min(1).default('./.facts').meta({
+        description: 'Directory for referenced (large) fact bytes, sharded <shard>/<rest>',
+    }),
+    FUZ_FACTS_X_ACCEL_REDIRECT_PREFIX: z.string().optional().meta({
+        description: 'Internal nginx prefix for X-Accel-Redirect fact delivery (production only)',
+    }),
 });
 /**
  * Validate a loaded `BaseServerEnv` and produce the artifacts needed for server init.

package/dist/server/fact_write.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared helper for routing fact bytes between embedded (PG `bytes`
+ * column) and external (filesystem + `put_ref`) storage tiers based
+ * on size.
+ *
+ * External writes go through atomic temp+rename so the `facts` row
+ * never references a partial file; idempotence comes from POSIX
+ * `rename` overwrite + `INSERT ... ON CONFLICT DO NOTHING` in the
+ * fact-store queries layer.
+ *
+ * @module
+ */
+import { type FactHash } from '@fuzdev/fuz_util/fact_hash.js';
+import type { FactStore } from '@fuzdev/fuz_util/fact_store.js';
+export interface WriteFactOptions {
+    content_type: string;
+}
+/**
+ * Write `bytes` as a fact, choosing embedded (PG) vs external (disk +
+ * `put_ref`) based on `embedded_threshold`. Returns the canonical
+ * `blake3:` hash either way.
+ *
+ * @param fact_store - the `FactStore` (typically `PgFactStore`)
+ * @param embedded_threshold - bytes ≤ threshold → embedded; > threshold → disk
+ * @param facts_dir - root of the sharded facts directory tree on disk
+ * @param bytes - the raw fact bytes
+ * @param options - content type for the fact metadata
+ * @returns the fact's `blake3:<hex64>` hash
+ * @mutates `fact_store`, `facts_dir` filesystem
+ */
+export declare const write_fact: (fact_store: FactStore, embedded_threshold: number, facts_dir: string, bytes: Uint8Array, options: WriteFactOptions) => Promise<FactHash>;
+//# sourceMappingURL=fact_write.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fact_write.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/fact_write.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,OAAO,EAAoC,KAAK,QAAQ,EAAC,MAAM,+BAA+B,CAAC;AAC/F,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,gCAAgC,CAAC;AAG9D,MAAM,WAAW,gBAAgB;IAChC,YAAY,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,UAAU,GACtB,YAAY,SAAS,EACrB,oBAAoB,MAAM,EAC1B,WAAW,MAAM,EACjB,OAAO,UAAU,EACjB,SAAS,gBAAgB,KACvB,OAAO,CAAC,QAAQ,CA4BlB,CAAC"}

package/dist/server/fact_write.js

@@ -0,0 +1,56 @@
+/**
+ * Shared helper for routing fact bytes between embedded (PG `bytes`
+ * column) and external (filesystem + `put_ref`) storage tiers based
+ * on size.
+ *
+ * External writes go through atomic temp+rename so the `facts` row
+ * never references a partial file; idempotence comes from POSIX
+ * `rename` overwrite + `INSERT ... ON CONFLICT DO NOTHING` in the
+ * fact-store queries layer.
+ *
+ * @module
+ */
+import { randomBytes } from 'node:crypto';
+import { writeFile, rename, mkdir, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { FACT_HASH_PREFIX, fact_hash_bytes } from '@fuzdev/fuz_util/fact_hash.js';
+import { mint_file_fact_url } from './file_fact_url.js';
+/**
+ * Write `bytes` as a fact, choosing embedded (PG) vs external (disk +
+ * `put_ref`) based on `embedded_threshold`. Returns the canonical
+ * `blake3:` hash either way.
+ *
+ * @param fact_store - the `FactStore` (typically `PgFactStore`)
+ * @param embedded_threshold - bytes ≤ threshold → embedded; > threshold → disk
+ * @param facts_dir - root of the sharded facts directory tree on disk
+ * @param bytes - the raw fact bytes
+ * @param options - content type for the fact metadata
+ * @returns the fact's `blake3:<hex64>` hash
+ * @mutates `fact_store`, `facts_dir` filesystem
+ */
+export const write_fact = async (fact_store, embedded_threshold, facts_dir, bytes, options) => {
+    if (bytes.length <= embedded_threshold) {
+        return fact_store.put(bytes, options);
+    }
+    const hash = fact_hash_bytes(bytes);
+    const hex = hash.slice(FACT_HASH_PREFIX.length);
+    const shard = hex.slice(0, 2);
+    const rest = hex.slice(2);
+    const shard_dir = join(facts_dir, shard);
+    const tmp_dir = join(facts_dir, '.tmp');
+    const tmp_path = join(tmp_dir, `${randomBytes(16).toString('hex')}.tmp`);
+    const final_path = join(shard_dir, rest);
+    await Promise.all([mkdir(shard_dir, { recursive: true }), mkdir(tmp_dir, { recursive: true })]);
+    let renamed = false;
+    try {
+        await writeFile(tmp_path, bytes);
+        await rename(tmp_path, final_path);
+        renamed = true;
+    }
+    finally {
+        if (!renamed) {
+            await unlink(tmp_path).catch(() => undefined);
+        }
+    }
+    return fact_store.put_ref(mint_file_fact_url(shard, rest), bytes.length, options);
+};