@substrat-run/contract-tests 0.147.0 → 0.149.0

package/dist/scope-host-suite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scope-host-suite.d.ts","sourceRoot":"","sources":["../src/scope-host-suite.ts"],"names":[],"mappings":"AAEA,OAAO,EAqBL,KAAK,SAAS,EAqBf,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAeL,KAAK,SAAS,EACf,MAAM,sBAAsB,CAAC;AAa9B,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,SAAS,CAAC;IAChB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAuCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,aAAa,MACrB,OAAO,CAAC,OAAO,CAAC,QACb,SAAS,YACL,MAAM,KACf,OAAO,CAAC,IAAI,CAOd,CAAC;AAEF,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,EAC5C,IAAI,GAAE,qBAA0B,GAC/B,IAAI,CAytUN"}
+{"version":3,"file":"scope-host-suite.d.ts","sourceRoot":"","sources":["../src/scope-host-suite.ts"],"names":[],"mappings":"AAEA,OAAO,EAqBL,KAAK,SAAS,EAsBf,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAkBL,KAAK,SAAS,EACf,MAAM,sBAAsB,CAAC;AAc9B,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,SAAS,CAAC;IAChB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAuCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,aAAa,MACrB,OAAO,CAAC,OAAO,CAAC,QACb,SAAS,YACL,MAAM,KACf,OAAO,CAAC,IAAI,CAOd,CAAC;AAEF,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAC;CACvC;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,EAC5C,IAAI,GAAE,qBAA0B,GAC/B,IAAI,CA8rVN"}

package/dist/scope-host-suite.js

@@ -1,9 +1,10 @@
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
 import { connectorCalls, connectorTestFetch, resetConnectorCalls } from './connector-fixture.js';
-import { connectionId, dataSubjectId, domainEvent, errorCodeOf, moduleId, SCOPE_GATE_REASONS, eventId, instant, moduleManifest, orgId, AUTO_ADMISSION_NOTE, permissionKey, platformActorId, platformRequestId, principalId, scopeId, tenantId, SCOPE_QUERY_ROW_MAX, KERNEL_AUTHORED_EVENT_TYPES, EMAIL_SENT, PLATFORM_REQUEST_ENTITY_TYPE, SEND_EMAIL_KIND, isUndecodablePlatformRequest, platformRequestEntry, SWEEP_RUNS_KIND, SCOPE_TABLE_PAGE_MAX, } from '@substrat-run/contracts';
-import { INERT_SCOPE_REASON, BACKFILL_MOVE_ID, SCOPE_COPY_LEASE_MS, isSearchIndexTable, platformIntentFailureMessage, REDACTED_DELIVERY_NOTE, REDACTED_FAILURE_NOTE, REDACTED_INTENT_MARKER, runPlatformSweep, startPlatformSweeper, createUlid, ulid, } from '@substrat-run/kernel';
+import { connectionId, dataSubjectId, domainEvent, errorCodeOf, moduleId, SCOPE_GATE_REASONS, eventId, instant, moduleManifest, orgId, AUTO_ADMISSION_NOTE, permissionKey, platformActorId, platformRequestId, principalId, scopeId, tenantId, SCOPE_QUERY_ROW_MAX, KERNEL_AUTHORED_EVENT_TYPES, EMAIL_SENT, PLATFORM_REQUEST_ENTITY_TYPE, SEND_EMAIL_KIND, isUndecodablePlatformRequest, platformRequestEntry, SWEEP_RUNS_KIND, SCOPE_TABLE_PAGE_MAX, unheldMigrationDigest, } from '@substrat-run/contracts';
+import { INERT_SCOPE_REASON, BACKFILL_MOVE_ID, SCOPE_COPY_LEASE_MS, isSearchIndexTable, platformIntentFailureMessage, REDACTED_DELIVERY_NOTE, REDACTED_FAILURE_NOTE, REDACTED_INTENT_MARKER, runPlatformSweep, startPlatformSweeper, promoteReviewDigest, promoteReviewRefusalOf, rebindReviewRefusalOf, createUlid, ulid, } from '@substrat-run/kernel';
 import { billedMod, contractTestBareOps, contractTestInitialModules, gateModManifest, lateMod, TEST_LIFECYCLE, testModManifest, victimModManifest, } from './modules.js';
 import { testOperations } from './test-operations.js';
+import { derivedDigestOf, heldMigrations } from './held-migrations.js';
 /**
  * A journal read whose every row is whole. A test that planted nothing has no business meeting
  * an `UndecodablePlatformRequest` (#1637), so one fails here, naming why, rather than being
@@ -3853,7 +3854,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                         version,
                         manifestDigest: `man-${version}`,
                         permissionDigest: 'p',
-                        migrationDigest: mig,
+                        ...(await heldMigrations(mig)),
                         deploymentRef: null,
                     });
                     await host.admin.admitVersion(staff, id);
@@ -5236,6 +5237,113 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             expect(await host.admin.openSubjectPayloads(staff, t1, s, [{ subjectId: subject, sealed: sealed }]))
                 .toEqual([null]);
         });
+        /** A vertical with one admitted version, served on `ref`, and a scope pinned to `scopeRef`. */
+        const pinnedErasureFixture = async (scopeRef) => {
+            const slug = `pin-${ulid().toLowerCase().slice(-8)}`;
+            await host.admin.registerVertical(staff, { slug, name: slug, source: 'cli' });
+            const versionId = ulid();
+            const ref = `${slug}-serving`;
+            await host.admin.publishVersion(staff, {
+                id: versionId,
+                verticalSlug: slug,
+                version: `1.0.${versionId.slice(-4).toLowerCase()}`,
+                manifestDigest: `m-${versionId}`,
+                permissionDigest: 'p',
+                migrationDigest: 'g',
+                deploymentRef: ref,
+                manifestJson: JSON.stringify({
+                    version: '1.0.0', entry: 'index.js', compatibilityDate: '2026-07-01',
+                    registry: { permissions: [], roles: [], entityGrants: [] },
+                    digests: { manifest: 'm', permission: 'p', migration: 'g' },
+                }),
+            });
+            await host.admin.admitVersion(staff, versionId);
+            const s = scopeId.parse(ulid());
+            const subject = ulid();
+            await host.provisionScope(staff, { tenantId: t1, scopeId: s, vertical: slug });
+            const [sealed] = await host.admin.sealSubjectPayloads(staff, t1, s, [{ subjectId: subject, plaintext: 'private' }]);
+            await host.admin.setVerticalServing(staff, slug, { ref, versionId, doClasses: ['ScopeDO'], migrationTag: 'v1' });
+            await host.admin.setScopeServingRef(staff, t1, s, scopeRef ?? ref);
+            const opened = () => host.admin.openSubjectPayloads(staff, t1, s, [{ subjectId: subject, sealed: sealed }]);
+            return { slug, versionId, ref, s, subject, opened };
+        };
+        const redacted = [{ events: 0, intents: 0, jobRuns: 0, idempotencyResults: 0, intentIds: [],
+                vertical: { verticalRows: [], hookRows: [], unreachedEntities: [] } }];
+        it('an erasure claim fails when the serving pointer is not the pair it read, and the key stays (#2285)', async () => {
+            const { versionId, ref, s, subject, opened } = await pinnedErasureFixture();
+            const expected = { versionId: null, servingRef: ref, epoch: 0, copyCount: 0, servingPointer: { ref, versionId: ulid() } };
+            await expectRefusal(host.admin.finalizeSubjectShred(staff, t1, s, subject, redacted, expected), 'precondition_failed');
+            expect(await opened()).toEqual(['private']);
+            expect((await host.admin.finalizeSubjectShred(staff, t1, s, subject, redacted, { ...expected, servingPointer: { ref, versionId } })).keyDestroyed).toBe(true);
+            expect(await opened()).toEqual([null]);
+        });
+        it('a scope off its pin is fenced too: a pointer moved onto its script refuses the claim (#2285)', async () => {
+            // The scope's own script is not the pointer's when the erasure reads it, so it runs no
+            // pointer version. A rollback onto that script before the claim would make it run one.
+            const { slug, versionId, ref, s, subject, opened } = await pinnedErasureFixture('old-script');
+            const expected = { versionId: null, servingRef: 'old-script', epoch: 0, copyCount: 0, servingPointer: { ref, versionId } };
+            await host.admin.setVerticalServing(staff, slug, { ref: 'old-script', versionId, doClasses: ['ScopeDO'], migrationTag: 'v1' });
+            await expectRefusal(host.admin.finalizeSubjectShred(staff, t1, s, subject, redacted, expected), 'precondition_failed');
+            expect(await opened()).toEqual(['private']);
+            expect((await host.admin.finalizeSubjectShred(staff, t1, s, subject, redacted, { ...expected, servingPointer: { ref: 'old-script', versionId } })).keyDestroyed).toBe(true);
+        });
+        it('a direct shred with a fence claims it: a moved scope keeps the key, and the pair it read destroys it (#2285)', async () => {
+            const { versionId, ref, s, subject, opened } = await pinnedErasureFixture();
+            const fence = { versionId: null, servingRef: ref, epoch: 0, copyCount: 0, servingPointer: { ref, versionId: ulid() } };
+            await expectRefusal(host.admin.shredSubject(staff, t1, s, subject, fence), 'precondition_failed');
+            expect(await opened()).toEqual(['private']);
+            expect(await host.admin.scopeErasureEpoch(staff, t1, s)).toBe(0);
+            expect((await host.admin.shredSubject(staff, t1, s, subject, { ...fence, servingPointer: { ref, versionId } })).keyDestroyed)
+                .toBe(true);
+            expect(await opened()).toEqual([null]);
+            // The claim moved the epoch every bind compares, as the orchestrated finalize's does.
+            expect(await host.admin.scopeErasureEpoch(staff, t1, s)).toBe(1);
+        });
+        // #2286, L17: what the lifecycle reaches is every binding any version declared.
+        it('keeps every scope-store binding a version declared, refuses a driver change at publish, and names none it cannot read', async () => {
+            const slug = `bind-${ulid().toLowerCase().slice(-8)}`;
+            await host.admin.registerVertical(staff, { slug, name: slug, source: 'cli' });
+            const publish = (scopeStores, raw) => {
+                const id = ulid();
+                return host.admin.publishVersion(staff, {
+                    id,
+                    verticalSlug: slug,
+                    version: `1.0.${id.slice(-6).toLowerCase()}`,
+                    manifestDigest: `m-${id}`,
+                    permissionDigest: 'p',
+                    migrationDigest: 'g',
+                    deploymentRef: null,
+                    manifestJson: raw ?? JSON.stringify({
+                        version: '1.0.0', entry: 'index.js', compatibilityDate: '2026-07-01',
+                        registry: { permissions: [], roles: [], entityGrants: [] },
+                        digests: { manifest: 'm', permission: 'p', migration: 'g' },
+                        ...(scopeStores ? { scopeStores } : {}),
+                    }),
+                }).then(() => id);
+            };
+            await publish([{ binding: 'GRAPH', driver: 'graph' }, { binding: 'OLD', driver: 'graph' }]);
+            await publish([{ binding: 'GRAPH', driver: 'graph' }]);
+            // A dropped binding is still there.
+            expect(await host.admin.verticalScopeStores(staff, slug)).toEqual([
+                { binding: 'GRAPH', driver: 'graph' },
+                { binding: 'OLD', driver: 'graph' },
+            ]);
+            // A driver change is refused, and the version is not stored.
+            const before = (await host.admin.listVersions(staff, slug)).length;
+            await expectRefusal(publish([{ binding: 'NEW', driver: 'graph' }, { binding: 'OLD', driver: 'counter' }]), 'conflict');
+            expect((await host.admin.listVersions(staff, slug)).length).toBe(before);
+            // So is a version that declares one binding twice.
+            await expectRefusal(publish([{ binding: 'NEW', driver: 'graph' }, { binding: 'NEW', driver: 'graph' }]), 'conflict');
+            expect((await host.admin.listVersions(staff, slug)).length).toBe(before);
+            // The twin: the same driver again, with a new binding beside it, is published.
+            await publish([{ binding: 'OLD', driver: 'graph' }, { binding: 'NEW', driver: 'graph' }]);
+            expect((await host.admin.verticalScopeStores(staff, slug)).map((s) => s.binding)).toEqual(['GRAPH', 'NEW', 'OLD']);
+            // A version whose manifest cannot be read may declare a store nobody can name.
+            await publish(undefined, '{nope');
+            await expectRefusal(host.admin.verticalScopeStores(staff, slug), 'unavailable');
+            // An unknown vertical declared none.
+            expect(await host.admin.verticalScopeStores(staff, `none-${slug}`)).toEqual([]);
+        });
         // #1722 (Codex #2008 r7): the admin-log record of a staff resolution of a kept copy. The
         // resolution itself runs in the vertical's store; the directory only records it, in full.
         it('records a kept-copy resolution in the admin log, before and after, and refuses an unknown scope', async () => {
@@ -5744,7 +5852,9 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                 const id = ulid();
                 await host.admin.publishVersion(staff, {
                     id, verticalSlug: 'migrationsapart', version: `1.0.${id.toLowerCase()}`, manifestDigest: 'm',
-                    permissionDigest: 'p', migrationDigest: 'g', deploymentRef: null,
+                    permissionDigest: 'p', deploymentRef: null,
+                    // #2339: a set it carries is hashed as the host derives it; the others store none to check.
+                    migrationDigest: typeof manifest === 'string' || !Array.isArray(manifest.migrations) ? 'g' : await derivedDigestOf(manifest),
                     manifestJson: typeof manifest === 'string' ? manifest : JSON.stringify(manifest),
                 });
                 return id;
@@ -5778,6 +5888,60 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             const junk = await publish('not json');
             expect(await host.admin.versionManifest(staff, 'migrationsapart', junk)).toBe('not json');
             expect(await host.admin.versionMigrations(staff, 'migrationsapart', junk)).toBeNull();
+            // #2322: each migration's declared moves and discards are stored beside its SQL and read
+            // back as published, whatever digest the publisher claimed; one declaring none has neither.
+            const declared = [
+                { ...migrations[0], moves: { legacy_a: 'a' } },
+                { ...migrations[1] },
+                { ...migrations[2], discards: { 'b.c': 'replaced by d; see "0003"' } },
+            ];
+            const withDeclarations = await publish({ ...base, migrations: declared });
+            expect(await host.admin.versionMigrations(staff, 'migrationsapart', withDeclarations)).toEqual(declared);
+            // A declaration the push boundary refuses (a discard with no reason) carries no SQL at all.
+            const reasonless = await publish({ ...base, migrations: [{ ...migrations[0], discards: { a: '' } }] });
+            expect(await host.admin.versionMigrations(staff, 'migrationsapart', reasonless)).toBeNull();
+        });
+        it("derives a version's migration digest from what it stores, and refuses a publish whose digest is not that (#2339)", async () => {
+            const slug = `acme/digest-${ulid().slice(-8).toLowerCase()}`;
+            await host.admin.registerVertical(staff, { slug, name: slug, source: 'cli' });
+            const A = [{ moduleId: 'helpdesk', version: '0001-init', sql: 'CREATE TABLE a (id TEXT);' }];
+            const B = [...A, { moduleId: 'helpdesk', version: '0002-drop', sql: 'DROP TABLE a;' }];
+            const declaredA = [{ ...A[0], discards: { 'a.id': 'nothing reads it' } }];
+            const publish = async (migrationDigest, migrations, doClasses) => {
+                const id = ulid();
+                await host.admin.publishVersion(staff, {
+                    id, verticalSlug: slug, version: `1.0.${id.toLowerCase()}`, manifestDigest: 'm', permissionDigest: 'p',
+                    migrationDigest, deploymentRef: null,
+                    ...(migrations ? { manifestJson: JSON.stringify({ migrations, ...(doClasses ? { doClasses } : {}) }) } : {}),
+                });
+                return id;
+            };
+            const digestOfA = await derivedDigestOf({ migrations: A });
+            const a = await publish(digestOfA, A);
+            expect((await host.admin.getVersion(staff, a, slug))?.migrationDigest).toBe(digestOfA);
+            // The base's digest over other SQL, over the same SQL with a declared loss added, or over other
+            // store classes: refused, and nothing is stored.
+            for (const [migrations, doClasses] of [[B, undefined], [declaredA, undefined], [A, ['OtherDO']]]) {
+                const before = (await host.admin.listVersions(staff, slug)).length;
+                await expectRefusal(publish(digestOfA, [...migrations], doClasses ? [...doClasses] : undefined), 'validation_failed', /is not the digest of the migrations it carries/);
+                expect(await host.admin.listVersions(staff, slug)).toHaveLength(before);
+            }
+            // Its positive twin: the digest B's own migrations give is stored, and a promote over A asks.
+            const b = await publish(await derivedDigestOf({ migrations: B }), B);
+            await host.admin.admitVersion(staff, a);
+            await host.admin.admitVersion(staff, b);
+            await host.admin.promoteVersion(staff, slug, 'prod', a);
+            await expectRefusal(host.admin.promoteVersion(staff, slug, 'prod', b), 'conflict', /changes migrations/);
+            // A version that stores none cannot be checked: never refused, and it equals no other version.
+            const bare = await publish(digestOfA);
+            expect((await host.admin.getVersion(staff, bare, slug))?.migrationDigest).toBe(unheldMigrationDigest(bare));
+            // The admin log records the digest the registry holds, not the one the push sent; so does a held one's.
+            const published = async (id) => (await host.admin.auditLog(staff, {})).find((e) => e.action === 'publishVersion' && e.after?.id === id)
+                ?.after?.migrationDigest;
+            expect(await published(bare)).toBe(unheldMigrationDigest(bare));
+            expect(await published(a)).toBe(digestOfA);
+            await host.admin.admitVersion(staff, bare);
+            await expectRefusal(host.admin.promoteVersion(staff, slug, 'prod', bare), 'conflict', /holds no migrations the platform can compare/);
         });
         it('an archived scope blocks the delete naming the reap step; a reaped tombstone never blocks', async () => {
             // A deleted app leaves an `archived` row (restorable via unarchive), then a
@@ -5885,12 +6049,24 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                 version,
                 manifestDigest: `man-${version}`,
                 permissionDigest: digests.perm,
-                migrationDigest: digests.mig,
+                ...(await heldMigrations(digests.mig)),
                 deploymentRef: null,
             });
             await host.admin.admitVersion(staff, id);
             return id;
         };
+        /**
+         * #2333: the binding a review hands out, computed as the migrations read computes it — from
+         * the stored rows of the version prod points at now and of the one being promoted.
+         */
+        const reviewOf = async (slug, versionId, base) => {
+            const prod = base !== undefined ? base : ((await host.admin.listChannels(staff, slug)).find((c) => c.channel === 'prod')?.versionId ?? null);
+            const side = async (id) => ({
+                ...(await host.admin.getVersion(staff, id, slug)),
+                migrations: await host.admin.versionMigrations(staff, slug, id),
+            });
+            return { base: prod, digest: await promoteReviewDigest(prod === null ? null : await side(prod), await side(versionId)) };
+        };
         it('promotes a first version with nothing to acknowledge', async () => {
             // The gate is about CHANGE, not existence. A first promotion has no
             // predecessor to diff against, so demanding an acknowledgement would be
@@ -5913,7 +6089,9 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
         it('refuses a promotion that changes migrations until it is acknowledged', async () => {
             const v3 = await publish('2.2.0', { perm: 'pB', mig: 'gB' }); // migrations moved
             await expectRefusal(host.admin.promoteVersion(staff, 'callout', 'prod', v3), 'conflict', /changes migrations/);
-            await host.admin.promoteVersion(staff, 'callout', 'prod', v3, { migrationChange: true });
+            // #2333: the acknowledgement that lets a migration reach live data names the review it answers.
+            await expectRefusal(host.admin.promoteVersion(staff, 'callout', 'prod', v3, { migrationChange: true }), 'precondition_failed', /needs the review it answers/);
+            await host.admin.promoteVersion(staff, 'callout', 'prod', v3, { migrationChange: true, review: await reviewOf('callout', v3) });
             expect((await host.admin.listChannels(staff, 'callout')).find((c) => c.channel === 'prod')
                 ?.versionId).toBe(v3);
         });
@@ -5950,9 +6128,259 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             await expectRefusal(host.admin.promoteVersion(staff, 'elsewhere', 'prod', v), 'conflict');
             // Positive twin: through its own vertical the same version promotes (the earlier tests
             // moved prod, so the digest checkpoints are acknowledged — they are not under test here).
-            await host.admin.promoteVersion(staff, 'callout', 'prod', v, { permissionChange: true, migrationChange: true });
+            await host.admin.promoteVersion(staff, 'callout', 'prod', v, { permissionChange: true, migrationChange: true, review: await reviewOf('callout', v) });
             expect((await host.admin.listChannels(staff, 'callout')).find((c) => c.channel === 'prod')?.versionId).toBe(v);
         });
+        // -- the acknowledgement names the review it answers (#2333) ---------------
+        // A review is computed over the channel's CURRENT version. A promote between showing it and
+        // acknowledging it moves that base, and a bare flag would then acknowledge a diff that is not
+        // the one applied. So the acknowledgement carries the review's binding, and the host refuses
+        // one that no longer holds.
+        describe('an acknowledgement bound to the review it answers (#2333)', () => {
+            const MIGRATION = (discards, moves = {}) => ({
+                moduleId: 'callout', version: '0002-drop', sql: 'ALTER TABLE t DROP COLUMN c;', discards, ...(Object.keys(moves).length ? { moves } : {}),
+            });
+            /** A fresh vertical with three admitted versions; `a` serves. */
+            const fresh = async () => {
+                const slug = `acme/review-${ulid().slice(-8).toLowerCase()}`;
+                await host.admin.registerVertical(staff, { slug, name: slug, source: 'cli' });
+                const put = async (perm, mig, migrations) => {
+                    const id = ulid();
+                    await host.admin.publishVersion(staff, {
+                        id, verticalSlug: slug, version: `1.0.${id.slice(-4).toLowerCase()}`, manifestDigest: `m-${id}`,
+                        // #2339: the digest is the one the stored migrations give; `mig` names the set without them.
+                        permissionDigest: perm, deploymentRef: null,
+                        ...(migrations
+                            ? { migrationDigest: await derivedDigestOf({ migrations }), manifestJson: JSON.stringify({ migrations }) }
+                            : { migrationDigest: mig }),
+                    });
+                    await host.admin.admitVersion(staff, id);
+                    return id;
+                };
+                const a = await put('pA', 'gA', []);
+                await host.admin.promoteVersion(staff, slug, 'prod', a);
+                return { slug, put, a };
+            };
+            const prodOf = async (slug) => (await host.admin.listChannels(staff, slug)).find((c) => c.channel === 'prod')?.versionId;
+            const refusal = async (p) => {
+                const err = await p.then(() => undefined, (e) => e);
+                return { kind: promoteReviewRefusalOf(err), message: err?.message };
+            };
+            it('a promote between show and acknowledge moves the base: the acknowledgement is refused, and a fresh review passes', async () => {
+                const { slug, put, a } = await fresh();
+                const c = await put('pC', 'gC', [MIGRATION({ c: 'the column is no longer read' })]);
+                const shown = await reviewOf(slug, c);
+                expect(shown.base).toBe(a);
+                // Someone else promotes b in between: same migrations as a, a different permission surface.
+                const b = await put('pB', 'gA', []);
+                await host.admin.promoteVersion(staff, slug, 'prod', b, { permissionChange: true, review: await reviewOf(slug, b) });
+                const stale = await refusal(host.admin.promoteVersion(staff, slug, 'prod', c, { permissionChange: true, migrationChange: true, review: shown }));
+                expect(stale.kind).toBe('stale');
+                expect(stale.message).toContain(`read against version ${a}`);
+                expect(await prodOf(slug)).toBe(b);
+                // The review read again names b, and is what an acknowledgement answers now.
+                const again = await reviewOf(slug, c);
+                expect(again).toEqual({ base: b, digest: expect.stringMatching(/^[0-9a-f]{64}$/) });
+                expect(again.digest).not.toBe(shown.digest);
+                await host.admin.promoteVersion(staff, slug, 'prod', c, { permissionChange: true, migrationChange: true, review: again });
+                expect(await prodOf(slug)).toBe(c);
+            });
+            it('two promotes bound to the same base, racing: one moves the channel, the other is refused as stale', async () => {
+                const { slug, put, a } = await fresh();
+                const b = await put('pB', 'gB', [MIGRATION({ c: 'gone' })]);
+                const c = await put('pC', 'gC', [MIGRATION({ c: 'gone too' })]);
+                const [forB, forC] = [await reviewOf(slug, b), await reviewOf(slug, c)];
+                expect([forB.base, forC.base]).toEqual([a, a]);
+                const ACK = { permissionChange: true, migrationChange: true };
+                // Neither awaited before the other starts: each judges its gates against `a`.
+                const settled = await Promise.allSettled([
+                    host.admin.promoteVersion(staff, slug, 'prod', b, { ...ACK, review: forB }),
+                    host.admin.promoteVersion(staff, slug, 'prod', c, { ...ACK, review: forC }),
+                ]);
+                const won = settled.flatMap((s, i) => (s.status === 'fulfilled' ? [[b, c][i]] : []));
+                const lost = settled.flatMap((s) => (s.status === 'rejected' ? [s.reason] : []));
+                expect(won).toHaveLength(1);
+                expect(lost.map((e) => promoteReviewRefusalOf(e))).toEqual(['stale']);
+                expect(await prodOf(slug)).toBe(won[0]);
+                // One move away from `a`, by the winner; the loser recorded nothing.
+                const history = await host.admin.listChannelHistory(staff, slug, 'prod');
+                expect(history.filter((h) => h.fromVersionId === a).map((h) => h.versionId)).toEqual(won);
+                expect(history.some((h) => h.versionId === (won[0] === b ? c : b))).toBe(false);
+            });
+            it('a binding is checked whatever it acknowledges: a moved base refuses even a promote that needs no acknowledgement', async () => {
+                const { slug, put, a } = await fresh();
+                const same = await put('pA', 'gA', []);
+                const shown = await reviewOf(slug, same);
+                const b = await put('pB', 'gA', []);
+                await host.admin.promoteVersion(staff, slug, 'prod', b, { permissionChange: true });
+                expect((await refusal(host.admin.promoteVersion(staff, slug, 'prod', same, { review: shown }))).kind).toBe('stale');
+                expect(await prodOf(slug)).toBe(b);
+                // Twin: bound to the base that still serves, it promotes.
+                await host.admin.promoteVersion(staff, slug, 'prod', a, { permissionChange: true, review: await reviewOf(slug, a) });
+                expect(await prodOf(slug)).toBe(a);
+            });
+            it('a review read before anything served is stale once something does', async () => {
+                const slug = `acme/review-${ulid().slice(-8).toLowerCase()}`;
+                await host.admin.registerVertical(staff, { slug, name: slug, source: 'cli' });
+                const put = async () => {
+                    const id = ulid();
+                    await host.admin.publishVersion(staff, { id, verticalSlug: slug, version: id, manifestDigest: 'm', permissionDigest: 'p', migrationDigest: 'g', deploymentRef: null });
+                    await host.admin.admitVersion(staff, id);
+                    return id;
+                };
+                const first = await put();
+                const shown = await reviewOf(slug, first, null);
+                expect(shown.base).toBeNull();
+                const other = await put();
+                await host.admin.promoteVersion(staff, slug, 'prod', other);
+                const stale = await refusal(host.admin.promoteVersion(staff, slug, 'prod', first, { review: shown }));
+                expect(stale.kind).toBe('stale');
+                expect(stale.message).toContain('read against no serving version');
+            });
+            it('a digest that is not the one the stored rows give is refused, with the base right', async () => {
+                const { slug, put, a } = await fresh();
+                const c = await put('pA', 'gC', [MIGRATION({ c: 'gone' })]);
+                const shown = await reviewOf(slug, c);
+                // Another review's digest, as a client that bound the wrong answer would send.
+                const other = await reviewOf(slug, await put('pA', 'gD', [MIGRATION({ c: 'gone, differently' })]));
+                expect(other.base).toBe(a);
+                const stale = await refusal(host.admin.promoteVersion(staff, slug, 'prod', c, { migrationChange: true, review: { base: a, digest: other.digest } }));
+                expect(stale.kind).toBe('stale');
+                expect(stale.message).toMatch(/no longer give the digest/);
+                // Never handed back: a refusal is not something to retry with.
+                expect(stale.message).not.toContain(shown.digest);
+                expect(await prodOf(slug)).toBe(a);
+                await host.admin.promoteVersion(staff, slug, 'prod', c, { migrationChange: true, review: shown });
+                expect(await prodOf(slug)).toBe(c);
+            });
+            it('a migration acknowledgement without a binding is refused; a permission-only one is still honoured', async () => {
+                const { slug, put } = await fresh();
+                const c = await put('pA', 'gC', [MIGRATION({ c: 'gone' })]);
+                const unbound = await refusal(host.admin.promoteVersion(staff, slug, 'prod', c, { migrationChange: true }));
+                expect(unbound.kind).toBe('unbound');
+                // It names the fix: the client release that binds, and how to read the review.
+                // By what the release does, never a version number the release tooling has not cut yet.
+                expect(unbound.message).toContain("a CLI release whose 'substrat promote' supports --review");
+                expect(unbound.message).toContain('/guide/deploying#acknowledgement-answers-one-review');
+                expect(unbound.message).not.toMatch(/\d+\.\d+\.\d+/);
+                // The compatibility rule: no migration moves, so an older client's bare flag still promotes.
+                const p = await put('pP', 'gA', []);
+                await host.admin.promoteVersion(staff, slug, 'prod', p, { permissionChange: true });
+                expect(await prodOf(slug)).toBe(p);
+                // And a migrationChange the gate does not consume needs no binding either.
+                const q = await put('pP', 'gA', []);
+                await host.admin.promoteVersion(staff, slug, 'prod', q, { migrationChange: true });
+                expect(await prodOf(slug)).toBe(q);
+            });
+            it('the digest is over the stored declarations, and the binding is recorded', async () => {
+                const { slug, put, a } = await fresh();
+                const c = await put('pA', 'gC', [MIGRATION({ c: 'gone' }, { 't.a': 't.b' })]);
+                const shown = await reviewOf(slug, c);
+                // What the host digests is what it stored: the declarations come back with the SQL…
+                const stored = await host.admin.versionMigrations(staff, slug, c);
+                expect(stored).toEqual([MIGRATION({ c: 'gone' }, { 't.a': 't.b' })]);
+                // …and a review of the same version showing a reworded reason binds another digest.
+                const side = async (id, migrations) => ({ ...(await host.admin.getVersion(staff, id, slug)), migrations: migrations });
+                const reworded = await promoteReviewDigest(await side(a, await host.admin.versionMigrations(staff, slug, a)), await side(c, [MIGRATION({ c: 'gone, differently' }, { 't.a': 't.b' })]));
+                expect(reworded).not.toBe(shown.digest);
+                expect((await refusal(host.admin.promoteVersion(staff, slug, 'prod', c, { migrationChange: true, review: { base: a, digest: reworded } }))).kind).toBe('stale');
+                await host.admin.promoteVersion(staff, slug, 'prod', c, { migrationChange: true, review: shown });
+                const row = (await host.admin.auditLog(staff, {})).find((e) => e.action === 'promoteVersion' && JSON.stringify(e.after).includes(c));
+                expect(row?.after?.acknowledged).toEqual({ migrationChange: true, review: shown });
+            });
+        });
+        // -- a rebind's route and pointer move in one write (#2347) ----------------
+        // A rebind onto another lineage is judged against the version the scope is bound to and the
+        // version the target serves. Flipping the route and crossing the pointer used to be two
+        // writes, so a promote on the target between them left the route on the new script and the
+        // pointer on the old lineage. Now they are one write, conditional on both sides.
+        describe("a rebind's route and pointer move in one write, conditional on both sides (#2347)", () => {
+            const lineages = async () => {
+                const tag = ulid().slice(-8).toLowerCase();
+                const [source, target] = [`acme/src-${tag}`, `acme/dst-${tag}`];
+                const put = async (slug) => {
+                    const id = ulid();
+                    await host.admin.publishVersion(staff, {
+                        id, verticalSlug: slug, version: `1.0.${id.slice(-4).toLowerCase()}`, manifestDigest: 'm', permissionDigest: 'p',
+                        migrationDigest: 'g', deploymentRef: null,
+                    });
+                    await host.admin.admitVersion(staff, id);
+                    return id;
+                };
+                for (const slug of [source, target])
+                    await host.admin.registerVertical(staff, { slug, name: slug, source: 'cli', ownerTenant: t1 });
+                const [s1, s2, t1v, t2v] = [await put(source), await put(source), await put(target), await put(target)];
+                const ref = `serving-${tag}`;
+                await host.admin.setVerticalServing(staff, target, { ref, versionId: t1v, doClasses: [], migrationTag: 'g' });
+                const install = async () => {
+                    const sc = scopeId.parse(ulid());
+                    await host.provisionScope(staff, { tenantId: t1, scopeId: sc, vertical: source });
+                    await host.admin.activateScope(staff, t1, sc);
+                    await host.admin.bindScopeVersion(staff, t1, sc, s1);
+                    return sc;
+                };
+                const judged = { vertical: target, ref, versionId: t1v };
+                return { source, target, s1, s2, t1v, t2v, ref, install, judged };
+            };
+            const where = async (sc) => {
+                const r = (await host.admin.getScopeRecord(staff, t1, sc));
+                return { vertical: r.vertical, versionId: r.verticalVersionId, servingRef: r.servingRef ?? null };
+            };
+            const refusal = (p) => p.then(() => undefined, (e) => e);
+            it('lands route and pointer together when both sides still hold, and records both', async () => {
+                const { source, target, s1, t1v, ref, install, judged } = await lineages();
+                const sc = await install();
+                expect(await where(sc)).toEqual({ vertical: source, versionId: s1, servingRef: null });
+                await host.admin.bindScopeVersion(staff, t1, sc, t1v, { servingRef: ref, expectedVersionId: s1, expectedServing: judged });
+                expect(await where(sc)).toEqual({ vertical: target, versionId: t1v, servingRef: ref });
+                const row = (await host.admin.auditLog(staff, { action: 'bindScopeVersion', scopeId: sc }))
+                    .find((e) => e.after?.versionId === t1v);
+                expect(row?.before).toEqual({ servingRef: null });
+                expect(row?.after).toMatchObject({ versionId: t1v, servingRef: ref, expectedVersionId: s1, expectedServing: judged });
+            });
+            it('a promote on the TARGET since the rebind was judged refuses it as stale, and moves neither route nor pointer', async () => {
+                const { source, target, s1, t1v, t2v, ref, install, judged } = await lineages();
+                const sc = await install();
+                // What the target serves moves on after the rebind read it.
+                await host.admin.setVerticalServing(staff, target, { ref, versionId: t2v, doClasses: [], migrationTag: 'g' });
+                const err = await refusal(host.admin.bindScopeVersion(staff, t1, sc, t1v, { servingRef: ref, expectedVersionId: s1, expectedServing: judged }));
+                expect(rebindReviewRefusalOf(err)).toBe('stale');
+                expect(await where(sc)).toEqual({ vertical: source, versionId: s1, servingRef: null });
+                // The twin: judged against what serves now, it lands.
+                await host.admin.bindScopeVersion(staff, t1, sc, t2v, { servingRef: ref, expectedVersionId: s1, expectedServing: { ...judged, versionId: t2v } });
+                expect(await where(sc)).toEqual({ vertical: target, versionId: t2v, servingRef: ref });
+            });
+            it('a move of the SOURCE binding since the rebind was judged refuses it as stale; a plain conditional bind keeps its own refusal', async () => {
+                const { source, s1, s2, t1v, ref, install, judged } = await lineages();
+                const sc = await install();
+                await host.admin.bindScopeVersion(staff, t1, sc, s2);
+                const err = await refusal(host.admin.bindScopeVersion(staff, t1, sc, t1v, { servingRef: ref, expectedVersionId: s1, expectedServing: judged }));
+                expect(rebindReviewRefusalOf(err)).toBe('stale');
+                expect(await where(sc)).toEqual({ vertical: source, versionId: s2, servingRef: null });
+                // Without `expectedServing` the bind is the #1722 compare-and-set it always was.
+                const plain = await refusal(host.admin.bindScopeVersion(staff, t1, sc, s1, { expectedVersionId: s1 }));
+                expect(rebindReviewRefusalOf(plain)).toBeNull();
+                expect(String(plain)).toMatch(/scope binding changed/);
+            });
+            it('racing a promote on the target: either the rebind lands whole, or it is refused as stale and nothing moved', async () => {
+                const { source, target, s1, t1v, t2v, ref, install, judged } = await lineages();
+                for (let round = 0; round < 4; round++) {
+                    const sc = await install();
+                    await host.admin.setVerticalServing(staff, target, { ref, versionId: t1v, doClasses: [], migrationTag: 'g' });
+                    const [rebind] = await Promise.allSettled([
+                        host.admin.bindScopeVersion(staff, t1, sc, t1v, { servingRef: ref, expectedVersionId: s1, expectedServing: judged }),
+                        host.admin.setVerticalServing(staff, target, { ref, versionId: t2v, doClasses: [], migrationTag: 'g' }),
+                    ]);
+                    if (rebind.status === 'fulfilled') {
+                        expect(await where(sc)).toEqual({ vertical: target, versionId: t1v, servingRef: ref });
+                    }
+                    else {
+                        expect(rebindReviewRefusalOf(rebind.reason)).toBe('stale');
+                        expect(await where(sc)).toEqual({ vertical: source, versionId: s1, servingRef: null });
+                    }
+                }
+            });
+        });
         // -- a version that strands people a link bound (#2178) -------------------
         // A binding shape's people keep it until they are released, and the levers need the shape:
         // an unbind needs it to bind, a retirement needs it to be a bootstrap shape, an erasure finds
