linkedparticles-core 1.149.0__tar.gz → 1.151.18__tar.gz

{linkedparticles_core-1.149.0 → linkedparticles_core-1.151.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: linkedparticles-core
-Version: 1.149.0
+Version: 1.151.18
 Summary: Store-free client library for Particles: define, validate, serialize, and extract provenance-tracked belief particles
 Project-URL: Homepage, https://linkedparticles.org
 Project-URL: Documentation, https://docs.linkedparticles.org
@@ -44,7 +44,7 @@ Requires-Dist: pyyaml>=6.0
 Requires-Dist: rdflib<8,>=7.0
 Requires-Dist: scipy>=1.13
 Requires-Dist: sentence-transformers>=2.7
-Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: sqlalchemy[asyncio]<2.2,>=2.0
 Requires-Dist: torch
 Provides-Extra: vision
 Requires-Dist: pypdfium2>=4.30; extra == 'vision'
@@ -76,7 +76,7 @@ wire format, and the extraction pipeline. Everything you need to *make* and
 > an MCP server), install
 > **[`linkedparticles`](https://pypi.org/project/linkedparticles/)** instead.
 > It depends on this package and pulls it in automatically. This one is the
-> substrate underneath it. Its repository,
+> foundation it is built on. Its repository,
 > **[`particles-engine-py`](https://github.com/LinkedParticles/particles-engine-py)**,
 > is the reference implementation's front door: issues, discussion, and
 > documentation live there.

{linkedparticles_core-1.149.0 → linkedparticles_core-1.151.18}/README.md

@@ -24,7 +24,7 @@ wire format, and the extraction pipeline. Everything you need to *make* and
 > an MCP server), install
 > **[`linkedparticles`](https://pypi.org/project/linkedparticles/)** instead.
 > It depends on this package and pulls it in automatically. This one is the
-> substrate underneath it. Its repository,
+> foundation it is built on. Its repository,
 > **[`particles-engine-py`](https://github.com/LinkedParticles/particles-engine-py)**,
 > is the reference implementation's front door: issues, discussion, and
 > documentation live there.

{linkedparticles_core-1.149.0 → linkedparticles_core-1.151.18}/particles/core/conflict_resolution.py

@@ -12,10 +12,13 @@ trust inputs already resolved by the caller, return a ``ConflictVerdict``
 saying what should happen. It also owns the constructor that builds an
 ``INCONSISTENCY`` ``Particle`` from a conflicting pair.
 
+It also owns the overrides around the verdict (:func:`decide_ladder`): the
+tri-state probe, the observer precondition, and which rung 2.5 input applies.
 The *effect* half of the ladder — DB writes, trust-rank lookups, embedding
 similarity computation, the LLM contradiction-signal call — stays in
-``particles/extraction/pipeline.py`` because it touches I/O. Core code must
-remain pure (see ``particles/core/AGENTS.md``).
+``particles/ingest/`` because it touches I/O: ``conflict_plan`` maps an outcome
+to writes, and ``pipeline`` gathers the inputs and applies the plan. Core code
+must remain pure (see ``particles/core/AGENTS.md``).
 
 Ladder (normative, applied in order — §6.4, rung for rung):
 
@@ -83,9 +86,11 @@ Two extra verdicts are emitted by the pre-ladder gate the caller may apply:
 
 from __future__ import annotations
 
+from dataclasses import dataclass
 from enum import StrEnum
 from typing import Any
 
+from particles.core.observer_scope import PairPrecondition
 from particles.core.schema import (
     SCHEMA_VERSION,
     Confidence,
@@ -309,6 +314,165 @@ def resolve_conflict(
     return ConflictVerdict.INCONSISTENT
 
 
+@dataclass(frozen=True)
+class RungInputs:
+    """The gathered §6.4 rung inputs for one pair; the defaults are "no input".
+
+    The caller resolves these only when :func:`needs_rung_inputs` says the
+    ladder can consult them (a confirmed or fail-closed signal on a pair the
+    observer precondition does not decline).
+    """
+
+    new_supersedes_existing: bool = False
+    """Rung 1.5: ``new``'s document (transitively) supersedes ``existing``'s."""
+    existing_supersedes_new: bool = False
+    """Rung 1.5 mirror."""
+    trust_score_new: float | None = None
+    """Rung 2: the candidate's pre-resolved trust score."""
+    trust_score_existing: float | None = None
+    """Rung 2: the existing particle's pre-resolved trust score."""
+    update_order: int | None = None
+    """Rung 2.5: see :func:`resolve_conflict`'s ``update_order``."""
+
+
+@dataclass(frozen=True)
+class LadderOutcome:
+    """What the §6.6 ladder decided for one pair, overrides included."""
+
+    verdict: ConflictVerdict | None
+    """The verdict; ``None`` when the observer precondition declined the pair:
+    the candidate is written ``ACTIVE`` beside the existing claim."""
+    record_divergence: bool
+    """Declined and the signal is set: the pair is recorded as a divergence."""
+
+
+class UpdateOrderSource(StrEnum):
+    """Which rung 2.5 input the caller gathers for a pair."""
+
+    UPDATE = "update"
+    """Extraction's same-lineage update order."""
+    OWN_ASSERTION = "own_assertion"
+    """The assertion pathway's own-assertion order."""
+
+
+def ladder_signal(probe: bool | None, *, fail_closed: bool) -> bool:
+    """The contradiction signal the ladder runs on, from a tri-state probe.
+
+    ``True``/``False`` is a verdict. ``None`` means the probe could not
+    complete: extraction stays fail-open (no signal), and the assertion pathway
+    fails closed (a signal, which :func:`forces_inconsistent` then overrides to
+    ``INCONSISTENT``).
+    """
+    if probe is None:
+        return fail_closed
+    return probe
+
+
+def forces_inconsistent(
+    probe: bool | None, *, fail_closed: bool, precondition: PairPrecondition
+) -> bool:
+    """Whether the verdict is ``INCONSISTENT`` whatever the rungs would say.
+
+    Two overrides: an incomplete probe under ``fail_closed``, and
+    a project's candidate contesting a global claim with a signal (
+    ``REVIEW``). A ``DECLINE`` outranks both; :func:`decide_ladder` checks it
+    first.
+    """
+    if probe is None and fail_closed:
+        return True
+    return precondition is PairPrecondition.REVIEW and ladder_signal(probe, fail_closed=fail_closed)
+
+
+def needs_rung_inputs(
+    probe: bool | None, *, fail_closed: bool, precondition: PairPrecondition
+) -> bool:
+    """Whether the caller should gather :class:`RungInputs` for the pair.
+
+    Only a set signal reaches the rungs, and a declined pair reaches none. A
+    forced ``INCONSISTENT`` still gathers: the domain read alongside the trust
+    scores is the INCONSISTENCY record's ``domain_hint``.
+    """
+    if precondition is PairPrecondition.DECLINE:
+        return False
+    return ladder_signal(probe, fail_closed=fail_closed)
+
+
+def update_order_source(
+    *,
+    allow_update: bool,
+    allow_own_assertion: bool,
+    forced: bool,
+) -> UpdateOrderSource | None:
+    """Which rung 2.5 input applies, if any.
+
+    ``allow_update`` is extraction's door with the config switch already folded
+    in; ``allow_own_assertion`` the assertion pathway's narrower one.
+    A forced ``INCONSISTENT`` consults neither.
+    """
+    if forced:
+        return None
+    if allow_update:
+        return UpdateOrderSource.UPDATE
+    if allow_own_assertion:
+        return UpdateOrderSource.OWN_ASSERTION
+    return None
+
+
+def effective_single_trust_order(override: bool | None, store_mode: str) -> bool:
+    """The trust regime the ladder runs under.
+
+    A caller's explicit ``override`` wins; otherwise the store mode decides.
+    """
+    if override is not None:
+        return override
+    return store_mode == "single"
+
+
+def decide_ladder(
+    existing: Particle,
+    new: Particle,
+    *,
+    probe: bool | None,
+    fail_closed: bool,
+    precondition: PairPrecondition,
+    rung_inputs: RungInputs | None,
+    single_trust_order: bool,
+    trust_differential_threshold: float,
+) -> LadderOutcome:
+    """The §6.6 ladder for one pair, with every override applied in order.
+
+    Pure: the caller gathers the probe, the precondition and (when
+    :func:`needs_rung_inputs`) the rung inputs, then applies the outcome. The
+    override order is:
+
+      1. ``DECLINE``: no rung runs, whatever the probe said. The
+         divergence is recorded when the signal is set, a fail-closed
+         incomplete probe included.
+      2. a forced ``INCONSISTENT`` (:func:`forces_inconsistent`): the rungs are
+         skipped.
+      3. otherwise :func:`resolve_conflict` on the signal and the rung inputs.
+    """
+    signal = ladder_signal(probe, fail_closed=fail_closed)
+    if precondition is PairPrecondition.DECLINE:
+        return LadderOutcome(verdict=None, record_divergence=signal)
+    if forces_inconsistent(probe, fail_closed=fail_closed, precondition=precondition):
+        return LadderOutcome(verdict=ConflictVerdict.INCONSISTENT, record_divergence=False)
+    inputs = rung_inputs if rung_inputs is not None else RungInputs()
+    verdict = resolve_conflict(
+        existing,
+        new,
+        has_contradiction_signal=signal,
+        new_supersedes_existing=inputs.new_supersedes_existing,
+        existing_supersedes_new=inputs.existing_supersedes_new,
+        trust_score_existing=inputs.trust_score_existing,
+        trust_score_new=inputs.trust_score_new,
+        trust_differential_threshold=trust_differential_threshold,
+        single_trust_order=single_trust_order,
+        update_order=inputs.update_order,
+    )
+    return LadderOutcome(verdict=verdict, record_divergence=False)
+
+
 # the ``properties`` marker on an INCONSISTENCY record whose
 # "Particle A" is a judgment-retired twin rather than a live claim. Its value
 # is the retired twin's ``status_reason``. Review reads it to know that

linkedparticles_core-1.151.18/particles/core/conflict_review.py

@@ -0,0 +1,310 @@
+# SPDX-FileCopyrightText: 2026 The Particles authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Pure INCONSISTENCY-resolution decisions shared by Review and the trust cascade.
+
+An INCONSISTENCY wrapper names two conflicting claims, A and B. Two operations
+close it: a human review (§9.6, :mod:`particles.operations.review`) and the
+source trust cascade (Extension B, :mod:`particles.operations.cascade`). Both
+decide the same things — which claim loses, what demoting it means given its
+current status, whether a quarantined claim is promoted, and which corpus
+entry a trust statement is keyed on — and those decisions are pure functions
+of the wrapper, the two claims and (for the cascade) their trust ranks.
+
+They live here so each rule exists once and is testable without a database
+(D2). The operations keep the I/O half: they gather the wrapper and
+the claims, call these functions, and apply the plan in their existing write
+order. Same split as :mod:`particles.core.cascade_gate`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+from particles.core.conflict_resolution import RETIRED_VALUE_KEY
+from particles.core.schema import Particle, ProvenanceRefType, ResolutionAction
+from particles.core.status import Status, StatusReason
+
+_TERMINAL = (Status.RETRACTED, Status.SUPERSEDED)
+
+
+class Demotion(Enum):
+    """What demoting a conflict's losing claim takes, given its current status."""
+
+    NONE = "none"
+    """Nothing to write: the claim is missing (a pre-ADR-0117 dangling ref),
+    already terminal, or stale for a reason other than a pending
+    conflict."""
+
+    REASON_FLIP = "reason_flip"
+    """A quarantined claim: ``CONFLICT_PENDING → CONFLICT_RESOLVED``
+    in place, with no status transition."""
+
+    TRANSITION = "transition"
+    """A live claim: transition to ``PROVENANCE_STALE`` / ``CONFLICT_RESOLVED``."""
+
+
+@dataclass(frozen=True)
+class AleatoryMark:
+    """One BOTH_VALID claim to keep queryable with ``ALEATORY`` nature."""
+
+    particle: Particle
+    mint: bool
+    """True for a quarantined claim, which is promoted to a new ACTIVE
+    particle carrying the nature; False to update the nature in place."""
+
+
+@dataclass(frozen=True)
+class TrustJudgment:
+    """The SourceTrustStatement a PREFER review writes, before it is minted."""
+
+    source_entry_id: str
+    """Corpus entry the statement is keyed on."""
+    preferred_id: str
+    """The preferred claim as stored. When the plan promotes it, the operation
+    names the minted particle instead."""
+    demoted_id: str | None
+    """The other wrapper ref, which may dangle on a pre-ADR-0117 wrapper."""
+
+
+@dataclass(frozen=True)
+class ResolutionPlan:
+    """Every write a review resolution makes, decided up front.
+
+    The operation applies the fields in declaration order, then closes (or,
+    for DEFER, re-sets) the wrapper, and only then runs the trust cascade
+    when ``trust`` is set. The wrapper closes first so the cascade never
+    re-processes the resolution just made.
+    """
+
+    demote: tuple[Particle, Demotion] | None
+    promote: Particle | None
+    aleatory: tuple[AleatoryMark, ...]
+    trust: TrustJudgment | None
+    """None: no trust statement is written, and no cascade runs."""
+    close_wrapper: bool
+    """False only for DEFER, the one action that leaves the wrapper open."""
+
+
+@dataclass(frozen=True)
+class CascadeVerdict:
+    """A trust-cascade resolution of one wrapper."""
+
+    winner: Particle
+    loser: Particle
+    loser_demotion: Demotion
+    promote_winner: bool
+    """True when the winner is quarantined: it is promoted to a new ACTIVE
+    particle, as a PREFER_B review would."""
+
+
+def is_quarantined(particle: Particle) -> bool:
+    """True for a §6.6 quarantined conflict loser."""
+    return (
+        particle.status is Status.PROVENANCE_STALE
+        and particle.status_reason is StatusReason.CONFLICT_PENDING
+    )
+
+
+def conflict_pair_ids(inconsistency: Particle) -> tuple[str | None, str | None]:
+    """The ids of claims A and B named by an INCONSISTENCY wrapper.
+
+    By convention the first PARTICLE provenance ref is A and the second is B;
+    the referenced particle id travels in ``corpus_entry_id``. A missing ref
+    reads as None.
+    """
+    refs = [
+        r.corpus_entry_id for r in inconsistency.provenance if r.type is ProvenanceRefType.PARTICLE
+    ]
+    return (
+        refs[0] if len(refs) > 0 else None,
+        refs[1] if len(refs) > 1 else None,
+    )
+
+
+def is_retired_value(inconsistency: Particle) -> bool:
+    """Whether the wrapper records a retired value rather than a source conflict.
+
+    A retired-value record pairs a judgment-retired twin (A) with a held
+    re-assertion (B). Resolving it rules on the earlier judgment, not on a
+    source, so neither review nor the cascade writes a trust verdict for it.
+    """
+    return bool(inconsistency.properties and inconsistency.properties.get(RETIRED_VALUE_KEY))
+
+
+def decide_demotion(loser: Particle | None) -> Demotion:
+    """What demoting a conflict's losing claim takes.
+
+    A missing loser (a pre-ADR-0117 wrapper's dangling ref) and a terminal one
+    (a judgment-retired twin) need nothing: there is no legal
+    transition out of a terminal state. A stale loser is already demoted; only
+    a quarantined one has its reason flipped.
+    """
+    if loser is None or loser.status in _TERMINAL:
+        return Demotion.NONE
+    if loser.status is Status.PROVENANCE_STALE:
+        if loser.status_reason is StatusReason.CONFLICT_PENDING:
+            return Demotion.REASON_FLIP
+        return Demotion.NONE
+    return Demotion.TRANSITION
+
+
+def _source_entry_id(particle: Particle) -> str | None:
+    """The corpus entry of the claim's first SOURCE provenance ref."""
+    ref = next((r for r in particle.provenance if r.type is ProvenanceRefType.SOURCE), None)
+    return ref.corpus_entry_id if ref is not None else None
+
+
+def trust_statement_source(preferred: Particle | None) -> str | None:
+    """The corpus-entry id a PREFER judgment's trust statement is keyed on.
+
+    Every consumer of a SourceTrustStatement matches its ``source_ref``
+    against a corpus-entry id: the §6.4 layered cascade and the reviewer
+    confirmation gate. The statement is therefore keyed on
+    the corpus entry of the preferred claim's SOURCE provenance, never on the
+    particle id, which no consumer could look up.
+
+    Returns None, meaning no statement is written, when the preferred claim is
+    unknown (a dangling ref), is not ACTIVE (a retired claim is no source
+    recommendation), or has no SOURCE provenance (an agent-asserted or
+    derived claim names no corpus entry).
+    """
+    if preferred is None or preferred.status is not Status.ACTIVE:
+        return None
+    return _source_entry_id(preferred)
+
+
+def decide_resolution(
+    action: ResolutionAction,
+    inconsistency: Particle,
+    particle_a: Particle | None,
+    particle_b: Particle | None,
+) -> ResolutionPlan:
+    """Decide every write a review resolution makes (§9.6).
+
+    Args:
+        action: The reviewer's resolution.
+        inconsistency: The INCONSISTENCY wrapper.
+        particle_a: Claim A as stored, or None when its ref dangles.
+        particle_b: Claim B as stored, or None when its ref dangles.
+
+    Returns:
+        The plan the operation applies.
+    """
+    a_id, b_id = conflict_pair_ids(inconsistency)
+    retired_value = is_retired_value(inconsistency)
+
+    match action:
+        case ResolutionAction.PREFER_A:
+            trust_source = trust_statement_source(particle_a)
+            trust = (
+                TrustJudgment(trust_source, particle_a.id, b_id)
+                if trust_source is not None and particle_a is not None and not retired_value
+                else None
+            )
+            return ResolutionPlan(
+                demote=_demote(particle_b),
+                promote=None,
+                aleatory=(),
+                trust=trust,
+                close_wrapper=True,
+            )
+        case ResolutionAction.PREFER_B:
+            # A quarantined B is minted as a new ACTIVE particle carrying its
+            # provenance verbatim, so the statement is keyed on B's source as
+            # if B were ACTIVE; any other B is judged as stored.
+            promote = particle_b if particle_b is not None and is_quarantined(particle_b) else None
+            trust_source = (
+                _source_entry_id(promote)
+                if promote is not None
+                else trust_statement_source(particle_b)
+            )
+            trust = (
+                TrustJudgment(trust_source, particle_b.id, a_id)
+                if trust_source is not None and particle_b is not None and not retired_value
+                else None
+            )
+            return ResolutionPlan(
+                demote=_demote(particle_a),
+                promote=promote,
+                aleatory=(),
+                trust=trust,
+                close_wrapper=True,
+            )
+        case ResolutionAction.BOTH_VALID:
+            marks = tuple(
+                AleatoryMark(particle=p, mint=is_quarantined(p))
+                for p in (particle_a, particle_b)
+                if p is not None
+            )
+            return ResolutionPlan(
+                demote=None, promote=None, aleatory=marks, trust=None, close_wrapper=True
+            )
+        case ResolutionAction.DEFER:
+            return ResolutionPlan(
+                demote=None, promote=None, aleatory=(), trust=None, close_wrapper=False
+            )
+
+
+def _demote(loser: Particle | None) -> tuple[Particle, Demotion] | None:
+    return (loser, decide_demotion(loser)) if loser is not None else None
+
+
+def cascade_pair(
+    inconsistency: Particle, particle_a: Particle | None, particle_b: Particle | None
+) -> tuple[Particle, Particle] | None:
+    """The structural half of the cascade decision: is this wrapper rankable?
+
+    The trust cascade leaves a wrapper for a person when either claim is
+    missing (a pre-ADR-0117 dangling ref), when it records a retired value, or
+    when A has since left the surface by a terminal transition: source trust
+    cannot answer a question about an earlier judgment.
+
+    The operation calls this before looking up trust ranks, so a skipped
+    wrapper costs no rank lookups. :func:`decide_cascade` applies it again,
+    so it is a complete decision on its own.
+
+    Returns:
+        ``(A, B)`` to rank, or None when the wrapper is left open.
+    """
+    if particle_a is None or particle_b is None:
+        return None
+    if is_retired_value(inconsistency) or particle_a.status in _TERMINAL:
+        return None
+    return particle_a, particle_b
+
+
+def decide_cascade(
+    inconsistency: Particle,
+    particle_a: Particle | None,
+    particle_b: Particle | None,
+    rank_a: float | None,
+    rank_b: float | None,
+    *,
+    differential_threshold: float,
+) -> CascadeVerdict | None:
+    """Decide whether the trust cascade resolves a wrapper, and for whom.
+
+    The claim whose source ranks higher wins, provided both ranks are known
+    and differ by at least ``differential_threshold``. On an exact tie that
+    clears a zero threshold, B wins.
+
+    Returns:
+        The verdict, or None when the wrapper stays open for manual review.
+    """
+    pair = cascade_pair(inconsistency, particle_a, particle_b)
+    if pair is None or rank_a is None or rank_b is None:
+        return None
+    diff = rank_a - rank_b
+    if abs(diff) < differential_threshold:
+        return None
+    a, b = pair
+    winner, loser = (a, b) if diff > 0 else (b, a)
+    return CascadeVerdict(
+        winner=winner,
+        loser=loser,
+        loser_demotion=decide_demotion(loser),
+        promote_winner=is_quarantined(winner),
+    )

{linkedparticles_core-1.149.0 → linkedparticles_core-1.151.18}/particles/core/equivalence.py

@@ -21,6 +21,10 @@ with cross-lingual detection and the ``language`` field.
 
 from __future__ import annotations
 
+from collections.abc import Iterable
+
+from particles.core.schema import ParticleRelation
+
 
 def effective_equivalence(link_confidence: float, *, observer_trust: float | None = None) -> float:
     """Observer-relative claim-equivalence strength in ``[0, 1]`` (§6.10).
@@ -38,3 +42,45 @@ def effective_equivalence(link_confidence: float, *, observer_trust: float | Non
     if observer_trust is None:
         return link_confidence
     return max(0.0, min(1.0, link_confidence * observer_trust))
+
+
+def co_evidential_components(
+    edges: Iterable[ParticleRelation], min_confidence: float
+) -> dict[str, frozenset[str]]:
+    """Group ids into CO_EVIDENTIAL components from the whole edge list at once.
+
+    The in-memory equivalent of running ``get_co_evidential_group`` per particle,
+    honouring the same ``effective_equivalence >= min_confidence`` gate, so a
+    caller reads the relation table once and decides "already linked" without a
+    session (D2). Ids with no qualifying edge are simply
+    absent: their component is the singleton the caller supplies.
+
+    Args:
+        edges: CO_EVIDENTIAL edges, e.g. ``get_all_relations(session, CO_EVIDENTIAL)``.
+        min_confidence: Edges whose effective equivalence falls below this are
+            not traversed.
+
+    Returns:
+        Every id that sits on a qualifying edge, mapped to its whole component
+        (itself included).
+    """
+    parent: dict[str, str] = {}
+
+    def find(x: str) -> str:
+        parent.setdefault(x, x)
+        while parent[x] != x:
+            parent[x] = parent[parent[x]]
+            x = parent[x]
+        return x
+
+    for e in edges:
+        if effective_equivalence(e.confidence) < min_confidence:
+            continue
+        a, b = find(e.particle_a), find(e.particle_b)
+        if a != b:
+            parent[a] = b
+
+    groups: dict[str, set[str]] = {}
+    for node in list(parent):
+        groups.setdefault(find(node), set()).add(node)
+    return {node: frozenset(members) for members in groups.values() for node in members}

linkedparticles_core-1.151.18/particles/core/provenance.py

@@ -0,0 +1,38 @@
+# SPDX-FileCopyrightText: 2026 The Particles authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""The shape of an appended provenance observation (D1).
+
+Provenance is append-only: a re-observation of a claim is a new ref, never an
+edit of an old one. This module holds the pure rule for what that ref looks
+like, so it is testable without a store; the write stays with
+``particle_store.append_provenance_ref``, the one provenance writer.
+"""
+
+from __future__ import annotations
+
+from particles.core.schema import Particle, ProvenanceRef, ProvenanceRefType
+
+
+def reobservation_ref(particle: Particle, entry_id: str, snapshot_id: str) -> ProvenanceRef:
+    """Return the ref recording that ``snapshot_id`` re-observed ``particle``.
+
+    The ref copies the particle's latest SOURCE ref to ``entry_id`` (its
+    location and chunk hash are the carried chunk's) and names the
+    re-observing snapshot. A particle with no SOURCE ref to the entry gets a
+    bare SOURCE ref naming the entry and snapshot.
+    """
+    prior = next(
+        (
+            r
+            for r in reversed(particle.provenance)
+            if r.type is ProvenanceRefType.SOURCE and r.corpus_entry_id == entry_id
+        ),
+        None,
+    )
+    if prior is not None:
+        return prior.model_copy(update={"snapshot_id": snapshot_id})
+    return ProvenanceRef(
+        type=ProvenanceRefType.SOURCE, corpus_entry_id=entry_id, snapshot_id=snapshot_id
+    )

{linkedparticles_core-1.149.0 → linkedparticles_core-1.151.18}/particles/extraction/journal.py

@@ -33,7 +33,7 @@ size — narrative grouping (one label, one sequence) is a whole-document concer
 Over-length entries (> ``extraction.html_chunk_size``) are extracted in multiple
 carry-forward passes and their per-chunk NARRATIVE fragments are
 merged into one whole-entry NARRATIVE by the Engine-side post-pass
-(:func:`particles.ingest.narrative_merge.collapse_chunk_narratives`).
+(:func:`particles.ingest.narrative_merge.collapse_narratives`).
 """
 
 from __future__ import annotations
@@ -283,7 +283,7 @@ class JournalExtractor:
         (2). Each cache-miss chunk yields its claims (chunk-local
         ``narrative_index``) plus one per-chunk NARRATIVE candidate; the Engine
         post-pass
-        (:func:`particles.ingest.narrative_merge.collapse_chunk_narratives`)
+        (:func:`particles.ingest.narrative_merge.collapse_narratives`)
         collapses those fragments into one whole-entry NARRATIVE with a global
         ``SEQUENCE_IN`` order. Chunks beyond ``max_llm_calls_per_source`` emit
         the shared ``CHUNK_TRUNCATION`` note — the new, much higher truncation

{linkedparticles_core-1.149.0 → linkedparticles_core-1.151.18}/pyproject.toml

@@ -19,7 +19,7 @@
 # version and advance together.
 [project]
 name = "linkedparticles-core"
-version = "1.149.0"
+version = "1.151.18"
 description = "Store-free client library for Particles: define, validate, serialize, and extract provenance-tracked belief particles"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -80,8 +80,10 @@ dependencies = [
     # The extraction layer types its session parameters against SQLAlchemy's
     # async session; the import is executed at module load even though no
     # Client module opens a connection. Declared so a store-free install still
-    # imports.
-    "sqlalchemy>=2.0",
+    # imports, and with `[asyncio]` because that import needs greenlet, which
+    # SQLAlchemy stopped installing by default in 2.1. Bounded below the next
+    # minor: 2.1 changed ORM and typing behaviour this code depends on.
+    "sqlalchemy[asyncio]>=2.0,<2.2",
     # JSON-LD / RDF / SHACL parsing stack — these handle attacker-influenced
     # input (interchange import, conformance validation), so they carry tested
     # next-breaking upper bounds in addition to the floor: a future breaking