[codex] docs: align Raft R3a with command WAL

[snissn]

Summary

• add an explicit R3a deterministic apply-harness milestone to the native query/Raft roadmap
• link the user-command WAL spec to the new Raft R3a tracker (TreeDB Raft R3a: deterministic command-entry apply harness over user-command WAL #1654)
• annotate the native-wire/command-WAL alignment manifest with R3a harness eligibility values

Scope

Docs/spec only. No code behavior, storage format, or public API changes.

Validation

• jq empty TreeDB/docs/spec/command-wal-nativewire-alignment.json
• GOWORK=off go test ./TreeDB/docs -count=1
• GOWORK=off make docs-check
• git diff --check

Refs #1654.

Summary by CodeRabbit

• Documentation
  • Updated Raft consensus implementation roadmap and command synchronization specifications with new phases and refined requirements documentation.
  • Enhanced internal tracking specifications for command operation eligibility and state consistency across distributed systems.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: b12d397b-31b0-4da8-a5f6-466884255924

📥 Commits

Reviewing files that changed from the base of the PR and between a174be3 and b10366c.

📒 Files selected for processing (3)

• TreeDB/docs/spec/command-wal-nativewire-alignment.json
• TreeDB/docs/spec/native-query-raft-roadmap.md
• TreeDB/docs/spec/user-command-wal.md

---

📝 Walkthrough

Walkthrough

Three specification documents are updated to establish the Raft R3a deterministic apply harness design: architectural roadmap positioning, normative contract for command eligibility and apply boundaries, and command-WAL alignment categorization mapping each command to its harness status.

Changes

Raft R3a Deterministic Apply Harness Specification

Layer / File(s)	Summary
R3a Roadmap & Architectural Role TreeDB/docs/spec/native-query-raft-roadmap.md	R3a deterministic apply harness is added as a new phase that replicates only deterministic write set (collection creates, insert/replace/delete batches, deterministic guards, idempotency), deferring non-deterministic operations (collection/index drop/create) until those command kinds become WAL-supported with deterministic guard/recovery tests. A TODO item is added to land R3a harness before selecting a Raft library or committing to a log-store boundary.
R3a Harness Normative Contract & Boundaries TreeDB/docs/spec/user-command-wal.md	Normative contract established for R3a harness: decodes deterministic command-entry bytes, enforces rejection of unsupported/local-only commands before local WAL append when presented as replicated entries, applies via normal command-WAL executor, and proves convergence across fresh DBs. Harness explicitly avoids replicating WAL frames, physical barriers, or reconstructing native-wire requests. Manifest records R3a eligibility per native-wire mutation.
Command-WAL Alignment & R3a Categorization TreeDB/docs/spec/command-wal-nativewire-alignment.json	Raft-r3a harness tracking metadata added with three result categories: eligible_v1 (deterministic, WAL-supported), rejected_until_wal_supported_v1, and local_only_not_replicated_v1. Each command in the entries relationship matrix is assigned its corresponding harness classification.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• #1654: This PR directly implements the R3a deterministic apply harness specification design described in that issue, establishing the architectural role, normative contract boundaries, and command categorization framework.

Poem

A harness for determinism, shaped with care,
Raft replicas march where mutations declare—
Deterministic entries flow through the WAL,
Convergence proven across all in thrall. 🐰✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title '[codex] docs: align Raft R3a with command WAL' is concise, specific, and clearly summarizes the main change—aligning R3a deterministic apply-harness documentation with command WAL specifications across three spec files.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/raft-r3a-doc-alignment

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This PR aligns the documentation roadmap/specs for TreeDB’s Raft direction with the newer “user-command WAL” approach by explicitly introducing an R3a milestone for a deterministic apply harness and annotating the existing native-wire ↔ command-WAL alignment manifest with R3a eligibility metadata.

Changes:

• Add explicit “R3a. Deterministic Apply Harness” milestone and acceptance criteria to the native query/Raft roadmap.
• Link the new Raft R3a tracker (#1654) from the user-command WAL spec and add R3a-oriented narrative clarifying the apply-harness scope.
• Extend the native-wire/command-WAL alignment manifest with R3a harness eligibility values and per-command eligibility annotations.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
TreeDB/docs/spec/user-command-wal.md	Adds Raft R3a tracker link and describes how the alignment manifest constrains the R3a apply-harness allowlist/rejections.
TreeDB/docs/spec/native-query-raft-roadmap.md	Introduces the R3a deterministic apply-harness milestone and adjusts R3 replication scope language to match WAL-supported commands.
TreeDB/docs/spec/command-wal-nativewire-alignment.json	Adds R3a tracker + harness eligibility taxonomy and annotates each native-wire mutation with an R3a harness eligibility value.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.