@adcp/sdk 7.3.0 → 7.5.0

package/dist/lib/server/test-controller-bridge.js

@@ -18,11 +18,90 @@
  * Sellers provide a `getSeededProducts` callback that returns the list the
  * SDK should merge — which lets the same wiring work whether the backing
  * store is in-memory, Postgres, Redis, or a mock.
+ *
+ * ## Scope of verification (storyboard pass through this bridge)
+ *
+ * A storyboard run that succeeds because seeded fixtures were merged into
+ * the response verifies **protocol conformance against fixture data**:
+ * wire shape, error envelopes, idempotency, signed-request handling,
+ * sandbox stamping. It does **not** verify that the seller's adapter
+ * against the real upstream (e.g., social / search / programmatic
+ * inventory APIs) is working — the upstream response is shadowed by the
+ * post-handler merge.
+ *
+ * Treat this bridge as the conformance equivalent of a recorded-fixtures
+ * unit test, not an end-to-end integration test. Sellers should still
+ * exercise their adapters against a real (or sandbox) upstream OAuth tier
+ * separately; the typical pattern is a CLI runner pointed at a deployed
+ * sandbox URL with live credentials. The two together — storyboard-via-
+ * bridge plus live-OAuth runner — give wire conformance and adapter
+ * health respectively. See adcp-client#1775 for the cross-repo
+ * coordination on making bridge participation visible in storyboard
+ * run records.
+ *
+ * ## Adopter responsibilities
+ *
+ * **`resolveAccount` is the trust boundary.** The dispatcher's sandbox
+ * gate is "request carries a sandbox marker AND (resolved account is
+ * sandbox OR no account was resolved)." If you deploy a server with this
+ * bridge registered but no `resolveAccount` configured, a buyer can stamp
+ * `context.sandbox: true` on a request and trigger the merge. That's the
+ * intended behavior for storyboard runners with no account scoping, but
+ * means **production bindings must always configure `resolveAccount`** —
+ * otherwise the buyer-supplied sandbox marker is the only gate.
+ *
+ * **Multi-tenant isolation is the adopter's job.** Callbacks receive
+ * `ctx.account` and must key their fixture store on it. The SDK does no
+ * defensive cross-check between the account on the response entries and
+ * the `ctx.account` that asked for them. A sloppy session-store keying
+ * can return tenant A's fixtures to tenant B; nothing in this module
+ * will notice. Treat fixture stores like any other multi-tenant data
+ * layer.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isSandboxRequest = isSandboxRequest;
 exports.mergeSeededProductsIntoResponse = mergeSeededProductsIntoResponse;
 exports.filterValidSeededProducts = filterValidSeededProducts;
+exports.filterValidSeededCreatives = filterValidSeededCreatives;
+exports.filterValidSeededMediaBuys = filterValidSeededMediaBuys;
+exports.filterValidSeededMediaBuyDeliveries = filterValidSeededMediaBuyDeliveries;
+exports.filterValidSeededAccounts = filterValidSeededAccounts;
+exports.filterValidSeededAccountFinancials = filterValidSeededAccountFinancials;
+exports.filterValidSeededCreativeFormats = filterValidSeededCreativeFormats;
+exports.mergeSeededCreativesIntoResponse = mergeSeededCreativesIntoResponse;
+exports.mergeSeededMediaBuysIntoResponse = mergeSeededMediaBuysIntoResponse;
+exports.recomputeAggregatedTotals = recomputeAggregatedTotals;
+exports.mergeSeededMediaBuyDeliveryIntoResponse = mergeSeededMediaBuyDeliveryIntoResponse;
+exports.mergeSeededAccountsIntoResponse = mergeSeededAccountsIntoResponse;
+exports.pickSeededAccountFinancialsForRequest = pickSeededAccountFinancialsForRequest;
+exports.replaceAccountFinancialsIfSeeded = replaceAccountFinancialsIfSeeded;
+exports.mergeSeededCreativeFormatsIntoResponse = mergeSeededCreativeFormatsIntoResponse;
+exports.filterValidSeededPropertyLists = filterValidSeededPropertyLists;
+exports.filterValidSeededCollectionLists = filterValidSeededCollectionLists;
+exports.filterValidSeededContentStandards = filterValidSeededContentStandards;
+exports.mergeSeededPropertyListsIntoResponse = mergeSeededPropertyListsIntoResponse;
+exports.mergeSeededCollectionListsIntoResponse = mergeSeededCollectionListsIntoResponse;
+exports.mergeSeededContentStandardsIntoResponse = mergeSeededContentStandardsIntoResponse;
+exports.pickSeededPropertyListForRequest = pickSeededPropertyListForRequest;
+exports.replacePropertyListIfSeeded = replacePropertyListIfSeeded;
+exports.pickSeededCollectionListForRequest = pickSeededCollectionListForRequest;
+exports.replaceCollectionListIfSeeded = replaceCollectionListIfSeeded;
+exports.pickSeededContentStandardsForRequest = pickSeededContentStandardsForRequest;
+exports.replaceContentStandardsIfSeeded = replaceContentStandardsIfSeeded;
+exports.filterValidSeededSignals = filterValidSeededSignals;
+exports.filterValidSeededCreativeDelivery = filterValidSeededCreativeDelivery;
+exports.filterValidSeededCreativeFeatures = filterValidSeededCreativeFeatures;
+exports.mergeSeededSignalsIntoResponse = mergeSeededSignalsIntoResponse;
+exports.mergeSeededCreativeDeliveryIntoResponse = mergeSeededCreativeDeliveryIntoResponse;
+exports.mergeSeededCreativeFeaturesIntoResponse = mergeSeededCreativeFeaturesIntoResponse;
+exports.filterValidSeededBrandIdentity = filterValidSeededBrandIdentity;
+exports.filterValidSeededRights = filterValidSeededRights;
+exports.filterValidSeededSiOffering = filterValidSeededSiOffering;
+exports.mergeSeededRightsIntoResponse = mergeSeededRightsIntoResponse;
+exports.pickSeededBrandIdentityForRequest = pickSeededBrandIdentityForRequest;
+exports.replaceBrandIdentityIfSeeded = replaceBrandIdentityIfSeeded;
+exports.pickSeededSiOfferingForRequest = pickSeededSiOfferingForRequest;
+exports.replaceSiOfferingIfSeeded = replaceSiOfferingIfSeeded;
 exports.bridgeFromTestControllerStore = bridgeFromTestControllerStore;
 exports.bridgeFromSessionStore = bridgeFromSessionStore;
 const seed_merge_1 = require("../testing/seed-merge");
@@ -50,6 +129,25 @@ function isSandboxRequest(input) {
     }
     return false;
 }
+/**
+ * Detect the Submitted-arm shape (`{ status: 'submitted', task_id }`) on a
+ * read-tool response payload. `get_products` formally permits this arm per
+ * `schemas/cache/3.0.11/media-buy/get-products-async-response-submitted.json`
+ * (queued custom/bespoke product curation); the dispatcher's
+ * `isSubmittedEnvelope` routes the wrap, but the bridge merge runs after
+ * wrap and would spread `products: [...]` into the Submitted envelope
+ * without this guard.
+ *
+ * Mirrors the `isSubmittedEnvelope` predicate at
+ * `src/lib/server/create-adcp-server.ts` — kept local rather than imported
+ * because that helper lives inside the dispatcher closure.
+ */
+function isSubmittedArm(value) {
+    if (value == null || typeof value !== 'object')
+        return false;
+    const obj = value;
+    return obj.status === 'submitted' && typeof obj.task_id === 'string';
+}
 /**
  * Merge seeded products into a `get_products` response payload.
  *
@@ -62,10 +160,29 @@ function isSandboxRequest(input) {
  * handler explicitly declared `sandbox: false` (which stays authoritative
  * — a handler that has already decided the request is non-sandbox
  * shouldn't be overridden by the bridge).
+ *
+ * **Submitted-arm short-circuit.** `get_products` formally permits an
+ * async Submitted arm per `schemas/cache/3.0.11/media-buy/get-products-async-response-submitted.json`
+ * (queued custom/bespoke curation). The dispatcher routes
+ * `{ status: 'submitted', task_id }` handler returns through
+ * `wrapSubmittedEnvelope`, but the bridge merge then receives the
+ * unwrapped Submitted body from `formatted.structuredContent`. Without
+ * this guard, the merge would spread `products: [...]` into that body
+ * and produce a `{ status: 'submitted', task_id, products: [...], sandbox: true }`
+ * hybrid that violates the wire schema. Detect the Submitted shape and
+ * return the handler response reference-equal so the dispatcher's
+ * skip-on-reference-equality wrap-avoidance kicks in.
+ *
+ * None of the other 12 bridged read tools have a formal Submitted arm
+ * in 3.0.11 per `schemas/cache/3.0.11/core/async-response-data.json`;
+ * this guard is `get_products`-specific defense rather than a uniform
+ * pattern across helpers.
  */
 function mergeSeededProductsIntoResponse(response, seeded) {
     if (!seeded.length)
         return response;
+    if (isSubmittedArm(response))
+        return response;
     const seededIds = new Set();
     for (const p of seeded)
         seededIds.add(p.product_id);
@@ -116,6 +233,1277 @@ function filterValidSeededProducts(raw, logger) {
     });
     return valid;
 }
