@fuzdev/fuz_app 0.81.0 → 0.82.0

package/dist/db/CLAUDE.md

@@ -92,11 +92,28 @@ DO NOTHING`), `_put_fact_refs`, `_get_fact` / `_get_fact_meta` / `_has_fact`
   external unlink), and the cell-coupled orphan queries `query_orphan_facts_list`
   / `_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.js`): embedded-vs-`put_ref` split by
-  `embedded_threshold`, JSON ref auto-extract, idempotent put, verify-on-read
-  for external content via an injected `FactExternalFetcher`. The filesystem
-  fetcher + write/serve plumbing live under `server/` (`file_fact_url.ts`,
-  `file_fact_fetcher.ts`, `fact_write.ts`, `serve_fact_route.ts`).
+  in `@fuzdev/fuz_util/fact_store.js`): 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
+  `runtime/*Deps`) configured, oversize `put` and the streaming `put_stream`
+  write to the `<shard>/<rest>` disk CAS and the default fetcher reads from it.
+- **`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
+  single source of truth for the on-disk layout (twins the Rust `fuz_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`,
+  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`, `fact_write.ts`, `serve_fact_route.ts`).
 
 ### Migration namespace order
 

package/dist/db/fact_disk_storage.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Filesystem CAS for externally-stored fact bytes — 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.
+ *
+ * Large facts (over the embedded threshold) live on disk at the canonical
+ * sharded layout `<facts_dir>/<shard>/<rest>` — `<shard>` is the first 2 hex
+ * chars of the blake3 digest, `<rest>` the remaining 62 — with the `fact` row
+ * carrying `external_url = file:<shard>/<rest>` (disk-root-relative). The layout
+ * is single-sourced by `fact_disk_path` in `db/file_fact_url.ts`, so the write
+ * path here and the URL minted into the row can't drift. The TS twin of the
+ * Rust `fuz_fact` disk CAS.
+ *
+ * Writes land through `<facts_dir>/.tmp/<rand>.tmp`, are `fsync`ed, then
+ * `rename`d into the content-addressed final path. The `rename` is atomic on
+ * POSIX (a *concurrent reader* observing the path sees either the full content
+ * or nothing), but atomicity is not durability — the `fsync` before the rename
+ * is what guards against a *host crash* leaving a torn/zero file at a published
+ * CAS path, because the serving path streams the hash-named file without
+ * re-hashing it (`server/serve_fact_route.ts`). This twins the Rust `fuz_fact`
+ * §fsync posture: data-sync before the rename; the parent-dir fsync stays
+ * deliberately waived (a lost dirent is regenerable under content addressing).
+ * If the final path already exists the temp is dropped instead of renamed over
+ * — idempotent dedup (same hash → byte-identical content), mirroring the Rust
+ * commit path. `.tmp/` is a sibling of `<shard>/` under the same `facts_dir` so
+ * `rename` is always same-filesystem (no EXDEV).
+ *
+ * @module
+ */
+import { type FactHash } from '@fuzdev/fuz_util/fact_hash.js';
+import type { Logger } from '@fuzdev/fuz_util/log.js';
+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. */
+export declare const FACT_TMP_ORPHAN_MAX_AGE_MS: number;
+/**
+ * Filesystem capabilities the disk CAS needs, drawn from `runtime/deps.ts`. A
+ * 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'>;
+/**
+ * Where a streamed body landed — `embedded` carries the in-memory bytes (under
+ * the embedded threshold, bound for the PG `fact.bytes` column); `disk` means
+ * the bytes are already at `<facts_dir>/<shard>/<rest>` and the row carries the
+ * `file:` URL.
+ */
+export type StreamPlacement = {
+    kind: 'embedded';
+    bytes: Uint8Array;
+} | {
+    kind: 'disk';
+    external_url: FileFactUrl;
+};
+/**
+ * Outcome of streaming an upload to storage: the `blake3:`-prefixed fact hash,
+ * the bare-hex SHA-256, the byte count, and where the bytes landed.
+ * `PgFactStore.put_stream` turns this into the `fact` row insert.
+ */
+export interface StreamFactToDiskResult {
+    hash: FactHash;
+    sha256: string;
+    size: number;
+    placement: StreamPlacement;
+}
+/**
+ * Stream `source` to storage with bounded memory: hash BLAKE3 + SHA-256
+ * incrementally in one pass, buffer in memory until the bytes cross
+ * `embedded_threshold`, then spill the buffer + remaining chunks through a temp
+ * file and atomically land it in the disk CAS. Peak heap is
+ * `O(chunk + embedded_threshold)`, never `O(artifact)`, so a multi-GB upload
+ * never buffers in RAM.
+ *
+ * - **Embedded vs disk.** A body `<= embedded_threshold` stays in memory and is
+ *   returned as `{kind: 'embedded'}` for the PG `bytes` column. Above it (with a
+ *   `facts_dir`), the buffer + remaining chunks spill to `<facts_dir>/.tmp/…`,
+ *   then `rename` into `<facts_dir>/<shard>/<rest>` once the hash is known —
+ *   `{kind: 'disk'}`. A body over the threshold with `facts_dir === undefined`
+ *   throws `PayloadTooLargeError` (matches `PgFactStore.put`).
+ * - **Cap enforcement.** Aborts with `PayloadTooLargeError` the moment the
+ *   running byte count passes `max_bytes` — the mid-stream backstop for a
+ *   chunked or mis-declared `Content-Length`.
+ * - **Disk-full.** An `ENOSPC` from the temp-file write surfaces as
+ *   `StorageFullError`.
+ *
+ * @mutates `facts_dir` filesystem
+ */
+export declare const stream_fact_to_disk: (deps: Pick<FactDiskStorageDeps, "mkdir" | "rename" | "remove" | "write_file_stream" | "fsync" | "stat">, facts_dir: string | undefined, source: ReadableStream<Uint8Array>, max_bytes: number, embedded_threshold: number) => Promise<StreamFactToDiskResult>;
+/**
+ * Write fully-buffered `bytes` for `hash` to the canonical
+ * `<facts_dir>/<shard>/<rest>` path, then publish via `commit_temp_to_cas`
+ * (fsync'd temp + atomic rename, dedup-aware). The buffering twin of
+ * `stream_fact_to_disk`, used by `PgFactStore.put` for oversize sync bytes.
+ * Returns the `file:` `external_url` for the `fact` row.
+ *
+ * @mutates `facts_dir` filesystem
+ */
+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.
+ *
+ * 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.
+ */
+export declare const create_disk_fact_fetcher: (deps: Pick<FactDiskStorageDeps, "read_file" | "read_file_stream">, facts_dir: string) => FactExternalFetcher;
+/**
+ * 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
+ * never ran. Removes `.tmp` entries whose mtime is older than `max_age_ms` (so
+ * an in-flight upload isn't yanked out from under itself). The TS twin of the
+ * Rust `sweep_orphan_temps`; call on startup + on an interval.
+ *
+ * Best-effort: a missing `.tmp/` dir (no oversize upload has ever run) is a
+ * no-op; a runtime that doesn't report `mtime_ms` (a mock) leaves every temp
+ * untouched; a per-file stat/remove failure is logged and skipped rather than
+ * aborting the sweep. Returns the count removed.
+ *
+ * @mutates `facts_dir` filesystem
+ */
+export declare const sweep_orphan_temps: (deps: Pick<FactDiskStorageDeps, "readdir" | "stat" | "remove">, facts_dir: string, options?: {
+    max_age_ms?: number;
+    log?: Pick<Logger, "warn">;
+}) => Promise<number>;
+//# sourceMappingURL=fact_disk_storage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fact_disk_storage.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/fact_disk_storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAQH,OAAO,EAAmB,KAAK,QAAQ,EAAC,MAAM,+BAA+B,CAAC;AAC9E,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,UAAU,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAC,MAAM,oBAAoB,CAAC;AAE5F,OAAO,EAIN,KAAK,WAAW,EAChB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,iBAAiB,CAAC;AAGzD,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,GACxB;IAAC,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAC,GACrC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,WAAW,CAAA;CAAC,CAAC;AAE7C;;;;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;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAC,KACzD,OAAO,CAAC,MAAM,CA6BhB,CAAC"}

