dos-kernel 0.22.0__py3-none-win_amd64.whl

dos/verdict_rollup.py

@@ -0,0 +1,217 @@
+"""verdict-rollup — fold many status-bearing items into ONE surface-agnostic
+summary every render surface reproduces identically (C9, the cross-surface-drift fix).
+
+A single per-producer verdict reaches the operator on several surfaces — console,
+Slack, an LLM summary, a JSON bundle — and each surface independently decides
+whether to show it and how. They drift: a probe a run *requested* but that never
+produced output shows on one surface and is silent on another (the
+"requested-but-absent → false-pass" class the reference benchmark logged before it
+built a per-feature rollup). The fix is to fold the statuses ONCE, here, into a
+summary object every surface renders from — so they cannot disagree about the
+headline, the all-clean flag, or a missing producer.
+
+This is the **domain-free kernel half** of that rollup. It ships the FOLD; the
+status vocabulary is CALLER DATA:
+
+  * The caller supplies a `StatusRank` — its own closed status set mapped to a
+    worst-first severity order (`{"failed": 0, "ok": 5, …}`). The kernel hard-codes
+    NO status names (no "blktrace", no "ok"/"empty") — those are workspace data, the
+    same closed-enum-as-data seam as `reasons`/`stamp`. Law 1 (kernel imports no
+    host) holds: a rolled-up status is a string the kernel never interprets beyond
+    "where does it rank?".
+  * `requested-but-absent` is a FIRST-CLASS synthesized item, not a silence: a
+    caller that *expected* a producer (it was requested) but got no item for it
+    passes its key to `rollup(..., absent=[…])`, and the fold emits a typed item
+    for it at a caller-named `absent_status`. So "we asked for X and got nothing"
+    surfaces as a verdict on every surface, never as a missing row one surface
+    happens to omit.
+
+The result composes with the `dos.verdict` conventions (a `worst_status` headline
++ `reason` + `to_dict`) so it drops into the same `--output json` / renderer seam
+as the other verdicts. Pure stdlib leaf — never raises on a malformed item (it
+degrades to a caller-named `unknown_status`), the fail-safe rollup discipline.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Optional, Sequence
+
+
+@dataclass(frozen=True)
+class StatusRank:
+    """A caller's closed status vocabulary as a worst-first severity order.
+
+    `order` maps each status string to an int where SMALLER == more severe (so the
+    worst status is the `min`). `unknown_status` is what a malformed/unrankable item
+    folds to (must itself be in `order`); `absent_status` is the status a
+    requested-but-absent producer is synthesized as (also in `order`). Both default
+    to common names but are caller-overridable — the kernel ships no fixed vocabulary.
+    """
+
+    order: Mapping[str, int]
+    unknown_status: str = "unknown"
+    absent_status: str = "requested"
+
+    def rank(self, status: str) -> int:
+        """Severity rank of `status` (smaller = worse). An unranked status sorts
+        LAST (least severe) so an unknown caller status never masquerades as the
+        worst — the headline must not be driven by a typo."""
+        return self.order.get(status, max(self.order.values(), default=0) + 1)
+
+    def __post_init__(self) -> None:
+        if not self.order:
+            raise ValueError("StatusRank.order must be non-empty")
+        for name in (self.unknown_status, self.absent_status):
+            if name not in self.order:
+                raise ValueError(
+                    f"StatusRank: {name!r} must appear in `order` "
+                    f"(got {sorted(self.order)})")
+
+
+@dataclass(frozen=True)
+class RollupItem:
+    """One folded item — a producer's status plus why, surface-agnostic.
+
+    `key` identifies the producer (a device, a check name, …). `status` is one of
+    the caller's vocabulary. `reason` is the operator-facing line. `absent` marks a
+    synthesized requested-but-absent item (so a surface can style it distinctly).
+    `integrity` carries extra flags a surface may highlight even on a status string
+    that predates them (the lift's integrity-field idea, generalized to data)."""
+
+    key: str
+    status: str
+    reason: str = ""
+    absent: bool = False
+    integrity: tuple[str, ...] = ()
+
+    def to_dict(self) -> dict:
+        return {
+            "key": self.key,
+            "status": self.status,
+            "reason": self.reason,
+            "absent": self.absent,
+            "integrity": list(self.integrity),
+        }
+
+
+@dataclass(frozen=True)
+class VerdictRollup:
+    """The single surface-agnostic summary every render surface reproduces.
+
+    Composes with the `dos.verdict.TypedVerdict` shape: `worst_status` is the
+    headline verdict, `reason` the one-line summary, `to_dict` the JSON seam. Every
+    surface reads THESE fields, so they cannot drift in what they claim."""
+
+    label: str
+    items: tuple[RollupItem, ...]
+    rank: StatusRank = field(repr=False, default=None)  # type: ignore[assignment]
+
+    @property
+    def present(self) -> bool:
+        """True when there is anything worth surfacing at all."""
+        return bool(self.items)
+
+    @property
+    def worst_status(self) -> Optional[str]:
+        """The single most-severe status across all items (None when empty)."""
+        if not self.items:
+            return None
+        return min((it.status for it in self.items), key=self.rank.rank)
+
+    @property
+    def all_clean(self) -> bool:
+        """True iff every item is at the LEAST-severe rank and carries no integrity
+        flag — i.e. nothing to act on. (Least-severe == the max-rank status, the
+        caller's 'ok'.)"""
+        if not self.items:
+            return True
+        best = max(self.rank.order.values())
+        return all(
+            self.rank.rank(it.status) == best and not it.integrity
+            for it in self.items
+        )
+
+    @property
+    def reason(self) -> str:
+        """A counts-by-status headline, worst-first, e.g. ``2 ok, 1 empty``."""
+        if not self.items:
+            return f"{self.label}: nothing reported"
+        counts: dict[str, int] = {}
+        for it in self.items:
+            counts[it.status] = counts.get(it.status, 0) + 1
+        ordered = sorted(counts.items(), key=lambda kv: self.rank.rank(kv[0]))
+        return ", ".join(f"{n} {st}" for st, n in ordered)
+
+    # `verdict` is the TypedVerdict headline (the str-valued status). Kept a
+    # property (not a field) so the rollup satisfies the Protocol structurally.
+    @property
+    def verdict(self) -> Optional[str]:
+        return self.worst_status
+
+    def to_dict(self) -> dict:
+        return {
+            "label": self.label,
+            "verdict": self.worst_status,
+            "worst_status": self.worst_status,
+            "all_clean": self.all_clean,
+            "reason": self.reason,
+            "present": self.present,
+            "items": [it.to_dict() for it in self.items],
+        }
+
+
+def _coerce_status(raw: Any, rank: StatusRank) -> str:
+    """A status the caller's rank knows, or the caller's unknown_status (never raise)."""
+    s = str(raw) if raw is not None else rank.unknown_status
+    return s if s in rank.order else rank.unknown_status
+
+
+def rollup(
+    items: Sequence[Any],
+    *,
+    rank: StatusRank,
+    label: str = "rollup",
+    absent: Sequence[str] | None = None,
+    status_of=lambda x: _get(x, "status"),
+    key_of=lambda x: _get(x, "key"),
+    reason_of=lambda x: _get(x, "reason", ""),
+    integrity_of=lambda x: _get(x, "integrity", ()),
+) -> VerdictRollup:
+    """Fold status-bearing `items` (+ requested-but-absent keys) into one rollup.
+
+    `items` is any sequence of objects or dicts; `status_of`/`key_of`/`reason_of`/
+    `integrity_of` extract the fields (defaulting to attr/dict access by those
+    names) — so a caller's own collector objects roll up without adapting them.
+    A status not in `rank.order` degrades to `rank.unknown_status`; a malformed
+    item degrades to one `unknown` row (never raises — the fail-safe discipline).
+
+    `absent` is the load-bearing anti-drift feature: each key in it is a producer
+    the caller REQUESTED but got no item for. Each becomes a synthesized
+    `RollupItem(absent=True, status=rank.absent_status)` so "requested but missing"
+    surfaces as a typed verdict on every surface, not as a silently-dropped row.
+    """
+    rows: list[RollupItem] = []
+    for it in items or ():
+        try:
+            rows.append(RollupItem(
+                key=str(key_of(it) or "?"),
+                status=_coerce_status(status_of(it), rank),
+                reason=str(reason_of(it) or ""),
+                integrity=tuple(str(x) for x in (integrity_of(it) or ())),
+            ))
+        except Exception:  # noqa: BLE001 — a bad item must not break the fold
+            rows.append(RollupItem(
+                key="?", status=rank.unknown_status,
+                reason="(unreadable item record)"))
+    for k in absent or ():
+        rows.append(RollupItem(
+            key=str(k), status=rank.absent_status, absent=True,
+            reason="requested but no result was produced"))
+    return VerdictRollup(label=label, items=tuple(rows), rank=rank)
+
+
+def _get(obj: Any, name: str, default: Any = None) -> Any:
+    """Attr-or-dict access, the duck-typed reader the lift uses."""
+    if isinstance(obj, dict):
+        return obj.get(name, default)
+    return getattr(obj, name, default)

dos/verdicts.py

@@ -0,0 +1,181 @@
+"""The verdict registry — the OS-extensibility surface for distrust verbs (docs/86 §2).
+
+`verdict.py` names the *contract* a typed verdict satisfies; this module is the
+*registry* of verbs that satisfy it. It is the seam that lets a third party add a
+verdict the way you add a device driver: ship a module with a `classify` (the
+`verdict.Classifier` shape) and a short spec, `register()` it, and a consumer —
+the CLI, the `dos decisions` queue, an MCP tool — can enumerate and dispatch it
+WITHOUT the kernel hard-wiring its name.
+
+This is the **verb-analogue of the data registries the kernel already ships**:
+`[reasons]` (`ReasonRegistry`), `[lanes]` (`LaneTaxonomy`), `[stamp]`
+(`StampConvention`) declare a workspace's *vocabulary* as data; this declares its
+set of *verdicts* as registered specs. The combination is the one design pattern
+(HACKING.md, the closed-enum-as-data axis) lifted one level up: **an OPEN set of
+verbs, each with a CLOSED verdict shape.**
+
+Built *after* there were two real instances to generalize from (`liveness`,
+`scope`) — the "generalize last" discipline (docs/86 §4): a registry built before
+its instances is machinery imported ahead of need. The two are seed-registered
+below, centrally — the registry imports the verbs (consumer → verb, the same
+arrow `cli.py` uses), so the pure verb modules stay registry-UNAWARE and there is
+no import cycle. A verb must never `import dos.verdicts`.
+
+The four-gate registration test (docs/85 §2) a verdict must pass to be a kernel
+verb: (1) it answers a claim about ground-truth state; (2) its evidence is
+unforgeable by the agent; (3) it is domain-free; (4) its verdict is a mechanical
+closed enum. Gate (4) is machine-checkable here (`verdict.conforms` on a produced
+sample); gates (1)–(3) are properties of the verb's DESIGN that no runtime check
+can see — they stay a review responsibility, and `register(..., reviewed=...)`
+records that a human signed off so a registry audit can surface anything that
+slipped in unreviewed.
+
+NOTE on `verify`: it is the third epistemic verb, but `oracle.ShipVerdict` has not
+yet been harmonized to the contract (`shipped: bool` + `source`, no `.verdict`
+enum / `.reason` — see `verdict.py` and the docs/86 §4 step-1 harmonization). So
+it is deliberately NOT seed-registered here; it would fail gate (4) today. That
+absence is the honest marker of the remaining drift, not an oversight.
+
+This module is a CONSUMER, on the same side of the layering line as `cli.py` /
+`dos_mcp`: nothing under `src/dos/*.py` that is a *verb* imports it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional
+
+from . import verdict as _verdict
+
+
+@dataclass(frozen=True)
+class VerdictSpec:
+    """One registered distrust verb.
+
+      name      — the CLI/MCP verb token (e.g. "liveness", "scope"). Unique.
+      classify  — the pure `verdict.Classifier`: `(evidence, policy=...) -> Verdict`.
+      summary   — a one-line help string (the `dos <verb> --help` / MCP description).
+      distrusts — the claim this verb refuses to take on faith, in one phrase
+                  (gate (1) made explicit: "I'm making progress" / "the diff stayed
+                  in its lane"). Documentation, and the audit's gate-(1) prompt.
+      gather    — OPTIONAL boundary-I/O callable `(args, cfg) -> Evidence`
+                  producing the `evidence` argument (the `git_delta`-mold reader).
+                  The registry stores it so a CLI/MCP consumer can run `gather()`
+                  then `classify()`; None means the consumer supplies evidence
+                  itself (e.g. the benchmark sink, which builds evidence inline).
+
+    The remaining fields are the CLI/MCP ADAPTER — everything a *generic* consumer
+    (`verdict_cli.attach`) needs to build this verb's surface WITHOUT hard-wiring
+    its name. They are what make the wiring modular: adding a verb is a
+    `register(...)` with these filled in, and the dispatcher loop does the rest.
+    All optional, so a spec used only as a library classifier (or by the bench)
+    omits them.
+
+      add_arguments — `(parser) -> None`: add this verb's flags to an argparse
+                  subparser (delegates straight to argparse — a callable, not a
+                  data-DSL, so we don't reinvent argument parsing). None = no
+                  verb-specific flags beyond the shared `--workspace`/`--output`.
+      policy_from — `(cfg) -> Policy`: build the verb's Policy from the resolved
+                  `SubstrateConfig` (the `dos.toml [<name>]` seam). None = the
+                  classifier's own default policy is used.
+      exit_codes  — `{verdict.value: int}`: the process exit code per verdict
+                  state (e.g. liveness ADVANCING→0/SPINNING→3/STALLED→4). Empty =
+                  always exit 0 (the verdict is in stdout regardless).
+      reviewed  — whether a human confirmed gates (1)–(3) (which no runtime check
+                  can see). A registry audit flags `reviewed=False` entries.
+    """
+
+    name: str
+    classify: "_verdict.Classifier"
+    summary: str
+    distrusts: str
+    gather: Optional[Callable[..., Any]] = None
+    add_arguments: Optional[Callable[[Any], None]] = None
+    policy_from: Optional[Callable[[Any], Any]] = None
+    exit_codes: dict = field(default_factory=dict)
+    reviewed: bool = False
+
+    def __post_init__(self) -> None:
+        if not self.name or not self.name.strip():
+            raise ValueError("a verdict spec needs a non-empty name")
+        if not callable(self.classify):
+            raise ValueError(f"verdict {self.name!r}: classify must be callable")
+
+
+# The registry. Insertion-ordered so `names()` is stable for tests/help output.
+_REGISTRY: dict[str, VerdictSpec] = {}
+
+
+def register(spec: VerdictSpec, *, replace: bool = False) -> VerdictSpec:
+    """Register a distrust verb. Raises on a duplicate name unless `replace`.
+
+    The callable/name checks are in `VerdictSpec.__post_init__`. The verdict-shape
+    gate (gate 4) is NOT run here — it needs a *produced* verdict, which `register`
+    has no evidence to make; use `validate_sample()` with a representative verdict
+    (every verb's test suite does — see `test_verdicts`). Keeping `register` cheap
+    and total (no verdict construction) is what lets a third party register at
+    import time without wiring up evidence first.
+    """
+    name = spec.name.strip()
+    if name in _REGISTRY and not replace:
+        raise ValueError(
+            f"verdict {name!r} already registered (pass replace=True to override)"
+        )
+    _REGISTRY[name] = spec
+    return spec
+
+
+def validate_sample(spec: VerdictSpec, sample: Any) -> bool:
+    """Gate (4): does a verdict this verb produced satisfy the typed contract?
+
+    `sample` is a verdict the verb's `classify` returned on representative
+    evidence. Returns True iff it `verdict.conforms` — a mechanical closed-enum
+    `verdict` + a str `reason` + a JSON-shaped `to_dict`. A registry audit / a
+    verb's own test calls this; it is the one gate a machine can enforce.
+    """
+    return _verdict.conforms(sample)
+
+
+def get(name: str) -> VerdictSpec:
+    """The spec for `name`. Raises KeyError if unregistered."""
+    return _REGISTRY[name]
+
+
+def names() -> list[str]:
+    """Registered verb names, in registration order (stable)."""
+    return list(_REGISTRY)
+
+
+def all_specs() -> dict[str, VerdictSpec]:
+    """A copy of the registry — for a consumer enumerating verbs (cli/mcp/audit)."""
+    return dict(_REGISTRY)
+
+
+def unreviewed() -> list[str]:
+    """Verb names registered without a human gate-(1)–(3) sign-off (audit hook)."""
+    return [n for n, s in _REGISTRY.items() if not s.reviewed]
+
+
+# ---------------------------------------------------------------------------
+# Seed registration — the two instances that prove the shape (docs/86 §4).
+# Central (here), not self-registration in the verb modules, so liveness/scope
+# stay pure and registry-unaware (the one-way arrow). `verify` is intentionally
+# absent until ShipVerdict is harmonized to the contract (it fails gate 4 today).
+# ---------------------------------------------------------------------------
+from . import liveness as _liveness  # noqa: E402  (consumer import, after the API)
+from . import scope as _scope        # noqa: E402
+
+register(VerdictSpec(
+    name="liveness",
+    classify=_liveness.classify,
+    summary="is the run advancing, or just spinning? (the temporal verdict)",
+    distrusts="I'm making progress",
+    reviewed=True,
+))
+register(VerdictSpec(
+    name="scope",
+    classify=_scope.classify,
+    summary="did the diff stay inside the lane it claims? (the footprint verdict)",
+    distrusts="the change I stamped as (plan, phase) stays in that phase's lane",
+    reviewed=True,
+))

dos/wedge_reason.py

@@ -0,0 +1,282 @@
+"""Closed `reason_class` vocabulary for `/next-up` no-pick (WEDGE / DRAIN) verdicts.
+
+⚓ One surface per metric / mechanical-contract-over-prose. Before this module the
+WEDGE refusal — the single most common dispatch-loop outcome (110/128 runs shipped
+0 picks in the 7d window of 2026-05-31, yet the scoreboard read `live_ship_rate=1.0`
+because it only measures *launched* picks) — was authored entirely in `/next-up`
+SKILL Step 2.5/Step 3 LLM prose. Each WEDGE envelope invented its own `reason_class`
+token and its own ad-hoc JSON shape. The three consumers could not agree on the set:
+
+  * the PRODUCER (`scripts/next_up_render.py`) only emitted typed verdicts for
+    `LANE_DRAINED` / `ALREADY_SHIPPED` / `IN_FLIGHT` / `FILE_COLLISION` / `RACE`;
+    every LANE_* WEDGE was hand-written;
+  * the VERIFIER (`scripts/picker_oracle.py`) recognised ~8 tokens, NONE of the
+    LANE_* WEDGE tokens the LLM actually wrote — so every WEDGE classified as
+    `UNCLASSIFIED` ("cannot verify — recommend backfill"). The oracle reported
+    itself healthy (`oracle_disagrees=0`) precisely because it could not classify
+    the rows that mattered;
+  * the CONSUMER (`scripts/fanout_preflight_context.py`) never opened the verdict
+    envelope at all (FQ-410).
+
+This module is the one place the token set is declared. All three consumers import
+it, so a new reason class is added once, here, and is simultaneously:
+emittable by the producer, verifiable by the oracle, and refusable by the preflight.
+
+Pure stdlib (no third-party imports) so `next_up_render` / `fanout_state` /
+`picker_oracle` / `fanout_preflight_context` can all import it without dragging in
+their own heavy deps. The companion category vocabulary lives in
+`picker_oracle.NoPickCause`; we mirror the category *strings* here (not the enum) to
+avoid a circular import, and `tests/test_dispatch_pick_observability.py` pins the two in lockstep.
+"""
+
+from __future__ import annotations
+
+import enum
+
+
+class NoPickCategory(str, enum.Enum):
+    """Coarse category each `reason_class` rolls up to.
+
+    Mirrors the string values of `picker_oracle.NoPickCause` so the oracle can map
+    a `WedgeReason` straight onto its verification branch. Kept as an independent
+    enum (not an import of `NoPickCause`) so this low-level module has zero
+    `scripts/`-internal deps; `tests/test_dispatch_pick_observability.py` asserts every value here
+    is a member of `NoPickCause`.
+    """
+
+    TRUE_DRAIN = "TRUE_DRAIN"        # all in-scope plans remaining:[]; no findings
+    OPERATOR_GATE = "OPERATOR_GATE"  # soak open / operator-attended / env-flag-gated
+    STALE_CLAIM = "STALE_CLAIM"      # collision with an in-flight/foreign soft|hard claim
+    LEASE_HELD = "OPERATOR_GATE"     # foreign live /dispatch-loop owns the lane lease
+    INFLIGHT = "STALE_CLAIM"         # remaining phases all soft-claimed by a sibling packet
+    MISROUTE = "MISROUTE"            # finding routed to the wrong lane
+    RENDERER_BUG = "RENDERER_BUG"    # packet rendered picks but the renderer dropped an artifact
+    UNCLASSIFIED = "UNCLASSIFIED"    # legacy / hand-authored envelope, no known token
+
+
+@enum.unique
+class WedgeReason(str, enum.Enum):
+    """The closed set of `reason_class` tokens a no-pick verdict may carry.
+
+    Membership here is the contract: the producer validates against it before
+    writing an envelope, the oracle maps each member onto a `NoPickCause`, and the
+    preflight refuses a packet whose envelope carries any of them. A token observed
+    in the wild that is NOT here is exactly the prose-drift this module exists to
+    end — it surfaces as `UNCLASSIFIED` and is a bug to add, not to tolerate.
+
+    The tokens below are the union of (a) the deterministic verdicts the renderer
+    already wrote and (b) every distinct LANE_* token observed in real
+    `output/next-up/.verdict-*.json` envelopes through 2026-05-31.
+    """
+
+    # --- deterministic, already code-emitted -------------------------------
+    LANE_DRAINED = "LANE_DRAINED"                      # 0 plans + 0 findings (true drain)
+
+    # --- the LANE_* family, formerly LLM-prose-only ------------------------
+    # Every remaining phase is soak-observation-gated with no dispatchable code
+    # follow-up (TM5 7d soak; AR7 blocked on AR5 soak denominator).
+    LANE_BLOCKED_ON_SOAK_GATED_PHASES = "LANE_BLOCKED_ON_SOAK_GATED_PHASES"
+    # A foreign, live /dispatch-loop holds this cluster's lane lease (racing it is
+    # the collision the lane arbiter exists to prevent). Carry the holder in `reason`.
+    LANE_LEASE_HELD_BY_LIVE_DISPATCH_LOOP = "LANE_LEASE_HELD_BY_LIVE_DISPATCH_LOOP"
+    # Remaining phases are all soft-claimed in-flight by a sibling packet, and/or
+    # deferred by the plan body's own gate.
+    LANE_ALL_INFLIGHT_OR_DEFERRED = "LANE_ALL_INFLIGHT_OR_DEFERRED"
+    # The lane's remaining phases are a mix of shipped-but-unstamped + in-flight +
+    # stale-stamped — the apply/tailor "everything's already done or drifting" shape.
+    LANE_ALL_SHIPPED_INFLIGHT_OR_STALE_STAMP = "LANE_ALL_SHIPPED_INFLIGHT_OR_STALE_STAMP"
+    # Generic "every remaining phase is blocked, or its stamp is drifted" — the
+    # catch-all the tailor lane wrote when soak + stamp-drift co-occur.
+    LANE_ALL_BLOCKED_OR_STALE_STAMP = "LANE_ALL_BLOCKED_OR_STALE_STAMP"
+    # The lane is blocked on an unanswered operator decision (e.g. CD #357), and the
+    # routing finding is already soft-claimed by a sibling. No automation clears it.
+    LANE_BLOCKED_ON_OPERATOR_DECISION = "LANE_BLOCKED_ON_OPERATOR_DECISION"
+
+    # --- producer-failure class (NOT a no-pick — picks EXIST) --------------
+    # The renderer rendered >= 1 pick but DROPPED the `.prompts.json` prompt
+    # sidecar (absent / corrupt / empty bodies), so the orchestrator has no
+    # worker prompt to launch. Unlike every LANE_* reason above (the picker
+    # decided not to pick), this is a *producer* defect: the picker picked, the
+    # renderer failed to serialize the bodies. FQ-419/FQ-420 — the root cause
+    # behind the recurring downstream `body_empty_picks` refuse (6+ consecutive
+    # dispatch runs wedged across apply/tailor/CD lanes, 2026-06-01). The
+    # producer-side verify (`dos.packet_sidecar.assert_packet_shippable`) emits
+    # this so the refusal points at the renderer, one rung above /fanout. Routes
+    # to /unstick (a structural renderer fix), not /replan (the backlog is fine).
+    RENDERER_SIDECAR_DROPPED = "RENDERER_SIDECAR_DROPPED"
+
+
+# Each WedgeReason → its NoPickCategory. Exhaustive over the enum (a test asserts
+# completeness), so adding a member without categorising it fails CI rather than
+# silently degrading to UNCLASSIFIED at runtime.
+REASON_TO_CATEGORY: dict[WedgeReason, NoPickCategory] = {
+    WedgeReason.LANE_DRAINED: NoPickCategory.TRUE_DRAIN,
+    WedgeReason.LANE_BLOCKED_ON_SOAK_GATED_PHASES: NoPickCategory.OPERATOR_GATE,
+    WedgeReason.LANE_LEASE_HELD_BY_LIVE_DISPATCH_LOOP: NoPickCategory.LEASE_HELD,
+    WedgeReason.LANE_ALL_INFLIGHT_OR_DEFERRED: NoPickCategory.INFLIGHT,
+    WedgeReason.LANE_ALL_SHIPPED_INFLIGHT_OR_STALE_STAMP: NoPickCategory.INFLIGHT,
+    WedgeReason.LANE_ALL_BLOCKED_OR_STALE_STAMP: NoPickCategory.OPERATOR_GATE,
+    WedgeReason.LANE_BLOCKED_ON_OPERATOR_DECISION: NoPickCategory.OPERATOR_GATE,
+    WedgeReason.RENDERER_SIDECAR_DROPPED: NoPickCategory.RENDERER_BUG,
+}
+
+# A WEDGE carrying any of these reason classes means "do not render, route to
+# /replan" — it is a refusal, not a deferred-but-valid packet. (All of them, today;
+# the set is named explicitly so a future advisory-only reason class can be added
+# without auto-refusing.)
+REFUSE_REASONS: frozenset[WedgeReason] = frozenset(REASON_TO_CATEGORY)
+
+_ALL_TOKENS: frozenset[str] = frozenset(r.value for r in WedgeReason)
+
+
+# ---------------------------------------------------------------------------
+# Registry-aware helpers.
+#
+# The `WedgeReason` enum above is the BUILT-IN reason set, kept verbatim so this
+# module stays byte-compatible (every `WedgeReason.X` reference, the lockstep
+# test, the `REASON_TO_CATEGORY`/`REFUSE_REASONS` maps all unchanged). The four
+# helpers below are the hackability seam: they answer for the built-in set first
+# (fast, no I/O), then fall through to the ACTIVE WORKSPACE's `ReasonRegistry`
+# (`dos.config.active().reasons`) so a workspace-DECLARED reason — one that is not
+# a `WedgeReason` enum member — is still known / categorised / refusable through
+# the exact same call. `coerce` still returns an enum member for a built-in token
+# (callers that switch on `WedgeReason.X` are unaffected) and `None` for a
+# registry-only token (use `category_for` / `is_refusal`, which understand both).
+#
+# `dos.config` is imported LAZILY inside each helper so this module keeps its
+# leaf-import character (it does not pull `config` at import time — `picker_oracle`
+# imports `wedge_reason` precisely because it is cheap), and so a process that
+# never installs a custom registry pays nothing.
+# ---------------------------------------------------------------------------
+
+
+def _active_reasons():
+    """The active workspace's ReasonRegistry, or None if config is unavailable.
+
+    Lazy + defensive: if `dos.config` cannot be imported or no config is active,
+    return None and the caller falls back to the built-in enum alone — the
+    helpers must never crash a consumer just because no workspace was installed.
+    """
+    try:
+        from dos import config as _config
+        return _config.active().reasons
+    except Exception:
+        return None
+
+
+def is_known_reason(token: str | None) -> bool:
+    """True iff `token` is a known reason — a built-in `WedgeReason` member OR a
+    reason declared on the active workspace's `ReasonRegistry` (case-insensitive)."""
+    if not token:
+        return False
+    if token.strip().upper() in _ALL_TOKENS:
+        return True
+    reg = _active_reasons()
+    return bool(reg and reg.is_known(token))
+
+
+def coerce(token: str | None) -> WedgeReason | None:
+    """Return the built-in `WedgeReason` for `token`, or None.
+
+    Case-insensitive and whitespace-tolerant so a hand-authored envelope (during the
+    prose→code transition) still classifies. Returns None for a token that is not a
+    BUILT-IN member — including a workspace-declared registry-only reason; such a
+    token is real and known (`is_known_reason` is True, `category_for`/`is_refusal`
+    answer for it) but has no enum member, so callers that need the typed enum use
+    the built-in set while callers that need the verdict use the registry-aware
+    helpers below.
+    """
+    if not token:
+        return None
+    try:
+        return WedgeReason(token.strip().upper())
+    except ValueError:
+        return None
+
+
+def category_for(token: str | None) -> NoPickCategory:
+    """Map a `reason_class` token onto its NoPickCategory.
+
+    Built-in members resolve through `REASON_TO_CATEGORY`. A workspace-declared
+    reason resolves through the active `ReasonRegistry` (its category string is a
+    `NoPickCategory` value by construction). A token known to neither →
+    `UNCLASSIFIED` (forward-compatible: a brand-new label does not crash a
+    consumer, it classifies as drift until declared — and `--check` turns that
+    drift into a CI failure).
+    """
+    reason = coerce(token)
+    if reason is not None:
+        return REASON_TO_CATEGORY[reason]
+    reg = _active_reasons()
+    if reg is not None:
+        cat = reg.category_for(token)  # 'UNCLASSIFIED' for an unknown token
+        try:
+            return NoPickCategory(cat)
+        except ValueError:
+            return NoPickCategory.UNCLASSIFIED
+    return NoPickCategory.UNCLASSIFIED
+
+
+def is_refusal(token: str | None) -> bool:
+    """True iff a verdict carrying `token` must NOT be rendered (route to /replan).
+
+    Used by `fanout_preflight_context` to refuse a packet whose `.verdict` envelope
+    was pre-routed WEDGE, independent of how many picks look live (FQ-410). A
+    built-in member honors `REFUSE_REASONS`; a workspace-declared reason honors its
+    own `refusal` flag (so a workspace CAN declare an advisory-only reason). Unknown
+    tokens are treated as refusals — a no-pick envelope with an unrecognised
+    reason_class is still a no-pick, and launching against it is the exact hazard.
+    """
+    reason = coerce(token)
+    if reason is not None:
+        return reason in REFUSE_REASONS
+    reg = _active_reasons()
+    if reg is not None:
+        # The registry returns True for both a declared-refusal reason AND an
+        # unknown token (its own conservative default) — exactly the policy here.
+        return reg.is_refusal(token)
+    # No registry available — an unrecognised token is drift; refuse conservatively.
+    return True
+
+
+# A verdict carrying one of these (or no verdict at all) is launchable; anything
+# else (WEDGE / DRAIN / RACE / …) is a refusal shape. The single source of truth
+# for the launchable set — `preflight` and `decisions` previously each kept their
+# own identical copy of this frozenset (one edit from drift).
+LAUNCHABLE_VERDICTS: frozenset[str] = frozenset({"", "LIVE", "ACCEPT"})
+
+
+def envelope_is_refusal(envelope: dict | None) -> tuple[bool, str | None]:
+    """Decide whether a `.verdict-<tag>.json` ENVELOPE means REFUSE (do not launch).
+
+    The one canonical reader of an envelope's refusal shape — `preflight` (which
+    gates a packet launch) and `decisions` (which surfaces a no-pick as an operator
+    decision) both need exactly this judgement, and previously each carried its own
+    byte-identical copy flagged "kept in lockstep" (the drift hazard this collapses).
+    It belongs here beside `is_refusal(token)`: that answers for a bare reason
+    *token*, this answers for the whole *envelope* — the token check is one of the
+    four rungs below.
+
+    Refuses when the envelope is a no-pick / blocked shape, most-specific first:
+      * `do_not_render` truthy, or `blocked` truthy without `all_clear`;
+      * `verdict` is anything other than a launchable token (LIVE / ACCEPT / absent)
+        — i.e. WEDGE / DRAIN / RACE;
+      * `reason_class` is a known refusal token (`is_refusal`).
+    A LIVE-shaped envelope (`all_clear=true` and a launchable verdict) does NOT
+    refuse. Returns `(refuse, reason)` where reason is a short machine-readable tag
+    (or None when not a refusal), prefixed `verdict_envelope:` for log greppability.
+    """
+    if not envelope:
+        return (False, None)
+    verdict = str(envelope.get("verdict") or "").strip().upper()
+    reason_class = envelope.get("reason_class")
+    all_clear = bool(envelope.get("all_clear"))
+    if envelope.get("do_not_render"):
+        return (True, f"verdict_envelope:do_not_render verdict={verdict or '?'}")
+    if envelope.get("blocked") and not all_clear:
+        return (True, f"verdict_envelope:blocked verdict={verdict or '?'}")
+    if verdict and verdict not in LAUNCHABLE_VERDICTS:
+        return (True, f"verdict_envelope:verdict={verdict}")
+    if reason_class is not None and is_refusal(str(reason_class)):
+        return (True, f"verdict_envelope:reason_class={reason_class}")
+    return (False, None)