gini-toolkit 6.0.1.dev0__py3-none-any.whl

gini/agent/tools/registry.py

@@ -0,0 +1,193 @@
+"""Shared tool registry — the single contract for build / inspect / explain / present.
+
+One registry is consumed by BOTH the in-app agent loop (local Ollama) and the MCP
+server (external agents). Register a tool once and it's available everywhere. Each
+tool carries a JSON-Schema parameter spec, so it can be handed to an LLM as an
+OpenAI/Ollama-style function and executed by name.
+"""
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from ..api import GiniAPI
+
+
+@dataclass
+class ToolSpec:
+    name: str
+    description: str
+    parameters: dict          # JSON Schema (object)
+    handler: Callable[..., Any]
+    group: str = "general"    # build | inspect | explain | present
+
+    def to_openai(self) -> dict:
+        return {"type": "function", "function": {
+            "name": self.name,
+            "description": self.description,
+            "parameters": self.parameters,
+        }}
+
+
+class ToolRegistry:
+    def __init__(self) -> None:
+        self._tools: dict[str, ToolSpec] = {}
+
+    def register(self, spec: ToolSpec) -> None:
+        self._tools[spec.name] = spec
+
+    def specs(self) -> list[ToolSpec]:
+        return list(self._tools.values())
+
+    def openai_tools(self) -> list[dict]:
+        return [t.to_openai() for t in self._tools.values()]
+
+    def names(self) -> list[str]:
+        return list(self._tools)
+
+    def execute(self, name: str, args: dict | None = None) -> Any:
+        args = args or {}
+        spec = self._tools.get(name)
+        if spec is None:
+            return {"error": f"unknown tool {name!r}"}
+        try:
+            return spec.handler(**args)
+        except TypeError as e:
+            return {"error": f"bad arguments for {name}: {e}"}
+        except Exception as e:  # surface to the agent rather than crashing
+            return {"error": str(e)}
+
+
+# JSON-schema fragments
+_STR = {"type": "string"}
+_NUM = {"type": "number"}
+
+
+def build_registry(api: GiniAPI) -> ToolRegistry:
+    """Register the GiniAPI surface as tools. `present` tools are added in phase A3."""
+    r = ToolRegistry()
+
+    r.register(ToolSpec(
+        "list_device_types", "List every device/element type GINI can place (networking + cloud).",
+        {"type": "object", "properties": {}},
+        lambda: api.list_device_types(), group="inspect"))
+
+    r.register(ToolSpec(
+        "add_device", "Add a device. type_key e.g. 'router','switch','vpc','container','instance'.",
+        {"type": "object",
+         "properties": {"type_key": _STR, "name": _STR, "x": _NUM, "y": _NUM},
+         "required": ["type_key"]},
+        lambda type_key, name="", x=0.0, y=0.0:
+            api.add_device(type_key, name=name or None, x=x, y=y), group="build"))
+
+    r.register(ToolSpec(
+        "connect_devices", "Create a link between two devices (by name or id).",
+        {"type": "object",
+         "properties": {"a": _STR, "b": _STR, "label": _STR}, "required": ["a", "b"]},
+        lambda a, b, label="": api.connect(a, b, label), group="build"))
+
+    r.register(ToolSpec(
+        "set_property", "Set a property on a device (by name or id).",
+        {"type": "object",
+         "properties": {"device": _STR, "key": _STR, "value": _STR},
+         "required": ["device", "key", "value"]},
+        lambda device, key, value: api.set_property(device, key, value), group="build"))
+
+    r.register(ToolSpec(
+        "remove_device", "Remove a device (by name or id).",
+        {"type": "object", "properties": {"device": _STR}, "required": ["device"]},
+        lambda device: (api.remove_device(device), {"removed": device})[1], group="build"))
+
+    r.register(ToolSpec(
+        "inspect_device", "Inspect a device's type, properties, neighbors, and degree.",
+        {"type": "object", "properties": {"device": _STR}, "required": ["device"]},
+        lambda device: api.inspect(device), group="inspect"))
+
+    r.register(ToolSpec(
+        "get_topology", "Return the full topology as JSON (devices + links).",
+        {"type": "object", "properties": {}},
+        lambda: api.get_topology(), group="inspect"))
+
+    r.register(ToolSpec(
+        "summarize_topology", "Counts of devices, links, and categories.",
+        {"type": "object", "properties": {}},
+        lambda: api.summary(), group="inspect"))
+
+    r.register(ToolSpec(
+        "explain_topology", "Explain the whole topology in plain language for a student.",
+        {"type": "object", "properties": {}},
+        lambda: api.explain_topology(), group="explain"))
+
+    r.register(ToolSpec(
+        "explain_device", "Explain a single device in plain language for a student.",
+        {"type": "object", "properties": {"device": _STR}, "required": ["device"]},
+        lambda device: api.explain_device(device), group="explain"))
+
+    r.register(ToolSpec(
+        "explain_element", "Explain a palette element TYPE (e.g. 'router', 'switch', "
+        "'hub', 'load_balancer') — what it is and when to use it vs. similar elements. "
+        "Use when the student asks about an element from the palette, not a placed device.",
+        {"type": "object", "properties": {"type_key": _STR}, "required": ["type_key"]},
+        lambda type_key: api.explain_element_type(type_key), group="explain"))
+
+    r.register(ToolSpec(
+        "trace_path", "Get the hop-by-hop device path a packet takes from one device to "
+        "another (names). Feed the result to animate_packet to show it on the canvas.",
+        {"type": "object", "properties": {"src": _STR, "dst": _STR},
+         "required": ["src", "dst"]},
+        lambda src, dst: {"path": api.trace_path(src, dst)}, group="inspect"))
+
+    _register_present(r, api)
+    return r
+
+
+def _register_present(r: ToolRegistry, api: GiniAPI) -> None:
+    """The `present` verb — the AI tutor's stage. Handlers emit on the event bus;
+    the canvas overlay renders them. Available to the in-app loop and external agents."""
+    bus = api.ctx.bus
+
+    def ids(names: list[str]) -> list[str]:
+        out = []
+        for n in names or []:
+            try:
+                out.append(api._resolve(n).id)
+            except KeyError:
+                pass
+        return out
+
+    _ARR = {"type": "array", "items": _STR}
+
+    r.register(ToolSpec(
+        "spotlight", "Spotlight device(s) by name and dim the rest, to focus attention.",
+        {"type": "object", "properties": {"targets": _ARR}, "required": ["targets"]},
+        lambda targets: (bus.present_spotlight.emit(ids(targets)), {"spotlight": targets})[1],
+        group="present"))
+
+    r.register(ToolSpec(
+        "highlight", "Outline/ring device(s) by name without dimming others.",
+        {"type": "object", "properties": {"targets": _ARR}, "required": ["targets"]},
+        lambda targets: (bus.present_highlight.emit(ids(targets)), {"highlight": targets})[1],
+        group="present"))
+
+    r.register(ToolSpec(
+        "callout", "Show an anchored speech bubble on a device with explanatory text.",
+        {"type": "object", "properties": {"device": _STR, "text": _STR},
+         "required": ["device", "text"]},
+        lambda device, text: (bus.present_callout.emit(ids([device])[0] if ids([device]) else "", text),
+                              {"callout": device})[1], group="present"))
+
+    r.register(ToolSpec(
+        "narrate", "Speak a line of narration to the student (shown on the canvas).",
+        {"type": "object", "properties": {"text": _STR}, "required": ["text"]},
+        lambda text: (bus.present_narrate.emit(text), {"narrated": True})[1], group="present"))
+
+    r.register(ToolSpec(
+        "animate_packet", "Animate a packet travelling along a path of device names.",
+        {"type": "object", "properties": {"path": _ARR}, "required": ["path"]},
+        lambda path: (bus.present_packet.emit(ids(path)), {"animated": path})[1], group="present"))
+
+    r.register(ToolSpec(
+        "clear_stage", "Clear all tutor overlays (spotlights, callouts, highlights).",
+        {"type": "object", "properties": {}},
+        lambda: (bus.present_clear.emit(), {"cleared": True})[1], group="present"))

