@fuzdev/fuz_app 0.119.0 → 0.121.0

package/dist/auth/deps.d.ts

@@ -61,9 +61,9 @@ export interface AppDeps {
     /**
      * Optional content-addressed byte store. Present only on backends that
      * serve binary content (facts) — minimal consumers leave it unset. The
-     * consumer constructs a `PgFactStore` (`db/fact_store.ts`) wired to a
-     * `file_fact_fetcher` (`server/file_fact_fetcher.ts`) at its own backend
-     * assembly and assigns it here; `create_app_backend` stays facts-agnostic.
+     * consumer constructs a `PgFactStore` (`db/fact_store.ts`) over its facts
+     * directory (`disk_root` + `fs`) at its own backend assembly and assigns it
+     * here; `create_app_backend` stays facts-agnostic.
      */
     fact_store?: FactStore;
 }

package/dist/db/CLAUDE.md

@@ -156,11 +156,16 @@ DO NOTHING`), `_put_fact_refs`, `_get_fact` / `_get_fact_meta` / `_has_fact`
   / `_select_for_delete` (a fact is orphan when no active `cell.refs` names it).
 - **`fact_store.ts`** — `PgFactStore implements FactStore` (the interface lives
   in `@fuzdev/fuz_util/fact_store.ts`): size-routed writes (embedded ≤
-  `embedded_threshold` / disk CAS above it / `put_ref` for an externally-managed
-  URL), JSON ref auto-extract, idempotent put, verify-on-read for external
-  content via an injected `FactExternalFetcher`. With `disk_root` + `fs` (the
+  `embedded_threshold` / disk CAS above it), JSON ref auto-extract, idempotent
+  put, verify-on-read for disk-backed content. With `disk_root` + `fs` (the
   `runtime/*Deps`) configured, oversize `put` and the streaming `put_stream`
-  write to the `<shard>/<rest>` disk CAS and the default fetcher reads from it.
+  write to the `<shard>/<rest>` disk CAS and `get` reads from it; without them
+  an oversize write throws (`put_stream` needs `fs` for a body of any size).
+  The disk CAS is the only place `get` reads external bytes from; the store
+  makes no network request. A row whose `external_url` is not a
+  `file:<shard>/<rest>` URL (the store never writes one), and any external row
+  on a store with no disk CAS, reads as `null` with a warning; the serve route
+  404s the former.
 - **`file_fact_url.ts`** — the canonical `file:<shard>/<rest>` URL shape
   (`FileFactUrl` brand, `mint_file_fact_url` / `parse_file_fact_url` /
   `FILE_FACT_URL_PATTERN`) plus `fact_disk_path(hash) → {shard, rest}`, the
@@ -168,15 +173,15 @@ DO NOTHING`), `_put_fact_refs`, `_get_fact` / `_get_fact_meta` / `_has_fact`
 - **`fact_disk_storage.ts`** — the filesystem CAS over `runtime/{FsStream,FsWrite,FsRemove,FsRead}Deps`
   (not raw `node:fs`): `stream_fact_to_disk` (bounded-memory blake3+sha256 single
   pass, buffer→spill, fsync-then-atomic-rename, dedup-drop if the CAS path already
-  exists), `write_fact_bytes_to_disk` (buffering twin), `create_disk_fact_fetcher`,
+  exists), `write_fact_bytes_to_disk` (buffering twin), `read_fact_bytes_from_disk`,
   and `sweep_orphan_temps` (reaps stale `.tmp` spills by mtime). The temp is
   `fsync`ed before the rename publishes it (twins the Rust `fuz_fact` §fsync
   posture: data-sync before rename, parent-dir fsync waived) — the serve path
   streams the file without re-hashing, so write-time durability is the guard.
 - **`fact_store_errors.ts`** — `PayloadTooLargeError` / `StorageFullError` (+
   `is_enospc_error`) thrown by `put_stream`, for a consumer route's 413 / 507.
-- The read-side fetcher + write/serve plumbing also live under `server/`
-  (`file_fact_fetcher.ts`, `serve_fact_route.ts`).
+- The HTTP serving plumbing lives under `server/` (`serve_fact_route.ts`,
+  `x_accel.ts`).
 
 ### Migration namespace order
 

package/dist/db/fact_disk_storage.d.ts

@@ -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.
  *
@@ -31,7 +31,6 @@ import { type FactHash } from '@fuzdev/fuz_util/hash_schemas.ts';
 import type { Logger } from '@fuzdev/fuz_util/log.ts';
 import type { FsReadDeps, FsWriteDeps, FsStreamDeps, FsRemoveDeps } from '../runtime/deps.js';
 import { type FileFactUrl } from './file_fact_url.js';
-import type { FactExternalFetcher } from './fact_store.js';
 /** Subdirectory under `facts_dir` for in-flight atomic temp files. */
 export declare const FACT_TMP_DIRNAME = ".tmp";
 /** Default age (1 hour) past which a `.tmp/*` file is considered orphaned. */
