cognexdb 0.4.1__py3-none-any.whl

cognex/__init__.py

@@ -0,0 +1,7 @@
+"""Cognex: local-first file database for humans, apps, and AI."""
+
+__version__ = "0.4.1"
+
+from .sdk import CognexClient, SDKResponse, create_client
+
+__all__ = ["CognexClient", "SDKResponse", "create_client"]

cognex/ai.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import csv
+import io
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .database import FileDatabase
+
+SAFE_NAME_RE = re.compile(r"^[A-Za-z0-9_.-]+$")
+
+
+@dataclass
+class AiPlan:
+    action: str
+    confidence: float
+    explanation: str
+    collection: str | None = None
+    query: str | None = None
+    sql: str | None = None
+    params: list[Any] | None = None
+    updates: dict[str, Any] | None = None
+    filters: dict[str, Any] | None = None
+
+    def as_dict(self) -> dict[str, Any]:
+        return {k: v for k, v in self.__dict__.items() if v is not None}
+
+
+class AiNativeEngine:
+    """Deterministic AI-native command layer for local file-backed data.
+
+    This is intentionally provider-free: it turns common natural-language data
+    tasks into safe plans that can be inspected before execution, then runs them
+    against Cognex files/SQLite. LLMs can call it directly through REST, CLI,
+    SDK, or MCP without needing custom database glue code.
+    """
+
+    def __init__(self, root: str | Path):
+        self.root = Path(root).resolve()
+        self.db = FileDatabase(self.root)
+        self.db.init()
+
+    def plan(self, prompt: str, *, collection: str | None = None, csv_text: str | None = None) -> dict[str, Any]:
+        prompt = prompt.strip()
+        if not prompt:
+            raise ValueError("Prompt is required")
+        if csv_text or re.search(r"\b(create|import)\b.*\bcsv\b", prompt, re.I):
+            target = collection or self._collection_after_words(prompt, ["crm", "collection", "table"]) or "records"
+            return AiPlan("import_csv", 0.82, f"Import CSV rows into the {target} collection.", collection=target).as_dict()
+        update = self._plan_update(prompt, collection)
+        if update:
+            return update.as_dict()
+        query = self._plan_query(prompt, collection)
+        if query:
+            return query.as_dict()
+        term = self._quoted(prompt) or prompt
+        return AiPlan("search", 0.55, "Search across indexed records because no safer structured intent matched.", collection=collection, query=term).as_dict()
+
+    def run(self, prompt: str, *, collection: str | None = None, csv_text: str | None = None, dry_run: bool = False) -> dict[str, Any]:
+        plan = self.plan(prompt, collection=collection, csv_text=csv_text)
+        action = plan["action"]
+        if dry_run:
+            return {"plan": plan, "dry_run": True, "result": None}
+        if action == "search":
+            return {"plan": plan, "result": self._search(plan.get("query") or prompt, plan.get("collection"))}
+        if action == "query":
+            return {"plan": plan, "result": self.db.query(plan["sql"], plan.get("params") or [])}
+        if action == "update":
+            return {"plan": plan, "result": self._update(plan["collection"], plan.get("filters") or {}, plan.get("updates") or {})}
+        if action == "import_csv":
+            if not csv_text:
+                raise ValueError("csv_text is required for CSV imports")
+            return {"plan": plan, "result": self._import_csv(plan["collection"], csv_text)}
+        raise ValueError(f"Unsupported AI action: {action}")
+
+    def _plan_query(self, prompt: str, collection: str | None) -> AiPlan | None:
+        low = prompt.lower()
+        if not re.search(r"\b(find|show|list|get|search)\b", low):
+            return None
+        target = collection or self._collection_after_words(prompt, ["every", "all", "from", "in"]) or self._first_collection()
+        if not target or not SAFE_NAME_RE.match(target):
+            term = self._quoted(prompt) or self._term_after_words(prompt, ["bought", "contains", "about", "for"])
+            return AiPlan("search", 0.62, "Search all records for the requested term.", query=term or prompt)
+        field_filter = self._field_equals(prompt)
+        if field_filter:
+            field, value = field_filter
+            sql = f'SELECT * FROM "{target}" WHERE lower("{field}") = lower(?)'
+            return AiPlan("query", 0.86, f"Query {target} where {field} equals {value}.", collection=target, sql=sql, params=[value], filters={field: value})
+        term = self._quoted(prompt) or self._term_after_words(prompt, ["bought", "contains", "about", "for"])
+        if term:
+            return AiPlan("search", 0.74, f"Search {target} records for {term}.", collection=target, query=term)
+        return AiPlan("query", 0.7, f"List records from {target}.", collection=target, sql=f'SELECT * FROM "{target}"', params=[])
+
+    def _plan_update(self, prompt: str, collection: str | None) -> AiPlan | None:
+        # Supported safe shape: update customers where status = lead set status = active
+        match = re.search(
+            r"update\s+(?P<collection>[A-Za-z0-9_.-]+)?\s*where\s+(?P<filter>[A-Za-z0-9_.-]+)\s*=\s*(?P<value>[^\s]+)\s+set\s+(?P<field>[A-Za-z0-9_.-]+)\s*=\s*(?P<new>[^\s]+)",
+            prompt,
+            re.I,
+        )
+        if not match:
+            return None
+        target = collection or match.group("collection")
+        if not target or not SAFE_NAME_RE.match(target):
+            raise ValueError("Safe update requires a valid collection")
+        filters = {match.group("filter"): self._clean_value(match.group("value"))}
+        updates = {match.group("field"): self._clean_value(match.group("new"))}
+        return AiPlan("update", 0.9, f"Update {target} records matching {filters} with {updates}.", collection=target, filters=filters, updates=updates)
+
+    def _search(self, query: str, collection: str | None) -> list[dict[str, Any]]:
+        records = self.db.search(query, 50)
+        if collection:
+            records = [record for record in records if record["collection"] == collection]
+        return records
+
+    def _update(self, collection: str, filters: dict[str, Any], updates: dict[str, Any]) -> dict[str, Any]:
+        changed = []
+        for record in self.db.list_records(collection, 10000, 0):
+            data = record.get("data") or {}
+            if all(str(data.get(key)) == str(value) for key, value in filters.items()):
+                merged = dict(data)
+                merged.update(updates)
+                changed.append(self.db.upsert_record(collection, record["id"], merged, record.get("content", ""), record.get("format", "json"), record.get("revision")))
+        return {"updated": len(changed), "records": changed}
+
+    def _import_csv(self, collection: str, csv_text: str) -> dict[str, Any]:
+        if not SAFE_NAME_RE.match(collection):
+            raise ValueError("Invalid collection name")
+        rows = list(csv.DictReader(io.StringIO(csv_text)))
+        written = []
+        for index, row in enumerate(rows):
+            rid = str(row.get("id") or row.get("email") or row.get("name") or index).strip().replace(" ", "_")
+            rid = re.sub(r"[^A-Za-z0-9_.-]", "_", rid) or str(index)
+            written.append(self.db.upsert_record(collection, rid, dict(row), fmt="json"))
+        return {"imported": len(written), "records": written}
+
+    def _field_equals(self, prompt: str) -> tuple[str, str] | None:
+        match = re.search(r"\b([A-Za-z0-9_.-]+)\s*(?:=|is)\s*['\"]?([^'\".?!]+)['\"]?", prompt, re.I)
+        if match and SAFE_NAME_RE.match(match.group(1)):
+            return match.group(1), self._clean_value(match.group(2))
+        return None
+
+    def _collection_after_words(self, prompt: str, words: list[str]) -> str | None:
+        for word in words:
+            match = re.search(rf"\b{re.escape(word)}\s+([A-Za-z0-9_.-]+)", prompt, re.I)
+            if match:
+                candidate = match.group(1).lower().strip(".,?!")
+                if candidate not in {"that", "with", "where", "from", "the", "a", "an"} and SAFE_NAME_RE.match(candidate):
+                    return candidate
+        return None
+
+    def _term_after_words(self, prompt: str, words: list[str]) -> str | None:
+        for word in words:
+            match = re.search(rf"\b{re.escape(word)}\s+['\"]?([^'\".?!]+)['\"]?", prompt, re.I)
+            if match:
+                return self._clean_value(match.group(1))
+        return None
+
+    def _quoted(self, prompt: str) -> str | None:
+        match = re.search(r"['\"]([^'\"]+)['\"]", prompt)
+        return match.group(1).strip() if match else None
+
+    def _first_collection(self) -> str | None:
+        collections = self.db.collections()
+        return collections[0]["collection"] if collections else None
+
+    def _clean_value(self, value: str) -> str:
+        return value.strip().strip("'\".,?!")

cognex/auth.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import os
+import secrets
+import time
+from pathlib import Path
+from typing import Any
+
+
+class AuthError(RuntimeError):
+    """Raised when local Cognex authentication fails."""
+
+
+class LocalAuth:
+    """File-backed local auth for single-node/local-first deployments.
+
+    Users and sessions are stored under `.cognex/auth.json`. Passwords are
+    salted PBKDF2 hashes and session tokens are stored hashed at rest.
+    """
+
+    def __init__(self, root: str | Path, session_ttl_seconds: int = 60 * 60 * 24 * 7):
+        self.root = Path(root).resolve()
+        self.path = self.root / ".cognex" / "auth.json"
+        self.session_ttl_seconds = session_ttl_seconds
+
+    def signup(self, email: str, password: str, role: str = "user") -> dict[str, Any]:
+        email = self._normalize_email(email)
+        if len(password) < 8:
+            raise AuthError("Password must be at least 8 characters")
+        state = self._load()
+        if email in state["users"]:
+            raise AuthError("User already exists")
+        now = time.time()
+        state["users"][email] = {
+            "email": email,
+            "role": role,
+            "password": self._hash_password(password),
+            "created_at": now,
+        }
+        token, session = self._new_session(email, role)
+        state["sessions"][session["token_hash"]] = session
+        self._save(state)
+        return {"user": self._public_user(state["users"][email]), "session": {"access_token": token, "expires_at": session["expires_at"]}}
+
+    def login(self, email: str, password: str) -> dict[str, Any]:
+        email = self._normalize_email(email)
+        state = self._load()
+        user = state["users"].get(email)
+        if not user or not self._verify_password(password, user["password"]):
+            raise AuthError("Invalid email or password")
+        token, session = self._new_session(email, user.get("role", "user"))
+        state["sessions"][session["token_hash"]] = session
+        self._save(state)
+        return {"user": self._public_user(user), "session": {"access_token": token, "expires_at": session["expires_at"]}}
+
+    def validate_token(self, token: str) -> dict[str, Any] | None:
+        if not token:
+            return None
+        state = self._load()
+        session = state["sessions"].get(self._token_hash(token))
+        if not session or session.get("expires_at", 0) < time.time():
+            return None
+        user = state["users"].get(session["email"])
+        return self._public_user(user) if user else None
+
+    def logout(self, token: str) -> bool:
+        state = self._load()
+        removed = state["sessions"].pop(self._token_hash(token), None) is not None
+        if removed:
+            self._save(state)
+        return removed
+
+    def _new_session(self, email: str, role: str) -> tuple[str, dict[str, Any]]:
+        token = secrets.token_urlsafe(32)
+        now = time.time()
+        return token, {"token_hash": self._token_hash(token), "email": email, "role": role, "created_at": now, "expires_at": now + self.session_ttl_seconds}
+
+    def _load(self) -> dict[str, Any]:
+        if not self.path.exists():
+            return {"users": {}, "sessions": {}}
+        return json.loads(self.path.read_text(encoding="utf-8"))
+
+    def _save(self, state: dict[str, Any]) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self.path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(state, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+        os.replace(tmp, self.path)
+
+    def _hash_password(self, password: str) -> str:
+        salt = secrets.token_bytes(16)
+        digest = hashlib.pbkdf2_hmac("sha256", password.encode(), salt, 210_000)
+        return "pbkdf2_sha256$210000$" + base64.b64encode(salt).decode() + "$" + base64.b64encode(digest).decode()
+
+    def _verify_password(self, password: str, encoded: str) -> bool:
+        try:
+            scheme, iterations, salt_b64, digest_b64 = encoded.split("$", 3)
+            if scheme != "pbkdf2_sha256":
+                return False
+            salt = base64.b64decode(salt_b64)
+            expected = base64.b64decode(digest_b64)
+            actual = hashlib.pbkdf2_hmac("sha256", password.encode(), salt, int(iterations))
+            return hmac.compare_digest(actual, expected)
+        except Exception:
+            return False
+
+    def _token_hash(self, token: str) -> str:
+        return hashlib.sha256(token.encode()).hexdigest()
+
+    def _normalize_email(self, email: str) -> str:
+        email = (email or "").strip().lower()
+        if "@" not in email:
+            raise AuthError("Valid email is required")
+        return email
+
+    def _public_user(self, user: dict[str, Any]) -> dict[str, Any]:
+        return {"email": user["email"], "role": user.get("role", "user"), "created_at": user.get("created_at")}

cognex/cli.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from .ai import AiNativeEngine
+from .crdt import CrdtEngine
+from .database import FileDatabase
+from .functions import FunctionRunner
+from .importers import Importer
+from .engine import ProjectEngine
+from .mcp import McpServer
+from .server import serve
+from .sync import SyncEngine
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="cognex", description="Local project intelligence engine for AI coding assistants.")
+    parser.add_argument("--root", default=".", help="Project root to index. Defaults to current directory.")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    sub.add_parser("init", help="Create local Cognex state and ignore rules.")
+    sub.add_parser("index", help="Index the project.")
+    s = sub.add_parser("search", help="Search the project index."); s.add_argument("query"); s.add_argument("--limit", type=int, default=10)
+    c = sub.add_parser("context", help="Build AI-ready context for a prompt."); c.add_argument("prompt"); c.add_argument("--limit", type=int, default=8); c.add_argument("--max-chars", type=int, default=14000)
+    sub.add_parser("graph", help="Print the project graph as JSON.")
+    q = sub.add_parser("sql", help="Run read-only SQL against file collections."); q.add_argument("sql")
+    ai = sub.add_parser("ai", help="Plan or run an AI-native natural-language data task."); ai.add_argument("prompt"); ai.add_argument("--collection", default=None); ai.add_argument("--csv-file", default=None); ai.add_argument("--dry-run", action="store_true")
+    sub.add_parser("collections", help="List file database collections.")
+    u = sub.add_parser("upsert", help="Write a JSON/Markdown record to the file database."); u.add_argument("collection"); u.add_argument("id"); u.add_argument("--data", default="{}"); u.add_argument("--content", default=""); u.add_argument("--format", default="json", choices=["json", "md"]); u.add_argument("--expected-revision", default=None)
+    sub.add_parser("transactions", help="List recent local write transactions.")
+    sp = sub.add_parser("sync-push", help="Push local data files to a filesystem/Git sync remote."); sp.add_argument("remote"); sp.add_argument("--force", action="store_true"); sp.add_argument("--git", action="store_true"); sp.add_argument("--message", default="Cognex sync push"); sp.add_argument("--no-crdt", action="store_true")
+    sl = sub.add_parser("sync-pull", help="Pull data files from a filesystem/Git sync remote."); sl.add_argument("remote"); sl.add_argument("--force", action="store_true"); sl.add_argument("--git", action="store_true"); sl.add_argument("--no-crdt", action="store_true")
+    ss = sub.add_parser("sync-status", help="Show pending push/pull/conflict status for a sync remote."); ss.add_argument("remote")
+    cu = sub.add_parser("crdt-update", help="Apply CRDT field updates to a JSON record."); cu.add_argument("collection"); cu.add_argument("id"); cu.add_argument("--fields", default="{}"); cu.add_argument("--deletes", default="[]"); cu.add_argument("--actor", default=None)
+    ce = sub.add_parser("crdt-export", help="Export CRDT operations to a JSON file."); ce.add_argument("target"); ce.add_argument("--since", type=float, default=0.0)
+    ci = sub.add_parser("crdt-import", help="Import CRDT operations from a JSON file."); ci.add_argument("source")
+    imp = sub.add_parser("import", help="Import Supabase/Firebase exports."); imp.add_argument("provider", choices=["supabase", "firebase"]); imp.add_argument("source"); imp.add_argument("--collection", default=None)
+    fn = sub.add_parser("function", help="Run a local Cognex function from .cognex/functions."); fn.add_argument("name"); fn.add_argument("--data", default="{}")
+    api = sub.add_parser("serve", help="Run the production REST backend."); api.add_argument("--host", default="0.0.0.0"); api.add_argument("--port", type=int, default=8080); api.add_argument("--api-key", default=""); api.add_argument("--no-watch", action="store_true")
+    sub.add_parser("mcp", help="Run an MCP stdio server.")
+    args = parser.parse_args(argv)
+    root = Path(args.root)
+    engine = ProjectEngine(root)
+
+    if args.cmd == "init":
+        engine.init(); print(f"Initialized Cognex at {engine.state_dir}")
+    elif args.cmd == "index":
+        engine.load(); print(json.dumps(engine.index(), indent=2))
+    elif args.cmd == "search":
+        engine.load(); print(json.dumps([h.__dict__ for h in engine.search(args.query, args.limit)], indent=2))
+    elif args.cmd == "context":
+        engine.load(); print(engine.context(args.prompt, args.limit, args.max_chars))
+    elif args.cmd == "graph":
+        engine.load(); print(json.dumps(engine.graph(), indent=2))
+    elif args.cmd == "sql":
+        db = FileDatabase(root); print(json.dumps(db.query(args.sql), indent=2))
+    elif args.cmd == "ai":
+        csv_text = Path(args.csv_file).read_text(encoding="utf-8") if args.csv_file else None
+        print(json.dumps(AiNativeEngine(root).run(args.prompt, collection=args.collection, csv_text=csv_text, dry_run=args.dry_run), indent=2))
+    elif args.cmd == "collections":
+        db = FileDatabase(root); print(json.dumps(db.collections(), indent=2))
+    elif args.cmd == "import":
+        importer = Importer(root)
+        result = importer.import_supabase(args.source, args.collection) if args.provider == "supabase" else importer.import_firebase(args.source, args.collection)
+        print(json.dumps(result, indent=2))
+    elif args.cmd == "function":
+        print(json.dumps(FunctionRunner(root).run(args.name, json.loads(args.data)), indent=2))
+    elif args.cmd == "upsert":
+        db = FileDatabase(root); print(json.dumps(db.upsert_record(args.collection, args.id, json.loads(args.data), args.content, args.format, args.expected_revision), indent=2))
+    elif args.cmd == "transactions":
+        db = FileDatabase(root); print(json.dumps(db.transaction_log(), indent=2))
+    elif args.cmd == "sync-push":
+        print(json.dumps(SyncEngine(root).push(args.remote, args.force, args.git, args.message, not args.no_crdt).__dict__, indent=2))
+    elif args.cmd == "sync-pull":
+        print(json.dumps(SyncEngine(root).pull(args.remote, args.force, args.git, not args.no_crdt).__dict__, indent=2))
+    elif args.cmd == "sync-status":
+        print(json.dumps(SyncEngine(root).status(args.remote), indent=2))
+    elif args.cmd == "crdt-update":
+        print(json.dumps(CrdtEngine(root, args.actor).apply_update(args.collection, args.id, json.loads(args.fields), json.loads(args.deletes)), indent=2))
+    elif args.cmd == "crdt-export":
+        print(json.dumps(CrdtEngine(root).write_export(args.target, args.since), indent=2))
+    elif args.cmd == "crdt-import":
+        print(json.dumps(CrdtEngine(root).merge_files(args.source), indent=2))
+    elif args.cmd == "serve":
+        serve(root, args.host, args.port, args.api_key, not args.no_watch)
+    elif args.cmd == "mcp":
+        McpServer(root).serve()
+    return 0
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cognex/crdt.py

@@ -0,0 +1,187 @@
+from __future__ import annotations
+
+import json
+import os
+import time
+import uuid
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+from .database import FileDatabase
+
+DELETE = "__cognex_deleted__"
+
+@dataclass(frozen=True)
+class CrdtOp:
+    op_id: str
+    actor: str
+    seq: int
+    collection: str
+    id: str
+    field: str
+    value: Any
+    deleted: bool
+    ts: float
+
+class CrdtEngine:
+    """Operation-based LWW-register CRDT for JSON-style Cognex records.
+
+    It stores idempotent field operations, imports/exports operation logs, and
+    materializes the deterministic merged state back into human-readable files.
+    Different fields merge automatically. Same-field concurrent edits resolve by
+    a deterministic last-writer-wins tuple: (ts, actor, op_id).
+    """
+
+    def __init__(self, root: str | Path, actor: str | None = None):
+        self.root = Path(root).resolve()
+        self.db = FileDatabase(self.root)
+        self.db.init()
+        self.actor = actor or os.getenv("COGNEX_ACTOR") or self._load_actor()
+        self._create_schema()
+
+    def _create_schema(self) -> None:
+        db = self.db.connect()
+        db.executescript(
+            """
+            CREATE TABLE IF NOT EXISTS crdt_ops (
+              op_id TEXT PRIMARY KEY,
+              actor TEXT NOT NULL,
+              seq INTEGER NOT NULL,
+              collection TEXT NOT NULL,
+              id TEXT NOT NULL,
+              field TEXT NOT NULL,
+              value_json TEXT NOT NULL,
+              deleted INTEGER NOT NULL,
+              ts REAL NOT NULL,
+              received_at REAL NOT NULL
+            );
+            CREATE INDEX IF NOT EXISTS idx_crdt_record ON crdt_ops(collection, id);
+            CREATE TABLE IF NOT EXISTS crdt_actor_state (
+              actor TEXT PRIMARY KEY,
+              seq INTEGER NOT NULL
+            );
+            """
+        )
+        db.commit()
+
+    def _load_actor(self) -> str:
+        path = self.root / ".cognex" / "actor_id"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        if path.exists():
+            return path.read_text(encoding="utf-8").strip()
+        actor = f"actor-{uuid.uuid4()}"
+        path.write_text(actor, encoding="utf-8")
+        return actor
+
+    def _next_seq(self) -> int:
+        db = self.db.connect()
+        row = db.execute("SELECT seq FROM crdt_actor_state WHERE actor=?", (self.actor,)).fetchone()
+        seq = int(row["seq"]) + 1 if row else 1
+        db.execute("INSERT INTO crdt_actor_state(actor,seq) VALUES(?,?) ON CONFLICT(actor) DO UPDATE SET seq=excluded.seq", (self.actor, seq))
+        db.commit()
+        return seq
+
+    def apply_update(self, collection: str, rid: str, fields: dict[str, Any], deletes: list[str] | None = None, actor: str | None = None) -> dict[str, Any]:
+        ops = []
+        actor_id = actor or self.actor
+        for field, value in fields.items():
+            ops.append(self._new_op(collection, rid, field, value, False, actor_id))
+        for field in deletes or []:
+            ops.append(self._new_op(collection, rid, field, None, True, actor_id))
+        imported = self.import_ops([asdict(op) for op in ops], materialize=False)
+        record = self.materialize_record(collection, rid)
+        return {"actor": actor_id, "applied": imported["imported"], "ops": [asdict(op) for op in ops], "record": record}
+
+    def delete_record(self, collection: str, rid: str, actor: str | None = None) -> dict[str, Any]:
+        return self.apply_update(collection, rid, {DELETE: True}, actor=actor)
+
+    def _new_op(self, collection: str, rid: str, field: str, value: Any, deleted: bool, actor: str) -> CrdtOp:
+        seq = self._next_seq() if actor == self.actor else int(time.time() * 1_000_000)
+        ts = time.time()
+        op_id = f"{actor}:{seq}:{uuid.uuid4().hex}"
+        return CrdtOp(op_id, actor, seq, collection, rid, field, value, deleted, ts)
+
+    def import_ops(self, ops: list[dict[str, Any]], materialize: bool = True) -> dict[str, Any]:
+        db = self.db.connect()
+        imported = 0
+        touched: set[tuple[str, str]] = set()
+        for raw in ops:
+            op = self._normalize(raw)
+            try:
+                db.execute(
+                    "INSERT INTO crdt_ops(op_id,actor,seq,collection,id,field,value_json,deleted,ts,received_at) VALUES(?,?,?,?,?,?,?,?,?,?)",
+                    (op.op_id, op.actor, op.seq, op.collection, op.id, op.field, json.dumps(op.value, sort_keys=True), int(op.deleted), op.ts, time.time()),
+                )
+                imported += 1
+                touched.add((op.collection, op.id))
+            except Exception as exc:
+                if "UNIQUE" not in str(exc).upper():
+                    raise
+        db.commit()
+        records = []
+        if materialize:
+            for collection, rid in sorted(touched):
+                records.append(self.materialize_record(collection, rid))
+        return {"imported": imported, "records": records}
+
+    def export_ops(self, since: float = 0.0, collection: str | None = None, rid: str | None = None) -> list[dict[str, Any]]:
+        sql = "SELECT * FROM crdt_ops WHERE ts >= ?"
+        params: list[Any] = [since]
+        if collection:
+            sql += " AND collection = ?"; params.append(collection)
+        if rid:
+            sql += " AND id = ?"; params.append(rid)
+        sql += " ORDER BY ts, actor, seq, op_id"
+        rows = self.db.connect().execute(sql, params).fetchall()
+        return [self._row_to_op(row) for row in rows]
+
+    def materialize_record(self, collection: str, rid: str) -> dict[str, Any]:
+        state = self.merged_state(collection, rid)
+        if state.get(DELETE) is True:
+            self.db.delete_record(collection, rid)
+            return {"collection": collection, "id": rid, "deleted": True, "data": {}}
+        record = self.db.upsert_record(collection, rid, state)
+        return record
+
+    def merged_state(self, collection: str, rid: str) -> dict[str, Any]:
+        rows = self.db.connect().execute("SELECT * FROM crdt_ops WHERE collection=? AND id=?", (collection, rid)).fetchall()
+        winners: dict[str, tuple[tuple[float, str, str], Any, bool]] = {}
+        for row in rows:
+            key = (float(row["ts"]), row["actor"], row["op_id"])
+            field = row["field"]
+            old = winners.get(field)
+            if old is None or key > old[0]:
+                winners[field] = (key, json.loads(row["value_json"]), bool(row["deleted"]))
+        data: dict[str, Any] = {}
+        for field, (_, value, deleted) in winners.items():
+            if not deleted:
+                data[field] = value
+        return data
+
+    def merge_files(self, source: str | Path) -> dict[str, Any]:
+        path = Path(source)
+        payload = json.loads(path.read_text(encoding="utf-8"))
+        return self.import_ops(payload.get("ops", payload if isinstance(payload, list) else []))
+
+    def write_export(self, target: str | Path, since: float = 0.0) -> dict[str, Any]:
+        path = Path(target)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        ops = self.export_ops(since)
+        payload = {"version": 1, "actor": self.actor, "exported_at": time.time(), "ops": ops}
+        path.write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
+        return {"target": str(path), "ops": len(ops)}
+
+    def _normalize(self, raw: dict[str, Any]) -> CrdtOp:
+        return CrdtOp(
+            op_id=str(raw["op_id"]), actor=str(raw["actor"]), seq=int(raw["seq"]),
+            collection=str(raw["collection"]), id=str(raw["id"]), field=str(raw["field"]),
+            value=raw.get("value"), deleted=bool(raw.get("deleted", False)), ts=float(raw["ts"]),
+        )
+
+    def _row_to_op(self, row) -> dict[str, Any]:
+        return {
+            "op_id": row["op_id"], "actor": row["actor"], "seq": row["seq"],
+            "collection": row["collection"], "id": row["id"], "field": row["field"],
+            "value": json.loads(row["value_json"]), "deleted": bool(row["deleted"]), "ts": row["ts"],
+        }