arkaos 4.22.0 → 4.24.0

package/core/synapse/kb_cache.py

@@ -20,6 +20,7 @@ Turn-scoped marker (record_obsidian_query / read_obsidian_query):
       as core.workflow.marker_cache).
 """
 
+import contextlib
 import hashlib
 import json
 import os
@@ -27,12 +28,11 @@ import threading
 import time
 import uuid
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any
 
 from core.shared import safe_session_id as _safe_session_id_module
 from core.shared.temp_paths import arkaos_temp_dir
 
-
 # Re-export for backward compatibility with any external importers.
 SAFE_SESSION_ID_RE = _safe_session_id_module.SAFE_SESSION_ID_RE
 KB_QUERY_MARKER_DIR = arkaos_temp_dir("arkaos-kb-query")
@@ -147,8 +147,8 @@ class KBSessionCache:
     def __init__(
         self,
         session_id: str,
-        project_path: Optional[str] = None,
-        cache_dir: Optional[str] = None,
+        project_path: str | None = None,
+        cache_dir: str | None = None,
         max_entries: int = 150,
         ttl_seconds: int = 5400,
     ) -> None:
@@ -278,8 +278,8 @@ class KBSessionCache:
 
     def retrieve(
         self,
-        query: Optional[str] = None,
-        topics: Optional[set[str]] = None,
+        query: str | None = None,
+        topics: set[str] | None = None,
         threshold: float = 0.3,
     ) -> list[dict]:
         """Retrieve cached knowledge by query or topic overlap.
@@ -433,11 +433,44 @@ def _kb_query_dir() -> Path:
     return KB_QUERY_MARKER_DIR
 
 
-def _kb_query_path(session_id: str) -> Optional[Path]:
+def _kb_query_path(session_id: str, kind: str = "obsidian") -> Path | None:
+    """Turn-scoped marker path for one KB source.
+
+    ``kind`` separates the sources so a graphify consult cannot satisfy a
+    check that asked about Obsidian, or vice versa. "obsidian" keeps the
+    historical unsuffixed filename so existing records stay readable.
+    """
     safe = _safe_session_id_module.safe_session_id(session_id)
     if safe is None:
         return None
-    return _kb_query_dir() / f"{safe}.json"
+    suffix = "" if kind == "obsidian" else f".{kind}"
+    return _kb_query_dir() / f"{safe}{suffix}.json"
+
+
+def record_graphify_query(session_id: str, query: str, hit_count: int = 0) -> None:
+    """Record that a Graphify graph query ran in this turn.
+
+    Counterpart to :func:`record_obsidian_query`. Without it the ``[graph:``
+    citation marker is pure narration — anyone can type ``[graph: MadeUpNode]``
+    and earn credit (QG review). A consumer that wants evidence rather than a
+    claim should require :func:`graphify_queried_this_turn` alongside it.
+    """
+    _record_query(session_id, query, hit_count, kind="graphify")
+
+
+def read_graphify_query(session_id: str) -> dict | None:
+    """Return the turn-scoped Graphify-query record, or None if absent."""
+    return _read_query(session_id, kind="graphify")
+
+
+def graphify_queried_this_turn(session_id: str) -> bool:
+    """True iff ``record_graphify_query`` was called since turn start."""
+    return read_graphify_query(session_id) is not None
+
+
+def invalidate_graphify_query(session_id: str) -> None:
+    """Clear the per-turn Graphify consult marker. Idempotent."""
+    _invalidate_query(session_id, kind="graphify")
 
 
 def record_obsidian_query(session_id: str, query: str, hit_count: int = 0) -> None:
@@ -455,7 +488,12 @@ def record_obsidian_query(session_id: str, query: str, hit_count: int = 0) -> No
         query: The query string that was executed.
         hit_count: Number of notes returned (0 means search ran but empty).
     """
-    path = _kb_query_path(session_id)
+    _record_query(session_id, query, hit_count, kind="obsidian")
+
+
+def _record_query(session_id: str, query: str, hit_count: int, kind: str) -> None:
+    """Shared writer for every KB source marker. Atomic tmp+rename."""
+    path = _kb_query_path(session_id, kind)
     if path is None:
         return
     safe_query = (query or "")[:_MAX_QUERY_LEN]
@@ -464,7 +502,7 @@ def record_obsidian_query(session_id: str, query: str, hit_count: int = 0) -> No
     except (TypeError, ValueError):
         hits = 0
     now = time.time()
-    existing = read_obsidian_query(session_id) or {}
+    existing = _read_query(session_id, kind) or {}
     queries_raw = existing.get("queries")
     queries = list(queries_raw) if isinstance(queries_raw, list) else []
     queries.append({"query": safe_query, "hit_count": hits, "ts": now})
@@ -472,6 +510,7 @@ def record_obsidian_query(session_id: str, query: str, hit_count: int = 0) -> No
         queries = queries[-_MAX_QUERIES_PER_TURN:]
     record = {
         "session_id": session_id,
+        "kind": kind,
         "queries": queries,
         "last_query_ts": now,
         "last_hit_count": hits,
@@ -483,15 +522,18 @@ def record_obsidian_query(session_id: str, query: str, hit_count: int = 0) -> No
         tmp.write_text(json.dumps(record), encoding="utf-8")
         os.replace(tmp, path)
     except OSError:
-        try:
+        with contextlib.suppress(FileNotFoundError):
             tmp.unlink()
-        except FileNotFoundError:
-            pass
 
 
-def read_obsidian_query(session_id: str) -> Optional[dict]:
+def read_obsidian_query(session_id: str) -> dict | None:
     """Return the turn-scoped Obsidian-query record, or None if absent."""
-    path = _kb_query_path(session_id)
+    return _read_query(session_id, kind="obsidian")
+
+
+def _read_query(session_id: str, kind: str) -> dict | None:
+    """Shared reader for every KB source marker."""
+    path = _kb_query_path(session_id, kind)
     if path is None or not path.exists():
         return None
     try:
@@ -510,7 +552,12 @@ def obsidian_queried_this_turn(session_id: str) -> bool:
 
 def invalidate_obsidian_query(session_id: str) -> None:
     """Clear the per-turn KB consult marker. Idempotent."""
-    path = _kb_query_path(session_id)
+    _invalidate_query(session_id, kind="obsidian")
+
+
+def _invalidate_query(session_id: str, kind: str) -> None:
+    """Shared invalidator for every KB source marker."""
+    path = _kb_query_path(session_id, kind)
     if path is None:
         return
     try:

package/core/synapse/layers.py

@@ -28,20 +28,20 @@ from typing import Any
 from core.synapse.layers_base import Layer, LayerResult, PromptContext
 
 __all__ = [
-    "Layer",
-    "LayerResult",
-    "PromptContext",
-    "ConstitutionLayer",
-    "DepartmentLayer",
     "AgentLayer",
-    "ProjectLayer",
     "BranchLayer",
     "CommandHintsLayer",
-    "QualityGateLayer",
-    "KnowledgeRetrievalLayer",
+    "ConstitutionLayer",
+    "DepartmentLayer",
     "ForgeContextLayer",
-    "SessionContextLayer",
     "KBContextLayer",
+    "KnowledgeRetrievalLayer",
+    "Layer",
+    "LayerResult",
+    "ProjectLayer",
+    "PromptContext",
+    "QualityGateLayer",
+    "SessionContextLayer",
 ]
 
 
@@ -90,22 +90,75 @@ class ConstitutionLayer(Layer):
 # --- L1: Department Detection ---
 
 DEPARTMENT_PATTERNS: dict[str, str] = {
-    "dev": r"\b(build|code|feature|deploy|test|review|scaffold|debug|refactor|api|migration|stack|implement|fix|bug)\b",
-    "marketing": r"\b(social|content|campaign|post|instagram|linkedin|twitter|tiktok|seo|marketing|ads|email.?campaign|growth|viral)\b",
-    "finance": r"\b(budget|invoice|revenue|forecast|profit|loss|roi|margin|cash.?flow|financial|invest|valuation|pricing)\b",
-    "ecom": r"\b(store|product|shop|shopify|ecommerce|catalog|inventory|cart|checkout|pricing|marketplace)\b",
-    "strategy": r"\b(strategy|brainstorm|market|swot|competitors?|roadmap|pivot|growth|porter|blue.?ocean|positioning)\b",
+    "dev": (
+        r"\b("
+        r"build|code|feature|deploy|test|review|scaffold|"
+        r"debug|refactor|api|migration|stack|implement|fix|"
+        r"bug)\b"
+    ),
+    "marketing": (
+        r"\b("
+        r"social|content|campaign|post|instagram|linkedin|"
+        r"twitter|tiktok|seo|marketing|ads|email.?campaign|"
+        r"growth|viral)\b"
+    ),
+    "finance": (
+        r"\b("
+        r"budget|invoice|revenue|forecast|profit|loss|roi|"
+        r"margin|cash.?flow|financial|invest|valuation|"
+        r"pricing)\b"
+    ),
+    "ecom": (
+        r"\b("
+        r"store|product|shop|shopify|ecommerce|catalog|"
+        r"inventory|cart|checkout|pricing|marketplace)\b"
+    ),
+    "strategy": (
+        r"\b("
+        r"strategy|brainstorm|market|swot|competitors?|"
+        r"roadmap|pivot|growth|porter|blue.?ocean|"
+        r"positioning)\b"
+    ),
     "ops": r"\b(task|automate|meeting|workflow|process|schedule|sop|integration|zapier|n8n)\b",
     "kb": r"\b(learn|persona|knowledge|youtube|transcribe|article|research|zettelkasten|note)\b",
-    "brand": r"\b(brand|logo|colors|palette|mockup|photoshoot|brand.?identity|brand.?guide|mood.?board|naming|visual.?design|motion|ux|ui|wireframe)\b",
+    "brand": (
+        r"\b("
+        r"brand|logo|colors|palette|mockup|photoshoot|brand.?identity|"
+        r"brand.?guide|mood.?board|naming|visual.?design|motion|ux|ui|"
+        r"wireframe)\b"
+    ),
     "saas": r"\b(saas|micro.?saas|plg|freemium|churn|mrr|arr|subscription|onboarding|metrics)\b",
-    "landing": r"\b(landing|funnel|copy|headline|offer|launch|affiliate|webinar|conversion|sales.?page)\b",
-    "community": r"\b(community|group|membership|discord|telegram|skool|circle|gamification|engagement)\b",
+    "landing": (
+        r"\b("
+        r"landing|funnel|copy|headline|offer|launch|"
+        r"affiliate|webinar|conversion|sales.?page)\b"
+    ),
+    "community": (
+        r"\b("
+        r"community|group|membership|discord|"
+        r"telegram|skool|circle|gamification|"
+        r"engagement)\b"
+    ),
     "content": r"\b(viral|hook|script|repurpose|youtube|tiktok|reels|shorts|newsletter|creator)\b",
     "pm": r"\b(sprint|backlog|standup|retro|scrum|kanban|story|estimate|roadmap|agile)\b",
-    "lead": r"\b(leadership|delegation|1on1|feedback|culture|hiring|performance.?review|team.?build)\b",
-    "sales": r"\b(pipeline|proposal|discovery.?call|objection|negotiate|deal|close|prospect|spin|challenger|cold.?email|outreach)\b",
-    "org": r"\b(org.?design|hiring.?plan|onboarding|remote|meeting.?optimize|compensation|decision.?framework)\b",
+    "lead": (
+        r"\b("
+        r"leadership|delegation|1on1|feedback|"
+        r"culture|hiring|performance.?review|"
+        r"team.?build)\b"
+    ),
+    "sales": (
+        r"\b("
+        r"pipeline|proposal|discovery.?call|objection|negotiate|"
+        r"deal|close|prospect|spin|challenger|cold.?email|"
+        r"outreach)\b"
+    ),
+    "org": (
+        r"\b("
+        r"org.?design|hiring.?plan|onboarding|remote|"
+        r"meeting.?optimize|compensation|"
+        r"decision.?framework)\b"
+    ),
 }
 
 
@@ -317,10 +370,7 @@ class BranchLayer(Layer):
         start = time.time()
         branch = ctx.git_branch
         # Hide main/master/dev branches
-        if branch in ("main", "master", "dev", ""):
-            tag = ""
-        else:
-            tag = f"[branch:{branch}]"
+        tag = "" if branch in ("main", "master", "dev", "") else f"[branch:{branch}]"
 
         ms = int((time.time() - start) * 1000)
         return LayerResult(
@@ -427,7 +477,7 @@ class QualityGateLayer(Layer):
     def compute(self, ctx: PromptContext) -> LayerResult:
         start = time.time()
         try:
-            from core.governance.quality_api import list_pending, list_approved
+            from core.governance.quality_api import list_approved, list_pending
 
             pending = list_pending()
             approved = list_approved(limit=3)
@@ -496,6 +546,17 @@ class KnowledgeRetrievalLayer(Layer):
     def cache_ttl(self) -> int:
         return 30
 
+    @property
+    def emits_block(self) -> bool:
+        """The retrieved chunks are a real block, not the tag's value.
+
+        `[knowledge:N chunks]` makes a QUANTIFIED claim about content the
+        model never received before the content channel existed — the
+        loudest unbacked claim in the tag line (QG review). Opting in
+        delivers what the tag advertises.
+        """
+        return True
+
     @property
     def priority(self) -> int:
         return 35
@@ -580,7 +641,10 @@ class KnowledgeRetrievalLayer(Layer):
                 parts.append(f"[cached] {src}: {text}" if src else f"[cached] {text}")
         parts.extend(snippets)
 
-        content = " | ".join(parts)
+        # Self-naming, because the content channel delivers this verbatim to
+        # the model: an unlabelled `[cached] file.md: …` fragment would read
+        # as stray text (the exact defect the opt-in channel exists to avoid).
+        content = f"[arka:knowledge] {' | '.join(parts)}" if parts else ""
         chunk_count = len(snippets) + (len(overlapping) if overlapping else 0)
         # RAG honesty (PR-3 v4.1): keyword-degraded results must never be
         # presented as semantic similarity — label the tag explicitly.
@@ -639,7 +703,7 @@ class ForgeContextLayer(Layer):
         parts = [f"Forge plan: {plan.id} ({plan.status.value})"]
         if plan.critic.confidence > 0:
             decisions = []
-            for source, elements in plan.critic.synthesis.items():
+            for _source, elements in plan.critic.synthesis.items():
                 decisions.extend(elements)
             if decisions:
                 parts.append(f"Decisions: {'; '.join(decisions[:5])}")
@@ -701,7 +765,6 @@ class SessionContextLayer(Layer):
                 layer_id=self.id, tag="", content="", tokens_est=0, compute_ms=0, cached=False
             )
 
-        lines = content.split("\n")
         tag = "[session:resume]"
         tokens = len(content.split())
 
@@ -720,6 +783,8 @@ class SessionContextLayer(Layer):
 # `core.synapse.layers` import paths and helper references keep working.
 
 from core.synapse.layers_kb import (  # noqa: E402,F401
+    _KB_CONFIG_PATH,
+    _MAX_FALLBACK_NOTES,
     KBContextLayer,
     _apply_grounding_policy,
     _build_note_entry,
@@ -732,10 +797,8 @@ from core.synapse.layers_kb import (  # noqa: E402,F401
     _hit_is_inferred,
     _jaccard,
     _jaccard_fallback,
-    _KB_CONFIG_PATH,
     _l25_feature_flag_on,
     _load_fallback_notes,
-    _MAX_FALLBACK_NOTES,
     _note_from_vector_hit,
     _tokenize_for_jaccard,
     _vector_search,

package/core/synapse/layers_base.py

@@ -69,6 +69,22 @@ class Layer(ABC):
         """
         return False
 
+    @property
+    def emits_block(self) -> bool:
+        """True when ``content`` is a self-describing full-text block.
+
+        OPT-IN, and deliberately so. The engine forwards ``content`` to the
+        model only for layers that declare this. Inferring it from
+        ``content != tag`` looked equivalent and was not: most layers set
+        ``content`` to their tag's VALUE (``dev``, ``active``,
+        ``feat/plan-canvas``), so every prompt gained stray unlabeled lines
+        carrying nothing the tag had not already said (QG review).
+
+        A block must stand alone: it names itself (``[arka:kb-context]``,
+        ``[arka:graph-remote unverified]``) and is meaningful without the tag.
+        """
+        return False
+
     @property
     def session_sensitive(self) -> bool:
         """True when compute() has per-session side effects or output.