pycforge-sdk 0.6.3__py3-none-any.whl

pycforge_sdk/__init__.py

@@ -0,0 +1,6 @@
+"""PyCForge SDK public API. Importing this module requires neither Qt nor PyCForge."""
+from .results import Outcome, SDKError, SDK_VERSION as __version__
+from .service import SDK
+from .discovery import discover_engines
+
+__all__ = ["SDK", "Outcome", "SDKError", "__version__", "discover_engines"]

pycforge_sdk/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

pycforge_sdk/catalogue.py

@@ -0,0 +1,287 @@
+"""Independent, headless catalogue service (no engine imports).
+
+Adapted from the PyCForge 1.3.60 independent reference reader. XML is validated against the closed grammar below. The supplied
+XSD is a separate validation artifact; ElementTree does not validate XSD.
+"""
+from __future__ import annotations
+from dataclasses import dataclass
+import argparse
+import ast
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import shutil
+import subprocess
+import tempfile
+from xml.etree import ElementTree as ET
+
+MAX_FILE = 8 * 1024 * 1024
+MAX_TOTAL = 32 * 1024 * 1024
+MAX_INDEX = 1024 * 1024
+VERSIONS = ("engine_api", "extension_api", "protocol", "catalogue_schema")
+FEATURES = {"sha256-inventory", "closed-xml-v1"}
+SHA = re.compile(r"[0-9a-f]{64}\Z")
+NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9_.-]{0,127}\Z")
+# Independent reader grammar: required attributes and ordered children with
+# inclusive occurrence bounds. None means unbounded (still under node limits).
+GRAMMAR = {
+ "pycforge-api": (("schema", "engine-version", "engine-api", "extension-api", "protocol"), tuple((s,1,1) for s in ("methods","operations","types","packs","capabilities","diagnostics","resources"))),
+ "methods": ((), (("method",1,None),)),
+ "method": (("id","kind","import-path","signature","status"), (("summary",1,1),)),
+ "summary": ((), ()),
+ "operations": ((), (("operation",1,None),)),
+ "operation": (("id","version","arity","summary"), (("route",2,2),("semantic",1,None))),
+ "route": (("name","target","lowering","unsupported"), (("guard",0,None),)),
+ "guard": (("id",), ()), "semantic": ((),()),
+ "types": ((), (("type",1,None),)),
+ "type": (("id","route","representation"), (("ownership",1,1),)),
+ "ownership": (("passing","ownership","lifetime","retains-input","mutates-input","allocation","cleanup"),()),
+ "packs": ((), (("pack",1,None),)),
+ "pack": (("id","version","namespace","profile","activation","author","created","license","description","verification-producer"), (("function",1,None),("constant",0,None))),
+ "function": (("operation-id","export","native-symbol","arity","result","domain","summary"),()),
+ "constant": (("export","value"),()),
+ "capabilities": ((), (("capability",1,None),)),
+ "capability": (("id","status","detail"),()),
+ "diagnostics": ((), (("diagnostic",1,None),)),
+ "diagnostic": (("code","message"),()),
+ "resources": ((), (("resource",1,None),)),
+ "resource": (("path",),()),
+}
+
+
+class CatalogueError(ValueError):
+    pass
+
+
+def _require(condition, message):
+    if not condition:
+        raise CatalogueError(message)
+
+
+def _json(data):
+    def unique(items):
+        result = {}
+        for key, value in items:
+            _require(key not in result, "Duplicate JSON key")
+            result[key] = value
+        return result
+    try:
+        return json.loads(data, object_pairs_hook=unique,
+                          parse_constant=lambda _: (_ for _ in ()).throw(CatalogueError("Nonfinite JSON")))
+    except (ValueError, UnicodeError, RecursionError) as exc:
+        raise CatalogueError("Invalid manifest JSON") from exc
+
+
+def _read(folder, name, limit):
+    _require(isinstance(name, str) and NAME.fullmatch(name), "Invalid inventory path")
+    path = folder / name
+    _require(not path.is_symlink() and path.is_file(), "Missing or symbolic-link resource: " + name)
+    with path.open("rb") as stream:
+        data = stream.read(limit + 1)
+    _require(len(data) <= limit, "Resource exceeds size budget: " + name)
+    return data
+
+
+def validate_xml(data, manifest):
+    _require(len(data) <= MAX_FILE, "XML exceeds size limit")
+    try:
+        text = data.decode("utf-8")
+    except UnicodeError as exc:
+        raise CatalogueError("Catalogue requires UTF-8 XML") from exc
+    # No DTDs, entity declarations, comments, secondary processing instructions,
+    # namespace/XInclude constructs, external schemas or encoding indirection.
+    _require("<!" not in text, "XML declarations/DTDs/entities/comments are forbidden")
+    body = re.sub(r"\A<\?xml version=['\"]1.0['\"] encoding=['\"]utf-8['\"]\?>", "", text, count=1)
+    _require("<?" not in body, "XML processing instructions are forbidden")
+    try:
+        root = ET.fromstring(text)
+    except (ET.ParseError, ValueError) as exc:
+        raise CatalogueError("Invalid XML") from exc
+    _require(root.tag == "pycforge-api", "Unexpected XML root")
+    stack = [(root, 1)]
+    count = 0
+    while stack:
+        node, depth = stack.pop()
+        count += 1
+        _require(depth <= 16 and count <= 50000, "XML structural budget exceeded")
+        _require(node.tag in GRAMMAR, "Unknown required XML element")
+        attrs, children = GRAMMAR[node.tag]
+        if node.tag == "function" and manifest["catalogue_schema"] in ("0.2", "0.3", "0.4"):
+            attrs = (*attrs, "errors", "integer-passthrough")
+        if node.tag == "function" and manifest["catalogue_schema"] in ("0.3", "0.4"):
+            attrs = (*attrs, "parameters", "implementation")
+        _require(set(node.attrib) == set(attrs), "Unexpected XML attributes: " + node.tag)
+        _require(node.tag in ("summary", "semantic") or not (node.text or "").strip(), "Unexpected XML text")
+        _require(not (node.tail or "").strip(), "Unexpected XML tail")
+        index = 0
+        for name, minimum, maximum in children:
+            start = index
+            while index < len(node) and node[index].tag == name:
+                index += 1
+            _require(index-start >= minimum and (maximum is None or index-start <= maximum), "Wrong XML child count: " + name)
+        _require(index == len(node), "Unexpected XML child or order: " + node.tag)
+        stack.extend((child, depth + 1) for child in node)
+    for xml_key, json_key in (("schema","catalogue_schema"),("engine-version","engine_version"),
+                              ("engine-api","engine_api"),("extension-api","extension_api"),("protocol","protocol")):
+        _require(root.get(xml_key) == manifest[json_key], "XML/manifest identity mismatch")
+    for parent, tag, key in (("methods","method","id"),("operations","operation","id"),
+        ("packs","pack","namespace"),("capabilities","capability","id"),("diagnostics","diagnostic","code"),
+        ("resources","resource","path")):
+        values = [e.get(key) for e in root.find(parent).findall(tag)]
+        _require(len(values) == len(set(values)) and all(values), "Duplicate or empty catalogue identity")
+    for operation in root.find("operations"):
+        _require({r.get("name") for r in operation.findall("route")} == {"typed","runtime"}, "Incomplete route decisions")
+        for route in operation.findall("route"):
+            _require(bool(route.get("lowering")) != bool(route.get("unsupported")), "Ambiguous route decision")
+    _require({e.get("path") for e in root.find("resources")} == {e["path"] for e in manifest["files"]}, "XML inventory mismatch")
+    return tuple(dict(m.attrib, summary=m.findtext("summary")) for m in root.find("methods"))
+
+
+@dataclass(frozen=True)
+class Snapshot:
+    identity: dict
+    files: dict[str, bytes]
+    methods: tuple[dict, ...]
+
+    @property
+    def revision(self):
+        return self.identity["manifest_sha256"]
+
+
+def read_snapshot(discovery):
+    _require(type(discovery) is dict, "Expected discovery object")
+    _require(discovery.get("engine") == "PyCForge", "Unexpected engine")
+    for key in ("engine_api", "protocol"):
+        _require(discovery.get(key) == "0.1", "Incompatible " + key)
+    _require((discovery.get("extension_api"), discovery.get("catalogue_schema")) in
+             (("0.1", "0.1"), ("0.2", "0.2"), ("0.3", "0.3"), ("0.4", "0.4")), "Incompatible extension API/catalogue schema")
+    _require(type(discovery.get("folder")) is str and Path(discovery["folder"]).is_absolute(), "Discovery requires an absolute folder")
+    folder = Path(discovery["folder"])
+    index = _read(folder, "index.json", MAX_INDEX)
+    _require(hashlib.sha256(index).hexdigest() == discovery.get("manifest_sha256"), "Discovery manifest changed")
+    manifest = _json(index)
+    _require(type(manifest) is dict and set(manifest) == {"engine","engine_version",*VERSIONS,"required_features","files"}, "Unknown manifest contract")
+    for key in ("engine", "engine_version", *VERSIONS):
+        _require(manifest[key] == discovery.get(key), "Engine identity mismatch: " + key)
+    _require(type(manifest["engine_version"]) is str and re.fullmatch(r"\d+\.\d+\.\d+", manifest["engine_version"]), "Malformed engine version")
+    features = manifest["required_features"]
+    _require(type(features) is list and all(type(f) is str for f in features), "Malformed required features")
+    _require(set(features) == FEATURES and len(features) == len(FEATURES), "Unsupported or missing required features")
+    entries = manifest["files"]
+    _require(type(entries) is list and 5 <= len(entries) <= 2048, "Invalid inventory count")
+    files = {"index.json": index}
+    total = len(index)
+    for entry in entries:
+        _require(type(entry) is dict and set(entry) == {"path","bytes","sha256"}, "Malformed inventory entry")
+        name = entry["path"]
+        _require(type(name) is str and name not in files, "Duplicate inventory path")
+        _require(type(entry["bytes"]) is int and 0 <= entry["bytes"] <= MAX_FILE, "Invalid resource size")
+        _require(type(entry["sha256"]) is str and SHA.fullmatch(entry["sha256"]), "Invalid SHA256")
+        data = _read(folder, name, MAX_FILE)
+        total += len(data)
+        _require(total <= MAX_TOTAL, "Inventory exceeds total size limit")
+        _require(len(data) == entry["bytes"] and hashlib.sha256(data).hexdigest() == entry["sha256"], "Resource hash/size mismatch: " + name)
+        files[name] = data
+    _require({"api.xml","api.xsd","guide.txt","scalar_template.py","requirements.txt"} <= files.keys(), "Incomplete landscape")
+    methods = validate_xml(files["api.xml"], manifest)
+    _require(_read(folder, "index.json", MAX_INDEX) == index, "Engine updated during refresh")
+    return Snapshot(dict(discovery), files, methods)
+
+
+def signature_compatible(previous, current):
+    """Accept only preserved call shapes plus new optional parameters; never eval."""
+    if previous == current:
+        return True
+    try:
+        old = ast.parse("def api" + previous + ": pass").body[0]
+        new = ast.parse("def api" + current + ": pass").body[0]
+    except (SyntaxError, ValueError, TypeError, RecursionError):
+        return False
+    dump = lambda node: ast.dump(node) if node is not None else None
+    if dump(old.returns) != dump(new.returns): return False
+    a, b = old.args, new.args
+    if len(a.posonlyargs) != len(b.posonlyargs): return False
+    if dump(a.vararg) != dump(b.vararg) or dump(a.kwarg) != dump(b.kwarg): return False
+    # A new parameter could consume values previously delivered to *args/**kwargs.
+    if a.kwarg is not None: return False
+    old_pos, new_pos = a.posonlyargs + a.args, b.posonlyargs + b.args
+    if len(new_pos) < len(old_pos) or a.vararg is not None and len(old_pos) != len(new_pos): return False
+    old_defaults = [None] * (len(old_pos)-len(a.defaults)) + a.defaults
+    new_defaults = [None] * (len(new_pos)-len(b.defaults)) + b.defaults
+    for i, arg in enumerate(old_pos):
+        if dump(arg) != dump(new_pos[i]) or dump(old_defaults[i]) != dump(new_defaults[i]): return False
+    if any(d is None for d in new_defaults[len(old_pos):]): return False
+    old_kw = {arg.arg: (dump(arg), dump(d)) for arg, d in zip(a.kwonlyargs, a.kw_defaults)}
+    new_kw = {arg.arg: (dump(arg), dump(d)) for arg, d in zip(b.kwonlyargs, b.kw_defaults)}
+    if any(new_kw.get(k) != v for k, v in old_kw.items()): return False
+    if any(v[1] is None for k, v in new_kw.items() if k not in old_kw): return False
+    return True
+
+
+def refresh(discovery, cache):
+    """Validate every byte, stage it, then replace one atomic active pointer."""
+    snapshot = read_snapshot(discovery)
+    cache = Path(cache)
+    if (cache / "current.json").exists():
+        previous = cached_snapshot(cache)
+        methods = {m["id"]: m for m in snapshot.methods}
+        for method in previous.methods:
+            replacement = methods.get(method["id"])
+            _require(replacement is not None and all(replacement[k] == method[k]
+                     for k in ("kind", "import-path"))
+                     and signature_compatible(method["signature"], replacement["signature"]),
+                     "Incompatible public method change; retain previous cache")
+    cache.mkdir(parents=True, exist_ok=True)
+    stage = Path(tempfile.mkdtemp(prefix="staging-", dir=cache))
+    pointer = None
+    try:
+        for name, data in snapshot.files.items():
+            (stage / name).write_bytes(data)
+        cached_identity = {**snapshot.identity, "folder": str(stage.resolve())}
+        read_snapshot(cached_identity)
+        destination = cache / snapshot.revision
+        if destination.exists():
+            # An existing cache must also be valid; never trust just its name.
+            read_snapshot({**snapshot.identity, "folder": str(destination.resolve())})
+        else:
+            os.replace(stage, destination)
+        fd, spelling = tempfile.mkstemp(prefix="pointer-", dir=cache)
+        pointer = Path(spelling)
+        with os.fdopen(fd, "w", encoding="utf-8") as stream:
+            json.dump({**snapshot.identity, "folder": str(destination.resolve())}, stream, sort_keys=True)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(pointer, cache / "current.json")
+        return snapshot
+    finally:
+        if stage.exists():
+            shutil.rmtree(stage)
+        if pointer is not None and pointer.exists():
+            pointer.unlink()
+
+
+def cached_snapshot(cache):
+    """Last valid metadata for OFFLINE display only; not execution authority."""
+    cache = Path(cache)
+    discovery = _json(_read(cache, "current.json", MAX_INDEX))
+    _require(type(discovery) is dict and type(discovery.get("manifest_sha256")) is str
+             and SHA.fullmatch(discovery["manifest_sha256"]), "Invalid cache pointer")
+    _require(discovery.get("folder") == str((cache / discovery["manifest_sha256"]).resolve()), "Cache pointer escapes cache")
+    return read_snapshot(discovery)
+
+
+def ensure_current(snapshot, discovery):
+    """Recheck immediately before a later SDK operation against this engine."""
+    current = read_snapshot(discovery)
+    _require(current.identity == snapshot.identity, "Stale engine/catalogue identity; refresh and revalidate before use")
+
+
+def discover_engine(python):
+    """Run only the explicitly selected installed engine's public endpoint."""
+    completed = subprocess.run([str(python), "-I", "-m", "pycforge", "--format", "json", "sdk-api"],
+                               check=True, capture_output=True, timeout=30)
+    _require(len(completed.stdout) <= MAX_INDEX, "Oversized engine discovery")
+    return _json(completed.stdout)
+

pycforge_sdk/cli.py

@@ -0,0 +1,114 @@
+"""Thin console client; all authoring operations use the public SDK service."""
+import argparse
+import json
+from pathlib import Path
+import sys
+import threading
+from . import SDK, Outcome, __version__, discover_engines
+
+
+def parser():
+    root = argparse.ArgumentParser(prog="pycforge-sdk", description="Author conversion add-ons using a selected PyCForge engine.")
+    root.add_argument("--version", action="version", version=__version__)
+    root.add_argument("--engine-python", help="Python interpreter containing the selected PyCForge installation")
+    root.add_argument("--cache", type=Path, default=Path.home()/".pycforge-sdk"/"cache")
+    root.add_argument("--timeout", type=float, default=30, help="Per-process deadline in seconds, at most 300")
+    root.add_argument("--json", action="store_true", help="Emit the versioned result object for automation")
+    commands = root.add_subparsers(dest="command", required=True)
+    discover = commands.add_parser("discover", help="Find installed PyCForge engines without changing the reference cache")
+    discover.add_argument("--location", action="append", help="Restrict the search to this environment or installed support folder; repeat for multiple locations")
+    discover.add_argument("--search-timeout", type=float, default=20, help="Total search deadline in seconds")
+    commands.add_parser("connect", help="Discover the engine and refresh its reference")
+    commands.add_parser("templates", help="Choose from concise engine starter descriptions")
+    commands.add_parser("workbench", help="Read engine-owned forms, default imports and Help")
+    methods = commands.add_parser("methods", help="Browse the authoring method tree")
+    methods.add_argument("--advanced", action="store_true")
+    describe = commands.add_parser("describe", help="Explain one authoring method")
+    describe.add_argument("method")
+    new = commands.add_parser("new", help="Create a starter extension project")
+    new.add_argument("directory", type=Path); new.add_argument("--author", required=True)
+    new.add_argument("--template", default="scalar-cube-root")
+    inspect = commands.add_parser("inspect", help="Inspect a saved declaration without executing it")
+    inspect.add_argument("directory", type=Path)
+    scan = commands.add_parser("scan", help="Show documentation readiness and editable field issues; do not run tests")
+    scan.add_argument("directory", type=Path)
+    ready = commands.add_parser("readiness", help="Check current packaging evidence without running fixtures")
+    ready.add_argument("directory", type=Path); ready.add_argument("--compiler")
+    document = commands.add_parser("document", help="Add missing author fields while preserving prose; explicitly upgrade legacy projects")
+    document.add_argument("directory", type=Path)
+    convert = commands.add_parser("convert", help="Convert one fixture without running it")
+    convert.add_argument("directory", type=Path); convert.add_argument("--case", required=True)
+    verify = commands.add_parser("verify", help="Explicitly compile and execute the complete fixture suite")
+    verify.add_argument("directory", type=Path); verify.add_argument("--compiler", default="cc")
+    build = commands.add_parser("build", help="Package only a currently verified snapshot")
+    build.add_argument("directory", type=Path); build.add_argument("--output", type=Path, required=True)
+    build.add_argument("--compiler", help="Require evidence for this selected compiler")
+    register = commands.add_parser("register", help="Explicitly register an import with PyCForge")
+    register.add_argument("package", type=Path); register.add_argument("--store", type=Path)
+    return root
+
+
+def render(result):
+    data = result.data
+    if "workbench" in data:
+        workbench = data["workbench"] or {}
+        return "\n".join(["Connection: " + data["connection"]["state"],
+            "Workbench: " + workbench.get("schema", "legacy catalogue"),
+            *[item["namespace"] + " " + item["version"] + ": " + item["description"] for item in workbench.get("imports", [])],
+            "Help: " + ", ".join(doc["title"] for doc in data.get("documents", []))])
+    if "method" in data:
+        method = data["method"]
+        lines = [method["title"], method["public_path"] + method["signature"], method["summary"], ""]
+        for parameter in method["parameters"]:
+            marker = "required" if parameter["required"] else "default=" + repr(parameter["default"])
+            lines.append(f"{parameter['name']} ({parameter['type']}, {marker}): {parameter['description']}")
+            if parameter["choices"]: lines.append("  Choices: " + ", ".join(map(str,parameter["choices"])))
+        lines += ["", "Returns: " + method["returns"], "Effects: " + method["effects"]]
+        for error in method["errors"]: lines.append(f"{error['code']}: {error['meaning']} {error['remedy']}")
+        lines += ["", "Example:", *method["examples"], "", *method["limits"]]
+        if data["connection"]["state"] != "connected": lines.insert(0,"OFFLINE REFERENCE — execution unavailable")
+        return "\n".join(lines)
+    if "templates" in data:
+        return "\n".join(["Connection: " + data["connection"]["state"], *[t["id"] + ": " + t["title"] + "\n  " + t["description"] for t in data["templates"]]])
+    if "methods" in data:
+        rows = data["methods"]
+        lines = ["Connection: " + data["connection"]["state"]]
+        if "categories" in data:
+            for category in data["categories"]:
+                lines.append("\n" + category["title"])
+                lines.extend(f"  {row['public_path']}: {row['summary']}" for row in rows if row["category"] == category["id"])
+        else: lines.extend(row["id"] + row["signature"] for row in rows)
+        return "\n".join(lines)
+    return json.dumps(result.to_dict(), indent=2, sort_keys=True)
+
+
+def main(argv=None):
+    args = parser().parse_args(argv)
+    cancel = threading.Event()
+    sdk = SDK(engine_python=args.engine_python or sys.executable, cache=args.cache, timeout=args.timeout, cancel=cancel)
+    try:
+        match args.command:
+            case "discover": result = discover_engines(preferred=args.engine_python, locations=args.location, timeout=min(args.timeout, 3),
+                                                        search_timeout=args.search_timeout, cancel=cancel)
+            case "connect": result = sdk.connect()
+            case "templates": result = sdk.templates()
+            case "workbench": result = sdk.workbench()
+            case "methods": result = sdk.methods(advanced=args.advanced)
+            case "describe": result = sdk.describe(args.method)
+            case "new": result = sdk.create_project(args.directory, author=args.author, template=args.template)
+            case "inspect": result = sdk.inspect(args.directory)
+            case "scan": result = sdk.scan(args.directory)
+            case "readiness": result = sdk.readiness(args.directory, compiler=args.compiler)
+            case "document": result = sdk.prepare_documentation(args.directory)
+            case "convert": result = sdk.convert(args.directory, args.case)
+            case "verify": result = sdk.verify(args.directory, compiler=args.compiler)
+            case "build": result = sdk.build(args.directory, args.output, compiler=args.compiler)
+            case "register": result = sdk.register(args.package, store=args.store)
+    except KeyboardInterrupt:
+        cancel.set()
+        result = Outcome("canceled", diagnostics=({"code":"SDK_CANCELED", "message":"Interrupted by the caller."},))
+    if args.json:
+        print(json.dumps(result.to_dict(), sort_keys=True, allow_nan=False))
+    else:
+        print(render(result))
+    return {"succeeded":0, "rejected":2, "incomplete":3, "canceled":130, "internal_failure":4}[result.status]

