FABRIC-3.md §H: close gap #6 -- CH is the topic, and H.7/H.8 are real code

Checked capsules/common/messaging.4th directly instead of assuming: the
H.7 messaging protocol isn't design vision, it's already substantially
built -- COMMON-CH, CH-REQUEST, CH-ACCEPT, CH-CONFIRM, CH-CLOSE, and
local ACK/NACK (MSG-ACK-LAST/MSG-NACK-LAST/MSG-NACKED) all exist and work
today. CH already is the topic, 1:1, no new representation needed.
Upgrades H.7/H.8's framing from "protocol groundwork, not yet real" to
"the mechanism exists, the ACL gate on top of it is the remaining work" --
the message card is now a concrete wiring task, not a hypothetical one.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Robert Allan James
2026-09-02 18:55:09 -04:00
co-authored by Claude Opus 5
parent 33286cb3a2
commit b15339ca1f
+35 -20
View File
@@ -3724,28 +3724,40 @@ are ordinary ACL state like `DictEntry`'s.
`BMAPFMT`'s field/API design (TTL + flags bits + FORTH wrappers) is now fully complete but
**the code change was never made** — this refactor is presumably where it finally lands.
### H.7 — Messaging protocol groundwork (prerequisite to the message card)
### H.7 — Messaging protocol: not groundwork, already real code (verified 2026-09-02)
- **PubSub, decided.** Terminology is **"topics"** — not "channels." Likely reconciles with
the existing `CH` field / `CH-ALLOC` API already on record in D.4's message shape
(`MSG-CELLS` = `TYPE, FROM, TO, PADDR, PLEN, STADIUM-CELL, SEQ, CH, ORIG-TYPE`) — `CH` is
likely the topic identifier, terminology now formalized as "topic."
- **Every VM always subscribes to one well-known "common" topic**a standing prerequisite,
not something set up per-conversation. This is the rendezvous point.
- **Handshake flow**: VM A posts a message on `common` addressed to VM B — "I would like to
commune with you." VM B, already listening on `common`, responds okay. That handshake
causes a **new private topic** to be created, which A and B then use directly instead of
`common`.
- **ACK/NACK confirmed as a general reliability mechanism**, applied to every message on any
topic (private or `common`) — not specific to the handshake step.
Originally captured as design vision — **upgraded 2026-09-02** after checking
`capsules/common/messaging.4th` directly instead of assuming. The protocol described below
isn't a future design, it's already substantially built:
- **PubSub, decided.** Terminology is **"topics"** — the existing code's own term is
"channel"/`CH`. **Resolved: `CH` already *is* the topic, 1:1, no new representation
needed** — "topic" is just today's newly-adopted vocabulary for what the code already calls
a channel.
- **Every VM always subscribes to one well-known "common" topic.** Real: `COMMON-CH`, the
actual variable holding the one canonical common channel, owned by Hermes and wired into
`hermes/init.4th` at boot (`CH-ADD-MBR` adds members 0 and 1).
- **Handshake flow, real functions**: `CH-REQUEST ( type from to paddr plen -- )` — checks
`COMMON-CH` is `CH-OPEN`, sends via `MSG-SEND` — is literally "post a message on `common`
requesting a commune." `CH-ACCEPT ( -- ch|0 )` — the receiving side allocates a new private
channel, marks it `CH-NEGOTIATING`. `CH-CONFIRM ( ch -- )` transitions
`CH-NEGOTIATING``CH-OPEN`. `CH-CLOSE ( ch -- )` tears a channel down (`CH-CLOSING`).
- **ACK/NACK, real**: `MSG-ACK-LAST`/`MSG-NACK-LAST`/`MSG-NACKED` (253) — "purely local, no
VM-EXEC indirection" per the code's own comment — a general reliability mechanism applied to
every message on any topic, not specific to the handshake step.
### H.8 — Message card
**Scope confirmed narrow and one-sided**: gates only "who's allowed to post on `common`
requesting a commune" — the *initiating* side of the H.7 handshake. The receiving VM's
decision to accept/ACK is **not** gated by this card. Not yet stated: whether traffic on an
established private topic (post-handshake) is gated by this card, a different mechanism, or
left ungated.
requesting a commune" — the *initiating* side of the H.7 handshake, i.e. who's allowed to
call the real `CH-REQUEST` function above. The receiving VM's decision to accept/ACK (i.e.
`CH-ACCEPT`) is **not** gated by this card. Not yet stated: whether traffic on an established
private topic (post-handshake) is gated by this card, a different mechanism, or left ungated.
**Implementation-gap note (2026-09-02)**: since `CH-REQUEST` is real, already-callable code
with (as far as checked) no ACL gate in front of it today, this card's job is now a concrete,
well-targeted wiring task — add the gate check to the real function — rather than a
hypothetical one waiting on future messaging infrastructure. Not yet built.
### H.9 — Gap analysis (as of 2026-09-02)
@@ -3773,9 +3785,12 @@ Explicitly open items surfaced during this capture pass, none decided yet:
5. **`BMAPFMT` code change (H.6).** Field design was finished in the §F.4 pass but the actual
code edit to `blk_meta_t` was never made — a real, concrete implementation gap, not just an
open question.
6. **Topic/`CH` reconciliation (H.7).** "Topic" is the newly formalized term; whether it maps
1:1 onto the existing `CH` field in `MSG-CELLS` or needs its own representation is inferred
by the model, not explicitly confirmed.
6. **CLOSED 2026-09-02 — topic/`CH` reconciliation (H.7).** `CH` already *is* the topic, 1:1.
Bigger than expected: this check also upgraded all of H.7/H.8 from "protocol vision" to
"already real code" (`COMMON-CH`, `CH-REQUEST`, `CH-ACCEPT`, `CH-CONFIRM`, `CH-CLOSE`,
`MSG-ACK-LAST`/`MSG-NACK-LAST` all exist and work today in `capsules/common/messaging.4th`).
The message card's gate is now a concrete wiring task onto a real function, not a
hypothetical one waiting on future infrastructure.
7. **Private-topic traffic gating (H.8).** Whether messages on an established private topic
(as opposed to the initiating `common` post) are gated by the message card, some other
mechanism, or left ungated entirely.