On this page

• RiftSpace
  • RiftSpace
    • RiftSpace.cleanup()
    • RiftSpace.register_category_pre_hook()
    • RiftSpace.register_category_post_hook()
    • RiftSpace.space_id
    • RiftSpace.space_name
    • RiftSpace.owner_rift_id
    • RiftSpace.space_kind
    • RiftSpace.metadata
    • RiftSpace.frame_viewer
    • RiftSpace.rift_gate
    • RiftSpace.workstation
    • RiftSpace.command_system
    • RiftSpace.event_system
    • RiftSpace.memory_system
    • RiftSpace.register_action_pre_hook()
    • RiftSpace.register_action_post_hook()
    • RiftSpace.unregister_action_hook()

RiftSpace

Use md.RiftSpace from the public package namespace.

Implementation source

class RiftSpace(owner_rift_id: str, *, rift: Rift, space_name: str | None = None, space_kind: str = 'base', metadata: Dict[str, object] | None = None, rift_gate: RiftGate | None = None, space_id: str | None = None)

Internal

Base room/workspace class for Rift.

Purpose:

Provide the base room/workspace contract for Rift.

Contract:

• Owns stable room identity and room-local metadata.

• Keeps a room name for paired lookup through the owning Rift.

• Carries a room-kind marker (base, static, capability, codegen).

• Owns a room-local workstation canvas for saved bindings and active target state.

• Owns a room-local command system for controlled getter/execute operations above the viewer/workstation split.

• Builds the command system through a room-owned factory seam so room subclasses can compose a mode-specific command surface without changing the public space.command_system access pattern.

• Owns a durable attached FrameViewer asset.

• Acts as the asset host, not the projection manager.

• Owns a room-local RiftMemorySystem for sequencing and shared memory context.

• Owns one room-local RiftEventSystem for outbound runtime-event publication.

• Does not yet implement full action history, memory points, checkpoints, or disposition semantics.

Room Mode Matrix:

Shared base behavior:

• Every room owns a workstation, command system, viewer asset, room-local memory system, and one room-local event system.

• Lower Melder frame/runtime truth still governs what actually works on automatic versus dynamic frames.

static:

• Uses the static viewer/command specializations.

• Spell-facing room surface is live-only and more restrictive.

• Workstation defaults weak when binds omit weak_ref.

capability:

• Uses the broad manual runtime command surface.

• Workstation defaults strong when binds omit weak_ref.

• No codegen distinction is added here.

codegen:

• Currently uses the same broad manual runtime command surface as capability.

• Intended to be the later codegen-oriented room.

Lifecycle:

Owned by a Rift. Cleanup clears room-local fields and the owned viewer, workstation, memory system, and event system.

Threading:

Room-local state is confined to the room; the viewer reads current projection truth from the owning Rift on demand rather than holding a second registry that could drift.

Lifecycle / Cleanup:

Created during Rift creation from space_type and cleaned with its Rift. It owns its workstation, command system, viewer asset, memory system, and event system, and tears them down as its children.

Registration:

MELDER KERNEL. StaticRiftSpace, CapabilityRiftSpace, and CodegenRiftSpace are all melder-internal and constructed only inside Rift (rift.py:917-933) from space_type; there is no injection seam - no room class kwarg, no factory hook.

Subsystem Context:

The room a user works in, hosted by Rift. It is an ASSET HOST rather than a projection manager: it creates the viewer during room init and the viewer then reads current Rift projection state on demand. The command-system factory seam is what lets each room compose a mode-specific command surface while space.command_system stays one stable access pattern.

System Context:

The three room modes are a CAPABILITY LADDER, not three unrelated features, and each rung trades reach for safety. static is live-only and read-shaped: no topology mutation, no create-path activation, weak-by-default workstation binds - so a static room cannot change the world it observes. capability is broad manual access with strong-by-default binds and real topology mutation, but no codegen. codegen deliberately does NOT have capability parity; it keeps a slimmer runtime-helper subset and instead owns an internal CodegenSystem, because a room that can generate and execute code needs a narrower manual surface, not a wider one. The weak-versus-strong workstation default follows the same logic: a static room observing the world should not extend the lifetime of what it looks at, while a capability room actively working on objects should.

AGENT_ACCESS: public

AGENT_PURPOSE:

access: public. The base room/workspace a Rift hosts - it owns the viewer, workstation, command system, and the room-local event and memory systems. You work in a concrete room mode (static/capability/codegen) through space.command_system and space.workstation; you do not construct or bind one.

cleanup() → None

Internal

Idempotently cleanup room-local state and the owned event system.

Contract:

• Cleans the owned durable viewer asset.

• Cleans the owned command system, workstation, memory system, and event system before dropping references.

• Clears room identity metadata and room-local metadata maps after owned child cleanup completes.

• Leaves the room unusable after cleanup.

Returns:

None.

register_category_pre_hook(category: str, callback: Callable[[], None]) → str

Register one category-wide pre hook.

Parameters:

• category -- Action category (command, viewer, or codegen).

• callback -- Zero-argument callback to run before any top-level action in the category.

Contract:

• Fires BEFORE every action in the category, so it is the place to observe or veto work rather than to inspect results.

• Returns a SUBSCRIPTION ID; keep it, because unregistering is by id and there is no unregister-by-callback path.

• Category-wide: it covers actions added to the category later, not just those present at registration time.

Threading:

Unsynchronized read; a snapshot only.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the object has been cleaned.

Returns:

Stable subscription id for later unregistration.

Return type:

str

register_category_post_hook(category: str, callback: Callable[[], None]) → str

Register one category-wide post hook.

Parameters:

• category -- Action category (command, viewer, or codegen).

• callback -- Zero-argument callback to run after any top-level action in the category.

Contract:

• Fires AFTER every action in the category, so it sees outcomes rather than intentions.

• Returns a SUBSCRIPTION ID; keep it for unregistration.

• Category-wide, including actions added later.

Threading:

Unsynchronized read; a snapshot only.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the object has been cleaned.

Returns:

Stable subscription id for later unregistration.

Return type:

str

property space_id: str

Purpose:

Return the canonical room id.

Returns:

The room id.

Return type:

str

property space_name: str | None

Purpose:

Return the optional stable room name.

Returns:

Room name, if one exists.

Return type:

Optional[str]

property owner_rift_id: str

Purpose:

Return the canonical owning Rift id.

Returns:

Owning Rift id.

Return type:

str

property space_kind: str

Purpose:

Return the room-kind discriminator.

Returns:

Room kind label.

Return type:

str

property metadata: Dict[str, object]

Purpose:

Return the room-local metadata map.

Contract:

Returns the live mutable metadata dict owned by this room, not a detached copy.

Returns:

Extensible room metadata.

Return type:

Dict[str, object]

property frame_viewer: FrameViewer

Purpose:

Return the attached frame-surface viewer for this space.

Contract:

• Active rooms always own one viewer asset.

• The viewer may host zero frames before any projection exists.

Returns:

Attached frame viewer for this active space.

Return type:

FrameViewer

property rift_gate: RiftGate | None

Purpose:

Return the optional Rift-owned gate bound to this room.

Returns:

Bound Rift gate when present.

Return type:

Optional[RiftGate]

property workstation: Workstation

Purpose:

Return the room-local workstation canvas.

Contract:

• Returns the live workstation object owned by this room.

• The returned workstation is cleaned with the room and is not a detached copy.

Returns:

Room-local workstation canvas.

Return type:

Workstation

property command_system: CommandSystem

Purpose:

Return the room-local command system.

Contract:

• Returns the live command system object owned by this room.

• The returned command system is cleaned with the room and is not a detached copy.

Returns:

Room-local command system.

Return type:

CommandSystem

property event_system: RiftEventSystem

Purpose:

Return the room-local event system.

Contract:

• Returns the live RiftEventSystem owned by this room.

• The returned object is cleaned with the room.

Returns:

Room-local event system.

Return type:

RiftEventSystem

property memory_system: RiftMemorySystem

Purpose:

Return the room-local memory sequencing system.

Contract:

• Returns the live RiftMemorySystem owned by this room.

• The returned object is cleaned with the room.

Returns:

Room-local memory system.

Return type:

RiftMemorySystem

register_action_pre_hook(category: str, action_name: str, callback: Callable[[], None]) → str

Register one pre-action hook for one room action category and name.

Parameters:

• category -- Action category (command, viewer, or codegen).

• action_name -- Stable public action name.

• callback -- Zero-argument callback to run before the action body.

Contract:

• Fires BEFORE one NAMED action only, narrower than the category hook.

• Returns a SUBSCRIPTION ID; keep it for unregistration.

• NOTE: unlike its post counterpart and the category hooks, this method does NOT perform its own cleaned-state check before delegating.

Threading:

Registration is serialized by the underlying hook registry.

Lifecycle / Cleanup:

Not directly guarded; the delegate performs registration.

Returns:

Stable subscription id for later unregistration.

Return type:

str

register_action_post_hook(category: str, action_name: str, callback: Callable[[], None]) → str

Register one post-action hook for one room action category and name.

Parameters:

• category -- Action category (command, viewer, or codegen).

• action_name -- Stable public action name.

• callback -- Zero-argument callback to run after the action exits.

Contract:

• Fires AFTER one NAMED action only, narrower than the category hook.

• Returns a SUBSCRIPTION ID; keep it for unregistration.

Threading:

Unsynchronized read; a snapshot only.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the object has been cleaned.

Returns:

Stable subscription id for later unregistration.

Return type:

str

unregister_action_hook(subscription_id: str) → None

Remove one action-hook subscription by id.

Parameters:

subscription_id -- Stable subscription id returned by hook registration.

Contract:

• BY SUBSCRIPTION ID ONLY - there is no unregister-by-callback path, so a lost id means a permanently registered hook.

• Empty subscription_id is rejected up front with ValueError.

• Removing an id that is not registered is a SILENT NO-OP rather than an error, so success does not prove the hook existed.

Threading:

Reads under self._lock, so the result is a coherent snapshot.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the object has been cleaned.

Returns:

None.

Topic reference · Full contents