@fuzdev/fuz_app 0.118.0 → 0.120.0

package/dist/db/fact_disk_storage.js

@@ -1,5 +1,5 @@
 /**
- * Filesystem CAS for externally-stored fact bytes — the disk half of
+ * Filesystem CAS for fact bytes stored outside Postgres — the disk half of
  * `PgFactStore`, threaded over the injectable `runtime/*Deps` rather than raw
  * `node:fs`, so it runs unchanged under Node, Deno, and a mock runtime.
  *
@@ -204,27 +204,23 @@ export const write_fact_bytes_to_disk = async (deps, facts_dir, hash, bytes) =>
     return mint_file_fact_url(shard, rest);
 };
 /**
- * `FactExternalFetcher` reading from the `<facts_dir>/<shard>/<rest>` layout the
- * writers above produce, over the injected `*Deps`. Does NOT verify hash content
- * — `PgFactStore.get` calls `fact_hash_verify(hash, bytes)` after the fetch and
- * returns `null` on mismatch.
+ * Read a disk-backed fact's bytes from the `<facts_dir>/<shard>/<rest>` layout
+ * the writers above produce, addressed by the row's `file:<shard>/<rest>`
+ * `external_url`. The only read of external bytes `PgFactStore.get` performs.
+ * Does NOT verify hash content — `PgFactStore.get` calls
+ * `fact_hash_verify(hash, bytes)` on the result and returns `null` on mismatch.
  *
  * Defense at the read seam is the `FILE_FACT_URL_PATTERN` regex (via
  * `parse_file_fact_url`) — `..` segments, foreign schemes, and non-hex chars
  * fail before any disk access.
+ *
+ * @throws Error when `url` is not a `file:<shard>/<rest>` URL, or when the read fails
  */
-export const create_disk_fact_fetcher = (deps, facts_dir) => {
-    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: (url) => deps.read_file(resolve_path(url)),
-        // `async` funnels a synchronous `resolve_path` throw into a rejection.
-        fetch_stream: async (url) => deps.read_file_stream(resolve_path(url))
-    };
+export const read_fact_bytes_from_disk = async (deps, facts_dir, url) => {
+    const parsed = parse_file_fact_url(url);
+    if (!parsed)
+        throw new Error('invalid file fact url');
+    return deps.read_file(join(facts_dir, parsed.shard, parsed.rest));
 };
 /**
  * Reap stale temp files left under `<facts_dir>/.tmp/` by a hard crash (SIGKILL

package/dist/db/fact_store.d.ts

@@ -4,14 +4,13 @@
  * 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`)
+ * - sync hash on `put`; `put_stream` hashes as it streams
  * - 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
+ * - verify-on-read for disk-backed content; embedded reads skip verify
  *   because PG storage IS the hash table
- * - mismatched external bytes return `null` + log warning (treat as
+ * - mismatched disk bytes return `null` + log warning (treat as
  *   unavailable; GC / repair is a separate concern)
  *
  * Embedded vs disk split: writes route by size. Bytes `<= embedded_threshold`
@@ -19,10 +18,20 @@
  * `<facts_dir>/<shard>/<rest>` (`db/fact_disk_storage.ts`) and the row records a
  * `file:<shard>/<rest>` `external_url`. `put` takes fully-buffered bytes;
  * `put_stream` is the bounded-memory streaming twin (hash BLAKE3 + SHA-256 in
- * one pass, spill past the threshold, enforce `max_bytes` / `ENOSPC`). Both need
- * `disk_root` + `fs` (the `runtime/*Deps`) configured for the over-threshold
- * path; without them, an oversize `put` throws and the caller must `put_ref`
- * against an externally-managed URL (federation / stub-fetcher tests).
+ * one pass, spill past the threshold, enforce `max_bytes` / `ENOSPC`). `put`
+ * needs `disk_root` + `fs` (the `runtime/*Deps`) for the over-threshold path
+ * only: without them the store has nowhere to put bytes it cannot embed, and an
+ * oversize `put` throws. `put_stream` needs `fs` for a body of any size — with
+ * none it throws before reading the stream — and `disk_root` for the
+ * over-threshold spill: with none, a body that passes the threshold throws
+ * `PayloadTooLargeError`.
+ *
+ * Every `external_url` the store writes is a `file:<shard>/<rest>` URL into its
+ * own disk CAS, and that CAS is the only place `get` reads external bytes from
+ * — the store makes no network request. The column is free text
+ * (`query_put_fact` inserts what it is given), so `get` treats a row whose
+ * `external_url` has any other shape, and any external row on a store with no
+ * disk CAS configured, as unavailable: a warning and `null`.
  *
  * @module
  */
