@adcp/sdk 5.25.1 → 6.0.0

package/dist/lib/server/decisioning/runtime/protocol-for-tool.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * Tool-name → AdCP protocol category mapping.
+ *
+ * Goes on the webhook payload's `protocol` field (per `enums/adcp-protocol.json`)
+ * and on the `tasks_get` lifecycle response so receivers can route to the
+ * right pipeline before parsing the task body.
+ *
+ * The map is exported as a plain `Record<string, AdcpProtocol>` so adopters
+ * with framework-extension code paths can introspect it (e.g., to build
+ * per-protocol metric emitters).
+ *
+ * @public
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPEC_WEBHOOK_TASK_TYPES = exports.TOOL_PROTOCOL_MAP = void 0;
+exports.protocolForTool = protocolForTool;
+/**
+ * Tool-name → protocol lookup. Keys are wire tool names (snake_case). Values
+ * are the 6 closed-enum protocol categories from `enums/adcp-protocol.json`.
+ *
+ * Tools not in this map fall through to `'media-buy'` — sales is the
+ * largest specialism and the safest default for unknown tools (anything
+ * the framework dispatches but isn't catalogued here is most likely a new
+ * sales tool added in a downstream release).
+ */
+exports.TOOL_PROTOCOL_MAP = {
+    // sponsored-intelligence
+    si_initiate_session: 'sponsored-intelligence',
+    si_send_message: 'sponsored-intelligence',
+    si_end_session: 'sponsored-intelligence',
+    si_get_session: 'sponsored-intelligence',
+    // governance
+    check_governance: 'governance',
+    sync_plans: 'governance',
+    report_plan_outcome: 'governance',
+    get_plan_audit_logs: 'governance',
+    get_media_buy_artifacts: 'governance',
+    calibrate_content: 'governance',
+    validate_content_delivery: 'governance',
+    create_property_list: 'governance',
+    update_property_list: 'governance',
+    get_property_list: 'governance',
+    list_property_lists: 'governance',
+    delete_property_list: 'governance',
+    create_collection_list: 'governance',
+    update_collection_list: 'governance',
+    get_collection_list: 'governance',
+    list_collection_lists: 'governance',
+    delete_collection_list: 'governance',
+    create_content_standards: 'governance',
+    update_content_standards: 'governance',
+    get_content_standards: 'governance',
+    // signals
+    get_signals: 'signals',
+    activate_signal: 'signals',
+    // creative
+    build_creative: 'creative',
+    preview_creative: 'creative',
+    get_creative_delivery: 'creative',
+    list_creative_formats: 'creative',
+    list_creatives: 'creative',
+    sync_creatives: 'creative',
+    // brand
+    get_brand_identity: 'brand',
+    get_rights: 'brand',
+    acquire_rights: 'brand',
+    // media-buy (explicit listing — anything not here falls back to media-buy)
+    get_products: 'media-buy',
+    create_media_buy: 'media-buy',
+    update_media_buy: 'media-buy',
+    get_media_buy_delivery: 'media-buy',
+    sync_audiences: 'media-buy',
+    sync_accounts: 'media-buy',
+    list_accounts: 'media-buy',
+    get_account_financials: 'media-buy',
+    report_usage: 'media-buy',
+    log_event: 'media-buy',
+    sync_event_sources: 'media-buy',
+    sync_catalogs: 'media-buy',
+    provide_performance_feedback: 'media-buy',
+    get_media_buys: 'media-buy',
+};
+/**
+ * Map a v6 tool name to its AdCP protocol category. Falls back to
+ * `'media-buy'` for unknown tools — see `TOOL_PROTOCOL_MAP` JSDoc.
+ */
+function protocolForTool(tool) {
+    return exports.TOOL_PROTOCOL_MAP[tool] ?? 'media-buy';
+}
+/**
+ * Tools whose `task_type` value is permitted in the v6.0 webhook payload
+ * envelope. Spec `enums/task-type.json` is a closed 20-value enum at AdCP
+ * 3.0 GA — receivers validate against it. Tools NOT in this set still
+ * dispatch fine but the framework MUST NOT emit a webhook with a
+ * non-spec `task_type` value (it would be rejected by spec-validating
+ * subscribers).
+ *
+ * Tracking spec issue to widen the enum: filing as `adcontextprotocol/adcp`
+ * follow-up. Until that lands the framework gates webhook delivery to
+ * spec-listed tools and uses `publishStatusChange` for the rest.
+ *
+ * @internal
+ */
+exports.SPEC_WEBHOOK_TASK_TYPES = new Set([
+    'create_media_buy',
+    'update_media_buy',
+    'sync_creatives',
+    'activate_signal',
+    'get_signals',
+    'create_property_list',
+    'update_property_list',
+    'get_property_list',
+    'list_property_lists',
+    'delete_property_list',
+    'sync_accounts',
+    'get_account_financials',
+    'get_creative_delivery',
+    'sync_event_sources',
+    'sync_audiences',
+    'sync_catalogs',
+    'log_event',
+    'get_brand_identity',
+    'get_rights',
+    'acquire_rights',
+]);
+//# sourceMappingURL=protocol-for-tool.js.map

