@geravant/sinain 1.19.0 → 1.20.0

package/sinain-core/src/web-db/schema.ts

@@ -0,0 +1,100 @@
+/**
+ * Schema for ~/.sinain/memory/web.db — UI metadata storage.
+ *
+ * Kept separate from triplestore (knowledge-graph.db) because triples are
+ * claims about the world (with confidence, retraction, bi-temporal validity),
+ * whereas this DB stores UI state, page caches, and undo tokens — metadata
+ * that should not be visible to the curator/distiller.
+ */
+
+export const SCHEMA_VERSION = 1;
+
+export const SCHEMA_SQL = `
+-- Schema version tracking (for future migrations)
+CREATE TABLE IF NOT EXISTS schema_meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+-- User bookmarks (favorite / archive / recent)
+CREATE TABLE IF NOT EXISTS user_bookmarks (
+  entity_id     TEXT PRIMARY KEY,
+  status        TEXT NOT NULL CHECK (status IN ('favorite','archive','recent')),
+  note          TEXT,
+  created_at    INTEGER NOT NULL,
+  last_visited  INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_bookmarks_status_visited
+  ON user_bookmarks(status, last_visited DESC);
+
+-- LLM-rendered page cache. Key: (entity, max tx_id of facts that fed the render)
+-- Implicit invalidation: new facts → tx advances → cache miss → regenerate.
+-- Old entries kept for bi-temporal "view as of" support.
+CREATE TABLE IF NOT EXISTS page_cache (
+  entity_id     TEXT NOT NULL,
+  tx_watermark  INTEGER NOT NULL,
+  page_json     TEXT NOT NULL,
+  generated_at  INTEGER NOT NULL,
+  tokens_in     INTEGER,
+  tokens_out    INTEGER,
+  cost_usd      REAL,
+  PRIMARY KEY (entity_id, tx_watermark)
+);
+CREATE INDEX IF NOT EXISTS idx_page_cache_entity
+  ON page_cache(entity_id, generated_at DESC);
+
+-- Undo snapshots for fact retraction. 10-minute server-side window.
+-- Single-use: consumed_at set when restored; row not deleted (audit trail).
+CREATE TABLE IF NOT EXISTS retraction_undo (
+  token         TEXT PRIMARY KEY,
+  fact_id       TEXT NOT NULL,
+  snapshot_json TEXT NOT NULL,
+  retracted_tx  INTEGER NOT NULL,
+  reason        TEXT,
+  actor         TEXT,
+  created_at    INTEGER NOT NULL,
+  expires_at    INTEGER NOT NULL,
+  consumed_at   INTEGER
+);
+CREATE INDEX IF NOT EXISTS idx_retraction_undo_expires
+  ON retraction_undo(expires_at);
+
+-- Audit log of every retraction (kept forever, feeds eval reports).
+CREATE TABLE IF NOT EXISTS retraction_log (
+  ts            INTEGER NOT NULL,
+  fact_id       TEXT NOT NULL,
+  reason        TEXT,
+  actor         TEXT,
+  undone_at     INTEGER,
+  source_entity TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_retraction_log_ts ON retraction_log(ts DESC);
+
+-- Imported concepts — provenance + idempotency check via bundle_sha256.
+CREATE TABLE IF NOT EXISTS concept_imports (
+  id              INTEGER PRIMARY KEY AUTOINCREMENT,
+  imported_at     INTEGER NOT NULL,
+  root_entity     TEXT NOT NULL,
+  source_tool     TEXT,
+  source_version  TEXT,
+  envelope_format TEXT NOT NULL,
+  bundle_sha256   TEXT NOT NULL,
+  conflict_mode   TEXT NOT NULL,
+  triples_count   INTEGER,
+  redactions_seen TEXT,
+  notes           TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_concept_imports_root
+  ON concept_imports(root_entity, imported_at DESC);
+CREATE INDEX IF NOT EXISTS idx_concept_imports_sha
+  ON concept_imports(bundle_sha256);
+
+-- Search log for telemetry / "what did the user search for that didn't resolve."
+CREATE TABLE IF NOT EXISTS search_log (
+  ts            INTEGER NOT NULL,
+  query         TEXT NOT NULL,
+  resolved_to   TEXT,
+  result_count  INTEGER
+);
+CREATE INDEX IF NOT EXISTS idx_search_log_ts ON search_log(ts DESC);
+`;

package/sinain-core/src/web-db/store.ts

@@ -0,0 +1,279 @@
+/**
+ * Typed accessor for ~/.sinain/memory/web.db.
+ *
+ * One module owns all SQL — keeps query strings out of HTTP handlers and
+ * lets us swap out better-sqlite3 later if needed.
+ */
+import Database from "better-sqlite3";
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { SCHEMA_SQL, SCHEMA_VERSION } from "./schema.js";
+import { log } from "../log.js";
+
+const TAG = "web-db";
+
+export type BookmarkStatus = "favorite" | "archive" | "recent";
+
+export interface Bookmark {
+  entity_id: string;
+  status: BookmarkStatus;
+  note: string | null;
+  created_at: number;
+  last_visited: number;
+}
+
+export interface PageCacheRow {
+  entity_id: string;
+  tx_watermark: number;
+  page_json: string;
+  generated_at: number;
+  tokens_in: number | null;
+  tokens_out: number | null;
+  cost_usd: number | null;
+}
+
+export interface RetractionUndoRow {
+  token: string;
+  fact_id: string;
+  snapshot_json: string;
+  retracted_tx: number;
+  reason: string | null;
+  actor: string | null;
+  created_at: number;
+  expires_at: number;
+  consumed_at: number | null;
+}
+
+export interface ConceptImportRow {
+  id?: number;
+  imported_at: number;
+  root_entity: string;
+  source_tool: string | null;
+  source_version: string | null;
+  envelope_format: string;
+  bundle_sha256: string;
+  conflict_mode: string;
+  triples_count: number | null;
+  redactions_seen: string | null;
+  notes: string | null;
+}
+
+const PAGE_CACHE_LRU_CAP = 500;
+
+export class WebDb {
+  private db: Database.Database;
+
+  constructor(dbPath: string) {
+    if (!existsSync(dirname(dbPath))) {
+      mkdirSync(dirname(dbPath), { recursive: true });
+    }
+    this.db = new Database(dbPath);
+    this.db.pragma("journal_mode = WAL");
+    this.db.pragma("foreign_keys = ON");
+    this.db.exec(SCHEMA_SQL);
+    this.db
+      .prepare(
+        "INSERT INTO schema_meta(key, value) VALUES('version', ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value",
+      )
+      .run(String(SCHEMA_VERSION));
+    log(TAG, `web.db ready at ${dbPath} (schema v${SCHEMA_VERSION})`);
+  }
+
+  close(): void {
+    this.db.close();
+  }
+
+  // ── Bookmarks ───────────────────────────────────────────
+
+  listBookmarks(status?: BookmarkStatus, limit = 100): Bookmark[] {
+    const sql = status
+      ? "SELECT * FROM user_bookmarks WHERE status = ? ORDER BY last_visited DESC LIMIT ?"
+      : "SELECT * FROM user_bookmarks ORDER BY last_visited DESC LIMIT ?";
+    const args = status ? [status, limit] : [limit];
+    return this.db.prepare(sql).all(...args) as Bookmark[];
+  }
+
+  upsertBookmark(entity_id: string, status: BookmarkStatus, note?: string): Bookmark {
+    const now = Date.now();
+    this.db
+      .prepare(
+        `INSERT INTO user_bookmarks(entity_id, status, note, created_at, last_visited)
+         VALUES(?, ?, ?, ?, ?)
+         ON CONFLICT(entity_id) DO UPDATE SET
+           status = excluded.status,
+           note = COALESCE(excluded.note, user_bookmarks.note),
+           last_visited = excluded.last_visited`,
+      )
+      .run(entity_id, status, note ?? null, now, now);
+    return this.db
+      .prepare("SELECT * FROM user_bookmarks WHERE entity_id = ?")
+      .get(entity_id) as Bookmark;
+  }
+
+  deleteBookmark(entity_id: string): boolean {
+    const r = this.db.prepare("DELETE FROM user_bookmarks WHERE entity_id = ?").run(entity_id);
+    return r.changes > 0;
+  }
+
+  /** Bump last_visited for a bookmark; if absent, insert as 'recent'. */
+  touchVisit(entity_id: string): void {
+    const now = Date.now();
+    this.db
+      .prepare(
+        `INSERT INTO user_bookmarks(entity_id, status, note, created_at, last_visited)
+         VALUES(?, 'recent', NULL, ?, ?)
+         ON CONFLICT(entity_id) DO UPDATE SET last_visited = excluded.last_visited`,
+      )
+      .run(entity_id, now, now);
+  }
+
+  // ── Page cache ──────────────────────────────────────────
+
+  getPageCache(entity_id: string, tx_watermark: number): PageCacheRow | null {
+    const row = this.db
+      .prepare(
+        "SELECT * FROM page_cache WHERE entity_id = ? AND tx_watermark = ?",
+      )
+      .get(entity_id, tx_watermark) as PageCacheRow | undefined;
+    return row ?? null;
+  }
+
+  putPageCache(row: Omit<PageCacheRow, "generated_at"> & { generated_at?: number }): void {
+    const generated_at = row.generated_at ?? Date.now();
+    this.db
+      .prepare(
+        `INSERT OR REPLACE INTO page_cache
+         (entity_id, tx_watermark, page_json, generated_at, tokens_in, tokens_out, cost_usd)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .run(
+        row.entity_id,
+        row.tx_watermark,
+        row.page_json,
+        generated_at,
+        row.tokens_in ?? null,
+        row.tokens_out ?? null,
+        row.cost_usd ?? null,
+      );
+    this.pruneCache();
+  }
+
+  /** LRU prune: keep newest PAGE_CACHE_LRU_CAP entries by generated_at. */
+  private pruneCache(): void {
+    const count = (this.db.prepare("SELECT COUNT(*) as n FROM page_cache").get() as { n: number }).n;
+    if (count <= PAGE_CACHE_LRU_CAP) return;
+    const overflow = count - PAGE_CACHE_LRU_CAP;
+    this.db
+      .prepare(
+        `DELETE FROM page_cache WHERE rowid IN (
+           SELECT rowid FROM page_cache ORDER BY generated_at ASC LIMIT ?
+         )`,
+      )
+      .run(overflow);
+  }
+
+  // ── Retraction undo ─────────────────────────────────────
+
+  putRetractionUndo(row: Omit<RetractionUndoRow, "consumed_at">): void {
+    this.db
+      .prepare(
+        `INSERT INTO retraction_undo
+         (token, fact_id, snapshot_json, retracted_tx, reason, actor, created_at, expires_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .run(
+        row.token,
+        row.fact_id,
+        row.snapshot_json,
+        row.retracted_tx,
+        row.reason,
+        row.actor,
+        row.created_at,
+        row.expires_at,
+      );
+  }
+
+  getRetractionUndo(token: string): RetractionUndoRow | null {
+    const row = this.db
+      .prepare("SELECT * FROM retraction_undo WHERE token = ?")
+      .get(token) as RetractionUndoRow | undefined;
+    return row ?? null;
+  }
+
+  consumeRetractionUndo(token: string): void {
+    this.db
+      .prepare("UPDATE retraction_undo SET consumed_at = ? WHERE token = ?")
+      .run(Date.now(), token);
+  }
+
+  pruneExpiredUndos(): number {
+    const r = this.db
+      .prepare("DELETE FROM retraction_undo WHERE expires_at < ? AND consumed_at IS NULL")
+      .run(Date.now());
+    return r.changes;
+  }
+
+  logRetraction(fact_id: string, reason: string | null, actor: string | null, source_entity: string | null): void {
+    this.db
+      .prepare(
+        `INSERT INTO retraction_log(ts, fact_id, reason, actor, source_entity)
+         VALUES (?, ?, ?, ?, ?)`,
+      )
+      .run(Date.now(), fact_id, reason, actor, source_entity);
+  }
+
+  markRetractionUndone(fact_id: string): void {
+    this.db
+      .prepare(
+        `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
+         )`,
+      )
+      .run(Date.now(), fact_id);
+  }
+
+  // ── Concept imports ─────────────────────────────────────
+
+  recordConceptImport(row: ConceptImportRow): number {
+    const r = this.db
+      .prepare(
+        `INSERT INTO concept_imports
+         (imported_at, root_entity, source_tool, source_version, envelope_format,
+          bundle_sha256, conflict_mode, triples_count, redactions_seen, notes)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .run(
+        row.imported_at,
+        row.root_entity,
+        row.source_tool,
+        row.source_version,
+        row.envelope_format,
+        row.bundle_sha256,
+        row.conflict_mode,
+        row.triples_count,
+        row.redactions_seen,
+        row.notes,
+      );
+    return Number(r.lastInsertRowid);
+  }
+
+  findImportBySha(bundle_sha256: string): ConceptImportRow | null {
+    const row = this.db
+      .prepare("SELECT * FROM concept_imports WHERE bundle_sha256 = ? ORDER BY imported_at DESC LIMIT 1")
+      .get(bundle_sha256) as ConceptImportRow | undefined;
+    return row ?? null;
+  }
+
+  // ── Search log ──────────────────────────────────────────
+
+  logSearch(query: string, resolved_to: string | null, result_count: number): void {
+    this.db
+      .prepare(
+        "INSERT INTO search_log(ts, query, resolved_to, result_count) VALUES (?, ?, ?, ?)",
+      )
+      .run(Date.now(), query, resolved_to, result_count);
+  }
+}

package/sinain-memory/concept_export.py

@@ -0,0 +1,310 @@
+#!/usr/bin/env python3
+"""Concept Export — package an entity + its neighborhood as a portable bundle.
+
+Produces a sinain-concept/v1 envelope that can be transferred to another
+machine and re-imported with concept_import.py to reconstruct the same
+entity page (including the LLM-rendered view, if bundled).
+
+The reproducibility invariant we honor:
+    "On a new machine: import the bundle → open the same URL → see the same page."
+
+For that to hold:
+  1. Entity IDs are content-addressed slugs → stable across machines.
+  2. Triples are exported verbatim (created_at, retracted) for round-trip.
+  3. Optionally bundle the rendered_page JSON so the receiver gets a
+     cache hit on first view (deterministic visual identity).
+
+We do NOT bundle embeddings — same model on both ends → same vectors,
+so receiver recomputes for ~1.5KB/fact saved.
+
+Usage:
+    python3 concept_export.py --db <kg.db> --root entity:foo \\
+        [--depth 1] [--include-retracted] [--include-page] [--web-db <web.db>] \\
+        [--redact private,creditcard,apikey,...]
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import sys
+import time
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Redaction (MIRROR OF sense_client/privacy.py — keep patterns in sync until
+# we extract a shared sinain-memory/redaction.py module).
+# ---------------------------------------------------------------------------
+REDACT_RULES_VERSION = "1.2"
+
+_REDACT_PATTERNS: list[tuple[re.Pattern, str, str]] = [
+    # (regex, replacement, rule-name)
+    (re.compile(r"\b\d{4}[\s-]?\d{4}[\s-]?\d{4}[\s-]?\d{4}\b"), "[REDACTED:card]", "creditcard"),
+    (re.compile(r"\b(?:sk-|pk-|api[_-]?key[=:]\s*)[A-Za-z0-9_\-]{20,}\b"), "[REDACTED:apikey]", "apikey"),
+    (re.compile(r"Bearer\s+[A-Za-z0-9_\-\.]{20,}"), "[REDACTED:bearer]", "bearer"),
+    (re.compile(r"\b(?:AKIA|ASIA)[A-Z0-9]{16}\b"), "[REDACTED:awskey]", "awskey"),
+    (re.compile(r"(?:password|passwd|pwd)\s*[:=]\s*\S+", re.IGNORECASE), "[REDACTED:password]", "password"),
+    (re.compile(r"\bghp_[A-Za-z0-9]{36}\b"), "[REDACTED:github_pat]", "github_pat"),
+    (re.compile(r"\bghs_[A-Za-z0-9]{36}\b"), "[REDACTED:github_srv]", "github_srv"),
+    (re.compile(r"\bxox[bpoa]-[0-9A-Za-z\-]+"), "[REDACTED:slack]", "slack"),
+    (re.compile(r"\bya29\.[0-9A-Za-z\-_]+"), "[REDACTED:google_oauth]", "google_oauth"),
+    (re.compile(r"\beyJ[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]+\.[A-Za-z0-9\-_]+"), "[REDACTED:jwt]", "jwt"),
+    (re.compile(r"(?:secret|token|key)\s*[:=]\s*[A-Za-z0-9_\-\.]{10,}", re.IGNORECASE), "[REDACTED:secret]", "secret"),
+    (re.compile(r"\b\d{3}-\d{2}-\d{4}\b"), "[REDACTED:ssn]", "ssn"),
+    (re.compile(r"-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----"), "[REDACTED:privkey]", "privkey"),
+]
+_PRIVATE_TAG = re.compile(r"<private>.*?</private>", re.DOTALL)
+
+
+def apply_redactions(text: str, enabled_rules: set[str]) -> tuple[str, list[str]]:
+    """Run enabled redaction rules over *text*. Returns (redacted_text, applied)."""
+    applied: list[str] = []
+    if "private" in enabled_rules:
+        new_text = _PRIVATE_TAG.sub("[REDACTED:private]", text)
+        if new_text != text:
+            applied.append("private")
+            text = new_text
+    for pattern, replacement, name in _REDACT_PATTERNS:
+        if name in enabled_rules:
+            new_text = pattern.sub(replacement, text)
+            if new_text != text:
+                applied.append(name)
+                text = new_text
+    return text, applied
+
+
+# ---------------------------------------------------------------------------
+# Export
+# ---------------------------------------------------------------------------
+
+def collect_neighborhood(store, root_entity: str, depth: int,
+                         include_retracted: bool) -> list[str]:
+    """BFS from root, following both incoming and outgoing refs.
+
+    Outgoing: triples WHERE entity_id = X AND value_type = 'ref' → recurse to value.
+    Incoming: triples WHERE value = X AND value_type = 'ref' → recurse to entity_id.
+
+    Returns deterministically-ordered list of entity_ids reachable within depth.
+    """
+    visited: dict[str, int] = {root_entity: 0}
+    queue: list[tuple[str, int]] = [(root_entity, 0)]
+    retracted_filter = "" if include_retracted else "AND retracted = 0"
+
+    while queue:
+        eid, d = queue.pop(0)
+        if d >= depth:
+            continue
+
+        # Outgoing refs
+        rows_out = store._conn.execute(
+            f"""SELECT DISTINCT value FROM triples
+                WHERE entity_id = ? AND value_type = 'ref' {retracted_filter}""",
+            (eid,),
+        ).fetchall()
+        for r in rows_out:
+            ref = r["value"]
+            if ref and ref not in visited:
+                visited[ref] = d + 1
+                queue.append((ref, d + 1))
+
+        # Incoming refs
+        rows_in = store._conn.execute(
+            f"""SELECT DISTINCT entity_id FROM triples
+                WHERE value = ? AND value_type = 'ref' {retracted_filter}""",
+            (eid,),
+        ).fetchall()
+        for r in rows_in:
+            ref = r["entity_id"]
+            if ref and ref not in visited:
+                visited[ref] = d + 1
+                queue.append((ref, d + 1))
+
+    return sorted(visited.keys())  # deterministic ordering for stable checksum
+
+
+def serialize_entity(store, entity_id: str, include_retracted: bool,
+                     redact_rules: set[str]) -> tuple[dict, list[str], int]:
+    """Pull all triples for entity_id, apply redactions to string values.
+
+    Returns ({id, type, triples: [...]}, applied_rules, redacted_count).
+    """
+    where = "" if include_retracted else "AND retracted = 0"
+    rows = store._conn.execute(
+        f"""SELECT attribute, value, value_type, tx_id, created_at, retracted, valid_to
+            FROM triples WHERE entity_id = ? {where}
+            ORDER BY tx_id, attribute, value""",
+        (entity_id,),
+    ).fetchall()
+
+    triples = []
+    all_applied: list[str] = []
+    redacted_count = 0
+    for r in rows:
+        value = r["value"]
+        if r["value_type"] == "string" and redact_rules and value:
+            new_value, applied = apply_redactions(value, redact_rules)
+            if applied:
+                all_applied.extend(applied)
+                redacted_count += 1
+                value = new_value
+        triples.append({
+            "attribute": r["attribute"],
+            "value": value,
+            "value_type": r["value_type"],
+            "tx_id": r["tx_id"],
+            "created_at": r["created_at"],
+            "retracted": int(r["retracted"]),
+            "valid_to": r["valid_to"],
+        })
+
+    type_prefix = entity_id.split(":", 1)[0] if ":" in entity_id else "unknown"
+    return ({"id": entity_id, "type": type_prefix, "triples": triples},
+            all_applied, redacted_count)
+
+
+def fetch_cached_page(web_db_path: str, root_entity: str,
+                     redact_rules: set[str]) -> dict | None:
+    """Pull the most recent cached rendered_page for root_entity, if any.
+    Apply redactions over the page summary + bullet text too — the LLM may
+    have woven sensitive content into its synthesis.
+    """
+    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, tokens_in, tokens_out, cost_usd
+               FROM page_cache WHERE entity_id = ?
+               ORDER BY generated_at DESC LIMIT 1""",
+            (root_entity,),
+        ).fetchone()
+        conn.close()
+        if not row:
+            return None
+        page = json.loads(row["page_json"])
+        # Redact rendered_page content.
+        if redact_rules:
+            if page.get("summary"):
+                new_summary, _ = apply_redactions(page["summary"], redact_rules)
+                page["summary"] = new_summary
+            for sec in page.get("sections", []) or []:
+                for b in sec.get("bullets", []) or []:
+                    if b.get("text"):
+                        new_text, _ = apply_redactions(b["text"], redact_rules)
+                        b["text"] = new_text
+        page["generated_at"] = row["generated_at"]
+        page.setdefault("rendered_with", {})
+        if row["tokens_in"]: page["rendered_with"]["tokens_in"] = row["tokens_in"]
+        if row["tokens_out"]: page["rendered_with"]["tokens_out"] = row["tokens_out"]
+        return page
+    except Exception as e:
+        sys.stderr.write(f"fetch_cached_page failed: {e}\n")
+        return None
+
+
+def export_concept(db_path: str, root_entity: str, depth: int = 1,
+                   include_retracted: bool = False,
+                   include_page: bool = True,
+                   web_db_path: str | None = None,
+                   redact_rules: set[str] | None = None) -> dict:
+    from triplestore import TripleStore
+
+    if redact_rules is None:
+        redact_rules = {"private", "creditcard", "apikey", "bearer", "awskey",
+                        "password", "secret"}
+
+    store = TripleStore(db_path)
+    entity_ids = collect_neighborhood(store, root_entity, depth, include_retracted)
+
+    entities = []
+    all_applied: list[str] = []
+    total_redacted = 0
+    triple_count = 0
+    fact_count = 0
+
+    for eid in entity_ids:
+        entity_obj, applied, n_redacted = serialize_entity(
+            store, eid, include_retracted, redact_rules,
+        )
+        entities.append(entity_obj)
+        all_applied.extend(applied)
+        total_redacted += n_redacted
+        triple_count += len(entity_obj["triples"])
+        if eid.startswith("fact:"):
+            fact_count += 1
+
+    store.close()
+
+    rendered_page = None
+    if include_page and web_db_path:
+        rendered_page = fetch_cached_page(web_db_path, root_entity, redact_rules)
+
+    envelope = {
+        "format": "sinain-concept/v1",
+        "exported_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "exporter": {
+            "tool": "sinain-core",
+            "tool_version": "1.14.0",
+            "schema_version": "triplestore/v3",
+            "embedding_model": "all-MiniLM-L6-v2",
+        },
+        "root_entity": root_entity,
+        "depth": depth,
+        "stats": {
+            "entities": len(entity_ids),
+            "facts": fact_count,
+            "triples": triple_count,
+        },
+        "entities": entities,
+        "rendered_page": rendered_page,
+        "redactions": {
+            "applied": sorted(set(all_applied)),
+            "rules_version": REDACT_RULES_VERSION,
+            "redacted_count": total_redacted,
+        },
+    }
+
+    # Compute checksum over canonical JSON of (root_entity + entities) — this is
+    # what the receiver should validate against on import.
+    canonical = json.dumps(
+        {"root_entity": root_entity, "entities": entities},
+        sort_keys=True, ensure_ascii=False, separators=(",", ":"),
+    )
+    envelope["checksum"] = "sha256:" + hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+    return envelope
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Concept Export")
+    parser.add_argument("--db", required=True)
+    parser.add_argument("--root", required=True, help="Root entity id (e.g. entity:citibank)")
+    parser.add_argument("--depth", type=int, default=1)
+    parser.add_argument("--include-retracted", action="store_true")
+    parser.add_argument("--include-page", action="store_true",
+                        help="Bundle the cached rendered_page if available")
+    parser.add_argument("--web-db", default=None,
+                        help="Path to web.db for page cache lookup")
+    parser.add_argument("--redact", default="private,creditcard,apikey,bearer,awskey,password,secret",
+                        help="Comma-separated redaction rule names")
+    args = parser.parse_args()
+
+    if not Path(args.db).exists():
+        print(json.dumps({"error": f"db not found: {args.db}"}))
+        sys.exit(1)
+
+    rules = {r.strip() for r in args.redact.split(",") if r.strip()}
+    envelope = export_concept(
+        args.db, args.root, depth=args.depth,
+        include_retracted=args.include_retracted,
+        include_page=args.include_page,
+        web_db_path=args.web_db,
+        redact_rules=rules,
+    )
+    print(json.dumps(envelope, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()