Skip to content

Say when supersession actually fires, because the README implied always - #225

Merged
joslat merged 1 commit into
mainfrom
docs/supersession-preconditions
Sep 20, 2026
Merged

joslat merged 1 commit into
mainfrom
docs/supersession-preconditions

Conversation

@joslat

@joslat joslat commented Sep 19, 2026

Copy link
Copy Markdown
Owner

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_at and two-clock point-in-time recall are built, tested and shipped. But the README said 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, and neither was 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 lived 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 deliberately did not patch is at into lives in.

What changed

  • README — the sentence that made the claim gains the two qualifiers.
  • architecture.md — a paragraph on when supersession 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; no code. Release build 0 warnings.

🤖 Generated with Claude Code

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>
Copilot AI lite review requested due to automatic review settings September 19, 2026 22:30

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 Medium severity

Open (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 thread docs/architecture.md
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants