engineering-argument-language 3.2.3__py3-none-any.whl

eal/catalogue.py

@@ -0,0 +1,384 @@
+"""Persistent developer catalogue of EAL sources and their stored run history.
+
+An entry has a stable developer name and workspace path. Each validated file
+revision is retained by its exact source digest. Collection and assessment
+records remain owned by RunStore; this catalogue indexes their identities and
+never turns a historical result into a fresh observation.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import stat
+from pathlib import Path
+from typing import Any
+
+from .evaluator import canonical_digest
+from .runtime import ReasoningService, bounded_path
+from .store import utc_now
+
+
+_ENTRY_ID = re.compile(r"[A-Za-z_][A-Za-z_0-9.-]{0,127}\Z")
+_DIGEST = re.compile(r"[0-9a-f]{64}\Z")
+_MAX_CONTEXT_BYTES = 8192
+_MAX_CLAIMS = 256
+_MAX_TREE_FILES = 512
+_MAX_TREE_ENTRIES = 8192
+_MAX_TREE_DEPTH = 16
+
+
+def _json(value: Any) -> str:
+    try:
+        encoded = json.dumps(value, sort_keys=True, separators=(",", ":"),
+                             ensure_ascii=False, allow_nan=False)
+        encoded.encode("utf-8")
+        return encoded
+    except (TypeError, ValueError, UnicodeError, RecursionError) as exc:
+        raise ValueError("Catalogue values must be finite UTF-8 JSON") from exc
+
+
+def _limit(value: int) -> int:
+    if type(value) is not int or not 1 <= value <= 100:
+        raise ValueError("limit must be an integer from 1 through 100")
+    return value
+
+
+class WorkspaceKnowledgeCatalogue:
+    """Named workspace sources with immutable revisions and indexed run lookup."""
+
+    def __init__(self, service: ReasoningService):
+        self.service = service
+        self.workspace = service.workspace
+        self.store = service.store
+        with self.store._connect() as connection:
+            connection.execute(
+                "CREATE TABLE IF NOT EXISTS catalogue_entries ("
+                "entry_id TEXT PRIMARY KEY, path TEXT NOT NULL UNIQUE, label TEXT NOT NULL, "
+                "context_json TEXT NOT NULL, selected_claims_json TEXT, "
+                "current_digest TEXT NOT NULL, current_method_fingerprint TEXT NOT NULL, "
+                "created_at TEXT NOT NULL, updated_at TEXT NOT NULL)"
+            )
+            connection.execute(
+                "CREATE TABLE IF NOT EXISTS catalogue_revisions ("
+                "entry_id TEXT NOT NULL, source_digest TEXT NOT NULL, source TEXT NOT NULL, "
+                "method_registry_fingerprint TEXT NOT NULL, claims_json TEXT NOT NULL, "
+                "claim_metadata_json TEXT NOT NULL, registered_at TEXT NOT NULL, "
+                "PRIMARY KEY(entry_id, source_digest, method_registry_fingerprint), "
+                "FOREIGN KEY(entry_id) REFERENCES catalogue_entries(entry_id))"
+            )
+            # Existing collections and assessments become discoverable without
+            # copying potentially large observation values into catalogue rows.
+            connection.execute(
+                "CREATE INDEX IF NOT EXISTS catalogue_run_source ON records "
+                "(kind, json_extract(payload, '$.source_digest'))"
+            )
+
+    def _normal_path(self, path: str) -> str:
+        if not isinstance(path, str) or not path or Path(path).is_absolute() or not path.endswith(".eal"):
+            raise ValueError("path must be a workspace-relative .eal file")
+        resolved = bounded_path(self.workspace, path)
+        return resolved.relative_to(self.workspace).as_posix()
+
+    def _read_source(self, relative_path: str) -> str:
+        path = bounded_path(self.workspace, relative_path)
+        if not stat.S_ISREG(path.stat().st_mode):
+            raise ValueError("Registered source must be a regular EAL file")
+        with path.open("rb") as stream:
+            data = stream.read(self.service.limits.source_bytes + 1)
+        if len(data) > self.service.limits.source_bytes:
+            raise ValueError("Registered source exceeds the EAL source limit")
+        try:
+            return data.decode("utf-8")
+        except UnicodeError as exc:
+            raise ValueError("Registered source must be UTF-8") from exc
+
+    def _metadata(self, source: str, selected_claims: tuple[str, ...] | None) -> tuple[str, dict[str, dict]]:
+        program = self.service.parse(source)
+        names = tuple(program.claims) if selected_claims is None else selected_claims
+        missing = set(names) - set(program.claims)
+        if missing:
+            raise ValueError(f"Selected claims are absent from the source: {', '.join(sorted(missing))}")
+        if not names or len(names) > _MAX_CLAIMS:
+            raise ValueError(f"Register one to {_MAX_CLAIMS} selected claims")
+        details = {name: {"statement": program.claims[name].statement,
+                          "environment": program.claims[name].environment} for name in names}
+        return program.source_digest, details
+
+    def _validate_revision(self, source: str, selected_claims: tuple[str, ...] | None) -> tuple[str, str, dict[str, dict]]:
+        validation = self.service.validate(source)
+        if not validation["valid"]:
+            raise ValueError("Registered source failed EAL validation: " +
+                             "; ".join(item["message"] for item in validation["diagnostics"][:5]))
+        source_digest, metadata = self._metadata(source, selected_claims)
+        if source_digest != validation["source_digest"]:
+            raise ValueError("Source changed during validation")
+        return source_digest, validation["method_registry_fingerprint"], metadata
+
+    def register(self, path: str, *, entry_id: str | None = None,
+                 context: dict[str, Any] | None = None,
+                 claims: list[str] | tuple[str, ...] | None = None,
+                 label: str | None = None) -> dict[str, Any]:
+        """Register a trusted path; repeated calls retain its stable entry ID."""
+        relative = self._normal_path(path)
+        identifier = relative if entry_id is None else entry_id
+        if not isinstance(identifier, str) or not identifier or len(identifier) > 256:
+            raise ValueError("entry_id must be a bounded nonempty string")
+        try:
+            identifier.encode("utf-8")
+        except UnicodeError as exc:
+            raise ValueError("entry_id must be valid UTF-8") from exc
+        if entry_id is not None and not _ENTRY_ID.fullmatch(entry_id):
+            raise ValueError("Explicit entry_id must be a simple developer name")
+        if label is None:
+            label = Path(relative).stem
+        if not isinstance(label, str) or not 1 <= len(label) <= 128 or not label.strip():
+            raise ValueError("label must contain one to 128 characters")
+        try:
+            label.encode("utf-8")
+        except UnicodeError as exc:
+            raise ValueError("label must be valid UTF-8") from exc
+        if context is None:
+            context = {}
+        if not isinstance(context, dict):
+            raise ValueError("context must be a JSON object")
+        context_json = _json(context)
+        if len(context_json.encode("utf-8")) > _MAX_CONTEXT_BYTES:
+            raise ValueError("context exceeds 8192 UTF-8 bytes")
+        if claims is not None:
+            if (not isinstance(claims, (list, tuple)) or not claims
+                    or len(claims) > _MAX_CLAIMS or any(not isinstance(name, str) for name in claims)
+                    or len(set(claims)) != len(claims)):
+                raise ValueError("claims must contain unique claim identifiers")
+            selected = tuple(claims)
+        else:
+            selected = None
+        selected_json = None if selected is None else _json(selected)
+        source = self._read_source(relative)
+        digest, method_fingerprint, metadata = self._validate_revision(source, selected)
+        now = utc_now()
+        with self.store._connect() as connection:
+            connection.execute("BEGIN IMMEDIATE")
+            row = connection.execute(
+                "SELECT path, label, context_json, selected_claims_json FROM catalogue_entries "
+                "WHERE entry_id = ?", (identifier,)
+            ).fetchone()
+            expected = (relative, label, context_json, selected_json)
+            if row is not None and row != expected:
+                raise ValueError("Registered entry metadata differs; use another developer entry_id")
+            path_owner = connection.execute(
+                "SELECT entry_id FROM catalogue_entries WHERE path = ?", (relative,)
+            ).fetchone()
+            if path_owner is not None and path_owner[0] != identifier:
+                raise ValueError("Source path is already registered under another entry_id")
+            if row is None:
+                connection.execute(
+                    "INSERT INTO catalogue_entries VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                    (identifier, relative, label, context_json, selected_json,
+                     digest, method_fingerprint, now, now),
+                )
+            else:
+                connection.execute(
+                    "UPDATE catalogue_entries SET current_digest = ?, "
+                    "current_method_fingerprint = ?, updated_at = ? "
+                    "WHERE entry_id = ? AND (current_digest != ? OR current_method_fingerprint != ?)",
+                    (digest, method_fingerprint, now, identifier, digest, method_fingerprint),
+                )
+            connection.execute(
+                "INSERT OR IGNORE INTO catalogue_revisions VALUES (?, ?, ?, ?, ?, ?, ?)",
+                (identifier, digest, source, method_fingerprint,
+                 _json(tuple(metadata)), _json(metadata), now),
+            )
+        return self.get(identifier, include_source=False, refresh=False)
+
+    def register_tree(self, directory: str = ".", *, context: dict[str, Any] | None = None,
+                      limit: int = _MAX_TREE_FILES) -> dict[str, Any]:
+        """Discover bounded workspace files and report every rejected source."""
+        if type(limit) is not int or not 1 <= limit <= _MAX_TREE_FILES:
+            raise ValueError(f"limit must be an integer from 1 through {_MAX_TREE_FILES}")
+        if not isinstance(directory, str) or Path(directory).is_absolute():
+            raise ValueError("directory must be workspace-relative")
+        root = bounded_path(self.workspace, directory)
+        if not root.is_dir():
+            raise ValueError("directory must resolve to a workspace directory")
+        paths = []
+        visited = 0
+
+        def traversal_error(error: OSError) -> None:
+            raise error
+
+        for base, directories, files in os.walk(root, followlinks=False,
+                                                 onerror=traversal_error):
+            directories.sort()
+            files.sort()
+            visited += len(directories) + len(files)
+            if visited > _MAX_TREE_ENTRIES:
+                raise ValueError("Directory exceeds the discovery scan limit")
+            if len(Path(base).relative_to(root).parts) >= _MAX_TREE_DEPTH and directories:
+                raise ValueError("Directory exceeds the discovery depth limit")
+            for filename in files:
+                if filename.endswith(".eal"):
+                    paths.append(Path(base) / filename)
+                    if len(paths) > limit:
+                        raise ValueError("Directory contains more EAL files than the discovery limit")
+        registered, rejected = [], []
+        for path in sorted(paths):
+            relative = path.relative_to(self.workspace).as_posix()
+            try:
+                registered.append(self.register(relative, context=context))
+            except (OSError, ValueError) as exc:
+                rejected.append({"path": relative, "reason": str(exc)})
+        return {"registered": registered, "rejected": rejected}
+
+    def _entry(self, entry_id: str, source_digest: str | None = None,
+               *, method_fingerprint: str | None = None,
+               include_source: bool = False) -> dict[str, Any]:
+        with self.store._connect() as connection:
+            row = connection.execute(
+                "SELECT e.entry_id, e.path, e.label, e.context_json, e.selected_claims_json, "
+                "e.current_digest, e.current_method_fingerprint, "
+                "r.source_digest, r.source, r.method_registry_fingerprint, "
+                "r.claims_json, r.claim_metadata_json, r.registered_at "
+                "FROM catalogue_entries e JOIN catalogue_revisions r "
+                "ON r.entry_id = e.entry_id AND r.source_digest = COALESCE(?, e.current_digest) "
+                "WHERE e.entry_id = ? AND (? IS NULL OR r.method_registry_fingerprint = ?) "
+                "ORDER BY (r.source_digest = e.current_digest AND "
+                "r.method_registry_fingerprint = e.current_method_fingerprint) DESC, "
+                "r.registered_at DESC LIMIT 1",
+                (source_digest, entry_id, method_fingerprint, method_fingerprint),
+            ).fetchone()
+        if row is None:
+            raise KeyError(f"Unknown catalogue entry or source revision {entry_id!r}")
+        (identifier, path, label, context_json, selected_claims_json,
+         current_digest, current_method_fingerprint, digest, source,
+         method_fingerprint, claims_json, metadata_json, registered_at) = row
+        result = {"entry_id": identifier, "path": path, "label": label,
+                  "source_digest": digest,
+                  "current": digest == current_digest and method_fingerprint == current_method_fingerprint,
+                  "method_registry_fingerprint": method_fingerprint,
+                  "context": json.loads(context_json), "claims": json.loads(claims_json),
+                  "selected_claims": None if selected_claims_json is None else json.loads(selected_claims_json),
+                  "claim_metadata": json.loads(metadata_json), "registered_at": registered_at}
+        if include_source:
+            result["source"] = source
+        return result
+
+    def get(self, entry_id: str, *, include_source: bool = False,
+            refresh: bool = True) -> dict[str, Any]:
+        """Return the latest validated revision, incorporating a changed file."""
+        if refresh:
+            current = self._entry(entry_id)
+            self.register(current["path"], entry_id=entry_id, context=current["context"],
+                          claims=current["selected_claims"], label=current["label"])
+        return self._entry(entry_id, include_source=include_source)
+
+    def get_revision(self, entry_id: str, source_digest: str, *,
+                     method_registry_fingerprint: str | None = None,
+                     include_source: bool = False) -> dict[str, Any]:
+        if not isinstance(source_digest, str) or _DIGEST.fullmatch(source_digest) is None:
+            raise ValueError("source_digest must be a lowercase SHA-256 digest")
+        if (method_registry_fingerprint is not None and
+                (not isinstance(method_registry_fingerprint, str) or
+                 _DIGEST.fullmatch(method_registry_fingerprint) is None)):
+            raise ValueError("method_registry_fingerprint must be a lowercase SHA-256 digest")
+        return self._entry(entry_id, source_digest,
+                           method_fingerprint=method_registry_fingerprint,
+                           include_source=include_source)
+
+    def revisions(self, entry_id: str, *, limit: int = 50) -> list[dict[str, Any]]:
+        """List immutable source and method identities, including old revisions."""
+        _limit(limit)
+        with self.store._connect() as connection:
+            row = connection.execute(
+                "SELECT current_digest, current_method_fingerprint FROM catalogue_entries "
+                "WHERE entry_id = ?", (entry_id,),
+            ).fetchone()
+            if row is None:
+                raise KeyError(f"Unknown catalogue entry {entry_id!r}")
+            revisions = connection.execute(
+                "SELECT source_digest, method_registry_fingerprint, registered_at, claims_json "
+                "FROM catalogue_revisions WHERE entry_id = ? "
+                "ORDER BY registered_at DESC, source_digest LIMIT ?", (entry_id, limit),
+            ).fetchall()
+        return [{"source_digest": digest, "method_registry_fingerprint": fingerprint,
+                 "registered_at": registered_at, "claims": json.loads(claims),
+                 "current": (digest, fingerprint) == row}
+                for digest, fingerprint, registered_at, claims in revisions]
+
+    def list(self, *, limit: int = 50, offset: int = 0) -> list[dict[str, Any]]:
+        _limit(limit)
+        if type(offset) is not int or not 0 <= offset <= 10_000:
+            raise ValueError("offset must be an integer from 0 through 10000")
+        with self.store._connect() as connection:
+            identifiers = [row[0] for row in connection.execute(
+                "SELECT entry_id FROM catalogue_entries ORDER BY path LIMIT ? OFFSET ?",
+                (limit, offset),
+            )]
+        return [self._entry(identifier) for identifier in identifiers]
+
+    def find(self, query: str | None = None, *, claim: str | None = None,
+             context: dict[str, Any] | None = None, path: str | None = None,
+             limit: int = 50) -> list[dict[str, Any]]:
+        """Advisory metadata search; execution still requires an exact entry ID."""
+        _limit(limit)
+        if query is not None and (not isinstance(query, str) or len(query) > 256):
+            raise ValueError("query must be at most 256 characters")
+        if claim is not None and not isinstance(claim, str):
+            raise ValueError("claim must be a string")
+        if path is not None and not isinstance(path, str):
+            raise ValueError("path must be a string")
+        context_json = None
+        if context is not None:
+            if not isinstance(context, dict):
+                raise ValueError("context must be a JSON object")
+            context_json = _json(context)
+        with self.store._connect() as connection:
+            rows = connection.execute(
+                "SELECT e.entry_id FROM catalogue_entries e JOIN catalogue_revisions r "
+                "ON r.entry_id = e.entry_id AND r.source_digest = e.current_digest "
+                "AND r.method_registry_fingerprint = e.current_method_fingerprint "
+                "WHERE (? IS NULL OR instr(lower(e.path || ' ' || e.label || ' ' || "
+                "r.claim_metadata_json), lower(?)) > 0) "
+                "AND (? IS NULL OR EXISTS (SELECT 1 FROM json_each(r.claims_json) WHERE value = ?)) "
+                "AND (? IS NULL OR e.context_json = ?) AND (? IS NULL OR e.path = ?) "
+                "ORDER BY e.path LIMIT ?",
+                (query, query, claim, claim, context_json, context_json, path, path, limit),
+            ).fetchall()
+        return [self._entry(row[0]) for row in rows]
+
+    def runs(self, entry_id: str, *, source_digest: str | None = None,
+             limit: int = 50) -> dict[str, Any]:
+        """Find exact-source, exact-context historical runs without replaying them."""
+        _limit(limit)
+        entry = (self.get(entry_id) if source_digest is None else
+                 self.get_revision(entry_id, source_digest))
+        digest = entry["source_digest"]
+        context_json = _json(entry["context"])
+        context_fingerprint = canonical_digest(entry["context"])
+        with self.store._connect() as connection:
+            collections = connection.execute(
+                "SELECT id, created_at, payload FROM records "
+                "WHERE kind = 'collection' AND json_extract(payload, '$.source_digest') = ? "
+                "AND json_extract(payload, '$.context') = ? ORDER BY rowid DESC LIMIT ?",
+                (digest, context_json, limit),
+            ).fetchall()
+            assessments = connection.execute(
+                "SELECT id, created_at, payload FROM records "
+                "WHERE kind = 'assessment' AND json_extract(payload, '$.source_digest') = ? "
+                "AND json_extract(payload, '$.context_fingerprint') = ? "
+                "ORDER BY rowid DESC LIMIT ?",
+                (digest, context_fingerprint, limit),
+            ).fetchall()
+        return {"entry_id": entry_id, "source_digest": digest,
+                "collections": [{"collection_id": record_id, "created_at": created_at,
+                                 "record_count": len(json.loads(payload).get("records", {}))}
+                                for record_id, created_at, payload in collections],
+                "assessments": [{"assessment_id": record_id,
+                                 "collection_id": item.get("collection_id"),
+                                 "created_at": created_at, "assessed_at": item.get("assessed_at"),
+                                 "method_registry_fingerprint": item.get("method_registry_fingerprint"),
+                                 "claim_statuses": {name: value.get("status") for name, value in
+                                                    item.get("claims", {}).items() if name in entry["claims"]}}
+                                for record_id, created_at, payload in assessments
+                                for item in (json.loads(payload),)]}

eal/cli.py

@@ -0,0 +1,204 @@
+"""Command-line access to the same operations exposed through MCP."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from .runtime import ReasoningService, bounded_path, strict_json, load_method_registry
+
+
+def _context(workspace: Path, value: str | None) -> dict | None:
+    if value is None:
+        return None
+    supplied = (bounded_path(workspace, value[1:]).read_text(encoding="utf-8")
+                if value.startswith("@") else value)
+    context = strict_json(supplied)
+    if not isinstance(context, dict):
+        raise ValueError("context must be a JSON object")
+    return context
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="EAL engineering reasoning language")
+    parser.add_argument("--workspace", type=Path, default=Path.cwd())
+    parser.add_argument("--registry", type=Path)
+    parser.add_argument("--database", type=Path)
+    parser.add_argument("--methods", help="Trusted host method-registry factory: package.module:function")
+    parser.add_argument("--limits", type=Path, help="Host-owned TOML execution budgets")
+    subcommands = parser.add_subparsers(dest="operation", required=True)
+    subcommands.add_parser("describe")
+    register = subcommands.add_parser("register", help="Register a workspace EAL file for later sessions")
+    register.add_argument("source", help="Workspace-relative .eal file")
+    register.add_argument("--entry-id", help="Stable developer name (defaults to the workspace path)")
+    register.add_argument("--label")
+    register.add_argument("--claim", action="append", dest="claims", help="Select a claim; repeat for more")
+    register.add_argument("--context", help="Default JSON context, or @file relative to the workspace")
+    register_tree = subcommands.add_parser("register-tree", help="Register EAL files in a workspace directory")
+    register_tree.add_argument("directory", nargs="?", default=".")
+    register_tree.add_argument("--context", help="Default JSON context, or @file relative to the workspace")
+    register_tree.add_argument("--limit", type=int, default=512)
+    sources = subcommands.add_parser("sources", help="List registered EAL sources and claims")
+    sources.add_argument("--limit", type=int, default=50)
+    sources.add_argument("--offset", type=int, default=0)
+    find = subcommands.add_parser("find", help="Find registered source and claim metadata")
+    find.add_argument("query", nargs="?")
+    find.add_argument("--claim")
+    find.add_argument("--context", help="Exact registered JSON context, or @file")
+    find.add_argument("--path", help="Exact workspace-relative EAL path")
+    find.add_argument("--limit", type=int, default=50)
+    known = subcommands.add_parser("assess-known", help="Assess one registered claim and reuse eligible observations")
+    known.add_argument("entry_id")
+    known.add_argument("--claim", required=True)
+    known.add_argument("--context", help="Operator-side JSON context override, or @file")
+    known.add_argument("--now", help="ISO-8601 assessment time; defaults to current UTC")
+    known.add_argument("--reuse", choices=("compatible", "fresh"), default="compatible")
+    history = subcommands.add_parser("history", help="Find durable runs for a registered EAL file")
+    history.add_argument("entry_id")
+    history.add_argument("--source-digest", help="Historical source revision (defaults to the current revision)")
+    history.add_argument("--limit", type=int, default=50)
+    model_context = subcommands.add_parser("model-context", help="Prepare a checked packet for a text-only model")
+    model_context.add_argument("entry_id")
+    model_context.add_argument("--claim", required=True)
+    model_context.add_argument("--question", required=True, help="The developer's question for the model")
+    model_context.add_argument("--context", help="Operator-side JSON context override, or @file")
+    model_context.add_argument("--now", help="ISO-8601 assessment time; defaults to current UTC")
+    model_context.add_argument("--reuse", choices=("compatible", "fresh"), default="compatible")
+    for operation in ("validate", "format", "plan", "collect", "reason", "compile-aspic"):
+        command = subcommands.add_parser(operation)
+        command.add_argument("source", help="Source file, relative to the workspace")
+        if operation in ("collect", "reason", "compile-aspic"):
+            command.add_argument("--context", required=True, help="JSON object, or @file relative to the workspace")
+        if operation == "plan":
+            command.add_argument("--claim", required=True, help="Declared claim to plan")
+        if operation == "collect":
+            selection = command.add_mutually_exclusive_group()
+            selection.add_argument("--evidence", action="append", dest="evidence_ids")
+            selection.add_argument("--claim", help="Collect the claim's complete evidence closure")
+        if operation == "reason":
+            command.add_argument("--collection", dest="collection_id")
+            command.add_argument("--now", help="ISO-8601 assessment time; defaults to current UTC")
+        if operation == "compile-aspic":
+            command.add_argument("--collection", dest="collection_id", required=True)
+            command.add_argument("--goal", required=True, help="Declared EAL claim to query")
+            command.add_argument("--now", help="ISO-8601 assessment time; defaults to current UTC")
+            command.add_argument('--semantics', choices=('grounded', 'preferred', 'stable'), default='grounded')
+            command.add_argument('--query-mode', choices=('credulous', 'sceptical'), default='sceptical')
+            command.add_argument('--preference', choices=('minimum_rank', 'last_link_rank', 'last_link_partial'))
+    explain = subcommands.add_parser("explain")
+    explain.add_argument("assessment_id")
+    explain.add_argument("--claim")
+    packet = subcommands.add_parser("packet")
+    packet.add_argument("assessment_id")
+    packet.add_argument("--claim")
+    grounded = subcommands.add_parser("grounded")
+    grounded.add_argument("graph", help="JSON file containing arguments and attacks")
+    export = subcommands.add_parser("export-aspic")
+    export.add_argument("result", help="JSON file containing theory and formal result")
+    export.add_argument("--output", required=True, help="ASPIC+ graph JSON within the workspace")
+    args = parser.parse_args()
+    workspace = args.workspace.resolve()
+    try:
+        from .limits import ExecutionLimits, using_limits
+        limits = ExecutionLimits.load(args.limits) if args.limits else ExecutionLimits()
+        if args.operation == "export-aspic":
+            from .aspic_export import MAX_INPUT_BYTES, export_aspic_view
+
+            input_path = bounded_path(workspace, args.result)
+            if input_path.stat().st_size > MAX_INPUT_BYTES:
+                raise ValueError("ASPIC+ result exceeds the 4 MiB export input limit")
+            supplied = strict_json(input_path.read_text(encoding="utf-8"))
+            view = export_aspic_view(supplied, limits=limits)
+            target = bounded_path(workspace, args.output)
+            target.write_text(json.dumps(view, indent=2, ensure_ascii=False, allow_nan=False) + "\n",
+                              encoding="utf-8")
+            result = {"output": str(target), "argument_count": len(view["arguments"]),
+                      "defeat_witness_count": len(view["defeats"]),
+                      "formal_status": view["formal_status"]}
+        elif args.operation == "grounded":
+            from .dialectic import solve_grounded
+
+            graph = strict_json(bounded_path(workspace, args.graph).read_text())
+            if not isinstance(graph, dict) or set(graph) != {"arguments", "attacks"}:
+                raise ValueError("Graph must contain exactly arguments and attacks")
+            with using_limits(limits):
+                result = solve_grounded(**graph)
+        else:
+            methods = load_method_registry(args.methods)
+            registered_operation = args.operation in {
+                "register", "register-tree", "sources", "find", "assess-known", "history", "model-context",
+            }
+            if registered_operation:
+                from .knowledge import EALKnowledgeBase
+
+                knowledge = EALKnowledgeBase(workspace, args.registry, args.database,
+                                             method_registry=methods, limits=limits)
+                service = knowledge.service
+            else:
+                service = ReasoningService(workspace, args.registry, args.database,
+                                           method_registry=methods, limits=limits)
+            if args.operation == "describe":
+                result = service.describe()
+            elif registered_operation:
+                catalogue = knowledge.catalogue
+                if args.operation == "register":
+                    result = catalogue.register(args.source, entry_id=args.entry_id,
+                                                context=_context(workspace, args.context),
+                                                claims=args.claims, label=args.label)
+                elif args.operation == "register-tree":
+                    result = catalogue.register_tree(args.directory, context=_context(workspace, args.context),
+                                                     limit=args.limit)
+                elif args.operation == "sources":
+                    result = {"entries": catalogue.list(limit=args.limit, offset=args.offset)}
+                elif args.operation == "find":
+                    result = {"matches": catalogue.find(args.query, claim=args.claim,
+                                                         context=_context(workspace, args.context),
+                                                         path=args.path, limit=args.limit)}
+                elif args.operation == "history":
+                    result = catalogue.runs(args.entry_id, source_digest=args.source_digest, limit=args.limit)
+                elif args.operation == "assess-known":
+                    result = knowledge.assess(
+                        args.entry_id, args.claim, context=_context(workspace, args.context),
+                        now=args.now, reuse=args.reuse,
+                    )
+                else:
+                    from .knowledge import ModelContextAdapter
+
+                    result = ModelContextAdapter(knowledge).prepare(
+                        args.question, args.entry_id, args.claim, context=_context(workspace, args.context),
+                        now=args.now, reuse=args.reuse,
+                    )
+            elif args.operation == "explain":
+                result = service.explain(args.assessment_id, args.claim)
+            elif args.operation == "packet":
+                result = service.packet(args.assessment_id, args.claim)
+            else:
+                source = bounded_path(workspace, args.source).read_text(encoding="utf-8")
+                if args.operation == "format":
+                    result = service.format(source)
+                elif args.operation == "validate":
+                    result = service.validate(source)
+                elif args.operation == "plan":
+                    result = service.plan(source, args.claim)
+                else:
+                    context = _context(workspace, args.context)
+                    if args.operation == "collect":
+                        result = (service.collect_claim(source, context, args.claim) if args.claim
+                                  else service.collect(source, context, args.evidence_ids))
+                    elif args.operation == "reason":
+                        result = service.reason(source, context, args.collection_id, args.now)
+                    else:
+                        result = service.compile_aspic(source, context, args.collection_id, args.goal, args.now,
+                                                       semantics=args.semantics, query_mode=args.query_mode,
+                                                       preference=args.preference)
+        print(json.dumps(result, indent=2, ensure_ascii=False, allow_nan=False))
+        if result.get("valid") is False or any(record.get("status") == "error" for record in result.get("records", {}).values()):
+            raise SystemExit(1)
+    except (ValueError, KeyError, OSError) as exc:
+        print(json.dumps({"error": str(exc)}, ensure_ascii=False))
+        raise SystemExit(2) from exc
+
+
+if __name__ == "__main__":
+    main()

