YujunZhou/tellonce / codex
tellonce
VerifiedUse 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.
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |