@substrat-run/contract-tests 0.88.0 → 0.90.0

package/dist/idempotency-suite.d.ts

@@ -0,0 +1,3 @@
+import type { ScopeHostFixture } from './scope-host-suite.js';
+export declare function idempotencyContractSuite(adapterName: string, makeFixture: () => Promise<ScopeHostFixture>): void;
+//# sourceMappingURL=idempotency-suite.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency-suite.d.ts","sourceRoot":"","sources":["../src/idempotency-suite.ts"],"names":[],"mappings":"AA4CA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAU9D,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,GAC3C,IAAI,CA6PN"}

package/dist/idempotency-suite.js

@@ -0,0 +1,243 @@
+/**
+ * Contract suite for request idempotency — `Idempotency-Key` (#116).
+ *
+ * What it pins: **a retry does not do the work twice, and the host is what makes
+ * that true.** Everything else about this feature is a projection — the header
+ * name is a wire detail `vertical-host` owns, the opt-out is a model detail
+ * `contracts` owns, and neither is what makes a retry free. This is: a recording
+ * written in the same transaction as the work, and a second request answered
+ * from it without running anything.
+ *
+ * **Every case counts executions rather than comparing responses.** A suite that
+ * asserted only on the returned value would pass against a host that re-ran the
+ * operation and produced the same answer again — which is exactly the bug, since
+ * a duplicated work order looks a great deal like the original. So the fixture
+ * appends a row per invocation and `idem/runs` reports the count, and that count
+ * is the assertion.
+ *
+ * The cases that matter are not the happy path:
+ *
+ * - **A failed request leaves no recording.** The row is written inside the
+ *   operation's transaction, so a throw takes it with the writes it describes and
+ *   the retry executes — correctly, because nothing happened the first time.
+ * - **A key belongs to the subject that sent it.** Two principals choosing `1`
+ *   must each get their own execution; a lookup that crossed that boundary would
+ *   replay one caller's response to another.
+ * - **A reused key is refused, never served.** Same key, different request means
+ *   the client's assertion is false, and answering with the earlier response
+ *   would be a lie it acts on.
+ * - **An unrecordable response fails closed.** A replay that cannot be answered
+ *   is a 409, not a second execution.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { errorCodeOf, permissionKey, platformActorId, principalId, scopeId, tenantId, IDEMPOTENCY_REPLAY_UNAVAILABLE, IDEMPOTENCY_REUSED, } from '@substrat-run/contracts';
+import { ulid } from '@substrat-run/kernel';
+import { idempotencyMod } from './modules.js';
+const IDEM_USE = permissionKey.parse('idem:use');
+/** The `reason` slug a refusal carried, or undefined — read off the thrown error. */
+function reasonOf(err) {
+    return err?.extensions?.['reason'];
+}
+export function idempotencyContractSuite(adapterName, makeFixture) {
+    describe(`request idempotency (Idempotency-Key): ${adapterName}`, () => {
+        let fixture;
+        let host;
+        let stub;
+        /** A second principal, for the case that a key is one caller's and not another's. */
+        let otherStub;
+        const t1 = tenantId.parse(ulid());
+        const s1 = scopeId.parse(ulid());
+        const alice = principalId.parse(ulid());
+        const bob = principalId.parse(ulid());
+        const staff = platformActorId.parse(ulid());
+        /** Whether each invocation was answered from a recording, newest last. */
+        let replays = [];
+        const sink = () => {
+            let replayed = false;
+            return {
+                options: {
+                    onIdempotentReplay: () => {
+                        replayed = true;
+                    },
+                },
+                done: () => replays.push(replayed),
+            };
+        };
+        const create = async (thingId, key, label, as = () => stub) => {
+            const probe = sink();
+            try {
+                return await as().invoke('idem/create', { thingId, ...(label === undefined ? {} : { label }) }, { ...probe.options, ...(key === undefined ? {} : { idempotencyKey: key }) });
+            }
+            finally {
+                probe.done();
+            }
+        };
+        /** How many times a handler in this module has actually run. */
+        const runs = async () => (await stub.invoke('idem/runs', {})).count;
+        beforeAll(async () => {
+            fixture = await makeFixture();
+            host = fixture.host;
+            host.registerModule(idempotencyMod);
+            await host.admin.createTenant(staff, { id: t1, slug: 'idem-tenant', name: 'Idem Tenant' });
+            await host.admin.grantEntitlement(staff, t1, 'idem');
+            await host.admin.defineRole(staff, t1, {
+                key: 'idem-admin',
+                permissions: [IDEM_USE],
+                source: 'vertical',
+            });
+            for (const principal of [alice, bob]) {
+                await host.admin.assignRole(staff, {
+                    principalId: principal,
+                    roleKey: 'idem-admin',
+                    node: { tenantId: t1, scopeId: null },
+                });
+            }
+            await host.provisionScope(staff, { tenantId: t1, scopeId: s1, vertical: 'idem-vertical' });
+            await host.admin.activateScope(staff, t1, s1);
+            stub = await host.getScope(alice, t1, s1);
+            otherStub = await host.getScope(bob, t1, s1);
+        });
+        afterAll(async () => {
+            await fixture.cleanup();
+        });
+        it('runs twice for two identical requests carrying no key', async () => {
+            const before = await runs();
+            await create('baseline');
+            await create('baseline');
+            // The baseline the whole feature is measured against: without a key there is
+            // no dedupe, and identical requests are two requests. A suite that skipped
+            // this could not tell a working replay from an operation that happens to be
+            // naturally idempotent.
+            expect(await runs()).toBe(before + 2);
+        });
+        it('runs once for a repeated request under one key, and replays the response', async () => {
+            const key = `k-${ulid()}`;
+            const before = await runs();
+            replays = [];
+            const first = await create('once', key, 'hello');
+            const second = await create('once', key, 'hello');
+            // The assertion that matters is the count, not the equality below it.
+            expect(await runs()).toBe(before + 1);
+            // `run` is a fresh ULID per execution, so identical values here mean the
+            // second response came from the recording rather than from a second run
+            // that agreed by luck.
+            expect(second).toEqual(first);
+            expect(replays).toEqual([false, true]);
+        });
+        it('scopes a key to the subject that sent it', async () => {
+            const key = `shared-${ulid()}`;
+            const before = await runs();
+            replays = [];
+            const mine = await create('theirs', key, 'a', () => stub);
+            const theirs = await create('theirs', key, 'a', () => otherStub);
+            // Two principals will choose the same key — `1` is a key someone sends. A
+            // lookup that found the other's row would replay a response across a
+            // principal boundary, which is a disclosure and not a convenience.
+            expect(await runs()).toBe(before + 2);
+            expect(theirs).not.toEqual(mine);
+            expect(replays).toEqual([false, false]);
+        });
+        it('refuses a key reused for a different request, and runs nothing', async () => {
+            const key = `reuse-${ulid()}`;
+            await create('reused', key, 'original');
+            const before = await runs();
+            await expect(create('reused', key, 'CHANGED')).rejects.toSatisfy((err) => {
+                return errorCodeOf(err) === 'conflict' && reasonOf(err) === IDEMPOTENCY_REUSED;
+            });
+            // Refused, and refused BEFORE anything ran. Serving the first request's
+            // response would be worse — the client would act on an answer to a question
+            // it did not ask.
+            expect(await runs()).toBe(before);
+        });
+        it('treats a different key as a different request', async () => {
+            const before = await runs();
+            await create('twice', `k-${ulid()}`, 'same input');
+            await create('twice', `k-${ulid()}`, 'same input');
+            // Dedupe is by KEY, never by content: two deliberate identical writes are
+            // two writes, and a client that wanted one sends one key.
+            expect(await runs()).toBe(before + 2);
+        });
+        it('retries — does not replay — a request that failed', async () => {
+            const key = `fail-${ulid()}`;
+            const before = await runs();
+            await expect(stub.invoke('idem/fails', { thingId: 'nope' }, { idempotencyKey: key })).rejects.toThrow();
+            // The handler wrote a row before throwing and the transaction rolled it
+            // back, so the count has not moved — which is also why there is nothing to
+            // replay.
+            expect(await runs()).toBe(before);
+            await expect(stub.invoke('idem/fails', { thingId: 'nope' }, { idempotencyKey: key })).rejects.toThrow();
+            // Executed again rather than replaying the failure. Recording failures would
+            // have meant deciding which are permanent, and a retry after a 500 is the
+            // most ordinary thing a client does.
+            expect(await runs()).toBe(before);
+            // The same key is still free for the request that eventually succeeds: the
+            // first two attempts left no row, so this is a first request.
+            const ok = await stub.invoke('idem/create', { thingId: 'recovered' }, { idempotencyKey: key });
+            expect(ok).toMatchObject({ id: 'recovered' });
+        });
+        it('refuses a replay it cannot answer rather than executing again', async () => {
+            const key = `big-${ulid()}`;
+            const before = await runs();
+            await stub.invoke('idem/big', { thingId: 'large' }, { idempotencyKey: key });
+            expect(await runs()).toBe(before + 1);
+            await expect(stub.invoke('idem/big', { thingId: 'large' }, { idempotencyKey: key })).rejects.toSatisfy((err) => {
+                return errorCodeOf(err) === 'conflict' && reasonOf(err) === IDEMPOTENCY_REPLAY_UNAVAILABLE;
+            });
+            // Fail closed. An error the caller can act on beats the duplicate execution
+            // the key was sent to prevent — and the original did complete, so re-running
+            // is the one answer that is certainly wrong.
+            expect(await runs()).toBe(before + 1);
+        });
+        it('refuses a key on an operation that declared `idempotency: false`', async () => {
+            const before = await runs();
+            await expect(stub.invoke('idem/secret', { thingId: 's1' }, { idempotencyKey: `s-${ulid()}` })).rejects.toThrow(/idempotency: false|cannot honour an Idempotency-Key/i);
+            // Refused rather than ignored: a caller who sent a key and got a 200 would
+            // believe the retry is safe, and here the response was never recorded — the
+            // second request would mint a second secret.
+            expect(await runs()).toBe(before);
+            // The operation itself still works; it is the header it refuses.
+            await expect(stub.invoke('idem/secret', { thingId: 's1' })).resolves.toMatchObject({
+                id: 's1',
+            });
+        });
+        it('refuses a malformed key', async () => {
+            const before = await runs();
+            for (const bad of ['', 'has space', 'x'.repeat(256)]) {
+                await expect(stub.invoke('idem/create', { thingId: 'bad' }, { idempotencyKey: bad })).rejects.toSatisfy((err) => errorCodeOf(err) === 'validation_failed');
+            }
+            expect(await runs()).toBe(before);
+        });
+        it('replays the entity version alongside the body', async () => {
+            const key = `guard-${ulid()}`;
+            const tags = [];
+            const options = {
+                idempotencyKey: key,
+                onEntityVersion: (v) => tags.push(v),
+            };
+            const first = await stub.invoke('idem/create-guarded', { thingId: 'g1' }, options);
+            const second = await stub.invoke('idem/create-guarded', { thingId: 'g1' }, options);
+            expect(second).toEqual(first);
+            // The two seams compose or neither works: a replayed response with no `ETag`
+            // leaves the client holding no validator, so its next conditional write has
+            // nothing to send and the lost-update protection quietly switches off.
+            expect(tags).toHaveLength(2);
+            expect(tags[1]).toBe(tags[0]);
+            expect(tags[0]).not.toBeNull();
+        });
+        it('does not report a version for a replay of an unguarded operation', async () => {
+            const key = `plain-${ulid()}`;
+            const tags = [];
+            const options = {
+                idempotencyKey: key,
+                onEntityVersion: (v) => tags.push(v),
+            };
+            await stub.invoke('idem/create', { thingId: 'p1' }, options);
+            await stub.invoke('idem/create', { thingId: 'p1' }, options);
+            // #129's rule survives the replay path: an operation that declared no
+            // `concurrency` never reports a tag, and a recording must not become the
+            // route by which one appears.
+            expect(tags).toEqual([]);
+        });
+    });
+}
+//# sourceMappingURL=idempotency-suite.js.map

package/dist/idempotency-suite.js.map

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

package/dist/impersonation-suite.d.ts

@@ -0,0 +1,3 @@
+import type { ScopeHostFixture } from './scope-host-suite.js';
+export declare function impersonationContractSuite(adapterName: string, makeFixture: () => Promise<ScopeHostFixture>): void;
+//# sourceMappingURL=impersonation-suite.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"impersonation-suite.d.ts","sourceRoot":"","sources":["../src/impersonation-suite.ts"],"names":[],"mappings":"AA+CA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AA6B9D,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,GAC3C,IAAI,CA2WN"}

package/dist/impersonation-suite.js

@@ -0,0 +1,346 @@
+/**
+ * Contract suite for impersonation — acting as a principal with the real actor
+ * preserved (K-42, #868).
+ *
+ * What it pins is one sentence: **the permission model answers as the
+ * impersonated principal, and every record keeps both actors.** Half of that is
+ * easy to get right and half of it is easy to get subtly wrong, and the ones
+ * that go wrong quietly are the ones this suite is mostly about.
+ *
+ * Four properties, and why each has to be a behavioural test rather than a note:
+ *
+ * 1. **The authority is the impersonated principal's, resolved the ordinary
+ *    way.** A door that grants authority by opening is a door nobody can audit,
+ *    so the assertion is that a session against a principal who holds NOTHING is
+ *    refused exactly as that principal would be — with the denial recorded, and
+ *    recorded against both actors.
+ *
+ * 2. **The stamp cannot be supplied or suppressed by module code.** It is absent
+ *    from `DomainEventInput`, which is a compile-time fact; what a test can show
+ *    is the runtime half — the same operation, invoked through the ordinary door,
+ *    writes a null stamp, and through the impersonation door writes both actors,
+ *    with nothing about the handler differing.
+ *
+ * 3. **Read-only is a mechanism, not a promise.** The test that matters is the
+ *    one where the handler never calls an effecting verb at all: it writes a row
+ *    with plain `ctx.sql.exec`. An adapter that only refused `ctx.emit` passes
+ *    every other case here and commits that row.
+ *
+ * 4. **The time box is checked per invoke, not per stub.** A stub is a
+ *    capability and nothing takes it away, so a session validated only at the
+ *    door expires for everyone except the one caller holding it. `endImpersonation`
+ *    is the same property from the other side.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { permissionKey, platformActorId, principalId, scopeId, tenantId, IMPERSONATION_MAX_MINUTES, } from '@substrat-run/contracts';
+import { ulid } from '@substrat-run/kernel';
+import { impersonationEchoMod, permMod } from './modules.js';
+const PERM_USE = permissionKey.parse('perm:use');
+export function impersonationContractSuite(adapterName, makeFixture) {
+    describe(`impersonation (K-42): ${adapterName}`, () => {
+        let fixture;
+        let host;
+        const t1 = tenantId.parse(ulid());
+        /** Holds `perm:use` through a role — the person support is helping. */
+        const anna = principalId.parse(ulid());
+        /** Holds nothing at all — the lever that proves the door grants no authority. */
+        const nobody = principalId.parse(ulid());
+        const staff = platformActorId.parse(ulid());
+        /**
+         * A FRESH scope per test. These assertions are about what a whole session
+         * left behind — rows, outbox, denials, intents — so a scope carrying another
+         * test's writes would make every count ambiguous.
+         */
+        const freshScope = async () => {
+            const s = scopeId.parse(ulid());
+            await host.provisionScope(staff, { tenantId: t1, scopeId: s, vertical: 'imp-vertical' });
+            await host.admin.activateScope(staff, t1, s);
+            return s;
+        };
+        const openSession = async (scope, overrides = {}) => host.admin.beginImpersonation(staff, {
+            tenantId: t1,
+            scopeId: scope,
+            principal: overrides.principal ?? anna,
+            reason: 'ticket #4182 — the invoice screen is empty',
+            ...(overrides.mode ? { mode: overrides.mode } : {}),
+            ...(overrides.minutes ? { minutes: overrides.minutes } : {}),
+        });
+        beforeAll(async () => {
+            fixture = await makeFixture();
+            host = fixture.host;
+            host.registerModule(permMod);
+            // K-42: the read-back half of the stamp — see the test that reads `imp-echo/seen`.
+            host.registerModule(impersonationEchoMod);
+            await host.admin.createTenant(staff, { id: t1, slug: 'imp-tenant', name: 'Imp Tenant' });
+            await host.admin.grantEntitlement(staff, t1, 'perm');
+            await host.admin.grantEntitlement(staff, t1, 'imp-echo');
+            await host.admin.defineRole(staff, t1, {
+                key: 'imp-user',
+                permissions: [PERM_USE],
+                source: 'vertical',
+            });
+            await host.admin.assignRole(staff, {
+                principalId: anna,
+                roleKey: 'imp-user',
+                node: { tenantId: t1, scopeId: null },
+            });
+        });
+        afterAll(async () => {
+            await fixture.cleanup();
+        });
+        // -- the session record ---------------------------------------------------
+        describe('a session is bounded, reason-carrying and recorded before it is usable', () => {
+            it('records the staff actor, the principal, the reason and an expiry', async () => {
+                const scope = await freshScope();
+                const session = await openSession(scope);
+                expect(session.actor).toBe(staff);
+                expect(session.principal).toBe(anna);
+                expect(session.tenantId).toBe(t1);
+                expect(session.scopeId).toBe(scope);
+                expect(session.reason).toContain('#4182');
+                expect(session.endedAt).toBeNull();
+                expect(session.expiresAt > session.startedAt).toBe(true);
+            });
+            it('is read-only unless the caller asked for otherwise', async () => {
+                const scope = await freshScope();
+                expect((await openSession(scope)).mode).toBe('read-only');
+                expect((await openSession(scope, { mode: 'write' })).mode).toBe('write');
+            });
+            it('refuses a session with no real reason', async () => {
+                const scope = await freshScope();
+                await expect(host.admin.beginImpersonation(staff, {
+                    tenantId: t1,
+                    scopeId: scope,
+                    principal: anna,
+                    reason: 'x',
+                })).rejects.toThrow();
+            });
+            /**
+             * REFUSED, not clamped. A caller silently handed a shorter session than it
+             * asked for believes it has one that is still open, which is the failure a
+             * time box exists to prevent, arrived at through the time box.
+             */
+            it('refuses an ask beyond the ceiling rather than shortening it', async () => {
+                const scope = await freshScope();
+                await expect(openSession(scope, { minutes: IMPERSONATION_MAX_MINUTES + 1 })).rejects.toThrow();
+            });
+            it('refuses a scope that does not exist — a session for nothing is not issued', async () => {
+                await expect(host.admin.beginImpersonation(staff, {
+                    tenantId: t1,
+                    scopeId: scopeId.parse(ulid()),
+                    principal: anna,
+                    reason: 'a scope that was never provisioned',
+                })).rejects.toThrow();
+            });
+            /**
+             * The admin-log entry PRECEDES the session being usable (K-33's failure
+             * ordering). Asserted by reading the log immediately after `begin` and
+             * before any invoke: if the row were written afterwards, or on first use,
+             * this is empty.
+             */
+            it('is in the admin log before a single operation has run', async () => {
+                const scope = await freshScope();
+                const session = await openSession(scope);
+                const log = await host.admin.auditLog(staff, { tenantId: t1, scopeId: scope });
+                const entry = log.find((e) => e.action === 'beginImpersonation');
+                expect(entry).toBeDefined();
+                expect(entry.actor).toBe(staff);
+                // The reason is IN the record — a log saying a session opened but not why
+                // is half a record, and the half an incident review reads is the why.
+                expect(JSON.stringify(entry.after)).toContain(session.reason);
+            });
+            it('reads back through the session log, and closes explicitly', async () => {
+                const scope = await freshScope();
+                const session = await openSession(scope);
+                const open = await host.admin.listImpersonations(staff, { scopeId: scope, active: true });
+                expect(open.map((s) => s.id)).toContain(session.id);
+                const ended = await host.admin.endImpersonation(staff, session.id);
+                expect(ended.endedAt).not.toBeNull();
+                // Idempotent: stopping a stopped session is not an error, and does not
+                // move the moment it stopped.
+                expect((await host.admin.endImpersonation(staff, session.id)).endedAt).toBe(ended.endedAt);
+                const stillOpen = await host.admin.listImpersonations(staff, { scopeId: scope, active: true });
+                expect(stillOpen.map((s) => s.id)).not.toContain(session.id);
+            });
+        });
+        // -- the authority --------------------------------------------------------
+        describe('the permission model answers about the IMPERSONATED principal', () => {
+            it('runs as that principal — `ctx.principal` is never the staff actor', async () => {
+                const scope = await freshScope();
+                const session = await openSession(scope);
+                const stub = await host.getImpersonatedScope(session.id, t1, scope);
+                await expect(stub.invoke('perm/whoami')).resolves.toBe(anna);
+            });
+            /**
+             * The door grants NOTHING. A session against a principal who holds no
+             * permission is refused exactly as that principal is — which is what makes
+             * "see what they see" true rather than "see everything, as them".
+             */
+            it('is refused wherever the impersonated principal would be refused', async () => {
+                const scope = await freshScope();
+                const session = await openSession(scope, { principal: nobody, mode: 'write' });
+                const stub = await host.getImpersonatedScope(session.id, t1, scope);
+                await expect(stub.invoke('perm/write-note', { note: 'nope' })).rejects.toThrow(/permission denied/);
+            });
+            it('records that denial against BOTH actors', async () => {
+                const scope = await freshScope();
+                const session = await openSession(scope, { principal: nobody, mode: 'write' });
+                const stub = await host.getImpersonatedScope(session.id, t1, scope);
+                await expect(stub.invoke('perm/write-note', { note: 'nope' })).rejects.toThrow();
+                // Read as a principal who may: the denial log is scope-local spine.
+                const asAnna = await host.getScope(anna, t1, scope);
+                const denials = await asAnna.invoke('perm/read-denials');
+                expect(denials).toHaveLength(1);
+                expect(JSON.parse(denials[0].actor)).toBe(nobody);
+                expect(denials[0].impersonation).not.toBeNull();
+                expect(JSON.parse(denials[0].impersonation)).toEqual({
+                    session: session.id,
+                    by: staff,
+                });
+            });
+        });
+        // -- the stamp ------------------------------------------------------------
+        describe('every record keeps both actors', () => {
+            it('stamps the emitted event with the session and the staff actor', async () => {
+                const scope = await freshScope();
+                const session = await openSession(scope, { mode: 'write' });
+                const stub = await host.getImpersonatedScope(session.id, t1, scope);
+                await stub.invoke('perm/authorized-emit', { permission: PERM_USE });
+                const asAnna = await host.getScope(anna, t1, scope);
+                const outbox = await asAnna.invoke('perm/read-outbox');
+                const acted = outbox.find((e) => e.type === 'perm.acted');
+                expect(acted).toBeDefined();
+                // The envelope's own `actor` stays the principal — K-34's authorization is
+                // untouched, and the domain fact is still theirs.
+                expect(JSON.parse(acted.authorization)).toEqual([{ permission: PERM_USE }]);
+                expect(JSON.parse(acted.impersonation)).toEqual({ session: session.id, by: staff });
+            });
+            /**
+             * The other half of "module code can neither supply it nor suppress it".
+             * The SAME operation through the ordinary door writes a null stamp — so a
+             * stamp is evidence of a session, never a default an adapter fills in.
+             */
+            it('writes no stamp when nobody is impersonating', async () => {
+                const scope = await freshScope();
+                const stub = await host.getScope(anna, t1, scope);
+                await stub.invoke('perm/authorized-emit', { permission: PERM_USE });
+                const outbox = await stub.invoke('perm/read-outbox');
+                expect(outbox.find((e) => e.type === 'perm.acted').impersonation).toBeNull();
+            });
+            /**
+             * The stamp is written by `ctx.emit` and read back by whatever turns a stored
+             * outbox row into a `DomainEvent`. Those are two different pieces of code in
+             * both adapters, and the tests above only exercise the first: they read the
+             * row with SQL. An adapter that stores the column and drops it on the way out
+             * passes every one of them while handing its consumers — and its executors,
+             * which is how an outbound effect gets made — an event with no administrative
+             * actor on it at all.
+             */
+            it('keeps the stamp on the event a CONSUMER receives, not only on the row', async () => {
+                const scope = await freshScope();
+                const session = await openSession(scope, { mode: 'write' });
+                const stub = await host.getImpersonatedScope(session.id, t1, scope);
+                await stub.invoke('perm/authorized-emit', { permission: PERM_USE });
+                const asAnna = await host.getScope(anna, t1, scope);
+                const seen = await asAnna.invoke('imp-echo/seen');
+                expect(seen).toHaveLength(1);
+                expect(JSON.parse(seen[0].impersonation)).toEqual({ session: session.id, by: staff });
+            });
+            /** And the null half, on the same reasoning as `writes no stamp when nobody is
+             *  impersonating`: a stamp on the delivered event is evidence of a session. */
+            it('delivers no stamp to a consumer when nobody is impersonating', async () => {
+                const scope = await freshScope();
+                const stub = await host.getScope(anna, t1, scope);
+                await stub.invoke('perm/authorized-emit', { permission: PERM_USE });
+                const seen = await stub.invoke('imp-echo/seen');
+                expect(seen).toHaveLength(1);
+                expect(seen[0].impersonation).toBeNull();
+            });
+            it('stamps a platform intent the session raised', async () => {
+                const scope = await freshScope();
+                const session = await openSession(scope, { mode: 'write' });
+                const stub = await host.getImpersonatedScope(session.id, t1, scope);
+                await stub.invoke('perm/request-intent', { kind: 'test.impersonated' });
+                const asAnna = await host.getScope(anna, t1, scope);
+                const intents = await asAnna.invoke('perm/read-intents');
+                expect(intents).toHaveLength(1);
+                // `requested_by` is the principal, as it always was; the staff actor is
+                // the fact a drain operator could not otherwise recover.
+                expect(JSON.parse(intents[0].requested_by)).toBe(anna);
+                expect(JSON.parse(intents[0].impersonation)).toEqual({ session: session.id, by: staff });
+            });
+        });
+        // -- read-only ------------------------------------------------------------
+        describe('a read-only session cannot write, mechanically', () => {
+            it('refuses the effecting verbs by name', async () => {
+                const scope = await freshScope();
+                const session = await openSession(scope);
+                const stub = await host.getImpersonatedScope(session.id, t1, scope);
+                await expect(stub.invoke('perm/authorized-emit', { permission: PERM_USE })).rejects.toThrow(/read-only impersonation session/);
+                await expect(stub.invoke('perm/request-intent', { kind: 'test.refused' })).rejects.toThrow(/read-only impersonation session/);
+            });
+            /**
+             * THE test. The handler calls no effecting verb at all — it writes a row
+             * with plain `ctx.sql.exec`, which is what most of a vertical's code does.
+             * An adapter that enforced read-only by refusing `ctx.emit` alone passes
+             * every other case in this suite and commits this row.
+             */
+            it('discards a row written with plain SQL — the transaction never commits', async () => {
+                const scope = await freshScope();
+                const session = await openSession(scope);
+                const stub = await host.getImpersonatedScope(session.id, t1, scope);
+                // It SUCCEEDS: the operation ran, the read it performed is the answer, and
+                // the caller gets it back. What does not survive is the write.
+                await expect(stub.invoke('perm/write-note', { note: 'support was here' })).resolves.toEqual({
+                    wrote: 'support was here',
+                });
+                const asAnna = await host.getScope(anna, t1, scope);
+                await expect(asAnna.invoke('perm/read-notes')).resolves.toEqual([]);
+            });
+            it('still answers reads', async () => {
+                const scope = await freshScope();
+                const asAnna = await host.getScope(anna, t1, scope);
+                await asAnna.invoke('perm/write-note', { note: 'annas own note' });
+                const session = await openSession(scope);
+                const stub = await host.getImpersonatedScope(session.id, t1, scope);
+                await expect(stub.invoke('perm/read-notes')).resolves.toEqual(['annas own note']);
+            });
+            /** A `write` session is an ordinary operation again — and still stamped. */
+            it('commits under a write session', async () => {
+                const scope = await freshScope();
+                const session = await openSession(scope, { mode: 'write' });
+                const stub = await host.getImpersonatedScope(session.id, t1, scope);
+                await stub.invoke('perm/write-note', { note: 'a fix, on purpose' });
+                const asAnna = await host.getScope(anna, t1, scope);
+                await expect(asAnna.invoke('perm/read-notes')).resolves.toEqual([
+                    'a fix, on purpose',
+                ]);
+            });
+        });
+        // -- the time box ---------------------------------------------------------
+        describe('the session is checked on every invoke, not once at the door', () => {
+            it('refuses a stub minted before the session was ended', async () => {
+                const scope = await freshScope();
+                const session = await openSession(scope, { mode: 'write' });
+                const stub = await host.getImpersonatedScope(session.id, t1, scope);
+                // It works…
+                await expect(stub.invoke('perm/whoami')).resolves.toBe(anna);
+                await host.admin.endImpersonation(staff, session.id);
+                // …and then it does not. Nothing took the stub away; the session is what
+                // was withdrawn, and that has to be enough.
+                await expect(stub.invoke('perm/whoami')).rejects.toThrow(/was ended/);
+            });
+            it('refuses a session pointed at another scope', async () => {
+                const scope = await freshScope();
+                const other = await freshScope();
+                const session = await openSession(scope);
+                await expect(host.getImpersonatedScope(session.id, t1, other)).rejects.toThrow(/is for \(/);
+            });
+            it('refuses a session nobody opened', async () => {
+                const scope = await freshScope();
+                await expect(host.getImpersonatedScope(ulid(), t1, scope)).rejects.toThrow(/unknown impersonation session/);
+            });
+        });
+    });
+}
+//# sourceMappingURL=impersonation-suite.js.map