@@ -5979,8 +6407,8 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                 const id = ulid();
                 await host.admin.publishVersion(staff, {
                     id, verticalSlug: slug, version: `3.0.${id.slice(-4).toLowerCase()}`, manifestDigest: `m-${id}`,
-                    permissionDigest: 'p', migrationDigest: 'g', deploymentRef: null,
-                    manifestJson: JSON.stringify({ registry: { permissions: [], roles: [], entityGrants } }),
+                    permissionDigest: 'p', deploymentRef: null,
+                    ...(await heldMigrations('g', { registry: { permissions: [], roles: [], entityGrants } })),
                 });
                 if (admit)
                     await host.admin.admitVersion(staff, id);
@@ -6078,6 +6506,22 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                 await host.admin.setScopeServingRef(staff, t1, sc, ref);
                 expect(await routeOf()).toBe(ref);
             });
+            it('a bind that routes the scope in the same write (#2347) is judged on the script it routes to', async () => {
+                const { slug, v } = await listed();
+                const sc = await install(slug, v.binds);
+                const ref = `serving-${ulid().slice(-8).toLowerCase()}`;
+                await host.admin.setVerticalServing(staff, slug, { ref, versionId: v.dropped, doClasses: [], migrationTag: 'g' });
+                // The pointer stays on the binding version; the route moves onto a script that runs one
+                // that drops the shape. Judged without the route, this bind would pass.
+                await expectRefusal(host.admin.bindScopeVersion(staff, t1, sc, v.binds, { servingRef: ref }), 'precondition_failed', /drops the shape/);
+                const r = await host.admin.getScopeRecord(staff, t1, sc);
+                expect([r?.verticalVersionId, r?.servingRef ?? null]).toEqual([v.binds, null]);
+                // The twin: the script serves a version that retires the keys, and both move in one write.
+                await host.admin.setVerticalServing(staff, slug, { ref, versionId: v.retired, doClasses: [], migrationTag: 'g' });
+                await host.admin.bindScopeVersion(staff, t1, sc, v.binds, { servingRef: ref });
+                const after = await host.admin.getScopeRecord(staff, t1, sc);
+                expect([after?.verticalVersionId, after?.servingRef]).toEqual([v.binds, ref]);
+            });
             it('a promote is judged from the version served in place too, and replacing what serves is judged like a promote (review of #2181)', async () => {
                 const { slug, v } = await listed();
                 const ref = `serving-${ulid().slice(-8).toLowerCase()}`;
@@ -6467,7 +6911,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                 version,
                 manifestDigest: `man-${version}`,
                 permissionDigest: digests?.perm ?? 'pp',
-                migrationDigest: digests?.mig ?? 'gg',
+                ...(await heldMigrations(digests?.mig ?? 'gg')),
                 deploymentRef: null,
             });
             return id;
