docs(rfc): add RFC-001 (MACP/Matrix-native comms) + RFC-002 (install/config/topology) #886

2026-07-25T00:38:25Z

jason.woltje commented

2026-07-25 00:38:25 +00:00

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).

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).

jason.woltje added 1 commit 2026-07-25 00:38:26 +00:00

docs(rfc): add RFC-001 (MACP/Matrix-native comms) + RFC-002 (install/config/topology)

ci/woodpecker/pr/ci Pipeline was canceled

Details

01dd2fadb3

Adds two design RFCs under docs/rfcs/ authored by MS-LEAD for the
Mosaic Stack comms-evolution program (sponsor/veto: Jason). RFC-001
is the MACP architecture (self-hosted Synapse + Mosaic appservice,
protocol, presence/escalation, federation, strangler migration off
Hermes). RFC-002 is the open-source install/config/topology substrate
RFC-001's phases run on. Docs only, no code. Links added to
docs/SITEMAP.md.

jason.woltje added 1 commit 2026-07-25 00:40:00 +00:00

style(rfc): apply repo prettier formatting to the two RFCs

ci/woodpecker/pr/ci Pipeline was successful

Details

5555cc7595

Whitespace/table-padding/emphasis-marker-style only (prettier --write),
to satisfy pnpm format:check (globs **/*.md). No wording, numbers,
[VERIFY] flags, or disclaimers changed — verified against the source
files line-for-line modulo formatting.

jason.woltje referenced this pull request

2026-07-25 00:43:46 +00:00

[EPIC] Comms-evolution: Mosaic-native Matrix layer + MACP standard (RFC-001 + RFC-002) #887

jason.woltje commented

2026-07-25 01:02:38 +00:00

RECORD OF REVIEW — PR #886 @5555cc75 — VERDICT: APPROVE

Reviewed head: 5555cc759552689b0d6d5b6ba70022171c2833f2 (branch docs/rfc-matrix-macp-topology), base main @ 529c1778303c8b82b5d593ceba0690c798729e0c. No drift — PR head matched the pinned commit exactly at review time. Independent reviewer (git identity ms-lead-reviewer), fresh clone of git.mosaicstack.dev/mosaicstack/stack, not the PR author.

1. Docs-only diff — PASS

git diff --name-only origin/main...5555cc75 returns exactly:

docs/SITEMAP.md
docs/rfcs/RFC-001-MACP-MATRIX-NATIVE.md
docs/rfcs/RFC-002-INSTALL-CONFIG-TOPOLOGY.md

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 (5555cc7 on top of 01dd2fa) 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.
Illustrative-values disclaimer: present verbatim (mod. emphasis-marker) in RFC-002 in two places — the framing note (§1, "illustrative operator values... never defaults and never literals in the product") and the closing note (§12, "every illustrative domain... is an operator-supplied example, never a product default or literal"). Note: RFC-001 does not contain this disclaimer or use any illustrative domain (woltje.com/uscllc.com do 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.
Spot-checked technical claims, all intact: federation hard-gated on DNS+cert, IP-only = standalone-forever (RFC-002 §2.4); single ACME integration with pluggable CA (step-ca/LE) (§3); server_name install-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.md gains 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, base main, 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 by mosaic-coder <[email protected]>. Reviewer git identity is ms-lead-reviewer, distinct. (PR was opened under the shared jason.woltje fleet 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.

RECORD OF REVIEW — PR #886 @5555cc75 — VERDICT: APPROVE **Reviewed head:** `5555cc759552689b0d6d5b6ba70022171c2833f2` (branch `docs/rfc-matrix-macp-topology`), base `main` @ `529c1778303c8b82b5d593ceba0690c798729e0c`. No drift — PR head matched the pinned commit exactly at review time. Independent reviewer (git identity `ms-lead-reviewer`), fresh clone of `git.mosaicstack.dev/mosaicstack/stack`, not the PR author. --- ### 1. Docs-only diff — PASS `git diff --name-only origin/main...5555cc75` returns exactly: ``` docs/SITEMAP.md docs/rfcs/RFC-001-MACP-MATRIX-NATIVE.md docs/rfcs/RFC-002-INSTALL-CONFIG-TOPOLOGY.md ``` 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 (`5555cc7` on top of `01dd2fa`) 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. - **Illustrative-values disclaimer:** present verbatim (mod. emphasis-marker) in RFC-002 in two places — the framing note (§1, "illustrative operator values... never defaults and never literals in the product") and the closing note (§12, "every illustrative domain... is an operator-supplied example, never a product default or literal"). **Note:** RFC-001 does not contain this disclaimer or use any illustrative domain (`woltje.com`/`uscllc.com` do 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. - **Spot-checked technical claims, all intact:** federation hard-gated on DNS+cert, IP-only = standalone-forever (RFC-002 §2.4); single ACME integration with pluggable CA (step-ca/LE) (§3); `server_name` install-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.md` gains 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`, base `main`, `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 by `mosaic-coder <[email protected]>`. Reviewer git identity is `ms-lead-reviewer`, distinct. (PR was opened under the shared `jason.woltje` fleet 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.

Ghost approved these changes 2026-07-25 21:02:53 +00:00

Ghost left a comment

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.

GO — Gate-16 id-11 stamp, pinned to exact head 5555cc759552. 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.

Ghost merged commit fabde1c834 into main

2026-07-25 21:02:55 +00:00

Ghost deleted branch docs/rfc-matrix-macp-topology

2026-07-25 21:02:56 +00:00

Ghost referenced this issue from a commit

2026-07-25 21:02:57 +00:00

docs(rfc): add RFC-001 (MACP/Matrix-native comms) + RFC-002 (install/config/topology) (#886)

jason.woltje referenced this pull request

2026-07-25 21:12:02 +00:00

[EPIC] Comms-evolution: Mosaic-native Matrix layer + MACP standard (RFC-001 + RFC-002) #887

Sign in to join this conversation.