SDK relationship event platform and public VCS exemplar

Merged
UN
4mo ago
+2325-43

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.

  • adds extension-contributed relationship-kind registration, validation, capability attribution, composition, and native workspace graph assembly
  • adds bounded immutable relationship event streams and reducer-based projections for in-memory and durable stores
  • injects a host-bound SDK into extension command handlers while avoiding activation-queue re-entry
  • adds the @unbrained/pm-vcs exemplar: custom types, fields, lifecycle, relationship ontology, seven domain commands, hooks, time travel, durable projections, and crash-consistent merge reconciliation
  • carries SDK caller authorship into extension-owned durable events
  • documents the extension and SDK surfaces and records follow-up gaps

pm lineage

Validation

  • full repository: 308 test files / 5,893 tests
  • exact coverage: 100% statements, branches, functions, and lines
  • typecheck, ESLint, zero-clone/static quality, 100% docstrings, package boundaries, token budgets, docs/contracts, version sync, and secret scan
  • packed npx smoke: version 2026.7.18, all 13 packages
  • 88-command package-first dogfood
  • isolated packed-artifact VCS acceptance across fresh processes, including normal core create/get, doctor, and validation
  • pnpm audit: zero vulnerabilities
  • full pnpm release:gates: passed

Review history

  • Greptile run ffc25364-c837-48d8-8fd1-ce6f2540180e: five findings fixed
  • clean re-review: confidence 5/5, zero comments
  • release-gate run cc0177cd-e16c-4bf8-9a4e-8fa900447367: found the two-store partial-write risk
  • targeted crash-consistency re-review on b8b40b51: confidence 5/5, zero comments
  • final committed-head release gates: passed

The 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

    • Register and validate relationship kinds with strict semantics; graph assembly uses extension ontologies.
    • Append-only relationship event log/store with bounded streaming and reducer projections; supports point-in-time reads.
    • Inject a host-bound SDK into extension command handlers; carries caller authorship.
    • New @unbrained/pm-vcs: custom types/fields, domain lifecycle, seven vcs commands, time travel, durable commits_to stream, merge policy via hook, and ref validation before changeset creation.

  • Bug Fixes

    • Crash-consistent merge reconciliation for partial writes and duplicate append races using deterministic event identity with idempotent retries and winner verification; preserves event-first recovery.
    • Legacy activation compatibility and graph registration fallbacks; strict relationship-kind validation; guaranteed test cleanup.