README.md

OmniGraph RFCs

RFCs are durable decision records for changes that are costly to reverse or wide enough that implementation review alone cannot establish the right shape. All formal RFCs live in this directory and use one lifecycle, one metadata schema, and one number namespace. track records where a proposal came from; it does not change the review or acceptance rules.

The architectural invariants remain the hard boundary for every change. An RFC explains why a particular design is worth its long-term liability and records the evidence behind the decision; it cannot waive the invariants or deny-list.

When an RFC is required

Write an RFC before implementing:

• a new query, schema, CLI, HTTP, or SDK contract;
• an on-disk format, wire format, recovery protocol, or compatibility change;
• a new storage substrate or dependency that constrains future architecture;
• a cross-cutting correctness, authorization, or operational boundary; or
• an exception to a deny-list item or another hard-to-reverse choice.

Routine bug fixes, narrow refactors, dependency maintenance, and documentation corrections normally do not need an RFC. If the code can land safely and be reverted cheaply without committing the project to a lasting contract, an issue and implementation PR are usually enough.

File and heading format

• Filename: YYYY-MM-DD-kebab-title.md. The date is the day drafting started and equals the created frontmatter field. The author chooses it alone; no registry, issue, or PR has to allocate anything first.
• Heading: # RFC: Title.
• The RFC id is the filename without .md. A reference is a link whose text is the RFC title and whose target is the canonical RFC filename.
• 0000-template.md is reserved and is not an RFC.
• Two RFCs may share a date; their slugs differ. Two RFCs never share a slug on the same day. A retitled RFC keeps its filename; the decision log records the new title.
• Do not create pre-merge, final, v2, internal, or review-ledger copies. Revise the canonical file; preserve meaningful changes in its decision log.

Numbered RFCs 0001 to 0068

RFCs 0001 to 0068 use NNNN-kebab-title.md, the heading # RFC NNNN: Title, and the reference label RFC NNNN. That namespace is closed at 0068: no new number is allocated, and scripts/check-docs.py rejects any numbered filename outside the allocated and reserved numbers it lists. Numbers reserved by PRs that were open when the namespace closed (0047 and 0048 by PR #606, carried on by PR #791 and PR #793; 0050 by the rfc/0050-engine-crate-topology branch; 0056 by PR #670; 0059 by PR #675; 0060 by PR #677; 0067 and 0068 by PR #725) may still land under their reserved numbers. Every other gap is historical and is never reused or backfilled.

The numbered scheme allocated an identifier only at merge, so every draft carried a working number that went stale whenever another RFC merged first, and the rename touched the filename, frontmatter, heading, registry row, and every reference. A date the author owns removes the allocation step.

Required frontmatter

Every RFC uses exactly this schema:

---
rfc: "2026-09-15-short-descriptive-title"
title: "Short descriptive title"
track: maintainer
status: draft
implementation: not-started
authors:
  - Name or handle
created: 2026-09-15
updated: 2026-09-15
discussion: null
supersedes: []
superseded_by: []
blocked_on: []
---

Field rules:

• rfc is the RFC id: the filename without .md. Numbered RFCs keep their four-digit string.
• title matches the heading text.
• track is public or maintainer; both follow the same lifecycle.
• status is one of draft, accepted, rejected, or superseded.
• implementation is one of not-started, in-progress, partial, complete, removed, or n/a.
• authors is a non-empty list.
• created and updated use YYYY-MM-DD; created equals the filename's date prefix.
• discussion is a durable issue/PR URL or null.
• supersedes and superseded_by contain RFC ids as quoted strings. Update both sides when the relationship applies to the whole decision.
• blocked_on contains concrete evidence or dependency gates. Research being blocked is not a lifecycle status; it is a draft with a non-empty list.

Frontmatter is the only status and date authority. Do not repeat it in a table or a hand-written Status, Date, Author track, or Implementation field. The body may contain a dated disposition or implementation note when it adds context rather than restating metadata.

Lifecycle

draft ──maintainer decision──▶ accepted ──accepted replacement──▶ superseded
  ├──maintainer decision──▶ rejected
  └──maintainer-approved draft replacement────────────────────▶ superseded

