@substrat-run/contract-tests 0.134.0 → 0.136.0

package/dist/async-log-suite.d.ts

@@ -0,0 +1,10 @@
+import { type InvocationLogLine, type ModuleLogLine } from '@substrat-run/kernel';
+import type { ScopeHostFixture } from './scope-host-suite.js';
+export type AsyncLogFixture = ScopeHostFixture & {
+    /** Every invocation line written so far, in order. */
+    lines: () => InvocationLogLine[];
+    /** Every `ctx.log` line written so far, in order. */
+    logs: () => ModuleLogLine[];
+};
+export declare function asyncLogContractSuite(adapterName: string, makeFixture: () => Promise<AsyncLogFixture>): void;
+//# sourceMappingURL=async-log-suite.d.ts.map

package/dist/async-log-suite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-log-suite.d.ts","sourceRoot":"","sources":["../src/async-log-suite.ts"],"names":[],"mappings":"AAWA,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAEnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAM9D,MAAM,MAAM,eAAe,GAAG,gBAAgB,GAAG;IAC/C,sDAAsD;IACtD,KAAK,EAAE,MAAM,iBAAiB,EAAE,CAAC;IACjC,qDAAqD;IACrD,IAAI,EAAE,MAAM,aAAa,EAAE,CAAC;CAC7B,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CAuO5G"}

package/dist/async-log-suite.js

@@ -0,0 +1,226 @@
+/**
+ * Contract suite for async work's invocation lines (#1901): the one line the scope host
+ * writes per consumer delivery, executor attempt and schedule run.
+ *
+ * Every case drives a real scope and reads the lines the host wrote, on both adapters — the
+ * Durable Object's consumers run inside workerd and its executors and schedules on the
+ * coordinator, the SQLite host does all of it in process, and any of the three could stamp
+ * the wrong id, call a failure a success, or let the error's text through.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { moduleId, platformActorId, principalId, scopeId, tenantId } from '@substrat-run/contracts';
+import { ASYNC_LINES_PER_PASS, ulid, } from '@substrat-run/kernel';
+import { ASYNC_LOG_SECRET_ENTITY, ASYNC_LOG_SECRET_TEXT, asyncLogMod } from './modules.js';
+const ASYNC_MODULE = moduleId.parse('@test/asynclog');
+const EFFECTOR = 'asynclog-effector';
+export function asyncLogContractSuite(adapterName, makeFixture) {
+    describe(`async invocation lines (#1901): ${adapterName}`, () => {
+        let fixture;
+        let host;
+        const t = tenantId.parse(ulid());
+        const staff = platformActorId.parse(ulid());
+        const alice = principalId.parse(ulid());
+        let s;
+        /** The tags the executor ran for — the effect, observed. */
+        const effected = [];
+        const scope = async (extra = {}) => {
+            const id = scopeId.parse(ulid());
+            await host.provisionScope(staff, { tenantId: t, scopeId: id, vertical: 'asynclog-vertical', ...extra });
+            await host.admin.activateScope(staff, t, id);
+            return id;
+        };
+        const act = async (on, tags, fail = false) => {
+            const invocationId = ulid();
+            const stub = await host.getScope(alice, t, on);
+            await stub.invoke('asynclog/act', { tags, fail }, { invocationId });
+            return invocationId;
+        };
+        /** The async lines about one event, by consumer. */
+        const linesAbout = (eventTag, operation) => {
+            const ids = new Set(fixture
+                .logs()
+                .filter((l) => l.template === 'consumed {tag}' && l.fields['tag'] === eventTag)
+                .map((l) => l.invocationId));
+            return fixture.lines().filter((l) => l.kind === 'consumer' && l.operation === operation && ids.has(l.invocationId));
+        };
+        const byEvent = (eventId) => fixture.lines().filter((l) => l.eventId === eventId);
+        beforeAll(async () => {
+            fixture = await makeFixture();
+            host = fixture.host;
+            host.registerModule(asyncLogMod);
+            // Retries at once, and dead-letters on the second attempt: the shortest real retry.
+            host.registerExecutor(EFFECTOR, 'asynclog.acted', async (_admin, event) => {
+                const { tag } = event.payload;
+                if (tag.startsWith('flaky'))
+                    throw new Error(`effector refused ${tag}: ${ASYNC_LOG_SECRET_TEXT}`);
+                effected.push(tag);
+            }, { maxAttempts: 2, baseDelayMs: 0 });
+            await host.admin.createTenant(staff, { id: t, slug: `asynclog-${t.slice(-8).toLowerCase()}`, name: 'Async log' });
+            await host.admin.grantEntitlement(staff, t, 'asynclog');
+            s = await scope();
+        });
+        afterAll(async () => {
+            await fixture.cleanup();
+        });
+        it('a delivered consumer writes one info line, under the call it ran in, beside its ctx.log line', async () => {
+            const tag = `ok-${ulid()}`;
+            const invocationId = await act(s, [tag]);
+            const [line, ...more] = fixture
+                .lines()
+                .filter((l) => l.kind === 'consumer' && l.operation === '@test/asynclog' && l.invocationId === invocationId);
+            expect(more).toEqual([]);
+            expect(line).toMatchObject({
+                substrat: 'invocation',
+                kind: 'consumer',
+                tenantId: t,
+                scopeId: s,
+                method: null,
+                path: null,
+                status: null,
+                threw: false,
+                level: 'info',
+                outcome: 'delivered',
+                operation: '@test/asynclog',
+                eventType: 'asynclog.acted',
+                attempt: 1,
+                problemCode: null,
+                principalKind: 'system',
+            });
+            expect(line.eventId).toMatch(/^[0-9A-HJKMNP-TV-Z]{26}$/);
+            // The handler's ctx.log line joins it: same id, so the call's drill-down shows both.
+            expect(fixture.logs().find((l) => l.fields['tag'] === tag)).toMatchObject({ invocationId, operation: null });
+        });
+        it('outside any call, a delivery mints its own id, and its ctx.log line still joins it', async () => {
+            const tag = `nocall-${ulid()}`;
+            const stub = await host.getScope(alice, t, s);
+            // No invocation id: the tail that delivers the event runs in no call.
+            await stub.invoke('asynclog/act', { tags: [tag], fail: false });
+            const log = fixture.logs().find((l) => l.fields['tag'] === tag);
+            expect(log?.invocationId).toMatch(/^[0-9A-HJKMNP-TV-Z]{26}$/);
+            expect(linesAbout(tag, '@test/asynclog')).toEqual([
+                expect.objectContaining({ kind: 'consumer', outcome: 'delivered', invocationId: log.invocationId }),
+            ]);
+        });
+        it('a consumer that throws is an error line, dead-lettered, with the code and none of the text', async () => {
+            const tag = `refuse-${ulid()}`;
+            const invocationId = await act(s, [tag], true);
+            const [line] = fixture
+                .lines()
+                .filter((l) => l.kind === 'consumer' && l.operation === '@test/asynclog' && l.invocationId === invocationId);
+            expect(line).toMatchObject({
+                level: 'error',
+                threw: true,
+                outcome: 'dead-lettered',
+                problemCode: 'precondition_failed',
+                attempt: 1,
+            });
+            // Ids, names and codes only: neither the error's text nor the payload's tag.
+            const text = JSON.stringify(line);
+            expect(text).not.toContain(ASYNC_LOG_SECRET_TEXT);
+            expect(text).not.toContain(tag);
+            expect(linesAbout(tag, '@test/asynclog')).toEqual([line]);
+        });
+        it('an executor that throws is retrying on attempt 1 and dead-lettered on attempt 2, each its own line', async () => {
+            const tag = `flaky-${ulid()}`;
+            const invocationId = await act(s, [tag]);
+            const first = fixture
+                .lines()
+                .find((l) => l.operation === `executor:${EFFECTOR}` && l.invocationId === invocationId);
+            expect(first).toMatchObject({
+                kind: 'consumer',
+                level: 'error',
+                threw: true,
+                outcome: 'retrying',
+                attempt: 1,
+                eventType: 'asynclog.acted',
+            });
+            expect(JSON.stringify(first)).not.toContain(ASYNC_LOG_SECRET_TEXT);
+            // The retry runs in a sweep, which is no call: its line mints its own id.
+            const report = await host.drainDue(t, s);
+            expect(report.deadLettered).toBeGreaterThanOrEqual(1);
+            const attempts = byEvent(first.eventId).filter((l) => l.operation === `executor:${EFFECTOR}`);
+            expect(attempts.map((l) => [l.attempt, l.outcome, l.level])).toEqual([
+                [1, 'retrying', 'error'],
+                [2, 'dead-lettered', 'error'],
+            ]);
+            expect(attempts[1].invocationId).not.toBe(invocationId);
+        });
+        it('a delivered executor is an info line, and a drain with nothing due writes none', async () => {
+            const tag = `effect-${ulid()}`;
+            const invocationId = await act(s, [tag]);
+            expect(effected).toContain(tag);
+            const line = fixture.lines().find((l) => l.operation === `executor:${EFFECTOR}` && l.invocationId === invocationId);
+            expect(line).toMatchObject({ outcome: 'delivered', level: 'info', attempt: 1, threw: false });
+            const before = fixture.lines().length;
+            await host.drainDue(t, s);
+            expect(fixture.lines().slice(before).filter((l) => l.scopeId === s)).toEqual([]);
+        });
+        it('a copy of a scope logs its held deliveries as inert — a warning, never delivered', async () => {
+            const copy = await scope({ kind: 'preview' });
+            const tag = `inert-${ulid()}`;
+            const invocationId = await act(copy, [tag]);
+            expect(effected).not.toContain(tag);
+            const line = fixture.lines().find((l) => l.operation === `executor:${EFFECTOR}` && l.invocationId === invocationId);
+            expect(line).toMatchObject({ scopeId: copy, outcome: 'inert', level: 'warn', threw: false });
+            expect(fixture.lines().filter((l) => l.eventId === line.eventId && l.operation === `executor:${EFFECTOR}`)).toEqual([
+                line,
+            ]);
+        });
+        it('a schedule run writes a schedule line under the run id its ctx.log lines carry, with its lateness', async () => {
+            const report = await host.runDueSchedules(ASYNC_MODULE, t, s);
+            expect(report.fired).toBe(1);
+            expect(report.failed).toBe(1);
+            const ok = fixture.lines().find((l) => l.kind === 'schedule' && l.scopeId === s && l.operation === 'asynclog/tick');
+            expect(ok).toMatchObject({
+                kind: 'schedule',
+                tenantId: t,
+                outcome: 'ok',
+                level: 'info',
+                threw: false,
+                principalKind: 'system',
+                // A first run has no due time to be late against.
+                dueAt: null,
+                latenessMs: null,
+                method: null,
+                path: null,
+            });
+            expect(fixture.logs().find((l) => l.template === 'ticked' && l.scopeId === s)?.invocationId).toBe(ok.invocationId);
+            // What the run emitted is counted by declared type; the entity — an email — is not named,
+            // on its line or on the line of the consumer it reached.
+            expect(ok).toMatchObject({ eventCount: 1, eventTypes: ['asynclog.acted'], entities: [] });
+            const ofRun = fixture.lines().filter((l) => l.invocationId === ok.invocationId);
+            expect(ofRun.length).toBeGreaterThanOrEqual(2);
+            expect(JSON.stringify(ofRun)).not.toContain(ASYNC_LOG_SECRET_ENTITY);
+            const failed = fixture
+                .lines()
+                .find((l) => l.kind === 'schedule' && l.scopeId === s && l.operation === 'asynclog/tick-fails');
+            expect(failed).toMatchObject({ outcome: 'failed', level: 'error', threw: true, problemCode: 'conflict' });
+            expect(JSON.stringify(failed)).not.toContain(ASYNC_LOG_SECRET_TEXT);
+            expect(fixture.logs().find((l) => l.template === 'ticking, about to refuse' && l.scopeId === s)?.invocationId).toBe(failed.invocationId);
+            // Not due again: a skipped schedule writes nothing.
+            const before = fixture.lines().length;
+            await host.runDueSchedules(ASYNC_MODULE, t, s);
+            expect(fixture.lines().slice(before).filter((l) => l.kind === 'schedule' && l.scopeId === s)).toEqual([]);
+        });
+        it(`a pass over its cap writes ${ASYNC_LINES_PER_PASS} lines and one that counts the rest by outcome`, async () => {
+            const capped = await scope();
+            const tags = Array.from({ length: ASYNC_LINES_PER_PASS + 5 }, (_, i) => `burst-${i}-${ulid()}`);
+            const invocationId = await act(capped, tags, true);
+            const ofModule = fixture
+                .lines()
+                .filter((l) => l.scopeId === capped && l.operation === '@test/asynclog' && l.invocationId === invocationId);
+            expect(ofModule).toHaveLength(ASYNC_LINES_PER_PASS);
+            const suppressed = fixture
+                .lines()
+                .filter((l) => l.scopeId === capped && l.outcome === 'suppressed' && l.invocationId === invocationId);
+            // One per pass that went over, each naming what it withheld by outcome — so the module
+            // consumers' dead-letter storm is named as one, at the worst level it withheld, and the
+            // executor's deliveries beside it stay info.
+            expect(suppressed.map((l) => [l.operation, l.suppressed, l.suppressedBy, l.level]).sort()).toEqual([
+                [null, 5, { 'consumer:dead-lettered': 5 }, 'error'],
+                [null, 5, { 'consumer:delivered': 5 }, 'info'],
+            ]);
+        });
+    });
+}
+//# sourceMappingURL=async-log-suite.js.map

