docs(rfc): add RFC-001 (MACP/Matrix-native comms) + RFC-002 (install/config/topology) #886
Assignees
jason.woltje
Clear assignees
jason.woltje
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: mosaicstack/stack#886
Reference in New Issue
Block a user
Delete Branch "docs/rfc-matrix-macp-topology"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
This PR lands two design RFCs as canonical, git-immutable docs for the Mosaic Stack comms-evolution program: a Mosaic-native Matrix comms layer design foundation, authored by MS-LEAD under Jason's direct authorization (sponsor/veto: Jason). RFC-001 (
docs/rfcs/RFC-001-MACP-MATRIX-NATIVE.md) is the architecture — a self-hosted Synapse homeserver plus a Mosaic-controlled appservice, the MACP v1 protocol, presence/liveness and escalation, per-site federation, and signed-authorship for gate actions. RFC-002 (docs/rfcs/RFC-002-INSTALL-CONFIG-TOPOLOGY.md) is the companion open-source install/config/topology substrate — the three supported topology modes, single ACME cert-provisioning integration, pluggable secret backend (Vault/Vaultwarden), and config precedence/mutability model that RFC-001's phases install onto. These are design docs only — no code ships from this PR. They explicitly supersede Hermes-as-backbone per the strangler migration plan described in RFC-001 §9 (stand the native layer up alongside Hermes, move channels as proven, retire Hermes at parity). Both RFCs are ratifiable design artifacts, not implementation commitments: they carry[VERIFY]flags on every unconfirmed technical claim and explicit disclaimers that illustrative operator values (e.g.mosaic.woltje.com) are never product defaults, and Jason retains sponsor/veto authority over ratification and the open questions listed in each RFC's closing section. Part of the comms-evolution program.Part of #887 (comms-evolution epic).
RECORD OF REVIEW — PR #886 @5555cc75 — VERDICT: APPROVE
Reviewed head:
5555cc759552689b0d6d5b6ba70022171c2833f2(branchdocs/rfc-matrix-macp-topology), basemain@529c1778303c8b82b5d593ceba0690c798729e0c. No drift — PR head matched the pinned commit exactly at review time. Independent reviewer (git identityms-lead-reviewer), fresh clone ofgit.mosaicstack.dev/mosaicstack/stack, not the PR author.1. Docs-only diff — PASS
git diff --name-only origin/main...5555cc75returns exactly:Zero source/code files. 1076 insertions, 0 deletions across 3 files.
2. Content fidelity — PASS
Diffed both RFCs against the authoring sources (
/home/hermes/agent-work/matrix-impl/RFC-00{1,2}-*.md). The prettier follow-up commit (5555cc7on top of01dd2fa) changes only: emphasis-marker style (*text*→_text_), Markdown table column padding/alignment, and JSONC code-block re-indentation/trailing-comma insertion. All 6 JSONC example blocks (2 in RFC-001, 4 in RFC-002) were parsed and semantically diffed (comments/trailing-commas stripped) against the source — identical structures and values in every block. No prose content was added, removed, or reworded beyond the emphasis-marker substitution.[VERIFY]flag counts preserved: RFC-001 = 13, RFC-002 = 23 (one RFC-002 line — the Vaultwarden "HONEST MATURITY FLAG" — carries two[VERIFY]mentions, so raw occurrence count is 24; distinct flagged lines = 23). Identical in source and PR.woltje.com/uscllc.comdo not appear in RFC-001 at all — it's protocol-only, no domain examples). This is consistent between source and PR (neither has it), so it is not a fidelity defect — flagging it because the review brief's premise that the disclaimer appears "in both" doesn't hold for RFC-001, but that's a property of the authored content, not something the PR altered.server_nameinstall-time-immutable, re-home cost documented (§5.3); Vaultwarden as open-source-ethos default candidate with the "HONEST MATURITY FLAG" caveat on machine-account/Secrets-Manager parity (§4, §6.2 discussion).3. SITEMAP entry — PASS
docs/SITEMAP.mdgains one new section ("Comms evolution — Matrix-native MACP (design, draft)") with two bullet links to the RFCs, following the file's existing heading+bullet-list pattern. No unrelated edits — diff is a pure 5-line append.4. No secrets / firewall — PASS
Scanned both new RFC files for credential patterns (API keys, private-key headers, token/password literals) — none found. All secret-shaped fields (
hs_token,as_token,auth_ref,hmac_key_ref) are placeholders (null,"…") or prose discussion, never live values. Illustrative domains (woltje.com,uscllc.com) are Jason's own operator examples, explicitly disclaimed as non-default in RFC-002 — expected and fine for this repo.5. Linkage + state — PASS
PR open,
mergeable: true,draft: false, basemain,merge_base== base sha (no rebase needed). Body contains "Part of #887 (comms-evolution epic)"; issue #887 is open. CI at the exact head is terminal-green:ci/woodpecker/pr/ci=success("Pipeline was successful", pipeline #1999/1).6. Author ≠ reviewer — PASS
Both commits (
01dd2fa,5555cc7) authored bymosaic-coder <coder@fleet.mosaicstack.dev>. Reviewer git identity isms-lead-reviewer, distinct. (PR was opened under the sharedjason.woltjefleet Gitea login per usual convention; merge-gating separation is via coordinator approval, not the PR-opener account.)Verdict: APPROVE. All six criteria pass. This is a clean docs-only landing of two design RFCs; the one prettier-formatting commit is cosmetic-only as claimed, technical content and VERIFY-flag counts are preserved, and CI/linkage/authorship all check out.
GO — Gate-16 id-11 stamp, pinned to exact head
5555cc7595.Basis: verbatim RoR (comment 18671) — independent reviewer APPROVE at this exact head (MS-LEAD relay, strict non-executor); CI success. Named executor: Mos (id-11), squash with pinned head. Part of #887.
Docs-only.