feat(sdk): govern runtime context, write safety, and verification gates

Merged
UN
3mo ago
+3340-383

Summary

  • add SDK-owned project-runtime compatibility and action-aware stale mutation refusal while preserving read-only context
  • add reusable host-environment faults plus linked-test source-context write fencing and safe merge-install resolution
  • make the gate registry own the canonical local preflight receipt and strengthen refusal/surface replication governance
  • pin patched nanoid 3.3.17 to clear GHSA-2v37-7h3g-55p8 without unrelated dependency churn

PM lineage

Verification

  • 453 test files / 7,061 tests
  • exact 100/100/100/100 coverage: 50,228 statements, 36,690 branches, 10,319 functions, 48,631 lines
  • full lint/static gates: ESLint, zero clones, 100% docstrings, SDK/package parity, token/context/tracker ratchets, SDK surface and performance floors
  • typecheck, build, package artifact, secret scan, and full pnpm audit pass
  • packed npx/bunx lifecycle and temporary two-repository nested merge-install acceptance pass
  • pm validation has zero history drift; health has zero warnings; no PM items remain in progress

Closes #926
Closes #933
Refs #934

Summary by Sourcery

Enforce SDK-governed runtime compatibility and host-environment fault handling, tighten source-context write safety, and formalize local/hosted gate parity and CLI refusal ownership while pinning a patched nanoid version.

New Features:

  • Introduce project runtime compatibility primitives that classify mutating CLI invocations, detect stale executables against project pm version pins, and expose inspection/assertion APIs for packages and automation.
  • Add a host-environment error boundary that standardizes classification and redaction of filesystem and resource faults across SDK operations.
  • Expose a source-context access policy that distinguishes read-only from writable inherited coordinates and reports override status to SDK consumers.
  • Provide a registry-owned local preflight entrypoint that validates the executed gate receipt against gate-registry.json and maps hosted-only gates with explicit reasons.

Bug Fixes:

  • Prevent nested linked tests from mutating the source project by default by marking inherited source context as read-only and requiring an explicit one-shot override for writes.
  • Ensure release gate receipts cannot drift from the governed registry by rejecting missing, reordered, or undeclared local preflight steps.
  • Improve surface replication coverage by detecting untracked files and by failing when CLI refusal ownership declarations are incomplete or inconsistent.

Enhancements:

  • Refactor workspace snapshot filesystem error handling to reuse the shared host-environment fault boundary while preserving existing snapshot-specific error codes and recovery flows.
  • Extend merge-install to resolve tracker/workspace context via a reusable resolution primitive that respects source-context write policy and dry-run behavior, improving safety for linked tests.
  • Expand the surface replication gate to inventory CLI refusal rules with per-occurrence ownership metadata and to include untracked files in change discovery.
  • Strengthen gate registry validation by requiring a canonical local preflight declaration with complete gate coverage and hosted-only waivers.
  • Wire the CLI entrypoint through the new runtime-compatibility boundary so stale mutations are refused with structured guidance while non-mutating commands remain available.

Build:

  • Add a verify:preflight package script that runs the canonical local release gate selection.
  • Pin nanoid to a patched 3.3.17 range in the workspace overrides to address GHSA-2v37-7h3g-55p8 without broader dependency changes.

CI:

  • Align gate-registry.json with the new local preflight model and hosted-only gate declarations to maintain parity between local verification and CI workflows.

Documentation:

  • Document SDK runtime boundaries, including project runtime compatibility, host-environment fault handling, and CLI refusal ownership contracts.
  • Update agent runtime, testing, and releasing guides to describe source-context access controls, the verify:preflight workflow, and local/hosted gate parity governance.

Tests:

  • Add comprehensive unit tests for project runtime compatibility classification, pin discovery, CLI boundary behavior, host-environment error translation, source-context policy, gate registry local preflight validation, release gate receipt drift detection, and extended surface replication behavior.
  • Extend merge-safety and linked-test execution tests to cover source-context read-only enforcement and explicit write overrides.

Chores:

  • Record PM tracking metadata for runtime compatibility, gate parity, CLI refusal ownership, linked-test safety, and nanoid security updates in the repository agents.

Summary by cubic

Adds SDK-governed runtime safety and a registry-owned, fail-closed preflight so stale pm binaries can’t mutate projects; stale reads now warn without blocking; linked tests inherit read-only source context; host faults are classified; pins nanoid to 3.3.17.

  • New Features - New features added

    • Stale runtime guard runs before dispatch with action-aware command classification (handles equals-form flags and global value flags after the command); read-only commands remain; typed stale-read diagnostics and CLI warnings preserve stdout for --json/equals-form flags; one-shot override via PM_ALLOW_STALE_CLI=1 (GH-926, pm-zjelve).
    • Linked-test source-context write fencing defaults to read-only via PM_SOURCE_CONTEXT_ACCESS=read_only; allow a single write with PM_ALLOW_SOURCE_CONTEXT_WRITES=1; resolveMergeInstallContext enables non-writing resolution and merge-install honors policy (GH-933).
    • Host environment fault boundary classifies capacity/permission/resource errors, redacts paths, and is applied to workspace snapshots with distinct codes; SDK exports helpers; preserves dependency-free fast --version startup (pm-dskxwf).
    • Gate registry owns the executable local preflight; pnpm verify:preflight runs the canonical plan and records explicit skipped receipts; run fails on drift or undeclared steps; stronger per-occurrence CLI refusal ownership inventory and untracked-file detection; pins nanoid 3.3.17 (pm-n41vay).

  • Migration - Steps needed for adoption

    • If a mutation is refused as stale: upgrade @unbrained/pm-cli to the project’s pin, or set PM_ALLOW_STALE_CLI=1 to proceed once; reads still work and now warn.
    • Linked tests inherit PM_SOURCE_CONTEXT_ACCESS=read_only; set PM_ALLOW_SOURCE_CONTEXT_WRITES=1 to permit a single nested write when needed.
    • Use pnpm verify:preflight to run the canonical local gates; receipts and step set are enforced at exact Git HEAD.