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, Enum

Typed runtime dependency semantics.

ORDERING = 'ordering'
REFRESH = 'refresh'
__new__(value)
class raes_processor.semantics.planner.ReconciliationAction

Bases: str, Enum

Generic reconciliation outcome before runtime-specific mapping.

CREATE = 'create'
UPDATE = 'update'
DELETE = 'delete'
UNCHANGED = 'unchanged'
__new__(value)
class raes_processor.semantics.planner.DependencyEdge

Bases: object

Normalized dependency edge between canonical resource identities.

source: str
target: str
kind: DependencyKind
__init__(source, target, kind)
Parameters:
Return type:

None

class raes_processor.semantics.planner.SupportsDependencySemantics

Bases: Protocol

Duck-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:
Return type:

dict[str, tuple[str, …]]

raes_processor.semantics.planner.dependency_edges(resources, *, kind)

Return normalized typed dependency edges for compiled resources.

Parameters:
Return type:

tuple[DependencyEdge, …]

raes_processor.semantics.planner.dependency_graph_for_resources(resources, *, kind)

Build a normalized dependency graph from compiled resources.

Parameters:
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:
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]]