@substrat-run/contract-tests 0.141.0 → 0.142.0

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

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

package/dist/scope-host-suite.js

@@ -1,7 +1,7 @@
 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 { 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';
 /**
  * Assert a refusal by the CODE it declared, not by the sentence it happens to carry
@@ -4930,6 +4930,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 +5034,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 });
@@ -7664,6 +7738,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.