feat(sdk): strengthen context and evidence contracts

Merged
UN
3mo ago
+1615-163

Outcome

This broad SDK/CLI tranche makes context and evidence contracts more truthful, portable, and token-efficient across every supported surface:

  • material omission receipts charge only source-proven recoverable context
  • extension preflight ownership participates in lazy command activation
  • isAlreadyClaimedError is a supported, bundle-safe SDK primitive
  • merge results distinguish requested preference from the value actually retained
  • item history hashes carry a backward-compatible canonicalization epoch
  • assurance mutation refusals cross CLI/SDK/MCP as typed usage errors instead of unclassified Sentry faults
  • the real Codex MCP smoke now ratchets the lean mutation envelope

Canonical pm items

  • pm-gok2km — GH-969 material omission receipts
  • pm-zryb9d — GH-971 scoped preflight ownership
  • pm-qckpnq — GH-974 truthful merge receipts
  • pm-hfqju5 — GH-975 public claim-race predicate
  • pm-2htk4p — GH-976 versioned history hashes
  • pm-v0a0un — typed assurance mutation refusals
  • pm-fb0lkg — dependency-update release evidence

Closes #969
Closes #971
Closes #974
Closes #975
Closes #976

Verification

  • exact repository coverage: 486 files, 7,234 tests, 100% statements / branches / functions / lines
  • linked isolated-tracker suites for all six implementation items
  • full build, typecheck, ESLint, jscpd, static quality, SDK surface, docs/skills, contracts, security, package-artifact, token-budget, context-calibration, graph and integrity gates
  • packed npx plus strict ESM/TypeScript consumer
  • real Codex and Claude MCP lifecycle smokes
  • compatibility smoke across 10 external packages
  • temporary-project cross-version history acceptance against published 2026.8.7 and 2026.8.10
  • manual JSON and TOON projection monotonicity acceptance
  • npm audit: zero vulnerabilities
  • pm history drift: 0 across 2,442 items; pm health: 10/10 checks clean

Release policy

v2026.8.11 already exists, so this PR must not create a second automatic release today. After merge, the immutable existing npm/GitHub release will be verified independently; the next eligible daily release remains fail-closed while recent high-severity Sentry issues are unresolved.

Summary by Sourcery

Strengthen SDK and CLI context, history, merge, assurance, and claim contracts for more truthful, portable, and version-compatible evidence across runtime surfaces.

New Features:

  • Expose isAlreadyClaimedError as a stable, bundle-safe predicate from both primary SDK entrypoints.
  • Introduce explicit item history hash epochs with versioned hashing APIs and verification helpers.
  • Add material field-group registration for read results so omission receipts charge only for truly present context.
  • Extend merge receipts and driver/item results with requested_preference to distinguish caller intent from retained values.

Bug Fixes:

  • Prevent assurance mutations with malformed or unauthorized definitions from surfacing as generic failures by classifying them as usage refusals.
  • Ensure merge summaries and receipts no longer misreport preferred side under stable value order, while retaining legacy receipt compatibility.
  • Fix extension preflight activation so scoped ownership only activates for owned commands and does not incorrectly contribute to global preflight overrides.
  • Adjust Codex MCP smoke to enforce the lean mutation envelope for pm_create responses and reject stale or malformed envelopes.
  • Guard measurement and assertion validation against missing or incorrectly typed dependency_kind and field values.

Enhancements:

  • Version and cache history drift scanning to track and reuse detected item_hash_version, preserving linked-test insertion order while remaining backward compatible.
  • Tighten output omission contracts for pm get so empty bodies and zero-cardinality collections do not inflate omission receipts, and material groups retain precise restoration guidance.
  • Normalize assurance action mutations through a shared boundary that maps deterministic TypeErrors to typed usage refusals while preserving non-validation failures.
  • Refine merge driver and three-way item merge results to treat per-decision retained/discarded values as authoritative, while propagating requested_preference consistently.
  • Update runtime primitives and error-code catalog to expose new history and assurance contracts through supported SDK surfaces.

Documentation:

  • Add SDK context and evidence contracts documentation covering omission receipts, scoped preflight ownership, merge provenance, claim-race classification, versioned history hashes, and assurance mutation refusals.
  • Extend merge safety documentation to describe requested_preference semantics, legacy receipt normalization, and history item hash epochs.
  • Update README and CHANGELOG entries to reflect strengthened context, evidence, and dependency updates.

Tests:

  • Add targeted unit tests for history hash versioning, drift cache behavior, merge receipts and direction contracts, output omission materiality, assurance action error typing, claim predicate exposure, extension preflight activation, and Codex MCP smoke envelopes to lock in the new contracts and compatibility behaviors.

Chores:

  • Refresh Sentry dependency evidence with packed-consumer verification and update project agents/history fixtures for the new contracts.

Summary by cubic

Strengthens SDK and CLI context/evidence contracts to cut tokens, clarify merge receipts, and harden history verification. Tracks PR #981 delivery and docs; tightens history epoch gating and omission billing.

  • New Features

    • Material omission receipts in pm get only charge for material groups; empty/default fields no longer add cost (GH-969).
    • Scoped preflight activation and diagnostics honor declared command ownership; lazy activation uses effective command sets (GH-971).
    • Public claim-race predicate: export isAlreadyClaimedError from supported SDK entrypoints for safe, bundle-proof checks (GH-975).
    • Truthful merge receipts: separate requested_preference from retained values; legacy preferred still read; driver result uses requested_preference (GH-974).
    • Versioned history hashes: add item_hash_version with default v2; replay/verify accept versions; drift cache v4; backward-compatible with v1 streams (GH-976).
    • Assurance mutation refusals are typed usage errors (invalid_argument_value/assurance_mutation_refused) across CLI/SDK/MCP; MCP smoke enforces a lean pm_create envelope.
    • Documentation: added SDK Context and Evidence Contracts guide.

  • Bug Fixes

    • Compacted generated error-code catalog arrays to a deterministic 100-column layout and added boundary tests to lock the format.
    • Narrowed assurance mutation normalization to only expected validation/policy refusals so unexpected TypeErrors are not masked by transport layers.
    • Regenerated the error-code catalog and contract fixtures to include the new sdk/governance/assurance-mutation-error boundary and updated provenance.
    • Hardened contracts: reject unsupported history hash epochs before hashing; type malformed assurance retirement metadata as usage refusals; stop billing default unclaimed claim_state in omission receipts.