mirror of
https://github.com/ModernRelay/omnigraph.git
synced 2026-06-09 01:35:18 +02:00
a335d98854
Splits the 990-line AGENTS.md into a 184-line map (architecture, where-to-find index, always-on invariants, capability matrix, maintenance contract) plus 18 new docs/*.md files holding the deep content per topic (storage, schema and query languages, indexes, embeddings, branches/commits, runs, merge, changes, execution, policy, server, CLI reference, audit, errors, CI, constants, v0.3.1 notes). Adds scripts/check-agents-md.sh and a check_agents_md CI job that verifies every docs/ link in AGENTS.md resolves and every doc in the canonical set is linked. CLAUDE.md remains a symlink to AGENTS.md. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
38 lines
1.6 KiB
Markdown
38 lines
1.6 KiB
Markdown
# Runs (transactional graph mutations)
|
|
|
|
`db/run_registry.rs` + run lifecycle in `db/omnigraph.rs`. Stored in `_graph_runs.lance` and `_graph_run_actors.lance`.
|
|
|
|
## RunRecord
|
|
|
|
```
|
|
RunRecord {
|
|
run_id: RunId (ULID),
|
|
target_branch: String, // where the run will publish
|
|
run_branch: "__run__<id>", // ephemeral isolation branch
|
|
base_snapshot_id: String,
|
|
base_manifest_version: u64,
|
|
operation_hash: Option<String>, // idempotency key
|
|
actor_id: Option<String>,
|
|
status: Running | Published | Failed | Aborted,
|
|
published_snapshot_id: Option<String>,
|
|
created_at, updated_at: i64 (microseconds),
|
|
}
|
|
```
|
|
|
|
## Lifecycle
|
|
|
|
1. `begin_run(target_branch, op_hash)` / `begin_run_as(target_branch, op_hash, actor_id)` — forks `__run__<id>` from the target's current head, appends a `RunRecord`.
|
|
2. Mutations on `run_branch` (via the normal write APIs) — isolated from concurrent activity on the target.
|
|
3. `publish_run(id)` / `publish_run_as(id, actor)`:
|
|
- **Fast path**: if the target hasn't moved since `base_snapshot_id`, promote the run snapshot directly.
|
|
- **Merge path**: if it has moved, perform a three-way merge (see [merge.md](merge.md)) into the target.
|
|
- On success: `status = Published`, `published_snapshot_id` set, run branch cleaned up asynchronously.
|
|
4. `abort_run(id)` / `fail_run(id)` — terminal; cleans up run branch best-effort.
|
|
|
|
## Idempotency
|
|
|
|
`operation_hash` is an optional field clients can use to detect a duplicate `begin_run` retry.
|
|
|
|
## Cleanup
|
|
|
|
`cleanup_terminal_run_branches_for_target(branch)` is called as branches change; failures are swallowed (lazy cleanup on next branch op).
|