mixle.experimental.typed_runtime.contracts module

Semantic contracts for the experimental statistically typed training runtime.

These types describe what an update means. They intentionally contain no execution code and do not import torch, distributed runtimes, or concrete model families. That makes a compiled plan inspectable before any model is sampled, scored, mutated, placed, or communicated.

class ArtifactKind(*values)

Bases: StrEnum

Versionable artifacts read or written by update nodes.

class ComputeBand(*values)

Bases: StrEnum

Model-side compute-precision eligibility of a node’s scoring subtree.

float32_eligible means the subtree fuses AND every leaf family is in the validated reduced-precision set (mixle.inference.precision_plan.FP32_SAFE_FAMILIES) – the fused float32 kernel’s summed-log-likelihood error is verified < ~1e-6 relative there. The DATA-side conditions (bounded magnitude, non-degenerate variances) remain a runtime decision (optimize(precision="minimal")); this axis declares what the model structure permits. Composition is weakest-link: one ineligible node keeps the tree at float64.

class ContractEvidenceKind(*values)

Bases: StrEnum

Provenance class supporting a compiled update contract.

class ConvergenceCertificate(*values)

Bases: StrEnum

Strongest convergence-guarantee class attributable to a node’s update rule.

Guarantees compose by WEAKEST LINK: a tree’s certificate is the minimum over its nodes’ (see weakest_certificate()). A frozen node is vacuously monotone – a preserved dependency cannot decline the objective.

• monotone_certified: exact / generalized-EM updates under the strict acceptance gate; the accepted-objective sequence is non-decreasing and (bounded above by the estimator variance floors) converges.

• robbins_monro_schedule: first-order updates whose per-round step schedule lies in the Robbins–Monro window (lr_decay in (0.5, 1]) – the step-size conditions stochastic-approximation EM analyses require for almost-sure convergence to stationary points.

• best_visited: stochastic/mutable updates with no schedule guarantee; the outer loop returns the best visited iterate.

• unknown: no attributable guarantee.

property strength: int

Total order for weakest-link composition (higher is stronger).

class ConsistencyRequirement(*values)

Bases: StrEnum

Strongest distributed consistency mode known to preserve semantics.

class CostEstimate(compute_units=0.0, wall_time_seconds=None, communication_bytes=0, peak_memory_bytes=0, source='structural_proxy', sample_count=0)

Bases: object

Planning cost with provenance separating measured data from a proxy.

Parameters:

• compute_units (float)

• wall_time_seconds (float | None)

• communication_bytes (int)

• peak_memory_bytes (int)

• source (str)

• sample_count (int)

property measured: bool

Whether this estimate came from runtime observations.

as_dict()

Return a JSON-compatible representation.

Return type:

dict[str, Any]

class CounterSemantics(*values)

Bases: StrEnum

How a numeric work field relates to earlier observations in the same run.

class CurvatureKind(*values)

Bases: StrEnum

Curvature information available to a geometry-aware optimizer.

class MergeLaw(*values)

Bases: StrEnum

Algebra available for combining work from separate data/model shards.

class ObjectiveKind(*values)

Bases: StrEnum

Objective whose value gives an update its statistical meaning.

class StateSemantics(*values)

Bases: StrEnum

Kinds of mutable or replay-relevant state touched by an update.

class UpdateContract(objective_kind, update_kind, merge_law, state_semantics=<factory>, consistency=ConsistencyRequirement.STRICT_SYNCHRONOUS, curvature_kind=CurvatureKind.UNAVAILABLE, decomposition_axes=(), reads=<factory>, writes=<factory>, outer_objective_compatible=True, exact=True, convergence_certificate=ConvergenceCertificate.UNKNOWN, compute_band=ComputeBand.FLOAT64, declared_by='compiler_default', evidence_kind=ContractEvidenceKind.UNVERIFIED, evidence_id=None, notes=())

Bases: object

Complete semantic declaration for one independently schedulable node.

Parameters:

• objective_kind (ObjectiveKind)

• update_kind (UpdateKind)

• merge_law (MergeLaw)

• state_semantics (frozenset[StateSemantics])

• consistency (ConsistencyRequirement)

• curvature_kind (CurvatureKind)

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

• reads (frozenset[ArtifactKind])

• writes (frozenset[ArtifactKind])

• outer_objective_compatible (bool)

• exact (bool)

• convergence_certificate (ConvergenceCertificate)

• compute_band (ComputeBand)

• declared_by (str)

• evidence_kind (ContractEvidenceKind)

• evidence_id (str | None)

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

property is_mutable: bool

Whether committing/rejecting this update requires state management.

property shard_mergeable: bool

Whether independent shard payloads have a declared merge operation.

as_dict()

Return a stable JSON-compatible representation.

Return type:

dict[str, Any]

class UpdateKind(*values)

Bases: StrEnum

Algorithmic family used to propose a node update.

weakest_band(bands)

FLOAT32_ELIGIBLE only when every node is eligible; FLOAT64 otherwise (or when empty).

Parameters:

bands (Iterable[ComputeBand])

Return type:

ComputeBand

weakest_certificate(certificates)

The minimum certificate over an iterable (the tree-level guarantee); UNKNOWN when empty.

Parameters:

certificates (Iterable[ConvergenceCertificate])

Return type:

ConvergenceCertificate