techtree 0.1.0__py3-none-any.whl

techtree/release/generate.py

@@ -0,0 +1,221 @@
+"""Binding one release together. Spec sections 9.3.1, 9.3.3 and 9.4.
+
+Generation is the step that turns "a source tree and a handful of founder
+decisions" into one document every other repository copies. It runs *before*
+the wheel is built and before the plugin is tagged, so nothing it reads may
+depend on either — that ordering is the whole reason the cross-repository
+binding has no cycle in it (spec section 9.3.3).
+
+Two kinds of value meet here and they are kept strictly apart.
+
+The founder's decisions arrive as :class:`~techtree.release.models.
+ReleaseInputs`, read from a file a person edits. This module never invents one
+and never guesses a default for one.
+
+Everything else is *read out of the tree being released* — the protocol
+version, the digest of the engine bundle, the digest of the catalog index, and
+the subject harness version the introductory Climb's Campaign pins. Those are
+facts about the source, so asking a person for them would only create a second
+answer that could disagree with the first.
+
+The introductory Climb reference sits on the seam: the founder chooses which
+Climb the release leads with, and this module refuses the choice unless the
+catalog actually ships it under exactly that reference. A release that
+advertises a Climb nobody shipped is the failure this check exists for.
+
+Generation is deterministic. The same source tree and the same inputs produce
+the same bytes on any machine, at any time, which is what lets a drift check
+regenerate the artifacts into a throwaway copy of the repository and compare.
+Nothing here reads the clock, the environment, the network, or version control.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from importlib.resources.abc import Traversable
+from typing import Final
+
+from techtree.catalog.repository import (
+    CATALOG_INDEX_FILENAME,
+    EmbeddedCatalogRepository,
+    packaged_catalog_root,
+)
+from techtree.engines.bundle import embedded_engine_root, engine_bundle_digest
+from techtree.errors import ValidationError
+from techtree.models.base import Digest, JsonValue
+from techtree.release.document import document_digest
+from techtree.release.models import (
+    BUILD_INFO_SCHEMA_VERSION,
+    RELEASE_CORE_SCHEMA_VERSION,
+    ReleaseCore,
+    ReleaseInputs,
+)
+from techtree.version import PROTOCOL_VERSION
+
+__all__ = [
+    "BUILD_PROVENANCE_MECHANISM",
+    "GENERATOR_VERSION",
+    "ReleaseSources",
+    "build_info_document",
+    "build_release_core",
+    "packaged_sources",
+]
+
+#: Bumped when the generated shape changes, so a stored artifact can say which
+#: generator produced it.
+GENERATOR_VERSION: Final = "0.1.0"
+
+#: How a wheel comes to know which commit it was built from (decisions 0026).
+#: One mechanism, described where the release process is recorded, so that a
+#: reader of ``release/build-info.json`` never has to read the build hook to
+#: learn what the stamp inside a wheel means or how much it is worth.
+BUILD_PROVENANCE_MECHANISM: Final[Mapping[str, str]] = {
+    "mechanism": (
+        "a hatchling build hook, tools/stamp_provenance.py, writes the source "
+        "commit into the package while the wheel is being built"
+    ),
+    "build_command": "uv build --wheel",
+    "stamped_file": "techtree/resources/release/build-provenance.json",
+    "stamp_schema_version": "techtree.build-provenance.v1",
+    "commit_source": "git rev-parse HEAD, asked of the tree being packaged",
+    "refuses": (
+        "a build with no git, no commit, or any packaged path (src/techtree, "
+        "pyproject.toml, README.md, LICENSE) differing from that commit; there "
+        "is no unknown value and no default"
+    ),
+    "in_the_committed_tree": (
+        "never; the stamp belongs to one artifact and is written and removed "
+        "by the build"
+    ),
+    "editable_installs": (
+        "not stamped: an editable install is the working tree rather than a "
+        "distributable artifact, and `techtree release info` reports that no "
+        "commit was stamped instead of naming one"
+    ),
+    "reported_by": "techtree release info",
+}
+
+
+@dataclass(frozen=True)
+class ReleaseSources:
+    """The part of a release that is read rather than decided."""
+
+    catalog_root: Traversable
+    engine_root: Traversable
+    protocol_version: str
+
+    def catalog_index_bytes(self) -> bytes:
+        """Return the exact bytes of the catalog index."""
+        return (self.catalog_root / CATALOG_INDEX_FILENAME).read_bytes()
+
+
+def packaged_sources() -> ReleaseSources:
+    """Return the sources of the build this process is running from."""
+    return ReleaseSources(
+        catalog_root=packaged_catalog_root(),
+        engine_root=embedded_engine_root(),
+        protocol_version=PROTOCOL_VERSION,
+    )
+
+
+def build_release_core(inputs: ReleaseInputs, sources: ReleaseSources) -> ReleaseCore:
+    """Bind founder decisions and source facts into one ReleaseCore."""
+    catalog = EmbeddedCatalogRepository(sources.catalog_root)
+    reference = _exact_climb_reference(catalog, inputs.intro_climb_reference)
+    climb = catalog.load_climb(reference)
+    campaign = catalog.load_campaign(climb.campaign_spec_digest)
+
+    values = {
+        "cli_version": inputs.cli_version,
+        "maximum_tested_host_hermes_version": (
+            inputs.maximum_tested_host_hermes_version
+        ),
+        "minimum_host_hermes_version": inputs.minimum_host_hermes_version,
+        "release_id": inputs.release_id,
+        "skill_improver_digest": inputs.skill_improver_digest,
+        "starter_skill_digest": inputs.starter_skill_digest,
+        "starter_skill_object_url": inputs.starter_skill_object_url,
+    }
+
+    return ReleaseCore(
+        schema_version=RELEASE_CORE_SCHEMA_VERSION,
+        protocol_version=sources.protocol_version,
+        engine_digest=engine_bundle_digest(sources.engine_root),
+        catalog_digest=document_digest(sources.catalog_index_bytes()),
+        intro_climb_reference=reference,
+        subject_hermes_version=campaign.subject.harness.version,
+        # Where a run is published, where it is then read, and the public half
+        # of the key that countersigns the answer. None of the three can be
+        # derived from this source tree — they are facts about a deployment and
+        # about a key the founder generates — so they arrive with the founder's
+        # other decisions and are copied through unchanged. Decisions 0038.
+        publication=inputs.publication,
+        **values,
+    )
+
+
+def build_info_document(
+    *,
+    inputs_digest: Digest,
+    pyproject_version: str,
+    core: ReleaseCore,
+    artifacts: Mapping[str, Digest],
+) -> dict[str, JsonValue]:
+    """Return what was built, from what, without reading the clock.
+
+    A build record normally starts with a timestamp. This one cannot: the
+    artifacts it describes are regenerated in a throwaway copy of the
+    repository and compared byte for byte, so anything that changes between two
+    identical builds would turn every drift check into a false alarm. What
+    matters for support is which inputs produced which bytes, and that is what
+    is recorded.
+
+    ``pyproject_version`` is recorded even though the ReleaseCore names the
+    published CLI version separately. They are two different statements — what
+    this source tree declares, and what the release publishes — and both a
+    support conversation and the version check in
+    :mod:`techtree.release.checks` need to see both.
+
+    ``build_provenance`` describes how the *wheel* gets the one coordinate this
+    document deliberately does not carry: the commit it was built from
+    (decisions 0026). The description is here because this is the record of how
+    a release is produced; the value itself exists only inside a built wheel.
+
+    ``artifacts`` does not include this document. A build record cannot state
+    its own digest, and pretending otherwise would only produce a value that
+    could never be recomputed.
+    """
+    return {
+        "schema_version": BUILD_INFO_SCHEMA_VERSION,
+        "generator": "tools/build_release_core.py",
+        "generator_version": GENERATOR_VERSION,
+        "build_provenance": dict(BUILD_PROVENANCE_MECHANISM),
+        "inputs": {
+            "release_inputs_digest": inputs_digest,
+            "pyproject_version": pyproject_version,
+            "protocol_version": core.protocol_version,
+            "engine_digest": core.engine_digest,
+            "catalog_digest": core.catalog_digest,
+            "intro_climb_reference": core.intro_climb_reference,
+        },
+        "artifacts": dict(sorted(artifacts.items())),
+    }
+
+
+def _exact_climb_reference(catalog: EmbeddedCatalogRepository, reference: str) -> str:
+    """Return the reference, having proved the catalog ships exactly it.
+
+    The repository resolves a bare slug to the newest version, which is right
+    for a person browsing and wrong for a release document: a release names one
+    immutable Climb, and it has to name it the way the catalog files it.
+    """
+    available = catalog.list_climb_references()
+    if reference not in available:
+        raise ValidationError(
+            f"the release names {reference!r} as its introductory Climb, but "
+            "this catalog does not ship that exact reference",
+            code="intro_climb_not_in_catalog",
+            details={"reference": reference, "available": list(available)},
+        )
+    return reference

techtree/release/models.py

@@ -0,0 +1,293 @@
+"""What a ReleaseCore is, and what makes one honest. Spec sections 6.6, 9.3.
+
+A ReleaseCore is the single document that says which CLI, which engine, which
+catalog, which Climb, and which Skills are one release. It is generated before
+the CLI wheel and the plugin commit exist, which is what keeps the
+cross-repository binding acyclic (spec section 9.3.3): the wheel and the plugin
+embed these exact bytes, and the website's later ``BootstrapRelease`` wraps
+them.
+
+Decisions document 0026 settles what may be in it. A ReleaseCore is a
+*contract*: it holds only values a person can know when they author it, so it
+is honestly final the moment it is committed. It therefore says nothing about
+the artifact built from it — no wheel hash, no plugin commit, and no source
+commit, because an artifact never describes its own identity. Identity is
+stamped onto the wheel at build time (:mod:`techtree.release.provenance`) and
+witnessed externally by the website's bootstrap document.
+
+Every coordinate here is concrete, and the schema is what makes that true
+rather than a convention anyone has to remember. A version is three numbers, a
+release identifier is a name, a digest is sixty-four hexadecimal characters
+that are not all zero, and the starter Skill's address is a content address
+ending in the digest of the bytes it returns. None of those admit a spelling
+that means "nobody has chosen this yet", so a document that validates is a
+document whose every coordinate was chosen.
+"""
+
+from __future__ import annotations
+
+import base64
+import re
+from typing import Annotated, Final, Literal, Self
+
+from pydantic import AfterValidator, StringConstraints, model_validator
+
+from techtree.canonical import sha256_digest_bytes
+from techtree.constants import DIGEST_PREFIX
+from techtree.crypto import ED25519_PUBLIC_KEY_BYTES
+from techtree.models.base import Digest, NonEmptyString, ProtocolModel, PublicKeyRef
+
+__all__ = [
+    "BUILD_INFO_SCHEMA_VERSION",
+    "CONCRETE_DIGEST_LENGTH",
+    "CONCRETE_DIGEST_PATTERN",
+    "OBJECT_URL_PATTERN",
+    "PLAIN_HTTPS_URL_PATTERN",
+    "RELEASE_CORE_SCHEMA_VERSION",
+    "RELEASE_ID_PATTERN",
+    "RELEASE_INPUTS_SCHEMA_VERSION",
+    "VERSION_PATTERN",
+    "ConcreteDigest",
+    "ObjectUrl",
+    "PinnedNetworkKey",
+    "PlainHttpsUrl",
+    "PublicationCoordinates",
+    "ReleaseCore",
+    "ReleaseId",
+    "ReleaseInputs",
+    "Version",
+    "object_url_digest",
+]
+
+RELEASE_CORE_SCHEMA_VERSION: Final = "techtree.release-core.v1"
+RELEASE_INPUTS_SCHEMA_VERSION: Final = "techtree.release-inputs.v1"
+BUILD_INFO_SCHEMA_VERSION: Final = "techtree.release-build-info.v1"
+
+#: A published version is three numbers. Everything this release names — the
+#: CLI, the host Hermes range, the subject harness — is versioned that way, and
+#: nothing that is merely *proposed* has a version at all, so the pattern needs
+#: no room for a suffix that would let one read as the other.
+VERSION_PATTERN: Final = r"^[0-9]+(?:\.[0-9]+){2}$"
+
+type Version = Annotated[str, StringConstraints(pattern=VERSION_PATTERN)]
+
+#: A release identifier is a name a person gives one release — ``climb-v0.1.0``
+#: — so it begins with a letter and joins lowercase words with ``-`` or ``.``.
+#: A bare number is a version, and a version is not an identity.
+RELEASE_ID_PATTERN: Final = r"^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$"
+
+type ReleaseId = Annotated[str, StringConstraints(pattern=RELEASE_ID_PATTERN)]
+
+#: Sixty-four hexadecimal characters with at least one of them non-zero. The
+#: length is fixed by :data:`CONCRETE_DIGEST_LENGTH` beside it, so this pattern
+#: only has to say "not all zeros": nothing hashes to zero, so a zeroed digest
+#: is never a measurement.
+CONCRETE_DIGEST_PATTERN: Final = rf"^{DIGEST_PREFIX}0*[1-9a-f][0-9a-f]*$"
+CONCRETE_DIGEST_LENGTH: Final = len(DIGEST_PREFIX) + 64
+
+type ConcreteDigest = Annotated[
+    str,
+    StringConstraints(
+        pattern=CONCRETE_DIGEST_PATTERN,
+        min_length=CONCRETE_DIGEST_LENGTH,
+        max_length=CONCRETE_DIGEST_LENGTH,
+    ),
+]
+
+#: Where a published artifact is served from. Spec section 4.1 requires the
+#: starter Skill to be an exact read-only object URL, and decision 0007 R10
+#: requires every coordinate of a real release to be concrete and immutable, so
+#: this is an absolute ``https`` content address: it ends in the digest of the
+#: bytes it returns, which is how the website files public objects and how a
+#: fetcher checks a response before it has scanned anything.
+#:
+#: The authority may not carry userinfo. A published coordinate is copied into
+#: the plugin, into the website, into an approval packet and into support
+#: transcripts, and ``https://user:token@host/…`` would carry a credential
+#: through every one of them — while also making the address mean different
+#: things to different readers. A public read-only object needs no credential,
+#: so an address that offers one is not the coordinate this field is for.
+OBJECT_URL_PATTERN: Final = rf"^https://[^\s/@]+/[^\s]*{DIGEST_PREFIX}[0-9a-f]{{64}}$"
+
+
+def _require_resolvable_host(value: str) -> str:
+    """Reject an address under a top-level domain that can never resolve.
+
+    RFC 2606 reserves ``.invalid`` so that names under it are guaranteed not to
+    resolve. An address nothing can ever fetch is not a place something is
+    published, whatever else it looks like.
+    """
+    authority = value.removeprefix("https://").split("/", 1)[0]
+    host = authority.rsplit(":", 1)[0] if ":" in authority else authority
+    if host.lower().endswith(".invalid"):
+        raise ValueError("an address under .invalid can never resolve")
+    return value
+
+
+type ObjectUrl = Annotated[
+    str,
+    StringConstraints(pattern=OBJECT_URL_PATTERN),
+    AfterValidator(_require_resolvable_host),
+]
+
+
+_OBJECT_URL_DIGEST_RE: Final = re.compile(rf"{DIGEST_PREFIX}[0-9a-f]{{64}}$")
+
+
+def object_url_digest(url: str) -> Digest:
+    """Return the file digest a content address is keyed by.
+
+    The address ends in the digest of the bytes it serves, which is what makes
+    it safe to fetch from at all: whatever arrives is checked against the
+    address it came from before anything else looks at it.
+
+    Raises:
+        ValueError: when the address ends in no digest, and therefore promises
+            nothing about what it serves.
+    """
+    found = _OBJECT_URL_DIGEST_RE.search(url)
+    if found is None:
+        raise ValueError(f"{url!r} is not keyed by the digest of what it serves")
+    return found.group()
+
+
+#: A published address with nothing after its path. Every URL a release pins is
+#: read by a machine and printed to a person, so it is ``https`` and it carries
+#: no query string and no fragment: a submission travels in a request body and
+#: never in a URL, and an address that could carry one would be a place a proof
+#: or a volunteered address could end up in somebody's access log.
+PLAIN_HTTPS_URL_PATTERN: Final = r"^https://[^\s/@?#]+(?:/[^\s?#]*)?$"
+
+type PlainHttpsUrl = Annotated[
+    str,
+    StringConstraints(pattern=PLAIN_HTTPS_URL_PATTERN),
+    AfterValidator(_require_resolvable_host),
+]
+
+
+class PinnedNetworkKey(PublicKeyRef):
+    """The public half of the key the run log countersigns receipts with.
+
+    Requiring a receipt to carry a key and a signature proves nothing on its
+    own: a server that wanted to lie would invent a key, sign with it, and hand
+    both to the participant. What makes a countersignature worth having is that
+    the participant already knows which key to expect, so the key is pinned in
+    the release rather than learned from the answer.
+
+    The identifier is the digest of the public key and is checked to be, as
+    every other key identifier in this protocol is (decisions 0038, founder
+    ruling of 2026-08-27). A derived identifier cannot name one key and carry
+    another, so a receipt that names a key it does not carry is caught without
+    anybody writing a check for it. Rotation is a new key and therefore a new
+    identifier, and a release pins exactly the one it trusts.
+
+    Only the public half ever reaches this repository. Nothing here can sign,
+    and nothing here is a place a private key could be put.
+    """
+
+    @model_validator(mode="after")
+    def _check_the_identifier_is_the_digest_of_the_key(self) -> Self:
+        """Reject a key whose identifier was assigned rather than derived."""
+        raw = base64.b64decode(self.public_key, validate=True)
+        if len(raw) != ED25519_PUBLIC_KEY_BYTES:
+            raise ValueError(
+                f"an Ed25519 public key is {ED25519_PUBLIC_KEY_BYTES} raw bytes"
+            )
+        if not any(raw):
+            raise ValueError(
+                "an all-zero public key names no key; it is the spelling of a "
+                "coordinate nobody has chosen yet, and a release pins only "
+                "coordinates somebody chose"
+            )
+        derived = sha256_digest_bytes(raw)
+        if self.key_id != derived:
+            raise ValueError(
+                f"a network key identifier is the digest of the key it carries: "
+                f"this one says {self.key_id} and carries {derived}"
+            )
+        return self
+
+
+class PublicationCoordinates(ProtocolModel):
+    """Where a run is published, where it is then read, and who countersigns.
+
+    All three are release coordinates rather than settings, for one reason each
+    (decisions 0038, founder ruling of 2026-08-27).
+
+    ``submission_endpoint`` is pinned because a stable release has to be able to
+    publish with nothing configured. An address that only arrived from the
+    environment meant a published wheel could not publish out of the box, and a
+    person who had to set a variable before publishing would be a person who
+    could set it to the wrong thing.
+
+    ``public_log_url`` is pinned because a receipt names where the entry now
+    lives, and an entry address the participant did not already expect is an
+    address the answering server chose. The receipt's address is checked to be
+    on this origin before the receipt is written down.
+
+    ``network_key`` is pinned because a countersignature is only worth the
+    prior knowledge of which key made it.
+    """
+
+    submission_endpoint: PlainHttpsUrl
+    public_log_url: PlainHttpsUrl
+    network_key: PinnedNetworkKey
+
+
+class ReleaseCore(ProtocolModel):
+    """The frozen coordinates of one Climb release. Spec section 6.6.
+
+    Every field is required and concrete. There is no field that describes the
+    wheel, the plugin, or the commit this document was authored at: those are
+    facts about artifacts that do not exist yet when the release is written,
+    and decision 0026 puts them where they can be known — stamped into the
+    wheel, and witnessed by the website's bootstrap document.
+
+    ``starter_skill_digest`` and ``starter_skill_object_url`` are two halves of
+    one coordinate and neither substitutes for the other. The digest says
+    *which* Skill the release measured — spec section 4.1 and decisions 0008
+    make it the ordered content-tree digest, not a file hash — and the URL says
+    where a machine that does not already hold those bytes can obtain them, and
+    which bytes the address itself promises.
+    """
+
+    schema_version: Literal["techtree.release-core.v1"]
+    release_id: ReleaseId
+    cli_version: Version
+    protocol_version: NonEmptyString
+    engine_digest: ConcreteDigest
+    catalog_digest: ConcreteDigest
+    intro_climb_reference: NonEmptyString
+    starter_skill_digest: ConcreteDigest
+    starter_skill_object_url: ObjectUrl
+    skill_improver_digest: ConcreteDigest
+    minimum_host_hermes_version: Version
+    maximum_tested_host_hermes_version: Version
+    subject_hermes_version: Version
+    publication: PublicationCoordinates
+
+
+class ReleaseInputs(ProtocolModel):
+    """The founder-owned half of a ReleaseCore. Spec section 4.5.
+
+    Every value here is a decision a person makes and freezes — the published
+    version, the release identifier, the Skill artifacts, the host Hermes
+    range. None of them can be derived from this repository, so they are held
+    in one hand-edited file that the generator reads, rather than passed as
+    command options that would leave the generated document unreproducible.
+
+    The remaining ReleaseCore coordinates are absent on purpose. A release
+    input file that tried to state the engine digest or the protocol version
+    would be asserting something the source tree already answers.
+    """
+
+    schema_version: Literal["techtree.release-inputs.v1"]
+    release_id: ReleaseId
+    cli_version: Version
+    intro_climb_reference: NonEmptyString
+    starter_skill_digest: ConcreteDigest
+    starter_skill_object_url: ObjectUrl
+    skill_improver_digest: ConcreteDigest
+    minimum_host_hermes_version: Version
+    maximum_tested_host_hermes_version: Version
+    publication: PublicationCoordinates

techtree/release/provenance.py

@@ -0,0 +1,109 @@
+"""Which commit a built artifact came from. Decisions document 0026.
+
+An artifact never describes its own identity. The ReleaseCore is written before
+the wheel exists and cannot name the commit the wheel is built from without
+inventing it, so the commit is *stamped onto the wheel while the wheel is being
+built* and read back out of it here.
+
+The stamp is one small document, ``build-provenance.json``, written into the
+package's release resources by the build hook in ``tools/stamp_provenance.py``
+and never present in the committed tree. Two properties of that hook are what
+make this module's answer worth anything, and both live there rather than here:
+the commit it writes is the commit the packaged sources are, and a build that
+cannot establish that fails instead of guessing.
+
+Reading it back has three possible answers and only two of them are values. A
+wheel carries the stamp. A source checkout — an editable install, the test
+suite, ``uv run techtree`` — is not a built artifact and carries none, and says
+so rather than reporting a commit nobody stamped.
+"""
+
+from __future__ import annotations
+
+import zipfile
+from pathlib import Path
+from typing import Annotated, Final, Literal
+
+from pydantic import StringConstraints
+
+from techtree.errors import ValidationError
+from techtree.models.base import ProtocolModel
+from techtree.release.document import (
+    packaged_release_root,
+    render_document,
+)
+
+__all__ = [
+    "BUILD_PROVENANCE_FILENAME",
+    "BUILD_PROVENANCE_SCHEMA_VERSION",
+    "COMMIT_PATTERN",
+    "BuildProvenance",
+    "Commit",
+    "packaged_build_provenance",
+    "parse_build_provenance",
+    "render_build_provenance",
+    "wheel_build_provenance",
+]
+
+#: Bumped only if the stamped shape changes. The website, the plugin, and the
+#: bootstrap checker all read it.
+BUILD_PROVENANCE_SCHEMA_VERSION: Final = "techtree.build-provenance.v1"
+
+#: The stamped file, wherever it is read from: the installed package, or a
+#: wheel that has not been installed yet.
+BUILD_PROVENANCE_FILENAME: Final = "build-provenance.json"
+
+#: A full git commit, lowercase, never abbreviated. Spec section 9.3.2 pins
+#: exact commits, and an abbreviation is not one.
+COMMIT_PATTERN: Final = r"^[0-9a-f]{40}$"
+
+type Commit = Annotated[str, StringConstraints(pattern=COMMIT_PATTERN)]
+
+#: Where the stamp sits inside a wheel, which stores the package tree flat
+#: under its import name.
+_WHEEL_MEMBER: Final = f"techtree/resources/release/{BUILD_PROVENANCE_FILENAME}"
+
+
+class BuildProvenance(ProtocolModel):
+    """The commit one built artifact was built from, and nothing else."""
+
+    schema_version: Literal["techtree.build-provenance.v1"]
+    source_commit: Commit
+
+
+def render_build_provenance(provenance: BuildProvenance) -> bytes:
+    """Return the one byte spelling of a stamp.
+
+    The same commit produces the same bytes, which is what keeps two builds of
+    one commit byte-identical.
+    """
+    return render_document(provenance.model_dump(mode="json"))
+
+
+def parse_build_provenance(raw: bytes) -> BuildProvenance:
+    """Load and validate a stamp from stored bytes."""
+    try:
+        return BuildProvenance.model_validate_json(raw)
+    except ValueError as error:
+        raise ValidationError(
+            f"this is not a valid build provenance stamp: {error}",
+            code="build_provenance_invalid",
+        ) from error
+
+
+def packaged_build_provenance() -> BuildProvenance | None:
+    """Return what this build was stamped with, or None if it is not a build."""
+    stamp = packaged_release_root() / BUILD_PROVENANCE_FILENAME
+    if not stamp.is_file():
+        return None
+    return parse_build_provenance(stamp.read_bytes())
+
+
+def wheel_build_provenance(wheel: Path) -> BuildProvenance | None:
+    """Return what a wheel on disk was stamped with, without installing it."""
+    with zipfile.ZipFile(wheel) as archive:
+        try:
+            raw = archive.read(_WHEEL_MEMBER)
+        except KeyError:
+            return None
+    return parse_build_provenance(raw)

techtree/resources/catalog/campaigns/hello-world-climb.json

@@ -0,0 +1 @@
+{"agents":{"subject":{"harness":{"id":"hermes-agent","skills":[],"use_bundled_skill":false,"version":"0.19.0"},"model":{"credential_env":"PRIME_API_KEY","model_id":"qwen/qwen3.7-flash","provider":"prime","revision":null},"runtime":{"cpu":2,"image":"python@sha256:90744cff8f32887f075c47d747a173ff333e9e98801667af93c357fa9f5e28ff","image_platform_digests":{"linux/amd64":"sha256:78b39ef14d8e2b4d71f8dc304f1328c37df95fe0ef99477c2ae6bd3d03784553","linux/arm64":"sha256:20eadabc42589e6543b24a64ab305b9895e9fcf6dbb2cadb14812f394ecdbadf"},"memory_gb":4,"network_policy":"restricted","supported_platforms":["linux/amd64","linux/arm64"],"type":"docker"},"sampling":{"max_tokens":4096,"temperature":0},"trainable":false}},"budgets":{"maximum_input_tokens":900000,"maximum_model_calls":44,"maximum_output_tokens":16000,"maximum_usd":2.5},"context":{"outcome_contract_digest":null,"program_ref":null},"data_policy_digest":"sha256:6c532a43d595286a08260481890bbbffa16d1b4dd89465d1cc8395099d9ebcf9","environment":{"id":"single-agent"},"evaluation_backend":{"attestation":"participant","executor_identity":null,"kind":"local_techtree","provider_run_ref":null,"schema_version":"techtree.evaluation-backend.v1alpha1","workspace_ref":null},"evidence":{"runtime_evidence":"not_required","verifiers_episode":"required"},"execution":{"max_concurrent":4,"order":"parallel_variants","retry_limit":0,"timeout_seconds":600},"kind":"Campaign","metadata":{"id":"campaign_4e8e01a28126c92a906b5cf10b46ee21","purpose":"component_uplift","version":1},"mutation_contract":{"allowed_differences":["/agents/subject/harness/skills"],"kind":"skill_insertion","maximum_skills":1,"minimum_skills":1,"target_agent":"subject"},"schema_version":"techtree.campaign.v1alpha1","scoring":{"aggregation":"mean","minimum_absolute_delta":0,"primary_reward":"exact_match","require_candidate_above_baseline":true},"taskset":{"membership":{"membership_digest":"sha256:56f697fb182cc31691c2e1fff20471acbd549a06e37232227c9491c03aa8f9aa","mode":"committed","ordered_task_hashes":["sha256:af8a43bbaf38d332131d73ef9a5b995d9f330fdc37a777a12bef7c51c9fa0ed1","sha256:e9a51458548dcfb10572fd9f032f00abdb298425114f68acdc074faa79229232","sha256:bafa30550e9c0b09281b3b4b99cb467b9522babc9c2b9d97fee93abef26933b0","sha256:1e74b2f5d62a6b25288d1d8ea3f85b6a0daf4a7697fe36d3f54b8534bb67b40d","sha256:c05fd9db26808494349e9292ecde51a2c6b19e6d87e6f7d7080e2089829504f5","sha256:02725a29cc06f2c883ad17e11a7fc2a09bd2b214df08f3c5c79e4941b54e315e","sha256:206eb5646df5b41b67d28f0e42d370ceb3eb0d72a78cea97e5bbecb7e3841a9f","sha256:c600be21a92a8c5401eaf645b8591b09f34052afe2ab61898d3be2edf8027cad","sha256:b11c2add8339b16dbe85804f9b046e203a0b05db2b7fe9412a4dc45172c6555b","sha256:bd835a69bbeb90d2b1c529aef6bac0c47a8b83750967bf4b64373a90540a07a4","sha256:0a5bde37b05e74be39c62f4418d4812a123d627bc627591fb02dde124b246426","sha256:f15ce47698160cd33fe7a0eb5e40a4cc7977624dd2bdf481ffee69b6204f26b3","sha256:4fb4ddcab900a74eb7cb6ff6a730cc07b5a244535f40f6ddb6aa726cb2796596","sha256:84d83849562386b699e048a91c5671e0f55b49098c9dfac9711a0895766caef3","sha256:e08bb7c7a18a57a83d2ad8dba412c416a8746f708f54b8a29efc0355cabbdb45","sha256:775f95710c5b09fd79e5720554b764f8a1c938063e5743977efe9a4f9d6dc12b","sha256:832e70ff2ab29bfc83da704344417f0c9be2af2935247178ecd1cedc00477097","sha256:5ef9194a49f5ada8a059b52cee70090a53df2bd5b415bf9ed8533287f3020dfc","sha256:b195109ade431bf058e12c4ae1dff6c7bf05d4770be9af9ed27d8f588e95c910","sha256:67eae183c9a688ab5172104c8f8e6380a3c052d367e5bd05964618f5f575bcd8","sha256:cb5651849ccdc4309b9931918392831a2afc7d1b82e6a976a8777a23e73057aa","sha256:391c080f51aa41130367d01e43ff21f80ef915274dd19b2f1a4aaf76380f8f13","sha256:6c39dc6c8c62d0b471e3e40cc560d6cf105632c62e40de8ab21f00e1f3dcd8dc","sha256:f5d73f388d604fc4df9afe63c70ca81f22646faad2bae99e24b1be0b5b6e239a","sha256:c6bb62c1b970b25d39823748dd9cb087884cfb7360668f8c405d870af26e223e","sha256:23c6f7a31ede5aa224788e4408ae1462ca57c559175232d740de6a139b02a5b4","sha256:13fe52ddfdeab29466e3ed21db540a08d169e09d338e86852f96387f2272795d","sha256:702eb0abb56d4554d7e9b8d75f15cf3d7ecfc0c8c9f83cf1c6c3caa25c5865f5","sha256:aee7f9a4999dce081dbd0ce6ab65db37ffe9bb88d9b4a07b944f376fef0a14ad","sha256:4b6a3d718933e312c05adff201cd14ab1d58b0eb5c0a0d32faccedc09cb9af68","sha256:8b5ae57c98f3963e91dd611d4cfc37da07c80d4b3c0091ed7b4a76175376381a","sha256:98f86f8d3663dcf3d0f32b6b1f9ef44913bb144355ecbcd89b8e4c96337b6964","sha256:3efcd8d42d8adfce2038f5e5d8c88c3ec1d30d6ae3379c4727ea711b28e1929d","sha256:bd2815069c78bced9ef23d36770c941b27753dad15db3e6c3a90c197181202a1","sha256:08c8263a76b1d93beb586c8c39f0469721455cd08d517b15bcf827cf09ac0755","sha256:0777a89a3da39284a1765937c3ce1cea7af2ac27a98ffee32e86a2a1fccca9b5"]},"ref":{"config":{},"id":"procedure-transfer-v1","kind":"verifiers","package":{"digest":"sha256:f42a0d5e968478af40c703645d247ef043f115f6801d3b497eca5fab47261a7c","kind":"embedded","name":"procedure-transfer-v1","revision":"0.1.0"}},"selection":{"num_rollouts":1,"num_tasks":36,"shuffle":false},"validation_receipt_digest":"sha256:4944bd71caa1a295e03325b18a7af753d0d8fcf787189c89244209171cda1302"}}

techtree/resources/catalog/catalog.json

@@ -0,0 +1,32 @@
+{
+  "climbs": [
+    {
+      "digest": "sha256:a3a5e9c5f9b40d4f08fad54852377e201fd0d6dd4acfa4c565a0edfac324a236",
+      "path": "climbs/hello-world-climb.json",
+      "reference": "hello-world-climb@1"
+    }
+  ],
+  "objects": {
+    "sha256:4944bd71caa1a295e03325b18a7af753d0d8fcf787189c89244209171cda1302": {
+      "kind": "taskset_validation",
+      "media_type": "application/json",
+      "path": "taskset-validations/hello-world-climb.json"
+    },
+    "sha256:6c532a43d595286a08260481890bbbffa16d1b4dd89465d1cc8395099d9ebcf9": {
+      "kind": "data_policy",
+      "media_type": "application/json",
+      "path": "data-policies/hello-world-climb.json"
+    },
+    "sha256:991be5e42acbd48c6bd9aaf8e1f5a5a2478c0a0e4bf04ad4f2be84b702adee43": {
+      "kind": "validation_evidence",
+      "media_type": "application/json",
+      "path": "validation-evidence/hello-world-climb.json"
+    },
+    "sha256:ebf029abb266ca74c2def50eb23030511bab0e929c6bf4a68691f9b5afd554b1": {
+      "kind": "campaign",
+      "media_type": "application/json",
+      "path": "campaigns/hello-world-climb.json"
+    }
+  },
+  "schema_version": "techtree.catalog.v1alpha1"
+}

techtree/resources/catalog/climbs/hello-world-climb.json

@@ -0,0 +1 @@
+{"campaign_spec_digest":"sha256:ebf029abb266ca74c2def50eb23030511bab0e929c6bf4a68691f9b5afd554b1","candidate_policy":{"constraints":{"format":"techtree-instruction-skill-v1","max_skills":1,"min_skills":1},"required_mutation":"skill_insertion","skill_visibility":"public"},"kind":"Climb","leaderboard":{"enabled":false,"evidence_required":"not_required"},"metadata":{"closes_at":null,"id":"climb_8475477d861d884f5dd2c046aeedb025","opens_at":null,"slug":"hello-world-climb","status":"development","summary":"A toy Skill-uplift Climb. It runs the synthetic BranchCode v1 task family twice — once without a Skill, once with one — so you can see what writing a procedure down changes. This is an introductory demonstration of the mechanism, not a measure of broad capability.","title":"Techtree Hello World","version":1},"publication":{"proof_grade":"development_only","public_trace_projection":"redacted","raw_episode_visibility":"prohibited","report_visibility":"public"},"schema_version":"techtree.climb.v1alpha1"}