mirror of https://github.com/ModernRelay/omnigraph.git synced 2026-06-12 01:45:14 +02:00

Ragnor Comerford 1786c87772

docs(dev): RFC 001 — inline + stored queries, envelope, MCP

Tracked artifact consolidating the design across MR-656 (this branch),
MR-976 (Phase 1 envelope hardening parent, with MR-977/978/979/980
sub-issues), and MR-969 (stored queries + MCP).

Sections:

* Two paths, one engine — inline `/query` + `/mutate` (this PR) coexist
  with stored `/queries/{name}` (MR-969). Same `run_query` / `run_mutate`
  backend (the fold-in landed in the previous commit).
* Request envelope ("before") — Idempotency-Key, If-Match, X-Deadline,
  X-Trace-Id, expect, dry_run, fields. Phase 1 ships the load-bearing
  subset on `/mutate`.
* Response envelope ("after") — audit_id, snapshot_id, commit_id, stats,
  warnings. Closes the provenance loop today's `ChangeOutput` leaves
  open.
* `.gq` pragmas — `@description`, `@returns`, `@mcp`. Source-of-truth
  for the stored-query agent contract; no separate YAML registry.
* Multi-graph MCP — per-graph `/graphs/{id}/mcp/tools` + `/mcp/invoke`.
  Token binds to one graph by default; cross-graph agents loop.
* Cedar split — `read`/`change` for inline, `invoke_query` for stored.
  Operators deny ad-hoc for agent groups while keeping curated tool
  list open.
* Rejected alternatives — per-env override files, compiled bundles,
  tool-name prefixing across graphs, body-field graph dispatch.

Index entry added under "Active Implementation Plans" so future agents
land on the RFC before touching queries / mutations / envelope code.
`scripts/check-agents-md.sh` clean (35 links, 34 docs).

2026-05-29 11:36:21 +02:00

3 KiB

Raw Blame History

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	runs.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.

3 KiB Raw Blame History