@substrat-run/kernel 0.138.0 → 0.140.0

package/dist/table-ownership.js

@@ -0,0 +1,285 @@
+/**
+ * Which module owns which table in a scope, as the migrations ACTUALLY made it (#2068).
+ *
+ * A subject erasure writes to a module's own tables with the kernel's handle, so "own" has to
+ * be a fact the kernel recorded, not a claim a manifest makes or a parse of migration text can
+ * infer: `CREATE TABLE IF NOT EXISTS other_modules_table` reads as creating a table and creates
+ * nothing when it already exists.
+ *
+ * **Recorded statement by statement.** Both adapters run an authored migration one statement at
+ * a time (`splitSqlStatements`) and diff the scope's tables around each one
+ * (`runMigrationStatements`, then `recordOwnershipSteps`). One statement changes at most one table
+ * (with its shadow tables, for a virtual one), so the diff names
+ * it exactly: a table that appeared was created by the migrating module; one table gone and one
+ * appeared is a rename, and the row moves with it; a table gone was dropped, and its row goes.
+ * A table that existed before the statement is never attributed to it. Diffing a whole migration
+ * instead could not tell `RENAME a TO b; CREATE TABLE a` from nothing having happened to `a`.
+ *
+ * **Guarded.** The ledger is a spine table, so module code cannot write it through `ctx.sql`, and
+ * an authored migration that names it is refused before it runs (`assertMigrationLeavesLedgerAlone`).
+ *
+ * **Backfilled conservatively.** Scopes migrated before the ledger existed have tables with no
+ * row. On the first erasure that needs them, the journal is replayed in applied order through the
+ * SAME transition function (`applyTableChange`), statement by statement, from each entry's
+ * migration text. The replay only ever attributes what it can prove: a plain `CREATE TABLE`
+ * (which would have failed had the table existed) proves its creator; `IF NOT EXISTS` proves
+ * nothing, since the table may already have been there; and an entry whose text is unavailable
+ * (its module no longer registered) makes every table it could have touched unowned. Unowned
+ * means the erasure refuses that table — the conservative answer, never a guess.
+ */
+import { namesSpineTable, substratError, tokenizeSql } from '@substrat-run/contracts';
+import { executableSqlStatements, splitSqlStatements } from './sql-statements.js';
+/** The ledger's name — also what an authored migration may never name. */
+export const TABLE_OWNERS = '_substrat_table_owners';
+/**
+ * The spine table the ownership lives in — a scope table, so it travels with the scope's data.
+ * The name is spelled out rather than interpolated: `lint:spine-ddl` reads this text as written.
+ */
+export const TABLE_OWNERS_DDL = `
+  CREATE TABLE IF NOT EXISTS _substrat_table_owners (
+    table_name TEXT PRIMARY KEY,
+    module_id TEXT NOT NULL,
+    source TEXT NOT NULL,
+    recorded_at TEXT NOT NULL
+  );
+`;
+/**
+ * Refuse an authored migration that names the ownership ledger — in any statement, read or
+ * write, quoted or qualified. Each adapter runs it beside `assertNoSpineReference`, before the
+ * migration executes, so a refused migration changes nothing and the scope fails closed.
+ */
+export function assertMigrationLeavesLedgerAlone(sql, what) {
+    for (const token of tokenizeSql(sql)) {
+        if (token.text.split('.').some((part) => part.toLowerCase() === TABLE_OWNERS)) {
+            throw substratError('forbidden', `${what} names ${TABLE_OWNERS}, the kernel's record of which module created which table — ` +
+                'a migration may not read or write it', { reason: 'spine_write' });
+        }
+    }
+}
+/** The scope's own tables, lowercased: no spine, no SQLite or workerd internals, no views. */
+export function moduleTableNames(sql) {
+    return new Set(sql
+        .query("SELECT name FROM sqlite_master WHERE type = 'table'")
+        .map((r) => r.name.toLowerCase())
+        .filter((n) => !namesSpineTable(n) && !n.startsWith('sqlite_') && !n.startsWith('_cf_')));
+}
+/** A table name a statement names, lowercased; `main.` is the default schema, any other is not ours. */
+function nameOf(token) {
+    if (!token)
+        return undefined;
+    const parts = token.text.toLowerCase().split('.');
+    if (parts.length === 1)
+        return parts[0];
+    return parts.length === 2 && parts[0] === 'main' ? parts[1] : undefined;
+}
+/** The table DDL in one migration's text, in statement order. TEMP tables are nobody's and are left out. */
+export function tableStatements(sqlText) {
+    const out = [];
+    // The same statement boundaries the adapters execute on, so the replay reads what ran.
+    const statements = splitSqlStatements(sqlText).map((text) => tokenizeSql(text).filter((t) => !t.punct));
+    for (const st of statements) {
+        const w = (i) => (st[i] && !st[i].quoted ? st[i].text.toLowerCase() : '');
+        if (w(0) === 'create') {
+            let k = 1;
+            const temp = w(k) === 'temp' || w(k) === 'temporary';
+            if (temp)
+                k += 1;
+            if (w(k) === 'virtual')
+                k += 1;
+            if (w(k) !== 'table')
+                continue;
+            k += 1;
+            const ifNotExists = w(k) === 'if' && w(k + 1) === 'not' && w(k + 2) === 'exists';
+            if (ifNotExists)
+                k += 3;
+            const table = nameOf(st[k]);
+            if (table && !temp)
+                out.push({ kind: 'create', table, ifNotExists });
+        }
+        else if (w(0) === 'alter' && w(1) === 'table') {
+            const from = nameOf(st[2]);
+            const at = st.findIndex((t, i) => i > 2 && !t.quoted && t.text.toLowerCase() === 'rename');
+            const to = at > 0 && w(at + 1) === 'to' ? nameOf(st[at + 2]) : undefined;
+            if (from && to)
+                out.push({ kind: 'rename', from, to });
+        }
+        else if (w(0) === 'drop' && w(1) === 'table') {
+            const table = nameOf(st[w(2) === 'if' && w(3) === 'exists' ? 4 : 2]);
+            if (table)
+                out.push({ kind: 'drop', table });
+        }
+    }
+    return out;
+}
+/**
+ * THE transition, shared by the live record and the journal replay: a create sets its owner (or
+ * an unknown one), a rename moves the row to the new name, a drop removes it.
+ */
+export function applyTableChange(store, change) {
+    switch (change.kind) {
+        case 'create':
+            store.set(change.table, change.owner);
+            return;
+        case 'rename': {
+            const owner = store.get(change.from);
+            store.delete(change.from);
+            store.set(change.to, owner ?? null);
+            return;
+        }
+        case 'drop':
+            store.delete(change.table);
+    }
+}
+/** The ledger as an `OwnerStore`: an unknown owner is no row, so an erasure refuses that table. */
+function ledgerStore(sql, source, at) {
+    return {
+        get: (table) => sql.query(`SELECT module_id FROM ${TABLE_OWNERS} WHERE table_name = ?`, [table])[0]
+            ?.module_id ?? null,
+        set: (table, owner) => {
+            if (owner === null) {
+                sql.exec(`DELETE FROM ${TABLE_OWNERS} WHERE table_name = ?`, [table]);
+                return;
+            }
+            sql.exec(`INSERT INTO ${TABLE_OWNERS} (table_name, module_id, source, recorded_at) VALUES (?, ?, ?, ?)
+           ON CONFLICT(table_name) DO UPDATE SET module_id = excluded.module_id, source = excluded.source,
+             recorded_at = excluded.recorded_at`, [table, owner, source, at]);
+        },
+        delete: (table) => {
+            sql.exec(`DELETE FROM ${TABLE_OWNERS} WHERE table_name = ?`, [table]);
+        },
+    };
+}
+/**
+ * Run an authored migration ONE statement at a time, through the adapter's `exec`, and return
+ * the table set either side of every statement that changed it. Both adapters run their
+ * authored migrations through this, inside the migration's transaction; recording happens
+ * afterwards (`recordOwnershipSteps`), so the journal's `rows_changed` counts the migration's
+ * own writes and none of the kernel's bookkeeping.
+ */
+export function runMigrationStatements(sql, migrationSql, exec) {
+    const steps = [];
+    let tables = moduleTableNames(sql);
+    // Comment-blanked text, at the same boundaries: what SQLite stores is what a later ALTER rewrites.
+    for (const statement of executableSqlStatements(migrationSql)) {
+        exec(statement);
+        const after = moduleTableNames(sql);
+        if (after.size !== tables.size || [...after].some((t) => !tables.has(t)))
+            steps.push({ before: tables, after });
+        tables = after;
+    }
+    return steps;
+}
+/**
+ * The table a group of names belongs to, when there is one: the shortest name, with every other
+ * name its shadow (`root_…`) — what one `CREATE VIRTUAL TABLE … USING fts5` makes (`x`, `x_data`,
+ * `x_idx`, …), drops or renames together. Undefined when the names are not one such group.
+ */
+function rootOf(names) {
+    if (names.length === 0)
+        return undefined;
+    const root = [...names].sort((a, b) => a.length - b.length)[0];
+    return names.every((n) => n === root || n.startsWith(`${root}_`)) ? root : undefined;
+}
+/**
+ * The changes one statement made, from the table set either side of it. A single SQLite
+ * statement changes ONE table — with its shadow tables, for a virtual table — so: tables only
+ * appearing are a create by `moduleId`; only disappearing, a drop; one group gone and one
+ * appeared, a rename, each shadow moving with its root. Anything else is not a shape a single
+ * statement produces, and is refused rather than guessed at.
+ */
+export function tableChangesOf(moduleId, step) {
+    const gone = [...step.before].filter((t) => !step.after.has(t));
+    const appeared = [...step.after].filter((t) => !step.before.has(t));
+    const from = rootOf(gone);
+    const to = rootOf(appeared);
+    if (gone.length === 0 && to !== undefined) {
+        return appeared.map((table) => ({ kind: 'create', table, owner: moduleId }));
+    }
+    if (appeared.length === 0 && from !== undefined)
+        return gone.map((table) => ({ kind: 'drop', table }));
+    if (from !== undefined && to !== undefined && gone.length === appeared.length) {
+        const renamed = gone.map((g) => ({ from: g, to: `${to}${g.slice(from.length)}` }));
+        if (renamed.every((r) => appeared.includes(r.to))) {
+            return renamed.map((r) => ({ kind: 'rename', from: r.from, to: r.to }));
+        }
+    }
+    throw substratError('internal', `migration of ${moduleId}: one statement changed unrelated tables (gone: ${gone.join(', ') || '-'}; ` +
+        `appeared: ${appeared.join(', ') || '-'}), which the ownership record cannot attribute`);
+}
+/** Apply each recorded step to the ledger, in statement order, through `applyTableChange`. */
+export function recordOwnershipSteps(sql, moduleId, steps, at) {
+    const store = ledgerStore(sql, 'migration', at);
+    for (const step of steps)
+        for (const change of tableChangesOf(moduleId, step))
+            applyTableChange(store, change);
+}
+/**
+ * Attribute the given tables, where they have no row yet, by replaying the migration journal in
+ * applied order, statement by statement, through `applyTableChange` — the one-time backfill for a
+ * scope migrated before ownership was recorded. Only what the replay can prove is attributed:
+ *
+ * - a plain `CREATE TABLE` proves its creator — it would have failed had the table existed;
+ * - `CREATE TABLE IF NOT EXISTS` proves nothing: an earlier migration, or runtime DDL, may already
+ *   have made the table, so it leaves the table's owner unknown;
+ * - an entry whose migration text is not available — its module no longer registered — could have
+ *   created, renamed or dropped anything, so every table that exists at that point becomes
+ *   unknown. A later plain `CREATE` still proves its own creation.
+ *
+ * An unknown owner is no row, and the erasure refuses that table.
+ */
+export function backfillOwnershipFromJournal(sql, tables, migrationSqlOf, at) {
+    const missing = [...tables]
+        .map((t) => t.toLowerCase())
+        .filter((t) => sql.query(`SELECT 1 FROM ${TABLE_OWNERS} WHERE table_name = ?`, [t]).length === 0);
+    if (missing.length === 0)
+        return;
+    const journal = sql.query('SELECT module_id, version FROM _substrat_migrations ORDER BY applied_at, rowid');
+    const model = new Map();
+    const store = {
+        get: (t) => model.get(t),
+        set: (t, o) => void model.set(t, o),
+        delete: (t) => void model.delete(t),
+    };
+    for (const entry of journal) {
+        const text = migrationSqlOf(entry.module_id, entry.version);
+        if (text === undefined) {
+            for (const t of model.keys())
+                model.set(t, null);
+            continue;
+        }
+        for (const st of tableStatements(text)) {
+            if (st.kind === 'create') {
+                if (st.ifNotExists && model.has(st.table))
+                    continue;
+                applyTableChange(store, { kind: 'create', table: st.table, owner: st.ifNotExists ? null : entry.module_id });
+            }
+            else {
+                applyTableChange(store, st);
+            }
+        }
+    }
+    const live = moduleTableNames(sql);
+    const ledger = ledgerStore(sql, 'journal', at);
+    for (const t of missing) {
+        const owner = model.get(t);
+        if (owner && live.has(t))
+            ledger.set(t, owner);
+    }
+}
+/**
+ * Refuse, before anything is written, an erasure that would touch a table the scope does not
+ * record as the erasing module's. Missing rows are backfilled from the journal first.
+ */
+export function assertTablesOwned(sql, moduleId, tables, migrationSqlOf, at) {
+    const list = [...tables].map((t) => t.toLowerCase());
+    if (list.length === 0)
+        return;
+    backfillOwnershipFromJournal(sql, list, migrationSqlOf, at);
+    const refused = list.filter((t) => sql.query(`SELECT module_id FROM ${TABLE_OWNERS} WHERE table_name = ?`, [t])[0]
+        ?.module_id !== moduleId);
+    if (refused.length > 0) {
+        throw substratError('precondition_failed', `erasure: ${moduleId} names ${refused.map((t) => `'${t}'`).join(', ')}, which this scope does not record as ` +
+            'created by its migrations — an erasure touches only the tables a module owns. Nothing was erased.');
+    }
+}
+//# sourceMappingURL=table-ownership.js.map

package/dist/table-ownership.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-ownership.js","sourceRoot":"","sources":["../src/table-ownership.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,WAAW,EAAiB,MAAM,yBAAyB,CAAC;AAErG,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAElF,0EAA0E;AAC1E,MAAM,CAAC,MAAM,YAAY,GAAG,wBAAwB,CAAC;AAErD;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;CAO/B,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,gCAAgC,CAAC,GAAW,EAAE,IAAY;IACxE,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;QACrC,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,YAAY,CAAC,EAAE,CAAC;YAC9E,MAAM,aAAa,CACjB,WAAW,EACX,GAAG,IAAI,UAAU,YAAY,8DAA8D;gBACzF,sCAAsC,EACxC,EAAE,MAAM,EAAE,aAAa,EAAE,CAC1B,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,gBAAgB,CAAC,GAAc;IAC7C,OAAO,IAAI,GAAG,CACZ,GAAG;SACA,KAAK,CAAmB,qDAAqD,CAAC;SAC9E,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;SAChC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAC3F,CAAC;AACJ,CAAC;AAED,wGAAwG;AACxG,SAAS,MAAM,CAAC,KAA2B;IACzC,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;IACxC,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1E,CAAC;AAQD,4GAA4G;AAC5G,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,MAAM,GAAG,GAAqB,EAAE,CAAC;IACjC,uFAAuF;IACvF,MAAM,UAAU,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IACxG,KAAK,MAAM,EAAE,IAAI,UAAU,EAAE,CAAC;QAC5B,MAAM,CAAC,GAAG,CAAC,CAAS,EAAU,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAE,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC5F,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC;YACtB,IAAI,CAAC,GAAG,CAAC,CAAC;YACV,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,WAAW,CAAC;YACrD,IAAI,IAAI;gBAAE,CAAC,IAAI,CAAC,CAAC;YACjB,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS;gBAAE,CAAC,IAAI,CAAC,CAAC;YAC/B,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,OAAO;gBAAE,SAAS;YAC/B,CAAC,IAAI,CAAC,CAAC;YACP,MAAM,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,QAAQ,CAAC;YACjF,IAAI,WAAW;gBAAE,CAAC,IAAI,CAAC,CAAC;YACxB,MAAM,KAAK,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;YAC5B,IAAI,KAAK,IAAI,CAAC,IAAI;gBAAE,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;QACvE,CAAC;aAAM,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,OAAO,EAAE,CAAC;YAChD,MAAM,IAAI,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;YAC3B,MAAM,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,QAAQ,CAAC,CAAC;YAC3F,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YACzE,IAAI,IAAI,IAAI,EAAE;gBAAE,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;QACzD,CAAC;aAAM,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,OAAO,EAAE,CAAC;YAC/C,MAAM,KAAK,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACrE,IAAI,KAAK;gBAAE,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAmBD;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAiB,EAAE,MAAmB;IACrE,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,QAAQ;YACX,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;YACtC,OAAO;QACT,KAAK,QAAQ,EAAE,CAAC;YACd,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YACrC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAC1B,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,KAAK,IAAI,IAAI,CAAC,CAAC;YACpC,OAAO;QACT,CAAC;QACD,KAAK,MAAM;YACT,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;AACH,CAAC;AAED,mGAAmG;AACnG,SAAS,WAAW,CAAC,GAAc,EAAE,MAA+B,EAAE,EAAU;IAC9E,OAAO;QACL,GAAG,EAAE,CAAC,KAAK,EAAE,EAAE,CACb,GAAG,CAAC,KAAK,CAAwB,yBAAyB,YAAY,uBAAuB,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YACxG,EAAE,SAAS,IAAI,IAAI;QACvB,GAAG,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;YACpB,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,GAAG,CAAC,IAAI,CAAC,eAAe,YAAY,uBAAuB,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;gBACtE,OAAO;YACT,CAAC;YACD,GAAG,CAAC,IAAI,CACN,eAAe,YAAY;;gDAEa,EACxC,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,CAC3B,CAAC;QACJ,CAAC;QACD,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;YAChB,GAAG,CAAC,IAAI,CAAC,eAAe,YAAY,uBAAuB,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;QACxE,CAAC;KACF,CAAC;AACJ,CAAC;AAQD;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAc,EAAE,YAAoB,EAAE,IAAiC;IAC5G,MAAM,KAAK,GAAgB,EAAE,CAAC;IAC9B,IAAI,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACnC,mGAAmG;IACnG,KAAK,MAAM,SAAS,IAAI,uBAAuB,CAAC,YAAY,CAAC,EAAE,CAAC;QAC9D,IAAI,CAAC,SAAS,CAAC,CAAC;QAChB,MAAM,KAAK,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;QACpC,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;QAChH,MAAM,GAAG,KAAK,CAAC;IACjB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,SAAS,MAAM,CAAC,KAAwB;IACtC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACzC,MAAM,IAAI,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAE,CAAC;IAChE,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;AACvF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,IAAe;IAC9D,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAChE,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACpE,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC1B,MAAM,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC5B,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;QAC1C,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;IAC/E,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IACvG,IAAI,IAAI,KAAK,SAAS,IAAI,EAAE,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,EAAE,CAAC;QAC9E,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QACnF,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;YAClD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QAC1E,CAAC;IACH,CAAC;IACD,MAAM,aAAa,CACjB,UAAU,EACV,gBAAgB,QAAQ,mDAAmD,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,IAAI;QACnG,aAAa,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,gDAAgD,CAC1F,CAAC;AACJ,CAAC;AAED,8FAA8F;AAC9F,MAAM,UAAU,oBAAoB,CAAC,GAAc,EAAE,QAAgB,EAAE,KAA2B,EAAE,EAAU;IAC5G,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,WAAW,EAAE,EAAE,CAAC,CAAC;IAChD,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,KAAK,MAAM,MAAM,IAAI,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC;YAAE,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AACjH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,4BAA4B,CAC1C,GAAc,EACd,MAAwB,EACxB,cAAyE,EACzE,EAAU;IAEV,MAAM,OAAO,GAAG,CAAC,GAAG,MAAM,CAAC;SACxB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;SAC3B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,iBAAiB,YAAY,uBAAuB,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC;IACpG,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IACjC,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,CACvB,gFAAgF,CACjF,CAAC;IACF,MAAM,KAAK,GAAG,IAAI,GAAG,EAAyB,CAAC;IAC/C,MAAM,KAAK,GAAe;QACxB,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;QACxB,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;QACnC,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;KACpC,CAAC;IACF,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;QAC5D,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,IAAI,EAAE;gBAAE,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;YACjD,SAAS;QACX,CAAC;QACD,KAAK,MAAM,EAAE,IAAI,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC;YACvC,IAAI,EAAE,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACzB,IAAI,EAAE,CAAC,WAAW,IAAI,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,KAAK,CAAC;oBAAE,SAAS;gBACpD,gBAAgB,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;YAC/G,CAAC;iBAAM,CAAC;gBACN,gBAAgB,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAC9B,CAAC;QACH,CAAC;IACH,CAAC;IACD,MAAM,IAAI,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,EAAE,SAAS,EAAE,EAAE,CAAC,CAAC;IAC/C,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QAC3B,IAAI,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,MAAM,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACjD,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAC/B,GAAc,EACd,QAAgB,EAChB,MAAwB,EACxB,cAAyE,EACzE,EAAU;IAEV,MAAM,IAAI,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;IACrD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAC9B,4BAA4B,CAAC,GAAG,EAAE,IAAI,EAAE,cAAc,EAAE,EAAE,CAAC,CAAC;IAC5D,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CACzB,CAAC,CAAC,EAAE,EAAE,CACJ,GAAG,CAAC,KAAK,CAAwB,yBAAyB,YAAY,uBAAuB,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACpG,EAAE,SAAS,KAAK,QAAQ,CAC7B,CAAC;IACF,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,aAAa,CACjB,qBAAqB,EACrB,YAAY,QAAQ,UAAU,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,wCAAwC;YAC3G,mGAAmG,CACtG,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/timeline.d.ts

@@ -139,10 +139,10 @@ export interface ScopeWalkPage extends ListPage {
  * A caller who can only justify SOME entities must not use this read and filter
  * afterwards without saying so: post-filtering with `ctx.check(perm, entry.entity)`
  * per row is legitimate, but it changes the page size (a page of 20 can come back
- * with 3) and the cursor must then advance by the last row EXAMINED, not the last
- * row returned — see callout's `portal-orders` for that shape. A walk that only
- * visits what the caller may read is a different read with a different cost, and
- * is deliberately not this one.
+ * with 3), and the cursor of a refused row is that row's position — so walk it
+ * with `pageVisible`, which never returns one (#2073), as callout's `portal-orders`
+ * does. A walk that only visits what the caller may read is a different read with
+ * a different cost, and is deliberately not this one.
  */
 export declare function readScopeTimeline(ctx: TimelineReader, page?: ScopeWalkPage): Page<ScopeTimelineEntry>;
 /**

package/dist/timeline.js

@@ -236,10 +236,10 @@ function entityOfRow(d, row) {
  * A caller who can only justify SOME entities must not use this read and filter
  * afterwards without saying so: post-filtering with `ctx.check(perm, entry.entity)`
  * per row is legitimate, but it changes the page size (a page of 20 can come back
- * with 3) and the cursor must then advance by the last row EXAMINED, not the last
- * row returned — see callout's `portal-orders` for that shape. A walk that only
- * visits what the caller may read is a different read with a different cost, and
- * is deliberately not this one.
+ * with 3), and the cursor of a refused row is that row's position — so walk it
+ * with `pageVisible`, which never returns one (#2073), as callout's `portal-orders`
+ * does. A walk that only visits what the caller may read is a different read with
+ * a different cost, and is deliberately not this one.
  */
 export function readScopeTimeline(ctx, page) {
     const limit = listLimitOf(page?.limit);

package/dist/visible-continuation.d.ts

@@ -0,0 +1,38 @@
+import { type SealedSecret } from './secret-box.js';
+export declare const CONTINUATION_POSITION_CAP = 256;
+export interface ContinuationKey {
+    id: string;
+    /** Raw AES-256 key, base64 encoded only inside adapter-private storage. */
+    material: string;
+    createdAt: number;
+}
+export interface ContinuationKeys {
+    active: ContinuationKey;
+    previous?: ContinuationKey;
+}
+export interface ContinuationPosition {
+    sealed: SealedSecret;
+    expiresAt: number;
+}
+/** Neither keys nor positions may be stored in module-readable scope SQL or a dump. */
+export interface ContinuationStore {
+    keys(): Promise<ContinuationKeys | null>;
+    setKeys(keys: ContinuationKeys): Promise<void>;
+    position(id: string, expiresAt: number): Promise<ContinuationPosition | null>;
+    setPosition(id: string, position: ContinuationPosition): Promise<void>;
+}
+/** Everything that makes the position mean the same walk, with no raw input kept. */
+export interface ContinuationBinding {
+    scopeId: string;
+    principal: string;
+    operation: string;
+    list: string;
+    query: unknown;
+}
+/** Full visible pages are stateless; only a hidden budget stop needs a private locator. */
+export declare function visibleContinuation(store: ContinuationStore, binding: ContinuationBinding, now?: () => number, legacyUsed?: () => void, writable?: boolean): {
+    writable: boolean;
+    seal(position: string, hidden?: boolean): Promise<string | null>;
+    open(cursor: string): Promise<string>;
+};
+//# sourceMappingURL=visible-continuation.d.ts.map

package/dist/visible-continuation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visible-continuation.d.ts","sourceRoot":"","sources":["../src/visible-continuation.ts"],"names":[],"mappings":"AAEA,OAAO,EAA4C,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAa9F,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAI7C,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,eAAe,CAAC;IACxB,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,YAAY,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,uFAAuF;AACvF,MAAM,WAAW,iBAAiB;IAChC,IAAI,IAAI,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IACzC,OAAO,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;IAC9E,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACxE;AAED,qFAAqF;AACrF,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;CAChB;AAiDD,2FAA2F;AAC3F,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,mBAAmB,EAC5B,GAAG,GAAE,MAAM,MAAiB,EAC5B,UAAU,CAAC,EAAE,MAAM,IAAI,EACvB,QAAQ,UAAO;;mBAkBQ,MAAM,qBAAkB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;iBAgChD,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;EAqC9C"}

package/dist/visible-continuation.js

@@ -0,0 +1,162 @@
+/** Private, short-lived positions for a per-row-filtered walk (#2074). */
+import { PAGE_CURSOR_RESTART, substratError } from '@substrat-run/contracts';
+import { fromBase64, toBase64, webCryptoSecretBox } from './secret-box.js';
+import { isPlainPageCursor } from './list-index.js';
+const TOKEN_PREFIX = 'sc1';
+const TOKEN_PLAINTEXT_LENGTH = 192;
+const LIFETIME_MS = 15 * 60_000;
+const ROTATION_MS = 24 * 60 * 60_000;
+export const CONTINUATION_POSITION_CAP = 256;
+/** Remove this migration window at the next cursor-breaking release. */
+const ACCEPT_LEGACY_VISIBLE_CURSORS = true;
+const restart = () => substratError('validation_failed', 'list: this cursor cannot continue this walk — restart paging from the first page, without a cursor', { reason: PAGE_CURSOR_RESTART });
+const random = (size) => crypto.getRandomValues(new Uint8Array(size));
+const base64url = (bytes) => toBase64(bytes).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+const unbase64url = (text) => fromBase64(text.replace(/-/g, '+').replace(/_/g, '/'));
+const key = (now) => ({ id: base64url(random(9)), material: toBase64(random(32)), createdAt: now });
+function canonical(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (value instanceof Set)
+        return `[${[...value].map(canonical).sort().join(',')}]`;
+    if (value instanceof Map)
+        return `{${[...value].map(([k, v]) => [canonical(k), canonical(v)])
+            .sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => `${k}:${v}`).join(',')}}`;
+    return `{${Object.entries(value).filter(([, v]) => v !== undefined).sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(',')}}`;
+}
+/** SQL IN filters are sets; request order and duplicates must not change a walk's identity. */
+function normalizeFilter(value) {
+    if (Array.isArray(value)) {
+        const members = new Map(value.map((item) => {
+            const normalized = normalizeFilter(item);
+            return [canonical(normalized), normalized];
+        }));
+        return [...members.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([, item]) => item);
+    }
+    if (value && typeof value === 'object' && !(value instanceof Set) && !(value instanceof Map)) {
+        return Object.fromEntries(Object.entries(value).map(([name, item]) => [name, normalizeFilter(item)]));
+    }
+    return value;
+}
+async function bindingHash(binding) {
+    const bytes = new TextEncoder().encode(canonical(binding));
+    return base64url(new Uint8Array(await crypto.subtle.digest('SHA-256', bytes)));
+}
+function box(material) {
+    const bytes = fromBase64(material.material);
+    if (bytes.length !== 32)
+        throw restart();
+    return webCryptoSecretBox(material.id, bytes);
+}
+/** Full visible pages are stateless; only a hidden budget stop needs a private locator. */
+export function visibleContinuation(store, binding, now = Date.now, legacyUsed, writable = true) {
+    // Pagination mechanics do not change the rows in the walk. Every other input,
+    // including a grant constraint, does; bind it without retaining its raw value.
+    const query = binding.query && typeof binding.query === 'object' && !Array.isArray(binding.query)
+        ? Object.fromEntries(Object.entries(binding.query).filter(([name]) => !['cursor', 'limit', 'rowCursors', 'total'].includes(name)))
+        : binding.query ?? {};
+    if (query && typeof query === 'object' && !Array.isArray(query) && 'filters' in query) {
+        query.filters = normalizeFilter(query.filters);
+    }
+    let fingerprint;
+    const hash = () => (fingerprint ??= bindingHash({ ...binding, query }));
+    const readKeys = async () => {
+        try {
+            return await store.keys();
+        }
+        catch {
+            throw restart();
+        }
+    };
+    return {
+        writable,
+        async seal(position, hidden = true) {
+            // A read-only invocation (including a copy) cannot persist a hidden
+            // position. It keeps the former bounded-walk result at this budget stop.
+            if (hidden && !writable)
+                return null;
+            try {
+                const at = now();
+                let keys = await readKeys();
+                if (!writable && !keys)
+                    return null;
+                if (writable && (!keys || at - keys.active.createdAt >= ROTATION_MS)) {
+                    keys = { active: key(at), ...(keys ? { previous: keys.active } : {}) };
+                    await store.setKeys(keys);
+                }
+                if (!keys)
+                    return null;
+                const expiresAt = at + LIFETIME_MS;
+                let payload;
+                if (hidden) {
+                    const id = base64url(random(16));
+                    const sealed = await box(keys.active).seal(JSON.stringify({ id, position }));
+                    await store.setPosition(id, { sealed, expiresAt });
+                    payload = JSON.stringify({ i: id, e: expiresAt, b: await hash() });
+                    if (payload.length > TOKEN_PLAINTEXT_LENGTH)
+                        throw restart();
+                    payload = payload.padEnd(TOKEN_PLAINTEXT_LENGTH, ' ');
+                }
+                else {
+                    payload = JSON.stringify({ p: position, e: expiresAt, b: await hash() });
+                }
+                const token = await box(keys.active).seal(payload);
+                return `${TOKEN_PREFIX}.${keys.active.id}.${base64url(fromBase64(token.ciphertext))}`;
+            }
+            catch {
+                if (!writable)
+                    return null;
+                throw restart();
+            }
+        },
+        async open(cursor) {
+            if (!cursor.startsWith(`${TOKEN_PREFIX}.`)) {
+                try {
+                    if (ACCEPT_LEGACY_VISIBLE_CURSORS && isPlainPageCursor(cursor)) {
+                        legacyUsed?.();
+                        return cursor;
+                    }
+                }
+                catch { /* All invalid legacy cursors have the same restart response. */ }
+                throw restart();
+            }
+            try {
+                const parts = cursor.split('.');
+                if (parts.length !== 3 || !/^[A-Za-z0-9_-]{12}$/.test(parts[1]) ||
+                    !/^[A-Za-z0-9_-]+$/.test(parts[2]))
+                    throw restart();
+                const keys = await readKeys();
+                const selected = [keys?.active, keys?.previous].find((candidate) => candidate?.id === parts[1]);
+                if (!selected)
+                    throw restart();
+                const decoded = await box(selected).open({ keyId: selected.id, ciphertext: toBase64(unbase64url(parts[2])) });
+                const payload = JSON.parse(decoded.trimEnd());
+                if (typeof payload.e !== 'number' || payload.e <= now() || payload.b !== await hash())
+                    throw restart();
+                if ('p' in payload) {
+                    if (typeof payload.p !== 'string')
+                        throw restart();
+                    return payload.p;
+                }
+                if (decoded.length !== TOKEN_PLAINTEXT_LENGTH ||
+                    typeof payload.i !== 'string' || !/^[A-Za-z0-9_-]{22}$/.test(payload.i))
+                    throw restart();
+                const record = await store.position(payload.i, payload.e);
+                if (!record || record.expiresAt !== payload.e || record.expiresAt <= now())
+                    throw restart();
+                const opened = JSON.parse(await box(selected).open(record.sealed));
+                if (opened.id !== payload.i || typeof opened.position !== 'string')
+                    throw restart();
+                return opened.position;
+            }
+            catch {
+                // No parsing, key, authentication, expiry or binding detail reaches a caller.
+                throw restart();
+            }
+        },
+    };
+}
+//# sourceMappingURL=visible-continuation.js.map

package/dist/visible-continuation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visible-continuation.js","sourceRoot":"","sources":["../src/visible-continuation.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@substrat-run/kernel",
-  "version": "0.138.0",
+  "version": "0.140.0",
   "description": "Substrat kernel contracts and services — pure TypeScript, no platform imports (D-14)",
   "license": "AGPL-3.0-only",
   "repository": {
@@ -22,7 +22,7 @@
     "dist"
   ],
   "dependencies": {
-    "@substrat-run/contracts": "^0.138.0"
+    "@substrat-run/contracts": "^0.140.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.5",