On this page

• CommandSystem
  • CommandSystem
    • CommandSystem.cleanup()
    • CommandSystem.command_system_id
    • CommandSystem.owner_space_id
    • CommandSystem.describe_spells_in_conduit()
    • CommandSystem.get_resolution_state()
    • CommandSystem.get_active_spellspace()
    • CommandSystem.find_spell_id()
    • CommandSystem.find_spell_key()
    • CommandSystem.get_spell_permissions()
    • CommandSystem.snapshot_state()
    • CommandSystem.get_spell_by_source_id()
    • CommandSystem.get_spell_by_index_id()
    • CommandSystem.get_spell_by_id()
    • CommandSystem.get_target_attribute()
    • CommandSystem.get_target_method()
    • CommandSystem.execute_target_method()
    • CommandSystem.link_frame()
    • CommandSystem.get_nexus_frame()
    • CommandSystem.list_supported_command_methods()

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)

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

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

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

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

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

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

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

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]

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

Return one live spell object using a published spell source id.

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:

Live spell object.

Return type:

object

Raises:

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

get_spell_by_index_id(spell_index_id: str, *, frame_name: str | None = None) → object

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_id(spell_id: str, *, frame_name: str | None = None) → object

Return one live spell object by current spell id.

Parameters:

• spell_id -- Current spell 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 is not published in the selected frame or command ACL denies spell access.

get_target_attribute(attribute_name: str) → object

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]

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

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

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

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

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