nexo-brain 6.1.0 → 6.3.0

package/src/enforcement_engine.py

@@ -63,6 +63,16 @@ except ImportError:  # pragma: no cover
     _R17_PROMPT = ""  # type: ignore
     _R17_WINDOW = 2
 
+try:
+    from r_catalog import should_inject_r_catalog as _r_catalog_should
+except ImportError:  # pragma: no cover
+    _r_catalog_should = None  # type: ignore
+
+try:
+    from r34_identity_coherence import should_inject_r34 as _r34_should
+except ImportError:  # pragma: no cover
+    _r34_should = None  # type: ignore
+
 try:
     from r20_constant_change import (
         should_inject_r20 as _r20_should,
@@ -812,6 +822,15 @@ class HeadlessEnforcer:
         decision = _r15_should(text or "", project_list, records)
         if not decision:
             return
+        # T4.2 — LLM gate: if the classifier says the turn is
+        # conversational / off-topic, skip the injection. Regex wins on
+        # "unknown" so legitimate R15 hits still fire without a working
+        # classifier.
+        if self._t4_gate_says_no("R15", span=(text or "")[:400]):
+            _logger.info(
+                "[R15 T4] gate=no, skipping project=%s", decision["project"]
+            )
+            return
         prompt = _R15_PROMPT.format(project=decision["project"])
         if mode == "shadow":
             _logger.info("[R15 SHADOW] would inject: project=%s", decision["project"])
@@ -819,6 +838,70 @@ class HeadlessEnforcer:
         self._enqueue(prompt, decision["tag"], rule_id="R15_project_context")
         _logger.info("[R15 %s] enqueued project=%s", mode.upper(), decision["project"])
 
+    # ------------------------------------------------------------------
+    # T4 LLM gate — central helper (Plan Consolidado T4.2-T4.6).
+    # ------------------------------------------------------------------
+    def _t4_gate_says_no(self, rule_id: str, *, span: str, context: str = "") -> bool:
+        """Return True ONLY when the T4 classifier explicitly votes "no"
+        for this rule hit. "yes" or "unknown" (classifier unavailable,
+        import error, rate limit, parse failure) fall through to regex
+        behaviour — never silently suppress a rule on infra flakiness.
+
+        Every unavailable-path logs a WARNING once per (rule_id, reason)
+        via ``_t4_gate_warned`` so degradations surface in the console
+        without flooding it.
+        """
+        if not hasattr(self, "_t4_gate_warned"):
+            self._t4_gate_warned = set()
+        try:
+            from t4_llm_gate import build_prompt, classify_with_llm
+            from enforcement_classifier import classify as _classifier_raw
+        except Exception as exc:
+            key = (rule_id, f"import:{exc.__class__.__name__}")
+            if key not in self._t4_gate_warned:
+                self._t4_gate_warned.add(key)
+                _logger.warning("[T4 gate] import failed for %s: %s", rule_id, exc)
+            return False
+
+        # Auditor H1 fix: the legacy bool contract of `classify` collapses
+        # "classifier said no" and "classifier response unparseable after
+        # two retries — conservative fallback" into the same False, which
+        # would silently suppress destructive rules (R23e/R23f/R23h) when
+        # the backend responds with garbage. Force the tristate path so
+        # "unknown" falls through to regex behaviour instead of becoming
+        # a silent rule disable.
+        def _classifier_tristate(q: str, ctx: str) -> str:
+            return _classifier_raw(q, ctx, tristate=True)
+
+        prompt = build_prompt(rule_id, span=span, context=context)
+        if not prompt:
+            key = (rule_id, "no-prompt")
+            if key not in self._t4_gate_warned:
+                self._t4_gate_warned.add(key)
+                _logger.warning(
+                    "[T4 gate] no prompt template for rule_id=%s (check PROMPTS)",
+                    rule_id,
+                )
+            return False
+        try:
+            verdict = classify_with_llm(
+                rule_id,
+                prompt=prompt,
+                context=context,
+                classifier=_classifier_tristate,
+            )
+        except Exception as exc:
+            key = (rule_id, f"classify:{exc.__class__.__name__}")
+            if key not in self._t4_gate_warned:
+                self._t4_gate_warned.add(key)
+                _logger.warning(
+                    "[T4 gate] classify failed for %s: %s — regex fallback active",
+                    rule_id,
+                    exc,
+                )
+            return False
+        return verdict == "no"
+
     def _check_r23(self, tool_name: str, tool_input):
         """R23 — ssh/scp/rsync/curl towards an unregistered host."""
         if _r23_should is None:
@@ -986,6 +1069,10 @@ class HeadlessEnforcer:
         should, prompt = _r23e_should(tool_name, tool_input)
         if not should:
             return
+        span = (tool_input or {}).get("command", "") if isinstance(tool_input, dict) else ""
+        if self._t4_gate_says_no("R23e", span=span):
+            _logger.info("[R23e T4] gate=no, skipping")
+            return
         if mode == "shadow":
             _logger.info("[R23e SHADOW] would inject")
             return
@@ -1003,6 +1090,10 @@ class HeadlessEnforcer:
         should, prompt = _r23f_should(tool_name, tool_input, production_markers=markers or None)
         if not should:
             return
+        span = (tool_input or {}).get("command", "") if isinstance(tool_input, dict) else ""
+        if self._t4_gate_says_no("R23f", span=span):
+            _logger.info("[R23f T4] gate=no, skipping")
+            return
         if mode == "shadow":
             _logger.info("[R23f SHADOW] would inject")
             return
@@ -1252,6 +1343,12 @@ class HeadlessEnforcer:
         should, prompt = _r23h_should(tool_name, tool_input)
         if not should:
             return
+        span = ""
+        if isinstance(tool_input, dict):
+            span = tool_input.get("content") or tool_input.get("new_string") or ""
+        if self._t4_gate_says_no("R23h", span=str(span)[:500]):
+            _logger.info("[R23h T4] gate=no, skipping")
+            return
         if mode == "shadow":
             _logger.info("[R23h SHADOW] would inject")
             return
@@ -1341,6 +1438,30 @@ class HeadlessEnforcer:
         self._enqueue(prompt, decision["tag"], rule_id="R22_personal_script")
         _logger.info("[R22 %s] enqueued path=%s missing=%s", mode.upper(), decision["path"], decision["missing"])
 
+    def _check_r_catalog(self, tool_name: str):
+        """R-CATALOG (Plan Consolidado 0.X.2) — pre-create discovery probe."""
+        if _r_catalog_should is None:
+            return
+        mode = self._guardian_rule_mode("R_CATALOG_before_artifact_create")
+        if mode == "off":
+            return
+        # The trigger tool was just appended to recent_tool_records so we
+        # inspect the preceding window (strip the current call).
+        window = 60.0
+        now = time.time()
+        names = [
+            r.tool for r in self.recent_tool_records[:-1]
+            if (now - getattr(r, "ts", now)) <= window
+        ]
+        should, prompt = _r_catalog_should(tool_name, recent_tool_names=names)
+        if not should:
+            return
+        if mode == "shadow":
+            _logger.info("[R_CATALOG SHADOW] would inject for %s", tool_name)
+            return
+        self._enqueue(prompt, f"R_CATALOG:{tool_name}", rule_id="R_CATALOG_before_artifact_create")
+        _logger.info("[R_CATALOG %s] enqueued tool=%s", mode.upper(), tool_name)
+
     def _check_r18(self, tool_name: str, tool_input):
         """R18 — suggest followup_complete on closure-class actions."""
         if _r18_should is None or _r18_format is None:
@@ -1361,6 +1482,40 @@ class HeadlessEnforcer:
         self._enqueue(prompt, decision["tag"], rule_id="R18_followup_autocomplete")
         _logger.info("[R18 %s] enqueued %d matches", mode.upper(), decision["count"])
 
+    def on_assistant_message(self, text: str, *, classifier=None):
+        """R34 entry point — called when an assistant message is complete.
+
+        Plan Consolidado T5. If the message is a past-tense denial of an
+        action (ES/EN patterns) and no shared-brain tool was called in the
+        current turn, the rule fires a reminder to consult the shared brain
+        before asserting what happened.
+
+        Args:
+            text: assistant output text.
+            classifier: optional LLM yes/no callable used to disambiguate
+                regex matches. Tests pass a fake.
+        """
+        if _r34_should is None or not text:
+            return
+        mode = self._guardian_rule_mode("R34_identity_coherence")
+        if mode == "off":
+            return
+        recent_names = [r.tool for r in self.recent_tool_records]
+        try:
+            inject, prompt, matched = _r34_should(
+                text, recent_tool_names=recent_names, classifier=classifier,
+            )
+        except Exception as exc:  # noqa: BLE001
+            _logger.warning("R34 probe failed (%s); staying silent", exc)
+            return
+        if not inject:
+            return
+        if mode == "shadow":
+            _logger.info("[R34 SHADOW] would inject matched=%r", matched)
+            return
+        self._enqueue(prompt, f"R34:{matched[:40]}", rule_id="R34_identity_coherence")
+        _logger.info("[R34 %s] enqueued matched=%r", mode.upper(), matched)
+
     def notify_stale_memory_cited(self):
         """External hook for R24 — caller (handle_cognitive_retrieve post-
         processing) flags when a stale memory entered the context. Opens
@@ -1510,6 +1665,10 @@ class HeadlessEnforcer:
         # R22 — personal script create without prior context probes.
         self._check_r22(name, tool_input)
 
+        # R-CATALOG (Plan 0.X.2) — nudge if we are about to create/open/add
+        # without having consulted the live inventory in the last 60 s.
+        self._check_r_catalog(name)
+
         # R18 — retroactive followup-complete suggestion on closure actions.
         self._check_r18(name, tool_input)
 

package/src/fase_f_loops.py

@@ -0,0 +1,194 @@
+"""Plan Consolidado F.2/F.5/F.6 — Fase F telemetry loops.
+
+Consumes `guardian-telemetry.ndjson` (item 0.18) and produces:
+  - per-rule aggregate metrics (F.2)
+  - false-positive grouping (F.5)
+  - false-negative candidates for new-rule promotion (F.6)
+
+These are pure functions with no side effects on the live runtime —
+`src/scripts/phase_guardian_analysis.py` (Deep Sleep phase) calls them
+and persists summaries to `~/.nexo/reports/guardian-fase-f-*.json`.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from collections import defaultdict
+from pathlib import Path
+from typing import Iterable
+
+
+DEFAULT_TELEMETRY_PATH = Path.home() / ".nexo" / "logs" / "guardian-telemetry.ndjson"
+DEFAULT_FP_GROUP_MIN_OCCURRENCES = 3
+DEFAULT_FN_PROMOTION_THRESHOLD = 3
+DEFAULT_FN_WINDOW_DAYS = 14
+
+
+def load_telemetry_events(path: Path | str = DEFAULT_TELEMETRY_PATH) -> list[dict]:
+    """Return events persisted by the guardian_engine, oldest-first.
+
+    Ignores lines that fail to parse so a malformed append does not
+    blow up Deep Sleep.
+    """
+    p = Path(path)
+    if not p.exists():
+        return []
+    out: list[dict] = []
+    for line in p.read_text(encoding="utf-8", errors="ignore").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            out.append(json.loads(line))
+        except Exception:
+            continue
+    return out
+
+
+def aggregate_per_rule(events: Iterable[dict]) -> dict[str, dict]:
+    """F.2 — produce the per-rule metrics table.
+
+    Each rule_id gets:
+      - trigger_count
+      - injection_count
+      - followed_through_count (engine observed the agent then called
+        the gating tool within the dedup window)
+      - false_positive_count (operator flagged the injection as noise)
+      - avg_response_latency (ms between injection emit and agent act)
+    """
+    agg: dict[str, dict] = defaultdict(lambda: {
+        "trigger_count": 0,
+        "injection_count": 0,
+        "followed_through_count": 0,
+        "false_positive_count": 0,
+        "latencies_ms": [],
+    })
+    for e in events:
+        rid = e.get("rule_id") or ""
+        if not rid:
+            continue
+        etype = e.get("event") or e.get("type") or "injection"
+        bucket = agg[rid]
+        if etype in ("trigger", "scan"):
+            bucket["trigger_count"] += 1
+        elif etype in ("injection", "inject"):
+            bucket["injection_count"] += 1
+        elif etype == "followed_through":
+            bucket["followed_through_count"] += 1
+        elif etype in ("false_positive", "fp"):
+            bucket["false_positive_count"] += 1
+        latency = e.get("response_latency_ms") or e.get("latency_ms")
+        if isinstance(latency, (int, float)):
+            bucket["latencies_ms"].append(float(latency))
+
+    out: dict[str, dict] = {}
+    for rid, bucket in agg.items():
+        latencies = bucket.pop("latencies_ms")
+        avg = round(sum(latencies) / len(latencies), 1) if latencies else 0.0
+        efficacy = 0.0
+        inj = bucket["injection_count"]
+        if inj > 0:
+            efficacy = round(bucket["followed_through_count"] / inj, 3)
+        fp_rate = 0.0
+        if inj > 0:
+            fp_rate = round(bucket["false_positive_count"] / inj, 3)
+        out[rid] = {
+            **bucket,
+            "avg_response_latency_ms": avg,
+            "efficacy": efficacy,
+            "false_positive_rate": fp_rate,
+        }
+    return out
+
+
+def group_false_positives(
+    events: Iterable[dict],
+    min_occurrences: int = DEFAULT_FP_GROUP_MIN_OCCURRENCES,
+) -> list[dict]:
+    """F.5 — cluster FP events by (rule_id, trigger_context_hash).
+
+    Returns groups that appear >= min_occurrences times, ordered by
+    frequency desc. Consumers propose threshold/scope adjustments on the
+    top groups.
+    """
+    groups: dict[tuple, list[dict]] = defaultdict(list)
+    for e in events:
+        etype = e.get("event") or e.get("type") or ""
+        if etype not in ("false_positive", "fp"):
+            continue
+        key = (
+            e.get("rule_id") or "",
+            e.get("trigger_context_hash") or e.get("trigger_context") or "",
+        )
+        groups[key].append(e)
+
+    out: list[dict] = []
+    for (rid, ctx), items in groups.items():
+        if len(items) < min_occurrences:
+            continue
+        out.append({
+            "rule_id": rid,
+            "trigger_context": ctx,
+            "occurrences": len(items),
+            "first_seen": min((it.get("ts") or 0) for it in items),
+            "last_seen": max((it.get("ts") or 0) for it in items),
+            "sample": items[:3],
+        })
+    out.sort(key=lambda r: r["occurrences"], reverse=True)
+    return out
+
+
+def collect_false_negative_candidates(
+    corrections: Iterable[dict],
+    injections: Iterable[dict],
+    *,
+    window_days: int = DEFAULT_FN_WINDOW_DAYS,
+    threshold: int = DEFAULT_FN_PROMOTION_THRESHOLD,
+) -> list[dict]:
+    """F.6 — user corrections with no matching guardian injection are
+    candidates for a new rule in shadow.
+
+    corrections: events that represent a user correction (from
+      nexo_cognitive_sentiment `is_correction=True` or `trust_event=correction`).
+    injections: guardian injection events (event=injection).
+
+    Corrections older than window_days are ignored. Returns candidates
+    grouped by a fingerprint of the preceding assistant action, ordered
+    by count desc, filtered by count >= threshold.
+    """
+    now = time.time()
+    cutoff = now - (window_days * 86400)
+
+    injection_keys = {
+        (i.get("rule_id") or "", i.get("trigger_fingerprint") or "")
+        for i in injections
+    }
+
+    buckets: dict[str, list[dict]] = defaultdict(list)
+    for c in corrections:
+        ts = c.get("ts") or c.get("at") or 0
+        if ts and ts < cutoff:
+            continue
+        fp = c.get("fingerprint") or c.get("assistant_action_fingerprint") or ""
+        if not fp:
+            continue
+        # Already covered by an existing guardian injection → not a
+        # false-negative, it's just noise the operator could not suppress.
+        if any(k[1] == fp for k in injection_keys):
+            continue
+        buckets[fp].append(c)
+
+    out: list[dict] = []
+    for fp, items in buckets.items():
+        if len(items) < threshold:
+            continue
+        out.append({
+            "fingerprint": fp,
+            "count": len(items),
+            "first_seen": min((it.get("ts") or 0) for it in items),
+            "last_seen": max((it.get("ts") or 0) for it in items),
+            "sample": items[:3],
+        })
+    out.sort(key=lambda r: r["count"], reverse=True)
+    return out

package/src/hook_guardrails.py

@@ -557,6 +557,20 @@ def process_pre_tool_event(payload: dict) -> dict:
     if op not in {"write", "delete"}:
         return {"ok": True, "skipped": True, "reason": "operation not blocked", "strictness": get_protocol_strictness()}
 
+    # Plan Consolidado F0.0.4 — skip hook-level strict blocking while a
+    # structure migration is in flight. NEXO_MIGRATING=1 is set by
+    # nexo_migrate.run_structure_migration while it moves files and
+    # re-paths the runtime. Without this bypass a legitimate migration
+    # cannot edit anything without having opened task_open for each
+    # individual moved file, which defeats the whole migration flow.
+    if os.environ.get("NEXO_MIGRATING") == "1":
+        return {
+            "ok": True,
+            "skipped": True,
+            "reason": "structure migration in progress (NEXO_MIGRATING=1)",
+            "strictness": get_protocol_strictness(),
+        }
+
     tool_input = payload.get("tool_input")
     files = _extract_touched_files(tool_input)
     strictness = get_protocol_strictness()

package/src/hooks/auto_capture.py

@@ -149,11 +149,66 @@ def _dedup_record(
 # ---------------------------------------------------------------------------
 
 
+# Labels used when the local zero-shot classifier is consulted. Plan
+# 0.21 wave-2: classifier decides *semantically* between the four
+# buckets; regex stays as a fast prefilter.
+_ZS_LABELS = ("decision", "correction", "explicit", "noise")
+_ZS_CONFIDENCE_FLOOR = 0.65
+_ZS_MIN_LEN_FOR_LLM = 40  # short lines stay regex-only
+
+# Module-level classifier handle, constructed lazily on first use so
+# importing the hook never pays the transformers load cost.
+_zs_classifier = None
+
+
+def _get_zs_classifier():
+    """Return a LocalZeroShotClassifier or None if unavailable."""
+    global _zs_classifier
+    if _zs_classifier is not None:
+        return _zs_classifier
+    try:
+        from classifier_local import LocalZeroShotClassifier  # type: ignore
+    except Exception:
+        _zs_classifier = False  # type: ignore[assignment]
+        return None
+    try:
+        _zs_classifier = LocalZeroShotClassifier()
+    except Exception:
+        _zs_classifier = False  # type: ignore[assignment]
+        return None
+    return _zs_classifier
+
+
+def _zero_shot_classify(line: str) -> tuple[str, float] | None:
+    """Plan 0.21 — ask the local zero-shot classifier to bucket the line.
+
+    Returns ``(label, confidence)`` when the classifier is available and
+    its top confidence clears ``_ZS_CONFIDENCE_FLOOR``. Returns None
+    otherwise (classifier missing, pipeline load failed, low confidence,
+    or any exception). Callers must fall back to the regex decision in
+    that case — the classifier is a pre-filter / tie-breaker, never the
+    exclusive decider.
+    """
+    if len(line) < _ZS_MIN_LEN_FOR_LLM:
+        return None
+    clf = _get_zs_classifier()
+    if not clf:
+        return None
+    try:
+        result = clf.classify(line, _ZS_LABELS)
+    except Exception:
+        return None
+    if result is None or result.confidence < _ZS_CONFIDENCE_FLOOR:
+        return None
+    return result.label, float(result.confidence)
+
+
 def _classify_line(line: str) -> list[tuple[str, str]]:
     line = line.strip()
     if len(line) < _MIN_LINE_LENGTH:
         return []
 
+    # 1. Regex fast-path — cheap and deterministic.
     facts: list[tuple[str, str]] = []
 
     for pattern in _DECISION_PATTERNS:
@@ -171,6 +226,18 @@ def _classify_line(line: str) -> list[tuple[str, str]]:
             facts.append(("explicit", line))
             break
 
+    # 2. If regex produced no facts, ask the local zero-shot classifier
+    # for a semantic opinion. This catches multilingual correction
+    # shapes the regex does not know ("la ruta estaba mal en realidad",
+    # "that last paragraph is backwards"). The floor + min-length
+    # guard keep noise / short chatter off the learning pipeline.
+    if not facts:
+        zs = _zero_shot_classify(line)
+        if zs is not None:
+            label, _ = zs
+            if label in {"decision", "correction", "explicit"}:
+                facts.append((label, line))
+
     return facts
 
 

package/src/nexo_migrate.py

@@ -0,0 +1,158 @@
+"""nexo_migrate — Plan Consolidado F0.0 migration helper.
+
+Pre-requisite for F0.1→F0.6 (the scripts-classification / core-vs-personal
+reshuffle). This module owns:
+
+  - ``apply_migration(version, fn, notes="")`` — idempotent runner that
+    records success in ``migrations_applied`` and writes the matching
+    ``~/.nexo/.structure-version`` file so ``doctor`` and the CLI can
+    detect where the runtime is in the migration ladder.
+  - ``get_structure_version()`` — reader for the .structure-version file.
+  - ``ensure_migrations_table(conn)`` — idempotent ``CREATE TABLE IF NOT
+    EXISTS``.
+  - ``is_applied(version, conn=None)`` — check before re-running.
+
+The guardian hook (``hooks/protocol-pretool-guardrail.sh`` /
+``hook_guardrails.py``) already recognises the ``NEXO_MIGRATING=1``
+environment variable; this helper sets it for the duration of
+``apply_migration`` so live-repo writes during a fase are not blocked
+by learnings that guard those paths.
+
+Fail-closed: a migration that throws leaves the old structure-version
+file in place and does NOT record the version as applied — rollback is
+implicit.
+"""
+from __future__ import annotations
+
+import os
+import sqlite3
+import time
+from pathlib import Path
+from typing import Callable
+
+
+def _nexo_home() -> Path:
+    env = os.environ.get("NEXO_HOME")
+    if env:
+        return Path(env)
+    return Path.home() / ".nexo"
+
+
+def _db_path() -> Path:
+    env = os.environ.get("NEXO_DB_PATH")
+    if env:
+        return Path(env)
+    return _nexo_home() / "data" / "nexo.db"
+
+
+def _structure_version_path() -> Path:
+    return _nexo_home() / ".structure-version"
+
+
+def ensure_migrations_table(conn: sqlite3.Connection) -> None:
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS migrations_applied (
+            version    TEXT PRIMARY KEY,
+            applied_at TEXT NOT NULL,
+            notes      TEXT
+        )
+        """
+    )
+    conn.commit()
+
+
+def is_applied(version: str, *, conn: sqlite3.Connection | None = None) -> bool:
+    owned = False
+    if conn is None:
+        path = _db_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        conn = sqlite3.connect(str(path))
+        owned = True
+    try:
+        ensure_migrations_table(conn)
+        cur = conn.execute(
+            "SELECT 1 FROM migrations_applied WHERE version = ?",
+            (version,),
+        )
+        return cur.fetchone() is not None
+    finally:
+        if owned:
+            conn.close()
+
+
+def _record_applied(version: str, notes: str, conn: sqlite3.Connection) -> None:
+    ensure_migrations_table(conn)
+    conn.execute(
+        "INSERT OR REPLACE INTO migrations_applied(version, applied_at, notes) VALUES (?, ?, ?)",
+        (version, time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()), notes or ""),
+    )
+    conn.commit()
+
+
+def apply_migration(
+    version: str,
+    fn: Callable[[sqlite3.Connection], None],
+    *,
+    notes: str = "",
+    db_path: Path | None = None,
+) -> dict:
+    """Run ``fn(conn)`` under the NEXO_MIGRATING flag and record success.
+
+    Idempotent: already-applied versions return early with
+    ``{"applied": False, "reason": "already_applied"}``. A failing ``fn``
+    propagates its exception AFTER rolling back the transaction and
+    clears the NEXO_MIGRATING flag even on error.
+    """
+    path = Path(db_path) if db_path is not None else _db_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    prev_flag = os.environ.get("NEXO_MIGRATING")
+    os.environ["NEXO_MIGRATING"] = "1"
+    try:
+        with sqlite3.connect(str(path)) as conn:
+            if is_applied(version, conn=conn):
+                return {"applied": False, "version": version, "reason": "already_applied"}
+            try:
+                fn(conn)
+                _record_applied(version, notes, conn)
+                _structure_version_path().parent.mkdir(parents=True, exist_ok=True)
+                _structure_version_path().write_text(version + "\n", encoding="utf-8")
+                return {"applied": True, "version": version, "notes": notes}
+            except Exception:
+                conn.rollback()
+                raise
+    finally:
+        if prev_flag is None:
+            os.environ.pop("NEXO_MIGRATING", None)
+        else:
+            os.environ["NEXO_MIGRATING"] = prev_flag
+
+
+def get_structure_version() -> str:
+    try:
+        return _structure_version_path().read_text(encoding="utf-8").strip()
+    except OSError:
+        return ""
+
+
+def bootstrap_f00(*, db_path: Path | None = None) -> dict:
+    """Convenience: install the migrations_applied table + F0.0 marker.
+
+    Safe to call repeatedly; follows the idempotent apply_migration path.
+    """
+    def _noop(_conn):
+        # F0.0 is a bootstrap marker — the side-effect is just "the
+        # migrations_applied table exists and we recorded F0.0". The
+        # real schema ALTERs live in later versions (F0.1+).
+        pass
+
+    return apply_migration("F0.0", _noop, notes="bootstrap migrations_applied", db_path=db_path)
+
+
+__all__ = [
+    "apply_migration",
+    "bootstrap_f00",
+    "ensure_migrations_table",
+    "get_structure_version",
+    "is_applied",
+]