symfonic.agent.cutover.authorised

authorised

What an authorised bundle is, and what it can actually serve.

Split out of :mod:~symfonic.agent.cutover.bundle when that module went over its line budget, the same way rounds left delegate and injections left policy. The division is not arbitrary: this module is the value -- a frozen record of what a composition root handed over, plus the predicates that answer "can this actually be served?" -- and bundle is the fold that produces one. The envelope asks the questions below; only the composition root calls the fold.

bundle re-exports :class:RetrievalBundle, so the address every importer and every evidence file already names keeps working.

RetrievalBundle dataclass

RetrievalBundle(retrieval: Any = None, conversation: Any = None, onboarding: Any = None, router: Any = None, identity: Any = None, writes: Any = None, lifecycle: Any = None, system_prompt: Any = None, stages: tuple[Any, ...] = (), stage_handlers: Mapping[str, Any] = dict(), authorized_effects: frozenset[str] = frozenset(), capability_names: tuple[str, ...] = (), tools: tuple[tuple[str, Any], ...] = (), delegation: Any = None, extensions: Any = None, human: Any = None)

The memory sources an authorised composition root handed to the kernel.

Both fields default to None so an incomplete bundle is constructible and refusable. Making them required would move the failure to construction, which sounds stricter and is worse: the composition root would raise at startup with no way to say "this deployment serves recall but not the window", and the envelope would never get to explain which half is missing.

missing

missing() -> tuple[str, ...]

The segments that cannot be served, named for the refusal message.

Named rather than counted: "the bundle is incomplete" sends a reader to re-derive which half, and the two halves fail in different ways.

Source code in src/symfonic/agent/cutover/authorised.py

def missing(self) -> tuple[str, ...]:
    """The segments that cannot be served, named for the refusal message.

    Named rather than counted: "the bundle is incomplete" sends a reader to
    re-derive which half, and the two halves fail in different ways.
    """
    absent: list[str] = []
    if not _answers(self.retrieval, "retrieve"):
        absent.append("retrieval")
    elif not _answers(self.retrieval, "scan_candidates"):
        # Named apart from a missing port, because the fixes differ: one
        # deployment forgot to wire a store, the other wired a store that
        # can only be asked for a capped result.
        absent.append("retrieval scan (CandidateScan.scan_candidates)")
    if not self.serves_conversation():
        absent.append("conversation")
    return tuple(absent)

serves_consolidation

serves_consolidation() -> bool

Both halves, because staging without committing recalls nothing.

write alone is not evidence, for the reason :meth:serves_retrieval gives about retrieve: the write port's own contract says "Pending memories are not retrievable until MemoryLifecyclePort.flush". A bundle that stages and cannot commit would be admitted, would run the write stage, and would leave a store that recalls nothing — admitted, answered, and empty.

Source code in src/symfonic/agent/cutover/authorised.py

def serves_consolidation(self) -> bool:
    """Both halves, because staging without committing recalls nothing.

    ``write`` alone is not evidence, for the reason
    :meth:`serves_retrieval` gives about ``retrieve``: the write port's own
    contract says "Pending memories are not retrievable until
    ``MemoryLifecyclePort.flush``". A bundle that stages and cannot commit
    would be admitted, would run the write stage, and would leave a store
    that recalls nothing — admitted, answered, and empty.
    """
    return _answers(self.writes, "write") and _answers(self.lifecycle, "flush")

serves_delegation

serves_delegation() -> bool

Whether a child can actually be reached from an admitted turn.

Asked by the envelope before sub_agents is admitted, and asked of the bundle rather than of the agent for the reason :meth:serves_hydration is: an agent that declares children and a bundle that carries no way to reach them is the half-shape. The turn would be served, the model would never be offered run_agent, and the parent would answer the question itself -- plausibly, with nothing raised. Both halves travel or the envelope stays closed: a capability that can name its children, and at least one bound tool for the model to reach them with.

Source code in src/symfonic/agent/cutover/authorised.py

def serves_delegation(self) -> bool:
    """Whether a child can actually be reached from an admitted turn.

    Asked by the envelope before ``sub_agents`` is admitted, and asked of
    the *bundle* rather than of the agent for the reason
    :meth:`serves_hydration` is: an agent that declares children and a
    bundle that carries no way to reach them is the half-shape. The turn
    would be served, the model would never be offered ``run_agent``, and
    the parent would answer the question itself -- plausibly, with nothing
    raised. Both halves travel or the envelope stays closed: a capability
    that can name its children, and at least one bound tool for the model
    to reach them with.
    """
    return bool(self.delegation is not None and self.tools)

serves_extensions

serves_extensions() -> bool

Whether a loaded plugin can actually reach an admitted turn (TA8.21).

Asked by the envelope before plugins is admitted, and asked of the bundle for the reason :meth:serves_delegation is. The half-shape here is the quietest one in this migration: an agent with a plugin loaded, admitted onto a path where nothing harvests it, is served normally -- the model answers, nothing raises, and the plugin's instructions are simply not in the prompt while its validate_state_transition is never asked.

Both halves travel or the envelope stays closed: a capability, and evidence its contribution actually landed in this fold. The second is checked by stage id rather than by presence, because a capability object that was passed and then contributed nothing -- an empty composition, a fold that skipped it -- is exactly the state that looks wired and is not.

Source code in src/symfonic/agent/cutover/authorised.py

def serves_extensions(self) -> bool:
    """Whether a loaded plugin can actually reach an admitted turn (TA8.21).

    Asked by the envelope before ``plugins`` is admitted, and asked of the
    *bundle* for the reason :meth:`serves_delegation` is. The half-shape
    here is the quietest one in this migration: an agent with a plugin
    loaded, admitted onto a path where nothing harvests it, is served
    normally -- the model answers, nothing raises, and the plugin's
    instructions are simply not in the prompt while its
    ``validate_state_transition`` is never asked.

    Both halves travel or the envelope stays closed: a capability, **and**
    evidence its contribution actually landed in this fold. The second is
    checked by stage id rather than by presence, because a capability
    object that was passed and then contributed nothing -- an empty
    composition, a fold that skipped it -- is exactly the state that looks
    wired and is not.
    """
    if self.extensions is None:
        return False
    stage = getattr(self.extensions, "stage_id", "")
    return bool(stage) and any(
        getattr(descriptor, "stage_id", None) == stage
        for descriptor in self.stages
    )

serves_human

serves_human() -> bool

Whether a turn admitted here could actually stop and be answered.

Asked by the envelope (_human_refusal) before an agent carrying a _human_interaction capability is admitted, of the bundle for the reason :meth:serves_extensions is asked of it, and checked by stage id rather than by presence for the same reason: a capability object that was passed and then contributed nothing -- nothing registered, no per-run binding resolver, no token encoder -- is exactly the state that looks wired and is not. An agent in it would offer ask_user to the model, or worse would not, and either way a human-in-the-loop consumer would wait for a pause that no stage in the compiled plan can raise.

Source code in src/symfonic/agent/cutover/authorised.py

def serves_human(self) -> bool:
    """Whether a turn admitted here could actually stop and be answered.

    Asked by the envelope (``_human_refusal``) before an agent carrying a
    ``_human_interaction`` capability is admitted, of the *bundle* for the
    reason :meth:`serves_extensions` is asked of it, and
    checked by **stage id rather than by presence** for the same reason: a
    capability object that was passed and then contributed nothing --
    nothing registered, no per-run binding resolver, no token encoder -- is
    exactly the state that looks wired and is not. An agent in it would
    offer ``ask_user`` to the model, or worse would not, and either way a
    human-in-the-loop consumer would wait for a pause that no stage in the
    compiled plan can raise.
    """
    if self.human is None:
        return False
    from symfonic.capabilities.human.contribution import PAUSE_STAGE_ID

    return any(
        getattr(descriptor, "stage_id", None) == PAUSE_STAGE_ID
        for descriptor in self.stages
    )

serves_hydration

serves_hydration() -> bool

Both segments, or the envelope stays closed.

Source code in src/symfonic/agent/cutover/authorised.py

def serves_hydration(self) -> bool:
    """Both segments, or the envelope stays closed."""
    return self.serves_retrieval() and self.serves_conversation()

serves_identity

serves_identity() -> bool

Whether the assistant's identity travels and can be rendered.

Source code in src/symfonic/agent/cutover/authorised.py

def serves_identity(self) -> bool:
    """Whether the assistant's identity travels and can be rendered."""
    return _answers(self.identity, "read")

serves_onboarding

serves_onboarding() -> bool

Whether an onboarding directive travels and can be rendered.

Source code in src/symfonic/agent/cutover/authorised.py

def serves_onboarding(self) -> bool:
    """Whether an onboarding directive travels and can be rendered."""
    return _answers(self.onboarding, "read")

serves_retrieval

serves_retrieval() -> bool

Both seams, because the composition needs both.

retrieve alone is not evidence. PortCandidateSource requires scan_candidates -- the gates that decide what survives run after retrieval, so a capped read starves them -- and a bundle claiming to serve recall on the strength of retrieve was admitted by the envelope and then refused by the fold. Admission has to ask for what composition will demand, or the refusal arrives after the decision that depended on it.

Source code in src/symfonic/agent/cutover/authorised.py

def serves_retrieval(self) -> bool:
    """Both seams, because the composition needs both.

    ``retrieve`` alone is not evidence. ``PortCandidateSource`` requires
    ``scan_candidates`` -- the gates that decide what survives run after
    retrieval, so a capped read starves them -- and a bundle claiming to
    serve recall on the strength of ``retrieve`` was admitted by the
    envelope and then refused by the fold. Admission has to ask for what
    composition will demand, or the refusal arrives after the decision that
    depended on it.
    """
    return _answers(self.retrieval, "retrieve") and _answers(
        self.retrieval, "scan_candidates"
    )

serves_routing

serves_routing() -> bool

Whether a turn's palette can actually be narrowed.

contribute alone is not evidence for the same reason retrieve was not: the boundary binds what the snapshot holds, so a router that cannot answer leaves the plan's binding in place and the turn is offered every tool -- which is the disabled behaviour wearing an admission.

Source code in src/symfonic/agent/cutover/authorised.py

def serves_routing(self) -> bool:
    """Whether a turn's palette can actually be narrowed.

    ``contribute`` alone is not evidence for the same reason ``retrieve``
    was not: the boundary binds what the *snapshot* holds, so a router that
    cannot answer leaves the plan's binding in place and the turn is offered
    every tool -- which is the disabled behaviour wearing an admission.
    """
    return _answers(self.router, "contribute")

serves_system_prompt

serves_system_prompt() -> bool

Whether an authored system prompt travels and can be read.

Separate from :meth:serves_hydration because they lift separate pins: an agent may hydrate without shaping a system prompt, and one that shapes a prompt without hydrating is equally valid. Folding them into one predicate would make each flag wait on the other's evidence.

Source code in src/symfonic/agent/cutover/authorised.py

def serves_system_prompt(self) -> bool:
    """Whether an authored system prompt travels and can be read.

    Separate from :meth:`serves_hydration` because they lift separate pins:
    an agent may hydrate without shaping a system prompt, and one that
    shapes a prompt without hydrating is equally valid. Folding them into
    one predicate would make each flag wait on the other's evidence.
    """
    return _answers(self.system_prompt, "read")

authorised_effects

authorised_effects(bundle: Any) -> frozenset[str]

The effects a plan compiled with bundle may exercise.

The model call, plus whatever the bundle carries. model_call is the plan factory's default and is not the bundle's to grant -- it comes from the invocation's shape -- so dropping it when a bundle is present would compile a plan that cannot call the model, which fails at the one place nothing tests: the first real turn.

Here rather than in delegate because it reads a field of the value this module defines, and because delegate is translation: what a bundle authorises is the bundle's own question.

Source code in src/symfonic/agent/cutover/authorised.py

def authorised_effects(bundle: Any) -> frozenset[str]:
    """The effects a plan compiled with ``bundle`` may exercise.

    The model call, plus whatever the bundle carries. ``model_call`` is the
    plan factory's default and is not the bundle's to grant -- it comes from the
    invocation's shape -- so dropping it when a bundle is present would compile
    a plan that cannot call the model, which fails at the one place nothing
    tests: the first real turn.

    Here rather than in ``delegate`` because it reads a field of the value this
    module defines, and because ``delegate`` is translation: what a bundle
    authorises is the bundle's own question.
    """
    granted = getattr(bundle, "authorized_effects", None) or frozenset()
    return frozenset({"model_call"}) | frozenset(granted)