tg_model.execution

Execution subsystem: frozen topology, dependency graph, validation, and evaluation.

Typical pipeline: compile element types (SomeSystem.compile()), build a ConfiguredModel with instantiate(), then call evaluate() (lazy compile + optional validation per call) or explicitly compile_graph(), optionally validate_graph(), then run Evaluator with a fresh RunContext. Per-run values live in RunContext; the configured model may cache a compiled graph on the instance.

Notes

Behavioral APIs (dispatch_event(), etc.) mutate RunContext discrete state and optional BehaviorTrace records; they do not change ConfiguredModel topology.

class tg_model.execution.AllocationBinding(*, stable_id, requirement, target, parameter_overrides=None)[source]

Bases: object

Resolved allocate edge from a requirement package to a target element.

Parameters:

  • parameter_overrides (dict[str, ValueSlot], optional) – Maps requirement package parameter() names to concrete source value slots. When present, the graph compiler wires the corresponding requirement package parameter slots as computed values (sourced from the mapped slots) rather than as free INPUT_PARAMETER nodes.

  • stable_id (str)

  • requirement (ElementInstance)

  • target (ElementInstance)

stable_id
requirement
target
parameter_overrides
class tg_model.execution.BehaviorStep(step_index, part_path, event_name, from_state, to_state, effect_name)[source]

Bases: object

One state-machine transition recorded in BehaviorTrace.

Parameters:

  • step_index (int)

  • part_path (str)

  • event_name (str)

  • from_state (str)

  • to_state (str)

  • effect_name (str | None)

step_index: int
part_path: str
event_name: str
from_state: str
to_state: str
effect_name: str | None
class tg_model.execution.BehaviorTrace(steps=<factory>, item_flows=<factory>, decision_steps=<factory>, fork_join_steps=<factory>, merge_steps=<factory>, sequence_steps=<factory>)[source]

Bases: object

Mutable collector for behavioral steps (multiple parallel lists).

Notes

Paths are PartInstance.path_string values and declared names, not slot stable ids. Global ordering uses step_index across lists (see behavior_trace_to_records()).

Parameters:
steps: list[BehaviorStep]
item_flows: list[ItemFlowStep]
decision_steps: list[DecisionTraceStep]
fork_join_steps: list[ForkJoinTraceStep]
merge_steps: list[MergeTraceStep]
sequence_steps: list[SequenceTraceStep]
class tg_model.execution.ConfiguredModel(root, *, path_registry, id_registry, connections, allocations, references, requirement_value_slots=None)[source]

Bases: object

Immutable configured topology for one root type instance.

Notes

Evaluations use fresh RunContext objects per evaluate() call; the part tree and registries do not change. A successful compile may be cached on this instance (_compiled_graph) for reuse.

Thread safety: Do not call evaluate() or compile_graph() concurrently on the same instance from multiple threads; the cache is not locked.

Copy / pickle: Caching a compiled graph on the instance means copying or unpickling a configured model without clearing _compiled_graph is unsupported; treat cached graphs as invalid across process or deep-copy boundaries unless you add an explicit clear or rebuild.

Attribute access delegates to the root part for ergonomics.

Parameters:
handle(path)[source]

Look up an instance or value slot by dotted path string.

Parameters:

path (str) – Instance path such as Rocket.tank.mass_kg.

Returns:

Registered topology object.

Return type:

ElementInstance or ValueSlot

Raises:

KeyError – If path is not in path_registry.

evaluate(inputs=None, *, run_context=None, validate=True)[source]

Run one synchronous evaluation over the compiled dependency graph.

Compiles the graph on first use (same cache as compile_graph()), optionally runs validate_graph(), then delegates to Evaluator.

Parameters:

  • inputs (dict, optional) – Per-run values keyed by ValueSlot handles belonging to this model, or by str giving the stable_id of such a slot only (not arbitrary element or part ids). Values are typically unitflow.Quantity instances.

  • run_context (RunContext, optional) – Fresh context per call by default. Supply only for advanced testing or tooling.

  • validate (bool, default True) – When True, runs validate_graph() before each evaluation (static checks). For tight loops, sweeps, or optimizers, pass validate=False after you have validated once out-of-band, to avoid repeating that work every run. On validation failure, raises GraphValidationError.

Returns:

Same aggregate type as tg_model.execution.evaluator.Evaluator.evaluate(). Missing inputs, failed constraints, and other runtime issues appear in failures / constraint_results — not as exceptions from this method.

Return type:

RunResult

Raises:

  • GraphCompilationError – If graph compilation fails (from compile_graph()).

  • GraphValidationError – If validate is True and static validation fails (subclass of Exception).

  • KeyError – If a string key is not present in this model’s id registry.

  • TypeError – Propagated from the evaluator when an async external is used in sync mode.

  • ValueError – If an input key is a ValueSlot not registered on this model, or a string id that does not refer to a ValueSlot.

See also

tg_model.execution.graph_compiler.compile_graph, tg_model.execution.evaluator.Evaluator

class tg_model.execution.ConnectionBinding(*, stable_id, source, target, carrying=None)[source]

Bases: object

Resolved connection between two PortInstance objects.

Parameters:

  • stable_id (str) – Unique edge id (derived at instantiate time).

  • source (PortInstance) – Endpoint ports.

  • target (PortInstance) – Endpoint ports.

  • carrying (str, optional) – Item kind discriminator for emit_item().

stable_id
source
target
carrying
class tg_model.execution.ConstraintResult(name, passed, evidence='', *, requirement_path=None, allocation_target_path=None)[source]

Bases: object

Outcome of one constraint or requirement-acceptance check.

Parameters:

  • name (str)

  • passed (bool)

  • evidence (str)

  • requirement_path (str | None)

  • allocation_target_path (str | None)

name
passed
evidence
requirement_path
allocation_target_path
class tg_model.execution.DecisionDispatchOutcome(*values)[source]

Bases: StrEnum

Outcome of dispatch_decision() (action ran vs not).

ACTION_RAN = 'action_ran'

A branch or default_action ran (name in DecisionDispatchResult.chosen_action).

NO_ACTION = 'no_action'

No branch matched and there was no default_action.

class tg_model.execution.DecisionDispatchResult(outcome, chosen_action=None, merge_ran=False)[source]

Bases: object

Structured result of dispatch_decision().

Notes

bool(result) is true when chosen_action is not None.

Parameters:
outcome: DecisionDispatchOutcome
chosen_action: str | None = None
merge_ran: bool = False

True when a paired merge was executed (after a chosen action).

class tg_model.execution.DecisionTraceStep(step_index, part_path, decision_name, chosen_action)[source]

Bases: object

Record of one dispatch_decision() invocation.

Parameters:

  • step_index (int)

  • part_path (str)

  • decision_name (str)

  • chosen_action (str | None)

step_index: int
part_path: str
decision_name: str
chosen_action: str | None
class tg_model.execution.DependencyGraph[source]

Bases: object

Directed graph of value and compute nodes for one compile of a configured model.

Notes

add_edge(from_id, to_id) means from_id must be satisfied before to_id.

add_node(node)[source]
Parameters:

node (DependencyNode)

Return type:

None

add_edge(from_id, to_id)[source]

Add dependency edge (from_id before to_id).

Parameters:

  • from_id (str)

  • to_id (str)

Return type:

None

get_node(node_id)[source]

Return node by id.

Raises:

KeyError – If unknown.

Parameters:

node_id (str)

Return type:

DependencyNode

property nodes: dict[str, DependencyNode]
property edges: list[tuple[str, str]]
dependencies_of(node_id)[source]
Parameters:

node_id (str)

Return type:

list[str]

dependents_of(node_id)[source]
Parameters:

node_id (str)

Return type:

list[str]

topological_order()[source]

Deterministic topological sort (stable tie-break by sorted ready queue).

Returns:

Node ids in evaluation order.

Return type:

list[str]

Raises:

ValueError – If a cycle remains (not all nodes scheduled).

dependency_closure(seeds)[source]

Walk upstream dependencies from seeds.

Raises:

KeyError – If a seed is not a known node id.

Parameters:

seeds (Iterable[str])

Return type:

set[str]

dependent_closure(seeds)[source]

Walk downstream dependents from seeds.

Raises:

KeyError – If a seed is not a known node id.

Parameters:

seeds (Iterable[str])

Return type:

set[str]

induced_subgraph(node_ids)[source]

Copy restricted to node_ids (internal edges only).

Raises:

KeyError – If any requested id is unknown.

Parameters:

node_ids (set[str])

Return type:

DependencyGraph

class tg_model.execution.DependencyNode(node_id, kind, slot_id=None, metadata=None)[source]

Bases: object

Single node in a DependencyGraph (value or compute kind).

Parameters:

  • node_id (str)

  • kind (NodeKind)

  • slot_id (str | None)

  • metadata (dict[str, Any] | None)

node_id
kind
slot_id
metadata
property is_value_node: bool
property is_compute_node: bool
class tg_model.execution.DispatchOutcome(*values)[source]

Bases: StrEnum

Outcome of dispatch_event() (transition fired vs skipped).

FIRED = 'fired'
NO_MATCH = 'no_match'

No transition for the current state and event name (or no behavior spec).

GUARD_FAILED = 'guard_failed'

A transition matched but its when guard returned false.

class tg_model.execution.DispatchResult(outcome)[source]

Bases: object

Structured result of dispatch_event().

Notes

bool(result) is true only when a transition fired (legacy truthiness preserved).

Parameters:

outcome (DispatchOutcome)

outcome: DispatchOutcome
class tg_model.execution.ElementInstance(*, stable_id, definition_type, definition_path, instance_path, kind, metadata=None)[source]

Bases: object

One materialized declaration (requirement, port, block, …) under the configured root.

Parameters:

  • stable_id (str)

  • definition_type (type)

  • definition_path (tuple[str, ...])

  • instance_path (tuple[str, ...])

  • kind (str)

  • metadata (dict[str, Any] | None)

stable_id
definition_type
definition_path
instance_path
kind
metadata
property path_string: str

Dotted path from configured root to this instance.

class tg_model.execution.Evaluator(graph, *, compute_handlers=None)[source]

Bases: object

Synchronous evaluation engine over a dependency graph.

Walks the topological order, evaluates ready compute nodes, and materializes results into the RunContext.

evaluate and evaluate_async intentionally duplicate the topological driver: bridging them through one coroutine would force asyncio.run (or worse) from evaluate, which breaks callers that already own an event loop. Shared helpers only cover non-async steps (see _bind_run_inputs / _finalize_run).

Parameters:
evaluate(ctx, inputs=None)[source]

Run one synchronous evaluation (external compute must not be async).

Parameters:

  • ctx (RunContext) – Fresh or reset per-run state.

  • inputs (dict, optional) – Bound by stable slot id (see graph node metadata / compile conventions).

Returns:

Aggregated failures and constraint outcomes.

Return type:

RunResult

Raises:

TypeError – Propagated from assert_sync_external() when an async external is present.

See also

evaluate_async

async evaluate_async(ctx, *, configured_model, inputs=None)[source]

Evaluate with async external backends (await compute when it returns a coroutine).

Parameters:

  • ctx (RunContext) – Per-run state.

  • configured_model (ConfiguredModel) – Topology context for external resolution paths.

  • inputs (dict, optional) – Same binding convention as evaluate().

Returns:

Same shape as evaluate().

Return type:

RunResult

See also

evaluate

class tg_model.execution.ForkJoinTraceStep(step_index, part_path, block_name)[source]

Bases: object

Record of one dispatch_fork_join() invocation.

Parameters:

  • step_index (int)

  • part_path (str)

  • block_name (str)

step_index: int
part_path: str
block_name: str
exception tg_model.execution.GraphCompilationError[source]

Bases: Exception

Raised when graph compilation cannot resolve symbols, slots, or bindings.

exception tg_model.execution.GraphValidationError(message, *, result)[source]

Bases: Exception

Raised when validate_graph() fails before evaluation.

Typical source: tg_model.execution.configured_model.ConfiguredModel.evaluate() when validate=True and static checks do not pass.

Subclasses Exception (not BaseException) so typical except Exception handlers catch it; use this type or inspect result when you need to distinguish validation from other failures.

Parameters:
Return type:

None

result

Structured failures from validate_graph().

Type:

ValidationResult

class tg_model.execution.ItemFlowStep(step_index, source_port_path, target_port_path, item_kind, payload=None)[source]

Bases: object

Inter-part item flow across one ConnectionBinding.

Parameters:

  • step_index (int)

  • source_port_path (str)

  • target_port_path (str)

  • item_kind (str)

  • payload (Any | None)

step_index: int
source_port_path: str
target_port_path: str
item_kind: str
payload: Any | None = None
class tg_model.execution.MergeTraceStep(step_index, part_path, merge_name, then_action)[source]

Bases: object

Record of one dispatch_merge() invocation.

Parameters:

  • step_index (int)

  • part_path (str)

  • merge_name (str)

  • then_action (str | None)

step_index: int
part_path: str
merge_name: str
then_action: str | None
class tg_model.execution.NodeKind(*values)[source]

Bases: Enum

Compute vs value classification for dependency nodes.

INPUT_PARAMETER = 'input_parameter'
ATTRIBUTE_VALUE = 'attribute_value'
CONSTRAINT_RESULT = 'constraint_result'
LOCAL_EXPRESSION = 'local_expression'
ROLLUP_COMPUTATION = 'rollup_computation'
SOLVE_GROUP = 'solve_group'
CONSTRAINT_CHECK = 'constraint_check'
EXTERNAL_COMPUTATION = 'external_computation'
class tg_model.execution.PartInstance(*, stable_id, definition_type, definition_path, instance_path, metadata=None)[source]

Bases: ElementInstance

Materialized Part / System.

Owns child parts, ports, and value slots. After freeze(), structure is immutable.

Raises:

RuntimeError – If mutators run after freeze().

Parameters:

  • stable_id (str)

  • definition_type (type)

  • definition_path (tuple[str, ...])

  • instance_path (tuple[str, ...])

  • metadata (dict[str, Any] | None)

freeze()[source]

Recursively freeze this part subtree (called on the full model after instantiate).

Return type:

None

add_child(name, child)[source]

Register a child part under name (instantiation only).

Raises:

RuntimeError – If this instance is frozen.

Parameters:
Return type:

None

add_port(name, port)[source]

Register a port under name (instantiation only).

Parameters:
Return type:

None

add_value_slot(name, slot)[source]

Register a value slot under name (instantiation only).

Parameters:
Return type:

None

add_requirement_package(name, pkg)[source]

Register a composable requirement package under name (instantiation only).

Parameters:
Return type:

None

property children: list[PartInstance]

Shallow copy of child parts.

property ports: list[PortInstance]

Shallow copy of owned ports.

property value_slots: list[ValueSlot]

Shallow copy of owned parameter/attribute slots.

class tg_model.execution.PortInstance(*, stable_id, definition_type, definition_path, instance_path, metadata=None)[source]

Bases: ElementInstance

Concrete port endpoint; direction comes from declaration metadata.

Parameters:

  • stable_id (str)

  • definition_type (type)

  • definition_path (tuple[str, ...])

  • instance_path (tuple[str, ...])

  • metadata (dict[str, Any] | None)

direction
class tg_model.execution.ReferenceBinding(*, stable_id, source, citation)[source]

Bases: object

Resolved references edge from a declaration to a citation node (provenance).

Parameters:
stable_id
source
citation
class tg_model.execution.RequirementPackageInstance(*, stable_id, definition_type, definition_path, instance_path, package_type, metadata=None)[source]

Bases: ElementInstance

Materialized composable requirement package under the configured root.

Exposes nested requirements, citations, nested packages, and package-level value slots via attribute access (e.g. root.mission.x_m for a package parameter).

Parameters:

  • stable_id (str)

  • definition_type (type)

  • definition_path (tuple[str, ...])

  • instance_path (tuple[str, ...])

  • package_type (type)

  • metadata (dict[str, Any] | None)

package_type
add_member(name, obj)[source]

Register a child (instantiation only).

Parameters:
Return type:

None

freeze()[source]

Freeze this package and nested packages recursively.

Return type:

None

class tg_model.execution.RequirementSatisfactionResult(requirement_path, allocation_target_path, passed, evidence, check_name)[source]

Bases: object

Outcome of one requirement acceptance check (one allocation x one compiled check).

Parameters:

  • requirement_path (str)

  • allocation_target_path (str)

  • passed (bool)

  • evidence (str)

  • check_name (str)

requirement_path: str
allocation_target_path: str
passed: bool
evidence: str
check_name: str
class tg_model.execution.RequirementSatisfactionSummary(results)[source]

Bases: object

Aggregated requirement acceptance outcomes for one run.

Use check_count to detect the case where no acceptance checks ran (no expr= requirements compiled into the graph for this configuration). all_passed is False when check_count == 0 so callers do not treat “nothing to verify” as green compliance.

Parameters:

results (tuple[RequirementSatisfactionResult, ...])

results: tuple[RequirementSatisfactionResult, ...]
property check_count: int
property all_passed: bool

True only when there is at least one acceptance check and every check passed.

class tg_model.execution.RunContext[source]

Bases: object

Per-run mutable state. Created fresh for each evaluation.

Keyed by ValueSlot.stable_id to maintain isolation from topology.

Behavior effects and guards (Phase 6): while push_behavior_effect_scope() is active (during transition guards, decision predicates, and action effects), slot and discrete-state accessors above are restricted to the active part subtree. This is API discipline for well-behaved callables — not a security sandbox: code can still close over ConfiguredModel or use other Python escape hatches. Item payload staging (prime_item_payload(), etc.) is intentionally not subtree-scoped (inter-part delivery).

push_behavior_effect_scope(part)[source]

Restrict value-slot access to the subtree of part until pop_behavior_effect_scope().

Parameters:

part (PartInstance) – Active part for guard/effect callables.

Return type:

None

pop_behavior_effect_scope()[source]

Pop the innermost behavior scope pushed by push_behavior_effect_scope().

Raises:

RuntimeError – If the stack is empty.

Return type:

None

get_or_create_record(slot_id)[source]

Return the mutable SlotRecord for slot_id, creating it if needed.

When a behavior effect scope is active, the same subtree rule as bind_input() applies (see class docstring).

Parameters:

slot_id (str)

Return type:

SlotRecord

bind_input(slot_id, value)[source]

Bind value to slot_id (creates record if needed).

Parameters:

  • slot_id (str)

  • value (Any)

Return type:

None

realize(slot_id, value, provenance='computed')[source]

Write computed value to slot_id.

Parameters:

  • slot_id (str)

  • value (Any)

  • provenance (Any)

Return type:

None

mark_pending(slot_id, note='')[source]

Mark slot_id pending (external deferral hook).

Parameters:

  • slot_id (str)

  • note (str)

Return type:

None

get_value(slot_id)[source]

Return the current value when the slot is in a ready state.

Raises:

  • ValueError – If the slot has no record or is not ready.

  • RuntimeError – If a behavior scope forbids access to this slot.

Parameters:

slot_id (str)

Return type:

Any

get_state(slot_id)[source]

Return SlotState for slot_id (UNBOUND if no record).

Raises:

RuntimeError – If a behavior effect scope forbids access to this slot.

Parameters:

slot_id (str)

Return type:

SlotState

add_constraint_result(result)[source]

Append one constraint or requirement-acceptance outcome to this run.

Parameters:

result (ConstraintResult)

Return type:

None

property constraint_results: list[ConstraintResult]

Copy of all ConstraintResult rows recorded during evaluation.

property all_passed: bool

True when every stored ConstraintResult has passed (empty is vacuously true).

get_active_behavior_state(part_path_string)[source]

Return the current discrete behavior state name for part_path_string, if any.

Raises:

RuntimeError – If called from a behavior effect with an out-of-scope part_path_string.

Parameters:

part_path_string (str)

Return type:

str | None

set_active_behavior_state(part_path_string, state_name)[source]

Set discrete behavior state for part_path_string (dotted instance path).

Raises:

RuntimeError – If a behavior effect scope forbids mutating this part’s state.

Parameters:

  • part_path_string (str)

  • state_name (str)

Return type:

None

prime_item_payload(part_path_string, event_name, payload)[source]

Stage payload for the next event_name on part_path_string (see emit_item()).

Notes

Not restricted by behavior subtree scope (inter-part delivery).

Parameters:

  • part_path_string (str)

  • event_name (str)

  • payload (Any)

Return type:

None

peek_item_payload(part_path_string, event_name)[source]

Return staged payload for (part_path_string, event_name) without consuming it.

Parameters:

  • part_path_string (str)

  • event_name (str)

Return type:

Any | None

clear_item_payload(part_path_string, event_name)[source]

Remove staged payload for (part_path_string, event_name) after handling.

Parameters:

  • part_path_string (str)

  • event_name (str)

Return type:

None

class tg_model.execution.RunResult(outputs=<factory>, constraint_results=<factory>, failures=<factory>)[source]

Bases: object

Aggregated outcome of one evaluate() / evaluate_async() run.

Parameters:

  • outputs (dict[str, Any])

  • constraint_results (list[ConstraintResult])

  • failures (list[str])

outputs: dict[str, Any]
constraint_results: list[ConstraintResult]
failures: list[str]
property passed: bool

True when there are no failures and every constraint result passed.

class tg_model.execution.SequenceTraceStep(step_index, part_path, sequence_name)[source]

Bases: object

Record of one dispatch_sequence() invocation.

Parameters:

  • step_index (int)

  • part_path (str)

  • sequence_name (str)

step_index: int
part_path: str
sequence_name: str
class tg_model.execution.SlotState(*values)[source]

Bases: Enum

Lifecycle state for one ValueSlot in a RunContext.

UNBOUND = 'unbound'
BOUND_INPUT = 'bound_input'
PENDING = 'pending'
REALIZED = 'realized'
FAILED = 'failed'
BLOCKED = 'blocked'
class tg_model.execution.ValidationResult(failures=<factory>)[source]

Bases: object

Aggregate result of validate_graph().

Parameters:

failures (list[ValidationFailure])

failures: list[ValidationFailure]
property passed: bool

True when failures is empty.

add(category, message, path=None)[source]

Append a ValidationFailure.

Parameters:

  • category (str)

  • message (str)

  • path (str | None)

Return type:

None

class tg_model.execution.ValueSlot(*, stable_id, instance_path, kind, definition_type=None, definition_path=None, metadata=None, has_expr=False, has_computed_by=False)[source]

Bases: object

Describes what can hold a value in the configured topology.

A ValueSlot is part of the configured topology. It describes the slot, not the per-run mutable value. Per-run state lives in RunContext.

Parameters:

  • stable_id (str)

  • instance_path (tuple[str, ...])

  • kind (str)

  • definition_type (type | None)

  • definition_path (tuple[str, ...] | None)

  • metadata (dict[str, Any] | None)

  • has_expr (bool)

  • has_computed_by (bool)

stable_id
instance_path
kind
definition_type
definition_path
metadata
has_expr
has_computed_by
property path_string: str

Dotted instance path for handles and debugging.

property is_parameter: bool

True when kind == "parameter".

property is_attribute: bool

True when kind == "attribute".

tg_model.execution.all_requirements_satisfied(ctx)[source]

Return RequirementSatisfactionSummary.all_passed for ctx.

Returns:

False when there are zero requirement acceptance checks (not vacuously true).

Return type:

bool

Parameters:

ctx (RunContext | RunResult)

See also

summarize_requirement_satisfaction

tg_model.execution.behavior_authoring_projection(definition_type)[source]

Return a JSON-oriented projection of behavioral declarations on definition_type.

Parameters:

definition_type (type) – Compiled part/system type.

Returns:

Node name lists by kind, serialized transitions, and edges (refs via to_dict()).

Return type:

dict

Notes

Tooling hook only: not a strict schema for every metadata field.

tg_model.execution.behavior_trace_to_records(trace)[source]

Flatten trace into JSON-friendly dict rows sorted by step_index.

Parameters:

trace (BehaviorTrace) – Collected steps from one or more dispatch calls.

Returns:

Each dict has kind, step_index, and kind-specific keys.

Return type:

