@substrat-run/contract-tests 0.135.0 → 0.137.0

package/dist/scope-host-suite.js

@@ -1,8 +1,8 @@
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
 import { connectorCalls, connectorTestFetch, resetConnectorCalls } from './connector-fixture.js';
 import { connectionId, dataSubjectId, domainEvent, errorCodeOf, eventId, instant, moduleManifest, orgId, AUTO_ADMISSION_NOTE, permissionKey, platformActorId, platformRequestId, principalId, scopeId, tenantId, SCOPE_QUERY_ROW_MAX, KERNEL_AUTHORED_EVENT_TYPES, SWEEP_RUNS_KIND, SCOPE_TABLE_PAGE_MAX, } from '@substrat-run/contracts';
-import { isSearchIndexTable, platformIntentFailureMessage, REDACTED_DELIVERY_NOTE, REDACTED_FAILURE_NOTE, REDACTED_INTENT_MARKER, runPlatformSweep, startPlatformSweeper, ulid, } from '@substrat-run/kernel';
-import { billedMod, contractTestBareOps, contractTestInitialModules, gateModManifest, lateMod, testModManifest, victimModManifest, } from './modules.js';
+import { INERT_SCOPE_REASON, isSearchIndexTable, platformIntentFailureMessage, REDACTED_DELIVERY_NOTE, REDACTED_FAILURE_NOTE, REDACTED_INTENT_MARKER, runPlatformSweep, startPlatformSweeper, createUlid, ulid, } from '@substrat-run/kernel';
+import { billedMod, contractTestBareOps, contractTestInitialModules, gateModManifest, lateMod, TEST_LIFECYCLE, testModManifest, victimModManifest, } from './modules.js';
 /**
  * Assert a refusal by the CODE it declared, not by the sentence it happens to carry
  * (#113 phase 5).
@@ -376,6 +376,253 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             expect(settled.lastError).toMatch(/personal number field/);
             expect(settled.payload).toEqual({ contract: 'c1' });
         });
+        /**
+         * #1686. The platform's drain walks every active scope, and a fork, a snapshot or a preview
+         * is one, so an intent copied while still pending would be executed a second time from the
+         * copy: an email sent twice, a connector delivery repeated. `listPlatformRequests` is the
+         * drain's one read, so what it returns on the copy is exactly what a drain would run.
+         */
+        describe("a copy never runs the source's pending intents (#1686)", () => {
+            let source;
+            let id;
+            const pendingAt = async (s) => (await host.listPlatformRequests(t1, s)).map((r) => r.id);
+            const historyAt = async (s) => (await host.listPlatformRequestHistory(t1, s)).find((r) => r.id === id);
+            /** The copy: the intent is not drainable there, and its journal says why. */
+            const notCarriedAt = async (copy) => {
+                expect(await pendingAt(copy)).not.toContain(id);
+                expect(await historyAt(copy)).toMatchObject({
+                    status: 'failed',
+                    failure: { origin: 'platform', code: 'precondition_failed', permission: null },
+                    lastError: expect.stringMatching(new RegExp(`^not carried: copied from scope ${source}`)),
+                    settledAt: expect.any(String),
+                });
+                // The twin: the source still holds it pending, for its own drain.
+                expect(await pendingAt(source)).toContain(id);
+            };
+            beforeAll(async () => {
+                source = scopeId.parse(ulid());
+                await host.provisionScope(staff, { tenantId: t1, scopeId: source, jurisdiction: 'eu', vertical: 'connector-vertical' });
+                await host.admin.activateScope(staff, t1, source);
+                id = await (await host.getScope(alice, t1, source)).invoke('platform/request', {
+                    kind: 'provision-sibling',
+                    payload: { slug: 'copied' },
+                });
+                expect(await pendingAt(source)).toContain(id);
+            });
+            it('a fork (importScope) settles it not-carried; the source keeps it pending', async () => {
+                const fork = scopeId.parse(ulid());
+                await host.importScope(staff, { tenantId: t1, scopeId: fork, jurisdiction: 'eu', vertical: 'connector-vertical' }, await host.admin.exportScope(staff, t1, source));
+                await notCarriedAt(fork);
+            });
+            it('a snapshot (snapshotScope): the same', async () => {
+                await notCarriedAt(await host.snapshotScope(staff, t1, source, { kind: 'preview' }));
+            });
+            it("a restore of the source's backup onto another scope: the same", async () => {
+                const other = scopeId.parse(ulid());
+                await host.provisionScope(staff, { tenantId: t1, scopeId: other, jurisdiction: 'eu', vertical: 'connector-vertical' });
+                await host.admin.activateScope(staff, t1, other);
+                await host.restoreScope(staff, t1, other, await host.admin.exportScope(staff, t1, source));
+                await notCarriedAt(other);
+            });
+            it('a restore into the scope the backup came from keeps it pending, payload and all', async () => {
+                await host.restoreScope(staff, t1, source, await host.admin.exportScope(staff, t1, source));
+                const back = (await host.listPlatformRequests(t1, source)).find((r) => r.id === id);
+                expect(back).toMatchObject({ status: 'pending', payload: { slug: 'copied' }, lastError: null, settledAt: null });
+            });
+        });
+        /**
+         * #1686, the rest of the queue. Delivery is "no delivery row yet", so an event the source
+         * emitted and nobody reached is owed work in the copy too, and an executor retry is due work.
+         * The dump below is the source's own export with the journal set back: the consumer's row
+         * for one event removed (never delivered), one executor delivery made due for a retry, and
+         * another removed (never attempted).
+         */
+        describe('a copy never runs work the source queued (#1686)', () => {
+            let source;
+            let queued;
+            let step1;
+            const count = (tag) => effected.filter((e) => e === tag).length;
+            const logOf = async (s) => (await (await host.getScope(alice, t1, s)).invoke('flow/log')).map((r) => r.event_id);
+            /**
+             * The events whose executor delivery a copy journaled INERT (#2005): its own work, which
+             * reached dispatch — so `emittedHere` let it through — and was then held, because a copy
+             * causes no outbound effects. The source's work never reaches dispatch at all.
+             */
+            const inertIn = async (s) => (await host.executorDeadLetters(t1, s)).filter((d) => d.error === INERT_SCOPE_REASON).map((d) => d.eventId);
+            const eventIdOf = async (s, entityId) => {
+                const outbox = (await host.admin.exportScope(staff, t1, s)).tables.find((t) => t.name === '_substrat_outbox');
+                return String(outbox.rows.find((r) => r[outbox.columns.indexOf('entity_id')] === entityId)[outbox.columns.indexOf('id')]);
+            };
+            const activeScope = async () => {
+                const s = scopeId.parse(ulid());
+                await host.provisionScope(staff, { tenantId: t1, scopeId: s, jurisdiction: 'eu', vertical: 'connector-vertical' });
+                await host.admin.activateScope(staff, t1, s);
+                return s;
+            };
+            beforeAll(async () => {
+                source = await activeScope();
+                const stub = await host.getScope(alice, t1, source);
+                await stub.invoke('flow/produce');
+                await stub.invoke('connector/request-effect', { tag: 'copy-retry' });
+                await stub.invoke('connector/request-effect', { tag: 'copy-unattempted' });
+                // The source ran all three: the consumer logged step1, the executor effected both.
+                expect(count('copy-retry')).toBe(1);
+                expect(count('copy-unattempted')).toBe(1);
+                const dump = await host.admin.exportScope(staff, t1, source);
+                const outbox = dump.tables.find((t) => t.name === '_substrat_outbox');
+                const col = (name) => outbox.columns.indexOf(name);
+                const idOf = (type, entityId) => String(outbox.rows.find((r) => r[col('type')] === type && r[col('entity_id')] === entityId)[col('id')]);
+                step1 = idOf('flow.step1', 'f1');
+                const retry = idOf('effect.requested', 'copy-retry');
+                const unattempted = idOf('effect.requested', 'copy-unattempted');
+                expect(await logOf(source)).toContain(step1);
+                queued = {
+                    ...dump,
+                    tables: dump.tables.map((t) => {
+                        // The consumer's own record of the delivery goes with the delivery row.
+                        if (t.name === 'flow_log')
+                            return { ...t, rows: [] };
+                        if (t.name !== '_substrat_deliveries')
+                            return t;
+                        const at = (name) => t.columns.indexOf(name);
+                        const rows = t.rows
+                            .filter((r) => !(r[at('event_id')] === step1 && r[at('consumer_module')] === '@test/flow'))
+                            .filter((r) => r[at('event_id')] !== unattempted)
+                            .map((r) => {
+                            if (r[at('event_id')] !== retry)
+                                return r;
+                            const due = [...r];
+                            due[at('error')] = 'boom';
+                            due[at('attempts')] = 1;
+                            due[at('next_attempt_at')] = '2000-01-01T00:00:00.000Z';
+                            return due;
+                        });
+                        return { ...t, rows };
+                    }),
+                };
+            });
+            it('a fork: no consumer reaches the copied event and no executor runs, on dispatch or on drainDue', async () => {
+                const fork = scopeId.parse(ulid());
+                await host.importScope(staff, { tenantId: t1, scopeId: fork, jurisdiction: 'eu', vertical: 'connector-vertical' }, queued);
+                const stub = await host.getScope(alice, t1, fork);
+                await stub.invoke('flow/log'); // an invocation in the copy dispatches
+                await host.drainDue(t1, fork);
+                expect(count('copy-retry')).toBe(1);
+                expect(count('copy-unattempted')).toBe(1);
+                // The consumer never ran on the copied event.
+                expect(await logOf(fork)).toEqual([]);
+                expect(await host.listPlatformRequests(t1, fork)).toEqual([]);
+                // The retry reads settled, saying why, rather than vanishing.
+                const settled = (await host.executorDeadLetters(t1, fork)).find((d) => d.executorId === 'flaky-effector');
+                expect(settled?.error).toMatch(new RegExp(`^not carried: copied from scope ${source}`));
+                // Nor does it ship the source's events to Tier 2 again: the drain's read is empty here,
+                // while the source's own read still holds them.
+                expect(await host.admin.readUndrainedEvents(staff, t1, fork, 200)).toHaveLength(0);
+                expect((await host.admin.readUndrainedEvents(staff, t1, source, 200)).map((e) => e.id)).toContain(step1);
+                // The twin: work the copy creates itself flows as it always did, to Tier 2 included.
+                await stub.invoke('flow/produce');
+                expect((await host.admin.readUndrainedEvents(staff, t1, fork, 200)).map((e) => e.type)).toContain('flow.step1');
+                const own = await logOf(fork);
+                expect(own).toHaveLength(2); // its own step1, and the step2 that consumer emitted
+                expect(own).not.toContain(step1);
+                // Its own executor work reaches dispatch too, and is held there: a fork is inert (#2005).
+                await stub.invoke('connector/request-effect', { tag: 'fork-own' });
+                expect(count('fork-own')).toBe(0);
+                expect(await inertIn(fork)).toEqual([await eventIdOf(fork, 'fork-own')]);
+            });
+            it("the copy's own events still sort above a copied event stamped by a clock that ran ahead", async () => {
+                // A copied event from a source whose clock was ahead: without the loader re-seeding the
+                // copy's id floor from the outbox it brought, the copy's next event would sort below the
+                // mark and be withheld as if it were the source's.
+                const ahead = createUlid()(Date.parse('2099-01-01T00:00:00.000Z'));
+                const withAhead = {
+                    ...queued,
+                    tables: queued.tables.map((t) => {
+                        if (t.name !== '_substrat_outbox')
+                            return t;
+                        const at = (name) => t.columns.indexOf(name);
+                        const template = t.rows.find((r) => r[at('type')] === 'effect.requested');
+                        const future = [...template];
+                        future[at('id')] = ahead;
+                        future[at('entity_id')] = 'copy-ahead';
+                        future[at('payload')] = JSON.stringify({ tag: 'copy-ahead' });
+                        return { ...t, rows: [...t.rows, future] };
+                    }),
+                };
+                const fork = scopeId.parse(ulid());
+                await host.importScope(staff, { tenantId: t1, scopeId: fork, jurisdiction: 'eu', vertical: 'connector-vertical' }, withAhead);
+                await (await host.getScope(alice, t1, fork)).invoke('connector/request-effect', { tag: 'fork-after-ahead' });
+                // The copy's own event reached dispatch (held inert there, #2005); the copied one did not.
+                expect(await inertIn(fork)).toEqual([await eventIdOf(fork, 'fork-after-ahead')]);
+                expect(count('fork-after-ahead')).toBe(0);
+                expect(count('copy-ahead')).toBe(0);
+            });
+            it('a snapshot: the same', async () => {
+                const snap = scopeId.parse(ulid());
+                await host.importScope(staff, { tenantId: t1, scopeId: snap, jurisdiction: 'eu', vertical: 'connector-vertical' }, queued);
+                await host.drainDue(t1, snap);
+                await (await host.getScope(alice, t1, snap)).invoke('flow/log');
+                expect(count('copy-retry')).toBe(1);
+                expect(count('copy-unattempted')).toBe(1);
+                expect(await logOf(snap)).toEqual([]);
+            });
+            /** A scope's export with one executor delivery removed, so that event is owed again. */
+            const owing = async (s, entityId) => {
+                const dump = await host.admin.exportScope(staff, t1, s);
+                const outbox = dump.tables.find((t) => t.name === '_substrat_outbox');
+                const id = outbox.rows.find((r) => r[outbox.columns.indexOf('entity_id')] === entityId)[outbox.columns.indexOf('id')];
+                return {
+                    ...dump,
+                    tables: dump.tables.map((t) => t.name === '_substrat_deliveries' ? { ...t, rows: t.rows.filter((r) => r[t.columns.indexOf('event_id')] !== id) } : t),
+                };
+            };
+            it("a copy of a copy runs neither source's work; the copy's own backup, returned, runs only its own", async () => {
+                const first = scopeId.parse(ulid());
+                await host.importScope(staff, { tenantId: t1, scopeId: first, jurisdiction: 'eu', vertical: 'connector-vertical' }, queued);
+                await (await host.getScope(alice, t1, first)).invoke('connector/request-effect', { tag: 'first-own' });
+                // A copy's own work reaches dispatch and is held inert there (#2005), never effected.
+                const firstOwn = await eventIdOf(first, 'first-own');
+                expect(await inertIn(first)).toEqual([firstOwn]);
+                const firstsBackup = await owing(first, 'first-own');
+                // copy → copy: the second copy's mark is above the first copy's own events too.
+                const second = scopeId.parse(ulid());
+                await host.importScope(staff, { tenantId: t1, scopeId: second, jurisdiction: 'eu', vertical: 'connector-vertical' }, firstsBackup);
+                await (await host.getScope(alice, t1, second)).invoke('flow/log');
+                await host.drainDue(t1, second);
+                expect(count('copy-retry')).toBe(1);
+                expect(count('copy-unattempted')).toBe(1);
+                // The first copy's own event is the second's INHERITED work: it never reaches dispatch.
+                expect(await inertIn(second)).toEqual([]);
+                await (await host.getScope(alice, t1, second)).invoke('connector/request-effect', { tag: 'second-own' });
+                expect(await inertIn(second)).toEqual([await eventIdOf(second, 'second-own')]);
+                // The first copy's backup returned to it: its own owed event runs, and the source's
+                // still do not, because the copy's origin came back with its backup.
+                await host.restoreScope(staff, t1, first, firstsBackup);
+                expect(await inertIn(first)).toEqual([]); // the backup had its delivery row removed
+                await (await host.getScope(alice, t1, first)).invoke('flow/log');
+                await host.drainDue(t1, first);
+                // Owed again and the first copy's own, so it reaches dispatch again: held inert (#2005).
+                expect(await inertIn(first)).toEqual([firstOwn]);
+                expect(count('first-own')).toBe(0);
+                expect(count('copy-retry')).toBe(1);
+                expect(count('copy-unattempted')).toBe(1);
+                expect(await logOf(first)).toEqual([]);
+            });
+            it('a return (the same dump restored into its own scope) runs all of it — from a dump that predates the origin table too', async () => {
+                // A backup taken before `_substrat_copy_origin` existed: the loader builds the table from
+                // the kernel's DDL, as every wake does on an existing scope, and no row means nothing here
+                // was copied.
+                const legacy = { ...queued, tables: queued.tables.filter((t) => t.name !== '_substrat_copy_origin') };
+                expect(legacy.tables.length).toBe(queued.tables.length - 1);
+                await host.restoreScope(staff, t1, source, legacy);
+                expect((await host.admin.listScopeTables(staff, t1, source)).map((t) => t.name)).toContain('_substrat_copy_origin');
+                await (await host.getScope(alice, t1, source)).invoke('flow/log');
+                await host.drainDue(t1, source);
+                expect(count('copy-retry')).toBe(2);
+                expect(count('copy-unattempted')).toBe(2);
+                expect(await logOf(source)).toContain(step1);
+            });
+        });
         /**
          * #1588. Every read of the intent journal returns a LIST, and the row decode behind all
          * three was strict — so ONE row whose JSON would not parse threw out of the map and took
@@ -1568,15 +1815,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             await stub.invoke('test/move', { entityId: 'l1' });
             const flow = await host.admin.lifecycleFlow(staff, t1, s1, {
                 entityType: 'test-lifecycle',
-                lifecycle: {
-                    field: 'state',
-                    initial: 'draft',
-                    states: {
-                        draft: { on: { 'test/move': 'live' } },
-                        live: { on: { 'test/move': 'done' } },
-                        done: { terminal: true },
-                    },
-                },
+                lifecycle: TEST_LIFECYCLE,
                 since,
                 until: new Date(Date.now() + 60_000).toISOString(),
             });
@@ -1586,6 +1825,84 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             expect(flow.observation).toMatchObject({ entities: 1, events: 3, inferred: 1, complete: true });
             expect(flow.totals.finished).toBe(1);
         });
+        describe('lifecycleFlow on both adapters (#1744)', () => {
+            let stub;
+            beforeAll(async () => {
+                stub = await host.getScope(alice, t1, s1);
+            });
+            /** One move, as its own call, returning the instant the outbox stamped on it. */
+            const move = async (entityId, state) => {
+                const invocationId = ulid();
+                await stub.invoke('test/move', { entityId, state }, { invocationId });
+                const { events } = await host.admin.invocationEvents(staff, t1, s1, { invocationId });
+                expect(events).toHaveLength(1);
+                const at = events[0].occurredAt;
+                // The boundaries below are exact instants, so no two moves may share one.
+                while (Date.now() <= Date.parse(at))
+                    await new Promise((r) => setTimeout(r, 2));
+                return at;
+            };
+            const edge = (flow, from, to) => flow.edges.find((e) => e.from === from && e.to === to && e.declared);
+            const state = (flow, name) => flow.states.find((s) => s.state === name);
+            it('counts an event at `since` and not one at `until`: the window is half-open', async () => {
+                const a = await move('w1', 'draft');
+                const b = await move('w1', 'live');
+                const c = await move('w1', 'done');
+                expect(a < b && b < c).toBe(true);
+                const read = (since, until) => host.admin.lifecycleFlow(staff, t1, s1, { entityType: 'test-lifecycle', lifecycle: TEST_LIFECYCLE, since, until });
+                // [b, c): the move AT `since` is in; the move AT `until` is not replayed at all,
+                // so "now" is still `live` — and the declared edge it would have taken reads 0.
+                const mid = await read(b, c);
+                expect(edge(mid, 'draft', 'live').count).toBe(1);
+                expect(edge(mid, 'live', 'done').count).toBe(0);
+                expect(state(mid, 'live').current).toBe(1);
+                // [a, b): history before `since` is replayed, never counted, and `b` is outside.
+                const before = await read(a, b);
+                expect(edge(before, 'draft', 'live').count).toBe(0);
+                expect(state(before, 'draft').current).toBeGreaterThanOrEqual(1);
+                // The twin: one millisecond past `c` and the same move is counted.
+                const after = await read(b, new Date(Date.parse(c) + 1).toISOString());
+                expect(edge(after, 'draft', 'live').count).toBe(1);
+                expect(edge(after, 'live', 'done').count).toBe(1);
+                expect(state(after, 'live').current).toBe(0);
+            });
+            it('lists a move the declaration does not have apart from the declared edges', async () => {
+                const since = await move('u1', 'draft');
+                await move('u1', 'done'); // `test/move` from draft is declared to lead to `live`
+                await move('u2', 'draft');
+                await move('u2', 'limbo'); // a state the declaration does not have at all
+                const flow = await host.admin.lifecycleFlow(staff, t1, s1, {
+                    entityType: 'test-lifecycle',
+                    lifecycle: TEST_LIFECYCLE,
+                    since,
+                    until: new Date(Date.now() + 60_000).toISOString(),
+                });
+                const undeclared = flow.edges.filter((e) => !e.declared);
+                expect(undeclared).toHaveLength(2);
+                expect(undeclared).toEqual(expect.arrayContaining([
+                    expect.objectContaining({ from: 'draft', to: 'done', operation: 'test/move', count: 1, seenLate: false }),
+                    expect.objectContaining({ from: 'draft', to: 'limbo', operation: 'test/move', count: 1, seenLate: false }),
+                ]));
+                // Not folded into the declared edge out of the same state under the same operation.
+                expect(edge(flow, 'draft', 'live').count).toBe(0);
+                expect(state(flow, 'limbo')).toMatchObject({ declared: false, current: 1 });
+            });
+            it("answers only for the tenant's own scope: a mismatched pair is refused, another tenant's scope sees none of it", async () => {
+                const since = await move('i1', 'draft');
+                const window = { entityType: 'test-lifecycle', lifecycle: TEST_LIFECYCLE, since, until: new Date(Date.now() + 60_000).toISOString() };
+                // The positive twin: t1's own pair sees the instance just started.
+                expect((await host.admin.lifecycleFlow(staff, t1, s1, window)).totals.started).toBe(1);
+                // K-3: never another tenant's outbox, and never an empty answer for one either.
+                await expect(host.admin.lifecycleFlow(staff, t2, s1, window)).rejects.toThrow();
+                await expect(host.admin.lifecycleFlow(staff, t1, s2, window)).rejects.toThrow();
+                // t2's own scope answers, from its own outbox — in which t1 emitted nothing.
+                const own = await host.admin.lifecycleFlow(staff, t2, s2, window);
+                expect(own.observation).toMatchObject({ entities: 0, events: 0, complete: true });
+                expect(own.edges.every((e) => e.count === 0)).toBe(true);
+                // K-24: the read is recorded against the actor.
+                expect((await host.admin.accessLog(staff, { tenantId: t1, method: 'lifecycleFlow' })).length).toBeGreaterThan(0);
+            });
+        });
         it('records a refused transition after the rollback, and the replay counts it (#1745)', async () => {
             // The operation throws the platform's conflict, so its transaction rolls back — the
             // refusal is the one write that must survive it, on both adapters.
@@ -1595,11 +1912,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             await expect(stub.invoke('test/refuse', { entityId: 'r1', from: 'done' })).rejects.toThrow(/invalid transition/);
             const flow = await host.admin.lifecycleFlow(staff, t1, s1, {
                 entityType: 'test-lifecycle',
-                lifecycle: {
-                    field: 'state',
-                    initial: 'draft',
-                    states: { draft: { on: { 'test/move': 'live' } }, live: { on: { 'test/move': 'done' } }, done: { terminal: true } },
-                },
+                lifecycle: TEST_LIFECYCLE,
                 since,
                 until: new Date(Date.now() + 60_000).toISOString(),
             });
@@ -1631,6 +1944,11 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                 drainedAt: null,
             });
             expect(rows[0].decodeError).toBeUndefined();
+            expect(rows[0].guard).toBeNull();
+            // A move the lifecycle allows records nothing.
+            const allowed = ulid();
+            await stub.invoke('test/move', { entityId: 'r2-ok', state: 'draft' }, { invocationId: allowed });
+            expect(await host.admin.listRefusals(staff, t1, s1, { invocationId: allowed })).toEqual([]);
             // The row survived the operation's rollback — and the operation itself left nothing
             // behind in the outbox for that call.
             expect((await host.admin.invocationEvents(staff, t1, s1, { invocationId: call })).events).toEqual([]);
@@ -1646,6 +1964,13 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             const logged = await host.admin.accessLog(staff, { tenantId: t1, method: 'listRefusals' });
             expect(logged.length).toBeGreaterThan(0);
             await expect(host.admin.listRefusals(staff, t2, s1)).rejects.toThrow();
+            // A record whose status column holds arbitrary text: the refusal is recorded, with the
+            // state as the marker — the lifecycle never vouched for that text, so it is not kept.
+            const undeclared = ulid();
+            await expect(stub.invoke('test/refuse', { entityId: 'r2-odd', from: 'call ada@example.com' }, { invocationId: undeclared })).rejects.toThrow(/invalid transition/);
+            const [oddRow] = await host.admin.listRefusals(staff, t1, s1, { invocationId: undeclared });
+            expect(oddRow).toMatchObject({ kind: 'transition', fromState: 'undeclared', entityId: 'r2-odd', operation: 'test/move' });
+            expect(JSON.stringify(oddRow)).not.toMatch(/ada@example\.com|call ada/);
         });
         // -- scope data introspection: the §5.4 admin-query RPC --------------------
         //
@@ -2684,9 +3009,12 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                 const dump = await host.admin.exportScope(staff, t1, s1);
                 const copy = scopeId.parse(ulid());
                 await host.importScope(staff, { tenantId: t1, scopeId: copy, jurisdiction: 'eu', vertical: 'connector-vertical' }, dump);
-                // Same tables and row counts as the source (the spine came across too).
-                const src = (await host.admin.listScopeTables(staff, t1, s1))
-                    .map((t) => `${t.name}:${t.rowCount}`)
+                // Same tables and row counts as the source (the spine came across too), but for the one
+                // row every copy adds: where it came from, and the mark (#1686, and #2005: an empty copy
+                // holds it too, which is how a host with no directory knows a copy).
+                const srcTables = await host.admin.listScopeTables(staff, t1, s1);
+                const src = srcTables
+                    .map((t) => (t.name === '_substrat_copy_origin' ? `${t.name}:1` : `${t.name}:${t.rowCount}`))
                     .sort();
                 const dst = (await host.admin.listScopeTables(staff, t1, copy))
                     .map((t) => `${t.name}:${t.rowCount}`)
@@ -4454,6 +4782,37 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             await host.admin.bindScopeVersion(staff, t1, s, v1); // legacy unconditional caller
             expect((await host.admin.getScopeRecord(staff, t1, s)).verticalVersionId).toBe(v1);
         });
