dos-kernel 0.22.0__py3-none-win_amd64.whl

dos/rewind_evidence.py

@@ -0,0 +1,168 @@
+"""rewind-evidence — the boundary I/O for the conversation-rewind axis (docs/164 F1.5).
+
+`rewind.rewind_plan` is a PURE verdict over `(TurnRef…, SuspendCheckpoint, FireVerdict)`.
+SOMETHING has to gather those off disk: read the run's transcript turns and hash each
+(`digest_turn`), read the SUSPEND record's minted checkpoint off the intent ledger, and
+build the `FireVerdict` from whichever ground-truth stop verdict fired. That is this
+module — the conversation axis's `resume_evidence` sibling: boundary I/O feeding the pure
+core, never inside the verdict.
+
+Three boundary jobs, mirroring `resume_evidence`'s shape:
+
+  * **`gather_turns(...)`** — read the run's transcript off disk (the host-owned
+    `transcript.jsonl` beside `intent.jsonl`), hashing each turn's bytes into a
+    `TurnRef(index, digest)`. The DIGEST is computed HERE (the byte-author of the
+    anchor's identity is the kernel's hash, not the judged agent — the
+    `evidence.believe_under_floor` framing that makes the checkpoint non-forgeable).
+    A missing/unreadable transcript degrades to NO turns (→ the verdict's UNANCHORED
+    floor: no live turn can match the checkpoint, so the kernel rewinds to nothing).
+  * **`read_checkpoint(...)`** — pull the minted `SuspendCheckpoint` off the run's
+    folded `LedgerState` (`intent_ledger.replay`). The checkpoint was stamped at
+    `OP_SUSPEND`; `state.suspend_checkpoint` is already the read-side object (the fold
+    decoded it). `absent()` when the run never suspended or an older kernel stamped no
+    checkpoint — the honest zero that yields UNANCHORED.
+  * **`fire_from(...)`** — wrap an already-computed `Resume`/`Convergence` verdict as a
+    `FireVerdict`, NEVER re-deriving it (the `resume`/`completion` reuse-not-reimplement
+    rule). The boundary computes the ground-truth stop signal upstream; this only adapts
+    its type.
+
+The served root/config is passed EXPLICITLY (never the process-global active), so a
+long-lived caller fielding several workspaces gets the right tree (the `resume_evidence`
+discipline). Every failure mode degrades to the SAFE direction: a transcript we cannot
+read is treated as NO turns, so the verdict refuses to rewind (UNANCHORED) rather than
+rewinding to a turn it cannot confirm the kernel stamped — fail-closed, the same posture
+`resume_evidence` takes for an unresolvable SHA.
+
+The transcript surface is a CONVENTION, not a kernel-owned format: the host writes its
+turns as JSONL beside the ledger (one record per turn). The kernel reads bytes and hashes
+them; it neither defines nor depends on the turn's internal shape ("the host owns the
+transcript", docs/164 P1.5). A host with its turns elsewhere passes them in directly via
+`turns_from_records` — the file reader is the convenience default, not the contract.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Iterable, Optional
+
+from dos import config as _config
+from dos import intent_ledger as _il
+from dos.completion import Convergence
+from dos.intent_ledger import LedgerState, SuspendCheckpoint
+from dos.resume import Resume
+from dos.rewind import FireVerdict, TurnRef, digest_turn
+
+# The host-owned transcript surface — JSONL, one record per turn, beside intent.jsonl.
+# A CONVENTION (not a kernel format): the kernel hashes each record's bytes, never reads
+# its internal fields. Named here so the reader and a host writer agree on one path.
+TRANSCRIPT_JSONL_NAME = "transcript.jsonl"
+
+
+def transcript_path_for(
+    run_id: str, *, cfg: "_config.SubstrateConfig | None" = None
+) -> Path:
+    """The ``transcript.jsonl`` path for ``run_id`` — beside its ``intent.jsonl``.
+
+    The conversation-axis sibling of `intent_ledger.ledger_path_for`: the host writes
+    its per-turn records here; `gather_turns` hashes them into `TurnRef`s. The kernel
+    owns neither the file's existence nor its record shape — a run with no transcript
+    simply yields no turns (→ UNANCHORED, the safe floor).
+    """
+    return _il.run_dir_for(run_id, cfg=cfg) / TRANSCRIPT_JSONL_NAME
+
+
+def turns_from_records(records: Iterable["bytes | str | dict"]) -> tuple[TurnRef, ...]:
+    """Hash an in-memory sequence of turn records into ``TurnRef(index, digest)``.
+
+    The pure-ish core of the reader (no I/O — the caller already has the records): each
+    record's bytes are digested by `digest_turn` and paired with its position. A `dict`
+    record is canonicalised with sorted keys before hashing so the digest is stable
+    across key-order — the kernel's hash is the anchor's identity, so it must be
+    deterministic for the same logical turn.
+
+    The byte-author discipline (the reason the anchor is non-forgeable): the DIGEST is
+    THIS function's hash of the turn, NOT a value the judged agent supplied. An agent
+    cannot forge the identity of its own turn's digest, exactly as `arg_provenance`'s
+    mint detector turns on the agent not authoring the identity of its own repeated
+    output.
+    """
+    out: list[TurnRef] = []
+    for i, rec in enumerate(records):
+        if isinstance(rec, dict):
+            # Canonical bytes: sorted keys, no whitespace drift → a stable digest for the
+            # same logical turn regardless of how the host serialised it.
+            raw = json.dumps(rec, sort_keys=True, separators=(",", ":"),
+                             ensure_ascii=False, default=str)
+        elif isinstance(rec, bytes):
+            raw = rec
+        else:
+            raw = str(rec)
+        out.append(TurnRef(index=i, digest=digest_turn(raw)))
+    return tuple(out)
+
+
+def gather_turns(
+    run_id: str,
+    *,
+    cfg: "_config.SubstrateConfig | None" = None,
+    path: Path | None = None,
+) -> tuple[TurnRef, ...]:
+    """Read the run's transcript off disk → ``TurnRef``s, hashing each turn. Fail-closed.
+
+    The conversation-axis evidence-gather (the `resume_evidence.gather_ancestry` shape):
+    the file read happens HERE; the already-hashed turns are handed to the pure verdict.
+    Reads `transcript.jsonl` beside the ledger (or an explicit `path`), one record per
+    line, and digests each. Every failure — no file, unreadable, a torn line — degrades
+    to the SAFE direction: that turn (or the whole transcript) yields no `TurnRef`, so a
+    checkpoint can find no matching live turn and the verdict refuses (UNANCHORED) rather
+    than rewinding to a turn it cannot confirm. A torn TAIL line is skipped (the
+    `intent_ledger` torn-tail tolerance), not fatal.
+    """
+    cfg = _config.ensure(cfg)
+    p = path or transcript_path_for(run_id, cfg=cfg)
+    try:
+        text = Path(p).read_text(encoding="utf-8", errors="replace")
+    except (OSError, ValueError):
+        return ()  # no readable transcript → no turns → UNANCHORED (fail-closed)
+    records: list[str] = []
+    for line in text.splitlines():
+        ln = line.strip()
+        if not ln:
+            continue
+        # Hash the LINE bytes as the turn (the host owns the record shape; the kernel
+        # hashes what the host wrote). A line that happens to be JSON is hashed as its
+        # own bytes here — `turns_from_records` canonicalises only when handed a dict.
+        records.append(ln)
+    return turns_from_records(records)
+
+
+def read_checkpoint(state: LedgerState) -> SuspendCheckpoint:
+    """The minted conversation rewind anchor off the folded ledger (or ``absent()``).
+
+    `intent_ledger.replay` already decoded the SUSPEND record's `(checkpoint_turn,
+    transcript_digest)` into `state.suspend_checkpoint`. This is the trivial accessor
+    that names the read for the rewind boundary — the sibling of reading
+    `state.suspend_resume_sha` on the git axis. A run that never suspended, or an older
+    kernel's SUSPEND that stamped no checkpoint, carries `SuspendCheckpoint.absent()` —
+    the honest zero `rewind_plan` maps to UNANCHORED.
+    """
+    return state.suspend_checkpoint
+
+
+def fire_from(
+    *,
+    resume_verdict: Optional[Resume] = None,
+    convergence_verdict: Optional[Convergence] = None,
+) -> FireVerdict:
+    """Adapt an already-computed ground-truth stop verdict into a ``FireVerdict``.
+
+    The boundary computes the stop signal upstream (`resume.resume_plan` → `Resume`;
+    `completion.convergence` → `Convergence`) and this wraps it — NEVER re-deriving it
+    inside the rewind axis (the reuse-not-reimplement rule). Pass whichever fired; both
+    None is a non-firing verdict (→ NO_REWIND, the loop continues).
+    """
+    return FireVerdict(
+        resume_verdict=resume_verdict,
+        convergence_verdict=convergence_verdict,
+    )

dos/rewind_tokens.py

@@ -0,0 +1,252 @@
+"""The no-good verdict-token registry — the rewind note's closed vocabulary, *as data*.
+
+docs/164 §6 (the F1.5 conversation-rewind axis). When the kernel rewinds a
+conversation to a minted checkpoint, the agent re-enters with a **no-good
+annotation**. The single load-bearing rule of that annotation (docs/164 §1, §6)
+is that it may carry **only un-forged bytes** — and the most dangerous failure
+mode is the one `BLOCK` died of: a *generated* explanation of why the branch
+failed ("you should have used a try/except") sneaking in as a note byte. That is
+the forgeable rung; it belongs to F3, behind the apply-gate PEP, never to F1.5.
+
+This module is the structural lock that makes that impossible. It is the
+`reasons.py` `ReasonRegistry` pattern (the closed-enum-as-data hackability seam,
+`docs/HACKING.md`) re-aimed at the no-good vocabulary: the *mechanism* (a token
+RENDERS via a registry-owned template over structured fields the kernel computed)
+lives here; the *set of token kinds* is a closed, ordered, immutable registry. A
+`VerdictToken` is **not a string** — it is a frozen `(kind, payload)` where `kind`
+is drawn from the registry and the rendered string is COMPOSED from the registry's
+own template + the structured fields, never from a free-form caller slot. The
+agent can supply neither the template nor a free field, so there is no reachable
+path by which model-generated prose becomes a note byte (the §6 grep-for-generated
+-prose litmus has nothing to find — `tests/test_rewind.py` pins it).
+
+Why a registry and not a bare enum
+==================================
+
+The same reason `reasons.py` is a registry: a closed set declared ONCE, as data,
+that every consumer derives from. A `VerdictKind` value that is not in the active
+registry is **not renderable** (`render` raises), so a note cannot carry a token
+whose template the kernel did not author. `extend()` returns a NEW registry (you
+compose, you don't mutate), so the closed-set property is a real value-level
+guarantee, not a hope a plugin could scribble over mid-run. The three built-in
+forms are exactly docs/164 §6's three: `DIVERGED`, `VERIFY_NOT_SHIPPED`,
+`TOOL_STREAM_REPEATING`.
+
+Pure stdlib — no third-party imports, no I/O, no `dos`-internal deps (a leaf, like
+`reasons.py`) — so `rewind` can import it as a sibling kernel leaf.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Iterable, Mapping
+
+
+@dataclass(frozen=True)
+class VerdictTokenSpec:
+    """One no-good token KIND, as data — the unit a workspace declares to add a form.
+
+    The `ReasonSpec` analogue. Fields:
+
+      kind     — the closed token identifier (canonical UPPER_SNAKE; the registry
+                 normalizes case on lookup). The thing a `VerdictToken` references;
+                 a token whose kind is not a member of the active registry is not
+                 renderable, which is the structural lock.
+      template — a `str.format_map`-style template OWNED BY THE KERNEL, rendered
+                 over the token's structured `payload`. This is the only source of
+                 the rendered prose — the caller supplies STRUCTURED FIELDS the
+                 kernel computed (a sha, a count), never the sentence. An unknown
+                 payload key is simply absent from the template; a template key the
+                 payload omits renders as an empty placeholder (a defaulting map),
+                 so a partial payload degrades to a still-kernel-authored string,
+                 never a raise that would let an exception text leak.
+      fields   — the payload keys this form expects (documentation + a `dos man`
+                 projection; not enforced — an extra key is dropped, a missing key
+                 blanks). Co-located with the kind by design (the DOM rule).
+      summary  — one-line gloss of what the token MEANS (the man-page NAME line).
+    """
+
+    kind: str
+    template: str
+    fields: tuple[str, ...] = ()
+    summary: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.kind or not self.kind.strip():
+            raise ValueError("VerdictTokenSpec.kind must be a non-empty string")
+        if not self.template or not self.template.strip():
+            raise ValueError(
+                f"VerdictTokenSpec {self.kind!r} must carry a non-empty render "
+                f"template — the kernel-authored string the token renders to "
+                f"(a token with no template would have no un-forged way to render)"
+            )
+
+    @property
+    def key(self) -> str:
+        """The normalized lookup key (UPPER, stripped) — what `get` matches."""
+        return self.kind.strip().upper()
+
+
+class _BlankingDict(dict):
+    """A `format_map` backing dict that renders a missing key as an empty string.
+
+    So a template key the payload omits blanks (kernel-authored, still un-forged)
+    rather than raising a `KeyError` whose text could leak into a caller's except
+    handler. The kernel's template is the author either way.
+    """
+
+    def __missing__(self, key: str) -> str:  # pragma: no cover - exercised via render
+        return ""
+
+
+@dataclass(frozen=True)
+class VerdictToken:
+    """One no-good annotation token: a `(kind, payload)` pair, NEVER a free string.
+
+    This is the (a)-class byte of the docs/164 §6 no-good note. The agent cannot
+    construct one that carries arbitrary prose: `kind` must resolve to a registry
+    spec to render at all, and `payload` is a `{str: str}` map of STRUCTURED fields
+    (a sha, a count, a turn index) that the kernel computed — fed into the
+    registry-owned template. There is no `text`/`message`/`critique` field a caller
+    fills freely. That absence is the lock the §6 grep-litmus relies on.
+
+      kind    — the token identifier; must be a member of the registry that renders
+                it (else `render` raises — an undeclared kind has no kernel template).
+      payload — structured fields (all coerced to `str`), substituted into the
+                registry's template. Extra keys are dropped by the template; missing
+                keys blank. Never a sentence — a count, a sha, an index.
+    """
+
+    kind: str
+    payload: Mapping[str, str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        # Coerce the payload to a plain, immutable-by-discipline str→str dict so a
+        # caller cannot smuggle a non-string (a callable, a nested structure that a
+        # template could `__str__` into prose) into a field slot.
+        object.__setattr__(
+            self,
+            "payload",
+            {str(k): str(v) for k, v in dict(self.payload).items()},
+        )
+
+    @property
+    def key(self) -> str:
+        return self.kind.strip().upper()
+
+
+@dataclass(frozen=True)
+class RewindTokenRegistry:
+    """A closed, ordered set of `VerdictTokenSpec`s — the active no-good vocabulary.
+
+    The `ReasonRegistry` analogue, immutable: `extend()` returns a NEW registry. A
+    process's active registry is a value, never a mutable global a plugin scribbles
+    on — which is what keeps "closed set" a real property. The kernel renders a
+    `VerdictToken` ONLY through this registry's template for the token's kind, so a
+    token whose kind is absent here is structurally unrenderable: there is no
+    code path by which generated prose, lacking a registered kind + template, can
+    become a rendered note byte.
+    """
+
+    specs: tuple[VerdictTokenSpec, ...] = ()
+
+    def __post_init__(self) -> None:
+        seen: set[str] = set()
+        for s in self.specs:
+            if s.key in seen:
+                raise ValueError(
+                    f"duplicate token kind {s.kind!r} in registry — a no-good token "
+                    f"kind is declared exactly once (a later declaration would shadow "
+                    f"silently, the drift this registry exists to forbid)"
+                )
+            seen.add(s.key)
+
+    # -- lookup ------------------------------------------------------------
+    def get(self, kind: str | None) -> VerdictTokenSpec | None:
+        """The spec for `kind`, or None if not a member of this set."""
+        if not kind:
+            return None
+        k = kind.strip().upper()
+        for s in self.specs:
+            if s.key == k:
+                return s
+        return None
+
+    def is_known(self, kind: str | None) -> bool:
+        return self.get(kind) is not None
+
+    def kinds(self) -> tuple[str, ...]:
+        """Every declared kind, in declaration order."""
+        return tuple(s.key for s in self.specs)
+
+    # -- the render mechanism (the whole point) ---------------------------
+    def render(self, token: VerdictToken) -> str:
+        """Render `token` to its KERNEL-AUTHORED string. The only way a token becomes prose.
+
+        The string is composed from THIS registry's template for the token's kind +
+        the token's structured payload. The caller supplied neither — only the
+        structured fields. A token whose kind is not a member of this registry has
+        no kernel template, so it is NOT renderable: `render` raises `ValueError`.
+        That raise is the structural lock — a generated critique, having no
+        registered kind, can never reach a rendered note byte (the §6 litmus). A
+        recognised kind with a partial payload blanks the missing fields
+        (`_BlankingDict`) rather than raising, so a partial-but-honest token still
+        renders a kernel-authored string.
+        """
+        spec = self.get(token.kind)
+        if spec is None:
+            raise ValueError(
+                f"un-renderable no-good token kind {token.kind!r}: not a member of "
+                f"the active RewindTokenRegistry (known: {', '.join(self.kinds()) or '∅'}). "
+                f"A token the kernel has no template for cannot author un-forged note "
+                f"bytes — this is the docs/164 §6 generated-prose lock, working."
+            )
+        return spec.template.format_map(_BlankingDict(token.payload))
+
+    # -- composition (the hackability verb) -------------------------------
+    def extend(self, more: Iterable[VerdictTokenSpec]) -> "RewindTokenRegistry":
+        """Return a NEW registry with `more` appended. The one way to add forms.
+
+        Raises on a colliding kind (the same declared-exactly-once guard
+        `__post_init__` enforces) — a workspace re-declaring a built-in is a mistake
+        to surface, not silently honor.
+        """
+        return RewindTokenRegistry(specs=tuple(self.specs) + tuple(more))
+
+
+# ---------------------------------------------------------------------------
+# The built-in registry — exactly docs/164 §6's three no-good forms. Each
+# template is KERNEL-AUTHORED; the {placeholders} are the structured fields the
+# kernel computed (a sha, a count, a turn index), never a caller-supplied
+# sentence. A workspace adds a form via `BASE_REWIND_TOKENS.extend([...])`.
+# ---------------------------------------------------------------------------
+
+# The closed kind identifiers (string constants so a builder references them by
+# name without re-typing the literal — the lockstep `wedge_reason` uses).
+KIND_DIVERGED = "DIVERGED"
+KIND_VERIFY_NOT_SHIPPED = "VERIFY_NOT_SHIPPED"
+KIND_TOOL_STREAM_REPEATING = "TOOL_STREAM_REPEATING"
+
+BASE_REWIND_TOKENS = RewindTokenRegistry(specs=(
+    VerdictTokenSpec(
+        kind=KIND_DIVERGED,
+        template="resume = DIVERGED",
+        fields=(),
+        summary="ground truth moved past the resume point — the prior branch is a "
+                "dead end (resume.Resume.DIVERGED).",
+    ),
+    VerdictTokenSpec(
+        kind=KIND_VERIFY_NOT_SHIPPED,
+        template="verify = NOT_SHIPPED @ {sha}",
+        fields=("sha",),
+        summary="the claimed phase did not actually ship at the named SHA "
+                "(oracle.is_shipped → NOT_SHIPPED).",
+    ),
+    VerdictTokenSpec(
+        kind=KIND_TOOL_STREAM_REPEATING,
+        template="tool_stream = REPEATING ×{count} @ turn {turn}",
+        fields=("count", "turn"),
+        summary="the same (tool, args, result) recurred N times — the env's results "
+                "stopped advancing (tool_stream.classify_stream → REPEATING).",
+    ),
+))