"""Why a write is refused, and who can lift the refusal, as one importable contract.
A refusal carries a *reason* (a member of :data:`REASONS`) and a *phrase* that says
what stopped the write and ends with who can lift it. :func:`refusal_text` is the
phrase plus a trailer line ``[osprey-refusal: <reason>]``; every refusal a write
path returns to the agent ends with it, so a reader recovers the reason without
parsing the words. The package's verdict, the connector
monitor and the stdlib-only hook twin all speak these words; the hook twin restates
the tables and a parity test pins them to this module.
No phrase names a config key, a file, an environment variable or a build command:
the reader of a refusal is an operator or an agent, not the person who edits the
deployment. :data:`STORE_PATH_MARKERS` holds the path spellings of the posture store
(the directory part and the record's file name) so that a text meant for an agent can
be scanned for them.
Reasons are added by the phase that first consumes them; none is speculative.
"""
from __future__ import annotations
__all__ = ["KIND_WORDS", "REASONS", "STORE_PATH_MARKERS", "refusal_phrase", "refusal_text"]
#: The closed set of refusal reasons.
REASONS: tuple[str, ...] = (
"readonly_run",
"tier_never",
"session_held",
"target_unknown",
"owner_unknown",
"owner_unscheduled",
"owner_foreign",
"record_unavailable",
"switch_off",
"launch_pinned",
"switching",
"stopped_since",
"auth_unreadable",
"auth_holder",
"auth_channel",
"auth_range",
"auth_exhausted",
"auth_lease_lapsed",
"auth_expired",
"auth_revoked",
"auth_overlap",
)
_PHRASES: dict[str, str] = {
"readonly_run": (
"Writes are refused because the deployment is running read-only; "
"the chip cannot lift this — ask the deployment admin."
),
"tier_never": (
"Writes are refused because this login's write tier does not allow them; "
"ask the deployment admin."
),
"session_held": (
"Writes are paused: this session has an unanswered hold the operator must answer."
),
"target_unknown": (
"Writes are refused because the machine this connector writes to is not known; "
"retry, then ask the deployment admin."
),
"owner_unknown": (
"Writes are refused because this login's write tier is not known; ask the deployment admin."
),
"owner_unscheduled": (
"Writes are refused because this scheduled or triggered job runs for no login, "
"so no switch covers it; ask the deployment admin."
),
"owner_foreign": (
"Writes are refused because this machine's writes belong to another login; "
"only that login can write here."
),
"record_unavailable": (
"Writes are refused because the write switch cannot be read; "
"retry, then ask the deployment admin."
),
"switch_off": ("Writes are off; turn it on from the chip in the web terminal."),
"launch_pinned": (
"Writes are refused because this run was started with writes held off; "
"run it again without the pin."
),
"switching": (
"Writes are refused because the write gateway has not yet followed the switch; "
"retry, then ask the deployment admin."
),
"stopped_since": (
"Writes are off because a stop came after the turn-on began; "
"turn it on again from the chip."
),
"auth_unreadable": (
"Writes are refused because this program's write authorization cannot be read; "
"retry, then ask the deployment admin."
),
"auth_holder": (
"Writes are refused because this write authorization was approved for another "
"program or login; ask the operator to approve one for this program."
),
"auth_channel": (
"Writes are refused because this channel is not in the program's write "
"authorization; ask the operator to approve one that lists it."
),
"auth_range": (
"Writes are refused because this value is outside the range the program's write "
"authorization allows; ask the operator to approve a wider range."
),
"auth_exhausted": (
"Writes are refused because the program has used every write its authorization "
"allows; ask the operator to approve a new authorization."
),
"auth_lease_lapsed": (
"Writes are refused because the program holding this write authorization stopped "
"renewing it; ask the operator to approve a new authorization."
),
"auth_expired": (
"Writes are refused because the program's write authorization has expired; "
"ask the operator to approve a new authorization."
),
"auth_revoked": (
"Writes are refused because the program's write authorization has ended: a stop "
"came, or the switch is no longer at allowed; ask the operator to approve a new "
"authorization."
),
"auth_overlap": (
"The authorization is refused because another program holds one on a channel of "
"this machine it names; wait for that run to end, or stop it from the chip."
),
}
#: The words a machine kind adds to a phrase.
KIND_WORDS: dict[str, str] = {
"real": "the live machine",
"rehearsal": "the rehearsal machine",
"simulator": "the simulator",
}
#: Path spellings of the posture store: the state directory part and the record file.
STORE_PATH_MARKERS: tuple[str, ...] = ("control_target", "control_context.json")
[docs]
def refusal_phrase(reason: str, kind: str | None = None) -> str:
"""The phrase for *reason*; a known *kind* names the machine it concerns.
Raises ``ValueError`` for a reason outside :data:`REASONS`. An unknown or absent
*kind* leaves the phrase as it is.
"""
try:
phrase = _PHRASES[reason]
except KeyError:
raise ValueError(f"unknown refusal reason: {reason!r}") from None
words = KIND_WORDS.get(kind) if kind is not None else None
return f"{phrase} (Concerns {words}.)" if words else phrase
[docs]
def refusal_text(reason: str, kind: str | None = None, *, detail: str | None = None) -> str:
"""The refusal a write path returns: the phrase, then ``[osprey-refusal: <reason>]``.
*detail* — what the refusing surface adds, such as which tool was refused —
follows the phrase on its line. The trailer is its own last line, so it ends
the text whatever the caller adds. Raises ``ValueError`` for a reason outside
:data:`REASONS`, as :func:`refusal_phrase` does.
"""
phrase = refusal_phrase(reason, kind)
if detail:
phrase = f"{phrase} {detail}"
return f"{phrase}\n[osprey-refusal: {reason}]"