On this page

• ViewConduit
  • ViewConduit
    • ViewConduit.cleanup()
    • ViewConduit.list_conduits()
    • ViewConduit.describe_conduits()
    • ViewConduit.describe_conduit()
    • ViewConduit.list_conduit_spells()
    • ViewConduit.describe_conduit_topology()
    • ViewConduit.describe_conduit_brief()
    • ViewConduit.describe_conduit_missing_sections()
    • ViewConduit.describe_conduit_crosswalk()
    • ViewConduit.describe_conduit_inventory()
    • ViewConduit.describe_conduit_relationships()
    • ViewConduit.compare_conduits()
    • ViewConduit.list_root_conduits()
    • ViewConduit.is_root_conduit()
    • ViewConduit.get_root_conduit_id()
    • ViewConduit.list_conduits_by_root_id()
    • ViewConduit.list_conduits_by_policy()
    • ViewConduit.list_conduits_by_state()
    • ViewConduit.list_peer_conduits()
    • ViewConduit.list_peer_conduit_ids()
    • ViewConduit.list_spell_source_ids_for_conduit()
    • ViewConduit.list_binding_names_for_conduit()
    • ViewConduit.list_spell_names_for_conduit()
    • ViewConduit.describe_conduit_access_summary()
    • ViewConduit.find_conduit_by_name()
    • ViewConduit.explain_conduit_access()
    • ViewConduit.get_conduit_payload_field()
    • ViewConduit.get_required_conduit()

ViewConduit

Use md.ViewConduit from the public package namespace.

Implementation source

class ViewConduit(*, frame_view: ViewFrame | None)

Purpose:

Hold conduit-scoped viewer helper methods for one selected frame.

Contract:

• Operates through a borrowed ViewFrame helper bound to one selected frame.

• Returns ACL-filtered conduit links and conduit descriptions only.

Lifecycle:

Cleanup is idempotent and clears the helper reference.

Threading:

Created on demand per use rather than cached on the viewer, so it always reads current projection truth.

Registration:

MELDER KERNEL - guarded. Produced by FrameViewer; users reach it through the viewer surface.

Subsystem Context:

The conduit-scoped helper of the viewer family (ViewMultiFrame, ViewFrame, ViewConduit, ViewSpell), which together form the read surface of a room.

System Context:

Every helper returns ACL-FILTERED results and never raw runtime objects. That is the viewer's security boundary: a read can surface what policy permits to be described, and cannot become a handle on the thing described. It returns conduit links and descriptions only - never the conduit itself - so discovering topology through a viewer can never hand back a live runtime object to act through. Creating helpers on demand rather than caching bound state is what keeps them honest across an ACL refresh - a cached helper would answer from the projection it was born with, after that projection had been replaced.

AGENT_ACCESS: public

AGENT_PURPOSE:

access: public. Conduit-local helper surface for conduit identity, inventory, relationships, crosswalks, and conduit-to-spell views inside one selected frame.

cleanup() → None

Idempotently drop the borrowed frame-helper reference.

Contract:

• Safe to call more than once.

• Runs grouped teardown under the helper-owned instance lock.

Returns:

None.

list_conduits(*, frame_name: str | None = None) → List[FrameLink]

Return the currently visible conduit links for the selected frame.

Contract:

• Delegates visibility decisions to the borrowed frame helper and its compiled ACL surface.

• Returns a fresh link snapshot for this call.

Parameters:

frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Returns:

Conduit links for the selected frame.

Return type:

List[FrameLink]

describe_conduits(*, frame_name: str | None = None) → List[Dict[str, object]]

Return record-aware descriptions for every visible conduit.

Contract:

• Materializes one describe_conduit(...) result per currently visible conduit.

• Preserves the active ACL filtering on payload sections.

Parameters:

frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Returns:

Conduit descriptions.

Return type:

List[Dict[str, object]]

describe_conduit(conduit_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return a record-aware conduit description for one conduit.

Purpose:

Surface one ConduitRecord through the currently active ACL sections instead of only returning the flattened FrameLink metadata view.

Contract:

• Requires the conduit to be visible in the compiled ACL surface.

• Returns only the conduit payload sections currently visible for that conduit id.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Returns:

ACL-filtered conduit description.

Return type:

Dict[str, object]

list_conduit_spells(conduit_id: str, *, frame_name: str | None = None) → List[FrameLink]

Return the ACL-visible spells owned by one conduit.

Purpose:

Give the viewer operator a direct conduit-to-spell traversal path instead of forcing a full spell scan and manual filtering.

Contract:

• Spells owned by ONE conduit and visible to this rift - a double filter, so a short list can mean restricted visibility rather than few spells.

• VISIBILITY-FILTERED PROJECTION: absence means "not visible to this rift" OR "not present", indistinguishable from outside.

• frame_name is an ASSERTION, not a selector - when supplied it must match the bound frame or the call raises.

Threading:

Reads a descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the viewer is unbound or cleaned, or frame_name does not match the bound frame.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Returns:

ACL-visible spells owned by the conduit.

Return type:

List[FrameLink]

describe_conduit_topology(conduit_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return the visible topology around one conduit.

Purpose:

Show the conduit's peer links plus the visible spells currently owned by that conduit in one compact description.

Contract:

• Places the conduit in the tree. Like all projection topology, it can appear truncated when intermediate conduits are invisible here.

• VISIBILITY-FILTERED PROJECTION: absence means "not visible to this rift" OR "not present", indistinguishable from outside.

• frame_name is an ASSERTION, not a selector - when supplied it must match the bound frame or the call raises.

Threading:

Reads a descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the viewer is unbound or cleaned, or frame_name does not match the bound frame.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Returns:

Visible conduit topology summary.

Return type:

Dict[str, object]

describe_conduit_brief(conduit_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return one compact operator-oriented conduit summary.

Purpose:

Give the operator a smaller "start here" conduit summary than the richer inventory and relationship methods.

Contract:

• Summary rather than inventory; cheap enough for polling.

• VISIBILITY-FILTERED PROJECTION: absence means "not visible to this rift" OR "not present", indistinguishable from outside.

• frame_name is an ASSERTION, not a selector - when supplied it must match the bound frame or the call raises.

Threading:

Reads a descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the viewer is unbound or cleaned, or frame_name does not match the bound frame.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Returns:

Compact conduit summary.

Return type:

Dict[str, object]

describe_conduit_missing_sections(conduit_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return the conduit payload sections not currently visible.

Purpose:

Make the conduit-local "what is hidden?" answer explicit instead of forcing the operator to infer it from missing payload keys.

Contract:

• THE WITHHELD-SECTION PROBE for conduits: reports the NAMES of payload sections you cannot read, which is how you tell "hidden" from "empty".

• VISIBILITY-FILTERED PROJECTION: absence means "not visible to this rift" OR "not present", indistinguishable from outside.

• frame_name is an ASSERTION, not a selector - when supplied it must match the bound frame or the call raises.

Threading:

Reads a descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the viewer is unbound or cleaned, or frame_name does not match the bound frame.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Returns:

Missing conduit-section summary.

Return type:

Dict[str, object]

describe_conduit_crosswalk(conduit_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return the related visible objects around one conduit.

Purpose:

Give the operator one direct conduit crosswalk from the conduit to its root, peers, owned spells, and frame context.

Contract:

• Cross-references the conduit against its root and peers, so it answers placement rather than contents.

• VISIBILITY-FILTERED PROJECTION: absence means "not visible to this rift" OR "not present", indistinguishable from outside.

• frame_name is an ASSERTION, not a selector - when supplied it must match the bound frame or the call raises.

Threading:

Reads a descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the viewer is unbound or cleaned, or frame_name does not match the bound frame.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Returns:

Conduit crosswalk summary.

Return type:

Dict[str, object]

describe_conduit_inventory(conduit_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return a compact inventory summary for one conduit.

Purpose:

Give the operator one quick conduit-local inventory view covering owned spells, peer links, and visible payload sections.

Contract:

• Counts and lists what the conduit holds, all of it visibility-filtered.

• VISIBILITY-FILTERED PROJECTION: absence means "not visible to this rift" OR "not present", indistinguishable from outside.

• frame_name is an ASSERTION, not a selector - when supplied it must match the bound frame or the call raises.

Threading:

Reads a descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the viewer is unbound or cleaned, or frame_name does not match the bound frame.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Returns:

Compact conduit inventory summary.

Return type:

Dict[str, object]

describe_conduit_relationships(conduit_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return the visible relationship posture for one conduit.

Purpose:

Make the conduit's root grouping, peer links, and owned visible spells explicit in one relationship-oriented view.

Contract:

• Reports links and peers as this rift can see them; an invisible peer is simply absent, so this is not a reliable peer count.

• VISIBILITY-FILTERED PROJECTION: absence means "not visible to this rift" OR "not present", indistinguishable from outside.

• frame_name is an ASSERTION, not a selector - when supplied it must match the bound frame or the call raises.

Threading:

Reads a descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the viewer is unbound or cleaned, or frame_name does not match the bound frame.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Returns:

Visible conduit relationship summary.

Return type:

Dict[str, object]

compare_conduits(left_conduit_id: str, right_conduit_id: str, *, frame_name: str | None = None) → Dict[str, object]

Compare two visible conduits inside the bound frame.

Contract:

• BOTH conduits must be visible; an invisible operand raises rather than producing a partial comparison.

• THE RESULT MIXES TWO FILTERING REGIMES, and this matters when interpreting it:

  • visible_spell_source_ids compares the VISIBILITY-FILTERED spell lists, so it describes what this rift can see.

  • peer_conduit_ids compares the RAW RECORDED peer lists straight off each payload, WITHOUT the visibility intersection that list_peer_conduit_ids applies.

  A peer difference reported here can therefore involve conduits this rift cannot otherwise see, and will not match what list_peer_conduit_ids returns for the same conduits.

• same_policy normalizes policy names before comparing, so it is case-insensitive; same_conduit_state compares state .name values directly.

• same_root_conduit_id compares recorded root ids, which may name a conduit that is not visible here.

• Pure comparison: it reports differences and never reconciles them.

Threading:

Reads a descriptor snapshot through the borrowed frame view; the two operands are not read atomically with respect to each other.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The frame view is BORROWED, not owned.

Parameters:

• left_conduit_id -- Left visible conduit id.

• right_conduit_id -- Right visible conduit id.

• frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Returns:

Visible conduit comparison summary.

Return type:

Dict[str, object]

Raises:

RuntimeError -- If either conduit is not visible, the viewer is unbound or cleaned, or frame_name does not match the bound frame.

list_root_conduits(*, frame_name: str | None = None) → List[FrameLink]

Return visible conduit links that are root conduits.

Parameters:

frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Contract:

• Roots as seen THROUGH THIS RIFT. A conduit can appear to be a root purely because its real parent is not visible here, so root-ness in a projection is a visibility statement, not frame topology.

• VISIBILITY-FILTERED PROJECTION over the bound frame view. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof of non-existence.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises; it cannot be used to look at another frame.

• Read-only snapshot taken at call time; it does not mutate frame state and does not stay live as the frame changes.

Threading:

Reads a descriptor snapshot through the borrowed frame view; concurrent frame changes are not reflected in a returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The frame view is BORROWED, not owned - cleaning this viewer does not clean it.

Raises:

RuntimeError -- If the viewer is unbound or cleaned, or frame_name does not match the bound frame.

Returns:

Visible root conduit links.

Return type:

List[FrameLink]

is_root_conduit(conduit_id: str, *, frame_name: str | None = None) → bool

Return whether one visible conduit is its own root.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Contract:

• Compares the record's root_conduit_id against its own id, so it answers "is this its own root" rather than "is this the top of the tree you can see".

• RAISES when the conduit is not visible, rather than returning False. A False answer therefore always means "visible and not a root".

• VISIBILITY-FILTERED PROJECTION over the bound frame view. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof of non-existence.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises; it cannot be used to look at another frame.

• Read-only snapshot taken at call time; it does not mutate frame state and does not stay live as the frame changes.

Threading:

Reads a descriptor snapshot through the borrowed frame view; concurrent frame changes are not reflected in a returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The frame view is BORROWED, not owned - cleaning this viewer does not clean it.

Raises:

RuntimeError -- If the viewer is unbound or cleaned, or frame_name does not match the bound frame.

Returns:

True when the conduit is a root conduit.

Return type:

bool

get_root_conduit_id(conduit_id: str, *, frame_name: str | None = None) → str

Return the root conduit id for one visible conduit.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Contract:

• Returns the root id recorded on the conduit, which may name a conduit that is NOT VISIBLE to this rift. The returned id is not guaranteed to be resolvable through this viewer.

• VISIBILITY-FILTERED PROJECTION over the bound frame view. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof of non-existence.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises; it cannot be used to look at another frame.

• Read-only snapshot taken at call time; it does not mutate frame state and does not stay live as the frame changes.

Threading:

Reads a descriptor snapshot through the borrowed frame view; concurrent frame changes are not reflected in a returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The frame view is BORROWED, not owned - cleaning this viewer does not clean it.

Raises:

RuntimeError -- If the viewer is unbound or cleaned, or frame_name does not match the bound frame.

Returns:

Root conduit id for the conduit.

Return type:

str

list_conduits_by_root_id(root_conduit_id: str, *, frame_name: str | None = None) → List[FrameLink]

Return visible conduits grouped under one root conduit id.

Parameters:

• root_conduit_id -- Required root conduit id.

• frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Contract:

• A root matches its OWN id, so passing a root's id returns the whole tree INCLUDING that root, not just its descendants.

• Empty root_conduit_id is rejected up front.

• Matching is exact; no normalization is applied to the id.

• VISIBILITY-FILTERED PROJECTION over the bound frame view. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof of non-existence.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises; it cannot be used to look at another frame.

• Read-only snapshot taken at call time; it does not mutate frame state and does not stay live as the frame changes.

Threading:

Reads a descriptor snapshot through the borrowed frame view; concurrent frame changes are not reflected in a returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The frame view is BORROWED, not owned - cleaning this viewer does not clean it.

Raises:

RuntimeError -- If the viewer is unbound or cleaned, or frame_name does not match the bound frame.

Returns:

Visible conduits whose root lineage matches.

Return type:

List[FrameLink]

list_conduits_by_policy(policy_name: str, *, frame_name: str | None = None) → List[FrameLink]

Return visible conduits with one conduit policy value.

Parameters:

• policy_name -- Required conduit policy name.

• frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Contract:

• CASE-INSENSITIVE. The supplied name and the record's policy are both normalized before comparison, so "BLOCK_ALL" and "block_all" match.

• Empty policy_name is rejected up front.

• An unknown policy name is not an error - it simply matches nothing.

• VISIBILITY-FILTERED PROJECTION over the bound frame view. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof of non-existence.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises; it cannot be used to look at another frame.

• Read-only snapshot taken at call time; it does not mutate frame state and does not stay live as the frame changes.

Threading:

Reads a descriptor snapshot through the borrowed frame view; concurrent frame changes are not reflected in a returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The frame view is BORROWED, not owned - cleaning this viewer does not clean it.

Raises:

RuntimeError -- If the viewer is unbound or cleaned, or frame_name does not match the bound frame.

Returns:

Visible conduits whose payload policy matches.

Return type:

List[FrameLink]

list_conduits_by_state(state_name: str, *, frame_name: str | None = None) → List[FrameLink]

Return visible conduits with one conduit-state value.

Parameters:

• state_name -- Required conduit-state name.

• frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Contract:

• CASE-INSENSITIVE against the conduit state's .name, so "CLEANED" and "cleaned" match.

• Empty state_name is rejected up front.

• An unknown state name is not an error - it simply matches nothing.

• VISIBILITY-FILTERED PROJECTION over the bound frame view. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof of non-existence.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises; it cannot be used to look at another frame.

• Read-only snapshot taken at call time; it does not mutate frame state and does not stay live as the frame changes.

Threading:

Reads a descriptor snapshot through the borrowed frame view; concurrent frame changes are not reflected in a returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The frame view is BORROWED, not owned - cleaning this viewer does not clean it.

Raises:

RuntimeError -- If the viewer is unbound or cleaned, or frame_name does not match the bound frame.

Returns:

Visible conduits whose payload state matches.

Return type:

List[FrameLink]

list_peer_conduits(conduit_id: str, *, frame_name: str | None = None) → List[FrameLink]

Return visible peer conduit links for one conduit.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Contract:

• Built from list_peer_conduit_ids, so it inherits that method's visibility intersection: peers invisible to this rift are absent from the result.

• VISIBILITY-FILTERED PROJECTION over the bound frame view. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof of non-existence.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises; it cannot be used to look at another frame.

• Read-only snapshot taken at call time; it does not mutate frame state and does not stay live as the frame changes.

Threading:

Reads a descriptor snapshot through the borrowed frame view; concurrent frame changes are not reflected in a returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The frame view is BORROWED, not owned - cleaning this viewer does not clean it.

Raises:

RuntimeError -- If the viewer is unbound or cleaned, or frame_name does not match the bound frame.

Returns:

Visible peer conduit links.

Return type:

List[FrameLink]

list_peer_conduit_ids(conduit_id: str, *, frame_name: str | None = None) → Tuple[str, ...]

Return visible peer conduit ids for one conduit.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Contract:

• INTERSECTED WITH VISIBILITY. The conduit's recorded peer list is filtered down to peers this rift can see, so the result can be SHORTER than the conduit's real peer count and an empty tuple does not mean the conduit is unpaired.

• Never use the length of this tuple as a peer count.

• VISIBILITY-FILTERED PROJECTION over the bound frame view. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof of non-existence.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises; it cannot be used to look at another frame.

• Read-only snapshot taken at call time; it does not mutate frame state and does not stay live as the frame changes.

Threading:

Reads a descriptor snapshot through the borrowed frame view; concurrent frame changes are not reflected in a returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The frame view is BORROWED, not owned - cleaning this viewer does not clean it.

Raises:

RuntimeError -- If the viewer is unbound or cleaned, or frame_name does not match the bound frame.

Returns:

Visible peer conduit ids in deterministic order.

Return type:

Tuple[str, ...]

list_spell_source_ids_for_conduit(conduit_id: str, *, frame_name: str | None = None) → Tuple[str, ...]

Return visible spell source ids owned by one conduit.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Contract:

• Covers only spells this rift can see AND that this conduit owns, so it is a double filter - ownership and visibility both narrow it.

• VISIBILITY-FILTERED PROJECTION over the bound frame view. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof of non-existence.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises; it cannot be used to look at another frame.

• Read-only snapshot taken at call time; it does not mutate frame state and does not stay live as the frame changes.

Threading:

Reads a descriptor snapshot through the borrowed frame view; concurrent frame changes are not reflected in a returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The frame view is BORROWED, not owned - cleaning this viewer does not clean it.

Raises:

RuntimeError -- If the viewer is unbound or cleaned, or frame_name does not match the bound frame.

Returns:

Visible spell source ids owned by the conduit.

Return type:

Tuple[str, ...]

list_binding_names_for_conduit(conduit_id: str, *, frame_name: str | None = None) → Tuple[str, ...]

Return visible spell binding names owned by one conduit.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Contract:

• SKIPS spells with no binding name, so the result is SHORTER than the conduit's visible spell list and is NOT positionally aligned with list_spell_names_for_conduit. Do not zip the two.

• VISIBILITY-FILTERED PROJECTION over the bound frame view. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof of non-existence.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises; it cannot be used to look at another frame.

• Read-only snapshot taken at call time; it does not mutate frame state and does not stay live as the frame changes.

Threading:

Reads a descriptor snapshot through the borrowed frame view; concurrent frame changes are not reflected in a returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The frame view is BORROWED, not owned - cleaning this viewer does not clean it.

Raises:

RuntimeError -- If the viewer is unbound or cleaned, or frame_name does not match the bound frame.

Returns:

Visible binding names owned by the conduit.

Return type:

Tuple[str, ...]

list_spell_names_for_conduit(conduit_id: str, *, frame_name: str | None = None) → Tuple[str, ...]

Return visible spell names owned by one conduit.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Contract:

• NOT deduplicated and positionally aligned with the conduit's visible spell links, unlike list_binding_names_for_conduit which skips entries.

• VISIBILITY-FILTERED PROJECTION over the bound frame view. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof of non-existence.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises; it cannot be used to look at another frame.

• Read-only snapshot taken at call time; it does not mutate frame state and does not stay live as the frame changes.

Threading:

Reads a descriptor snapshot through the borrowed frame view; concurrent frame changes are not reflected in a returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The frame view is BORROWED, not owned - cleaning this viewer does not clean it.

Raises:

RuntimeError -- If the viewer is unbound or cleaned, or frame_name does not match the bound frame.

Returns:

Visible spell names owned by the conduit.

Return type:

Tuple[str, ...]

describe_conduit_access_summary(conduit_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return one compact access/inventory summary for a conduit.

Purpose:

Combine the conduit access explanation, relationship view, and compact inventory so the operator can decide quickly whether to go deeper on that conduit.

Contract:

• COMPOSITE of identity and access posture in one call; costs more than any single component because it fans out.

• VISIBILITY-FILTERED PROJECTION: absence means "not visible to this rift" OR "not present", indistinguishable from outside.

• frame_name is an ASSERTION, not a selector - when supplied it must match the bound frame or the call raises.

Threading:

Reads a descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the viewer is unbound or cleaned, or frame_name does not match the bound frame.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Returns:

Compact conduit access summary.

Return type:

Dict[str, object]

find_conduit_by_name(conduit_name: str, *, frame_name: str | None = None) → List[FrameLink]

Return visible conduits whose display name matches exactly.

Parameters:

• conduit_name -- Exact conduit display name.

• frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Contract:

• EXACT, case-sensitive match on display name - unlike the policy and state listers, which normalize case.

• Returns a LIST because display names are not unique; more than one visible conduit may carry the same name.

• Empty conduit_name is rejected up front.

• VISIBILITY-FILTERED PROJECTION over the bound frame view. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof of non-existence.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises; it cannot be used to look at another frame.

• Read-only snapshot taken at call time; it does not mutate frame state and does not stay live as the frame changes.

Threading:

Reads a descriptor snapshot through the borrowed frame view; concurrent frame changes are not reflected in a returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The frame view is BORROWED, not owned - cleaning this viewer does not clean it.

Raises:

RuntimeError -- If the viewer is unbound or cleaned, or frame_name does not match the bound frame.

Returns:

Matching visible conduit links.

Return type:

List[FrameLink]

explain_conduit_access(conduit_id: str, *, frame_name: str | None = None) → Dict[str, object]

Explain the effective ACL access posture for one conduit.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Contract:

• Explains the ACL posture for a conduit and augments the frame-level explanation with a payload_visible verdict derived from the returned visible sections.

• This is the honest way to distinguish "absent" from "hidden", which the plain listers cannot express.

• VISIBILITY-FILTERED PROJECTION over the bound frame view. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof of non-existence.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises; it cannot be used to look at another frame.

• Read-only snapshot taken at call time; it does not mutate frame state and does not stay live as the frame changes.

Threading:

Reads a descriptor snapshot through the borrowed frame view; concurrent frame changes are not reflected in a returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The frame view is BORROWED, not owned - cleaning this viewer does not clean it.

Raises:

RuntimeError -- If the viewer is unbound or cleaned, or frame_name does not match the bound frame.

Returns:

Conduit visibility and section explanation.

Return type:

Dict[str, object]

get_conduit_payload_field(conduit_id: str, field_name: str, *, frame_name: str | None = None) → object

Return one ACL-visible conduit payload field or raise.

Parameters:

• conduit_id -- Published conduit id.

• field_name -- Required conduit payload field name.

• frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Contract:

• ACL-GATED FIELD READ. The field is returned only when its section is in the conduit's visible sections; an invisible section raises rather than returning None, so a value of None always means a real None.

• Empty field_name is rejected up front.

• VISIBILITY-FILTERED PROJECTION over the bound frame view. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof of non-existence.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises; it cannot be used to look at another frame.

• Read-only snapshot taken at call time; it does not mutate frame state and does not stay live as the frame changes.

Threading:

Reads a descriptor snapshot through the borrowed frame view; concurrent frame changes are not reflected in a returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The frame view is BORROWED, not owned - cleaning this viewer does not clean it.

Raises:

RuntimeError -- If the viewer is unbound or cleaned, or frame_name does not match the bound frame.

Returns:

ACL-visible conduit payload field value.

Return type:

object

get_required_conduit(conduit_id: str, *, frame_name: str | None = None) → FrameLink

Return one conduit link by conduit id or raise.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional frame-name assertion passed through to the selected- frame helper.

Contract:

• RAISES rather than returning None, which is the distinction from the find/list siblings.

• The raise is AMBIGUOUS between "no such conduit" and "exists but not visible to this rift"; do not treat it as proof of non-existence.

• Empty conduit_id is rejected up front.

• VISIBILITY-FILTERED PROJECTION over the bound frame view. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof of non-existence.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises; it cannot be used to look at another frame.

• Read-only snapshot taken at call time; it does not mutate frame state and does not stay live as the frame changes.

Threading:

Reads a descriptor snapshot through the borrowed frame view; concurrent frame changes are not reflected in a returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The frame view is BORROWED, not owned - cleaning this viewer does not clean it.

Raises:

RuntimeError -- If the viewer is unbound or cleaned, or frame_name does not match the bound frame.

Returns:

Matching conduit link.

Return type:

FrameLink

Topic reference · Full contents