On this page

ViewMultiFrame
- ViewMultiFrame

ViewMultiFrame

Use md.ViewMultiFrame from the public package namespace.

class ViewMultiFrame(*, viewer: FrameViewer)[source]

Purpose:: Hold descriptor-oriented multi-frame and record-level viewer methods.

Contract:

Owns only a borrowed reference to the parent FrameViewer.

Reuses the viewer's private descriptor and record utilities instead of duplicating lookup logic or Rift access.

Exposes cross-frame and descriptor-hosted inventory/comparison logic without introducing frame-local helper binding state.

Lifecycle:: Cleanup is idempotent and clears only the borrowed viewer reference. ViewMultiFrame is cheap to create and may be materialized on demand.
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 multi-frame-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 DESCRIPTOR-ORIENTED specifically because cross-frame questions must be answerable without reaching into any one frame's runtime - the widest scope is deliberately the shallowest surface. 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. Descriptor-oriented cross-frame viewer helper. Use it to compare frames and read descriptor records without touching any frame's runtime. Obtained from FrameViewer.

cleanup() → None[source]

Idempotently drop the borrowed viewer reference.

Contract:

Safe to call more than once.

Clears only the helper's borrowed viewer reference.

Returns:: None.

list_frame_names() → List[str][source]

Return the currently linked frame names in deterministic order.

Contract:

SORTED, so iteration order is deterministic across calls.

Scoped to the frames this rift is ASSIGNED. Frames the rift cannot reach are absent, so this is a reachability list, not a census of the process.

DESCRIPTOR-LEVEL, CROSS-FRAME surface. Access is scoped at FRAME granularity by the rift's assigned/accessible frame lists, and within a reachable frame this reads descriptor records directly rather than the per-target ACL-filtered link set used by ViewFrame / ViewSpell. Results here therefore need not match those helpers for the same frame.

frame_name is a per-call FILTER at this layer, not a bound-frame assertion: None means "every reachable frame".

Read-only; it resolves through the parent viewer per query rather than from one frozen snapshot, so two calls can observe different state.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads and are not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned - this helper must not outlive it.

Raises:

ValueError -- If a required argument is empty.
RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.

Returns:

Sorted linked frame names.

Return type:

List[str]

list_linked_frame_names() → List[str][source]

Return the currently linked frame names in deterministic order.

Contract:

CURRENTLY IDENTICAL to list_frame_names() - it delegates straight to it, so "linked" and "assigned" name the same set today. Treat the two as interchangeable, and prefer list_frame_names() unless you specifically mean linkage.

DESCRIPTOR-LEVEL, CROSS-FRAME surface. Access is scoped at FRAME granularity by the rift's assigned/accessible frame lists, and within a reachable frame this reads descriptor records directly rather than the per-target ACL-filtered link set used by ViewFrame / ViewSpell. Results here therefore need not match those helpers for the same frame.

frame_name is a per-call FILTER at this layer, not a bound-frame assertion: None means "every reachable frame".

Read-only; it resolves through the parent viewer per query rather than from one frozen snapshot, so two calls can observe different state.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads and are not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned - this helper must not outlive it.

Raises:

ValueError -- If a required argument is empty.
RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.

Returns:

Sorted linked frame names.

Return type:

List[str]

list_nexus_frame_names() → List[str][source]

Return the currently accessible Nexus-managed frame names.

Contract:

SORTED, and scoped to the NEXUS-hosted frames this rift can access.

Complementary to list_non_nexus_frame_names(); together they cover the accessible set, and neither includes frames the rift cannot reach.

DESCRIPTOR-LEVEL, CROSS-FRAME surface. Access is scoped at FRAME granularity by the rift's assigned/accessible frame lists, and within a reachable frame this reads descriptor records directly rather than the per-target ACL-filtered link set used by ViewFrame / ViewSpell. Results here therefore need not match those helpers for the same frame.

frame_name is a per-call FILTER at this layer, not a bound-frame assertion: None means "every reachable frame".

Read-only; it resolves through the parent viewer per query rather than from one frozen snapshot, so two calls can observe different state.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads and are not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned - this helper must not outlive it.

Raises:

ValueError -- If a required argument is empty.
RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.

Returns:

Sorted accessible Nexus-managed frame names.

Return type:

List[str]

list_non_nexus_frame_names() → List[str][source]

Return the currently accessible published non-Nexus frame names.

Contract:

SORTED, and scoped to the accessible frames that are NOT nexus-hosted.

Complementary to list_nexus_frame_names().

DESCRIPTOR-LEVEL, CROSS-FRAME surface. Access is scoped at FRAME granularity by the rift's assigned/accessible frame lists, and within a reachable frame this reads descriptor records directly rather than the per-target ACL-filtered link set used by ViewFrame / ViewSpell. Results here therefore need not match those helpers for the same frame.

frame_name is a per-call FILTER at this layer, not a bound-frame assertion: None means "every reachable frame".

Read-only; it resolves through the parent viewer per query rather than from one frozen snapshot, so two calls can observe different state.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads and are not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned - this helper must not outlive it.

Raises:

ValueError -- If a required argument is empty.
RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.

Returns:

Sorted accessible published non-Nexus frame names.

Return type:

List[str]

count_frames() → int[source]

Return the number of hosted frame descriptors.

Contract:

Counts REACHABLE frames only - it is the length of list_frame_names(), so it inherits that method's assigned-frame scoping and is not a count of frames in the process.

DESCRIPTOR-LEVEL, CROSS-FRAME surface. Access is scoped at FRAME granularity by the rift's assigned/accessible frame lists, and within a reachable frame this reads descriptor records directly rather than the per-target ACL-filtered link set used by ViewFrame / ViewSpell. Results here therefore need not match those helpers for the same frame.

frame_name is a per-call FILTER at this layer, not a bound-frame assertion: None means "every reachable frame".

Read-only; it resolves through the parent viewer per query rather than from one frozen snapshot, so two calls can observe different state.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads and are not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned - this helper must not outlive it.

Raises:

ValueError -- If a required argument is empty.
RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.

Returns:

Hosted frame count.

Return type:

int

count_root_conduits(*, frame_name: str | None = None) → int[source]

Return the number of root conduit records.

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

Contract:

Counts DISTINCT root conduit ids PER FRAME and sums those counts. A root id present in two frames is therefore counted TWICE - this is a sum of per-frame totals, not a distinct count across frames.

frame_name=None spans every reachable frame; supplying one narrows to that frame.

DESCRIPTOR-LEVEL, CROSS-FRAME surface. Access is scoped at FRAME granularity by the rift's assigned/accessible frame lists, and within a reachable frame this reads descriptor records directly rather than the per-target ACL-filtered link set used by ViewFrame / ViewSpell. Results here therefore need not match those helpers for the same frame.

frame_name is a per-call FILTER at this layer, not a bound-frame assertion: None means "every reachable frame".

Read-only; it resolves through the parent viewer per query rather than from one frozen snapshot, so two calls can observe different state.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads and are not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned - this helper must not outlive it.

Raises:

ValueError -- If a required argument is empty.
RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.

Returns:

Root conduit record count.

Return type:

int

count_spell_records(*, frame_name: str | None = None) → int[source]

Return the number of spell records.

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

Contract:

Counts DESCRIPTOR RECORDS, so it counts spells as the frame descriptor holds them rather than as the ACL-filtered projection exposes them. It will not necessarily equal the length of ViewSpell.list_spells(...) for the same frame.

Sums per-frame totals; frame_name=None spans every reachable frame.

DESCRIPTOR-LEVEL, CROSS-FRAME surface. Access is scoped at FRAME granularity by the rift's assigned/accessible frame lists, and within a reachable frame this reads descriptor records directly rather than the per-target ACL-filtered link set used by ViewFrame / ViewSpell. Results here therefore need not match those helpers for the same frame.

frame_name is a per-call FILTER at this layer, not a bound-frame assertion: None means "every reachable frame".

Read-only; it resolves through the parent viewer per query rather than from one frozen snapshot, so two calls can observe different state.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads and are not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned - this helper must not outlive it.

Raises:

ValueError -- If a required argument is empty.
RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.

Returns:

Spell record count.

Return type:

int

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

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:

Frame overview plus record counts. THE OVERVIEW MAY BE ABSENT, in which case frame_id, nexus_label and nexus_version are None rather than the call failing - None means "no overview recorded", not "no frame".

DESCRIPTOR-LEVEL and CROSS-FRAME: scoped at FRAME granularity by the rift's reachable frames, then reading descriptor records directly rather than the ACL-filtered link set, so results need not match ViewFrame / ViewSpell for the same frame.

frame_name is a per-call FILTER here; None means every reachable frame.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads, not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned.

Raises:: RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.
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]][source]

Return descriptor-level summaries for all hosted frames.

Contract:

Describes EVERY reachable frame in one call, so its cost scales with frame count - it is a fan-out over describe_frame, not a bulk query.

Keys are the frame names; a frame the rift cannot reach is absent rather than present with an empty description.

DESCRIPTOR-LEVEL, CROSS-FRAME surface. Access is scoped at FRAME granularity by the rift's assigned/accessible frame lists, and within a reachable frame this reads descriptor records directly rather than the per-target ACL-filtered link set used by ViewFrame / ViewSpell. Results here therefore need not match those helpers for the same frame.

frame_name is a per-call FILTER at this layer, not a bound-frame assertion: None means "every reachable frame".

Read-only; it resolves through the parent viewer per query rather than from one frozen snapshot, so two calls can observe different state.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads and are not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned - this helper must not outlive it.

Raises:

ValueError -- If a required argument is empty.
RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.

Returns:

Hosted frame summaries keyed by frame name.

Return type:

Dict[str, Dict[str, object]]

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

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][source]

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_frames_inventory() → Dict[str, Dict[str, object]][source]

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]]

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

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][source]

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][source]

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:

CROSS-FRAME comparison of conduit inventories: record ids and root ids on each side.

Reports differences and never reconciles them.

The two frames are not read atomically with respect to each other, so a concurrently changing frame can produce a comparison that was never simultaneously true.

DESCRIPTOR-LEVEL, CROSS-FRAME surface. Access is scoped at FRAME granularity by the rift's assigned/accessible frame lists, and within a reachable frame this reads descriptor records directly rather than the per-target ACL-filtered link set used by ViewFrame / ViewSpell. Results here therefore need not match those helpers for the same frame.

frame_name is a per-call FILTER at this layer, not a bound-frame assertion: None means "every reachable frame".

Read-only; it resolves through the parent viewer per query rather than from one frozen snapshot, so two calls can observe different state.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads and are not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned - this helper must not outlive it.

Raises:

ValueError -- If a required argument is empty.
RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.

Returns:

Conduit-record comparison summary.

Return type:

Dict[str, object]

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

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:

CROSS-FRAME comparison across FOUR axes - source ids, index ids, spell names and binding names - so two frames can agree on names while differing on identity, which is exactly the case this surfaces.

Reports differences and never reconciles them.

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

DESCRIPTOR-LEVEL, CROSS-FRAME surface. Access is scoped at FRAME granularity by the rift's assigned/accessible frame lists, and within a reachable frame this reads descriptor records directly rather than the per-target ACL-filtered link set used by ViewFrame / ViewSpell. Results here therefore need not match those helpers for the same frame.

frame_name is a per-call FILTER at this layer, not a bound-frame assertion: None means "every reachable frame".

Read-only; it resolves through the parent viewer per query rather than from one frozen snapshot, so two calls can observe different state.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads and are not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned - this helper must not outlive it.

Raises:

ValueError -- If a required argument is empty.
RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.

Returns:

Spell-record comparison summary.

Return type:

Dict[str, object]

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

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:

Groups spells sharing a BINDING NAME. Collisions are legitimate - binding names are reusable across frames - so this reports ambiguity, not a defect.

DESCRIPTOR-LEVEL and CROSS-FRAME: scoped at FRAME granularity by the rift's reachable frames, then reading descriptor records directly rather than the ACL-filtered link set, so results need not match ViewFrame / ViewSpell for the same frame.

frame_name is a per-call FILTER here; None means every reachable frame.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads, not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned.

Raises:: RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.
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, ...]][source]

Return spell-name collisions in the selected descriptor scope.

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

Contract:

Groups spells that SHARE A SPELL NAME. A collision is NOT an error: names are legitimately reusable across spellframes and binding names, so this reports ambiguity for a human to judge, not a defect.

frame_name=None spans every reachable frame, which is where genuine cross-frame ambiguity shows up.

DESCRIPTOR-LEVEL, CROSS-FRAME surface. Access is scoped at FRAME granularity by the rift's assigned/accessible frame lists, and within a reachable frame this reads descriptor records directly rather than the per-target ACL-filtered link set used by ViewFrame / ViewSpell. Results here therefore need not match those helpers for the same frame.

frame_name is a per-call FILTER at this layer, not a bound-frame assertion: None means "every reachable frame".

Read-only; it resolves through the parent viewer per query rather than from one frozen snapshot, so two calls can observe different state.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads and are not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned - this helper must not outlive it.

Raises:

ValueError -- If a required argument is empty.
RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.

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, ...]][source]

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:

Groups by spell INDEX id, so each group is one version LINEAGE rather than one spell.

DESCRIPTOR-LEVEL and CROSS-FRAME: scoped at FRAME granularity by the rift's reachable frames, then reading descriptor records directly rather than the ACL-filtered link set, so results need not match ViewFrame / ViewSpell for the same frame.

frame_name is a per-call FILTER here; None means every reachable frame.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads, not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned.

Raises:: RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.
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, ...]][source]

Return spellframe groups in the selected descriptor scope.

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

Contract:

Groups by NORMALIZED spellframe value; spells whose spellframe normalizes to nothing are absent from every group.

DESCRIPTOR-LEVEL and CROSS-FRAME: scoped at FRAME granularity by the rift's reachable frames, then reading descriptor records directly rather than the ACL-filtered link set, so results need not match ViewFrame / ViewSpell for the same frame.

frame_name is a per-call FILTER here; None means every reachable frame.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads, not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned.

Raises:: RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.
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]][source]

Return spellbook groups whose permission posture is not uniform.

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

Contract:

Reports where the SAME spell carries DIFFERENT permission postures across spellbooks. Divergence is the finding; this method does not decide which side is correct and changes nothing.

Compares the permission enum's .name, so it is exact, not normalized.

DESCRIPTOR-LEVEL, CROSS-FRAME surface. Access is scoped at FRAME granularity by the rift's assigned/accessible frame lists, and within a reachable frame this reads descriptor records directly rather than the per-target ACL-filtered link set used by ViewFrame / ViewSpell. Results here therefore need not match those helpers for the same frame.

frame_name is a per-call FILTER at this layer, not a bound-frame assertion: None means "every reachable frame".

Read-only; it resolves through the parent viewer per query rather than from one frozen snapshot, so two calls can observe different state.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads and are not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned - this helper must not outlive it.

Raises:

ValueError -- If a required argument is empty.
RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.

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]][source]

Return spellbook groups whose existence posture is not uniform.

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

Contract:

Reports where the SAME spell carries DIFFERENT existence policies across spellbooks - the lifetime equivalent of the permission mismatch report. A mismatch means one book would produce a singleton where another produces per-call instances.

Compares the existence enum's .name, so it is exact, not normalized.

DESCRIPTOR-LEVEL, CROSS-FRAME surface. Access is scoped at FRAME granularity by the rift's assigned/accessible frame lists, and within a reachable frame this reads descriptor records directly rather than the per-target ACL-filtered link set used by ViewFrame / ViewSpell. Results here therefore need not match those helpers for the same frame.

frame_name is a per-call FILTER at this layer, not a bound-frame assertion: None means "every reachable frame".

Read-only; it resolves through the parent viewer per query rather than from one frozen snapshot, so two calls can observe different state.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads and are not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned - this helper must not outlive it.

Raises:

ValueError -- If a required argument is empty.
RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.

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][source]

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:

Compares two frames' spell records and REPORTS differences without reconciling them.

The two sides are not read atomically, so a concurrently changing frame can yield a comparison that was never simultaneously true.

DESCRIPTOR-LEVEL and CROSS-FRAME: scoped at FRAME granularity by the rift's reachable frames, then reading descriptor records directly rather than the ACL-filtered link set, so results need not match ViewFrame / ViewSpell for the same frame.

frame_name is a per-call FILTER here; None means every reachable frame.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads, not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned.

Raises:

RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.

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][source]

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:

Compares TWO CONDUITS THAT MAY LIVE IN DIFFERENT FRAMES, which is what distinguishes this from ViewConduit.compare_conduits. The result carries same_frame precisely because a cross-frame comparison is legal here.

Each operand resolves its own frame, so both frame names are optional and independent.

Reports differences and never reconciles them; the two operands are not read atomically.

DESCRIPTOR-LEVEL, CROSS-FRAME surface. Access is scoped at FRAME granularity by the rift's assigned/accessible frame lists, and within a reachable frame this reads descriptor records directly rather than the per-target ACL-filtered link set used by ViewFrame / ViewSpell. Results here therefore need not match those helpers for the same frame.

frame_name is a per-call FILTER at this layer, not a bound-frame assertion: None means "every reachable frame".

Read-only; it resolves through the parent viewer per query rather than from one frozen snapshot, so two calls can observe different state.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads and are not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned - this helper must not outlive it.

Raises:

ValueError -- If a required argument is empty.
RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.

Returns:

Record-level conduit comparison summary.

Return type:

Dict[str, object]

list_spell_source_ids_for_frame(frame_name: str) → List[str][source]

Return spell source ids for one hosted frame.

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

Contract:

Built source ids for one frame, NOT deduplicated.

DESCRIPTOR-LEVEL and CROSS-FRAME: scoped at FRAME granularity by the rift's reachable frames, then reading descriptor records directly rather than the ACL-filtered link set, so results need not match ViewFrame / ViewSpell for the same frame.

frame_name is a per-call FILTER here; None means every reachable frame.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads, not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned.

Raises:: RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.
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][source]

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]][source]

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[source]

Return the number of published conduit records.

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

Contract:

Counts DESCRIPTOR RECORDS, so it need not equal what ViewConduit exposes for the same frame.

DESCRIPTOR-LEVEL and CROSS-FRAME: scoped at FRAME granularity by the rift's reachable frames, then reading descriptor records directly rather than the ACL-filtered link set, so results need not match ViewFrame / ViewSpell for the same frame.

frame_name is a per-call FILTER here; None means every reachable frame.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads, not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned.

Raises:: RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.
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][source]

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:

Descriptor-level conduit ids, including conduits the per-target ACL would hide from ViewConduit.

DESCRIPTOR-LEVEL and CROSS-FRAME: scoped at FRAME granularity by the rift's reachable frames, then reading descriptor records directly rather than the ACL-filtered link set, so results need not match ViewFrame / ViewSpell for the same frame.

frame_name is a per-call FILTER here; None means every reachable frame.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads, not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned.

Raises:: RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.
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][source]

Return root conduit ids for the selected descriptor scope.

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

Contract:

Roots by descriptor record, so unlike the projection helpers this is not distorted by invisible parents.

DESCRIPTOR-LEVEL and CROSS-FRAME: scoped at FRAME granularity by the rift's reachable frames, then reading descriptor records directly rather than the ACL-filtered link set, so results need not match ViewFrame / ViewSpell for the same frame.

frame_name is a per-call FILTER here; None means every reachable frame.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads, not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned.

Raises:: RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.
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[source]

Return the number of distinct published origin spellbooks.

Purpose:: Surface spellbook provenance breadth at the descriptor host level.

Contract:

DERIVED: it is the length of list_origin_spellbook_ids(...), so it counts DISTINCT origin spellbooks rather than spells.

DESCRIPTOR-LEVEL and CROSS-FRAME: scoped at FRAME granularity by the rift's reachable frames, then reading descriptor records directly rather than the ACL-filtered link set, so results need not match ViewFrame / ViewSpell for the same frame.

frame_name is a per-call FILTER here; None means every reachable frame.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads, not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned.

Raises:: RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.
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][source]

Return distinct origin spellbook ids for the selected scope.

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

Contract:

ORIGIN spellbooks - the books that first bound each spell - not the books that own them now after a graft or transfer.

DESCRIPTOR-LEVEL and CROSS-FRAME: scoped at FRAME granularity by the rift's reachable frames, then reading descriptor records directly rather than the ACL-filtered link set, so results need not match ViewFrame / ViewSpell for the same frame.

frame_name is a per-call FILTER here; None means every reachable frame.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads, not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned.

Raises:: RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.
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][source]

Return published spell record ids for the selected scope.

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

Contract:

Descriptor-level spell ids for the selected frame scope.

DESCRIPTOR-LEVEL and CROSS-FRAME: scoped at FRAME granularity by the rift's reachable frames, then reading descriptor records directly rather than the ACL-filtered link set, so results need not match ViewFrame / ViewSpell for the same frame.

frame_name is a per-call FILTER here; None means every reachable frame.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads, not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned.

Raises:: RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.
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]][source]

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:

The descriptor's RECORD KEYS, which are the internal index into spell_records_by_key - not the same thing as spell source ids.

