[bokelley]

T9 for #3504 (approved DX plan §2.11 and §6.1 T9): the accounts.ensure reshape. It stacks on #3555 (T8) → #3554 (T7) → … and the rest of the #3504 stack. Review only feat(accounts)!: accounts.ensure returns an AccountOutcome and routes to request_account. It targets main because CI runs only for PRs into main.

This is a deliberate breaking return-type change for this release (major changeset, within the SDK 17 beta line).

API

import { formatPendingAction, nextStep } from '@adcp/sdk';

const outcome = await client.accounts.ensure(
  { brand: { domain: 'renault.fr', countries: ['FR'] }, operator: 'wppmedia.fr' },
  { billing: 'operator', currency: 'EUR', timezone: 'Europe/Paris' }
);
switch (outcome.kind) {
  case 'ready':     use(outcome.account_id); break;
  case 'pending':   if (nextStep(outcome) === 'send_human_to_url') show(formatPendingAction(outcome.action)); break;
  case 'ambiguous': await outcome.choose(outcome.candidates[0].account_id); break;
  case 'rejected':  report(outcome.errors); break;
}
for (const moved of await client.accounts.refresh()) { /* outcomes whose state moved */ }
await client.accounts.pending(); // local, no network

Old	New
accounts.ensure(account, options) → ProvisionedAccount	accounts.ensure(account, options) → AccountOutcome
(the same call)	accounts.provision(account, options) → ProvisionedAccount (unchanged behavior; resolveAccount uses it)
none	accounts.refresh(), accounts.pending(), nextStep(), formatPendingAction(), AccountRequestError
none	AccountCapabilities.requestsSupported, EnsureAccountOptions.currency / .timezone, BuyerAccountStorage.list?(scope)

• AccountOutcome is AccountReady | AccountPending | AccountAmbiguous | AccountRejected, discriminated by kind. Wire-style keys (account_id, request_id) match plan §2.11 and Python's field names. pending.action is the generated wire PendingAction, and its TSDoc says to show url to a person and never fetch it.
• Routing.
  • When the capabilities advertise account.requests.supported, ensure calls request_account. Otherwise it calls sync_accounts through the existing provisioning engine.
  • On the sync path, pending_approval with setup maps to pending, and a failed or rejected row maps to rejected.
• Idempotency.
  • A repeat ensure re-reads the open request through list_accounts request_ids instead of opening another.
  • request_account uses a deterministic key, adcp-ensure-<sha256(scope, body, previous)>, as Python does, so registries that share storage replay one request. A new request after a rejection gets a new key.
  • A resolved request publishes the account_id alias for account-scoped tasks.
• Errors. Only a failure to process the call throws. On the request_account path that is AccountRequestError, which carries the wire code, recovery and errors.

Deviations from the plan and from Python

• The sync_accounts path keeps throwing the existing typed errors (AccountSetupRequiredError, AccountNotFoundError, …) when the call itself fails. They already carry the wire code, and changing them would break resolveAccount callers. Python raises AccountRequestError there too.
• outcome.wait?.({ timeout }) is not built. It is optional in the plan's sample, and Python has no equivalent. Use refresh().
• change() / use() are T16.
• provision() is the old method under a new name, kept as the migration path for callers that need the registry record.
• A Python-only guard is not ported. Python refuses require_operator_auth sellers before sync_accounts. TS keeps its existing billing-capability checks.

Tests

test/lib/account-outcomes.test.js (12) covers:

• nextStep across every kind;
• formatPendingAction stripping control and bidi characters, quoting and capping;
• in_review → pending, then a repeat ensure that re-reads without a duplicate, then refresh() → ready with the alias published;
• ambiguous + choose, including a refused non-candidate;
• rejected as a value, with a new key on retry;
• AccountRequestError;
• one key across registries that share storage, and pending() from a fresh registry;
• the sync path: ready, pending with a human URL followed by refresh() → ready, and a failed row as rejected;
• the capability parse.

The existing provisioning suites (buyer-account-registry*, buyer-stable-account-id, sync-accounts-version-guards, version-translation) now call provision(), mechanically. docs/guides/FIRST-CALL-TO-A-SELLER.md and docs/development/BUYER-STORAGE.md show the new outcome.

File budget +4 (one dual-format module). Packed SDK: 26,604,124 bytes, under the inherited 26,610,000 cap.

Checks

npm run typecheck, lint:boundaries, check:package-size, ci:docs-check, Prettier, and 1,059 tests across the account, client, reporting-facade and version-translation suites.

Refs #3504

🤖 Generated with Claude Code

[aao-secretariat]

Ladon verdict: Approve

Approve — scoped review of commit 201e6dc (accounts.ensure → AccountOutcome, routes to request_account).

Verified clean: changeset correctly typed major for the breaking return-type change; capability-gated routing gives 3.2 sellers a fallback to sync_accounts (DR-0033 version pathway satisfied); official clients used throughout; no fabrication beyond documented SDK outcome shapes (witness-not-translator upheld). Idempotency-key derivation, rejection-retry key rotation, read() pagination bound + required accounts guard, knownOutcome/recordRequest alias publishing, and formatPendingAction untrusted-text stripping all confirmed sound.

Medium findings

• src/lib/core/buyer-account-registry.ts:894 — refresh() discards already-persisted request moves on partial failure (sync-pending repairStatus loop throwing leaves persisted moves un-re-reported). Worth a follow-up but non-blocking.

Only a single medium finding, not in data-loss/schema/infra category. No critical/high findings, high_risk is false, gated_paths is false, no author team gate. Falls through decision table rows 1–8 to row 9.

Medium findings

• src/lib/core/buyer-account-registry.ts:894 — refresh() discards already-persisted request moves on partial failure

[aao-secretariat]

Ladon verdict: Approve

Approve — delta review, prior blocking issue resolved, 1 medium finding remaining (below comment threshold).

Prior finding resolved: The earlier Medium (src/lib/core/buyer-account-registry.ts:894 — refresh() discarding already-persisted request moves on partial failure) is fixed correctly. repairStatus now runs in try/catch, re-throws on abort and otherwise continues, leaving the failed account pending, and is covered by a new test. Net improvement over the prior pass.

Medium findings (1):

• src/lib/reporting/consumer-runtime.ts:346 — Consumer durability guard is fail-open (refuses only durability === 'process-local') vs the seller's fail-closed check (requires === 'durable'); a storage wrapper omitting the optional durability field would run non-durable in production. Worth a follow-up but non-blocking.

Changesets are present for the src/lib changes. No critical/high findings and no blockers in the delta.

Decision path: No critical/high (row 1 n/a). gated_paths false (row 2 n/a). high_risk false, no deletions/modifications triggers (rows 3–5 n/a). Prior decision was approve, not escalate (row 6 n/a). No no-auto-approve team match (row 7 n/a). Only 1 medium finding, below the 3-medium threshold (row 8 n/a). Falls through to row 9 → approve.

Medium findings

• src/lib/reporting/consumer-runtime.ts:346 — Consumer durability guard is fail-open vs the seller's fail-closed check

[aao-secretariat]

Ladon verdict: Approve

Approve — prior Medium resolved, no new blocking or Medium findings.

This is a subsequent review following a prior approve. The developer pushed a 52-line delta across 2 files that resolves the prior Medium finding (src/lib/reporting/consumer-runtime.ts:346 — consumer durability guard was fail-open vs the seller's fail-closed check). The fix makes storage.durability required and rewrites the guard to storage !== undefined && durability !== 'durable', now fail-closed and matching the seller's pattern (runtime.ts:134, webhook-emitter.ts:540). A test asserting undefined-durability storage is refused was added. The breaking type change is covered by the PR's declared major changeset on an @experimental reporting surface.

Decision table: no critical/high findings (row 1 n/a); gated_paths false (row 2 n/a); high_risk false (rows 3/5 n/a); no Medium findings at all (rows 4/8 n/a); no no-auto-approve team match (row 7 n/a); prior decision was approve not escalate (row 6 n/a). Falls through to row 9 → approve.

Note: review_decision is REVIEW_REQUIRED, but gated_paths is false, so the hard gate in row 2 does not apply. The deprecated protected-branch rule no longer forces comment/escalate.

No blocking findings. Clean delta that improves durability safety.