On this page

• FrameViewer
  • FrameViewer
    • FrameViewer.cleanup()
    • FrameViewer.id
    • FrameViewer.list_frame_names()
    • FrameViewer.list_linked_frame_names()
    • FrameViewer.list_nexus_frame_names()
    • FrameViewer.list_non_nexus_frame_names()
    • FrameViewer.count_frames()
    • FrameViewer.describe_available_views()
    • FrameViewer.count_root_conduits()
    • FrameViewer.count_spell_records()
    • FrameViewer.describe_frame()
    • FrameViewer.describe_frames()
    • FrameViewer.describe_frame_brief()
    • FrameViewer.describe_host_inventory()
    • FrameViewer.describe_viewer()
    • FrameViewer.describe_frames_inventory()
    • FrameViewer.describe_viewer_method_surface()
    • FrameViewer.compare_frames()
    • FrameViewer.compare_frames_brief()
    • FrameViewer.compare_frame_conduits()
    • FrameViewer.compare_frame_spells()
    • FrameViewer.describe_binding_name_collisions()
    • FrameViewer.describe_spell_name_collisions()
    • FrameViewer.describe_index_groups()
    • FrameViewer.describe_spellframe_groups()
    • FrameViewer.describe_spellbook_permission_mismatches()
    • FrameViewer.describe_spellbook_existence_mismatches()
    • FrameViewer.compare_spell_records()
    • FrameViewer.compare_conduit_records()
    • FrameViewer.list_spell_source_ids_for_frame()
    • FrameViewer.list_frame_ids()
    • FrameViewer.list_nexus_contracts()
    • FrameViewer.count_conduit_records()
    • FrameViewer.list_conduit_record_ids()
    • FrameViewer.list_root_conduit_ids()
    • FrameViewer.count_spellbooks()
    • FrameViewer.list_origin_spellbook_ids()
    • FrameViewer.list_spell_record_ids()
    • FrameViewer.list_spell_record_keys()
    • FrameViewer.list_spell_names()
    • FrameViewer.list_binding_names()
    • FrameViewer.list_index_ids()
    • FrameViewer.list_spellframes()
    • FrameViewer.list_permissions()
    • FrameViewer.list_existence_kinds()
    • FrameViewer.describe_descriptor_inventory()
    • FrameViewer.describe_descriptor_topology()
    • FrameViewer.describe_conduit_records()
    • FrameViewer.describe_spell_records()
    • FrameViewer.describe_spell_record()
    • FrameViewer.list_spells_by_owner_conduit()
    • FrameViewer.list_spells_by_spellbook_id()
    • FrameViewer.list_spells_by_permission()
    • FrameViewer.list_spells_by_existence()
    • FrameViewer.list_spells_by_spellframe()
    • FrameViewer.clone()
    • FrameViewer.get_view_frame()
    • FrameViewer.get_view_conduit()
    • FrameViewer.get_view_spell()
    • FrameViewer.get_view_multiframe()
    • FrameViewer.list_viewer_method_names_ast_json()
    • FrameViewer.describe_agent_onboarding_json()
    • FrameViewer.describe_viewer_agent_purpose_json()
    • FrameViewer.describe_viewer_class_surface_ast_json()
    • FrameViewer.describe_visible_surface()
    • FrameViewer.describe_missing_surface()
    • FrameViewer.describe_frame_brief_local()
    • FrameViewer.describe_visible_inventory_by_kind()
    • FrameViewer.describe_frame_topology()
    • FrameViewer.list_visible_target_ids()
    • FrameViewer.list_visible_target_ids_by_kind()
    • FrameViewer.list_visible_conduit_ids()
    • FrameViewer.list_visible_spell_source_ids()
    • FrameViewer.list_visible_root_conduits()
    • FrameViewer.list_visible_binding_names()
    • FrameViewer.list_visible_spell_names()
    • FrameViewer.list_visible_spellframes()
    • FrameViewer.list_visible_index_ids()
    • FrameViewer.describe_visible_spell_ownership()
    • FrameViewer.describe_visible_conduit_tree()
    • FrameViewer.search_targets_contains()
    • FrameViewer.search_targets_prefix()
    • FrameViewer.group_targets_by_kind()
    • FrameViewer.describe_target_brief()
    • FrameViewer.describe_target_identity()
    • FrameViewer.describe_visible_collisions()
    • FrameViewer.describe_frame_payload()
    • FrameViewer.describe_frame_inventory()
    • FrameViewer.describe_frame_access_contract()
    • FrameViewer.get_frame_payload_field()
    • FrameViewer.find_target_by_display_name()
    • FrameViewer.explain_target_access()
    • FrameViewer.list_targets()
    • FrameViewer.describe_targets()
    • FrameViewer.list_conduits()
    • FrameViewer.list_root_conduits()
    • FrameViewer.describe_conduits()
    • FrameViewer.get_conduit()
    • FrameViewer.describe_conduit()
    • FrameViewer.describe_conduit_brief()
    • FrameViewer.describe_conduit_inventory()
    • FrameViewer.describe_conduit_relationships()
    • FrameViewer.describe_conduit_missing_sections()
    • FrameViewer.describe_conduit_crosswalk()
    • FrameViewer.list_conduit_spells()
    • FrameViewer.describe_conduit_topology()
    • FrameViewer.compare_conduits()
    • FrameViewer.is_root_conduit()
    • FrameViewer.get_root_conduit_id()
    • FrameViewer.list_conduits_by_root_id()
    • FrameViewer.list_conduits_by_policy()
    • FrameViewer.list_conduits_by_state()
    • FrameViewer.list_peer_conduits()
    • FrameViewer.list_peer_conduit_ids()
    • FrameViewer.list_spell_source_ids_for_conduit()
    • FrameViewer.list_binding_names_for_conduit()
    • FrameViewer.list_spell_names_for_conduit()
    • FrameViewer.describe_conduit_access_summary()
    • FrameViewer.find_conduit_by_name()
    • FrameViewer.explain_conduit_access()
    • FrameViewer.get_conduit_payload_field()
    • FrameViewer.list_spells()
    • FrameViewer.describe_spells()
    • FrameViewer.get_spell()
    • FrameViewer.describe_spell()
    • FrameViewer.describe_spell_brief()
    • FrameViewer.describe_spell_origin()
    • FrameViewer.describe_spell_index()
    • FrameViewer.describe_spell_payload()
    • FrameViewer.describe_spell_detail()
    • FrameViewer.describe_spell_identity()
    • FrameViewer.describe_spell_binding()
    • FrameViewer.describe_spell_resolution()
    • FrameViewer.describe_spell_metadata()
    • FrameViewer.describe_spell_class_profile()
    • FrameViewer.describe_spell_callable_profile()
    • FrameViewer.describe_spell_instance_members()
    • FrameViewer.describe_spell_dynamic_access()
    • FrameViewer.list_spell_dunder_member_names()
    • FrameViewer.describe_spell_dunder_members()
    • FrameViewer.list_spells_by_payload_type()
    • FrameViewer.find_spell_by_binding_name()
    • FrameViewer.list_spells_by_index_id()
    • FrameViewer.list_spells_by_spell_name()
    • FrameViewer.search_spells_contains()
    • FrameViewer.search_spells_prefix()
    • FrameViewer.explain_spell_access()
    • FrameViewer.describe_spell_access_summary()
    • FrameViewer.get_spell_payload_section()
    • FrameViewer.describe_spell_missing_sections()
    • FrameViewer.describe_spell_crosswalk()
    • FrameViewer.compare_spells()

FrameViewer

Use md.FrameViewer from the public package namespace.

Implementation source

class FrameViewer(*, rift: Rift, action_hook_scope_factory: Callable[[...], Any] | None = None)

Purpose:

Hold one durable viewer asset that reads current frame truth from the Rift-owned projection bundle plus the viewer helper surfaces used to inspect that state.

Contract:

• Holds one borrowed Rift reference and reads current view projections from that owner on demand.

• Treats descriptor/config/surface state as Rift-owned, not viewer-owned.

• Owns the public viewer feature surface directly.

• Creates helper objects on demand for the view/frame/conduit/spell families rather than caching bound helper state on the viewer itself.

• Exposes descriptor-only multi-frame host methods directly on the viewer.

• Exposes frame-local ACL/payload-aware behavior through the viewer's helper surfaces without a separate profile layer or generic dispatch entrypoint.

• Does not expose raw runtime objects or any direct code-execution behavior.

Threading:

Uses one instance threading.RLock to serialize cleanup and multi-step viewer-state mutation and teardown.

Lifecycle:

Cleanup clears only viewer-owned references. It does not cleanup the owning Rift or any Rift-owned projection objects because those are borrowed runtime inputs.

Registration:

MELDER KERNEL. The one subclass, StaticFrameViewer, is melder-internal and created by static rooms during room init; no injection seam exists.

Subsystem Context:

The READ surface of a room, opposite CommandSystem (the mediated action surface) and Workstation (the binding canvas). It creates view/frame/conduit/spell helper objects ON DEMAND rather than caching bound helper state, which is what keeps it truthful when projections refresh underneath it.

System Context:

This class is a VIEW, not a cache, and that is the whole design. It holds a borrowed Rift reference and reads current projections from it on demand; descriptor, config, and surface state are Rift-owned. A viewer that cached projections would answer confidently with stale truth after an ACL change, which is precisely the failure the Nexus refresh fan-out exists to prevent. The final contract line is the security boundary: it exposes NO raw runtime objects and NO direct code execution. Everything reachable through a viewer is a projection, so a read can never become a write. That is what makes the viewer safe to hand to a static room and to agents. Cleanup mirrors the borrow: it clears viewer-owned references ONLY and never touches the owning Rift or its projection objects, because those are borrowed inputs whose lifetime belongs to someone else.

AGENT_ACCESS: public

AGENT_PURPOSE:

access: public. Multi-frame descriptor host for the Rift viewer path. Use this object to inspect hosted frames, compare descriptor records, and call the explicit viewer methods for frame-local behavior.

cleanup() → None

Idempotently clear viewer-owned state.

Contract:

• Safe to call more than once.

• Clears only viewer-owned references.

• Does not cleanup the owning Rift because the viewer borrows that runtime object.

Returns:

None.

property id: str

Return the stable viewer identifier.

Contract:

• Identifies THIS VIEWER OBJECT, not the rift and not the frame. A new viewer over the same rift carries a different id.

• Assigned at construction and stable for the object's life.

Threading:

Unsynchronized read of a write-once slot; safe from any thread.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the viewer has been cleaned.

Returns:

Stable viewer id.

Return type:

str

list_frame_names() → List[str]

Return the currently linked frame names in deterministic order.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.list_frame_names(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_multiframe() constructs a new ViewMultiFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: the multi-frame helper is not bound to a single frame, so no frame selection happens here.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Sorted linked frame names.

Return type:

List[str]

list_linked_frame_names() → List[str]

Return the currently linked frame names in deterministic order.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.list_linked_frame_names(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_multiframe() constructs a new ViewMultiFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: the multi-frame helper is not bound to a single frame, so no frame selection happens here.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Sorted linked frame names.

Return type:

List[str]

list_nexus_frame_names() → List[str]

Return the currently accessible Nexus-managed frame names.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.list_nexus_frame_names(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_multiframe() constructs a new ViewMultiFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: the multi-frame helper is not bound to a single frame, so no frame selection happens here.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Sorted accessible Nexus-managed frame names.

Return type:

List[str]

list_non_nexus_frame_names() → List[str]

Return the currently accessible published non-Nexus frame names.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.list_non_nexus_frame_names(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_multiframe() constructs a new ViewMultiFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: the multi-frame helper is not bound to a single frame, so no frame selection happens here.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Sorted accessible published non-Nexus frame names.

Return type:

List[str]

count_frames() → int

Return the number of hosted frame descriptors.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.count_frames(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_multiframe() constructs a new ViewMultiFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: the multi-frame helper is not bound to a single frame, so no frame selection happens here.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Hosted frame count.

Return type:

int

describe_available_views() → List[Dict[str, object]]

Return a simple host-level description of the hosted frames.

Contract:

This is a host-only descriptor surface. It does not expose payload data or ACL-shaped visibility details.

Contract:

• Lists ONLY frame names, one single-key dict per reachable frame. It is a directory of what can be viewed, not a description of any frame's contents - use the ViewFrame helpers for that.

• Scoped to the rift's reachable frames, so a frame absent here is invisible to this viewer entirely.

• The single-key dict shape is deliberate: it leaves room for more fields without changing the return type.

Returns:

Hosted frame descriptions.

Return type:

List[Dict[str, object]]

count_root_conduits(*, frame_name: str | None = None) → int

Return the number of root conduit records.

Parameters:

frame_name -- Optional frame name. When omitted, counts across all hosted frames.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.count_root_conduits(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_multiframe() constructs a new ViewMultiFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: the multi-frame helper is not bound to a single frame, so no frame selection happens here.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Root conduit record count.

Return type:

int

count_spell_records(*, frame_name: str | None = None) → int

Return the number of spell records.

Parameters:

frame_name -- Optional frame name. When omitted, counts across all hosted frames.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.count_spell_records(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_multiframe() constructs a new ViewMultiFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: the multi-frame helper is not bound to a single frame, so no frame selection happens here.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Spell record count.

Return type:

int

describe_frame(frame_name: str) → Dict[str, object]

Return a descriptor-level summary for one hosted frame.

Contract:

This host-level summary is limited to descriptor structure and published record identity. It does not expose payload bodies or ACL-shaped payload visibility.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.describe_frame(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_multiframe() constructs a new ViewMultiFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: no frame selection happens here.

Parameters:

frame_name -- Hosted frame name to summarize.

Returns:

Descriptor-level frame summary.

Return type:

Dict[str, object]

describe_frames() → Dict[str, Dict[str, object]]

Return descriptor-level summaries for all hosted frames.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.describe_frames(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_multiframe() constructs a new ViewMultiFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: the multi-frame helper is not bound to a single frame, so no frame selection happens here.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Hosted frame summaries keyed by frame name.

Return type:

Dict[str, Dict[str, object]]

describe_frame_brief(frame_name: str) → Dict[str, object]

Return one compact descriptor-level frame summary.

Purpose:

Give the operator a smaller "start here" frame summary than describe_frame(...) while staying entirely on descriptor-owned host data.

Contract:

• Uses only descriptor/record identity and count data.

• Does not expose payload bodies or ACL-shaped visibility details.

• Always includes the frame's Nexus contract and top-level record counts.

Parameters:

frame_name -- Hosted frame name to summarize.

Returns:

Compact descriptor-level frame summary.

Return type:

Dict[str, object]

describe_host_inventory() → Dict[str, object]

Return one compact host-level inventory summary.

Purpose:

Give the operator a quick overview of what the FrameViewer host is carrying without forcing a deeper descriptor walk.

Contract:

• Aggregates only descriptor-owned counts, names, and record-level identities.

• Does not expose payload bodies or ACL-shaped detail.

Returns:

Compact host-level inventory summary.

Return type:

Dict[str, object]

describe_viewer() → Dict[str, object]

Return one compact summary of the FrameViewer host itself.

Purpose:

Give the operator one host-level summary of what this viewer is currently carrying without walking frame-local helper surfaces.

Contract:

• Returns host identity, default routing state, and descriptor-only inventory posture.

• Does not expose payload bodies, ACL-shaped data, or frame-local helper output.

Returns:

Compact host summary for this viewer.

Return type:

Dict[str, object]

describe_frames_inventory() → Dict[str, Dict[str, object]]

Return one compact per-frame descriptor inventory summary.

Purpose:

Give the operator a small inventory table across hosted frames without exposing anything deeper than descriptor-owned counts and stable record identity.

Contract:

• Multi-frame output stays shallow and descriptor-only.

• Does not expose payload bodies or ACL-shaped visibility detail.

• Includes only per-frame counts and stable host identity fields.

Returns:

Per-frame compact inventories keyed by frame name.

Return type:

Dict[str, Dict[str, object]]

describe_viewer_method_surface() → Dict[str, object]

Return one curated summary of the host-side viewer method surface.

Purpose:

Explain how to use the FrameViewer host without forcing the operator to read the raw AST-described class surface first.

Contract:

• Describes only the curated host-side method groups.

• Keeps the host boundary explicit: descriptor-oriented viewer methods on the host, with explicit helper-backed methods exposed directly on the viewer surface.

Returns:

Curated host method-surface summary.

Return type:

Dict[str, object]

compare_frames(left_frame_name: str, right_frame_name: str) → Dict[str, object]

Compare two hosted frame descriptors at the record-identity level.

Purpose:

Give the operator one descriptor-only diff between two hosted frames so they can see what differs without manually comparing the individual host list methods.

Contract:

• Uses descriptor-owned identities, counts, and normalized values only.

• Does not expose payload bodies or ACL-shaped detail.

• Returns shared sets plus left-only/right-only deltas for the most important descriptor-level inventories.

Parameters:

• left_frame_name -- Left hosted frame name.

• right_frame_name -- Right hosted frame name.

Returns:

Descriptor-level comparison summary.

Return type:

Dict[str, object]

compare_frames_brief(left_frame_name: str, right_frame_name: str) → Dict[str, object]

Return one compact descriptor-only comparison summary for two frames.

Purpose:

Provide a smaller "what materially differs?" answer than the full compare_frames(...) payload.

Contract:

• Uses only descriptor-level comparison data derived from the full frame comparison.

• Keeps multi-frame output shallow and count-focused.

Parameters:

• left_frame_name -- Left hosted frame name.

• right_frame_name -- Right hosted frame name.

Returns:

Compact descriptor-level frame comparison.

Return type:

Dict[str, object]

compare_frame_conduits(left_frame_name: str, right_frame_name: str) → Dict[str, object]

Compare the conduit-record inventories of two hosted frames.

Parameters:

• left_frame_name -- Left hosted frame name.

• right_frame_name -- Right hosted frame name.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.compare_frame_conduits(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_multiframe() constructs a new ViewMultiFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: the multi-frame helper is not bound to a single frame, so no frame selection happens here.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Conduit-record comparison summary.

Return type:

Dict[str, object]

compare_frame_spells(left_frame_name: str, right_frame_name: str) → Dict[str, object]

Compare the spell-record inventories of two hosted frames.

Parameters:

• left_frame_name -- Left hosted frame name.

• right_frame_name -- Right hosted frame name.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.compare_frame_spells(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_multiframe() constructs a new ViewMultiFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: the multi-frame helper is not bound to a single frame, so no frame selection happens here.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Spell-record comparison summary.

Return type:

Dict[str, object]

describe_binding_name_collisions(*, frame_name: str | None = None) → Dict[str, Tuple[str, ...]]

Return binding-name collisions in the selected descriptor scope.

Purpose:

Surface visible ambiguity at the record-identity level when the same binding name is attached to multiple published spell records.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.describe_binding_name_collisions(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_multiframe() constructs a new ViewMultiFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: no frame selection happens here.

Parameters:

frame_name -- Optional hosted frame name. When omitted, scans all hosted frames.

Returns:

Binding names mapped to the colliding spell source ids.

Return type:

Dict[str, Tuple[str, ...]]

describe_spell_name_collisions(*, frame_name: str | None = None) → Dict[str, Tuple[str, ...]]

Return spell-name collisions in the selected descriptor scope.

Parameters:

frame_name -- Optional hosted frame name. When omitted, scans all hosted frames.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.describe_spell_name_collisions(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_multiframe() constructs a new ViewMultiFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: the multi-frame helper is not bound to a single frame, so no frame selection happens here.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Spell names mapped to the colliding spell source ids.

Return type:

Dict[str, Tuple[str, ...]]

describe_index_groups(*, frame_name: str | None = None) → Dict[str, Tuple[str, ...]]

Return spell-index groups in the selected descriptor scope.

Purpose:

Surface all published spell source ids grouped by spell-index id, even when an index currently has only one visible member.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.describe_index_groups(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_multiframe() constructs a new ViewMultiFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: no frame selection happens here.

Parameters:

frame_name -- Optional hosted frame name. When omitted, scans all hosted frames.

Returns:

Spell-index ids mapped to published spell source ids.

Return type:

Dict[str, Tuple[str, ...]]

describe_spellframe_groups(*, frame_name: str | None = None) → Dict[str, Tuple[str, ...]]

Return spellframe groups in the selected descriptor scope.

Purpose:

Group published spells by normalized spellframe value so frame-wide spellframe overlaps are obvious.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.describe_spellframe_groups(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_multiframe() constructs a new ViewMultiFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: no frame selection happens here.

Parameters:

frame_name -- Optional hosted frame name. When omitted, scans all hosted frames.

Returns:

Spellframe values mapped to published spell source ids.

Return type:

Dict[str, Tuple[str, ...]]

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

Return spellbook groups whose permission posture is not uniform.

Parameters:

frame_name -- Optional hosted frame name. When omitted, scans all hosted frames.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.describe_spellbook_permission_mismatches(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_multiframe() constructs a new ViewMultiFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: the multi-frame helper is not bound to a single frame, so no frame selection happens here.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Spellbook ids mapped to permission mismatch summaries.

Return type:

Dict[str, Dict[str, object]]

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

Return spellbook groups whose existence posture is not uniform.

Parameters:

frame_name -- Optional hosted frame name. When omitted, scans all hosted frames.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.describe_spellbook_existence_mismatches(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_multiframe() constructs a new ViewMultiFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: the multi-frame helper is not bound to a single frame, so no frame selection happens here.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Spellbook ids mapped to existence mismatch summaries.

Return type:

Dict[str, Dict[str, object]]

compare_spell_records(left_spell_source_id: str, right_spell_source_id: str, *, left_frame_name: str | None = None, right_frame_name: str | None = None) → Dict[str, object]

Compare two published spell records.

Purpose:

Give the operator one record-level spell diff without requiring them to manually compare multiple identity, provenance, and posture methods.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.compare_spell_records(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_multiframe() constructs a new ViewMultiFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: no frame selection happens here.

Parameters:

• left_spell_source_id -- Left published spell source id.

• right_spell_source_id -- Right published spell source id.

• left_frame_name -- Optional hosted frame constraint for the left spell.

• right_frame_name -- Optional hosted frame constraint for the right spell.

Returns:

Record-level spell comparison summary.

Return type:

Dict[str, object]

compare_conduit_records(left_conduit_id: str, right_conduit_id: str, *, left_frame_name: str | None = None, right_frame_name: str | None = None) → Dict[str, object]

Compare two published conduit records.

Parameters:

• left_conduit_id -- Left published conduit id.

• right_conduit_id -- Right published conduit id.

• left_frame_name -- Optional hosted frame constraint for the left conduit.

• right_frame_name -- Optional hosted frame constraint for the right conduit.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.compare_conduit_records(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_multiframe() constructs a new ViewMultiFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: the multi-frame helper is not bound to a single frame, so no frame selection happens here.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Record-level conduit comparison summary.

Return type:

Dict[str, object]

list_spell_source_ids_for_frame(frame_name: str) → List[str]

Return spell source ids for one hosted frame.

Purpose:

Provide the canonical published spell identities for one hosted descriptor in deterministic order.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.list_spell_source_ids_for_frame(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_multiframe() constructs a new ViewMultiFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: no frame selection happens here.

Parameters:

frame_name -- Hosted frame name whose spell source ids should be returned.

Returns:

Spell source ids for the frame.

Return type:

List[str]

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

Return published frame ids for the selected descriptor scope.

Purpose:

Surface the stable published frame identifiers without exposing any payload body data.

Contract:

• Reads only FrameRecord identity fields.

• Returns ids in deterministic frame-order.

• Omits frames that do not currently expose a frame_overview record.

Parameters:

frame_name -- Optional hosted frame name. When omitted, returns frame ids across all hosted descriptors.

Returns:

Published frame ids in deterministic order.

Return type:

List[str]

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

Return the published Nexus dataset contracts for hosted frames.

Purpose:

Give the operator a direct host-level view of the record contracts currently attached to the selected descriptor scope.

Contract:

• Uses only record-level nexus_label / nexus_version.

• Does not expose payload body content.

• Returns one contract entry per frame that currently exposes a frame_overview record.

Parameters:

frame_name -- Optional hosted frame name. When omitted, returns contract entries across all hosted frames.

Returns:

Nexus contract entries in deterministic frame order.

Return type:

List[Dict[str, str]]

count_conduit_records(*, frame_name: str | None = None) → int

Return the number of published conduit records.

Purpose:

Surface conduit-record inventory at the descriptor host level without reaching into conduit payload bodies.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.count_conduit_records(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_multiframe() constructs a new ViewMultiFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: no frame selection happens here.

Parameters:

frame_name -- Optional hosted frame name. When omitted, counts conduit records across all hosted frames.

Returns:

Published conduit-record count.

Return type:

int

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

Return published conduit record ids for the selected scope.

Purpose:

Expose the conduit ids owned by the selected frame descriptor scope without surfacing payload details.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.list_conduit_record_ids(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_multiframe() constructs a new ViewMultiFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: no frame selection happens here.

Parameters:

frame_name -- Optional hosted frame name. When omitted, returns conduit ids across all hosted frames.

Returns:

Conduit ids in deterministic order.

Return type:

List[str]

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

Return root conduit ids for the selected descriptor scope.

Purpose:

Surface conduit-root topology at the host level using record identity only.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.list_root_conduit_ids(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_multiframe() constructs a new ViewMultiFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: no frame selection happens here.

Parameters:

frame_name -- Optional hosted frame name. When omitted, returns unique root conduit ids across all hosted frames.

Returns:

Deterministically sorted root conduit ids.

Return type:

List[str]

count_spellbooks(*, frame_name: str | None = None) → int

Return the number of distinct published origin spellbooks.

Purpose:

Surface spellbook provenance breadth at the descriptor host level.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.count_spellbooks(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_multiframe() constructs a new ViewMultiFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: no frame selection happens here.

Parameters:

frame_name -- Optional hosted frame name. When omitted, counts distinct spellbook ids across all hosted frames.

Returns:

Distinct origin spellbook count.

Return type:

int

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

Return distinct origin spellbook ids for the selected scope.

Purpose:

Expose the spellbook provenance ids attached to the hosted spell records.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.list_origin_spellbook_ids(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_multiframe() constructs a new ViewMultiFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: no frame selection happens here.

Parameters:

frame_name -- Optional hosted frame name. When omitted, returns distinct spellbook ids across all hosted frames.

Returns:

Distinct spellbook ids in deterministic order.

Return type:

List[str]

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

Return published spell record ids for the selected scope.

Purpose:

Expose spell ids directly from SpellRecord ownership without surfacing payload bodies.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.list_spell_record_ids(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_multiframe() constructs a new ViewMultiFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: no frame selection happens here.

Parameters:

frame_name -- Optional hosted frame name. When omitted, returns spell ids across all hosted frames.

Returns:

Spell ids in deterministic record order.

Return type:

List[str]

list_spell_record_keys(*, frame_name: str | None = None) → List[Tuple[str, str]]

Return canonical spell record keys for the selected scope.

Purpose:

Surface the exact (spellbook_id, spell_id) storage identities attached to the selected descriptors.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.list_spell_record_keys(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_multiframe() constructs a new ViewMultiFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: no frame selection happens here.

Parameters:

frame_name -- Optional hosted frame name. When omitted, returns record keys across all hosted frames.

Returns:

Spell record keys in deterministic order.

Return type:

List[Tuple[str, str]]

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

Return published spell names for the selected scope.

Purpose:

Expose spell-name inventory directly from SpellRecord metadata.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.list_spell_names(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_multiframe() constructs a new ViewMultiFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: no frame selection happens here.

Parameters:

frame_name -- Optional hosted frame name. When omitted, returns spell names across all hosted frames.

Returns:

Spell names in deterministic record order.

Return type:

List[str]

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

Return published binding names for the selected scope.

Purpose:

Expose the spell binding identities currently represented in the hosted descriptors.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.list_binding_names(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_multiframe() constructs a new ViewMultiFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: no frame selection happens here.

Parameters:

frame_name -- Optional hosted frame name. When omitted, returns binding names across all hosted frames.

Returns:

Non-empty binding names in deterministic record order.

Return type:

List[str]

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

Return spell-index ids for the selected descriptor scope.

Purpose:

Expose SpellIndex identity directly from SpellRecord metadata.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.list_index_ids(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_multiframe() constructs a new ViewMultiFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: no frame selection happens here.

Parameters:

frame_name -- Optional hosted frame name. When omitted, returns spell-index ids across all hosted frames.

Returns:

Spell-index ids in deterministic record order.

Return type:

List[str]

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

Return normalized spellframe values for the selected scope.

Purpose:

Surface the logical spellframe inventory directly from SpellRecord.spellframe without exposing payload data.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.list_spellframes(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_multiframe() constructs a new ViewMultiFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: no frame selection happens here.

Parameters:

frame_name -- Optional hosted frame name. When omitted, returns unique spellframe values across all hosted frames.

Returns:

Distinct normalized spellframe values in deterministic order.

Return type:

List[str]

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

Return distinct spell permission names for the selected scope.

Purpose:

Surface the spell permission posture currently represented in the hosted descriptors.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.list_permissions(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_multiframe() constructs a new ViewMultiFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: no frame selection happens here.

Parameters:

frame_name -- Optional hosted frame name. When omitted, returns permission names across all hosted frames.

Returns:

Distinct permission names in deterministic order.

Return type:

List[str]

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

Return distinct spell existence kinds for the selected scope.

Purpose:

Surface spell lifetime categories directly from SpellRecord metadata.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.list_existence_kinds(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_multiframe() constructs a new ViewMultiFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: no frame selection happens here.

Parameters:

frame_name -- Optional hosted frame name. When omitted, returns existence kinds across all hosted frames.

Returns:

Distinct existence-kind names in deterministic order.

Return type:

List[str]

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

Return a descriptor-only inventory summary for the selected scope.

Purpose:

Give the operator one compact host-level answer to "what descriptors do I have here?" without crossing into payload bodies.

Contract:

• Uses only FrameRecord, ConduitRecord, and SpellRecord identity/provenance fields.

• May summarize one frame or the entire hosted viewer scope.

• Does not expose payload body contents.

Parameters:

frame_name -- Optional hosted frame name. When omitted, summarizes all hosted descriptors together.

Returns:

Descriptor-only inventory summary.

Return type:

Dict[str, object]

describe_descriptor_topology(frame_name: str) → Dict[str, object]

Return descriptor-topology groupings for one hosted frame.

Purpose:

Surface the descriptor-owned conduit/spell index structure in one place so the operator can understand how records are grouped before moving into payload-aware helper methods.

Contract:

• Uses only descriptor-owned indexes and record identity fields.

• Does not expose payload body contents.

• Requires one concrete hosted frame.

Parameters:

frame_name -- Hosted frame name whose descriptor topology should be summarized.

Returns:

Descriptor topology summary for the frame.

Return type:

Dict[str, object]

describe_conduit_records(frame_name: str) → List[Dict[str, object]]

Return descriptor-only conduit record descriptions for one frame.

Purpose:

Surface the conduit record identities and lineage grouping owned by one frame descriptor without exposing conduit payload bodies.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.describe_conduit_records(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_multiframe() constructs a new ViewMultiFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: no frame selection happens here.

Parameters:

frame_name -- Hosted frame name whose conduit records should be described.

Returns:

Conduit record descriptions.

Return type:

List[Dict[str, object]]

describe_spell_records(frame_name: str) → List[Dict[str, object]]

Return descriptor-only spell record descriptions for one frame.

Purpose:

Surface spell record identities and provenance directly from SpellRecord without crossing into spell payload bodies.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.describe_spell_records(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_multiframe() constructs a new ViewMultiFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: no frame selection happens here.

Parameters:

frame_name -- Hosted frame name whose spell records should be described.

Returns:

Spell record descriptions.

Return type:

List[Dict[str, object]]

describe_spell_record(spell_source_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return one descriptor-only spell record description.

Purpose:

Give the operator one exact spell-record view built strictly from record identity and provenance fields.

Contract:

• Uses only SpellRecord fields and normalized spellframe values.

• Does not expose payload body content.

• When frame_name is omitted, searches the hosted frames for a unique matching spell source id.

Parameters:

• spell_source_id -- Published spell source id in spellbook_id:spell_id form.

• frame_name -- Optional hosted frame name to constrain the lookup.

Returns:

Descriptor-only spell record description.

Return type:

Dict[str, object]

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

Return spell source ids owned by one conduit.

Purpose:

Expose spell ownership at the descriptor host level without requiring a payload-aware helper path.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.list_spells_by_owner_conduit(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_multiframe() constructs a new ViewMultiFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: no frame selection happens here.

Parameters:

• conduit_id -- Required owner conduit id.

• frame_name -- Optional hosted frame name. When omitted, scans all hosted frames.

Returns:

Matching spell source ids in deterministic order.

Return type:

List[str]

list_spells_by_spellbook_id(spellbook_id: str, *, frame_name: str | None = None) → List[str]

Return spell source ids published by one origin spellbook.

Parameters:

• spellbook_id -- Required origin spellbook id.

• frame_name -- Optional hosted frame name. When omitted, scans all hosted frames.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.list_spells_by_spellbook_id(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_multiframe() constructs a new ViewMultiFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: the multi-frame helper is not bound to a single frame, so no frame selection happens here.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Matching spell source ids in deterministic order.

Return type:

List[str]

list_spells_by_permission(permission: str, *, frame_name: str | None = None) → List[str]

Return spell source ids with one permission posture.

Parameters:

• permission -- Required permission name.

• frame_name -- Optional hosted frame name. When omitted, scans all hosted frames.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.list_spells_by_permission(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_multiframe() constructs a new ViewMultiFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: the multi-frame helper is not bound to a single frame, so no frame selection happens here.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Matching spell source ids in deterministic order.

Return type:

List[str]

list_spells_by_existence(existence: str, *, frame_name: str | None = None) → List[str]

Return spell source ids with one existence posture.

Parameters:

• existence -- Required existence-kind name.

• frame_name -- Optional hosted frame name. When omitted, scans all hosted frames.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.list_spells_by_existence(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_multiframe() constructs a new ViewMultiFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: the multi-frame helper is not bound to a single frame, so no frame selection happens here.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Matching spell source ids in deterministic order.

Return type:

List[str]

list_spells_by_spellframe(spellframe_name: str, *, frame_name: str | None = None) → List[str]

Return spell source ids with one normalized spellframe value.

Parameters:

• spellframe_name -- Required normalized spellframe name.

• frame_name -- Optional hosted frame name. When omitted, scans all hosted frames.

Contract:

• FACADE PASS-THROUGH to ViewMultiFrame.list_spells_by_spellframe(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_multiframe() constructs a new ViewMultiFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• Descriptor-hosted and CROSS-FRAME: the multi-frame helper is not bound to a single frame, so no frame selection happens here.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Matching spell source ids in deterministic order.

Return type:

List[str]

clone() → FrameViewer

Return a detached copy of the viewer host.

Purpose:

Preserve the borrowed Rift reference while creating a detached viewer object with no additional local state.

Contract:

• Produces a NEW viewer over THE SAME rift and the same action-hook scope factory - it copies the wiring, NOT any state, because a viewer holds no cached projection to copy.

• The clone is INDEPENDENTLY OWNED: cleaning it does not clean this viewer, and both remain valid over the shared rift.

• Useful for handing a viewer to another thread without sharing this one; it is not a snapshot and will see the same live frame state.

Returns:

Detached viewer clone.

Return type:

FrameViewer

get_view_frame(frame_name: str) → ViewFrame

Return one frame helper bound to the requested frame.

Parameters:

frame_name -- Required hosted frame name.

Contract:

• CONSTRUCTS A FRESH ViewFrame ON EVERY CALL. Nothing is cached, so two calls return two distinct objects over two distinct descriptor snapshots. HOLD THE RESULT if you want a stable view or want to make several queries against one consistent snapshot.

• frame_name is a SELECTOR here - it resolves which hosted frame to bind. Inside the returned helper the same parameter becomes an ASSERTION that must match this binding. Passing None resolves the viewer's currently selected frame.

• Binds the descriptor, ACL configuration and compiled access surface together at construction, so the returned helper is internally consistent even if the frame changes afterwards.

• Built at detailed detail level and wired to this viewer's action hook scope.

Threading:

Takes a descriptor snapshot at construction; the returned helper does not track later frame changes.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The returned helper is owned by the CALLER; this viewer does not retain or clean it.

Raises:

RuntimeError -- If the frame cannot be resolved, or the viewer has been cleaned.

Returns:

Selected-frame helper surface.

Return type:

ViewFrame

get_view_conduit(*, frame_name: str) → ViewConduit

Return one conduit helper bound to the requested frame.

Parameters:

frame_name -- Required hosted frame name.

Contract:

• CONSTRUCTS A FRESH ViewConduit ON EVERY CALL, and a fresh ViewFrame beneath it. Two calls therefore cost two full projections; hold the result when making several conduit queries.

• The returned helper BORROWS its frame view - it does not own it - so the two share one descriptor snapshot and stay mutually consistent.

• frame_name is a SELECTOR here and becomes an ASSERTION inside the helper.

• Does NOT call check_cleaned() itself; the guard comes from the get_view_frame(...) call it delegates to.

Threading:

Snapshot-bound at construction; does not track later frame changes.

Lifecycle / Cleanup:

The returned helper is owned by the CALLER.

Raises:

RuntimeError -- If the frame cannot be resolved, or the viewer has been cleaned.

Returns:

Bound conduit helper surface.

Return type:

ViewConduit

get_view_spell(*, frame_name: str) → ViewSpell

Return one spell helper bound to the requested frame.

Parameters:

frame_name -- Required hosted frame name.

Contract:

• CONSTRUCTS A FRESH ViewSpell ON EVERY CALL, and a fresh ViewFrame beneath it. Two calls cost two full projections; hold the result when making several spell queries.

• The returned helper BORROWS its frame view - it does not own it - so the two share one descriptor snapshot and stay mutually consistent.

• frame_name is a SELECTOR here and becomes an ASSERTION inside the helper.

• Does NOT call check_cleaned() itself; the guard comes from the get_view_frame(...) call it delegates to.

Threading:

Snapshot-bound at construction; does not track later frame changes.

Lifecycle / Cleanup:

The returned helper is owned by the CALLER.

Raises:

RuntimeError -- If the frame cannot be resolved, or the viewer has been cleaned.

Returns:

Bound spell helper surface.

Return type:

ViewSpell

get_view_multiframe() → ViewMultiFrame

Return one descriptor-hosted multi-frame helper.

Contract:

• CONSTRUCTS A FRESH ViewMultiFrame ON EVERY CALL; nothing is cached.

• CROSS-FRAME by design, so it takes no frame selector and is not bound to one frame's snapshot. It reaches back through THIS viewer for each frame it inspects, which is why it is the one helper that can compare across frames.

• Because it holds this viewer rather than a snapshot, its reads are resolved later rather than frozen at construction - the opposite of the single-frame helpers.

Threading:

Resolves per query rather than from one snapshot, so two of its calls can observe different frame states.

Lifecycle / Cleanup:

Guarded by check_cleaned(). It BORROWS this viewer, so it must not outlive it; the returned helper is owned by the CALLER.

Raises:

RuntimeError -- If the viewer has been cleaned.

Returns:

Fresh helper for cross-frame and descriptor-hosted inventory/comparison logic.

Return type:

ViewMultiFrame

list_viewer_method_names_ast_json(*, include_private: bool = False, include_dunder: bool = False) → str

Return a minified JSON list of FrameViewer class method names.

Purpose:

Give the agent a source-defined list of host methods available on the viewer itself without inspecting method bodies or runtime internals.

Contract:

• Reports THIS VIEWER'S OWN method names, not the frame's contents, so it carries no frame data and needs no ACL filtering.

• include_private and include_dunder widen the surface; both default to the narrow agent-facing view.

• Returned MINIFIED as JSON for token efficiency - it is meant to be handed to an agent rather than read by a human.

Parameters:

• include_private -- Whether _private methods should be included.

• include_dunder -- Whether __dunder__ methods should be included.

Returns:

Minified JSON list of source-defined FrameViewer methods.

Return type:

str

describe_agent_onboarding_json() → str

Return the shared first-time onboarding hint for Melder agents.

Contract:

• STATIC CONTENT: the onboarding hint is produced by ClassSurfaceAstDescriber and is identical for every viewer and every frame. It describes how to drive Melder's agent surface, NOT anything about this rift's contents, so it leaks no frame data and needs no ACL filtering.

• Returned MINIFIED for token efficiency - it is meant to be handed to an agent, not read by a human.

Threading:

No viewer state is read beyond the cleaned check.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the viewer has been cleaned.

Returns:

Minified JSON onboarding hint for Melder agents.

Return type:

str

describe_viewer_agent_purpose_json() → str

Return the minified JSON agent-purpose surface for the viewer host.

Contract:

• Describes THIS VIEWER'S OWN callable surface - the agent-facing contract of the object you are holding - not the frame it projects. It is built from the class's __agent_purpose__ and __ast_helper_access__ markers by ClassSurfaceAstDescriber.

• Reports the SHAPE of the API, so it carries no frame contents and needs no ACL filtering.

• Returned MINIFIED for token efficiency.

Threading:

Reflects over the class, not over frame state.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the viewer has been cleaned.

Returns:

Minified JSON agent-purpose surface for this viewer.

Return type:

str

describe_viewer_class_surface_ast_json(*, include_private: bool = False, include_dunder: bool = False) → str

Return a minified JSON description of the FrameViewer class surface.

Purpose:

Expose the source-defined FrameViewer class surface, including method signatures, properties, and docstrings, for direct agent consumption.

Contract:

• Describes THIS VIEWER'S CALLABLE SURFACE - signatures and the agent markers on the class - rather than the frame it projects, so it is safe regardless of ACL.

• Richer than list_viewer_method_names_ast_json, which returns names only.

• Returned MINIFIED as JSON for token efficiency.

Parameters:

• include_private -- Whether _private members should be included.

• include_dunder -- Whether __dunder__ members should be included.

Returns:

Minified JSON description of the FrameViewer class surface.

Return type:

str

describe_visible_surface(*, frame_name: str) → Dict[str, object]

Return the current visible frame-local surface in one summary.

Purpose:

Give the operator a single "what can I actually see right now?" entry point over the selected frame without making them manually merge inventory, topology, and access-contract calls.

Contract:

• Uses only the selected frame descriptor plus the compiled ACL surface.

• Summarizes the currently visible target ids, grouped inventory, visible topology, and access contract.

• Remains frame-local; it never spans multiple hosted frames.

Parameters:

frame_name -- Optional hosted frame name override.

Returns:

Summary of the currently visible frame-local surface.

Return type:

Dict[str, object]

describe_missing_surface(*, frame_name: str) → Dict[str, object]

Return what is currently hidden or absent from the selected frame surface.

Purpose:

Help the operator answer "what am I not seeing right now?" by comparing descriptor-owned records and payload fields against the currently visible ACL-shaped surface.

Contract:

• Uses descriptor truth plus the compiled ACL surface only.

• Distinguishes hidden frame payload fields, hidden conduit/spell records, and payload sections not currently visible.

• Does not expose hidden payload bodies.

Parameters:

frame_name -- Optional hosted frame name override.

Returns:

Missing/hidden surface summary.

Return type:

Dict[str, object]

describe_frame_brief_local(*, frame_name: str) → Dict[str, object]

Return one compact operator-oriented frame summary.

Purpose:

Give the operator a smaller "start here" summary than the richer frame surface methods while still reflecting visible inventory and ACL posture.

Contract:

• FACADE PASS-THROUGH to ViewFrame.describe_frame_brief(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_frame() constructs a new ViewFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and becomes an ASSERTION inside the sub-viewer. Passing None resolves the selected frame.

Parameters:

frame_name -- Optional hosted frame name override.

Returns:

Compact frame-local summary.

Return type:

Dict[str, object]

describe_visible_inventory_by_kind(*, frame_name: str) → Dict[str, Dict[str, object]]

Return visible inventory grouped by target kind.

Purpose:

Provide a frame-local grouped inventory over visible targets so the operator can see counts, source ids, and names without manually regrouping raw links.

Contract:

• FACADE PASS-THROUGH to ViewFrame.describe_visible_inventory_by_kind(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_frame() constructs a new ViewFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and becomes an ASSERTION inside the sub-viewer. Passing None resolves the selected frame.

Parameters:

frame_name -- Optional hosted frame name override.

Returns:

Inventory grouped by target kind.

Return type:

Dict[str, Dict[str, object]]

describe_frame_topology(*, frame_name: str) → Dict[str, object]

Return the visible conduit/spell topology for the selected frame.

Purpose:

Summarize how the currently visible conduits and spells relate to each other so the operator can navigate the frame structure without reading each target individually first.

Contract:

• FACADE PASS-THROUGH to ViewFrame.describe_frame_topology(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_frame() constructs a new ViewFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and becomes an ASSERTION inside the sub-viewer. Passing None resolves the selected frame.

Parameters:

frame_name -- Optional hosted frame name override.

Returns:

Visible frame-local topology summary.

Return type:

Dict[str, object]

list_visible_target_ids(*, frame_name: str, source_kind: str | None = None) → List[str]

Return visible target ids for the selected frame.

Purpose:

Provide a compact id-only view over the currently visible target surface.

Contract:

• FACADE PASS-THROUGH to ViewFrame.list_visible_target_ids(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_frame() constructs a new ViewFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and becomes an ASSERTION inside the sub-viewer. Passing None resolves the selected frame.

Parameters:

• frame_name -- Optional hosted frame name override.

• source_kind -- Optional target-kind filter.

Returns:

Visible target ids in deterministic order.

Return type:

List[str]

list_visible_target_ids_by_kind(*, frame_name: str) → Dict[str, Tuple[str, ...]]

Return visible target ids grouped by target kind.

Parameters:

frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewFrame.list_visible_target_ids_by_kind(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_frame() constructs a new ViewFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Visible target ids grouped by kind.

Return type:

Dict[str, Tuple[str, ...]]

list_visible_conduit_ids(*, frame_name: str) → List[str]

Return visible conduit ids for the selected frame.

Parameters:

frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewFrame.list_visible_conduit_ids(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_frame() constructs a new ViewFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Visible conduit ids in deterministic order.

Return type:

List[str]

list_visible_spell_source_ids(*, frame_name: str) → List[str]

Return visible spell source ids for the selected frame.

Parameters:

frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewFrame.list_visible_spell_source_ids(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_frame() constructs a new ViewFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Visible spell source ids in deterministic order.

Return type:

List[str]

list_visible_root_conduits(*, frame_name: str) → List[FrameLink]

Return visible conduit links that are also root conduits.

Parameters:

frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewFrame.list_visible_root_conduits(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_frame() constructs a new ViewFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Visible root conduit links.

Return type:

List[FrameLink]

list_visible_binding_names(*, frame_name: str) → List[str]

Return visible spell binding names for the selected frame.

Parameters:

frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewFrame.list_visible_binding_names(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_frame() constructs a new ViewFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Visible binding names in deterministic spell order.

Return type:

List[str]

list_visible_spell_names(*, frame_name: str) → List[str]

Return visible spell names for the selected frame.

Parameters:

frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewFrame.list_visible_spell_names(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_frame() constructs a new ViewFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Visible spell names in deterministic spell order.

Return type:

List[str]

list_visible_spellframes(*, frame_name: str) → List[str]

Return visible normalized spellframe values for the selected frame.

Parameters:

frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewFrame.list_visible_spellframes(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_frame() constructs a new ViewFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Distinct visible spellframe values in deterministic order.

Return type:

List[str]

list_visible_index_ids(*, frame_name: str) → List[str]

Return visible spell-index ids for the selected frame.

Parameters:

frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewFrame.list_visible_index_ids(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_frame() constructs a new ViewFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Visible spell-index ids in deterministic spell order.

Return type:

List[str]

describe_visible_spell_ownership(*, frame_name: str) → Dict[str, Tuple[str, ...]]

Return visible spell ownership grouped by conduit id.

Parameters:

frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewFrame.describe_visible_spell_ownership(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_frame() constructs a new ViewFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Visible spell source ids grouped by owner conduit id.

Return type:

Dict[str, Tuple[str, ...]]

describe_visible_conduit_tree(*, frame_name: str) → Dict[str, Tuple[str, ...]]

Return visible conduit ids grouped by root conduit id.

Parameters:

frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewFrame.describe_visible_conduit_tree(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_frame() constructs a new ViewFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Visible conduit ids grouped by root conduit id.

Return type:

Dict[str, Tuple[str, ...]]

search_targets_contains(text: str, *, frame_name: str, source_kind: str | None = None) → List[FrameLink]

Return visible targets whose identity contains one text fragment.

Purpose:

Provide a forgiving search path over visible target display names and source ids.

Contract:

• FACADE PASS-THROUGH to ViewFrame.search_targets_contains(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_frame() constructs a new ViewFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and becomes an ASSERTION inside the sub-viewer. Passing None resolves the selected frame.

Parameters:

• text -- Case-insensitive text fragment to search for.

• frame_name -- Optional hosted frame name override.

• source_kind -- Optional target-kind filter.

Returns:

Matching visible targets in deterministic order.

Return type:

List[FrameLink]

search_targets_prefix(prefix: str, *, frame_name: str, source_kind: str | None = None) → List[FrameLink]

Return visible targets whose identity starts with one prefix.

Parameters:

• prefix -- Case-insensitive prefix to match against display names and source ids.

• frame_name -- Optional hosted frame name override.

• source_kind -- Optional target-kind filter.

Contract:

• FACADE PASS-THROUGH to ViewFrame.search_targets_prefix(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_frame() constructs a new ViewFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Matching visible targets in deterministic order.

Return type:

List[FrameLink]

group_targets_by_kind(*, frame_name: str) → Dict[str, List[FrameLink]]

Return visible targets grouped by target kind.

Parameters:

frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewFrame.group_targets_by_kind(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_frame() constructs a new ViewFrame per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Visible targets grouped by source kind.

Return type:

Dict[str, List[FrameLink]]

describe_target_brief(*, source_kind: str, source_id: str, frame_name: str) → Dict[str, object]

Return one compact summary for a visible target.

Purpose:

Give the operator a quick identity/access snapshot for one visible target without forcing the richer identity or payload-specific methods immediately.

Contract:

• FACADE PASS-THROUGH to ViewFrame.describe_target_brief(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_frame() constructs a new ViewFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and becomes an ASSERTION inside the sub-viewer. Passing None resolves the selected frame.

Parameters:

• source_kind -- Required target kind.

• source_id -- Required target source id.

• frame_name -- Optional hosted frame name override.

Returns:

Compact visible target summary.

Return type:

Dict[str, object]

describe_target_identity(*, source_kind: str, source_id: str, frame_name: str) → Dict[str, object]

Return a compact identity summary for one visible target.

Purpose:

Give the operator a stable identity/provenance snapshot for one currently visible target without forcing a wider payload dump.

Contract:

• FACADE PASS-THROUGH to ViewFrame.describe_target_identity(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_frame() constructs a new ViewFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and becomes an ASSERTION inside the sub-viewer. Passing None resolves the selected frame.

Parameters:

• source_kind -- Required target kind.

• source_id -- Required target source id.

• frame_name -- Optional hosted frame name override.

Returns:

Visible target identity summary.

Return type:

Dict[str, object]

describe_visible_collisions(*, frame_name: str) → Dict[str, object]

Return visible identity collisions for the selected frame.

Purpose:

Make visible ambiguity explicit at the frame-local surface so the operator can see where multiple visible spells share the same binding name, spell name, lineage, or spellframe.

Contract:

• FACADE PASS-THROUGH to ViewFrame.describe_visible_collisions(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_frame() constructs a new ViewFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and becomes an ASSERTION inside the sub-viewer. Passing None resolves the selected frame.

Parameters:

frame_name -- Optional hosted frame name override.

Returns:

Visible collision and grouping summary.

Return type:

Dict[str, object]

describe_frame_payload(*, frame_name: str) → Dict[str, object]

Return the ACL-filtered frame payload for the selected frame.

Purpose:

Surface the real FrameRecord.payload content the viewer can use after the compiled ACL surface has already reduced it to the currently visible frame fields.

Contract:

• Uses the selected FrameDescriptor and compiled ACL surface only.

• Returns only fields present in CompiledFrameACLAccessSurface.frame_payload_fields.

• Raises when the selected frame does not expose frame_overview.

Parameters:

frame_name -- Optional hosted frame name override.

Returns:

ACL-filtered frame payload description.

Return type:

Dict[str, object]

describe_frame_inventory(*, frame_name: str) → Dict[str, object]

Return a compact inventory of the selected frame surface.

Purpose:

Give the main viewer operator a fast answer to "what is in this frame right now?" without forcing a full target dump first.

Contract:

• Counts only ACL-visible conduits and spells.

• Preserves the currently visible target ids and source ids.

Parameters:

frame_name -- Optional hosted frame name override.

Returns:

Compact frame inventory summary.

Return type:

Dict[str, object]

describe_frame_access_contract(*, frame_name: str) → Dict[str, object]

Return the selected ACL access contract for the frame surface.

Purpose:

Surface the effective view/codegen posture and visible frame payload fields so the viewer operator can understand why certain data is or is not available.

Contract:

• FACADE PASS-THROUGH to ViewFrame.describe_frame_access_contract(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_frame() constructs a new ViewFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and becomes an ASSERTION inside the sub-viewer. Passing None resolves the selected frame.

Parameters:

frame_name -- Optional hosted frame name override.

Returns:

Effective ACL access contract summary.

Return type:

Dict[str, object]

get_frame_payload_field(field_name: str, *, frame_name: str) → object

Return one ACL-visible frame payload field or raise.

Purpose:

Provide a fail-fast, field-level access path for agent use when the caller needs one specific frame payload field instead of the whole filtered payload map.

Contract:

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

• Returns the normalized field value from the selected frame payload.

Parameters:

• field_name -- Required frame payload field name.

• frame_name -- Optional hosted frame name override.

Returns:

ACL-visible frame payload field value.

Return type:

object

find_target_by_display_name(display_name: str, *, frame_name: str, source_kind: str | None = None) → List[FrameLink]

Return visible targets whose display name matches exactly.

Purpose:

Give the operator a fast exact-name lookup path over the currently visible target surface without forcing a manual target scan.

Contract:

• FACADE PASS-THROUGH to ViewFrame.find_target_by_display_name(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_frame() constructs a new ViewFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and becomes an ASSERTION inside the sub-viewer. Passing None resolves the selected frame.

Parameters:

• display_name -- Exact display name to match.

• frame_name -- Optional hosted frame name override.

• source_kind -- Optional target-kind filter.

Returns:

Matching visible targets.

Return type:

List[FrameLink]

explain_target_access(*, source_kind: str, source_id: str, frame_name: str) → Dict[str, object]

Explain whether one target is visible and what ACL data is exposed.

Purpose:

Make the effective access posture explicit for one frame, conduit, or spell target instead of forcing the operator to infer it from missing results or partial payloads.

Contract:

• FACADE PASS-THROUGH to ViewFrame.explain_target_access(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_frame() constructs a new ViewFrame against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and becomes an ASSERTION inside the sub-viewer. Passing None resolves the selected frame.

Parameters:

• source_kind -- Target kind to inspect.

• source_id -- Target source id to inspect.

• frame_name -- Optional hosted frame name override.

Returns:

Visibility and section/field explanation for the requested target.

Return type:

Dict[str, object]

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

Return the currently visible targets for the selected frame.

Contract:

• Builds links from the selected descriptor plus compiled ACL surface.

• Optionally filters that visible set down to one source kind.

• Returns a fresh snapshot for this call.

Parameters:

• frame_name -- Optional hosted frame name override.

• source_kind -- Optional target-kind filter (frame, conduit, or spell).

Returns:

Ordered ACL-filtered targets.

Return type:

List[FrameLink]

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

Return summary descriptions for the current visible target snapshot.

Contract:

• Preserves the same target visibility as list_targets(...).

• Includes link metadata only when the helper is in detailed posture.

Parameters:

• frame_name -- Optional hosted frame name override.

• source_kind -- Optional target-kind filter.

Returns:

ACL-filtered target descriptions.

Return type:

List[Dict[str, object]]

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 selected-frame helper and its compiled ACL surface.

• Returns a fresh link snapshot for this call.

Parameters:

frame_name -- Optional hosted frame name override.

Returns:

Conduit links for the selected frame.

Return type:

List[FrameLink]

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

Return visible conduit links that are root conduits.

Parameters:

frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewConduit.list_root_conduits(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_conduit() constructs a new ViewConduit (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Visible root conduit links.

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 hosted frame name override.

Returns:

Conduit descriptions.

Return type:

List[Dict[str, object]]

get_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 hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewConduit.get_required_conduit(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_conduit() constructs a new ViewConduit (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Matching conduit link.

Return type:

FrameLink

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 hosted frame name override.

Returns:

ACL-filtered conduit description.

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:

• FACADE PASS-THROUGH to ViewConduit.describe_conduit_brief(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_conduit() constructs a new ViewConduit (and a new ViewFrame beneath it) against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and becomes an ASSERTION inside the sub-viewer. Passing None resolves the selected frame.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional hosted frame name override.

Returns:

Compact conduit 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:

• FACADE PASS-THROUGH to ViewConduit.describe_conduit_inventory(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_conduit() constructs a new ViewConduit (and a new ViewFrame beneath it) against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and becomes an ASSERTION inside the sub-viewer. Passing None resolves the selected frame.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional hosted frame name override.

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 root grouping, peer links, and owned visible spells explicit in one relationship-oriented view.

Contract:

• FACADE PASS-THROUGH to ViewConduit.describe_conduit_relationships(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_conduit() constructs a new ViewConduit (and a new ViewFrame beneath it) against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and becomes an ASSERTION inside the sub-viewer. Passing None resolves the selected frame.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional hosted frame name override.

Returns:

Visible conduit relationship 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:

• FACADE PASS-THROUGH to ViewConduit.describe_conduit_missing_sections(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_conduit() constructs a new ViewConduit (and a new ViewFrame beneath it) against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and becomes an ASSERTION inside the sub-viewer. Passing None resolves the selected frame.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional hosted frame name override.

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:

• FACADE PASS-THROUGH to ViewConduit.describe_conduit_crosswalk(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_conduit() constructs a new ViewConduit (and a new ViewFrame beneath it) against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and becomes an ASSERTION inside the sub-viewer. Passing None resolves the selected frame.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional hosted frame name override.

Returns:

Conduit crosswalk summary.

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:

• FACADE PASS-THROUGH to ViewConduit.list_conduit_spells(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_conduit() constructs a new ViewConduit (and a new ViewFrame beneath it) against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and becomes an ASSERTION inside the sub-viewer. Passing None resolves the selected frame.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional hosted frame name override.

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 peer links plus the visible spells currently owned by that conduit in one compact description.

Contract:

• FACADE PASS-THROUGH to ViewConduit.describe_conduit_topology(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_conduit() constructs a new ViewConduit (and a new ViewFrame beneath it) against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and becomes an ASSERTION inside the sub-viewer. Passing None resolves the selected frame.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional hosted frame name override.

Returns:

Visible conduit topology 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 selected frame.

Parameters:

• left_conduit_id -- Left visible conduit id.

• right_conduit_id -- Right visible conduit id.

• frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewConduit.compare_conduits(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_conduit() constructs a new ViewConduit (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Visible conduit comparison summary.

Return type:

Dict[str, object]

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 hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewConduit.is_root_conduit(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_conduit() constructs a new ViewConduit (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

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 hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewConduit.get_root_conduit_id(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_conduit() constructs a new ViewConduit (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

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 hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewConduit.list_conduits_by_root_id(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_conduit() constructs a new ViewConduit (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

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 hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewConduit.list_conduits_by_policy(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_conduit() constructs a new ViewConduit (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

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 hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewConduit.list_conduits_by_state(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_conduit() constructs a new ViewConduit (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

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 hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewConduit.list_peer_conduits(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_conduit() constructs a new ViewConduit (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

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 hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewConduit.list_peer_conduit_ids(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_conduit() constructs a new ViewConduit (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

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 hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewConduit.list_spell_source_ids_for_conduit(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_conduit() constructs a new ViewConduit (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

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 hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewConduit.list_binding_names_for_conduit(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_conduit() constructs a new ViewConduit (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

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 hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewConduit.list_spell_names_for_conduit(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_conduit() constructs a new ViewConduit (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

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.

Parameters:

• conduit_id -- Published conduit id.

• frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewConduit.describe_conduit_access_summary(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_conduit() constructs a new ViewConduit (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

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 hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewConduit.find_conduit_by_name(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_conduit() constructs a new ViewConduit (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

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 hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewConduit.explain_conduit_access(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_conduit() constructs a new ViewConduit (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

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 hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewConduit.get_conduit_payload_field(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_conduit() constructs a new ViewConduit (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

ACL-visible conduit payload field value.

Return type:

object

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

Return the currently visible spell links for the selected frame.

Contract:

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

• Returns a fresh link snapshot for this call.

Parameters:

frame_name -- Optional hosted frame name override.

Returns:

Spell links for the selected frame.

Return type:

List[FrameLink]

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

Return record-aware descriptions for every visible spell.

Contract:

• Materializes one describe_spell(...) result per currently visible spell link.

• Preserves the active ACL filtering and payload-type degradation semantics of the spell helper.

Parameters:

frame_name -- Optional hosted frame name override.

Returns:

Spell descriptions.

Return type:

List[Dict[str, object]]

get_spell(spell_source_id: str, *, frame_name: str | None = None) → FrameLink

Return one spell link by published source id or raise.

Parameters:

• spell_source_id -- Published spell source id.

• frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewSpell.get_required_spell(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Matching spell link.

Return type:

FrameLink

describe_spell(spell_source_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return a record-aware spell description for one spell.

Purpose:

Surface one SpellRecord through the currently active ACL sections while gracefully degrading when the published spell payload is only general and therefore lacks richer detailed payload content.

Contract:

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

• Returns only the spell payload sections currently visible for the spell record key.

• Omits richer fields when the payload does not actually publish them, even if a more permissive ACL would have allowed them.

Parameters:

• spell_source_id -- Published spell source id in spellbook_id:spell_id form.

• frame_name -- Optional hosted frame name override.

Returns:

ACL-filtered spell description.

Return type:

Dict[str, object]

describe_spell_brief(spell_source_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return one compact operator-oriented spell summary.

Purpose:

Give the operator a smaller spell summary than the richer identity, access, and detail methods when they just need the essentials.

Contract:

• FACADE PASS-THROUGH to ViewSpell.describe_spell_brief(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and becomes an ASSERTION inside the sub-viewer. Passing None resolves the selected frame.

Parameters:

• spell_source_id -- Published spell source id.

• frame_name -- Optional hosted frame name override.

Returns:

Compact spell summary.

Return type:

Dict[str, object]

describe_spell_origin(spell_source_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return the publication-origin fields for one visible spell.

Purpose:

Surface where the spell came from in frame/spellbook/conduit terms so the operator can reason about provenance before reading payload sections.

Contract:

• FACADE PASS-THROUGH to ViewSpell.describe_spell_origin(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and becomes an ASSERTION inside the sub-viewer. Passing None resolves the selected frame.

Parameters:

• spell_source_id -- Published spell source id.

• frame_name -- Optional hosted frame name override.

Returns:

Publication-origin fields for the visible spell.

Return type:

Dict[str, object]

describe_spell_index(spell_source_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return spell-index grouping information for one visible spell.

Purpose:

Expose all visible and descriptor-local siblings that share the same spell-index id so the operator can understand the spell-index context inside the current frame.

Contract:

• FACADE PASS-THROUGH to ViewSpell.describe_spell_index(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and becomes an ASSERTION inside the sub-viewer. Passing None resolves the selected frame.

Parameters:

• spell_source_id -- Published spell source id.

• frame_name -- Optional hosted frame name override.

Returns:

Spell-index grouping summary for the spell.

Return type:

Dict[str, object]

describe_spell_payload(spell_source_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return only the ACL-filtered spell payload body.

Purpose:

Give the main viewer operator a stable, payload-focused spell read surface without the wider record wrapper.

Contract:

• FACADE PASS-THROUGH to ViewSpell.describe_spell_payload(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and becomes an ASSERTION inside the sub-viewer. Passing None resolves the selected frame.

Parameters:

• spell_source_id -- Published spell source id.

• frame_name -- Optional hosted frame name override.

Returns:

Spell payload summary.

Return type:

Dict[str, object]

describe_spell_detail(spell_source_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return the richer detail posture for one spell when available.

Parameters:

• spell_source_id -- Published spell source id.

• frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewSpell.describe_spell_detail(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Rich detail status and payload.

Return type:

Dict[str, object]

describe_spell_identity(spell_source_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return the stable identity fields for one visible spell.

Parameters:

• spell_source_id -- Published spell source id.

• frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewSpell.describe_spell_identity(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Stable identity fields for the visible spell.

Return type:

Dict[str, object]

describe_spell_binding(spell_source_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return the binding-facing summary for one visible spell.

Parameters:

• spell_source_id -- Published spell source id.

• frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewSpell.describe_spell_binding(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Binding-facing spell summary.

Return type:

Dict[str, object]

describe_spell_resolution(spell_source_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return the resolution-facing summary for one visible spell.

Parameters:

• spell_source_id -- Published spell source id.

• frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewSpell.describe_spell_resolution(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Resolution-facing spell summary.

Return type:

Dict[str, object]

describe_spell_metadata(spell_source_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return the metadata-facing summary for one visible spell.

Parameters:

• spell_source_id -- Published spell source id.

• frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewSpell.describe_spell_metadata(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Metadata-facing spell summary.

Return type:

Dict[str, object]

describe_spell_class_profile(spell_source_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return the class-profile summary for one visible detailed spell.

Parameters:

• spell_source_id -- Published spell source id.

• frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewSpell.describe_spell_class_profile(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Class-profile summary.

Return type:

Dict[str, object]

describe_spell_callable_profile(spell_source_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return the callable-profile summary for one visible detailed spell.

Parameters:

• spell_source_id -- Published spell source id.

• frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewSpell.describe_spell_callable_profile(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Callable-profile summary.

Return type:

Dict[str, object]

describe_spell_instance_members(spell_source_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return the instance-member summary for one visible detailed spell.

Parameters:

• spell_source_id -- Published spell source id.

• frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewSpell.describe_spell_instance_members(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Instance-member summary.

Return type:

Dict[str, object]

describe_spell_dynamic_access(spell_source_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return the dynamic-access summary for one visible detailed spell.

Parameters:

• spell_source_id -- Published spell source id.

• frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewSpell.describe_spell_dynamic_access(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Dynamic-access availability and normalized data.

Return type:

Dict[str, object]

list_spell_dunder_member_names(spell_source_id: str, *, frame_name: str | None = None) → Tuple[str, ...]

Return dunder member names visible in detailed spell data.

Parameters:

• spell_source_id -- Published spell source id.

• frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewSpell.list_spell_dunder_member_names(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Visible dunder member names.

Return type:

Tuple[str, ...]

describe_spell_dunder_members(spell_source_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return the visible dunder members surfaced by detailed spell data.

Parameters:

• spell_source_id -- Published spell source id.

• frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewSpell.describe_spell_dunder_members(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Visible dunder member summary.

Return type:

Dict[str, object]

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

Return visible spells whose published payload type matches exactly.

Parameters:

• payload_type -- Required spell payload type.

• frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewSpell.list_spells_by_payload_type(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Matching visible spell links.

Return type:

List[FrameLink]

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

Return visible spells whose binding name matches exactly.

Parameters:

• binding_name -- Exact published binding name.

• frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewSpell.find_spell_by_binding_name(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Matching visible spell links.

Return type:

List[FrameLink]

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

Return visible spells sharing one spell-index id.

Parameters:

• spell_index_id -- Required spell-index id.

• frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewSpell.list_spells_by_index_id(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Matching visible spell links.

Return type:

List[FrameLink]

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

Return visible spells whose spell name matches exactly.

Parameters:

• spell_name -- Required spell name.

• frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewSpell.list_spells_by_spell_name(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Matching visible spell links.

Return type:

List[FrameLink]

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

Return visible spells whose identity contains one text fragment.

Parameters:

• text -- Case-insensitive text fragment to match.

• frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewSpell.search_spells_contains(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Matching visible spell links.

Return type:

List[FrameLink]

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

Return visible spells whose identity starts with one prefix.

Parameters:

• prefix -- Case-insensitive prefix to match.

• frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewSpell.search_spells_prefix(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Matching visible spell links.

Return type:

List[FrameLink]

explain_spell_access(spell_source_id: str, *, frame_name: str | None = None) → Dict[str, object]

Explain the effective ACL access posture for one spell.

Parameters:

• spell_source_id -- Published spell source id.

• frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewSpell.explain_spell_access(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Spell visibility, section, and detail posture explanation.

Return type:

Dict[str, object]

describe_spell_access_summary(spell_source_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return one compact access/identity/detail summary for a spell.

Parameters:

• spell_source_id -- Published spell source id.

• frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewSpell.describe_spell_access_summary(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Compact spell access summary.

Return type:

Dict[str, object]

get_spell_payload_section(spell_source_id: str, section_name: str, *, frame_name: str | None = None) → object

Return one ACL-visible spell payload section or raise.

Parameters:

• spell_source_id -- Published spell source id.

• section_name -- Required spell payload section name.

• frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewSpell.get_spell_payload_section(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

ACL-visible spell payload section value.

Return type:

object

describe_spell_missing_sections(spell_source_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return the spell payload sections not currently visible or published.

Purpose:

Make the spell-local "what is missing and why?" answer explicit instead of forcing the operator to infer it from absent detail fields.

Contract:

• FACADE PASS-THROUGH to ViewSpell.describe_spell_missing_sections(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and becomes an ASSERTION inside the sub-viewer. Passing None resolves the selected frame.

Parameters:

• spell_source_id -- Published spell source id.

• frame_name -- Optional hosted frame name override.

Returns:

Missing spell-section summary.

Return type:

Dict[str, object]

describe_spell_crosswalk(spell_source_id: str, *, frame_name: str | None = None) → Dict[str, object]

Return the related visible objects around one spell.

Purpose:

Give the operator one direct spell crosswalk from the spell to its conduit, root conduit, peer conduits, spellbook, lineage, and visible sibling spells.

Contract:

• FACADE PASS-THROUGH to ViewSpell.describe_spell_crosswalk(...). Filtering, ordering and raise behaviour are that method's; this adds no logic of its own.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL: get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) against a newly resolved descriptor snapshot, so a loop of facade calls rebuilds the projection each time and TWO FACADE CALLS NEED NOT SEE THE SAME FRAME STATE. Hold one sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED: absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and becomes an ASSERTION inside the sub-viewer. Passing None resolves the selected frame.

Parameters:

• spell_source_id -- Published spell source id.

• frame_name -- Optional hosted frame name override.

Returns:

Spell crosswalk summary.

Return type:

Dict[str, object]

compare_spells(left_spell_source_id: str, right_spell_source_id: str, *, frame_name: str | None = None) → Dict[str, object]

Compare two visible spells inside the selected frame.

Parameters:

• left_spell_source_id -- Left visible spell source id.

• right_spell_source_id -- Right visible spell source id.

• frame_name -- Optional hosted frame name override.

Contract:

• FACADE PASS-THROUGH to ViewSpell.compare_spells(...). The filtering, ordering and raise behaviour are that method's; this adds no logic of its own, so read its contract for the details that matter.

• BUILDS A FRESH SUB-VIEWER ON EVERY CALL. get_view_spell() constructs a new ViewSpell (and a new ViewFrame beneath it) per invocation against a freshly resolved descriptor snapshot. A loop of facade calls therefore rebuilds the projection each time; hold the sub-viewer yourself when making several calls against one frame.

• Because each call re-resolves the descriptor, two facade calls are NOT guaranteed to see the same frame state. Use one held sub-viewer when results must be mutually consistent.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - never proof of non-existence.

• frame_name SELECTS the frame at THIS layer and then becomes an ASSERTION inside the sub-viewer. Same parameter name, two different meanings by layer. Passing None resolves the viewer's selected frame.

Threading:

Each call takes its own descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.

Lifecycle / Cleanup:

Guarded by check_cleaned(). The sub-viewer it builds is transient and owned by the call, not retained by this viewer.

Returns:

Visible spell comparison summary.

Return type:

Dict[str, object]

Topic reference · Full contents