@substrat-run/contract-tests 0.87.0 → 0.89.0

package/dist/entity-check-plan.js

@@ -0,0 +1,181 @@
+/** An operation declaring an entity-narrowed check — the ones in scope here. */
+function entityCheckOf(op) {
+    const permission = op.permission;
+    if (!permission || typeof permission === 'string')
+        return undefined;
+    return permission.entity || permission.entityFrom || permission.refFrom ? permission : undefined;
+}
+/**
+ * The values a schema admits, when it admits a knowable few.
+ *
+ * `z.literal('workorder')` and `z.literal(['workorder', 'protocol'])` publish a
+ * `values` Set; `z.enum([…])` publishes `options`. An open `z.string()` publishes
+ * neither, and that is the answer the caller needs — not a guess.
+ */
+function admissibleValues(schema) {
+    const values = schema.values;
+    if (values instanceof Set)
+        return [...values];
+    const options = schema.options;
+    if (Array.isArray(options))
+        return options;
+    return undefined;
+}
+/**
+ * The fields whose value the SCHEMA already fixes — one admissible value each.
+ *
+ * #890. A timeline operation declares `entity: 'workorder'` and takes
+ * `entityType: z.literal('workorder')`, so the fixture used to be handed
+ * `{ entityType: 'workorder' }` by hand: the same constant written twice, in two
+ * files, with nothing holding them together. Written as `'customer'` by mistake
+ * and case 1 fails claiming the handler checks the node — a false accusation
+ * against correct code, which is the kind of red that gets a suite disabled.
+ *
+ * So the kit reads the constant instead of being told it. A literal with more
+ * than one admissible value is deliberately NOT read: driving it means driving
+ * once per value, which is a different feature, and `.value` throws there rather
+ * than picking one.
+ */
+function fixedFields(op, idField) {
+    const shape = op.input?.shape;
+    if (!shape)
+        return {};
+    const fixed = {};
+    for (const [field, schema] of Object.entries(shape)) {
+        if (field === idField)
+            continue;
+        const values = admissibleValues(schema);
+        if (values?.length === 1)
+            fixed[field] = values[0];
+    }
+    return fixed;
+}
+/**
+ * The input fields an operation REQUIRES, beyond the one carrying the entity id.
+ *
+ * Read off the schema rather than asked for: an operation taking only an id
+ * needs no fixture entry, and one that needs more says so precisely instead of
+ * failing later as a validation error the reader has to decode.
+ *
+ * A field the schema fixes to one value is not one of them, nor is the type field
+ * an `entityFrom` check names — the kit supplies both, so demanding a sample
+ * input for either would report a gap that is not there.
+ */
+function requiredExtras(op, idField, supplied = []) {
+    const shape = op.input?.shape;
+    if (!shape)
+        return [];
+    const kitSupplies = new Set([idField, ...supplied, ...Object.keys(fixedFields(op, idField))]);
+    return Object.entries(shape)
+        .filter(([field]) => !kitSupplies.has(field))
+        .filter(([, schema]) => {
+        const parse = schema.safeParse;
+        // No `safeParse` means we cannot tell — treat it as required, because
+        // guessing "optional" is the answer that silently drops the operation.
+        return typeof parse !== 'function' || !parse.call(schema, undefined).success;
+    })
+        .map(([field]) => field);
+}
+/**
+ * Partition an operation set into what this kit can drive and what it cannot.
+ *
+ * Exported and pure so the classification is testable on its own. It is the part
+ * that decides what counts as covered, and a bug here is invisible in the worst
+ * way — it would drop an operation from the suite while every remaining test
+ * still passed.
+ *
+ * Out of scope entirely (neither covered nor uncovered): an operation with a
+ * bare-key node check, or one declaring `narrows`. Neither claims an entity
+ * check, so neither has one to honour.
+ *
+ * An `entityFrom` operation appears ONCE PER ADMISSIBLE TYPE (#890) — the pair is
+ * what tells a correct check from a node check, and it is worth no less for the
+ * second type than for the first. So `callout/timeline` is driven twice, over a
+ * work order and over a protocol, and a handler that honoured the check for one
+ * and not the other has nowhere left to hide.
+ */
+export function planEntityCheckCoverage(operations, inputs = {}, refEntityType) {
+    const covered = [];
+    const uncovered = {};
+    for (const [name, raw] of Object.entries(operations).sort(([a], [b]) => a.localeCompare(b))) {
+        const op = raw;
+        const check = entityCheckOf(op);
+        if (!check)
+            continue;
+        // The ref case first: it names neither a type nor an id field, because the
+        // field it names carries both (#896).
+        if (check.refFrom) {
+            const path = check.refFrom.split('.');
+            if (!refEntityType) {
+                uncovered[name] =
+                    `declares 'refFrom: ${check.refFrom}' and the suite named no 'refEntityType' — the ` +
+                        'check narrows to a type this module cannot know, so the harness has to say which ' +
+                        'one it can create';
+                continue;
+            }
+            if (!(path[0] in (op.input?.shape ?? {}))) {
+                uncovered[name] = `declares 'refFrom: ${check.refFrom}', which names no input field`;
+                continue;
+            }
+            const missing = requiredExtras(op, '', [path[0]]).filter((f) => inputs[name]?.[f] === undefined);
+            if (missing.length > 0) {
+                uncovered[name] = `no sample input for required field(s): ${missing.join(', ')}`;
+                continue;
+            }
+            covered.push({
+                name,
+                key: check.key,
+                entity: refEntityType,
+                target: { kind: 'ref', path },
+                fixed: fixedFields(op, path[0]),
+            });
+            continue;
+        }
+        if (!check.idFrom) {
+            uncovered[name] =
+                `declares 'resolved' (${check.resolved ?? 'no reason given'}) — the entity id is not ` +
+                    'in the input, so the harness cannot reach the entity';
+            continue;
+        }
+        // One fixed type, or the several the type field's schema admits (#890). An
+        // `entityFrom` pointing at a field that enumerates nothing is a gap with a
+        // name: the kit will not invent a type, because driving one arm of an
+        // operation and reporting the operation covered is the overclaim this whole
+        // suite exists to avoid.
+        let types;
+        if (check.entity) {
+            types = [check.entity];
+        }
+        else {
+            const field = check.entityFrom;
+            const values = admissibleValues(op.input?.shape?.[field]);
+            if (!values || values.length === 0) {
+                uncovered[name] =
+                    `declares 'entityFrom: ${field}', whose schema does not enumerate the types it ` +
+                        'admits — the kit cannot know which entity to create, and will not guess one';
+                continue;
+            }
+            types = values;
+        }
+        const typeField = check.entityFrom ? [check.entityFrom] : [];
+        const missing = requiredExtras(op, check.idFrom, typeField).filter((f) => inputs[name]?.[f] === undefined);
+        if (missing.length > 0) {
+            uncovered[name] = `no sample input for required field(s): ${missing.join(', ')}`;
+            continue;
+        }
+        for (const type of types) {
+            covered.push({
+                name,
+                key: check.key,
+                entity: String(type),
+                target: { kind: 'id', path: [check.idFrom] },
+                fixed: {
+                    ...fixedFields(op, check.idFrom),
+                    ...(check.entityFrom ? { [check.entityFrom]: type } : {}),
+                },
+            });
+        }
+    }
+    return { covered, uncovered };
+}
+//# sourceMappingURL=entity-check-plan.js.map

package/dist/entity-check-plan.js.map

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

package/dist/entity-check-suite.d.ts

@@ -1,93 +1,6 @@
-import type { EntityRef } from '@substrat-run/contracts';
-/** What a vertical supplies so the kit can drive its operations. */
-export interface EntityCheckFixture {
-    /**
-     * Create one entity of this declared type and return its id.
-     *
-     * Called for each case, so every case gets a world nobody else has touched —
-     * the operation under test may well delete the thing it is given.
-     */
-    createEntity(entityType: string): Promise<string>;
-    /**
-     * Grant `permission` to the probe principal, narrowed to exactly this entity.
-     *
-     * Deliberately NOT the vertical's own sharing operation: using `share-list` to
-     * set up the test for `share-list` would prove only that it agrees with
-     * itself. Reach for the admin grant.
-     */
-    grantOnEntity(permission: string, entity: EntityRef): Promise<void>;
-    /** Invoke as the probe principal — the one holding only narrowed grants. */
-    invoke(operation: string, input: Record<string, unknown>): Promise<unknown>;
-    /**
-     * Is this error a permission denial? Defaults to `PermissionDenied`, which is
-     * what a stub throws; a fixture driving HTTP would test for its 403 instead.
-     */
-    isDenial?(error: unknown): boolean;
-}
-export interface EntityCheckSuiteOptions {
-    /**
-     * Extra input fields per operation, beyond the entity id the kit supplies.
-     *
-     * Only needed where the operation's schema has REQUIRED fields besides the id
-     * — the kit reads the schema to find out, so an operation taking nothing but
-     * an id needs no entry here.
-     */
-    readonly inputs?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
-    /**
-     * Permissions an operation needs BEYOND the one it declares, granted on the
-     * same target entity — with the reason it needs them.
-     *
-     * The first vertical this kit ran against produced one immediately.
-     * `todo/share-list` declares `list:manage` and honours it, then calls
-     * `ctx.grant` to hand `list:contribute` to the invitee — and delegation only
-     * works for a permission the caller HOLDS. A principal granted `list:manage`
-     * alone is refused, correctly, by the second gate.
-     *
-     * So an operation's declared permission is the gate it opens with, not
-     * necessarily the whole authority it exercises. That gap is invisible in
-     * production here only because todo's bootstrap grant hands every owner both
-     * keys on their own entity, so nobody ever holds one without the other.
-     *
-     * `because` is required rather than a comment: this is the one place the gap
-     * gets written down, and an entry without a reason is indistinguishable from
-     * someone widening the grant until the test went green.
-     */
-    readonly alsoGrant?: Readonly<Record<string, {
-        readonly permissions: readonly string[];
-        readonly because: string;
-    }>>;
-    /**
-     * The in-scope operations this kit cannot generate, each with its reason.
-     *
-     * Asserted EXACTLY: an operation that becomes uncoverable, or one that stops
-     * being, fails until this list is updated. That is the point — it is the
-     * coverage gap made reviewable rather than invisible.
-     */
-    readonly uncovered?: Readonly<Record<string, string>>;
-}
-/** One operation the kit can drive, with the declaration it was read from. */
-export interface PlannedCheck {
-    readonly name: string;
-    readonly key: string;
-    readonly entity: string;
-    readonly idFrom: string;
-}
-/**
- * Partition an operation set into what this kit can drive and what it cannot.
- *
- * Exported and pure so the classification is testable on its own. It is the part
- * that decides what counts as covered, and a bug here is invisible in the worst
- * way — it would drop an operation from the suite while every remaining test
- * still passed.
- *
- * Out of scope entirely (neither covered nor uncovered): an operation with a
- * bare-key node check, or one declaring `narrows`. Neither claims an entity
- * check, so neither has one to honour.
- */
-export declare function planEntityCheckCoverage(operations: Readonly<Record<string, object>>, inputs?: Readonly<Record<string, Readonly<Record<string, unknown>>>>): {
-    covered: PlannedCheck[];
-    uncovered: Record<string, string>;
-};
+export type { EntityCheckFixture, EntityCheckSuiteOptions, PlannedCheck } from './entity-check-plan.js';
+export { planEntityCheckCoverage } from './entity-check-plan.js';
+import type { EntityCheckFixture, EntityCheckSuiteOptions } from './entity-check-plan.js';
 /**
  * Generate the conformance pair for every operation declaring an entity check.
  *

package/dist/entity-check-suite.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entity-check-suite.d.ts","sourceRoot":"","sources":["../src/entity-check-suite.ts"],"names":[],"mappings":"AA6DA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAGzD,oEAAoE;AACpE,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD;;;;;;OAMG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpE,4EAA4E;IAC5E,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5E;;;OAGG;IACH,QAAQ,CAAC,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC;CACpC;AAED,MAAM,WAAW,uBAAuB;IACtC;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9E;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAC3B,MAAM,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CACtF,CAAC;IACF;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACvD;AA0CD,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAC5C,MAAM,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAM,GACvE;IAAE,OAAO,EAAE,YAAY,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAuBhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAC5C,WAAW,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,EAC9C,OAAO,GAAE,uBAA4B,GACpC,IAAI,CAkGN"}
+{"version":3,"file":"entity-check-suite.d.ts","sourceRoot":"","sources":["../src/entity-check-suite.ts"],"names":[],"mappings":"AA+DA,YAAY,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACxG,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAG1F;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EAC5C,WAAW,EAAE,MAAM,OAAO,CAAC,kBAAkB,CAAC,EAC9C,OAAO,GAAE,uBAA4B,GACpC,IAAI,CA2IN"}

package/dist/entity-check-suite.js

@@ -60,69 +60,8 @@
  */
 import { describe, expect, it } from 'vitest';
 import { PermissionDenied } from '@substrat-run/kernel';
