@fuzdev/fuz_app 0.81.0 → 0.83.0

package/dist/auth/account_queries.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"account_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/account_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAEN,KAAK,OAAO,EACZ,KAAK,KAAK,EACV,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,MAAM,qBAAqB,CAAC;AAG7B;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,SAAS,EACf,OAAO,kBAAkB,KACvB,OAAO,CAAC,OAAO,CAQjB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,SAAS,EACf,IAAI,MAAM,KACR,OAAO,CAAC,OAAO,GAAG,SAAS,CAI7B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,SAAS,EACf,UAAU,MAAM,KACd,OAAO,CAAC,OAAO,GAAG,SAAS,CAI7B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,SAAS,EACf,OAAO,MAAM,KACX,OAAO,CAAC,OAAO,GAAG,SAAS,CAI7B,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,kCAAkC,GAC9C,MAAM,SAAS,EACf,OAAO,MAAM,KACX,OAAO,CAAC,OAAO,GAAG,SAAS,CAS7B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,6BAA6B,GACzC,MAAM,SAAS,EACf,IAAI,MAAM,EACV,eAAe,MAAM,EACrB,YAAY,MAAM,GAAG,IAAI,EACzB,eAAe,MAAM,KACnB,OAAO,CAAC,OAAO,CAQjB,CAAC;AAEF;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,SAAS,EACf,IAAI,MAAM,EACV,YAAY,MAAM,GAAG,IAAI,KACvB,OAAO,CAAC,uBAAuB,GAAG,SAAS,CAO7C,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,SAAS,EACf,IAAI,MAAM,KACR,OAAO,CAAC,uBAAuB,GAAG,SAAS,CAK7C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,SAAS,EACf,IAAI,MAAM,EACV,YAAY,MAAM,GAAG,IAAI,KACvB,OAAO,CAAC,OAAO,CAQjB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,SAAS,EACf,IAAI,MAAM,KACR,OAAO,CAAC,uBAAuB,GAAG,SAAS,CAO7C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAAU,MAAM,SAAS,EAAE,IAAI,MAAM,KAAG,OAAO,CAAC,OAAO,CAQvF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,qBAAqB,GAAU,MAAM,SAAS,KAAG,OAAO,CAAC,OAAO,CAK5E,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAC9B,MAAM,SAAS,EACf,YAAY,MAAM,EAClB,MAAM,MAAM,KACV,OAAO,CAAC,KAAK,CAMf,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,SAAS,EACf,YAAY,MAAM,KAChB,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAKtB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iBAAiB,GAC7B,MAAM,SAAS,EACf,IAAI,MAAM,KACR,OAAO,CAAC,KAAK,GAAG,SAAS,CAE3B,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,+BAA+B,GAC3C,MAAM,SAAS,EACf,OAAO,kBAAkB,KACvB,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAC,CAI1C,CAAC;AA2BF,8CAA8C;AAC9C,MAAM,WAAW,uBAAuB;IACvC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,wCAAwC;IACxC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,SAAS,EACf,UAAU,uBAAuB,KAC/B,OAAO,CAAC,KAAK,CAAC,qBAAqB,CAAC,CA8GtC,CAAC"}
+{"version":3,"file":"account_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/account_queries.ts"],"names":[],"mappings":"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"}

package/dist/auth/account_queries.js

@@ -9,6 +9,22 @@
 import { assert_row } from '../db/assert_row.js';
 import { to_admin_account, } from './account_schema.js';
 import { ADMIN_ACCOUNT_LIST_DEFAULT_LIMIT } from './admin_action_specs.js';
+/**
+ * The full `account` column set, named explicitly so a row read fails loud
+ * on schema drift.
+ *
+ * `SELECT *` silently omits a dropped column, which the login lookups then
+ * misread: `query_account_by_username_or_email` filters its result with
+ * `account.deleted_at === null`, so a missing `deleted_at` column reads back
+ * as `undefined`, `undefined === null` is `false`, and *every* login resolves
+ * to "not found" (401) — a silent, total auth outage instead of an error.
+ * Selecting named columns turns that drift into a hard Postgres
+ * `column "..." does not exist`. Mirrors the Rust side
+ * (`fuz_auth/src/account_queries.rs`), which selects named columns and
+ * decodes them positionally. Keep in sync with `Account` and the `account`
+ * DDL in `auth/auth_ddl.ts`.
+ */
+const ACCOUNT_COLUMNS = 'id, username, email, email_verified, password_hash, created_at, created_by, updated_at, updated_by, deleted_at, deleted_by';
 /**
  * Create a new account.
  *
@@ -33,25 +49,19 @@ export const query_create_account = async (deps, input) => {
  * soft-deleted rows too, uses `query_purge_account` directly.
  */
 export const query_account_by_id = async (deps, id) => {
-    return deps.db.query_one(`SELECT * FROM account WHERE id = $1 AND deleted_at IS NULL`, [
-        id,
-    ]);
+    return deps.db.query_one(`SELECT ${ACCOUNT_COLUMNS} FROM account WHERE id = $1 AND deleted_at IS NULL`, [id]);
 };
 /**
  * Find an account by username (case-insensitive).
  */
 export const query_account_by_username = async (deps, username) => {
-    return deps.db.query_one(`SELECT * FROM account WHERE LOWER(username) = LOWER($1)`, [
-        username,
-    ]);
+    return deps.db.query_one(`SELECT ${ACCOUNT_COLUMNS} FROM account WHERE LOWER(username) = LOWER($1)`, [username]);
 };
 /**
  * Find an account by email (case-insensitive).
  */
 export const query_account_by_email = async (deps, email) => {
-    return deps.db.query_one(`SELECT * FROM account WHERE LOWER(email) = LOWER($1)`, [
-        email,
-    ]);
+    return deps.db.query_one(`SELECT ${ACCOUNT_COLUMNS} FROM account WHERE LOWER(email) = LOWER($1)`, [email]);
 };
 /**
  * Find an account by username or email.

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