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>

Author: bokelley

docs/handler-authoring.md

@@ -738,6 +738,108 @@ 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``.
+    async def list(
+        self,
+        filter: dict | None = None,
+        ctx: ResolveContext | None = None,
+    ) -> list[Account]:
+        principal = ctx.auth_info.principal if ctx and ctx.auth_info else None
+        return self._list_for_principal(principal, filter or {})
+
+
+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

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