eal/client_transports.py

@@ -0,0 +1,69 @@
+"""Transport factories for the one-shot host client.
+
+These factories select connections without constructing the application service.
+HTTP targets refer to existing servers; stdio targets own one subprocess for the
+duration of the request. Credentials are obtained from the trusted environment.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+import ipaddress
+from urllib.parse import urlsplit, urlunsplit
+
+from fastmcp.client.auth import BearerAuth
+from fastmcp.client.transports import ClientTransport, StdioTransport, StreamableHttpTransport
+from mcp import StdioServerParameters
+
+from .credentials import read_bearer_token
+
+
+def create_client_transport(parameters: StdioServerParameters | ClientTransport) -> ClientTransport:
+    """Use a transport directly or translate the host's stdio launch contract."""
+    if isinstance(parameters, ClientTransport):
+        return parameters
+    if not isinstance(parameters, StdioServerParameters):
+        raise TypeError("Host target must be an MCP client transport or StdioServerParameters")
+    if parameters.encoding.lower().replace("_", "-") != "utf-8" or parameters.encoding_error_handler != "strict":
+        raise ValueError("FastMCP stdio requires strict UTF-8 encoding")
+    return StdioTransport(command=parameters.command, args=parameters.args,
+                          env=parameters.env, cwd=parameters.cwd, keep_alive=False)
+
+
+def validate_http_url(url: str) -> str:
+    """Validate an explicit HTTP endpoint without credentials in its URL."""
+    if not isinstance(url, str) or not url or any(character.isspace() or ord(character) < 32 for character in url):
+        raise ValueError("HTTP URL must be a non-empty URL without whitespace")
+    try:
+        parsed = urlsplit(url)
+        port = parsed.port
+        host = parsed.hostname
+    except ValueError as exc:
+        raise ValueError("HTTP URL has an invalid host or port") from exc
+    if parsed.scheme not in {"http", "https"} or not host or port == 0:
+        raise ValueError("HTTP URL must use http or https with a valid hostname and port")
+    if parsed.username is not None or parsed.password is not None or parsed.query or parsed.fragment:
+        raise ValueError("HTTP URL must not contain credentials, a query or a fragment")
+    return urlunsplit((parsed.scheme, parsed.netloc, parsed.path, "", ""))
+
+
+def create_http_transport(url: str, *, token_env: str | None = None,
+                          environ: Mapping[str, str] | None = None,
+                          httpx_client_factory=None) -> StreamableHttpTransport:
+    """Connect to an existing HTTP server, requiring a token beyond loopback.
+
+The optional HTTP client factory supports controlled embedding and local tests.
+Ordinary clients retain the HTTP library's environment proxy configuration.
+"""
+    url = validate_http_url(url)
+    host = urlsplit(url).hostname
+    loopback = host.lower().rstrip(".") == "localhost"
+    try:
+        loopback = loopback or ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        pass
+    if not loopback and token_env is None:
+        raise ValueError("HTTP connections beyond loopback require --token-env authentication")
+    token = read_bearer_token(token_env, environ)
+    return StreamableHttpTransport(url, auth=BearerAuth(token) if token is not None else None,
+                                   httpx_client_factory=httpx_client_factory)