@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/adapters/scoped/keyRows.d.ts

@@ -0,0 +1,65 @@
+/**
+ * A record's row, read once in full through the row scope by its key, and
+ * every later read of that record by the same key, in the same transaction
+ * and under the same scope, answered from it: the columns it asks for, in its
+ * order, from the row already read.
+ *
+ * A command reads its target by key several times before it writes — whether
+ * it is visible, its revision, the columns its machine moves, the before image
+ * its audit keeps, the guard the write checks — each a round trip of its own,
+ * each the same row. Read under the row lock the transaction takes first
+ * (postgres.ts sends both ahead, behind its BEGIN), the row cannot move
+ * underneath it, and a row scope's visibility is decided by the row's own
+ * columns (shared/rowScope.ts), so the projection is what each read would
+ * have answered.
+ *
+ * Only while the transaction has sent nothing that could change it: a row is
+ * kept with the transaction's statement generation (postgresTransactionHandle
+ * generationOf), which moves with every statement that is not a read or a
+ * lock — its own write, a savepoint, a rollback, a failure — and a row kept
+ * under an older generation answers nothing. Only reads that name the
+ * table's primary key by equality, from the first row, with no order, are
+ * answered; anything else is asked in its turn. A read that also names other
+ * columns by equality (a guard: the record, and only in the state it moves
+ * from) is answered only where the kept row holds exactly the value asked,
+ * identical in type and content: identical values are equal under any
+ * collation or type the server compares them by, so that answer is the
+ * server's. Where they differ (a numeric's text, a citext's case, a bytea),
+ * the read is asked in its turn rather than answered with no row.
+ */
+import { type Filter, type QueryRequest, type ScopedReads, type SqlFragment } from '../adapter.js';
+import type { DatabaseSchema, TableMeta } from '../../shared/schema.js';
+import type { RowScope } from '../../shared/rowScope.js';
+type Row = Record<string, unknown>;
+type Reads = Pick<ScopedReads, 'query'> & Partial<ScopedReads>;
+export declare class KeyRows {
+    #private;
+    /** The transaction's statement generation now; undefined where it has none (nothing is kept). */
+    private readonly generation;
+    constructor(
+    /** The transaction's statement generation now; undefined where it has none (nothing is kept). */
+    generation: () => number | undefined);
+    /** Keep nothing more and answer nothing from what was kept (the catalog the rows were read under is not the transaction's). */
+    forget(): void;
+    /** Keep the rows a full read of `table` by its key will answer (`rows`, the driver's own, unconverted). */
+    keep(scope: RowScope, table: TableMeta, filter: Filter, rows: Promise<readonly Row[]>, take?: () => void): void;
+    /**
+     * `reads`, with every read by key answered from a kept row where one is
+     * kept. `statementOf` says the statement the read would have sent (its
+     * `sql`); `format` turns a driver row into the read's own (binary or not, as
+     * the read's executor would). With `keeps`, a full read by key that is asked
+     * in its turn is kept for those after it (a guard's read: its rows are the
+     * driver's own). With `widen`, a read by key of a row the transaction holds
+     * locked (`held`), with nothing kept of it since the transaction last
+     * changed something, is sent as a full read through `widen.reads` (whose
+     * rows are the driver's own) and kept, and answered from it: the row cannot
+     * move while the lock is held, so the reads of it that follow — the guard
+     * reads of the write it is read for — are answered from it too, rather
+     * than each asked in its turn.
+     */
+    over<R extends Reads>(reads: R, scope: RowScope, schema: DatabaseSchema, statementOf: (request: QueryRequest) => SqlFragment | undefined, format: (row: Row, request: QueryRequest) => Row, keeps: boolean, widen?: {
+        held(table: TableMeta, key: Readonly<Record<string, string | number>>): boolean;
+        reads: Pick<ScopedReads, 'query'>;
+    }): R;
+}
+export {};

package/dist/adapters/scoped/keyRows.js