package/dist/db/fact_disk_storage.js

@@ -0,0 +1,315 @@
+/**
+ * Filesystem CAS for externally-stored fact bytes — 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.
+ *
+ * Large facts (over the embedded threshold) live on disk at the canonical
+ * sharded layout `<facts_dir>/<shard>/<rest>` — `<shard>` is the first 2 hex
+ * chars of the blake3 digest, `<rest>` the remaining 62 — with the `fact` row
+ * carrying `external_url = file:<shard>/<rest>` (disk-root-relative). The layout
+ * is single-sourced by `fact_disk_path` in `db/file_fact_url.ts`, so the write
+ * path here and the URL minted into the row can't drift. The TS twin of the
+ * Rust `fuz_fact` disk CAS.
+ *
+ * Writes land through `<facts_dir>/.tmp/<rand>.tmp`, are `fsync`ed, then
+ * `rename`d into the content-addressed final path. The `rename` is atomic on
+ * POSIX (a *concurrent reader* observing the path sees either the full content
+ * or nothing), but atomicity is not durability — the `fsync` before the rename
+ * is what guards against a *host crash* leaving a torn/zero file at a published
+ * CAS path, because the serving path streams the hash-named file without
+ * re-hashing it (`server/serve_fact_route.ts`). This twins the Rust `fuz_fact`
+ * §fsync posture: data-sync before the rename; the parent-dir fsync stays
+ * deliberately waived (a lost dirent is regenerable under content addressing).
+ * If the final path already exists the temp is dropped instead of renamed over
+ * — idempotent dedup (same hash → byte-identical content), mirroring the Rust
+ * commit path. `.tmp/` is a sibling of `<shard>/` under the same `facts_dir` so
+ * `rename` is always same-filesystem (no EXDEV).
+ *
+ * @module
+ */
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { Blake3Hasher } from '@fuzdev/blake3_wasm';
+import { blake3_ready } from '@fuzdev/fuz_util/hash_blake3.js';
+import { to_hex } from '@fuzdev/fuz_util/hex.js';
+import { FACT_HASH_PREFIX } from '@fuzdev/fuz_util/fact_hash.js';
+import { generate_random_base64url } from '../crypto.js';
+import { fact_disk_path, mint_file_fact_url, parse_file_fact_url, } from './file_fact_url.js';
+import { is_enospc_error, PayloadTooLargeError, StorageFullError } from './fact_store_errors.js';
+/** Subdirectory under `facts_dir` for in-flight atomic temp files. */
+export const FACT_TMP_DIRNAME = '.tmp';
+/** Default age (1 hour) past which a `.tmp/*` file is considered orphaned. */
+export const FACT_TMP_ORPHAN_MAX_AGE_MS = 60 * 60 * 1000;
+/**
+ * Stream `source` to storage with bounded memory: hash BLAKE3 + SHA-256
+ * incrementally in one pass, buffer in memory until the bytes cross
+ * `embedded_threshold`, then spill the buffer + remaining chunks through a temp
+ * file and atomically land it in the disk CAS. Peak heap is
+ * `O(chunk + embedded_threshold)`, never `O(artifact)`, so a multi-GB upload
+ * never buffers in RAM.
+ *
+ * - **Embedded vs disk.** A body `<= embedded_threshold` stays in memory and is
+ *   returned as `{kind: 'embedded'}` for the PG `bytes` column. Above it (with a
+ *   `facts_dir`), the buffer + remaining chunks spill to `<facts_dir>/.tmp/…`,
+ *   then `rename` into `<facts_dir>/<shard>/<rest>` once the hash is known —
+ *   `{kind: 'disk'}`. A body over the threshold with `facts_dir === undefined`
+ *   throws `PayloadTooLargeError` (matches `PgFactStore.put`).
+ * - **Cap enforcement.** Aborts with `PayloadTooLargeError` the moment the
+ *   running byte count passes `max_bytes` — the mid-stream backstop for a
+ *   chunked or mis-declared `Content-Length`.
+ * - **Disk-full.** An `ENOSPC` from the temp-file write surfaces as
+ *   `StorageFullError`.
+ *
+ * @mutates `facts_dir` filesystem
+ */
+export const stream_fact_to_disk = async (deps, facts_dir, source, max_bytes, embedded_threshold) => {
+    await blake3_ready;
+    const blake3 = new Blake3Hasher();
+    const sha256 = createHash('sha256');
+    let size = 0;
+    // Buffer leading bytes until they cross the embedded threshold; small facts
+    // stay embedded (no disk), large ones never buffer past the threshold.
+    const buffered = [];
+    let buffered_len = 0;
+    const reader = source.getReader();
+    const hash_and_count = (chunk) => {
+        size += chunk.length;
+        if (size > max_bytes)
+            throw new PayloadTooLargeError(size, max_bytes);
+        blake3.update(chunk);
+        sha256.update(chunk);
+    };
+    try {
+        // Phase 1: read + hash + buffer until the threshold is crossed or the
+        // stream ends. The crossing chunk is hashed + buffered here, then emitted
+        // (not re-read) by the spill stream below.
+        let spill_needed = false;
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value || value.length === 0)
+                continue;
+            hash_and_count(value);
+            buffered.push(value);
+            buffered_len += value.length;
+            if (buffered_len > embedded_threshold) {
+                spill_needed = true;
+                break;
+            }
+        }
+        if (!spill_needed) {
+            const hash = (FACT_HASH_PREFIX + to_hex(blake3.finalize()));
+            return {
+                hash,
+                sha256: sha256.digest('hex'),
+                size,
+                placement: { kind: 'embedded', bytes: concat_chunks(buffered, buffered_len) },
+            };
+        }
+        if (facts_dir === undefined) {
+            // Over the embedded threshold with nowhere to spill — same shape as the
+            // `PgFactStore.put` oversize-without-disk_root reject.
+            throw new PayloadTooLargeError(size, embedded_threshold);
+        }
+        // Phase 2: spill. A combined stream emits the already-hashed buffered
+        // chunks, then continues pulling from `reader`, hashing each remaining
+        // chunk as it flows. `write_file_stream` consumes it with backpressure
+        // (peak memory one chunk).
+        let buffer_index = 0;
+        const combined = new ReadableStream({
+            async pull(controller) {
+                if (buffer_index < buffered.length) {
+                    controller.enqueue(buffered[buffer_index++]);
+                    return;
+                }
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        controller.close();
+                        return;
+                    }
+                    if (!value || value.length === 0)
+                        continue;
+                    try {
+                        hash_and_count(value);
+                    }
+                    catch (err) {
+                        controller.error(err);
+                        return;
+                    }
+                    controller.enqueue(value);
+                    return;
+                }
+            },
+            cancel: (reason) => reader.cancel(reason),
+        });
+        const tmp_dir = join(facts_dir, FACT_TMP_DIRNAME);
+        const tmp_path = join(tmp_dir, `${generate_random_base64url(16)}.tmp`);
+        await deps.mkdir(tmp_dir, { recursive: true });
+        try {
+            await deps.write_file_stream(tmp_path, combined);
+        }
+        catch (err) {
+            await deps.remove(tmp_path).catch(() => undefined);
+            if (is_enospc_error(err))
+                throw new StorageFullError(err);
+            throw err; // includes a mid-stream PayloadTooLargeError surfaced via the stream
+        }
+        const hash = (FACT_HASH_PREFIX + to_hex(blake3.finalize()));
+        const { shard, rest } = await commit_temp_to_cas(deps, tmp_path, facts_dir, hash);
+        return {
+            hash,
+            sha256: sha256.digest('hex'),
+            size,
+            placement: { kind: 'disk', external_url: mint_file_fact_url(shard, rest) },
+        };
+    }
+    finally {
+        blake3.free();
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            // Already released/cancelled by the spill stream's cancel path.
+        }
+    }
+};
+/**
+ * Write fully-buffered `bytes` for `hash` to the canonical
+ * `<facts_dir>/<shard>/<rest>` path, then publish via `commit_temp_to_cas`
+ * (fsync'd temp + atomic rename, dedup-aware). The buffering twin of
+ * `stream_fact_to_disk`, used by `PgFactStore.put` for oversize sync bytes.
+ * Returns the `file:` `external_url` for the `fact` row.
+ *
+ * @mutates `facts_dir` filesystem
+ */
+export const write_fact_bytes_to_disk = async (deps, facts_dir, hash, bytes) => {
+    const tmp_dir = join(facts_dir, FACT_TMP_DIRNAME);
+    const tmp_path = join(tmp_dir, `${generate_random_base64url(16)}.tmp`);
+    await deps.mkdir(tmp_dir, { recursive: true });
+    // Write the temp first (mapping disk-full), then publish — the same
+    // write-then-commit shape as the streaming twin.
+    try {
+        await deps.write_file(tmp_path, bytes);
+    }
+    catch (err) {
+        await deps.remove(tmp_path).catch(() => undefined);
+        if (is_enospc_error(err))
+            throw new StorageFullError(err);
+        throw err;
+    }
+    const { shard, rest } = await commit_temp_to_cas(deps, tmp_path, facts_dir, hash);
+    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.
+ *
+ * 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.
+ */
+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)),
+    };
+};
+/**
+ * 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
+ * never ran. Removes `.tmp` entries whose mtime is older than `max_age_ms` (so
+ * an in-flight upload isn't yanked out from under itself). The TS twin of the
+ * Rust `sweep_orphan_temps`; call on startup + on an interval.
+ *
+ * Best-effort: a missing `.tmp/` dir (no oversize upload has ever run) is a
+ * no-op; a runtime that doesn't report `mtime_ms` (a mock) leaves every temp
+ * untouched; a per-file stat/remove failure is logged and skipped rather than
+ * aborting the sweep. Returns the count removed.
+ *
+ * @mutates `facts_dir` filesystem
+ */
+export const sweep_orphan_temps = async (deps, facts_dir, options) => {
+    const max_age_ms = options?.max_age_ms ?? FACT_TMP_ORPHAN_MAX_AGE_MS;
+    const tmp_dir = join(facts_dir, FACT_TMP_DIRNAME);
+    let entries;
+    try {
+        entries = await deps.readdir(tmp_dir);
+    }
+    catch {
+        return 0; // `.tmp/` doesn't exist yet — nothing to sweep.
+    }
+    const cutoff = Date.now() - max_age_ms;
+    let removed = 0;
+    for (const entry of entries) {
+        if (!entry.endsWith('.tmp'))
+            continue;
+        const path = join(tmp_dir, entry);
+        try {
+            const info = await deps.stat(path);
+            // Unknown age (missing file, or a runtime that doesn't report mtime) →
+            // leave it; never reap something we can't prove is stale.
+            if (!info || info.mtime_ms === undefined || info.mtime_ms >= cutoff)
+                continue;
+            await deps.remove(path);
+            removed++;
+        }
+        catch (err) {
+            options?.log?.warn(`sweep_orphan_temps: failed to reap ${path}:`, err instanceof Error ? err.message : String(err));
+        }
+    }
+    return removed;
+};
+/**
+ * Publish a written temp file into the CAS at `<facts_dir>/<shard>/<rest>`:
+ * `fsync` the temp's data (durability before the rename — the serve path streams
+ * the file without re-hashing, so the bytes must be stable before they become
+ * the canonical body), then either drop the temp (byte-identical content already
+ * present — idempotent dedup) or atomically `rename` it into place. On any
+ * failure the temp is unlinked and an `ENOSPC` is surfaced as `StorageFullError`.
+ * The single commit path shared by both writers above — twins the Rust `fuz_fact`
+ * `SpillFile::rename_into_cas` (data-sync before rename; parent-dir fsync waived).
+ *
+ * @mutates `facts_dir` filesystem
+ */
+const commit_temp_to_cas = async (deps, tmp_path, facts_dir, hash) => {
+    const { shard, rest } = fact_disk_path(hash);
+    const final_path = join(facts_dir, shard, rest);
+    try {
+        await deps.fsync(tmp_path);
+        if (await deps.stat(final_path)) {
+            await deps.remove(tmp_path).catch(() => undefined);
+        }
+        else {
+            await deps.mkdir(join(facts_dir, shard), { recursive: true });
+            await deps.rename(tmp_path, final_path);
+        }
+    }
+    catch (err) {
+        await deps.remove(tmp_path).catch(() => undefined);
+        if (is_enospc_error(err))
+            throw new StorageFullError(err);
+        throw err;
+    }
+    return { shard, rest };
+};
+/** Concatenate buffered chunks into a single `Uint8Array` of `total` bytes. */
+const concat_chunks = (chunks, total) => {
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+};

