mirror of
https://github.com/ModernRelay/omnigraph.git
synced 2026-06-15 01:55:13 +02:00
77dffdae92
Remove developer-only scaffolding that leaked into the public user/operator docs, while preserving every user-facing behavior, command, flag, endpoint, constant, and env var. No behavior changes. Removed across 18 files: - internal ticket / sequencing refs (MR-NNN, RFC-NNN, "Phase N"); - source-code paths (crates/**/*.rs, *.pest) and internal struct/function dumps (e.g. the QueryIR / GraphCommit / SchemaMigrationPlan Rust types, internal fn names like fork_branch_from_state, optimize_all_tables); - Lance-internal blocker prose (upstream issue numbers, blob-decode cause, sidecar Phase-B/C mechanics) — keeping the user-visible behavior (e.g. "optimize skips Blob-column tables; reads/writes unaffected"); - pre-v0.4.0 Run-state-machine archaeology. Internal IR/lowering/recovery-internals sections were either trimmed to a brief user-facing note (e.g. "Traversal execution", "interrupted writes recover automatically; recovery commits are recorded under actor omnigraph:recovery") or removed. Kept: all language syntax, lint codes, Cedar actions/scopes, endpoints, error taxonomy, every constant and env var (verified none dropped from the constants cheat-sheet), and the operator-facing explanations of on-disk artifacts. Residual "legacy" mentions are all user-facing (the deprecated omnigraph.yaml, the legacy token chain, old command names). Verified: zero internal-scaffolding leaks (MR/RFC/Phase/.rs/.pest = 0) across docs/user; zero broken links; check-agents-md.sh green. Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
40 lines
2.5 KiB
Markdown
40 lines
2.5 KiB
Markdown
# Branches, Commits, Snapshots
|
|
|
|
## L1 — Lance per-dataset branches
|
|
|
|
Lance supports branching at the dataset level: a branch is a named lineage of versions, and a copy-on-write fork creates a new branch from a source branch at a given version.
|
|
|
|
## L2 — Graph-level branches
|
|
|
|
OmniGraph builds *graph branches* on top by branching every sub-table coherently:
|
|
|
|
- **Create** (`branch create` / `branch create --from <target>`) — the name `main` is disallowed; fails if the branch exists. Atomic: the new branch becomes visible all-or-nothing, so a name never half-exists.
|
|
- **List** (`branch list`) — returns public branches, **filtering the internal** `__schema_apply_lock__` branch.
|
|
- **Delete** (`branch delete`) — refuses if there are descendants on the branch, or if it is the current branch. Once deleted, the branch is gone from every snapshot. The owned per-table forks are reclaimed best-effort; if that reclaim hits a transient object-store error, the leftover storage is reclaimed later by the [`cleanup`](../operations/maintenance.md) command. One consequence: if a delete's reclaim fails, reusing that branch name before the next `cleanup` surfaces a clear error pointing at `cleanup`.
|
|
- **Lazy forking**: a branch only forks a sub-table when that sub-table is first mutated on it. Pure-read branches share storage with their source. If two writers race to first-write the same branch, the loser gets a retryable "refresh and retry".
|
|
|
|
## L2 — Commit graph
|
|
|
|
Each graph commit carries a ULID id, the manifest branch and version it published, its parent commit (two parents for a merge commit, one for a linear commit), the actor who made it, and a creation timestamp.
|
|
|
|
- Every successful publish (load / change / merge / schema apply) appends one commit.
|
|
- Merge commits have two parents; linear commits have one.
|
|
- Inspect history with `commit list` and `commit show`.
|
|
|
|
## L2 — Snapshots & time travel
|
|
|
|
Reading a branch at a past version, or a single entity at a past version, is
|
|
covered on the [time travel](time-travel.md) page. Merging branches and the
|
|
conflict kinds are on the [merge](merge.md) page.
|
|
|
|
## L2 — Internal system branches
|
|
|
|
- `__schema_apply_lock__` — serializes schema migrations; filtered from `branch list` but used internally.
|
|
|
|
## L2 — Recovery audit trail
|
|
|
|
Interrupted multi-table writes are recovered automatically the next time the graph is opened read-write. Recovery commits are recorded in the audit trail under the actor `omnigraph:recovery`, so you can find them with:
|
|
|
|
```bash
|
|
omnigraph commit list --filter actor=omnigraph:recovery
|
|
```
|