@substrat-run/contract-tests 0.141.0 → 0.143.0

package/dist/scope-host-suite.js

@@ -1,8 +1,21 @@
 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, SWEEP_RUNS_KIND, SCOPE_TABLE_PAGE_MAX, } from '@substrat-run/contracts';
-import { INERT_SCOPE_REASON, 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, } 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 { billedMod, contractTestBareOps, contractTestInitialModules, gateModManifest, lateMod, TEST_LIFECYCLE, testModManifest, victimModManifest, } from './modules.js';
+import { testOperations } from './test-operations.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
+ * narrowed away — the read a vertical makes is held to the same union, and must narrow too.
+ */
+function whole(entries) {
+    return entries.map((e) => {
+        if (isUndecodablePlatformRequest(e))
+            throw new Error(`unexpected undecodable intent row: ${e.decodeError}`);
+        return e;
+    });
+}
 /**
  * Assert a refusal by the CODE it declared, not by the sentence it happens to carry
  * (#113 phase 5).
@@ -258,7 +271,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
         it('the platform lists pending intents and settles them done (drain surface, Phase B)', async () => {
             const stub = await host.getScope(alice, t1, s1);
             const id = await stub.invoke('platform/request', { kind: 'provision-sibling', payload: { slug: 'padel' } });
-            const pending = await host.listPlatformRequests(t1, s1);
+            const pending = whole(await host.listPlatformRequests(t1, s1));
             const mine = pending.find((r) => r.id === id);
             expect(mine).toBeDefined();
             expect(mine.kind).toBe('provision-sibling');
@@ -266,7 +279,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             expect(mine.payload).toEqual({ slug: 'padel' }); // JSON parsed back to the contract shape
             await host.settlePlatformRequest(t1, s1, mine.id, { status: 'done', result: { scopeId: 'NEWSITE' } });
             // A settled intent drops out of the pending list…
-            expect((await host.listPlatformRequests(t1, s1)).some((r) => r.id === id)).toBe(false);
+            expect((whole(await host.listPlatformRequests(t1, s1))).some((r) => r.id === id)).toBe(false);
             // …and the row now reads done with its handler result recorded.
             const rows = await stub.invoke('platform/read-requests');
             const settled = rows.find((r) => r.id === id);
@@ -297,7 +310,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             // another request. The row stays exactly as it was.
             await expect(host.settlePlatformRequest(t1, s1, platformRequestId.parse(id), { status: 'pending', event: event(id) })).rejects.toThrow();
             await expect(host.settlePlatformRequest(t1, s1, platformRequestId.parse(id), { status: 'done', event: event(ulid()) })).rejects.toThrow();
-            expect((await host.listPlatformRequests(t1, s1)).find((r) => r.id === id)?.attempts).toBe(0);
+            expect((whole(await host.listPlatformRequests(t1, s1))).find((r) => r.id === id)?.attempts).toBe(0);
             expect(await mine()).toEqual([]);
             await host.settlePlatformRequest(t1, s1, platformRequestId.parse(id), { status: 'done', event: event(id) });
             const written = await mine();
@@ -315,10 +328,10 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
         it('a transient failure keeps the intent pending and preserves a two-phase result (retry)', async () => {
             const stub = await host.getScope(alice, t1, s1);
             const id = await stub.invoke('platform/request', { kind: 'provision-sibling', payload: {} });
-            const mine = (await host.listPlatformRequests(t1, s1)).find((r) => r.id === id);
+            const mine = (whole(await host.listPlatformRequests(t1, s1))).find((r) => r.id === id);
             // Two-phase: record a minted id but keep the intent pending (crash-safe pre-write).
             await host.settlePlatformRequest(t1, s1, mine.id, { status: 'pending', result: { scopeId: 'MINTED' } });
-            const still = (await host.listPlatformRequests(t1, s1)).find((r) => r.id === id);
+            const still = (whole(await host.listPlatformRequests(t1, s1))).find((r) => r.id === id);
             expect(still.status).toBe('pending'); // still drainable
             expect(still.result).toEqual({ scopeId: 'MINTED' });
             expect(still.attempts).toBe(1);
@@ -332,15 +345,15 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
         it('reads back settled intents — the journal both the platform and the vertical see (#618)', async () => {
             const stub = await host.getScope(alice, t1, s1);
             const id = await stub.invoke('platform/request', { kind: 'connector:test', payload: { doc: 1 } });
-            const row = (await host.listPlatformRequests(t1, s1)).find((r) => r.id === id);
+            const row = (whole(await host.listPlatformRequests(t1, s1))).find((r) => r.id === id);
             // The failure this issue is about: a provider's own sentence, journaled and then
             // unreachable from anywhere a builder would look.
             const refusal = 'HTTP 409 requires valid personal number field';
             await host.settlePlatformRequest(t1, s1, row.id, { status: 'failed', lastError: refusal });
             // Settled, so it is gone from the DRAIN's read…
-            expect((await host.listPlatformRequests(t1, s1)).some((r) => r.id === id)).toBe(false);
+            expect((whole(await host.listPlatformRequests(t1, s1))).some((r) => r.id === id)).toBe(false);
             // …and present, with the whole error, in the JOURNAL's.
-            const history = await host.listPlatformRequestHistory(t1, s1, { kind: 'connector:test' });
+            const history = whole(await host.listPlatformRequestHistory(t1, s1, { kind: 'connector:test' }));
             const settled = history.find((r) => r.id === id);
             expect(settled.status).toBe('failed');
             expect(settled.lastError).toBe(refusal); // verbatim, never truncated
@@ -348,10 +361,10 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             expect(settled.settledAt).not.toBeNull();
             // `kind` is an exact match, so one provider's traffic reads alone.
             await stub.invoke('platform/request', { kind: 'provision-sibling', payload: {} });
-            expect((await host.listPlatformRequestHistory(t1, s1, { kind: 'connector:test' })).every((r) => r.kind === 'connector:test')).toBe(true);
+            expect((whole(await host.listPlatformRequestHistory(t1, s1, { kind: 'connector:test' }))).every((r) => r.kind === 'connector:test')).toBe(true);
             // …as does `status`, and `limit` bounds the window.
-            expect((await host.listPlatformRequestHistory(t1, s1, { status: 'failed' })).every((r) => r.status === 'failed')).toBe(true);
-            expect((await host.listPlatformRequestHistory(t1, s1, { limit: 1 })).length).toBe(1);
+            expect((whole(await host.listPlatformRequestHistory(t1, s1, { status: 'failed' }))).every((r) => r.status === 'failed')).toBe(true);
+            expect((whole(await host.listPlatformRequestHistory(t1, s1, { limit: 1 }))).length).toBe(1);
         });
         /**
          * #841. `lastError` says WHAT happened; this says WHO refused — and until it existed the
@@ -363,13 +376,13 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
         it('journals WHO refused beside what was refused, and survives the round trip (#841)', async () => {
             const stub = await host.getScope(alice, t1, s1);
             const id = await stub.invoke('platform/request', { kind: 'connector:test', payload: { doc: 9 } });
-            const row = (await host.listPlatformRequests(t1, s1)).find((r) => r.id === id);
+            const row = (whole(await host.listPlatformRequests(t1, s1))).find((r) => r.id === id);
             await host.settlePlatformRequest(t1, s1, row.id, {
                 status: 'failed',
                 lastError: 'permission denied: protocol:read',
                 failure: { origin: 'platform', code: 'permission_denied', permission: 'protocol:read' },
             });
-            const settled = (await host.listPlatformRequestHistory(t1, s1, { kind: 'connector:test' })).find((r) => r.id === id);
+            const settled = (whole(await host.listPlatformRequestHistory(t1, s1, { kind: 'connector:test' }))).find((r) => r.id === id);
             expect(settled.failure).toEqual({
                 origin: 'platform',
                 code: 'permission_denied',
@@ -385,9 +398,9 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
         it('leaves attribution null when the settling caller did not attribute (#841)', async () => {
             const stub = await host.getScope(alice, t1, s1);
             const id = await stub.invoke('platform/request', { kind: 'connector:test', payload: { doc: 10 } });
-            const row = (await host.listPlatformRequests(t1, s1)).find((r) => r.id === id);
+            const row = (whole(await host.listPlatformRequests(t1, s1))).find((r) => r.id === id);
             await host.settlePlatformRequest(t1, s1, row.id, { status: 'failed', lastError: 'something broke' });
-            const settled = (await host.listPlatformRequestHistory(t1, s1, { kind: 'connector:test' })).find((r) => r.id === id);
+            const settled = (whole(await host.listPlatformRequestHistory(t1, s1, { kind: 'connector:test' }))).find((r) => r.id === id);
             expect(settled.lastError).toBe('something broke');
             expect(settled.failure).toBeNull();
         });
@@ -395,9 +408,9 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             const stub = await host.getScope(alice, t1, s1);
             const first = await stub.invoke('platform/request', { kind: 'order-check', payload: { n: 1 } });
             const second = await stub.invoke('platform/request', { kind: 'order-check', payload: { n: 2 } });
-            const rows = await host.listPlatformRequestHistory(t1, s1, { kind: 'order-check' });
+            const rows = whole(await host.listPlatformRequestHistory(t1, s1, { kind: 'order-check' }));
             expect(rows.map((r) => r.id)).toEqual([second, first]);
-            expect((await host.listPlatformRequestHistory(t1, s1, { kind: 'order-check', limit: 1 }))[0].id).toBe(second);
+            expect((whole(await host.listPlatformRequestHistory(t1, s1, { kind: 'order-check', limit: 1 })))[0].id).toBe(second);
         });
         it('a vertical reads the outcome of its OWN intents in scope — ctx.platformRequests (#618)', async () => {
             const stub = await host.getScope(alice, t1, s1);
@@ -425,8 +438,8 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
         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);
+            const pendingAt = async (s) => (whole(await host.listPlatformRequests(t1, s))).map((r) => r.id);
+            const historyAt = async (s) => (whole(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);
@@ -466,7 +479,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             });
             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);
+                const back = (whole(await host.listPlatformRequests(t1, source))).find((r) => r.id === id);
                 expect(back).toMatchObject({ status: 'pending', payload: { slug: 'copied' }, lastError: null, settledAt: null });
             });
         });
@@ -551,7 +564,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                 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([]);
+                expect(whole(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}`));
@@ -735,8 +748,8 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             };
             /** All three reads, so each of the three decode sites is on the hook. */
             const readAll = async (s) => ({
-                pending: await host.listPlatformRequests(t1, s),
-                history: await host.listPlatformRequestHistory(t1, s),
+                pending: whole(await host.listPlatformRequests(t1, s)),
+                history: whole(await host.listPlatformRequestHistory(t1, s)),
                 inScope: await (await host.getScope(alice, t1, s)).invoke('platform/intents'),
             });
             const byId = (rows, id) => rows.find((r) => r.id === id);
@@ -749,6 +762,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                 for (const row of [...pending, ...history, ...inScope]) {
                     // ABSENT rather than null, so a healthy list is the shape it always was.
                     expect(row).not.toHaveProperty('decodeError');
+                    expect(row).not.toHaveProperty('undecodable');
                 }
                 expect(byId(history, healthySettled.id)).toMatchObject({
                     payload: { doc: 2 },
@@ -802,14 +816,120 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                     lastError: refusal,
                     failure: { origin: 'platform', code: 'validation_failed', permission: null },
                 });
-                expect((await host.listPlatformRequests(t1, s)).map((r) => r.id)).toEqual([healthyPending.id]);
-                const after = byId(await host.listPlatformRequestHistory(t1, s), brokenPendingId);
+                expect((whole(await host.listPlatformRequests(t1, s))).map((r) => r.id)).toEqual([healthyPending.id]);
+                const after = byId(whole(await host.listPlatformRequestHistory(t1, s)), brokenPendingId);
                 expect(after.status).toBe('failed');
                 expect(after.lastError).toBe(refusal);
                 expect(after.failure).toEqual({ origin: 'platform', code: 'validation_failed', permission: null });
                 // The stored payload is untouched by the settle, so the row still says it is not whole.
                 expect(after.decodeError).toMatch(/^payload: /);
             });
