Tighten who writes and reviews a record, date the rules, bound history (review of #206)
mesh/merge-gate pass: builds new: modules/mesh-knowledge, sent nowhere; no bus step; every machine composes with the change as it did without (4 of 4 compo…
mesh/repo-check pass: its merge-check.sh passed, each part in its toolchain: merge-check.sh (go), merge-check-typescript.sh (typescript)
mesh/delivery superseded: a newer head of the same pull request

A revision came from anyone and a review was refused only to the first author,
so a co-writer could approve, and a record proposed before callers are proven
would later be reviewable by its own unproven author. Now a revision is taken
only from the proven author, a reserved number only from whoever reserved it,
and a review is refused from any writer of any version or for any record with
an unproven writer. The rules held records from no date, so a correction to an
older record was refused by rules hq never held it to; each dated rule now holds
from hq's own start date, and a new record cannot be dated before its
reservation. history and the question to ask are bounded like the other answers.
This commit is contained in:
2026-10-11 05:10:02 +02:00
parent ba7b455719
commit 10ab959d0f
10 changed files with 382 additions and 33 deletions
+29 -10
View File
@@ -15,24 +15,34 @@ accepted only on the operator's Approve, given on a channel that proves who answ
| Verb | Takes | Answers |
|---|---|---|
| `ask` | `question`, `bound` | the records and clauses bearing on the question, ranked; each clause says whether it holds, what changed it, or that it is only drafted; each record says what changed it since and how to read its reasoning |
| `ask` | `question` (at most 500 characters), `bound` | the records and clauses bearing on the question, ranked; each clause says whether it holds, what changed it, or that it is only drafted; each record says what changed it since and how to read its reasoning |
| `get` | `number`, `kind`, `reasoning`, `section`, `version`, `bound` | one record: clauses, links both ways, what changed it since, versions, reviews, the operator's ask; its reasoning only when asked |
| `holds` | `topic` or `number`, `bound` | the clauses in force for a topic of the reading order or for one record; never a drafted clause |
| `links` | `number`, `kind` | the record's typed links, out and in |
| `history` | `number`, `kind`, `from`, `to` | every version; with `from` and `to`, the difference between the two, line by line |
| `history` | `number`, `kind`, `from`, `to`, `bound` | every version; with `from` and `to`, the difference between the two, line by line |
| `reserve` | `kind`, `for` | the next decision or research number, asked of the issue tracker (`issue-tracker.reserve`); spent whether or not its record is accepted |
| `propose` | the record whole | proposed, or refused naming every rule it breaks; an accepted record changes only by a progressive insight (`insight`) |
| `review` | `number`, `verdict` (approve or changes), `findings` | accepted, asked of the operator, or kept proposed with the findings |
| `import` | `dry-run`, `commit` | hq's decision records and research efforts at the commit the records module stands at, each whole at its own number |
| `return` | `number`, `reason` | drafted clauses sent back to be drafted again |
`ask`, `get` and `holds` stay within `bound` bytes (4096 unless asked for, at most 65536) and say what they cut
`ask`, `get`, `holds` and `history` stay within `bound` bytes (4096 unless asked for, at most 65536) and say what they cut
and how to read the rest. The module's own tool `knowledge_health` answers its health (below).
**Who acted** is the caller as the runtime proves it, never an argument: no verb takes one. The runtime does not
hand a module its caller yet (hq issue 365), so every change is recorded as by `unproven`. Until it does,
**every review is refused**. A review by the record's author is refused, and with no proven caller a review
cannot be told from one by the author.
**Who acted** is the caller as the runtime proves it, never an argument: no verb takes one. Today the runtime
does not hand a module its caller. The SDK's tool call carries only a name and arguments, so proving the caller
needs an SDK change first (hq issue 365). Until then every change is recorded as by `unproven`. In this module
the caller is read in one place, `callerOf` in `main.go`, so the SDK change touches that one function.
The rules about callers:
- A proposal is revised only by its author, as the runtime proves them.
- A number reserved by a proven caller is proposed only by that caller.
- A review is refused from anyone who wrote any version of the record.
- A review is refused for a record that has a version whose writer was unproven: who wrote it cannot be told
from who reviews it, so its author proposes it again under a new number.
Until the runtime proves callers, **every review is refused**.
## What a record holds
@@ -61,6 +71,16 @@ record it goes out from.
superseder, a graduated effort says what it became, and the links in its text resolve;
- 4 on the prose: no word the glossary retired, no daemon's line, a deferral names its tracking issue, and a
progressive insight in the dated, marked form.
A rule holds a record from the day hq's checks began to hold it (`RuleFrom` in `rules.go`):
- retired words from 2026-10-07;
- daemons' lines and deferrals from 2026-10-09;
- the clauses from 2026-10-11;
- the decision record's sections and the live-citation rule, which no hq check held on a decision record,
from 2026-10-11, the day the knowledge base takes the write.
A progressive insight keeps its record's date, so a correction to an older record is not refused by a rule
that never held it. A new record is dated no earlier than the day its number was reserved.
3. Revise it by proposing again; every version is kept.
4. A `review` by someone else either approves it or asks for changes. On approve the record and its clauses are
accepted and in force. Every clause it changes moves to `changed`, and every record it supersedes moves to
@@ -125,9 +145,8 @@ the consolidated schema for a fresh database is `schema.sql`. A test holds the t
## What it needs at release
- assignment to the control-node, and a postgres provider for its `postgres-database` provision;
- `issue-tracker.reserve` (hq issue 424) before `reserve` works; until then reserve says the tracker did not hand
out a number, and writes nothing;
- the runtime proving the caller (hq issue 365) before any review is taken;
- the issue tracker serving `issue-tracker.reserve` (hq issue 424, merged as mesh-catalog#204) on the mesh;
- the SDK and the runtime proving the caller (hq issue 365) before any review is taken;
- the import run once, then checked against hq record by record (hq issue 426).
## Tests