Skip to content

symfonic.agent.cutover.fallback_reason

fallback_reason

Closed vocabulary for fallback telemetry reason codes.

A fallback's raw reason is configuration-bearing prose and never leaves the in-process tally. Telemetry carries only the code this module projects it onto. Known refusals are matched by equality with what their producer returns; prose that merely resembles one stays unknown_refusal.

default_row_refusals cached 

default_row_refusals() -> Mapping[str, str]

The exact refusal each stock default row gets when nothing serves it.

Built by calling the envelope's own producers rather than copying their prose, so a reworded refusal moves with them; and asked of the envelope rather than exported from it, because envelope.py is pinned by content in the retirement inventory. Hydration is the no-bundle refusal only: the partial-bundle one names the missing segments and is not a default row.

Source code in src/symfonic/agent/cutover/fallback_reason.py 
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
@cache
def default_row_refusals() -> Mapping[str, str]:
    """The exact refusal each stock default row gets when nothing serves it.

    Built by calling the envelope's own producers rather than copying their
    prose, so a reworded refusal moves with them; and asked of the envelope
    rather than exported from it, because ``envelope.py`` is pinned by content
    in the retirement inventory. Hydration is the no-bundle refusal only: the
    partial-bundle one names the missing segments and is not a default row.
    """
    from symfonic.agent.cutover import envelope  # noqa: PLC0415 - fallback only

    refusals = {
        "auto_hydrate": envelope._hydration_refusal(SimpleNamespace(auto_hydrate=True), None),
        "auto_consolidate": envelope._reason("auto_consolidate", True),
        "lazy_tooling": envelope._reason("lazy_tooling", True),
    }
    return MappingProxyType({f: r for f, r in refusals.items() if r is not None})

fallback_reason_code 

fallback_reason_code(reason: str) -> str

Project refusal prose onto a closed vocabulary; exact refusals by identity.

Source code in src/symfonic/agent/cutover/fallback_reason.py 
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
def fallback_reason_code(reason: str) -> str:
    """Project refusal prose onto a closed vocabulary; exact refusals by identity."""
    from symfonic.agent.cutover import continuation as pause  # noqa: PLC0415 - fallback only

    if "release line predates" in reason.casefold():
        return "release_contract_not_published"
    exact = {
        pause.NO_PAUSE_CAPABILITY: "pause_capability_missing",
        pause.NO_DECODE_TRANSPORT: "pause_transport_unreadable",
        pause.NOT_A_CAPABILITY_TOKEN: "pause_token_invalid",
    }
    for field, refusal in default_row_refusals().items():
        exact[refusal] = DEFAULT_ROW_REFUSAL_CODES[field]
    exact[UNPROVEN_TOOL_ROUTING] = DEFAULT_ROW_REFUSAL_CODES["lazy_tooling"]
    if code := exact.get(reason):
        return code
    if "outside the migrated envelope" in reason.casefold():
        return "outside_migrated_envelope"
    return "unknown_refusal"

recorded_fallback_reason 

recorded_fallback_reason(reason: str) -> str

The reason the tally records; only the exact stock lazy_tooling refusal is renamed.

Source code in src/symfonic/agent/cutover/fallback_reason.py 
68
69
70
71
72
def recorded_fallback_reason(reason: str) -> str:
    """The reason the tally records; only the exact stock lazy_tooling refusal is renamed."""
    if reason == default_row_refusals().get("lazy_tooling"):
        return UNPROVEN_TOOL_ROUTING
    return reason