Repository navigation
Say when supersession actually fires, because the README implied always - #225
Merged
Merged
Conversation
Found reviewing public claims against what the code does, after the bitemporal review showed
supersession had never fired in any measured run.
THE FEATURE IS REAL AND THE CLAIM WAS NOT. `SUPERSEDED_BY`, `invalidated_at` and two-clock
point-in-time recall are built, tested and shipped. But the README stated flatly that "contradictions
resolve via non-destructive SUPERSEDED_BY", and a reader would reasonably take that as something the
library does for their facts. Two conditions stand between them and it, neither documented anywhere
user-facing:
1. It is OPT-IN. `ExtractionOptions.SupersedeReplacedFacts` defaults to false.
2. It applies only to predicates the vocabulary declares SINGLE-VALUED -- belongs to, costs,
expires, lives in, weighs, works at. Everything else joins rather than replaces.
The six-relation limit existed only in an internal class remark. A user whose extractor writes
"is at" or "moved to" gets no supersession at all, silently, and indistinguishably from having
nothing to supersede.
THE DEFAULT IS RIGHT AND STAYS. Getting this wrong in the replacing direction is a data-shaped
defect: storing "likes tea" would drop "likes coffee" from live recall with nothing marking that a
true fact had been closed. The fix is to say so, not to widen the set -- which is also why the
bitemporal work did not patch `is at` into `lives in`.
README gains the two qualifiers in the sentence that made the claim. architecture.md gains the
paragraph explaining when it fires, why the default is deliberate, what the failure looks like
(nothing, silently), and that `UsePredicateVocabulary` is what steers extraction towards relations
supersession can recognise.
Docs only. Release build 0 warnings.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Unresolved documentation inaccuracies and an incomplete public capability caveat remain.
Get a fresh assessment by requesting another Copilot review.
Review effort: Lite
Findings: 1
What changed in this PR
This documentation-only PR clarifies that extraction-time supersession is opt-in and limited to six single-valued predicates.
Changes:
- Qualifies the README supersession claim.
- Documents activation conditions, defaults, and vocabulary guidance in
docs/architecture.md.
| File | Review findings |
|---|---|
README.md |
Moderate issue (1 vote): scope the qualifier to extraction-time supersession or document explicit resolution APIs. |
docs/architecture.md |
Moderate issues (2 votes, 1 vote): correct warning behavior and the UsePredicateVocabulary option type. Nit issues (1 vote each): update docs/memory-map.md and accurately describe warning details. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+471
to
+473
| enabled and nothing qualifies, the library logs one warning per batch naming the predicates it | ||
| refused; `ExtractionOptions.UsePredicateVocabulary` is what steers extraction towards the declared | ||
| relations in the first place. |
This was referenced Oct 7, 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
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.

Found by reviewing public claims against what the code does, after the bitemporal review showed supersession had never fired in any measured run.
The feature is real; the claim was not
SUPERSEDED_BY,invalidated_atand two-clock point-in-time recall are built, tested and shipped. But the README said flatly that "contradictions resolve via non-destructiveSUPERSEDED_BY", and a reader would reasonably take that as something the library does for their facts.Two conditions stand between them and it, and neither was documented anywhere user-facing:
ExtractionOptions.SupersedeReplacedFactsdefaults tofalse.belongs to,costs,expires,lives in,weighs,works at. Everything else joins rather than replaces.The six-relation limit lived only in an internal class remark. A user whose extractor writes
is atormoved togets no supersession at all, silently, and indistinguishably from having nothing to supersede.The default is right and stays
Getting this wrong in the replacing direction is a data-shaped defect: storing "likes tea" would drop "likes coffee" from live recall with nothing marking that a true fact had been closed. The fix is to say so, not to widen the set — which is also why the bitemporal work deliberately did not patch
is atintolives in.What changed
UsePredicateVocabularyis what steers extraction towards relations supersession can recognise.Docs only; no code. Release build 0 warnings.
🤖 Generated with Claude Code