+        // #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 () => {
+            const s = scopeId.parse(ulid());
+            await host.provisionScope(staff, { tenantId: t1, scopeId: s, vertical: 'demo' });
+            await host.admin.recordKeptCopyResolution(staff, t1, s, {
+                action: 'restore-forward',
+                script: 'demo-v1',
+                liveScript: 'demo-v2',
+                keptAt: '2026-10-03T12:00:00.000Z',
+                revisionBefore: '41',
+                revisionAfter: '7',
+            });
+            const [row] = await host.admin.auditLog(staff, { action: 'resolveKeptCopy', scopeId: s });
+            expect(row).toMatchObject({
+                actor: staff,
+                action: 'resolveKeptCopy',
+                before: { script: 'demo-v1', keptAt: '2026-10-03T12:00:00.000Z', revision: '41' },
+                after: { action: 'restore-forward', liveScript: 'demo-v2', revision: '7' },
+            });
+            const other = scopeId.parse(ulid());
+            await expect(host.admin.recordKeptCopyResolution(staff, t1, other, {
+                action: 'discard',
+                script: 'demo-v1',
+                liveScript: null,
+                keptAt: '2026-10-03T12:00:00.000Z',
+                revisionBefore: null,
+                revisionAfter: null,
+            })).rejects.toThrow(/unknown scope/);
+            expect(await host.admin.auditLog(staff, { action: 'resolveKeptCopy', scopeId: other })).toEqual([]);
+        });
         it('publishes a version as pending, and refuses to bind it until admitted', async () => {
             const versionId = ulid();
             await host.admin.registerVertical(staff, {
@@ -5636,6 +5995,77 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             const stub = await host.getScope(alice, t1, s1);
             await expect(stub.invoke('guarded/rows')).resolves.toEqual(['go']);
         });
+        it('records a guard refusal once, after the rollback, with no message or input on the row (#1745)', async () => {
+            const stub = await host.getScope(alice, t1, s1);
+            const rowsBefore = await stub.invoke('guarded/rows');
+            const call = ulid();
+            const note = 'call me at ada@example.com';
+            await expect(stub.invoke('guarded/open', { id: 'g-refused', note }, { invocationId: call })).rejects.toThrow(/gate closed/);
+            // The caller's answer is the predicate's own 409, unchanged by being recorded.
+            await expect(stub.invoke('guarded/open', { id: 'g-refused', note })).rejects.toMatchObject({
+                code: 'conflict',
+            });
+            const rows = await host.admin.listRefusals(staff, t1, s1, { invocationId: call });
+            expect(rows).toHaveLength(1);
+            expect(rows[0]).toMatchObject({
+                kind: 'guard',
+                guard: 'gate/must-be-open',
+                reason: 'gate_closed',
+                actor: alice,
+                actorKind: 'principal',
+                tenantId: t1,
+                scopeId: s1,
+                entityType: 'guarded-thing',
+                entityId: 'g-refused',
+                // A guard stands before an operation; the kernel does not know the record's state.
+                fromState: null,
+                attemptedState: null,
+                operation: 'guarded/open',
+                invokedOperation: 'guarded/open',
+                impersonation: null,
+                invocationId: call,
+                drainedAt: null,
+            });
+            expect(rows[0].decodeError).toBeUndefined();
+            // Keys and vocabulary only: neither the input nor the message the caller saw.
+            expect(JSON.stringify(rows[0])).not.toMatch(/ada@example\.com|gate closed|call me/);
+            // Both attempts recorded, each once, and as guards.
+            expect(await host.admin.listRefusals(staff, t1, s1, { kind: 'guard', entityId: 'g-refused' })).toHaveLength(2);
+            expect(await host.admin.listRefusals(staff, t1, s1, { kind: 'transition', entityId: 'g-refused' })).toEqual([]);
+            // The wire takes any non-empty string as a conflict's reason, so a predicate can put
+            // request text there; the row keeps a code or the fixed marker, never the text.
+            const leaked = ulid();
+            await expect(stub.invoke('guarded/open', { id: 'g-leak', reason: 'call ada@example.com' }, { invocationId: leaked })).rejects.toThrow(/gate closed/);
+            const [leakRow] = await host.admin.listRefusals(staff, t1, s1, { invocationId: leaked });
+            expect(leakRow).toMatchObject({ kind: 'guard', reason: 'unrecognized', entityId: 'g-leak' });
+            expect(JSON.stringify(leakRow)).not.toMatch(/ada@example\.com|call ada/);
+            // The same for the record's type, which a predicate names from whatever it was handed:
+            // kept only when spelled as an entity type. The id stays — it is the record's key.
+            const typed = ulid();
+            await expect(stub.invoke('guarded/open', { id: 'g-typed', entityType: 'ada@example.com' }, { invocationId: typed })).rejects.toThrow(/gate closed/);
+            const [typedRow] = await host.admin.listRefusals(staff, t1, s1, { invocationId: typed });
+            expect(typedRow).toMatchObject({ kind: 'guard', entityType: 'undeclared', entityId: 'g-typed' });
+            expect(JSON.stringify(typedRow)).not.toMatch(/ada@example\.com/);
+            // The rollback took the predicate's own write with it, and the handler never ran —
+            // the refusal row is the one write that survived.
+            expect(await stub.invoke('guarded/rows')).toEqual(rowsBefore);
+        });
+        it('records nothing for a guard that passes, or one that throws something other than a refusal (#1745)', async () => {
+            const stub = await host.getScope(alice, t1, s1);
+            const rowsBefore = await stub.invoke('guarded/rows');
+            const passed = ulid();
+            await stub.invoke('guarded/open', { id: 'g-open', open: true }, { invocationId: passed });
+            expect(await host.admin.listRefusals(staff, t1, s1, { invocationId: passed })).toEqual([]);
+            expect(await stub.invoke('guarded/rows')).toEqual([...rowsBefore, 'gate saw g-open', 'opened g-open']);
+            // A bare Error is a guard failing, not a guard refusing: blocked, never recorded.
+            const failed = ulid();
+            await expect(stub.invoke('guarded/act', { flag: 'stop' }, { invocationId: failed })).rejects.toThrow(/expected flag/);
+            expect(await host.admin.listRefusals(staff, t1, s1, { invocationId: failed })).toEqual([]);
+            // And a guard whose predicate is missing fails closed, also unrecorded.
+            const orphan = ulid();
+            await expect(stub.invoke('guarded/orphan', {}, { invocationId: orphan })).rejects.toThrow(/unknown guard predicate/);
+            expect(await host.admin.listRefusals(staff, t1, s1, { invocationId: orphan })).toEqual([]);
+        });
         // -- operation withdrawal (K-17) -----------------------------------------
         it('withdraws a default binding regardless of registration order (K-17)', async () => {
             const stub = await host.getScope(alice, t1, s1);