+// ---------------------------------------------------------------------------
+// Per-tool validation + merge helpers
+//
+// Each helper pair (`filterValidSeededXxx` + `mergeSeededXxxIntoResponse`)
+// mirrors the `filterValidSeededProducts` + `mergeSeededProductsIntoResponse`
+// shape. The semantics are identical: validate-and-drop on the input side,
+// dedupe-and-stamp-sandbox on the merge side. Symmetry is the point — adopters
+// who understand the products seam should be able to read the others at a
+// glance.
+// ---------------------------------------------------------------------------
+/**
+ * Validate seeded creatives. Drops entries that are not plain objects or are
+ * missing a non-empty string `creative_id` — matches the products contract
+ * (a missing identifier collides on `undefined === undefined` when deduping).
+ */
+function filterValidSeededCreatives(raw, logger) {
+    return filterValidById(raw, 'creative_id', 'getSeededCreatives', logger);
+}
+/**
+ * Validate seeded media buys. Drops entries missing a non-empty string
+ * `media_buy_id`.
+ */
+function filterValidSeededMediaBuys(raw, logger) {
+    return filterValidById(raw, 'media_buy_id', 'getSeededMediaBuys', logger);
+}
+/**
+ * Validate seeded media-buy-delivery snapshots. Drops entries missing a
+ * non-empty string `media_buy_id` — the dedup key against the handler set.
+ */
+function filterValidSeededMediaBuyDeliveries(raw, logger) {
+    return filterValidById(raw, 'media_buy_id', 'getSeededMediaBuyDelivery', logger);
+}
+/**
+ * Validate seeded accounts. Drops entries missing a non-empty string `account_id`.
+ */
+function filterValidSeededAccounts(raw, logger) {
+    return filterValidById(raw, 'account_id', 'getSeededAccounts', logger);
+}
+/**
+ * Validate seeded account-financials records. Drops entries whose `account`
+ * field is not a `{ account_id: string }`-shaped object (`AccountReference`
+ * carries `account_id` on the operator-resolved variant; the bridge keys on
+ * that field to match against the request's account).
+ *
+ * Also drops duplicate entries by `account.account_id` (first occurrence
+ * wins, matching the array-collection helpers' on-collision-seeded-wins
+ * contract — the "first" seeded entry in iteration order is authoritative).
+ * A fixture array with two entries for the same `account_id` is almost
+ * always a seed-store bug; warn-and-drop surfaces it instead of silently
+ * picking whichever happened to come first in iteration order.
+ */
+function filterValidSeededAccountFinancials(raw, logger) {
+    if (!Array.isArray(raw)) {
+        logger?.warn('testController.getSeededAccountFinancials did not return an array; skipping bridge', {
+            received: typeof raw,
+        });
+        return [];
+    }
+    const valid = [];
+    const seenAccountIds = new Set();
+    raw.forEach((entry, index) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            logger?.warn('testController.getSeededAccountFinancials entry is not an object; dropping', { index });
+            return;
+        }
+        const account = entry.account;
+        const accountId = account && typeof account === 'object' && !Array.isArray(account)
+            ? account.account_id
+            : undefined;
+        if (typeof accountId !== 'string' || accountId.length === 0) {
+            logger?.warn('testController.getSeededAccountFinancials entry missing account.account_id; dropping', { index });
+            return;
+        }
+        if (seenAccountIds.has(accountId)) {
+            logger?.warn('testController.getSeededAccountFinancials duplicate account.account_id; dropping (first occurrence wins)', { index, account_id: accountId });
+            return;
+        }
+        seenAccountIds.add(accountId);
+        valid.push(entry);
+    });
+    return valid;
+}
+/**
+ * Validate seeded creative formats. Drops entries whose `format_id` is not a
+ * `{ agent_url: string, id: string }`-shaped object — both fields are
+ * required to dedupe (and to canonicalize per the URL canonicalization rules
+ * in the AdCP spec).
+ */
+function filterValidSeededCreativeFormats(raw, logger) {
+    if (!Array.isArray(raw)) {
+        logger?.warn('testController.getSeededCreativeFormats did not return an array; skipping bridge', {
+            received: typeof raw,
+        });
+        return [];
+    }
+    const valid = [];
+    raw.forEach((entry, index) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            logger?.warn('testController.getSeededCreativeFormats entry is not an object; dropping', { index });
+            return;
+        }
+        const formatId = entry.format_id;
+        if (!formatId || typeof formatId !== 'object' || Array.isArray(formatId)) {
+            logger?.warn('testController.getSeededCreativeFormats entry missing format_id; dropping', { index });
+            return;
+        }
+        const agentUrl = formatId.agent_url;
+        const id = formatId.id;
+        if (typeof agentUrl !== 'string' || agentUrl.length === 0 || typeof id !== 'string' || id.length === 0) {
+            logger?.warn('testController.getSeededCreativeFormats entry has incomplete format_id (agent_url and id required); dropping', { index });
+            return;
+        }
+        valid.push(entry);
+    });
+    return valid;
+}
+/**
+ * Shared by-`id` validator for collections whose entries dedupe on a single
+ * top-level string field (creatives → `creative_id`, media buys →
+ * `media_buy_id`, accounts → `account_id`). Mirrors
+ * {@link filterValidSeededProducts} exactly; factored only because the three
+ * shapes share the same single-string-key contract.
+ */
+function filterValidById(raw, idField, callbackName, logger) {
+    if (!Array.isArray(raw)) {
+        logger?.warn(`testController.${callbackName} did not return an array; skipping bridge`, {
+            received: typeof raw,
+        });
+        return [];
+    }
+    const valid = [];
+    raw.forEach((entry, index) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            logger?.warn(`testController.${callbackName} entry is not an object; dropping`, { index });
+            return;
+        }
+        const id = entry[idField];
+        if (typeof id !== 'string' || id.length === 0) {
+            logger?.warn(`testController.${callbackName} entry missing ${idField}; dropping`, { index });
+            return;
+        }
+        valid.push(entry);
+    });
+    return valid;
+}
+/**
+ * Merge seeded creatives into a `list_creatives` response. Existing creatives
+ * come first; seeded entries append after deduping by `creative_id`. On
+ * collision the seeded entry wins. Stamps `sandbox: true` unless the handler
+ * explicitly declared `sandbox: false`. Returns a NEW response object.
+ *
+ * Also updates `query_summary.returned` to match the final array length and
+ * `query_summary.total_matching` to `handler.total_matching + (seeded entries
+ * that did NOT collide with the handler set)`. Storyboards that assert on
+ * counts see the merged totals, not the handler's pre-merge counts. Mirror
+ * field on `pagination.total_count` is updated by the same delta when the
+ * handler set it.
+ */
+function mergeSeededCreativesIntoResponse(response, seeded) {
+    if (!seeded.length)
+        return response;
+    const seededIds = new Set();
+    for (const c of seeded)
+        seededIds.add(c.creative_id);
+    const existing = Array.isArray(response.creatives) ? response.creatives : [];
+    const existingIds = new Set();
+    for (const c of existing) {
+        if (c && typeof c.creative_id === 'string')
+            existingIds.add(c.creative_id);
+    }
+    const retained = existing.filter(c => !seededIds.has(c?.creative_id));
+    const finalCreatives = [...retained, ...seeded];
+    // New entries = seeded that did NOT collide with the handler's set. Collisions
+    // replace in-place; the merged total_matching shouldn't grow on those.
+    let newCount = 0;
+    for (const c of seeded)
+        if (!existingIds.has(c.creative_id))
+            newCount += 1;
+    const merged = {
+        ...response,
+        creatives: finalCreatives,
+    };
+    if (response.sandbox !== false) {
+        merged.sandbox = true;
+    }
+    // query_summary is required on list_creatives per AdCP 3.0.11. Update the
+    // counts if the handler provided them; leave the rest of the block
+    // (filters_applied, etc.) untouched.
+    const qs = response.query_summary;
+    if (qs && typeof qs === 'object') {
+        const baseTotal = typeof qs.total_matching === 'number' ? qs.total_matching : existing.length;
+        merged.query_summary = {
+            ...qs,
+            total_matching: baseTotal + newCount,
+            returned: finalCreatives.length,
+        };
+    }
+    // pagination.total_count is optional; only update when the handler provided it.
+    const pagination = response.pagination;
+    if (pagination && typeof pagination === 'object' && typeof pagination.total_count === 'number') {
+        merged.pagination = {
+            ...pagination,
+            total_count: pagination.total_count + newCount,
+        };
+    }
+    return merged;
+}
+/**
+ * Merge seeded media buys into a `get_media_buys` response. Existing media
+ * buys come first; seeded entries append after deduping by `media_buy_id`.
+ * On collision the seeded entry wins. Returns a NEW response object.
+ *
+ * `get_media_buys` does NOT carry a `query_summary` block (per AdCP 3.0.11);
+ * it exposes its count via `pagination.total_count` (optional). When the
+ * handler set `pagination.total_count`, it's incremented by the count of
+ * new (non-colliding) seeded entries so the merged response stays
+ * internally consistent. Handlers that left `total_count` off pass through
+ * unchanged.
+ */
+function mergeSeededMediaBuysIntoResponse(response, seeded) {
+    if (!seeded.length)
+        return response;
+    const seededIds = new Set();
+    for (const mb of seeded)
+        seededIds.add(mb.media_buy_id);
+    const existing = Array.isArray(response.media_buys) ? response.media_buys : [];
+    const existingIds = new Set();
+    for (const mb of existing) {
+        if (mb && typeof mb.media_buy_id === 'string')
+            existingIds.add(mb.media_buy_id);
+    }
+    const retained = existing.filter(mb => !seededIds.has(mb?.media_buy_id));
+    let newCount = 0;
+    for (const mb of seeded)
+        if (!existingIds.has(mb.media_buy_id))
+            newCount += 1;
+    const merged = {
+        ...response,
+        media_buys: [...retained, ...seeded],
+    };
+    if (response.sandbox !== false) {
+        merged.sandbox = true;
+    }
+    const pagination = response.pagination;
+    if (pagination && typeof pagination === 'object' && typeof pagination.total_count === 'number') {
+        merged.pagination = {
+            ...pagination,
+            total_count: pagination.total_count + newCount,
+        };
+    }
+    return merged;
+}
+/**
+ * Recompute `aggregated_totals` from a merged `media_buy_deliveries` array.
+ *
+ * The wire schema makes `aggregated_totals.impressions` / `spend` /
+ * `media_buy_count` REQUIRED, so once the bridge changes the delivery list it
+ * MUST rewrite the totals — otherwise `media_buy_count` is stale and the
+ * impressions/spend sums no longer reflect the merged set.
+ *
+ * Policy (see VALIDATE-YOUR-AGENT.md "Platform-proxy sellers"):
+ *   - Sum-derived (required): `impressions`, `spend`, `media_buy_count`.
+ *   - Sum-derived (optional): `clicks`, `completed_views`, `views`,
+ *     `conversions`, `conversion_value` — recomputed ONLY when EVERY merged
+ *     delivery populates the field on its `totals`. Otherwise fall back to
+ *     the handler's value (or omit if the handler omitted).
+ *   - Derived ratios: `roas` (`conversion_value / spend`),
+ *     `completion_rate` (`completed_views / impressions`),
+ *     `cost_per_acquisition` (`spend / conversions`). Recomputed ONLY when
+ *     both input fields recomputed AND the divisor is non-zero. Otherwise
+ *     fall back to the handler's value (or omit).
+ *   - Pass-through (not derivable from per-delivery `totals`): `reach`,
+ *     `reach_unit`, `frequency`, `new_to_brand_rate`. The handler's values
+ *     survive verbatim.
+ *
+ * Empty merged array → `{ impressions: 0, spend: 0, media_buy_count: 0 }` +
+ * any pass-through the handler set. Divide-by-zero guards keep ratios omitted
+ * rather than producing `Infinity` / `NaN` values that would fail validation.
+ *
+ * Pure helper — testable in isolation, no I/O.
+ */
+function recomputeAggregatedTotals(deliveries, handlerAggregated) {
+    const totalsList = deliveries.map(d => d.totals);
+    const sumNumber = (key) => {
+        let acc = 0;
+        for (const t of totalsList) {
+            const v = t[key];
+            if (typeof v === 'number')
+                acc += v;
+        }
+        return acc;
+    };
+    const everyHasNumber = (key) => {
+        if (totalsList.length === 0)
+            return false;
+        for (const t of totalsList) {
+            const v = t[key];
+            if (typeof v !== 'number')
+                return false;
+        }
+        return true;
+    };
+    // Required sums: per spec, these fields are REQUIRED on aggregated_totals
+    // when the block exists. Empty merged set → zeros (still wire-correct).
+    const recomputed = {
+        impressions: everyHasNumber('impressions') ? sumNumber('impressions') : 0,
+        spend: everyHasNumber('spend') ? sumNumber('spend') : 0,
+        media_buy_count: deliveries.length,
+    };
+    // Optional sums — only recompute when every delivery populates the field.
+    // Otherwise fall back to the handler's value to avoid wire-incorrect
+    // partial sums.
+    const recomputedFields = new Set();
+    const optionalSumFields = ['clicks', 'completed_views', 'views', 'conversions', 'conversion_value'];
+    for (const field of optionalSumFields) {
+        if (everyHasNumber(field)) {
+            recomputed[field] = sumNumber(field);
+            recomputedFields.add(field);
+        }
+        else {
+            const handlerValue = handlerAggregated ? handlerAggregated[field] : undefined;
+            if (handlerValue !== undefined)
+                recomputed[field] = handlerValue;
+        }
+    }
+    // Also track recomputed status for the required sum fields — needed for the
+    // derived-ratio guards below. `impressions` / `spend` are recomputed when
+    // every delivery populates them; empty merged set counts as "recomputed to 0".
+    if (everyHasNumber('impressions') || deliveries.length === 0)
+        recomputedFields.add('impressions');
+    if (everyHasNumber('spend') || deliveries.length === 0)
+        recomputedFields.add('spend');
+    // Derived ratios — only recompute when BOTH inputs were recomputed AND the
+    // divisor is non-zero. Otherwise fall back to the handler's value (or omit).
+    const tryRatio = (outKey, numerator, denominator) => {
+        if (recomputedFields.has(numerator) && recomputedFields.has(denominator)) {
+            const denom = recomputed[denominator];
+            const num = recomputed[numerator];
+            if (typeof denom === 'number' && denom > 0 && typeof num === 'number') {
+                recomputed[outKey] = num / denom;
+                return;
+            }
+            // Divide-by-zero — omit the ratio (don't fall back; the recomputed
+            // inputs say the ratio is undefined for this set).
+            return;
+        }
+        const handlerValue = handlerAggregated ? handlerAggregated[outKey] : undefined;
+        if (handlerValue !== undefined)
+            recomputed[outKey] = handlerValue;
+    };
+    tryRatio('roas', 'conversion_value', 'spend');
+    tryRatio('completion_rate', 'completed_views', 'impressions');
+    tryRatio('cost_per_acquisition', 'spend', 'conversions');
+    // Pass-through fields — not derivable from per-delivery `totals` (reach
+    // needs de-dup info we don't have; frequency depends on reach; NTB rate
+    // needs an NTB conversion count that isn't carried on per-delivery totals).
+    // Preserve handler's values verbatim.
+    const passThroughFields = ['reach', 'reach_unit', 'frequency', 'new_to_brand_rate'];
+    for (const field of passThroughFields) {
+        const handlerValue = handlerAggregated ? handlerAggregated[field] : undefined;
+        if (handlerValue !== undefined)
+            recomputed[field] = handlerValue;
+    }
+    return recomputed;
+}
+/**
+ * Merge seeded media-buy-delivery entries into a `get_media_buy_delivery`
+ * response. Existing handler entries come first; seeded entries append after
+ * deduping by `media_buy_id`. On collision the SEEDED entry wins, matching the
+ * precedent set by `mergeSeededMediaBuys` / `mergeSeededCreatives` /
+ * `mergeSeededAccounts` — storyboards seed deliberately, so a seeded fixture
+ * for an existing `media_buy_id` is an explicit author override.
+ *
+ * After merging, `aggregated_totals` is recomputed via
+ * {@link recomputeAggregatedTotals} so `media_buy_count` / `impressions` /
+ * `spend` reflect the merged set instead of the handler's pre-merge values.
+ *
+ * Returns a NEW response object — the handler's singleton envelope fields
+ * (`reporting_period`, `currency`, `attribution_window`, `errors`, `sandbox`,
+ * `context`, `ext`, plus webhook-only `notification_type` / `partial_data` /
+ * `sequence_number` / etc.) pass through verbatim. Stamps `sandbox: true`
+ * unless the handler explicitly declared `sandbox: false`.
+ */
+function mergeSeededMediaBuyDeliveryIntoResponse(response, seeded) {
+    if (!seeded.length)
+        return response;
+    const handlerDeliveries = Array.isArray(response.media_buy_deliveries) ? response.media_buy_deliveries : [];
+    const seededIds = new Set();
+    for (const d of seeded)
+        seededIds.add(d.media_buy_id);
+    // Seeded wins on collision: drop handler entries whose `media_buy_id` is in
+    // the seeded set, then append seeded entries. Order mirrors
+    // `mergeSeededMediaBuysIntoResponse` — retained handler entries first,
+    // seeded entries (including overrides) last.
+    const retained = handlerDeliveries.filter(d => !seededIds.has(d?.media_buy_id));
+    const final = [...retained, ...seeded];
+    const merged = {
+        ...response,
+        media_buy_deliveries: final,
+        aggregated_totals: recomputeAggregatedTotals(final, response.aggregated_totals),
+    };
+    if (response.sandbox !== false) {
+        merged.sandbox = true;
+    }
+    return merged;
+}
+/**
+ * Merge seeded accounts into a `list_accounts` response. Existing accounts
+ * come first; seeded entries append after deduping by `account_id`. On
+ * collision the seeded entry wins. Returns a NEW response object.
+ *
+ * `list_accounts` exposes its count via `pagination.total_count` (optional,
+ * same as `get_media_buys`). When the handler set it, it's incremented by
+ * the count of new (non-colliding) seeded entries.
+ */
+function mergeSeededAccountsIntoResponse(response, seeded) {
+    if (!seeded.length)
+        return response;
+    const seededIds = new Set();
+    for (const a of seeded)
+        seededIds.add(a.account_id);
+    const existing = Array.isArray(response.accounts) ? response.accounts : [];
+    const existingIds = new Set();
+    for (const a of existing) {
+        if (a && typeof a.account_id === 'string')
+            existingIds.add(a.account_id);
+    }
+    const retained = existing.filter(a => !seededIds.has(a?.account_id));
+    let newCount = 0;
+    for (const a of seeded)
+        if (!existingIds.has(a.account_id))
+            newCount += 1;
+    const merged = {
+        ...response,
+        accounts: [...retained, ...seeded],
+    };
+    if (response.sandbox !== false) {
+        merged.sandbox = true;
+    }
+    const pagination = response.pagination;
+    if (pagination && typeof pagination === 'object' && typeof pagination.total_count === 'number') {
+        merged.pagination = {
+            ...pagination,
+            total_count: pagination.total_count + newCount,
+        };
+    }
+    return merged;
+}
+/**
+ * Extract `account_id` from a `get_account_financials` request's `account`
+ * reference. `AccountReference` is a discriminated union — the
+ * operator-resolved variant carries `account_id` directly, brand+operator
+ * variants do not. Returns `undefined` for variants that don't carry an
+ * `account_id` (those requests can't match a seeded fixture by id and pass
+ * through to the handler).
+ */
+function readRequestAccountId(req) {
+    const account = req?.account;
+    if (!account || typeof account !== 'object' || Array.isArray(account))
+        return undefined;
+    const id = account.account_id;
+    return typeof id === 'string' && id.length > 0 ? id : undefined;
+}
+/**
+ * Pick a seeded `get_account_financials` fixture matching the request's
+ * account. Unlike the array-collection helpers, this returns the SINGLE
+ * matched envelope or `undefined` — `get_account_financials` is a singleton
+ * response and "merge" reduces to "replace if the request's account matches
+ * a seeded fixture".
+ *
+ * Matching honors both the raw request and the resolved account from
+ * `resolveAccount`. `AccountReference` is a discriminated union — the
+ * operator-resolved variant carries `account_id` on the request, but the
+ * brand+operator variants do not. When the framework has already resolved
+ * the request to an account, prefer that resolved id so seeded fixtures
+ * find their match regardless of which `AccountReference` variant the
+ * buyer sent.
+ *
+ * @param resolvedAccountId - The `account_id` from `ctx.account` after
+ *   `resolveAccount` ran. Pass `undefined` when no account was resolved
+ *   (singleton-tenant adopters) — the function falls back to the request's
+ *   `account.account_id` field, which preserves the original semantics for
+ *   adopters who don't wire `resolveAccount`.
+ */
+function pickSeededAccountFinancialsForRequest(request, seeded, resolvedAccountId) {
+    if (!seeded.length)
+        return undefined;
+    const requestedId = resolvedAccountId ?? readRequestAccountId(request);
+    if (requestedId == null)
+        return undefined;
+    for (const entry of seeded) {
+        const id = entry.account?.account_id;
+        if (typeof id === 'string' && id === requestedId)
+            return entry;
+    }
+    return undefined;
+}
+/**
+ * Replace a `get_account_financials` response when a seeded fixture matches
+ * the request's account. The seeded fixture is authoritative on the
+ * financials payload (spend, period, account, currency, ...). The handler's
+ * `context` and `ext` are framework-managed (`context` echoes
+ * `adcp_version` / `request_id`; `ext` carries adopter passthrough) and
+ * MUST be preserved across the replace — wire-correct context echo is the
+ * framework's responsibility, not the seed fixture's.
+ *
+ * When no fixture matches, returns the handler response unchanged.
+ *
+ * @param resolvedAccountId - Optional resolved `account_id` from
+ *   `ctx.account`; passed through to {@link pickSeededAccountFinancialsForRequest}.
+ */
+function replaceAccountFinancialsIfSeeded(request, response, seeded, resolvedAccountId) {
+    const picked = pickSeededAccountFinancialsForRequest(request, seeded, resolvedAccountId);
+    if (!picked)
+        return response;
+    // Preserve framework-managed envelope fields from the handler response;
+    // seeded fixture owns the financials body. Pull `context` / `ext` off the
+    // handler response (when present) and re-stamp them on top of the seeded
+    // payload — the fixture's own `context` / `ext` (if any) lose to the
+    // handler's, which is correct: a seeded snapshot can't know the current
+    // request's `request_id` / `adcp_version` echo.
+    const handlerContext = response.context;
+    const handlerExt = response.ext;
+    const merged = { ...picked };
+    if (handlerContext !== undefined)
+        merged.context = handlerContext;
+    if (handlerExt !== undefined)
+        merged.ext = handlerExt;
+    return merged;
+}
+/**
+ * Canonical dedup key for a `Format` — `${agent_url}|${id}`. Matches the AdCP
+ * format-id contract: two formats from the same agent with the same id are
+ * the same format, regardless of parameterized dimension / duration. Fixtures
+ * that seed multiple parameterized variants of the same template should use
+ * distinct `id` values per variant.
+ */
+function formatDedupKey(f) {
+    const fid = f.format_id;
+    if (!fid || typeof fid !== 'object')
+        return undefined;
+    const agentUrl = fid.agent_url;
+    const id = fid.id;
+    if (typeof agentUrl !== 'string' || typeof id !== 'string')
+        return undefined;
+    return `${agentUrl}|${id}`;
+}
+/**
+ * Merge seeded creative formats into a `list_creative_formats` response.
+ * Existing formats come first; seeded entries append after deduping by
+ * canonical `${agent_url}|${id}`. On collision the seeded entry wins.
+ * Returns a NEW response object.
+ */
+function mergeSeededCreativeFormatsIntoResponse(response, seeded) {
+    if (!seeded.length)
+        return response;
+    const seededKeys = new Set();
+    for (const f of seeded) {
+        const key = formatDedupKey(f);
+        if (key != null)
+            seededKeys.add(key);
+    }
+    const existing = Array.isArray(response.formats) ? response.formats : [];
+    const retained = existing.filter(f => {
+        const key = formatDedupKey(f);
+        return key == null || !seededKeys.has(key);
+    });
+    const merged = {
+        ...response,
+        formats: [...retained, ...seeded],
+    };
+    if (response.sandbox !== false) {
+        merged.sandbox = true;
+    }
+    return merged;
+}
+// ---------------------------------------------------------------------------
+// Property lists / collection lists / content standards
+//
+// Each entity has a "list" tool (returns `T[]` under a top-level key) AND a
+// "get" tool (returns a singleton). The same seeded fixture array feeds both
+// tools — the list tool merges with seeded-wins on collision; the get tool
+// picks by id and replaces. PropertyList and CollectionList wrap the picked
+// entity into the response's `list` field; ContentStandards' success arm IS
+// the entity directly.
+//
+// All three follow the same dedup contract:
+//   PropertyList     → top-level `list_id` (string, required)
+//   CollectionList   → top-level `list_id` (string, required)
+//   ContentStandards → top-level `standards_id` (string, required)
+// ---------------------------------------------------------------------------
+/**
+ * Validate seeded property-list entries. Drops entries missing a non-empty
+ * string `list_id`.
+ */
+function filterValidSeededPropertyLists(raw, logger) {
+    return filterValidById(raw, 'list_id', 'getSeededPropertyLists', logger);
+}
+/**
+ * Validate seeded collection-list entries. Drops entries missing a non-empty
+ * string `list_id`.
+ */
+function filterValidSeededCollectionLists(raw, logger) {
+    return filterValidById(raw, 'list_id', 'getSeededCollectionLists', logger);
+}
+/**
+ * Validate seeded content-standards entries. Drops entries missing a
+ * non-empty string `standards_id`.
+ */
+function filterValidSeededContentStandards(raw, logger) {
+    return filterValidById(raw, 'standards_id', 'getSeededContentStandards', logger);
+}
+/**
+ * Merge seeded property lists into a `list_property_lists` response.
+ * Existing entries come first; seeded entries append after deduping by
+ * `list_id`. On collision the seeded entry wins. Returns a NEW response
+ * object. When the handler set `pagination.total_count`, it's incremented
+ * by the count of new (non-colliding) seeded entries.
+ *
+ * `list_property_lists` does not carry a `query_summary` block (per AdCP
+ * 3.0.11) — pagination.total_count is the only count field to update.
+ */
+function mergeSeededPropertyListsIntoResponse(response, seeded) {
+    if (!seeded.length)
+        return response;
+    const seededIds = new Set();
+    for (const l of seeded)
+        seededIds.add(l.list_id);
+    const existing = Array.isArray(response.lists) ? response.lists : [];
+    const existingIds = new Set();
+    for (const l of existing) {
+        if (l && typeof l.list_id === 'string')
+            existingIds.add(l.list_id);
+    }
+    const retained = existing.filter(l => !seededIds.has(l?.list_id));
+    let newCount = 0;
+    for (const l of seeded)
+        if (!existingIds.has(l.list_id))
+            newCount += 1;
+    const merged = {
+        ...response,
+        lists: [...retained, ...seeded],
+    };
+    const pagination = response.pagination;
+    if (pagination && typeof pagination === 'object' && typeof pagination.total_count === 'number') {
+        merged.pagination = {
+            ...pagination,
+            total_count: pagination.total_count + newCount,
+        };
+    }
+    return merged;
+}
+/**
+ * Merge seeded collection lists into a `list_collection_lists` response.
+ * Symmetric with {@link mergeSeededPropertyListsIntoResponse} — same dedup
+ * key (`list_id`), same pagination update policy.
+ */
+function mergeSeededCollectionListsIntoResponse(response, seeded) {
+    if (!seeded.length)
+        return response;
+    const seededIds = new Set();
+    for (const l of seeded)
+        seededIds.add(l.list_id);
+    const existing = Array.isArray(response.lists) ? response.lists : [];
+    const existingIds = new Set();
+    for (const l of existing) {
+        if (l && typeof l.list_id === 'string')
+            existingIds.add(l.list_id);
+    }
+    const retained = existing.filter(l => !seededIds.has(l?.list_id));
+    let newCount = 0;
+    for (const l of seeded)
+        if (!existingIds.has(l.list_id))
+            newCount += 1;
+    const merged = {
+        ...response,
+        lists: [...retained, ...seeded],
+    };
+    const pagination = response.pagination;
+    if (pagination && typeof pagination === 'object' && typeof pagination.total_count === 'number') {
+        merged.pagination = {
+            ...pagination,
+            total_count: pagination.total_count + newCount,
+        };
+    }
+    return merged;
+}
+/**
+ * Merge seeded content-standards into a `list_content_standards` response
+ * (success arm). Drops to a no-op if the response is the error arm (no
+ * `standards` array). On `standards_id` collision the seeded entry wins.
+ * Updates `pagination.total_count` when the handler set it. Returns a NEW
+ * response object.
+ */
+function mergeSeededContentStandardsIntoResponse(response, seeded) {
+    if (!seeded.length)
+        return response;
+    // Skip the error arm — the dispatcher already gates on !isErrorResponse,
+    // but the type is a union so we re-narrow defensively.
+    const successArm = response;
+    if (!Array.isArray(successArm.standards))
+        return response;
+    const seededIds = new Set();
+    for (const s of seeded)
+        seededIds.add(s.standards_id);
+    const existing = successArm.standards;
+    const existingIds = new Set();
+    for (const s of existing) {
+        if (s && typeof s.standards_id === 'string')
+            existingIds.add(s.standards_id);
+    }
+    const retained = existing.filter(s => !seededIds.has(s?.standards_id));
+    let newCount = 0;
+    for (const s of seeded)
+        if (!existingIds.has(s.standards_id))
+            newCount += 1;
+    const merged = {
+        ...successArm,
+        standards: [...retained, ...seeded],
+    };
+    const pagination = successArm.pagination;
+    if (pagination && typeof pagination === 'object' && typeof pagination.total_count === 'number') {
+        merged.pagination = {
+            ...pagination,
+            total_count: pagination.total_count + newCount,
+        };
+    }
+    return merged;
+}
+/**
+ * Read the `list_id` from a `get_property_list` request. Required field per
+ * spec; this helper is defensive about runtime input.
+ */
+function readRequestListId(req) {
+    const id = req?.list_id;
+    return typeof id === 'string' && id.length > 0 ? id : undefined;
+}
+/**
+ * Read the `standards_id` from a `get_content_standards` request.
+ */
+function readRequestStandardsId(req) {
+    const id = req?.standards_id;
+    return typeof id === 'string' && id.length > 0 ? id : undefined;
+}
+/**
+ * Pick the seeded property list whose `list_id` matches the request.
+ * Returns `undefined` when nothing matches.
+ */
+function pickSeededPropertyListForRequest(request, seeded) {
+    if (!seeded.length)
+        return undefined;
+    const requestedId = readRequestListId(request);
+    if (requestedId == null)
+        return undefined;
+    for (const entry of seeded) {
+        if (entry.list_id === requestedId)
+            return entry;
+    }
+    return undefined;
+}
+/**
+ * Replace a `get_property_list` response's `list` field with a seeded fixture
+ * when one matches. The handler's auxiliary fields (`identifiers`,
+ * `pagination`, `resolved_at`, `cache_valid_until`, `coverage_gaps`,
+ * `context`, `ext`) pass through verbatim — those depend on request-time
+ * pagination / resolve params that a static fixture can't know. Only `list`
+ * is replaced. When no fixture matches, returns the handler response
+ * unchanged.
+ */
+function replacePropertyListIfSeeded(request, response, seeded) {
+    const picked = pickSeededPropertyListForRequest(request, seeded);
+    if (!picked)
+        return response;
+    return { ...response, list: picked };
+}
+/**
+ * Pick the seeded collection list whose `list_id` matches the request.
+ * Returns `undefined` when nothing matches.
+ */
+function pickSeededCollectionListForRequest(request, seeded) {
+    if (!seeded.length)
+        return undefined;
+    const requestedId = readRequestListId(request);
+    if (requestedId == null)
+        return undefined;
+    for (const entry of seeded) {
+        if (entry.list_id === requestedId)
+            return entry;
+    }
+    return undefined;
+}
+/**
+ * Replace a `get_collection_list` response's `list` field with a seeded
+ * fixture when one matches. Same envelope-preservation policy as
+ * {@link replacePropertyListIfSeeded}.
+ */
+function replaceCollectionListIfSeeded(request, response, seeded) {
+    const picked = pickSeededCollectionListForRequest(request, seeded);
+    if (!picked)
+        return response;
+    return { ...response, list: picked };
+}
+/**
+ * Pick the seeded content-standards entry whose `standards_id` matches the
+ * request. Returns `undefined` when nothing matches.
+ */
+function pickSeededContentStandardsForRequest(request, seeded) {
+    if (!seeded.length)
+        return undefined;
+    const requestedId = readRequestStandardsId(request);
+    if (requestedId == null)
+        return undefined;
+    for (const entry of seeded) {
+        if (entry.standards_id === requestedId)
+            return entry;
+    }
+    return undefined;
+}
+/**
+ * Replace a `get_content_standards` response with a seeded fixture when one
+ * matches. Seeded fixture is authoritative on the `ContentStandards` body.
+ * Framework-managed envelope fields (`context`, `ext`) round-trip from the
+ * handler — matches the precedent set by {@link replaceAccountFinancialsIfSeeded}.
+ *
+ * When no fixture matches, returns the handler response unchanged. The
+ * caller is responsible for skipping the error arm (the dispatcher gates on
+ * `!isErrorResponse`).
+ */
+function replaceContentStandardsIfSeeded(request, response, seeded) {
+    const picked = pickSeededContentStandardsForRequest(request, seeded);
+    if (!picked)
+        return response;
+    // Both context and ext are framework-managed envelope fields.
+    // Seeded fixture is authoritative on the ContentStandards body only.
+    const handlerContext = response.context;
+    const handlerExt = response.ext;
+    const replaced = { ...picked };
+    if (handlerContext !== undefined)
+        replaced.context = handlerContext;
+    if (handlerExt !== undefined)
+        replaced.ext = handlerExt;
+    return replaced;
+}
+// ---------------------------------------------------------------------------
+// Signals / creative delivery / creative features
+//
+// `get_signals` (signal-marketplace + signal-owned)   → list-merge by signal_id
+// `get_creative_delivery` (creative-* delivery)        → list-merge by creative_id, pagination.total update
+// `get_creative_features` (creative-* governance)      → list-merge into success-arm `results` by feature_id
+//
+// All three follow the validate-and-drop / dedupe-and-stamp-sandbox
+// precedent set by the earlier bridges. The features bridge gates on the
+// success arm — error envelopes pass through unchanged.
+// ---------------------------------------------------------------------------
+/**
+ * Canonical dedup key for a `SignalID`. `SignalID` is a discriminated union
+ * (`{source:'catalog', data_provider_domain, id}` vs `{source:'agent',
+ * agent_url, id}`) — two signals with the same `id` from different sources
+ * are distinct, so dedup keys on the full source+origin+id tuple.
+ */
+function signalIdDedupKey(signal) {
+    const sid = signal.signal_id;
+    if (!sid || typeof sid !== 'object' || Array.isArray(sid))
+        return undefined;
+    const source = sid.source;
+    const id = sid.id;
+    if (typeof source !== 'string' || typeof id !== 'string' || id.length === 0)
+        return undefined;
+    if (source === 'catalog') {
+        const origin = sid.data_provider_domain;
+        if (typeof origin !== 'string' || origin.length === 0)
+            return undefined;
+        return `catalog|${origin}|${id}`;
+    }
+    if (source === 'agent') {
+        const origin = sid.agent_url;
+        if (typeof origin !== 'string' || origin.length === 0)
+            return undefined;
+        return `agent|${origin}|${id}`;
+    }
+    return undefined;
+}
+/**
+ * Validate seeded signals. Drops entries whose `signal_id` is not a valid
+ * `SignalID` discriminated-union shape (`{source:'catalog',
+ * data_provider_domain, id}` or `{source:'agent', agent_url, id}`). A missing
+ * or malformed `signal_id` collides on `undefined === undefined` when
+ * deduping, so we drop early.
+ */
+function filterValidSeededSignals(raw, logger) {
+    if (!Array.isArray(raw)) {
+        logger?.warn('testController.getSeededSignals did not return an array; skipping bridge', {
+            received: typeof raw,
+        });
+        return [];
+    }
+    const valid = [];
+    raw.forEach((entry, index) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            logger?.warn('testController.getSeededSignals entry is not an object; dropping', { index });
+            return;
+        }
+        const key = signalIdDedupKey(entry);
+        if (!key) {
+            logger?.warn('testController.getSeededSignals entry has invalid signal_id (expected {source:catalog,data_provider_domain,id} or {source:agent,agent_url,id}); dropping', { index });
+            return;
+        }
+        valid.push(entry);
+    });
+    return valid;
+}
+/**
+ * Validate seeded creative-delivery entries. Drops entries missing a non-empty
+ * string `creative_id`.
+ */
+function filterValidSeededCreativeDelivery(raw, logger) {
+    return filterValidById(raw, 'creative_id', 'getSeededCreativeDelivery', logger);
+}
+/**
+ * Validate seeded creative-feature results. Drops entries missing a non-empty
+ * string `feature_id` (the dedup key against the handler's `results` array).
+ */
+function filterValidSeededCreativeFeatures(raw, logger) {
+    return filterValidById(raw, 'feature_id', 'getSeededCreativeFeatures', logger);
+}
+/**
+ * Merge seeded signals into a `get_signals` response. Existing handler signals
+ * come first; seeded entries append after deduping by `signal_id`. On
+ * collision the seeded entry wins. Stamps `sandbox: true` unless the handler
+ * explicitly declared `sandbox: false`.
+ *
+ * `get_signals` carries `pagination: PaginationResponse` and no `query_summary`.
+ * Pagination is not recomputed on the merge. `PaginationResponse.total_count`
+ * is optional; recomputing it on partial pages would mis-represent the
+ * cross-page total (the handler may have served page 1 of N, and the seeded
+ * fixture sits outside that pagination context). Storyboards asserting on
+ * totals should seed the handler's response, not the post-merge envelope.
+ */
+function mergeSeededSignalsIntoResponse(response, seeded) {
+    if (!seeded.length)
+        return response;
+    const seededKeys = new Set();
+    for (const s of seeded) {
+        const key = signalIdDedupKey(s);
+        if (key)
+            seededKeys.add(key);
+    }
+    const existing = Array.isArray(response.signals) ? response.signals : [];
+    const retained = existing.filter(s => {
+        const key = s ? signalIdDedupKey(s) : undefined;
+        return key == null || !seededKeys.has(key);
+    });
+    const merged = {
+        ...response,
+        signals: [...retained, ...seeded],
+    };
+    if (response.sandbox !== false) {
+        merged.sandbox = true;
+    }
+    return merged;
+}
+/**
+ * Merge seeded creative-delivery entries into a `get_creative_delivery`
+ * response. Existing handler creatives come first; seeded entries append after
+ * deduping by `creative_id`. On collision the seeded entry wins (matches the
+ * precedent set by `mergeSeededMediaBuyDelivery` — storyboards seed
+ * deliberately, so a seeded fixture for an existing id is an explicit author
+ * override).
+ *
+ * `pagination.total` (optional per the AdCP 3.0.11 schema) is incremented by
+ * the count of new non-colliding seeded entries. There is no top-level
+ * aggregated-totals envelope on this response (unlike `get_media_buy_delivery`),
+ * so no further recomputation is performed. Stamps `sandbox: true` unless the
+ * handler explicitly declared `sandbox: false`. Returns a NEW response object.
+ */
+function mergeSeededCreativeDeliveryIntoResponse(response, seeded) {
+    if (!seeded.length)
+        return response;
+    const seededIds = new Set();
+    for (const c of seeded)
+        seededIds.add(c.creative_id);
+    const existing = Array.isArray(response.creatives) ? response.creatives : [];
+    const existingIds = new Set();
+    for (const c of existing) {
+        if (c && typeof c.creative_id === 'string')
+            existingIds.add(c.creative_id);
+    }
+    const retained = existing.filter(c => !seededIds.has(c?.creative_id));
+    let newCount = 0;
+    for (const c of seeded)
+        if (!existingIds.has(c.creative_id))
+            newCount += 1;
+    const merged = {
+        ...response,
+        creatives: [...retained, ...seeded],
+    };
+    if (response.sandbox !== false) {
+        merged.sandbox = true;
+    }
+    // `pagination.total` is the schema-correct field name on
+    // GetCreativeDeliveryResponse (distinct from `pagination.total_count` used
+    // by list_creatives / get_media_buys / list_accounts).
+    const pagination = response.pagination;
+    if (pagination && typeof pagination === 'object' && typeof pagination.total === 'number') {
+        merged.pagination = {
+            ...pagination,
+            total: pagination.total + newCount,
+        };
+    }
+    return merged;
+}
+/**
+ * Merge seeded creative-feature results into a `get_creative_features`
+ * response. The response is a `oneOf` envelope — success arm carries
+ * `results: CreativeFeatureResult[]`, error arm carries `errors: Error[]`.
+ * When the handler returned the error arm, this helper is a no-op; the error
+ * envelope passes through unchanged. When the handler returned the success
+ * arm, seeded results merge into the `results` array (dedup by `feature_id`,
+ * seeded wins on collision).
+ *
+ * Framework-managed envelope fields (`context`, `ext`, `detail_url`,
+ * `pricing_option_id`, `vendor_cost`, `currency`, `consumption`) round-trip
+ * from the handler verbatim — the bridge only augments the per-feature
+ * results array.
+ *
+ * Returns a NEW response object.
+ */
+function mergeSeededCreativeFeaturesIntoResponse(response, seeded) {
+    if (!seeded.length)
+        return response;
+    // Discriminate the success vs error arms. The error arm carries `errors`
+    // and no `results`; the success arm carries `results` (required per spec).
+    const successArm = response;
+    if (!Array.isArray(successArm.results))
+        return response;
+    const seededIds = new Set();
+    for (const r of seeded)
+        seededIds.add(r.feature_id);
+    const existing = successArm.results;
+    const retained = existing.filter(r => !seededIds.has(r?.feature_id));
+    const merged = {
+        ...successArm,
+        results: [...retained, ...seeded],
+    };
+    return merged;
+}
+// ---------------------------------------------------------------------------
+// Brand rights / sponsored intelligence
+//
+// `get_brand_identity` and `si_get_offering` are stateless singleton lookups
+// keyed by a top-level request id; the bridge picks the matching seeded
+// fixture and REPLACES the handler response body, preserving framework-managed
+// `context` / `ext`. `get_rights` is a discovery / search tool with an array
+// response; the bridge appends seeded entries with dedup by `rights_id`,
+// matching the `getSeededProducts` precedent.
+//
+// Mutating siblings (`acquire_rights`, `update_rights`, `si_initiate_session`,
+// `si_send_message`, `si_terminate_session`) are intentionally NOT bridged —
+// seeded read paths only.
+// ---------------------------------------------------------------------------
+/**
+ * Validate seeded brand-identity entries. Drops entries missing a non-empty
+ * string `brand_id`, and warn-drops duplicates (first occurrence wins) since
+ * a fixture array with two entries for the same `brand_id` is almost always
+ * a seed-store bug.
+ */
+function filterValidSeededBrandIdentity(raw, logger) {
+    if (!Array.isArray(raw)) {
+        logger?.warn('testController.getSeededBrandIdentity did not return an array; skipping bridge', {
+            received: typeof raw,
+        });
+        return [];
+    }
+    const valid = [];
+    const seen = new Set();
+    raw.forEach((entry, index) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            logger?.warn('testController.getSeededBrandIdentity entry is not an object; dropping', { index });
+            return;
+        }
+        const brandId = entry.brand_id;
+        if (typeof brandId !== 'string' || brandId.length === 0) {
+            logger?.warn('testController.getSeededBrandIdentity entry missing brand_id; dropping', { index });
+            return;
+        }
+        if (seen.has(brandId)) {
+            logger?.warn('testController.getSeededBrandIdentity duplicate brand_id; dropping (first occurrence wins)', {
+                index,
+                brand_id: brandId,
+            });
+            return;
+        }
+        seen.add(brandId);
+        valid.push(entry);
+    });
+    return valid;
+}
+/**
+ * Validate seeded rights entries. Drops entries missing a non-empty string
+ * `rights_id` (the dedup key against the handler set).
+ */
+function filterValidSeededRights(raw, logger) {
+    return filterValidById(raw, 'rights_id', 'getSeededRights', logger);
+}
+/**
+ * Validate seeded SI offering entries. Each entry must carry a non-empty
+ * string at `offering.offering_id` — that's the field the bridge matches
+ * against `request.offering_id`. Warn-drops duplicates by that key.
+ *
+ * An entry without `offering` (e.g. an `available: false` fixture from a
+ * different storyboard) can't be matched by the bridge and is dropped — a
+ * seeded fixture that can't address a request would be a dead write.
+ */
+function filterValidSeededSiOffering(raw, logger) {
+    if (!Array.isArray(raw)) {
+        logger?.warn('testController.getSeededSiOffering did not return an array; skipping bridge', {
+            received: typeof raw,
+        });
+        return [];
+    }
+    const valid = [];
+    const seen = new Set();
+    raw.forEach((entry, index) => {
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            logger?.warn('testController.getSeededSiOffering entry is not an object; dropping', { index });
+            return;
+        }
+        const offering = entry.offering;
+        const offeringId = offering && typeof offering === 'object' && !Array.isArray(offering)
+            ? offering.offering_id
+            : undefined;
+        if (typeof offeringId !== 'string' || offeringId.length === 0) {
+            logger?.warn('testController.getSeededSiOffering entry missing offering.offering_id; dropping', { index });
+            return;
+        }
+        if (seen.has(offeringId)) {
+            logger?.warn('testController.getSeededSiOffering duplicate offering.offering_id; dropping (first occurrence wins)', { index, offering_id: offeringId });
+            return;
+        }
+        seen.add(offeringId);
+        valid.push(entry);
+    });
+    return valid;
+}
+/**
+ * Merge seeded rights entries into a `get_rights` response (success arm).
+ * Existing entries come first; seeded entries append after deduping by
+ * `rights_id`. On collision the seeded entry wins. Returns a NEW response
+ * object. `get_rights` does not carry `pagination` / `query_summary` blocks
+ * per AdCP 3.0.11 — no count fields to update.
+ *
+ * Drops to a no-op if the response is the error arm (no `rights` array). The
+ * dispatcher gates on `!isErrorResponse` upstream; we re-narrow defensively.
+ */
+function mergeSeededRightsIntoResponse(response, seeded) {
+    if (!seeded.length)
+        return response;
+    const successArm = response;
+    if (!Array.isArray(successArm.rights))
+        return response;
+    const seededIds = new Set();
+    for (const r of seeded)
+        seededIds.add(r.rights_id);
+    const existing = successArm.rights;
+    const retained = existing.filter(r => !seededIds.has(r?.rights_id));
+    return { ...response, rights: [...retained, ...seeded] };
+}
+/**
+ * Read the `brand_id` from a `get_brand_identity` request. Required field per
+ * spec; defensive about runtime input.
+ */
+function readRequestBrandId(req) {
+    const id = req?.brand_id;
+    return typeof id === 'string' && id.length > 0 ? id : undefined;
+}
+/**
+ * Pick the seeded brand-identity entry whose `brand_id` matches the request.
+ * Returns `undefined` when nothing matches.
+ */
+function pickSeededBrandIdentityForRequest(request, seeded) {
+    if (!seeded.length)
+        return undefined;
+    const requestedId = readRequestBrandId(request);
+    if (requestedId == null)
+        return undefined;
+    for (const entry of seeded) {
+        if (entry.brand_id === requestedId)
+            return entry;
+    }
+    return undefined;
+}
+/**
+ * Replace a `get_brand_identity` response with a seeded fixture when one
+ * matches the request's `brand_id`. Seeded fixture is authoritative on the
+ * `GetBrandIdentitySuccess` body. Framework-managed envelope fields
+ * (`context`, `ext`) round-trip from the handler — matches the precedent set
+ * by {@link replaceContentStandardsIfSeeded}.
+ *
+ * When no fixture matches, returns the handler response unchanged. Caller
+ * is responsible for skipping the error arm (the dispatcher gates on
+ * `!isErrorResponse`).
+ */
+function replaceBrandIdentityIfSeeded(request, response, seeded) {
+    const picked = pickSeededBrandIdentityForRequest(request, seeded);
+    if (!picked)
+        return response;
+    const handlerContext = response.context;
+    const handlerExt = response.ext;
+    const replaced = { ...picked };
+    if (handlerContext !== undefined)
+        replaced.context = handlerContext;
+    if (handlerExt !== undefined)
+        replaced.ext = handlerExt;
+    return replaced;
+}
+/**
+ * Read the `offering_id` from an `si_get_offering` request. Required field
+ * per spec; defensive about runtime input.
+ */
+function readRequestOfferingId(req) {
+    const id = req?.offering_id;
+    return typeof id === 'string' && id.length > 0 ? id : undefined;
+}
+/**
+ * Pick the seeded SI offering entry whose `offering.offering_id` matches the
+ * request's `offering_id`. Returns `undefined` when nothing matches.
+ */
+function pickSeededSiOfferingForRequest(request, seeded) {
+    if (!seeded.length)
+        return undefined;
+    const requestedId = readRequestOfferingId(request);
+    if (requestedId == null)
+        return undefined;
+    for (const entry of seeded) {
+        const id = entry.offering?.offering_id;
+        if (typeof id === 'string' && id === requestedId)
+            return entry;
+    }
+    return undefined;
+}
+/**
+ * Replace an `si_get_offering` response with a seeded fixture when one
+ * matches the request's `offering_id`. Seeded fixture is authoritative on
+ * the offering body (`available`, `offering_token`, `offering`, ...);
+ * handler's `context` and `ext` round-trip — same envelope-preservation
+ * policy as {@link replaceBrandIdentityIfSeeded}.
+ *
+ * When no fixture matches, returns the handler response unchanged.
+ *
+ * Note: seeded fixture is authoritative on the entire offering body,
+ * including `offering_token`. The token is intentionally NOT preserved
+ * from the handler — storyboards seed `offering_token` to drive
+ * deterministic session continuation in downstream steps. When/if a
+ * stateful SI session bridge ships (phase 5+; see
+ * adcontextprotocol/adcp-client#1755), the storyboard contract becomes
+ * coupled: seeded `offering_token` here must match the seeded session's
+ * `offering_token`, or `si_initiate_session` will reject as stale-token.
+ */
+function replaceSiOfferingIfSeeded(request, response, seeded) {
+    const picked = pickSeededSiOfferingForRequest(request, seeded);
+    if (!picked)
+        return response;
+    const handlerContext = response.context;
+    const handlerExt = response.ext;
+    const replaced = { ...picked };
+    if (handlerContext !== undefined)
+        replaced.context = handlerContext;
+    if (handlerExt !== undefined)
+        replaced.ext = handlerExt;
+    return replaced;
+}
 /**
  * Bridge the default test-controller store (a `Map<string, unknown>` that
  * holds seeded fixtures by `product_id`, populated by `seed_product` scenarios)
@@ -185,8 +1573,14 @@ function bridgeFromTestControllerStore(store, productDefaults = {}) {
  * ```
  */
 function bridgeFromSessionStore(opts) {
-    const { loadSession, selectSeededProducts, productDefaults = {} } = opts;
-    return {
+    const { loadSession, selectSeededProducts, productDefaults = {}, selectSeededCreatives, selectSeededMediaBuys, selectSeededMediaBuyDelivery, selectSeededAccounts, selectSeededAccountFinancials, selectSeededCreativeFormats, selectSeededPropertyLists, selectSeededContentStandards, selectSeededCollectionLists, selectSeededSignals, selectSeededCreativeDelivery, selectSeededCreativeFeatures, selectSeededBrandIdentity, selectSeededRights, selectSeededSiOffering, } = opts;
+    // Each per-tool callback resolves the session per-request (no memoisation —
+    // same contract as the original `getSeededProducts` path) and awaits the
+    // selector so callers can lazy-load seed collections on the selector path.
+    // Selectors are wired only when the adopter provided them; absent selectors
+    // leave the bridge callback omitted (opt-in by presence on the bridge
+    // interface, same shape as `getSeededProducts`).
+    const bridge = {
         getSeededProducts: async (ctx) => {
             const session = await loadSession(ctx.input);
             const entries = await selectSeededProducts(session);
@@ -203,5 +1597,111 @@ function bridgeFromSessionStore(opts) {
             return out;
         },
     };
+    if (selectSeededCreatives) {
+        bridge.getSeededCreatives = async (ctx) => {
+            const session = await loadSession(ctx.input);
+            const entries = await selectSeededCreatives(session);
+            return entries ? Array.from(entries) : [];
+        };
+    }
+    if (selectSeededMediaBuys) {
+        bridge.getSeededMediaBuys = async (ctx) => {
+            const session = await loadSession(ctx.input);
+            const entries = await selectSeededMediaBuys(session);
+            return entries ? Array.from(entries) : [];
+        };
+    }
+    if (selectSeededMediaBuyDelivery) {
+        bridge.getSeededMediaBuyDelivery = async (ctx) => {
+            const session = await loadSession(ctx.input);
+            const entries = await selectSeededMediaBuyDelivery(session);
+            return entries ? Array.from(entries) : [];
+        };
+    }
+    if (selectSeededAccounts) {
+        bridge.getSeededAccounts = async (ctx) => {
+            const session = await loadSession(ctx.input);
+            const entries = await selectSeededAccounts(session);
+            return entries ? Array.from(entries) : [];
+        };
+    }
+    if (selectSeededAccountFinancials) {
+        bridge.getSeededAccountFinancials = async (ctx) => {
+            const session = await loadSession(ctx.input);
+            const entries = await selectSeededAccountFinancials(session);
+            return entries ? Array.from(entries) : [];
+        };
+    }
+    if (selectSeededCreativeFormats) {
+        bridge.getSeededCreativeFormats = async (ctx) => {
+            const session = await loadSession(ctx.input);
+            const entries = await selectSeededCreativeFormats(session);
+            return entries ? Array.from(entries) : [];
+        };
+    }
+    if (selectSeededPropertyLists) {
+        bridge.getSeededPropertyLists = async (ctx) => {
+            const session = await loadSession(ctx.input);
+            const entries = await selectSeededPropertyLists(session);
+            return entries ? Array.from(entries) : [];
+        };
+    }
+    if (selectSeededContentStandards) {
+        bridge.getSeededContentStandards = async (ctx) => {
+            const session = await loadSession(ctx.input);
+            const entries = await selectSeededContentStandards(session);
+            return entries ? Array.from(entries) : [];
+        };
+    }
+    if (selectSeededCollectionLists) {
+        bridge.getSeededCollectionLists = async (ctx) => {
+            const session = await loadSession(ctx.input);
+            const entries = await selectSeededCollectionLists(session);
+            return entries ? Array.from(entries) : [];
+        };
+    }
+    if (selectSeededSignals) {
+        bridge.getSeededSignals = async (ctx) => {
+            const session = await loadSession(ctx.input);
+            const entries = await selectSeededSignals(session);
+            return entries ? Array.from(entries) : [];
+        };
+    }
+    if (selectSeededCreativeDelivery) {
+        bridge.getSeededCreativeDelivery = async (ctx) => {
+            const session = await loadSession(ctx.input);
+            const entries = await selectSeededCreativeDelivery(session);
+            return entries ? Array.from(entries) : [];
+        };
+    }
+    if (selectSeededCreativeFeatures) {
+        bridge.getSeededCreativeFeatures = async (ctx) => {
+            const session = await loadSession(ctx.input);
+            const entries = await selectSeededCreativeFeatures(session);
+            return entries ? Array.from(entries) : [];
+        };
+    }
+    if (selectSeededBrandIdentity) {
+        bridge.getSeededBrandIdentity = async (ctx) => {
+            const session = await loadSession(ctx.input);
+            const entries = await selectSeededBrandIdentity(session);
+            return entries ? Array.from(entries) : [];
+        };
+    }
+    if (selectSeededRights) {
+        bridge.getSeededRights = async (ctx) => {
+            const session = await loadSession(ctx.input);
+            const entries = await selectSeededRights(session);
+            return entries ? Array.from(entries) : [];
+        };
+    }
+    if (selectSeededSiOffering) {
+        bridge.getSeededSiOffering = async (ctx) => {
+            const session = await loadSession(ctx.input);
+            const entries = await selectSeededSiOffering(session);
+            return entries ? Array.from(entries) : [];
+        };
+    }
+    return bridge;
 }
 //# sourceMappingURL=test-controller-bridge.js.map