@@ -0,0 +1,173 @@
+/**
+ * A record's row, read once in full through the row scope by its key, and
+ * every later read of that record by the same key, in the same transaction
+ * and under the same scope, answered from it: the columns it asks for, in its
+ * order, from the row already read.
+ *
+ * A command reads its target by key several times before it writes — whether
+ * it is visible, its revision, the columns its machine moves, the before image
+ * its audit keeps, the guard the write checks — each a round trip of its own,
+ * each the same row. Read under the row lock the transaction takes first
+ * (postgres.ts sends both ahead, behind its BEGIN), the row cannot move
+ * underneath it, and a row scope's visibility is decided by the row's own
+ * columns (shared/rowScope.ts), so the projection is what each read would
+ * have answered.
+ *
+ * Only while the transaction has sent nothing that could change it: a row is
+ * kept with the transaction's statement generation (postgresTransactionHandle
+ * generationOf), which moves with every statement that is not a read or a
+ * lock — its own write, a savepoint, a rollback, a failure — and a row kept
+ * under an older generation answers nothing. Only reads that name the
+ * table's primary key by equality, from the first row, with no order, are
+ * answered; anything else is asked in its turn. A read that also names other
+ * columns by equality (a guard: the record, and only in the state it moves
+ * from) is answered only where the kept row holds exactly the value asked,
+ * identical in type and content: identical values are equal under any
+ * collation or type the server compares them by, so that answer is the
+ * server's. Where they differ (a numeric's text, a citext's case, a bytea),
+ * the read is asked in its turn rather than answered with no row.
+ */
+import { clampLimit } from '../adapter.js';
+export class KeyRows {
+    generation;
+    #entries = new Map();
+    #scopes = new WeakMap();
+    #next = 0;
+    constructor(
+    /** The transaction's statement generation now; undefined where it has none (nothing is kept). */
+    generation) {
+        this.generation = generation;
+    }
+    /** Keep nothing more and answer nothing from what was kept (the catalog the rows were read under is not the transaction's). */
+    forget() {
+        this.#entries.clear();
+    }
+    #scope(scope) {
+        let id = this.#scopes.get(scope);
+        if (id === undefined)
+            this.#scopes.set(scope, (id = this.#next++));
+        return id;
+    }
+    /** The key a read of `table` by `filter` is kept under: undefined unless the filter is exactly the primary key by equality. */
+    #keyOf(scope, table, filter) {
+        const found = this.#guarded(scope, table, filter);
+        return found && !found.also.length ? found.key : undefined;
+    }
+    /** The key of a read by the primary key by equality, and the other columns it names by equality (`also`). */
+    #guarded(scope, table, filter) {
+        const pk = table.columns.filter((column) => column.primaryKey).map((column) => column.name);
+        const group = filter?.groups.length === 1 ? filter.groups[0] : undefined;
+        if (!pk.length || !group || group.length < pk.length)
+            return undefined;
+        const values = {};
+        const also = [];
+        for (const condition of group) {
+            if (condition.op !== '=' || Object.keys(condition).length !== 3)
+                return undefined;
+            if (pk.includes(condition.column)) {
+                if (typeof condition.value !== 'string' && typeof condition.value !== 'number')
+                    return undefined;
+                if (Object.hasOwn(values, condition.column))
+                    return undefined;
+                values[condition.column] = condition.value;
+                continue;
+            }
+            const column = table.columns.find((candidate) => candidate.name === condition.column);
+            // json has no equality operator: the server refuses that read, so it is sent for the server to say so.
+            if (!column || /^json$/i.test(column.type))
+                return undefined;
+            if (typeof condition.value !== 'string' && typeof condition.value !== 'number' && typeof condition.value !== 'boolean')
+                return undefined;
+            also.push({ column: condition.column, value: condition.value });
+        }
+        if (Object.keys(values).length !== pk.length)
+            return undefined;
+        return { key: JSON.stringify([this.#scope(scope), table.id, pk.map((column) => values[column])]), values, also };
+    }
+    /** Keep the rows a full read of `table` by its key will answer (`rows`, the driver's own, unconverted). */
+    keep(scope, table, filter, rows, take) {
+        const generation = this.generation(), key = this.#keyOf(scope, table, filter);
+        if (generation === undefined || key === undefined)
+            return;
+        this.#entries.set(key, {
+            generation,
+            // A failed read answers nothing: each read is then asked in its turn.
+            rows: rows.then((found) => found, () => undefined),
+            take,
+        });
+    }
+    /**
+     * `reads`, with every read by key answered from a kept row where one is
+     * kept. `statementOf` says the statement the read would have sent (its
+     * `sql`); `format` turns a driver row into the read's own (binary or not, as
+     * the read's executor would). With `keeps`, a full read by key that is asked
+     * in its turn is kept for those after it (a guard's read: its rows are the
+     * driver's own). With `widen`, a read by key of a row the transaction holds
+     * locked (`held`), with nothing kept of it since the transaction last
+     * changed something, is sent as a full read through `widen.reads` (whose
+     * rows are the driver's own) and kept, and answered from it: the row cannot
+     * move while the lock is held, so the reads of it that follow — the guard
+     * reads of the write it is read for — are answered from it too, rather
+     * than each asked in its turn.
+     */
+    over(reads, scope, schema, statementOf, format, keeps, widen) {
+        const query = async (request) => {
+            const table = schema.tables.find((candidate) => candidate.id === request?.table);
+            const guarded = table && !request.orderBy?.length && !request.offset && clampLimit(request.limit) >= 1
+                ? this.#guarded(scope, table, request.filter)
+                : undefined;
+            const key = guarded && !guarded.also.length ? guarded.key : undefined;
+            // Asked again after a statement that moved the generation, of a column the row does not carry, or of a value it does not hold exactly: in its turn.
+            const answer = async (kept) => {
+                const rows = await kept.rows;
+                const names = request.columns?.length ? request.columns : table.columns.map((column) => column.name);
+                const sql = statementOf(request);
+                if (!rows ||
+                    !sql ||
+                    kept.generation !== this.generation() ||
+                    !rows.every((row) => names.every((name) => Object.hasOwn(row, name))) ||
+                    !rows.every((row) => guarded.also.every((condition) => Object.hasOwn(row, condition.column) && row[condition.column] === condition.value)))
+                    return undefined;
+                kept.take?.();
+                return {
+                    columns: [...names],
+                    rows: rows
+                        .slice(0, clampLimit(request.limit))
+                        .map((row) => format(Object.fromEntries(names.map((name) => [name, row[name]])), request)),
+                    ms: 0,
+                    sql,
+                };
+            };
+            const current = this.generation();
+            const kept = guarded === undefined ? undefined : this.#entries.get(guarded.key);
+            if (kept && kept.generation === current) {
+                const answered = await answer(kept);
+                if (answered)
+                    return answered;
+            }
+            else if (key !== undefined && current !== undefined && widen?.held(table, guarded.values)) {
+                const sent = widen.reads.query({ table: request.table, filter: request.filter, limit: 2, offset: 0 });
+                /* Its generation is the one it was sent under: what waited for the COMMIT leaves in front of it, in its flight
+                   (postgresTransactionHandle), moving the generation as it goes, and the row it reads is after that. Kept
+                   under the generation before it was sent, it would answer nothing after it. Reads are sent as they are
+                   asked (createScopedReads compiles before it executes), so this is that moment. */
+                const generation = this.generation();
+                // A failure is the read's own: thrown as it would have been asked.
+                const full = await sent;
+                const read = { generation: generation ?? current, rows: Promise.resolve(full.rows) };
+                this.#entries.set(key, read);
+                const answered = await answer(read);
+                if (answered)
+                    return answered;
+            }
+            if (!keeps || key === undefined || request.columns?.length)
+                return reads.query(request);
+            const generation = this.generation();
+            const result = await reads.query(request);
+            if (generation !== undefined && generation === this.generation())
+                this.#entries.set(key, { generation, rows: Promise.resolve(result.rows) });
+            return result;
+        };
+        return Object.freeze({ ...reads, query });
+    }
+}

package/dist/adapters/scoped/postgresScopeCatalog.d.ts

@@ -0,0 +1,16 @@
+import type { DatabaseSchema } from '../../shared/schema.js';
+import type { RowScope } from '../../shared/rowScope.js';
+import type { PgQuery } from '../postgresPool.js';
+import { type ScopeCatalog } from './scopedTransaction.js';
+export interface PostgresScopeCatalog extends ScopeCatalog {
+    /** Ordinary tables the writer role may UPDATE, and so lock rows in. A
+     * superset of `writable`: a lockable table with a trigger is still refused
+     * as a target, but its rows can be held for a parent-visibility check. */
+    lockable: ReadonlySet<string>;
+    /** The relations this read pinned, quoted, in order: what a later transaction under the same epoch pins before it reads the epoch. */
+    pinned: readonly string[];
+}
+/** Call only on the leased writer inside its transaction, before any read of
+ * user data. The describe callback is the adapter's own introspection so the
+ * evidence has the same shape as the catalog the permissions were bound to. */
+export declare function readPostgresScopeCatalog(client: PgQuery, scope: RowScope, describe: (client: PgQuery) => Promise<DatabaseSchema>): Promise<PostgresScopeCatalog>;

package/dist/adapters/scoped/postgresScopeCatalog.js

@@ -0,0 +1,117 @@
+/**
+ * The scope catalog on PostgreSQL.
+ *
+ * SQLite reads its physical metadata inside `BEGIN IMMEDIATE`, where nothing
+ * else can write, so what it attests is what the transaction will see until
+ * COMMIT. PostgreSQL has no such fence: DDL from another session commits
+ * under a READ COMMITTED transaction unless something holds a lock on the
+ * relation it touches. So the tables this scope may write are pinned first,
+ * with `LOCK TABLE … IN ROW EXCLUSIVE MODE` — the lock an UPDATE takes
+ * anyway, compatible with every ordinary reader and writer and in conflict
+ * with everything that would change what a write means: ALTER TABLE, CREATE
+ * TRIGGER, ADD FOREIGN KEY (on either side), CREATE INDEX, ENABLE ROW LEVEL
+ * SECURITY. The catalog is read *after* the pin, so drift that committed
+ * before it is what the attestation compares, and drift after it waits for
+ * this transaction to end.
+ *
+ * Only tables in the scope that the writer role may update are pinned. That
+ * is not a loophole: a table outside the scope is unreadable here (`WHERE
+ * 1 = 0`), and one the role cannot update cannot be written by it, locked
+ * for update, or have its rows held for a parent check — so it is never in
+ * `writable` and the guarantee it lacks is one it could not use.
+ *
+ * What is described is exactly what `introspect()` describes, on the leased
+ * writer inside the transaction, so the deployed catalog and this evidence
+ * differ only when the database does.
+ */
+import { POSTGRES_STYLE, Refusal } from '../adapter.js';
+import { captureScopeCatalog } from '../../shared/scopeCatalog.js';
+import { triggerNames } from './scopedTransaction.js';
+const refuse = () => {
+    throw new Refusal('PostgreSQL scoped transactions require a complete catalog and an ordinary table the writer may update.');
+};
+/** The adapter's own id convention: `schema.name`, or `name` in public. */
+function located(id) {
+    const dot = id.indexOf('.');
+    return dot === -1 ? { schema: 'public', name: id } : { schema: id.slice(0, dot), name: id.slice(dot + 1) };
+}
+const key = (at) => `${at.schema}.${at.name}`;
+/** Everything that decides whether a write to a relation means what the
+ * scope assumes: its kind, row security, and the presence of triggers,
+ * rules and policies — and whether this role may update it at all. */
+async function facts(client, targets) {
+    const result = new Map();
+    if (!targets.length)
+        return result;
+    const rows = await client.query(`SELECT n.nspname AS schema, c.relname AS name, c.relkind::text AS kind, c.relrowsecurity AS rls,
+            EXISTS (SELECT 1 FROM pg_trigger t WHERE t.tgrelid = c.oid AND NOT t.tgisinternal) AS triggers,
+            ARRAY(SELECT t.tgname::text FROM pg_trigger t WHERE t.tgrelid = c.oid AND NOT t.tgisinternal ORDER BY 1) AS trigger_names,
+            EXISTS (SELECT 1 FROM pg_rewrite r WHERE r.ev_class = c.oid) AS rules,
+            EXISTS (SELECT 1 FROM pg_policy p WHERE p.polrelid = c.oid) AS policies,
+            has_table_privilege(c.oid, 'UPDATE') AS updatable
+       FROM pg_class c
+       JOIN pg_namespace n ON n.oid = c.relnamespace
+       JOIN unnest($1::text[], $2::text[]) AS wanted(schema, name) ON wanted.schema = n.nspname AND wanted.name = c.relname`, [targets.map((target) => target.schema), targets.map((target) => target.name)]);
+    for (const row of rows.rows) {
+        if (typeof row.schema !== 'string' ||
+            typeof row.name !== 'string' ||
+            typeof row.kind !== 'string' ||
+            [row.rls, row.triggers, row.rules, row.policies, row.updatable].some((value) => typeof value !== 'boolean') ||
+            !Array.isArray(row.trigger_names) ||
+            row.trigger_names.some((name) => typeof name !== 'string') ||
+            result.has(key(row)))
+            return refuse();
+        result.set(key(row), row);
+    }
+    return result;
+}
+const lockable = (fact) => fact !== undefined && ['r', 'p'].includes(fact.kind) && fact.updatable;
+const clean = (fact) => !fact.rls && !fact.triggers && !fact.rules && !fact.policies;
+/** What makes a table unclean, as a refusal names it. */
+const unclean = (fact) => [fact.triggers ? triggerNames(fact.trigger_names) : '', fact.rules ? 'a rule' : '', fact.policies || fact.rls ? 'row-level security' : '']
+    .filter(Boolean)
+    .join(' and ');
+/** Call only on the leased writer inside its transaction, before any read of
+ * user data. The describe callback is the adapter's own introspection so the
+ * evidence has the same shape as the catalog the permissions were bound to. */
+export async function readPostgresScopeCatalog(client, scope, describe) {
+    try {
+        const wanted = Object.keys(scope).map(located);
+        const before = await facts(client, wanted);
+        const pinned = wanted.filter((target) => lockable(before.get(key(target))));
+        const relations = pinned.map((target) => `${POSTGRES_STYLE.quote(target.schema)}.${POSTGRES_STYLE.quote(target.name)}`);
+        if (pinned.length)
+            await client.query(`LOCK TABLE ${relations.join(', ')} IN ROW EXCLUSIVE MODE`);
+        const described = await describe(client);
+        const schema = captureScopeCatalog({ ...described, label: 'PostgreSQL scoped transaction', readAt: new Date().toISOString() });
+        const after = facts(client, schema.tables.map((table) => ({ schema: table.schema, name: table.name })));
+        const held = new Set(pinned.map(key));
+        const writable = new Set();
+        const blockedBy = new Map();
+        const locks = new Set();
+        for (const table of schema.tables) {
+            const fact = (await after).get(key(table));
+            // A relation the catalog listed a moment ago and cannot describe now
+            // was dropped under this transaction; nothing here may rely on it.
+            if (!fact || table.id !== key(table))
+                return refuse();
+            if (!lockable(fact))
+                continue;
+            locks.add(table.id);
+            // Writable means pinned: a table that became clean after the pin
+            // decision could be dirtied again before COMMIT, so it stays read-only.
+            if (held.has(table.id) && clean(fact) && !table.isView && table.columns.some((column) => column.primaryKey))
+                writable.add(table.id);
+            else if (!clean(fact))
+                blockedBy.set(table.id, unclean(fact));
+        }
+        return { schema, writable, ...(blockedBy.size ? { blockedBy } : {}), lockable: locks, pinned: relations };
+    }
+    catch (error) {
+        if (error instanceof Refusal)
+            throw error;
+        // A lock the role may not take, a vanished relation or unknown metadata
+        // cannot weaken the boundary; the failure aborts the transaction anyway.
+        return refuse();
+    }
+}

package/dist/adapters/scoped/scopedCommandOperations.d.ts

@@ -0,0 +1,5 @@
+/** Adapter-owned command queue capture and failure accounting within a scoped transaction. */
+import { type TransactionOperations } from '../adapter.js';
+/** Shared adapter queue boundary: capture before waiting; caught malformed or
+ * failed operations still poison the transaction. No writer escapes here. */
+export declare function scopedCommandInvoker(operations: TransactionOperations, scoped: boolean, command: boolean, runtime: (table: string) => boolean, verify?: () => void): <A, R>(input: A, work: (input: A) => Promise<R>, read?: boolean) => Promise<R>;

package/dist/adapters/scoped/scopedCommandOperations.js

@@ -0,0 +1,48 @@
+/** Adapter-owned command queue capture and failure accounting within a scoped transaction. */
+import { Refusal } from '../adapter.js';
+import { snapshotScopedData } from './scopedReads.js';
+/** Shared adapter queue boundary: capture before waiting; caught malformed or
+ * failed operations still poison the transaction. No writer escapes here. */
+export function scopedCommandInvoker(operations, scoped, command, runtime, verify = () => { }) {
+    let failed = false;
+    /* `read`: the work only reads, so on a transaction that sends together it may start beside reads in flight
+       (TransactionOperations.read); a failure still poisons every operation after it, in the order asked. */
+    return (input, work, read = false) => {
+        let captured = input;
+        let invalid;
+        if (scoped) {
+            try {
+                captured = snapshotScopedData(input);
+            }
+            catch (error) {
+                invalid = { error };
+            }
+        }
+        const job = async () => {
+            if (scoped && failed)
+                throw new Refusal('This scoped transaction has failed.');
+            try {
+                if (invalid)
+                    throw invalid.error;
+                verify();
+                if (command &&
+                    scoped &&
+                    captured &&
+                    typeof captured === 'object' &&
+                    'table' in captured &&
+                    typeof captured.table === 'string' &&
+                    runtime(captured.table)) {
+                    throw new Refusal('Reserved resources are runtime-only.');
+                }
+                const result = await work(captured);
+                verify();
+                return result;
+            }
+            catch (error) {
+                failed = true;
+                throw error;
+            }
+        };
+        return read ? operations.read(job) : operations.run(job);
+    };
+}

package/dist/adapters/scoped/scopedReads.d.ts

@@ -0,0 +1,20 @@
+import { type QueryResult, type ScopedReads, type SqlFragment, type SqlStyle } from '../adapter.js';
+import { type DatabaseSchema } from '../../shared/schema.js';
+import { type RowScope } from '../../shared/rowScope.js';
+/** Structured read arguments must not retain mutable values across driver
+ * waits. This is deliberately separate from stricter nonempty policy filters:
+ * an empty user filter is fine, because it never replaces the bound policy. */
+export declare function snapshotScopedData<T>(input: T): T;
+/** Dialect-independent policy binding. The driver only executes compiler output
+ * on its existing read handle; consumers never receive that execute function.
+ * Snapshot the trusted catalog too, so a later refresh cannot change the
+ * graph/columns against which this capability was bound — except a catalog
+ * `captureScopeCatalog` already detached and deeply froze, which nothing can
+ * change: a tenant source binds a reader per operation over one of those, and
+ * copying it each time cost milliseconds per read on a wide catalog.
+ */
+export declare function createScopedReads(catalog: DatabaseSchema, input: RowScope, style: SqlStyle, 
+/** Execution formatting only: it never changes the compiled statement or scope. */
+execute: (statement: SqlFragment, hint?: {
+    binary?: true;
+}) => Promise<QueryResult>): ScopedReads;

package/dist/adapters/scoped/scopedReads.js

