pycforge-sdk 0.6.3__py3-none-any.whl

pycforge_sdk/service.py

@@ -0,0 +1,454 @@
+"""Public headless SDK: the console and optional PySide6 UI share this service."""
+from __future__ import annotations
+import base64
+from datetime import date
+from pathlib import Path
+import tempfile
+from .connection import Connection
+from .native import compiler_identity, execute_fixture
+from .project import Project, PROJECT_SCHEMA, DOCUMENTED_PROJECT_SCHEMA, REPORT_SCHEMA, MAX_PROJECT, atomic_write, canonical, digest, parse, read
+from .results import SDK_VERSION, Outcome, SDKError, operation
+
+
+class SDK:
+    """Select an installed engine and author extensions through its public API.
+
+    Construction performs no discovery, execution or file writes. Each instance
+    is a single-client session. Pass a threading.Event as cancel; progress is a
+    callable receiving detached dictionaries on the calling thread. A GUI should
+    run long operations in its own worker and forward those events to its UI.
+    """
+    def __init__(self, *, engine_python, cache, timeout=30, cancel=None, progress=None):
+        self._connection = Connection(engine_python, cache, timeout=timeout, cancel=cancel)
+        self.timeout, self.cancel, self.progress = timeout, cancel, progress
+
+    def _notify(self, phase, **data):
+        if self.cancel is not None and self.cancel.is_set():
+            raise SDKError("SDK_CANCELED", "Operation canceled.", status="canceled")
+        if self.progress is not None:
+            self.progress({"schema": "pycforge-sdk.progress/0.1", "phase": phase, **data})
+
+    @operation
+    def connect(self, *, offline=False) -> Outcome:
+        """Discover and refresh; failed connections retain labeled offline metadata."""
+        info = self._connection.connect(offline=offline)
+        return Outcome("succeeded" if info["state"] == "connected" else "incomplete", info)
+
+    @operation
+    def methods(self, *, advanced: bool = False) -> Outcome:
+        """Return grouped method-tree data without importing or executing examples."""
+        snapshot = self._connection.metadata()
+        if advanced:
+            return {"connection": self._connection.description(), "methods": list(snapshot.methods)}
+        guide = self._connection.reference()
+        return {"connection": self._connection.description(), "categories": guide["categories"],
+                "methods": guide["entries"], "limits": guide["limits"],
+                "domain_contracts": guide.get("domain_contracts", {}),
+                "documentation": guide.get("documentation", {}),
+                "workflow": guide.get("workflow", []), "array_operations": guide.get("array_operations", []),
+                "supported_profiles": guide.get("supported_profiles", [guide["profile"]])}
+
+    @operation
+    def workbench(self) -> Outcome:
+        """Read engine-owned forms, default imports and inert Help for every client."""
+        value = self._connection.workbench()
+        return {"connection": self._connection.description(), "workbench": value["definition"] if value else None,
+                "documents": value["documents"] if value else [], "source": "engine" if value else "legacy"}
+
+    @operation
+    def templates(self) -> Outcome:
+        """List small engine-owned starter cards; never execute template sources."""
+        guide = self._connection.reference()
+        return {"connection": self._connection.description(),
+                "templates": [{"id": t["id"], "title": t["title"], "description": t["description"],
+                               "declaration_schema": t["declaration"]["schema"]} for t in guide["templates"]],
+                "workflow": guide.get("workflow", []), "limits": guide["limits"]}
+
+    @operation
+    def describe(self, method: str) -> Outcome:
+        """Explain one supported authoring method, including parameters and examples."""
+        entries = self._connection.reference()["entries"]
+        selected = [entry for entry in entries if entry["id"] == method or entry["id"].endswith("." + method)]
+        if len(selected) != 1:
+            raise SDKError("SDK_METHOD", "Choose one exact method from the authoring tree.")
+        return {"connection": self._connection.description(), "method": selected[0],
+                "domain_contracts": self._connection.reference().get("domain_contracts", {}),
+                "array_operations": self._connection.reference().get("array_operations", []) if method.endswith("ArrayFunction") else []}
+
+    @operation
+    def create_project(self, directory: str | Path, *, author: str, template: str = "scalar-cube-root") -> Outcome:
+        """Create a data-only starter project from engine-provided template data."""
+        guide = self._connection.reference()
+        choices = [item for item in guide["templates"] if item.get("id") == template]
+        if len(choices) != 1:
+            raise SDKError("SDK_TEMPLATE", "Unknown or ambiguous engine template.")
+        selected = choices[0]
+        destination = Path(directory).absolute()
+        if destination.exists() or destination.is_symlink():
+            raise SDKError("SDK_EXISTS", "Project destination already exists; no files were changed.")
+        if type(author) is not str or not author.strip():
+            raise SDKError("SDK_ARGUMENT", "An author name is required.")
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        with tempfile.TemporaryDirectory(prefix=".sdk-project-", dir=destination.parent) as temporary:
+            stage = Path(temporary)/"project"
+            (stage/"tests").mkdir(parents=True)
+            cases = []
+            for i,case in enumerate(selected["cases"]):
+                filename = f"tests/case_{i+1}.py"
+                (stage/filename).write_text(case["source"], encoding="utf-8", newline="\n")
+                cases.append({"name": case["name"], "file": filename, "expect": case["expect"]})
+            document = {"schema": PROJECT_SCHEMA, "declaration": selected["declaration"],
+                        "metadata": {"author": author, "created": date.today().isoformat(),
+                            "description": selected["description"], "license": "GPL-3.0-only"}, "cases": cases}
+            if guide.get("documentation", {}).get("schema") == "pycforge.extension-help/0.1":
+                document["schema"] = DOCUMENTED_PROJECT_SCHEMA
+                document["documentation"] = selected.get("documentation")
+            (stage/"project.json").write_bytes(canonical(document))
+            Project.load(stage)
+            stage.rename(destination)
+        project = Project.load(destination)
+        return {"directory": str(destination), "project_sha256": project.sha256,
+                "verification": "not-established", "connection": self._connection.description()}
+
+    @operation
+    def inspect(self, directory: str | Path) -> Outcome:
+        """Ask the engine to inspect the exact saved declaration; never run tests."""
+        project = Project.load(directory)
+        result = self._connection.call("inspect", {"declaration": project.document["declaration"]})
+        project.ensure_current()
+        return {"project_sha256": project.sha256, "inspection": result}
+
+    def _documentation_capability(self):
+        guide = self._connection.reference()
+        if guide.get("documentation", {}).get("schema") != "pycforge.extension-help/0.1":
+            raise SDKError("SDK_CAPABILITY", "Documented builds require PyCForge 1.3.64 or a compatible engine advertising extension-help/0.1. Existing project files were not changed.")
+
+    def _scan(self, project):
+        self._documentation_capability()
+        document = project.document
+        result = self._connection.call("scan", {"declaration": document["declaration"],
+                                               "documentation": document.get("documentation")})
+        issues = list(result["issues"])
+        if not issues:
+            cases = {case["name"]: case for case in document["cases"]}
+            for export, item in document["documentation"]["functions"].items():
+                case = cases.get(item["example"])
+                if case is None or case["expect"]["kind"] != "run":
+                    issues.append({"code": "SDK_DOCUMENTATION_EXAMPLE", "path": "/documentation/functions/" + export + "/example",
+                        "message": "Choose an existing native run fixture; rejected-source cases cannot be Help examples.",
+                        "remedy": "Add the fixture or select a run case from this project."})
+        if not issues:
+            bounded = self._connection.call("scan", {"declaration": document["declaration"],
+                "documentation": document["documentation"], "examples": self._examples(project)})
+            issues.extend(bounded["issues"])
+        project.ensure_current()
+        return {"schema": "pycforge-sdk.scan/0.1", "project_sha256": project.sha256,
+                "engine": dict(self._connection.snapshot.identity), "reference": result["reference"],
+                "template": result["template"], "coverage": result["coverage"], "issues": issues,
+                "state": "needs-authoring" if issues else "ready-to-verify",
+                "verification": "not-run", "checks": [
+                    {"id": "declaration", "status": "passed"},
+                    {"id": "documentation", "status": "incomplete" if result["issues"] else "passed"},
+                    {"id": "example-links", "status": "incomplete" if issues else "passed"},
+                    {"id": "native-verification", "status": "not-run"}]}
+
+    @operation
+    def scan(self, directory: str | Path) -> Outcome:
+        """Return a versioned readiness object and field locations; never run tests."""
+        result = self._scan(Project.load(directory))
+        return Outcome("rejected" if result["issues"] else "succeeded", {"scan": result}, tuple(result["issues"]))
+
+    @operation
+    def prepare_documentation(self, directory: str | Path) -> Outcome:
+        """Explicitly add missing author fields, preserving all existing prose.
+
+        Legacy projects are upgraded atomically to project/0.2. Generated blank
+        fields remain incomplete until the author supplies meaningful content.
+        Removed exports and changed argument meanings require explicit editing.
+        """
+        self._documentation_capability()
+        project = Project.load(directory)
+        document = project.document
+        result = self._connection.call("scan", {"declaration": document["declaration"]})
+        def fill(current, defaults):
+            if type(current) is dict and type(defaults) is dict:
+                return {**current, **{key: fill(current[key], value) if key in current else value
+                                     for key, value in defaults.items()}}
+            if type(current) is list and type(defaults) is list and len(current) < len(defaults):
+                return current + defaults[len(current):]
+            return current
+        existing = document.get("documentation")
+        document["documentation"] = result["template"] if existing is None else fill(existing, result["template"])
+        document["schema"] = DOCUMENTED_PROJECT_SCHEMA
+        project.ensure_current()
+        output = canonical(document)
+        if len(output) + sum(len(content) for _, content in project.sources) > MAX_PROJECT:
+            raise SDKError("SDK_PROJECT", "Documentation scaffolding would exceed the 4 MiB project budget; no files were changed.")
+        if output != project.document_bytes:
+            atomic_write(project.root / "project.json", output)
+        updated = Project.load(directory)
+        return {"project_sha256": updated.sha256, "changed": updated.sha256 != project.sha256,
+                "document": str(updated.root / "project.json"), "verification": "not-established",
+                "next": "Fill the author fields, run scan, then verify and build."}
+
+    @staticmethod
+    def _examples(project):
+        document = project.document
+        names = {item["example"] for item in document["documentation"]["functions"].values()}
+        sources = dict(project.sources)
+        return [{"name": case["name"], "source": sources[case["file"]].decode("utf-8"),
+                 **{k: case["expect"][k] for k in ("stdout", "stderr", "exit_code")}}
+                for case in sorted(document["cases"], key=lambda c: c["name"]) if case["name"] in names]
+
+    @staticmethod
+    def _documentation_coverage(project, inspection, cases):
+        by_name = {case["name"]: case for case in cases}
+        missing = []
+        for function in inspection["extension"]["functions"]:
+            example = project.document["documentation"]["functions"][function["export"]]["example"]
+            case = by_name.get(example)
+            if (case is None or case.get("passed") is not True or case["expected"]["kind"] != "run"
+                    or function["operation_id"] not in case.get("operations_used", [])):
+                missing.append(function["export"])
+        return {"kind": "documented-source-call-coverage", "missing": sorted(missing),
+                "scope": "Each Help example names a passing native fixture containing the documented operation; not dynamic branch or all-input coverage."}
+
+    @operation
+    def convert(self, directory: str | Path, case: str) -> Outcome:
+        """Convert a named fixture without compiling, executing or registering it."""
+        project = Project.load(directory)
+        cases = [item for item in project.document["cases"] if item["name"] == case]
+        if len(cases) != 1:
+            raise SDKError("SDK_CASE", "Unknown fixture name.")
+        result = self._convert(project, cases[0])
+        project.ensure_current()
+        status = "succeeded" if result.get("generated_c") else {
+            "Rejected": "rejected", "Canceled": "canceled", "InternalFailure": "internal_failure"}.get(result.get("status"), "incomplete")
+        return Outcome(status, {"project_sha256": project.sha256, "conversion": result})
+
+    def _convert(self, project, case):
+        source = dict(project.sources)[case["file"]].decode("utf-8")
+        return self._connection.call("convert", {"declaration": project.document["declaration"],
+                    "source": source, "logical_name": case["file"]})
+
+    @operation
+    def verify(self, directory: str | Path, *, compiler: str = "cc") -> Outcome:
+        """Explicitly convert, compile and execute the saved fixture suite.
+
+        Evidence covers those fixtures on the selected engine/compiler/host.
+        It is not a proof of all inputs and is not a security attestation.
+        """
+        project = Project.load(directory)
+        report = {"schema": REPORT_SCHEMA, "sdk_version": SDK_VERSION, "status": "incomplete",
+                  "project_sha256": project.sha256, "cases": []}
+        atomic_write(project.report_path, canonical(report))
+        try:
+            self._connection.ensure_current()
+            guide = self._connection.reference()
+            scanned = self._scan(project)
+            if scanned["issues"]:
+                raise SDKError("SDK_DOCUMENTATION_REQUIRED", "Complete the documentation and example links before verification.",
+                               details={"issues": scanned["issues"]})
+            report["engine"] = dict(self._connection.snapshot.identity)
+            inspection = self._connection.call("inspect", {"declaration": project.document["declaration"]})
+            report["extension_fingerprint"] = inspection["fingerprint"]
+            document = project.document
+            kinds = {case["expect"]["kind"] for case in document["cases"]}
+            policy = guide.get("verification", {})
+            if policy.get("policy") not in ("scalar-fixtures/0.1", "scalar-fixtures/0.2"):
+                raise SDKError("SDK_CAPABILITY", "Unsupported engine fixture policy.")
+            required_kinds = set(policy["required_case_kinds"])
+            if not required_kinds <= {"run", "reject"}:
+                raise SDKError("SDK_CAPABILITY", "Engine requires an unsupported fixture kind.")
+            if not required_kinds <= kinds:
+                raise SDKError("SDK_INCOMPLETE_SUITE", "Verification requires successful native fixtures and explicit rejected-source fixtures.")
+            toolchain = compiler_identity(compiler, guide["native_test"], timeout=self.timeout, cancel=self.cancel)
+            report["compiler"] = toolchain
+            for i,case in enumerate(document["cases"]):
+                self._notify("case", name=case["name"], index=i, total=len(document["cases"]))
+                result = self._convert(project, case)
+                if result["status"] in ("InternalFailure", "Canceled"):
+                    raise SDKError("SDK_ENGINE_RESULT", "Engine ended with " + result["status"],
+                        status="canceled" if result["status"] == "Canceled" else "internal_failure",
+                        details={"diagnostics": result["diagnostics"]})
+                check = {"name": case["name"], "file": case["file"], "expected": case["expect"],
+                         "conversion_status": result["status"], "diagnostics": result["diagnostics"],
+                         "generated_c_sha256": digest(result["generated_c"].encode()) if result.get("generated_c") else None}
+                check["operations_used"] = sorted({operation
+                    for extension in (result.get("conversion_summary") or {}).get("extensions", [])
+                    for operation in extension.get("operations_used", [])})
+                if case["expect"]["kind"] == "reject":
+                    check["passed"] = (result["status"] == "Rejected" and result.get("generated_c") is None
+                                       and case["expect"]["code"] in {d["code"] for d in result["diagnostics"]})
+                elif result.get("generated_c"):
+                    with tempfile.TemporaryDirectory(prefix="native-", dir=project.report_path.parent) as work:
+                        check.update(execute_fixture(result["generated_c"], case["expect"], toolchain, work,
+                                                     timeout=self.timeout, cancel=self.cancel))
+                else:
+                    check.update(passed=False, reason="Engine did not produce C for a native fixture.")
+                report["cases"].append(check)
+            project.ensure_current()
+            self._connection.ensure_current()
+            current_compiler = compiler_identity(toolchain["executable"], guide["native_test"], timeout=self.timeout, cancel=self.cancel)
+            if current_compiler != toolchain:
+                raise SDKError("SDK_STALE_COMPILER", "Compiler changed while verifying; re-run verification.")
+            coverage = self._coverage(inspection, report["cases"])
+            report["coverage"] = coverage
+            doc_coverage = self._documentation_coverage(project, inspection, report["cases"])
+            report["documentation"] = doc_coverage
+            complete = (policy["policy"] != "scalar-fixtures/0.2" or not coverage["missing"]) and not doc_coverage["missing"]
+            report["status"] = "passed" if complete and all(c["passed"] for c in report["cases"]) else "failed"
+            report["scope"] = guide["native_test"]["scope"]
+            report["evidence_sha256"] = digest(canonical(report))
+            atomic_write(project.report_path, canonical(report))
+            diagnostics = () if complete else ({"code": "SDK_INCOMPLETE_COVERAGE",
+                "message": "Every export and its linked Help example must occur in a passing native fixture.",
+                "details": {"missing": coverage["missing"], "documentation_missing": doc_coverage["missing"]}},)
+            return Outcome("succeeded" if report["status"] == "passed" else "rejected",
+                {"report": report, "report_file": str(project.report_path)}, diagnostics)
+        except (SDKError, OSError) as exc:
+            report["status"] = "canceled" if isinstance(exc, SDKError) and exc.status == "canceled" else "incomplete"
+            report["problem"] = {"code": getattr(exc, "code", "SDK_IO"), "message": str(exc)}
+            atomic_write(project.report_path, canonical(report))
+            raise
+
+    def _validated_evidence(self, project, *, selected_compiler=None):
+        """Single evidence gate used by readiness and packaging; never run fixtures."""
+        if not project.report_path.is_file():
+            raise SDKError("SDK_VERIFICATION_REQUIRED", "Run verify successfully before building this project.")
+        report = parse(read(project.report_path, 8*1024*1024))
+        if type(report) is not dict:
+            raise SDKError("SDK_EVIDENCE", "Malformed verification report; run verify again.")
+        self._connection.ensure_current()
+        guide = self._connection.reference()
+        supplied_digest = report.get("evidence_sha256")
+        if (report.get("schema") != REPORT_SCHEMA or report.get("sdk_version") != SDK_VERSION
+                or report.get("status") != "passed" or report.get("project_sha256") != project.sha256
+                or report.get("engine") != self._connection.snapshot.identity
+                or supplied_digest != digest(canonical({k:v for k,v in report.items() if k != "evidence_sha256"}))):
+            raise SDKError("SDK_STALE_EVIDENCE", "No complete passing verification matches this project and engine; run verify.")
+        policy = guide.get("verification", {})
+        kinds = {case["expect"]["kind"] for case in project.document["cases"]}
+        if policy.get("policy") not in ("scalar-fixtures/0.1", "scalar-fixtures/0.2"):
+            raise SDKError("SDK_CAPABILITY", "Unsupported engine fixture policy.")
+        if not set(policy.get("required_case_kinds", [])) <= kinds:
+            raise SDKError("SDK_INCOMPLETE_SUITE", "Verification requires native run and expected rejection fixtures.")
+        cases = report.get("cases", [])
+        expected = project.document["cases"]
+        if type(cases) is not list or len(cases) != len(expected) or any(type(c) is not dict or c.get("passed") is not True or c.get("name") != e["name"]
+                 or c.get("file") != e["file"] or c.get("expected") != e["expect"] for c,e in zip(cases,expected)):
+            raise SDKError("SDK_STALE_EVIDENCE", "Verification does not cover the complete current suite.")
+        compiler = report.get("compiler", {})
+        if type(compiler) is not dict:
+            raise SDKError("SDK_EVIDENCE", "Malformed compiler evidence; run verify again.")
+        if compiler_identity(selected_compiler or compiler.get("executable", ""), guide["native_test"], timeout=self.timeout, cancel=self.cancel) != compiler:
+            raise SDKError("SDK_STALE_COMPILER", "The recorded compiler or target profile changed; run verify.")
+        info = self._connection.call("inspect", {"declaration": project.document["declaration"]})
+        if info["fingerprint"] != report.get("extension_fingerprint"):
+            raise SDKError("SDK_STALE_EVIDENCE", "Candidate identity no longer matches the evidence.")
+        coverage = self._coverage(info, cases)
+        if guide.get("verification", {}).get("policy") == "scalar-fixtures/0.2" and (
+                coverage["missing"] or report.get("coverage") != coverage):
+            raise SDKError("SDK_INCOMPLETE_COVERAGE", "Verification must cover every exported operation; run verify.")
+        scanned = self._scan(project)
+        doc_coverage = self._documentation_coverage(project, info, cases) if not scanned["issues"] else None
+        if scanned["issues"] or doc_coverage["missing"] or report.get("documentation") != doc_coverage:
+            raise SDKError("SDK_DOCUMENTATION_REQUIRED", "Documentation and its examples must match complete current verification.",
+                           details={"issues": scanned["issues"]})
+        project.ensure_current()
+        self._connection.ensure_current()
+        return report, info, scanned
+
+    @operation
+    def readiness(self, directory: str | Path, *, compiler: str | None = None) -> Outcome:
+        """Check packaging readiness without compiling or running fixtures.
+
+        Identifies the compiler with its version command when evidence exists.
+        Only ready-to-package is a successful approval. All clients use this
+        same result; Build independently repeats the same evidence gate.
+        """
+        from .readiness import evaluate
+        return evaluate(self, directory, compiler=compiler)
+
+    @operation
+    def open_project(self, directory: str | Path) -> Outcome:
+        """Read an immutable editor snapshot without executing project code."""
+        from .editing import open_project
+        self._notify("read", name="Read saved project")
+        result = open_project(directory)
+        self._notify("read", name="Project loaded")
+        return result
+
+    @operation
+    def save_project(self, directory: str | Path, document: dict, *, expected_sha256: str) -> Outcome:
+        """Validate and atomically save project.json, refusing external edits."""
+        from .editing import save_project
+        self._notify("save", name="Validate and save project")
+        return save_project(directory, document, expected_sha256=expected_sha256)
+
+    @operation
+    def validate_project(self, directory: str | Path, document: dict, *, expected_sha256: str) -> Outcome:
+        """Check editor data and file budgets without saving or executing it."""
+        from .editing import current, validate_draft
+        self._notify("validate", name="Check project draft")
+        project = current(directory, expected_sha256)
+        data = validate_draft(project, document, dict(project.sources))
+        project.ensure_current()
+        self._notify("validate", name="Project draft checked")
+        return {"document": parse(data), "project_sha256": project.sha256}
+
+    @operation
+    def save_source(self, directory: str | Path, filename: str, source: str, *, expected_sha256: str) -> Outcome:
+        """Atomically save an existing fixture; preserve files on conflict/failure."""
+        from .editing import save_source
+        self._notify("save", name="Validate and save fixture")
+        return save_source(directory, filename, source, expected_sha256=expected_sha256)
+
+    @operation
+    def build(self, directory: str | Path, destination: str | Path, *, compiler: str | None = None) -> Outcome:
+        """Write a package only when complete passing evidence still matches."""
+        project = Project.load(directory)
+        report, info, scanned = self._validated_evidence(project, selected_compiler=compiler)
+        supplied_digest = report["evidence_sha256"]
+        content = self._package_content(project, report)
+        from .package_metadata import archive_format
+        package_format = archive_format(content)
+        project.ensure_current()
+        destination = Path(destination).absolute()
+        protected = {project.root/"project.json", project.report_path, *(project.root/name for name,_ in project.sources)}
+        if destination.resolve() in {path.resolve() for path in protected}:
+            raise SDKError("SDK_ARGUMENT", "Package output cannot overwrite project inputs or evidence.")
+        if destination.suffix != ".pcfplugin":
+            raise SDKError("SDK_ARGUMENT", "Package destination must end in .pcfplugin.")
+        atomic_write(destination, content)
+        return {"package": str(destination), "sha256": digest(content), "bytes": len(content),
+                "evidence_sha256": supplied_digest, "registered": False,
+                "package_format": package_format, "documentation": "complete",
+                "project_sha256": project.sha256, "package_version": info["extension"]["version"]}
+
+    def _package_content(self, project, report):
+        """Ask the selected engine to validate its inert archive in memory."""
+        supplied_digest = report["evidence_sha256"]
+        result = self._connection.call("package", {"declaration": project.document["declaration"],
+                   "metadata": project.document["metadata"],
+                   "documentation": project.document["documentation"], "examples": self._examples(project),
+                   "verification_producer": f"PyCForge SDK {SDK_VERSION}; fixture evidence {supplied_digest}"})
+        content = base64.b64decode(result["package_base64"], validate=True)
+        project.ensure_current()
+        return content
+
+    @staticmethod
+    def _coverage(inspection, cases):
+        required = {f["operation_id"] for f in inspection["extension"]["functions"]}
+        used = {operation for case in cases if case.get("passed") is True
+                and case["expected"]["kind"] == "run" for operation in case.get("operations_used", [])}
+        return {"kind": "source-call-coverage", "required": sorted(required),
+                "covered": sorted(required & used), "missing": sorted(required - used),
+                "scope": "Calls present in successfully executed fixture programs; not dynamic branch coverage or a proof of all inputs."}
+
+    @operation
+    def register(self, package: str | Path, *, store: str | Path | None = None) -> Outcome:
+        """Explicitly ask PyCForge to register a package in the selected registry."""
+        row = self._connection.call("register", {"file": str(Path(package).absolute()),
+                    "store": None if store is None else str(Path(store).absolute())})
+        return Outcome("succeeded" if row["status"] == "Ready" else "rejected", {"registration": row})

