Skip to content

YujunZhou/tellonce / codex

tellonce

Verified

Use to view, explain, correct, delete or reorganize the user's saved preferences, or to record one by hand when automatic recording is off; learning and rule injection otherwise run automatically through Codex hooks.

FileKindSize
.codex-plugin/plugin.jsonconfig1.3 KB
SKILL.mdskill md12.0 KB
dashboard.shexecutablescript348 B
docs/CC_PARITY_MATRIX.mdmarkdown7.3 KB
docs/README.mdmarkdown3.4 KB
doctor.shexecutablescript345 B
hooks/hooks.jsonconfig714 B
hooks/posttooluse-deterministic-block.shexecutablescript2.0 KB
hooks/sessionstart-init.shexecutablescript1.9 KB
hooks/userpromptsubmit-dispatch.pyscript2.6 KB
hooks/userpromptsubmit-memory-upsert.shscript326 B
hooks/userpromptsubmit-pending-inject.shexecutablescript2.0 KB
hooks/userpromptsubmit-retrieve-inject.shexecutablescript3.1 KB
hooks/userpromptsubmit-shadow-alert-inject.shexecutablescript1.2 KB
install.shexecutablescript13.9 KB
shared_lib/_install_merge_settings.pyscript12.1 KB
shared_lib/_pt_hooks.txtmarkdown407 B
shared_lib/correction_interpretation.pyscript8.5 KB
shared_lib/detect_user_prefer.pyscript7.2 KB
shared_lib/deterministic_block.pyscript9.3 KB
shared_lib/event_obligations.pyscript19.8 KB
shared_lib/execution_support.pyscript75.8 KB
shared_lib/fingerprints.yamlconfig1.1 KB
shared_lib/learning_policy.pyscript4.6 KB
shared_lib/memory_judge.pyscript84.8 KB
shared_lib/memory_publication.pyscript14.9 KB
shared_lib/memory_runtime.pyscript12.2 KB
shared_lib/memory_store.pyscript99.6 KB
shared_lib/memory_upsert.pyscript57.1 KB
shared_lib/memory_upsert_hook.pyscript4.6 KB
shared_lib/model_requests.pyscript5.8 KB
shared_lib/path_config.pyscript13.3 KB
shared_lib/pending_queue_manager.pyscript23.4 KB
shared_lib/pt_platform.pyscript1.5 KB
shared_lib/redaction.pyscript3.4 KB
shared_lib/retrieve_inject.pyexecutablescript57.9 KB
shared_lib/rule_selection.pyscript18.9 KB
shared_lib/shadow_alert_inject.pyscript6.1 KB
shared_lib/training_memory.pyscript17.8 KB
shared_lib/transcript_adapter.pyscript13.7 KB
shared_lib/verify_compliance.pyexecutablescript24.5 KB
shared_lib/verify_retry_shadow.pyscript27.4 KB
tellonce_codex/__init__.pyscript52 B
tellonce_codex/__main__.pyscript49 B
tellonce_codex/cli.pyscript6.8 KB
tellonce_codex/codex_posttooluse_block.pyscript11.2 KB
tellonce_codex/dashboard.pyscript3.4 KB
tellonce_codex/doctor.pyscript10.9 KB
tellonce_codex/index.pyscript1.8 KB
tellonce_codex/install.pyscript3.1 KB
tellonce_codex/install_codex_hooks.pyscript15.1 KB
tellonce_codex/ledger.pyscript17.1 KB
tellonce_codex/memory.pyscript5.3 KB
tellonce_codex/migrate.pyscript1.3 KB
tellonce_codex/mode.pyscript2.3 KB
tellonce_codex/paths.pyscript8.6 KB
tellonce_codex/promote.pyscript4.4 KB
tellonce_codex/scan.pyscript2.6 KB
tellonce_codex/uninstall.pyscript1.7 KB
tellonce_codex/verify.pyscript5.3 KB
tellonce_codex/wrapper.pyscript12.0 KB
uninstall.shexecutablescript4.6 KB

shared_lib/memory_store.py

View on GitHub
#!/usr/bin/env python3
"""SQLite-backed source of truth for tellonce memories.

Semantic decisions are supplied by an LLM plan. This module only performs
schema validation, optimistic concurrency checks, transactional updates, and
deterministic Markdown/JSON projection.
"""
from __future__ import annotations

import hashlib
import json
import os
from pathlib import Path
import re
import sys
import sqlite3
import time
import uuid
from contextlib import contextmanager


import learning_policy

SCHEMA_VERSION = 3
DB_FILENAME = ".tellonce.sqlite3"
ACTIVE_INDEX_FILENAME = ".tellonce-active.json"
VALID_OPERATIONS = {
    "NOOP", "UPDATE", "SUPERSEDE", "SPLIT", "NEW", "NEEDS_USER",
    "REJECT", "ARCHIVE", "RESTORE",
}
SPLIT_CHILD_OPERATIONS = {
    "NOOP", "UPDATE", "SUPERSEDE", "NEW", "REJECT", "ARCHIVE", "RESTORE",
}
VALID_ATOMIC_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$")
VALID_EXTRA_KEY = re.compile(r"^[A-Za-z][A-Za-z0-9_-]{0,63}$")
VALID_CONFIDENCE = {"high", "medium", "low"}
VALID_SCOPES = {"global", "project", "task", "unclear"}

DOMAIN_ABBREVIATIONS = {
    "formatting": "fmt",
    "language": "lang",
    "workflow": "wf",
    "coding": "code",
    "tools": "tool",
    "experiment": "exp",
    "writing": "wrt",
    "communication": "comm",
    "other": "oth",
}
TYPE_ABBREVIATIONS = {
    "preference": "pref",
    "pitfall": "pit",
    "friction": "fric",
    "user": "usr",
    "project": "proj",
    "reference": "ref",
}
DOMAIN_HEADINGS = {
    "formatting": "Formatting",
    "language": "Language",
    "workflow": "Workflow",
    "coding": "Coding",
    "tools": "Tools",
    "experiment": "Experiment",
    "writing": "Writing",
    "communication": "Communication",
    "other": "Other",
}
RECORD_FIELDS = (
    "name",
    "description",
    "type",
    "domain",
    "scope",
    "scope_anchor",
    "condition",
    "confidence",
    "rule_text",
    "applies_when",
    "does_not_apply_when",
    "body",
)


class MemoryStoreError(RuntimeError):
    pass


class StaleSnapshotError(MemoryStoreError):
    pass


class InvalidPlanError(MemoryStoreError):
    pass


def _normalize_exact_quote(value: str, source_text: str) -> str:
    text = str(value or "").strip()
    if text in source_text:
        return text
    quote_pairs = {
        '"': '"',
        "'": "'",
        "\u201c": "\u201d",
        "\u2018": "\u2019",
    }
    if len(text) >= 2 and quote_pairs.get(text[0]) == text[-1]:
        inner = text[1:-1]
        if inner and inner in source_text:
            return inner
    return text


def _normalize_quote_against_sources(span: str, sources: list[str]) -> str:
    for source in sources:
        normalized = _normalize_exact_quote(span, source)
        if normalized and normalized in source:
            return normalized
    return _normalize_exact_quote(span, sources[0] if sources else "")


def _utc_now() -> str:
    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())


def _today() -> str:
    return time.strftime("%Y-%m-%d", time.gmtime())


def _sha256(text: str) -> str:
    return hashlib.sha256(text.encode("utf-8")).hexdigest()


def _json(value) -> str:
    return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"))


def _safe_scalar(value) -> str:
    return re.sub(r"[\r\n]+", " ", str(value if value is not None else "")).strip()


def _strip_balanced_quotes(value: str) -> str:
    if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
        return value[1:-1]
    return value


def parse_frontmatter(text: str):
    """Parse the simple scalar/list YAML subset used by tellonce rule files."""
    if text.startswith("\ufeff"):
        text = text.lstrip("\ufeff")
    if not text.startswith("---\n"):
        raise ValueError("missing frontmatter")
    end = text.find("\n---\n", 4)
    separator_length = 5
    if end < 0 and text.endswith("\n---"):
        end = len(text) - 4
        separator_length = 4
    if end < 0:
        raise ValueError("unterminated frontmatter")
    raw = text[4:end]
    body = text[end + separator_length :]
    data = {}
    current_key = None
    for raw_line in raw.splitlines():
        if not raw_line.strip():
            continue
        stripped = raw_line.strip()
        if stripped.startswith("- ") and current_key:
            current = data.setdefault(current_key, [])
            if current == "":
                current = []
                data[current_key] = current
            if isinstance(current, list):
                current.append(_strip_balanced_quotes(stripped[2:].strip()))
            continue
        if ":" not in raw_line:
            continue
        key, value = raw_line.split(":", 1)
        key = key.strip()
        if not key:
            continue
        value = _strip_balanced_quotes(value.strip())
        current_key = key
        if value == "[]":
            data[key] = []
        elif value == "":
            data[key] = ""
        else:
            data[key] = value
    return data, body


def _render_frontmatter(data: dict, body: str) -> str:
    order = (
        "schema_version",
        "atomic_id",
        "name",
        "description",
        "type",
        "domain",
        "scope",
        "scope_anchor",
        "condition",
        "confidence",
        "status",
        "revision",
        "rule_text",
        "applies_when",
        "does_not_apply_when",
        "supersedes",
        "superseded_by",
        "created",
        "updated",
        "content_sha256",
    )
    lines = ["---"]
    emitted = set()
    for key in order:
        if key not in data:
            continue
        emitted.add(key)
        value = data[key]
        if isinstance(value, list):
            if not value:
                lines.append(f"{key}: []")
            else:
                lines.append(f"{key}:")
                lines.extend(f"  - {_safe_scalar(item)}" for item in value)
        else:
            lines.append(f"{key}: {_safe_scalar(value)}")
    for key in sorted(set(data) - emitted):
        value = data[key]
        if isinstance(value, list):
            if not value:
                lines.append(f"{key}: []")
            else:
                lines.append(f"{key}:")
                lines.extend(f"  - {_safe_scalar(item)}" for item in value)
        elif isinstance(value, (str, int, float)):
            lines.append(f"{key}: {_safe_scalar(value)}")
    lines.extend(["---", body.rstrip(), ""])
    return "\n".join(lines)


def _atomic_write(path: Path, content: str, retries: int = 6) -> None:
    """Write and replace in the target directory, retrying Windows share errors."""
    path.parent.mkdir(parents=True, exist_ok=True)
    tmp = path.with_name(f"{path.name}.tmp.{os.getpid()}.{uuid.uuid4().hex[:8]}")
    try:
        with tmp.open("w", encoding="utf-8", newline="\n") as handle:
            handle.write(content)
            handle.flush()
            os.fsync(handle.fileno())
        try:
            os.chmod(tmp, 0o600)
        except OSError:
            pass
        delay = 0.05
        for attempt in range(retries):
            try:
                os.replace(str(tmp), str(path))
                break
            except PermissionError:
                if attempt + 1 >= retries:
                    raise
                time.sleep(delay)
                delay = min(delay * 2, 0.8)
        try:
            os.chmod(path, 0o600)
        except OSError:
            pass
        try:
            directory_fd = os.open(str(path.parent), os.O_RDONLY)
            try:
                os.fsync(directory_fd)
            finally:
                os.close(directory_fd)
        except OSError:
            pass
    finally:
        try:
            tmp.unlink()
        except OSError:
            pass


