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

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

@@ -0,0 +1,89 @@
+import { Refusal, type Filter, type ScopedReads, type WriteTransaction } from '../adapter.js';
+import type { RowScope } from '../../shared/rowScope.js';
+import type { DatabaseSchema, TableMeta } from '../../shared/schema.js';
+/** Physical metadata read on the writer inside its own transaction. `writable`
+ * names the tables this scope may mutate; everything else stays in the graph
+ * so a hidden dependent cannot vanish from the FK checks. */
+export interface ScopeCatalog {
+    schema: DatabaseSchema;
+    writable: ReadonlySet<string>;
+    /** What in the database keeps a table out of `writable`, named where it can be: its triggers, and on PostgreSQL its
+     * rules, policies or row security. A refusal says it, so the owner knows what to drop or move. */
+    blockedBy?: ReadonlyMap<string, string>;
+}
+/** A table's triggers as a refusal names them: `the trigger "audit_order"`, `the triggers "a", "b"`. */
+export declare const triggerNames: (names: readonly string[]) => string;
+/** Row locks taken on the writer before a guard read, for engines whose
+ * transaction does not already exclude every other writer. SQLite passes
+ * none: `BEGIN IMMEDIATE` is the lock. Each receives the physical table and
+ * the complete-key (target) or parent-key (parent) filter. */
+interface ScopeRowLocks {
+    target(table: TableMeta, filter: Filter): Promise<void>;
+    parent(table: TableMeta, filter: Filter): Promise<void>;
+    /**
+     * Run `ride` the moment the update of `table` is sent, so the read that
+     * proves the row still in scope leaves behind it in the same round trip
+     * (postgresTransactionHandle.ts behindWrite). Answers a withdraw, true when
+     * `ride` never ran; undefined where reads are not sent behind a write.
+     */
+    behind?(table: TableMeta, ride: () => void): (() => boolean) | undefined;
+    /**
+     * Whether statements asked without waiting leave together (a writer that
+     * pipelines, postgresPool.ts). A row's lock and the guard read behind it,
+     * and every parent's lock and count, are then sent at once, in the order
+     * they would have been asked one by one, and judged in that order when the
+     * flight is answered: the server still grants each lock before it runs the
+     * read behind it, so each read is as fresh as it was a round trip later.
+     * Elsewhere each is asked once the one before it is answered.
+     */
+    readonly together?: boolean;
+}
+/**
+ * The outer bound a command's scope sits inside, when its host has one: a
+ * tenant's rows within the command's footprint, whatever the member's own
+ * row policy narrows (tenantWriteKindMember.ts). `reads` reads under it, and
+ * `whole` names the tables where the principal's scope is the bound itself —
+ * nothing within the bound is hidden from it there.
+ *
+ * Two checks are judged against it, and only these:
+ * - a command's insert may land on a row the principal cannot read, so long
+ *   as it lands inside the bound; it is answered its key and the values it
+ *   wrote, never the stored row (a requester's rating opens a desk-only
+ *   follow-up);
+ * - a delete of a row others reference is no longer refused outright: once
+ *   the row is locked, every table that references it must be `whole` and
+ *   hold no row referencing it at all, counted on the writer itself across
+ *   every row of that table — so a cascade can never reach a row anyone hid.
+ */
+export interface ScopeBound {
+    readonly reads: Pick<ScopedReads, 'query' | 'count'>;
+    readonly whole: ReadonlySet<string>;
+}
+/** The tables where `scope` is exactly `bound`, and the bound admits rows at all: nothing in it is hidden there. */
+export declare function wholeWithin(scope: Readonly<Record<string, unknown>>, bound: Readonly<Record<string, unknown>>): ReadonlySet<string>;
+/** A bound names exactly the scope's tables: it bounds that scope, never another. */
+export declare function sameTables(scope: Readonly<Record<string, unknown>>, bound: Readonly<Record<string, unknown>>): boolean;
+/** A write the row scope refuses: for good, for this request — outside the principal's rows, off the footprint, on a
+ * table it cannot bound. Its own class so the executor can say it as forbidden rather than as a while (503); the
+ * words stay value-free, the reason recorded beneath them for the owner. */
+export declare class ScopeRefusal extends Refusal {
+}
+/**
+ * The principal's scope and the reads it compiles to, for a transaction that
+ * may create a parent and then its children. A scope is resolved before the
+ * transaction begins, so a child rule that names its parents by key (`request_id
+ * in [...]`) cannot name a parent this transaction made: a resident filing a
+ * repair with its first message was refused the message. Rows this transaction
+ * inserted inside the principal's rows join those key lists for the rest of the
+ * transaction — every other condition of the child's rule still holds, a rule
+ * of `false` stays false, and a parent anyone else made gains nothing.
+ */
+export interface ScopeOwnRows {
+    readonly scope: RowScope;
+    readonly reads: (scope: RowScope, guard: boolean) => Pick<ScopedReads, 'query' | 'count'>;
+}
+/** Runs INSIDE a single queued operation. The supplied guards retain actual
+ * stored scalar types, not display conversions (a blob label is not a key).
+ * This capability deliberately refuses side effects it cannot bound. */
+export declare function createScopedTransaction(catalog: ScopeCatalog, records: WriteTransaction, reads: Pick<ScopedReads, 'query' | 'count'>, guards: Pick<ScopedReads, 'query' | 'count'>, locks?: ScopeRowLocks, bound?: ScopeBound, own?: ScopeOwnRows): WriteTransaction;
+export {};

package/dist/adapters/scoped/scopedTransaction.js

@@ -0,0 +1,303 @@
+import { Refusal } from '../adapter.js';
+import { recordRefusalCause } from '../../shared/refusal.js';
+/** A table's triggers as a refusal names them: `the trigger "audit_order"`, `the triggers "a", "b"`. */
+export const triggerNames = (names) => `the trigger${names.length === 1 ? '' : 's'} ${names.map((name) => JSON.stringify(name)).join(', ')}`;
+/** The tables where `scope` is exactly `bound`, and the bound admits rows at all: nothing in it is hidden there. */
+export function wholeWithin(scope, bound) {
+    return new Set(Object.keys(bound).filter((table) => bound[table] !== false && Object.hasOwn(scope, table) && JSON.stringify(scope[table]) === JSON.stringify(bound[table])));
+}
+/** A bound names exactly the scope's tables: it bounds that scope, never another. */
+export function sameTables(scope, bound) {
+    const tables = Object.keys(scope);
+    return tables.length === Object.keys(bound).length && tables.every((table) => Object.hasOwn(bound, table));
+}
+/* The caller hears one sentence, whatever the rule: which row a scope hides,
+   and that it exists, is what the scope keeps. The rule and the row are
+   recorded for the operator (shared/refusal.ts) — a command that failed here
+   used to answer a bare 503 with nothing anywhere saying which check it was. */
+/** A write the row scope refuses: for good, for this request — outside the principal's rows, off the footprint, on a
+ * table it cannot bound. Its own class so the executor can say it as forbidden rather than as a while (503); the
+ * words stay value-free, the reason recorded beneath them for the owner. */
+export class ScopeRefusal extends Refusal {
+}
+const refuse = (reason) => {
+    throw recordRefusalCause(new ScopeRefusal('This operation is not available in the current row scope.'), reason);
+};
+const keyText = (key) => Object.entries(key)
+    .map(([column, value]) => `${column} ${JSON.stringify(value)}`)
+    .join(', ');
+const comparable = (value) => typeof value === 'string' || (typeof value === 'number' && Number.isFinite(value));
+/** `scope` with each child rule's key conditions on a reference to a table in `made` extended by those rows' keys. */
+function withOwnRows(schema, scope, made) {
+    const out = { ...scope };
+    for (const [table, rule] of Object.entries(scope)) {
+        if (typeof rule !== 'object')
+            continue;
+        const extra = new Map();
+        for (const fk of schema.foreignKeys) {
+            // A composite reference is named by no single condition: it is left as the policy said it.
+            if (fk.from.table !== table || fk.from.columns.length !== 1)
+                continue;
+            const rows = made.get(fk.to.table);
+            if (!rows?.length)
+                continue;
+            const values = rows.map((row) => row[fk.to.columns[0]]).filter(comparable);
+            if (values.length)
+                extra.set(fk.from.columns[0], [...(extra.get(fk.from.columns[0]) ?? []), ...values]);
+        }
+        if (!extra.size)
+            continue;
+        out[table] = {
+            ...rule,
+            groups: rule.groups.map((group) => group.map((condition) => {
+                const added = extra.get(condition.column);
+                if (!added || condition.other !== undefined || condition.any !== undefined)
+                    return condition;
+                if (condition.op === '=' && comparable(condition.value))
+                    return { ...condition, op: 'in', value: [condition.value, ...added] };
+                if (condition.op === 'in' && Array.isArray(condition.value))
+                    return { ...condition, value: [...condition.value, ...added] };
+                return condition;
+            })),
+        };
+    }
+    return out;
+}
+/** Runs INSIDE a single queued operation. The supplied guards retain actual
+ * stored scalar types, not display conversions (a blob label is not a key).
+ * This capability deliberately refuses side effects it cannot bound. */
+export function createScopedTransaction(catalog, records, reads, guards, locks, bound, own) {
+    /* The rows this transaction inserted inside the principal's rows, by table, and the reads that count them in
+       (ScopeOwnRows). Rebuilt on each such insert; until the first, the reads are the ones resolved for the request. */
+    const made = new Map();
+    const madeBy = (table, row) => {
+        if (!own)
+            return;
+        made.set(table.id, [...(made.get(table.id) ?? []), row]);
+        const scope = withOwnRows(catalog.schema, own.scope, made);
+        reads = own.reads(scope, false);
+        guards = own.reads(scope, true);
+    };
+    const target = (id) => {
+        const table = catalog.schema.tables.find((table) => table.id === id);
+        if (!table)
+            return refuse(`"${id}" is not in this write's footprint: a command writes only the tables it declares.`);
+        if (!catalog.writable.has(id)) {
+            /* A trigger writes what no row policy bounds, so a scoped write never fires one: name it, or the owner is left
+               guessing why a table they declared written is not. */
+            const by = catalog.blockedBy?.get(id);
+            return refuse(by
+                ? `"${id}" cannot be written under a row policy: it has ${by}, whose writes the policy cannot bound.`
+                : `"${id}" is read-only in this scope: the command does not declare it written, or the principal's rows do not admit writing it.`);
+        }
+        if (!table.columns.some((column) => column.primaryKey))
+            return refuse(`"${id}" has no primary key, so a scoped write cannot prove which row it changed.`);
+        return table;
+    };
+    const keyFilter = (table, key) => {
+        const pk = table.columns.filter((column) => column.primaryKey).map((column) => column.name);
+        if (!key || Object.keys(key).length !== pk.length || !pk.every((column) => Object.hasOwn(key, column) && comparable(key[column]))) {
+            return refuse(`A key for "${table.id}" names exactly its primary key (${pk.join(', ')}), each a text or a number.`);
+        }
+        return { groups: [pk.map((column) => ({ column, op: '=', value: key[column] }))] };
+    };
+    /* A row by its key, read after its lock. Lock before looking: the guard's
+       snapshot is then the row no other writer can move until this transaction
+       ends, so what the scope checks is what the write will change. Where the
+       writer sends together, the read leaves right behind the lock, in its
+       flight; the server runs it only once the lock is granted. */
+    const lockedRead = async (table, filter, within) => {
+        const locked = locks?.target(table, filter);
+        const read = () => within.query({ table: table.id, filter, limit: 2, offset: 0 });
+        if (!locks?.together) {
+            await locked;
+            return read();
+        }
+        const sent = read();
+        // Both heard before either is judged: the lock's failure, if it failed, is the one said.
+        await Promise.allSettled([locked, sent]);
+        await locked;
+        return sent;
+    };
+    const one = (table, key, result) => {
+        if (result.rows.length !== 1) {
+            return refuse(`The "${table.id}" row ${keyText(key)} is outside the principal's rows: the row policy (or tenant) does not admit it, before or after this write.`);
+        }
+        const row = result.rows[0];
+        // Null / opaque / nonportable keys cannot prove stored-row identity.
+        keyFilter(table, Object.fromEntries(table.columns.filter((column) => column.primaryKey).map((column) => [column.name, row[column.name]])));
+        return row;
+    };
+    const stored = async (table, key, within = guards) => one(table, key, await lockedRead(table, keyFilter(table, key), within));
+    /* Every reference a write makes must land on a row the principal reads:
+       all of a new row's, and of an updated row only those whose columns the
+       update sets. A reference the update leaves as it was is not this write's
+       to vouch for — it was made before, and refusing over it refused every
+       edit of a row whose unrelated parent (a lender's relationship manager on
+       a dealer) lies outside the scope, while telling the caller that it does.
+  
+       Each reference is checked by its parent's lock, then that parent's count
+       under the principal's rows; a reference that cannot be checked ends the
+       list, refused there, so the checks before it still speak first. */
+    const parentChecks = (table, row, set) => {
+        const checks = [];
+        for (const fk of catalog.schema.foreignKeys.filter((fk) => fk.from.table === table.id && (!set || fk.from.columns.some((column) => set.has(column))))) {
+            const values = fk.from.columns.map((column) => row[column]);
+            if (values.some((value) => value === null))
+                continue;
+            if (!values.every(comparable)) {
+                checks.push({ refused: `"${table.id}".${fk.from.columns.join('+')} holds a value that is not a text or a number.` });
+                break;
+            }
+            // Parent columns stay on the SQL left-hand side so SQLite's parent
+            // affinity and collation, rather than JavaScript equality, decide.
+            const filter = {
+                groups: [fk.to.columns.map((column, index) => ({ column, op: '=', value: values[index] }))],
+            };
+            const parent = catalog.schema.tables.find((table) => table.id === fk.to.table);
+            if (!parent) {
+                checks.push({
+                    refused: `"${table.id}" references "${fk.to.table}", which is not in this write's footprint: declare it read by the command.`,
+                });
+                break;
+            }
+            checks.push({ fk, values, filter, parent });
+        }
+        return checks;
+    };
+    const unseen = (check) => `"${check.fk.from.table}".${check.fk.from.columns.join('+')} points at the "${check.fk.to.table}" row ${keyText(Object.fromEntries(check.fk.to.columns.map((column, index) => [column, check.values[index]])))}, which the principal's rows do not include (or the command does not declare "${check.fk.to.table}" read).`;
+    /** The checks sent at once (locks.together): each parent's lock, then its count, every answer heard. */
+    const ask = (checks) => checks.map((check) => {
+        if ('refused' in check)
+            return check;
+        const locked = locks?.parent(check.parent, check.filter) ?? Promise.resolve();
+        const counted = guards.count(check.fk.to.table, check.filter);
+        locked.catch(() => { });
+        counted.catch(() => { });
+        return { ...check, locked, counted };
+    });
+    /* Checks asked ahead of the row they are for (built from what the write
+       returned, or from what an update sets), used only where they name exactly
+       the references the row as stored holds: the same statements, sent sooner. */
+    const sameChecks = (asked, checks) => asked.length === checks.length &&
+        asked.every((guess, index) => {
+            const check = checks[index];
+            if ('refused' in guess || 'refused' in check)
+                return 'refused' in guess && 'refused' in check && guess.refused === check.refused;
+            return guess.fk === check.fk && guess.values.every((value, at) => value === check.values[at]);
+        });
+    const parents = async (table, row, set, guessed) => {
+        const checks = parentChecks(table, row, set);
+        if (!locks?.together) {
+            for (const check of checks) {
+                if ('refused' in check)
+                    return refuse(check.refused);
+                // A parent's visibility must hold until commit, not just at this read.
+                await locks?.parent(check.parent, check.filter);
+                if ((await guards.count(check.fk.to.table, check.filter)) !== 1)
+                    return refuse(unseen(check));
+            }
+            return;
+        }
+        const asked = guessed && sameChecks(guessed, checks) ? guessed : ask(checks);
+        // Every answer is heard before any is judged: nothing is left in flight behind a refusal.
+        await Promise.allSettled(asked.flatMap((check) => ('refused' in check ? [] : [check.locked, check.counted])));
+        for (const check of asked) {
+            if ('refused' in check)
+                return refuse(check.refused);
+            await check.locked;
+            if ((await check.counted) !== 1)
+                return refuse(unseen(check));
+        }
+    };
+    return Object.freeze({
+        query: (request) => reads.query(request),
+        count: (table, filter) => reads.count(table, filter),
+        async insert(request) {
+            const table = target(request.table);
+            const result = await records.insert(request);
+            const filter = keyFilter(table, result.key);
+            /* The new row locked and read back, and where the writer sends together
+               its references checked in the same flight, from the row the INSERT
+               returned (parents uses them only where the stored row holds exactly
+               those). No other transaction can see this row yet, so its lock is
+               granted at once and the read answers what a count before it would. */
+            const read = lockedRead(table, filter, guards);
+            const guessed = locks?.together && result.row ? ask(parentChecks(table, result.row)) : undefined;
+            read.catch(() => { });
+            const found = await read;
+            // Inside the bound and outside the principal's rows: the command's own row, answered by its key and what it wrote.
+            if (bound && found.rows.length !== 1) {
+                await parents(table, await stored(table, result.key, bound.reads), undefined, guessed);
+                return { key: result.key, applied: result.applied, sql: result.sql };
+            }
+            const row = one(table, result.key, found);
+            await parents(table, row, undefined, guessed);
+            madeBy(table, row);
+            return result;
+        },
+        async update(request) {
+            const table = target(request.table);
+            const protectedColumns = new Set([
+                ...table.columns.filter((column) => column.primaryKey).map((column) => column.name),
+                ...catalog.schema.foreignKeys.filter((fk) => fk.to.table === table.id).flatMap((fk) => fk.to.columns),
+            ]);
+            const moved = Object.keys(request.values ?? {}).filter((column) => protectedColumns.has(column));
+            if (moved.length)
+                return refuse(`A scoped update may not change "${table.id}".${moved.join(', ')}: a key, or a column another table references.`);
+            const before = await stored(table, request.key);
+            const set = new Set(Object.keys(request.values ?? {}));
+            /* The row read again after the write, sent the moment the write is: it
+               reads what the write wrote, and leaves in the write's round trip, with
+               the references the write sets checked behind it, as the row will hold
+               them. A write that fails aborts them too, and the write's failure is
+               the one thrown. */
+            const after = {};
+            const withdraw = locks?.behind?.(table, () => {
+                after.row = stored(table, request.key);
+                after.row.catch(() => { });
+                if (locks.together)
+                    after.guessed = ask(parentChecks(table, { ...before, ...request.values }, set));
+            });
+            let result;
+            try {
+                result = await records.update(request);
+            }
+            finally {
+                withdraw?.();
+            }
+            if (result.affected !== 1)
+                return refuse(`The update of "${table.id}" changed ${result.affected} rows, not one.`);
+            await parents(table, await (after.row ?? stored(table, request.key)), set, after.guessed);
+            return result;
+        },
+        async remove(request) {
+            const table = target(request.table);
+            const children = catalog.schema.foreignKeys.filter((fk) => fk.to.table === table.id);
+            const hidden = children.find((fk) => !bound?.whole.has(fk.from.table));
+            if (hidden)
+                return refuse(`A scoped command may not delete from "${table.id}": "${hidden.from.table}" references it, and a hidden row might.`);
+            const row = await stored(table, request.key);
+            /* Locked first (stored), so no reference can be made to it while these
+               are counted: across every row of each table, on the writer itself,
+               since the principal sees every row the bound holds there and a row
+               outside the bound pointing in is the one a cascade must never reach. */
+            for (const fk of children) {
+                const values = fk.to.columns.map((column) => row[column]);
+                if (values.some((value) => value === null))
+                    continue;
+                if (!values.every(comparable))
+                    return refuse(`"${table.id}".${fk.to.columns.join('+')} holds a value that is not a text or a number.`);
+                const filter = {
+                    groups: [fk.from.columns.map((column, index) => ({ column, op: '=', value: values[index] }))],
+                };
+                if ((await records.count(fk.from.table, filter)) !== 0)
+                    return refuse(`A scoped command may not delete the "${table.id}" row ${keyText(request.key)}: "${fk.from.table}" still references it.`);
+            }
+            const result = await records.remove(request);
+            if (result.affected !== 1)
+                return refuse(`The delete from "${table.id}" removed ${result.affected} rows, not one.`);
+            return result;
+        },
+    });
+}

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

