On this page

CodegenCommandSystem
- CodegenCommandSystem

CodegenCommandSystem

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

class CodegenCommandSystem(*, rift: Rift, space: CodegenRiftSpace, workstation: Workstation, codegen_system: CodegenSystem | None = None)[source]

Internal

Codegen-room command surface.

Purpose:: Own the slim runtime-helper plus codegen execution surface for CodegenRiftSpace.

Contract:

Inherits shared selected-target, ACL, and workstation behavior from CommandSystem.

Owns the explicitly selected conduit/runtime helper subset for codegen work without inheriting the full capability command surface.

Routes validate_codegen(...) and execute_codegen(...) into the attached CodegenSystem.

Emits full-source top-level codegen memory records through the owning room's RiftMemorySystem instead of using the generic command-memory metadata shape.

Registration:: MELDER KERNEL - guarded. Built by CodegenRiftSpace during room init and attached to that room's CodegenSystem.
Subsystem Context:: The codegen posture of the command family and the facade over the room-owned CodegenSystem. It owns the FULL research command family - record, organization, campaign, foresight, crystal-well, synthesis, and composition - where capability rooms carry reads only.
System Context:: This class is a FACADE, not an engine, and the split is deliberate: validate_codegen(...) and execute_codegen(...) are public seams that route into the attached CodegenSystem, which owns transaction context, validation, namespace building, compilation, execution, and monitoring. Keeping the command layer thin means the dangerous machinery has one owner rather than being spread across a command surface. The memory emission is the accountability half. Codegen rooms emit FULL-SOURCE records through the room's RiftMemorySystem rather than the generic command-memory metadata shape, because for generated code the source IS the record - metadata alone would leave what actually ran unrecoverable. research_preview is codegen-only for the same reason: it produces a read-only candidate mock, which is code-shaped output that capability rooms deliberately do not take.

AGENT_ACCESS: internal

AGENT_PURPOSE:: access: internal. Codegen-room command surface. Melder kernel machinery: read it to understand the runtime, do not drive it directly.

cleanup() → None[source]

Idempotently clear codegen-command references.

Returns:: None.

attach_codegen_system(codegen_system: CodegenSystem) → None[source]

Attach the room-owned CodegenSystem after room initialization.

Parameters:: codegen_system -- Root codegen system owned by the same room.
Returns:: None.
Raises:: TypeError -- If codegen_system is None.

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

Return the live conduit cloud for one hosted frame.

Parameters:: frame_name -- Optional frame name. When omitted, the room default frame is used.
Returns:: Live conduit-cloud object for the resolved frame.
Return type:: object

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

Return one live conduit object by id, including lesser-conduit fallback.

Parameters:

conduit_id -- Conduit id to resolve.
frame_name -- Optional frame name. When omitted, the room default frame is used.

Returns:

Live conduit object.

Return type:

object

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

Return one live root/normal conduit object by name.

Parameters:

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

Returns:

Live conduit object.

Return type:

object

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

Return the command-enabled published conduit ids for one frame.

Parameters:: frame_name -- Optional frame name. When omitted, the room default frame is used.
Returns:: Published command-enabled conduit ids.
Return type:: Tuple[str, ...]

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

Return the command-enabled published conduit names for one frame.

Parameters:: frame_name -- Optional frame name. When omitted, the room default frame is used.
Returns:: Published command-enabled conduit names.
Return type:: Tuple[str, ...]

count_conduits(*, frame_name: str | None = None) → int[source]

Return the number of command-enabled published conduits for one frame.

Parameters:: frame_name -- Optional frame name. When omitted, the room default frame is used.
Returns:: Number of published command-enabled conduits.
Return type:: int

find_conduit_id_by_name(conduit_name: str, *, frame_name: str | None = None) → str | None[source]

Return the published command-enabled conduit id for one conduit name.

Parameters:

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

Returns:

Matching conduit id, or None when missing.

Return type:

Optional[str]

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

Return the cluster names visible from one conduit.

Parameters:

conduit_id -- Conduit id whose cluster membership view should be queried.
frame_name -- Optional frame name. When omitted, the room default frame is used.

Returns:

Cluster names visible from the conduit.

Return type:

Tuple[str, ...]

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

Return the current peer links for one conduit.

Parameters:

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

Returns:

Linked conduit objects.

Return type:

Tuple[object, ...]

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

Return the contracted peer conduits for one conduit.

Parameters:

conduit_id -- Source conduit id whose contracted peers should be returned.
frame_name -- Optional frame name. When omitted, the room default frame is used.

Returns:

Lower-runtime contracted conduit collection.

Return type:

object

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

Return one contracted spell lookup result from a conduit.

Parameters:

conduit_id -- Source conduit id whose contract view should be queried.
spell_id -- Current spell id to resolve inside the conduit's contract set.
frame_name -- Optional frame name. When omitted, the room default frame is used.

Returns:

Lower-runtime spell-in-contract lookup result.

Return type:

object

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

Return contracted spell data keyed by peer conduit name.

Parameters:

conduit_id -- Source conduit id whose contract table should be queried.
conduit_name -- Peer conduit name whose contract spell data should be returned.
frame_name -- Optional frame name. When omitted, the room default frame is used.

Returns:

Lower-runtime contract spell payload for the peer name.

Return type:

object

validate_codegen(code: str, *, frame_name: str) → Dict[str, object][source]

Validate generated Python code through the attached codegen system.

Purpose:: Keep the public room-facing validation seam on the command surface while delegating real validation work into the internal CodegenSystem.

Contract:

Delegates validation into the attached CodegenSystem.

Emits one full-source codegen memory record for the completed top-level validation action when room memory is enabled.

Requires non-empty code and frame_name to preserve the future call contract.

Parameters:

code -- Generated Python source to validate later.
frame_name -- Target frame whose codegen ACL/namespace policy will later be applied.

Returns:

Public validation payload.

Return type:

Dict[str, object]

Raises:

ValueError -- If code or frame_name is empty.

execute_codegen(code: str, *, frame_name: str) → Dict[str, object][source]

Execute generated Python code through the attached codegen system.

Purpose:: Keep the public room-facing execution seam on the command surface while delegating real validation, namespace construction, compile/exec, and lifecycle event publication into the internal CodegenSystem.

Contract:

Delegates execution into the attached CodegenSystem.

Emits one full-source codegen memory record for the completed top-level execution action when room memory is enabled.

Requires non-empty code and frame_name to preserve the future call contract.

Parameters:

code -- Generated Python source to execute later.
frame_name -- Target frame whose codegen ACL/namespace policy will later be applied.

Returns:

Public execution payload.

Return type:

Dict[str, object]

Raises:

ValueError -- If code or frame_name is empty.

materialize_codegen(code: str, *, module_name: str, frame_name: str) → Dict[str, object][source]

Promote validated codegen source to a live SyntheticModule.

Purpose:: The codegen room's missing materialization lane (epic M5, "the X"): the residency-ladder Progenitor act. Execution and preview lanes stay ephemeral by design; THIS verb is the one explicit opt-in step that turns generated source into a durable, importable world object. Binding the class inside it afterwards (a Spellbook act) mints custody through the landed bind seam and closes the codegen -> synthmodule -> bind -> crystal loop.

Contract:

Validation-gated: the source runs through the attached engine's full validation policy first; a rejected verdict returns the validator's payload marked materialized: False and NOTHING is registered or published.

Accepted source materializes as one SyntheticModule (register -> parent shells -> publish -> exec -> importlib metadata) with the import hook installed, so plain import <module_name> resolves onto the world object immediately.

Pre-bind sentinel identity: the module carries spell_crystal_id="unbound_codegen" and binding_signature="codegen_materialized" until a bind mints real custody (rebuild-lane sentinel precedent).

R8 no-half-published law: if module exec raises, the module is torn down (cleanup) before the error propagates.

Emits one full-source codegen memory record for the completed top-level action when room memory is enabled.

Parameters:

code -- Generated Python source to materialize.
module_name -- Canonical import name for the new module; every dotted segment must be a legal Python identifier.
frame_name -- Target frame whose codegen ACL/validation policy applies.

Returns:

materialized flag, module identity (module_name, source_sha256, module_file), public export names, and the validation payload.

Return type:

Dict[str, object]

Raises:

ValueError -- If code, module_name, or frame_name is empty, or module_name is not dotted-identifier legal.
RuntimeError -- If the room's codegen engine is not attached or the command system has been cleaned.

research_walk(lane: str = 'default') → object[source]

Return one research lane's line of versions with its ancestry hop.

Parameters:: lane -- Lane name or id; the default lane when omitted.
Returns:: Ordered node payloads (detached).
Return type:: object

research_history(spell_id: str) → object[source]

Return everything the research record knows about one identity.

Parameters:: spell_id -- Binding-signature SHA256 to report on.
Returns:: History payload (holder lane, record, journal events).
Return type:: object

research_heads() → object[source]

Return the tip identity of every open research lane.

Returns:: lane name -> tip spell id mapping (detached).
Return type:: object

research_residency(spell_id: str) → object[source]

Return the query-time residency join for one identity.

Parameters:: spell_id -- Binding-signature SHA256 to locate.
Returns:: Residency payload (declared/runtime/custody verdicts).
Return type:: object

research_diff(left_spell_id: str, right_spell_id: str, *, strategy: str | None = None) → object[source]

Return a derived diff between two research identities.

Parameters:

left_spell_id -- Left version identity.
right_spell_id -- Right version identity.
strategy -- Registered diff strategy. None picks the kind-aware room default: "structural" for spell pairs (the room's reasoning layer; "source" for whole-module text, "parts" for per-class/function grain), and the root's "members" default for composition pairs. An explicit unknown name surfaces the engine's KeyError - the room never silently reroutes a caller's strategy ask (BUG-044 law).

Returns:

Detached diff verdict.

Return type:

object

research_campaign_view(campaign: str) → object[source]

Return everything the record knows about one research campaign.

Parameters:: campaign -- Campaign stamp to gather.
Returns:: Campaign payload (nodes, transitions, lanes involved).
Return type:: object

research_create_lane(name: str, *, lane_type: str | None = None, attach_to: str | None = None, attach_at_spell_id: str | None = None, reason: str | None = None) → object[source]

Create one research lane, optionally anchored onto an existing node.

Parameters:

name -- Unique lane name.
lane_type -- Optional policy vocabulary word (development/experiment/production/test); experiment when omitted.
attach_to -- Optional lane (name or id) to anchor onto.
attach_at_spell_id -- Node identity within attach_to.
reason -- Optional reason line.

Returns:

The new lane's describe() payload (detached).

Return type:

object

research_attach(lane: str, *, onto: str, at_spell_id: str, reason: str | None = None) → None[source]

Anchor one lane's ancestry onto another lane's node.

Parameters:

lane -- Lane (name or id) being organized.
onto -- Lane (name or id) to anchor onto.
at_spell_id -- Node identity within onto.
reason -- Optional reason line.

Returns:

None.

research_detach(lane: str, *, reason: str | None = None) → None[source]

Remove one lane's ancestry anchor.

Parameters:

lane -- Lane (name or id) being organized.
reason -- Optional reason line.

Returns:

None.

research_join(lane: str, *, into: str, collapse: bool = False, force: bool = False, reason: str | None = None) → object[source]

Finish one lane into a receiving lane (divergence-aware).

Parameters:

lane -- Source lane (name or id) to finish.
into -- Receiving lane (name or id).
collapse -- Move only the tip when True.
force -- Permit a divergent join (explicit supersede).
reason -- Optional reason line.

Returns:

The receiving lane's describe() payload (detached).

Return type:

object

research_archive(lane: str, *, reason: str | None = None) → None[source]

Retire one dead-end research lane from the active view.

Parameters:

lane -- Lane (name or id) to archive.
reason -- Optional reason line.

Returns:

None.

research_set_campaign(campaign: str) → None[source]

Set the ambient research-campaign stamp for this world's records.

Parameters:: campaign -- Non-empty campaign name.
Returns:: None.

research_clear_campaign() → None[source]

Clear the ambient research-campaign stamp.

Returns:: None.

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

Return the code of one spell's module world (or one module of it).

Parameters:

spell_id -- Binding-signature SHA256 whose world to read.
module_name -- Optional single module to return.

Returns:

Per-module source rows (recorded-first, live-disk: fallback, honest text_unavailable).

Return type:

object

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

Return one blast radius joined with research residency.

Parameters:

spell_id -- Optional spell SHA256 at the blast center.
module_name -- Optional canonical module name at the blast center.

Returns:

Radius payload plus the per-spell research join: (declared/lane/campaign rows).

Return type:

object

research_module_graph(spell_id: str) → object[source]

Return one spell's module world as a walkable graph payload.

Parameters:

spell_id -- Binding-signature SHA256 whose world to walk.

Returns:

Modules, dependency edges, local reverse edges,: export surfaces, fingerprints, paths, and load order.

Return type:

object

research_source_drift() → object[source]

Return the full recorded-vs-disk drift report with radii.

Returns:

Drift statuses per sealed module plus blast radii for: every module that is not unchanged.

Return type:

object

research_module(spell_id: str, module_name: str) → object[source]

Return the full crystal dossier for one module of one version.

Parameters:

spell_id -- Binding-signature SHA256 whose world carries it.
module_name -- Module to gather.

Returns:

Source (labeled synthetic/user/live_disk), fingerprint,: path, deps, local importers, export surface, drift.

Return type:

object

research_part(spell_id: str, part_name: str, *, kind: str | None = None, module_name: str | None = None) → object[source]

Return one named top-level function/class's text from a version.

Parameters:

spell_id -- Binding-signature SHA256 whose world to search.
part_name -- Top-level part name.
kind -- Optional "function" or "class" filter.
module_name -- Optional single module to search.

Returns:

Part text + span + carrying module, or an honest miss.

Return type:

object

research_part_diff(left_spell_id: str, right_spell_id: str, part_name: str, *, kind: str | None = None, module_name: str | None = None) → object[source]

Unified text diff of one named part between two versions + radius.

Parameters:

left_spell_id -- Left version identity.
right_spell_id -- Right version identity.
part_name -- Top-level part name to compare.
kind -- Optional "function" or "class" filter.
module_name -- Optional single module to search on both sides.

Returns:

Per-side found flags/modules/kinds, unified diff of the: part text (recorded material only), and the carrying module's residency-joined blast radius.

Return type:

object

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

Return every top-level class/function of a version, with code.

Parameters:

spell_id -- Binding-signature SHA256 whose world to inventory.
module_name -- Optional single module to inventory.

Returns:

Per-module part rows (name/kind/span/text) with: per-module honesty (text_unavailable / parse_error).

Return type:

object

research_preview(code: str, *, against_spell_id: str | None = None, module_name: str | None = None, frame_name: str | None = None) → object[source]

Mock one candidate codegen and report what would happen next.

Purpose:: The codegen room's foresight centerpiece: BEFORE anything executes or binds, report what the candidate defines and imports, the would-be source + structural diff against the version it would replace, the current blast radius of that replacement joined with research residency, and - when a frame_name is supplied - the room's normal codegen validation verdict for the candidate.

Contract:

Read-only: nothing executes, binds, or records.

Validation is optional because it is frame-scoped; without a frame_name the validation section is None and the agent can call validate_codegen separately.

Parameters:

code -- Candidate Python source text.
against_spell_id -- Optional current version it would replace.
module_name -- Optional module identity when no against-version exists.
frame_name -- Optional frame for the namespace-scoped validation pass.

Returns:

The root preview payload plus a validation section.

Return type:

object

research_synthesize(base_spell_id: str, donor_spell_id: str, *, take_functions: object | None = None, take_classes: object | None = None, stage_ancestry: bool = False) → object[source]

Surgically compose one candidate from two recorded versions.

Purpose:: The codegen-workshop composition verb: take named top-level functions/classes from the donor version's root module, splice them into the base version's, and return the composed source with its full foresight preview. With stage_ancestry=True the two parents stage for the next world entry, so executing the composed candidate mints the multi-parent node automatically.

Parameters:

base_spell_id -- Version being upgraded.
donor_spell_id -- Version parts are taken from.
take_functions -- Top-level function names to take.
take_classes -- Top-level class names to take.
stage_ancestry -- Stage [base, donor] as the next entry's parents.

Returns:

Synthesis verdict incl. composed_source, selections,: provenance, and the preview payload.

Return type:

object

research_stage_ancestry(parent_spell_ids: object) → None[source]

Stage parent ancestry for the NEXT world entry (one-shot).

Parameters:: parent_spell_ids -- Non-empty list of declared parent identities.
Returns:: None.

research_clear_staged_ancestry() → None[source]

Clear the staged parent ancestry without consuming it.

Returns:: None.

research_group_register(member_spell_ids: object, *, lane: str | None = None, reason: str | None = None) → object[source]

Declare one subsystem composition over declared versions.

Parameters:

member_spell_ids -- Non-empty member identities to pin.
lane -- Optional lane (name or id); default lane when omitted.
reason -- Optional reason line.

Returns:

The new composition node's describe() payload.

Return type:

object

research_group_recompose(previous_group_id: str, *, add: object | None = None, remove: object | None = None, reason: str | None = None) → object[source]

Evolve one composition forward (iterate-and-add).

Parameters:

previous_group_id -- The composition being evolved.
add -- Member identities to add.
remove -- Member identities to drop.
reason -- Optional reason line.

Returns:

The new composition node's describe() payload.

Return type:

object

research_group_view(group_id: str) → object[source]

Return one composition's roster with residence and drift truth.

Parameters:: group_id -- Composition identity to gather.
Returns:: Roster + per-member lane joins + behind drift flags.
Return type:: object

research_group_diff(left_group_id: str, right_group_id: str, *, strategy: str = 'members') → object[source]

Return a derived diff between two recorded compositions.

Parameters:

left_group_id -- Left composition identity.
right_group_id -- Right composition identity.
strategy -- Registered grouped strategy ("members" default: added/removed members + lane-evidenced version moves).

Returns:

Detached grouped-diff verdict.

Return type:

object

research_group_impact(group_id: str) → object[source]

Return one composition's union blast radius with closure math.

Parameters:

group_id -- Composition identity at the blast center.

Returns:

Union radius, internal/outbound split, closure: fraction, affected compositions, residency join.

Return type:

object

research_group_footprint(group_id: str) → object[source]

Return one composition's physical shadow (module footprint).

Parameters:

group_id -- Composition identity to shadow.

Returns:

Union of member module worlds, per-module member map,: shared modules, honest unknown-custody members.

Return type:

object

research_group_drift(group_id: str) → object[source]

Return recorded-vs-disk drift filtered to one composition.

Parameters:: group_id -- Composition identity to check.
Returns:: Footprint-narrowed drift statuses, radii, and counts.
Return type:: object

research_group_history(group_id: str, *, campaign: str | None = None) → object[source]

Return the journal story of one subsystem area.

Parameters:

group_id -- Composition identity to gather around.
campaign -- Optional campaign stamp - narrow the area's story to one effort (the WHERE x WHEN join).

Returns:

Subsystem-lane, member, and member-lane events in: journal order, campaign stamps intact.

Return type:

object

research_recent(*, limit: int = 50) → object[source]

Return the newest journal events across the whole record.

Purpose:: The cold-landing read: "what happened here lately" in one call, before choosing where to work.

Parameters:

limit -- Bound on the number of newest entries.

Returns:

Newest journal entries in journal order, with the: total entry count and next sequence.

Return type:

object

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

Return the public command methods supported by codegen rooms.

Purpose:: Preserve the explicitly approved shared frame-navigation surface, append the selected codegen runtime helpers, and then append the codegen execution seams.

Returns:

Shared frame-navigation names plus selected: codegen helper and execution method names.

Return type:

Tuple[str, ...]

Topic reference · Full contents