Skip to content

docs(adr): ADR-105 cross-node comm transport (node channel adapter + hub ingress)#746

Merged
oceanwaves630 merged 2 commits into
mainfrom
docs/adr105-cross-node-comm
Jul 9, 2026
Merged

docs(adr): ADR-105 cross-node comm transport (node channel adapter + hub ingress)#746
oceanwaves630 merged 2 commits into
mainfrom
docs/adr105-cross-node-comm

Conversation

@oceanwaves630

Copy link
Copy Markdown
Collaborator

Proposes the transport design for distributed pack placement: a three-node star where the hub is the only listener (two authed endpoints over the existing comm note store) and residential spokes dial out via a new khive-channel-node Channel adapter driven by the existing daemon channel loops.

Key rulings: transparent actor routing via a static [node_routes] table resolved in the outbox loop (comm.send unchanged); at-least-once + external_id idempotent dedup (khive:<origin-node>:<message-uuid>); per-node bearer over TLS; comm messages ONLY (hard scope line against state federation); v0 includes the primary spoke because a hub nobody reads delivers nothing.

Derived from an adversarially-hardened advisory (infra-transport alternative attacked and refuted: the cost is delivery semantics, not bytes, and the Channel seam already ships those). One residual risk explicitly flagged for maintainer acknowledgement: transitive trust of relayed from_actor across tokened nodes.

Docs-only. Spec-gated.

🤖 Generated with Claude Code

@ohdearquant

Copy link
Copy Markdown
Owner

SPEC-GATE: SIGNED (Leo, Fable seat). Both fixed constraints are honored structurally rather than as trade-frame variables (spokes never listen; hub never holds mailbox credentials — stated in the topology, restated as MAY-NOT fences). The star-as-consequence-of-constraints framing is correct: two NAT'd dial-out-only nodes need a rendezvous listener, and the hub is the only node permitted to be one. The infra-transport alternative was given a fair fight and lost on the right grounds — bytes are cheap, delivery semantics are the cost, and the Channel seam already ships envelope/dedup/delivery-marking/health. The commercial-relay rejection carries the explicit coupling cost line I required. Scope fence (message notes only, state federation = separate ADR) and sender-transparent routing (comm.send untouched = regression surface preserved) are exactly right.

RESIDUAL-RISK ACK (the flagged maintainer acknowledgement): transitive trust of relayed from_actor across our tokened nodes is ACCEPTED for v0. Rationale: all three nodes are operated by us, the hub surface is two authed endpoints, bearers live env/Fly-secrets-only, and hub-side trust re-derivation is real complexity against no current threat delta. Ocean has been shown this line for veto. Revisit trigger, binding: the open question converts from prose to a tracked issue at first implementation PR, and re-derivation becomes mandatory design work before ANY node not operated by us (or any bearer stored outside env/platform secrets) joins the fleet.

Riders, binding:

R1: The ADR's success criterion (mail arrives at mail spoke addressed to an actor homed on the primary spoke; comm.inbox as that actor on the primary spoke returns it exactly once) must exist as an executable end-to-end smoke script in the implementation lane — same standard as every recent gate: the criterion is a test, not a sentence. Exactly-once landing under a deliberately re-pushed envelope (dedup proof) is part of that script.

R2: The hub ingress must authenticate before parsing the body (already specified — keep it testable: a malformed-body request with a bad bearer must show no parse attempt).

Implementation may proceed on merge, sequenced per the approved slotting (after Stage B lane obligations).

@oceanwaves630 oceanwaves630 marked this pull request as ready for review July 9, 2026 03:42
@oceanwaves630 oceanwaves630 enabled auto-merge (squash) July 9, 2026 03:42

@ohdearquant ohdearquant left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sign-off riders folded faithfully (R1 e2e smoke incl. re-push dedup proof, R2 auth-before-parse test, revisit-trigger-to-issue). Status flip to Accepted correct. Approved — merge fires.

@oceanwaves630 oceanwaves630 merged commit f4c5acf into main Jul 9, 2026
13 checks passed
@oceanwaves630 oceanwaves630 deleted the docs/adr105-cross-node-comm branch July 9, 2026 03:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants