On this page

• ViewSpell
  • ViewSpell
    • ViewSpell.cleanup()
    • ViewSpell.list_spells()
    • ViewSpell.describe_spells()
    • ViewSpell.describe_spell()
    • ViewSpell.describe_spell_payload()
    • ViewSpell.describe_spell_detail()
    • ViewSpell.describe_spell_brief()
    • ViewSpell.describe_spell_missing_sections()
    • ViewSpell.describe_spell_identity()
    • ViewSpell.describe_spell_research()
    • ViewSpell.describe_spell_source()
    • ViewSpell.describe_spell_origin()
    • ViewSpell.describe_spell_index()
    • ViewSpell.describe_spell_binding()
    • ViewSpell.describe_spell_resolution()
    • ViewSpell.describe_spell_metadata()
    • ViewSpell.describe_spell_class_profile()
    • ViewSpell.describe_spell_callable_profile()
    • ViewSpell.describe_spell_instance_members()
    • ViewSpell.describe_spell_dynamic_access()
    • ViewSpell.list_spell_dunder_member_names()
    • ViewSpell.describe_spell_dunder_members()
    • ViewSpell.list_spells_by_payload_type()
    • ViewSpell.find_spell_by_binding_name()
    • ViewSpell.list_spells_by_owner_conduit()
    • ViewSpell.list_spells_by_spellbook_id()
    • ViewSpell.list_spells_by_index_id()
    • ViewSpell.list_spells_by_permission()
    • ViewSpell.list_spells_by_existence()
    • ViewSpell.list_spells_by_spell_name()
    • ViewSpell.list_spells_by_spellframe()
    • ViewSpell.search_spells_contains()
    • ViewSpell.search_spells_prefix()
    • ViewSpell.explain_spell_access()
    • ViewSpell.describe_spell_access_summary()
    • ViewSpell.describe_spell_crosswalk()
    • ViewSpell.compare_spells()
    • ViewSpell.get_spell_payload_section()
    • ViewSpell.get_required_spell()

ViewSpell

Use md.ViewSpell from the public package namespace.

Implementation source

class ViewSpell(*, frame_view: ViewFrame | None)

Purpose:

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

Contract:

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

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

Lifecycle:

Cleanup is idempotent and clears the helper reference.

Threading:

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

Registration:

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

Subsystem Context:

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

System Context:

Every helper returns ACL-FILTERED results and never raw runtime objects. That is the viewer's security boundary: a read can surface what policy permits to be described, and cannot become a handle on the thing described. It is where research and source annotation surface (describe_spell_research, describe_spell_source), so a visible spell can be explained without the caller reaching into MutationResearch directly. Creating helpers on demand rather than caching bound state is what keeps them honest across an ACL refresh - a cached helper would answer from the projection it was born with, after that projection had been replaced.

AGENT_ACCESS: public

AGENT_PURPOSE:

access: public. Spell-local helper surface for spell identity, origin, spell-index grouping, filtering, detailed payload access, dunder-member visibility, and spell crosswalk/comparison flows inside one selected frame.

cleanup() → None

Idempotently drop the borrowed frame-helper reference.

Contract:

• Safe to call more than once.

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

Returns:

None.

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

Return the currently visible spell links for the selected frame.

Contract:

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

• Returns a fresh link snapshot for this call.

Parameters:

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

Returns:

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 frame-name assertion passed through to the selected- frame helper.

Returns:

Spell descriptions.

Return type:

List[Dict[str, object]]

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 frame-name assertion passed through to the selected- frame helper.

Returns:

ACL-filtered spell description.

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:

• Returns the ACL-FILTERED payload, so hidden sections are simply absent rather than present-and-empty. Pair it with describe_spell_missing_sections to learn what was withheld.

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

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

Threading:

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

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

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

Parameters:

• spell_source_id -- Published spell source id.

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

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.

Purpose:

Separate the "try to go deep" path from the normal spell summary so the operator can ask for richer detail explicitly and still get a truthful answer when the detail is unavailable because of the payload type or ACL restrictions.

Contract:

• When payload_type is not detailed, returns detail_available=False with reason payload_not_detailed.

• When the payload is detailed but no rich sections are ACL- visible, returns detail_available=False with reason acl_restricted.

• When rich sections are visible, returns only the rich payload sections currently present in the payload body.

Parameters:

• spell_source_id -- Published spell source id.

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

Returns:

Rich detail status and payload.

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:

• A SUMMARY, not a payload: identity plus a COUNT of visible sections. The count tells you HOW MUCH is visible without revealing what is hidden.

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

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

Threading:

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

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

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

Parameters:

• spell_source_id -- Published spell source id.

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

Returns:

Compact spell summary.

Return type:

Dict[str, 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:

• THE WITHHELD-SECTION PROBE: it computes every payload field name and subtracts the visible ones, so it reports the NAMES of sections you cannot read. This is how you tell "hidden" from "empty" without the contents.

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

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

Threading:

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

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

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

Parameters:

• spell_source_id -- Published spell source id.

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

Returns:

Missing spell-section summary.

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.

Purpose:

Give the operator a narrow identity view over one spell record without forcing a wider payload or access-contract dump first.

Contract:

• Identity fields only - the stable naming of the spell, not its payload or its placement.

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

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

Threading:

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

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

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

Parameters:

• spell_source_id -- Published spell source id.

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

Returns:

Stable identity fields for the visible spell.

Return type:

Dict[str, object]

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

Return the research annotation for one visible spell.

Purpose:

Join the viewer's runtime truth with the MutationResearch record: whether this spell's identity is formally declared research, which lane holds it, and its query-time residency verdict - alongside the identity the operator already sees.

Contract:

• Non-constructing peek: the viewer never births the MR root.

• Honest unavailability: an absent or inactive root returns research_available=False with a named reason instead of raising - viewing a spell must never fail on research state.

Parameters:

• spell_source_id -- Published spell source id.

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

Returns:

source_id, spell_id, and either the residency payload (declared/lane/runtime/custody) or the unavailability reason.

Return type:

Dict[str, object]

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

Return the recorded source of one visible spell's module world.

Purpose:

Foresight read for the operator: the actual code behind the spell they are looking at - recorded custody text first (synthetic always recorded; user text when retained), live-disk fallback with a drift marker, honest text_unavailable otherwise.

Contract:

• Non-constructing peek: routes through the SAME MutationResearch door as describe_spell_research; the viewer never births the MR root.

• Honest unavailability: an absent or inactive root returns research_available=False with a named reason instead of raising - viewing a spell must never fail on research state.

Parameters:

• spell_source_id -- Published spell source id.

• module_name -- Optional single module of the world to return.

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

Returns:

source_id, spell_id, and either the per-module source payload or the unavailability reason.

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:

• Reports where the spell CAME FROM (its origin spellbook), which is not necessarily where it lives now after a graft or transfer.

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

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

Threading:

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

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

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

Parameters:

• spell_source_id -- Published spell source id.

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

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's index context inside the current frame.

Contract:

• Describes the spell's INDEX, i.e. its version lineage, so it answers "what other versions exist" rather than "what is this version".

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

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

Threading:

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

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

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

Parameters:

• spell_source_id -- Published spell source id.

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

Returns:

Spell-index grouping summary for the 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.

Purpose:

Keep the spell's binding identity and optional binding payload together in one focused summary.

Contract:

• Binding-time facts - how the spell was registered - as opposed to runtime state.

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

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

Threading:

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

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

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

Parameters:

• spell_source_id -- Published spell source id.

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

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 frame-name assertion passed through to the selected- frame helper.

Contract:

• ACL SECTION PROBE. The result carries BOTH an availability flag and the section value, and it does NOT raise when the section is hidden.

• CHECK THE FLAG BEFORE TRUSTING THE VALUE: an empty value means "hidden" or "genuinely empty" and the flag is the only way to tell them apart. Contrast get_spell_payload_section, which raises instead of reporting.

• Delegates to the shared detail-section helper, so every describe_spell_* section behaves identically.

• Additionally derives requirement_count, which stays None when the resolution payload is absent or is not shaped as expected. None means "could not count", NOT "zero requirements".

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof that a spell does not exist.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises.

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

Threading:

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

Lifecycle / Cleanup:

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

Raises:

• ValueError -- If a required argument is empty.

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

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 section for one visible spell.

Parameters:

• spell_source_id -- Published spell source id.

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

Contract:

• ACL SECTION PROBE. The result carries BOTH an availability flag and the section value, and it does NOT raise when the section is hidden.

• CHECK THE FLAG BEFORE TRUSTING THE VALUE: an empty value means "hidden" or "genuinely empty" and the flag is the only way to tell them apart. Contrast get_spell_payload_section, which raises instead of reporting.

• Delegates to the shared detail-section helper, so every describe_spell_* section behaves identically.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof that a spell does not exist.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises.

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

Threading:

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

Lifecycle / Cleanup:

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

Raises:

• ValueError -- If a required argument is empty.

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

Returns:

Metadata visibility summary for the spell.

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 posture for one visible spell.

Parameters:

• spell_source_id -- Published spell source id.

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

Contract:

• ACL SECTION PROBE. The result carries BOTH an availability flag and the section value, and it does NOT raise when the section is hidden.

• CHECK THE FLAG BEFORE TRUSTING THE VALUE: an empty value means "hidden" or "genuinely empty" and the flag is the only way to tell them apart. Contrast get_spell_payload_section, which raises instead of reporting.

• Delegates to the shared detail-section helper, so every describe_spell_* section behaves identically.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof that a spell does not exist.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises.

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

Threading:

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

Lifecycle / Cleanup:

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

Raises:

• ValueError -- If a required argument is empty.

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

Returns:

Class-profile availability and normalized data.

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 posture for one visible spell.

Parameters:

• spell_source_id -- Published spell source id.

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

Contract:

• ACL SECTION PROBE. The result carries BOTH an availability flag and the section value, and it does NOT raise when the section is hidden.

• CHECK THE FLAG BEFORE TRUSTING THE VALUE: an empty value means "hidden" or "genuinely empty" and the flag is the only way to tell them apart. Contrast get_spell_payload_section, which raises instead of reporting.

• Delegates to the shared detail-section helper, so every describe_spell_* section behaves identically.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof that a spell does not exist.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises.

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

Threading:

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

Lifecycle / Cleanup:

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

Raises:

• ValueError -- If a required argument is empty.

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

Returns:

Callable-profile availability and normalized data.

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 posture for one visible spell.

Contract:

Dunder members are preserved when the published detailed payload included them; this method does not hide or strip them.

Contract:

• Reports member NAMES from the recorded surface, not live attribute values; nothing is executed or introspected on a live object here.

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

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

Threading:

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

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

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

Parameters:

• spell_source_id -- Published spell source id.

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

Returns:

Instance-member availability and normalized data.

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 posture for one visible spell.

Parameters:

• spell_source_id -- Published spell source id.

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

Contract:

• ACL SECTION PROBE. The result carries BOTH an availability flag and the section value, and it does NOT raise when the section is hidden.

• CHECK THE FLAG BEFORE TRUSTING THE VALUE: an empty value means "hidden" or "genuinely empty" and the flag is the only way to tell them apart. Contrast get_spell_payload_section, which raises instead of reporting.

• Delegates to the shared detail-section helper, so every describe_spell_* section behaves identically.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof that a spell does not exist.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises.

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

Threading:

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

Lifecycle / Cleanup:

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

Raises:

• ValueError -- If a required argument is empty.

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

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.

Purpose:

Make dunder visibility explicit in detailed mode instead of leaving it implicit inside larger payload maps.

Contract:

• UNIONS class-level and instance-level dunder names into a SET, so the result is DEDUPLICATED and a name appearing in both origins appears once. It does not tell you which origin a name came from.

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

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

Threading:

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

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

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

Parameters:

• spell_source_id -- Published spell source id.

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

Returns:

Distinct 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.

Purpose:

Give the operator one explicit place to inspect the dunder-facing portion of the published detailed spell data.

Contract:

• Keeps class-level and instance-level dunder members SEPARATE, unlike list_spell_dunder_member_names which unions them.

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

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

Threading:

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

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

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

Parameters:

• spell_source_id -- Published spell source id.

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

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 frame-name assertion passed through to the selected- frame helper.

Contract:

• EXACT, CASE-SENSITIVE match. Unlike the permission and existence listers, no normalization is applied, so casing must match exactly.

• A non-matching id is not an error - it simply matches nothing.

• Empty input is rejected up front.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof that a spell does not exist.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises.

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

Threading:

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

Lifecycle / Cleanup:

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

Raises:

• ValueError -- If a required argument is empty.

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

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 frame-name assertion passed through to the selected- frame helper.

Contract:

• Matches the link's DISPLAY NAME, which is the published binding name for spells. Exact and case-sensitive.

• Returns a LIST, not a single link: binding names are not guaranteed unique across the visible set.

• Empty binding_name is rejected up front.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof that a spell does not exist.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises.

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

Threading:

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

Lifecycle / Cleanup:

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

Raises:

• ValueError -- If a required argument is empty.

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

Returns:

Matching visible spell links.

Return type:

List[FrameLink]

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

Return visible spells owned by one conduit.

Parameters:

• conduit_id -- Published conduit id.

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

Contract:

• EXACT, CASE-SENSITIVE match on the recorded owner conduit id.

• Spells that are bound but NOT YET OWNED (no conjure stamp) have no owner id and therefore match nothing here - they are absent from every owner query rather than grouped under a null owner.

• Empty conduit_id is rejected up front.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof that a spell does not exist.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises.

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

Threading:

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

Lifecycle / Cleanup:

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

Raises:

• ValueError -- If a required argument is empty.

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

Returns:

Matching visible spell links.

Return type:

List[FrameLink]

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

Return visible spells published by one spellbook id.

Parameters:

• spellbook_id -- Required origin spellbook id.

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

Contract:

• EXACT, CASE-SENSITIVE match on the ORIGIN spellbook id - the book that first bound the spell, which is not necessarily the book that owns it now after a graft or transfer.

• Empty spellbook_id is rejected up front.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof that a spell does not exist.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises.

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

Threading:

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

Lifecycle / Cleanup:

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

Raises:

• ValueError -- If a required argument is empty.

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

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 frame-name assertion passed through to the selected- frame helper.

Contract:

• EXACT, CASE-SENSITIVE match on spell index id. Because an index tracks a whole version lineage, this returns EVERY visible spell sharing that lineage, not one spell.

• Empty spell_index_id is rejected up front.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof that a spell does not exist.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises.

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

Threading:

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

Lifecycle / Cleanup:

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

Raises:

• ValueError -- If a required argument is empty.

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

Returns:

Matching visible spell links.

Return type:

List[FrameLink]

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

Return visible spells with one permission posture.

Parameters:

• permission_name -- Required permission name.

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

Contract:

• CASE-INSENSITIVE: the supplied name and the record value are both lowered before comparison.

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

• Empty input is rejected up front.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof that a spell does not exist.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises.

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

Threading:

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

Lifecycle / Cleanup:

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

Raises:

• ValueError -- If a required argument is empty.

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

Returns:

Matching visible spell links.

Return type:

List[FrameLink]

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

Return visible spells with one existence posture.

Parameters:

• existence_name -- Required existence-kind name.

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

Contract:

• CASE-INSENSITIVE: the supplied name and the record value are both lowered before comparison.

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

• Empty input is rejected up front.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof that a spell does not exist.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises.

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

Threading:

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

Lifecycle / Cleanup:

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

Raises:

• ValueError -- If a required argument is empty.

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

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 frame-name assertion passed through to the selected- frame helper.

Contract:

• EXACT, CASE-SENSITIVE match on spell name.

• Returns a LIST because spell names are NOT unique - the same name can be bound many times under different frames or binding names.

• Empty spell_name is rejected up front.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof that a spell does not exist.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises.

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

Threading:

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

Lifecycle / Cleanup:

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

Raises:

• ValueError -- If a required argument is empty.

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

Returns:

Matching visible spell links.

Return type:

List[FrameLink]

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

Return visible spells with one normalized spellframe value.

Parameters:

• spellframe_name -- Required normalized spellframe name.

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

Contract:

• Compares the NORMALIZED spellframe value, so pass the normalized form rather than the raw object used at bind time.

• Spells whose spellframe normalizes to nothing never match.

• Empty spellframe_name is rejected up front.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof that a spell does not exist.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises.

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

Threading:

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

Lifecycle / Cleanup:

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

Raises:

• ValueError -- If a required argument is empty.

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

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 frame-name assertion passed through to the selected- frame helper.

Contract:

• CASE-INSENSITIVE SUBSTRING match against spell identity. Use the prefix sibling when you want anchored matching - this one will hit mid-string and returns strictly more results.

• Empty text is rejected rather than matching everything.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof that a spell does not exist.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises.

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

Threading:

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

Lifecycle / Cleanup:

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

Raises:

• ValueError -- If a required argument is empty.

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

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 frame-name assertion passed through to the selected- frame helper.

Contract:

• CASE-INSENSITIVE PREFIX match, anchored at the start of the identity. Narrower than the contains sibling.

• Empty prefix is rejected rather than matching everything.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof that a spell does not exist.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises.

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

Threading:

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

Lifecycle / Cleanup:

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

Raises:

• ValueError -- If a required argument is empty.

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

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 frame-name assertion passed through to the selected- frame helper.

Contract:

• Explains the ACL posture for one spell, including which sections are visible. This is the honest way to distinguish "absent" from "hidden", which the plain listers cannot express.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof that a spell does not exist.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises.

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

Threading:

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

Lifecycle / Cleanup:

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

Raises:

• ValueError -- If a required argument is empty.

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

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.

Purpose:

Give the operator one high-signal spell summary that combines record identity, provenance, ACL posture, and detailed payload availability in one place.

Contract:

• COMPOSITE of identity, origin and access in one call - a convenience over three separate queries, each of which is individually available.

• Because it fans out, it costs more than any single component; prefer the specific describer when you need only one part.

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

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

Threading:

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

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

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

Parameters:

• spell_source_id -- Published spell source id.

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

Returns:

Compact spell access 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, spell index, and visible sibling spells.

Contract:

• Walks OWNER -> ROOT -> PEERS to place the spell in the conduit topology.

• AN UNOWNED SPELL yields a None root and an EMPTY peer tuple rather than raising, so unowned is reported as data.

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

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

Threading:

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

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

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

Parameters:

• spell_source_id -- Published spell source id.

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

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 bound frame.

Parameters:

• left_spell_source_id -- Left visible spell source id.

• right_spell_source_id -- Right visible spell source id.

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

Contract:

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

• Compares recorded fields AND the ACL-filtered descriptions, so a reported difference can reflect DIFFERING VISIBILITY between the two spells rather than a real difference in the underlying spells.

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

• The two operands are not read atomically with respect to each other.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof that a spell does not exist.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises.

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

Threading:

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

Lifecycle / Cleanup:

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

Raises:

• ValueError -- If a required argument is empty.

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

Returns:

Visible spell comparison 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 frame-name assertion passed through to the selected- frame helper.

Contract:

• ACL-GATED SECTION READ that RAISES when the section is not visible, rather than reporting availability. That is the deliberate contrast with the describe_spell_* probes, which return a flag.

• Because it raises on hidden sections, a returned value is always genuinely visible data.

• Empty section_name is rejected up front.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof that a spell does not exist.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises.

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

Threading:

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

Lifecycle / Cleanup:

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

Raises:

• ValueError -- If a required argument is empty.

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

Returns:

ACL-visible spell payload section value.

Return type:

object

get_required_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 frame-name assertion passed through to the selected- frame helper.

Contract:

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

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

• Empty spell_source_id is rejected up front.

• VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present" - indistinguishable from outside. Never use an empty result as proof that a spell does not exist.

• frame_name is an ASSERTION passed through to the frame helper, not a selector. When supplied it must match the bound frame or the call raises.

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

Threading:

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

Lifecycle / Cleanup:

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

Raises:

• ValueError -- If a required argument is empty.

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

Returns:

Matching spell link.

Return type:

FrameLink

Topic reference · Full contents