Skip to content

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

Merged
unbraind merged 3 commits into
mainfrom
feat/sdk-surface-contract-and-transport-budgets
Jul 25, 2026
Merged

unbraind merged 3 commits into
mainfrom
feat/sdk-surface-contract-and-transport-budgets

Conversation

@unbraind

@unbraind unbraind commented Jul 25, 2026 •

Copy link
Copy Markdown
Owner

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.

Written for commit a5bb4be. Summary will update on new commits.

Review in cubic

Deliver capability-scoped SDK entrypoints, semantic API snapshots, import and CLI transport budgets, extension runtime coordinates and actionable activation diagnostics. Unify automatic harness author attribution, advisory duplicate governance, bare boolean mutation flags, cross-platform Node 22 index behavior, and package-first verification. Record all implementation, tests, documentation, graph lineage, and append-only author dispositions through pm.
@gemini-code-assist

Copy link
Copy Markdown

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

@coderabbitai

coderabbitai Bot commented Jul 25, 2026 •

Copy link
Copy Markdown

Important

Review skipped

Too many files!

This PR contains 132 files, which is 32 over the limit of 100.

To get a review, narrow the scope:
• coderabbit review --committed # exclude uncommitted changes
• coderabbit review --dir # limit to a subdirectory
• coderabbit review --base # compare against a closer base

Upgrade to a paid plan to raise the limit.

This review couldn't start because sufficient usage credits or metered capacity aren't available. Add credits or update usage-based reviews in the billing tab, then retry.

⚙️ Run configuration

Configuration used: Repository UI (base), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: e68a8831-c3d8-4da4-82bd-b20a1a43c81e

📥 Commits

Reviewing files that changed from the base of the PR and between 840e4ef and a5bb4be.

📒 Files selected for processing (132)
  • .agents/pm/decisions/pm-irp1.toon
  • .agents/pm/extensions/.managed-extensions.json
  • .agents/pm/history/_workspace.jsonl
  • .agents/pm/history/pm-38bskj.jsonl
  • .agents/pm/history/pm-3ljt19.jsonl
  • .agents/pm/history/pm-3x8w4m.jsonl
  • .agents/pm/history/pm-42p9nk.jsonl
  • .agents/pm/history/pm-de3foa.jsonl
  • .agents/pm/history/pm-e02lgu.jsonl
  • .agents/pm/history/pm-e6tm5c.jsonl
  • .agents/pm/history/pm-fc9gm4.jsonl
  • .agents/pm/history/pm-irp1.jsonl
  • .agents/pm/history/pm-ulb3rc.jsonl
  • .agents/pm/history/pm-yse5dt.jsonl
  • .agents/pm/issues/pm-3ljt19.toon
  • .agents/pm/issues/pm-3x8w4m.toon
  • .agents/pm/issues/pm-42p9nk.toon
  • .agents/pm/issues/pm-de3foa.toon
  • .agents/pm/issues/pm-fc9gm4.toon
  • .agents/pm/issues/pm-ulb3rc.toon
  • .agents/pm/tasks/pm-38bskj.toon
  • .agents/pm/tasks/pm-e02lgu.toon
  • .agents/pm/tasks/pm-e6tm5c.toon
  • .agents/pm/tasks/pm-yse5dt.toon
  • .github/workflows/ci.yml
  • CHANGELOG.md
  • docs/AGENT_GUIDE.md
  • docs/CONFIGURATION.md
  • docs/EXTENSIONS.md
  • docs/ONBOARDING.md
  • docs/PERFORMANCE.md
  • docs/RELEASING.md
  • docs/SDK.md
  • docs/SDK_CONTEXT_COORDINATION.md
  • docs/SDK_CUSTOMIZATION_PRIMITIVES.md
  • docs/TESTING.md
  • docs/performance/cli-transport-overhead.md
  • docs/performance/sdk-entrypoint-import-costs.md
  • eslint-suppressions.json
  • package.json
  • scripts/bench/cli-transport-budgets.json
  • scripts/bench/cli-transport-floor.mjs
  • scripts/bench/run-scale-benchmarks.mjs
  • scripts/bench/scale-budgets.json
  • scripts/bench/sdk-entrypoint-budgets.json
  • scripts/bench/sdk-entrypoint-costs.mjs
  • scripts/bundle-cli.mjs
  • scripts/release/static-quality-gate.mts
  • scripts/sdk-surface-snapshot.mjs
  • src/cli/after-command-context-usage.ts
  • src/cli/commander-usage.ts
  • src/cli/commands/claim.ts
  • src/cli/commands/context.ts
  • src/cli/commands/copy.ts
  • src/cli/commands/create.ts
  • src/cli/commands/get.ts
  • src/cli/commands/next.ts
  • src/cli/commands/reindex.ts
  • src/cli/extension-recovery.ts
  • src/cli/main.ts
  • src/cli/register-mutation.ts
  • src/cli/register-setup.ts
  • src/cli/registration-helpers.ts
  • src/core/extensions/extension-hook-runtime.ts
  • src/core/extensions/loader.ts
  • src/core/history/event-index.ts
  • src/core/search/background-refresh.ts
  • src/core/shared/author.ts
  • src/core/shared/constants.ts
  • src/core/store/item-metadata-query-index.ts
  • src/core/store/settings.ts
  • src/core/telemetry/runtime.ts
  • src/mcp/tool-definitions.ts
  • src/sdk/authoring.ts
  • src/sdk/cli-contracts/commander-mutation-options.ts
  • src/sdk/context-usage.ts
  • src/sdk/contracts.ts
  • src/sdk/core.ts
  • src/sdk/extension-contracts.ts
  • src/sdk/extension.ts
  • src/sdk/extension/doctor.ts
  • src/sdk/governance.ts
  • src/sdk/governance/tracked-runtime-cache.ts
  • src/sdk/graph.ts
  • src/sdk/history-repair.ts
  • src/sdk/index.ts
  • src/sdk/init-agent-guidance.ts
  • src/sdk/init.ts
  • src/sdk/invocation-author.ts
  • src/sdk/merge.ts
  • src/sdk/merge/install.ts
  • src/sdk/mutation-events.ts
  • src/sdk/package-import-adapters.ts
  • src/sdk/query.ts
  • src/sdk/runtime-primitives.ts
  • src/sdk/schema-migration.ts
  • src/sdk/schema.ts
  • src/sdk/test/runs.ts
  • tests/fixtures/contracts/full.json
  • tests/fixtures/sdk/public-surface.json
  • tests/integration/cli.integration.spec.ts
  • tests/integration/extension-host-contracts.integration.spec.ts
  • tests/integration/release-automation-contract.spec.ts
  • tests/integration/release-readiness-runtime.spec.ts
  • tests/types/sdk-subpath-entrypoints.test-d.ts
  • tests/unit/cli/recovery-context-usage.spec.ts
  • tests/unit/cli/registration-helpers.spec.ts
  • tests/unit/commands/claim-command.spec.ts
  • tests/unit/commands/context-relevance-command.spec.ts
  • tests/unit/commands/create-command.spec.ts
  • tests/unit/commands/init-command.spec.ts
  • tests/unit/commands/next-command.spec.ts
  • tests/unit/commands/schema-command.spec.ts
  • tests/unit/core/history/drift-scan.spec.ts
  • tests/unit/core/history/event-index.spec.ts
  • tests/unit/core/item/item-metadata-query-index.spec.ts
  • tests/unit/core/shared/shared-helpers.spec.ts
  • tests/unit/core/store/settings-store.spec.ts
  • tests/unit/extensions/extension-command.spec.ts
  • tests/unit/extensions/extensions-runtime.spec.ts
  • tests/unit/packages/package-import-adapters.spec.ts
  • tests/unit/scripts/bundle-cli.spec.ts
  • tests/unit/scripts/cli-transport-floor.spec.ts
  • tests/unit/scripts/scale-benchmark.spec.ts
  • tests/unit/scripts/sdk-entrypoint-costs.spec.ts
  • tests/unit/scripts/sdk-surface-snapshot.spec.ts
  • tests/unit/sdk/author-attribution.spec.ts
  • tests/unit/sdk/context-packing-usage.spec.ts
  • tests/unit/sdk/mutation-events.spec.ts
  • tests/unit/sdk/sdk-subpath-entrypoints.spec.ts
  • tests/unit/sdk/tracked-runtime-cache.spec.ts
  • tests/unit/sdk/workspace-memory.spec.ts

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry @unbraind, your pull request is larger than the review limit of 150000 diff characters

@unbraind
unbraind marked this pull request as ready for review July 25, 2026 11:37
@unbraind

Copy link
Copy Markdown
Owner Author

@greptileai review

@coderabbitai full review

@gemini-code-assist

Copy link
Copy Markdown

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

@coderabbitai

coderabbitai Bot commented Jul 25, 2026 •

Copy link
Copy Markdown

@unbraind: Starting a full review of the PR, including the complete diff and affected contracts.

✅ Action performed

Full review finished.


Your included review limit is currently reached under our Fair Usage Limits Policy. This review may still proceed through usage-based billing if eligible. Your next included review will be available in 54 minutes.

@codspeed

codspeed Bot commented Jul 25, 2026 •

Copy link
Copy Markdown

Merging this PR will degrade performance by 0.12%

⚡ 4 improved benchmarks
❌ 7 regressed benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

