On this page

ViewFrame
- ViewFrame

ViewFrame

Use md.ViewFrame from the public package namespace.

class ViewFrame(*, frame_name: str | None, frame_descriptor: FrameDescriptor | None, frame_acl_configuration: FrameACLConfiguration | None, compiled_access_surface: CompiledFrameACLAccessSurface | None, default_detail_level: str, action_hook_scope_factory: Callable[[...], Any] | None = None)[source]

Purpose:: Hold frame-scoped viewer helper methods for one selected frame.

Contract:

Operates only on one selected frame's descriptor and ACL state.

Returns ACL-filtered FrameLink objects and summaries.

Does not expose raw runtime objects.

Lifecycle:: Cleanup is idempotent and clears all bound references.
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 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 the anchor the conduit and spell helpers borrow: both operate through a ViewFrame bound to one selected frame, which is what keeps frame selection stated once rather than repeated per call. 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. Frame-local helper surface for visible targets, frame summaries, inventory, search, collision detection, and frame-local access explanations.

cleanup() → None[source]

Idempotently drop the borrowed frame-state references.

Contract:

Clears only the helper's own references and lock.

Never cleans the descriptor or ACL objects because they are borrowed runtime inputs.

Returns:: None.

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

Return the currently visible targets for the bound frame.

Contract:

Builds links from the bound descriptor plus compiled ACL surface.

Optionally filters that visible set down to one source kind.

Returns a fresh snapshot for this call.

Parameters:

frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.
source_kind -- Optional target-kind filter (frame, conduit, or spell).

Returns:

Ordered ACL-filtered targets.

Return type:

List[FrameLink]

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

Return summary descriptions for the current visible target snapshot.

Contract:

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

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

Parameters:

frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.
source_kind -- Optional target-kind filter.

Returns:

ACL-filtered target descriptions.

Return type:

List[Dict[str, object]]

describe_frame(*, frame_name: str | None = None) → Dict[str, object][source]

Return a compact summary of the visible frame surface.

Contract:

Summarizes only currently visible target kinds and counts.

Merges compiled ACL metadata with the frame's advertised Nexus contract when frame overview data is present.

Parameters:: frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.
Returns:: Frame summary with Nexus-contract metadata.
Return type:: Dict[str, object]

describe_frame_payload(*, frame_name: str | None = None) → Dict[str, object][source]

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

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

Contract:

Uses the bound FrameDescriptor and compiled ACL surface only.

Returns only fields present in CompiledFrameACLAccessSurface.frame_payload_fields.

Raises when the bound frame does not expose frame_overview.

Parameters:: frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.
Returns:: ACL-filtered frame payload description.
Return type:: Dict[str, object]

describe_frame_inventory(*, frame_name: str | None = None) → Dict[str, object][source]

Return a compact inventory of the bound frame surface.

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

Contract:

Counts only ACL-visible conduits and spells.

Preserves the currently visible target ids and source ids.

Parameters:: frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.
Returns:: Compact frame inventory summary.
Return type:: Dict[str, object]

describe_frame_access_contract(*, frame_name: str | None = None) → Dict[str, object][source]

Return the bound ACL access contract for the frame surface.

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

Contract:

Describes the ACL CONTRACT shaping this projection - the rules, not the data they filter.

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:: frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.
Returns:: Effective ACL access contract summary.
Return type:: Dict[str, object]

describe_frame_brief(*, frame_name: str | None = None) → Dict[str, object][source]

Return one compact operator-oriented frame summary.

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

Contract:

A summary of the frame rather than an inventory; cheap enough for polling where the full descriptions are not.

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:: frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.
Returns:: Compact frame-local summary.
Return type:: Dict[str, object]

describe_target_brief(*, source_kind: str, source_id: str, frame_name: str | None = None) → Dict[str, object][source]

Return one compact summary for a visible target.

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

Contract:

Identity-level summary for ONE target, without its payload.

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:

source_kind -- Required target kind.
source_id -- Required target source id.
frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.

Returns:

Compact visible target summary.

Return type:

Dict[str, object]

describe_missing_surface(*, frame_name: str | None = None) → Dict[str, object][source]

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

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

Contract:

Uses descriptor truth plus the compiled ACL surface only.

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

Does not expose hidden payload bodies.

Parameters:: frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.
Returns:: Missing/hidden surface summary.
Return type:: Dict[str, object]

describe_visible_collisions(*, frame_name: str | None = None) → Dict[str, object][source]

Return visible identity collisions for the bound frame.

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

Contract:

Groups visible spells FOUR WAYS at once - binding name, spell name, index id and spellframe - so one call surfaces every kind of ambiguity.

SPELLS WITH NO BINDING NAME ARE SKIPPED from the binding-name grouping but still counted in the others, so group sizes differ legitimately.

A collision is NOT an error: names are reusable by design. This reports ambiguity for a human to judge.

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:: frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.
Returns:: Visible collision and grouping summary.
Return type:: Dict[str, object]

describe_visible_surface(*, frame_name: str | None = None) → Dict[str, object][source]

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

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

Contract:

Uses only the bound frame descriptor plus the compiled ACL surface.

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

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

Parameters:: frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.
Returns:: Summary of the currently visible frame-local surface.
Return type:: Dict[str, object]

describe_visible_inventory_by_kind(*, frame_name: str | None = None) → Dict[str, Dict[str, object]][source]

Return visible inventory grouped by target kind.

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

Contract:

Inventory grouped by target kind; kinds with nothing visible are absent as keys rather than mapping to empty collections.

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:: frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.
Returns:: Inventory grouped by target kind.
Return type:: Dict[str, Dict[str, object]]

describe_frame_topology(*, frame_name: str | None = None) → Dict[str, object][source]

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

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

Contract:

COMPOSITE view: root conduits, the conduit tree, and spell ownership in one result, all built from the visible set.

Because every component is visibility-filtered, the topology can appear TRUNCATED - a tree may look rootless or a conduit parentless purely because intermediate nodes are invisible here.

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

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

Threading:: Reads a descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If the viewer is unbound or cleaned, or frame_name does not match the bound frame.
Parameters:: frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.
Returns:: Visible frame-local topology summary.
Return type:: Dict[str, object]

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

Return visible target ids for the bound frame.

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

Contract:

Flat id list across every kind. Use list_visible_target_ids_by_kind when you need the kind, and note that one returns link_id while the id listers return source_id.

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:

frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.
source_kind -- Optional target-kind filter.

Returns:

Visible target ids in deterministic order.

Return type:

List[str]

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

Return visible target ids grouped by target kind.

Parameters:: frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.

Contract:

Returns link_id values, NOT source_id. This is the one lister that does - list_visible_conduit_ids and list_visible_spell_source_ids both return source ids. Do not feed these ids into lookups that expect a source id.

Keys are SORTED, inherited from group_targets_by_kind.

VISIBILITY-FILTERED PROJECTION. Everything here is derived from the ACL-filtered target set, so absence means "not visible to this rift" OR "not present" - the two are indistinguishable from the outside. Never use an empty result as proof that something does not exist.

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

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

Threading:: Reads a descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If frame_name does not match the bound frame, or the viewer has been cleaned.
Returns:: Visible target ids grouped by kind.
Return type:: Dict[str, Tuple[str, ...]]

list_visible_conduit_ids(*, frame_name: str | None = None) → List[str][source]

Return visible conduit ids for the bound frame.

Parameters:: frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.

Contract:

Returns source_id values, one per visible conduit link, with NO deduplication and no ordering guarantee beyond the underlying target order.

VISIBILITY-FILTERED PROJECTION. Everything here is derived from the ACL-filtered target set, so absence means "not visible to this rift" OR "not present" - the two are indistinguishable from the outside. Never use an empty result as proof that something does not exist.

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

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

Threading:: Reads a descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If frame_name does not match the bound frame, or the viewer has been cleaned.
Returns:: Visible conduit ids in deterministic order.
Return type:: List[str]

list_visible_spell_source_ids(*, frame_name: str | None = None) → List[str][source]

Return visible spell source ids for the bound frame.

Parameters:: frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.

Contract:

Returns source_id values, one per visible spell link, with NO deduplication - the list is positionally aligned with the visible spell links, so repeats are meaningful rather than accidental.

VISIBILITY-FILTERED PROJECTION. Everything here is derived from the ACL-filtered target set, so absence means "not visible to this rift" OR "not present" - the two are indistinguishable from the outside. Never use an empty result as proof that something does not exist.

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

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

Threading:: Reads a descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If frame_name does not match the bound frame, or the viewer has been cleaned.
Returns:: Visible spell source ids in deterministic order.
Return type:: List[str]

list_visible_root_conduits(*, frame_name: str | None = None) → List[FrameLink][source]

Return visible conduit links that are also root conduits.

Parameters:: frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.

Contract:

Filters the visible conduit links down to those whose root_conduit_id equals their own id, so it returns TREE ROOTS as seen through this rift.

A conduit can look like a root here purely because its real parent is not visible to this rift. Root-ness in a projection is a statement about VISIBILITY, not about the underlying frame topology.

VISIBILITY-FILTERED PROJECTION. Absence means "not visible to this rift" OR "not present"; the two are indistinguishable from outside.

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

Read-only snapshot taken at call time.

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 frame_name does not match the bound frame, or the viewer has been cleaned.
Returns:: Visible root conduit links.
Return type:: List[FrameLink]

list_visible_binding_names(*, frame_name: str | None = None) → List[str][source]

Return visible spell binding names for the bound frame.

Parameters:: frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.

Contract:

SKIPS spells that have no binding name. The result is therefore SHORTER than the visible spell list and is NOT positionally aligned with it - do not zip it against list_visible_spell_names.

No deduplication; two spells may share a binding name.

VISIBILITY-FILTERED PROJECTION. Everything here is derived from the ACL-filtered target set, so absence means "not visible to this rift" OR "not present" - the two are indistinguishable from the outside. Never use an empty result as proof that something does not exist.

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

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

Threading:: Reads a descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If frame_name does not match the bound frame, or the viewer has been cleaned.
Returns:: Visible binding names in deterministic spell order.
Return type:: List[str]

list_visible_spell_names(*, frame_name: str | None = None) → List[str][source]

Return visible spell names for the bound frame.

Parameters:: frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.

Contract:

NOT deduplicated. Spell names are not unique, so the same name can appear more than once; the list is positionally aligned with the visible spell links.

VISIBILITY-FILTERED PROJECTION. Everything here is derived from the ACL-filtered target set, so absence means "not visible to this rift" OR "not present" - the two are indistinguishable from the outside. Never use an empty result as proof that something does not exist.

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

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

Threading:: Reads a descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If frame_name does not match the bound frame, or the viewer has been cleaned.
Returns:: Visible spell names in deterministic spell order.
Return type:: List[str]

list_visible_spellframes(*, frame_name: str | None = None) → List[str][source]

Return visible normalized spellframe values for the bound frame.

Parameters:: frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.

Contract:

DISTINCT, unlike the sibling listers. Duplicates are collapsed via a seen-set while FIRST-SEEN ORDER is preserved, so this is not sorted and not positionally aligned with the spell list.

Spells whose spellframe normalizes to None are skipped entirely.

VISIBILITY-FILTERED PROJECTION. Everything here is derived from the ACL-filtered target set, so absence means "not visible to this rift" OR "not present" - the two are indistinguishable from the outside. Never use an empty result as proof that something does not exist.

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

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

Threading:: Reads a descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If frame_name does not match the bound frame, or the viewer has been cleaned.
Returns:: Distinct visible spellframe values in deterministic order.
Return type:: List[str]

list_visible_index_ids(*, frame_name: str | None = None) → List[str][source]

Return visible spell-index ids for the bound frame.

Parameters:: frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.

Contract:

NOT deduplicated, and duplicates are EXPECTED: several spells can share one spell index, so the same index id repeats once per spell. Deduplicate yourself if you want distinct spell indexes.

Positionally aligned with the visible spell links.

VISIBILITY-FILTERED PROJECTION. Everything here is derived from the ACL-filtered target set, so absence means "not visible to this rift" OR "not present" - the two are indistinguishable from the outside. Never use an empty result as proof that something does not exist.

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

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

Threading:: Reads a descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If frame_name does not match the bound frame, or the viewer has been cleaned.
Returns:: Visible spell-index ids in deterministic spell order.
Return type:: List[str]

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

Return visible spell ownership grouped by conduit id.

Parameters:: frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.

Contract:

SKIPS spells with no owner conduit, so unowned spells - anything bound but not yet stamped by conjure - are ABSENT from the result entirely rather than grouped under a null key. The union of the values is therefore not the full visible spell set.

Keys are in insertion order, NOT sorted.

VISIBILITY-FILTERED PROJECTION. Everything here is derived from the ACL-filtered target set, so absence means "not visible to this rift" OR "not present" - the two are indistinguishable from the outside. Never use an empty result as proof that something does not exist.

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

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

Threading:: Reads a descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If frame_name does not match the bound frame, or the viewer has been cleaned.
Returns:: Visible spell source ids grouped by owner conduit id.
Return type:: Dict[str, Tuple[str, ...]]

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

Return visible conduit ids grouped by root conduit id.

Parameters:: frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.

Contract:

A root conduit appears BOTH as a key and inside its own value tuple, because a root's root_conduit_id is its own id. The value is the whole tree including the root, not just descendants.

Keys are in insertion order, NOT sorted.

Only visible conduits are grouped, so a tree can appear truncated when intermediate conduits are not visible to this rift.

VISIBILITY-FILTERED PROJECTION. Everything here is derived from the ACL-filtered target set, so absence means "not visible to this rift" OR "not present" - the two are indistinguishable from the outside. Never use an empty result as proof that something does not exist.

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

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

Threading:: Reads a descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If frame_name does not match the bound frame, or the viewer has been cleaned.
Returns:: Visible conduit ids grouped by root conduit id.
Return type:: Dict[str, Tuple[str, ...]]

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

Return visible targets whose identity contains one text fragment.

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

Contract:

CASE-INSENSITIVE SUBSTRING match, so it hits mid-string and returns strictly more than the prefix sibling.

Empty text is rejected rather than matching everything.

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:

text -- Case-insensitive text fragment to search for.
frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.
source_kind -- Optional target-kind filter.

Returns:

Matching visible targets in deterministic order.

Return type:

List[FrameLink]

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

Return visible targets whose identity starts with one prefix.

Parameters:

prefix -- Case-insensitive prefix to match against display names and source ids.
frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.
source_kind -- Optional target-kind filter.

Contract:

CASE-INSENSITIVE, and matches against EITHER the display name OR the source id - a hit on either one includes the target, so results can look unrelated to the visible name.

Prefix match only; use the contains-search sibling for substrings.

An empty prefix raises rather than matching everything.

VISIBILITY-FILTERED PROJECTION. Everything here is derived from the ACL-filtered target set, so absence means "not visible to this rift" OR "not present" - the two are indistinguishable from the outside. Never use an empty result as proof that something does not exist.

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

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

Threading:: Reads a descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If frame_name does not match the bound frame, or the viewer has been cleaned.
Returns:: Matching visible targets in deterministic order.
Return type:: List[FrameLink]

group_targets_by_kind(*, frame_name: str | None = None) → Dict[str, List[FrameLink]][source]

Return visible targets grouped by target kind.

Parameters:: frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.

Contract:

Keys are SORTED, so iteration order is deterministic across calls and processes.

Kinds with no visible targets are ABSENT as keys rather than mapping to an empty list; use .get(kind, []) rather than indexing.

VISIBILITY-FILTERED PROJECTION. Everything here is derived from the ACL-filtered target set, so absence means "not visible to this rift" OR "not present" - the two are indistinguishable from the outside. Never use an empty result as proof that something does not exist.

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

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

Threading:: Reads a descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If frame_name does not match the bound frame, or the viewer has been cleaned.
Returns:: Visible targets grouped by source kind.
Return type:: Dict[str, List[FrameLink]]

describe_target_identity(*, source_kind: str, source_id: str, frame_name: str | None = None) → Dict[str, object][source]

Return a compact identity summary for one visible target.

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

Contract:

Identity fields for one target - the stable naming, not payload or access.

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:

source_kind -- Required target kind.
source_id -- Required target source id.
frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.

Returns:

Visible target identity summary.

Return type:

Dict[str, object]

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

Return visible targets whose display name matches exactly.

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

Contract:

EXACT, CASE-SENSITIVE match, unlike the case-insensitive search helpers.

Returns a LIST because display names are NOT unique across the visible set.

Empty display_name is rejected up front.

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:

display_name -- Exact display name to match.
frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.
source_kind -- Optional target-kind filter.

Returns:

Matching visible targets.

Return type:

List[FrameLink]

explain_target_access(*, source_kind: str, source_id: str, frame_name: str | None = None) → Dict[str, object][source]

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

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

Contract:

THE HONEST ANSWER to "why can't I see this": it reports the ACL posture and which sections are visible, which the plain listers cannot express.

FRAME targets take a special path - existence is decided by matching the frame overview's id rather than by scanning the target set.

Empty source_kind or source_id is rejected up front.

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:

source_kind -- Target kind to inspect.
source_id -- Target source id to inspect.
frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.

Returns:

Visibility and section/field explanation for the requested target.

Return type:

Dict[str, object]

get_frame_payload_field(field_name: str, *, frame_name: str | None = None) → object[source]

Return one ACL-visible frame payload field or raise.

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

Contract:

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

Returns the normalized field value from the bound frame payload.

Parameters:

field_name -- Required frame payload field name.
frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.

Returns:

ACL-visible frame payload field value.

Return type:

object

get_required_target_by_source(*, frame_name: str | None = None, source_kind: str, source_id: str) → FrameLink[source]

Return one ACL-filtered target by source identity or raise.

Parameters:

frame_name -- Optional frame-name assertion. When supplied, it must match the bound frame.
source_kind -- Required target kind.
source_id -- Required target source identifier.

Contract:

RAISES rather than returning None when nothing matches, which is the distinction from the non-required lookups.

"Not found" here is AMBIGUOUS: the target may not exist, or it may exist and be filtered out by ACL for this rift. Do not treat the raise as proof of non-existence.

Empty source_kind or source_id is rejected up front.

VISIBILITY-FILTERED PROJECTION. Everything here is derived from the ACL-filtered target set, so absence means "not visible to this rift" OR "not present" - the two are indistinguishable from the outside. Never use an empty result as proof that something does not exist.

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

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

Threading:: Reads a descriptor snapshot; concurrent frame changes are not reflected in an already-returned result.
Lifecycle / Cleanup:: Guarded by check_cleaned().

Raises:: RuntimeError -- If frame_name does not match the bound frame, or the viewer has been cleaned.
Returns:: Matching ACL-filtered target.
Return type:: FrameLink

Topic reference · Full contents