@adcp/sdk 6.6.0 → 6.8.0

package/dist/lib/server/decisioning/runtime/from-platform.js

@@ -38,9 +38,10 @@
  * `tasks/get` wire handler, per-server + module-level `publishStatusChange`.
  *
  * **Still deferred (rc.1+):** MCP Resources subscription projection for
- * `publishStatusChange`; `resolveAccount(undefined, { authInfo, toolName })`
- * refactor for `provide_performance_feedback` / `list_creative_formats`
- * no-account path in `'explicit'`-mode adopters (see `SalesPlatform` JSDoc).
+ * `publishStatusChange`. The no-account tool surface (`preview_creative`,
+ * `list_creative_formats`, `provide_performance_feedback`) is now typed
+ * via `NoAccountCtx<TCtxMeta>` — handlers receive `ctx.account: Account |
+ * undefined` and must narrow before reading `ctx_metadata`.
  *
  * Status: Preview / 6.0. Not yet exported from the public `./server`
  * subpath; reach in via `@adcp/sdk/server/decisioning/runtime` for
@@ -49,6 +50,7 @@
  * @public
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.INTENTIONALLY_UNHYDRATED_ENTITIES = exports.ENTITY_TO_RESOURCE_KIND = void 0;
 exports.createAdcpServerFromPlatform = createAdcpServerFromPlatform;
 exports._resetMergeSeamDedupe = _resetMergeSeamDedupe;
 exports.getAllAdcpMigrations = getAllAdcpMigrations;
@@ -58,12 +60,14 @@ const account_1 = require("../account");
 const async_outcome_1 = require("../async-outcome");
 const errors_1 = require("../../errors");
 const validate_platform_1 = require("./validate-platform");
+const validate_specialisms_1 = require("../validate-specialisms");
 const to_context_1 = require("./to-context");
 const ctx_metadata_1 = require("../../ctx-metadata");
 const idempotency_1 = require("../../idempotency");
 const pg_1 = require("../../idempotency/backends/pg");
 const postgres_task_registry_1 = require("./postgres-task-registry");
 const async_outcome_2 = require("../async-outcome");
+const entity_hydration_generated_1 = require("./entity-hydration.generated");
 const zod_1 = require("zod");
 const task_registry_1 = require("./task-registry");
 const protocol_for_tool_1 = require("./protocol-for-tool");
@@ -85,6 +89,10 @@ const DEFAULT_FRAMEWORK_LOGGER = {
 const status_changes_1 = require("../status-changes");
 const comply_controller_1 = require("../../../testing/comply-controller");
 const seed_merge_1 = require("../../../testing/seed-merge");
+const adcp_server_1 = require("../../adcp-server");
+const account_mode_1 = require("../../account-mode");
+const test_controller_1 = require("../../test-controller");
+const observed_modes_1 = require("./observed-modes");
 const normalize_errors_1 = require("../../normalize-errors");
 /**
  * Apply `normalizeErrors` to a sync_creatives row's optional `errors`
@@ -100,6 +108,80 @@ function normalizeRowErrors(row) {
         return row;
     return { ...row, errors: (0, normalize_errors_1.normalizeErrors)(row.errors) };
 }
+/**
+ * Enforce the documented inline-`account_id` refusal for resolution modes
+ * that declare the field meaningless on the wire — `'implicit'` (since
+ * #1364) and `'derived'` (since adcp-client#1468). Both modes share the
+ * same wire contract: the buyer does not pass `account_id` inline; the
+ * framework derives the tenant from the authenticated principal (after a
+ * `sync_accounts` step for `'implicit'`; directly for `'derived'`).
+ *
+ * Throws `AdcpError('INVALID_REQUEST')` before reaching the adopter's
+ * `accounts.resolve`, so each adopter doesn't reimplement the same
+ * `if (ref?.account_id) return null` branch and the wire response is
+ * consistent across both modes. The brand+operator union arm is
+ * permitted — only `account_id`-shaped references are refused.
+ *
+ * Mode-specific message and suggestion: `'implicit'` adopters get the
+ * `sync_accounts`-first guidance; `'derived'` adopters get the single-
+ * tenant explanation (no `sync_accounts` step exists in derived mode —
+ * the auth principal alone identifies the tenant).
+ *
+ * Documented at `AccountStore.resolution` in `account.ts`.
+ */
+function refuseInlineAccountIdWhenForbidden(resolution, ref) {
+    if (resolution !== 'implicit' && resolution !== 'derived')
+        return;
+    if ((0, account_1.refAccountId)(ref) === undefined)
+        return;
+    if (resolution === 'implicit') {
+        throw new async_outcome_1.AdcpError('INVALID_REQUEST', {
+            message: 'This platform resolves accounts from the authenticated principal — call sync_accounts first; do not pass account.account_id inline.',
+            field: 'account.account_id',
+            suggestion: 'Call sync_accounts to associate accounts with your principal, then omit account_id on subsequent calls.',
+        });
+    }
+    throw new async_outcome_1.AdcpError('INVALID_REQUEST', {
+        message: 'This single-tenant agent identifies the tenant from the authenticated principal alone — do not pass account.account_id inline; the field is meaningless on the wire for derived-resolution agents.',
+        field: 'account.account_id',
+        suggestion: 'Omit the account field; the framework derives the tenant from your authenticated credential.',
+    });
+}
+/**
+ * Dev-mode warning when a multi-id read tool returns fewer rows than
+ * the buyer requested — the canonical signal that the platform is
+ * silently truncating to `<id_field>[0]` (closes #1342, follow-up
+ * #1399, extended in #1410 to additional read-by-id surfaces). Catches
+ * the bug class where adopters write the recommended pattern wrong on
+ * first pass; quiet in production where legitimate misses (deleted,
+ * archived, cross-account) are routine and warning on every miss would
+ * be noise.
+ *
+ * Suppressible via `ADCP_SUPPRESS_MULTI_ID_WARN=1` for adopters whose
+ * legitimate-miss rate is high (deleted-account-rich datasets, etc.).
+ *
+ * Sync / upsert surfaces (`syncCreatives`, `syncCatalogs`, `syncPlans`)
+ * are intentionally out of scope — those have a different shape where
+ * pass-through is the obvious pattern and "did all rows roundtrip?"
+ * isn't a clean question.
+ */
+function warnIfTruncatedMultiIdResponse(toolName, idFieldName, requestedIds, responseArray, logger) {
+    if (process.env.NODE_ENV === 'production')
+        return;
+    if (process.env.ADCP_SUPPRESS_MULTI_ID_WARN === '1')
+        return;
+    if (!requestedIds || requestedIds.length === 0)
+        return;
+    const returned = Array.isArray(responseArray) ? responseArray.length : 0;
+    if (returned >= requestedIds.length)
+        return;
+    // Empty `<id_field>` is filtered above as paginated-mode (no truncation
+    // possible without a request to compare against).
+    logger.warn(`[adcp/sdk] ${toolName}: platform returned ${returned} row${returned === 1 ? '' : 's'} for ${requestedIds.length} requested ${idFieldName} — ` +
+        `the platform may be silently truncating to ${idFieldName}[0]. ` +
+        `See https://github.com/adcontextprotocol/adcp-client/issues/1342 for the multi-id pass-through contract. ` +
+        `Suppress with ADCP_SUPPRESS_MULTI_ID_WARN=1 if legitimate misses (deleted / cross-account) are routine.`);
+}
 // Use `DecisioningPlatform<any, any>` for the generic constraint. The default
 // `TCtxMeta = Record<string, unknown>` doesn't accept adopter metadata interfaces
 // without an index signature (e.g., `interface MyMeta { brand_id: string }`),
@@ -107,6 +189,37 @@ function normalizeRowErrors(row) {
 // framework, so we don't need to constrain it here.
 function createAdcpServerFromPlatform(platform, opts) {
     (0, validate_platform_1.validatePlatform)(platform);
+    // Specialism→required-tools coverage check (adcp-client#1299).
+    //
+    // For each specialism declared in `capabilities.specialisms[]`, verify the
+    // platform exposes a method matching every tool the manifest's
+    // `SPECIALISM_REQUIRED_TOOLS` lists for that specialism. Catches the
+    // common adopter mistake of declaring `'sales-non-guaranteed'` while
+    // forgetting to implement `getProducts` / `createMediaBuy` / etc. —
+    // would otherwise surface as a runtime error when a buyer actually
+    // calls the missing tool.
+    //
+    // Default behavior is console.warn — strictSpecialismValidation: true
+    // escalates to a thrown `PlatformConfigError`. The check is method-
+    // presence-anywhere on the platform (not method-on-specific-field) so
+    // adopters with non-standard layouts (e.g., a single mega-platform vs.
+    // the conventional sales/creative/accounts split) aren't false-positively
+    // flagged.
+    {
+        const specialisms = platform.capabilities.specialisms;
+        const issues = (0, validate_specialisms_1.validateSpecialismRequiredTools)(platform, specialisms);
+        if (issues.length > 0) {
+            const messages = issues.map(validate_specialisms_1.formatSpecialismIssue);
+            if (opts.strictSpecialismValidation === true) {
+                throw new validate_platform_1.PlatformConfigError(`Platform missing methods for ${issues.length} specialism-required tool(s). ` +
+                    `Strict mode (\`strictSpecialismValidation: true\`) treats this as fatal.\n` +
+                    messages.map(m => `  - ${m}`).join('\n'));
+            }
+            // eslint-disable-next-line no-console
+            for (const message of messages)
+                console.warn(message);
+        }
+    }
     // Compliance-testing capability/adapter consistency.
     //
     // Two failure modes the framework refuses to ship:
@@ -388,6 +501,23 @@ function createAdcpServerFromPlatform(platform, opts) {
         ...opts,
         ...(autoSeedStore != null && { testController: makeAutoSeedBridge(autoSeedStore) }),
         ...(projectedCapabilitiesConfig != null && { capabilities: projectedCapabilitiesConfig }),
+        // Buyer-agent registry (Phase 1 of #1269). Threaded through from the
+        // platform so the v5 dispatcher can call `agentRegistry.resolve()` on
+        // every request and populate `ctx.agent`. When the platform omits the
+        // field, the v5 surface stays unchanged.
+        //
+        // Precedence: this spread runs AFTER `...opts`, so `platform.agentRegistry`
+        // wins over any `opts.agentRegistry` an adopter passes via the v5 escape
+        // hatch. Same convention as the `idempotency` spread below — the platform
+        // is the authoritative v6 surface; opts is a low-level escape hatch.
+        ...(platform.agentRegistry !== undefined && { agentRegistry: platform.agentRegistry }),
+        // Server-level `instructions` (closes #1312). Same precedence pattern as
+        // `agentRegistry` above — platform-declared instructions win over the
+        // v5 `opts.instructions` escape hatch when both are present, so v6
+        // adopters can colocate platform facts / decision policy with the rest
+        // of their platform declaration.
+        ...(platform.instructions !== undefined && { instructions: platform.instructions }),
+        ...(platform.onInstructionsError !== undefined && { onInstructionsError: platform.onInstructionsError }),
         // Pool-derived stores override the spread above when adopters supplied
         // `pool` but no explicit per-store opt. Explicit values still win.
         ...(effectiveIdempotency !== undefined && { idempotency: effectiveIdempotency }),
@@ -408,10 +538,16 @@ function createAdcpServerFromPlatform(platform, opts) {
             let resolved = false;
             let resolvedAccountId;
             try {
-                const account = await platform.accounts.resolve(ref, {
-                    ...(ctx.authInfo !== undefined && { authInfo: ctx.authInfo }),
-                    toolName: ctx.toolName,
-                });
+                // Enforce the JSDoc contract documented at `AccountStore.resolution`:
+                // implicit-mode and derived-mode platforms refuse inline `account_id`
+                // references. Implicit: buyers call sync_accounts first, then the
+                // framework resolves from the auth principal. Derived: single-tenant;
+                // the principal alone identifies the tenant. The brand+operator union
+                // arm is permitted (implicit's sync_accounts onboarding flow); only
+                // the `{ account_id }` arm is refused. Closes adcp-client#1364
+                // (implicit) and adcp-client#1468 (derived).
+                refuseInlineAccountIdWhenForbidden(platform.accounts.resolution, ref);
+                const account = await platform.accounts.resolve(ref, toResolveCtx(ctx, ctx.toolName));
                 resolved = account != null;
                 resolvedAccountId = account?.id;
                 return account;
@@ -453,10 +589,7 @@ function createAdcpServerFromPlatform(platform, opts) {
             let resolved = false;
             let resolvedAccountId;
             try {
-                const account = await platform.accounts.resolve(undefined, {
-                    ...(ctx.authInfo !== undefined && { authInfo: ctx.authInfo }),
-                    toolName: ctx.toolName,
-                });
+                const account = await platform.accounts.resolve(undefined, toResolveCtx(ctx, ctx.toolName));
                 resolved = account != null;
                 resolvedAccountId = account?.id;
                 return account;
@@ -478,49 +611,73 @@ function createAdcpServerFromPlatform(platform, opts) {
         },
         // Merge: platform-derived handlers WIN per-key over adopter-supplied
         // custom handlers. Adopter handlers fill gaps for tools the v6 platform
-        // doesn't yet model (getMediaBuys, listCreativeFormats, content-standards
-        // CRUD, sync_event_sources, etc.). See `CreateAdcpServerFromPlatformOptions`
-        // JSDoc for the migration-seam contract.
+        // doesn't yet model (content-standards CRUD, sync_event_sources, etc.).
+        // See `CreateAdcpServerFromPlatformOptions` JSDoc for the migration-seam
+        // contract.
         mediaBuy: mergeHandlers(opts.mediaBuy, buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observability, fwLogger, {
             allowPrivateWebhookUrls: opts.allowPrivateWebhookUrls === true,
             autoEmitCompletionWebhooks: opts.autoEmitCompletionWebhooks !== false,
-        }, ctxFor, effectiveCtxMetadata), 'mediaBuy', mergeOpts),
+        }, ctxFor, effectiveCtxMetadata, opts.mediaBuyStore), 'mediaBuy', mergeOpts),
         creative: mergeHandlers(opts.creative, buildCreativeHandlers(platform, taskRegistry, taskWebhookEmit, observability, fwLogger, {
             allowPrivateWebhookUrls: opts.allowPrivateWebhookUrls === true,
             autoEmitCompletionWebhooks: opts.autoEmitCompletionWebhooks !== false,
         }, ctxFor), 'creative', mergeOpts),
         eventTracking: mergeHandlers(opts.eventTracking, buildEventTrackingHandlers(platform, ctxFor), 'eventTracking', mergeOpts),
         signals: mergeHandlers(opts.signals, buildSignalsHandlers(platform, ctxFor, effectiveCtxMetadata, fwLogger), 'signals', mergeOpts),
+        sponsoredIntelligence: mergeHandlers(opts.sponsoredIntelligence, buildSponsoredIntelligenceHandlers(platform, ctxFor, effectiveCtxMetadata, fwLogger), 'sponsoredIntelligence', mergeOpts),
         governance: mergeHandlers(opts.governance, buildGovernanceHandlers(platform, ctxFor), 'governance', mergeOpts),
         accounts: mergeHandlers(opts.accounts, buildAccountHandlers(platform, ctxFor), 'accounts', mergeOpts),
         brandRights: mergeHandlers(opts.brandRights, buildBrandRightsHandlers(platform, ctxFor, effectiveCtxMetadata, fwLogger), 'brandRights', mergeOpts),
         customTools: {
             ...opts.customTools,
-            tasks_get: buildTasksGetTool(platform, taskRegistry),
+            tasks_get: buildTasksGetTool(platform, taskRegistry, platform.agentRegistry, fwLogger),
         },
     };
     const server = (0, create_adcp_server_1.createAdcpServer)(config);
     // Wire `comply_test_controller` if the adopter supplied adapters.
     // `createComplyController` builds the tool definition + handler + raw
-    // dispatch; `register(server)` calls server.registerTool. Sandbox
-    // gating is the adopter's job (per-request via complyTest.sandboxGate
-    // or environment-level by guarding the createAdcpServerFromPlatform
-    // call site itself).
+    // dispatch. The framework registers the tool itself (bypassing
+    // `controller.register(server)`) so the sandbox-authority gate can
+    // resolve the calling account through `platform.accounts.resolve`
+    // BEFORE dispatching — under no circumstances should the controller
+    // operate on a `live`-mode account, regardless of what the caller
+    // claims on the wire. See `docs/proposals/lifecycle-state-and-sandbox-authority.md`
+    // for the full three-mode design and #1435 phase 2.
     if (opts.complyTest != null) {
         let complyConfig = opts.complyTest;
         if (autoSeedStore != null) {
             // Inject auto-seed adapters for `seed_product` and `seed_pricing_option`
             // when the adopter didn't wire explicit ones. Explicit adapters win — the
-            // spread only fills the undefined slots. Each write is keyed by the
-            // request's `account.account_id` so two sandbox accounts can seed the
-            // same `product_id` without colliding.
+            // spread only fills the undefined slots.
+            //
+            // **Namespace key: raw `account.account_id`.** The adapter does NOT call
+            // `platform.accounts.resolve` even though that would seem symmetric with
+            // the bridge's `ctx.account?.id` read — calling resolve here without
+            // `authInfo` (which `ComplyControllerContext` doesn't expose) lets a
+            // caller spoof `account.account_id: 'victim'` and have a non-validating
+            // resolver write seeds into the victim's resolved namespace. Raw id is
+            // the safe choice: a caller can only write to their own claimed id, and
+            // the sandboxGate already filters non-sandbox traffic.
+            //
+            // **Trade-off.** Adopters whose resolver maps `account_id` to a distinct
+            // internal id (e.g., `acc_1` → `tenant_a:acc_1`) will see seeded fixtures
+            // disappear — the adapter writes to `acc_1`, the bridge reads
+            // `tenant_a:acc_1`, no match. That's a documented limitation, not a
+            // security issue: silent test loss, not cross-tenant pollution. The
+            // architectural fix (widen `ComplyControllerContext` to expose the
+            // framework-resolved account so writes match reads even under mapping
+            // resolvers) is tracked at #1216. Mapping-resolver adopters wire
+            // explicit seed adapters today.
             const explicitSeed = opts.complyTest.seed ?? {};
             const autoSeed = { ...explicitSeed };
             if (!explicitSeed.product) {
                 autoSeed.product = async (params, ctx) => {
                     const accountId = readAutoSeedAccountId(ctx.input);
-                    if (accountId == null)
+                    if (accountId == null) {
+                        fwLogger.warn('[adcp/auto-seed] seed_product fired without `account.account_id`; dropping write. ' +
+                            'Verify the request envelope carries an account ref and the sandboxGate is configured correctly.', { product_id: params.product_id });
                         return;
+                    }
                     autoSeedStoreFor(autoSeedStore, accountId).set(params.product_id, {
                         ...params.fixture,
                         product_id: params.product_id,
@@ -530,8 +687,11 @@ function createAdcpServerFromPlatform(platform, opts) {
             if (!explicitSeed.pricing_option) {
                 autoSeed.pricing_option = async (params, ctx) => {
                     const accountId = readAutoSeedAccountId(ctx.input);
-                    if (accountId == null)
+                    if (accountId == null) {
+                        fwLogger.warn('[adcp/auto-seed] seed_pricing_option fired without `account.account_id`; dropping write. ' +
+                            'Verify the request envelope carries an account ref and the sandboxGate is configured correctly.', { product_id: params.product_id, pricing_option_id: params.pricing_option_id });
                         return;
+                    }
                     const accountStore = autoSeedStoreFor(autoSeedStore, accountId);
                     const existing = accountStore.get(params.product_id);
                     const pricingOption = { ...params.fixture, pricing_option_id: params.pricing_option_id };
@@ -550,7 +710,131 @@ function createAdcpServerFromPlatform(platform, opts) {
             complyConfig = { ...opts.complyTest, seed: autoSeed };
         }
         const controller = (0, comply_controller_1.createComplyController)(complyConfig);
-        controller.register(server);
+        // Manual registration with framework-side sandbox-authority gate. See
+        // top-of-block rationale and `docs/proposals/lifecycle-state-and-sandbox-authority.md`.
+        //
+        // Trust boundary: the gate consults the *resolved* account from
+        // `platform.accounts.resolve`, NOT a buyer-supplied claim like
+        // `account.sandbox === true` on the wire. The resolver is the only
+        // thing that names the account's mode; the gate refuses dispatch when
+        // mode is `live` (or the resolver fails to produce an account, modulo
+        // the env / context fallbacks below).
+        //
+        // Fallback paths (deprecated):
+        //   - `context.sandbox === true` admits when no account resolved. Useful
+        //     during the migration window for adopters whose wire shape carries
+        //     sandbox routing in `context` but whose resolver isn't yet returning
+        //     `mode: 'sandbox'`.
+        //   - `process.env.ADCP_SANDBOX === '1'` admits unconditionally — the
+        //     historical pattern. KEPT for back-compat so existing test platforms
+        //     don't break on upgrade. Fails closed if the same process has ever
+        //     resolved an explicit `mode: 'live'` account from the resolver: that
+        //     pairing is a misconfiguration (env var should be unset on prod) and
+        //     leaving it open re-exposes the live principal we just gated against.
+        //
+        // `list_scenarios` is exempt — it's the discovery probe used by buyer
+        // tooling to distinguish "controller wired but locked" from "controller
+        // missing entirely". Read-only and reveals nothing beyond which scenarios
+        // the adopter advertised in capabilities.
+        const mcp = (0, adcp_server_1.getSdkServer)(server);
+        if (mcp == null) {
+            // Non-MCP server — fall back to the controller's own registration so
+            // adopters wiring a custom transport keep the v5 behavior. The gate is
+            // an MCP-side concern; A2A and other transports are wired separately.
+            controller.register(server);
+        }
+        else {
+            // Permit a top-level `account` field on the wire so the gate can read
+            // the buyer's account ref. The canonical AdCP shape strips it (account
+            // routes through `context.account`), but adopters' storyboard fixtures
+            // commonly send it at the top level — `TOOL_INPUT_SHAPE`'s JSDoc in
+            // `src/lib/server/test-controller.ts` documents this extension as the
+            // supported escape hatch.
+            //
+            // Schema is the full canonical `AccountReference` per
+            // `schemas/cache/3.0.5/core/account-ref.json`: oneOf
+            //   { account_id }                       — explicit accounts
+            //   { brand, operator, sandbox? }        — implicit accounts
+            // Modeled here as a single object with all four fields optional so
+            // either arm passes; resolvers narrow on the shape at dispatch.
+            // `brand` content is `unknown()` because the inner `brand-ref.json`
+            // shape is itself a oneOf and resolvers (not the gate) validate it.
+            // Top-level `.strict()` still blocks unknown keys at the framework
+            // boundary so a buyer can't stuff `__proto__` / arbitrary payloads
+            // into adopters' resolvers.
+            const gatedInputSchema = {
+                ...controller.toolDefinition.inputSchema,
+                account: zod_1.z
+                    .object({
+                    account_id: zod_1.z.string().min(1).optional(),
+                    brand: zod_1.z.unknown().optional(),
+                    operator: zod_1.z.string().optional(),
+                    sandbox: zod_1.z.boolean().optional(),
+                })
+                    .strict()
+                    .optional(),
+            };
+            mcp.registerTool(controller.toolDefinition.name, {
+                description: controller.toolDefinition.description,
+                inputSchema: gatedInputSchema,
+            }, (async (input, extra) => {
+                // Probe exempt — capability discovery, no state mutation.
+                if (input.scenario === 'list_scenarios') {
+                    return controller.handle(input);
+                }
+                // Read account ref from top-level (extended shape) or from
+                // `context.account` (canonical AdCP routing). First non-null wins.
+                const refFromTop = input.account;
+                const refFromContext = input.context?.account;
+                const accountRef = refFromTop ?? refFromContext;
+                let resolvedAccount = null;
+                try {
+                    resolvedAccount = await platform.accounts.resolve(accountRef, {
+                        ...(extra?.authInfo !== undefined && { authInfo: extra.authInfo }),
+                        toolName: 'comply_test_controller',
+                    });
+                }
+                catch {
+                    // Resolver failures fall through to the wire-ref / env fallbacks.
+                    // Treat as "no account resolved" — fail-closed by default unless a
+                    // fallback admits.
+                }
+                // Record the resolved account's explicit mode (if any). Used by the
+                // env-fallback fail-closed guard below.
+                (0, observed_modes_1.recordResolvedAccountMode)(resolvedAccount);
+                const accountIsSandbox = resolvedAccount != null && (0, account_mode_1.isSandboxOrMockAccount)(resolvedAccount);
+                // Spec-defined fallback for the unresolved-account path: read
+                // `sandbox: true` off the wire `AccountReference` (per
+                // `core/account-ref.json`). Only consulted when the resolver
+                // returned `null` — if the resolver names the account, the
+                // resolver wins. The buyer's wire claim never overrides a
+                // resolved live account.
+                const refSandbox = accountRef?.sandbox === true;
+                const envSandbox = process.env.ADCP_SANDBOX === '1';
+                const wouldAdmitOnlyViaEnv = envSandbox && !accountIsSandbox && !(resolvedAccount == null && refSandbox);
+                // Fail-closed guard on the env fallback. If the env var is the only
+                // signal that would admit AND this process has ever resolved an
+                // explicit `mode: 'live'` account from the resolver, the env is
+                // misconfigured. Refuse loudly so operators notice, instead of
+                // silently downgrading the gate for live principals.
+                if (wouldAdmitOnlyViaEnv && (0, observed_modes_1.hasObservedLiveMode)()) {
+                    throw new Error('comply_test_controller: ADCP_SANDBOX=1 is set but this process has resolved at least one ' +
+                        'live-mode account from platform.accounts.resolve. Remove ADCP_SANDBOX from your prod ' +
+                        'environment; gate the controller via mode: "sandbox" on resolved sandbox accounts instead. ' +
+                        'See docs/proposals/lifecycle-state-and-sandbox-authority.md.');
+                }
+                const allowed = accountIsSandbox || (resolvedAccount == null && refSandbox) || envSandbox;
+                if (!allowed) {
+                    return (0, test_controller_1.toMcpResponse)({
+                        success: false,
+                        error: 'FORBIDDEN',
+                        error_detail: 'comply_test_controller requires a sandbox or mock account; ' +
+                            'resolved account is in live mode (or no account resolved).',
+                    });
+                }
+                return controller.handle(input);
+            }));
+        }
     }
     return Object.assign(server, {
         getTaskState: async (taskId, expectedAccountId) => {
@@ -592,7 +876,7 @@ function createAdcpServerFromPlatform(platform, opts) {
  * (`resolution: 'derived'`) get scoping for free via the auth-derived
  * resolver.
  */
-function buildTasksGetTool(platform, taskRegistry) {
+function buildTasksGetTool(platform, taskRegistry, agentRegistry, logger) {
     const inputShape = {
         // Cap task_id length: framework-issued task ids are
         // `task_<UUIDv4>` = 41 chars. Cap at 128 so a malicious buyer can't
@@ -633,12 +917,64 @@ function buildTasksGetTool(platform, taskRegistry) {
         // `resolveAccount` dispatch flow in `create-adcp-server.ts:2380-2398`.
         handler: async (args, extra) => {
             const ref = args.account;
+            // Resolve the buyer agent (when an `agentRegistry` is configured) so
+            // adopters' `accounts.resolve` impl sees `ctx.agent` — same contract as
+            // every other AccountStore method. Bypasses the dispatcher's
+            // resolution-and-status-enforcement seam at
+            // `create-adcp-server.ts:2748-2832` deliberately:
+            //
+            //   - **Status enforcement is intentionally skipped on tasks_get
+            //     polls.** A buyer agent suspended AFTER kicking off an HITL task
+            //     must still be able to learn the task's terminal state — refusing
+            //     the poll would strand work with no visibility. Hard-cutoff
+            //     sellers implement that policy inside their `accounts.resolve`
+            //     or downstream by reading `ctx.agent.status` themselves.
+            //   - **Registry failures don't break the poll.** A transient registry
+            //     error during a read poll falls through to `agent: undefined`;
+            //     adopters who require a resolved agent for tenant scoping can
+            //     return null from their `accounts.resolve` and the existing
+            //     ACCOUNT_NOT_FOUND surface fires.
+            let agent;
+            if (agentRegistry !== undefined) {
+                try {
+                    const resolved = await agentRegistry.resolve({
+                        ...(extra?.authInfo?.credential !== undefined && { credential: extra.authInfo.credential }),
+                        ...(extra?.authInfo?.extra !== undefined && { extra: extra.authInfo.extra }),
+                    });
+                    if (resolved != null) {
+                        // Mirror the dispatcher's freeze contract: lock the resolved
+                        // record (and `billing_capabilities` Set if present) so adopter
+                        // code cannot mutate shared registry state across requests.
+                        // See `create-adcp-server.ts:2762-2779` for the full rationale.
+                        if (!Object.isFrozen(resolved)) {
+                            if (resolved.billing_capabilities instanceof Set) {
+                                Object.freeze(resolved.billing_capabilities);
+                            }
+                            Object.freeze(resolved);
+                        }
+                        agent = resolved;
+                    }
+                }
+                catch (err) {
+                    // Swallow to keep the poll alive (see policy comment above), but
+                    // log so upstream-IDP outages are visible to operators. Without
+                    // this log, buyers seeing REFERENCE_NOT_FOUND for valid tasks
+                    // (because adopters' resolvers return null without `ctx.agent`)
+                    // would be invisible in adopter logs. Per security-reviewer
+                    // defense-in-depth note on PR #1323.
+                    logger.warn?.('Buyer-agent registry resolution failed during tasks_get poll', {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
             const resolveCtx = {
                 ...(extra?.authInfo !== undefined && { authInfo: extra.authInfo }),
                 toolName: 'tasks_get',
+                ...(agent !== undefined && { agent }),
             };
             let resolvedAccountId;
             if (ref) {
+                refuseInlineAccountIdWhenForbidden(platform.accounts.resolution, ref);
                 try {
                     const resolved = await platform.accounts.resolve(ref, resolveCtx);
                     if (resolved)
@@ -974,9 +1310,16 @@ async function runWithTokenRefresh(fn, refresh) {
                 recovery: 'correctable',
             });
         }
-        refresh.account.authInfo.token = refreshed.token;
-        if (refreshed.expiresAt !== undefined) {
-            refresh.account.authInfo.expiresAt = refreshed.expiresAt;
+        // `authInfo` became optional in #1286. Token refresh only fires after an
+        // AUTH_REQUIRED throw — meaning an upstream call attempted to use a
+        // token, which means `authInfo` was populated before the throw.
+        // Defensive guard: if for some reason it isn't, the refreshed token
+        // still flows on the next request rather than crashing here.
+        if (refresh.account.authInfo) {
+            refresh.account.authInfo.token = refreshed.token;
+            if (refreshed.expiresAt !== undefined) {
+                refresh.account.authInfo.expiresAt = refreshed.expiresAt;
+            }
         }
         return fn();
     }
@@ -1053,11 +1396,11 @@ async function routeIfHandoff(taskRegistry, opts, result, project) {
             // but didn't go through ctx.handoffToTask. Treat as a sync
             // success arm with an empty body (caller-supplied projection
             // shapes the result; this branch is defensive).
-            return project(result);
+            return await project(result);
         }
         return dispatchHitl(taskRegistry, opts, async (taskId) => {
             const inner = await taskFn((0, to_context_1.buildHandoffContext)(taskRegistry, taskId));
-            return project(inner);
+            return await project(inner);
         });
     }
     // Catch the most common LLM-scaffolded mistake: hand-rolling a
@@ -1079,7 +1422,7 @@ async function routeIfHandoff(taskRegistry, opts, result, project) {
             `task registry and the buyer ends up polling a task_id the framework ` +
             `never registered.`);
     }
-    const projected = project(result);
+    const projected = await project(result);
     if (opts.autoEmitCompletion === true && opts.pushNotificationUrl) {
         // Auto-emit completion webhook on sync-success arm — fire-and-forget.
         // Awaiting inline would let an attacker-controlled
@@ -1383,6 +1726,31 @@ function bucketWebhookError(msg) {
 function makeCtxFor(ctxMetadataStore) {
     return handlerCtx => (0, to_context_1.buildRequestContext)(handlerCtx, ctxMetadataStore);
 }
+/**
+ * Project a framework `HandlerContext` / `RequestContext` to the public
+ * `ResolveContext` shape passed to every `AccountStore` method
+ * (`resolve`, `upsert`, `list`, `reportUsage`, `getAccountFinancials`).
+ *
+ * Single source of truth for the threading shape: when `ResolveContext`
+ * gains a new field, update this function and every account-method call
+ * site picks it up. The alternative (inline literals at each call site)
+ * is what produced the original asymmetric `agent` gap on `reportUsage`
+ * and `getAccountFinancials` — fixed by routing all six framework call
+ * sites through here.
+ *
+ * `toolName` is supplied per call site (handlers hardcode their tool
+ * name; the dispatcher's `resolveAccount` / `resolveAccountFromAuth`
+ * paths read it off `RequestContext.toolName`). Spread guards keep
+ * `authInfo` / `agent` keys absent rather than `undefined` — adopters
+ * can use `'authInfo' in ctx` as a presence check.
+ */
+function toResolveCtx(ctx, toolName) {
+    return {
+        ...(ctx.authInfo !== undefined && { authInfo: ctx.authInfo }),
+        toolName,
+        ...(ctx.agent != null && { agent: ctx.agent }),
+    };
+}
 /**
  * Auto-store helper. After a publisher returns resources from a discovery
  * tool (`getProducts`, `getMediaBuys`, etc.), persist each resource's wire
@@ -1434,6 +1802,69 @@ async function autoStoreResources(store, accountId, kind, resources, idField, lo
             `to reference these resources on a subsequent mutating call.`);
     }
 }
+/**
+ * Persist `packages[].targeting_overlay` from a successful
+ * `create_media_buy`. Called from the createMediaBuy projection so the
+ * persistence applies to both the sync arm and the HITL completion arm
+ * (the projection runs after the handoff fn resolves).
+ *
+ * Failures are logged + swallowed: a successful seller response must
+ * never be turned into an error by the auto-echo plumbing.
+ */
+async function persistTargetingOverlayFromCreate(store, accountId, request, result, logger) {
+    if (!store || !accountId)
+        return;
+    if (result == null || typeof result !== 'object')
+        return;
+    try {
+        await store.persistFromCreate(accountId, request, result);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.warn(`[adcp/decisioning] mediaBuyStore.persistFromCreate failed: ${msg}`);
+    }
+}
+/**
+ * Apply an `update_media_buy` patch to the persisted media-buy store.
+ * Per-field merge inside `targeting_overlay`: omitted keeps prior,
+ * present-non-null replaces, present-null clears.
+ *
+ * Failures are logged + swallowed for the same reason as the create
+ * path — the seller's update succeeded; auto-merge is best-effort.
+ */
+async function persistTargetingOverlayFromUpdate(store, accountId, mediaBuyId, patch, logger) {
+    if (!store || !accountId)
+        return;
+    try {
+        await store.mergeFromUpdate(accountId, mediaBuyId, patch);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.warn(`[adcp/decisioning] mediaBuyStore.mergeFromUpdate failed: ${msg}`);
+    }
+}
+/**
+ * Backfill missing `packages[].targeting_overlay` on a `get_media_buys`
+ * response from the persisted store. Mutates the response. Packages the
+ * seller already echoed are left alone.
+ *
+ * Failures are logged + swallowed: a partial-echo response is strictly
+ * better than a hard error wiping out the seller's correctly-returned
+ * media-buy data.
+ */
+async function backfillTargetingOverlay(store, accountId, result, logger) {
+    if (!store || !accountId)
+        return;
+    if (result == null || typeof result !== 'object')
+        return;
+    try {
+        await store.backfill(accountId, result);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.warn(`[adcp/decisioning] mediaBuyStore.backfill failed: ${msg}`);
+    }
+}
 /**
  * Auto-hydrate helper. Before invoking a publisher's mutating handler,
  * walk the request's resource references and attach the full wire
@@ -1594,6 +2025,135 @@ async function hydrateSingleResource(store, accountId, kind, id, attachField, ta
         configurable: true,
     });
 }
+/**
+ * Spec `x-entity` annotation → SDK `ResourceKind`. The SDK only hydrates
+ * resource kinds it has a backing store for; unmapped entities (e.g.
+ * `vendor_pricing_option`, `governance_plan`) are gracefully skipped.
+ *
+ * The annotation acts as a renaming-firewall: if the spec renames
+ * `media_buy_id` → `mediabuy_id`, the `x-entity: "media_buy"` tag travels
+ * with the field and the codegen step in `scripts/generate-entity-hydration.ts`
+ * picks up the new field name automatically — no SDK code change required.
+ *
+ * Adding a new `ResourceKind` for hydration is a coordinated change: add
+ * it to `ResourceKind` (in `ctx-metadata/store.ts`) and to this map.
+ */
+/** @internal Exported for the coverage test in `test/lib/x-entity-hydration.test.js`. */
+exports.ENTITY_TO_RESOURCE_KIND = {
+    media_buy: 'media_buy',
+    package: 'package',
+    creative: 'creative',
+    audience: 'audience',
+    // Spec quirk: `signal_activation_id` is a SEPARATE entity from `signal`
+    // (per AdCP `core/x-entity-types.json` — the activation handle is
+    // scoped to the issuing signals agent, not interchangeable with the
+    // catalog's `signal_id`). The SDK collapses them onto the existing
+    // `signal` ResourceKind for backward-compat: adopters already seed
+    // the cache keyed by `signal_agent_segment_id` under `kind: 'signal'`.
+    // Splitting `signal_activation` to its own ResourceKind would orphan
+    // those entries. Tracked upstream — file an `adcp` issue if/when this
+    // collapse causes confusion.
+    signal_activation_id: 'signal',
+    rights_grant: 'rights_grant',
+    property_list: 'property_list',
+    collection_list: 'collection_list',
+    account: 'account',
+    product: 'product',
+    // SI session lifecycle, hydrated on `si_send_message` /
+    // `si_terminate_session` from the entry the framework auto-stores after
+    // `si_initiate_session`. See `buildSponsoredIntelligenceHandlers`.
+    si_session: 'si_session',
+};
+/**
+ * `x-entity` values the SDK does NOT hydrate today — graceful skip rather
+ * than failure. Entries here are documented intentional skips so a future
+ * code reader can distinguish "we forgot to map this" from "the SDK
+ * doesn't model this kind."
+ *
+ * The codegen-derived `TOOL_ENTITY_FIELDS` map carries every `x-entity`
+ * the spec emits on dispatchable tools (webhook-only payloads like
+ * `creative_approval` are filtered out at codegen time); this allowlist
+ * + `ENTITY_TO_RESOURCE_KIND` together must cover the full set,
+ * enforced by a test (`test/lib/x-entity-hydration.test.js`) that
+ * imports both.
+ *
+ * @internal Exported for the coverage test; not part of the public API.
+ */
+exports.INTENTIONALLY_UNHYDRATED_ENTITIES = new Set([
+    'vendor_pricing_option', // Scoped to issuing vendor agent; adopters seed pricing context themselves.
+    'governance_plan', // No SDK ResourceKind yet; campaign-governance follow-up.
+    'governance_check', // Transient request envelope; not stored.
+    'event_source', // No SDK ResourceKind yet.
+    'offering', // SI offering catalog; correlation handled by brand-side `offering_token`, not framework hydration.
+    'rights_holder_brand', // Read-through `get_brand_identity`; not separately stored.
+    'advertiser_brand', // Same as above.
+]);
+/**
+ * Per-tool, per-field destination property name for hydrated resources.
+ *
+ * The hydrator's default is to derive the destination from the field name
+ * by stripping the `_id` suffix (e.g. `media_buy_id` → attach as
+ * `params.media_buy`). Three cases need explicit overrides because their
+ * historical attach-fields don't match that convention — adopters already
+ * read these in handler code and a rename would be wire-visible behavior:
+ *
+ *   - `acquire_rights.rights_id` → `params.rights` (NOT `rights_grant`).
+ *     Predates the entity-driven hydrator. Kept for backward-compat.
+ *   - `activate_signal.signal_agent_segment_id` → `params.signal`
+ *     (NOT `signal_agent_segment` — `_id` suffix isn't on the boundary
+ *     the convention strips).
+ *   - `update_rights.rights_id` → `params.rights_grant` (NOT `rights`).
+ *     Diverges from `acquire_rights`'s historical `params.rights` because
+ *     the wire payloads model different things — acquire takes an
+ *     offering selection, update modifies an existing grant.
+ *
+ * Other tools either follow the convention (`update_media_buy`,
+ * `provide_performance_feedback`) or don't currently have hydration
+ * registered (the unmapped `x-entity` skips above).
+ */
+const HYDRATION_ATTACH_FIELD_OVERRIDES = {
+    acquire_rights: { rights_id: 'rights' },
+    activate_signal: { signal_agent_segment_id: 'signal' },
+    update_rights: { rights_id: 'rights_grant' },
+};
+function deriveAttachField(toolName, field) {
+    const override = HYDRATION_ATTACH_FIELD_OVERRIDES[toolName]?.[field];
+    if (override)
+        return override;
+    // Default: strip the `_id` suffix so `media_buy_id` → `media_buy`,
+    // `creative_id` → `creative`, etc. This is the convention every existing
+    // hydration call site followed before the schema-driven refactor.
+    return field.endsWith('_id') ? field.slice(0, -3) : field;
+}
+/**
+ * Schema-driven auto-hydration for a tool's request payload.
+ *
+ * Walks the codegen-derived `TOOL_ENTITY_FIELDS` table for the named tool,
+ * looks up each spec-tagged identifier on `params`, maps the `x-entity`
+ * annotation to a `ResourceKind`, and attaches the resolved record at the
+ * conventional destination field. Replaces the four hand-rolled
+ * `hydrateSingleResource` call sites that hardcoded `(field_name, kind)`
+ * pairs and were vulnerable to a silent break under a future spec rename
+ * (protocol-expert review of #1086 → tracked as #1109).
+ */
+async function hydrateForTool(store, accountId, toolName, params, logger) {
+    if (!store || !accountId || params == null || typeof params !== 'object')
+        return;
+    const fields = entity_hydration_generated_1.TOOL_ENTITY_FIELDS[toolName];
+    if (!fields || fields.length === 0)
+        return;
+    const paramsRecord = params;
+    for (const { field, xEntity } of fields) {
+        const id = paramsRecord[field];
+        if (typeof id !== 'string' || id.length === 0)
+            continue;
+        const kind = exports.ENTITY_TO_RESOURCE_KIND[xEntity];
+        if (!kind)
+            continue; // Unknown entity — graceful skip; don't break unknown verbs.
+        const attachField = deriveAttachField(toolName, field);
+        await hydrateSingleResource(store, accountId, kind, id, attachField, params, logger);
+    }
+}
 /**
  * Extract the buyer's push-notification webhook config from a request body
  * and validate the URL + token against SSRF / replay primitives.
@@ -1806,92 +2366,121 @@ function validatePushNotificationToken(token) {
     }
     return { ok: true };
 }
-function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observability, logger, pushOpts, ctxFor, ctxMetadataStore) {
+function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observability, logger, pushOpts, ctxFor, ctxMetadataStore, mediaBuyStore) {
     const sales = platform.sales;
     if (!sales)
         return undefined;
+    // Core lifecycle methods are optional on the SalesPlatform interface
+    // (#1341) — the per-specialism mapping in `RequiredPlatformsFor<S>`
+    // enforces "you claimed `sales-non-guaranteed`, therefore you must
+    // implement getProducts" at the type level, while specialisms whose
+    // upstream owns bidding (`sales-social`) skip them entirely. The
+    // dispatcher mirrors that with conditional spreads — we don't register
+    // a wire handler when the platform method is absent, so the merge seam
+    // (`opts.mediaBuy.X`) can supply it OR the framework returns
+    // `METHOD_NOT_FOUND` from `tools/list` for the unsupported tool.
     return {
-        getProducts: async (params, ctx) => {
-            const reqCtx = ctxFor(ctx);
-            return projectSync(async () => {
-                const result = await sales.getProducts(params, reqCtx);
-                // Auto-store products: persist each Product's wire shape +
-                // ctx_metadata so subsequent createMediaBuy / updateMediaBuy
-                // calls referencing product_id can hydrate the full Product
-                // automatically (publisher sees `req.packages[i].product`).
-                await autoStoreResources(ctxMetadataStore, reqCtx.account?.id, 'product', result?.products, 'product_id', logger);
-                return result;
-            }, r => r);
-        },
-        createMediaBuy: async (params, ctx) => {
-            const reqCtx = ctxFor(ctx);
-            // Auto-hydrate: walk `params.packages`, attach the full Product object
-            // (including `ctx_metadata`) at `pkg.product`. Publisher reads
-            // `pkg.product.format_ids`, `pkg.product.ctx_metadata?.gam?.ad_unit_ids`
-            // directly — no separate lookup, no boilerplate.
-            await hydratePackagesWithProducts(ctxMetadataStore, reqCtx.account?.id, params?.packages, logger);
-            return projectSync(async () => {
-                const push = extractPushConfig(params, logger, { allowPrivateWebhookUrls: pushOpts.allowPrivateWebhookUrls });
-                const result = await sales.createMediaBuy(params, reqCtx);
-                return routeIfHandoff(taskRegistry, {
-                    tool: 'create_media_buy',
-                    accountId: reqCtx.account.id,
-                    pushNotificationUrl: push.url,
-                    pushNotificationToken: push.token,
-                    emitWebhook: taskWebhookEmit ?? ctx.emitWebhook,
-                    autoEmitCompletion: pushOpts.autoEmitCompletionWebhooks,
-                    observability,
-                    logger,
-                }, result, r => r // identity projection for createMediaBuy
-                );
-            }, r => r);
-        },
-        updateMediaBuy: async (params, ctx) => {
-            const reqCtx = ctxFor(ctx);
-            // `media_buy_id` is required on the wire schema, but `validation: 'off'`
-            // mode skips the schema parse — guard at the seam so platform code can
-            // trust the value rather than re-checking. Also catches buyers calling
-            // with the param missing under an off-spec server config.
-            const { media_buy_id } = params;
-            if (!media_buy_id) {
-                return (0, errors_1.adcpError)('INVALID_REQUEST', {
-                    message: 'update_media_buy requires media_buy_id',
-                    field: 'media_buy_id',
-                });
-            }
-            // Auto-hydrate: attach the full MediaBuy (wire shape + ctx_metadata)
-            // at `req.media_buy`. Publisher reads `req.media_buy.ctx_metadata?.gam`
-            // directly — no separate lookup. Misses are silent; publisher falls
-            // back to its own DB.
-            await hydrateSingleResource(ctxMetadataStore, reqCtx.account?.id, 'media_buy', media_buy_id, 'media_buy', params, logger);
-            return projectSync(async () => {
-                const push = extractPushConfig(params, logger, {
-                    allowPrivateWebhookUrls: pushOpts.allowPrivateWebhookUrls,
-                });
-                const result = await sales.updateMediaBuy(media_buy_id, params, reqCtx);
-                // F12 sync auto-emit. updateMediaBuy is sync-only on the
-                // platform interface (no TaskHandoff arm — spec response
-                // doesn't include Submitted), so we don't route through
-                // routeIfHandoff. Fire-and-forget to keep slowloris webhook
-                // receivers from blocking the sync response.
-                if (pushOpts.autoEmitCompletionWebhooks && push.url) {
-                    const emitOpts = {
-                        tool: 'update_media_buy',
+        ...(sales.getProducts && {
+            getProducts: async (params, ctx) => {
+                const reqCtx = ctxFor(ctx);
+                return projectSync(async () => {
+                    const result = await sales.getProducts(params, reqCtx);
+                    // Auto-store products: persist each Product's wire shape +
+                    // ctx_metadata so subsequent createMediaBuy / updateMediaBuy
+                    // calls referencing product_id can hydrate the full Product
+                    // automatically (publisher sees `req.packages[i].product`).
+                    await autoStoreResources(ctxMetadataStore, reqCtx.account?.id, 'product', result?.products, 'product_id', logger);
+                    return result;
+                }, r => r);
+            },
+        }),
+        ...(sales.createMediaBuy && {
+            createMediaBuy: async (params, ctx) => {
+                const reqCtx = ctxFor(ctx);
+                // Auto-hydrate: walk `params.packages`, attach the full Product object
+                // (including `ctx_metadata`) at `pkg.product`. Publisher reads
+                // `pkg.product.format_ids`, `pkg.product.ctx_metadata?.gam?.ad_unit_ids`
+                // directly — no separate lookup, no boilerplate.
+                await hydratePackagesWithProducts(ctxMetadataStore, reqCtx.account?.id, params?.packages, logger);
+                return projectSync(async () => {
+                    const push = extractPushConfig(params, logger, {
+                        allowPrivateWebhookUrls: pushOpts.allowPrivateWebhookUrls,
+                    });
+                    const result = await sales.createMediaBuy(params, reqCtx);
+                    return routeIfHandoff(taskRegistry, {
+                        tool: 'create_media_buy',
                         accountId: reqCtx.account.id,
                         pushNotificationUrl: push.url,
-                        ...(push.token !== undefined && { pushNotificationToken: push.token }),
+                        pushNotificationToken: push.token,
                         emitWebhook: taskWebhookEmit ?? ctx.emitWebhook,
-                        ...(observability && { observability }),
+                        autoEmitCompletion: pushOpts.autoEmitCompletionWebhooks,
+                        observability,
                         logger,
-                    };
-                    void emitSyncCompletionWebhook(emitOpts, result).catch((err) => {
-                        const msg = err instanceof Error ? err.message : String(err);
-                        logger.warn(`[adcp/decisioning] sync completion webhook background-error: ${msg}`);
+                    }, result, async (r) => {
+                        await persistTargetingOverlayFromCreate(mediaBuyStore, reqCtx.account?.id, params, r, logger);
+                        return r;
+                    });
+                }, r => r);
+            },
+        }),
+        ...(sales.updateMediaBuy && {
+            updateMediaBuy: async (params, ctx) => {
+                const reqCtx = ctxFor(ctx);
+                // `media_buy_id` is required on the wire schema, but `validation: 'off'`
+                // mode skips the schema parse — guard at the seam so platform code can
+                // trust the value rather than re-checking. Also catches buyers calling
+                // with the param missing under an off-spec server config.
+                const { media_buy_id } = params;
+                if (!media_buy_id) {
+                    return (0, errors_1.adcpError)('INVALID_REQUEST', {
+                        message: 'update_media_buy requires media_buy_id',
+                        field: 'media_buy_id',
                     });
                 }
-                return result;
-            }, r => r);
-        },
+                // Auto-hydrate: attach the full MediaBuy (wire shape + ctx_metadata)
+                // at `req.media_buy`. Publisher reads `req.media_buy.ctx_metadata?.gam`
+                // directly — no separate lookup. Misses are silent; publisher falls
+                // back to its own DB. Schema-driven via `x-entity` (#1109).
+                await hydrateForTool(ctxMetadataStore, reqCtx.account?.id, 'update_media_buy', params, logger);
+                return projectSync(async () => {
+                    const push = extractPushConfig(params, logger, {
+                        allowPrivateWebhookUrls: pushOpts.allowPrivateWebhookUrls,
+                    });
+                    const result = await sales.updateMediaBuy(media_buy_id, params, reqCtx);
+                    // Persist optimistically: the platform method returned without
+                    // throwing, so the patch was accepted at the seam. If the
+                    // publisher returned an error envelope on the success path
+                    // (rare but possible — `update_media_buy` can return a Failed
+                    // status arm in the wire schema), the persisted overlay
+                    // diverges from the seller's view of the buy. Adopters who
+                    // need stricter coupling should not return error-shaped
+                    // success arms; the spec's preferred shape is to throw an
+                    // `AdcpError` for genuine failures.
+                    await persistTargetingOverlayFromUpdate(mediaBuyStore, reqCtx.account?.id, media_buy_id, params, logger);
+                    // F12 sync auto-emit. updateMediaBuy is sync-only on the
+                    // platform interface (no TaskHandoff arm — spec response
+                    // doesn't include Submitted), so we don't route through
+                    // routeIfHandoff. Fire-and-forget to keep slowloris webhook
+                    // receivers from blocking the sync response.
+                    if (pushOpts.autoEmitCompletionWebhooks && push.url) {
+                        const emitOpts = {
+                            tool: 'update_media_buy',
+                            accountId: reqCtx.account.id,
+                            pushNotificationUrl: push.url,
+                            ...(push.token !== undefined && { pushNotificationToken: push.token }),
+                            emitWebhook: taskWebhookEmit ?? ctx.emitWebhook,
+                            ...(observability && { observability }),
+                            logger,
+                        };
+                        void emitSyncCompletionWebhook(emitOpts, result).catch((err) => {
+                            const msg = err instanceof Error ? err.message : String(err);
+                            logger.warn(`[adcp/decisioning] sync completion webhook background-error: ${msg}`);
+                        });
+                    }
+                    return result;
+                }, r => r);
+            },
+        }),
         syncCreatives: async (params, ctx) => {
             const reqCtx = ctxFor(ctx);
             const creatives = params.creatives ?? [];
@@ -1915,10 +2504,16 @@ function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observab
                 }, result, rows => ({ creatives: rows.map(normalizeRowErrors) }));
             }, r => r);
         },
-        getMediaBuyDelivery: async (params, ctx) => {
-            const reqCtx = ctxFor(ctx);
-            return projectSync(() => sales.getMediaBuyDelivery(params, reqCtx), actuals => actuals);
-        },
+        ...(sales.getMediaBuyDelivery && {
+            getMediaBuyDelivery: async (params, ctx) => {
+                const reqCtx = ctxFor(ctx);
+                return projectSync(async () => {
+                    const result = await sales.getMediaBuyDelivery(params, reqCtx);
+                    warnIfTruncatedMultiIdResponse('getMediaBuyDelivery', 'media_buy_ids', params.media_buy_ids, result?.media_buy_deliveries, logger);
+                    return result;
+                }, actuals => actuals);
+            },
+        }),
         // Optional methods — return UNSUPPORTED_FEATURE when the platform omits
         // them. Adopters that haven't migrated to the v6 platform interface for
         // these specific tools can still pass raw handlers via opts.mediaBuy
@@ -1937,7 +2532,9 @@ function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observab
                 const reqCtx = ctxFor(ctx);
                 return projectSync(async () => {
                     const result = await sales.getMediaBuys(params, reqCtx);
+                    warnIfTruncatedMultiIdResponse('getMediaBuys', 'media_buy_ids', params.media_buy_ids, result?.media_buys, logger);
                     await autoStoreResources(ctxMetadataStore, reqCtx.account?.id, 'media_buy', result?.media_buys, 'media_buy_id', logger);
+                    await backfillTargetingOverlay(mediaBuyStore, reqCtx.account?.id, result, logger);
                     return result;
                 }, r => r);
             },
@@ -1947,15 +2544,13 @@ function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observab
                 const reqCtx = ctxFor(ctx);
                 // Auto-hydrate `req.media_buy` from the prior createMediaBuy /
                 // getMediaBuys store entry, plus `req.creative` when the buyer
-                // scoped feedback to a specific creative. Both fields are optional
-                // hydration targets — adopters who only care about the feedback
-                // payload itself can ignore them.
-                const accountId = reqCtx.account?.id;
-                await hydrateSingleResource(ctxMetadataStore, accountId, 'media_buy', params.media_buy_id, 'media_buy', params, logger);
-                const creativeId = params.creative_id;
-                if (creativeId) {
-                    await hydrateSingleResource(ctxMetadataStore, accountId, 'creative', creativeId, 'creative', params, logger);
-                }
+                // scoped feedback to a specific creative, plus `req.package`
+                // when scoped to a package. All three are optional hydration
+                // targets — adopters who only care about the feedback payload
+                // itself can ignore them. Schema-driven via `x-entity` (#1109);
+                // package hydration is additive vs the prior hardcoded version
+                // (silent no-op when packages aren't seeded).
+                await hydrateForTool(ctxMetadataStore, reqCtx.account?.id, 'provide_performance_feedback', params, logger);
                 return projectSync(() => sales.providePerformanceFeedback(params, reqCtx), r => r);
             },
         }),
@@ -1968,7 +2563,11 @@ function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observab
         ...(sales.listCreatives && {
             listCreatives: async (params, ctx) => {
                 const reqCtx = ctxFor(ctx);
-                return projectSync(() => sales.listCreatives(params, reqCtx), r => r);
+                return projectSync(async () => {
+                    const result = await sales.listCreatives(params, reqCtx);
+                    warnIfTruncatedMultiIdResponse('listCreatives', 'creative_ids', params.creative_ids, result?.creatives, logger);
+                    return result;
+                }, r => r);
             },
         }),
     };
@@ -2013,14 +2612,31 @@ function buildCreativeHandlers(platform, taskRegistry, taskWebhookEmit, observab
             return projectSync(() => creative.buildCreative(params, reqCtx), ret => projectBuildCreativeReturn(ret));
         },
         previewCreative: async (params, ctx) => {
-            if (!('previewCreative' in creative)) {
+            if (!('previewCreative' in creative) || creative.previewCreative == null) {
                 return (0, errors_1.adcpError)('UNSUPPORTED_FEATURE', {
-                    message: 'preview_creative not supported by this platform',
+                    message: 'preview_creative: this creative platform did not implement previewCreative. ' +
+                        'Add `previewCreative(req, ctx)` to your CreativeBuilderPlatform / CreativeAdServerPlatform literal.',
                 });
             }
             const reqCtx = ctxFor(ctx);
             return projectSync(() => creative.previewCreative(params, reqCtx), preview => preview);
         },
+        // No-account tool — `list_creative_formats` request schema doesn't carry
+        // `account`. The framework's `resolveAccountFromAuth` runs and accepts a
+        // null return; the platform method receives `ctx.account` possibly
+        // undefined per `NoAccountCtx`. Wired identically on both
+        // `CreativeBuilderPlatform` and `CreativeAdServerPlatform`.
+        listCreativeFormats: async (params, ctx) => {
+            if (!('listCreativeFormats' in creative) || creative.listCreativeFormats == null) {
+                return (0, errors_1.adcpError)('UNSUPPORTED_FEATURE', {
+                    message: 'list_creative_formats: this creative platform did not implement listCreativeFormats. ' +
+                        'Add `listCreativeFormats(req, ctx)` to your CreativeBuilderPlatform / CreativeAdServerPlatform literal, ' +
+                        'or delegate via `capabilities.creative_agents`.',
+                });
+            }
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => creative.listCreativeFormats(params, reqCtx), r => r);
+        },
         syncCreatives: async (params, ctx) => {
             const reqCtx = ctxFor(ctx);
             const creatives = params.creatives ?? [];
@@ -2054,7 +2670,11 @@ function buildCreativeHandlers(platform, taskRegistry, taskWebhookEmit, observab
                 });
             }
             const reqCtx = ctxFor(ctx);
-            return projectSync(() => creative.listCreatives(params, reqCtx), r => r);
+            return projectSync(async () => {
+                const result = await creative.listCreatives(params, reqCtx);
+                warnIfTruncatedMultiIdResponse('listCreatives', 'creative_ids', params.creative_ids, result?.creatives, logger);
+                return result;
+            }, r => r);
         },
         getCreativeDelivery: async (params, ctx) => {
             if (!('getCreativeDelivery' in creative)) {
@@ -2063,7 +2683,11 @@ function buildCreativeHandlers(platform, taskRegistry, taskWebhookEmit, observab
                 });
             }
             const reqCtx = ctxFor(ctx);
-            return projectSync(() => creative.getCreativeDelivery(params, reqCtx), r => r);
+            return projectSync(async () => {
+                const result = await creative.getCreativeDelivery(params, reqCtx);
+                warnIfTruncatedMultiIdResponse('getCreativeDelivery', 'creative_ids', params.creative_ids, result?.creative_deliveries, logger);
+                return result;
+            }, r => r);
         },
     };
 }
@@ -2114,6 +2738,10 @@ function buildSignalsHandlers(platform, ctxFor, ctxMetadataStore, logger) {
             const reqCtx = ctxFor(ctx);
             return projectSync(async () => {
                 const result = await signals.getSignals(params, reqCtx);
+                // signal_ids is `SignalID[]` (`{source, data_provider_domain, id}`
+                // objects), not bare strings — but the helper's truncation-detection
+                // is purely length-based, so the object element type is irrelevant.
+                warnIfTruncatedMultiIdResponse('getSignals', 'signal_ids', params.signal_ids, result?.signals, logger);
                 // Auto-store signals so subsequent activate_signal can hydrate
                 // `req.signal` from the publisher's prior catalog entry.
                 await autoStoreResources(ctxMetadataStore, reqCtx.account?.id, 'signal', result?.signals, 'signal_agent_segment_id', logger);
@@ -2125,11 +2753,133 @@ function buildSignalsHandlers(platform, ctxFor, ctxMetadataStore, logger) {
             // Auto-hydrate `req.signal` from the prior getSignals store entry —
             // publisher reads pricing options, agent segment id, ctx_metadata
             // directly without the buyer round-tripping the full signal object.
-            await hydrateSingleResource(ctxMetadataStore, reqCtx.account?.id, 'signal', params.signal_agent_segment_id, 'signal', params, logger);
+            // Schema-driven via `x-entity` (#1109): `signal_agent_segment_id`
+            // carries `x-entity: "signal_activation_id"`, mapped to ResourceKind
+            // `signal`; attached at `params.signal` per the override table.
+            await hydrateForTool(ctxMetadataStore, reqCtx.account?.id, 'activate_signal', params, logger);
             return projectSync(() => signals.activateSignal(params, reqCtx), r => r);
         },
     };
 }
+/**
+ * Adapt `SponsoredIntelligencePlatform` (v6 protocol-keyed shape) onto the v5
+ * `SponsoredIntelligenceHandlers` handler-bag the dispatcher consumes.
+ *
+ * Auto-store on `initiateSession`: stash a session record keyed by
+ * `session_id` under `ResourceKind: 'si_session'`. The framework's
+ * schema-driven hydrator (TOOL_ENTITY_FIELDS for `si_send_message` /
+ * `si_terminate_session`) attaches that record at `params.session` on
+ * subsequent calls so the platform reads transcript context from
+ * `req.session` without manual `ctx.store.get`.
+ *
+ * Hydrate on `sendMessage` / `terminateSession`: schema-driven
+ * `hydrateForTool` reads `params.session_id`, looks up the stored
+ * session, and attaches at `params.session`.
+ */
+function buildSponsoredIntelligenceHandlers(platform, ctxFor, ctxMetadataStore, logger) {
+    const si = platform.sponsoredIntelligence;
+    if (!si)
+        return undefined;
+    return {
+        getOffering: async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(() => si.getOffering(params, reqCtx), r => r);
+        },
+        initiateSession: async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            return projectSync(async () => {
+                const result = await si.initiateSession(params, reqCtx);
+                // Auto-store the session record so subsequent `sendMessage` /
+                // `terminateSession` calls hydrate `req.session` without a
+                // manual lookup. Stored payload preserves the bits the brand
+                // engine needs to resume context across turns: identity
+                // consent, offering scoping, negotiated capabilities,
+                // placement provenance, and any media-buy linkage. The full
+                // request intent is stored alongside so brand handlers can
+                // re-read what the user originally asked for. Production
+                // brand engines that own transcript state in their own
+                // backend can ignore this and read from their own store —
+                // see SponsoredIntelligencePlatform JSDoc.
+                if (ctxMetadataStore && reqCtx.account?.id) {
+                    const sessionId = result?.session_id;
+                    if (typeof sessionId === 'string' && sessionId.length > 0) {
+                        const reqRec = params;
+                        const resRec = result;
+                        const sessionRecord = {
+                            session_id: sessionId,
+                            // Request-side scoping the brand engine needs across turns.
+                            intent: reqRec.intent,
+                            offering_id: reqRec.offering_id,
+                            offering_token: reqRec.offering_token,
+                            placement: reqRec.placement,
+                            media_buy_id: reqRec.media_buy_id,
+                            identity: reqRec.identity,
+                            supported_capabilities: reqRec.supported_capabilities,
+                            // Response-side state.
+                            negotiated_capabilities: resRec.negotiated_capabilities,
+                            session_status: resRec.session_status,
+                            session_ttl_seconds: resRec.session_ttl_seconds,
+                        };
+                        try {
+                            await ctxMetadataStore.setResource(reqCtx.account.id, 'si_session', sessionId, sessionRecord);
+                        }
+                        catch (err) {
+                            const msg = err instanceof Error ? err.message : String(err);
+                            logger.warn(`[adcp/decisioning] auto-store si_session ${sessionId} failed: ${msg}`);
+                        }
+                    }
+                }
+                return result;
+            }, r => r);
+        },
+        sendMessage: async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            // Auto-hydrate `req.session` from the stored si_session record. The
+            // schema-driven hydrator reads `params.session_id` and attaches the
+            // stored session at `params.session` (via the `_id` → strip
+            // convention; `session_id` → `session`).
+            await hydrateForTool(ctxMetadataStore, reqCtx.account?.id, 'si_send_message', params, logger);
+            return projectSync(() => si.sendMessage(params, reqCtx), r => r);
+        },
+        terminateSession: async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            await hydrateForTool(ctxMetadataStore, reqCtx.account?.id, 'si_terminate_session', params, logger);
+            return projectSync(async () => {
+                const result = await si.terminateSession(params, reqCtx);
+                // Persist `acp_handoff` and terminal `session_status` onto the
+                // stored session record so a re-terminate replay (which is
+                // naturally idempotent on `session_id` per the spec) hydrates
+                // the same handoff payload via `req.session` without the
+                // adopter having to remember to write through. Honors the
+                // platform interface JSDoc contract:
+                //   "Re-terminating a closed session MUST return the same
+                //    payload, including any acp_handoff block."
+                if (ctxMetadataStore && reqCtx.account?.id) {
+                    const sessionId = params?.session_id;
+                    if (typeof sessionId === 'string' && sessionId.length > 0) {
+                        const resRec = result;
+                        try {
+                            const existing = await ctxMetadataStore.getEntry(reqCtx.account.id, 'si_session', sessionId);
+                            const merged = {
+                                ...(existing?.resource ?? { session_id: sessionId }),
+                                session_status: resRec.session_status,
+                                acp_handoff: resRec.acp_handoff,
+                                follow_up: resRec.follow_up,
+                                terminated: resRec.terminated,
+                            };
+                            await ctxMetadataStore.setResource(reqCtx.account.id, 'si_session', sessionId, merged);
+                        }
+                        catch (err) {
+                            const msg = err instanceof Error ? err.message : String(err);
+                            logger.warn(`[adcp/decisioning] auto-store si_session ${sessionId} on terminate failed: ${msg}`);
+                        }
+                    }
+                }
+                return result;
+            }, r => r);
+        },
+    };
+}
 function buildBrandRightsHandlers(platform, ctxFor, ctxMetadataStore, logger) {
     const br = platform.brandRights;
     if (!br)
@@ -2159,9 +2909,29 @@ function buildBrandRightsHandlers(platform, ctxFor, ctxMetadataStore, logger) {
             const reqCtx = ctxFor(ctx);
             // Auto-hydrate `req.rights` from the prior getRights catalog entry.
             // Publisher reads selected pricing option + ctx_metadata directly.
-            await hydrateSingleResource(ctxMetadataStore, reqCtx.account?.id, 'rights_grant', params.rights_id, 'rights', params, logger);
+            // Schema-driven via `x-entity` (#1109); destination field stays at
+            // `params.rights` per the override table — historical, predates
+            // the entity-driven hydrator and `updateRights`'s convention of
+            // `params.rights_grant`. Adopters already read this field, so a
+            // rename would be wire-visible behavior.
+            await hydrateForTool(ctxMetadataStore, reqCtx.account?.id, 'acquire_rights', params, logger);
             return projectSync(() => br.acquireRights(params, reqCtx), r => r);
         },
+        // `update_rights` modifies an existing grant. The framework hydrates
+        // the grant record from `req.rights_id` so the implementation reads
+        // the resolved state from `ctx.store` (or as `params.rights_grant`
+        // — see field-name divergence note on `acquireRights` above; this
+        // tool attaches under `rights_grant` because the wire payload has
+        // no `rights` field). Schema-driven via `x-entity` (#1109). Async
+        // delivery — when the change requires rights-holder counter-
+        // signature — rides the buyer's `push_notification_config` webhook;
+        // the immediate response carries `implementation_date: null` to
+        // signal pending state.
+        updateRights: async (params, ctx) => {
+            const reqCtx = ctxFor(ctx);
+            await hydrateForTool(ctxMetadataStore, reqCtx.account?.id, 'update_rights', params, logger);
+            return projectSync(() => br.updateRights(params, reqCtx), r => r);
+        },
     };
 }
 function buildGovernanceHandlers(platform, ctxFor) {
@@ -2288,18 +3058,27 @@ function buildAccountHandlers(platform, ctxFor) {
     // closer to the truth than a fabricated UNSUPPORTED_FEATURE envelope.
     const handlers = {};
     if (accounts.upsert) {
-        handlers.syncAccounts = async (params, _ctx) => {
+        handlers.syncAccounts = async (params, ctx) => {
             const refs = (params.accounts ?? []);
-            return projectSync(() => accounts.upsert(refs), rows => ({ accounts: rows }));
+            const resolveCtx = toResolveCtx(ctx, 'sync_accounts');
+            return projectSync(() => accounts.upsert(refs, resolveCtx), rows => ({ accounts: rows.map(account_1.toWireSyncAccountRow) }));
+        };
+    }
+    if (accounts.syncGovernance) {
+        handlers.syncGovernance = async (params, ctx) => {
+            const entries = params.accounts;
+            const resolveCtx = toResolveCtx(ctx, 'sync_governance');
+            return projectSync(() => accounts.syncGovernance(entries, resolveCtx), rows => ({ accounts: rows.map(account_1.toWireSyncGovernanceRow) }));
         };
     }
     if (accounts.list) {
-        handlers.listAccounts = async (params, _ctx) => {
+        handlers.listAccounts = async (params, ctx) => {
             const filter = params;
+            const resolveCtx = toResolveCtx(ctx, 'list_accounts');
             // Wrap in projectSync so adopter `throw new AdcpError('PERMISSION_DENIED', ...)`
             // from the list impl projects to the structured wire envelope rather
             // than falling through to the framework's `SERVICE_UNAVAILABLE` mapping.
-            return projectSync(() => accounts.list(filter), page => ({
+            return projectSync(() => accounts.list(filter, resolveCtx), page => ({
                 accounts: page.items.map(account_1.toWireAccount),
                 ...(page.nextCursor != null && { next_cursor: page.nextCursor }),
             }));
@@ -2307,10 +3086,7 @@ function buildAccountHandlers(platform, ctxFor) {
     }
     if (accounts.reportUsage) {
         handlers.reportUsage = async (params, ctx) => {
-            const resolveCtx = {
-                ...(ctx.authInfo !== undefined && { authInfo: ctx.authInfo }),
-                toolName: 'report_usage',
-            };
+            const resolveCtx = toResolveCtx(ctx, 'report_usage');
             return projectSync(() => accounts.reportUsage(params, resolveCtx), r => r);
         };
     }
@@ -2320,10 +3096,8 @@ function buildAccountHandlers(platform, ctxFor) {
             // platform method runs. Adopters fronting an upstream platform read
             // tokens / upstream IDs off `ctx.account.ctx_metadata` without
             // having to re-resolve from `params.account`.
-            const resolveCtx = {
-                ...(ctx.authInfo !== undefined && { authInfo: ctx.authInfo }),
-                toolName: 'get_account_financials',
-            };
+            const resolveCtx = toResolveCtx(ctx, 'get_account_financials');
+            refuseInlineAccountIdWhenForbidden(accounts.resolution, params.account);
             const resolved = await accounts.resolve(params.account, resolveCtx);
             if (!resolved) {
                 throw new async_outcome_1.AdcpError('ACCOUNT_NOT_FOUND', {
@@ -2340,11 +3114,19 @@ function buildAccountHandlers(platform, ctxFor) {
 // ────────────────────────────────────────────────────────────
 // Auto-seed helpers (catalog-backed comply sandbox; issue #1091)
 // ────────────────────────────────────────────────────────────
-// Pull the request's account_id from the comply tool input. Sandbox-flagged
-// requests carry it on `input.account.account_id`; non-sandbox traffic is
-// already short-circuited by `complyTest.sandboxGate`, so a missing id here
-// means the adapter fired outside the gated path — drop the write rather
-// than collapse it into a shared namespace.
+// Auto-seed namespace key extractor. Used by both the write side (the
+// `seed.product` / `seed.pricing_option` adapter closures injected
+// inline in the auto-seed wiring) and the read side (`makeAutoSeedBridge`
+// when `ctx.account?.id` is absent — i.e., the framework didn't
+// pre-resolve the account on a custom dispatcher path).
+//
+// Write-side rationale: the adapter cannot reach the framework-resolved
+// `ctx.account.id` (the comply-controller's `ComplyControllerContext`
+// only exposes `{ input }`), and calling `platform.accounts.resolve`
+// here without `authInfo` would let a caller spoof `account.account_id`
+// and write into another tenant's resolved namespace. The architectural
+// fix (widen `ComplyControllerContext` to surface the resolved account)
+// is tracked at #1216 — until then, raw id is the secure choice.
 function readAutoSeedAccountId(input) {
     const account = input.account;
     if (account == null || typeof account !== 'object')