package/dist/async-log-suite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-log-suite.js","sourceRoot":"","sources":["../src/async-log-suite.ts"],"names":[],"mappings":"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"}

package/dist/capability-suite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capability-suite.d.ts","sourceRoot":"","sources":["../src/capability-suite.ts"],"names":[],"mappings":"AAuDA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAkC9D,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,GAC3C,IAAI,CA0jBN"}
+{"version":3,"file":"capability-suite.d.ts","sourceRoot":"","sources":["../src/capability-suite.ts"],"names":[],"mappings":"AAwDA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAkC9D,wBAAgB,uBAAuB,CACrC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,GAC3C,IAAI,CA45BN"}

package/dist/capability-suite.js

@@ -514,6 +514,334 @@ export function capabilityContractSuite(adapterName, makeFixture) {
                 expect(errorCodeOf(await refusal(host.admin.revokeCapability(staff, t1, s1, ulid())))).toBe('not_found');
             });
         });
+        // #1686: the operator's read. A staff actor has no operation to stand in, so
+        // `HostAdmin.listCapabilities` is the directory `ctx.capabilities.list` reads, for them.
+        // The property that matters is what it NEVER returns — a secret or a hash — and each such
+        // check below has its positive twin: the same record shows everything else it should.
+        describe('the operator read — HostAdmin.listCapabilities (#1686)', () => {
+            const HEX64 = /\b[0-9a-f]{64}\b/i;
+            let shareLink;
+            let narrowed;
+            let revoked;
+            let claim;
+            let expiry;
+            let sessionToken;
+            const entriesOf = async (t, sc, filter) => (await host.admin.listCapabilities(staff, t, sc, filter)).entries;
+            const own = (rows) => rows.filter((r) => [shareLink, narrowed, revoked, claim].some((m) => m.id === r.id));
+            beforeAll(async () => {
+                expiry = inFuture(3_600_000);
+                shareLink = await share(alice, { entity: folder('F'), permissions: [CAP_READ], label: 'ops-share' });
+                narrowed = await share(alice, {
+                    entity: folder('G'),
+                    permissions: [CAP_READ],
+                    operations: ['cap/read'],
+                    expiresAt: expiry,
+                    maxUses: 3,
+                    label: 'ops-narrowed',
+                });
+                revoked = await share(alice, { entity: folder('F2'), permissions: [CAP_READ], label: 'ops-revoked' });
+                await (await as(alice)).invoke('cap/unshare', { id: revoked.id });
+                claim = await host.admin.mintCapability(staff, t1, s1, {
+                    principal: seat,
+                    expiresAt: inFuture(3_600_000),
+                    maxUses: 1,
+                    label: 'ops-claim',
+                });
+                sessionToken = await sessionOf(narrowed.secret); // one counted use on `narrowed`
+            });
+            it('lists what the module-side list does, as records an operator can read', async () => {
+                const rows = own(await entriesOf(t1, s1, { includeRevoked: true, limit: 200 }));
+                expect(rows.map((r) => r.id).sort()).toEqual([shareLink.id, narrowed.id, revoked.id, claim.id].sort());
+                const byId = new Map(rows.map((r) => [r.id, r]));
+                expect(byId.get(shareLink.id)).toMatchObject({
+                    mode: 'act',
+                    label: 'ops-share',
+                    entity: folder('F'),
+                    permissions: [CAP_READ],
+                    operations: null,
+                    mintedBy: alice,
+                    expiresAt: null,
+                    maxUses: null,
+                    uses: 0,
+                    revokedAt: null,
+                    revokedBy: null,
+                });
+                expect(byId.get(narrowed.id)).toMatchObject({
+                    mode: 'act',
+                    entity: folder('G'),
+                    operations: ['cap/read'],
+                    expiresAt: expiry,
+                    maxUses: 3,
+                    uses: 1,
+                });
+                expect(byId.get(narrowed.id).lastUsedAt).not.toBeNull();
+                expect(byId.get(revoked.id)).toMatchObject({ revokedBy: alice });
+                expect(byId.get(revoked.id).revokedAt).not.toBeNull();
+                expect(byId.get(claim.id)).toMatchObject({
+                    mode: 'become',
+                    principal: seat,
+                    mintedBy: { platform: staff },
+                    maxUses: 1,
+                });
+                // Every row is exactly the published record — the same schema ctx.capabilities.list is held to.
+                for (const r of rows)
+                    expect(capabilityRecord.parse(r)).toEqual(r);
+            });
+            it('never returns a secret or a hash — not as a field, not anywhere in the text', async () => {
+                const rows = await entriesOf(t1, s1, { includeRevoked: true, limit: 200 });
+                const text = JSON.stringify(rows);
+                // The positive twin of everything below: the read is not empty and is a faithful one.
+                expect(own(rows)).toHaveLength(4);
+                for (const m of [shareLink, narrowed, revoked, claim]) {
+                    expect(text).toContain(m.id);
+                    expect(text).not.toContain(m.secret);
+                    expect(text).not.toContain(await capabilityTokenHash(m.secret));
+                }
+                // A session token's hash is as live a credential as the capability's own.
+                expect(text).not.toContain(sessionToken);
+                expect(text).not.toContain(await capabilityTokenHash(sessionToken));
+                // And whatever else a column might carry: no 64-hex digest of anything.
+                expect(text).not.toMatch(HEX64);
+                // Field by field: a record has only the published keys, and none of them is a credential.
+                const allowed = new Set([
+                    ...Object.keys(capabilityRecord.options[0].shape),
+                    ...Object.keys(capabilityRecord.options[1].shape),
+                ]);
+                for (const r of rows) {
+                    for (const key of Object.keys(r)) {
+                        expect(allowed.has(key)).toBe(true);
+                        expect(key).not.toMatch(/hash|secret|token/i);
+                    }
+                }
+            });
+            it('is live-only by default, and shows the revoked one when asked', async () => {
+                const live = own(await entriesOf(t1, s1, { limit: 200 })).map((r) => r.id);
+                expect(live).toContain(shareLink.id);
+                expect(live).not.toContain(revoked.id);
+                const all = own(await entriesOf(t1, s1, { includeRevoked: true, limit: 200 }));
+                expect(all.map((r) => r.id)).toContain(revoked.id);
+            });
+            it('is newest first, narrows by entity, and is bounded', async () => {
+                const all = await entriesOf(t1, s1, { includeRevoked: true, limit: 200 });
+                const ids = all.map((r) => r.id);
+                expect(ids).toEqual([...ids].sort().reverse()); // ULIDs: id order IS mint order
+                const onG = await entriesOf(t1, s1, { entity: folder('G'), includeRevoked: true });
+                expect(onG.length).toBeGreaterThan(0);
+                expect(onG.every((r) => r.mode === 'act' && r.entity.entityId === 'G')).toBe(true);
+                expect(onG.map((r) => r.id)).toContain(narrowed.id);
+                expect(await entriesOf(t1, s1, { limit: 1 })).toHaveLength(1);
+                // The bound is the filter's: past it is refused, not silently clamped.
+                await expect(host.admin.listCapabilities(staff, t1, s1, { limit: 201 })).rejects.toThrow();
+                await expect(host.admin.listCapabilities(staff, t1, s1, { limit: 0 })).rejects.toThrow();
+            });
+            it('reads the scope it is asked about and no other (K-3), and each read leaves an access row', async () => {
+                const other = await entriesOf(t1, s2, { includeRevoked: true, limit: 200 });
+                expect(own(other)).toEqual([]);
+                // A scope of another tenant: the pair does not resolve, so no log of another tenant's is reachable.
+                const t2 = tenantId.parse(ulid());
+                const s3 = scopeId.parse(ulid());
+                await host.admin.createTenant(staff, { id: t2, slug: 'cap-tenant-2', name: 'Cap Tenant 2' });
+                await host.admin.grantEntitlement(staff, t2, 'cap');
+                await host.provisionScope(staff, { tenantId: t2, scopeId: s3, vertical: 'cap-vertical' });
+                await host.admin.activateScope(staff, t2, s3);
+                const foreign = await host.admin.mintCapability(staff, t2, s3, {
+                    principal: seat,
+                    expiresAt: inFuture(60_000),
+                    maxUses: 1,
+                    label: 'ops-foreign',
+                });
+                await expect(host.admin.listCapabilities(staff, t2, s1)).rejects.toThrow();
+                await expect(host.admin.listCapabilities(staff, t1, s3)).rejects.toThrow();
+                // The twin: the foreign tenant's own pair reads its own row, which t1's never showed.
+                const theirs = await entriesOf(t2, s3);
+                expect(theirs.map((r) => r.id)).toEqual([foreign.id]);
+                expect(JSON.stringify(await entriesOf(t1, s1, { includeRevoked: true, limit: 200 }))).not.toContain(foreign.id);
+                const logged = await host.admin.accessLog(staff, { tenantId: t1, method: 'listCapabilities' });
+                expect(logged.length).toBeGreaterThan(0);
+                expect(JSON.stringify(logged)).not.toContain(shareLink.secret);
+            });
+            it('is a read: the use counts it reports do not move because it was asked', async () => {
+                const a = await entriesOf(t1, s1, { entity: folder('G'), includeRevoked: true });
+                const b = await entriesOf(t1, s1, { entity: folder('G'), includeRevoked: true });
+                expect(b).toEqual(a);
+            });
+            // Paging. A scope with more capabilities than one page holds is walked to the end by
+            // the cursor each page hands back — the operator is never left with the newest 50 and no
+            // way to the rest. The walk runs on a scope of its own so its count is exact.
+            describe('paging', () => {
+                const TOTAL = 205; // past the filter's own ceiling of 200, so no single read can hold it
+                const walkScope = scopeId.parse(ulid());
+                const minted = []; // oldest first
+                const mintMore = async (n) => {
+                    const stub = await as(alice, walkScope);
+                    const ids = [];
+                    for (let i = 0; i < n; i++) {
+                        ids.push((await stub.invoke('cap/share', { entity: folder('F'), permissions: [CAP_READ] })).id);
+                    }
+                    return ids;
+                };
+                const walk = async (limit, between) => {
+                    const seen = [];
+                    const sizes = [];
+                    let cursor;
+                    for (let page = 0;; page++) {
+                        const p = await host.admin.listCapabilities(staff, t1, walkScope, {
+                            limit,
+                            ...(cursor === undefined ? {} : { cursor: cursor }),
+                        });
+                        seen.push(...p.entries.map((r) => r.id));
+                        sizes.push(p.entries.length);
+                        if (p.nextCursor === null)
+                            return { seen, sizes };
+                        // The cursor is the last record of the page just read, and only a page with more behind it carries one.
+                        expect(p.nextCursor).toBe(p.entries[p.entries.length - 1].id);
+                        expect(p.entries).toHaveLength(limit);
+                        cursor = p.nextCursor;
+                        await between?.(page);
+                        expect(page).toBeLessThan(TOTAL + 100); // a cursor that does not advance would loop for ever
+                    }
+                };
+                beforeAll(async () => {
+                    await host.provisionScope(staff, { tenantId: t1, scopeId: walkScope, vertical: 'cap-vertical' });
+                    await host.admin.activateScope(staff, t1, walkScope);
+                    minted.push(...(await mintMore(TOTAL)));
+                }, 120_000);
+                it('hands back a cursor exactly when more follow, and the whole set is reachable in pages', async () => {
+                    const newestFirst = [...minted].reverse();
+                    // The default page is not the whole set — and says so rather than looking complete.
+                    const first = await host.admin.listCapabilities(staff, t1, walkScope);
+                    expect(first.entries.map((r) => r.id)).toEqual(newestFirst.slice(0, 50));
+                    expect(first.nextCursor).toBe(newestFirst[49]);
+                    // Even the ceiling does not hold 205: the 5 oldest are behind the cursor, not dropped.
+                    const max = await host.admin.listCapabilities(staff, t1, walkScope, { limit: 200 });
+                    expect(max.entries).toHaveLength(200);
+                    expect(max.nextCursor).toBe(newestFirst[199]);
+                    const rest = await host.admin.listCapabilities(staff, t1, walkScope, { limit: 200, cursor: max.nextCursor });
+                    expect(rest.entries.map((r) => r.id)).toEqual(newestFirst.slice(200));
+                    expect(rest.nextCursor).toBeNull();
+                    // The walk, at several page sizes: every record once, newest first, no gap, no repeat.
+                    for (const limit of [1, 50, 73, 200]) {
+                        const { seen } = await walk(limit);
+                        expect([limit, seen]).toEqual([limit, newestFirst]);
+                    }
+                }, 120_000);
+                it('a page that ends exactly at the end carries no cursor (no trailing empty page)', async () => {
+                    // 205 = 5 × 41: five full pages of 41 end the walk exactly, with nothing after the fifth.
+                    const { sizes } = await walk(41);
+                    expect(sizes).toEqual([41, 41, 41, 41, 41]);
+                    const { sizes: by5 } = await walk(5);
+                    expect(by5).toEqual(Array(TOTAL / 5).fill(5));
+                });
+                it('a record minted mid-walk neither repeats nor drops one the walk had yet to reach', async () => {
+                    const before = [...minted].reverse();
+                    const added = [];
+                    const { seen } = await walk(40, async () => {
+                        added.push(...(await mintMore(1)));
+                    });
+                    // Every record that existed when the walk began, once and in order…
+                    expect(seen).toEqual(before);
+                    // …and the newcomers sort ahead of every cursor already handed out, so they are the
+                    // next walk's first records rather than a hole in this one.
+                    expect(added.length).toBeGreaterThan(0);
+                    const fresh = await host.admin.listCapabilities(staff, t1, walkScope, { limit: added.length });
+                    expect(fresh.entries.map((r) => r.id)).toEqual([...added].reverse());
+                    minted.push(...added);
+                }, 120_000);
+                it('narrows and pages together: the cursor walks the filtered set', async () => {
+                    const stub = await as(alice, walkScope);
+                    const g = await stub.invoke('cap/share', { entity: folder('G'), permissions: [CAP_READ] });
+                    const g2 = await stub.invoke('cap/share', { entity: folder('G'), permissions: [CAP_READ] });
+                    minted.push(g.id, g2.id);
+                    const one = await host.admin.listCapabilities(staff, t1, walkScope, { entity: folder('G'), limit: 1 });
+                    expect(one.entries.map((r) => r.id)).toEqual([g2.id]);
+                    expect(one.nextCursor).toBe(g2.id);
+                    const two = await host.admin.listCapabilities(staff, t1, walkScope, {
+                        entity: folder('G'),
+                        limit: 1,
+                        cursor: one.nextCursor,
+                    });
+                    expect(two.entries.map((r) => r.id)).toEqual([g.id]);
+                    expect(two.nextCursor).toBeNull();
+                });
+                it('refuses a cursor that is not a capability id, and a limit past the bound', async () => {
+                    for (const cursor of ['', 'not-an-id', 'sbcap_x', '01JZ0000000000000000000000'.toLowerCase()]) {
+                        await expect(host.admin.listCapabilities(staff, t1, walkScope, { cursor: cursor })).rejects.toThrow();
+                    }
+                    await expect(host.admin.listCapabilities(staff, t1, walkScope, { limit: 201 })).rejects.toThrow();
+                    // The twin: a well-formed cursor is accepted, even one that matches nothing.
+                    const nothing = await host.admin.listCapabilities(staff, t1, walkScope, { cursor: ulid() });
+                    expect(nothing.entries.length).toBeGreaterThanOrEqual(0);
+                });
+                it('pages carry the same records and no hash, however they are cut', async () => {
+                    const p = await host.admin.listCapabilities(staff, t1, walkScope, { limit: 3 });
+                    expect(JSON.stringify(p)).not.toMatch(HEX64);
+                    expect(Object.keys(p).sort()).toEqual(['entries', 'nextCursor']);
+                });
+            });
+        });
+        // #1686: capability rows never cross a scope id. A link minted on production opens
+        // production, never a fork or a preview copy of it; a backup restored into the scope it
+        // came from keeps the links that were live. Every refusal on the copy is paired with the
+        // source still working, and the copy is shown to hold the rest of the data.
+        describe('forks and restores — a link never opens a copy (#1686)', () => {
+            let link;
+            let token;
+            const listed = async (sc) => (await host.admin.listCapabilities(staff, t1, sc, { includeRevoked: true, limit: 200 })).entries.map((r) => r.id);
+            const refusedAt = async (sc) => {
+                expect(await exchange(link.secret, sc)).toBeNull();
+                const stub = await host.getCapabilityScope(token, t1, sc);
+                expect(errorCodeOf(await refusal(stub.invoke('cap/read', { entity: folder('F') })))).toBe('unauthenticated');
+                expect(await listed(sc)).toEqual([]);
+                // The copy is a working copy of everything else: the owner reads the shared folder there.
+                await expect((await as(alice, sc)).invoke('cap/read', { entity: folder('F') })).resolves.toMatchObject({
+                    read: folder('F'),
+                });
+            };
+            const worksAtSource = async () => {
+                expect((await exchange(link.secret, s1))?.kind).toBe('session');
+                const stub = await host.getCapabilityScope(token, t1, s1);
+                await expect(stub.invoke('cap/read', { entity: doc('d1') })).resolves.toMatchObject({ read: doc('d1') });
+                expect(await listed(s1)).toContain(link.id);
+            };
+            beforeAll(async () => {
+                link = await share(alice, { entity: folder('F'), permissions: [CAP_READ], label: 'fork-share' });
+                token = await sessionOf(link.secret);
+            });
+            it('the dump a copy is made from carries the capability row — what the loader leaves behind is real', async () => {
+                const dumped = await host.admin.exportScope(staff, t1, s1);
+                const caps = dumped.tables.find((t) => t.name === '_substrat_capabilities');
+                expect(JSON.stringify(caps?.rows)).toContain(await capabilityTokenHash(link.secret));
+                const sessions = dumped.tables.find((t) => t.name === '_substrat_capability_sessions');
+                expect(JSON.stringify(sessions?.rows)).toContain(await capabilityTokenHash(token));
+            });
+            it('a fork (importScope): the secret and the session are refused there, and the fork lists nothing', async () => {
+                const fork = scopeId.parse(ulid());
+                await host.importScope(staff, { tenantId: t1, scopeId: fork, vertical: 'cap-vertical' }, await host.admin.exportScope(staff, t1, s1));
+                await refusedAt(fork);
+                await worksAtSource();
+            });
+            it('a snapshot (snapshotScope): the same', async () => {
+                const snap = await host.snapshotScope(staff, t1, s1, { kind: 'preview' });
+                await refusedAt(snap);
+                await worksAtSource();
+            });
+            it("a restore of this scope's backup onto another scope: the same", async () => {
+                const other = scopeId.parse(ulid());
+                await host.provisionScope(staff, { tenantId: t1, scopeId: other, vertical: 'cap-vertical' });
+                await host.admin.activateScope(staff, t1, other);
+                await host.restoreScope(staff, t1, other, await host.admin.exportScope(staff, t1, s1));
+                await refusedAt(other);
+                await worksAtSource();
+            });
+            it('a restore into the scope the backup came from keeps the link, its session and its listing', async () => {
+                const backup = await host.admin.exportScope(staff, t1, s1);
+                await host.restoreScope(staff, t1, s1, backup);
+                await worksAtSource();
+                // Its standing came back as it was: still live, the uses it had.
+                const rec = (await host.admin.listCapabilities(staff, t1, s1, { limit: 200 })).entries.find((r) => r.id === link.id);
+                expect(rec).toMatchObject({ revokedAt: null, label: 'fork-share' });
+            });
+        });
     });
 }
 //# sourceMappingURL=capability-suite.js.map