jschoubben
90b44a48df
Design 35 implemented with what shipped and the live check; 006 closes on ADR 0025's own test, run through the console.
100 lines
5.3 KiB
Markdown
100 lines
5.3 KiB
Markdown
---
|
|
layer: to-be
|
|
status: implemented
|
|
code: [mesh-catalog modules/records]
|
|
updated: 2026-09-30
|
|
decisions:
|
|
- 02-DECISIONS/0153-the-record-is-read-by-a-module-and-the-console-lists-it.md
|
|
- 02-DECISIONS/0025-the-design-record-is-read-not-copied.md
|
|
- 02-DECISIONS/0112-a-module-definition-names-no-node-mesh-or-path.md
|
|
---
|
|
|
|
# 35 — Reading the record
|
|
|
|
**The design record, answered from a checkout the mesh keeps, at the commit it read.** A module,
|
|
`records`, holds a working copy of a repository of markdown — this one, for this mesh — and answers
|
|
where a phrase appears, what a document says, what a folder holds and where the copy stands. The
|
|
console lists those answers beside every other tool
|
|
([ADR 0153](../../02-DECISIONS/0153-the-record-is-read-by-a-module-and-the-console-lists-it.md)).
|
|
|
|
## 1. What it keeps, and why that is not a copy
|
|
|
|
A git checkout, cloned from the forge that holds the `git` seat, brought up to date on every merge the
|
|
forge announces and every ten minutes besides. The bytes are the repository's; nothing is derived
|
|
from them and stored. What [ADR 0025](../../02-DECISIONS/0025-the-design-record-is-read-not-copied.md)
|
|
refused was a second store that is *searched* while the first is *edited*, drifting silently. A
|
|
checkout cannot drift; it can lag, and the lag is in every answer as the commit it was read at and
|
|
in `records_status` as when it was last brought up to date.
|
|
|
|
The checkout is reset to the origin on every sync, never merged: it is the mesh's, so a local change
|
|
is nobody's.
|
|
|
|
## 2. What it answers
|
|
|
|
| tool | answers |
|
|
|---|---|
|
|
| `records_search` | every place a phrase appears, as written and case-insensitively: document, line, the nearest heading above it; bounded, and says when it was |
|
|
| `records_read` | one document, whole, or its first part with a note when very long |
|
|
| `records_list` | what a folder holds: sub-folders and documents |
|
|
| `records_status` | repository, forge, commit and its date, last sync, document count, last error |
|
|
| `records_sync` | bring the checkout up to date now |
|
|
|
|
No ranking and no summary, on purpose: a record is found by its own words, and the reasoning is in
|
|
the document, not in the tool.
|
|
|
|
## 3. What it is told, and what it refuses to guess
|
|
|
|
Three things, none from a manifest ([ADR 0112](../../02-DECISIONS/0112-a-module-definition-names-no-node-mesh-or-path.md)):
|
|
the directory its checkout lives in (a resource the mesh gives it), the forge's address (the `git`
|
|
provision's binding, written into a file as `scheme://host:port`), and the repository's path on the
|
|
forge (a **setting**, `{"repository": "<owner>/<name>"}`). Without the third it serves no tools and its
|
|
log says so. Public repositories only; it holds no credential.
|
|
|
|
## 4. How it is found
|
|
|
|
The console asks every module what it serves and lists `records_search` with a description that says
|
|
when to call it — *search the literal words of a symptom or a term before forming a hypothesis*. That
|
|
is 0025's second half in today's mesh: there is no store to be beside, and an agent choosing from a
|
|
tool list is the search.
|
|
|
|
## 5. Where it runs
|
|
|
|
Anywhere a node has the forge in reach; one assignment is enough, and a second on another machine is
|
|
harmless. The mesh session of design 15, when it exists, calls this rather than reading for itself.
|
|
|
|
## How it is checked
|
|
|
|
| Check | Defends |
|
|
|---|---|
|
|
| a phrase in one document of a repository the test makes comes back from that document, with the commit; a second commit on the origin is pulled and the next answer names it | ADR 0025's check, ADR 0153 |
|
|
| a path outside the checkout is refused; an empty search is refused | the reader reads the repository and nothing else |
|
|
| a sync against an unreachable origin leaves the checkout standing and says why | silence and success never look alike |
|
|
| live: through the console, `records_search` for a phrase that appears only in a design document here returns it | issue 006's closing check |
|
|
|
|
## What shipped, 2026-09-30
|
|
|
|
mesh-catalog PR 183, then PR 185. Verified on the live mesh the same evening: `records` assigned to the
|
|
control node with `{"repository": …}` as its setting, its checkout at the repository's `main` with 478
|
|
documents, its five tools listed by the console beside every other tool, and — ADR 0025's check —
|
|
`records_search` for a phrase from this document's title returned it from where it is written, with
|
|
the commit. The first live search missed: the phrase chosen from ADR 0025 straddled a line break under
|
|
emphasis, and the reader matched single lines. PR 185 matches a line together with the next and
|
|
ignores emphasis marks, which the module's test now covers; until it rolls, a phrase that wraps is one
|
|
to shorten.
|
|
|
|
The reader's `consumes` names the forge module's event rather than the `git` seat, because the seat
|
|
declares none; a merge into the repository was seen and pulled within seconds.
|
|
|
|
## What this does not settle
|
|
|
|
- Ranking or meaning. A search that understands a question is the session's job, not the reader's.
|
|
- A private repository. That is a credential the module would have to hold, and a decision about
|
|
what may read what.
|
|
|
|
## References
|
|
|
|
- [ADR 0153](../../02-DECISIONS/0153-the-record-is-read-by-a-module-and-the-console-lists-it.md)
|
|
- [ADR 0025](../../02-DECISIONS/0025-the-design-record-is-read-not-copied.md)
|
|
- [34 — The console](34-the-console.md) — what lists it
|
|
- [issue 006](../../04-ISSUES/006-hq-is-not-indexed-into-the-knowledge-base/00-report.md)
|