@@ -0,0 +1,174 @@
+import { buildWhere, clampLimit, orderClause, clampOffset, countStatement, Refusal, } from '../adapter.js';
+import { findTable } from '../../shared/schema.js';
+import { COUNT_EACH_MAX, countEachRows } from '../../shared/reads.js';
+import { isCapturedScopeCatalog } from '../../shared/scopeCatalog.js';
+import { ScopedRelations, snapshotRowScope } from '../../shared/rowScope.js';
+import { compileView, compileViewCount } from '../../shared/view.js';
+import { compileBreakdown, compileBreakdownCount } from '../../shared/breakdown.js';
+/** Structured read arguments must not retain mutable values across driver
+ * waits. This is deliberately separate from stricter nonempty policy filters:
+ * an empty user filter is fine, because it never replaces the bound policy. */
+export function snapshotScopedData(input) {
+    let nodes = 0;
+    let characters = 0;
+    let bytes = 0;
+    const fail = () => {
+        throw new Refusal('Invalid structured operation.');
+    };
+    const copy = (value, depth = 0) => {
+        if (++nodes > 32_768 || depth > 16)
+            return fail();
+        if (value === undefined || value === null || typeof value === 'boolean')
+            return value;
+        if (typeof value === 'string') {
+            characters += value.length;
+            if (characters > 1_048_576)
+                return fail();
+            return value;
+        }
+        if (typeof value === 'number' && Number.isFinite(value))
+            return value;
+        // A file's bytes: copied, and bounded as the characters are (the largest upload an App may accept).
+        if (value instanceof Uint8Array && (Object.getPrototypeOf(value) === Uint8Array.prototype || Buffer.isBuffer(value))) {
+            bytes += value.byteLength;
+            if (bytes > 26_214_400)
+                return fail();
+            return Buffer.from(value);
+        }
+        if (typeof value !== 'object')
+            return fail();
+        const array = Array.isArray(value);
+        const proto = Object.getPrototypeOf(value);
+        if (array ? proto !== Array.prototype : proto !== Object.prototype && proto !== null)
+            return fail();
+        const keys = Reflect.ownKeys(value);
+        if (keys.length > 8193)
+            return fail();
+        if (array) {
+            const length = Object.getOwnPropertyDescriptor(value, 'length')?.value;
+            if (!Number.isInteger(length) || length > 8192 || keys.length !== length + 1)
+                return fail();
+            const result = [];
+            for (let i = 0; i < length; i++) {
+                const descriptor = Object.getOwnPropertyDescriptor(value, String(i));
+                if (!descriptor || !descriptor.enumerable || !('value' in descriptor))
+                    return fail();
+                result.push(copy(descriptor.value, depth + 1));
+            }
+            return result;
+        }
+        const result = Object.create(null);
+        for (const key of keys) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (typeof key !== 'string' || !descriptor.enumerable || !('value' in descriptor))
+                return fail();
+            characters += key.length;
+            if (characters > 1_048_576)
+                return fail();
+            result[key] = copy(descriptor.value, depth + 1);
+        }
+        return result;
+    };
+    return copy(input);
+}
+/** Dialect-independent policy binding. The driver only executes compiler output
+ * on its existing read handle; consumers never receive that execute function.
+ * Snapshot the trusted catalog too, so a later refresh cannot change the
+ * graph/columns against which this capability was bound — except a catalog
+ * `captureScopeCatalog` already detached and deeply froze, which nothing can
+ * change: a tenant source binds a reader per operation over one of those, and
+ * copying it each time cost milliseconds per read on a wide catalog.
+ */
+export function createScopedReads(catalog, input, style, 
+/** Execution formatting only: it never changes the compiled statement or scope. */
+execute) {
+    const schema = isCapturedScopeCatalog(catalog) ? catalog : structuredClone(catalog);
+    const scope = snapshotRowScope(schema, input);
+    const tableFor = (id) => {
+        const table = findTable(schema, id);
+        if (!table)
+            throw new Refusal('Unknown resource in scoped read.');
+        return table;
+    };
+    const from = (id, filter) => {
+        const table = tableFor(id);
+        const column = (name) => {
+            if (!table.columns.some((column) => column.name === name))
+                throw new Refusal('Unknown column in scoped read.');
+            return style.quote(name);
+        };
+        const relations = new ScopedRelations(schema, style, scope);
+        const relation = relations.table(id);
+        const prefix = relations.finish();
+        const where = buildWhere(filter, style, prefix.params.length + 1, column);
+        return { table, column, relation, prefix, where, params: [...prefix.params, ...where.params] };
+    };
+    const counted = async (statement) => {
+        const result = await execute(statement);
+        return Number(result.rows[0]?.n ?? 0);
+    };
+    return Object.freeze({
+        async query(input) {
+            const request = snapshotScopedData(input);
+            const plan = from(request.table, request.filter);
+            const names = request.columns?.length ? request.columns : plan.table.columns.map((column) => column.name);
+            const columns = names.map(plan.column);
+            const order = orderClause(request.orderBy, plan.table, style, plan.params.length + 1, plan.column);
+            const n = plan.params.length + order.params.length;
+            const text = `${plan.prefix.text}SELECT ${columns.join(', ')} FROM ${plan.relation}${plan.where.text}${order.text}` +
+                ` LIMIT ${style.placeholder(n + 1)} OFFSET ${style.placeholder(n + 2)}`;
+            const result = await execute({ text, params: [...plan.params, ...order.params, clampLimit(request.limit), clampOffset(request.offset)] }, request.binary ? { binary: true } : undefined);
+            return { ...result, columns: [...names] };
+        },
+        async count(table, filter, limit) {
+            const plan = from(table, snapshotScopedData(filter));
+            // One plan either way: a bound wraps the scoped relation, never replaces it.
+            return counted({ text: `${plan.prefix.text}${countStatement(`${plan.relation}${plan.where.text}`, limit)}`, params: plan.params });
+        },
+        /* Several tables' counts, each under its own scope and filter, as one
+           statement: the scope's CTEs are defined once, ahead of one bounded
+           count per item joined by UNION ALL. Each branch reads the relation
+           `count` would, so no item sees a row its own count would not. */
+        async countEach(items, limit) {
+            const given = snapshotScopedData(items);
+            if (!given.length || given.length > COUNT_EACH_MAX)
+                throw new Refusal(`One statement counts 1 to ${COUNT_EACH_MAX} things.`);
+            const relations = new ScopedRelations(schema, style, scope);
+            const planned = given.map((item) => {
+                const table = tableFor(item.table);
+                const column = (name) => {
+                    if (!table.columns.some((column) => column.name === name))
+                        throw new Refusal('Unknown column in scoped read.');
+                    return style.quote(name);
+                };
+                return { relation: relations.table(item.table), column, filter: item.filter };
+            });
+            const prefix = relations.finish();
+            const params = [...prefix.params];
+            const branches = planned.map(({ relation, column, filter }, i) => {
+                const where = buildWhere(filter, style, params.length + 1, column);
+                params.push(...where.params);
+                const counted = countStatement(`${relation}${where.text}`, limit);
+                return counted.replace(/^SELECT COUNT\(\*\) AS n/, `SELECT ${i} AS i, COUNT(*) AS n`);
+            });
+            const result = await execute({ text: `${prefix.text}${branches.join('\nUNION ALL\n')}`, params });
+            return countEachRows(result.rows, given.length);
+        },
+        async runView(view, offset = 0) {
+            const compiled = compileView(schema, snapshotScopedData(view), style, offset, scope);
+            const result = await execute(compiled);
+            return { ...result, columns: compiled.columns.map((column) => column.name), resolved: compiled.columns, joins: compiled.joins };
+        },
+        async countView(view, limit) {
+            return counted(compileViewCount(schema, snapshotScopedData(view), style, scope, limit));
+        },
+        async runBreakdown(breakdown, offset = 0) {
+            const compiled = compileBreakdown(schema, snapshotScopedData(breakdown), style, offset, scope);
+            const result = await execute(compiled);
+            return { ...result, columns: compiled.columns.map((column) => column.name), resolved: compiled.columns };
+        },
+        async countBreakdown(breakdown, limit) {
+            return counted(compileBreakdownCount(schema, snapshotScopedData(breakdown), style, scope, limit));
+        },
+    });
+}