pycforge_sdk/workbench.py

@@ -0,0 +1,88 @@
+"""Validate a versioned engine-owned workbench; no library-name dispatch."""
+import re
+from .project import parse
+from .results import SDKError
+
+FEATURES = {"declaration-forms/1", "html-help/1", "import-catalogue/1"}
+KINDS = {"text", "multiline", "choice", "json", "boolean"}
+NAME = re.compile(r"[A-Za-z_][A-Za-z0-9_]{0,127}\Z")
+
+
+def require(condition, message):
+    if not condition:
+        raise SDKError("SDK_WORKBENCH", message + " Keep the last compatible reference or update the SDK.")
+
+
+def text(value):
+    return type(value) is str and 0 < len(value) <= 8192
+
+
+def validate(snapshot):
+    """Major 1 permits additive metadata; unknown required semantics are refused."""
+    raw = snapshot.files.get("workbench.json")
+    if raw is None:
+        return None
+    data = parse(raw)
+    require(type(data) is dict and type(data.get("schema")) is str and
+            re.fullmatch(r"pycforge\.sdk-workbench/1\.[0-9]+", data["schema"]), "Unsupported workbench schema.")
+    features = data.get("required_features")
+    require(type(features) is list and all(type(x) is str for x in features) and
+            set(features) <= FEATURES and len(features) == len(set(features)), "Unsupported workbench requirements.")
+    profiles = data.get("profiles")
+    require(type(profiles) is list and 1 <= len(profiles) <= 256, "Invalid authoring profiles.")
+    schemas = set()
+    for profile in profiles:
+        require(type(profile) is dict and text(profile.get("declaration_schema")) and text(profile.get("title")), "Incomplete authoring profile.")
+        require(profile["declaration_schema"] not in schemas, "Duplicate authoring profile.")
+        require(type(profile.get("description", "")) is str and len(profile.get("description", "")) <= 8192, "Invalid profile explanation.")
+        schemas.add(profile["declaration_schema"])
+        for group in ("fields", "function_fields"):
+            fields = profile.get(group)
+            require(type(fields) is list and len(fields) <= 128, "Invalid authoring fields.")
+            names = set()
+            for field in fields:
+                require(type(field) is dict and type(field.get("name")) is str and NAME.fullmatch(field["name"]), "Invalid field name.")
+                require(field["name"] not in names and field["name"] != "schema", "Duplicate or reserved authoring field.")
+                names.add(field["name"])
+                require(text(field.get("title")) and type(field.get("description", "")) is str and
+                        len(field.get("description", "")) <= 8192, "Missing field explanation.")
+                require(field.get("kind") in KINDS and type(field.get("advanced", False)) is bool, "Unsupported authoring control.")
+                if field["kind"] == "choice":
+                    options = field.get("options")
+                    require(type(options) is list and 1 <= len(options) <= 1024, "Invalid operation choices.")
+                    values = []
+                    for option in options:
+                        require(type(option) is dict and text(option.get("title")) and
+                                type(option.get("value")) in (str, int, float, bool, type(None)), "Invalid operation choice.")
+                        identity = (type(option["value"]), option["value"])
+                        require(identity not in values, "Duplicate operation choice.")
+                        values.append(identity)
+                        for key in ("description", "signature"):
+                            require(type(option.get(key, "")) is str and len(option.get(key, "")) <= 8192, "Invalid operation explanation.")
+        operation = profile.get("operation_field", "")
+        require(type(operation) is str and (not operation or operation in {f["name"] for f in profile["function_fields"]}), "Unknown operation field.")
+        require(type(profile.get("contract_note", "")) is str and len(profile.get("contract_note", "")) <= 8192, "Invalid contract explanation.")
+    docs, ids = [], set()
+    guides, imports = data.get("help"), data.get("imports")
+    require(type(guides) is list and 1 <= len(guides) <= 128 and type(imports) is list and len(imports) <= 1024, "Invalid Help inventory.")
+    def document(key, title, resource):
+        require(text(key) and key not in ids and text(title) and type(resource) is str and
+                resource.endswith('.html') and resource in snapshot.files, "Help resource is missing or duplicated.")
+        ids.add(key)
+        try:
+            content = snapshot.files[resource].decode('utf-8')
+        except UnicodeError as exc:
+            raise SDKError("SDK_WORKBENCH", "Engine Help must be UTF-8.") from exc
+        docs.append({"id": key, "title": title, "html": content, "resource": resource})
+    for guide in guides:
+        require(type(guide) is dict, "Invalid guide entry.")
+        document(guide.get("id"), guide.get("title"), guide.get("resource"))
+    namespaces = set()
+    for item in imports:
+        require(type(item) is dict and all(text(item.get(key)) for key in
+                ("id", "namespace", "version", "profile", "description")), "Incomplete import description.")
+        require(item["namespace"] not in namespaces, "Duplicate bundled import namespace.")
+        namespaces.add(item["namespace"])
+        require(type(item.get("operation_count")) is int and item["operation_count"] >= 0, "Invalid import operation count.")
+        document("import:" + item["namespace"], "*import " + item["namespace"] + " · " + item["version"], item.get("help_resource"))
+    return {"definition": data, "documents": docs}