ctxora 6.2.0

package/src/harness_context/storage/__init__.py

@@ -0,0 +1,6 @@
+"""Local persistence adapters."""
+
+from harness_context.storage.pins import SnapshotPin
+from harness_context.storage.snapshots import SnapshotStore
+
+__all__ = ["SnapshotPin", "SnapshotStore"]

package/src/harness_context/storage/migrations.py

@@ -0,0 +1,24 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Migration:
+    version: int
+    apply: object
+    rollback: object | None = None
+
+
+def _version_one(state_dir: Path) -> None:
+    (state_dir / "snapshots").mkdir(parents=True, exist_ok=True)
+
+
+def _version_two(state_dir: Path) -> None:
+    (state_dir / "candidates").mkdir(parents=True, exist_ok=True)
+
+
+def _rollback_version_two(state_dir: Path) -> None:
+    (state_dir / "candidates").rmdir()
+
+
+MIGRATIONS = (Migration(1, _version_one), Migration(2, _version_two, _rollback_version_two))

package/src/harness_context/storage/pins.py

@@ -0,0 +1,10 @@
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class SnapshotPin:
+    workspace_id: str
+    snapshot_id: str
+    snapshot_version: int
+    state: Any

package/src/harness_context/storage/snapshots.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import time
+import uuid
+from pathlib import Path
+
+from harness_context.paths import workspace_state_dir
+from harness_context.storage.migrations import MIGRATIONS
+from harness_context.workspace import file_lock, validate_ready_snapshot
+
+SCHEMA_VERSION = 2
+
+
+class SnapshotStore:
+    def __init__(self, workspace_root: str | Path):
+        self.state_dir = workspace_state_dir(workspace_root)
+        self.snapshots_dir = self.state_dir / "snapshots"
+        self.candidates_dir = self.state_dir / "candidates"
+        self.active_path = self.state_dir / "active.json"
+        self.previous_path = self.state_dir / "active.previous.json"
+        self.schema_path = self.state_dir / "schema.json"
+        self.lock_path = self.state_dir / "state.lock"
+
+    @staticmethod
+    def _atomic_json(path: Path, payload: dict) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        descriptor, temporary = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+        try:
+            with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+                json.dump(payload, handle, ensure_ascii=False, sort_keys=True)
+                handle.flush()
+                os.fsync(handle.fileno())
+            os.replace(temporary, path)
+        finally:
+            if os.path.exists(temporary):
+                os.unlink(temporary)
+
+    def prepare(self) -> None:
+        self.state_dir.mkdir(parents=True, exist_ok=True)
+        with file_lock(self.lock_path):
+            version = json.loads(self.schema_path.read_text("utf-8")).get("version", 0) if self.schema_path.exists() else 0
+            if version > SCHEMA_VERSION:
+                raise RuntimeError(f"snapshot schema {version} is newer than supported {SCHEMA_VERSION}")
+            for migration in MIGRATIONS:
+                if migration.version > version:
+                    try:
+                        migration.apply(self.state_dir)
+                    except Exception:
+                        if migration.rollback is not None:
+                            migration.rollback(self.state_dir)
+                        raise
+                    self._atomic_json(self.schema_path, {"version": migration.version})
+                    version = migration.version
+            for temporary in self.state_dir.rglob("*.tmp"):
+                temporary.unlink(missing_ok=True)
+            self._recover_active()
+
+    def _recover_active(self) -> None:
+        if not self.active_path.exists() and self.previous_path.exists():
+            os.replace(self.previous_path, self.active_path)
+        if self.active_path.exists():
+            try:
+                active = json.loads(self.active_path.read_text("utf-8"))
+            except (json.JSONDecodeError, OSError):
+                active = {}
+            if not (self.snapshots_dir / f"{active.get('snapshot_id', '')}.json").exists() and self.previous_path.exists():
+                os.replace(self.previous_path, self.active_path)
+
+    def create_candidate(self, snapshot: dict) -> str:
+        validate_ready_snapshot(snapshot)
+        candidate_id = self.begin_candidate(snapshot["workspace_id"])
+        self.validate_candidate(candidate_id, snapshot)
+        return candidate_id
+
+    def begin_candidate(self, workspace_id: str) -> str:
+        self.prepare()
+        candidate_id = uuid.uuid4().hex
+        self._atomic_json(self.candidates_dir / f"{candidate_id}.json", {
+            "candidate_id": candidate_id, "workspace_id": workspace_id,
+            "status": "building", "created_at": time.time(),
+        })
+        return candidate_id
+
+    def validate_candidate(self, candidate_id: str, snapshot: dict) -> None:
+        validate_ready_snapshot(snapshot)
+        record_path = self.candidates_dir / f"{candidate_id}.json"
+        record = json.loads(record_path.read_text("utf-8"))
+        if record["workspace_id"] != snapshot["workspace_id"]:
+            raise ValueError("candidate workspace does not match snapshot")
+        record.update(status="validated", snapshot=snapshot, validated_at=time.time())
+        self._atomic_json(record_path, record)
+
+    def fail_candidate(self, candidate_id: str, error: Exception) -> None:
+        record_path = self.candidates_dir / f"{candidate_id}.json"
+        if not record_path.exists():
+            return
+        record = json.loads(record_path.read_text("utf-8"))
+        record.update(status="failed", failed_at=time.time(), error=str(error))
+        self._atomic_json(record_path, record)
+
+    def promote_candidate(self, candidate_id: str) -> None:
+        with file_lock(self.lock_path):
+            record_path = self.candidates_dir / f"{candidate_id}.json"
+            record = json.loads(record_path.read_text("utf-8"))
+            if record.get("status") != "validated":
+                raise ValueError("only validated candidates may be promoted")
+            snapshot = record["snapshot"]
+            validate_ready_snapshot(snapshot)
+            snapshot_path = self.snapshots_dir / f"{snapshot['snapshot_id']}.json"
+            if not snapshot_path.exists():
+                self._atomic_json(snapshot_path, snapshot)
+            if self.active_path.exists():
+                self._atomic_json(self.previous_path, json.loads(self.active_path.read_text("utf-8")))
+            self._atomic_json(self.active_path, {
+                "workspace_id": snapshot["workspace_id"], "snapshot_id": snapshot["snapshot_id"],
+                "snapshot_version": snapshot["snapshot_version"],
+            })
+            record["status"] = "promoted"
+            self._atomic_json(record_path, record)
+            retained = sorted(self.snapshots_dir.glob("*.json"), key=lambda item: item.stat().st_mtime, reverse=True)
+            for expired in retained[3:]:
+                expired.unlink(missing_ok=True)
+
+    def promote(self, snapshot: dict) -> None:
+        self.promote_candidate(self.create_candidate(snapshot))
+
+    def rollback(self) -> None:
+        with file_lock(self.lock_path):
+            if not self.previous_path.exists():
+                raise RuntimeError("no previous active snapshot")
+            current = json.loads(self.active_path.read_text("utf-8")) if self.active_path.exists() else None
+            previous = json.loads(self.previous_path.read_text("utf-8"))
+            self._atomic_json(self.active_path, previous)
+            if current:
+                self._atomic_json(self.previous_path, current)
+
+    def load_active(self, workspace_id: str) -> dict | None:
+        self.prepare()
+        with file_lock(self.lock_path):
+            if not self.active_path.exists():
+                return None
+            active = json.loads(self.active_path.read_text("utf-8"))
+            if active.get("workspace_id") != workspace_id:
+                return None
+            path = self.snapshots_dir / f"{active['snapshot_id']}.json"
+            return json.loads(path.read_text("utf-8")) if path.exists() else None

package/src/harness_context/tokenize.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+import re
+import unicodedata
+
+
+def tokens(text: str) -> list[str]:
+    normalized = unicodedata.normalize("NFC", text)
+    normalized = re.sub(r"([a-z0-9])([A-Z])", r"\1 \2", normalized).replace("_", " ")
+    words = re.findall(r"[^\W_]+", normalized.casefold(), re.UNICODE)
+    grams = [word[index:index + 3] for word in words for index in range(max(0, len(word) - 2))]
+    return words + grams

package/src/harness_context/topology.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import ast
+import json
+from pathlib import Path
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # Python 3.10
+    import tomli as tomllib
+
+REQUIRED_PATHS = (
+    "CHANGELOG.md", "SUPPORT.md", "docs/ARCHITECTURE.md", "docs/OPERATIONS.md",
+    "docs/PRICING.md",
+    "examples/basic_usage.py", "examples/mcp-config.json", "migrations/manifest.json",
+    "migrations/README.md", "schemas/README.md", "scripts/install.sh",
+    "scripts/migrate_state.py", "scripts/uninstall.sh", "src/harness_context/server.py",
+)
+LEGACY_IMPLEMENTATION_DIRS = ("harness_context", "chunking", "compact", "context", "memory", "retrieval", "evaluation")
+PAID_DEPENDENCIES = {
+    "stripe", "launchdarkly", "ctxora_cloud", "ctxora_control_plane",
+    "harness_cloud", "harness_control_plane",
+}
+
+
+def audit(root: Path) -> list[str]:
+    failures: list[str] = []
+    for relative in REQUIRED_PATHS:
+        if not (root / relative).exists():
+            failures.append(f"missing required artifact: {relative}")
+    for directory in LEGACY_IMPLEMENTATION_DIRS:
+        if (root / directory).is_dir():
+            failures.append(f"legacy production package remains at repository root: {directory}/")
+    config = tomllib.loads((root / "pyproject.toml").read_text("utf-8"))
+    package_dir = config.get("tool", {}).get("setuptools", {}).get("package-dir", {})
+    if package_dir.get("") != "src":
+        failures.append("setuptools package-dir must map the package root to src")
+    dependencies = {item.split("[", 1)[0].split("<", 1)[0].split(">", 1)[0].split("=", 1)[0].strip().lower() for item in config["project"].get("dependencies", [])}
+    for dependency in sorted(dependencies & PAID_DEPENDENCIES):
+        failures.append(f"paid control-plane dependency is forbidden: {dependency}")
+    for source in sorted((root / "src").rglob("*.py")):
+        tree = ast.parse(source.read_text("utf-8"), filename=str(source))
+        imported = set()
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                imported.update(alias.name.split(".", 1)[0] for alias in node.names)
+            elif isinstance(node, ast.ImportFrom) and node.module:
+                imported.add(node.module.split(".", 1)[0])
+        for dependency in sorted(imported & PAID_DEPENDENCIES):
+            failures.append(f"paid control-plane import in {source.relative_to(root)}: {dependency}")
+    shim = (root / "server.py").read_text("utf-8")
+    if shim.count("\n") > 20 or "harness_context import server" not in shim:
+        failures.append("server.py must remain a tiny compatibility shim")
+    return failures
+
+
+def main() -> int:
+    root = Path(__file__).resolve().parents[2]
+    failures = audit(root)
+    print(json.dumps({"status": "failed" if failures else "ok", "failures": failures}, sort_keys=True))
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/harness_context/watcher/__init__.py

