@fuzdev/fuz_app 0.141.0 → 0.143.0

package/dist/db/cell_queries.js

@@ -22,7 +22,9 @@
  */
 import { fact_hash_extract_refs } from '@fuzdev/fuz_util/fact_hash.ts';
 import { assert_row } from './assert_row.js';
-import { iso8601_timestamp_expr, qualify_columns } from './sql_columns.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';
+import { can_view_cell_sql, caller_role_grants_cte, cell_grant_admits_caller_sql } from './cell_view_sql.js';
 /**
  * The full `cell` column set, named explicitly so a row read fails loud on
  * schema drift — a `SELECT *` silently omits a dropped column and the
@@ -69,6 +71,18 @@ const cell_expr = iso8601_timestamp_expr(CELL_COLUMNS, ['created_at', 'updated_a
  * actually produces one.
  */
 export const cell_row_projection = (alias) => `${qualify_columns(CELL_COLUMNS, alias, cell_expr(alias))}, (SELECT COUNT(*)::int FROM cell_grant WHERE cell_id = ${alias}.id) AS grant_count`;
+/**
+ * The columns a view check reads (`can_view_cell`) — the `CELL_COLUMNS`
+ * subset `query_cell_view_load_many` projects, typed against `CELL_COLUMNS`
+ * so the base const's drift guard covers it. Twin of `fuz_cell`'s
+ * `CELL_VIEW_COLUMNS`.
+ */
+export const CELL_VIEW_COLUMNS = [
+    'id',
+    'visibility',
+    'moderation',
+    'created_by'
+];
 /**
  * Insert a cell row, deriving `refs` from `data`.
  *
@@ -133,11 +147,10 @@ export const query_cell_get_by_path = async (deps, path) => {
     return row ?? 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.
+ * Bulk-load active cell rows by id, **no visibility filter applied** — the
+ * full rows, for a caller that copies or returns them (the deep-clone walk).
+ * A caller that needs only the view check reads `query_cell_view_load_many`.
+ * Soft-deleted rows are excluded so relations to tombstones never surface.
  *
  * @param deps - query deps
  * @param ids - cell ids to load (duplicates are harmless)
@@ -150,6 +163,24 @@ export const query_cell_load_many = async (deps, ids) => {
 		 FROM cell
 		 WHERE id = ANY($1::uuid[]) AND deleted_at IS NULL`, [ids]);
 };
+/**
+ * Bulk-load the active cells among `ids` for a view check — the
+ * `CELL_VIEW_COLUMNS` alone, never the payload. Backs 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 and ids with no row are absent.
+ *
+ * @param deps - query deps
+ * @param ids - cell ids to load (duplicates are harmless)
+ * @returns active rows in arbitrary order (caller indexes by `id`)
+ */
+export const query_cell_view_load_many = async (deps, ids) => {
+    if (ids.length === 0)
+        return [];
+    return deps.db.query(`SELECT ${columns_sql(CELL_VIEW_COLUMNS)}
+		 FROM cell
+		 WHERE id = ANY($1::uuid[]) AND deleted_at IS NULL`, [ids]);
+};
 /**
  * Update a cell. Fields left `undefined` in the patch keep their existing
  * value; explicit `null` writes `NULL`. `refs` is re-derived from `data`
@@ -274,15 +305,24 @@ export const query_cell_list_by_creator = async (deps, actor_id, options) => dep
  * dimension — keep it simple) plus an optional viewer-aware visibility
  * predicate.
  *
- * The visibility predicate mirrors `can_view_cell` in SQL form:
+ * The visibility predicate mirrors `can_view_cell || can_steward_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>))
+ *  OR (<moderation admits an audience> AND (
+ *       cell.visibility = 'public'
+ *       OR (viewer_actor_id IS NOT NULL AND <grant admits caller>)))
+ *  OR (viewer_actor_id IS NOT NULL AND <pending or rejected contribution>
+ *      AND <viewer owns its live governing root>))
  * ```
  *
+ * The moderation rules are `cell_moderation_admits_audience_sql` and
+ * `cell_moderation_is_stewardable_sql` (`db/cell_moderation.ts`). The last arm
+ * is the steward arm (`auth/cell_steward.ts`) — a root owner reads the
+ * moderation queue under their root; a global admin is already admitted.
+ *
  * 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
@@ -304,7 +344,9 @@ export const query_cell_list_by_creator = async (deps, actor_id, options) => dep
  * 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.
+ * own grant footprint, not every cell. A grant admits there only while the
+ * cell's moderation admits an audience, as in `can_view_cell`, and the steward
+ * arm doesn't apply — a grant footprint is not a moderation queue.
  *
  * Soft-deleted rows are excluded by default; opt-in via `include_deleted`.
  *
@@ -369,36 +411,17 @@ export const query_cell_list = async (deps, params) => {
     ]);
 };
 /**
- * The `cell_grant` admits-caller predicate, factored once and reused by
- * both SQL shapes (general visibility branch + shared-with-me semi-join).
- *
- * Resolves true when the grant row at `g_alias` admits the caller via
- * either an actor-shaped principal (`g.actor_id = $11`) or a
- * role-shaped principal whose `(role, scope_id)` matches a row in the
- * `caller_role_grants` CTE. NULL `g.scope_id` matches any scope, mirroring
- * `grant_admits` in `auth/cell_authorize.ts`.
+ * The caller's `(role, scope_id)` role_grant pairs, materialized once per
+ * query so the role-grant predicate doesn't re-scan `unnest()` per outer row.
+ * Shared by both SQL shapes.
  */
