@substrat-run/contract-tests 0.136.0 → 0.138.0

package/dist/scope-host-suite.js

@@ -1,8 +1,8 @@
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
 import { connectorCalls, connectorTestFetch, resetConnectorCalls } from './connector-fixture.js';
-import { connectionId, dataSubjectId, domainEvent, errorCodeOf, eventId, instant, moduleManifest, orgId, AUTO_ADMISSION_NOTE, permissionKey, platformActorId, platformRequestId, principalId, scopeId, tenantId, SCOPE_QUERY_ROW_MAX, KERNEL_AUTHORED_EVENT_TYPES, SWEEP_RUNS_KIND, SCOPE_TABLE_PAGE_MAX, } from '@substrat-run/contracts';
+import { connectionId, dataSubjectId, domainEvent, errorCodeOf, moduleId, SCOPE_GATE_REASONS, eventId, instant, moduleManifest, orgId, AUTO_ADMISSION_NOTE, permissionKey, platformActorId, platformRequestId, principalId, scopeId, tenantId, SCOPE_QUERY_ROW_MAX, KERNEL_AUTHORED_EVENT_TYPES, SWEEP_RUNS_KIND, SCOPE_TABLE_PAGE_MAX, } from '@substrat-run/contracts';
 import { INERT_SCOPE_REASON, isSearchIndexTable, platformIntentFailureMessage, REDACTED_DELIVERY_NOTE, REDACTED_FAILURE_NOTE, REDACTED_INTENT_MARKER, runPlatformSweep, startPlatformSweeper, createUlid, ulid, } from '@substrat-run/kernel';
