agent-bios 0.14.0 → 0.16.0

package/compose/corpus_store.py

@@ -0,0 +1,1414 @@
+#!/usr/bin/env python3
+"""Private, revision-checked storage for an activated corpus.
+
+The store deliberately owns source state and immutable projections only.  It
+does not alter a host configuration or claim that a snapshot was loaded by a
+host; that is the launch adapter's job.
+"""
+from __future__ import annotations
+
+import copy
+import contextlib
+import datetime as dt
+import hashlib
+import importlib
+import json
+import os
+from pathlib import Path, PurePosixPath
+import re
+import tempfile
+import uuid
+from typing import Any, Iterator
+
+try:
+    from corpus_transaction import transaction_lock, guard_pending, pending_operations, operation_scope_active
+except ImportError:
+    from .corpus_transaction import transaction_lock, guard_pending, pending_operations, operation_scope_active
+
+SCHEMA_VERSION = 1
+LOCAL_PACKAGE = "@local/personal"
+SURFACES = {"always", "relevant", "requested", "event", "delegated"}
+KINDS = {"rule", "guide", "skill", "hook", "agent"}
+ITEM_FIELDS = {
+    "ref", "package_id", "item_id", "title", "body", "surface", "tier",
+    "domains", "kind", "members", "origin", "routes", "dependencies",
+    "active", "learning_source", "hook", "primary_member",
+}
+RUNTIME_FIELDS = {
+    "digest", "revision", "content_ref", "path", "state", "created_at",
+    "updated_at", "baseline_ref", "plan_id", "history_id",
+}
+LEARNING_FIELDS = {"schema_version", "learning_id", "lesson", "domain", "created", "supporting_sessions",
+                   "criteria", "classification", "proposed_domain", "context"}
+LEARNING_ID_RE = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$")
+
+
+class CorpusStoreError(RuntimeError):
+    pass
+
+
+class StaleRevision(CorpusStoreError):
+    pass
+
+
+class ValidationError(CorpusStoreError):
+    pass
+
+
+def _canonical(value: Any) -> bytes:
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode("utf-8")
+
+
+def _digest(value: Any) -> str:
+    if isinstance(value, bytes):
+        return hashlib.sha256(value).hexdigest()
+    return hashlib.sha256(_canonical(value)).hexdigest()
+
+
+def _utcnow() -> str:
+    return dt.datetime.now(dt.timezone.utc).isoformat(timespec="microseconds")
+
+
+def _safe_part(value: str, label: str = "path") -> str:
+    if not isinstance(value, str) or not value or "\x00" in value:
+        raise ValidationError(f"invalid {label}")
+    path = PurePosixPath(value)
+    if path.is_absolute() or ".." in path.parts or path == PurePosixPath("."):
+        raise ValidationError(f"unowned {label}: {value!r}")
+    return value
+
+
+def _host(value: str) -> str:
+    if value not in {"claude", "codex"}:
+        raise ValidationError(f"unsupported host: {value!r}")
+    return value
+
+
+def _reject_symlink_path(path: Path, *, leaf: bool = True) -> None:
+    """Refuse a symlink at the store-owned path boundary.
+
+    Platform temporary directories commonly sit below system symlink aliases
+    (macOS `/var` is one), so the boundary deliberately stops at the configured
+    store path or its direct parent.  Every store-created nested root is checked
+    when it becomes the direct parent of a write; the lock itself also uses
+    ``O_NOFOLLOW`` against a final-component substitution race.
+    """
+    target = path if leaf else path.parent
+    if target.exists() or target.is_symlink():
+        if target.is_symlink():
+            raise CorpusStoreError(f"symlink is not a corpus-store path: {target}")
+
+
+def _json_read(path: Path, default: Any = None) -> Any:
+    _reject_symlink_path(path)
+    if not path.is_file():
+        return copy.deepcopy(default)
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        raise CorpusStoreError(f"unreadable state at {path}: {exc}") from exc
+
+
+def _atomic_write(path: Path, value: Any) -> None:
+    _reject_symlink_path(path)
+    _reject_symlink_path(path, leaf=False)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    body = _canonical(value) + b"\n"
+    fd, tmp_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    tmp = Path(tmp_name)
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(body)
+            handle.flush()
+            os.fsync(handle.fileno())
+        if path.exists():
+            tmp.chmod(path.stat().st_mode & 0o777)
+        os.replace(tmp, path)
+        # Persist the directory entry as well as the file bytes.
+        directory = os.open(path.parent, os.O_RDONLY)
+        try:
+            os.fsync(directory)
+        finally:
+            os.close(directory)
+    finally:
+        with contextlib.suppress(FileNotFoundError):
+            tmp.unlink()
+
+
+def _copy_json(value: Any) -> Any:
+    return json.loads(_canonical(value))
+
+
+def _rewrite_staged_paths(staging: Path, destination: Path) -> None:
+    """Replace compiler-internal absolute staging links before publication."""
+    old, new = str(staging), str(destination)
+    for path in staging.rglob("*"):
+        if not path.is_file():
+            continue
+        try:
+            text = path.read_text(encoding="utf-8")
+        except UnicodeDecodeError as exc:
+            raise CorpusStoreError(f"snapshot compiler emitted non-text member: {path}") from exc
+        if old in text:
+            path.write_text(text.replace(old, new), encoding="utf-8")
+
+
+def _snapshot_relative_paths(files: Any) -> list[str]:
+    if not isinstance(files, list) or not files or not all(isinstance(path, str) for path in files):
+        raise ValidationError("snapshot compiler returned an empty or invalid file set")
+    normalized = [_safe_part(path, "snapshot file") for path in files]
+    if len(set(normalized)) != len(normalized):
+        raise ValidationError("snapshot compiler returned duplicate files")
+    return sorted(normalized)
+
+
+def _snapshot_file_digests(root: Path, files: list[str]) -> dict[str, str]:
+    expected = sorted(set(files) | {"output.json"})
+    result: dict[str, str] = {}
+    for relative in expected:
+        path = root / _safe_part(relative, "snapshot file")
+        if path.is_symlink() or not path.is_file():
+            raise CorpusStoreError(f"snapshot output is missing or symlinked: {relative}")
+        result[relative] = _digest(path.read_bytes())
+    return result
+
+
+def _snapshot_assets(value: Any, files: list[str]) -> dict[str, Any]:
+    if not isinstance(value, dict) or set(value) - {"claude_plugins"}:
+        raise ValidationError("invalid snapshot native assets")
+    plugins = value.get("claude_plugins", [])
+    if not isinstance(plugins, list) or not all(isinstance(path, str) for path in plugins):
+        raise ValidationError("snapshot plugins must be relative paths")
+    if len(plugins) != len(set(plugins)):
+        raise ValidationError("duplicate snapshot plugin")
+    for relative in plugins:
+        _safe_part(relative, "snapshot plugin")
+        if PurePosixPath(relative).as_posix() != relative:
+            raise ValidationError("snapshot plugin path is not canonical")
+        if f"{relative}/.claude-plugin/plugin.json" not in files:
+            raise ValidationError("snapshot plugin has no inventoried manifest")
+    return _copy_json(value)
+
+
+def verify_snapshot(path: Path, expected_content_ref: str) -> dict[str, Any]:
+    """Validate a persisted snapshot without consulting current authoring state."""
+    root = Path(path)
+    _safe_part(expected_content_ref, "content ref")
+    if root.is_symlink() or not root.is_dir():
+        raise ValidationError(f"snapshot is missing or symlinked: {root}")
+    inventory = _json_read(root / "inventory.json")
+    output = _json_read(root / "output.json")
+    if not isinstance(inventory, dict) or not isinstance(output, dict):
+        raise ValidationError("snapshot metadata is unreadable")
+    inputs = inventory.get("inputs")
+    if not isinstance(inputs, dict) or _digest(inputs) != expected_content_ref:
+        raise ValidationError("snapshot content ref does not match canonical inputs")
+    files = _snapshot_relative_paths(output.get("files"))
+    _snapshot_assets(output.get("assets", {}), files)
+    digests = inventory.get("file_digests")
+    if not isinstance(digests, dict) or not digests:
+        raise ValidationError("snapshot has no file digest inventory")
+    expected = set(files) | {"output.json"}
+    if set(digests) != expected:
+        raise ValidationError("snapshot digest file set is not exact")
+    actual_files: set[str] = set()
+    for candidate in root.rglob("*"):
+        if candidate.is_symlink():
+            raise ValidationError(f"snapshot contains symlink: {candidate.relative_to(root)}")
+        if candidate.is_file() and candidate != root / "inventory.json":
+            actual_files.add(candidate.relative_to(root).as_posix())
+    if actual_files != expected:
+        raise ValidationError("snapshot persisted file set is not exact")
+    for relative, digest in digests.items():
+        if not isinstance(digest, str) or _digest((root / relative).read_bytes()) != digest:
+            raise ValidationError(f"snapshot file digest mismatch: {relative}")
+    return {"content_ref": expected_content_ref, "path": str(root), "inputs": inputs,
+            "items": inventory.get("items"), "file_digests": digests, "output": output}
+
+
+class CorpusStore:
+    """The private corpus source, transaction journal, and snapshot compiler.
+
+    ``state_root`` is deploy/runtime-owned. ``user_root`` is deliberately a
+    separate authority: install never overwrites it.
+    """
+
+    def __init__(self, repo: Path, state_root: Path | None = None, user_root: Path | None = None):
+        self.repo = Path(repo).resolve()
+        self.state_root = Path(state_root or os.environ.get(
+            "AGENT_BIOS_STATE_DIR", str(Path.home() / ".local/share/agent-bios")
+        )).expanduser()
+        self.user_root = Path(user_root or os.environ.get(
+            "AGENT_BIOS_CORPUS_DIR", str(Path.home() / ".config/agent-bios/corpus")
+        )).expanduser()
+        self.runtime = self.state_root / "runtime"
+        self.sessions = self.state_root / "sessions"
+
+    # ---- layout and locking -------------------------------------------------
+
+    @property
+    def _runtime_state_path(self) -> Path:
+        return self.runtime / "state.json"
+
+    @property
+    def _user_state_path(self) -> Path:
+        return self.user_root / "state.json"
+
+    @contextlib.contextmanager
+    def _lock(self) -> Iterator[None]:
+        _reject_symlink_path(self.state_root, leaf=False)
+        _reject_symlink_path(self.state_root)
+        _reject_symlink_path(self.user_root, leaf=False)
+        _reject_symlink_path(self.user_root)
+        self.state_root.mkdir(parents=True, exist_ok=True)
+        with transaction_lock(self.state_root):
+            yield
+
+    def _empty_runtime(self) -> dict[str, Any]:
+        return {
+            "schema_version": SCHEMA_VERSION,
+            "last_successful_install_ref": None,
+            "selected_baseline_ref": None,
+        }
+
+    def _empty_user(self) -> dict[str, Any]:
+        return {
+            "schema_version": SCHEMA_VERSION,
+            "items": {},
+            "overrides": {},
+            "tombstones": {},
+            "selection": None,
+            "learning_suppressions": {"claude": [], "codex": []},
+        }
+
+    def _runtime_state(self) -> dict[str, Any]:
+        state = _json_read(self._runtime_state_path, self._empty_runtime())
+        if state.get("schema_version") != SCHEMA_VERSION:
+            raise CorpusStoreError("runtime state schema mismatch")
+        return state
+
+    def _user_state(self) -> dict[str, Any]:
+        state = _json_read(self._user_state_path, self._empty_user())
+        if state.get("schema_version") != SCHEMA_VERSION:
+            raise CorpusStoreError("personal state schema mismatch")
+        # v1 sources created before reset acquired this projection field.  It
+        # has a deterministic empty meaning and is persisted on the next
+        # authoring transaction rather than rewritten by a read.
+        state.setdefault("learning_suppressions", {"claude": [], "codex": []})
+        for field, typ in (("items", dict), ("overrides", dict), ("tombstones", dict), ("learning_suppressions", dict)):
+            if not isinstance(state.get(field), typ):
+                raise CorpusStoreError(f"personal state has invalid {field}")
+        return state
+
+    def _write_transaction(self, tx_id: str, record: dict[str, Any]) -> None:
+        _atomic_write(self.runtime / "transactions" / tx_id / "journal.json", record)
+
+    def _recover_locked(self) -> None:
+        """Finish a source publication interrupted after its PREPARED journal.
+
+        User and runtime sources have separate ownership roots and cannot share
+        one rename.  The journal therefore records both candidate documents
+        before either pointer moves.  Recovery accepts only an exact prior/next
+        pair and finishes the known transaction; any third value is evidence of
+        an out-of-band writer and remains a fail-loud recovery record.
+        """
+        guard_pending(self.state_root)
+        root = self.runtime / "transactions"
+        if not root.is_dir():
+            return
+        for journal_path in sorted(root.glob("*/journal.json")):
+            journal = _json_read(journal_path)
+            if isinstance(journal, dict) and journal.get("state") == "NEEDS_RECOVERY":
+                raise CorpusStoreError(f"transaction {journal_path.parent.name} needs manual recovery")
+            if not isinstance(journal, dict) or journal.get("state") != "PREPARED":
+                continue
+            plan = journal.get("plan")
+            if not isinstance(plan, dict) or not isinstance(plan.get("before"), dict) or not isinstance(plan.get("after"), dict):
+                raise CorpusStoreError(f"invalid prepared transaction {journal_path.parent.name}")
+            current_runtime = _json_read(self._runtime_state_path, self._empty_runtime())
+            current_user = _json_read(self._user_state_path, self._empty_user())
+            prior, candidate = plan["before"], plan["after"]
+            known_runtime = current_runtime in (prior.get("runtime"), candidate.get("runtime"))
+            known_user = current_user in (prior.get("user"), candidate.get("user"))
+            if not known_runtime or not known_user:
+                journal["state"] = "NEEDS_RECOVERY"
+                journal["recovery_error"] = "source differs from prepared transaction prior and candidate"
+                _atomic_write(journal_path, journal)
+                raise CorpusStoreError(f"transaction {journal_path.parent.name} needs manual recovery")
+            history_id = journal.get("history_id")
+            if history_id is None:
+                instant = plan.get("created_at", journal.get("prepared_at", _utcnow()))
+                history_id = f"{instant.replace(':', '').replace('+00:00', 'Z')}-{journal_path.parent.name[:12]}"
+                journal["history_id"] = history_id
+                _atomic_write(journal_path, journal)
+            history = {"runtime": prior["runtime"], "user": prior["user"],
+                       "revision": plan.get("expected_revision")}
+            history_path = self.user_root / "history" / history_id / "state.json"
+            if not history_path.exists():
+                _atomic_write(history_path, history)
+            if plan.get("details", {}).get("operation") == "reset":
+                trash_path = self.user_root / "trash" / history_id / "state.json"
+                if not trash_path.exists():
+                    _atomic_write(trash_path, history)
+            _atomic_write(self._user_state_path, candidate["user"])
+            _atomic_write(self._runtime_state_path, candidate["runtime"])
+            journal["state"] = "RECOVERED_COMMITTED"
+            journal["recovered_at"] = _utcnow()
+            _atomic_write(journal_path, journal)
+
+    # ---- baseline and source resolution ------------------------------------
+
+    def _catalog_module(self):
+        try:
+            return importlib.import_module("corpus_catalog")
+        except ModuleNotFoundError:
+            # Package execution is useful in tests and is harmless in a checkout.
+            import sys
+            sys.path.insert(0, str(self.repo / "compose"))
+            try:
+                return importlib.import_module("corpus_catalog")
+            except ModuleNotFoundError as exc:
+                raise CorpusStoreError("compose/corpus_catalog.py is required") from exc
+
+    def _baseline_dir(self, ref: str) -> Path:
+        _safe_part(ref, "baseline reference")
+        return self.runtime / "baselines" / ref
+
+    def _normalize_content(self, item: dict[str, Any], *, allow_legacy: bool = False) -> dict[str, Any]:
+        return self._catalog_module().normalize_content(item, allow_legacy=allow_legacy)
+
+    def _read_baseline(self, ref: str) -> tuple[dict[str, Any], dict[str, Any]]:
+        root = self._baseline_dir(ref)
+        inventory = _json_read(root / "inventory.json")
+        defaults = _json_read(root / "defaults.json")
+        if not isinstance(inventory, dict) or not isinstance(defaults, dict):
+            raise CorpusStoreError(f"missing baseline tuple {ref}")
+        return inventory, defaults
+
+    def _baseline_promotions(self, ref: str) -> dict[str, Any]:
+        data = _json_read(self._baseline_dir(ref) / "promotions.json", {"version": 0, "promotions": []})
+        if not isinstance(data, dict) or not isinstance(data.get("promotions"), list):
+            raise CorpusStoreError(f"invalid promotion data in baseline {ref}")
+        return data
+
+    def _selected_baseline(self, runtime: dict[str, Any]) -> tuple[str, dict[str, Any], dict[str, Any]]:
+        ref = runtime.get("selected_baseline_ref")
+        if not isinstance(ref, str):
+            raise CorpusStoreError("no installed baseline; run install first")
+        inventory, defaults = self._read_baseline(ref)
+        return ref, inventory, defaults
+
+    def _learning_events(self, host: str) -> list[dict[str, Any]]:
+        _host(host)
+        _reject_symlink_path(self.user_root)
+        _reject_symlink_path(self.user_root / "learnings")
+        _reject_symlink_path(self.user_root / "learnings" / host)
+        path = self.user_root / "learnings" / host / "events.jsonl"
+        _reject_symlink_path(path)
+        if not path.is_file():
+            return []
+        events: list[dict[str, Any]] = []
+        for line_no, raw in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+            if not raw.strip():
+                continue
+            try:
+                event = json.loads(raw)
+            except ValueError as exc:
+                raise CorpusStoreError(f"invalid learning event {path}:{line_no}") from exc
+            if not isinstance(event, dict):
+                raise CorpusStoreError(f"invalid learning event {path}:{line_no}")
+            events.append(event)
+        return events
+
+    def _learning_item(self, host: str, event: dict[str, Any]) -> dict[str, Any] | None:
+        learning_id = event["learning_id"]
+        body = event["lesson"]
+        return {
+            "ref": f"@local/learnings-{host}:{learning_id}",
+            "package_id": f"@local/learnings-{host}", "item_id": learning_id,
+            "title": event["domain"],
+            "body": body, "surface": event.get("surface", "always"),
+            "tier": event.get("tier", "env-personal"), "domains": ["personal"], "kind": "rule",
+            "members": {"learning.md": body}, "origin": {"type": "learning", "host": host},
+            "learning_source": True,
+        }
+
+    @staticmethod
+    def _learning_host_from_ref(ref: str) -> str | None:
+        prefix = "@local/learnings-"
+        if not ref.startswith(prefix) or ":" not in ref:
+            return None
+        host = ref[len(prefix):].split(":", 1)[0]
+        return host if host in {"claude", "codex"} else None
+
+    def _effective_items(
+        self, runtime: dict[str, Any], user: dict[str, Any], host: str | None = None, include_suppressed: bool = False
+    ) -> tuple[list[dict[str, Any]], dict[str, Any], dict[str, Any], str]:
+        baseline_ref, inventory, defaults = self._selected_baseline(runtime)
+        source = inventory.get("items")
+        if not isinstance(source, list):
+            raise CorpusStoreError(f"baseline {baseline_ref} has no item inventory")
+        items: dict[str, dict[str, Any]] = {}
+        for raw in source:
+            item = self._validate_item(raw, allow_origin=True)
+            items[item["ref"]] = item
+        for ref, raw in user["items"].items():
+            item = self._validate_item(raw, allow_origin=True)
+            if item["ref"] != ref or item["package_id"] != LOCAL_PACKAGE:
+                raise CorpusStoreError("personal item identity mismatch")
+            items[ref] = item
+        if host:
+            suppressed = set(user.get("learning_suppressions", {}).get(host, []))
+            for event in self._learning_events(host):
+                suppressed_event = _digest(event) in suppressed
+                if suppressed_event and not include_suppressed:
+                    continue
+                item = self._learning_item(host, event)
+                if item is not None:
+                    if suppressed_event:
+                        item["active"] = False
+                    items[item["ref"]] = self._validate_item(item, allow_origin=True)
+        for ref, override in user["overrides"].items():
+            if ref not in items:
+                continue
+            base_digest = override.get("base_digest")
+            patch = override.get("patch")
+            if not isinstance(base_digest, str) or not isinstance(patch, dict):
+                raise CorpusStoreError(f"invalid override for {ref}")
+            # An upstream change to the same base is not silently merged.
+            if _digest(items[ref]) != base_digest:
+                items[ref]["conflict"] = {"base_digest": base_digest, "current_digest": _digest(items[ref])}
+                continue
+            merged = {**items[ref], **patch}
+            items[ref] = self._validate_item(merged, allow_origin=True)
+        for ref in user["tombstones"]:
+            if include_suppressed and self._learning_host_from_ref(ref) == host and ref in items:
+                items[ref]["active"] = False
+            else:
+                items.pop(ref, None)
+        return [self._normalize_content(item, allow_legacy=True) for item in items.values()], inventory, defaults, baseline_ref
+
+    def _resolve_promotions(
+        self, selected: list[dict[str, Any]], user: dict[str, Any], host: str, baseline_ref: str
+    ) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+        """Suppress only a source event proven replaced in this exact snapshot."""
+        promotions = self._baseline_promotions(baseline_ref)
+        by_id: dict[str, list[dict[str, Any]]] = {}
+        warnings: list[dict[str, Any]] = []
+        for row in promotions["promotions"]:
+            if not isinstance(row, dict):
+                warnings.append({"reason": "invalid_promotion_row"})
+                continue
+            required = {"learning_id", "host", "source_digest", "target_ref", "target_digest"}
+            if not required <= set(row):
+                # v2 rows are audience claims only.  They must never cause a
+                # source deletion merely because an anchor happens to match.
+                if isinstance(row.get("learning_id"), str):
+                    warnings.append({"ref": f"@local/learnings-{host}:{row['learning_id']}",
+                                     "reason": "promotion_mapping_incomplete"})
+                continue
+            if all(isinstance(row.get(field), str) for field in required):
+                by_id.setdefault(row["learning_id"], []).append(row)
+            else:
+                warnings.append({"reason": "invalid_promotion_row"})
+        chosen = {item["ref"]: item for item in selected}
+        retained: list[dict[str, Any]] = []
+        for item in selected:
+            if item.get("origin", {}).get("type") != "learning" or item.get("origin", {}).get("host") != host:
+                retained.append(item)
+                continue
+            learning_id = item["item_id"]
+            event = next((event for event in self._learning_events(host)
+                          if (event.get("learning_id") or event.get("id")) == learning_id), None)
+            candidates = [row for row in by_id.get(learning_id, [])
+                          if row["host"] == host and event is not None and row["source_digest"] == _digest(event)]
+            if not candidates:
+                retained.append(item)
+                continue
+            row = candidates[0]
+            target = chosen.get(row["target_ref"])
+            if target is None:
+                retained.append(item)
+                continue
+            if row["target_digest"] != _digest(target):
+                warnings.append({"ref": item["ref"], "reason": "promotion_target_digest_mismatch"})
+                retained.append(item)
+                continue
+            member = row.get("target_member")
+            if row.get("exclusive") is True and target["body"] == item["body"]:
+                continue
+            if isinstance(member, str) and target.get("members", {}).get(member) == item["body"]:
+                baseline_inventory, _defaults = self._read_baseline(baseline_ref)
+                original = next((raw for raw in baseline_inventory["items"] if raw.get("ref") == row["target_ref"]), None)
+                if not isinstance(original, dict) or not isinstance(original.get("members"), dict):
+                    raise ValidationError(f"learning_rebase_conflict: {item['ref']}")
+                if set(original["members"]) - set(target["members"]):
+                    raise ValidationError(f"learning_rebase_conflict: {item['ref']}")
+                continue
+            raise ValidationError(f"learning_rebase_conflict: {item['ref']}")
+        return retained, warnings
+
+    def _authoring_revision(self, runtime: dict[str, Any], user: dict[str, Any]) -> str:
+        learning = {}
+        for host in ("claude", "codex"):
+            events = self._learning_events(host)
+            learning[host] = _digest(events)
+        return _digest({
+            "selected_baseline_ref": runtime.get("selected_baseline_ref"),
+            "last_successful_install_ref": runtime.get("last_successful_install_ref"),
+            "user": user, "learning": learning,
+        })
+
+    # ---- validation ---------------------------------------------------------
+
+    def _validate_item(self, raw: Any, *, allow_origin: bool = False) -> dict[str, Any]:
+        if not isinstance(raw, dict):
+            raise ValidationError("item must be an object")
+        unknown = set(raw) - ITEM_FIELDS - {"conflict", "content_conflict"}
+        if unknown:
+            raise ValidationError(f"unknown item fields: {', '.join(sorted(unknown))}")
+        runtime = set(raw) & RUNTIME_FIELDS
+        if runtime:
+            raise ValidationError(f"runtime-owned item fields: {', '.join(sorted(runtime))}")
+        item = _copy_json(raw)
+        required = ("ref", "package_id", "item_id", "title", "body", "surface", "tier", "domains", "kind", "members")
+        missing = [field for field in required if field not in item]
+        if missing:
+            raise ValidationError(f"item missing fields: {', '.join(missing)}")
+        for field in ("ref", "package_id", "item_id", "title", "tier"):
+            if not isinstance(item[field], str) or not item[field]:
+                raise ValidationError(f"invalid item {field}")
+        if not isinstance(item["body"], str):
+            raise ValidationError("invalid item body")
+        if item["ref"] != f"{item['package_id']}:{item['item_id']}":
+            raise ValidationError("item ref does not match package_id and item_id")
+        catalog = self._catalog_module()
+        surfaces = getattr(catalog, "SURFACES", SURFACES)
+        kinds = getattr(catalog, "KINDS", KINDS)
+        if item["surface"] not in surfaces or item["kind"] not in kinds:
+            raise ValidationError("invalid consumption surface or kind")
+        if "hook" in item:
+            try:
+                catalog.validate_hook_binding(item["hook"])
+            except (ValueError, AttributeError) as exc:
+                raise ValidationError(f"invalid hook binding: {exc}") from exc
+        if not isinstance(item["domains"], list) or not all(isinstance(x, str) for x in item["domains"]):
+            raise ValidationError("invalid item domains")
+        if not isinstance(item["members"], dict):
+            raise ValidationError("invalid item members")
+        for path, body in item["members"].items():
+            _safe_part(path, "member path")
+            if not isinstance(body, str):
+                raise ValidationError("member body must be text")
+        if "origin" in item and not isinstance(item["origin"], dict):
+            raise ValidationError("invalid item origin")
+        if not allow_origin and "origin" in item:
+            raise ValidationError("origin is catalog-owned")
+        return item
+
+    def _validate_patch(self, patch: Any) -> dict[str, Any]:
+        if not isinstance(patch, dict) or not patch:
+            raise ValidationError("update needs a non-empty patch")
+        unknown = set(patch) - (ITEM_FIELDS - {"ref", "package_id", "item_id", "origin", "active", "learning_source"})
+        if unknown:
+            raise ValidationError(f"unknown or immutable patch fields: {', '.join(sorted(unknown))}")
+        if set(patch) & RUNTIME_FIELDS:
+            raise ValidationError("runtime-owned field in patch")
+        return _copy_json(patch)
+
+    def _validate_selection(self, selection: Any, inventory: dict[str, Any]) -> list[str] | None:
+        if selection is None:
+            return None
+        if not isinstance(selection, list) or not all(isinstance(x, str) for x in selection):
+            raise ValidationError("selection must be a list of qualified refs/domains")
+        packages = {p.get("package_id") for p in inventory.get("packages", []) if isinstance(p, dict)}
+        for value in selection:
+            if value == "all":
+                continue
+            if ":" in value:
+                continue
+            if value.startswith("@local/"):
+                continue
+            if "/" not in value or not value.startswith("@"):
+                raise ValidationError(f"selection must be fully qualified: {value!r}")
+            package = value.rsplit("/", 1)[0]
+            if package not in packages and package != LOCAL_PACKAGE and not package.startswith("@local/"):
+                raise ValidationError(f"unknown package in selection: {value!r}")
+        return sorted(set(selection))
+
+    def _normalized_install_selection(self, domains: list[str] | None, catalog: dict[str, Any]) -> list[str]:
+        """Translate legacy bare domain inputs at the installer boundary once."""
+        if domains is None:
+            return []
+        if not isinstance(domains, list) or not all(isinstance(domain, str) for domain in domains):
+            raise ValidationError("install domains must be a list of strings")
+        packages = catalog.get("packages", [])
+        if not packages or not isinstance(packages[0], dict) or not isinstance(packages[0].get("package_id"), str):
+            raise ValidationError("catalog lacks a core package")
+        core_package = packages[0]["package_id"]
+        normalized = [domain if domain == "all" or domain.startswith("@") else f"{core_package}/{domain}" for domain in domains]
+        return self._validate_selection(normalized, catalog) or []
+
+    @staticmethod
+    def _effective_selection(user: dict[str, Any], defaults: dict[str, Any], requested: list[str] | None) -> list[str] | None:
+        if requested is not None:
+            return requested
+        if user.get("selection") is not None:
+            return user["selection"]
+        return defaults.get("selection")
+
+    def _validate_snapshot_selection(self, selection: list[str] | None, inventory: dict[str, Any], items: list[dict[str, Any]]) -> None:
+        if selection is None:
+            return
+        if not isinstance(selection, list) or not all(isinstance(value, str) for value in selection):
+            raise ValidationError("selection must be a list")
+        packages = {entry["package_id"]: set((entry.get("domains") or {}).keys())
+                    for entry in inventory.get("packages", []) if isinstance(entry, dict) and isinstance(entry.get("package_id"), str)}
+        packages.update({LOCAL_PACKAGE: {"personal"}, "@local/learnings-claude": {"personal"},
+                         "@local/learnings-codex": {"personal"}})
+        refs = {item["ref"] for item in items}
+        for value in selection:
+            if value == "all":
+                continue
+            if ":" in value:
+                if value not in refs:
+                    raise ValidationError(f"unknown corpus selection ref: {value}")
+                continue
+            if value in packages:
+                continue
+            if not value.startswith("@") or "/" not in value:
+                raise ValidationError(f"selection must be package/domain-qualified: {value!r}")
+            package, domain = value.rsplit("/", 1)
+            if package not in packages or domain not in packages[package]:
+                raise ValidationError(f"unknown corpus selection domain: {value}")
+
+    def _validate_candidate_projection(self, runtime: dict[str, Any], user: dict[str, Any]) -> None:
+        """Use the real compiler as a plan validator without publishing output."""
+        catalog = self._catalog_module()
+        try:
+            with tempfile.TemporaryDirectory(prefix="agent-bios-plan-") as temp:
+                for host in ("claude", "codex"):
+                    items, _inventory, defaults, _baseline = self._effective_items(runtime, user, host=host)
+                    active = [item for item in items if item.get("active", True) is not False]
+                    selection = self._effective_selection(user, defaults, None)
+                    self._validate_snapshot_selection(selection, _inventory, active)
+                    selected = self._selected_items(active, selection)
+                    self._require_resolved(selected)
+                    catalog.compile_items(_copy_json(selected), Path(temp) / host, host)
+        except Exception as exc:
+            # The catalog names the concrete member/ref; retain that actionable
+            # evidence but keep the manager's public validation contract stable.
+            raise ValidationError(f"candidate projection is invalid: {exc}") from exc
+
+    @staticmethod
+    def _require_resolved(items: list[dict[str, Any]]) -> None:
+        conflicts = [item["ref"] for item in items if item.get("conflict") or item.get("content_conflict")]
+        if conflicts:
+            raise ValidationError("unresolved corpus conflict: " + ", ".join(sorted(conflicts)))
+
+    def _rebase_overlays(self, old_inventory: dict[str, Any], new_inventory: dict[str, Any], user: dict[str, Any]) -> dict[str, Any]:
+        """Three-way field/member comparison shared by forward and reverse switches."""
+        result = _copy_json(user)
+        old_items = {item["ref"]: item for item in old_inventory.get("items", []) if isinstance(item, dict)}
+        new_items = {item["ref"]: item for item in new_inventory.get("items", []) if isinstance(item, dict)}
+        conflicts: list[str] = []
+        for ref, override in list(result["overrides"].items()):
+            learning_host = self._learning_host_from_ref(ref)
+            if learning_host is not None:
+                event = next((event for event in self._learning_events(learning_host)
+                              if ref == f"@local/learnings-{learning_host}:{event['learning_id']}"), None)
+                if event is None or override.get("base_digest") != _digest(self._learning_item(learning_host, event)):
+                    conflicts.append(ref)
+                continue
+            old, new = old_items.get(ref), new_items.get(ref)
+            if old is None or not isinstance(override, dict):
+                conflicts.append(ref)
+                continue
+            if override.get("base_digest") != _digest(old) or not isinstance(override.get("patch"), dict):
+                conflicts.append(ref)
+                continue
+            base = self._normalize_content(old, allow_legacy=True)
+            personal = self._normalize_content({**old, **override["patch"]}, allow_legacy=True)
+            if personal == base:
+                result["overrides"].pop(ref, None)
+                continue
+            if new is None:
+                conflicts.append(ref)
+                continue
+            target = self._normalize_content(new, allow_legacy=True)
+            self._require_resolved([base, target, personal])
+            merged = _copy_json(target)
+            missing = object()
+            for field in ITEM_FIELDS - {"body"}:
+                if field == "members":
+                    output = dict(target["members"])
+                    for member in set(base["members"]) | set(personal["members"]) | set(target["members"]):
+                        prior = base["members"].get(member, missing)
+                        mine = personal["members"].get(member, missing)
+                        theirs = target["members"].get(member, missing)
+                        if mine == prior:
+                            continue
+                        if theirs != prior and mine != theirs:
+                            conflicts.append(f"{ref} members/{member}")
+                        elif mine is missing:
+                            output.pop(member, None)
+                        else:
+                            output[member] = mine
+                    merged[field] = output
+                else:
+                    prior, mine, theirs = base.get(field, missing), personal.get(field, missing), target.get(field, missing)
+                    if mine == prior:
+                        continue
+                    if theirs != prior and mine != theirs:
+                        conflicts.append(f"{ref} {field}")
+                    elif mine is missing:
+                        merged.pop(field, None)
+                    else:
+                        merged[field] = mine
+            # body is a view of the merged primary member, not a second merge input.
+            merged.pop("body", None)
+            merged = self._normalize_content(merged)
+            patch = {field: value for field, value in merged.items()
+                     if field in ITEM_FIELDS and value != new.get(field)}
+            if patch:
+                result["overrides"][ref] = {"base_digest": _digest(new), "patch": patch}
+            else:
+                result["overrides"].pop(ref, None)
+        if conflicts:
+            raise ValidationError("baseline_update_conflict: " + ", ".join(sorted(conflicts)))
+        return result
+
+    # ---- public read API ----------------------------------------------------
+
+    def install(self, domains: list[str] | None = None) -> dict[str, Any]:
+        """Install one immutable validated baseline tuple without touching user data."""
+        with self._lock():
+            return self.commit_install(self.prepare_install(domains))
+
+    def prepare_install(self, domains: list[str] | None = None) -> dict[str, Any]:
+        """Stage a validated baseline and source plan without advancing any pointer."""
+        with self._lock():
+            self._recover_locked()
+            catalog = self._catalog_module().load_catalog(self.repo)
+            if not isinstance(catalog, dict) or catalog.get("schema_version") != SCHEMA_VERSION:
+                raise ValidationError("catalog schema mismatch")
+            raw_items = catalog.get("items")
+            if not isinstance(raw_items, list) or not raw_items:
+                raise ValidationError("catalog inventory is empty")
+            items = [self._validate_item(item, allow_origin=True) for item in raw_items]
+            if len({item["ref"] for item in items}) != len(items):
+                raise ValidationError("catalog has duplicate corpus refs")
+            defaults = {"schema_version": SCHEMA_VERSION,
+                        "selection": self._normalized_install_selection(domains, catalog) +
+                                     [LOCAL_PACKAGE, "@local/learnings-claude", "@local/learnings-codex"]}
+            promotion_path = self.repo / "learn" / "promotions.json"
+            promotions = _json_read(promotion_path, {"version": 0, "promotions": []})
+            if not isinstance(promotions, dict) or not isinstance(promotions.get("promotions"), list):
+                raise ValidationError("promotion manifest is invalid")
+            compiler = self.repo / "compose" / "corpus_catalog.py"
+            tuple_data = {
+                "schema_version": SCHEMA_VERSION, "catalog": catalog, "defaults": defaults,
+                "promotions": promotions,
+                "compiler_digest": _digest(compiler.read_bytes()) if compiler.is_file() else None,
+            }
+            baseline_ref = _digest(tuple_data)
+            root = self._baseline_dir(baseline_ref)
+            existing = root / "inventory.json"
+            if existing.exists() and _json_read(existing) != catalog:
+                raise CorpusStoreError(f"immutable baseline collision: {baseline_ref}")
+            runtime = self._runtime_state()
+            user = self._user_state()
+            prior_last = runtime.get("last_successful_install_ref")
+            next_user = user
+            adopt = runtime.get("selected_baseline_ref") == prior_last
+            if adopt and isinstance(prior_last, str) and prior_last != baseline_ref:
+                old_inventory, _old_defaults = self._read_baseline(prior_last)
+                # A conflict refuses before either the baseline pointer or the
+                # successful-install record changes.
+                next_user = self._rebase_overlays(old_inventory, catalog, user)
+            before = {"runtime": _copy_json(runtime), "user": _copy_json(user)}
+            _atomic_write(root / "inventory.json", catalog)
+            _atomic_write(root / "defaults.json", defaults)
+            _atomic_write(root / "promotions.json", promotions)
+            runtime["last_successful_install_ref"] = baseline_ref
+            if runtime.get("selected_baseline_ref") is None or adopt:
+                runtime["selected_baseline_ref"] = baseline_ref
+            self._validate_candidate_projection(runtime, next_user)
+            transaction_id = uuid.uuid4().hex
+            details = {"baseline_ref": baseline_ref, "selected_baseline_ref": runtime["selected_baseline_ref"], "items": len(items)}
+            candidate = {"transaction_id": transaction_id, "before": before,
+                         "after": {"runtime": runtime, "user": next_user}, "details": details,
+                         "expected_revision": self._authoring_revision(before["runtime"], before["user"])}
+            self._write_transaction(transaction_id, {"state": "PLANNED", "kind": "install", "plan": candidate})
+            return _copy_json(candidate)
+
+    def commit_install(self, candidate: dict[str, Any]) -> dict[str, Any]:
+        """Publish a staged installation; repeated recovery consumes the same journal."""
+        transaction_id = _safe_part(candidate.get("transaction_id"), "transaction id")
+        with self._lock():
+            self._recover_locked()
+            record = _json_read(self.runtime / "transactions" / transaction_id / "journal.json")
+            if (self.runtime / "private-install.json").exists() and not operation_scope_active(self.state_root):
+                raise ValidationError("managed installations must publish through agent-bios install")
+            if not isinstance(record, dict) or record.get("kind") != "install":
+                raise ValidationError("unknown installation candidate")
+            plan = record["plan"]
+            if len(candidate) > 1 and candidate != plan:
+                raise ValidationError("installation candidate differs from its recorded plan")
+            if record["state"] in {"COMMITTED", "RECOVERED_COMMITTED"}:
+                return _copy_json(plan["details"])
+            runtime, user = self._runtime_state(), self._user_state()
+            if record["state"] != "PLANNED" or self._authoring_revision(runtime, user) != plan["expected_revision"]:
+                raise StaleRevision("installation candidate is stale")
+            self._validate_candidate_projection(plan["after"]["runtime"], plan["after"]["user"])
+            record["state"] = "PREPARED"
+            self._write_transaction(transaction_id, record)
+            self._recover_locked()
+            return _copy_json(plan["details"])
+
+    def status(self) -> dict[str, Any]:
+        with self._lock():
+            pending = [entry for entry in pending_operations(self.state_root)
+                       if entry["state"] == "NEEDS_RECOVERY"
+                       or "resets" in Path(entry["path"]).parts
+                       or _json_read(Path(entry["path"])).get("owner") == "installer"]
+            if pending:
+                return {"schema_version": SCHEMA_VERSION, "needs_recovery": pending,
+                        "installed": self._runtime_state().get("last_successful_install_ref") is not None}
+            self._recover_locked()
+            runtime, user = self._runtime_state(), self._user_state()
+            revision = self._authoring_revision(runtime, user)
+            refs = list((self.runtime / "baselines").glob("*/inventory.json"))
+            defaults = self._selected_baseline(runtime)[2] if runtime.get("selected_baseline_ref") else {}
+            return {
+                "schema_version": SCHEMA_VERSION, "installed": runtime.get("last_successful_install_ref") is not None,
+                "last_successful_install_ref": runtime.get("last_successful_install_ref"),
+                "selected_baseline_ref": runtime.get("selected_baseline_ref"),
+                "revision": revision, "baseline_count": len(refs),
+                "personal_items": len(user["items"]), "overrides": len(user["overrides"]),
+                "tombstones": len(user["tombstones"]), "selection": self._effective_selection(user, defaults, None),
+            }
+
+    def list_items(self, include_removed: bool = True) -> list[dict[str, Any]]:
+        with self._lock():
+            self._recover_locked()
+            runtime, user = self._runtime_state(), self._user_state()
+            selected_ref, inventory, _defaults = self._selected_baseline(runtime)
+            all_items, _, _, _ = self._effective_items(runtime, user)
+            effective = {item["ref"]: item for item in all_items}
+            for host in ("claude", "codex"):
+                effective.update({item["ref"]: item for item in self._effective_items(runtime, user, host=host, include_suppressed=True)[0]})
+            source = {item["ref"]: self._validate_item(item, allow_origin=True) for item in inventory["items"]}
+            rows: list[dict[str, Any]] = []
+            for ref in sorted(set(source) | set(user["items"]) | set(effective)):
+                base = source.get(ref)
+                item = effective.get(ref)
+                removed = ref in user["tombstones"] or (item is not None and item.get("active", True) is False)
+                if removed and not include_removed:
+                    continue
+                row = _copy_json(item or base or user["items"][ref])
+                row["state"] = "removed" if removed else ("conflict" if item and (item.get("conflict") or item.get("content_conflict")) else "active")
+                row["digest"] = _digest(item or base or user["items"][ref])
+                row["baseline_ref"] = selected_ref if base else None
+                rows.append(row)
+            return rows
+
+    def show(self, ref: str, view: str = "effective") -> dict[str, Any]:
+        if view not in {"effective", "installed", "change", "diff", "history"}:
+            raise ValidationError("unknown corpus view")
+        with self._lock():
+            self._recover_locked()
+            runtime, user = self._runtime_state(), self._user_state()
+            baseline_ref, inventory, _defaults = self._selected_baseline(runtime)
+            base = next((self._validate_item(x, allow_origin=True) for x in inventory["items"] if x.get("ref") == ref), None)
+            learning_host = self._learning_host_from_ref(ref)
+            effective = {x["ref"]: x for x in self._effective_items(runtime, user, host=learning_host, include_suppressed=learning_host is not None)[0]}.get(ref)
+            if base is None and ref not in user["items"] and effective is None:
+                raise ValidationError(f"unknown corpus ref: {ref}")
+            if view == "installed":
+                return {"ref": ref, "baseline_ref": baseline_ref, "item": base}
+            if view == "change":
+                return {"ref": ref, "override": user["overrides"].get(ref), "tombstone": user["tombstones"].get(ref), "personal": user["items"].get(ref)}
+            if view == "diff":
+                return {"ref": ref, "installed": base, "effective": effective, "change": user["overrides"].get(ref), "removed": ref in user["tombstones"]}
+            if view == "history":
+                return {"ref": ref, "history": self.history(ref)}
+            removed = ref in user["tombstones"] or (effective is not None and effective.get("active", True) is False)
+            state = "removed" if removed else ("conflict" if effective and (effective.get("conflict") or effective.get("content_conflict")) else "active")
+            return {"ref": ref, "item": effective, "digest": _digest(effective) if effective else None, "state": state}
+
+    # ---- plans --------------------------------------------------------------
+
+    def _next_personal_id(self, user: dict[str, Any]) -> str:
+        """Allocate against retained sources and plans, including retired identities."""
+        issued = set(user["items"])
+        for path in (self.user_root / "history").glob("*/state.json"):
+            record = _json_read(path)
+            issued.update((record.get("user") or {}).get("items", {}))
+        for path in (self.runtime / "transactions").glob("*/journal.json"):
+            record = _json_read(path)
+            plan = record.get("plan") or {}
+            issued.update(((plan.get("after") or {}).get("user") or {}).get("items", {}))
+            if ref := (plan.get("details") or {}).get("ref"):
+                issued.add(ref)
+        for _attempt in range(16):
+            item_id = f"personal-{uuid.uuid4().hex}"
+            if f"{LOCAL_PACKAGE}:{item_id}" not in issued:
+                return item_id
+        raise CorpusStoreError("could not allocate an unused personal identity")
+
+    def _prepare_operation(self, payload: dict[str, Any], runtime: dict[str, Any], user: dict[str, Any],
+                           *, allocated_item_id: str | None = None) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]]:
+        if not isinstance(payload, dict):
+            raise ValidationError("plan payload must be an object")
+        op = payload.get("operation", payload.get("op"))
+        if op not in {"create", "update", "remove", "restore", "recover", "reset", "rollback", "select"}:
+            raise ValidationError("unknown corpus operation")
+        allowed = {
+            "create": {"operation", "op", "item", "package_id", "expected_revision"},
+            "update": {"operation", "op", "ref", "patch", "item_digest", "expected_revision"},
+            "remove": {"operation", "op", "ref", "item_digest", "expected_revision"},
+            "restore": {"operation", "op", "ref", "expected_revision"},
+            "recover": {"operation", "op", "ref", "expected_revision"},
+            "reset": {"operation", "op", "expected_revision"},
+            "rollback": {"operation", "op", "baseline_ref", "history_id", "expected_revision"},
+            "select": {"operation", "op", "selection", "expected_revision"},
+        }[op]
+        unknown = set(payload) - allowed
+        if unknown:
+            raise ValidationError(f"unknown plan fields: {', '.join(sorted(unknown))}")
+        current = self._authoring_revision(runtime, user)
+        given = payload.get("expected_revision")
+        if given is not None and given != current:
+            raise StaleRevision(f"expected revision {given} is stale; current is {current}")
+        next_runtime, next_user = _copy_json(runtime), _copy_json(user)
+        items, inventory, defaults, _baseline_ref = self._effective_items(runtime, user)
+        effective = {item["ref"]: item for item in items}
+        details: dict[str, Any] = {"operation": op}
+        if op == "create":
+            raw = _copy_json(payload.get("item"))
+            if not isinstance(raw, dict):
+                raise ValidationError("create needs item")
+            if set(raw) & {"item_id", "ref", "content_conflict", "conflict"}:
+                raise ValidationError("creation identity and conflict metadata are runtime-owned")
+            if allocated_item_id is None:
+                raise ValidationError("creation needs a recorded runtime-owned identity")
+            package = payload.get("package_id", raw.get("package_id", LOCAL_PACKAGE))
+            if package != LOCAL_PACKAGE:
+                raise ValidationError("V1 creation targets @local/personal")
+            raw["package_id"] = LOCAL_PACKAGE
+            raw["item_id"] = allocated_item_id
+            raw["ref"] = f"{LOCAL_PACKAGE}:{raw['item_id']}"
+            raw.setdefault("surface", "requested")
+            raw.setdefault("tier", "env-personal")
+            raw.setdefault("domains", ["personal"])
+            raw.setdefault("kind", "rule")
+            if "members" not in raw:
+                raw.setdefault("body", "")
+                raw["members"] = {"content.md": raw["body"]}
+                raw["primary_member"] = "content.md"
+            elif "body" not in raw:
+                primary = raw.get("primary_member")
+                if not isinstance(raw["members"], dict) or not isinstance(primary, str) or primary not in raw["members"]:
+                    raise ValidationError("members-only creation needs primary_member")
+                raw["body"] = raw["members"][primary]
+            try:
+                item = self._validate_item(self._normalize_content(raw, allow_legacy=True))
+                self._require_resolved([item])
+                if "body" in payload["item"] and item["body"] != raw["body"]:
+                    raise ValidationError("body conflicts with primary_member member content")
+            except ValueError as exc:
+                raise ValidationError(str(exc)) from exc
+            if item["kind"] not in {"rule", "guide", "skill"}:
+                raise ValidationError("V1 personal creation supports rule, guide, and skill items")
+            if item["ref"] in effective or item["ref"] in next_user["items"]:
+                raise ValidationError(f"corpus ref already exists: {item['ref']}")
+            next_user["items"][item["ref"]] = item
+            details.update({"ref": item["ref"], "item_digest": _digest(item)})
+        elif op == "update":
+            ref = payload.get("ref")
+            if isinstance(ref, str) and ref not in effective:
+                learning_host = self._learning_host_from_ref(ref)
+                if learning_host is not None:
+                    effective = {item["ref"]: item for item in self._effective_items(runtime, user, host=learning_host, include_suppressed=True)[0]}
+            if not isinstance(ref, str) or ref not in effective:
+                raise ValidationError("update needs an active corpus ref")
+            item = effective[ref]
+            supplied_digest = payload.get("item_digest")
+            item_digest = _digest(item)
+            if not isinstance(supplied_digest, str) or supplied_digest != item_digest:
+                raise StaleRevision(f"item digest for {ref} is stale")
+            patch = self._validate_patch(payload.get("patch"))
+            try:
+                candidate = self._validate_item(self._catalog_module().update_content(item, patch), allow_origin=True)
+            except ValueError as exc:
+                raise ValidationError(str(exc)) from exc
+            self._require_resolved([candidate])
+            if ref in next_user["items"]:
+                next_user["items"][ref] = candidate
+            else:
+                base = next((row for row in inventory["items"] if row["ref"] == ref), None)
+                if base is None:
+                    host = self._learning_host_from_ref(ref)
+                    event = next(event for event in self._learning_events(host)
+                                 if f"@local/learnings-{host}:{event['learning_id']}" == ref)
+                    base = self._learning_item(host, event)
+                normalized_base = self._normalize_content(base, allow_legacy=True)
+                delta = {field: value for field, value in candidate.items()
+                         if field in ITEM_FIELDS and value != normalized_base.get(field)}
+                if delta:
+                    next_user["overrides"][ref] = {"base_digest": _digest(base), "patch": delta}
+                else:
+                    next_user["overrides"].pop(ref, None)
+            details.update({"ref": ref, "prior_item_digest": item_digest, "item_digest": _digest(candidate)})
+        elif op == "remove":
+            ref = payload.get("ref")
+            if isinstance(ref, str) and ref not in effective:
+                learning_host = self._learning_host_from_ref(ref)
+                if learning_host is not None:
+                    effective = {item["ref"]: item for item in self._effective_items(runtime, user, host=learning_host, include_suppressed=True)[0]}
+            if not isinstance(ref, str) or ref not in effective:
+                raise ValidationError("remove needs an active corpus ref")
+            supplied_digest = payload.get("item_digest")
+            if supplied_digest is not None and supplied_digest != _digest(effective[ref]):
+                raise StaleRevision(f"item digest for {ref} is stale")
+            if ref in next_user["items"]:
+                next_user["items"][ref]["active"] = False
+            else:
+                # The plan must have a stable result digest.  Audit time belongs in
+                # its journal, not in authoring state that is recomputed at Apply.
+                next_user["tombstones"][ref] = {"base_digest": _digest(effective[ref])}
+            details["ref"] = ref
+        elif op == "restore":
+            ref = payload.get("ref")
+            if not isinstance(ref, str):
+                raise ValidationError("restore needs corpus ref")
+            if ref not in {x.get("ref") for x in inventory.get("items", [])}:
+                raise ValidationError("restore is available only for selected installed baseline items")
+            next_user["overrides"].pop(ref, None)
+            next_user["tombstones"].pop(ref, None)
+            details["ref"] = ref
+        elif op == "recover":
+            ref = payload.get("ref")
+            learning_host = self._learning_host_from_ref(ref) if isinstance(ref, str) else None
+            if learning_host is not None:
+                event = next((event for event in self._learning_events(learning_host)
+                              if f"@local/learnings-{learning_host}:{event['learning_id']}" == ref), None)
+                if event is None:
+                    raise ValidationError("recover needs personal corpus ref")
+                next_user["tombstones"].pop(ref, None)
+                suppressions = next_user.setdefault("learning_suppressions", {}).setdefault(learning_host, [])
+                if _digest(event) in suppressions:
+                    suppressions.remove(_digest(event))
+            elif not isinstance(ref, str) or ref not in next_user["items"]:
+                raise ValidationError("recover needs personal corpus ref")
+            else:
+                next_user["items"][ref].pop("active", None)
+            details["ref"] = ref
+        elif op == "select":
+            selection = self._validate_selection(payload.get("selection"), inventory)
+            next_user["selection"] = selection
+            details["selection"] = selection
+        elif op == "reset":
+            suppressions = {host: [_digest(event) for event in self._learning_events(host)]
+                            for host in ("claude", "codex")}
+            next_user = self._empty_user()
+            next_user["learning_suppressions"] = suppressions
+            latest = next_runtime.get("last_successful_install_ref")
+            if not latest:
+                raise CorpusStoreError("cannot reset before install")
+            next_runtime["selected_baseline_ref"] = latest
+            _inv, latest_defaults = self._read_baseline(latest)
+            next_user["selection"] = latest_defaults.get("selection")
+            details["baseline_ref"] = latest
+        elif op == "rollback":
+            history_id = payload.get("history_id")
+            baseline_ref = payload.get("baseline_ref")
+            if history_id is not None:
+                _safe_part(history_id, "history id")
+                record = _json_read(self.user_root / "history" / str(history_id) / "state.json")
+                if not isinstance(record, dict) or "user" not in record or "runtime" not in record:
+                    raise ValidationError("unknown rollback history")
+                next_user = record["user"]
+                # History rollback replays authoring state but preserves the current successful-install pointer.
+                next_runtime["selected_baseline_ref"] = record["runtime"].get("selected_baseline_ref")
+                self._read_baseline(next_runtime["selected_baseline_ref"])
+                details["history_id"] = history_id
+            else:
+                if not isinstance(baseline_ref, str):
+                    raise ValidationError("rollback needs baseline_ref or history_id")
+                target, _target_defaults = self._read_baseline(baseline_ref)
+                next_user = self._rebase_overlays(inventory, target, next_user)
+                next_runtime["selected_baseline_ref"] = baseline_ref
+                details["baseline_ref"] = baseline_ref
+        return next_runtime, next_user, details
+
+    def plan(self, payload: dict[str, Any]) -> dict[str, Any]:
+        with self._lock():
+            self._recover_locked()
+            runtime, user = self._runtime_state(), self._user_state()
+            before = self._authoring_revision(runtime, user)
+            allocated = self._next_personal_id(user) if isinstance(payload, dict) and payload.get("operation", payload.get("op")) == "create" else None
+            next_runtime, next_user, details = self._prepare_operation(payload, runtime, user, allocated_item_id=allocated)
+            self._validate_candidate_projection(next_runtime, next_user)
+            after = self._authoring_revision(next_runtime, next_user)
+            plan_id = uuid.uuid4().hex
+            plan = {
+                "schema_version": SCHEMA_VERSION, "plan_id": plan_id, "created_at": _utcnow(),
+                "expected_revision": before, "result_revision": after, "payload": _copy_json(payload),
+                "details": details, "before": {"runtime": runtime, "user": user},
+                "after": {"runtime": next_runtime, "user": next_user},
+            }
+            if allocated is not None:
+                plan["allocated_item_id"] = allocated
+            self._write_transaction(plan_id, {"state": "PLANNED", "plan": plan})
+            return {key: plan[key] for key in ("schema_version", "plan_id", "expected_revision", "result_revision", "details")}
+
+    def apply(self, plan_id: str, expected_revision: str | None = None) -> dict[str, Any]:
+        _safe_part(plan_id, "plan id")
+        with self._lock():
+            self._recover_locked()
+            journal_path = self.runtime / "transactions" / plan_id / "journal.json"
+            journal = _json_read(journal_path)
+            if not isinstance(journal, dict):
+                raise ValidationError("plan is unknown")
+            if journal.get("state") in {"COMMITTED", "RECOVERED_COMMITTED"} and journal.get("kind") != "install":
+                return self._applied_result(journal)
+            if journal.get("state") != "PLANNED" or journal.get("kind") == "install":
+                raise ValidationError("plan is not ready for apply")
+            plan = journal.get("plan")
+            if not isinstance(plan, dict):
+                raise CorpusStoreError("invalid plan journal")
+            runtime, user = self._runtime_state(), self._user_state()
+            current = self._authoring_revision(runtime, user)
+            expected = expected_revision if expected_revision is not None else plan.get("expected_revision")
+            if expected != current or plan.get("expected_revision") != current:
+                raise StaleRevision(f"plan {plan_id} is stale; current revision is {current}")
+            # Recalculate from payload under the lock; journal after-state is a preview, not authority.
+            allocated = plan.get("allocated_item_id")
+            if allocated is None and plan["payload"].get("operation", plan["payload"].get("op")) == "create":
+                # Persisted pre-allocation plans already resolved their identity in after-state.
+                ref = plan.get("details", {}).get("ref")
+                allocated = ref.split(":", 1)[1] if isinstance(ref, str) and ref.startswith(LOCAL_PACKAGE + ":") else None
+            next_runtime, next_user, details = self._prepare_operation(plan["payload"], runtime, user, allocated_item_id=allocated)
+            self._validate_candidate_projection(next_runtime, next_user)
+            result = self._authoring_revision(next_runtime, next_user)
+            if result != plan.get("result_revision"):
+                raise CorpusStoreError("plan result changed during apply")
+            prepared = {"state": "PREPARED", "plan": plan, "prior_revision": current, "prepared_at": _utcnow()}
+            history_id = f"{prepared['prepared_at'].replace(':', '').replace('+00:00', 'Z')}-{plan_id[:12]}"
+            prepared["history_id"] = history_id
+            self._write_transaction(plan_id, prepared)
+            _atomic_write(self.user_root / "history" / history_id / "state.json", {"runtime": runtime, "user": user, "revision": current})
+            if details.get("operation") == "reset":
+                _atomic_write(self.user_root / "trash" / history_id / "state.json", {"runtime": runtime, "user": user, "revision": current})
+            _atomic_write(self._user_state_path, next_user)
+            _atomic_write(self._runtime_state_path, next_runtime)
+            committed = {"state": "COMMITTED", "plan": plan, "history_id": history_id, "revision": result, "committed_at": _utcnow()}
+            self._write_transaction(plan_id, committed)
+            return {"plan_id": plan_id, "history_id": history_id, "revision": result, "details": details}
+
+    @staticmethod
+    def _applied_result(journal: dict[str, Any]) -> dict[str, Any]:
+        plan = journal["plan"]
+        return {"plan_id": plan["plan_id"], "history_id": journal["history_id"],
+                "revision": plan["result_revision"], "details": plan["details"]}
+
+    # ---- immutable snapshots and history -----------------------------------
+
+    def _selected_items(self, items: list[dict[str, Any]], selection: list[str] | None) -> list[dict[str, Any]]:
+        if selection and "all" in selection:
+            return items
+        selected: list[dict[str, Any]] = []
+        for item in items:
+            if item.get("tier") in {"core", "infra"}:
+                selected.append(item)
+                continue
+            if not selection:
+                continue
+            if item["ref"] in selection or item["package_id"] in selection:
+                selected.append(item)
+                continue
+            if any(f"{item['package_id']}/{domain}" in selection for domain in item.get("domains", [])):
+                selected.append(item)
+        return selected
+
+    def snapshot(self, host: str, selection: list[str] | None = None, dry_run: bool = False,
+                 native: bool = False) -> dict[str, Any]:
+        """Compose an immutable activated-session snapshot.
+
+        A dry run has no durable write path: it compiles in an OS temporary
+        directory and rewrites only the returned private paths to their future
+        content-addressed destination.  The ContentRef is therefore the same
+        value Apply/launch will later publish.
+        """
+        _host(host)
+        if not isinstance(native, bool):
+            raise ValidationError("native activation must be boolean")
+        if dry_run and not self._runtime_state_path.is_file():
+            raise CorpusStoreError("no installed baseline; run install first")
+        lock = transaction_lock(self.state_root) if dry_run else self._lock()
+        with lock:
+            guard_pending(self.state_root)
+            if dry_run and pending_operations(self.state_root):
+                raise CorpusStoreError("source transaction needs recovery before snapshot preview")
+            if not dry_run:
+                self._recover_locked()
+            runtime, user = self._runtime_state(), self._user_state()
+            items, inventory, defaults, baseline_ref = self._effective_items(runtime, user, host=host)
+            active = [item for item in items if item.get("active", True) is not False]
+            effective_selection = self._effective_selection(user, defaults, selection)
+            self._validate_snapshot_selection(effective_selection, inventory, active)
+            selected = self._selected_items(active, effective_selection)
+            self._require_resolved(selected)
+            selected, promotion_warnings = self._resolve_promotions(selected, user, host, baseline_ref)
+            bootstrap_path = self.repo / "compose" / "bootstrap" / "SKILL.md"
+            if not bootstrap_path.is_file():
+                raise CorpusStoreError("private management bootstrap is missing")
+            catalog_path = self.repo / "compose" / "corpus_catalog.py"
+            inputs = {
+                "schema_version": SCHEMA_VERSION, "host": host, "baseline_ref": baseline_ref,
+                "selection": effective_selection,
+                "selection_digest": _digest(effective_selection),
+                "authoring_revision": self._authoring_revision(runtime, user),
+                "item_digests": {item["ref"]: _digest(item) for item in sorted(selected, key=lambda x: x["ref"])},
+                "learning_digest": _digest(self._learning_events(host)),
+                "promotion_digest": _digest(self._baseline_promotions(baseline_ref)),
+                "compiler_digest": _digest(catalog_path.read_bytes()) if catalog_path.is_file() else None,
+                "store_schema_digest": _digest(Path(__file__).read_bytes()),
+                "bootstrap_digest": _digest(bootstrap_path.read_bytes()),
+            }
+            if native:
+                import sys
+                inputs["native"] = True
+                inputs["native_python"] = sys.executable
+            content_ref = _digest(inputs)
+            root = self.sessions / "snapshots" / content_ref
+            _reject_symlink_path(self.sessions)
+            _reject_symlink_path(self.sessions / "snapshots")
+            catalog = self._catalog_module()
+            if not hasattr(catalog, "compile_items"):
+                raise CorpusStoreError("corpus catalog has no compile_items")
+            if not dry_run and (root / "inventory.json").exists():
+                verified = verify_snapshot(root, content_ref)
+                if verified["inputs"] != inputs:
+                    raise CorpusStoreError(f"immutable snapshot collision: {content_ref}")
+                output = verified["output"]
+            else:
+                if dry_run:
+                    temp = tempfile.TemporaryDirectory(prefix="agent-bios-snapshot-")
+                    staging = Path(temp.name) / "snapshot"
+                    staging.mkdir()
+                else:
+                    temp = None
+                    staging = root.with_name(f".{root.name}.staging-{uuid.uuid4().hex}")
+                    staging.mkdir(parents=True, exist_ok=False)
+                try:
+                    compiled = catalog.compile_items(_copy_json(selected), staging, host, native=True) if native else catalog.compile_items(_copy_json(selected), staging, host)
+                    if not isinstance(compiled, dict) or not isinstance(compiled.get("instruction_text"), str):
+                        raise CorpusStoreError("catalog compiler returned invalid output")
+                    files = _snapshot_relative_paths(compiled.get("files"))
+                    output = {
+                        "instruction_text": compiled.get("instruction_text", ""),
+                        "files": sorted(set(files) | {"bootstrap/SKILL.md"}), "item_refs": compiled.get("item_refs", []),
+                        "unavailable": compiled.get("unavailable", []) + promotion_warnings,
+                    }
+                    assets = _snapshot_assets(compiled.get("assets", {}), files)
+                    if assets:
+                        output["assets"] = assets
+                    invocation = f"Corpus management: invoke $corpus using {root / 'bootstrap' / 'SKILL.md'}."
+                    output["instruction_text"] = output["instruction_text"].rstrip() + "\n\n" + invocation + "\n"
+                    for plugin in assets.get("claude_plugins", []):
+                        for agent_path in (staging / plugin / "agents").glob("*.md"):
+                            with agent_path.open("a", encoding="utf-8") as agent_file:
+                                agent_file.write("\n\n" + invocation + "\n")
+                    if dry_run:
+                        output["instruction_text"] = output["instruction_text"].replace(str(staging), str(root))
+                    else:
+                        bootstrap_target = staging / "bootstrap" / "SKILL.md"
+                        bootstrap_target.parent.mkdir(parents=True, exist_ok=True)
+                        bootstrap_target.write_bytes(bootstrap_path.read_bytes())
+                        _rewrite_staged_paths(staging, root)
+                        output["instruction_text"] = output["instruction_text"].replace(str(staging), str(root))
+                        _atomic_write(staging / "inventory.json", {"inputs": inputs, "items": selected})
+                        _atomic_write(staging / "output.json", output)
+                        digests = _snapshot_file_digests(staging, output["files"])
+                        _atomic_write(staging / "inventory.json", {"inputs": inputs, "items": selected, "file_digests": digests})
+                    # A directory rename is the publication point; no consumer sees a partial snapshot.
+                    if not dry_run:
+                        root.parent.mkdir(parents=True, exist_ok=True)
+                        try:
+                            os.replace(staging, root)
+                        except FileExistsError:
+                            if verify_snapshot(root, content_ref)["inputs"] != inputs:
+                                raise CorpusStoreError(f"immutable snapshot collision: {content_ref}")
+                finally:
+                    if temp is not None:
+                        temp.cleanup()
+                    elif staging.exists():
+                        import shutil
+                        shutil.rmtree(staging)
+            return {"content_ref": content_ref, "path": str(root), "instruction_text": output["instruction_text"],
+                    "revision": inputs["authoring_revision"], "unavailable": output.get("unavailable", []),
+                    "assets": output.get("assets", {})}
+
+    def history(self, ref: str | None = None) -> list[dict[str, Any]]:
+        root = self.user_root / "history"
+        if not root.is_dir():
+            return []
+        rows: list[dict[str, Any]] = []
+        for path in sorted(root.glob("*/state.json"), reverse=True):
+            record = _json_read(path)
+            if not isinstance(record, dict):
+                continue
+            if ref is not None:
+                user = record.get("user", {})
+                if ref not in user.get("items", {}) and ref not in user.get("overrides", {}) and ref not in user.get("tombstones", {}):
+                    continue
+            rows.append({"history_id": path.parent.name, "revision": record.get("revision"), "path": str(path.parent)})
+        return rows
+
+    def snapshot_inventory(self, content_ref: str) -> dict[str, Any]:
+        """Read a pinned snapshot by ContentRef without resolving current state."""
+        _safe_part(content_ref, "content ref")
+        with self._lock():
+            self._recover_locked()
+            root = self.sessions / "snapshots" / content_ref
+            verified = verify_snapshot(root, content_ref)
+            output = verified["output"]
+            return {"content_ref": content_ref, "path": str(root), "inputs": verified["inputs"],
+                    "items": verified["items"], "files": output.get("files"),
+                    "item_refs": output.get("item_refs"), "instruction_text": output.get("instruction_text"),
+                    "unavailable": output.get("unavailable"), "assets": output.get("assets", {})}
+
+    def capture_learning(self, host: str, record: dict[str, Any]) -> dict[str, Any]:
+        """Append exact captured bytes to a host-private immutable source journal."""
+        _host(host)
+        if not isinstance(record, dict):
+            raise ValidationError("learning capture must be an object")
+        event = _copy_json(record)
+        unknown = set(event) - LEARNING_FIELDS
+        required = {"schema_version", "learning_id", "lesson", "domain", "created", "supporting_sessions"}
+        if unknown or not required <= set(event):
+            raise ValidationError("learning record must use the collector v1 schema exactly")
+        if event["schema_version"] != 1 or not isinstance(event["learning_id"], str) or not LEARNING_ID_RE.fullmatch(event["learning_id"]):
+            raise ValidationError("invalid collector learning identity")
+        if not isinstance(event["lesson"], str) or not isinstance(event["domain"], str) or not isinstance(event["created"], str):
+            raise ValidationError("invalid collector learning content")
+        sessions = event["supporting_sessions"]
+        if not isinstance(sessions, list) or not sessions or not all(isinstance(value, str) for value in sessions):
+            raise ValidationError("invalid collector learning provenance")
+        path = self.user_root / "learnings" / host / "events.jsonl"
+        with self._lock():
+            self._recover_locked()
+            prior = self._learning_events(host)
+            if any(x.get("learning_id") == event["learning_id"] for x in prior):
+                raise ValidationError("learning_id already captured")
+            _reject_symlink_path(path, leaf=False)
+            path.parent.mkdir(parents=True, exist_ok=True)
+            # Append is atomic under the store lock and fsync makes the capture durable before return.
+            with path.open("a", encoding="utf-8") as handle:
+                handle.write(_canonical(event).decode("utf-8") + "\n")
+                handle.flush()
+                os.fsync(handle.fileno())
+            return {"host": host, "learning_id": event["learning_id"], "digest": _digest(event), "revision": self._authoring_revision(self._runtime_state(), self._user_state())}