Configuration
A derived repository configures yidam through four files, and the split between them is not arbitrary. Each answers a different question. Putting an answer in the wrong file is how one repository's judgement ends up imposed on another.
| File | Answers | Written by |
|---|---|---|
.yidam.toml | Which yidam governs this corpus? | clone / overlay, then mise run yidam-vendor-update |
.yidam/config.toml | What has this corpus decided about itself? | You |
.yidam/lint-baseline.yml | What debt did this corpus start with? | yidam lint --bless / --init-baseline |
.yidam/tonpa.toml | Which other corpora does this one draw on? | yidam tonpa add |
Everything is optional. A repository with none of them still lints, still gates, and still serves. It simply has no ratchet, no dependencies, and no opinion about how its sources age.
.yidam.toml
The template provenance pin, at the repository root. Generated; you do not normally edit it.
[yidam]
origin = "git@github.com:goedelsoup/yidam.git"
commit = "88edd17f4c2a1b09e3d5f7a8c6b4e2d1a9f0c3b5"
template = "v0.1.0"
committed = "2026-08-27"
cli = "0.16.0 (ce5e738)"
| Field | Meaning |
|---|---|
origin | Where the template came from |
commit | The resolvable pin — what the re-vendor procedure and CI check out |
template | The template-layer release tag at that commit, or "untagged" |
committed | That commit's author date — i.e. how old the vendored prelude is |
cli | The yidam binary in use when the file was written: version and build commit |
[build] — yours, and preserved
[build]
features = ["export-sqlite"]
| Field | Meaning |
|---|---|
features | Features this repository's yidam binary must have beyond the released default set |
The only part of this file you write. Every path that can produce a binary reads it:
| Path | What it does |
|---|---|
mise run yidam-build (download) | asks the downloaded binary's --version and compiles instead if it is short |
yidam-build-source (compile) | passes it to cargo install --features |
mise run yidam-vendor-update | withholds the [tools] entry, so mise install cannot make the swap |
Declare it here rather than editing mise.yidam.toml: that file is the inherited task layer
and a re-vendor replaces it wholesale. This table survives the re-vendor that rewrites
everything else in .yidam.toml.
A release that carries what you asked for is still adopted — the declaration costs nothing
until it would cost you a capability. A single-line array; the writer emits that form and the
readers are sed, not a TOML parser.
commit is the field that makes the pin mean anything; the other three are for reading.
template names the template layer specifically — bare v<semver> tags — . Every other
layer prefixes its tag (cli/v*, sdk/rust/v*, bootstrap/v*, editor/v*). A field that
answered with whichever tag happened to sit on the commit would answer for the wrong layer.
committed is the pinned commit's date, not the date this repository ran the vendor step.
That is what makes yidam doctor's prelude-age check meaningful.
This file is also how the editor surface decides which binary may speak for a corpus. It records which yidam governs the repository, and only that one gets to say.
.yidam/config.toml
What this corpus has decided about itself. Every section and every key is optional, and absent means the behaviour is off — not a compiled-in default quietly applying.
Bootstrap scaffolds this file with every key present and commented out. That is the delivered state, not an unfinished one. A number shipped in a scaffold is one corpus's judgement, arriving in another that never agreed to it. What the file gives you is the list. Leaving a clock unset is then a choice you looked at, rather than a key you never met. Uncomment what you mean; an empty section says what no section says.
[lint]
escalate_after = 100
[propose]
withdraw_uncited_after = 400
[catalog]
ttl_days = 180
[due]
questions_after = 100
phases_after = 60
index_after = 25
superseded_after = 14
[due.declined]
index = "due-clocks"
[index]
model = "BAAI/bge-small-en-v1.5"
[object]
paths = ["web/**", "crates/**"]
[derive]
paths = ["dossier/**"]
[serve]
act = true
offline_sources = true
record = true
[index.remote] and [vault.<name>] are the two sections not shown above. Each has required
fields, so a half-filled one is refused rather than ignored. Both are in the scaffold,
commented, with those fields named. The shared vector index is covered in
cli-reference.md; the stores, in
artifact-vaults.md.
[lint] escalate_after
Corpus-touching commits a dated finding may hold before it escalates from a warning to an error.
Absent means no finding ever escalates, and that is the design rather than timidity. The number is a judgement about how fast this corpus is meant to consume what it collects. A breadth sweep landing twelve nodes it will link over the next eighty commits is healthy in one repository and over-collection in another. A value compiled into the binary would be one corpus's answer arriving as a build failure in a repository that never agreed to it.
It reaches one check, and the report says which
"A dated finding" is a small population. Escalation needs two things at once: this threshold,
and a finding carrying a clock. Most checks date nothing. So most of the report is unreachable
by every value of escalate_after. Arming it today escalates aged orphan-in findings and
nothing else.
That is not a number to keep here, where it would go stale. Each check declares it instead.
yidam lint --format json carries the declaration on every check, including the ones that
found nothing. That is the case that matters when you are deciding whether to adopt:
$ yidam lint --format json | jq -r '.checks[] | select(.escalation_eligible) | .id'
orphan-in
yidam lint --explain says the same thing beside a check it is already printing.
escalation_eligible: true does not mean anything escalated. That is
violations[].severity, and it also depends on this number being set. True means the
threshold can reach this check at all.
Worth reading before deciding not to adopt. Suppose your report is mostly one undated finding shape. Arming this changes nothing about that shape. So "most of our findings are awaiting an editorial pass" is not by itself an argument against it.
[propose] withdraw_uncited_after
Corpus-touching commits an uncited node may hold before yidam propose
drafts its withdrawal.
Absent means no withdrawal is ever drafted, which is every corpus until someone turns it on.
This is not escalate_after under another name. escalate_after declares when a finding
becomes a build failure — a statement about the gate. This declares when an uncited node stops
being a sweep in progress and becomes over-collection — a statement about the corpus. A
repository may reasonably hold the first and not the second, and most will. Failing the build
asks a person to look; drafting a deletion decides what they would have concluded.
[catalog] ttl_days
Days a catalog entry may stand before it is worth looking at again, when the entry does not
declare its own. The per-entry ttl_days: is the primary form, because a gauge record and a
statute do not age at the same rate. This key exists for the common case: a corpus whose
sources mostly do age alike. Adopting a TTL is then one line rather than one line per entry.
Absent means no entry expires unless it says so itself.
[cluster]
What yidam cluster workflow needs to write an Argo manifest, and what cluster admit caps.
Every key outside git_auth, [cluster.names], [cluster.pod], [cluster.cleanup] and
[cluster.github_app] has a flag that overrides it. See
cluster-runs.md.
[cluster]
remote = "git@github.com:you/corpus.git"
branch = "main"
image = "ghcr.io/you/yidam-cluster:latest"
vault = "default"
namespace = "yidam"
max_open_proposals = 1
remote and image have no default, and the generator refuses without them. branch is
main. vault names a [vault.<name>] table, and its url is the workflow's vault-url.
namespace is written into the manifest's metadata when set.
max_open_proposals is the cap cluster admit reads. A run that would propose while that
many propose/* branches stand open on the remote is not admitted. Absent means no cap.
yidam propose and yidam run read it too, against local propose/* branches. At the cap,
neither opens a new branch. Re-proposing onto a branch that already exists is still allowed. This
is the throughput judgement RFC-0026 §3 leaves to the corpus. It never decides what a run may
author.
git_auth is what the lander pushes with. deploy-key, the default, is an SSH key.
github-app is a GitHub App's private key, from which the lander mints a token per push:
[cluster]
git_auth = "github-app"
[cluster.github_app]
app_id = 123456
api_url = "https://github.example.com/api/v3"
app_id is required. api_url is for GitHub Enterprise Server and defaults to
https://api.github.com. The generator refuses a remote that names no GitHub repository,
and an api_url that is not HTTPS. It also refuses the table without
git_auth = "github-app", since the lander would ignore it. See
cluster-runs.md.
[cluster.names] sets the Kubernetes objects the workflow refers to by name. Each defaults to
a name derived from the corpus, its root directory's name lowercased:
[cluster.names]
service_account = "yidam-corpus-run"
git_read = "yidam-corpus-git-read"
git_write = "yidam-corpus-git-write"
vault_secret = "yidam-corpus-vault"
vault_claim = "yidam-corpus-vault"
events_account = "yidam-corpus-events"
webhook_secret = "yidam-corpus-webhook"
events_account and webhook_secret are read only by --on-push. The first is the account
the Sensor creates the run as. The second holds the secret a push is checked against.
The defaults differ per corpus, so two corpora in one namespace share no write key. Override
one only to keep a name you already have. Two corpora given one git_write share its key.
The generator refuses a name Kubernetes would refuse: lowercase letters, digits, - and ..
[cluster.pod] sets what every pod requests, may use and may run for. The values shown are
the defaults:
[cluster.pod]
cpu_request = "250m"
memory_request = "512Mi"
cpu_limit = "2"
memory_limit = "2Gi"
deadline_seconds = 3600
A quantity is spelled as Kubernetes spells it, and the generator refuses one it would refuse.
A capability may set any of these keys under [capability.<name>.cluster] in
.yidam/capabilities.toml. Only that step's pod changes, and each key it leaves unset comes
from here.
[cluster.cleanup] sets when Argo deletes a finished run:
[cluster.cleanup]
pod_gc = "OnPodSuccess"
seconds_after_success = 86400
seconds_after_failure = 604800
pod_gc is Argo's podGC strategy. The two seconds_* keys are the workflow's ttlStrategy.
[cluster.egress] is what yidam cluster network-policy
lets each pod reach. A NetworkPolicy cannot name a host, so each key is a list of CIDRs:
[cluster.egress]
executor = ["172.18.0.2/32"]
remote = ["140.82.112.0/20"]
vault = ["10.20.0.0/16"]
sts = ["10.20.8.0/24"]
executor is the API server's endpoint addresses. Argo's executor sidecar reports through
them from inside every pod, and the generator refuses without them. remote is optional.
Unset, the pods holding a git key reach anywhere. Under git_auth = "github-app" the lander
also calls the GitHub API, so remote must cover it too. vault is required for an s3:// vault and
refused for a file:// one. sts is needed only when pods assume a role by web identity, as
IRSA gives them. List the regional STS interface endpoint's addresses. See
cli-reference.md. Each CIDR must be a network address: 10.0.0.1/8 is
refused.
[due]
The intervals yidam due reads. Each is an age a subject may
reach before that clock comes due. An absent key means the clock reports what it measured and
never comes due.
| Key | Subject | Unit |
|---|---|---|
questions_after | An open question | corpus-touching commits |
phases_after | A bounded inquiry ref not yet on the baseline | days |
index_after | Corpus files changed since the index was built | files |
superseded_after | A node citing a source that gained a new version since the node's last commit | days |
The catalog clock's interval is not here. due also reads a source record's TTL, and that
is [catalog] ttl_days and each entry's own ttl_days:, where it already
lived. Restating it under [due] would create two places to set one number.
Two of these count days and two do not. How long a question has gone unanswered is a fact
about the repository, and the repository's clock is HEAD. A corpus that has not committed has
not ignored anything. A phase's time in flight is a fact about the world, which is the same
argument ttl_days makes. Work does not stop having been open for four months because nobody
committed to the corpus.
index_after = 1 means any change at all makes a rebuild due. A larger number is a corpus
saying it is content for retrieval to lag its own edits by that much.
superseded_after counts from the commit that recorded the new version, not from the node's
last edit. A new version is a digest from a location the entry already held one from. A new
text reading of a PDF is not one. Any commit touching the node discharges it.
[due.declined]
Clocks this corpus decided it does not want, each naming the record that argues it.
[due.declined]
index = "due-clocks"
The key is the clock's id: index, catalog, questions, phases or superseded. The value
is a decision record in .yidam/decisions/, by its id: or its file stem.
Unset and declined are different states. Without this key they report the same. A corpus that examined a vector index and chose against it looks like one that never considered it. The only remedy on offer is to declare an interval for work nobody intends. That clock is then permanently due, and a permanently red row is one a reader learns to skip.
A declined clock reports declined. It still prints what it measured, and it prints the
record. It is not counted among the clocks with no interval declared.
The record is required. That is what makes this a declaration rather than a mute button.
If the named record is missing, the decline is not honoured. The clock reverts to what it
really is, and says so. A key naming no clock is reported too. The property is
.yidam/lint-baseline.yml's: a decline that no longer has anything behind it goes red rather
than quiet.
Declaring an interval and declining the same clock is a contradiction. The interval wins, and the row names the contradiction.
[index] model
The embedding model index-build uses. Read only by index-build, which the light reports
binary does not carry. The key is still parsed there, so a binary that cannot act on a model
does not reject a config naming one. yidam index-build --model overrides it. Absent, the model
is Xenova/all-MiniLM-L6-v2.
[index] batch_size, threads, session_options
How index-build runs the model on this machine.
| Key | Absent | Set |
|---|---|---|
batch_size | 1 record per call | Records per call, and how often progress prints |
threads | One per logical core | ONNX Runtime intra-op threads; 0 lets ONNX Runtime choose |
session_options | No entries | ONNX Runtime session config entries, passed through unread |
[index]
batch_size = 1
threads = 0
session_options = { "mlas.disable_kleidiai" = "1" }
Leave batch_size at 1. The default model quantizes with one scale per batch. In a larger
batch, a record's vector depends on what shares its batch. It then drifts from the query
vectors, which are always embedded alone (#1428). Batch 256 was also slower when measured. It
used 12 GB of memory where batch 1 used 0.2 GB.
threads and session_options left the vectors unchanged when measured. Queries always embed
with the defaults.
[object] paths
Globs naming the artifact this corpus is about, relative to the repository root. A repository
with a web/ site or a crates/ workspace beside its corpus has two commit registers. This
key is how it says which paths are the second one.
** spans any number of path segments and * any run within one. A glob also claims
everything beneath what it names, so "web" and "web/**" say the same thing.
Read by yidam lint --commits. A commit touching only these paths
is not checked against the corpus vocabulary. feat: on the artifact is not a corpus
violation. Two derived repositories carry 30 and 72 such commits, every one reported today.
Three rules govern the rest, and each is deliberate:
| The commit touches | Governed by |
|---|---|
| Only declared object paths | Nothing — the corpus vocabulary does not reach it |
| Both registers | The corpus |
| No paths at all | The corpus |
A mixed commit raises no new finding. The export act crosses the registers by design: it
turns the corpus into web/. A rule firing on it would fire hardest on the best-behaved
repositories. That measurement is in RFC-0028 §4.
A commit with no paths is corpus work. git log --name-only lists nothing for a merge, so
an authored merge arrives here with an empty list. Absence of evidence is not a declaration of
jurisdiction.
Absent means the repository has one register, and every commit is corpus work. That is what every repository did before this key existed, and it is what all six defining corpora do today.
It also names the artifact yidam lint reads for links into the corpus. Those are the
tracked .md, .rs and .ts files these globs claim. A relative link from one of them into
.yidam/ must resolve. One that does not is a broken-object-link warning at the line that
holds it. It warns and never fails the build. A file under a region in .yidam/authorship.yml
is skipped, because its links are its upstream's citations. The other direction was already
checked: a node's link into the artifact is held by broken-prose-link.
yidam kuten check counts the links both ways. Its report adds a coupling section. It
says how many nodes, decisions and catalog entries the artifact cites, and how many cite it.
Nothing is a finding there, because no rule says a node must be cited. The section is empty
when no object is declared, or when the kuten declares the corpus projected.
kuten check's history is not scoped by this key. It measures every authored commit, because
its numbers are read against a band. Scoping them would let a corpus move its own reading by
widening this list, with no commit written.
yidam vocabulary --check is not scoped by it either. It reads a subject line, and no
commit exists yet. So it has no paths to read. Three surfaces call it: a contributor at a
terminal, the VS Code commit box, and the MCP tool check_subject. All three still warn about
feat: on an artifact while lint --commits stays silent. The asymmetry is recorded rather
than fixed: closing it means changing a frozen MCP tool.
This project ships no commit-msg hook. The stance is conformance, not hooks (RFC-0004).
[derive] paths
Globs naming the arguments this repository derives from its corpus: the memos, dossiers and
findings that carry a claim out. yidam derive check reads them. It
holds each one to the three rules in agent-conduct.md for a claim leaving the repository.
The grammar is [object] paths's. Under these globs, a .yml or .yaml file is an artifact.
So is a .md file that opens with YAML frontmatter. A .md without frontmatter is prose kept
beside the artifacts, and is skipped.
No directory is compiled in. The repositories that built this gate keep their arguments in
dossier/, briefs/ and analysis/. Where an argument lives is a fact about a repository.
Absent means derive check has nothing to read, and it passes.
[serve] act
Whether a server started against this corpus may write to it.
An MCP server is read-only unless this key says otherwise (RFC-0029).
With it, serve --mcp serves two more tools. propose drafts the epistemic commits this corpus's
own findings license onto a propose/<head> branch. cycle reports where the repository is in
its loop.
Without it, both are absent from tools/list. A call to either is refused
capability-not-supported.
This is the one capability a server declares that is permission rather than ability. That is why it is a key here, and not something a server works out.
Every other capability is filled from what the server can do. A corpus with no .ont.yml has no
class contract, so ontology is false because it cannot be true. act is false on a server that
could write perfectly well, until this file says otherwise.
A server allowed to discover that it may write has discovered a policy. A policy nobody stated is not one.
It is a key in this file and not a flag, deliberately. A flag puts the declaration in the launcher's argv — a client config, a desktop manifest, a shell alias. May a tool write into this corpus would then be a fact about who started the server. It is a fact about the corpus, and this file is the corpus saying it.
The key takes three values. false, or no key, declares nothing. true and "when-identity"
both declare the tier, and both are necessary and not sufficient. Two more conditions are
checked at startup:
| Condition | Why |
|---|---|
A git author identity resolves — user.name and user.email, the values a commit here would take | The history these tools write into is the knowledge graph. A commit recording what a process did rather than who decided it is what this clause prevents. It applies on every transport, stdio included |
Every listening socket is loopback — serve --mcp --http --bind 0.0.0.0 is refused, with a bearer token or without one | A server reachable from another machine has no author for a remote caller. A shared token says a caller holds it, not who they are. Vacuous over stdio, where the transport has one peer and it is the process that started the server |
What a failed condition does depends on the value:
| Value | Where a condition fails |
|---|---|
true | The server refuses to start. Serving the read tools and declaring act: false would be a silent downgrade, and whoever wrote true would read a running server as the answer to their question |
"when-identity" | The server starts with the read tools only. It declares act: false, prints which condition failed, and appends that sentence to every refusal of propose or cycle. The downgrade is stated, never silent |
The scaffold writes act = "when-identity", by the owner's decision on
#1438. A fresh clone with no user.name still
serves every read. Write true where a missing tier should stop the server.
The loopback rule is not a security boundary and should not be read as one. Anything on the host reaches loopback. A tunnel in front of a loopback port is the remote case wearing this clause's clothes.
What it separates is this machine from another machine, without inventing an authenticator. That is the most a server can see from inside. Whether a caller is the person these conditions describe is the operator's declaration, and nothing detects it. That is why this is configuration in the first place.
A proposal is not a merge. propose writes to a branch and nothing else. No commit lands on
the baseline and nothing merges itself. There is no establish, no new node and no edge.
You review the branch as commits and reject it by deleting it. The CLI's --force is not offered
over MCP: replacing a proposal branch discards commits nobody has read.
Absent means read-only, which is what every server did before this key existed.
[serve] offline_sources
Whether a server answers search_sources and resolve_source from the packs' recorded fixtures.
Absent, those two tools ask the publisher, as yidam source search does. With it, they read
each pack's fixtures/ and make no request. It is --offline for the server, which takes no
per-call flag.
Every answer says which route it took. answered is network, fixture, or null when nothing
was asked. A list read from a fixture is not the publisher's answer today, and the field says
so. (RFC-0048 asked whether it should. This is the answer.)
It is declared, not detected. A server that guessed it was offline would read fixtures during a network blip. A client could not tell that from a deliberate choice.
It reaches only the source tools. A remote vector index is still asked, and retrieve still
reports remote_unavailable when it does not answer.
[serve] record
Whether a server started against this corpus keeps a record of what it was asked.
With it, serve --mcp appends one line per tools/call to .yidam/record/calls.jsonl. It does
this over either transport. Absent, it writes nothing at all. That is what every server did before
this key existed.
The asymmetry this closes. This repository can say, for every node, who asserted it and when. It can say under what review, and what the node looked like at any commit. Until this key it could not say whether any node had ever been read. Thirteen tools dispatched, returned, and the process forgot.
RFC-0015 exists to make testimony visible rather than merely asserted. Its argument: a philosophy you cannot see is a philosophy you cannot use. The same argument applies unchanged to the consumption side, where nothing was visible at all.
Four questions a corpus cannot ask about itself without this, and can with it:
| Question | What answers it |
|---|---|
| Which queries came back empty? | outcome: "ok" with results: 0 and rejected: false — the most direct empirical evidence of what a corpus is missing |
| Did the degraded keyword path serve real traffic? | degraded per line. retrieve always reported it per call, and nothing aggregated it, so this corpus has been answering from keyword search for a month was not a statement anyone could make |
| Did anything act on a clock? | A cycle or propose line. Four freshness clocks, and no closing evidence that one was ever discharged through this surface |
| How much of the read surface is used at all? | tool and ms across the file |
Which nodes has retrieve never returned? | node_ids on retrieve lines, against the corpus. A row count has no complement; the ids do (#1020) |
One line per call, and every key is present on every line. null where a key does not apply to the
tool in hand. So a reader never has to tell nothing to report from a writer too old to report
it:
{"at":1758758400,"commit":"2bb499a","tool":"retrieve",
"args_digest":"sha256:9f3a…","outcome":"ok","results":3,
"node_ids":["concept/a","concept/b","concept/c"],
"degraded":true,"rejected":false,"ms":12}
commit is why a line is evidence. A reading becomes attributable to a corpus state, the way every
other claim here is. Without it the record says a query came back empty. It cannot say what the
query was asked of. The value is read live. So a propose that reloads the snapshot is followed by
lines naming what that write produced.
Never the query text. The digest and nothing else. Over --http a server answers callers it
cannot authenticate. A plaintext record would be a file of their questions, accumulating in a
working tree. The digest still answers every question above — which queries came back empty is a
set with counts either way. It answers them identically on both transports, so no
transport-conditional shape exists for anyone to reason about.
node_ids is closer to the query, and is kept anyway. It is on retrieve lines only, and null
on every other tool. Two calls that got the same ids asked related things. That is more than a
digest says. Three things bound it. Every id is a name list_nodes already publishes to any caller.
No line names a caller, so the ids link one anonymous call to another. And an empty answer records
an empty set, so the questions a corpus could not answer stay digests.
yidam record reads it. It answers the four questions above in sentences, below a table of
calls per tool. Pass --format json for the same counts as a report. A line from an older
writer is read as far as its keys go. A line that is not JSON is counted as unreadable, not
dropped.
The file is gitignored, and serve refuses to start until it is. .yidam/record/ must be
ignored, on the same rule as .yidam/vault/. The reason is related: this project's protocols
prescribe git add -A. A tracked record is a working tree that is dirty after every served
session. The check asks git check-ignore rather than grepping, because ignoring can come from
.git/info/exclude or a global file.
It is a staging buffer, not the record of last resort. The history is the graph is this
project's premise. Folding this file into a refresh:-class commit is a scheduled run, not
something a tool call does. git commit-tree on the read path would make the cheapest tool call
the most expensive thing the server does. It would also give serve a git-write path that the
act tier's identity gate currently guards alone. A record of what was retrieved is
operational under RFC-0026. It is closest to index: in the
commit vocabulary's own table, so it needs no new authority concept.
yidam record --fold is that run. It counts the file's new lines into .yidam/consumption.json
and commits it as one refresh: commit on the current branch. The tracked file holds counts, not
lines, so the history grows with distinct tools and nodes rather than with traffic. A returned
node keeps how often it came back, and loses which call it came back with. The fold never
truncates the file. It remembers how many bytes it has counted, and takes only complete lines past
that point. A line a server is writing during the fold is the next fold's, so none is lost or
counted twice. With nothing new, it writes no commit, so it is safe on a clock. yidam record
then reads both: the committed counts, and whatever the file has gained since. Deleting the file
after a fold loses nothing, but only the operator knows no server is still writing to it.
Not [serve] act under another name. act declares what a server may write into the graph.
It carries an identity gate, because the history it writes is the knowledge graph. This key
declares that the server keeps an operational record of what it was asked. It needs no author,
because nothing it writes is testimony. Nor is this the record in disclose/record below. That
one is a catalog entry's record of a source, judged for disclosure.
.yidam/policy/
The rules this repository writes about itself (RFC-0024), as Rego. Absent in every corpus until somebody disagrees with a default — the binary carries a complete rule set, and this directory exists only to supersede part of it.
.yidam/policy/
record.rego # package yidam.disclose.record — supersedes the default
record_test.rego # your cases for it
A file overrides by package name. Declaring package yidam.disclose.record replaces that
decision entirely; every other decision stays the one the binary shipped, and yidam policy check says which is which.
The local rule decides, including by being more permissive. That is the model RFC-0024
settled on, and the cost is that a loosened guard is a rule nobody is stopped from writing. It
is not, however, a rule anybody can write quietly: policy check names every override, and
policy test runs the inherited cases against yours and reports what they no longer say.
An override shows up in three places, none of which fails a build:
| Where | What it says |
|---|---|
yidam policy check | the decision is local, and the file it came from |
yidam lint — policy-override, Info | one finding per overridden decision, in the JSON report and therefore in the editor |
yidam doctor — policy | how many decisions are this repository's, and whether every rule compiles |
doctor is also where a broken policy is caught: a rule that does not compile, or that
names a builtin this build does not carry, is a fail — a rule that cannot answer refuses
nothing. That is deliberately not a new CI job. doctor is already offline and read-only and
derived CI already runs it, and machinery nobody invokes is how a check comes to cover nothing.
Two things belong nowhere near this directory:
- The vendored copy.
.yidam/.vendor/prelude/policy/is the default policy as shipped, and it is read-only like the rest of the vendored prelude — an edit there is discarded at the next re-vendor. It is the copy you read; this is the one you write. - A credential. Nothing here is secret and everything here is committed.
.yidam/lint-baseline.yml
The ratchet. It records the findings a corpus already had when the baseline was written, so
yidam lint can answer did this change make the corpus less clean? rather than is the
corpus clean? — which is the only question a corpus with inherited debt can usefully be asked.
Generated, sorted for a stable diff, and identified by node path plus message. You do not hand-edit it.
yidam lint --init-baseline # write it only if absent — the adoption path, safe to re-run
yidam lint --bless # rewrite it from this run, accepting the current findings
Two consequences worth knowing:
- A baselined finding that is later repaired fails the build. The baseline says "this was broken"; a fix means the entry no longer describes reality, and a stale ratchet is a ratchet that has stopped ratcheting. Re-bless after a cleanup pass.
- Baseline membership outranks severity in the editor. Inherited debt renders as a Hint however severe the finding is. The severity read is the finding's own, not its check's — see Editor setup.
Commit-vocabulary findings are baselined by commit, not by file: history is immutable, so a baselined commit stays baselined.
.yidam/decisions/proposals.yml
Bootstrap writes this decision record when you approve its proposals. Two of its fields are read again on every re-vendor:
prelude_domains: []
prelude_sources:
- scholarly@^0.1
- us-oh-legislature@^0.3 from github.com/<owner>/<corpus>@<commit>
prelude_domains names the domain libraries to vendor into .yidam/.vendor/domains/.
A domain is vendored only when this field names it. mise run yidam-vendor-update copies exactly
those, with the index and the parity harness. An empty list vendors none, and is the common case.
Write the field even when it is empty, because the empty list is a decision. Where the field is
absent, the update keeps exactly what the repository already vendored. To vendor a domain later,
add its name and re-run the update.
prelude_sources pins the source packs a re-vendor copies into .yidam/.vendor/sources/.
<pack>@<range> names a pack the template ships. A pin ending from <repo>@<commit> names one
another corpus wrote, at a full 40-character commit. A pin the update cannot satisfy refuses
the whole update, before anything changes. No pins vendors no packs.
Source packs covers the pack format and yidam source check.
.yidam/tonpa.toml
Bundle dependencies on other derived corpora. Written by yidam tonpa add; the lock file
beside it records the hashes tonpa verify checks.
[package]
name = "my-domain"
[dependencies.upstream-hydrology]
github = "someone/hydrology-corpus"
tag = "v1.2.0"
[index]
merge_imported_index = true
A dependency is named by exactly one source — github, url, or path. A path may add
rev = "<full sha>" to read the sibling at that commit instead of its working tree. merge_imported_index
defaults to true: an imported corpus's vectors join the local index so retrieval spans both.
A repository with no dependencies and one that never declared any are the same answer to every
caller, and neither is an error.
Sharing a derivation covers what a cross-corpus citation is and is not.
.yidam/corpus/<class>.ont.yml
Class definitions live at .yidam/corpus/<class>.ont.yml and are configuration in the sense
that matters most: they decide what the gate will and will not accept.
Information architecture has the full
shape. Three fields are worth calling out here because their defaults are load-bearing.
required: on a property defaults to false. It is what lets the missing-property check
gate at all — without it the check cannot distinguish every instance of this class has this
from an instance may have this, and gating on the second reading asserts a contract the
ontology never wrote. Defaulting it to true would demand a declaration nobody made, in every
derived repository at once.
Absent and false both mean an instance may omit the property, but they report differently.
missing-property warns about an omission where the property says nothing. It is silent where
the property says required: false, because the class has already answered.
implemented_by: is absent by default, and nothing is checked without it. A class may
name the struct or enum under crates/ that implements it, and unimplemented-class then
gates when the tree defines no type of that name — the class stated a fact about the code, and
a missing type contradicts it. Reading the absence of a type as a finding was measured and
rejected: across twelve derived corpora 129 of 157 declared classes have no type bearing their
name, and matching traits, aliases and every language in the tree raises it to 165 of 186. An
ontology models a domain while crates/ models the pipeline that gathers evidence about it, so
a class with no type is the ordinary case rather than debt. Name the type as Rust spells it —
HTTPServer and HttpServer are two types and one kebab-case name, so nothing is derived.
A property type: the corpus coins is carried through unconstrained. string, text,
date, number, ref, claim, quotation and list are the types the tooling understands; anything
else is accepted and left alone rather than rejected. A number is written unquoted. Its unit,
if it has one, is declared once on the property as unit: rather than in each value. A
quotation holds of: and span:: a catalog entry and words copied from it. Lint compares
the words with the entry's cached bytes. Add sha256: when the entry holds more than one
artifact.
A list holds several values, and declares what they are in one of two ways.
items: number makes every item a number. fields: makes every item a record, declared in
the grammar a property is:
- name: effects
type: list
fields:
- { name: label, type: string, required: true }
- { name: value, type: number, unit: elasticity }
- { name: claim_tag, type: claim }
- { name: source, type: ref }
A record is closed, as a class is: property-type reports a key no field names. A claim
field is the standing of that entry, not of the node, and is counted once per entry. In an
entry that has one, source must resolve as a link's source: does
(entry-source-unresolved). A bare type: list holds any non-empty list. Declaring both
items: and fields:, or a field typed list or quotation, is reported by
list-declaration-invalid. See RFC-0050.
A string may declare the values it admits, as values: [extant, demolished, ruin]
beside type:. Declaring the set closes it. property-type reports an instance holding
anything else and names the set. The compiled class schema carries the set as enum. The
match is exact, as written. The field binds string only. On every other type it is carried
through unchanged. A set on a coined type constrains nothing until the property is retyped.
A coined type is read by nothing. Its values pass every check, so
property-type-unknown warns on it, for a property or a record field. The known types are
string, text, ref, date, number, claim, quotation and list. A value holding
records is a list with fields:. The finding does not gate.
Environment variables
| Variable | Read by | Effect |
|---|---|---|
YIDAM_BIN_DIR | install.sh | Install target, default ~/.local/bin |
YIDAM_VERSION | install.sh | Install a specific tag rather than the latest |
YIDAM_REPO | install.sh | Resolve releases from a fork |
GITHUB_TOKEN | install.sh | Optional. Raises the release-listing rate limit; the anonymous limit is 60/hour per IP |
YIDAM_API | install.sh | GitHub API origin, default https://api.github.com — for an Enterprise host |
YIDAM_REF | yidam-vendor-update, yidam-vendor-status | Target a tag, branch or HEAD instead of the newest cli/v* release |
YIDAM_CODE | ext-dev | The editor CLI, when code is not on PATH |
YIDAM_REQUIRE_CONTRACT | extension tests | Turn a missing or stale binary from a skip into a failure; CI sets it |
YIDAM_BUILD_COMMIT | build script | Stamps the commit yidam --version reports |
YIDAM_SERVE_TOKEN | serve --mcp --http | The bearer token every request must carry. An empty value is refused; so is setting it beside --token-file |
YIDAM_VAULT_<NAME>_ACCESS_KEY_ID, _SECRET_ACCESS_KEY, _SESSION_TOKEN | every vault command | One vault's keys. <NAME> is upper-cased, hyphens as underscores |
YIDAM_VAULT_<NAME>_ROLE_ARN, _WEB_IDENTITY_TOKEN_FILE, _ROLE_SESSION_NAME | every vault command | One vault's role, assumed by web identity. A vault given its own role and its own keys is refused |
YIDAM_INDEX_ACCESS_KEY_ID, _SECRET_ACCESS_KEY, _SESSION_TOKEN | the remote index | Keys for the vector index [index.remote] declares |
YIDAM_INDEX_ROLE_ARN, _WEB_IDENTITY_TOKEN_FILE, _ROLE_SESSION_NAME | the remote index | A role for that index, assumed by web identity. Its own role and keys together are refused |
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_ROLE_ARN, AWS_WEB_IDENTITY_TOKEN_FILE | the default vault and the remote index only | The fallback when their own variables are unset. Never read for any other vault |
AWS_ENDPOINT_URL_STS | web identity | The STS endpoint; otherwise the regional one for AWS_REGION |
Editor settings
The VS Code extension contributes five settings; Editor setup explains when each matters.
| Setting | Default | Effect |
|---|---|---|
yidam.path | "" | An explicit binary path, outranking every other resolution step |
yidam.lint.showBaselined | true | Show findings the baseline already records, as faded Hints |
yidam.diagnostics.debounceMs | 400 | Wait after a save before re-running the reports — they walk the whole corpus per run |
yidam.claims.decorate | true | Tint [verified] / [inference] / [open] inline |
yidam.vendor.protect | true | Guard .yidam/.vendor/ against edits the next re-vendor would discard |
yidam.claims.decorate is always off in high-contrast themes regardless of this setting: a
high-contrast theme is a stated accessibility choice, and tinting text against it would override
a decision the reader made deliberately.
Turning showBaselined off loses nothing a reader needs — the debt is still in
.yidam/lint-baseline.yml and still in the gate.