@substrat-run/contract-tests 0.23.0 → 0.25.0

package/dist/scope-host-suite.js

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
 import { connectorCalls, connectorTestFetch, resetConnectorCalls } from './connector-fixture.js';
-import { connectionId, moduleManifest, orgId, AUTO_ADMISSION_NOTE, platformActorId, principalId, scopeId, tenantId, SCOPE_QUERY_ROW_MAX, } from '@substrat-run/contracts';
+import { connectionId, moduleManifest, orgId, AUTO_ADMISSION_NOTE, permissionKey, platformActorId, principalId, scopeId, tenantId, SCOPE_QUERY_ROW_MAX, } from '@substrat-run/contracts';
 import { runPlatformSweep, ulid } from '@substrat-run/kernel';
 import { billedMod, contractTestBareOps, contractTestInitialModules, gateModManifest, lateMod, testModManifest, victimModManifest, } from './modules.js';
 /**
@@ -561,6 +561,37 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                 const vCol = page.columns.indexOf('v');
                 expect(page.rows.map((r) => r[vCol])).toContain('post-restore-write');
             });
+            it('accepts a dump missing kernel-spine tables — the spine is re-asserted, not left absent (#321)', async () => {
+                // A backup captured from a WORLD that stores some `_substrat_*` tables ELSEWHERE
+                // (an `@substrat-run/adapter-sqlite` scope file keeps roles/tuples in its DIRECTORY
+                // db), or simply a partial dump, omits spine tables the target must have. Before
+                // #321 the restore's frontier refresh read `_substrat_migrations` straight after the
+                // replay and raised a bare `no such table` → a detail-less 500. Restore must instead
+                // re-create the missing spine (empty) so the load completes.
+                //
+                // A dedicated throwaway scope: the stripped restore drops this scope's migration
+                // frontier, so it must not be one the rest of the shared suite depends on.
+                const spineScope = scopeId.parse(ulid());
+                await host.provisionScope(staff, {
+                    tenantId: t1,
+                    scopeId: spineScope,
+                    jurisdiction: 'eu',
+                    vertical: 'connector-vertical',
+                });
+                await host.admin.activateScope(staff, t1, spineScope);
+                const backup = await host.admin.exportScope(staff, t1, spineScope);
+                expect(backup.tables.some((t) => t.name === '_substrat_migrations')).toBe(true);
+                const stripped = {
+                    ...backup,
+                    tables: backup.tables.filter((t) => t.name !== '_substrat_migrations'),
+                };
+                // Pre-#321 this rejected (the frontier read hit `no such table`); now it completes.
+                await expect(host.restoreScope(staff, t1, spineScope, stripped)).resolves.toBeUndefined();
+                // The spine is present, not absent — introspection reads the scope without crashing,
+                // and the re-created `_substrat_migrations` is back.
+                const tables = await host.admin.listScopeTables(staff, t1, spineScope);
+                expect(tables.some((t) => t.name === '_substrat_migrations')).toBe(true);
+            });
         });
         // -- snapshot & auto-snapshot on bind (preview-and-snapshots.md §3/§4) -----
         //
@@ -1723,6 +1754,126 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             // s3 is active — you cannot un-archive an active scope.
             await expect(host.admin.unarchiveScope(staff, t3, s3)).rejects.toThrow(/illegal scope transition/);
         });
+        // -- reap: the terminal storage wipe (control-plane.md §4.4) ---------------
+        it('archive stamps archivedAt; unarchive clears it (§4.4)', async () => {
+            const s = scopeId.parse(ulid());
+            await host.provisionScope(staff, { tenantId: t3, scopeId: s, jurisdiction: 'eu' });
+            await host.admin.activateScope(staff, t3, s);
+            // Active: no archival timestamp yet.
+            const [active] = await host.admin.listScopes(staff, { tenantId: t3, status: ['active'] }).then((rows) => rows.filter((r) => r.id === s));
+            expect(active?.archivedAt).toBeNull();
+            // Archiving stamps it…
+            await host.admin.archiveScope(staff, t3, s);
+            const archived = (await host.admin.getScopeRecord(staff, t3, s));
+            expect(archived.status).toBe('archived');
+            expect(archived.archivedAt).not.toBeNull();
+            // …and un-archiving (a restore) clears it, so a later re-archive dates fresh.
+            await host.admin.unarchiveScope(staff, t3, s);
+            const restored = (await host.admin.getScopeRecord(staff, t3, s));
+            expect(restored.archivedAt).toBeNull();
+        });
+        it('reapScope wipes storage, keeps the tombstone row, and fails getScope closed (§4.4)', async () => {
+            const s = scopeId.parse(ulid());
+            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 host.admin.archiveScope(staff, t3, s);
+            await host.admin.reapScope(staff, t3, s);
+            // The directory row SURVIVES as a tombstone, now `reaped`.
+            const rec = (await host.admin.getScopeRecord(staff, t3, s));
+            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/);
+            // 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);
+        });
+        it('a reaped scope releases its slug for reuse; reap is terminal (§4.4)', async () => {
+            const s = scopeId.parse(ulid());
+            await host.provisionScope(staff, { tenantId: t3, scopeId: s, slug: 'recyclable', jurisdiction: 'eu' });
+            await host.admin.activateScope(staff, t3, s);
+            await host.admin.archiveScope(staff, t3, s);
+            await host.admin.reapScope(staff, t3, s);
+            // The name is free again: a fresh scope may claim the reaped scope's slug.
+            const fresh = scopeId.parse(ulid());
+            await host.provisionScope(staff, { tenantId: t3, scopeId: fresh, slug: 'recyclable', jurisdiction: 'eu' });
+            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/);
+        });
+        // -- tenant delete lifecycle (control-plane.md §4.8) ----------------------
+        it('delete stamps deletingAt and fails getScope closed; un-delete restores (§4.8)', async () => {
+            const t = tenantId.parse(ulid());
+            const s = scopeId.parse(ulid());
+            await host.admin.createTenant(staff, { id: t, slug: `del-${t.toLowerCase()}`, name: 'Del' });
+            await host.provisionScope(staff, { tenantId: t, scopeId: s, jurisdiction: 'eu' });
+            await host.admin.activateScope(staff, t, s);
+            await expect(host.getScope(alice, t, s)).resolves.toBeDefined();
+            // Entering `deleting` stamps deletingAt and fails the scope closed (like suspend).
+            await host.admin.setTenantStatus(staff, t, 'deleting');
+            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/);
+            // 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));
+            expect(restored.status).toBe('active');
+            expect(restored.deletingAt).toBeNull();
+            await expect(host.getScope(alice, t, s)).resolves.toBeDefined();
+        });
+        it('reapTenant clears PII/config rows, keeps the tombstone + admin log, fails closed (§4.8)', async () => {
+            const t = tenantId.parse(ulid());
+            const s = scopeId.parse(ulid());
+            const org = orgId.parse(ulid());
+            const person = principalId.parse(ulid());
+            await host.admin.createTenant(staff, { id: t, slug: `reap-${t.toLowerCase()}`, name: 'Reap Co' });
+            await host.provisionScope(staff, { tenantId: t, scopeId: s, jurisdiction: 'eu' });
+            await host.admin.activateScope(staff, t, s);
+            // Seed the directory-side rows a reap must clear.
+            await host.admin.defineRole(staff, t, { key: 'tech', permissions: [permissionKey.parse('thing:read')], source: 'vertical' });
+            await host.admin.grantEntitlement(staff, t, 'workorder');
+            await host.admin.createOrg(staff, { id: org, tenantId: t, slug: 'acme', name: 'Acme' });
+            await host.admin.registerIdentityPool(staff, { provider: `oidc:reap-${t.toLowerCase()}`, topology: 'tenant-bound', tenantId: t });
+            await host.admin.linkIdentity(staff, { provider: `oidc:reap-${t.toLowerCase()}`, externalId: 'x1', principal: person, tenantId: t });
+            expect(await host.admin.listEntitlements(staff, t)).toHaveLength(1);
+            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/);
+            // 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');
+            await host.admin.archiveScope(staff, t, s);
+            await host.admin.reapScope(staff, t, s);
+            await host.admin.reapTenant(staff, t);
+            // The tenant row SURVIVES as a `reaped` tombstone…
+            const tomb = (await host.admin.getTenant(staff, t));
+            expect(tomb.status).toBe('reaped');
+            expect(tomb.slug).toBe(`reap-${t.toLowerCase()}`); // slug stays burned
+            // …its scope fails closed like a missing one…
+            await expect(host.getScope(alice, t, s)).rejects.toThrow(/not active|unknown scope/);
+            // …and the PII/config rows are gone.
+            expect(await host.admin.listEntitlements(staff, t)).toHaveLength(0);
+            expect((await host.admin.listOrgs(staff, t)).filter((o) => o.id === org)).toHaveLength(0);
+            expect(await host.admin.resolveIdentity(t, `oidc:reap-${t.toLowerCase()}`, 'x1')).toBeUndefined();
+            // The admin log is KEPT WHOLE — the witness outlives the tenant — and records the reap.
+            const log = await host.admin.auditLog(staff, { tenantId: t });
+            expect(log.some((r) => r.action === 'createTenant')).toBe(true);
+            const reapEntry = log.find((r) => r.action === 'reapTenant');
+            expect(reapEntry.actor).toBe(staff);
+            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/);
+        });
+        it('rejects reapTenant on an unknown tenant', async () => {
+            await expect(host.admin.reapTenant(staff, tenantId.parse(ulid()))).rejects.toThrow(/unknown tenant/);
+        });
         it('rejects a lifecycle transition on a scope not under the named tenant', async () => {
             await expect(host.admin.suspendScope(staff, t1, s3)).rejects.toThrow(/unknown scope for tenant/);
         });
@@ -1738,11 +1889,84 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
             // Granting the flag loads the module for this tenant.
             await host.admin.grantEntitlement(staff, t4, 'billed');
             await expect(stub.invoke('billed/act')).resolves.toBe('ran');
-            expect(await host.admin.listEntitlements(staff, t4)).toContain('billed');
+            const held = await host.admin.listEntitlements(staff, t4);
+            expect(held.map((e) => e.entitlementKey)).toContain('billed');
+            // A bare grant is #33's null plan: a perpetual boolean flag, stamped.
+            const billed = held.find((e) => e.entitlementKey === 'billed');
+            expect(billed.expiresAt).toBeNull();
+            expect(billed.quota).toBeNull();
+            expect(billed.plan).toBeNull();
+            expect(billed.grantedBy).toBe(staff);
+            expect(billed.grantedAt).not.toBeNull();
             // Revoking it takes the operation away again — as if never registered.
             await host.admin.revokeEntitlement(staff, t4, 'billed');
             await expect(stub.invoke('billed/act')).rejects.toThrow(/not entitled/);
-            expect(await host.admin.listEntitlements(staff, t4)).not.toContain('billed');
+            expect((await host.admin.listEntitlements(staff, t4)).map((e) => e.entitlementKey)).not.toContain('billed');
+        });
+        it('fails closed on an expired grant, which stays listed for renewal (#33)', async () => {
+            const stub = await host.getScope(alice, t4, s4);
+            const past = new Date(Date.now() - 60_000).toISOString();
+            const future = new Date(Date.now() + 3_600_000).toISOString();
+            // A grant that has lapsed gates exactly like a revoke…
+            await host.admin.grantEntitlement(staff, t4, 'billed', { expiresAt: past });
+            await expect(stub.invoke('billed/act')).rejects.toThrow(/not entitled/);
+            // …but the row is NOT gone: a lapsed trial must look lapsed, not never-granted.
+            const lapsed = (await host.admin.listEntitlements(staff, t4)).find((e) => e.entitlementKey === 'billed');
+            expect(lapsed?.expiresAt).toBe(past);
+            // Renewal is just a re-grant with a live expiry.
+            await host.admin.grantEntitlement(staff, t4, 'billed', { expiresAt: future });
+            await expect(stub.invoke('billed/act')).resolves.toBe('ran');
+            await host.admin.revokeEntitlement(staff, t4, 'billed');
+        });
+        it('round-trips plan fields, preserves them on a bare re-grant, clears on null (#33)', async () => {
+            await host.admin.grantEntitlement(staff, t4, 'billed', {
+                expiresAt: new Date(Date.now() + 3_600_000).toISOString(),
+                quota: 500,
+                plan: 'pro',
+            });
+            const read = async () => (await host.admin.listEntitlements(staff, t4)).find((e) => e.entitlementKey === 'billed');
+            let g = await read();
+            expect(g.quota).toBe(500);
+            expect(g.plan).toBe('pro');
+            expect(g.expiresAt).not.toBeNull();
+            // A bare re-grant (the idempotent provisioning path) must NOT erase the
+            // plan — omitted preserves; only explicit null clears.
+            await host.admin.grantEntitlement(staff, t4, 'billed');
+            g = await read();
+            expect(g.quota).toBe(500);
+            expect(g.plan).toBe('pro');
+            expect(g.expiresAt).not.toBeNull();
+            await host.admin.grantEntitlement(staff, t4, 'billed', { expiresAt: null, quota: null, plan: null });
+            g = await read();
+            expect(g.expiresAt).toBeNull();
+            expect(g.quota).toBeNull();
+            expect(g.plan).toBeNull();
+            await host.admin.revokeEntitlement(staff, t4, 'billed');
+        });
+        it('exposes the tenant grant to an operation via ctx.entitlement, dropping expired keys (#304)', async () => {
+            const stub = await host.getScope(alice, t4, s4);
+            const future = new Date(Date.now() + 3_600_000).toISOString();
+            // Hold 'billed' so the (billed-gated) read operation itself resolves, granted with a full plan.
+            await host.admin.grantEntitlement(staff, t4, 'billed', { expiresAt: future, quota: 500, plan: 'pro' });
+            // The held grant reads back as a view — the plan/quota/expiry a vertical gates features on.
+            expect(await stub.invoke('billed/read-entitlement', 'billed')).toEqual({
+                key: 'billed',
+                plan: 'pro',
+                quota: 500,
+                expiresAt: future,
+            });
+            // ctx.entitlements() lists every currently-held grant as a view.
+            const all = (await stub.invoke('billed/list-entitlements')) ?? [];
+            expect(all.map((e) => e.key)).toContain('billed');
+            // A key the tenant does not hold reads as null — the vertical branches on it, no throw.
+            expect(await stub.invoke('billed/read-entitlement', 'never-granted')).toBeNull();
+            // An expired grant is dropped at read, exactly as it is dropped at the gate (#33).
+            await host.admin.grantEntitlement(staff, t4, 'aux-sku', {
+                expiresAt: new Date(Date.now() - 60_000).toISOString(),
+            });
+            expect(await stub.invoke('billed/read-entitlement', 'aux-sku')).toBeNull();
+            await host.admin.revokeEntitlement(staff, t4, 'billed');
+            await host.admin.revokeEntitlement(staff, t4, 'aux-sku');
         });
         it('audits grant/revoke idempotently and records the SKU flag', async () => {
             // Re-grant twice: only the first is a real change, so only one row.
@@ -1752,6 +1976,19 @@ export function scopeHostContractSuite(adapterName, makeFixture, opts = {}) {
                 r.after.entitlementKey === 'audited-sku');
             expect(grants).toHaveLength(1);
             expect(grants[0].actor).toBe(staff);
+            // A re-grant that CHANGES the plan is a renewal — audited, with the old
+            // plan in `before` (#33). The audit row is the grant's history.
+            const until = new Date(Date.now() + 3_600_000).toISOString();
+            await host.admin.grantEntitlement(staff, t4, 'audited-sku', { expiresAt: until, plan: 'pro' });
+            const renewals = (await host.admin.auditLog(staff, { tenantId: t4 })).filter((r) => r.action === 'grantEntitlement' &&
+                r.after.entitlementKey === 'audited-sku');
+            expect(renewals).toHaveLength(2);
+            const renewal = renewals[renewals.length - 1];
+            expect(renewal.before.plan).toBeNull();
+            expect(renewal.after).toMatchObject({
+                plan: 'pro',
+                expiresAt: until,
+            });
             await host.admin.revokeEntitlement(staff, t4, 'audited-sku');
             const revokes = (await host.admin.auditLog(staff, { tenantId: t4 })).filter((r) => r.action === 'revokeEntitlement');
             expect(revokes.length).toBeGreaterThanOrEqual(1);