@substrat-run/adapter-cloudflare 0.170.0 → 0.171.0

package/dist/scope-do.js

@@ -457,6 +457,82 @@ const stageRowsTable = (ord) => `_substrat_stage_rows_${ord}`;
 const STAGE_READ_BATCH = 500;
 /** How many rows a dump page reads from a table at a time; each batch is read to its end. */
 const DUMP_READ_BATCH = 500;
+/**
+ * A capture's own tables and triggers (#2450): what lets a copy page a scope that never stops
+ * taking writes. `_substrat_capture` holds one row per copy reading this store (its id, when it was
+ * last asked for, the schema its pages read), `_substrat_capture_changes` the rows written since
+ * (table, rowid, and the batch that served it, null until one did), and three triggers per dumped
+ * table log every insert, update and delete there, once for every open capture. They exist only
+ * while a capture is open: the last one to end drops them all. Never in a dump.
+ */
+const CAPTURE_GLOB = '_substrat_capture*';
+const CAPTURE_TABLES_DDL = [
+    `CREATE TABLE IF NOT EXISTS _substrat_capture (copy_id TEXT PRIMARY KEY, touched_at INTEGER NOT NULL, schema TEXT NOT NULL, triggers INTEGER NOT NULL)`,
+    `CREATE TABLE IF NOT EXISTS _substrat_capture_changes (
+     copy_id TEXT NOT NULL, tbl TEXT NOT NULL, rid INTEGER NOT NULL, batch INTEGER,
+     PRIMARY KEY (copy_id, tbl, rid)) WITHOUT ROWID`,
+];
+/**
+ * How long a capture nobody asks for stays open: one copy lease. A copy's job renews its lease at
+ * least every quarter of it, and asks the source at every step, so a capture this idle belongs to
+ * a copy that has stopped, and its triggers would only cost every write a log row.
+ */
+const CAPTURE_IDLE_MS = SCOPE_COPY_LEASE_MS;
+/** How many logged rows one batch of changes serves at most, before its byte cap. */
+const CAPTURE_BATCH_ROWS = 2_000;
+/** Rowids per `IN (…)`: a Durable Object's SQLite binds at most 100 parameters to a statement. */
+const CAPTURE_IN_CHUNK = 90;
+const CAPTURE_GONE = 'the copy\'s capture of this scope is gone (it ended, expired or a load replaced the store); start the copy again';
+const CAPTURE_SCHEMA_MOVED = 'the scope\'s schema changed while it was copied (a migration ran, or a table was rebuilt); start the copy again';
+const CAPTURE_EXPRESSION_INDEX = 'a table with a unique index on an expression cannot be copied while it takes writes; copy it at a quiet moment';
+/** A write the capture path takes: one whose target is a capture table or a capture trigger. */
+const CAPTURE_STATEMENT = /^\s*(?:CREATE TABLE IF NOT EXISTS|INSERT INTO|UPDATE|DELETE FROM|DROP TABLE IF EXISTS|CREATE TRIGGER|DROP TRIGGER IF EXISTS)\s+"?_substrat_capture(?:\b|_)/;
+const quoteIdent = (name) => `"${name.replaceAll('"', '""')}"`;
+const quoteText = (text) => `'${text.replaceAll("'", "''")}'`;
+/**
+ * The triggers that log `name`'s writes for every open capture (#2450). A write logs the rowid it
+ * touched (an update both the old and the new, should it move the row), once per capture however
+ * often the row is written, and clears the batch that served it, so it is served again. A table
+ * read by offset has no rowid to log, and logs `0`: the whole table is sent again.
+ *
+ * A row a `REPLACE` resolution deletes (`INSERT OR REPLACE`, `REPLACE INTO`, `UPDATE OR REPLACE`
+ * onto another key) fires no delete trigger while recursive triggers are off, so for each of
+ * `uniqueKeys` a BEFORE trigger also logs every row equal to the incoming one on that key: the row
+ * the resolution is about to delete. Logging a row that then survives is harmless (a batch reads
+ * every row as it is), so a partial index is matched without its WHERE.
+ *
+ * A delete and a plain insert rather than `INSERT OR REPLACE`: inside a trigger, the outer
+ * statement's conflict handling wins, so an upsert's update (the write revision's own bump is one)
+ * would turn the replace into an abort, and fail the write it logs.
+ */
+function captureTriggers(name, byRowid, uniqueKeys) {
+    const tbl = quoteText(name);
+    const table = quoteIdent(name);
+    // Keyed on the log's primary key, copy first, so neither statement scans the log.
+    const clear = (rids) => `DELETE FROM _substrat_capture_changes WHERE copy_id IN (SELECT copy_id FROM _substrat_capture) AND tbl = ${tbl} AND rid IN (${rids}); `;
+    const log = (rid) => clear(rid) + `INSERT INTO _substrat_capture_changes (copy_id, tbl, rid, batch) SELECT copy_id, ${tbl}, ${rid}, NULL FROM _substrat_capture;`;
+    const logHeld = (key) => {
+        const match = key.map(({ column, collation }) => `t.${quoteIdent(column)} = NEW.${quoteIdent(column)} COLLATE ${quoteIdent(collation)}`).join(' AND ');
+        return (clear(`SELECT t.rowid FROM ${table} t WHERE ${match}`) +
+            `INSERT INTO _substrat_capture_changes (copy_id, tbl, rid, batch) SELECT c.copy_id, ${tbl}, t.rowid, NULL FROM _substrat_capture c, ${table} t WHERE ${match};`);
+    };
+    // Spelled as `sqlite_master` keeps it (no IF NOT EXISTS, one space after CREATE TRIGGER), so a
+    // trigger in place can be compared with the one this schema needs, text for text.
+    const on = (kind, when, event, body) => {
+        const trigger = `_substrat_capture_${kind}_${name}`;
+        return { name: trigger, sql: `CREATE TRIGGER ${quoteIdent(trigger)} ${when} ${event} ON ${table} BEGIN ${body} END` };
+    };
+    const triggers = [
+        on('i', 'AFTER', 'INSERT', log(byRowid ? 'NEW.rowid' : '0')),
+        on('u', 'AFTER', 'UPDATE', byRowid ? log('OLD.rowid') + ' ' + log('NEW.rowid') : log('0')),
+        on('d', 'AFTER', 'DELETE', log(byRowid ? 'OLD.rowid' : '0')),
+    ];
+    if (byRowid && uniqueKeys.length > 0) {
+        const held = uniqueKeys.map(logHeld).join(' ');
+        triggers.push(on('bi', 'BEFORE', 'INSERT', held), on('bu', 'BEFORE', 'UPDATE', held));
+    }
+    return triggers;
+}
 /** The names under which SQLite answers a table's rowid, unless a column takes one. */
 const ROWID_NAMES = new Set(['rowid', '_rowid_', 'oid']);
 /**
@@ -527,6 +603,7 @@ class WriteRevision {
     storage;
     suspended;
     refusal;
+    beforeWrite;
     /** Whether the current run, in the current transaction scope, already holds a bump. */
     covered = false;
     /** Inside `bookkeeping`: the one path whose writes advance no revision. */
@@ -544,18 +621,33 @@ class WriteRevision {
      * reads) only costs a pass a re-check.
      */
     written = 0;
+    /** Inside `untracked`: a capture's own bookkeeping, which nothing here counts. */
+    bypass = false;
     sql;
     constructor(raw, storage, suspended, 
     /** Why this store takes no write at all right now, or null (a `carried_away` copy, #1722). */
-    refusal) {
+    refusal, 
+    /** Run before every write statement (#2450: an idle capture's triggers go before the write). */
+    beforeWrite = () => undefined) {
         this.raw = raw;
         this.storage = storage;
         this.suspended = suspended;
         this.refusal = refusal;
+        this.beforeWrite = beforeWrite;
         const exec = (query, ...bindings) => {
+            if (this.bypass) {
+                // Enforced, not trusted, as `bookkeeping` is: a write here that is not the capture's own
+                // would be one the revision never saw.
+                if (this.isWrite(query) && !CAPTURE_STATEMENT.test(query)) {
+                    throw substratError('internal', `the capture path takes only the capture's own statements (#2450), not: ${query.slice(0, 80)}`);
+                }
+                return raw.exec(query, ...bindings);
+            }
             const write = this.isWrite(query);
-            if (write)
+            if (write) {
                 this.written++;
+                this.beforeWrite();
+            }
             if (this.keeping && write) {
                 // Bookkeeping takes the copy-marker insert, the lifecycle delivery (#1713) and the wire
                 // nonce claim's own statements (RFC wire-signing §4) and nothing else: any other write here would be one the revision never saw, which is the hole this
@@ -603,6 +695,23 @@ class WriteRevision {
             this.keeping = was;
         }
     }
+    /**
+     * A copy's capture of this store (#2450): its log, its triggers and its clock. That is what this
+     * store records about a copy reading it, never its data, so it advances no write revision and
+     * meets no refusal: a capture must open, renew and end on a store whatever state it is in. Only
+     * the capture's own statements run here; the triggers it creates log the scope's writes, which
+     * still go through the counted path above.
+     */
+    untracked(run) {
+        const was = this.bypass;
+        this.bypass = true;
+        try {
+            return run();
+        }
+        finally {
+            this.bypass = was;
+        }
+    }
     /** `storage.transactionSync`, at a transaction boundary. */
     transactionSync(run) {
         this.covered = false;
@@ -938,7 +1047,7 @@ options = {}) {
             // so every write advances the write revision a carry's restore is fenced on, inside the
             // transaction that commits it. Nothing else here may take the raw handle or open a
             // transaction on `ctx.storage` itself (`carried-copy.test.ts` in the kernel holds that).
-            this.revision = new WriteRevision(ctx.storage.sql, ctx.storage, () => this.revisionSuspended, () => (this.carriedAwayCopy ? CARRIED_AWAY_WRITE_REFUSAL : null));
+            this.revision = new WriteRevision(ctx.storage.sql, ctx.storage, () => this.revisionSuspended, () => (this.carriedAwayCopy ? CARRIED_AWAY_WRITE_REFUSAL : null), () => this.expireIdleCaptures());
             this.sql = this.revision.sql;
             for (const stmt of executableSqlStatements(KERNEL_DDL)) {
                 this.sql.exec(stmt);
@@ -946,6 +1055,12 @@ options = {}) {
             this.applySpineColumnAdditions();
             this.revisionSuspended = false;
             this.carriedAwayCopy = this.metaValue(CARRIED_AWAY_KEY) !== null;
+            // #2450: the triggers and tables an expiry emptied but could not drop go here, if no capture
+            // is open, before any request runs.
+            this.revision.untracked(() => {
+                if (this.hasTable('_substrat_capture'))
+                    this.dropCaptureIfIdle();
+            });
             for (const registration of modules)
                 this.registerModule(registration);
             for (const [name, handler] of Object.entries(bareOps))
@@ -5370,13 +5485,13 @@ options = {}) {
          * tables cannot be replayed — this host answers "object name reserved for internal use" — and
          * it is recomputable, so `importDump` rebuilds it from the loaded rows. A dump carries the rows,
          * never the index over them. A staged load's own tables (#2450) are this store's, not its data,
-         * and so is the wire nonce store (RFC wire-signing §4): a load builds it empty.
+         * and so are a capture's (#2450) and the wire nonce store (RFC wire-signing §4): a load builds it empty.
          */
         dumpTableDefs() {
             return this.sql
                 .exec(`SELECT name, sql FROM sqlite_master
               WHERE type = 'table' AND name NOT GLOB 'sqlite_*' AND name NOT GLOB '_cf_*'
-                AND name NOT GLOB '${STAGE_GLOB}' AND sql IS NOT NULL
+                AND name NOT GLOB '${STAGE_GLOB}' AND name NOT GLOB '${CAPTURE_GLOB}' AND sql IS NOT NULL
               ORDER BY name`)
                 .toArray().filter(({ name }) => !isSearchIndexTable(name) && !isWireNonceTable(name));
         }
@@ -5387,34 +5502,41 @@ options = {}) {
          * own; the pages are one consistent read only while `revision` stays the same, which the reader
          * compares. With `stamp`, the first page (`cursor` null) mints the load stamp, as
          * `exportDumpStamped` does; without it the export writes nothing, as `exportDump`.
+         *
+         * With `capture` (a copy's id), the pages need no quiet moment: the first page opens a capture
+         * in the same turn it reads (`openCapture`), so every row written after it is logged for
+         * `exportDumpChanges`, and every page names each row by its rowid (`rowids`), so a change can
+         * replace or delete it at the destination. A later page of a capture that is gone is refused.
          */
         exportDumpPage(cursor, opts = {}) {
             // Answered as data, so a refusal's code survives the hop (#113).
             return replyOf(() => this.dumpPage(cursor, opts));
         }
-        dumpPage(cursor, { stamp = false, maxBytes = SCOPE_DUMP_PAGE_MAX_BYTES }) {
+        dumpPage(cursor, { stamp = false, maxBytes = SCOPE_DUMP_PAGE_MAX_BYTES, capture }) {
             let loadStamp = this.loadStamp();
             if (stamp && cursor === null && !loadStamp && !this.carriedAwayCopy) {
                 loadStamp = ulid();
                 this.sql.exec(`INSERT INTO _substrat_meta (key, value) VALUES (?, ?)`, LOAD_STAMP_KEY, loadStamp);
             }
+            const defs = this.dumpTableDefs();
+            if (capture !== undefined) {
+                if (cursor === null)
+                    this.openCapture(capture, defs);
+                else
+                    this.heldCapture(capture, defs);
+            }
             const at = cursor === null ? null : decodeDumpCursor(cursor);
             const tables = [];
             let bytes = 0;
             let next = null;
-            for (const { name, sql } of this.dumpTableDefs()) {
+            for (const { name, sql } of defs) {
                 // Tables are read in name order: those before the cursor's are done. A cursor naming a
                 // table that is gone resumes at the next name.
                 if (at && name < at.table)
                     continue;
                 const after = at && name === at.table ? at.after : null;
                 const { where, bindings } = dumpRowFilter(name);
-                // Read to its end (it holds no row), as every cursor here is: see the batches below.
-                const probe = this.sql.exec(`SELECT * FROM "${name}" WHERE 0`);
-                probe.toArray();
-                const columns = probe.columnNames;
-                // A table without a rowid, or with a column that takes the name, is read by offset.
-                const byRowid = !/\bWITHOUT\s+ROWID\b/i.test(sql) && !columns.some((c) => ROWID_NAMES.has(c.toLowerCase()));
+                const { columns, byRowid } = this.tableShape(name, sql);
                 // In batches, each read to its end: a cursor left part-read keeps its table locked, and
                 // the next statement that drops or alters it fails with SQLITE_LOCKED.
                 const batch = (from) => Array.from(!byRowid
@@ -5425,12 +5547,15 @@ options = {}) {
                             .exec(`SELECT rowid, * FROM "${name}" WHERE (${where}) AND rowid > ? ORDER BY rowid LIMIT ?`, ...bindings, from, DUMP_READ_BATCH)
                             .raw(), (raw) => raw);
                 const rows = [];
+                const rowids = [];
                 let last = after;
                 let full = false;
                 for (;;) {
                     const read = batch(last);
                     for (const cells of read) {
                         rows.push(byRowid ? cells.slice(1) : cells);
+                        if (byRowid)
+                            rowids.push(Number(cells[0]));
                         last = byRowid ? Number(cells[0]) : (last ?? 0) + 1;
                         bytes += rowBytes(rows[rows.length - 1]);
                         if (bytes >= maxBytes) {
@@ -5441,7 +5566,7 @@ options = {}) {
                     if (full || read.length < DUMP_READ_BATCH)
                         break;
                 }
-                tables.push({ name, ddl: sql, columns, rows });
+                tables.push({ name, ddl: sql, columns, rows, ...(capture !== undefined && byRowid ? { rowids } : {}) });
                 if (full) {
                     next = encodeDumpCursor({ table: name, after: last ?? 0 });
                     break;
@@ -5449,6 +5574,296 @@ options = {}) {
             }
             return { tables, next, loadStamp, revision: this.metaValue(WRITE_REVISION_KEY) };
         }
+        /** A dumped table's columns, and whether its rows are read, and named, by rowid. */
+        tableShape(name, sql) {
+            // Read to its end (it holds no row), as every cursor here is: see `dumpPage`'s batches.
+            const probe = this.sql.exec(`SELECT * FROM ${quoteIdent(name)} WHERE 0`);
+            probe.toArray();
+            const columns = probe.columnNames;
+            // A table without a rowid, or with a column that takes the name, is read by offset.
+            return { columns, byRowid: !/\bWITHOUT\s+ROWID\b/i.test(sql) && !columns.some((c) => ROWID_NAMES.has(c.toLowerCase())) };
+        }
+        /**
+         * #2450: when the oldest open capture goes idle (epoch ms); null when none is open; undefined
+         * when not read since the object woke or since the last expiry, so the next write reads it.
+         */
+        captureIdleAt = undefined;
+        /**
+         * Open (or, for page 0 asked again, renew) the capture `copyId` (#2450): its row, the log, and
+         * the triggers that fill it on every dumped table. Through the untracked path: a capture is this
+         * store's bookkeeping about a copy, not its data, so it moves no write revision, and no dump
+         * carries it. Every trigger logs for every open capture, so one set serves overlapping copies.
+         *
+         * One set serving several captures means a capture opening must not vouch for one already open.
+         * So, before its triggers are made:
+         * - every other open capture is held to what `heldCapture` holds it to (the schema its pages read,
+         *   and every trigger it opened with still there) and ended here if it fails, because the triggers
+         *   about to be made again would hide a table rebuilt under it;
+         * - the triggers in place must be exactly the ones this schema needs, text for text. If any
+         *   differ, are missing or are left over (an index added under an open capture, a drop that did
+         *   not run), every other open capture ends, as the triggers it relied on were not these, and the
+         *   whole set is dropped and made again.
+         */
+        openCapture(copyId, defs) {
+            // Every trigger is worked out before anything is written, so a table a capture cannot follow
+            // refuses it with nothing left behind.
+            const triggers = defs.flatMap(({ name, sql }) => {
+                const { byRowid } = this.tableShape(name, sql);
+                return captureTriggers(name, byRowid, byRowid ? this.uniqueKeysOf(name) : []);
+            });
+            const schema = this.captureSchema(defs);
+            this.revision.untracked(() => {
+                for (const ddl of CAPTURE_TABLES_DDL)
+                    this.sql.exec(ddl);
+                const inPlace = new Map(this.sql.exec(`SELECT name, sql FROM sqlite_master WHERE type = 'trigger' AND name GLOB '${CAPTURE_GLOB}'`).toArray().map((t) => [t.name, t.sql]));
+                const others = this.sql.exec(`SELECT copy_id, schema, triggers FROM _substrat_capture WHERE copy_id <> ?`, copyId).toArray();
+                for (const other of others) {
+                    if (other.schema !== schema || Number(other.triggers) !== inPlace.size)
+                        this.forgetCapture(other.copy_id);
+                }
+                const current = inPlace.size === triggers.length && triggers.every((t) => inPlace.get(t.name) === t.sql);
+                if (!current) {
+                    this.sql.exec(`DELETE FROM _substrat_capture_changes WHERE copy_id <> ?`, copyId);
+                    this.sql.exec(`DELETE FROM _substrat_capture WHERE copy_id <> ?`, copyId);
+                    for (const name of inPlace.keys())
+                        this.sql.exec(`DROP TRIGGER IF EXISTS ${quoteIdent(name)}`);
+                    for (const t of triggers)
+                        this.sql.exec(t.sql);
+                }
+                // Page 0 asked again starts the pages over: what was logged since its first read is still
+                // to be sent, and is sent again at worst.
+                this.sql.exec(`INSERT INTO _substrat_capture (copy_id, touched_at, schema, triggers) VALUES (?, ?, ?, ?)
+             ON CONFLICT (copy_id) DO UPDATE SET touched_at = excluded.touched_at, schema = excluded.schema, triggers = excluded.triggers`, copyId, Date.now(), schema, triggers.length);
+            });
+            this.readCaptureClock();
+        }
+        /** Forget the capture `copyId` and its log (#2450), leaving the tables and triggers. Untracked, in the caller's run. */
+        forgetCapture(copyId) {
+            this.sql.exec(`DELETE FROM _substrat_capture_changes WHERE copy_id = ?`, copyId);
+            this.sql.exec(`DELETE FROM _substrat_capture WHERE copy_id = ?`, copyId);
+        }
+        /**
+         * The unique keys of dumped rowid table `name` (#2450), for the triggers that log a row a
+         * `REPLACE` deletes. A unique index on an expression has no columns to match the incoming row
+         * on, so a capture of its table is refused: that copy is taken at a quiet moment instead.
+         */
+        uniqueKeysOf(name) {
+            const indexes = this.sql.exec(`SELECT name FROM pragma_index_list(?) WHERE "unique" = 1`, name).toArray();
+            return indexes.map(({ name: index }) => {
+                const key = this.sql
+                    .exec(`SELECT cid, name, coll FROM pragma_index_xinfo(?) WHERE key = 1 ORDER BY seqno`, index)
+                    .toArray();
+                if (key.some((c) => Number(c.cid) < 0 || c.name === null)) {
+                    throw substratError('precondition_failed', `${CAPTURE_EXPRESSION_INDEX}: ${name} (${index})`);
+                }
+                return key.map((c) => ({ column: c.name, collation: c.coll }));
+            });
+        }
+        /** What a capture's pages read the schema as (#2450): the dumped tables and their explicit indexes. */
+        captureSchema(defs) {
+            const names = new Set(defs.map((d) => d.name));
+            const indexes = this.sql.exec(`SELECT tbl_name, name, sql FROM sqlite_master WHERE type = 'index' AND sql IS NOT NULL ORDER BY name`).toArray().filter((i) => names.has(i.tbl_name));
+            return JSON.stringify({ tables: defs, indexes: indexes.map((i) => [i.name, i.sql]) });
+        }
+        /**
+         * The capture `copyId`, renewed, as its pages read the schema (#2450). Refused when it is gone.
+         * Ended and refused when a table or an index was added, dropped or altered since its first
+         * page (no trigger logs a table it did not see, and a table altered under it no longer reads as
+         * its pages did), or when a capture trigger is missing: a table dropped and made again with the
+         * same schema took its triggers with it, and nothing logged its writes since.
+         */
+        heldCapture(copyId, defs) {
+            const row = this.revision.untracked(() => this.hasTable('_substrat_capture')
+                ? this.sql.exec(`SELECT schema, triggers FROM _substrat_capture WHERE copy_id = ?`, copyId).toArray()[0]
+                : undefined);
+            if (!row)
+                throw substratError('precondition_failed', CAPTURE_GONE);
+            const triggers = Number(this.sql.exec(`SELECT COUNT(*) AS n FROM sqlite_master WHERE type = 'trigger' AND name GLOB '${CAPTURE_GLOB}'`).toArray()[0].n);
+            if (row.schema !== this.captureSchema(defs) || triggers !== Number(row.triggers)) {
+                this.endCapture(copyId);
+                throw substratError('precondition_failed', CAPTURE_SCHEMA_MOVED);
+            }
+            this.revision.untracked(() => this.sql.exec(`UPDATE _substrat_capture SET touched_at = ? WHERE copy_id = ?`, Date.now(), copyId));
+            this.readCaptureClock();
+        }
+        /**
+         * One batch of what was written since the capture `copyId` opened (#2450), read in one turn.
+         *
+         * Batch `seq` acknowledges every batch before it: their rows leave the log. A batch asked for
+         * again under the same `seq` (its answer was lost) is served afresh, from the rows as they are
+         * now. A row written after a batch served it is logged again, so a later batch serves it again.
+         * Each row is read as it is now: present, it is put in place by its rowid; gone, it is deleted.
+         * A table read by offset is logged as a whole and sent whole.
+         *
+         * The batch that leaves nothing in the log is `final`: read in the same turn as the log ran
+         * empty, so nothing was written between it and the moment its `revision` names, and the capture
+         * ends with it (its triggers too, when it was the last).
+         */
+        exportDumpChanges(copyId, seq, opts = {}) {
+            return replyOf(() => this.captureChanges(copyId, seq, opts.maxBytes ?? SCOPE_DUMP_PAGE_MAX_BYTES));
+        }
+        captureChanges(copyId, seq, maxBytes) {
+            if (!Number.isSafeInteger(seq) || seq < 0)
+                throw substratError('validation_failed', 'a change batch is numbered from 0');
+            const defs = this.dumpTableDefs();
+            this.heldCapture(copyId, defs);
+            const sqlOf = new Map(defs.map((d) => [d.name, d.sql]));
+            return this.revision.untracked(() => {
+                this.sql.exec(`DELETE FROM _substrat_capture_changes WHERE copy_id = ? AND batch < ?`, copyId, seq);
+                this.sql.exec(`UPDATE _substrat_capture_changes SET batch = NULL WHERE copy_id = ? AND batch >= ?`, copyId, seq);
+                const logged = this.sql
+                    .exec(`SELECT tbl, rid FROM _substrat_capture_changes WHERE copy_id = ? ORDER BY tbl, rid LIMIT ?`, copyId, CAPTURE_BATCH_ROWS)
+                    .toArray();
+                const byTable = new Map();
+                for (const { tbl, rid } of logged) {
+                    const rids = byTable.get(tbl) ?? [];
+                    rids.push(Number(rid));
+                    byTable.set(tbl, rids);
+                }
+                const tables = [];
+                let bytes = 0;
+                for (const [name, rids] of byTable) {
+                    if (bytes >= maxBytes)
+                        break;
+                    const ddl = sqlOf.get(name);
+                    const { columns, byRowid } = this.tableShape(name, ddl);
+                    const { where, bindings } = dumpRowFilter(name);
+                    const served = [];
+                    if (!byRowid) {
+                        const rows = Array.from(this.sql.exec(`SELECT * FROM ${quoteIdent(name)} WHERE ${where}`, ...bindings).raw(), (r) => r);
+                        for (const row of rows)
+                            bytes += rowBytes(row);
+                        tables.push({ name, ddl, columns, rows, deleted: [] });
+                        served.push(...rids);
+                    }
+                    else {
+                        const change = { name, ddl, columns, rows: [], rowids: [], deleted: [] };
+                        for (let i = 0; i < rids.length && bytes < maxBytes; i += CAPTURE_IN_CHUNK) {
+                            const chunk = rids.slice(i, i + CAPTURE_IN_CHUNK);
+                            const found = new Map();
+                            for (const cells of this.sql
+                                .exec(`SELECT rowid, * FROM ${quoteIdent(name)} WHERE (${where}) AND rowid IN (${chunk.map(() => '?').join(', ')})`, ...bindings, ...chunk)
+                                .raw()) {
+                                found.set(Number(cells[0]), cells.slice(1));
+                            }
+                            for (const rid of chunk) {
+                                if (bytes >= maxBytes)
+                                    break;
+                                const row = found.get(rid);
+                                if (row) {
+                                    change.rows.push(row);
+                                    change.rowids.push(rid);
+                                    bytes += rowBytes(row);
+                                }
+                                else {
+                                    change.deleted.push(rid);
+                                    bytes += 24;
+                                }
+                                served.push(rid);
+                            }
+                        }
+                        tables.push(change);
+                    }
+                    for (let i = 0; i < served.length; i += CAPTURE_IN_CHUNK) {
+                        const chunk = served.slice(i, i + CAPTURE_IN_CHUNK);
+                        this.sql.exec(`UPDATE _substrat_capture_changes SET batch = ? WHERE copy_id = ? AND tbl = ? AND rid IN (${chunk.map(() => '?').join(', ')})`, seq, copyId, name, ...chunk);
+                    }
+                }
+                const left = this.sql.exec(`SELECT 1 FROM _substrat_capture_changes WHERE copy_id = ? AND batch IS NULL LIMIT 1`, copyId).toArray();
+                const final = left.length === 0;
+                if (final)
+                    this.endCapture(copyId);
+                return { tables, final, revision: this.metaValue(WRITE_REVISION_KEY) };
+            });
+        }
+        /**
+         * End the capture `copyId` (#2450), if it is open: a copy that finished, failed or was cancelled
+         * calls it. The last capture to end takes the log and every trigger with it.
+         */
+        endDumpCapture(copyId) {
+            return { ended: this.endCapture(copyId) };
+        }
+        endCapture(copyId) {
+            const ended = this.revision.untracked(() => {
+                if (!this.hasTable('_substrat_capture'))
+                    return false;
+                this.sql.exec(`DELETE FROM _substrat_capture_changes WHERE copy_id = ?`, copyId);
+                const gone = this.sql.exec(`DELETE FROM _substrat_capture WHERE copy_id = ? RETURNING copy_id`, copyId).toArray().length > 0;
+                this.dropCaptureIfIdle();
+                return gone;
+            });
+            this.readCaptureClock();
+            return ended;
+        }
+        /** With no capture left open, drop the log, the capture table and every capture trigger. */
+        dropCaptureIfIdle() {
+            if (this.sql.exec(`SELECT 1 FROM _substrat_capture LIMIT 1`).toArray().length > 0)
+                return;
+            const triggers = this.sql
+                .exec(`SELECT name FROM sqlite_master WHERE type = 'trigger' AND name GLOB '${CAPTURE_GLOB}'`)
+                .toArray();
+            for (const { name } of triggers)
+                this.sql.exec(`DROP TRIGGER IF EXISTS ${quoteIdent(name)}`);
+            this.sql.exec(`DROP TABLE IF EXISTS _substrat_capture_changes`);
+            this.sql.exec(`DROP TABLE IF EXISTS _substrat_capture`);
+        }
+        /** Read when the oldest open capture goes idle (`captureIdleAt`). */
+        readCaptureClock() {
+            const oldest = this.revision.untracked(() => this.hasTable('_substrat_capture')
+                ? this.sql.exec(`SELECT MIN(touched_at) AS t FROM _substrat_capture`).toArray()[0]?.t ?? null
+                : null);
+            this.captureIdleAt = oldest === null ? null : Number(oldest) + CAPTURE_IDLE_MS;
+        }
+        /**
+         * Run before every write (#2450, the write revision's `beforeWrite`): a capture nobody has asked
+         * for in `CAPTURE_IDLE_MS` belongs to a copy that stopped, so it ends here, before the write its
+         * triggers would log. Once the clock is read this is one comparison per write; the clock is read
+         * on the first write after a wake, a load, or an expiry.
+         *
+         * No DDL here: the write this runs before may hold a read cursor open (a module iterating a
+         * table and writing as it goes), and a DROP under one fails that write (SQLITE_LOCKED). Only the
+         * idle captures' rows go; a trigger with no capture to log for logs nothing, and the triggers and
+         * tables are dropped in a turn of their own (`dropIdleCaptureLater`).
+         */
+        expireIdleCaptures() {
+            if (this.captureIdleAt === undefined)
+                this.readCaptureClock();
+            if (this.captureIdleAt === null || this.captureIdleAt === undefined || Date.now() < this.captureIdleAt)
+                return;
+            this.revision.untracked(() => {
+                // A load took the capture's tables with it: there is nothing left to end.
+                if (!this.hasTable('_substrat_capture'))
+                    return;
+                const idle = this.sql
+                    .exec(`SELECT copy_id FROM _substrat_capture WHERE touched_at <= ?`, Date.now() - CAPTURE_IDLE_MS)
+                    .toArray();
+                for (const { copy_id } of idle)
+                    this.forgetCapture(copy_id);
+            });
+            // Read again at the next write, not now: should the write's own transaction roll back, the
+            // capture is back, and the next write ends it again.
+            this.captureIdleAt = undefined;
+            this.dropIdleCaptureLater();
+        }
+        /**
+         * Drop the capture's triggers and tables once no capture is open (#2450), after the current
+         * turn: never under the write that ended the last capture. Best effort: one that fails (a cursor
+         * still open across an await) leaves them to the next capture call or the next wake, and a
+         * trigger with no capture to log for costs a write only an empty lookup meanwhile.
+         */
+        dropIdleCaptureLater() {
+            setTimeout(() => {
+                try {
+                    this.revision.untracked(() => {
+                        if (this.hasTable('_substrat_capture'))
+                            this.dropCaptureIfIdle();
+                    });
+                }
+                catch {
+                    // Left to the next capture call or wake, as above.
+                }
+            }, 0);
+        }
         /**
          * `exportDump`, with the store's load stamp read in the same call (#1722): the stamp a
          * carry's fenced wipe of this copy later expects. A store no load has stamped gets one now,
@@ -5918,6 +6333,8 @@ options = {}) {
                 }
             });
             this.carriedAwayCopy = this.metaValue(CARRIED_AWAY_KEY) !== null;
+            // #2450: the drops took any capture with them; its clock is read again at the next write.
+            this.captureIdleAt = undefined;
             // #1335 / #1686: the outbox arrived with the dump, so this DO's event ids resume above it,
             // as on a wake. A copy's own events then sort above every copied one, which is what
             // `emittedHere()` relies on. A dump whose top id is no ULID leaves the floor where it was.
@@ -6073,9 +6490,6 @@ options = {}) {
                     if (seq > head.nextSeq) {
                         throw substratError('precondition_failed', `stage page ${seq} arrived before page ${head.nextSeq}`);
                     }
-                    // #2314: a page carrying an attachment row this store condemned is refused here, at the
-                    // page, as the commit refuses it again before its first drop (`loadTables`).
-                    refuseCondemnedInDump(doSpineSql(this.sql), tables);
                     for (const t of tables) {
                         const columns = JSON.stringify(t.columns);
                         let held = this.sql
@@ -6091,13 +6505,81 @@ options = {}) {
                         else if (held.ddl !== t.ddl || held.columns !== columns) {
                             throw substratError('precondition_failed', `table ${t.name} changed between dump pages; nothing more was staged`);
                         }
-                        const insert = `INSERT INTO "${stageRowsTable(held.ord)}" VALUES (${t.columns.map(() => '?').join(', ')})`;
-                        for (const row of t.rows) {
-                            if (row.length !== t.columns.length) {
-                                throw substratError('validation_failed', `a row of ${t.name} has ${row.length} cells for ${t.columns.length} columns`);
-                            }
-                            this.sql.exec(insert, ...row);
+                        this.stageRows(held.ord, t);
+                    }
+                    this.sql.exec(`UPDATE _substrat_stage SET next_seq = ?`, seq + 1);
+                    return { staged: true };
+                });
+            }
+            finally {
+                this.revisionSuspended = false;
+            }
+        }
+        /**
+         * Put a fragment's rows into staged table `ord` (#2450). With `rowids` each row is staged under
+         * its source rowid, replacing the one staged there: a capture's page and its changes name rows
+         * that way, and the commit reads the stage in rowid order, so the rows load in the source's order.
+         */
+        stageRows(ord, t) {
+            // #2314: a fragment carrying an attachment row this store condemned is refused here, as it
+            // arrives, and the commit refuses it again before its first drop (`loadTables`).
+            refuseCondemnedInDump(doSpineSql(this.sql), [t]);
+            if (t.rowids && t.rowids.length !== t.rows.length) {
+                throw substratError('validation_failed', `${t.name} has ${t.rowids.length} rowids for ${t.rows.length} rows`);
+            }
+            const marks = t.columns.map(() => '?').join(', ');
+            const insert = t.rowids
+                ? `INSERT OR REPLACE INTO "${stageRowsTable(ord)}" (rowid, ${t.columns.map((_, i) => `c${i}`).join(', ')}) VALUES (?, ${marks})`
+                : `INSERT INTO "${stageRowsTable(ord)}" VALUES (${marks})`;
+            for (const [i, row] of t.rows.entries()) {
+                if (row.length !== t.columns.length) {
+                    throw substratError('validation_failed', `a row of ${t.name} has ${row.length} cells for ${t.columns.length} columns`);
+                }
+                if (t.rowids)
+                    this.sql.exec(insert, t.rowids[i], ...row);
+                else
+                    this.sql.exec(insert, ...row);
+            }
+        }
+        /**
+         * Apply one batch of a capture's changes to the stage (#2450): numbered in the same sequence as
+         * the stage's pages, after the last of them, and as idempotent: a batch already applied answers
+         * `staged: false`. A change with `rowids` puts its rows in place and deletes `deleted` by rowid;
+         * one without replaces its table whole. A table no page staged, or staged with another schema,
+         * is refused: the source's schema moved, and the copy starts again.
+         */
+        stageDumpChanges(stageId, seq, tables) {
+            return replyOf(() => this.stageChanges(stageId, seq, tables));
+        }
+        stageChanges(stageId, seq, tables) {
+            if (!Number.isSafeInteger(seq) || seq < 1)
+                throw substratError('validation_failed', 'a change batch follows a stage\'s first page');
+            assertReplayableDump(tables, { maxColumns: DO_SQL_LIMITS.columns });
+            this.revisionSuspended = true;
+            try {
+                return this.revision.transactionSync(() => {
+                    const head = this.stageHead();
+                    if (head?.stageId !== stageId)
+                        throw substratError('precondition_failed', STAGE_GONE);
+                    if (seq < head.nextSeq)
+                        return { staged: false };
+                    if (seq > head.nextSeq)
+                        throw substratError('precondition_failed', `stage page ${seq} arrived before page ${head.nextSeq}`);
+                    for (const t of tables) {
+                        const held = this.sql
+                            .exec(`SELECT ord, ddl, columns FROM _substrat_stage_tables WHERE name = ?`, t.name)
+                            .toArray()[0];
+                        if (!held || held.ddl !== t.ddl || held.columns !== JSON.stringify(t.columns)) {
+                            throw substratError('precondition_failed', `table ${t.name} changed since its pages were staged; nothing more was staged`);
+                        }
+                        const rows = `"${stageRowsTable(held.ord)}"`;
+                        if (!t.rowids)
+                            this.sql.exec(`DELETE FROM ${rows}`);
+                        for (let i = 0; i < t.deleted.length; i += CAPTURE_IN_CHUNK) {
+                            const chunk = t.deleted.slice(i, i + CAPTURE_IN_CHUNK);
+                            this.sql.exec(`DELETE FROM ${rows} WHERE rowid IN (${chunk.map(() => '?').join(', ')})`, ...chunk);
                         }
+                        this.stageRows(held.ord, t);
                     }
                     this.sql.exec(`UPDATE _substrat_stage SET next_seq = ?`, seq + 1);
                     return { staged: true };
@@ -6149,11 +6631,14 @@ options = {}) {
         }
         /** One staged table's rows, in the order they were staged, a batch at a time. */
         *stagedRows(ord) {
-            let after = 0;
+            // No lower bound on the first batch: a row staged under its source rowid (#2450) may sit at 0
+            // or below.
+            let after = null;
             for (;;) {
-                const batch = Array.from(this.sql
-                    .exec(`SELECT rowid, * FROM "${stageRowsTable(ord)}" WHERE rowid > ? ORDER BY rowid LIMIT ?`, after, STAGE_READ_BATCH)
-                    .raw(), (row) => row);
+                const table = `"${stageRowsTable(ord)}"`;
+                const batch = Array.from((after === null
+                    ? this.sql.exec(`SELECT rowid, * FROM ${table} ORDER BY rowid LIMIT ?`, STAGE_READ_BATCH)
+                    : this.sql.exec(`SELECT rowid, * FROM ${table} WHERE rowid > ? ORDER BY rowid LIMIT ?`, after, STAGE_READ_BATCH)).raw(), (row) => row);
                 for (const row of batch)
                     yield row.slice(1);
                 if (batch.length < STAGE_READ_BATCH)