ADR 0275, to-be 53: the issue tracker's module is mesh-issues, holding the seat issue-tracker
mesh/merge-gate pass: the change touches no module of the mesh's graph
mesh/repo-check pass: its merge-check.sh passed
mesh/delivery delivered

The operator named the module on 2026-10-10: the mesh's own parts carry the
mesh- prefix, and the seat is the role. A dated insight in ADR 0275 says so,
and that compare-and-set state was already in the runtime (ADR 0259): slice 1
added the SDK's Increment. To-be 53 and the glossary say the same, and the
design is handed to mesh-catalog and mesh-sdk (in progress).
This commit is contained in:
jochen
2026-10-10 12:52:37 +02:00
parent 2798306de7
commit 8d9eae7224
3 changed files with 26 additions and 13 deletions
+2 -2
View File
@@ -540,8 +540,8 @@ Not a domain of the mesh but of the way it is built, listed because its words me
one at the level of design or governance also has a report in `04-ISSUES/` under the same number
([ADR 0275](../02-DECISIONS/0275-the-mesh-numbers-and-tracks-its-issues-in-a-module-of-its-own-and-hq-keeps-only-the-narrative-of-a-design-or-governance-issue.md)).
An **incident** is a past event that taught a rule.
- **issue tracker** — the module that holds the mesh's issues and hands out their numbers, named `issues`,
holding the seat `issue-tracker` ([53 — The issue tracker](../03-DESIGN/01-to-be/53-the-issue-tracker.md)).
- **issue tracker** — the role that holds the mesh's issues and hands out their numbers: the seat `issue-tracker`,
held by the module `mesh-issues` ([53 — The issue tracker](../03-DESIGN/01-to-be/53-the-issue-tracker.md)).
Not hits's *item*; bare *ticket* is a homonym (see [Homonyms](#homonyms)).
*Not:* ~~ticketing system~~ (hq), ~~ticket system~~ (hq)
- **hq check** — one of `00-META/checks/`, run by `merge-check.sh` as this repository's check.
@@ -128,6 +128,17 @@ along the way".
issue: a condition is cleared only by observation
([ADR 0231](0231-a-healer-acts-on-what-observation-raised-and-only-observation-says-it-worked.md)).
> **Progressive insight — 2026-10-10.** Two facts, found as slice 1 was built. **The module's name:** §1 and §7 name
> the module `issues`. The operator named it `mesh-issues` on 2026-10-10, as the mesh's own parts carry the `mesh-`
> prefix (`mesh-delivery`, `mesh-vault`). The seat stays `issue-tracker`, the role, as `operator-channel` is held by
> `messenger`; the thing is still the *issue tracker*, and its verbs are still called `issue-tracker.<verb>`.
> Wherever this record says the module `issues`, read `mesh-issues`; the state named `issues` keeps its name.
> **Compare-and-set:** §3 says the runtime's state verbs "gain" a write refused when the key changed. They had it
> already: `create` and `update` at a revision, with a lost write told by its own error code, came with
> [ADR 0259](0259-an-ask-is-a-message-on-the-bus-any-channel-answers-it-and-the-asker-acts-on-a-warrant.md).
> What slice 1 added is the SDK's `Increment`, which reads a counter and writes the next number only at the revision
> it read. The decision stands as written.
## Consequences
- Collisions end at the source: a number is taken from one counter, not read from a repository many branches write.
+13 -11
View File
@@ -1,7 +1,7 @@
---
layer: to-be
status: designed
code: []
status: in-progress
code: [mesh-catalog, mesh-sdk]
updated: 2026-10-10
decisions:
- 02-DECISIONS/0275-the-mesh-numbers-and-tracks-its-issues-in-a-module-of-its-own-and-hq-keeps-only-the-narrative-of-a-design-or-governance-issue.md
@@ -9,7 +9,8 @@ decisions:
# 53 — The issue tracker
**The mesh keeps its issues in a module of its own, `issues`, one instance on the control-node. It hands out every
**The mesh keeps its issues in a module of its own, `mesh-issues`, one instance on the control-node, holding the seat
`issue-tracker`. It hands out every
issue's number from one counter that two callers can never both advance, holds each issue's status and links, refuses
a change the development cycle would refuse, and announces every change on the bus. hq keeps a folder only for a design
or governance issue, under the tracker's number.**
@@ -17,7 +18,7 @@ or governance issue, under the tracker's number.**
from [research 042](../../01-RESEARCH/042-the-mesh-keeps-its-own-issues/00-overview.md).)
An **issue** is a question about the mesh that someone must answer. The **issue tracker** is the module that holds
issues, named `issues`. The glossary holds both words.
issues, named `mesh-issues`; the seat it holds is `issue-tracker`. The glossary holds both words.
**Acceptance.** An agent opens an issue and gets the next number; two agents opening at the same moment never get the
same one.
@@ -30,7 +31,7 @@ each with what the operator sees when it is done.
```
control-node
issues (seat issue-tracker, held once for the mesh)
mesh-issues (seat issue-tracker, held once for the mesh)
├ its process, launched by the node runtime
├ bucket issues one key per issue, by number; a short history per key
├ bucket counters one key per sequence; slice 1 has `issue` only
@@ -97,15 +98,16 @@ per key, `counters` one value per key, neither expires. The module never creates
the 256 KiB a value may be, a note that would push an issue past it is refused with that reason (the largest issue
folder in hq is 25 KiB).
**The counter is advanced by compare-and-set.** The runtime's state verbs are `get`, `put`, `delete`, `keys` and
`watch`, and none of them refuses a write because the key changed since it was read. Slice 1 adds two, in the runtime
and the SDK's state interface together:
**The counter is advanced by compare-and-set.** Beside `get`, `put`, `delete`, `keys` and `watch`, the runtime's state
verbs hold two writes that are refused when another writer was first, in the runtime and the SDK's state interface
together ([ADR 0259](../../02-DECISIONS/0259-an-ask-is-a-message-on-the-bus-any-channel-answers-it-and-the-asker-acts-on-a-warrant.md)):
- `create` writes a key only if it does not exist;
- `update` writes a key only if its revision is still the one the caller read, and returns the new revision.
Whether the bus's own key-value store already offers these to the runtime is the first thing the build checks; it is
the mechanism the design rests on either way. `open` then runs in this order:
The SDK's `Increment` reads a counter and writes the next number with `create` or `update` at the revision it read,
trying again a bounded number of times when another writer was first. The counter is started once, by `create` at
the number before the first, so it never starts twice. `open` then runs in this order:
1. validate the issue; a refused issue spends no number;
2. read `counters/issue` and its revision;
@@ -160,7 +162,7 @@ in one call, from any session, and the responder on a channel answers from it on
| Slice | Delivers | Done when the operator sees |
|---|---|---|
| 1 | The `issues` module: `open`, `get`, `list`, `move`, `note`, `link`; compare-and-set in the runtime and the SDK; playbook 03 takes its numbers from it | an agent opens an issue and gets the next number; two agents opening at the same moment never get the same one |
| 1 | The `mesh-issues` module: `open`, `get`, `list`, `move`, `note`, `link`; a counter by compare-and-set in the SDK; playbook 03 takes its numbers from it | an agent opens an issue and gets the next number; two agents opening at the same moment never get the same one |
| 2 | Decision and research numbers from the tracker, each its own key in `counters`; a number is reserved when a branch starts | two agents writing a decision at once get two numbers, and no hq pull request is renumbered |
| 3 | `import`: every issue folder in hq read through the records module and written as an issue with its own number, idempotent and showing what it would change before it does; the four consolidation passes of research 042 (fixed, duplicates, owners, grouping), each a list confirmed before it is applied; an audit of `fixed-by` against the forge; then one pull request removes the status keys from every report, changes playbook 03 and `cycle.py`, and adds dated notes to ADR 0019 and 0080 | the not-closed list comes from one call and shrinks by what was already fixed or duplicated, each with its reason |
| 4 | Conditions and pull requests linked: an issue links a condition by its key and the controller shows the link; a merged pull request notes every issue it names; after a week of that, the controller opens one issue per `healer-wanted` condition key by itself | a condition shows its issue, and a merge notes the issues it names |