RFCs
Design documents for yidam architectural decisions. Each RFC is a proposal held open for review before it becomes behavior — testimony about a change, not a changelog of one.
These RFCs describe the yidam template and tooling, not any derived repo's domain. They
follow the register of the rest of docs/: precise, evidenced, and honest
about what is not yet settled.
Why this set exists
yidam's promise is that a derived repository can inherit a research instrument — the node
model, the reports that keep it honest, the index that makes it retrievable, the MCP surface
that lets an agent work it — and stay in parity with upstream as both evolve. In practice the
first real downstream consumer, Project BOSC (watermark-directory), could not inherit any
of that. It re-implemented ~1,600 lines of yidam in Python: the four reports, the MCP server,
and the vector index. It did so because everything a consumer actually integrates lives
above the parity line and is siloed per language — the reports are Rust-CLI-only, the node
model the reports run on is parsed by no SDK, the MCP surface exists in three mutually
incompatible forms, and the Python index layer is documented but unbuilt. The cli_ref pin
that was supposed to make drift visible is enforced by nothing, and a divergence already
exists in the wild.
The through-line of every RFC below: yidam's parity surface certifies the wrong things match. It guarantees three SDKs parse Markdown identically while the products a consumer depends on drift freely. These RFCs move the contract boundary to where integration actually happens, so a downstream repo can conform to and verify against yidam instead of re-deriving it.
Index
| RFC | Track | Title | Status |
|---|---|---|---|
| 0001 | I1 | The report contract — reports as versioned rules with golden fixtures | Implemented |
| 0002 | I2 | Node-model unification — one graph model the reports and SDKs share | Implemented |
| 0003 | I3 | Feature-gated builds and a publishable reports-only binary | Accepted |
| 0004 | I4 | Drift detection — making .yidam.toml enforceable (yidam sync) | Draft |
| 0005 | I5 | One MCP tool contract across the Rust CLI, TS, and Python servers | Implemented |
| 0006 | I6 | Correctness reconciliation — runtime-verifiable embeds + internal inconsistencies | Implemented |
| 0007 | I7 | The Python SDK index/feature layer — one canonical embed text, and the index layer retracted | Implemented |
| 0008 | G1 | Emergent claims and the scope of synthesis — the strict reading of Article V, and what "the same claim" means | Accepted |
| 0009 | G2 | Resolution execution authority and the synthesized-by record | Accepted |
| 0010 | G3 | Evolution lineage — forking, parentage, and explicit baselines | Accepted |
| 0011 | G4 | Partial-sangha resolutions and participant-scoped binding | Accepted |
| 0012 | G5 | Elector identity and attestation — model/version/config + commit signing | Accepted |
| 0013 | I8 | Closing RFC-0002 — the node-model open questions | Implemented |
| 0014 | I9 | Node rename as a sanctioned operation — dangling-edge gate + atomic yidam rename | Implemented |
| 0015 | I10 | An epistemic-only history view (yidam log --epistemic) | Implemented |
| 0016 | I11 | An editor surface for derived repositories (yidam for VS Code) | Implemented |
| 0017 | I12 | Serving assertions, not documents (claims and the practice tools) | Implemented |
| 0018 | I13 | The query surface — typed traversal bounded by the ontology (yidam query) | Implemented |
| 0019 | I14 | Citing a corpus you cannot revise (cites:) | Implemented |
| 0020 | I15 | Proposing what a finding already says (yidam propose) | Implemented |
| 0021 | I16 | Code that names what the ontology has not (yidam check-diff) | Implemented |
| 0022 | I17 | What a tool may say about code it cannot read (check-diff, Phase B) | Implemented |
| 0023 | I18 | Bytes the catalog fetched and never kept — remote vaults | Implemented |
| 0024 | I19 | The rule a repository writes about itself — policy as code | Implemented |
| 0025 | I20 | The instrument, turned around — measuring the repository that measures | Implemented |
| 0026 | I21 | A run is a commit somebody can refuse — the orchestrator layer | Implemented |
| 0027 | I22 | A profile is a projection, not a second contract — the openai profile | Draft |
| 0028 | I23 | The form a practice takes — the kuten layer | Implemented |
| 0029 | I24 | A write is a capability a server declares, not a transport it happens to have — the MCP write tier | Accepted |
| 0030 | I25 | The surface is beside the binary, and earns a version (yidam-edit) | Draft |
| 0031 | I26 | A node's prose is not one field, and a finding is not a sentence — the node prose model | Draft |
| 0032 | I27 | One name for a thing, and one parser that reads it — the reference grammar | Draft |
| 0033 | I28 | A vector index a corpus is queried out of, not one it carries | Implemented |
| 0034 | I29 | A claim resting on a node beside it (cites: without a package) | Draft |
| 0035 | I30 | What a class is meant to span, and what a hole in it is worth (coverage:) | Draft |
| 0036 | G6 | An yidam-level change, and the two shapes a derivation's report takes | Accepted |
| 0037 | G7 | An open question is a node; [open] is a claim's standing | Accepted |
| 0038 | G8 | A rule is separable from the essay that justifies it | Draft |
| 0039 | G9 | A read is scoped to the occasion, not to the repository | Implemented |
| 0040 | G10 | A numeric property type | Draft |
| 0041 | G11 | Typed property columns, and a predicate on a ranked answer (retrieve --where) | Draft |
| 0042 | I31 | A calculator whose purity is a closed scope and a typecheck, not a norm — a typed, effect-tracked arm on the capability manifest | Draft |
| 0043 | I32 | A figure published twice, computed once — an inline REGEN block and the count generator | Implemented |
| 0044 | G12 | A declared value set | Draft |
| 0045 | I33 | A refusal is declared, and a derivation is checked against it (refuses: and yidam derive check) | Implemented |
| 0046 | G13 | A quotation property type | Implemented |
| 0047 | I34 | A domain article is sealed by the genesis commit | Implemented |
| 0048 | I35 | A source is named by what it is, and fetched by something the corpus did not write (source packs) | Implemented |
| 0049 | I36 | The ontology is the schema a pipeline loads, and the semantic layer reads (warehouse contract and the textql export) | Draft |
| 0050 | G14 | A list property type — scalar items, and records that carry their own standing | Draft |
Reading order
- Start with 0002 (the root: two disjoint node models with no bridge) and 0001 (the highest-leverage fix: make the reports a tested contract).
- 0003 removes the reason a consumer re-implements at all (a light, publishable binary); 0004 turns the version pin into an enforced check on top of it.
- 0005, 0006, 0007 reconcile the surfaces that already diverged (MCP, embeddings, the empty Python layer).
Status legend
Draft — under review, not accepted. Accepted — agreed, implementation may begin.
Implemented — landed: the behaviour it specifies ships, in a released layer or in this
repository's own infrastructure where the RFC releases nothing. Superseded — replaced by a
later RFC (named in its header). Rejected — considered and declined, with the reason kept.
The Commands line
A status is a claim about a design, and the one thing in an RFC that can be checked against the tree is the command surface it specifies. So an RFC that specifies commands names them in its header, machine-readably, one line:
- **Commands:** `run`, `phase`
Top-level command names as yidam --help-all spells them, or group sub pairs, comma-separated,
and nothing else on the line — rfc_status.rs reads it and asks the built binary whether each
one exists. Once every
command an RFC names is in the binary, the RFC may not read Draft or Accepted: a design still
under review does not have a shipped command. #941 reported that combination three times; writing
the lines out found it in RFC-0033 as well, which nobody had noticed.
The line is for commands this RFC specifies, not ones it mentions. Every RFC below names
lint or vault somewhere; two thirds of them introduce no command at all and carry no line.
An RFC whose commands are unbuilt carries the line too — RFC-0004's three are the example — and
that is the half of the check with a future: the day one of them ships, the status has to move
with it.
A group can be named one subcommand at a time, as group sub, and the check then asks the
group's own --help for each one. RFC-0048 names source check, source list, source search
and source add. Had its line said only source, the RFC would have had to read Implemented
on the day check shipped alone (#1329). An RFC that lands across several PRs keeps its true
status this way until the last subcommand is built.
RFC template
Every RFC in this directory follows this shape:
# RFC-000X — <Title>
- **Status:** Draft
- **Commands:** `<name>`, `<name>` — only where this RFC specifies commands; see above
- **Track:** I<n>
- **Relates to:**
- RFC-000Y (what this takes from it, in a clause)
- RFC-000Z (what this takes from it, in a clause)
- **Versioning layers touched:** template / SDK+parity / bootstrap protocol
- **Downstream reference case:** Project BOSC (watermark-directory)
## Summary
One paragraph: what changes and why it matters to a downstream consumer.
## Problem
The current shape, with concrete `file:line` evidence from the yidam tree and from the
BOSC consumer. State the drift or friction precisely.
## Proposal
The concrete design — schemas, command surface, fixture format, type changes. Name it
`Proposal`, not `Design`: six RFCs drifted to the latter and a reader looking for the
design should not have to know which word this one chose.
## What this does not touch
The adjacent surfaces this deliberately leaves alone, and the reader who might expect
otherwise. Optional, but ten RFCs found they needed it — a scope boundary stated once
here is a paragraph nobody has to argue in review.
## Migration & compatibility
Which versioning layer bumps; how existing derived repos and BOSC adopt; what breaks.
## Alternatives considered
The options weighed and why this one.
## Open questions
What is genuinely unresolved and needs a decision.