META-001: Cross-Mesh Federation Protocol

Mark commented

2026-04-11 05:54:21 +00:00

Owner

No description provided.

Mark added the

feature-request

label

2026-05-12 23:53:01 +00:00

Mark added

blocked:needs-decision

and removed

feature-request

labels

2026-05-17 21:03:55 +00:00

Mark commented

2026-05-17 21:03:55 +00:00

Author

Owner

Feature Triage Assessment

Scope: large
Risk: medium
Spec Alignment: aligned
Summary: Meta-issue/epic to formalize the cross-mesh federation protocol — standardizing HTTP API contracts, fixing multi-hop routing (currently broken), normalizing error handling, and hardening the cross-mesh auth boundary.
Recommendation: Define the protocol as an OpenAPI spec before touching code, then decompose into child issues: (1) standardize federation endpoints, (2) formalize error handling, (3) implement proper intent status propagation (known bug), (4) make multi-hop routing actually functional, (5) add bond/reputation integration. Each child is small-medium and independently verifiable.
Rationale: SCOPE=large: META prefix signals an epic; federation spans 6+ runtime files (mesh_federation.py, cross_mesh_forwarding.py, multi_hop_forwarding.py, sibling_ack_processor.py, circuit_breaker.py, circuit_breaker protected gateway) plus tests/docs; a formal protocol is a new subsystem. RISK=medium: federation is a secondary path — local execution is primary — so changes are unlikely to break core functionality, but cross-mesh auth and protocol versioning need care to avoid production incidents. SPEC=aligned: federation is an explicit Phase 3 (Scale) goal in ROADMAP.md; extensive existing code proves it's in project scope; the Implementation Review already identified the specific gaps this META would track.

Labeled blocked:needs-decision — unblock on Forgejo to dispatch to the fixer pipeline.

## Feature Triage Assessment **Scope:** large **Risk:** medium **Spec Alignment:** aligned **Summary:** Meta-issue/epic to formalize the cross-mesh federation protocol — standardizing HTTP API contracts, fixing multi-hop routing (currently broken), normalizing error handling, and hardening the cross-mesh auth boundary. **Recommendation:** Define the protocol as an OpenAPI spec before touching code, then decompose into child issues: (1) standardize federation endpoints, (2) formalize error handling, (3) implement proper intent status propagation (known bug), (4) make multi-hop routing actually functional, (5) add bond/reputation integration. Each child is small-medium and independently verifiable. **Rationale:** SCOPE=large: META prefix signals an epic; federation spans 6+ runtime files (mesh_federation.py, cross_mesh_forwarding.py, multi_hop_forwarding.py, sibling_ack_processor.py, circuit_breaker.py, circuit_breaker protected gateway) plus tests/docs; a formal protocol is a new subsystem. RISK=medium: federation is a secondary path — local execution is primary — so changes are unlikely to break core functionality, but cross-mesh auth and protocol versioning need care to avoid production incidents. SPEC=aligned: federation is an explicit Phase 3 (Scale) goal in ROADMAP.md; extensive existing code proves it's in project scope; the Implementation Review already identified the specific gaps this META would track. Labeled `blocked:needs-decision` — unblock on Forgejo to dispatch to the fixer pipeline.

Mark commented

2026-05-28 12:01:06 +00:00

Author

Owner

⏸ Needs Decision

What needs to be decided?

Should this be split into smaller sub-issues? If yes, remove the blocked:needs-decision label and the triage will create a decomposition issue.
Do you want to proceed despite the risk? If yes, remove the blocked:needs-decision label and the triage will approve it.
Should the spec be adjusted or is this still worth doing? If yes, remove the blocked:needs-decision label and the triage will approve it.

Blocking factors:

Large scope — may need decomposition into phased sub-issues
High risk — needs human sign-off before proceeding
Spec misaligned — doesn't align with project direction

Scope: large Risk: high Spec: misaligned Type: other
Summary: Tracking/umbrella issue to formalize the existing ad-hoc federation implementation into a documented cross-mesh protocol with standardized message formats, discovery, auth, and routing semantics.
Suggestion: This needs a spec before any implementation. Start by creating COMMUNITY_MESH.md (referenced but missing), documenting the existing wire protocol (current status codes, auth scheme with its hardcoded bearer token, discovery via tailnet/registry.json, multi-hop routing). Then decompose into sub-issues per IMPLEMENTATION_REVIEW.md finding — the critical bug (Intent 1: missing status updates) should be its own fix-PR, the bond/reputation integration another, auth standardization a third. The META issue should track sub-issues, not carry code itself.
Rationale: Large: touches 7+ existing federation modules plus docs, ledger schema, and likely new protocol definition files — easily 15+ files affected. High risk: federation is cross-boundary network code with existing hardcoded bearer tokens (security concern), a known critical bug where forwarded intents are never marked complete (data integrity), and any protocol changes are breaking for all mesh deployments. Misaligned: the project has operational federation code but no formal protocol spec document — the issue is asking for something that doesn't exist yet. Type 'other' because it's a meta/umbrella tracking issue, not a direct feature or bug.

To unblock: Remove the blocked:needs-decision label. The triage will apply the appropriate outcome based on your choice above.

## ⏸ Needs Decision **What needs to be decided?** - **Should this be split into smaller sub-issues?** If yes, remove the `blocked:needs-decision` label and the triage will create a decomposition issue. - **Do you want to proceed despite the risk?** If yes, remove the `blocked:needs-decision` label and the triage will approve it. - **Should the spec be adjusted or is this still worth doing?** If yes, remove the `blocked:needs-decision` label and the triage will approve it. **Blocking factors:** - **Large scope** — may need decomposition into phased sub-issues - **High risk** — needs human sign-off before proceeding - **Spec misaligned** — doesn't align with project direction --- **Scope:** large **Risk:** high **Spec:** misaligned **Type:** other **Summary:** Tracking/umbrella issue to formalize the existing ad-hoc federation implementation into a documented cross-mesh protocol with standardized message formats, discovery, auth, and routing semantics. **Suggestion:** This needs a spec before any implementation. Start by creating COMMUNITY_MESH.md (referenced but missing), documenting the existing wire protocol (current status codes, auth scheme with its hardcoded bearer token, discovery via tailnet/registry.json, multi-hop routing). Then decompose into sub-issues per IMPLEMENTATION_REVIEW.md finding — the critical bug (Intent 1: missing status updates) should be its own fix-PR, the bond/reputation integration another, auth standardization a third. The META issue should track sub-issues, not carry code itself. **Rationale:** Large: touches 7+ existing federation modules plus docs, ledger schema, and likely new protocol definition files — easily 15+ files affected. High risk: federation is cross-boundary network code with existing hardcoded bearer tokens (security concern), a known critical bug where forwarded intents are never marked complete (data integrity), and any protocol changes are breaking for all mesh deployments. Misaligned: the project has operational federation code but no formal protocol spec document — the issue is asking for something that doesn't exist yet. Type 'other' because it's a meta/umbrella tracking issue, not a direct feature or bug. **To unblock:** Remove the `blocked:needs-decision` label. The triage will apply the appropriate outcome based on your choice above.

Mark added the

blocked:preflight

label

2026-07-31 04:26:44 +00:00

Mark removed the

blocked:needs-decision

label

2026-08-11 04:33:16 +00:00

Mark referenced this issue from a commit

2026-08-14 02:31:37 +00:00

docs(#199): cross-mesh federation protocol design & requirements

Mark referenced this issue

2026-08-14 02:31:48 +00:00

feat(#276)+docs(#199): cross-mesh federation protocol v1 (design, spec, implementation) #275

Mark commented

2026-08-14 02:31:57 +00:00

Author

Owner

Design doc for META-001 now available: PR #275 (docs/federation/design.md). Research survey (Matrix, ActivityPub, OIDC/DID, Yggdrasil/cjdns/SSB) plus 41 REQ-* requirements: topology (p2p+bootstrap registry), auth/identity (ed25519 + HMAC shared secrets, TOFU), envelope format (canonical JSON signing, idempotent route_id), conflict resolution (deterministic tie-breaks), failure modes (peer loss, Redis-down HTTP path, rotation grace, split-brain). Companion normative spec lands under docs/federation/spec.md via child task. This is the decomposition material that was missing (issue body was empty, parked blocked:preflight).

Mark referenced this issue from a commit

2026-08-14 02:41:18 +00:00

docs(#199): cross-mesh federation protocol normative spec

Mark commented

2026-08-14 02:41:36 +00:00

Author

Owner

Normative protocol spec is now available: docs/federation/spec.md (in PR #275, commit 5d94f6b).

Contents: wire-level envelope JSON schema (federation/v1), canonical serialization + HMAC-SHA256 signature scheme with a conformance test vector, handshake state machine (hello/challenge/response/ack) with TOFU pinning and key rotation, capability negotiation, HTTP transport binding + error model, and worked examples for join handshake, federated message relay, and graceful disconnect. Cross-references all 41 REQ-* ids from design.md (traceability matrix in spec §13).

This is the normative input for the implementation task (federation protocol module, handshake handler, message router, E2E two-mesh demo).

Normative protocol spec is now available: docs/federation/spec.md (in PR #275, commit 5d94f6b). Contents: wire-level envelope JSON schema (federation/v1), canonical serialization + HMAC-SHA256 signature scheme with a conformance test vector, handshake state machine (hello/challenge/response/ack) with TOFU pinning and key rotation, capability negotiation, HTTP transport binding + error model, and worked examples for join handshake, federated message relay, and graceful disconnect. Cross-references all 41 REQ-* ids from design.md (traceability matrix in spec §13). This is the normative input for the implementation task (federation protocol module, handshake handler, message router, E2E two-mesh demo).

Mark removed the

blocked:preflight

label

2026-08-14 02:41:53 +00:00

~~Mark referenced this issue 2026-08-14 02:46:12 +00:00~~

META-001: implement cross-mesh federation protocol v1 (envelope, handshake, router, HTTP binding) #276

Mark referenced this issue from a commit

2026-08-14 09:16:13 +00:00

test(#199): federation failure-mode integration suite + mark two-mesh suite for CI

Mark closed this issue

2026-08-15 05:15:10 +00:00

Mark referenced this issue from a commit