@substrat-run/contract-tests 0.114.0 → 0.116.0

package/dist/scope-host-suite.js

@@ -1,8 +1,35 @@
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
 import { connectorCalls, connectorTestFetch, resetConnectorCalls } from './connector-fixture.js';
-import { connectionId, dataSubjectId, eventId, instant, moduleManifest, orgId, AUTO_ADMISSION_NOTE, permissionKey, platformActorId, principalId, scopeId, tenantId, SCOPE_QUERY_ROW_MAX, } from '@substrat-run/contracts';
+import { connectionId, dataSubjectId, errorCodeOf, eventId, instant, moduleManifest, orgId, AUTO_ADMISSION_NOTE, permissionKey, platformActorId, principalId, scopeId, tenantId, SCOPE_QUERY_ROW_MAX, } from '@substrat-run/contracts';
 import { isSearchIndexTable, runPlatformSweep, ulid, } from '@substrat-run/kernel';
 import { billedMod, contractTestBareOps, contractTestInitialModules, gateModManifest, lateMod, testModManifest, victimModManifest, } from './modules.js';
+/**
+ * Assert a refusal by the CODE it declared, not by the sentence it happens to carry
+ * (#113 phase 5).
+ *
+ * `errorCodeOf` is the same reading the control plane's `mapError` does, so what this
+ * pins and the problem document a transport renders agree by construction. A `/message/`
+ * match agreed with it only by coincidence — and that coincidence was load-bearing:
+ * `CODE_PATTERNS` in `packages/control-plane-api/src/errors.ts` guessed the code by
+ * regex, so rewording a throw silently changed a 404 into a 500, and the suite's own
+ * message assertion was the only thing standing in the way. Moving the assertion here
+ * makes the message free to change and the TYPE the thing that cannot.
+ *
+ * A promise that RESOLVES fails this too: `errorCodeOf(undefined)` is `undefined`, which
+ * is never a code — so it cannot pass by not throwing at all.
+ *
+ * `message` is for the minority of refusals where the sentence carries something the code
+ * cannot: WHICH branch fired, when two branches share one code. `deleteVertical` refuses a
+ * live scope with "delete or rebind" and an archived one with "reap or restore" — both
+ * `conflict`, and an adapter that answered the wrong one would send an operator to a button
+ * that is not there. Pass it only for that; a code is the contract everywhere else.
+ */
+const expectRefusal = async (p, code, message) => {
+    const err = await p.then(() => undefined, (e) => e);
+    expect(errorCodeOf(err)).toBe(code);
+    if (message !== undefined)
+        expect(err?.message).toMatch(message);
+};
 /**
  * The scope-host contract suite (design doc §11). Every adapter — pure SQLite,
  * Cloudflare, and any future one — must pass this unchanged (D-14). If an
@@ -451,6 +478,44 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             // rebuild instant went to the new table, and reopening it would write it there twice.
             await expect(host.admin.redrainEvents(staff, t1, sDrain, { drainedBefore: stampedAt })).resolves.toBe(0);
             const justAfter = new Date(Date.parse(stampedAt) + 1).toISOString();
+            // COUNT ONLY (#1545) — the same window asked read-only, which is what a dry run needs
+            // and what nothing could answer before: the verb only ever reopened, so a caller could
+            // learn the number by changing the rows or not at all.
+            const redrainRows = async () => (await host.admin.auditLog(staff, { tenantId: t1 })).filter((r) => r.action === 'redrainEvents' && r.scopeId === sDrain).length;
+            const receiptsBefore = await redrainRows();
+            const undrainedBefore = await host.admin.readUndrainedEvents(staff, t1, sDrain, 200);
+            // Strictly before, on the same boundary the reopen holds: a count that included the
+            // instant would rehearse a different window from the one the real run touches.
+            await expect(host.admin.redrainEvents(staff, t1, sDrain, { drainedBefore: stampedAt, countOnly: true })).resolves.toBe(0);
+            // Asked TWICE on purpose: a "count" that reopened its own window would answer
+            // differently the second time, which is the one failure a rehearsal must not have.
+            await expect(host.admin.redrainEvents(staff, t1, sDrain, { drainedBefore: justAfter, countOnly: true })).resolves.toBe(first.length);
+            await expect(host.admin.redrainEvents(staff, t1, sDrain, { drainedBefore: justAfter, countOnly: true })).resolves.toBe(first.length);
+            // …and it moved nothing: the stamped rows are still stamped, so the drain has exactly
+            // the same work in front of it as before the count.
+            expect((await host.admin.readUndrainedEvents(staff, t1, sDrain, 200)).map((e) => e.id)).toEqual(undrainedBefore.map((e) => e.id));
+            // …and wrote no receipt. The intent row exists because a reopen that crashed before
+            // its outcome row would leave a second egress with no trace; a count egresses nothing,
+            // and a row claiming a redrain on a scope that was only counted is a false statement
+            // in the one log that is evidence.
+            expect(await redrainRows()).toBe(receiptsBefore);
+            // It is still a READ, and K-24 takes all reads rather than a chosen subset — so the
+            // access log carries a row per count, naming the window and the number it found.
+            // "Nobody can tell who counted every tenant's outbox" is the hole that would be.
+            const counts = (await host.admin.accessLog(staff, { tenantId: t1, method: 'redrainEvents' })).filter((r) => r.scopeId === sDrain);
+            expect(counts).toHaveLength(3);
+            expect(counts.map((r) => r.resultCount)).toEqual(expect.arrayContaining([0, first.length]));
+            // The future refusal is the verb's, not the reopen's alone — the window rule is
+            // checked before the two branches part.
+            await expect(host.admin.redrainEvents(staff, t1, sDrain, {
+                drainedBefore: new Date(Date.now() + 60_000).toISOString(),
+                countOnly: true,
+            })).rejects.toThrow(/future/);
+            // K-3 holds for the count as for the reopen: a foreign pair is refused, never answered
+            // 0 — "nothing to reopen" would read as a finished rehearsal of a scope never touched.
+            await expect(host.admin.redrainEvents(staff, t2, sDrain, { drainedBefore: justAfter, countOnly: true })).rejects.toThrow(/unknown scope/);
+            // The number the count gave IS the number the reopen changes — the property that makes
+            // a dry run a rehearsal rather than a second, differently-shaped question.
             await expect(host.admin.redrainEvents(staff, t1, sDrain, { drainedBefore: justAfter })).resolves.toBe(first.length);
             // The reopened rows come back through the ordinary read, unchanged — nothing about the
             // event moves except that it may leave again.
@@ -2950,8 +3015,8 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             expect((await at('listtest'))?.publishRequestedAt).toBeTruthy();
             await host.admin.setVerticalListed(staff, 'listtest', true);
             expect((await at('listtest'))?.publishRequestedAt).toBeUndefined(); // cleared on review
-            await expect(host.admin.setVerticalListed(staff, 'no-such-vertical', true)).rejects.toThrow(/unknown vertical/);
-            await expect(host.admin.requestPublish(staff, 'no-such-vertical')).rejects.toThrow(/unknown vertical/);
+            await expectRefusal(host.admin.setVerticalListed(staff, 'no-such-vertical', true), 'not_found');
+            await expectRefusal(host.admin.requestPublish(staff, 'no-such-vertical'), 'not_found');
         });
         it('blocks new installs (setVerticalInstallsBlocked) — a provisioning gate, not a delete', async () => {
             const at = (slug) => host.admin.listVerticals(staff).then((vs) => vs.find((v) => v.slug === slug));
@@ -2964,7 +3029,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             expect((await at('blocktest'))?.listed).toBe(false);
             await host.admin.setVerticalInstallsBlocked(staff, 'blocktest', false);
             expect((await at('blocktest'))?.installsBlocked).toBe(false);
-            await expect(host.admin.setVerticalInstallsBlocked(staff, 'no-such-vertical', true)).rejects.toThrow(/unknown vertical/);
+            await expectRefusal(host.admin.setVerticalInstallsBlocked(staff, 'no-such-vertical', true), 'not_found');
         });
         it('grants the tenant-provisioner capability (setVerticalTenantProvisioner) — a staff grant a re-push cannot touch', async () => {
             const at = (slug) => host.admin.listVerticals(staff).then((vs) => vs.find((v) => v.slug === slug));
@@ -2979,7 +3044,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             expect((await at('managertest'))?.tenantProvisioner).toBe(true);
             await host.admin.setVerticalTenantProvisioner(staff, 'managertest', false);
             expect((await at('managertest'))?.tenantProvisioner).toBe(false);
-            await expect(host.admin.setVerticalTenantProvisioner(staff, 'no-such-vertical', true)).rejects.toThrow(/unknown vertical/);
+            await expectRefusal(host.admin.setVerticalTenantProvisioner(staff, 'no-such-vertical', true), 'not_found');
         });
         it('carries the declared provisioner intent (#455) — a refreshable request, orthogonal to the grant', async () => {
             const at = (slug) => host.admin.listVerticals(staff).then((vs) => vs.find((v) => v.slug === slug));
@@ -3030,12 +3095,13 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             expect((await at('mailer'))?.emailSender).toBe(true);
             await host.admin.setVerticalEmailSender(staff, 'mailer', false);
             expect((await at('mailer'))?.emailSender).toBe(false);
-            await expect(host.admin.setVerticalEmailSender(staff, 'no-such-vertical', true)).rejects.toThrow(/unknown vertical/);
+            await expectRefusal(host.admin.setVerticalEmailSender(staff, 'no-such-vertical', true), 'not_found');
         });
         it('deletes a vertical — refused while a scope is bound, total once nothing is', async () => {
             // 'callout' still backs s1 (bound above): the refusal that stops a delete from
-            // stranding a live scope's version pin and routing.
-            await expect(host.admin.deleteVertical(staff, 'callout')).rejects.toThrow(/still backs/);
+            // stranding a live scope's version pin and routing. Pinned by the CODE (#113
+            // phase 5) — the sentence is free to change, the 409 is not.
+            await expectRefusal(host.admin.deleteVertical(staff, 'callout'), 'conflict');
             expect((await host.admin.listVerticals(staff)).some((v) => v.slug === 'callout')).toBe(true);
             // A vertical nothing is bound to deletes totally: row, versions, channels.
             const versionId = ulid();
@@ -3059,7 +3125,55 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             await host.admin.registerVertical(staff, { slug: 'deletable', name: 'Deletable', source: 'cli', ownerTenant: t2 });
             expect(await host.admin.listVersions(staff, 'deletable')).toEqual([]); // no resurrected versions
             await host.admin.deleteVertical(staff, 'deletable');
-            await expect(host.admin.deleteVertical(staff, 'no-such-vertical')).rejects.toThrow(/unknown vertical/);
+            await expectRefusal(host.admin.deleteVertical(staff, 'no-such-vertical'), 'not_found');
+        });
+        it('refuses the serving-state read and write for a vertical that does not exist', async () => {
+            await expectRefusal(host.admin.verticalServing(staff, 'no-such-vertical'), 'not_found');
+            await expectRefusal(host.admin.setVerticalServing(staff, 'no-such-vertical', {
+                ref: 'serving-script', versionId: ulid(), doClasses: [], migrationTag: 'g1',
+            }), 'not_found');
+        });
+        it('refuses every registry verb that addresses a version which does not exist (#113 phase 5)', async () => {
+            // The five `unknown version …` throw sites, one per verb, on both adapters. Nothing
+            // asserted them before this case: each was a bare `Error` whose 404 came from a
+            // `/unknown version /` regex in the control plane, so a reword — or a regression to
+            // `new Error` — changed the status with no test to notice. The code is the contract
+            // now, and it is pinned here rather than in the transport.
+            //
+            // The id is well-formed and simply names nothing, which is what separates this from
+            // a parse failure: `not_found`, never `validation_failed`.
+            const ghost = ulid();
+            await expectRefusal(host.admin.admitVersion(staff, ghost), 'not_found');
+            await expectRefusal(host.admin.rejectVersion(staff, ghost, 'no such version'), 'not_found');
+            await expectRefusal(host.admin.promoteVersion(staff, 'callout', 'prod', ghost), 'not_found');
+            await expectRefusal(host.admin.bindScopeVersion(staff, t1, s1, ghost), 'not_found');
+            await expectRefusal(host.admin.versionManifest(staff, 'callout', ghost), 'not_found');
+            // versionManifest refuses on the PAIR — `!v || v.vertical_slug !== verticalSlug` —
+            // so the absent id above only exercises HALF its guard. A version that really
+            // exists, under a DIFFERENT vertical, must read as absent too: asking for it under
+            // someone else's slug is not a way in. Without this second call an implementation
+            // that dropped the ownership check would still pass the case, which is the same
+            // shape of hole this whole change exists to close.
+            await host.admin.registerVertical(staff, {
+                slug: 'otherowner',
+                name: 'OtherOwner',
+                source: 'cli',
+                ownerTenant: t1,
+            });
+            const elsewhere = ulid();
+            await host.admin.publishVersion(staff, {
+                id: elsewhere,
+                verticalSlug: 'otherowner',
+                version: '1.0.0',
+                manifestDigest: 'm-other',
+                permissionDigest: 'p-other',
+                migrationDigest: 'g-other',
+                deploymentRef: null,
+            });
+            // It resolves under its OWN vertical — so the refusal below is the pair check
+            // firing, not the version failing to exist.
+            await host.admin.versionManifest(staff, 'otherowner', elsewhere);
+            await expectRefusal(host.admin.versionManifest(staff, 'callout', elsewhere), 'not_found');
         });
         it('an archived scope blocks the delete naming the reap step; a reaped tombstone never blocks', async () => {
             // A deleted app leaves an `archived` row (restorable via unarchive), then a
@@ -3070,9 +3184,14 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             const sRet = scopeId.parse(ulid());
             await host.admin.registerVertical(staff, { slug: 'retirable', name: 'Retirable', source: 'cli', ownerTenant: t2 });
             await host.provisionScope(staff, { tenantId: t2, scopeId: sRet, jurisdiction: 'eu', vertical: 'retirable' });
-            await expect(host.admin.deleteVertical(staff, 'retirable')).rejects.toThrow(/still backs 1 scope\(s\) — delete or rebind/);
+            // Both halves are `conflict` and the sentence is what tells them apart, so both are
+            // asserted (#113 phase 5). The CODE is what the transport renders the 409 from —
+            // the archived half reached the control plane as a generic 500 until these throws
+            // were typed, because the pattern row that carried the live one read
+            // `/still backs \d+ scope\(s\)/` and the word `archived` sits in the middle of it.
+            await expectRefusal(host.admin.deleteVertical(staff, 'retirable'), 'conflict', /still backs 1 scope\(s\) — delete or rebind/);
             await host.admin.archiveScope(staff, t2, sRet);
-            await expect(host.admin.deleteVertical(staff, 'retirable')).rejects.toThrow(/1 archived scope\(s\) — reap or restore/);
+            await expectRefusal(host.admin.deleteVertical(staff, 'retirable'), 'conflict', /1 archived scope\(s\) — reap or restore/);
             await host.admin.reapScope(staff, t2, sRet);
             await host.admin.deleteVertical(staff, 'retirable');
             expect((await host.admin.listVerticals(staff)).some((v) => v.slug === 'retirable')).toBe(false);
@@ -3104,7 +3223,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             await host.admin.rejectVersion(staff, versionId, 'permission diff widened a role');
             await expect(host.admin.bindScopeVersion(staff, t1, s1, versionId)).rejects.toThrow(/rejected, not admitted/);
             // Terminal: a rejected version is not resurrected, a new one is published.
-            await expect(host.admin.admitVersion(staff, versionId)).rejects.toThrow(/was rejected/);
+            await expectRefusal(host.admin.admitVersion(staff, versionId), 'conflict');
             const rejected = (await host.admin.listVersions(staff, 'callout')).find((v) => v.id === versionId);
             expect(rejected?.admissionNote).toContain('widened a role');
         });
@@ -3120,7 +3239,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             }
         });
         it('refuses a version for a vertical nobody registered', async () => {
-            await expect(host.admin.publishVersion(staff, {
+            await expectRefusal(host.admin.publishVersion(staff, {
                 id: ulid(),
                 verticalSlug: 'ghost',
                 version: '1.0.0',
@@ -3128,7 +3247,7 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                 permissionDigest: 'p',
                 migrationDigest: 'g',
                 deploymentRef: null,
-            })).rejects.toThrow(/unknown vertical/);
+            }), 'not_found');
         });
         // -- channels and promotion-time checkpoints (#31 step 2) ----------------
         // Promotion is the moment a change reaches anyone, so it is where §4's two
@@ -3871,6 +3990,124 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             expect(reactions).toHaveLength(2);
             expect(new Set(reactions.map((r) => r.caused_by)).size).toBe(2);
         });
+        // -- the invocation a DELIVERY belongs to (#1525) -------------------------
+        //
+        // #1237 put `invocation_id` on the outbox, which answers "which call emitted this
+        // event". A delivery joins to that through `event_id`, so the tempting reading is
+        // that deliveries needed nothing. What the event's id cannot say is which call
+        // attempted the DELIVERY — and for an executor those come apart by design: attempt
+        // one runs in the emitting call's post-commit tail, every retry after it in a drain
+        // that is a different call or none at all.
+        //
+        // Each test takes its own scope: they assert over the whole delivery log they read.
+        describe('the invocation a delivery belongs to (#1525)', () => {
+            const flowScope = async () => {
+                const s = scopeId.parse(ulid());
+                await host.provisionScope(staff, { tenantId: t1, scopeId: s, vertical: 'flow-vertical' });
+                await host.admin.activateScope(staff, t1, s);
+                return s;
+            };
+            it('stamps a consumer delivery with the invocation the call carried', async () => {
+                const s = await flowScope();
+                const stub = await host.getScope(alice, t1, s);
+                const call = ulid();
+                await stub.invoke('flow/produce', undefined, { invocationId: call });
+                // The VALUE, not merely the column: a delivery that recorded null here would
+                // satisfy every "the column exists" assertion and join to nothing.
+                const rows = (await stub.invoke('flow/deliveries'));
+                expect(rows).toHaveLength(2);
+                expect(rows.map((r) => r.invocation_id)).toEqual([call, call]);
+                // A SECOND call is a second id. The field is cleared after each invocation
+                // (#1237), so a leak would file this call's deliveries under the previous one
+                // — which a single-call assertion cannot see.
+                const next = ulid();
+                await stub.invoke('flow/produce', undefined, { invocationId: next });
+                const after = (await stub.invoke('flow/deliveries'));
+                expect(after).toHaveLength(4);
+                expect(after.filter((r) => r.invocation_id === call)).toHaveLength(2);
+                expect(after.filter((r) => r.invocation_id === next)).toHaveLength(2);
+            });
+            it('records null when the caller carried no invocation, and still delivers', async () => {
+                // A seed, a test, an internal call. Null is the honest answer — and the
+                // delivery itself must still happen and still be journalled, since a drain that
+                // failed because no id was carried is a far worse outcome than an unjoined row.
+                // The positive twin above shares this mechanism, so breaking the write reddens
+                // that one rather than leaving both green on a column nobody fills.
+                const s = await flowScope();
+                const stub = await host.getScope(alice, t1, s);
+                await stub.invoke('flow/produce');
+                const rows = (await stub.invoke('flow/deliveries'));
+                expect(rows).toHaveLength(2);
+                expect(rows.every((r) => r.invocation_id === null)).toBe(true);
+                expect(rows.every((r) => r.error === null)).toBe(true);
+            });
+            it('carries the delivery\'s invocation out through the effects walk', async () => {
+                // The column is written; this is what makes it reachable. `walkEventEffects`
+                // is the read that renders a delivery, so a column added to the store and
+                // missed there would leave the join invisible to every surface that shows one.
+                const s = await flowScope();
+                const stub = await host.getScope(alice, t1, s);
+                const call = ulid();
+                await stub.invoke('flow/produce', undefined, { invocationId: call });
+                const rows = (await stub.invoke('flow/causes'));
+                const step1 = rows.find((r) => r.type === 'flow.step1');
+                const tree = await host.admin.eventEffects(staff, t1, s, {
+                    eventId: eventId.parse(step1.id),
+                });
+                expect(tree.root.deliveries).not.toHaveLength(0);
+                expect(tree.root.deliveries.every((d) => d.invocationId === call)).toBe(true);
+            });
+            it('stamps an executor delivery with the call whose tail ran it', async () => {
+                // Executors are the half the event's own id could never have covered. On the
+                // hosted adapter this journal is written from the COORDINATOR over an RPC, so
+                // there is no ambient field to read and the id has to survive the hop.
+                const s = scopeId.parse(ulid());
+                await host.provisionScope(staff, {
+                    tenantId: t1,
+                    scopeId: s,
+                    vertical: 'connector-vertical',
+                });
+                await host.admin.activateScope(staff, t1, s);
+                const stub = await host.getScope(alice, t1, s);
+                const call = ulid();
+                await stub.invoke('connector/request-effect', { tag: 'inv-ok' }, { invocationId: call });
+                const emitted = await host.admin.invocationEvents(staff, t1, s, { invocationId: call });
+                const requested = emitted.events.find((e) => e.type === 'effect.requested');
+                const tree = await host.admin.eventEffects(staff, t1, s, { eventId: requested.id });
+                const delivery = tree.root.deliveries.find((d) => d.consumer === 'executor:flaky-effector');
+                expect(delivery).toBeDefined();
+                expect(delivery.state).toBe('delivered');
+                expect(delivery.invocationId).toBe(call);
+            });
+            it('files a RETRY under the call that re-attempted it, not the one that emitted', async () => {
+                // The test that proves this column is not a copy of the outbox's. A doomed
+                // executor is attempted once in the emitting call's tail and once more on a
+                // drain — and the drain is not a call. So the dead row's event still names the
+                // request that produced it while the attempt that gave up names none, which is
+                // exactly the pair `DeadLetter` could not previously tell apart.
+                const s = scopeId.parse(ulid());
+                await host.provisionScope(staff, {
+                    tenantId: t1,
+                    scopeId: s,
+                    vertical: 'connector-vertical',
+                });
+                await host.admin.activateScope(staff, t1, s);
+                const stub = await host.getScope(alice, t1, s);
+                const call = ulid();
+                await stub.invoke('connector/request-doomed', { tag: 'inv-doomed' }, { invocationId: call });
+                // maxAttempts 2: attempt one ran inline under `call`, attempt two runs here.
+                expect((await host.drainDue(t1, s)).deadLettered).toBe(1);
+                const page = await host.admin.deadLetters(staff, t1, s, {});
+                const dead = page.entries.find((d) => d.consumer === 'executor:doomed-effector');
+                expect(dead).toBeDefined();
+                // The EVENT still joins to the request that emitted it…
+                expect(dead.invocationId).toBe(call);
+                // …and the ATTEMPT that gave up names no call, because a drain is not one. An
+                // implementation that copied the event's id here would read `call` and claim a
+                // request had done something it did not do.
+                expect(dead.attemptInvocationId).toBeNull();
+            });
+        });
         it('creates a tenant record, idempotently; only real creates are audited', async () => {
             await host.admin.createTenant(staff, { id: t3, slug: 'acme-co', name: 'Acme Co' });
             await host.admin.createTenant(staff, { id: t3, slug: 'acme-co', name: 'Acme Co' }); // no-op