On this page

CommandSystem
- CommandSystem

CommandSystem

Receive this surface through rift.space.command_system; use that owning object's public entry point.

Implementation source

class CommandSystem(*, rift: Rift, space: RiftSpace, workstation: Workstation)[source]

Internal

Room-local shared command infrastructure plus common read/target helpers.

Purpose:: Provide shared command infrastructure above the viewer/workstation split without owning every room-specific command vocabulary.

Contract:

Uses the owning Rift command projections as the shared command substrate.

Enforces compiled command ACL state on direct fetch paths before exposing frame/conduit/spell runtime objects.

Uses the owned workstation for active-target attribute/method getters and method execution.

Does not store results itself. Callers that want persistence must bind returned values into the workstation explicitly.

Leaves room-owned topology mutation and spell activation commands to room-specific subclasses instead of pretending every room owns the same broad public surface.

Lifecycle:: Owned by one RiftSpace. Cleanup drops references to the owning room and workstation but does not clean those children itself.
Threading:: Room-confined. It holds no cross-room state and takes no lock of its own; the ACL projections it enforces against are refreshed by the owning Rift.
Registration:: MELDER KERNEL. The three postures are melder-internal and constructed by their owning room (for example CapabilityRiftSpace builds CapabilityCommandSystem), with no user injection seam.
Subsystem Context:: The MEDIATED command layer above the viewer/workstation split. FrameViewer answers read questions, Workstation holds bindings and the active target, and this class is the controlled surface through which getters and executes actually run. Room-specific subclasses add the vocabulary that does not belong to every room.
System Context:: Two rules define this class and both are about refusing convenience. First, ACL IS ENFORCED ON THE DIRECT FETCH PATH - compiled command ACL state is checked BEFORE any frame, conduit, or spell runtime object is exposed. Checking after would mean the object had already escaped. Second, IT DOES NOT STORE RESULTS. A caller that wants persistence must bind the returned value into the workstation explicitly. Auto-storing would make every read silently extend object lifetime and quietly populate a room's canvas with things nobody chose to keep. The subclass split exists because pretending every room owns the same broad public surface is exactly the lie the room modes exist to prevent: CapabilityCommandSystem owns topology mutation and direct activation, StaticCommandSystem owns live-only retrieval and reuse-only activation, and CodegenCommandSystem owns the validate/execute seams plus the full research command family.

AGENT_ACCESS: internal

AGENT_PURPOSE:: access: internal. Room-local shared command infrastructure plus common read/target helpers. Melder kernel machinery: read it to understand the runtime, do not drive it directly.

cleanup() → None[source]

Internal

Idempotently clear command-system-owned references.

Contract:

Safe to call more than once.

Clears only command-system-owned references.

Does not cleanup the owning RiftSpace or its workstation, because those remain owned by the room itself.

Returns:: None.

property command_system_id: str

Return the stable command-system identifier.

Returns:: Stable command-system id.
Return type:: str

property owner_space_id: str

Return the owning room identifier.

Returns:: Owning RiftSpace id.
Return type:: str

describe_spells_in_conduit(conduit_id: str, *, frame_name: str | None = None) → List[dict[str, Any]][source]

Return the spell description payloads exposed by one conduit.

Purpose:: Provide a structured spell-description surface for one runtime conduit through the shared command API.

Contract:

Resolves the conduit through command ACL and descriptor truth before touching runtime conduit state.

Returns the lower conduit runtime's current spell description payloads as a list without additional filtering.

Uses one top-level command action boundary for gate admission and memory emission.

Parameters:

conduit_id -- Conduit id whose spell descriptions should be returned.
frame_name -- Optional frame name. When omitted, the room default frame is used.

Returns:

Runtime spell description payloads for the conduit.

Return type:

List[dict[str, Any]]

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

Return the conduit-scoped resolution state for one conduit.

Purpose:: Expose the lower conduit runtime's current resolution-state object through the shared command surface.

Contract:

Resolves the conduit through command ACL and descriptor truth before touching runtime conduit state.

Returns the live lower-runtime resolution-state object directly.

Uses one top-level command action boundary for gate admission and memory emission.

Parameters:

conduit_id -- Conduit id whose resolution state should be returned.
frame_name -- Optional frame name. When omitted, the room default frame is used.

Returns:

Live conduit-scoped resolution-state object.

Return type:

object

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

Return the active spellspace for one conduit, if any.

Purpose:: Expose the lower conduit runtime's active spellspace surface through the shared command API.

Contract:

Resolves the conduit through command ACL and descriptor truth before touching runtime conduit state.

Returns the currently active spellspace object or whatever the lower runtime exposes for the no-active-spellspace case.

Uses one top-level command action boundary for gate admission and memory emission.

Parameters:

conduit_id -- Conduit id whose active spellspace should be returned.
frame_name -- Optional frame name. When omitted, the room default frame is used.

Returns:

Active spellspace object or lower-runtime sentinel value.

Return type:

object

find_spell_id(conduit_id: str, spellframe: str, spell_name: str, binding_name: str, *, frame_name: str | None = None) → object[source]

Return the current spell id resolved from logical spell identifiers.

Purpose:: Mirror the lower conduit spell-id lookup on the shared command surface using logical spell identity fields.

Contract:

Resolves the conduit through command ACL and descriptor truth before touching runtime conduit state.

Defers lookup semantics to the lower conduit runtime instead of re-implementing spell identity matching in the command layer.

Uses one top-level command action boundary for gate admission and memory emission.

Parameters:

conduit_id -- Conduit id whose spell inventory should be queried.
spellframe -- Logical spellframe key.
spell_name -- Logical spell name.
binding_name -- Logical binding name.
frame_name -- Optional frame name. When omitted, the room default frame is used.

Returns:

Current spell id resolved by the lower conduit runtime.

Return type:

object

find_spell_key(conduit_id: str, spellframe: str, spell_name: str, binding_name: str, *, frame_name: str | None = None) → object[source]

Return the spellbook key resolved from logical spell identifiers.

Purpose:: Mirror the lower conduit spellbook-key lookup on the shared command surface using logical spell identity fields.

Contract:

Resolves the conduit through command ACL and descriptor truth before touching runtime conduit state.

Defers lookup semantics to the lower conduit runtime instead of re-implementing spell identity matching in the command layer.

Uses one top-level command action boundary for gate admission and memory emission.

Parameters:

conduit_id -- Conduit id whose spell inventory should be queried.
spellframe -- Logical spellframe key.
spell_name -- Logical spell name.
binding_name -- Logical binding name.
frame_name -- Optional frame name. When omitted, the room default frame is used.

Returns:

Spellbook key resolved by the lower conduit runtime.

Return type:

object

get_spell_permissions(conduit_id: str, spell_id: str, *, frame_name: str | None = None) → object[source]

Return the permissions string for one spell inside one conduit.

Purpose:: Expose one lower-runtime spell-permissions lookup through the shared command surface.

Contract:

Resolves the conduit through command ACL and descriptor truth before touching runtime conduit state.

Returns the exact permissions value exposed by the lower conduit runtime.

Uses one top-level command action boundary for gate admission and memory emission.

Parameters:

conduit_id -- Conduit id whose spell permissions should be queried.
spell_id -- Current spell id to inspect.
frame_name -- Optional frame name. When omitted, the room default frame is used.

Returns:

Lower-runtime permissions value for the spell.

Return type:

object

snapshot_state(conduit_id: str, *, frame_name: str | None = None) → Dict[str, Any][source]

Return a detached snapshot of one conduit state payload.

Purpose:: Expose one lower-runtime conduit state snapshot through the shared command surface.

Contract:

Resolves the conduit through command ACL and descriptor truth before touching runtime conduit state.

Returns the lower conduit runtime's detached snapshot payload.

Uses one top-level command action boundary for gate admission and memory emission.

Parameters:

conduit_id -- Conduit id whose state snapshot should be returned.
frame_name -- Optional frame name. When omitted, the room default frame is used.

Returns:

Detached conduit state snapshot payload.

Return type:

Dict[str, Any]

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

Return the Spell a published spell source id names.

Purpose:: Hand out the runtime Spell behind one published record, addressed the way the frame viewer addresses it: spellbook_id:spell_id.

Contract:

Answers exactly the spell the source id names, from its owner's Spellbook (find_spell_by_spell_id), never another version of its SpellIndex; the version an index has active is get_spell_by_index_id's answer. Nexus publishes the version an index has active, so a published record names that version. Until 0.2.8253 this method resolved the record's index and returned the spell the index had active.

Enforces raw-runtime access, the frame command gate, the record's spell-index ACL and the owner conduit's ACL before touching runtime state (_get_spell_by_record_locked).

Uses one top-level command action boundary for gate admission and memory emission.

Parameters:

spell_source_id -- Published spell source id in spellbook_id:spell_id form.
frame_name -- Optional frame name. When omitted, the room default frame is used.

Returns:

The live Spell the source id names.

Return type:

object

Raises:

ValueError -- If the spell source id is empty, malformed, not published or ambiguous in the selected frame, if command ACL denies frame, spell or conduit access, if the record has no owner conduit, or if the owner's Spellbook no longer holds the spell_id.

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

Return one live spell object by stable spell index id.

Parameters:

spell_index_id -- Stable SpellIndex spell-index id to resolve.
frame_name -- Optional frame name. When omitted, the room default frame is used.

Returns:

Live spell object.

Return type:

object

Raises:

ValueError -- If the spell index is not published in the selected frame or command ACL denies spell access.

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

Return the Spell that owns a spell_id.

Purpose:: Hand out the runtime Spell behind one spell_id - the SHA256 bind and bind_inactive return - through the shared command surface.

Contract:

Answers exactly the spell that owns the spell_id, never another version of its SpellIndex; the version an index has active is get_spell_by_index_id's answer. The spell_id must be published in the room's projection of the frame, and Nexus publishes the version an index has active, so a parked version's spell_id is refused (ValueError), not answered with the active one. Renamed from get_spell_by_id in 0.2.8253, whose owner-Book lookup answered a parked spell_id with the spell its index had active.

Enforces raw-runtime access, the frame command gate and the spell-index ACL of the published record before touching runtime state, then reads the owner Spellbook's id maps (Spellbook.find_spell_by_spell_id) without walking its live index map.

Uses one top-level command action boundary for gate admission and memory emission.

Parameters:

spell_id -- The spell_id to resolve.
frame_name -- Optional frame name. When omitted, the room default frame is used.

Returns:

The live Spell that owns the spell_id.

Return type:

object

Raises:

ValueError -- If the spell_id is empty, not published or published under more than one index in the selected frame, if command ACL denies frame or spell access, if no conduit of the frame claims the spell_id, if the owner conduit has no Spellbook, or if that Spellbook no longer holds the spell_id.

get_target_attribute(attribute_name: str) → object[source]

Return one attribute value from the current workstation target.

Parameters:

attribute_name -- Attribute name to retrieve from the active target.

Returns:

Retrieved attribute value.

Return type:

object

Raises:

ValueError -- If attribute_name is empty.
AttributeError -- If the target does not expose the requested attribute.

get_target_method(method_name: str) → Callable[[...], object][source]

Return one method/callable from the current workstation target.

Parameters:

method_name -- Method name to retrieve from the active target.

Returns:

Bound callable from the target.

Return type:

Callable[..., object]

Raises:

ValueError -- If method_name is empty.
AttributeError -- If the target does not expose the requested method.
RuntimeError -- If the resolved attribute is not callable.

execute_target_method(method_name: str, *args: Any, bind_as_name: str | None = None, bind_as_store: str = 'objects', bind_result_weak_ref: bool | None = None, **kwargs: Any) → object[source]

Execute one method on the current workstation target.

Parameters:

method_name -- Method name to execute on the active target.
*args -- Positional arguments passed to the method.
bind_as_name -- Optional workstation binding name for the return value.
bind_as_store -- Store to use when binding the return value.
bind_result_weak_ref -- Optional workstation reference-mode override for the bound result. True forces weak storage, False forces strong storage, and None uses the room/workstation default.
**kwargs -- Keyword arguments passed to the method.

Returns:

Method return value.

Return type:

object

link_frame(frame_name: str) → None[source]

Engage one target frame on this Rift through the shared command surface.

Parameters:: frame_name -- Target frame name to link.
Returns:: None.

get_nexus_frame(frame_name: str | None = None) → object[source]

Return one rooted Nexus-managed conduit through the shared command surface.

Parameters:: frame_name -- Optional explicit Nexus frame name.
Returns:: Root conduit for the resolved Nexus-managed frame.
Return type:: object

list_supported_command_methods() → Tuple[str, ...][source]

Return the public command methods supported by this room surface.

Purpose:: Give callers a cheap, explicit way to discover the current command-surface vocabulary instead of guessing from room type or trial-and-error errors.

Returns:

Supported public command method names in stable: presentation order.

Return type:

Tuple[str, ...]

Topic reference · Full contents