[bokelley]

Guides 5 and 7 of the reporting-subscriptions DX plan (.context/dx-reporting-subscriptions.md §5.3). Stacked on #1776, the top of the stack, because the error reference documents codes from P10–P14 and PR 6. It also lists the account refusals from #1777 (P15), which targets next separately.

Guides 3, 4 and 6 are written in their slices: coverage in #1766, accounts in #1777, testing in #1774 and #1776.

Guide 5: Migrating from account-level reporting_delivery_configs

A four-step handover:

1. Subscribe, scoped to the accounts already served.
2. Read the excluded:overridden periods with reconcile(include_not_owed=True).
3. Hand over with replace_account_configs.
4. Widen the scope to all_authorized_accounts with operator_domains.

The existing anchors are kept: Precedence, Overrides, replace_account_configs. The guide also covers the pre-dispatch SUBSCRIPTION_ID_CLASH check, the once-per-version rule for replace_account_configs, and a pointer to assert_agreement across a handover.

Guide 7: Error reference

New sections beside the frozen error-codes.json table:

• Reconcile issues (values, not exceptions): SUBSCRIPTION_PRINCIPAL_UNAVAILABLE, SUBSCRIPTION_OFFERINGS_UNAVAILABLE, SUBSCRIPTION_ROSTER_UNAVAILABLE, SUBSCRIPTION_ACCOUNT_UNREADABLE, SUBSCRIPTION_LEDGER_UNAVAILABLE, SUBSCRIPTION_ACCOUNT_NOT_COVERED, and coverage input errors.
• Events and receipts: REPORTING_EVENTS_CONFLICT, RECEIPT_WRITE_FAILED, and report.receipts.failed.
• Accounts: ACCOUNT_REVISION_REQUIRED, ACCOUNT_CHANGE_INVALID, ACCOUNT_REQUESTS_UNSUPPORTED (all dispatched=False), and requires_new_account.
• Coverage traces: the input errors of explain and explain_coverage.

Anchor parity

The Python guide anchors, which the TypeScript guides 3–7 should mirror once written:

Guide	File	Sections
3	reporting-subscriptions-coverage.md	the-owed-rules, explaining-a-period, the-trace, comparing-a-buyer-trace-with-a-seller-trace, reason-codes, worked-traces (confirmation-day, cancellation-mid-period, re-grant-gap, timezone-cutover, billing-stub, sticky-resolution, reactivation, dst)
4	accounts-ensure-and-change.md	outcomes, pending-actions-for-humans-and-agents, separate-accounts, money-changes-and-revision, cold-start
5	reporting-subscriptions-migration.md	precedence, overrides, replace_account_configs
6	reporting-subscriptions-testing.md	testing-today, the-test-kit, the-reference-seller
7	reporting-subscriptions-errors.md	reconcile-issues, events-and-receipts, accounts, coverage-traces

Docs only; no code changes.

🤖 Generated with Claude Code

[aao-secretariat]

Ladon verdict: Approve

Approve — docs-only PR adding Guide 5 (migration) and Guide 7 (error reference).

What I checked:

• Reviewer verified every referenced error code, exception class (AccountRequestError, AccountRejected, CoverageInputError), the ReconcileIssue(code, message, account_id, subscription_id) and report.receipts.failed shapes, and explain() KeyError/CoverageInputError raise behavior against the SDK — all accurate.
• No critical/high findings; high_risk: false; gated_paths: false; no author-team gate.

Medium findings (1):

• docs/reporting-subscriptions-migration.md:15 — Migration code example references an undefined subscription variable (NameErrors on copy-paste). Worth a quick fix but non-blocking.

Non-blocking note: The error reference documents client.accounts.change() and its dispatched=False refusal codes, which land in sibling PR #1777 (targeting next separately) — a merge-order coupling, not a code defect.

Decision table: no critical/high (row 1 no), gated_paths false (row 2 no), no deletions (row 3 no), the single medium is not data-loss/schema/infra (row 4 no), high_risk false (row 5 no), no prior escalation (row 6 no), no team gate (row 7 no), only 1 medium (<3, row 8 no) → row 9 approve.

Medium findings

• docs/reporting-subscriptions-migration.md:15 — Migration code example references undefined subscription variable

[aao-secretariat]

Ladon verdict: Comment (human reviewer recommended)

Comment — 2 medium findings on a docs-only PR; a human should take a look before merge.

This PR changes two documentation files only (+62/-3): the reporting-subscriptions error reference and migration guide. The reviewer verified the Reconcile-issues, Events-and-receipts, Receipts, and Coverage-traces sections (and the migration guide) against actual branch code and found them accurate. Two non-blocking medium findings remain:

Medium findings

• docs/reporting-subscriptions-errors.md:50 — Accounts section documents a P15 API surface (client.accounts.change(), AccountRejected.requires_new_account, three ACCOUNT_* codes) that is absent from this branch/release line; per the PR body that surface targets next separately.
• docs/reporting-subscriptions-errors.md:44 — RECEIPT_WRITE_FAILED row claims a recovery attribute that ReportingReconciliationError does not expose.

Both are documentation-accuracy gaps describing behavior/attributes that don't exist on this branch — worth a human fix so adopters aren't misled, but neither is a blocking (critical/high) issue. No high-risk paths, no gated paths, no author-team gate. With exactly 2 medium findings and no escalation trigger this does not meet the 3+ threshold for row 8, but both findings are documentation claiming nonexistent API — surfacing for human attention.

Medium findings

• docs/reporting-subscriptions-errors.md:50 — Accounts section documents API absent from this branch/release line
• docs/reporting-subscriptions-errors.md:44 — RECEIPT_WRITE_FAILED row claims recovery the class does not expose

[aao-secretariat]

Ladon verdict: Approve

Approve — docs-only delta with no outstanding findings.

This PR rewrites two reporting-subscription docs (docs/reporting-subscriptions-errors.md, docs/reporting-subscriptions-migration.md; +52/-3). Both Medium findings from the prior comment run are now resolved:

• RECEIPT_WRITE_FAILED is documented as carrying no recovery, matching ReportingReconciliationError (code/message only, _reconcile.py:91).
• The absent-API "Accounts" content was replaced with Reconcile issues / Events and receipts / Coverage traces sections.

Reviewer verified every documented symbol against the shipped code (ReconcileIssue, ReportingEventConflictError, reconcile issue codes, receipts.failed, explain() error behavior, and the migration doc's dispatch/refusal flow). Docs match the API. No new findings this run.

No blocking or medium findings remain. high_risk=false, gated_paths=false, review_decision=APPROVED, no author-team gate. None of rows 1–8 fire → row 9 approve.

[aao-secretariat]

Ladon verdict: Approve

Approve — docs-only delta across two files, both prior Medium findings resolved.

This is a subsequent review following a prior comment. The developer addressed both previously flagged medium findings:

• The Accounts section documenting the absent account-change API was removed (refusals moved to the accounts slice, #1777).
• The RECEIPT_WRITE_FAILED line now correctly states it carries no recovery, matching ReportingReconciliationError (which exposes only code).

The reviewer verified the new reconcile-issue codes, event/receipt failures, coverage-trace input errors, the ReconcileIssue shape, report.receipts.failed tuple shape, explain()/explain_coverage() error behavior, and the migration guide's pre-dispatch checks against the base checkout — all match code. No new Critical/High/Medium findings.

No blocking findings, gated_paths is false (and review_decision is APPROVED anyway), no high-risk flag, no team gate, zero current findings. Falls through to row 9.

[aao-secretariat]

Ladon verdict: Approve

Approve — docs-only PR, no blocking or medium findings.

This PR changes two documentation files (docs/reporting-subscriptions-errors.md and docs/reporting-subscriptions-migration.md), +52/-3. The reviewer verified every documented symbol, error code, class, field tuple, and method signature against the SDK: ReconcileIssue/ReconcileReport fields, report.receipts.failed tuple shape, reconcile/receipt/event codes, ReportingEventConflictError recovery semantics, CoverageInputError→COVERAGE_INPUT_INVALID, KeyError on unknown subscription, SUBSCRIPTION_ID_CLASH pre-dispatch refusal, and the migration example's surface. All accurate and grounded in the SDK.

These files are not in the adopter-facing behavior-doc set (SKILL.md/AGENTS.md/llms.txt/README.md), no public exports change, so no AGENTS.md handler-table obligation applies. high_risk=false, gated_paths=false, review_decision=APPROVED, no author team gate. Prior decision was approve with no findings; this run also surfaces none.

Decision table: no critical/high (row 1 n/a), no gated-path gap (row 2 n/a), no deletions (row 3), no medium findings (rows 4/5/8 n/a), prior was approve not escalate (row 6 n/a), no team gate (row 7). Falls through to row 9 → approve.

[aao-secretariat]

Ladon verdict: Approve

Approve — documentation-only delta since prior approve.

This PR changes two files (docs/reporting-subscriptions-errors.md, docs/reporting-subscriptions-migration.md): +52/-3. The reviewer verified every documented claim against code — ReconcileIssue/ReconcileReport.definitive, the SUBSCRIPTION_/COVERAGE_INPUT_ codes, CoverageInferError/CoverageInputError, RECEIPT_WRITE_FAILED, ReportingEventConflictError, and explain()'s period forms all exist and match the prose. No code, public-surface, wire, or spec-drift changes; no semver signal implicated.

No blocking findings. No medium findings. high_risk is false; gated_paths is false; review_decision is APPROVED; no no-auto-approve team match. Prior decision was approve with no findings, and none re-surface in this run. Decision table rows 1–8 do not fire → row 9 approve.

[aao-secretariat]

Ladon verdict: Approve

Approve — clean docs-only change verified against base next.

This PR changes two adopter-facing docs files (+52/-3): docs/reporting-subscriptions-errors.md and docs/reporting-subscriptions-migration.md. The reviewer verified every load-bearing doc claim against the code in next — ReconcileIssue field order, report.receipts.failed shape with INSPECTION_FAILED, explain() KeyError on unknown subscription_id, CoverageInputError→COVERAGE_INPUT_INVALID, ReportingEventConflictError recovery=transient, ReportingReconciliationError carrying no recovery, and SUBSCRIPTION_ID_CLASH refused pre-dispatch. All accurate.

No critical/high/medium findings. high_risk is false, gated_paths is false, review_decision is APPROVED, and no no-auto-approve team match. Prior decision was also approve with no findings. No decision-table rows 1–8 fire → row 9 approve.