@adcp/sdk 5.25.0 → 6.0.0

package/dist/lib/server/ctx-metadata/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/lib/server/ctx-metadata/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,iCAQiB;AAPf,+GAAA,sBAAsB,OAAA;AACtB,6GAAA,oBAAoB,OAAA;AACpB,4GAAA,mBAAmB,OAAA;AACnB,mHAAA,0BAA0B,OAAA;AAC1B,0GAAA,iBAAiB,OAAA;AACjB,gHAAA,uBAAuB,OAAA;AACvB,wGAAA,eAAe,OAAA;AAYjB,4CAA2D;AAAlD,gHAAA,sBAAsB,OAAA;AAG/B,oCAKuB;AAJrB,wGAAA,kBAAkB,OAAA;AAClB,6GAAA,uBAAuB,OAAA;AACvB,+GAAA,yBAAyB,OAAA;AACzB,4GAAA,sBAAsB,OAAA;AAIxB,2CAAgE;AAAvD,8GAAA,gBAAgB,OAAA;AAAE,4GAAA,cAAc,OAAA"}

package/dist/lib/server/ctx-metadata/store.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Ctx-metadata store for AdCP server handlers.
+ *
+ * Publishers attach platform-specific opaque blobs to any returned
+ * resource (product, media_buy, package, creative, audience, signal,
+ * rights_grant). The framework persists the blob keyed by
+ * `(account_id, kind, id)`, strips it from buyer-facing wire payloads,
+ * and threads it back into the publisher's request context on
+ * subsequent calls referencing the same resource ID.
+ *
+ * Use case: GAM ad_unit_ids per product, GAM order_id per media_buy,
+ * line_item_id per package — adapter-internal state the AdCP wire
+ * spec doesn't model. Avoids forcing publishers to re-derive on every
+ * call or maintain a side-cache the SDK could provide.
+ *
+ * Scope is `(account_id, kind, id)` — keys are tenant-isolated. No
+ * auto-eviction by design (a media buy lifetime can be months).
+ * Adopter-driven cleanup via `cleanupExpiredCtxMetadata(db)` for
+ * Postgres deployments that opt into row-level `expires_at`.
+ *
+ * @example
+ * ```ts
+ * import { createCtxMetadataStore, memoryCtxMetadataStore } from '@adcp/sdk/server';
+ *
+ * const store = createCtxMetadataStore({ backend: memoryCtxMetadataStore() });
+ *
+ * createAdcpServerFromPlatform({ platform, ctxMetadata: store });
+ * ```
+ *
+ * @public
+ */
+/**
+ * Resource kinds the ctx-metadata store recognizes. Closed enum:
+ * adding a new kind is a coordinated change across the framework
+ * dispatch (which kinds get hydrated on which request shapes).
+ */
+export type ResourceKind = 'account' | 'product' | 'media_buy' | 'package' | 'creative' | 'audience' | 'signal' | 'rights_grant' | 'property_list' | 'collection_list';
+/**
+ * Default size cap on serialized blob, in bytes. Crossed → `CTX_METADATA_TOO_LARGE`.
+ *
+ * Memory backend without a cap is a single-node DoS vector; Postgres
+ * JSONB performance dies at scale before disk does. 16KB covers the
+ * common case (ad_unit_ids arrays, key-value targeting maps) with
+ * room to spare.
+ */
+export declare const DEFAULT_MAX_VALUE_BYTES: number;
+/**
+ * Maximum allowed TTL in seconds. Crossed → throws at `set()`.
+ *
+ * Lifetime of a media buy can be months, but unbounded retention
+ * compounds drift between SDK cache and publisher truth. 30 days is
+ * the soft ceiling; cleanup is adopter-driven beyond that.
+ */
+export declare const MAX_TTL_SECONDS: number;
+/**
+ * Symbol tag attached to retrieved blobs. Symbols don't survive
+ * `JSON.stringify`, so an accidental serialization in error envelopes
+ * / log lines / agent-card payloads silently elides the blob.
+ * Defense-in-depth against LLM-context leaks.
+ */
+export declare const ADCP_INTERNAL_TAG: unique symbol;
+export interface CtxMetadataEntry {
+    /** Opaque publisher-attached value. Untouched by the framework. */
+    value: unknown;
+    /**
+     * SDK-attached AdCP wire resource shape (e.g., the full `Product` /
+     * `MediaBuy` / `Creative` object minus `ctx_metadata`). Populated by
+     * the framework's auto-hydration path, not by adopter code.
+     *
+     * Used to reconstruct a hydrated resource on subsequent calls that
+     * reference the same id by string. Buyer sends `product_id: 'p1'`;
+     * SDK looks up the entry, builds `{ ...resource, ctx_metadata: value }`,
+     * attaches as `req.packages[i].product`.
+     *
+     * Adopter code never reads or writes this field — the framework owns
+     * it end-to-end.
+     */
+    resource?: unknown;
+    /** Optional unix epoch seconds expiry. Informational; no auto-eviction. */
+    expiresAt?: number;
+}
+/**
+ * Storage backend interface. Swap implementations for memory / Postgres / Redis.
+ *
+ * Keys are flattened to `${accountId}${kind}${id}` before
+ * reaching the backend. Validation runs before flattening — backends
+ * trust their inputs.
+ */
+export interface CtxMetadataBackend {
+    get(scopedKey: string): Promise<CtxMetadataEntry | null>;
+    bulkGet(scopedKeys: readonly string[]): Promise<Map<string, CtxMetadataEntry>>;
+    put(scopedKey: string, entry: CtxMetadataEntry): Promise<void>;
+    delete(scopedKey: string): Promise<void>;
+    /** Optional startup probe. Implementations wrapping an external store should implement. */
+    probe?(): Promise<void>;
+    /** Optional resource-release hook. Called by `store.close()`. */
+    close?(): Promise<void>;
+    /** Optional test-harness flush. Used by `compliance.reset()` between storyboards. */
+    clearAll?(): Promise<void>;
+}
+export interface CtxMetadataStoreConfig {
+    /** Storage backend. Use `memoryCtxMetadataStore()` for dev, `pgCtxMetadataStore(pool)` for cluster. */
+    backend: CtxMetadataBackend;
+    /**
+     * Max serialized blob size in bytes. Defaults to 16384 (16KB).
+     * Crossed → `CTX_METADATA_TOO_LARGE` thrown at `set()`.
+     */
+    maxValueBytes?: number;
+}
+/**
+ * Reference to a stored entry. `bulkGet` accepts an array of these;
+ * the resulting Map is keyed by `${kind}:${id}` for caller convenience.
+ */
+export interface CtxMetadataRef {
+    kind: ResourceKind;
+    id: string;
+}
+export interface CtxMetadataStore {
+    /**
+     * Look up a single entry. Returns `undefined` (not `null`) for misses
+     * so publishers can branch with `??` against their own DB.
+     *
+     * Returned values carry a non-enumerable `[ADCP_INTERNAL_TAG]: true`
+     * marker — JSON serialization elides it automatically (defense
+     * against accidental leak via error envelopes and log lines).
+     */
+    get(accountId: string, kind: ResourceKind, id: string): Promise<unknown | undefined>;
+    /**
+     * Bulk lookup. Returns a Map keyed by `${kind}:${id}` so callers
+     * with mixed-kind refs (e.g., `create_media_buy` carrying products
+     * + an audience ref) can index without remembering what they asked for.
+     * Misses are absent from the Map (no `undefined` entries).
+     */
+    bulkGet(accountId: string, refs: readonly CtxMetadataRef[]): Promise<ReadonlyMap<string, unknown>>;
+    /**
+     * Store a blob. Throws `CTX_METADATA_TOO_LARGE` if `JSON.stringify(value).length`
+     * exceeds the configured cap. Throws `INVALID_ARGUMENT` for null/undefined/empty
+     * `accountId` or out-of-shape `id`.
+     *
+     * `ttlSeconds` is optional and capped at 30 days. No auto-eviction.
+     */
+    set(accountId: string, kind: ResourceKind, id: string, value: unknown, ttlSeconds?: number): Promise<void>;
+    /** Delete a single entry. Tenant-scoped via `accountId`. */
+    delete(accountId: string, kind: ResourceKind, id: string): Promise<void>;
+    /** Probe the backend for boot-time readiness. */
+    probe(): Promise<void>;
+    /** Release backend resources (close pools, clear timers). */
+    close(): Promise<void>;
+    /** Test-harness reset. Throws if backend doesn't support it (no `force` opt — production safety). */
+    clearAll(): Promise<void>;
+}
+/**
+ * Validation error thrown for bad input shape. Distinct from
+ * `CTX_METADATA_TOO_LARGE` (size violation) so callers can branch.
+ */
+export declare class CtxMetadataValidationError extends Error {
+    readonly code: 'INVALID_ARGUMENT' | 'CTX_METADATA_TOO_LARGE';
+    constructor(code: 'INVALID_ARGUMENT' | 'CTX_METADATA_TOO_LARGE', message: string);
+}
+/**
+ * Compose the flattened storage key. Internal — backends trust this format.
+ */
+export declare function scopeCtxMetadataKey(accountId: string, kind: ResourceKind, id: string): string;
+/**
+ * Compose the bulkGet result key. External — callers index Map entries by this.
+ */
+export declare function ctxMetadataResultKey(kind: ResourceKind, id: string): string;
+/**
+ * Build a CtxMetadataStore wrapping a backend.
+ *
+ * Memory backend is fine for single-process dev. Cluster deployments
+ * MUST use `pgCtxMetadataStore` — silent ctx_metadata loss after a
+ * rolling restart produces "package not found" errors that look like
+ * publisher bugs and run for weeks.
+ */
+export declare function createCtxMetadataStore(config: CtxMetadataStoreConfig): CtxMetadataStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/lib/server/ctx-metadata/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/ctx-metadata/store.ts"],"names":[],"mappings":"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"}

package/dist/lib/server/ctx-metadata/store.js

@@ -0,0 +1,327 @@
+"use strict";
+/**
+ * Ctx-metadata store for AdCP server handlers.
+ *
+ * Publishers attach platform-specific opaque blobs to any returned
+ * resource (product, media_buy, package, creative, audience, signal,
+ * rights_grant). The framework persists the blob keyed by
+ * `(account_id, kind, id)`, strips it from buyer-facing wire payloads,
+ * and threads it back into the publisher's request context on
+ * subsequent calls referencing the same resource ID.
+ *
+ * Use case: GAM ad_unit_ids per product, GAM order_id per media_buy,
+ * line_item_id per package — adapter-internal state the AdCP wire
+ * spec doesn't model. Avoids forcing publishers to re-derive on every
+ * call or maintain a side-cache the SDK could provide.
+ *
+ * Scope is `(account_id, kind, id)` — keys are tenant-isolated. No
+ * auto-eviction by design (a media buy lifetime can be months).
+ * Adopter-driven cleanup via `cleanupExpiredCtxMetadata(db)` for
+ * Postgres deployments that opt into row-level `expires_at`.
+ *
+ * @example
+ * ```ts
+ * import { createCtxMetadataStore, memoryCtxMetadataStore } from '@adcp/sdk/server';
+ *
+ * const store = createCtxMetadataStore({ backend: memoryCtxMetadataStore() });
+ *
+ * createAdcpServerFromPlatform({ platform, ctxMetadata: store });
+ * ```
+ *
+ * @public
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CtxMetadataValidationError = exports.ADCP_INTERNAL_TAG = exports.MAX_TTL_SECONDS = exports.DEFAULT_MAX_VALUE_BYTES = void 0;
+exports.scopeCtxMetadataKey = scopeCtxMetadataKey;
+exports.ctxMetadataResultKey = ctxMetadataResultKey;
+exports.createCtxMetadataStore = createCtxMetadataStore;
+const ALL_RESOURCE_KINDS = [
+    'account',
+    'product',
+    'media_buy',
+    'package',
+    'creative',
+    'audience',
+    'signal',
+    'rights_grant',
+    'property_list',
+    'collection_list',
+];
+/**
+ * Default size cap on serialized blob, in bytes. Crossed → `CTX_METADATA_TOO_LARGE`.
+ *
+ * Memory backend without a cap is a single-node DoS vector; Postgres
+ * JSONB performance dies at scale before disk does. 16KB covers the
+ * common case (ad_unit_ids arrays, key-value targeting maps) with
+ * room to spare.
+ */
+exports.DEFAULT_MAX_VALUE_BYTES = 16 * 1024;
+/**
+ * Maximum allowed TTL in seconds. Crossed → throws at `set()`.
+ *
+ * Lifetime of a media buy can be months, but unbounded retention
+ * compounds drift between SDK cache and publisher truth. 30 days is
+ * the soft ceiling; cleanup is adopter-driven beyond that.
+ */
+exports.MAX_TTL_SECONDS = 30 * 24 * 60 * 60;
+/**
+ * Account ID and resource ID shape allowlist. Excludes the U+001F
+ * separator used in the flattened storage key, NUL bytes that
+ * Postgres TEXT rejects, and anything else that could confuse the
+ * key parser.
+ */
+const VALID_KEY_SEGMENT = /^[A-Za-z0-9_.:\-]{1,255}$/;
+/**
+ * Symbol tag attached to retrieved blobs. Symbols don't survive
+ * `JSON.stringify`, so an accidental serialization in error envelopes
+ * / log lines / agent-card payloads silently elides the blob.
+ * Defense-in-depth against LLM-context leaks.
+ */
+exports.ADCP_INTERNAL_TAG = Symbol.for('adcp.ctx_metadata.internal');
+/**
+ * Validation error thrown for bad input shape. Distinct from
+ * `CTX_METADATA_TOO_LARGE` (size violation) so callers can branch.
+ */
+class CtxMetadataValidationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'CtxMetadataValidationError';
+    }
+}
+exports.CtxMetadataValidationError = CtxMetadataValidationError;
+/**
+ * Compose the flattened storage key. Internal — backends trust this format.
+ */
+function scopeCtxMetadataKey(accountId, kind, id) {
+    return `${accountId}${kind}${id}`;
+}
+/**
+ * Compose the bulkGet result key. External — callers index Map entries by this.
+ */
+function ctxMetadataResultKey(kind, id) {
+    return `${kind}:${id}`;
+}
+function validateAccountId(accountId) {
+    if (accountId == null || accountId === '') {
+        throw new CtxMetadataValidationError('INVALID_ARGUMENT', 'ctx_metadata requires an account scope. No-account tools (provide_performance_feedback, ' +
+            'list_creative_formats) cannot use ctx_metadata.');
+    }
+    if (!VALID_KEY_SEGMENT.test(accountId)) {
+        throw new CtxMetadataValidationError('INVALID_ARGUMENT', `Invalid accountId shape: must match ${VALID_KEY_SEGMENT}`);
+    }
+}
+function validateResourceId(id) {
+    if (id == null || id === '') {
+        throw new CtxMetadataValidationError('INVALID_ARGUMENT', 'ctx_metadata resource id must be non-empty');
+    }
+    if (!VALID_KEY_SEGMENT.test(id)) {
+        throw new CtxMetadataValidationError('INVALID_ARGUMENT', `Invalid resource id shape: must match ${VALID_KEY_SEGMENT}`);
+    }
+}
+function validateResourceKind(kind) {
+    if (!ALL_RESOURCE_KINDS.includes(kind)) {
+        throw new CtxMetadataValidationError('INVALID_ARGUMENT', `Unknown ctx_metadata resource kind: ${kind}`);
+    }
+}
+function tagInternal(value) {
+    if (value == null || typeof value !== 'object')
+        return value;
+    Object.defineProperty(value, exports.ADCP_INTERNAL_TAG, {
+        value: true,
+        enumerable: false,
+        writable: false,
+        configurable: false,
+    });
+    return value;
+}
+/**
+ * Build a CtxMetadataStore wrapping a backend.
+ *
+ * Memory backend is fine for single-process dev. Cluster deployments
+ * MUST use `pgCtxMetadataStore` — silent ctx_metadata loss after a
+ * rolling restart produces "package not found" errors that look like
+ * publisher bugs and run for weeks.
+ */
+function createCtxMetadataStore(config) {
+    const backend = config.backend;
+    const maxValueBytes = config.maxValueBytes ?? exports.DEFAULT_MAX_VALUE_BYTES;
+    return {
+        async get(accountId, kind, id) {
+            validateAccountId(accountId);
+            validateResourceKind(kind);
+            validateResourceId(id);
+            const entry = await backend.get(scopeCtxMetadataKey(accountId, kind, id));
+            if (!entry)
+                return undefined;
+            if (entry.expiresAt != null && entry.expiresAt < Math.floor(Date.now() / 1000)) {
+                return undefined;
+            }
+            return tagInternal(entry.value);
+        },
+        async bulkGet(accountId, refs) {
+            validateAccountId(accountId);
+            if (refs.length === 0)
+                return new Map();
+            const scopedKeys = [];
+            const scopedToResultKey = new Map();
+            for (const ref of refs) {
+                validateResourceKind(ref.kind);
+                validateResourceId(ref.id);
+                const scoped = scopeCtxMetadataKey(accountId, ref.kind, ref.id);
+                scopedKeys.push(scoped);
+                scopedToResultKey.set(scoped, ctxMetadataResultKey(ref.kind, ref.id));
+            }
+            const entries = await backend.bulkGet(scopedKeys);
+            const result = new Map();
+            const nowSeconds = Math.floor(Date.now() / 1000);
+            for (const [scopedKey, entry] of entries) {
+                if (entry.expiresAt != null && entry.expiresAt < nowSeconds)
+                    continue;
+                const resultKey = scopedToResultKey.get(scopedKey);
+                if (resultKey != null)
+                    result.set(resultKey, tagInternal(entry.value));
+            }
+            return result;
+        },
+        async set(accountId, kind, id, value, ttlSeconds) {
+            validateAccountId(accountId);
+            validateResourceKind(kind);
+            validateResourceId(id);
+            if (ttlSeconds != null) {
+                if (!Number.isFinite(ttlSeconds) || ttlSeconds <= 0) {
+                    throw new CtxMetadataValidationError('INVALID_ARGUMENT', 'ttlSeconds must be a positive finite number');
+                }
+                if (ttlSeconds > exports.MAX_TTL_SECONDS) {
+                    throw new CtxMetadataValidationError('INVALID_ARGUMENT', `ttlSeconds exceeds the 30-day maximum (${exports.MAX_TTL_SECONDS}s)`);
+                }
+            }
+            const serialized = JSON.stringify(value);
+            if (serialized == null) {
+                throw new CtxMetadataValidationError('INVALID_ARGUMENT', 'ctx_metadata value must be JSON-serializable (got undefined / function / symbol)');
+            }
+            const byteLen = Buffer.byteLength(serialized, 'utf8');
+            if (byteLen > maxValueBytes) {
+                throw new CtxMetadataValidationError('CTX_METADATA_TOO_LARGE', `ctx_metadata blob is ${byteLen} bytes, exceeds the configured cap of ${maxValueBytes} bytes ` +
+                    `for ${kind}:${id}. Offload large payloads to your own storage and reference by ID.`);
+            }
+            const expiresAt = ttlSeconds != null ? Math.floor(Date.now() / 1000) + ttlSeconds : undefined;
+            // Preserve any prior `resource` from the framework-managed entry —
+            // adopter `set()` only mutates `value`. The dispatch seam writes
+            // resource via `setEntry`.
+            const prior = await backend.get(scopeCtxMetadataKey(accountId, kind, id));
+            const next = {
+                value,
+                ...(prior?.resource !== undefined && { resource: prior.resource }),
+                ...(expiresAt !== undefined
+                    ? { expiresAt }
+                    : prior?.expiresAt !== undefined
+                        ? { expiresAt: prior.expiresAt }
+                        : {}),
+            };
+            await backend.put(scopeCtxMetadataKey(accountId, kind, id), next);
+        },
+        async setEntry(accountId, kind, id, entry) {
+            validateAccountId(accountId);
+            validateResourceKind(kind);
+            validateResourceId(id);
+            // Cap applied to the COMBINED serialization (value + resource) since
+            // both round-trip together. Use the same upstream message so adopters
+            // see the same diagnostic surface.
+            const serialized = JSON.stringify({ value: entry.value, resource: entry.resource });
+            const byteLen = Buffer.byteLength(serialized, 'utf8');
+            if (byteLen > maxValueBytes) {
+                throw new CtxMetadataValidationError('CTX_METADATA_TOO_LARGE', `ctx_metadata combined blob is ${byteLen} bytes, exceeds the configured cap of ${maxValueBytes} bytes ` +
+                    `for ${kind}:${id}. Offload large payloads to your own storage and reference by ID.`);
+            }
+            await backend.put(scopeCtxMetadataKey(accountId, kind, id), entry);
+        },
+        async setResource(accountId, kind, id, resource, publisherCtxMetadata) {
+            validateAccountId(accountId);
+            validateResourceKind(kind);
+            validateResourceId(id);
+            const scopedKey = scopeCtxMetadataKey(accountId, kind, id);
+            const prior = await backend.get(scopedKey);
+            // Resolve the value to persist:
+            //   - publisher returned ctx_metadata on the wire shape → use it (overrides prior)
+            //   - publisher omitted ctx_metadata → preserve prior value (don't clobber)
+            //   - no prior, no publisher value → store null
+            const nextValue = publisherCtxMetadata !== undefined && publisherCtxMetadata !== null
+                ? publisherCtxMetadata
+                : (prior?.value ?? null);
+            const nextEntry = {
+                value: nextValue,
+                resource,
+                ...(prior?.expiresAt !== undefined && { expiresAt: prior.expiresAt }),
+            };
+            // Apply the same size cap used by setEntry.
+            const serialized = JSON.stringify({ value: nextEntry.value, resource: nextEntry.resource });
+            const byteLen = Buffer.byteLength(serialized, 'utf8');
+            if (byteLen > maxValueBytes) {
+                throw new CtxMetadataValidationError('CTX_METADATA_TOO_LARGE', `ctx_metadata combined blob is ${byteLen} bytes, exceeds the configured cap of ${maxValueBytes} bytes ` +
+                    `for ${kind}:${id}. Offload large payloads to your own storage and reference by ID.`);
+            }
+            await backend.put(scopedKey, nextEntry);
+        },
+        async getEntry(accountId, kind, id) {
+            validateAccountId(accountId);
+            validateResourceKind(kind);
+            validateResourceId(id);
+            const entry = await backend.get(scopeCtxMetadataKey(accountId, kind, id));
+            if (!entry)
+                return undefined;
+            if (entry.expiresAt != null && entry.expiresAt < Math.floor(Date.now() / 1000)) {
+                return undefined;
+            }
+            return entry;
+        },
+        async bulkGetEntries(accountId, refs) {
+            validateAccountId(accountId);
+            if (refs.length === 0)
+                return new Map();
+            const scopedKeys = [];
+            const scopedToResultKey = new Map();
+            for (const ref of refs) {
+                validateResourceKind(ref.kind);
+                validateResourceId(ref.id);
+                const scoped = scopeCtxMetadataKey(accountId, ref.kind, ref.id);
+                scopedKeys.push(scoped);
+                scopedToResultKey.set(scoped, ctxMetadataResultKey(ref.kind, ref.id));
+            }
+            const entries = await backend.bulkGet(scopedKeys);
+            const result = new Map();
+            const nowSeconds = Math.floor(Date.now() / 1000);
+            for (const [scopedKey, entry] of entries) {
+                if (entry.expiresAt != null && entry.expiresAt < nowSeconds)
+                    continue;
+                const resultKey = scopedToResultKey.get(scopedKey);
+                if (resultKey != null)
+                    result.set(resultKey, entry);
+            }
+            return result;
+        },
+        async delete(accountId, kind, id) {
+            validateAccountId(accountId);
+            validateResourceKind(kind);
+            validateResourceId(id);
+            await backend.delete(scopeCtxMetadataKey(accountId, kind, id));
+        },
+        async probe() {
+            if (backend.probe)
+                await backend.probe();
+        },
+        async close() {
+            if (backend.close)
+                await backend.close();
+        },
+        async clearAll() {
+            if (!backend.clearAll) {
+                throw new Error('ctx_metadata backend does not support clearAll(). ' +
+                    'Production backends (e.g., shared Postgres) should refuse this; use memory backend for tests.');
+            }
+            await backend.clearAll();
+        },
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/lib/server/ctx-metadata/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../../src/lib/server/ctx-metadata/store.ts"],"names":[],"mappings":"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"}

package/dist/lib/server/ctx-metadata/wire-shape.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Compile-time + runtime defense against `ctx_metadata` leaking into
+ * buyer-facing wire payloads.
+ *
+ * - **Compile-time:** `WireShape<T>` strips `ctx_metadata` from a type
+ *   tree, so the framework's response builder return types refuse a
+ *   payload that carries it.
+ * - **Runtime:** `stripCtxMetadata(value)` shape-aware shallow walk
+ *   over known carrier locations (response root + `packages[]` +
+ *   `creatives[]` + `audiences[]` + `signals[]` + `media_buys[]` +
+ *   `products[]`). Catches custom-handler escape hatches and HITL
+ *   task return values that re-introduce the field at runtime.
+ *
+ * Single chokepoint at the dispatcher seam. Strip runs *before* the
+ * idempotency cache write so cached replays don't leak.
+ *
+ * @public
+ */
+/**
+ * Compile-time strip: recursively remove `ctx_metadata` from a type
+ * tree. Used as the framework's response-boundary type so a publisher
+ * payload that carries the field fails type-checking before it
+ * reaches the wire.
+ *
+ * Strips `ctx_metadata` at top level, inside arrays, and inside
+ * objects nested under `packages` / `creatives` / `audiences` /
+ * `signals` / `media_buys` / `products` — the carrier shapes the
+ * AdCP 3.0 wire spec defines. Other shapes pass through unchanged
+ * (the runtime walk is deliberately not recursive everywhere — see
+ * the docstring).
+ */
+export type WireShape<T> = T extends ReadonlyArray<infer U> ? ReadonlyArray<WireShape<U>> : T extends object ? {
+    [K in keyof T as K extends 'ctx_metadata' ? never : K]: WireShape<T[K]>;
+} : T;
+/**
+ * Runtime strip. Walks known carrier shapes in the response and
+ * deletes `ctx_metadata` keys. Returns the input value (mutates in
+ * place — the dispatcher constructs a fresh response per call, so
+ * mutation is safe).
+ *
+ * **Why shape-aware shallow walk, not full recursion.** Full
+ * recursion is O(response size) and risks stripping a field a
+ * future spec adds with the same name elsewhere (e.g., a diagnostic
+ * envelope's `ctx_metadata`). Shape-aware walks the carrier
+ * locations defined by AdCP 3.0 — adding a new carrier requires
+ * updating this list, which is the right kind of friction.
+ */
+export declare function stripCtxMetadata<T>(value: T): WireShape<T>;
+/**
+ * Detect whether a payload contains `ctx_metadata` at any walked
+ * carrier location. Used by the test suite to assert wire payloads
+ * are clean — production code paths just call `stripCtxMetadata`.
+ */
+export declare function hasCtxMetadata(value: unknown): boolean;
+//# sourceMappingURL=wire-shape.d.ts.map

package/dist/lib/server/ctx-metadata/wire-shape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-shape.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/ctx-metadata/wire-shape.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IACrB,CAAC,SAAS,aAAa,CAAC,MAAM,CAAC,CAAC,GAC5B,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,GAC3B,CAAC,SAAS,MAAM,GACd;KAAG,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,cAAc,GAAG,KAAK,GAAG,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GAC3E,CAAC,CAAC;AAEV;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAI1D;AA+CD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGtD"}