mixle.experimental.typed_runtime.scheduler module

Deterministic gain-per-cost scheduling over a typed update graph.

class GainEvidence(node_id, objective_kind, expected_gain, model_version, standard_error=0.0, sample_count=0, normalized_to=None, staleness_risk=0.0)

Bases: object

Objective-gain estimate for one update node.

normalized_to is required when a surrogate gain has been transformed to the scheduler’s reporting objective. Merely setting outer_objective_compatible on a contract does not make unlike numeric scales comparable.

Parameters:

• node_id (str)

• objective_kind (ObjectiveKind)

• expected_gain (float)

• model_version (int)

• standard_error (float)

• sample_count (int)

• normalized_to (ObjectiveKind | None)

• staleness_risk (float)

property effective_objective: ObjectiveKind

Objective scale on which expected_gain is expressed.

lower_confidence_bound(z_value)

Return the one-sided normal-approximation lower bound.

Parameters:

z_value (float)

Return type:

float

as_dict()

Return a JSON-compatible representation.

Return type:

dict[str, Any]

class GainPerCostScheduler(config=None)

Bases: object

Stateful deterministic scheduler with terminal-evidence fairness.

Starved nodes move to the front of the ranking, but no scheduling decision may claim resources outside the declared budget.

Parameters:

config (SchedulerConfig | None)

property states: dict[str, NodeScheduleState]

Return a copy of the fairness clocks.

reset()

Reset round and starvation state without changing configuration.

Return type:

None

schedule(graph, evidence=None, *, target_objective=None, model_version, round_index=None, candidate_nodes=None)

Select a budgeted set without claiming that scheduled work succeeded.

Parameters:

• graph (UpdateGraph)

• evidence (dict[str, GainEvidence] | None)

• target_objective (ObjectiveKind | None)

• model_version (int)

• round_index (int | None)

• candidate_nodes (Collection[str] | None)

Return type:

ScheduleReceipt

record_terminal(receipt, outcomes, *, terminal_id)

Advance fairness clocks only after every selected node is terminal.

Parameters:

• receipt (ScheduleReceipt)

• outcomes (Sequence[NodeTerminalReceipt])

• terminal_id (str)

Return type:

ScheduleCompletionReceipt

class NodeExecutionStatus(*values)

Bases: StrEnum

Terminal execution status for one scheduled node.

class NodeScheduleState(committed_count=0, skip_rounds=0, last_committed_round=None)

Bases: object

Persistent fairness clock advanced only by terminal execution evidence.

Parameters:

• committed_count (int)

• skip_rounds (int)

• last_committed_round (int | None)

property selected_count: int

Compatibility alias whose value now counts committed selections only.

property last_selected_round: int | None

Compatibility alias whose value now records the last committed round.

class NodeTerminalReceipt(round_index, node_id, status, evidence_id)

Bases: object

Execution evidence binding a scheduled node to one terminal outcome.

Parameters:

• round_index (int)

• node_id (str)

• status (NodeExecutionStatus)

• evidence_id (str)

as_dict()

Return a JSON-compatible terminal receipt.

Return type:

dict[str, Any]

class ScheduleCompletionReceipt(terminal_id, round_index, outcomes, committed_nodes, unsuccessful_nodes, states_after)

Bases: object

Fairness-state transition justified by complete terminal node evidence.

Parameters:

• terminal_id (str)

• round_index (int)

• outcomes (tuple[NodeTerminalReceipt, ...])

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

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

• states_after (dict[str, NodeScheduleState])

as_dict()

Return a JSON-compatible completion receipt.

Return type:

dict[str, Any]

class ScheduleReceipt(round_index, model_version, target_objective, selected_nodes, ranked_nodes, eligible_nodes, forced_starvation, bootstrap_nodes, lower_confidence_bounds, effective_costs, priorities, invalidation_costs, skipped, rejected_evidence, budget, spent)

Bases: object

Complete, replayable record of one deterministic scheduling decision.

Parameters:

• round_index (int)

• model_version (int)

• target_objective (ObjectiveKind)

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

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

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

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

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

• lower_confidence_bounds (dict[str, float | None])

• effective_costs (dict[str, float])

• priorities (dict[str, float | None])

• invalidation_costs (dict[str, float])

• skipped (dict[str, str])

• rejected_evidence (dict[str, str])

• budget (float)

• spent (float)

property budget_overrun: float

Amount by which a fairness-forced decision exceeds its soft budget.

as_dict()

Return a JSON-compatible receipt.

Return type:

dict[str, Any]

class SchedulerConfig(budget_fraction=0.5, confidence_z=1.645, lambda_network=0.0, lambda_memory=0.0, lambda_stale=1.0, lambda_invalidation=0.1, minimum_gain_lcb=0.0, max_skip_rounds=2, bootstrap_unmeasured=True)

Bases: object

Resource weights and fairness policy for typed greedy scheduling.

Parameters:

• budget_fraction (float)

• confidence_z (float)

• lambda_network (float)

• lambda_memory (float)

• lambda_stale (float)

• lambda_invalidation (float)

• minimum_gain_lcb (float)

• max_skip_rounds (int)

• bootstrap_unmeasured (bool)