@@ -33,13 +42,6 @@ import type { FactMeta, FactPutOptions, FactStore, PutStreamOutcome } from '@fuz
 import { type FactDiskStorageDeps } from './fact_disk_storage.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`.
  *
@@ -52,18 +54,19 @@ export declare const create_default_fetcher: () => FactExternalFetcher;
  *
  * `disk_root` is the facts directory backing the `<shard>/<rest>` disk CAS;
  * `fs` supplies the filesystem capabilities (a `RuntimeDeps` satisfies it).
- * When both are set, oversize `put` + `put_stream` write to disk and the
- * default `fetcher` reads from it. When unset, oversize `put`/`put_stream`
- * spill throws and reads fall back to the `globalThis.fetch`-backed default
- * fetcher (or an injected stub). `log` is optional — the only call site is the
- * verify-mismatch warning path.
+ * When both are set, oversize `put` + `put_stream` write to disk and `get`
+ * reads disk-backed facts from it. When either is unset the store writes
+ * embedded rows only and `get` returns `null` for an external row: an oversize
+ * `put` throws; `put_stream` throws for a body of any size when `fs` is unset,
+ * and with `fs` but no `disk_root` throws `PayloadTooLargeError` for a body
+ * that passes the threshold. `log` is optional — its call sites are the
+ * warnings on the paths where `get` returns `null` for an external row.
  */
 export interface PgFactStoreDeps {
     deps: QueryDeps;
     embedded_threshold?: number;
     disk_root?: string;
     fs?: FactDiskStorageDeps;
-    fetcher?: FactExternalFetcher;
     log?: Logger;
 }
 /**
@@ -77,8 +80,8 @@ export declare class PgFactStore implements FactStore {
      * Store fully-buffered bytes, routing by size: `<= embedded_threshold` into
      * the PG `bytes` column; larger into the disk CAS (when `disk_root` + `fs`
      * are configured) at `<facts_dir>/<shard>/<rest>` with a `file:` URL. Oversize
-     * without a disk root throws so the caller routes it through `put_ref`
-     * explicitly. Idempotent — `ON CONFLICT DO NOTHING` + content-addressed disk
+     * without a disk root throws: the store has nowhere to put bytes it cannot
+     * embed. Idempotent — `ON CONFLICT DO NOTHING` + content-addressed disk
      * filenames make a re-write a no-op.
      */
     put(bytes: Uint8Array, options?: FactPutOptions): Promise<FactHash>;
@@ -101,16 +104,14 @@ export declare class PgFactStore implements FactStore {
      */
     put_stream(stream: ReadableStream<Uint8Array>, max_bytes: number, options?: FactPutOptions): Promise<PutStreamOutcome>;
     /**
-     * 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.
+     * Retrieve bytes. Embedded reads return PG bytes directly. An external
+     * read comes from the disk CAS and nowhere else: the bytes at the row's
+     * `file:<shard>/<rest>` URL are read and verified against the hash.
+     *
+     * Returns `null`, with a warning log, for an external row the store cannot
+     * serve — an `external_url` that is not a `file:<shard>/<rest>` URL, no disk
+     * CAS configured (`disk_root` + `fs`), a failed disk read, or bytes that
+     * don't match the hash. Never makes a network request.
      */
     get(hash: FactHash): Promise<Uint8Array | null>;
     has(hash: FactHash): Promise<boolean>;
@@ -126,11 +127,11 @@ export declare class PgFactStore implements FactStore {
      * 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.
+     * The disk file of a disk-backed fact is NOT unlinked — that is the
+     * caller's responsibility, using the returned `external_url` (when
+     * non-null): a `file:<shard>/<rest>` URL names
+     * `<disk_root>/<shard>/<rest>`. The value is the row's free text — parse
+     * it with `parse_file_fact_url` before joining a path.
      *
      * @returns `{size, external_url}` for the deleted row, or `null` if
      *   no row matched the hash.

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

@@ -1 +1 @@
-{"version":3,"file":"fact_store.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/fact_store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAQtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,KAAK,EACX,QAAQ,EACR,cAAc,EACd,SAAS,EACT,gBAAgB,EAChB,MAAM,gCAAgC,CAAC;AAWxC,OAAO,EAIN,KAAK,mBAAmB,EACxB,MAAM,wBAAwB,CAAC;AAEhC,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;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,SAAS,CAAC;IAChB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,EAAE,mBAAmB,CAAC;IACzB,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,qBAAa,WAAY,YAAW,SAAS;;gBAQhC,OAAO,EAAE,eAAe;IAapC;;;;;;;OAOG;IACG,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;IA+BzE;;;;;;;;;;;;;;;;OAgBG;IACG,UAAU,CACf,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,cAAc,GACtB,OAAO,CAAC,gBAAgB,CAAC;IA6B5B;;;;;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;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;CAG3F"}
+{"version":3,"file":"fact_store.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/fact_store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAOtD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,KAAK,EACX,QAAQ,EACR,cAAc,EACd,SAAS,EACT,gBAAgB,EAChB,MAAM,gCAAgC,CAAC;AAYxC,OAAO,EAIN,KAAK,mBAAmB,EACxB,MAAM,wBAAwB,CAAC;AAEhC,qDAAqD;AACrD,eAAO,MAAM,+BAA+B,QAAc,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,SAAS,CAAC;IAChB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,EAAE,CAAC,EAAE,mBAAmB,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,qBAAa,WAAY,YAAW,SAAS;;gBAOhC,OAAO,EAAE,eAAe;IAQpC;;;;;;;OAOG;IACG,GAAG,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;IA+BzE;;;;;;;;;;;;;;;;OAgBG;IACG,UAAU,CACf,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC,EAClC,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,cAAc,GACtB,OAAO,CAAC,gBAAgB,CAAC;IA6B5B;;;;;;;;;OASG;IACG,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IA0C/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;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;CAG3F"}

package/dist/db/fact_store.js

@@ -4,14 +4,13 @@
  * 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`)
+ * - sync hash on `put`; `put_stream` hashes as it streams
  * - 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
+ * - verify-on-read for disk-backed content; embedded reads skip verify
  *   because PG storage IS the hash table
- * - mismatched external bytes return `null` + log warning (treat as
+ * - mismatched disk bytes return `null` + log warning (treat as
  *   unavailable; GC / repair is a separate concern)
  *
  * Embedded vs disk split: writes route by size. Bytes `<= embedded_threshold`
@@ -19,39 +18,30 @@
  * `<facts_dir>/<shard>/<rest>` (`db/fact_disk_storage.ts`) and the row records a
  * `file:<shard>/<rest>` `external_url`. `put` takes fully-buffered bytes;
  * `put_stream` is the bounded-memory streaming twin (hash BLAKE3 + SHA-256 in
- * one pass, spill past the threshold, enforce `max_bytes` / `ENOSPC`). Both need
- * `disk_root` + `fs` (the `runtime/*Deps`) configured for the over-threshold
- * path; without them, an oversize `put` throws and the caller must `put_ref`
- * against an externally-managed URL (federation / stub-fetcher tests).
+ * one pass, spill past the threshold, enforce `max_bytes` / `ENOSPC`). `put`
+ * needs `disk_root` + `fs` (the `runtime/*Deps`) for the over-threshold path
+ * only: without them the store has nowhere to put bytes it cannot embed, and an
+ * oversize `put` throws. `put_stream` needs `fs` for a body of any size — with
+ * none it throws before reading the stream — and `disk_root` for the
+ * over-threshold spill: with none, a body that passes the threshold throws
+ * `PayloadTooLargeError`.
+ *
+ * Every `external_url` the store writes is a `file:<shard>/<rest>` URL into its
+ * own disk CAS, and that CAS is the only place `get` reads external bytes from
+ * — the store makes no network request. The column is free text
+ * (`query_put_fact` inserts what it is given), so `get` treats a row whose
+ * `external_url` has any other shape, and any external row on a store with no
+ * disk CAS configured, as unavailable: a warning and `null`.
  *
  * @module
  */
 import { to_error_message } from '@fuzdev/fuz_util/error.ts';
-import { fact_hash_bytes, fact_hash_stream, fact_hash_verify, fact_hash_extract_refs } from '@fuzdev/fuz_util/fact_hash.ts';
+import { fact_hash_bytes, fact_hash_verify, fact_hash_extract_refs } from '@fuzdev/fuz_util/fact_hash.ts';
 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';
-import { create_disk_fact_fetcher, stream_fact_to_disk, write_fact_bytes_to_disk } from './fact_disk_storage.js';
+import { is_file_fact_url } from './file_fact_url.js';
+import { read_fact_bytes_from_disk, stream_fact_to_disk, write_fact_bytes_to_disk } from './fact_disk_storage.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.
@@ -61,26 +51,20 @@ export class PgFactStore {
     #embedded_threshold;
     #disk_root;
     #fs;
-    #fetcher;
     #log;
     constructor(options) {
         this.#deps = options.deps;
         this.#embedded_threshold = options.embedded_threshold ?? FACT_EMBEDDED_THRESHOLD_DEFAULT;
         this.#disk_root = options.disk_root;
         this.#fs = options.fs;
-        this.#fetcher =
-            options.fetcher ??
-                (options.disk_root !== undefined && options.fs !== undefined
-                    ? create_disk_fact_fetcher(options.fs, options.disk_root)
-                    : create_default_fetcher());
         this.#log = options.log;
     }
     /**
      * Store fully-buffered bytes, routing by size: `<= embedded_threshold` into
      * the PG `bytes` column; larger into the disk CAS (when `disk_root` + `fs`
      * are configured) at `<facts_dir>/<shard>/<rest>` with a `file:` URL. Oversize
-     * without a disk root throws so the caller routes it through `put_ref`
-     * explicitly. Idempotent — `ON CONFLICT DO NOTHING` + content-addressed disk
+     * without a disk root throws: the store has nowhere to put bytes it cannot
+     * embed. Idempotent — `ON CONFLICT DO NOTHING` + content-addressed disk
      * filenames make a re-write a no-op.
      */
     async put(bytes, options) {
@@ -89,7 +73,7 @@ export class PgFactStore {
         let row_external_url;
         if (bytes.length > this.#embedded_threshold) {
             if (this.#disk_root === undefined || this.#fs === undefined) {
-                throw new Error(`fact bytes exceed embedded threshold (${bytes.length} > ${this.#embedded_threshold}); configure disk_root or use put_ref for external storage`);
+                throw new Error(`fact bytes exceed embedded threshold (${bytes.length} > ${this.#embedded_threshold}) and no disk CAS is configured; set disk_root and fs to store them on disk`);
             }
             row_bytes = null;
             row_external_url = await write_fact_bytes_to_disk(this.#fs, this.#disk_root, hash, bytes);
@@ -147,33 +131,14 @@ export class PgFactStore {
         return { hash: streamed.hash, sha256: streamed.sha256, size: streamed.size };
     }
     /**
-     * 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.
+     * Retrieve bytes. Embedded reads return PG bytes directly. An external
+     * read comes from the disk CAS and nowhere else: the bytes at the row's
+     * `file:<shard>/<rest>` URL are read and verified against the hash.
+     *
+     * Returns `null`, with a warning log, for an external row the store cannot
+     * serve — an `external_url` that is not a `file:<shard>/<rest>` URL, no disk
+     * CAS configured (`disk_root` + `fs`), a failed disk read, or bytes that
+     * don't match the hash. Never makes a network request.
      */
     async get(hash) {
         const row = await query_get_fact(this.#deps, hash);
@@ -185,12 +150,22 @@ export class PgFactStore {
         if (row.external_url === null) {
             return null;
         }
+        // the URL is not echoed — the column is free text, so its shape and
+        // length are whatever the row's writer chose
+        if (!is_file_fact_url(row.external_url)) {
+            this.#log?.warn(`PgFactStore.get external_url for ${hash} is not a file:<shard>/<rest> URL; treating as not-found`);
+            return null;
+        }
+        if (this.#disk_root === undefined || this.#fs === undefined) {
+            this.#log?.warn(`PgFactStore.get ${hash} is disk-backed and no disk CAS is configured (disk_root + fs); treating as not-found`);
+            return null;
+        }
         let bytes;
         try {
-            bytes = await this.#fetcher.fetch_bytes(row.external_url);
+            bytes = await read_fact_bytes_from_disk(this.#fs, this.#disk_root, row.external_url);
         }
         catch (err) {
-            this.#log?.warn(`PgFactStore.get fetch failed for ${hash} at ${row.external_url}:`, to_error_message(err));
+            this.#log?.warn(`PgFactStore.get disk read failed for ${hash} at ${row.external_url}:`, to_error_message(err));
             return null;
         }
         if (!fact_hash_verify(hash, bytes)) {
@@ -226,11 +201,11 @@ export class PgFactStore {
      * 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.
+     * The disk file of a disk-backed fact is NOT unlinked — that is the
+     * caller's responsibility, using the returned `external_url` (when
+     * non-null): a `file:<shard>/<rest>` URL names
+     * `<disk_root>/<shard>/<rest>`. The value is the row's free text — parse
+     * it with `parse_file_fact_url` before joining a path.
      *
      * @returns `{size, external_url}` for the deleted row, or `null` if
      *   no row matched the hash.
@@ -260,19 +235,6 @@ const resolve_refs = (bytes, options) => {
     }
     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`.
  *

package/dist/db/file_fact_url.d.ts

@@ -1,9 +1,9 @@
 /**
  * Canonical filesystem-fact URL shape + on-disk layout.
  *
- * `external_url` on the generic `fact` row is `string | null` because the
- * `FactStore` interface stays federation-friendly (future
- * `https://...` / `s3://...` shapes). Filesystem-minted URLs are exactly
+ * `external_url` on the `fact` row is free text (`string | null`), but the
+ * only shape `PgFactStore` writes, reads, or serves is the filesystem-minted
+ * one — any other reads as unavailable. Those 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
@@ -11,9 +11,9 @@
  *
  * Centralizing the regex + the `fact_disk_path` split keeps the shape in one
  * place: `PgFactStore`'s disk CAS (`db/fact_disk_storage.ts`), the
- * `serve_fact_route` defense-in-depth check, and the `file_fact_fetcher`
- * resolver all derive the layout here, so the write path and the read path
- * can't drift. The TS twin of the Rust `fact_disk_path` (`fuz_fact`).
+ * `serve_fact_route` defense-in-depth check, and the disk read
+ * (`read_fact_bytes_from_disk`) all derive the layout here, so the write path
+ * and the read path can't drift. The TS twin of the Rust `fact_disk_path` (`fuz_fact`).
  *
  * 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.

package/dist/db/file_fact_url.js

@@ -1,9 +1,9 @@
 /**
  * Canonical filesystem-fact URL shape + on-disk layout.
  *
- * `external_url` on the generic `fact` row is `string | null` because the
- * `FactStore` interface stays federation-friendly (future
- * `https://...` / `s3://...` shapes). Filesystem-minted URLs are exactly
+ * `external_url` on the `fact` row is free text (`string | null`), but the
+ * only shape `PgFactStore` writes, reads, or serves is the filesystem-minted
+ * one — any other reads as unavailable. Those 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
@@ -11,9 +11,9 @@
  *
  * Centralizing the regex + the `fact_disk_path` split keeps the shape in one
  * place: `PgFactStore`'s disk CAS (`db/fact_disk_storage.ts`), the
- * `serve_fact_route` defense-in-depth check, and the `file_fact_fetcher`
- * resolver all derive the layout here, so the write path and the read path
- * can't drift. The TS twin of the Rust `fact_disk_path` (`fuz_fact`).
+ * `serve_fact_route` defense-in-depth check, and the disk read
+ * (`read_fact_bytes_from_disk`) all derive the layout here, so the write path
+ * and the read path can't drift. The TS twin of the Rust `fact_disk_path` (`fuz_fact`).
  *
  * 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.

package/dist/db/status.d.ts

@@ -97,10 +97,67 @@ export interface DbStatus {
  */
 export declare const query_db_status: (db: Db, namespaces?: Array<MigrationNamespace>) => Promise<DbStatus>;
 /**
- * Format a `DbStatus` as a human-readable string for CLI output.
+ * Format a `DbStatus` as the body of the human-facing operator report.
+ *
+ * A `tables:` count with one aligned `name  N rows` line per table, then a
+ * `migrations:` header (always printed, even with no namespaces) and one
+ * aligned line per namespace: its state (`up-to-date`, `PENDING <n>`, or
+ * `DIVERGED`), `applied/declared`, and the latest applied name (`(none)` when
+ * nothing is applied). A diverged namespace adds a `diverged:` line, a pending
+ * one a `pending:` line naming the tail. A failed connection renders the single
+ * line `connection: FAILED (<error>)`. Every line ends in a newline.
+ *
+ * The body only — the `database status` / `url:` header belongs to the CLI
+ * script, which holds the URL a `DbStatus` never sees. For a connected status
+ * the output is byte-identical with the Rust twin's `format_db_status`; both
+ * test suites pin the same fixture report.
  *
  * @param status - the status to format
  * @returns multi-line string suitable for console output
  */
 export declare const format_db_status: (status: DbStatus) => string;
+/**
+ * Render a database URL for printing from the parse node-postgres dials —
+ * `new URL`, with pg-connection-string's precedence, where a `user`, `host`, or
+ * `port` query parameter overrides the URL's own — so the line names the server
+ * dialed and no credential can leak however the input spells it.
+ *
+ * A `postgres://` or `postgresql://` URL renders as
+ * `postgres://[user@]host:port[/dbname]`: never the password, and never the
+ * query or fragment (`sslmode` and the like are dropped by design). The scheme
+ * always prints as `postgres://`. The port always prints, `5432` when the URL
+ * names none. The user and database name print percent-encoded with
+ * `encodeURIComponent`, so no control character, escape sequence, or bidi
+ * override reaches the terminal and an `@` can't pose as the separator; each
+ * prints only when non-empty. An IP-literal host prints canonically (IPv6
+ * bracketed); a Unix-socket directory prints with each `/` as `%2F`. A PGlite
+ * `file://` or `memory://` URL prints as scheme, host, and path.
+ *
+ * The whole line is `(not a URL; hidden)` for any other scheme, when `new URL`
+ * rejects the input, when it holds a malformed percent-escape (`%ZZ`), when
+ * there is no host, when the host is neither an IP literal, a hostname of
+ * `A-Z a-z 0-9 . _ -`, nor a socket directory of those characters and `/`, when
+ * the user holds `?`, `=`, `&`, `/`, or `#`, or when the port isn't a number up
+ * to 65535. The host and user rules match the Rust twin's, where they catch
+ * tokio-postgres's split at the first `@`.
+ *
+ * Twin of the Rust `fuz_db` CLI's `display_db_url`, byte-identical on the URLs
+ * both drivers read alike. They part where the drivers do: a `host=` or `port=`
+ * query parameter overrides the URL's here (tokio-postgres appends it to a list
+ * whose first entry the pool dials); a `dbname=` query parameter, which
+ * tokio-postgres honours and node-postgres ignores, and a `#…` fragment, which
+ * tokio-postgres keeps as part of the database name; tokio-postgres also
+ * accepts `key=value` strings, host lists, and an unencoded `/` or `?` in the
+ * password (here, the placeholder); an unencoded `@` in the userinfo splits at
+ * the last `@` here, rendering the user and host node-postgres dials, where the
+ * Rust twin prints the placeholder; node-postgres decodes the database name
+ * with `decodeURI`, so a reserved-character escape such as `%2F` stays literal
+ * and prints as `%252F`; an IPv4-mapped IPv6 address serializes differently;
+ * and tokio-postgres refuses an unknown query parameter (`sslpassword=`) that
+ * node-postgres passes.
+ *
+ * @param url - the database URL
+ * @returns the URL without its password, query, or fragment, or the placeholder
+ */
+export declare const display_db_url: (url: string) => string;
 //# sourceMappingURL=status.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GACnB;IACA,mEAAmE;IACnE,IAAI,EAAE,eAAe,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;CAChB,GACD;IACA,kEAAkE;IAClE,IAAI,EAAE,cAAc,CAAC;IACrB,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;CAChB,CAAC;AAEL;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B,2EAA2E;IAC3E,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,yCAAyC;IACzC,SAAS,EAAE,OAAO,CAAC;IACnB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,MAAM,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAC3B,sCAAsC;IACtC,UAAU,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;CACnC;AAaD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,GAC3B,IAAI,EAAE,EACN,aAAa,KAAK,CAAC,kBAAkB,CAAC,KACpC,OAAO,CAAC,QAAQ,CAsGlB,CAAC;AAeF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,QAAQ,KAAG,MA4CnD,CAAC"}
+{"version":3,"file":"status.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEvD;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GACnB;IACA,mEAAmE;IACnE,IAAI,EAAE,eAAe,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;CAChB,GACD;IACA,kEAAkE;IAClE,IAAI,EAAE,cAAc,CAAC;IACrB,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;CAChB,CAAC;AAEL;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B,2EAA2E;IAC3E,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B;;;OAGG;IACH,UAAU,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,yCAAyC;IACzC,SAAS,EAAE,OAAO,CAAC;IACnB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,MAAM,EAAE,KAAK,CAAC,WAAW,CAAC,CAAC;IAC3B,sCAAsC;IACtC,UAAU,EAAE,KAAK,CAAC,eAAe,CAAC,CAAC;CACnC;AA6DD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,GAC3B,IAAI,EAAE,EACN,aAAa,KAAK,CAAC,kBAAkB,CAAC,KACpC,OAAO,CAAC,QAAQ,CA2DlB,CAAC;AA0BF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,gBAAgB,GAAI,QAAQ,QAAQ,KAAG,MAmCnD,CAAC;AA8BF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,cAAc,GAAI,KAAK,MAAM,KAAG,MAoC5C,CAAC"}