-import { billedMod, contractTestBareOps, contractTestInitialModules, gateModManifest, lateMod, testModManifest, victimModManifest, } from './modules.js';
+import { billedMod, contractTestBareOps, contractTestInitialModules, gateModManifest, lateMod, TEST_LIFECYCLE, testModManifest, victimModManifest, } from './modules.js';
 /**
  * Assert a refusal by the CODE it declared, not by the sentence it happens to carry
  * (#113 phase 5).
@@ -133,10 +133,11 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             await expect(host.provisionScope(staff, { tenantId: t1, scopeId: s1, jurisdiction: 'eu' })).resolves.toBeUndefined();
         });
         it('refuses to provision a scope under a tenant with no record (§4.1)', async () => {
-            await expect(host.provisionScope(staff, {
+            // `conflict`, not `not_found`: POST /scopes exists, and what is missing is its precondition.
+            await expectRefusal(host.provisionScope(staff, {
                 tenantId: tenantId.parse(ulid()),
                 scopeId: scopeId.parse(ulid()),
-            })).rejects.toThrow(/unknown tenant/);
+            }), 'conflict');
         });
         it('fails closed on a mismatched (tenantId, scopeId) pair (K-3)', async () => {
             await expect(host.getScope(alice, t2, s1)).rejects.toThrow();
@@ -1815,15 +1816,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             await stub.invoke('test/move', { entityId: 'l1' });
             const flow = await host.admin.lifecycleFlow(staff, t1, s1, {
                 entityType: 'test-lifecycle',
-                lifecycle: {
-                    field: 'state',
-                    initial: 'draft',
-                    states: {
-                        draft: { on: { 'test/move': 'live' } },
-                        live: { on: { 'test/move': 'done' } },
-                        done: { terminal: true },
-                    },
-                },
+                lifecycle: TEST_LIFECYCLE,
                 since,
                 until: new Date(Date.now() + 60_000).toISOString(),
             });
@@ -1833,6 +1826,130 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             expect(flow.observation).toMatchObject({ entities: 1, events: 3, inferred: 1, complete: true });
             expect(flow.totals.finished).toBe(1);
         });
+        describe('lifecycleFlow on both adapters (#1744)', () => {
+            let stub;
+            beforeAll(async () => {
+                stub = await host.getScope(alice, t1, s1);
+            });
+            /** One move, as its own call, returning the instant the outbox stamped on it. */
+            const move = async (entityId, state) => {
+                const invocationId = ulid();
+                await stub.invoke('test/move', { entityId, state }, { invocationId });
+                const { events } = await host.admin.invocationEvents(staff, t1, s1, { invocationId });
+                expect(events).toHaveLength(1);
+                const at = events[0].occurredAt;
+                // The boundaries below are exact instants, so no two moves may share one.
+                while (Date.now() <= Date.parse(at))
+                    await new Promise((r) => setTimeout(r, 2));
+                return at;
+            };
+            const edge = (flow, from, to) => flow.edges.find((e) => e.from === from && e.to === to && e.declared);
+            const state = (flow, name) => flow.states.find((s) => s.state === name);
+            it('counts an event at `since` and not one at `until`: the window is half-open', async () => {
+                const a = await move('w1', 'draft');
+                const b = await move('w1', 'live');
+                const c = await move('w1', 'done');
+                expect(a < b && b < c).toBe(true);
+                const read = (since, until) => host.admin.lifecycleFlow(staff, t1, s1, { entityType: 'test-lifecycle', lifecycle: TEST_LIFECYCLE, since, until });
+                // [b, c): the move AT `since` is in; the move AT `until` is not replayed at all,
+                // so "now" is still `live` — and the declared edge it would have taken reads 0.
+                const mid = await read(b, c);
+                expect(edge(mid, 'draft', 'live').count).toBe(1);
+                expect(edge(mid, 'live', 'done').count).toBe(0);
+                expect(state(mid, 'live').current).toBe(1);
+                // [a, b): history before `since` is replayed, never counted, and `b` is outside.
+                const before = await read(a, b);
+                expect(edge(before, 'draft', 'live').count).toBe(0);
+                expect(state(before, 'draft').current).toBeGreaterThanOrEqual(1);
+                // The twin: one millisecond past `c` and the same move is counted.
+                const after = await read(b, new Date(Date.parse(c) + 1).toISOString());
+                expect(edge(after, 'draft', 'live').count).toBe(1);
+                expect(edge(after, 'live', 'done').count).toBe(1);
+                expect(state(after, 'live').current).toBe(0);
+            });
+            it('lists a move the declaration does not have apart from the declared edges', async () => {
+                const since = await move('u1', 'draft');
+                await move('u1', 'done'); // `test/move` from draft is declared to lead to `live`
+                await move('u2', 'draft');
+                await move('u2', 'limbo'); // a state the declaration does not have at all
+                const flow = await host.admin.lifecycleFlow(staff, t1, s1, {
+                    entityType: 'test-lifecycle',
+                    lifecycle: TEST_LIFECYCLE,
+                    since,
+                    until: new Date(Date.now() + 60_000).toISOString(),
+                });
+                const undeclared = flow.edges.filter((e) => !e.declared);
+                expect(undeclared).toHaveLength(2);
+                expect(undeclared).toEqual(expect.arrayContaining([
+                    expect.objectContaining({ from: 'draft', to: 'done', operation: 'test/move', count: 1, seenLate: false }),
+                    expect.objectContaining({ from: 'draft', to: 'limbo', operation: 'test/move', count: 1, seenLate: false }),
+                ]));
+                // Not folded into the declared edge out of the same state under the same operation.
+                expect(edge(flow, 'draft', 'live').count).toBe(0);
+                expect(state(flow, 'limbo')).toMatchObject({ declared: false, current: 1 });
+            });
+            it("answers only for the tenant's own scope: a mismatched pair is refused, another tenant's scope sees none of it", async () => {
+                const since = await move('i1', 'draft');
+                const window = { entityType: 'test-lifecycle', lifecycle: TEST_LIFECYCLE, since, until: new Date(Date.now() + 60_000).toISOString() };
+                // The positive twin: t1's own pair sees the instance just started.
+                expect((await host.admin.lifecycleFlow(staff, t1, s1, window)).totals.started).toBe(1);
+                // K-3: never another tenant's outbox, and never an empty answer for one either.
+                await expect(host.admin.lifecycleFlow(staff, t2, s1, window)).rejects.toThrow();
+                await expect(host.admin.lifecycleFlow(staff, t1, s2, window)).rejects.toThrow();
+                // t2's own scope answers, from its own outbox — in which t1 emitted nothing.
+                const own = await host.admin.lifecycleFlow(staff, t2, s2, window);
+                expect(own.observation).toMatchObject({ entities: 0, events: 0, complete: true });
+                expect(own.edges.every((e) => e.count === 0)).toBe(true);
+                // K-24: the read is recorded against the actor.
+                expect((await host.admin.accessLog(staff, { tenantId: t1, method: 'lifecycleFlow' })).length).toBeGreaterThan(0);
+            });
+        });
+        describe('operationSeries on both adapters (#1750)', () => {
+            // `readOperationSeries`'s own suite pins the counting over a hand-built outbox; this
+            // proves the wiring — real emits, with real ids, read back through the platform verb.
+            // On the Durable Object it is also the proof that `strftime`, `json_each` and the
+            // primary-key seek run in workerd's SQLite.
+            const MOVES = [{ entityType: 'test-lifecycle', operation: 'test/move' }];
+            /** A window from the current whole second, a minute wide, in one-minute buckets. */
+            const window = () => {
+                const since = Math.floor(Date.now() / 1000) * 1000;
+                return { moves: MOVES, since: new Date(since).toISOString(), until: new Date(since + 60_000).toISOString(), bucketMinutes: 1 };
+            };
+            const total = (r) => r.series[0].total;
+            it('counts every call that made the move, inside the window', async () => {
+                const stub = await host.getScope(alice, t1, s1);
+                const w = window();
+                const earlier = { ...w, since: new Date(Date.parse(w.since) - 120_000).toISOString(), until: w.since };
+                const before = total(await host.admin.operationSeries(staff, t1, s1, w));
+                const beforeEarlier = total(await host.admin.operationSeries(staff, t1, s1, earlier));
+                await stub.invoke('test/move', { entityId: 'v1', state: 'draft' });
+                await stub.invoke('test/move', { entityId: 'v1', state: 'live' });
+                await stub.invoke('test/move', { entityId: 'v2', state: 'draft' });
+                const after = await host.admin.operationSeries(staff, t1, s1, w);
+                expect(total(after)).toBe(before + 3);
+                expect(after.series[0].buckets.every((b) => Date.parse(b.start) >= Date.parse(w.since))).toBe(true);
+                // The twin: a window that closed before the calls ran counts none of them. Compared
+                // with itself, not with zero: earlier cases in this scope may have moved inside it.
+                expect(total(await host.admin.operationSeries(staff, t1, s1, earlier))).toBe(beforeEarlier);
+            });
+            it("answers only for the tenant's own scope: a mismatched pair is refused, another tenant's scope counts none of it", async () => {
+                const stub = await host.getScope(alice, t1, s1);
+                const w = window();
+                await stub.invoke('test/move', { entityId: 'v3', state: 'draft' });
+                // The positive twin: t1's own pair sees the move.
+                expect(total(await host.admin.operationSeries(staff, t1, s1, w))).toBeGreaterThanOrEqual(1);
+                // K-3: never another tenant's outbox, and never an empty answer for one either.
+                await expect(host.admin.operationSeries(staff, t2, s1, w)).rejects.toThrow();
+                await expect(host.admin.operationSeries(staff, t1, s2, w)).rejects.toThrow();
+                // t2's own scope answers from its own outbox, in which t1 moved nothing.
+                expect(total(await host.admin.operationSeries(staff, t2, s2, w))).toBe(0);
+                // K-24: the read is recorded against the actor, with the window and no operation names.
+                const rows = await host.admin.accessLog(staff, { tenantId: t1, method: 'operationSeries' });
+                expect(rows.length).toBeGreaterThan(0);
+                expect(rows[0].params).toContain('test-lifecycle');
+                expect(rows[0].params).not.toContain('test/move');
+            });
+        });
         it('records a refused transition after the rollback, and the replay counts it (#1745)', async () => {
             // The operation throws the platform's conflict, so its transaction rolls back — the
             // refusal is the one write that must survive it, on both adapters.
@@ -1842,11 +1959,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             await expect(stub.invoke('test/refuse', { entityId: 'r1', from: 'done' })).rejects.toThrow(/invalid transition/);
             const flow = await host.admin.lifecycleFlow(staff, t1, s1, {
                 entityType: 'test-lifecycle',
-                lifecycle: {
-                    field: 'state',
-                    initial: 'draft',
-                    states: { draft: { on: { 'test/move': 'live' } }, live: { on: { 'test/move': 'done' } }, done: { terminal: true } },
-                },
+                lifecycle: TEST_LIFECYCLE,
                 since,
                 until: new Date(Date.now() + 60_000).toISOString(),
             });
@@ -1878,6 +1991,11 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                 drainedAt: null,
             });
             expect(rows[0].decodeError).toBeUndefined();
