docs(philosophy): v3.0 relatedness ratification — stay deterministic (closes #605) - #610
Merged
Merged
Conversation
Reviewer's GuideDocs-only PR that ratifies the v3.0 natural-language-relatedness philosophy (remain fully deterministic, push paraphrase/synonymy to consuming agents), adds a dedicated memo documenting the decision and its exclusions, cross-links it from PHILOSOPHY, and records the decision in the changelog. Sequence diagram for paraphrase-related dedup handled by consuming agentsequenceDiagram
actor User
participant ConsumingAgent
participant AelfriceIngest as Aelfrice_Ingest_layer
participant AelfriceRetrieval as Aelfrice_Retrieval_path
User->>ConsumingAgent: Submit_new_belief(text)
ConsumingAgent->>ConsumingAgent: Detect_paraphrase_and_contradictions_with_existing_beliefs(LLM_or_embeddings)
ConsumingAgent->>AelfriceIngest: Store_belief(structured_record)
AelfriceIngest->>AelfriceIngest: Apply_R1_dedup(hash_collision_only)
AelfriceIngest->>AelfriceIngest: Apply_typed_slot_value_comparator(numeric_enum)
AelfriceIngest-->>ConsumingAgent: Ingest_result(deterministic)
User->>ConsumingAgent: Ask_question(query_text)
ConsumingAgent->>AelfriceRetrieval: Retrieve(query_text_or_terms)
AelfriceRetrieval-->>ConsumingAgent: Deterministic_results(BM25F_posterior_HRR)
ConsumingAgent->>ConsumingAgent: Apply_synonym_bridging_and_paraphrase_rerank(LLM_or_embeddings)
ConsumingAgent-->>User: Answer_with_coherent_context
Flow diagram for gating embedding-based relatedness changes by PHILOSOPHY determinismflowchart TD
A["Propose_new_relatedness_feature"] --> B["Does_feature_require_embeddings_or_LLM_similarity_in_retrieval_or_ingest_path?"]
B -->|No| C["Feature_may_ship_if_deterministic_constraints_are_met"]
B -->|Yes| D["Is_PHILOSOPHY_Determinism_section_amended_to_allow_nondeterministic_lane?"]
D -->|No| E["Mark_ticket_WONTFIX_per_v3_relatedness_philosophy"]
E --> F["Option:_run_lab_side_experiments_in_aelfrice_lab_only"]
D -->|Yes| G["Implement_feature_with_new_global_determinism_contract"]
C --> H["Use_R1_dedup_or_typed_slot_value_comparator_if_applicable"]
F --> I["Use_results_as_evidence_for_future_PHILOSOPHY_amendment_proposals"]
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 (2)
✨ 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 |
robotrocketscience
added
the
attn:review
![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:
- The new cross-reference sentence added to
PHILOSOPHY.mdis quite long and dense; consider splitting it into two sentences or moving the bench details into the dedicated memo to keep that core paragraph easily scannable. - The new
CHANGELOG.mdentry for the v3.0 PHILOSOPHY ratification is very verbose for a changelog bullet; consider shortening it to the core decision and pushing the detailed rationale and evidence intov3_relatedness_philosophy.md(which you can link from the entry).
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The new cross-reference sentence added to `PHILOSOPHY.md` is quite long and dense; consider splitting it into two sentences or moving the bench details into the dedicated memo to keep that core paragraph easily scannable.
- The new `CHANGELOG.md` entry for the v3.0 PHILOSOPHY ratification is very verbose for a changelog bullet; consider shortening it to the core decision and pushing the detailed rationale and evidence into `v3_relatedness_philosophy.md` (which you can link from the entry).
## Individual Comments
### Comment 1
<location path="docs/v3_relatedness_philosophy.md" line_range="21" />
<code_context>
+The bench evidence the issue cites confirms the ceiling is real, not the conclusion that the ceiling should be paid for inside aelfrice:
</code_context>
<issue_to_address>
**suggestion (typo):** Sentence structure around "confirms the ceiling is real, not the conclusion" is a bit awkward.
You might rephrase for clarity, for example: "The bench evidence the issue cites confirms the ceiling is real; it does not show that the ceiling should be paid for inside aelfrice."
```suggestion
The bench evidence the issue cites confirms the ceiling is real; it does not show that the ceiling should be paid for inside aelfrice:
```
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
|
|
||
| Option 2 (admit a sentence-embedding lane, fenced) and Option 3 (deterministic primary, embedding fallback) both violate the compositionality clause: any embedding lane in the retrieval path — even fenced behind a flag, even consulted only on miss — is a non-deterministic step in the retrieval path. The property cannot be partitioned per-lane without rewriting `PHILOSOPHY.md` § *Determinism* itself, and the costs cited in that section (debugging boundedness, provenance composition, counterfactual evaluation, audit comprehensible to a non-technical reviewer) are downstream of the global property holding. | ||
|
|
||
| The bench evidence the issue cites confirms the ceiling is real, not the conclusion that the ceiling should be paid for inside aelfrice: |
There was a problem hiding this comment.
suggestion (typo): Sentence structure around "confirms the ceiling is real, not the conclusion" is a bit awkward.
You might rephrase for clarity, for example: "The bench evidence the issue cites confirms the ceiling is real; it does not show that the ceiling should be paid for inside aelfrice."
Suggested change
| The bench evidence the issue cites confirms the ceiling is real, not the conclusion that the ceiling should be paid for inside aelfrice: | |
| The bench evidence the issue cites confirms the ceiling is real; it does not show that the ceiling should be paid for inside aelfrice: |
|
This PR is now behind Auto-rebase was removed because the bot has no signing key; rebasing as the bot strips author signatures and the |
…istic (#605) Adds docs/v3_relatedness_philosophy.md ratifying Option 1 from the issue (stay deterministic, narrow the surface) over Option 2 (admit a fenced embedding lane) and Option 3 (deterministic primary with embedding fallback). PHILOSOPHY.md § 'Determinism is the property' already commits to no embeddings / no learned re-rankers in the retrieval path and is explicit that the property is end-to-end ('there is no mostly deterministic'), which rules out the per-lane partition Options 2 and 3 require. Bench evidence (#197 R2, #422, #201 R2 — three corpora, same boundary) confirms the deterministic ceiling on natural-language paraphrase is real; the ratification is that the ceiling is accepted, not paid down inside aelfrice. Paraphrase / synonymy resolution lives in the consuming agent. R1 dedup surface and the typed-slot value-comparator stay shipped because they do what determinism can do.
…m section (#605) Adds a one-line pointer at the end of the 'trade-off is real' paragraph in PHILOSOPHY.md § Determinism is the property, naming the three bench closures (#197, #422, #201) and linking the v3 ratification memo. The memo itself says 'no doc surgery needed beyond a one-line cross- reference' — this is that line.
Inserts the entry above the existing v3.0-scope-cut row so the v3.0 PHILOSOPHY ratifications cluster together in Unreleased.
robotrocketscience
force-pushed
the
docs/issue-605-philosophy-relatedness
branch
from
May 10, 2026 23:52
a331f63 to
158d983
Compare
robotrocketscience
added
attn:review
Owner
Author
|
[claim:review:Maxwell:2026-05-11T00:03:24Z] |
Owner
Author
|
[claim:review:leibniz:2026-05-11T00:03:41Z] |
Owner
Author
|
[release:review:leibniz:2026-05-11T00:03:45Z] |
Owner
Author
|
[release:review:Maxwell:2026-05-11T00:04:59Z] |
This was referenced May 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Ratifies issue #605 (v3.0 PHILOSOPHY decision: natural-language-relatedness gate). Decision: Option 1 — stay deterministic, narrow the surface.
Three commits, atomic:
docs/v3_relatedness_philosophy.md— the ratification memodocs/PHILOSOPHY.md— one-line cross-reference at the end of the trade-off is real paragraph in § Determinism is the propertyCHANGELOG.md— Unreleased entry above the v3.0-scope-cut rowCloses #605.
Why this disposition
PHILOSOPHY.md§ Determinism is the property already commits to "no embeddings, no learned re-rankers, no LLM in the retrieval path […] there is no 'mostly deterministic' — either it holds end-to-end or it does not." Options 2 (admit a fenced embedding lane) and 3 (deterministic primary with embedding fallback) both require partitioning the property per-lane, which the existing PHILOSOPHY wording rules out. Re-opening the boundary requires aPHILOSOPHY.md§ Determinism amendment, not a dependency-posture change.Bench evidence the issue cites (#197 R2 WONTFIX, #422 contradiction WONTFIX, #201 R2 close — three corpora, same boundary) confirms the deterministic ceiling on natural-language paraphrase resolution is real. The ratification: the ceiling is accepted, paraphrase / synonymy resolution lives in the consuming agent, R1 dedup surface (
aelf doctor dedup) and the typed-slot value-comparator from #422 stay shipped because they do what determinism can do.Scope
Docs-only. No module surface added or removed. No dependency change. No test change.
Test plan
docs/v3_relatedness_philosophy.mdand confirms the rationale aligns with the existingPHILOSOPHY.md§ Determinism commitment they want preservedSummary by Sourcery
Document and ratify the v3.0 philosophy decision that natural-language-relatedness gates remain fully deterministic and live outside aelfrice’s retrieval and ingest path.
Documentation: