Bound SDK context sessions and isolate linked-test diagnostics

Merged
UN
3mo ago
+265-8

Outcome

This follow-up hardening tranche completes two cross-cutting findings from the broad SDK/CLI delivery in #983:

  • keeps every caller-carried read-session continuation valid at the public 10,000-identity ceiling, with deterministic retention and an explicit overflow receipt replicated through every SDK entrypoint;
  • prevents real linked pm test sandbox failures from being classified as production Sentry incidents while preserving explicit run-level and per-test environment overrides.

It also records GitHub issue #984 under a canonical, unclaimed PM owner without mixing that separate command-grammar fix into this tranche.

PM lineage

Verification

  • 486 test files / 7,244 tests
  • exact 100/100/100/100 coverage
  • repo-wide lint, typecheck, contracts, docs links, secrets, SDK surface, package artifact, import-cost, calibration, assurance, and tracker ratchet gates
  • packed npx smoke
  • 88-command package-first dogfood
  • temporary-project acceptance through the real CLI: linked child isolation plus a 10,000-ID receipt reused by the next invocation
  • pm health --check-only and zero history drift
  • latest pm-changelog 2026.8.12 check, unchanged before item closeout

Operational guard

Sentry PM-CLI-31 remains unresolved and publication remains fail-closed until this fix is merged and the production incident is explicitly dispositioned.

Summary by Sourcery

Bound read-output session receipts to the 10,000-identity safety ceiling and isolate linked test Sentry diagnostics from production classification.

New Features:

  • Expose a read-output session receipt field that reports when newly served identities exceed the carried next-state capacity.
  • Default linked test executions to a test Sentry environment while allowing explicit run-level and per-test overrides.

Enhancements:

  • Ensure read-output session next_state remains a valid, capacity-respecting input for subsequent SDK calls with deterministic identity retention ordering.

Documentation:

  • Document read-output session capacity, overflow reporting, and next_state validity guarantees.
  • Document the default Sentry environment behavior for linked tests and how explicit overrides interact with it.

Tests:

  • Add SDK tests verifying read-output session overflow handling and next_state validity under capacity pressure.
  • Add command-level tests confirming linked tests use the test Sentry environment by default while honoring explicit env_set overrides.

Chores:

  • Record PM lineage and history entries for bounded reusable output-session receipts, linked-test Sentry isolation, and canonical ownership of GitHub issue #984.

Summary by cubic

Bounds SDK read-output session state to the 10,000-ID limit with a deterministic overflow receipt, and defaults linked pm test --run children to SENTRY_ENVIRONMENT=test so sandbox failures don’t show up as production. Clarifies and tests override precedence: default < run-level < per-test.

  • Bug Fixes
    • SDK: PmReadOutputSessionReceipt.next_state now always fits the 10,000-ID input ceiling. Newly served IDs are retained deterministically up to capacity; overflow is reported via optional seen_item_overflow_count. Below-capacity receipts remain wire-compatible and are accepted by parseReadOutputSession.
    • Linked tests: pm test --run children default to SENTRY_ENVIRONMENT=test while honoring explicit run-level and per-test overrides. Tests prove precedence (default < run-level < per-test), preventing sandbox errors from being classified as production (addresses PM-CLI-31).