+            expect(rows[0].guard).toBeNull();
+            // A move the lifecycle allows records nothing.
+            const allowed = ulid();
+            await stub.invoke('test/move', { entityId: 'r2-ok', state: 'draft' }, { invocationId: allowed });
+            expect(await host.admin.listRefusals(staff, t1, s1, { invocationId: allowed })).toEqual([]);
             // The row survived the operation's rollback — and the operation itself left nothing
             // behind in the outbox for that call.
             expect((await host.admin.invocationEvents(staff, t1, s1, { invocationId: call })).events).toEqual([]);
@@ -1893,6 +2011,13 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             const logged = await host.admin.accessLog(staff, { tenantId: t1, method: 'listRefusals' });
             expect(logged.length).toBeGreaterThan(0);
             await expect(host.admin.listRefusals(staff, t2, s1)).rejects.toThrow();
+            // A record whose status column holds arbitrary text: the refusal is recorded, with the
+            // state as the marker — the lifecycle never vouched for that text, so it is not kept.
+            const undeclared = ulid();
+            await expect(stub.invoke('test/refuse', { entityId: 'r2-odd', from: 'call ada@example.com' }, { invocationId: undeclared })).rejects.toThrow(/invalid transition/);
+            const [oddRow] = await host.admin.listRefusals(staff, t1, s1, { invocationId: undeclared });
+            expect(oddRow).toMatchObject({ kind: 'transition', fromState: 'undeclared', entityId: 'r2-odd', operation: 'test/move' });
+            expect(JSON.stringify(oddRow)).not.toMatch(/ada@example\.com|call ada/);
         });
         // -- scope data introspection: the §5.4 admin-query RPC --------------------
         //
@@ -1927,7 +2052,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                 expect(page.limit).toBe(1);
             });
             it('rejects an unknown table', async () => {
-                await expect(host.admin.readScopeTable(staff, t1, s1, { table: 'no_such_table', limit: 50, offset: 0 })).rejects.toThrow(/unknown table/);
+                await expectRefusal(host.admin.readScopeTable(staff, t1, s1, { table: 'no_such_table', limit: 50, offset: 0 }), 'not_found');
             });
             it('refuses a page bound SQLite would misread, and still clamps to the ceiling (#1632)', async () => {
                 // The clamp passed NaN straight through to LIMIT / OFFSET. Refused instead, with the
@@ -2026,9 +2151,9 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                     `WITH x AS (SELECT v FROM marker) INSERT INTO marker (v) SELECT v FROM x`,
                 ];
                 for (const sql of writes) {
-                    // The message prefix is CONTRACT: the transport maps /read-only console/
-                    // to a 400, so both adapters must refuse with it (errors.ts).
-                    await expect(host.admin.queryScope(staff, t1, s1, { sql })).rejects.toThrow(/read-only console/);
+                    // The code is what the transport renders (a 400). The prefix stays contract too:
+                    // a CP-less vertical's console route and the dashboard still recognise it by it.
+                    await expectRefusal(host.admin.queryScope(staff, t1, s1, { sql }), 'validation_failed', /read-only console/);
                 }
                 // No write happened and nothing was forged: the marker rows are intact.
                 const after = await host.admin.queryScope(staff, t1, s1, {
@@ -3681,7 +3806,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                 await expect(host.admin.exportScope(staff, t1, snapId)).rejects.toThrow();
             });
             it('refuses to delete a primary scope (forkedFrom is null)', async () => {
-                await expect(host.deleteSnapshot(staff, t1, s1)).rejects.toThrow(/not a fork/);
+                await expectRefusal(host.deleteSnapshot(staff, t1, s1), 'forbidden', /not a fork/);
                 // Still there, still readable.
                 expect((await host.admin.getScopeRecord(staff, t1, s1))?.id).toBe(s1);
             });
@@ -5370,7 +5495,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
         });
         it('refuses a promotion that changes permissions until it is acknowledged', async () => {
             const v2 = await publish('2.1.0', { perm: 'pB', mig: 'gA' }); // permissions moved
-            await expect(host.admin.promoteVersion(staff, 'callout', 'prod', v2)).rejects.toThrow(/changes the permission surface/);
+            await expectRefusal(host.admin.promoteVersion(staff, 'callout', 'prod', v2), 'conflict', /changes the permission surface/);
             // Still pointing at the old one — a refused promotion changes nothing.
             const before = await host.admin.listChannels(staff, 'callout');
             expect(before.find((c) => c.channel === 'prod')?.versionId).not.toBe(v2);
@@ -5380,7 +5505,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
         });
         it('refuses a promotion that changes migrations until it is acknowledged', async () => {
             const v3 = await publish('2.2.0', { perm: 'pB', mig: 'gB' }); // migrations moved
-            await expect(host.admin.promoteVersion(staff, 'callout', 'prod', v3)).rejects.toThrow(/changes migrations/);
+            await expectRefusal(host.admin.promoteVersion(staff, 'callout', 'prod', v3), 'conflict', /changes migrations/);
             await host.admin.promoteVersion(staff, 'callout', 'prod', v3, { migrationChange: true });
             expect((await host.admin.listChannels(staff, 'callout')).find((c) => c.channel === 'prod')
                 ?.versionId).toBe(v3);
@@ -5595,7 +5720,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             const sc = scopeId.parse(ulid());
             await host.admin.createTenant(staff, { id: t, slug: `t-${t.toLowerCase()}`, name: 'T' });
             await host.provisionScope(staff, { tenantId: t, scopeId: sc, jurisdiction: 'eu' });
-            await expect(host.getScope(alice, t, sc)).rejects.toThrow(/not active/);
+            await expectRefusal(host.getScope(alice, t, sc), 'conflict', /not active/);
             await host.admin.activateScope(staff, t, sc);
             await expect(host.getScope(alice, t, sc)).resolves.toBeDefined();
         });
@@ -5712,7 +5837,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                 canonical: true,
             });
             await bind(holder);
-            await expect(bind(claimant)).rejects.toThrow(/already bound to another scope/);
+            await expectRefusal(bind(claimant), 'conflict', /already bound to another scope/);
             await host.admin.archiveScope(staff, t1, holder);
             await bind(claimant); // the holder released the name
             await host.admin.setHostnameStatus(staff, 'reclaim.example.com', 'active');
@@ -5827,14 +5952,14 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
         it('refuses to move a hostname to another scope', async () => {
             // A hostname routes to exactly one place. Silently rebinding would move
             // another tenant's traffic.
-            await expect(host.admin.bindHostname(staff, {
+            await expectRefusal(host.admin.bindHostname(staff, {
                 hostname: 'acme.example.com',
                 tenantId: t2,
                 scopeId: s2,
                 surface: 'app',
                 region: null,
                 canonical: false,
-            })).rejects.toThrow(/already bound to another scope/);
+            }), 'conflict', /already bound to another scope/);
         });
         it('carries the region, which is what Regional Services is set from', async () => {
             // Residency is per hostname, which is why it lives here rather than in a
@@ -5917,6 +6042,77 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             const stub = await host.getScope(alice, t1, s1);
             await expect(stub.invoke('guarded/rows')).resolves.toEqual(['go']);
         });
+        it('records a guard refusal once, after the rollback, with no message or input on the row (#1745)', async () => {
+            const stub = await host.getScope(alice, t1, s1);
+            const rowsBefore = await stub.invoke('guarded/rows');
+            const call = ulid();
+            const note = 'call me at ada@example.com';
+            await expect(stub.invoke('guarded/open', { id: 'g-refused', note }, { invocationId: call })).rejects.toThrow(/gate closed/);
+            // The caller's answer is the predicate's own 409, unchanged by being recorded.
+            await expect(stub.invoke('guarded/open', { id: 'g-refused', note })).rejects.toMatchObject({
+                code: 'conflict',
+            });
+            const rows = await host.admin.listRefusals(staff, t1, s1, { invocationId: call });
+            expect(rows).toHaveLength(1);
+            expect(rows[0]).toMatchObject({
+                kind: 'guard',
+                guard: 'gate/must-be-open',
+                reason: 'gate_closed',
+                actor: alice,
+                actorKind: 'principal',
+                tenantId: t1,
+                scopeId: s1,
+                entityType: 'guarded-thing',
+                entityId: 'g-refused',
+                // A guard stands before an operation; the kernel does not know the record's state.
+                fromState: null,
+                attemptedState: null,
+                operation: 'guarded/open',
+                invokedOperation: 'guarded/open',
+                impersonation: null,
+                invocationId: call,
+                drainedAt: null,
+            });
+            expect(rows[0].decodeError).toBeUndefined();
+            // Keys and vocabulary only: neither the input nor the message the caller saw.
+            expect(JSON.stringify(rows[0])).not.toMatch(/ada@example\.com|gate closed|call me/);
+            // Both attempts recorded, each once, and as guards.
+            expect(await host.admin.listRefusals(staff, t1, s1, { kind: 'guard', entityId: 'g-refused' })).toHaveLength(2);
+            expect(await host.admin.listRefusals(staff, t1, s1, { kind: 'transition', entityId: 'g-refused' })).toEqual([]);
+            // The wire takes any non-empty string as a conflict's reason, so a predicate can put
+            // request text there; the row keeps a code or the fixed marker, never the text.
+            const leaked = ulid();
+            await expect(stub.invoke('guarded/open', { id: 'g-leak', reason: 'call ada@example.com' }, { invocationId: leaked })).rejects.toThrow(/gate closed/);
+            const [leakRow] = await host.admin.listRefusals(staff, t1, s1, { invocationId: leaked });
+            expect(leakRow).toMatchObject({ kind: 'guard', reason: 'unrecognized', entityId: 'g-leak' });
+            expect(JSON.stringify(leakRow)).not.toMatch(/ada@example\.com|call ada/);
+            // The same for the record's type, which a predicate names from whatever it was handed:
+            // kept only when spelled as an entity type. The id stays — it is the record's key.
+            const typed = ulid();
+            await expect(stub.invoke('guarded/open', { id: 'g-typed', entityType: 'ada@example.com' }, { invocationId: typed })).rejects.toThrow(/gate closed/);
+            const [typedRow] = await host.admin.listRefusals(staff, t1, s1, { invocationId: typed });
+            expect(typedRow).toMatchObject({ kind: 'guard', entityType: 'undeclared', entityId: 'g-typed' });
+            expect(JSON.stringify(typedRow)).not.toMatch(/ada@example\.com/);
+            // The rollback took the predicate's own write with it, and the handler never ran —
+            // the refusal row is the one write that survived.
+            expect(await stub.invoke('guarded/rows')).toEqual(rowsBefore);
+        });
+        it('records nothing for a guard that passes, or one that throws something other than a refusal (#1745)', async () => {
+            const stub = await host.getScope(alice, t1, s1);
+            const rowsBefore = await stub.invoke('guarded/rows');
+            const passed = ulid();
+            await stub.invoke('guarded/open', { id: 'g-open', open: true }, { invocationId: passed });
+            expect(await host.admin.listRefusals(staff, t1, s1, { invocationId: passed })).toEqual([]);
+            expect(await stub.invoke('guarded/rows')).toEqual([...rowsBefore, 'gate saw g-open', 'opened g-open']);
+            // A bare Error is a guard failing, not a guard refusing: blocked, never recorded.
+            const failed = ulid();
+            await expect(stub.invoke('guarded/act', { flag: 'stop' }, { invocationId: failed })).rejects.toThrow(/expected flag/);
+            expect(await host.admin.listRefusals(staff, t1, s1, { invocationId: failed })).toEqual([]);
+            // And a guard whose predicate is missing fails closed, also unrecorded.
+            const orphan = ulid();
+            await expect(stub.invoke('guarded/orphan', {}, { invocationId: orphan })).rejects.toThrow(/unknown guard predicate/);
+            expect(await host.admin.listRefusals(staff, t1, s1, { invocationId: orphan })).toEqual([]);
+        });
         // -- operation withdrawal (K-17) -----------------------------------------
         it('withdraws a default binding regardless of registration order (K-17)', async () => {
             const stub = await host.getScope(alice, t1, s1);
@@ -6673,7 +6869,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             await host.admin.activateScope(staff, t3, s3);
             await expect(host.getScope(alice, t3, s3)).resolves.toBeDefined();
             await host.admin.setTenantStatus(staff, t3, 'suspended');
-            await expect(host.getScope(alice, t3, s3)).rejects.toThrow(/not active/);
+            await expectRefusal(host.getScope(alice, t3, s3), 'conflict', /tenant not active/);
             await host.admin.setTenantStatus(staff, t3, 'active');
             await expect(host.getScope(alice, t3, s3)).resolves.toBeDefined();
         });