pycforge_sdk/connection.py

@@ -0,0 +1,136 @@
+"""Selected-engine discovery, offline metadata and a narrow public-service bridge."""
+from __future__ import annotations
+from pathlib import Path
+import json
+from . import catalogue
+from .process import run
+from .project import canonical, parse
+from .results import SDKError
+
+
+class Connection:
+    def __init__(self, python, cache, *, timeout=30, cancel=None):
+        self.python = str(python)
+        self.cache = Path(cache)
+        self.timeout, self.cancel = timeout, cancel
+        self.snapshot = None
+        self.state = "unavailable"
+        self.problem = None
+        self._authoring_ready = False
+
+    def discover(self):
+        result = run([self.python, "-I", Path(__file__).with_name("engine_launch.py"), "discover"],
+                     timeout=self.timeout, cancel=self.cancel, max_output=1024*1024)
+        if result.returncode:
+            raise SDKError("SDK_ENGINE_UNAVAILABLE", "Selected Python cannot discover PyCForge.", status="incomplete",
+                           details={"stderr": result.stderr.decode("utf-8", "replace")})
+        return parse(result.stdout)
+
+    def connect(self, *, offline=False):
+        if offline:
+            self._authoring_ready = False
+            self.problem = "Working offline; cached reference cannot authorize execution."
+            try:
+                self.snapshot = catalogue.cached_snapshot(self.cache)
+                self.state = "offline"
+            except (catalogue.CatalogueError, OSError):
+                self.snapshot, self.state = None, "unavailable"
+            return self.description()
+        try:
+            discovery = self.discover()
+            # Validate supported authoring metadata before committing the cache.
+            self.snapshot = catalogue.read_snapshot(discovery)
+            self._authoring_ready = False
+            if "authoring.json" in self.snapshot.files:
+                self.reference()
+            self.workbench()
+            self.snapshot = catalogue.refresh(discovery, self.cache)
+            self.state, self.problem = "connected", None
+        except (catalogue.CatalogueError, OSError, SDKError) as exc:
+            if isinstance(exc, SDKError) and exc.status == "canceled": raise
+            self.problem = str(exc)
+            try:
+                self.snapshot = catalogue.cached_snapshot(self.cache)
+                self.state = "offline"
+            except (catalogue.CatalogueError, OSError):
+                self.snapshot, self.state = None, "unavailable"
+        return self.description()
+
+    def description(self):
+        return {"state": self.state, "engine": None if self.snapshot is None else dict(self.snapshot.identity),
+                "problem": self.problem, "execution_available": self.state == "connected" and self._authoring_ready}
+
+    def metadata(self):
+        if self.snapshot is None:
+            self.connect()
+        if self.snapshot is None:
+            raise SDKError("SDK_ENGINE_UNAVAILABLE", self.problem or "No engine catalogue is available.", status="incomplete")
+        return self.snapshot
+
+    def ensure_current(self):
+        self.metadata()
+        if self.state != "connected":
+            raise SDKError("SDK_OFFLINE", "Cached metadata is for browsing; connect to a compatible engine before authoring operations.", status="incomplete")
+        try:
+            catalogue.ensure_current(self.snapshot, self.discover())
+        except (catalogue.CatalogueError, OSError) as exc:
+            self.state = "offline"
+            raise SDKError("SDK_STALE_ENGINE", str(exc), status="incomplete") from exc
+
+    def reference(self):
+        snapshot = self.metadata()
+        if "authoring.json" not in snapshot.files:
+            raise SDKError("SDK_CAPABILITY", "This engine supports catalogue browsing but lacks the scalar authoring service; select PyCForge 1.3.61 or a compatible later build.")
+        data = parse(snapshot.files["authoring.json"])
+        if (type(data) is not dict or data.get("schema") != "pycforge.authoring-reference/0.1"
+                or data.get("service_api") != "0.1"):
+            raise SDKError("SDK_CAPABILITY", "Unsupported authoring reference contract.")
+        required = {"categories", "entries", "templates", "native_test", "limits"}
+        if not required <= data.keys() or not all(type(data[k]) is list for k in ("categories","entries","templates","limits")):
+            raise SDKError("SDK_CAPABILITY", "Incomplete engine authoring guidance.")
+        if not 1 <= len(data["entries"]) <= 1024 or not 1 <= len(data["templates"]) <= 512:
+            raise SDKError("SDK_CAPABILITY", "Invalid authoring catalogue size.")
+        identifiers = set()
+        categories = {c["id"] for c in data["categories"] if type(c) is dict and type(c.get("id")) is str}
+        for entry in data["entries"]:
+            fields = {"id","public_path","title","category","summary","parameters","returns","effects","errors","examples","limits","status","since"}
+            if type(entry) is not dict or not fields <= entry.keys() or entry["id"] in identifiers or entry["category"] not in categories:
+                raise SDKError("SDK_CAPABILITY", "Malformed authoring reference entry.")
+            identifiers.add(entry["id"])
+            for key in ("id","public_path","title","category","summary","returns","effects","status","since"):
+                if type(entry[key]) is not str or not entry[key]: raise SDKError("SDK_CAPABILITY", "Missing reference explanation: " + key)
+            for key in ("parameters","errors","examples","limits"):
+                if type(entry[key]) is not list: raise SDKError("SDK_CAPABILITY", "Malformed reference details: " + key)
+            suffix = entry["public_path"].removeprefix("pycforge.crucible.")
+            matches = [m for m in snapshot.methods if m["id"].endswith("." + suffix)]
+            if len(matches) != 1:
+                raise SDKError("SDK_CAPABILITY", "Reference does not resolve to one published public method: " + suffix)
+            entry["signature"] = matches[0]["signature"]
+        self._authoring_ready = True
+        return data
+
+    def workbench(self):
+        from .workbench import validate
+        return validate(self.metadata())
+
+    def call(self, action, payload):
+        self.ensure_current()
+        reference = self.reference()
+        identity = self.snapshot.identity
+        request = canonical({"identity": identity, "action": action, "payload": payload})
+        if len(request) > 8*1024*1024:
+            raise SDKError("SDK_LIMIT", "Engine request exceeds the bridge budget.")
+        result = run([self.python, "-I", Path(__file__).with_name("engine_launch.py"), "call"], input_bytes=request,
+                     timeout=self.timeout, cancel=self.cancel, max_output=16*1024*1024)
+        if result.returncode:
+            raise SDKError("SDK_ENGINE_FAILURE", "Selected engine worker failed.", status="internal_failure",
+                           details={"stderr": result.stderr.decode("utf-8", "replace")})
+        answer = parse(result.stdout)
+        if answer.get("schema") != "pycforge-sdk.bridge/0.1":
+            raise SDKError("SDK_PROTOCOL", "Unexpected engine bridge response.", status="internal_failure")
+        if not answer.get("ok"):
+            failure = answer.get("diagnostic", {})
+            raise SDKError(failure.get("code", "SDK_ENGINE_ERROR"), failure.get("message", "Engine operation failed."))
+        if answer.get("identity") != identity:
+            raise SDKError("SDK_STALE_ENGINE", "Engine identity changed during the operation.", status="incomplete")
+        return answer["result"]