"""Fail-closed static validation for System Numeric IR v2.""" from __future__ import annotations from dataclasses import dataclass, fields, is_dataclass from math import isfinite from types import UnionType from typing import Union, get_args, get_origin, get_type_hints from app.simulation.ir import schema as ir SUPPORTED_REQUIRED_FEATURES = frozenset( { "callback_free", "independent_entry_points", "transactional_closure", "fixed_csr_jacobian", "reference_kernel_dispatch", } ) @dataclass(frozen=True, slots=True) class IRValidationIssue: code: str path: str message: str @dataclass(frozen=True, slots=True) class IRValidationReport: issues: tuple[IRValidationIssue, ...] @property def valid(self) -> bool: return not self.issues class SystemIRValidationError(ValueError): def __init__(self, report: IRValidationReport) -> None: self.report = report summary = "; ".join( f"{issue.code} at {issue.path}: {issue.message}" for issue in report.issues[:8] ) if len(report.issues) > 8: summary += f"; and {len(report.issues) - 8} more issue(s)" super().__init__(f"System IR validation failed: {summary}") class _Issues: def __init__(self) -> None: self.items: list[IRValidationIssue] = [] def add(self, code: str, path: str, message: str) -> None: self.items.append(IRValidationIssue(code, path, message)) def unique_ids(self, values: tuple[object, ...], attribute: str, path: str) -> None: seen: dict[str, int] = {} for index, value in enumerate(values): identity = str(getattr(value, attribute)) if not identity: self.add("EMPTY_ID", f"{path}[{index}].{attribute}", "ID must not be empty.") if identity in seen: self.add( "DUPLICATE_ID", f"{path}[{index}].{attribute}", f"Duplicates {path}[{seen[identity]}].", ) else: seen[identity] = index def _finite(value: float | None) -> bool: return value is None or isfinite(float(value)) _TYPE_HINT_CACHE: dict[type[object], dict[str, object]] = {} def _matches_runtime_type(value: object, annotation: object) -> bool: origin = get_origin(annotation) if origin in {UnionType, Union}: return any(_matches_runtime_type(value, item) for item in get_args(annotation)) if origin is tuple: return type(value) is tuple if annotation is type(None): return value is None if isinstance(annotation, type): return type(value) is annotation return False def _validate_runtime_types( value: object, annotation: object, path: str, issues: _Issues, seen: set[tuple[int, object]], ) -> None: """Reject values that would serialize differently from their schema type.""" origin = get_origin(annotation) if origin in {UnionType, Union}: matching = tuple( item for item in get_args(annotation) if _matches_runtime_type(value, item) ) if len(matching) != 1: issues.add( "RUNTIME_TYPE_MISMATCH", path, f"Value has type {type(value).__name__}, which does not match the declared union.", ) return _validate_runtime_types(value, matching[0], path, issues, seen) return if origin is tuple: if type(value) is not tuple: issues.add( "RUNTIME_TYPE_MISMATCH", path, "Schema arrays must be immutable tuples before serialization.", ) return arguments = get_args(annotation) if len(arguments) == 2 and arguments[1] is Ellipsis: for index, item in enumerate(value): _validate_runtime_types( item, arguments[0], f"{path}[{index}]", issues, seen, ) return if len(value) != len(arguments): issues.add( "RUNTIME_TYPE_MISMATCH", path, "Tuple length differs from its declared schema type.", ) return for index, (item, item_type) in enumerate(zip(value, arguments)): _validate_runtime_types( item, item_type, f"{path}[{index}]", issues, seen, ) return if annotation is type(None): if value is not None: issues.add("RUNTIME_TYPE_MISMATCH", path, "Expected null.") return if not isinstance(annotation, type) or type(value) is not annotation: expected_name = getattr(annotation, "__name__", str(annotation)) issues.add( "RUNTIME_TYPE_MISMATCH", path, f"Expected {expected_name}, received {type(value).__name__}.", ) return if not is_dataclass(value): return marker = (id(value), annotation) if marker in seen: return seen.add(marker) hints = _TYPE_HINT_CACHE.get(annotation) if hints is None: hints = get_type_hints(annotation) _TYPE_HINT_CACHE[annotation] = hints for item in fields(value): _validate_runtime_types( getattr(value, item.name), hints[item.name], f"{path}.{item.name}", issues, seen, ) def _validate_csr( pattern: ir.IRCSRPattern, path: str, issues: _Issues, ) -> None: if pattern.row_count < 0 or pattern.column_count < 0: issues.add("CSR_NEGATIVE_SHAPE", path, "CSR dimensions must be non-negative.") pointers = pattern.row_pointers columns = pattern.column_indices if len(pointers) != pattern.row_count + 1: issues.add("CSR_ROW_POINTER_LENGTH", f"{path}.row_pointers", "Length must be row_count + 1.") return if not pointers or pointers[0] != 0: issues.add("CSR_ROW_POINTER_START", f"{path}.row_pointers", "First pointer must be zero.") return if any(first > second for first, second in zip(pointers, pointers[1:])): issues.add("CSR_ROW_POINTER_ORDER", f"{path}.row_pointers", "Pointers must be monotonic.") return if pointers[-1] != len(columns): issues.add("CSR_NONZERO_COUNT", path, "Final row pointer must equal column count length.") return for row in range(pattern.row_count): row_columns = columns[pointers[row] : pointers[row + 1]] if any(column < 0 or column >= pattern.column_count for column in row_columns): issues.add("CSR_COLUMN_BOUNDS", f"{path}.row[{row}]", "Column index is out of bounds.") if tuple(sorted(set(row_columns))) != row_columns: issues.add("CSR_ROW_CANONICAL", f"{path}.row[{row}]", "Columns must be sorted and unique.") def _operation_slots(operation: ir.IROperation) -> tuple[ir.IRSlotRef, ...]: return (*ir.operation_read_slots(operation), *ir.operation_write_slots(operation)) def validate_system_ir(program: ir.SystemIR) -> IRValidationReport: """Validate every cross-reference and numeric invariant in one program.""" issues = _Issues() _validate_runtime_types(program, ir.SystemIR, "$", issues, set()) if issues.items: return IRValidationReport(tuple(issues.items)) if program.version.schema_id != ir.SYSTEM_NUMERIC_IR_SCHEMA_ID: issues.add("SCHEMA_ID_UNSUPPORTED", "version.schema_id", "Unknown schema ID.") if program.version.major != ir.SYSTEM_NUMERIC_IR_SCHEMA_MAJOR: issues.add("SCHEMA_MAJOR_UNSUPPORTED", "version.major", "Unknown schema major version.") if program.version.minor < 0: issues.add("SCHEMA_MINOR_INVALID", "version.minor", "Schema minor version cannot be negative.") elif program.version.minor > ir.SYSTEM_NUMERIC_IR_SCHEMA_MINOR: issues.add("SCHEMA_MINOR_UNSUPPORTED", "version.minor", "Schema minor version is newer than this reader.") if program.numeric_dtype is not ir.IRDType.FLOAT64: issues.add("NUMERIC_DTYPE_UNSUPPORTED", "numeric_dtype", "Only float64 programs are supported.") for name, value in ( ("model_id", program.model_id), ("model_version", program.model_version), ("compiler_id", program.compiler_id), ("compiler_version", program.compiler_version), ): if not value: issues.add("EMPTY_ID", name, f"{name} must not be empty.") unknown_features = sorted(set(program.required_features) - SUPPORTED_REQUIRED_FEATURES) if unknown_features: issues.add("REQUIRED_FEATURE_UNSUPPORTED", "required_features", ", ".join(unknown_features)) if len(set(program.required_features)) != len(program.required_features): issues.add("DUPLICATE_REQUIRED_FEATURE", "required_features", "Features must be unique.") buffer_by_kind: dict[ir.IRBufferKind, ir.IRBufferSpec] = {} expected_buffer_dtypes = { kind: ( ir.IRDType.INT32 if kind in {ir.IRBufferKind.MODE, ir.IRBufferKind.WORK_INT} else ir.IRDType.FLOAT64 ) for kind in ir.IRBufferKind } for index, buffer in enumerate(program.buffers): path = f"buffers[{index}]" if buffer.kind in buffer_by_kind: issues.add("DUPLICATE_BUFFER", path, f"Buffer {buffer.kind.value} is declared twice.") buffer_by_kind[buffer.kind] = buffer if buffer.size < 0: issues.add("BUFFER_NEGATIVE_SIZE", f"{path}.size", "Size must be non-negative.") if buffer.dtype is not expected_buffer_dtypes[buffer.kind]: issues.add( "BUFFER_DTYPE_INVALID", f"{path}.dtype", f"{buffer.kind.value} requires {expected_buffer_dtypes[buffer.kind].value}.", ) if buffer.initial_float_values and buffer.initial_int_values: issues.add("BUFFER_MIXED_INITIAL_VALUES", path, "A buffer cannot have both float and integer initial values.") if buffer.initial_float_values and len(buffer.initial_float_values) != buffer.size: issues.add("BUFFER_INITIAL_SIZE", path, "Float initial values must cover the full buffer.") if buffer.initial_int_values and len(buffer.initial_int_values) != buffer.size: issues.add("BUFFER_INITIAL_SIZE", path, "Integer initial values must cover the full buffer.") if any(not isfinite(float(value)) for value in buffer.initial_float_values): issues.add("NONFINITE_VALUE", path, "Buffer initial values must be finite.") if buffer.dtype is ir.IRDType.FLOAT64 and buffer.initial_int_values: issues.add("BUFFER_INITIAL_TYPE", path, "float64 buffer cannot use integer initial values.") if buffer.dtype is not ir.IRDType.FLOAT64 and buffer.initial_float_values: issues.add("BUFFER_INITIAL_TYPE", path, "Integer buffer cannot use float initial values.") if any(value < -(2**31) or value > 2**31 - 1 for value in buffer.initial_int_values): issues.add("BUFFER_INT32_RANGE", path, "Integer initial values must fit signed int32.") required_buffers = set(ir.IRBufferKind) for kind in sorted(required_buffers - set(buffer_by_kind), key=lambda value: value.value): issues.add("MISSING_BUFFER", "buffers", f"Missing {kind.value} buffer.") time_buffer = buffer_by_kind.get(ir.IRBufferKind.TIME) if time_buffer is not None and time_buffer.size != 1: issues.add("TIME_BUFFER_SIZE", "buffers", "The time buffer must contain exactly one float64 value.") def valid_slot(slot: ir.IRSlotRef, path: str) -> bool: buffer = buffer_by_kind.get(slot.buffer) if buffer is None: issues.add("SLOT_BUFFER_MISSING", path, f"Buffer {slot.buffer.value} is not declared.") return False if slot.index < 0 or slot.index >= buffer.size: issues.add("SLOT_INDEX_BOUNDS", path, f"Index {slot.index} is outside buffer size {buffer.size}.") return False return True issues.unique_ids(program.values, "value_id", "values") value_slots: set[ir.IRSlotRef] = set() for index, value in enumerate(program.values): path = f"values[{index}]" valid_slot(value.slot, f"{path}.slot") if value.slot in value_slots: issues.add("DUPLICATE_VALUE_SLOT", f"{path}.slot", "A numeric slot has more than one value descriptor.") value_slots.add(value.slot) if not value.semantic or not value.role or not value.quantity: issues.add( "VALUE_METADATA_INCOMPLETE", path, "Value semantic, role and quantity must not be empty.", ) if not isfinite(value.scale) or value.scale <= 0.0: issues.add("VALUE_SCALE_INVALID", f"{path}.scale", "Scale must be finite and positive.") if not _finite(value.lower_bound) or not _finite(value.upper_bound): issues.add("NONFINITE_VALUE", path, "Bounds must be finite or null.") if value.lower_bound is not None and value.upper_bound is not None and value.lower_bound > value.upper_bound: issues.add("VALUE_BOUNDS_ORDER", path, "Lower bound exceeds upper bound.") if value.owner_component_index is not None and not 0 <= value.owner_component_index < len(program.components): issues.add("COMPONENT_INDEX_BOUNDS", f"{path}.owner_component_index", "Component index is invalid.") expected_value_slots = { ir.IRSlotRef(buffer.kind, index) for buffer in program.buffers for index in range(max(0, buffer.size)) } if value_slots != expected_value_slots: issues.add( "VALUE_SLOT_COVERAGE", "values", "Value descriptors must cover every declared buffer slot exactly once.", ) issues.unique_ids(program.kernels, "kernel_id", "kernels") for index, kernel in enumerate(program.kernels): path = f"kernels[{index}]" if not kernel.model_type or not kernel.model_version or not kernel.implementation_version: issues.add("KERNEL_IDENTITY_INCOMPLETE", path, "Kernel type and versions are required.") counts = ( kernel.parameter_count, kernel.state_count, kernel.mode_count, kernel.workspace_float_count, kernel.workspace_int_count, ) if any(count < 0 for count in counts): issues.add("KERNEL_NEGATIVE_ARITY", path, "Kernel arities must be non-negative.") phases = tuple(phase.phase for phase in kernel.phases) if not phases: issues.add("KERNEL_PHASE_MISSING", f"{path}.phases", "Every kernel must declare at least one phase.") if len(set(phases)) != len(phases): issues.add("KERNEL_DUPLICATE_PHASE", f"{path}.phases", "Kernel phases must be unique.") if kernel.availability is ir.IRKernelAvailability.NATIVE and kernel.unavailable_reason is not None: issues.add("KERNEL_AVAILABILITY_CONFLICT", path, "Native kernel cannot have an unavailable reason.") if kernel.availability is ir.IRKernelAvailability.REFERENCE_ONLY and not kernel.unavailable_reason: issues.add("KERNEL_AVAILABILITY_REASON_MISSING", path, "Reference-only kernel needs a reason.") issues.unique_ids(program.components, "instance_id", "components") for index, component in enumerate(program.components): path = f"components[{index}]" if not 0 <= component.kernel_index < len(program.kernels): issues.add("KERNEL_INDEX_BOUNDS", f"{path}.kernel_index", "Kernel index is invalid.") continue kernel = program.kernels[component.kernel_index] for slot_index, slot in enumerate( (*component.parameter_slots, *component.state_slots, *component.derivative_slots, *component.mode_slots, *component.port_slots, *component.workspace_float_slots, *component.workspace_int_slots) ): valid_slot(slot, f"{path}.slots[{slot_index}]") binding_kinds = ( (component.parameter_slots, ir.IRBufferKind.PARAMETER, "parameter_slots"), (component.state_slots, ir.IRBufferKind.LOCAL_STATE, "state_slots"), ( component.derivative_slots, ir.IRBufferKind.LOCAL_DERIVATIVE, "derivative_slots", ), (component.mode_slots, ir.IRBufferKind.MODE, "mode_slots"), ( component.workspace_float_slots, ir.IRBufferKind.WORK_FLOAT, "workspace_float_slots", ), ( component.workspace_int_slots, ir.IRBufferKind.WORK_INT, "workspace_int_slots", ), ) for bound_slots, expected_kind, label in binding_kinds: if any(slot.buffer is not expected_kind for slot in bound_slots): issues.add( "COMPONENT_BINDING_BUFFER", f"{path}.{label}", f"Bindings must use the {expected_kind.value} buffer.", ) if len(set(bound_slots)) != len(bound_slots): issues.add( "COMPONENT_BINDING_DUPLICATE", f"{path}.{label}", "Bindings within one component must be unique.", ) if len(component.parameter_slots) != kernel.parameter_count: issues.add("KERNEL_PARAMETER_ARITY", path, "Component parameter binding count differs from kernel.") if len(component.state_slots) != kernel.state_count or len(component.derivative_slots) != kernel.state_count: issues.add("KERNEL_STATE_ARITY", path, "Component state bindings differ from kernel.") if len(component.mode_slots) != kernel.mode_count: issues.add("KERNEL_MODE_ARITY", path, "Component mode bindings differ from kernel.") if len(component.workspace_float_slots) != kernel.workspace_float_count: issues.add("KERNEL_WORKSPACE_ARITY", path, "Float workspace bindings differ from kernel.") if len(component.workspace_int_slots) != kernel.workspace_int_count: issues.add("KERNEL_WORKSPACE_ARITY", path, "Integer workspace bindings differ from kernel.") if any(port < 0 or port >= len(program.ports) for port in component.port_indices): issues.add("PORT_INDEX_BOUNDS", f"{path}.port_indices", "Port index is invalid.") if any(output < 0 or output >= len(program.outputs) for output in component.output_indices): issues.add("OUTPUT_INDEX_BOUNDS", f"{path}.output_indices", "Output index is invalid.") issues.unique_ids(program.ports, "port_id", "ports") port_variable_ids: set[str] = set() for index, port in enumerate(program.ports): path = f"ports[{index}]" if not port.name or not port.domain: issues.add("PORT_METADATA_INCOMPLETE", path, "Port name and domain must not be empty.") if not 0 <= port.component_index < len(program.components): issues.add("COMPONENT_INDEX_BOUNDS", f"{path}.component_index", "Component index is invalid.") if port.kind is ir.IRPortKind.PHYSICAL and port.positive_flow_direction is None: issues.add("PORT_FLOW_DIRECTION_MISSING", path, "Physical ports need a positive-flow direction.") if port.kind is ir.IRPortKind.SIGNAL and port.positive_flow_direction is not None: issues.add("PORT_FLOW_DIRECTION_INVALID", path, "Signal ports cannot define physical flow direction.") names: set[str] = set() for variable_index, variable in enumerate(port.variables): variable_path = f"{path}.variables[{variable_index}]" if not variable.variable_id or not variable.name: issues.add("PORT_VARIABLE_ID_INVALID", variable_path, "Port variable names and IDs must be non-empty.") if not variable.quantity: issues.add("PORT_VARIABLE_METADATA_INCOMPLETE", variable_path, "Port variable quantity must not be empty.") if variable.variable_id in port_variable_ids: issues.add("PORT_VARIABLE_ID_INVALID", variable_path, "Port variable ID must be globally unique.") port_variable_ids.add(variable.variable_id) if variable.name in names: issues.add("PORT_VARIABLE_ID_INVALID", variable_path, "Port variable name must be unique within its port.") names.add(variable.name) valid_slot(variable.slot, f"{variable_path}.slot") expected_rule = { ir.IRVariableRole.EFFORT: ir.IRConnectionRule.EQUAL, ir.IRVariableRole.FLOW: ir.IRConnectionRule.SUM_TO_ZERO, ir.IRVariableRole.STREAM: ir.IRConnectionRule.STREAM_MIX, ir.IRVariableRole.SIGNAL: ir.IRConnectionRule.DIRECTED, }[variable.role] if variable.connection_rule is not expected_rule: issues.add( "PORT_VARIABLE_RULE_INVALID", variable_path, f"{variable.role.value} variables require {expected_rule.value}.", ) if 0 <= port.component_index < len(program.components) and index not in program.components[port.component_index].port_indices: issues.add("COMPONENT_PORT_BACKREF", path, "Owning component does not reference this port.") for component_index, component in enumerate(program.components): expected_port_indices = tuple( index for index, port in enumerate(program.ports) if port.component_index == component_index ) if component.port_indices != expected_port_indices: issues.add( "COMPONENT_PORT_COVERAGE", f"components[{component_index}].port_indices", "Component port indices must exactly cover its owned ports in program order.", ) if all(0 <= index < len(program.ports) for index in component.port_indices): expected_port_slots = tuple( variable.slot for port_index in component.port_indices for variable in program.ports[port_index].variables ) if component.port_slots != expected_port_slots: issues.add( "COMPONENT_PORT_SLOT_COVERAGE", f"components[{component_index}].port_slots", "Component port slots must match its ordered port-variable bindings.", ) issues.unique_ids(program.connections, "connection_id", "connections") connected_port_indices: list[int] = [] endpoint_pairs: set[tuple[int, int]] = set() for index, connection in enumerate(program.connections): path = f"connections[{index}]" endpoints = (connection.endpoint_a_port_index, connection.endpoint_b_port_index) if endpoints[0] == endpoints[1]: issues.add("CONNECTION_SELF_LOOP", path, "Connection endpoints must be distinct ports.") if any(endpoint < 0 or endpoint >= len(program.ports) for endpoint in endpoints): issues.add("PORT_INDEX_BOUNDS", path, "Connection endpoint is invalid.") continue connected_port_indices.extend(endpoints) endpoint_pair = tuple(sorted(endpoints)) if endpoint_pair in endpoint_pairs: issues.add("CONNECTION_DUPLICATE", path, "The same port pair is connected more than once.") endpoint_pairs.add(endpoint_pair) first, second = (program.ports[endpoint] for endpoint in endpoints) if first.kind is not connection.kind or second.kind is not connection.kind or first.domain != connection.domain or second.domain != connection.domain: issues.add("CONNECTION_DOMAIN_MISMATCH", path, "Connection kind/domain differs from an endpoint.") first_variables = {variable.name: variable for variable in first.variables} second_variables = {variable.name: variable for variable in second.variables} connection_names = tuple(variable.name for variable in connection.variables) if ( len(set(connection_names)) != len(connection_names) or set(connection_names) != set(first_variables) or set(connection_names) != set(second_variables) ): issues.add( "CONNECTION_VARIABLE_COVERAGE", f"{path}.variables", "Connection variables must cover both endpoint contracts exactly once.", ) for variable_index, variable in enumerate(connection.variables): variable_path = f"{path}.variables[{variable_index}]" valid_slot(variable.endpoint_a_slot, f"{variable_path}.endpoint_a_slot") valid_slot(variable.endpoint_b_slot, f"{variable_path}.endpoint_b_slot") if variable.name not in first_variables or variable.name not in second_variables: issues.add("CONNECTION_VARIABLE_MISSING", variable_path, "Variable is absent from an endpoint.") elif ( first_variables[variable.name].slot != variable.endpoint_a_slot or second_variables[variable.name].slot != variable.endpoint_b_slot or first_variables[variable.name].connection_rule is not variable.rule or second_variables[variable.name].connection_rule is not variable.rule ): issues.add("CONNECTION_VARIABLE_MISMATCH", variable_path, "Connection variable does not match its ports.") connection_counts: dict[int, int] = {} for port_index in connected_port_indices: connection_counts[port_index] = connection_counts.get(port_index, 0) + 1 for port_index, count in connection_counts.items(): port = program.ports[port_index] allows_fan_out = ( port.kind is ir.IRPortKind.SIGNAL and port.nominal_role is ir.IRPortNominalRole.OUTPUT ) if count > 1 and not allows_fan_out: issues.add( "CONNECTION_PORT_REUSED", f"ports[{port_index}]", "Physical ports and signal inputs may have at most one connection.", ) issues.unique_ids(program.mediums, "medium_id", "mediums") for index, medium in enumerate(program.mediums): path = f"mediums[{index}]" if not medium.name or not medium.implementation_id or not medium.implementation_version: issues.add("MEDIUM_IDENTITY_INCOMPLETE", path, "Medium identity is incomplete.") if len(set(medium.parameter_slots)) != len(medium.parameter_slots): issues.add("MEDIUM_PARAMETER_DUPLICATE", f"{path}.parameter_slots", "Medium parameter slots must be unique.") if len(set(medium.component_indices)) != len(medium.component_indices): issues.add("MEDIUM_COMPONENT_DUPLICATE", f"{path}.component_indices", "Medium component indices must be unique.") for slot_index, slot in enumerate(medium.parameter_slots): valid_slot(slot, f"{path}.parameter_slots[{slot_index}]") if slot.buffer is not ir.IRBufferKind.CONSTANT: issues.add("MEDIUM_PARAMETER_BUFFER", f"{path}.parameter_slots[{slot_index}]", "Medium constants must use the constant buffer.") if any(component < 0 or component >= len(program.components) for component in medium.component_indices): issues.add("COMPONENT_INDEX_BOUNDS", f"{path}.component_indices", "Medium component index is invalid.") reducer = program.state_reducer state_buffer = buffer_by_kind.get(ir.IRBufferKind.STATE_INPUT) derivative_buffer = buffer_by_kind.get(ir.IRBufferKind.DERIVATIVE_OUTPUT) if state_buffer is not None and state_buffer.size != reducer.solver_state_count: issues.add("STATE_COUNT_MISMATCH", "state_reducer", "State buffer size differs from reducer count.") if derivative_buffer is not None and derivative_buffer.size != reducer.solver_state_count: issues.add("DERIVATIVE_COUNT_MISMATCH", "state_reducer", "Derivative buffer size differs from reducer count.") if len(reducer.initial_state) != reducer.solver_state_count or len(reducer.absolute_tolerances) != reducer.solver_state_count: issues.add("STATE_METADATA_LENGTH", "state_reducer", "Initial state and tolerances must cover every state.") if any(not isfinite(value) for value in reducer.initial_state): issues.add("NONFINITE_VALUE", "state_reducer.initial_state", "Initial state must be finite.") if ( state_buffer is not None and state_buffer.initial_float_values != reducer.initial_state ): issues.add( "STATE_INITIAL_VALUE_MISMATCH", "state_reducer.initial_state", "State-input buffer initial values must exactly equal the reducer initial state.", ) if any(not isfinite(value) or value <= 0.0 for value in reducer.absolute_tolerances): issues.add("STATE_TOLERANCE_INVALID", "state_reducer.absolute_tolerances", "Tolerances must be finite and positive.") for index, slot in enumerate(reducer.local_state_slots): valid_slot(slot, f"state_reducer.local_state_slots[{index}]") if slot.buffer is not ir.IRBufferKind.LOCAL_STATE: issues.add("STATE_REDUCER_BUFFER", f"state_reducer.local_state_slots[{index}]", "Local states must use the local_state buffer.") for index, slot in enumerate(reducer.raw_derivative_slots): valid_slot(slot, f"state_reducer.raw_derivative_slots[{index}]") if slot.buffer is not ir.IRBufferKind.LOCAL_DERIVATIVE: issues.add("STATE_REDUCER_BUFFER", f"state_reducer.raw_derivative_slots[{index}]", "Raw derivatives must use the local_derivative buffer.") expected_local_state_slots = tuple( slot for component in program.components for slot in component.state_slots ) expected_raw_derivative_slots = tuple( slot for component in program.components for slot in component.derivative_slots ) if reducer.local_state_slots != expected_local_state_slots: issues.add( "STATE_REDUCER_LOCAL_COVERAGE", "state_reducer.local_state_slots", "Reducer local-state order must exactly match component state bindings.", ) if reducer.raw_derivative_slots != expected_raw_derivative_slots: issues.add( "STATE_REDUCER_DERIVATIVE_COVERAGE", "state_reducer.raw_derivative_slots", "Reducer derivative order must exactly match component derivative bindings.", ) _validate_csr(reducer.state_scatter.pattern, "state_reducer.state_scatter.pattern", issues) _validate_csr(reducer.derivative_gather.pattern, "state_reducer.derivative_gather.pattern", issues) if reducer.state_scatter.pattern.row_count != len(reducer.local_state_slots) or reducer.state_scatter.pattern.column_count != reducer.solver_state_count: issues.add("STATE_SCATTER_SHAPE", "state_reducer.state_scatter", "Scatter shape must be local_state_count x solver_state_count.") if reducer.derivative_gather.pattern.row_count != reducer.solver_state_count or reducer.derivative_gather.pattern.column_count != len(reducer.raw_derivative_slots): issues.add("DERIVATIVE_GATHER_SHAPE", "state_reducer.derivative_gather", "Gather shape must be solver_state_count x raw_derivative_count.") if len(reducer.state_scatter.values) != reducer.state_scatter.pattern.nonzero_count: issues.add("CSR_VALUE_COUNT", "state_reducer.state_scatter.values", "Value count differs from pattern.") if len(reducer.derivative_gather.values) != reducer.derivative_gather.pattern.nonzero_count: issues.add("CSR_VALUE_COUNT", "state_reducer.derivative_gather.values", "Value count differs from pattern.") if any(not isfinite(value) for value in (*reducer.state_scatter.values, *reducer.derivative_gather.values)): issues.add("NONFINITE_VALUE", "state_reducer", "Reducer matrix values must be finite.") if ( reducer.state_scatter.pattern.row_pointers and any( first == second for first, second in zip( reducer.state_scatter.pattern.row_pointers, reducer.state_scatter.pattern.row_pointers[1:], ) ) ): issues.add("STATE_SCATTER_EMPTY_ROW", "state_reducer.state_scatter", "Every local state must depend on at least one solver state.") if set(reducer.state_scatter.pattern.column_indices) != set( range(reducer.solver_state_count) ): issues.add("STATE_SCATTER_COLUMN_COVERAGE", "state_reducer.state_scatter", "Every solver state must feed at least one local state.") if set(reducer.derivative_gather.pattern.column_indices) != set( range(len(reducer.raw_derivative_slots)) ): issues.add("DERIVATIVE_GATHER_COLUMN_COVERAGE", "state_reducer.derivative_gather", "Every raw derivative must contribute to a solver derivative.") if ( reducer.derivative_gather.pattern.row_pointers and any( first == second for first, second in zip( reducer.derivative_gather.pattern.row_pointers, reducer.derivative_gather.pattern.row_pointers[1:], ) ) ): issues.add("DERIVATIVE_GATHER_EMPTY_ROW", "state_reducer.derivative_gather", "Every solver state must receive at least one derivative contribution.") pressure_flow = program.pressure_flow issues.unique_ids(pressure_flow.unknowns, "unknown_id", "pressure_flow.unknowns") issues.unique_ids(pressure_flow.equations, "equation_id", "pressure_flow.equations") issues.unique_ids(pressure_flow.blocks, "block_id", "pressure_flow.blocks") issues.unique_ids(pressure_flow.scopes, "scope_id", "pressure_flow.scopes") for index, unknown in enumerate(pressure_flow.unknowns): path = f"pressure_flow.unknowns[{index}]" valid_slot(unknown.slot, f"{path}.slot") if unknown.slot.buffer is not ir.IRBufferKind.ALGEBRAIC: issues.add("PRESSURE_FLOW_UNKNOWN_BUFFER", f"{path}.slot", "Pressure-flow unknowns must use the algebraic buffer.") if not 0 <= unknown.component_index < len(program.components) or not 0 <= unknown.port_index < len(program.ports): issues.add("PRESSURE_FLOW_UNKNOWN_OWNER", path, "Unknown owner is invalid.") else: port = program.ports[unknown.port_index] matching_variables = tuple( variable for variable in port.variables if variable.name == unknown.variable ) if ( port.component_index != unknown.component_index or len(matching_variables) != 1 or matching_variables[0].variable_id != unknown.unknown_id or matching_variables[0].role is not unknown.role or matching_variables[0].slot != unknown.slot ): issues.add( "PRESSURE_FLOW_UNKNOWN_OWNER", path, "Unknown must match one variable on a port owned by its component.", ) if not isfinite(unknown.scale) or unknown.scale <= 0.0: issues.add("VALUE_SCALE_INVALID", f"{path}.scale", "Scale must be finite and positive.") if not _finite(unknown.lower_bound) or not _finite(unknown.upper_bound): issues.add("NONFINITE_VALUE", path, "Unknown bounds must be finite or null.") if unknown.lower_bound is not None and unknown.upper_bound is not None and unknown.lower_bound > unknown.upper_bound: issues.add("VALUE_BOUNDS_ORDER", path, "Unknown lower bound exceeds upper bound.") residual_slots: set[ir.IRSlotRef] = set() for index, equation in enumerate(pressure_flow.equations): path = f"pressure_flow.equations[{index}]" valid_slot(equation.residual_slot, f"{path}.residual_slot") if equation.residual_slot in residual_slots: issues.add( "PRESSURE_FLOW_RESIDUAL_SLOT_DUPLICATE", f"{path}.residual_slot", "Every pressure-flow equation requires a unique residual slot.", ) residual_slots.add(equation.residual_slot) if equation.residual_slot.buffer is not ir.IRBufferKind.WORK_FLOAT: issues.add("EQUATION_RESIDUAL_BUFFER", f"{path}.residual_slot", "Equation residuals must use the float workspace.") for slot_index, slot in enumerate(equation.variable_slots): valid_slot(slot, f"{path}.variable_slots[{slot_index}]") if slot.buffer not in { ir.IRBufferKind.ALGEBRAIC, ir.IRBufferKind.LOCAL_STATE, ir.IRBufferKind.SIGNAL, ir.IRBufferKind.PARAMETER, ir.IRBufferKind.CONSTANT, ir.IRBufferKind.MODE, ir.IRBufferKind.RUNTIME_INPUT, }: issues.add( "EQUATION_VARIABLE_BUFFER", f"{path}.variable_slots[{slot_index}]", "Equation variables must be model values, not time or result buffers.", ) if len(set(equation.variable_slots)) != len(equation.variable_slots): issues.add("EQUATION_VARIABLE_DUPLICATE", f"{path}.variable_slots", "Equation variables must be unique.") owner_count = len(program.components) if equation.owner is ir.IREquationOwner.COMPONENT else len(program.connections) if not 0 <= equation.owner_index < owner_count: issues.add("EQUATION_OWNER_BOUNDS", path, "Equation owner index is invalid.") if not isfinite(equation.scale) or equation.scale <= 0.0: issues.add("VALUE_SCALE_INVALID", f"{path}.scale", "Equation scale must be finite and positive.") for index, block in enumerate(pressure_flow.blocks): path = f"pressure_flow.blocks[{index}]" if len(set(block.unknown_indices)) != len(block.unknown_indices): issues.add("ALGEBRAIC_BLOCK_DUPLICATE", f"{path}.unknown_indices", "Block unknowns must be unique.") if len(set(block.equation_indices)) != len(block.equation_indices): issues.add("ALGEBRAIC_BLOCK_DUPLICATE", f"{path}.equation_indices", "Block equations must be unique.") if any(item < 0 or item >= len(pressure_flow.unknowns) for item in block.unknown_indices): issues.add("UNKNOWN_INDEX_BOUNDS", path, "Block unknown index is invalid.") if any(item < 0 or item >= len(pressure_flow.equations) for item in block.equation_indices): issues.add("EQUATION_INDEX_BOUNDS", path, "Block equation index is invalid.") _validate_csr(block.jacobian_pattern, f"{path}.jacobian_pattern", issues) if block.jacobian_pattern.row_count != len(block.equation_indices) or block.jacobian_pattern.column_count != len(block.unknown_indices): issues.add("ALGEBRAIC_BLOCK_SHAPE", path, "Block Jacobian shape differs from its rows/columns.") block_unknowns = tuple( item for block in pressure_flow.blocks for item in block.unknown_indices ) block_equations = tuple( item for block in pressure_flow.blocks for item in block.equation_indices ) if ( tuple(sorted(block_unknowns)) != tuple(range(len(pressure_flow.unknowns))) or len(set(block_unknowns)) != len(block_unknowns) ): issues.add("ALGEBRAIC_BLOCK_UNKNOWN_PARTITION", "pressure_flow.blocks", "Blocks must partition all pressure-flow unknowns.") if ( tuple(sorted(block_equations)) != tuple(range(len(pressure_flow.equations))) or len(set(block_equations)) != len(block_equations) ): issues.add("ALGEBRAIC_BLOCK_EQUATION_PARTITION", "pressure_flow.blocks", "Blocks must partition all pressure-flow equations.") for index, scope in enumerate(pressure_flow.scopes): path = f"pressure_flow.scopes[{index}]" bounds = ( (scope.component_indices, len(program.components), "component"), (scope.unknown_indices, len(pressure_flow.unknowns), "unknown"), (scope.equation_indices, len(pressure_flow.equations), "equation"), (scope.block_indices, len(pressure_flow.blocks), "block"), ) for indexes, upper, label in bounds: if any(item < 0 or item >= upper for item in indexes): issues.add(f"{label.upper()}_INDEX_BOUNDS", path, f"Scope {label} index is invalid.") if len(set(indexes)) != len(indexes): issues.add(f"{label.upper()}_INDEX_DUPLICATE", path, f"Scope {label} indices must be unique.") if scope.causal_plan_index is not None and not 0 <= scope.causal_plan_index < len(program.causal_plans): issues.add("CAUSAL_PLAN_INDEX_BOUNDS", path, "Causal plan index is invalid.") if not isfinite(scope.residual_tolerance) or scope.residual_tolerance <= 0.0 or scope.max_evaluations <= 0: issues.add("PRESSURE_FLOW_LIMIT_INVALID", path, "Solver limits must be positive and finite.") if scope.sparse_pattern_trusted == (scope.sparse_fallback_reason is not None): issues.add( "PRESSURE_FLOW_SPARSE_STATUS", path, "A trusted sparse pattern must have no fallback reason; an untrusted one must explain its fallback.", ) if all(0 <= item < len(pressure_flow.blocks) for item in scope.block_indices): scoped_unknowns = { item for block_index in scope.block_indices for item in pressure_flow.blocks[block_index].unknown_indices } scoped_equations = { item for block_index in scope.block_indices for item in pressure_flow.blocks[block_index].equation_indices } if scoped_unknowns != set(scope.unknown_indices): issues.add("PRESSURE_FLOW_SCOPE_UNKNOWN_COVERAGE", path, "Scope unknowns must equal its blocks' unknowns.") if scoped_equations != set(scope.equation_indices): issues.add("PRESSURE_FLOW_SCOPE_EQUATION_COVERAGE", path, "Scope equations must equal its blocks' equations.") if not pressure_flow.scopes or not 0 <= pressure_flow.global_scope_index < len(pressure_flow.scopes): issues.add("GLOBAL_SCOPE_INDEX_BOUNDS", "pressure_flow.global_scope_index", "Global scope is invalid.") else: global_scope = pressure_flow.scopes[pressure_flow.global_scope_index] if ( global_scope.kind is not ir.IRPressureFlowScopeKind.NETWORK or set(global_scope.component_indices) != set(range(len(program.components))) or set(global_scope.unknown_indices) != set(range(len(pressure_flow.unknowns))) or set(global_scope.equation_indices) != set(range(len(pressure_flow.equations))) or set(global_scope.block_indices) != set(range(len(pressure_flow.blocks))) ): issues.add("GLOBAL_SCOPE_COVERAGE", "pressure_flow.global_scope_index", "Global scope must cover the complete network.") if any(index < 0 or index >= len(pressure_flow.scopes) for index in pressure_flow.secondary_scope_indices): issues.add("SECONDARY_SCOPE_INDEX_BOUNDS", "pressure_flow.secondary_scope_indices", "Secondary scope is invalid.") if ( len(set(pressure_flow.secondary_scope_indices)) != len(pressure_flow.secondary_scope_indices) or pressure_flow.global_scope_index in pressure_flow.secondary_scope_indices ): issues.add("SECONDARY_SCOPE_INDEX_INVALID", "pressure_flow.secondary_scope_indices", "Secondary scopes must be unique and exclude the global scope.") if not isfinite(pressure_flow.pressure_lower_bound): issues.add("NONFINITE_VALUE", "pressure_flow.pressure_lower_bound", "Pressure bound must be finite.") issues.unique_ids(program.stages, "stage_id", "stages") for stage_index, stage in enumerate(program.stages): path = f"stages[{stage_index}]" reads: list[ir.IRSlotRef] = [] writes: list[ir.IRSlotRef] = [] for operation_index, operation in enumerate(stage.operations): operation_path = f"{path}.operations[{operation_index}]" for slot_index, slot in enumerate(_operation_slots(operation)): valid_slot(slot, f"{operation_path}.slots[{slot_index}]") reads.extend(ir.operation_read_slots(operation)) writes.extend(ir.operation_write_slots(operation)) if isinstance(operation, ir.IRLinearCombinationOperation): if len(operation.source_slots) != len(operation.weights) or any(not isfinite(value) for value in (*operation.weights, operation.bias)): issues.add("LINEAR_COMBINATION_INVALID", operation_path, "Weights must be finite and match sources.") if isinstance(operation, ir.IRKernelCallOperation): if len(set(operation.read_slots)) != len(operation.read_slots): issues.add("KERNEL_CALL_READ_DUPLICATE", operation_path, "Kernel read slots must be unique.") if len(set(operation.write_slots)) != len(operation.write_slots): issues.add("KERNEL_CALL_WRITE_DUPLICATE", operation_path, "Kernel write slots must be unique.") if not 0 <= operation.kernel_index < len(program.kernels): issues.add("KERNEL_INDEX_BOUNDS", operation_path, "Operation kernel index is invalid.") else: phases = {phase.phase for phase in program.kernels[operation.kernel_index].phases} if operation.phase not in phases: issues.add("KERNEL_PHASE_UNDECLARED", operation_path, "Operation uses an undeclared kernel phase.") if operation.component_index is not None and not 0 <= operation.component_index < len(program.components): issues.add("COMPONENT_INDEX_BOUNDS", operation_path, "Operation component index is invalid.") elif ( operation.component_index is not None and 0 <= operation.kernel_index < len(program.kernels) and program.components[operation.component_index].kernel_index != operation.kernel_index ): issues.add( "KERNEL_COMPONENT_MISMATCH", operation_path, "Component-bound operation must use the component's declared kernel.", ) if any(item < 0 or item >= len(pressure_flow.equations) for item in operation.equation_indices): issues.add("EQUATION_INDEX_BOUNDS", operation_path, "Operation equation index is invalid.") if len(set(operation.equation_indices)) != len(operation.equation_indices): issues.add("EQUATION_INDEX_DUPLICATE", operation_path, "Operation equation indices must be unique.") if operation.equation_indices and operation.phase is not ir.IRKernelPhase.RESIDUAL: issues.add("KERNEL_EQUATION_PHASE_INVALID", operation_path, "Equation indices are only valid for residual calls.") if ( operation.phase is ir.IRKernelPhase.RESIDUAL and all( 0 <= item < len(pressure_flow.equations) for item in operation.equation_indices ) ): required_reads = { slot for equation_index in operation.equation_indices for slot in pressure_flow.equations[ equation_index ].variable_slots } required_writes = { pressure_flow.equations[equation_index].residual_slot for equation_index in operation.equation_indices } if not required_reads.issubset(operation.read_slots): issues.add("RESIDUAL_CALL_READ_COVERAGE", operation_path, "Residual call reads must cover every referenced equation variable.") if not required_writes.issubset(operation.write_slots): issues.add("RESIDUAL_CALL_WRITE_COVERAGE", operation_path, "Residual call writes must cover every referenced equation residual.") if isinstance(operation, (ir.IREffortBroadcastOperation, ir.IRFlowAssignmentOperation)): if operation.equation_id not in {equation.equation_id for equation in pressure_flow.equations}: issues.add("EQUATION_ID_MISSING", operation_path, "Assignment references an unknown equation.") if len(set(stage.declared_read_slots)) != len(stage.declared_read_slots) or set(stage.declared_read_slots) != set(reads): issues.add("STAGE_READ_SET_MISMATCH", f"{path}.declared_read_slots", "Declared reads must equal the operation read union.") if len(set(stage.declared_write_slots)) != len(stage.declared_write_slots) or set(stage.declared_write_slots) != set(writes): issues.add("STAGE_WRITE_SET_MISMATCH", f"{path}.declared_write_slots", "Declared writes must equal the operation write union.") def valid_step(step: ir.IRStepRef, path: str) -> bool: upper = len(program.stages) if step.kind is ir.IRStepKind.STAGE else len(program.blocks) if step.index < 0 or step.index >= upper: issues.add("STEP_INDEX_BOUNDS", path, f"{step.kind.value} index is invalid.") return False return True issues.unique_ids(program.blocks, "block_id", "blocks") for block_index, block in enumerate(program.blocks): path = f"blocks[{block_index}]" for step_index, step in enumerate(block.steps): valid_step(step, f"{path}.steps[{step_index}]") iterative_kinds = {ir.IRBlockKind.FIXED_POINT, ir.IRBlockKind.STREAM_SCC} if block.kind in iterative_kinds and block.convergence is None: issues.add("FIXED_POINT_CONVERGENCE_MISSING", path, "Iterative block needs convergence settings.") if block.kind not in iterative_kinds and block.convergence is not None: issues.add("UNEXPECTED_CONVERGENCE", path, "Only iterative blocks may define convergence.") if block.convergence is not None: convergence = block.convergence if ( not isfinite(convergence.absolute_tolerance) or convergence.absolute_tolerance < 0.0 or not isfinite(convergence.relative_tolerance) or convergence.relative_tolerance < 0.0 or convergence.max_iterations <= 0 or not isfinite(convergence.relaxation) or not 0.0 < convergence.relaxation <= 1.0 ): issues.add("CONVERGENCE_LIMIT_INVALID", f"{path}.convergence", "Convergence limits are invalid.") for slot_index, slot in enumerate((*convergence.monitor_slots, *convergence.rollback_slots)): valid_slot(slot, f"{path}.convergence.slots[{slot_index}]") visit_state = [0] * len(program.blocks) def visit_block(block_index: int) -> None: if visit_state[block_index] == 1: issues.add("BLOCK_REFERENCE_CYCLE", f"blocks[{block_index}]", "Execution blocks must be acyclic.") return if visit_state[block_index] == 2: return visit_state[block_index] = 1 for step in program.blocks[block_index].steps: if step.kind is ir.IRStepKind.BLOCK and 0 <= step.index < len(program.blocks): visit_block(step.index) visit_state[block_index] = 2 for block_index in range(len(program.blocks)): visit_block(block_index) def expanded_stage_indices( steps: tuple[ir.IRStepRef, ...], ) -> tuple[int, ...]: result: list[int] = [] def append_step(step: ir.IRStepRef, active_blocks: set[int]) -> None: if step.kind is ir.IRStepKind.STAGE: if 0 <= step.index < len(program.stages): result.append(step.index) return if not 0 <= step.index < len(program.blocks) or step.index in active_blocks: return nested_active = {*active_blocks, step.index} for nested in program.blocks[step.index].steps: append_step(nested, nested_active) for step in steps: append_step(step, set()) return tuple(result) expected_entry_inputs = tuple( ir.IRSlotRef(kind, index) for kind in ( ir.IRBufferKind.TIME, ir.IRBufferKind.STATE_INPUT, ir.IRBufferKind.RUNTIME_INPUT, ) for buffer in (buffer_by_kind.get(kind),) if buffer is not None for index in range(buffer.size) ) entry_required_stage = { ir.IREntryPointKind.RHS: ir.IRStageKind.DERIVATIVE_REDUCE, ir.IREntryPointKind.EVENTS: ir.IRStageKind.EVENT, ir.IREntryPointKind.JACOBIAN: ir.IRStageKind.JACOBIAN, ir.IREntryPointKind.OUTPUTS: ir.IRStageKind.OUTPUT, } entry_forbidden_stages = { ir.IREntryPointKind.RHS: { ir.IRStageKind.EVENT, ir.IRStageKind.JACOBIAN, ir.IRStageKind.OUTPUT, ir.IRStageKind.RESET, }, ir.IREntryPointKind.EVENTS: { ir.IRStageKind.DERIVATIVE_REDUCE, ir.IRStageKind.JACOBIAN, ir.IRStageKind.OUTPUT, ir.IRStageKind.RESET, }, ir.IREntryPointKind.JACOBIAN: { ir.IRStageKind.EVENT, ir.IRStageKind.OUTPUT, ir.IRStageKind.RESET, }, ir.IREntryPointKind.OUTPUTS: { ir.IRStageKind.EVENT, ir.IRStageKind.JACOBIAN, ir.IRStageKind.RESET, }, } entry_kinds = tuple(entry.kind for entry in program.entry_points) expected_entry_kinds = set(ir.IREntryPointKind) if len(entry_kinds) != len(expected_entry_kinds) or set(entry_kinds) != expected_entry_kinds: issues.add("ENTRY_POINT_SET_INVALID", "entry_points", "Exactly rhs, events, jacobian and outputs are required.") for entry_index, entry in enumerate(program.entry_points): path = f"entry_points[{entry_index}]" for step_index, step in enumerate(entry.steps): valid_step(step, f"{path}.steps[{step_index}]") for slot_index, slot in enumerate((*entry.input_slots, *entry.output_slots)): valid_slot(slot, f"{path}.slots[{slot_index}]") output_kinds = {slot.buffer for slot in entry.output_slots} expected_output_kind = { ir.IREntryPointKind.RHS: ir.IRBufferKind.DERIVATIVE_OUTPUT, ir.IREntryPointKind.EVENTS: ir.IRBufferKind.EVENT_OUTPUT, ir.IREntryPointKind.JACOBIAN: ir.IRBufferKind.JACOBIAN_VALUE, ir.IREntryPointKind.OUTPUTS: ir.IRBufferKind.RESULT_OUTPUT, }[entry.kind] if output_kinds - {expected_output_kind}: issues.add("ENTRY_POINT_OUTPUT_BUFFER", path, f"Outputs must use {expected_output_kind.value}.") if entry.input_slots != expected_entry_inputs: issues.add( "ENTRY_POINT_INPUT_CONTRACT", f"{path}.input_slots", "Entry inputs must be ordered time, full solver state and runtime inputs.", ) expected_outputs = { ir.IREntryPointKind.RHS: tuple( ir.IRSlotRef(ir.IRBufferKind.DERIVATIVE_OUTPUT, index) for index in range(buffer_by_kind.get(ir.IRBufferKind.DERIVATIVE_OUTPUT).size) ) if buffer_by_kind.get(ir.IRBufferKind.DERIVATIVE_OUTPUT) is not None else (), ir.IREntryPointKind.EVENTS: tuple(event.root_slot for event in program.events), ir.IREntryPointKind.JACOBIAN: program.jacobian.value_slots, ir.IREntryPointKind.OUTPUTS: tuple(output.output_slot for output in program.outputs), }[entry.kind] if entry.output_slots != expected_outputs: issues.add( "ENTRY_POINT_OUTPUT_COVERAGE", f"{path}.output_slots", "Entry outputs must exactly match its ordered public result contract.", ) reachable_stage_indices = expanded_stage_indices(entry.steps) reachable_kinds = { program.stages[index].kind for index in reachable_stage_indices } if entry_required_stage[entry.kind] not in reachable_kinds: issues.add( "ENTRY_POINT_FINAL_STAGE_MISSING", f"{path}.steps", f"{entry.kind.value} must execute a {entry_required_stage[entry.kind].value} stage.", ) forbidden = reachable_kinds & entry_forbidden_stages[entry.kind] if forbidden: issues.add( "ENTRY_POINT_STAGE_FORBIDDEN", f"{path}.steps", "Entry executes incompatible stage kinds: " + ", ".join(sorted(kind.value for kind in forbidden)), ) reachable_writes = { slot for index in reachable_stage_indices for slot in program.stages[index].declared_write_slots } if not set(entry.output_slots).issubset(reachable_writes): issues.add( "ENTRY_POINT_OUTPUT_NOT_WRITTEN", f"{path}.steps", "Entry steps do not write every declared output slot.", ) forbidden_write_buffers = { ir.IRBufferKind.STATE_INPUT, ir.IRBufferKind.PARAMETER, ir.IRBufferKind.CONSTANT, ir.IRBufferKind.MODE, ir.IRBufferKind.RUNTIME_INPUT, } if any(slot.buffer in forbidden_write_buffers for slot in reachable_writes): issues.add( "ENTRY_POINT_PERSISTENT_WRITE", f"{path}.steps", "Evaluation entries may not mutate state, parameters, constants, modes or runtime inputs.", ) issues.unique_ids(program.causal_plans, "plan_id", "causal_plans") for index, plan in enumerate(program.causal_plans): path = f"causal_plans[{index}]" if plan.source_schema_version != 1: issues.add("CAUSAL_SOURCE_VERSION_INVALID", path, "Only causal IR v1 metadata is supported.") if plan.source_structural_signature is not None and ( len(plan.source_structural_signature) != 64 or any(character not in "0123456789abcdef" for character in plan.source_structural_signature) ): issues.add("CAUSAL_SIGNATURE_INVALID", path, "Source signature must be lowercase SHA-256.") if any(item < 0 or item >= len(program.components) for item in plan.scope_component_indices): issues.add("COMPONENT_INDEX_BOUNDS", path, "Causal scope component index is invalid.") for slot_index, slot in enumerate((*plan.canonical_slots, *plan.compatibility_slots, *plan.reset_slots, *plan.external_effort_slots)): valid_slot(slot, f"{path}.slots[{slot_index}]") for stage in plan.effort_stages: if stage.stage_index < 0 or stage.stage_index >= len(program.stages): issues.add("STAGE_INDEX_BOUNDS", path, "Causal effort stage index is invalid.") if any(stage < 0 or stage >= len(program.stages) for stage in plan.flow_stage_indices): issues.add("STAGE_INDEX_BOUNDS", path, "Causal flow stage index is invalid.") issues.unique_ids(program.stream_plans, "plan_id", "stream_plans") for plan_index, plan in enumerate(program.stream_plans): path = f"stream_plans[{plan_index}]" scc_ids: set[str] = set() for slot_index, slot in enumerate(plan.node_slots): valid_slot(slot, f"{path}.node_slots[{slot_index}]") partition = tuple(slot for component in plan.strongly_connected_components for slot in component.node_slots) if len(set(partition)) != len(partition) or set(partition) != set(plan.node_slots): issues.add("STREAM_SCC_PARTITION", path, "SCCs must partition stream nodes exactly once.") for scc_index, scc in enumerate(plan.strongly_connected_components): if not scc.scc_id or scc.scc_id in scc_ids: issues.add("STREAM_SCC_ID_INVALID", f"{path}.strongly_connected_components[{scc_index}]", "SCC IDs must be non-empty and unique.") scc_ids.add(scc.scc_id) if scc.block_index < 0 or scc.block_index >= len(program.blocks): issues.add("BLOCK_INDEX_BOUNDS", f"{path}.strongly_connected_components[{scc_index}]", "SCC block index is invalid.") elif program.blocks[scc.block_index].kind is not ir.IRBlockKind.STREAM_SCC: issues.add("STREAM_SCC_BLOCK_KIND", f"{path}.strongly_connected_components[{scc_index}]", "SCCs must reference stream_scc blocks.") elif ( program.blocks[scc.block_index].convergence is None or set(program.blocks[scc.block_index].convergence.monitor_slots) != set(scc.node_slots) ): issues.add("STREAM_SCC_MONITOR_COVERAGE", f"{path}.strongly_connected_components[{scc_index}]", "SCC convergence monitors must match its node slots.") scc_count = len(plan.strongly_connected_components) if tuple(sorted(plan.topological_scc_indices)) != tuple(range(scc_count)): issues.add("STREAM_TOPOLOGICAL_ORDER", path, "Topological order must cover each SCC once.") position = {scc: index for index, scc in enumerate(plan.topological_scc_indices)} for edge_index, edge in enumerate(plan.condensed_edges): if not 0 <= edge.source_scc_index < scc_count or not 0 <= edge.target_scc_index < scc_count: issues.add("STREAM_EDGE_BOUNDS", f"{path}.condensed_edges[{edge_index}]", "SCC edge is invalid.") elif position.get(edge.source_scc_index, -1) >= position.get(edge.target_scc_index, -1): issues.add("STREAM_DAG_CYCLE", f"{path}.condensed_edges[{edge_index}]", "Edge contradicts topological order.") thermofluid = program.thermofluid if not 0 <= thermofluid.stream_plan_index < len(program.stream_plans): issues.add("STREAM_PLAN_INDEX_BOUNDS", "thermofluid.stream_plan_index", "Stream plan is invalid.") for indexes, upper, label in ( (thermofluid.physical_port_indices, len(program.ports), "port"), (thermofluid.global_component_indices, len(program.components), "component"), (thermofluid.sensitive_component_indices, len(program.components), "component"), (thermofluid.secondary_pressure_scope_indices, len(pressure_flow.scopes), "scope"), ): if any(item < 0 or item >= upper for item in indexes): issues.add(f"{label.upper()}_INDEX_BOUNDS", "thermofluid", f"Thermofluid {label} index is invalid.") if len(set(indexes)) != len(indexes): issues.add(f"{label.upper()}_INDEX_DUPLICATE", "thermofluid", f"Thermofluid {label} indices must be unique.") expected_physical_ports = { index for index, port in enumerate(program.ports) if port.kind is ir.IRPortKind.PHYSICAL } if set(thermofluid.physical_port_indices) != expected_physical_ports: issues.add("THERMOFLUID_PORT_COVERAGE", "thermofluid.physical_port_indices", "Thermofluid plan must cover every physical port.") if thermofluid.secondary_pressure_scope_indices != pressure_flow.secondary_scope_indices: issues.add("THERMOFLUID_SCOPE_MISMATCH", "thermofluid.secondary_pressure_scope_indices", "Thermofluid and pressure-flow secondary scopes must match.") if not set(thermofluid.sensitive_component_indices).issubset( thermofluid.global_component_indices ): issues.add("THERMOFLUID_SENSITIVE_SCOPE", "thermofluid.sensitive_component_indices", "Sensitive components must belong to the global closure component set.") if thermofluid.maximum_iterations <= 0 or not isfinite(thermofluid.flow_relative_tolerance) or thermofluid.flow_relative_tolerance <= 0.0: issues.add("THERMOFLUID_LIMIT_INVALID", "thermofluid", "Fixed-point limits must be positive.") if thermofluid.uses_conservative_global_solver != ( thermofluid.conservative_fallback_reason is not None ): issues.add("THERMOFLUID_FALLBACK_REASON", "thermofluid", "Conservative fallback flag and reason must be declared together.") transaction = program.transaction for slot_index, slot in enumerate((*transaction.snapshot_slots, *transaction.flow_slots)): valid_slot(slot, f"transaction.slots[{slot_index}]") if len(set(transaction.snapshot_slots)) != len(transaction.snapshot_slots): issues.add("TRANSACTION_DUPLICATE_SLOT", "transaction.snapshot_slots", "Snapshot slots must be unique.") if len(set(transaction.flow_slots)) != len(transaction.flow_slots): issues.add("TRANSACTION_DUPLICATE_SLOT", "transaction.flow_slots", "Flow slots must be unique.") if not set(transaction.flow_slots).issubset(set(transaction.snapshot_slots)): issues.add("TRANSACTION_FLOW_COVERAGE", "transaction.flow_slots", "Flow slots must be part of the snapshot.") if any(item < 0 or item >= len(program.components) for item in transaction.cache_component_indices): issues.add("COMPONENT_INDEX_BOUNDS", "transaction.cache_component_indices", "Cache owner is invalid.") if len(set(transaction.cache_component_indices)) != len(transaction.cache_component_indices): issues.add("TRANSACTION_CACHE_OWNER_DUPLICATE", "transaction.cache_component_indices", "Cache owners must be unique.") if len(set(transaction.cache_attribute_ids)) != len(transaction.cache_attribute_ids): issues.add("TRANSACTION_CACHE_ID_DUPLICATE", "transaction.cache_attribute_ids", "Cache attribute IDs must be unique.") if any(not value for value in transaction.cache_attribute_ids): issues.add("TRANSACTION_CACHE_ID_INVALID", "transaction.cache_attribute_ids", "Cache attribute IDs must not be empty.") if len(set(transaction.diagnostic_owner_ids)) != len(transaction.diagnostic_owner_ids) or any( not value for value in transaction.diagnostic_owner_ids ): issues.add("TRANSACTION_DIAGNOSTIC_ID_INVALID", "transaction.diagnostic_owner_ids", "Diagnostic owner IDs must be non-empty and unique.") if "transactional_closure" in program.required_features and not ( transaction.restores_on_recoverable_failure and transaction.restores_on_fatal_failure ): issues.add("TRANSACTION_RESTORE_REQUIRED", "transaction", "Transactional closure requires rollback for every failed trial.") for block_index, block in enumerate(program.blocks): if block.convergence is not None and not set( block.convergence.rollback_slots ).issubset(transaction.snapshot_slots): issues.add("TRANSACTION_ROLLBACK_COVERAGE", f"blocks[{block_index}].convergence.rollback_slots", "Iterative rollback slots must belong to the transaction snapshot.") expected_flow_slots = { variable.slot for port in program.ports if port.kind is ir.IRPortKind.PHYSICAL and port.domain == "pneumatic" for variable in port.variables if variable.name == "m_flow" } if set(transaction.flow_slots) != expected_flow_slots: issues.add("TRANSACTION_FLOW_SEMANTICS", "transaction.flow_slots", "Transaction flow slots must exactly cover active pneumatic m_flow variables.") expected_snapshot_slots = { variable.slot for port in program.ports if port.kind is ir.IRPortKind.PHYSICAL for variable in port.variables } if set(transaction.snapshot_slots) != expected_snapshot_slots: issues.add("TRANSACTION_SNAPSHOT_COVERAGE", "transaction.snapshot_slots", "Transaction snapshots must exactly cover mutable physical port values.") issues.unique_ids(program.modes, "mode_id", "modes") mode_by_slot: dict[ir.IRSlotRef, ir.IRModeSpec] = {} for index, mode in enumerate(program.modes): path = f"modes[{index}]" valid_slot(mode.slot, f"{path}.slot") if mode.slot.buffer is not ir.IRBufferKind.MODE: issues.add("MODE_BUFFER_INVALID", f"{path}.slot", "Mode must use the mode buffer.") if mode.slot in mode_by_slot: issues.add("MODE_SLOT_DUPLICATE", f"{path}.slot", "Each mode requires a distinct slot.") mode_by_slot[mode.slot] = mode values = tuple(item.value for item in mode.values) names = tuple(item.name for item in mode.values) if any(value < -(2**31) or value > 2**31 - 1 for value in (*values, mode.initial_value)): issues.add("MODE_INT32_RANGE", path, "Mode values and initial value must fit signed int32.") if len(set(values)) != len(values) or len(set(names)) != len(names) or mode.initial_value not in values: issues.add("MODE_VALUES_INVALID", path, "Mode values/names must be unique and include the initial value.") if any(item < 0 or item >= len(program.components) for item in mode.owner_component_indices): issues.add("COMPONENT_INDEX_BOUNDS", path, "Mode owner is invalid.") if len(set(mode.owner_component_indices)) != len(mode.owner_component_indices): issues.add("MODE_OWNER_DUPLICATE", path, "Mode owners must be unique.") mode_buffer = buffer_by_kind.get(ir.IRBufferKind.MODE) if mode_buffer is not None and set(mode_by_slot) != { ir.IRSlotRef(ir.IRBufferKind.MODE, index) for index in range(mode_buffer.size) }: issues.add("MODE_SLOT_COVERAGE", "modes", "Modes must cover every mode buffer slot exactly once.") if mode_buffer is not None and mode_buffer.initial_int_values: for mode in program.modes: if ( 0 <= mode.slot.index < len(mode_buffer.initial_int_values) and mode_buffer.initial_int_values[mode.slot.index] != mode.initial_value ): issues.add("MODE_INITIAL_VALUE_MISMATCH", mode.mode_id, "Mode metadata and buffer initial value differ.") for component_index, component in enumerate(program.components): expected_mode_slots = { mode.slot for mode in program.modes if component_index in mode.owner_component_indices } if set(component.mode_slots) != expected_mode_slots: issues.add("COMPONENT_MODE_COVERAGE", f"components[{component_index}].mode_slots", "Component mode bindings must match mode ownership.") jacobian = program.jacobian _validate_csr(jacobian.pattern, "jacobian.pattern", issues) if jacobian.pattern.row_count != reducer.solver_state_count or jacobian.pattern.column_count != reducer.solver_state_count: issues.add("JACOBIAN_SHAPE", "jacobian.pattern", "Jacobian must be state_count square.") if len(jacobian.value_slots) != jacobian.pattern.nonzero_count: issues.add("JACOBIAN_VALUE_COUNT", "jacobian.value_slots", "One value slot is required per nonzero.") for slot_index, slot in enumerate(jacobian.value_slots): valid_slot(slot, f"jacobian.value_slots[{slot_index}]") if slot.buffer is not ir.IRBufferKind.JACOBIAN_VALUE: issues.add("JACOBIAN_VALUE_BUFFER", f"jacobian.value_slots[{slot_index}]", "Jacobian values need the Jacobian buffer.") jacobian_buffer = buffer_by_kind.get(ir.IRBufferKind.JACOBIAN_VALUE) expected_jacobian_slots = tuple( ir.IRSlotRef(ir.IRBufferKind.JACOBIAN_VALUE, index) for index in range(jacobian_buffer.size if jacobian_buffer is not None else 0) ) if jacobian.value_slots != expected_jacobian_slots: issues.add("JACOBIAN_VALUE_SLOT_COVERAGE", "jacobian.value_slots", "Jacobian value slots must be unique and cover their buffer in CSR order.") colors = tuple(column for group in jacobian.color_groups for column in group) if tuple(sorted(colors)) != tuple(range(reducer.solver_state_count)) or len(set(colors)) != len(colors): issues.add("JACOBIAN_COLOR_PARTITION", "jacobian.color_groups", "Colors must partition all state columns.") if ( len(jacobian.pattern.row_pointers) == jacobian.pattern.row_count + 1 and jacobian.pattern.row_pointers and jacobian.pattern.row_pointers[0] == 0 and jacobian.pattern.row_pointers[-1] == len(jacobian.pattern.column_indices) and all( first <= second for first, second in zip( jacobian.pattern.row_pointers, jacobian.pattern.row_pointers[1:], ) ) ): rows_by_column: dict[int, set[int]] = { column: set() for column in range(jacobian.pattern.column_count) } for row in range(jacobian.pattern.row_count): for column in jacobian.pattern.column_indices[ jacobian.pattern.row_pointers[row] : jacobian.pattern.row_pointers[row + 1] ]: if column in rows_by_column: rows_by_column[column].add(row) for color_index, group in enumerate(jacobian.color_groups): occupied_rows: set[int] = set() for column in group: if column not in rows_by_column: continue if occupied_rows & rows_by_column[column]: issues.add( "JACOBIAN_COLOR_CONFLICT", f"jacobian.color_groups[{color_index}]", "Columns in one color may not share a nonzero row.", ) break occupied_rows.update(rows_by_column[column]) for step_index, step in enumerate(jacobian.fill_steps): valid_step(step, f"jacobian.fill_steps[{step_index}]") jacobian_entry = next( ( entry for entry in program.entry_points if entry.kind is ir.IREntryPointKind.JACOBIAN ), None, ) if jacobian_entry is not None and jacobian.fill_steps != jacobian_entry.steps: issues.add("JACOBIAN_FILL_STEP_MISMATCH", "jacobian.fill_steps", "Jacobian fill steps must equal the public Jacobian entry plan.") analytic = set(jacobian.analytic_value_indices) if len(analytic) != len(jacobian.analytic_value_indices): issues.add("JACOBIAN_ANALYTIC_DUPLICATE", "jacobian.analytic_value_indices", "Analytic value indices must be unique.") numerical: set[int] = set() numerical_sequence: list[int] = [] seen_columns: set[int] = set() for column_index, column in enumerate(jacobian.local_finite_difference_columns): if not 0 <= column.column_index < reducer.solver_state_count or column.column_index in seen_columns: issues.add("JACOBIAN_FD_COLUMN_INVALID", f"jacobian.local_finite_difference_columns[{column_index}]", "FD column is invalid or duplicated.") seen_columns.add(column.column_index) if not isfinite(column.relative_step) or column.relative_step <= 0.0: issues.add("JACOBIAN_FD_STEP_INVALID", f"jacobian.local_finite_difference_columns[{column_index}]", "FD step must be positive.") numerical.update(column.value_indices) numerical_sequence.extend(column.value_indices) if len(set(column.value_indices)) != len(column.value_indices): issues.add("JACOBIAN_FD_VALUE_DUPLICATE", f"jacobian.local_finite_difference_columns[{column_index}]", "FD value indices within one column must be unique.") for value_index in column.value_indices: if ( 0 <= value_index < len(jacobian.pattern.column_indices) and jacobian.pattern.column_indices[value_index] != column.column_index ): issues.add("JACOBIAN_FD_COLUMN_MISMATCH", f"jacobian.local_finite_difference_columns[{column_index}]", "FD values must belong to the declared CSR column.") if len(set(numerical_sequence)) != len(numerical_sequence): issues.add("JACOBIAN_FD_VALUE_DUPLICATE", "jacobian.local_finite_difference_columns", "FD value indices may be assigned only once.") all_value_indices = set(range(jacobian.pattern.nonzero_count)) if analytic & numerical or analytic | numerical != all_value_indices: issues.add("JACOBIAN_FILL_COVERAGE", "jacobian", "Every nonzero needs exactly one analytic or local-FD strategy.") if any(index < 0 or index >= jacobian.pattern.nonzero_count for index in analytic | numerical): issues.add("JACOBIAN_VALUE_INDEX_BOUNDS", "jacobian", "Jacobian strategy references an invalid nonzero.") issues.unique_ids(program.events, "event_id", "events") event_root_slots: set[ir.IRSlotRef] = set() for index, event in enumerate(program.events): path = f"events[{index}]" valid_slot(event.root_slot, f"{path}.root_slot") if event.root_slot.buffer is not ir.IRBufferKind.EVENT_OUTPUT: issues.add("EVENT_BUFFER_INVALID", f"{path}.root_slot", "Event root must use the event buffer.") if event.root_slot in event_root_slots: issues.add("EVENT_ROOT_DUPLICATE", f"{path}.root_slot", "Each event must have a distinct root slot.") event_root_slots.add(event.root_slot) if any(item < 0 or item >= len(program.components) for item in event.owner_component_indices): issues.add("COMPONENT_INDEX_BOUNDS", path, "Event owner is invalid.") for guard_index, guard in enumerate(event.mode_guards): if any( value < -(2**31) or value > 2**31 - 1 for value in guard.allowed_values ): issues.add( "MODE_INT32_RANGE", f"{path}.mode_guards[{guard_index}]", "Mode guard values must fit signed int32.", ) if guard.mode_slot not in mode_by_slot: issues.add("EVENT_MODE_MISSING", f"{path}.mode_guards[{guard_index}]", "Guard mode is not declared.") elif not set(guard.allowed_values).issubset({value.value for value in mode_by_slot[guard.mode_slot].values}): issues.add("EVENT_MODE_VALUE_INVALID", f"{path}.mode_guards[{guard_index}]", "Guard value is not declared.") if len({guard.mode_slot for guard in event.mode_guards}) != len(event.mode_guards): issues.add("EVENT_MODE_GUARD_DUPLICATE", f"{path}.mode_guards", "An event may guard each mode only once.") for step_index, step in enumerate(event.reset_steps): valid_step(step, f"{path}.reset_steps[{step_index}]") reset_stage_indices = expanded_stage_indices(event.reset_steps) if any( program.stages[stage_index].kind is not ir.IRStageKind.RESET for stage_index in reset_stage_indices ): issues.add("EVENT_RESET_STAGE_INVALID", f"{path}.reset_steps", "Event reset plans may contain only reset stages.") if len(set(event.invalidated_caches)) != len(event.invalidated_caches): issues.add("EVENT_CACHE_DUPLICATE", f"{path}.invalidated_caches", "Invalidated caches must be unique.") event_buffer = buffer_by_kind.get(ir.IRBufferKind.EVENT_OUTPUT) expected_event_slots = { ir.IRSlotRef(ir.IRBufferKind.EVENT_OUTPUT, index) for index in range(event_buffer.size if event_buffer is not None else 0) } if event_root_slots != expected_event_slots: issues.add("EVENT_ROOT_COVERAGE", "events", "Events must cover every event output slot exactly once.") issues.unique_ids(program.outputs, "output_id", "outputs") output_slots: set[ir.IRSlotRef] = set() output_order_keys: set[tuple[int, str, str | None, int]] = set() for index, output in enumerate(program.outputs): path = f"outputs[{index}]" valid_slot(output.source_slot, f"{path}.source_slot") valid_slot(output.output_slot, f"{path}.output_slot") if output.output_slot.buffer is not ir.IRBufferKind.RESULT_OUTPUT: issues.add("OUTPUT_BUFFER_INVALID", f"{path}.output_slot", "Output must use result buffer.") if output.output_slot in output_slots: issues.add("OUTPUT_SLOT_DUPLICATE", f"{path}.output_slot", "Output slot is duplicated.") output_slots.add(output.output_slot) if not output.scope or not output.name or not output.label or not output.category or not output.quantity: issues.add("OUTPUT_METADATA_INCOMPLETE", path, "Output scope, name, label, category and quantity are required.") if output.order < 0: issues.add("OUTPUT_ORDER_INVALID", f"{path}.order", "Output order cannot be negative.") order_key = ( output.component_index, output.scope, output.port_name, output.order, ) if order_key in output_order_keys: issues.add("OUTPUT_ORDER_DUPLICATE", f"{path}.order", "Output order must be unique within one component scope/port.") output_order_keys.add(order_key) if not 0 <= output.component_index < len(program.components): issues.add("COMPONENT_INDEX_BOUNDS", path, "Output component is invalid.") if not isfinite(output.scale) or output.scale == 0.0 or not isfinite(output.offset): issues.add("OUTPUT_AFFINE_INVALID", path, "Output scale/offset must be finite and scale nonzero.") if index not in program.components[output.component_index].output_indices if 0 <= output.component_index < len(program.components) else False: issues.add("COMPONENT_OUTPUT_BACKREF", path, "Owning component does not reference this output.") result_buffer = buffer_by_kind.get(ir.IRBufferKind.RESULT_OUTPUT) expected_output_slots = { ir.IRSlotRef(ir.IRBufferKind.RESULT_OUTPUT, index) for index in range(result_buffer.size if result_buffer is not None else 0) } if output_slots != expected_output_slots: issues.add("OUTPUT_SLOT_COVERAGE", "outputs", "Outputs must cover every result buffer slot exactly once.") for component_index, component in enumerate(program.components): expected_output_indices = tuple( index for index, output in enumerate(program.outputs) if output.component_index == component_index ) if component.output_indices != expected_output_indices: issues.add("COMPONENT_OUTPUT_COVERAGE", f"components[{component_index}].output_indices", "Component outputs must exactly cover its owned outputs in program order.") capabilities = program.capabilities component_capabilities = tuple(item.component_index for item in capabilities.components) called_phases_by_component: dict[int, set[ir.IRKernelPhase]] = { index: set() for index in range(len(program.components)) } for stage in program.stages: for operation in stage.operations: if ( isinstance(operation, ir.IRKernelCallOperation) and operation.component_index is not None and 0 <= operation.component_index < len(program.components) ): called_phases_by_component[operation.component_index].add( operation.phase ) if tuple(sorted(component_capabilities)) != tuple(range(len(program.components))) or len(set(component_capabilities)) != len(component_capabilities): issues.add("CAPABILITY_COMPONENT_COVERAGE", "capabilities.components", "Capability report must cover every component once.") for index, capability in enumerate(capabilities.components): if not 0 <= capability.component_index < len(program.components): issues.add("COMPONENT_INDEX_BOUNDS", f"capabilities.components[{index}]", "Capability component is invalid.") continue kernel_index = program.components[capability.component_index].kernel_index if not 0 <= kernel_index < len(program.kernels): continue kernel = program.kernels[kernel_index] kernel_phases = {phase.phase for phase in kernel.phases} if len(set(capability.supported_phases)) != len(capability.supported_phases): issues.add("CAPABILITY_PHASE_DUPLICATE", f"capabilities.components[{index}]", "Supported phases must be unique.") if not set(capability.supported_phases).issubset(kernel_phases): issues.add("CAPABILITY_PHASE_MISMATCH", f"capabilities.components[{index}]", "Capability phases must be declared by the component kernel.") if ( capability.level is ir.IRCapabilityLevel.NATIVE and not called_phases_by_component[capability.component_index].issubset( capability.supported_phases ) ): issues.add( "CAPABILITY_NATIVE_PHASE_MISSING", f"capabilities.components[{index}].supported_phases", "A native component must support every phase used by its kernel calls.", ) if ( capability.level is ir.IRCapabilityLevel.NATIVE and kernel.availability is not ir.IRKernelAvailability.NATIVE ): issues.add("CAPABILITY_KERNEL_MISMATCH", f"capabilities.components[{index}]", "A component cannot be native while its kernel is reference-only.") if capability.level is ir.IRCapabilityLevel.NATIVE and capability.missing_features: issues.add("CAPABILITY_MISSING_FEATURE_CONFLICT", f"capabilities.components[{index}]", "Native components cannot list missing features.") if capability.level is not ir.IRCapabilityLevel.NATIVE and not capability.missing_features: issues.add("CAPABILITY_MISSING_FEATURE_REQUIRED", f"capabilities.components[{index}]", "Non-native components must identify missing features.") if len(set(capability.missing_features)) != len(capability.missing_features) or any( not value for value in capability.missing_features ): issues.add("CAPABILITY_MISSING_FEATURE_INVALID", f"capabilities.components[{index}]", "Missing feature IDs must be non-empty and unique.") issue_keys: set[tuple[str, str]] = set() for index, issue in enumerate(capabilities.issues): key = (issue.code, issue.scope_id) if not issue.code or not issue.scope_id or not issue.message: issues.add("CAPABILITY_ISSUE_INCOMPLETE", f"capabilities.issues[{index}]", "Capability issues require code, scope and message.") if key in issue_keys: issues.add("CAPABILITY_ISSUE_DUPLICATE", f"capabilities.issues[{index}]", "Capability issue code/scope pairs must be unique.") issue_keys.add(key) if any(issue.severity is ir.IRDiagnosticSeverity.ERROR for issue in capabilities.issues) and capabilities.system_level is not ir.IRCapabilityLevel.UNSUPPORTED: issues.add("CAPABILITY_LEVEL_CONFLICT", "capabilities.system_level", "Error issues require unsupported system level.") if capabilities.system_level is ir.IRCapabilityLevel.NATIVE and any( item.level is not ir.IRCapabilityLevel.NATIVE for item in capabilities.components ): issues.add("CAPABILITY_LEVEL_CONFLICT", "capabilities.system_level", "Native system contains a non-native component.") if capabilities.system_level is ir.IRCapabilityLevel.NATIVE and any( kernel.availability is not ir.IRKernelAvailability.NATIVE for kernel in program.kernels ): issues.add("CAPABILITY_LEVEL_CONFLICT", "capabilities.system_level", "Native system contains a reference-only kernel.") if ( capabilities.system_level is ir.IRCapabilityLevel.NATIVE and transaction.cache_attribute_ids ): issues.add( "CAPABILITY_LEVEL_CONFLICT", "transaction.cache_attribute_ids", "Native systems cannot depend on opaque Python cache attributes.", ) if ( capabilities.system_level is ir.IRCapabilityLevel.NATIVE and "reference_kernel_dispatch" in program.required_features ): issues.add( "CAPABILITY_LEVEL_CONFLICT", "required_features", "Native systems cannot require reference-kernel dispatch.", ) if ( capabilities.system_level is not ir.IRCapabilityLevel.UNSUPPORTED and any( item.level is ir.IRCapabilityLevel.UNSUPPORTED for item in capabilities.components ) ): issues.add( "CAPABILITY_LEVEL_CONFLICT", "capabilities.system_level", "A system containing an unsupported component must be unsupported.", ) if ( capabilities.system_level is ir.IRCapabilityLevel.UNSUPPORTED and not any( issue.severity is ir.IRDiagnosticSeverity.ERROR for issue in capabilities.issues ) ): issues.add("CAPABILITY_LEVEL_CONFLICT", "capabilities.system_level", "Unsupported systems require an error capability issue.") try: program.canonical_json_bytes() except (TypeError, ValueError) as exc: issues.add("CANONICAL_SERIALIZATION_FAILED", "$", str(exc)) return IRValidationReport(tuple(issues.items)) def require_valid_system_ir(program: ir.SystemIR) -> ir.SystemIR: """Return ``program`` or raise one error containing all static issues.""" report = validate_system_ir(program) if not report.valid: raise SystemIRValidationError(report) return program