Processor semantics¶
The raes_processor.semantics package helps compare compiled resources with
runtime snapshots. It builds dependency graphs, orders resources, and finds
the resource actions needed to bring runtime state in line with the plan.
SDL rules, such as objective windows, live in raes.semantics (ADR-015).
Shared workflow step types, branch closure, and step-result checks live in
raes_contracts.workflow.semantics (ADR-121). See SDL semantics for
both sets of rules.
Planner semantics¶
Pure dependency-graph semantics shared by planner and runtime lifecycle code.
- class raes_processor.semantics.planner.DependencyKind¶
Bases:
str,EnumTyped runtime dependency semantics.
- ORDERING = 'ordering'¶
- REFRESH = 'refresh'¶
- __new__(value)¶
- class raes_processor.semantics.planner.ReconciliationAction¶
Bases:
str,EnumGeneric reconciliation outcome before runtime-specific mapping.
- CREATE = 'create'¶
- UPDATE = 'update'¶
- DELETE = 'delete'¶
- UNCHANGED = 'unchanged'¶
- __new__(value)¶
- class raes_processor.semantics.planner.DependencyEdge¶
Bases:
objectNormalized dependency edge between canonical resource identities.
- source: str¶
- target: str¶
- kind: DependencyKind¶
- __init__(source, target, kind)¶
- Parameters:
source (str)
target (str)
kind (DependencyKind)
- Return type:
None
- class raes_processor.semantics.planner.SupportsDependencySemantics¶
Bases:
ProtocolDuck-typed resource shape for semantic dependency analysis.
- ordering_dependencies: Iterable[str]¶
- refresh_dependencies: Iterable[str]¶
- __init__(*args, **kwargs)¶
- raes_processor.semantics.planner.canonical_resource_identity(address)¶
Return an opaque, validated ordering key for a compiled address.
- Parameters:
address (str)
- Return type:
tuple[str, …]
- raes_processor.semantics.planner.dependency_graph(dependencies_by_node)¶
Normalize a dependency graph to only include known nodes.
- Parameters:
dependencies_by_node (Mapping[str, Iterable[str]])
- Return type:
dict[str, tuple[str, …]]
- raes_processor.semantics.planner.dependency_graph_from_edges(edges, *, known_nodes)¶
Build a normalized graph from typed dependency edges.
- Parameters:
edges (Iterable[DependencyEdge])
known_nodes (Iterable[str])
- Return type:
dict[str, tuple[str, …]]
- raes_processor.semantics.planner.dependency_edges(resources, *, kind)¶
Return normalized typed dependency edges for compiled resources.
- Parameters:
resources (Mapping[str, SupportsDependencySemantics])
kind (DependencyKind)
- Return type:
tuple[DependencyEdge, …]
- raes_processor.semantics.planner.dependency_graph_for_resources(resources, *, kind)¶
Build a normalized dependency graph from compiled resources.
- Parameters:
resources (Mapping[str, SupportsDependencySemantics])
kind (DependencyKind)
- Return type:
dict[str, tuple[str, …]]
- raes_processor.semantics.planner.dependency_cycles(dependencies_by_node)¶
Return strongly connected components that represent dependency cycles.
- Parameters:
dependencies_by_node (Mapping[str, Iterable[str]])
- Return type:
list[tuple[str, …]]
- raes_processor.semantics.planner.topological_dependency_order(dependencies_by_node)¶
Return a stable topological order, appending residual nodes on cycles.
- Parameters:
dependencies_by_node (Mapping[str, Iterable[str]])
- Return type:
list[str]
- raes_processor.semantics.planner.reverse_delete_order(dependencies_by_node)¶
Return reverse topological order for delete/teardown semantics.
- Parameters:
dependencies_by_node (Mapping[str, Iterable[str]])
- Return type:
list[str]
- raes_processor.semantics.planner.resource_topological_order(resources)¶
Return ordering-based topological order for compiled resources.
- Parameters:
resources (Mapping[str, SupportsDependencySemantics])
- Return type:
list[str]
- raes_processor.semantics.planner.resource_delete_order(resources)¶
Return ordering-based delete order for compiled resources.
- Parameters:
resources (Mapping[str, SupportsDependencySemantics])
- Return type:
list[str]
- raes_processor.semantics.planner.resource_dependency_cycles(resources)¶
Return ordering-cycle SCCs for compiled resources.
- Parameters:
resources (Mapping[str, SupportsDependencySemantics])
- Return type:
list[tuple[str, …]]
- raes_processor.semantics.planner.refresh_impacted_nodes(resources, changed_nodes)¶
Return nodes that must refresh because dependencies changed.
- Parameters:
resources (Mapping[str, SupportsDependencySemantics])
changed_nodes (Iterable[str])
- Return type:
tuple[str, …]
- raes_processor.semantics.planner.reconcile_resource_actions(resources, snapshot_entries, *, resource_dependencies, matches)¶
Compute create/update/delete/unchanged actions from semantic dependencies.
- Parameters:
resources (Mapping[str, TResource])
snapshot_entries (Mapping[str, TSnapshot])
resource_dependencies (Callable[[TResource], SupportsDependencySemantics])
matches (Callable[[TSnapshot, TResource], bool])
- Return type:
tuple[dict[str, ReconciliationAction], dict[str, TSnapshot]]