@adcp/sdk 5.23.0

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

@@ -0,0 +1,282 @@
+"use strict";
+/**
+ * Pre-flight `comply_test_controller` seeding.
+ *
+ * Spec: adcontextprotocol/adcp#2585 (fixtures block + `controller_seeding`
+ * flag) + adcontextprotocol/adcp#2584 (seed_* scenarios on
+ * `comply_test_controller`). Storyboards such as `sales_non_guaranteed`,
+ * `creative_ad_server`, `governance_delivery_monitor`,
+ * `media_buy_governance_escalation`, and `governance_spend_authority`
+ * reference fixture IDs (product_ids, pricing_option_ids, creative_ids,
+ * plan_ids, media_buy_ids) that the seller must already hold before the
+ * buyer-side flow runs. This module fires the `seed_*` scenarios derived
+ * from the storyboard's top-level `fixtures:` block before the first real
+ * phase, so the seller's catalog is populated ahead of any `create_media_buy`
+ * / `sync_creatives` / etc. call that would otherwise fail with
+ * `PRODUCT_NOT_FOUND`.
+ *
+ * Failures here surface as a dedicated synthetic phase (`__controller_seeding__`)
+ * so an implementor reading the report can distinguish "setup broke" from
+ * "buyer did something wrong" — the runner short-circuits the rest of the
+ * phases on any seed failure, emitting a cascade skip with reason
+ * `controller_seeding_failed`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONTROLLER_SEEDING_PHASE_ID = void 0;
+exports.buildSeedCalls = buildSeedCalls;
+exports.runControllerSeeding = runControllerSeeding;
+const test_controller_1 = require("../test-controller");
+/** Synthetic phase id used in `StoryboardResult.phases[]` for the seed pass. */
+exports.CONTROLLER_SEEDING_PHASE_ID = '__controller_seeding__';
+/**
+ * Translate a storyboard `fixtures:` block into an ordered list of seed
+ * calls. Each entry's id field(s) are lifted into the scenario params; every
+ * remaining field rides in `params.fixture` verbatim. Missing required ids
+ * produce an authoring-error marker the runner surfaces as a failed seed
+ * step (rather than crashing or silently skipping).
+ */
+// Top-level fixture keys are forwarded to the server verbatim inside
+// `params.fixture`. Prototype-pollution rejection (`__proto__`, `constructor`,
+// `prototype`) is enforced by the server-side `dispatchSeed` at a single
+// canonical point (`src/lib/server/test-controller.ts`), NOT re-guarded here:
+// surfacing the rejection through the normal seed-error path keeps one source
+// of truth for the check, and the server-side handler is where a seed request
+// can actually land from any client implementation. A future refactor that
+// removes the server check must add the client guard before removing it.
+function buildSeedCalls(fixtures) {
+    if (!fixtures)
+        return [];
+    const calls = [];
+    (fixtures.products ?? []).forEach((entry, i) => {
+        const { product_id, ...fixture } = entry;
+        const label = product_id ?? `#${i}`;
+        if (typeof product_id !== 'string' || product_id.length === 0) {
+            calls.push({
+                step_id: `seed_product.${label}`,
+                title: `Seed product ${label}`,
+                scenario: 'seed_product',
+                params: { fixture },
+                authoring_error: `fixtures.products[${i}] requires a non-empty string 'product_id'`,
+            });
+            return;
+        }
+        calls.push({
+            step_id: `seed_product.${product_id}`,
+            title: `Seed product ${product_id}`,
+            scenario: 'seed_product',
+            params: { product_id, fixture },
+        });
+    });
+    (fixtures.pricing_options ?? []).forEach((entry, i) => {
+        const { product_id, pricing_option_id, ...fixture } = entry;
+        const label = pricing_option_id && product_id
+            ? `${product_id}:${pricing_option_id}`
+            : (pricing_option_id ?? product_id ?? `#${i}`);
+        const missing = [];
+        if (typeof product_id !== 'string' || product_id.length === 0)
+            missing.push('product_id');
+        if (typeof pricing_option_id !== 'string' || pricing_option_id.length === 0)
+            missing.push('pricing_option_id');
+        if (missing.length > 0) {
+            calls.push({
+                step_id: `seed_pricing_option.${label}`,
+                title: `Seed pricing option ${label}`,
+                scenario: 'seed_pricing_option',
+                params: { ...(product_id && { product_id }), ...(pricing_option_id && { pricing_option_id }), fixture },
+                authoring_error: `fixtures.pricing_options[${i}] requires non-empty string(s) for: ${missing.join(', ')}`,
+            });
+            return;
+        }
+        calls.push({
+            step_id: `seed_pricing_option.${product_id}.${pricing_option_id}`,
+            title: `Seed pricing option ${pricing_option_id} on ${product_id}`,
+            scenario: 'seed_pricing_option',
+            params: { product_id, pricing_option_id, fixture },
+        });
+    });
+    (fixtures.creatives ?? []).forEach((entry, i) => {
+        const { creative_id, ...fixture } = entry;
+        const label = creative_id ?? `#${i}`;
+        if (typeof creative_id !== 'string' || creative_id.length === 0) {
+            calls.push({
+                step_id: `seed_creative.${label}`,
+                title: `Seed creative ${label}`,
+                scenario: 'seed_creative',
+                params: { fixture },
+                authoring_error: `fixtures.creatives[${i}] requires a non-empty string 'creative_id'`,
+            });
+            return;
+        }
+        calls.push({
+            step_id: `seed_creative.${creative_id}`,
+            title: `Seed creative ${creative_id}`,
+            scenario: 'seed_creative',
+            params: { creative_id, fixture },
+        });
+    });
+    (fixtures.plans ?? []).forEach((entry, i) => {
+        const { plan_id, ...fixture } = entry;
+        const label = plan_id ?? `#${i}`;
+        if (typeof plan_id !== 'string' || plan_id.length === 0) {
+            calls.push({
+                step_id: `seed_plan.${label}`,
+                title: `Seed plan ${label}`,
+                scenario: 'seed_plan',
+                params: { fixture },
+                authoring_error: `fixtures.plans[${i}] requires a non-empty string 'plan_id'`,
+            });
+            return;
+        }
+        calls.push({
+            step_id: `seed_plan.${plan_id}`,
+            title: `Seed plan ${plan_id}`,
+            scenario: 'seed_plan',
+            params: { plan_id, fixture },
+        });
+    });
+    (fixtures.media_buys ?? []).forEach((entry, i) => {
+        const { media_buy_id, ...fixture } = entry;
+        const label = media_buy_id ?? `#${i}`;
+        if (typeof media_buy_id !== 'string' || media_buy_id.length === 0) {
+            calls.push({
+                step_id: `seed_media_buy.${label}`,
+                title: `Seed media buy ${label}`,
+                scenario: 'seed_media_buy',
+                params: { fixture },
+                authoring_error: `fixtures.media_buys[${i}] requires a non-empty string 'media_buy_id'`,
+            });
+            return;
+        }
+        calls.push({
+            step_id: `seed_media_buy.${media_buy_id}`,
+            title: `Seed media buy ${media_buy_id}`,
+            scenario: 'seed_media_buy',
+            params: { media_buy_id, fixture },
+        });
+    });
+    return calls;
+}
+/**
+ * Fire every seed call for this storyboard. Returns `null` when seeding is
+ * not applicable (opt-out, no declaration, empty fixtures) so the runner can
+ * treat a no-op identically to a non-seeding storyboard.
+ */
+async function runControllerSeeding(client, storyboard, options, context) {
+    if (options.skip_controller_seeding === true)
+        return null;
+    if (storyboard.prerequisites?.controller_seeding !== true)
+        return null;
+    const calls = buildSeedCalls(storyboard.fixtures);
+    if (calls.length === 0)
+        return null;
+    // If we can see the agent's tool list and `comply_test_controller` is
+    // absent, grade as not_applicable rather than issuing calls that are
+    // guaranteed to fail on the wire. Spec: `fixture_seed_unsupported` in
+    // storyboard-schema.yaml — missing test-controller is a coverage gap, not
+    // a setup break. `options.agentTools` is discovered from the agent profile
+    // or passed explicitly by the caller; we don't enforce when it's absent
+    // because some harnesses skip tool discovery.
+    if (options.agentTools && !options.agentTools.includes('comply_test_controller')) {
+        return buildMissingControllerResult(storyboard, calls, context);
+    }
+    const start = Date.now();
+    const steps = [];
+    let passedCount = 0;
+    let failedCount = 0;
+    let allPassed = true;
+    for (const call of calls) {
+        const stepStart = Date.now();
+        let passed = false;
+        let error;
+        if (call.authoring_error) {
+            error = call.authoring_error;
+        }
+        else {
+            try {
+                const raw = await (0, test_controller_1.callControllerRaw)(client, { scenario: call.scenario, params: call.params }, options);
+                const data = raw.data;
+                if (raw.success && data?.success === true) {
+                    passed = true;
+                }
+                else {
+                    error = formatControllerError(call.scenario, raw, data);
+                }
+            }
+            catch (err) {
+                error = err instanceof Error ? err.message : String(err);
+            }
+        }
+        const step = {
+            storyboard_id: storyboard.id,
+            step_id: call.step_id,
+            phase_id: exports.CONTROLLER_SEEDING_PHASE_ID,
+            title: call.title,
+            task: 'comply_test_controller',
+            passed,
+            duration_ms: Date.now() - stepStart,
+            validations: [],
+            context,
+            extraction: { path: 'none' },
+            ...(error !== undefined && { error }),
+        };
+        steps.push(step);
+        if (passed) {
+            passedCount++;
+        }
+        else {
+            failedCount++;
+            allPassed = false;
+        }
+    }
+    return {
+        phase: {
+            phase_id: exports.CONTROLLER_SEEDING_PHASE_ID,
+            phase_title: 'Controller seeding (pre-flight)',
+            passed: allPassed,
+            steps,
+            duration_ms: Date.now() - start,
+        },
+        allPassed,
+        passedCount,
+        failedCount,
+    };
+}
+function formatControllerError(scenario, raw, data) {
+    if (data?.error_detail)
+        return data.error ? `${data.error}: ${data.error_detail}` : data.error_detail;
+    if (data?.error)
+        return data.error;
+    return raw.error ?? `comply_test_controller ${scenario} call failed`;
+}
+const MISSING_CONTROLLER_DETAIL = 'Skipped: agent did not advertise comply_test_controller, so fixture seeding (`fixture_seed_unsupported`) cannot run. Storyboard grades not_applicable — the buyer-side flow depends on pre-seeded state the agent has no way to accept.';
+function buildMissingControllerResult(storyboard, calls, context) {
+    const steps = calls.map(call => ({
+        storyboard_id: storyboard.id,
+        step_id: call.step_id,
+        phase_id: exports.CONTROLLER_SEEDING_PHASE_ID,
+        title: call.title,
+        task: 'comply_test_controller',
+        passed: true,
+        skipped: true,
+        skip_reason: 'missing_test_controller',
+        skip: { reason: 'missing_test_controller', detail: MISSING_CONTROLLER_DETAIL },
+        duration_ms: 0,
+        validations: [],
+        context,
+        extraction: { path: 'none' },
+    }));
+    return {
+        phase: {
+            phase_id: exports.CONTROLLER_SEEDING_PHASE_ID,
+            phase_title: 'Controller seeding (pre-flight) — agent lacks comply_test_controller',
+            passed: true,
+            steps,
+            duration_ms: 0,
+        },
+        allPassed: true,
+        passedCount: 0,
+        failedCount: 0,
+        missingController: true,
+    };
+}
+//# sourceMappingURL=seeding.js.map

package/dist/lib/testing/storyboard/seeding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seeding.js","sourceRoot":"","sources":["../../../../src/lib/testing/storyboard/seeding.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;;;AA8CH,wCAoHC;AAyBD,oDAmFC;AA3QD,wDAAuD;AAUvD,gFAAgF;AACnE,QAAA,2BAA2B,GAAG,wBAAwB,CAAC;AAiBpE;;;;;;GAMG;AACH,qEAAqE;AACrE,+EAA+E;AAC/E,yEAAyE;AACzE,8EAA8E;AAC9E,8EAA8E;AAC9E,8EAA8E;AAC9E,2EAA2E;AAC3E,yEAAyE;AACzE,SAAgB,cAAc,CAAC,QAAwC;IACrE,IAAI,CAAC,QAAQ;QAAE,OAAO,EAAE,CAAC;IACzB,MAAM,KAAK,GAAe,EAAE,CAAC;IAE7B,CAAC,QAAQ,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;QAC7C,MAAM,EAAE,UAAU,EAAE,GAAG,OAAO,EAAE,GAAG,KAAK,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,IAAI,IAAI,CAAC,EAAE,CAAC;QACpC,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9D,KAAK,CAAC,IAAI,CAAC;gBACT,OAAO,EAAE,gBAAgB,KAAK,EAAE;gBAChC,KAAK,EAAE,gBAAgB,KAAK,EAAE;gBAC9B,QAAQ,EAAE,cAAc;gBACxB,MAAM,EAAE,EAAE,OAAO,EAAE;gBACnB,eAAe,EAAE,qBAAqB,CAAC,4CAA4C;aACpF,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QACD,KAAK,CAAC,IAAI,CAAC;YACT,OAAO,EAAE,gBAAgB,UAAU,EAAE;YACrC,KAAK,EAAE,gBAAgB,UAAU,EAAE;YACnC,QAAQ,EAAE,cAAc;YACxB,MAAM,EAAE,EAAE,UAAU,EAAE,OAAO,EAAE;SAChC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,CAAC,QAAQ,CAAC,eAAe,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;QACpD,MAAM,EAAE,UAAU,EAAE,iBAAiB,EAAE,GAAG,OAAO,EAAE,GAAG,KAAK,CAAC;QAC5D,MAAM,KAAK,GACT,iBAAiB,IAAI,UAAU;YAC7B,CAAC,CAAC,GAAG,UAAU,IAAI,iBAAiB,EAAE;YACtC,CAAC,CAAC,CAAC,iBAAiB,IAAI,UAAU,IAAI,IAAI,CAAC,EAAE,CAAC,CAAC;QACnD,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,IAAI,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAC1F,IAAI,OAAO,iBAAiB,KAAK,QAAQ,IAAI,iBAAiB,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;QAC/G,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,KAAK,CAAC,IAAI,CAAC;gBACT,OAAO,EAAE,uBAAuB,KAAK,EAAE;gBACvC,KAAK,EAAE,uBAAuB,KAAK,EAAE;gBACrC,QAAQ,EAAE,qBAAqB;gBAC/B,MAAM,EAAE,EAAE,GAAG,CAAC,UAAU,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,GAAG,CAAC,iBAAiB,IAAI,EAAE,iBAAiB,EAAE,CAAC,EAAE,OAAO,EAAE;gBACvG,eAAe,EAAE,4BAA4B,CAAC,uCAAuC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;aAC1G,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QACD,KAAK,CAAC,IAAI,CAAC;YACT,OAAO,EAAE,uBAAuB,UAAU,IAAI,iBAAiB,EAAE;YACjE,KAAK,EAAE,uBAAuB,iBAAiB,OAAO,UAAU,EAAE;YAClE,QAAQ,EAAE,qBAAqB;YAC/B,MAAM,EAAE,EAAE,UAAU,EAAE,iBAAiB,EAAE,OAAO,EAAE;SACnD,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,CAAC,QAAQ,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;QAC9C,MAAM,EAAE,WAAW,EAAE,GAAG,OAAO,EAAE,GAAG,KAAK,CAAC;QAC1C,MAAM,KAAK,GAAG,WAAW,IAAI,IAAI,CAAC,EAAE,CAAC;QACrC,IAAI,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAChE,KAAK,CAAC,IAAI,CAAC;gBACT,OAAO,EAAE,iBAAiB,KAAK,EAAE;gBACjC,KAAK,EAAE,iBAAiB,KAAK,EAAE;gBAC/B,QAAQ,EAAE,eAAe;gBACzB,MAAM,EAAE,EAAE,OAAO,EAAE;gBACnB,eAAe,EAAE,sBAAsB,CAAC,6CAA6C;aACtF,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QACD,KAAK,CAAC,IAAI,CAAC;YACT,OAAO,EAAE,iBAAiB,WAAW,EAAE;YACvC,KAAK,EAAE,iBAAiB,WAAW,EAAE;YACrC,QAAQ,EAAE,eAAe;YACzB,MAAM,EAAE,EAAE,WAAW,EAAE,OAAO,EAAE;SACjC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,CAAC,QAAQ,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;QAC1C,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,GAAG,KAAK,CAAC;QACtC,MAAM,KAAK,GAAG,OAAO,IAAI,IAAI,CAAC,EAAE,CAAC;QACjC,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxD,KAAK,CAAC,IAAI,CAAC;gBACT,OAAO,EAAE,aAAa,KAAK,EAAE;gBAC7B,KAAK,EAAE,aAAa,KAAK,EAAE;gBAC3B,QAAQ,EAAE,WAAW;gBACrB,MAAM,EAAE,EAAE,OAAO,EAAE;gBACnB,eAAe,EAAE,kBAAkB,CAAC,yCAAyC;aAC9E,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QACD,KAAK,CAAC,IAAI,CAAC;YACT,OAAO,EAAE,aAAa,OAAO,EAAE;YAC/B,KAAK,EAAE,aAAa,OAAO,EAAE;YAC7B,QAAQ,EAAE,WAAW;YACrB,MAAM,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE;SAC7B,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,CAAC,QAAQ,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;QAC/C,MAAM,EAAE,YAAY,EAAE,GAAG,OAAO,EAAE,GAAG,KAAK,CAAC;QAC3C,MAAM,KAAK,GAAG,YAAY,IAAI,IAAI,CAAC,EAAE,CAAC;QACtC,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClE,KAAK,CAAC,IAAI,CAAC;gBACT,OAAO,EAAE,kBAAkB,KAAK,EAAE;gBAClC,KAAK,EAAE,kBAAkB,KAAK,EAAE;gBAChC,QAAQ,EAAE,gBAAgB;gBAC1B,MAAM,EAAE,EAAE,OAAO,EAAE;gBACnB,eAAe,EAAE,uBAAuB,CAAC,8CAA8C;aACxF,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QACD,KAAK,CAAC,IAAI,CAAC;YACT,OAAO,EAAE,kBAAkB,YAAY,EAAE;YACzC,KAAK,EAAE,kBAAkB,YAAY,EAAE;YACvC,QAAQ,EAAE,gBAAgB;YAC1B,MAAM,EAAE,EAAE,YAAY,EAAE,OAAO,EAAE;SAClC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,OAAO,KAAK,CAAC;AACf,CAAC;AAoBD;;;;GAIG;AACI,KAAK,UAAU,oBAAoB,CACxC,MAAkB,EAClB,UAAsB,EACtB,OAA6B,EAC7B,OAA0B;IAE1B,IAAI,OAAO,CAAC,uBAAuB,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC1D,IAAI,UAAU,CAAC,aAAa,EAAE,kBAAkB,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACvE,MAAM,KAAK,GAAG,cAAc,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IAClD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEpC,sEAAsE;IACtE,qEAAqE;IACrE,sEAAsE;IACtE,0EAA0E;IAC1E,2EAA2E;IAC3E,wEAAwE;IACxE,8CAA8C;IAC9C,IAAI,OAAO,CAAC,UAAU,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,wBAAwB,CAAC,EAAE,CAAC;QACjF,OAAO,4BAA4B,CAAC,UAAU,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAClE,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,MAAM,KAAK,GAA2B,EAAE,CAAC;IACzC,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,SAAS,GAAG,IAAI,CAAC;IAErB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,IAAI,MAAM,GAAG,KAAK,CAAC;QACnB,IAAI,KAAyB,CAAC;QAE9B,IAAI,IAAI,CAAC,eAAe,EAAE,CAAC;YACzB,KAAK,GAAG,IAAI,CAAC,eAAe,CAAC;QAC/B,CAAC;aAAM,CAAC;YACN,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,MAAM,IAAA,mCAAiB,EAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,OAAO,CAAC,CAAC;gBACvG,MAAM,IAAI,GAAG,GAAG,CAAC,IAAgF,CAAC;gBAClG,IAAI,GAAG,CAAC,OAAO,IAAI,IAAI,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC;oBAC1C,MAAM,GAAG,IAAI,CAAC;gBAChB,CAAC;qBAAM,CAAC;oBACN,KAAK,GAAG,qBAAqB,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;gBAC1D,CAAC;YACH,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,KAAK,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YAC3D,CAAC;QACH,CAAC;QAED,MAAM,IAAI,GAAyB;YACjC,aAAa,EAAE,UAAU,CAAC,EAAE;YAC5B,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,QAAQ,EAAE,mCAA2B;YACrC,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,IAAI,EAAE,wBAAwB;YAC9B,MAAM;YACN,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;YACnC,WAAW,EAAE,EAAE;YACf,OAAO;YACP,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;YAC5B,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,CAAC;SACtC,CAAC;QACF,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACjB,IAAI,MAAM,EAAE,CAAC;YACX,WAAW,EAAE,CAAC;QAChB,CAAC;aAAM,CAAC;YACN,WAAW,EAAE,CAAC;YACd,SAAS,GAAG,KAAK,CAAC;QACpB,CAAC;IACH,CAAC;IAED,OAAO;QACL,KAAK,EAAE;YACL,QAAQ,EAAE,mCAA2B;YACrC,WAAW,EAAE,iCAAiC;YAC9C,MAAM,EAAE,SAAS;YACjB,KAAK;YACL,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK;SAChC;QACD,SAAS;QACT,WAAW;QACX,WAAW;KACZ,CAAC;AACJ,CAAC;AAED,SAAS,qBAAqB,CAC5B,QAAsB,EACtB,GAAyC,EACzC,IAA8E;IAE9E,IAAI,IAAI,EAAE,YAAY;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,YAAY,CAAC;IACtG,IAAI,IAAI,EAAE,KAAK;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC;IACnC,OAAO,GAAG,CAAC,KAAK,IAAI,0BAA0B,QAAQ,cAAc,CAAC;AACvE,CAAC;AAED,MAAM,yBAAyB,GAC7B,yOAAyO,CAAC;AAE5O,SAAS,4BAA4B,CACnC,UAAsB,EACtB,KAAgD,EAChD,OAA0B;IAE1B,MAAM,KAAK,GAA2B,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACvD,aAAa,EAAE,UAAU,CAAC,EAAE;QAC5B,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,QAAQ,EAAE,mCAA2B;QACrC,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,IAAI,EAAE,wBAAwB;QAC9B,MAAM,EAAE,IAAI;QACZ,OAAO,EAAE,IAAI;QACb,WAAW,EAAE,yBAAyB;QACtC,IAAI,EAAE,EAAE,MAAM,EAAE,yBAAyB,EAAE,MAAM,EAAE,yBAAyB,EAAE;QAC9E,WAAW,EAAE,CAAC;QACd,WAAW,EAAE,EAAE;QACf,OAAO;QACP,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;KAC7B,CAAC,CAAC,CAAC;IACJ,OAAO;QACL,KAAK,EAAE;YACL,QAAQ,EAAE,mCAA2B;YACrC,WAAW,EAAE,sEAAsE;YACnF,MAAM,EAAE,IAAI;YACZ,KAAK;YACL,WAAW,EAAE,CAAC;SACf;QACD,SAAS,EAAE,IAAI;QACf,WAAW,EAAE,CAAC;QACd,WAAW,EAAE,CAAC;QACd,iBAAiB,EAAE,IAAI;KACxB,CAAC;AACJ,CAAC"}

package/dist/lib/testing/storyboard/shape-drift-hints.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Structured shape-drift hint detection (issue #935).
+ *
+ * The runner emits one `ShapeDriftHint` per response when it recognizes a
+ * common payload-shape mistake — bare arrays from list tools, platform-
+ * native fields from `build_creative`, missing wrappers on `sync_creatives`
+ * / `preview_creative`. Each hint carries the same prose the legacy
+ * `detectShapeDriftHint` returned, plus structured fields (`tool`,
+ * `observed_variant`, `expected_variant`, `instance_path`) so renderers
+ * (CLI, Addie, JUnit, SARIF) can build per-case fix plans without re-
+ * parsing the message.
+ *
+ * The string-only `detectShapeDriftHint` in `validations.ts` is a thin
+ * shim over this detector — kept so existing unit tests and external
+ * callers keep working, but the canonical path is structured.
+ *
+ * Fires unconditionally (regardless of step pass/fail) — same gate as
+ * `ValidationResult.warning` carried previously. The caller (`runner.ts`)
+ * merges the result into `StoryboardStepResult.hints[]`.
+ */
+import type { ShapeDriftHint } from './types';
+/**
+ * List-shaped tools where handlers commonly return the bare inner array
+ * (`[{...}]`) at the top level instead of wrapping it in the required
+ * object envelope. Each entry names the wrapper key and the response
+ * helper that builds the correct shape.
+ *
+ * Helper names aren't uniformly prefixed — `get_products` uses
+ * `productsResponse` (no `get` prefix) while `get_media_buys` uses
+ * `getMediaBuysResponse`. Names match the exports in
+ * `src/lib/server/responses.ts` verbatim so a developer can grep
+ * straight from the hint.
+ */
+export declare const LIST_WRAPPER_TOOLS: Record<string, {
+    wrapperKey: string;
+    helper: string;
+}>;
+/**
+ * Detect shape-drift and return the structured hints that apply (zero or
+ * one — the detector emits at most one hint per response, but returns an
+ * array so callers can spread it into `step.hints[]` without a guard).
+ *
+ * @param taskName — tool name (snake_case) the storyboard dispatched under
+ * @param payload — raw response payload, after the runner's `_message`
+ *   pre-strip. `unknown` rather than `Record<string, unknown>` so bare-
+ *   array payloads are recognizable at the top level; object branches
+ *   guard internally.
+ * @param libraryVersion — optional SDK version string the agent self-reported
+ *   in `get_adcp_capabilities` (e.g. `"@adcp/client@4.16.2"`). When present
+ *   and below the helper's minimum version, the hint message is suffixed with
+ *   an upgrade note so developers know to update their SDK dep.
+ */
+export declare function detectShapeDriftHints(taskName: string, payload: unknown, libraryVersion?: string): ShapeDriftHint[];
+//# sourceMappingURL=shape-drift-hints.d.ts.map

package/dist/lib/testing/storyboard/shape-drift-hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape-drift-hints.d.ts","sourceRoot":"","sources":["../../../../src/lib/testing/storyboard/shape-drift-hints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AA0C9C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAWrF,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,cAAc,EAAE,CAKnH"}

package/dist/lib/testing/storyboard/shape-drift-hints.js

@@ -0,0 +1,200 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIST_WRAPPER_TOOLS = void 0;
+exports.detectShapeDriftHints = detectShapeDriftHints;
+/**
+ * Minimum @adcp/client version in which each server-side helper first shipped.
+ * Used to suffix shape-drift hints when the agent reports an older SDK version.
+ * Keys match the helper name referenced in the hint `message`.
+ */
+const HELPER_MIN_VERSION = {
+    buildCreativeResponse: '5.14.0',
+    listCreativesResponse: '5.10.0',
+    listCreativeFormatsResponse: '5.10.0',
+    listAccountsResponse: '5.10.0',
+    productsResponse: '5.10.0',
+    getMediaBuysResponse: '5.10.0',
+    getSignalsResponse: '5.10.0',
+    listPropertyListsResponse: '5.10.0',
+    listCollectionListsResponse: '5.10.0',
+    listContentStandardsResponse: '5.10.0',
+    getPlanAuditLogsResponse: '5.10.0',
+    syncCreativesResponse: '5.10.0',
+    previewCreativeResponse: '5.10.0',
+};
+/**
+ * Compare two semver strings using numeric segment ordering.
+ * Returns true when `a` is strictly less than `b`.
+ * Handles `@adcp/client@X.Y.Z` format by stripping the package prefix.
+ */
+function semverLessThan(a, b) {
+    // Strip package prefix (e.g. "@adcp/client@") and pre-release suffix (e.g. "-beta.1")
+    const normalize = (v) => v.replace(/^.*@/, '').replace(/-.*$/, '');
+    const segs = (v) => normalize(v)
+        .split('.')
+        .map(s => parseInt(s, 10) || 0);
+    const [aMaj = 0, aMin = 0, aPatch = 0] = segs(a);
+    const [bMaj = 0, bMin = 0, bPatch = 0] = segs(b);
+    if (aMaj !== bMaj)
+        return aMaj < bMaj;
+    if (aMin !== bMin)
+        return aMin < bMin;
+    return aPatch < bPatch;
+}
+/**
+ * List-shaped tools where handlers commonly return the bare inner array
+ * (`[{...}]`) at the top level instead of wrapping it in the required
+ * object envelope. Each entry names the wrapper key and the response
+ * helper that builds the correct shape.
+ *
+ * Helper names aren't uniformly prefixed — `get_products` uses
+ * `productsResponse` (no `get` prefix) while `get_media_buys` uses
+ * `getMediaBuysResponse`. Names match the exports in
+ * `src/lib/server/responses.ts` verbatim so a developer can grep
+ * straight from the hint.
+ */
+exports.LIST_WRAPPER_TOOLS = {
+    list_creatives: { wrapperKey: 'creatives', helper: 'listCreativesResponse' },
+    list_creative_formats: { wrapperKey: 'formats', helper: 'listCreativeFormatsResponse' },
+    list_accounts: { wrapperKey: 'accounts', helper: 'listAccountsResponse' },
+    get_products: { wrapperKey: 'products', helper: 'productsResponse' },
+    get_media_buys: { wrapperKey: 'media_buys', helper: 'getMediaBuysResponse' },
+    get_signals: { wrapperKey: 'signals', helper: 'getSignalsResponse' },
+    list_property_lists: { wrapperKey: 'lists', helper: 'listPropertyListsResponse' },
+    list_collection_lists: { wrapperKey: 'lists', helper: 'listCollectionListsResponse' },
+    list_content_standards: { wrapperKey: 'standards', helper: 'listContentStandardsResponse' },
+    get_plan_audit_logs: { wrapperKey: 'plans', helper: 'getPlanAuditLogsResponse' },
+};
+/**
+ * Detect shape-drift and return the structured hints that apply (zero or
+ * one — the detector emits at most one hint per response, but returns an
+ * array so callers can spread it into `step.hints[]` without a guard).
+ *
+ * @param taskName — tool name (snake_case) the storyboard dispatched under
+ * @param payload — raw response payload, after the runner's `_message`
+ *   pre-strip. `unknown` rather than `Record<string, unknown>` so bare-
+ *   array payloads are recognizable at the top level; object branches
+ *   guard internally.
+ * @param libraryVersion — optional SDK version string the agent self-reported
+ *   in `get_adcp_capabilities` (e.g. `"@adcp/client@4.16.2"`). When present
+ *   and below the helper's minimum version, the hint message is suffixed with
+ *   an upgrade note so developers know to update their SDK dep.
+ */
+function detectShapeDriftHints(taskName, payload, libraryVersion) {
+    const hint = detect(taskName, payload);
+    if (!hint)
+        return [];
+    if (libraryVersion)
+        hint.message = appendVersionSuffix(hint.message, libraryVersion);
+    return [hint];
+}
+/**
+ * If the hint message references a helper that requires a minimum SDK
+ * version and the agent's reported version is below it, append an upgrade
+ * note to the message. Returns the message unchanged if no version data or
+ * no match.
+ */
+function appendVersionSuffix(message, libraryVersion) {
+    // Skip non-numeric version strings (e.g. "local-dev") to avoid spurious suffixes
+    const stripped = libraryVersion.replace(/^.*@/, '').replace(/-.*$/, '');
+    if (!/^\d+\.\d+/.test(stripped))
+        return message;
+    for (const [helper, minVersion] of Object.entries(HELPER_MIN_VERSION)) {
+        if (message.includes(helper) && semverLessThan(libraryVersion, minVersion)) {
+            return (message +
+                ` (Note: your agent reports ${libraryVersion} — ${helper}() ships in @adcp/client ≥${minVersion}. Upgrade your SDK dep.)`);
+        }
+    }
+    return message;
+}
+function detect(taskName, payload) {
+    if (Array.isArray(payload)) {
+        const listMeta = exports.LIST_WRAPPER_TOOLS[taskName];
+        if (!listMeta)
+            return undefined;
+        return {
+            kind: 'shape_drift',
+            tool: taskName,
+            observed_variant: 'bare_array',
+            expected_variant: `{ ${listMeta.wrapperKey}: [...] }`,
+            instance_path: '',
+            message: `${taskName} returned a bare array at the top level. ` +
+                `Required: { ${listMeta.wrapperKey}: [...] }. ` +
+                `Use ${listMeta.helper}() from @adcp/sdk/server.`,
+        };
+    }
+    if (typeof payload !== 'object' || payload === null)
+        return undefined;
+    const p = payload;
+    if (taskName === 'build_creative') {
+        const hasManifest = 'creative_manifest' in p || 'creative_manifests' in p;
+        const platformNativeKeys = ['tag_url', 'creative_id', 'media_type', 'tag_type'];
+        const platformNativePresent = platformNativeKeys.filter(k => k in p);
+        if (!hasManifest && platformNativePresent.length > 0) {
+            return {
+                kind: 'shape_drift',
+                tool: taskName,
+                observed_variant: 'platform_native_fields',
+                expected_variant: '{ creative_manifest: { format_id, assets } }',
+                instance_path: '',
+                message: `build_creative returned platform-native fields at the top level (${platformNativePresent.join(', ')}). ` +
+                    `Required: { creative_manifest: { format_id, assets } }. ` +
+                    `Use buildCreativeResponse() from @adcp/sdk/server.`,
+            };
+        }
+    }
+    if (taskName === 'sync_creatives') {
+        const hasValidWrapper = 'creatives' in p || 'errors' in p || 'task_id' in p;
+        const perItemKeys = ['creative_id', 'platform_id', 'action'];
+        const perItemPresent = perItemKeys.filter(k => k in p);
+        if (!hasValidWrapper && perItemPresent.length > 0) {
+            return {
+                kind: 'shape_drift',
+                tool: taskName,
+                observed_variant: 'per_item_shape',
+                expected_variant: '{ creatives: [{ creative_id, action, ... }] }',
+                instance_path: '',
+                message: `sync_creatives returned a single creative's inner shape at the top level (${perItemPresent.join(', ')}). ` +
+                    `Required: { creatives: [{ creative_id, action, ... }] } (or { errors: [...] } / { status: 'submitted', task_id }). ` +
+                    `Use syncCreativesResponse() from @adcp/sdk/server.`,
+            };
+        }
+        const results = p.results;
+        if (!hasValidWrapper && Array.isArray(results) && results.length > 0) {
+            const firstRow = results[0];
+            const looksLikeCreativeRow = firstRow != null && typeof firstRow === 'object' && ('creative_id' in firstRow || 'action' in firstRow);
+            if (looksLikeCreativeRow) {
+                return {
+                    kind: 'shape_drift',
+                    tool: taskName,
+                    observed_variant: 'wrong_wrapper_key',
+                    expected_variant: '{ creatives: [{ creative_id, action, ... }] }',
+                    instance_path: '/results',
+                    message: `sync_creatives returned { results: [...] } instead of { creatives: [...] } — wrong wrapper key. ` +
+                        `Required: { creatives: [{ creative_id, action, ... }] }. ` +
+                        `Use syncCreativesResponse() from @adcp/sdk/server.`,
+                };
+            }
+        }
+    }
+    if (taskName === 'preview_creative') {
+        const hasValidWrapper = 'response_type' in p || 'previews' in p || 'results' in p;
+        const rawRenderKeys = ['preview_url', 'preview_html', 'interactive_url'];
+        const rawRenderPresent = rawRenderKeys.filter(k => k in p);
+        const driftSignal = rawRenderPresent.filter(k => k !== 'interactive_url');
+        if (!hasValidWrapper && driftSignal.length > 0) {
+            return {
+                kind: 'shape_drift',
+                tool: taskName,
+                observed_variant: 'raw_render_fields',
+                expected_variant: "{ response_type: 'single', previews: [{ renders: [...] }], expires_at }",
+                instance_path: '',
+                message: `preview_creative returned raw render fields at the top level (${driftSignal.join(', ')}). ` +
+                    `Required: { response_type: 'single', previews: [{ renders: [{ preview_url | preview_html }] }], expires_at }. ` +
+                    `Use previewCreativeResponse() from @adcp/sdk/server.`,
+            };
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=shape-drift-hints.js.map

package/dist/lib/testing/storyboard/shape-drift-hints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape-drift-hints.js","sourceRoot":"","sources":["../../../../src/lib/testing/storyboard/shape-drift-hints.ts"],"names":[],"mappings":"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"}

package/dist/lib/testing/storyboard/signer-grader/grader.d.ts

@@ -0,0 +1,56 @@
+import { type AdcpSignAlg, type ContentDigestPolicy } from '../../../signing';
+import type { SignerGradeReport } from './types';
+export interface GradeSignerOptions {
+    /** Agent URL of the signer being graded — used as `agent_url` in the report and as the host for the sample signed request. */
+    agentUrl: string;
+    /** `kid` the signer advertises in `Signature-Input`. Must match a JWK at the agent's `jwks_uri`. */
+    kid: string;
+    /** Algorithm the signer advertises. Must match `ALLOWED_ALGS` and the JWK's `alg`. */
+    algorithm: AdcpSignAlg;
+    /**
+     * Local JWK file (must include the private scalar `d`). Pick this OR
+     * `signerUrl` — the grader produces a `SigningProvider` from whichever
+     * is set.
+     */
+    keyFilePath?: string;
+    /**
+     * HTTP signing-oracle endpoint for KMS-backed signers. The grader POSTs
+     * `{ payload_b64, kid, alg }` and expects `{ signature_b64 }` back. The
+     * payload is the canonical RFC 9421 signature base; the response is raw
+     * wire-format signature bytes (Ed25519: 64-byte raw; ECDSA-P256:
+     * 64-byte `r‖s` IEEE P1363, NOT DER).
+     */
+    signerUrl?: string;
+    /** Optional `Authorization` header for the signer-url POSTs. */
+    signerAuth?: string;
+    /** JWKS endpoint to verify against. Required (no brand.json discovery in v1). */
+    jwksUrl: string;
+    /** AdCP operation to embed in the sample request body. Defaults to `create_media_buy`. */
+    operation?: string;
+    /**
+     * Content-digest policy the operator's verifier advertises. The grader
+     * exercises the same policy locally so a signer that fails to emit
+     * `Content-Digest` against a `'required'` policy surfaces here as
+     * `request_signature_components_incomplete` (step 6) — the same code a
+     * real counterparty would reject with. Defaults to `'required'`, which
+     * is the recommended posture for spend-committing operations.
+     */
+    coversContentDigest?: ContentDigestPolicy;
+    /** Allow http:// signer / JWKS URLs for development. Off by default. */
+    allowPrivateIp?: boolean;
+    /** Per-probe timeout. Defaults to 10000 ms. */
+    timeoutMs?: number;
+}
+/**
+ * Grade a signer end-to-end: produce a sample signed AdCP request through
+ * the operator's signer, verify the signature against the JWKS the
+ * operator publishes, report verifier-pipeline results step-by-step.
+ *
+ * Useful before pushing live signed traffic from a KMS-backed signer —
+ * surfaces algorithm-mismatch / kid-mismatch / DER-vs-P1363 / wrong-key
+ * failures as specific verifier error codes (the same codes a real
+ * counterparty would reject with), rather than a generic
+ * `request_signature_invalid` from the seller's monitoring.
+ */
+export declare function gradeSigner(options: GradeSignerOptions): Promise<SignerGradeReport>;
+//# sourceMappingURL=grader.d.ts.map

package/dist/lib/testing/storyboard/signer-grader/grader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grader.d.ts","sourceRoot":"","sources":["../../../../../src/lib/testing/storyboard/signer-grader/grader.ts"],"names":[],"mappings":"AAEA,OAAO,EAQL,KAAK,WAAW,EAChB,KAAK,mBAAmB,EAGzB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,iBAAiB,EAAmB,MAAM,SAAS,CAAC;AAElE,MAAM,WAAW,kBAAkB;IACjC,8HAA8H;IAC9H,QAAQ,EAAE,MAAM,CAAC;IACjB,oGAAoG;IACpG,GAAG,EAAE,MAAM,CAAC;IACZ,sFAAsF;IACtF,SAAS,EAAE,WAAW,CAAC;IACvB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IAC1C,wEAAwE;IACxE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA4GzF"}