@substrat-run/contract-tests 0.120.0 → 0.121.0

package/dist/vertical-events-suite.js

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeAll, afterAll, beforeEach } from 'vitest';
 import { dataSubjectId, eventId, moduleManifest, permissionKey, platformActorId, principalId, scopeId, tenantId, z, } from '@substrat-run/contracts';
-import { assertAllowed, runPlatformSweep, ulid, } from '@substrat-run/kernel';
+import { assertAllowed, crossVerticalHealth, runPlatformSweep, ulid, } from '@substrat-run/kernel';
 // -- the two fixture verticals ------------------------------------------------
 //
 // Named as the verticals of one tenant would be: a CRM that owns customers, and a board-room
@@ -28,8 +28,14 @@ export const crmExportModManifest = moduleManifest.parse({
             { type: 'crm.customer-created', schemaVersion: 1 },
             { type: 'crm.customer-noted', schemaVersion: 1 },
             { type: 'crm.customer-touched', schemaVersion: 1 },
+            // #1705 PR 2: not exported. Its local consumer answers with an exported type, which is
+            // how the kick's signal is shown to count a consumer's emit in the invoke's tail.
+            { type: 'crm.customer-flagged', schemaVersion: 1 },
+        ],
+        consumes: [
+            { from: BOARD_VERTICAL, type: 'board.association-linked', schemaVersion: 1 },
+            { type: 'crm.customer-flagged', schemaVersion: 1 },
         ],
-        consumes: [{ from: BOARD_VERTICAL, type: 'board.association-linked', schemaVersion: 1 }],
         exports: [
             { type: 'crm.customer-created', schemaVersion: 1, readPermission: 'customer:read' },
             { type: 'crm.customer-touched', schemaVersion: 1, readPermission: 'customer:read' },
@@ -93,6 +99,30 @@ const crmTouch = async (ctx, input) => {
         payload: { id: input.id },
     });
 };