@@ -0,0 +1,3 @@
+from harness_context.watcher.service import WorkspaceWatcher
+
+__all__ = ["WorkspaceWatcher"]

package/src/harness_context/watcher/service.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import threading
+
+from harness_context.application.protocols import RefreshCommands, RetrievalQueries
+
+
+class WorkspaceWatcher:
+    """Treat filesystem events as hints and confirm freshness by content hash."""
+
+    def __init__(self, retrieval: RetrievalQueries, refresh: RefreshCommands, workspace_id: str, interval: float = 1.0):
+        self.retrieval = retrieval
+        self.refresh = refresh
+        self.workspace_id = workspace_id
+        self.interval = interval
+        self._stop = threading.Event()
+        self._thread = threading.Thread(target=self._run, name="harness-watcher", daemon=True)
+
+    def start(self) -> None:
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        self._thread.join(timeout=max(2.0, self.interval * 2))
+
+    def _run(self) -> None:
+        while not self._stop.wait(self.interval):
+            if not self.retrieval.snapshot_is_current(self.workspace_id):
+                try:
+                    self.refresh.execute(self.workspace_id)
+                except Exception:
+                    continue

package/src/harness_context/workspace/__init__.py

@@ -0,0 +1,13 @@
+from harness_context.workspace.identity import workspace_identity
+from harness_context.workspace.lock import file_lock
+from harness_context.workspace.policy import WorkspacePolicy
+from harness_context.workspace.roots import DEFAULT_DENY, WorkspaceRegistry
+from harness_context.workspace.state import (
+    WorkspaceStatus,
+    transition_workspace_status,
+    validate_ready_snapshot,
+)
+
+_DEFAULT_DENY = DEFAULT_DENY
+
+__all__ = ["WorkspacePolicy", "WorkspaceRegistry", "WorkspaceStatus", "file_lock", "transition_workspace_status", "validate_ready_snapshot", "workspace_identity"]

package/src/harness_context/workspace/identity.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+
+def workspace_identity(root: str | Path) -> str:
+    canonical = str(Path(root).expanduser().resolve(strict=True))
+    return "ws_" + hashlib.sha256(canonical.encode()).hexdigest()[:16]

package/src/harness_context/workspace/lock.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from pathlib import Path
+
+
+@contextmanager
+def file_lock(path: str | Path):
+    lock_path = Path(path)
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    with lock_path.open("a+") as handle:
+        try:
+            import fcntl
+            fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+        except ImportError:
+            pass
+        try:
+            yield
+        finally:
+            try:
+                import fcntl
+                fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+            except ImportError:
+                pass

package/src/harness_context/workspace/policy.py

@@ -0,0 +1,3 @@
+from harness_context.schemas import WorkspacePolicy
+
+__all__ = ["WorkspacePolicy"]

package/src/harness_context/workspace/roots.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import fnmatch
+from pathlib import Path
+
+from harness_context.schemas import HarnessError
+from harness_context.security import contains_secret
+from harness_context.workspace.policy import WorkspacePolicy
+
+DEFAULT_DENY = (
+    ".git", ".hg", ".svn", ".ctxora", ".harness", ".ecc", "node_modules", "vendor", ".venv", "venv",
+    "dist", "build", "__pycache__", ".env", ".env.*", "*.pem", "*.key", "id_rsa", "id_ed25519",
+    "*.sqlite", "*.sqlite3", "*.db", "*.egg-info",
+)
+
+
+class WorkspaceRegistry:
+    def __init__(self) -> None:
+        self._policies: dict[str, WorkspacePolicy] = {}
+
+    def register(self, workspace_id: str, roots: list[str], **limits: int) -> WorkspacePolicy:
+        if not workspace_id.strip():
+            raise HarnessError("invalid_workspace", "workspace_id is required")
+        canonical = tuple(sorted({str(Path(root).expanduser().resolve(strict=True)) for root in roots}))
+        if not canonical:
+            raise HarnessError("invalid_workspace", "at least one existing root is required")
+        policy = WorkspacePolicy(roots=canonical, **limits)
+        self._policies[workspace_id] = policy
+        return policy
+
+    def get(self, workspace_id: str) -> WorkspacePolicy:
+        try:
+            return self._policies[workspace_id]
+        except KeyError as error:
+            raise HarnessError("unknown_workspace", f"workspace not registered: {workspace_id}") from error
+
+    def authorize(self, workspace_id: str, paths: list[str]) -> list[Path]:
+        policy = self.get(workspace_id)
+        authorized = []
+        for raw in paths:
+            unresolved = Path(raw).expanduser()
+            if unresolved.is_symlink():
+                raise HarnessError("symlink_path", f"symlink paths are not allowed: {unresolved.name}")
+            path = unresolved.resolve(strict=False)
+            if not any(path == Path(root) or Path(root) in path.parents for root in policy.roots):
+                raise HarnessError("unauthorized_path", f"path is outside workspace roots: {path.name}")
+            authorized.append(path)
+        return authorized
+
+    @staticmethod
+    def _patterns(root: Path) -> list[str]:
+        patterns = list(DEFAULT_DENY)
+        for name in (".gitignore", ".ctxoraignore", ".harnessignore"):
+            ignore = root / name
+            if ignore.is_file():
+                patterns.extend(line.strip().lstrip("/") for line in ignore.read_text("utf-8").splitlines() if line.strip() and not line.lstrip().startswith("#") and not line.startswith("!"))
+        return patterns
+
+    def files(self, workspace_id: str, paths: list[str]) -> list[Path]:
+        policy = self.get(workspace_id)
+        selected, total = [], 0
+        for source in self.authorize(workspace_id, paths):
+            if not source.exists():
+                continue
+            base = source if source.is_dir() else source.parent
+            patterns = self._patterns(base)
+            candidates = [source] if source.is_file() else source.rglob("*")
+            for path in candidates:
+                if not path.is_file() or path.is_symlink():
+                    continue
+                relative = path.relative_to(base).as_posix()
+                if any(fnmatch.fnmatch(relative, pattern) or any(fnmatch.fnmatch(part, pattern) for part in path.parts) for pattern in patterns):
+                    continue
+                size = path.stat().st_size
+                if size > policy.max_file_bytes:
+                    continue
+                content = path.read_bytes()
+                if b"\x00" in content[:4096] or contains_secret(content):
+                    continue
+                total += size
+                if total > policy.max_total_bytes or len(selected) >= policy.max_files:
+                    raise HarnessError("workspace_limit", "workspace indexing limits exceeded")
+                selected.append(path)
+        return sorted(set(selected))

package/src/harness_context/workspace/state.py

@@ -0,0 +1,35 @@
+from enum import Enum
+
+
+class WorkspaceStatus(str, Enum):
+    REGISTERED = "registered"
+    INDEXING = "indexing"
+    READY = "ready"
+
+
+_TRANSITIONS = {
+    WorkspaceStatus.REGISTERED: {WorkspaceStatus.INDEXING},
+    WorkspaceStatus.INDEXING: {WorkspaceStatus.READY},
+    WorkspaceStatus.READY: {WorkspaceStatus.INDEXING, WorkspaceStatus.REGISTERED},
+}
+
+
+def transition_workspace_status(current: str | WorkspaceStatus, target: str | WorkspaceStatus) -> WorkspaceStatus:
+    current_status = WorkspaceStatus(current)
+    target_status = WorkspaceStatus(target)
+    if target_status not in _TRANSITIONS[current_status]:
+        raise ValueError(f"invalid workspace transition: {current_status.value} -> {target_status.value}")
+    return target_status
+
+
+def validate_ready_snapshot(snapshot: dict) -> None:
+    required = {"workspace_id", "snapshot_id", "snapshot_version", "status", "fingerprints", "items"}
+    missing = required - snapshot.keys()
+    if missing:
+        raise ValueError(f"snapshot is missing required fields: {sorted(missing)}")
+    if snapshot["status"] != WorkspaceStatus.READY:
+        raise ValueError("only ready snapshots may be promoted")
+    if not snapshot["snapshot_id"] or int(snapshot["snapshot_version"]) < 1:
+        raise ValueError("snapshot identity is invalid")
+    if any(item.get("workspace_id") != snapshot["workspace_id"] for item in snapshot["items"]):
+        raise ValueError("snapshot contains items from another workspace")