mirror of https://github.com/ModernRelay/omnigraph.git synced 2026-06-09 01:35:18 +02:00

Ragnor Comerford a335d98854

Refactor AGENTS.md from encyclopedia to map; move spec into docs/

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>

2026-04-28 23:31:08 +02:00

1.6 KiB

Raw Blame History

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

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.
Mutations on run_branch (via the normal write APIs) — isolated from concurrent activity on the target.
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) into the target.
- On success: status = Published, published_snapshot_id set, run branch cleaned up asynchronously.
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).

1.6 KiB Raw Blame History