@fuzdev/fuz_app 0.67.1 → 0.69.0

package/dist/db/cell_grant_queries.js

@@ -0,0 +1,145 @@
+/**
+ * Raw queries against the `cell_grant` table.
+ *
+ * Resource-side ACL for cells: each row admits a principal at a `level`
+ * (`viewer` | `editor`). Principal is discriminated by which columns are
+ * set — `actor_id` (single actor) xor `(role, scope_id?)` (any holder
+ * of a matching role_grant). Owner is implicit on `cell.created_by` and never
+ * appears in this table.
+ *
+ * Convention: `deps: QueryDeps` first, no audit side effects, mutations
+ * return the affected row (or `null` for not-found).
+ *
+ * `query_cell_grant_create` upserts on the relevant partial unique index so
+ * re-granting the same principal updates `level` rather than producing
+ * duplicate rows. The two principal shapes use different indexes:
+ *
+ * - Actor-shaped: `idx_cell_grant_unique_actor` on `(cell_id, actor_id)`.
+ * - Role-shaped: `idx_cell_grant_unique_role_scope` on `(cell_id, role, scope_id)`
+ *   with `NULLS NOT DISTINCT` so two `(role, NULL)` grants on the same cell
+ *   collide.
+ *
+ * @module
+ */
+import { assert_row } from './assert_row.js';
+/**
+ * Insert a grant, or update the existing row's `level` + `granted_by` when
+ * one already exists for the same `(cell_id, principal)` pair.
+ *
+ * Idempotent re-share: caller doesn't need to check existence first. The
+ * UPSERT path runs even when the existing row's level matches — handlers
+ * reading the row's prior state for audit ("create vs. update") must do
+ * so before this call.
+ *
+ * @param deps - query deps
+ * @param input - cell, level, principal, grantor
+ * @returns the inserted-or-updated row
+ * @mutates `cell_grant` - inserts or updates one row
+ */
+export const query_cell_grant_create = async (deps, input) => {
+    const { cell_id, level, principal, granted_by } = input;
+    if (principal.kind === 'actor') {
+        const row = await deps.db.query_one(`INSERT INTO cell_grant (cell_id, level, actor_id, granted_by)
+			 VALUES ($1, $2, $3, $4)
+			 ON CONFLICT (cell_id, actor_id) WHERE actor_id IS NOT NULL
+			 DO UPDATE SET level = EXCLUDED.level, granted_by = EXCLUDED.granted_by
+			 RETURNING *`, [cell_id, level, principal.actor_id, granted_by]);
+        return assert_row(row, 'INSERT INTO cell_grant (actor)');
+    }
+    const row = await deps.db.query_one(`INSERT INTO cell_grant (cell_id, level, role, scope_id, granted_by)
+		 VALUES ($1, $2, $3, $4, $5)
+		 ON CONFLICT (cell_id, role, scope_id) WHERE role IS NOT NULL
+		 DO UPDATE SET level = EXCLUDED.level, granted_by = EXCLUDED.granted_by
+		 RETURNING *`, [cell_id, level, principal.role, principal.scope_id, granted_by]);
+    return assert_row(row, 'INSERT INTO cell_grant (role)');
+};
+/**
+ * Fetch a grant by id.
+ *
+ * @param deps - query deps
+ * @param grant_id - grant id
+ * @returns the row or `null` when not found
+ */
+export const query_cell_grant_get = async (deps, grant_id) => {
+    const row = await deps.db.query_one(`SELECT * FROM cell_grant WHERE id = $1`, [
+        grant_id,
+    ]);
+    return row ?? null;
+};
+/**
+ * Delete a grant by id, returning the deleted row.
+ *
+ * Returning the row lets the caller audit the principal + level after the
+ * delete and (for self-revoke) recompute `still_admitted` against the
+ * remaining grants on the cell without a second fetch.
+ *
+ * @param deps - query deps
+ * @param grant_id - grant id
+ * @returns the deleted row or `null` when no row matched
+ * @mutates `cell_grant` - deletes one row
+ */
+export const query_cell_grant_delete = async (deps, grant_id) => {
+    const row = await deps.db.query_one(`DELETE FROM cell_grant WHERE id = $1 RETURNING *`, [grant_id]);
+    return row ?? null;
+};
+/**
+ * List all grants on a cell, oldest first.
+ *
+ * Used by `cell_grant_list` (RPC) and by handlers that need grants
+ * alongside the cell row for the authorize predicate.
+ *
+ * @param deps - query deps
+ * @param cell_id - cell id
+ * @returns matching rows
+ */
+export const query_cell_grant_list_for_cell = async (deps, cell_id) => deps.db.query(`SELECT * FROM cell_grant
+		 WHERE cell_id = $1
+		 ORDER BY created_at ASC`, [cell_id]);
+/**
+ * List all grants across a set of cells, ordered by cell then creation.
+ * Used by the strict relation-read filter to test `can_view_cell` per
+ * target in memory — the caller groups the flat result by `cell_id`.
+ * Returns **every** grant on each cell (not caller-filtered), because
+ * `can_view_cell` needs the full grant list to decide admission.
+ *
+ * @param deps - query deps
+ * @param cell_ids - cells to fetch grants for (duplicates are harmless)
+ * @returns matching grant rows (group by `cell_id` caller-side)
+ */
+export const query_cell_grant_list_for_cells = async (deps, cell_ids) => {
+    if (cell_ids.length === 0)
+        return [];
+    return deps.db.query(`SELECT * FROM cell_grant
+		 WHERE cell_id = ANY($1::uuid[])
+		 ORDER BY cell_id, created_at ASC`, [cell_ids]);
+};
+/**
+ * Load grants that admit the caller (by actor or role-scoped role_grants) across
+ * multiple cells. Used to enrich `cell_list` responses with context about what
+ * granted access. Returns grants for the given cells that match the caller's
+ * identity or role_grant set.
+ *
+ * @param cell_ids - cells to fetch grants for
+ * @param caller_actor_id - actor id of the caller (null for unauth)
+ * @param role_grant_roles - active role_grant roles (parallel array)
+ * @param role_grant_scope_ids - active role_grant scope ids (parallel array, parallel to roles)
+ * @returns matching grants (may include grants the caller doesn't match; caller's
+ * list handler must filter when returning to the API)
+ */
+export const query_cell_grants_for_caller_in_cells = async (deps, cell_ids, caller_actor_id, role_grant_roles, role_grant_scope_ids) => {
+    if (cell_ids.length === 0) {
+        return [];
+    }
+    return deps.db.query(`SELECT g.* FROM cell_grant g
+		 WHERE g.cell_id = ANY($1::uuid[])
+		   AND (
+		     g.actor_id = $2
+		     OR EXISTS (
+		       SELECT 1
+		       FROM unnest($3::text[], $4::uuid[]) AS p(role, scope_id)
+		       WHERE g.role = p.role
+		         AND (g.scope_id IS NULL OR g.scope_id IS NOT DISTINCT FROM p.scope_id)
+		     )
+		   )
+		 ORDER BY g.cell_id, g.created_at ASC`, [cell_ids, caller_actor_id, role_grant_roles, role_grant_scope_ids]);
+};

package/dist/db/cell_history_ddl.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Cell history PG schema (schema only).
+ *
+ * Lightweight references to cell state snapshots. Heavy data (serialized
+ * cell bytes) lives in the fact store; `fact_hash` points there. The
+ * snapshot lifecycle (when to serialize, hash, store, and record) is
+ * deferred to a future iteration — this only stages the table so
+ * downstream code can target a stable schema. The table ships
+ * present-but-unwritten.
+ *
+ * `fact_hash` is intentionally **not** a foreign key to `facts(hash)` —
+ * snapshots may be evicted by GC policy while history rows remain as audit
+ * traces, and federation may target facts on another instance.
+ *
+ * Depends on `CELL_MIGRATION_NS` (FK on `cell.id`).
+ *
+ * @module
+ */
+import type { Migration, MigrationNamespace } from './migrate.js';
+/** `cell_history` table — append-only log of cell snapshot references. */
+export declare const CELL_HISTORY_SCHEMA = "\nCREATE TABLE IF NOT EXISTS cell_history (\n\tid BIGSERIAL PRIMARY KEY,\n\tcell_id UUID NOT NULL REFERENCES cell(id) ON DELETE CASCADE,\n\tfact_hash TEXT NOT NULL,\n\taction_id UUID,\n\tcreated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()\n)";
+/**
+ * Cell-history indexes.
+ *
+ * - `idx_cell_history_cell`: per-cell timeline reads (newest first).
+ * - `idx_cell_history_fact`: fact → cells reverse lookup for GC liveness
+ *   and provenance queries.
+ */
+export declare const CELL_HISTORY_INDEXES: Array<string>;
+/** Tables created by `CELL_HISTORY_MIGRATION_NS`, in drop order. */
+export declare const CELL_HISTORY_DROP_TABLES: readonly ["cell_history"];
+/** Cell-history migrations. */
+export declare const CELL_HISTORY_MIGRATIONS: Array<Migration>;
+/** Namespace identifier for cell-history migrations. */
+export declare const CELL_HISTORY_MIGRATION_NAMESPACE = "fuz_cell_history";
+/** Migration namespace consumed by `run_migrations`. */
+export declare const CELL_HISTORY_MIGRATION_NS: MigrationNamespace;
+//# sourceMappingURL=cell_history_ddl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cell_history_ddl.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/cell_history_ddl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAC,SAAS,EAAE,kBAAkB,EAAC,MAAM,cAAc,CAAC;AAEhE,0EAA0E;AAC1E,eAAO,MAAM,mBAAmB,gPAO9B,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,KAAK,CAAC,MAAM,CAK9C,CAAC;AAEF,oEAAoE;AACpE,eAAO,MAAM,wBAAwB,2BAA4B,CAAC;AAElE,+BAA+B;AAC/B,eAAO,MAAM,uBAAuB,EAAE,KAAK,CAAC,SAAS,CAUpD,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,gCAAgC,qBAAqB,CAAC;AAEnE,wDAAwD;AACxD,eAAO,MAAM,yBAAyB,EAAE,kBAGvC,CAAC"}

package/dist/db/cell_history_ddl.js

@@ -0,0 +1,61 @@
+/**
+ * Cell history PG schema (schema only).
+ *
+ * Lightweight references to cell state snapshots. Heavy data (serialized
+ * cell bytes) lives in the fact store; `fact_hash` points there. The
+ * snapshot lifecycle (when to serialize, hash, store, and record) is
+ * deferred to a future iteration — this only stages the table so
+ * downstream code can target a stable schema. The table ships
+ * present-but-unwritten.
+ *
+ * `fact_hash` is intentionally **not** a foreign key to `facts(hash)` —
+ * snapshots may be evicted by GC policy while history rows remain as audit
+ * traces, and federation may target facts on another instance.
+ *
+ * Depends on `CELL_MIGRATION_NS` (FK on `cell.id`).
+ *
+ * @module
+ */
+/** `cell_history` table — append-only log of cell snapshot references. */
+export const CELL_HISTORY_SCHEMA = `
+CREATE TABLE IF NOT EXISTS cell_history (
+	id BIGSERIAL PRIMARY KEY,
+	cell_id UUID NOT NULL REFERENCES cell(id) ON DELETE CASCADE,
+	fact_hash TEXT NOT NULL,
+	action_id UUID,
+	created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+)`;
+/**
+ * Cell-history indexes.
+ *
+ * - `idx_cell_history_cell`: per-cell timeline reads (newest first).
+ * - `idx_cell_history_fact`: fact → cells reverse lookup for GC liveness
+ *   and provenance queries.
+ */
+export const CELL_HISTORY_INDEXES = [
+    `CREATE INDEX IF NOT EXISTS idx_cell_history_cell
+		ON cell_history(cell_id, created_at DESC)`,
+    `CREATE INDEX IF NOT EXISTS idx_cell_history_fact
+		ON cell_history(fact_hash)`,
+];
+/** Tables created by `CELL_HISTORY_MIGRATION_NS`, in drop order. */
+export const CELL_HISTORY_DROP_TABLES = ['cell_history'];
+/** Cell-history migrations. */
+export const CELL_HISTORY_MIGRATIONS = [
+    {
+        name: 'cell_history_v0',
+        up: async (db) => {
+            await db.query(CELL_HISTORY_SCHEMA);
+            for (const sql of CELL_HISTORY_INDEXES) {
+                await db.query(sql);
+            }
+        },
+    },
+];
+/** Namespace identifier for cell-history migrations. */
+export const CELL_HISTORY_MIGRATION_NAMESPACE = 'fuz_cell_history';
+/** Migration namespace consumed by `run_migrations`. */
+export const CELL_HISTORY_MIGRATION_NS = {
+    namespace: CELL_HISTORY_MIGRATION_NAMESPACE,
+    migrations: CELL_HISTORY_MIGRATIONS,
+};

package/dist/db/cell_item_queries.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Raw queries against the `cell_item` table.
+ *
+ * Ordered-child membership: each row is `(parent_id, position) → child_id`.
+ * `position` is opaque text (fractional-indexing key) — lex ordering is
+ * the contract. The PK on `(parent_id, position)` enforces one cell per
+ * slot but allows the same `child_id` to appear at multiple positions
+ * (the primitive is JSON-array-shaped — ordered multiset, not set;
+ * domain dedup rules ride on top).
+ *
+ * Reads filter both endpoints by `cell.deleted_at IS NULL` so items
+ * dangling off a soft-deleted cell don't surface.
+ *
+ * `query_cell_item_insert` returns the inserted row OR throws the
+ * underlying `23505` (Postgres unique violation) on a `(parent_id,
+ * position)` collision. Handlers convert this into the
+ * `cell_item_position_taken` JSON-RPC error so the client retries with a
+ * refreshed bracket.
+ *
+ * @module
+ */
+import type { QueryDeps } from './query_deps.js';
+import type { Uuid } from '@fuzdev/fuz_util/id.js';
+/** Row shape returned by `cell_item` SELECTs. */
+export interface CellItemRow {
+    parent_id: Uuid;
+    position: string;
+    child_id: Uuid;
+    created_at: Date;
+}
+/** Input for `query_cell_item_insert`. */
+export interface CellItemInsertQueryInput {
+    parent_id: Uuid;
+    position: string;
+    child_id: Uuid;
+}
+/**
+ * Insert one item row at the caller-supplied `position`.
+ *
+ * Throws on `(parent_id, position)` collision (Postgres `23505`); handler
+ * callers detect via `is_pg_unique_violation` and surface as
+ * `cell_item_position_taken`. Helper-side jitter (`fractional_index`)
+ * makes the collision rate negligible at realistic UX concurrency, so
+ * the throw is the cold-path safety net, not the hot path.
+ *
+ * @mutates `cell_item` - inserts one row
+ */
+export declare const query_cell_item_insert: (deps: QueryDeps, input: CellItemInsertQueryInput) => Promise<CellItemRow>;
+/**
+ * Fetch one item row by `(parent_id, position)`. Used by move + delete
+ * handlers to confirm the row exists before issuing the mutation.
+ *
+ * @returns the row or `null` when not found
+ */
+export declare const query_cell_item_get: (deps: QueryDeps, parent_id: Uuid, position: string) => Promise<CellItemRow | null>;
+/**
+ * Move an item row from `position_old` to `position_new` (same parent).
+ *
+ * Implemented as an UPDATE on the PK; throws `23505` on collision with
+ * an existing row at `position_new` so handlers can surface
+ * `cell_item_position_taken`. The caller-supplied `position_new` is what
+ * fractional-indexing produced for the new slot — collisions are rare
+ * but the error path keeps the client truthful.
+ *
+ * @returns the updated row, or `null` when the source row was missing
+ *   (raced with a deleter)
+ * @mutates `cell_item` - updates one row's `position`
+ */
+export declare const query_cell_item_move: (deps: QueryDeps, parent_id: Uuid, position_old: string, position_new: string) => Promise<CellItemRow | null>;
+/**
+ * Delete one item row by `(parent_id, position)`. Returns the deleted
+ * row so callers can audit `child_id` after the delete without a
+ * pre-fetch.
+ *
+ * @returns the deleted row, or `null` when nothing matched
+ * @mutates `cell_item` - deletes one row
+ */
+export declare const query_cell_item_delete: (deps: QueryDeps, parent_id: Uuid, position: string) => Promise<CellItemRow | null>;
+/**
+ * Forward items list (`parent.items[]`), ordered by lex `position`.
+ *
+ * Filters child by `deleted_at IS NULL` so items pointing at tombstoned
+ * cells don't surface; the parent filter is the caller's responsibility
+ * (gated upstream by `can_view_cell(parent)`).
+ *
+ * @param limit - optional row cap (passes through to SQL `LIMIT`)
+ */
+export declare const query_cell_item_list_for_parent: (deps: QueryDeps, parent_id: Uuid, options?: {
+    limit?: number;
+    position_after?: string;
+}) => Promise<Array<CellItemRow>>;
+/**
+ * Reverse items list (`child.lists[]`).
+ *
+ * Returns rows whose `child_id = $1`, joined to `cell` on `parent_id` so
+ * items from tombstoned parents don't surface. The caller-side authz
+ * filter (per-parent `can_view_cell`) runs after the SQL fetch — see
+ * the 2-layer authz contract on `cell_item_list({child_id})`.
+ *
+ * Bounded by `limit` (the wire `cell_item_list` cap) so a heavily
+ * inbound-linked child can't force an unbounded fetch + per-parent authz
+ * pass on the public, IP-rate-limited reverse endpoint.
+ */
+export declare const query_cell_item_list_for_child: (deps: QueryDeps, child_id: Uuid, options?: {
+    limit?: number;
+}) => Promise<Array<CellItemRow>>;
+//# sourceMappingURL=cell_item_queries.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cell_item_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/cell_item_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAC/C,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,wBAAwB,CAAC;AAGjD,iDAAiD;AACjD,MAAM,WAAW,WAAW;IAC3B,SAAS,EAAE,IAAI,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,IAAI,CAAC;IACf,UAAU,EAAE,IAAI,CAAC;CACjB;AAED,0CAA0C;AAC1C,MAAM,WAAW,wBAAwB;IACxC,SAAS,EAAE,IAAI,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,IAAI,CAAC;CACf;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,SAAS,EACf,OAAO,wBAAwB,KAC7B,OAAO,CAAC,WAAW,CAQrB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,SAAS,EACf,WAAW,IAAI,EACf,UAAU,MAAM,KACd,OAAO,CAAC,WAAW,GAAG,IAAI,CAM5B,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,SAAS,EACf,WAAW,IAAI,EACf,cAAc,MAAM,EACpB,cAAc,MAAM,KAClB,OAAO,CAAC,WAAW,GAAG,IAAI,CAS5B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,SAAS,EACf,WAAW,IAAI,EACf,UAAU,MAAM,KACd,OAAO,CAAC,WAAW,GAAG,IAAI,CAM5B,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,+BAA+B,GAC3C,MAAM,SAAS,EACf,WAAW,IAAI,EACf,UAAU;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAC,KACjD,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAa5B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,8BAA8B,GAC1C,MAAM,SAAS,EACf,UAAU,IAAI,EACd,UAAU;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAC,KACxB,OAAO,CAAC,KAAK,CAAC,WAAW,CAAC,CAS3B,CAAC"}

package/dist/db/cell_item_queries.js

@@ -0,0 +1,119 @@
+/**
+ * Raw queries against the `cell_item` table.
+ *
+ * Ordered-child membership: each row is `(parent_id, position) → child_id`.
+ * `position` is opaque text (fractional-indexing key) — lex ordering is
+ * the contract. The PK on `(parent_id, position)` enforces one cell per
+ * slot but allows the same `child_id` to appear at multiple positions
+ * (the primitive is JSON-array-shaped — ordered multiset, not set;
+ * domain dedup rules ride on top).
+ *
+ * Reads filter both endpoints by `cell.deleted_at IS NULL` so items
+ * dangling off a soft-deleted cell don't surface.
+ *
+ * `query_cell_item_insert` returns the inserted row OR throws the
+ * underlying `23505` (Postgres unique violation) on a `(parent_id,
+ * position)` collision. Handlers convert this into the
+ * `cell_item_position_taken` JSON-RPC error so the client retries with a
+ * refreshed bracket.
+ *
+ * @module
+ */
+import { assert_row } from './assert_row.js';
+/**
+ * Insert one item row at the caller-supplied `position`.
+ *
+ * Throws on `(parent_id, position)` collision (Postgres `23505`); handler
+ * callers detect via `is_pg_unique_violation` and surface as
+ * `cell_item_position_taken`. Helper-side jitter (`fractional_index`)
+ * makes the collision rate negligible at realistic UX concurrency, so
+ * the throw is the cold-path safety net, not the hot path.
+ *
+ * @mutates `cell_item` - inserts one row
+ */
+export const query_cell_item_insert = async (deps, input) => {
+    const row = await deps.db.query_one(`INSERT INTO cell_item (parent_id, position, child_id)
+		 VALUES ($1, $2, $3)
+		 RETURNING *`, [input.parent_id, input.position, input.child_id]);
+    return assert_row(row, 'INSERT INTO cell_item');
+};
+/**
+ * Fetch one item row by `(parent_id, position)`. Used by move + delete
+ * handlers to confirm the row exists before issuing the mutation.
+ *
+ * @returns the row or `null` when not found
+ */
+export const query_cell_item_get = async (deps, parent_id, position) => {
+    const row = await deps.db.query_one(`SELECT * FROM cell_item WHERE parent_id = $1 AND position = $2`, [parent_id, position]);
+    return row ?? null;
+};
+/**
+ * Move an item row from `position_old` to `position_new` (same parent).
+ *
+ * Implemented as an UPDATE on the PK; throws `23505` on collision with
+ * an existing row at `position_new` so handlers can surface
+ * `cell_item_position_taken`. The caller-supplied `position_new` is what
+ * fractional-indexing produced for the new slot — collisions are rare
+ * but the error path keeps the client truthful.
+ *
+ * @returns the updated row, or `null` when the source row was missing
+ *   (raced with a deleter)
+ * @mutates `cell_item` - updates one row's `position`
+ */
+export const query_cell_item_move = async (deps, parent_id, position_old, position_new) => {
+    const row = await deps.db.query_one(`UPDATE cell_item
+		 SET position = $3
+		 WHERE parent_id = $1 AND position = $2
+		 RETURNING *`, [parent_id, position_old, position_new]);
+    return row ?? null;
+};
+/**
+ * Delete one item row by `(parent_id, position)`. Returns the deleted
+ * row so callers can audit `child_id` after the delete without a
+ * pre-fetch.
+ *
+ * @returns the deleted row, or `null` when nothing matched
+ * @mutates `cell_item` - deletes one row
+ */
+export const query_cell_item_delete = async (deps, parent_id, position) => {
+    const row = await deps.db.query_one(`DELETE FROM cell_item WHERE parent_id = $1 AND position = $2 RETURNING *`, [parent_id, position]);
+    return row ?? null;
+};
+/**
+ * Forward items list (`parent.items[]`), ordered by lex `position`.
+ *
+ * Filters child by `deleted_at IS NULL` so items pointing at tombstoned
+ * cells don't surface; the parent filter is the caller's responsibility
+ * (gated upstream by `can_view_cell(parent)`).
+ *
+ * @param limit - optional row cap (passes through to SQL `LIMIT`)
+ */
+export const query_cell_item_list_for_parent = async (deps, parent_id, options) => {
+    const limit = options?.limit ?? null;
+    const position_after = options?.position_after ?? null;
+    return deps.db.query(`SELECT i.* FROM cell_item i
+		 JOIN cell c ON c.id = i.child_id
+		 WHERE i.parent_id = $1
+		   AND c.deleted_at IS NULL
+		   AND ($3::text IS NULL OR i.position > $3)
+		 ORDER BY i.position ASC
+		 LIMIT $2`, [parent_id, limit, position_after]);
+};
+/**
+ * Reverse items list (`child.lists[]`).
+ *
+ * Returns rows whose `child_id = $1`, joined to `cell` on `parent_id` so
+ * items from tombstoned parents don't surface. The caller-side authz
+ * filter (per-parent `can_view_cell`) runs after the SQL fetch — see
+ * the 2-layer authz contract on `cell_item_list({child_id})`.
+ *
+ * Bounded by `limit` (the wire `cell_item_list` cap) so a heavily
+ * inbound-linked child can't force an unbounded fetch + per-parent authz
+ * pass on the public, IP-rate-limited reverse endpoint.
+ */
+export const query_cell_item_list_for_child = async (deps, child_id, options) => deps.db.query(`SELECT i.* FROM cell_item i
+		 JOIN cell p ON p.id = i.parent_id
+		 WHERE i.child_id = $1
+		   AND p.deleted_at IS NULL
+		 ORDER BY i.created_at ASC
+		 LIMIT $2`, [child_id, options?.limit ?? null]);