fix(decisioning): wire sync_accounts/list_accounts dispatch to AccountStore Protocols (#610)

* fix(decisioning): wire sync_accounts/list_accounts dispatch to AccountStore Protocols

PlatformHandler.sync_accounts and PlatformHandler.list_accounts were
inherited as _not_supported stubs from ADCPHandler — every adopter
implementing AccountStoreUpsert / AccountStoreList saw their account
roster invisible on the wire regardless of what the store declared.

This wires real shims that route through platform.accounts.upsert /
.list with a ResolveContext carrying the caller's verified AuthInfo
and registry-resolved BuyerAgent (same threading AccountStore.resolve
already uses, so adopter impls implementing principal-keyed gates —
e.g. spec BILLING_NOT_PERMITTED_FOR_AGENT — read the principal off
the canonical context).

Wire advertisement: _ACCOUNT_ADVERTISED_TOOLS = {"sync_accounts",
"list_accounts"} unioned into every sales-* entry of
SPECIALISM_TO_ADVERTISED_TOOLS. The per-instance filter at
advertised_tools_for_instance drops the tool when the store doesn't
expose the corresponding optional Protocol method (with a one-line
logger.info breadcrumb on first drop), so adopters who haven't wired
the optional Protocols don't over-advertise.

Defense-in-depth: shims project results through
strip_credentials_from_wire_result on the final envelope so loose
dicts and Pydantic extra='allow' rows can't smuggle
governance_agents[i].authentication or billing_entity.bank past the
typed projections.

Closes #609.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(examples): sales-proposal-mode seller emits spec-shape sync_accounts rows

The example's _SingleTenantAccounts.upsert returned rows shaped as
``{ref, account, operation}`` — a custom layout that worked while the
framework's sync_accounts dispatch was a no_supported stub but trips
schema output validation now that the dispatch actually invokes
accounts.upsert.

Reshape each row to the wire schema per
schemas/cache/account/sync-accounts-response.json:
``{account_id, brand, operator, action, status, ...}``. The framework
wraps the list as ``{"accounts": [...]}``.

Verified end-to-end against the running seller: storyboard runner's
sync_accounts step now passes output validation.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(decisioning): unblock sync_accounts/list_accounts bootstrap on explicit-mode stores

The shims called ``await self._resolve_account(None, tool_ctx)`` purely
to side-effect-stash the registry-resolved buyer-agent on
``ctx.metadata``. For ``AccountStore.resolution == "explicit"`` impls
without a principal/subdomain fallback, that no-ref resolve raised
``ACCOUNT_NOT_FOUND`` — deadlocking the bootstrap path that uses
``sync_accounts`` to populate the store in the first place.

Extract the side-effect into a ``_prime_auth_context`` helper that
runs the buyer-agent registry gate (suspended/blocked rejection still
fires) WITHOUT calling ``AccountStore.resolve``. Use it in both
account-roster shims; ``_resolve_account`` delegates to it for the
buyer-agent stash.

Also:
- Warn on unexpected ``upsert`` / ``list`` return shapes (None, tuple,
  bare string) so adopter contract violations aren't silent — the
  credential scrubber relies on dict-or-list shape.
- Document that the per-tenant handler created by
  ``LazyPlatformRouter`` emits the dropped-tool boot log per (tenant,
  tool) — intentional, since stores can be wired differently per
  tenant.
- Doc nit: ``AccountStoreList.list`` example shows binding ``filter``
  to ``filter_`` to avoid shadowing the builtin in the method body.

Test additions:
- explicit-mode bootstrap regression: shim must NOT call
  ``ExplicitAccounts.resolve(None, ...)`` first.
- unexpected-shape return triggers the new ``logger.warning``.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bokelley

docs/handler-authoring.md

@@ -738,6 +738,113 @@ For the full set of scope invariants — what each field means, how
 cache keys are composed, what leaks if you populate fields wrong — see
 [docs/multi-tenant-contract.md](./multi-tenant-contract.md).
 
+## Account roster: `sync_accounts` and `list_accounts`
+
+Sales-* adopters expose two account-roster tools so buyers can
+declare implicit accounts (`sync_accounts`) or discover explicit ones
+(`list_accounts`). Both dispatch through optional Protocols on
+your `AccountStore`, not through per-specialism platform methods —
+implement them on the same object you use for `AccountStore.resolve`.
+
+```python
+from adcp.decisioning import (
+    AccountStore,
+    DecisioningPlatform,
+    ResolveContext,
+)
+from adcp.decisioning.types import Account, SyncAccountsResultRow
+
+
+class TenantAccountStore:
+    resolution = "explicit"
+
+    def resolve(self, ref, auth_info=None):
+        return self._load(ref["account_id"])
+
+    # Optional — opts your platform into ``sync_accounts``.
+    async def upsert(
+        self,
+        refs: list,
+        ctx: ResolveContext | None = None,
+    ) -> list[SyncAccountsResultRow]:
+        principal = ctx.auth_info.principal if ctx and ctx.auth_info else None
+        return [
+            SyncAccountsResultRow(
+                brand=ref.brand.model_dump(),
+                operator=ref.operator,
+                action="created",
+                status="active",
+                account_id=self._provision(ref, principal),
+            )
+            for ref in refs
+        ]
+
+    # Optional — opts your platform into ``list_accounts``.
+    # Note: the framework calls this with the parameter named ``filter``
+    # (matching the Protocol signature). Bind it to ``filter_`` inside
+    # your impl so you don't shadow the ``filter`` builtin in the
+    # method body.
+    async def list(
+        self,
+        filter: dict | None = None,  # noqa: A002 — Protocol param name
+        ctx: ResolveContext | None = None,
+    ) -> list[Account]:
+        filter_ = filter or {}
+        principal = ctx.auth_info.principal if ctx and ctx.auth_info else None
+        return self._list_for_principal(principal, filter_)
+
+
+class MySeller(DecisioningPlatform):
+    capabilities = ...  # your sales-* claim
+    accounts = TenantAccountStore()
+```
+
+**The framework auto-advertises `sync_accounts` / `list_accounts`
+for every `sales-*` claim.** When your store doesn't expose `upsert`
+or `list`, the per-instance advertisement filter drops the missing
+tool from `tools/list` AND emits a one-line `logger.info` at first
+boot:
+
+```
+PlatformHandler dropped 'sync_accounts' from advertised_tools — platform.accounts
+does not implement 'upsert'. Implement the optional AccountStoreUpsert Protocol
+method (see adcp.decisioning.accounts) to surface this tool on the wire.
+```
+
+If a buyer somehow calls a tool you didn't advertise, the shim
+returns `NotImplementedResponse(supported=False)` — never an
+`AttributeError`.
+
+**Filter shape for `list`.** The framework projects
+`ListAccountsRequest` to a flat dict before calling your store:
+`status` (string, e.g. `"active"`), `sandbox` (bool), and
+`pagination` (`{"max_results": 50, "cursor": "..."}` — already
+`model_dump`-ed, never the typed Pydantic instance). `None` values
+are stripped, so you can pattern-match present-vs-absent without
+explicit `None` checks.
+
+**`ResolveContext` carries the principal.** `ctx.auth_info` is the
+verified credential; `ctx.agent` is the registry-resolved
+`BuyerAgent` when you've wired a `BuyerAgentRegistry` (preferred for
+commercial-relationship gates like
+`BILLING_NOT_PERMITTED_FOR_AGENT`). `ctx.tool_name` is
+`'sync_accounts'` / `'list_accounts'` for audit logs.
+
+**Wire-envelope wrapping is automatic.** Return
+`list[SyncAccountsResultRow]` / `list[Account]` and the framework
+projects each row through `to_wire_sync_accounts_row` /
+`to_wire_account` (write-only credential strip on
+`billing_entity.bank` and `governance_agents[i].authentication`)
+and wraps the result as `{"accounts": [...]}` for the wire. Don't
+build the envelope yourself — the framework already does it, AND
+runs a defense-in-depth credential scrub on the final payload.
+
+For roster-curated stores that reject `sync_accounts` outright (the
+adopter manages accounts out-of-band), see
+`adcp.decisioning.create_roster_account_store`. For multi-tenant
+stores enforcing per-entry tenant isolation, see
+`adcp.decisioning.create_tenant_account_store`.
+
 ## Account modes and mock-mode upstream routing
 
 The framework recognizes three operationally distinct account modes

examples/sales_proposal_mode_seller/src/app.py

@@ -79,7 +79,9 @@ def upsert(
         ctx: Any = None,
     ) -> list[dict[str, Any]]:
         """``sync_accounts`` API. Storyboards call this first to seed
-        the stateful account chain. Returns one result row per ref."""
+        the stateful account chain. Returns one result row per ref in
+        the wire shape per ``schemas/cache/account/sync-accounts-response.json``
+        — the framework wraps the list as ``{"accounts": [...]}``."""
         del ctx
         rows: list[dict[str, Any]] = []
         for ref in refs:
@@ -95,16 +97,13 @@ def upsert(
             account_id = f"acct_{operator}".replace(".", "_")
             rows.append(
                 {
-                    "ref": ref_dict,
-                    "account": {
-                        "account_id": account_id,
-                        "name": f"Account for {domain or operator}",
-                        "status": "active",
-                        "brand": {"domain": domain or "demo.example"},
-                        "operator": operator,
-                        "billing": "operator",
-                    },
-                    "operation": "created",
+                    "account_id": account_id,
+                    "name": f"Account for {domain or operator}",
+                    "brand": {"domain": domain or "demo.example"},
+                    "operator": operator,
+                    "action": "created",
+                    "status": "active",
+                    "billing": "operator",
                 }
             )
         return rows

src/adcp/decisioning/accounts.py

@@ -280,9 +280,25 @@ def list(
     ) -> Awaitable[list[Account[TMeta]]] | list[Account[TMeta]]:
         """Return the accounts visible to the calling principal.
 
-        :param filter: Wire-shape filter object — ``status`` /
-            ``sandbox`` / pagination. Pass-through from the parsed
-            wire request.
+        :param filter: Wire-shape filter dict projected from the parsed
+            ``ListAccountsRequest`` by the framework's
+            :func:`adcp.decisioning.handler._build_list_accounts_filter`.
+            Keys (all optional, omitted when not set on the wire):
+
+            * ``status`` (``str``) — one of ``'active'``,
+              ``'pending_approval'``, ``'rejected'``, ``'payment_required'``,
+              ``'suspended'``, ``'closed'``. Already coerced from the
+              codegen'd Enum to its string ``.value``.
+            * ``sandbox`` (``bool``) — sandbox-account marker.
+            * ``pagination`` (``dict``) — sub-keys are
+              ``max_results: int`` (1–100, default 50) and
+              ``cursor: str`` (opaque, from a prior response). Already
+              ``model_dump(mode='json', exclude_none=True)``-ed; never
+              the typed Pydantic instance.
+
+            The framework strips ``None`` values before invoking, so
+            adopters can pattern-match present-vs-absent without
+            explicit ``None`` checks.
         :param ctx: Per-request context. ``ctx.auth_info`` and
             ``ctx.agent`` carry the caller's principal — adopters
             scope the listing per-principal (e.g., return only