@agentikos/omega-os 0.1.0 → 0.19.5

package/omega/Agentik_Engine/omega_engine/skill_routing.py

@@ -0,0 +1,388 @@
+"""Role → skills routing.
+
+Why this module exists
+----------------------
+
+OmegaOS ships 24 first-party skills (17 audits + dispatch + pursue + cadence
++ skill-finder/auditor + rag-route). Anthropic's catalog grows weekly. A
+worker spawned with EVERY skill available has its context bloated with
+descriptions it'll never use — and Claude gets confused about which to
+reach for.
+
+The right shape: each role declares the skills it should reach for, and the
+``WorkerBrief.skills`` field becomes the authoritative tool palette. The
+worker's system prompt enumerates those skills + a "use them when
+applicable" instruction so Claude actually engages them.
+
+Topology overrides this per-mission (e.g. a "frontend-fix" mission gives
+the worker only `pursue` + `uiuxaudit` + `a11yaudit`, while a "data-migration"
+mission gives it `pursue` + `dataaudit` + `apiaudit`).
+
+Resolution order (highest wins)
+-------------------------------
+
+  1. Explicit ``brief.skills`` (operator passed --skills)
+  2. Topology declares ``mission_skills`` for the role
+  3. ``_ROLE_SKILLS`` map below (sensible defaults per role)
+  4. Empty list → Claude uses whatever's globally installed
+
+Public API
+----------
+
+  ``skills_for(role, ...)`` returns the resolved list.
+  ``recommend(role)`` returns the role-default for `omega skill recommend`.
+  ``catalog_for_home(home)`` returns every skill id present in the SSOT.
+  ``format_skill_block(skills, home)`` builds the system_prompt snippet
+  embedded by ``spawn_worker``.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+# ---------------------------------------------------------------------------
+# Role → default skills
+# ---------------------------------------------------------------------------
+#
+# Curated. Not "every skill" — only the ones that role actually benefits from.
+# Each entry is a comment + a list because future maintainers should be able
+# to see the WHY of every line.
+
+_ROLE_SKILLS: dict[str, list[str]] = {
+    # ---------------------------------------------------------------------
+    # Dispatchers — they plan + delegate. They orchestrate but never code.
+    # ``dispatch`` lets them spawn sub-missions; ``pursue`` lets them run
+    # a goal-driven loop directly when planning isn't worth it. ``cadence``
+    # lets them schedule recurring beats. They have the FULL audit catalog
+    # in scope so they can RECOMMEND audits when assigning work.
+    # ---------------------------------------------------------------------
+    "oracle": [
+        "dispatch", "pursue", "cadence",
+        "codeaudit", "debugaudit", "uiuxaudit", "secaudit",
+        "perfaudit", "a11yaudit", "flowaudit", "featureaudit",
+    ],
+    "manager": [
+        "dispatch", "pursue",
+        "codeaudit", "debugaudit", "secaudit", "perfaudit",
+    ],
+    "aisb": [
+        "dispatch", "pursue", "cadence",
+        "codeaudit", "debugaudit", "uiuxaudit", "secaudit",
+    ],
+    "architect": [
+        "dispatch", "pursue",
+        "codeaudit", "logicaudit", "apiaudit", "dataaudit",
+        "secaudit", "perfaudit",
+    ],
+
+    # ---------------------------------------------------------------------
+    # Executors — they DO the work. They get the full audit palette so
+    # they can self-verify BEFORE claiming done (a worker that runs
+    # /codeaudit on its own changes catches its own mistakes — verified
+    # completion shifts left). ``pursue`` is the goal-driven loop.
+    # ---------------------------------------------------------------------
+    "worker": [
+        "pursue",
+        # Core code / runtime
+        "codeaudit", "debugaudit", "logicaudit",
+        # UI / UX (most common worker domain)
+        "uiuxaudit", "a11yaudit", "flowaudit", "motionaudit", "copyaudit",
+        # Cross-cutting checks
+        "perfaudit", "secaudit", "seoaudit",
+    ],
+    "construct": [
+        "pursue",
+        # Build / data / API specialist
+        "codeaudit", "apiaudit", "dataaudit", "logicaudit",
+        "perfaudit", "secaudit", "dxaudit",
+    ],
+    "link": [
+        "pursue",
+        # Integration / external systems
+        "apiaudit", "secaudit", "automationaudit",
+    ],
+
+    # ---------------------------------------------------------------------
+    # Verifiers — read-only; they audit. The bigger the palette, the
+    # harder it is for a worker to hide a regression. Seraph is the
+    # senior verifier — it gets EVERY audit.
+    # ---------------------------------------------------------------------
+    "audit": [
+        "codeaudit", "debugaudit", "secaudit",
+        "perfaudit", "a11yaudit",
+    ],
+    "verifier": [
+        "codeaudit", "debugaudit", "logicaudit",
+    ],
+    "seraph": [
+        "codeaudit", "debugaudit", "uiuxaudit", "secaudit",
+        "perfaudit", "a11yaudit", "seoaudit", "apiaudit", "dataaudit",
+        "flowaudit", "featureaudit", "logicaudit",
+    ],
+
+    # ---------------------------------------------------------------------
+    # Triage / classifier — minimal tool surface. Haiku model, fast pass.
+    # ---------------------------------------------------------------------
+    "classifier": [],
+    "triage":     [],
+
+    # ---------------------------------------------------------------------
+    # Special meta-roles
+    # ---------------------------------------------------------------------
+    "skill_curator":  ["skill-finder", "skill-auditor"],
+    "smith":          [        # Reflection / learning — reads audits
+        "codeaudit", "debugaudit", "retentionaudit",
+    ],
+
+    # ---------------------------------------------------------------------
+    # Domain-specialist worker roles. Operators dispatch to these when a
+    # mission has an obvious primary domain. Each gets pursue + the
+    # domain audit + the 2-3 most relevant cross-cutters.
+    # ---------------------------------------------------------------------
+    "worker_ui":      [
+        "pursue",
+        # Audits — UI domain
+        "uiuxaudit", "a11yaudit", "motionaudit", "copyaudit", "refontaudit",
+        # Design-discipline skills (Genesis writes these into feature briefs;
+        # workers MUST invoke them, not paraphrase them)
+        "shadcn-ui", "emil-design-eng", "impeccable", "taste-skill",
+        "frontend-design", "design-taste-frontend",
+    ],
+    "worker_perf":    ["pursue", "perfaudit", "codeaudit", "debugaudit", "logicaudit"],
+    "worker_sec":     ["pursue", "secaudit", "codeaudit", "apiaudit", "dataaudit"],
+    "worker_api":     ["pursue", "apiaudit", "codeaudit", "dataaudit", "secaudit"],
+    "worker_data":    ["pursue", "dataaudit", "codeaudit", "apiaudit", "secaudit"],
+    "worker_seo":     ["pursue", "seoaudit", "perfaudit", "a11yaudit", "copyaudit"],
+    "worker_ops":     ["pursue", "automationaudit", "dxaudit", "secaudit"],
+    "worker_growth":  ["pursue", "retentionaudit", "featureaudit", "copyaudit"],
+}
+
+
+# Skills the engine treats as "power tools" — operators should know they
+# exist. Surfaced by `omega skill recommend` and the post-install card.
+POWER_SKILLS: list[str] = [
+    "dispatch",      # multi-agent orchestration
+    "pursue",        # goal-driven loop
+    "cadence",       # scheduled / recurring beats
+    "codeaudit",     # is the code SOLID
+    "debugaudit",    # what's broken right now
+    "uiuxaudit",     # is the UI beautiful
+    "secaudit",      # is it secure
+    "perfaudit",     # is it fast
+    "a11yaudit",     # is it accessible
+    "seoaudit",      # is it discoverable
+]
+
+
+# ---------------------------------------------------------------------------
+# Canonical skill-chain workflows.
+#
+# Each entry is a multi-line string describing how skills compose into a
+# complete workflow. ``omega skill workflows`` surfaces these so operators
+# can SEE how /dispatch → /pursue → /codeaudit → fix-workers → re-audit
+# actually chains together at runtime.
+#
+# The content is informative — Claude reads these via the skill block when
+# the role's palette includes the relevant primitives. They are NOT executed
+# as code; they're the canonical playbook.
+# ---------------------------------------------------------------------------
+
+WORKFLOWS: dict[str, str] = {
+    "ship-feature": """\
+Build + verify a feature, end-to-end, with no API-key burn.
+
+  1.  Operator runs:  /dispatch "implement OAuth login with verify against tests/auth.test.ts"
+  2.  /dispatch  →  Oracle plans 3 worker subtasks:
+                      a. add the auth endpoint (worker, with /codeaudit + /apiaudit + /secaudit)
+                      b. update the client form    (worker, with /uiuxaudit + /a11yaudit + /flowaudit)
+                      c. add the playwright test   (worker, with /codeaudit + /flowaudit)
+  3.  Each worker runs /pursue <verify_cmd> until exit 0.
+  4.  Seraph runs /codeaudit + /debugaudit + /secaudit on each .done.json.
+  5.  Mission completes only when EVERY child is VERIFIED (not just CLAIMED_DONE).
+  6.  Smith reflection (autonomous, daily) reads the audit history and writes Insight
+       proposals to Agentik_Extra/staging/promotion/ if anything was weak.
+
+Skills in chain:  /dispatch  →  /pursue  →  /codeaudit  →  fix workers  →  /codeaudit (re-audit)
+""",
+
+    "self-audit-loop": """\
+A worker AUDITS ITS OWN CHANGES before claiming done — verified completion
+shifts left, catching mistakes one layer earlier.
+
+  1.  Worker reads brief, makes the change.
+  2.  BEFORE writing .done.json, worker runs /codeaudit --files=<changed>
+        - If score >= 85 → write done_clean
+        - If score <  85 → fix the findings (loop), then re-audit
+        - Hard cap: 3 iterations, then write `pending` with the unresolved findings
+  3.  Seraph (verifier) re-runs the audit independently.
+        - If Seraph also passes → VERIFIED
+        - If Seraph fails what the worker thought it passed → REJECTED + retry budget
+  4.  Verified completion is now SOLID — two independent passes had to agree.
+
+Skills in chain:  /pursue  →  /codeaudit (self)  →  /codeaudit (verifier)
+""",
+
+    "ux-redesign": """\
+Multi-domain UX redesign with parallel specialised workers.
+
+  1.  Operator:  /refontaudit --url=https://app/dashboard
+                   → produces a redesign plan with /100 score per pillar
+  2.  /dispatch "execute the refontaudit plan; preserve existing functionality"
+       → Oracle spawns 4 worker_ui's in parallel, file ownership disjoint:
+           a. layout shell             (worker_ui  + /uiuxaudit)
+           b. component primitives     (worker_ui  + /a11yaudit)
+           c. motion + transitions     (worker_ui  + /motionaudit)
+           d. copy + microcopy         (worker_ui  + /copyaudit)
+  3.  Each worker /pursue <playwright-screenshot-diff> until 0 visual regressions.
+  4.  Seraph runs FULL audit pass (12 audits) on the final state.
+  5.  Mission verified only if every audit >= threshold.
+
+Skills in chain:  /refontaudit  →  /dispatch  →  4× /pursue + /uiuxaudit/a11yaudit/motionaudit/copyaudit
+""",
+
+    "linear-fix-batch": """\
+Fix N Linear tickets in parallel-safe batches (the v0.10 pattern).
+
+  1.  Operator:  /dispatch "fix all 36 Linear feedback tickets in this project"
+  2.  Oracle calls linear-conflict-analyzer.py → annotates each ticket with
+       files_touched + conflict_class (narrow | broad | terminal).
+  3.  Oracle greedy-packs up to 4 NARROW tickets with disjoint file footprints
+       into one batch; BROAD tickets run alone.
+  4.  Per ticket, worker runs:
+        - Playwright BEFORE capture (visual + console baseline)
+        - implement fix
+        - Playwright AFTER capture
+        - /codeaudit --files=<changed>  (self-audit)
+        - write .done.json with Before/After paths
+  5.  Seraph runs /debugaudit on each ticket  →  VERIFIED or REJECTED.
+  6.  After each batch, `npm run build` once.
+  7.  Next batch dispatches; repeat until queue empty.
+
+Skills in chain:  /dispatch  →  /pursue per ticket  →  /codeaudit  →  /debugaudit
+""",
+
+    "scheduled-quality": """\
+Continuously running quality watch via cron + /cadence.
+
+  1.  Operator:  /cadence schedule cron "0 3 * * *" \\
+                   "run the full forensic audit suite on $project, write the report,
+                    create Linear tickets for findings >= high severity"
+  2.  Every night at 03:00, autonomous-supervisor fires the charter.
+  3.  Engine dispatches a verifier with the full audit palette (12 audits).
+  4.  Failing audits → Insight files in Agentik_Extra/staging/promotion/.
+  5.  Smith reflection (also daily) reads the trend → proposes which audits
+       to dispatch fix-workers for first.
+
+Skills in chain:  /cadence  →  daily cron  →  /dispatch verifier  →  12 audits  →  Smith insight
+""",
+}
+
+
+def recommend(role: str) -> list[str]:
+    """Default skill list for a role. Empty list if the role is unknown."""
+    return list(_ROLE_SKILLS.get(role, []))
+
+
+def skills_for(
+    role: str,
+    *,
+    explicit: list[str] | None = None,
+    topology_skills: list[str] | None = None,
+) -> list[str]:
+    """Resolve the final skill list for a worker (precedence order documented above)."""
+    if explicit:
+        return list(explicit)
+    if topology_skills:
+        return list(topology_skills)
+    return recommend(role)
+
+
+def catalog_for_home(home: str | Path) -> list[str]:
+    """Every skill id present under ``$OMEGA_HOME/Agentik_SSOT/skills/``."""
+    root = Path(home) / "Agentik_SSOT" / "skills"
+    if not root.is_dir():
+        return []
+    out: list[str] = []
+    for child in sorted(root.iterdir()):
+        if child.is_dir() and (child / "SKILL.md").exists():
+            out.append(child.name)
+        elif child.is_file() and child.suffix == ".md":
+            out.append(child.stem)
+    return out
+
+
+def format_skill_block(
+    skills: list[str], home: str | Path | None = None,
+) -> str:
+    """Build the system_prompt snippet that tells the worker which skills it
+    should reach for. Empty list → empty string (worker uses ambient skills).
+
+    Output shape:
+
+        ## Skills available
+
+        You have these OmegaOS skills available — invoke them as slash
+        commands when applicable:
+
+          /pursue <verify-cmd> <intent>       — goal-driven loop
+          /codeaudit --files=...              — forensic code audit
+          ...
+
+        Prefer these over ad-hoc Bash whenever they fit. Do not paraphrase
+        an audit protocol into raw prompts.
+    """
+    if not skills:
+        return ""
+
+    # Build short descriptions from the SSOT SKILL.md if available; otherwise
+    # we just list the names.
+    descs: dict[str, str] = {}
+    if home is not None:
+        root = Path(home) / "Agentik_SSOT" / "skills"
+        for s in skills:
+            md = root / s / "SKILL.md"
+            if not md.is_file():
+                md = root / f"{s}.md"
+            if md.is_file():
+                d = _extract_description(md)
+                if d:
+                    descs[s] = d
+
+    lines = ["", "## Skills available", ""]
+    lines.append(
+        "You have these OmegaOS skills available — invoke them as slash"
+    )
+    lines.append("commands when applicable:")
+    lines.append("")
+    for s in skills:
+        desc = descs.get(s, "")
+        if desc:
+            # Truncate to one line for compactness.
+            desc_line = desc.replace("\n", " ").strip()
+            if len(desc_line) > 110:
+                desc_line = desc_line[:107] + "..."
+            lines.append(f"  /{s}  — {desc_line}")
+        else:
+            lines.append(f"  /{s}")
+    lines.append("")
+    lines.append(
+        "Prefer these over ad-hoc Bash whenever they fit. Do not paraphrase"
+    )
+    lines.append("an audit protocol into raw prompts — invoke the slash command.")
+    return "\n".join(lines)
+
+
+def _extract_description(skill_md: Path) -> str:
+    """Pull the `description:` field from a SKILL.md frontmatter."""
+    try:
+        text = skill_md.read_text()
+    except OSError:
+        return ""
+    if not text.startswith("---"):
+        return ""
+    # Manual minimal YAML — avoid the PyYAML dep on this hot path.
+    body = text.split("---", 2)[1] if text.count("---") >= 2 else ""
+    for line in body.splitlines():
+        if line.startswith("description:"):
+            return line.split(":", 1)[1].strip().strip('"').strip("'")
+    return ""

package/omega/Agentik_Engine/omega_engine/smoke.py

@@ -0,0 +1,81 @@
+"""`omega smoke` — 30-second post-install end-to-end check.
+
+Runs a synthetic mission against the live engine using the deterministic
+MockProvider. The mission is intentionally tiny: one Oracle, one Worker,
+one Verifier. Pass = events flow + .done.json written + audit gate
+returned VERIFIED. Fail = something in the orchestration stack is
+broken and the operator's first real mission would too.
+
+Exit code 0 on smoke pass, 1 on fail. Designed for CI / cron / install
+post-step.
+"""
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class SmokeResult:
+    passed: bool
+    elapsed_ms: int
+    mission_id: str = ""
+    final_state: str = ""
+    events_recorded: int = 0
+    done_files_written: int = 0
+    detail: str = ""
+
+
+def run_smoke(*, omega_home: str | Path | None = None) -> SmokeResult:
+    """One synthetic mission. Always uses MockProvider — no API keys needed.
+
+    The goal is "the orchestration stack itself works", not "your API
+    keys are valid" (that's ``omega validate providers``).
+    """
+    home = Path(omega_home or os.environ.get("OMEGA_HOME")
+                or Path.home() / "Omega")
+    start = time.time()
+    try:
+        from omega_engine.audit import AuditGate
+        from omega_engine.bus import EventBus
+        from omega_engine.executor import Executor
+        from omega_engine.provider import MockProvider
+        from omega_engine.router import ModelRouter
+        from omega_engine.store import SQLiteStore
+
+        store_path = home / "Agentik_Runtime" / "eventlog" / "omega.db"
+        store_path.parent.mkdir(parents=True, exist_ok=True)
+        store = SQLiteStore(store_path)
+        bus = EventBus(store)
+        router = ModelRouter.single(MockProvider())
+        executor = Executor(store, bus, router, AuditGate(),
+                            partial_policy="accept_partial")
+        outcome = executor.run_mission(
+            "OmegaOS smoke test — synthetic mission, no real work expected",
+            root_role="oracle",
+        )
+        events = store.events_for(outcome.root.id)
+        # how many .done.json files landed in the per-task session dirs
+        sess = home / "Agentik_Runtime" / "sessions"
+        done = sum(1 for p in sess.rglob(".done.json")) if sess.is_dir() else 0
+        store.close()
+
+        return SmokeResult(
+            passed=outcome.verified,
+            elapsed_ms=int((time.time() - start) * 1000),
+            mission_id=outcome.mission_id,
+            final_state=outcome.final_state.value,
+            events_recorded=len(events),
+            done_files_written=done,
+            detail=("orchestration stack healthy" if outcome.verified
+                    else f"mission ended {outcome.final_state.value}"),
+        )
+    except Exception as exc:  # noqa: BLE001
+        return SmokeResult(
+            passed=False,
+            elapsed_ms=int((time.time() - start) * 1000),
+            detail=f"smoke crashed: {exc}"[:300],
+        )

package/omega/Agentik_Engine/omega_engine/store.py

@@ -47,51 +47,158 @@ CREATE TABLE IF NOT EXISTS events (
 );
 CREATE INDEX IF NOT EXISTS idx_events_task ON events(task_id, ts, id);
 CREATE INDEX IF NOT EXISTS idx_events_ts   ON events(ts, id);
+
+-- Snapshots: bounded reduction time on a growing log. A snapshot captures the
+-- reduced state of a task at a given event rowid; later reductions can start
+-- from the snapshot instead of replaying from genesis.
+CREATE TABLE IF NOT EXISTS snapshots (
+    task_id          TEXT NOT NULL,
+    state            TEXT NOT NULL,
+    ts               REAL NOT NULL,
+    last_event_rowid INTEGER NOT NULL,
+    PRIMARY KEY (task_id, ts)
+);
+CREATE INDEX IF NOT EXISTS idx_snapshots_task ON snapshots(task_id, ts DESC);
 """
 
 
 class SQLiteStore(EventStore):
-    """Append-only event log on SQLite (WAL). The default store for a VPS."""
+    """Append-only event log on SQLite (WAL). The default store for a VPS.
+
+    Thread-safety
+    -------------
+    The connection is opened with ``check_same_thread=False`` AND every
+    write is serialized through ``self._lock``. Background services
+    (AutonomousSupervisor, Telegram bot, webhook daemon) all share one
+    store from different threads — without this, the first cross-thread
+    call raises ``sqlite3.ProgrammingError`` and the supervisor dies.
+
+    Bug history: pre-v0.13 the lock was missing and a 5-thread fuzz
+    raised 5/5 ProgrammingErrors. Test: tests/test_store_concurrency.py.
+    """
 
     def __init__(self, db_path: str | Path):
+        import threading
         self.db_path = str(db_path)
         Path(self.db_path).parent.mkdir(parents=True, exist_ok=True)
-        self._conn = sqlite3.connect(self.db_path, isolation_level=None)
+        # check_same_thread=False: we serialise via self._lock so the
+        # connection can be safely shared across threads.
+        self._conn = sqlite3.connect(
+            self.db_path, isolation_level=None, check_same_thread=False,
+        )
         self._conn.row_factory = sqlite3.Row
         self._conn.execute("PRAGMA journal_mode=WAL;")
         self._conn.execute("PRAGMA synchronous=NORMAL;")
         self._conn.executescript(_SCHEMA)
+        self._lock = threading.Lock()
+
+    def close(self) -> None:
+        """Explicitly close the SQLite connection (best-effort)."""
+        try:
+            with self._lock:
+                self._conn.close()
+        except (sqlite3.Error, AttributeError):
+            pass
+
+    def __del__(self) -> None:
+        # Best-effort cleanup — Python may have already torn things down.
+        try:
+            self.close()
+        except Exception:  # noqa: BLE001
+            pass
 
     def append(self, event: Event) -> None:
-        self._conn.execute(
-            "INSERT INTO events (id, task_id, type, ts, payload) "
-            "VALUES (:id, :task_id, :type, :ts, :payload)",
-            event.to_row(),
-        )
+        with self._lock:
+            self._conn.execute(
+                "INSERT INTO events (id, task_id, type, ts, payload) "
+                "VALUES (:id, :task_id, :type, :ts, :payload)",
+                event.to_row(),
+            )
 
     def events_for(self, task_id: str) -> list[Event]:
         # ORDER BY rowid = insertion order — the only correct order for a reducer.
         # Ordering by `ts` is unsafe: rapid emits can share a timestamp.
-        cur = self._conn.execute(
-            "SELECT * FROM events WHERE task_id = ? ORDER BY rowid", (task_id,)
-        )
-        return [Event.from_row(dict(r)) for r in cur.fetchall()]
+        with self._lock:
+            cur = self._conn.execute(
+                "SELECT * FROM events WHERE task_id = ? ORDER BY rowid",
+                (task_id,),
+            )
+            rows = cur.fetchall()
+        return [Event.from_row(dict(r)) for r in rows]
 
     def all_events(self, since_ts: float = 0.0) -> Iterator[Event]:
-        cur = self._conn.execute(
-            "SELECT * FROM events WHERE ts >= ? ORDER BY rowid", (since_ts,)
-        )
-        for r in cur.fetchall():
+        # Read all rows under the lock, then yield outside it — long-running
+        # consumers must not hold the write lock.
+        with self._lock:
+            cur = self._conn.execute(
+                "SELECT * FROM events WHERE ts >= ? ORDER BY rowid",
+                (since_ts,),
+            )
+            rows = cur.fetchall()
+        for r in rows:
             yield Event.from_row(dict(r))
 
     def task_ids(self) -> list[str]:
-        cur = self._conn.execute("SELECT DISTINCT task_id FROM events")
-        return [r["task_id"] for r in cur.fetchall()]
-
-    def close(self) -> None:
-        self._conn.close()
-
-# NOTE — snapshotting. An append-only log grows without bound. A future
-# `snapshots` table (state of every task at a checkpoint ts) lets `reduce_task`
-# start from the last snapshot instead of replaying from genesis. Snapshots live
-# in Agentik_Runtime/snapshots/. Not required for correctness — only for scale.
+        with self._lock:
+            cur = self._conn.execute("SELECT DISTINCT task_id FROM events")
+            return [r["task_id"] for r in cur.fetchall()]
+
+    # --- snapshots --------------------------------------------------------
+    # Snapshots are an optional optimisation. Correctness depends only on
+    # events; snapshots merely bound reduction time as the log grows.
+
+    def snapshot(self, task_id: str) -> dict | None:
+        """Capture the current reduced state of a task at the latest event.
+        Returns the snapshot row, or None if the task has no events."""
+        with self._lock:
+            cur = self._conn.execute(
+                "SELECT rowid FROM events WHERE task_id = ? "
+                "ORDER BY rowid DESC LIMIT 1",
+                (task_id,),
+            )
+            row = cur.fetchone()
+        if not row:
+            return None
+        last_rowid = row[0]
+        # Local import to keep `store` importable without `reducer`-time deps.
+        from omega_engine.reducer import reduce_task
+        events = self.events_for(task_id)
+        state = reduce_task(events)
+        ts = events[-1].ts
+        with self._lock:
+            self._conn.execute(
+                "INSERT OR REPLACE INTO snapshots (task_id, state, ts, "
+                "last_event_rowid) VALUES (?, ?, ?, ?)",
+                (task_id, state.value, ts, last_rowid),
+            )
+        return {"task_id": task_id, "state": state, "ts": ts,
+                "last_event_rowid": last_rowid}
+
+    def latest_snapshot(self, task_id: str) -> dict | None:
+        """Latest snapshot for a task, or None."""
+        with self._lock:
+            cur = self._conn.execute(
+                "SELECT state, ts, last_event_rowid FROM snapshots "
+                "WHERE task_id = ? ORDER BY ts DESC LIMIT 1",
+                (task_id,),
+            )
+            row = cur.fetchone()
+        if not row:
+            return None
+        from omega_engine.task import TaskState
+        return {"state": TaskState(row["state"]), "ts": row["ts"],
+                "last_event_rowid": row["last_event_rowid"]}
+
+    def events_since_snapshot(self, task_id: str) -> list[Event]:
+        """Events appended since the latest snapshot, or all events if none."""
+        snap = self.latest_snapshot(task_id)
+        if not snap:
+            return self.events_for(task_id)
+        with self._lock:
+            cur = self._conn.execute(
+                "SELECT * FROM events WHERE task_id = ? AND rowid > ? "
+                "ORDER BY rowid",
+                (task_id, snap["last_event_rowid"]),
+            )
+            rows = cur.fetchall()
+        return [Event.from_row(dict(r)) for r in rows]