DESCRIPTOR-LEVEL and CROSS-FRAME: scoped at FRAME granularity by the rift's reachable frames, then reading descriptor records directly rather than the ACL-filtered link set, so results need not match ViewFrame / ViewSpell for the same frame.

frame_name is a per-call FILTER here; None means every reachable frame.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads, not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned.

Raises:: RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.
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][source]

Return published spell names for the selected scope.

Purpose:: Expose spell-name inventory directly from SpellRecord metadata.

Contract:

Spell names across the scope, NOT deduplicated - names are reusable.

DESCRIPTOR-LEVEL and CROSS-FRAME: scoped at FRAME granularity by the rift's reachable frames, then reading descriptor records directly rather than the ACL-filtered link set, so results need not match ViewFrame / ViewSpell for the same frame.

frame_name is a per-call FILTER here; None means every reachable frame.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads, not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned.

Raises:: RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.
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][source]

Return published binding names for the selected scope.

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

Contract:

Binding names across the scope. Spells with no binding name contribute nothing, so this is shorter than the spell list and NOT aligned with it.

DESCRIPTOR-LEVEL and CROSS-FRAME: scoped at FRAME granularity by the rift's reachable frames, then reading descriptor records directly rather than the ACL-filtered link set, so results need not match ViewFrame / ViewSpell for the same frame.

frame_name is a per-call FILTER here; None means every reachable frame.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads, not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned.

Raises:: RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.
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][source]

Return spell-index ids for the selected descriptor scope.

Purpose:: Expose SpellIndex identity directly from SpellRecord metadata.

Contract:

Index ids across the scope. Duplicates are EXPECTED, since many spells share one lineage.

DESCRIPTOR-LEVEL and CROSS-FRAME: scoped at FRAME granularity by the rift's reachable frames, then reading descriptor records directly rather than the ACL-filtered link set, so results need not match ViewFrame / ViewSpell for the same frame.

frame_name is a per-call FILTER here; None means every reachable frame.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads, not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned.

Raises:: RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.
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][source]

Return normalized spellframe values for the selected scope.

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

Contract:

Normalized spellframe values across the scope.

DESCRIPTOR-LEVEL and CROSS-FRAME: scoped at FRAME granularity by the rift's reachable frames, then reading descriptor records directly rather than the ACL-filtered link set, so results need not match ViewFrame / ViewSpell for the same frame.

frame_name is a per-call FILTER here; None means every reachable frame.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads, not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned.

Raises:: RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.
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][source]

Return distinct spell permission names for the selected scope.

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

Contract:

DISTINCT and SORTED: values are collected into a set and then sorted, so this lists which permission postures are IN USE, not one entry per spell.

DESCRIPTOR-LEVEL and CROSS-FRAME: scoped at FRAME granularity by the rift's reachable frames, then reading descriptor records directly rather than the ACL-filtered link set, so results need not match ViewFrame / ViewSpell for the same frame.

frame_name is a per-call FILTER here; None means every reachable frame.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads, not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned.

Raises:: RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.
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][source]

Return distinct spell existence kinds for the selected scope.

Purpose:: Surface spell lifetime categories directly from SpellRecord metadata.

Contract:

DISTINCT and SORTED, like list_permissions - which existence policies are in use, not one entry per spell.

DESCRIPTOR-LEVEL and CROSS-FRAME: scoped at FRAME granularity by the rift's reachable frames, then reading descriptor records directly rather than the ACL-filtered link set, so results need not match ViewFrame / ViewSpell for the same frame.

frame_name is a per-call FILTER here; None means every reachable frame.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads, not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned.

Raises:: RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.
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][source]

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][source]

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]][source]

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:

Full descriptor-level conduit descriptions; cost scales with record count.

DESCRIPTOR-LEVEL and CROSS-FRAME: scoped at FRAME granularity by the rift's reachable frames, then reading descriptor records directly rather than the ACL-filtered link set, so results need not match ViewFrame / ViewSpell for the same frame.

frame_name is a per-call FILTER here; None means every reachable frame.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads, not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned.

Raises:: RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.
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]][source]

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:

Full descriptor-level spell descriptions; cost scales with record count.

DESCRIPTOR-LEVEL and CROSS-FRAME: scoped at FRAME granularity by the rift's reachable frames, then reading descriptor records directly rather than the ACL-filtered link set, so results need not match ViewFrame / ViewSpell for the same frame.

frame_name is a per-call FILTER here; None means every reachable frame.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads, not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned.

Raises:: RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.
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][source]

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][source]

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:

EXACT, CASE-SENSITIVE match on owner conduit id.

Spells bound but NOT YET OWNED have no owner and match nothing here.

DESCRIPTOR-LEVEL and CROSS-FRAME: scoped at FRAME granularity by the rift's reachable frames, then reading descriptor records directly rather than the ACL-filtered link set, so results need not match ViewFrame / ViewSpell for the same frame.

frame_name is a per-call FILTER here; None means every reachable frame.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads, not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned.

Raises:

RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.

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][source]

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:

EXACT, CASE-SENSITIVE match on the ORIGIN spellbook id - the book that first bound the spell, not necessarily the book that owns it now.

Empty spellbook_id is rejected up front.

Returns BUILT spell source ids, not links.

DESCRIPTOR-LEVEL, CROSS-FRAME surface. Access is scoped at FRAME granularity by the rift's assigned/accessible frame lists, and within a reachable frame this reads descriptor records directly rather than the per-target ACL-filtered link set used by ViewFrame / ViewSpell. Results here therefore need not match those helpers for the same frame.

frame_name is a per-call FILTER at this layer, not a bound-frame assertion: None means "every reachable frame".

Read-only; it resolves through the parent viewer per query rather than from one frozen snapshot, so two calls can observe different state.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads and are not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned - this helper must not outlive it.

Raises:

ValueError -- If a required argument is empty.
RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.

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][source]

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:

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

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

Empty input is rejected up front.

Returns BUILT spell source ids, not links.

DESCRIPTOR-LEVEL, CROSS-FRAME surface. Access is scoped at FRAME granularity by the rift's assigned/accessible frame lists, and within a reachable frame this reads descriptor records directly rather than the per-target ACL-filtered link set used by ViewFrame / ViewSpell. Results here therefore need not match those helpers for the same frame.

frame_name is a per-call FILTER at this layer, not a bound-frame assertion: None means "every reachable frame".

Read-only; it resolves through the parent viewer per query rather than from one frozen snapshot, so two calls can observe different state.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads and are not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned - this helper must not outlive it.

Raises:

ValueError -- If a required argument is empty.
RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.

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][source]

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:

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

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

Empty input is rejected up front.

Returns BUILT spell source ids, not links.

DESCRIPTOR-LEVEL, CROSS-FRAME surface. Access is scoped at FRAME granularity by the rift's assigned/accessible frame lists, and within a reachable frame this reads descriptor records directly rather than the per-target ACL-filtered link set used by ViewFrame / ViewSpell. Results here therefore need not match those helpers for the same frame.

frame_name is a per-call FILTER at this layer, not a bound-frame assertion: None means "every reachable frame".

Read-only; it resolves through the parent viewer per query rather than from one frozen snapshot, so two calls can observe different state.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads and are not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned - this helper must not outlive it.

Raises:

ValueError -- If a required argument is empty.
RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.

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][source]

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:

EXACT match against the NORMALIZED spellframe value, and unlike the permission and existence listers it is CASE-SENSITIVE. Pass the normalized form rather than the raw bind-time object.

Empty spellframe_name is rejected up front.

Returns BUILT spell source ids, not links.

DESCRIPTOR-LEVEL, CROSS-FRAME surface. Access is scoped at FRAME granularity by the rift's assigned/accessible frame lists, and within a reachable frame this reads descriptor records directly rather than the per-target ACL-filtered link set used by ViewFrame / ViewSpell. Results here therefore need not match those helpers for the same frame.

frame_name is a per-call FILTER at this layer, not a bound-frame assertion: None means "every reachable frame".

Read-only; it resolves through the parent viewer per query rather than from one frozen snapshot, so two calls can observe different state.

Threading:: Resolves descriptors through the parent viewer per query; multi-frame results are assembled across several reads and are not one atomic snapshot.
Lifecycle / Cleanup:: Guarded by check_cleaned(). The parent viewer is BORROWED, not owned - this helper must not outlive it.

Raises:

ValueError -- If a required argument is empty.
RuntimeError -- If a frame cannot be resolved, or the helper or its parent viewer has been cleaned.

Returns:

Matching spell source ids in deterministic order.

Return type:

List[str]

Topic reference · Full contents