Repository navigation
SDK relationship event platform and public VCS exemplar - #587
Conversation
Register extension-owned relationship ontologies across SDK, CLI, MCP graph assembly, policy contracts, and declarative composition. Add deterministic relationship event streaming/projection plus host-bound extension command services with reentrant-safe native SDK dispatch. Ship the first-party pm-vcs beyond-PM exemplar with custom schema, lifecycle commands, reviewed merge policy, point-in-time history, durable graph projection, full docs, tracker evidence, generated changelog, and exact 100% repository coverage.
Carry SDK authors into extension-host clients, serialize independent VCS merge events without stale optimistic versions, preserve registered relationship payload schemas, and reject malformed registration containers. Document the intentional stream checkpoint boundary and record the complete pre-push Greptile findings in pm.
Make deterministic merge events recoverable across tracker-item and relationship-ledger partial failures. Retry either persisted side, reject conflicting event identities, and cover both failure directions with source-level acceptance tests.
📝 WalkthroughWalkthroughAdds a first-party VCS SDK exemplar with changeset/ref commands, custom relationship kinds, durable event streaming and projection, and active-host command SDK plumbing. It also updates extension contracts, graph assembly, tests, documentation, package catalogs, and project-management records. ChangesVCS SDK exemplar
Estimated code review effort: 4 (Complex) | ~60 minutes Possibly related issues
Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
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. Comment |
|
@greptileai Please perform a full review of exact head |
|
@coderabbitai full review Please review the complete broad SDK relationship-event platform and VCS exemplar on exact head |
|
✅ Action performedFull review finished. |
Merging this PR will regress 5 benchmarks
|
| Benchmark | BASE |
HEAD |
Efficiency | |
|---|---|---|---|---|
| ❌ | build index (2000 docs x 80 words) |
161.3 ms | 161.4 ms | -0.02% |
| ❌ | decodeQueryCursor |
115.9 µs | 115.9 µs | -0.02% |
| ❌ | jaccardSimilarity |
153.3 µs | 153.3 µs | -0.01% |
| ❌ | tokenizeAlphaNumeric |
367.3 µs | 367.3 µs | -0.01% |
| ❌ | normalizeLowercaseWhitespace |
135.8 µs | 135.8 µs | 0% |
| ⚡ | createQueryFingerprint |
515.8 µs | 515.2 µs | +0.12% |
| ⚡ | encodeQueryCursor |
101 µs | 101 µs | +0.05% |
| ⚡ | build index (200 docs x 40 words) |
8.4 ms | 8.4 ms | +0.03% |
| ⚡ | stableStringify (nested contract) |
161.2 µs | 161.2 µs | +0.02% |
| ⚡ | tokenize + score query over 2000 docs |
7.5 ms | 7.5 ms | +0.01% |
| ⚡ | score query over 2000 docs |
5.6 ms | 5.6 ms | 0% |
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-vcs-domain-event-platform (c392182) with main (70cdc8c)
There was a problem hiding this comment.
Code Review
This pull request introduces a new, non-PM domain package pm-vcs as an SDK exemplar to model a minimal VCS-style changeset workflow. It adds custom relationship-kind registration to the extension API, injects host-bound SDK services into extension commands, and implements bounded stream and projection capabilities for relationship event logs and stores. The review feedback focuses on enhancing backward compatibility and robustness. It suggests adding defensive nullish coalescing guards (?? []) and documenting them with inline comments when accessing the newly introduced relationship_kinds field to prevent crashes with legacy payloads. It also recommends allowing undefined in type checks for optional fields like ordering and allowSelf in relationships.ts and defaulting them to false during normalization.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/pm-vcs/extensions/vcs/index.ts`:
- Around line 322-340: Reorder the merge flow in
packages/pm-vcs/extensions/vcs/index.ts around the relationship append and
changeset update: append or reuse the validated stable merge event before
updating the proposed item, then reconcile the item state on retries while
preserving idempotency. Update packages/pm-vcs/GAP_REPORT.md at line 21 to
retain the event-first claim; no other sites require changes.
- Around line 267-284: Validate the required ref option in the changeset
creation flow before calling clientFor(context).create: confirm it resolves to
an existing item whose type is VcsRef, and reject otherwise without persisting a
changeset. Keep the validated ref value in the existing vcs_ref field, and add
coverage for both nonexistent IDs and IDs belonging to another item type.
In `@packages/pm-vcs/GAP_REPORT.md`:
- Line 21: The merge flow must append the relationship event before updating
terminal item state, matching the documented event-first ordering. Reorder the
relevant merge operation so relationship-event persistence completes first, then
apply the terminal item update while preserving stable relationship identity and
retry safety.
In `@packages/pm-vcs/package.json`:
- Line 34: Update the report catalog entry in package metadata to link to the
package’s advertised GAP_REPORT.md document instead of the generic GitHub issue
tracker URL.
In `@tests/unit/packages/vcs-extension.spec.ts`:
- Around line 287-292: Wrap the test body following
setActiveExtensionRegistrations in a try/finally block so cleanup always runs
after assertions or other failures. In finally, call
resetActiveExtensionRuntimeState and assertExtensionDeactivated(await
harness.deactivate()); apply the same cleanup structure to the corresponding
setup around the additional referenced location.
In `@tests/unit/sdk/relationship-history-projection.spec.ts`:
- Around line 94-132: Clean up the mkdtemp workspace created in the “streams and
projects one coherent durable snapshot” test by importing rm from
node:fs/promises and wrapping the test body in try/finally, removing the
temporary directory recursively in the finally block.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI (base), Organization UI (inherited)
Review profile: ASSERTIVE
Plan: Pro
Run ID: 0f13556f-54d8-4bd9-859d-21e6552971ea
📒 Files selected for processing (45)
.agents/pm/epics/pm-qwoy.toon.agents/pm/features/pm-ju83.toon.agents/pm/features/pm-xtrd.toon.agents/pm/history/pm-7zs0.jsonl.agents/pm/history/pm-8ngt.jsonl.agents/pm/history/pm-ju83.jsonl.agents/pm/history/pm-qwoy.jsonl.agents/pm/history/pm-um4g.jsonl.agents/pm/history/pm-v1yo.jsonl.agents/pm/history/pm-xtrd.jsonl.agents/pm/issues/pm-um4g.toon.agents/pm/issues/pm-v1yo.toon.agents/pm/reminders/pm-7zs0.toon.agents/pm/stories/pm-8ngt.toonCHANGELOG.mddocs/EXTENSIONS.mddocs/SDK.mdpackages/pm-vcs/GAP_REPORT.mdpackages/pm-vcs/README.mdpackages/pm-vcs/extensions/vcs/index.tspackages/pm-vcs/extensions/vcs/manifest.jsonpackages/pm-vcs/extensions/vcs/package.jsonpackages/pm-vcs/package.jsonsrc/cli/main.tssrc/core/extensions/activation-summary.tssrc/core/extensions/capability-usage.tssrc/core/extensions/extension-hook-runtime.tssrc/core/extensions/extension-registries.tssrc/core/extensions/extension-types.tssrc/core/extensions/loader.tssrc/sdk/compose.tssrc/sdk/dependencies.tssrc/sdk/extension-command-context.tssrc/sdk/graph/assembly.tssrc/sdk/relationship-history.tssrc/sdk/relationships.tssrc/sdk/runtime-input.tssrc/sdk/runtime.tstests/fixtures/contracts/full.jsontests/integration/cli.integration.spec.tstests/integration/init-path-guard.integration.spec.tstests/unit/extensions/extension-command.spec.tstests/unit/packages/vcs-extension.spec.tstests/unit/sdk/extension-relationship-kinds.spec.tstests/unit/sdk/relationship-history-projection.spec.ts
Validate VCS refs before changeset creation, preserve event-first crash reconciliation with idempotent retries, and keep package diagnostics routed to the bundled gap report. Harden legacy activation compatibility, document graph registration fallbacks, guarantee test cleanup, and lock strict relationship-kind semantics with full coverage.
|
CodeRabbit walkthrough acknowledged: the draft-skip status and broad change summary were reviewed. The explicit full review completed separately; all six actionable inline findings have now been reacted to, answered, resolved, and addressed in dff9f36. |
|
CodSpeed report acknowledged: the reported aggregate delta is 0.01% across mixed runtime environments and only touches unchanged pagination, BM25, and text-normalization benchmarks. This PR changes none of those hot paths; the signal is below meaningful noise and requires no product change. |
|
CodeRabbit review acknowledged in full: all six inline findings were accepted, implemented, reacted to, answered, and resolved on dff9f36. Focused acceptance, typecheck, lint, and exact 100% full coverage pass. |
|
Greptile hosted summary acknowledged. Its platform-level review was read alongside the two completed local Greptile rounds; the valid crash-consistency and SDK findings are incorporated, and dff9f36 is ready for an exact-head re-review. |
|
Gemini review acknowledged in full: all six inline comments were reacted to and answered. Four compatibility/documentation findings were applied; the two defaulting proposals were declined because ordering and allowSelf are required public contract fields, with new missing-field rejection tests proving the intended boundary. |
|
Codecov report acknowledged: hosted coverage was green on the reviewed head, and exact-current dff9f36 independently passes 308 files / 5,896 tests at 100% statements, branches, functions, and lines. |
|
Sourcery review acknowledged: the bot reported a service rate-limit condition and supplied no actionable code finding. No code change is justified for that external availability result. |
|
@greptileai Please perform a full exact-head re-review of dff9f36. The first hosted findings are implemented or explicitly contract-rejected in their threads; inspect SDK public API design, extension isolation, event concurrency, crash consistency, security, and the new regression tests. |
|
@coderabbitai full review\n\nPlease re-review the complete broad PR at exact head dff9f36. All first-round comments were individually reacted to, answered, resolved, and validated with 5,896 tests at exact 100/100/100/100 coverage. |
|
✅ Action performedFull review finished. Your plan includes PR reviews subject to rate limits. More reviews will be available in 20 minutes. |
|
CodeRabbit exact-head re-review acknowledged: the full dff9f36 review finished with no new inline findings. Its temporary plan-rate-limit notice is external and non-actionable; the completed result is clean. |
|
CodeRabbit's six empty follow-up review records were inspected. They are automated acknowledgements associated with the six answered CodeRabbit threads, contain no additional findings, and have each been reacted to. |
|
Sourcery's second review record was inspected and reacted to; it repeats the external weekly diff-character rate limit and contains no code finding. |
|
Greptile exact-head review acknowledged: the dff9f36 review check passed, its review submission contains no finding, and the exact-head inventory has zero unresolved threads. |
Refresh and verify deterministic merge winners when another process wins the durable append lock. Preserve unrelated storage failures, reject missing or conflicting winners with causal errors, and cover every concurrency outcome at exact repository-wide 100 percent coverage.
|
@greptileai Please re-review exact head c392182, specifically the duplicate deterministic append race from thread PRRT_kwDORSgRDc6R-X1z and its matching, missing, conflicting, and unrelated-error failure-injection coverage. Then inspect the complete broad PR for regressions. |
|
@coderabbitai full review\n\nPlease re-review the complete PR at exact head c392182 after the Greptile P1 concurrency correction. Validate deterministic append race recovery, causal failures, SDK/package boundaries, and the exact 100% coverage tests. |
|
✅ Action performedFull review finished. Your plan includes PR reviews subject to rate limits. More reviews will be available in 5 minutes. |
|
CodeRabbit final exact-head review acknowledged: the complete c392182 re-review finished with no new findings. The temporary plan-rate-limit note is external and non-actionable; all exact-head checks and review threads are clean. |
Summary
This broad SDK/CLI platform PR makes extension-owned domain modeling substantially more capable and proves it with a first-party VCS implementation built on public SDK contracts.
@unbrained/pm-vcsexemplar: custom types, fields, lifecycle, relationship ontology, seven domain commands, hooks, time travel, durable projections, and crash-consistent merge reconciliationpm lineage
Validation
npxsmoke: version 2026.7.18, all 13 packagespnpm audit: zero vulnerabilitiespnpm release:gates: passedReview history
ffc25364-c837-48d8-8fd1-ce6f2540180e: five findings fixedcc0177cd-e16c-4bf8-9a4e-8fa900447367: found the two-store partial-write riskb8b40b51: confidence 5/5, zero commentsThe VCS merge protocol now reconciles either partial-write direction using deterministic event identity and fails closed on conflicting events; failure-injection tests cover ledger-first, item-first, and conflict states.
Summary by cubic
Adds extension-owned relationship kinds and deterministic relationship event streams with reducer-based projections, and ships a public VCS exemplar built entirely on the SDK. Unlocks non-PM domain modeling and delivers a reviewed merge workflow with crash-consistent reconciliation.
New Features
@unbrained/pm-vcs: custom types/fields, domain lifecycle, sevenvcscommands, time travel, durablecommits_tostream, merge policy via hook, and ref validation before changeset creation.Bug Fixes
Written for commit c392182. Summary will update on new commits.