Processor Semantics

The raes_processor.semantics subpackage holds processor-runtime reconciliation helpers — dependency-graph construction over compiled resources, topological ordering, and resource-action reconciliation between compiled resources and runtime snapshots.

Per ADR-015, the SDL-language semantic helpers (objective windows, the workflow step-type contract, branch closure, the workflow step-result validator) live under raes.semantics and are documented in SDL Semantics.

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