induscode 0.1.0__py3-none-any.whl

induscode/insight/wrapper.py

@@ -0,0 +1,1115 @@
+"""Insight wrapper — the app's tracing vocabulary aliased onto ``indusagi.tracing``.
+
+This is a **wrapper, not a re-port** (locked plan decision; PYTHON_PORT_PLAN
+PLAN.md M1 + analysis 05 §3). The TS ``src/insight/`` subsystem maps almost
+1:1 onto the framework's ``indusagi.tracing`` module — same architecture,
+renamed vocabulary — so this module only translates names and pins the app's
+own constants on top of the framework machinery:
+
+==============================  ==============================================
+app (TS insight)                framework (``indusagi.tracing``)
+==============================  ==============================================
+``Trail`` / ``TrailId``         trace / ``fresh_trace_id`` (32-hex, 128-bit)
+``Probe`` / ``ProbeId``         ``Segment`` / ``fresh_segment_id`` (16-hex)
+``ProbeKind``                   ``SegmentKind`` via :data:`KIND_TO_SEGMENT`
+                                (run→run, turn→inference, tool→action,
+                                model→recall, custom→custom)
+``ProbeHandle`` + NOOP_HANDLE   ``SegmentHandle`` shape (note/child/fail/close)
+``createRecorder``              :class:`InsightRecorder` over the framework
+                                ``SignalChannel`` + ``SampleGate`` + segment
+                                value functions (``open_segment`` /
+                                ``with_attributes`` / ``close_segment``)
+``ratioGate`` (FNV-1a)          ``SampleGate(RatioStrategy)`` — **verified**
+                                bit-identical to the TS ``hash32`` for fixture
+                                trail ids (``"a"*32`` → 1297108005,
+                                ``"b"*32`` → 2615884229), so the framework
+                                gate is reused, not re-ported
+``SecretRedactor``              re-ported wrapper-side (TS ``createRedactor``)
+                                reusing the app's ``SecretPattern`` rule set and
+                                the app token ``"[insight:scrubbed]"``: key rules
+                                tokenize a whole subtree, value rules replace
+                                only the matched run (``re.sub``), ``omit_keys``
+                                drops keys wholesale, and the 4096-char cap is
+                                applied in the same walk. (Not the framework
+                                ``SecretScrubber``, which replaces a matching
+                                value wholesale and has no cap or omit support.)
+==============================  ==============================================
+
+**What rides the wire.** Live probe handles emit *framework* signals
+(``OpenSignal(segment)`` / ``UpdateSignal(id, attributes)`` /
+``CloseSignal(record)``) onto a *framework* ``SignalChannel`` with framework
+segment kinds — so the framework sinks (``ConsoleSink`` / ``FileSink`` /
+``StreamSink``) plug in unchanged and the on-disk NDJSON is the framework's
+flat camelCase close-record schema (see ``replay.py`` for the schema note).
+The app vocabulary lives at the edges: :meth:`InsightRecorder.signals` adapts
+the channel into app-vocabulary :data:`Signal` values, and the replay readers
+recover app :class:`Probe` values from the framework NDJSON.
+
+**Remaining divergences from the TS surface** (wrapper costs, all unobserved
+by the ported test suite):
+
+- the framework ``UpdateSignal`` carries only ``(id, attributes)`` — not the
+  full probe — so the :meth:`InsightRecorder.signals` adapter reconstructs the
+  updated probe statefully and stamps the update's ``at`` at observation time;
+- scrubbing happens on *input* (open/child/note attributes, fail text) rather
+  than at emit time — equivalent observable behaviour, since attributes only
+  enter through those calls.
+
+**Behaviours brought to TS parity** (formerly divergences):
+
+- ``fail()`` now emits an in-flight ``update`` (mirroring the TS recorder),
+  carrying the failure through the reserved fault attributes (see
+  :data:`FAULT_MESSAGE_KEY` / :data:`FAULT_NAME_KEY` / :data:`FAULT_STACK_KEY`)
+  because the framework ``UpdateSignal`` cannot carry a status/fault directly;
+  the ``signals()`` adapter lifts them back into an error-status probe;
+- the fault's error ``name`` and ``stack`` now survive emit + NDJSON + replay
+  (via the same reserved attributes), not just the ``message`` the framework
+  ``SegmentError`` keeps;
+- a string *value* that trips a value rule now has only the matched run(s)
+  replaced (TS ``applyValueRules`` semantics), not the whole value; the
+  redactor also honours ``omit_keys``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import math
+import re
+import time
+import traceback
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import AsyncIterator, ClassVar, Literal, Protocol, TypeAlias
+
+from indusagi.tracing.channel.signal import (
+    CloseSignal as FwCloseSignal,
+    OpenSignal as FwOpenSignal,
+    SignalChannel,
+    TraceSignal,
+    UpdateSignal as FwUpdateSignal,
+)
+from indusagi.tracing.recorder.sampling import RatioStrategy, SampleGate
+from indusagi.tracing.redaction.secret_scrubber import SecretPattern
+from indusagi.tracing.signal.segment import (
+    OpenSegmentInput,
+    Segment,
+    SegmentError,
+    SegmentKind,
+    close_segment,
+    fresh_segment_id,
+    fresh_trace_id,
+    open_segment,
+    with_attributes,
+)
+from indusagi.tracing.sinks.base import Sink
+
+__all__ = [
+    "APP_SECRET_PATTERNS",
+    "CloseSignal",
+    "DEFAULT_MAX_STRING_LENGTH",
+    "DEFAULT_REDACTOR",
+    "ID_WIDTHS",
+    "InsightRecorder",
+    "KIND_TO_SEGMENT",
+    "NOOP_HANDLE",
+    "OpenSignal",
+    "PASSTHRU_REDACTOR",
+    "PROBE_KINDS",
+    "Probe",
+    "ProbeAttributes",
+    "ProbeFault",
+    "ProbeHandle",
+    "ProbeId",
+    "ProbeKind",
+    "ProbeOutcome",
+    "ProbeStatus",
+    "REDACTED_TOKEN",
+    "RatioGate",
+    "SEGMENT_TO_KIND",
+    "SecretRedactor",
+    "Signal",
+    "SignalPhase",
+    "TRUNCATION_SUFFIX",
+    "TrailId",
+    "TrailRecorder",
+    "UpdateSignal",
+    "always_gate",
+    "create_recorder",
+    "create_redactor",
+    "fault_of",
+    "is_close_signal",
+    "is_closed_probe",
+    "mint_probe_id",
+    "mint_trail_id",
+    "never_gate",
+    "probe_from_segment",
+    "ratio_gate",
+]
+
+# --------------------------------------------------------------------------
+# Identifiers + kind vocabulary
+# --------------------------------------------------------------------------
+
+# Lowercase hex ids at the W3C Trace Context widths (TS contract ID_WIDTHS).
+TrailId: TypeAlias = str
+ProbeId: TypeAlias = str
+
+# The byte widths the id minter uses (trail: 32 hex chars, probe: 16).
+ID_WIDTHS: Mapping[str, int] = MappingProxyType({"trail": 16, "probe": 8})
+
+# The app's probe kinds — a small, closed set chosen for a coding agent.
+ProbeKind: TypeAlias = Literal["run", "turn", "tool", "model", "custom"]
+PROBE_KINDS: tuple[ProbeKind, ...] = ("run", "turn", "tool", "model", "custom")
+
+ProbeStatus: TypeAlias = Literal["open", "ok", "error"]
+ProbeOutcome: TypeAlias = Literal["ok", "error"]
+ProbeAttributes: TypeAlias = Mapping[str, object]
+
+# The locked kind map: app probe kind ⇄ framework segment kind.
+KIND_TO_SEGMENT: Mapping[ProbeKind, SegmentKind] = MappingProxyType(
+    {
+        "run": "run",
+        "turn": "inference",
+        "tool": "action",
+        "model": "recall",
+        "custom": "custom",
+    }
+)
+SEGMENT_TO_KIND: Mapping[SegmentKind, ProbeKind] = MappingProxyType(
+    {segment: kind for kind, segment in KIND_TO_SEGMENT.items()}
+)
+
+
+def mint_trail_id() -> TrailId:
+    """Mint a fresh 128-bit trail id (32 hex chars) via the framework minter."""
+    return fresh_trace_id()
+
+
+def mint_probe_id() -> ProbeId:
+    """Mint a fresh 64-bit probe id (16 hex chars) via the framework minter."""
+    return fresh_segment_id()
+
+
+def _now_ms() -> int:
+    return time.time_ns() // 1_000_000
+
+
+_EMPTY_ATTRIBUTES: ProbeAttributes = MappingProxyType({})
+
+# --------------------------------------------------------------------------
+# Probe data model (app-vocabulary view over the framework Segment)
+# --------------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class ProbeFault:
+    """A captured failure attached to a probe (message + optional name/stack).
+
+    Richer than the framework's message-only ``SegmentError`` — the TS
+    ``ProbeFault`` carries the error name and stack alongside the message. The
+    framework ``SegmentError`` keeps only ``message`` and its NDJSON sink only
+    writes ``{"message": …}``, so the wrapper carries ``name``/``stack`` through
+    the *attribute* channel instead (see :data:`FAULT_NAME_KEY` /
+    :data:`FAULT_STACK_KEY`), recovering them on the close signal and on replay.
+    """
+
+    message: str
+    name: str | None = None
+    stack: str | None = None
+
+
+# Reserved attribute keys the wrapper uses to carry a fault's fields through the
+# framework's message-only ``SegmentError`` / ``UpdateSignal`` paths. The
+# framework scrubber's key rules never match them (they contain none of the
+# secret-key fragments), the file sink serializes them like any other attribute,
+# and the close-signal adapter / replay reader lift them back onto the recovered
+# :class:`ProbeFault`. ``FAULT_MESSAGE_KEY`` rides only the in-flight ``fail()``
+# update (the close record keeps the message on ``SegmentError``); name/stack
+# ride both update and close. The dotted ``insight.`` namespace avoids collision
+# with caller attributes.
+FAULT_MESSAGE_KEY = "insight.fault.message"
+FAULT_NAME_KEY = "insight.fault.name"
+FAULT_STACK_KEY = "insight.fault.stack"
+
+
+def fault_of(error: object) -> ProbeFault:
+    """Coerce an arbitrary raised value into a serializable :class:`ProbeFault`.
+
+    An exception contributes its message, type name, and a rendered traceback
+    when one is attached; any other value is rendered to a string message.
+    """
+    if isinstance(error, BaseException):
+        stack: str | None = None
+        if error.__traceback__ is not None:
+            stack = "".join(traceback.format_exception(error)).rstrip("\n")
+        return ProbeFault(message=str(error), name=type(error).__name__, stack=stack)
+    return ProbeFault(message=str(error))
+
+
+def _fault_attributes(fault: ProbeFault) -> dict[str, object]:
+    """The reserved name/stack attributes carrying a fault's rich fields.
+
+    Only the present (non-``None``) fields are emitted, so a bare
+    message-only fault adds nothing to the attribute bag.
+    """
+    extra: dict[str, object] = {}
+    if fault.name is not None:
+        extra[FAULT_NAME_KEY] = fault.name
+    if fault.stack is not None:
+        extra[FAULT_STACK_KEY] = fault.stack
+    return extra
+
+
+def _fault_from_record(
+    message: str | None, attributes: Mapping[str, object]
+) -> ProbeFault | None:
+    """Recover a :class:`ProbeFault` from a message plus the reserved attributes.
+
+    Lifts ``name``/``stack`` out of the reserved attribute keys (the channel
+    the wrapper uses to carry them past the framework's message-only error).
+    Returns ``None`` when there is no message *and* no reserved fault attribute.
+    """
+    raw_name = attributes.get(FAULT_NAME_KEY)
+    raw_stack = attributes.get(FAULT_STACK_KEY)
+    name = raw_name if isinstance(raw_name, str) else None
+    stack = raw_stack if isinstance(raw_stack, str) else None
+    if message is None and name is None and stack is None:
+        return None
+    return ProbeFault(message=message if message is not None else "", name=name, stack=stack)
+
+
+@dataclass(frozen=True, slots=True)
+class Probe:
+    """An immutable timed segment within a trail — the app view of a ``Segment``.
+
+    Every transition produces a *new* frozen value; ``ended_at is None`` means
+    the probe is still in flight.
+    """
+
+    id: ProbeId
+    trail_id: TrailId
+    parent_id: ProbeId | None
+    kind: ProbeKind
+    name: str
+    started_at: int
+    ended_at: int | None = None
+    status: ProbeStatus = "open"
+    attributes: ProbeAttributes = _EMPTY_ATTRIBUTES
+    fault: ProbeFault | None = None
+
+
+def is_closed_probe(probe: Probe) -> bool:
+    """Whether ``probe`` reached a terminal state (timed and not ``open``)."""
+    return probe.status != "open" and probe.ended_at is not None
+
+
+def probe_from_segment(segment: Segment, fault: ProbeFault | None = None) -> Probe:
+    """Project a framework ``Segment`` onto the app's :class:`Probe` view.
+
+    Maps the framework segment kind back to the app vocabulary; ``fault``
+    overrides the fault otherwise recovered from ``segment.error`` plus the
+    reserved name/stack attributes. The reserved fault keys are stripped from
+    the exposed attribute bag so the fault's name/stack surface only on
+    :attr:`Probe.fault`, never as caller attributes.
+    """
+    if fault is None:
+        message = segment.error.message if segment.error is not None else None
+        fault = _fault_from_record(message, segment.attributes)
+    attributes: ProbeAttributes = segment.attributes
+    if FAULT_NAME_KEY in attributes or FAULT_STACK_KEY in attributes:
+        attributes = MappingProxyType(
+            {
+                k: v
+                for k, v in attributes.items()
+                if k not in (FAULT_NAME_KEY, FAULT_STACK_KEY)
+            }
+        )
+    return Probe(
+        id=segment.id,
+        trail_id=segment.trace_id,
+        parent_id=segment.parent_id,
+        kind=SEGMENT_TO_KIND[segment.kind],
+        name=segment.name,
+        started_at=segment.started_at,
+        ended_at=segment.ended_at,
+        status=segment.status,
+        attributes=attributes,
+        fault=fault,
+    )
+
+
+# --------------------------------------------------------------------------
+# Signal — the app-vocabulary wire union
+# --------------------------------------------------------------------------
+
+SignalPhase: TypeAlias = Literal["open", "update", "close"]
+
+
+@dataclass(frozen=True, slots=True)
+class OpenSignal:
+    """A probe-open event: carries the fresh, still-in-flight probe."""
+
+    probe: Probe
+    at: int
+    phase: ClassVar[Literal["open"]] = "open"
+
+
+@dataclass(frozen=True, slots=True)
+class UpdateSignal:
+    """A probe-update event: attributes amended (probe reconstructed, still open)."""
+
+    probe: Probe
+    at: int
+    phase: ClassVar[Literal["update"]] = "update"
+
+
+@dataclass(frozen=True, slots=True)
+class CloseSignal:
+    """A probe-close event: carries the terminal probe a sink persists."""
+
+    probe: Probe
+    at: int
+    phase: ClassVar[Literal["close"]] = "close"
+
+
+Signal: TypeAlias = OpenSignal | UpdateSignal | CloseSignal
+
+
+def is_close_signal(signal: Signal) -> bool:
+    """Narrow a :data:`Signal` to a terminal :class:`CloseSignal`."""
+    return isinstance(signal, CloseSignal)
+
+
+# --------------------------------------------------------------------------
+# Sampling gates (delegating to the framework SampleGate / RatioStrategy)
+# --------------------------------------------------------------------------
+
+
+class InsightGate(Protocol):
+    """The app's admission contract: a sticky, trail-id-keyed verdict."""
+
+    def verdict(self, trail_id: TrailId) -> bool:
+        """``True`` admits the trail (live handles); ``False`` collapses it."""
+        ...
+
+
+class _FixedGate:
+    """A constant-verdict gate wrapping a framework ``SampleGate``."""
+
+    __slots__ = ("_gate",)
+
+    def __init__(self, strategy: Literal["always", "never"]) -> None:
+        self._gate = SampleGate(strategy)
+
+    def verdict(self, trail_id: TrailId) -> bool:
+        return self._gate.decide(trail_id)
+
+
+#: Admit every trail (the default when sampling is off).
+always_gate: InsightGate = _FixedGate("always")
+#: Reject every trail (a disabled recorder).
+never_gate: InsightGate = _FixedGate("never")
+
+
+def _clamp_fraction(fraction: float) -> float:
+    """Clamp into ``[0, 1]``; NaN fails closed to 0 (mirrors the TS clamp)."""
+    if math.isnan(fraction):
+        return 0.0
+    if fraction <= 0:
+        return 0.0
+    if fraction >= 1:
+        return 1.0
+    return fraction
+
+
+class RatioGate:
+    """Admit a deterministic fraction of trails, keyed on the trail id.
+
+    Pure delegation to the framework ``SampleGate(RatioStrategy)`` — its
+    FNV-1a unit hash was verified bit-identical to the TS ``hash32`` (same
+    32-bit digests for the test fixture ids), so the verdict is sticky per id
+    and agrees across the TS and Python builds.
+    """
+
+    __slots__ = ("fraction", "_gate")
+
+    def __init__(self, fraction: float) -> None:
+        # The exposed, clamped fraction (the framework clamps internally too).
+        self.fraction = _clamp_fraction(fraction)
+        self._gate = SampleGate(RatioStrategy(self.fraction))
+
+    def verdict(self, trail_id: TrailId) -> bool:
+        return self._gate.decide(trail_id)
+
+
+def ratio_gate(fraction: float) -> RatioGate:
+    """Build a :class:`RatioGate` admitting roughly ``fraction`` of all trails."""
+    return RatioGate(fraction)
+
+
+# --------------------------------------------------------------------------
+# Secret redaction (framework SecretScrubber + the app's rules/token/cap)
+# --------------------------------------------------------------------------
+
+#: The app's redaction sentinel — pinned in the wrapper; the framework default
+#: is ``"‹redacted›"`` and is overridden via the scrubber's ``token=`` option.
+REDACTED_TOKEN = "[insight:scrubbed]"
+
+#: Hard cap on retained string length (the framework scrubber has no cap, so
+#: the wrapper applies it after scrubbing).
+DEFAULT_MAX_STRING_LENGTH = 4096
+
+#: Suffix appended to a string truncated for length.
+TRUNCATION_SUFFIX = "...[insight:truncated]"
+
+# The app's own rule set, expressed as framework SecretPatterns: one
+# case-insensitive key rule over the secret-bearing key fragments, plus one
+# value rule per credential shape (ported from the TS DEFAULT_REDACTION_RULES).
+APP_SECRET_PATTERNS: tuple[SecretPattern, ...] = (
+    SecretPattern(
+        label="secret-key",
+        key=re.compile(
+            r"(?:apikey|api_key|secret|password|passwd|authorization|auth_token"
+            r"|access_token|refresh_token|session_token|private_key|credential"
+            r"|cookie|set-cookie|bearer)",
+            re.IGNORECASE,
+        ),
+    ),
+    # Authorization scheme prefixes followed by an opaque credential run.
+    SecretPattern(
+        label="secret-value-scheme",
+        value=re.compile(r"\b(?:Bearer|Basic|Token)\s+[A-Za-z0-9._~+/=-]{8,}"),
+    ),
+    # Provider-style keys: sk-..., pk-..., rk-..., and the live/test variants.
+    SecretPattern(
+        label="secret-value-provider-key",
+        value=re.compile(r"\b[a-z]{1,5}-(?:live|test|proj)?[-_]?[A-Za-z0-9]{16,}\b"),
+    ),
+    # GitHub fine-grained / classic tokens.
+    SecretPattern(
+        label="secret-value-github",
+        value=re.compile(r"\b(?:gh[opsu]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})\b"),
+    ),
+    # AWS access key ids.
+    SecretPattern(label="secret-value-aws", value=re.compile(r"\bAKIA[0-9A-Z]{12,}\b")),
+    # JSON Web Tokens (three dot-separated base64url segments).
+    SecretPattern(
+        label="secret-value-jwt",
+        value=re.compile(
+            r"\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b"
+        ),
+    ),
+    # PEM private-key blocks (header through footer, across newlines).
+    SecretPattern(
+        label="secret-value-pem",
+        value=re.compile(
+            r"-----BEGIN[ A-Z]*PRIVATE KEY-----[\s\S]*?-----END[ A-Z]*PRIVATE KEY-----"
+        ),
+    ),
+)
+
+class SecretRedactor:
+    """The app's attribute processor, re-ported from the TS ``createRedactor``.
+
+    Two rule kinds, taken from the framework :class:`SecretPattern` objects the
+    app configures:
+
+    - a **key** rule tokenizes the *whole subtree* under a secret-named key (so
+      ``auth: {token: …}`` collapses to the token — matching the framework
+      scrubber and the TS ``scrubNode`` short-circuit);
+    - a **value** rule replaces only the *matched run(s)* inside a string with
+      the token via :func:`re.sub`, leaving the surrounding prose intact (the
+      TS ``applyValueRules`` substitution semantics — *not* the framework
+      scrubber's whole-value replacement).
+
+    A key listed in ``omit_keys`` is dropped from the output container entirely
+    rather than tokenized (the TS ``RedactionOptions.omitKeys``). The walk is
+    depth-first, tracking the enclosing key; every output structure is freshly
+    allocated and the input is never mutated.
+
+    The wrapper-side length cap (the framework scrubber has none) is folded into
+    the same walk, applied to scrubbed string leaves.
+
+    .. note::
+       The matched-run value substitution is re-ported here rather than
+       delegated to the framework ``SecretScrubber`` (whose ``_sanitize_leaf``
+       replaces a matching string value *wholesale*). The app's
+       :data:`APP_SECRET_PATTERNS` are reused unchanged, so the rule set — and
+       its FNV-parity-verified token — stays the framework's; only the
+       substitution policy is the wrapper's.
+    """
+
+    __slots__ = ("_key_rules", "_value_rules", "_max_len", "_omit")
+
+    def __init__(
+        self,
+        patterns: Iterable[SecretPattern] | None = None,
+        *,
+        max_string_length: int = DEFAULT_MAX_STRING_LENGTH,
+        omit_keys: Iterable[str] = (),
+    ) -> None:
+        resolved = (
+            tuple(patterns) if patterns is not None else APP_SECRET_PATTERNS
+        )
+        # Pre-split the rule set so the hot walk never re-checks which side a
+        # rule carries (mirrors the framework scrubber's pre-split views).
+        self._key_rules: tuple[re.Pattern[str], ...] = tuple(
+            p.key for p in resolved if p.key is not None
+        )
+        self._value_rules: tuple[re.Pattern[str], ...] = tuple(
+            p.value for p in resolved if p.value is not None
+        )
+        self._max_len = max_string_length
+        # Lower-cased for case-insensitive membership, as in the TS omit set.
+        self._omit: frozenset[str] = frozenset(k.lower() for k in omit_keys)
+
+    def _is_omitted(self, key: str) -> bool:
+        """Whether ``key`` should be dropped from the output container wholesale."""
+        return key.lower() in self._omit
+
+    def _is_secret_key(self, key: str) -> bool:
+        """Whether ``key`` trips any key rule (case-insensitive, unanchored)."""
+        for rule in self._key_rules:
+            if rule.search(key) is not None:
+                return True
+        return False
+
+    def _apply_value_rules(self, text: str) -> str:
+        """Replace every value-rule run in ``text`` with the token.
+
+        Per-rule :func:`re.sub` over the matched span only — surrounding,
+        non-secret text is preserved (the TS ``applyValueRules`` policy).
+        """
+        out = text
+        for rule in self._value_rules:
+            out = rule.sub(REDACTED_TOKEN, out)
+        return out
+
+    def _cap(self, text: str) -> str:
+        """Cap a string at the max length, appending the truncation marker."""
+        if len(text) <= self._max_len:
+            return text
+        return text[: self._max_len] + TRUNCATION_SUFFIX
+
+    def _scrub_node(self, value: object, key: str | None) -> object:
+        """Scrub one value depth-first, tracking the enclosing key.
+
+        A non-``None`` ``key`` that names a secret tokenizes the whole subtree.
+        Strings additionally run the value rules and the length cap. Mappings
+        and sequences recurse (dropping ``omit_keys``); everything else passes
+        through. Output is always freshly allocated.
+        """
+        if key is not None and self._is_secret_key(key):
+            return REDACTED_TOKEN
+        if isinstance(value, str):
+            return self._cap(self._apply_value_rules(value))
+        if isinstance(value, Mapping):
+            out: dict[str, object] = {}
+            for k, v in value.items():
+                ks = str(k)
+                if self._is_omitted(ks):
+                    continue
+                out[ks] = self._scrub_node(v, ks)
+            return out
+        if isinstance(value, (list, tuple)):
+            return [self._scrub_node(item, None) for item in value]
+        return value
+
+    def scrub_value(self, value: object) -> object:
+        """Scrub a single value (string / mapping / sequence), recursively."""
+        return self._scrub_node(value, None)
+
+    def scrub_attributes(self, attributes: ProbeAttributes) -> ProbeAttributes:
+        """Scrub an attribute bag, returning a fresh read-only bag."""
+        out: dict[str, object] = {}
+        for k, v in attributes.items():
+            ks = str(k)
+            if self._is_omitted(ks):
+                continue
+            out[ks] = self._scrub_node(v, ks)
+        return MappingProxyType(out)
+
+    def scrub_fault(self, fault: ProbeFault) -> ProbeFault:
+        """Scrub a fault's free-text fields with the value rules and cap."""
+        message = self.scrub_value(fault.message)
+        stack = self.scrub_value(fault.stack) if fault.stack is not None else None
+        return ProbeFault(
+            message=message if isinstance(message, str) else fault.message,
+            name=fault.name,
+            stack=stack if isinstance(stack, str) or stack is None else fault.stack,
+        )
+
+    def scrub_probe(self, probe: Probe) -> Probe:
+        """Scrub a whole probe (attributes + fault), returning a new frozen probe."""
+        return Probe(
+            id=probe.id,
+            trail_id=probe.trail_id,
+            parent_id=probe.parent_id,
+            kind=probe.kind,
+            name=probe.name,
+            started_at=probe.started_at,
+            ended_at=probe.ended_at,
+            status=probe.status,
+            attributes=self.scrub_attributes(probe.attributes),
+            fault=self.scrub_fault(probe.fault) if probe.fault is not None else None,
+        )
+
+
+class _PassthruRedactor:
+    """The identity processor used when redaction is disabled."""
+
+    __slots__ = ()
+
+    def scrub_value(self, value: object) -> object:
+        return value
+
+    def scrub_attributes(self, attributes: ProbeAttributes) -> ProbeAttributes:
+        return attributes
+
+    def scrub_fault(self, fault: ProbeFault) -> ProbeFault:
+        return fault
+
+    def scrub_probe(self, probe: Probe) -> Probe:
+        return probe
+
+
+#: A redactor that performs no redaction (the recorder's default, as in TS).
+PASSTHRU_REDACTOR = _PassthruRedactor()
+
+
+def create_redactor(
+    patterns: Iterable[SecretPattern] | None = None,
+    *,
+    max_string_length: int = DEFAULT_MAX_STRING_LENGTH,
+    omit_keys: Iterable[str] = (),
+) -> SecretRedactor:
+    """Build a :class:`SecretRedactor` from a rule set and options.
+
+    ``omit_keys`` (the TS ``RedactionOptions.omitKeys``) names attribute keys
+    dropped from the scrubbed output container entirely, rather than tokenized;
+    it defaults to empty, so the default redactor's behaviour is unchanged.
+    """
+    return SecretRedactor(
+        patterns, max_string_length=max_string_length, omit_keys=omit_keys
+    )
+
+
+#: A ready-built redactor using the app's default rules and caps.
+DEFAULT_REDACTOR = create_redactor()
+
+# --------------------------------------------------------------------------
+# Probe handles
+# --------------------------------------------------------------------------
+
+
+class ProbeHandle(Protocol):
+    """The behavioural face of a single in-flight probe.
+
+    ``note`` / ``child`` / ``fail`` are no-ops after ``close``; ``close`` is
+    idempotent (first call wins) — the framework's forgiving lifecycle.
+    """
+
+    @property
+    def trail_id(self) -> TrailId: ...
+
+    @property
+    def id(self) -> ProbeId: ...
+
+    @property
+    def sampled(self) -> bool: ...
+
+    def note(self, attributes: ProbeAttributes) -> None: ...
+
+    def child(
+        self,
+        kind: ProbeKind,
+        name: str,
+        attributes: ProbeAttributes | None = None,
+    ) -> "ProbeHandle": ...
+
+    def fail(self, error: object) -> None: ...
+
+    def close(self, outcome: ProbeOutcome | None = None) -> None: ...
+
+
+class _NoopProbeHandle:
+    """The single shared sampled-out handle (the framework NOOP idea, with the
+    app's ``sampled``/``trail_id`` spelling and child-attributes signature)."""
+
+    __slots__ = ()
+
+    @property
+    def trail_id(self) -> TrailId:
+        return ""
+
+    @property
+    def id(self) -> ProbeId:
+        return ""
+
+    @property
+    def sampled(self) -> bool:
+        return False
+
+    def note(self, attributes: ProbeAttributes) -> None:
+        return None
+
+    def child(
+        self,
+        kind: ProbeKind,
+        name: str,
+        attributes: ProbeAttributes | None = None,
+    ) -> ProbeHandle:
+        # Returns *itself* so an entire sampled-out subtree costs nothing.
+        return NOOP_HANDLE
+
+    def fail(self, error: object) -> None:
+        return None
+
+    def close(self, outcome: ProbeOutcome | None = None) -> None:
+        return None
+
+
+#: The frozen sampled-out handle; ``child`` returns itself.
+NOOP_HANDLE: ProbeHandle = _NoopProbeHandle()
+
+
+class _LiveProbeHandle:
+    """A sampled-in handle: drives the framework segment value functions with
+    the recorder's injected clock and emits framework signals."""
+
+    __slots__ = ("_recorder", "_segment", "_fault", "_done")
+
+    def __init__(self, recorder: "InsightRecorder", segment: Segment) -> None:
+        self._recorder = recorder
+        self._segment = segment
+        self._fault: ProbeFault | None = None
+        self._done = False
+
+    @property
+    def trail_id(self) -> TrailId:
+        return self._segment.trace_id
+
+    @property
+    def id(self) -> ProbeId:
+        return self._segment.id
+
+    @property
+    def sampled(self) -> bool:
+        return True
+
+    def note(self, attributes: ProbeAttributes) -> None:
+        if self._done:
+            return
+        clean = self._recorder._redactor.scrub_attributes(attributes)
+        self._segment = with_attributes(self._segment, clean)
+        self._recorder._emit(FwUpdateSignal(id=self._segment.id, attributes=clean))
+
+    def child(
+        self,
+        kind: ProbeKind,
+        name: str,
+        attributes: ProbeAttributes | None = None,
+    ) -> ProbeHandle:
+        if self._done:
+            return NOOP_HANDLE
+        return self._recorder._open_probe(
+            self._segment.trace_id, self._segment.id, kind, name, attributes
+        )
+
+    def fail(self, error: object) -> None:
+        # Emit an in-flight update reflecting the failure (mirroring the TS
+        # ``recorder.fail`` which routes a ``status:"error"`` update before
+        # close). The framework ``UpdateSignal`` carries only ``(id, attributes)``
+        # — no status/fault — so the failure rides the reserved fault attributes
+        # (message + name/stack), which the ``signals()`` adapter lifts back into
+        # an error-status probe. The full fault still also travels in the close
+        # record; this update makes it observable the moment ``fail`` is called.
+        if self._done:
+            return
+        self._fault = self._recorder._redactor.scrub_fault(fault_of(error))
+        fault_attrs: dict[str, object] = {
+            FAULT_MESSAGE_KEY: self._fault.message,
+            **_fault_attributes(self._fault),
+        }
+        self._segment = with_attributes(self._segment, fault_attrs)
+        self._recorder._emit(
+            FwUpdateSignal(id=self._segment.id, attributes=MappingProxyType(fault_attrs))
+        )
+
+    def close(self, outcome: ProbeOutcome | None = None) -> None:
+        if self._done:
+            return
+        self._done = True
+        status: ProbeOutcome = outcome if outcome is not None else (
+            "error" if self._fault is not None else "ok"
+        )
+        error = (
+            SegmentError(message=self._fault.message)
+            if self._fault is not None and status == "error"
+            else None
+        )
+        # Carry the fault's name + stack through the framework's message-only
+        # ``SegmentError`` by stashing them in the reserved attribute keys; the
+        # file sink serializes attributes verbatim, so they survive NDJSON and
+        # replay (the close-signal adapter / ``record_to_probe`` lift them back).
+        if error is not None and self._fault is not None:
+            extra = _fault_attributes(self._fault)
+            if extra:
+                self._segment = with_attributes(self._segment, extra)
+        record = close_segment(
+            self._segment,
+            status,
+            ended_at=self._recorder._now(),
+            error=error,
+        )
+        self._segment = record
+        self._recorder._emit(FwCloseSignal(record=record))
+
+
+# --------------------------------------------------------------------------
+# Recorder
+# --------------------------------------------------------------------------
+
+
+def _to_gate(gate: object) -> InsightGate:
+    """Coerce a gate spec (wrapper gate / framework SampleGate / strategy)."""
+    if hasattr(gate, "verdict"):
+        return gate  # type: ignore[return-value]
+    if isinstance(gate, SampleGate):
+        framework = gate
+
+        class _Adapted:
+            __slots__ = ()
+
+            def verdict(self, trail_id: TrailId) -> bool:
+                return framework.decide(trail_id)
+
+        return _Adapted()
+    if isinstance(gate, RatioStrategy):
+        return ratio_gate(gate.ratio)
+    if gate == "always":
+        return always_gate
+    if gate == "never":
+        return never_gate
+    raise TypeError(f"insight: unsupported sample gate {gate!r}")
+
+
+@dataclass(frozen=True, slots=True)
+class TrailRecorder:
+    """A recorder view bound to one trail (``Recorder.scope`` in the TS surface)."""
+
+    trail_id: TrailId
+    sampled: bool
+    _recorder: "InsightRecorder"
+
+    def open(
+        self,
+        kind: ProbeKind,
+        name: str,
+        attributes: ProbeAttributes | None = None,
+    ) -> ProbeHandle:
+        """Open a probe at the trail root level; returns its handle."""
+        if not self.sampled:
+            return NOOP_HANDLE
+        return self._recorder._open_probe(self.trail_id, None, kind, name, attributes)
+
+    def child(
+        self,
+        parent_id: ProbeId,
+        kind: ProbeKind,
+        name: str,
+        attributes: ProbeAttributes | None = None,
+    ) -> ProbeHandle:
+        """Open a probe under the given parent probe id; returns its handle."""
+        if not self.sampled:
+            return NOOP_HANDLE
+        return self._recorder._open_probe(self.trail_id, parent_id, kind, name, attributes)
+
+
+class InsightRecorder:
+    """The single recorder facade the agent talks to — the TS ``createRecorder``
+    surface over the framework transport.
+
+    Owns a framework :class:`SignalChannel` (exposed as :attr:`channel`, the
+    stream framework sinks drain), the admission gate, the redactor, and the
+    injectable clock. ``sinks`` passed at construction each get their own
+    fan-out channel (the framework channel is single-consumer) and a drain
+    task — which requires a running event loop.
+    """
+
+    __slots__ = ("service", "enabled", "channel", "_gate", "_redactor", "_now",
+                 "_sink_channels", "_drains")
+
+    def __init__(
+        self,
+        *,
+        service: str = "insight",
+        enabled: bool = True,
+        gate: object | None = None,
+        redactor: object | None = None,
+        sinks: Iterable[Sink] = (),
+        now: Callable[[], int] | None = None,
+        channel: SignalChannel | None = None,
+    ) -> None:
+        self.service = service
+        self.enabled = enabled
+        self._gate: InsightGate = (
+            _to_gate(gate) if gate is not None else always_gate
+        ) if enabled else never_gate
+        self._redactor = redactor if redactor is not None else PASSTHRU_REDACTOR
+        self._now: Callable[[], int] = now if now is not None else _now_ms
+        self.channel: SignalChannel = channel if channel is not None else SignalChannel()
+        self._sink_channels: list[SignalChannel] = []
+        self._drains: list[asyncio.Task[None]] = []
+        for sink in sinks:
+            sink_channel = SignalChannel()
+            self._sink_channels.append(sink_channel)
+            self._drains.append(
+                asyncio.get_running_loop().create_task(sink.drain(sink_channel))
+            )
+
+    # -- emission ----------------------------------------------------------
+
+    def _emit(self, signal: TraceSignal) -> None:
+        """Fan one framework signal out to the main channel and every sink."""
+        self.channel.emit(signal)
+        for sink_channel in self._sink_channels:
+            sink_channel.emit(signal)
+
+    def _open_probe(
+        self,
+        trail_id: TrailId,
+        parent_id: ProbeId | None,
+        kind: ProbeKind,
+        name: str,
+        attributes: ProbeAttributes | None,
+    ) -> ProbeHandle:
+        if kind not in KIND_TO_SEGMENT:
+            raise ValueError(f"insight: unknown probe kind {kind!r}")
+        clean = self._redactor.scrub_attributes(attributes if attributes is not None else {})
+        segment = open_segment(
+            OpenSegmentInput(
+                kind=KIND_TO_SEGMENT[kind],
+                name=name,
+                trace_id=trail_id,
+                parent_id=parent_id,
+                id=mint_probe_id(),
+                attributes=clean,
+                started_at=self._now(),
+            )
+        )
+        handle = _LiveProbeHandle(self, segment)
+        self._emit(FwOpenSignal(segment=segment))
+        return handle
+
+    # -- the app surface ----------------------------------------------------
+
+    def open_trail(
+        self,
+        name: str,
+        *,
+        kind: ProbeKind = "run",
+        trail_id: TrailId | None = None,
+        attributes: ProbeAttributes | None = None,
+    ) -> ProbeHandle:
+        """Open a brand-new trail; returns its root handle (or NOOP when gated out)."""
+        resolved = trail_id if trail_id is not None else mint_trail_id()
+        if not self.enabled or not self._gate.verdict(resolved):
+            return NOOP_HANDLE
+        return self._open_probe(resolved, None, kind, name, attributes)
+
+    def scope(self, trail_id: TrailId) -> TrailRecorder:
+        """Bind a :class:`TrailRecorder` view to an existing trail id."""
+        sampled = self.enabled and self._gate.verdict(trail_id)
+        return TrailRecorder(trail_id=trail_id, sampled=sampled, _recorder=self)
+
+    async def signals(self) -> AsyncIterator[Signal]:
+        """Adapt the framework channel into app-vocabulary :data:`Signal` values.
+
+        Single-consumer, like the underlying channel: call once and drain.
+        Update probes are reconstructed statefully from the open they amend
+        (the framework update signal carries only ``(id, attributes)``), and
+        an update's ``at`` is stamped at observation time.
+        """
+        open_probes: dict[ProbeId, Probe] = {}
+        async for raw in self.channel:
+            if isinstance(raw, FwOpenSignal):
+                probe = probe_from_segment(raw.segment)
+                open_probes[probe.id] = probe
+                yield OpenSignal(probe=probe, at=probe.started_at)
+            elif isinstance(raw, FwUpdateSignal):
+                prior = open_probes.get(raw.id)
+                if prior is None:
+                    continue
+                amended = {**prior.attributes, **raw.attributes}
+                # A ``fail()`` update carries the reserved fault attributes; lift
+                # them onto the reconstructed probe as an error status + fault
+                # (the TS in-flight ``status:"error"`` update), then strip the
+                # reserved keys so they never surface as caller attributes.
+                fault = prior.fault
+                status = prior.status
+                fault_message = amended.pop(FAULT_MESSAGE_KEY, None)
+                recovered = _fault_from_record(
+                    fault_message if isinstance(fault_message, str) else None,
+                    amended,
+                )
+                if recovered is not None:
+                    fault = recovered
+                    status = "error"
+                    amended.pop(FAULT_NAME_KEY, None)
+                    amended.pop(FAULT_STACK_KEY, None)
+                merged = Probe(
+                    id=prior.id,
+                    trail_id=prior.trail_id,
+                    parent_id=prior.parent_id,
+                    kind=prior.kind,
+                    name=prior.name,
+                    started_at=prior.started_at,
+                    ended_at=prior.ended_at,
+                    status=status,
+                    attributes=MappingProxyType(amended),
+                    fault=fault,
+                )
+                open_probes[raw.id] = merged
+                yield UpdateSignal(probe=merged, at=self._now())
+            elif isinstance(raw, FwCloseSignal):
+                probe = probe_from_segment(raw.record)
+                open_probes.pop(probe.id, None)
+                assert probe.ended_at is not None
+                yield CloseSignal(probe=probe, at=probe.ended_at)
+
+    async def flush(self) -> None:
+        """Yield a tick so synchronously-enqueued signals settle in sink tasks."""
+        await asyncio.sleep(0)
+
+    async def shutdown(self) -> None:
+        """Flush, close every channel, and await the sink drain tasks."""
+        await self.flush()
+        self.channel.close()
+        for sink_channel in self._sink_channels:
+            sink_channel.close()
+        if self._drains:
+            await asyncio.gather(*self._drains, return_exceptions=True)
+
+
+def create_recorder(
+    *,
+    service: str = "insight",
+    enabled: bool = True,
+    gate: object | None = None,
+    redactor: object | None = None,
+    sinks: Iterable[Sink] = (),
+    now: Callable[[], int] | None = None,
+    channel: SignalChannel | None = None,
+) -> InsightRecorder:
+    """Create the recorder at the head of the insight pipeline (TS ``createRecorder``)."""
+    return InsightRecorder(
+        service=service,
+        enabled=enabled,
+        gate=gate,
+        redactor=redactor,
+        sinks=sinks,
+        now=now,
+        channel=channel,
+    )