rfc: add RFC 0040, the system column namespace

[azimafroozeh]

What & why

This PR adds RFC 0040, which frees the property names id, src, and dst for user schemas and moves OmniGraph's implicit stored columns into a reserved namespace. Motivated by #529: a ported schema whose natural key is named id collides with the implicit physical id column, failing with a misleading error when declared with @key and silently producing a duplicate physical column without it.

• Reserve the leading-underscore property namespace for the system; the per-name Lance reservations collapse into one prefix rule, and future system columns need no further reservations or versions.
• Newly created graphs spell the system columns __id/__src/__dst; every existing graph keeps its current spellings through per-graph resolution keyed on its schema IR version, so the design contains no migration.
• The query language gains meta-fields ($p.@id, $e.@src, $e.@dst) that work on every graph; $p.id keeps its exact current behavior on existing graphs (with a deprecation lint) and refers only to a user property on new ones.
• API payloads carry each graph's own column names; an explicit per-graph upgrade renames the columns and mechanically rewrites the graph's stored queries in one schema apply.

Backing issue / RFC

• This PR is the RFC (docs/rfcs/0040-system-column-namespace.md); motivated by bug: a node property named id silently collides with the implicit physical id column, and @key then fails claiming the property is undeclared #529. A companion bug-fix patch reserving the three names lands separately before the implementation: it is the fence that makes the RFC's coexistence guarantees provable.

Checklist

• Change is focused (adds one RFC document, no source changes)
• Tests added/updated for behavior changes (none: docs-only, no behavior change)
• Public docs updated if user-facing surface changed (the RFC is the added document; user docs change with the implementation)
• Reviewed against docs/dev/invariants.md: no Hard Invariant weakened; the RFC's Invariants section names the one knowingly brushed deny-list item (on-disk format change) and carries its refusal and compatibility evidence plan

Local verification

• no build or test commands: docs-only RFC addition, no source touched
• vocabulary guard not run: the diff touches only docs/rfcs/, outside the guarded surfaces

Notes for reviewers

• No flag day: at the release boundary, existing graphs, queries, and clients see no behavior change beyond a deprecation lint; each graph adopts the new spellings at its own explicit upgrade.
• The new binary permanently accepts exactly two schema IR vintages; old binaries refuse new-vintage graphs through the existing strict version validation.
• A draft implementation is in progress alongside; unresolved questions 1 and 2 (Lance rename metadata-only, constraint endpoint spelling) are implementation gates, and question 3 is release timing.

Greptile Summary

The PR adds RFC 0040, proposing a reserved system-column namespace while preserving existing graph spellings through per-graph schema vintage.

• Introduces __id, __src, and __dst storage names and corresponding query meta-fields.
• Defines feature-set-based schema IR compatibility and explicit graph upgrades.
• Documents stored-query rewriting, cluster rollout ordering, compatibility gates, and implementation tests.
• Registers RFC 0040 in the RFC index.

Confidence Score: 5/5

The PR appears safe to merge because no blocking failure remains from the previously reported issues.

The revised RFC preserves vintage during ordinary applies, moves stored-query rewriting outside the graph transaction with a post-upgrade validation gate, and documents an ordered restart-before-upgrade rollout.

Important Files Changed

Filename	Overview
docs/rfcs/0040-system-column-namespace.md	Defines the system-column namespace, vintage-preserving compatibility model, explicit upgrade workflow, and associated validation gates.
docs/rfcs/README.md	Registers RFC 0040 in the canonical RFC index.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Old[Old-vintage graph<br/>id / src / dst] --> Apply[Ordinary schema apply]
  Apply --> Old
  Old --> Rewrite[Rewrite stored queries<br/>to meta-fields]
  Rewrite --> Restart[Restart with rewritten registry]
  Restart --> Upgrade[Explicit graph upgrade]
  Upgrade --> New[New-vintage graph<br/>__id / __src / __dst]
  New --> Meta[Queries use @id / @src / @dst]

Loading

_{Reviews (4): Last reviewed commit: "review" | Re-trigger Greptile}

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[ragnorc]

The design is sound — spelling resolution keyed on the accepted IR's vintage (never physical inspection) keeps one source of truth, the meta-fields are proper grammar constructs, and the no-migration story is credible including the resolver-stamping landmine you caught. The reserved __ namespace is also going to pay off beyond this RFC: it gives future engine-owned computed columns (e.g. retrieval metric columns) a collision-free home with no per-name reservations.

Three fixes before acceptance:

1. Template conformance (blocking): the file uses the retired header-table format (**Status**, **Author track**, provisional number). The registry mandates the exact YAML frontmatter schema and template sections — Evidence and tests, Rollout, and Decision log are currently missing (the evidence gates exist but are scattered inline), and Proposed isn't in the status enum.
2. Registry: the diff never adds the 0040 row or removes the reservation sentence in docs/rfcs/README.md.
3. The vintage-closure claim needs reconciling with rfc: add RFC 0044, derived edge identity via @key on edge types #592/feat(engine): add edge keys with derived identity #593: "the new binary accepts exactly two vintages, permanently" is already in tension with edge keys minting a third ir_version under a highest-required-stamp rule. An old-spelling graph that later declares an edge key is exactly the combination a single linear scalar can't express — suggest settling the joint numbering question (facets vs. linear) at acceptance of these two RFCs rather than leaving it to implementation-time coordination, since a third orthogonal schema feature (analyzed-search semantics) is already queued behind them.