SDK context integrity, recovery, and external dependency primitives

Merged
UN
2mo ago
+7279-992

Outcome

This broad delivery advances project management = context management through SDK-owned primitives consumed by the CLI and packages. It combines the open agent-UX, history, package, merge, dependency, and duplication reports into one reviewed context-integrity release rather than isolated patches.

SDK and CLI delivery

  • Preserve literal commas and whitespace in structured mutations, refuse ambiguous bare comma inputs, and make strict-create recovery truthful with explicit clear flags.
  • Return linked file and documentation validation receipts at write time, and reject linked-test runs that execute zero selected tests.
  • Accept npm 11 and npm 12 pack receipts while preserving fail-closed package selection.
  • Resolve Claude JSONL provenance through a bounded deterministic search.
  • Version history item hashing, report future writer capabilities as version skew, and confirm cache-originated corruption candidates with authoritative item reads plus content hashes.
  • Require exact hash-only merge proof without unconditional force, and make pending-receipt health remediation execute the state-changing reconcile command while retaining dry-run as optional preview guidance.
  • Model external blockers as typed graph nodes, expose public SDK resolver registration, retain unverifiable blockers in pm next, and exclude them from destructive local dangling-reference guidance.
  • Add a JavaScript/TypeScript cross-format production-source duplication ratchet alongside the repository-wide clone gate.
  • Regenerate public SDK surface, contracts, error catalog, agent docs, and the pm-changelog output.

PM evidence

Verification

  • Full repository suite: 586 files and 8,124 tests passed.
  • Exact coverage: 60,169/60,169 statements, 45,397/45,397 branches, 12,514/12,514 functions, and 57,939/57,939 lines (100/100/100/100).
  • Repository static assurance, TypeScript, ESLint, contract and SDK surface checks, package parity, graph and record-integrity assurances, context/token gates, secret scan, and both jscpd profiles pass with zero clones.
  • Packed npm smoke passed for all 13 packages; Node and Bun CLI/SDK consumers were manually exercised in an isolated temporary workspace.
  • Compatible dependency updates resolve greptile 3.4.2, @types/node 26.4.0, @sentry/cli 3.7.0, and pm-changelog 2026.8.29; npm-package-arg 14 and TypeScript 7 remain in evidence-backed canonical deferral items.
  • Open Dependabot, code-scanning, and secret-scanning alert counts are zero.

Closes #1002
Closes #1134
Closes #1135
Closes #1136
Closes #1137
Closes #1138
Closes #1140
Closes #1143
Closes #1144
Closes #1145
Closes #1146
Closes #1147
Closes #1148
Closes #1150
Closes #1151
Closes #1152

Summary by Sourcery

Strengthen SDK and CLI context integrity with lossless mutations, trustworthy recovery and validation, version-aware history safeguards, exact merge proofs, and safe external dependency handling.

New Features:

  • Add SDK-owned primitives for typed external dependency resolution and public resolver registration.
  • Expose write-time validation receipts for linked files and documentation and richer external blocker data in scheduling output.

Bug Fixes:

  • Preserve literal commas and whitespace in structured metadata while rejecting ambiguous bare comma inputs.
  • Prevent filtered linked-test commands from succeeding when they execute zero tests.
  • Support npm 11 and npm 12 package receipts without weakening deterministic package selection.
  • Improve Claude provenance discovery, strict-create recovery guidance, history drift verification, and hash-only merge reconciliation.

Enhancements:

  • Version history item hashing and classify unsupported writer capabilities as version skew rather than corruption.
  • Materialize external blockers in relationship graphs and exclude them from destructive dangling-reference remediation.
  • Add a stricter production-source duplication detection profile.

Build:

  • Run repository-wide and production-source duplication checks as part of the duplicate lint command.

Documentation:

  • Document context integrity, recovery, external blockers, package receipts, and history and merge safeguards.
  • Regenerate changelog and public SDK, contract, error catalog, and agent-facing documentation surfaces.

Tests:

  • Expand regression and integration coverage for context parsing, dependency resolution, package receipts, provenance recovery, history drift, merge proofs, linked tests, and validation receipts.

Chores:

  • Update project-management evidence and history artifacts for the delivered integrity work.

Summary by cubic

Ships SDK-owned context-integrity primitives so parse, link, merge, and dependency state is recorded truthfully instead of silently corrupted, falsely reported green, or left permanently stuck.

Context integrity primitives

  • Structured mutations preserve literal commas, whitespace, and newlines, refuse ambiguous bare comma inputs, and share one grammar across create, files, docs, and linked-test paths.
  • Strict-create recovery surfaces truthful --clear-* intent; linked file/docs writes return validation receipts at write time; linked-test runs require a positive executed-test receipt, with filtered runs count-aware across real runners, zero-test receipts recognized across reporter variants, and regression probes time-bounded so hosted coverage teardown stays deterministic.
  • npm 11 and 12 pack receipts are accepted with fail-closed package selection (including file-alias receipts and keyed identity checks), and Claude JSONL provenance resolves through bounded deterministic reads.
  • New ambiguous-input, missing-receipt, and version-skew diagnostics are registered in the public error contract.

Recovery and external dependencies

  • History hashing advances from version 2 to 3, invalidates incompatible drift caches, reports future writer capabilities as version skew with budget-bounded evidence and an upgrade remediation that survives bulk history repair, keeps item drift comparable when a stream mixes valid final entries with unsupported writer epochs, confirms cached corruption candidates with authoritative rereads, rejects malformed cached chain state, and continues replay past unsupported hash versions so later corruption stays independently diagnosable before failing closed.
  • Merge repair reloads authoritative receipts before writing; reconcile trusts exact hash-only proof without force (merge_reconcile_discards_require_acceptance is removed); health remediation now runs the state-changing pm merge reconcile instead of --dry-run, which stays as optional preview guidance; durable receipt recovery guidance is corrected.
  • External blockers become typed graph nodes with safe public resolver registration that validates resolver outputs before projection and isolates synchronous failures (including malformed decoded identifiers), are separated from local graph targets by edge provenance, keep their identity through provenance, case, actionability, and graph flows, stay in pm next, are excluded from destructive dangling-reference guidance, and expose blocked_since through the public resolver with ISO-8601-normalized observation timestamps.
  • A stricter production-source duplication ratchet (cross-format, per-source threshold) joins the repository-wide clone gate.
  • Compatible patches refresh greptile to 3.4.2, @types/node to 26.4.0, @sentry/cli to 3.7.0, and pm-changelog to 2026.8.29, deferring npm-package-arg 14 and TypeScript 7.
  • The linked-test sandbox guard stays a distinct open recurrence (GH-1154).