@senpi/runtime 3.0.129 → 3.0.130

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

@@ -11,18 +11,23 @@ build_delivery_sink(
     clock: Callable[[], float] = time.time,
 ) -> sink
 
-The returned sink is a callable: sink(candidates)
-On each call it:
+The returned sink is a callable: sink(candidates, tick_id=None, tick=None)
+`tick` is the scaffold's per-tick observability facts; the sink stamps the journal's
+pending count onto them (it owns the journal) and rides them on the POST it already
+makes. On each call it:
   1. Replays journal on first call (if file-backed), re-queuing valid undelivered entries
   2. Flushes still-valid undelivered entries from prior ticks (retry)
-  3. Wraps this tick's candidates into wire signals (skips invalid ones)
+  3. Wraps this tick's candidates into wire signals (skips invalid ones), stamping the
+     producing tick's id on each
   4. Drops locally superseded / expired entries
   5. POSTs {scanner_id, signals:[...]} to <intake_url>/signals
   6. Interprets the response: accepted/expired/superseded/rejected = delivered;
      transport failure or non-success envelope leaves entry queued for retry
 
-sink.post_error(error: dict) -> None
-    POSTs {scanner_id, error} to <intake_url>/errors. Fire-and-forget.
+sink.post_error(error: dict, tick: dict | None = None) -> None
+    POSTs {scanner_id, error} to <intake_url>/errors. Fire-and-forget. A failed tick's
+    facts ride here for the same reason they ride /signals on a clean one: this is the
+    POST that tick already makes.
 
 Module constants:
     SIGNALS_PATH = "/signals"
@@ -59,14 +64,47 @@ def build_delivery_sink(
 
     journal = Journal(journal_path)
     replayed = [False]  # mutable cell; replay runs once on first invocation
+    # Mutable cell; the id of the tick currently inside _sink, so the reject/warn
+    # callbacks — which are built once, here — can name it. _sink sets it on entry,
+    # before anything can read it, and both callbacks run only from inside _sink.
+    # None when the caller passed no id, or one the wire would refuse.
+    current_tick_id: list[str | None] = [None]
     # Distinct dropped-field shapes already warned about (rate-limit: a scanner that
     # sets a stray key every tick warns ONCE per shape, not every tick).
     warned_dropped_shapes: set[frozenset] = set()
+    # Distinct unusable tick-id shapes already warned about, same rate-limit reason: a loop
+    # handing the sink the same bad id every tick warns ONCE, not on every tick forever.
+    warned_unusable_tick_ids: set[str] = set()
+    # Set once per process, the first time the intake refuses a batch for carrying tick_id.
+    # From then on the field is left off the wire and the "this intake predates the field" line
+    # is not written again. Never cleared: an intake that refuses the field once would refuse it
+    # again, so re-arming would buy back the guaranteed-400 round-trip on every later tick.
+    intake_predates_tick_id = [False]
+    # The same latch for the body-level `tick` facts. Separate from the one above because
+    # they are separate fields on separate levels of the body: an intake may know one and
+    # not the other, and stripping both on either refusal would throw away what still works.
+    intake_predates_tick_facts = [False]
 
     # ------------------------------------------------------------------
     # Internal helpers
     # ------------------------------------------------------------------
 
+    def _tick_field(tick_id: Any) -> dict:
+        """`tick_id=...` as log kwargs, or nothing at all when no tick is nameable.
+
+        An absent key is the honest answer; a null or a blank would join to nothing
+        while looking like an id.
+        """
+        return {"tick_id": tick_id} if isinstance(tick_id, str) and tick_id else {}
+
+    def _signal_tick_id(signal: Any) -> Any:
+        """The producing tick's id off a stored signal, or None.
+
+        A journal line is arbitrary text on disk: `signal` may be a null, a string or
+        a list, so this never assumes a mapping.
+        """
+        return signal.get("tick_id") if isinstance(signal, dict) else None
+
     def _now_ms() -> int:
         return int(clock() * 1000)
 
@@ -89,13 +127,40 @@ def build_delivery_sink(
                 to_drop.append(entry)
         for entry in to_drop:
             journal.record_outcome(entry.id, "dropped_expired")
-            log_event("delivery_dropped_expired", entry_id=entry.id, asset=entry.asset)
+            # The producing tick's id, read off the journalled signal — the tick that
+            # noticed the expiry did not cause it.
+            log_event(
+                "delivery_dropped_expired",
+                entry_id=entry.id,
+                asset=entry.asset,
+                **_tick_field(_signal_tick_id(entry.signal)),
+            )
         return to_send
 
+    def _usable_tick_id(tick_id: Any) -> str | None:
+        """The tick id to stamp, or None to leave the field off the wire entirely.
+
+        The intake requires a non-empty string and rejects the WHOLE post on one bad field, so an
+        unusable id is dropped here rather than taking the tick's signals down with it. No id at
+        all is the old call shape, not a fault, and is not logged.
+        """
+        if tick_id is None or (isinstance(tick_id, str) and tick_id):
+            return tick_id
+        shape = repr(tick_id)[:80]
+        if shape in warned_unusable_tick_ids:
+            return None
+        warned_unusable_tick_ids.add(shape)
+        log_event("delivery_tick_id_unusable", scanner_id=scanner_id, rejected_tick_id=shape)
+        return None
+
     def _on_reject(reason: dict) -> None:
         """Loud rejection: log AND POST to /errors (design §4 — never a silent drop)."""
-        log_event("delivery_candidate_invalid", **reason)
-        _post_error({"type": "candidate_rejected", **reason})
+        # Merged into one dict before expanding: a reject record that happens to carry
+        # its own `tick_id` would otherwise be a duplicate kwarg — a TypeError raised
+        # here would take down the whole tick's delivery. The scaffold's id goes last,
+        # so the tick that actually ran the candidate is the one named.
+        log_event("delivery_candidate_invalid", **{**reason, **_tick_field(current_tick_id[0])})
+        _post_error({"type": "candidate_rejected", **reason, **_tick_field(current_tick_id[0])})
 
     def _on_warn(info: dict) -> None:
         """Loud-but-non-fatal: a valid signal still emitted, but author top-level
@@ -110,9 +175,10 @@ def build_delivery_sink(
             scanner_id=scanner_id,
             dropped=info.get("dropped"),
             asset=info.get("asset"),
+            **_tick_field(current_tick_id[0]),
         )
 
-    def _wrap_candidates(candidates, produced_at_ms: int) -> list[tuple]:
+    def _wrap_candidates(candidates, produced_at_ms: int, tick_id: str | None) -> list[tuple]:
         """Wrap candidates into (signal, entry_id) pairs, skipping invalid ones.
 
         Schema-rejected candidates are NOT silently dropped: candidate_to_signal
@@ -135,13 +201,51 @@ def build_delivery_sink(
             )
             if sig is None:
                 continue
+            # Stamped before the journal writes the entry, so a retry — later in this process or
+            # after a restart — re-posts the id of the tick that PRODUCED the signal. Skipped
+            # once the intake has proved it predates the field: a stamped signal is refused and
+            # re-posted without it, and stamping again would buy that same 400 every tick.
+            if tick_id is not None and not intake_predates_tick_id[0]:
+                sig["tick_id"] = tick_id
             entry_id = journal.record_produced(sig, now_ms=produced_at_ms)
             result.append((sig, entry_id))
         return result
 
-    def _post_signals(signals: list[dict]) -> tuple[int, Any]:
-        """POST the signals list to the intake."""
+    def _is_shape_reject(status: int, parsed: Any) -> bool:
+        """True when the intake refused the whole POST because it did not know the shape."""
+        if status != 400 or not isinstance(parsed, dict):
+            return False
+        err = parsed.get("error")
+        return isinstance(err, dict) and err.get("code") == "INVALID_SHAPE"
+
+    def _without_tick_id(signals: list[dict]) -> list[dict]:
+        """Copies of `signals` with `tick_id` removed.
+
+        Copies, never edits: the journal keeps each entry's producing tick, so once the intake
+        is upgraded a later retry of the same entry names it again.
+        """
+        return [
+            {k: v for k, v in sig.items() if k != "tick_id"} if isinstance(sig, dict) else sig
+            for sig in signals
+        ]
+
+    def _with_pending(tick: dict | None) -> dict | None:
+        """The tick facts plus the journal's BACKLOG, which only this closure knows.
+
+        Counted before this tick's own candidates are journalled, so the number is
+        signals from EARLIER ticks that the intake never acknowledged — a scanner
+        producing work that is not arriving. Counting this tick's own signals too
+        would put a 1 on every healthy signal-bearing tick and say nothing.
+        """
+        if tick is None:
+            return None
+        return {**tick, "journal_pending": len(journal.pending())}
+
+    def _post_signals(signals: list[dict], tick: dict | None = None) -> tuple[int, Any]:
+        """POST the signals list to the intake, with this tick's facts when it has any."""
         body = {"scanner_id": scanner_id, "signals": signals}
+        if tick is not None and not intake_predates_tick_facts[0]:
+            body["tick"] = tick
         # Log the exact wire shape so a 400 can be matched to the field that broke.
         if signals:
             log_event(
@@ -154,7 +258,7 @@ def build_delivery_sink(
         url = intake_url.rstrip("/") + SIGNALS_PATH
         return post_json(url, body, timeout)
 
-    def _interpret_response(status: int, parsed: Any, pending_eids: list[str], pending_entries: list) -> bool:
+    def _interpret_response(status: int, parsed: Any, pending_eids: list[str], pending_signals: list) -> bool:
         """Interpret POST response; journal outcomes. Returns True if successful envelope."""
         if status != 200 or parsed is None:
             if isinstance(parsed, dict):
@@ -194,6 +298,10 @@ def build_delivery_sink(
         # signals), and unknown/missing signal_id (ignored safely, never applied by
         # position). An unmatched entry stays pending and is retried.
         pending = set(pending_eids)
+        # eid -> the tick that produced it, for the per-entry lines below. Built only if one of
+        # those lines is actually reached: every POST pays for it otherwise, and the unknown-status
+        # branch that reads it is the rare one.
+        produced_by: dict | None = None
         for sig_status in per_signal:
             if not isinstance(sig_status, dict):
                 continue
@@ -211,7 +319,16 @@ def build_delivery_sink(
                 journal.record_outcome(eid, st)
             else:
                 # Unknown status — treat as undelivered (no outcome written)
-                log_event("delivery_unknown_status", entry_id=eid, status=st)
+                if produced_by is None:
+                    produced_by = {
+                        e: _signal_tick_id(sig) for e, sig in zip(pending_eids, pending_signals)
+                    }
+                log_event(
+                    "delivery_unknown_status",
+                    entry_id=eid,
+                    status=st,
+                    **_tick_field(produced_by.get(eid)),
+                )
         # Entries with no matching status returned stay pending (retry next tick).
 
         return True
@@ -220,7 +337,10 @@ def build_delivery_sink(
     # The sink callable
     # ------------------------------------------------------------------
 
-    def _sink(candidates) -> None:
+    def _sink(candidates, tick_id=None, tick=None) -> None:
+        tick_id = _usable_tick_id(tick_id)
+        current_tick_id[0] = tick_id
+
         # Replay journal on very first invocation
         if not replayed[0]:
             replayed[0] = True
@@ -232,8 +352,12 @@ def build_delivery_sink(
         # 1. Flush prior pending (retry candidates from older ticks)
         prior_entries = _flush_prior_pending(now_ms)
 
+        # Read here and not below: the backlog is what EARLIER ticks left behind, and
+        # step 2 is about to journal this tick's own candidates on top of it.
+        tick_body = _with_pending(tick)
+
         # 2. Wrap new candidates into signals
-        new_signal_pairs = _wrap_candidates(candidates, produced_at_ms)
+        new_signal_pairs = _wrap_candidates(candidates, produced_at_ms, tick_id)
 
         # Build the ordered signal list and corresponding entry-id list:
         # prior entries first (retry), then new ones.
@@ -253,30 +377,75 @@ def build_delivery_sink(
                 all_signals.append(sig)
                 all_eids.append(eid)
 
-        # 3. POST (always, even when signals==[])
+        # 3. POST (always, even when signals==[]) — which is what makes this the channel
+        # the tick facts ride: a quiet scanner still posts, every tick.
         try:
-            status, parsed = _post_signals(all_signals)
+            status, parsed = _post_signals(all_signals, tick_body)
         except TransportError as exc:
             log_event("delivery_transport_error", error=str(exc))
             # All signals remain undelivered -> retry on next tick
             # Empty-list no-ops: nothing to retry (no produced lines were written)
             return
 
+        # 3b. Forward-compat guard for an intake rolled back to before tick_id. Such an intake
+        # validates with additionalProperties:false, so it 400s the WHOLE batch on the unknown
+        # field — and because the journal re-posts the stored signal untouched, that batch is
+        # re-sent every tick forever, taking every fresh signal batched with it down too. Re-post
+        # the same batch without the field so one unknown key cannot strand real signals, and
+        # latch the discovery so later ticks leave the field off and stop paying the refused POST.
+        # Entries already journalled with an id still reach here and are still stripped per POST.
+        sent_tick_id = any(isinstance(sig, dict) and "tick_id" in sig for sig in all_signals)
+        sent_tick_facts = tick_body is not None and not intake_predates_tick_facts[0]
+        if _is_shape_reject(status, parsed) and (sent_tick_id or sent_tick_facts):
+            if sent_tick_id and not intake_predates_tick_id[0]:
+                intake_predates_tick_id[0] = True
+                log_event("delivery_intake_predates_tick_id", scanner_id=scanner_id)
+            if sent_tick_facts:
+                intake_predates_tick_facts[0] = True
+                log_event("delivery_intake_predates_tick_facts", scanner_id=scanner_id)
+            try:
+                status, parsed = _post_signals(_without_tick_id(all_signals))
+            except TransportError as exc:
+                log_event("delivery_transport_error", error=str(exc))
+                return
+
         # 4. Interpret response
         # The response per-signal list corresponds only to all_signals that have
-        # produced entries (all_eids). Empty no-ops: no eids.
-        _interpret_response(status, parsed, all_eids, [])
+        # produced entries (all_eids). Empty no-ops: no eids. The signals are the ones the
+        # journal holds — with their tick ids — so a log line still names the producing tick
+        # even when the retry above had to send them without it.
+        _interpret_response(status, parsed, all_eids, all_signals)
+
+    def _post_error(error: dict, tick: dict | None = None) -> None:
+        """POST an error dict, with the failed tick's facts when the caller has them.
 
-    def _post_error(error: dict) -> None:
-        """POST an error dict. Fire-and-forget."""
-        body = {"scanner_id": scanner_id, "error": error}
+        Fire-and-forget, with one exception: an intake that refuses the body because it
+        does not know `tick` is retried once without it and latched, so a failed tick's
+        error record is never lost to a field that only telemetry wanted.
+        """
+        tick_body = _with_pending(tick)
         url = intake_url.rstrip("/") + ERRORS_PATH
+        # The error belongs to exactly one tick and already names it; a body that
+        # names none leaves the key off rather than borrowing the current one.
+        origin = _tick_field(error.get("tick_id")) if isinstance(error, dict) else {}
+
+        def _body(with_tick: bool) -> dict:
+            body = {"scanner_id": scanner_id, "error": error}
+            if with_tick and tick_body is not None and not intake_predates_tick_facts[0]:
+                body["tick"] = tick_body
+            return body
+
         try:
-            post_json(url, body, timeout)
+            sent_tick_facts = tick_body is not None and not intake_predates_tick_facts[0]
+            status, parsed = post_json(url, _body(True), timeout)
+            if sent_tick_facts and _is_shape_reject(status, parsed):
+                intake_predates_tick_facts[0] = True
+                log_event("delivery_intake_predates_tick_facts", scanner_id=scanner_id)
+                post_json(url, _body(False), timeout)
         except TransportError as exc:
-            log_event("delivery_error_post_failed", error=str(exc))
+            log_event("delivery_error_post_failed", error=str(exc), **origin)
         except Exception as exc:  # noqa: BLE001
-            log_event("delivery_error_post_failed", error=str(exc))
+            log_event("delivery_error_post_failed", error=str(exc), **origin)
 
     _sink.post_error = _post_error  # type: ignore[attr-defined]
     return _sink

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),
         )