On this page

• Rift
  • Rift
    • Rift.cleanup()
    • Rift.id
    • Rift.rift_name
    • Rift.configuration
    • Rift.rift_gate
    • Rift.list_assigned_frame_names()
    • Rift.get_frame_link_contract()
    • Rift.get_selected_contract_names()
    • Rift.create_frame_link()
    • Rift.refresh_runtime_projections()
    • Rift.get_frame_viewer()
    • Rift.space
    • Rift.metadata
    • Rift.is_registered
    • Rift.is_active
    • Rift.mark_registered()
    • Rift.mark_active()
    • Rift.mark_inactive()
    • Rift.get_nexus_frame()
    • Rift.create_nexus_frame()
    • Rift.list_accessible_nexus_frame_names()
    • Rift.list_accessible_non_nexus_frame_names()
    • Rift.on_nexus_frame_disposed()

Rift

Use md.Rift from the public package namespace.

Implementation source

class Rift(nexus: Nexus, *, configuration: RiftConfiguration, rift_gate: RiftGate | None = None, rift_name: str | None = None, rift_id: str | None = None, space_id: str | None = None, metadata: Dict[str, object] | None = None, logger: Any | None = None)

Internal

Live Rift runtime object created and registered by Nexus.

Purpose:

Represent one live Rift that owns its own immediate runtime state, explicit frame-link contracts and one owned room without requiring a separate public state object.

Contract:

• Owns a per-Rift configuration snapshot, explicit frame-link contracts, and one primary room.

• Owns only live Rift runtime state, not global registry or Nexus-wide configuration.

• Programs one primary concrete space from the chosen Rift space_type during creation.

• Does not eagerly realize Nexus frames during creation.

• Defers target-frame selection to later explicit linking.

• Treats Aether as hidden substrate reached later by lower runtime layers such as workstation/workspace logic.

Room Mode Matrix:

• static

  • Programs StaticRiftSpace.

  • Uses the static viewer/command posture.

  • Defaults workstation binds to weak when callers omit weak_ref.

  • Denies topology mutation and direct create-path spell activation.

• capability

  • Programs CapabilityRiftSpace.

  • Broad manual runtime/object access without codegen.

  • Defaults workstation binds to strong.

  • Lower Melder frame/runtime truth still decides what actually works.

• codegen

  • Programs CodegenRiftSpace.

  • Keeps a selected slim runtime-helper subset rather than capability parity.

  • Owns one internal CodegenSystem; CodegenCommandSystem delegates validate_codegen(...) / execute_codegen(...) into that engine and emits full-source codegen room-memory records.

Lifecycle:

Created by Nexus, then registered into the Nexus registry. Cleanup clears the owned room and owned live-state references.

Todo

When Rift-owned Melder frames are introduced for local conduit hosting, bind them in the most permissive AR posture by default: rift_enabled=True, ai_native_enabled=True, and system_state=dynamic.

Threading:

Refresh orchestration is the concurrency-sensitive path: on an ACL change the Rift is asked for fresh projections and applies them to its hosted assets. The config-backed refresh barrier (projection_refresh_gate_enabled and its timeout/poll settings) blocks new entrants at the Rift gate, drains in-flight tickets, refreshes once, then reopens.

Lifecycle / Cleanup:

Cleanup cleans the one owned space, the owned config snapshot, the owned RiftGate, and every engaged FrameLinkContract, then clears Rift-local metadata and cleans the logger LAST.

Registration:

MELDER KERNEL - guarded. Rifts are created and registered by Nexus (Nexus.create_rift), never constructed directly.

Subsystem Context:

The live AR runtime object: Nexus is the process-wide root, Rift is one live connection into Melder's object world, and RiftSpace is the room a user actually works in. A Rift owns exactly ONE primary room, programmed from space_type at creation - there is no room registry and no active-space switching.

System Context:

