adopt-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{adopt_cli-0.3.0 → adopt_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: adopt-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: The adopt command surface: config resolution, JSON mode, exit codes.
 Project-URL: Homepage, https://github.com/onboardux/onboard-core
 Project-URL: Source, https://github.com/onboardux/onboard-core
@@ -9,14 +9,20 @@ Author: The Adopt Authors
 License-Expression: Apache-2.0
 Requires-Python: >=3.12
 Requires-Dist: adopt-agent
+Requires-Dist: adopt-ask
 Requires-Dist: adopt-const
 Requires-Dist: adopt-coverage
 Requires-Dist: adopt-detect
 Requires-Dist: adopt-export
 Requires-Dist: adopt-freshness
+Requires-Dist: adopt-handover
 Requires-Dist: adopt-identity
+Requires-Dist: adopt-knowledge
+Requires-Dist: adopt-map
+Requires-Dist: adopt-model
 Requires-Dist: adopt-obs
 Requires-Dist: adopt-policy
+Requires-Dist: adopt-probe
 Requires-Dist: adopt-scope
 Requires-Dist: adopt-store
 Requires-Dist: click<9,>=8

{adopt_cli-0.3.0 → adopt_cli-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "adopt-cli"
-version = "0.3.0"
+version = "0.4.0"
 description = "The adopt command surface: config resolution, JSON mode, exit codes."
 requires-python = ">=3.12"
 license = "Apache-2.0"
@@ -12,14 +12,34 @@ authors = [{ name = "The Adopt Authors" }]
 # `adopt_cli` (CR-36) -- sees nothing new.
 dependencies = [
     "adopt-agent",
+    # Build 3. `commands/ask.py` imports it inside the command body, but the
+    # `first-party-deps` gate is about what the distribution needs installed, not
+    # about when the import runs: `pip install adopt-cli` must always yield a
+    # working `adopt ask`.
+    "adopt-ask",
     "adopt-const",
     "adopt-coverage",
     "adopt-detect",
     "adopt-export",
     "adopt-freshness",
+    # Build 4. `commands/pack.py` imports it inside the command body; the
+    # `first-party-deps` gate is about what the distribution needs installed,
+    # so `pip install adopt-cli` must always yield a working `adopt pack`.
+    "adopt-handover",
     "adopt-identity",
+    "adopt-knowledge",
+    "adopt-map",
+    # `adopt_model._enums` is imported directly by `commands/init.py` and
+    # `commands/boundary.py`. It arrived transitively through `adopt-store` until
+    # someone installed a subset that did not include it, which is why an
+    # undeclared dependency is a defect even while it happens to resolve.
+    "adopt-model",
     "adopt-obs",
     "adopt-policy",
+    # Build 5. `commands/probe.py` imports it inside the command body; the
+    # `first-party-deps` gate is about what the distribution needs installed,
+    # so `pip install adopt-cli` must always yield a working `adopt probe run`.
+    "adopt-probe",
     "adopt-scope",
     "adopt-store",
     "typer>=0.12,<1",

adopt_cli-0.4.0/src/adopt_cli/_build_info.py

@@ -0,0 +1,6 @@
+"""Generated by scripts/embed_build_info.py; do not edit in a release build."""
+
+from typing import Final
+
+SBOM_SHA256: Final[str | None] = '86636f02cad8578ffdc6c4b39fe311c0a8191cafd5fcb323ddb732447dc6b0c8'
+BUILD_ID: Final[str | None] = 'github:onboardux/onboard-core:34144382673:1:a1b32208f0a296bc708e283d860023ce7fdf4609'

adopt_cli-0.4.0/src/adopt_cli/commands/_ask_support.py

@@ -0,0 +1,311 @@
+"""The ask pipeline, in one place, so `adopt ask` and `adopt serve` cannot diverge.
+
+v6.1 says `adopt serve` "exposes the same paths on loopback". *Same* is doing
+real work in that sentence: two implementations of the ask pipeline would be two
+places the freshness check could be skipped, two boundary guards to keep in step
+and two answers to one question depending on which door you came through. So the
+composition root moved here when serve arrived, and both verbs call
+`answer_question`. The payload-parity test asserts what this arrangement makes
+structurally true.
+
+**The order below is the contract**, not an implementation detail:
+
+    refresh the derived index -> retrieve candidates -> resolve freshness for
+    every one -> compose -> guard against the boundary -> log/escalate -> render
+
+`compose` accepts only candidates already paired with a resolution, so the third
+step cannot be skipped by editing this file: the worst a future edit can do is
+fail to type-check. That is critical semantic invariant #5, and
+`adopt_ask.branch` records why it is a type rather than a check.
+
+**The store is opened by the caller**, because the two callers want different
+lifetimes -- one command, versus one request on a server that must not hold a
+connection across threads.
+
+**Build 7 gives escalation a second destination.** With a control plane
+configured, a consented escalation is posted to
+`POST /v1/systems/{id}/escalations` and opened in the tenant's canon, where the
+owner is resolved and the draft is routed; with none, it is written to the local
+store exactly as Build 3 wrote it. **The consent decision is unchanged and
+happens first** -- `consented()` still decides whether the text may be stored at
+all, and only then does the destination question arise. Reversing those two
+would make a network configuration able to change what a human agreed to.
+
+**Answering is never routed.** Only the escalation is: reading is what a replica
+is for, so `adopt ask` on an operated system answers from the local store at
+local latency and reaches the plane only when a question turns into work
+somebody else has to do.
+
+**Synthesis is the last step and changes nothing but the rendering.** It runs
+only when an adapter is configured, only over passages the branch already
+approved, and only if `ground` accepts what came back (invariant #7). The
+`--json` payload is deliberately identical either way except for one added
+`synthesis` block: a caller that scripts on `branch` and `citations` must not
+see a different shape because somebody set `ADOPT_ADAPTER` -- that would make
+the no-model mode a different product rather than a complete one (R3).
+"""
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from adopt_cli.store_option import configured_question_log, configured_search
+from adopt_obs import Clock, SystemClock
+
+__all__ = ["AskOutcome", "answer_question"]
+
+#: The config key passive logging reads. Named once so the registry entry and
+#: the read have exactly one spelling between them.
+LOG_QUESTIONS_KEY = "ADOPT_ASK_LOG_QUESTIONS"
+
+
+@dataclass(frozen=True, slots=True)
+class AskOutcome:
+    """One answered question: the machine payload, the human text, the branch."""
+
+    payload: dict[str, Any]
+    human: str
+    branch: str
+    escalation_id: str | None
+
+
+def answer_question(
+    handle: Any,
+    question: str,
+    *,
+    scope: str | None = None,
+    reindex: bool = False,
+    escalate_flag: bool = False,
+    interactive: bool = False,
+    confirm: Callable[[str], bool] | None = None,
+    resolved_config: Mapping[str, str | None] | None = None,
+    synthesize: bool = True,
+) -> AskOutcome:
+    """Answer `question` against the open store `handle`.
+
+    Args:
+        handle: An open, writable store handle. Writable because answering may
+            rebuild the retrieval index in the annex beside it -- answering
+            itself writes no canon, and `escalate_flag` is the only thing here
+            that does.
+        question: The question, verbatim.
+        scope: `firm/engagement/system/environment`, or `None` for the store's.
+        reindex: Rebuild the index even if its stamp says it is current.
+        escalate_flag: The `--escalate` flag, or the request's `escalate` field.
+            **The action is the consent** (F2), so this alone records the text.
+        interactive: Whether a human can answer a prompt. `False` for `--json`
+            and for **every** serve request, because an HTTP client is not a
+            person and a server that prompted would hang holding a socket.
+        confirm: How to ask, injected. `None` in every non-interactive context.
+        resolved_config: Config key -> value, for the passive-logging switch.
+            Injected so a test can drive the key without the environment.
+        synthesize: Whether to attempt the optional synthesis pass. `True` means
+            *try*, not *require*: with no adapter configured it is a no-op and
+            the extractive answer serves, which is the complete no-model mode
+            (R3). Passed `False` by tests that assert the extractive path.
+
+    Returns:
+        The `--json` payload, the human rendering, and the branch.
+
+    Raises:
+        AdoptError: ``ASK_OUTSIDE_BOUNDARY`` when the declared boundary refuses
+            the answer, or none is declared; ``ESCALATION_NOT_FOUND`` when a
+            consented escalation has no system to attach to.
+    """
+    from adopt_ask import compose, guard, json_payload, render, retrieve
+    from adopt_ask.branch import Resolved
+    from adopt_ask.escalate import consented, escalate, may_escalate
+    from adopt_ask.questionlog import log_question, should_log
+    from adopt_ask.synthesis import SYNTHESIS_PROMPT_REF, render_with
+
+    from adopt_cli.commands._map_support import resolve_scope
+    from adopt_cli.config import resolve_all
+    from adopt_detect import BoundaryView
+    from adopt_freshness import resolve_freshness
+    from adopt_obs import AdoptError, ErrorCode
+
+    resolved_scope = resolve_scope(handle, scope)
+    clock: Clock = handle.clock if handle.clock is not None else SystemClock()
+
+    with configured_search(handle, clock=clock) as search:
+        search.refresh(force=reindex)
+        candidates = retrieve(search, question)
+        verified = search.verified_in_store(
+            [candidate.passage.revision_id for candidate in candidates]
+        )
+
+    freshness_records = handle.freshness_records()
+    resolved = tuple(
+        Resolved(
+            candidate=candidate,
+            freshness=resolve_freshness(freshness_records, candidate.passage.item_id, clock=clock),
+        )
+        for candidate in candidates
+    )
+
+    answer = compose(resolved, verified, question)
+
+    system = resolved_scope.system
+    environment = resolved_scope.environment
+    row = (
+        None
+        if system is None
+        else handle.boundary().current(
+            system_id=system.id,
+            environment_id=None if environment is None else environment.id,
+        )
+    )
+    guard(
+        answer,
+        None if row is None else BoundaryView.of(row, archetype=None),
+        scope=resolved_scope,
+        occurred_at=clock.now(),
+    )
+
+    # Passive logging is asked **before** escalation and is entirely separate
+    # from it: `--escalate` is consent to store one question, and the config key
+    # is an operator's standing decision to store all of them. Reading either
+    # from the other would collapse F2's two halves into one.
+    config = (
+        resolved_config
+        if resolved_config is not None
+        else {item.key: item.value for item in resolve_all()}
+    )
+    if should_log(config, key=LOG_QUESTIONS_KEY):
+        with configured_question_log(handle) as question_log:
+            log_question(
+                question_log, answer, scope_ref=resolved_scope.path(), asked_at=clock.now()
+            )
+
+    escalation_id: str | None = None
+    routed_to_plane = False
+    if consented(answer, escalate_flag=escalate_flag, interactive=interactive, confirm=confirm):
+        if system is None:
+            raise AdoptError(
+                ErrorCode.ESCALATION_NOT_FOUND,
+                message=f"the scope {resolved_scope.path()!r} names no system, so there is "
+                "nothing to open a question against",
+                hint="Pass --scope firm/engagement/system/environment, or open a store whose "
+                "default scope resolves to a system.",
+            )
+        from adopt_cli.commands._remote_support import configured_remote
+
+        remote = configured_remote(config)
+        if remote is None:
+            # **The one capture this module performs, and the one write here that
+            # is canon.** `ask` and `serve` open the store writable with the
+            # guard opted out, because answering rebuilds the retrieval index in
+            # the annex and a replica exists to be asked questions. An
+            # escalation is different: it lands an `escalation` row that the
+            # next `adopt pull` replaces wholesale, so the question a human
+            # recorded would be gone with no trace. The check is here rather
+            # than at the open because which branch is taken is decided here --
+            # a configured remote routes to the plane and writes nothing local.
+            from adopt_cli.replica import refuse_write_to_replica
+
+            refuse_write_to_replica(handle.backend.path, verb="ask --escalate")
+            escalation_id = escalate(handle.governance(), answer, system_id=system.id)
+        else:
+            escalation_id = _escalate_remotely(remote, question)
+            routed_to_plane = True
+
+    payload = dict(json_payload(answer))
+    human = render(answer)
+
+    synthesis = _synthesize(answer, question=question, config=config) if synthesize else None
+    if synthesis is not None:
+        payload["synthesis"] = {
+            "answer_md": synthesis.answer_md,
+            "cited_revision_ids": list(synthesis.cited_revision_ids),
+            "prompt_ref": SYNTHESIS_PROMPT_REF,
+        }
+        human = render_with(answer, synthesis)
+    if escalation_id is not None:
+        payload["escalation_id"] = escalation_id
+        payload["routed_to_plane"] = routed_to_plane
+        where = "on the control plane" if routed_to_plane else "in this store"
+        human += f"\n\nRecorded as open question {escalation_id} {where}."
+        human += f'\nAnswer it with: adopt answer {escalation_id} --text "..."'
+        if routed_to_plane:
+            human += "\nIts owner has been routed a draft reply."
+    elif may_escalate(answer) and not escalate_flag:
+        human += "\n\nRecord it as an open question with `--escalate`."
+
+    return AskOutcome(
+        payload=payload, human=human, branch=answer.branch, escalation_id=escalation_id
+    )
+
+
+def _synthesize(answer: Any, *, question: str, config: Mapping[str, str | None]) -> Any:
+    """One optional model call. `None` for every reason not to have made it.
+
+    **Every failure here is silent and returns `None`**, because the answer is
+    already complete without it: no adapter configured, offline refused, budget
+    exhausted, provider error, ungrounded output. Turning any of those into a
+    visible failure would make an optional improvement a required dependency,
+    which is exactly what R3's no-model mode forbids.
+
+    The idempotency key is the question plus the cited set, so re-asking an
+    unchanged question over unchanged knowledge replays the recorded run instead
+    of paying for it again (PRD F13.5) -- and a store whose knowledge has moved
+    on asks a genuinely new question.
+    """
+    import hashlib
+
+    from adopt_ask.synthesis import synthesize as run_synthesis
+
+    from adopt_agent import Runner
+    from adopt_cli.commands.agent import adapter_settings, prompts_root
+    from adopt_cli.store_option import configured_annex
+    from adopt_obs import AdoptError
+
+    if not answer.citations:
+        return None
+    offline, adapter_id, model, endpoint = adapter_settings()
+    if not adapter_id:
+        # No adapter is the ordinary case and is not a failure: the extractive
+        # answer is the product (`04` §3), not a fallback from one.
+        return None
+
+    material = "\0".join([question, *(c.revision_id for c in answer.citations)])
+    key = f"ask-001:{hashlib.sha256(material.encode('utf-8')).hexdigest()}"
+
+    try:
+        with configured_annex() as annex:
+            runner = Runner(
+                annex=annex,
+                scope_ref=question,
+                skills_root=prompts_root(),
+                offline=offline,
+                adapter_id=adapter_id,
+                model=model,
+                endpoint=endpoint,
+            )
+            return run_synthesis(runner, answer, idempotency_key=key)
+    except AdoptError:
+        return None
+
+
+def _escalate_remotely(remote: Any, question: str) -> str | None:
+    """Open the question on the configured plane. Returns its id.
+
+    **The plane runs the same `adopt_ask` code on its own side**, so the branch
+    it decides and the branch decided here agree -- and the id that comes back is
+    the plane's, which is the one `adopt answer` will confirm against. Returning
+    a local id would be worse than returning none: it would name a row nobody
+    else can see, in a command whose whole point is that somebody else acts on it.
+
+    `None` comes back only when the plane answered `escalated: false`, meaning
+    *it* could answer the question. That is a real outcome rather than a failure:
+    the replica is behind the plane's canon, which is exactly what `adopt pull`
+    is for.
+    """
+    from adopt_cli.remote import post_json
+
+    response = post_json(
+        remote,
+        f"/v1/systems/{remote.system_id}/escalations",
+        {"question": question},
+    )
+    escalation_id = response.get("escalation_id")
+    return str(escalation_id) if isinstance(escalation_id, str) else None

adopt_cli-0.4.0/src/adopt_cli/commands/_ci_sense_probes.py

@@ -0,0 +1,229 @@
+"""The probe half of `adopt ci-sense`: run them here, decide nothing.
+
+**Sensing executes where access exists** (v6.1 §6 Build 8 F4). A probe reaches
+a client's own deployment, so the CI is where it can be run at all for every
+system behind a network the plane cannot enter. This module runs the probes the
+local replica declares, through `adopt_probe.runner` -- the one module in the
+programme permitted to open a probe socket -- and renders what they observed
+into the sense payload.
+
+**Nothing is stored and nothing is compared.** `execute_probe` is called with
+`records=None` and with a sink that carries the heartbeat instead of writing it,
+so no `probe_run`, no `probe_observation` and no `sensor_heartbeat` lands in the
+replica: `adopt ci-sense` writes nothing locally, because after activation the
+plane is the sole writer of an operated system's canon (R9). The comparison is
+the plane's too, against **its** baseline, for `_ci_sense_support`'s reason -- a
+replica is only as fresh as its last `adopt pull`, and comparing against a stale
+baseline would report drift that a current baseline explains.
+
+**What travels is what a comparison needs and nothing more.** The step outputs
+travel because Build 5's `compare_run` is a text comparison and cannot be done
+on digests; they are the client's *own system's* responses, already canon in
+their store, and already redacted of every declared secret by the runner before
+this module can see them. No line of the repository travels here any more than
+it does in the artifact half.
+
+**The revision id travels with every result, and it is load-bearing.** A run of
+revision B compared against a baseline of revision A is the *question* changing,
+not the system -- so the plane reports `probe_changed` and produces no change
+event at all. Without the revision id on the wire that distinction is
+unreachable, and every probe edit would arrive as a client incident.
+"""
+
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = ["ProbeSection", "run_payload_probes"]
+
+
+@dataclass(slots=True)
+class ProbeSection:
+    """What the probe half of one ci-sense run observed, ready to be rendered.
+
+    **Every field that is not a result is a statement about what was not looked
+    at**, which is `ProbeDelta`'s rule and its reason: a run that examined
+    nothing must not read as a clean one. `reason` says why the half did not run
+    at all; `skipped` says which probes had no revision to execute.
+    """
+
+    ran: bool = False
+    reason: str | None = None
+    results: list[dict[str, Any]] = field(default_factory=list)
+    skipped: list[dict[str, str]] = field(default_factory=list)
+    heartbeats: list[dict[str, Any]] = field(default_factory=list)
+
+    def payload(self) -> dict[str, Any]:
+        """The `probes` object as the payload carries it.
+
+        Sorted by probe name for `build_payload`'s reason: the framing fixture
+        is compared byte for byte across two repositories, and a section that
+        reordered per run could not be pinned.
+        """
+        return {
+            "ran": self.ran,
+            "reason": self.reason,
+            "results": sorted(self.results, key=lambda row: str(row["probe"])),
+            "skipped": sorted(self.skipped, key=lambda row: row["probe"]),
+            "heartbeats": sorted(self.heartbeats, key=lambda row: str(row["probe"])),
+        }
+
+    @property
+    def drifted_candidates(self) -> int:
+        """How many probes completed and could therefore be compared.
+
+        Named *candidates* rather than *drifted* deliberately: this side does not
+        compare anything, so it cannot know what drifted. The count exists for
+        the CI log line, where "ran 3, 3 comparable" and "ran 3, 0 comparable"
+        are very different mornings.
+        """
+        return sum(1 for row in self.results if row["outcome"] in ("success", "diff"))
+
+
+def run_payload_probes(handle: Any, scope: Any, *, allow_network: bool = False) -> ProbeSection:
+    """Execute the probes this scope declares and render what they observed.
+
+    Args:
+        handle: The read-only store handle ci-sense already opened. Used for
+            **reads only** -- the definitions and their active revisions.
+        scope: The resolved four-level scope.
+        allow_network: Permits the model adapter for a probe's `prompt` steps.
+            An `http` step needs no such flag; the host allow-list is the
+            invariant there and it is enforced inside the runner.
+
+    Returns:
+        A `ProbeSection`. `ran=False` with a reason when there is nothing to run,
+        which is not the same answer as "ran and found nothing".
+    """
+    import os
+    from contextlib import ExitStack
+
+    from adopt_probe import execute_probe, parse_probe
+
+    from adopt_cli.commands._probe_support import (
+        active_revision,
+        probes_in_scope,
+    )
+
+    definitions = probes_in_scope(handle, scope)
+    if not definitions:
+        return ProbeSection(ran=False, reason="no probes are defined in this scope")
+
+    section = ProbeSection(ran=True)
+    pairs: list[tuple[Any, Any, Any]] = []
+    for probe in definitions:
+        revision = active_revision(handle, probe)
+        if revision is None:
+            section.skipped.append({"probe": probe.name, "reason": "no revision"})
+            continue
+        if revision.status != "active":
+            section.skipped.append(
+                {"probe": probe.name, "reason": f"revision is {revision.status}"}
+            )
+            continue
+        pairs.append((probe, revision, parse_probe(revision.capability_manifest)))
+
+    if not pairs:
+        section.ran = False
+        section.reason = "no probe in this scope has an active revision"
+        return section
+
+    # The annex stays open for the whole set and closes with the stack, exactly
+    # as `execute_in_scope` holds it -- a `prompt` step's model call is metered
+    # through the one seam, and opening an annex per probe would make each run's
+    # budget its own.
+    with ExitStack() as stack:
+        agent = _agent_for([spec for _, _, spec in pairs], stack, allow_network=allow_network)
+        for probe, revision, spec in pairs:
+            sink = _CarriedHeartbeat()
+            report = execute_probe(
+                spec,
+                probe_definition_id=probe.id,
+                probe_definition_revision_id=revision.id,
+                # **`records=None`, and that is the verb's whole discipline.** A
+                # recorded run here would be a canon write from a caller that is
+                # not the writer (R9), so nothing lands in the replica: the run,
+                # its observations and its heartbeat all travel instead.
+                records=None,
+                environ=os.environ,
+                agent=agent,
+                sensor=sink,
+            )
+            section.results.append(_result(probe, revision, spec, report))
+            section.heartbeats.append(sink.payload(probe.name))
+
+    return section
+
+
+def _agent_for(specs: Sequence[Any], stack: Any, *, allow_network: bool) -> Any:
+    """The model seam, opened only when a probe actually has a `prompt` step.
+
+    `_probe_support._agent_for` unchanged and by import, rather than a second
+    construction of the same runner: the adapter resolution, the annex lifetime
+    and the offline refusal are all decisions that must be identical to the
+    local loop's, and two spellings of them would differ the first time one was
+    edited.
+    """
+    from adopt_cli.commands._probe_support import _agent_for as build_agent
+
+    return build_agent(list(specs), stack, allow_network=allow_network, audience="probe")
+
+
+def _result(probe: Any, revision: Any, spec: Any, report: Any) -> dict[str, Any]:
+    """One probe's run, as the payload carries it.
+
+    `exercises` travels because it is **the only probe -> identity link** (B5's
+    `conflict.py` reading, which Build 6's refresh already inherits): the plane
+    turns a drift into a change event about the referents the probe declares it
+    exercises, and a payload without them would be a finding about nothing.
+
+    `outputs` and `fingerprints` are parallel to `steps`, in step order, because
+    that is the order `compare_run` pairs them against the baseline in. Ordered
+    by the loop that ran them rather than sorted -- step 2 compared against step
+    0's baseline is a comparison of two unrelated things that would report drift
+    with complete confidence.
+    """
+    return {
+        "probe": probe.name,
+        "probe_definition_id": probe.id,
+        "probe_definition_revision_id": revision.id,
+        "outcome": report.outcome,
+        "exercises": list(spec.exercises),
+        "outputs": [step.output for step in report.steps],
+        "fingerprints": [step.fingerprint for step in report.steps],
+        # Already redacted of every declared secret by the runner -- `redact` is
+        # applied to a refusal before it reaches the report, because a refusal
+        # message is the one place a bad request's interpolated value would
+        # otherwise appear.
+        "refusal": report.refusal,
+    }
+
+
+class _CarriedHeartbeat:
+    """A `SensorSink` that carries the fact instead of writing it.
+
+    v6.1 §6 B5 requires probe runs to *"emit per-run sensor-health facts locally
+    so Builds 6/8 treat probes as sensors without rework"*. In CI there is no
+    local sensor worth writing to -- the replica's health is nobody's oracle,
+    and a heartbeat there would leave the plane's sensor (the row
+    `resolve_freshness` actually reads) hearing nothing while the scope looked
+    healthy. So the fact travels.
+
+    **A sink rather than a mapping of outcome to health**, which was the first
+    spelling here. The runner already owns that mapping and applies it before
+    calling this; re-deriving it on this side would be a second copy of a rule
+    whose two halves would differ the first time either was edited -- and the
+    symptom would be a scope whose sensor health disagreed with the run that
+    produced it.
+    """
+
+    def __init__(self) -> None:
+        self.outcome: str | None = None
+        self.detail: str | None = None
+
+    def heartbeat(self, *, outcome: str, detail: str | None = None) -> None:
+        self.outcome = outcome
+        self.detail = detail
+
+    def payload(self, probe_name: str) -> dict[str, Any]:
+        return {"probe": probe_name, "outcome": self.outcome, "detail": self.detail}