package/dist/db/fact_store.d.ts

@@ -14,21 +14,23 @@
  * - 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.
+ * Embedded vs disk split: writes route by size. Bytes `<= embedded_threshold`
+ * land in the PG `bytes` column; larger bytes go to the disk CAS at
+ * `<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).
  *
  * @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';
+import type { FactMeta, FactPutOptions, FactStore, PutStreamOutcome } from '@fuzdev/fuz_util/fact_store.js';
+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. */
@@ -43,16 +45,24 @@ export declare const create_default_fetcher: () => FactExternalFetcher;
  *
  * `embedded_threshold` (bytes) is the inline-vs-external cutoff: payloads
  * at or under it store embedded in the `fact` row, larger ones route to
- * the external fetcher. Defaults to `FACT_EMBEDDED_THRESHOLD_DEFAULT`
+ * the disk CAS. 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.
+ * thumbnails to disk.
+ *
+ * `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.
  */
 export interface PgFactStoreDeps {
     deps: QueryDeps;
     embedded_threshold?: number;
+    disk_root?: string;
+    fs?: FactDiskStorageDeps;
     fetcher?: FactExternalFetcher;
     log?: Logger;
 }
@@ -64,11 +74,32 @@ 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.
+     * 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
+     * filenames make a re-write a no-op.
      */
     put(bytes: Uint8Array, options?: FactPutOptions): Promise<FactHash>;
+    /**
+     * Stream bytes into the store with bounded memory, returning the finalized
+     * digests + size. Delegates the byte path to `stream_fact_to_disk` (hash
+     * BLAKE3 + SHA-256 in one pass, buffer to the embedded threshold, spill to the
+     * disk CAS), then inserts the `fact` row by placement — embedded bytes go to
+     * the PG `bytes` column, disk-spilled bytes record the `file:` `external_url`.
+     * The cap is enforced mid-stream (`PayloadTooLargeError`); a disk-full mid-
+     * stream throws `StorageFullError`.
+     *
+     * Refs: explicit `options.refs` are recorded; JSON auto-extraction is NOT
+     * attempted (it would need a buffered re-read, defeating the bounded-memory
+     * contract) — streamed uploads are opaque blobs.
+     *
+     * Requires `fs` (and, for the over-threshold spill, `disk_root`) to be
+     * configured. The streaming twin of `put`; mirrors the Rust
+     * `FactStore::put_stream`.
+     */
+    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

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;;;;;;;;;;;;;;;;;;;;;;;;;;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"}
+{"version":3,"file":"fact_store.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/fact_store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;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,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;IA6BzE;;;;;;;;;;;;;;;;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;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;KAAC,GAAG,IAAI,CAAC;CAGzF"}

package/dist/db/fact_store.js

@@ -14,19 +14,21 @@
  * - 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.
+ * Embedded vs disk split: writes route by size. Bytes `<= embedded_threshold`
+ * land in the PG `bytes` column; larger bytes go to the disk CAS at
+ * `<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).
  *
  * @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';
+import { create_disk_fact_fetcher, 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`. */
@@ -56,28 +58,49 @@ export const create_default_fetcher = () => ({
 export class PgFactStore {
     #deps;
     #embedded_threshold;
+    #disk_root;
+    #fs;
     #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.#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 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.
+     * 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
+     * filenames make a re-write a no-op.
      */
     async put(bytes, options) {
+        const hash = fact_hash_bytes(bytes);
+        let row_bytes;
+        let row_external_url;
         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`);
+            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`);
+            }
+            row_bytes = null;
+            row_external_url = await write_fact_bytes_to_disk(this.#fs, this.#disk_root, hash, bytes);
+        }
+        else {
+            row_bytes = bytes;
+            row_external_url = null;
         }
-        const hash = fact_hash_bytes(bytes);
         const inserted = await query_put_fact(this.#deps, {
             hash,
-            bytes,
-            external_url: null,
+            bytes: row_bytes,
+            external_url: row_external_url,
             content_type: options?.content_type ?? null,
             size: bytes.length,
         });
@@ -86,6 +109,42 @@ export class PgFactStore {
         }
         return hash;
     }
+    /**
+     * Stream bytes into the store with bounded memory, returning the finalized
+     * digests + size. Delegates the byte path to `stream_fact_to_disk` (hash
+     * BLAKE3 + SHA-256 in one pass, buffer to the embedded threshold, spill to the
+     * disk CAS), then inserts the `fact` row by placement — embedded bytes go to
+     * the PG `bytes` column, disk-spilled bytes record the `file:` `external_url`.
+     * The cap is enforced mid-stream (`PayloadTooLargeError`); a disk-full mid-
+     * stream throws `StorageFullError`.
+     *
+     * Refs: explicit `options.refs` are recorded; JSON auto-extraction is NOT
+     * attempted (it would need a buffered re-read, defeating the bounded-memory
+     * contract) — streamed uploads are opaque blobs.
+     *
+     * Requires `fs` (and, for the over-threshold spill, `disk_root`) to be
+     * configured. The streaming twin of `put`; mirrors the Rust
+     * `FactStore::put_stream`.
+     */
+    async put_stream(stream, max_bytes, options) {
+        if (this.#fs === undefined) {
+            throw new Error('PgFactStore.put_stream requires `fs` (FactDiskStorageDeps) to be configured');
+        }
+        const streamed = await stream_fact_to_disk(this.#fs, this.#disk_root, stream, max_bytes, this.#embedded_threshold);
+        const row_bytes = streamed.placement.kind === 'embedded' ? streamed.placement.bytes : null;
+        const row_external_url = streamed.placement.kind === 'disk' ? streamed.placement.external_url : null;
+        const inserted = await query_put_fact(this.#deps, {
+            hash: streamed.hash,
+            bytes: row_bytes,
+            external_url: row_external_url,
+            content_type: options?.content_type ?? null,
+            size: streamed.size,
+        });
+        if (inserted && options?.refs && options.refs.length > 0) {
+            await query_put_fact_refs(this.#deps, streamed.hash, options.refs);
+        }
+        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

package/dist/db/fact_store_errors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Typed errors thrown by `PgFactStore.put_stream` so a file-store route can
+ * map them to the canonical wire responses.
+ *
+ * The Rust twin uses `FactError::PayloadTooLarge` / `::StorageFull` (`fuz_fact`);
+ * these TS classes carry the same two cases so the upload handler can branch
+ * identically and return the same status + body shape (`413` / `507`).
+ *
+ * @module
+ */
+/**
+ * The streamed upload exceeded the byte cap. Thrown by `put_stream` when its
+ * mid-stream counter passes `max_bytes` — the backstop for a chunked or
+ * mis-declared `Content-Length` that the cheap header pre-check can't catch.
+ * A consumer route maps this to `413`.
+ */
+export declare class PayloadTooLargeError extends Error {
+    /** Bytes read before the cap tripped (may exceed `max_bytes` by one chunk). */
+    readonly bytes_read: number;
+    readonly max_bytes: number;
+    constructor(bytes_read: number, max_bytes: number);
+}
+/**
+ * The disk filled mid-stream (`ENOSPC`). Thrown by `put_stream` when the
+ * temp-file write fails for lack of space — the real disk-full guarantee that
+ * a best-effort free-space preflight can't promise (chunked uploads, TOCTOU
+ * races). A consumer route maps this to `507`.
+ */
+export declare class StorageFullError extends Error {
+    constructor(cause?: unknown);
+}
+/**
+ * Whether a thrown value is a Node filesystem `ENOSPC` (no space left on
+ * device). Used by the streaming disk write to translate the raw FS error
+ * into a `StorageFullError`.
+ */
+export declare const is_enospc_error: (err: unknown) => boolean;
+//# sourceMappingURL=fact_store_errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fact_store_errors.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/fact_store_errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC9C,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBACf,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM;CAMjD;AAED;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;gBAC9B,KAAK,CAAC,EAAE,OAAO;CAI3B;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,OAAO,KAAG,OAIH,CAAC"}

package/dist/db/fact_store_errors.js

@@ -0,0 +1,48 @@
+/**
+ * Typed errors thrown by `PgFactStore.put_stream` so a file-store route can
+ * map them to the canonical wire responses.
+ *
+ * The Rust twin uses `FactError::PayloadTooLarge` / `::StorageFull` (`fuz_fact`);
+ * these TS classes carry the same two cases so the upload handler can branch
+ * identically and return the same status + body shape (`413` / `507`).
+ *
+ * @module
+ */
+/**
+ * The streamed upload exceeded the byte cap. Thrown by `put_stream` when its
+ * mid-stream counter passes `max_bytes` — the backstop for a chunked or
+ * mis-declared `Content-Length` that the cheap header pre-check can't catch.
+ * A consumer route maps this to `413`.
+ */
+export class PayloadTooLargeError extends Error {
+    /** Bytes read before the cap tripped (may exceed `max_bytes` by one chunk). */
+    bytes_read;
+    max_bytes;
+    constructor(bytes_read, max_bytes) {
+        super(`payload too large: read ${bytes_read} bytes, exceeds ${max_bytes} byte limit`);
+        this.name = 'PayloadTooLargeError';
+        this.bytes_read = bytes_read;
+        this.max_bytes = max_bytes;
+    }
+}
+/**
+ * The disk filled mid-stream (`ENOSPC`). Thrown by `put_stream` when the
+ * temp-file write fails for lack of space — the real disk-full guarantee that
+ * a best-effort free-space preflight can't promise (chunked uploads, TOCTOU
+ * races). A consumer route maps this to `507`.
+ */
+export class StorageFullError extends Error {
+    constructor(cause) {
+        super('storage_full', cause === undefined ? undefined : { cause });
+        this.name = 'StorageFullError';
+    }
+}
+/**
+ * Whether a thrown value is a Node filesystem `ENOSPC` (no space left on
+ * device). Used by the streaming disk write to translate the raw FS error
+ * into a `StorageFullError`.
+ */
+export const is_enospc_error = (err) => typeof err === 'object' &&
+    err !== null &&
+    'code' in err &&
+    err.code === 'ENOSPC';

package/dist/{server → db}/file_fact_url.d.ts

@@ -1,7 +1,7 @@
 /**
- * Canonical filesystem-fact URL shape.
+ * Canonical filesystem-fact URL shape + on-disk layout.
  *
- * `external_url` on the generic `facts` row is `string | null` because the
+ * `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
  * `file:<shard>/<rest>` where `<shard>` is the first 2 hex chars of the
@@ -9,10 +9,11 @@
  * `<facts_dir>/<shard>/<rest>` after the writer atomically temp+renames
  * them in.
  *
- * Centralizing the regex keeps the shape in one place: the `serve_fact_route`
- * defense-in-depth check and the `file_fact_fetcher` resolver both validate
- * against it, so federation work that loosens or extends the shape (e.g.,
- * admitting `https://`) updates one place, not several.
+ * 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`).
  *
  * 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.
@@ -21,6 +22,7 @@
  *
  * @module
  */
+import { type FactHash } from '@fuzdev/fuz_util/fact_hash.js';
 import { z } from 'zod';
 /** Anchored, capture-group form: `^file:(<shard>)/(<rest>)$`. */
 export declare const FILE_FACT_URL_PATTERN: RegExp;
@@ -33,6 +35,17 @@ export declare const FileFactUrl: z.core.$ZodBranded<z.ZodString, "FileFactUrl",
 export type FileFactUrl = z.infer<typeof FileFactUrl>;
 /** Type guard. Useful when discriminating a `string | null` column. */
 export declare const is_file_fact_url: (s: string) => s is FileFactUrl;
+/**
+ * Split a `FactHash` into its on-disk `<shard>/<rest>` parts — the first 2
+ * hex chars of the digest (shard subdir) + the remaining 62. The single
+ * source of truth for the disk layout, so the write path (`put` /
+ * `put_stream`) and the URL minted into the `fact` row can't disagree.
+ * Mirrors the Rust `fact_disk_path` in `fuz_fact`.
+ */
+export declare const fact_disk_path: (hash: FactHash) => {
+    shard: string;
+    rest: string;
+};
 /**
  * Validate a string against the canonical shape. Returns the branded URL
  * plus its parsed parts, or `null` on shape mismatch — callers decide
@@ -45,9 +58,9 @@ export declare const parse_file_fact_url: (url: string) => {
 } | null;
 /**
  * Construct a canonical `file:<shard>/<rest>` URL. The writer side
- * (`server/fact_write.ts`) assembles the shape from a freshly-computed
- * hash; this helper centralizes the literal so a future shape change is
- * a single edit.
+ * (`db/fact_disk_storage.ts`) assembles the shape from a freshly-computed
+ * hash via `fact_disk_path`; this helper centralizes the literal so a
+ * future shape change is a single edit.
  */
 export declare const mint_file_fact_url: (shard: string, rest: string) => FileFactUrl;
 //# sourceMappingURL=file_fact_url.d.ts.map

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

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

package/dist/{server → db}/file_fact_url.js

@@ -1,7 +1,7 @@
 /**
- * Canonical filesystem-fact URL shape.
+ * Canonical filesystem-fact URL shape + on-disk layout.
  *
- * `external_url` on the generic `facts` row is `string | null` because the
+ * `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
  * `file:<shard>/<rest>` where `<shard>` is the first 2 hex chars of the
@@ -9,10 +9,11 @@
  * `<facts_dir>/<shard>/<rest>` after the writer atomically temp+renames
  * them in.
  *
- * Centralizing the regex keeps the shape in one place: the `serve_fact_route`
- * defense-in-depth check and the `file_fact_fetcher` resolver both validate
- * against it, so federation work that loosens or extends the shape (e.g.,
- * admitting `https://`) updates one place, not several.
+ * 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`).
  *
  * 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.
@@ -21,6 +22,7 @@
  *
  * @module
  */
+import { FACT_HASH_PREFIX } from '@fuzdev/fuz_util/fact_hash.js';
 import { z } from 'zod';
 /** Anchored, capture-group form: `^file:(<shard>)/(<rest>)$`. */
 export const FILE_FACT_URL_PATTERN = /^file:([0-9a-f]{2})\/([0-9a-f]{62})$/;
@@ -32,6 +34,17 @@ export const FILE_FACT_URL_PATTERN = /^file:([0-9a-f]{2})\/([0-9a-f]{62})$/;
 export const FileFactUrl = z.string().regex(FILE_FACT_URL_PATTERN).brand('FileFactUrl');
 /** Type guard. Useful when discriminating a `string | null` column. */
 export const is_file_fact_url = (s) => FILE_FACT_URL_PATTERN.test(s);
+/**
+ * Split a `FactHash` into its on-disk `<shard>/<rest>` parts — the first 2
+ * hex chars of the digest (shard subdir) + the remaining 62. The single
+ * source of truth for the disk layout, so the write path (`put` /
+ * `put_stream`) and the URL minted into the `fact` row can't disagree.
+ * Mirrors the Rust `fact_disk_path` in `fuz_fact`.
+ */
+export const fact_disk_path = (hash) => {
+    const hex = hash.slice(FACT_HASH_PREFIX.length);
+    return { shard: hex.slice(0, 2), rest: hex.slice(2) };
+};
 /**
  * Validate a string against the canonical shape. Returns the branded URL
  * plus its parsed parts, or `null` on shape mismatch — callers decide
@@ -45,8 +58,8 @@ export const parse_file_fact_url = (url) => {
 };
 /**
  * Construct a canonical `file:<shard>/<rest>` URL. The writer side
- * (`server/fact_write.ts`) assembles the shape from a freshly-computed
- * hash; this helper centralizes the literal so a future shape change is
- * a single edit.
+ * (`db/fact_disk_storage.ts`) assembles the shape from a freshly-computed
+ * hash via `fact_disk_path`; this helper centralizes the literal so a
+ * future shape change is a single edit.
  */
 export const mint_file_fact_url = (shard, rest) => `file:${shard}/${rest}`;

package/dist/runtime/deno.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deno.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/runtime/deno.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,WAAW,EAA4B,MAAM,WAAW,CAAC;AA0DtE;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,aAAa,CAAC,MAAM,CAAC,KAAG,WAmIhE,CAAC"}
+{"version":3,"file":"deno.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/runtime/deno.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,WAAW,EAA4B,MAAM,WAAW,CAAC;AA6DtE;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,aAAa,CAAC,MAAM,CAAC,KAAG,WAgJhE,CAAC"}

package/dist/runtime/deno.js

@@ -29,7 +29,12 @@ export const create_deno_runtime = (args) => ({
     stat: async (path) => {
         try {
             const s = await Deno.stat(path);
-            return { is_file: s.isFile, is_directory: s.isDirectory, size: s.size };
+            return {
+                is_file: s.isFile,
+                is_directory: s.isDirectory,
+                size: s.size,
+                mtime_ms: s.mtime?.getTime(),
+            };
         }
         catch {
             return null;
@@ -75,6 +80,15 @@ export const create_deno_runtime = (args) => ({
     write_text_file: (path, content) => Deno.writeTextFile(path, content),
     write_file: (path, data) => Deno.writeFile(path, data),
     rename: (old_path, new_path) => Deno.rename(old_path, new_path),
+    fsync: async (path) => {
+        const file = await Deno.open(path, { read: true });
+        try {
+            await file.sync();
+        }
+        finally {
+            file.close();
+        }
+    },
     remove: (path, options) => Deno.remove(path, options),
     // === HTTP ===
     fetch: globalThis.fetch,

package/dist/runtime/deps.d.ts

@@ -24,6 +24,15 @@ export interface StatResult {
      * `Content-Length`) read it from a real runtime, where it is always present.
      */
     size?: number;
+    /**
+     * Last-modification time in epoch milliseconds, when the runtime reports it.
+     * Populated by `create_node_runtime` / `create_deno_runtime`;
+     * `create_mock_runtime` omits it (so a mock-backed sweep treats every temp as
+     * unknown-age and never reaps). Optional so loose test stubs that only assert
+     * `is_file` / `is_directory` don't have to supply it. The orphan-temp sweep
+     * (`db/fact_disk_storage.ts`) reads it to age out stale `.tmp` spill files.
+     */
+    mtime_ms?: number;
 }
 /**
  * Result of executing a command.
@@ -105,6 +114,18 @@ export interface FsWriteDeps {
     write_file: (path: string, data: Uint8Array) => Promise<void>;
     /** Rename (move) a file. */
     rename: (old_path: string, new_path: string) => Promise<void>;
+    /**
+     * Flush a file's data to stable storage (fsync). Call on a temp file after
+     * writing it and *before* `rename`-ing it into place when the renamed path is
+     * later served without re-verification — otherwise a host crash after the
+     * rename can surface a torn/zero file as authentic content. The fact disk CAS
+     * (`db/fact_disk_storage.ts`) is the one such path; it twins the Rust
+     * `fuz_fact` §fsync posture (data-sync before rename; the parent-dir fsync
+     * stays deliberately waived — a lost dirent is regenerable under content
+     * addressing). Real runtimes open the path, fsync, and close;
+     * `create_mock_runtime` no-ops (it models no durability).
+     */
+    fsync: (path: string) => Promise<void>;
 }
 /**
  * Streaming file I/O — read a file as a byte stream, or write a byte stream to

package/dist/runtime/deps.d.ts.map

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

package/dist/runtime/mock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mock.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/runtime/mock.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,WAAW,EAAc,aAAa,EAAE,iBAAiB,EAAC,MAAM,WAAW,CAAC;AAIzF;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC/C,kCAAkC;IAClC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,0CAA0C;IAC1C,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,+CAA+C;IAC/C,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACvC,mCAAmC;IACnC,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvB,wCAAwC;IACxC,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC1B,gGAAgG;IAChG,aAAa,EAAE,KAAK,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAAC,OAAO,CAAC,EAAE,iBAAiB,CAAA;KAAC,CAAC,CAAC;IACtF,sCAAsC;IACtC,qBAAqB,EAAE,KAAK,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;KAAC,CAAC,CAAC;IACjE,8BAA8B;IAC9B,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B,4CAA4C;IAC5C,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACjD,yCAAyC;IACzC,YAAY,EAAE,UAAU,GAAG,IAAI,CAAC;IAChC,4BAA4B;IAC5B,WAAW,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,WAAW,CAAA;KAAC,CAAC,CAAC;IACxE,wDAAwD;IACxD,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAM,KAAK,CAAC,MAAM,CAAM,KAAG,WAoR9D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,WAAW,KAAG,IAazD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,SAAS,WAAW,EAAE,OAAO,MAAM,KAAG,IAEpE,CAAC;AAEF;;;;GAIG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM;CAKxB"}
+{"version":3,"file":"mock.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/runtime/mock.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,WAAW,EAAc,aAAa,EAAE,iBAAiB,EAAC,MAAM,WAAW,CAAC;AAIzF;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC/C,kCAAkC;IAClC,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,0CAA0C;IAC1C,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,+CAA+C;IAC/C,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACvC,mCAAmC;IACnC,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvB,wCAAwC;IACxC,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC1B,gGAAgG;IAChG,aAAa,EAAE,KAAK,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAAC,OAAO,CAAC,EAAE,iBAAiB,CAAA;KAAC,CAAC,CAAC;IACtF,sCAAsC;IACtC,qBAAqB,EAAE,KAAK,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;KAAC,CAAC,CAAC;IACjE,8BAA8B;IAC9B,aAAa,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC7B,4CAA4C;IAC5C,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACjD,yCAAyC;IACzC,YAAY,EAAE,UAAU,GAAG,IAAI,CAAC;IAChC,4BAA4B;IAC5B,WAAW,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,WAAW,CAAA;KAAC,CAAC,CAAC;IACxE,wDAAwD;IACxD,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,mBAAmB,GAAI,OAAM,KAAK,CAAC,MAAM,CAAM,KAAG,WAuR9D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,WAAW,KAAG,IAazD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,SAAS,WAAW,EAAE,OAAO,MAAM,KAAG,IAEpE,CAAC;AAEF;;;;GAIG;AACH,qBAAa,aAAc,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM;CAKxB"}

package/dist/runtime/mock.js

@@ -222,6 +222,9 @@ export const create_mock_runtime = (args = []) => {
             }
             mock_fs_bytes.set(path, merged);
         },
+        // The mock models no real disk, so durability is a no-op (mirrors how it
+        // omits `mtime_ms`). The fact disk CAS sweep + fsync stay deps-based.
+        fsync: async () => { },
         rename: async (old_path, new_path) => {
             const content = mock_fs.get(old_path);
             if (content !== undefined) {

package/dist/runtime/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/runtime/node.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH,OAAO,KAAK,EAAC,WAAW,EAA4B,MAAM,WAAW,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAC/B,OAAM,aAAa,CAAC,MAAM,CAAyB,KACjD,WAmLD,CAAC"}
+{"version":3,"file":"node.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/runtime/node.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH,OAAO,KAAK,EAAC,WAAW,EAA4B,MAAM,WAAW,CAAC;AAEtE;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAC/B,OAAM,aAAa,CAAC,MAAM,CAAyB,KACjD,WAkMD,CAAC"}

package/dist/runtime/node.js

@@ -34,7 +34,12 @@ export const create_node_runtime = (args = process.argv.slice(2)) => ({
     stat: async (path) => {
         try {
             const s = await stat(path);
-            return { is_file: s.isFile(), is_directory: s.isDirectory(), size: s.size };
+            return {
+                is_file: s.isFile(),
+                is_directory: s.isDirectory(),
+                size: s.size,
+                mtime_ms: s.mtimeMs,
+            };
         }
         catch {
             return null;
@@ -82,6 +87,17 @@ export const create_node_runtime = (args = process.argv.slice(2)) => ({
     write_text_file: (path, content) => writeFile(path, content, 'utf-8'),
     write_file: (path, data) => writeFile(path, data),
     rename: (old_path, new_path) => rename(old_path, new_path),
+    fsync: async (path) => {
+        // fsync flushes the inode's dirty pages regardless of the fd's open mode,
+        // so a read handle is enough (and needs no write permission).
+        const handle = await open(path, 'r');
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    },
     remove: (path, options) => rm(path, options),
     // === HTTP ===
     fetch: globalThis.fetch,

package/dist/server/fact_write.js

@@ -14,7 +14,7 @@ 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';
+import { mint_file_fact_url } from '../db/file_fact_url.js';
 /**
  * Write `bytes` as a fact, choosing embedded (PG) vs external (disk +
  * `put_ref`) based on `embedded_threshold`. Returns the canonical

package/dist/server/file_fact_fetcher.js

@@ -27,7 +27,7 @@ import { readFile } from 'node:fs/promises';
 import { createReadStream } from 'node:fs';
 import { Readable } from 'node:stream';
 import { join } from 'node:path';
-import { parse_file_fact_url } from './file_fact_url.js';
+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

package/dist/server/serve_fact_route.js

@@ -89,7 +89,7 @@ import { query_get_fact, query_get_fact_meta } from '../db/fact_queries.js';
 import { query_cell_get } from '../db/cell_queries.js';
 import { query_cell_grant_list_for_cell } from '../db/cell_grant_queries.js';
 import { can_view_cell } from '../auth/cell_authorize.js';
-import { parse_file_fact_url } from './file_fact_url.js';
+import { parse_file_fact_url } from '../db/file_fact_url.js';
 /** `Cache-Control` for fact responses — 5 min revocation window. */
 const CACHE_CONTROL = 'private, max-age=300';
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_app",
-  "version": "0.81.0",
+  "version": "0.82.0",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",

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

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