-/** An operation declaring an entity-narrowed check — the ones in scope here. */
-function entityCheckOf(op) {
-    const permission = op.permission;
-    if (!permission || typeof permission === 'string')
-        return undefined;
-    return permission.entity ? permission : undefined;
-}
-/**
- * The input fields an operation REQUIRES, beyond the one carrying the entity id.
- *
- * Read off the schema rather than asked for: an operation taking only an id
- * needs no fixture entry, and one that needs more says so precisely instead of
- * failing later as a validation error the reader has to decode.
- */
-function requiredExtras(op, idField) {
-    const shape = op.input?.shape;
-    if (!shape)
-        return [];
-    return Object.entries(shape)
-        .filter(([field]) => field !== idField)
-        .filter(([, schema]) => {
-        const parse = schema.safeParse;
-        // No `safeParse` means we cannot tell — treat it as required, because
-        // guessing "optional" is the answer that silently drops the operation.
-        return typeof parse !== 'function' || !parse.call(schema, undefined).success;
-    })
-        .map(([field]) => field);
-}
-/**
- * Partition an operation set into what this kit can drive and what it cannot.
- *
- * Exported and pure so the classification is testable on its own. It is the part
- * that decides what counts as covered, and a bug here is invisible in the worst
- * way — it would drop an operation from the suite while every remaining test
- * still passed.
- *
- * Out of scope entirely (neither covered nor uncovered): an operation with a
- * bare-key node check, or one declaring `narrows`. Neither claims an entity
- * check, so neither has one to honour.
- */
-export function planEntityCheckCoverage(operations, inputs = {}) {
-    const covered = [];
-    const uncovered = {};
-    for (const [name, raw] of Object.entries(operations).sort(([a], [b]) => a.localeCompare(b))) {
-        const op = raw;
-        const check = entityCheckOf(op);
-        if (!check)
-            continue;
-        if (!check.idFrom) {
-            uncovered[name] =
-                `declares 'resolved' (${check.resolved ?? 'no reason given'}) — the entity id is not ` +
-                    'in the input, so the harness cannot reach the entity';
-            continue;
-        }
-        const missing = requiredExtras(op, check.idFrom).filter((f) => inputs[name]?.[f] === undefined);
-        if (missing.length > 0) {
-            uncovered[name] = `no sample input for required field(s): ${missing.join(', ')}`;
-            continue;
-        }
-        covered.push({ name, key: check.key, entity: check.entity, idFrom: check.idFrom });
-    }
-    return { covered, uncovered };
-}
+export { planEntityCheckCoverage } from './entity-check-plan.js';
+import { planEntityCheckCoverage } from './entity-check-plan.js';
 /**
  * Generate the conformance pair for every operation declaring an entity check.
  *
@@ -137,7 +76,7 @@ export function entityCheckConformanceSuite(subjectName, operations, makeFixture
     const declaredUncovered = options.uncovered ?? {};
     const supplied = options.inputs ?? {};
     // Partitioned at collection time so the generated tests can be named.
-    const { covered, uncovered } = planEntityCheckCoverage(operations, supplied);
+    const { covered, uncovered } = planEntityCheckCoverage(operations, supplied, options.refEntityType);
     describe(`declared entity checks are honoured: ${subjectName}`, () => {
         it('covers every entity check it can, and names every one it cannot', () => {
             // The whole partition asserted at once. A new operation with an entity
@@ -157,9 +96,41 @@ export function entityCheckConformanceSuite(subjectName, operations, makeFixture
             // the zero guard: silence must not read as success.
             expect(covered.length).toBeGreaterThan(0);
         });
-        for (const { name, key, entity, idFrom } of covered) {
-            describe(`${name} — ${key} on ${entity}, id from '${idFrom}'`, () => {
-                const extras = supplied[name] ?? {};
+        for (const { name, key, entity, target, fixed } of covered) {
+            const where = target.kind === 'ref'
+                ? `ref from '${target.path.join('.')}'`
+                : `id from '${target.path[0]}'`;
+            /**
+             * The input the pair is driven with. A `refFrom` check is handed the whole
+             * ref — which is the assertion, since an engine declaring this shape claims
+             * to honour whatever noun arrives.
+             */
+            const inputFor = (entityId, extras) => {
+                const value = target.kind === 'ref' ? { entityType: entity, entityId } : entityId;
+                const [head, ...rest] = target.path;
+                if (rest.length === 0)
+                    return { ...extras, [head]: value };
+                // One level in: the ref travels beside other fields the caller supplied,
+                // so the sibling keys the fixture gave for that object are preserved.
+                const outer = (extras[head] ?? {});
+                return { ...extras, [head]: { ...outer, [rest.join('.')]: value } };
+            };
+            describe(`${name} — ${key} on ${entity}, ${where}`, () => {
+                /**
+                 * Schema-fixed constants first, so an explicit fixture entry still wins —
+                 * it is the reviewable way to say "this one needs something else".
+                 *
+                 * Read per CASE, not once per describe. A fixture entry legitimately
+                 * holds a value that does not exist yet at collect time: rally's spare
+                 * member is created in `beforeAll` and written into the object the kit
+                 * was handed, which is the documented way to supply an id the harness
+                 * must make first. Spreading in the describe body captured the empty
+                 * placeholder instead, and nothing said so — case 1 only asserts "was
+                 * not denied", and case 2's permission answer arrived before anything
+                 * looked at the field. Once the host parses a declared input (#893) the
+                 * same fixture fails the parse, which is what surfaced this.
+                 */
+                const extrasNow = () => ({ ...fixed, ...(supplied[name] ?? {}) });
                 const extraKeys = options.alsoGrant?.[name]?.permissions ?? [];
                 /**
                  * The declared key on the target, plus anything the operation needs to
@@ -188,9 +159,9 @@ export function entityCheckConformanceSuite(subjectName, operations, makeFixture
                 };
                 it('allows a principal granted on THAT entity (the node-check catcher)', async () => {
                     const fixture = await makeFixture();
-                    const target = await fixture.createEntity(entity);
-                    await grantAllOn(fixture, target);
-                    const outcome = await denialFrom(fixture, { ...extras, [idFrom]: target });
+                    const targetId = await fixture.createEntity(entity);
+                    await grantAllOn(fixture, targetId);
+                    const outcome = await denialFrom(fixture, inputFor(targetId, extrasNow()));
                     const denied = outcome !== undefined && !outcome.notADenial;
                     expect(denied, `${name} denied a principal holding ${key} on the very ${entity} it was ` +
                         'invoked against — the handler is checking the node, not the entity').toBe(false);
@@ -202,7 +173,7 @@ export function entityCheckConformanceSuite(subjectName, operations, makeFixture
                     const granted = await fixture.createEntity(entity);
                     await grantAllOn(fixture, granted);
                     const other = await fixture.createEntity(entity);
-                    const outcome = await denialFrom(fixture, { ...extras, [idFrom]: other });
+                    const outcome = await denialFrom(fixture, inputFor(other, extrasNow()));
                     const notADenial = outcome?.notADenial;
                     expect(outcome, `${name} allowed a principal to reach a ${entity} they hold no grant on`).toBeDefined();
                     expect(notADenial, `${name} failed against an ungranted ${entity}, but not with a permission ` +

package/dist/entity-check-suite.js.map

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

package/dist/entity-version-suite.d.ts

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

package/dist/entity-version-suite.d.ts.map

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

package/dist/entity-version-suite.js

@@ -0,0 +1,160 @@
+/**
+ * Contract suite for `ctx.versionOf` — an entity's version (#901).
+ *
+ * What it pins: **the version was already being written.** No entity table has a
+ * version column and none is going to; `_substrat_outbox` has recorded
+ * `entity_type` and `entity_id` against a monotonic ULID since it was written,
+ * so every mutation that followed the fat-event rule already versioned the thing
+ * it touched. This suite is what holds both adapters to that reading.
+ *
+ * The assertions are behavioural for the reason the search suite gives: an
+ * emitter or a query that reads correctly can still be wrong against a real
+ * database, and a string comparison would call it a pass. So every case here
+ * provisions a real scope, emits real events, and asks a real question.
+ *
+ * Two of these cases are the interesting ones, and neither is about the happy
+ * path:
+ *
+ * - **A shred must not take the version with it.** The payload goes, the row
+ *   stays, and an erased entity can still refuse a stale write. A version that
+ *   vanished with the data would fail OPEN at exactly the moment the data was
+ *   most sensitive.
+ * - **A silent mutation does not move it.** That is the documented hole, pinned
+ *   here deliberately so it stays a known property. The fix is a compile-checked
+ *   `concurrency` against the operation's declared `emits` (#129) — not a change
+ *   to this behaviour.
+ */
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { dataSubjectId, permissionKey, platformActorId, principalId, scopeId, tenantId, } from '@substrat-run/contracts';
+import { ulid } from '@substrat-run/kernel';
+import { contractTestBareOps, testMod } from './modules.js';
+const PERM_USE = permissionKey.parse('testmod:use');
+export function entityVersionContractSuite(adapterName, makeFixture) {
+    describe(`entity version (ctx.versionOf): ${adapterName}`, () => {
+        let fixture;
+        let host;
+        let stub;
+        const t1 = tenantId.parse(ulid());
+        const s1 = scopeId.parse(ulid());
+        const alice = principalId.parse(ulid());
+        const staff = platformActorId.parse(ulid());
+        const versionOf = (entityId, entityType = 'test-thing') => stub.invoke('test/version-of', { entityType, entityId });
+        const emitAbout = (entityId, subject) => stub.invoke('test/emit-about', { entityId, ...(subject ? { subject } : {}) });
+        beforeAll(async () => {
+            fixture = await makeFixture();
+            host = fixture.host;
+            for (const [name, handler] of Object.entries(contractTestBareOps)) {
+                host.defineOperation(name, handler);
+            }
+            host.registerModule(testMod);
+            await host.admin.createTenant(staff, { id: t1, slug: 'version-tenant', name: 'Version Tenant' });
+            await host.admin.grantEntitlement(staff, t1, 'testmod');
+            await host.admin.defineRole(staff, t1, {
+                key: 'version-admin',
+                permissions: [PERM_USE],
+                source: 'vertical',
+            });
+            await host.admin.assignRole(staff, {
+                principalId: alice,
+                roleKey: 'version-admin',
+                node: { tenantId: t1, scopeId: null },
+            });
+            await host.provisionScope(staff, { tenantId: t1, scopeId: s1, vertical: 'version-vertical' });
+            await host.admin.activateScope(staff, t1, s1);
+            stub = await host.getScope(alice, t1, s1);
+        });
+        afterAll(async () => {
+            await fixture.cleanup();
+        });
+        it('is absent for an entity nothing has emitted about', async () => {
+            // Absence, not a throw and not an empty string: `MAX(id)` over no rows is
+            // NULL, and the caller distinguishes "never touched" from "touched" on the
+            // value alone. A precondition against an entity with no history has nothing
+            // to compare and must be able to see that.
+            expect(await versionOf('never-touched')).toBeNull();
+        });
+        it('appears on the first event and moves on every one after', async () => {
+            const id = `e-${ulid()}`;
+            expect(await versionOf(id)).toBeNull();
+            await emitAbout(id);
+            const first = await versionOf(id);
+            expect(first).not.toBeNull();
+            await emitAbout(id);
+            const second = await versionOf(id);
+            expect(second).not.toBe(first);
+            // ULIDs are lexicographically ordered, and `ulid()` uses the monotonic
+            // factory — so two events in the SAME millisecond still compare in creation
+            // order. Without that this assertion would flake rather than fail, which is
+            // the worst way for it to be wrong.
+            expect(second > first).toBe(true);
+        });
+        it('is stable across reads that change nothing', async () => {
+            const id = `e-${ulid()}`;
+            await emitAbout(id);
+            const a = await versionOf(id);
+            const b = await versionOf(id);
+            const c = await versionOf(id);
+            expect(b).toBe(a);
+            expect(c).toBe(a);
+        });
+        it('is per entity — an event about one does not move another', async () => {
+            const left = `e-${ulid()}`;
+            const right = `e-${ulid()}`;
+            await emitAbout(left);
+            await emitAbout(right);
+            const leftBefore = await versionOf(left);
+            await emitAbout(right);
+            // The scope's newest event is now about `right`. If the query were reading
+            // the outbox head rather than the entity's own last row, this would move.
+            expect(await versionOf(left)).toBe(leftBefore);
+            expect(await versionOf(right)).not.toBe(leftBefore);
+        });
+        it('distinguishes two entities that share an id under different types', async () => {
+            const shared = `e-${ulid()}`;
+            await emitAbout(shared);
+            const asThing = await versionOf(shared, 'test-thing');
+            // Nothing has emitted about this id under the OTHER type, so the pair is
+            // what identifies the row — not the id alone.
+            expect(await versionOf(shared, 'other-thing')).toBeNull();
+            expect(asThing).not.toBeNull();
+        });
+        it('reflects an emit made earlier in the same operation', async () => {
+            const id = `e-${ulid()}`;
+            const { before, after } = await stub.invoke('test/emit-then-version', { entityId: id });
+            // Read-after-write within one operation. This holds because `emit` writes
+            // the outbox row inline rather than buffering to commit — the same property
+            // the search index depends on, and worth pinning where it can regress.
+            expect(before).toBeNull();
+            expect(after).not.toBeNull();
+        });
+        it('survives a shred — the payload goes, the version stays', async () => {
+            const id = `e-${ulid()}`;
+            const subject = dataSubjectId.parse(ulid());
+            await emitAbout(id, subject);
+            const before = await versionOf(id);
+            expect(before).not.toBeNull();
+            const receipt = await host.admin.shredSubject(staff, t1, s1, subject);
+            expect(receipt.eventsRedacted).toBe(1);
+            // The whole point. An erasure nulls the payload and keeps the envelope, so
+            // the version token outlives the data it described. Were it to go null here,
+            // a stale write against an erased entity would be admitted rather than
+            // refused — failing open at the worst possible moment.
+            expect(await versionOf(id)).toBe(before);
+        });
+        it('does NOT move for a mutation that emits nothing', async () => {
+            const id = `e-${ulid()}`;
+            await emitAbout(id);
+            const before = await versionOf(id);
+            await stub.invoke('test/mutate-silently', {});
+            // The documented hole, pinned so it stays known. "Every mutation emits a fat
+            // event" is enforced by review, not by boundary-lint, and this is what that
+            // costs: a version that did not move because nobody announced the change.
+            // The answer is a `concurrency` declaration compile-checked against the
+            // operation's declared `emits` (#129) — strictly more than a version column
+            // with a trigger would have given, which guarantees the column moved but
+            // never that the operation said what it did.
+            expect(await versionOf(id)).toBe(before);
+        });
+    });
+}
+//# sourceMappingURL=entity-version-suite.js.map