@@ -41,7 +40,7 @@ export declare const FACT_TMP_ORPHAN_MAX_AGE_MS: number;
  * full `RuntimeDeps` (Node or Deno) satisfies this; each function below picks
  * the narrow subset it actually uses.
  */
-export type FactDiskStorageDeps = Pick<FsReadDeps, 'stat' | 'readdir' | 'read_file'> & Pick<FsWriteDeps, 'mkdir' | 'rename' | 'write_file' | 'fsync'> & Pick<FsStreamDeps, 'write_file_stream' | 'read_file_stream'> & Pick<FsRemoveDeps, 'remove'>;
+export type FactDiskStorageDeps = Pick<FsReadDeps, 'stat' | 'readdir' | 'read_file'> & Pick<FsWriteDeps, 'mkdir' | 'rename' | 'write_file' | 'fsync'> & Pick<FsStreamDeps, 'write_file_stream'> & Pick<FsRemoveDeps, 'remove'>;
 /**
  * Where a streamed body landed — `embedded` carries the in-memory bytes (under
  * the embedded threshold, bound for the PG `fact.bytes` column); `disk` means
@@ -100,16 +99,19 @@ export declare const stream_fact_to_disk: (deps: Pick<FactDiskStorageDeps, "mkdi
  */
 export declare const write_fact_bytes_to_disk: (deps: Pick<FactDiskStorageDeps, "mkdir" | "rename" | "remove" | "write_file" | "fsync" | "stat">, facts_dir: string, hash: FactHash, bytes: Uint8Array) => Promise<FileFactUrl>;
 /**
- * `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 declare const create_disk_fact_fetcher: (deps: Pick<FactDiskStorageDeps, "read_file" | "read_file_stream">, facts_dir: string) => FactExternalFetcher;
+export declare const read_fact_bytes_from_disk: (deps: Pick<FactDiskStorageDeps, "read_file">, facts_dir: string, url: string) => Promise<Uint8Array>;
 /**
  * Reap stale temp files left under `<facts_dir>/.tmp/` by a hard crash (SIGKILL
  * / OOM / host crash) mid-write — the `finally` cleanup in the writers above

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

@@ -1 +1 @@
-{"version":3,"file":"fact_disk_storage.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/fact_disk_storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AASH,OAAO,EAAoB,KAAK,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AACnF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE9F,OAAO,EAIN,KAAK,WAAW,EAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAG3D,sEAAsE;AACtE,eAAO,MAAM,gBAAgB,SAAS,CAAC;AAEvC,8EAA8E;AAC9E,eAAO,MAAM,0BAA0B,QAAiB,CAAC;AAEzD;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,CAAC,GACnF,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,QAAQ,GAAG,YAAY,GAAG,OAAO,CAAC,GAC9D,IAAI,CAAC,YAAY,EAAE,mBAAmB,GAAG,kBAAkB,CAAC,GAC5D,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;AAE9B;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAC1B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,WAAW,CAAA;CAAE,CAAC;AAEvF;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,eAAe,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,IAAI,CACT,mBAAmB,EACnB,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,mBAAmB,GAAG,OAAO,GAAG,MAAM,CACtE,EACD,WAAW,MAAM,GAAG,SAAS,EAC7B,QAAQ,cAAc,CAAC,UAAU,CAAC,EAClC,WAAW,MAAM,EACjB,oBAAoB,MAAM,KACxB,OAAO,CAAC,sBAAsB,CA8GhC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,IAAI,CAAC,mBAAmB,EAAE,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,YAAY,GAAG,OAAO,GAAG,MAAM,CAAC,EAChG,WAAW,MAAM,EACjB,MAAM,QAAQ,EACd,OAAO,UAAU,KACf,OAAO,CAAC,WAAW,CAgBrB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,IAAI,CAAC,mBAAmB,EAAE,WAAW,GAAG,kBAAkB,CAAC,EACjE,WAAW,MAAM,KACf,mBAWF,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kBAAkB,GAC9B,MAAM,IAAI,CAAC,mBAAmB,EAAE,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC,EAC9D,WAAW,MAAM,EACjB,UAAU;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,KAC3D,OAAO,CAAC,MAAM,CA0BhB,CAAC"}
+{"version":3,"file":"fact_disk_storage.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/fact_disk_storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AASH,OAAO,EAAoB,KAAK,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AACnF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE9F,OAAO,EAIN,KAAK,WAAW,EAChB,MAAM,oBAAoB,CAAC;AAG5B,sEAAsE;AACtE,eAAO,MAAM,gBAAgB,SAAS,CAAC;AAEvC,8EAA8E;AAC9E,eAAO,MAAM,0BAA0B,QAAiB,CAAC;AAEzD;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,CAAC,GACnF,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,QAAQ,GAAG,YAAY,GAAG,OAAO,CAAC,GAC9D,IAAI,CAAC,YAAY,EAAE,mBAAmB,CAAC,GACvC,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAC,CAAC;AAE9B;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAC1B;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,WAAW,CAAA;CAAE,CAAC;AAEvF;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACtC,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,eAAe,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,IAAI,CACT,mBAAmB,EACnB,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,mBAAmB,GAAG,OAAO,GAAG,MAAM,CACtE,EACD,WAAW,MAAM,GAAG,SAAS,EAC7B,QAAQ,cAAc,CAAC,UAAU,CAAC,EAClC,WAAW,MAAM,EACjB,oBAAoB,MAAM,KACxB,OAAO,CAAC,sBAAsB,CA8GhC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,IAAI,CAAC,mBAAmB,EAAE,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,YAAY,GAAG,OAAO,GAAG,MAAM,CAAC,EAChG,WAAW,MAAM,EACjB,MAAM,QAAQ,EACd,OAAO,UAAU,KACf,OAAO,CAAC,WAAW,CAgBrB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,IAAI,CAAC,mBAAmB,EAAE,WAAW,CAAC,EAC5C,WAAW,MAAM,EACjB,KAAK,MAAM,KACT,OAAO,CAAC,UAAU,CAIpB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,kBAAkB,GAC9B,MAAM,IAAI,CAAC,mBAAmB,EAAE,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC,EAC9D,WAAW,MAAM,EACjB,UAAU;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,KAC3D,OAAO,CAAC,MAAM,CA0BhB,CAAC"}

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/server/serve_fact_route.d.ts

@@ -13,9 +13,9 @@
  * Embedded facts stream from the `fact.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`
- * factory option — a validated `XAccelConfig` (built via
+ * (production) or stream from disk (dev / tests). The runtime mode is
+ * selected by the optional `x_accel` factory option — a validated
+ * `XAccelConfig` (built via
  * `create_x_accel_config` in `server/x_accel.ts`) set in prod, unset in dev.
  * The handle can only be obtained by proving the facts nginx location is
  * `internal;`, so X-Accel serving can't be enabled against a public location.
@@ -80,10 +80,13 @@
  *
  * ## 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.
+ * `external_url` is re-validated against the `file:<shard>/<rest>` shape
+ * before it addresses the filesystem or an `X-Accel-Redirect`. `PgFactStore`
+ * writes only that shape, but the column is free text and `query_put_fact`
+ * inserts what it is given, so a row written past the store — or a
+ * row-injection bug upstream — would otherwise hand nginx an
+ * attacker-controlled path. Any other shape is a logged 404, the same
+ * unavailable that `PgFactStore.get` reports for it as `null`.
  *
  * @module
  */

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

