[bokelley]

T8 for #3504 (approved DX plan §2.4 and §6.1 T8, owner decision (a)): the storage facade. It stacks on #3554 (T7) → #3553 → #3552 → #3551 → #3546 → … and the rest of the #3504 stack. Review only feat(reporting): one storage decision with versioned migrations. It targets main because CI runs only for PRs into main.

What a seller writes now

import { createReliableReportingService } from '@adcp/sdk/reporting/service';
import { postgresStorage } from '@adcp/reporting-storage'; // memoryStorage() from '@adcp/sdk/storage' in development

const storage = postgresStorage({ pool, acknowledgeIsolatedDatabase: true });
await storage.checkSchema(); // REPORTING_SCHEMA_BEHIND: run "npx adcp-reporting-storage migrate" (pending: …)
const reporting = createReliableReportingService({
  storage, // was: store
  /* producer config */
  subscriptions: { principal: { agentUrl, notifications, resolvePrincipal }, configure }, // principals is now optional
});
const server = createAdcpServerFromPlatform(reporting.install(platform), { protocol: reporting.principals.protocol });

npx adcp-reporting-storage migrate [--database-url URL] [--schema NAME] [--status | --dry-run]

API

• @adcp/sdk/storage (new subpath; exports and typesVersions; +8 files in the budget):
  • memoryStorage({ now? }) returns a ReportingStorage: durability, ledger, principals, subscriptions, consumer, checkSchema(), close().
  • Also exports developmentEnvironment(), requireDurable(), isReportingStorage() and DEVELOPMENT_ENVIRONMENTS.
  • The in-memory ledger the SDK tests used is now the shipped memoryStorage().ledger. test/helpers/memory-reporting-ledger-store.js re-exports it, so the existing ledger suites now exercise it.
• @adcp/reporting-storage:
  • postgresStorage({ pool, acknowledgeIsolatedDatabase?, ledger?, namespace? }) returns a PostgresReportingStorage (adds pool and migrations).
  • Versioned migrations: migrations(), migrate(pool, { dryRun }), migrationStatus, pendingMigrations, appliedMigrations, describeMigrations, MIGRATE_COMMAND.
  • The new bin/adcp-reporting-storage.js provides the adcp-reporting-storage command. The package had no bin before; the command is named after the package.
• Migrations 0001–0008: adcp_state, reporting_ledger, reporting_ledger_finality_fence (stopped-worker), reporting_row_storage, reporting_ledger_changes, reporting_managed_delivery, reporting_object_writes, reporting_consumer.
  • Each runs in its own transaction under pg_advisory_xact_lock(hashtext('adcp.reporting.schema'), hashtext(current_schema())).
  • Each is recorded in adcp_schema_migrations, the same table and lock Python's python -m adcp migrate uses.
  • Their statements are the existing idempotent constants, so a schema set up by hand migrates cleanly.
  • REPORTING_LEDGER_MIGRATION, REPORTING_LEDGER_FINALITY_WRITER_FENCE_MIGRATION, REPORTING_ROW_STORAGE_MIGRATION, REPORTING_LEDGER_CHANGES_MIGRATION, REPORTING_MANAGED_DELIVERY_MIGRATION and REPORTING_OBJECT_WRITE*_MIGRATION are @deprecated re-exports for one beta.
• Service:
  • createReliableReportingService({ storage }). store is optional, and passing both, or neither, is refused.
  • Process-local storage outside NODE_ENV=test|development throws REPORTING_STORAGE_NOT_DURABLE.
  • The first runCycle runs checkSchema() once. A failed check is retried.
  • New service.storage and service.principals.
• Managed block:
  • stateStore defaults to storage.subscriptions.
  • principals is optional: subscriptions.principal (the lifecycle options minus store and reportingSubscriptions) builds the runtime over storage.principals.
• Production service and consumer: createPostgresReliableReportingProductionService({ storage }) replaces db, defaults the managed block to the storage, and awaits checkSchema(). createReliableReportingConsumerV1({ storage }) uses storage.consumer.
• Durability is intrinsic:
  • AdcpStateStore.durability is declared by the store: InMemoryStateStore is process-local and PostgresStateStore is durable. createSessionedStore propagates it.
  • The durability option of createPrincipalStateStore and createReportingSubscriptionEngineStateStoreV1 is @deprecated. A value that agrees with the store is accepted. A contradicting value is refused (REPORTING_STORAGE_NOT_DURABLE on the engine store). A custom store that declares nothing keeps the caller's value.

Deviations from the plan

• Paths (owner decision (a)).
  • postgresStorage lives in @adcp/reporting-storage, not @adcp/sdk/storage/postgres.
  • The command is npx adcp-reporting-storage migrate, not npx adcp migrate, because the SDK may never import the storage package.
  • The DX guide in the spec checkout is read-only. The SDK docs get the new paths in T10.
• Migrations are versioned entries, not .sql files. Each entry's SQL is the existing constant, so every statement lives in one place, the same reason Python uses -- include:.
• No startup hook on a request-only host. The service checks the schema before its first cycle. A host that serves requests before running a cycle should await storage.checkSchema() at boot. The production service awaits it at construction.
• Managed delivery for memory storage. Managed delivery's tables live in the Postgres storage's schema and migrations. The production service builds the managed store over storage.pool, because it needs the service's notification port and retention. memoryStorage() has no managed delivery, because TS has no in-memory managed-delivery store.
• Production notification tables. The production service's notification outbox and activity tables have configurable names, so they stay on setup.migrations / applyMigrations.
• Not ported from Python. Python's staging/seals source stores have no TS counterpart.
• New for buyers. The buyer consumer state (consumer) is new relative to Python's ReportingStorage.
• subscriptions.principal is TS-specific. TS principal runtimes also need notifications and agentUrl, which Python's PrincipalService(store) does not, so the block carries the lifecycle options.

Tests

• test/lib/reporting-storage-facade.test.js (11) covers:
  • the subpath;
  • memoryStorage shape;
  • the production refusal;
  • lease-fenced memory consumer;
  • intrinsic and deprecated durability;
  • storage vs store;
  • the schema check run once and retried;
  • subscriptions.principal rules;
  • the consumer taking storage.
• reporting-subscription-managed.test.js gains a storage world. The service builds the runtime, and principal records, engine state and obligations land in the storage.
• packages/reporting-storage/test/reporting-storage-migrations.test.js covers order, the behind-schema refusal (it never writes), and the CLI's arguments, --status and --dry-run.
• New PostgreSQL suite. packages/reporting-storage/test/reporting-storage-facade-pg.test.js covers:
  • the CLI migrating a fresh schema;
  • --status and --dry-run;
  • a re-run reporting "up to date";
  • every store round-tripping;
  • concurrent runners applying each version once;
  • a schema set up from the deprecated constants migrating with rows kept.

Package weight

• SDK: 26,587,751 packed bytes, under the inherited 26,610,000 cap, which is unchanged.
• Storage package: 445,755 packed bytes. Its file budget is 125 → 140 (+13: three modules and the bin), with a comment.

Checks

npm run typecheck, the storage typecheck, lint:boundaries, check:package-size, Prettier, 964 tests across reporting, principal, persistent-notification and state-store, and the packages/reporting-storage suite (PostgreSQL suites run in CI).

Refs #3504

🤖 Generated with Claude Code

[aao-secretariat]

Ladon verdict: Approve

Approve — one medium finding, no blocking issues.

The reviewer isolated the in-scope T8 commit (f8368e7, "one storage decision with versioned migrations") and verified the load-bearing paths: migrate() concurrency (per-migration tx under pg_advisory_xact_lock with a post-lock double-check, resumable on partial failure), the CLI --schema injection guard (identifier validated before -c search_path), checkSchema being non-mutating, resolveStoreDurability agree/contradict/absent logic, the withStorage/withStorageSubscriptions one-of refusals, and the memory-ledger.ts move preserving structuredClone and immutability semantics. Changeset is present and correctly minor for both experimental packages; package-size budgets match.

Medium findings

• src/lib/reporting/consumer-runtime.ts:340 — Buyer consumer accepts process-local storage (memoryStorage()) in production without a durability refusal, asymmetric with the seller's requireDurable gate and the PR's own "refused in production" invariant.

Only 1 medium finding, no critical/high, no gated paths, high_risk false, no team gate. Falls through to row 9. The medium is worth a human eye but does not block.

Decision rules walkthrough: Row 1 (critical/high) — no. Row 2 (gated_paths true & not approved) — gated_paths is false, skip. Row 3/5 (high_risk) — false. Row 4 (medium data-loss/schema/infra) — the finding category is a durability/refusal gap, not tagged schema/infra; no escalation. Row 6 — no prior decision. Row 7 — no team gate. Row 8 — fewer than 3 mediums. Row 9 — approve.

Medium findings

• src/lib/reporting/consumer-runtime.ts:340 — Buyer consumer accepts process-local storage in production without refusal

[aao-secretariat]

Ladon verdict: Approve

Approve.

Delta since the prior approve is a single test-only change in packages/reporting-storage/test/reporting-storage-facade-pg.test.js: an ownerToken literal renamed 'owner-a' → 'owner-token-a'. No behavior change, test-file only (no changeset required), and the value is opaque to lease logic.

No current findings. The prior Medium (src/lib/reporting/consumer-runtime.ts:340) is non-blocking and its file is absent from this delta, so it does not carry forward. No Critical/High findings exist.

Decision table: no critical/high (row 1 n/a), gated_paths false (row 2 n/a), no deletions (row 3 n/a), no medium data-loss/schema/infra (row 4 n/a), high_risk false (row 5 n/a), prior decision was approve not escalate (row 6 n/a), no team gate (row 7 n/a), fewer than 3 mediums (row 8 n/a) → row 9 approve.

[aao-secretariat]

Ladon verdict: Approve

Approve — test-only delta since prior approve, no findings.

The only change since the prior approve (head f8368e7) is a test-only edit in packages/reporting-storage/test/reporting-storage-facade-pg.test.js: ownerToken renamed owner-a → owner-token-a in a single workLeases.claim call. The value is never asserted against and flows straight into claim with the returned lease reused, so there is no behavior or correctness impact.

The prior Medium finding (src/lib/reporting/consumer-runtime.ts:340) is out of scope this pass — that file is absent from the current delta, so it does not carry forward.

No critical/high/medium findings in this run. No gated paths, no high-risk flag, no author team gate. Falls through to row 9.

[aao-secretariat]

Ladon verdict: Approve

Approve — clean subsequent pass, no blocking findings.

This delta (2 files / 55 lines) adds an optional durability to the consumer storage option and refuses process-local outside NODE_ENV=test|development with REPORTING_STORAGE_NOT_DURABLE — a fail-closed guard symmetric with the already-approved seller refusal, and tested under NODE_ENV=production (reporting-storage-facade.test.js:48-53). The surface is @experimental with no wire change, so DR-0033 does not apply.

One non-blocking Low observation (not surfaced inline): the service uses the shared requireDurable() helper (service/index.ts:499) while the consumer inlines its own test/development guard — currently identical behavior but a potential drift risk if DEVELOPMENT_ENVIRONMENTS ever changes. Consider consolidating on the shared helper.

Prior pass (approve) had no blockers; none re-surface. No critical/high/medium findings. No author-team gate, gated_paths is false, high_risk is false. Decision table falls through to row 9.

[aao-secretariat]

Ladon verdict: Approve

Approve — clean fail-closed hardening of the reliable-reporting consumer.

The delta (2 files, 52 lines) makes storage.durability required and flips the production guard from === 'process-local' to !== 'durable', so any storage that does not explicitly declare itself durable is now refused outside test/development — mirroring the seller side. The input.storage !== undefined short-circuit preserves the prior no-throw path when storage is absent, and a new test covers the undeclared-durability branch using the same production-env arrangement as the adjacent postgresStorage assertion. Changesets are present.

No critical/high/medium findings in this run. Prior approve stands and this is a net-neutral/positive iteration. No author team gate, gated_paths is false, and high_risk is false — falls through to row 9.