@substrat-run/kernel 0.147.0 → 0.149.0

package/dist/version-migrations.js

@@ -21,8 +21,12 @@
  *   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.
+ * - `migration_digest_derived` (#2339): 1 once `migration_digest` is the one the control plane
+ *   derives from these rows and the manifest's `doClasses`, never the one the push sent. NULL is
+ *   a version stored before this, whose digest is still the pushed one: a backfill re-derives
+ *   those a batch at a time, and a read of one derives it first.
  */
-import { deployManifest, storedDeployManifest, } from '@substrat-run/contracts';
+import { declaredMigrationDeclarations, deployManifest, migrationDigestOf, reviewLine, storedDeployManifest, substratError, UNHELD_MIGRATION_DIGEST_PREFIX, unheldMigrationDigest, } 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
@@ -42,10 +46,16 @@ export const VERSION_MIGRATIONS_DDL = `
     -- The module's SqlMigration.version, e.g. 0001-init.
     version    TEXT NOT NULL,
     sql        TEXT NOT NULL,
+    -- The migration's declared moves and discards (#2322), as JSON { moves?, discards? }.
+    -- NULL = it declares none, or was stored before they were carried.
+    declarations TEXT,
     PRIMARY KEY (version_id, ordinal)
   );
   CREATE INDEX IF NOT EXISTS vertical_versions_unsplit
     ON vertical_versions (id) WHERE migrations_split IS NULL;
+  -- #2339: versions whose migration_digest is still the pushed one, not yet re-derived.
+  CREATE INDEX IF NOT EXISTS vertical_versions_underived
+    ON vertical_versions (id) WHERE migration_digest_derived IS NULL;
 `;
 /**
  * Take `migrations` out of a manifest.
@@ -84,12 +94,43 @@ export function splitManifestMigrations(manifestJson, mode) {
         migrations: result.success && result.data !== undefined ? result.data : null,
     };
 }
+/** The `declarations` column of one row: JSON `{ moves?, discards? }`, or NULL when it declares none. */
+function declarationsJson(m) {
+    if (!m.moves && !m.discards)
+        return null;
+    return JSON.stringify({ ...(m.moves ? { moves: m.moves } : {}), ...(m.discards ? { discards: m.discards } : {}) });
+}
+/** What a stored `declarations` column must parse as: the push boundary's own schema, and nothing else. */
+const storedDeclarations = declaredMigrationDeclarations.strict();
+/**
+ * One row's declarations as a `DeclaredMigration`'s spread, or null when the column holds
+ * something that is not a declaration — which the caller answers as "not available" for the
+ * whole version, never as a list that silently lost what a migration may lose.
+ */
+function declarationsOf(json) {
+    if (json === null)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+    const result = storedDeclarations.safeParse(parsed);
+    if (!result.success || (!result.data.moves && !result.data.discards))
+        return null;
+    return {
+        ...(result.data.moves ? { moves: result.data.moves } : {}),
+        ...(result.data.discards ? { discards: result.data.discards } : {}),
+    };
+}
 /** 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);
+        db.run(`INSERT INTO vertical_version_migrations (version_id, ordinal, module_id, version, sql, declarations)
+       VALUES (?, ?, ?, ?, ?, ?)`, versionId, ordinal, m.moduleId, m.version, m.sql, declarationsJson(m));
     });
 }
 /**
@@ -173,15 +214,140 @@ export function versionMigrationsOf(db, versionId) {
     }
     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
+    const rows = db.all(`SELECT module_id, version, sql, declarations 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,
+    const migrations = [];
+    for (const r of rows) {
+        // Never a list without what a migration declares it may lose (#2322): a row whose
+        // declarations do not read makes the whole version "not available".
+        const declared = declarationsOf(r.declarations);
+        if (declared === null)
+            return { verticalSlug: row.vertical_slug, migrations: null };
         // 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 })),
-    };
+        migrations.push({ moduleId: r.module_id, version: r.version, sql: r.sql, ...declared });
+    }
+    return { verticalSlug: row.vertical_slug, migrations };
+}
+/**
+ * The `reason` on a push refused because its `digests.migration` is not the one the control plane
+ * derives from the migrations it carries (#2339).
+ */
+export const MIGRATION_DIGEST_MISMATCH_REASON = 'migration_digest_mismatch';
+/** The manifest's `doClasses` as the stored parser reads them (absent is `[]`), or null when they do not read. */
+function doClassesOf(raw) {
+    const result = storedDeployManifest.shape.doClasses.safeParse(raw);
+    return result.success ? result.data : null;
+}
+/**
+ * A version's migration digest as the control plane derives it (#2339): `migrationDigestOf`
+ * over the manifest's `doClasses` and the migrations the version stores, with what each
+ * declares. A version that stores no migrations to derive it from (`migrations` null), or whose
+ * `doClasses` do not read, gets `unheldMigrationDigest`, which equals no other version's.
+ */
+export async function derivedMigrationDigest(versionId, doClasses, migrations) {
+    const classes = doClassesOf(doClasses);
+    if (migrations === null || classes === null)
+        return unheldMigrationDigest(versionId);
+    return migrationDigestOf({ doClasses: classes, migrations });
+}
+/**
+ * The migration digest a publish stores (#2339): the one derived from what it stores, never the
+ * one pushed. A push that carries its migrations and pushed another digest is refused
+ * (`validation_failed`, reason {@link MIGRATION_DIGEST_MISMATCH_REASON}): either its CLI hashes
+ * something other than what it sent, or it hashes less than the platform compares. One that
+ * carries none is not refused, since nothing can check it, and stores the unheld digest.
+ */
+export async function publishedMigrationDigest(input) {
+    let doClasses;
+    if (input.manifestJson !== null) {
+        try {
+            doClasses = JSON.parse(input.manifestJson)?.doClasses;
+        }
+        catch {
+            doClasses = null;
+        }
+    }
+    const derived = await derivedMigrationDigest(input.id, input.manifestJson === null ? null : doClasses, input.migrations);
+    if (input.migrations !== null && derived !== input.migrationDigest) {
+        throw substratError('validation_failed', `the push's migration digest (${input.migrationDigest}) is not the digest of the migrations it carries ` +
+            `(${derived}). The platform derives the digest a promote compares from the migrations and their declared ` +
+            'moves and discards itself, so a push must hash exactly those: upgrade to a CLI release whose push digest ' +
+            'covers its SQL migrations and their declarations (npm i -g @substrat-run/cli), and push again', { reason: MIGRATION_DIGEST_MISMATCH_REASON });
+    }
+    return derived;
+}
+/** The two reads that find versions whose digest is not derived yet, answered from `vertical_versions_underived`. */
+export const UNDERIVED_IDS_SQL = 'SELECT id FROM vertical_versions WHERE migration_digest_derived IS NULL ORDER BY id LIMIT ?';
+export const UNDERIVED_PROBE_SQL = 'SELECT 1 AS present FROM vertical_versions WHERE migration_digest_derived IS NULL LIMIT 1';
+/** How many versions one digest batch derives at most. Each reads at most the push's 512 KiB of SQL. */
+const DIGEST_BATCH_VERSIONS = 10;
+/**
+ * Derive one stored version's migration digest from its stored rows and record it (#2339),
+ * unless it is derived already. Returns the digest the version now holds, or undefined when
+ * there is no such version.
+ *
+ * Two statements, not a transaction: the digest is computed between them (Web Crypto is
+ * asynchronous), and the write is guarded on the row still being underived, so two derivations
+ * racing write once. A version's migrations and `doClasses` never change after it is published,
+ * so both derive the same value, and what was read is what is recorded.
+ */
+export async function deriveVersionMigrationDigest(db, versionId) {
+    const row = db.all(`SELECT migration_digest, migration_digest_derived,
+            CASE WHEN manifest_json IS NULL THEN 0 ELSE 1 END AS has_manifest,
+            CASE WHEN json_valid(manifest_json) THEN json_extract(manifest_json, '$.doClasses') END AS do_classes
+       FROM vertical_versions WHERE id = ?`, versionId)[0];
+    if (!row)
+        return undefined;
+    if (row.migration_digest_derived !== null)
+        return row.migration_digest;
+    let doClasses = null;
+    if (row.has_manifest === 1) {
+        try {
+            // `json_extract` answers an array as its JSON text, and NULL for a manifest without the key.
+            doClasses = row.do_classes === null ? undefined : JSON.parse(row.do_classes);
+        }
+        catch {
+            doClasses = null;
+        }
+    }
+    const digest = await derivedMigrationDigest(versionId, doClasses, versionMigrationsOf(db, versionId)?.migrations ?? null);
+    db.run('UPDATE vertical_versions SET migration_digest = ?, migration_digest_derived = 1 WHERE id = ? AND migration_digest_derived IS NULL', digest, versionId);
+    return digest;
+}
+/**
+ * Re-derive the next versions stored before #2339, whose migration digest is still the one their
+ * push sent: at most `limit` of them. Returns how many it derived, and whether any are left.
+ * Resumable and idempotent on #1764's terms: each version is marked as it is derived, and a
+ * derived one is never selected again. Until the backfill reaches a version, a read of it
+ * derives it first (`deriveVersionMigrationDigest`), so no gate compares a pushed digest.
+ */
+export async function deriveMigrationDigestsBatch(db, limit = DIGEST_BATCH_VERSIONS) {
+    const ids = db.all(UNDERIVED_IDS_SQL, limit);
+    for (const { id } of ids)
+        await deriveVersionMigrationDigest(db, id);
+    return { derived: ids.length, more: versionsAwaitDigest(db) };
+}
+/** Whether any version's migration digest still waits to be derived. One probe of the partial index. */
+export function versionsAwaitDigest(db) {
+    return db.all(UNDERIVED_PROBE_SQL).length > 0;
+}
+/**
+ * The promote gate's refusal when the migration digest moved and the change was not acknowledged.
+ * A side whose digest is unheld (#2339) is named with why it always asks, so a vertical whose
+ * pushes leave their SQL out of the manifest is not surprised that every promote does.
+ */
+export function migrationChangeRefusal(outgoing, incoming) {
+    const unheld = [outgoing, incoming]
+        .filter((d) => d.startsWith(UNHELD_MIGRATION_DIGEST_PREFIX))
+        .map((d) => d.slice(UNHELD_MIGRATION_DIGEST_PREFIX.length));
+    return (`promotion changes migrations (${outgoing} → ${incoming}) — acknowledge it explicitly to promote` +
+        (unheld.length === 0
+            ? ''
+            : `. ${unheld.length === 1 ? `Version ${reviewLine(unheld[0])} holds` : `Versions ${unheld.map((id) => reviewLine(id)).join(' and ')} hold`} ` +
+                'no migrations the platform can compare: the push left them out of the manifest (over the size a manifest ' +
+                'carries, or from before manifests carried them), so a promote to or over it always asks for this acknowledgement'));
 }
 //# sourceMappingURL=version-migrations.js.map

package/dist/version-migrations.js.map

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

package/dist/vertical-scope-stores.d.ts

@@ -0,0 +1,43 @@
+import type { SwitchSql } from './system-switch.js';
+/** Interpolated into both adapters' directory DDL, so `lint:spine-ddl` sees one spelling on each side. */
+export declare const VERTICAL_SCOPE_STORES_DDL = "\n  CREATE TABLE IF NOT EXISTS vertical_scope_stores (\n    vertical_slug    TEXT NOT NULL,\n    binding          TEXT NOT NULL,\n    driver           TEXT NOT NULL,\n    -- The version that declared the binding first.\n    first_version_id TEXT NOT NULL,\n    PRIMARY KEY (vertical_slug, binding)\n  );\n  CREATE TABLE IF NOT EXISTS vertical_scope_store_versions (\n    version_id    TEXT PRIMARY KEY,\n    vertical_slug TEXT NOT NULL,\n    -- 0: the manifest could not be read, so the version may declare a store nobody can name.\n    readable      INTEGER NOT NULL\n  );\n  CREATE INDEX IF NOT EXISTS vertical_scope_store_versions_slug\n    ON vertical_scope_store_versions (vertical_slug, readable);\n  -- A vertical every version of which is indexed above.\n  CREATE TABLE IF NOT EXISTS vertical_scope_store_indexed (\n    vertical_slug TEXT PRIMARY KEY\n  );\n";
+/** One declared binding. */
+export interface VerticalScopeStore {
+    readonly binding: string;
+    readonly driver: string;
+}
+/**
+ * Index a version `publishVersion` is inserting, in the insert's transaction, after its row. The
+ * vertical's older versions are indexed first when it is not marked yet, so a driver change is judged
+ * against every version, not only those a read reached. Refuses (`conflict`) a binding the vertical
+ * already declared as another driver, or one declared twice, and then nothing is written.
+ */
+export declare function indexVersionScopeStores(db: SwitchSql, verticalSlug: string, versionId: string, manifestJson: string | null): void;
+/**
+ * Every binding any version of the vertical declared, in binding order. An unmarked vertical is
+ * indexed first (the caller runs this in one transaction). Refuses (`unavailable`) when a version's
+ * manifest cannot be read, or when versions stored before the record moved a binding to another driver: the
+ * lifecycle cannot name every store the vertical may hold.
+ */
+export declare function verticalScopeStoresOf(db: SwitchSql, verticalSlug: string): VerticalScopeStore[];
+/**
+ * Every vertical whose any version declared a binding of `driver`, with those bindings (#2300): the
+ * store scripts a release rollout of the driver reaches, including a vertical whose serving version
+ * dropped the store while a pinned or preview scope still runs one that declares it. Every vertical
+ * not indexed yet is indexed first (the caller runs this in one transaction).
+ *
+ * `unreadable` names the verticals that cannot say: a version whose manifest cannot be read, or
+ * versions stored before the record that moved a binding to another driver. Any of them may declare the driver, so
+ * a caller that must reach every script (a rollout) refuses while the list is not empty, rather
+ * than leave a script on another release without saying so.
+ */
+export declare function driverDeclarationsOf(db: SwitchSql, driver: string): {
+    verticals: {
+        vertical: string;
+        stores: VerticalScopeStore[];
+    }[];
+    unreadable: string[];
+};
+/** A deleted vertical's declarations go with its versions, so a slug registered again starts clean. */
+export declare function forgetVerticalScopeStores(db: SwitchSql, verticalSlug: string): void;
+//# sourceMappingURL=vertical-scope-stores.d.ts.map

package/dist/vertical-scope-stores.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vertical-scope-stores.d.ts","sourceRoot":"","sources":["../src/vertical-scope-stores.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD,0GAA0G;AAC1G,eAAO,MAAM,yBAAyB,u2BAqBrC,CAAC;AAEF,4BAA4B;AAC5B,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAiFD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,EAAE,EAAE,SAAS,EACb,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,GAAG,IAAI,GAC1B,IAAI,CAGN;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAa/F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,EAAE,EAAE,SAAS,EACb,MAAM,EAAE,MAAM,GACb;IAAE,SAAS,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,kBAAkB,EAAE,CAAA;KAAE,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CA6B3F;AAED,uGAAuG;AACvG,wBAAgB,yBAAyB,CAAC,EAAE,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAInF"}

package/dist/vertical-scope-stores.js

@@ -0,0 +1,195 @@
+/**
+ * Every scope-store binding a vertical has declared, by any version (#2286, RFC scope-stores L17),
+ * shared by both adapters.
+ *
+ * A store object is named by (tenant, vertical, scope, binding) and carries no version, so a later
+ * version that drops a binding leaves the old object holding data. The lifecycle (export, wipe,
+ * erasure, the meter) reaches the union of every binding any version declared, which this keeps as
+ * a directory table, read by its keys, instead of reading every version's manifest per call.
+ *
+ * A binding keeps its driver for the life of its vertical. The driver names the store script, so a
+ * binding moved to another driver would point the same name at another script's object, and the union would have
+ * to hold both. `publishVersion` refuses it instead (`conflict`), in the transaction that inserts
+ * the version: one door, where the push can still be told to pick a new binding name. A manifest
+ * that declares one binding twice is refused there too.
+ *
+ * Each version is indexed once, and marked in `vertical_scope_store_versions`; a vertical whose
+ * versions are all indexed is marked in `vertical_scope_store_indexed`, so a read of it is three
+ * keyed lookups and no per-version work. A version stored before these tables, or loaded by a
+ * directory restore from an older dump, leaves its vertical unmarked. Whichever comes first, a read
+ * or a publish, then indexes all of the vertical's versions, oldest first, in its own transaction:
+ * nothing runs on a constructor's path, a restore needs no backfill of its own, and a publish judges
+ * a driver change against every older version, not only those indexed so far. A version whose manifest
+ * cannot be read is marked unreadable, and a read of its vertical refuses: it may declare a store
+ * nobody can name.
+ *
+ * Nothing here retires a binding: the record never shrinks (K-50 forbids it as a side effect of a
+ * push). The explicit retire step is an open item of the RFC (§10.8).
+ */
+import { substratError } from '@substrat-run/contracts';
+/** Interpolated into both adapters' directory DDL, so `lint:spine-ddl` sees one spelling on each side. */
+export const VERTICAL_SCOPE_STORES_DDL = `
+  CREATE TABLE IF NOT EXISTS vertical_scope_stores (
+    vertical_slug    TEXT NOT NULL,
+    binding          TEXT NOT NULL,
+    driver           TEXT NOT NULL,
+    -- The version that declared the binding first.
+    first_version_id TEXT NOT NULL,
+    PRIMARY KEY (vertical_slug, binding)
+  );
+  CREATE TABLE IF NOT EXISTS vertical_scope_store_versions (
+    version_id    TEXT PRIMARY KEY,
+    vertical_slug TEXT NOT NULL,
+    -- 0: the manifest could not be read, so the version may declare a store nobody can name.
+    readable      INTEGER NOT NULL
+  );
+  CREATE INDEX IF NOT EXISTS vertical_scope_store_versions_slug
+    ON vertical_scope_store_versions (vertical_slug, readable);
+  -- A vertical every version of which is indexed above.
+  CREATE TABLE IF NOT EXISTS vertical_scope_store_indexed (
+    vertical_slug TEXT PRIMARY KEY
+  );
+`;
+/**
+ * The bindings a stored manifest declares, or null when the manifest cannot be read. No manifest
+ * declares none. Read for its shape only, `{ binding, driver }` strings as the router reads them:
+ * whether a driver is one the platform runs is the push's question, and a record that refused to
+ * hold a driver it did not know could not refuse a move away from that driver either.
+ */
+function declaredIn(manifestJson) {
+    if (manifestJson === null)
+        return [];
+    let raw;
+    try {
+        raw = JSON.parse(manifestJson);
+    }
+    catch {
+        return null;
+    }
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw))
+        return null;
+    const stores = raw.scopeStores;
+    if (stores === undefined)
+        return [];
+    if (!Array.isArray(stores))
+        return null;
+    const declared = [];
+    for (const store of stores) {
+        const { binding, driver } = (store ?? {});
+        if (typeof binding !== 'string' || typeof driver !== 'string')
+            return null;
+        declared.push({ binding, driver });
+    }
+    return declared;
+}
+/** One version, judged and written; a version already indexed is left as it is. */
+function indexOne(db, verticalSlug, versionId, manifestJson) {
+    if (db.all('SELECT 1 AS present FROM vertical_scope_store_versions WHERE version_id = ?', versionId).length > 0)
+        return;
+    const declared = declaredIn(manifestJson);
+    // Every binding is judged before any is written, so a refusal writes nothing.
+    const fresh = [];
+    const seen = new Set();
+    for (const { binding, driver } of declared ?? []) {
+        if (seen.has(binding)) {
+            throw substratError('conflict', `a version of '${verticalSlug}' declares scope store '${binding}' twice`);
+        }
+        seen.add(binding);
+        const [held] = db.all('SELECT driver FROM vertical_scope_stores WHERE vertical_slug = ? AND binding = ?', verticalSlug, binding);
+        if (held && held.driver !== driver) {
+            throw substratError('conflict', `scope store '${binding}' of '${verticalSlug}' is a '${held.driver}', and a binding keeps its driver for ` +
+                `the life of its vertical: objects of the old driver may still hold data under that name. ` +
+                `Declare the '${driver}' store under a new binding name`);
+        }
+        if (!held)
+            fresh.push({ binding, driver });
+    }
+    for (const { binding, driver } of fresh) {
+        db.run('INSERT INTO vertical_scope_stores (vertical_slug, binding, driver, first_version_id) VALUES (?, ?, ?, ?)', verticalSlug, binding, driver, versionId);
+    }
+    db.run('INSERT INTO vertical_scope_store_versions (version_id, vertical_slug, readable) VALUES (?, ?, ?)', versionId, verticalSlug, declared === null ? 0 : 1);
+}
+/** Index every version of the vertical not indexed yet, oldest first, then mark the vertical. */
+function indexVertical(db, verticalSlug) {
+    if (db.all('SELECT 1 AS present FROM vertical_scope_store_indexed WHERE vertical_slug = ?', verticalSlug).length > 0)
+        return;
+    const unindexed = db.all(`SELECT v.id, v.manifest_json FROM vertical_versions AS v
+      WHERE v.vertical_slug = ?
+        AND NOT EXISTS (SELECT 1 FROM vertical_scope_store_versions AS s WHERE s.version_id = v.id)
+      ORDER BY v.created_at, v.id`, verticalSlug);
+    for (const { id, manifest_json } of unindexed)
+        indexOne(db, verticalSlug, id, manifest_json);
+    db.run('INSERT OR IGNORE INTO vertical_scope_store_indexed (vertical_slug) VALUES (?)', verticalSlug);
+}
+/**
+ * Index a version `publishVersion` is inserting, in the insert's transaction, after its row. The
+ * vertical's older versions are indexed first when it is not marked yet, so a driver change is judged
+ * against every version, not only those a read reached. Refuses (`conflict`) a binding the vertical
+ * already declared as another driver, or one declared twice, and then nothing is written.
+ */
+export function indexVersionScopeStores(db, verticalSlug, versionId, manifestJson) {
+    indexVertical(db, verticalSlug);
+    indexOne(db, verticalSlug, versionId, manifestJson);
+}
+/**
+ * Every binding any version of the vertical declared, in binding order. An unmarked vertical is
+ * indexed first (the caller runs this in one transaction). Refuses (`unavailable`) when a version's
+ * manifest cannot be read, or when versions stored before the record moved a binding to another driver: the
+ * lifecycle cannot name every store the vertical may hold.
+ */
+export function verticalScopeStoresOf(db, verticalSlug) {
+    try {
+        indexVertical(db, verticalSlug);
+    }
+    catch (error) {
+        throw substratError('unavailable', `the scope stores of '${verticalSlug}' cannot be named: ${String(error.message ?? error)}`);
+    }
+    if (db.all('SELECT 1 AS present FROM vertical_scope_store_versions WHERE vertical_slug = ? AND readable = 0 LIMIT 1', verticalSlug).length > 0) {
+        throw substratError('unavailable', `a version of '${verticalSlug}' has a manifest that cannot be read, so its scope stores cannot be named`);
+    }
+    return db.all('SELECT binding, driver FROM vertical_scope_stores WHERE vertical_slug = ? ORDER BY binding', verticalSlug).map(({ binding, driver }) => ({ binding, driver }));
+}
+/**
+ * Every vertical whose any version declared a binding of `driver`, with those bindings (#2300): the
+ * store scripts a release rollout of the driver reaches, including a vertical whose serving version
+ * dropped the store while a pinned or preview scope still runs one that declares it. Every vertical
+ * not indexed yet is indexed first (the caller runs this in one transaction).
+ *
+ * `unreadable` names the verticals that cannot say: a version whose manifest cannot be read, or
+ * versions stored before the record that moved a binding to another driver. Any of them may declare the driver, so
+ * a caller that must reach every script (a rollout) refuses while the list is not empty, rather
+ * than leave a script on another release without saying so.
+ */
+export function driverDeclarationsOf(db, driver) {
+    const slugs = db.all('SELECT DISTINCT vertical_slug FROM vertical_versions ORDER BY vertical_slug');
+    const unreadable = new Set();
+    for (const { vertical_slug } of slugs) {
+        try {
+            indexVertical(db, vertical_slug);
+        }
+        catch {
+            unreadable.add(vertical_slug);
+        }
+    }
+    for (const { vertical_slug } of db.all('SELECT DISTINCT vertical_slug FROM vertical_scope_store_versions WHERE readable = 0')) {
+        unreadable.add(vertical_slug);
+    }
+    const rows = db.all('SELECT vertical_slug, binding FROM vertical_scope_stores WHERE driver = ? ORDER BY vertical_slug, binding', driver);
+    const byVertical = new Map();
+    for (const { vertical_slug, binding } of rows) {
+        const stores = byVertical.get(vertical_slug) ?? [];
+        stores.push({ binding, driver });
+        byVertical.set(vertical_slug, stores);
+    }
+    return {
+        verticals: [...byVertical].map(([vertical, stores]) => ({ vertical, stores })),
+        unreadable: [...unreadable].sort(),
+    };
+}
+/** A deleted vertical's declarations go with its versions, so a slug registered again starts clean. */
+export function forgetVerticalScopeStores(db, verticalSlug) {
+    db.run('DELETE FROM vertical_scope_stores WHERE vertical_slug = ?', verticalSlug);
+    db.run('DELETE FROM vertical_scope_store_versions WHERE vertical_slug = ?', verticalSlug);
+    db.run('DELETE FROM vertical_scope_store_indexed WHERE vertical_slug = ?', verticalSlug);
+}
+//# sourceMappingURL=vertical-scope-stores.js.map

package/dist/vertical-scope-stores.js.map

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

package/package.json

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