mesh-knowledge: a record may change a drafted clause, and a record whose clauses others link by number is never redrafted (hq issue 494, ADR 0321) #245

Merged
mesh-admin merged 1 commits from fix/494-change-a-drafted-clause into main 2026-10-12 12:18:34 +00:00
Contributor

Fixes issue 494 (a record cannot declare that it changes a clause the knowledge base holds only as drafted). Decided in ADR 0321 (proposed 2026-10-12, needs the operator's Approve; changes ADR 0290 §8 for return).

What was wrong

  • propose refused every changes link onto a drafted clause (changes-in-force: "never superseded, proposed or drafted"). ADR 0290 §8 only says a drafted clause is never served as in force; nothing decided it may not be changed. Hit by ADR 0294 (changes 0281 §4), ADR 0301 (changes 0110 §4, issue 514) and ADR 0320 (changes 0281 §9, issue 547).
  • The only way around, return, drafts the record again and numbers its clauses anew: it renumbered ADR 0281 (14 clauses became 11) and pointed other records' links by number at other clauses.

What changes (modules/mesh-knowledge)

  • rules.go: changes-in-force refuses only a superseded or proposed clause; a drafted one (confirmed or not) may be changed. Acceptance already marks the target clause changed with changed-by; it keeps its number and its drafted source, so Served stays false.
  • answers.go: a drafted clause's holds adds "; changed by ADR NNNN §N: read both" (or superseded by), so get/ask say both.
  • draft.go: return refuses a record any of whose clauses another record changed, or links by clause number in a served or proposed version (withdrawn ignored). The refusal names each link and says the way forward (changes NNNN §N). Nothing is written. A record nobody links by clause is returned as before.
  • main.go (the verb's description) and README say both.

Tests

  • issue494_test.go (memory and postgres stores):
    • TestARecordMayChangeAClauseHeldOnlyAsDrafted: 0240 §1 drafted and rejected by the second judgement; a record with §2 changes 0240 §1 is proposed, reviewed, accepted; 0240 §1 is changed, keeps its number, stays drafted, is not served; get says drafted and changed by; no partial finding.
    • TestARecordWhoseClausesAreLinkedByNumberIsNeverReturned: a proposed record citing 0240 §2 blocks return (refusal names it and the way forward, no version written, no event); a record whose clause was changed blocks it too.
    • Both fail on main (propose refuses with changes-in-force; return takes the record).
  • The table test keeps the changes-in-force case (a superseded clause is refused); still 29 rules.
  • go vet, go test ./... in the module; MESH_GATE=<controller built from mesh-controller main 4b1dee6> MESH_CHECK_MODULES=mesh-knowledge sh merge-check.sh passes.

Limits I chose

  • return is refused rather than made renumber-safe: a redraft cannot promise the same clauses, so a linked record is corrected by a record that changes the drafted clause. A clause-by-clause redraft in place is not built.
  • A pending hq supersedes-in-part (judged at the import) still waits for a confirmed clause in the older record; unchanged here.
  • No schema change, no data touched.

Reviewers' checklist

  • New tests fail without the fix; checks green.
  • A change of a drafted clause is accepted and the clause is still never served as in force.
  • return never writes a version for a record another record links by clause number.

By fix-494@g14. Not merged.

Fixes issue 494 (a record cannot declare that it changes a clause the knowledge base holds only as drafted). Decided in **ADR 0321** (proposed 2026-10-12, needs the operator's Approve; changes ADR 0290 §8 for `return`). ## What was wrong - `propose` refused every `changes` link onto a drafted clause (`changes-in-force`: "never superseded, proposed or drafted"). ADR 0290 §8 only says a drafted clause is never *served* as in force; nothing decided it may not be changed. Hit by ADR 0294 (`changes 0281 §4`), ADR 0301 (`changes 0110 §4`, issue 514) and ADR 0320 (`changes 0281 §9`, issue 547). - The only way around, `return`, drafts the record again and numbers its clauses anew: it renumbered ADR 0281 (14 clauses became 11) and pointed other records' links by number at other clauses. ## What changes (modules/mesh-knowledge) - `rules.go`: `changes-in-force` refuses only a superseded or proposed clause; a drafted one (confirmed or not) may be changed. Acceptance already marks the target clause `changed` with `changed-by`; it keeps its number and its `drafted` source, so `Served` stays false. - `answers.go`: a drafted clause's `holds` adds "; changed by ADR NNNN §N: read both" (or superseded by), so `get`/`ask` say both. - `draft.go`: `return` refuses a record any of whose clauses another record changed, or links by clause number in a served or proposed version (withdrawn ignored). The refusal names each link and says the way forward (`changes NNNN §N`). Nothing is written. A record nobody links by clause is returned as before. - `main.go` (the verb's description) and README say both. ## Tests - `issue494_test.go` (memory and postgres stores): - `TestARecordMayChangeAClauseHeldOnlyAsDrafted`: 0240 §1 drafted and rejected by the second judgement; a record with `§2 changes 0240 §1` is proposed, reviewed, accepted; 0240 §1 is `changed`, keeps its number, stays `drafted`, is not served; `get` says drafted and changed by; no `partial` finding. - `TestARecordWhoseClausesAreLinkedByNumberIsNeverReturned`: a proposed record citing 0240 §2 blocks `return` (refusal names it and the way forward, no version written, no event); a record whose clause was changed blocks it too. - Both fail on main (propose refuses with changes-in-force; return takes the record). - The table test keeps the `changes-in-force` case (a superseded clause is refused); still 29 rules. - `go vet`, `go test ./...` in the module; `MESH_GATE=<controller built from mesh-controller main 4b1dee6> MESH_CHECK_MODULES=mesh-knowledge sh merge-check.sh` passes. ## Limits I chose - `return` is refused rather than made renumber-safe: a redraft cannot promise the same clauses, so a linked record is corrected by a record that changes the drafted clause. A clause-by-clause redraft in place is not built. - A pending hq `supersedes-in-part` (judged at the import) still waits for a confirmed clause in the older record; unchanged here. - No schema change, no data touched. ## Reviewers' checklist - [ ] New tests fail without the fix; checks green. - [ ] A change of a drafted clause is accepted and the clause is still never served as in force. - [ ] `return` never writes a version for a record another record links by clause number. By fix-494@g14. Not merged.
mesh-admin added 1 commit 2026-10-12 12:05:54 +00:00
mesh-knowledge: let a record change a drafted clause, and never redraft a record whose clauses others link by number
mesh/merge-gate pass: builds mesh-knowledge → novox; no bus step; every machine composes with the change as it did without (4 of 4 compose)
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 delivered
9f893b6305
A changes link onto a drafted clause was refused, so records that really
change such a rule could only cite it (ADR 0294, 0301, 0320); and return
renumbered ADR 0281's clauses, pointing other records' links at other
clauses. The changed drafted clause keeps its number and stays unserved;
return refuses a record whose clauses another record changed or links by
number. Issue 494, ADR 0321.
Author
Contributor

Delivery novox/mesh-catalog@9f893b630572 — delivered since 2026-10-12T12:25:42Z

Delivery plan — builds mesh-knowledge → novox; no bus step

  • tier 0: mesh-knowledge
  • novox: receives mesh-knowledge

Machines

  • mesh-knowledge on novox: passed — healthy 1 times over 1m40s
  • mesh-knowledge on the rest running it: sent

Transitions

  • 2026-10-12 12:06 (new) → proposed (announced): novox/mesh-catalog#245's head announced
  • 2026-10-12 12:12 proposed → checked (checked): the verdict names this commit
  • 2026-10-12 12:12 checked → ready (accepted): the gate passed or warned, and the repository's own check did not fail
  • 2026-10-12 12:22 ready → published (merged): on the trunk its modules follow: merged there, and its walk opened — or nothing for a walk to move
  • 2026-10-12 12:22 published → delivering (go): its walk started: let go by this owner in its group's order, by a person, or on the controller's own path — not a failed walk that carried a later commit for it, after which it waits for a walk of its own commit
  • 2026-10-12 12:25 delivering → delivered (done): its walk is done, carrying its own commit: every machine of its deploy plan passed, or was left as its policy says

The commit's note under refs/notes/mesh-plan keeps every transition: git log --notes=mesh-plan.

<!-- mesh-delivery:view --> **Delivery** `novox/mesh-catalog@9f893b630572` — **delivered** since 2026-10-12T12:25:42Z **Delivery plan** — builds mesh-knowledge → novox; no bus step - tier 0: mesh-knowledge - novox: receives mesh-knowledge **Machines** - mesh-knowledge on novox: passed — healthy 1 times over 1m40s - mesh-knowledge on the rest running it: sent **Transitions** - 2026-10-12 12:06 (new) → proposed (announced): novox/mesh-catalog#245's head announced - 2026-10-12 12:12 proposed → checked (checked): the verdict names this commit - 2026-10-12 12:12 checked → ready (accepted): the gate passed or warned, and the repository's own check did not fail - 2026-10-12 12:22 ready → published (merged): on the trunk its modules follow: merged there, and its walk opened — or nothing for a walk to move - 2026-10-12 12:22 published → delivering (go): its walk started: let go by this owner in its group's order, by a person, or on the controller's own path — not a failed walk that carried a later commit for it, after which it waits for a walk of its own commit - 2026-10-12 12:25 delivering → delivered (done): its walk is done, carrying its own commit: every machine of its deploy plan passed, or was left as its policy says The commit's note under `refs/notes/mesh-plan` keeps every transition: `git log --notes=mesh-plan`.
Author
Contributor

Merge check at 9f893b63

  • mesh/merge-gate: PASS — every machine composes with the change as it did without (4 of 4 compose) (modules: mesh-knowledge)
  • mesh/repo-check: PASS — its merge-check.sh passed, each part in its toolchain: merge-check.sh (go), merge-check-typescript.sh (typescript)

Delivery plan — builds mesh-knowledge → novox; no bus step

  • tier 0: mesh-knowledge
  • novox: receives mesh-knowledge
  • read by no module's build: modules/mesh-knowledge/README.md, modules/mesh-knowledge/cmd/mesh-knowledge/issue494_test.go

Run by the build seat on ace as build-1791806771391756292 (builds --log build-1791806771391756292).

--- the gate: mesh-knowledge
note: mesh-knowledge uses the seat "operator-channel", which no module declares and the mesh does not define among the manifests given; registration judges it against the whole catalogue, and passing the declaring module's manifest too judges it here
mesh-knowledge: ok, 2 tool(s), invokes seat:issue-tracker.reserve, claude-code.claude_code_judge, claude-code.claude_code_judged, records.records_status, records.records_list, records.records_read, seat:operator-channel.notify, ready: keep by unit every 30s; watch by its tool knowledge_health every 1m0s
long-running resources without health: 0
files asking for a setting without saying whether it is trusted: 0
1 manifest(s) checked. Judged against the seats this binary carries; a claim on one of the mesh's own seats is judged fully at registration, and a seat declared by a module not given here reads as unknown. Identities judged on a 6-character machine name, against the bounds of the providers given here
judging 0 module(s) changed against 4 machine(s), as the snapshot of 2026-10-12T12:01:38Z says they run
composing every machine as the mesh is
the bus's user list leaves out 5 user(s) the mesh has minted no credential for: controller, node.f35, node.idt, node.ygcyr, node.yvbpsm. Each is a user that cannot connect until one is issued
the bus's user list leaves out 5 user(s) the mesh has minted no credential for: controller, node.f35, node.idt, node.ygcyr, node.yvbpsm. Each is a user that cannot connect until one is issued
composing every machine with the change
the bus's user list leaves out 5 user(s) the mesh has minted no credential for: controller, node.f35, node.idt, node.ygcyr, node.yvbpsm. Each is a user that cannot connect until one is issued
the bus's user list leaves out 5 user(s) the mesh has minted no credential for: controller, node.f35, node.idt, node.ygcyr, node.yvbpsm. Each is a user that cannot connect until one is issued
merge gate: PASS — every machine composes with the change as it did without (4 of 4 compose)
judged by controller development build against the facts of 2026-10-12T12:01:38Z

machines:
  - a machine (f35): composes
  - holds mesh-dns-resolver (idt): composes
  - holds git, holds mesh-artifact-store, holds mesh-broker, holds mesh-catalog, holds mesh-delivery, holds mesh-dns-resolver, holds mesh-store, holds mesh-vault, holds npm-package-registry, the control node, the hub (ygcyr): composes
  - a machine (yvbpsm): composes

a merge would rebuild 1 module(s) in 1 tier(s): mesh-knowledge

notes:
  - modules/mesh-knowledge/README.md and modules/mesh-knowledge/cmd/mesh-knowledge/issue494_test.go read by no module's build, and rebuild nothing (issue 280)
--- its merge-check.sh (go toolchain)
ok  	git.novox.be/novox/mesh-catalog/checks/words	0.002s
words: 12 retired words and 70 daemons' lines, none in the 43193 strings of 690 files
ok  	git.novox.be/novox/mesh-catalog/checks/agenthome	0.012s
agent-home: no archive and no file written into under the agent's home
ok  	git.novox.be/novox/mesh-catalog/checks/paths	0.007s
paths: no module names another's state on its machine (3 known, listed to go)
long-running resources without health: 69, as kept
ok  	git.novox.be/novox/mesh-catalog/checks/deps	0.218s
testing modules/mesh-knowledge
ok  	mesh-knowledge/cmd/mesh-knowledge	105.606s
--- its merge-check-typescript.sh (typescript toolchain)
**Merge check** at `9f893b63` - `mesh/merge-gate`: **PASS** — every machine composes with the change as it did without (4 of 4 compose) (modules: mesh-knowledge) - `mesh/repo-check`: **PASS** — its merge-check.sh passed, each part in its toolchain: merge-check.sh (go), merge-check-typescript.sh (typescript) **Delivery plan** — builds mesh-knowledge → novox; no bus step - tier 0: mesh-knowledge - novox: receives mesh-knowledge - read by no module's build: modules/mesh-knowledge/README.md, modules/mesh-knowledge/cmd/mesh-knowledge/issue494_test.go Run by the build seat on ace as `build-1791806771391756292` (`builds --log build-1791806771391756292`). ``` --- the gate: mesh-knowledge note: mesh-knowledge uses the seat "operator-channel", which no module declares and the mesh does not define among the manifests given; registration judges it against the whole catalogue, and passing the declaring module's manifest too judges it here mesh-knowledge: ok, 2 tool(s), invokes seat:issue-tracker.reserve, claude-code.claude_code_judge, claude-code.claude_code_judged, records.records_status, records.records_list, records.records_read, seat:operator-channel.notify, ready: keep by unit every 30s; watch by its tool knowledge_health every 1m0s long-running resources without health: 0 files asking for a setting without saying whether it is trusted: 0 1 manifest(s) checked. Judged against the seats this binary carries; a claim on one of the mesh's own seats is judged fully at registration, and a seat declared by a module not given here reads as unknown. Identities judged on a 6-character machine name, against the bounds of the providers given here judging 0 module(s) changed against 4 machine(s), as the snapshot of 2026-10-12T12:01:38Z says they run composing every machine as the mesh is the bus's user list leaves out 5 user(s) the mesh has minted no credential for: controller, node.f35, node.idt, node.ygcyr, node.yvbpsm. Each is a user that cannot connect until one is issued the bus's user list leaves out 5 user(s) the mesh has minted no credential for: controller, node.f35, node.idt, node.ygcyr, node.yvbpsm. Each is a user that cannot connect until one is issued composing every machine with the change the bus's user list leaves out 5 user(s) the mesh has minted no credential for: controller, node.f35, node.idt, node.ygcyr, node.yvbpsm. Each is a user that cannot connect until one is issued the bus's user list leaves out 5 user(s) the mesh has minted no credential for: controller, node.f35, node.idt, node.ygcyr, node.yvbpsm. Each is a user that cannot connect until one is issued merge gate: PASS — every machine composes with the change as it did without (4 of 4 compose) judged by controller development build against the facts of 2026-10-12T12:01:38Z machines: - a machine (f35): composes - holds mesh-dns-resolver (idt): composes - holds git, holds mesh-artifact-store, holds mesh-broker, holds mesh-catalog, holds mesh-delivery, holds mesh-dns-resolver, holds mesh-store, holds mesh-vault, holds npm-package-registry, the control node, the hub (ygcyr): composes - a machine (yvbpsm): composes a merge would rebuild 1 module(s) in 1 tier(s): mesh-knowledge notes: - modules/mesh-knowledge/README.md and modules/mesh-knowledge/cmd/mesh-knowledge/issue494_test.go read by no module's build, and rebuild nothing (issue 280) --- its merge-check.sh (go toolchain) ok git.novox.be/novox/mesh-catalog/checks/words 0.002s words: 12 retired words and 70 daemons' lines, none in the 43193 strings of 690 files ok git.novox.be/novox/mesh-catalog/checks/agenthome 0.012s agent-home: no archive and no file written into under the agent's home ok git.novox.be/novox/mesh-catalog/checks/paths 0.007s paths: no module names another's state on its machine (3 known, listed to go) long-running resources without health: 69, as kept ok git.novox.be/novox/mesh-catalog/checks/deps 0.218s testing modules/mesh-knowledge ok mesh-knowledge/cmd/mesh-knowledge 105.606s --- its merge-check-typescript.sh (typescript toolchain) ```
mesh-admin left a comment
Author
Contributor

Verdict: approve at 9f893b6

Independent review for issue 494, built to ADR 0321 (accepted; it needed the operator, and the operator approved it).

Checks. mesh/merge-gate passes (builds mesh-knowledge for novox; 4 of 4 machines compose). mesh/repo-check passes. Locally: go vet ./... is clean and go test -race -count=1 ./... passes (120 s, memory and postgres stores).

The tests fail on main. I took rules.go, draft.go and answers.go from main and kept the new tests. Both tests then fail on both stores. TestARecordMayChangeAClauseHeldOnlyAsDrafted fails because the change is refused by changes-in-force. TestARecordWhoseClausesAreLinkedByNumberIsNeverReturned fails because the record is returned.

It matches ADR 0321:

  • §1: changes-in-force now refuses only a clause that is superseded or proposed. The c.Source == SourceDrafted condition is gone, and so is the source in the refusal text.
  • §2: the change keeps the clause's number and its drafted source. Served() still requires Source != SourceDrafted, so a changed drafted clause is never served as in force; the test asserts !Served. held() keeps "drafted, not confirmed: … never in force" and adds "; changed by ADR NNNN §N: read both" (or "superseded by"). get, ask and holds all use held().
  • §3: Return reads the whole set under k.mu, the same lock propose takes, so a link cannot slip in between the check and the return. It refuses when any clause of the record is changed or superseded, or when any other record, current or pending and not withdrawn, links one of its clauses by number. A refused return writes nothing: the version count, the clauses and the events are all unchanged, which the test checks.

The refusal text is true and helpful. It names each link, for example "ADR 0300 (proposed) cites §2" or "§1 is changed by ADR 0300 §2". It says why: a redraft numbers the clauses anew. It gives the way forward that §3 prescribes: "propose a record that changes it (changes 0240 §N)".

Could any other path renumber a linked record?

  • The drafting worker does not: confirming keeps each N. A record still waiting to be drafted has no clauses, so link-target refuses any clause link to it.
  • One theoretical path is left. import with refresh may draft a prose record again when hq's source text differs (carry: "else they are drafted again"). A cites §N link writes no version on the target, so importedOnly would still let the refresh through. In practice this is closed: hq no longer holds the records (issue 426), and import refuses a commit without them. It could only happen through an import at an old commit whose text differs. Not blocking. If it matters, a follow-up could apply clauseHolds in refresh too.

Not blocking:

  1. The "changed" half of the return test runs only on the memory store. The linked-by-number half runs on both.
  2. The ask wording is not asserted on its own. It shares held() with get, which is asserted. The knowledge base's review of ADR 0321 asked for a test of that wording.
Verdict: approve at 9f893b6 Independent review for issue 494, built to ADR 0321 (accepted; it needed the operator, and the operator approved it). **Checks.** mesh/merge-gate passes (builds mesh-knowledge for novox; 4 of 4 machines compose). mesh/repo-check passes. Locally: `go vet ./...` is clean and `go test -race -count=1 ./...` passes (120 s, memory and postgres stores). **The tests fail on main.** I took rules.go, draft.go and answers.go from main and kept the new tests. Both tests then fail on both stores. `TestARecordMayChangeAClauseHeldOnlyAsDrafted` fails because the change is refused by `changes-in-force`. `TestARecordWhoseClausesAreLinkedByNumberIsNeverReturned` fails because the record is returned. **It matches ADR 0321:** - §1: `changes-in-force` now refuses only a clause that is superseded or proposed. The `c.Source == SourceDrafted` condition is gone, and so is the source in the refusal text. - §2: the change keeps the clause's number and its `drafted` source. `Served()` still requires `Source != SourceDrafted`, so a changed drafted clause is never served as in force; the test asserts `!Served`. `held()` keeps "drafted, not confirmed: … never in force" and adds "; changed by ADR NNNN §N: read both" (or "superseded by"). `get`, `ask` and `holds` all use `held()`. - §3: `Return` reads the whole set under `k.mu`, the same lock `propose` takes, so a link cannot slip in between the check and the return. It refuses when any clause of the record is changed or superseded, or when any other record, current or pending and not withdrawn, links one of its clauses by number. A refused return writes nothing: the version count, the clauses and the events are all unchanged, which the test checks. **The refusal text is true and helpful.** It names each link, for example "ADR 0300 (proposed) cites §2" or "§1 is changed by ADR 0300 §2". It says why: a redraft numbers the clauses anew. It gives the way forward that §3 prescribes: "propose a record that changes it (changes 0240 §N)". **Could any other path renumber a linked record?** - The drafting worker does not: confirming keeps each `N`. A record still waiting to be drafted has no clauses, so `link-target` refuses any clause link to it. - One theoretical path is left. `import` with `refresh` may draft a prose record again when hq's source text differs (`carry`: "else they are drafted again"). A `cites §N` link writes no version on the target, so `importedOnly` would still let the refresh through. In practice this is closed: hq no longer holds the records (issue 426), and `import` refuses a commit without them. It could only happen through an import at an old commit whose text differs. Not blocking. If it matters, a follow-up could apply `clauseHolds` in `refresh` too. **Not blocking:** 1. The "changed" half of the return test runs only on the memory store. The linked-by-number half runs on both. 2. The `ask` wording is not asserted on its own. It shares `held()` with `get`, which is asserted. The knowledge base's review of ADR 0321 asked for a test of that wording.
mesh-admin merged commit 13a7d40ac5 into main 2026-10-12 12:18:34 +00:00
mesh-admin deleted branch fix/494-change-a-drafted-clause 2026-10-12 12:18:35 +00:00
Sign in to join this conversation.
No Reviewers
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: novox/mesh-catalog#245