@adcp/sdk 6.6.0 → 6.8.0

package/compliance/cache/{3.0.1 → 3.0.5}/universal/storyboard-schema.yaml

@@ -53,6 +53,60 @@
 #     MUST exist in the source tree at build time. Duplicate IDs
 #     across files are a build-time error.)
 #
+# default_agent: string (optional — logical agent key used by multi-agent
+#   storyboard runners to route steps that do not have a unique specialism
+#   claimant in the runtime agents map. Resolved by the runner against the
+#   `agents` option passed to `runStoryboard({ agents: { sales: …, governance: …, … } })`.
+#
+#   Key shape: free-form non-empty string, matched verbatim against the
+#   runtime `agents` map's keys. The spec does NOT constrain the key to the
+#   specialism enum (`sales`, `signals`, `governance`, `creative`, `brand`)
+#   because production multi-agent topologies legitimately fan out per-property
+#   (`nyt_sales`, `wsj_sales`), per-region (`sales_eu`, `sales_us`), or
+#   per-brand-rights-holder. Authors choose the convention that matches their
+#   operator's CI invocation; portability across operators is the author's
+#   concern, not the spec's.
+#
+#   When to set it. Storyboards that exercise cross-domain tools — e.g.,
+#   `sync_creatives`, `list_creative_formats` — do not name a single specialism
+#   the runner can match. The author has the most context for which logical
+#   tenant should receive these calls (usually "wherever the seller is":
+#   `sales`). Encoding `default_agent: sales` once in the YAML beats
+#   re-asserting it on every CI invocation. (Note: `comply_test_controller`
+#   is routed via `prerequisites.controller_seeding`, not this field — the
+#   controller is a back-channel, not a specialism claimant.)
+#
+#   Resolution order (runner contract — see adcp-client#1066, adcp-client#1355):
+#     1. Step-level `agent:` override (if declared on the step).
+#     2. Specialism-claimant match against the runtime agents map (matched
+#        via each agent's `get_adcp_capabilities.supported_protocols`):
+#          - Exactly one agent claims the step's task's specialism → route there.
+#          - Zero claimants → fall through to slot 3.
+#          - Two or more claimants → runner MUST grade the step `unrouted_step`
+#            rather than picking arbitrarily. Multi-claim is an operator-config
+#            error; the storyboard cannot disambiguate it. Slot 3/4 do NOT
+#            rescue this case — silently picking one would mask the misconfig.
+#     3. Storyboard-level `default_agent` (THIS field) resolved against the
+#        runtime agents map. When the field is set but the key is absent from
+#        the map, the runner MUST grade the step `default_agent_unresolved`
+#        and MUST NOT fall through to slot 4 — silent fallback would invisibly
+#        override the storyboard author's encoded intent. Slot 4 fires only
+#        when the storyboard does NOT declare this field.
+#     4. Run-options `default_agent` passed to `runStoryboard({ default_agent })`.
+#        Same key-resolution rule as slot 3: set-but-unmatched grades
+#        `default_agent_unresolved`; unset falls through to slot 5.
+#     5. Fail-fast — runner raises `unrouted_step` and grades the step failed.
+#
+#   Single-agent runs ignore this field entirely — there is no map to resolve
+#   against, every step routes to the only configured agent. Authors SHOULD
+#   still declare it for clarity; multi-agent runners treat it as advisory and
+#   single-agent runners as a no-op.
+#
+#   Validation. The `<key>` MUST be a non-empty string. Validation that the
+#   key resolves to a configured tenant is a runtime concern (per the slot 3
+#   rule above), not a schema concern — the same storyboard runs against
+#   different topologies.)
+#
 # agent:
 #   interaction_model: enum (stateless_transform | stateful_preloaded | stateful_push | stateless_generate | media_buy_seller | marketplace_catalog | owned_signals | si_platform | brand_rights_holder | governance_agent)
 #   capabilities: string[] (AdCP capability flags: supports_transformation, has_creative_library, supports_generation, sells_media, accepts_briefs, supports_guaranteed, supports_non_guaranteed, catalog_signals)
@@ -272,6 +326,54 @@
 #     "prior_step.<step_id>.passed"   → true if the named prior step in the same storyboard passed
 #   Storyboard authors should prefer expressing gating through step ordering when possible.
 #