gini/agent/twin/__init__.py

@@ -0,0 +1,28 @@
+"""The Reasoning Twin — a deterministic (non-LLM) shadow that twins each structured reasoning
+turn and checks the LLM caught the main points (docs/REASONING_2.0_DESIGN.md).
+
+It enumerates the concerns that matter (from GINI's symbolic substrate — blackboard verdicts,
+the predicate explainer, legality flags), asks the Reasoning persona to report coverage against
+them, diffs that report EXACTLY (a set diff, no NLP), poses "why not X?" objections for silent
+misses, and — after one bounded revision round — turns surviving objections into visible flags.
+It is a challenger, never a judge: verdicts still come only from the deterministic oracle, and
+with the Twin disabled every turn behaves exactly as before.
+"""
+from .contracts import Concern, Coverage, Objection, parse_coverage
+from .dialectic import (
+    COVERAGE_SCHEMA, Twin, TwinContext, TwinResult, concern_context, coverage_instruction,
+)
+from .authoring import authoring_concerns
+from .harness import GoldenTurn, HarnessReport, replay
+from .justify import Adjudication, adjudicate, classify, state_holds
+from .learner import learner_concerns
+from .mission import mission_concerns
+from .os_coach import coach_concerns, fallback_text, focus_line
+from .salience import MAX_CONCERNS, MUST_ADDRESS, cap
+
+__all__ = ["Concern", "Coverage", "Objection", "parse_coverage", "Twin", "TwinContext",
+           "TwinResult", "concern_context", "coverage_instruction", "COVERAGE_SCHEMA",
+           "Adjudication", "adjudicate", "classify", "state_holds", "mission_concerns",
+           "coach_concerns", "focus_line", "fallback_text", "authoring_concerns",
+           "learner_concerns", "GoldenTurn", "HarnessReport", "replay",
+           "MAX_CONCERNS", "MUST_ADDRESS", "cap"]

gini/agent/twin/authoring.py

@@ -0,0 +1,71 @@
+"""The authoring/compose concern enumerator (REASONING_2.0_DESIGN.md §5, third surface).
+
+These concerns run at RATIFY time, teacher-facing: deterministic observations about the gap
+between what the teacher's words said and what the model picked — "the words strongly match Y
+but X was chosen; why not Y?" — plus a check that stated DON'Ts really were honoured. The
+ratify UI renders them as questions beside the Proposal; nothing here blocks or judges."""
+from __future__ import annotations
+
+from .contracts import Concern
+from .salience import cap
+
+_DISAGREE_MARGIN = 3     # the lexical-override threshold lesson_resolver already uses
+
+
+def authoring_concerns(intent_text: str, proposal) -> list[Concern]:
+    """Concerns about a compose/resolve Proposal, for the ratify surface. Duck-typed against
+    `lesson_resolver.Proposal` (archetype_id, lesson, infeasible, suppressed)."""
+    concerns: list[Concern] = []
+
+    # 1) strong lexical disagreement: the teacher's words match a different archetype hard.
+    try:
+        from ..lesson_resolver import lexical_scores
+        scores = lexical_scores(intent_text)
+        if scores:
+            top_id, top_score = scores[0]
+            if top_id != getattr(proposal, "archetype_id", "") and top_score >= _DISAGREE_MARGIN:
+                concerns.append(Concern(
+                    id=f"authoring:lexical-disagreement:{top_id}",
+                    kind="composition-gap",
+                    statement=(f"the request's words strongly match '{top_id}' but "
+                               f"'{proposal.archetype_id}' was chosen — why not {top_id}?"),
+                    evidence=f"lexical score {top_score} for {top_id} (defining-field overlap)",
+                    salience=2, source="lesson_resolver.lexical_scores"))
+    except Exception:
+        pass
+
+    # 2) stated DON'Ts must be honoured in the assembled lesson (deterministic negation scan
+    #    against the elements the lesson actually stages/grades).
+    try:
+        from ...domain import constraints as _con
+        excluded = set(getattr(_con.from_text(intent_text), "exclude", ()) or ())
+        lesson = getattr(proposal, "lesson", None)
+        if excluded and lesson is not None:
+            staged = {getattr(d, "type_key", "") for d in
+                      getattr(getattr(lesson, "stage", None), "values", lambda: [])()} \
+                if hasattr(getattr(lesson, "stage", None), "values") else set()
+            violated = sorted(excluded & staged)
+            if violated:
+                concerns.append(Concern(
+                    id="authoring:exclusion-violated", kind="composition-gap",
+                    statement=("the request excluded " + ", ".join(violated) +
+                               " but the proposal stages them"),
+                    evidence=f"negation scan: exclude={sorted(excluded)}; staged∩={violated}",
+                    salience=3, source="constraints.from_text"))
+    except Exception:
+        pass
+
+    # 3) infeasibility / suppression the resolver already computed — surfaced as concerns so the
+    #    ratify UI shows them in the same voice.
+    if getattr(proposal, "infeasible", ""):
+        concerns.append(Concern(
+            id="authoring:infeasible", kind="composition-gap",
+            statement=f"the request is infeasible as stated: {proposal.infeasible}",
+            evidence=proposal.infeasible, salience=3, source="lesson_resolver"))
+    if getattr(proposal, "suppressed", ""):
+        concerns.append(Concern(
+            id="authoring:suppressed", kind="composition-gap",
+            statement=f"something was left out to honour the DON'Ts: {proposal.suppressed}",
+            evidence=proposal.suppressed, salience=2, source="lesson_resolver"))
+
+    return cap(concerns)

gini/agent/twin/contracts.py

@@ -0,0 +1,54 @@
+"""Twin contracts — the Concern (a point that matters), the Coverage report (what the model says
+it addressed), and the Objection (the Twin's challenge). Plain dataclasses; no Qt, no LLM.
+
+A Concern is only ever emitted with `evidence` — a deterministic ground fact from the substrate.
+The Twin can only cite what GINI can prove (REASONING_2.0_DESIGN.md §7)."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class Concern:
+    id: str            # stable, e.g. "objective:web-reach", "legality:off_task"
+    kind: str          # objective | legality | grammar-option | watcher-event | composition-gap
+    statement: str     # human-readable: what matters ("'Wire the LAN to a router' is unmet")
+    evidence: str      # the deterministic ground fact backing it (explain why / verdict data)
+    salience: int = 1  # 0..3 (rules-only, twin/salience.py); >= MUST_ADDRESS -> must be covered
+    source: str = ""   # which substrate produced it (debugging / eval)
+
+
+@dataclass
+class Coverage:
+    """The model's self-report, used ONLY as an index for the exact diff — never trusted as
+    truth (omission justifications get validated; false 'addressed' claims are the eval
+    harness's and verify_claims' business)."""
+    addressed: frozenset = field(default_factory=frozenset)   # concern ids
+    omitted: dict = field(default_factory=dict)               # concern id -> one-line why
+
+
+def parse_coverage(obj) -> Coverage | None:
+    """The `coverage` member of the persona's JSON reply -> Coverage, or None when absent or
+    malformed (-> the coverage-silent posture; must never raise)."""
+    if not isinstance(obj, dict):
+        return None
+    addressed = obj.get("addressed")
+    omitted_raw = obj.get("omitted")
+    if not isinstance(addressed, list) and not isinstance(omitted_raw, list):
+        return None
+    omitted: dict = {}
+    for entry in omitted_raw if isinstance(omitted_raw, list) else []:
+        if isinstance(entry, dict) and entry.get("id"):
+            omitted[str(entry["id"])] = str(entry.get("why", ""))
+        elif isinstance(entry, str) and entry:
+            omitted[entry] = ""
+    return Coverage(
+        addressed=frozenset(str(a) for a in (addressed or []) if a),
+        omitted=omitted)
+
+
+@dataclass(frozen=True)
+class Objection:
+    """A challenge the Twin poses for a silently-missed (or unjustified) concern."""
+    concern: Concern
+    question: str

gini/agent/twin/dialectic.py

@@ -0,0 +1,189 @@
+"""The dialectic — the Twin's audit of one reasoning turn (REASONING_2.0_DESIGN.md §3.4).
+
+Deterministic control flow throughout: an EXACT set diff of the model's coverage report against
+the must-address concerns; ADJUDICATION of every claimed omission against ground truth
+(twin/justify.py — an objection is defeated only by a VALIDATED justification); template-
+generated objections; a bounded dialectic (max_rounds revisions or the time budget, whichever
+first) driven by the persona's existing `react(note=…)` mechanism; and surviving objections
+turned into a visible flag appended to the move — never a silent ship, never suppression.
+
+The Twin also keeps per-mission state: the HISTORY of concern ids the model actually covered
+(what "already addressed" is checked against) and METRICS (phase-E raw material)."""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+
+from .contracts import Concern, Coverage, Objection
+from .justify import Adjudication, adjudicate
+
+# The decoder-constrained reply shape for a covered reasoning turn (via Ollama structured
+# outputs — see agent/llm/ollama.py `schema=`). text = the tutor line; coverage = the report.
+COVERAGE_SCHEMA: dict = {
+    "type": "object",
+    "properties": {
+        "text": {"type": "string"},
+        "coverage": {
+            "type": "object",
+            "properties": {
+                "addressed": {"type": "array", "items": {"type": "string"}},
+                "omitted": {"type": "array", "items": {
+                    "type": "object",
+                    "properties": {"id": {"type": "string"}, "why": {"type": "string"}},
+                    "required": ["id"],
+                }},
+            },
+            "required": ["addressed", "omitted"],
+        },
+    },
+    "required": ["text", "coverage"],
+}
+
+
+def concern_context(concerns: list[Concern]) -> str:
+    """Twin-as-context (phase B): the concern set injected UP FRONT into the grounding, so the
+    substrate's guaranteed recall shapes the DRAFT — the same enumeration that later audits it.
+    Statements + evidence only; what to do about them stays the model's call."""
+    if not concerns:
+        return ""
+    lines = [f"- {c.statement} ({c.evidence})" for c in concerns]
+    return "Things that matter right now (ground truth):\n" + "\n".join(lines)
+
+
+def coverage_instruction(concerns: list[Concern]) -> str:
+    """The reporting checklist appended to the persona task — the INDEX the exact diff runs
+    against (ids the reply must account for, addressed or justified)."""
+    lines = [f'  {c.id}: {c.statement}' for c in concerns]
+    return (
+        "\nRespond as ONE JSON object: {\"text\": \"<your line to the student>\", \"coverage\": "
+        "{\"addressed\": [<concern ids your line addresses>], \"omitted\": [{\"id\": \"<concern "
+        "id>\", \"why\": \"<one line>\"}]}}. Every concern below must appear in either list; "
+        "omitting is fine WITH a reason (e.g. it would give the answer away, or it is off this "
+        "question's topic).\nConcerns:\n" + "\n".join(lines))
+
+
+def _question(c: Concern) -> str:
+    if c.kind == "legality":
+        return (f"You did not address this: {c.statement}. It is an active rule violation "
+                f"({c.evidence}) — why not?")
+    return (f"You did not address this: {c.statement} ({c.evidence}). "
+            "Is it OK to leave that out? If it belongs in your line, work it in.")
+
+
+def _rejected_question(c: Concern, why: str, adj: Adjudication) -> str:
+    """The objection for an omission whose justification failed adjudication — it tells the
+    model exactly why its excuse doesn't hold (the ground the Twin checked)."""
+    return (f"You left out {c.statement!r} saying {why!r}, but {adj.reason}. "
+            "Address it, or give a reason that actually holds.")
+
+
+@dataclass
+class TwinContext:
+    """What omission adjudication needs from the turn (built by the orchestrator)."""
+    move_kind: str = "say"
+    utterance: str = ""
+    world: object = None                      # the live board (for state-claim checks)
+    history: set = field(default_factory=set)  # concern ids covered in prior turns
+    translate: object = None                   # callable(why) -> predicate | None (LLM-backed)
+
+
+@dataclass
+class TwinResult:
+    """What one audit produced — for tests, metrics (phase E), and the instructor log."""
+    concerns: tuple = ()
+    coverage_silent: bool = False
+    objections: tuple = ()           # first-round objections
+    surviving: tuple = ()            # objections still standing after the revision round(s)
+    accepted_omissions: dict = field(default_factory=dict)   # id -> VALIDATED why
+    rejected_omissions: dict = field(default_factory=dict)   # id -> why the justification failed
+    rounds: int = 0
+
+
+class Twin:
+    """The Reasoning Twin's audit half. `audit` = exact diff + omission adjudication (phase B);
+    `note`/`flag` are the two ways an objection re-enters the turn. Per-mission state: covered-
+    concern history + metrics. Bounds: `max_rounds` revisions or `budget_s`, whichever first."""
+
+    def __init__(self, max_rounds: int = 2, budget_s: float = 4.0) -> None:
+        self.max_rounds = max_rounds
+        self.budget_s = budget_s
+        self.history: set = set()            # concern ids the model actually covered, ever
+        self.metrics: dict = {"turns": 0, "coverage_silent": 0, "objections": 0,
+                              "defeats": 0, "revisions": 0, "flags": 0}
+        self.last_adjudications: dict = {}   # id -> Adjudication (of the most recent audit)
+
+    def diff(self, concerns: list[Concern], coverage: Coverage | None) -> list[Objection]:
+        """Exact diff of the coverage report against the must-address concerns — the SILENT
+        misses only (omissions are the `audit` step's business).
+
+        Coverage-silent (no report — model without schema support, or the offline fallback):
+        don't guess what the prose covered; object only about the URGENT tier (salience 3),
+        so a degraded model still surfaces rule violations without nagging about the rest."""
+        from .salience import MUST_ADDRESS
+        if coverage is None:
+            return [Objection(c, _question(c)) for c in concerns if c.salience >= 3]
+        seen = coverage.addressed | set(coverage.omitted)
+        return [Objection(c, _question(c))
+                for c in concerns
+                if c.salience >= MUST_ADDRESS and c.id not in seen]
+
+    def audit(self, concerns: list[Concern], coverage: Coverage | None,
+              ctx: TwinContext | None = None) -> list[Objection]:
+        """One audit round: silent misses (the diff) PLUS every claimed omission adjudicated
+        against ground truth. A justification defeats its objection only if it VALIDATES."""
+        from .salience import MUST_ADDRESS
+        objections = self.diff(concerns, coverage)
+        self.last_adjudications = {}
+        if coverage is None or ctx is None:
+            return objections
+        by_id = {c.id: c for c in concerns}
+        for cid, why in coverage.omitted.items():
+            c = by_id.get(cid)
+            if c is None or c.salience < MUST_ADDRESS:
+                continue
+            adj = adjudicate(c, why, ctx)
+            self.last_adjudications[cid] = adj
+            if adj.valid:
+                self.metrics["defeats"] += 1
+            else:
+                objections.append(Objection(c, _rejected_question(c, why, adj)))
+        return objections
+
+    def record(self, coverage: Coverage | None) -> None:
+        """Fold the turn's genuinely-covered concern ids into the mission history (what a later
+        'already addressed' justification is checked against). Omissions do NOT count."""
+        if coverage is not None:
+            self.history |= set(coverage.addressed)
+
+    def split_omissions(self, concerns: list[Concern], coverage: Coverage | None) -> tuple:
+        """(accepted, rejected) omission maps from the last audit's adjudications."""
+        if coverage is None:
+            return {}, {}
+        ids = {c.id for c in concerns}
+        accepted, rejected = {}, {}
+        for cid, why in coverage.omitted.items():
+            if cid not in ids:
+                continue
+            adj = self.last_adjudications.get(cid)
+            if adj is not None and not adj.valid:
+                rejected[cid] = adj.reason or why
+            else:
+                accepted[cid] = why
+        return accepted, rejected
+
+    @staticmethod
+    def note(objections: list[Objection]) -> str:
+        """One revision note carrying every objection (batched — one round trip, not N)."""
+        return " ".join(o.question for o in objections)
+
+    @staticmethod
+    def flag(move, objections: list[Objection]):
+        """Surviving objections become a visible, clearly-separated addendum on the move (the
+        ratified game-master surfacing: append). The Twin's voice is the concern STATEMENT —
+        grounded substrate text, not model prose."""
+        if not objections:
+            return move
+        worth = "; ".join(o.concern.statement for o in objections)
+        from ..contracts import Move
+        return Move(kind=move.kind, text=(move.text + f"\n(Also worth a look: {worth}.)").strip(),
+                    refs=move.refs, claims=move.claims)

gini/agent/twin/harness.py

@@ -0,0 +1,93 @@
+"""The reasoning eval harness (REASONING_2.0_DESIGN.md phase E).
+
+Replays a bank of GOLDEN TURNS — (world setup, a scripted model, a trigger, expectations) —
+through the real MissionAgent+Twin and aggregates the metrics the design names: addressed-rate
+of must-address concerns, coverage-silence rate, false-objection rate, flag rate. The harness
+tests the TWIN deterministically (scripted models make every run reproducible) and gives prompt/
+model changes a regression gate: run the same bank, compare the report.
+
+A `false objection` is an objection raised on a turn whose golden expectation says the model's
+coverage was complete/justified — i.e. the Twin nagged when it shouldn't have. With scripted
+models this is fully deterministic, so the false-objection rate here is a check on the TWIN's
+rules; against a live model (Mac-side) the same report measures the MODEL instead."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .salience import MUST_ADDRESS
+
+
+@dataclass
+class GoldenTurn:
+    """One replayable turn: `make_agent(llm)` builds the MissionAgent (world + twin inside);
+    `llm` is the scripted model; `trigger`/`utterance` wake it. Expectations are about the
+    TWIN's behavior, not prose."""
+    name: str
+    make_agent: object                  # callable(llm) -> MissionAgent (with a Twin)
+    llm: object                         # scripted callable(prompt) -> str
+    trigger: object = None
+    utterance: str = ""
+    expect_flags: bool = False          # should the turn end with a visible flag?
+    expect_objections: bool = False     # should the FIRST audit raise objections?
+    expect_clean: bool = False          # golden says coverage was complete/justified
+
+
+@dataclass
+class TurnOutcome:
+    name: str
+    ok: bool
+    flags: bool
+    objections: int
+    surviving: int
+    rounds: int
+    coverage_silent: bool
+    false_objection: bool
+    notes: str = ""
+
+
+@dataclass
+class HarnessReport:
+    outcomes: list = field(default_factory=list)
+
+    @property
+    def passed(self) -> bool:
+        return all(o.ok for o in self.outcomes)
+
+    def metrics(self) -> dict:
+        n = len(self.outcomes) or 1
+        addressed = [o for o in self.outcomes if not o.surviving]
+        return {
+            "turns": len(self.outcomes),
+            "pass_rate": sum(o.ok for o in self.outcomes) / n,
+            "addressed_rate": len(addressed) / n,      # must-address fully covered by turn end
+            "silence_rate": sum(o.coverage_silent for o in self.outcomes) / n,
+            "false_objection_rate": sum(o.false_objection for o in self.outcomes) / n,
+            "flag_rate": sum(o.flags for o in self.outcomes) / n,
+            "mean_rounds": sum(o.rounds for o in self.outcomes) / n,
+        }
+
+
+def replay(turns: list[GoldenTurn]) -> HarnessReport:
+    """Run every golden turn through the real orchestration; never raises — a broken turn is a
+    failed outcome with a note, so the CI report always renders."""
+    report = HarnessReport()
+    for t in turns:
+        try:
+            agent = t.make_agent(t.llm)
+            move = agent.turn(t.trigger, utterance=t.utterance)
+            res = agent.last_twin_result
+            flags = "Also worth a look" in (move.text or "")
+            objections = len(res.objections) if res else 0
+            surviving = len(res.surviving) if res else 0
+            silent = bool(res and res.coverage_silent)
+            rounds = res.rounds if res else 0
+            false_obj = bool(t.expect_clean and objections)
+            ok = (flags == t.expect_flags
+                  and (objections > 0) == t.expect_objections
+                  and not false_obj)
+            report.outcomes.append(TurnOutcome(
+                t.name, ok, flags, objections, surviving, rounds, silent, false_obj))
+        except Exception as e:                          # noqa: BLE001 — report, don't die
+            report.outcomes.append(TurnOutcome(
+                t.name, False, False, 0, 0, 0, False, False, notes=f"error: {e}"))
+    return report