package/dist/lib/server/decisioning/runtime/protocol-for-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-for-tool.js","sourceRoot":"","sources":["../../../../../src/lib/server/decisioning/runtime/protocol-for-tool.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAkFH,0CAEC;AA9ED;;;;;;;;GAQG;AACU,QAAA,iBAAiB,GAA2C;IACvE,yBAAyB;IACzB,mBAAmB,EAAE,wBAAwB;IAC7C,eAAe,EAAE,wBAAwB;IACzC,cAAc,EAAE,wBAAwB;IACxC,cAAc,EAAE,wBAAwB;IAExC,aAAa;IACb,gBAAgB,EAAE,YAAY;IAC9B,UAAU,EAAE,YAAY;IACxB,mBAAmB,EAAE,YAAY;IACjC,mBAAmB,EAAE,YAAY;IACjC,uBAAuB,EAAE,YAAY;IACrC,iBAAiB,EAAE,YAAY;IAC/B,yBAAyB,EAAE,YAAY;IACvC,oBAAoB,EAAE,YAAY;IAClC,oBAAoB,EAAE,YAAY;IAClC,iBAAiB,EAAE,YAAY;IAC/B,mBAAmB,EAAE,YAAY;IACjC,oBAAoB,EAAE,YAAY;IAClC,sBAAsB,EAAE,YAAY;IACpC,sBAAsB,EAAE,YAAY;IACpC,mBAAmB,EAAE,YAAY;IACjC,qBAAqB,EAAE,YAAY;IACnC,sBAAsB,EAAE,YAAY;IACpC,wBAAwB,EAAE,YAAY;IACtC,wBAAwB,EAAE,YAAY;IACtC,qBAAqB,EAAE,YAAY;IAEnC,UAAU;IACV,WAAW,EAAE,SAAS;IACtB,eAAe,EAAE,SAAS;IAE1B,WAAW;IACX,cAAc,EAAE,UAAU;IAC1B,gBAAgB,EAAE,UAAU;IAC5B,qBAAqB,EAAE,UAAU;IACjC,qBAAqB,EAAE,UAAU;IACjC,cAAc,EAAE,UAAU;IAC1B,cAAc,EAAE,UAAU;IAE1B,QAAQ;IACR,kBAAkB,EAAE,OAAO;IAC3B,UAAU,EAAE,OAAO;IACnB,cAAc,EAAE,OAAO;IAEvB,2EAA2E;IAC3E,YAAY,EAAE,WAAW;IACzB,gBAAgB,EAAE,WAAW;IAC7B,gBAAgB,EAAE,WAAW;IAC7B,sBAAsB,EAAE,WAAW;IACnC,cAAc,EAAE,WAAW;IAC3B,aAAa,EAAE,WAAW;IAC1B,aAAa,EAAE,WAAW;IAC1B,sBAAsB,EAAE,WAAW;IACnC,YAAY,EAAE,WAAW;IACzB,SAAS,EAAE,WAAW;IACtB,kBAAkB,EAAE,WAAW;IAC/B,aAAa,EAAE,WAAW;IAC1B,4BAA4B,EAAE,WAAW;IACzC,cAAc,EAAE,WAAW;CAC5B,CAAC;AAEF;;;GAGG;AACH,SAAgB,eAAe,CAAC,IAAY;IAC1C,OAAO,yBAAiB,CAAC,IAAI,CAAC,IAAI,WAAW,CAAC;AAChD,CAAC;AAED;;;;;;;;;;;;;GAaG;AACU,QAAA,uBAAuB,GAAwB,IAAI,GAAG,CAAC;IAClE,kBAAkB;IAClB,kBAAkB;IAClB,gBAAgB;IAChB,iBAAiB;IACjB,aAAa;IACb,sBAAsB;IACtB,sBAAsB;IACtB,mBAAmB;IACnB,qBAAqB;IACrB,sBAAsB;IACtB,eAAe;IACf,wBAAwB;IACxB,uBAAuB;IACvB,oBAAoB;IACpB,gBAAgB;IAChB,eAAe;IACf,WAAW;IACX,oBAAoB;IACpB,YAAY;IACZ,gBAAgB;CACjB,CAAC,CAAC"}

package/dist/lib/server/decisioning/runtime/task-registry.d.ts

@@ -0,0 +1,105 @@
+/**
+ * In-memory task registry for the v6.0 alpha runtime.
+ *
+ * The framework owns task lifecycle. When an adopter method returns a
+ * `TaskHandoff` marker, the framework:
+ *   1. Allocates a `taskId` and writes a `submitted` record.
+ *   2. Returns the submitted envelope to the buyer immediately.
+ *   3. Runs the handoff function in the background.
+ *   4. Updates the record on progress (`updateProgress`) and terminal
+ *      state (`complete` / `fail`) from the method's return/throw.
+ *
+ * Adopters never call into the registry directly. Wire-level `tasks/get`
+ * integration (so buyers can poll the lifecycle) reads via `getTask`;
+ * test harnesses use `awaitTask` to flush the background promise
+ * deterministically.
+ *
+ * Status: Preview / 6.0.
+ *
+ * @public
+ */
+import type { AdcpStructuredError, TaskHandoffProgress } from '../async-outcome';
+/**
+ * AdCP-spec task lifecycle states. Mirrors `enums/task-status.json` —
+ * the v6 framework writes `'submitted'` on create, transitions to
+ * `'working'` on the first `updateProgress()` call, and terminates at
+ * `'completed'` / `'failed'`. The other states (`'input-required'`,
+ * `'canceled'`, `'rejected'`, `'auth-required'`, `'unknown'`) are
+ * reserved for adopter-emitted transitions via the forthcoming
+ * `taskRegistry.transition()` API (v6.1).
+ */
+export type TaskStatus = 'submitted' | 'working' | 'input-required' | 'completed' | 'canceled' | 'failed' | 'rejected' | 'auth-required' | 'unknown';
+export interface TaskRecord<TResult = unknown, TError extends AdcpStructuredError = AdcpStructuredError> {
+    taskId: string;
+    /** Tool name that started the task (e.g., 'create_media_buy'). */
+    tool: string;
+    /** Account that started the task — sessionKey-like for cross-request scoping. */
+    accountId: string;
+    /** Current lifecycle state — full AdCP-spec `task-status` enum. */
+    status: TaskStatus;
+    /** Status message on the final arm (`error.message` on failed). */
+    statusMessage?: string;
+    /** Terminal result on `completed`. */
+    result?: TResult;
+    /** Terminal error on `failed`. */
+    error?: TError;
+    /**
+     * Intermediate progress from `TaskHandoffContext.update(...)` calls.
+     * Written by the background handoff function; surfaced to buyers polling
+     * `tasks_get` via the spec `progress` field.
+     */
+    progress?: TaskHandoffProgress;
+    /**
+     * Whether the buyer wired `push_notification_config.url` on the original
+     * request. Surfaced to the buyer via `tasks_get`'s spec-defined
+     * `has_webhook: boolean` field so they can decide between long-poll vs.
+     * single-shot polling.
+     */
+    hasWebhook?: boolean;
+    /** ISO 8601 timestamps. */
+    createdAt: string;
+    updatedAt: string;
+}
+export interface TaskRegistry {
+    /**
+     * Allocate a new task record. Returns the `taskId` the framework hands
+     * to `platform.xxxTask(taskId, ...)`. Initial status is `submitted`.
+     *
+     * `hasWebhook: true` when the buyer wired `push_notification_config.url`
+     * — surfaced via `tasks_get`'s `has_webhook` field. Defaults to `false`.
+     */
+    create(opts: {
+        tool: string;
+        accountId: string;
+        hasWebhook?: boolean;
+    }): Promise<{
+        taskId: string;
+    }>;
+    /** Read a task by id. Returns `null` if unknown. */
+    getTask<TResult = unknown>(taskId: string): Promise<TaskRecord<TResult> | null>;
+    /**
+     * Mark a task `completed` with the method's return value. No-op if the
+     * task is already terminal (idempotent).
+     */
+    complete<TResult>(taskId: string, result: TResult): Promise<void>;
+    /**
+     * Mark a task `failed` with the structured error. No-op if the task is
+     * already terminal (idempotent).
+     */
+    fail(taskId: string, error: AdcpStructuredError): Promise<void>;
+    /**
+     * Record intermediate progress from `TaskHandoffContext.update(...)`.
+     * Transitions the task from `'submitted'` → `'working'` on the first
+     * call. No-op on already-terminal tasks. The `progress` payload is
+     * written to the record and surfaced to buyers polling `tasks_get`.
+     */
+    updateProgress(taskId: string, progress: TaskHandoffProgress): Promise<void>;
+    /**
+     * Await any registered background completion for a task. Resolves
+     * immediately if no background is registered or it has already settled.
+     * Used by test harnesses + `tasks/get` integration.
+     */
+    awaitTask(taskId: string): Promise<void>;
+}
+export declare function createInMemoryTaskRegistry(): TaskRegistry;
+//# sourceMappingURL=task-registry.d.ts.map

package/dist/lib/server/decisioning/runtime/task-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-registry.d.ts","sourceRoot":"","sources":["../../../../../src/lib/server/decisioning/runtime/task-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEjF;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAClB,WAAW,GACX,SAAS,GACT,gBAAgB,GAChB,WAAW,GACX,UAAU,GACV,QAAQ,GACR,UAAU,GACV,eAAe,GACf,SAAS,CAAC;AAEd,MAAM,WAAW,UAAU,CAAC,OAAO,GAAG,OAAO,EAAE,MAAM,SAAS,mBAAmB,GAAG,mBAAmB;IACrG,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAC;IAClB,mEAAmE;IACnE,MAAM,EAAE,UAAU,CAAC;IACnB,mEAAmE;IACnE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sCAAsC;IACtC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,kCAAkC;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD,MAAM,WAAW,YAAY;IAC3B;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAErG,oDAAoD;IACpD,OAAO,CAAC,OAAO,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,CAAC;IAEhF;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElE;;;OAGG;IACH,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhE;;;;;OAKG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAW7E;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C;AAED,wBAAgB,0BAA0B,IAAI,YAAY,CAsEzD"}

package/dist/lib/server/decisioning/runtime/task-registry.js

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * In-memory task registry for the v6.0 alpha runtime.
+ *
+ * The framework owns task lifecycle. When an adopter method returns a
+ * `TaskHandoff` marker, the framework:
+ *   1. Allocates a `taskId` and writes a `submitted` record.
+ *   2. Returns the submitted envelope to the buyer immediately.
+ *   3. Runs the handoff function in the background.
+ *   4. Updates the record on progress (`updateProgress`) and terminal
+ *      state (`complete` / `fail`) from the method's return/throw.
+ *
+ * Adopters never call into the registry directly. Wire-level `tasks/get`
+ * integration (so buyers can poll the lifecycle) reads via `getTask`;
+ * test harnesses use `awaitTask` to flush the background promise
+ * deterministically.
+ *
+ * Status: Preview / 6.0.
+ *
+ * @public
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createInMemoryTaskRegistry = createInMemoryTaskRegistry;
+const node_crypto_1 = require("node:crypto");
+function createInMemoryTaskRegistry() {
+    const tasks = new Map();
+    const backgrounds = new Map();
+    return {
+        async create(opts) {
+            const taskId = `task_${(0, node_crypto_1.randomUUID)()}`;
+            const now = new Date().toISOString();
+            tasks.set(taskId, {
+                taskId,
+                tool: opts.tool,
+                accountId: opts.accountId,
+                status: 'submitted',
+                ...(opts.hasWebhook && { hasWebhook: true }),
+                createdAt: now,
+                updatedAt: now,
+            });
+            return { taskId };
+        },
+        async getTask(taskId) {
+            const record = tasks.get(taskId);
+            return record ?? null;
+        },
+        async complete(taskId, result) {
+            const existing = tasks.get(taskId);
+            if (!existing)
+                return;
+            if (existing.status === 'completed' || existing.status === 'failed')
+                return;
+            existing.status = 'completed';
+            existing.result = result;
+            existing.updatedAt = new Date().toISOString();
+        },
+        async fail(taskId, error) {
+            const existing = tasks.get(taskId);
+            if (!existing)
+                return;
+            if (existing.status === 'completed' || existing.status === 'failed')
+                return;
+            existing.status = 'failed';
+            existing.error = error;
+            existing.statusMessage = error.message;
+            existing.updatedAt = new Date().toISOString();
+        },
+        async updateProgress(taskId, progress) {
+            const existing = tasks.get(taskId);
+            if (!existing)
+                return;
+            if (existing.status === 'completed' || existing.status === 'failed')
+                return;
+            if (existing.status === 'submitted')
+                existing.status = 'working';
+            existing.progress = progress;
+            existing.updatedAt = new Date().toISOString();
+        },
+        _registerBackground(taskId, completion) {
+            const composed = completion.then(() => {
+                if (backgrounds.get(taskId) === composed)
+                    backgrounds.delete(taskId);
+            }, () => {
+                if (backgrounds.get(taskId) === composed)
+                    backgrounds.delete(taskId);
+            });
+            backgrounds.set(taskId, composed);
+        },
+        async awaitTask(taskId) {
+            const pending = backgrounds.get(taskId);
+            if (pending)
+                await pending;
+        },
+    };
+}
+//# sourceMappingURL=task-registry.js.map