@@ -6684,7 +6880,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             expect(suspend.before.status).toBe('active');
         });
         it('rejects a status transition on an unknown tenant', async () => {
-            await expect(host.admin.setTenantStatus(staff, tenantId.parse(ulid()), 'suspended')).rejects.toThrow(/unknown tenant/);
+            await expectRefusal(host.admin.setTenantStatus(staff, tenantId.parse(ulid()), 'suspended'), 'not_found');
         });
         it('renames a tenant display name — audited with before/after, slug untouched', async () => {
             const before = (await host.admin.getTenant(staff, t3));
@@ -6699,13 +6895,13 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             // Renaming to the current name is a no-op and leaves no audit row.
             await host.admin.setTenantName(staff, t3, 'Renamed Co');
             expect((await host.admin.auditLog(staff, { tenantId: t3 })).filter((r) => r.action === 'setTenantName')).toHaveLength(1);
-            await expect(host.admin.setTenantName(staff, tenantId.parse(ulid()), 'Ghost')).rejects.toThrow(/unknown tenant/);
+            await expectRefusal(host.admin.setTenantName(staff, tenantId.parse(ulid()), 'Ghost'), 'not_found');
         });
         // -- scope lifecycle (control-plane.md §4.2) ------------------------------
         it('suspend/unsuspend a scope gates getScope for that scope alone (§4.2)', async () => {
             // s3 is active (reactivated above). Suspending it fails closed…
             await host.admin.suspendScope(staff, t3, s3);
-            await expect(host.getScope(alice, t3, s3)).rejects.toThrow(/scope not active/);
+            await expectRefusal(host.getScope(alice, t3, s3), 'conflict', /scope not active/);
             // …while a sibling scope under the same tenant is untouched.
             const sibling = scopeId.parse(ulid());
             await host.provisionScope(staff, { tenantId: t3, scopeId: sibling, jurisdiction: 'eu' });
@@ -6717,7 +6913,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
         });
         it('archive then un-archive is an explicit audited restore (§4.2)', async () => {
             await host.admin.archiveScope(staff, t3, s3);
-            await expect(host.getScope(alice, t3, s3)).rejects.toThrow(/scope not active/);
+            await expectRefusal(host.getScope(alice, t3, s3), 'conflict', /scope not active/);
             await host.admin.unarchiveScope(staff, t3, s3);
             await expect(host.getScope(alice, t3, s3)).resolves.toBeDefined();
             const transitions = (await host.admin.auditLog(staff, { tenantId: t3 })).filter((r) => r.action === 'archiveScope' || r.action === 'unarchiveScope');
@@ -6729,7 +6925,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
         });
         it('rejects an illegal scope transition, fail closed (§4.2)', async () => {
             // s3 is active — you cannot un-archive an active scope.
-            await expect(host.admin.unarchiveScope(staff, t3, s3)).rejects.toThrow(/illegal scope transition/);
+            await expectRefusal(host.admin.unarchiveScope(staff, t3, s3), 'conflict', /illegal scope transition/);
         });
         // -- reap: the terminal storage wipe (control-plane.md §4.4) ---------------
         it('archive stamps archivedAt; unarchive clears it (§4.4)', async () => {
@@ -6754,7 +6950,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             await host.provisionScope(staff, { tenantId: t3, scopeId: s, slug: 'reap-me', jurisdiction: 'eu' });
             await host.admin.activateScope(staff, t3, s);
             // Reap refuses a live (active) scope — only archived may be reaped.
-            await expect(host.admin.reapScope(staff, t3, s)).rejects.toThrow(/not archived/);
+            await expectRefusal(host.admin.reapScope(staff, t3, s), 'conflict', /not archived/);
             await host.admin.archiveScope(staff, t3, s);
             await host.admin.reapScope(staff, t3, s);
             // The directory row SURVIVES as a tombstone, now `reaped`.
@@ -6768,10 +6964,10 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             // "this scope has no events" where the truth is "this scope is gone".
             await expect(host.admin.facetEvents(staff, t3, s, { groupBy: { kind: 'type' } })).rejects.toThrow(/reaped/);
             await expect(host.admin.entityHistory(staff, t3, s, { entityType: 'test-thing', entityId: 'x1' })).rejects.toThrow(/reaped/);
-            await expect(host.admin.listScopeTables(staff, t3, s)).rejects.toThrow(/reaped/);
+            await expectRefusal(host.admin.listScopeTables(staff, t3, s), 'conflict', /reaped/);
             // #1524: a size read is refused BEFORE it reaches the storage. Addressing a reaped
             // DO to ask its size would recreate an empty database and report that as the scope.
-            await expect(host.admin.scopeDatabaseSize(staff, t3, s)).rejects.toThrow(/reaped/);
+            await expectRefusal(host.admin.scopeDatabaseSize(staff, t3, s), 'conflict', /reaped/);
             // Audited as reapScope against the right scope + actor.
             const reapEntry = (await host.admin.auditLog(staff, { tenantId: t3 })).find((r) => r.action === 'reapScope' && r.scopeId === s);
             expect(reapEntry?.actor).toBe(staff);
@@ -6806,8 +7002,8 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             await host.admin.activateScope(staff, t3, fresh);
             await expect(host.getScope(alice, t3, fresh)).resolves.toBeDefined();
             // Terminal: a reaped scope cannot be unarchived (bytes are gone) or reaped again.
-            await expect(host.admin.unarchiveScope(staff, t3, s)).rejects.toThrow(/illegal scope transition/);
-            await expect(host.admin.reapScope(staff, t3, s)).rejects.toThrow(/not archived/);
+            await expectRefusal(host.admin.unarchiveScope(staff, t3, s), 'conflict', /illegal scope transition/);
+            await expectRefusal(host.admin.reapScope(staff, t3, s), 'conflict', /not archived/);
         });
         it('reap refuses while a hostname still resolves; unbind first, then it reaps (§4.4)', async () => {
             // The regression this guards: a console `archiveScope` (unlike the dashboard delete
@@ -6828,7 +7024,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             // Archive alone (the console path) leaves the hostname bound…
             await host.admin.archiveScope(staff, t3, s);
             // …so reap refuses, naming the offending hostname, and the row survives untouched.
-            await expect(host.admin.reapScope(staff, t3, s)).rejects.toThrow(/still resolves hostname 'still-serving\.example\.com'/);
+            await expectRefusal(host.admin.reapScope(staff, t3, s), 'conflict', /still resolves hostname 'still-serving\.example\.com'/);
             expect((await host.admin.getScopeRecord(staff, t3, s)).status).toBe('archived');
             // Unbinding is the visible, reversible step that clears the wall…
             await host.admin.unbindHostname(staff, 'still-serving.example.com');
@@ -6849,7 +7045,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             const deleting = (await host.admin.getTenant(staff, t));
             expect(deleting.status).toBe('deleting');
             expect(deleting.deletingAt).not.toBeNull();
-            await expect(host.getScope(alice, t, s)).rejects.toThrow(/not active/);
+            await expectRefusal(host.getScope(alice, t, s), 'conflict', /tenant not active/);
             // Un-delete (→ active) is a full restore and clears deletingAt.
             await host.admin.setTenantStatus(staff, t, 'active');
             const restored = (await host.admin.getTenant(staff, t));
@@ -6875,7 +7071,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             expect((await host.admin.listOrgs(staff, t)).filter((o) => o.id === org)).toHaveLength(1);
             expect((await host.admin.resolveIdentity(t, `oidc:reap-${t.toLowerCase()}`, 'x1'))?.principal).toBe(person);
             // Reap only follows the reversible delete state.
-            await expect(host.admin.reapTenant(staff, t)).rejects.toThrow(/not deleting/);
+            await expectRefusal(host.admin.reapTenant(staff, t), 'conflict', /not deleting/);
             // The caller reaps the scope first (the sweep/route orchestrates this above the
             // kernel); reapTenant itself is directory-side only.
             await host.admin.setTenantStatus(staff, t, 'deleting');
@@ -6900,11 +7096,72 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             expect(reapEntry.before.status).toBe('deleting');
             expect(reapEntry.after.status).toBe('reaped');
             // Terminal: `reaped` is unreachable via setTenantStatus and reapTenant refuses it.
-            await expect(host.admin.setTenantStatus(staff, t, 'reaped')).rejects.toThrow(/cannot be set to 'reaped'/);
-            await expect(host.admin.reapTenant(staff, t)).rejects.toThrow(/not deleting/);
+            await expectRefusal(host.admin.setTenantStatus(staff, t, 'reaped'), 'validation_failed', /cannot be set to 'reaped'/);
+            await expectRefusal(host.admin.reapTenant(staff, t), 'conflict', /not deleting/);
         });
         it('rejects reapTenant on an unknown tenant', async () => {
-            await expect(host.admin.reapTenant(staff, tenantId.parse(ulid()))).rejects.toThrow(/unknown tenant/);
+            await expectRefusal(host.admin.reapTenant(staff, tenantId.parse(ulid())), 'not_found');
+        });
+        // #113: the last directory refusals the control plane matched by message, each typed now.
+        // Asserted on the code — the thing a transport renders — with its positive twin beside it.
+        it('marks the scope gate\'s refusal as the gate\'s, so a public edge can answer it neutrally (#113)', async () => {
+            const t = tenantId.parse(ulid());
+            const sc = scopeId.parse(ulid());
+            await host.admin.createTenant(staff, { id: t, slug: `gate-${t.toLowerCase()}`, name: 'Gate Co' });
+            await host.provisionScope(staff, { tenantId: t, scopeId: sc });
+            await host.admin.activateScope(staff, t, sc);
+            await host.admin.suspendScope(staff, t, sc);
+            const scopeHeld = await host.getScope(alice, t, sc).then(() => undefined, (e) => e);
+            expect(errorCodeOf(scopeHeld)).toBe('conflict');
+            expect(scopeHeld.extensions.reason).toBe(SCOPE_GATE_REASONS.notActive);
+            await host.admin.unsuspendScope(staff, t, sc);
+            await host.admin.setTenantStatus(staff, t, 'suspended');
+            const tenantHeld = await host.getScope(alice, t, sc).then(() => undefined, (e) => e);
+            expect(tenantHeld.extensions.reason).toBe(SCOPE_GATE_REASONS.notActive);
+            // The twin: an admin refusal of the same code is not the gate's.
+            const illegal = await host.admin.unarchiveScope(staff, t, sc).then(() => undefined, (e) => e);
+            expect(errorCodeOf(illegal)).toBe('conflict');
+            expect(illegal.extensions.reason).toBeUndefined();
+        });
+        it('refuses what used to answer the generic 500 with its own code (#113)', async () => {
+            const t = tenantId.parse(ulid());
+            const sc = scopeId.parse(ulid());
+            await host.admin.createTenant(staff, { id: t, slug: `was500-${t.toLowerCase()}`, name: 'Was 500' });
+            await host.provisionScope(staff, { tenantId: t, scopeId: sc });
+            await host.admin.activateScope(staff, t, sc);
+            // An unknown hostname, on both of its doors.
+            await expectRefusal(host.admin.setHostnameStatus(staff, `ghost-${t.toLowerCase()}.example.com`, 'active'), 'not_found', /unknown hostname/);
+            // A link into a pool nobody registered: its precondition is missing.
+            await expectRefusal(host.admin.linkIdentity(staff, { provider: `oidc:ghost-${t.toLowerCase()}`, externalId: 'u1', principal: alice, tenantId: t }), 'conflict', /is not registered/);
+            // A system door for a module this host never registered.
+            await expectRefusal(host.getSystemScope(moduleId.parse('@ghost/none'), t, sc), 'not_found', /module not registered/);
+            // A migration asked of a scope that is archived.
+            await host.admin.archiveScope(staff, t, sc);
+            await expectRefusal(host.migrateScope(t, sc), 'conflict', /not migratable \(status: archived\)/);
+        });
+        it('refuses to provision a scope under a non-active tenant, typed conflict (#113)', async () => {
+            const t = tenantId.parse(ulid());
+            await host.admin.createTenant(staff, { id: t, slug: `held-${t.toLowerCase()}`, name: 'Held Co' });
+            await host.admin.setTenantStatus(staff, t, 'suspended');
+            await expectRefusal(host.provisionScope(staff, { tenantId: t, scopeId: scopeId.parse(ulid()) }), 'conflict', /non-active tenant \(status: suspended\)/);
+            await host.admin.setTenantStatus(staff, t, 'active');
+            await host.provisionScope(staff, { tenantId: t, scopeId: scopeId.parse(ulid()) }); // the twin: active again, it provisions
+        });
+        it('refuses an identity pool re-registered with another topology, typed conflict (#113)', async () => {
+            const t = tenantId.parse(ulid());
+            const provider = `oidc:pool-${t.toLowerCase()}`;
+            await host.admin.createTenant(staff, { id: t, slug: `pool-${t.toLowerCase()}`, name: 'Pool Co' });
+            await host.admin.registerIdentityPool(staff, { provider, topology: 'tenant-bound', tenantId: t });
+            // The same declaration again is idempotent…
+            await expect(host.admin.registerIdentityPool(staff, { provider, topology: 'tenant-bound', tenantId: t })).resolves.toBeUndefined();
+            // …a different one conflicts.
+            await expectRefusal(host.admin.registerIdentityPool(staff, { provider, topology: 'central', tenantId: null }), 'conflict', /is already registered as tenant-bound/);
+        });
+        it('refuses a vertical re-registered from another source, typed conflict (#113)', async () => {
+            const slug = `src-${ulid().toLowerCase()}`;
+            await host.admin.registerVertical(staff, { slug, name: 'Source Test', source: 'git' });
+            await expect(host.admin.registerVertical(staff, { slug, name: 'Source Test', source: 'git' })).resolves.toBeUndefined();
+            await expectRefusal(host.admin.registerVertical(staff, { slug, name: 'Source Test', source: 'cli' }), 'conflict', /is already registered as git/);
         });
         // -- identity links: the projection read (#406) ---------------------------
         it('listIdentityLinks returns one tenant’s links and tracks link/unlink', async () => {
@@ -7198,7 +7455,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
         });
         it('refuses a slug already taken under the tenant, and re-provision is still idempotent (§3.2)', async () => {
             const other = scopeId.parse(ulid());
-            await expect(host.provisionScope(staff, { tenantId: t5, scopeId: other, slug: 'brf-vasastan' })).rejects.toThrow(/already taken/);
+            await expectRefusal(host.provisionScope(staff, { tenantId: t5, scopeId: other, slug: 'brf-vasastan' }), 'conflict', /already taken/);
             // Idempotency is keyed on the scope id, so re-provisioning the SAME scope
             // must not collide with its own slug.
             const named = (await host.admin.listScopes(staff, { tenantId: t5 })).find((s) => s.slug === 'brf-vasastan');
@@ -7213,11 +7470,11 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
         it('refuses a tenant slug already taken, fail closed (§4.1)', async () => {
             // INSERT OR IGNORE would have reported this as an idempotent no-op and
             // silently not created the tenant the caller asked for.
-            await expect(host.admin.createTenant(staff, {
+            await expectRefusal(host.admin.createTenant(staff, {
                 id: tenantId.parse(ulid()),
                 slug: 'directory-co',
                 name: 'Impostor Co',
-            })).rejects.toThrow(/already taken/);
+            }), 'conflict', /already taken/);
         });
         it('enumerates the scopes under a tenant, and filters by status (§4.5)', async () => {
             const all = await host.admin.listScopes(staff, { tenantId: t5 });