v0.1 is a deliberate pre-production cutover, not a compatibility
release. The package now teaches one revision-first model and exposes 18
functions around it. The older storage-shaped kg_* surface,
parallel write paths, and bundled demonstration applications are not
part of this design.
Existing development stores should be rebuilt from source records under the current contract. graft does not include migration aliases or a compatibility layer for the unreleased API.
What became simpler
One acceptance path
All candidate records become a GraftCommitPlan.
graft_commit() is the one internal function that accepts
revisions. graft_ingest() merely plans and commits when no
separate review is required; graft_review() turns readable
file edits into the same plan type.
There is no special OKF import mutation path, force-write path, or direct current-record update.
One authority for record content
Immutable revisions are authoritative. Current records, identity lookup, search, semantic relationships, and OKF files are rebuildable projections. This removes the need to reconcile multiple answers to “what is current?”
One public retrieval boundary
graft_get(), graft_find(),
graft_query(), and graft_history() replace a
larger family of storage- and projection-specific helpers. Advanced
reads are named, validated operations rather than arbitrary SQL.
graft_snapshot() and graft_at() bind those
reads to one accepted commit boundary.
graft_view_snapshot() recovers that exact path-free
boundary from a view.
A smaller package scope
The package contains the reusable knowledge layer. Example applications live outside the package so their Shiny, provider, and domain dependencies do not define graft’s runtime or documentation architecture. A public companion link will be added when that repository is ready; the package site does not point to an unpublished location.
The 18-function surface
| Lifecycle | Functions |
|---|---|
| Define and open |
graft_schema(), graft_open(),
graft_close()
|
| Propose and accept |
graft_provenance(), graft_plan(),
graft_commit(), graft_ingest()
|
| Retrieve and inspect |
graft_snapshot(), graft_at(),
graft_view_snapshot(), graft_get(),
graft_find(), graft_query(),
graft_history()
|
| Synchronize and integrate |
graft_sync(), graft_status(),
graft_review(), graft_tools()
|
The grouping follows user intent instead of internal subsystems. Reference documentation uses the same four groups.
Why S7, and why not everywhere
The redesign uses S7 for GraftSchema,
GraftProvenance, GraftCommitPlan,
GraftStore, GraftSnapshot, and
GraftView. These objects own invariants that must survive
across calls: contract digests, producer semantics, commit
preconditions, store and snapshot identity, and connection-bound view
state.
Records remain ordinary data frames, record sets remain named lists, and read results remain ordinary lists or data frames. The compiled LinkML or data-dict contract already supplies the domain type system. Mirroring each domain class in S7 would create two class systems without strengthening the acceptance boundary.
Intentional non-goals
v0.1 does not promise:
- backward compatibility with the unreleased
kg_*API; - in-place migration from development store formats;
- mutation through SQL, agent tools, or OKF files;
- an ORM that maps every contract class or table to an R class;
- automatic contract transformations for historical payloads; or
- bundled workflow applications.
These exclusions keep the package small enough to reason about and leave room to stabilize the correct semantics before production use.
Start with the new model
Use Getting started for the complete workflow, Architecture for the authority and projection model, and Change control for the exact commit preconditions.