mirror of
https://github.com/ModernRelay/omnigraph.git
synced 2026-06-09 01:35:18 +02:00
2d5c4b1202
Some checks failed
CI / Classify Changes (push) Has been cancelled
CI / Check AGENTS.md Links (push) Has been cancelled
CI / Container Entrypoint (push) Has been cancelled
Release Edge / Prepare edge release (push) Has been cancelled
CI / Test Workspace (push) Has been cancelled
CI / Test omnigraph-server --features aws (push) Has been cancelled
CI / Test Windows release binaries (push) Has been cancelled
CI / RustFS S3 Integration (push) Has been cancelled
Release Edge / Build edge omnigraph-linux-x86_64 (push) Has been cancelled
Release Edge / Build edge omnigraph-macos-arm64 (push) Has been cancelled
Release Edge / Build edge omnigraph-windows-x86_64 (push) Has been cancelled
Release Edge / Smoke Windows installer (push) Has been cancelled
The Run state machine was removed in MR-771 (v0.4.0); `docs/dev/runs.md` and `crates/omnigraph/tests/runs.rs` have since documented and tested the direct-publish write path, so the "runs" name was misleading. - git mv docs/dev/runs.md → docs/dev/writes.md (reframe H1 + intro; keep MR-771 history note) - git mv crates/omnigraph/tests/runs.rs → tests/writes.rs (reframe header) - repoint every runs.md / runs.rs reference across docs, AGENTS.md, and source comments - fix four pre-existing broken `docs/runs.md` links (the file never lived at that path) to `docs/dev/writes.md` - fix the stale v0.4.0 anchor to the live section No behavior change: every source edit is a comment. Engine builds and the renamed test passes 25/25; scripts/check-agents-md.sh passes. The run-removal cleanup itself (run_registry.rs guard, __run__ prefix) is deferred to MR-770.
3.1 KiB
3.1 KiB
Developer Docs
Audience: contributors, maintainers, and coding agents
This is the contributor-facing entry point. These docs explain architecture, invariants, implementation contracts, test ownership, and upstream Lance constraints. User-facing behavior should still be documented through docs/user/index.md and the relevant public reference docs.
Required For Every Non-Trivial Change
| Need | Read |
|---|---|
| Architectural rules, known gaps, deny-list | invariants.md |
| Upstream Lance source-of-truth index | lance.md |
| Existing test coverage and test placement | testing.md |
Architecture And Storage
| Area | Read |
|---|---|
| System structure, L1/L2 framing, component diagrams | architecture.md |
| On-disk layout, manifest schema, URI behavior | storage.md |
| Direct-publish writes, D2, staged writes, recovery sidecars | writes.md |
| Query execution, mutation execution, loader flow | execution.md |
| Index lifecycle and graph topology indexes | indexes.md |
| Branch and commit internals | branches-commits.md |
| Three-way merge implementation and conflicts | merge.md |
| Diff/change-feed implementation | changes.md |
| Branch protection policy | branch-protection.md |
| CODEOWNERS source of truth | codeowners.md |
Language, Runtime, And Boundaries
| Area | Read |
|---|---|
| Schema grammar, catalog, migration planner | schema-language.md |
| Query grammar, IR, lints, mutation restrictions | query-language.md |
Embedding client and @embed integration |
embeddings.md |
| Cedar policy surface and server gating | policy.md |
| Server auth, OpenAPI, endpoint handlers | server.md |
| Error taxonomy and serialization | errors.md |
| Constants and tunables | constants.md |
| Transaction model public contract | transactions.md |
Project Operations
| Area | Read |
|---|---|
| CI and release workflows | ci.md |
| Install and deployment packaging | install.md, deployment.md |
| Release history | releases/ |
Active Implementation Plans
Working documents for in-flight feature work. Removed when the work lands.
| Area | Read |
|---|---|
Schema-lint chassis v1 (MR-694) — --allow-data-loss, soft/hard drops |
schema-lint-v1-plan.md |
| Inline + stored queries, request/response envelope, MCP (MR-656 / MR-976 / MR-969) | rfc-001-queries-envelope-mcp.md |
Boundary
Developer docs may mention implementation details, stale gaps, upstream Lance blockers, and review rules. User docs should not require that context unless the detail changes the public contract.