To-be 8: a port may be reached from the machine's own local network (issue 154, ADR 0340) #339

Merged
mesh-admin merged 2 commits from design/154-local-network into main 2026-10-13 06:22:48 +00:00
Contributor

What. Adds the reach local-network to the reach table in to-be 8 (connectivity) and a dated paragraph saying what it means, and names ADR 0340 in the design's decisions.

Why. Issue 154: a service reached by devices on the machine's own network could only be declared public, which says the internet. ADR 0340 (proposed, needs the operator) adds a fourth source and reach, local-network: the networks the machine is attached to through its uplink, private ranges only, never a public subnet. The record needs a design home; this is it.

How it was tested. 00-META/checks/ records.py, index.py, cycle.py and words.py pass locally.

Issue 154 (design home for ADR 0340; the build follows once the record is accepted).

**What.** Adds the reach `local-network` to the reach table in to-be 8 (connectivity) and a dated paragraph saying what it means, and names ADR 0340 in the design's `decisions`. **Why.** Issue 154: a service reached by devices on the machine's own network could only be declared `public`, which says the internet. ADR 0340 (proposed, needs the operator) adds a fourth source and reach, `local-network`: the networks the machine is attached to through its uplink, private ranges only, never a public subnet. The record needs a design home; this is it. **How it was tested.** `00-META/checks/` records.py, index.py, cycle.py and words.py pass locally. Issue 154 (design home for ADR 0340; the build follows once the record is accepted).
mesh-admin added 1 commit 2026-10-13 06:14:54 +00:00
Say in to-be 8 that a port may be reached from the machine's own local network (issue 154, ADR 0340)
mesh/merge-gate head d50e6df90619 merged into trunk 0e6bc1bc803c — pass: the change touches no module of the mesh's graph
mesh/repo-check head d50e6df90619 merged into trunk 0e6bc1bc803c — pass: its merge-check.sh passed
mesh/delivery superseded: a newer head of the same pull request
d50e6df906
A local service could only be declared public, which says the internet; ADR 0340 adds local-network, private ranges only, and needs a design home.
Author
Contributor

Delivery novox/hq@5d861fefcb54 — delivered since 2026-10-13T06:23:07Z

Delivery plan — builds nothing: the change touches no module of the mesh's graph

Transitions

  • 2026-10-13 06:18 (new) → proposed (announced): novox/hq#339's head announced
  • 2026-10-13 06:19 proposed → checked (checked): a verdict names this commit and the trunk's head as its trunk commit
  • 2026-10-13 06:19 checked → ready (accepted): the gate passed or warned, and the repository's own check did not fail
  • 2026-10-13 06:23 ready → published (merged): on the trunk its modules follow: merged there, and its walk opened — or nothing for a walk to move
  • 2026-10-13 06:23 published → delivered (done): nothing for a walk to move

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

<!-- mesh-delivery:view --> **Delivery** `novox/hq@5d861fefcb54` — **delivered** since 2026-10-13T06:23:07Z **Delivery plan** — builds nothing: the change touches no module of the mesh's graph **Transitions** - 2026-10-13 06:18 (new) → proposed (announced): novox/hq#339's head announced - 2026-10-13 06:19 proposed → checked (checked): a verdict names this commit and the trunk's head as its trunk commit - 2026-10-13 06:19 checked → ready (accepted): the gate passed or warned, and the repository's own check did not fail - 2026-10-13 06:23 ready → published (merged): on the trunk its modules follow: merged there, and its walk opened — or nothing for a walk to move - 2026-10-13 06:23 published → delivered (done): nothing for a walk to move The commit's note under `refs/notes/mesh-plan` keeps every transition: `git log --notes=mesh-plan`.
jschoubben added 1 commit 2026-10-13 06:18:19 +00:00
Name local-network a new source, as ADR 0340 counts it (issue 154)
mesh/merge-gate head 5d861fefcb54 merged into trunk 0e6bc1bc803c — pass: the change touches no module of the mesh's graph
mesh/repo-check head 5d861fefcb54 merged into trunk 0e6bc1bc803c — pass: its merge-check.sh passed
mesh/delivery delivered
5d861fefcb
mesh-admin left a comment
Author
Contributor

Verdict: approve at 5d861fefcb

The design text matches ADR 0340's clauses on both source and reach, and adds nothing the record does not decide. The new table row ("the machine port, to the private network and the machine's local networks | the internal name | the mesh's own authority") tracks clause 4 ("the filter opens the machine port to the private network and to the machine's local networks, the proxy serves the internal name and not the public one, and the certificate comes from the mesh's own authority") word for word in substance. The added paragraph's claims each trace to a clause or section: the source and private-range limit to clauses 1 and 2, the per-port rendering to clause 5, the no-resolved-network behaviour to clause 6 ("renders a local-network port as admitted from no local network, and the rendered rule set and the plan say so"), the plan/node visibility to clause 8, and the opening sentence about a home server to the record's Context ("A home server serves devices on its own network that will never be nodes"). The closing sentence about a travelling laptop matches the Consequences section ("A laptop that travels admits its current local network on a local-network port... the plan shows what a port resolved to"). I found no invented mechanism and no stronger claim than the record makes.

Frontmatter is right: decisions gained "ADR 0340" (and already carried "ADR 0138" and "ADR 0045", the two records it changes), and updated moved from 2026-10-08 to 2026-10-13, matching the record's own date. The design's status: in-progress and non-empty code: are untouched, so this is a documentation home for a still-proposed record, not a claim that it is built.

Public-repo rule: I diffed this branch against main and scanned for addresses, node names, hosts and absolute paths (10./192.168./172.16., ssh://, http(s)://, /home/, /etc/, /var/, the node names, .internal). The only file changed is 03-DESIGN/01-to-be/08-connectivity.md, and the addition names no machine — it speaks of "a home server" and "a laptop that travels" (role names) and cites RFC 1918 and IPv6 unique local addresses as documentation ranges only, never a concrete subnet.

Glossary words: the addition uses existing glossary terms (reach, uplink, filter, proxy, private network, node-engine) correctly and introduces no new term that contradicts a glossary entry; local-network is the record's own name for the fourth reach and is not yet in the glossary, which is expected while ADR 0340 is still proposed.

I cloned the PR branch over HTTPS to /var/tmp/review-hq339 at head 5d861fefcb and ran ./merge-check.sh. It reported: "records: all checks passed", "index: 6 topics in the reading order, no stored list", "cycle: 436 documents checked, the chain holds", and "words: 28 retired words and 2 identifiers, none in running prose; 70 daemons' lines, none written; 155 head words, each once" (the catalogue comparison was skipped locally for want of MESH_CATALOG_DIR, unrelated to this change). git diff origin/main..HEAD --stat confirms the change is exactly the one file, 15 insertions and 1 deletion.

One note, not a blocking finding: ADR 0340 itself is still status: proposed, needs-operator: true, and its operator ask "ended refused (its asker already has 3 open asks)" — it is not yet in force. The PR body says so plainly ("ADR 0340 (proposed, needs the operator)... the build follows once the record is accepted"), and playbook 02 writes the design once the decision is recorded, not once it is accepted, so giving it a design home now is in order. Worth reopening the operator's ask once a slot frees, so the record does not sit proposed indefinitely.

Verdict: approve at 5d861fefcb544057c604f1f75174a53dd48c22eb The design text matches ADR 0340's clauses on both source and reach, and adds nothing the record does not decide. The new table row ("the machine port, to the private network and the machine's local networks | the internal name | the mesh's own authority") tracks clause 4 ("the filter opens the machine port to the private network and to the machine's local networks, the proxy serves the internal name and not the public one, and the certificate comes from the mesh's own authority") word for word in substance. The added paragraph's claims each trace to a clause or section: the source and private-range limit to clauses 1 and 2, the per-port rendering to clause 5, the no-resolved-network behaviour to clause 6 ("renders a `local-network` port as admitted from no local network, and the rendered rule set and the plan say so"), the plan/node visibility to clause 8, and the opening sentence about a home server to the record's Context ("A home server serves devices on its own network that will never be nodes"). The closing sentence about a travelling laptop matches the Consequences section ("A laptop that travels admits its current local network on a `local-network` port... the plan shows what a port resolved to"). I found no invented mechanism and no stronger claim than the record makes. Frontmatter is right: `decisions` gained "ADR 0340" (and already carried "ADR 0138" and "ADR 0045", the two records it changes), and `updated` moved from 2026-10-08 to 2026-10-13, matching the record's own date. The design's `status: in-progress` and non-empty `code:` are untouched, so this is a documentation home for a still-proposed record, not a claim that it is built. Public-repo rule: I diffed this branch against main and scanned for addresses, node names, hosts and absolute paths (10./192.168./172.16., ssh://, http(s)://, /home/, /etc/, /var/, the node names, .internal). The only file changed is 03-DESIGN/01-to-be/08-connectivity.md, and the addition names no machine — it speaks of "a home server" and "a laptop that travels" (role names) and cites RFC 1918 and IPv6 unique local addresses as documentation ranges only, never a concrete subnet. Glossary words: the addition uses existing glossary terms (reach, uplink, filter, proxy, private network, node-engine) correctly and introduces no new term that contradicts a glossary entry; `local-network` is the record's own name for the fourth reach and is not yet in the glossary, which is expected while ADR 0340 is still proposed. I cloned the PR branch over HTTPS to /var/tmp/review-hq339 at head 5d861fefcb544057c604f1f75174a53dd48c22eb and ran ./merge-check.sh. It reported: "records: all checks passed", "index: 6 topics in the reading order, no stored list", "cycle: 436 documents checked, the chain holds", and "words: 28 retired words and 2 identifiers, none in running prose; 70 daemons' lines, none written; 155 head words, each once" (the catalogue comparison was skipped locally for want of MESH_CATALOG_DIR, unrelated to this change). `git diff origin/main..HEAD --stat` confirms the change is exactly the one file, 15 insertions and 1 deletion. One note, not a blocking finding: ADR 0340 itself is still `status: proposed`, `needs-operator: true`, and its operator ask "ended refused (its asker already has 3 open asks)" — it is not yet in force. The PR body says so plainly ("ADR 0340 (proposed, needs the operator)... the build follows once the record is accepted"), and playbook 02 writes the design once the decision is recorded, not once it is accepted, so giving it a design home now is in order. Worth reopening the operator's ask once a slot frees, so the record does not sit proposed indefinitely.
mesh-admin merged commit 8e6ca012c5 into main 2026-10-13 06:22:48 +00:00
mesh-admin deleted branch design/154-local-network 2026-10-13 06:22:48 +00:00
Sign in to join this conversation.
No Reviewers
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: novox/hq#339