+# provides_state_for: string | string[] (optional — declares that this step's pass
+#   establishes equivalent state for the named peer step(s) in the same phase. Used
+#   to rescue the cascade-skip default when one of two interchangeable stateful
+#   steps is missing on the agent: e.g., explicit-mode sellers that pre-provision
+#   accounts out-of-band declare `sync_accounts` as missing_tool but expose
+#   `list_accounts` as the canonical alternative — declaring
+#   `provides_state_for: sync_accounts` on `list_accounts` tells the runner that
+#   the substitute's pass satisfies the same downstream state contract.
+#
+#   Grammar parallels `contributes_to`: declared on the substitute step, names
+#   the target peer(s) whose state it provides. The two fields are independent —
+#   `contributes_to` flows branch-set flags into a later `assert_contribution`;
+#   `provides_state_for` waives a peer's missing-tool / missing-test-controller
+#   cascade so downstream stateful steps still run.
+#
+#   Array semantics: `provides_state_for: [A, B]` is ALL-OF — one substitute pass
+#   establishes state for both A and B simultaneously. ANY-OF semantics are not
+#   supported; if a substitute only conditionally satisfies a peer, model it as
+#   two separate substitute steps.
+#
+#   Validation rules (enforced by lint:storyboard-provides-state-for, fail at
+#   parse time):
+#     - Same-phase only. The target step MUST live in the same phase as the
+#       substitute step. Cross-phase substitution is rejected; a cross-phase
+#       state contract belongs in `context_outputs` / `context_inputs`, not
+#       this field.
+#     - Target step must exist in the same phase by `id`.
+#     - Target step MUST declare `stateful: true`. Stateless peers don't
+#       carry a state contract to substitute for.
+#     - Substitute step MUST declare `stateful: true`. A stateless step
+#       cannot establish equivalent state on the agent side.
+#     - Self-references (`provides_state_for: <own_id>`) are rejected.
+#     - Cycles (A→B and B→A in the same phase) are rejected. The peer-graph
+#       per phase MUST be acyclic.
+#
+#   Runner behavior (see runner-output-contract.yaml > skip_result.reasons.peer_substituted):
+#     - When the substitute step passes AND the target peer would otherwise
+#       grade `missing_tool` / `missing_test_controller`, the runner MUST
+#       grade the target peer with skip reason `peer_substituted` (not
+#       `missing_tool`) and MUST NOT cascade `prerequisite_failed` to
+#       downstream stateful steps in subsequent phases.
+#     - When the substitute step itself fails or is skipped, the cascade
+#       proceeds as if `provides_state_for` were absent — the substitute
+#       did not establish the state it claimed.
+#
+#   See adcontextprotocol/adcp#3734 (mechanism rationale) and
+#   adcp-client#1130 (the cascade-skip default this field rescues).
+#
 # context_outputs: array of ContextOutput objects (optional — capture values from
 #   this step's response into the runner's context accumulator so later steps can
 #   reference them via $context.<name>). Each entry:
@@ -575,7 +677,10 @@
 #
 # --- Validation ---
 #
-# check: string (what to validate: "response_schema", "field_present", "field_value",
+# check: string (what to validate: "response_schema", "field_present",
+#                "envelope_field_present" (walks protocol-envelope.json instead of
+#                response_schema_ref — use for top-level envelope fields like `status`),
+#                "field_value",
 #                "field_value_or_absent", "status_code", "http_status", "http_status_in",
 #                "error_code", "on_401_require_header", "resource_equals_agent_url",
 #                "any_of", "refs_resolve", "a2a_submitted_artifact")

package/compliance/cache/{3.0.1 → 3.0.5}/universal/v3-envelope-integrity.yaml

@@ -15,7 +15,9 @@ narrative: |
   docs/building/implementation/task-lifecycle.mdx.
 
   This storyboard documents the machine-check assertion and asserts the canonical v3
-  `status` field is present. The explicit envelope-root field-absence checks
+  `status` field is present using the `envelope_field_present` check type (added in
+  adcp-client#1045), which walks the protocol envelope rather than the inner response
+  schema. The explicit envelope-root field-absence checks
   (asserting task_status and response_status are absent) require `field_absent`
   runner support in @adcp/client — those checks are marked TODO below and are not
   executed until the runner ships that check type. The schema-level constraint
@@ -82,7 +84,7 @@ phases:
         validations:
           - check: response_schema
             description: "Response matches get-adcp-capabilities-response.json schema"
-          - check: field_present
+          - check: envelope_field_present
             path: "status"
             description: "Envelope carries the canonical v3 status field"
           # TODO: restore these as field_absent checks once @adcp/client runner ships

package/dist/lib/adapters/derived-account-store.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Derived `AccountStore` factory for `resolution: 'derived'` single-tenant
+ * agents — there is no `account_id` on the wire and the auth principal alone
+ * identifies the tenant. Most self-hosted broadcasters, retail-media operators
+ * in proxy mode, and creative-only adapters (audiostack, flashtalking) where
+ * every API call is scoped by the buyer's per-request credential.
+ *
+ * Pairs with the existing reference adapters. Pick by asking *who creates the
+ * account?*:
+ * - **Buyer self-onboards via `sync_accounts`** → {@link InMemoryImplicitAccountStore}
+ *   (Shape A, `resolution: 'implicit'`).
+ * - **Upstream OAuth API owns the roster** → {@link createOAuthPassthroughResolver}
+ *   (Shape B, `resolution: 'explicit'`).
+ * - **Publisher ops curates the roster** → {@link createRosterAccountStore}
+ *   (Shape C, `resolution: 'explicit'`).
+ * - **No account concept — auth principal IS the tenant** → `createDerivedAccountStore`
+ *   (this file, Shape D, `resolution: 'derived'`).
+ *
+ * Closes adcp-client#1462. Replaces the ~25–30 LOC of `if (!authInfo.token) throw
+ * AUTH_REQUIRED; return { id: ..., ctx_metadata: { accessToken } }` boilerplate
+ * Shape D adopters write today.
+ *
+ * @see docs/guides/account-resolution.md
+ * @public
+ */
+import type { Account, AccountStore, ResolveContext } from '../server/decisioning/account';
+/**
+ * Options for {@link createDerivedAccountStore}.
+ *
+ * @public
+ */
+export interface DerivedAccountStoreOptions<TCtxMeta = Record<string, unknown>> {
+    /**
+     * Build the singleton account from the request context. Called on every
+     * `resolve()` (no caching — the tenant is per-request because the auth
+     * principal varies). The returned account's `id` is typically a stable
+     * literal (e.g. `'audiostack'`, `'__publisher_wide__'`); single-tenant
+     * adapters have no buyer-supplied account_id to reflect back.
+     *
+     * **DO NOT put credentials in `ctx_metadata`.** See
+     * `docs/guides/CTX-METADATA-SAFETY.md` for the rationale. The wire-strip
+     * protects buyer responses but does NOT protect server-side log lines,
+     * error envelopes, or adopter-generated strings (e.g. `JSON.stringify(account)`
+     * in an error message). Re-derive the bearer from `ctx.authInfo` per
+     * request inside specialism methods instead.
+     *
+     * Adopters MAY omit `authInfo` from the returned `Account` — the framework
+     * auto-attaches the principal from `ctx.authInfo` when absent (matches
+     * Shape A/B/C semantics).
+     */
+    toAccount: (ctx: ResolveContext | undefined) => Account<TCtxMeta>;
+    /**
+     * Skip the `AUTH_REQUIRED` precheck. Defaults to `false` — the factory
+     * throws `AdcpError('AUTH_REQUIRED')` when `ctx.authInfo` is absent or
+     * carries no credential, matching the canonical Shape D pattern (every
+     * call must authenticate).
+     *
+     * Set to `true` for genuinely unauthenticated single-tenant agents (rare —
+     * public format catalogs, signed-request-only agents that authenticate
+     * out-of-band). When `true`, `toAccount` runs unconditionally.
+     *
+     * If you're tempted to set this because tests don't carry `authInfo`,
+     * fix the tests instead — `serve({ authenticate })` should populate
+     * `ctx.authInfo` from your test harness (or use `dispatchTestRequest`
+     * which threads a synthetic principal). The escape hatch is for
+     * production agents that legitimately accept unauthenticated traffic,
+     * not for working around fixture gaps.
+     *
+     * @default false
+     */
+    skipAuthCheck?: boolean;
+}
+/**
+ * Build an `AccountStore<TCtxMeta>` for single-tenant agents whose tenant is
+ * derived from the auth principal alone (no `account_id` on the wire).
+ *
+ * The factory:
+ * 1. Sets `resolution: 'derived'`.
+ * 2. Throws `AdcpError('AUTH_REQUIRED')` when `ctx.authInfo` carries no
+ *    credential (skip with `skipAuthCheck: true`). The check accepts the
+ *    discriminated `credential` shape (preferred) AND the deprecated
+ *    `token` / `clientId` fields populated by pre-#1269 authenticators —
+ *    fail-closed only when none of the three are present.
+ * 3. Calls `toAccount(ctx)` and returns the result. Buyer-supplied
+ *    `AccountReference` is ignored — single-tenant by definition.
+ * 4. Omits `list` / `upsert` — single-tenant adapters have nothing to
+ *    enumerate or write. Adopters who want either compose via spread.
+ *
+ * **When NOT to use this.** If two different auth principals should resolve
+ * to two different `account.id` values, you want Shape B
+ * ({@link createOAuthPassthroughResolver}) or `createTenantStore` — NOT this
+ * factory. Misusing Shape D in a multi-tenant deployment routes every buyer
+ * to the same singleton id and breaks tenant isolation silently (no error,
+ * no log). The factory is single-tenant by design — `toAccount(ctx)` should
+ * return the same `id` for every principal that calls it.
+ *
+ * @example AudioStack-shaped creative adapter:
+ * ```ts
+ * import { createDerivedAccountStore } from '@adcp/sdk/server';
+ *
+ * const accounts = createDerivedAccountStore<AudioStackAccountMeta>({
+ *   toAccount: (ctx) => ({
+ *     id: 'audiostack',
+ *     name: 'AudioStack',
+ *     status: 'active',
+ *     ctx_metadata: {},                     // tokens stay on ctx.authInfo, not here
+ *   }),
+ * });
+ * ```
+ *
+ * @example Single-tenant retail-media proxy with derived display name:
+ * ```ts
+ * const accounts = createDerivedAccountStore<{ tenantId: string }>({
+ *   toAccount: (ctx) => {
+ *     const cred = ctx?.authInfo?.credential;
+ *     const tenantId = cred?.kind === 'oauth' ? cred.client_id
+ *                    : cred?.kind === 'api_key' ? cred.key_id
+ *                    : 'public';
+ *     return {
+ *       id: 'criteo',
+ *       name: `Criteo (${tenantId})`,
+ *       status: 'active',
+ *       ctx_metadata: { tenantId },
+ *     };
+ *   },
+ * });
+ * ```
+ *
+ * @example Compose `upsert` for adapters that ALSO want a buyer-driven
+ * write path (rare for Shape D, but possible):
+ * ```ts
+ * const accounts: AccountStore<MyMeta> = {
+ *   ...createDerivedAccountStore({ toAccount }),
+ *   upsert: async (refs, ctx) => mySync(refs, ctx),
+ * };
+ * ```
+ *
+ * **Buyer-supplied `account_id` is refused at the framework boundary.**
+ * Since adcp-client#1468, the framework throws `AdcpError('INVALID_REQUEST',
+ * { field: 'account.account_id' })` BEFORE reaching this resolver when a
+ * `'derived'`-mode platform receives an inline `account_id` — same shape
+ * as `'implicit'`'s long-standing refusal (#1364), with a single-tenant
+ * message instead of the `sync_accounts`-first guidance. The factory
+ * itself ignores any `account_id` that does reach it (defensive belt +
+ * braces), but adopters can rely on the framework refusal as the
+ * canonical surface. Hand-rolled `'derived'` stores get the same
+ * enforcement automatically.
+ *
+ * @public
+ */
+export declare function createDerivedAccountStore<TCtxMeta = Record<string, unknown>>(options: DerivedAccountStoreOptions<TCtxMeta>): AccountStore<TCtxMeta>;
+//# sourceMappingURL=derived-account-store.d.ts.map

package/dist/lib/adapters/derived-account-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derived-account-store.d.ts","sourceRoot":"","sources":["../../../src/lib/adapters/derived-account-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAG3F;;;;GAIG;AACH,MAAM,WAAW,0BAA0B,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC5E;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,EAAE,CAAC,GAAG,EAAE,cAAc,GAAG,SAAS,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAElE;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC1E,OAAO,EAAE,0BAA0B,CAAC,QAAQ,CAAC,GAC5C,YAAY,CAAC,QAAQ,CAAC,CAgBxB"}

package/dist/lib/adapters/derived-account-store.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * Derived `AccountStore` factory for `resolution: 'derived'` single-tenant
+ * agents — there is no `account_id` on the wire and the auth principal alone
+ * identifies the tenant. Most self-hosted broadcasters, retail-media operators
+ * in proxy mode, and creative-only adapters (audiostack, flashtalking) where
+ * every API call is scoped by the buyer's per-request credential.
+ *
+ * Pairs with the existing reference adapters. Pick by asking *who creates the
+ * account?*:
+ * - **Buyer self-onboards via `sync_accounts`** → {@link InMemoryImplicitAccountStore}
+ *   (Shape A, `resolution: 'implicit'`).
+ * - **Upstream OAuth API owns the roster** → {@link createOAuthPassthroughResolver}
+ *   (Shape B, `resolution: 'explicit'`).
+ * - **Publisher ops curates the roster** → {@link createRosterAccountStore}
+ *   (Shape C, `resolution: 'explicit'`).
+ * - **No account concept — auth principal IS the tenant** → `createDerivedAccountStore`
+ *   (this file, Shape D, `resolution: 'derived'`).
+ *
+ * Closes adcp-client#1462. Replaces the ~25–30 LOC of `if (!authInfo.token) throw
+ * AUTH_REQUIRED; return { id: ..., ctx_metadata: { accessToken } }` boilerplate
+ * Shape D adopters write today.
+ *
+ * @see docs/guides/account-resolution.md
+ * @public
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDerivedAccountStore = createDerivedAccountStore;
+const async_outcome_1 = require("../server/decisioning/async-outcome");
+/**
+ * Build an `AccountStore<TCtxMeta>` for single-tenant agents whose tenant is
+ * derived from the auth principal alone (no `account_id` on the wire).
+ *
+ * The factory:
+ * 1. Sets `resolution: 'derived'`.
+ * 2. Throws `AdcpError('AUTH_REQUIRED')` when `ctx.authInfo` carries no
+ *    credential (skip with `skipAuthCheck: true`). The check accepts the
+ *    discriminated `credential` shape (preferred) AND the deprecated
+ *    `token` / `clientId` fields populated by pre-#1269 authenticators —
+ *    fail-closed only when none of the three are present.
+ * 3. Calls `toAccount(ctx)` and returns the result. Buyer-supplied
+ *    `AccountReference` is ignored — single-tenant by definition.
+ * 4. Omits `list` / `upsert` — single-tenant adapters have nothing to
+ *    enumerate or write. Adopters who want either compose via spread.
+ *
+ * **When NOT to use this.** If two different auth principals should resolve
+ * to two different `account.id` values, you want Shape B
+ * ({@link createOAuthPassthroughResolver}) or `createTenantStore` — NOT this
+ * factory. Misusing Shape D in a multi-tenant deployment routes every buyer
+ * to the same singleton id and breaks tenant isolation silently (no error,
+ * no log). The factory is single-tenant by design — `toAccount(ctx)` should
+ * return the same `id` for every principal that calls it.
+ *
+ * @example AudioStack-shaped creative adapter:
+ * ```ts
+ * import { createDerivedAccountStore } from '@adcp/sdk/server';
+ *
+ * const accounts = createDerivedAccountStore<AudioStackAccountMeta>({
+ *   toAccount: (ctx) => ({
+ *     id: 'audiostack',
+ *     name: 'AudioStack',
+ *     status: 'active',
+ *     ctx_metadata: {},                     // tokens stay on ctx.authInfo, not here
+ *   }),
+ * });
+ * ```
+ *
+ * @example Single-tenant retail-media proxy with derived display name:
+ * ```ts
+ * const accounts = createDerivedAccountStore<{ tenantId: string }>({
+ *   toAccount: (ctx) => {
+ *     const cred = ctx?.authInfo?.credential;
+ *     const tenantId = cred?.kind === 'oauth' ? cred.client_id
+ *                    : cred?.kind === 'api_key' ? cred.key_id
+ *                    : 'public';
+ *     return {
+ *       id: 'criteo',
+ *       name: `Criteo (${tenantId})`,
+ *       status: 'active',
+ *       ctx_metadata: { tenantId },
+ *     };
+ *   },
+ * });
+ * ```
+ *
+ * @example Compose `upsert` for adapters that ALSO want a buyer-driven
+ * write path (rare for Shape D, but possible):
+ * ```ts
+ * const accounts: AccountStore<MyMeta> = {
+ *   ...createDerivedAccountStore({ toAccount }),
+ *   upsert: async (refs, ctx) => mySync(refs, ctx),
+ * };
+ * ```
+ *
+ * **Buyer-supplied `account_id` is refused at the framework boundary.**
+ * Since adcp-client#1468, the framework throws `AdcpError('INVALID_REQUEST',
+ * { field: 'account.account_id' })` BEFORE reaching this resolver when a
+ * `'derived'`-mode platform receives an inline `account_id` — same shape
+ * as `'implicit'`'s long-standing refusal (#1364), with a single-tenant
+ * message instead of the `sync_accounts`-first guidance. The factory
+ * itself ignores any `account_id` that does reach it (defensive belt +
+ * braces), but adopters can rely on the framework refusal as the
+ * canonical surface. Hand-rolled `'derived'` stores get the same
+ * enforcement automatically.
+ *
+ * @public
+ */
+function createDerivedAccountStore(options) {
+    const skipAuthCheck = options.skipAuthCheck ?? false;
+    return {
+        resolution: 'derived',
+        async resolve(_ref, ctx) {
+            if (!skipAuthCheck && !hasAuthSignal(ctx)) {
+                throw new async_outcome_1.AdcpError('AUTH_REQUIRED', {
+                    message: 'Single-tenant agent requires an authenticated principal; no credential on ctx.authInfo.',
+                    recovery: 'correctable',
+                });
+            }
+            return options.toAccount(ctx);
+        },
+    };
+}
+/**
+ * True when `ctx.authInfo` carries any usable credential signal — the
+ * discriminated `credential` shape (preferred, post-#1269) OR the deprecated
+ * `token` / `clientId` fields still populated by pre-Stage-3 authenticators
+ * during the N+1 deprecation window. Fail-closed only when none are present.
+ */
+function hasAuthSignal(ctx) {
+    const authInfo = ctx?.authInfo;
+    if (!authInfo)
+        return false;
+    return authInfo.credential !== undefined || authInfo.token !== undefined || authInfo.clientId !== undefined;
+}
+//# sourceMappingURL=derived-account-store.js.map

package/dist/lib/adapters/derived-account-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derived-account-store.js","sourceRoot":"","sources":["../../../src/lib/adapters/derived-account-store.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;;AAoIH,8DAkBC;AAlJD,uEAAgE;AAkDhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AACH,SAAgB,yBAAyB,CACvC,OAA6C;IAE7C,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,KAAK,CAAC;IAErD,OAAO;QACL,UAAU,EAAE,SAAS;QAErB,KAAK,CAAC,OAAO,CAAC,IAAkC,EAAE,GAAoB;YACpE,IAAI,CAAC,aAAa,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;gBAC1C,MAAM,IAAI,yBAAS,CAAC,eAAe,EAAE;oBACnC,OAAO,EAAE,yFAAyF;oBAClG,QAAQ,EAAE,aAAa;iBACxB,CAAC,CAAC;YACL,CAAC;YACD,OAAO,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QAChC,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,aAAa,CAAC,GAA+B;IACpD,MAAM,QAAQ,GAAG,GAAG,EAAE,QAAQ,CAAC;IAC/B,IAAI,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5B,OAAO,QAAQ,CAAC,UAAU,KAAK,SAAS,IAAI,QAAQ,CAAC,KAAK,KAAK,SAAS,IAAI,QAAQ,CAAC,QAAQ,KAAK,SAAS,CAAC;AAC9G,CAAC"}

package/dist/lib/adapters/implicit-account-store.d.ts

@@ -0,0 +1,172 @@
+/**
+ * InMemoryImplicitAccountStore
+ *
+ * Reference implementation of `AccountStore` for `resolution: 'implicit'`
+ * platforms. Platforms using this resolution mode require buyers to call
+ * `sync_accounts` before any tool that needs tenant context; subsequent
+ * requests resolve the account from the caller's auth principal rather
+ * than from an inline `ext.account_ref`.
+ *
+ * Use this in tests and as a copy-and-adapt starting point for durable
+ * implementations. See `docs/guides/account-resolution.md` for key
+ * derivation guidance, error contracts, and TTL recommendations.
+ *
+ * **Picking an AccountStore?** Four reference shapes by *who creates the
+ * account*:
+ * - **Buyer self-onboards via `sync_accounts`** → `InMemoryImplicitAccountStore`
+ *   (this file, Shape A).
+ * - **Upstream OAuth API owns the roster** → `createOAuthPassthroughResolver`
+ *   (Shape B, returns just `resolve`).
+ * - **Publisher ops curates the roster** → `createRosterAccountStore`
+ *   (Shape C, complete AccountStore).
+ * - **No account concept — auth principal IS the tenant** → `createDerivedAccountStore`
+ *   (Shape D, `resolution: 'derived'`).
+ *
+ * @see docs/guides/account-resolution.md
+ * @public
+ */
+import type { AccountReference } from '../types/tools.generated';
+import type { Account, AccountStore, ResolvedAuthInfo, ResolveContext, SyncAccountsResultRow } from '../server/decisioning';
+/**
+ * Default key-extraction function for the auth-principal→account mapping.
+ *
+ * Canonical choices by credential kind:
+ * - `'oauth'`   → `oauth:<client_id>`   (OAuth 2.0 client identity; stable across token rotations)
+ * - `'api_key'` → `api_key:<key_id>`   (API-key identity; stable until key is revoked)
+ * - `'http_sig'`→ `http_sig:<agent_url>` (verified caller URL; the most durable identity)
+ *
+ * Adopters who key on `authInfo.sub` or `authInfo.extra` instead MUST
+ * document that choice — those fields are grant-specific and may not be
+ * stable across credential rotations.
+ */
+export declare function defaultImplicitKeyFn(authInfo: ResolvedAuthInfo): string | undefined;
+/**
+ * Constructor options for `InMemoryImplicitAccountStore`.
+ * @public
+ */
+export interface ImplicitAccountStoreOptions<TCtxMeta = Record<string, unknown>> {
+    /**
+     * Convert a buyer-supplied `AccountReference` (from `sync_accounts`) to the
+     * seller's `Account<TCtxMeta>`. Called once per ref in `upsert()`.
+     *
+     * **Default:** builds a synthetic account from the ref fields. Suitable
+     * for tests; replace for production (call your platform's account-lookup
+     * or account-creation API here).
+     */
+    buildAccount?: (ref: AccountReference, ctx?: ResolveContext) => Account<TCtxMeta> | Promise<Account<TCtxMeta>>;
+    /**
+     * Extract the principal key from `ResolvedAuthInfo`. The returned string
+     * is the lookup key for the `authInfo → accounts` mapping.
+     *
+     * **Default:** `defaultImplicitKeyFn` — uses `credential.client_id`
+     * (oauth), `credential.key_id` (api_key), or `credential.agent_url`
+     * (http_sig). Stable across token rotations within the same credential
+     * kind.
+     *
+     * Override when your platform keys on a custom claim (e.g., a
+     * `sub`-derived tenant ID in `authInfo.extra`).
+     */
+    keyFn?: (authInfo: ResolvedAuthInfo) => string | undefined;
+    /**
+     * Sync-linkage TTL in milliseconds. Entries stored by `upsert()` expire
+     * after this duration; `resolve()` returns `null` (→ `ACCOUNT_NOT_FOUND`)
+     * for expired entries, prompting the buyer to call `sync_accounts` again.
+     *
+     * **Default:** `86_400_000` (24 hours). Align with your platform's session
+     * or token lifetime; longer TTLs risk serving stale account state.
+     *
+     * Distinct from `AccountStore.refreshToken` — that refreshes the upstream
+     * OAuth token mid-request. This TTL governs how long the sync-linkage
+     * itself is valid before a fresh `sync_accounts` is required.
+     */
+    ttlMs?: number;
+}
+/**
+ * In-memory `AccountStore` for `resolution: 'implicit'` platforms.
+ *
+ * Wire contract:
+ * 1. Buyer calls `sync_accounts` → framework calls `upsert()` → store records
+ *    `authKey → accounts[]`.
+ * 2. Buyer calls any tool (e.g. `create_media_buy`) without `ext.account_ref`
+ *    → framework calls `resolve(undefined, ctx)` → store looks up by `authKey`.
+ * 3. If no prior sync: `resolve()` returns `null` → framework emits
+ *    `ACCOUNT_NOT_FOUND`. Do NOT return `AUTH_REQUIRED` — that signals
+ *    missing credentials, not a missing pre-sync.
+ *
+ * This class is intentionally minimal. Copy-and-adapt for durable stores
+ * (Postgres, Redis); see `docs/guides/account-resolution.md` for the DDL
+ * reference and the key-derivation rationale.
+ *
+ * @example
+ * ```ts
+ * import { InMemoryImplicitAccountStore } from '@adcp/sdk/server';
+ *
+ * const accountStore = new InMemoryImplicitAccountStore({
+ *   buildAccount: async (ref, ctx) => {
+ *     const upstream = await myPlatform.findOrCreate(ref, ctx?.authInfo);
+ *     return {
+ *       id: upstream.id,
+ *       name: upstream.name,
+ *       status: 'active',
+ *       ctx_metadata: { upstreamId: upstream.id },
+ *     };
+ *   },
+ * });
+ *
+ * // Wire into createAdcpServer:
+ * createAdcpServer({ accounts: accountStore, ... });
+ * ```
+ *
+ * @public
+ */
+export declare class InMemoryImplicitAccountStore<TCtxMeta = Record<string, unknown>> implements AccountStore<TCtxMeta> {
+    readonly resolution: "implicit";
+    private _store;
+    private _keyFn;
+    private _ttlMs;
+    private _buildAccount;
+    constructor(options?: ImplicitAccountStoreOptions<TCtxMeta>);
+    /**
+     * Resolve the caller's account from the auth-principal→account mapping
+     * populated by a prior `sync_accounts` call.
+     *
+     * Returns `null` (→ `ACCOUNT_NOT_FOUND`) when:
+     * - No prior `sync_accounts` was called for this principal
+     * - The stored entry has exceeded `ttlMs`
+     * - `ctx.authInfo` is absent or carries no extractable key
+     *
+     * **Multi-account note.** When a buyer synced multiple refs in one
+     * `sync_accounts` call, this implementation returns the _first_ stored
+     * account. If your platform requires per-request account disambiguation
+     * (e.g., different brands on the same buyer), switch to `'explicit'` mode
+     * so buyers pass `ext.account_ref` on each request, or override `keyFn`
+     * to encode the brand into the key.
+     */
+    resolve(_ref: AccountReference | undefined, ctx?: ResolveContext): Promise<Account<TCtxMeta> | null>;
+    /**
+     * Process a `sync_accounts` payload: build accounts from refs and store
+     * them under the caller's auth key.
+     *
+     * The auth key is extracted from `ctx.authInfo` via `keyFn`. When the
+     * key cannot be derived (no credential or unrecognized credential kind),
+     * all refs are returned as `SYNC_FAILED` rows — a silent-success-then-
+     * mystery-failure sequence is worse than an explicit error. Check your
+     * `authenticate` callback and `keyFn` if you see this error.
+     *
+     * When `ctx.authInfo` is absent (unauthenticated call), all refs fail
+     * with `UNAUTHENTICATED`. Your `authenticate` callback in
+     * `serve({ authenticate })` should reject unauthenticated requests before
+     * reaching this method.
+     */
+    upsert(refs: AccountReference[], ctx?: ResolveContext): Promise<SyncAccountsResultRow[]>;
+    /** Remove all stored sync linkages. */
+    clear(): void;
+    /**
+     * Return the auth key that would be derived from `authInfo`.
+     * Useful in tests to assert that a specific principal's linkage was stored.
+     */
+    authKey(authInfo: ResolvedAuthInfo): string | undefined;
+    /** Return the number of principal → accounts linkages currently stored. */
+    get size(): number;
+}
+//# sourceMappingURL=implicit-account-store.d.ts.map

package/dist/lib/adapters/implicit-account-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"implicit-account-store.d.ts","sourceRoot":"","sources":["../../../src/lib/adapters/implicit-account-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAkB,MAAM,0BAA0B,CAAC;AACjF,OAAO,KAAK,EACV,OAAO,EACP,YAAY,EAEZ,gBAAgB,EAChB,cAAc,EACd,qBAAqB,EACtB,MAAM,uBAAuB,CAAC;AAM/B;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS,CAWnF;AAiBD;;;GAGG;AACH,MAAM,WAAW,2BAA2B,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC7E;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,EAAE,GAAG,CAAC,EAAE,cAAc,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAE/G;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,MAAM,GAAG,SAAS,CAAC;IAE3D;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAyCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAAa,4BAA4B,CAAC,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,YAAW,YAAY,CAAC,QAAQ,CAAC;IAC7G,QAAQ,CAAC,UAAU,EAAG,UAAU,CAAU;IAE1C,OAAO,CAAC,MAAM,CAA4C;IAC1D,OAAO,CAAC,MAAM,CAAqD;IACnE,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,aAAa,CAG+B;gBAExC,OAAO,CAAC,EAAE,2BAA2B,CAAC,QAAQ,CAAC;IAQ3D;;;;;;;;;;;;;;;OAeG;IACG,OAAO,CAAC,IAAI,EAAE,gBAAgB,GAAG,SAAS,EAAE,GAAG,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,IAAI,CAAC;IAc1G;;;;;;;;;;;;;;OAcG;IACG,MAAM,CAAC,IAAI,EAAE,gBAAgB,EAAE,EAAE,GAAG,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAqH9F,uCAAuC;IACvC,KAAK,IAAI,IAAI;IAIb;;;OAGG;IACH,OAAO,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,GAAG,SAAS;IAIvD,2EAA2E;IAC3E,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}