mkp-contracts 0.2.0__py3-none-any.whl

mkp_contracts/__init__.py

@@ -0,0 +1,12 @@
+"""The contracts that cross component boundaries, as code.
+
+`schema/` holds them as data; this holds the rules a schema cannot express — what a
+bundle's canonical form is, therefore what its digest is, therefore what its identity
+is. Both the builder and the control plane depend on this rather than on each other,
+because "what is this bundle" must have one answer and neither of them owns it.
+
+A library, deliberately: no CLI, no side effects, no I/O beyond reading a document it
+was handed.
+"""
+
+__version__ = "0.1.0"

mkp_contracts/archive.py

@@ -0,0 +1,70 @@
+"""What is inside a bundle archive, and whether it is what it claims to be.
+
+Here for the same reason `canonical.py` is: **a bundle's identity is the digest of its
+manifest, not the hash of its archive**, so "does this archive belong under this
+digest?" is not a question either the builder or the control plane can answer alone
+without one of them defining the answer for the other.
+
+The distinction bites the first time someone stores an archive. Two builds of identical
+content produce byte-identical archives — that is what the `filename=""` in the gzip
+header exists for — but the archive is still not the identity: the manifest inside it
+is, and it is the manifest that `signature` covers and that `created` is excluded from.
+An implementation that filed archives under `sha256(bytes)` would be filing them under a
+name nothing else in the system uses.
+"""
+
+from __future__ import annotations
+
+import io
+import json
+import tarfile
+from typing import Any
+
+from .canonical import manifest_digest
+from .errors import ContractError
+
+MANIFEST_NAME = "manifest.json"
+
+# A bundle is workflows, machines and small assets. Refusing to expand beyond this is
+# what stops a crafted archive turning a read into a memory exhaustion — the check
+# happens before the tar is walked, on a number the header states rather than on what
+# it actually contains.
+MAX_ARCHIVE_BYTES = 64 * 1024 * 1024
+
+
+def manifest_of(archive: bytes) -> dict[str, Any]:
+    """The manifest at the root of an archive."""
+    if len(archive) > MAX_ARCHIVE_BYTES:
+        raise ContractError(f"archive is larger than {MAX_ARCHIVE_BYTES} bytes")
+    try:
+        with tarfile.open(fileobj=io.BytesIO(archive), mode="r:gz") as tar:
+            member = tar.extractfile(MANIFEST_NAME)
+            if member is None:
+                raise ContractError(f"no {MANIFEST_NAME} at the root of the archive")
+            return json.loads(member.read())
+    except tarfile.TarError as exc:
+        raise ContractError(f"not a readable bundle archive: {exc}") from exc
+    except ValueError as exc:
+        raise ContractError(f"{MANIFEST_NAME} is not JSON: {exc}") from exc
+
+
+def digest_of(archive: bytes) -> str:
+    """The bundle identity this archive carries.
+
+    Read off the manifest inside, never off the bytes: the archive is a container and
+    the manifest is the thing with a name.
+    """
+    return manifest_digest(manifest_of(archive))
+
+
+def belongs_under(archive: bytes, digest: str) -> bool:
+    return digest_of(archive) == digest
+
+
+__all__ = [
+    "MANIFEST_NAME",
+    "MAX_ARCHIVE_BYTES",
+    "belongs_under",
+    "digest_of",
+    "manifest_of",
+]

mkp_contracts/canonical.py

@@ -0,0 +1,42 @@
+"""Canonical form and digests.
+
+A bundle's identity is the digest of its content (ADR 0008), which only works if
+building the same content twice produces the same digest. Three manifest fields
+are therefore outside the canonical form:
+
+- `created` is a build timestamp; including it would give identical content two
+  identities and defeat the whole model — promote-by-digest, "nothing is rebuilt",
+  and "a superseded bundle is retained until no run references it" all rest on
+  content and identity being the same thing.
+- `source` is documented in `bundle.schema.json` as informational: "identity is
+  the content digest, not this".
+- `signature` cannot be inside the bytes it signs.
+
+The signature covers exactly these canonical bytes, so there is one canonical
+form and not two.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+EXCLUDED_FROM_IDENTITY = ("created", "source", "signature")
+
+
+def canonical_bytes(document: dict[str, Any]) -> bytes:
+    """The bytes a digest and a signature are both computed over."""
+    stripped = {k: v for k, v in document.items() if k not in EXCLUDED_FROM_IDENTITY}
+    return json.dumps(stripped, sort_keys=True, separators=(",", ":"), ensure_ascii=False).encode(
+        "utf-8"
+    )
+
+
+def manifest_digest(manifest: dict[str, Any]) -> str:
+    """The bundle's identity: sha256 over the canonical manifest, bare hex."""
+    return hashlib.sha256(canonical_bytes(manifest)).hexdigest()
+
+
+def file_digest(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()

mkp_contracts/cli_versions.py

@@ -0,0 +1,34 @@
+"""The CLI versions the control plane serves (ADR 0014, `C33`).
+
+Here rather than in the api, because this package is where wire compatibility
+already lives: the PR that changes a canonical form is the PR that moves
+`CLI_MINIMUM`, reviewed as one change. `CLI_LATEST` moves in the commit that tags a
+CLI release — `release-cli.yml` fails when the tag disagrees, so the two cannot
+drift silently.
+"""
+
+from __future__ import annotations
+
+# The oldest mkctl the wire still serves. Raised deliberately, in the same PR as the
+# change that stops serving older ones — never as housekeeping.
+CLI_MINIMUM = "0.1.0"
+
+# What `mkctl upgrade` and the login advisory point at. 0.4.0 is the first version on
+# PyPI: before it, `mkbundle` and this package shipped as `0.1.0` in three different
+# GitHub releases, which is three builds behind one number — fine for assets fetched by
+# tag, wrong for an index where a version is permanent.
+CLI_LATEST = "0.4.0"
+
+
+def parse(version: str) -> tuple[int, ...] | None:
+    """`"0.2.0"` → `(0, 2, 0)`; anything else → None.
+
+    None means "do not gate": a User-Agent this module cannot read belongs to a
+    client this contract does not cover, and refusing what you cannot parse would
+    gate curl and every future tool along with it.
+    """
+    parts = version.strip().split(".")
+    try:
+        return tuple(int(part) for part in parts)
+    except ValueError:
+        return None

mkp_contracts/errors.py

@@ -0,0 +1,69 @@
+"""Failures, reported as data rather than raised one at a time.
+
+A build reports every rule a bundle breaks, not the first. Fixing one problem
+only to be told about the next is what makes a validator feel like an obstacle
+instead of a tool.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Failure:
+    """One broken rule, attributable to one place."""
+
+    rule: str
+    """Stable id, e.g. `machine-missing`. Cited in messages and in tests."""
+
+    message: str
+
+    path: str = ""
+    """Bundle-relative path of the document at fault, when there is one."""
+
+    location: str = ""
+    """Where inside the document, e.g. `steps[2].idempotency_key`."""
+
+    def __str__(self) -> str:
+        where = self.path or "<bundle>"
+        if self.location:
+            where = f"{where}:{self.location}"
+        return f"{where}: [{self.rule}] {self.message}"
+
+    def as_dict(self) -> dict[str, str]:
+        return {
+            "rule": self.rule,
+            "message": self.message,
+            "path": self.path,
+            "location": self.location,
+        }
+
+
+@dataclass
+class Report:
+    """The outcome of a validation or a build."""
+
+    failures: list[Failure] = field(default_factory=list)
+    skipped_rules: list[str] = field(default_factory=list)
+    """Rules that could not run. Never silent: a build says what it did not check."""
+
+    @property
+    def ok(self) -> bool:
+        return not self.failures
+
+    def fail(self, rule: str, message: str, path: str = "", location: str = "") -> None:
+        self.failures.append(Failure(rule, message, path, location))
+
+    def extend(self, other: Report) -> None:
+        self.failures.extend(other.failures)
+        self.skipped_rules.extend(other.skipped_rules)
+
+
+class ContractError(Exception):
+    """A document cannot be read or placed against a contract at all.
+
+    Distinct from a `Failure`: a failure is a rule a document breaks, reported
+    alongside every other one. This is the case where there is nothing to report
+    on — an unparseable file, a missing schema, a document of no known kind.
+    """

mkp_contracts/expressions.py

@@ -0,0 +1,103 @@
+"""The `{{ … }}` grammar a workflow document may use.
+
+The runner evaluates these and the builder must refuse the ones it cannot. Those two
+answers have to be the same answer, or a bundle validates, signs, deploys, and then
+dies on the first run that reaches the step — which is exactly what happened to
+`schedule_mail`'s effect branches: `not a and b` is not in this grammar, and `a == 'x'
+or b == 'y'` parsed as a comparison against the *literal* `"x' or b == 'y"`, so the
+step silently never ran.
+
+So the grammar lives here, beside the canonical form and the gate vocabulary, and
+neither side owns it:
+
+* **path** — `inputs.a.b`, `steps.<id>.<result_path>…`, `run.id`
+* **comparison against a literal** — `<path> == 'routine'`, `!=`
+
+No boolean operators, no arithmetic, no calls. A workflow that can compute is a
+workflow that can compute its way around the control-flow guard (ADR 0005); anything
+that genuinely needs computing belongs in a `code` step. Combining conditions is done
+with nesting — an `if:` on a branch and a `when:` on its case.
+"""
+
+from __future__ import annotations
+
+import re
+
+from .gates import scalar
+
+TEMPLATE = re.compile(r"\{\{(.*?)\}\}", re.DOTALL)
+COMPARISON = re.compile(r"^(?P<left>[\w.]+)\s*(?P<op>==|!=)\s*(?P<right>.+)$")
+PATH = re.compile(r"[\w.]+")
+#: `secrets` is accepted as a root here because `requires.secrets` and the
+#: `undeclared-secret` rule treat `{{ secrets.x }}` as a legitimate document form.
+#: The interpreter's own scope holds the other three.
+ROOTS = ("inputs", "steps", "run", "secrets")
+
+_REFUSED = object()
+
+#: Words that read as operators but are not in the grammar. Named so the refusal can
+#: say what to do instead rather than only that the expression is wrong.
+_OPERATORS = ("not", "and", "or")
+
+
+def refusal(expression: str) -> str | None:
+    """Why this expression cannot be evaluated, or ``None`` when it can.
+
+    The literal check matters as much as the shape: an unquoted or half-quoted
+    right-hand side is the failure that does not raise, it just compares false forever.
+    """
+    text = expression.strip()
+    if not text:
+        return "an empty expression reads nothing"
+
+    comparison = COMPARISON.match(text)
+    if comparison:
+        right = comparison.group("right").strip()
+        if _literal_refused(right):
+            return (
+                f"{right!r} is not a literal. The right-hand side of a comparison is a "
+                "quoted string, a number, true, false or null — never another "
+                "expression. Note that a value like \"'a' or x == 'b'\" is read as one "
+                "quoted string and compares false forever, in silence"
+            )
+        return _root_refusal(comparison.group("left"))
+
+    if not PATH.fullmatch(text):
+        for word in _OPERATORS:
+            if re.search(rf"\b{word}\b", text):
+                return (
+                    f"{text!r} uses {word!r}, which this language does not have. An "
+                    "expression is a path or a path compared against a literal; combine "
+                    "conditions by nesting (`if:` on a branch, `when:` on its case) or "
+                    "decide in a `code` step"
+                )
+        return (
+            f"{text!r} is not an expression this language has. A workflow may read a "
+            "path or compare one against a literal; anything more belongs in a code step"
+        )
+
+    return _root_refusal(text)
+
+
+def _root_refusal(path: str) -> str | None:
+    root = path.split(".")[0]
+    if root not in ROOTS:
+        return f"unknown root {root!r} in {path!r}; an expression may read {', '.join(ROOTS)}"
+    return None
+
+
+def _literal_refused(text: str) -> bool:
+    if len(text) >= 2 and text[0] == text[-1] and text[0] in "'\"":
+        # The delimiter must not reappear inside, or `'a' or x == 'b'` reads as the
+        # single string `a' or x == 'b` — which the evaluator accepts and compares
+        # false forever. That silence is the failure this rule exists to catch.
+        return text[0] in text[1:-1]
+    return scalar(text, default=_REFUSED) is _REFUSED
+
+
+def expressions_in(text: str) -> list[str]:
+    """Every `{{ … }}` body in a string, in order."""
+    return [match.group(1) for match in TEMPLATE.finditer(text)]
+
+
+__all__ = ["COMPARISON", "PATH", "ROOTS", "TEMPLATE", "expressions_in", "refusal"]

mkp_contracts/gates.py

@@ -0,0 +1,243 @@
+"""What a machine's gate may name, and therefore what a bundle may be built with.
+
+A gate in a `.mkl` can carry `hook: <name>`, and mklang resolves that name against a
+registry the host supplies — builtins, entry-point plugins, and whatever the host passes
+as `extra`. That registry is where a tenant's Python would go, and ADR 0003 says it must
+not:
+
+> mklang steps run in the runner process — **there is no customer code in a `.mkl`, only
+> data** — but get an ephemeral filesystem workspace per run.
+
+That clause is the *reason* a machine runs in the runner process at all rather than in a
+container like a code step. A bundle that carried Python for its gates would take the
+reason away. And a gate is not business logic in the first place: it is where a judgement
+is checked before it is allowed to matter, which ADR 0005 puts on the platform's side of
+the line — the machinery a tenant cannot switch off.
+
+So the vocabulary is closed, declarative, and defined here rather than in either component
+that needs it. The builder refuses a bundle whose machine names something outside it; the
+runner compiles what is inside it into predicates. Two definitions would mean a bundle that
+builds and then halts at its first gate, which is the failure `mkbundle` exists to prevent
+— mklang resolves an unknown hook to nothing and **halts when the gate is reached**.
+
+## The forms
+
+    mkp:eq:<path>:<literal>          the value at <path> equals the literal
+    mkp:neq:<path>:<literal>         it does not
+    mkp:has:<path>[,<path>…]         every path is present and non-empty
+    mkp:in:<path>:<path>             the first value is a member of the second, a list
+
+Namespaced `mkp:` because that prefix is what the platform owns (`README.md`, "Naming"),
+and because mklang has parametric forms of its own — `eq:` and `neq:` over a context key —
+that a machine may keep using. Those two, plus `always_true` and `always_false`, are the
+only names from mklang a bundle may gate on: the rest of that project's builtins are its
+examples (`amount_le_100`, `has_receipt`), and a signed bundle should not depend on whether
+somebody's example is installed next to the runner.
+
+## The paths
+
+Rooted, like the workflow expression language beside it (`expressions.py`, whose roots are
+`inputs`, `steps` and `run`):
+
+    output              the value the state just produced, whole — a string, or a document
+    output.a.b          a field of it, when it is a document
+    context.free_slots  a machine context key
+    context.slots[].start   `[]` maps over a list: the `start` of each element
+
+`[]` is the one addition to a dotted path and it exists for a shape vendors actually
+return: a list of objects, where the gate is about one field of each. It maps, it does not
+filter or aggregate.
+
+Deliberately absent: arithmetic, boolean combination, membership in a literal set, reading
+a second state's output, and any form of call. The rule is the expression language's own —
+whatever this accepts becomes something a bundle author can make the platform do — and the
+consequence is stated rather than implied: **a gate that needs computing is a workflow that
+needs a `code` step**, where computing is visible as what it is and runs in a sandbox.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any
+
+NAMESPACE = "mkp"
+
+# mklang's own, and the only ones from it a bundle may name. `eq:`/`neq:` are parametric
+# over a *context* key; the rest of mklang's builtins are that project's examples.
+MKLANG_NAMED = frozenset({"always_true", "always_false"})
+MKLANG_PARAMETRIC = ("eq:", "neq:")
+
+ROOTS = frozenset({"output", "context"})
+
+KINDS = frozenset({"eq", "neq", "has", "in"})
+
+# A path segment: a name, or `[]` meaning "each element of the list here".
+SEGMENT = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(\[\])?$")
+
+VOCABULARY = (
+    "mkp:eq:<path>:<literal>, mkp:neq:<path>:<literal>, mkp:has:<path>[,<path>...], "
+    "mkp:in:<path>:<path>, eq:<key>:<value>, neq:<key>:<value>, always_true, always_false"
+)
+
+
+class GateError(ValueError):
+    """The name is in the platform's namespace and is not one of its forms.
+
+    Distinct from a name outside the namespace, which may be mklang's and is not this
+    module's to judge — see `resolvable`.
+    """
+
+
+@dataclass(frozen=True)
+class Gate:
+    """A parsed platform gate. Data, so both the builder and the runner read one name the
+    same way: the builder to accept it, the runner to answer it."""
+
+    kind: str
+    paths: tuple[str, ...]
+    literal: str | None = None
+
+
+def parse(name: str) -> Gate:
+    """Parse a `mkp:` gate name, or raise `GateError` saying what the vocabulary is.
+
+    Only for names in the platform's namespace. `resolvable` is the question a builder
+    asks about *any* hook name; this is the answer for the ones that are ours.
+    """
+    if not name.startswith(f"{NAMESPACE}:"):
+        raise GateError(f"{name!r} is not a {NAMESPACE}: gate name")
+
+    # Split at most four ways so a literal keeps its own colons: a time of "10:30" is a
+    # value, not a separator, and a vocabulary that could not express one would be a
+    # vocabulary nobody could gate a calendar on.
+    parts = name.split(":", 3)
+    kind = parts[1] if len(parts) > 1 else ""
+    if kind not in KINDS:
+        raise GateError(
+            f"{name!r} names no gate this platform has: {kind!r} is not one of "
+            f"{', '.join(sorted(KINDS))}. The vocabulary is {VOCABULARY}"
+        )
+
+    if kind in ("eq", "neq"):
+        if len(parts) != 4 or not parts[2]:
+            raise GateError(f"{name!r}: {NAMESPACE}:{kind} takes a path and a literal")
+        return Gate(kind=kind, paths=(_path(parts[2], name),), literal=parts[3])
+
+    if kind == "has":
+        if len(parts) != 3 or not parts[2]:
+            raise GateError(f"{name!r}: {NAMESPACE}:has takes one or more comma-separated paths")
+        paths = tuple(_path(part, name) for part in parts[2].split(",") if part)
+        if not paths:
+            raise GateError(f"{name!r}: {NAMESPACE}:has takes one or more comma-separated paths")
+        return Gate(kind=kind, paths=paths)
+
+    if len(parts) != 4 or not parts[2] or not parts[3]:
+        raise GateError(
+            f"{name!r}: {NAMESPACE}:in takes two paths — a value, and the list it must be in"
+        )
+    return Gate(kind=kind, paths=(_path(parts[2], name), _path(parts[3], name)))
+
+
+def resolvable(name: str | None) -> bool:
+    """Whether a runner will be able to answer this gate.
+
+    The question a builder asks. `None` is a gate with no hook, which is judged by the
+    model and is not this module's business.
+    """
+    if not name:
+        return True
+    if name in MKLANG_NAMED or name.startswith(MKLANG_PARAMETRIC):
+        return True
+    if not name.startswith(f"{NAMESPACE}:"):
+        return False
+    try:
+        parse(name)
+    except GateError:
+        return False
+    return True
+
+
+def reason(name: str) -> str:
+    """Why a name is not resolvable, for a message a bundle author can act on."""
+    if name.startswith(f"{NAMESPACE}:"):
+        try:
+            parse(name)
+        except GateError as exc:
+            return str(exc)
+        return ""
+    return (
+        f"hook {name!r} is not a gate this platform can resolve. A gate is data, not code "
+        f"(ADR 0003), so a machine may name: {VOCABULARY}"
+    )
+
+
+def _path(text: str, name: str) -> str:
+    segments = text.split(".")
+    if segments[0] not in ROOTS:
+        raise GateError(
+            f"{name!r}: a gate path starts at {' or '.join(sorted(ROOTS))}, not {segments[0]!r}"
+        )
+    for segment in segments[1:]:
+        if not SEGMENT.match(segment):
+            raise GateError(
+                f"{name!r}: {segment!r} is not a path segment. A segment is a name, "
+                "optionally followed by `[]` to map over a list"
+            )
+    return text
+
+
+_UNSET = object()
+
+
+def scalar(text: str, *, default: Any = _UNSET) -> Any:
+    """`true`, `false`, `null` and numbers as themselves; anything else per `default`.
+
+    The half that two readers of the same syntax must agree on: a gate's right-hand side
+    here, and a workflow comparison's in the runner's expression language. They differ at
+    the edges only — the runner accepts quoted strings and refuses a bare word, a gate
+    takes a bare word as text — and those edges are the callers' to state. What "42" and
+    "true" mean is not, and it lived in two places until 2026-08-04.
+
+    With no `default`, an unrecognised value comes back as its own text.
+    """
+    lowered = text.lower()
+    if lowered in ("true", "false"):
+        return lowered == "true"
+    if lowered in ("null", "none"):
+        return None
+    try:
+        return int(text)
+    except ValueError:
+        pass
+    try:
+        return float(text)
+    except ValueError:
+        return text if default is _UNSET else default
+
+
+def literal(text: str) -> Any:
+    """A gate's right-hand side, read the way the expression language reads one.
+
+    Unquoted, because a hook name is already a string inside a YAML document and a second
+    layer of quoting is a layer to get wrong. `true`, `false`, `null` and numbers are
+    themselves; everything else is text.
+    """
+    return scalar(text)
+
+
+__all__ = [
+    "KINDS",
+    "MKLANG_NAMED",
+    "MKLANG_PARAMETRIC",
+    "NAMESPACE",
+    "ROOTS",
+    "VOCABULARY",
+    "Gate",
+    "GateError",
+    "literal",
+    "parse",
+    "reason",
+    "resolvable",
+    "scalar",
+]

mkp_contracts/roles.py

@@ -0,0 +1,35 @@
+"""The role names, which cross every boundary this platform has.
+
+Here for the same reason `cli_versions` is here: the set of roles is not the control
+plane's private business. `mkctl` names them in its help, the operator console decides
+what to render from them, the glossary fixes them as vocabulary, and the API authorizes
+against them. Four copies is what the repository had, and the fourth was wrong — `mkctl`
+offered `developer`, which has never existed, while citing the ADR that lists the real
+four. A help string is read *before* the API refuses, so the wrong name cost a round trip
+and left the right one unsaid.
+
+What is **not** here is `ROLE_ACTIONS`: which actions each role holds is policy, it is
+answered in one table in `services/api/src/control_plane/authz.py`, and nothing outside
+the control plane may have an opinion about it. This module owns the names and their
+order — the smallest thing that has to agree everywhere.
+
+`platform_admin` is deliberately absent. It is not a role a tenant can grant (ADR 0004
+Amendment 3): it lives in its own table, is read by a different function, and putting it
+in a list called ROLES is how it would eventually be offered in a grant menu.
+"""
+
+from __future__ import annotations
+
+OWNER = "owner"
+MAINTAINER = "maintainer"
+OPERATOR = "operator"
+VIEWER = "viewer"
+
+# Ordered from most to least: it is the order a person expects in a help string and in a
+# menu, and an arbitrary one would be re-sorted differently by each consumer.
+ROLES: tuple[str, ...] = (OWNER, MAINTAINER, OPERATOR, VIEWER)
+
+
+def is_role(name: str) -> bool:
+    """Whether `name` is one of the four a tenant can grant."""
+    return name in ROLES

mkp_contracts/schemas.py

@@ -0,0 +1,82 @@
+"""Schema loading, document-kind detection, and shape validation.
+
+The schemas are the shape; `rules.py` holds the rules. A document that validates
+here is well-formed, not necessarily deployable (`schema/README.md`).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+from jsonschema import Draft202012Validator
+
+from .errors import ContractError, Report
+
+KINDS = ("workflow", "connector", "bundle")
+
+_SCHEMA_FILES = {
+    "workflow": "workflow.schema.json",
+    "connector": "connector.schema.json",
+    "bundle": "bundle.schema.json",
+}
+
+
+def schema_dir() -> Path:
+    """Locate `schema/` by walking up from this file, then from the cwd.
+
+    The tool lives in the same repository as the contracts it enforces, so it
+    finds them rather than carrying a copy that can drift.
+    """
+    for start in (Path(__file__).resolve(), Path.cwd().resolve() / "_"):
+        for parent in start.parents:
+            candidate = parent / "schema"
+            if (candidate / "bundle.schema.json").is_file():
+                return candidate
+    raise ContractError(
+        "cannot find the schema/ directory — run mkp from inside the mklang-platform repository"
+    )
+
+
+def load_schema(kind: str) -> dict[str, Any]:
+    if kind not in _SCHEMA_FILES:
+        raise ContractError(f"unknown document kind {kind!r}; expected one of {', '.join(KINDS)}")
+    return json.loads((schema_dir() / _SCHEMA_FILES[kind]).read_text())
+
+
+def load_document(path: Path) -> Any:
+    """Parse YAML or JSON. Both are validated after parsing, as mklang does for `.mkl`."""
+    text = path.read_text()
+    try:
+        return yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        raise ContractError(f"{path}: not parseable as YAML or JSON: {exc}") from exc
+
+
+def detect_kind(document: Any) -> str | None:
+    """Infer the kind from the document's own shape.
+
+    Deliberately structural: the three contracts have disjoint required fields,
+    so a document does not need to announce what it is.
+    """
+    if not isinstance(document, dict):
+        return None
+    if "actions" in document and "auth" in document:
+        return "connector"
+    if "contents" in document and "lock" in document:
+        return "bundle"
+    if "steps" in document:
+        return "workflow"
+    return None
+
+
+def validate_document(document: Any, kind: str, path: str = "") -> Report:
+    """Validate one document against its schema, reporting every violation."""
+    report = Report()
+    validator = Draft202012Validator(load_schema(kind))
+    for error in sorted(validator.iter_errors(document), key=lambda e: list(e.absolute_path)):
+        location = ".".join(str(part) for part in error.absolute_path)
+        report.fail("schema", error.message, path=path, location=location)
+    return report

mkp_contracts/signature.py

@@ -0,0 +1,120 @@
+"""Verifying a bundle's signature. Signing stays with the builder.
+
+The split is not symmetric and should not be: **signing is a build-time act and
+verifying is a runtime one.** The builder signs and also verifies its own output;
+the runner verifies at load and must never sign anything. Putting verification here
+lets the runner do its half without depending on a build tool — the same argument
+that moved `canonical.py` and `archive.py` out of `mkbundle`.
+
+What is verified is exactly the canonical manifest bytes, which are also the bytes the
+digest is taken over. One canonical form and not two, which is why signing a bundle
+does not move its identity.
+
+`signature.key_id` is minisign's 8-byte key id, not the public key. A verifier looks
+that id up in a trust store it already holds. Taking the key from the artifact it is
+meant to authenticate would verify only that the artifact signed itself.
+"""
+
+from __future__ import annotations
+
+import base64
+import re
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from .errors import ContractError, Report
+
+ALGORITHM = "minisign"
+CANONICAL_NAME = "manifest.canonical"
+
+# minisign prints the key id as a hexadecimal number, so it drops leading zeros: about
+# one key in sixteen is written with fewer than sixteen digits. Requiring sixteen made
+# `key_id` raise on those, which meant a build key that could not sign and a trust key a
+# runner crashed on rather than refused with — both invisible until the wrong key was
+# generated. Read one to sixteen digits and pad, so what is stored is always canonical.
+_KEY_ID_RE = re.compile(r"minisign public key:?\s*([0-9A-Fa-f]{1,16})\b")
+
+
+def available() -> bool:
+    return shutil.which(ALGORITHM) is not None
+
+
+def require() -> None:
+    if not available():
+        raise ContractError("minisign is not on PATH; a bundle cannot be signed or verified")
+
+
+def key_id(public_key: Path) -> str:
+    """minisign's key id, read from the public key file's comment, always 16 digits."""
+    match = _KEY_ID_RE.search(public_key.read_text())
+    if not match:
+        raise ContractError(f"{public_key}: cannot read a minisign key id out of this file")
+    return match.group(1).upper().rjust(16, "0")
+
+
+def verify(canonical: bytes, signature: dict[str, Any], public_key: Path) -> Report:
+    """Check a manifest's signature against a public key held out of band."""
+    report = Report()
+    require()
+
+    algorithm = signature.get("algorithm")
+    if algorithm != ALGORITHM:
+        report.fail(
+            "signature-algorithm",
+            f"cannot verify {algorithm!r} signatures; this verifies {ALGORITHM}",
+        )
+        return report
+
+    expected = key_id(public_key)
+    # Padded on both sides: a bundle signed before the padding fix carries the short
+    # form, and rejecting it would be this fix inventing a signature failure.
+    if signature.get("key_id", "").upper().rjust(16, "0") != expected:
+        report.fail(
+            "signature-key",
+            f"signed by key {signature.get('key_id')!r}, but the key offered is {expected}",
+        )
+        return report
+
+    try:
+        payload = base64.b64decode(signature["value"], validate=True)
+    except (KeyError, ValueError) as exc:
+        report.fail("signature-malformed", f"signature.value is not base64: {exc}")
+        return report
+
+    with tempfile.TemporaryDirectory() as workspace:
+        target = Path(workspace) / CANONICAL_NAME
+        target.write_bytes(canonical)
+        signature_path = target.with_suffix(".minisig")
+        signature_path.write_bytes(payload)
+
+        # A fixed argv list and no shell: everything interpolated is a path this
+        # process just wrote into a temporary directory of its own.
+        completed = subprocess.run(
+            [
+                ALGORITHM,
+                "-V",
+                "-p",
+                str(public_key),
+                "-m",
+                str(target),
+                "-x",
+                str(signature_path),
+                "-q",
+            ],
+            capture_output=True,
+            text=True,
+        )
+
+    if completed.returncode != 0:
+        report.fail(
+            "signature-invalid",
+            "the signature does not verify against this key and these manifest bytes: "
+            f"{completed.stderr.strip() or completed.stdout.strip()}",
+        )
+    return report
+
+
+__all__ = ["ALGORITHM", "CANONICAL_NAME", "available", "key_id", "require", "verify"]

mkp_contracts-0.2.0.dist-info/METADATA

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: mkp-contracts
+Version: 0.2.0
+Summary: The cross-boundary contracts as code: canonical form, digests, schema validation
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: <3.14,>=3.11
+Requires-Dist: jsonschema>=4.21
+Requires-Dist: pyyaml>=6.0

mkp_contracts-0.2.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+mkp_contracts/__init__.py,sha256=ksri1hSCLJ4bN-MRWI0w8JUmwO_DX80t-_bxVs7FeV4,523
+mkp_contracts/archive.py,sha256=3WSxY7cjyFqKJudzxkdsC2NAw76YaCTBW-dRHgtLg3k,2627
+mkp_contracts/canonical.py,sha256=csgkd6bUp8CO6EEtJoovNBzcP3dU121HcOnmq5zNwag,1555
+mkp_contracts/cli_versions.py,sha256=V_oHHyOkrJxOVEJeFc6VumoHMBd6Od08fm8LoBb8sNw,1425
+mkp_contracts/errors.py,sha256=bpVs4r4uOQv7QxH_Cr6z1VdAQo-ICz5PKMvhUjOwStU,2137
+mkp_contracts/expressions.py,sha256=uquTYlP2n0emKkw2cMKPDnLGgxqOtHNp_0RXKjBAt8s,4353
+mkp_contracts/gates.py,sha256=1EcNJUbnqxKJZXSw6QaUmmxHC28W15BifAdpG1hbntY,9506
+mkp_contracts/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mkp_contracts/roles.py,sha256=FP1ws1QpddtLGvnI8rOW61AJAWuL7MVZs5XJ_Jo6IIg,1677
+mkp_contracts/schemas.py,sha256=7zMJOqBtoMZPyFjvKcW7xI1JxgEKN34OsJkUFTXcJXw,2829
+mkp_contracts/signature.py,sha256=QqW9tPGmq0RPVZg8-avUhDHCxuCsXTZvO9bkKiARbe8,4483
+mkp_contracts-0.2.0.dist-info/METADATA,sha256=iQXNkHyJksnSIpQ7v-fAiWxASjoPzBUM6nrPwgDd430,289
+mkp_contracts-0.2.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+mkp_contracts-0.2.0.dist-info/licenses/LICENSE,sha256=OomESGL67ZXotKqNbTv84ga2xAp3zho0QQH_kjVDTxQ,11338
+mkp_contracts-0.2.0.dist-info/RECORD,,

mkp_contracts-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mkp_contracts-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Gianluca
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.