Benchmark BASE HEAD Efficiency
❌ decodeQueryCursor 114.3 µs 116.4 µs -1.87%
❌ jaccardSimilarity 153.4 µs 153.5 µs -0.09%
❌ tokenizeAlphaNumeric 367.3 µs 367.4 µs -0.03%
❌ normalizeLowercaseWhitespace 135.9 µs 135.9 µs -0.02%
❌ encodeQueryCursor 101.2 µs 101.2 µs -0.02%
❌ stableStringify (nested contract) 161.5 µs 161.6 µs -0.01%
❌ tokenize + score query over 2000 docs 7.5 ms 7.5 ms 0%
⚡ build index (2000 docs x 80 words) 161.3 ms 160.7 ms +0.36%
⚡ createQueryFingerprint 516.9 µs 515.1 µs +0.36%
⚡ score query over 2000 docs 5.6 ms 5.6 ms +0.02%
⚡ build index (200 docs x 40 words) 8.4 ms 8.4 ms +0.01%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.


Comparing feat/sdk-surface-contract-and-transport-budgets (a5bb4be) with main (840e4ef)

Open in CodSpeed

@codecov

codecov Bot commented Jul 25, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!

Regenerate the full contract fixture for automatic harness author semantics and replace the Unix-only import-cost failure executable with a portable Node failure path. Record the CI diagnosis and verification on the owning pm SDK items.
@unbraind

Copy link
Copy Markdown
Owner Author

@greptileai review

@coderabbitai full review

Fresh full review requested for exact head 7c1921db after fixing the generated author-contract snapshot and the Windows-portable SDK import-cost failure fixture.

@coderabbitai

coderabbitai Bot commented Jul 25, 2026 •

Copy link
Copy Markdown

@unbraind: Starting a fresh full review for head 7c1921db, including the author-contract snapshot and Windows-portable SDK import-cost fixture fixes.

✅ Action performed

Full review finished.


Your included review limit is currently reached under our Fair Usage Limits Policy. This review may still proceed through usage-based billing if eligible. Your next included review will be available in 43 minutes.

@unbraind

Copy link
Copy Markdown
Owner Author

Automated review disposition for 7c1921db

  • CodeRabbit: terminal success, but the service explicitly skipped code analysis because this 129-file PR exceeds its current review/usage allowance; no inline finding was returned. Both status comments were acknowledged with positive usefulness reactions.
  • Greptile: both GitHub review requests remained silent, so the repository-owned authenticated agent gate was run directly. It returned terminal free_reviews_limit_reached; no code finding was returned. This is recorded as reviewer infrastructure unavailable, not approval.
  • Sourcery: explicit 150,000-diff-character limit; no code finding. The status review was acknowledged with a positive usefulness reaction.
  • Gemini Code Assist: service-sunset notices only; no code findings. Both obsolete notices were acknowledged with negative usefulness reactions.
  • Codecov: all modified lines covered; acknowledged positively.
  • CodSpeed: net -0.11% across the benchmark suite (6 improved, 5 regressed; largest displayed movement -1.81%). The changed SDK entrypoint/transport paths passed their dedicated ratchet gates, so the small unrelated movements are treated as benchmark noise; acknowledged positively.
  • Inline review threads: none.

Every required GitHub check is terminal and green on this exact head, including static, Windows Node 24, all coverage shards and gate, compatibility, smokes, CodeQL, Semgrep, Trivy, TruffleHog, ShellCheck, PSScriptAnalyzer, docs, and benchmarks.

Record exact-head CI, packed-consumer, telemetry, and reviewer evidence; close and release the nine actively delivered items with complete resolution metadata; document the canonical Greptile quota lineage; and regenerate CHANGELOG.md through pm-changelog 2026.7.25.
@unbraind

Copy link
Copy Markdown
Owner Author

@greptileai review

@coderabbitai full review

Final full review requested for exact closeout head a5bb4bec; this push records PM resolution/evidence, releases all nine delivered items, and regenerates CHANGELOG.md through pm-changelog 2026.7.25.

@coderabbitai

coderabbitai Bot commented Jul 25, 2026 •

Copy link
Copy Markdown

@unbraind: Starting a fresh full review of the complete PR at closeout head a5bb4bec, including the PM resolution evidence, released items, and regenerated CHANGELOG.md.

✅ Action performed

Full review finished.


Your included review limit is currently reached under our Fair Usage Limits Policy. This review may still proceed through usage-based billing if eligible. Your next included review will be available in 31 minutes.

@unbraind

Copy link
Copy Markdown
Owner Author

Final exact-head review disposition for a5bb4bec:

  • All required checks passed again after PM closeout and generated changelog changes.
  • CodeRabbit returned terminal success with its documented size/usage limit and no inline finding; the fresh response received a positive usefulness reaction.
  • Hosted Greptile produced no review surface after the final request; the authenticated gate had already returned free_reviews_limit_reached, recorded on canonical pm-e02lgu.
  • No new Sourcery, Gemini, Codecov, CodSpeed, or other bot comment/review appeared. Existing bot surfaces retain their explicit usefulness reactions.
  • Review threads: zero total, zero unresolved.

@unbraind
unbraind merged commit c68469d into main Jul 25, 2026
32 checks passed
@unbraind
unbraind deleted the feat/sdk-surface-contract-and-transport-budgets branch July 25, 2026 12:08
@unbraind

unbraind commented Aug 4, 2026

Copy link
Copy Markdown
Owner Author

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment