techtree 0.1.0__py3-none-any.whl

techtree/presentation/sanitize.py

@@ -0,0 +1,156 @@
+"""What may appear in a result, enforced rather than intended.
+
+Spec section 7.17.
+
+The evidence a run produces contains material that must not travel into a
+rendering. Some of it is obvious — an absolute path naming somebody's home
+directory. Some of it is the whole point of the evaluation: the taskset's
+hidden expected answers and the grader that knows them. A presentation that
+leaked either would not be a cosmetic bug; it would be a contaminated
+benchmark.
+
+So the rule here is that the payload's *shape* keeps hidden material out and
+these functions keep it out of the free text the shape still allows:
+
+```text
+may appear      task ordinal or public name, public prompt summary when the
+                policy allows it, score, delta
+never appears   hidden expected answer, grader source, absolute private path,
+                a traceback carrying environment values
+```
+
+Nothing here inspects a string for credential-shaped text. Decision 0036
+removed that from the whole project: a value's shape is not evidence of what
+it is, in either direction.
+
+One decision is worth stating because it was a decision and not an oversight.
+The engine's normalized output carries each rollout's *final reply* — what the
+subject actually answered. It is the participant's own material, it is often
+the most useful thing in a failed task, and it is not hidden verifier material.
+It still does not appear in a presentation payload in this release: a reply is
+free text from a model, a rendering is a place a reader trusts, and the release
+that shows replies should show them where a person asked for them (spec section
+7.18's improvement context) rather than in the summary a phone message quotes.
+The payload therefore has no field for one.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Final
+
+from pydantic import BaseModel
+
+from techtree.errors import ValidationError
+from techtree.presentation.models import UpliftPresentationPayload
+from techtree.verifiers.models import NormalizedExecutionError
+
+__all__ = [
+    "PRESENTATION_REDACTION_FAILED",
+    "ensure_no_control_or_local_path",
+    "ensure_no_hidden_task_material",
+    "sanitize_error_summary",
+    "sanitize_label",
+]
+
+#: Stable error code. Spec section 15.
+PRESENTATION_REDACTION_FAILED: Final = "presentation_redaction_failed"
+
+#: Escape sequences of every shape a terminal would act on. A payload is
+#: channel-neutral, so an escape sequence in it is either an accident or an
+#: attempt to control someone else's terminal.
+_ANSI = re.compile(r"\x1b\[[0-9;?]*[ -/]*[@-~]|\x1b[@-_]|\x9b[0-9;?]*[@-~]")
+
+#: Everything a terminal treats as a command rather than as text, newline and
+#: tab included: a rendering places its own line breaks.
+_CONTROL = re.compile(r"[\x00-\x1f\x7f]")
+
+_WHITESPACE_RUN = re.compile(r"\s+")
+
+#: A rooted filesystem path with at least two segments, POSIX or Windows.
+#: Digests, identifiers and prose do not look like this; ``~/.techtree/...``
+#: does, and so does a temporary directory naming a person's account.
+_ABSOLUTE_PATH = re.compile(r"(?:[A-Za-z]:\\|/)[\w.-]+[/\\][\w.\-/\\]*")
+
+#: What a truncated label ends with. One character, and not an escape.
+_ELLIPSIS: Final = "…"
+
+
+def sanitize_label(value: str, maximum: int = 120) -> str:
+    """Return one line of plain, bounded text.
+
+    Applied to everything a person or another system supplied — a Climb title,
+    a Skill name — because those are the fields that reach a rendering without
+    having been through a protocol validator that cared what was in them.
+    Escape sequences and control characters go, whitespace is flattened, and
+    the result is truncated. The remaining words are left exactly as written.
+    """
+    flattened = _WHITESPACE_RUN.sub(" ", _CONTROL.sub(" ", _ANSI.sub("", value)))
+    label = flattened.strip()
+    if len(label) <= maximum:
+        return label
+    return label[: maximum - 1].rstrip() + _ELLIPSIS
+
+
+def sanitize_error_summary(error: NormalizedExecutionError, maximum: int = 200) -> str:
+    """Summarize one recorded failure in one line.
+
+    The traceback is dropped rather than shortened. Its diagnostic worth is to
+    somebody reading the run directory, not to somebody reading a result.
+    """
+    summary = f"{error.type}: {error.message}" if error.message else error.type
+    return sanitize_label(summary, maximum)
+
+
+def ensure_no_control_or_local_path(value: str, *, field: str) -> None:
+    """Raise when one string would carry a terminal command or a local path.
+
+    Shared by the presentation payload and by spec section 7.18's improvement
+    context, because the two answer the same question about their free text:
+    a payload is read by a terminal and a context is read by a model, and
+    neither may be handed an escape sequence or somebody's home directory.
+    """
+    if _ANSI.search(value) or _CONTROL.search(value):
+        raise ValidationError(
+            "a result rendering may not carry terminal control sequences",
+            code=PRESENTATION_REDACTION_FAILED,
+            details={"field": field},
+        )
+    if _ABSOLUTE_PATH.search(value):
+        raise ValidationError(
+            "a result rendering may not name an absolute local path",
+            code=PRESENTATION_REDACTION_FAILED,
+            details={"field": field},
+        )
+
+
+def ensure_no_hidden_task_material(payload: UpliftPresentationPayload) -> None:
+    """Check every string in a payload before anything renders it.
+
+    Walks the payload rather than the fields somebody remembered, so a field
+    added later is covered the day it is added.
+    """
+    for path, value in _strings(payload, ""):
+        ensure_no_control_or_local_path(value, field=path)
+
+
+def _strings(value: object, path: str) -> list[tuple[str, str]]:
+    """Return every string inside a payload, with the field it came from."""
+    if isinstance(value, str):
+        return [(path, value)]
+    if isinstance(value, BaseModel):
+        found: list[tuple[str, str]] = []
+        for name in type(value).model_fields:
+            found.extend(_strings(getattr(value, name), f"{path}.{name}".lstrip(".")))
+        return found
+    if isinstance(value, dict):
+        found = []
+        for key, item in value.items():
+            found.extend(_strings(item, f"{path}[{key}]"))
+        return found
+    if isinstance(value, list | tuple):
+        found = []
+        for position, item in enumerate(value):
+            found.extend(_strings(item, f"{path}[{position}]"))
+        return found
+    return []

techtree/publication/__init__.py

@@ -0,0 +1,44 @@
+"""Publishing one finished run to the public log. Decisions document 0038.
+
+This is the only package in Techtree that sends anything anywhere, and it sends
+one thing: a proof bundle a person asked it to publish, after that bundle's own
+proof has been checked and found to hold together. Nothing here runs on its own,
+nothing here runs during a run, and nothing here is reachable without somebody
+answering a question first.
+
+Four rules shape every module below.
+
+*A result that does not verify is never offered.* The verification is the first
+step of publishing, not a check somebody could skip, because the whole of what
+this product is for is that a published number came with its own evidence.
+
+*A completed run's files are final.* Publishing adds a countersigned receipt and
+a journal of its own to the run directory. It rewrites nothing, including the
+run's own event log, which closed when the run ended.
+
+*The address bar carries nothing.* A submission is a request body. No proof, no
+digest and no volunteered address is ever put in a URL or a query string.
+
+*A volunteered address is sent and not kept.* It is optional, it defaults to no,
+its field name says it is unverified because nobody proved control of it, and
+nothing on this machine writes it down.
+
+The division of labour:
+
+``address``
+    Trimming, shape, the EIP-55 checksum, and the canonical lowercase form.
+``keccak``
+    The one hash EIP-55 needs and no standard library provides.
+``models``
+    What a submission is and what a receipt is.
+``journal``
+    The append-only record of what has been published about one run.
+``transport``
+    The single seam that opens a socket, and the only substitutable part.
+``service``
+    The order the steps happen in, which is the product.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

