@substrat-run/contract-tests 0.108.0 → 0.110.0

package/dist/scope-host-suite.js

@@ -362,6 +362,165 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             const journal2 = await again.invoke('testmod/read-journal');
             expect(journal2.filter((r) => r.module_id === '@test/mod')).toHaveLength(1);
         });
+        it('drains events at-least-once, and a re-mark cannot rewrite when they shipped (#1334)', async () => {
+            // Tier 2 (master-plan §5.3) is fed exclusively by this stream, and
+            // `drained_at` has been on the outbox since it shipped with nothing writing
+            // it. These two verbs are what a drain is built from.
+            //
+            // Its OWN scope, not the shared `s1`. A drain read is "everything undrained,
+            // up to a limit", so every event any earlier test left behind is part of this
+            // test's input — and the closing assertion, that exactly one event is
+            // undrained after a new emit, is only true while that backlog stays under the
+            // page size. Nothing about this test's subject needs the shared fixture, and
+            // depending on how full it is makes the failure arrive later, in someone
+            // else's PR.
+            const sDrain = scopeId.parse(ulid());
+            await host.provisionScope(staff, {
+                tenantId: t1,
+                scopeId: sDrain,
+                jurisdiction: 'eu',
+                vertical: 'connector-vertical',
+            });
+            await host.admin.activateScope(staff, t1, sDrain);
+            const stub = await host.getScope(alice, t1, sDrain);
+            const subject = ulid();
+            await stub.invoke('test/emit-event');
+            await stub.invoke('test/emit-event', { subject });
+            const first = await host.admin.readUndrainedEvents(staff, t1, sDrain, 200);
+            expect(first.length).toBeGreaterThanOrEqual(2);
+            // Oldest first and stable — a drain resumes where it stopped rather than
+            // re-reading from the top.
+            expect([...first].sort((a, b) => (a.id < b.id ? -1 : 1)).map((e) => e.id)).toEqual(first.map((e) => e.id));
+            // The dimensions the lake exists to carry ride along: the emitting operation
+            // and the version, which #1250 deliberately keeps OFF the envelope.
+            const emitted = first.find((e) => e.type === 'test.happened');
+            expect(emitted.operation).toBe('test/emit-event');
+            expect('version' in emitted).toBe(true);
+            // And the erasure key rides along, so a shred can still reach the copy that
+            // left the scope. Absent on an event with no data subject — the key is a
+            // fact about the event, not a field the drain invents.
+            expect(first.find((e) => e.subjectId === subject)).toBeDefined();
+            // Reading does NOT mark: a sink that fails must leave the events replayable,
+            // which is the whole reason read and mark are separate verbs.
+            const again = await host.admin.readUndrainedEvents(staff, t1, sDrain, 200);
+            expect(again.map((e) => e.id)).toEqual(first.map((e) => e.id));
+            const marked = await host.admin.markEventsDrained(staff, t1, sDrain, first.map((e) => e.id));
+            expect(marked).toBe(first.length);
+            const afterMark = await host.admin.readUndrainedEvents(staff, t1, sDrain, 200);
+            expect(afterMark.map((e) => e.id)).not.toEqual(expect.arrayContaining(first.map((e) => e.id)));
+            // K-24's rule one tier down: domain payloads leaving the platform are an
+            // EGRESS, so the admin log carries a receipt naming who declared it and how
+            // many rows it covered. Without one there is no durable record of who shipped
+            // a customer's events off the platform.
+            const receipt = (await host.admin.auditLog(staff, { tenantId: t1 })).find((r) => r.action === 'drainEvents' && r.scopeId === sDrain);
+            expect(receipt?.actor).toBe(staff);
+            expect((receipt?.after).drained).toBe(first.length);
+            // Marking is idempotent, and a replayed batch must not move an earlier
+            // drain's timestamp forward — a lake row's "when did this ship" would
+            // otherwise drift every time a retry passed over it.
+            await expect(host.admin.markEventsDrained(staff, t1, sDrain, first.map((e) => e.id))).resolves.toBe(0);
+            // …and the re-mark writes NO second receipt. An admin log that grows a row
+            // per retry claims egresses that never happened, which is worse than silence:
+            // the log is the evidence, and inflated evidence is not evidence.
+            const receipts = (await host.admin.auditLog(staff, { tenantId: t1 })).filter((r) => r.action === 'drainEvents' && r.scopeId === sDrain);
+            expect(receipts).toHaveLength(1);
+            // A new event after the drain is picked up; the drained ones are not.
+            await stub.invoke('test/emit-event');
+            const next = await host.admin.readUndrainedEvents(staff, t1, sDrain, 200);
+            expect(next.length).toBe(1);
+            expect(first.map((e) => e.id)).not.toContain(next[0].id);
+            // An empty mark is a no-op, not an error — a drain with nothing to ship.
+            await expect(host.admin.markEventsDrained(staff, t1, sDrain, [])).resolves.toBe(0);
+            // But "nothing to mark" and "you may not address this scope" stay different
+            // answers. The empty batch must not become a shortcut past K-3: a mismatched
+            // pair that quietly returns 0 makes a caller's typo read as a successful drain.
+            await expect(host.admin.markEventsDrained(staff, t2, sDrain, [])).rejects.toThrow(/unknown scope/);
+            await expect(host.admin.markEventsDrained(staff, t1, scopeId.parse(ulid()), [])).rejects.toThrow(/unknown scope/);
+        });
+        it('facets the outbox, and keeps an ERASED payload out of the null bucket (#1239)', async () => {
+            const stub = await host.getScope(alice, t1, s1);
+            const subject = ulid();
+            // Three events: two whose payload carries `secret`, one that never had it.
+            await stub.invoke('test/emit-event', { subject, secret: 'kept' });
+            await stub.invoke('test/emit-event', { subject: ulid(), secret: 'kept' });
+            await stub.invoke('test/emit-event');
+            const byType = await host.admin.facetEvents(staff, t1, s1, { groupBy: { kind: 'type' } });
+            const happened = byType.buckets.find((b) => b.value === 'test.happened');
+            expect(happened.count).toBeGreaterThanOrEqual(3);
+            // An envelope grouping cannot be erased, so the count is structurally zero.
+            expect(byType.erased).toBe(0);
+            const before = await host.admin.facetEvents(staff, t1, s1, {
+                groupBy: { kind: 'payload', field: 'secret' },
+                type: 'test.happened',
+            });
+            expect(before.erased).toBe(0);
+            expect(before.buckets.find((b) => b.value === 'kept').count).toBe(2);
+            // The event that never carried the field is a genuine null bucket — an
+            // absence in the data, which is a different fact from an erasure.
+            expect(before.buckets.find((b) => b.value === null).count).toBeGreaterThanOrEqual(1);
+            // Now erase one subject: the shred keeps the row and drops the payload.
+            await host.admin.shredSubject(staff, t1, s1, dataSubjectId.parse(subject));
+            const after = await host.admin.facetEvents(staff, t1, s1, {
+                groupBy: { kind: 'payload', field: 'secret' },
+                type: 'test.happened',
+            });
+            // THE RULE: the erased event is counted apart, and did NOT join the null
+            // bucket. Folding it in would show a reader a clean distribution with no
+            // hint that part of the history was redacted.
+            expect(after.erased).toBe(1);
+            expect(after.buckets.find((b) => b.value === 'kept').count).toBe(1);
+            expect(after.buckets.find((b) => b.value === null)?.count ?? 0).toBe(before.buckets.find((b) => b.value === null).count);
+            // And the denominator still counts it: the event happened, whatever it said.
+            expect(after.total).toBe(before.total);
+        });
+        it('carries WHEN each bucket last saw an event, not only how many (#1234)', async () => {
+            const stub = await host.getScope(alice, t1, s1);
+            await stub.invoke('test/emit-event');
+            await stub.invoke('test/emit-event');
+            const byType = await host.admin.facetEvents(staff, t1, s1, { groupBy: { kind: 'type' } });
+            const happened = byType.buckets.find((b) => b.value === 'test.happened');
+            // Recency is the question a count cannot answer, and the one the flow map asks:
+            // a consumer with a big number that stopped months ago is the failure volume hides.
+            expect(happened.lastSeen).toEqual(expect.any(String));
+            // And it is genuinely the MAXIMUM, not just some row's timestamp. `until` is
+            // exclusive, so faceting up to `lastSeen` must drop every event that carries it —
+            // which is a property of the query rather than a hope about the clock, and needs
+            // no control over time to assert.
+            const upTo = await host.admin.facetEvents(staff, t1, s1, {
+                groupBy: { kind: 'type' },
+                until: happened.lastSeen,
+            });
+            const earlier = upTo.buckets.find((b) => b.value === 'test.happened');
+            expect(earlier?.count ?? 0).toBeLessThan(happened.count);
+            // Whatever survives is strictly older, so its own recency moved back with it.
+            if (earlier?.lastSeen)
+                expect(earlier.lastSeen < happened.lastSeen).toBe(true);
+        });
+        it('renders one bucket per rendered value, and does not invent an erasure (#1239)', async () => {
+            const stub = await host.getScope(alice, t1, s1);
+            // SQLite keeps these in separate storage classes: `json_extract` hands back an
+            // INTEGER for the first and TEXT for the second, so grouping the raw result and
+            // stringifying afterwards produces two buckets both labelled "1".
+            await stub.invoke('test/emit-facet-edge', { code: 1 });
+            await stub.invoke('test/emit-facet-edge', { code: '1' });
+            // Legal and ordinary: an event with no payload at all. It is stored as the same
+            // SQL NULL a shred writes, and nothing about it has been erased.
+            await stub.invoke('test/emit-facet-edge', { omit: true });
+            const facet = await host.admin.facetEvents(staff, t1, s1, {
+                groupBy: { kind: 'payload', field: 'code' },
+                type: 'test.facet-edge',
+            });
+            // ONE bucket for "1", carrying both events — not two that split the count.
+            const ones = facet.buckets.filter((b) => b.value === '1');
+            expect(ones).toHaveLength(1);
+            expect(ones[0].count).toBe(2);
+            // The payload-less event is an extraction-null, NOT a redaction. Reporting it
+            // as erased would tell a reader that history was withheld from them when it
+            // was simply never written.
+            expect(facet.erased).toBe(0);
+            expect(facet.buckets.find((b) => b.value === null).count).toBe(1);
+            expect(facet.total).toBe(3);
+        });
         it('answers one record’s history through the platform (#1235)', async () => {
             // `readHistory` has been the sanctioned read since #800 and, until this
             // verb, nothing above the scope could call it — the whole point of #1235.
@@ -3426,6 +3585,57 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             }
         });
         // -- tenant registry + lifecycle (control-plane.md §4.1) -----------------
