apunkt/omnigraph
1
0
Fork 0
mirror of https://github.com/ModernRelay/omnigraph.git synced 2026-06-15 01:55:13 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

docs: document V1a config/CLI (version/storage/servers/--graph); mark RFC landed

Browse source 
Sweep `--target` → `--graph` across the user docs (cli-reference, cli, server,
policy) and update `omnigraph.example.yaml` to the v1 schema (`version: 1`,
`storage:`, `servers:`/`server:`). Add the typed-locator schema (version/storage/
servers/graph_id + strictness) to cli-reference, and a server "embedded graphs
only" note. The RFC gets an Implementation-status banner recording V1a as landed
and its divergences (`--target` removed outright — no alias; `uri:` deprecation-
warned) and corrects the stale `QueryRegistry`/config-location claims (it's in
`omnigraph-queries` / `omnigraph-config` now). testing.md gains a Config & CLI
note. Past release notes keep `--target` (accurate for those versions);
`--target-branch` untouched.
This commit is contained in:
Ragnor Comerford 2026-06-04 16:22:17 +02:00
parent c2db7b5002
commit 536eab3928
No known key found for this signature in database
7 changed files with 53 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

14
docs/dev/rfc-002-config-cli-architecture.md
View file

@ -4,6 +4,20 @@
**Supersedes:** the original additive-only draft (2026-05-30). This revision **embraces breaking changes** to remove ambiguity and conflation rather than carrying every legacy shape forward. It is gated behind a config `version:` field and ships compat aliases for the highest-traffic legacy keys, but it does not pretend the end-state is purely additive. Incorporates an implementation-readiness review: endpoint-bound credentials, layer identity trust, route-unification specifics, restored `query.roots`, and right-sized auth scope.
**Target release:** v0.8.x (phased — see Rollout)
**Implementation status — V1a "locator core" landed.** Shipped: the typed
`GraphLocator` (`storage:` XOR `server:`+`graph_id:`), a `servers:` map, version-gated
config strictness (no `version:` = lenient + deprecation-warned; `version: 1` = unknown
keys rejected at any depth, via `serde_ignored`), `omnigraph-server` rejecting remote
graph entries (embedded-only), and the `--graph` flag. **Divergences from this proposal as
built:** `--target` was **removed outright (no deprecated alias)** — a clean rename, not the
alias proposed below; and `uri:` is honored-but-deprecation-warned (not auto-rewritten to
`storage.uri`). **Crate-location corrections** (the "Reconciliation"/"Implementation"
sections below predate V0): the config schema now lives in the extracted `omnigraph-config`
crate, and `QueryRegistry` was extracted to `omnigraph-queries` (not "kept in
`omnigraph-server`"). Deferred: layered global-first config + merge/provenance + `config
view`, the `cli:`→`defaults:` / `server:`→`serve:` renames (V1-remainder), route unification
+ remote client (V2), and the auth model (V3).
## Summary
OmniGraph today reads one config file, `omnigraph.yaml`, from both the CLI (operating the embedded engine) and `omnigraph-server` (hosting graphs). The CLI **can** already reach a *single-graph* server — point a graph entry's URI at the endpoint and set `bearer_token_env` — but it **cannot address a specific graph on a multi-graph server**, has no named-server credential model, and does not work without a project file in the current directory. Those are the real gaps.

7
docs/dev/testing.md
View file

@ -39,6 +39,13 @@ The engine's `tests/` is the principal coverage surface; most graph-shaped behav
| `recovery.rs` | Open-time recovery sweep — sidecar I/O, classifier dispatch (NoMovement / RolledPastExpected / UnexpectedAtP1 / UnexpectedMultistep / InvariantViolation), all-or-nothing decision, roll-forward via `ManifestBatchPublisher::publish`, roll-back via `Dataset::restore`, audit row in `_graph_commit_recoveries.lance`, `OpenMode::ReadOnly` skip path |
| `composite_flow.rs` | Compositional/narrative end-to-end stories — multi-step flows that compose mechanics covered by other test files. Catches integration regressions where individual operations all pass their unit tests but their composition breaks (sequential merges, post-merge main writes, time-travel through merge DAG, reopen consistency over multi-merge histories). |
**Config & CLI (RFC-002 V1a)** — these live outside the engine `tests/` dir: the
version-gated config-strictness and `deprecation_warnings` tests are inline in
`omnigraph-config` (`src/lib.rs` test module); the `GraphLocator` discriminant +
graph-identity tests are inline in `omnigraph-cli` (`src/main.rs`) plus
`tests/cli.rs` / `tests/system_local.rs`; the server embedded-only rejection tests
are in `omnigraph-server/tests/server.rs` (`multi_graph_startup`).
## Fixtures
`crates/omnigraph/tests/fixtures/` holds the canonical schema (`.pg`), seed data (`.jsonl`), and queries (`.gq`) shared across tests. Reuse these before inventing new ones — the helpers harness already knows how to load them.