package/dist/lib/server/decisioning/runtime/task-registry.js.map

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

package/dist/lib/server/decisioning/runtime/to-context.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Translate the existing `HandlerContext` into the v6 `RequestContext` shape
+ * that platform methods receive.
+ *
+ * The handler-style framework already resolves the account, sets sessionKey,
+ * and exposes `store` + `authInfo` + `emitWebhook`. The new context layers
+ * `state.*` (sync state reads), `resolve.*` (async framework-mediated
+ * resolvers), and `handoffToTask(...)` (the unified hybrid-seller handoff
+ * primitive) on top.
+ *
+ * **Stub status — v6.0 alpha.** `state.*` (workflow-step reads, proposal
+ * lookups, governance JWS) and `resolve.*` (property/collection-list +
+ * format fetchers) are NOT yet wired. The state readers return empty
+ * results; the resolvers throw. Touching them in a platform method will
+ * crash the request — the framework hasn't connected them to an underlying
+ * store / fetch layer yet.
+ *
+ * Adopters spiking against the preview surface MUST avoid `ctx.state.*`
+ * and `ctx.resolve.*` until the wire-up commits land in rc.1. Use
+ * `ctx.account`, `ctx.handoffToTask(...)`, and the structured-error /
+ * status-change primitives only.
+ *
+ * @internal — framework-internal wiring; not adopter surface. The
+ * exported helpers (`buildRequestContext`, `buildHandoffContext`) are
+ * called from the dispatch seam in `from-platform.ts`. Adopters should
+ * never construct a `RequestContext` themselves; the framework supplies
+ * one to every specialism method call.
+ */
+import type { Account } from '../account';
+import type { RequestContext } from '../context';
+import type { TaskRegistry } from './task-registry';
+import { type TaskHandoffContext } from '../async-outcome';
+import type { CtxMetadataStore } from '../../ctx-metadata';
+export declare function buildRequestContext<TCtxMeta = Record<string, unknown>>(handlerCtx: HandlerContext<Account<TCtxMeta>>, ctxMetadataStore?: CtxMetadataStore): RequestContext<Account<TCtxMeta>>;
+/**
+ * Construct a `TaskHandoffContext` from a registry + framework-issued
+ * task id. The framework calls this AFTER detecting a `TaskHandoff`
+ * marker on a method's return — the handoff function gets a context
+ * carrying the framework-allocated `taskId` plus `update`/`heartbeat`
+ * affordances.
+ *
+ * `update(progress)` writes the progress payload to the task record and
+ * transitions status `submitted` → `working`. Buyers polling `tasks_get`
+ * see the `progress` object and the `'working'` status — this is the
+ * buyer-facing UX signal that distinguishes "stuck/no news" from
+ * "step 2/3, awaiting trafficker." Errors from the registry write are
+ * swallowed so a transient DB hiccup doesn't abort the adopter's handoff
+ * function.
+ *
+ * `heartbeat()` remains a no-op stub (v6.1); it is a liveness / TTL-reset
+ * signal for operator infrastructure, not buyer-facing.
+ */
+export declare function buildHandoffContext(taskRegistry: TaskRegistry, taskId: string): TaskHandoffContext;
+//# sourceMappingURL=to-context.d.ts.map

