@geravant/sinain 1.19.0 → 1.22.0

package/sinain-memory/page_renderer.py

@@ -0,0 +1,447 @@
+#!/usr/bin/env python3
+"""Page Renderer — synthesize a Confluence-style page for an entity.
+
+Given an entity_id, loads top-K facts from the triplestore, calls an LLM to
+group them into themed sections with a summary, and emits validated JSON.
+
+Output schema:
+    {
+      "entity": "entity:citibank",
+      "tx_watermark": 14823,
+      "fact_count": 247,
+      "facts_used": 247,
+      "summary": "Citibank is …",
+      "sections": [
+        {
+          "heading": "Key People",
+          "bullets": [
+            { "fact_id": "fact:citibank-cto-17yrs",
+              "text": "CTO has 17 yrs tenure",
+              "confidence": 0.92,
+              "domain": "people",
+              "first_seen": "2026-04-12" }
+          ]
+        }
+      ],
+      "stats": { "tokens_in": 18420, "tokens_out": 1380, "dropped_bullets": 0 }
+    }
+
+Hallucinated fact_ids (in LLM output but not in input) are dropped with a
+count in stats.dropped_bullets — same defensive pattern as
+knowledge_integrator.py.
+
+Usage:
+    python3 page_renderer.py --db memory/knowledge-graph.db \
+        --entity entity:citibank [--max-facts 1000]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from common import LLMError, call_llm_with_fallback, extract_json
+
+
+SYSTEM_PROMPT = """\
+You are organizing knowledge into a Confluence-style page about a specific entity.
+INPUT: a list of facts each with a stable fact_id, value, confidence, domain, and first_seen.
+OUTPUT: JSON matching the schema below.
+
+RULES:
+- Group facts into 2 to 8 themed sections.
+- Section ordering preference: Overview → People → Projects/Work → Decisions → Open Questions → Recent Activity. Only include sections that fit the available facts.
+- EVERY bullet MUST reference a real fact_id from the input list. Do not invent fact_ids.
+- Each bullet's "text" is at most 140 characters, present-tense, plain English. Rewrite the fact for readability — do NOT just quote it verbatim if it can be tighter.
+- The "summary" is 2 to 4 sentences synthesizing the entity at a glance. Cite no fact_ids in the summary.
+- If facts contradict, prefer the higher-confidence fact and note the disagreement in the section's optional "notes" field.
+- If the entity has very few facts (<5), produce one "Overview" section with all of them.
+
+OUTPUT ONLY a JSON object, no other text:
+{
+  "summary": "2-4 sentence summary",
+  "sections": [
+    {
+      "heading": "Section title",
+      "bullets": [
+        { "fact_id": "fact:...", "text": "...", "confidence": 0.0 }
+      ],
+      "notes": "optional: contradictions or caveats"
+    }
+  ]
+}
+"""
+
+
+def load_entity_facts(db_path: str, entity_id: str, max_facts: int) -> tuple[list[dict], int]:
+    """Load facts for an entity. Returns (facts, tx_watermark).
+
+    Resolution strategy:
+      1. If entity_id starts with `entity:` — find all facts referencing it
+         via (attribute='entity', value=entity_id, value_type='ref'),
+         then return their full attribute sets.
+      2. If entity_id starts with `fact:` — return its own attributes as a
+         single-fact "page" (the fact IS the page).
+      3. Otherwise — try entity:<slug> first, then fall back to all fact:<slug>-*.
+    """
+    from triplestore import TripleStore
+
+    store = TripleStore(db_path)
+    fact_ids: list[str] = []
+
+    if entity_id.startswith("fact:"):
+        fact_ids = [entity_id]
+    elif entity_id.startswith("entity:"):
+        # Find ANY incoming ref (any attribute), matching the same broad
+        # predicate that graph_children uses. Filtering to attribute='entity'
+        # was too narrow — real data references entities via many attribute
+        # names (related_to, parent_org, employed_by, etc.).
+        rows = store._conn.execute(
+            """SELECT DISTINCT entity_id FROM triples
+               WHERE value = ? AND value_type = 'ref' AND retracted = 0
+               LIMIT ?""",
+            (entity_id, max_facts),
+        ).fetchall()
+        fact_ids = [r["entity_id"] for r in rows]
+        # Some installs store the entity-pointer as value_type='string' (the
+        # slug, not a typed ref). Match those too via the slugified entity name
+        # against the 'entity' attribute (the most common holder for that
+        # legacy shape).
+        slug_part = entity_id.split(":", 1)[1] if ":" in entity_id else entity_id
+        legacy_rows = store._conn.execute(
+            """SELECT DISTINCT entity_id FROM triples
+               WHERE attribute = 'entity' AND value = ?
+                 AND value_type = 'string' AND retracted = 0
+               LIMIT ?""",
+            (slug_part, max_facts),
+        ).fetchall()
+        for r in legacy_rows:
+            if r["entity_id"] not in fact_ids:
+                fact_ids.append(r["entity_id"])
+        # Always include the entity itself's own attributes as a "self" fact.
+        self_attrs_count = store._conn.execute(
+            "SELECT COUNT(*) AS n FROM triples WHERE entity_id = ? AND retracted = 0",
+            (entity_id,),
+        ).fetchone()["n"]
+        if self_attrs_count > 0:
+            fact_ids.insert(0, entity_id)
+        fact_ids = fact_ids[:max_facts]
+    else:
+        # Bare slug — try entity: first, then fact: prefix scan, then
+        # broader substring match across both prefixes (handles cases where
+        # the slug is a fragment of the actual entity_id).
+        eid = f"entity:{entity_id}"
+        exists = store._conn.execute(
+            "SELECT 1 FROM triples WHERE entity_id = ? AND retracted = 0 LIMIT 1",
+            (eid,),
+        ).fetchone()
+        if exists:
+            return load_entity_facts(db_path, eid, max_facts)
+        # Try fact:<slug>* (prefix), then *<slug>* (substring) across both prefixes.
+        rows = store._conn.execute(
+            """SELECT DISTINCT entity_id FROM triples
+               WHERE entity_id LIKE ? AND retracted = 0
+               LIMIT ?""",
+            (f"fact:{entity_id}%", max_facts),
+        ).fetchall()
+        fact_ids = [r["entity_id"] for r in rows]
+        if not fact_ids:
+            rows = store._conn.execute(
+                """SELECT DISTINCT entity_id FROM triples
+                   WHERE (entity_id LIKE ? OR entity_id LIKE ?) AND retracted = 0
+                   LIMIT ?""",
+                (f"fact:%{entity_id}%", f"entity:%{entity_id}%", max_facts),
+            ).fetchall()
+            fact_ids = [r["entity_id"] for r in rows]
+
+    # Load full attribute sets for each fact
+    facts: list[dict] = []
+    tx_watermark = 0
+    for fid in fact_ids:
+        attrs = store.entity(fid)
+        if not attrs:
+            continue
+        # Compute tx_watermark across all triples for this fact
+        max_tx_row = store._conn.execute(
+            "SELECT MAX(tx_id) AS m FROM triples WHERE entity_id = ? AND retracted = 0",
+            (fid,),
+        ).fetchone()
+        if max_tx_row and max_tx_row["m"] is not None:
+            tx_watermark = max(tx_watermark, max_tx_row["m"])
+
+        fact = {"fact_id": fid}
+        for attr, values in attrs.items():
+            v = values[0] if len(values) == 1 else values
+            if attr == "tag":
+                fact["tags"] = values
+            else:
+                fact[attr] = v
+        # Coerce confidence to float
+        try:
+            fact["confidence"] = float(fact.get("confidence", 0.5))
+        except (ValueError, TypeError):
+            fact["confidence"] = 0.5
+        facts.append(fact)
+
+    store.close()
+
+    # Sort by composite score: confidence * recency-bonus
+    facts.sort(key=lambda f: (
+        -float(f.get("confidence", 0.5)),
+        f.get("first_seen", ""),
+    ))
+    return facts[:max_facts], tx_watermark
+
+
+def build_user_prompt(entity_id: str, facts: list[dict]) -> str:
+    """Compact representation for the LLM. Strips noise, keeps essential fields."""
+    parts = [f"Entity: {entity_id}", f"Total facts: {len(facts)}", "", "Facts:"]
+    for f in facts:
+        fid = f.get("fact_id", "?")
+        value = (f.get("value") or "").strip().replace("\n", " ")[:300]
+        conf = f.get("confidence", "?")
+        domain = f.get("domain", "")
+        first_seen = f.get("first_seen", "")[:10]  # YYYY-MM-DD
+        tags = ",".join(f.get("tags", [])[:5]) if f.get("tags") else ""
+        meta_bits = []
+        if domain: meta_bits.append(f"domain={domain}")
+        if first_seen: meta_bits.append(f"first_seen={first_seen}")
+        if tags: meta_bits.append(f"tags={tags}")
+        meta = " | ".join(meta_bits)
+        parts.append(f"- [{fid}] (conf={conf}{', ' + meta if meta else ''}): {value}")
+    return "\n".join(parts)
+
+
+def render_page(db_path: str, entity_id: str, max_facts: int = 1000) -> dict:
+    facts, tx_watermark = load_entity_facts(db_path, entity_id, max_facts)
+    fact_count_total = len(facts)
+
+    if not facts:
+        return {
+            "entity": entity_id,
+            "tx_watermark": tx_watermark,
+            "fact_count": 0,
+            "facts_used": 0,
+            "summary": "No knowledge captured for this entity yet.",
+            "sections": [],
+            "stats": {"tokens_in": 0, "tokens_out": 0, "dropped_bullets": 0,
+                      "from_cache": False},
+        }
+
+    # Single-fact short-circuit (no LLM needed)
+    if fact_count_total == 1:
+        f = facts[0]
+        return {
+            "entity": entity_id,
+            "tx_watermark": tx_watermark,
+            "fact_count": 1,
+            "facts_used": 1,
+            "summary": (f.get("value") or "")[:200],
+            "sections": [{
+                "heading": "Overview",
+                "bullets": [{
+                    "fact_id": f["fact_id"],
+                    "text": (f.get("value") or "")[:140],
+                    "confidence": f.get("confidence", 0.5),
+                    "domain": f.get("domain"),
+                    "first_seen": f.get("first_seen"),
+                }],
+            }],
+            "stats": {"tokens_in": 0, "tokens_out": 0, "dropped_bullets": 0,
+                      "from_cache": False},
+        }
+
+    # Multi-fact: LLM rendering
+    user_prompt = build_user_prompt(entity_id, facts)
+
+    try:
+        raw = call_llm_with_fallback(
+            SYSTEM_PROMPT, user_prompt, script="page_renderer",
+            json_mode=True, retries=1,
+        )
+        parsed = extract_json(raw)
+    except Exception as e:
+        # Catch broad — covers LLMError, ValueError, missing API key
+        # (RuntimeError), JSON parse errors, network errors, etc. The web UI
+        # always wants a renderable response; degraded > broken.
+        sys.stderr.write(f"page_renderer LLM failed: {e}\n")
+        return _fallback_page(entity_id, facts, tx_watermark, error=str(e))
+
+    if not isinstance(parsed, dict):
+        return _fallback_page(entity_id, facts, tx_watermark, error="LLM did not return object")
+
+    # Validate fact_ids — drop hallucinated ones
+    valid_fids = {f["fact_id"] for f in facts}
+    fact_meta = {f["fact_id"]: f for f in facts}
+    sections_in = parsed.get("sections", []) or []
+    sections_out: list[dict] = []
+    dropped = 0
+
+    for sec in sections_in:
+        if not isinstance(sec, dict): continue
+        heading = (sec.get("heading") or "").strip()[:80]
+        if not heading: continue
+        bullets_in = sec.get("bullets", []) or []
+        bullets_out: list[dict] = []
+        for b in bullets_in:
+            if not isinstance(b, dict): continue
+            fid = b.get("fact_id")
+            if not fid or fid not in valid_fids:
+                dropped += 1
+                continue
+            meta = fact_meta[fid]
+            bullets_out.append({
+                "fact_id": fid,
+                "text": (b.get("text") or meta.get("value") or "")[:200],
+                "confidence": meta.get("confidence", 0.5),
+                "domain": meta.get("domain"),
+                "first_seen": meta.get("first_seen"),
+            })
+        if bullets_out:
+            sec_out = {"heading": heading, "bullets": bullets_out}
+            if sec.get("notes"):
+                sec_out["notes"] = str(sec["notes"])[:300]
+            sections_out.append(sec_out)
+
+    summary = (parsed.get("summary") or "").strip()[:1000]
+    if not summary:
+        summary = f"Knowledge about {entity_id}: {fact_count_total} facts."
+
+    return {
+        "entity": entity_id,
+        "tx_watermark": tx_watermark,
+        "fact_count": fact_count_total,
+        "facts_used": fact_count_total - dropped,
+        "summary": summary,
+        "sections": sections_out,
+        "stats": {
+            "tokens_in": 0,  # tracked in stderr; aggregating here would require parser
+            "tokens_out": 0,
+            "dropped_bullets": dropped,
+            "from_cache": False,
+        },
+    }
+
+
+def _fallback_page(entity_id: str, facts: list[dict], tx_watermark: int, error: str = "") -> dict:
+    """Ungrouped fallback when LLM fails or returns garbage."""
+    bullets = [{
+        "fact_id": f["fact_id"],
+        "text": (f.get("value") or "")[:140],
+        "confidence": f.get("confidence", 0.5),
+        "domain": f.get("domain"),
+        "first_seen": f.get("first_seen"),
+    } for f in facts]
+    return {
+        "entity": entity_id,
+        "tx_watermark": tx_watermark,
+        "fact_count": len(facts),
+        "facts_used": len(facts),
+        "summary": f"Knowledge about {entity_id} ({len(facts)} facts). LLM rendering unavailable.",
+        "sections": [{"heading": "All Facts", "bullets": bullets}],
+        "stats": {"tokens_in": 0, "tokens_out": 0, "dropped_bullets": 0,
+                  "from_cache": False, "fallback": True, "error": error[:200]},
+    }
+
+
+def lookup_cache(web_db_path: str, entity_id: str, tx_watermark: int) -> dict | None:
+    """Read page_cache row matching (entity, tx_watermark). Returns parsed JSON or None."""
+    import sqlite3
+    if not Path(web_db_path).exists():
+        return None
+    try:
+        conn = sqlite3.connect(web_db_path)
+        conn.row_factory = sqlite3.Row
+        row = conn.execute(
+            "SELECT page_json, generated_at FROM page_cache WHERE entity_id = ? AND tx_watermark = ?",
+            (entity_id, tx_watermark),
+        ).fetchone()
+        conn.close()
+        if row:
+            page = json.loads(row["page_json"])
+            page.setdefault("stats", {})["from_cache"] = True
+            page["generated_at"] = row["generated_at"]
+            return page
+    except Exception as e:
+        sys.stderr.write(f"page_renderer cache lookup failed: {e}\n")
+    return None
+
+
+def write_cache(web_db_path: str, entity_id: str, page: dict) -> None:
+    """Persist a freshly-rendered page to web.db.page_cache."""
+    import sqlite3
+    import time
+    try:
+        conn = sqlite3.connect(web_db_path)
+        stats = page.get("stats", {})
+        conn.execute(
+            """INSERT OR REPLACE INTO page_cache
+               (entity_id, tx_watermark, page_json, generated_at, tokens_in, tokens_out, cost_usd)
+               VALUES (?, ?, ?, ?, ?, ?, ?)""",
+            (
+                entity_id,
+                page.get("tx_watermark", 0),
+                json.dumps(page, ensure_ascii=False),
+                int(time.time() * 1000),
+                stats.get("tokens_in"),
+                stats.get("tokens_out"),
+                stats.get("cost_usd"),
+            ),
+        )
+        conn.commit()
+        conn.close()
+    except Exception as e:
+        sys.stderr.write(f"page_renderer cache write failed: {e}\n")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Page Renderer")
+    parser.add_argument("--db", required=True, help="Path to knowledge-graph.db")
+    parser.add_argument("--entity", required=True, help="Entity id (entity:* or fact:* or bare slug)")
+    parser.add_argument("--max-facts", type=int, default=1000, help="Max facts to consider")
+    parser.add_argument("--web-db", default=None,
+                        help="Path to web.db for page cache (optional). If provided, hits and writes cache.")
+    parser.add_argument("--refresh", action="store_true",
+                        help="Bypass cache and always re-render via LLM.")
+    args = parser.parse_args()
+
+    if not Path(args.db).exists():
+        print(json.dumps({"error": f"db not found: {args.db}"}))
+        sys.exit(1)
+
+    # Determine tx_watermark cheaply for the cache key, before we commit to LLM.
+    facts, tx_watermark = load_entity_facts(args.db, args.entity, args.max_facts)
+
+    # Cache hit fast-path
+    if args.web_db and not args.refresh:
+        cached = lookup_cache(args.web_db, args.entity, tx_watermark)
+        if cached:
+            print(json.dumps(cached, ensure_ascii=False))
+            return
+
+    # Render (uses already-loaded facts via a thin reuse path)
+    if not facts:
+        page = {
+            "entity": args.entity,
+            "tx_watermark": tx_watermark,
+            "fact_count": 0,
+            "facts_used": 0,
+            "summary": "No knowledge captured for this entity yet.",
+            "sections": [],
+            "stats": {"tokens_in": 0, "tokens_out": 0, "dropped_bullets": 0, "from_cache": False},
+        }
+    else:
+        page = render_page(args.db, args.entity, max_facts=args.max_facts)
+        # render_page reloads facts internally; the load above is duplicated. Keep
+        # the cleaner separation rather than threading state — the second load
+        # hits the in-process SQLite page cache, so the cost is negligible.
+
+    if args.web_db and page.get("fact_count", 0) > 0:
+        write_cache(args.web_db, args.entity, page)
+
+    print(json.dumps(page, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

package/sinain-memory/retract.py

@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+"""Fact retraction (soft-delete) for the web UI.
+
+The triplestore already supports retraction via store.retract_triple() —
+this script is the user-initiated equivalent of what knowledge_integrator
+does automatically. The new ingredients are:
+
+  1. Audit triples (retracted_reason, retracted_by) so the WHY survives.
+  2. Pre-retraction snapshot saved to web.db.retraction_undo, single-use,
+     10-minute TTL — gives the UI a real "undo" button.
+
+Soft delete: rows stay; retracted=1 + retracted_tx + valid_to are set.
+Bi-temporal queries (entity_as_of) still see the fact at past tx_ids.
+Physical removal only happens via gc_retracted_triples (off by default).
+
+Usage:
+    python3 retract.py --retract --db <db> --web-db <web.db> \
+        --fact-id fact:foo [--reason "..."] [--actor "..."]
+
+    python3 retract.py --restore --db <db> --web-db <web.db> \
+        --fact-id fact:foo --undo-token <token>
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import secrets
+import sqlite3
+import sys
+import time
+from pathlib import Path
+
+UNDO_TTL_MS = 10 * 60 * 1000  # 10 minutes
+
+
+def snapshot_triples(store, fact_id: str) -> list[dict]:
+    """Capture every active triple for a fact entity for restore. Includes
+    value_type so re-asserts preserve string-vs-ref semantics."""
+    rows = store._conn.execute(
+        """SELECT attribute, value, value_type, tx_id, created_at
+           FROM triples
+           WHERE entity_id = ? AND retracted = 0""",
+        (fact_id,),
+    ).fetchall()
+    return [
+        {
+            "attribute": r["attribute"],
+            "value": r["value"],
+            "value_type": r["value_type"],
+            "original_tx_id": r["tx_id"],
+            "original_created_at": r["created_at"],
+        }
+        for r in rows
+    ]
+
+
+def retract_fact(db_path: str, web_db_path: str, fact_id: str,
+                 reason: str | None, actor: str | None,
+                 source_entity: str | None = None) -> dict:
+    """Retract all triples for a fact entity + persist undo snapshot."""
+    from triplestore import TripleStore
+
+    store = TripleStore(db_path)
+    snapshot = snapshot_triples(store, fact_id)
+    if not snapshot:
+        store.close()
+        return {"ok": False, "error": "fact not found or already retracted",
+                "fact_id": fact_id}
+
+    metadata = {"actor": actor, "reason": reason, "source": "web-ui"}
+    tx_id = store.begin_tx(source="web-ui-retract",
+                           metadata={k: v for k, v in metadata.items() if v})
+
+    # Retract every active triple
+    triples_retracted = 0
+    for t in snapshot:
+        triples_retracted += store.retract_triple(
+            tx_id, fact_id, t["attribute"], t["value"],
+        )
+
+    # Audit triples — these are NEW assertions ABOUT the retraction event
+    if reason:
+        store.assert_triple(tx_id, fact_id, "retracted_reason", reason, "string")
+    if actor:
+        store.assert_triple(tx_id, fact_id, "retracted_by", actor, "string")
+
+    store.close()
+
+    # Persist undo snapshot
+    token = secrets.token_hex(16)
+    now_ms = int(time.time() * 1000)
+    expires_at = now_ms + UNDO_TTL_MS
+
+    if Path(web_db_path).exists():
+        try:
+            conn = sqlite3.connect(web_db_path)
+            conn.execute(
+                """INSERT INTO retraction_undo
+                   (token, fact_id, snapshot_json, retracted_tx,
+                    reason, actor, created_at, expires_at)
+                   VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
+                (token, fact_id, json.dumps(snapshot),
+                 tx_id, reason, actor, now_ms, expires_at),
+            )
+            conn.execute(
+                """INSERT INTO retraction_log
+                   (ts, fact_id, reason, actor, source_entity)
+                   VALUES (?, ?, ?, ?, ?)""",
+                (now_ms, fact_id, reason, actor, source_entity),
+            )
+            conn.commit()
+            conn.close()
+        except Exception as e:
+            sys.stderr.write(f"undo persist failed: {e}\n")
+
+    return {
+        "ok": True,
+        "fact_id": fact_id,
+        "retracted": True,
+        "retracted_tx": tx_id,
+        "triples_retracted": triples_retracted,
+        "undo_token": token,
+        "expires_at": expires_at,
+    }
+
+
+def restore_fact(db_path: str, web_db_path: str, fact_id: str,
+                 undo_token: str) -> dict:
+    """Re-assert a previously retracted fact from the undo snapshot."""
+    from triplestore import TripleStore
+
+    if not Path(web_db_path).exists():
+        return {"ok": False, "error": "web.db not available"}
+
+    conn = sqlite3.connect(web_db_path)
+    conn.row_factory = sqlite3.Row
+    row = conn.execute(
+        "SELECT * FROM retraction_undo WHERE token = ? AND fact_id = ?",
+        (undo_token, fact_id),
+    ).fetchone()
+
+    if not row:
+        conn.close()
+        return {"ok": False, "error": "undo token not found"}
+    if row["consumed_at"] is not None:
+        conn.close()
+        return {"ok": False, "error": "undo token already consumed"}
+    if row["expires_at"] < int(time.time() * 1000):
+        conn.close()
+        return {"ok": False, "error": "undo token expired"}
+
+    original_retracted_tx = row["retracted_tx"]
+
+    store = TripleStore(db_path)
+    tx_id = store.begin_tx(source="web-ui-restore",
+                           metadata={"undo_token": undo_token,
+                                     "reverses_tx": original_retracted_tx})
+
+    # Un-retract: flip retracted=0 on triples that were closed by the original
+    # retraction tx. Avoids creating duplicate triples — the originals come back
+    # with their original tx_ids and created_at intact, preserving bi-temporal
+    # history.
+    cur = store._conn.execute(
+        """UPDATE triples SET retracted = 0, retracted_tx = NULL, valid_to = NULL
+           WHERE entity_id = ? AND retracted_tx = ?""",
+        (fact_id, original_retracted_tx),
+    )
+    triples_restored = cur.rowcount
+
+    # Also retract the audit triples we wrote during retraction so they don't
+    # linger as active facts on the restored entity.
+    store.retract_triple(tx_id, fact_id, "retracted_reason")
+    store.retract_triple(tx_id, fact_id, "retracted_by")
+
+    store._conn.commit()
+    store.close()
+
+    # Mark consumed + log undo
+    conn.execute(
+        "UPDATE retraction_undo SET consumed_at = ? WHERE token = ?",
+        (int(time.time() * 1000), undo_token),
+    )
+    conn.execute(
+        """UPDATE retraction_log SET undone_at = ?
+           WHERE rowid = (
+             SELECT rowid FROM retraction_log
+             WHERE fact_id = ? AND undone_at IS NULL
+             ORDER BY ts DESC LIMIT 1
+           )""",
+        (int(time.time() * 1000), fact_id),
+    )
+    conn.commit()
+    conn.close()
+
+    return {
+        "ok": True,
+        "fact_id": fact_id,
+        "restored": True,
+        "restored_tx": tx_id,
+        "triples_restored": triples_restored,
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Fact retraction / restore")
+    parser.add_argument("--db", required=True, help="Knowledge graph DB path")
+    parser.add_argument("--web-db", required=True, help="Web metadata DB path")
+    parser.add_argument("--fact-id", required=True, help="Fact entity id (e.g. fact:foo)")
+    mode = parser.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--retract", action="store_true")
+    mode.add_argument("--restore", action="store_true")
+    parser.add_argument("--reason", default=None)
+    parser.add_argument("--actor", default=None)
+    parser.add_argument("--source-entity", default=None,
+                        help="Entity page user was on when retracting (telemetry)")
+    parser.add_argument("--undo-token", default=None)
+    args = parser.parse_args()
+
+    if not Path(args.db).exists():
+        print(json.dumps({"ok": False, "error": f"db not found: {args.db}"}))
+        sys.exit(1)
+
+    if args.retract:
+        out = retract_fact(args.db, args.web_db, args.fact_id,
+                           args.reason, args.actor, args.source_entity)
+    else:
+        if not args.undo_token:
+            print(json.dumps({"ok": False, "error": "--undo-token required for --restore"}))
+            sys.exit(1)
+        out = restore_fact(args.db, args.web_db, args.fact_id, args.undo_token)
+
+    print(json.dumps(out, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()