linkedparticles 1.149.0__tar.gz → 1.151.18__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: linkedparticles
-Version: 1.149.0
+Version: 1.151.18
 Summary: Auditable, provenance-tracked memory for AI agents — the Particles engine and its API, CLI, and MCP surfaces
 Project-URL: Homepage, https://linkedparticles.org
 Project-URL: Documentation, https://docs.linkedparticles.org
@@ -39,11 +39,11 @@ Requires-Dist: fastapi>=0.111
 Requires-Dist: filelock>=3.13
 Requires-Dist: greenlet>=3.5.0
 Requires-Dist: jinja2>=3.1
-Requires-Dist: linkedparticles-core==1.149.0
+Requires-Dist: linkedparticles-core==1.151.18
 Requires-Dist: mcp<2,>=1.27.1
 Requires-Dist: opentelemetry-api>=1.27
 Requires-Dist: python-multipart>=0.0.9
-Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: sqlalchemy[asyncio]<2.2,>=2.0
 Requires-Dist: typer>=0.12
 Requires-Dist: uvicorn[standard]>=0.30
 Requires-Dist: warcio>=1.7

linkedparticles-1.151.18/alembic/versions/040_backfill_particle_tag_edges.py

@@ -0,0 +1,88 @@
+# SPDX-FileCopyrightText: 2026 The Particles authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Backfill ``particle_tag_edges`` from ``particles.tags_json``.
+
+A particle's tags live in two places: ``particles.tags_json`` (the canonical
+list, round-tripped to ``Particle.tags``) and ``particle_tag_edges`` (one row
+per tag, the index every tag-filtered read joins on). Until this release
+``insert_particle`` wrote only the JSON column; the edge rows came only from
+``set_particle_tags`` / ``add_particle_tags``. A particle born with tags (an
+agent assertion with ``tags``, a supersession or subject-assign successor
+inheriting its predecessor's tags, a conversation deposit) was therefore
+invisible to every tag-filtered query.
+
+**The backfill.** For every particle with a non-empty ``tags_json``, insert the
+edge rows it is missing. Rows already present are left alone, so the migration
+is idempotent and safe on a store where some particles were retagged by hand.
+Malformed JSON is skipped, not repaired: the column is read as-is by
+``ParticleRow.to_model``, and this migration does not change what a particle
+says about itself.
+
+``downgrade()`` is a deliberate no-op. A backfilled edge cannot be told apart
+from one ``set_particle_tags`` wrote, and each one agrees with the particle's
+own tag list, so removing them would only reintroduce the defect.
+
+Revision ID: 040
+Revises: 039
+"""
+
+from __future__ import annotations
+
+import json
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "040"
+down_revision = "039"
+branch_labels = None
+depends_on = None
+
+
+def backfill_tag_edges(bind: sa.engine.Connection) -> int:
+    """Insert the edge rows each tagged particle is missing.
+
+    Takes the connection rather than calling ``op.get_bind()`` so the backfill
+    is exercisable outside an Alembic context, as in migration 037. See
+    ``tests/test_migration_040_tag_edges.py``.
+
+    Returns the number of edge rows inserted.
+    """
+    existing = {
+        (pid, tag)
+        for pid, tag in bind.execute(
+            sa.text("SELECT particle_id, tag FROM particle_tag_edges")
+        ).fetchall()
+    }
+    rows = bind.execute(
+        sa.text("SELECT id, tags_json FROM particles WHERE tags_json IS NOT NULL")
+    ).fetchall()
+    missing: list[dict[str, str]] = []
+    for pid, tags_json in rows:
+        try:
+            tags = json.loads(tags_json)
+        except (TypeError, ValueError):
+            continue
+        if not isinstance(tags, list):
+            continue
+        for tag in dict.fromkeys(t for t in tags if isinstance(t, str) and t):
+            if (pid, tag) not in existing:
+                existing.add((pid, tag))
+                missing.append({"pid": pid, "tag": tag})
+    if missing:
+        bind.execute(
+            sa.text("INSERT INTO particle_tag_edges (particle_id, tag) VALUES (:pid, :tag)"),
+            missing,
+        )
+    return len(missing)
+
+
+def upgrade() -> None:
+    backfill_tag_edges(op.get_bind())
+
+
+def downgrade() -> None:
+    pass

{linkedparticles-1.149.0 → linkedparticles-1.151.18}/artifacts/openapi.json

@@ -2656,6 +2656,7 @@
         "description": "The kind of operator action an event records.\n\nOne value per distinct *outcome*: opposite outcomes get distinct types\n(``PARTICLE_TAGGED`` vs ``PARTICLE_UNTAGGED``) so ``--type`` is a precise\nfilter; the *same* outcome reached two ways (``trust set`` /\n``trust statement-set`` both write a SourceTrustStatement) shares one type,\nwith ``actor`` recording which verb. Extensible for later verbs that meet\nthe inclusion criterion.",
         "enum": [
           "SOURCE_RETRACTED",
+          "CORPUS_ENTRY_DELETED",
           "CONFLICT_CANDIDATE_DROPPED",
           "SUBJECTS_SPLIT",
           "SUBJECTS_MERGED",
@@ -7849,7 +7850,7 @@
     },
     "/particles/{particle_id}/source": {
       "get": {
-        "description": "Return the source passage behind a particle, with how it was found.\n\n``match`` is ``EXACT`` (the hash-verified chunk the extractor saw),\n``LOCATED`` (best term-overlap paragraph \u2014 a reading aid, not\nverification), ``WHOLE`` (the snapshot text), or ``UNAVAILABLE`` with a\n``note``. Display only: never a ranking input. 404 if the particle does\nnot exist.",
+        "description": "Return the source passage behind a particle, with how it was found.\n\n``match`` is ``EXACT`` (the hash-verified chunk the extractor saw),\n``LOCATED`` (best term-overlap paragraph; a reading aid, not\nverification), ``WHOLE`` (the snapshot text), or ``UNAVAILABLE`` with a\n``note``. Display only: never a ranking input. 404 if the particle does\nnot exist.",
         "operationId": "get_particle_source_particles__particle_id__source_get",
         "parameters": [
           {

{linkedparticles-1.149.0 → linkedparticles-1.151.18}/particles/api/app.py

@@ -1070,7 +1070,7 @@ async def get_particle_source(
     """Return the source passage behind a particle, with how it was found.
 
     ``match`` is ``EXACT`` (the hash-verified chunk the extractor saw),
-    ``LOCATED`` (best term-overlap paragraph — a reading aid, not
+    ``LOCATED`` (best term-overlap paragraph; a reading aid, not
     verification), ``WHOLE`` (the snapshot text), or ``UNAVAILABLE`` with a
     ``note``. Display only: never a ranking input. 404 if the particle does
     not exist."""

{linkedparticles-1.149.0 → linkedparticles-1.151.18}/particles/api/cli/audit.py

@@ -99,7 +99,7 @@ def audit_cmd(
         ),
     ),
     output: Path | None = typer.Option(
-        None, "--output", help="Also write the Markdown report to FILE."
+        None, "--output", help="Write the Markdown report to FILE as well."
     ),
     format_: str = typer.Option(
         "markdown", "--format", help="Terminal format: markdown (default) or json."

{linkedparticles-1.149.0 → linkedparticles-1.151.18}/particles/api/cli/benchmark.py

@@ -695,13 +695,13 @@ def benchmark_observer_cmd(
         "suppression); `chunked` sends two lines per chunk through carry-forward.",
     ),
 ) -> None:
-    """The two-project observer fixture — zero LLM calls.
+    """The two-project observer fixture, with zero LLM calls.
 
     Two repositories' memory files, sharing generic subjects, evolve over
     `--days` and are harvested into one scratch store through the real
     pipeline with scripted extraction and a scripted contradiction probe.
     Each day, every line a project currently states is checked through that
-    project's observer: in view, or not — and if not, which mechanism retired
+    project's observer: in view, or not, and if not, which mechanism retired
     it (cross-project supersession, the generation cascade, or a surviving
     particle attested only by the other project) and whether the winner is in
     view. Report-only; the only number the default flip is decided
@@ -765,7 +765,7 @@ def benchmark_rot_cmd(  # noqa: PLR0913 — CLI option list is the API
         "--arm",
         help="Perception arm: oracle (scripted extraction + scripted §6.6 probe; "
         "zero LLM calls, deterministic), probe (scripted extraction, live "
-        "contradiction probe), or live (the general extractor — the product).",
+        "contradiction probe), or live (the general extractor, i.e. the product).",
     ),
     seed: list[int] | None = typer.Option(
         None,
@@ -792,7 +792,7 @@ def benchmark_rot_cmd(  # noqa: PLR0913 — CLI option list is the API
         False, "--yes", "-y", help="Skip the confirmation above the call threshold."
     ),
     output: Path | None = typer.Option(
-        None, "--output", "-o", help="Also write the rendered report to this path."
+        None, "--output", "-o", help="Write the rendered report to this path as well."
     ),
     output_format: _Format = typer.Option(
         _Format.table, "--format", help="table (default) or json (the report of record)."
@@ -823,7 +823,7 @@ def benchmark_rot_cmd(  # noqa: PLR0913 — CLI option list is the API
     checkpoint, probes every attribute through the query op's selection half.
     Reports currency (recall_current@k, current_first), supersession
     (stale_over_current, stale_retained@k), and poison leakage across three
-    untrusted channels — separately, with no aggregate score.
+    untrusted channels, each reported separately, with no aggregate score.
     """
     if ctx.invoked_subcommand is not None:
         # ``benchmark rot rescore …`` owns the invocation.
@@ -941,7 +941,7 @@ def benchmark_rot_rescore_cmd(
 ) -> None:
     """Re-classify a saved rot report under the current scorer.
 
-    Free: retrieval is taken as recorded — no store, encoder, or LLM call. The
+    Free: retrieval is taken as recorded, with no store, encoder, or LLM call. The
     output is a complete report of record with ``selection.scorer_version`` set
     to what ran and a first note naming the source and both versions.
     """
@@ -1028,8 +1028,8 @@ def benchmark_floor_harvest_cmd(
     prompts: bool = typer.Option(
         True,
         "--prompts/--no-prompts",
-        help="Also harvest question-shaped sentences the operator typed to the "
-        "agent: a proxy source, reported apart. --no-prompts keeps explicit "
+        help="Harvest question-shaped sentences the operator typed to the agent "
+        "as well: a proxy source, reported apart. --no-prompts keeps explicit "
         "memory queries only.",
     ),
     allow_in_repo: bool = typer.Option(
@@ -1147,7 +1147,7 @@ def benchmark_floor_cmd(  # noqa: PLR0913 — CLI option list is the API
     judge: bool = typer.Option(
         False,
         "--judge",
-        help="Also run the LLM-priced stage: answer every question with the gate "
+        help="Run the LLM-priced stage too: answer every question with the gate "
         "disabled, then judge the answer grounded-and-useful. Estimate-gated.",
     ),
     estimate: bool = typer.Option(
@@ -1160,7 +1160,7 @@ def benchmark_floor_cmd(  # noqa: PLR0913 — CLI option list is the API
         False, "--yes", "-y", help="Skip the confirmation above the call threshold."
     ),
     output: Path | None = typer.Option(
-        None, "--output", "-o", help="Also write the rendered report to this path."
+        None, "--output", "-o", help="Write the rendered report to this path as well."
     ),
     output_format: _Format = typer.Option(
         _Format.table,

{linkedparticles-1.149.0 → linkedparticles-1.151.18}/particles/api/cli/corpus.py

@@ -355,99 +355,58 @@ def corpus_delete_cmd(
     entry_id: str = typer.Argument(..., help="Entry ID (prefix OK)"),
     yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
 ) -> None:
-    """Delete a corpus entry, its snapshots, and all particles sourced from it."""
+    """Delete a corpus entry, its snapshots, and the particles only it supports.
+
+    A particle that another entry also supports is kept, with this entry's
+    source refs removed. When the removed ref was its earliest source, the
+    next-earliest one becomes the age anchor. The delete is recorded as a
+    CORPUS_ENTRY_DELETED event that holds the entry id and counts, not the
+    deleted content.
+    """
     run(_corpus_delete(entry_id, yes))
 
 
 async def _corpus_delete(entry_id_prefix: str, yes: bool) -> None:
-    from sqlalchemy import delete, select
-
     from particles.api.cli._remote import ensure_local
-    from particles.corpus.store import CorpusEntryRow, SnapshotRow, get_entry
-    from particles.store.particle_store import ParticleRow, ProvenanceEdgeRow
-    from particles.store.subject_store import ParticleSubjectRow
+    from particles.corpus.store import get_entry
+    from particles.operations.corpus_delete import delete_entry, plan_entry_deletion
 
     ensure_local("corpus delete")
 
     async with session_scope() as session:
-        if len(entry_id_prefix) < 36:
-            result = await session.execute(
-                select(CorpusEntryRow).where(
-                    CorpusEntryRow.entry_id.like(
-                        f"{escape_like_pattern(entry_id_prefix)}%", escape=LIKE_ESCAPE
-                    )
-                )
-            )
-            row = result.scalar_one_or_none()
-            if row is None:
-                typer.echo(f"Entry {entry_id_prefix!r} not found.", err=True)
-                raise typer.Exit(1)
-            entry_id = row.entry_id
-        else:
-            entry_id = entry_id_prefix
-
+        entry_id = await _resolve_entry_id(session, entry_id_prefix)
         entry = await get_entry(session, entry_id)
         if entry is None:
             typer.echo(f"Entry {entry_id_prefix!r} not found.", err=True)
             raise typer.Exit(1)
 
-        # Count particles to be deleted
-        particle_ids_result = await session.execute(
-            select(ProvenanceEdgeRow.particle_id).where(
-                ProvenanceEdgeRow.corpus_entry_id == entry_id
-            )
-        )
-        particle_ids = list(particle_ids_result.scalars())
+        plan = await plan_entry_deletion(session, entry_id)
+        n_delete = len(plan.decision.to_delete)
+        n_strip = len(plan.decision.to_strip)
+        n_moved = sum(1 for s in plan.decision.to_strip if s.anchor_moved)
 
         label = (entry.uri_r or entry_id).replace("file://", "")
         typer.echo(f"Entry:     {entry_id[:8]}…  {label}")
-        typer.echo(f"Snapshots: {len(entry.snapshots)}")
-        typer.echo(f"Particles: {len(particle_ids)} will be deleted")
+        typer.echo(f"Snapshots: {plan.snapshots}")
+        typer.echo(f"Particles: {n_delete} will be deleted (this entry is their only source)")
+        strip_line = f"           {n_strip} kept, other sources remain; this entry's refs removed"
+        if n_moved:
+            strip_line += f" ({n_moved} with a new earliest source)"
+        typer.echo(strip_line)
 
         if not yes:
             typer.confirm("Delete this entry and all its data?", abort=True)
 
-        # Subjects linked to the doomed particles — captured *before* we drop
-        # the join rows, so afterwards we can re-check each for orphanhood.
-        candidate_subject_ids: set[str] = set()
-        if particle_ids:
-            candidate_subject_ids = set(
-                (
-                    await session.execute(
-                        select(ParticleSubjectRow.subject_id).where(
-                            ParticleSubjectRow.particle_id.in_(particle_ids)
-                        )
-                    )
-                ).scalars()
-            )
-
-        # Delete particles + every index row keyed on them. These tables carry
-        # no FK to ``particles`` (SQLite FK enforcement is off), so they would
-        # otherwise be left dangling.
-        if particle_ids:
-            await session.execute(delete(ParticleRow).where(ParticleRow.id.in_(particle_ids)))
-            await _purge_particle_index_rows(session, particle_ids)
-
-        # Subjects that lost their last link become orphans; drop them and any
-        # synthesis-cache rows keyed on them. A subject still linked to a
-        # surviving particle is left untouched.
-        subj_removed, synth_removed = await _purge_orphan_subjects(session, candidate_subject_ids)
-
-        # Delete provenance edges
-        await session.execute(
-            delete(ProvenanceEdgeRow).where(ProvenanceEdgeRow.corpus_entry_id == entry_id)
-        )
-        # Delete snapshots
-        await session.execute(delete(SnapshotRow).where(SnapshotRow.entry_id == entry_id))
-        # Delete entry
-        await session.execute(delete(CorpusEntryRow).where(CorpusEntryRow.entry_id == entry_id))
+        result = await delete_entry(session, entry_id)
         await session.commit()
 
-    parts = [f"{len(particle_ids)} particles removed"]
-    if subj_removed:
-        parts.append(f"{subj_removed} orphaned subjects")
-    if synth_removed:
-        parts.append(f"{synth_removed} synthesis-cache rows")
+    parts = [f"{result.particles_deleted} particles removed"]
+    if result.particles_stripped:
+        parts.append(f"{result.particles_stripped} kept with refs stripped")
+    if result.subjects_orphaned:
+        parts.append(f"{result.subjects_orphaned} orphaned subjects")
+    if result.synthesis_rows_deleted:
+        parts.append(f"{result.synthesis_rows_deleted} synthesis-cache rows")
     typer.echo(f"Deleted entry {entry_id[:8]}… ({', '.join(parts)}).")
 
 
@@ -555,83 +514,6 @@ async def _corpus_retract(
     )
 
 
-# ---------------------------------------------------------------------------
-# Orphan cleanup — shared by ``corpus delete`` and ``corpus prune-orphans``.
-# None of the index tables (particle_subjects, particle_tag_edges,
-# particle_relations, synthesis_cache) declare a foreign key, and SQLite FK
-# enforcement is off, so deleting particles or subjects elsewhere leaves
-# dangling rows unless they are swept explicitly here.
-# ---------------------------------------------------------------------------
-
-
-async def _purge_particle_index_rows(session: AsyncSession, particle_ids: list[str]) -> None:
-    """Delete every index row keyed on one of ``particle_ids``.
-
-    Sweeps the ``particle_subjects`` join, ``particle_tag_edges``, and
-    ``particle_relations`` (either endpoint). Caller deletes the
-    ``ParticleRow`` rows themselves.
-    """
-    from sqlalchemy import delete, or_
-
-    from particles.store.relation_store import ParticleRelationRow
-    from particles.store.subject_store import ParticleSubjectRow
-    from particles.store.taxonomy_store import ParticleTagEdgeRow
-
-    if not particle_ids:
-        return
-    await session.execute(
-        delete(ParticleSubjectRow).where(ParticleSubjectRow.particle_id.in_(particle_ids))
-    )
-    await session.execute(
-        delete(ParticleTagEdgeRow).where(ParticleTagEdgeRow.particle_id.in_(particle_ids))
-    )
-    await session.execute(
-        delete(ParticleRelationRow).where(
-            or_(
-                ParticleRelationRow.particle_a.in_(particle_ids),
-                ParticleRelationRow.particle_b.in_(particle_ids),
-            )
-        )
-    )
-
-
-async def _purge_orphan_subjects(
-    session: AsyncSession, candidate_ids: set[str] | None
-) -> tuple[int, int]:
-    """Delete subjects with no remaining ``particle_subjects`` link.
-
-    Also drops any ``synthesis_cache`` rows keyed on the removed subjects.
-    Returns ``(subjects_removed, synthesis_rows_removed)``.
-
-    ``candidate_ids`` restricts the orphan check to a known set — the subjects
-    that were linked to a just-deleted entry's particles — so a subject still
-    linked to surviving particles is never touched. Pass ``None`` to scan
-    every subject (the whole-DB ``prune-orphans`` sweep).
-    """
-    from sqlalchemy import delete, select
-    from sqlalchemy.engine import CursorResult
-
-    from particles.store.subject_store import ParticleSubjectRow, SubjectRow
-    from particles.store.synthesis_cache_store import SynthesisCacheRow
-
-    if candidate_ids is not None and not candidate_ids:
-        return (0, 0)
-
-    linked = select(ParticleSubjectRow.subject_id).distinct()
-    stmt = select(SubjectRow.id).where(SubjectRow.id.not_in(linked))
-    if candidate_ids is not None:
-        stmt = stmt.where(SubjectRow.id.in_(candidate_ids))
-    orphan_ids = list((await session.execute(stmt)).scalars())
-    if not orphan_ids:
-        return (0, 0)
-
-    synth_result: CursorResult[None] = await session.execute(  # type: ignore[assignment]
-        delete(SynthesisCacheRow).where(SynthesisCacheRow.subject_id.in_(orphan_ids))
-    )
-    await session.execute(delete(SubjectRow).where(SubjectRow.id.in_(orphan_ids)))
-    return (len(orphan_ids), synth_result.rowcount or 0)
-
-
 @corpus_app.command("prune-orphans")
 def corpus_prune_orphans_cmd(
     yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt"),
@@ -652,6 +534,7 @@ async def _corpus_prune_orphans(yes: bool) -> None:
     from sqlalchemy.engine import CursorResult
 
     from particles.api.cli._remote import ensure_local
+    from particles.operations.corpus_delete import purge_orphan_subjects
     from particles.store.particle_store import ParticleRow
     from particles.store.relation_store import ParticleRelationRow
     from particles.store.subject_store import ParticleSubjectRow, SubjectRow
@@ -711,7 +594,7 @@ async def _corpus_prune_orphans(yes: bool) -> None:
         await session.execute(delete(ParticleRelationRow).where(dangling_rel_q))
         # Orphan-subject removal must run *after* the dangling join rows are
         # gone, so a subject linked only via a now-deleted row is detected.
-        subj_removed, synth_from_subj = await _purge_orphan_subjects(session, None)
+        subj_removed, synth_from_subj = await purge_orphan_subjects(session, None)
         synth_res: CursorResult[None] = await session.execute(  # type: ignore[assignment]
             delete(SynthesisCacheRow).where(dangling_synth_q)
         )
@@ -820,13 +703,9 @@ async def _corpus_refresh(
     entry_id: str | None, force: bool, backfill_cascade: bool, yes: bool
 ) -> None:
     from particles.api.cli._remote import ensure_local
-    from particles.core.schema import WarcRecordType
-    from particles.corpus.fetch import maybe_refetch
-    from particles.corpus.store import (
-        list_refreshable_local_entries,
-        list_snapshots_for_entry,
-        resolve_entry_id,
-    )
+    from particles.corpus.refresh_outcome import RefreshOutcome
+    from particles.corpus.store import list_refreshable_local_entries, resolve_entry_id
+    from particles.operations.corpus_refresh import refresh_entries
 
     if backfill_cascade:
         await _corpus_refresh_backfill(yes)
@@ -853,24 +732,23 @@ async def _corpus_refresh(
             return
 
         changed = unchanged = missing = 0
-        for target_id, _uri in targets:
-            snapshots = await list_snapshots_for_entry(session, target_id)
-            before = max(snapshots, key=lambda s: s.captured_at).snapshot_id if snapshots else None
-            try:
-                snap = await maybe_refetch(session, target_id, force=force)
-            except Exception as exc:  # noqa: BLE001 — one bad source must not stop the sweep
-                typer.echo(f"  {target_id[:8]}  error: {exc}", err=True)
-                await session.rollback()
-                continue
-            if snap is None:
-                missing += 1
-                typer.echo(f"  {target_id[:8]}  missing (source unavailable)")
-            elif snap.snapshot_id == before or snap.warc_record_type is WarcRecordType.REVISIT:
-                unchanged += 1
-            else:
-                changed += 1
-                typer.echo(f"  {target_id[:8]}  changed → snapshot {snap.snapshot_id[:8]} PENDING")
-            await session.commit()
+        async for result in refresh_entries(
+            session, (target_id for target_id, _uri in targets), force=force
+        ):
+            short = result.entry_id[:8]
+            match result.outcome:
+                case None:
+                    typer.echo(f"  {short}  error: {result.error}", err=True)
+                case RefreshOutcome.MISSING:
+                    missing += 1
+                    typer.echo(f"  {short}  missing (source unavailable)")
+                case RefreshOutcome.UNCHANGED_MTIME | RefreshOutcome.UNCHANGED_HASH:
+                    unchanged += 1
+                case RefreshOutcome.CHANGED:
+                    changed += 1
+                    typer.echo(
+                        f"  {short}  changed → snapshot {(result.snapshot_id or '')[:8]} PENDING"
+                    )
 
     typer.echo(
         f"\nChecked {len(targets)} local source(s): {changed} changed, "
@@ -886,7 +764,7 @@ def corpus_fsck_cmd(
         [],
         "--search",
         help=(
-            "Also look for strays under this blob root, the directory holding the "
+            "Look for strays under this blob root too, the directory holding the "
             "two-character shards (repeatable). Nothing is inferred: the audit tells "
             "you what is missing so you can point --search at where you think it went."
         ),

{linkedparticles-1.149.0 → linkedparticles-1.151.18}/particles/api/cli/extractor.py

@@ -1229,7 +1229,7 @@ def extractor_benchmark_validity_cmd(
     Reports the dangerous **wrong-expiry rate**: of the aligned claims whose
     gold is durable (no boundary), the fraction the extractor wrongly assigned a
     ``valid_until`` and thereby set up for silent retirement by the §9.3
-    staleness lint (the headline, the over-eager-expiry risk). Also reports existence
+    staleness lint (the headline, the over-eager-expiry risk). It also reports existence
     precision/recall of correct date-bounded extraction and date accuracy.
     Discovers every validity suite under --suites-dir the extractor is the
     production routing choice for (or runs only --suite). Report-only

{linkedparticles-1.149.0 → linkedparticles-1.151.18}/particles/api/cli/init.py

@@ -115,7 +115,7 @@ def init_claude_code_cmd(
         True,
         "--skills/--no-skills",
         help=(
-            "Also install the shipped agent-onboarding skill files "
+            "Install the shipped agent-onboarding skill files too, "
             "into the harness's skills directory (a Particles-owned subdirectory; "
             "--remove deletes exactly that). Default on: an agent that has the "
             "tools but not the guidance is the gap these close."

{linkedparticles-1.149.0 → linkedparticles-1.151.18}/particles/api/cli/memory.py

@@ -229,7 +229,7 @@ def rescope_cmd(
     A belief is *in view* for a project when one of its sources was harvested
     there, which is read from the `project:` tag on the source's corpus entry.
     Older versions stamped a per-worktree name, or nothing at all. This verb
-    adds the project's real key beside whatever an entry already carries — it
+    adds the project's real key beside whatever an entry already carries. It
     never removes a tag, and running it twice changes nothing.
 
     It reports the two things you need to see: harvested entries it could not
@@ -350,7 +350,7 @@ def widen_cmd(
     judgement, so it is yours to record. The belief and its sources are not
     touched: the widening is a standing statement the read lens consults, and
     `--revoke` withdraws it. There is deliberately no agent-facing way to do
-    this — an agent that could widen its own belief could put it in front of
+    this: an agent that could widen its own belief could put it in front of
     every future session.
     """
     configure_output(verbose, debug, quiet, progress)
@@ -692,7 +692,7 @@ def consolidate_cmd(
         ),
     ),
     output: Path | None = typer.Option(
-        None, "--output", help="Also write the run report as Markdown to FILE."
+        None, "--output", help="Write the run report as Markdown to FILE as well."
     ),
     format_: str = typer.Option(
         "markdown", "--format", help="Terminal format: markdown (default) or json."

{linkedparticles-1.149.0 → linkedparticles-1.151.18}/particles/api/cli/query.py

@@ -68,7 +68,7 @@ def query_cmd(
     include_ancestors: bool = typer.Option(
         False,
         "--include-ancestors",
-        help="Also match particles tagged with a broader ancestor of each --tag "
+        help="Match particles tagged with a broader ancestor of each --tag as well "
         "(up-expansion over taxonomy parent links)",
     ),
     show_particles: bool = typer.Option(

{linkedparticles-1.149.0 → linkedparticles-1.151.18}/particles/benchmark/observer/render.py

@@ -33,7 +33,7 @@ def _metrics_rows(m: ObserverMetrics) -> list[str]:
     ]
     for kind in ("fact", "rule", "own"):
         if kind in m.by_kind:
-            rows.append(f"| In view — `{kind}` lines | {_rate(m.by_kind[kind])} |")
+            rows.append(f"| In view, `{kind}` lines | {_rate(m.by_kind[kind])} |")
     return rows
 
 

linkedparticles-1.151.18/particles/corpus/refresh_outcome.py

@@ -0,0 +1,51 @@
+# SPDX-FileCopyrightText: 2026 The Particles authors
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Classify one :func:`~particles.corpus.fetch.maybe_refetch` result.
+
+The decide half of a refresh, as a pure function over plain values (
+D2). ``particles corpus refresh`` and consolidation pass 0.5 both derive their
+counts from :func:`classify_refresh`. The outcomes are fine-grained, so a report
+that wants one ``unchanged`` total sums the two unchanged outcomes.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+from particles.core.schema import Snapshot, WarcRecordType
+
+
+class RefreshOutcome(StrEnum):
+    """What one re-check of a corpus entry found."""
+
+    MISSING = "missing"
+    """No snapshot came back: the source is unavailable, or the entry is not refetchable."""
+    UNCHANGED_MTIME = "unchanged_mtime"
+    """The latest snapshot came back untouched: a tier-1 short-circuit, before any read."""
+    UNCHANGED_HASH = "unchanged_hash"
+    """A REVISIT was written: the body was read and its hash matched."""
+    CHANGED = "changed"
+    """A new RESPONSE snapshot landed PENDING."""
+
+
+def classify_refresh(before_id: str | None, snap: Snapshot | None) -> RefreshOutcome:
+    """Classify a refetch result against the entry's latest snapshot id before it.
+
+    Args:
+        before_id: The entry's newest snapshot id before the refetch, or None
+            when it had none.
+        snap: What ``maybe_refetch`` returned.
+
+    Returns:
+        The outcome. A returned snapshot whose id equals ``before_id`` is
+        ``UNCHANGED_MTIME`` whatever its record type, since no new row was written.
+    """
+    if snap is None:
+        return RefreshOutcome.MISSING
+    if snap.snapshot_id == before_id:
+        return RefreshOutcome.UNCHANGED_MTIME
+    if snap.warc_record_type is WarcRecordType.REVISIT:
+        return RefreshOutcome.UNCHANGED_HASH
+    return RefreshOutcome.CHANGED