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

package/dist/server/journal.js

@@ -0,0 +1,398 @@
+/**
+ * What was written, and how to put it back.
+ *
+ * Transactions protect a call from failing *halfway*. They do nothing at all
+ * about a call that succeeded and should not have — which is the failure mode
+ * that actually happens when an agent has write access: nothing errored,
+ * nothing rolled back, and the row is simply wrong now. Every destructive
+ * label in the tool surface warns about that and none of them helped after
+ * the fact.
+ *
+ * So every write that lands is recorded with what it would take to undo it,
+ * and `revert` undoes the last one. The browser has had an undo for its own
+ * edits since write mode shipped; this is the same idea one door out, covering
+ * the writes an agent makes as well, and covering inserts and deletes, which
+ * that one never did.
+ *
+ * Three things it deliberately does not do.
+ *
+ * It is **not persisted**. The browser's undo stack makes this argument and it
+ * is the right one: a stack that outlives the process invites undoing
+ * something from an hour ago, by which time the row has very likely moved on
+ * and the "undo" is an overwrite wearing a friendly name. In-session is the
+ * honest scope.
+ *
+ * It **checks before it writes**. Putting the old value back over a newer one
+ * is not an undo, it is a silent overwrite — so the row is re-read first and
+ * the revert refused if it no longer holds what this journal put there. An
+ * undo that can quietly destroy someone else's edit is worse than no undo.
+ *
+ * And it **does not pretend about SQL**. A `runSql` write is recorded so the
+ * history is complete, and marked unrevertible with the reason: arbitrary SQL
+ * has no general inverse, and guessing one is how a safety net becomes the
+ * thing that cut you.
+ */
+import { Refusal, TransactionOutcomeUnknown, WriteConflict, } from '../adapters/adapter.js';
+import { snapshotScopedData } from '../adapters/scoped/scopedReads.js';
+/** Enough to walk back a mistake, not a session. Matches the browser's depth. */
+const DEPTH = 50;
+/* Per connection: a write on staging is not undoable on production, and a
+   single stack would offer exactly that. */
+const journals = new Map();
+let nextId = 1;
+const entriesFor = (connection) => {
+    if (!journals.has(connection))
+        journals.set(connection, []);
+    return journals.get(connection);
+};
+/** Record a write that landed. Returns the entry, mostly for tests. */
+export function recordWrite(connection, entry) {
+    const full = {
+        id: nextId++,
+        connection,
+        at: new Date().toISOString(),
+        ...entry,
+    };
+    const list = entriesFor(connection);
+    list.push(full);
+    if (list.length > DEPTH)
+        list.shift();
+    return full;
+}
+/** The most recent first, which is the order anyone asks about them in. */
+export function history(connection, limit = 10) {
+    return [...entriesFor(connection)].reverse().slice(0, Math.max(1, limit));
+}
+/** The newest write that could still be undone, if there is one. */
+export function lastRevertible(connection) {
+    return latestRevertible([...entriesFor(connection)].reverse());
+}
+/** Entries are newest first. Never silently step past an unresolved Undo. */
+export function latestRevertible(entries) {
+    for (const entry of entries) {
+        if (entry.blocksUndo || entry.undoState === 'pending' || entry.undoState === 'unknown')
+            return undefined;
+        if (entry.revertible)
+            return entry;
+    }
+    return undefined;
+}
+export function forget(connection, id) {
+    const list = entriesFor(connection);
+    const at = list.findIndex((e) => e.id === id);
+    if (at !== -1)
+        list.splice(at, 1);
+}
+/** Testing seam: a fresh process is the normal state, and tests want it too. */
+export function clearJournal(connection) {
+    if (connection === undefined)
+        journals.clear();
+    else
+        journals.delete(connection);
+}
+/** Fail closed without publishing another entry (or consulting a clock). The
+ * caller supplies already verified ownership; no record values are introduced. */
+export function quarantineHistory(connection, owner) {
+    for (const entry of journals.get(connection) ?? []) {
+        if (owner && (entry.principal !== owner.principal || entry.app !== owner.app))
+            continue;
+        entry.revertible = false;
+        entry.undoState = 'unknown';
+        entry.reason = 'Newer write history could not be confirmed. Refresh and reconcile before further editing.';
+    }
+}
+const keyFilter = (key) => ({
+    groups: [
+        Object.entries(key).map(([column, value]) => ({
+            column,
+            op: '=',
+            value: value,
+        })),
+    ],
+});
+/** The row as it stands now, or undefined if it is gone. */
+async function currentRow(adapter, table, key) {
+    const result = await adapter.query({ table, filter: keyFilter(key), limit: 1, offset: 0 });
+    return result.rows[0];
+}
+/* Compared as strings, because a value that went through the database and came
+   back may be a different JavaScript type than the one that went in — SQLite
+   hands back an integer for a boolean, and a driver may widen a numeric. The
+   question is "is this still the value we wrote", not "is this the same
+   object". */
+const same = (a, b) => a === b || (a ?? null) === (b ?? null) || String(a ?? '') === String(b ?? '');
+/**
+ * Undo one recorded write.
+ *
+ * Every step is checked against the database before anything is written, and
+ * the whole revert is refused if any of them has moved on. Half an undo is
+ * worse than none: it leaves the row in a state neither the write nor the
+ * revert intended, and nothing recorded that it happened.
+ */
+export async function revert(adapter, connection, entry, errorMessage = (error) => error.message) {
+    // HTTP may pass a logical-resource projection, not the actual journal object.
+    // Gate by the canonical entry so stale copies cannot start a second attempt.
+    const canonical = entriesFor(connection).find((item) => item.id === entry.id);
+    if (!canonical || canonical.connection !== entry.connection) {
+        return { reverted: false, outcome: 'not_applied', entry, errors: ['This write is no longer available to undo.'] };
+    }
+    if (canonical.undoState) {
+        return {
+            reverted: false,
+            outcome: 'unknown',
+            entry,
+            errors: [canonical.undoState === 'pending' ? 'This Undo is already in progress. Do not retry it.' : undoUncertain],
+        };
+    }
+    if (canonical.blocksUndo || entry.blocksUndo || !canonical.revertible || !entry.revertible) {
+        return { reverted: false, outcome: 'not_applied', entry, errors: [canonical.reason ?? entry.reason ?? 'That write cannot be undone.'] };
+    }
+    if (!adapter.update || !adapter.insert || !adapter.remove || !adapter.transaction) {
+        return { reverted: false, outcome: 'not_applied', entry, errors: ['This connection cannot safely undo writes in one transaction.'] };
+    }
+    let owned;
+    try {
+        owned = snapshotScopedData(entry);
+        // Logical-resource projections may rename tables, but cannot weaken the
+        // canonical inverse contract by dropping its comparison markers.
+        if (canonical.steps.some((step) => step.wholeRow || step.exactFields)) {
+            if (owned.kind !== canonical.kind || owned.steps.length !== canonical.steps.length) {
+                throw new Refusal('This write has no complete inverse projection.');
+            }
+            owned.steps.forEach((step, index) => {
+                if (canonical.steps[index].wholeRow)
+                    step.wholeRow = true;
+                if (canonical.steps[index].exactFields)
+                    step.exactFields = true;
+            });
+        }
+    }
+    catch (error) {
+        return { reverted: false, outcome: 'not_applied', entry, errors: [errorMessage(error)] };
+    }
+    canonical.undoState = 'pending';
+    try {
+        const result = await revertOwned(adapter, connection, owned, errorMessage);
+        if (result.outcome === 'unknown') {
+            canonical.undoState = 'unknown';
+            canonical.revertible = false;
+            canonical.reason = undoUncertain;
+            Object.assign(owned, { undoState: 'unknown', revertible: false, reason: undoUncertain });
+        }
+        return result;
+    }
+    catch (error) {
+        // Mutation failures are classified in revertOwned. This is a preflight
+        // read failure: no inverse operation has entered its transaction yet.
+        return { reverted: false, outcome: 'not_applied', entry, errors: [errorMessage(error)] };
+    }
+    finally {
+        if (canonical.undoState === 'pending')
+            delete canonical.undoState;
+    }
+}
+const undoUncertain = 'The Undo outcome could not be confirmed. Refresh and reconcile the records; do not retry this Undo.';
+function scalarImage(image) {
+    // A display label might now be real text. Even SQL cannot recover the
+    // original type from that journal image, so refuse the ambiguous label too.
+    return Boolean(image &&
+        Object.keys(image).length &&
+        Object.values(image).every((value) => value === null ||
+            typeof value === 'boolean' ||
+            (typeof value === 'string' && !/^<\d+ bytes>$/.test(value)) ||
+            (typeof value === 'number' && Number.isFinite(value) && (!Number.isInteger(value) || Number.isSafeInteger(value)))));
+}
+const imagePredicates = (image) => Object.entries(image).map(([column, value]) => value === null ? { column, op: 'isNull' } : { column, op: '=', value });
+function returnedImageMatches(current, image) {
+    return (current.rows.length === 1 &&
+        Object.keys(current.rows[0]).length === Object.keys(image).length &&
+        current.columns.length === Object.keys(image).length &&
+        Object.entries(image).every(([column, value]) => Object.hasOwn(current.rows[0], column) && current.columns.includes(column) && current.rows[0][column] === value));
+}
+/** Call on the fenced writer BOTH when capturing an image and when undoing it.
+ * SQL equality detects lossy driver conversions (e.g. submillisecond dates);
+ * strict scalar comparison also rejects NULL/empty and collation-equivalent
+ * text changes. Capture-time validation is essential: a later rounded value
+ * could match an image whose original precision was already lost.
+ * Permission wrappers must expose complete raw fields before marking wholeRow.
+ * This proves one scalar row, not trigger/cascade side effects or DDL history. */
+export async function journalImageMatches(tx, table, image) {
+    if (!scalarImage(image))
+        return false;
+    const filter = { groups: [imagePredicates(image)] };
+    const current = await tx.query({ table, filter, limit: 2, offset: 0 });
+    return returnedImageMatches(current, image);
+}
+/** The touched-field counterpart to journalImageMatches. Call under lockRecord
+ * before and after a shared update to establish lossless history, and around
+ * its inverse to detect races and restore coercion. Untouched fields need no
+ * projection or inverse permission. A successful capture is not a guarantee
+ * that generic type coercion will restore it; inverse readback must still pass. */
+export async function journalFieldsMatch(tx, table, key, values) {
+    if (!scalarImage(values) ||
+        !key ||
+        !Object.keys(key).length ||
+        Object.values(key).some((value) => typeof value !== 'string' && !(typeof value === 'number' && Number.isFinite(value))))
+        return false;
+    const filter = { groups: [...keyFilter(key).groups.map((group) => [...group, ...imagePredicates(values)])] };
+    const current = await tx.query({ table, columns: Object.keys(values), filter, limit: 2, offset: 0 });
+    return returnedImageMatches(current, values);
+}
+async function completeImageMatches(tx, step, image) {
+    if (!image ||
+        !step.key ||
+        !Object.keys(step.key).length ||
+        Object.entries(step.key).some(([column, value]) => !Object.hasOwn(image, column) || image[column] !== value))
+        return false;
+    return journalImageMatches(tx, step.table, image);
+}
+async function revertOwned(adapter, connection, entry, errorMessage) {
+    /* An insert is undone by removing what it added, and a delete by putting it
+       back — so a graph's steps are reversed, children before parents or the
+       other way round depending on which it was. The order a graph went in is
+       the order it must come out of, backwards. */
+    const steps = entry.kind === 'insert_graph' || entry.kind === 'delete_graph' ? [...entry.steps].reverse() : entry.steps;
+    const undoing = entry.kind === 'insert' || entry.kind === 'insert_graph'
+        ? 'remove'
+        : entry.kind === 'delete' || entry.kind === 'delete_graph'
+            ? 'restore'
+            : 'put back';
+    /* Checked first, all of it, before anything is written. */
+    const problems = [];
+    for (const step of steps) {
+        // An outside read is neither the complete image nor a lock. New bounded
+        // inverses do all validation below, after acquiring the transaction fence.
+        if (step.wholeRow || step.exactFields)
+            continue;
+        if (!step.key) {
+            problems.push(`A ${step.table} row in this write has no key, so it cannot be found again.`);
+            continue;
+        }
+        const row = await currentRow(adapter, step.table, step.key);
+        if (undoing === 'restore') {
+            /* The row was deleted; putting it back is only honest if nothing has
+               taken its key since. */
+            if (row)
+                problems.push(`${step.table} ${describe(step.key)} exists again, so restoring it would overwrite something.`);
+            continue;
+        }
+        if (!row) {
+            problems.push(`${step.table} ${describe(step.key)} is gone, so there is nothing to undo.`);
+            continue;
+        }
+        const moved = Object.entries(step.after ?? {}).filter(([column, value]) => !same(row[column], value));
+        if (moved.length) {
+            problems.push(`${step.table} ${describe(step.key)} has changed since — "${moved[0][0]}" is no longer what this write left. ` +
+                'Undoing would overwrite that.');
+        }
+    }
+    if (problems.length)
+        return { reverted: false, outcome: 'not_applied', entry, errors: problems };
+    const done = [];
+    /* The steps go back as one transaction where the adapter offers one, so a
+       revert that fails on its third row leaves the first two as they were:
+       half an undo is the state neither the write nor the revert intended.
+       Legacy preflight stays on the read handle. Bounded single-row images are
+       checked inside the writer, after a fence: a shared handle alone does not
+       exclude concurrent PG writers. No nontransactional fallback. */
+    const undo = async (tx) => {
+        for (const step of steps) {
+            if ((step.wholeRow || step.exactFields) &&
+                (!step.key ||
+                    !Object.keys(step.key).length ||
+                    !tx.lockRecord ||
+                    (step.wholeRow && !['insert', 'delete'].includes(entry.kind)) ||
+                    (step.exactFields && entry.kind !== 'update'))) {
+                throw new Refusal('This connection cannot fence a complete single-row inverse.');
+            }
+            if (step.key && tx.lockRecord)
+                await tx.lockRecord({ table: step.table, key: step.key });
+        }
+        for (const step of steps) {
+            if (undoing === 'remove') {
+                if (step.wholeRow && !(await completeImageMatches(tx, step, step.after)))
+                    throw new WriteConflict();
+                const removed = await tx.remove({ table: step.table, key: step.key });
+                if (step.wholeRow && removed.affected !== 1)
+                    throw new WriteConflict();
+                done.push({ table: step.table, key: { ...step.key }, action: 'removed' });
+            }
+            else if (undoing === 'restore') {
+                if (step.wholeRow && (await currentRow(tx, step.table, step.key)))
+                    throw new WriteConflict();
+                // An absent-row read does not reserve a PK. The transaction insert
+                // contract MUST reject every uniqueness conflict, including SQLite
+                // schema REPLACE policies, so a racing occupant cannot be overwritten.
+                // Trigger/cascade side effects remain the adapter's row-only boundary.
+                await tx.insert({
+                    table: step.table,
+                    values: (step.before ?? {}),
+                });
+                if (step.wholeRow && !(await completeImageMatches(tx, step, step.before)))
+                    throw new WriteConflict();
+                done.push({ table: step.table, key: { ...step.key }, action: 'restored' });
+            }
+            else {
+                if (step.exactFields &&
+                    (!scalarImage(step.before) ||
+                        !scalarImage(step.after) ||
+                        Object.keys(step.before).length !== Object.keys(step.after).length ||
+                        Object.keys(step.before).some((column) => !Object.hasOwn(step.after, column)) ||
+                        !(await journalFieldsMatch(tx, step.table, step.key, step.after))))
+                    throw new WriteConflict();
+                const updated = await tx.update({
+                    table: step.table,
+                    key: step.key,
+                    values: (step.before ?? {}),
+                    expected: (step.after ?? {}),
+                    // Returning to the recorded before-image is not a new transition.
+                    restore: true,
+                });
+                if (step.exactFields && (updated.affected !== 1 || !(await journalFieldsMatch(tx, step.table, step.key, step.before))))
+                    throw new WriteConflict();
+                done.push({ table: step.table, key: { ...step.key }, action: 'put back' });
+            }
+        }
+    };
+    try {
+        await adapter.transaction((tx) => undo(tx));
+    }
+    catch (err) {
+        if (err instanceof TransactionOutcomeUnknown) {
+            return { reverted: false, outcome: 'unknown', entry, errors: [undoUncertain] };
+        }
+        return {
+            reverted: false,
+            outcome: 'not_applied',
+            entry,
+            steps: [],
+            errors: [`${errorMessage(err)}${done.length ? ' — nothing was changed; the whole undo rolled back.' : ''}`],
+        };
+    }
+    forget(connection, entry.id);
+    return { reverted: true, outcome: 'applied', entry, steps: done };
+}
+const describe = (key) => {
+    const parts = Object.entries(key);
+    return parts.length === 1 ? String(parts[0][1]) : parts.map(([c, v]) => `${c}=${v}`).join(',');
+};
+/** A sentence for the history, in the words someone would use about it. */
+export function summarise(kind, steps, detail) {
+    const table = steps[0]?.table ?? 'something';
+    const n = steps.length;
+    switch (kind) {
+        case 'update':
+            return `Updated ${table} ${steps[0]?.key ? describe(steps[0].key) : ''}`.trim();
+        // Many rows of one table in one insert entry is an import (recordedImport).
+        case 'insert':
+            return n > 1 ? `Imported ${n} rows into ${table}` : `Inserted into ${table}`;
+        case 'delete':
+            return `Deleted ${table} ${steps[0]?.key ? describe(steps[0].key) : ''}`.trim();
+        case 'insert_graph':
+            return `Inserted ${n} row${n === 1 ? '' : 's'} as one graph`;
+        case 'delete_graph':
+            return `Deleted ${n} row${n === 1 ? '' : 's'} as one graph`;
+        default:
+            return detail ? `Ran SQL: ${detail}` : 'Ran a SQL write';
+    }
+}

package/dist/server/keysetReadHttp.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The query bar's side of paging by key (shared/keysetPage.ts): which order a
+ * read pages in, the continuation a step asks for, and the page's boundaries
+ * for the next step. A table read and a view read the bar falls through to
+ * each get the same three answers, one over columns and one over paths.
+ *
+ * A boundary needs every order column in the row. A list that sorts by one
+ * it does not show (`show name sort created_at`) asks for it too, and it is
+ * taken out of the rows before they are sent: the reader may sort by it, so
+ * they may read it, but the list did not ask to show it.
+ */
+import type { Filter } from '../adapters/adapter.js';
+import { type DatabaseSchema, type Order, type TableMeta } from '../shared/schema.js';
+import type { ViewDef } from '../shared/viewPaths.js';
+import { type PageBounds, type PageStep } from '../shared/keysetPage.js';
+import type { RecordsContinuation, ViewContinuation } from './resourceReadOperations.js';
+type Row = Record<string, unknown>;
+interface RecordsPaging {
+    order: Order[];
+    /** The columns to read: the request's, with any order column it left out. */
+    columns?: string[];
+    continuation?: RecordsContinuation;
+    /** Read for the boundary only, and taken out of the rows. */
+    extra: string[];
+}
+/** How a table read pages, or undefined when it can only page by offset. */
+export declare function recordsPaging(table: TableMeta, dialect: DatabaseSchema['dialect'], orderBy: Order[] | undefined, columns: string[] | undefined, filter: Filter | undefined, step: PageStep | undefined): RecordsPaging | undefined;
+export interface ViewPaging {
+    /** The view as it is read: its order made total, and any order column it left out asked for. */
+    view: ViewDef;
+    order: Order[];
+    continuation?: ViewContinuation;
+    extra: string[];
+}
+/**
+ * How a view read pages. Only an order over the base table's own columns
+ * pages by key: a path through a reference, an aggregate's alias, a distance
+ * or byte-ordered text keep the offset. Its order is made total with the key,
+ * as a table read's is (withKey), on every page, so the first page and the
+ * next agree about ties.
+ */
+export declare function viewPaging(schema: DatabaseSchema, table: TableMeta, view: ViewDef, step: PageStep | undefined): ViewPaging | undefined;
+/** The page's boundaries, then the rows and columns without what was read only for them. */
+export declare function settlePage(order: readonly Order[], extra: readonly string[], result: {
+    rows: Row[];
+    columns: string[];
+}, name?: (column: string) => string): {
+    bounds?: PageBounds;
+    rows: Row[];
+    columns: string[];
+};
+export {};

package/dist/server/keysetReadHttp.js

@@ -0,0 +1,85 @@
+import { defaultOrder, resolveOrder, withKey } from '../shared/schema.js';
+import { continueGroups, keysetAfter, keysetOrder, pageBounds, reversedOrder, } from '../shared/keysetPage.js';
+/** The groups past (or, read the other way, before) a step's boundary; undefined when it names no exact boundary. */
+function continuationGroups(table, order, step, dialect) {
+    if ('end' in step)
+        return { reverse: true, groups: undefined };
+    const reverse = 'before' in step;
+    const tail = keysetAfter(table, reverse ? reversedOrder(order) : order, reverse ? step.before : step.after, dialect);
+    return tail && { reverse, groups: tail };
+}
+/** How a table read pages, or undefined when it can only page by offset. */
+export function recordsPaging(table, dialect, orderBy, columns, filter, step) {
+    const { order } = resolveOrder(table, orderBy);
+    if (!keysetOrder(table, order, dialect))
+        return undefined;
+    const extra = columns?.length ? order.map((o) => o.column).filter((column) => !columns.includes(column)) : [];
+    const planned = step && continuationGroups(table, order, step, dialect);
+    if (step && !planned)
+        return { order, extra: [] };
+    return {
+        order,
+        extra,
+        ...(extra.length ? { columns: [...columns, ...extra] } : {}),
+        ...(planned
+            ? {
+                continuation: { reverse: planned.reverse, ...(planned.groups ? { groups: continueGroups(filter?.groups, planned.groups) } : {}) },
+            }
+            : {}),
+    };
+}
+/**
+ * How a view read pages. Only an order over the base table's own columns
+ * pages by key: a path through a reference, an aggregate's alias, a distance
+ * or byte-ordered text keep the offset. Its order is made total with the key,
+ * as a table read's is (withKey), on every page, so the first page and the
+ * next agree about ties.
+ */
+export function viewPaging(schema, table, view, step) {
+    const given = view.orderBy ?? [];
+    if (given.some((o) => o.alias || o.near !== undefined || o.collation !== undefined || !table.columns.some((c) => c.name === o.path)))
+        return undefined;
+    const order = given.length
+        ? withKey(table, given.map((o) => ({ column: o.path, direction: o.direction })))
+        : defaultOrder(table);
+    if (!keysetOrder(table, order, schema.dialect))
+        return undefined;
+    // No columns is every column of the base table, the order's among them.
+    const shown = new Set(view.columns.map((c) => c.path));
+    const extra = view.columns.length ? order.map((o) => o.column).filter((column) => !shown.has(column)) : [];
+    const read = {
+        ...view,
+        orderBy: order.map((o) => ({ path: o.column, direction: o.direction })),
+        ...(extra.length ? { columns: [...view.columns, ...extra.map((path) => ({ path }))] } : {}),
+    };
+    const planned = step && continuationGroups(table, order, step, schema.dialect);
+    if (step && !planned)
+        return { view: read, order, extra };
+    const toPaths = (groups) => groups.map((group) => group.map(({ column, op, value }) => ({ path: column, op, ...(value === undefined ? {} : { value }) })));
+    return {
+        view: read,
+        order,
+        extra,
+        ...(planned
+            ? {
+                continuation: {
+                    reverse: planned.reverse,
+                    orderBy: planned.reverse ? reversedOrder(order).map((o) => ({ path: o.column, direction: o.direction })) : read.orderBy,
+                    ...(planned.groups ? { groups: continueGroups(view.filter?.groups, toPaths(planned.groups)) } : {}),
+                },
+            }
+            : {}),
+    };
+}
+/** The page's boundaries, then the rows and columns without what was read only for them. */
+export function settlePage(order, extra, result, name = (column) => column) {
+    const bounds = pageBounds(order, result.rows, name);
+    if (!extra.length)
+        return { ...(bounds ? { bounds } : {}), rows: result.rows, columns: result.columns };
+    const dropped = new Set(extra.map(name));
+    return {
+        ...(bounds ? { bounds } : {}),
+        rows: result.rows.map((row) => Object.fromEntries(Object.entries(row).filter(([key]) => !dropped.has(key)))),
+        columns: result.columns.filter((column) => !dropped.has(column)),
+    };
+}

