dos-kernel 0.22.0__py3-none-win_amd64.whl

dos/claim_extract.py

@@ -0,0 +1,229 @@
+"""claim_extract — what (plan, phase) did an agent CLAIM it shipped? (docs/134 §2.1)
+
+The crux of the runtime binding: a `Stop` hook is handed a *transcript*, but the
+truth syscall (`verify`) wants `(plan, phase)`. This module is that bridge — it
+reads what an agent *asserted* it finished, so the hook can check each assertion
+against git. It does NOT verify anything; it only extracts the *claims* to be
+verified (the oracle does the verifying).
+
+Three rungs, strongest-first, mirroring the oracle's own evidence ladder:
+
+  1. **MARKER** (strongest, opt-in): the agent ended a unit with a machine line
+     ``DOS-CLAIM: <plan> <phase>``. Lifted byte-exactly. This is where the
+     operator's literal "@verify-style marker" lives — the agent *declaring what
+     to check*, not a directive DOS executes.
+  2. **FRONTMATTER** (structural): a skill whose frontmatter declares
+     ``dos.plan``/``dos.phase`` makes the claim known without parsing prose. That
+     rung lives at the hook boundary (the firing skill is known there), exposed
+     here as ``claim_from_frontmatter`` so both paths return the same ``Claim``.
+  3. **HEURISTIC** (weakest, ABSTAINING): absent a marker, scan a "shipped/landed
+     /done <ID>" sentence for an explicit plan/phase-shaped token. This rung's
+     ONLY failure mode is a *missed* claim (the agent then stops unverified — the
+     safe direction); it must NEVER fabricate a `(plan, phase)`, because a
+     `verify` run against a hallucinated claim would make the verifier itself the
+     unreliable narrator it exists to catch (docs/103, inward).
+
+The load-bearing rule, stated once: **abstain, never invent.** Free prose ("I'm
+done", "shipped the auth work") yields NO claim — there is no way to know the
+plan/phase *identifiers* from prose without inventing them, so the heuristic only
+fires on an explicit ID-shaped token and is marked low-confidence. A design that
+pretends prose alone is enough is hand-waving (docs/134 §2.1).
+
+Shape follows ``liveness.classify`` / ``git_delta``: the **pure** extractor
+(``extract_claims(text, policy) -> list[Claim]``) operates on already-read text;
+the **boundary reader** (``assistant_text_from_transcript``) does the file/JSON
+I/O at the call site, never inside the pure core. The transcript-parsing
+convention (``message.content`` list of blocks, text from ``block["text"]``)
+mirrors ``scripts/trajectory_audit.py`` so the two readers cannot drift.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+
+
+# The explicit marker an agent (or skill) emits to declare a verifiable claim.
+# Byte-exact, anchored at a line start (after optional list/quote markup) so a
+# mention *inside* prose ("emit a DOS-CLAIM: line") is not mistaken for a real
+# one — only a line that IS the marker counts.
+_MARKER_RE = re.compile(
+    r"""^[ \t>*\-]*           # optional leading markup (blockquote, list bullet)
+        DOS-CLAIM:[ \t]+      # the literal marker
+        (?P<plan>[^\s]+)      # plan token (no whitespace)
+        [ \t]+
+        (?P<phase>[^\s]+)     # phase token (no whitespace)
+        [ \t]*$               # nothing else on the line
+    """,
+    re.VERBOSE | re.MULTILINE,
+)
+
+# A plan/phase-shaped identifier for the HEURISTIC rung: an uppercase-led token
+# of LETTERS then DIGITS (AUTH2, FQ390, DLA3) — the shape this codebase's phases
+# actually take. Deliberately narrow: it will MISS a lowercased or prose-only
+# claim (safe — abstain) rather than guess. It never matches a bare English word
+# (no digits) so "done" / "shipped" alone yield nothing.
+_PHASE_TOKEN_RE = re.compile(r"\b([A-Z][A-Z_]*[A-Z])(\d+)\b")
+
+# The completion verbs that gate the heuristic rung — the phase-shaped token must
+# sit in a sentence that actually CLAIMS completion, not merely mentions the id.
+_COMPLETION_HINT_RE = re.compile(
+    r"\b(shipped|landed|completed|finished|done|merged)\b", re.IGNORECASE
+)
+
+
+@dataclass(frozen=True)
+class Claim:
+    """One (plan, phase) an agent claimed shipped, plus how we know.
+
+    ``rung`` is ``marker`` › ``frontmatter`` › ``heuristic`` (strongest-first),
+    the same provenance discipline as the oracle's ``source`` tag. ``raw`` is the
+    text the claim was lifted from (the marker line, or the sentence), for an
+    auditable trail. ``confident`` is False only for the heuristic rung — a
+    caller may choose to treat a low-confidence claim as advisory.
+    """
+
+    plan: str
+    phase: str
+    rung: str
+    raw: str = ""
+
+    @property
+    def confident(self) -> bool:
+        return self.rung in ("marker", "frontmatter")
+
+    def to_dict(self) -> dict:
+        return {
+            "plan": self.plan,
+            "phase": self.phase,
+            "rung": self.rung,
+            "raw": self.raw,
+            "confident": self.confident,
+        }
+
+
+def claim_from_frontmatter(plan: str | None, phase: str | None) -> list[Claim]:
+    """The FRONTMATTER rung: a skill declared (dos.plan, dos.phase).
+
+    Returns a single-element list when both are present, else empty. Pure — the
+    hook reads the frontmatter at the boundary and passes the two strings in.
+    """
+    plan = (plan or "").strip()
+    phase = (phase or "").strip()
+    if plan and phase:
+        return [Claim(plan=plan, phase=phase, rung="frontmatter",
+                      raw=f"dos.plan={plan} dos.phase={phase}")]
+    return []
+
+
+def extract_claims(text: str, *, allow_heuristic: bool = True) -> list[Claim]:
+    """The PURE extractor: claims an agent asserted, strongest rung first.
+
+    Operates on already-read assistant text (the boundary reader hands it over).
+    No I/O. Deterministic. Deduplicates on (plan, phase), keeping the strongest
+    rung. ``allow_heuristic=False`` restricts to the byte-exact MARKER rung — the
+    fail-closed posture a strict caller wants (only act on what the agent
+    explicitly declared).
+
+    Returns ``[]`` when nothing is confidently extractable — the abstain floor.
+    """
+    if not text:
+        return []
+
+    out: dict[tuple[str, str], Claim] = {}
+
+    # Rung 1 — the byte-exact marker. Strongest; always honored.
+    for m in _MARKER_RE.finditer(text):
+        plan, phase = m.group("plan"), m.group("phase")
+        out[(plan, phase)] = Claim(plan=plan, phase=phase, rung="marker",
+                                   raw=m.group(0).strip())
+
+    if not allow_heuristic:
+        return list(out.values())
+
+    # Rung 3 — the abstaining heuristic. Only fires when a phase-SHAPED token
+    # (AUTH2) sits in a sentence that also carries a completion verb. This never
+    # invents an id from prose: no ID-shaped token ⇒ no claim. A token already
+    # captured by the marker rung is not downgraded.
+    for line in text.splitlines():
+        if not _COMPLETION_HINT_RE.search(line):
+            continue
+        for tok in _PHASE_TOKEN_RE.finditer(line):
+            phase = tok.group(0)            # e.g. "AUTH2"
+            plan = tok.group(1)             # the letter stem, e.g. "AUTH"
+            key = (plan, phase)
+            if key in out:
+                continue                    # don't shadow a stronger rung
+            out[key] = Claim(plan=plan, phase=phase, rung="heuristic",
+                             raw=line.strip())
+
+    return list(out.values())
+
+
+# ---------------------------------------------------------------------------
+# Boundary I/O — the transcript reader. NOT pure (reads a file); kept here so the
+# extractor's caller has one home for the read, the git_delta discipline.
+# ---------------------------------------------------------------------------
+def _text_blocks(content: object) -> list[str]:
+    """Pull text from a message `content` (a str, or a list of typed blocks).
+
+    Mirrors scripts/trajectory_audit.py so the two transcript readers can't drift.
+    """
+    if isinstance(content, str):
+        return [content]
+    if isinstance(content, list):
+        texts: list[str] = []
+        for b in content:
+            if isinstance(b, dict) and b.get("type") == "text":
+                t = b.get("text", "")
+                if isinstance(t, str) and t:
+                    texts.append(t)
+        return texts
+    return []
+
+
+def assistant_text_from_transcript(path: str, *, last_turns: int = 1) -> str:
+    """Read the text of the last N assistant turn(s) from a transcript JSONL.
+
+    The Stop hook is told to verify "what the agent just claimed," so we read the
+    *tail* — the final assistant turn(s) — not the whole session (an earlier,
+    superseded claim must not re-trigger). Returns the concatenated text, or ``""``
+    on any read/parse failure (the no-crash floor: a missing/garbled transcript
+    yields no claims, the agent stops unverified — the safe direction).
+    """
+    if last_turns < 1:
+        last_turns = 1
+    try:
+        lines = _read_lines(path)
+    except OSError:
+        return ""
+
+    # Collect assistant-turn texts in order, then keep the last N.
+    turns: list[str] = []
+    for raw in lines:
+        raw = raw.strip()
+        if not raw:
+            continue
+        try:
+            obj = json.loads(raw)
+        except (ValueError, TypeError):
+            continue
+        if not isinstance(obj, dict):
+            continue
+        msg = obj.get("message")
+        if not isinstance(msg, dict) or msg.get("role") != "assistant":
+            continue
+        blocks = _text_blocks(msg.get("content"))
+        if blocks:
+            turns.append("\n".join(blocks))
+
+    if not turns:
+        return ""
+    return "\n".join(turns[-last_turns:])
+
+
+def _read_lines(path: str) -> list[str]:
+    """Read a transcript file's lines (split out so a test can monkeypatch I/O)."""
+    with open(path, "r", encoding="utf-8", errors="replace") as fh:
+        return fh.readlines()

dos/claim_ttl.py

@@ -0,0 +1,150 @@
+"""Claim TTL / kind / status math — pure branch logic over scalars.
+
+Lifted from the job userland's ``scripts/fanout_state.py`` (MQ3X P1, docs/62).
+The kernel half of the OS7 per-status TTL model: given a claim's
+``(status, kind, expected_wallclock)`` scalars (and a frozen ``TtlPolicy`` of the
+host's tuning), compute how long the claim lives. Plus the legacy-row inference
+(``infer_kind`` / ``infer_status``) the ``stats`` / ``disambiguate`` verbs use to
+label un-migrated rows consistently.
+
+``dos`` carries **mechanism, not policy** (the package-wide invariant): the OS7
+minute constants are job *tuning*, so they live on a ``TtlPolicy`` dataclass the
+CALLER supplies — exactly the ``LivenessPolicy`` / ``loop_decide`` thresholds
+split. The defaults below match the job's historical values so a caller that
+passes ``DEFAULT_POLICY`` (or nothing) is byte-identical to the pre-lift code.
+
+Purity boundary (docs/62 §0): every function here takes scalars and returns
+scalars — zero ``datetime.now`` / ``os`` / ``Path`` / ``open`` / ``yaml`` /
+``importlib``. The three job-side functions that read the CLOCK
+(``_compute_expires_at`` / ``_claim_heartbeat_expired`` / ``_is_working_claim_fresh``)
+keep their clock-reading WRAPPER in ``agents/leases/`` and delegate their decision
+to the ``now``-injected pure cores here (``expires_at_from`` is the first; the
+others land with the P3 io-layer move).
+"""
+from __future__ import annotations
+
+import datetime as _dt
+from dataclasses import dataclass
+
+# Claim taxonomy — the closed value sets. Carried with the inference functions
+# because they decide which inferred label is "valid" (explicit field wins).
+VALID_CLAIM_KINDS = ("soft", "hard", "agent_in_session")
+VALID_CLAIM_STATUSES = ("working", "awaiting_decision", "awaiting_commit", "stale", "done")
+
+
+@dataclass(frozen=True)
+class TtlPolicy:
+    """OS7 per-status TTL tuning — policy, not mechanism (job-side data).
+
+    The single 90-min TTL was wrong for all three claim kinds; TTL now matches the
+    kind's lifecycle. ``None`` resolved minutes = infinity (no ``claim_expires_at``
+    written). The defaults reproduce the job's historical constants exactly:
+
+      awaiting_commit_minutes  — 24h, drives the OS2 auto-archive cadence.
+      agent_in_session_minutes — 6h, one operator session (overrides status).
+      default_working_wallclock_minutes — used when ``expected_wallclock`` is absent
+                                 (matches pre-OS7 ``--ttl-minutes 90`` callsites).
+      working_ttl_multiplier   — working TTL = ``expected_wallclock × multiplier``.
+    """
+
+    awaiting_commit_minutes: int = 24 * 60
+    agent_in_session_minutes: int = 6 * 60
+    default_working_wallclock_minutes: int = 30
+    working_ttl_multiplier: int = 3
+
+    def __post_init__(self) -> None:
+        for name in (
+            "awaiting_commit_minutes", "agent_in_session_minutes",
+            "default_working_wallclock_minutes", "working_ttl_multiplier",
+        ):
+            if getattr(self, name) < 0:
+                raise ValueError(f"TtlPolicy.{name} must be non-negative")
+
+
+DEFAULT_POLICY = TtlPolicy()
+
+
+def infer_kind(
+    entry: dict,
+    dispatcher_kinds: tuple[tuple[str, str], ...] = (),
+) -> str:
+    """Infer claim_kind for legacy rows that pre-date the 2026-05-13 schema
+    addition. Used by ``disambiguate`` and ``stats`` so the operator sees a
+    consistent kind label even on un-migrated rows. Never written back to disk;
+    the explicit field on new rows takes precedence.
+
+    ``dispatcher_kinds`` is the host's ``(dispatched_by-prefix, claim_kind)`` map for
+    the legacy fallback — the prefixes name a host's dispatcher SKILLS (e.g. the
+    reference app's ``fanout-`` → ``hard`` / ``next-up-`` → ``soft``), so the kernel
+    hardcodes NONE of them (userland-coupling audit 2026-06-08): the host passes its
+    own. Pairs are tried in order; the first matching prefix wins. Empty (the kernel
+    default) means a row with no explicit kind / TTL is simply ``unknown``."""
+    if entry.get("claim_kind") in VALID_CLAIM_KINDS:
+        return entry["claim_kind"]
+    if entry.get("claim_expires_at"):
+        return "soft"
+    by = (entry.get("dispatched_by") or "").lower()
+    for prefix, kind in dispatcher_kinds:
+        if by.startswith(prefix.lower()):
+            return kind
+    return "unknown"
+
+
+def infer_status(entry: dict) -> str:
+    """Infer claim_status. Returns 'working' for in_progress rows lacking explicit
+    claim_status; the precise working/stale split needs heartbeat substrate."""
+    if entry.get("claim_status") in VALID_CLAIM_STATUSES:
+        return entry["claim_status"]
+    if entry.get("status") == "in_progress":
+        return "working"
+    return entry.get("status", "unknown")
+
+
+def expected_wallclock(claim_kind: str, ttl_minutes: int | None) -> int:
+    """Default expected wallclock per claim_kind. Used by the stale detector when
+    an explicit ``expected_wallclock_minutes`` isn't set on the row."""
+    if ttl_minutes:
+        return ttl_minutes
+    if claim_kind == "soft":
+        return 90
+    if claim_kind == "agent_in_session":
+        return 60  # in-conversation agents tend to be quicker
+    return 360  # hard fanout default — agents can take up to a few hours
+
+
+def resolve_ttl_minutes(
+    claim_status: str, claim_kind: str,
+    expected_wallclock_minutes: int | None,
+    policy: TtlPolicy = DEFAULT_POLICY,
+) -> int | None:
+    """OS7 — per-status TTL formula. Returns minutes until claim expiry, or
+    ``None`` for infinity (no TTL field written).
+
+    Resolution order:
+      1. claim_kind=agent_in_session → 6h (in-conversation agents shouldn't linger
+         past one operator session; overrides status formula).
+      2. claim_status=working → expected_wallclock × multiplier (defaults to
+         ``policy.default_working_wallclock_minutes`` when expected_wallclock is
+         absent — matches pre-OS7 behaviour for legacy ``--ttl-minutes 90``).
+      3. claim_status=awaiting_commit → 24h (drives OS2 auto-archive).
+      4. claim_status=awaiting_decision / stale → None (operator drives resolution).
+    """
+    if claim_kind == "agent_in_session":
+        return policy.agent_in_session_minutes
+    if claim_status == "working":
+        ew = expected_wallclock_minutes or policy.default_working_wallclock_minutes
+        return ew * policy.working_ttl_multiplier
+    if claim_status == "awaiting_commit":
+        return policy.awaiting_commit_minutes
+    return None
+
+
+def expires_at_from(now: _dt.datetime, ttl_minutes: int | None) -> str | None:
+    """Pure core of ``_compute_expires_at``: convert a TTL in minutes (or
+    None=infinity) to an ISO ``%Y-%m-%dT%H:%MZ`` timestamp, given an injected
+    ``now``. The clock-reading wrapper (``agents/leases/ttl.py``) supplies
+    ``dt.datetime.now(dt.timezone.utc)``; this stays pure + replay-testable."""
+    if ttl_minutes is None:
+        return None
+    expiry = now + _dt.timedelta(minutes=ttl_minutes)
+    return expiry.strftime("%Y-%m-%dT%H:%MZ")