ltcai 9.9.5 → 9.9.9

package/lattice_brain/context.py

@@ -116,12 +116,19 @@ class ContextAssembler:
 
     Section priority (kept under budget in this order — semantic memories
     first because they are cheap and durable; recency last):
-      1. memories  — workspace semantic memories (preferences/decisions/…)
-      2. knowledge — hybrid search over the brain (the product's own engine)
-      3. notes     — garden-note context
-      4. recent    — the user's recent exchange
+      1. memories   — workspace semantic memories (preferences/decisions/…)
+      2. artifacts  — files this conversation just produced (v9.9.6)
+      3. knowledge  — hybrid search over the brain (the product's own engine)
+      4. notes      — garden-note context
+      5. recent     — the user's recent exchange
     Every seam is optional; an absent seam contributes nothing (honest
     absence), never a fabricated section.
+
+    The ``artifacts`` seam closes the re-search loop (review 2026-07-27 루프
+    §1): a file written moments ago may not be indexed yet — embedding and
+    graph writes are asynchronous — so asking "what did you just make?" could
+    miss it. The artifact ledger is a deterministic, high-priority section: it
+    does not depend on retrieval catching up.
     """
 
     def __init__(
@@ -131,11 +138,13 @@ class ContextAssembler:
         hybrid_search: Optional[Callable[..., Dict[str, Any]]] = None,
         notes_context: Optional[Callable[..., str]] = None,
         recent_chat: Optional[Callable[..., str]] = None,
+        recent_artifacts: Optional[Callable[..., List[Dict[str, Any]]]] = None,
     ) -> None:
         self._memory_recall = memory_recall
         self._hybrid_search = hybrid_search
         self._notes_context = notes_context
         self._recent_chat = recent_chat
+        self._recent_artifacts = recent_artifacts
 
     def assemble(
         self,
@@ -152,6 +161,8 @@ class ContextAssembler:
 
         if self._memory_recall is not None:
             sections.append(self._memories_section(query, user_email, workspace_id, memory_limit))
+        if self._recent_artifacts is not None:
+            sections.append(self._artifacts_section(user_email, conversation_id, workspace_id))
         if self._hybrid_search is not None:
             sections.append(self._knowledge_section(query, knowledge_limit, user_email, workspace_id))
         if self._notes_context is not None:
@@ -182,6 +193,30 @@ class ContextAssembler:
             ],
         )
 
+    def _artifacts_section(self, user_email, conversation_id, workspace_id) -> ContextSection:
+        """Files this conversation produced, whether or not retrieval indexed them yet."""
+        try:
+            items = _call_keyword_seam(
+                self._recent_artifacts,
+                user_email=user_email,
+                conversation_id=conversation_id,
+                workspace_id=workspace_id,
+            ) or []
+        except Exception as exc:
+            logging.debug("context: recent artifacts failed: %s", exc)
+            items = []
+        rows = [item for item in items if isinstance(item, dict) and item.get("path")][:10]
+        lines = [
+            f"- {item['path']}" + (f" ({item['at']})" if item.get("at") else "")
+            for item in rows
+        ]
+        return ContextSection(
+            name="Files created in this conversation",
+            content="\n".join(lines),
+            source="artifacts",
+            provenance=[{"path": item.get("path"), "run_id": item.get("run_id")} for item in rows],
+        )
+
     def _knowledge_section(self, query, limit, user_email=None, workspace_id=None) -> ContextSection:
         try:
             hybrid = _call_context_seam(

package/lattice_brain/graph/_kg_common.py

@@ -105,7 +105,10 @@ _CODE_CHUNK_EXTENSIONS = {
     ".c", ".h", ".cpp", ".css", ".sh", ".sql", ".vue", ".svelte",
     ".json", ".yaml", ".yml", ".toml",
 }
-_CHUNK_STRATEGIES = {"plain", "markdown", "code"}
+_PROSE_CHUNK_EXTENSIONS = {
+    ".txt", ".pdf", ".docx", ".doc", ".rtf", ".odt", ".epub", ".html", ".htm",
+}
+_CHUNK_STRATEGIES = {"plain", "markdown", "code", "prose"}
 # Markdown sections smaller than this merge forward into the next section so
 # heading-dense documents don't shatter into confetti chunks.
 _MARKDOWN_MIN_SECTION_CHARS = 200
@@ -120,9 +123,15 @@ def chunk_strategy_for(filename: Any, *, content_type: str = "") -> str:
     """Route a filename / path / URI (plus optional MIME hint) to a strategy.
 
     Returns ``"markdown"`` for .md/.markdown, ``"code"`` for known source-code
-    extensions, ``"plain"`` otherwise. Case-insensitive, tolerant of URLs
-    (query/fragment stripped) and ``Path`` objects; never raises — any
-    malformed input falls back to ``"plain"``.
+    extensions, ``"prose"`` for document formats whose text is running prose
+    (.txt/.pdf/.docx/.html/…), ``"plain"`` otherwise. Case-insensitive,
+    tolerant of URLs (query/fragment stripped) and ``Path`` objects; never
+    raises — any malformed input falls back to ``"plain"``.
+
+    Unknown/extension-less input stays ``"plain"`` on purpose: the plain
+    strategy is the byte-compatible legacy walk, and guessing prose for
+    something that might be a data dump would move chunk boundaries for no
+    retrieval gain.
     """
     try:
         name = str(filename or "").strip().lower()
@@ -135,8 +144,13 @@ def chunk_strategy_for(filename: Any, *, content_type: str = "") -> str:
             return "markdown"
         if ext in _CODE_CHUNK_EXTENSIONS:
             return "code"
-        if "markdown" in str(content_type or "").strip().lower():
+        if ext in _PROSE_CHUNK_EXTENSIONS:
+            return "prose"
+        mime = str(content_type or "").strip().lower()
+        if "markdown" in mime:
             return "markdown"
+        if mime.startswith("text/html") or mime.startswith("text/plain"):
+            return "prose"
     except Exception:
         pass
     return "plain"
@@ -324,6 +338,72 @@ def _code_chunks(cleaned: str, size: int, overlap: int) -> List[Dict[str, Any]]:
     return out
 
 
+# ── Prose chunking (review 2026-07-27 P1 #4) ────────────────────────────────
+# The plain walk cuts every ``size`` characters, which lands mid-sentence and
+# — for Korean, where the verb carrying the meaning sits at the end — routinely
+# splits a claim from its predicate. Retrieval then matches half a statement
+# and the citation shows a fragment. The prose strategy keeps the same window
+# budget but ends each chunk at the last sentence/paragraph boundary inside it.
+
+# Strong: sentence-final punctuation (ASCII + CJK) with optional closing
+# quotes/brackets, followed by whitespace; or a blank-line paragraph break.
+_PROSE_STRONG_BOUNDARY_RE = re.compile(
+    r"(?:[.!?。！？…]+[\"'”’」』\)\]]*\s+|\n[ \t]*\n)"
+)
+# Weak: a single line break. Korean notes and bullet lists often carry no
+# sentence punctuation at all; a line end is still a real boundary there.
+_PROSE_WEAK_BOUNDARY_RE = re.compile(r"\n")
+# Never emit a chunk shorter than this fraction of ``size`` just to hit a
+# boundary — tiny chunks hurt recall more than a mid-sentence cut.
+_PROSE_MIN_SPAN_RATIO = 0.5
+
+
+def _last_boundary(cleaned: str, lo: int, hi: int) -> Optional[int]:
+    """End offset of the last sentence/paragraph boundary in ``cleaned[lo:hi]``.
+
+    Strong boundaries win; a single line break is the fallback. Returns None
+    when the span holds neither, so the caller keeps the hard window cut.
+    """
+    window = cleaned[lo:hi]
+    for pattern in (_PROSE_STRONG_BOUNDARY_RE, _PROSE_WEAK_BOUNDARY_RE):
+        last = None
+        for match in pattern.finditer(window):
+            last = match.end()
+        if last:
+            return lo + last
+    return None
+
+
+def _prose_chunks(cleaned: str, size: int, overlap: int) -> List[Dict[str, Any]]:
+    out: List[Dict[str, Any]] = []
+    total = len(cleaned)
+    min_span = max(1, int(size * _PROSE_MIN_SPAN_RATIO))
+    start = 0
+    while start < total:
+        hard_end = min(total, start + size)
+        end = hard_end
+        if hard_end < total:
+            boundary = _last_boundary(cleaned, start + min_span, hard_end)
+            if boundary is not None and boundary > start:
+                end = boundary
+        out.append(
+            {
+                "text": cleaned[start:end],
+                "meta": {
+                    "strategy": "prose",
+                    "start_char": start,
+                    "heading_path": None,
+                },
+            }
+        )
+        if end >= total:
+            break
+        # Overlap carries the tail of the previous chunk into the next one so
+        # a claim split across a boundary is still retrievable from both.
+        start = max(start + 1, end - overlap)
+    return out
+
+
 def typed_chunks(
     text: str,
     *,
@@ -356,6 +436,8 @@ def typed_chunks(
         return _markdown_chunks(cleaned, size, overlap)
     if label == "code":
         return _code_chunks(cleaned, size, overlap)
+    if label == "prose":
+        return _prose_chunks(cleaned, size, overlap)
     return _plain_windows(cleaned, size, overlap)
 
 
@@ -377,6 +459,35 @@ def typed_chunk_meta_fields(piece: Dict[str, Any]) -> Dict[str, Any]:
     return fields
 
 
+def citation_locator(chunk_metadata: Any) -> str:
+    """Human "where in the document" label for one chunk, or "".
+
+    Built only from provenance the chunk actually carries — a section heading
+    path and/or a page number. When neither is known the answer is the empty
+    string, so a citation never claims a location it cannot prove.
+    """
+    if not isinstance(chunk_metadata, dict):
+        return ""
+    parts: List[str] = []
+    heading = str(chunk_metadata.get("heading_path") or "").strip()
+    if heading:
+        parts.append(heading)
+    def _page(key: str) -> int:
+        value = chunk_metadata.get(key)
+        try:
+            return int(value) if value is not None else 0
+        except (TypeError, ValueError):
+            return 0
+
+    page_number = _page("page")
+    if page_number > 0:
+        page_end = _page("page_end")
+        parts.append(
+            f"p.{page_number}–{page_end}" if page_end > page_number else f"p.{page_number}"
+        )
+    return " · ".join(parts)
+
+
 def pdf_page_offsets(structure: Any) -> List[int]:
     """Start offset of each PDF page in the "\\n\\n"-joined page text.
 
@@ -538,13 +649,27 @@ def _llm_extract_triples(
             triples = []
             for item in parsed[:limit]:
                 if isinstance(item, dict) and "subject" in item and "object" in item:
+                    relation = str(item.get("relation", "관련됨"))
+                    evidence_text = str(item.get("evidence", ""))[:240]
+                    confidence = float(item.get("confidence", 0.8))
+                    # An LLM triple that names a real verb and cites the
+                    # sentence it came from is semantic evidence; a bare
+                    # "관련됨" with no quoted evidence is the model restating
+                    # co-occurrence, and is weighted (and labelled) as such.
+                    is_semantic = bool(evidence_text) and relation != "관련됨"
                     triples.append(
                         {
                             "subject": str(item["subject"]),
-                            "relation": str(item.get("relation", "관련됨")),
+                            "relation": relation,
                             "object": str(item["object"]),
-                            "context": str(item.get("evidence", ""))[:240],
-                            "confidence": float(item.get("confidence", 0.8)),
+                            "context": evidence_text,
+                            "confidence": confidence,
+                            "evidence": "verb" if is_semantic else "cooccurrence",
+                            "weight": round(
+                                (VERB_EDGE_WEIGHT if is_semantic else COOCCURRENCE_EDGE_WEIGHT)
+                                * max(0.1, min(confidence, 1.0)),
+                                4,
+                            ),
                         }
                     )
             return triples if triples else None
@@ -820,13 +945,52 @@ EDGE_VERB = {
 }
 
 
-def _infer_edge(sentence: str) -> str:
-    """Return the best-matching verb-form edge label for a sentence."""
-    s = sentence.lower()
+# Concepts in a list-like sentence ("A, B, C, D를 사용한다") sit together by
+# enumeration, not by relation. Beyond this many concepts in one sentence, a
+# verb-less pairing is enumeration noise and is dropped outright.
+COOCCURRENCE_CONCEPT_LIMIT = 4
+# Verb-backed relations carry the sentence's own evidence; co-occurrence
+# relations carry only adjacency, so they enter the graph at a lower weight
+# and are labelled as such.
+VERB_EDGE_WEIGHT = 1.0
+COOCCURRENCE_EDGE_WEIGHT = 0.35
+
+
+def infer_edge_relation(sentence: str) -> Dict[str, Any]:
+    """Classify the relation between two concepts in one sentence.
+
+    Review 2026-07-27 P1 #6: the graph drifted toward co-occurrence because a
+    verb-less sentence still produced a "관련됨" edge indistinguishable from a
+    real semantic relation. The label alone cannot carry that difference, so
+    the evidence class rides with it::
+
+        {"relation": "사용함", "evidence": "verb",         "weight": 1.0}
+        {"relation": "관련됨", "evidence": "cooccurrence", "weight": 0.35}
+
+    ``evidence`` is what the graph, the curator, and the UI use to tell a
+    meaning edge from an adjacency edge — the honest distinction the previous
+    label-only output erased.
+    """
+    s = str(sentence or "").lower()
     for label, pattern in EDGE_VERB.items():
         if re.search(pattern, s):
-            return label
-    return "관련됨"
+            # "관련됨" is itself a weak, generic label: matching it by keyword
+            # ("관련", "related") is still verb evidence, but nothing stronger.
+            return {
+                "relation": label,
+                "evidence": "verb",
+                "weight": VERB_EDGE_WEIGHT,
+            }
+    return {
+        "relation": "관련됨",
+        "evidence": "cooccurrence",
+        "weight": COOCCURRENCE_EDGE_WEIGHT,
+    }
+
+
+def _infer_edge(sentence: str) -> str:
+    """Back-compat wrapper: the verb label only (see :func:`infer_edge_relation`)."""
+    return infer_edge_relation(sentence)["relation"]
 
 
 # Technical words that cannot be person names
@@ -940,7 +1104,16 @@ def _extract_triples_rules(
         if len(present) < 2:
             continue
 
-        edge = _infer_edge(sent)
+        relation = infer_edge_relation(sent)
+        edge = relation["relation"]
+        # Enumeration guard (review 2026-07-27 P1 #6): a verb-less sentence
+        # listing many concepts is a list, not a set of relations. Verb-backed
+        # sentences keep every pair — the verb is the evidence.
+        if (
+            relation["evidence"] == "cooccurrence"
+            and len(present) > COOCCURRENCE_CONCEPT_LIMIT
+        ):
+            continue
 
         for i in range(len(present) - 1):
             subj, obj = present[i], present[i + 1]
@@ -955,6 +1128,8 @@ def _extract_triples_rules(
                     "relation": edge,  # verb form (동사)
                     "object": obj,
                     "context": sent[:240],
+                    "evidence": relation["evidence"],
+                    "weight": relation["weight"],
                 }
             )
             if len(triples) >= limit:

package/lattice_brain/graph/curator.py

@@ -548,6 +548,68 @@ def plan_concept_noise_reduction(
     return {"remove": remove, "keep": keep}
 
 
+def plan_relation_noise_reduction(
+    edges: Iterable[Dict[str, Any]],
+    *,
+    min_cooccurrence_weight: float = 0.3,
+    max_cooccurrence_degree: int = 12,
+) -> Dict[str, List[Dict[str, Any]]]:
+    """Separate meaning edges from adjacency edges (review 2026-07-27 P1 #6).
+
+    ``edges``: ``[{"id", "from", "to", "type", "weight", "evidence", "degree"}]``
+    where ``evidence`` is the class recorded at ingest (``"verb"`` |
+    ``"cooccurrence"``) and ``degree`` is how many co-occurrence edges the
+    source node already carries.
+
+    Rules (pure decision, dry-run friendly):
+
+    * verb-backed edges are **never** demoted — the sentence carried a real
+      relation;
+    * edges with no recorded evidence class are legacy rows: kept, and marked
+      ``unknown_evidence`` rather than guessed at;
+    * co-occurrence edges below ``min_cooccurrence_weight`` are noise;
+    * a node whose co-occurrence degree exceeds ``max_cooccurrence_degree`` is
+      a hub built by adjacency, not meaning — its extra co-occurrence edges
+      are demoted.
+
+    Returns ``{"keep": [...], "demote": [...]}``. "Demote" is deliberate:
+    these edges are candidates for review, not silent deletion.
+    """
+    keep: List[Dict[str, Any]] = []
+    demote: List[Dict[str, Any]] = []
+    for edge in edges:
+        entry = {
+            "id": str(edge.get("id") or ""),
+            "from": edge.get("from"),
+            "to": edge.get("to"),
+            "type": edge.get("type"),
+            "evidence": str(edge.get("evidence") or ""),
+        }
+        try:
+            entry["weight"] = float(edge.get("weight") or 0.0)
+        except (TypeError, ValueError):
+            entry["weight"] = 0.0
+        try:
+            degree = int(edge.get("degree") or 0)
+        except (TypeError, ValueError):
+            degree = 0
+        entry["degree"] = degree
+        if entry["evidence"] == "verb":
+            keep.append({**entry, "reason": "verb_evidence"})
+            continue
+        if not entry["evidence"]:
+            keep.append({**entry, "reason": "unknown_evidence"})
+            continue
+        if entry["weight"] < float(min_cooccurrence_weight):
+            demote.append({**entry, "reason": "weak_cooccurrence"})
+            continue
+        if degree > int(max_cooccurrence_degree):
+            demote.append({**entry, "reason": "cooccurrence_hub"})
+            continue
+        keep.append({**entry, "reason": "cooccurrence_within_budget"})
+    return {"keep": keep, "demote": demote}
+
+
 # ── End-to-end helper ─────────────────────────────────────────────────────────
 
 

package/lattice_brain/graph/discovery.py

@@ -454,6 +454,82 @@ class KnowledgeGraphDiscoveryMixin:
             source["file_status"] = counts.get(source["id"], {})
         return {"sources": sources}
 
+    def local_source_health(self, *, error_samples: int = 3) -> Dict[str, Any]:
+        """Per-folder memory state (v9.9.7).
+
+        ``local_sources`` answers "which folders are connected"; a user asking
+        "is this folder actually in my Brain?" needs three more facts per
+        folder, and this is the single read that provides them:
+
+        * **coverage** — indexed / known files, so a half-indexed folder is
+          visible instead of looking connected;
+        * **failed / skipped counts** — what did not make it in;
+        * **recent error samples** — *why*, with the stored message.
+
+        Vector freshness is deliberately **not** claimed per folder: the vector
+        index is global, so a per-folder number would be invented. Callers pair
+        this with ``vector_freshness()`` and label it as global.
+        """
+        try:
+            samples = max(0, min(int(error_samples), 20))
+        except (TypeError, ValueError):
+            samples = 3
+        payload = self.local_sources()
+        sources = payload.get("sources") or []
+        by_id = {str(source.get("id")): source for source in sources}
+        errors: Dict[str, List[Dict[str, Any]]] = {}
+        if by_id:
+            with self._connect() as conn:
+                for source_id in by_id:
+                    rows = conn.execute(
+                        """
+                            SELECT relative_path, status, error_message, last_scanned_at
+                            FROM local_file_index
+                            WHERE source_id=? AND error_message IS NOT NULL AND error_message<>''
+                            ORDER BY last_scanned_at DESC
+                            LIMIT ?
+                            """,
+                        (source_id, samples or 1),
+                    ).fetchall()
+                    if samples:
+                        errors[source_id] = [
+                            {
+                                "path": row["relative_path"],
+                                "status": row["status"],
+                                "detail": str(row["error_message"] or "")[:300],
+                                "at": row["last_scanned_at"],
+                            }
+                            for row in rows
+                        ]
+
+        folders: List[Dict[str, Any]] = []
+        for source in sources:
+            counts = source.get("file_status") or {}
+            total = sum(int(value or 0) for value in counts.values())
+            indexed = int(counts.get("indexed") or 0)
+            failed = int(counts.get("failed") or 0) + int(counts.get("error") or 0)
+            skipped = int(counts.get("skipped") or 0)
+            folders.append({
+                "id": source.get("id"),
+                "label": source.get("label") or source.get("root_path"),
+                "root_path": source.get("root_path"),
+                "status": source.get("status"),
+                "watch_enabled": bool(source.get("watch_enabled")),
+                "last_scanned_at": source.get("last_scanned_at"),
+                "files": {
+                    "total": total,
+                    "indexed": indexed,
+                    "failed": failed,
+                    "skipped": skipped,
+                    "pending": max(0, total - indexed - failed - skipped),
+                },
+                # None (not 0) when nothing is known yet — an empty folder must
+                # not read as "0% indexed".
+                "coverage": round(indexed / total, 4) if total else None,
+                "recent_errors": errors.get(str(source.get("id")), []),
+            })
+        return {"folders": folders, "count": len(folders)}
+
     def set_local_source_watch(self, source_id: str, enabled: bool) -> Dict[str, Any]:
         source_id = str(source_id or "").strip()
         if not source_id:

package/lattice_brain/graph/ingest.py

@@ -19,6 +19,27 @@ def _scoped_hash_id(prefix: str, value: str, workspace_id: Optional[str]) -> str
     return f"{prefix}:{_sha256_text(identity)[:24]}"
 
 
+def _triple_edge_metadata(triple: Dict[str, Any]) -> Dict[str, Any]:
+    """Edge metadata that keeps the relation's evidence class visible.
+
+    Review 2026-07-27 P1 #6: a verb-backed relation and a bare co-occurrence
+    used to land in the graph identically. ``evidence`` travels with the edge
+    so readers (graph views, curator, promotion review) can tell a meaning
+    edge from an adjacency edge instead of guessing from the label.
+    """
+    metadata: Dict[str, Any] = {"context": str(triple.get("context") or "")[:240]}
+    evidence = str(triple.get("evidence") or "")
+    if evidence:
+        metadata["evidence"] = evidence
+    confidence = triple.get("confidence")
+    if confidence is not None:
+        try:
+            metadata["confidence"] = round(float(confidence), 4)
+        except (TypeError, ValueError):
+            pass
+    return metadata
+
+
 class KnowledgeGraphIngestMixin:
     def ingest_message(
         self,
@@ -168,8 +189,8 @@ class KnowledgeGraphIngestMixin:
                         subj_id,
                         obj_id,
                         triple["relation"],  # 동사형 레이블
-                        weight=1.0,
-                        metadata={"context": triple.get("context", "")[:240]},
+                        weight=float(triple.get("weight") or 1.0),
+                        metadata=_triple_edge_metadata(triple),
                     )
 
             # ── 7. Task / Decision 노드  (점: 명사) ────────────────────────────
@@ -342,9 +363,18 @@ class KnowledgeGraphIngestMixin:
                 chunk = piece["text"]
                 chunk_fields = typed_chunk_meta_fields(piece)
                 if page_offsets:
-                    page = page_for_offset(page_offsets, chunk_fields["start_char"])
+                    start_char = chunk_fields["start_char"]
+                    page = page_for_offset(page_offsets, start_char)
                     if page is not None:
                         chunk_fields["page"] = page
+                        # Sentence-aware chunks can straddle a page break, so
+                        # the start page alone would under-describe them.
+                        # `page_end` is recorded only when it really differs.
+                        end_page = page_for_offset(
+                            page_offsets, max(start_char, start_char + len(chunk) - 1)
+                        )
+                        if end_page is not None and end_page > page:
+                            chunk_fields["page_end"] = end_page
                 chunk_id = f"chunk:{_sha256_text(f'{file_id}:{index}:{chunk}')[:24]}"
                 chunk_ids.append(chunk_id)
                 self._upsert_node(
@@ -394,8 +424,8 @@ class KnowledgeGraphIngestMixin:
                         subj_id,
                         obj_id,
                         triple["relation"],
-                        weight=1.0,
-                        metadata={"context": triple.get("context", "")[:240]},
+                        weight=float(triple.get("weight") or 1.0),
+                        metadata=_triple_edge_metadata(triple),
                     )
 
             # ── Task / Decision 노드 ──────────────────────────────────────────
@@ -735,8 +765,8 @@ class KnowledgeGraphIngestMixin:
                         subj_id,
                         obj_id,
                         triple["relation"],
-                        weight=1.0,
-                        metadata={"context": triple.get("context", "")[:240]},
+                        weight=float(triple.get("weight") or 1.0),
+                        metadata=_triple_edge_metadata(triple),
                     )
             # ── Task / Decision 노드 ────────────────────────────────────────
             for item in _semantic_items(text):

package/lattice_brain/graph/retrieval_vector.py

@@ -657,6 +657,7 @@ class KnowledgeGraphVectorMixin:
                       n.type AS node_type, n.title AS node_title, n.summary AS node_summary,
                       n.metadata_json AS node_metadata, n.updated_at AS node_updated_at,
                       c.text AS chunk_text, c.source_node AS parent_node_id,
+                      c.metadata_json AS chunk_metadata,
                       pn.type AS parent_type, pn.title AS parent_title,
                       pn.summary AS parent_summary, pn.metadata_json AS parent_metadata,
                       pn.updated_at AS parent_updated_at
@@ -690,6 +691,13 @@ class KnowledgeGraphVectorMixin:
             )
             parent_metadata = _safe_loads(row["parent_metadata"])
             node_metadata = _safe_loads(row["node_metadata"])
+            # Citation precision (review 2026-07-27 P1 #4): a chunk hit used to
+            # cite only its parent document, so a 200-page PDF answered with
+            # "from report.pdf". The chunk's own provenance (section heading,
+            # page, offset) now rides along, and `locator` is the one-line
+            # human form — absent when the chunk carries no such metadata.
+            chunk_metadata = _safe_loads(row["chunk_metadata"]) if is_chunk else {}
+            locator = citation_locator(chunk_metadata)
             scored.append(
                 {
                     "id": row["item_id"],
@@ -708,6 +716,8 @@ class KnowledgeGraphVectorMixin:
                         "vector": _safe_loads(row["vector_metadata"]),
                         "parent_node_id": row["parent_node_id"],
                         "parent_type": row["parent_type"],
+                        **({"chunk": chunk_metadata} if chunk_metadata else {}),
+                        **({"locator": locator} if locator else {}),
                     },
                     "updated_at": row["parent_updated_at"]
                     if is_chunk and row["parent_updated_at"]