ctxora 6.2.0

package/src/harness_context/application/context_service.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import time
+
+from compact.handoff import ConversationHandoffStore
+from harness_context.adapters.ecc import EccMemoryReader
+from harness_context.api.v2 import ContextPackageV2, PrepareContextRequest
+from harness_context.engine import ContextEngine
+from harness_context.schemas import HarnessError
+from memory.episodic import MemoryStore
+
+
+class ContextService:
+    def __init__(self, engine: ContextEngine, memory: MemoryStore, handoffs: ConversationHandoffStore, ecc: EccMemoryReader | None = None):
+        self.engine = engine
+        self.memory = memory
+        self.handoffs = handoffs
+        self.ecc = ecc
+
+    def prepare(self, request: PrepareContextRequest) -> ContextPackageV2:
+        if request.deadline_ms <= 0:
+            raise HarnessError("invalid_deadline", "deadline_ms must be positive")
+        started = time.perf_counter()
+        preferred = "" if request.preferred_strategy == "auto" else request.preferred_strategy
+        with self.engine.snapshot_pin(request.workspace_id) as pin:
+            if request.freshness == "current" and not self.engine.snapshot_is_current(request.workspace_id, pin.state):
+                raise HarnessError("stale_snapshot", "active snapshot is stale; refresh_workspace is required")
+            prepared = self.engine.prepare_context(request.workspace_id, request.query, request.available_input_tokens, preferred, pin)
+        evidence = prepared["retrieval"]
+        memory = self.memory.search(request.query, top_k=4, workspace_id=request.workspace_id) if request.include_memory else []
+        handoff = None
+        if request.include_handoff:
+            if not request.handoff_id:
+                raise HarnessError("missing_handoff_id", "handoff_id is required when include_handoff is true")
+            handoff = self.handoffs.restore(request.handoff_id, request.workspace_id)
+            if handoff is None:
+                raise HarnessError("handoff_not_found", "handoff was not found in this workspace")
+        external_context, ecc_diagnostics = [], []
+        if request.include_ecc:
+            if self.ecc is None or not self.ecc.installation.available:
+                raise HarnessError("ecc_not_available", "ECC adapter is not enabled or no local ECC vault was detected")
+            ecc_result = self.ecc.search(request.query, limit=4)
+            external_context, ecc_diagnostics = ecc_result["entries"], ecc_result["diagnostics"]
+        elapsed_ms = (time.perf_counter() - started) * 1000
+        if elapsed_ms > request.deadline_ms:
+            raise HarnessError("deadline_exceeded", "context preparation exceeded deadline_ms")
+        diagnostics = {"coverage": evidence.get("coverage", "not_applicable") if evidence else "not_applicable", "freshness": request.freshness, "untrusted_content": True, "latency_ms": round(elapsed_ms, 3), "ecc": {"enabled": self.ecc is not None, "diagnostics": ecc_diagnostics}}
+        return ContextPackageV2(api_version="2.0", workspace_id=request.workspace_id, snapshot_id=prepared["snapshot_id"], snapshot_version=prepared["snapshot_version"], plan=prepared["plan"], stable_context=prepared["bundle"], evidence=evidence, memory=memory, handoff=handoff, external_context=external_context, diagnostics=diagnostics)
+
+    def prepare_values(self, **values) -> dict:
+        return self.prepare(PrepareContextRequest(**values)).to_dict()

package/src/harness_context/application/ecc_service.py

@@ -0,0 +1,7 @@
+class EccService:
+    def __init__(self, reader): self.reader = reader
+    def status(self): return self.reader.status() if self.reader else {"enabled": False, "available": False, "read_only": True}
+    def search(self, query, limit=4):
+        if self.reader is None or not self.reader.installation.available:
+            raise ValueError("ECC adapter is not enabled or no local ECC vault was detected")
+        return self.reader.search(query, limit)

package/src/harness_context/application/handoff_service.py

@@ -0,0 +1,11 @@
+class HandoffService:
+    def __init__(self, store): self.store = store
+    def prepare(self, workspace_id, messages_json, threshold_tokens=30_000, label="", retention_seconds=604_800, consent=False): return self.store.prepare(messages_json, threshold_tokens, label, workspace_id, retention_seconds, consent)
+    def restore(self, workspace_id, handoff_id):
+        result = self.store.restore(handoff_id, workspace_id)
+        if result is None:
+            raise ValueError("handoff not found")
+        return result
+    def list(self, workspace_id, limit=30): return self.store.list(workspace_id, limit)
+    def delete(self, workspace_id, handoff_id): return {"deleted": self.store.delete(handoff_id, workspace_id)}
+    def purge(self): return {"purged": self.store.purge_expired()}

package/src/harness_context/application/memory_service.py

@@ -0,0 +1,9 @@
+from memory.episodic import MemoryType
+
+
+class MemoryService:
+    def __init__(self, store): self.store = store
+    def save(self, workspace_id, key, value, mtype="semantic", tags="", scope="workspace", source="user", confidence=1.0, expires_at=None): return self.store.save(MemoryType(mtype), key, value, tags, workspace_id=workspace_id, scope=scope, source=source, confidence=confidence, expires_at=expires_at)
+    def search(self, workspace_id, query, mtype="", top_k=5, min_sim=0.12): return self.store.search(query, MemoryType(mtype) if mtype else None, top_k, min_sim, workspace_id)
+    def delete(self, workspace_id, key, mtype="semantic"): return {"deleted": self.store.delete(MemoryType(mtype), key, workspace_id)}
+    def list(self, workspace_id, mtype="", limit=30): return self.store.list_keys(MemoryType(mtype) if mtype else None, limit, workspace_id)

package/src/harness_context/application/protocols.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from harness_context.api.v2 import ContextPackageV2, PrepareContextRequest
+
+
+class RefreshCommands(Protocol):
+    def execute(self, workspace_id: str, paths: list[str] | None = None) -> dict: ...
+    def invalidate(self, workspace_id: str, target: str) -> dict: ...
+
+
+class ContextQueries(Protocol):
+    def prepare(self, request: PrepareContextRequest) -> ContextPackageV2: ...
+    def prepare_values(self, **values) -> dict: ...
+
+
+class WorkspaceCommands(Protocol):
+    def register(self, workspace_id: str, roots: list[str], initial_refresh: bool = False) -> dict: ...
+
+
+class RetrievalQueries(Protocol):
+    def plan(self, workspace_id: str, query: str, available_input_tokens: int, strategy_override: str = "") -> dict: ...
+    def retrieve(self, workspace_id: str, query: str, top_k: int = 12, graph_expand: bool = True, token_budget: int = 4_000) -> dict: ...
+    def stats(self, workspace_id: str) -> dict: ...
+    def snapshot_is_current(self, workspace_id: str) -> bool: ...
+
+
+class MemoryCommandsQueries(Protocol):
+    def save(self, workspace_id: str, key: str, value: str, **options) -> dict: ...
+    def search(self, workspace_id: str, query: str, **options) -> list[dict]: ...
+    def delete(self, workspace_id: str, key: str, mtype: str = "semantic") -> dict: ...
+    def list(self, workspace_id: str, mtype: str = "", limit: int = 30) -> list[str]: ...
+
+
+class HandoffCommandsQueries(Protocol):
+    def prepare(self, workspace_id: str, messages_json: str, **options) -> dict: ...
+    def restore(self, workspace_id: str, handoff_id: str) -> dict: ...
+    def list(self, workspace_id: str, limit: int = 30) -> list[dict]: ...
+    def delete(self, workspace_id: str, handoff_id: str) -> dict: ...
+    def purge(self) -> dict: ...
+
+
+class EccQueries(Protocol):
+    def status(self) -> dict: ...
+    def search(self, query: str, limit: int = 4) -> dict: ...

package/src/harness_context/application/refresh_service.py

@@ -0,0 +1,25 @@
+from harness_context.engine import ContextEngine
+from harness_context.storage import SnapshotStore
+
+
+class RefreshService:
+    def __init__(self, engine: ContextEngine, snapshots: SnapshotStore):
+        self.engine, self.snapshots = engine, snapshots
+
+    def execute(self, workspace_id: str, paths: list[str] | None = None) -> dict:
+        candidate_id = self.snapshots.begin_candidate(workspace_id)
+        try:
+            candidate, result = self.engine.build_workspace_snapshot(workspace_id, paths)
+            self.engine.prepare_bundle(workspace_id, _state=candidate, _record=True)
+            self.snapshots.validate_candidate(candidate_id, self.engine.export_state(workspace_id, candidate))
+            self.snapshots.promote_candidate(candidate_id)
+            self.engine.activate_snapshot(workspace_id, candidate)
+            return result
+        except Exception as error:
+            self.snapshots.fail_candidate(candidate_id, error)
+            raise
+
+    def invalidate(self, workspace_id: str, target: str) -> dict:
+        result = self.engine.invalidate(workspace_id, target)
+        self.snapshots.promote(self.engine.export_snapshot(workspace_id))
+        return result

package/src/harness_context/application/retrieval_service.py

@@ -0,0 +1,22 @@
+class RetrievalService:
+    def __init__(self, engine, ecc=None):
+        self.engine, self.ecc = engine, ecc
+
+    def plan(self, workspace_id, query, available_input_tokens, strategy_override=""):
+        with self.engine.snapshot_pin(workspace_id) as pin:
+            return self.engine.plan_context(workspace_id, query, available_input_tokens, strategy_override, pin.state)
+
+    def retrieve(self, workspace_id, query, top_k=12, graph_expand=True, token_budget=4_000):
+        with self.engine.snapshot_pin(workspace_id) as pin:
+            result = self.engine.retrieve_context(workspace_id, query, top_k, graph_expand, token_budget, pin.state)
+            result["snapshot_id"] = pin.snapshot_id
+            result["snapshot_version"] = pin.snapshot_version
+            return result
+
+    def stats(self, workspace_id):
+        result = self.engine.stats(workspace_id)
+        result["adapters"] = {"ecc": self.ecc.status() if self.ecc else {"enabled": False, "available": False, "read_only": True}}
+        return result
+
+    def snapshot_is_current(self, workspace_id):
+        return self.engine.snapshot_is_current(workspace_id)

package/src/harness_context/application/services.py

@@ -0,0 +1,4 @@
+from harness_context.application.context_service import ContextService
+from harness_context.application.refresh_service import RefreshService
+
+__all__ = ["ContextService", "RefreshService"]

package/src/harness_context/application/workspace_service.py

@@ -0,0 +1,18 @@
+from pathlib import Path
+
+
+class WorkspaceService:
+    def __init__(self, engine, refresh, default_workspace_id):
+        self.engine, self.refresh, self.default_workspace_id = engine, refresh, default_workspace_id
+
+    def register(self, workspace_id, roots, initial_refresh=False):
+        if workspace_id != self.default_workspace_id:
+            raise ValueError("one runtime serves exactly one workspace")
+        policy = self.engine.registry.get(self.default_workspace_id)
+        requested = tuple(sorted(str(Path(root).resolve()) for root in roots))
+        if requested != policy.roots:
+            raise ValueError("workspace roots cannot change after runtime startup")
+        result = {"workspace_id": workspace_id, "roots": list(policy.roots), "status": self.engine.stats(workspace_id)["status"]}
+        if initial_refresh:
+            result["refresh"] = self.refresh.execute(workspace_id)
+        return result

package/src/harness_context/bootstrap.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from compact.handoff import ConversationHandoffStore
+from harness_context.adapters.ecc import EccMemoryReader, detect_ecc
+from harness_context.application.container import ApplicationContainer
+from harness_context.application.ecc_service import EccService
+from harness_context.application.handoff_service import HandoffService
+from harness_context.application.memory_service import MemoryService
+from harness_context.application.retrieval_service import RetrievalService
+from harness_context.application.services import ContextService, RefreshService
+from harness_context.application.workspace_service import WorkspaceService
+from harness_context.engine import ContextEngine
+from harness_context.paths import workspace_state_dir
+from harness_context.storage import SnapshotStore
+from harness_context.workspace.identity import workspace_identity
+from memory.episodic import MemoryStore
+
+
+def build_container(root: str | Path, workspace_id: str = "", *, ecc_enabled: bool = False, ecc_allow_user_scope: bool = False) -> ApplicationContainer:
+    canonical = Path(root).expanduser().resolve(strict=True)
+    identity = workspace_id or workspace_identity(canonical)
+    engine = ContextEngine()
+    engine.register_workspace(identity, [str(canonical)])
+    snapshots = SnapshotStore(canonical)
+    snapshots.prepare()
+    active = snapshots.load_active(identity)
+    if active:
+        engine.load_snapshot(active)
+    data_dir = workspace_state_dir(canonical)
+    memory = MemoryStore(str(data_dir / "memory.sqlite3"))
+    handoffs = ConversationHandoffStore(str(data_dir / "handoffs.sqlite3"))
+    ecc = EccMemoryReader(detect_ecc(canonical, allow_user_scope=ecc_allow_user_scope)) if ecc_enabled else None
+    refresh = RefreshService(engine, snapshots)
+    return ApplicationContainer(
+        engine=engine, snapshots=snapshots,
+        refresh=refresh,
+        context=ContextService(engine, memory, handoffs, ecc),
+        memory=memory, handoffs=handoffs,
+        ecc=ecc,
+        workspace=WorkspaceService(engine, refresh, identity),
+        retrieval=RetrievalService(engine, ecc),
+        memories=MemoryService(memory),
+        handoff=HandoffService(handoffs),
+        ecc_queries=EccService(ecc),
+    )

package/src/harness_context/branding.py

@@ -0,0 +1,16 @@
+"""Public CTXORA product metadata."""
+
+BRAND_NAME = "CTXORA"
+PRODUCT_NAME = "CTXORA Engine"
+MCP_SERVER_NAME = "CTXORA MCP"
+CLI_NAME = "ctxora"
+MCP_CLI_NAME = "ctxora-mcp"
+DISTRIBUTION_NAME = "ctxora-engine"
+MCP_SERVER_KEY = "ctxora"
+FREE_PLAN_NAME = "CTXORA Free"
+PAID_PLAN_NAME = "CTXORA Pro"
+PAID_PLAN_STATUS = "waitlist"
+TAGLINE = "Index once. Ground every agent."
+DESCRIPTION = "Local-first context engine for coding agents."
+WORKSPACE_DIR_NAME = ".ctxora"
+LEGACY_WORKSPACE_DIR_NAME = ".harness"

package/src/harness_context/cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line transport."""

package/src/harness_context/cli/app.py

@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import signal
+import subprocess
+import sys
+from dataclasses import asdict
+from pathlib import Path
+
+from harness_context.adapters.clients import PROFILES
+from harness_context.api.v2 import PrepareContextRequest
+from harness_context.branding import CLI_NAME, PAID_PLAN_NAME, PAID_PLAN_STATUS
+from harness_context.cli.exit_codes import error_report, exit_code_for
+from harness_context.free_tools import (
+    context_score,
+    explain_context,
+    instruction_document,
+    repository_map,
+    write_instruction,
+)
+from harness_context.installer import ClientInstaller
+from harness_context.paths import workspace_data_dir, workspace_data_dirs, workspace_runtime_dir
+from harness_context.runtime import HarnessRuntime
+
+
+def _runtime(args) -> HarnessRuntime:
+    if args.host and args.host not in {"127.0.0.1", "localhost", "::1"} and not args.allow_external:
+        raise SystemExit("external HTTP binding requires --allow-external")
+    return HarnessRuntime.for_workspace(
+        args.workspace, args.transport, args.host, args.port, args.watch,
+        args.ecc, args.ecc_user_scope,
+    )
+
+
+def _print(payload: dict) -> None:
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+def _pid_path(workspace: str) -> Path:
+    return workspace_runtime_dir(workspace) / "run.pid"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog=CLI_NAME)
+    commands = parser.add_subparsers(dest="command", required=True)
+    for name in (
+        "setup", "install", "profile", "run", "start", "index", "query", "explain",
+        "context-score", "repo-map", "generate-agents-md",
+        "generate-copilot-instructions", "generate-cursor-rules", "pro", "inspect",
+        "status", "stop", "doctor", "repair", "register", "export", "uninstall", "ci",
+    ):
+        command = commands.add_parser(name)
+        command.add_argument("--workspace", default=".")
+        command.add_argument("--transport", choices=("stdio", "streamable-http"))
+        command.add_argument("--host")
+        command.add_argument("--port", type=int)
+        command.add_argument("--allow-external", action="store_true")
+        command.add_argument("--watch", action="store_true", default=None)
+        command.add_argument("--ecc", action="store_true", default=None)
+        command.add_argument("--ecc-user-scope", action="store_true", default=None)
+        if name in {"query", "explain"}:
+            command.add_argument("query")
+            command.add_argument("--tokens", type=int, default=8_000)
+        if name in {"generate-agents-md", "generate-copilot-instructions", "generate-cursor-rules"}:
+            command.add_argument("--output")
+            command.add_argument("--force", action="store_true")
+        if name == "inspect":
+            command.add_argument("target", choices=("workspace", "snapshot", "bundle", "ecc"), default="workspace", nargs="?")
+        if name == "index":
+            command.add_argument("--incremental", action="store_true")
+        if name == "ci":
+            command.add_argument("--base", default="origin/main")
+            command.add_argument("--head", default="HEAD")
+        if name == "export":
+            command.add_argument("--output", required=True)
+        if name in {"install", "uninstall"}:
+            command.add_argument("--profile", choices=tuple(PROFILES))
+            command.add_argument("--client-config")
+            command.add_argument("--dry-run", action="store_true")
+        if name == "uninstall":
+            command.add_argument("--delete-data", action="store_true")
+    return parser
+
+
+def _main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    root = Path(args.workspace).expanduser().resolve(strict=True)
+    if args.command == "setup":
+        config = workspace_data_dir(root) / "config.toml"
+        config.parent.mkdir(parents=True, exist_ok=True)
+        if not config.exists():
+            config.write_text('transport = "stdio"\nstartup_policy = "block_until_ready"\nwatch = false\necc_enabled = false\necc_allow_user_scope = false\n', "utf-8")
+        _print({"status": "configured", "config": str(config)})
+        return 0
+    if args.command == "profile":
+        _print({"profiles": [asdict(profile) | {"default_config": str(profile.default_config)} for profile in PROFILES.values()]})
+        return 0
+    if args.command == "pro":
+        _print({
+            "plan": PAID_PLAN_NAME,
+            "status": PAID_PLAN_STATUS,
+            "features": ["managed automation", "private workflows", "team context"],
+        })
+        return 0
+    if args.command == "install":
+        if not args.profile:
+            raise SystemExit("install requires --profile")
+        plan = ClientInstaller(root).install(args.profile, args.client_config, args.dry_run)
+        _print({"status": "planned" if args.dry_run else "installed", "plan": plan.to_dict()})
+        return 0
+    if args.command == "register":
+        runtime = _runtime(args)
+        _print({"workspace_id": runtime.config.workspace_id, "root": str(root), "status": "registered"})
+        return 0
+    if args.command == "uninstall":
+        if args.profile:
+            plan = ClientInstaller(root).uninstall(args.profile, args.client_config, args.dry_run, args.delete_data)
+            _print({"status": "planned" if args.dry_run else "uninstalled", "plan": plan.to_dict(), "data_deleted": args.delete_data})
+            return 0
+        if args.delete_data:
+            for owned in workspace_data_dirs(root):
+                shutil.rmtree(owned, ignore_errors=True)
+        _print({"status": "uninstalled", "data_deleted": args.delete_data})
+        return 0
+    if args.command == "start":
+        if args.host and args.host not in {"127.0.0.1", "localhost", "::1"} and not args.allow_external:
+            raise SystemExit("external HTTP binding requires --allow-external")
+        pid_path = _pid_path(str(root))
+        pid_path.parent.mkdir(parents=True, exist_ok=True)
+        log = (pid_path.parent / "runtime.log").open("a", encoding="utf-8")
+        command = [
+            sys.executable, "-m", "harness_context.cli.app", "run",
+            "--workspace", str(root), "--transport", "streamable-http",
+            "--host", args.host or "127.0.0.1", "--port", str(args.port or 8765),
+            "--watch",
+        ]
+        if args.ecc:
+            command.append("--ecc")
+        if args.ecc_user_scope:
+            command.append("--ecc-user-scope")
+        process = subprocess.Popen(command, stdout=log, stderr=log, start_new_session=True)
+        pid_path.write_text(str(process.pid), "utf-8")
+        _print({"status": "started", "pid": process.pid})
+        return 0
+    if args.command in {"status", "stop"}:
+        pid_path = _pid_path(str(root))
+        pid = int(pid_path.read_text("utf-8")) if pid_path.exists() else 0
+        running = False
+        if pid:
+            try:
+                os.kill(pid, 0)
+                running = True
+            except OSError:
+                pass
+        if args.command == "stop" and running:
+            os.kill(pid, signal.SIGTERM)
+            pid_path.unlink(missing_ok=True)
+            running = False
+        _print({"status": "running" if running else "stopped", "pid": pid or None})
+        return 0
+    runtime = _runtime(args)
+    startup = runtime.startup()
+    if args.command == "run":
+        runtime.run()
+        return 0
+    if args.command == "index":
+        _print(startup)
+        return 0
+    if args.command == "repair":
+        repaired = runtime.container.refresh.execute(runtime.config.workspace_id)
+        _print({"status": "repaired", "workspace": str(root), "runtime": repaired})
+        return 0
+    if args.command == "doctor":
+        _print(runtime.health_report())
+        return 0
+    if args.command == "ci":
+        changed = subprocess.run(
+            ["git", "diff", "--name-only", args.base, args.head],
+            cwd=root, check=True, capture_output=True, text=True,
+        ).stdout.splitlines()
+        paths = [str(root / path) for path in changed]
+        result = runtime.container.refresh.execute(runtime.config.workspace_id, paths) if paths else startup
+        _print({"status": "ok", "changed_files": changed, "refresh": result})
+        return 0
+    assert runtime.container is not None
+    if args.command in {"query", "explain"}:
+        request = PrepareContextRequest(runtime.config.workspace_id, args.query, args.tokens)
+        package = runtime.container.context.prepare(request).to_dict()
+        _print(package if args.command == "query" else explain_context(args.query, package, root))
+        return 0
+    snapshot = runtime.container.engine.export_snapshot(runtime.config.workspace_id)
+    if args.command == "context-score":
+        _print(context_score(snapshot, root))
+        return 0
+    if args.command == "repo-map":
+        _print(repository_map(snapshot, root))
+        return 0
+    generators = {
+        "generate-agents-md": (root / "AGENTS.md", "AGENTS.md"),
+        "generate-copilot-instructions": (root / ".github" / "copilot-instructions.md", "GitHub Copilot"),
+        "generate-cursor-rules": (root / ".cursor" / "rules" / "ctxora.mdc", "Cursor"),
+    }
+    if args.command in generators:
+        default_output, target = generators[args.command]
+        output = Path(args.output).expanduser().resolve() if args.output else default_output
+        write_instruction(output, instruction_document(snapshot, root, target), args.force)
+        _print({"status": "generated", "target": target, "output": str(output), "snapshot_id": snapshot["snapshot_id"]})
+        return 0
+    stats = runtime.container.engine.stats(runtime.config.workspace_id)
+    if args.command == "export":
+        output = Path(args.output).expanduser().resolve()
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(json.dumps(runtime.container.engine.export_snapshot(runtime.config.workspace_id), ensure_ascii=False, indent=2), "utf-8")
+        _print({"status": "exported", "output": str(output), "snapshot_id": stats["snapshot_id"]})
+        return 0
+    if args.target == "bundle":
+        _print(runtime.container.engine.prepare_bundle(runtime.config.workspace_id))
+    elif args.target == "ecc":
+        _print(runtime.container.ecc.status() if runtime.container.ecc else {"available": False, "enabled": False, "read_only": True})
+    else:
+        _print(stats)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        return _main(argv)
+    except SystemExit:
+        raise
+    except Exception as error:  # noqa: BLE001 - CLI boundary maps all failures to stable exits.
+        print(json.dumps(error_report(error), sort_keys=True), file=sys.stderr)
+        return int(exit_code_for(error))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/harness_context/cli/exit_codes.py

@@ -0,0 +1,25 @@
+from enum import IntEnum
+
+
+class ExitCode(IntEnum):
+    OK = 0
+    USAGE = 2
+    CONFIGURATION = 3
+    NOT_READY = 4
+    TEMPORARY_FAILURE = 5
+    INTERNAL_ERROR = 70
+
+
+def exit_code_for(error: BaseException) -> ExitCode:
+    if isinstance(error, (FileNotFoundError, PermissionError, ValueError)):
+        return ExitCode.CONFIGURATION
+    if getattr(error, "code", "") in {"workspace_not_ready", "stale_snapshot"}:
+        return ExitCode.NOT_READY
+    if isinstance(error, (TimeoutError, ConnectionError)):
+        return ExitCode.TEMPORARY_FAILURE
+    return ExitCode.INTERNAL_ERROR
+
+
+def error_report(error: BaseException) -> dict[str, object]:
+    code = exit_code_for(error)
+    return {"status": "error", "exit_code": int(code), "error": code.name.lower()}

package/src/harness_context/domain/__init__.py

@@ -0,0 +1,9 @@
+from harness_context.domain.cag import CAGStore
+from harness_context.domain.chunking import bounded_windows, stable_chunk_id
+from harness_context.domain.planning import ContextPlanner
+from harness_context.domain.retrieval import CoveragePolicy, GraphExpander, RankFusion, Selector
+
+__all__ = [
+    "CAGStore", "ContextPlanner", "CoveragePolicy", "GraphExpander",
+    "RankFusion", "Selector", "bounded_windows", "stable_chunk_id",
+]

package/src/harness_context/domain/cag.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from collections.abc import Sequence
+
+from harness_context.domain.planning import ContextPlanner
+from harness_context.schemas import ContextItem
+
+
+class CAGStore:
+    def build(self, workspace_id: str, items: Sequence[ContextItem], version: int, ttl_seconds: int) -> dict:
+        stable = [item for item in items if ContextPlanner.is_stable(item)]
+        sources = [{"path": item.path, "content_hash": item.content_hash, "start_line": item.start_line, "end_line": item.end_line} for item in sorted(stable, key=lambda item: (item.path, item.start_line))]
+        bundle_id = "sha256:" + hashlib.sha256(json.dumps(sources, sort_keys=True).encode()).hexdigest()
+        now = time.time()
+        return {"bundle_id": bundle_id, "workspace_id": workspace_id, "version": version, "bundle_type": "project_core", "model_family": "provider-neutral", "token_count": sum(item.tokens for item in stable), "created_at": now, "expires_at": now + ttl_seconds, "sources": sources, "items": [item.to_dict() for item in stable]}

package/src/harness_context/domain/chunking.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Iterator
+from pathlib import Path
+
+
+def stable_chunk_id(workspace_id: str, path: Path, kind: str, symbol: str, start: int, end: int, content_hash: str) -> str:
+    identity = f"{workspace_id}\0{path}\0{kind}\0{symbol}\0{start}\0{end}\0{content_hash}"
+    return hashlib.sha256(identity.encode()).hexdigest()
+
+
+def bounded_windows(lines: list[str], window: int = 160, overlap: int = 20) -> Iterator[tuple[int, int, str]]:
+    if window <= 0 or overlap < 0 or overlap >= window:
+        raise ValueError("window must be positive and overlap smaller than window")
+    for offset in range(0, max(1, len(lines)), window - overlap):
+        yield offset + 1, min(offset + window, len(lines)), "\n".join(lines[offset:offset + window])

package/src/harness_context/domain/planning.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+
+from harness_context.schemas import ContextItem
+
+
+class ContextPlanner:
+    STABLE_FILES = {"AGENTS.md", "CLAUDE.md", "README.md", "pyproject.toml"}
+
+    @classmethod
+    def is_stable(cls, item: ContextItem) -> bool:
+        return Path(item.path).name in cls.STABLE_FILES or "/docs/" in item.path
+
+    def plan(self, workspace_id: str, query: str, available: int, items: Sequence[ContextItem], override: str = "") -> dict:
+        corpus = sum(item.tokens for item in items)
+        stable = sum(item.tokens for item in items if self.is_stable(item))
+        repo_wide = any(word in query.casefold() for word in ("architecture", "kiến trúc", "repo", "toàn bộ", "cross-module"))
+        if override:
+            strategy, reason, confidence = override, "Caller override requested.", 1.0
+        elif corpus <= available * 0.7:
+            strategy, reason, confidence = "long_context", "Authorized corpus fits comfortably in the supplied budget.", 0.84
+        elif stable and repo_wide:
+            strategy, reason, confidence = "hybrid_cag_rag", "Reusable stable core plus fresh cross-file evidence is required.", 0.88
+        elif repo_wide:
+            strategy, reason, confidence = "graph_augmented", "Cross-module query benefits from parsed dependency expansion.", 0.78
+        else:
+            strategy, reason, confidence = "hybrid_rag", "Narrow task over a larger changing corpus.", 0.82
+        return {"workspace_id": workspace_id, "strategy": strategy, "reason": reason, "confidence": confidence, "estimated_context_tokens": min(corpus, available), "rag_budget_tokens": min(5000, available), "graph_expand": strategy in {"hybrid_cag_rag", "graph_augmented"}, "alternatives": ["hybrid_rag"] if strategy != "hybrid_rag" else ["long_context"], "override_allowed": True}

package/src/harness_context/domain/ports.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Protocol
+
+from harness_context.schemas import ContextItem
+
+
+class FileScanner(Protocol):
+    def scan(self, workspace_id: str, requested: Sequence[str]) -> list[Path]: ...
+
+
+class ChunkParser(Protocol):
+    def parse(self, workspace_id: str, path: Path) -> list[ContextItem]: ...
+
+
+class SearchIndex(Protocol):
+    def rebuild(self, items: Sequence[ContextItem]) -> None: ...
+    def scores(self, query: str, items: Sequence[ContextItem]) -> list[float]: ...
+
+
+class DependencyGraph(Protocol):
+    def build(self, items: Sequence[ContextItem]) -> dict[str, set[str]]: ...