@fuzdev/fuz_app 0.67.0 → 0.68.0

package/dist/db/cell_ddl.js

@@ -0,0 +1,247 @@
+/**
+ * Cell PG schema.
+ *
+ * The universal content primitive: a single `cell` table whose `data` JSONB
+ * is interpreted by view shape. Parent→child membership and named
+ * relationships live in two sibling tables — `cell_item` (ordered
+ * children, fractional-indexing keyed) and `cell_field` (named edges).
+ * `refs text[]` carries `blake3:` fact hashes auto-extracted from `data`
+ * by application code on every write.
+ *
+ * Soft delete via `deleted_at`. Most indexes are partial on
+ * `deleted_at IS NULL` so active-cell queries skip tombstones.
+ *
+ * `path` is the global namespace axis — a partial unique index enforces
+ * uniqueness across all active rows (PostgreSQL UNIQUE constraints don't
+ * support WHERE clauses, so it's expressed as a partial unique index). It
+ * additionally filters on `deleted_at IS NULL` so a soft-deleted cell
+ * doesn't block reuse of its path. Path writes are admin-only at the
+ * action layer; user-namespaced paths are a future extension.
+ *
+ * **Ownership columns** (`created_by`, `updated_by`) are nullable FKs to
+ * `actor`: NULL = system origin (well-known cells, daemon/agent cells).
+ * The non-admin authz path treats NULL `created_by` as admin-only via an
+ * explicit equality check (`auth/cell_authorize.ts`).
+ *
+ * **Timestamp naming** (`created_at`, `updated_at`) aligns with fuz_app's
+ * `_at`-everywhere convention used by `account`, `actor`, `audit_log`,
+ * `role_grant`, etc.
+ *
+ * **Single-migration shape**: `cell_v0` creates the canonical
+ * cell + cell_grant + cell_field + cell_item layout in one shot from the
+ * live exported constants.
+ *
+ * @module
+ */
+/**
+ * `cell_visibility` enum — access-control axis for a cell. Lives as a
+ * top-level column (not inside `data`) because visibility is access
+ * control, not content metadata. `cell_grant` is the other ACL surface;
+ * keeping visibility as a peer column (not a JSON field) co-locates
+ * access-control state and lets the planner reason about it directly.
+ *
+ * Ships with two states (`'private'`, `'public'`); a third (unlisted /
+ * public-link) folds in via `ALTER TYPE` when public-link sharing lands.
+ *
+ * Wrapped in a `DO` block so the migration can replay idempotently —
+ * `CREATE TYPE` has no `IF NOT EXISTS` variant in PostgreSQL.
+ */
+export const CELL_VISIBILITY_TYPE = `
+DO $$ BEGIN
+	CREATE TYPE cell_visibility AS ENUM ('private', 'public');
+EXCEPTION WHEN duplicate_object THEN NULL;
+END $$`;
+/**
+ * `cell` table — universal content primitive: identity + content only.
+ * Parent→child membership lives in `cell_item`; named relations live in
+ * `cell_field`. Includes the `created_by` / `updated_by` ownership columns.
+ *
+ * `visibility` is the access-control axis — `private` (default) is
+ * restricted to admin / owner / `cell_grant`-admitted callers; `public`
+ * admits everyone, including unauthenticated visitors. Lives as a
+ * top-level column so the auth predicate reads off the row directly
+ * rather than reaching into `data`.
+ *
+ * `path` is the global namespace axis (no tenant/hub scoping) — globally
+ * unique on active rows via `idx_cell_path_unique`.
+ */
+export const CELL_SCHEMA = `
+CREATE TABLE IF NOT EXISTS cell (
+	id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+	data JSONB NOT NULL,
+	visibility cell_visibility NOT NULL DEFAULT 'private',
+	path TEXT,
+	refs TEXT[],
+	created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+	updated_at TIMESTAMPTZ,
+	deleted_at TIMESTAMPTZ,
+	created_by UUID REFERENCES actor(id) ON DELETE SET NULL,
+	updated_by UUID REFERENCES actor(id) ON DELETE SET NULL
+)`;
+/**
+ * Cell indexes — all active-only, partial on `deleted_at IS NULL`.
+ *
+ * - `idx_cell_active`: active-cell list/scan ordered by creation.
+ * - `idx_cell_path_unique`: global `path` uniqueness + read-side path
+ *   lookup. Partial on path + active so reused paths after soft delete are
+ *   allowed.
+ * - `idx_cell_data`: shape-driven queries (`data ? 'kind'`, `data @> ...`).
+ * - `idx_cell_refs`: cells-by-fact discovery (cross-cell reference graph).
+ * - `idx_cell_created_by`: "cells this actor created" queries.
+ *
+ * Parent↔child membership and named relations live in sibling tables;
+ * see `CELL_ITEM_INDEXES` / `CELL_FIELD_INDEXES` below.
+ */
+export const CELL_INDEXES = [
+    `CREATE INDEX IF NOT EXISTS idx_cell_active ON cell(created_at)
+		WHERE deleted_at IS NULL`,
+    `CREATE UNIQUE INDEX IF NOT EXISTS idx_cell_path_unique
+		ON cell(path)
+		WHERE path IS NOT NULL AND deleted_at IS NULL`,
+    `CREATE INDEX IF NOT EXISTS idx_cell_data ON cell USING gin(data)
+		WHERE deleted_at IS NULL`,
+    `CREATE INDEX IF NOT EXISTS idx_cell_refs ON cell USING gin(refs)
+		WHERE refs IS NOT NULL AND deleted_at IS NULL`,
+    `CREATE INDEX IF NOT EXISTS idx_cell_created_by ON cell(created_by)
+		WHERE deleted_at IS NULL`,
+];
+/**
+ * `cell_grant` table — resource-side ACL for cells. Each row admits a
+ * principal (actor or `(role, scope_id)`) at a `level` (`viewer` or
+ * `editor`). Owner is implicit (`cell.created_by`); the table never carries
+ * owner rows.
+ *
+ * The single-principal arm is actor-grain (`actor_id` FK); the other arm is
+ * role-shaped (`(role, scope_id)`). The CHECK enforces exactly one arm.
+ */
+export const CELL_GRANT_SCHEMA = `
+CREATE TABLE IF NOT EXISTS cell_grant (
+	id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+	cell_id UUID NOT NULL REFERENCES cell(id) ON DELETE CASCADE,
+	level TEXT NOT NULL CHECK (level IN ('viewer', 'editor')),
+	actor_id UUID REFERENCES actor(id) ON DELETE CASCADE,
+	role TEXT,
+	scope_id UUID,
+	granted_by UUID REFERENCES actor(id) ON DELETE SET NULL,
+	created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+	CHECK (
+		(actor_id IS NOT NULL AND role IS NULL AND scope_id IS NULL) OR
+		(actor_id IS NULL AND role IS NOT NULL)
+	)
+)`;
+/**
+ * `cell_grant` indexes.
+ *
+ * - `idx_cell_grant_cell`: forward lookup ("who has access to this cell?").
+ * - `idx_cell_grant_actor`: reverse lookup ("which cells does this actor have access to?").
+ * - `idx_cell_grant_role_scope`: reverse lookup for role-shaped principals.
+ * - `idx_cell_grant_unique_actor`: prevents duplicate actor-shaped grants for the same cell.
+ *   Re-granting updates `level` via UPSERT on this index.
+ * - `idx_cell_grant_unique_role_scope`: same, for role-shaped grants.
+ *   `NULLS NOT DISTINCT` so two rows with the same `(cell_id, role)` and
+ *   `scope_id IS NULL` collide — without it, default NULL-distinct
+ *   semantics would let duplicate null-scope role grants slip past the
+ *   re-share UPSERT path. Requires PostgreSQL 15+ (pglite tracks PG 16).
+ */
+export const CELL_GRANT_INDEXES = [
+    `CREATE INDEX IF NOT EXISTS idx_cell_grant_cell ON cell_grant(cell_id)`,
+    `CREATE INDEX IF NOT EXISTS idx_cell_grant_actor
+		ON cell_grant(actor_id) WHERE actor_id IS NOT NULL`,
+    `CREATE INDEX IF NOT EXISTS idx_cell_grant_role_scope
+		ON cell_grant(role, scope_id) WHERE role IS NOT NULL`,
+    `CREATE UNIQUE INDEX IF NOT EXISTS idx_cell_grant_unique_actor
+		ON cell_grant(cell_id, actor_id) WHERE actor_id IS NOT NULL`,
+    `CREATE UNIQUE INDEX IF NOT EXISTS idx_cell_grant_unique_role_scope
+		ON cell_grant(cell_id, role, scope_id) NULLS NOT DISTINCT
+		WHERE role IS NOT NULL`,
+];
+/**
+ * `cell_field` table — named relation (`(source_id, name) → target_id`).
+ * One target per name per source — JSON-object keys are unique. Multiplicity
+ * is expressed by composition (`foo.tags = collection_cell` whose `items[]`
+ * are the tags), not by allowing duplicate `(source_id, name)` rows.
+ */
+export const CELL_FIELD_SCHEMA = `
+CREATE TABLE IF NOT EXISTS cell_field (
+	source_id UUID NOT NULL REFERENCES cell(id) ON DELETE CASCADE,
+	name TEXT NOT NULL,
+	target_id UUID NOT NULL REFERENCES cell(id) ON DELETE CASCADE,
+	created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+	PRIMARY KEY (source_id, name)
+)`;
+/**
+ * `cell_field` indexes.
+ *
+ * - PK on `(source_id, name)` covers forward lookup ("what does this cell
+ *   point to via field X?") and the per-source fields list.
+ * - `idx_cell_field_target` covers reverse lookup ("which cells link to
+ *   this target?").
+ *
+ * Soft-delete is filtered by JOIN at the read boundary; no partial indexes
+ * here on `deleted_at` (would force index churn on cell soft-delete
+ * toggles, and the join filter is sufficient).
+ */
+export const CELL_FIELD_INDEXES = [
+    `CREATE INDEX IF NOT EXISTS idx_cell_field_target ON cell_field(target_id)`,
+];
+/**
+ * `cell_item` table — ordered child membership keyed by an opaque
+ * fractional-indexing string. `(parent_id, position)` PK enforces one cell
+ * per slot; the same `child_id` may appear at multiple positions (the
+ * primitive is JSON-array-shaped — ordered multiset, not set). Domain
+ * dedup rules ride on top in helpers.
+ */
+export const CELL_ITEM_SCHEMA = `
+CREATE TABLE IF NOT EXISTS cell_item (
+	parent_id UUID NOT NULL REFERENCES cell(id) ON DELETE CASCADE,
+	position TEXT NOT NULL,
+	child_id UUID NOT NULL REFERENCES cell(id) ON DELETE CASCADE,
+	created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+	PRIMARY KEY (parent_id, position)
+)`;
+/**
+ * `cell_item` indexes.
+ *
+ * - PK on `(parent_id, position)` covers ordered scans for the per-parent
+ *   items list (`SELECT ... ORDER BY position`).
+ * - `idx_cell_item_child` covers reverse lookup ("which parents contain
+ *   this child?").
+ */
+export const CELL_ITEM_INDEXES = [
+    `CREATE INDEX IF NOT EXISTS idx_cell_item_parent_position ON cell_item(parent_id, position)`,
+    `CREATE INDEX IF NOT EXISTS idx_cell_item_child ON cell_item(child_id)`,
+];
+/** Tables created by `CELL_MIGRATION_NS`, in drop order (children first). */
+export const CELL_DROP_TABLES = ['cell_field', 'cell_item', 'cell_grant', 'cell'];
+/** Cell migrations. */
+export const CELL_MIGRATIONS = [
+    {
+        name: 'cell_v0',
+        up: async (db) => {
+            await db.query(CELL_VISIBILITY_TYPE);
+            await db.query(CELL_SCHEMA);
+            for (const sql of CELL_INDEXES) {
+                await db.query(sql);
+            }
+            await db.query(CELL_GRANT_SCHEMA);
+            for (const sql of CELL_GRANT_INDEXES) {
+                await db.query(sql);
+            }
+            await db.query(CELL_FIELD_SCHEMA);
+            for (const sql of CELL_FIELD_INDEXES) {
+                await db.query(sql);
+            }
+            await db.query(CELL_ITEM_SCHEMA);
+            for (const sql of CELL_ITEM_INDEXES) {
+                await db.query(sql);
+            }
+        },
+    },
+];
+/** Namespace identifier for cell migrations. */
+export const CELL_MIGRATION_NAMESPACE = 'fuz_cell';
+/** Migration namespace consumed by `run_migrations`. */
+export const CELL_MIGRATION_NS = {
+    namespace: CELL_MIGRATION_NAMESPACE,
+    migrations: CELL_MIGRATIONS,
+};

package/dist/db/cell_field_queries.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Raw queries against the `cell_field` table.
+ *
+ * Named-relation primitive: each row is `(source_id, name) → target_id`,
+ * a JSON-object-shaped edge from one cell to another. `(source_id, name)`
+ * is unique — one target per name per source. Multiplicity by composition
+ * (target a collection cell whose `items[]` are the multi-valued tags),
+ * not by allowing duplicate field rows.
+ *
+ * Reads filter both endpoints by `cell.deleted_at IS NULL` so relations
+ * dangling off a soft-deleted cell don't surface to the live graph.
+ *
+ * `query_cell_field_set` upserts on the `(source_id, name)` PK so
+ * re-pointing a name updates `target_id` in place — JSON-object semantics
+ * (`obj.foo = bar` overwrites whatever was there).
+ *
+ * @module
+ */
+import type { QueryDeps } from './query_deps.js';
+import type { Uuid } from '@fuzdev/fuz_util/id.js';
+/** Row shape returned by `cell_field` SELECTs. */
+export interface CellFieldRow {
+    source_id: Uuid;
+    name: string;
+    target_id: Uuid;
+    created_at: Date;
+}
+/** Input for `query_cell_field_set`. */
+export interface CellFieldSetQueryInput {
+    source_id: Uuid;
+    name: string;
+    target_id: Uuid;
+}
+/**
+ * Insert or update a field row.
+ *
+ * UPSERT on `(source_id, name)` — re-setting the same name updates
+ * `target_id` and bumps `created_at` (timestamp reflects last write).
+ * Idempotent at the row level: caller can re-issue with the same input
+ * without checking existence first.
+ *
+ * @param deps - query deps
+ * @param input - source, name, target
+ * @returns the inserted-or-updated row
+ * @mutates `cell_field` - inserts or updates one row
+ */
+export declare const query_cell_field_set: (deps: QueryDeps, input: CellFieldSetQueryInput) => Promise<CellFieldRow>;
+/**
+ * Fetch one field row by primary key.
+ *
+ * Does NOT JOIN cell — the caller decides whether to filter by
+ * `deleted_at`. Used by handlers that need the row's current target_id
+ * for audit envelopes before issuing the delete.
+ *
+ * @param deps - query deps
+ * @param source_id - source cell id
+ * @param name - field name
+ * @returns the row or `null` when not found
+ */
+export declare const query_cell_field_get: (deps: QueryDeps, source_id: Uuid, name: string) => Promise<CellFieldRow | null>;
+/**
+ * Delete a field row by primary key. Returns the deleted row so callers
+ * can audit the prior target_id without a pre-fetch.
+ *
+ * @returns the deleted row, or `null` when no row matched (idempotent
+ *   delete: a 200 response is correct even when nothing was deleted)
+ * @mutates `cell_field` - deletes one row
+ */
+export declare const query_cell_field_delete: (deps: QueryDeps, source_id: Uuid, name: string) => Promise<CellFieldRow | null>;
+/**
+ * Forward fields list (`source.fields[]`).
+ *
+ * Filters target by `deleted_at IS NULL` so relations to tombstoned cells
+ * don't surface; the source filter is the caller's responsibility (gated
+ * upstream by `can_view_cell(source)`).
+ *
+ * @param deps - query deps
+ * @param source_id - source cell id
+ * @returns matching rows, oldest first by name (lex order)
+ */
+export declare const query_cell_field_list_for_source: (deps: QueryDeps, source_id: Uuid, options?: {
+    limit?: number;
+    name_after?: string;
+}) => Promise<Array<CellFieldRow>>;
+/**
+ * Reverse fields list (`target.upfields[]`).
+ *
+ * Returns rows whose `target_id = $1`, joined to `cell` on `source_id` so
+ * relations from tombstoned sources don't surface. The caller-side
+ * authz filter (per-source `can_view_cell`) runs after the SQL fetch
+ * — see the 2-layer authz contract on `cell_field_list({target_id})`.
+ *
+ * Bounded by `limit` (the wire `cell_field_list` cap) so a heavily
+ * inbound-linked target can't force an unbounded fetch + per-source authz
+ * pass on the public, IP-rate-limited reverse endpoint.
+ *
+ * @param deps - query deps
+ * @param target_id - target cell id
+ * @param options - `limit` caps the row count
+ * @returns matching rows, oldest first by source created_at
+ */
+export declare const query_cell_field_list_for_target: (deps: QueryDeps, target_id: Uuid, options?: {
+    limit?: number;
+}) => Promise<Array<CellFieldRow>>;
+//# sourceMappingURL=cell_field_queries.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cell_field_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/cell_field_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAC/C,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,wBAAwB,CAAC;AAGjD,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC5B,SAAS,EAAE,IAAI,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,IAAI,CAAC;IAChB,UAAU,EAAE,IAAI,CAAC;CACjB;AAED,wCAAwC;AACxC,MAAM,WAAW,sBAAsB;IACtC,SAAS,EAAE,IAAI,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,IAAI,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,SAAS,EACf,OAAO,sBAAsB,KAC3B,OAAO,CAAC,YAAY,CAUtB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,SAAS,EACf,WAAW,IAAI,EACf,MAAM,MAAM,KACV,OAAO,CAAC,YAAY,GAAG,IAAI,CAM7B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,SAAS,EACf,WAAW,IAAI,EACf,MAAM,MAAM,KACV,OAAO,CAAC,YAAY,GAAG,IAAI,CAM7B,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,SAAS,EACf,WAAW,IAAI,EACf,UAAU;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAC,KAC7C,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAa7B,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,SAAS,EACf,WAAW,IAAI,EACf,UAAU;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAC,KACxB,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAS5B,CAAC"}