list[dict]

tg_model.execution.compile_graph(model)[source]

Compile dependency graph and per-node compute handlers from a configured model.

This is the only supported public entry point for graph compilation.

Parameters:

model (ConfiguredModel) – Frozen topology from instantiate().

Returns:

  • graph (DependencyGraph) – Bipartite value/compute graph in topological-evaluable form.

  • handlers (dict[str, Callable]) – Sync callables keyed by compute node_id (expressions, roll-ups, externals, constraints).

Raises:

GraphCompilationError – On unresolvable references, binding errors, or other compile failures.

Return type:

tuple[DependencyGraph, dict[str, Callable]]

Notes

Walks value slots, requirement acceptance, constraints, solve groups, and external nodes. Async externals are still scheduled from sync evaluate_async().

Successful results are cached on model._compiled_graph so repeated calls and evaluate() reuse the same (graph, handlers) tuple without recompilation.

tg_model.execution.dispatch_decision(ctx, part, decision_name, *, trace=None, run_merge=True)[source]

Run a declared decision: first branch whose guard passes runs its action.

Parameters:

  • ctx (RunContext) – Current run state.

  • part (PartInstance) – Owner of the decision declaration.

  • decision_name (str) – Declared decision node name.

  • trace (BehaviorTrace, optional) – Records DecisionTraceStep when provided.

  • run_merge (bool, default True) – When False, skip automatic paired merge (advanced sequencing).

Raises:

KeyError – If decision_name is not declared on part.definition_type.

Returns:

outcome is NO_ACTION only when no branch matched and there is no default_action. bool(result) is true iff an action ran.

Return type:

DecisionDispatchResult

Notes

If the decision was declared with merge_point= to a merge() node, also runs that merge’s then_action after the branch action (unless run_merge=False for manual dispatch_merge() — do not call dispatch_merge() again for the same merge when pairing is enabled, or the continuation runs twice).

Branches with guard is None match unconditionally (place them last unless you intend a catch-all).

tg_model.execution.dispatch_event(ctx, part, event_name, *, trace=None)[source]

Dispatch one discrete event on part’s state machine.

Parameters:

  • ctx (RunContext) – Run state (discrete state + optional item payloads).

  • part (PartInstance) – Part whose compiled type owns transitions.

  • event_name (str) – Declared event name (last segment of the event ref path).

  • trace (BehaviorTrace, optional) – When passed, appends a BehaviorStep on success.

Returns:

NO_MATCH, GUARD_FAILED, or fired.

Return type:

DispatchResult

Raises:

Exception – Any guard/effect error propagates; if the effect fails after the state advanced, the prior discrete state is restored first.

Notes

bool(result) is true only when a transition fired.

tg_model.execution.dispatch_fork_join(ctx, part, block_name, *, trace=None)[source]

Execute a fork_join block: branches run one after another (fixed list order).

Raises:

  • KeyError – If block_name is not declared.

  • v0 semantics are deterministic serial execution, not OS-level parallelism or –

  • arbitrary interleaving; fork/join name the logical activity structure. –

Parameters:
Return type:

None

tg_model.execution.dispatch_merge(ctx, part, merge_name, *, trace=None)[source]

Continue at a declared merge: runs optional then_action (shared after branches).

Call after exclusive branches (e.g. following dispatch_decision()) to model a methodology Merge node. If no then_action was declared, returns None and only records the trace step when trace is set.

Raises:

KeyError – If merge_name is not declared.

Parameters:
Return type:

str | None

tg_model.execution.dispatch_sequence(ctx, part, sequence_name, *, trace=None)[source]

Run a declared linear sequence of actions (methodology default simplicity rule).

Raises:

KeyError – If sequence_name is not declared.

Parameters:
Return type:

None

tg_model.execution.emit_item(ctx, cm, source_port, item_kind, payload, *, trace=None)[source]

Send an item from source_port across structural connections.

Parameters:

  • ctx (RunContext) – Stages payloads per receiving part/event.

  • cm (ConfiguredModel) – Supplies connections and handle().

  • source_port (PortInstance) – Emitting port.

  • item_kind (str) – Event name / kind matched on receivers; may be filtered by binding carrying.

  • payload (Any) – Opaque payload for receiver effects.

  • trace (BehaviorTrace, optional) – Records ItemFlowStep rows.