@@ -1 +1 @@
-{"version":3,"file":"serve_fact_route.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/serve_fact_route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwFG;AAMH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAetD,OAAO,EAAuC,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAE5F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAM/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAkEjD,MAAM,WAAW,+BAA+B;IAC/C;;;;;;OAMG;IACH,IAAI,EAAE,OAAO,CAAC;IACd,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;CACZ;AAgHD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,GAC7C,SAAS,+BAA+B,KACtC,SAgDF,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,4BAA4B,GACxC,SAAS,+BAA+B,KACtC,SA2CF,CAAC"}
+{"version":3,"file":"serve_fact_route.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/server/serve_fact_route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2FG;AAMH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAetD,OAAO,EAAuC,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAE5F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAM/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAkEjD,MAAM,WAAW,+BAA+B;IAC/C;;;;;;OAMG;IACH,IAAI,EAAE,OAAO,CAAC;IACd,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;CACZ;AAkHD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,GAC7C,SAAS,+BAA+B,KACtC,SAgDF,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,4BAA4B,GACxC,SAAS,+BAA+B,KACtC,SA2CF,CAAC"}

package/dist/server/serve_fact_route.js

@@ -13,9 +13,9 @@
  * Embedded facts stream from the `fact.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`
- * factory option — a validated `XAccelConfig` (built via
+ * (production) or stream from disk (dev / tests). The runtime mode is
+ * selected by the optional `x_accel` factory option — a validated
+ * `XAccelConfig` (built via
  * `create_x_accel_config` in `server/x_accel.ts`) set in prod, unset in dev.
  * The handle can only be obtained by proving the facts nginx location is
  * `internal;`, so X-Accel serving can't be enabled against a public location.
@@ -80,10 +80,13 @@
  *
  * ## 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.
+ * `external_url` is re-validated against the `file:<shard>/<rest>` shape
+ * before it addresses the filesystem or an `X-Accel-Redirect`. `PgFactStore`
+ * writes only that shape, but the column is free text and `query_put_fact`
+ * inserts what it is given, so a row written past the store — or a
+ * row-injection bug upstream — would otherwise hand nginx an
+ * attacker-controlled path. Any other shape is a logged 404, the same
+ * unavailable that `PgFactStore.get` reports for it as `null`.
  *
  * @module
  */
@@ -202,7 +205,7 @@ const serve_fact_bytes = async (c, route, hash, config) => {
     // 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}`);
+        log.error(`serve_fact: external_url for ${hash} is not a file:<shard>/<rest> URL; answering 404`);
         return c.body(null, 404);
     }
     const { shard, rest } = parsed;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_app",
-  "version": "0.119.0",
+  "version": "0.121.0",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",
@@ -33,7 +33,7 @@
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.4",
     "@fuzdev/blake3-wasm": ">=0.2.0",
-    "@fuzdev/fuz_util": ">=0.68.0",
+    "@fuzdev/fuz_util": ">=0.70.0",
     "@hono/node-server": ">=1",
     "@hono/node-ws": ">=1",
     "@node-rs/argon2": ">=2",
@@ -77,7 +77,7 @@
     "@fuzdev/fuz_code": "^0.48.0",
     "@fuzdev/fuz_css": "^0.64.0",
     "@fuzdev/fuz_ui": "^0.208.0",
-    "@fuzdev/fuz_util": "^0.69.0",
+    "@fuzdev/fuz_util": "^0.70.0",
     "@fuzdev/gro": "^0.213.0",
     "@fuzdev/mdz": "^0.3.0",
     "@hono/node-server": "^1.19.14",

package/dist/server/file_fact_fetcher.d.ts

@@ -1,42 +0,0 @@
-/**
- * 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

@@ -1 +0,0 @@
-{"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,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAG/D,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

@@ -1,60 +0,0 @@
-/**
- * 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 '../db/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);
-        })
-    };
-};