-const grant_admits_caller_predicate = (g_alias) => `(
-	     ($11::uuid IS NOT NULL AND ${g_alias}.actor_id = $11)
-	     OR (
-	       ${g_alias}.role IS NOT NULL
-	       AND EXISTS (
-	         SELECT 1 FROM caller_role_grants p
-	         WHERE p.role = ${g_alias}.role
-	           AND (${g_alias}.scope_id IS NULL OR p.scope_id IS NOT DISTINCT FROM ${g_alias}.scope_id)
-	       )
-	     )
-	   )`;
+const CALLER_ROLE_GRANTS_CTE = `WITH ${caller_role_grants_cte('$12', '$13')}`;
 /**
- * Materialize the caller's `(role, scope_id)` role_grant pairs once per
- * query so the role-grant predicate doesn't re-scan `unnest()` per
- * outer row. PG 12+ inlines non-recursive single-use CTEs, so this is
- * planner-equivalent to a subquery — the form is for clarity.
+ * General `cell_list` SQL: cell-driven scan, full visibility predicate — the
+ * `can_view_cell` arms (`can_view_cell_sql`), then the steward arm
+ * (`can_steward_cell`: the caller owns the live governing root of a pending or
+ * rejected contribution; a global admin is already in through `$6`).
  */
-const CALLER_ROLE_GRANTS_CTE = `WITH caller_role_grants AS (
-	   SELECT role, scope_id FROM unnest($12::text[], $13::uuid[]) AS p(role, scope_id)
-	 )`;
-/** General `cell_list` SQL: cell-driven scan, full visibility predicate. */
 const build_general_sql = (order_column, order_direction) => `${CALLER_ROLE_GRANTS_CTE}
 	 SELECT ${cell_row_projection('c')} FROM cell c
 	 WHERE ($1::bool OR c.deleted_at IS NULL)
@@ -411,13 +434,12 @@ const build_general_sql = (order_column, order_direction) => `${CALLER_ROLE_GRAN
 	   AND ($15::uuid IS NULL OR c.root_id = $15)
 	   AND ($16::text IS NULL OR c.moderation = $16::text)
 	   AND (
-	     $6::bool
-	     OR c.visibility = 'public'
-	     OR ($7::uuid IS NOT NULL AND c.created_by = $7)
-	     OR ($7::uuid IS NOT NULL AND EXISTS (
-	       SELECT 1 FROM cell_grant g
-	       WHERE g.cell_id = c.id AND ${grant_admits_caller_predicate('g')}
-	     ))
+	     ${can_view_cell_sql('c', { is_admin: '$6', actor_id: '$7', grant_actor_id: '$11' })}
+	     OR ($7::uuid IS NOT NULL AND c.root_id IS NOT NULL AND ${cell_moderation_is_stewardable_sql('c')}
+	       AND EXISTS (
+	         SELECT 1 FROM cell r
+	         WHERE r.id = c.root_id AND r.deleted_at IS NULL AND r.created_by = $7
+	       ))
 	   )
 	 ORDER BY c.${order_column} ${order_direction} NULLS LAST
 	 LIMIT $8 OFFSET $9`;
@@ -450,9 +472,10 @@ const build_shared_with_sql = (order_column, order_direction) => `${CALLER_ROLE_
 	   AND ($16::text IS NULL OR c.moderation = $16::text)
 	   AND $7::uuid IS NOT NULL
 	   AND c.created_by IS DISTINCT FROM $7
+	   AND ${cell_moderation_admits_audience_sql('c')}
 	   AND c.id IN (
 	     SELECT g.cell_id FROM cell_grant g
-	     WHERE ${grant_admits_caller_predicate('g')}
+	     WHERE ${cell_grant_admits_caller_sql('g', '$11')}
 	   )
 	   -- $6 (viewer_is_admin) intentionally not consulted: an admin
 	   -- asking "what's shared with me" wants their grant footprint, not

package/dist/db/cell_view_sql.d.ts

@@ -0,0 +1,102 @@
+/**
+ * `can_view_cell` in SQL — the view predicate a query applies to a cell row
+ * before `LIMIT`, so a page holds only rows the caller may view.
+ *
+ * `can_view_cell_sql` is the one SQL form of the predicate: `query_cell_list`
+ * embeds it (adding the steward arm beside it), and the relation lists apply
+ * it to the cell at the other end of each edge. It binds the caller through a
+ * `CellViewer` (`auth/cell_authorize.ts`'s `cell_viewer_from_auth` builds one
+ * from a request context), and the role-shaped grant arm reads the
+ * `caller_role_grants` CTE `caller_role_grants_cte` defines. Twin of the Rust
+ * `fuz_cell::cell_view_sql`.
+ *
+ * @module
+ */
+import type { Uuid } from '../primitive_schemas.js';
+/**
+ * The caller a view predicate binds — what `can_view_cell` reads off the
+ * request context.
+ *
+ * `role_grant_roles` and `role_grant_scope_ids` are parallel, one entry per
+ * active role grant (`null` = a global grant): `unnest` pads the shorter with
+ * NULLs, and a NULL scope reads as a global grant, so `cell_viewer_params`
+ * refuses a mismatch.
+ */
+export interface CellViewer {
+    /** The acting actor; `null` for an anonymous or account-grain caller. */
+    readonly actor_id: Uuid | null;
+    /** Whether the caller holds the global admin role — the arm that admits every cell. */
+    readonly is_admin: boolean;
+    /** The roles of the caller's active role grants, parallel to `role_grant_scope_ids`. */
+    readonly role_grant_roles: ReadonlyArray<string>;
+    /** The scopes of the caller's active role grants, parallel to `role_grant_roles`. */
+    readonly role_grant_scope_ids: ReadonlyArray<Uuid | null>;
+}
+/** An anonymous caller — admitted by the public arm alone. */
+export declare const CELL_VIEWER_ANONYMOUS: CellViewer;
+/**
+ * A server-side read that filters nothing — the admin arm admits every cell.
+ * For a caller that applies its own view check afterwards (the `cell_get`
+ * bundle) or acts for the server itself.
+ */
+export declare const CELL_VIEWER_UNRESTRICTED: CellViewer;
+/** Where a query binds the `CellViewer` facts `can_view_cell_sql` reads — each a `$N` placeholder. */
+export interface CellViewerSqlParams {
+    /** The global-admin flag (`bool`). */
+    readonly is_admin: string;
+    /** The acting actor (`uuid`, NULL when anonymous) — the owner arm and the grant arm's guard. */
+    readonly actor_id: string;
+    /**
+     * The actor an actor-shaped grant matches, when a query binds it apart
+     * from `actor_id` (`query_cell_list` does). Defaults to `actor_id`.
+     */
+    readonly grant_actor_id?: string;
+}
+/**
+ * The viewer's bind values, in the order `[is_admin, actor_id, roles,
+ * scope_ids]`.
+ *
+ * @param viewer - the caller
+ * @returns the four bind values
+ * @throws {Error} when the role-grant arrays aren't parallel
+ */
+export declare const cell_viewer_params: (viewer: CellViewer) => [boolean, Uuid | null, ReadonlyArray<string>, ReadonlyArray<Uuid | null>];
+/**
+ * The `caller_role_grants` CTE body (no `WITH`): the caller's
+ * `(role, scope_id)` pairs, unnested once per query from the parallel arrays
+ * at placeholders `roles` and `scope_ids`. PG 12+ inlines a non-recursive
+ * single-use CTE, so this is planner-equivalent to a subquery — the form is
+ * for clarity.
+ *
+ * @param roles - the placeholder of the roles array (`text[]`)
+ * @param scope_ids - the placeholder of the scope-id array (`uuid[]`)
+ * @returns the CTE body
+ */
+export declare const caller_role_grants_cte: (roles: string, scope_ids: string) => string;
+/**
+ * The `cell_grant` admits-caller predicate over grant alias `g_alias`: an
+ * actor-shaped grant matches the actor at placeholder `actor_id`; a
+ * role-shaped grant matches a `(role, scope_id)` pair in the
+ * `caller_role_grants` CTE (a NULL grant `scope_id` matches any scope).
+ * Mirrors `grant_admits` in `auth/cell_authorize.ts`.
+ *
+ * @param g_alias - the `cell_grant` alias in the enclosing query
+ * @param actor_id - the placeholder of the caller's actor (`uuid`)
+ * @returns the SQL predicate
+ */
+export declare const cell_grant_admits_caller_sql: (g_alias: string, actor_id: string) => string;
+/**
+ * `can_view_cell` over the cell alias `c_alias`: admin, the owner, or — while
+ * the cell's `moderation` admits an audience — `public` or a `cell_grant`
+ * admitting the caller.
+ *
+ * Reads the caller at `params`; the grant arm needs the
+ * `caller_role_grants_cte` in scope. Liveness (`deleted_at IS NULL`) is the
+ * query's own clause, as `can_view_cell` reads a loaded live row.
+ *
+ * @param c_alias - the `cell` alias in the enclosing query
+ * @param params - where the query binds the caller
+ * @returns the SQL predicate (parenthesized)
+ */
+export declare const can_view_cell_sql: (c_alias: string, params: CellViewerSqlParams) => string;
+//# sourceMappingURL=cell_view_sql.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cell_view_sql.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/cell_view_sql.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAGpD;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;IAC/B,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,wFAAwF;IACxF,QAAQ,CAAC,gBAAgB,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACjD,qFAAqF;IACrF,QAAQ,CAAC,oBAAoB,EAAE,aAAa,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;CAC1D;AAED,8DAA8D;AAC9D,eAAO,MAAM,qBAAqB,EAAE,UAKnC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,UAKtC,CAAC;AAEF,sGAAsG;AACtG,MAAM,WAAW,mBAAmB;IACnC,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gGAAgG;IAChG,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAC9B,QAAQ,UAAU,KAChB,CAAC,OAAO,EAAE,IAAI,GAAG,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,IAAI,GAAG,IAAI,CAAC,CAQ1E,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,GAAI,OAAO,MAAM,EAAE,WAAW,MAAM,KAAG,MAGtE,CAAC;AAEL;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,GAAI,SAAS,MAAM,EAAE,UAAU,MAAM,KAAG,MAU3E,CAAC;AAEP;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAS,MAAM,EAAE,QAAQ,mBAAmB,KAAG,MAchF,CAAC"}

package/dist/db/cell_view_sql.js

@@ -0,0 +1,112 @@
+/**
+ * `can_view_cell` in SQL — the view predicate a query applies to a cell row
+ * before `LIMIT`, so a page holds only rows the caller may view.
+ *
+ * `can_view_cell_sql` is the one SQL form of the predicate: `query_cell_list`
+ * embeds it (adding the steward arm beside it), and the relation lists apply
+ * it to the cell at the other end of each edge. It binds the caller through a
+ * `CellViewer` (`auth/cell_authorize.ts`'s `cell_viewer_from_auth` builds one
+ * from a request context), and the role-shaped grant arm reads the
+ * `caller_role_grants` CTE `caller_role_grants_cte` defines. Twin of the Rust
+ * `fuz_cell::cell_view_sql`.
+ *
+ * @module
+ */
+import { cell_moderation_admits_audience_sql } from './cell_moderation.js';
+/** An anonymous caller — admitted by the public arm alone. */
+export const CELL_VIEWER_ANONYMOUS = {
+    actor_id: null,
+    is_admin: false,
+    role_grant_roles: [],
+    role_grant_scope_ids: []
+};
+/**
+ * A server-side read that filters nothing — the admin arm admits every cell.
+ * For a caller that applies its own view check afterwards (the `cell_get`
+ * bundle) or acts for the server itself.
+ */
+export const CELL_VIEWER_UNRESTRICTED = {
+    actor_id: null,
+    is_admin: true,
+    role_grant_roles: [],
+    role_grant_scope_ids: []
+};
+/**
+ * The viewer's bind values, in the order `[is_admin, actor_id, roles,
+ * scope_ids]`.
+ *
+ * @param viewer - the caller
+ * @returns the four bind values
+ * @throws {Error} when the role-grant arrays aren't parallel
+ */
+export const cell_viewer_params = (viewer) => {
+    if (viewer.role_grant_roles.length !== viewer.role_grant_scope_ids.length) {
+        throw new Error(`CellViewer: role_grant_roles (len=${viewer.role_grant_roles.length}) and ` +
+            `role_grant_scope_ids (len=${viewer.role_grant_scope_ids.length}) must be parallel arrays`);
+    }
+    return [viewer.is_admin, viewer.actor_id, viewer.role_grant_roles, viewer.role_grant_scope_ids];
+};
+/**
+ * The `caller_role_grants` CTE body (no `WITH`): the caller's
+ * `(role, scope_id)` pairs, unnested once per query from the parallel arrays
+ * at placeholders `roles` and `scope_ids`. PG 12+ inlines a non-recursive
+ * single-use CTE, so this is planner-equivalent to a subquery — the form is
+ * for clarity.
+ *
+ * @param roles - the placeholder of the roles array (`text[]`)
+ * @param scope_ids - the placeholder of the scope-id array (`uuid[]`)
+ * @returns the CTE body
+ */
+export const caller_role_grants_cte = (roles, scope_ids) => `caller_role_grants AS (
+	   SELECT role, scope_id FROM unnest(${roles}::text[], ${scope_ids}::uuid[]) AS p(role, scope_id)
+	 )`;
+/**
+ * The `cell_grant` admits-caller predicate over grant alias `g_alias`: an
+ * actor-shaped grant matches the actor at placeholder `actor_id`; a
+ * role-shaped grant matches a `(role, scope_id)` pair in the
+ * `caller_role_grants` CTE (a NULL grant `scope_id` matches any scope).
+ * Mirrors `grant_admits` in `auth/cell_authorize.ts`.
+ *
+ * @param g_alias - the `cell_grant` alias in the enclosing query
+ * @param actor_id - the placeholder of the caller's actor (`uuid`)
+ * @returns the SQL predicate
+ */
+export const cell_grant_admits_caller_sql = (g_alias, actor_id) => `(
+	     (${actor_id}::uuid IS NOT NULL AND ${g_alias}.actor_id = ${actor_id})
+	     OR (
+	       ${g_alias}.role IS NOT NULL
+	       AND EXISTS (
+	         SELECT 1 FROM caller_role_grants p
+	         WHERE p.role = ${g_alias}.role
+	           AND (${g_alias}.scope_id IS NULL OR p.scope_id IS NOT DISTINCT FROM ${g_alias}.scope_id)
+	       )
+	     )
+	   )`;
+/**
+ * `can_view_cell` over the cell alias `c_alias`: admin, the owner, or — while
+ * the cell's `moderation` admits an audience — `public` or a `cell_grant`
+ * admitting the caller.
+ *
+ * Reads the caller at `params`; the grant arm needs the
+ * `caller_role_grants_cte` in scope. Liveness (`deleted_at IS NULL`) is the
+ * query's own clause, as `can_view_cell` reads a loaded live row.
+ *
+ * @param c_alias - the `cell` alias in the enclosing query
+ * @param params - where the query binds the caller
+ * @returns the SQL predicate (parenthesized)
+ */
+export const can_view_cell_sql = (c_alias, params) => {
+    const { is_admin, actor_id } = params;
+    const grant_actor_id = params.grant_actor_id ?? actor_id;
+    return `(
+	     ${is_admin}::bool
+	     OR (${actor_id}::uuid IS NOT NULL AND ${c_alias}.created_by = ${actor_id})
+	     OR (${cell_moderation_admits_audience_sql(c_alias)} AND (
+	       ${c_alias}.visibility = 'public'
+	       OR (${actor_id}::uuid IS NOT NULL AND EXISTS (
+	         SELECT 1 FROM cell_grant g
+	         WHERE g.cell_id = ${c_alias}.id AND ${cell_grant_admits_caller_sql('g', grant_actor_id)}
+	       ))
+	     ))
+	   )`;
+};

package/dist/db/db_pg.d.ts

@@ -18,7 +18,7 @@ import { type DbDriverResult } from './db.js';
  * call this, don't need `pg` installed) and coerces int8 (`BIGINT`, OID 20)
  * to a JS number. pg defaults to returning
  * int8 as a string to avoid 2^53 precision loss; our int8 columns today
- * (`audit_log.seq`, `cell_history.id`, `fact.size`) stay well under that
+ * (`audit_log.seq`, `fact.size`) stay well under that
  * bound, and reading as a number keeps the wire shape uniform with PGlite —
  * which returns int8 as a number — so `AuditLogEvent.seq` and friends
  * validate identically across both drivers.

package/dist/db/db_pg.js

@@ -17,7 +17,7 @@ import { Db, no_nested_transaction } from './db.js';
  * call this, don't need `pg` installed) and coerces int8 (`BIGINT`, OID 20)
  * to a JS number. pg defaults to returning
  * int8 as a string to avoid 2^53 precision loss; our int8 columns today
- * (`audit_log.seq`, `cell_history.id`, `fact.size`) stay well under that
+ * (`audit_log.seq`, `fact.size`) stay well under that
  * bound, and reading as a number keeps the wire shape uniform with PGlite —
  * which returns int8 as a number — so `AuditLogEvent.seq` and friends
  * validate identically across both drivers.

package/dist/http/CLAUDE.md

@@ -24,7 +24,7 @@ effects, see ../../../docs/architecture.md.
 - `http/surface_query.ts` — pure filters/groupings over `AppSurface`.
 - `http/proxy.ts` — trusted-proxy middleware, CIDR parsing, rightmost-first XFF resolution. Pulls `hono/utils/ipaddr` for CIDR matching.
 - `http/client_ip.ts` — `get_client_ip(c)` — reads the resolved IP off the context (set by `proxy.ts`'s middleware). Split out of `proxy.ts` so it's hono-free: dispatch + route modules that only _read_ the IP don't pull `hono/utils/ipaddr`, keeping cross-process test surfaces free of the optional `hono` peer.
-- `http/ip_canonical.ts` — RFC 5952 IPv6 canonicalization + IPv4-mapped collapse; `IP_LITERAL_CHARS` regex.
+- `http/ip_canonical.ts` — RFC 5952 IPv6 canonicalization + IPv4-mapped collapse, `rate_limit_ip_key` (an IPv6 client's `/64`), and its own `parse_ipv4_bits` / `parse_ipv6_bits` (the grammar of Rust's `IpAddr::from_str`); `IP_LITERAL_CHARS` regex. Imports nothing — the dispatcher keys its IP limiter through it, so it must stay hono-free (`src/test/hono_free_modules.test.ts` walks every `src/lib` module's graph).
 - `http/origin.ts` — origin allowlist: the strict pattern grammar shared with the Rust spine, typed refusals, and the Origin-only middleware.
 - `http/jsonrpc.ts` — JSON-RPC 2.0 envelope schemas (MCP superset), `JsonrpcErrorCode`, `_meta`.
 - `http/jsonrpc_errors.ts` — `ThrownJsonrpcError`, `jsonrpc_errors` throwers, HTTP-status mappings.

package/dist/http/auth_shape.d.ts

@@ -68,9 +68,12 @@ export type ActingActor = z.infer<typeof ActingActor>;
  * instead would put an input-shape complaint ahead of the authority gates,
  * which is the ordering this pipeline exists to avoid.
  *
- * Both callers pass through here so that rule has one home: the action
+ * The dispatchers pass through here so that rule has one home: the action
  * dispatcher's `read_acting` and the REST authorization handler's
- * `read_route_acting`. Twin of the Rust dispatcher's `read_acting`.
+ * `read_route_acting`. Twin of the Rust dispatcher's `read_acting`. The status
+ * route and the WS upgrade read the raw `?acting=` through it too; neither has
+ * an input schema behind it, so there a malformed selector is final (the
+ * status route answers account-only).
  *
  * @param value - the raw `acting` field, from params / query / body
  * @returns the actor id, or `undefined` when absent or malformed

package/dist/http/auth_shape.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth_shape.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/auth_shape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,WAAW,6DAGtB,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,SAGtD,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa;;;;EAA2C,CAAC;AACtE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;kBAyEnB,CAAC;AACJ,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAUlD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,SAAS,KAAG,OACA,CAAC;AAElD;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,SAAS,KAAG,OAAgC,CAAC;AAE/E;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,KAAG,OAAkC,CAAC;AAEnF,wEAAwE;AACxE,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,KAAG,OAA+B,CAAC;AAE/E,8FAA8F;AAC9F,eAAO,MAAM,wBAAwB,GAAI,MAAM,SAAS,KAAG,OAC3B,CAAC;AAEjC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,SAAS,KAAG,OACQ,CAAC;AAE1D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2BAA2B,GAAI,MAAM,SAAS,KAAG,OACwB,CAAC;AAYvF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OAIhE,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,sCAAsC,GAClD,MAAM,SAAS,EACf,OAAO,WAAW,EAClB,SAAS,MAAM,KACb,IAmBF,CAAC"}
+{"version":3,"file":"auth_shape.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/auth_shape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,WAAW,6DAGtB,CAAC;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,SAGtD,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa;;;;EAA2C,CAAC;AACtE,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;kBAyEnB,CAAC;AACJ,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC;AAUlD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,SAAS,KAAG,OACA,CAAC;AAElD;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,SAAS,KAAG,OAAgC,CAAC;AAE/E;;;;GAIG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,KAAG,OAAkC,CAAC;AAEnF,wEAAwE;AACxE,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,KAAG,OAA+B,CAAC;AAE/E,8FAA8F;AAC9F,eAAO,MAAM,wBAAwB,GAAI,MAAM,SAAS,KAAG,OAC3B,CAAC;AAEjC;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,SAAS,KAAG,OACQ,CAAC;AAE1D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2BAA2B,GAAI,MAAM,SAAS,KAAG,OACwB,CAAC;AAYvF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,OAIhE,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC3B,KAAK,EAAE,CAAC,CAAC,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,sCAAsC,GAClD,MAAM,SAAS,EACf,OAAO,WAAW,EAClB,SAAS,MAAM,KACb,IAmBF,CAAC"}

package/dist/http/auth_shape.js

@@ -71,9 +71,12 @@ export const ActingActor = Uuid.optional().meta({
  * instead would put an input-shape complaint ahead of the authority gates,
  * which is the ordering this pipeline exists to avoid.
  *
- * Both callers pass through here so that rule has one home: the action
+ * The dispatchers pass through here so that rule has one home: the action
  * dispatcher's `read_acting` and the REST authorization handler's
- * `read_route_acting`. Twin of the Rust dispatcher's `read_acting`.
+ * `read_route_acting`. Twin of the Rust dispatcher's `read_acting`. The status
+ * route and the WS upgrade read the raw `?acting=` through it too; neither has
+ * an input schema behind it, so there a malformed selector is final (the
+ * status route answers account-only).
  *
  * @param value - the raw `acting` field, from params / query / body
  * @returns the actor id, or `undefined` when absent or malformed

package/dist/http/ip_canonical.d.ts

@@ -18,7 +18,8 @@
  *    strings (`'unknown'`, `'attacker:controlled'`, `'::1\n'`) pass
  *    through unchanged so downstream strict validators can still
  *    reject them.
- * 2. Parses via Hono's `convertIPv*ToBinary` family.
+ * 2. Parses with `parse_ipv4_bits` / `parse_ipv6_bits` — the grammar of
+ *    Rust's `IpAddr::from_str`, which the spine parses with.
  * 3. Re-emits the canonical RFC 5952 string (lowercase hex,
  *    longest-zero-run compressed, IPv4-mapped emitted in the dotted
  *    form mandated by RFC 5952 §5).
@@ -27,12 +28,41 @@
  *    canonicalization because the dotted form is the only form the
  *    strip can recognize symmetrically.
  *
- * Mirrors `zzz_server::proxy::normalize_ip` (landed 2026-05-16) which
- * uses the same parse-then-canonicalize-then-strip ordering for the
- * same rate-limit-key-poisoning surface.
+ * Mirrors the Rust spine's `fuz_http::normalize_ip`, which uses the same
+ * parse-then-canonicalize-then-strip ordering for the same
+ * rate-limit-key-poisoning surface.
+ *
+ * `rate_limit_ip_key` is the bucket key an IP-keyed rate limiter uses: an
+ * IPv6 address collapses to its `/64`, the smallest block a host is commonly
+ * assigned, so rotating through one's own subnet buys no fresh budget. Only
+ * the limiter call sites apply it — the client IP stays the full address
+ * everywhere else (audit rows, token `last_used_ip`, `REMOTE_ADDR`).
+ *
+ * The module imports nothing: the action dispatcher keys its IP limiter
+ * through it, so it must not pull the optional `hono` peer.
  *
  * @module
  */
+/**
+ * Parse a dotted-quad IPv4 address to its 32-bit value.
+ *
+ * Four decimal octets, each 0–255 with no leading zeros (`01.2.3.4` is
+ * refused, as Rust's `Ipv4Addr::from_str` refuses it).
+ *
+ * @returns the address as an unsigned 32-bit number, or `null` when `ip` isn't one
+ */
+export declare const parse_ipv4_bits: (ip: string) => number | null;
+/**
+ * Parse an IPv6 address to its 128-bit value.
+ *
+ * The grammar of Rust's `Ipv6Addr::from_str`: eight groups of one to four
+ * hex digits (either case), or fewer around a single `::` standing for one or
+ * more zero groups, the last two groups optionally written as a dotted-quad
+ * IPv4 address. No zone (`%eth0`) — callers strip it first.
+ *
+ * @returns the address as a `bigint` in `[0, 2^128)`, or `null` when `ip` isn't one
+ */
+export declare const parse_ipv6_bits: (ip: string) => bigint | null;
 /**
  * Allowed character set for a bare IP literal.
  *
@@ -89,7 +119,7 @@ export declare const canonicalize_ip: (ip: string) => string;
  *
  * Pure helper exported for the test suite to exercise the
  * canonicalization invariants directly without a full
- * `convertIPv6ToBinary` round-trip.
+ * `parse_ipv6_bits` round-trip.
  *
  * @param bits - the 128-bit IPv6 value as `bigint`. Must satisfy `0n <= bits < 2n ** 128n`;
  *   throws `RangeError` otherwise. Silent truncation would mask caller bugs since the
@@ -97,4 +127,25 @@ export declare const canonicalize_ip: (ip: string) => string;
  * @throws {RangeError} when `bits` is negative or exceeds 128 bits
  */
 export declare const ipv6_bigint_to_canonical: (bits: bigint) => string;
+/**
+ * The bucket key an IP-keyed rate limiter uses for client IP `ip`.
+ *
+ * An IPv6 address keys its `/64`: the low 64 bits masked off, rendered in
+ * RFC 5952 canonical form with a `/64` suffix (`2001:db8:1:2::/64`; the
+ * all-zero prefix is `::/64`). A zone suffix (`%eth0`) is dropped first. An
+ * IPv4 address — an IPv4-mapped IPv6 one included — keys its canonical form,
+ * with no suffix. Anything that doesn't parse (`'unknown'` among them) is
+ * returned unchanged. Twin of the Rust spine's `fuz_http::rate_limit_ip_key`.
+ *
+ * For limiter keys only: audit rows and every other record of the client
+ * keep the full address.
+ *
+ * @example
+ * rate_limit_ip_key('2001:db8:1:2::1')        // → '2001:db8:1:2::/64'
+ * rate_limit_ip_key('2001:db8:1:2:8000::')    // → '2001:db8:1:2::/64'
+ * rate_limit_ip_key('fe80::1%eth0')           // → 'fe80::/64'
+ * rate_limit_ip_key('203.0.113.7')            // → '203.0.113.7'
+ * rate_limit_ip_key('unknown')                // → 'unknown'
+ */
+export declare const rate_limit_ip_key: (ip: string) => string;
 //# sourceMappingURL=ip_canonical.d.ts.map

package/dist/http/ip_canonical.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ip_canonical.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/ip_canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAIH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,QAAqB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,eAAe,GAAI,IAAI,MAAM,KAAG,MAmC5C,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,wBAAwB,GAAI,MAAM,MAAM,KAAG,MAgEvD,CAAC"}
+{"version":3,"file":"ip_canonical.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/ip_canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AASH;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,GAAI,IAAI,MAAM,KAAG,MAAM,GAAG,IAKrD,CAAC;AA0BF;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,GAAI,IAAI,MAAM,KAAG,MAAM,GAAG,IAkBrD,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,QAAqB,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,eAAO,MAAM,eAAe,GAAI,IAAI,MAAM,KAAG,MAsB5C,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,wBAAwB,GAAI,MAAM,MAAM,KAAG,MAgEvD,CAAC;AAKF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,iBAAiB,GAAI,IAAI,MAAM,KAAG,MAQ9C,CAAC"}