[bokelley]

T10 for #3504 (approved DX plan §5.3 and §6.1 T10): docs. It stacks on #3556 (T9) → #3555 (T8) → #3554 (T7) → … and the rest of the #3504 stack. Review only docs(reporting): reporting-subscription guides, README section, skill and storage paths. It targets main because CI runs only for PRs into main.

What it adds

• README section "Reporting subscriptions (AdCP 3.3, experimental)". It shows the seller block (storage + subscriptions), the buyer calls (subscribe, unsubscribe, accounts.ensure), one line each on storage, grants and what is coming, and links to the guides.
• Guides: docs/guides/REPORTING-SUBSCRIPTIONS-SELLER.md ("Serving reporting subscriptions (seller)") and docs/guides/REPORTING-SUBSCRIPTIONS-BUYER.md ("Subscribing to reports (buyer)").
  • Titles and section headings match the Python SDK's docs/reporting-subscriptions-{seller,buyer}.md, so the anchors line up across SDKs.
  • The content is the TS API as built in T5–T9.
  • Each "arrives in a later beta" item points at today's workaround.
• Skill: skills/reporting-subscriptions/SKILL.md, covering the five buyer calls, the seller block, and §4.1's anti-patterns in do/don't form.
  • skills/build-seller-agent/SKILL.md and CLAUDE.md point at it.
  • check:skill-sync passes. The protocol-managed call-adcp-agent skill is synced from the spec and is not edited.
• syncPrincipal TSDoc. AgentClient/SingleAgentClient already start "Replaces each submitted section. To add a reporting subscription, use client.reporting.subscribe." (T7). This adds the same text to:
  • ADCPMultiAgentClient.syncPrincipal;
  • the generated Agent / AgentCollection.syncPrincipal, through a note table in scripts/generate-types.ts. The note also says the raw call is unguarded. I regenerated and diffed: the output is byte-identical to the committed file apart from the timestamp.

Storage paths updated

The SDK docs now show import { postgresStorage } from '@adcp/reporting-storage' and npx adcp-reporting-storage migrate, where they used to apply the migration constants:

• docs/guides/REPORTING-LEDGER.md: the recommended setup, the row-storage, change-feed, managed-delivery, advanced and notification samples, and the managed subscriptions block, which now shows storage + principal;
• REPORTING-OPERATIONS.md (deployment step 3, row storage, change feed), PRINCIPAL-LIFECYCLE.md (drops durability: 'durable'), REPORTING-STABILITY.md, REPORTING-LEDGER-CUTOVER.md, REPORTING-GCS-MANAGED.md;
• docs/migration-16-to-17.md, docs/migration-reporting-row-storage-alignment.md;
• docs/migration-reporting-storage-package.md: a new old → new table;
• packages/reporting-storage/README.md: the version table replaces the constant-order table;
• the integrated example README in that package.

The DX guide itself is not updated. It is the plan in the spec checkout (.context/dx-reporting-subscriptions.md), which is read-only for this work. Its storage paths should change:

• import { postgresStorage } from '@adcp/sdk/storage/postgres' → import { postgresStorage } from '@adcp/reporting-storage'.
• npx adcp migrate → npx adcp-reporting-storage migrate.

The SDK can never import the storage package, so the command lives in that package's bin. These are owner decision (a).

Deviations from the plan

• Not built. The plan's guides 3–7 (coverage, accounts, migrating, test kit, error reference) are not written; Python has skeletons for them. Accounts are covered in FIRST-CALL-TO-A-SELLER.md (T9). The error and reason codes are referenced from the canonical vectors.
• No llms.txt entry. docs/llms.txt is generated from the schemas, and ci:docs-check still passes.

Package weight

	Packed bytes	Cap
SDK at this PR	26,613,272	26,610,000 → 26,640,000 (comment added)
@adcp/reporting-storage	446,595	450,000 (unchanged)

The two guides and the skill add 3 packed files. docs/guides/** and skills/** ship in the tarball, so the file budget goes up by +3.

Checks

npm run typecheck, lint:boundaries, check:package-size, check:skill-sync, ci:docs-check, Prettier, and the doc and boundary tests.

Refs #3504

🤖 Generated with Claude Code

[aao-secretariat]

Ladon verdict: Approve

Approve — T10 docs commit reviewed, clean.

Scope note: The setup delta/full diffs were empty (0 files) despite ~41,896 additions because this is a 100+ commit stack targeting main. Per the author's instruction, review was scoped to the single T10 docs commit (e1b1fd3, 22 files, +463/-110): two new reporting-subscription guides, the skill, the README section, storage-path doc updates, a codegen TSDoc note, and the package-size budget bump.

What was checked:

• Changeset present and correctly typed patch (docs + TSDoc only, no API-shape change) — satisfies changeset-vs-wire-impact.
• Generated index.generated.ts matches the generate-types.ts note.
• ADCPMultiAgentClient.syncPrincipal "each agent's client applies the raw guard" claim is accurate (delegates to guarded AgentClient.syncPrincipal).
• Both blob/main/ anchors resolve to real headings — doc-link integrity clean.
• Guides internally consistent with the stack's described API.

No Critical/High/Medium findings. Not covered: underlying stack code (T5–T9), out of declared review scope.

Decision path: No critical/high findings (row 1 no). gated_paths is false (row 2 no — the REVIEW_REQUIRED status does not gate because no gated path is touched). high_risk false (rows 3/5 no). No medium findings (rows 4/8 no). No prior decision (row 6 no). No no-auto-approve team match (row 7 no). Falls through to row 9 → approve.

[aao-secretariat]

Ladon verdict: Approve

Approve.

This delta (5 files, 147 lines) hardens two paths atop a prior clean pass. buyer-account-registry.ts refresh() now wraps per-account repairStatus in try/catch with throwIfAborted propagation — the correct shape for a background reconciler (a failed re-read stays pending for the next refresh rather than discarding recorded moves). The degraded-completion behavior is deliberate and tested, and the silent swallow is consistent with the class's logger-free style.

Medium findings

• src/lib/reporting/consumer-runtime.ts:347 — Buyer durability guard fails open and diverges from the shared requireDurable helper (throws only on explicit 'process-local', re-inlines the NODE_ENV test, throws TypeError vs the seller's PlatformConfigError). Documented storage paths always set durability, so the realistic footgun is still caught; recommend consolidating on the shared helper.

Decision rationale: 1 medium finding, no critical/high. high_risk is false, gated_paths is false, no no-auto-approve team match. Prior decision was approve, so no sticky escalation applies. One medium with no escalation trigger falls through to row 9 — approve. Tests cover both changes.

Medium findings

• src/lib/reporting/consumer-runtime.ts:347 — Buyer durability guard fails open; diverges from shared requireDurable helper

[aao-secretariat]

Ladon verdict: Approve

Approve — prior Medium resolved, no new findings.

This is a subsequent review following a prior approve. The developer's delta resolves the previously flagged Medium: the buyer consumer durability guard (src/lib/reporting/consumer-runtime.ts) now fails closed (input.storage.durability !== 'durable'), matching the seller shape at engine.ts:642. durability is made required (new-in-PR field, covered by the reporting-subscription-dx-storage minor changeset), and a new test asserts undeclared storage is refused. The README link change to a blob/main/ URL is correct for the packed README.

No current findings. Decision table: no critical/high (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); no no-auto-approve team match (row 7 n/a); prior decision was approve so no sticky escalation (row 6 n/a). Falls through to row 9 → approve.

Note: review_decision is REVIEW_REQUIRED, but since gated_paths is false, row 2 does not fire and this does not block auto-approve.