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

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

@@ -23,6 +23,7 @@ exports.applyBrandInvariant = applyBrandInvariant;
 exports.applyDisableSandboxHint = applyDisableSandboxHint;
 exports.applyIdempotencyInvariant = applyIdempotencyInvariant;
 exports.getFirstStepPreview = getFirstStepPreview;
+const node_crypto_1 = require("node:crypto");
 const client_1 = require("../client");
 const protocols_1 = require("../../protocols");
 const rawResponseCapture_1 = require("../../protocols/rawResponseCapture");
@@ -34,10 +35,12 @@ const strict_validation_hints_1 = require("./strict-validation-hints");
 const validations_1 = require("./validations");
 const parallel_dispatch_1 = require("./parallel-dispatch");
 const path_1 = require("./path");
+const rate_limit_trip_1 = require("./rate-limit-trip");
 const redact_secrets_1 = require("../../utils/redact-secrets");
 const response_unwrapper_1 = require("../../utils/response-unwrapper");
 const envelope_status_compat_1 = require("../../utils/envelope-status-compat");
 const test_controller_1 = require("../test-controller");
+const constants_1 = require("../../upstream-recorder/constants");
 const request_builder_1 = require("./request-builder");
 const client_2 = require("../client");
 const idempotency_1 = require("../../utils/idempotency");
@@ -83,6 +86,15 @@ function applyAdcpVersionRunOptions(defaultAdcpVersion, options) {
     }
     return { ...options, adcpVersion, versionEnvelope };
 }
+function registerRunSchemaRoot(options) {
+    if (!options.schemaRoot)
+        return;
+    const adcpVersion = options.adcpVersion ?? options._serverAdcpVersion;
+    if (!adcpVersion) {
+        throw new Error('schemaRoot requires an AdCP version. Pass adcpVersion, or run a storyboard/compliance bundle with adcp_version set.');
+    }
+    (0, schema_loader_1.registerExternalSchemaRoot)(adcpVersion, options.schemaRoot);
+}
 function storyboardVersionEnvelopeMode(adcpVersion) {
     const bundleKey = (0, schema_loader_1.resolveBundleKey)(adcpVersion);
     const major = (0, version_1.parseAdcpMajorVersion)(bundleKey);
@@ -116,6 +128,7 @@ const DETAILED_SKIP_DETAILS = {
     rate_abuse_opt_out: 'Rate-abuse vector was excluded by request_signing.skipRateAbuse.',
     capability_profile_mismatch: 'Vector is outside the agent capability profile selected for this run.',
     transport_ungradable: 'Vector cannot be graded faithfully by the selected transport.',
+    rate_limit_not_triggered: 'No RATE_LIMITED response was observed within the configured max_attempts.',
 };
 function selectionForProbeSkip(reason, detail) {
     switch (reason) {
@@ -735,6 +748,7 @@ function filterResponseHeaders(headers) {
  */
 async function runStoryboard(agentUrlOrUrls, storyboard, options = {}) {
     options = applyStoryboardVersionOptions(storyboard, options);
+    registerRunSchemaRoot(options);
     (0, test_kit_1.validateTestKit)(options.test_kit);
     // Enforce authoring-time branch_set invariants regardless of how the
     // storyboard reached us. YAML callers already ran these rules in
@@ -901,6 +915,10 @@ function buildCapabilityUnsupportedResult(agentUrls, storyboard, detail) {
         ],
         context: {},
         total_duration_ms: 0,
+        // This synthetic phase is an applicability gate, not a real passed
+        // scenario. `overall_passed: true` preserves non-failing CI semantics,
+        // while passed_count stays 0 so rollups do not report unexecuted
+        // storyboards as successful coverage.
         passed_count: 0,
         failed_count: 0,
         skipped_count: 1,
@@ -978,6 +996,56 @@ function buildRequirementUnmetResult(agentUrls, storyboard, requirement, detail)
         ],
         context: {},
         total_duration_ms: 0,
+        // `required_any_of_tools` unmet is an applicability skip. Keep
+        // `overall_passed: true` for CI/non-failing semantics, but do not
+        // increment passed_count because no scenario behavior was exercised.
+        passed_count: 0,
+        failed_count: 0,
+        skipped_count: 1,
+        tested_at: new Date().toISOString(),
+        strict_validation_summary: {
+            observable: false,
+            checked: 0,
+            passed: 0,
+            failed: 0,
+            strict_only_failures: 0,
+            lenient_also_failed: 0,
+        },
+        notices: [],
+    };
+}
+function buildRequiredAnyOfToolsMissingResult(agentUrls, storyboard, detail) {
+    const syntheticStep = {
+        storyboard_id: storyboard.id,
+        step_id: 'missing_required_tool_family',
+        phase_id: 'requirement_unmet',
+        title: 'Storyboard skipped: required tool family missing',
+        task: '',
+        passed: true,
+        skipped: true,
+        skip_reason: 'requirement_unmet',
+        skip: { reason: 'requirement_unmet', detail },
+        duration_ms: 0,
+        validations: [],
+        context: {},
+        extraction: { path: 'none' },
+    };
+    return {
+        storyboard_id: storyboard.id,
+        storyboard_title: storyboard.title,
+        agent_url: agentUrls[0],
+        overall_passed: true,
+        phases: [
+            {
+                phase_id: 'requirement_unmet',
+                phase_title: 'Requirement unmet: required_any_of_tools',
+                passed: true,
+                steps: [syntheticStep],
+                duration_ms: 0,
+            },
+        ],
+        context: {},
+        total_duration_ms: 0,
         passed_count: 0,
         failed_count: 0,
         skipped_count: 1,
@@ -993,6 +1061,22 @@ function buildRequirementUnmetResult(agentUrls, storyboard, requirement, detail)
         notices: [],
     };
 }
+function normalizeAgentToolNames(tools) {
+    if (!Array.isArray(tools))
+        return undefined;
+    const names = [];
+    for (const tool of tools) {
+        if (typeof tool === 'string') {
+            names.push(tool);
+        }
+        else if (tool && typeof tool === 'object') {
+            const name = tool.name;
+            if (typeof name === 'string')
+                names.push(name);
+        }
+    }
+    return names.length > 0 ? names : undefined;
+}
 /**
  * Resolve a storyboard's `requires:` tags against the runtime environment.
  * Returns the first unmet requirement (with a human-readable detail) or
@@ -1409,7 +1493,7 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
         // passes the gate when any tenant in the map serves either one.
         const unionedTools = new Set();
         for (const p of routingContext.profiles.values()) {
-            for (const t of p.tools ?? [])
+            for (const t of normalizeAgentToolNames(p.tools) ?? [])
                 unionedTools.add(t);
         }
         if (!options.agentTools) {
@@ -1455,8 +1539,9 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
             // Populate agentTools and _profile from discovered profile if not already set.
             // _profile is threaded into executeStep so capability-based skip gates
             // (e.g. account-mode branching) can read raw_capabilities at step time.
-            if (!options.agentTools && profile?.tools) {
-                options = { ...options, agentTools: profile.tools, _profile: profile };
+            const profileTools = normalizeAgentToolNames(profile?.tools);
+            if (!options.agentTools && profileTools) {
+                options = { ...options, agentTools: profileTools, _profile: profile };
             }
             else if (profile && !options._profile) {
                 options = { ...options, _profile: profile };
@@ -1464,6 +1549,25 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
         }
         else {
             profile = options._profile;
+            const profileTools = normalizeAgentToolNames(profile?.tools);
+            if (!options.agentTools && profileTools) {
+                options = { ...options, agentTools: profileTools, _profile: profile };
+            }
+            else if (!options.agentTools &&
+                typeof clients[0]?.getAgentInfo === 'function') {
+                const discovered = await (0, client_1.getOrDiscoverProfile)(clients[0], options);
+                if (discovered.step.passed === false) {
+                    return buildDiscoveryFailedResult(agentUrls, storyboard, discovered.step);
+                }
+                profile = discovered.profile;
+                const discoveredTools = normalizeAgentToolNames(profile?.tools);
+                if (discoveredTools) {
+                    options = { ...options, agentTools: discoveredTools, _profile: profile };
+                }
+                else if (profile && !options._profile) {
+                    options = { ...options, _profile: profile };
+                }
+            }
         }
     }
     // Evaluate `requires` tags before any phase setup. The runner detects
@@ -1502,6 +1606,20 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
             };
         }
     }
+    if (storyboard.required_any_of_tools?.length && options.agentTools) {
+        const agentTools = new Set(options.agentTools);
+        const missing = storyboard.required_any_of_tools.find(family => !family.tools.some(tool => agentTools.has(tool)));
+        if (missing) {
+            const detail = `missing_required_tool_family: needs ${missing.tools.join(' or ')}` +
+                (missing.rationale ? ` (${missing.rationale})` : '');
+            if (!callerOwnsClients)
+                await (0, protocols_1.closeConnections)(options.protocol);
+            return {
+                ...buildRequiredAnyOfToolsMissingResult(agentUrls, storyboard, detail),
+                notices: preflightNotices,
+            };
+        }
+    }
     // Evaluate requires_capability predicate before any phase setup.
     // When the agent explicitly declared it doesn't support what this storyboard
     // tests (e.g. `adcp.idempotency.supported: false`), skip the whole storyboard
@@ -1527,12 +1645,11 @@ async function executeStoryboardPass(agentUrls, storyboard, options, dispatchOff
     // advertises none of them, skip the whole storyboard instead of producing
     // misleading per-step failures.
     //
-    // Gate condition: `options.agentTools` is falsy when the caller set
-    // `options._client` without also supplying `agentTools`. In that case the
-    // gate is a no-op — the caller accepted responsibility for tool compatibility
-    // by reusing an external client. The comply() path always populates
-    // `agentTools` before calling runStoryboard(), so the gate is always active
-    // in the standard runner flow.
+    // Gate condition: `options.agentTools` is populated from discovery or
+    // `_profile.tools` before this point, including reused-client callers when
+    // discovery is available. If a direct `_client` caller supplies neither
+    // `agentTools` nor a discoverable profile, this gate remains a no-op and
+    // step-level `requires_tool` checks carry the compatibility signal.
     if (storyboard.required_tools?.length && options.agentTools) {
         const hasAnyRequired = storyboard.required_tools.some(t => options.agentTools.includes(t));
         if (!hasAnyRequired) {
@@ -2725,7 +2842,9 @@ function summarizeStrictValidation(phases) {
  * Context is passed in and returned, enabling step-by-step orchestration.
  */
 async function runStoryboardStep(agentUrl, storyboard, stepId, options = {}) {
+    (0, loader_1.validateStoryboardShape)(storyboard);
     options = applyStoryboardVersionOptions(storyboard, options);
+    registerRunSchemaRoot(options);
     (0, test_kit_1.validateTestKit)(options.test_kit);
     const clientResolution = (0, client_1.getOrCreateClientResolution)(agentUrl, options);
     const client = clientResolution.client;
@@ -2817,7 +2936,7 @@ client, step, phaseId, context, allSteps, options, state) {
     };
     // HTTP probe tasks bypass the MCP client entirely.
     if (probes_1.PROBE_TASKS.has(step.task)) {
-        return executeProbeStep(step, phaseId, context, allSteps, options, runState);
+        return executeProbeStep(client, step, phaseId, context, allSteps, options, runState);
     }
     // Webhook-assertion pseudo-tasks observe the shared receiver instead of
     // driving the agent. They never reach the MCP/A2A transport.
@@ -3436,10 +3555,11 @@ client, step, phaseId, context, allSteps, options, state) {
         // synchronously. Adopters who don't advertise the scenario short-
         // circuit to a single `advertised: false` marker and every
         // upstream_traffic check on the step grades not_applicable.
-        const upstreamTraffic = await prefetchUpstreamTraffic(step.id, resolvedValidations, client, options, runState, requestStartIso);
+        const upstreamTraffic = await prefetchUpstreamTraffic(step.id, resolvedValidations, client, options, runState, requestStartIso, requestRecord.payload, step.sample_request);
         const vctx = {
             taskName: effectiveStep.task,
             ...(options.adcpVersion && { adcpVersion: options.adcpVersion }),
+            ...(options._serverAdcpVersion && { responseAdcpVersion: options._serverAdcpVersion }),
             ...(taskResult && { taskResult }),
             ...(httpResult && { httpResult }),
             agentUrl: runState.agentUrl,
@@ -3761,10 +3881,13 @@ client, step, phaseId, context, allSteps, options, state) {
 // ────────────────────────────────────────────────────────────
 // Probe dispatch (raw HTTP tasks)
 // ────────────────────────────────────────────────────────────
-async function executeProbeStep(step, phaseId, context, allSteps, options, runState) {
+async function executeProbeStep(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- client type varies (TestClient)
+client, step, phaseId, context, allSteps, options, runState) {
     const start = Date.now();
     let httpResult;
     const probeOpts = { allowPrivateIp: options.allow_http === true };
+    let requestRecordOverride;
     if (step.requires_contract) {
         const contracts = new Set(options.contracts ?? []);
         if (!contracts.has(step.requires_contract)) {
@@ -3815,33 +3938,116 @@ async function executeProbeStep(step, phaseId, context, allSteps, options, runSt
         httpResult = assertJwksPurpose(runState.priorProbes.get('fetch_brand_jwks'), 'webhook-signing');
     }
     else if (step.task === 'expect_rate_limit_not_replayed') {
-        httpResult = {
-            url: runState.agentUrl,
-            status: 0,
-            headers: {},
-            body: null,
-            error: 'rate_limit_trip_runner contract is configured, but this SDK runner does not yet implement live rate-limit trip/replay probing.',
-        };
+        const specError = (0, rate_limit_trip_1.validateRateLimitTripSpec)(step.rate_limit_trip);
+        if (specError) {
+            httpResult = {
+                url: runState.agentUrl,
+                status: 0,
+                headers: {},
+                body: { attempts: 0, error: 'rate_limit_trip_misconfigured' },
+                error: specError,
+            };
+        }
+        else {
+            const rateLimitTrip = step.rate_limit_trip;
+            const targetStep = {
+                ...step,
+                task: rateLimitTrip.trip_target_task,
+                sample_request: rateLimitTrip.trip_target_sample_request,
+                omit_idempotency_key: true,
+            };
+            const resolvedTargetRequest = buildEffectiveStepRequest(targetStep, context, options, runState);
+            const unresolvedVars = findUnresolvedContextVars(resolvedTargetRequest);
+            if (unresolvedVars.length > 0 && !targetStep.expect_error) {
+                const next = getNextStepPreview(step.id, allSteps, context, runState.runnerVars);
+                const detail = `Skipped: unresolved context variables from rate_limit_trip.trip_target_sample_request: ${unresolvedVars
+                    .map(v => v.key)
+                    .join(', ')}.`;
+                return {
+                    step_id: step.id,
+                    phase_id: phaseId,
+                    title: step.title,
+                    task: step.task,
+                    passed: false,
+                    skipped: true,
+                    skip_reason: 'prerequisite_failed',
+                    skip: buildSkip('prerequisite_failed', detail),
+                    duration_ms: Date.now() - start,
+                    validations: [],
+                    context,
+                    next,
+                    extraction: { path: 'none' },
+                    error: detail,
+                };
+            }
+            const advertisedTools = resolveAdvertisedTools(options);
+            if (advertisedTools && !advertisedTools.includes(rateLimitTrip.trip_target_task)) {
+                const next = getNextStepPreview(step.id, allSteps, context, runState.runnerVars);
+                const detail = `Agent did not advertise tool "${rateLimitTrip.trip_target_task}"; agent tools: [${advertisedTools.join(', ')}].`;
+                return {
+                    step_id: step.id,
+                    phase_id: phaseId,
+                    title: step.title,
+                    task: step.task,
+                    passed: true,
+                    skipped: true,
+                    skip_reason: 'missing_tool',
+                    skip: buildSkip('missing_tool', detail),
+                    duration_ms: Date.now() - start,
+                    validations: [],
+                    context,
+                    next,
+                    extraction: { path: 'none' },
+                };
+            }
+            const resolvedSpec = {
+                ...rateLimitTrip,
+                trip_target_sample_request: resolvedTargetRequest,
+            };
+            const targetTransport = options.protocol === 'a2a' ? 'a2a' : 'mcp';
+            const observer = new rate_limit_trip_1.RateLimitTripObserver(client, {
+                keyMinter: idempotency_1.generateIdempotencyKey,
+                correlationPrefix: step.id,
+                transport: targetTransport,
+            });
+            const observation = await observer.run(resolvedSpec);
+            httpResult = rateLimitTripObservationToProbeResult(runState.agentUrl, observation);
+            const observedRequest = observation.body.replay_request ?? observation.body.trip_request ?? resolvedTargetRequest;
+            requestRecordOverride = {
+                transport: targetTransport,
+                operation: rateLimitTrip.trip_target_task,
+                payload: (0, redact_secrets_1.redactSecrets)(observedRequest),
+                ...(runState.agentUrl ? { url: runState.agentUrl } : {}),
+            };
+        }
     }
     if (httpResult)
         runState.priorProbes.set(step.task, httpResult);
     const duration = Date.now() - start;
-    const requestRecord = {
+    const requestRecord = requestRecordOverride ?? {
         transport: 'http',
         operation: step.task,
         payload: null,
         ...(httpResult?.url ? { url: httpResult.url } : runState.agentUrl ? { url: runState.agentUrl } : {}),
     };
     const filteredProbeHeaders = filterResponseHeaders(httpResult?.headers);
+    const responseTransport = requestRecordOverride?.transport ?? 'http';
     const responseRecord = httpResult
         ? {
-            transport: 'http',
+            transport: responseTransport,
             payload: (0, redact_secrets_1.redactSecrets)(httpResult.body),
-            status: httpResult.status,
+            ...(responseTransport === 'http' && { status: httpResult.status }),
             ...(filteredProbeHeaders && { headers: filteredProbeHeaders }),
             duration_ms: duration,
         }
         : undefined;
+    const redactedHttpResult = httpResult
+        ? {
+            ...httpResult,
+            body: (0, redact_secrets_1.redactSecrets)(httpResult.body),
+            ...(responseTransport !== 'http' && { status: undefined }),
+        }
+        : undefined;
     // Probe may self-skip (request_signing_probe uses this for operator opt-outs
     // and capability-profile mismatches). Surface as a skipped step without
     // running validations — skip ≠ fail. The detailed reason goes on
@@ -3863,7 +4069,7 @@ async function executeProbeStep(step, phaseId, context, allSteps, options, runSt
             skip: { reason: canonicalReason, detail },
             ...(selectionResult && { selection_result: selectionResult }),
             duration_ms: duration,
-            response: httpResult,
+            response: redactedHttpResult,
             validations: [],
             context,
             next: getNextStepPreview(step.id, allSteps, context, runState.runnerVars),
@@ -3875,7 +4081,8 @@ async function executeProbeStep(step, phaseId, context, allSteps, options, runSt
     const vctx = {
         taskName: step.task,
         ...(options.adcpVersion && { adcpVersion: options.adcpVersion }),
-        httpResult,
+        ...(options._serverAdcpVersion && { responseAdcpVersion: options._serverAdcpVersion }),
+        httpResult: redactedHttpResult,
         agentUrl: runState.agentUrl,
         contributions: runState.contributions,
         request: requestRecord,
@@ -3901,7 +4108,7 @@ async function executeProbeStep(step, phaseId, context, allSteps, options, runSt
         task: step.task,
         passed,
         duration_ms: duration,
-        response: httpResult ?? undefined,
+        response: redactedHttpResult ?? undefined,
         validations,
         context,
         error: httpResult?.error ?? (passed ? undefined : 'Probe validations failed.'),
@@ -3911,6 +4118,63 @@ async function executeProbeStep(step, phaseId, context, allSteps, options, runSt
         extraction,
     };
 }
+function buildEffectiveStepRequest(step, context, options, runState) {
+    let request;
+    if (options.request) {
+        request = { ...options.request };
+    }
+    else if (step.expect_error && step.sample_request) {
+        request = (0, context_1.injectContext)({ ...step.sample_request }, context, runState.runnerVars);
+    }
+    else if ((0, request_builder_1.hasRequestEnricher)(step.task)) {
+        request = (0, request_builder_1.enrichRequest)(step, context, options, runState.runnerVars);
+    }
+    else if (step.sample_request) {
+        request = (0, context_1.injectContext)({ ...step.sample_request }, context, runState.runnerVars);
+    }
+    else {
+        request = {};
+    }
+    if (step.context_inputs?.length) {
+        request = (0, context_1.applyContextInputs)(request, step.context_inputs, context);
+    }
+    request = applyBrandInvariant(request, options, step.task, { omit_account: step.omit_account });
+    if (options.disable_sandbox === true) {
+        request = applyDisableSandboxHint(request, step.task);
+    }
+    return applyIdempotencyInvariant(request, step.task, step);
+}
+function resolveAdvertisedTools(options) {
+    return options.agentTools ?? normalizeAgentToolNames(options._profile?.tools);
+}
+function rateLimitTripObservationToProbeResult(agentUrl, observation) {
+    if (observation.status === 'not_applicable') {
+        return {
+            url: agentUrl,
+            status: 0,
+            headers: {},
+            body: observation.body,
+            skipped: true,
+            skip_reason: observation.skip_reason,
+            error: observation.message,
+        };
+    }
+    if (observation.status === 'failed') {
+        return {
+            url: agentUrl,
+            status: 0,
+            headers: {},
+            body: { ...observation.body, error: observation.error },
+            error: observation.message,
+        };
+    }
+    return {
+        url: agentUrl,
+        status: 200,
+        headers: {},
+        body: observation.body,
+    };
+}
 async function probeBrandJwks(rawCapabilities, options) {
     const brandJsonUrl = (0, capabilities_types_1.readBrandJsonUrl)(rawCapabilities);
     if (!brandJsonUrl) {
@@ -4455,10 +4719,13 @@ function truncateError(error) {
  * controller does not advertise `query_upstream_traffic` (every check
  * grades not_applicable per the spec's adopter-opt-in rule).
  */
-async function prefetchUpstreamTraffic(stepId, resolvedValidations, client, options, runState, requestStartIso) {
+async function prefetchUpstreamTraffic(stepId, resolvedValidations, client, options, runState, requestStartIso, requestPayload, sampleRequest) {
     const upstreamChecks = resolvedValidations.filter(v => v.check === 'upstream_traffic');
     if (upstreamChecks.length === 0)
         return undefined;
+    if (upstreamChecks.some(check => (check.identifier_paths ?? []).some(path => (0, path_1.validatePortableIdentifierPath)(path)))) {
+        return undefined;
+    }
     const advertised = options._controllerCapabilities?.detected === true &&
         options._controllerCapabilities.scenarios.includes('query_upstream_traffic');
     if (!advertised) {
@@ -4492,6 +4759,11 @@ async function prefetchUpstreamTraffic(stepId, resolvedValidations, client, opti
         }
     }
     const queries = new Map();
+    const identifierDigestCollection = collectUpstreamIdentifierDigests(upstreamChecks, requestPayload, sampleRequest);
+    const identifierDigestByValue = identifierDigestCollection.digests;
+    const identifier_value_digests = [...identifierDigestByValue.values()];
+    const requiresRawAttestation = upstreamChecks.some(check => check.attestation_mode_required === 'raw' || (check.payload_must_contain?.length ?? 0) > 0);
+    const requestedAttestationMode = !requiresRawAttestation && identifier_value_digests.length > 0 ? 'digest' : 'raw';
     for (const sinceTs of sinceTimestamps) {
         // Per spec PR adcp#3816: runners SHOULD subtract a clock-skew tolerance
         // (50ms minimum, 250ms recommended) before sending the bound to the
@@ -4499,7 +4771,12 @@ async function prefetchUpstreamTraffic(stepId, resolvedValidations, client, opti
         // runner's clock measurement isn't silently excluded. We use 250ms (the
         // spec's recommended value).
         const adjustedSince = new Date(new Date(sinceTs).getTime() - 250).toISOString();
-        const params = { since_timestamp: adjustedSince, limit: 100 };
+        const params = {
+            since_timestamp: adjustedSince,
+            limit: 100,
+            attestation_mode: requestedAttestationMode,
+            ...(identifier_value_digests.length > 0 ? { identifier_value_digests } : {}),
+        };
         const requestRecord = {
             transport: options.protocol === 'a2a' ? 'a2a' : 'mcp',
             operation: 'comply_test_controller',
@@ -4518,7 +4795,8 @@ async function prefetchUpstreamTraffic(stepId, resolvedValidations, client, opti
                 const message = errResult.error_detail
                     ? `${errResult.error ?? 'controller_error'}: ${errResult.error_detail}`
                     : (errResult.error ?? 'controller returned a non-success response');
-                payload = { error: message };
+                const errorKind = extractControllerErrorKind(errResult);
+                payload = { error: message, ...(errorKind ? { error_kind: errorKind } : {}) };
             }
         }
         catch (err) {
@@ -4535,10 +4813,65 @@ async function prefetchUpstreamTraffic(stepId, resolvedValidations, client, opti
         advertised: true,
         queries,
         thisStepSince: requestStartIso,
+        ...(identifierDigestByValue.size > 0 ? { identifierDigestByValue } : {}),
+        ...(identifierDigestCollection.clipped > 0
+            ? {
+                identifierDigestLimitExceeded: {
+                    limit: identifierDigestCollection.limit,
+                    clipped: identifierDigestCollection.clipped,
+                },
+            }
+            : {}),
         ...(priorStepSinceMap.size > 0 ? { priorStepSinceMap } : {}),
         ...(unresolvedSinceRefs.size > 0 ? { unresolvedSinceRefs } : {}),
     };
 }
+function extractControllerErrorKind(result) {
+    return readErrorKind(result.context) ?? readErrorKind(result.ext);
+}
+function readErrorKind(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const record = value;
+    if (typeof record.error_kind === 'string' && record.error_kind.length > 0)
+        return record.error_kind;
+    if (typeof record.kind === 'string' && record.kind.length > 0)
+        return record.kind;
+    return undefined;
+}
+function collectUpstreamIdentifierDigests(validations, requestPayload, sampleRequest) {
+    const digests = new Map();
+    let clipped = 0;
+    const sample = requestPayload && typeof requestPayload === 'object' && !Array.isArray(requestPayload)
+        ? requestPayload
+        : sampleRequest;
+    if (!sample)
+        return { digests, limit: constants_1.IDENTIFIER_DIGEST_LIMIT, clipped };
+    const clippedVectors = new Set();
+    for (const validation of validations) {
+        for (const path of validation.identifier_paths ?? []) {
+            const vectors = (0, path_1.resolvePortableIdentifierPathAll)(sample, path);
+            for (const vector of vectors) {
+                if (typeof vector !== 'string')
+                    continue;
+                if (digests.has(vector))
+                    continue;
+                if (digests.size >= constants_1.IDENTIFIER_DIGEST_LIMIT) {
+                    if (!clippedVectors.has(vector)) {
+                        clippedVectors.add(vector);
+                        clipped++;
+                    }
+                    continue;
+                }
+                digests.set(vector, sha256Hex(vector));
+            }
+        }
+    }
+    return { digests, limit: constants_1.IDENTIFIER_DIGEST_LIMIT, clipped };
+}
+function sha256Hex(value) {
+    return (0, node_crypto_1.createHash)('sha256').update(value, 'utf8').digest('hex');
+}
 /**
  * Find any "$context.xxx" strings that weren't resolved during injection.
  * Returns one entry per occurrence with both the bare key (for legacy