@substrat-run/kernel 0.120.0 → 0.122.0

package/dist/version-migrations.js

@@ -0,0 +1,187 @@
+/**
+ * A version's SQL migrations, stored apart from its manifest (#1764), shared by both adapters.
+ *
+ * Since #1677 a pushed deploy manifest carries its whole cumulative migration set
+ * (`migrations: { moduleId, version, sql }[]`). The manifest is one `manifest_json` column on
+ * `vertical_versions`, so every read of a version moved that SQL too: `readVersion` on every
+ * admit, promote and bind, and every `storedDeployManifest.parse` behind `/registry`, `/model`,
+ * `/schedules` and the serving upload. Only the promote review reads the SQL.
+ *
+ * So `publishVersion` splits the field off: the SQL goes to `vertical_version_migrations`, one
+ * row per migration, and the manifest is stored without it. The wire is unchanged, since the
+ * CLI still sends `migrations` inside the manifest. Two columns on `vertical_versions` carry
+ * what the rows alone cannot:
+ *
+ * - `migration_count`: how many rows the version stored. **NULL means the version carries no
+ *   SQL** (pushed before #1677, over the push's caps, or malformed), which a reader must show
+ *   as "not available", never as "no migrations". `0` is a version whose modules ship none. A
+ *   read whose row count disagrees with it answers null rather than a short list.
+ * - `migrations_split`: 1 once the version's SQL is out of its manifest. NULL is a version
+ *   stored before this, whose manifest may still carry it. The backfill below moves those a
+ *   bounded batch at a time, and until it reaches a version the read falls back to that
+ *   version's manifest. The fallback is only for those rows. A version published by this code
+ *   is split on the way in.
+ */
+import { deployManifest, storedDeployManifest, } from '@substrat-run/contracts';
+/**
+ * The table, and the index the backfill walks. Interpolated into both adapters' directory DDL,
+ * so `lint:spine-ddl` sees one spelling on each side. Anything that references this table or
+ * this index goes in this fragment, which is what the adapters run after their column additions.
+ *
+ * The index is partial: it holds only versions still waiting for the backfill, so "is there
+ * anything left" is one probe that costs nothing once the backfill is done. It names a column
+ * a directory from before #1764 lacks, so the adapters run these statements after their
+ * column additions, not in their DDL loop.
+ */
+export const VERSION_MIGRATIONS_DDL = `
+  CREATE TABLE IF NOT EXISTS vertical_version_migrations (
+    version_id TEXT NOT NULL,
+    -- The migration's place in the order the host runs them, from 0.
+    ordinal    INTEGER NOT NULL,
+    module_id  TEXT NOT NULL,
+    -- The module's SqlMigration.version, e.g. 0001-init.
+    version    TEXT NOT NULL,
+    sql        TEXT NOT NULL,
+    PRIMARY KEY (version_id, ordinal)
+  );
+  CREATE INDEX IF NOT EXISTS vertical_versions_unsplit
+    ON vertical_versions (id) WHERE migrations_split IS NULL;
+`;
+/**
+ * Take `migrations` out of a manifest.
+ *
+ * `push` holds the field to the push boundary's caps (`deployManifest`): at most 2000 entries
+ * and 512 KiB of SQL, which also bounds every row under a Durable Object's 2 MB row limit.
+ * `/deploy` already refuses an over-cap set, before the upload, because it parses the whole
+ * manifest with `deployManifest`. This split caps whatever reaches `publishVersion` by any
+ * route, including `POST /verticals/:slug/versions`, which stores `manifestJson` unparsed
+ * (#1765). There, a field over the caps or not shaped like migrations is dropped and the
+ * version reads as "SQL not available", so the promote dialog still asks. `stored` is for a
+ * manifest already in the directory, whose history the caps must never make unreadable
+ * (`storedDeployManifest`).
+ *
+ * A manifest that is not a JSON object is returned as it came, with no migrations. The
+ * manifest is only rewritten when it has a `migrations` key to remove.
+ */
+export function splitManifestMigrations(manifestJson, mode) {
+    if (manifestJson === null)
+        return { manifestJson, migrations: null };
+    let parsed;
+    try {
+        parsed = JSON.parse(manifestJson);
+    }
+    catch {
+        return { manifestJson, migrations: null };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed) || !('migrations' in parsed)) {
+        return { manifestJson, migrations: null };
+    }
+    const { migrations: carried, ...rest } = parsed;
+    const schema = (mode === 'push' ? deployManifest : storedDeployManifest).shape.migrations;
+    const result = schema.safeParse(carried);
+    return {
+        manifestJson: JSON.stringify(rest),
+        migrations: result.success && result.data !== undefined ? result.data : null,
+    };
+}
+/** Replace one version's migration rows. The caller sets its `migration_count` and `migrations_split`. */
+export function writeVersionMigrations(db, versionId, migrations) {
+    db.run('DELETE FROM vertical_version_migrations WHERE version_id = ?', versionId);
+    (migrations ?? []).forEach((m, ordinal) => {
+        db.run(`INSERT INTO vertical_version_migrations (version_id, ordinal, module_id, version, sql)
+       VALUES (?, ?, ?, ?, ?)`, versionId, ordinal, m.moduleId, m.version, m.sql);
+    });
+}
+/**
+ * The two reads that find unsplit versions. Named so the kernel's test can EXPLAIN these
+ * exact strings: each must be answered from `vertical_versions_unsplit`, never by a scan of
+ * every version's row (and its manifest's overflow pages).
+ */
+export const UNSPLIT_IDS_SQL = 'SELECT id FROM vertical_versions WHERE migrations_split IS NULL ORDER BY id LIMIT ?';
+export const UNSPLIT_PROBE_SQL = 'SELECT 1 AS present FROM vertical_versions WHERE migrations_split IS NULL LIMIT 1';
+/** How many versions one backfill batch moves at most. */
+const BATCH_VERSIONS = 25;
+/**
+ * How much manifest one batch reads at most, in UTF-8 bytes (the first version is always
+ * moved). A stored manifest can be up to about 1.5 MiB, and a batch holds the directory DO.
+ * Bytes, because what a batch costs is the bytes it reads: a manifest of four-byte characters
+ * is four times its character count.
+ */
+export const BATCH_MANIFEST_BYTES = 4 * 1024 * 1024;
+/**
+ * Move the SQL out of the next versions stored before #1764: at most `limit` of them, and
+ * at most `BATCH_MANIFEST_BYTES` of manifest. Returns how many it moved, and whether any are
+ * left.
+ *
+ * Bounded so that no one run has to read the whole version history: the Durable-Object
+ * adapter runs one batch per alarm and re-arms while any are left, so its constructor never
+ * does per-version work. Resumable because each version is marked as it is moved, in the
+ * caller's transaction with its rows. A version is moved by the same `splitManifestMigrations`
+ * a push goes through, in `stored` mode, so history is read without the push caps.
+ *
+ * Idempotent: a version that is already split is never selected, and moving one replaces its
+ * rows. A directory restored from a dump taken before the backfill comes back unsplit and is
+ * simply moved again.
+ */
+export function splitVersionMigrationsBatch(db, limit = BATCH_VERSIONS) {
+    // The ids come off the partial index alone; each manifest is read only when it is moved.
+    const ids = db.all(UNSPLIT_IDS_SQL, limit);
+    let moved = 0;
+    let bytes = 0;
+    for (const { id } of ids) {
+        // The candidate is measured before it is taken, so a batch never passes the bound by one
+        // more manifest. The first is always taken, or a manifest over the bound would never move.
+        // `octet_length` (SQLite 3.43+) counts bytes; `length` would count code points.
+        const { size } = db.all('SELECT COALESCE(octet_length(manifest_json), 0) AS size FROM vertical_versions WHERE id = ?', id)[0];
+        if (moved > 0 && bytes + size > BATCH_MANIFEST_BYTES)
+            break;
+        bytes += size;
+        const { manifest_json: stored } = db.all('SELECT manifest_json FROM vertical_versions WHERE id = ?', id)[0];
+        const split = splitManifestMigrations(stored, 'stored');
+        writeVersionMigrations(db, id, split.migrations);
+        const count = split.migrations?.length ?? null;
+        // A manifest with nothing taken out is left where it is, not rewritten.
+        if (split.manifestJson === stored) {
+            db.run('UPDATE vertical_versions SET migration_count = ?, migrations_split = 1 WHERE id = ?', count, id);
+        }
+        else {
+            db.run('UPDATE vertical_versions SET manifest_json = ?, migration_count = ?, migrations_split = 1 WHERE id = ?', split.manifestJson, count, id);
+        }
+        moved++;
+    }
+    return { moved, more: versionsAwaitSplit(db) };
+}
+/** Whether any version still waits for the backfill. One probe of the partial index. */
+export function versionsAwaitSplit(db) {
+    return db.all(UNSPLIT_PROBE_SQL).length > 0;
+}
+/**
+ * One version's migrations, in the order the host runs them. `undefined` when there is no
+ * such version. `migrations` is null when the version carries none that can be shown, which
+ * a reader must say as "not available", never as "no migrations".
+ */
+export function versionMigrationsOf(db, versionId) {
+    // The manifest is read only for a version the backfill has not reached: its SQL, if any,
+    // is still in there. A split version's manifest carries none, so it is left unread.
+    const row = db.all(`SELECT vertical_slug, migration_count, migrations_split,
+            CASE WHEN migrations_split IS NULL THEN manifest_json END AS manifest_json
+       FROM vertical_versions WHERE id = ?`, versionId)[0];
+    if (!row)
+        return undefined;
+    if (row.migrations_split === null) {
+        return { verticalSlug: row.vertical_slug, migrations: splitManifestMigrations(row.manifest_json, 'stored').migrations };
+    }
+    if (row.migration_count === null)
+        return { verticalSlug: row.vertical_slug, migrations: null };
+    const rows = db.all(`SELECT module_id, version, sql FROM vertical_version_migrations
+      WHERE version_id = ? ORDER BY ordinal`, versionId);
+    // Never a short list: rows that disagree with the count are not the version's migrations.
+    if (rows.length !== row.migration_count)
+        return { verticalSlug: row.vertical_slug, migrations: null };
+    return {
+        verticalSlug: row.vertical_slug,
+        // Parsed on the way in (`splitManifestMigrations`), so the brand is the stored value's.
+        migrations: rows.map((r) => ({ moduleId: r.module_id, version: r.version, sql: r.sql })),
+    };
+}
+//# sourceMappingURL=version-migrations.js.map

package/dist/version-migrations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-migrations.js","sourceRoot":"","sources":["../src/version-migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EACL,cAAc,EACd,oBAAoB,GAGrB,MAAM,yBAAyB,CAAC;AAGjC;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;CAarC,CAAC;AAUF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,uBAAuB,CAAC,YAA2B,EAAE,IAAuB;IAC1F,IAAI,YAAY,KAAK,IAAI;QAAE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IACrE,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IAC5C,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,YAAY,IAAI,MAAM,CAAC,EAAE,CAAC;QACxG,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IAC5C,CAAC;IACD,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,MAAiC,CAAC;IAC3E,MAAM,MAAM,GAAG,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC;IAC1F,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IACzC,OAAO;QACL,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;QAClC,UAAU,EAAE,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;KAC7E,CAAC;AACJ,CAAC;AAED,0GAA0G;AAC1G,MAAM,UAAU,sBAAsB,CACpC,EAAa,EACb,SAAiB,EACjB,UAA+C;IAE/C,EAAE,CAAC,GAAG,CAAC,8DAA8D,EAAE,SAAS,CAAC,CAAC;IAClF,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE;QACxC,EAAE,CAAC,GAAG,CACJ;8BACwB,EACxB,SAAS,EAAE,OAAO,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CACjD,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,qFAAqF,CAAC;AACrH,MAAM,CAAC,MAAM,iBAAiB,GAAG,mFAAmF,CAAC;AAErH,0DAA0D;AAC1D,MAAM,cAAc,GAAG,EAAE,CAAC;AAC1B;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAEpD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,2BAA2B,CACzC,EAAa,EACb,KAAK,GAAW,cAAc;IAE9B,yFAAyF;IACzF,MAAM,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,eAAe,EAAE,KAAK,CAAqB,CAAC;IAC/D,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,EAAE,EAAE,EAAE,IAAI,GAAG,EAAE,CAAC;QACzB,yFAAyF;QACzF,2FAA2F;QAC3F,gFAAgF;QAChF,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,GAAG,CACrB,6FAA6F,EAC7F,EAAE,CACH,CAAC,CAAC,CAAqB,CAAC;QACzB,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,IAAI,GAAG,oBAAoB;YAAE,MAAM;QAC5D,KAAK,IAAI,IAAI,CAAC;QACd,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,0DAA0D,EAAE,EAAE,CAAC,CAAC,CAAC,CAEzG,CAAC;QACF,MAAM,KAAK,GAAG,uBAAuB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QACxD,sBAAsB,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,CAAC,UAAU,CAAC,CAAC;QACjD,MAAM,KAAK,GAAG,KAAK,CAAC,UAAU,EAAE,MAAM,IAAI,IAAI,CAAC;QAC/C,wEAAwE;QACxE,IAAI,KAAK,CAAC,YAAY,KAAK,MAAM,EAAE,CAAC;YAClC,EAAE,CAAC,GAAG,CAAC,qFAAqF,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;QAC3G,CAAC;aAAM,CAAC;YACN,EAAE,CAAC,GAAG,CACJ,wGAAwG,EACxG,KAAK,CAAC,YAAY,EAAE,KAAK,EAAE,EAAE,CAC9B,CAAC;QACJ,CAAC;QACD,KAAK,EAAE,CAAC;IACV,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,kBAAkB,CAAC,EAAE,CAAC,EAAE,CAAC;AACjD,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,kBAAkB,CAAC,EAAa;IAC9C,OAAO,EAAE,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,EAAa,EACb,SAAiB;IAEjB,yFAAyF;IACzF,oFAAoF;IACpF,MAAM,GAAG,GAAG,EAAE,CAAC,GAAG,CAChB;;2CAEuC,EACvC,SAAS,CACV,CAAC,CAAC,CAEU,CAAC;IACd,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAC3B,IAAI,GAAG,CAAC,gBAAgB,KAAK,IAAI,EAAE,CAAC;QAClC,OAAO,EAAE,YAAY,EAAE,GAAG,CAAC,aAAa,EAAE,UAAU,EAAE,uBAAuB,CAAC,GAAG,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC,UAAU,EAAE,CAAC;IAC1H,CAAC;IACD,IAAI,GAAG,CAAC,eAAe,KAAK,IAAI;QAAE,OAAO,EAAE,YAAY,EAAE,GAAG,CAAC,aAAa,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IAC/F,MAAM,IAAI,GAAG,EAAE,CAAC,GAAG,CACjB;4CACwC,EACxC,SAAS,CAC+C,CAAC;IAC3D,0FAA0F;IAC1F,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG,CAAC,eAAe;QAAE,OAAO,EAAE,YAAY,EAAE,GAAG,CAAC,aAAa,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IACtG,OAAO;QACL,YAAY,EAAE,GAAG,CAAC,aAAa;QAC/B,wFAAwF;QACxF,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,SAAqB,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;KACrG,CAAC;AACJ,CAAC"}

package/dist/vertical-events.d.ts

@@ -23,10 +23,11 @@
  * production builds them, and one definition is what keeps the two identical.
  * `lint:spine-ddl` holds each adapter to including it.
  */
-import { type EventExport, type ModuleManifest, type ExportedBatch, type WantedEvent, type WithheldEvent } from '@substrat-run/contracts';
+import { type ImportCursorMove, type ImportCursorMoved, type ScopeId, type TenantId, type VerticalResolution, type EventExport, type ModuleManifest, type ExportedBatch, type WantedEvent, type WithheldEvent } from '@substrat-run/contracts';
 import { type OutboxEnvelopeRow } from './outbox-event.js';
 import type { ImportHandler } from './scope-host.js';
-export declare const VERTICAL_EVENTS_DDL = "\n  -- #1705: every event this scope has received from another vertical. The envelope only, and\n  -- never the payload. The producer's outbox keeps the one copy, where erasure already reaches.\n  CREATE TABLE IF NOT EXISTS _substrat_imports (\n    -- The PRODUCER's event id. A ULID the producer's host minted, so it is unique across\n    -- every source this scope imports from, and it is the dedupe key: a batch delivered\n    -- twice finds its events here and its handlers' journal rows in _substrat_deliveries.\n    event_id TEXT PRIMARY KEY,\n    source_scope_id TEXT NOT NULL,\n    source_vertical TEXT NOT NULL,\n    type TEXT NOT NULL,\n    schema_version INTEGER NOT NULL,\n    occurred_at TEXT NOT NULL,\n    entity_type TEXT NOT NULL,\n    entity_id TEXT NOT NULL,\n    -- How many vertical boundaries this event's cause chain has crossed, this one included.\n    -- An export read in THIS scope counts from here when one of its own events was caused by\n    -- an import, which is how a loop between two verticals is stopped.\n    hops INTEGER NOT NULL,\n    -- NULL: released, and handed to this scope's handlers. Otherwise the producer's reason\n    -- for NOT releasing it ('pii', 'version', 'cascade', 'undecodable'). Such a row was\n    -- named but never carried.\n    withheld TEXT,\n    imported_at TEXT NOT NULL\n  );\n  -- #1705: how far this scope has read each producer. Written in the same store as the\n  -- handlers' writes, so a restore of this scope rewinds the watermark with the data and the\n  -- producer re-delivers what the restore undid. A watermark the platform held instead would\n  -- skip it.\n  CREATE TABLE IF NOT EXISTS _substrat_import_cursors (\n    source_scope_id TEXT PRIMARY KEY,\n    source_vertical TEXT NOT NULL,\n    -- The id of the last producer row the reads walked (released or withheld). NULL is not\n    -- stored: a producer with no row here has never been read, which the absence says.\n    cursor TEXT NOT NULL,\n    updated_at TEXT NOT NULL\n  );\n  -- #1705: the export read, on the PRODUCER side. It asks for a few types after a watermark,\n  -- in id order. Without this index SQLite walks the primary key from the watermark forward and\n  -- steps over every row of every other type. A consumer that is caught up would then pay, on\n  -- every pass, for all the unexported activity since the last exported event. With it, the read\n  -- seeks each type's range and costs what it returns.\n  CREATE INDEX IF NOT EXISTS _substrat_outbox_type_id ON _substrat_outbox (type, id);\n";
+import type { SwitchSql } from './system-switch.js';
+export declare const VERTICAL_EVENTS_DDL = "\n  -- #1705: every event this scope has received from another vertical. The envelope only, and\n  -- never the payload. The producer's outbox keeps the one copy, where erasure already reaches.\n  CREATE TABLE IF NOT EXISTS _substrat_imports (\n    -- The PRODUCER's event id. A ULID the producer's host minted, so it is unique across\n    -- every source this scope imports from, and it is the dedupe key: a batch delivered\n    -- twice finds its events here and its handlers' journal rows in _substrat_deliveries.\n    event_id TEXT PRIMARY KEY,\n    source_scope_id TEXT NOT NULL,\n    source_vertical TEXT NOT NULL,\n    type TEXT NOT NULL,\n    schema_version INTEGER NOT NULL,\n    occurred_at TEXT NOT NULL,\n    entity_type TEXT NOT NULL,\n    entity_id TEXT NOT NULL,\n    -- How many vertical boundaries this event's cause chain has crossed, this one included.\n    -- An export read in THIS scope counts from here when one of its own events was caused by\n    -- an import, which is how a loop between two verticals is stopped.\n    hops INTEGER NOT NULL,\n    -- NULL: released, and handed to this scope's handlers. Otherwise the producer's reason\n    -- for NOT releasing it ('pii', 'version', 'cascade', 'undecodable'). Such a row was\n    -- named but never carried.\n    withheld TEXT,\n    imported_at TEXT NOT NULL\n  );\n  -- #1705: how far this scope has read each producer. Written in the same store as the\n  -- handlers' writes, so a restore of this scope rewinds the watermark with the data and the\n  -- producer re-delivers what the restore undid. A watermark the platform held instead would\n  -- skip it.\n  CREATE TABLE IF NOT EXISTS _substrat_import_cursors (\n    source_scope_id TEXT PRIMARY KEY,\n    source_vertical TEXT NOT NULL,\n    -- The id of the last producer row the reads walked (released or withheld). NULL is not\n    -- stored: a producer with no row here has never been read, which the absence says.\n    cursor TEXT NOT NULL,\n    updated_at TEXT NOT NULL\n  );\n  -- #1705: the export read, on the PRODUCER side. It asks for a few types after a watermark,\n  -- in id order. Without this index SQLite walks the primary key from the watermark forward and\n  -- steps over every row of every other type. A consumer that is caught up would then pay, on\n  -- every pass, for all the unexported activity since the last exported event. With it, the read\n  -- seeks each type's range and costs what it returns.\n  CREATE INDEX IF NOT EXISTS _substrat_outbox_type_id ON _substrat_outbox (type, id);\n  -- #1705 PR 3: what a REPLAY moved out of the live journal. A replay re-delivers events this\n  -- scope already took, and the live tables are also the dedupe (a row in _substrat_deliveries\n  -- means \"do not run this handler again\"). So the rows for the replayed range leave them. They\n  -- are moved here rather than dropped, because they are the record that a handler ran on an\n  -- event, when, and what it reported: evidence the spine keeps. One row per moved row, the\n  -- whole row as JSON under the replay that moved it. Nothing reads this to deliver.\n  -- ERASURE: today no erasure path touches imported copies, because only piiClass 'none' crosses\n  -- and the delivery-error rewrite (#1632) reaches only this scope's OWN outbox events. If a\n  -- consumer-side erasure of imported copies is ever added, it must reach `row` here too (a\n  -- moved delivery row's `error` is a handler's own sentence), or the history keeps what the\n  -- live tables gave up. Follow-up: #1757.\n  CREATE TABLE IF NOT EXISTS _substrat_import_replays (\n    -- The act (a ULID). The admin log's row for the replay carries the same id.\n    replay_id TEXT NOT NULL,\n    replayed_at TEXT NOT NULL,\n    source_scope_id TEXT NOT NULL,\n    -- 'journal': a _substrat_imports row. 'delivery': a _substrat_deliveries row.\n    kind TEXT NOT NULL,\n    event_id TEXT NOT NULL,\n    -- The handler's module on a 'delivery' row, and '' on a 'journal' row.\n    consumer_module TEXT NOT NULL,\n    row TEXT NOT NULL,\n    PRIMARY KEY (replay_id, kind, event_id, consumer_module)\n  );\n";
 /**
  * The producer-side read: rows of the given types after the watermark, oldest first.
  *
@@ -96,6 +97,27 @@ export declare function exportsOf(manifests: readonly {
         exports?: readonly EventExport[];
     };
 }[]): Map<string, EventExport>;
+/**
+ * The outbox's insertion mark (#1705 PR 2): the kick's "before", taken ahead of an invoke.
+ *
+ * `rowid`, not the event id. A ULID minted in the same millisecond as the newest row can sort
+ * BELOW it, so "ids above the newest id" can miss an event this invoke wrote. SQLite assigns a
+ * new row `max(rowid) + 1` while the newest row is still there. No code path deletes outbox rows
+ * inside an invoke: the only removals are a restore and a wipe, and they replace the whole table
+ * outside any invocation. So every row the invoke and its consumers add sits above the mark. If
+ * that ever stopped being true, the effect is bounded: an exported event would miss its kick and
+ * wait for the sweep, and no event would be lost or sent twice.
+ */
+export declare const OUTBOX_MARK_SQL = "SELECT COALESCE(MAX(rowid), 0) AS mark FROM _substrat_outbox";
+/**
+ * How many rows of the exported `types` were added after `mark` (#1705 PR 2). This is the
+ * count `ScopeStubOptions.onExportedEvents` reports. A seek on the rowid, so it walks only
+ * what the invoke added. Callers skip it entirely when the deployment exports nothing.
+ */
+export declare function exportedSinceQuery(types: readonly string[], mark: number): {
+    sql: string;
+    params: unknown[];
+};
 /** The consumer's watermark per producer, oldest source first. */
 export declare const IMPORT_CURSORS_SQL = "SELECT source_scope_id, source_vertical, cursor, updated_at FROM _substrat_import_cursors ORDER BY source_scope_id";
 /** One producer's watermark, for the compare-and-set a batch is applied under. */
@@ -115,6 +137,74 @@ export declare const IMPORT_CURSOR_ADVANCE_SQL = "\n  INSERT INTO _substrat_impo
  * `imported_at` forward or rewrite what was withheld and why.
  */
 export declare const IMPORT_RECORD_SQL = "\n  INSERT OR IGNORE INTO _substrat_imports\n    (event_id, source_scope_id, source_vertical, type, schema_version, occurred_at,\n     entity_type, entity_id, hops, withheld, imported_at)\n  VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)\n";
+/**
+ * The producer end of the edge a lever moves, resolved by the sweep's own rule (#1705 PR 3).
+ *
+ * Both ends must be their tenant's one primary instance, exactly as `sweepEdge` requires. A
+ * watermark on any other pair is one no pass reads, so a move there would report success and
+ * change nothing. `resolve` is the directory's `resolveVerticalInstance`, and it takes the
+ * CONSUMER's tenant, so a producer in another tenant is not found rather than moved.
+ */
+export declare function importCursorSourceOf(resolve: (tenantId: TenantId, vertical: string) => Promise<VerticalResolution>, consumer: {
+    tenantId: TenantId;
+    scopeId: ScopeId;
+    vertical: string | null;
+}, from: string): Promise<{
+    vertical: string;
+    scopeId: ScopeId;
+}>;
+/**
+ * Move one edge's watermark (#1705 PR 3). The adapter supplies the store (as the switches'
+ * `SwitchSql`), the transaction, the queue, the clock and the act's id. Run on the scope's own
+ * queue, so a pass delivering on the same edge can never interleave with the move. Everything the move decides is decided here, once, for
+ * both adapters.
+ *
+ * Why a bare rewind is not a replay. Three guards stand between an event and a second run of
+ * its handler, and a replay must pass each one on purpose:
+ *
+ *   1. `IMPORT_CURSOR_ADVANCE_SQL` moves the watermark forward only. The lever sets it here.
+ *   2. `_substrat_deliveries` holds a row per (event, module) that ran, and the delivery path
+ *      skips any pair it finds. Rewound but not cleared, every replayed event would come back
+ *      as a `duplicate` and nothing would run.
+ *   3. `_substrat_imports` is `INSERT OR IGNORE`. Left in place, an event first withheld for its
+ *      version would stay recorded as withheld after the consumer's upgrade released it.
+ *
+ * So a replay moves the range's rows in (2) and (3) into `_substrat_import_replays` under
+ * `replayId`, then clears them, then sets the watermark. The evidence stays, and the live tables
+ * take the events again. Two things are true between the move and the redelivery, and are
+ * stated rather than hidden: a cause walk through a moved event's id ends at `missing`, and an
+ * export read in this scope counts fewer hops for a chain through it. Both heal when the next
+ * pass redelivers. The undercount only loosens the loop bound (the hop cap bounds loops, and
+ * authorizes nothing), so a loop may run a round longer; no event crosses that exports, grants
+ * and the PII rule would not already release.
+ *
+ * Refused, with the reason a person reads:
+ * - a replay whose `after` is AHEAD of the watermark (that is a skip), or a skip whose `through`
+ *   is BEHIND it (that is a replay). The acknowledgement names one direction, and it must be
+ *   the direction that moves;
+ * - a skip past now, which would pass over events not yet written while the edge read as
+ *   caught up;
+ * - a replay on an edge that has delivered nothing yet: there is nothing to run again.
+ */
+export declare function moveImportCursor(sql: SwitchSql, input: {
+    move: ImportCursorMove;
+    source: {
+        vertical: string;
+        scopeId: string;
+    };
+    replayId: string;
+    /** Epoch ms: the rows' time, and "now" for a skip, as the watermark's ceiling. */
+    now: number;
+    /**
+     * What the code running this scope imports (`CrossVerticalRegistry.consumes()`). A move names
+     * an edge only if the consumer declares it. Otherwise a skip would plant a watermark for an
+     * edge that does not exist yet, and the backfill of a later version that adds the import would
+     * silently start from it.
+     */
+    imports: readonly {
+        from: string;
+    }[];
+}): ImportCursorMoved;
 /** The note a withheld event's dead letter carries at the consumer. Names the reason, never the content. */
 export declare function withheldNote(reason: WithheldEvent['reason'], vertical: string): string;
 /** One registered import handler: which module, from which vertical, for which (type, version). */
@@ -145,9 +235,13 @@ export declare class CrossVerticalRegistry {
     private readonly exportsByType;
     private readonly importVersion;
     private readonly registered;
+    /** `exportTypes()`, kept current by `register`: an invoke reads it, and must not rebuild a map to. */
+    private exportTypeList;
     register(manifest: Pick<ModuleManifest, 'id' | 'events'>, handlers: Record<string, Record<string, ImportHandler>> | undefined): void;
     /** type → export, over every registered module: what this deployment releases. */
     exports(): Map<string, EventExport>;
+    /** The exported type names (#1705 PR 2), for the per-invoke kick count. Empty: exports nothing. */
+    exportTypes(): readonly string[];
     /** What this deployment imports, one row per (source, type), sorted. */
     consumes(): {
         from: string;

package/dist/vertical-events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vertical-events.d.ts","sourceRoot":"","sources":["../src/vertical-events.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"vertical-events.d.ts","sourceRoot":"","sources":["../src/vertical-events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,aAAa,EAElB,KAAK,WAAW,EAChB,KAAK,aAAa,EACnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAiB,KAAK,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAErD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD,eAAO,MAAM,mBAAmB,+hIAmE/B,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,KAAK,EAAE,MAAM,GACZ;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,EAAE,CAAA;CAAE,CAepC;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,eAAe,0VAU3B,CAAC;AAEF,4FAA4F;AAC5F,MAAM,MAAM,SAAS,GAAG,iBAAiB,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAE1E;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,IAAI,EAAE,SAAS,SAAS,EAAE,CAAC;IAC3B,oDAAoD;IACpD,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,0EAA0E;IAC1E,UAAU,EAAE,CAAC,GAAG,EAAE,SAAS,KAAK,MAAM,CAAC;IACvC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC,CA0D/D;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,EACzC,KAAK,EAAE,SAAS,WAAW,EAAE,GAC5B;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,UAAU,EAAE,WAAW,EAAE,CAAA;CAAE,CAgB7F;AAED,sGAAsG;AACtG,wBAAgB,SAAS,CACvB,SAAS,EAAE,SAAS;IAAE,MAAM,EAAE;QAAE,OAAO,CAAC,EAAE,SAAS,WAAW,EAAE,CAAA;KAAE,CAAA;CAAE,EAAE,GACrE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAI1B;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,iEAAiE,CAAC;AAE9F;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,EAAE,CAAA;CAAE,CAO7G;AAED,kEAAkE;AAClE,eAAO,MAAM,kBAAkB,uHACuF,CAAC;AAEvH,kFAAkF;AAClF,eAAO,MAAM,oBAAoB,0EAA0E,CAAC;AAE5G;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,6VAQrC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,8OAK7B,CAAC;AAIF;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,CAAC,EAC9E,QAAQ,EAAE;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAC3E,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAwBjD;AA8DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,SAAS,EACd,KAAK,EAAE;IACL,IAAI,EAAE,gBAAgB,CAAC;IACvB,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,OAAO,EAAE,SAAS;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACtC,GACA,iBAAiB,CAoEnB;AAED,4GAA4G;AAC5G,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQtF;AAED,mGAAmG;AACnG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,aAAa,CAAC;CACxB;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA2D;IACzF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoE;IAClG,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA0B;IACrD,sGAAsG;IACtG,OAAO,CAAC,cAAc,CAAgB;IAEtC,QAAQ,CACN,QAAQ,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,GAAG,QAAQ,CAAC,EAC/C,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,GAAG,SAAS,GAClE,IAAI,CAiDN;IAED,kFAAkF;IAClF,OAAO,IAAI,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAElC;IAED,mGAAmG;IACnG,WAAW,IAAI,SAAS,MAAM,EAAE,CAE/B;IAED,wEAAwE;IACxE,QAAQ,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,EAAE,CAOlE;IAED,kEAAkE;IAClE,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAE1D;IAED,yGAAyG;IACzG,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAErD;CACF"}