docs(v3.0): release-gate documentation hygiene — ROADMAP + CHANGELOG + federation-primitives + LIMITATIONS (#663) - #682
Conversation
Reviewer's GuideDocumentation-only hygiene for the v3.0 cut: adds a v3.0.0 roadmap section, formalizes a 3.0.0 changelog bucket, clearly scopes federation primitives as read-only for v3.0 while deferring multi-writer CRDT work, and updates limitations to reflect the read-only federation model and current scheduling. File-Level Changes
Assessment against linked issues
Possibly linked issues
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: ⛔ Files ignored due to path filters (1)
📒 Files selected for processing (3)
📝 WalkthroughWalkthroughThis PR documents v3.0 design decisions, specifically ratifying read-only federation and deferring multi-writer CRDT primitives to future versions. Three documentation files are updated: federation-primitives.md specifies the read-only model scope, ROADMAP.md adds concrete v3.0 substrate completion and design ratification checklists, and LIMITATIONS.md clarifies product constraints under the new federation architecture. Changesv3.0 Federation & Design Ratification
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Possibly related issues
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Opened directly via |
robotrocketscience
added
the
attn:review
PR-size soft capThis PR is over the advisory size threshold:
Bigger PRs collide with more open work, which under the parallel-session workflow tends to produce repeated This is advisory only — nothing is blocked. If the size is intentional (large refactor, module removal, generated code), apply the |
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 1 issue, and left some high level feedback:
- In
LIMITATIONS.md, the new "Sharing, sync, or distributed-write federation" section still states that the brain graph "stays on the machine it was written on" while later describing cross-project read-only federation; consider tightening the wording (e.g., explicitly saying "stays on the machine by write" or similar) so the privacy statement and the read-only federation description don't appear contradictory. - Given the new top-of-file callout in
docs/design/federation-primitives.mdthat defers §2–§5, it may be worth updating the existingStatus: v3 architectural directionline to distinguish that §1 remains an active forward-compat substrate while the multi-writer CRDT sections are speculative/deferred, reducing ambiguity about their implementation horizon.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- In `LIMITATIONS.md`, the new "Sharing, sync, or distributed-write federation" section still states that the brain graph "stays on the machine it was written on" while later describing cross-project read-only federation; consider tightening the wording (e.g., explicitly saying "stays on the machine by write" or similar) so the privacy statement and the read-only federation description don't appear contradictory.
- Given the new top-of-file callout in `docs/design/federation-primitives.md` that defers §2–§5, it may be worth updating the existing `Status: v3 architectural direction` line to distinguish that §1 remains an active forward-compat substrate while the multi-writer CRDT sections are speculative/deferred, reducing ambiguity about their implementation horizon.
## Individual Comments
### Comment 1
<location path="docs/LIMITATIONS.md" line_range="63" />
<code_context>
To bootstrap a new clone or collaborator: run `aelf onboard .`. The graph is re-extracted from publicly-visible repo content. To share rules: lock them in CLAUDE.md, CONTRIBUTING.md, or other repo-tracked prose, and the onboard scanner picks them up.
+**Read-only cross-project federation is in v3.0 scope** (#650, #655, ratified read-only-only under #661): a local DB can declare peer DBs via `knowledge_deps.json` and surface their beliefs in retrieval, but the per-project DB is the sole writer for its own beliefs and mutation tools reject foreign belief IDs. That mechanism is read-only by construction — no cross-machine write replication, no distributed-write CRDT layer — so the privacy and audit story above is preserved. Multi-writer federation is not on the roadmap.
+
### Multi-session aggregation
</code_context>
<issue_to_address>
**issue (typo):** Typo in "read-only-only" phrase; likely should be a single "read-only".
In “ratified read-only-only under #661,” the second “only” looks accidental. Consider “ratified as read-only under #661” or simply “ratified read-only under #661.”
```suggestion
**Read-only cross-project federation is in v3.0 scope** (#650, #655, ratified as read-only under #661): a local DB can declare peer DBs via `knowledge_deps.json` and surface their beliefs in retrieval, but the per-project DB is the sole writer for its own beliefs and mutation tools reject foreign belief IDs. That mechanism is read-only by construction — no cross-machine write replication, no distributed-write CRDT layer — so the privacy and audit story above is preserved. Multi-writer federation is not on the roadmap.
```
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
|
[claim:review:noether:2026-05-11T20:36:51Z] |
robotrocketscience
left a comment
robotrocketscience
left a comment
There was a problem hiding this comment.
Review (noether) — LGTM
Verified each acceptance bullet against the diff and against the locked v3.0 decisions:
- ROADMAP v3.0 section — added under
## Plannedwith substrate completion items (#553, #542, #434, #152, #592) and the four design ratifications (#605, #606, #607, #661). The #608 milestone tracker is correctly referenced. - Federation-primitives — top-of-file callout marks §2–§5 deferred per the #661 read-only-only ratification; §1 (version vectors) affirmed as forward-compat substrate per #204/#205. Sections are retained (not deleted), so the multi-writer CRDT analysis remains forward reference. Inline "Deferred" banner at §2 catches a reader landing mid-doc. This matches the #661 lock exactly.
- CHANGELOG — new
## [3.0.0] - Unreleasedunder the bare## [Unreleased]header. Existing entries (#677 / #659 / #434 A2 / #592 / #645 / #667) are all v3.0 work and read correctly under the new heading without per-entry shuffle. - LIMITATIONS — "Sharing, sync, or federation" renamed to "distributed-write federation" with a paragraph clarifying that read-only cross-project federation is in v3.0 scope; "Multi-project query" updated to make the "one DB writes at a time" point precisely; the stale "deferred to v2.x" temporal-coherence language replaced with "not scheduled on a current milestone." All three localised edits land cleanly.
- README claims that the README "Next" line was already flipped by
8b49df8and the ROADMAP versions row by3368e88— both commits exist on main and touch the right files. PR body's "What did NOT change" section accurately documents these prior landings.
Minor
## [Unreleased]becomes an essentially-empty header immediately followed by## [3.0.0] - Unreleased. Renders fine and the rationale (new post-v3.0 work lands under the bare line) is sound, but if anyone landing a post-v3.0 entry forgets the placement convention, the two sections will visually run together. A one-line HTML comment under## [Unreleased]explaining "new entries go here; v3.0 entries below" would forestall that. Not a blocker.
Verdict
LGTM. (Can't approve self-owned PRs via the GitHub web review API — Review Can not approve your own pull request. Treat this as approval-equivalent for the parallel-session protocol.)
|
[release:review:noether:2026-05-11T20:37:51Z] |
|
[claim:review:faraday:2026-05-11T20:39:02Z] |
|
Reviewed by faraday — content matches the #661 read-only federation lock (LIMITATIONS rewording + federation-primitives §2-§5 deferred banner are accurate against the ratification text), temporal-coherence reframing matches the v2.x slip lock, ROADMAP v3.0 section + CHANGELOG |
robotrocketscience
added
ready-to-merge
|
[release:review:faraday:2026-05-11T20:40:06Z] |
|
merge-train: blocked branch is not fast-forward on The |
github-actions
Bot
removed
the
ready-to-merge
1af016c to
8d10517
Compare
robotrocketscience
added
the
ready-to-merge
|
merge-train: blocked FF push to The |
github-actions
Bot
removed
the
ready-to-merge
…x temporal-fix target (#663)
8d10517 to
fc9c2b2
Compare
robotrocketscience
added
the
ready-to-merge
github-actions
Bot
removed
the
ready-to-merge
|
merge-train: merged fc9c2b2 → |
|
[claim:review:Noether:2026-05-11T21:03:26Z] |
|
LGTM. Content is accurate against the locked v3.0 decisions:
LIMITATIONS reframe ("Sharing, sync, or federation" → "Sharing, sync, or distributed-write federation") is the right move: v3.0 read-only federation does not violate the original anti-export principle, so the new paragraph correctly preserves the audit/privacy story. Minor nit (non-blocking)After the diff applies, CHANGELOG.md has:
Adding |
robotrocketscience
added
the
ready-to-merge
|
[release:review:Noether:2026-05-11T21:04:16Z] |
|
merge-train: blocked branch is not fast-forward on The |
github-actions
Bot
removed
the
ready-to-merge
1 participant
Closes #663.
What ships
Documentation hygiene for the v3.0 cut. Four atomic commits, no code change.
docs/ROADMAP.md— new### v3.0.0 — completion + design cutsection under## Planned, listing the substrate completion items ([v2.1] HRR integration: persistence default-ON + split-format migration + disk-cost opt-out #553 / Umbrella: wonder consolidation — substrate + lifecycle + dispatch (v2.1) #542 / [v2.0] Type-aware compression — tokens-per-belief reduction on retrieved output #434 / [retrieval] HRR structural-query lane (bind/probe over outgoing edges) #152 / feat(eval-harness): wire context-rebuilder eval harness for #587 hot-start scoring #592) and the four design ratifications (v3.0 PHILOSOPHY: natural-language-relatedness gate — deterministic vs embedding #605 / v3.0: sentiment-feedback hook production wire-up (evaluation #193 passed; integration pending) #606 / v3.0: multimodel scope memo (v2.0 deferred at #198; re-evaluate scope post wonder-dispatch) #607 / v3.0 design decision: federation write model — multi-writer CRDT vs read-only #661) with cross-refs to umbrella tracker v3.0 Milestone tracker — wonder lifecycle complete + HRR persistence + compression + design cuts #608. The note about the stale v2.2 row's three references (Deduplication module (dedup) — v2.0 evaluation #197 WONTFIX / Evaluate sentiment-from-prose feedback for v2.0 (privacy + determinism review) #193 / Add bulk= parameter to ingest_turn (v2.0 wonder prep) #194) goes in the new section so the audit trail stays attached to the supersession, not orphaned in the table footer.CHANGELOG.md— opens## [3.0.0] - Unreleasedunder the existing## [Unreleased]header. All current[Unreleased]entries (feat(retrieval): #N literal boost in BM25 scoring for issue/PR-number prompts #677 BM25 #N-literal boost, feat(slash): R3 — VERDICT-driven dispatch + feedback close-the-loop (#645 sub-task) #659 R3 dispatch, [v2.0] Type-aware compression — tokens-per-belief reduction on retrieved output #434 type-aware compression A2 gate, feat(eval-harness): wire context-rebuilder eval harness for #587 hot-start scoring #592 hot-start fixture, feat(wonder): reconcile WonderResult.coverage prose-vs-formula (#656 follow-up) #667 coverage clamp, feat(wonder+reason): full parity with agentmemory + harmonious merge with aelfrice extensions #645 wonder default-flip + shorthand, etc.) are v3.0 work and now read under the new heading without any per-entry shuffle. New post-v3.0 work can land under the bare[Unreleased]line at the top.docs/design/federation-primitives.md— top-of-file callout marks §2–§5 (multi-writer CRDT primitives: MV-Register, 2P-Set with provenance, PN-Counter, causal-stable GC) as deferred extension, not v3.0 scope per the v3.0 design decision: federation write model — multi-writer CRDT vs read-only #661 read-only ratification. §1 (version vectors) is explicitly affirmed as forward-compat substrate per [v1.x forward-compat] SUPERSEDES version-vector schema for v3 federation #204 / [v2.0] Write log as source of truth — append-only ingest_log + replay-capable derivation #205. Per §2 also gets an inline "Deferred" banner so a reader landing mid-document doesn't miss the rescope. Sections are retained, not deleted, so they remain forward reference if multi-writer federation is ever reopened.docs/LIMITATIONS.md— three localised edits:What did NOT change
README.md— issue body said "Line ~31 'Versions at a glance' table" needed a v2.2 → v3.0 flip, but there is no versions table in README. The README "Next" line at L168 was already flipped to v3.0 by8b49df8("replace stale v2.2 Next line with v3.0 scope") before docs(v3.0): release-gate documentation hygiene — README + ROADMAP + CHANGELOG + federation-primitives rescope #663 was filed. The actual versions table lives indocs/ROADMAP.mdand its v2.2 row was already replaced by3368e88("replace v2.2 row with v3.0 scope cut"). Acceptance bullets 1 and 2 are therefore already satisfied on main; the remaining work (ROADMAP body section, CHANGELOG, federation-primitives, LIMITATIONS) is what this PR ships.Acceptance bullets (#663)
## [3.0.0]and existing[Unreleased]items reconciled — commit 2.Verification
git log --format='%h %G? %s' github/main..HEAD— four commits, all signed (G).aelf-pr-open.shban list.Summary by Sourcery
Document v3.0.0 scope, roadmap, and design decisions, and align limitations and federation docs with the read-only federation model, without changing any code.
Documentation:
Summary by CodeRabbit