feat(sdk): tier public surfaces and enforce transport contracts

Merged
UN
3mo ago
+27540-3836

Summary

This is a broad SDK/CLI platform bundle centered on project management = context management:

  • partitions the aggregate SDK into independently importable authoring, contracts, core, governance, graph, merge, and query entrypoints while preserving the existing flat SDK;
  • freezes the complete public type/error surface behind a semantic additive/compatible/breaking-change gate;
  • adds mandatory SDK import-cost, CLI cold-start, and CLI-minus-SDK transport budgets without weakening existing scale gates;
  • makes extension workspace coordinates portable and activation failures actionable at install, activate, explore, doctor, and unknown-command boundaries;
  • unifies automatic harness author resolution across CLI/SDK mutations and context-usage feedback, with typed failure contracts and append-only historical disposition;
  • enables advisory duplicate governance by default, conventional bare boolean metadata flags, and Node 22/cross-platform index/cache behavior;
  • expands package-first, packed-consumer, integration, contract, release, and documentation coverage.

PM lineage

Closes #700
Closes #701
Closes #702
Closes #703
Closes #704
Closes #705
Closes #706

Verification

  • 6,340 tests; 100% statements, branches, functions, and lines
  • lint, typecheck, zero-clone gate, 100% source/export/member docstrings
  • SDK surface, SDK import-cost, CLI transport, package-boundary, token-budget, docs/skills, version, secret, and changelog gates
  • pnpm audit --prod: no known vulnerabilities
  • packed npm consumer with Node and Bun: all eight SDK subpaths, automatic harness:codex attribution with PM_AUTHOR unset, and bare --regression
  • package-first dogfood: 88 commands
  • packed npx smoke: 15 packages
  • latest pm-changelog 2026.7.25 regeneration/check
  • previous-version compatibility: item count preserved, health and validation green
  • Sentry/telemetry gate: zero critical/high issues in the 14-day activity window
  • PM health: green, zero actionable unknown-author events, no history drift

The workstation scale run retained the existing budgets but recorded a latency-only miss under load ~10 on 8 CPUs; the unchanged base revision was slower and failed the same ratchet. The clean GitHub runner remains the authoritative scale/nightly proof, and this PR does not weaken or bypass that gate.

Summary by cubic

Delivers capability-scoped SDK entrypoints and a semantic public API snapshot with import-cost and CLI transport budgets. Adds portable extension coordinates, actionable activation diagnostics, unified harness-based author attribution, advisory duplicate governance, and stabilized Node 22 cross‑platform gates; CI now enforces pnpm sdk:surface:check and docs/CHANGELOG are updated.

  • New Features

    • Tiered SDK exports: @unbrained/pm-cli/sdk/authoring, @unbrained/pm-cli/sdk/contracts, @unbrained/pm-cli/sdk/core, @unbrained/pm-cli/sdk/governance, @unbrained/pm-cli/sdk/graph, @unbrained/pm-cli/sdk/merge, @unbrained/pm-cli/sdk/query (aggregate ./sdk remains).
    • Public API snapshot and gate: scripts/sdk-surface-snapshot.mjs, fixture tests/fixtures/sdk/public-surface.json, CI step pnpm sdk:surface:check.
    • Extension runtime coordinates in handlers and parser overrides: source_workspace_root, repo_root, pm_root_rel; activation failures surfaced in unknown-command/help, doctor, and explore.
    • Unified author precedence: --author > PM_AUTHOR > project default > detected harness > unknown (harness attribution is automatic).
    • Duplicate-governance default is now advisory; boolean metadata flags accept bare values (e.g., --regression); Node 22/cross-platform fixes; docs refreshed (entrypoints, performance gates, testing, onboarding, releasing) and CHANGELOG regenerated.

  • Performance

    • SDK entrypoint import-cost budgets and report: scripts/bench/sdk-entrypoint-costs.mjs, scripts/bench/sdk-entrypoint-budgets.json, docs at docs/performance/sdk-entrypoint-import-costs.md.
    • CLI cold-start transport budgets and report: scripts/bench/cli-transport-floor.mjs, scripts/bench/cli-transport-budgets.json, docs at docs/performance/cli-transport-overhead.md.
    • Scale budgets include CLI-vs-SDK transport deltas; gates are ratchets. Cross-platform contracts stabilized by regenerating the full fixture for author semantics and replacing a Unix-only import-cost failure path with a portable Node path.