@pentatonic-ai/ai-agent-sdk 0.10.30 → 0.10.32

package/dist/index.cjs

@@ -878,7 +878,7 @@ function fireAndForgetEmit(clientConfig, sessionOpts, messages, result, model) {
 }
 
 // src/telemetry.js
-var VERSION = "0.10.30";
+var VERSION = "0.10.32";
 var TELEMETRY_URL = "https://sdk-telemetry.philip-134.workers.dev";
 function machineId() {
   const raw = typeof process !== "undefined" ? `${process.env?.USER || process.env?.USERNAME || "u"}:${process.platform || "x"}:${process.arch || "x"}` : "browser";

package/dist/index.js

@@ -847,7 +847,7 @@ function fireAndForgetEmit(clientConfig, sessionOpts, messages, result, model) {
 }
 
 // src/telemetry.js
-var VERSION = "0.10.30";
+var VERSION = "0.10.32";
 var TELEMETRY_URL = "https://sdk-telemetry.philip-134.workers.dev";
 function machineId() {
   const raw = typeof process !== "undefined" ? `${process.env?.USER || process.env?.USERNAME || "u"}:${process.platform || "x"}:${process.arch || "x"}` : "browser";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pentatonic-ai/ai-agent-sdk",
-  "version": "0.10.30",
+  "version": "0.10.32",
   "description": "TES SDK — LLM observability and lifecycle tracking via Pentatonic Thing Event System. Track token usage, tool calls, and conversations. Manage things through event-sourced lifecycle stages with AI enrichment and vector search.",
   "type": "module",
   "main": "./dist/index.cjs",

package/packages/memory-engine-v2/compat/server.py

@@ -57,6 +57,8 @@ NV_EMBED_URL = os.environ.get("NV_EMBED_URL", "http://nv-embed:8041/v1/embedding
 NV_EMBED_API_KEY = os.environ.get("NV_EMBED_API_KEY", "")
 NV_EMBED_PROVIDER = os.environ.get("NV_EMBED_PROVIDER", "openai")  # 'openai' | 'pentatonic-gateway'
 EMBED_DIM = int(os.environ.get("EMBED_DIM", "4096"))
+# Window (minutes) over which /health/deep computes the distillation drain rate.
+HEALTH_DRAIN_WINDOW_MIN = int(os.environ.get("HEALTH_DRAIN_WINDOW_MIN", "5"))
 
 COLLECTION_NAME = "evidence"
 
@@ -665,6 +667,31 @@ async def health_deep():
     except Exception as e:
         result["stores"]["org_model"] = {"status": "error", "error": str(e)}
 
+    # distillation drain rate — events distilled per minute over a recent
+    # window, by producer. Surfaces whether the async extractor fleet is keeping
+    # up with ingest (pair with distillation_pending in the counts above). Cheap:
+    # served by idx_event_distillations_producer_time (producer, distilled_at).
+    try:
+        async with _pool.connection() as conn:
+            async with conn.cursor() as cur:
+                await cur.execute(
+                    "SELECT producer, count(*) AS n FROM event_distillations "
+                    "WHERE distilled_at > now() - make_interval(mins => %s) "
+                    "GROUP BY producer",
+                    (HEALTH_DRAIN_WINDOW_MIN,),
+                )
+                rows = await cur.fetchall()
+        by_producer = {r["producer"]: r["n"] for r in rows}
+        total = sum(by_producer.values())
+        result["distillation"] = {
+            "window_min": HEALTH_DRAIN_WINDOW_MIN,
+            "drain_per_min": round(total / HEALTH_DRAIN_WINDOW_MIN, 1),
+            "drained_in_window": total,
+            "by_producer": by_producer,
+        }
+    except Exception as e:
+        result["distillation"] = {"status": "error", "error": str(e)}
+
     # vector-index
     try:
         info = await _qdrant.get_collection(COLLECTION_NAME)

package/packages/memory-engine-v2/extractor-async/worker.py

@@ -153,6 +153,42 @@ MAX_INFLIGHT_BATCHES = int(os.environ.get("MAX_INFLIGHT_BATCHES", "4"))
 # continuous stream of calls instead of per-batch bursts. None until amain runs.
 _STUDENT_SEM: "asyncio.Semaphore | None" = None
 _TEACHER_SEM: "asyncio.Semaphore | None" = None
+
+# Cap on provenance_event_ids array length per node (entity/fact/relationship).
+# UNBOUNDED accretion was the drain-throughput bottleneck: hot nodes re-mentioned
+# thousands of times grew arrays to 50k+ event IDs (~2MB TOASTed), so every
+# subsequent upsert read+rewrote the whole array off disk (16s DataFileRead
+# measured; entities TOAST hit 233GB, relationships 66GB — 2026-07-08). Keep only
+# the most-recent N distinct IDs — provenance drives corroboration counts +
+# citations, and the avg node has ~6 (only a handful of super-nodes exceed this),
+# so 200 preserves all real provenance while bounding the pathological tail.
+# Capping the STORED array is self-healing: the first capped write shrinks a
+# bloated node to N, then its upserts stay cheap.
+PROVENANCE_MAX_EVENT_IDS = int(os.environ.get("PROVENANCE_MAX_EVENT_IDS", "200"))
+
+
+def _cap_prov(existing: str, incoming: str) -> str:
+    """SQL expression: merge the `existing` and `incoming` text[] provenance
+    arrays, dedupe, and keep the PROVENANCE_MAX_EVENT_IDS most-recent IDs (by
+    position — appended IDs are newest), re-ordered oldest→newest to preserve the
+    append convention readers see. Drop-in replacement for the old unbounded
+    `ARRAY(SELECT DISTINCT UNNEST(existing || incoming))`. `incoming` may carry a
+    single %s placeholder; it stays in the same param position."""
+    return (
+        "(SELECT COALESCE(array_agg(ev ORDER BY ord), ARRAY[]::text[]) "
+        "FROM (SELECT ev, max(ord) AS ord "
+        f"FROM unnest(({existing}) || ({incoming})) WITH ORDINALITY AS _pu(ev, ord) "
+        f"GROUP BY ev ORDER BY max(ord) DESC LIMIT {PROVENANCE_MAX_EVENT_IDS}) _pk)"
+    )
+
+
+# Precomputed capped-provenance SQL fragments for each upsert site (built once).
+_PROV_ENT_UPDATE = _cap_prov("provenance_event_ids", "%s::text[]")
+_PROV_ENT_CONFLICT = _cap_prov("entities.provenance_event_ids", "EXCLUDED.provenance_event_ids")
+_PROV_FACT = _cap_prov("facts.provenance_event_ids", "EXCLUDED.provenance_event_ids")
+_PROV_REL = _cap_prov("relationships.provenance_event_ids", "EXCLUDED.provenance_event_ids")
+
+
 # Fraction of student-passing events ALSO sent to the teacher — NOT a quality
 # lever, this is the monitoring + active-learning sample (drift detection and
 # fresh teacher-gold on live traffic). Default conservative-ish 5%.
@@ -1910,7 +1946,7 @@ def upsert_entities(
                     """
                     UPDATE entities SET
                       aliases = ARRAY(SELECT DISTINCT UNNEST(aliases || %s::text[])),
-                      provenance_event_ids = ARRAY(SELECT DISTINCT UNNEST(provenance_event_ids || %s::text[])),
+                      provenance_event_ids = """ + _PROV_ENT_UPDATE + """,
                       -- Merge the org-domain hard key (no-op for the `{}` default
                       -- on non-orgs / unmatched orgs; never clobbers an existing key).
                       attributes = entities.attributes || %s::jsonb,
@@ -1986,9 +2022,7 @@ def upsert_entities(
                       aliases = (
                         SELECT ARRAY(SELECT DISTINCT UNNEST(entities.aliases || EXCLUDED.aliases))
                       ),
-                      provenance_event_ids = (
-                        SELECT ARRAY(SELECT DISTINCT UNNEST(entities.provenance_event_ids || EXCLUDED.provenance_event_ids))
-                      ),
+                      provenance_event_ids = """ + _PROV_ENT_CONFLICT + """,
                       -- merge the org-domain hard key (no-op for `{}`)
                       attributes = entities.attributes || EXCLUDED.attributes,
                       -- re-corroboration can only RAISE salience, never lower it
@@ -2107,11 +2141,7 @@ def upsert_facts(
                   COALESCE(%s, NOW()), %s, %s
                 )
                 ON CONFLICT (id) DO UPDATE SET
-                  provenance_event_ids = (
-                    SELECT ARRAY(SELECT DISTINCT UNNEST(
-                      facts.provenance_event_ids || EXCLUDED.provenance_event_ids
-                    ))
-                  ),
+                  provenance_event_ids = """ + _PROV_FACT + """,
                   salience = GREATEST(facts.salience, EXCLUDED.salience),
                   -- Confidence bumps with each additional independent
                   -- source. The cardinality of the merged provenance
@@ -2222,9 +2252,7 @@ def upsert_relationships(
                 -- distillation + the SEE-490 backfill on merged-entity edges.
                 ON CONFLICT (arena, from_entity_id, to_entity_id, relationship_type) DO UPDATE SET
                   weight = relationships.weight + EXCLUDED.weight,
-                  provenance_event_ids = (
-                    SELECT ARRAY(SELECT DISTINCT UNNEST(relationships.provenance_event_ids || EXCLUDED.provenance_event_ids))
-                  ),
+                  provenance_event_ids = """ + _PROV_REL + """,
                   attributes = relationships.attributes || EXCLUDED.attributes,
                   last_seen = GREATEST(relationships.last_seen, EXCLUDED.last_seen),
                   first_seen = LEAST(relationships.first_seen, EXCLUDED.first_seen)

package/packages/memory-engine-v2/extractor-sync/server.py

@@ -49,6 +49,30 @@ log = logging.getLogger("extractor-sync")
 
 PG_DSN = os.environ.get("PG_DSN", "postgresql://pme:local-dev-pw@org-model:5432/org_model")
 
+# Cap on provenance_event_ids array length. Unbounded accretion bloated the
+# entities table to 249GB (233GB TOAST) — hot nodes grew 50k+-element arrays so
+# every upsert read+rewrote ~2MB off disk (16s DataFileRead, 2026-07-08). Keep
+# only the most-recent N distinct IDs. Byte-identical intent to extractor-async's
+# _cap_prov (kept as a local copy per the sibling-service duplication convention,
+# like confidence.py / source_time.py).
+PROVENANCE_MAX_EVENT_IDS = int(os.environ.get("PROVENANCE_MAX_EVENT_IDS", "200"))
+
+
+def _cap_prov(existing: str, incoming: str) -> str:
+    """Merge `existing`||`incoming` text[] provenance, dedupe, keep the
+    PROVENANCE_MAX_EVENT_IDS most-recent IDs (append order = newest last).
+    Drop-in for the old unbounded `ARRAY(SELECT DISTINCT UNNEST(...))`."""
+    return (
+        "(SELECT COALESCE(array_agg(ev ORDER BY ord), ARRAY[]::text[]) "
+        "FROM (SELECT ev, max(ord) AS ord "
+        f"FROM unnest(({existing}) || ({incoming})) WITH ORDINALITY AS _pu(ev, ord) "
+        f"GROUP BY ev ORDER BY max(ord) DESC LIMIT {PROVENANCE_MAX_EVENT_IDS}) _pk)"
+    )
+
+
+_PROV_ENT_UPDATE = _cap_prov("provenance_event_ids", "%s::text[]")
+_PROV_ENT_CONFLICT = _cap_prov("entities.provenance_event_ids", "EXCLUDED.provenance_event_ids")
+
 # Connection pool. Sized for high-concurrency bursts: with TES at
 # shardCount=8 and BATCH_SIZE=50 in the DO drain, compat's parallel
 # asyncio.gather in /store-batch can fan ~400 simultaneous _extract
@@ -534,7 +558,7 @@ async def _upsert_entities(
                 """
                 UPDATE entities SET
                   aliases = ARRAY(SELECT DISTINCT UNNEST(aliases || %s::text[])),
-                  provenance_event_ids = ARRAY(SELECT DISTINCT UNNEST(provenance_event_ids || %s::text[])),
+                  provenance_event_ids = """ + _PROV_ENT_UPDATE + """,
                   -- Widen the seen-window with this event's SOURCE time,
                   -- not NOW(): newest evidence = newest source time.
                   last_seen = GREATEST(last_seen, COALESCE(%s, NOW())),
@@ -574,9 +598,7 @@ async def _upsert_entities(
                   aliases = (
                     SELECT ARRAY(SELECT DISTINCT UNNEST(entities.aliases || EXCLUDED.aliases))
                   ),
-                  provenance_event_ids = (
-                    SELECT ARRAY(SELECT DISTINCT UNNEST(entities.provenance_event_ids || EXCLUDED.provenance_event_ids))
-                  ),
+                  provenance_event_ids = """ + _PROV_ENT_CONFLICT + """,
                   -- merge the email/domain hard key (no-op for the `{}` default
                   -- on entity types that don't stamp it); never clobbers.
                   attributes = entities.attributes || EXCLUDED.attributes,

package/packages/memory-engine-v2/fusion_drive/merge.py

@@ -17,6 +17,13 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from typing import Any
 
+# Defensive bound on merged provenance arrays. A merge of many fragmented
+# entities could otherwise union thousands of provenance IDs into the master,
+# re-bloating the entities/relationships TOAST that the extractor cap fixes
+# (see extractor-async/worker.py PROVENANCE_MAX_EVENT_IDS). Kept a literal here
+# to preserve this module's no-env/no-clock purity; must match the extractor.
+PROVENANCE_MAX_EVENT_IDS = 200
+
 
 # ── entity fusion plan ───────────────────────────────────────────────
 @dataclass
@@ -75,7 +82,7 @@ def build_entity_merge_plan(
     provenance = _union(
         master.get("provenance_event_ids", []),
         *[l.get("provenance_event_ids", []) for l in losers],
-    )
+    )[:PROVENANCE_MAX_EVENT_IDS]
 
     plan = EntityMergePlan(
         arena=arena,
@@ -112,7 +119,7 @@ def build_entity_merge_plan(
                 "drop": r["id"],
                 "summed_weight": round(keep.get("weight", 1.0) + r.get("weight", 1.0), 4),
                 "provenance": _union(keep.get("provenance_event_ids", []),
-                                     r.get("provenance_event_ids", [])),
+                                     r.get("provenance_event_ids", []))[:PROVENANCE_MAX_EVENT_IDS],
             })
         else:
             by_key[key] = r
@@ -147,7 +154,7 @@ def build_fact_merge_plan(*, arena: str, dup_facts: list[dict]) -> dict | None:
     )
     master, losers = ranked[0], ranked[1:]
     provenance = _union(master.get("provenance_event_ids", []),
-                        *[l.get("provenance_event_ids", []) for l in losers])
+                        *[l.get("provenance_event_ids", []) for l in losers])[:PROVENANCE_MAX_EVENT_IDS]
     return {
         "arena": arena,
         "master_id": master["id"],

package/packages/memory-engine-v2/org-model/migrations/011_event_distillations_time_index.sql

@@ -0,0 +1,26 @@
+-- 011_event_distillations_time_index.sql — time-ordered index for drain-rate
+-- queries over the distillation ledger.
+--
+-- /health/deep surfaces the distillation drain rate (events distilled per
+-- minute, by producer) so we can see whether the async extractor fleet is
+-- keeping up with ingest. That query is a recent-window scan across ALL
+-- producers:
+--
+--   SELECT producer, count(*) FROM event_distillations
+--   WHERE distilled_at > now() - interval '5 minutes' GROUP BY producer;
+--
+-- The existing idx_event_distillations_producer_time is (producer, distilled_at)
+-- — producer-leading, so it cannot serve a cross-producer time-range scan, and
+-- the planner falls back to a Seq Scan (measured 244ms at 420k rows). The ledger
+-- is an append-only, unbounded log growing ~80k rows/day, so that scan degrades
+-- linearly. This time-leading index makes the drain query an index range scan
+-- (producer trails so the GROUP BY is covered) and keeps it flat as the ledger
+-- grows. Also serves any other "recent distillations" time-range query.
+--
+-- On an already-initialised prod DB (migrations mount at
+-- /docker-entrypoint-initdb.d and only run on a fresh volume) apply this
+-- manually with CREATE INDEX CONCURRENTLY to avoid locking the ledger against
+-- live writes.
+
+CREATE INDEX IF NOT EXISTS idx_event_distillations_distilled_at
+  ON event_distillations (distilled_at DESC, producer);

package/packages/memory-engine-v2/scripts/cap_provenance.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""cap_provenance.py — one-time truncation of over-long provenance_event_ids
+arrays on the graph PG (org_model).
+
+Unbounded provenance accretion bloated `entities` to 249GB (233GB TOAST) and
+`relationships` to 72GB (66GB TOAST): a handful of hot nodes grew arrays to
+50k+ event IDs (~2MB TOASTed), so every upsert read+rewrote the whole array off
+disk — a 16s DataFileRead per update, which was THE distillation drain-throughput
+bottleneck (2026-07-08). The extractor cap (worker.py / server.py
+PROVENANCE_MAX_EVENT_IDS) stops NEW growth; this script shrinks the arrays that
+are ALREADY over the cap so their next upsert is cheap immediately, rather than
+waiting for each hot node to be re-mentioned.
+
+It keeps the most-recent CAP distinct IDs (same recency-preserving expression as
+the extractor write path). Runs in bounded batches with a commit per batch so it
+never holds a long lock against live distillation, and is fully idempotent
+(re-running skips already-capped rows via the cardinality guard).
+
+DRY-RUN by default (reports how many rows would be capped, writes nothing).
+Pass --apply to write.
+
+  # in the extractor-async container (has psycopg + PG_DSN):
+  python3 cap_provenance.py --table entities --apply
+  python3 cap_provenance.py --table relationships --apply
+
+Disk reclaim: truncation turns the old 2MB array versions into dead TOAST
+tuples. autovacuum frees them for REUSE (so the table stops growing) but does
+NOT shrink the file. To return the ~299GB to disk, run VACUUM FULL (locks) or
+pg_repack (online) in a maintenance window — non-urgent; performance recovers
+as soon as the live arrays are small.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import time
+
+import psycopg
+
+# Same recency-preserving cap as the extractor write path (worker.py._cap_prov):
+# dedupe existing, keep the CAP most-recent by position, re-order oldest→newest.
+_CAP_SQL = (
+    "(SELECT COALESCE(array_agg(ev ORDER BY ord), ARRAY[]::text[]) "
+    "FROM (SELECT ev, max(ord) AS ord "
+    "FROM unnest(provenance_event_ids) WITH ORDINALITY AS _pu(ev, ord) "
+    "GROUP BY ev ORDER BY max(ord) DESC LIMIT %(cap)s) _pk)"
+)
+
+ALLOWED_TABLES = {"entities", "facts", "relationships"}
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--table", required=True, choices=sorted(ALLOWED_TABLES))
+    ap.add_argument("--cap", type=int, default=int(os.environ.get("PROVENANCE_MAX_EVENT_IDS", "200")))
+    ap.add_argument("--batch", type=int, default=200, help="ids updated per commit")
+    ap.add_argument("--apply", action="store_true", help="write (default: dry-run)")
+    args = ap.parse_args()
+
+    # choices= already guards this; belt-and-braces since the table name is
+    # interpolated into DDL-ish SQL (can't be a bound parameter).
+    if args.table not in ALLOWED_TABLES:
+        print(f"refusing unknown table {args.table!r}", file=sys.stderr)
+        return 2
+    tbl = args.table
+
+    dsn = os.environ["PG_DSN"]
+    with psycopg.connect(dsn, autocommit=True) as conn:
+        over = conn.execute(
+            f"SELECT count(*) FROM {tbl} WHERE cardinality(provenance_event_ids) > %s",
+            (args.cap,),
+        ).fetchone()[0]
+        mx = conn.execute(
+            f"SELECT COALESCE(max(cardinality(provenance_event_ids)), 0) FROM {tbl}"
+        ).fetchone()[0]
+        print(f"{tbl}: {over} row(s) over cap={args.cap} (current max cardinality={mx})")
+        if not args.apply:
+            print("dry-run — pass --apply to truncate")
+            return 0
+        if over == 0:
+            print("nothing to do")
+            return 0
+
+        ids = [
+            r[0]
+            for r in conn.execute(
+                f"SELECT id FROM {tbl} WHERE cardinality(provenance_event_ids) > %s",
+                (args.cap,),
+            ).fetchall()
+        ]
+        total = len(ids)
+        done = 0
+        t0 = time.monotonic()
+        for i in range(0, total, args.batch):
+            chunk = ids[i : i + args.batch]
+            # Re-check cardinality in the WHERE so a concurrent write that already
+            # shrank a row is skipped (idempotent, no wasted rewrite).
+            conn.execute(
+                f"UPDATE {tbl} SET provenance_event_ids = {_CAP_SQL} "
+                f"WHERE id = ANY(%(ids)s) AND cardinality(provenance_event_ids) > %(cap)s",
+                {"ids": chunk, "cap": args.cap},
+            )
+            done += len(chunk)
+            print(f"  capped {done}/{total} ({time.monotonic()-t0:.0f}s)", flush=True)
+
+        mx2 = conn.execute(
+            f"SELECT COALESCE(max(cardinality(provenance_event_ids)), 0) FROM {tbl}"
+        ).fetchone()[0]
+        print(f"done: {total} row(s) capped; max cardinality now {mx2} (<= {args.cap})")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/packages/memory-engine-v2/scripts/prune_distillation_queue.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""prune_distillation_queue.py — batched prune of old terminal-state rows from
+distillation_queue.
+
+The queue accumulates one row per distillation ATTEMPT and never prunes: done
+rows pile up (992k of ~1.08M rows measured 2026-07-09), and the redistill
+gardener inserts a fresh row per re-distill (no unique constraint on event_id).
+This bloats idx_distillation_status, so once the workers got fast (after the
+provenance cap) every `claim_next_batch` scan and every mark-done UPDATE started
+taking 10-12s — the queue became the next drain bottleneck.
+
+A `done` row's ONLY consumer is the ingest idempotency guard in
+_enqueue_distillation (`NOT EXISTS ... status IN ('pending','claimed','done')`),
+which stops a RE-DELIVERED event being distilled twice. Re-delivery only happens
+for recent events (ingest retries / DLQ replays), so done rows older than a
+safety window are pure tombstones. The redistill gardener does NOT read done rows
+(its "already queued" guard checks only pending/claimed; its "already clean" gate
+reads distillation_traces + event_distillations) — verified 2026-07-09. So
+pruning old terminal rows is safe and does not trigger re-distillation.
+
+Deletes in bounded batches (commit per batch) so it never holds a long lock or a
+huge transaction against live distillation / replication. Idempotent + resumable.
+
+DRY-RUN by default (reports how many rows match, writes nothing). --apply to delete.
+
+  python3 prune_distillation_queue.py --older-than-days 14            # dry-run
+  python3 prune_distillation_queue.py --older-than-days 14 --apply
+
+Only 'done' by default. 'failed' rows are kept (few; useful for investigation)
+unless --include-failed. After a large prune, plain autovacuum reclaims the space
+for reuse (table stops growing); returning it to disk needs VACUUM/pg_repack.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import time
+
+import psycopg
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--older-than-days", type=int, default=14,
+                    help="prune terminal rows whose completed_at (or enqueued_at) is older than this")
+    ap.add_argument("--batch", type=int, default=10000, help="rows deleted per commit")
+    ap.add_argument("--include-failed", action="store_true",
+                    help="also prune old 'failed' rows (default: 'done' only)")
+    ap.add_argument("--apply", action="store_true", help="delete (default: dry-run)")
+    args = ap.parse_args()
+
+    statuses = ["done"] + (["failed"] if args.include_failed else [])
+    # age is measured on completion time, falling back to enqueue time for legacy
+    # rows written before completed_at existed.
+    where = (
+        "status = ANY(%(statuses)s) "
+        "AND COALESCE(completed_at, enqueued_at) < now() - make_interval(days => %(days)s)"
+    )
+    params = {"statuses": statuses, "days": args.older_than_days}
+
+    with psycopg.connect(os.environ["PG_DSN"], autocommit=True) as conn:
+        total = conn.execute(
+            f"SELECT count(*) FROM distillation_queue WHERE {where}", params
+        ).fetchone()[0]
+        overall = conn.execute("SELECT count(*) FROM distillation_queue").fetchone()[0]
+        print(f"matched {total} prunable row(s) (statuses={statuses}, "
+              f"older_than={args.older_than_days}d) of {overall} total")
+        if not args.apply:
+            print("dry-run — pass --apply to delete")
+            return 0
+        if total == 0:
+            print("nothing to prune")
+            return 0
+
+        deleted = 0
+        t0 = time.monotonic()
+        while True:
+            # Delete by PK from a bounded id subset so each statement is a small,
+            # index-driven batch — never a full-table lock.
+            n = conn.execute(
+                f"DELETE FROM distillation_queue WHERE id IN "
+                f"(SELECT id FROM distillation_queue WHERE {where} LIMIT %(batch)s)",
+                {**params, "batch": args.batch},
+            ).rowcount
+            deleted += n
+            print(f"  deleted {deleted}/{total} ({time.monotonic()-t0:.0f}s)", flush=True)
+            if n == 0:
+                break
+
+        remaining = conn.execute("SELECT count(*) FROM distillation_queue").fetchone()[0]
+        print(f"done: pruned {deleted} row(s); distillation_queue now {remaining} rows")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())