SDK output envelopes, format-aware budgets, and stable error contracts

Merged
UN
3mo ago
+6490-220

Outcome

Delivers a cohesive SDK/CLI context-contract tranche: typed output envelopes and mutation receipts, format-aware command budgets, classified/stability-gated error metadata, typed workspace snapshot failures, and deterministic offline reindex coverage. This directly resolves the undocumented mutation/query envelope defect reported in #888 while retaining broader follow-on scopes as open PM features.

Closes #888.

PM lineage

What changed

  • Added public SDK envelope definitions, built-in/package fallback resolution, flat CLI mutation receipt typing, validation, and camelCase normalization.
  • Paired every active runtime command with an output envelope and format-specific TOON/JSON budget; full consumer discovery currently reports 117 command contracts.
  • Added semantic exit classes, emitting-command ownership, and a stable/provisional ledger whose generator fails closed on malformed state, unsupported exits, stable removals, and drift.
  • Reclassified workspace snapshot grammar/not-found/conflict paths into typed errors with real CLI negative controls.
  • Added SDK/scripting documentation and an executable package-consumer receipt example.
  • Prevented mutation-triggered semantic refresh from escaping the residual reindex test mock boundary.
  • Regenerated contracts, SDK surface, error catalog, token baseline, and CHANGELOG through pm-changelog 2026.8.4.

Verification

  • Full repository coverage: 433 files, 6,850 tests, 100% statements / branches / functions / lines.
  • ESLint: zero warnings; jscpd: zero clones; static quality: 100% docstrings.
  • Typecheck, contract snapshot, SDK surface, docs/skills, secrets, token-budget, context-calibration, tracker measurement, CLI transport, and package-boundary gates pass.
  • Packed artifact installed in unrelated temporary npm and Bun projects; npx and bunx initialized trackers and created receipts parsed through the public SDK. Offline npm install audited 70 packages with zero vulnerabilities.
  • GitHub open security inventory: zero Dependabot, code-scanning, and secret-scanning alerts.

Explicit limitations

  • The npm advisory endpoint timed out through all pnpm audit retries; the cached/offline artifact audit and GitHub alert surfaces are clean.
  • The pre-existing pm-ay3l0p defect makes a broad coverage command direct-green but linked-schema-red; focused linked tests pass and direct coverage is the authoritative 100% result.
  • Local import-cost timing was noisy under sustained host load after passing earlier on the same code; hosted exact-head gates remain authoritative.

Summary by Sourcery

Introduce typed output envelope and mutation receipt contracts across the SDK/CLI, enrich error metadata with semantic classes, stability gating, and emitting command ownership, and harden workspace snapshot flows and offline reindex behavior.

New Features:

  • Expose SDK output envelope contracts, including generated budgets and envelopes for core and package commands, plus a public mutation receipt parser for scripting and package consumers.
  • Add format-aware command output budgets with TOON/JSON-specific token ceilings and fallback generation for extension-owned commands.
  • Publish command output and error-code contracts through the contracts command, including envelope families, budgets, semantic exit classes, stability, and emitting command roots.

Bug Fixes:

  • Fix workspace snapshot CLI errors by replacing generic exceptions with structured, typed PmCliError failures for invalid targets, missing snapshots, manifest mismatches, and unsafe restores.
  • Prevent reindex coverage tests from leaking mutation-triggered semantic refresh HTTP calls past their intended mock boundaries.

Enhancements:

  • Extend the error-code catalog generator and runtime contracts to track stability over time, infer emitting commands, classify exit codes into semantic classes, and reject unsupported or malformed catalog entries.
  • Tighten SDK and CLI contracts around output formats, including documenting mutation-versus-read envelope differences, enriching scripting docs, and enforcing non-empty, normalized command paths in budget and envelope helpers.
  • Broaden tests and type coverage for error catalogs, output budgets, output envelopes, SDK subpath entrypoints, and scripting examples to keep the public surface deterministic and safely consumable.

Documentation:

  • Update scripting and SDK documentation and examples to describe mutation receipts versus read envelopes, command output budget/envelope contracts, and how machine clients should consume these structured results.

Tests:

  • Add unit and integration tests for the error-code catalog generator stability ledger, output envelope contracts, mutation receipt parsing, workspace snapshot CLI error behavior, SDK subpath entrypoints, and the contract-consumer example receipt script.

Chores:

  • Regenerate public SDK surface, contracts fixtures, token baselines, and changelog entries to reflect the new output and error-code contracts.

Summary by cubic

Adds typed output envelopes and flat mutation receipts to the SDK/CLI, plus format-aware TOON/JSON budgets and a stability-gated error catalog with exit classes. Hardens contract discovery (normalized subcommand paths, explicit single/bulk mutations), clarifies --json, validates normalized error provenance, and makes reindex coverage deterministic. Closes #888.

  • New Features

    • SDK: PM_COMMAND_OUTPUT_ENVELOPE_CONTRACTS; parseMutationReceipt/isPmMutationReceipt with unambiguous overloads.
    • Budgets: TOON/JSON ceilings in PM_COMMAND_OUTPUT_BUDGET_CONTRACTS; helpers createPmCommandOutputBudget and inferPmOutputBudgetClass.
    • Errors: catalog includes PM_ERROR_CODE_EXIT_CLASS_CONTRACTS, emitting commands, and a reviewed stability ledger.

  • Bug Fixes

    • Discovery: preserve normalized subcommand/alias paths for envelope and budget lookups; classify single vs bulk mutation shapes.
    • Catalog: generator fails closed on unreadable/drifting ledgers; trims/normalizes sources and emitting commands and rejects empty provenance; unknown_error maps to exit 1; adds tests that lock resolution semantics and usage-class exits.
    • CLI/Tests: --json help clarifies receipts vs envelopes; workspace snapshot emits typed usage errors; reindex coverage is deterministic and under 30s.