@adcp/sdk 6.6.0 → 6.7.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");
@@ -100,6 +104,61 @@ function normalizeRowErrors(row) {
         return row;
     return { ...row, errors: (0, normalize_errors_1.normalizeErrors)(row.errors) };
 }
+/**
+ * Enforce the documented `'implicit'`-resolution refusal. When a platform
+ * declares `accounts.resolution: 'implicit'`, the framework refuses inline
+ * `account_id` references on the wire — the buyer is expected to call
+ * `sync_accounts` first, then the framework resolves the account from the
+ * authenticated principal on subsequent calls. Documented at
+ * `AccountStore.resolution` in `account.ts`.
+ *
+ * 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 implicit-mode platforms. The brand+operator union arm
+ * is permitted — the strict-reading docstring claim only refuses
+ * `account_id`-shaped references.
+ */
+function refuseImplicitAccountId(resolution, ref) {
+    if (resolution !== 'implicit')
+        return;
+    if ((0, account_1.refAccountId)(ref) === undefined)
+        return;
+    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.',
+    });
+}
+/**
+ * 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 `media_buy_ids[0]` (closes #1342, follow-up
+ * #1399). 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.).
+ */
+function warnIfTruncatedMultiIdResponse(toolName, 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 `media_buy_ids` 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 media_buy_ids — ` +
+        `the platform may be silently truncating to media_buy_ids[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 +166,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 +478,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 +515,15 @@ 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 platforms refuse inline
+                // `account_id` references — buyers call sync_accounts first, then
+                // the framework resolves accounts from the auth principal on
+                // subsequent calls. The brand+operator union arm is permitted
+                // (used during the initial sync_accounts onboarding flow); only
+                // the `{ account_id }` arm is refused. Closes adcp-client#1364.
+                refuseImplicitAccountId(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 +565,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,13 +587,13 @@ 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,
@@ -496,7 +605,7 @@ function createAdcpServerFromPlatform(platform, opts) {
         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);
@@ -511,16 +620,36 @@ function createAdcpServerFromPlatform(platform, opts) {
         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 +659,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 };
@@ -592,7 +724,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 +765,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) {
+                refuseImplicitAccountId(platform.accounts.resolution, ref);
                 try {
                     const resolved = await platform.accounts.resolve(ref, resolveCtx);
                     if (resolved)
@@ -974,9 +1158,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 +1244,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 +1270,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 +1574,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 +1650,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 +1873,132 @@ 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',
+};
+/**
+ * `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.
+    'si_session', // Session lifecycle owned by `SponsoredIntelligencePlatform`.
+    'offering', // SI offering catalog; not stored as ctx-metadata.
+    '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 +2211,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 +2349,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', 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 +2377,9 @@ function buildMediaBuyHandlers(platform, taskRegistry, taskWebhookEmit, observab
                 const reqCtx = ctxFor(ctx);
                 return projectSync(async () => {
                     const result = await sales.getMediaBuys(params, reqCtx);
+                    warnIfTruncatedMultiIdResponse('getMediaBuys', 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 +2389,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);
             },
         }),
@@ -2013,14 +2453,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 ?? [];
@@ -2125,7 +2582,10 @@ 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);
         },
     };
@@ -2159,9 +2619,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 +2768,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 +2796,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 +2806,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');
+            refuseImplicitAccountId(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 +2824,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')