[bokelley]

T7 for #3504 (approved DX plan, section 2.7 and section 4.1): the buyer write facade and the raw syncPrincipal guard. It stacks on #3553 (T6) → #3552 → #3551 → #3546 → #3545 → #3544 → #3543 → #3542 → #3534 and the rest of the #3504 stack. Review only feat(reporting): buyer write facade and the raw syncPrincipal guard. It targets main because CI runs only for PRs into main.

API

const result = await client.reporting.subscribe(subscription, { registerDestination, acknowledgeCrossOperator });
result.action;               // 'created' | 'updated' | 'unchanged' | 'reactivated'
result.subscriptionVersion;  // chosen by the SDK
await client.reporting.unsubscribe('pacing-hourly');    // 'deactivated': the only deactivation path
await client.reporting.listSubscriptions();
await client.reporting.preview(subscription);           // seller dry run + offeringIds
await client.reporting.replaceSubscriptions(list, { deactivateOmitted: true }); // expert; [] needs deactivateAll
await client.syncPrincipal(raw, undefined, { allowDeactivation: true }); // the raw guard's opt-out

ReportingClient (root export) is a port of the Python SDK's ReportingClient, and client.reporting is available on AgentClient and SingleAgentClient:

• Merge and versioning. It reads get_principal, replaces this subscription_id and keeps every other entry. subscription_version is kept when only active or replace_account_configs change, and bumped when the selector, scope, destination, reconciliation_mode, exclude_account_ids or operator_domains change. A supplied version is validated.

• Pre-dispatch checks (ReportingSubscriptionError, dispatched: false):

  • an implicit scope, an unregistered or inactive destination, and a missing {account_id} on a multi-account scope (INVALID_REQUEST);
  • SUBSCRIPTION_ID_CLASH, from list_accounts;
  • SUBSCRIPTION_OPERATOR_SCOPE_REQUIRED;
  • SUBSCRIPTION_SELECTOR_UNMATCHED, with nearest (offering plus failed attributes), from the advertised offerings.

  The roster and capability checks are best effort: when the client can't read them, they are skipped.

• Write. The write sends expected_configuration_version. On CONFLICT the facade re-reads, re-merges and retries with a fresh key (3 attempts), then throws SUBSCRIPTION_CONFLICT_EXHAUSTED. A transport failure retries the same key and body once. The readback is verified; a mismatch throws SUBSCRIPTION_READBACK_MISMATCH with readback.

• Raw guard. client.syncPrincipal with reporting_subscriptions or reporting_destinations reads the principal once. It refuses, before sending, a deactivation (SUBSCRIPTION_WOULD_DEACTIVATE, including an explicit active: false) or a revocation (DESTINATION_WOULD_REVOKE) unless allowed. Dry runs are not guarded. Neither are the lifecycle helpers, which check what they replace themselves, or storyboard runs, which test the seller. The method's TSDoc now starts "Replaces each submitted section. To add a reporting subscription, use client.reporting.subscribe."

• Error class. ReportingSubscriptionError now accepts a seller's wire code, or a local INVALID_REQUEST (correctable, dispatched: false), as Python's does.

Deviations

• The preview result type is SubscriptionPreviewResult. Python calls it PreviewResult, but the root already exports an unrelated PreviewResult.
• ADCPMultiAgentClient has no reporting. The fleet view (section 2.8) is T11.

Tests

test/lib/reporting-subscription-facade.test.js covers:

• create, unchanged (no write), auto-bump, other entries kept, unsubscribe and reactivate;
• every malformed call refused with nothing sent;
• clash and unmatched-selector refusals from a seller roster and capabilities;
• preview as a dry run;
• conflict exhaustion;
• the raw guard, including allowed, dry-run and untouched sections.

The storyboard suite still passes, because it sends unguarded.

File budget +4 (one dual-format module). The packed-byte cap is raised to 26,610,000 (measured 26,566,153), with a comment.

Checks

npm run typecheck, lint:boundaries, check:package-size, Prettier, and 7,760 tests across reporting, principal, client, server, storyboard and packages/reporting-storage.

Refs #3504

🤖 Generated with Claude Code

[aao-secretariat]

Ladon verdict: Approve

Approve — clean additive T7 slice with 1 medium finding (below the ≥3 threshold).

The buyer write facade client.reporting (reporting-facade.ts, 689 new lines) and the raw syncPrincipal guard are well-structured and correctly wired: the guard is fail-closed (refuses deactivation/revocation by omission unless opted in), retries are bounded (maxAttempts 1–10, roster paging capped at 10, transport retry once with replayable key), AgentClient delegates the guard through SingleAgentClient, lifecycle/storyboard writes correctly pass unguarded, and the minor changeset is appropriate for an additive, experimental (AdCP 3.3) surface. Witness-not-translator, changeset-vs-wire-impact, and transport-client rules all satisfied.

Medium findings

• src/lib/principal/reporting-facade.ts:630 — Facade verify() readback-mismatch throw path is untested (only the lower-level syncReportingSubscriptionsV1 equivalent is covered)

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); the single medium is not data-loss/schema/infra (row 4 n/a); no prior escalation (row 6 n/a); no no-auto-approve team match (row 7 n/a); only 1 medium, below the 3-medium bar (row 8 n/a). Falls through to row 9 → approve. Note: review_decision is REVIEW_REQUIRED, but with gated_paths false that does not gate this PR.

Medium findings

• src/lib/principal/reporting-facade.ts:630 — Facade verify() readback-mismatch throw path is untested

[aao-secretariat]

Ladon verdict: Approve

Approve — clean delta on a subsequent review.

The prior medium finding (src/lib/principal/reporting-facade.ts:630 — verify() readback-mismatch throw path untested) has been resolved by a new facade test covering both throw branches.

The managed.ts changes are improvements: fail-closed authInfo allowlist (SNAPSHOT_AUTH_FIELDS), abort-signal propagation into platformAccounts/platformBuys with per-page throwIfAborted, and journal reporting on authorized_at projection failure. No new blocking or medium findings.

Only a Low note remains (differingPath duplicated verbatim across two files for eager-graph isolation), which is omitted from gating.

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 (rows 4/8 n/a), prior decision was approve so sticky-escalation does not apply (row 6 n/a), no no-auto-approve team match (row 7 n/a). Falls through to row 9 → approve.

The merge-base changed after approval.