ltcai 9.9.1 → 9.9.3

package/README.md

@@ -11,7 +11,7 @@
 [![CI Status](https://github.com/TaeSooPark-PTS/LatticeAI/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/TaeSooPark-PTS/LatticeAI/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
-![v9.9.1 Living Brain walkthrough](output/release/v9.9.1/gifs/v9.9.1-living-brain-walkthrough.gif)
+![v9.9.3 Living Brain walkthrough](output/release/v9.9.3/gifs/v9.9.3-living-brain-walkthrough.gif)
 
 Chat, files, folders, notes, and web pages all flow into one durable knowledge
 graph on your computer. Any model — local MLX or cloud — can speak with that
@@ -24,9 +24,9 @@ memory. Nothing leaves your machine without explicit consent.
 
 | | |
 | --- | --- |
-| **Chat with a Brain that remembers** — every conversation grows durable, source-linked memory ![Brain Chat](output/release/v9.9.1/screenshots/04-brain-chat-home.png) | **See how knowledge connects** — a real relationship graph, not a file list ![Memory Graph](output/release/v9.9.1/screenshots/05-memory-graph.png) |
-| **Capture anything** — files, whole folders, notes, screenshots, web pages ![Capture](output/release/v9.9.1/screenshots/06-capture.png) | **Automate with review** — agent changes become proposals you approve first ![Review Center](output/release/v9.9.1/screenshots/12-review-center.png) |
-| **Pick a model in one click** — recommended local models for your hardware ![Recommended Models](output/release/v9.9.1/screenshots/02-recommended-models.png) | **Stay in control** — audit, roles, retention in a separate admin surface ![Admin Console](output/release/v9.9.1/screenshots/10-admin-console.png) |
+| **Chat with a Brain that remembers** — every conversation grows durable, source-linked memory ![Brain Chat](output/release/v9.9.3/screenshots/04-brain-chat-home.png) | **See how knowledge connects** — a real relationship graph, not a file list ![Memory Graph](output/release/v9.9.3/screenshots/05-memory-graph.png) |
+| **Capture anything** — files, whole folders, notes, screenshots, web pages ![Capture](output/release/v9.9.3/screenshots/06-capture.png) | **Automate with review** — agent changes become proposals you approve first ![Review Center](output/release/v9.9.3/screenshots/12-review-center.png) |
+| **Pick a model in one click** — recommended local models for your hardware ![Recommended Models](output/release/v9.9.3/screenshots/02-recommended-models.png) | **Stay in control** — audit, roles, retention in a separate admin surface ![Admin Console](output/release/v9.9.3/screenshots/10-admin-console.png) |
 
 ## Why Lattice AI
 
@@ -57,49 +57,48 @@ First-run flow — wake the Brain, pick the owner, load a recommended model:
 
 | | | |
 | --- | --- | --- |
-| ![Login](output/release/v9.9.1/screenshots/01-login.png) | ![Model install](output/release/v9.9.1/screenshots/03-install-load-progress.png) | ![Model library](output/release/v9.9.1/screenshots/07-model-library.png) |
+| ![Login](output/release/v9.9.3/screenshots/01-login.png) | ![Model install](output/release/v9.9.3/screenshots/03-install-load-progress.png) | ![Model library](output/release/v9.9.3/screenshots/07-model-library.png) |
 
 Screenshot index and capture notes:
-[output/release/v9.9.1/SCREENSHOT_INDEX.md](output/release/v9.9.1/SCREENSHOT_INDEX.md)
+[output/release/v9.9.3/SCREENSHOT_INDEX.md](output/release/v9.9.3/SCREENSHOT_INDEX.md)
 
 ## Current Release
 
-The current release is **9.9.1 — Clean Foundations**:
-
-- **A clean core.** The historical repo-root compatibility shims are gone
-  (only `server.py` remains for `uvicorn server:app`); packaging ships exactly
-  the `latticeai.*` / `lattice_brain.*` packages, and a legacy debt gate in
-  `npm run lint` plus a dedicated test suite keep the root clean for good.
-- **Your first five minutes matter.** A guided "First 5 minutes" card on the
-  empty Brain home walks a new user through asking a first question, adding a
-  first file or note, and seeing what the Brain learned — wired to real
-  features, with progress that persists and a briefing that loads immediately.
-- **Proactive intelligence you can actually see.** Today's briefing now lives
-  on the Brain home instead of a double-collapsed drawer, and Cmd+K opens with
-  proactive quick actions (open briefing, review pending items, ask the Brain)
-  before you type a single letter.
-- **Review Center at product quality.** Proposal cards translate risk and
-  change class into human language, frame diffs with file targets and honest
-  truncation counts, tuck raw IDs into a "Technical details" disclosure, and
-  every approve/reject failure shows a friendly message first.
-- **Errors that speak your language.** The API error pipeline is localized
-  (ko/en): timeouts, unreachable-service, and backend failures produce plain,
-  helpful copy instead of raw `statusText` or English literals, across chat,
-  admin, care, and intelligence panels.
-- **Scenario-first tests, smaller evidence footprint.** 37 version-named test
-  files were renamed to behavior-named suites, and `output/release/` now keeps
-  only the newest three evidence sets (~70MB reclaimed) via an automated
-  retention policy.
+The current release is **9.9.3 — Closed Loops**:
+
+- **Multi-file projects, not single files.** "todo 앱 html+css+js" now infers
+  a project manifest, generates and validates every file through the same
+  sanitize pipeline, repairs cross-file references, verifies the bundle, and
+  offers a safe zip download — every file rides the `artifacts[]` contract.
+- **Approval is a conversation, not a dead end.** Runs that need human
+  approval pause as `awaiting_approval` with a plan summary and a short-TTL
+  token; an inline card lets you approve, edit the plan, or cancel — the
+  fail-closed guarantee is unchanged.
+- **First value in 30 seconds.** One click installs a 3-document demo corpus,
+  suggested questions prove recall with real sources, and answers carry an
+  honest grounding badge (근거 있음/근거 없음) bound to retrieved sources.
+- **Retrieval that knows what you asked.** Hybrid search classifies queries
+  (fact/code/person/recency) and fuses channels with per-class weights, gated
+  by a benchmark-threshold CI test; a graph noise-curation job and an opt-in
+  folder watch keep the Brain fresh and clean.
+- **Automation you can see and trust.** Per-automation "run now" with
+  dry-run-first, last execution surfaced on cards and the daily briefing,
+  failures routed to the Review queue — plus inline file previews, global
+  drag-and-drop capture, 409 conflict rebase, and a funnel-metrics endpoint.
+- **A deeper harness.** 23 agent_eval scenarios including dirty-write filegen
+  paths, golden sanitize fixtures, a multi-model filegen benchmark, a
+  deterministic knowledge-pipeline E2E test, per-phase token budgets, and
+  `.tsx/.vue/.svelte` support with `ast.parse` Python validation.
 
 Release notes: [RELEASE.md](RELEASE.md) · Full history: [docs/CHANGELOG.md](docs/CHANGELOG.md)
 
-Expected artifacts for 9.9.1 release must use exact filenames:
+Expected artifacts for 9.9.3 release must use exact filenames:
 
-- `dist/ltcai-9.9.1-py3-none-any.whl`
-- `dist/ltcai-9.9.1.tar.gz`
-- `ltcai-9.9.1.tgz`
-- `dist/ltcai-9.9.1.vsix`
-- `src-tauri/target/release/bundle/dmg/Lattice AI_9.9.1_aarch64.dmg`
+- `dist/ltcai-9.9.3-py3-none-any.whl`
+- `dist/ltcai-9.9.3.tar.gz`
+- `ltcai-9.9.3.tgz`
+- `dist/ltcai-9.9.3.vsix`
+- `src-tauri/target/release/bundle/dmg/Lattice AI_9.9.3_aarch64.dmg`
 
 Do not use wildcard artifact uploads. Package registry publishing remains owner-run.
 
@@ -119,7 +118,7 @@ See [ARCHITECTURE.md](ARCHITECTURE.md) for details and
 
 - External package registries are owner-published and can lag behind GitHub.
 - PostgreSQL/pgvector is optional scale/migration tooling. SQLite remains the
-  live local Brain store in 9.9.1.
+  live local Brain store in 9.9.3.
 - Docker, model downloads, cloud model calls, Telegram, Brain Network, and
   update checks require explicit user action.
 - Conversation does not fabricate answers when no model is loaded. Agent and
@@ -131,6 +130,8 @@ See [ARCHITECTURE.md](ARCHITECTURE.md) for details and
 
 | Version | Theme |
 | --- | --- |
+| 9.9.3 | Closed Loops |
+| 9.9.2 | Artifact Trust |
 | 9.9.1 | Clean Foundations |
 | 9.9.0 | Fail-Closed Trust |
 | 9.8.0 | Honest Knowledge Pipeline |

package/docs/CHANGELOG.md

@@ -4,6 +4,86 @@ The top entry is either the current unreleased main-branch work or the current
 release line. Older entries are historical and may describe behavior as it
 existed at that release.
 
+## [9.9.3] - 2026-07-22
+
+### Added
+- Multi-file Artifact Loop: `infer_project_manifest` → per-file
+  generate/validate → cross-file reference repair → bundle validation →
+  `artifacts[]` + `project.zip_url`; safe `GET /tools/download_zip`.
+- Interactive approval: governed plans pause as `awaiting_approval` with a
+  single-use 10-minute token; `POST /agent/resume` approves, edits, or
+  cancels. Inline approval card in chat.
+- First Value Loop: `POST/GET/DELETE /api/setup/demo-corpus` (3 built-in demo
+  documents, `demo://` provenance, idempotent) + the "30초 체험" home track
+  with suggested-question chips.
+- Answer grounding: `grounding {status, source_ids, overlap}` on chat
+  responses; 근거 있음/근거 없음 badge.
+- Retrieval fusion: query-class detection (fact/code/person/recency) with
+  per-class channel weights and a benchmark-threshold CI gate
+  (`tests/unit/test_retrieval_fusion_gate.py`).
+- Opt-in folder watch (`/api/ingestion/watch`, polling + persisted consent),
+  capture-quality CTA (`capture_quality` on browser captures), graph noise
+  curation job (`POST /knowledge-graph/curate/noise`, dry-run default).
+- Automation visibility: `POST /api/automation/run-now` (dry-run-first),
+  `last_execution` on overview/briefing, failed runs → Review queue; Act-panel
+  "지금 한 번 실행" cards.
+- UX: inline file preview (sandboxed iframe / modal), folder job report card,
+  global drag-and-drop capture, 409 proposal rebase flow, focus traps, graph
+  keyboard navigation, reduced-motion coverage, success pulse / inflow motes.
+- Harness: agent_eval 23 scenarios (dirty-write filegen paths), golden
+  sanitize fixtures, `bench_models.py --filegen` (fail-open), deterministic
+  knowledge-pipeline E2E test, funnel metrics
+  (`GET /api/admin/funnel-metrics`), `PhaseBudgets` per-phase token caps,
+  `.ts/.tsx/.jsx/.vue/.svelte` filegen validation and Python `ast.parse`.
+
+### Changed
+- Approval-requiring agent runs return `awaiting_approval` instead of FAILED;
+  legacy `context_id` resume with `approved: true` now executes the gated
+  steps.
+- Hybrid search responses expose `query_class`; chat responses expose
+  `grounding`; automation overview exposes `last_execution`.
+
+### Fixed
+- Fenced/chatty CSS is now sanitized before write (`.css` validation rejects
+  Markdown fences) — caught by the new golden fixtures.
+- A legacy approved resume no longer re-fails at the approval gate.
+
+## [9.9.2] - 2026-07-21
+
+### Added
+- ArtifactWritePipeline: `sanitize_write_content` in
+  `latticeai/core/file_generation.py` — a conservative validate-first →
+  extract → repair gate. The agent executor applies it to every `write_file`
+  `args.content` before dispatch, records a `content_sanitize` verdict on the
+  transcript, and tags `artifact_sanitize`/`artifact_repair` in the loop trace.
+- Artifact-first chat contract: direct file-creation responses and agent runs
+  carry an `artifacts[]` array (`kind/path/filename/bytes/previewable/valid/
+  repaired`) via `collect_artifacts(transcript)`.
+- Direct-path overwrite protection: an existing target is auto-suffixed
+  (`generated_page_2.html`) and announced, instead of silently overwritten.
+- Generated files are optionally indexed into the Brain through the unified
+  `IngestionPipeline` (`workspace://` provenance, `origin: generated_file`);
+  disable with `LATTICEAI_INGEST_GENERATED=0`. The response reports an honest
+  `brain_ingest` status; ingest failures never fail the file creation.
+- Plan schema enforcement (`normalize_plan`): non-empty goal, junk-step
+  filtering, `estimated_steps` clamping, and a deterministic single
+  `write_file` step for file-intent requests whose plan came back empty.
+- Memory quality filter (`filter_learnings`): trivial and duplicate agent
+  learnings are dropped before entering the Brain.
+- FG harness `tests/unit/test_artifact_write_scenarios.py` (FG-01..FG-08):
+  intent gating, filename inference, dirty-output extraction, truncated-HTML
+  repair, agent-path sanitization, how-to non-routing, scaffold validity.
+- Frontend honesty surfaces: "Auto-repaired" badge on file cards
+  (`generation.repaired`), and a distinct warning strip for `NEEDS_REVIEW` /
+  `FAILED` terminal agent states (`role="alert"`, ko/en, dark/light).
+
+### Changed
+- HTML file validation now rejects documents wrapped in prose or Markdown
+  fences, so extraction gets a chance to slice out the real document instead
+  of the wrapper being saved as "valid".
+- `product_readiness` `action-aware-chat` gate additionally proves the
+  ArtifactWritePipeline evidence (module, agent seam, FG harness test).
+
 ## [9.9.1] - 2026-07-21
 
 ### Removed

package/docs/COMMUNITY_AND_PLUGINS.md

@@ -1,6 +1,6 @@
 # Community And Plugins
 
-Current release: **9.9.1 — Clean Foundations**.
+Current release: **9.9.3 — Closed Loops**.
 
 LatticeAI defines the path from a strong local-first framework (8.4.0
 action-aware baseline, 8.5.0 registry+DI hardening, 8.6.0 capture/navigation

package/docs/DEVELOPMENT.md

@@ -3,7 +3,7 @@
 > **Status: canonical** — current contributor guidance, kept in sync with the
 > current release.
 
-Current release: **9.9.1 — Clean Foundations**.
+Current release: **9.9.3 — Closed Loops**.
 
 This document is for contributors working on the local-first Digital Brain
 codebase. Product positioning and quick start stay in `README.md`; release

package/docs/ONBOARDING.md

@@ -1,6 +1,6 @@
 # Lattice AI Onboarding
 
-Current release: **9.9.1 — Clean Foundations**.
+Current release: **9.9.3 — Closed Loops**.
 
 The first-run goal is a five-minute path from "I opened the app" to "my Brain
 has a source, a question, and proof." This page is the product contract behind

package/docs/OPERATIONS.md

@@ -1,4 +1,4 @@
-# Lattice AI — Operations Guide (v9.9.1)
+# Lattice AI — Operations Guide (v9.9.3)
 
 > **Status: canonical** — kept in sync with the current release. Storage layout
 > below reflects the SQLite live Brain store and workspace scoping, not the

package/docs/TRUST_MODEL.md

@@ -1,6 +1,6 @@
 # Lattice AI Trust Model
 
-Current release: **9.9.1 — Clean Foundations**.
+Current release: **9.9.3 — Closed Loops**.
 
 Lattice AI is local-first, explicit about external communication, and honest
 when a capability is unavailable.

package/docs/WHY_LATTICE.md

@@ -1,6 +1,6 @@
 # Why Lattice AI Exists
 
-Current release: **9.9.1 — Clean Foundations**.
+Current release: **9.9.3 — Closed Loops**.
 
 **Lattice AI is a local-first Digital Brain that keeps your knowledge durable
 across any AI model.**

package/docs/kg-schema.md

@@ -1,6 +1,6 @@
 # Knowledge Graph Schema
 
-Current release: **9.9.1 — Clean Foundations**.
+Current release: **9.9.3 — Closed Loops**.
 
 명세 출처: `lattice_ai_full_spec.pptx` 슬라이드 20·21·22
 구현: `lattice_brain/graph/schema.py`

package/lattice_brain/__init__.py

@@ -26,7 +26,7 @@ from .storage import (
     storage_from_env,
 )
 
-__version__ = "9.9.1"
+__version__ = "9.9.3"
 
 __all__ = [
     "AgentRuntime",

package/lattice_brain/graph/curator.py

@@ -412,6 +412,142 @@ def curate_nodes(
     return enriched
 
 
+# ── Noise reduction (backlog #10, review §7.2 D) ─────────────────────────────
+# Relation-verb normalization dictionary (ko/en). Keys are canonical verbs;
+# values are the free-string labels observed in the legacy edge table. The
+# canonical labels stay aligned with the v2 EdgeType legacy mapping so this
+# never fights the schema normalization.
+
+RELATION_VERB_GROUPS: Dict[str, List[str]] = {
+    "created": [
+        "creates", "create", "만들다", "만든", "만들었다", "만듦", "만들어냄",
+        "생성함", "생성", "생성했다", "작성함", "작성", "작성했다",
+    ],
+    "mentions": ["mention", "언급함", "언급", "언급했다", "언급됨"],
+    "contains": ["contain", "포함함", "포함", "포함했다", "포함됨"],
+    "uses": ["use", "used", "사용함", "사용", "사용했다", "이용함", "이용"],
+    "related_to": ["related", "relates_to", "관련", "관련됨", "관련있음", "연관됨", "연관"],
+    "fixed": ["fixes", "fix", "수정함", "수정", "수정했다", "고침", "고쳤다"],
+    "decided": ["decides", "decide", "결정함", "결정", "결정했다"],
+    "uploaded": ["uploads", "upload", "업로드함", "업로드", "올림", "올렸다"],
+}
+
+
+def build_relation_verb_index(
+    groups: Optional[Dict[str, List[str]]] = None,
+) -> Dict[str, str]:
+    """{alias(lower) → canonical} — canonical labels map to themselves."""
+    groups = groups or RELATION_VERB_GROUPS
+    index: Dict[str, str] = {}
+    for canonical, aliases in groups.items():
+        canon = str(canonical).strip().lower()
+        index[canon] = canon
+        for alias in aliases:
+            index[str(alias).strip().lower()] = canon
+    return index
+
+
+def normalize_relation_verb(
+    verb: str,
+    *,
+    index: Optional[Dict[str, str]] = None,
+) -> str:
+    """Map a free-string edge verb to its canonical form (identity if unknown).
+
+    Korean verbs are additionally tried with the trailing josa stripped so
+    "생성함을" style variants still normalize; unknown labels pass through
+    unchanged (lossless — this function is a rename map, not a filter).
+    """
+    raw = str(verb or "").strip()
+    if not raw:
+        return raw
+    index = index if index is not None else build_relation_verb_index()
+    low = raw.lower()
+    if low in index:
+        return index[low]
+    stripped = _strip_josa(low)
+    if stripped in index:
+        return index[stripped]
+    return raw
+
+
+# v4 write-door enum labels are SCREAMING_SNAKE_CASE ASCII; those are already
+# canonical schema taxonomy and must never be rewritten by the verb dictionary.
+_V4_ENUM_LABEL_RE = re.compile(r"^[A-Z][A-Z0-9_]*$")
+
+
+def plan_relation_normalization(
+    edge_types: Iterable[str],
+    *,
+    index: Optional[Dict[str, str]] = None,
+) -> Dict[str, str]:
+    """{observed_type → canonical} for every type the dictionary changes.
+
+    Skips v4-canonical enum labels (``MENTIONS``, ``INDEXED_FROM``, …): this
+    plan targets the free-string verbs of pre-v4 rows, not the schema enum.
+    """
+    index = index if index is not None else build_relation_verb_index()
+    plan: Dict[str, str] = {}
+    for edge_type in edge_types:
+        original = str(edge_type or "")
+        if _V4_ENUM_LABEL_RE.match(original):
+            continue
+        canonical = normalize_relation_verb(original, index=index)
+        if canonical and canonical != original:
+            plan[original] = canonical
+    return plan
+
+
+def plan_concept_noise_reduction(
+    concepts: Iterable[Dict[str, Any]],
+    total_docs: int,
+    *,
+    max_df_ratio: float = 0.8,
+    min_doc_frequency: int = 1,
+    min_corpus_docs: int = 5,
+) -> Dict[str, List[Dict[str, Any]]]:
+    """Decide which heuristic concept nodes are graph noise.
+
+    ``concepts``: ``[{"id", "label", "df", "heuristic"}]`` where ``df`` is the
+    number of distinct content documents linking to the concept.
+
+    Rules (dry-run friendly — pure decision, no side effects):
+
+    * **never** flag ``heuristic=False`` nodes (explicit user-created nodes
+      are untouchable, whatever their stats);
+    * low IDF: with a corpus of at least ``min_corpus_docs`` documents, a
+      concept appearing in ``> max_df_ratio`` of them separates nothing —
+      remove;
+    * frequency floor: ``df < min_doc_frequency`` (orphaned/near-orphaned
+      auto concepts) — remove.
+    """
+    total = max(0, int(total_docs))
+    remove: List[Dict[str, Any]] = []
+    keep: List[Dict[str, Any]] = []
+    for concept in concepts:
+        entry = {
+            "id": str(concept.get("id") or ""),
+            "label": concept.get("label"),
+            "df": int(concept.get("df") or 0),
+            "heuristic": bool(concept.get("heuristic")),
+        }
+        if not entry["heuristic"]:
+            keep.append({**entry, "reason": "user_created_protected"})
+            continue
+        df = entry["df"]
+        if df < int(min_doc_frequency):
+            df_ratio = (df / total) if total else 0.0
+            remove.append({**entry, "df_ratio": round(df_ratio, 4), "reason": "below_frequency_floor"})
+            continue
+        if total >= int(min_corpus_docs):
+            df_ratio = df / total
+            if df_ratio > float(max_df_ratio):
+                remove.append({**entry, "df_ratio": round(df_ratio, 4), "reason": "low_idf_ubiquitous"})
+                continue
+        keep.append({**entry, "reason": "signal"})
+    return {"remove": remove, "keep": keep}
+
+
 # ── End-to-end helper ─────────────────────────────────────────────────────────
 
 
@@ -457,6 +593,11 @@ def auto_build_graph_overlay(
 
 
 __all__ = [
+    "RELATION_VERB_GROUPS",
+    "build_relation_verb_index",
+    "normalize_relation_verb",
+    "plan_relation_normalization",
+    "plan_concept_noise_reduction",
     "TopicCandidate",
     "PromotionDecision",
     "ThreadEdge",

package/lattice_brain/graph/documents.py

@@ -6,6 +6,117 @@ from ._kg_common import *  # noqa: F403,F401
 
 
 class KnowledgeGraphDocumentsMixin:
+    def find_documents_by_uri_prefix(self, prefix: str) -> List[Dict[str, Any]]:
+        """Content nodes whose ``metadata.source_uri`` starts with ``prefix``.
+
+        Powers removable seeded corpora (e.g. the ``demo://`` First Value Loop
+        documents): callers stamp a URI scheme at ingest time and can later
+        enumerate exactly those nodes without guessing ids.
+        """
+        prefix = str(prefix or "").strip()
+        if not prefix:
+            return []
+        nt, _ = self._read_tables()
+        documents: List[Dict[str, Any]] = []
+        with self._connect() as conn:
+            rows = conn.execute(
+                f"""
+                SELECT id, type, title, metadata_json, created_at, updated_at
+                FROM {nt}
+                WHERE json_extract(metadata_json, '$.source_uri') LIKE ? || '%'
+                  AND type NOT IN ('Source', 'Chunk')
+                ORDER BY created_at ASC, id ASC
+                """,
+                (prefix,),
+            ).fetchall()
+            for row in rows:
+                meta = _safe_loads(row["metadata_json"]) or {}
+                documents.append(
+                    {
+                        "id": row["id"],
+                        "type": row["type"],
+                        "title": row["title"],
+                        "source_uri": meta.get("source_uri"),
+                        "workspace_id": meta.get("workspace_id"),
+                        "created_at": row["created_at"],
+                        "updated_at": row["updated_at"],
+                    }
+                )
+        return documents
+
+    def delete_document_tree(self, node_id: str) -> Dict[str, Any]:
+        """Delete an ingested content node plus everything it owns.
+
+        Removes the node, its retrieval chunks (``chunks`` table + ``Chunk``
+        nodes), auto-extracted Task/Decision nodes whose ``source_node`` is
+        this document, every touching edge, the vector rows, and — when it
+        becomes orphaned — the linked ``Source`` node. Shared Concept nodes
+        are intentionally left alone (they may be cited by other content).
+        Mirrored into the v2 projection via ``_v2_delete_nodes``.
+        """
+        node_id = str(node_id or "").strip()
+        if not node_id:
+            return {"status": "skipped", "removed_nodes": 0}
+        with self._connect() as conn:
+            if not conn.execute(
+                "SELECT 1 FROM nodes WHERE id=?", (node_id,)
+            ).fetchone():
+                return {"status": "not_found", "node_id": node_id, "removed_nodes": 0}
+
+            remove_ids = {node_id}
+            # Owned children: chunks + auto-extracted semantic nodes that
+            # explicitly point back at this document via metadata.source_node.
+            for row in conn.execute(
+                """
+                SELECT id FROM nodes
+                WHERE json_extract(metadata_json, '$.source_node') = ?
+                """,
+                (node_id,),
+            ):
+                remove_ids.add(row["id"])
+            # The Source node this content was indexed from (if it ends up
+            # referenced by nothing else after the delete, drop it too).
+            source_ids = [
+                row["to_node"]
+                for row in conn.execute(
+                    "SELECT to_node FROM edges WHERE from_node=? AND type IN ('indexed_from', 'INDEXED_FROM')",
+                    (node_id,),
+                )
+            ]
+
+            ids = list(remove_ids)
+            ph = ",".join("?" * len(ids))
+            conn.execute(f"DELETE FROM chunks WHERE source_node IN ({ph})", ids)
+            conn.execute(
+                f"DELETE FROM edges WHERE from_node IN ({ph}) OR to_node IN ({ph})",
+                ids * 2,
+            )
+            conn.execute(
+                f"DELETE FROM vector_embeddings WHERE item_id IN ({ph}) OR source_node IN ({ph})",
+                ids * 2,
+            )
+            conn.execute(f"DELETE FROM nodes WHERE id IN ({ph})", ids)
+            self._v2_delete_nodes(conn, ids)
+
+            removed_sources = 0
+            for source_id in source_ids:
+                still_linked = conn.execute(
+                    "SELECT 1 FROM edges WHERE from_node=? OR to_node=? LIMIT 1",
+                    (source_id, source_id),
+                ).fetchone()
+                if still_linked:
+                    continue
+                conn.execute("DELETE FROM vector_embeddings WHERE item_id=?", (source_id,))
+                conn.execute("DELETE FROM nodes WHERE id=?", (source_id,))
+                self._v2_delete_nodes(conn, [source_id])
+                removed_sources += 1
+
+        return {
+            "status": "ok",
+            "node_id": node_id,
+            "removed_nodes": len(remove_ids) + removed_sources,
+        }
+
     def _ingest_structure_nodes(
         self,
         conn: sqlite3.Connection,