@fuzdev/fuz_app 0.143.0 → 0.145.0

package/dist/db/cell_queries.js

@@ -4,11 +4,11 @@
  * Convention: `deps: QueryDeps` first, no audit side effects, mutations
  * return the affected row (or `null` for not-found).
  *
- * `cell.refs` is auto-extracted from `data` on every create and update via
- * `fact_hash_extract_refs` (depth-first walk for `blake3:`-prefixed strings). Callers
- * never pass `refs` directly — the column is a derived projection of
- * `data` for cells-by-fact discovery, mirroring what a fact store does for
- * JSON facts.
+ * `cell.refs` is derived from `data` on every create and update via
+ * `derive_cell_refs` (depth-first walk for string values that are exactly a
+ * fact hash). Callers never pass `refs` directly — the column is a derived
+ * projection of `data`, what fact serving admits a read through and what
+ * cell ref admission (`auth/cell_ref_admission.ts`) gates on a write.
  *
  * Soft delete via `deleted_at`. All `get` / `list` queries exclude
  * tombstones by default; `include_deleted: true` opts in for admin /
@@ -20,7 +20,7 @@
  *
  * @module
  */
-import { fact_hash_extract_refs } from '@fuzdev/fuz_util/fact_hash.ts';
+import { is_fact_hash } from '@fuzdev/fuz_util/hash_schemas.ts';
 import { assert_row } from './assert_row.js';
 import { columns_sql, iso8601_timestamp_expr, qualify_columns } from './sql_columns.js';
 import { cell_moderation_admits_audience_sql, cell_moderation_is_stewardable_sql } from './cell_moderation.js';
@@ -98,7 +98,7 @@ export const CELL_VIEW_COLUMNS = [
  * @mutates `cell` - inserts one row
  */
 export const query_cell_create = async (deps, input) => {
-    const refs = derive_refs(input.data);
+    const refs = derive_cell_refs(input.data);
     const row = await deps.db.query_one(`INSERT INTO cell
 		   (data, kind, visibility, path, refs, parent_id, root_id, moderation, created_by)
 		 VALUES ($1::jsonb, $2, COALESCE($3::cell_visibility, 'private'::cell_visibility), $4, $5::text[], $6, $7, $8, $9)
@@ -196,7 +196,7 @@ export const query_cell_view_load_many = async (deps, ids) => {
  */
 export const query_cell_update = async (deps, id, patch) => {
     const data_provided = patch.data !== undefined;
-    const refs = data_provided ? derive_refs(patch.data) : null;
+    const refs = data_provided ? derive_cell_refs(patch.data) : null;
     const visibility_provided = patch.visibility !== undefined;
     const row = await deps.db.query_one(`UPDATE cell SET
 		   data       = CASE WHEN $2::bool THEN $3::jsonb ELSE data END,
@@ -485,20 +485,47 @@ const build_shared_with_sql = (order_column, order_direction) => `${CALLER_ROLE_
 	 ORDER BY c.${order_column} ${order_direction} NULLS LAST
 	 LIMIT $8 OFFSET $9`;
 /**
- * Derive the `refs` array column value from a cell's `data`.
+ * Derive the `refs` array column value from a cell's `data`: the string
+ * values that are exactly a fact hash, deduped and sorted.
+ *
+ * A ref is a **whole** string value matching the wire fact-hash grammar —
+ * `blake3:` followed by exactly sixty-four lowercase hex characters
+ * (`is_fact_hash`, `FACT_HASH_EXACT`). A hash inside prose or markup, an
+ * uppercase-hex digest, or a `blake3:` string of any other length is not a
+ * ref. Refs are what fact serving admits a read through and what cell ref
+ * admission gates on a write, so the grammar is exact: a string either is an
+ * address or isn't one. Object keys are not walked — only values. (JSON facts'
+ * `fact_ref` edges keep `fact_hash_extract_refs`, the substring scan.)
  *
  * Returns `null` (rather than `[]`) when no refs are present — the column
  * is nullable and the `idx_cell_refs` partial index is `WHERE refs IS NOT
  * NULL`, so an empty array would force every cell into the index.
  *
- * Sorts the deduped refs lexicographically so the stored `text[]` is
- * deterministic and byte-identical to the Rust twin (`fuz_cell`'s
- * `extract_refs`, which sorts the same `blake3:`-prefixed element form).
- * The shared `fact_hash_extract_refs` deliberately preserves traversal
- * order per its contract, so the sort lives here at the storage boundary,
- * not in the util.
+ * Sorts the deduped refs so the stored `text[]` is deterministic and
+ * byte-identical to the Rust twin (`fuz_cell`'s `extract_refs`); every ref is
+ * ASCII, so the code-unit sort here and the byte sort there agree.
+ *
+ * @param data - the cell's `data`
+ * @returns the sorted refs, or `null` when there are none
  */
-const derive_refs = (data) => {
-    const refs = fact_hash_extract_refs(data);
-    return refs.length > 0 ? refs.sort() : null;
+export const derive_cell_refs = (data) => {
+    const found = new Set();
+    collect_cell_refs(data, found);
+    return found.size > 0 ? [...found].sort() : null;
+};
+const collect_cell_refs = (value, found) => {
+    if (typeof value === 'string') {
+        if (is_fact_hash(value))
+            found.add(value);
+        return;
+    }
+    if (value === null || typeof value !== 'object')
+        return;
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collect_cell_refs(item, found);
+        return;
+    }
+    for (const v of Object.values(value))
+        collect_cell_refs(v, found);
 };

package/dist/db/fact_ddl.d.ts

@@ -1,7 +1,7 @@
 /**
- * Fact + memo PG schema.
+ * Fact + memo + possession PG schema.
  *
- * Three tables:
+ * Tables:
  *
  * - `fact` — content-addressed bytes. `hash = 'blake3:<hex64>'`. Either
  *   embedded (`bytes`) or referenced (`external_url`); the CHECK constraint
@@ -11,6 +11,20 @@
  *   `target_hash` is intentionally **not** a foreign key: in federation a
  *   reference may target a fact stored on another instance.
  * - `memo` — `(fn_id, input_hash) → output_hash` for memoized computations.
+ * - `fact_holder` — which actors hold which facts: one row per `(actor, fact)`
+ *   the actor has put, the possession record cell ref admission reads.
+ *
+ * `fact_holder.actor_id` references the auth schema's `actor` table, so the
+ * namespace runs after `fuz_auth`.
+ *
+ * **The released chain is frozen — every schema change ships as an appended
+ * migration.** Migrations are tracked by `(namespace, name)` with no checksum,
+ * so editing a released entry in place never reruns on a database that already
+ * recorded it. Never edit, rename, reorder, or re-purpose an entry in
+ * `FACT_MIGRATIONS`; append a new one with idempotent DDL. Each entry is
+ * twinned with the Rust `fuz_fact` migration of the same name and position,
+ * statement for statement (the `_testing_migration_tracker` and schema-parity
+ * gates compare the two).
  *
  * @module
  */
@@ -27,9 +41,21 @@ export declare const FACT_REFS_SCHEMA = "\nCREATE TABLE IF NOT EXISTS fact_ref (
 export declare const FACT_REFS_TARGET_INDEX = "\nCREATE INDEX IF NOT EXISTS idx_fact_ref_target ON fact_ref(target_hash)";
 /** `memo` table — `(fn_id, input_hash) → output_hash` for memoized computations. */
 export declare const MEMOS_SCHEMA = "\nCREATE TABLE IF NOT EXISTS memo (\n\tfn_id TEXT NOT NULL,\n\tinput_hash TEXT NOT NULL,\n\toutput_hash TEXT NOT NULL,\n\tcreated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n\tPRIMARY KEY (fn_id, input_hash)\n)";
+/**
+ * `fact_holder` table — the possession record: one row per `(actor, fact)` the
+ * actor has put, a deduplicated put by a second actor included.
+ *
+ * Both FKs cascade: deleting an actor erases its possession, and deleting a
+ * fact (the orphan sweep) drops its holders. The primary key leads with
+ * `actor_id`, serving the admission lookup and the actor-side cascade.
+ * `created_at` is the holder's most recent put, not the first.
+ */
+export declare const FACT_HOLDER_SCHEMA = "\nCREATE TABLE IF NOT EXISTS fact_holder (\n\tactor_id UUID NOT NULL REFERENCES actor(id) ON DELETE CASCADE,\n\thash TEXT NOT NULL REFERENCES fact(hash) ON DELETE CASCADE,\n\tcreated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),\n\tPRIMARY KEY (actor_id, hash)\n)";
+/** Serves the fact-side cascade of `fact_holder`. */
+export declare const FACT_HOLDER_HASH_INDEX = "\nCREATE INDEX IF NOT EXISTS idx_fact_holder_hash ON fact_holder(hash)";
 /** Tables created by `FACT_MIGRATION_NS`, in drop order (children first). */
-export declare const FACT_DROP_TABLES: readonly ["memo", "fact_ref", "fact"];
-/** Fact + memo migrations. */
+export declare const FACT_DROP_TABLES: readonly ["fact_holder", "memo", "fact_ref", "fact"];
+/** Fact + memo + possession migrations. Frozen + append-only — see the module doc. */
 export declare const FACT_MIGRATIONS: Array<Migration>;
 /** Namespace identifier for fact + memo migrations. */
 export declare const FACT_MIGRATION_NAMESPACE = "fuz_facts";

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

@@ -1 +1 @@
-{"version":3,"file":"fact_ddl.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/fact_ddl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElE,mDAAmD;AACnD,eAAO,MAAM,YAAY,qSASvB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,6LAK3B,CAAC;AAEH,4DAA4D;AAC5D,eAAO,MAAM,sBAAsB,8EACqC,CAAC;AAEzE,oFAAoF;AACpF,eAAO,MAAM,YAAY,mNAOvB,CAAC;AAEH,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB,uCAAwC,CAAC;AAEtE,8BAA8B;AAC9B,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,SAAS,CAU5C,CAAC;AAEF,uDAAuD;AACvD,eAAO,MAAM,wBAAwB,cAAc,CAAC;AAEpD,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,EAAE,kBAG/B,CAAC"}
+{"version":3,"file":"fact_ddl.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/fact_ddl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElE,mDAAmD;AACnD,eAAO,MAAM,YAAY,qSASvB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,6LAK3B,CAAC;AAEH,4DAA4D;AAC5D,eAAO,MAAM,sBAAsB,8EACqC,CAAC;AAEzE,oFAAoF;AACpF,eAAO,MAAM,YAAY,mNAOvB,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,qQAM7B,CAAC;AAEH,qDAAqD;AACrD,eAAO,MAAM,sBAAsB,2EACkC,CAAC;AAEtE,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB,sDAAuD,CAAC;AAErF,sFAAsF;AACtF,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,SAAS,CAiB5C,CAAC;AAEF,uDAAuD;AACvD,eAAO,MAAM,wBAAwB,cAAc,CAAC;AAEpD,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,EAAE,kBAG/B,CAAC"}

package/dist/db/fact_ddl.js

@@ -1,7 +1,7 @@
 /**
- * Fact + memo PG schema.
+ * Fact + memo + possession PG schema.
  *
- * Three tables:
+ * Tables:
  *
  * - `fact` — content-addressed bytes. `hash = 'blake3:<hex64>'`. Either
  *   embedded (`bytes`) or referenced (`external_url`); the CHECK constraint
@@ -11,6 +11,20 @@
  *   `target_hash` is intentionally **not** a foreign key: in federation a
  *   reference may target a fact stored on another instance.
  * - `memo` — `(fn_id, input_hash) → output_hash` for memoized computations.
+ * - `fact_holder` — which actors hold which facts: one row per `(actor, fact)`
+ *   the actor has put, the possession record cell ref admission reads.
+ *
+ * `fact_holder.actor_id` references the auth schema's `actor` table, so the
+ * namespace runs after `fuz_auth`.
+ *
+ * **The released chain is frozen — every schema change ships as an appended
+ * migration.** Migrations are tracked by `(namespace, name)` with no checksum,
+ * so editing a released entry in place never reruns on a database that already
+ * recorded it. Never edit, rename, reorder, or re-purpose an entry in
+ * `FACT_MIGRATIONS`; append a new one with idempotent DDL. Each entry is
+ * twinned with the Rust `fuz_fact` migration of the same name and position,
+ * statement for statement (the `_testing_migration_tracker` and schema-parity
+ * gates compare the two).
  *
  * @module
  */
@@ -48,9 +62,28 @@ CREATE TABLE IF NOT EXISTS memo (
 	created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
 	PRIMARY KEY (fn_id, input_hash)
 )`;
+/**
+ * `fact_holder` table — the possession record: one row per `(actor, fact)` the
+ * actor has put, a deduplicated put by a second actor included.
+ *
+ * Both FKs cascade: deleting an actor erases its possession, and deleting a
+ * fact (the orphan sweep) drops its holders. The primary key leads with
+ * `actor_id`, serving the admission lookup and the actor-side cascade.
+ * `created_at` is the holder's most recent put, not the first.
+ */
+export const FACT_HOLDER_SCHEMA = `
+CREATE TABLE IF NOT EXISTS fact_holder (
+	actor_id UUID NOT NULL REFERENCES actor(id) ON DELETE CASCADE,
+	hash TEXT NOT NULL REFERENCES fact(hash) ON DELETE CASCADE,
+	created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+	PRIMARY KEY (actor_id, hash)
+)`;
+/** Serves the fact-side cascade of `fact_holder`. */
+export const FACT_HOLDER_HASH_INDEX = `
+CREATE INDEX IF NOT EXISTS idx_fact_holder_hash ON fact_holder(hash)`;
 /** Tables created by `FACT_MIGRATION_NS`, in drop order (children first). */
-export const FACT_DROP_TABLES = ['memo', 'fact_ref', 'fact'];
-/** Fact + memo migrations. */
+export const FACT_DROP_TABLES = ['fact_holder', 'memo', 'fact_ref', 'fact'];
+/** Fact + memo + possession migrations. Frozen + append-only — see the module doc. */
 export const FACT_MIGRATIONS = [
     {
         name: 'full_fact_schema',
@@ -60,6 +93,13 @@ export const FACT_MIGRATIONS = [
             await db.query(FACT_REFS_TARGET_INDEX);
             await db.query(MEMOS_SCHEMA);
         }
+    },
+    {
+        name: 'fact_holder',
+        up: async (db) => {
+            await db.query(FACT_HOLDER_SCHEMA);
+            await db.query(FACT_HOLDER_HASH_INDEX);
+        }
     }
 ];
 /** Namespace identifier for fact + memo migrations. */

package/dist/db/fact_holder_queries.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Raw queries against `fact_holder` — the possession record.
+ *
+ * A `fact_holder` row says an actor has put a fact's bytes. `PgFactStore`
+ * writes one on every put that names a holder (`HeldFactPutOptions.holder`),
+ * deduplicated puts included: identical bytes put again by a second actor
+ * make that actor a holder too. Cell ref admission
+ * (`auth/cell_ref_admission.ts`) reads it back — a write may introduce a fact
+ * ref only for a fact the acting actor holds.
+ *
+ * Same discipline as `db/fact_queries.ts`: `deps: QueryDeps` first (the caller
+ * owns the transaction), no audit side effects, idempotent writes.
+ *
+ * @module
+ */
+import type { FactHash } from '@fuzdev/fuz_util/hash_schemas.ts';
+import type { QueryDeps } from './query_deps.js';
+import type { Uuid } from '../primitive_schemas.js';
+/** Row shape of `fact_holder`. */
+export interface FactHolderRow {
+    actor_id: Uuid;
+    hash: FactHash;
+    created_at: Date;
+}
+/**
+ * The `fact_holder` table's columns.
+ *
+ * Twin of the Rust `fuz_fact::FACT_HOLDER_COLUMNS` (same names, same order).
+ * No query reads whole rows — admission reads hashes only — so the const is
+ * the drift guard's anchor rather than a projection source.
+ */
+export declare const FACT_HOLDER_COLUMNS: readonly ["actor_id", "hash", "created_at"];
+/**
+ * Record `actor_id` as a holder of `hash`, or refresh the row's `created_at`
+ * when it already holds it. The `fact` row must already exist (FK).
+ *
+ * `created_at` is the holder's most recent put, which the orphan sweep reads
+ * as the fact's grace window: a re-put keeps an old orphan out of any
+ * sweep whose window covers the put.
+ *
+ * @param deps - query deps
+ * @param actor_id - the actor that brought the bytes
+ * @param hash - the fact's hash
+ * @mutates fact_holder - inserts the `(actor_id, hash)` row, or sets an existing row's `created_at` to now
+ */
+export declare const query_put_fact_holder: (deps: QueryDeps, actor_id: Uuid, hash: FactHash) => Promise<void>;
+/**
+ * Whether the `fact_holder` table exists — `false` on a database that mounts
+ * the cell verbs without the fact chain.
+ *
+ * Probed before `query_fact_holder_unheld`, since naming a missing table
+ * would abort the caller's transaction. Twin of the Rust admission's
+ * `to_regclass('fact_holder')` probe, read from `information_schema` (which
+ * every supported driver answers).
+ */
+export declare const query_fact_holder_table_exists: (deps: QueryDeps) => Promise<boolean>;
+/**
+ * The subset of `hashes` that `actor_id` does **not** hold, in input order.
+ *
+ * Answered from `fact_holder` alone: a hash with no stored fact and a stored
+ * fact the actor never put read the same. Hashes are compared as text. The
+ * caller has checked the table exists.
+ *
+ * @param deps - query deps
+ * @param actor_id - the acting actor
+ * @param hashes - the candidate hashes
+ * @returns the hashes with no `(actor_id, hash)` row
+ */
+export declare const query_fact_holder_unheld: (deps: QueryDeps, actor_id: Uuid, hashes: ReadonlyArray<string>) => Promise<Array<string>>;
+//# sourceMappingURL=fact_holder_queries.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fact_holder_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/fact_holder_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAEjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEpD,kCAAkC;AAClC,MAAM,WAAW,aAAa;IAC7B,QAAQ,EAAE,IAAI,CAAC;IACf,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,IAAI,CAAC;CACjB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,6CAIuB,CAAC;AAExD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qBAAqB,GACjC,MAAM,SAAS,EACf,UAAU,IAAI,EACd,MAAM,QAAQ,KACZ,OAAO,CAAC,IAAI,CAMd,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,8BAA8B,GAAU,MAAM,SAAS,KAAG,OAAO,CAAC,OAAO,CAQrF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB,GACpC,MAAM,SAAS,EACf,UAAU,IAAI,EACd,QAAQ,aAAa,CAAC,MAAM,CAAC,KAC3B,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAQvB,CAAC"}

package/dist/db/fact_holder_queries.js

@@ -0,0 +1,79 @@
+/**
+ * Raw queries against `fact_holder` — the possession record.
+ *
+ * A `fact_holder` row says an actor has put a fact's bytes. `PgFactStore`
+ * writes one on every put that names a holder (`HeldFactPutOptions.holder`),
+ * deduplicated puts included: identical bytes put again by a second actor
+ * make that actor a holder too. Cell ref admission
+ * (`auth/cell_ref_admission.ts`) reads it back — a write may introduce a fact
+ * ref only for a fact the acting actor holds.
+ *
+ * Same discipline as `db/fact_queries.ts`: `deps: QueryDeps` first (the caller
+ * owns the transaction), no audit side effects, idempotent writes.
+ *
+ * @module
+ */
+/**
+ * The `fact_holder` table's columns.
+ *
+ * Twin of the Rust `fuz_fact::FACT_HOLDER_COLUMNS` (same names, same order).
+ * No query reads whole rows — admission reads hashes only — so the const is
+ * the drift guard's anchor rather than a projection source.
+ */
+export const FACT_HOLDER_COLUMNS = [
+    'actor_id',
+    'hash',
+    'created_at'
+];
+/**
+ * Record `actor_id` as a holder of `hash`, or refresh the row's `created_at`
+ * when it already holds it. The `fact` row must already exist (FK).
+ *
+ * `created_at` is the holder's most recent put, which the orphan sweep reads
+ * as the fact's grace window: a re-put keeps an old orphan out of any
+ * sweep whose window covers the put.
+ *
+ * @param deps - query deps
+ * @param actor_id - the actor that brought the bytes
+ * @param hash - the fact's hash
+ * @mutates fact_holder - inserts the `(actor_id, hash)` row, or sets an existing row's `created_at` to now
+ */
+export const query_put_fact_holder = async (deps, actor_id, hash) => {
+    await deps.db.query(`INSERT INTO fact_holder (actor_id, hash) VALUES ($1, $2)
+		 ON CONFLICT (actor_id, hash) DO UPDATE SET created_at = NOW()`, [actor_id, hash]);
+};
+/**
+ * Whether the `fact_holder` table exists — `false` on a database that mounts
+ * the cell verbs without the fact chain.
+ *
+ * Probed before `query_fact_holder_unheld`, since naming a missing table
+ * would abort the caller's transaction. Twin of the Rust admission's
+ * `to_regclass('fact_holder')` probe, read from `information_schema` (which
+ * every supported driver answers).
+ */
+export const query_fact_holder_table_exists = async (deps) => {
+    const row = await deps.db.query_one(`SELECT EXISTS (
+			SELECT 1 FROM information_schema.tables
+			WHERE table_schema = 'public' AND table_name = 'fact_holder'
+		) AS exists`);
+    return row?.exists === true;
+};
+/**
+ * The subset of `hashes` that `actor_id` does **not** hold, in input order.
+ *
+ * Answered from `fact_holder` alone: a hash with no stored fact and a stored
+ * fact the actor never put read the same. Hashes are compared as text. The
+ * caller has checked the table exists.
+ *
+ * @param deps - query deps
+ * @param actor_id - the acting actor
+ * @param hashes - the candidate hashes
+ * @returns the hashes with no `(actor_id, hash)` row
+ */
+export const query_fact_holder_unheld = async (deps, actor_id, hashes) => {
+    if (hashes.length === 0)
+        return [];
+    const rows = await deps.db.query(`SELECT hash FROM fact_holder WHERE actor_id = $1 AND hash = ANY($2::text[])`, [actor_id, hashes]);
+    const held = new Set(rows.map((r) => r.hash));
+    return hashes.filter((h) => !held.has(h));
+};

package/dist/db/fact_queries.d.ts

@@ -37,6 +37,14 @@ export interface FactMetaRow {
     size: number | string;
     created_at: Date;
 }
+/** Input for `query_put_fact` — one `fact` row. Twin of the Rust `PutFactInput`. */
+export interface PutFactInput {
+    hash: FactHash;
+    bytes: Uint8Array | null;
+    external_url: string | null;
+    content_type: string | null;
+    size: number;
+}
 /**
  * Idempotently insert a fact row.
  *
@@ -46,13 +54,7 @@ export interface FactMetaRow {
  * inserted, `false` when a row already existed (caller can use this to
  * decide whether to also write `fact_ref`).
  */
-export declare const query_put_fact: (deps: QueryDeps, input: {
-    hash: FactHash;
-    bytes: Uint8Array | null;
-    external_url: string | null;
-    content_type: string | null;
-    size: number;
-}) => Promise<boolean>;
+export declare const query_put_fact: (deps: QueryDeps, input: PutFactInput) => Promise<boolean>;
 /**
  * Idempotently insert declared refs for a fact. No-ops on `(source_hash,
  * target_hash)` collisions and skips the round trip entirely when
@@ -121,14 +123,15 @@ export interface OrphanFactsListResult {
  * outputs? external fact mirrors?) the predicate moves to a generic
  * `fact_consumers` registry; today the cell layer is the only consumer.
  *
- * The `older_than` filter applies to `fact.created_at`. Pass `null`
- * to skip the filter (used by the list-summary preview); the delete
- * handler always passes a non-null cutoff (default 0, meaning "any
- * orphan").
+ * The `older_than` filter is the grace cutoff: a fact passes it when both
+ * its `created_at` and every `fact_holder` row's are older (a re-put
+ * refreshes the holder row). Pass `null` to skip the filter (used by the
+ * list-summary preview); the delete handler always passes a non-null
+ * cutoff (default 0, meaning "any orphan").
  *
  * @param deps - query deps
- * @param older_than - filter to facts created before this Date (or null
- *   to skip)
+ * @param older_than - filter to facts created, and last put by any holder,
+ *   before this Date (or null to skip)
  * @param sample_limit - row cap for the returned `sample`
  */
 export declare const query_orphan_facts_list: (deps: QueryDeps, older_than: Date | null, sample_limit: number) => Promise<OrphanFactsListResult>;
@@ -137,7 +140,9 @@ export declare const query_orphan_facts_list: (deps: QueryDeps, older_than: Date
  * (no row-count limit) — callers iterate to unlink disk files. The
  * `older_than` cutoff is required (non-null) here: bulk delete should
  * always be operator-scoped to a time window. A "delete all" sweep
- * passes a far-future cutoff, not `null`.
+ * passes a far-future cutoff, not `null`. It is the same grace cutoff as
+ * `query_orphan_facts_list`: a fact put — or re-put, deduplicated — by an
+ * actor within the window is kept, whatever its own `created_at`.
  */
 export declare const query_orphan_facts_select_for_delete: (deps: QueryDeps, older_than: Date) => Promise<Array<{
     hash: FactHash;

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

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

package/dist/db/fact_queries.js

@@ -113,6 +113,21 @@ export const query_delete_fact = async (deps, hash) => {
         return null;
     return { size: Number(row.size), external_url: row.external_url };
 };
+/**
+ * The grace-window half of the orphan cutoff: no `fact_holder` row was
+ * recorded (or refreshed) at or after `$1`. A dedup put adds no `fact` row,
+ * so `fact.created_at` stays at the first insert — without this, an old
+ * orphan an actor re-uploads looks stale, and a sweep between the upload and
+ * the cell write that references it deletes the fact (and, by cascade, the
+ * possession the write needs). A fact counts as recent when its own
+ * `created_at` or any holder's is within the window. Served by
+ * `idx_fact_holder_hash`. Twin of the Rust `ORPHAN_FACT_NOT_RECENTLY_HELD`.
+ */
+const ORPHAN_FACT_NOT_RECENTLY_HELD = `NOT EXISTS (
+		   SELECT 1 FROM fact_holder h
+		   WHERE h.hash = f.hash
+		     AND h.created_at >= $1::timestamptz
+		 )`;
 /**
  * Compute the "orphan facts" set: rows in `fact` where no active
  * (non-tombstone) `cell.refs` array contains the hash.
@@ -124,14 +139,15 @@ export const query_delete_fact = async (deps, hash) => {
  * outputs? external fact mirrors?) the predicate moves to a generic
  * `fact_consumers` registry; today the cell layer is the only consumer.
  *
- * The `older_than` filter applies to `fact.created_at`. Pass `null`
- * to skip the filter (used by the list-summary preview); the delete
- * handler always passes a non-null cutoff (default 0, meaning "any
- * orphan").
+ * The `older_than` filter is the grace cutoff: a fact passes it when both
+ * its `created_at` and every `fact_holder` row's are older (a re-put
+ * refreshes the holder row). Pass `null` to skip the filter (used by the
+ * list-summary preview); the delete handler always passes a non-null
+ * cutoff (default 0, meaning "any orphan").
  *
  * @param deps - query deps
- * @param older_than - filter to facts created before this Date (or null
- *   to skip)
+ * @param older_than - filter to facts created, and last put by any holder,
+ *   before this Date (or null to skip)
  * @param sample_limit - row cap for the returned `sample`
  */
 export const query_orphan_facts_list = async (deps, older_than, sample_limit) => {
@@ -142,7 +158,8 @@ export const query_orphan_facts_list = async (deps, older_than, sample_limit) =>
 		   WHERE c.refs @> ARRAY[f.hash]::text[]
 		     AND c.deleted_at IS NULL
 		 )
-		 AND ($1::timestamptz IS NULL OR f.created_at < $1::timestamptz)`, [older_than]);
+		 AND ($1::timestamptz IS NULL
+		      OR (f.created_at < $1::timestamptz AND ${ORPHAN_FACT_NOT_RECENTLY_HELD}))`, [older_than]);
     const sample_rows = await deps.db.query(`SELECT hash, size, ${iso8601_timestamp_column('f', 'created_at')} AS created_at, external_url
 		 FROM fact f
 		 WHERE NOT EXISTS (
@@ -150,7 +167,8 @@ export const query_orphan_facts_list = async (deps, older_than, sample_limit) =>
 		   WHERE c.refs @> ARRAY[f.hash]::text[]
 		     AND c.deleted_at IS NULL
 		 )
-		 AND ($1::timestamptz IS NULL OR f.created_at < $1::timestamptz)
+		 AND ($1::timestamptz IS NULL
+		      OR (f.created_at < $1::timestamptz AND ${ORPHAN_FACT_NOT_RECENTLY_HELD}))
 		 ORDER BY f.created_at ASC
 		 LIMIT $2`, [older_than, sample_limit]);
     return {
@@ -169,7 +187,9 @@ export const query_orphan_facts_list = async (deps, older_than, sample_limit) =>
  * (no row-count limit) — callers iterate to unlink disk files. The
  * `older_than` cutoff is required (non-null) here: bulk delete should
  * always be operator-scoped to a time window. A "delete all" sweep
- * passes a far-future cutoff, not `null`.
+ * passes a far-future cutoff, not `null`. It is the same grace cutoff as
+ * `query_orphan_facts_list`: a fact put — or re-put, deduplicated — by an
+ * actor within the window is kept, whatever its own `created_at`.
  */
 export const query_orphan_facts_select_for_delete = async (deps, older_than) => {
     const rows = await deps.db.query(`SELECT hash, size, external_url
@@ -179,6 +199,7 @@ export const query_orphan_facts_select_for_delete = async (deps, older_than) =>
 		   WHERE c.refs @> ARRAY[f.hash]::text[]
 		     AND c.deleted_at IS NULL
 		 )
-		 AND f.created_at < $1::timestamptz`, [older_than]);
+		 AND f.created_at < $1::timestamptz
+		 AND ${ORPHAN_FACT_NOT_RECENTLY_HELD}`, [older_than]);
     return rows.map((r) => ({ hash: r.hash, size: Number(r.size), external_url: r.external_url }));
 };