syntara-plugin-contracts 0.1.0a1__tar.gz

syntara_plugin_contracts-0.1.0a1/.gitignore

@@ -0,0 +1,66 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# uv
+.uv/
+
+# Step SDK specific
+*.compiled.json
+step-definition.json
+examples/*/step-definition.json
+
+# Databases
+*.db
+*.sqlite
+*.sqlite3
+
+# Logs
+*.log
+
+# Environment variables
+.env
+.env.local
+coverage.xml

syntara_plugin_contracts-0.1.0a1/PKG-INFO

@@ -0,0 +1,37 @@
+Metadata-Version: 2.5
+Name: syntara-plugin-contracts
+Version: 0.1.0a1
+Summary: Versioned contracts and deterministic bundles for Syntara plugins
+Project-URL: Homepage, https://github.com/syntara-orchestration/syntara-plugin-sdk
+Project-URL: Repository, https://github.com/syntara-orchestration/syntara-plugin-sdk
+Project-URL: Issues, https://github.com/syntara-orchestration/syntara-plugin-sdk/issues
+License-Expression: Apache-2.0
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: grpcio>=1.78.0
+Requires-Dist: jsonschema>=4.23
+Requires-Dist: protobuf>=6.31.1
+Requires-Dist: pydantic>=2.0
+Requires-Dist: referencing>=0.37
+Description-Content-Type: text/markdown
+
+# Syntara Plugin Contracts
+
+`syntara-plugin-contracts` distributes the versioned Syntara Plugin contract
+bundle and runtime APIs. It contains the canonical JSON Schemas, conformance
+fixtures, protocol definitions, and the Python APIs used by plugin workload
+implementers and the SDK. It also installs the `syntara-plugin-runtime-server`
+console script, which a final Python workload image uses to serve the container
+ABI.
+
+The source of truth is maintained in the
+[Syntara Plugin SDK repository](https://github.com/syntara-orchestration/syntara-plugin-sdk).
+Install `syntara-plugin-sdk` to author plugins. Depend on this package directly
+when implementing another contract-aware tool or plugin workload runtime.

syntara_plugin_contracts-0.1.0a1/README.md

@@ -0,0 +1,13 @@
+# Syntara Plugin Contracts
+
+`syntara-plugin-contracts` distributes the versioned Syntara Plugin contract
+bundle and runtime APIs. It contains the canonical JSON Schemas, conformance
+fixtures, protocol definitions, and the Python APIs used by plugin workload
+implementers and the SDK. It also installs the `syntara-plugin-runtime-server`
+console script, which a final Python workload image uses to serve the container
+ABI.
+
+The source of truth is maintained in the
+[Syntara Plugin SDK repository](https://github.com/syntara-orchestration/syntara-plugin-sdk).
+Install `syntara-plugin-sdk` to author plugins. Depend on this package directly
+when implementing another contract-aware tool or plugin workload runtime.

syntara_plugin_contracts-0.1.0a1/hatch_build.py

@@ -0,0 +1,31 @@
+"""Stage canonical SDK contracts in both wheels and source distributions."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class CustomBuildHook(BuildHookInterface):
+    """Include the one canonical contract tree without a checked-in copy.
+
+    A source distribution must rebuild without a checkout of the whole SDK
+    workspace. During an sdist build this hook maps canonical repository files
+    into the Python package path. During a wheel build from that sdist those
+    staged files already exist in the package, so no external path is needed.
+    """
+
+    def initialize(self, version: str, build_data: dict[str, Any]) -> None:
+        package_contracts = Path(self.root) / "src/syntara_plugin/contracts"
+        required = ("schemas", "fixtures", "proto")
+        if all((package_contracts / name).is_dir() for name in required):
+            return
+
+        canonical_contracts = Path(self.root).parents[3] / "contracts"
+        for name in required:
+            source = canonical_contracts / name
+            if not source.is_dir():
+                raise RuntimeError(f"canonical contract directory is missing: {source}")
+            build_data["force_include"][str(source)] = f"src/syntara_plugin/contracts/{name}"

syntara_plugin_contracts-0.1.0a1/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "syntara-plugin-contracts"
+version = "0.1.0a1"
+description = "Versioned contracts and deterministic bundles for Syntara plugins"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.12"
+dependencies = [
+  "grpcio>=1.78.0",
+  "jsonschema>=4.23",
+  "protobuf>=6.31.1",
+  "pydantic>=2.0",
+  "referencing>=0.37",
+]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+
+[project.scripts]
+syntara-plugin-runtime-server = "syntara_plugin.runtime.server:main"
+
+[project.urls]
+Homepage = "https://github.com/syntara-orchestration/syntara-plugin-sdk"
+Repository = "https://github.com/syntara-orchestration/syntara-plugin-sdk"
+Issues = "https://github.com/syntara-orchestration/syntara-plugin-sdk/issues"
+
+[build-system]
+# Keep release builds reproducible; upgrades are reviewed like any other
+# build-tool supply-chain change.
+requires = ["hatchling==1.32.4"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/syntara_plugin"]
+
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"

syntara_plugin_contracts-0.1.0a1/src/syntara_plugin/contracts/__init__.py

@@ -0,0 +1,45 @@
+"""Normative, versioned Syntara plugin contracts."""
+
+from .bundle import (
+    CatalogCheckpoint,
+    CatalogDiagnostic,
+    ContractBundle,
+    bundle_digest,
+    load_bundle,
+    validate_catalog_index,
+    validate_document,
+)
+from .canonical import (
+    CanonicalJsonError,
+    canonical_json_bytes,
+    canonical_json_digest,
+    container_workload_request_digest,
+)
+from .descriptor import (
+    materialized_schemas,
+    schema_digests,
+    validate_plugin_descriptor_semantics,
+)
+from .fixtures import FixtureBundle, fixture_content_digest, load_fixture_bundle
+from .image import is_digest_image_reference
+
+__all__ = [
+    "CatalogCheckpoint",
+    "CatalogDiagnostic",
+    "CanonicalJsonError",
+    "ContractBundle",
+    "FixtureBundle",
+    "bundle_digest",
+    "canonical_json_bytes",
+    "canonical_json_digest",
+    "container_workload_request_digest",
+    "fixture_content_digest",
+    "load_bundle",
+    "load_fixture_bundle",
+    "materialized_schemas",
+    "schema_digests",
+    "validate_plugin_descriptor_semantics",
+    "is_digest_image_reference",
+    "validate_catalog_index",
+    "validate_document",
+]

syntara_plugin_contracts-0.1.0a1/src/syntara_plugin/contracts/bundle.py

@@ -0,0 +1,277 @@
+"""Load and validate the self-contained v1alpha1 contract bundle."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import datetime
+from importlib.resources import files
+from pathlib import Path
+from typing import Any, Literal
+
+from jsonschema import Draft202012Validator, FormatChecker
+from referencing import Registry, Resource
+
+ContractKind = Literal[
+    "plugin",
+    "plugin_build_settings",
+    "action",
+    "control",
+    "trigger",
+    "step",
+    "plugin_descriptor",
+    "runtime",
+    "provider",
+    "catalog_index",
+    "catalog_source",
+    "catalog_source_status",
+    "integration",
+    "http_mapping",
+    "http_runner_context",
+    "credential_recipe",
+    "trigger_driver",
+    "trigger_event_mapping",
+    "installed_identity",
+]
+_SCHEMA_FILES: dict[ContractKind, str] = {
+    "plugin": "plugin.schema.json",
+    "plugin_build_settings": "plugin-build-settings.schema.json",
+    "action": "action.schema.json",
+    "control": "control.schema.json",
+    "trigger": "trigger.schema.json",
+    "step": "step.schema.json",
+    "plugin_descriptor": "plugin-descriptor.schema.json",
+    "runtime": "runtime.schema.json",
+    "provider": "provider.schema.json",
+    "catalog_index": "catalog-index.schema.json",
+    "catalog_source": "catalog-source.schema.json",
+    "catalog_source_status": "catalog-source-status.schema.json",
+    "integration": "integration.schema.json",
+    "http_mapping": "http-operation.schema.json",
+    "http_runner_context": "http-runner-context.schema.json",
+    "credential_recipe": "credential-recipe.schema.json",
+    "trigger_driver": "trigger-driver.schema.json",
+    "trigger_event_mapping": "trigger-event-mapping.schema.json",
+    "installed_identity": "installed-identity.schema.json",
+}
+_RFC3339_DATETIME = re.compile(
+    r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$"
+)
+_FORMAT_CHECKER = FormatChecker()
+
+
+@_FORMAT_CHECKER.checks("date-time", raises=ValueError)
+def _is_rfc3339_datetime(value: object) -> bool:
+    """Accept the RFC 3339 subset used by Syntara runtime envelopes."""
+
+    if not isinstance(value, str) or not _RFC3339_DATETIME.fullmatch(value):
+        return False
+    datetime.fromisoformat(value.removesuffix("Z") + "+00:00" if value.endswith("Z") else value)
+    return True
+
+
+@dataclass(frozen=True)
+class ContractBundle:
+    """An immutable in-process view of the packaged contract documents."""
+
+    version: str
+    digest: str
+    documents: dict[str, dict[str, Any]]
+
+    def validator(self, kind: ContractKind) -> Draft202012Validator:
+        """Return a validator with every local schema in this bundle registered."""
+        target = self.documents[_SCHEMA_FILES[kind]]
+        registry = Registry().with_resources(
+            (document["$id"], Resource.from_contents(document))
+            for document in self.documents.values()
+        )
+        return Draft202012Validator(
+            target,
+            registry=registry,
+            format_checker=_FORMAT_CHECKER,
+        )
+
+
+def _schema_directory() -> Any:
+    packaged = files("syntara_plugin.contracts").joinpath("schemas", "v1alpha1")
+    if packaged.is_dir():
+        return packaged
+    # Editable source installs consume the repository's language-neutral source.
+    for parent in Path(__file__).resolve().parents:
+        source = parent / "contracts" / "schemas" / "v1alpha1"
+        if source.is_dir():
+            return source
+    raise RuntimeError("cannot locate packaged or repository contract schemas")
+
+
+def _canonical_bytes(documents: dict[str, dict[str, Any]]) -> bytes:
+    payload = {path: documents[path] for path in sorted(documents)}
+    return json.dumps(payload, ensure_ascii=False, separators=(",", ":"), sort_keys=True).encode(
+        "utf-8"
+    )
+
+
+def bundle_digest(documents: dict[str, dict[str, Any]]) -> str:
+    """Return the stable SHA-256 digest of a complete contract bundle."""
+    return "sha256:" + hashlib.sha256(_canonical_bytes(documents)).hexdigest()
+
+
+def load_bundle() -> ContractBundle:
+    """Load the packaged, local-only `syntara.io/v1alpha1` contract bundle."""
+    directory = _schema_directory()
+    documents: dict[str, dict[str, Any]] = {}
+    for entry in sorted(directory.iterdir(), key=lambda item: item.name):
+        if entry.name.endswith(".schema.json"):
+            documents[entry.name] = json.loads(entry.read_text(encoding="utf-8"))
+    if set(_SCHEMA_FILES.values()) - set(documents):
+        raise RuntimeError("contract bundle is missing a required manifest or runtime schema")
+    return ContractBundle(
+        version="syntara.io/v1alpha1",
+        digest=bundle_digest(documents),
+        documents=documents,
+    )
+
+
+def validate_document(bundle: ContractBundle, kind: ContractKind, document: object) -> list[str]:
+    """Return stable, path-prefixed JSON Schema validation errors."""
+    errors = sorted(
+        bundle.validator(kind).iter_errors(document), key=lambda error: list(error.path)
+    )
+    return [
+        f"{'/'.join(str(part) for part in error.path) or '<root>'}: {error.message}"
+        for error in errors
+    ]
+
+
+@dataclass(frozen=True)
+class CatalogCheckpoint:
+    """Last accepted immutable catalog state for one configured source.
+
+    The caller persists this state. The contracts package only compares a
+    candidate index to it; it does not fetch, verify signatures, or write data.
+    """
+
+    generation: int = 0
+    index_digest: str | None = None
+
+
+@dataclass(frozen=True, order=True)
+class CatalogDiagnostic:
+    """Stable, non-secret reason returned when a catalog candidate is rejected."""
+
+    code: str
+    path: str
+    message: str
+
+
+def validate_catalog_index(
+    bundle: ContractBundle,
+    document: Mapping[str, Any],
+    *,
+    source_id: str,
+    now: datetime,
+    checkpoint: CatalogCheckpoint | None = None,
+) -> tuple[CatalogDiagnostic, ...]:
+    """Validate a catalog index against one source's replay checkpoint.
+
+    This is intentionally a pure control-plane contract check. OCI resolution,
+    signature verification, repository-scope checks, and persistence are owned
+    by the catalog service that calls it.
+    """
+
+    checkpoint = checkpoint or CatalogCheckpoint()
+    schema_errors = validate_document(bundle, "catalog_index", document)
+    if schema_errors:
+        return tuple(
+            CatalogDiagnostic(
+                code="CATALOG_INDEX_SCHEMA_INVALID",
+                path=message.partition(":")[0],
+                message=message,
+            )
+            for message in schema_errors
+        )
+    if now.tzinfo is None or now.utcoffset() is None:
+        raise ValueError("now must be timezone-aware")
+
+    metadata = document["metadata"]
+    specification = document["spec"]
+    diagnostics: list[CatalogDiagnostic] = []
+    if metadata["sourceId"] != source_id:
+        diagnostics.append(
+            CatalogDiagnostic(
+                code="CATALOG_INDEX_SOURCE_MISMATCH",
+                path="metadata/sourceId",
+                message="Catalog index sourceId does not match the configured source.",
+            )
+        )
+    if specification["contractVersion"] != bundle.version:
+        diagnostics.append(
+            CatalogDiagnostic(
+                code="CATALOG_INDEX_CONTRACT_UNSUPPORTED",
+                path="spec/contractVersion",
+                message=f"Catalog index contract must be {bundle.version!r}.",
+            )
+        )
+
+    issued_at = _parse_rfc3339(metadata["issuedAt"])
+    expires_at = _parse_rfc3339(metadata["expiresAt"])
+    if expires_at <= issued_at:
+        diagnostics.append(
+            CatalogDiagnostic(
+                code="CATALOG_INDEX_TIME_WINDOW_INVALID",
+                path="metadata/expiresAt",
+                message="Catalog index expiresAt must be later than issuedAt.",
+            )
+        )
+    if expires_at <= now:
+        diagnostics.append(
+            CatalogDiagnostic(
+                code="CATALOG_INDEX_EXPIRED",
+                path="metadata/expiresAt",
+                message="Catalog index is expired at the supplied reconciliation time.",
+            )
+        )
+    if metadata["generation"] <= checkpoint.generation:
+        diagnostics.append(
+            CatalogDiagnostic(
+                code="CATALOG_INDEX_GENERATION_REPLAY",
+                path="metadata/generation",
+                message="Catalog index generation must be greater than the accepted generation.",
+            )
+        )
+    if (
+        checkpoint.index_digest is not None
+        and metadata.get("previousIndexDigest") != checkpoint.index_digest
+    ):
+        diagnostics.append(
+            CatalogDiagnostic(
+                code="CATALOG_INDEX_PREDECESSOR_MISMATCH",
+                path="metadata/previousIndexDigest",
+                message="Catalog index predecessor does not match the accepted index digest.",
+            )
+        )
+
+    seen_identities: set[tuple[str, str, str]] = set()
+    for index, entry in enumerate(specification["entries"]):
+        identity = (entry["namespace"], entry["name"], entry["version"])
+        if identity in seen_identities:
+            diagnostics.append(
+                CatalogDiagnostic(
+                    code="CATALOG_ENTRY_IDENTITY_DUPLICATE",
+                    path=f"spec/entries/{index}",
+                    message="Catalog index entries must not repeat namespace, name, and version.",
+                )
+            )
+        seen_identities.add(identity)
+    return tuple(sorted(diagnostics))
+
+
+def _parse_rfc3339(value: str) -> datetime:
+    """Parse a value already checked by the bundle's strict date-time format."""
+
+    return datetime.fromisoformat(
+        value.removesuffix("Z") + "+00:00" if value.endswith("Z") else value
+    )

syntara_plugin_contracts-0.1.0a1/src/syntara_plugin/contracts/canonical.py

@@ -0,0 +1,60 @@
+"""Normative canonical JSON and generic-container request hashing helpers."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Mapping
+from copy import deepcopy
+from typing import Any
+
+
+class CanonicalJsonError(ValueError):
+    """A value cannot be represented by the Syntara canonical JSON form."""
+
+
+def canonical_json_bytes(value: object) -> bytes:
+    """Return the strict deterministic JSON form used by versioned contracts.
+
+    The format is UTF-8 JSON with sorted object keys, compact separators, and
+    no non-finite numbers. Other language SDKs must implement this exact form
+    before they calculate a compatible request hash.
+    """
+
+    try:
+        return json.dumps(
+            value,
+            allow_nan=False,
+            ensure_ascii=False,
+            separators=(",", ":"),
+            sort_keys=True,
+        ).encode("utf-8")
+    except (TypeError, ValueError) as error:
+        raise CanonicalJsonError("value is not canonical JSON") from error
+
+
+def canonical_json_digest(value: object) -> str:
+    """Return the SHA-256 digest of one canonical JSON value."""
+
+    return f"sha256:{hashlib.sha256(canonical_json_bytes(value)).hexdigest()}"
+
+
+def container_workload_request_digest(request: Mapping[str, Any]) -> str:
+    """Hash a container workload request without its two mirrored hash fields.
+
+    The work-item and policy snapshot each carry the resulting digest. Removing
+    both fields before hashing avoids a circular representation while ensuring
+    every other execution, policy, and runtime value is committed.
+    """
+
+    try:
+        canonical_request = deepcopy(dict(request))
+        for section_name in ("workItem", "policySnapshot"):
+            section = canonical_request.get(section_name)
+            if isinstance(section, Mapping):
+                section_copy = dict(section)
+                section_copy.pop("requestHash", None)
+                canonical_request[section_name] = section_copy
+    except (TypeError, ValueError) as error:
+        raise CanonicalJsonError("container workload request is not canonical JSON") from error
+    return canonical_json_digest(canonical_request)