package/dist/server/layouts.d.ts

@@ -0,0 +1,49 @@
+/** One stored entry, as the client wrote it. Opaque here on purpose: the
+    store round-trips any JSON value — layout objects, filter lists. */
+export type StoredLayout = unknown;
+/** connection id → table id → layout. */
+type LayoutFile = Record<string, Record<string, StoredLayout>>;
+/**
+ * Saved pages live in a sibling file with the same shape — connection id,
+ * then page id. The same shape because it earns the same machinery: pages
+ * were the one piece of built work that lived only in localStorage, so a
+ * page assembled in one browser was invisible to every other, while the
+ * record layout beside it travelled. Same store, same guarantees.
+ */
+export declare function pagesPath(): string;
+/**
+ * Saved list filters, the third sibling — connection id, then table id, to
+ * a list of `{name, query}`. The same argument as pages: a filter someone
+ * saved is work, and work that lives only in one browser's localStorage is
+ * work that vanishes with the browser.
+ */
+export declare function filtersPath(): string;
+/**
+ * Where a request's saved filters live, in that one file. An App without
+ * sign-in (and the plain browser) keeps one list per connection, shared. An
+ * App that signs people in keeps each account's own, in a section keyed by
+ * the connection and the account the verified session established — never
+ * by anything the client sends — so one account's list is a key no other
+ * account's request can name; the separator is a character no connection or
+ * account id carries. Null where nothing may be kept: no verified account,
+ * or rows scoped by a policy, whose principals write only through it.
+ */
+export declare function filtersSection(connection: string, reader: {
+    signIn: boolean;
+    account?: string;
+    rowPolicy: boolean;
+}): string | null;
+/**
+ * Read every stored layout.
+ *
+ * A missing file is the normal case — most connections have never had a
+ * layout saved — and an unreadable one falls back to empty rather than
+ * refusing to serve the page. A record with its derived layout is a working
+ * page; a record that will not render because a preferences file has a stray
+ * comma in it is not.
+ */
+export declare function readLayouts(path?: string): Promise<LayoutFile>;
+/** Every layout for one connection. */
+export declare function layoutsFor(connection: string, path?: string): Promise<Record<string, StoredLayout>>;
+export declare function writeLayout(connection: string, table: string, layout: StoredLayout | null, path?: string): Promise<void>;
+export {};