Rift creation and frame attachment are deliberately SEPARATE STEPS, and that staging is the important design fact. create_rift builds a bare live Rift with a programmed room and no target frame; create_frame_link(frame_name) is the later explicit attachment that validates target-frame policy, REQUIRES descriptor truth to already exist, delegates Nexus-managed authorization back through Nexus, ensures the frame-name ACL contract, and refreshes the viewer. Splitting them means a Rift can exist and be configured before any frame is chosen, and that attachment failures never leave a half-built Rift. Rift does NOT own Melder's object world - it is where an agent gains mediated access to it. Lower Melder frame and runtime truth always wins: a room may advertise a capability the underlying frame refuses, and the frame's answer is final. Known limitation, stated honestly: on_nexus_frame_disposed(...) is still only a logging seam. Rooms have a real room-local event system, but there is no Rift-level event orchestration layer yet.

AGENT_ACCESS: public

AGENT_PURPOSE:

access: public. One live AR connection. Created bare by Nexus with a single primary room from space_type; attach targets afterwards with create_frame_link(frame_name), which REQUIRES descriptor truth to exist. Reach the room via .space.

cleanup() → None

Internal

Idempotently cleanup the live Rift object.

Contract:

• Cleans every owned room before clearing the room registries.

• Cleans the owned per-Rift configuration snapshot before dropping the reference.

• Clears room registries and live state references only after owned teardown completes.

• Does not attempt to clean Nexus or Aether-owned global state.

• Leaves the Rift unusable after cleanup.

Returns:

None.

property id: str

Purpose:

Return the canonical Rift id.

Returns:

Stable Rift id.

Return type:

str

property rift_name: str | None

Purpose:

Return the optional stable Rift name.

Returns:

Rift name when one is assigned.

Return type:

Optional[str]

property configuration: RiftConfiguration

Purpose:

Return the finalized per-Rift configuration snapshot.

Returns:

Owned configuration snapshot.

Return type:

RiftConfiguration

property rift_gate: RiftGate

Purpose:

Return the Rift-owned gate for this runtime instance.

Returns:

Rift-scoped gate.

Return type:

RiftGate

list_assigned_frame_names() → Tuple[str, ...]

Internal

Return the frame names assigned to this Rift.

Contract:

• Returns a TUPLE SNAPSHOT of the frames this rift is contracted to. This is the rift's REACHABILITY BOUNDARY: every viewer query is scoped to these frames, and a frame absent here is invisible to the rift entirely.

• Order follows the contract map's insertion order, not sorted order.

Threading:

Unsynchronized read; a snapshot only.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the object has been cleaned.

Returns:

Assigned frame names.

Return type:

Tuple[str, ...]

get_frame_link_contract(frame_name: str) → FrameLinkContract

Return the per-frame contract for one engaged frame.

Parameters:

frame_name -- Engaged target frame name.

Returns:

Per-frame contract object.

Return type:

FrameLinkContract

Raises:

ValueError -- If frame_name is empty or not engaged on this Rift.

get_selected_contract_names(frame_name: str) → Dict[str, str]

Return the selected ACL contract names for one engaged frame.

Parameters:

frame_name -- Engaged target frame name.

Contract:

• Reports the contracts CURRENTLY SELECTED for one frame, which is narrower than the contracts available - selection is what actually shapes the projection.

• Requires the frame to be assigned to this rift; an unassigned frame raises rather than returning an empty tuple.

Threading:

Unsynchronized read; a snapshot only.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the object has been cleaned.

Returns:

Selected view/command/codegen contract names.

Return type:

Dict[str, str]

create_frame_link(frame_name: str) → None

Internal

Validate and engage one target frame on this Rift's frame contract.

Parameters:

frame_name -- Target frame name to engage.

Contract:

• Validates target-frame policy and runtime posture through Nexus.

• Delegates Nexus-managed frame attachment authorization back through Nexus before the frame link is created.

• Materializes the frame-name-selected ACL contract when the selected contract does not yet exist for the frame.

• Resolves and validates the selected named ACL contract for the frame against descriptor truth.

• Registers the frame on the Rift-local frame contract.

• Refreshes the owned-space viewer when descriptor truth is available for the currently assigned frame set.

Returns:

None.

refresh_runtime_projections(*, frame_names: Sequence[str] | None = None) → Dict[str, FrameProjectionSet]

Build fresh runtime projections and sync the hosted room assets.

Purpose:

Refresh the owned room's projection sets and synchronize the existing durable viewer asset in place.

Parameters:

frame_names -- Optional explicit multi-frame refresh scope.

Returns:

Fresh projection sets keyed by frame name.

Return type:

Dict[str, IFrameProjectionSet]

get_frame_viewer() → FrameViewer

Internal

Return the attached frame viewer for the owned space or raise.

Contract:

• Returns the space's frame viewer BY REFERENCE. It is owned by the space, not created here, so repeated calls yield the SAME viewer - unlike the viewer's own get_view_* accessors, which build fresh helpers per call.

Threading:

Unsynchronized read; a snapshot only.

Lifecycle / Cleanup:

Guarded by check_cleaned().

Raises:

RuntimeError -- If the object has been cleaned.

Returns:

Attached frame viewer for the owned space.

Return type:

FrameViewer

property space: RiftSpace

Purpose:

Return the one owned RiftSpace for this Rift.

Returns:

Owned primary space.

Return type:

RiftSpace

property metadata: Dict[str, object]

Purpose:

Return the live Rift metadata map.

Contract:

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

Returns:

Rift-level metadata.

Return type:

Dict[str, object]

property is_registered: bool

Purpose:

Return whether this Rift is registered in Nexus.

Returns:

True when registered.

Return type:

bool

property is_active: bool

Purpose:

Return whether this Rift is currently active.

Returns:

True when active.

Return type:

bool

mark_registered() → None

Internal

Mark this Rift as registered in Nexus.

Contract:

• Sets the local registration flag under the Rift lock.

• Does not register the Rift in Nexus by itself; callers should use this after the owning Nexus registry mutation succeeds.

Returns:

None.

mark_active() → None

Internal

Mark this Rift as active.

Contract:

• Sets only the local active-state flag under the Rift lock.

• Does not create spaces or register additional runtime objects.

Returns:

None.

mark_inactive() → None

Internal

Mark this Rift as inactive.

Contract:

• Clears only the local active-state flag under the Rift lock.

• Does not remove spaces or detach frame assignments.

Returns:

None.

get_nexus_frame(frame_name: str | None = None) → Conduit

Internal

Return one rooted Nexus-managed conduit through Nexus policy.

Parameters:

frame_name -- Optional explicit Nexus frame name.

Contract:

Delegates rooted conduit resolution to Nexus using this Rift's identity and the current Nexus/Rift frame policy.

Returns:

Root conduit for the resolved Nexus-managed frame.

Return type:

Conduit

create_nexus_frame(frame_name: str | None = None, root_conduit_name: str = 'root', immutable: bool = False) → Conduit

Internal

Create one new rooted Nexus-managed conduit through Nexus policy.

Parameters:

• frame_name -- Optional explicit Nexus frame name.

• root_conduit_name -- Root conduit name to use for newly created frames.

• immutable -- Immutable flag for indexed/shared creation.

Contract:

Delegates strict frame creation to Nexus using this Rift's identity and current frame policy.

Returns:

Root conduit for the newly created frame.

Return type:

Conduit

Raises:

ValueError -- If the target Nexus-managed frame already exists or creation is invalid under the current topology rules.

list_accessible_nexus_frame_names() → Tuple[str, ...]

Internal

Return the Nexus frame names this Rift may currently access.

Contract:

Delegates to Nexus and returns a snapshot tuple of currently accessible frame names for this Rift.

Returns:

Accessible Nexus frame names.

Return type:

Tuple[str, ...]

list_accessible_non_nexus_frame_names() → Tuple[str, ...]

Internal

Return the published non-Nexus frame names this Rift may currently target.

Contract:

Delegates to Nexus and returns a snapshot tuple of currently accessible published non-Nexus frame names for this Rift.

Returns:

Accessible published non-Nexus frame names.

Return type:

Tuple[str, ...]

on_nexus_frame_disposed(frame_name: str) → None

Internal

Placeholder hook for later Rift/workspace frame-disposal event propagation.

Parameters:

frame_name -- Frame name that was disposed externally.

Contract:

Currently logs the disposal observation only; it does not yet mutate local frame-name state or room attachments.

Returns:

None.

Topic reference · Full contents