stacktrace-cli 0.2.2__py3-none-any.whl → 0.3.0__py3-none-any.whl

stacktrace_cli/detector/rules.py

@@ -14,8 +14,8 @@ These are not advisory identifiers, they never enter the overlay corpus
 `guardrail-modification`, `destructive-action`, `tool-shadowing` and
 `unpinned-invoked` — were removed rather than kept as aspirations (ADR-0013).
 Two produced *noise*: output whose majority a reader learns to skip. Two had *no
-input*: a match outcome the join has never emitted, and an escalation threshold
-that could not be met.
+input*: a match outcome the join has never emitted, and a reasoning-request
+threshold that could not be met.
 
 **Five more were withdrawn by ADR-0015, and not for either of those reasons.**
 `unsanctioned-mcp-tool-use`, `unattended-privileged-action`, `provider-refusal`,
@@ -57,7 +57,7 @@ SECURITY_RULES = frozenset(
 #: A stalled loop and a leaked credential competed for one reader's attention
 #: while sharing one severity ladder, and the ladder cannot express the
 #: difference. ADR-0010 gives each finding family its own grades; this is that
-#: argument one level down. These rules never escalate: no amount of inference
+#: argument one level down. These rules never request reasoning: no amount of inference
 #: makes a repeated call more or less repeated.
 RELIABILITY_RULES = frozenset(
     {

stacktrace_cli/detector/run.py

@@ -3,19 +3,19 @@
 Microseconds, then milliseconds, then — only for the residue neither could
 resolve — seconds of inference. The per-session cost of the ordinary case is
 effectively zero, so session volume does not scale the model bill, and
-escalation is capped for the same reason: an unbounded escalation path would
+reasoning is capped for the same reason: an unbounded reasoning path would
 make cost a function of how noisy a day was.
 
 Three things the ordering does not settle on its own, and this module does:
 
-- **A qualifying escalation that never runs is recorded, not dropped.** A
+- **A qualifying request that never runs is recorded, not dropped.** A
   default run, a budget exhaustion and an absent analyzer all leave a session
   *pending*, never indistinguishable from one with no prior at all.
-- **The budget is spent in priority order.** A marker-route escalation asks
+- **The budget is spent in priority order.** A marker-route request asks
   whether an injection was acted on and nothing else can answer it; a
   combination-route one is two supply-chain priors that happened to coincide.
   Ties resolve in session order, so a run is reproducible.
-- **Reliability findings never escalate.** A repeated call is not more or less
+- **Reliability findings never request reasoning.** A repeated call is not more or less
   repeated for having been reasoned about, and a session whose only stage-one
   finding is a stall is still evidence-free of security concern — so it stays
   eligible for the quiet-session sample.
@@ -53,7 +53,7 @@ from stacktrace_cli.detector.finding import (
 from stacktrace_cli.detector.priors import (
     _SAMPLE_BUCKETS,
     SAMPLED,
-    Escalation,
+    ReasoningRequest,
     _session_ref,
     in_sample_bucket,
     run_priors,
@@ -90,9 +90,9 @@ _WORKERS = 4
 #: default. This is where "a sample never crowds out evidence" is actually
 #: enforced: excluding evidence-backed sessions from candidacy keeps the
 #: candidate list clean, but says nothing about the order the *shared* budget is
-#: spent in once sampled and evidence-backed escalations sit in one pending list.
+#: spent in once sampled and evidence-backed requests sit in one pending list.
 #: With this rank, a sample can consume a slot only when no evidence-backed
-#: escalation is waiting for one — regardless of session order.
+#: request is waiting for one — regardless of session order.
 _PRIORITY = {"stacktrace-injection-marker": 0, SAMPLED: 9}
 
 #: Quiet sessions analysed per run with no evidence behind them. **Zero by
@@ -109,10 +109,10 @@ _PRIORITY = {"stacktrace-injection-marker": 0, SAMPLED: 9}
 #:
 #: Not additional to `DEFAULT_BUDGET`, despite an earlier comment here saying
 #: so. A selected sample joins the same `pending` list as every evidence-backed
-#: escalation, and the run-level budget caps that list as a whole -- so
+#: request, and the run-level budget caps that list as a whole -- so
 #: `sample_budget` bounds how many samples become *candidates for* a slot, not
 #: how many extra invocations a run may make. `SAMPLED`'s rank above is what
-#: keeps one from taking a slot an evidence-backed escalation is waiting for.
+#: keeps one from taking a slot an evidence-backed request is waiting for.
 DEFAULT_SAMPLE_BUDGET = 0
 
 
@@ -123,9 +123,9 @@ class DetectorRun:
     detections: tuple[Detection, ...] = ()
     unknowns: tuple[Unknown, ...] = ()
     sessions: int = 0
-    escalated: int = 0
+    requested: int = 0
     analysed: int = 0
-    #: Escalations answered from the cache. Reported because a run that spent
+    #: Reasoning requests answered from the cache. Reported because a run that spent
     #: nothing and a run that had nothing to do are not the same run.
     cache_hits: int = 0
     #: Session readers that failed before correlation ever saw their sessions —
@@ -140,7 +140,7 @@ class DetectorRun:
 def run_detector(
     correlated: CorrelatedView,
     *,
-    escalate: bool = False,
+    reasoning: bool = False,
     budget: int = DEFAULT_BUDGET,
     analyzers: dict[str, Analyzer] | None = None,
     cache: VerdictCache | None = None,
@@ -152,8 +152,8 @@ def run_detector(
 
     detections: list[Detection] = []
     unknowns: list[Unknown] = []
-    pending: list[tuple[Escalation, object]] = []
-    candidates: list[tuple[Escalation, object]] = []
+    pending: list[tuple[ReasoningRequest, object]] = []
+    candidates: list[tuple[ReasoningRequest, object]] = []
     cache_hits = 0
     # The run's own UTC calendar day. Never `date.today()`, which is local time
     # and would make eligibility depend on the machine's timezone rather than
@@ -182,23 +182,23 @@ def run_detector(
         detections.extend(stage_one)
         unknowns.extend(stage_one_unknowns)
 
-        stage_two, stage_two_unknowns, escalation = run_priors(session, stage_one)
+        stage_two, stage_two_unknowns, request = run_priors(session, stage_one)
         detections.extend(stage_two)
         unknowns.extend(stage_two_unknowns)
-        if escalation is not None:
-            pending.append((escalation, session.session))
+        if request is not None:
+            pending.append((request, session.session))
             continue
         # A sample *candidate* is evidence-free by every route already built.
         # **Of security concern**, which is narrower than "found nothing": a
         # session that stalled or hung has a reliability finding and no
         # security evidence at all, and excluding it would make the sample
         # skip exactly the sessions where something went wrong in a way no
-        # security rule reads. Reliability rules never escalate, so nothing
+        # security rule reads. Reliability rules never request reasoning, so nothing
         # else in this path distinguishes them.
         #
         # Both stages are checked: a stage-two rule such as
         # `stacktrace-advisory-reach`
-        # is security-family evidence that does not itself escalate (it is not
+        # is security-family evidence that does not itself request reasoning (it is not
         # in `_SOLO_ROUTES`), so a stage-one-only check would still route an
         # evidence-backed session into the evidence-free sample.
         if not any(d.family == "security" for d in (*stage_one, *stage_two)) and in_sample_bucket(
@@ -206,7 +206,7 @@ def run_detector(
         ):
             candidates.append(
                 (
-                    Escalation(
+                    ReasoningRequest(
                         session=_session_ref(session),
                         reasons=(SAMPLED,),
                         spans=(),
@@ -235,28 +235,28 @@ def run_detector(
     # Three passes, not one index-gated walk, because budget must be spent on
     # dispatched work rather than on list position. A cache hit or an
     # unavailable analyzer anywhere in priority order must never reduce how many
-    # real invocations a later, lower-priority escalation can still consume.
+    # real invocations a later, lower-priority request can still consume.
     #
     # Pass one: cache hits. No subprocess, no thread, no budget — and no
-    # `escalate` either. A verdict already paid for is an answer this run
-    # *has*, and `escalate` governs whether new ones may be commissioned, not
+    # `reasoning` either. A verdict already paid for is an answer this run
+    # *has*, and `reasoning` governs whether new ones may be commissioned, not
     # whether old ones may be read. Withholding it would make one session read
     # as graded or ungraded depending on a flag that spent nothing either way,
     # which is how a reader ends up paying twice for the same answer.
     keys: dict[int, str] = {}
-    misses: list[tuple[Escalation, object, Analyzer]] = []
-    not_requested: list[Escalation] = []
-    for position, (escalation, session) in enumerate(ordered):
-        analyzer = analyzers.get(escalation.session.agent_kind)
+    misses: list[tuple[ReasoningRequest, object, Analyzer]] = []
+    not_requested: list[ReasoningRequest] = []
+    for position, (request, session) in enumerate(ordered):
+        analyzer = analyzers.get(request.session.agent_kind)
         if cache is not None and analyzer is not None:
             identity = analyzer.identity()
             key = cache_key(
                 session,  # type: ignore[arg-type]
-                escalation,
+                request,
                 # The rules actually asked, not the whole shipped set: a session
                 # with no marker is never asked the marker follow-up, so its
                 # entry answers for a smaller set and must key on that.
-                applicable_rules(escalation),
+                applicable_rules(request),
                 PROMPT_VERSION,
                 identity,
             )
@@ -267,7 +267,7 @@ def run_detector(
             # session, or a rule id to be one this outcome actually asked.
             if cached is not None and validate(
                 cached,
-                rule_ids=applicable_rules(escalation),
+                rule_ids=applicable_rules(request),
                 prompt_version=PROMPT_VERSION,
                 identity=identity,
                 # Per rule, and the same function the live path parses against:
@@ -276,47 +276,45 @@ def run_detector(
                 admissible_spans=partial(
                     admissible_spans,
                     session=session,  # type: ignore[arg-type]
-                    escalation=escalation,
+                    request=request,
                 ),
             ):
-                detections.extend(_from_cache(cached, escalation))
+                detections.extend(_from_cache(cached, request))
                 cache_hits += 1
                 continue
-        if not escalate:
+        if not reasoning:
             # Not silence: a session that qualified and was never analysed is
             # pending, and the priors that qualified it travel with it.
-            not_requested.append(escalation)
+            not_requested.append(request)
             continue
         # Pass two: an analyzer that cannot run. Also no budget — a session
         # analysed by another vendor's CLI is a trust boundary created for
         # convenience, and declining costs nothing to declare.
         if analyzer is None or not analyzer.available():
-            unknowns.append(_pending(escalation, "analyzer_unavailable"))
+            unknowns.append(_pending(request, "analyzer_unavailable"))
             continue
         # Also no budget — a session whose every applicable rule is oversized
         # or otherwise unanswerable would submit to `run_reasoning` and consume
         # a slot without ever calling `analyzer.analyze`, silently starving a
-        # dispatchable escalation ranked behind it.
-        if not dispatchable(escalation, session):  # type: ignore[arg-type]
-            unknowns.append(_pending(escalation, undispatchable_reason(escalation, session)))  # type: ignore[arg-type]
+        # dispatchable request ranked behind it.
+        if not dispatchable(request, session):  # type: ignore[arg-type]
+            unknowns.append(_pending(request, undispatchable_reason(request, session)))  # type: ignore[arg-type]
             continue
-        misses.append((escalation, session, analyzer))
+        misses.append((request, session, analyzer))
 
-    if not escalate:
-        unknowns.extend(
-            _pending(escalation, "reasoning_not_requested") for escalation in not_requested
-        )
+    if not reasoning:
+        unknowns.extend(_pending(request, "reasoning_not_requested") for request in not_requested)
         return DetectorRun(
             detections=tuple(detections),
             unknowns=tuple(unknowns),
             sessions=len(correlated.sessions),
-            escalated=len(pending),
+            requested=len(pending),
             cache_hits=cache_hits,
             collection_failures=_collection_failures(correlated.unavailable),
         )
 
     # Pass three: the budget, on what is actually left to dispatch.
-    runnable: list[tuple[Escalation, object, Analyzer]] = []
+    runnable: list[tuple[ReasoningRequest, object, Analyzer]] = []
     for index, entry in enumerate(misses):
         if index >= budget:
             unknowns.append(_pending(entry[0], "budget_exhausted"))
@@ -333,24 +331,24 @@ def run_detector(
     if runnable:
         with ThreadPoolExecutor(max_workers=min(_WORKERS, len(runnable))) as pool:
             futures = {
-                pool.submit(run_reasoning, escalation, session, analyzer): position  # type: ignore[arg-type]
-                for position, (escalation, session, analyzer) in enumerate(runnable)
+                pool.submit(run_reasoning, request, session, analyzer): position  # type: ignore[arg-type]
+                for position, (request, session, analyzer) in enumerate(runnable)
             }
             for future in as_completed(futures):
                 outcomes.append((futures[future], future.result()))
 
     for position, outcome in sorted(outcomes):
-        escalation, session, analyzer = runnable[position]
+        request, session, analyzer = runnable[position]
         detections.extend(outcome.findings)  # type: ignore[attr-defined]
         unknowns.extend(outcome.unknowns)  # type: ignore[attr-defined]
         analysed += 1
         # Written from this loop and nowhere else. `run_reasoning` runs on a
         # worker thread; a write from inside it would happen on whichever worker
-        # ran that escalation, and two workers writing at once could interleave.
+        # ran that request, and two workers writing at once could interleave.
         # Every `get` and `put` is therefore made from this one thread by
         # construction, needing no lock within one process.
         if cache is not None and cacheable(outcome):
-            key = keys.get(_position_of(ordered, escalation))
+            key = keys.get(_position_of(ordered, request))
             if key is not None:
                 cache.put(key, _to_cache(outcome, analyzer))  # type: ignore[arg-type]
 
@@ -358,7 +356,7 @@ def run_detector(
         detections=tuple(detections),
         unknowns=tuple(unknowns),
         sessions=len(correlated.sessions),
-        escalated=len(pending),
+        requested=len(pending),
         analysed=analysed,
         cache_hits=cache_hits,
         collection_failures=_collection_failures(correlated.unavailable),
@@ -719,7 +717,7 @@ def _collection_failures(unavailable: Sequence[str]) -> tuple[str, ...]:
     )
 
 
-def _in_priority_order(pending: Sequence[tuple[Escalation, object]]):
+def _in_priority_order(pending: Sequence[tuple[ReasoningRequest, object]]):
     """Marker route first, then session order.
 
     Ties resolve by position, so two runs over the same corpus spend the budget
@@ -727,9 +725,9 @@ def _in_priority_order(pending: Sequence[tuple[Escalation, object]]):
     "analysed" a property of the day rather than of the corpus.
     """
 
-    def rank(item: tuple[int, tuple[Escalation, object]]) -> tuple[int, int]:
-        index, (escalation, _) = item
-        return (min((_PRIORITY.get(r, 1) for r in escalation.reasons), default=1), index)
+    def rank(item: tuple[int, tuple[ReasoningRequest, object]]) -> tuple[int, int]:
+        index, (request, _) = item
+        return (min((_PRIORITY.get(r, 1) for r in request.reasons), default=1), index)
 
     return [pair for _, pair in sorted(enumerate(pending), key=rank)]
 
@@ -740,9 +738,11 @@ def _in_priority_order(pending: Sequence[tuple[Escalation, object]]):
 _CACHED_DETAIL = "confirmed by a cached stage-3 verdict"
 
 
-def _position_of(ordered: Sequence[tuple[Escalation, object]], escalation: Escalation) -> int:
+def _position_of(
+    ordered: Sequence[tuple[ReasoningRequest, object]], request: ReasoningRequest
+) -> int:
     for position, (candidate, _) in enumerate(ordered):
-        if candidate is escalation:
+        if candidate is request:
             return position
     return -1
 
@@ -774,7 +774,7 @@ def _to_cache(outcome: ReasoningOutcome, analyzer: Analyzer) -> CachedOutcome:
     )
 
 
-def _from_cache(cached: CachedOutcome, escalation: Escalation) -> tuple[Detection, ...]:
+def _from_cache(cached: CachedOutcome, request: ReasoningRequest) -> tuple[Detection, ...]:
     """Rebuild the findings a stored outcome represents.
 
     Titles and remediations come from `reasoning.py`'s tables, already keyed by
@@ -797,25 +797,25 @@ def _from_cache(cached: CachedOutcome, escalation: Escalation) -> tuple[Detectio
             severity=entry.severity,
             confidence=entry.confidence,
             title=_TITLES.get(entry.rule_id, entry.rule_id),
-            session=escalation.session,
+            session=request.session,
             evidence=tuple(
                 Evidence(span=span, kind="cached_verdict", detail=_CACHED_DETAIL)
                 for span in entry.spans
             ),
             remediation=_REMEDIATION.get(entry.rule_id, ""),
             verdict=verdict,
-            coverage=escalation.coverage,
+            coverage=request.coverage,
         )
         for entry in cached.verdicts
     )
 
 
-def _pending(escalation: Escalation, reason: str) -> Unknown:
+def _pending(request: ReasoningRequest, reason: str) -> Unknown:
     return Unknown(
-        session=escalation.session,
+        session=request.session,
         stage="reasoning",
         reason=reason,  # type: ignore[arg-type]
-        spans=escalation.spans,
-        detail=f"escalated on {', '.join(escalation.reasons)}; not analysed",
-        reasons=escalation.reasons,
+        spans=request.spans,
+        detail=f"requested on {', '.join(request.reasons)}; not analysed",
+        reasons=request.reasons,
     )

stacktrace_cli/monitor/{escalate.py → reasoning.py}

@@ -22,8 +22,8 @@ from stacktrace_cli.monitor.state import Snapshot, StateStore
 JsonObject = dict[str, Any]
 
 
-class Escalator:
-    """The escalation budget, and the sessions currently spending it."""
+class ReasoningRunner:
+    """The reasoning budget, and the sessions currently spending it."""
 
     def __init__(
         self,
@@ -61,7 +61,7 @@ class Escalator:
             }
 
     def request(self, session_id: str) -> tuple[bool, str | None]:
-        """Accept or refuse one escalation, and say which it was.
+        """Accept or refuse one reasoning run, and say which it was.
 
         The decision and the decrement happen under one lock: two clicks
         arriving together must not both see the last unit of budget, or the
@@ -82,7 +82,7 @@ class Escalator:
                 )
             if self._remaining <= 0:
                 return False, (
-                    "refused: this monitor's escalation budget is spent. Restart "
+                    "refused: this monitor's reasoning budget is spent. Restart "
                     "monitor, or raise --budget, to allow more"
                 )
             self._remaining -= 1
@@ -91,7 +91,7 @@ class Escalator:
         # Before the thread starts, so the page cannot see a click that spent a
         # unit and left no trace. The page renders on a changed revision and
         # nothing else moves the revision on an idle machine, so an unpublished
-        # acceptance is an accepted escalation nobody is told about.
+        # acceptance is an accepted run nobody is told about.
         self._publish()
         thread = threading.Thread(target=self._work, args=(session_id,), daemon=True)
         thread.start()
@@ -107,7 +107,7 @@ class Escalator:
         and so does any local client that mistypes an id.
 
         Read outside this class's lock and through the store's, which is the
-        watcher's order — store first, escalator second — so no pair of
+        watcher's order — store first, runner second — so no pair of
         publishers can take the two the other way round.
         """
         return any(
@@ -129,8 +129,8 @@ class Escalator:
         banner: str | None = None
         try:
             banner = self._run(session_id)
-        except Exception as error:  # noqa: BLE001 - a failed escalation must not kill the thread
-            banner = f"escalating {session_id} failed: {error}"
+        except Exception as error:  # noqa: BLE001 - a failed reasoning run must not kill the thread
+            banner = f"reasoning about {session_id} failed: {error}"
         finally:
             with self._lock:
                 if session_id in self._running:
@@ -138,9 +138,9 @@ class Escalator:
             self._publish(banner=banner)
 
     def _publish(self, banner: str | None = None) -> None:
-        """Republish the current view with this escalation's state in it.
+        """Republish the current view with this reasoning run's state in it.
 
-        Only the escalation fields and, on a failure, one banner: the sessions
+        Only the reasoning fields and, on a failure, one banner: the sessions
         and alerts on the page belong to the watcher's last pass and are not
         this thread's to rebuild.
 
@@ -149,7 +149,7 @@ class Escalator:
         publish them in the other, and the newer snapshot is then overwritten
         by the older: a spent unit of budget back on the page, or a finished
         session left listed as running with no later revision to correct it.
-        The lock order is the watcher's — the store first, this escalator's
+        The lock order is the watcher's — the store first, this runner's
         second — so the two publishers cannot deadlock against each other.
 
         A banner is handed to `note` inside the same builder, for the same
@@ -160,12 +160,12 @@ class Escalator:
 
         def build(previous: Snapshot, revision: int) -> Snapshot:
             if banner is None:
-                return replace(previous, revision=revision, escalate=self.state())
+                return replace(previous, revision=revision, reasoning=self.state())
             self._note(banner)
             return replace(
                 previous,
                 revision=revision,
-                escalate=self.state(),
+                reasoning=self.state(),
                 banners=[*previous.banners, banner],
             )
 

stacktrace_cli/monitor/render.py

@@ -196,7 +196,7 @@ def snapshot_from(
     analysis: Analysis,
     *,
     revision: int,
-    escalate: JsonObject,
+    reasoning: JsonObject,
     last_active: dict[str, float] | None = None,
 ) -> Snapshot:
     """Build the page's whole state from one pipeline run.
@@ -251,6 +251,6 @@ def snapshot_from(
         },
         sessions=sessions,
         alerts=alerts,
-        escalate=escalate,
+        reasoning=reasoning,
         banners=_banners(analysis),
     )