techtree 0.1.0__py3-none-any.whl

techtree/models/validation.py

@@ -0,0 +1,299 @@
+"""Taskset locking and mechanical validation. Spec 11.9, decisions 0003 A1.
+
+Three objects, with a deliberate split between them.
+
+``TasksetLock``
+    What the taskset resolved to: engine, package, ordered task hashes, and the
+    membership digest computed from them.
+
+``TasksetValidationReceipt``
+    The scientific answer to one narrow question — is this taskset mechanically
+    valid and internally consistent? It carries no identifier, no timestamp, no
+    duration, no path, and no raw log. Decisions document 0003 makes the
+    receipt's own content digest its identity, which is what allows the
+    publisher's receipt and a participant's locally recomputed receipt to be
+    compared by equality instead of by narrative. A display identifier can be
+    derived with :func:`validation_display_id`; it is never stored.
+
+``ValidationExecutionRecord``
+    Everything the receipt refuses to carry: when it ran, on which host, with
+    which command, and which raw artifacts it left behind. It is local
+    operational provenance, never part of the Campaign graph, never referenced
+    by a public Climb, and never byte-compared by ``make generated-check``.
+
+Between the raw upstream output and the receipt sits ``ValidationEvidence``:
+the normalized, deterministic form of what the validator reported, with
+elapsed times, temporary paths, run identifiers, and host detail removed. That
+is the artifact a receipt points at and the one that ships publicly.
+
+The receipt does not answer whether the environment is discriminative, robust
+to reward hacking, suitable for RL, or economically useful. Those belong to a
+future ``EnvironmentQualificationReport``.
+"""
+
+from __future__ import annotations
+
+from typing import Final, Literal, Self
+
+from pydantic import Field, model_validator
+
+from techtree.models.base import (
+    ArtifactRef,
+    Digest,
+    NonEmptyString,
+    ProtocolModel,
+    StateModel,
+    UtcDateTime,
+)
+from techtree.models.campaign import TasksetRef
+
+__all__ = [
+    "REQUIRED_VALIDATION_CHECKS",
+    "TasksetLock",
+    "TasksetValidationReceipt",
+    "UpstreamValidationSummary",
+    "ValidationCheck",
+    "ValidationEvidence",
+    "ValidationEvidenceSummary",
+    "ValidationEvidenceTask",
+    "ValidationExecutionRecord",
+    "ValidationMethod",
+    "ValidationTaskOutcome",
+    "validation_display_id",
+]
+
+#: Every check a receipt must report on. A receipt that silently omits one is
+#: not a weaker receipt, it is an unreadable one: a reader cannot tell whether
+#: the check passed or was never attempted.
+REQUIRED_VALIDATION_CHECKS: Final[tuple[str, ...]] = (
+    "upstream_gold",
+    "upstream_setup",
+    "membership_repeatability",
+    "task_hash_uniqueness",
+    "committed_membership_match",
+    "expected_task_count",
+)
+
+#: How many hexadecimal characters of the receipt digest a display identifier
+#: shows. Enough to be unambiguous in a terminal, short enough to read aloud.
+_DISPLAY_ID_HEX_LENGTH: Final = 24
+
+
+class TasksetLock(ProtocolModel):
+    """What a taskset reference resolved to, pinned."""
+
+    schema_version: Literal["techtree.taskset-lock.v1alpha1"]
+    taskset_ref: TasksetRef
+    engine_digest: Digest
+    resolved_package_digest: Digest
+    ordered_task_hashes: list[Digest]
+    membership_digest: Digest
+    task_count: int = Field(ge=1)
+
+    @model_validator(mode="after")
+    def _check_task_list(self) -> Self:
+        """Reject a hash list that disagrees with the count or repeats a task."""
+        if len(self.ordered_task_hashes) != self.task_count:
+            raise ValueError(
+                f"lock records {len(self.ordered_task_hashes)} task hashes but "
+                f"a task_count of {self.task_count}"
+            )
+        if len(set(self.ordered_task_hashes)) != len(self.ordered_task_hashes):
+            raise ValueError("locked task hashes must be unique")
+        return self
+
+
+class ValidationCheck(ProtocolModel):
+    """One mechanical check and what it found."""
+
+    id: NonEmptyString
+    status: Literal["passed", "failed", "warning", "not_run"]
+    detail: NonEmptyString
+
+
+class UpstreamValidationSummary(ProtocolModel):
+    """What the upstream validator reported, in aggregate."""
+
+    mode: Literal["all", "gold", "setup"]
+    total: int = Field(ge=0)
+    recorded: int = Field(ge=0)
+    valid: int = Field(ge=0)
+    invalid: int = Field(ge=0)
+    error: int = Field(ge=0)
+    timeout: int = Field(ge=0)
+    missing: int = Field(ge=0)
+    valid_rate: float | None = Field(default=None, ge=0.0, le=1.0)
+
+    @model_validator(mode="after")
+    def _check_counts_add_up(self) -> Self:
+        """Reject a summary whose parts do not account for its total."""
+        counted = self.valid + self.invalid + self.error + self.timeout + self.missing
+        if counted != self.total:
+            raise ValueError(
+                f"summary accounts for {counted} tasks but reports a total of "
+                f"{self.total}"
+            )
+        if self.recorded > self.total:
+            raise ValueError("recorded cannot exceed total")
+        return self
+
+
+class ValidationMethod(ProtocolModel):
+    """How the validation was performed, in reproducible terms."""
+
+    kind: Literal["verifiers_validate"]
+    mode: Literal["all"]
+    runtime: Literal["subprocess"]
+    validator_revision: NonEmptyString
+
+
+class ValidationTaskOutcome(ProtocolModel):
+    """One validator verdict for one task."""
+
+    valid: bool
+    reason: NonEmptyString
+
+
+class ValidationEvidenceTask(ProtocolModel):
+    """The normalized per-task record the validator produced."""
+
+    position: int = Field(ge=0)
+    task_hash: Digest
+    gold: ValidationTaskOutcome
+    setup: ValidationTaskOutcome
+
+
+class ValidationEvidenceSummary(ProtocolModel):
+    """Aggregate counts over the normalized task records."""
+
+    total: int = Field(ge=0)
+    valid: int = Field(ge=0)
+    invalid: int = Field(ge=0)
+    error: int = Field(ge=0)
+    timeout: int = Field(ge=0)
+    missing: int = Field(ge=0)
+
+    @model_validator(mode="after")
+    def _check_counts_add_up(self) -> Self:
+        """Reject a summary whose parts do not account for its total."""
+        counted = self.valid + self.invalid + self.error + self.timeout + self.missing
+        if counted != self.total:
+            raise ValueError(
+                f"evidence accounts for {counted} tasks but reports a total of "
+                f"{self.total}"
+            )
+        return self
+
+
+class ValidationEvidence(ProtocolModel):
+    """Deterministic normalized validator output. Decisions 0003 A1.
+
+    Normalization has already removed elapsed times, wall-clock timestamps,
+    temporary paths, run identifiers, process identifiers, hostnames, absolute
+    output directories, log prefixes, and tracebacks from successful runs.
+    What remains is the part two honest parties must agree on.
+    """
+
+    schema_version: Literal["techtree.validation-evidence.v1alpha1"]
+    taskset_lock_digest: Digest
+    method: ValidationMethod
+    tasks: list[ValidationEvidenceTask]
+    summary: ValidationEvidenceSummary
+
+    @model_validator(mode="after")
+    def _check_tasks_are_a_dense_ordered_run(self) -> Self:
+        """Reject gaps, repeats, or an order that depends on who wrote the file."""
+        positions = [task.position for task in self.tasks]
+        if positions != list(range(len(self.tasks))):
+            raise ValueError(
+                "evidence tasks must be sorted by position and cover 0..n-1 "
+                "without gaps"
+            )
+        hashes = [task.task_hash for task in self.tasks]
+        if len(set(hashes)) != len(hashes):
+            raise ValueError("evidence task hashes must be unique")
+        if self.summary.total != len(self.tasks):
+            raise ValueError(
+                f"evidence lists {len(self.tasks)} tasks but its summary reports "
+                f"{self.summary.total}"
+            )
+        return self
+
+
+class TasksetValidationReceipt(ProtocolModel):
+    """Is this taskset mechanically valid and internally consistent?
+
+    Decisions document 0003 A1 removed the identifier, creation time, raw
+    artifact list, durations, absolute paths, and tracebacks that the original
+    shape carried. Every one of those varies between two correct runs of the
+    same validation, which meant the publisher's receipt and a participant's
+    receipt could never be equal even when they agreed completely. They now
+    are, and that equality is the check.
+    """
+
+    schema_version: Literal["techtree.taskset-validation.v1alpha1"]
+    taskset_lock_digest: Digest
+    engine_digest: Digest
+    method: ValidationMethod
+    status: Literal["valid", "invalid", "errored"]
+    upstream_summary: UpstreamValidationSummary
+    checks: list[ValidationCheck]
+    normalized_evidence: ArtifactRef | None
+
+    @model_validator(mode="after")
+    def _check_required_checks_are_reported(self) -> Self:
+        """Reject a receipt that omits or repeats a required check."""
+        reported = [check.id for check in self.checks]
+        if len(set(reported)) != len(reported):
+            raise ValueError("a receipt reports each check exactly once")
+        missing = [name for name in REQUIRED_VALIDATION_CHECKS if name not in reported]
+        if missing:
+            raise ValueError(
+                "receipt is missing required checks: " + ", ".join(missing)
+            )
+        if self.status == "valid" and any(
+            check.status == "failed" for check in self.checks
+        ):
+            raise ValueError("a receipt with a failed check is not valid")
+        return self
+
+
+class ValidationExecutionRecord(StateModel):
+    """Local operational provenance for one validation execution.
+
+    Decisions document 0003 A1. This is the mutable, host-specific companion to
+    the receipt. It is never part of the Campaign graph, never referenced by a
+    public Climb, never the publisher commitment, and never byte-compared by
+    generated-fixture checks.
+    """
+
+    schema_version: Literal["techtree.validation-execution.v1alpha1"]
+    id: NonEmptyString
+    receipt_digest: Digest
+    started_at: UtcDateTime
+    finished_at: UtcDateTime
+    command: list[NonEmptyString]
+    command_digest: Digest
+    host_platform: NonEmptyString
+    worker_pid: int | None
+    raw_artifacts: list[ArtifactRef]
+
+    @model_validator(mode="after")
+    def _check_execution_window(self) -> Self:
+        """Reject a record that finished before it started."""
+        if self.finished_at < self.started_at:
+            raise ValueError("finished_at cannot precede started_at")
+        if not self.command:
+            raise ValueError("a validation execution records the command it ran")
+        return self
+
+
+def validation_display_id(receipt_digest: Digest) -> str:
+    """Return the human-facing identifier derived from a receipt digest.
+
+    The value is derived for display only. Storing it inside the receipt would
+    put a second, redundant identity in an object whose whole point is that its
+    content is its identity.
+    """
+    _, _, hexadecimal = receipt_digest.partition(":")
+    return f"validation_{hexadecimal[:_DISPLAY_ID_HEX_LENGTH]}"

techtree/paths.py

@@ -0,0 +1,116 @@
+"""Where Techtree keeps its local state. Spec sections 10.10 and 28.
+
+One root directory holds everything: the settings file, the download cache,
+submission drafts, runs, and installed managed engines. Resolving that root
+through ``platformdirs`` means the location follows each platform's own
+convention instead of hard-coding a Unix dotfile path.
+
+Nothing here touches the filesystem at import time. Directories are created
+only when :func:`ensure_path_layout` is called, which keeps ``import techtree``
+free of side effects.
+
+``identities_dir`` is resolved here and created elsewhere. The local executor
+identity (spec section 7.5) is made by ``techtree setup``, or by a run that
+reaches the point of signing its receipts, and
+:class:`~techtree.identity.store.IdentityStore` creates the directory then.
+Creating it as part of the layout would leave every machine looking as though
+it held a key.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from platformdirs import user_data_path
+
+from techtree.canonical import validate_digest
+from techtree.fs import ensure_private_directory
+from techtree.ids import validate_id
+from techtree.models.base import Digest
+
+__all__ = [
+    "APPLICATION_NAME",
+    "TechtreePaths",
+    "default_paths",
+    "ensure_path_layout",
+    "paths_from_root",
+]
+
+APPLICATION_NAME = "techtree"
+
+
+@dataclass(frozen=True)
+class TechtreePaths:
+    """Every directory and file Techtree owns, derived from one root."""
+
+    root: Path
+    config_file: Path
+    cache_dir: Path
+    drafts_dir: Path
+    runs_dir: Path
+    engines_dir: Path
+    identities_dir: Path
+
+    def draft_dir(self, draft_id: str) -> Path:
+        """Return the directory holding one submission draft."""
+        return self.drafts_dir / validate_id(draft_id, "draft")
+
+    def run_dir(self, run_id: str) -> Path:
+        """Return the directory holding one run."""
+        return self.runs_dir / validate_id(run_id, "run")
+
+    def skills_cache_dir(self) -> Path:
+        """Return the directory holding Skills Techtree materialized itself."""
+        return self.cache_dir / "skills"
+
+    def skill_cache_dir(self, digest: Digest) -> Path:
+        """Return the cache directory holding one Skill, named by its digest.
+
+        Content-addressed by the Skill's own root digest and spelled the way
+        an engine install is, so the same Skill is materialized once per home
+        and a directory's name is a claim its contents can be checked against.
+        """
+        return self.skills_cache_dir() / validate_digest(digest).replace(":", "-", 1)
+
+    def engine_dir(self, digest: Digest) -> Path:
+        """Return the install directory for one managed engine bundle.
+
+        The digest's colon becomes a dash: ``sha256-<hex>``. A colon is legal
+        on POSIX but not on Windows, and an engine install is content-addressed
+        on every platform.
+        """
+        return self.engines_dir / validate_digest(digest).replace(":", "-", 1)
+
+
+def paths_from_root(root: Path) -> TechtreePaths:
+    """Construct deterministic test paths."""
+    resolved = Path(root)
+    return TechtreePaths(
+        root=resolved,
+        config_file=resolved / "config.toml",
+        cache_dir=resolved / "cache",
+        drafts_dir=resolved / "drafts",
+        runs_dir=resolved / "runs",
+        engines_dir=resolved / "engines",
+        identities_dir=resolved / "identities",
+    )
+
+
+def default_paths() -> TechtreePaths:
+    """Resolve platform paths through platformdirs."""
+    return paths_from_root(
+        user_data_path(appname=APPLICATION_NAME, appauthor=False, roaming=False)
+    )
+
+
+def ensure_path_layout(paths: TechtreePaths) -> None:
+    """Create top-level private directories."""
+    for directory in (
+        paths.root,
+        paths.cache_dir,
+        paths.drafts_dir,
+        paths.runs_dir,
+        paths.engines_dir,
+    ):
+        ensure_private_directory(directory)

techtree/presentation/__init__.py

@@ -0,0 +1,31 @@
+"""Showing a result without becoming part of it. Spec sections 7.13-7.17.
+
+Spec section 3.5 draws the line this package lives on: rich terminal output is
+a view, not scientific evidence. No colour, markup, prose, or channel-specific
+formatting enters an ``EpisodeReceipt`` or an ``UpliftReport``, and nothing in
+this package can change a number, a status, or a digest — every one of them is
+copied out of a signed report and formatted.
+
+That is why the payload is channel-neutral. One builder produces one
+:class:`~techtree.presentation.models.UpliftPresentationPayload` from the
+signed report; a terminal renderer, a phone-sized Markdown renderer, and the
+founder's own rich-output Skill all consume the same object. A second builder
+per channel would be a second place a result could be described differently.
+
+The division of labour:
+
+``models``
+    The neutral payload, and the pieces a renderer draws.
+``build``
+    Turning one signed report into one payload.
+``rich``
+    The accessible terminal rendering.
+``compact``
+    The bounded, ANSI-free rendering a gateway or a phone can carry.
+``sanitize``
+    What may appear at all, enforced rather than intended.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []