@adcp/sdk 8.1.0-beta.13 → 8.1.0-beta.14

package/dist/lib/testing/storyboard/validations.js

@@ -16,12 +16,16 @@ const response_schemas_1 = require("../../utils/response-schemas");
 const envelope_status_compat_1 = require("../../utils/envelope-status-compat");
 const a2a_discovery_1 = require("../../utils/a2a-discovery");
 const schema_validator_1 = require("../../validation/schema-validator");
+const schema_loader_1 = require("../../validation/schema-loader");
 const version_1 = require("../../version");
+const adcp_version_config_1 = require("../../utils/adcp-version-config");
 const test_controller_1 = require("../test-controller");
 const glob_1 = require("../../utils/glob");
 const path_1 = require("./path");
 const shape_drift_hints_1 = require("./shape-drift-hints");
 const test_kit_1 = require("./test-kit");
+const canonical_format_satisfaction_1 = require("./canonical-format-satisfaction");
+const rate_limit_trip_1 = require("./rate-limit-trip");
 /**
  * Run all validations for a storyboard step.
  */
@@ -108,10 +112,25 @@ function runValidation(validation, ctx) {
             return validateFieldEqualsContext(validation, ctx);
         case 'upstream_traffic':
             return validateUpstreamTraffic(validation, ctx);
+        case 'replay_not_cached_rate_limit':
+            return validateReplayNotCachedRateLimit(validation, ctx);
         case 'cross_response_field_equal':
             return validateCrossResponseFieldEqual(validation, ctx);
         case 'cross_response_count_distinct':
             return validateCrossResponseCountDistinct(validation, ctx);
+        case 'canonical_format_satisfaction':
+            if (ctx.taskName !== 'create_media_buy') {
+                return {
+                    check: validation.check,
+                    passed: false,
+                    description: validation.description,
+                    error: 'canonical_format_satisfaction applies only to create_media_buy storyboard steps',
+                    json_pointer: null,
+                    expected: 'create_media_buy',
+                    actual: ctx.taskName,
+                };
+            }
+            return requireTaskResult(ctx, validation, tr => (0, canonical_format_satisfaction_1.validateCanonicalFormatSatisfaction)(validation, ctx.request, ctx.storyboardContext, tr));
         case 'array_length':
             return validateArrayLength(validation, resolveTarget(ctx));
         default:
@@ -291,13 +310,14 @@ function validateResponseSchema(validation, ctx, taskResult) {
     const dataForValidation = Array.isArray(dataWithoutMessage)
         ? dataWithoutMessage
         : (0, envelope_status_compat_1.injectLegacyEnvelopeStatus)(dataWithoutMessage, { toolName: taskName });
-    const parseResult = schema.safeParse(dataForValidation);
+    const responseAdcpVersion = ctx.responseAdcpVersion ?? ctx.adcpVersion;
+    const parseResult = schema.safeParse((0, response_schemas_1.prepareResponseForSchemaValidation)(taskName, dataForValidation, responseAdcpVersion));
     // Strict (AJV) verdict runs alongside the lenient Zod check so the run
     // report surfaces strictness deltas (issue #820 follow-up). The AJV path
     // enforces `format` keywords and `additionalProperties: false` that Zod's
     // `passthrough()` omits — a response can pass Zod and fail AJV. The step's
     // overall pass/fail stays Zod-driven to preserve backwards compatibility.
-    const strict = computeStrictVerdict(taskName, dataWithoutMessage, ctx.adcpVersion);
+    const strict = computeStrictVerdict(taskName, dataWithoutMessage, ctx.adcpVersion, ctx.responseAdcpVersion);
     // Shape-drift no longer rides on `ValidationResult.warning` — issue #935
     // moved that diagnostic to `StoryboardStepResult.hints[]` as a structured
     // `ShapeDriftHint`. The runner emits the structured hint via
@@ -348,8 +368,13 @@ function validateResponseSchema(validation, ctx, taskResult) {
  * the SDK — notably the brand-rights and governance schemas that live
  * outside the `bundled/` tree the loader walks today).
  */
-function computeStrictVerdict(taskName, payload, adcpVersion) {
-    const outcome = (0, schema_validator_1.validateResponse)(taskName, payload, adcpVersion);
+function computeStrictVerdict(taskName, payload, adcpVersion, responseAdcpVersion) {
+    const validationVersion = responseAdcpVersion && (0, schema_loader_1.hasSchemaBundle)(responseAdcpVersion) ? responseAdcpVersion : adcpVersion;
+    if (responseAdcpVersion && (0, adcp_version_config_1.isPre31AdcpVersion)(responseAdcpVersion) && !(0, schema_loader_1.hasSchemaBundle)(responseAdcpVersion)) {
+        return undefined;
+    }
+    const payloadForValidation = (0, response_schemas_1.prepareResponseForSchemaValidation)(taskName, payload, responseAdcpVersion);
+    const outcome = (0, schema_validator_1.validateResponse)(taskName, payloadForValidation, validationVersion);
     // `variant: 'skipped'` means no AJV validator compiled for this task (no
     // strictness signal to emit); treat the same as "no AJV schema available".
     if (outcome.variant === 'skipped')
@@ -2242,6 +2267,27 @@ function validateFieldEqualsContext(validation, ctx) {
  */
 function validateUpstreamTraffic(validation, ctx) {
     const expected = buildUpstreamTrafficExpected(validation);
+    const invalidIdentifierPaths = collectInvalidIdentifierPaths(validation.identifier_paths);
+    if (invalidIdentifierPaths.length > 0) {
+        return {
+            check: 'upstream_traffic',
+            passed: false,
+            description: validation.description,
+            error: 'storyboard authoring error: invalid upstream_traffic.identifier_paths: ' +
+                invalidIdentifierPaths.map(issue => `${issue.path} (${issue.reason})`).join('; '),
+            json_pointer: null,
+            expected,
+            actual: {
+                matched_count: 0,
+                total_calls: 0,
+                missing_payload_paths: [],
+                missing_identifier_values: [],
+                invalid_identifier_paths: invalidIdentifierPaths,
+            },
+            schema_id: null,
+            schema_url: null,
+        };
+    }
     const upstream = ctx.upstreamTraffic;
     // Adopter opted out (or controller wasn't detected): grade not_applicable.
     // missing_test_controller controller-side, not failed — opt-in by adopter
@@ -2298,6 +2344,22 @@ function validateUpstreamTraffic(validation, ctx) {
     // `MAX_ERROR_LENGTH` posture on every other validation_result.error.
     if (!('success' in query.payload) || query.payload.success !== true) {
         const errMsg = 'error' in query.payload ? query.payload.error : 'controller returned a non-success response';
+        if ('error_kind' in query.payload && query.payload.error_kind === 'jcs_non_finite') {
+            return {
+                check: 'upstream_traffic',
+                passed: true,
+                not_applicable: true,
+                description: validation.description,
+                note: 'digest attestation could not canonicalize a non-finite JSON number - graded not_applicable',
+                json_pointer: null,
+                expected,
+                actual: { matched_count: 0, total_calls: 0, missing_payload_paths: [], missing_identifier_values: [] },
+                schema_id: null,
+                schema_url: null,
+                request: query.request,
+                response: query.response,
+            };
+        }
         return {
             check: 'upstream_traffic',
             passed: false,
@@ -2318,11 +2380,10 @@ function validateUpstreamTraffic(validation, ctx) {
     const matchedCount = matched.length;
     const minCount = validation.min_count ?? 1;
     // payload_must_contain results bucket two ways: paths that no matched
-    // call satisfied (failure), and paths whose only matched calls were
-    // non-JSON for an `equals` / `contains_any` assertion (`not_applicable`).
-    // Per spec, the assertion grades `not_applicable` only when *every*
-    // path-based check downgraded that way; mixed payload+content_type
-    // results still fail the validation if any required path is missing.
+    // call satisfied despite inspectable raw JSON evidence (failure), and
+    // paths with no portable payload evidence to inspect (`not_applicable`).
+    // Any actionable raw JSON miss keeps the validation failed; otherwise any
+    // not_applicable path downgrades the validation from pass to not_applicable.
     const missingPayloadPaths = [];
     const notApplicablePaths = [];
     if (validation.payload_must_contain && validation.payload_must_contain.length > 0) {
@@ -2345,46 +2406,77 @@ function validateUpstreamTraffic(validation, ctx) {
     // fabrication is the threat. Replaces the earlier `buyer_identifier_echo`
     // boolean shorthand per spec PR adcp#3816.
     const missingIdentifierValues = [];
+    const notApplicableIdentifierValues = [];
     if (validation.identifier_paths && validation.identifier_paths.length > 0) {
         const requestPayload = ctx.request?.payload;
         const sample = requestPayload && typeof requestPayload === 'object' && !Array.isArray(requestPayload)
             ? requestPayload
             : ctx.storyboardStep?.sample_request;
         for (const path of validation.identifier_paths) {
-            const vectors = sample !== undefined ? resolveJsonPathLite(sample, path) : [];
+            const vectors = sample !== undefined ? (0, path_1.resolvePortableIdentifierPathAll)(sample, path) : [];
             for (const vector of vectors) {
                 if (vector === undefined || vector === null)
                     continue;
-                if (!anyMatchedCallEchoesValue(matched, vector)) {
+                const digest = typeof vector === 'string' ? upstream.identifierDigestByValue?.get(vector) : undefined;
+                const result = anyMatchedCallEchoesValue(matched, vector, digest);
+                if (result.satisfied)
+                    continue;
+                if (result.not_applicable) {
+                    notApplicableIdentifierValues.push(vector);
+                }
+                else {
                     missingIdentifierValues.push(vector);
                 }
             }
         }
     }
-    const countOk = matchedCount >= minCount;
+    const hasRawIntrospectionAssertions = (validation.payload_must_contain?.length ?? 0) > 0 || (validation.identifier_paths?.length ?? 0) > 0;
+    const rawRequiredDigestDowngrade = validation.attestation_mode_required === 'raw' &&
+        hasRawIntrospectionAssertions &&
+        matched.length > 0 &&
+        matched.every(call => call.attestation_mode === 'digest');
+    if (rawRequiredDigestDowngrade) {
+        missingPayloadPaths.length = 0;
+        missingIdentifierValues.length = 0;
+    }
+    const countOk = minCount === 0 ? matchedCount === 0 : matchedCount >= minCount;
     const payloadOk = missingPayloadPaths.length === 0;
     const echoOk = missingIdentifierValues.length === 0;
-    const passed = countOk && payloadOk && echoOk;
-    // Per spec: a payload_must_contain assertion whose ONLY checks were
-    // path-based against non-JSON content_types grades not_applicable. When
-    // EVERY declared path landed in that bucket (and count + echo also
-    // passed), the whole validation grades not_applicable rather than passed.
-    const allPathsNotApplicable = (validation.payload_must_contain?.length ?? 0) > 0 &&
-        notApplicablePaths.length === (validation.payload_must_contain?.length ?? 0) &&
+    const passed = countOk && (rawRequiredDigestDowngrade || (payloadOk && echoOk));
+    // Per spec: a payload_must_contain assertion whose only available evidence
+    // is not portable to inspect grades not_applicable. When any required path
+    // lands in that bucket (and count + echo passed with no actionable payload
+    // misses), the whole validation grades not_applicable rather than passed.
+    const anyPayloadNotApplicable = (validation.payload_must_contain?.length ?? 0) > 0 &&
+        notApplicablePaths.length > 0 &&
         missingPayloadPaths.length === 0;
-    const not_applicable = passed && allPathsNotApplicable && countOk && echoOk;
+    const hasMeaningfulPayloadPass = (validation.payload_must_contain?.length ?? 0) > 0 && payloadOk && !anyPayloadNotApplicable;
+    const allIdentifiersNotApplicable = (validation.identifier_paths?.length ?? 0) > 0 &&
+        missingIdentifierValues.length === 0 &&
+        notApplicableIdentifierValues.length > 0;
+    const not_applicable = passed &&
+        countOk &&
+        (rawRequiredDigestDowngrade ||
+            anyPayloadNotApplicable ||
+            (allIdentifiersNotApplicable && !hasMeaningfulPayloadPass));
     const actual = {
         matched_count: matchedCount,
         total_calls: totalCalls,
         missing_payload_paths: missingPayloadPaths,
         missing_identifier_values: missingIdentifierValues,
+        not_applicable_payload_paths: notApplicablePaths,
+        not_applicable_identifier_values: notApplicableIdentifierValues,
+        ...(upstream.identifierDigestLimitExceeded && {
+            identifier_digest_limit_exceeded: upstream.identifierDigestLimitExceeded,
+        }),
     };
     // RFC 6901 pointer: when one specific call's payload failed
     // payload_must_contain, point at that call's payload; null when the
     // failure is a count mismatch or no specific call is implicated.
     let jsonPointer = null;
     if (!payloadOk && matched.length > 0) {
-        const idx = all.indexOf(matched[0]);
+        const actionableMiss = matched.find(call => call.attestation_mode === 'raw' && (0, test_controller_1.isJsonContentType)(call.content_type));
+        const idx = all.indexOf(actionableMiss ?? matched[0]);
         if (idx >= 0)
             jsonPointer = `/recorded_calls/${idx}/payload`;
     }
@@ -2394,7 +2486,13 @@ function validateUpstreamTraffic(validation, ctx) {
             passed: true,
             ...(not_applicable && { not_applicable: true }),
             ...(not_applicable && {
-                note: `payload_must_contain paths only matched non-JSON content_types — graded not_applicable`,
+                note: rawRequiredDigestDowngrade
+                    ? `attestation_mode_required: raw but controller returned digest attestations — graded not_applicable`
+                    : allIdentifiersNotApplicable
+                        ? upstream.identifierDigestLimitExceeded
+                            ? `identifier_paths exceeded the runner digest buffer; recorder buffer capped at ${upstream.identifierDigestLimitExceeded.limit} unique digests with ${upstream.identifierDigestLimitExceeded.clipped} overflow value(s) clipped — graded not_applicable`
+                            : `identifier_paths only matched digest attestations without portable proofs — graded not_applicable`
+                        : `payload_must_contain paths could not be fully inspected in raw JSON attestations — graded not_applicable`,
             }),
             description: validation.description,
             json_pointer: null,
@@ -2405,8 +2503,11 @@ function validateUpstreamTraffic(validation, ctx) {
         };
     }
     const errParts = [];
-    if (!countOk)
-        errParts.push(`expected at least ${minCount} matching call(s); observed ${matchedCount}`);
+    if (!countOk) {
+        errParts.push(minCount === 0
+            ? `expected zero matching call(s); observed ${matchedCount}`
+            : `expected at least ${minCount} matching call(s); observed ${matchedCount}`);
+    }
     if (!payloadOk)
         errParts.push(`missing payload paths: ${missingPayloadPaths.join(', ')}`);
     if (!echoOk)
@@ -2425,6 +2526,15 @@ function validateUpstreamTraffic(validation, ctx) {
         response: query.response,
     };
 }
+function collectInvalidIdentifierPaths(paths) {
+    const invalid = [];
+    for (const path of paths ?? []) {
+        const reason = (0, path_1.validatePortableIdentifierPath)(path);
+        if (reason)
+            invalid.push({ path, reason });
+    }
+    return invalid;
+}
 /**
  * Cap on agent / controller-controlled error strings inlined into a
  * `validation_result.error` field. Mirrors the runner's `MAX_ERROR_LENGTH`
@@ -2445,6 +2555,9 @@ function buildUpstreamTrafficExpected(validation) {
         expected.endpoint_pattern = validation.endpoint_pattern;
     if (validation.payload_must_contain !== undefined)
         expected.payload_must_contain = validation.payload_must_contain;
+    if (validation.attestation_mode_required !== undefined) {
+        expected.attestation_mode_required = validation.attestation_mode_required;
+    }
     if (validation.identifier_paths !== undefined)
         expected.identifier_paths = validation.identifier_paths;
     return expected;
@@ -2464,8 +2577,7 @@ function filterByEndpointPattern(calls, pattern) {
 /**
  * Returns whether at least one matched call's payload satisfies the
  * `payload_must_contain` predicate, plus a flag indicating the assertion
- * graded `not_applicable` (every matched call was non-JSON; path-based
- * matching has no portable semantics on non-JSON wire formats).
+ * graded `not_applicable` (no matched call had a JSON payload to inspect).
  *
  * Per spec PRs adcp#3816 (initial JSONPath restriction) and adcp#3987
  * (closes the substring-fallback ambiguity #3845):
@@ -2491,11 +2603,15 @@ function filterByEndpointPattern(calls, pattern) {
 function anyMatchedCallSatisfies(calls, spec) {
     let sawApplicableCall = false;
     for (const call of calls) {
+        if (call.attestation_mode !== 'raw') {
+            continue;
+        }
         const isJson = (0, test_controller_1.isJsonContentType)(call.content_type);
         // All match modes require a structured-JSON payload — non-JSON calls
         // don't contribute regardless of mode (adcp#3987).
-        if (!isJson)
+        if (!isJson) {
             continue;
+        }
         sawApplicableCall = true;
         const candidates = resolveJsonPathLite(call.payload, spec.path);
         if (candidates.length === 0)
@@ -2525,7 +2641,7 @@ function anyMatchedCallSatisfies(calls, spec) {
 function resolveJsonPathLite(root, path) {
     if (!path)
         return [];
-    let p = path;
+    let p = path.trim();
     if (p.startsWith('$.'))
         p = p.slice(2);
     else if (p.startsWith('$'))
@@ -2589,20 +2705,34 @@ function walkLitePath(root, path) {
  * nested object that would blow the recursion stack.
  */
 const CONTAINS_VALUE_MAX_DEPTH = 256;
-function anyMatchedCallEchoesValue(calls, value) {
+function anyMatchedCallEchoesValue(calls, value, valueDigest) {
+    let sawApplicableCall = false;
     for (const call of calls) {
+        if (call.attestation_mode === 'digest') {
+            if (!(0, test_controller_1.isJsonContentType)(call.content_type))
+                continue;
+            if (!valueDigest)
+                continue;
+            sawApplicableCall = true;
+            if (call.identifier_match_proofs?.some(proof => proof.identifier_value_sha256 === valueDigest && proof.found)) {
+                return { satisfied: true, not_applicable: false };
+            }
+            continue;
+        }
+        sawApplicableCall = true;
         // Non-JSON payloads land as raw strings — substring-match the
         // stringified vector. Defensible best-effort downgrade per the spec's
         // non-JSON fallback note.
         if (typeof call.payload === 'string') {
-            if (typeof value === 'string' && call.payload.includes(value))
-                return true;
+            if (typeof value === 'string' && call.payload.includes(value)) {
+                return { satisfied: true, not_applicable: false };
+            }
             continue;
         }
         if (containsValueAnyDepth(call.payload, value, 0))
-            return true;
+            return { satisfied: true, not_applicable: false };
     }
-    return false;
+    return { satisfied: false, not_applicable: !sawApplicableCall };
 }
 function containsValueAnyDepth(root, target, depth) {
     if (depth > CONTAINS_VALUE_MAX_DEPTH)
@@ -2716,6 +2846,81 @@ function validateCrossResponseFieldEqual(validation, ctx) {
         schema_url: null,
     };
 }
+function validateReplayNotCachedRateLimit(validation, ctx) {
+    const payload = resolveTarget(ctx).data;
+    const tripResponse = payload?.trip_response;
+    const replayResponse = payload?.replay_response;
+    const targetTask = typeof payload?.target_task === 'string' ? payload.target_task : undefined;
+    if (!tripResponse || typeof tripResponse !== 'object' || !replayResponse || typeof replayResponse !== 'object') {
+        const missing = [
+            !tripResponse || typeof tripResponse !== 'object' ? 'trip_response' : undefined,
+            !replayResponse || typeof replayResponse !== 'object' ? 'replay_response' : undefined,
+        ].filter((field) => typeof field === 'string');
+        return {
+            check: validation.check,
+            passed: true,
+            not_applicable: true,
+            description: validation.description,
+            note: `step did not produce rate_limit_trip_runner ${missing.join(' and ')}; replay_not_cached_rate_limit grades not_applicable`,
+            json_pointer: null,
+        };
+    }
+    const tripCode = extractSnapshotErrorCode(tripResponse, targetTask);
+    const replayCode = extractSnapshotErrorCode(replayResponse, targetTask);
+    if (tripCode !== 'RATE_LIMITED') {
+        return {
+            check: validation.check,
+            passed: false,
+            description: validation.description,
+            json_pointer: '/trip_response/error/code',
+            expected: 'RATE_LIMITED trip_response error code',
+            actual: tripCode ?? null,
+            schema_id: null,
+            schema_url: null,
+        };
+    }
+    if (replayCode === 'RATE_LIMITED') {
+        return {
+            check: validation.check,
+            passed: false,
+            description: validation.description,
+            error: 'rate_limit_response_cached_as_replay',
+            json_pointer: '/replay_response/error/code',
+            expected: 'replay_response must not return RATE_LIMITED from the idempotency cache',
+            actual: replayCode,
+            schema_id: null,
+            schema_url: null,
+        };
+    }
+    return {
+        check: validation.check,
+        passed: true,
+        description: validation.description,
+        json_pointer: '/replay_response/error/code',
+        actual: replayCode ?? null,
+    };
+}
+function extractSnapshotErrorCode(snapshot, taskName) {
+    const structuredError = snapshot.error;
+    if (structuredError && typeof structuredError === 'object') {
+        const code = structuredError.code;
+        if (typeof code === 'string')
+            return code;
+    }
+    const adcpError = snapshot.adcp_error;
+    if (adcpError && typeof adcpError === 'object') {
+        const code = adcpError.code;
+        if (typeof code === 'string')
+            return code;
+    }
+    const data = snapshot.data;
+    if (data && typeof data === 'object') {
+        const extracted = (0, rate_limit_trip_1.extractTaskAdcpError)({ success: snapshot.success === true, data }, taskName);
+        if (extracted)
+            return extracted.code;
+    }
+    return undefined;
+}
 /**
  * Cross-response: the cardinality of distinct values at `path` across all
  * resolved dispatches is in `allowed_values`. Spec: