@lovrozagar/oat 0.7.3 → 0.7.5

package/dist/runtime/checks.js

@@ -15,8 +15,10 @@ import { describeFeatureGate, isDocumentedFeatureGateDenial, reportFeatureGateSc
 import { driveAsync, inspectStreamAsync, matchesPredicate, resolveAsyncId } from "./async.js";
 import { resolveOutOfBandValue } from "./auth.js";
 import { buildCohort } from "./fixture.js";
+import { forEachInvocation } from "./upload-each.js";
 import { driveWait } from "./wait.js";
 import { fillPath } from "./world.js";
+import { bindAfterCreateEffects, bindCreatedScope, bindMissingPathParams, canFillPath, describeEffectHold, effectHolds, identityPathParam, } from "./effects.js";
 /* ------------------------------------------------------------------- helpers */
 /**
  * A documented feature-gate 403 is not a 2xx-check failure and not SECURITY.
@@ -3170,13 +3172,18 @@ function bodyForOp(ctx, op) {
         body[spec.granteeField] = delegate.inviteAs;
     return body;
 }
+function subject(entity, operationId, fixture) {
+    if (fixture === undefined)
+        return entity;
+    return `${operationId} · ${fixture}`;
+}
 function requestSchemaOf(ctx, op) {
     const raw = ctx.model.rawOperations.get(op.operationId);
     const picked = raw === undefined ? null : requestContent(raw);
     return picked === null ? null : picked.schema;
 }
-async function encodeOpBody(ctx, op, fields, variant = "baseline", index = 0) {
-    const encoded = await encodeForOperation(op, ctx.model, fields, ctx.uploads, variant, index);
+async function encodeOpBody(ctx, op, fields, variant = "baseline", index = 0, uploads = ctx.uploads) {
+    const encoded = await encodeForOperation(op, ctx.model, fields, uploads, variant, index);
     return encoded.contentType === undefined
         ? { body: encoded.body }
         : { body: encoded.body, contentType: encoded.contentType };
@@ -3259,11 +3266,15 @@ function findConstrained(schema, predicate) {
  * downstream consequence.
  */
 /**
- * An operation declaring `x-effects` must produce exactly the stated change.
+ * An operation declaring `x-effects` must produce the stated change.
+ *
+ * `count` is an exact cardinality delta (default 1). `min` is at-least. After a `create` on A,
+ * later items in the same array fill a child list under A with the new id — from the write
+ * response (`table_id` or the entity identity) or from A's list delta.
  *
  * `x-invalidate` says a read route changes; `x-effects` says *how*. That difference is what
  * separates "something differed" — which is satisfied by a stray timestamp and missed by a
- * cache-stale read — from an exact assertion on cardinality and membership.
+ * cache-stale read — from an assertion on cardinality and membership.
  */
 /**
  * A numeric field must compare numerically, not lexically.
@@ -3471,62 +3482,108 @@ const declaredEffectsOccur = {
     needs: "an operation declaring x-effects",
     async run(ctx) {
         for (const op of ctx.effectOps) {
-            for (const effect of op.effects) {
-                const target = ctx.model.entities.get(effect.entity);
-                const listId = target?.list;
-                if (listId === undefined) {
-                    ctx.findings.gap(this.id, ctx.entityName, `${op.operationId} declares an effect on "${effect.entity}", which has no list route`, "the effect cannot be observed, so it is not verified");
-                    continue;
+            await forEachInvocation(op.operationId, ctx.uploads, async (uploads, slot) => {
+                const fixture = slot?.filename;
+                const effects = op.effects;
+                if (effects.length === 0)
+                    return;
+                const scope = { ...ctx.scope };
+                const befores = new Map();
+                for (const effect of effects) {
+                    const listOp = listOpFor(ctx, effect.entity);
+                    if (listOp === undefined)
+                        continue;
+                    if (befores.has(effect.entity))
+                        continue;
+                    befores.set(effect.entity, await observe(ctx, listOp, scope));
                 }
-                const listOp = ctx.model.byOperationId.get(listId);
-                if (listOp === undefined)
-                    continue;
-                const before = await observe(ctx, listOp);
-                if (before === null)
-                    continue;
                 const body = op.hasRequestBody ? bodyForOp(ctx, op) : undefined;
                 const invoked = await ctx.client.request(op.method, fillPath(op.path, ctx.scope), {
                     headers: ctx.auth(),
-                    ...(body === undefined ? {} : await encodeOpBody(ctx, op, body)),
+                    operationId: op.operationId,
+                    ...(fixture === undefined ? {} : { fixture }),
+                    ...(body === undefined ? {} : await encodeOpBody(ctx, op, body, "baseline", 0, uploads)),
                 });
                 if (standDownForFeatureGate(ctx, op, invoked, this.id))
-                    continue;
+                    return;
                 if (standDownForRateLimit(ctx, invoked, this.id))
-                    continue;
+                    return;
                 if (invoked.status >= 400) {
-                    ctx.findings.gap(this.id, ctx.entityName, `${op.operationId} could not be invoked`, `returned ${invoked.status}; its declared effects are unverified`);
-                    continue;
+                    ctx.findings.gap(this.id, subject(ctx.entityName, op.operationId, fixture), `${op.operationId} could not be invoked`, `returned ${invoked.status}; its declared effects are unverified`, fixture);
+                    return;
                 }
-                const after = await observe(ctx, listOp);
-                if (after === null)
-                    continue;
-                const expected = effect.count ?? 1;
-                const delta = after.ids.length - before.ids.length;
-                const added = after.ids.filter((id) => !before.ids.includes(id));
-                const removed = before.ids.filter((id) => !after.ids.includes(id));
-                const wanted = effect.op === "create" || effect.op === "append" ? expected : effect.op === "delete" ? -expected : 0;
-                if (effect.op === "create" || effect.op === "append") {
-                    if (delta === wanted && added.length === expected)
+                const deltas = new Map();
+                Object.assign(scope, bindAfterCreateEffects(ctx.model, effects, invoked.responseBody, deltas));
+                for (const effect of effects) {
+                    if (effect.op !== "create")
                         continue;
-                    ctx.findings.backend(this.id, ctx.entityName, `${op.operationId} did not produce the "${effect.entity}" records it declares`, `x-effects declares ${effect.op} × ${expected} on "${effect.entity}", but the ` +
-                        `collection went from ${before.ids.length} to ${after.ids.length} ` +
-                        `(${added.length} added, ${removed.length} removed). A declared effect that does ` +
-                        "not occur means callers cannot rely on the operation having done anything.", [invoked, after.exchange]);
-                    continue;
-                }
-                if (effect.op === "delete") {
-                    if (delta === wanted && removed.length === expected)
+                    const param = identityPathParam(ctx.model, effect.entity);
+                    if (scope[param] !== undefined)
                         continue;
-                    ctx.findings.backend(this.id, ctx.entityName, `${op.operationId} did not remove the "${effect.entity}" records it declares`, `x-effects declares delete × ${expected} on "${effect.entity}", but the collection ` +
-                        `went from ${before.ids.length} to ${after.ids.length}`, [invoked, after.exchange]);
-                    continue;
+                    const listOp = listOpFor(ctx, effect.entity);
+                    if (listOp === undefined)
+                        continue;
+                    const afterParent = await observe(ctx, listOp, scope);
+                    if (afterParent.status !== "ok")
+                        continue;
+                    const before = befores.get(effect.entity);
+                    const prior = before?.status === "ok" ? before.ids : [];
+                    const added = afterParent.ids.filter((id) => !prior.includes(id));
+                    deltas.set(effect.entity, added);
+                    Object.assign(scope, bindCreatedScope(ctx.model, effect.entity, invoked.responseBody, added));
                 }
-                /* update and replace change content, not cardinality. */
-                if (delta !== 0) {
-                    ctx.findings.backend(this.id, ctx.entityName, `${op.operationId} changed the size of "${effect.entity}" while declaring ${effect.op}`, `x-effects declares ${effect.op}, which must not add or remove records, but the ` +
-                        `collection went from ${before.ids.length} to ${after.ids.length}`, [invoked, after.exchange]);
+                for (const effect of effects) {
+                    const listOp = listOpFor(ctx, effect.entity);
+                    if (listOp === undefined) {
+                        ctx.findings.gap(this.id, subject(ctx.entityName, op.operationId, fixture), `${op.operationId} declares an effect on "${effect.entity}", which has no list route`, "the effect cannot be observed, so it is not verified", fixture);
+                        continue;
+                    }
+                    if (!canFillPath(listOp.path, scope)) {
+                        const missing = listOp.pathParams.filter((name) => scope[name] === undefined);
+                        ctx.findings.gap(this.id, subject(ctx.entityName, op.operationId, fixture), `${op.operationId} declares an effect on "${effect.entity}", but the list path cannot be filled`, `missing ${missing.map((name) => `{${name}}`).join(", ")} after the write; the effect is unverified`, fixture);
+                        continue;
+                    }
+                    const after = await observe(ctx, listOp, scope);
+                    if (after.status === "error") {
+                        ctx.findings.gap(this.id, subject(ctx.entityName, op.operationId, fixture), `${op.operationId} could not observe "${effect.entity}" after the write`, `list returned ${after.exchange.status}; the declared effect is unverified`, fixture);
+                        continue;
+                    }
+                    if (after.status === "unfillable") {
+                        ctx.findings.gap(this.id, subject(ctx.entityName, op.operationId, fixture), `${op.operationId} declares an effect on "${effect.entity}", but the list path cannot be filled`, "the child list still lacks a parent id after the write; the effect is unverified", fixture);
+                        continue;
+                    }
+                    const before = befores.get(effect.entity);
+                    if (before?.status === "error") {
+                        ctx.findings.gap(this.id, subject(ctx.entityName, op.operationId, fixture), `${op.operationId} could not observe "${effect.entity}" before the write`, `list returned ${before.exchange.status}; no baseline, so the effect is unverified`, fixture);
+                        continue;
+                    }
+                    const prior = before?.status === "ok" ? before.ids : [];
+                    const delta = after.ids.length - prior.length;
+                    const added = after.ids.filter((id) => !prior.includes(id));
+                    const removed = prior.filter((id) => !after.ids.includes(id));
+                    if (effectHolds(effect, delta, added.length, removed.length)) {
+                        if (effect.op === "create") {
+                            Object.assign(scope, bindCreatedScope(ctx.model, effect.entity, invoked.responseBody, added));
+                        }
+                        continue;
+                    }
+                    const hold = describeEffectHold(effect);
+                    if (effect.op === "create" || effect.op === "append") {
+                        ctx.findings.backend(this.id, subject(ctx.entityName, op.operationId, fixture), `${op.operationId} did not produce the "${effect.entity}" records it declares`, `x-effects declares ${hold} on "${effect.entity}", but the ` +
+                            `collection went from ${prior.length} to ${after.ids.length} ` +
+                            `(${added.length} added, ${removed.length} removed). A declared effect that does ` +
+                            "not occur means callers cannot rely on the operation having done anything.", [invoked, after.exchange], fixture);
+                        continue;
+                    }
+                    if (effect.op === "delete") {
+                        ctx.findings.backend(this.id, subject(ctx.entityName, op.operationId, fixture), `${op.operationId} did not remove the "${effect.entity}" records it declares`, `x-effects declares ${hold} on "${effect.entity}", but the collection ` +
+                            `went from ${prior.length} to ${after.ids.length}`, [invoked, after.exchange], fixture);
+                        continue;
+                    }
+                    ctx.findings.backend(this.id, subject(ctx.entityName, op.operationId, fixture), `${op.operationId} changed the size of "${effect.entity}" while declaring ${effect.op}`, `x-effects declares ${effect.op}, which must not add or remove records, but the ` +
+                        `collection went from ${prior.length} to ${after.ids.length}`, [invoked, after.exchange], fixture);
                 }
-            }
+            });
         }
     },
 };
@@ -3550,58 +3607,74 @@ const sideEffectArrives = {
                 ctx.findings.gap(this.id, ctx.entityName, `${op.operationId} x-wait names "${spec.operationId}", which is not in the document`, "the side effect cannot be observed, so it is not verified");
                 continue;
             }
-            const body = op.hasRequestBody ? bodyForOp(ctx, op) : undefined;
-            const invoked = await ctx.client.request(op.method, fillPath(op.path, ctx.scope), {
-                headers: ctx.auth(),
-                operationId: op.operationId,
-                ...(body === undefined ? {} : await encodeOpBody(ctx, op, body)),
-            });
-            if (standDownForFeatureGate(ctx, op, invoked, this.id))
-                continue;
-            if (standDownForRateLimit(ctx, invoked, this.id))
-                continue;
-            if (invoked.status >= 400) {
-                ctx.findings.gap(this.id, ctx.entityName, `${op.operationId} could not be invoked`, `returned ${invoked.status}; its declared x-wait is unverified`);
-                continue;
-            }
-            const outcome = await driveWait({
-                awaitSideEffect: ctx.hooks.awaitSideEffect,
-                client: ctx.client,
-                headers: ctx.auth,
-                pollOp,
-                record: invoked.responseBody,
-                scope: ctx.scope,
-                spec,
-                writeOpId: op.operationId,
-                ...(ctx.refreshIfStale === undefined ? {} : { refreshIfStale: ctx.refreshIfStale }),
+            await forEachInvocation(op.operationId, ctx.uploads, async (uploads, slot) => {
+                const fixture = slot?.filename;
+                const body = op.hasRequestBody ? bodyForOp(ctx, op) : undefined;
+                const invoked = await ctx.client.request(op.method, fillPath(op.path, ctx.scope), {
+                    headers: ctx.auth(),
+                    operationId: op.operationId,
+                    ...(fixture === undefined ? {} : { fixture }),
+                    ...(body === undefined ? {} : await encodeOpBody(ctx, op, body, "baseline", 0, uploads)),
+                });
+                if (standDownForFeatureGate(ctx, op, invoked, this.id))
+                    return;
+                if (standDownForRateLimit(ctx, invoked, this.id))
+                    return;
+                if (invoked.status >= 400) {
+                    ctx.findings.gap(this.id, subject(ctx.entityName, op.operationId, fixture), `${op.operationId} could not be invoked`, `returned ${invoked.status}; its declared x-wait is unverified`, fixture);
+                    return;
+                }
+                const scope = bindWaitScope(ctx, op, pollOp, invoked.responseBody);
+                const outcome = await driveWait({
+                    awaitSideEffect: ctx.hooks.awaitSideEffect,
+                    client: ctx.client,
+                    headers: ctx.auth,
+                    pollOp,
+                    record: invoked.responseBody,
+                    scope,
+                    spec,
+                    writeOpId: op.operationId,
+                    ...(ctx.refreshIfStale === undefined ? {} : { refreshIfStale: ctx.refreshIfStale }),
+                });
+                if (!outcome.timedOut)
+                    return;
+                ctx.findings.backend(this.id, subject(ctx.entityName, op.operationId, fixture), `${op.operationId} side effect did not appear within ${spec.timeoutMs}ms`, `x-wait polls ${spec.operationId}` +
+                    (spec.until === undefined ? "" : ` until ${spec.until} is non-empty`) +
+                    ` and the path was still empty after ${outcome.polls} poll(s) / ${Math.round(outcome.elapsedMs)}ms. ` +
+                    "Queue consumers and webhook inboxes are not the same request; a timeout here is a " +
+                    "missed delivery, not a coverage gap.", [invoked, ...outcome.exchanges.slice(-2)], fixture);
             });
-            if (!outcome.timedOut)
-                continue;
-            ctx.findings.backend(this.id, ctx.entityName, `${op.operationId} side effect did not appear within ${spec.timeoutMs}ms`, `x-wait polls ${spec.operationId}` +
-                (spec.until === undefined ? "" : ` until ${spec.until} is non-empty`) +
-                ` and the path was still empty after ${outcome.polls} poll(s) / ${Math.round(outcome.elapsedMs)}ms. ` +
-                "Queue consumers and webhook inboxes are not the same request; a timeout here is a " +
-                "missed delivery, not a coverage gap.", [invoked, ...outcome.exchanges.slice(-2)]);
         }
     },
 };
-async function observe(ctx, listOp) {
+function listOpFor(ctx, entityName) {
+    const listId = ctx.model.entities.get(entityName)?.list;
+    return listId === undefined ? undefined : ctx.model.byOperationId.get(listId);
+}
+function bindWaitScope(ctx, writeOp, pollOp, writeBody) {
+    const scope = { ...ctx.scope };
+    Object.assign(scope, bindAfterCreateEffects(ctx.model, writeOp.effects, writeBody));
+    Object.assign(scope, bindMissingPathParams(pollOp.pathParams, scope, writeBody));
+    return scope;
+}
+async function observe(ctx, listOp, scope = ctx.scope) {
     let path;
     try {
-        path = fillPath(listOp.path, ctx.scope);
+        path = fillPath(listOp.path, scope);
     }
     catch {
-        return null;
+        return { status: "unfillable" };
     }
     const exchange = await ctx.client.get(path, {
         headers: ctx.auth(),
+        operationId: listOp.operationId,
         query: { limit: listOp.query?.maxLimit ?? 100 },
     });
     if (exchange.status >= 400)
-        return null;
+        return { exchange, status: "error" };
     const identity = ctx.model.entities.get(listOp.entity ?? "")?.identity ?? "id";
     const items = extractItems(exchange.responseBody, listOp.collection?.key ?? null);
-    return { exchange, ids: items.map((item) => String(item[identity])) };
+    return { exchange, ids: items.map((item) => String(item[identity])), status: "ok" };
 }
 const asyncReachesTerminalState = {
     applicable: (ctx) => ctx.asyncOps.length > 0,
@@ -3613,47 +3686,50 @@ const asyncReachesTerminalState = {
             const spec = op.async;
             if (spec === null)
                 continue;
-            const body = op.hasRequestBody ? bodyForOp(ctx, op) : undefined;
-            const start = await ctx.client.request(op.method, fillPath(op.path, ctx.scope), {
-                headers: ctx.auth(),
-                ...(body === undefined ? {} : await encodeOpBody(ctx, op, body)),
-            });
-            if (standDownForFeatureGate(ctx, op, start, this.id))
-                continue;
-            if (start.status >= 400) {
-                ctx.findings.gap(this.id, ctx.entityName, `${op.operationId} could not be started`, `returned ${start.status}; the async lifecycle after it is untested`);
-                continue;
-            }
-            const streamed = isEventStream(start, op);
-            const fromStream = streamed ? inspectStreamAsync(start.responseBody, spec) : null;
-            if (fromStream?.terminal !== null && fromStream?.terminal !== undefined) {
-                if (spec.successWhen !== undefined && !matchesPredicate(fromStream.terminal, spec.successWhen)) {
-                    ctx.findings.gap(this.id, ctx.entityName, `${op.operationId} reached a non-success terminal state`, `terminal state did not satisfy "${spec.successWhen}"; downstream effects of ` +
-                        "this operation are untested");
+            await forEachInvocation(op.operationId, ctx.uploads, async (uploads, slot) => {
+                const fixture = slot?.filename;
+                const body = op.hasRequestBody ? bodyForOp(ctx, op) : undefined;
+                const start = await ctx.client.request(op.method, fillPath(op.path, ctx.scope), {
+                    headers: ctx.auth(),
+                    ...(body === undefined ? {} : await encodeOpBody(ctx, op, body, "baseline", 0, uploads)),
+                });
+                if (standDownForFeatureGate(ctx, op, start, this.id))
+                    return;
+                if (start.status >= 400) {
+                    ctx.findings.gap(this.id, subject(ctx.entityName, op.operationId, fixture), `${op.operationId} could not be started`, `returned ${start.status}; the async lifecycle after it is untested`, fixture);
+                    return;
                 }
-                continue;
-            }
-            const receipt = fromStream?.idRecord !== null && fromStream?.idRecord !== undefined ? fromStream.idRecord : start.responseBody;
-            if (streamed && fromStream !== null && (fromStream.id === undefined || fromStream.id === null)) {
-                ctx.findings.backend(this.id, ctx.entityName, `${op.operationId} job disappeared before completing`, "the stream ended without a terminal frame and without a job id, so the poll route cannot be named.", [start]);
-                continue;
-            }
-            const outcome = await driveAsync(ctx.client, spec, receipt, ctx.scope, ctx.auth, ctx.refreshIfStale);
-            if (outcome.timedOut) {
-                ctx.findings.backend(this.id, ctx.entityName, `${op.operationId} never reached a terminal state`, `polled ${spec.poll} ${outcome.polls} time(s) over ${Math.round(outcome.elapsedMs)}ms ` +
-                    `without satisfying "${spec.until ?? "any terminal state"}". A job that neither ` +
-                    "completes nor fails leaves callers polling forever.", [start, ...outcome.exchanges.slice(-2)]);
-                continue;
-            }
-            if (outcome.terminal === null) {
-                ctx.findings.backend(this.id, ctx.entityName, `${op.operationId} job disappeared before completing`, `the poll route stopped serving the job after ${outcome.polls} poll(s). A job that ` +
-                    "vanishes is indistinguishable from one that never existed.", [start, ...outcome.exchanges.slice(-2)]);
-                continue;
-            }
-            if (!outcome.succeeded) {
-                ctx.findings.gap(this.id, ctx.entityName, `${op.operationId} reached a non-success terminal state`, `terminal state did not satisfy "${spec.successWhen ?? ""}"; downstream effects of ` +
-                    "this operation are untested");
-            }
+                const streamed = isEventStream(start, op);
+                const fromStream = streamed ? inspectStreamAsync(start.responseBody, spec) : null;
+                if (fromStream?.terminal !== null && fromStream?.terminal !== undefined) {
+                    if (spec.successWhen !== undefined && !matchesPredicate(fromStream.terminal, spec.successWhen)) {
+                        ctx.findings.gap(this.id, subject(ctx.entityName, op.operationId, fixture), `${op.operationId} reached a non-success terminal state`, `terminal state did not satisfy "${spec.successWhen}"; downstream effects of ` +
+                            "this operation are untested", fixture);
+                    }
+                    return;
+                }
+                const receipt = fromStream?.idRecord !== null && fromStream?.idRecord !== undefined ? fromStream.idRecord : start.responseBody;
+                if (streamed && fromStream !== null && (fromStream.id === undefined || fromStream.id === null)) {
+                    ctx.findings.backend(this.id, subject(ctx.entityName, op.operationId, fixture), `${op.operationId} job disappeared before completing`, "the stream ended without a terminal frame and without a job id, so the poll route cannot be named.", [start], fixture);
+                    return;
+                }
+                const outcome = await driveAsync(ctx.client, spec, receipt, ctx.scope, ctx.auth, ctx.refreshIfStale);
+                if (outcome.timedOut) {
+                    ctx.findings.backend(this.id, subject(ctx.entityName, op.operationId, fixture), `${op.operationId} never reached a terminal state`, `polled ${spec.poll} ${outcome.polls} time(s) over ${Math.round(outcome.elapsedMs)}ms ` +
+                        `without satisfying "${spec.until ?? "any terminal state"}". A job that neither ` +
+                        "completes nor fails leaves callers polling forever.", [start, ...outcome.exchanges.slice(-2)], fixture);
+                    return;
+                }
+                if (outcome.terminal === null) {
+                    ctx.findings.backend(this.id, subject(ctx.entityName, op.operationId, fixture), `${op.operationId} job disappeared before completing`, `the poll route stopped serving the job after ${outcome.polls} poll(s). A job that ` +
+                        "vanishes is indistinguishable from one that never existed.", [start, ...outcome.exchanges.slice(-2)], fixture);
+                    return;
+                }
+                if (!outcome.succeeded) {
+                    ctx.findings.gap(this.id, subject(ctx.entityName, op.operationId, fixture), `${op.operationId} reached a non-success terminal state`, `terminal state did not satisfy "${spec.successWhen ?? ""}"; downstream effects of ` +
+                        "this operation are untested", fixture);
+                }
+            });
         }
     },
 };