@fuzdev/fuz_app 0.67.1 → 0.68.0

package/dist/db/cell_queries.d.ts

@@ -0,0 +1,327 @@
+/**
+ * Raw queries against the `cell` table.
+ *
+ * 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.
+ *
+ * Soft delete via `deleted_at`. All `get` / `list` queries exclude
+ * tombstones by default; `include_deleted: true` opts in for admin /
+ * audit views.
+ *
+ * `path` uniqueness is global, enforced by `idx_cell_path_unique` (partial
+ * on active rows). Path reuse after soft delete falls out of the partial
+ * index — queries do not need special handling.
+ *
+ * @module
+ */
+import type { QueryDeps } from './query_deps.js';
+import type { Json } from '@fuzdev/fuz_util/json.js';
+import type { Uuid } from '@fuzdev/fuz_util/id.js';
+import { type FactHash } from '@fuzdev/fuz_util/fact_hash.js';
+import type { CellData } from '../auth/cell_data_schema.js';
+import type { CellVisibility } from '../auth/cell_action_specs.js';
+/**
+ * Row shape returned by `cell` SELECTs. `data` is typed as `CellData` —
+ * the storage layer trusts the wire validation; the row is what was
+ * written, and the wire validates `CellData` on every write.
+ *
+ * Parent↔child membership and named relations live in the `cell_item` /
+ * `cell_field` sibling tables (see `cell_item_queries.ts` /
+ * `cell_field_queries.ts`). The cell row carries identity + content only.
+ *
+ * `grant_count` is a derived projection (correlated subquery against
+ * `cell_grant` keyed by `cell_id`, served by `idx_cell_grant_cell`) —
+ * not a table column. New cells naturally land at 0.
+ */
+export interface CellRow {
+    id: Uuid;
+    data: CellData;
+    visibility: CellVisibility;
+    path: string | null;
+    refs: Array<FactHash> | null;
+    created_at: Date;
+    updated_at: Date | null;
+    deleted_at: Date | null;
+    created_by: Uuid | null;
+    updated_by: Uuid | null;
+    grant_count: number;
+}
+/** Input for `query_cell_create`. `refs` is derived from `data`. */
+export interface CellCreateQueryInput {
+    data: Json;
+    visibility?: CellVisibility;
+    path?: string | null;
+    created_by?: Uuid | null;
+}
+/**
+ * Patch for `query_cell_update`. Fields left `undefined` are unchanged;
+ * `path` may be explicitly set to `null` to clear. `refs` is re-derived
+ * from `data` whenever `data` is updated.
+ */
+export interface CellUpdatePatch {
+    data?: Json;
+    visibility?: CellVisibility;
+    path?: string | null;
+    updated_by?: Uuid | null;
+}
+/** Common pagination + tombstone-visibility options for list queries. */
+export interface CellListOptions {
+    limit?: number;
+    offset?: number;
+    include_deleted?: boolean;
+}
+/**
+ * Insert a cell row, deriving `refs` from `data`.
+ *
+ * `updated_by` is left NULL on insert — same convention as `updated_at`
+ * (NULL until first update). The "last modifier" stamp is meaningful only
+ * after a real edit; copying the creator's id into `updated_by` at create
+ * time would make a no-op update by a different actor look authored by
+ * the creator.
+ *
+ * @param deps - query deps
+ * @param input - data, optional visibility, path, and ownership
+ * @returns the inserted row
+ * @mutates `cell` - inserts one row
+ */
+export declare const query_cell_create: (deps: QueryDeps, input: CellCreateQueryInput) => Promise<CellRow>;
+/**
+ * Fetch a cell by id. Excludes soft-deleted rows by default.
+ *
+ * @param deps - query deps
+ * @param id - cell id
+ * @param options - `include_deleted: true` returns tombstones
+ * @returns the row or `null` when not found (or soft-deleted and not requested)
+ */
+export declare const query_cell_get: (deps: QueryDeps, id: Uuid, options?: {
+    include_deleted?: boolean;
+}) => Promise<CellRow | null>;
+/**
+ * Fetch a cell by `path`. Excludes soft-deleted rows; the global partial
+ * unique index on `path WHERE deleted_at IS NULL` guarantees at most one
+ * result.
+ *
+ * @param deps - query deps
+ * @param path - the named lookup alias (e.g. `/map/main`)
+ * @returns the row or `null` when not found
+ */
+export declare const query_cell_get_by_path: (deps: QueryDeps, path: string) => Promise<CellRow | null>;
+/**
+ * Bulk-load active cell rows by id, **no visibility filter applied**. Used
+ * by the strict relation-read filter (`auth/cell_relation_visibility.ts`'s
+ * `filter_visible_target_ids`), which runs `can_view_cell` per row in
+ * memory rather than in SQL. Soft-deleted rows are excluded so relations
+ * to tombstones never surface.
+ *
+ * @param deps - query deps
+ * @param ids - cell ids to load (duplicates are harmless)
+ * @returns active rows in arbitrary order (caller indexes by `id`)
+ */
+export declare const query_cell_load_many: (deps: QueryDeps, ids: ReadonlyArray<Uuid>) => Promise<Array<CellRow>>;
+/**
+ * Update a cell. Fields left `undefined` in the patch keep their existing
+ * value; explicit `null` writes `NULL`. `refs` is re-derived from `data`
+ * whenever the patch updates `data`. `updated_at` is bumped to `NOW()`
+ * on every successful update.
+ *
+ * @param deps - query deps
+ * @param id - cell id
+ * @param patch - subset of mutable fields
+ * @returns the updated row, or `null` when no row matched (already deleted
+ *   or never existed)
+ * @mutates `cell` - updates one row
+ */
+export declare const query_cell_update: (deps: QueryDeps, id: Uuid, patch: CellUpdatePatch) => Promise<CellRow | null>;
+/**
+ * Soft-delete a cell. Sets `deleted_at = NOW()`, `updated_at = NOW()`,
+ * and `updated_by = options.deleted_by` (or `NULL`). No-op when the row
+ * is already deleted.
+ *
+ * @param deps - query deps
+ * @param id - cell id
+ * @param options - `deleted_by` records who triggered the delete
+ * @returns `true` when a row was soft-deleted, `false` when no active row matched
+ * @mutates `cell` - sets `deleted_at` on one row
+ */
+export declare const query_cell_delete: (deps: QueryDeps, id: Uuid, options?: {
+    deleted_by?: Uuid | null;
+}) => Promise<boolean>;
+/**
+ * List cells whose `data.kind` matches the given value, newest first.
+ * Uses the `idx_cell_data` GIN index (`data @> ...`).
+ *
+ * @param deps - query deps
+ * @param kind - `data.kind` value to match (e.g. `'collection'`, `'entry'`)
+ * @param options - pagination
+ * @returns matching active rows
+ */
+export declare const query_cell_list_by_data_kind: (deps: QueryDeps, kind: string, options?: Pick<CellListOptions, "limit" | "offset">) => Promise<Array<CellRow>>;
+/**
+ * List active cells created by an actor, newest first. Backed by the
+ * `idx_cell_created_by` partial index.
+ *
+ * @param deps - query deps
+ * @param actor_id - the creator's actor id
+ * @param options - pagination
+ * @returns matching active rows
+ */
+export declare const query_cell_list_by_creator: (deps: QueryDeps, actor_id: Uuid, options?: Pick<CellListOptions, "limit" | "offset">) => Promise<Array<CellRow>>;
+/**
+ * Filterable list query for the generic `cell_list` RPC.
+ *
+ * Takes a flat filter shape (single optional clause per dimension; the
+ * `cell_list` API explicitly does NOT support OR'd alternatives within a
+ * dimension — keep it simple) plus an optional viewer-aware visibility
+ * predicate.
+ *
+ * The visibility predicate mirrors `can_view_cell` in SQL form:
+ *
+ * ```
+ * (viewer_is_admin
+ *  OR cell.visibility = 'public'
+ *  OR (viewer_actor_id IS NOT NULL AND created_by = viewer_actor_id)
+ *  OR (viewer_actor_id IS NOT NULL AND <grant admits caller>))
+ * ```
+ *
+ * The grants branch closes parity with `can_view_cell`: a SQL `EXISTS`
+ * over `cell_grant`, parameterized by the caller's `actor_id` and the
+ * parallel `(role[], scope_id[])` projection of `auth.role_grants`. The
+ * caller's role_grants are materialized once via a `caller_role_grants`
+ * CTE so the role-grant `unnest` isn't re-scanned per outer row. Empty
+ * role_grant arrays are fine: the CTE yields zero rows, the inner EXISTS
+ * returns false, and the actor-grant branch still fires for actor-shaped
+ * grants.
+ *
+ * `shared_with_caller_only: true` (`shared_with: 'me'` at the wire layer)
+ * takes a **different SQL shape**: instead of layering an extra
+ * conjunction on the cell-driven scan, it semi-joins through
+ * `cell_grant`, letting the planner drive from the (typically tiny)
+ * admitted-grant set via `idx_cell_grant_actor` /
+ * `idx_cell_grant_role_scope` rather than scanning every cell row. For a
+ * sharee with N grants over a table of M cells, the cost drops from
+ * O(M) to O(N + matched-cells). Owner-is-implicit (a cell's owner never
+ * appears as a grant principal) means the grants branch is itself
+ * owner-excluding, but the explicit `created_by IS DISTINCT FROM caller`
+ * guards against any future deviation. The shared_with branch does NOT
+ * bypass for admin: an admin asking "what's shared with me" wants their
+ * own grant footprint, not every cell.
+ *
+ * Soft-deleted rows are excluded by default; opt-in via `include_deleted`.
+ *
+ * @param deps - query deps
+ * @param params - filter + visibility + ordering + pagination
+ * @returns matching rows, ordered per `order_by` / `order_direction`
+ */
+export declare const query_cell_list: (deps: QueryDeps, params: CellListParams) => Promise<Array<CellRow>>;
+/** Parameters for `query_cell_list`. All filter dimensions are optional. */
+export interface CellListParams {
+    /** Match `data.kind = ?` via `data @> {"kind": ?}` (uses `idx_cell_data`). */
+    data_kind?: string;
+    /**
+     * Match `cell.visibility = ?` directly on the top-level column.
+     * Additional narrowing on top of the SQL-side auth visibility
+     * predicate — useful for the public discovery feed where authed
+     * callers must NOT see their own private entries mixed in.
+     */
+    visibility?: CellVisibility;
+    /** Match cells whose `refs[]` contains this hash (uses `idx_cell_refs`). */
+    ref?: FactHash;
+    /** Filter to cells created by this actor (uses `idx_cell_created_by`). */
+    created_by?: Uuid;
+    /**
+     * Filter to cells whose `path` starts with this prefix. Wildcard
+     * metachars in the prefix are NOT special — `starts_with()` does
+     * literal matching.
+     */
+    path_prefix?: string;
+    /**
+     * Batch-fetch by id. The visibility predicate still runs, so callers
+     * passing ids they can't view simply get fewer rows back. Order of
+     * the returned rows follows `order_by` / `order_direction`, not the
+     * input list — callers that need positional output (e.g. preserving
+     * a collection's `items[]` order) should re-index client-side.
+     */
+    ids?: Array<Uuid>;
+    /**
+     * Viewer actor for the visibility predicate. Pass `null` for
+     * unauthenticated callers — only `cell.visibility === 'public'` rows
+     * are admitted then.
+     */
+    viewer_actor_id: Uuid | null;
+    /**
+     * When `true`, the visibility predicate is dropped (admin sees all).
+     * When `false`, rows pass when public, owned by the viewer, or
+     * admitted by a `cell_grant` row.
+     */
+    viewer_is_admin: boolean;
+    /**
+     * Caller's `actor_id` for the actor-shaped grant branch. NULL =
+     * anonymous (actor-grants can never admit). Kept distinct from
+     * `viewer_actor_id` for the predicate's clarity (the visibility branch
+     * and the grant branch are independent concerns even when they
+     * currently agree).
+     */
+    caller_actor_id?: Uuid | null;
+    /**
+     * Caller's role_grant roles, parallel-array projection of `auth.role_grants`
+     * (active-only — middleware filters). Pair-wise aligned with
+     * `caller_role_grant_scope_ids`. Empty array (or omitted) admits no
+     * role-shaped grants. The two arrays MUST have equal length —
+     * `unnest(text[], uuid[])` null-pads on length mismatch and would
+     * silently widen role-grant admits.
+     */
+    caller_role_grant_roles?: ReadonlyArray<string>;
+    /**
+     * Caller's role_grant scope ids, parallel-array projection. NULLs in the
+     * array mark global (any-scope) role_grants — `IS NOT DISTINCT FROM`
+     * handles them per design.
+     */
+    caller_role_grant_scope_ids?: ReadonlyArray<Uuid | null>;
+    /**
+     * When `true`, narrow to cells admitting the caller via a
+     * `cell_grant` row AND that the caller does not own. Authenticated
+     * only (`viewer_actor_id` must be set). Combine with `data_kind` /
+     * `path_prefix` etc. to scope further.
+     */
+    shared_with_caller_only?: boolean;
+    /** Sort column. Default `created_at`. */
+    order_by?: 'created_at' | 'updated_at';
+    /** Sort direction. Default `desc`. */
+    order_direction?: 'asc' | 'desc';
+    /** Page size. */
+    limit?: number;
+    /** Page offset. */
+    offset?: number;
+    /** Include soft-deleted rows. Default `false`. */
+    include_deleted?: boolean;
+}
+/**
+ * List active cells whose `refs` array contains the given fact hash,
+ * newest first. Backed by the `idx_cell_refs` GIN index.
+ *
+ * Used by the fact-serving route's authz walk: a fact is viewable iff
+ * **at least one** referencing active cell admits the caller via
+ * `can_view_cell`. Unreferenced facts (no row returned here) are
+ * unreachable through the public surface — orphan-fact GC handles them.
+ *
+ * `include_grant_count` defaults to true so the row hydrates uniformly
+ * with the rest of the cell query surface. The fact-serving route is
+ * the one hot path where the count is wasted work — pass `false`
+ * there to skip the per-row correlated subquery; the field falls back
+ * to a constant 0 so `CellRow` stays type-stable.
+ *
+ * @param deps - query deps
+ * @param hash - fact hash to search for
+ * @param options - pagination + grant-count toggle
+ * @returns matching active rows
+ */
+export declare const query_cell_list_by_ref: (deps: QueryDeps, hash: FactHash, options?: Pick<CellListOptions, "limit" | "offset"> & {
+    include_grant_count?: boolean;
+}) => Promise<Array<CellRow>>;
+//# sourceMappingURL=cell_queries.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cell_queries.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/cell_queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAC/C,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,0BAA0B,CAAC;AACnD,OAAO,KAAK,EAAC,IAAI,EAAC,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAyB,KAAK,QAAQ,EAAC,MAAM,+BAA+B,CAAC;AAGpF,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,6BAA6B,CAAC;AAC1D,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,8BAA8B,CAAC;AAEjE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,OAAO;IACvB,EAAE,EAAE,IAAI,CAAC;IACT,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,cAAc,CAAC;IAC3B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IAC7B,UAAU,EAAE,IAAI,CAAC;IACjB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;CACpB;AAgBD,oEAAoE;AACpE,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,IAAI,CAAC;IACX,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC/B,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,UAAU,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CACzB;AAED,yEAAyE;AACzE,MAAM,WAAW,eAAe;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,GAC7B,MAAM,SAAS,EACf,OAAO,oBAAoB,KACzB,OAAO,CAAC,OAAO,CAgBjB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GAC1B,MAAM,SAAS,EACf,IAAI,IAAI,EACR,UAAU;IAAC,eAAe,CAAC,EAAE,OAAO,CAAA;CAAC,KACnC,OAAO,CAAC,OAAO,GAAG,IAAI,CAUxB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,SAAS,EACf,MAAM,MAAM,KACV,OAAO,CAAC,OAAO,GAAG,IAAI,CAQxB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,GAChC,MAAM,SAAS,EACf,KAAK,aAAa,CAAC,IAAI,CAAC,KACtB,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAQxB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,GAC7B,MAAM,SAAS,EACf,IAAI,IAAI,EACR,OAAO,eAAe,KACpB,OAAO,CAAC,OAAO,GAAG,IAAI,CA4BxB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAC7B,MAAM,SAAS,EACf,IAAI,IAAI,EACR,UAAU;IAAC,UAAU,CAAC,EAAE,IAAI,GAAG,IAAI,CAAA;CAAC,KAClC,OAAO,CAAC,OAAO,CAWjB,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,GACxC,MAAM,SAAS,EACf,MAAM,MAAM,EACZ,UAAU,IAAI,CAAC,eAAe,EAAE,OAAO,GAAG,QAAQ,CAAC,KACjD,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CASvB,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,GACtC,MAAM,SAAS,EACf,UAAU,IAAI,EACd,UAAU,IAAI,CAAC,eAAe,EAAE,OAAO,GAAG,QAAQ,CAAC,KACjD,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAQvB,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,eAAO,MAAM,eAAe,GAC3B,MAAM,SAAS,EACf,QAAQ,cAAc,KACpB,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CA0DxB,CAAC;AAiGF,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC9B,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,4EAA4E;IAC5E,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,0EAA0E;IAC1E,UAAU,CAAC,EAAE,IAAI,CAAC;IAClB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,GAAG,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IAClB;;;;OAIG;IACH,eAAe,EAAE,IAAI,GAAG,IAAI,CAAC;IAC7B;;;;OAIG;IACH,eAAe,EAAE,OAAO,CAAC;IACzB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAC9B;;;;;;;OAOG;IACH,uBAAuB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAChD;;;;OAIG;IACH,2BAA2B,CAAC,EAAE,aAAa,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IACzD;;;;;OAKG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,yCAAyC;IACzC,QAAQ,CAAC,EAAE,YAAY,GAAG,YAAY,CAAC;IACvC,sCAAsC;IACtC,eAAe,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACjC,iBAAiB;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mBAAmB;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,eAAe,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,sBAAsB,GAClC,MAAM,SAAS,EACf,MAAM,QAAQ,EACd,UAAU,IAAI,CAAC,eAAe,EAAE,OAAO,GAAG,QAAQ,CAAC,GAAG;IAAC,mBAAmB,CAAC,EAAE,OAAO,CAAA;CAAC,KACnF,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAYxB,CAAC"}