+/** Emits an exported type, then throws: the kick's signal must not survive the rollback. */
+const crmCreateThenFail = async (ctx, input) => {
+    assertAllowed(await ctx.check(key('customer:write')));
+    const id = ulid();
+    ctx.emit({
+        type: 'crm.customer-created',
+        schemaVersion: 1,
+        entity: { entityType: 'customer', entityId: id },
+        piiClass: 'none',
+        payload: { id, name: input.name },
+    });
+    throw new Error('crm/create-then-fail fails after emitting, by design');
+};
+/** Emits a type crm does NOT export; its local consumer answers with one it does. */
+const crmFlag = async (ctx, input) => {
+    assertAllowed(await ctx.check(key('customer:write')));
+    ctx.emit({
+        type: 'crm.customer-flagged',
+        schemaVersion: 1,
+        entity: { entityType: 'customer', entityId: input.id },
+        piiClass: 'none',
+        payload: { id: input.id },
+    });
+};
 export const crmExportMod = {
     manifest: crmExportModManifest,
     migrations: [{ version: '0001-init', sql: 'CREATE TABLE crm_customers (id TEXT PRIMARY KEY, name TEXT NOT NULL)' }],
@@ -100,6 +130,21 @@ export const crmExportMod = {
         'crm/create': crmCreate,
         'crm/note': crmNote,
         'crm/touch': crmTouch,
+        'crm/create-then-fail': crmCreateThenFail,
+        'crm/flag': crmFlag,
+    },
+    consumers: {
+        // In the invoke's post-commit tail: an exported type committed by a consumer, not the operation.
+        'crm.customer-flagged': async (ctx, event) => {
+            const { id } = z.object({ id: z.string() }).parse(event.payload);
+            ctx.emit({
+                type: 'crm.customer-created',
+                schemaVersion: 1,
+                entity: { entityType: 'customer', entityId: id },
+                piiClass: 'none',
+                payload: { id, name: 'Flagged' },
+            });
+        },
     },
     imports: {
         [BOARD_VERTICAL]: {
@@ -156,6 +201,7 @@ const boardRead = async (ctx) => {
         imports: ctx.sql.query('SELECT event_id, source_vertical, source_scope_id, type, hops, withheld FROM _substrat_imports ORDER BY event_id'),
         deliveries: ctx.sql.query('SELECT event_id, consumer_module, error FROM _substrat_deliveries ORDER BY event_id, consumer_module'),
         outbox: ctx.sql.query('SELECT id, type, caused_by, actor FROM _substrat_outbox ORDER BY id'),
+        replays: ctx.sql.query('SELECT replay_id, kind, event_id, consumer_module FROM _substrat_import_replays ORDER BY kind, event_id'),
     };
 };
 export const boardImportMod = {
@@ -252,12 +298,18 @@ export function verticalEventsContractSuite(adapterName, makeFixture) {
         // fills from the registry, so the suite also proves that a scope it drops is never called.
         const current = new Set();
         beforeEach(() => current.clear());
-        const reach = {
-            candidates: (scopes) => scopes.filter((s) => current.has(s.tenantId)),
+        const inProcess = {
             importState: async (t, s) => (await hostOf(t, s)).admin.importState(staff, t, s),
             readExports: async (t, s, input) => (await hostOf(t, s)).admin.readExportedEvents(staff, t, s, input),
             deliver: async (t, s, batch) => (await hostOf(t, s)).deliverToPeer(t, s, batch),
         };
+        // Resolved per call, because the fixture is built in `beforeAll`.
+        const reach = {
+            candidates: (scopes) => scopes.filter((s) => current.has(s.tenantId)),
+            importState: (t, s) => (fx.transport ?? inProcess).importState(t, s),
+            readExports: (t, s, input) => (fx.transport ?? inProcess).readExports(t, s, input),
+            deliver: (t, s, batch) => (fx.transport ?? inProcess).deliver(t, s, batch),
+        };
         const newTenant = async () => {
             const t = tenantId.parse(ulid());
             await fx.producer.admin.createTenant(staff, { id: t, slug: `ve-${t.toLowerCase()}`, name: 'Vertical events' });
@@ -280,6 +332,7 @@ export function verticalEventsContractSuite(adapterName, makeFixture) {
                     grantedBy: writer,
                 });
             }
+            await fx.afterInstall?.(t, s, vertical);
             return s;
         };
         const crm = async (t, s, op, input) => (await fx.producer.getScope(writer, t, s)).invoke(op, input);
@@ -302,6 +355,28 @@ export function verticalEventsContractSuite(adapterName, makeFixture) {
             });
             return { report, runs };
         };
+        const lever = (t, s, move) => fx.lever ? fx.lever(t, s, move) : fx.consumer.admin.moveImportCursor(staff, t, s, move);
+        const replay = (after) => ({
+            mode: 'replay',
+            from: CRM_VERTICAL,
+            after: after === null ? null : eventId.parse(after),
+            acknowledge: 'rerun-handlers',
+            reason: 'the board app lost a day of associations',
+        });
+        const skip = (through) => ({
+            mode: 'skip',
+            from: CRM_VERTICAL,
+            through: through === 'now' ? 'now' : eventId.parse(through),
+            acknowledge: 'skip-events',
+            reason: 'the board app starts from today',
+        });
+        const refusal = (x) => x.then(() => undefined, (e) => e);
+        /**
+         * Let the clock pass the millisecond an event was minted in. "Skip to now" passes over earlier
+         * milliseconds only, so a test that needs an event skipped must not share the skip's. A timer,
+         * not a spin: on workerd the clock does not move without I/O.
+         */
+        const nextMillisecond = () => new Promise((r) => setTimeout(r, 2));
         const edgesOf = (report, t) => (report.crossVertical?.edges ?? []).filter((e) => e.tenantId === t);
         /** The edge INTO one consumer scope. crm imports from board too, so a tenant has two. */
         const into = (report, consumer) => (report.crossVertical?.edges ?? []).find((e) => e.consumer.scopeId === consumer);
@@ -329,6 +404,60 @@ export function verticalEventsContractSuite(adapterName, makeFixture) {
             expect(again.every((e) => e.state === 'idle' && e.delivered === 0)).toBe(true);
             expect((await board(t, c)).associations).toHaveLength(2);
         });
+        it('the stub reports a committed exported type, and nothing else — the router kick\'s signal (#1705 PR 2)', async () => {
+            const t = await newTenant();
+            const p = await install(t, CRM_VERTICAL);
+            await install(t, BOARD_VERTICAL);
+            const seen = [];
+            const stub = await fx.producer.getScope(writer, t, p, { onExportedEvents: (n) => seen.push(n) });
+            const id = (await stub.invoke('crm/create', { name: 'Kicked' })).id;
+            expect(seen).toEqual([1]);
+            // A type crm emits but does not export is no reason to run its edges.
+            await stub.invoke('crm/note', { id });
+            expect(seen).toEqual([1]);
+            // Nor is an invoke that committed nothing: refused before it could emit.
+            const refused = await fx.producer.getScope(reader, t, p, { onExportedEvents: (n) => seen.push(n) });
+            await expect(refused.invoke('crm/create', { name: 'Refused' })).rejects.toThrow();
+            expect(seen).toEqual([1]);
+            // Each exported type counts, whichever operation committed it.
+            await stub.invoke('crm/touch', { id });
+            expect(seen).toEqual([1, 1]);
+        });
+        it('the kick\'s signal: never for a rolled-back invoke or a read-only session, and a consumer\'s tail counts (#1705 PR 2)', async () => {
+            const t = await newTenant();
+            const p = await install(t, CRM_VERTICAL);
+            const seen = [];
+            const stub = await fx.producer.getScope(writer, t, p, { onExportedEvents: (n) => seen.push(n) });
+            // Emitted an exported type, then threw: the event rolled back, so there is nothing to kick.
+            await expect(stub.invoke('crm/create-then-fail', { name: 'Gone' })).rejects.toThrow(/by design/);
+            expect(seen).toEqual([]);
+            // The operation emits an unexported type; its local consumer, in the tail, an exported one.
+            await stub.invoke('crm/flag', { id: ulid() });
+            expect(seen).toEqual([1]);
+            // A read-only support session commits nothing, whatever the operation emits.
+            const readOnly = await fx.producer.admin.beginImpersonation(staff, {
+                tenantId: t,
+                scopeId: p,
+                principal: writer,
+                reason: 'ticket #1705 — checking the kick signal',
+                mode: 'read-only',
+            });
+            // The kernel refuses its emit outright (K-42), so the invoke fails and nothing is raised.
+            const ro = await fx.producer.getImpersonatedScope(readOnly.id, t, p, { onExportedEvents: (n) => seen.push(n) });
+            await expect(ro.invoke('crm/create', { name: 'Looked at' })).rejects.toThrow(/read-only/);
+            expect(seen).toEqual([1]);
+            // The twin: a WRITE session that commits the same operation does raise it.
+            const write = await fx.producer.admin.beginImpersonation(staff, {
+                tenantId: t,
+                scopeId: p,
+                principal: writer,
+                reason: 'ticket #1705 — the write twin',
+                mode: 'write',
+            });
+            const rw = await fx.producer.getImpersonatedScope(write.id, t, p, { onExportedEvents: (n) => seen.push(n) });
+            await rw.invoke('crm/create', { name: 'Written' });
+            expect(seen).toEqual([1, 1]);
+        });
         it('never crosses a tenant: each consumer receives its own tenant\'s producer, and none from another', async () => {
             const t = await newTenant();
             const u = await newTenant();
@@ -559,6 +688,464 @@ export function verticalEventsContractSuite(adapterName, makeFixture) {
             await sweep();
             expect((await board(t, c)).associations.map((r) => r.crm_id)).toEqual([during]);
         });
+        // -- the replay lever (#1705 PR 3) ---------------------------------------------------------
+        it('replay from the start: every handler runs again, and the first delivery\'s record is moved aside, not deleted', async () => {
+            const t = await newTenant();
+            const p = await install(t, CRM_VERTICAL);
+            const c = await install(t, BOARD_VERTICAL);
+            await create(t, p, 'Alpha');
+            await create(t, p, 'Beta');
+            await sweep();
+            const before = await board(t, c);
+            const created = (v) => v.outbox.filter((o) => o.type === 'board.association-created');
+            expect(created(before)).toHaveLength(2);
+            const moved = await lever(t, c, replay(null));
+            expect(moved).toMatchObject({ mode: 'replay', cursor: null, source: { vertical: CRM_VERTICAL, scopeId: p } });
+            expect(moved.previous).not.toBeNull();
+            expect(moved.archived).toEqual({ journal: 2, deliveries: 2 });
+            // The evidence of the first delivery stays, under the act that moved it.
+            const aside = await board(t, c);
+            expect(aside.replays.filter((r) => r.kind === 'journal').map((r) => r.event_id)).toEqual(before.imports.map((i) => i.event_id));
+            expect(aside.replays.filter((r) => r.kind === 'delivery')).toHaveLength(2);
+            expect(new Set(aside.replays.map((r) => r.replay_id))).toEqual(new Set([moved.replayId]));
+            // ...and it has left the LIVE journal, so the redelivery journals each event afresh: an event
+            // first withheld for its version is decided again rather than kept as withheld forever.
+            expect(aside.imports).toEqual([]);
+            expect(aside.deliveries).toEqual([]);
+            // The admin log names the act, its reason and what it moved.
+            const log = await fx.consumer.admin.auditLog(staff, { tenantId: t, action: ['moveImportCursor'] });
+            expect(log.map((e) => e.after.phase).sort()).toEqual(['applied', 'intent']);
+            expect(log.every((e) => e.after.replayId === moved.replayId)).toBe(true);
+            // The next pass delivers both again, and each handler RUNS again: that is what a replay is.
+            const { report } = await sweep();
+            expect(into(report, c)).toMatchObject({ state: 'delivered', delivered: 2, duplicates: 0 });
+            const after = await board(t, c);
+            expect(created(after)).toHaveLength(4);
+            expect(after.associations.map((r) => r.name)).toEqual(['Alpha', 'Beta']);
+            expect(after.imports.map((i) => i.event_id)).toEqual(before.imports.map((i) => i.event_id));
+        });
+        it('replay from a point: only the events after it run again', async () => {
+            const t = await newTenant();
+            const p = await install(t, CRM_VERTICAL);
+            const c = await install(t, BOARD_VERTICAL);
+            await create(t, p, 'Kept');
+            await create(t, p, 'Replayed');
+            await sweep();
+            const [first, second] = (await board(t, c)).imports;
+            const moved = await lever(t, c, replay(first.event_id));
+            expect(moved).toMatchObject({ cursor: first.event_id, archived: { journal: 1, deliveries: 1 } });
+            await sweep();
+            const view = await board(t, c);
+            // The positive twin of the whole-history replay: the first event's handler did not run again.
+            const createdFor = (id) => view.outbox.filter((o) => o.type === 'board.association-created' && o.caused_by === id).length;
+            expect(createdFor(first.event_id)).toBe(1);
+            expect(createdFor(second.event_id)).toBe(2);
+        });
+        it('skip to now: nothing before the skip is delivered, what comes after is, and a replay reaches back', async () => {
+            const t = await newTenant();
+            const p = await install(t, CRM_VERTICAL);
+            const c = await install(t, BOARD_VERTICAL);
+            await create(t, p, 'Before the skip');
+            await nextMillisecond();
+            const moved = await lever(t, c, skip('now'));
+            expect(moved).toMatchObject({ mode: 'skip', previous: null, archived: { journal: 0, deliveries: 0 } });
+            expect(moved.cursor).not.toBeNull();
+            await sweep();
+            expect((await board(t, c)).associations).toEqual([]);
+            await create(t, p, 'After the skip');
+            await sweep();
+            expect((await board(t, c)).associations.map((r) => r.name)).toEqual(['After the skip']);
+            // Recoverable: the producer's outbox kept what was skipped.
+            await lever(t, c, replay(null));
+            await sweep();
+            expect((await board(t, c)).associations.map((r) => r.name).sort()).toEqual(['After the skip', 'Before the skip']);
+        });
+        it('a pass that read before a move is refused by the watermark\'s compare-and-set, and cannot undo it', async () => {
+            const t = await newTenant();
+            const p = await install(t, CRM_VERTICAL);
+            const c = await install(t, BOARD_VERTICAL);
+            await create(t, p, 'Read before the skip');
+            await nextMillisecond();
+            const read = await fx.producer.admin.readExportedEvents(staff, t, p, {
+                consumer: BOARD_VERTICAL,
+                after: null,
+                wants: [{ type: 'crm.customer-created', schemaVersion: 1 }],
+                limit: 100,
+            });
+            const moved = await lever(t, c, skip('now'));
+            const late = await fx.consumer.deliverToPeer(t, c, {
+                source: { vertical: CRM_VERTICAL, scopeId: p },
+                after: null,
+                next: read.next,
+                events: read.events,
+                withheld: read.withheld,
+            });
+            expect(late).toMatchObject({ stale: true, delivered: 0, cursor: moved.cursor });
+            expect((await board(t, c)).associations).toEqual([]);
+        });
+        it('the lever holds each mode to its direction, and a replay needs something to replay', async () => {
+            const t = await newTenant();
+            const p = await install(t, CRM_VERTICAL);
+            const c = await install(t, BOARD_VERTICAL);
+            // Nothing taken yet: there is nothing to run again.
+            expect(String(await refusal(lever(t, c, replay(null))))).toMatch(/nothing to replay/);
+            await create(t, p, 'One');
+            await create(t, p, 'Two');
+            await sweep();
+            const [first, second] = (await board(t, c)).imports;
+            // A skip behind the watermark is a replay, and a replay ahead of it is a skip.
+            expect(String(await refusal(lever(t, c, skip(first.event_id))))).toMatch(/skip moves the watermark forward/);
+            expect(String(await refusal(lever(t, c, replay(ulid()))))).toMatch(/replay moves the watermark back/);
+            // Neither refusal moved anything: the next pass is idle.
+            expect(into((await sweep()).report, c)).toMatchObject({ state: 'idle' });
+            // The positive twins, each in its own direction.
+            await expect(lever(t, c, replay(first.event_id))).resolves.toMatchObject({ cursor: first.event_id });
+            await expect(lever(t, c, skip(second.event_id))).resolves.toMatchObject({ cursor: second.event_id });
+        });
+        it('a skip cannot be aimed past now: the future is refused, and the edge still reads behind', async () => {
+            const t = await newTenant();
+            const p = await install(t, CRM_VERTICAL);
+            const c = await install(t, BOARD_VERTICAL);
+            await create(t, p, 'Waiting');
+            // The greatest ULID there is: a watermark past every event ever to be written.
+            expect(String(await refusal(lever(t, c, skip('7ZZZZZZZZZZZZZZZZZZZZZZZZZ'))))).toMatch(/at most now.*future/);
+            expect((await fx.consumer.admin.importState(staff, t, c)).cursors).toEqual([]);
+            expect(await healthOf(t, c)).toMatchObject({ state: 'behind' });
+            // The twin: to now, it moves, and an event written after it still arrives.
+            await nextMillisecond();
+            await lever(t, c, skip('now'));
+            await create(t, p, 'After');
+            await sweep();
+            expect((await board(t, c)).associations.map((r) => r.name)).toEqual(['After']);
+        });
+        it('skip to now never drops an event of its own millisecond: on the boundary it delivers', async () => {
+            const t = await newTenant();
+            const p = await install(t, CRM_VERTICAL);
+            const c = await install(t, BOARD_VERTICAL);
+            const moved = await lever(t, c, skip('now'));
+            // Whatever is written next, however soon, sorts after the watermark: it cannot have been
+            // minted in a millisecond earlier than the skip's.
+            await create(t, p, 'Right after');
+            await sweep();
+            expect((await board(t, c)).associations.map((r) => r.name)).toEqual(['Right after']);
+            expect(moved.cursor < ulid()).toBe(true);
+        });
+        it('the replay history is part of the scope: a dump carries it, and a restore puts it back or takes it away', async () => {
+            const t = await newTenant();
+            const p = await install(t, CRM_VERTICAL);
+            const c = await install(t, BOARD_VERTICAL);
+            await create(t, p, 'Dumped');
+            await sweep();
+            const beforeReplay = await fx.consumer.admin.exportScope(staff, t, c);
+            const moved = await lever(t, c, replay(null));
+            const afterReplay = await fx.consumer.admin.exportScope(staff, t, c);
+            const table = afterReplay.tables.find((x) => x.name === '_substrat_import_replays');
+            expect(table?.rows.length).toBe(2);
+            // Restoring the dump from before the replay takes the history away, as it rewinds the data.
+            await fx.consumer.restoreScope(staff, t, c, beforeReplay);
+            expect((await board(t, c)).replays).toEqual([]);
+            // Restoring the dump from after it puts the history back, under the same act.
+            await fx.consumer.restoreScope(staff, t, c, afterReplay);
+            const back = (await board(t, c)).replays;
+            expect(back).toHaveLength(2);
+            expect(new Set(back.map((r) => r.replay_id))).toEqual(new Set([moved.replayId]));
+        });
+        it('the lever moves only an edge the consumer imports: a skip cannot plant a watermark for one that does not exist', async () => {
+            const t = await newTenant();
+            await install(t, CRM_VERTICAL);
+            const c = await install(t, BOARD_VERTICAL);
+            // Installed in the tenant, and imported by nobody.
+            await install(t, 'acme/ledger');
+            const plant = { ...skip('now'), from: 'acme/ledger' };
+            expect(String(await refusal(lever(t, c, plant)))).toMatch(/imports nothing from 'acme\/ledger'/);
+            expect((await fx.consumer.admin.importState(staff, t, c)).cursors).toEqual([]);
+            // The twin: the edge it does import moves.
+            await expect(lever(t, c, skip('now'))).resolves.toMatchObject({ source: { vertical: CRM_VERTICAL } });
+        });
+        it('a replay without its acknowledgement never reaches the store', async () => {
+            const t = await newTenant();
+            const p = await install(t, CRM_VERTICAL);
+            const c = await install(t, BOARD_VERTICAL);
+            await create(t, p, 'Acknowledged');
+            await sweep();
+            const { acknowledge: _, ...bare } = replay(null);
+            await expect(lever(t, c, bare)).rejects.toThrow();
+            const wrong = { ...replay(null), acknowledge: 'skip-events' };
+            await expect(lever(t, c, wrong)).rejects.toThrow();
+            expect((await board(t, c)).replays).toEqual([]);
+            // The twin: acknowledged, it moves.
+            await expect(lever(t, c, replay(null))).resolves.toMatchObject({ archived: { journal: 1 } });
+        });
+        it('the lever never crosses a tenant: another tenant\'s scope is not found, and the producer is the consumer\'s own tenant\'s', async () => {
+            const t = await newTenant();
+            const u = await newTenant();
+            const pt = await install(t, CRM_VERTICAL);
+            const ct = await install(t, BOARD_VERTICAL);
+            const pu = await install(u, CRM_VERTICAL);
+            const cu = await install(u, BOARD_VERTICAL);
+            await create(t, pt, 'T');
+            await create(u, pu, 'U');
+            await sweep();
+            const cursorOf = async (tt, cc) => (await fx.consumer.admin.importState(staff, tt, cc)).cursors.map((x) => [x.source, x.cursor]);
+            const uBefore = await cursorOf(u, cu);
+            // u's consumer scope named under t: not found, and nothing moved anywhere.
+            expect(String(await refusal(lever(t, cu, replay(null))))).toMatch(/unknown scope|not found|conflict/i);
+            expect(await cursorOf(u, cu)).toEqual(uBefore);
+            // t's replay resolves t's producer, and moves t's edge only.
+            const moved = await lever(t, ct, replay(null));
+            expect(moved.source.scopeId).toBe(pt);
+            expect(await cursorOf(u, cu)).toEqual(uBefore);
+            // A tenant with no producer has no edge to move.
+            const v = await newTenant();
+            const cv = await install(v, BOARD_VERTICAL);
+            expect(String(await refusal(lever(v, cv, skip('now'))))).toMatch(/not installed in this tenant/);
+        });
+        // -- edge health (#1705 PR 3) --------------------------------------------------------------
+        const health = (t, override = {}) => crossVerticalHealth(fx.consumer, {
+            actor: staff,
+            tenantId: t,
+            crossVertical: { reach: { ...reach, ...override } },
+            ...(fx.door ? { door: fx.door } : {}),
+        });
+        const healthOf = async (t, c, override = {}) => (await health(t, override)).edges.find((e) => e.consumer.scopeId === c);
+        it('edge health: behind before a pass (with its lag), caught up after, and the pass that delivered', async () => {
+            const t = await newTenant();
+            const p = await install(t, CRM_VERTICAL);
+            const c = await install(t, BOARD_VERTICAL);
+            await create(t, p, 'Waiting');
+            const before = await healthOf(t, c);
+            expect(before).toMatchObject({
+                state: 'behind',
+                producer: { vertical: CRM_VERTICAL, scopeId: p },
+                watermark: null,
+                lastDelivered: null,
+            });
+            expect(before?.oldestPending).not.toBeNull();
+            expect(before?.lagMs).toBeGreaterThanOrEqual(0);
+            // The probe delivered nothing: the view is a read.
+            expect((await board(t, c)).associations).toEqual([]);
+            await sweep();
+            const after = await healthOf(t, c);
+            expect(after).toMatchObject({ state: 'caught-up', oldestPending: null, lagMs: null, reason: null });
+            expect(after?.watermark).not.toBeNull();
+            // A door that cannot be read changes nothing about a caught-up edge: its reason stays null.
+            const unreadDoor = await crossVerticalHealth(fx.consumer, {
+                actor: staff,
+                tenantId: t,
+                crossVertical: { reach },
+                door: async () => {
+                    throw new Error('door unreadable');
+                },
+            });
+            expect(unreadDoor.edges.find((e) => e.consumer.scopeId === c)).toMatchObject({ state: 'caught-up', reason: null });
+            // What the consumer asks for and the producer does not export, reported beside the state.
+            // (The sweep-run history is covered where the rows are durable: the control plane's route.)
+            expect(after?.unexported).toEqual([{ type: 'crm.customer-noted', schemaVersion: 1 }]);
+        });
+        it('edge health: paused by the producer, and paused at the consumer\'s door, each saying why', async () => {
+            const t = await newTenant();
+            const p = await install(t, CRM_VERTICAL);
+            const c = await install(t, BOARD_VERTICAL);
+            await create(t, p, 'Held');
+            await fx.producer.admin.revokeFromPeer(staff, { vertical: BOARD_VERTICAL, node: { tenantId: t, scopeId: p }, reason: 'stop exports' });
+            expect(await healthOf(t, c)).toMatchObject({
+                state: 'paused',
+                reason: expect.stringContaining(`does not grant vertical:${BOARD_VERTICAL} customer:read`),
+            });
+            await fx.producer.admin.restoreToPeer(staff, { vertical: BOARD_VERTICAL, node: { tenantId: t, scopeId: p }, reason: 'ok' });
+            // The twin: granted again, the edge is merely behind.
+            expect(await healthOf(t, c)).toMatchObject({ state: 'behind' });
+            await fx.consumer.admin.revokeFromPeer(staff, {
+                vertical: CRM_VERTICAL,
+                node: { tenantId: t, scopeId: c },
+                reason: 'board stops taking CRM changes',
+            });
+            expect(await healthOf(t, c)).toMatchObject({
+                state: 'paused',
+                reason: expect.stringContaining(`has '${CRM_VERTICAL}' switched off`),
+            });
+            // Paused at the door, the backlog is still dated.
+            expect((await healthOf(t, c))?.oldestPending).not.toBeNull();
+        });
+        it('edge health: a producer missing from the tenant is unresolved, and a side that cannot be asked is unavailable, never healthy', async () => {
+            const t = await newTenant();
+            const c = await install(t, BOARD_VERTICAL);
+            expect(await healthOf(t, c)).toMatchObject({
+                state: 'unresolved',
+                reason: `'${CRM_VERTICAL}' is not installed in this tenant`,
+            });
+            const u = await newTenant();
+            const pu = await install(u, CRM_VERTICAL);
+            const cu = await install(u, BOARD_VERTICAL);
+            await create(u, pu, 'Unknown');
+            // The consumer cannot be asked.
+            const noConsumer = await healthOf(u, cu, {
+                importState: async () => {
+                    throw new Error('the deployment serving this scope predates cross-vertical events — redeploy it');
+                },
+            });
+            expect(noConsumer).toMatchObject({ state: 'unavailable', producer: { vertical: '*' }, reason: expect.stringMatching(/redeploy/) });
+            // The producer cannot be asked.
+            const noProducer = await healthOf(u, cu, {
+                readExports: async () => {
+                    throw new Error('vertical unreachable');
+                },
+            });
+            expect(noProducer).toMatchObject({ state: 'unavailable', producer: { vertical: CRM_VERTICAL }, reason: expect.stringMatching(/unreachable/) });
+            // The twin: asked, it answers.
+            expect(await healthOf(u, cu)).toMatchObject({ state: 'behind' });
+        });
+        it('edge health focused on one app shows its edges into it and out of it, and nothing else', async () => {
+            const t = await newTenant();
+            const p = await install(t, CRM_VERTICAL);
+            const c = await install(t, BOARD_VERTICAL);
+            const focused = (focus) => crossVerticalHealth(fx.consumer, {
+                actor: staff,
+                tenantId: t,
+                focus,
+                crossVertical: { reach },
+                ...(fx.door ? { door: fx.door } : {}),
+            });
+            const all = await health(t);
+            // crm imports from board and board from crm: two edges in the tenant.
+            expect(all.edges).toHaveLength(2);
+            // On the board app, both touch it: board ← crm (into), crm ← board (out of).
+            const onBoard = await focused(c);
+            expect(onBoard.edges.map((e) => `${e.consumer.scopeId}:${e.producer.vertical}`).sort()).toEqual([`${c}:${CRM_VERTICAL}`, `${p}:${BOARD_VERTICAL}`].sort());
+            // A scope that is no install at all has no edges, and asks nothing.
+            expect((await focused(scopeId.parse(ulid()))).edges).toEqual([]);
+            // A consumer that cannot be asked stays on its PRODUCER's view, as a failure there: tagged
+            // with the producer, since it names none itself, so a per-app filter keeps it.
+            const unreachable = await crossVerticalHealth(fx.consumer, {
+                actor: staff,
+                tenantId: t,
+                focus: p,
+                crossVertical: {
+                    reach: {
+                        ...reach,
+                        importState: (tt, s) => s === c ? Promise.reject(new Error('the board deployment is down')) : reach.importState(tt, s),
+                    },
+                },
+                ...(fx.door ? { door: fx.door } : {}),
+            });
+            const out = unreachable.edges.find((e) => e.consumer.scopeId === c);
+            expect(out).toMatchObject({ state: 'unavailable', producer: { vertical: CRM_VERTICAL, scopeId: p } });
+            expect(out?.reason).toMatch(/board deployment is down/);
+            // Unfocused, the same failure names no producer: the tenant view shows it under '*'.
+            const tenantWide = await health(t, {
+                importState: (tt, s) => (s === c ? Promise.reject(new Error('down')) : reach.importState(tt, s)),
+            });
+            expect(tenantWide.edges.find((e) => e.consumer.scopeId === c)).toMatchObject({ producer: { vertical: '*', scopeId: null } });
+        });
+        it('edge health reads each edge\'s history on its own: a noisy edge cannot push out a quiet one\'s last delivery', async () => {
+            const t = await newTenant();
+            const p = await install(t, CRM_VERTICAL);
+            const c = await install(t, BOARD_VERTICAL);
+            const quiet = `${c}:${CRM_VERTICAL}`;
+            const noisy = `${p}:${BOARD_VERTICAL}`;
+            const row = (unit, outcome, scope) => ({
+                kind: 'vertical-events',
+                unit,
+                outcome,
+                tenantId: t,
+                scopeId: scope,
+                operation: 'sweep.vertical-events:test',
+                error: outcome === 'ok' ? null : 'the producer is unreachable',
+            });
+            await fx.consumer.admin.recordSweepRun(row(quiet, 'ok', c));
+            // Far more than any one tenant-wide window: the quiet edge's row is the oldest by far.
+            for (let i = 0; i < 250; i++)
+                await fx.consumer.admin.recordSweepRun(row(noisy, 'failed', p));
+            const view = await health(t);
+            expect(view.history.available).toBe(true);
+            expect(view.edges.find((e) => e.consumer.scopeId === c)?.lastDelivered).not.toBeNull();
+            expect(view.edges.find((e) => e.consumer.scopeId === p)).toMatchObject({
+                lastDelivered: null,
+                lastProblem: { outcome: 'failed', error: 'the producer is unreachable' },
+            });
+        });
+        it('edge health never crosses a tenant: one tenant\'s view names only its own edges', async () => {
+            const t = await newTenant();
+            const u = await newTenant();
+            await install(t, CRM_VERTICAL);
+            const ct = await install(t, BOARD_VERTICAL);
+            await install(u, CRM_VERTICAL);
+            const cu = await install(u, BOARD_VERTICAL);
+            const view = await health(t);
+            expect(view.edges.some((e) => e.consumer.scopeId === ct)).toBe(true);
+            expect(view.edges.every((e) => e.tenantId === t)).toBe(true);
+            expect(view.edges.some((e) => e.consumer.scopeId === cu)).toBe(false);
+        });
+        // -- the promote refusal (#1705 PR 3) ------------------------------------------------------
+        it('a promote that drops or re-versions an export an installed app imports is refused, and acknowledged it passes', async () => {
+            // Fresh slugs: a channel is per vertical and fleet-wide, so this test must own its pair.
+            const tag = ulid().slice(-8).toLowerCase();
+            const producer = `acme/ex-${tag}`;
+            const consumer = `acme/in-${tag}`;
+            const TYPE = 'crm.customer-created';
+            for (const slug of [producer, consumer]) {
+                await fx.consumer.admin.registerVertical(staff, { slug, name: slug, source: 'cli' });
+            }
+            const registry = (extra) => JSON.stringify({ registry: { permissions: [], roles: [], entityGrants: [], ...extra } });
+            const exporting = (v) => registry(v === null ? {} : { exports: [{ type: TYPE, schemaVersion: v, readPermission: 'customer:read', declaredBy: ['@test/x'] }] });
+            const publish = async (slug, manifestJson, perm = 'p') => {
+                const id = ulid();
+                await fx.consumer.admin.publishVersion(staff, {
+                    id,
+                    verticalSlug: slug,
+                    version: `1.0.${id.slice(-4).toLowerCase()}`,
+                    manifestDigest: `m-${id}`,
+                    permissionDigest: perm,
+                    migrationDigest: 'g',
+                    deploymentRef: null,
+                    manifestJson,
+                });
+                await fx.consumer.admin.admitVersion(staff, id);
+                return id;
+            };
+            const prodOf = async (slug) => (await fx.consumer.admin.listChannels(staff, slug)).find((ch) => ch.channel === 'prod')?.versionId;
+            // The producer exports TYPE v1. A tenant runs it beside a consumer whose version imports it.
+            const v1 = await publish(producer, exporting(1));
+            await fx.consumer.admin.promoteVersion(staff, producer, 'prod', v1);
+            const imports = registry({ imports: [{ from: producer, type: TYPE, schemaVersion: 1, declaredBy: ['@test/y'] }] });
+            const consumerVersion = await publish(consumer, imports);
+            const t = await newTenant();
+            const u = await newTenant();
+            const bindAt = async (tenant, slug, version) => {
+                const sc = scopeId.parse(ulid());
+                await fx.consumer.provisionScope(staff, { tenantId: tenant, scopeId: sc, vertical: slug });
+                await fx.consumer.admin.activateScope(staff, tenant, sc);
+                if (version)
+                    await fx.consumer.admin.bindScopeVersion(staff, tenant, sc, version);
+                return sc;
+            };
+            await bindAt(t, producer, v1);
+            const ct = await bindAt(t, consumer, consumerVersion);
+            // A tenant that runs the consumer but not the producer has no edge, so nothing of it breaks.
+            await bindAt(u, consumer, consumerVersion);
+            // The twin first: a version that keeps the export promotes with no new acknowledgement.
+            const same = await publish(producer, exporting(1));
+            await expect(fx.consumer.admin.promotionImpact(staff, producer, 'prod', same)).resolves.toEqual([]);
+            await fx.consumer.admin.promoteVersion(staff, producer, 'prod', same);
+            // Dropped: refused, the channel unmoved, and the refusal counts without naming a tenant.
+            const dropped = await publish(producer, exporting(null));
+            const refused = await refusal(fx.consumer.admin.promoteVersion(staff, producer, 'prod', dropped));
+            expect(String(refused)).toMatch(/drops or re-versions 1 exported event type\(s\) that 1 installed app\(s\) in 1 tenant\(s\)/);
+            expect(String(refused)).not.toContain(t);
+            expect(await prodOf(producer)).toBe(same);
+            // The listing is the read beside it, and names exactly the app in the producer's tenant.
+            expect(await fx.consumer.admin.promotionImpact(staff, producer, 'prod', dropped)).toEqual([
+                { tenantId: t, scopeId: ct, vertical: consumer, version: consumerVersion, type: TYPE, schemaVersion: 1, incoming: null },
+            ]);
+            // Re-versioned is a break too, and says what it became.
+            const bumped = await publish(producer, exporting(2));
+            expect((await fx.consumer.admin.promotionImpact(staff, producer, 'prod', bumped))[0]).toMatchObject({ incoming: 2 });
+            // Acknowledged, it promotes, and the admin log records the acknowledgement.
+            await fx.consumer.admin.promoteVersion(staff, producer, 'prod', dropped, { exportBreak: true });
+            expect(await prodOf(producer)).toBe(dropped);
+            const log = await fx.consumer.admin.auditLog(staff, { action: 'promoteVersion' });
+            expect(log.some((e) => JSON.stringify(e.after).includes('"exportBreak":true'))).toBe(true);
+        });
         it('a fork is neither read nor fed, and two primary installs are refused rather than guessed between', async () => {
             const t = await newTenant();
             const p = await install(t, CRM_VERTICAL);