hq/02-DECISIONS/0153-the-record-is-read-by-a-module-and-the-console-lists-it.md

topic, status, date, deciders, reconstructed, extends

topic	status	date	deciders	reconstructed	extends
how we work	accepted	2026-09-30	jochen	false	02-DECISIONS/0025-the-design-record-is-read-not-copied.md

153. The record is read by a module the mesh assigns, and the console lists it

Context

ADR 0025 decided that this repository is read where it is written, never copied to be found: an agent reads it directly, and a search of the mesh's memory consults that agent so its answers appear beside ordinary results. It named the check that closes issue 006: search for a phrase that appears only in a design document here, and get it back. It gated the build on an agent that did not exist — the mesh session of 15 — The agent session — and on a search that does not exist either, now: the knowledge base 0025 meant was the predecessor's, and since the cut-over nothing reaches it (issue 147).

So the two halves of 0025 have no home. There is no store to be "beside", and no session to be the reader. What the mesh has instead, since today: a tool model in which every module answers what it serves, and a console on the machine a person sits at that lists every tool the running modules answer (ADR 0152). An agent holding the console does not search a store; it reads a tool list and calls what fits the question.

What 0025 could not tolerate was a derived copy — the enforced copy winning while the reasoned one quietly stops being true. It rejected a sync for that reason and for no other. A git checkout is not a derived copy: it is the same bytes at a commit the answer names, and the only way it can differ from the source is by lagging behind it, which is measurable and stated. 0025's own words allow it — retrieval is an agent reading this repository, not a copy living in a second store — and the transformation that makes a copy dangerous is exactly what a checkout does not do.

Considered Options

1. Wait for the mesh session. Rejected. Design 15 is designed with nothing built, its model access is a provisions question with no consumer identity yet, and 006 has waited since 2026-08-23. A record whose check cannot run is a rule enforced by nothing.

2. The console reads the repository itself. Rejected. The console holds nothing and decides nothing (ADR 0152, ADR 0035); a reader inside it would be a second implementation of a thing that should be one module, unavailable to a person's client and to any other module.

3. A module that keeps a checkout of the repository and answers questions about it, listed by the console like any tool. Chosen.

Decision

The reader is a module: records. It requires the git provision — the forge — clones the repository its settings name, keeps the checkout current on every merge the forge announces and on a timer, and answers over the bus: where a phrase appears as written (document, line, nearest heading), one document whole, what a folder holds, and where the checkout stands — always with the commit it read. Nothing is indexed, ranked or summarised: a design record is found by its own words, and a reader deciding which words matter would be a second opinion about somebody else's document.

The repository is a setting, not a manifest field. The module names no mesh (ADR 0112): which repository it reads is the assignment's business, and an installation that keeps its record elsewhere sets that. Until a repository is set it serves no tools and says why. Public repositories only; it asks for no credential, because a secret it did not need would be one more thing to seal.

"Beside everything else" is the console's tool list. 0025's second half — the search consults the agent — has no store to consult and needs none: the console lists records_search beside the forge's tools and the mesh's own verbs, with a description that says when to call it, and an agent choosing tools for a symptom is the search. That is surfacing, not merely reaching: nobody has to know this repository exists to be offered it.

Reading stays one-way. The module reads the forge and answers; nothing flows back into the repository. It holds no credential that could write.

The mesh session, when it exists, is a caller of this module, not a replacement for it. Design 15's it holds the design record by reading it is satisfied by asking records; the session brings judgement, this brings the text.

Consequences

• Issue 006 closes on 0025's own check, run through the console: records_search for a phrase that appears in one design document here returns that document. The module's test does the same against a repository it makes.
• The as-is knowledge document is rewritten. 07-knowledge.md described the predecessor's two stores; neither is reachable from the mesh, and what the mesh knows is now what its modules answer. Saying otherwise is the failure this repository exists to name.
• A checkout lags. Between a merge and the next sync — seconds when the forge announces it, minutes when it does not — an answer is the previous commit's, and says which. That is the cost of no copy, and it is a number rather than a silence.
• The reader depends on the forge module's event, by name. consumes: gitea.pull.merged names a module rather than the git seat, because the seat declares no events. A forge that is not gitea leaves the timer as the only refresh, which still works.
• What got harder: the record is now reachable from every machine holding a console, which is what was wanted, and a reader must remember that this repository is public and the mesh is not — the module reads the public repository and nothing about the installation.

How this is checked

Rule	Checked by
A phrase in one document comes back from where it is written, with the commit	the module's test against a repository it makes; and live, through the console
A merge on the origin is pulled and the next answer names the new commit	the same test
A path outside the checkout is refused, not resolved	a test per shape
A failed sync leaves the checkout standing and is said	a test against an unreachable origin
Without a repository set, no tools are served and the log says why	the module's own start
The console lists records_search beside every other tool	the console's listing, live

References

• ADR 0025 — extended: the reader is a module, the search is the console's list
• ADR 0152 — what lists it
• issue 006 — what closes
• 35 — Reading the record — the design
• mesh-catalog modules/records — the module (PR 183)