@@ -6916,6 +7360,17 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             const reclaimed = (await host.admin.listHostnames(staff, { scopeId: s2 })).find((h) => h.hostname === 'eu.example.com');
             expect(reclaimed?.scopeId).toBe(s2);
         });
+        it('an unbind for one scope leaves a name rebound to another scope bound (#2285)', async () => {
+            // `eu.example.com` is s2's now (the test above). An unroute of s1 that listed the name while
+            // it was s1's must not take it from s2: the owner is judged by the delete itself.
+            const s2Names = async () => (await host.admin.listHostnames(staff, { scopeId: s2 })).map((h) => h.hostname);
+            await host.admin.unbindHostname(staff, 'eu.example.com', { tenantId: t1, scopeId: s1 });
+            expect(await s2Names()).toContain('eu.example.com');
+            // The twin: the owner it names unbinds it, and the unbind is audited on that scope.
+            await host.admin.unbindHostname(staff, 'EU.example.com', { tenantId: t2, scopeId: s2 });
+            expect(await s2Names()).not.toContain('eu.example.com');
+            expect((await host.admin.auditLog(staff, { scopeId: s2 })).map((e) => e.action)).toContain('unbindHostname');
+        });
         it('rejects duplicate module registration', () => {
             expect(() => host.registerModule({ manifest: testModManifest })).toThrow(/already registered/);
         });