Returns:

One result per matched connection (may be empty).

Return type:

list[DispatchResult]

Notes

For each matching ConnectionBinding (same source port; optional carrying must match item_kind), dispatches item_kind on the receiving part. Payload is staged via RunContext.prime_item_payload() and cleared if dispatch does not fire.

Bindings are visited in cm.connections order (deterministic for a frozen model).

tg_model.execution.instantiate(root_type)[source]

Build a ConfiguredModel from a compiled root type.

Walks the compiled definition depth-first, creating PartInstance, PortInstance, RequirementPackageInstance (composable requirement packages with package-level value slots), ValueSlot, connection bindings, and allocation bindings. Registers handles then freezes all parts.

Parameters:

root_type (type) – Compiled System / Part subclass.

Returns:

Frozen topology ready for compile_graph().

Return type:

ConfiguredModel

Notes

Stable IDs derive from the configured root type plus full instance path so identities stay unique regardless of which intermediate type owns a declaration.

See also

tg_model.execution.graph_compiler.compile_graph, tg_model.execution.evaluator.Evaluator

tg_model.execution.iter_requirement_satisfaction(ctx)[source]

Filter constraint rows that carry requirement_path (acceptance checks).

Parameters:

ctx (RunContext or RunResult) – Object exposing constraint_results (same ordering as evaluation).

Returns:

One row per tagged constraint result.

Return type:

list of RequirementSatisfactionResult

tg_model.execution.scenario_expected_event_names(definition_type, scenario_name)[source]

Return authored expected_event_order names for a scenario node.

Raises:

  • KeyError – If the scenario is missing.

  • ValueError – If metadata is malformed.

Parameters:

  • definition_type (type)

  • scenario_name (str)

Return type:

list[str]

tg_model.execution.summarize_requirement_satisfaction(ctx)[source]

Aggregate iter_requirement_satisfaction() into a summary tuple.

Returns:

Includes RequirementSatisfactionSummary.all_passed semantics for zero checks.

Return type:

RequirementSatisfactionSummary

Parameters:

ctx (RunContext | RunResult)

tg_model.execution.trace_events_chronological(trace)[source]

List (part_path, event_name) for state-machine steps sorted by step_index.

Returns:

Transition events only (excludes decisions, merges, item flows).

Return type:

list[tuple[str, str]]

Parameters:

trace (BehaviorTrace)

tg_model.execution.validate_graph(graph, *, configured_model=None)[source]

Run static checks before evaluation (cycles, orphans, roll-ups, externals).

Parameters:
Returns:

Non-passing result lists structured ValidationFailure rows (never raises for soft checks).

Return type:

ValidationResult

tg_model.execution.validate_scenario_trace(*, definition_type, scenario_name, part_path, trace, ctx=None, root=None)[source]

Compare trace slices to an authored scenario (partial contracts).

Parameters:

  • definition_type (type) – Owner type of the scenario declaration.

  • scenario_name (str) – Scenario node name on that type.

  • part_path (str) – Instance path string for transition-focused checks.

  • trace (BehaviorTrace) – Collected behavioral steps.

  • ctx (RunContext, optional) – Needed when checking final discrete state.

  • root (PartInstance, optional) – Configured root when validating expected_interaction_order.

Returns:

  • ok (bool) – True when every enabled check passes.

  • errors (list[str]) – Human-readable failure messages (empty when ok).

Return type:

tuple[bool, list[str]]

Notes

This is a bundle of independent checks, not one end-to-end story:

  • Transition events for part_path vs expected_event_order.

  • Optional final/initial discrete state (ctx needed for final).

  • Optional global transition order via trace_events_chronological() (state-machine steps only — not decisions, merges, or item flows).

  • Optional item kind order from ItemFlowStep.

Passing everything still does not prove full causal intent; combine with tests or tooling. Call with ctx from outside behavior effects when checking final state.

For expected_interaction_order, pass root (configured root part) so global ordering can be compared. For expected_item_kind_order, compares item flow kinds.