+        /**
+         * #1237 — placed at the end of the flow cases deliberately. These provision their
+         * own scopes (the shared one is where the dispatch cases assert exact row counts),
+         * and a scope provisioned earlier adds directory audit rows that push an older
+         * entry out of a bounded `auditLog` window upstream.
+         */
+        it('records WHY a consumer-emitted event exists, and nothing where there is no cause (#1237)', async () => {
+            // Its own scope: the shared one is where the dispatch tests assert exact row
+            // counts, and an extra `flow/produce` there would move them.
+            const sCause = scopeId.parse(ulid());
+            await host.provisionScope(staff, { tenantId: t1, scopeId: sCause, vertical: 'flow-vertical' });
+            await host.admin.activateScope(staff, t1, sCause);
+            const stub = await host.getScope(alice, t1, sCause);
+            await stub.invoke('flow/produce');
+            const rows = (await stub.invoke('flow/causes'));
+            const step1 = rows.find((r) => r.type === 'flow.step1');
+            const step2 = rows.find((r) => r.type === 'flow.step2');
+            // The operation's own event has no cause. Null here is the ordinary case — an
+            // operation emitted it directly — not a gap in the recording.
+            expect(step1.operation).toBe('flow/produce');
+            expect(step1.caused_by).toBeNull();
+            // THE EDGE. A consumer emit records no operation, so before this column the
+            // trail from step2 back to step1 was simply not written down and a backwards
+            // walk stopped at the first consumer hop.
+            expect(step2.operation).toBeNull();
+            expect(step2.caused_by).toBe(step1.id);
+            // And the pair is what identifies a consumer emit at all: `operation` alone is
+            // null both for a consumer and for a row written before that column existed.
+            expect(step2.operation === null && step2.caused_by !== null).toBe(true);
+        });
+        it('does not leak a delivered event\'s id onto a later unrelated emit (#1237)', async () => {
+            // The failure mode of a field held on the host across a dispatch: left set, the
+            // next operation's own event is stamped as caused by whatever was delivered
+            // last — a recorded fact that is false, which is worse than recording nothing.
+            const sLeak = scopeId.parse(ulid());
+            await host.provisionScope(staff, { tenantId: t1, scopeId: sLeak, vertical: 'flow-vertical' });
+            await host.admin.activateScope(staff, t1, sLeak);
+            const stub = await host.getScope(alice, t1, sLeak);
+            await stub.invoke('flow/produce'); // runs consumers, which set the field
+            await stub.invoke('flow/produce'); // must not inherit it
+            const rows = (await stub.invoke('flow/causes'));
+            const producedDirectly = rows.filter((r) => r.type === 'flow.step1');
+            expect(producedDirectly).toHaveLength(2);
+            for (const row of producedDirectly)
+                expect(row.caused_by).toBeNull();
+            // …and both consumer emits still name their own cause, so clearing the field
+            // did not simply turn the whole feature off.
+            const reactions = rows.filter((r) => r.type === 'flow.step2');
+            expect(reactions).toHaveLength(2);
+            expect(new Set(reactions.map((r) => r.caused_by)).size).toBe(2);
+        });
         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
@@ -3534,6 +3744,13 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             expect(rec.status).toBe('reaped');
             // getScope fails closed on the reaped scope, exactly like a missing one.
             await expect(host.getScope(alice, t3, s)).rejects.toThrow(/scope not active|unknown scope/);
+            // And so does every read that would OPEN that storage. The tombstone row still
+            // resolves, so an existence check alone lets these through — and opening a
+            // reaped scope does not read an empty database, it CREATES one, answering
+            // "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/);
             // 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);