jschoubben
37b46d5349
Design 33 in progress against ADR 0154 (the twelve verbs, the prerequisites built); design 35 for the records module under ADR 0153, extending 0025; as-is 07 rewritten to a mesh that keeps no store; as-is 12 and 13 updated; issue 006 built and waiting on its live check.
114 lines
7.1 KiB
Markdown
114 lines
7.1 KiB
Markdown
---
|
|
topic: how we work
|
|
status: accepted
|
|
date: 2026-09-30
|
|
deciders: jochen
|
|
reconstructed: false
|
|
extends: 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](0025-the-design-record-is-read-not-copied.md) 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](../04-ISSUES/006-hq-is-not-indexed-into-the-knowledge-base/00-report.md): 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](../03-DESIGN/01-to-be/15-the-agent-session.md) — 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](../04-ISSUES/147-the-operators-tools-still-dial-the-bus-that-was-removed/00-report.md)).
|
|
|
|
**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](0152-the-operators-surface-is-a-module-the-console.md)). 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](0112-a-module-definition-names-no-node-mesh-or-path.md)): 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`](../03-DESIGN/00-as-is/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](0025-the-design-record-is-read-not-copied.md) — extended: the reader is a module, the search is the console's list
|
|
- [ADR 0152](0152-the-operators-surface-is-a-module-the-console.md) — what lists it
|
|
- [issue 006](../04-ISSUES/006-hq-is-not-indexed-into-the-knowledge-base/00-report.md) — what closes
|
|
- [35 — Reading the record](../03-DESIGN/01-to-be/35-reading-the-record.md) — the design
|
|
- mesh-catalog `modules/records` — the module (PR 183)
|