KG versioning: snapshots, branches, and remotes

[ohdearquant]

Summary

Build the versioning primitives that turn khive into "git for knowledge graphs": content-addressed snapshots, named branches, and remote push/pull. Strategic direction documented in ADR-010.

Phasing

Depends on #1 (KG merge) shipping first — versioning without merge is useless.

v0.6 — local versioning

• Snapshot primitive: content-addressed hash of graph state at time T (immutable).
• Branch primitive: named mutable pointer to a snapshot.
• khive commit -m "..." — create a snapshot from current namespace state.
• khive checkout <branch> — switch namespace to point at a branch's head.
• khive log — walk snapshot history.

v0.7 — remote sync

• Remote primitive: connection to another khive instance.
• khive push origin main — upload snapshots not present at remote.
• khive pull origin main — download remote snapshots, three-way merge into local.
• Authentication: per-remote auth (API key for v0.7, OAuth later).
• Federation protocol: TBD (SPARQL endpoints? Custom Bolt-like? GraphQL?).

v1.0 — social layer

• Forks of public graphs.
• PRs on proposed changes with review UI.
• Issues/discussion on entities and edges.
• The "GitHub" layer above "git."

Primitives

pub struct Snapshot {
    pub id: SnapshotId,              // content-addressed hash
    pub parent: Option<SnapshotId>,
    pub created_at: i64,
    pub namespace: Namespace,
    pub message: String,
    pub author: Option<String>,
}

pub struct Branch {
    pub name: String,
    pub namespace: Namespace,
    pub head: SnapshotId,
}

pub struct Remote {
    pub name: String,                // "origin"
    pub url: String,                 // grpc/http endpoint
    pub auth: Option<RemoteAuth>,
}

Open questions

1. Snapshot storage: separate "objects" directory (git-style) or backend-native? Likely git-style for sharing efficiency.
2. Snapshot granularity: per-namespace, per-project, sub-graph? Default to per-namespace.
3. Federation protocol: SPARQL? GraphQL? Custom? Defer to v0.7 design phase.
4. Conflict resolution UX: CLI (like git) vs web UI vs hybrid. Web UI essential for the GitHub layer.

Priority

P3 — strategic direction, depends on #1 (merge) and earlier foundation crates.

References

• ADR-010: KG Versioning Direction
• Related: KG merge: combine two graph states with conflict detection #1 (KG merge)