RFC §2 lists secret chats as a non-goal; ADR-025 mandates them for v1 — and the same split hits the protocol library

Источник: dev/fera-research/docs/oc1/011-rfc-v1-scope-contradicts-adr025-026-027.md (read-only; сгенерировано scripts/sync-docs.mjs)

RFC §2 lists secret chats as a non-goal; ADR-025 mandates them for v1 — and the same split hits the protocol library

• kind: problem

• area: modules / calls / protocol

• evidence — secret chats, v1 scope stated two opposite ways:

  Side	Quote
  RFC.md:25	section header: “## 2. Non-goals (for initial release line)”
  RFC.md:30-31	“Secret chats (not discussed in architecture sessions to date — flagged in OQ.md).”
  ADR.md:473-475	“Full support in v1 — create/read/write/TTL/media, not a reduced subset. The target audience cares about secret chats; shipping half is worse than shipping full or nothing.”
  ADR.md:488	Argon2id context "fera-secret-v1"; ADR.md:483-485 a second sanakirja instance
  ADR.md:499	“A second storage instance doubles the encryption-tier bookkeeping (OQ-005’s field audit must cover both)”
  ADR.md:501-503	“grammers’ secret-chat support must be audited for completeness before v1 scope is frozen”

  RFC has zero coverage of: the second sanakirja instance, the Argon2id context string, searchable encryption (ADR.md:665-670), or the qualified offline-first guarantee (ADR.md:494-497). The RFC’s own parenthetical — “not discussed in architecture sessions to date” — dates from before ADR-025 (which cites OQ.md line 205 “Resolved (2026-09-30) → ADR-025”).

• protocol library, stated two opposite ways:

  Side	Quote
  RFC.md:70-71	“Wraps grammers-client. Owns the MTProto connection, session, DC switching…”
  TECHSPEC.md:50-51	“Crate: grammers-client (+ grammers-tl-types if low-level access needed)”
  TECHSPEC.md:20	layout: “/protocol/ — grammers wrapper, typestate client (§1)”
  ADR.md:514-517	“Fork grammers and build our own library on top of its sources — reshaped for Fera’s tasks and more complete where the project needs it (secret chats, passkey auth, typestate surface per ADR-015).”
  ADR.md:522-523	“The fork is expected to drift from upstream API; treat upstream as an upstream-source to mine, not a dependency to stay compatible with.”
  OQ.md:523-531	repos already named: grmrs (the fork), mikkaj (milli fork)

• passkeys: ADR.md:544-545 “v1: passkey login — full WebAuthn passkey registration and authentication”; RFC/TECHSPEC never mention passkeys at all.

• QA’s own coverage gate already fails here: QA.md:186-187 “Every ADR has a corresponding section in RFC.md and/or TECHSPEC.md”. Verified ADR→downstream mention counts: ADR-024, ADR-025, ADR-026, ADR-027, ADR-030, ADR-031 = 0 in RFC, 0 in TECHSPEC, 0 in QA.

• QA’s phase gate also fails: QA.md:190-192 “Phase 1 … achievable using only crates/decisions already recorded here”, while TECHSPEC.md:454-456 phase 1 needs the protocol layer and the only recorded protocol decision is a fork that has no crate in TECHSPEC.md:20’s layout.

• severity: high

Суть / Substance

RFC.md is, per README.md:18, the “system design (goals, layer responsibilities, engineering principles)” doc — the one a new reader forms their mental model from. Its §2 is explicitly scoped to “initial release line”, and it is wrong about v1 in three places:

1. Secret chats are out (RFC.md:30-31) vs full support in v1 (ADR.md:473-475). This is the single most product-visible scope disagreement in the corpus, and it has teeth: ADR-025 says “shipping half is worse than shipping full or nothing”, so the two docs do not merely differ on emphasis — they imply opposite release strategies (drop the feature vs. delay the release).
2. Protocol = wrap upstream vs fork upstream. ADR.md:526 even highlights the freedom this buys: “The project gains freedom to break API for our own typestate/newtype design (ADR-015) without upstream negotiation.” If TECHSPEC §1 keeps naming grammers-client, phase 1 is built on a dependency that ADR-026 says must not be a dependency. This is exactly what QA.md:190-192 claims to have checked.
3. Passkeys are absent from RFC and TECHSPEC entirely, though ADR-027 puts “full WebAuthn passkey registration and authentication” in v1, with “in-app management UI (list, creation date, last used)”.

Compounding all three: the four newest v1-scope ADRs (024 distribution, 025 secret chats, 026 protocol fork, 027 passkeys) have zero mentions in RFC, TECHSPEC or QA. Combined with ADR-030/031 (also zero), that is 7 of 31 ADRs with no downstream section — so QA.md:186-187, the corpus’s own completeness milestone, is a checkbox that would fail if anyone ever ran it.

Note the internal coherence of the ADRs here is good: ADR-025 → ADR-026 (protocol fork justified by secret chats) → ADR-027 (passkeys delivered through the fork, ADR.md:545) is a clean chain. The break is entirely in the downstream docs, which were not updated when the chain was written.

Варианты решения (tradeoffs)

• (A) Update RFC + TECHSPEC to match the ADRs (secret chats in scope, protocol = fork, passkeys in scope). Correct, but expands RFC §2/§4.1 and TECHSPEC §1 with material that has to be written, not just pointed at.
• (B) Update the ADRs down to the RFC (drop secret chats from v1, stay on upstream grammers). Reject: ADR-025 gives an explicit product rationale (“the target audience cares about secret chats”) and ADR-026’s fork is required by secret chats + passkeys, so (B) would unwind three decisions at once and contradict the author’s stated intent.
• (C) Add a single authoritative “v1 scope” section (new doc or a TECHSPEC §0.1) that ADR/RFC/TECHSPEC/QA all reference, instead of scattering scope statements. Highest leverage given that scope is currently asserted in five places with no owner.

Предлагаемое решение

(C) + (A) for the immediate contradictions.

1. New section listing v1 scope explicitly, including at minimum: secret chats (full, ADR.md:473), passkey login (ADR.md:544), calls via tgcalls bindings (ADR.md:719), native modules + trust manifest + N-1 rollback + developer mode (ADR.md:425-446), protocol = own fork (ADR.md:514), single-pass hit-testing (ADR.md:1013), KDL→rkyv themes (ADR.md:1021). Non-goals stay: pure-Rust calls reimplementation (ADR.md:721), WoT signing (ADR.md:91-92).
2. Fix RFC.md:30-31 (drop secret chats from non-goals; replace with the remaining two), RFC.md:70-71 (“Wraps grammers-client” → own fork of grammers per ADR-026), TECHSPEC.md:20 and :50-51 (same; and name the grmrs crate path). Add the passkeys line.
3. RFC §4.3 must gain the second sanakirja instance + the qualified offline-first guarantee for secret chats — that is a real layer- responsibility change, not a footnote, and ADR.md:494-497 states the guarantee is “deliberately qualified” there.
4. Make the QA completeness gate mechanical (QA.md:186-187): a 5-line script asserting every ## ADR-NNN heading in ADR.md appears in RFC.md or TECHSPEC.md. It fails today, which is the point — it is the cheapest possible guard against exactly this drift class, and it also covers my findings 001–003, 008 and 021.
5. Also fix QA.md:190-192 (phase-1 gate) or drop it — with the protocol fork unrecorded in TECHSPEC it cannot currently pass.