package/dist/db/cell_field_queries.js

@@ -0,0 +1,113 @@
+/**
+ * Raw queries against the `cell_field` table.
+ *
+ * Named-relation primitive: each row is `(source_id, name) → target_id`,
+ * a JSON-object-shaped edge from one cell to another. `(source_id, name)`
+ * is unique — one target per name per source. Multiplicity by composition
+ * (target a collection cell whose `items[]` are the multi-valued tags),
+ * not by allowing duplicate field rows.
+ *
+ * Reads filter both endpoints by `cell.deleted_at IS NULL` so relations
+ * dangling off a soft-deleted cell don't surface to the live graph.
+ *
+ * `query_cell_field_set` upserts on the `(source_id, name)` PK so
+ * re-pointing a name updates `target_id` in place — JSON-object semantics
+ * (`obj.foo = bar` overwrites whatever was there).
+ *
+ * @module
+ */
+import { assert_row } from './assert_row.js';
+/**
+ * Insert or update a field row.
+ *
+ * UPSERT on `(source_id, name)` — re-setting the same name updates
+ * `target_id` and bumps `created_at` (timestamp reflects last write).
+ * Idempotent at the row level: caller can re-issue with the same input
+ * without checking existence first.
+ *
+ * @param deps - query deps
+ * @param input - source, name, target
+ * @returns the inserted-or-updated row
+ * @mutates `cell_field` - inserts or updates one row
+ */
+export const query_cell_field_set = async (deps, input) => {
+    const row = await deps.db.query_one(`INSERT INTO cell_field (source_id, name, target_id)
+		 VALUES ($1, $2, $3)
+		 ON CONFLICT (source_id, name)
+		 DO UPDATE SET target_id = EXCLUDED.target_id, created_at = NOW()
+		 RETURNING *`, [input.source_id, input.name, input.target_id]);
+    return assert_row(row, 'INSERT INTO cell_field');
+};
+/**
+ * Fetch one field row by primary key.
+ *
+ * Does NOT JOIN cell — the caller decides whether to filter by
+ * `deleted_at`. Used by handlers that need the row's current target_id
+ * for audit envelopes before issuing the delete.
+ *
+ * @param deps - query deps
+ * @param source_id - source cell id
+ * @param name - field name
+ * @returns the row or `null` when not found
+ */
+export const query_cell_field_get = async (deps, source_id, name) => {
+    const row = await deps.db.query_one(`SELECT * FROM cell_field WHERE source_id = $1 AND name = $2`, [source_id, name]);
+    return row ?? null;
+};
+/**
+ * Delete a field row by primary key. Returns the deleted row so callers
+ * can audit the prior target_id without a pre-fetch.
+ *
+ * @returns the deleted row, or `null` when no row matched (idempotent
+ *   delete: a 200 response is correct even when nothing was deleted)
+ * @mutates `cell_field` - deletes one row
+ */
+export const query_cell_field_delete = async (deps, source_id, name) => {
+    const row = await deps.db.query_one(`DELETE FROM cell_field WHERE source_id = $1 AND name = $2 RETURNING *`, [source_id, name]);
+    return row ?? null;
+};
+/**
+ * Forward fields list (`source.fields[]`).
+ *
+ * Filters target by `deleted_at IS NULL` so relations to tombstoned cells
+ * don't surface; the source filter is the caller's responsibility (gated
+ * upstream by `can_view_cell(source)`).
+ *
+ * @param deps - query deps
+ * @param source_id - source cell id
+ * @returns matching rows, oldest first by name (lex order)
+ */
+export const query_cell_field_list_for_source = async (deps, source_id, options) => {
+    const limit = options?.limit ?? null;
+    const name_after = options?.name_after ?? null;
+    return deps.db.query(`SELECT f.* FROM cell_field f
+		 JOIN cell t ON t.id = f.target_id
+		 WHERE f.source_id = $1
+		   AND t.deleted_at IS NULL
+		   AND ($3::text IS NULL OR f.name > $3)
+		 ORDER BY f.name ASC
+		 LIMIT $2`, [source_id, limit, name_after]);
+};
+/**
+ * Reverse fields list (`target.upfields[]`).
+ *
+ * Returns rows whose `target_id = $1`, joined to `cell` on `source_id` so
+ * relations from tombstoned sources don't surface. The caller-side
+ * authz filter (per-source `can_view_cell`) runs after the SQL fetch
+ * — see the 2-layer authz contract on `cell_field_list({target_id})`.
+ *
+ * Bounded by `limit` (the wire `cell_field_list` cap) so a heavily
+ * inbound-linked target can't force an unbounded fetch + per-source authz
+ * pass on the public, IP-rate-limited reverse endpoint.
+ *
+ * @param deps - query deps
+ * @param target_id - target cell id
+ * @param options - `limit` caps the row count
+ * @returns matching rows, oldest first by source created_at
+ */
+export const query_cell_field_list_for_target = async (deps, target_id, options) => deps.db.query(`SELECT f.* FROM cell_field f
+		 JOIN cell s ON s.id = f.source_id
+		 WHERE f.target_id = $1
+		   AND s.deleted_at IS NULL
+		 ORDER BY f.created_at ASC
+		 LIMIT $2`, [target_id, options?.limit ?? null]);

package/dist/db/cell_grant_queries.d.ts

@@ -0,0 +1,132 @@
+/**
+ * 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 type { QueryDeps } from './query_deps.js';
+import type { Uuid } from '@fuzdev/fuz_util/id.js';
+import type { CellGrantLevel } from '../auth/cell_grant_action_specs.js';
+/** Row shape returned by `cell_grant` SELECTs. */
+export interface CellGrantRow {
+    id: Uuid;
+    cell_id: Uuid;
+    level: CellGrantLevel;
+    actor_id: Uuid | null;
+    role: string | null;
+    scope_id: Uuid | null;
+    granted_by: Uuid | null;
+    created_at: Date;
+}
+/**
+ * Discriminated principal input for `query_cell_grant_create`. Wire
+ * and query shapes are aligned — actor-shaped principals carry a
+ * pre-resolved `actor_id`; pickers run `actor_search` to convert a
+ * typed name to an id upstream of the handler.
+ */
+export type CellGrantPrincipalQueryInput = {
+    kind: 'actor';
+    actor_id: Uuid;
+} | {
+    kind: 'role';
+    role: string;
+    scope_id: Uuid | null;
+};
+/** Input for `query_cell_grant_create`. */
+export interface CellGrantCreateQueryInput {
+    cell_id: Uuid;
+    level: CellGrantLevel;
+    principal: CellGrantPrincipalQueryInput;
+    granted_by: Uuid | null;
+}
+/**
+ * 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 declare const query_cell_grant_create: (deps: QueryDeps, input: CellGrantCreateQueryInput) => Promise<CellGrantRow>;
+/**
+ * Fetch a grant by id.
+ *
+ * @param deps - query deps
+ * @param grant_id - grant id
+ * @returns the row or `null` when not found
+ */
+export declare const query_cell_grant_get: (deps: QueryDeps, grant_id: Uuid) => Promise<CellGrantRow | 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 declare const query_cell_grant_delete: (deps: QueryDeps, grant_id: Uuid) => Promise<CellGrantRow | 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 declare const query_cell_grant_list_for_cell: (deps: QueryDeps, cell_id: Uuid) => Promise<Array<CellGrantRow>>;
+/**
+ * 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 declare const query_cell_grant_list_for_cells: (deps: QueryDeps, cell_ids: ReadonlyArray<Uuid>) => Promise<Array<CellGrantRow>>;
+/**
+ * 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 declare const query_cell_grants_for_caller_in_cells: (deps: QueryDeps, cell_ids: Array<Uuid>, caller_actor_id: Uuid | null, role_grant_roles: Array<string>, role_grant_scope_ids: Array<Uuid | null>) => Promise<Array<CellGrantRow>>;
+//# sourceMappingURL=cell_grant_queries.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cell_grant_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/cell_grant_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAC/C,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,wBAAwB,CAAC;AACjD,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,oCAAoC,CAAC;AAGvE,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC5B,EAAE,EAAE,IAAI,CAAC;IACT,OAAO,EAAE,IAAI,CAAC;IACd,KAAK,EAAE,cAAc,CAAC;IACtB,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;IACtB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,IAAI,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,MAAM,4BAA4B,GACrC;IAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAA;CAAC,GAC/B;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAA;CAAC,CAAC;AAEvD,2CAA2C;AAC3C,MAAM,WAAW,yBAAyB;IACzC,OAAO,EAAE,IAAI,CAAC;IACd,KAAK,EAAE,cAAc,CAAC;IACtB,SAAS,EAAE,4BAA4B,CAAC;IACxC,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;CACxB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,SAAS,EACf,OAAO,yBAAyB,KAC9B,OAAO,CAAC,YAAY,CAsBtB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,SAAS,EACf,UAAU,IAAI,KACZ,OAAO,CAAC,YAAY,GAAG,IAAI,CAK7B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,GACnC,MAAM,SAAS,EACf,UAAU,IAAI,KACZ,OAAO,CAAC,YAAY,GAAG,IAAI,CAM7B,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,8BAA8B,GAC1C,MAAM,SAAS,EACf,SAAS,IAAI,KACX,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAM5B,CAAC;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,+BAA+B,GAC3C,MAAM,SAAS,EACf,UAAU,aAAa,CAAC,IAAI,CAAC,KAC3B,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAQ7B,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,qCAAqC,GACjD,MAAM,SAAS,EACf,UAAU,KAAK,CAAC,IAAI,CAAC,EACrB,iBAAiB,IAAI,GAAG,IAAI,EAC5B,kBAAkB,KAAK,CAAC,MAAM,CAAC,EAC/B,sBAAsB,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,KACtC,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAmB7B,CAAC"}