techtree/publication/address.py

@@ -0,0 +1,180 @@
+"""Checking an EVM address somebody typed. Decisions document 0038.
+
+An address is optional, it is volunteered, and it is unverifiable. Nobody has
+proved control of the account, and this module cannot change that — what it can
+do is refuse the two mistakes that are cheap to catch and expensive to make.
+
+*The shape.* ``0x`` and exactly forty hexadecimal characters, after the
+surrounding whitespace a paste brings with it has been trimmed off. Anything
+else is a typo or a different kind of identifier, and either way it is not what
+was asked for.
+
+*The checksum, where there is one.* EIP-55 hides a checksum in the letter case
+of an address: the hexadecimal is case-insensitive, so the case of each letter
+is free to carry four bits of a Keccak-256 digest of the address itself. An
+address written in one case carries no checksum and there is nothing to check.
+An address written in mixed case does carry one, and checking it costs a hash
+and catches a single mistyped character — which is the difference between a
+recognisable contributor and an address that belongs to nobody and always will,
+because there is no undo and no support desk.
+
+What travels is the lowercase spelling. It is the same address, it is the form
+the checksum is computed from, and one canonical form is what makes an address
+usable as a key.
+
+Nothing here stores anything. The caller sends the canonical form and keeps no
+copy: an address is a detail somebody volunteered about themselves, not
+evidence, and it belongs in no journal, no proof bundle and no log.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Final
+
+from techtree.errors import ValidationError
+from techtree.publication.keccak import keccak256
+
+__all__ = [
+    "CONTRIBUTOR_ADDRESS_INVALID",
+    "SKILL_GITHUB_URL_INVALID",
+    "canonical_contributor_address",
+    "canonical_skill_github_url",
+    "eip55_checksum",
+]
+
+#: Stable error code for "that is not an address anybody could have meant".
+CONTRIBUTOR_ADDRESS_INVALID: Final = "contributor_address_invalid"
+
+#: Stable error code for an optional public Skill repository URL that is not a
+#: canonical GitHub repository address.
+SKILL_GITHUB_URL_INVALID: Final = "skill_github_url_invalid"
+
+_ADDRESS_PATTERN: Final = re.compile(r"\A0x[0-9a-fA-F]{40}\Z")
+
+# GitHub user and organization names are at most 39 characters and contain
+# alphanumerics or dashes (never at either edge). Repository names are at most
+# 100 characters and may also contain dots and underscores. The URL is
+# deliberately narrower than what a browser might accept: one spelling, no
+# redirects, no .git suffix, and no extra path or URL components.
+_GITHUB_OWNER_PATTERN: Final = re.compile(
+    r"\A[A-Za-z0-9](?:[A-Za-z0-9-]{0,37}[A-Za-z0-9])?\Z"
+)
+_GITHUB_REPOSITORY_PATTERN: Final = re.compile(
+    r"\A[A-Za-z0-9][A-Za-z0-9._-]{0,99}\Z"
+)
+
+#: A digest nibble of eight or more uppercases the hexadecimal character it
+#: sits beside. EIP-55, in the one sentence it amounts to.
+_UPPERCASE_THRESHOLD: Final = 8
+
+
+def canonical_contributor_address(typed: str) -> str:
+    """Return the lowercase form of a typed address, or refuse it.
+
+    Refusals carry the reason rather than a generic "invalid": somebody who has
+    pasted the wrong forty characters and somebody who has mistyped one of the
+    right forty need to be told different things.
+    """
+    trimmed = typed.strip()
+    if not _ADDRESS_PATTERN.match(trimmed):
+        raise ValidationError(
+            "an address is 0x followed by exactly 40 hexadecimal characters, "
+            f"and this one is not: {_shape_of(trimmed)}",
+            code=CONTRIBUTOR_ADDRESS_INVALID,
+            details={"reason": "shape"},
+        )
+
+    body = trimmed[2:]
+    if body == body.lower() or body == body.upper():
+        # One case throughout carries no checksum, so there is nothing here to
+        # be right or wrong about.
+        return trimmed.lower()
+
+    if trimmed != eip55_checksum(trimmed):
+        raise ValidationError(
+            "this address is written in mixed case, which carries a checksum, "
+            "and the checksum does not match: one character of it is wrong. "
+            "An address nobody controls cannot be undone, so it is refused "
+            "rather than sent",
+            code=CONTRIBUTOR_ADDRESS_INVALID,
+            details={"reason": "checksum"},
+        )
+    return trimmed.lower()
+
+
+def canonical_skill_github_url(typed: str) -> str:
+    """Return a canonical GitHub repository URL, or refuse it.
+
+    This is descriptive metadata, not proof that a repository exists or that
+    its publisher controls it. Keeping the accepted form strict prevents a
+    public link from silently becoming a redirect, a different host, or a
+    clone URL with credentials and query data attached.
+    """
+    from urllib.parse import urlsplit
+
+    if typed != typed.strip():
+        raise ValidationError(
+            "a Skill GitHub URL has no surrounding whitespace",
+            code=SKILL_GITHUB_URL_INVALID,
+            details={"reason": "whitespace"},
+        )
+
+    try:
+        parts = urlsplit(typed)
+        # Accessing ``port`` validates a malformed explicit port and may raise
+        # ValueError even when the rest of the URL can be split.
+        port = parts.port
+    except ValueError:
+        parts = None
+        port = None
+
+    path_parts = parts.path.split("/") if parts is not None else []
+    if (
+        parts is None
+        or parts.scheme != "https"
+        or parts.netloc != "github.com"
+        or parts.username is not None
+        or parts.password is not None
+        or port is not None
+        or parts.query
+        or parts.fragment
+        or "?" in typed
+        or "#" in typed
+        or len(path_parts) != 3
+        or path_parts[0]
+        or not _GITHUB_OWNER_PATTERN.fullmatch(path_parts[1])
+        or not _GITHUB_REPOSITORY_PATTERN.fullmatch(path_parts[2])
+        or path_parts[2].lower().endswith(".git")
+    ):
+        raise ValidationError(
+            "a Skill GitHub URL must be exactly https://github.com/owner/repo, "
+            "with no .git suffix, query, fragment, credentials, or extra path",
+            code=SKILL_GITHUB_URL_INVALID,
+            details={"reason": "shape"},
+        )
+    return typed
+
+
+def eip55_checksum(address: str) -> str:
+    """Return the mixed-case EIP-55 spelling of a well-formed address."""
+    body = address[2:].lower()
+    digest = keccak256(body.encode("ascii")).hex()
+    return "0x" + "".join(
+        character.upper()
+        if int(digest[position], 16) >= _UPPERCASE_THRESHOLD
+        else character
+        for position, character in enumerate(body)
+    )
+
+
+def _shape_of(typed: str) -> str:
+    """Describe what was typed without repeating it back.
+
+    A refusal that echoed the string would put it in the envelope, in the
+    terminal's scrollback, and in whatever a host agent keeps — which is
+    exactly where a volunteered address must not end up. The length and whether
+    the prefix was there are enough for somebody to see what they did.
+    """
+    prefix = "starts with 0x" if typed[:2].lower() == "0x" else "no 0x prefix"
+    return f"{prefix}, {len(typed)} characters"

techtree/publication/coordinates.py

@@ -0,0 +1,26 @@
+"""Where this build publishes, read off the release it belongs to.
+
+Decisions document 0038, founder ruling of 2026-08-27.
+
+One function, in one place, because two commands need the same answer and an
+answer that differed between them would be a build that publishes to one address
+and withdraws at another.
+
+It is read from the ReleaseCore the wheel carries rather than from a setting,
+which is what makes a stable release able to publish the moment it is installed.
+A build that ships no ReleaseCore was not produced by the release generator, and
+it says so: publishing needs to know not only where the run log is but which
+key's countersignature would be worth anything, and neither is a thing to guess.
+"""
+
+from __future__ import annotations
+
+from techtree.release.document import packaged_release_core_bytes, parse_release_core
+from techtree.release.models import PublicationCoordinates
+
+__all__ = ["packaged_publication_coordinates"]
+
+
+def packaged_publication_coordinates() -> PublicationCoordinates:
+    """Return the publication coordinates this build's release pins."""
+    return parse_release_core(packaged_release_core_bytes()).publication

techtree/publication/journal.py

@@ -0,0 +1,212 @@
+"""A completed run's publication journal. Decisions document 0038.
+
+A run's own event log closes when the run ends. That is not an inconvenience to
+work around: ``events.jsonl`` is the record of an execution, the state machine
+is what makes it derivable, and a file that a later command appends to is a file
+whose earlier bytes were not final. Publishing happens after all of that, is not
+part of the execution, and must not touch a byte the run wrote.
+
+So it is recorded in a journal of its own, in the same run directory, created
+the first time somebody publishes and appended to after that. Every property the
+run's own log has, this one has for the same reasons: canonical JSON one line at
+a time, sequence numbers that start at zero and increase by exactly one, and an
+``O_APPEND`` write followed by an ``fsync``, so a crash can lose a trailing line
+but cannot interleave two.
+
+What it does not carry is a contributor address. An address is a detail somebody
+volunteered about themselves rather than evidence about a run; it is sent and
+not kept, so there is nothing here to read it back out of.
+
+The publication status of a run is derived from this file and from nowhere else.
+The signed report inside the proof bundle says ``not_requested``, permanently
+and correctly: it was not requested when the report was written, and rewriting a
+signed document to say otherwise would break the proof it is part of.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Final, Literal, Self
+
+from pydantic import Field, model_validator
+from pydantic import ValidationError as PydanticValidationError
+
+from techtree.canonical import canonical_json_bytes
+from techtree.errors import ValidationError
+from techtree.fs import fsync_directory
+from techtree.models.base import Digest, NonEmptyString, ProtocolModel, UtcDateTime
+from techtree.models.uplift_report import PublicationStatus
+
+__all__ = [
+    "ATTEMPT_STATUSES",
+    "PUBLICATION_JOURNAL_CORRUPT",
+    "PUBLICATION_JOURNAL_FILENAME",
+    "PublicationJournal",
+    "PublicationJournalEntry",
+]
+
+#: The file, beside the run's own records and never inside its proof.
+PUBLICATION_JOURNAL_FILENAME: Final = "publication.jsonl"
+
+#: Stable error code for a journal whose lines do not form a history.
+PUBLICATION_JOURNAL_CORRUPT: Final = "publication_journal_corrupt"
+
+_LINE_SEPARATOR: Final = b"\n"
+#: Owner read and write only, matching every other file Techtree writes.
+_FILE_MODE: Final = 0o600
+
+#: The three statuses a publication attempt moves through. The other two
+#: members of :class:`~techtree.models.uplift_report.PublicationStatus` describe
+#: a report rather than an attempt: ``not_requested`` is what a run with no
+#: journal at all is, and ``blocked`` is a data policy's answer, decided before
+#: anything is attempted.
+ATTEMPT_STATUSES: Final[frozenset[PublicationStatus]] = frozenset(
+    {
+        PublicationStatus.PENDING,
+        PublicationStatus.PUBLISHED,
+        PublicationStatus.FAILED,
+    }
+)
+
+
+class PublicationJournalEntry(ProtocolModel):
+    """One thing that happened when somebody published this run."""
+
+    schema_version: Literal["techtree.publication-journal.v1alpha1"]
+    sequence: int = Field(ge=0)
+    at: UtcDateTime
+    run_id: NonEmptyString
+    status: PublicationStatus
+    #: The bundle this attempt was about, so a journal with several attempts in
+    #: it says which proof each one carried.
+    bundle_digest: Digest
+    #: Where it was sent. An origin and a path; a submission never travels in a
+    #: query string, so nothing here can contain one.
+    endpoint: NonEmptyString
+    file_count: int = Field(gt=0)
+    byte_count: int = Field(gt=0)
+    #: Set by a published attempt: where the entry now lives, and the log
+    #: position the network gave it.
+    entry_url: NonEmptyString | None = None
+    log_sequence: int | None = Field(default=None, ge=0)
+    #: Set by a failed attempt: the stable code of what went wrong. The message
+    #: belongs to the envelope the command already returned; a code is what a
+    #: later reader can act on.
+    error_code: NonEmptyString | None = None
+
+    @model_validator(mode="after")
+    def _check_the_outcome_carries_what_it_means(self) -> Self:
+        """Reject an entry that reports one outcome and describes another."""
+        if self.status not in ATTEMPT_STATUSES:
+            raise ValueError(
+                "a journal entry records an attempt, which is pending, "
+                "published or failed"
+            )
+        published = self.status is PublicationStatus.PUBLISHED
+        landed = self.entry_url is not None or self.log_sequence is not None
+        if published and (self.entry_url is None or self.log_sequence is None):
+            raise ValueError(
+                "a published entry records where it landed and its log position"
+            )
+        if not published and landed:
+            raise ValueError(
+                "only a published entry has somewhere it landed and a log position"
+            )
+        failed = self.status is PublicationStatus.FAILED
+        if failed and self.error_code is None:
+            raise ValueError("a failed entry records why it failed")
+        if not failed and self.error_code is not None:
+            raise ValueError("only a failed entry carries a failure code")
+        return self
+
+
+class PublicationJournal:
+    """The append-only record of what has been published about one run."""
+
+    def __init__(self, run_root: Path) -> None:
+        self._path = run_root / PUBLICATION_JOURNAL_FILENAME
+
+    @property
+    def path(self) -> Path:
+        """Return the journal file, whether or not it exists yet."""
+        return self._path
+
+    def entries(self) -> list[PublicationJournalEntry]:
+        """Return every entry, refusing a history with a hole in it.
+
+        A sequence that skips is a journal that lost a line, and a status
+        derived from it would be quietly wrong. That check also catches a
+        half-written trailing line, which fails to parse before its sequence is
+        ever considered.
+        """
+        try:
+            raw = self._path.read_bytes()
+        except FileNotFoundError:
+            return []
+
+        entries: list[PublicationJournalEntry] = []
+        for position, line in enumerate(raw.splitlines()):
+            if not line.strip():
+                continue
+            try:
+                entry = PublicationJournalEntry.model_validate_json(line)
+            except PydanticValidationError as error:
+                raise ValidationError(
+                    f"line {position + 1} of this run's publication journal "
+                    "cannot be read",
+                    code=PUBLICATION_JOURNAL_CORRUPT,
+                    details={"path": str(self._path), "line": position + 1},
+                ) from error
+            if entry.sequence != len(entries):
+                raise ValidationError(
+                    f"this run's publication journal jumps from {len(entries) - 1} "
+                    f"to {entry.sequence}, so a line is missing",
+                    code=PUBLICATION_JOURNAL_CORRUPT,
+                    details={"path": str(self._path), "sequence": entry.sequence},
+                )
+            entries.append(entry)
+        return entries
+
+    def status(self) -> PublicationStatus:
+        """Return where this run stands, derived from the journal alone.
+
+        A run nobody has published has no journal, and that is
+        ``not_requested`` — the same thing its report has said since it was
+        written.
+        """
+        entries = self.entries()
+        if not entries:
+            return PublicationStatus.NOT_REQUESTED
+        return entries[-1].status
+
+    def published(self) -> PublicationJournalEntry | None:
+        """Return the entry that published this run, if one did."""
+        for entry in reversed(self.entries()):
+            if entry.status is PublicationStatus.PUBLISHED:
+                return entry
+        return None
+
+    def next_sequence(self) -> int:
+        """Return the sequence the next appended entry takes."""
+        return len(self.entries())
+
+    def append(self, entry: PublicationJournalEntry) -> None:
+        """Append one entry durably.
+
+        A single ``O_APPEND`` write of one whole line, then an ``fsync``. The
+        entry is serialized before the file is opened, so an entry that cannot
+        be written down does not leave a partial line behind it.
+        """
+        line = canonical_json_bytes(entry) + _LINE_SEPARATOR
+        descriptor = os.open(
+            self._path, os.O_WRONLY | os.O_CREAT | os.O_APPEND, _FILE_MODE
+        )
+        try:
+            written = 0
+            while written < len(line):
+                written += os.write(descriptor, line[written:])
+            os.fsync(descriptor)
+        finally:
+            os.close(descriptor)
+        fsync_directory(self._path.parent)