• Draft: under design and review. A draft may live on the main branch so review and evidence have one durable home, but merge alone does not accept it. Product behavior must not claim authority from a draft.
• Accepted: maintainers approved the decision and its stated boundaries. Implementation status moves independently as work lands.
• Rejected: the decision was not adopted. Keep the record and concise rationale; use removed if an experiment shipped and was later deleted, otherwise n/a or not-started as appropriate.
• Superseded: another RFC owns the current decision or proposal. Link both directions and keep the old rationale intact.

A maintainer may consolidate or replace an unaccepted draft with another draft and mark the previous draft superseded. This transfers the proposal's ownership, not acceptance or implementation authority; the disposition must say that the replacement is still a draft. Reserve rejected for a decision not to adopt the proposal, rather than merely moving its continuing design into a replacement. An accepted RFC remains authoritative until its replacement is accepted: a draft cannot retire an accepted contract. Record reciprocal supersession metadata only when that disposition takes effect.

Acceptance requires all invariants, compatibility consequences, operational boundaries, and owned evidence gates to be explicit. A blocker owned by another RFC does not block an independently reviewable decision, but hidden shared dependencies do.

Process

1. Copy the template to YYYY-MM-DD-kebab-title.md, dated the day drafting starts.
2. Set every frontmatter field and open a PR in draft status.
3. Review the problem, user/operational behavior, invariants, substrate alignment, compatibility, evidence, alternatives, and rollout.
4. Record material review outcomes in the RFC's decision log. Do not maintain a separate review ledger. A post-merge amendment rewrites the body sentences it changes and its Decision-log entry names each sentence it supersedes, so the body alone stays current.
5. A maintainer decision changes the lifecycle to accepted or rejected.
6. Implementation PRs link the accepted RFC and update implementation plus any durable evidence or support boundary in the canonical file.
7. A later incompatible decision gets a new RFC and supersedes the old one.
8. An accepted RFC that replaces only part of an earlier RFC keeps that RFC's status. Its PR adds a > **RFC NNNN disposition:** note under the earlier RFC's title: what changed, Historical: sections, Current: remainder.

For Lance-dependent work, follow the Lance reading protocol and record the exact upstream version and surfaces reviewed. For test planning, extend existing owners according to the test map.

Registry

This table is the human index for the canonical RFC corpus. The first column links the canonical file; its text is the number for numbered RFCs and the created date for dated ones. Rows are in creation order: numbered RFCs first, then dated RFCs by date.

RFC	Decision	Track	Status	Implementation
0001	Branch merge by fragment adoption	maintainer	draft	not-started
0002	Config and CLI architecture	maintainer	superseded	partial
0003	MCP server surface	maintainer	draft	partial
0004	Cluster graph and schema apply	maintainer	accepted	complete
0005	Server boot from cluster state	maintainer	accepted	partial
0006	Object-storage cluster roots	maintainer	accepted	complete
0007	Per-operator configuration	maintainer	accepted	complete
0008	Retire omnigraph.yaml	maintainer	accepted	complete
0009	Unified embedded and remote access paths	maintainer	accepted	complete
0010	Explicit CLI planes	maintainer	superseded	partial
0011	CLI addressing and configuration	maintainer	accepted	complete
0012	Provider-independent embedding configuration	maintainer	accepted	complete
0013	Write-path latency and bounded history cost	maintainer	superseded	partial
0015	Ingest-time @embed reconciliation	maintainer	draft	not-started
0018	Streaming-ingest WAL on Lance MemWAL	maintainer	rejected	removed
0019	Heads and fences	maintainer	superseded	partial
0022	Unified graph-write protocol	maintainer	accepted	complete
0023	Substrate-native key-conflict fencing	maintainer	accepted	complete
0024	Durable table heads	maintainer	draft	not-started
0025	Checkpoint-pinned retention	maintainer	draft	not-started
0026	MemWAL streaming ingest	maintainer	rejected	removed
0027	Lineage-based merge deltas	maintainer	draft	not-started
0028	Stable schema identity and table incarnation	maintainer	accepted	complete
0029	Native Azure Blob storage	public	accepted	in-progress
0030	Graph diffs, change feeds and retained history	maintainer	accepted	partial
0031	Comparative cost harness	maintainer	draft	not-started
0032	Adversarial correctness harness	maintainer	draft	not-started
0033	Blob management	maintainer	accepted	partial
0034	Durable recovery authority and outcomes	maintainer	superseded	not-started
0035	Served operation ownership	maintainer	superseded	not-started
0036	Atomic runtime activation and graph availability supervision	maintainer	superseded	not-started
0037	Deterministic simulation harness	public	accepted	in-progress
0038	Typed storage failures	public	accepted	complete
0039	The end-to-end benchmark	public	accepted	in-progress
0040	System column namespace	public	accepted	in-progress
0041	Inline and stored queries	maintainer	accepted	partial
0042	Incarnation-suffixed native branch refs	maintainer	accepted	complete
0043	Full-text index compatibility and explicit rebuild	maintainer	accepted	complete
0044	Edge keys: derived edge identity	maintainer	draft	in-progress
0045	GQ logic tests	maintainer	draft	partial
0046	Read-only index status	maintainer	draft	not-started
0047	Search plan validation and result guarantees	public	draft	in-progress
0049	Control-plane seams: observe, readiness witness, bounded shutdown	maintainer	accepted	partial
0051	JSON output via Arrow	maintainer	draft	partial
0052	Managed control-plane CLI	maintainer	accepted	complete
0053	Offline data-token verification	maintainer	accepted	complete
0054	Default graph actor provenance	maintainer	rejected	removed
0055	Branch statements in GQ	maintainer	draft	in-progress
0057	Accepted-context reuse and bounded merge preparation	maintainer	accepted	in-progress
0058	Retained merged ancestry	maintainer	draft	not-started
0061	Managed cluster lifecycle and config preparation	maintainer	accepted	complete
0062	Manifest version as the table registration clock	maintainer	draft	in-progress
0063	Self-contained branch lineage	maintainer	draft	in-progress
0064	Explicit storage upgrades	maintainer	accepted	in-progress
0065	Isolated branch merge publication	maintainer	superseded	not-started
0066	One seam type for test-time behavior substitution	maintainer	draft	in-progress
0067	Detached table commits	maintainer	accepted	complete
0068	Graph commit record	maintainer	draft	not-started
2026-09-09	Identity credentials and applied policy authorization	maintainer	accepted	complete
2026-09-10	Server lifecycle and online deployment	maintainer	superseded	not-started
2026-09-14	Compatibility surfaces	maintainer	draft	not-started
2026-09-16	Session settings	maintainer	draft	in-progress
2026-09-18	Shared schema gate and the write critical section	maintainer	accepted	complete
2026-09-21	Detached-only tables	maintainer	accepted	in-progress
2026-09-24	Shared expression model	maintainer	draft	in-progress
2026-09-26	Self-contained server testing with GQT and DST	maintainer	draft	not-started
2026-09-29	Server runtime and online deployment	maintainer	accepted	in-progress
2026-09-30	Typed edge alternation and bounded wildcard traversal	maintainer	accepted	complete
2026-09-30	HTTP contract admission	maintainer	accepted	complete
2026-09-30	Exact merge receipts	maintainer	accepted	complete
2026-09-30	Owned server operations	maintainer	accepted	complete
2026-09-30	Schema contract in the manifest	maintainer	draft	in-progress
2026-10-01	Engine settlement and resource bounds	maintainer	accepted	partial
2026-10-08	Index facts as planner input	maintainer	accepted	complete
2026-10-10	Unpublished graph commits	maintainer	accepted	partial
2026-10-10	Block registry for merge base lookup	maintainer	draft	in-progress
2026-10-11	Unattached graph branches	maintainer	draft	not-started
2026-10-15	Bulk load as a query plan	maintainer	draft	partial
2026-10-16	Engine catalogue	maintainer	draft	in-progress