class MemoryStore:
    def __init__(self, memory_dir, db_path=None, legacy_dirs=None):
        self.memory_dir = Path(memory_dir).expanduser().resolve()
        self.db_path = Path(db_path).expanduser().resolve() if db_path else self.memory_dir / DB_FILENAME
        self.legacy_dirs = [
            Path(path).expanduser().resolve()
            for path in (legacy_dirs or [])
            if Path(path).expanduser().resolve() != self.memory_dir
        ]

    def _tighten_permissions(self) -> None:
        try:
            os.chmod(self.memory_dir, 0o700)
        except OSError:
            pass
        for path in (
            self.db_path,
            Path(f"{self.db_path}-wal"),
            Path(f"{self.db_path}-shm"),
        ):
            if not path.exists():
                continue
            try:
                os.chmod(path, 0o600)
            except OSError:
                pass

    def connect(self, timeout_seconds: float = 30.0):
        self.memory_dir.mkdir(parents=True, exist_ok=True)
        self._tighten_permissions()
        conn = sqlite3.connect(
            str(self.db_path),
            timeout=max(0.0, timeout_seconds),
            isolation_level=None,
        )
        self._tighten_permissions()
        try:
            conn.row_factory = sqlite3.Row
            conn.execute("PRAGMA foreign_keys=ON")
            conn.execute(f"PRAGMA busy_timeout={int(max(0.0, timeout_seconds) * 1000)}")
            conn.execute("PRAGMA synchronous=FULL")
            return conn
        except Exception:
            conn.close()
            raise

    @contextmanager
    def connection(self, timeout_seconds: float = 30.0):
        conn = self.connect(timeout_seconds=timeout_seconds)
        try:
            yield conn
        finally:
            self._tighten_permissions()
            conn.close()

    @contextmanager
    def _initialization_lock(self):
        """Serialize supported initialization/binding across worker processes."""
        self.memory_dir.mkdir(parents=True, exist_ok=True)
        lock_path = self.db_path.with_name(self.db_path.name + '.init.lock')
        lock_path.parent.mkdir(parents=True, exist_ok=True)
        fd = os.open(str(lock_path), os.O_CREAT | os.O_RDWR, 0o600)
        acquired = False
        try:
            if os.fstat(fd).st_size == 0:
                os.write(fd, b'0')
            deadline = time.monotonic() + 30
            while True:
                try:
                    if os.name == 'nt':
                        import msvcrt
                        os.lseek(fd, 0, os.SEEK_SET)
                        msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
                    else:
                        import fcntl
                        fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
                    acquired = True
                    break
                except (BlockingIOError, PermissionError):
                    if time.monotonic() >= deadline:
                        raise MemoryStoreError('memory initialization lock timed out')
                    time.sleep(0.05)
            yield
        finally:
            if acquired:
                if os.name == 'nt':
                    import msvcrt
                    os.lseek(fd, 0, os.SEEK_SET)
                    msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
                else:
                    import fcntl
                    fcntl.flock(fd, fcntl.LOCK_UN)
            os.close(fd)

    def peek_namespace(self) -> str | None:
        """Read ownership before initialization; None denotes an empty/missing DB."""
        if not self.db_path.exists():
            return None
        check = sqlite3.connect(self.db_path.absolute().as_uri() + '?mode=ro', uri=True)
        try:
            if not check.execute("SELECT 1 FROM sqlite_master WHERE type='table' AND name='meta'").fetchone():
                return None
            owner = check.execute("SELECT value FROM meta WHERE key='memory_namespace'").fetchone()
            return owner[0] if owner else ''
        finally:
            check.close()

    def initialize(self, namespace: str | None = None) -> None:
        with self._initialization_lock():
            self._initialize_locked(namespace)

    def _initialize_locked(self, namespace: str | None = None) -> None:
        if namespace is not None:
            if not isinstance(namespace, str) or not namespace.strip():
                raise MemoryStoreError('an explicit memory namespace is required')
            # Reject a wrong pre-existing library before migrations/projection
            # can modify it. Binding is checked again inside its transaction.
            if self.db_path.exists() and self.peek_namespace() is not None:
                check = sqlite3.connect(self.db_path.absolute().as_uri() + '?mode=ro', uri=True)
                try:
                    owner = check.execute("SELECT value FROM meta WHERE key='memory_namespace'").fetchone()
                    if owner and owner[0] != namespace:
                        raise MemoryStoreError('memory namespace ownership mismatch')
                    if not owner and (check.execute('SELECT 1 FROM rules LIMIT 1').fetchone()
                                      or check.execute('SELECT 1 FROM turns LIMIT 1').fetchone()):
                        raise MemoryStoreError('cannot relabel an existing unowned library')
                finally:
                    check.close()
        projection_required = False
        with self.connection() as conn:
            conn.execute("PRAGMA journal_mode=WAL")
            conn.executescript(
                """
                CREATE TABLE IF NOT EXISTS meta (
                    key TEXT PRIMARY KEY,
                    value TEXT NOT NULL
                );
                CREATE TABLE IF NOT EXISTS turns (
                    turn_key TEXT PRIMARY KEY,
                    source_hash TEXT NOT NULL,
                    source_text TEXT NOT NULL,
                    context_text TEXT NOT NULL DEFAULT '',
                    judge_cli TEXT NOT NULL DEFAULT '',
                    clarification_candidates_json TEXT NOT NULL DEFAULT '[]',
                    status TEXT NOT NULL,
                    lease_owner TEXT,
                    lease_expires_at REAL,
                    attempt_count INTEGER NOT NULL DEFAULT 0,
                    plan_json TEXT,
                    result_json TEXT,
                    last_error TEXT,
                    created_at TEXT NOT NULL,
                    updated_at TEXT NOT NULL
                );
                CREATE TABLE IF NOT EXISTS rules (
                    atomic_id TEXT PRIMARY KEY,
                    type TEXT NOT NULL,
                    domain TEXT NOT NULL,
                    scope TEXT NOT NULL,
                    scope_anchor TEXT NOT NULL DEFAULT '',
                    status TEXT NOT NULL,
                    current_revision INTEGER NOT NULL,
                    superseded_by TEXT,
                    created_at TEXT NOT NULL,
                    updated_at TEXT NOT NULL
                );
                CREATE TABLE IF NOT EXISTS rule_versions (
                    atomic_id TEXT NOT NULL,
                    revision INTEGER NOT NULL,
                    name TEXT NOT NULL,
                    description TEXT NOT NULL,
                    condition TEXT NOT NULL,
                    confidence TEXT NOT NULL,
                    rule_text TEXT NOT NULL,
                    applies_when TEXT NOT NULL,
                    does_not_apply_when TEXT NOT NULL,
                    body TEXT NOT NULL,
                    source_text TEXT NOT NULL,
                    extra_json TEXT NOT NULL,
                    content_hash TEXT NOT NULL,
                    created_at TEXT NOT NULL,
                    PRIMARY KEY (atomic_id, revision),
                    FOREIGN KEY (atomic_id) REFERENCES rules(atomic_id)
                );
                CREATE TABLE IF NOT EXISTS rule_relations (
                    from_id TEXT NOT NULL,
                    to_id TEXT NOT NULL,
                    relation TEXT NOT NULL,
                    turn_key TEXT NOT NULL,
                    created_at TEXT NOT NULL,
                    PRIMARY KEY (from_id, to_id, relation)
                );
                CREATE TABLE IF NOT EXISTS transactions (
                    txn_id TEXT PRIMARY KEY,
                    turn_key TEXT UNIQUE NOT NULL,
                    status TEXT NOT NULL,
                    base_generation INTEGER NOT NULL,
                    plan_json TEXT NOT NULL,
                    result_json TEXT,
                    committed_generation INTEGER,
                    error TEXT,
                    created_at TEXT NOT NULL,
                    committed_at TEXT,
                    projected_at TEXT
                );
                CREATE TABLE IF NOT EXISTS id_counters (
                    prefix TEXT PRIMARY KEY,
                    next_value INTEGER NOT NULL
                );
                """
            )
            conn.execute(
                "INSERT OR IGNORE INTO meta(key, value) VALUES('schema_version', ?)",
                (str(SCHEMA_VERSION),),
            )
            stored_version_row = conn.execute(
                "SELECT value FROM meta WHERE key='schema_version'"
            ).fetchone()
            try:
                stored_version = int(stored_version_row["value"])
            except (TypeError, ValueError):
                stored_version = 0
            if stored_version > SCHEMA_VERSION:
                raise MemoryStoreError(
                    f"database schema {stored_version} is newer than supported "
                    f"schema {SCHEMA_VERSION}; upgrade tellonce before opening it"
                )
            conn.execute("INSERT OR IGNORE INTO meta(key, value) VALUES('generation', '0')")
            conn.execute(
                "INSERT OR IGNORE INTO meta(key, value) "
                "VALUES('projection_required', '0')"
            )
            columns = {
                row["name"] for row in conn.execute("PRAGMA table_info(turns)").fetchall()
            }
            if "context_text" not in columns:
                conn.execute(
                    "ALTER TABLE turns ADD COLUMN context_text TEXT NOT NULL DEFAULT ''"
                )
            if "context_reference_json" not in columns:
                conn.execute("ALTER TABLE turns ADD COLUMN context_reference_json TEXT NOT NULL DEFAULT 'null'")
            if "signal_state" not in columns:
                conn.execute("ALTER TABLE turns ADD COLUMN signal_state TEXT NOT NULL DEFAULT 'not_required'")
            if "judge_cli" not in columns:
                conn.execute(
                    "ALTER TABLE turns ADD COLUMN judge_cli TEXT NOT NULL DEFAULT ''"
                )
            if "clarification_candidates_json" not in columns:
                conn.execute(
                    """
                    ALTER TABLE turns
                    ADD COLUMN clarification_candidates_json TEXT NOT NULL DEFAULT '[]'
                    """
                )
            if "lease_owner" not in columns:
                conn.execute("ALTER TABLE turns ADD COLUMN lease_owner TEXT")
            if "lease_expires_at" not in columns:
                conn.execute("ALTER TABLE turns ADD COLUMN lease_expires_at REAL")
            if "attempt_count" not in columns:
                conn.execute(
                    "ALTER TABLE turns ADD COLUMN attempt_count INTEGER NOT NULL DEFAULT 0"
                )
            if "forced" not in columns:
                conn.execute(
                    "ALTER TABLE turns ADD COLUMN forced INTEGER NOT NULL DEFAULT 0"
                )
            rule_columns = {
                row["name"] for row in conn.execute("PRAGMA table_info(rules)").fetchall()
            }
            legacy_scope_rows = bool(
                conn.execute(
                    "SELECT 1 FROM rules WHERE scope LIKE 'project:%' LIMIT 1"
                ).fetchone()
            )
            projection_required = (
                "scope_anchor" not in rule_columns or legacy_scope_rows
            )
            if projection_required:
                # Persist the retry marker before changing schema or canonical
                # rows, so interruption cannot leave stale projections unmarked.
                conn.execute(
                    "UPDATE meta SET value='1' WHERE key='projection_required'"
                )
            if "scope_anchor" not in rule_columns:
                conn.execute(
                    "ALTER TABLE rules ADD COLUMN scope_anchor TEXT NOT NULL DEFAULT ''"
                )
            migrated_scopes = conn.execute(
                """
                UPDATE rules
                SET scope_anchor=CASE
                        WHEN scope_anchor='' THEN substr(scope, length('project:') + 1)
                        ELSE scope_anchor
                    END,
                    scope='project'
                WHERE scope LIKE 'project:%'
                """
            )
            transaction_columns = {
                row["name"] for row in conn.execute("PRAGMA table_info(transactions)").fetchall()
            }
            if "committed_generation" not in transaction_columns:
                conn.execute(
                    "ALTER TABLE transactions ADD COLUMN committed_generation INTEGER"
                )
            conn.execute(
                """
                UPDATE transactions
                SET committed_generation=CAST(
                    (SELECT value FROM meta WHERE key='generation') AS INTEGER
                )
                WHERE status='committed' AND committed_generation IS NULL
                """
            )
            conn.execute(
                "INSERT OR REPLACE INTO meta(key, value) VALUES('schema_version', ?)",
                (str(SCHEMA_VERSION),),
            )
        if namespace is not None:
            self._bind_namespace_locked(namespace)
        if not self.get_namespace() and self._import_legacy_if_empty():
            with self.connection() as conn:
                conn.execute(
                    "UPDATE meta SET value='1' WHERE key='projection_required'"
                )
        with self.connection() as conn:
            projection_required = (
                conn.execute(
                    "SELECT value FROM meta WHERE key='projection_required'"
                ).fetchone()["value"]
                == "1"
            )
        if projection_required:
            self.project()

    def generation(self) -> int:
        with self.connection() as conn:
            row = conn.execute("SELECT value FROM meta WHERE key='generation'").fetchone()
            return int(row["value"]) if row else 0

    def _record_from_row(self, row) -> dict:
        record = {
            "atomic_id": row["atomic_id"],
            "revision": int(row["current_revision"]),
            "status": row["status"],
            "superseded_by": row["superseded_by"] or "",
            "created": row["created_at"],
            "updated": row["updated_at"],
            "type": row["type"],
            "domain": row["domain"],
            "scope": row["scope"],
            "scope_anchor": row["scope_anchor"],
            "name": row["name"],
            "description": row["description"],
            "condition": row["condition"],
            "confidence": row["confidence"],
            "rule_text": row["rule_text"],
            "applies_when": row["applies_when"],
            "does_not_apply_when": row["does_not_apply_when"],
            "body": row["body"],
            "source_text": row["source_text"],
            "content_hash": row["content_hash"],
        }
        try:
            record["extra"] = json.loads(row["extra_json"] or "{}")
        except (TypeError, json.JSONDecodeError):
            record["extra"] = {}
        return record

    def _current_records(self, conn, active_only=False):
        where = "WHERE r.status='active' AND r.superseded_by IS NULL" if active_only else ""
        rows = conn.execute(
            f"""
            SELECT r.*, v.name, v.description, v.condition, v.confidence,
                   v.rule_text, v.applies_when, v.does_not_apply_when,
                   v.body, v.source_text, v.extra_json, v.content_hash
            FROM rules r
            JOIN rule_versions v
              ON v.atomic_id=r.atomic_id AND v.revision=r.current_revision
            {where}
            ORDER BY r.domain, r.type, r.atomic_id
            """
        ).fetchall()
        return [self._record_from_row(row) for row in rows]

    def snapshot(self):
        with self.connection() as conn:
            generation_row = conn.execute("SELECT value FROM meta WHERE key='generation'").fetchone()
            generation = int(generation_row["value"]) if generation_row else 0
            return generation, self._current_records(conn, active_only=True)

    def all_records(self):
        with self.connection() as conn:
            return self._current_records(conn, active_only=False)

    def bind_namespace(self, namespace: str) -> None:
        """Permanently bind a new experiment store before any learning occurs."""
        with self._initialization_lock():
            self._bind_namespace_locked(namespace)

    def _bind_namespace_locked(self, namespace: str) -> None:
        if not isinstance(namespace, str) or not namespace.strip():
            raise MemoryStoreError('an explicit memory namespace is required')
        with self.connection() as conn:
            conn.execute('BEGIN IMMEDIATE')
            existing = conn.execute("SELECT value FROM meta WHERE key='memory_namespace'").fetchone()
            if existing:
                if existing['value'] != namespace:
                    raise MemoryStoreError('memory namespace ownership mismatch')
                conn.execute('COMMIT')
                return
            if (conn.execute('SELECT 1 FROM rules LIMIT 1').fetchone()
                    or conn.execute('SELECT 1 FROM turns LIMIT 1').fetchone()):
                raise MemoryStoreError('bind namespace before learning; never relabel an existing library')
            conn.execute("INSERT INTO meta(key,value) VALUES('memory_namespace',?)", (namespace,))
            conn.execute('COMMIT')

    def get_namespace(self) -> str:
        with self.connection() as conn:
            row = conn.execute("SELECT value FROM meta WHERE key='memory_namespace'").fetchone()
            return row['value'] if row else ''

    def ensure_turn(
        self,
        turn_key: str,
        source_text: str,
        context_text: str = "",
        judge_cli: str = "",
        clarification_candidates=None,
        forced: bool = False,
        context_reference=None,
        detect_signal: bool = False,
        expected_namespace: str | None = None,
    ):
        source_hash = _sha256(source_text)
        now = _utc_now()
        with self.connection() as conn:
            conn.execute("BEGIN IMMEDIATE")
            if expected_namespace is not None:
                owner = conn.execute("SELECT value FROM meta WHERE key='memory_namespace'").fetchone()
                if (owner['value'] if owner else '') != expected_namespace:
                    raise MemoryStoreError('request ownership changed before turn registration')
            row = conn.execute("SELECT * FROM turns WHERE turn_key=?", (turn_key,)).fetchone()
            if row:
                if row["source_hash"] != source_hash:
                    conn.execute("ROLLBACK")
                    raise MemoryStoreError("turn_key already exists with different source text")
                if forced and not int(row["forced"] or 0):
                    conn.execute(
                        "UPDATE turns SET forced=1, updated_at=? WHERE turn_key=?",
                        (now, turn_key),
                    )
                conn.execute("COMMIT")
                result = json.loads(row["result_json"]) if row["result_json"] else None
                return {"status": row["status"], "result": result}
            conn.execute(
                """
                INSERT INTO turns(
                    turn_key, source_hash, source_text, context_text, judge_cli,
                    clarification_candidates_json,
                    forced, context_reference_json, signal_state, status, created_at, updated_at
                ) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', ?, ?)
                """,
                (
                    turn_key,
                    source_hash,
                    source_text,
                    context_text,
                    _safe_scalar(judge_cli).lower(),
                    _json(
                        list(
                            dict.fromkeys(
                                str(item).strip()
                                for item in (clarification_candidates or [])
                                if str(item).strip()
                            )
                        )
                    ),
                    1 if forced else 0,
                    _json(context_reference),
                    'unchecked' if detect_signal else 'not_required',
                    now,
                    now,
                ),
            )
            conn.execute("COMMIT")
        return {"status": "pending", "result": None}

    def save_resolved_context(self, turn_key: str, lease_owner: str,
                              context_text: str, signal: bool) -> None:
        """Checkpoint admission/context under the current worker lease."""
        with self.connection() as conn:
            updated = conn.execute(
                "UPDATE turns SET context_text=?, signal_state=?, updated_at=? "
                "WHERE turn_key=? AND status='resolving' AND lease_owner=? "
                "AND lease_expires_at>?",
                (context_text, 'present' if signal else 'absent', _utc_now(),
                 turn_key, lease_owner, time.time()),
            )
            if updated.rowcount != 1:
                raise StaleSnapshotError('context resolution lost its worker lease')

    def get_turn(self, turn_key: str):
        with self.connection() as conn:
            row = conn.execute("SELECT * FROM turns WHERE turn_key=?", (turn_key,)).fetchone()
            return dict(row) if row else None

    def claim_turn(self, turn_key: str, lease_seconds: int = 900):
        """Claim a pending turn for one worker, reclaiming stale workers."""
        now_epoch = time.time()
        owner = f"worker-{os.getpid()}-{uuid.uuid4().hex}"
        with self.connection() as conn:
            conn.execute("BEGIN IMMEDIATE")
            row = conn.execute(
                "SELECT status, lease_expires_at FROM turns WHERE turn_key=?",
                (turn_key,),
            ).fetchone()
            if not row:
                conn.execute("ROLLBACK")
                return None
            status = row["status"]
            if status in {
                "committed", "projected", "noop", "needs_user", "clarified",
                "dismissed", "rejected", "failed",
            }:
                conn.execute("COMMIT")
                return None
            lease_expires_at = row["lease_expires_at"]
            if status == "resolving" and lease_expires_at and float(lease_expires_at) > now_epoch:
                conn.execute("COMMIT")
                return None
            conn.execute(
                """
                UPDATE turns
                SET status='resolving', lease_owner=?, lease_expires_at=?,
                    attempt_count=attempt_count+1, updated_at=?
                WHERE turn_key=?
                """,
                (owner, now_epoch + max(30, lease_seconds), _utc_now(), turn_key),
            )
            conn.execute("COMMIT")
            return owner

    def renew_lease(self, turn_key: str, lease_owner: str, lease_seconds: int = 900) -> bool:
        """Extend a live lease only; never revive an expired/reassigned worker."""
        now = time.time()
        with self.connection(timeout_seconds=5) as conn:
            updated = conn.execute(
                "UPDATE turns SET lease_expires_at=? WHERE turn_key=? "
                "AND status='resolving' AND lease_owner=? AND lease_expires_at>?",
                (now + max(30, lease_seconds), turn_key, lease_owner, now),
            )
            return updated.rowcount == 1

    def pending_turn_keys(self, limit: int = 20, forced_only: bool = False):
        with self.connection() as conn:
            rows = conn.execute(
                f"""
                SELECT turn_key FROM turns
                WHERE status IN ('pending', 'resolving')
                {"AND forced=1" if forced_only else ""}
                ORDER BY created_at
                LIMIT ?
                """,
                (max(1, int(limit)),),
            ).fetchall()
            return [row["turn_key"] for row in rows]

    def failed_turn_keys(self, limit: int = 20):
        with self.connection() as conn:
            rows = conn.execute(
                """
                SELECT turn_key FROM turns
                WHERE status='failed'
                ORDER BY updated_at DESC
                LIMIT ?
                """,
                (max(1, int(limit)),),
            ).fetchall()
            return [row["turn_key"] for row in rows]

    def rejected_turns(self, limit: int = 20):
        limit = max(1, int(limit))
        with self.connection() as conn:
            rows = conn.execute(
                """
                SELECT turn_key, status, result_json, created_at
                FROM turns
                WHERE status='rejected' OR result_json LIKE '%"REJECT"%'
                ORDER BY created_at DESC
                LIMIT ?
                """,
                (max(100, limit * 4),),
            ).fetchall()
        result = []

        def rejected_mutations(mutations):
            rejected = []
            for mutation in mutations or []:
                if not isinstance(mutation, dict):
                    continue
                if str(mutation.get("operation", "")).upper() == "REJECT":
                    rejected.append(mutation)
                rejected.extend(rejected_mutations(mutation.get("children")))
            return rejected

        for row in rows:
            parsed = {}
            try:
                parsed = json.loads(row["result_json"] or "{}")
            except (TypeError, json.JSONDecodeError):
                pass
            rejected = rejected_mutations(parsed.get("mutations", []))
            if not rejected:
                continue
            result.append(
                {
                    "turn_key": row["turn_key"],
                    "status": row["status"],
                    "mutations": rejected,
                    "created_at": row["created_at"],
                }
            )
            if len(result) >= limit:
                break
        return result

    def needs_user_turns(self, limit: int = 20, exclude_turn_key: str = ""):
        with self.connection() as conn:
            rows = conn.execute(
                """
                SELECT turn_key, source_text, result_json, created_at
                FROM turns
                WHERE status='needs_user' AND turn_key != ?
                ORDER BY created_at
                LIMIT ?
                """,
                (exclude_turn_key, max(1, int(limit))),
            ).fetchall()
        result = []
        for row in rows:
            parsed = {}
            try:
                parsed = json.loads(row["result_json"] or "{}")
            except (TypeError, json.JSONDecodeError):
                pass
            result.append(
                {
                    "turn_key": row["turn_key"],
                    "source_text": str(row["source_text"] or "")[:500],
                    "reason": _safe_scalar(parsed.get("reason", "")),
                    "created_at": row["created_at"],
                }
            )
        return result

    def turn_has_transaction(self, turn_key: str) -> bool:
        """True when any committed transaction row exists for this turn."""
        with self.connection() as conn:
            row = conn.execute(
                "SELECT 1 FROM transactions WHERE turn_key=? LIMIT 1",
                (turn_key,),
            ).fetchone()
        return bool(row)

    def mark_clarifications_resolved(
        self,
        turn_keys: list[str],
        resolved_by: str,
    ) -> list[str]:
        unique = list(dict.fromkeys(str(item).strip() for item in turn_keys if str(item).strip()))
        if not unique:
            return []
        resolved = []
        with self.connection() as conn:
            conn.execute("BEGIN IMMEDIATE")
            for turn_key in unique:
                row = conn.execute(
                    "SELECT result_json FROM turns WHERE turn_key=? AND status='needs_user'",
                    (turn_key,),
                ).fetchone()
                if not row:
                    continue
                try:
                    result = json.loads(row["result_json"] or "{}")
                except (TypeError, json.JSONDecodeError):
                    result = {}
                result["status"] = "clarified"
                result["resolved_by"] = resolved_by
                conn.execute(
                    """
                    UPDATE turns
                    SET status='clarified', result_json=?, updated_at=?
                    WHERE turn_key=? AND status='needs_user'
                    """,
                    (_json(result), _utc_now(), turn_key),
                )
                resolved.append(turn_key)
            conn.execute("COMMIT")
        return resolved

    def dismiss_clarification(self, turn_key: str) -> dict:
        with self.connection() as conn:
            conn.execute("BEGIN IMMEDIATE")
            row = conn.execute(
                "SELECT result_json FROM turns WHERE turn_key=? AND status='needs_user'",
                (turn_key,),
            ).fetchone()
            if not row:
                conn.execute("ROLLBACK")
                raise MemoryStoreError(
                    f"turn is not an unresolved clarification: {turn_key}"
                )
            try:
                result = json.loads(row["result_json"] or "{}")
            except (TypeError, json.JSONDecodeError):
                result = {}
            result["status"] = "dismissed"
            result["turn_key"] = turn_key
            conn.execute(
                """
                UPDATE turns
                SET status='dismissed', result_json=?, updated_at=?
                WHERE turn_key=? AND status='needs_user'
                """,
                (_json(result), _utc_now(), turn_key),
            )
            conn.execute("COMMIT")
        return result

    def retry_delay_seconds(self) -> int:
        with self.connection() as conn:
            row = conn.execute(
                """
                SELECT COALESCE(MAX(attempt_count), 0) AS attempts
                FROM turns
                WHERE status IN ('pending', 'resolving')
                """
            ).fetchone()
        attempts = int(row["attempts"]) if row else 0
        return min(900, 15 * (2 ** min(attempts, 6)))

    def mark_turn_error(
        self,
        turn_key: str,
        error: str,
        lease_owner: str = "",
        max_attempts: int = 5,
        charge_attempt: bool = True,
        learning_recovery=None,
    ) -> str:
        """Record a turn failure.

        With a lease_owner, claim_turn already charged this attempt, so only the
        owner's row is updated and the count is left alone. Without a lease,
        pass charge_attempt=False when the failure follows a claim made inside
        the same logical attempt (e.g. drain catching a resolve_turn exception)
        — otherwise one real failure is charged twice and the turn reaches
        `failed` after roughly half the intended retries.
        """
        if learning_recovery is not None and (
                not isinstance(learning_recovery,tuple) or len(learning_recovery)!=2 or
                type(learning_recovery[0]) is not int or learning_recovery[0]<0 or
                type(learning_recovery[1]) not in {int,float} or not 0<=learning_recovery[1]<=60):
            raise MemoryStoreError('bounded learning recovery and original generation required')
        with self.connection() as conn:
            conn.execute('BEGIN IMMEDIATE')
            row = conn.execute(
                "SELECT attempt_count FROM turns WHERE turn_key=?",
                (turn_key,),
            ).fetchone()
            attempts = int(row["attempt_count"]) if row else 0
            if not lease_owner and charge_attempt:
                attempts += 1
            next_status = "failed" if attempts >= max(1, int(max_attempts)) else "pending"
            if lease_owner:
                updated = conn.execute(
                    """
                    UPDATE turns
                    SET status=?, lease_owner=NULL, lease_expires_at=NULL,
                        last_error=?, updated_at=?
                    WHERE turn_key=? AND status='resolving' AND lease_owner=?
                    """,
                    (
                        next_status,
                        _safe_scalar(error)[:1000],
                        _utc_now(),
                        turn_key,
                        lease_owner,
                    ),
                )
            else:
                # Never stomp another worker's live lease: a 'resolving' row is
                # only reset when its lease has already expired (or is absent).
                updated = conn.execute(
                    f"""
                    UPDATE turns
                    SET status=?, lease_owner=NULL, lease_expires_at=NULL,
                        attempt_count=attempt_count+{1 if charge_attempt else 0},
                        last_error=?, updated_at=?
                    WHERE turn_key=? AND status NOT IN (
                        'committed','projected','noop','needs_user','clarified',
                        'dismissed','rejected','failed'
                    ) AND (
                        status != 'resolving'
                        OR lease_expires_at IS NULL
                        OR lease_expires_at < ?
                    )
                    """,
                    (
                        next_status,
                        _safe_scalar(error)[:1000],
                        _utc_now(),
                        turn_key,
                        time.time(),
                    ),
                )
            if updated.rowcount==1 and next_status=='failed' and learning_recovery is not None:
                conn.execute('CREATE TABLE IF NOT EXISTS learning_recovery ('
                    'turn_key TEXT PRIMARY KEY, generation INTEGER NOT NULL, '
                    'not_before REAL NOT NULL, epoch INTEGER NOT NULL DEFAULT 0 CHECK(epoch IN (0,1)))')
                # An exhausted recovery must never get a second recovery epoch.
                conn.execute('INSERT OR IGNORE INTO learning_recovery VALUES (?,?,?,0)',
                    (turn_key,learning_recovery[0],time.time()+learning_recovery[1]))
            conn.execute('COMMIT')
        return next_status

    def learning_recovery(self, turn_key=None):
        """Read recovery receipts without migrating existing/frozen libraries."""
        with self.connection() as conn:
            if not conn.execute("SELECT 1 FROM sqlite_master WHERE type='table' AND name='learning_recovery'").fetchone():
                return None if turn_key is not None else []
            if turn_key is not None:
                row=conn.execute('SELECT * FROM learning_recovery WHERE turn_key=?',(turn_key,)).fetchone()
                return dict(row) if row else None
            return [dict(row) for row in conn.execute(
                "SELECT r.* FROM learning_recovery r JOIN turns t USING(turn_key) "
                "WHERE (r.epoch=0 AND t.status='failed') OR "
                "(r.epoch=1 AND t.status IN ('pending','resolving')) ORDER BY t.created_at,t.rowid")]

    def resume_failed_learning(self, turn_key, *, namespace):
        """Consume one recovery epoch; never reorder past a newer memory commit."""
        if (self.memory_dir/'frozen.json').exists():
            raise MemoryStoreError('frozen memory cannot recover learning')
        with self.connection() as conn:
            conn.execute('BEGIN IMMEDIATE')
            owner=conn.execute("SELECT value FROM meta WHERE key='memory_namespace'").fetchone()
            if not namespace or owner is None or owner['value']!=namespace:
                raise MemoryStoreError('learning recovery belongs to another namespace')
            if not conn.execute("SELECT 1 FROM sqlite_master WHERE type='table' AND name='learning_recovery'").fetchone():
                return False
            receipt=conn.execute('SELECT * FROM learning_recovery WHERE turn_key=?',(turn_key,)).fetchone()
            generation=int(conn.execute("SELECT value FROM meta WHERE key='generation'").fetchone()['value'])
            if (not receipt or receipt['epoch']!=0 or receipt['generation']!=generation or
                    receipt['not_before']>time.time()):
                return False
            updated=conn.execute("UPDATE turns SET status='pending',updated_at=? WHERE turn_key=? AND status='failed'",
                                 (_utc_now(),turn_key))
            if updated.rowcount!=1:
                return False
            conn.execute('UPDATE learning_recovery SET epoch=1 WHERE turn_key=?',(turn_key,))
            conn.execute('COMMIT')
            return True

    def mark_needs_user(self, turn_key: str, plan: dict, lease_owner: str = "") -> dict:
        result = {
            "status": "needs_user",
            "turn_key": turn_key,
            "reason": _safe_scalar(plan.get("reason", "semantic decision needs user input")),
            "plan": plan,
        }
        with self.connection() as conn:
            conn.execute("BEGIN IMMEDIATE")
            sql = """
                UPDATE turns
                SET status='needs_user', lease_owner=NULL, lease_expires_at=NULL,
                    plan_json=?, result_json=?, updated_at=?
                WHERE turn_key=?
            """
            params = [_json(plan), _json(result), _utc_now(), turn_key]
            if lease_owner:
                sql += " AND status='resolving' AND lease_owner=?"
                params.append(lease_owner)
            updated = conn.execute(sql, tuple(params))
            if updated.rowcount != 1:
                conn.execute("ROLLBACK")
                raise StaleSnapshotError("worker lease no longer owns the turn")
            conn.execute("COMMIT")
        return result

    def _active_record(self, conn, atomic_id: str):
        row = conn.execute(
            """
            SELECT r.*, v.name, v.description, v.condition, v.confidence,
                   v.rule_text, v.applies_when, v.does_not_apply_when,
                   v.body, v.source_text, v.extra_json, v.content_hash
            FROM rules r
            JOIN rule_versions v
              ON v.atomic_id=r.atomic_id AND v.revision=r.current_revision
            WHERE r.atomic_id=? AND r.status='active' AND r.superseded_by IS NULL
            """,
            (atomic_id,),
        ).fetchone()
        return self._record_from_row(row) if row else None

    def _allocate_atomic_id(self, conn, domain: str, rule_type: str) -> str:
        domain_key = DOMAIN_ABBREVIATIONS.get(domain, "oth")
        type_key = TYPE_ABBREVIATIONS.get(rule_type, "ref")
        prefix = f"{domain_key}-{type_key}"
        row = conn.execute("SELECT next_value FROM id_counters WHERE prefix=?", (prefix,)).fetchone()
        if row:
            value = int(row["next_value"])
        else:
            maximum = 0
            pattern = re.compile(rf"^{re.escape(prefix)}-(\d+)$")
            for existing in conn.execute("SELECT atomic_id FROM rules").fetchall():
                match = pattern.match(existing["atomic_id"])
                if match:
                    maximum = max(maximum, int(match.group(1)))
            value = maximum + 1
        while True:
            atomic_id = f"{prefix}-{value:03d}"
            exists = conn.execute("SELECT 1 FROM rules WHERE atomic_id=?", (atomic_id,)).fetchone()
            if not exists:
                break
            value += 1
        conn.execute(
            """
            INSERT OR REPLACE INTO id_counters(prefix, next_value) VALUES(?, ?)
            """,
            (prefix, value + 1),
        )
        return atomic_id

    def _normalize_record(self, record: dict, base=None) -> dict:
        if not isinstance(record, dict):
            raise InvalidPlanError("record must be an object")
        base = base or {}
        out = {}
        for field in RECORD_FIELDS:
            if field in {"scope", "scope_anchor"}:
                continue
            incoming = record[field] if field in record else base.get(field, "")
            if incoming is None:
                incoming = ""
            out[field] = _safe_scalar(incoming) if field != "body" else str(incoming or "").strip()
        if "scope" in record:
            out["scope"] = _safe_scalar(record.get("scope", ""))
            out["scope_anchor"] = _safe_scalar(record.get("scope_anchor", ""))
        elif "scope_anchor" in record:
            out["scope"] = _safe_scalar(base.get("scope", ""))
            out["scope_anchor"] = _safe_scalar(record.get("scope_anchor", ""))
        else:
            out["scope"] = _safe_scalar(base.get("scope", ""))
            out["scope_anchor"] = _safe_scalar(base.get("scope_anchor", ""))
        out["type"] = out["type"] or "preference"
        out["domain"] = out["domain"] or "other"
        out["scope"] = out["scope"] or "global"
        legacy_anchor = ""
        if out["scope"].startswith("project:"):
            legacy_anchor = out["scope"][len("project:"):].strip()
            out["scope"] = "project"
        if legacy_anchor:
            if out["scope_anchor"] and out["scope_anchor"] != legacy_anchor:
                raise InvalidPlanError(
                    "record.scope_anchor conflicts with legacy project:<name> scope"
                )
            out["scope_anchor"] = legacy_anchor
        out["confidence"] = out["confidence"] or "medium"
        out["rule_text"] = out["rule_text"] or out["description"]
        out["description"] = out["description"] or out["rule_text"]
        out["name"] = out["name"] or re.sub(r"[^A-Za-z0-9_-]+", "-", out["description"].lower())[:60].strip("-")
        out["applies_when"] = out["applies_when"] or out["condition"]
        out["does_not_apply_when"] = out["does_not_apply_when"] or "(none)"
        if not out["rule_text"]:
            raise InvalidPlanError("record.rule_text is required")
        if out["domain"] not in DOMAIN_ABBREVIATIONS:
            raise InvalidPlanError(f"unsupported record.domain: {out['domain']}")
        if out["type"] not in TYPE_ABBREVIATIONS:
            raise InvalidPlanError(f"unsupported record.type: {out['type']}")
        if out["confidence"] not in VALID_CONFIDENCE:
            raise InvalidPlanError(f"unsupported record.confidence: {out['confidence']}")
        if out["scope"] not in VALID_SCOPES:
            raise InvalidPlanError(
                "record.scope must be global, project, task, or unclear"
            )
        if out["scope"] in {"project", "task"} and not out["scope_anchor"]:
            raise InvalidPlanError(
                f"record.scope_anchor is required for {out['scope']} scope"
            )
        if out["scope"] == "global" and out["scope_anchor"]:
            raise InvalidPlanError(
                "record.scope_anchor must be empty for global scope"
            )
        if out["scope"] == "unclear" and out["scope_anchor"]:
            raise InvalidPlanError(
                "record.scope_anchor must be empty for unclear scope"
            )
        reserved = set(RECORD_FIELDS) | {
            "schema_version",
            "atomic_id",
            "status",
            "revision",
            "supersedes",
            "superseded_by",
            "created",
            "updated",
            "content_sha256",
            "content_hash",
            "priority_tier",
        }
        extra = {}
        if isinstance(base.get("extra"), dict):
            extra.update(
                {
                    key: value
                    for key, value in base["extra"].items()
                    if isinstance(key, str)
                    and VALID_EXTRA_KEY.fullmatch(key)
                    and key not in reserved
                }
            )
        if isinstance(record.get("extra"), dict):
            extra.update(
                {
                    key: value
                    for key, value in record["extra"].items()
                    if isinstance(key, str)
                    and VALID_EXTRA_KEY.fullmatch(key)
                    and key not in reserved
                }
            )
        out["extra"] = extra
        return out

    def _insert_rule(self, conn, atomic_id: str, record: dict, source_text: str) -> None:
        now = _today()
        conn.execute(
            """
            INSERT INTO rules(
                atomic_id, type, domain, scope, scope_anchor, status, current_revision,
                superseded_by, created_at, updated_at
            ) VALUES(?, ?, ?, ?, ?, 'active', 1, NULL, ?, ?)
            """,
            (
                atomic_id,
                record["type"],
                record["domain"],
                record["scope"],
                record["scope_anchor"],
                now,
                now,
            ),
        )
        self._insert_version(conn, atomic_id, 1, record, source_text, now)

    def _insert_version(
        self,
        conn,
        atomic_id: str,
        revision: int,
        record: dict,
        source_text: str,
        created_at: str,
    ) -> None:
        material = {field: record.get(field, "") for field in RECORD_FIELDS}
        material["extra"] = record.get("extra", {})
        content_hash = _sha256(_json(material))
        conn.execute(
            """
            INSERT INTO rule_versions(
                atomic_id, revision, name, description, condition, confidence,
                rule_text, applies_when, does_not_apply_when, body, source_text,
                extra_json, content_hash, created_at
            ) VALUES(?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
            """,
            (
                atomic_id,
                revision,
                record["name"],
                record["description"],
                record["condition"],
                record["confidence"],
                record["rule_text"],
                record["applies_when"],
                record["does_not_apply_when"],
                record["body"],
                source_text,
                _json(record.get("extra", {})),
                content_hash,
                created_at,
            ),
        )

    def _retire_rule(self, conn, old_id: str, new_id: str, relation: str, turn_key: str) -> None:
        if old_id == new_id:
            raise InvalidPlanError("a rule cannot supersede itself")
        updated = conn.execute(
            """
            UPDATE rules
            SET status='superseded', superseded_by=?, updated_at=?
            WHERE atomic_id=? AND status='active' AND superseded_by IS NULL
            """,
            (new_id, _today(), old_id),
        )
        if updated.rowcount != 1:
            raise InvalidPlanError(f"target rule is not active: {old_id}")
        conn.execute(
            """
            INSERT OR IGNORE INTO rule_relations(from_id, to_id, relation, turn_key, created_at)
            VALUES(?, ?, ?, ?, ?)
            """,
            (old_id, new_id, relation, turn_key, _utc_now()),
        )

    def _validate_mutation(
        self,
        conn,
        mutation: dict,
        label: str,
        claimed_targets: set[str],
        allowed_operations: set[str],
        source_text: str,
        extra_sources: list[str] | None = None,
    ):
        evidence_sources = [source_text] + [s for s in (extra_sources or []) if s]
        if not isinstance(mutation, dict):
            raise InvalidPlanError(f"{label} must be an object")
        operation = str(mutation.get("operation", "")).upper()
        if operation not in allowed_operations:
            raise InvalidPlanError(f"unsupported operation: {operation}")
        target_ids = mutation.get("target_ids") or []
        if not isinstance(target_ids, list) or not all(
            isinstance(item, str) for item in target_ids
        ):
            raise InvalidPlanError(f"{label}.target_ids must be string list")
        if len(target_ids) != len(set(target_ids)):
            raise InvalidPlanError(f"{label} repeats a target")
        overlap = claimed_targets.intersection(target_ids)
        if overlap:
            raise InvalidPlanError(
                f"target appears in multiple mutations: {sorted(overlap)}"
            )
        claimed_targets.update(target_ids)
        if operation in {
            "UPDATE", "SUPERSEDE", "ARCHIVE", "RESTORE",
        } and not target_ids:
            raise InvalidPlanError(f"{operation} requires target_ids")
        if operation == "NOOP" and not target_ids:
            raise InvalidPlanError(
                "NOOP must identify the active rule that entails the turn"
            )
        if operation in {"NEW", "SPLIT", "REJECT", "NEEDS_USER"} and target_ids:
            raise InvalidPlanError(f"{operation} cannot target an existing rule")
        target_revisions = {}
        for atomic_id in target_ids:
            if not VALID_ATOMIC_ID.match(atomic_id):
                raise InvalidPlanError(f"invalid target atomic_id: {atomic_id}")
            row = conn.execute(
                "SELECT status, current_revision FROM rules WHERE atomic_id=?",
                (atomic_id,),
            ).fetchone()
            if operation == "ARCHIVE":
                if not row or row["status"] != "active":
                    raise InvalidPlanError(
                        f"target rule cannot be archived (not active): {atomic_id}"
                    )
            elif operation == "RESTORE":
                if not row or row["status"] != "archived":
                    raise InvalidPlanError(
                        f"target rule cannot be restored (not archived): {atomic_id}"
                    )
            elif operation in {"NOOP", "UPDATE", "SUPERSEDE"} and (
                not row or row["status"] != "active"
            ):
                raise InvalidPlanError(f"target rule is not active: {atomic_id}")
            if row:
                target_revisions[atomic_id] = int(row["current_revision"])
        record = mutation.get("record") or {}
        if not isinstance(record, dict):
            raise InvalidPlanError(f"{operation} requires a record object")
        children = mutation.get("children") or []
        if not isinstance(children, list):
            raise InvalidPlanError(f"{label}.children must be a list")
        if operation == "SPLIT":
            if record:
                raise InvalidPlanError("SPLIT parent record must be empty")
            if len(children) < 2:
                raise InvalidPlanError("SPLIT requires at least two children")
            normalized_children = [
                self._validate_mutation(
                    conn,
                    child,
                    f"{label}.children[{child_index}]",
                    claimed_targets,
                    SPLIT_CHILD_OPERATIONS,
                    source_text,
                    extra_sources,
                )
                for child_index, child in enumerate(children)
            ]
        else:
            if children:
                raise InvalidPlanError(
                    f"{label}.children must be empty for {operation}"
                )
            normalized_children = []
        if operation in {
            "NOOP", "NEEDS_USER", "REJECT", "ARCHIVE", "RESTORE",
        } and record:
            raise InvalidPlanError(f"{operation} record must be empty")
        evidence_spans = mutation.get("evidence_spans")
        if not isinstance(evidence_spans, list) or not all(
            isinstance(span, str) and span.strip() for span in evidence_spans
        ):
            raise InvalidPlanError(f"{label}.evidence_spans must be a string list")
        evidence_spans = list(
            dict.fromkeys(
                _normalize_quote_against_sources(span, evidence_sources)
                for span in evidence_spans
            )
        )
        if len(evidence_spans) > 8:
            raise InvalidPlanError(
                f"{label}.evidence_spans may contain at most 8 quotes"
            )
        for span in evidence_spans:
            if len(span) > 500 or not any(
                span in source for source in evidence_sources
            ):
                raise InvalidPlanError(
                    f"{label}.evidence_spans must be short exact quotes from the "
                    "user turn or a clarification turn resolved by this plan"
                )
        if operation not in {"NEEDS_USER", "SPLIT"} and not evidence_spans:
            raise InvalidPlanError(f"{operation} requires user-turn evidence")

        def normalized_exception(value) -> str:
            text = str(value or "").strip()
            return (
                ""
                if text.casefold() in {"", "none", "(none)", "[]", "[ ]"}
                else text
            )

        applicability_evidence = str(
            mutation.get("applicability_evidence", "")
        ).strip()
        if not applicability_evidence.startswith("existing:"):
            applicability_evidence = _normalize_quote_against_sources(
                applicability_evidence,
                evidence_sources,
            )
        has_boundary = bool(
            str(record.get("applies_when", "")).strip()
            or str(record.get("condition", "")).strip()
            or normalized_exception(record.get("does_not_apply_when", ""))
        )
        if operation in {
            "NOOP", "SPLIT", "NEEDS_USER", "REJECT", "ARCHIVE", "RESTORE",
        }:
            applicability_evidence = ""
        elif not has_boundary:
            boundary_fields_present = any(
                field in record
                for field in (
                    "condition",
                    "applies_when",
                    "does_not_apply_when",
                )
            )
            preserves_omitted_boundary = (
                operation == "UPDATE"
                and not boundary_fields_present
                and target_ids
                and applicability_evidence == f"existing:{target_ids[0]}"
            )
            if not preserves_omitted_boundary:
                existing_had_boundary = False
                for atomic_id in target_ids:
                    existing = self._active_record(conn, atomic_id)
                    existing_had_boundary = existing_had_boundary or bool(
                        str(existing.get("applies_when", "")).strip()
                        or str(existing.get("condition", "")).strip()
                        or normalized_exception(
                            existing.get("does_not_apply_when", "")
                        )
                    )
                if existing_had_boundary:
                    if not applicability_evidence or not any(
                        applicability_evidence in source
                        for source in evidence_sources
                    ):
                        raise InvalidPlanError(
                            f"{label}.applicability_evidence must quote the user "
                            "removing the existing applicability boundary"
                        )
                elif applicability_evidence:
                    raise InvalidPlanError(
                        f"{label}.applicability_evidence must be empty without "
                        "an applicability boundary"
                    )
        elif applicability_evidence.startswith("existing:"):
            existing_id = applicability_evidence.split(":", 1)[1].strip()
            if (
                operation != "UPDATE"
                or not target_ids
                or existing_id != target_ids[0]
            ):
                raise InvalidPlanError(
                    f"{label}.applicability_evidence may cite only the primary "
                    "rule on its UPDATE"
                )
            existing = self._active_record(conn, existing_id)
            for field in (
                "condition",
                "applies_when",
                "does_not_apply_when",
            ):
                if field not in record:
                    continue
                incoming = str(record.get(field, "")).strip()
                current = str(existing.get(field, "")).strip()
                if field == "does_not_apply_when":
                    incoming = normalized_exception(incoming)
                    current = normalized_exception(current)
                if incoming != current:
                    raise InvalidPlanError(
                        f"{label}.{field} changed and requires exact "
                        "user-turn evidence"
                    )
        elif not applicability_evidence or not any(
            applicability_evidence in source for source in evidence_sources
        ):
            raise InvalidPlanError(
                f"{label}.applicability_evidence must be an exact quote from the "
                "user turn or a clarification turn resolved by this plan"
            )
        return {
            "operation": operation,
            "target_ids": target_ids,
            "target_revisions": target_revisions,
            "record": record,
            "evidence_spans": evidence_spans,
            "applicability_evidence": applicability_evidence[:1000],
            "children": normalized_children,
            "reason": _safe_scalar(mutation.get("reason", "")),
            "reason_code": _safe_scalar(mutation.get("reason_code", "")),
        }

    def _validate_plan(self, conn, plan: dict, source_text: str):
        mutations = plan.get("mutations")
        if not isinstance(mutations, list):
            raise InvalidPlanError("plan.mutations must be a list")
        namespaced = bool(conn.execute("SELECT 1 FROM meta WHERE key='memory_namespace'").fetchone())
        if namespaced and plan.get('resolved_turn_keys'):
            raise InvalidPlanError('experimental learning cannot import another turn as authorization')
        # Evidence may additionally quote the original text of a clarification
        # turn this plan resolves (mirrors the judge-side contract). The extra
        # corpus is limited to registered needs_user turns actually listed in
        # resolved_turn_keys — both texts are genuine stored user turns, so the
        # trusted-source anti-forgery property holds.
        extra_sources = []
        for key in plan.get("resolved_turn_keys") or []:
            if not isinstance(key, str) or not key.strip():
                continue
            row = conn.execute(
                "SELECT source_text FROM turns WHERE turn_key=? AND status='needs_user'",
                (key.strip(),),
            ).fetchone()
            if row and row["source_text"]:
                extra_sources.append(row["source_text"])
        claimed_targets = set()
        normalized = []
        for index, mutation in enumerate(mutations):
            normalized.append(
                self._validate_mutation(
                    conn,
                    mutation,
                    f"mutation {index}",
                    claimed_targets,
                    VALID_OPERATIONS,
                    source_text,
                    extra_sources,
                )
            )

        def collect_operations(items):
            operations = set()
            for item in items:
                operations.add(item["operation"])
                operations.update(collect_operations(item.get("children", [])))
            return operations

        operations = collect_operations(normalized)
        if {"REJECT", "NEEDS_USER"}.issubset(operations):
            raise InvalidPlanError("REJECT and NEEDS_USER cannot appear in one plan")
        if namespaced:
            try:
                learning_policy.validate_types({'mutations': normalized}, learning_policy.CORRECTIONS)
            except ValueError as exc:
                raise InvalidPlanError(str(exc)) from exc
        return normalized

    def commit_plan(
        self,
        turn_key: str,
        source_text: str,
        plan: dict,
        expected_generation: int,
        lease_owner: str = "",
        pending_plan: dict | None = None,
        resolve_pending_by: str = '',
    ) -> dict:
        now = _utc_now()
        txn_id = f"txn-{time.strftime('%Y%m%dT%H%M%SZ', time.gmtime())}-{uuid.uuid4().hex[:12]}"
        with self.connection() as conn:
            conn.execute("BEGIN IMMEDIATE")
            generation_row = conn.execute("SELECT value FROM meta WHERE key='generation'").fetchone()
            generation = int(generation_row["value"]) if generation_row else 0
            if generation != expected_generation:
                conn.execute("ROLLBACK")
                raise StaleSnapshotError(
                    f"memory changed while judging: expected generation {expected_generation}, got {generation}"
                )
            turn = conn.execute(
                "SELECT status, result_json, source_text FROM turns WHERE turn_key=?",
                (turn_key,),
            ).fetchone()
            if not turn:
                conn.execute("ROLLBACK")
                raise MemoryStoreError("turn must be registered before commit")
            if source_text != turn["source_text"]:
                conn.execute("ROLLBACK")
                raise InvalidPlanError(
                    "commit source_text does not match the registered trusted turn"
                )
            source_text = turn["source_text"]
            replay_pending = bool(resolve_pending_by) and turn['status'] == 'needs_user'
            if turn["status"] in {
                "committed", "projected", "noop", "needs_user", "rejected", "clarified", "dismissed", "failed",
            } and not replay_pending:
                conn.execute("COMMIT")
                return json.loads(turn["result_json"]) if turn["result_json"] else {
                    "status": turn["status"],
                    "turn_key": turn_key,
                }
            if resolve_pending_by and not replay_pending:
                raise InvalidPlanError('only a parked clarification can be replayed')
            if lease_owner:
                ownership = conn.execute(
                    """
                    SELECT 1 FROM turns
                    WHERE turn_key=? AND status='resolving' AND lease_owner=?
                      AND lease_expires_at>?
                    """,
                    (turn_key, lease_owner, time.time()),
                ).fetchone()
                if not ownership:
                    conn.execute("ROLLBACK")
                    raise StaleSnapshotError("worker lease no longer owns the turn")
            normalized = self._validate_plan(conn, plan, source_text)
            if pending_plan is not None:
                pending_normalized = self._validate_plan(conn, pending_plan, source_text)
                if not pending_normalized or any(item['operation'] != 'NEEDS_USER' for item in pending_normalized):
                    raise InvalidPlanError('pending_plan must contain only unresolved requirements')
            if any(item["operation"] == "NEEDS_USER" for item in normalized):
                conn.execute("ROLLBACK")
                return self.mark_needs_user(turn_key, plan, lease_owner=lease_owner)
            committed_plan = dict(plan)
            committed_plan["mutations"] = normalized

            conn.execute(
                """
                INSERT INTO transactions(
                    txn_id, turn_key, status, base_generation, plan_json, created_at
                ) VALUES(?, ?, 'applying', ?, ?, ?)
                """,
                (txn_id, turn_key, generation, _json(committed_plan), now),
            )
            results = []
            changed = False
            def apply_mutation(mutation):
                operation = mutation["operation"]
                target_ids = mutation["target_ids"]
                if operation == "NOOP":
                    return (
                        {
                            "operation": operation,
                            "atomic_id": target_ids[0] if target_ids else "",
                            "reason": mutation["reason"],
                        },
                        False,
                    )
                if operation == "REJECT":
                    return (
                        {
                            "operation": operation,
                            "reason": mutation["reason"],
                            "reason_code": mutation["reason_code"] or "unsafe_rule",
                        },
                        False,
                    )
                if operation == "ARCHIVE":
                    archived_ids = []
                    already_archived_ids = []
                    for atomic_id in target_ids:
                        updated = conn.execute(
                            """
                            UPDATE rules
                            SET status='archived', superseded_by=NULL, updated_at=?
                            WHERE atomic_id=? AND status='active'
                            """,
                            (_today(), atomic_id),
                        )
                        if updated.rowcount:
                            archived_ids.append(atomic_id)
                        else:
                            already_archived_ids.append(atomic_id)
                    return (
                        {
                            "operation": operation,
                            "archived_ids": archived_ids,
                            "already_archived_ids": already_archived_ids,
                            "reason": mutation["reason"],
                        },
                        bool(archived_ids),
                    )
                if operation == "RESTORE":
                    restored_ids = []
                    already_active_ids = []
                    for atomic_id in target_ids:
                        updated = conn.execute(
                            """
                            UPDATE rules
                            SET status='active', superseded_by=NULL, updated_at=?
                            WHERE atomic_id=? AND status='archived'
                            """,
                            (_today(), atomic_id),
                        )
                        if updated.rowcount:
                            restored_ids.append(atomic_id)
                        else:
                            already_active_ids.append(atomic_id)
                    return (
                        {
                            "operation": operation,
                            "restored_ids": restored_ids,
                            "already_active_ids": already_active_ids,
                            "reason": mutation["reason"],
                        },
                        bool(restored_ids),
                    )
                if operation == "NEW":
                    record = self._normalize_record(mutation["record"])
                    atomic_id = self._allocate_atomic_id(conn, record["domain"], record["type"])
                    self._insert_rule(conn, atomic_id, record, source_text)
                    return {"operation": operation, "atomic_id": atomic_id}, True
                if operation == "UPDATE":
                    primary_id = target_ids[0]
                    primary = self._active_record(conn, primary_id)
                    record = self._normalize_record(mutation["record"], primary)
                    revision = int(primary["revision"]) + 1
                    self._insert_version(conn, primary_id, revision, record, source_text, _utc_now())
                    conn.execute(
                        """
                        UPDATE rules
                        SET type=?, domain=?, scope=?, scope_anchor=?,
                            current_revision=?, updated_at=?
                        WHERE atomic_id=?
                        """,
                        (
                            record["type"],
                            record["domain"],
                            record["scope"],
                            record["scope_anchor"],
                            revision,
                            _today(),
                            primary_id,
                        ),
                    )
                    for old_id in target_ids[1:]:
                        self._retire_rule(conn, old_id, primary_id, "consolidated_into", turn_key)
                    return (
                        {
                            "operation": operation,
                            "atomic_id": primary_id,
                            "revision": revision,
                            "consolidated_ids": target_ids[1:],
                        },
                        True,
                    )
                if operation == "SUPERSEDE":
                    record = self._normalize_record(mutation["record"])
                    new_id = self._allocate_atomic_id(conn, record["domain"], record["type"])
                    self._insert_rule(conn, new_id, record, source_text)
                    for old_id in target_ids:
                        self._retire_rule(conn, old_id, new_id, "superseded_by", turn_key)
                    return (
                        {
                            "operation": operation,
                            "atomic_id": new_id,
                            "superseded_ids": target_ids,
                        },
                        True,
                    )
                raise InvalidPlanError(f"unsupported executable operation: {operation}")

            for mutation in normalized:
                if mutation["operation"] == "SPLIT":
                    child_results = []
                    split_changed = False
                    for child in mutation["children"]:
                        child_result, child_changed = apply_mutation(child)
                        child_results.append(child_result)
                        split_changed = split_changed or child_changed
                    results.append(
                        {
                            "operation": "SPLIT",
                            "children": child_results,
                            "reason": mutation["reason"],
                        }
                    )
                    changed = changed or split_changed
                    continue
                mutation_result, mutation_changed = apply_mutation(mutation)
                results.append(mutation_result)
                changed = changed or mutation_changed

            new_generation = generation + 1 if changed else generation
            if changed:
                conn.execute(
                    "UPDATE meta SET value=? WHERE key='generation'",
                    (str(new_generation),),
                )
            has_reject = any(
                item["operation"] == "REJECT"
                or (
                    item["operation"] == "SPLIT"
                    and any(
                        child["operation"] == "REJECT"
                        for child in item["children"]
                    )
                )
                for item in normalized
            )
            status = "committed" if changed else ("rejected" if has_reject else "noop")
            result = {
                "status": status,
                "turn_key": turn_key,
                "txn_id": txn_id,
                "generation": new_generation,
                "mutations": results,
            }
            transaction_status = "rejected" if status == "rejected" else "committed"
            conn.execute(
                """
                UPDATE transactions
                SET status=?, result_json=?, committed_at=?,
                    committed_generation=?
                WHERE txn_id=?
                """,
                (
                    transaction_status,
                    _json(result),
                    _utc_now(),
                    new_generation,
                    txn_id,
                ),
            )
            turn_status, turn_plan, turn_result = status, committed_plan, result
            if pending_plan is not None:
                turn_status = 'needs_user'
                turn_plan = dict(pending_plan)
                turn_result = {'status': 'needs_user', 'turn_key': turn_key,
                               'reason': _safe_scalar(pending_plan.get('reason', 'unresolved requirement')),
                               'plan': turn_plan, 'committed': result}
            elif resolve_pending_by:
                turn_status = 'clarified'
                turn_result = {'status': 'clarified', 'turn_key': turn_key,
                               'resolved_by': resolve_pending_by, 'committed': result}
            conn.execute(
                """
                UPDATE turns
                SET status=?, lease_owner=NULL, lease_expires_at=NULL,
                    plan_json=?, result_json=?, last_error=NULL, updated_at=?
                WHERE turn_key=?
                """,
                (
                    turn_status,
                    _json(turn_plan),
                    _json(turn_result),
                    _utc_now(),
                    turn_key,
                ),
            )
            conn.execute("COMMIT")
        return turn_result

    def _relations_for_projection(self, conn):
        supersedes = {}
        for row in conn.execute(
            "SELECT from_id, to_id FROM rule_relations WHERE relation IN ('superseded_by','consolidated_into')"
        ).fetchall():
            supersedes.setdefault(row["to_id"], []).append(row["from_id"])
        for value in supersedes.values():
            value.sort()
        return supersedes

    def project(self) -> dict:
        """Rebuild all Markdown/JSON projections from committed SQLite state."""
        with self.connection() as conn:
            conn.execute("BEGIN IMMEDIATE")
            try:
                generation_row = conn.execute(
                    "SELECT value FROM meta WHERE key='generation'"
                ).fetchone()
                generation = int(generation_row["value"]) if generation_row else 0
                records = self._current_records(conn, active_only=False)
                supersedes = self._relations_for_projection(conn)
                projected_records = [
                    record for record in records if record["status"] != "archived"
                ]
                active = [
                    record
                    for record in projected_records
                    if record["status"] == "active" and not record["superseded_by"]
                ]

                written = []
                for record in projected_records:
                    frontmatter = {
                        "schema_version": "tellonce-memory-v2",
                        "atomic_id": record["atomic_id"],
                        "name": record["name"],
                        "description": record["description"],
                        "type": record["type"],
                        "domain": record["domain"],
                        "scope": record["scope"],
                        "scope_anchor": record["scope_anchor"],
                        "condition": record["condition"],
                        "confidence": record["confidence"],
                        "status": record["status"],
                        "revision": record["revision"],
                        "rule_text": record["rule_text"],
                        "applies_when": record["applies_when"],
                        "does_not_apply_when": record["does_not_apply_when"],
                        "supersedes": supersedes.get(record["atomic_id"], []),
                        "superseded_by": record["superseded_by"],
                        "created": record["created"],
                        "updated": record["updated"],
                    }
                    frontmatter.update(
                        {
                            key: value
                            for key, value in (record.get("extra") or {}).items()
                            if isinstance(key, str)
                            and VALID_EXTRA_KEY.fullmatch(key)
                            and key not in set(RECORD_FIELDS)
                            and key not in frontmatter
                            and key not in {"content_hash", "content_sha256"}
                            and key != "priority_tier"
                        }
                    )
                    without_hash = _render_frontmatter(frontmatter, record["body"])
                    frontmatter["content_sha256"] = _sha256(without_hash)
                    content = _render_frontmatter(frontmatter, record["body"])
                    target = self.memory_dir / f"{record['atomic_id']}.md"
                    _atomic_write(target, content)
                    written.append(str(target))

                projected_ids = {
                    record["atomic_id"] for record in projected_records
                }
                for stale_path in self.memory_dir.glob("*.md"):
                    if stale_path.name == "MEMORY.md":
                        continue
                    if not VALID_ATOMIC_ID.fullmatch(stale_path.stem):
                        continue
                    if stale_path.stem not in projected_ids:
                        try:
                            stale_data, _stale_body = parse_frontmatter(
                                stale_path.read_text(encoding="utf-8-sig")
                            )
                        except (OSError, UnicodeError, ValueError):
                            continue
                        if (
                            stale_data.get("schema_version") == "tellonce-memory-v2"
                            and stale_data.get("atomic_id") == stale_path.stem
                        ):
                            stale_path.unlink()

                grouped = {}
                for record in active:
                    grouped.setdefault(record["domain"], []).append(record)
                index_lines = ["# Memory", ""]
                ordered_domains = list(DOMAIN_ABBREVIATIONS)
                for domain in ordered_domains:
                    items = sorted(
                        grouped.get(domain, []),
                        key=lambda item: (item["type"], item["atomic_id"]),
                    )
                    if not items:
                        continue
                    index_lines.extend(
                        [f"## {DOMAIN_HEADINGS.get(domain, domain.title())}", ""]
                    )
                    for item in items:
                        description = _safe_scalar(
                            item["description"] or item["rule_text"]
                        )[:150]
                        index_lines.append(
                            f"- [{item['atomic_id']}]({item['atomic_id']}.md) — {description}"
                        )
                    index_lines.append("")
                _atomic_write(
                    self.memory_dir / "MEMORY.md",
                    "\n".join(index_lines).rstrip() + "\n",
                )

                active_index = {
                    "schema_version": SCHEMA_VERSION,
                    "generation": generation,
                    "active": [
                        {
                            "atomic_id": item["atomic_id"],
                            "revision": item["revision"],
                            "type": item["type"],
                            "domain": item["domain"],
                            "scope": item["scope"],
                            "scope_anchor": item["scope_anchor"],
                            "description": item["description"],
                            "rule_text": item["rule_text"],
                            "condition": item["condition"],
                            "confidence": item["confidence"],
                            "applies_when": item["applies_when"],
                            "does_not_apply_when": item["does_not_apply_when"],
                            "content_hash": item["content_hash"],
                        }
                        for item in active
                    ],
                }
                _atomic_write(
                    self.memory_dir / ACTIVE_INDEX_FILENAME,
                    json.dumps(active_index, ensure_ascii=False, indent=2) + "\n",
                )

                now = _utc_now()
                projected_turns = [
                    row["turn_key"]
                    for row in conn.execute(
                        """
                        SELECT turn_key FROM transactions
                        WHERE status='committed'
                          AND committed_generation IS NOT NULL
                          AND committed_generation<=?
                        """,
                        (generation,),
                    ).fetchall()
                ]
                conn.execute(
                    """
                    UPDATE transactions
                    SET status='projected', projected_at=?
                    WHERE status='committed'
                      AND committed_generation IS NOT NULL
                      AND committed_generation<=?
                    """,
                    (now, generation),
                )
                for turn_key in projected_turns:
                    conn.execute(
                        """
                        UPDATE turns
                        SET status='projected', updated_at=?
                        WHERE turn_key=? AND status='committed'
                        """,
                        (now, turn_key),
                    )
                conn.execute(
                    "UPDATE meta SET value='0' WHERE key='projection_required'"
                )
                conn.execute("COMMIT")
            except Exception:
                conn.execute("ROLLBACK")
                raise
        return {
            "status": "projected",
            "generation": active_index["generation"],
            "active_count": len(active),
            "files_written": written,
        }

    def projection_pending(self) -> bool:
        with self.connection() as conn:
            return bool(
                conn.execute(
                    "SELECT 1 FROM transactions WHERE status='committed' LIMIT 1"
                ).fetchone()
                or conn.execute(
                    "SELECT 1 FROM meta "
                    "WHERE key='projection_required' AND value='1'"
                ).fetchone()
            )

    def recover(self) -> dict:
        """SQLite commits are atomic; recovery only needs to rebuild projections."""
        self.initialize()
        return self.project()

    def _legacy_record(self, data: dict, body: str) -> dict:
        known = set(RECORD_FIELDS) | {
            "schema_version",
            "atomic_id",
            "status",
            "revision",
            "supersedes",
            "superseded_by",
            "created",
            "updated",
            "content_sha256",
            "canonical_key",
            "source_event_ids",
            "priority_tier",
        }
        extra = {key: value for key, value in data.items() if key not in known}
        legacy_type = str(data.get("type", "preference")).strip()
        legacy_domain = str(data.get("domain", "other")).strip()
        legacy_confidence = str(data.get("confidence", "medium")).strip()
        legacy_scope = str(data.get("scope", "global")).strip()
        legacy_scope_anchor = str(data.get("scope_anchor", "")).strip()
        if legacy_type not in TYPE_ABBREVIATIONS:
            legacy_type = "preference"
        if legacy_domain not in DOMAIN_ABBREVIATIONS:
            legacy_domain = "other"
        if legacy_confidence not in VALID_CONFIDENCE:
            legacy_confidence = "medium"
        if legacy_scope == "project":
            project_name = (
                self.memory_dir.parent.parent.name
                if self.memory_dir.parent.name == ".tellonce"
                else "legacy"
            )
            legacy_scope_anchor = legacy_scope_anchor or project_name
        elif legacy_scope.startswith("project:"):
            legacy_scope_anchor = (
                legacy_scope_anchor
                or legacy_scope[len("project:"):].strip()
            )
            legacy_scope = "project"
        elif legacy_scope == "task":
            if not legacy_scope_anchor:
                legacy_scope = "global"
        elif legacy_scope == "global":
            legacy_scope_anchor = ""
        elif legacy_scope not in VALID_SCOPES:
            legacy_scope = "global"
            legacy_scope_anchor = ""
        record = {
            "name": data.get("name", ""),
            "description": data.get("description") or data.get("rule_text", ""),
            "type": legacy_type,
            "domain": legacy_domain,
            "scope": legacy_scope,
            "scope_anchor": legacy_scope_anchor,
            "condition": data.get("condition", ""),
            "confidence": legacy_confidence,
            "rule_text": data.get("rule_text") or data.get("description", ""),
            "applies_when": data.get("applies_when") or data.get("condition", ""),
            "does_not_apply_when": data.get("does_not_apply_when", "(none)"),
            "body": body.strip(),
            "extra": extra,
        }
        return self._normalize_record(record)

    def _import_legacy_if_empty(self) -> bool:
        with self.connection() as conn:
            if conn.execute("SELECT 1 FROM meta WHERE key='memory_namespace'").fetchone():
                return False
            if conn.execute("SELECT 1 FROM rules LIMIT 1").fetchone():
                return False
        candidates = {}
        source_dirs = [self.memory_dir, *self.legacy_dirs]
        invalid_paths = []
        for source_rank, source_dir in enumerate(source_dirs):
            if not source_dir.is_dir():
                continue
            for path in sorted(source_dir.glob("*.md")):
                if path.name == "MEMORY.md" or path.name.startswith("_archived_"):
                    continue
                source_text = ""
                try:
                    source_text = path.read_text(
                        encoding="utf-8-sig",
                        errors="replace",
                    )
                    data, body = parse_frontmatter(source_text)
                except Exception as exc:
                    # Refuse only for files that are evidently rules: a broken
                    # frontmatter fence or a rule filename prefix. Any other
                    # unparsable file (an index, a note) is skipped; matching
                    # every filename against the atomic-id pattern made such
                    # files refuse the whole import.
                    likely_rule = (
                        path.name.startswith(
                            (
                                "pref_", "pit_", "fric_", "usr_", "proj_",
                                "ref_", "feedback_",
                            )
                        )
                        or source_text.lstrip("\ufeff").startswith("---")
                    )
                    if likely_rule:
                        invalid_paths.append(
                            f"{path}: {type(exc).__name__}: {exc}"
                        )
                    else:
                        print(
                            f"tellonce: legacy import skipped non-rule file {path}",
                            file=sys.stderr,
                        )
                    continue
                atomic_id = str(data.get("atomic_id", "")).strip()
                if not VALID_ATOMIC_ID.match(atomic_id):
                    continue
                revision_raw = data.get("revision", 0)
                try:
                    revision = int(revision_raw)
                except (TypeError, ValueError):
                    revision = 0
                priority = (
                    revision,
                    1 if path.name == f"{atomic_id}.md" else 0,
                    -source_rank,
                )
                fingerprint = _sha256(_json(data) + "\n" + body)
                candidate_key = atomic_id
                prior = candidates.get(candidate_key)
                if prior is not None and prior[1] != fingerprint:
                    candidate_key = f"{atomic_id}#{fingerprint}"
                    prior = candidates.get(candidate_key)
                if prior is None or priority > prior[0]:
                    candidates[candidate_key] = (
                        priority,
                        fingerprint,
                        atomic_id,
                        data,
                        body,
                        str(path),
                    )
        if invalid_paths:
            raise MemoryStoreError(
                "legacy memory migration refused unreadable rule files: "
                + "; ".join(invalid_paths[:10])
            )
        if not candidates:
            return False
        with self.connection() as conn:
            conn.execute("BEGIN IMMEDIATE")
            if conn.execute("SELECT 1 FROM rules LIMIT 1").fetchone():
                conn.execute("ROLLBACK")
                return False
            now = _utc_now()
            pending_relations = []
            for _candidate_key, (
                _priority,
                _fingerprint,
                legacy_atomic_id,
                data,
                body,
                source_path,
            ) in sorted(candidates.items()):
                try:
                    record = self._legacy_record(data, body)
                except InvalidPlanError as exc:
                    raise MemoryStoreError(
                        "legacy memory migration refused invalid rule file: "
                        f"{source_path}: {exc}"
                    ) from exc
                atomic_id = legacy_atomic_id
                if conn.execute(
                    "SELECT 1 FROM rules WHERE atomic_id=?",
                    (atomic_id,),
                ).fetchone():
                    record["extra"]["legacy_atomic_id"] = legacy_atomic_id
                    record["extra"]["legacy_source_path"] = source_path
                    atomic_id = self._allocate_atomic_id(
                        conn,
                        record["domain"],
                        record["type"],
                    )
                created = _safe_scalar(data.get("created", "")) or _today()
                updated = _safe_scalar(data.get("updated", "")) or created
                superseded_by = _safe_scalar(data.get("superseded_by", ""))
                status = _safe_scalar(data.get("status", ""))
                if status not in {"active", "superseded", "archived"}:
                    status = "superseded" if superseded_by else "active"
                conn.execute(
                    """
                    INSERT INTO rules(
                        atomic_id, type, domain, scope, scope_anchor, status, current_revision,
                        superseded_by, created_at, updated_at
                    ) VALUES(?, ?, ?, ?, ?, ?, 1, ?, ?, ?)
                    """,
                    (
                        atomic_id,
                        record["type"],
                        record["domain"],
                        record["scope"],
                        record["scope_anchor"],
                        status,
                        superseded_by or None,
                        created,
                        updated,
                    ),
                )
                self._insert_version(conn, atomic_id, 1, record, "legacy import", now)
                supersedes = data.get("supersedes") or []
                if isinstance(supersedes, str):
                    supersedes = [supersedes]
                for old_id in supersedes:
                    if isinstance(old_id, str) and VALID_ATOMIC_ID.match(old_id):
                        pending_relations.append((old_id, atomic_id, "superseded_by"))
                if superseded_by and VALID_ATOMIC_ID.match(superseded_by):
                    pending_relations.append((atomic_id, superseded_by, "superseded_by"))
            for old_id, new_id, relation in pending_relations:
                conn.execute(
                    """
                    INSERT OR IGNORE INTO rule_relations(from_id, to_id, relation, turn_key, created_at)
                    VALUES(?, ?, ?, 'legacy-import', ?)
                    """,
                    (old_id, new_id, relation, now),
                )
            conn.execute("UPDATE meta SET value='1' WHERE key='generation'")
            conn.execute("COMMIT")
        return True
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 323kUpdated Claude CodeCodexVerifiedInstall