Skip to content

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

RFCTrackTitleStatus
0001I1The report contract — reports as versioned rules with golden fixturesImplemented
0002I2Node-model unification — one graph model the reports and SDKs shareImplemented
0003I3Feature-gated builds and a publishable reports-only binaryAccepted
0004I4Drift detection — making .yidam.toml enforceable (yidam sync)Draft
0005I5One MCP tool contract across the Rust CLI, TS, and Python serversImplemented
0006I6Correctness reconciliation — runtime-verifiable embeds + internal inconsistenciesImplemented
0007I7The Python SDK index/feature layer — one canonical embed text, and the index layer retractedImplemented
0008G1Emergent claims and the scope of synthesis — the strict reading of Article V, and what "the same claim" meansAccepted
0009G2Resolution execution authority and the synthesized-by recordAccepted
0010G3Evolution lineage — forking, parentage, and explicit baselinesAccepted
0011G4Partial-sangha resolutions and participant-scoped bindingAccepted
0012G5Elector identity and attestation — model/version/config + commit signingAccepted
0013I8Closing RFC-0002 — the node-model open questionsImplemented
0014I9Node rename as a sanctioned operation — dangling-edge gate + atomic yidam renameImplemented
0015I10An epistemic-only history view (yidam log --epistemic)Implemented
0016I11An editor surface for derived repositories (yidam for VS Code)Implemented
0017I12Serving assertions, not documents (claims and the practice tools)Implemented
0018I13The query surface — typed traversal bounded by the ontology (yidam query)Implemented
0019I14Citing a corpus you cannot revise (cites:)Implemented
0020I15Proposing what a finding already says (yidam propose)Implemented
0021I16Code that names what the ontology has not (yidam check-diff)Implemented
0022I17What a tool may say about code it cannot read (check-diff, Phase B)Implemented
0023I18Bytes the catalog fetched and never kept — remote vaultsImplemented
0024I19The rule a repository writes about itself — policy as codeImplemented
0025I20The instrument, turned around — measuring the repository that measuresImplemented
0026I21A run is a commit somebody can refuse — the orchestrator layerImplemented
0027I22A profile is a projection, not a second contract — the openai profileDraft
0028I23The form a practice takes — the kuten layerImplemented
0029I24A write is a capability a server declares, not a transport it happens to have — the MCP write tierAccepted
0030I25The surface is beside the binary, and earns a version (yidam-edit)Draft
0031I26A node's prose is not one field, and a finding is not a sentence — the node prose modelDraft
0032I27One name for a thing, and one parser that reads it — the reference grammarDraft
0033I28A vector index a corpus is queried out of, not one it carriesImplemented
0034I29A claim resting on a node beside it (cites: without a package)Draft
0035I30What a class is meant to span, and what a hole in it is worth (coverage:)Draft
0036G6An yidam-level change, and the two shapes a derivation's report takesAccepted
0037G7An open question is a node; [open] is a claim's standingAccepted
0038G8A rule is separable from the essay that justifies itDraft
0039G9A read is scoped to the occasion, not to the repositoryImplemented
0040G10A numeric property typeDraft
0041G11Typed property columns, and a predicate on a ranked answer (retrieve --where)Draft
0042I31A calculator whose purity is a closed scope and a typecheck, not a norm — a typed, effect-tracked arm on the capability manifestDraft
0043I32A figure published twice, computed once — an inline REGEN block and the count generatorImplemented
0044G12A declared value setDraft
0045I33A refusal is declared, and a derivation is checked against it (refuses: and yidam derive check)Implemented
0046G13A quotation property typeImplemented
0047I34A domain article is sealed by the genesis commitImplemented
0048I35A source is named by what it is, and fetched by something the corpus did not write (source packs)Implemented
0049I36The ontology is the schema a pipeline loads, and the semantic layer reads (warehouse contract and the textql export)Draft
0050G14A list property type — scalar items, and records that carry their own standingDraft

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.