pm-vcs-sdk-exemplar

Tracker: namespace ownership pm-6z0wzf, SDK exemplar pm-xtrd, acceptance story pm-8ngt, atomic SDK transactions pm-4e12, graph SDK pm-ju83.

pm-vcs-sdk-exemplar is the first deliberately non-project-management package in the first-party ecosystem. It proves that public pm SDK and extension contracts can model a small version-control domain without importing src/core, reading item files directly, or adding VCS policy to the core CLI.

The exemplar provides:

• Changeset and VcsRef custom item types;
• draft -> proposed -> merged|abandoned domain lifecycle;
• collision-free vcs-exemplar ref-create, create, propose, merge, abandon, show, and log commands, with internal vcs compatibility spellings retained for existing local consumers;
• a beforeCommand hook enforcing explicit reviewed-merge affirmation;
• point-in-time changeset reconstruction through getItemAt;
• a durable, optimistic, append-only commits_to relationship stream projected through RelationshipEventStore.project;
• a crash-resumable commitWorkspaceTransaction merge that coordinates item lifecycle and relationship events with append-only compensation.

Install and stage the domain

pm install vcs-exemplar --project
pm profile apply vcs
pm package doctor --project --isolated --detail deep --json
pm contracts --command "vcs-exemplar merge" --flags-only --json

The package registers live types and fields globally, so the manifest does not use narrow command activation. Applying the profile stages custom statuses and the Changeset transition graph idempotently.

End-to-end changeset flow

pm vcs-exemplar ref-create main --author demo
pm vcs-exemplar create "Add durable projection" --ref <ref-id> --tree-hash sha256:abc --author demo
pm vcs-exemplar propose <changeset-id> --author demo
pm vcs-exemplar show <changeset-id> --at 1
pm vcs-exemplar merge <changeset-id> --ref <ref-id> --reviewed --author demo
pm vcs-exemplar log

vcs-exemplar show --at reconstructs immutable item history. vcs-exemplar log independently projects the package-owned relationship JSONL stream, proving that current item state and graph event state are both rebuildable from public SDK contracts. vcs-exemplar merge publishes success only after its SDK transaction journal commits; ordinary failures compensate in reverse order, and retrying the same merge id resumes any interrupted forward or compensation phase.

Package boundary

All runtime imports use @unbrained/pm-cli/sdk. The exemplar intentionally does not implement content-addressed object storage, a working tree, filesystem diffing, or a network protocol. Those are Git product features; this package tests the reusable context, lifecycle, history, graph, package, and policy primitives beneath them.

See GAP_REPORT.md for the concrete primitive assessment.