+            /**
+             * #1637: the columns #1588 could not tolerate — id, kind, status, attempts, requested_at —
+             * have no value the contract accepts that would not be fabricated, so such a row still
+             * threw, and took every read of the journal with it. It now reads as the OTHER half of
+             * the entry: those five columns as stored, as text, and why. One column at a time, each
+             * beside a healthy twin, because a restored dump can only show a column at a time.
+             */
+            describe('a row whose identity does not decode (#1637)', () => {
+                /** The healthy pending row's identity, as the variant names it: stored, as text. */
+                const asStored = {
+                    undecodable: true,
+                    id: brokenPendingId,
+                    kind: 'connector:test',
+                    status: 'pending',
+                    attempts: '0',
+                    requestedAt: at,
+                };
+                /** One broken column each: what is planted, and the field it reads back as — written out. */
+                const broken = [
+                    { column: 'id', over: { id: 'not-a-ulid' }, reads: { id: 'not-a-ulid' } },
+                    { column: 'id', over: { id: null }, reads: { id: null } },
+                    // Oversized: read back capped, the way the decoder caps any value it quotes, so it cannot
+                    // ride whole into the drain's report, the sweep log on every tick, or the dashboard card.
+                    { column: 'id', over: { id: 'x'.repeat(5000) }, reads: { id: `${'x'.repeat(200)}…` } },
+                    { column: 'kind', over: { kind: '' }, reads: { kind: '' } },
+                    { column: 'status', over: { status: 'queued' }, reads: { status: 'queued' } },
+                    { column: 'attempts', over: { attempts: -1 }, reads: { attempts: '-1' } },
+                    { column: 'attempts', over: { attempts: 'abc' }, reads: { attempts: 'abc' } },
+                    // An epoch, the shape a dump from another world would carry — as text, since a restore
+                    // binds a JSON number as REAL and TEXT affinity would store it as `1756684800.0`.
+                    { column: 'requested_at', over: { requested_at: '1756684800' }, reads: { requestedAt: '1756684800' } },
+                ];
+                /** The raw reads — no `whole`, since meeting the variant is the point. */
+                const readEntries = async (s) => ({
+                    pending: await host.listPlatformRequests(t1, s),
+                    history: await host.listPlatformRequestHistory(t1, s),
+                    inScope: await (await host.getScope(alice, t1, s)).invoke('platform/intents'),
+                });
+                for (const { column, over, reads } of broken) {
+                    it(`${column} = ${JSON.stringify(over[column])}: named as stored, beside the row that is whole`, async () => {
+                        const clean = await readAll(await restoredWith([healthyPending]));
+                        const row = { ...healthyPending, id: brokenPendingId, ...over };
+                        const { pending, history, inScope } = await readEntries(await restoredWith([row, healthyPending]));
+                        const expected = {
+                            ...asStored,
+                            ...reads,
+                            decodeError: expect.stringMatching(new RegExp(`^${column}: `)),
+                        };
+                        // A stored `queued` is not pending, so the drain's queue never meets that one.
+                        const queued = column === 'status' ? [] : [expected];
+                        for (const [read, entries, twin, also] of [
+                            ['pending', pending, clean.pending, queued],
+                            ['history', history, clean.history, [expected]],
+                            ['in-scope', inScope, clean.inScope, [expected]],
+                        ]) {
+                            expect(entries, read).toHaveLength(1 + also.length);
+                            // The healthy row reads EXACTLY as it does with no bad neighbour.
+                            const healthy = entries.filter((e) => !isUndecodablePlatformRequest(e));
+                            expect(healthy, read).toEqual(twin);
+                            expect(entries.filter(isUndecodablePlatformRequest), read).toEqual(also);
+                            // Every entry satisfies the published union — the variant claims no branded type.
+                            for (const e of entries)
+                                expect(() => platformRequestEntry.parse(e), read).not.toThrow();
+                        }
+                    });
+                }
+                it('several broken columns at once are all named, and the JSON beside them too', async () => {
+                    const row = { ...healthyPending, id: 'not-a-ulid', status: 'queued', payload: 'nope' };
+                    const { history } = await readEntries(await restoredWith([row, healthyPending]));
+                    const variant = history.find(isUndecodablePlatformRequest);
+                    expect(variant.decodeError.split('; ').map((part) => part.split(':')[0])).toEqual(['id', 'status', 'payload']);
+                    // Named, never quoted: the payload's stored text does not travel in the reason.
+                    expect(variant.decodeError).not.toContain('nope');
+                });
+                it('a clean journal carries no variant marker at all (the positive twin)', async () => {
+                    const { pending, history, inScope } = await readEntries(await restoredWith([healthyPending, healthySettled]));
+                    for (const e of [...pending, ...history, ...inScope]) {
+                        expect(e).not.toHaveProperty('undecodable');
+                        expect(isUndecodablePlatformRequest(e)).toBe(false);
+                    }
+                });
+                it('a variant whose stored id is still an id can be refused: settled, out of the queue, still named', async () => {
+                    // The drain's case (a) — tested there against a fake; what BOTH adapters owe it is that
+                    // the settle lands on a row the read could not decode.
+                    const s = await restoredWith([{ ...healthyPending, id: brokenPendingId, kind: '' }, healthyPending]);
+                    const refusal = 'not executed: the intent row could not be decoded (kind: …)';
+                    await host.settlePlatformRequest(t1, s, brokenPendingId, {
+                        status: 'failed',
+                        lastError: refusal,
+                        failure: { origin: 'platform', code: 'validation_failed', permission: null },
+                    });
+                    const { pending, history } = await readEntries(s);
+                    expect(pending.map((e) => e.id)).toEqual([healthyPending.id]);
+                    // Settled — and the settle's `attempts + 1` left a number where text was — but the kind
+                    // is still not a kind, so the row is still the variant, and says so.
+                    expect(history.find(isUndecodablePlatformRequest)).toEqual({
+                        undecodable: true,
+                        id: brokenPendingId,
+                        kind: '',
+                        status: 'failed',
+                        attempts: '1',
+                        requestedAt: healthyPending.requested_at,
+                        decodeError: expect.stringMatching(/^kind: /),
+                    });
+                });
+            });
         });
         /**
          * #1636 — #1588's shape everywhere else it lived. One outbox or denial row whose JSON
@@ -2467,7 +2587,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                     });
                     return id;
                 };
-                const journal = async (kind) => host.listPlatformRequestHistory(t1, s1, { kind });
+                const journal = async (kind) => whole(await host.listPlatformRequestHistory(t1, s1, { kind }));
                 it('redacts the routed copy of the event, and leaves the neighbour intact', async () => {
                     // A distinct kind per test: this scope's journal is shared with every other
                     // suite that enqueues, and `connector:<provider>` IS a family of kinds.
@@ -2522,7 +2642,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                     const kind = `connector:erasure-${ulid()}`;
                     const erased = dataSubjectId.parse(ulid());
                     const id = await routeIntent(kind, erased, 'Anna Ek');
-                    expect((await host.listPlatformRequests(t1, s1)).some((r) => r.id === id)).toBe(true);
+                    expect((whole(await host.listPlatformRequests(t1, s1))).some((r) => r.id === id)).toBe(true);
                     await host.admin.shredSubject(staff, t1, s1, erased);
                     // Redacting and leaving it pending would hand the drain a tombstone to execute;
                     // leaving it pending and intact would keep the name. `failed` is the truthful
@@ -2531,7 +2651,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                     expect(settled.status).toBe('failed');
                     expect(settled.settledAt).not.toBeNull();
                     expect(settled.lastError).toContain('subject erasure');
-                    const stillPending = await host.listPlatformRequests(t1, s1);
+                    const stillPending = whole(await host.listPlatformRequests(t1, s1));
                     expect(stillPending.some((r) => r.id === id)).toBe(false);
                 });
                 it('redacts what the provider said back, not only what we sent', async () => {
@@ -3041,7 +3161,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                         });
                         await host.settlePlatformRequest(t1, s1, template, { status: 'done' });
                         const queued = async () => {
-                            const rows = await host.listPlatformRequestHistory(t1, s, { kind: SWEEP_RUNS_KIND });
+                            const rows = whole(await host.listPlatformRequestHistory(t1, s, { kind: SWEEP_RUNS_KIND }));
                             return { mine: rows.find((r) => r.id === ids.mine), theirs: rows.find((r) => r.id === ids.theirs) };
                         };
                         const before = await queued();
@@ -4930,6 +5050,48 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             }
             expect(beforeClaim.map((copy) => copy.moveId).sort()).toEqual([first, next].sort());
         });
+        it('a backfilled copy is retained, once per script, never over a ledgered one, and never under a reap claim (#1722)', async () => {
+            const s = scopeId.parse(ulid());
+            await host.provisionScope(staff, { tenantId: t1, scopeId: s });
+            const [historic, tracked] = [`version-${ulid().toLowerCase()}`, `version-${ulid().toLowerCase()}`];
+            const from = ulid();
+            expect(await host.admin.backfillScopeScriptCopy(staff, t1, s, historic, { fromLogId: from })).toBe('recorded');
+            expect(await host.admin.backfillScopeScriptCopy(staff, t1, s, historic)).toBe('ledgered'); // a re-run writes nothing
+            // Audited once, naming the script and the log row it was read from.
+            expect((await host.admin.auditLog(staff, { scopeId: s, action: 'backfillScopeCopy' })).map((r) => r.after))
+                .toEqual([{ scriptRef: historic, fromLogId: from }]);
+            const [entry] = await host.admin.listScopeScriptCopies(staff, { tenantId: t1, scopeId: s });
+            expect(entry).toMatchObject({ scriptRef: historic, moveId: BACKFILL_MOVE_ID, state: 'retained', role: null, leaseUntil: null });
+            // Never pending, so no lease sweep ever claims it, and a reap is not held off by it.
+            expect((await host.admin.claimExpiredScopeScriptCopies(staff, {
+                now: new Date(Date.now() + 365 * 86_400_000).toISOString(), leaseUntil: new Date().toISOString(), owner: 'sweep:test', limit: 1000,
+            })).filter((c) => c.scopeId === s)).toEqual([]);
+            // A script the ledger already names for this scope, in ANY state, is not backfilled again.
+            const move = ulid();
+            await host.admin.recordScopeScriptCopy(staff, t1, s, tracked, move, { role: 'source' });
+            await host.admin.settleScopeScriptCopy(staff, t1, s, tracked, move, 'done');
+            expect(await host.admin.backfillScopeScriptCopy(staff, t1, s, tracked)).toBe('ledgered');
+            expect((await host.admin.listScopeScriptCopies(staff, { tenantId: t1, scopeId: s })).map((c) => c.moveId).sort())
+                .toEqual([BACKFILL_MOVE_ID, move].sort());
+            // A move that later carries the store out of the historic script takes it over: while its
+            // own entry is live the backfilled one stays, and once that entry is done (wiped, or the
+            // route) the backfilled one settles with it, so no reap or erasure is sent there again.
+            const carry = ulid();
+            await host.admin.recordScopeScriptCopy(staff, t1, s, historic, carry, { role: 'source' });
+            await host.admin.settleScopeScriptCopy(staff, t1, s, historic, carry, 'eligible', { loadStamp: 'st', revision: '1' });
+            expect((await host.admin.listScopeScriptCopies(staff, { tenantId: t1, scopeId: s, state: 'retained' })).map((c) => c.scriptRef))
+                .toEqual([historic]);
+            await host.admin.settleScopeScriptCopy(staff, t1, s, historic, carry, 'done');
+            expect(await host.admin.listScopeScriptCopies(staff, { tenantId: t1, scopeId: s, state: 'retained' })).toEqual([]);
+            // Scoped by tenant: the same scope id under another tenant is unknown.
+            expect(await host.admin.backfillScopeScriptCopy(staff, t2, s, `version-${ulid().toLowerCase()}`)).toBe('missing');
+            expect(await host.admin.backfillScopeScriptCopy(staff, t1, scopeId.parse(ulid()), historic)).toBe('missing');
+            // Under a reap claim nothing new enters the ledger, so the reap's own listing stays whole.
+            await host.admin.beginScopeScriptReap(staff, t1, s);
+            const late = `version-${ulid().toLowerCase()}`;
+            expect(await host.admin.backfillScopeScriptCopy(staff, t1, s, late)).toBe('reaping');
+            expect((await host.admin.listScopeScriptCopies(staff, { tenantId: t1, scopeId: s })).some((c) => c.scriptRef === late)).toBe(false);
+        });
         it('a pending copy entry is claimed only once its lease ran out, and only once (#1722)', async () => {
             const s = scopeId.parse(ulid());
             await host.provisionScope(staff, { tenantId: t1, scopeId: s });
@@ -4992,6 +5154,38 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             // And it confirms once: the same confirmation again refuses.
             await expectRefusal(host.admin.setScopeServingRef(staff, t1, s, from, { expectedErasureEpoch: 0, confirmMove: { moveId: move, source: 'eligible' } }), 'precondition_failed');
         });
+        it('a backfill and every erasure record the erasure epoch they ran under (#1722)', async () => {
+            const s = scopeId.parse(ulid());
+            await host.provisionScope(staff, { tenantId: t1, scopeId: s });
+            const epochs = async (action) => (await host.admin.auditLog(staff, { scopeId: s, action })).map((r) => r.before);
+            expect(await host.admin.backfillScopeScriptCopy(staff, t1, s, `version-${ulid().toLowerCase()}`)).toBe('recorded');
+            const redacted = [{ events: 0, intents: 0, jobRuns: 0, idempotencyResults: 0, intentIds: [],
+                    vertical: { verticalRows: [], hookRows: [], unreachedEntities: [] } }];
+            await host.admin.finalizeSubjectShred(staff, t1, s, ulid(), redacted, { versionId: null, servingRef: null, epoch: 0, copyCount: 1 });
+            expect(await host.admin.backfillScopeScriptCopy(staff, t1, s, `version-${ulid().toLowerCase()}`)).toBe('recorded');
+            expect(await epochs('backfillScopeCopy')).toEqual([{ erasureEpoch: 0 }, { erasureEpoch: 1 }]);
+            expect(await epochs('shredSubject')).toEqual([{ erasureEpoch: 0, path: 'orchestrated' }]);
+            // A direct shred claims nothing, and says so, with the epoch it ran under.
+            await host.admin.shredSubject(staff, t1, s, ulid());
+            expect(await epochs('shredSubject')).toEqual([{ erasureEpoch: 0, path: 'orchestrated' }, { erasureEpoch: 1, path: 'direct' }]);
+        });
+        it('a move that routes onto a backfilled script settles that entry in the confirming write (#1722)', async () => {
+            const s = scopeId.parse(ulid());
+            await host.provisionScope(staff, { tenantId: t1, scopeId: s });
+            const [from, to, other] = [`version-${ulid().toLowerCase()}`, `version-${ulid().toLowerCase()}`, `version-${ulid().toLowerCase()}`];
+            expect(await host.admin.backfillScopeScriptCopy(staff, t1, s, to)).toBe('recorded');
+            expect(await host.admin.backfillScopeScriptCopy(staff, t1, s, other)).toBe('recorded');
+            const move = ulid();
+            await host.admin.recordScopeScriptCopy(staff, t1, s, from, move, { role: 'source' });
+            await host.admin.recordScopeScriptCopy(staff, t1, s, to, move, { role: 'destination', loadStamp: 'restore-stamp' });
+            // Until it confirms, the move's own entry is pending: the backfilled one still stands.
+            expect((await host.admin.listScopeScriptCopies(staff, { tenantId: t1, scopeId: s, state: 'retained' })).map((c) => c.scriptRef).sort())
+                .toEqual([other, to].sort());
+            await host.admin.setScopeServingRef(staff, t1, s, to, { expectedErasureEpoch: 0, confirmMove: { moveId: move, source: 'retained' } });
+            const byRef = Object.fromEntries((await host.admin.listScopeScriptCopies(staff, { tenantId: t1, scopeId: s }))
+                .filter((c) => c.moveId === BACKFILL_MOVE_ID).map((c) => [c.scriptRef, c.state]));
+            expect(byRef).toEqual({ [to]: 'done', [other]: 'retained' });
+        });
         it('a reap claim refuses a conditional bind until the scope row is deleted (#1722)', async () => {
             const s = scopeId.parse(ulid());
             await host.provisionScope(staff, { tenantId: t1, scopeId: s });
@@ -6346,7 +6540,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                     permissions: [{ key: 'selfw:use', description: 'self' }],
                     withdraws: ['selfw/op'],
                 }),
-                operations: { 'selfw/op': (() => 'x') },
+                ...testOperations({ 'selfw/op': (() => 'x') }),
             })).toThrow(/withdraws its own operation/);
         });
         it('links declared entity relations, idempotently (K-16)', async () => {
@@ -7664,6 +7858,265 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             await host.admin.revokeEntitlement(staff, mt, 'billed');
             await host.admin.revokeEntitlement(staff, mt, 'aux-sku');
         });
+        // -- the stored storage gauge (#1524) --------------------------------------
+        describe('the stored storage gauge (#1524)', () => {
+            const day = (offsetDays, time) => `${new Date(Date.now() + offsetDays * 86_400_000).toISOString().slice(0, 10)}T${time}.000Z`;
+            const newScope = async (tenant) => {
+                const s = scopeId.parse(ulid());
+                await host.provisionScope(staff, { tenantId: tenant, scopeId: s });
+                await host.admin.activateScope(staff, tenant, s);
+                return s;
+            };
+            const record = (tenant, scope, bytes, readAt) => host.admin.recordScopeStorage(staff, [{ tenantId: tenant, scopeId: scope, bytes, readAt }]);
+            it('keeps one row per scope per UTC day: a same-day reading replaces an older one, the next day adds a row', async () => {
+                const tg = tenantId.parse(ulid());
+                await host.admin.createTenant(staff, { id: tg, slug: 'gauge-days', name: 'Gauge Days' });
+                const s = await newScope(tg);
+                expect(await record(tg, s, 100, day(-1, '10:00:00'))).toEqual({ recorded: 1 });
+                expect(await record(tg, s, 200, day(-1, '11:00:00'))).toEqual({ recorded: 1 });
+                // An OLDER reading arriving late never overwrites a newer one of the same day.
+                expect(await record(tg, s, 50, day(-1, '09:00:00'))).toEqual({ recorded: 0 });
+                expect(await record(tg, s, 300, day(0, '00:00:00'))).toEqual({ recorded: 1 });
+                const history = await host.admin.listScopeStorage(staff, { scopeId: s });
+                expect(history.map((r) => [r.day, r.bytes])).toEqual([
+                    [day(-1, '00:00:00').slice(0, 10), 200],
+                    [day(0, '00:00:00').slice(0, 10), 300],
+                ]);
+                expect(await host.admin.listScopeStorage(staff, { scopeId: s, latest: true })).toEqual([
+                    { tenantId: tg, scopeId: s, day: day(0, '00:00:00').slice(0, 10), bytes: 300, readAt: day(0, '00:00:00') },
+                ]);
+                // History is bounded and windowed by day.
+                expect(await host.admin.listScopeStorage(staff, { scopeId: s, limit: 1 })).toHaveLength(1);
+                expect((await host.admin.listScopeStorage(staff, { scopeId: s, since: day(0, '00:00:00').slice(0, 10) })).map((r) => r.bytes)).toEqual([300]);
+                // K-24: the read is attributable.
+                const reads = await host.admin.accessLog(staff, { method: 'listScopeStorage' });
+                expect(reads.some((r) => r.scopeId === s)).toBe(true);
+            });
+            it('records every attempt; a failed one keeps the last sample, and the attempt is what the pass reads next', async () => {
+                const tf = tenantId.parse(ulid());
+                await host.admin.createTenant(staff, { id: tf, slug: 'gauge-tries', name: 'Gauge Tries' });
+                const [s, declined] = [await newScope(tf), await newScope(tf)];
+                await record(tf, s, 700, day(-1, '05:00:00'));
+                expect(await host.admin.recordScopeStorage(staff, [
+                    { tenantId: tf, scopeId: s, bytes: null, error: 'vertical answered 501', readAt: day(0, '05:00:00') },
+                    { tenantId: tf, scopeId: declined, bytes: null, readAt: day(0, '05:00:00') },
+                    // Under the wrong tenant: no attempt row either.
+                    { tenantId: tenantId.parse(ulid()), scopeId: s, bytes: null, error: 'x', readAt: day(0, '06:00:00') },
+                ])).toEqual({ recorded: 0 });
+                // The last good sample stands.
+                expect((await host.admin.listScopeStorage(staff, { scopeId: s, latest: true })).map((r) => r.bytes)).toEqual([700]);
+                const attempts = (await host.admin.listScopeStorageAttempts(staff)).filter((a) => a.tenantId === tf);
+                expect(attempts.map((a) => [a.scopeId, a.attemptedAt, a.error]).sort()).toEqual([
+                    [s, day(0, '05:00:00'), 'vertical answered 501'],
+                    [declined, day(0, '05:00:00'), null],
+                ].sort());
+                // /meters names the failing scope rather than letting it go missing; its last good
+                // reading is still in the sum. A declined scope is not failing.
+                expect((await host.admin.readMeters(staff, { tenantId: tf })).perTenant[0].storage).toMatchObject({
+                    bytes: 700,
+                    sampled: 1,
+                    total: 2,
+                    failing: 1,
+                    lastFailedAt: day(0, '05:00:00'),
+                });
+                // A successful read clears the error and moves the attempt on.
+                await record(tf, s, 900, day(0, '07:00:00'));
+                expect((await host.admin.readMeters(staff, { tenantId: tf })).perTenant[0].storage).toMatchObject({
+                    bytes: 900,
+                    failing: 0,
+                    lastFailedAt: null,
+                });
+                expect((await host.admin.listScopeStorageAttempts(staff)).find((a) => a.scopeId === s)).toMatchObject({
+                    attemptedAt: day(0, '07:00:00'),
+                    error: null,
+                });
+            });
+            it("writes a reading only under the scope's own tenant, and folds each tenant's figure from its own scopes", async () => {
+                const [ta, tb] = [tenantId.parse(ulid()), tenantId.parse(ulid())];
+                await host.admin.createTenant(staff, { id: ta, slug: 'gauge-a', name: 'Gauge A' });
+                await host.admin.createTenant(staff, { id: tb, slug: 'gauge-b', name: 'Gauge B' });
+                const [a1, a2, b1] = [await newScope(ta), await newScope(ta), await newScope(tb)];
+                // Named under the wrong tenant: refused by the directory, not merely filtered on read.
+                expect(await record(tb, a1, 1_000_000, day(0, '01:00:00'))).toEqual({ recorded: 0 });
+                expect(await host.admin.listScopeStorage(staff, { tenantId: tb })).toEqual([]);
+                await host.admin.recordScopeStorage(staff, [
+                    { tenantId: ta, scopeId: a1, bytes: 4096, readAt: day(-1, '06:00:00') },
+                    { tenantId: ta, scopeId: a2, bytes: 8192, readAt: day(0, '06:00:00') },
+                    { tenantId: tb, scopeId: b1, bytes: 10, readAt: day(0, '07:00:00') },
+                ]);
+                const a = await host.admin.readMeters(staff, { tenantId: ta });
+                expect(a.perTenant[0].storage).toEqual({
+                    basis: 'scope-databases',
+                    excluded: ['attachments', 'tenant-stores', 'lake'],
+                    bytes: 4096 + 8192,
+                    sampled: 2,
+                    total: 2,
+                    oldestReadAt: day(-1, '06:00:00'),
+                    newestReadAt: day(0, '06:00:00'),
+                    failing: 0,
+                    lastFailedAt: null,
+                });
+                expect(a.storage).toEqual(a.perTenant[0].storage);
+                const b = await host.admin.readMeters(staff, { tenantId: tb });
+                expect(b.perTenant[0].storage).toMatchObject({ bytes: 10, sampled: 1, total: 1 });
+                // A new scope with no reading yet: the figure says so rather than calling itself whole.
+                await newScope(tb);
+                expect((await host.admin.readMeters(staff, { tenantId: tb })).perTenant[0].storage).toMatchObject({
+                    bytes: 10,
+                    sampled: 1,
+                    total: 2,
+                });
+                // The fleet figure is the per-tenant figures summed.
+                const fleet = await host.admin.readMeters(staff);
+                expect(fleet.storage.bytes).toBe(fleet.perTenant.reduce((n, r) => n + (r.storage?.bytes ?? 0), 0));
+                expect(fleet.storage.sampled).toBe(fleet.perTenant.reduce((n, r) => n + (r.storage?.sampled ?? 0), 0));
+            });
+            it("forgets a reaped scope's samples, and never writes one for it again", async () => {
+                const tr = tenantId.parse(ulid());
+                await host.admin.createTenant(staff, { id: tr, slug: 'gauge-reap', name: 'Gauge Reap' });
+                const [kept, reaped] = [await newScope(tr), await newScope(tr)];
+                await record(tr, kept, 1, day(0, '02:00:00'));
+                await record(tr, reaped, 2, day(-1, '02:00:00'));
+                await record(tr, reaped, 3, day(0, '02:00:00'));
+                // A sample past retention, so the prune below (which reads the raw table, with no join
+                // to scope status) can tell whether reap deleted the rows or only the join hides them.
+                while ((await host.admin.pruneScopeStorage(staff, 500)) > 0)
+                    ;
+                const old = new Date();
+                old.setUTCMonth(old.getUTCMonth() - 14);
+                expect(await record(tr, reaped, 5, old.toISOString())).toEqual({ recorded: 1 });
+                await host.admin.archiveScope(staff, tr, reaped);
+                await host.admin.reapScope(staff, tr, reaped);
+                expect(await host.admin.pruneScopeStorage(staff, 500)).toBe(0);
+                expect((await host.admin.listScopeStorage(staff, { tenantId: tr })).map((r) => r.scopeId)).toEqual([kept]);
+                expect(await record(tr, reaped, 4, day(0, '03:00:00'))).toEqual({ recorded: 0 });
+                expect((await host.admin.readMeters(staff, { tenantId: tr })).perTenant[0].storage).toMatchObject({
+                    bytes: 1,
+                    sampled: 1,
+                    total: 1, // the tombstone is not in the denominator
+                });
+            });
+            it('keeps an archived scope in the figure and refreshes it, so the tenant is not stuck stale', async () => {
+                const ta = tenantId.parse(ulid());
+                await host.admin.createTenant(staff, { id: ta, slug: 'gauge-archived', name: 'Gauge Archived' });
+                const s = await newScope(ta);
+                const threeDaysAgo = new Date(Date.now() - 3 * 86_400_000).toISOString();
+                await record(ta, s, 4096, threeDaysAgo);
+                await host.admin.archiveScope(staff, ta, s);
+                // Archived storage is still storage until reap: counted, and stale until re-read.
+                expect((await host.admin.readMeters(staff, { tenantId: ta })).perTenant[0].storage).toMatchObject({
+                    sampled: 1,
+                    total: 1,
+                    oldestReadAt: threeDaysAgo,
+                });
+                // No drain reaches an archived scope; the storage phase reads it anyway, once a day.
+                const before = new Date().toISOString();
+                const report = await runPlatformSweep(host, {
+                    actor: staff,
+                    fetch: connectorTestFetch,
+                    sweepers: {},
+                    drainRetries: false,
+                    storageGauge: { read: (scope) => host.admin.scopeDatabaseSize(staff, scope.tenantId, scope.id), batch: 10_000 },
+                });
+                expect(report.errors.filter((e) => e.kind === 'storage' && e.id === s)).toEqual([]);
+                const after = (await host.admin.readMeters(staff, { tenantId: ta })).perTenant[0].storage;
+                expect(after).toMatchObject({ sampled: 1, total: 1, failing: 0 });
+                expect(after.oldestReadAt >= before).toBe(true);
+                expect(after.bytes).toBeGreaterThan(0);
+            });
+            it('leaves a provisioning scope, which has no store yet, out of the figure entirely', async () => {
+                const tp = tenantId.parse(ulid());
+                await host.admin.createTenant(staff, { id: tp, slug: 'gauge-provisioning', name: 'Gauge Provisioning' });
+                const s = await newScope(tp);
+                const pending = scopeId.parse(ulid());
+                await host.provisionScope(staff, { tenantId: tp, scopeId: pending }); // not activated
+                expect((await host.admin.getScopeRecord(staff, tp, pending)).status).toBe('provisioning');
+                await record(tp, s, 10, day(0, '08:00:00'));
+                // A reading for it is refused too, so it can never enter the sum.
+                expect(await record(tp, pending, 99, day(0, '08:00:00'))).toEqual({ recorded: 0 });
+                expect((await host.admin.readMeters(staff, { tenantId: tp })).perTenant[0].storage).toMatchObject({
+                    bytes: 10,
+                    sampled: 1,
+                    total: 1, // not "1 of 2": the tenant's figure is whole
+                });
+            });
+            it('neither counts nor accepts a reading for a scope archived before it held data; one archived from active still counts', async () => {
+                const tv = tenantId.parse(ulid());
+                await host.admin.createTenant(staff, { id: tv, slug: 'gauge-abandoned', name: 'Gauge Abandoned' });
+                const kept = await newScope(tv);
+                await record(tv, kept, 50, day(0, '09:00:00'));
+                // A failed provision is archived straight from `provisioning` (it never held data).
+                const abandoned = scopeId.parse(ulid());
+                await host.provisionScope(staff, { tenantId: tv, scopeId: abandoned });
+                await host.admin.archiveScope(staff, tv, abandoned);
+                expect((await host.admin.getScopeRecord(staff, tv, abandoned)).archivedFromStatus).toBe('provisioning');
+                // An app deleted after it served is archived from `active`.
+                const deleted = await newScope(tv);
+                await record(tv, deleted, 70, day(-2, '09:00:00')); // due again by the time the pass runs
+                await host.admin.archiveScope(staff, tv, deleted);
+                expect((await host.admin.getScopeRecord(staff, tv, deleted)).archivedFromStatus).toBe('active');
+                expect(await record(tv, abandoned, 99, day(0, '10:00:00'))).toEqual({ recorded: 0 });
+                expect((await host.admin.readMeters(staff, { tenantId: tv })).perTenant[0].storage).toMatchObject({
+                    bytes: 120,
+                    sampled: 2,
+                    total: 2, // kept + deleted; never the abandoned one
+                });
+                // The storage phase never wakes it.
+                const asked = [];
+                await runPlatformSweep(host, {
+                    actor: staff,
+                    fetch: connectorTestFetch,
+                    sweepers: {},
+                    drainRetries: false,
+                    storageGauge: {
+                        read: async (scope) => {
+                            asked.push(scope.id);
+                            return host.admin.scopeDatabaseSize(staff, scope.tenantId, scope.id);
+                        },
+                        batch: 10_000,
+                    },
+                });
+                expect(asked).not.toContain(abandoned);
+                expect(asked).toContain(deleted);
+                // Unarchiving clears it, as it clears archivedAt.
+                await host.admin.unarchiveScope(staff, tv, deleted);
+                expect((await host.admin.getScopeRecord(staff, tv, deleted)).archivedFromStatus ?? null).toBeNull();
+            });
+            it("deletes a fork's samples when the fork is deleted", async () => {
+                const tk = tenantId.parse(ulid());
+                await host.admin.createTenant(staff, { id: tk, slug: 'gauge-fork', name: 'Gauge Fork' });
+                const source = await newScope(tk);
+                const fork = await host.snapshotScope(staff, tk, source);
+                // A sample past retention: the prune reads the raw table, with no join to the scope
+                // row, so it sees a leftover that every other read would hide once the row is gone.
+                while ((await host.admin.pruneScopeStorage(staff, 500)) > 0)
+                    ;
+                const old = new Date();
+                old.setUTCMonth(old.getUTCMonth() - 14);
+                expect(await record(tk, fork, 9, old.toISOString())).toEqual({ recorded: 1 });
+                await host.deleteSnapshot(staff, tk, fork);
+                expect(await host.admin.pruneScopeStorage(staff, 500)).toBe(0);
+            });
+            it('prunes samples older than thirteen months, at most the limit per call', async () => {
+                const tp = tenantId.parse(ulid());
+                await host.admin.createTenant(staff, { id: tp, slug: 'gauge-prune', name: 'Gauge Prune' });
+                const s = await newScope(tp);
+                const monthsAgo = (m) => {
+                    const d = new Date();
+                    d.setUTCMonth(d.getUTCMonth() - m);
+                    return d.toISOString();
+                };
+                for (const m of [14, 15, 16])
+                    await record(tp, s, m, monthsAgo(m));
+                await record(tp, s, 12, monthsAgo(12)); // inside retention: kept
+                await record(tp, s, 0, day(0, '04:00:00'));
+                expect(await host.admin.pruneScopeStorage(staff, 2)).toBe(2);
+                expect(await host.admin.pruneScopeStorage(staff, 2)).toBe(1);
+                expect(await host.admin.pruneScopeStorage(staff, 2)).toBe(0);
+                expect((await host.admin.listScopeStorage(staff, { scopeId: s })).map((r) => r.bytes)).toEqual([12, 0]);
+                await expect(host.admin.pruneScopeStorage(staff, -1)).rejects.toThrow(/limit/);
+            });
+        });
         it('leaves bare (module-less) operations ungated', async () => {
             // test/read-counter was registered via defineOperation, no manifest — it
             // must resolve regardless of entitlements.