@@ -0,0 +1,16 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { type DatabaseSchema } from '../../shared/schema.js';
+import { type ScopeCatalog } from './scopedTransaction.js';
+export type SqliteScopeCatalog = ScopeCatalog;
+/** Call only on the writer inside BEGIN IMMEDIATE. No cached/public catalog,
+ * estimates or data scans: the lease's physical metadata is the authority.
+ * A non-writable table remains in the graph so hidden dependents cannot vanish.
+ */
+export declare function readSqliteScopeCatalog(db: DatabaseSync): SqliteScopeCatalog;
+/** Metadata-only read attestation inside the caller's owned snapshot. Exposes
+ * no writer eligibility. Keep every non-engine table and dependency, including
+ * private/unmapped objects, so an unknown business edge cannot disappear. */
+export declare function readSqliteReadCatalog(db: DatabaseSync): {
+    schema: DatabaseSchema;
+    readable: ReadonlySet<string>;
+};

package/dist/adapters/scoped/sqliteScopeCatalog.js

@@ -0,0 +1,241 @@
+import { ANSI_STYLE, Refusal } from '../adapter.js';
+import { chooseColumnReference, deleteRuleOf, } from '../../shared/schema.js';
+import { mapScopeCatalog } from '../../shared/scopeCatalog.js';
+import { triggerNames } from './scopedTransaction.js';
+/* `table_xinfo`'s hidden: 0 a plain column, 1 a virtual table's own (its module's plumbing), 2 and 3 generated
+   (virtual, stored). A generated column keeps its table in scope: it is computed from the row the policy or the
+   tenant predicate already bounds, so a scoped read reads it and a scoped write leaves it to the database (sqlite.ts
+   refuses writing one). */
+const generated = (column) => column.hidden === 2 || column.hidden === 3;
+// SQLite's built-in identifier matching folds ASCII, not arbitrary Unicode.
+const folded = (name) => name.replace(/[A-Z]/g, (char) => char.toLowerCase());
+const refuse = (cause) => {
+    throw new Refusal('SQLite scoped transactions require a complete, unambiguous catalog and enabled foreign keys.', cause === undefined ? {} : { cause });
+};
+// SQLite's primary result codes for an engine that could not answer, rather
+// than a catalog that is wrong: BUSY, LOCKED, NOMEM, INTERRUPT, IOERR, FULL,
+// CANTOPEN, PROTOCOL. Extended codes keep the primary code in the low byte.
+const UNAVAILABLE = new Set([5, 6, 7, 9, 10, 13, 14, 15]);
+function identities(items) {
+    const result = new Map();
+    for (const item of items) {
+        if (typeof item.name !== 'string' || !item.name || result.has(folded(item.name)))
+            return refuse();
+        result.set(folded(item.name), item);
+    }
+    return result;
+}
+/** Call only on the writer inside BEGIN IMMEDIATE. No cached/public catalog,
+ * estimates or data scans: the lease's physical metadata is the authority.
+ * A non-writable table remains in the graph so hidden dependents cannot vanish.
+ */
+export function readSqliteScopeCatalog(db) {
+    const { schema, writable, blockedBy } = scanSqliteScopeCatalog(db);
+    return { schema, writable, ...(blockedBy.size ? { blockedBy } : {}) };
+}
+/** Metadata-only read attestation inside the caller's owned snapshot. Exposes
+ * no writer eligibility. Keep every non-engine table and dependency, including
+ * private/unmapped objects, so an unknown business edge cannot disappear. */
+export function readSqliteReadCatalog(db) {
+    if (!db.isTransaction)
+        return refuse();
+    const { schema, readable } = scanSqliteScopeCatalog(db);
+    const ids = new Map(schema.tables.filter((table) => !folded(table.id).startsWith('sqlite_')).map((table) => [table.id, table.id]));
+    return { schema: mapScopeCatalog(schema, ids), readable };
+}
+function scanSqliteScopeCatalog(db) {
+    try {
+        if (db.prepare('PRAGMA foreign_keys').get()?.foreign_keys !== 1)
+            return refuse();
+        const entries = db
+            .prepare("SELECT name, type FROM main.sqlite_schema WHERE type IN ('table', 'view') ORDER BY name")
+            .all();
+        const listed = db.prepare('PRAGMA main.table_list').all();
+        // Unknown PRAGMAs can return nothing without throwing. Never interpret
+        // unavailable table-kind metadata as proof that a table is ordinary.
+        if (!listed.some((table) => table.schema === 'main' && table.name === 'sqlite_schema' && table.type === 'table'))
+            return refuse();
+        const kinds = identities(listed.filter((table) => table.schema === 'main'));
+        const blocked = new Set();
+        const triggered = new Map();
+        for (const namespace of ['main', 'temp']) {
+            const triggers = db
+                .prepare(`SELECT tbl_name AS name, name AS trigger FROM ${namespace}.sqlite_schema WHERE type = 'trigger' ORDER BY name`)
+                .all();
+            for (const trigger of triggers) {
+                if (typeof trigger.name !== 'string' || typeof trigger.trigger !== 'string')
+                    return refuse();
+                blocked.add(folded(trigger.name));
+                triggered.set(folded(trigger.name), [...(triggered.get(folded(trigger.name)) ?? []), trigger.trigger]);
+            }
+        }
+        const blockedBy = new Map();
+        const shadowed = new Set();
+        for (const table of db.prepare("SELECT name FROM temp.sqlite_schema WHERE type IN ('table', 'view')").all()) {
+            if (typeof table.name !== 'string')
+                return refuse();
+            blocked.add(folded(table.name));
+            shadowed.add(folded(table.name));
+        }
+        const tables = [];
+        const columnsByTable = new Map();
+        const writable = new Set();
+        const readable = new Set();
+        identities(entries);
+        for (const entry of entries) {
+            const kind = kinds.get(folded(entry.name));
+            if (!kind ||
+                kind.name !== entry.name ||
+                !['table', 'view', 'virtual', 'shadow'].includes(kind.type) ||
+                (entry.type === 'view') !== (kind.type === 'view'))
+                return refuse();
+            const columns = db.prepare(`PRAGMA main.table_xinfo(${ANSI_STYLE.quote(entry.name)})`).all();
+            identities(columns);
+            if (!columns.length || columns.length !== kind.ncol)
+                return refuse();
+            for (const [i, column] of columns.entries()) {
+                if (column.cid !== i ||
+                    typeof column.type !== 'string' ||
+                    !Number.isInteger(column.pk) ||
+                    column.pk < 0 ||
+                    ![0, 1].includes(column.notnull) ||
+                    ![0, 1, 2, 3].includes(column.hidden) ||
+                    (column.dflt_value !== null && typeof column.dflt_value !== 'string'))
+                    return refuse();
+            }
+            const primary = columns.filter((column) => column.pk > 0).sort((a, b) => a.pk - b.pk);
+            if (primary.some((column, i) => column.pk !== i + 1))
+                return refuse();
+            const indexes = db.prepare(`PRAGMA main.index_list(${ANSI_STYLE.quote(entry.name)})`).all();
+            // INTEGER PRIMARY KEY DESC has a PK index and is not a rowid alias.
+            const identity = kind.type === 'table' &&
+                kind.wr === 0 &&
+                primary.length === 1 &&
+                /^INTEGER$/i.test(primary[0].type.trim()) &&
+                !indexes.some((index) => index.origin === 'pk')
+                ? primary[0].name
+                : undefined;
+            tables.push({
+                id: entry.name,
+                name: entry.name,
+                schema: 'main',
+                isView: kind.type === 'view',
+                columns: columns.map((column) => ({
+                    name: column.name,
+                    type: column.type || (kind.type === 'view' ? '' : 'BLOB'),
+                    primaryKey: column.pk > 0,
+                    nullable: column.notnull === 0 && column.name !== identity && !(column.pk > 0 && (kind.wr === 1 || kind.strict === 1)),
+                    ...(column.dflt_value !== null ? { default: column.dflt_value } : {}),
+                    ...(column.name === identity ? { identity: 'by-default' } : {}),
+                    // The database computes a generated column from its row: read like any other, never written.
+                    ...(generated(column) ? { writable: false } : {}),
+                })),
+            });
+            columnsByTable.set(entry.name, columns);
+            if (kind.type === 'table' &&
+                !folded(entry.name).startsWith('sqlite_') &&
+                !blocked.has(folded(entry.name)) &&
+                columns.every((column) => column.hidden !== 1))
+                writable.add(entry.name);
+            const triggers = kind.type === 'table' ? triggered.get(folded(entry.name)) : undefined;
+            if (triggers)
+                blockedBy.set(entry.name, triggerNames(triggers));
+            if (kind.type === 'table' &&
+                !folded(entry.name).startsWith('sqlite_') &&
+                !shadowed.has(folded(entry.name)) &&
+                // A generated column is read like any other; a virtual table's own columns (hidden 1) are its module's.
+                columns.every((column) => column.hidden !== 1))
+                readable.add(entry.name);
+        }
+        const byName = identities(tables);
+        const foreignKeys = [];
+        for (const table of tables) {
+            const rows = db.prepare(`PRAGMA main.foreign_key_list(${ANSI_STYLE.quote(table.name)})`).all();
+            const groups = new Map();
+            for (const row of rows) {
+                if (!Number.isInteger(row.id) ||
+                    row.id < 0 ||
+                    !Number.isInteger(row.seq) ||
+                    row.seq < 0 ||
+                    typeof row.table !== 'string' ||
+                    typeof row.from !== 'string' ||
+                    (row.to !== null && typeof row.to !== 'string'))
+                    return refuse();
+                const group = groups.get(row.id) ?? [];
+                group.push(row);
+                groups.set(row.id, group);
+            }
+            const localColumns = identities(table.columns);
+            /* Every key a column sits in, judged together after the groups: one
+               column legitimately carries its own reference and its part in a
+               composite key (chooseColumnReference says which link a reader
+               follows, and which case is a contradiction). */
+            const candidates = new Map();
+            for (const [id, unordered] of groups) {
+                const group = unordered.sort((a, b) => a.seq - b.seq);
+                const first = group[0];
+                const parent = byName.get(folded(first.table));
+                const onDelete = deleteRuleOf(first.on_delete);
+                if (!parent ||
+                    kinds.get(folded(parent.name))?.type !== 'table' ||
+                    !onDelete ||
+                    !deleteRuleOf(first.on_update) ||
+                    group.some((row, i) => row.seq !== i ||
+                        folded(row.table) !== folded(first.table) ||
+                        row.on_delete !== first.on_delete ||
+                        row.on_update !== first.on_update))
+                    return refuse();
+                const parentColumns = identities(parent.columns);
+                const primary = columnsByTable
+                    .get(parent.id)
+                    .filter((column) => column.pk > 0)
+                    .sort((a, b) => a.pk - b.pk);
+                const implicit = first.to === null;
+                if (group.some((row) => (row.to === null) !== implicit) || (implicit && primary.length !== group.length))
+                    return refuse();
+                const from = group.map((row) => localColumns.get(folded(row.from))?.name ?? refuse());
+                const to = group.map((row, i) => (implicit ? primary[i].name : (parentColumns.get(folded(row.to))?.name ?? refuse())));
+                if (new Set(from).size !== from.length || new Set(to).size !== to.length)
+                    return refuse();
+                foreignKeys.push({
+                    name: `${table.name}_fk_${id}`,
+                    from: { table: table.id, columns: from },
+                    to: { table: parent.id, columns: to },
+                    onDelete,
+                });
+                for (const [i, name] of from.entries()) {
+                    const column = localColumns.get(folded(name));
+                    const listed = candidates.get(column.name) ?? [];
+                    listed.push({ reference: { table: parent.id, column: to[i] }, composite: group.length > 1 });
+                    candidates.set(column.name, listed);
+                }
+            }
+            for (const [name, listed] of candidates) {
+                const chosen = chooseColumnReference(listed);
+                // This is the attesting path, so a contradiction refuses the catalog.
+                // The adapter's own describe keeps the same verdict and shows no link
+                // instead: see chooseColumnReference for why the two differ.
+                if (chosen.kind === 'conflict')
+                    return refuse();
+                if (chosen.kind === 'one')
+                    localColumns.get(folded(name)).references = chosen.reference;
+            }
+        }
+        return {
+            schema: { dialect: 'sqlite', label: 'SQLite scoped transaction', readAt: new Date().toISOString(), tables, foreignKeys },
+            writable,
+            readable,
+            blockedBy,
+        };
+    }
+    catch (error) {
+        if (error instanceof Refusal)
+            throw error;
+        // Missing/broken objects and unknown metadata cannot weaken the boundary.
+        // Refused either way; a busy or failing engine is kept as the cause.
+        const { code, errcode } = (error ?? {});
+        if (code === 'ERR_SQLITE_ERROR' && typeof errcode === 'number' && UNAVAILABLE.has(errcode & 0xff))
+            return refuse(error);
+        return refuse();
+    }
+}

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

@@ -0,0 +1,3 @@
+import { type SqlFragment, type SqlStyle, type UpdateRequest } from '../adapter.js';
+/** Appended to a complete primary-key WHERE, with values bound after its parameters. */
+export declare function buildUpdateGuard(request: UpdateRequest, types: Record<string, string>, style: SqlStyle, dialect: 'sqlite' | 'postgres', startIndex: number): SqlFragment;