@substrat-run/contract-tests 0.138.0 → 0.140.0

package/dist/permission-suite.js

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { coverage, moduleId, permissionKey, platformActorId, orgId, principalId, scopeId, tenantId, delegatedReadParams, moduleManifest, PERMISSION_KEY_MAX_LENGTH, } from '@substrat-run/contracts';
+import { coverage, moduleId, permissionKey, platformActorId, orgId, principalId, scopeId, tenantId, delegatedReadParams, errorCodeOf, moduleManifest, PERMISSION_KEY_MAX_LENGTH, } from '@substrat-run/contracts';
 import { ulid } from '@substrat-run/kernel';
 import { expectRefusal } from './scope-host-suite.js';
 import { permMod, permModManifest } from './modules.js';
@@ -109,6 +109,111 @@ export function permissionContractSuite(adapterName, makeFixture) {
         afterAll(async () => {
             await fixture.cleanup();
         });
+        /** A complete page walk is compared with the real checker, never another grant query. */
+        const grantedIds = async (who, entityType) => {
+            const stub = await host.getScope(who, t1, s1);
+            const ids = [];
+            let cursor;
+            for (let pageNo = 0; pageNo < 100; pageNo++) {
+                const page = await stub.invoke('perm/granted-entities', {
+                    permission: PERM_READ, entityType, limit: 2, ...(cursor ? { cursor } : {}),
+                });
+                if (page.kind !== 'ids')
+                    return page.kind;
+                ids.push(...page.ids);
+                if (page.nextCursor === null)
+                    return ids;
+                cursor = page.nextCursor;
+            }
+            throw new Error('grant walk did not terminate');
+        };
+        it('grant-scoped pages equal ctx.check over generated parent graphs', async () => {
+            const owner = await host.getScope(alice, t1, s1);
+            for (let graph = 0; graph < 4; graph++) {
+                const who = principalId.parse(ulid());
+                const folder = (n) => ({ entityType: 'folder', entityId: `gr-${graph}-f${n}` });
+                const item = (n) => ({ entityType: 'item', entityId: `gr-${graph}-i${n}` });
+                let seed = graph + 17;
+                const pick = (n) => {
+                    seed = (Math.imul(seed, 1664525) + 1013904223) >>> 0;
+                    return seed % n;
+                };
+                const edges = new Set();
+                for (let i = 1; i < 6; i++) {
+                    for (let j = 0; j < 2; j++) {
+                        const parent = pick(i);
+                        const key = `${i}:${parent}`;
+                        if (edges.has(key))
+                            continue;
+                        edges.add(key);
+                        await owner.invoke('perm/link', { child: folder(i), parent: folder(parent) });
+                    }
+                }
+                for (let i = 0; i < 8; i++) {
+                    await owner.invoke('perm/link', { child: item(i), parent: folder(pick(6)) });
+                }
+                for (const entity of [folder(pick(6)), folder(pick(6)), item(pick(8))]) {
+                    await host.admin.grant(staff, {
+                        principalId: who, permission: PERM_READ, node: { tenantId: t1, scopeId: s1 },
+                        entity, grantedBy: alice,
+                    });
+                }
+                await host.admin.grant(staff, {
+                    principalId: who, permission: PERM_READ, node: { tenantId: t1, scopeId: s1 },
+                    entity: folder(pick(6)), grantedBy: alice,
+                    expiresAt: (await import('@substrat-run/contracts')).instant.parse('2000-01-01T00:00:00Z'),
+                });
+                const expected = [];
+                for (let i = 0; i < 8; i++) {
+                    if ((await probe(who, s1, PERM_READ, item(i))).allowed)
+                        expected.push(item(i).entityId);
+                }
+                const got = await grantedIds(who, 'item');
+                expect(got).not.toBe('all');
+                expect(got).not.toBe('incomplete');
+                expect(new Set(got)).toEqual(new Set(expected));
+            }
+        });
+        it('node roles return all, while an ungranted caller has an empty completed page', async () => {
+            expect(await grantedIds(alice, 'item')).toBe('all');
+            expect(await grantedIds(principalId.parse(ulid()), 'item')).toEqual([]);
+        });
+        it('an org entity grant is enumerated only for its live member', async () => {
+            const member = principalId.parse(ulid());
+            const other = principalId.parse(ulid());
+            const org = orgId.parse(ulid());
+            const entity = { entityType: 'item', entityId: `org-grant-${ulid()}` };
+            await host.admin.createOrg(staff, { id: org, tenantId: t1, slug: `grant-${ulid().toLowerCase()}`, name: 'Grant Org' });
+            await host.admin.addMember(staff, t1, member, org);
+            await host.admin.grantToOrg(staff, org, PERM_READ, { tenantId: t1, scopeId: s1 }, entity);
+            expect(await grantedIds(member, 'item')).toContain(entity.entityId);
+            expect(await grantedIds(other, 'item')).toEqual([]);
+            await host.admin.removeMember(staff, t1, member, org);
+            expect(await grantedIds(member, 'item')).toEqual([]);
+        });
+        it('a revoked entity grant leaves no id on the next read', async () => {
+            const who = principalId.parse(ulid());
+            const entity = { entityType: 'item', entityId: `revoked-${ulid()}` };
+            await host.admin.grant(staff, {
+                principalId: who, permission: PERM_READ, node: { tenantId: t1, scopeId: s1 },
+                entity, grantedBy: alice,
+            });
+            expect(await grantedIds(who, 'item')).toContain(entity.entityId);
+            const owner = await host.getScope(alice, t1, s1);
+            await owner.invoke('perm/revoke-grant', { principal: who, permission: PERM_READ, entity });
+            expect(await grantedIds(who, 'item')).toEqual([]);
+        });
+        it('an expired entity grant does not enter a grant page', async () => {
+            const who = principalId.parse(ulid());
+            const entity = { entityType: 'item', entityId: `expired-${ulid()}` };
+            await host.admin.grant(staff, {
+                principalId: who, permission: PERM_READ, node: { tenantId: t1, scopeId: s1 },
+                entity, grantedBy: alice,
+                expiresAt: (await import('@substrat-run/contracts')).instant.parse('2000-01-01T00:00:00Z'),
+            });
+            expect((await probe(who, s1, PERM_READ, entity)).allowed).toBe(false);
+            expect(await grantedIds(who, 'item')).toEqual([]);
+        });
         /**
          * §5.1's assignment bound (K-21): a principal may assign role `R` at node `N` only
          * if they already hold every permission `R` carries at `N`.
@@ -228,6 +333,81 @@ export function permissionContractSuite(adapterName, makeFixture) {
                     expect((await probe(assignee, s1, PERM_READ)).allowed).toBe(false);
                 });
             });
+            /**
+             * The scope's role roster and the two bounded writes over it (#1150) — what a dashboard
+             * managing an installed vertical's members reads and calls. Each write is one scope
+             * task: the bound over every role it touches, then all of its writes, or none.
+             */
+            describe('the scope role roster, and bounded change and removal', () => {
+                const fresh = () => principalId.parse(ulid());
+                const rolesOf = async (who, scope = s1) => (await host.listScopeRoleHolders(t1, scope)).filter((h) => h.principal === who).map((h) => h.roleKey).sort();
+                const seat = async (who, roleKey) => expect((await host.assignScopeRoleBounded(t1, s1, alice, who, roleKey)).covered).toBe(true);
+                it('lists who holds which scope role, at this scope only, and drops a revoked one', async () => {
+                    const x = fresh();
+                    await seat(x, 'tech');
+                    expect(await rolesOf(x)).toEqual(['tech']);
+                    expect(await rolesOf(x, s2)).toEqual([]);
+                    expect((await host.revokeScopeRolesBounded(t1, s1, alice, x)).revoked).toEqual(['tech']);
+                    expect(await rolesOf(x)).toEqual([]);
+                });
+                it('changes a role in one write when the caller covers both', async () => {
+                    const x = fresh();
+                    await seat(x, 'tech');
+                    expect(await host.changeScopeRoleBounded(t1, s1, alice, x, 'tech', 'admin')).toEqual({ covered: true, missing: [] });
+                    expect(await rolesOf(x)).toEqual(['admin']);
+                    expect((await probe(x, s1, PERM_USE)).allowed).toBe(true);
+                });
+                /** Escalation: bob holds `tech` only, so he can neither promote someone nor demote an admin. */
+                it('refuses a change beyond the caller, leaving the old role in place', async () => {
+                    const x = fresh();
+                    await seat(x, 'tech');
+                    expect(await host.changeScopeRoleBounded(t1, s1, bob, x, 'tech', 'admin')).toEqual({ covered: false, missing: [PERM_USE] });
+                    expect(await rolesOf(x)).toEqual(['tech']);
+                    const y = fresh();
+                    await seat(y, 'admin');
+                    expect(await host.changeScopeRoleBounded(t1, s1, bob, y, 'admin', 'tech')).toEqual({ covered: false, missing: [PERM_USE] });
+                    expect(await rolesOf(y)).toEqual(['admin']);
+                    expect((await probe(y, s1, PERM_USE)).allowed).toBe(true);
+                });
+                it('writes nothing for an unknown target role, or a role the principal does not hold', async () => {
+                    const x = fresh();
+                    await seat(x, 'tech');
+                    await expectRefusal(host.changeScopeRoleBounded(t1, s1, alice, x, 'tech', 'no-such-role'), 'not_found', /no such role/);
+                    await expectRefusal(host.changeScopeRoleBounded(t1, s1, alice, x, 'admin', 'tech'), 'conflict', /does not hold/);
+                    expect(await rolesOf(x)).toEqual(['tech']);
+                });
+                it('removes every scope role a principal holds, bounded by the caller over each', async () => {
+                    const x = fresh();
+                    await seat(x, 'tech');
+                    await seat(x, 'admin');
+                    // bob covers `tech` but not `admin`: nothing is taken, not even the role he covers.
+                    expect(await host.revokeScopeRolesBounded(t1, s1, bob, x)).toEqual({
+                        coverage: { covered: false, missing: [PERM_USE] },
+                        revoked: [],
+                    });
+                    expect(await rolesOf(x)).toEqual(['admin', 'tech']);
+                    const removed = await host.revokeScopeRolesBounded(t1, s1, alice, x);
+                    expect(removed.coverage.covered).toBe(true);
+                    expect([...removed.revoked].sort()).toEqual(['admin', 'tech']);
+                    expect(await rolesOf(x)).toEqual([]);
+                    expect((await probe(x, s1, PERM_READ)).allowed).toBe(false);
+                });
+                it('lets a caller remove a role they hold themselves', async () => {
+                    const x = fresh();
+                    await seat(x, 'tech');
+                    expect((await host.revokeScopeRolesBounded(t1, s1, bob, x)).revoked).toEqual(['tech']);
+                    expect((await probe(x, s1, PERM_READ)).allowed).toBe(false);
+                });
+                it('refuses another tenant’s scope as one that does not exist, writing nothing', async () => {
+                    const x = fresh();
+                    await seat(x, 'tech');
+                    const other = tenantId.parse(ulid());
+                    await expectRefusal(host.listScopeRoleHolders(other, s1), 'not_found', /unknown scope/);
+                    await expectRefusal(host.changeScopeRoleBounded(other, s1, alice, x, 'tech', 'admin'), 'not_found', /unknown scope/);
+                    await expectRefusal(host.revokeScopeRolesBounded(other, s1, alice, x), 'not_found', /unknown scope/);
+                    expect(await rolesOf(x)).toEqual(['tech']);
+                });
+            });
         });
         // -- runtime delegation: ctx.grant / ctx.revoke ---------------------------
         // The verb user-initiated sharing needs. Every OTHER entity-narrowed grant in
@@ -267,6 +447,321 @@ export function permissionContractSuite(adapterName, makeFixture) {
                 });
                 expect((await probe(frank, s1, PERM_USE, { entityType: 'item', entityId: 'i1' })).allowed).toBe(false);
             });
+            /**
+             * K-21 (#2071): a revoke tombstones rather than deletes, so "taken back" and "never held"
+             * are two facts. A declared entity-grant shape's top-up reads that difference: it must
+             * never hand a person back a key someone revoked from them.
+             */
+            describe('a revoke leaves a tombstone, and a re-grant clears it (K-21, #2071)', () => {
+                const i3 = { entityType: 'item', entityId: 'i3' };
+                const rows = async () => (await (await host.getScope(alice, t1, s1)).invoke('perm/grant-rows', { principal: frank })).filter((r) => r.object === 'item:i3');
+                const unshare = async () => (await host.getScope(alice, t1, s1)).invoke('perm/unshare', { principal: frank, permission: PERM_USE, entity: i3 });
+                it('the revoked row stays, tombstoned, and grants nothing', async () => {
+                    await share(alice, PERM_USE, i3);
+                    expect(await rows()).toEqual([{ relation: `granted:${PERM_USE}`, object: 'item:i3', revokedAt: null, expiresAt: null }]);
+                    await unshare();
+                    const [row] = await rows();
+                    expect(row?.revokedAt).toEqual(expect.any(String));
+                    expect((await probe(frank, s1, PERM_USE, i3)).allowed).toBe(false);
+                });
+                it('a repeat revoke changes nothing: the first tombstone keeps its instant', async () => {
+                    const [before] = await rows();
+                    await unshare();
+                    expect(await rows()).toEqual([before]);
+                });
+                it('a re-grant clears the tombstone and grants again', async () => {
+                    await share(alice, PERM_USE, i3);
+                    expect(await rows()).toEqual([{ relation: `granted:${PERM_USE}`, object: 'item:i3', revokedAt: null, expiresAt: null }]);
+                    expect((await probe(frank, s1, PERM_USE, i3)).allowed).toBe(true);
+                });
+                it('a grant over a live row leaves it as it was', async () => {
+                    const before = await rows();
+                    await share(alice, PERM_USE, i3);
+                    expect(await rows()).toEqual(before);
+                });
+                it('a copy of the scope carries the tombstone, and it still grants nothing there', async () => {
+                    await unshare();
+                    const s3 = scopeId.parse(ulid());
+                    await host.importScope(staff, { tenantId: t1, scopeId: s3, vertical: 'perm-vertical' }, await host.admin.exportScope(staff, t1, s1));
+                    expect((await probe(frank, s3, PERM_USE, i3)).allowed).toBe(false);
+                    const [carried] = (await (await host.getScope(alice, t1, s3)).invoke('perm/grant-rows', {
+                        principal: frank,
+                    })).filter((r) => r.object === 'item:i3');
+                    expect(carried?.revokedAt).toEqual(expect.any(String));
+                });
+            });
+        });
+        /**
+         * #2071: a vertical's declared entity-grant SHAPE reaches the people who already held it
+         * when it grows. The kernel's own edges are in `kernel/test/entity-grant-shape.test.ts`;
+         * this is the same reconcile end to end on each adapter, through the admin verbs a
+         * vertical calls, with the checker as the judge.
+         */
+        describe('a declared entity-grant shape reaches existing holders when it grows (#2071)', () => {
+            const s4 = scopeId.parse(ulid());
+            const OLD = [PERM_READ];
+            const GROWN = [PERM_READ, PERM_USE];
+            const node = { tenantId: t1, scopeId: s4 };
+            const desk = (id) => ({ entityType: 'desk', entityId: id });
+            const hana = principalId.parse(ulid());
+            const ivo = principalId.parse(ulid());
+            const jon = principalId.parse(ulid());
+            const kim = principalId.parse(ulid());
+            const shapeTo = (who, id, permissions = OLD) => host.admin.grantEntityShape(staff, { principalId: who, node, entity: desk(id), permissions, grantedBy: alice });
+            const reconcile = (permissions = GROWN, batch) => host.admin.reconcileEntityGrantShapes(staff, node, [{ entityType: 'desk', permissions, bootstrap: true }], batch === undefined ? undefined : { batch });
+            const can = async (who, permission, id) => (await probe(who, s4, permission, desk(id))).allowed;
+            const toppedUp = async (id) => (await host.getScope(alice, t1, s4)).invoke('perm/topped-up', desk(id));
+            beforeAll(async () => {
+                await host.provisionScope(staff, { tenantId: t1, scopeId: s4, vertical: 'perm-vertical' });
+                await host.admin.activateScope(staff, t1, s4);
+            });
+            it('the shape grant gives every key of the shape, and is audited', async () => {
+                await shapeTo(hana, 'd1');
+                expect(await can(hana, PERM_READ, 'd1')).toBe(true);
+                expect(await can(hana, PERM_USE, 'd1')).toBe(false);
+                const log = await host.admin.auditLog(staff, { tenantId: t1 });
+                expect(log.some((e) => e.action === 'grantEntityShape')).toBe(true);
+            });
+            it('a principal granted before a key was added holds it after the reconcile', async () => {
+                expect(await reconcile()).toEqual({ toppedUp: 1, retired: 0 });
+                expect(await can(hana, PERM_USE, 'd1')).toBe(true);
+                // ...on that entity only: the shape is entity-narrowed, and so is the top-up.
+                expect(await can(hana, PERM_USE, 'd2')).toBe(false);
+            });
+            it('the top-up is an event on the entity, written by the kernel, and the reconcile is audited', async () => {
+                const [event, ...rest] = await toppedUp('d1');
+                expect(rest).toEqual([]);
+                expect(event).toEqual({
+                    payload: { entity: desk('d1'), principal: hana, added: [PERM_USE] },
+                    actor: { system: '@substrat-run/kernel' },
+                    // No operation ran and no check passed: both say so rather than inventing one.
+                    operation: null,
+                    authorization: null,
+                });
+                const log = await host.admin.auditLog(staff, { tenantId: t1 });
+                expect(log.filter((e) => e.action === 'reconcileEntityGrantShapes')).toHaveLength(1);
+            });
+            it('a re-run is a no-op: nobody topped up, no event, no audit row', async () => {
+                expect(await reconcile()).toEqual({ toppedUp: 0, retired: 0 });
+                expect(await toppedUp('d1')).toHaveLength(1);
+                const log = await host.admin.auditLog(staff, { tenantId: t1 });
+                expect(log.filter((e) => e.action === 'reconcileEntityGrantShapes')).toHaveLength(1);
+            });
+            it('a key revoked from the holder (ctx.revoke) is not re-granted by the next top-up', async () => {
+                await shapeTo(ivo, 'd3');
+                await reconcile();
+                await (await host.getScope(alice, t1, s4)).invoke('perm/unshare', { principal: ivo, permission: PERM_USE, entity: desk('d3') });
+                expect(await can(ivo, PERM_USE, 'd3')).toBe(false);
+                expect(await reconcile([...GROWN, PERM_ADMIN])).toMatchObject({ toppedUp: expect.any(Number) });
+                expect(await can(ivo, PERM_USE, 'd3')).toBe(false);
+                // The positive twin: the key the shape gained this time DID arrive for the same person.
+                expect(await can(ivo, PERM_ADMIN, 'd3')).toBe(true);
+            });
+            it('someone ctx.granted one key of the shape is not a holder, and is not escalated to all of it', async () => {
+                await (await host.getScope(alice, t1, s4)).invoke('perm/share', { principal: jon, permission: PERM_READ, entity: desk('d1') });
+                await reconcile([...GROWN, PERM_ADMIN]);
+                expect(await can(jon, PERM_READ, 'd1')).toBe(true);
+                expect(await can(jon, PERM_USE, 'd1')).toBe(false);
+            });
+            it('passes are bounded: a small batch still reaches every holder, each exactly once', async () => {
+                const people = [0, 1, 2, 3, 4].map(() => principalId.parse(ulid()));
+                for (const [i, p] of people.entries())
+                    await shapeTo(p, `b${i}`, OLD);
+                expect(await reconcile([...GROWN, PERM_ADMIN], 2)).toEqual({ toppedUp: 5, retired: 0 });
+                for (const [i, p] of people.entries()) {
+                    expect(await can(p, PERM_ADMIN, `b${i}`)).toBe(true);
+                    expect(await toppedUp(`b${i}`)).toHaveLength(1);
+                }
+            });
+            it('the shape grant brings back a key a revoke tombstoned — it is the explicit grant', async () => {
+                await shapeTo(kim, 'd9', GROWN);
+                await (await host.getScope(alice, t1, s4)).invoke('perm/unshare', { principal: kim, permission: PERM_USE, entity: desk('d9') });
+                expect(await can(kim, PERM_USE, 'd9')).toBe(false);
+                await shapeTo(kim, 'd9', GROWN);
+                expect(await can(kim, PERM_USE, 'd9')).toBe(true);
+            });
+            it('the backfill marks a person on their OWN record only — a one-key grant delegated on another’s is not', async () => {
+                const seat = (id) => ({ entityType: 'seat', entityId: id });
+                const shape = (permissions) => [{ entityType: 'seat', permissions, bootstrap: true, holder: 'self' }];
+                const lena = principalId.parse(ulid());
+                const max = principalId.parse(ulid());
+                // Both granted before markers existed: lena on her own seat, max on lena's (a delegation).
+                for (const who of [lena, max]) {
+                    await host.admin.grant(staff, { principalId: who, permission: PERM_READ, node, entity: seat(lena), grantedBy: alice });
+                }
+                await host.admin.reconcileEntityGrantShapes(staff, node, shape([PERM_READ]));
+                await host.admin.reconcileEntityGrantShapes(staff, node, shape([PERM_READ, PERM_USE]));
+                expect((await probe(lena, s4, PERM_USE, seat(lena))).allowed).toBe(true);
+                expect((await probe(max, s4, PERM_USE, seat(lena))).allowed).toBe(false);
+            });
+            /**
+             * #2083: `holder: 'grantee'`, for a portal record that names no principal. Everyone holding a
+             * key of the shape there is marked, and from that reconcile on `ctx.grant` cannot give those
+             * keys on that type — so "holds one" keeps meaning "was given the shape".
+             */
+            it("a 'grantee' shape reaches people granted before markers, and ctx.grant can no longer give its keys", async () => {
+                const room = (id) => ({ entityType: 'room', entityId: id });
+                const shape = (permissions) => [{ entityType: 'room', permissions, bootstrap: true, holder: 'grantee' }];
+                const nils = principalId.parse(ulid());
+                const ola = principalId.parse(ulid());
+                const pia = principalId.parse(ulid());
+                // Two people on one portal record, granted key by key before the declaration.
+                for (const who of [nils, ola]) {
+                    await host.admin.grant(staff, { principalId: who, permission: PERM_READ, node, entity: room('r1'), grantedBy: alice });
+                }
+                await host.admin.reconcileEntityGrantShapes(staff, node, shape([PERM_READ]));
+                const share = async (permission) => (await host.getScope(alice, t1, s4)).invoke('perm/share', { principal: pia, permission, entity: room('r2') }).then(() => 'granted', errorCodeOf);
+                expect(await share(PERM_READ)).toBe('permission_denied');
+                // The twin: a key outside the shape, on the same type, is still delegable.
+                expect(await share(PERM_USE)).toBe('granted');
+                await host.admin.reconcileEntityGrantShapes(staff, node, shape([PERM_READ, PERM_ADMIN]));
+                for (const who of [nils, ola])
+                    expect((await probe(who, s4, PERM_ADMIN, room('r1'))).allowed).toBe(true);
+                // ...and the person ctx.granted the other key is no holder.
+                expect((await probe(pia, s4, PERM_ADMIN, room('r2'))).allowed).toBe(false);
+            });
+            it('a grantee retirement finds live retired-key holders, excludes tombstoned keys, and never tops up the retired key', async () => {
+                const scope = scopeId.parse(ulid());
+                const at = { tenantId: t1, scopeId: scope };
+                const room = (id) => ({ entityType: 'retiringRoom', entityId: id });
+                const oldLive = principalId.parse(ulid());
+                const oldDead = principalId.parse(ulid());
+                const current = principalId.parse(ulid());
+                const marked = principalId.parse(ulid());
+                await host.provisionScope(staff, { ...at, vertical: 'perm-vertical' });
+                await host.admin.activateScope(staff, t1, scope);
+                for (const [who, id] of [[oldLive, 'old-live'], [oldDead, 'old-dead']]) {
+                    await host.admin.grant(staff, { principalId: who, permission: PERM_READ, node: at, entity: room(id), grantedBy: alice });
+                }
+                await (await host.getScope(alice, t1, scope)).invoke('perm/unshare', { principal: oldDead, permission: PERM_READ, entity: room('old-dead') });
+                await host.admin.grant(staff, { principalId: current, permission: PERM_USE, node: at, entity: room('current'), grantedBy: alice });
+                await host.admin.grantEntityShape(staff, { principalId: marked, node: at, entity: room('marked'), permissions: [PERM_READ], grantedBy: alice });
+                const shape = [{ entityType: 'retiringRoom', permissions: [PERM_USE, PERM_ADMIN], retired: [PERM_READ], bootstrap: true, holder: 'grantee' }];
+                expect(await host.admin.reconcileEntityGrantShapes(staff, at, shape)).toEqual({ toppedUp: 3, retired: 2 });
+                const marker = async (who, id) => (await host.getScope(alice, t1, scope)).invoke('perm/shape-marker', {
+                    principal: who,
+                    entity: room(id),
+                });
+                expect((await probe(oldDead, scope, PERM_ADMIN, room('old-dead'))).allowed).toBe(false);
+                expect((await probe(oldDead, scope, PERM_USE, room('old-dead'))).allowed).toBe(false);
+                expect(await marker(oldDead, 'old-dead')).toEqual([]);
+                // The live retired-key holder is marked before retirement; the tombstoned-key twin
+                // stays unmarked. Previously marked holders retain their markers.
+                expect((await probe(oldDead, scope, PERM_READ, room('old-dead'))).allowed).toBe(false);
+                for (const [who, id] of [[oldLive, 'old-live'], [current, 'current'], [marked, 'marked']]) {
+                    expect((await probe(who, scope, PERM_ADMIN, room(id))).allowed).toBe(true);
+                    expect((await probe(who, scope, PERM_USE, room(id))).allowed).toBe(true);
+                    expect((await probe(who, scope, PERM_READ, room(id))).allowed).toBe(false);
+                    expect(await marker(who, id)).toEqual([{ revoked_at: null }]);
+                }
+                expect(await host.admin.reconcileEntityGrantShapes(staff, at, shape)).toEqual({ toppedUp: 0, retired: 0 });
+                for (const [who, id] of [[oldLive, 'old-live'], [marked, 'marked']]) {
+                    expect((await probe(who, scope, PERM_READ, room(id))).allowed).toBe(false);
+                }
+            });
+            it('after a grantee declaration, direct writers refuse current and retired keys; shape grants still work', async () => {
+                const scope = scopeId.parse(ulid());
+                const at = { tenantId: t1, scopeId: scope };
+                const room = (id) => ({ entityType: 'guardedRoom', entityId: id });
+                const [later, shaped] = [principalId.parse(ulid()), principalId.parse(ulid())];
+                await host.provisionScope(staff, { ...at, vertical: 'perm-vertical' });
+                await host.admin.activateScope(staff, t1, scope);
+                await host.admin.reconcileEntityGrantShapes(staff, at, [
+                    { entityType: 'guardedRoom', permissions: [PERM_USE], retired: [PERM_READ], bootstrap: true, holder: 'grantee' },
+                ]);
+                for (const permission of [PERM_USE, PERM_READ]) {
+                    await expectRefusal(host.admin.grant(staff, { principalId: later, permission, node: at, entity: room('r1'), grantedBy: alice }), 'permission_denied');
+                    await expectRefusal(host.admin.grantToOrg(staff, acme, permission, at, room('r1')), 'permission_denied');
+                    await expectRefusal((await host.getScope(alice, t1, scope)).invoke('perm/share', { principal: later, permission, entity: room('r1') }), 'permission_denied');
+                }
+                expect((await probe(later, scope, PERM_USE, room('r1'))).allowed).toBe(false);
+                // Protection is entity-type narrow; an unrelated key on the same type and a scoped
+                // grant of the same key remain valid, while the shape grant writes its marker atomically.
+                await host.admin.grant(staff, { principalId: later, permission: PERM_ADMIN, node: at, entity: room('r1'), grantedBy: alice });
+                await host.admin.grant(staff, { principalId: later, permission: PERM_USE, node: at, grantedBy: alice });
+                await host.admin.grantEntityShape(staff, { principalId: shaped, node: at, entity: room('r2'), permissions: [PERM_USE], grantedBy: alice });
+                expect((await probe(shaped, scope, PERM_USE, room('r2'))).allowed).toBe(true);
+                await host.admin.reconcileEntityGrantShapes(staff, at, [
+                    { entityType: 'guardedRoom', permissions: [PERM_USE, PERM_ADMIN], retired: [PERM_READ], bootstrap: true, holder: 'grantee' },
+                ]);
+                expect((await probe(shaped, scope, PERM_ADMIN, room('r2'))).allowed).toBe(true);
+                expect((await probe(shaped, scope, PERM_READ, room('r2'))).allowed).toBe(false);
+            });
+            it.each([0, -1, 1.5, 5001])('refuses batch %s with validation_failed, before touching the scope', async (batch) => {
+                const err = await reconcile(GROWN, batch).then(() => undefined, (e) => e);
+                expect(errorCodeOf(err)).toBe('validation_failed');
+            });
+            it('a sharing shape (no `bootstrap`) passed in is never reconciled, even for a marked holder', async () => {
+                await shapeTo(kim, 's1', OLD);
+                expect(await host.admin.reconcileEntityGrantShapes(staff, node, [{ entityType: 'desk', permissions: GROWN }])).toEqual({
+                    toppedUp: 0,
+                    retired: 0,
+                });
+                expect(await can(kim, PERM_USE, 's1')).toBe(false);
+            });
+        });
+        /**
+         * #2082: a key the declared shape RETIRES is taken back from every holder, end to end on each
+         * adapter. The kernel's own edges are in `kernel/test/entity-grant-shape.test.ts`.
+         */
+        describe('a key a declared shape retires is taken back from its holders (#2082)', () => {
+            const s5 = scopeId.parse(ulid());
+            const node = { tenantId: t1, scopeId: s5 };
+            const desk = (id) => ({ entityType: 'desk', entityId: id });
+            const SHAPE = [PERM_READ, PERM_USE];
+            const hana = principalId.parse(ulid());
+            const jon = principalId.parse(ulid());
+            const shapeTo = (who, id) => host.admin.grantEntityShape(staff, { principalId: who, node, entity: desk(id), permissions: SHAPE, grantedBy: alice });
+            const retire = (batch) => host.admin.reconcileEntityGrantShapes(staff, node, [{ entityType: 'desk', permissions: [PERM_READ], bootstrap: true, retired: [PERM_USE] }], batch === undefined ? undefined : { batch });
+            const can = async (who, permission, id) => (await probe(who, s5, permission, desk(id))).allowed;
+            const scope = () => host.getScope(alice, t1, s5);
+            const retiredOn = async (id) => (await scope()).invoke('perm/topped-up', {
+                ...desk(id),
+                type: 'entity.grants-retired',
+            });
+            beforeAll(async () => {
+                await host.provisionScope(staff, { tenantId: t1, scopeId: s5, vertical: 'perm-vertical' });
+                await host.admin.activateScope(staff, t1, s5);
+                await shapeTo(hana, 'd1');
+                // alice holds the shape too, and perm:use through her tenant role as well.
+                await shapeTo(alice, 'd2');
+                // jon is not a holder: ctx.granted the key on hana's desk.
+                await (await scope()).invoke('perm/share', { principal: jon, permission: PERM_USE, entity: desk('d1') });
+            });
+            it('the holder loses the key after the reconcile, and keeps the rest of the shape', async () => {
+                expect(await can(hana, PERM_USE, 'd1')).toBe(true);
+                expect(await retire()).toEqual({ toppedUp: 0, retired: 2 });
+                expect(await can(hana, PERM_USE, 'd1')).toBe(false);
+                expect(await can(hana, PERM_READ, 'd1')).toBe(true);
+            });
+            it('...while the key held another way stays: a non-holder’s direct grant, and a role', async () => {
+                expect(await can(jon, PERM_USE, 'd1')).toBe(true);
+                expect(await can(alice, PERM_USE, 'd2')).toBe(true);
+            });
+            it('the row is tombstoned, not deleted, and the retirement is a kernel event and an audit row', async () => {
+                const [row] = (await (await scope()).invoke('perm/grant-rows', { principal: hana })).filter((r) => r.relation === `granted:${PERM_USE}`);
+                expect(row?.revokedAt).toEqual(expect.any(String));
+                expect(await retiredOn('d1')).toEqual([
+                    { payload: { entity: desk('d1'), principal: hana, removed: [PERM_USE] }, actor: { system: '@substrat-run/kernel' }, operation: null, authorization: null },
+                ]);
+                const log = await host.admin.auditLog(staff, { tenantId: t1 });
+                expect(log.filter((e) => e.action === 'reconcileEntityGrantShapes' && e.scopeId === s5).map((e) => e.after.retired)).toEqual([2]);
+            });
+            it('runs once: a re-run retires nobody, and the key granted back afterwards stays', async () => {
+                await (await scope()).invoke('perm/share', { principal: hana, permission: PERM_USE, entity: desk('d1') });
+                expect(await retire()).toEqual({ toppedUp: 0, retired: 0 });
+                expect(await can(hana, PERM_USE, 'd1')).toBe(true);
+                expect(await retiredOn('d1')).toHaveLength(1);
+            });
+            it('the shape shrunk WITHOUT `retired` changes nothing for a holder', async () => {
+                const kim = principalId.parse(ulid());
+                await shapeTo(kim, 'd7');
+                expect(await host.admin.reconcileEntityGrantShapes(staff, node, [{ entityType: 'desk', permissions: [PERM_READ], bootstrap: true }])).toEqual({
+                    toppedUp: 0,
+                    retired: 0,
+                });
+                expect(await can(kim, PERM_USE, 'd7')).toBe(true);
+            });
         });
         it('denies by default with the checked permission and node', async () => {
             const d = await probe(principalId.parse(ulid()), s1, PERM_READ);
@@ -757,7 +1252,8 @@ export function permissionContractSuite(adapterName, makeFixture) {
                     const mine = out.deliveries.filter((d) => d.permission === PERM_READ);
                     expect(mine).toHaveLength(1);
                     expect(mine[0].error).toBeNull();
-                    expect(out.log.filter((r) => r.permission === PERM_READ).map((r) => r.allowed)).toEqual([1]);
+                    expect(out.log.filter((r) => r.permission === PERM_READ).map((r) => [r.allowed, r.grant_read_kind]))
+                        .toEqual([[1, 'all']]);
                 });
                 it('caught and ignored: no allow, and ctx.grant writes no tuple under the cast key', async () => {
                     const out = await requestCheck(CAST_KEY, true);
@@ -1437,6 +1933,98 @@ export function permissionContractSuite(adapterName, makeFixture) {
             await expect(host.admin.recordOwnerTransfer(operator, { ...base, phase: 'moved' })).rejects.toThrow();
             await expect(host.admin.recordOwnerTransfer(operator, { ...base, phase: 'intent', actor: staff })).rejects.toThrow();
             expect((await host.admin.auditLog(staff, { tenantId: t1 })).filter((r) => r.action === 'transferOwner')).toHaveLength(2);
+            // #2064: the platform sweep closes an intent with no outcome as `unknown`, saying why. Its
+            // reason is required, as a refusal's is.
+            await expect(host.admin.recordOwnerTransfer(operator, { ...base, phase: 'unknown' })).rejects.toThrow();
+            await host.admin.recordOwnerTransfer(operator, { ...base, phase: 'unknown', error: 'no outcome was recorded' });
+            const settled = (await host.admin.auditLog(staff, { tenantId: t1, action: 'transferOwner' })).at(-1);
+            expect(settled?.after).toEqual({ phase: 'unknown', error: 'no outcome was recorded', operationId, from, to });
+        });
+        it('settles an intent with no outcome ONCE, with its ops-failure row in the same unit (#2064)', async () => {
+            // Held on both adapters: the settle's check-then-write is one transaction on each, which is
+            // the whole reason two racing sweeps cannot both write `unknown`.
+            const from = principalId.parse(ulid());
+            const to = principalId.parse(ulid());
+            const opsOf = async (operationId) => (await host.admin.auditLog(staff, { tenantId: t1, action: 'transferOwner' }))
+                .filter((r) => r.after.operationId === operationId)
+                .map((r) => r.after.phase);
+            const intentOf = async (operationId) => {
+                await host.admin.recordOwnerTransfer(staff, { tenantId: t1, scopeId: s1, operationId, from, to, phase: 'intent' });
+                return (await host.admin.auditLog(staff, { tenantId: t1, action: 'transferOwner', order: 'desc', limit: 1 }))[0].id;
+            };
+            // Two settles racing on one orphan: exactly one writes, and one ops-failure row is left.
+            const orphan = ulid();
+            const intentId = await intentOf(orphan);
+            const raced = await Promise.all([
+                host.admin.settleUnrecordedOutcome(staff, { intentId, error: 'no outcome was recorded' }),
+                host.admin.settleUnrecordedOutcome(staff, { intentId, error: 'no outcome was recorded' }),
+            ]);
+            expect(raced.sort()).toEqual([false, true]);
+            expect(await opsOf(orphan)).toEqual(['intent', 'unknown']);
+            const settled = (await host.admin.auditLog(staff, { tenantId: t1, action: 'transferOwner', order: 'desc', limit: 1 }))[0];
+            expect(settled.after).toEqual({ phase: 'unknown', error: 'no outcome was recorded', operationId: orphan, from, to });
+            const failures = (await host.admin.listOpsFailures(staff, { tenantId: t1, operation: 'audit.transferOwner' }))
+                .filter((f) => f.message.includes(orphan));
+            expect(failures.map((f) => [f.stage, f.scopeId])).toEqual([['outcome-unknown', s1]]);
+            // A real outcome that lands later is still recorded, as the later row, and supersedes it.
+            await host.admin.recordOwnerTransfer(staff, { tenantId: t1, scopeId: s1, operationId: orphan, from, to, phase: 'refused', error: 'late' });
+            expect(await opsOf(orphan)).toEqual(['intent', 'unknown', 'refused']);
+            expect(await host.admin.settleUnrecordedOutcome(staff, { intentId, error: 'again' })).toBe(false);
+            // An intent whose outcome landed first is not settled — the twin of the orphan above.
+            const answered = ulid();
+            const answeredId = await intentOf(answered);
+            await host.admin.recordOwnerTransfer(staff, { tenantId: t1, scopeId: s1, operationId: answered, from, to, phase: 'applied', outcome: 'transferred', fromRevoked: true });
+            expect(await host.admin.settleUnrecordedOutcome(staff, { intentId: answeredId, error: 'no outcome' })).toBe(false);
+            expect(await opsOf(answered)).toEqual(['intent', 'applied']);
+            // Only an audited-change intent can be settled: an outcome row's id, or no row, is not_found.
+            const outcomeId = (await host.admin.auditLog(staff, { tenantId: t1, action: 'transferOwner', order: 'desc', limit: 1 }))[0].id;
+            await expect(host.admin.settleUnrecordedOutcome(staff, { intentId: outcomeId, error: 'x' })).rejects.toThrow(/no audited-change intent/);
+            await expect(host.admin.settleUnrecordedOutcome(staff, { intentId: ulid(), error: 'x' })).rejects.toThrow(/no audited-change intent/);
+        });
+        it('the settle checks the WHOLE operation: the same id answered in another tenant or scope does not settle it (#2064)', async () => {
+            const from = principalId.parse(ulid());
+            const to = principalId.parse(ulid());
+            const otherTenant = tenantId.parse(ulid());
+            const settleOf = async (operationId) => {
+                await host.admin.recordOwnerTransfer(staff, { tenantId: t1, scopeId: s1, operationId, from, to, phase: 'intent' });
+                const [intent] = await host.admin.auditLog(staff, { tenantId: t1, action: 'transferOwner', order: 'desc', limit: 1 });
+                return () => host.admin.settleUnrecordedOutcome(staff, { intentId: intent.id, error: 'no outcome was recorded' });
+            };
+            const failuresOf = async (operationId) => (await host.admin.listOpsFailures(staff, { tenantId: t1, operation: 'audit.transferOwner' })).filter((f) => f.reference === operationId);
+            // The orphan's id, answered in another tenant AND in another scope: neither is its outcome.
+            const collided = ulid();
+            const settle = await settleOf(collided);
+            const answered = { operationId: collided, from, to, phase: 'applied', outcome: 'transferred', fromRevoked: true };
+            await host.admin.recordOwnerTransfer(staff, { ...answered, tenantId: otherTenant, scopeId: s1 });
+            await host.admin.recordOwnerTransfer(staff, { ...answered, tenantId: t1, scopeId: s2 });
+            expect(await settle()).toBe(true);
+            expect((await failuresOf(collided)).map((f) => [f.stage, f.scopeId])).toEqual([['outcome-unknown', s1]]);
+            // The twin: answered under its own whole key, the orphan is not one, and nothing is written.
+            const own = ulid();
+            const settleOwn = await settleOf(own);
+            await host.admin.recordOwnerTransfer(staff, { ...answered, operationId: own, tenantId: t1, scopeId: s1 });
+            expect(await settleOwn()).toBe(false);
+            expect(await failuresOf(own)).toEqual([]);
+            // An id that is not well-formed text never reaches the log: matched in SQL and in memory,
+            // it would not read the same in both. Its well-formed twin is the case above.
+            await expect(host.admin.recordOwnerTransfer(staff, { tenantId: t1, scopeId: s1, operationId: 'op\uD800', from, to, phase: 'intent' })).rejects.toThrow(/well-formed/);
+        });
+        it('reads exactly the audited operations asked about, in batches a Durable Object can bind (#2064)', async () => {
+            const from = principalId.parse(ulid());
+            const to = principalId.parse(ulid());
+            // More operations than one batch binds, so a hosted read must split them.
+            const ops = Array.from({ length: 120 }, () => ulid());
+            for (const operationId of ops) {
+                await host.admin.recordOwnerTransfer(staff, { tenantId: t1, scopeId: s1, operationId, from, to, phase: 'intent' });
+            }
+            await host.admin.recordOwnerTransfer(staff, { tenantId: t1, scopeId: s1, operationId: ops[0], from, to, phase: 'refused', error: 'no' });
+            const refs = ops.map((operationId) => ({ action: 'transferOwner', operationId, tenantId: t1, scopeId: s1 }));
+            const rows = await host.admin.auditedOperations(staff, refs);
+            expect(rows).toHaveLength(121);
+            expect(rows.filter((r) => r.operationId === ops[0]).map((r) => r.phase).sort()).toEqual(['intent', 'refused']);
+            // An operation is its action and scope too: the same id asked under another is not it.
+            expect(await host.admin.auditedOperations(staff, [{ ...refs[0], action: 'manageScopeMember' }])).toEqual([]);
+            expect(await host.admin.auditedOperations(staff, [{ ...refs[0], scopeId: scopeId.parse(ulid()) }])).toEqual([]);
         });
         it('audits reading the audit trail, and reading the access log itself', async () => {
             const nosy = platformActorId.parse(ulid());