@senpi/runtime 3.0.129 → 3.0.131

package/dist/scanners/external/scaffold/scaffold.py

@@ -3,7 +3,8 @@
 run_scaffold(...) loads the author's entrypoint, finds and validates scan(),
 builds the ScanContext, then drives the interval loop: time-box per tick, graceful
 stop on SIGTERM/SIGINT, parent-death detection via ppid, transactional state via
-ctx.state, candidates to sink.
+ctx.state, candidates to sink. Each tick mints one id, handed to the sink with the
+tick's candidates and carried on every error the tick reports.
 
 `path` is a scaffold concern only — it is put on sys.path before import and never
 passed to scan(). scan() is called as scan(inputs, ctx) — 2-arg, sync, returning a
@@ -42,6 +43,8 @@ from .loop_primitives import (
     log_event,
 )
 from .state_manager import StateManager
+from .tick_facts import build_tick_facts, count_changed, project_state_row
+from .ulid import new_ulid
 
 
 def _read_call_timeout_seconds(senpi_mcp_mod: Any) -> float:
@@ -103,6 +106,28 @@ def _build_senpi_mcp() -> Any:
     )
 
 
+def _accepts_kwarg(fn: Any, name: str) -> bool:
+    """Whether `fn` takes `name` as a keyword argument.
+
+    Read from the signature, once, rather than calling with the keyword and retrying on
+    TypeError: a sink that raises TypeError from its own body would then be called twice and
+    deliver the same candidates twice. A callable whose signature cannot be read keeps the
+    narrower call it has today.
+    """
+    try:
+        params = list(inspect.signature(fn).parameters.values())
+    except (TypeError, ValueError):
+        return False
+    return any(
+        p.kind == inspect.Parameter.VAR_KEYWORD
+        or (
+            p.name == name
+            and p.kind in (inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.KEYWORD_ONLY)
+        )
+        for p in params
+    )
+
+
 def _call_scan(scan: Callable, inputs: dict, ctx: Any):
     """Call scan(inputs, ctx) — the v2 2-arg contract.
 
@@ -148,7 +173,8 @@ def run_scaffold(
         state_history_max_count:
                      Bound on the persisted state series. 0/unset = history disabled
                      (ctx.state.append raises).
-        sink:        Callable(candidates) invoked after each clean tick. Default no-op.
+        sink:        Callable(candidates, tick_id=None) invoked after each clean tick. A sink
+                     that takes candidates only is called with candidates only. Default no-op.
         max_ticks:   Stop after this many ticks. None = unbounded. Used by tests and by a
                      validation run, which forces exactly one tick.
         senpi_mcp:   Data client to hand to scan(). Default: built from the launch environment.
@@ -235,6 +261,24 @@ def run_scaffold(
     # The MCP boundary's per-tick failure tally, when the client exposes one. Duck-typed:
     # an injected stub without it (a validation run) simply never reclassifies a tick.
     mcp_tally = getattr(senpi_mcp, "tick_errors", None)
+    sink_takes_tick_id = sink is not None and _accepts_kwarg(sink, "tick_id")
+    # The per-tick observability facts ride the POST the sink already makes. A sink that
+    # predates them is called exactly as before, so an older sink is not broken by them.
+    sink_takes_tick = sink is not None and _accepts_kwarg(sink, "tick")
+    post_error_takes_tick = (
+        sink is not None
+        and hasattr(sink, "post_error")
+        and _accepts_kwarg(sink.post_error, "tick")
+    )
+
+    # Consecutive ticks that produced no candidate. 47 quiet ticks is information; the word
+    # "quiet" repeated 47 times is not, so the streak is counted here and sent as a number.
+    quiet_ticks = 0
+    # The previous tick's start, for the cadence lag. None on the first tick of a process:
+    # there is no gap to measure yet, and a 0 would claim the scanner was exactly on time.
+    prev_tick_started_at: Optional[float] = None
+    # The last projection reported, so `state_changed` says what MOVED rather than what exists.
+    prev_state_projection: Optional[dict] = None
 
     try:
         while not stop_event.is_set():
@@ -245,7 +289,18 @@ def run_scaffold(
                 break
 
             tick_count += 1
+            # One id per tick, minted before any of the tick's work so every candidate and every
+            # error it reports names the same tick.
+            tick_id = new_ulid()
             tick_started_at = time.time()
+            # Actual gap between tick starts, minus the cadence the scanner is configured for.
+            # A positive number is a scanner falling behind its own interval.
+            lag_ms = (
+                None
+                if prev_tick_started_at is None
+                else int(round((tick_started_at - prev_tick_started_at - interval) * 1000))
+            )
+            prev_tick_started_at = tick_started_at
             tick_status = "ok"
             tick_error = None
             candidates: list = []
@@ -269,10 +324,15 @@ def run_scaffold(
                         )
                         # Carried on the error record, not only in this log line: the sink is what
                         # a caller reads, and "malformed" without the reason is not actionable.
-                        tick_error = {"type": "malformed", "message": malformed_reason}
+                        tick_error = {
+                            "type": "malformed",
+                            "tick_id": tick_id,
+                            "message": malformed_reason,
+                        }
                         log_event(
                             "scaffold_tick_malformed",
                             tick=tick_count,
+                            tick_id=tick_id,
                             reason=malformed_reason,
                         )
                     else:
@@ -281,10 +341,11 @@ def run_scaffold(
                 except _TickTimeout as exc:
                     tick_status = "timeout"
                     candidates = []
-                    tick_error = {"type": "timeout", "message": str(exc)}
+                    tick_error = {"type": "timeout", "tick_id": tick_id, "message": str(exc)}
                     log_event(
                         "scaffold_tick_timeout",
                         tick=tick_count,
+                        tick_id=tick_id,
                         reason=str(exc),
                     )
                 except Exception as exc:  # noqa: BLE001 — author bug must not crash scaffold
@@ -292,12 +353,14 @@ def run_scaffold(
                     candidates = []
                     tick_error = {
                         "type": "error",
+                        "tick_id": tick_id,
                         "error_type": type(exc).__name__,
                         "message": str(exc),
                     }
                     log_event(
                         "scaffold_tick_error",
                         tick=tick_count,
+                        tick_id=tick_id,
                         error_type=type(exc).__name__,
                         error=str(exc),
                     )
@@ -317,15 +380,23 @@ def run_scaffold(
                 mcp_error_count, mcp_failure = _classify_mcp_errors(mcp_tally, candidates)
                 if tick_status == "ok" and mcp_failure is not None:
                     tick_status = "mcp_error"
-                    tick_error = mcp_failure
+                    # Stamped here, not in the classifier: every error record posted to
+                    # `/errors` names the tick it came from, and the classifier is tick-agnostic.
+                    tick_error = {**mcp_failure, "tick_id": tick_id}
                     log_event(
                         "scaffold_tick_mcp_error",
                         tick=tick_count,
+                        tick_id=tick_id,
                         error_type=mcp_failure["error_type"],
                         error_count=mcp_error_count,
                     )
 
+                # The quiet streak counts ticks, not words: a tick that produced a
+                # candidate ends the streak whatever its status.
+                quiet_ticks = 0 if candidates else quiet_ticks + 1
+
                 # --- Clean tick: commit ctx.state, deliver candidates ---
+                persist_error = None
                 if tick_status == "ok":
                     # Transactional commit. A failed persist RAISES (StateManager
                     # enforces it) and does NOT advance the committed snapshot — so
@@ -341,46 +412,100 @@ def run_scaffold(
                         log_event(
                             "scaffold_state_persist_failed",
                             tick=tick_count,
+                            tick_id=tick_id,
                             error_type=type(commit_exc).__name__,
                             error=str(commit_exc),
                         )
-                        if sink is not None and hasattr(sink, "post_error"):
-                            _post_error_safe(
-                                sink,
-                                {
-                                    "type": "state_persist_failed",
-                                    "tick": tick_count,
-                                    "message": (
-                                        "scanner state could not be persisted; "
-                                        "tick discarded, state not advanced"
-                                    ),
-                                },
-                                tick_count,
-                            )
+                        persist_error = {
+                            "type": "state_persist_failed",
+                            "tick": tick_count,
+                            "tick_id": tick_id,
+                            "message": (
+                                "scanner state could not be persisted; "
+                                "tick discarded, state not advanced"
+                            ),
+                        }
+                    commit_outcome = "committed" if committed else "persist_failed"
+                else:
+                    # Non-ok tick (error / timeout / malformed): roll back the
+                    # working buffer (discard the tick's mutations — state not
+                    # advanced) and report to /errors via the sink, when supported.
+                    ctx.state.rollback()
+                    committed = False
+                    commit_outcome = "rolled_back"
+
+                # Read AFTER the commit/rollback above, so this is always the last
+                # COMMITTED row — stale by one tick on a failed tick, which is exactly
+                # when the last state the scanner agreed on is worth seeing.
+                state_row = ctx.state.last()
+                state_projection = project_state_row(state_row)
+                state_fields = len(state_row) if isinstance(state_row, dict) else None
+                state_changed = (
+                    None
+                    if state_fields is None
+                    else count_changed(state_projection, prev_state_projection)
+                )
+                prev_state_projection = state_projection if state_fields is not None else None
+
+                tick_facts = build_tick_facts(
+                    tick_id=tick_id,
+                    status=tick_status,
+                    candidate_count=len(candidates),
+                    duration_ms=duration_ms,
+                    commit=commit_outcome,
+                    quiet_ticks=quiet_ticks,
+                    lag_ms=lag_ms,
+                    mcp_snapshot=mcp_tally.snapshot() if mcp_tally is not None else None,
+                    call_snapshot=(
+                        mcp_tally.call_snapshot()
+                        if mcp_tally is not None and hasattr(mcp_tally, "call_snapshot")
+                        else None
+                    ),
+                    state_row=state_row,
+                    state_fields=state_fields,
+                    state_changed=state_changed,
+                )
+
+                # Exactly one POST carries this tick's facts: /signals on a clean tick,
+                # /errors on any tick that failed. Both already happen every tick, so the
+                # facts add no request of their own.
+                sink_can_post_error = sink is not None and hasattr(sink, "post_error")
+                facts_for_error = tick_facts if post_error_takes_tick else None
+                if tick_status == "ok":
+                    if persist_error is not None and sink_can_post_error:
+                        _post_error_safe(
+                            sink, persist_error, tick_count, tick_id, facts_for_error
+                        )
 
                     if committed and sink is not None:
                         try:
-                            sink(candidates)
+                            kwargs = {}
+                            if sink_takes_tick_id:
+                                kwargs["tick_id"] = tick_id
+                            if sink_takes_tick:
+                                kwargs["tick"] = tick_facts
+                            sink(candidates, **kwargs)
                         except Exception as sink_exc:  # noqa: BLE001
                             log_event(
                                 "scaffold_sink_error",
                                 tick=tick_count,
+                                tick_id=tick_id,
                                 error_type=type(sink_exc).__name__,
                                 error=str(sink_exc),
                             )
-                else:
-                    # Non-ok tick (error / timeout / malformed): roll back the
-                    # working buffer (discard the tick's mutations — state not
-                    # advanced) and report to /errors via the sink, when supported.
-                    ctx.state.rollback()
-                    if sink is not None and hasattr(sink, "post_error"):
-                        _post_error_safe(
-                            sink, tick_error or {"type": tick_status}, tick_count
-                        )
+                elif sink_can_post_error:
+                    _post_error_safe(
+                        sink,
+                        tick_error or {"type": tick_status, "tick_id": tick_id},
+                        tick_count,
+                        tick_id,
+                        facts_for_error,
+                    )
 
                 log_event(
                     "scaffold_tick_finished",
                     tick=tick_count,
+                    tick_id=tick_id,
                     status=tick_status,
                     duration_ms=duration_ms,
                     candidate_count=len(candidates),
@@ -402,6 +527,7 @@ def run_scaffold(
                 log_event(
                     "scaffold_tick_timeout_late",
                     tick=tick_count,
+                    tick_id=tick_id,
                     reason=str(late_exc),
                 )
 
@@ -454,14 +580,29 @@ def _classify_mcp_errors(mcp_tally: Any, candidates: list) -> tuple[int, Optiona
     }
 
 
-def _post_error_safe(sink: Any, error: dict, tick_count: int) -> None:
-    """Call sink.post_error(error), swallowing/logging any failure."""
+def _post_error_safe(
+    sink: Any,
+    error: dict,
+    tick_count: int,
+    tick_id: str,
+    tick: Optional[dict] = None,
+) -> None:
+    """Call sink.post_error(error), swallowing/logging any failure.
+
+    `tick` is passed only when the sink's signature accepts it — the caller checks
+    once at launch, so a sink that predates the per-tick facts keeps its one-argument
+    call rather than being handed a keyword it would raise on.
+    """
     try:
-        sink.post_error(error)
+        if tick is None:
+            sink.post_error(error)
+        else:
+            sink.post_error(error, tick=tick)
     except Exception as perr:  # noqa: BLE001
         log_event(
             "scaffold_post_error_failed",
             tick=tick_count,
+            tick_id=tick_id,
             error_type=type(perr).__name__,
             error=str(perr),
         )

package/dist/scanners/external/scaffold/senpi_mcp.py

@@ -404,28 +404,155 @@ def _cast_market_numerics(name: str, payload: Any, args: Optional[dict] = None)
     return payload
 
 
+# Per-call detail kept for one tick. The counts and the total duration below are
+# whole however many calls a tick makes; only this per-call list is cut, because
+# a scanner that calls a tool in a loop would otherwise grow an unbounded list
+# inside a process that must not grow.
+MAX_TICK_CALL_RECORDS = 64
+
+# Per-argument bounds for a recorded call. Arguments are author-supplied and
+# reach a watching operator's screen, so what is kept is scalars only, capped.
+MAX_TICK_CALL_ARG_KEYS = 16
+MAX_TICK_CALL_ARG_CHARS = 1024
+
+# A list of scalars is kept as well, because the assets a scanner priced arrive
+# in that shape and are the most useful argument on the event. Both bounds apply
+# to one list: at most this many elements, and no more rendered characters than a
+# single string argument is allowed. MAX_TICK_CALL_ARG_CHARS is shared rather than
+# doubled so one long list cannot cost more frame than one long string.
+MAX_TICK_CALL_ARG_LIST_ITEMS = 16
+
+
+def _is_arg_scalar(value: Any) -> bool:
+    """Whether one value is a scalar this event carries: str, bool, or a finite number.
+
+    The int branch covers bool, which subclasses it, and comes before the float
+    branch on purpose: an int cannot be infinite, and `math.isfinite` on one too
+    large to convert to a float raises OverflowError.
+    """
+    if isinstance(value, int):
+        return True
+    if isinstance(value, float):
+        return math.isfinite(value)
+    return isinstance(value, str)
+
+
+def _record_arg_list(value: list) -> Optional[list]:
+    """One list argument, bounded — or None when the list is not carried at all.
+
+    A single non-scalar element rejects the whole list. Filtering it out instead
+    would let an author's unbounded dict decide how much of a nested payload gets
+    rendered, which is the input this event refuses to take.
+
+    Elements dropped by either bound are replaced by a trailing count, so a
+    shortened list reads as shortened rather than as a shorter call. The marker is
+    a plain string element because the consumer expands dictionary indexes and
+    scalars, and a nested object would not survive it.
+    """
+    if not all(_is_arg_scalar(item) for item in value):
+        return None
+    kept: list = []
+    chars = 0
+    for item in value[:MAX_TICK_CALL_ARG_LIST_ITEMS]:
+        rendered = len(item) if isinstance(item, str) else len(str(item))
+        if chars + rendered > MAX_TICK_CALL_ARG_CHARS:
+            break
+        chars += rendered
+        kept.append(item)
+    if len(kept) < len(value):
+        kept.append(f"+{len(value) - len(kept)} more")
+    return kept
+
+
+def _record_args(args: Optional[dict]) -> dict:
+    """The scalar arguments of one call, bounded — never the caller's own dict.
+
+    A reference would let authored code mutate what the tally already recorded,
+    and a deep copy would pay for a payload the wire is going to drop anyway. A
+    kept list is a new list for the same reason.
+    """
+    if not isinstance(args, dict):
+        return {}
+    kept: dict = {}
+    for key in list(args.keys())[:MAX_TICK_CALL_ARG_KEYS]:
+        if not isinstance(key, str):
+            continue
+        value = args[key]
+        if isinstance(value, str):
+            kept[key] = value[:MAX_TICK_CALL_ARG_CHARS]
+        elif _is_arg_scalar(value):
+            # The same gate the list path applies, and for a harder reason here: an
+            # `inf` compares equal to itself, so a self-equality check lets it
+            # through, and json.dumps then writes the bare `Infinity` token. That
+            # token is not JSON, and the tick facts ride one POST body — a
+            # JavaScript JSON.parse on it throws and every other fact on the tick
+            # is lost with the one argument.
+            kept[key] = value
+        elif isinstance(value, list):
+            # An empty list is kept. Absent means unmeasured on this event, and a
+            # scanner that passed no elements did measure something: it asked for
+            # nothing. Dropping it would report the argument as never supplied.
+            rendered_list = _record_arg_list(value)
+            if rendered_list is not None:
+                kept[key] = rendered_list
+    return kept
+
+
 class TickErrorTally:
-    """Per-tick count of MCP call failures, by error type.
+    """Per-tick record of what the MCP boundary did: every call, and every failure.
+
+    Two tallies, one object, because both are read at the same moment and reset
+    at the same moment.
+
+    FAILURES. Authored scan() code routinely catches the MCP exception and
+    returns [], so the exception alone never reaches the scaffold — the tick
+    would finish `ok` with zero candidates while the scanner is blind. The client
+    records every failure here as it re-raises; the scaffold resets the tally at
+    tick start and reads it at tick end to decide whether a candidate-less tick
+    was really ok.
+
+    CALLS. Every call is recorded, succeeded or failed, with the time it took.
+    Failures alone say what broke but not what the tick actually did or where its
+    time went — a tick with no failures and one 9-second call is a slow venue, and
+    nothing else on the box can tell an operator that.
 
-    Authored scan() code routinely catches the MCP exception and returns [], so
-    the exception alone never reaches the scaffold — the tick would finish `ok`
-    with zero candidates while the scanner is blind. The client records every
-    failure here as it re-raises; the scaffold resets the tally at tick start and
-    reads it at tick end to decide whether a candidate-less tick was really ok.
     Thread-safe because call_tool may be driven from author threads.
     """
 
     def __init__(self) -> None:
         self._by_type: dict[str, int] = {}
+        self._calls: list[dict] = []
+        self._call_count = 0
+        self._total_ms = 0.0
         self._lock = threading.Lock()
 
     def record(self, error_type: str) -> None:
         with self._lock:
             self._by_type[error_type] = self._by_type.get(error_type, 0) + 1
 
+    def record_call(
+        self,
+        tool: str,
+        elapsed_ms: float,
+        args: Optional[dict] = None,
+        error_type: Optional[str] = None,
+    ) -> None:
+        """Record one completed call. Called on the success path and the failure path alike."""
+        entry = {"tool": tool, "ms": elapsed_ms, "args": _record_args(args)}
+        if error_type is not None:
+            entry["error_type"] = error_type
+        with self._lock:
+            self._call_count += 1
+            self._total_ms += elapsed_ms
+            if len(self._calls) < MAX_TICK_CALL_RECORDS:
+                self._calls.append(entry)
+
     def reset(self) -> None:
         with self._lock:
             self._by_type = {}
+            self._calls = []
+            self._call_count = 0
+            self._total_ms = 0.0
 
     def snapshot(self) -> dict[str, Any]:
         """{count, dominant_error_type, by_type}; count 0 / None when clean.
@@ -440,6 +567,15 @@ class TickErrorTally:
         dominant = max(by_type, key=by_type.__getitem__) if by_type else None
         return {"count": count, "dominant_error_type": dominant, "by_type": by_type}
 
+    def call_snapshot(self) -> dict[str, Any]:
+        """{count, total_ms, calls}. `count` and `total_ms` are whole; `calls` may be cut."""
+        with self._lock:
+            return {
+                "count": self._call_count,
+                "total_ms": round(self._total_ms, 1),
+                "calls": [dict(call) for call in self._calls],
+            }
+
 
 # --------------------------------------------------------------------------
 # Transport-failure classification — which errors mean "the session is dead".
@@ -670,7 +806,11 @@ class SenpiMcpClient:
 
             used = self._ensure_connected(name, deadline)
             result = self._run(used.session.call_tool(name, arguments=args), name, deadline)
-            return _cast_market_numerics(name, self._unwrap(name, result), args)
+            value = _cast_market_numerics(name, self._unwrap(name, result), args)
+            # Recorded after the unwrap, so a call that returned an `isError` result is
+            # counted on the failure path below and never twice.
+            self.tick_errors.record_call(name, round((time.monotonic() - started) * 1000, 1), args)
+            return value
         except Exception as exc:
             # Catch every failure — mutation block, missing creds, the lazy
             # `import mcp`, transport errors, timeouts, tool `isError` — tally
@@ -691,13 +831,15 @@ class SenpiMcpClient:
             # counts under the SAME name, so the dominant type a blind tick
             # reports to /errors matches the senpi_mcp_error lines beside it.
             error_type = "TimeoutError" if timed_out else type(primary).__name__
+            elapsed_ms = round((time.monotonic() - started) * 1000, 1)
             self.tick_errors.record(error_type)
+            self.tick_errors.record_call(name, elapsed_ms, args, error_type)
             log_event(
                 "senpi_mcp_error",
                 tool=name,
                 error_type=error_type,
                 error=str(primary)[:500],
-                elapsed_ms=round((time.monotonic() - started) * 1000, 1),
+                elapsed_ms=elapsed_ms,
                 **({"leaf_count": len(leaves)} if len(leaves) > 1 else {}),
                 **({"timeout_seconds": self._call_timeout} if timed_out else {}),
                 **({"session_rebuilt": True} if rebuilt else {}),

package/dist/scanners/external/scaffold/tick_facts.py

@@ -0,0 +1,130 @@
+"""Per-tick observability facts the scaffold hands to the intake.
+
+A scanner tick produces nothing on roughly 99% of ticks, so the only thing a
+live screen can show about a working box is what the tick itself reports. These
+facts are assembled here, once per tick, and ride the POST the delivery sink
+already makes every tick — `/signals` on a clean tick, `/errors` on a failed
+one. There is no second channel and no extra request.
+
+ABSENT IS NOT ZERO. Every field is omitted when its value is unknown, never
+defaulted. A `candidate_count` of 0 is a scanner that found nothing; an absent
+one would be a scanner that did not say. The distinction has to survive from
+here to the screen, so nothing in this module substitutes one for the other.
+
+The state projection is the LAST COMMITTED row, which makes it stale by one tick
+whenever the current tick failed. That is deliberate: a tick that could not
+commit is exactly when the last agreed state is worth seeing.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+# Per-value character ceiling inside a projected row. An author may park a whole
+# serialised payload in one state key; this bounds what one tick can put on the
+# wire without bounding what the author may store.
+MAX_STATE_VALUE_CHARS = 1024
+
+# Keys projected out of one state row. Bounds an author's open-ended row the way
+# the runtime bounds an open attribute bag.
+MAX_STATE_KEYS = 32
+
+
+def _is_scalar(value: Any) -> bool:
+    """A value a consumer can parse: str, bool, or a FINITE number.
+
+    bool is checked before the numeric branch only implicitly — it is accepted
+    either way. NaN and the infinities are rejected: they are not JSON, and a
+    consumer reading one has no way to tell it from a real measurement.
+    """
+    if isinstance(value, bool) or isinstance(value, str):
+        return True
+    if isinstance(value, (int, float)):
+        return value == value and value not in (float("inf"), float("-inf"))
+    return False
+
+
+def project_state_row(row: Any) -> dict:
+    """The scalar fields of one state row, capped and bounded.
+
+    Returns {} for anything that is not a dict — a row the author replaced with
+    a list or a string projects to nothing rather than raising inside the loop.
+    """
+    if not isinstance(row, dict):
+        return {}
+    projected: dict = {}
+    for key in list(row.keys())[:MAX_STATE_KEYS]:
+        if not isinstance(key, str):
+            continue
+        value = row[key]
+        if not _is_scalar(value):
+            continue
+        projected[key] = value[:MAX_STATE_VALUE_CHARS] if isinstance(value, str) else value
+    return projected
+
+
+def count_changed(current: dict, previous: Optional[dict]) -> int:
+    """How many projected fields moved since the previously reported row.
+
+    A first row counts every field as changed: nothing was known before it, so
+    every value is new information. A key that disappeared counts too — its
+    absence is a change the operator should see.
+    """
+    if previous is None:
+        return len(current)
+    keys = set(current) | set(previous)
+    return sum(1 for key in keys if current.get(key) != previous.get(key))
+
+
+def build_tick_facts(
+    *,
+    tick_id: str,
+    status: str,
+    candidate_count: int,
+    duration_ms: int,
+    commit: Optional[str],
+    quiet_ticks: int,
+    lag_ms: Optional[int],
+    mcp_snapshot: Optional[dict],
+    call_snapshot: Optional[dict],
+    state_row: Any,
+    state_fields: Optional[int],
+    state_changed: Optional[int],
+) -> dict:
+    """Assemble one tick's facts for the wire.
+
+    `mcp_snapshot` / `call_snapshot` are the MCP boundary's own per-tick tallies,
+    or None when the tick ran without an MCP client — which is not the same as a
+    tick that made no calls, so both keys are then left off entirely.
+    """
+    facts: dict = {
+        "tick_id": tick_id,
+        "status": status,
+        "candidate_count": candidate_count,
+        "duration_ms": duration_ms,
+        # Always known: the loop either commits, rolls back, or fails to persist.
+        **({"commit": commit} if commit else {}),
+        # Zero is a real answer here (this tick produced a signal), so it is sent.
+        "quiet_ticks": quiet_ticks,
+    }
+    # Unknown on the very first tick of a process: there is no previous tick to
+    # measure the gap against, and a 0 would claim the scanner was exactly on time.
+    if lag_ms is not None:
+        facts["lag_ms"] = lag_ms
+    if mcp_snapshot is not None:
+        # Every failure the boundary saw this tick. The overwhelming case is a failure the
+        # author's own `except` caught and turned into an empty return — the one thing that
+        # otherwise leaves no trace at all. A failure that escaped scan() is in the count too,
+        # and needs no separating out: it already failed the tick, so `status` names it.
+        facts["mcp_failures"] = int(mcp_snapshot.get("count") or 0)
+    if call_snapshot is not None:
+        facts["mcp_ms"] = call_snapshot.get("total_ms", 0)
+        facts["mcp_calls"] = call_snapshot.get("calls", [])
+    projected = project_state_row(state_row)
+    if state_fields is not None:
+        facts["state"] = projected
+        facts["state_fields"] = state_fields
+        if state_changed is not None:
+            facts["state_changed"] = state_changed
+    return facts