package/dist/lib/server/decisioning/runtime/to-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-context.d.ts","sourceRoot":"","sources":["../../../../../src/lib/server/decisioning/runtime/to-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EAAE,cAAc,EAAuB,MAAM,YAAY,CAAC;AACtE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAsB,KAAK,kBAAkB,EAAoB,MAAM,kBAAkB,CAAC;AACjG,OAAO,KAAK,EAAE,gBAAgB,EAAgC,MAAM,oBAAoB,CAAC;AAgDzF,wBAAgB,mBAAmB,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpE,UAAU,EAAE,cAAc,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,EAC7C,gBAAgB,CAAC,EAAE,gBAAgB,GAClC,cAAc,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAwDnC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,GAAG,kBAAkB,CAgBlG"}

package/dist/lib/server/decisioning/runtime/to-context.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * Translate the existing `HandlerContext` into the v6 `RequestContext` shape
+ * that platform methods receive.
+ *
+ * The handler-style framework already resolves the account, sets sessionKey,
+ * and exposes `store` + `authInfo` + `emitWebhook`. The new context layers
+ * `state.*` (sync state reads), `resolve.*` (async framework-mediated
+ * resolvers), and `handoffToTask(...)` (the unified hybrid-seller handoff
+ * primitive) on top.
+ *
+ * **Stub status — v6.0 alpha.** `state.*` (workflow-step reads, proposal
+ * lookups, governance JWS) and `resolve.*` (property/collection-list +
+ * format fetchers) are NOT yet wired. The state readers return empty
+ * results; the resolvers throw. Touching them in a platform method will
+ * crash the request — the framework hasn't connected them to an underlying
+ * store / fetch layer yet.
+ *
+ * Adopters spiking against the preview surface MUST avoid `ctx.state.*`
+ * and `ctx.resolve.*` until the wire-up commits land in rc.1. Use
+ * `ctx.account`, `ctx.handoffToTask(...)`, and the structured-error /
+ * status-change primitives only.
+ *
+ * @internal — framework-internal wiring; not adopter surface. The
+ * exported helpers (`buildRequestContext`, `buildHandoffContext`) are
+ * called from the dispatch seam in `from-platform.ts`. Adopters should
+ * never construct a `RequestContext` themselves; the framework supplies
+ * one to every specialism method call.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildRequestContext = buildRequestContext;
+exports.buildHandoffContext = buildHandoffContext;
+const async_outcome_1 = require("../async-outcome");
+/**
+ * Build an account-scoped CtxMetadataAccessor for a single request.
+ *
+ * Account scope comes from `ctx.account.id` — accessor methods don't take
+ * an account param. When `account.id` is null/undefined (no-account tools),
+ * the accessor methods reject — no-account tools cannot use ctx_metadata
+ * (cross-tenant collision risk via missing scope).
+ */
+function buildCtxMetadataAccessor(store, accountId) {
+    return {
+        get(kind, id) {
+            return store.get(accountId, kind, id);
+        },
+        bulkGet(refs) {
+            return store.bulkGet(accountId, refs);
+        },
+        set(kind, id, value, ttlSeconds) {
+            return store.set(accountId, kind, id, value, ttlSeconds);
+        },
+        delete(kind, id) {
+            return store.delete(accountId, kind, id);
+        },
+        account(id) {
+            return store.get(accountId, 'account', id);
+        },
+        product(id) {
+            return store.get(accountId, 'product', id);
+        },
+        mediaBuy(id) {
+            return store.get(accountId, 'media_buy', id);
+        },
+        package(id) {
+            return store.get(accountId, 'package', id);
+        },
+        creative(id) {
+            return store.get(accountId, 'creative', id);
+        },
+        audience(id) {
+            return store.get(accountId, 'audience', id);
+        },
+        signal(id) {
+            return store.get(accountId, 'signal', id);
+        },
+    };
+}
+function buildRequestContext(handlerCtx, ctxMetadataStore) {
+    // `account` may legitimately be undefined for tools whose wire request
+    // doesn't carry an `account` field AND whose `resolveAccountFromAuth`
+    // returned null (`'explicit'`-mode adopters who don't model the
+    // no-account tools, or buyers calling without auth). Adopter handlers
+    // for those tools are responsible for either deriving the account
+    // themselves (e.g., via `media_buy_id` ownership) or throwing
+    // `AdcpError('ACCOUNT_NOT_FOUND')` if account is required.
+    //
+    // The `RequestContext.account` type is non-optional for ergonomic typing
+    // — adopters writing handlers for the 90% case (tools with `account` on
+    // the wire) shouldn't have to optional-chain everywhere. Adopters of
+    // no-account tools either:
+    //   1. Declare `resolution: 'derived'` and return a singleton from
+    //      `accounts.resolve(undefined)` — `ctx.account` is always set
+    //   2. Implement only `'explicit'` and never claim no-account
+    //      specialisms — the tool is unreachable
+    //   3. Read `ctx.account` defensively (`as Account | undefined` cast)
+    //      and look up by request body when missing
+    const account = handlerCtx.account;
+    const stubResolver = (name) => async () => {
+        throw new Error(`ctx.resolve.${name}: not yet wired in v6.0 alpha — landing in rc.1. ` +
+            `Avoid touching ctx.resolve.* in adopter code until the framework ` +
+            `connects this resolver to an underlying fetcher.`);
+    };
+    // Bind ctx-metadata accessor when store wired AND account scope present.
+    // No-account tools (provide_performance_feedback, list_creative_formats)
+    // get `ctx.ctxMetadata = undefined` even when the store is wired — cannot
+    // use ctx_metadata without an account boundary (cross-tenant risk).
+    const ctxMetadata = ctxMetadataStore != null && account != null && (account.id ?? '') !== ''
+        ? buildCtxMetadataAccessor(ctxMetadataStore, account.id)
+        : undefined;
+    return {
+        account,
+        state: {
+            findByObject: () => [],
+            findProposalById: () => null,
+            governanceContext: () => null,
+            workflowSteps: () => [],
+        },
+        resolve: {
+            propertyList: stubResolver('propertyList'),
+            collectionList: stubResolver('collectionList'),
+            creativeFormat: stubResolver('creativeFormat'),
+        },
+        ctxMetadata,
+        handoffToTask(fn) {
+            return (0, async_outcome_1._createTaskHandoff)(fn);
+        },
+    };
+}
+/**
+ * Construct a `TaskHandoffContext` from a registry + framework-issued
+ * task id. The framework calls this AFTER detecting a `TaskHandoff`
+ * marker on a method's return — the handoff function gets a context
+ * carrying the framework-allocated `taskId` plus `update`/`heartbeat`
+ * affordances.
+ *
+ * `update(progress)` writes the progress payload to the task record and
+ * transitions status `submitted` → `working`. Buyers polling `tasks_get`
+ * see the `progress` object and the `'working'` status — this is the
+ * buyer-facing UX signal that distinguishes "stuck/no news" from
+ * "step 2/3, awaiting trafficker." Errors from the registry write are
+ * swallowed so a transient DB hiccup doesn't abort the adopter's handoff
+ * function.
+ *
+ * `heartbeat()` remains a no-op stub (v6.1); it is a liveness / TTL-reset
+ * signal for operator infrastructure, not buyer-facing.
+ */
+function buildHandoffContext(taskRegistry, taskId) {
+    return {
+        id: taskId,
+        update: async (progress) => {
+            try {
+                await taskRegistry.updateProgress(taskId, progress);
+            }
+            catch {
+                // Swallow — a transient registry write failure must not abort the
+                // adopter's background handoff function. The buyer-facing impact is
+                // a missed progress event, not a failed task.
+            }
+        },
+        heartbeat: async () => {
+            await Promise.resolve();
+        },
+    };
+}
+//# sourceMappingURL=to-context.js.map

package/dist/lib/server/decisioning/runtime/to-context.js.map

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

package/dist/lib/server/decisioning/runtime/validate-platform.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Runtime validation that a `DecisioningPlatform` impl matches its
+ * `capabilities.specialisms[]` declaration.
+ *
+ * Compile-time, `RequiredPlatformsFor<S>` enforces this in TypeScript adopter
+ * code. Untyped JS callers, downstream packages with relaxed `tsconfig`, and
+ * Python-port adopters running this through bindings need a runtime gate.
+ *
+ * Mirrors the v1.0 specialism × interface mapping in
+ * `src/lib/server/decisioning/platform.ts`.
+ *
+ * @public
+ */
+import type { DecisioningPlatform } from '../platform';
+export declare class PlatformConfigError extends Error {
+    readonly name: "PlatformConfigError";
+    constructor(message: string);
+}
+export declare function validatePlatform(platform: DecisioningPlatform): void;
+//# sourceMappingURL=validate-platform.d.ts.map

package/dist/lib/server/decisioning/runtime/validate-platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-platform.d.ts","sourceRoot":"","sources":["../../../../../src/lib/server/decisioning/runtime/validate-platform.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AA2CvD,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAG,qBAAqB,CAAU;gBACnC,OAAO,EAAE,MAAM;CAG5B;AAcD,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAkBpE"}