SDL Semantics

The raes.semantics subpackage holds SDL-language semantic rules — objective-window analysis, the workflow step-type contract, branch closure, and the (pure) workflow step-result validator — used by the SDL validator, by the processor at compile time, and by the processor runtime.

Per ADR-015 these helpers live with the SDL package because raes defines the language; they depend only on the standard library and have no import-time coupling to raes_processor.

Objective Semantics

Pure objective/window semantic helpers.

class raes.semantics.objectives.ObjectiveWindowReferenceKind

Bases: str, Enum

Normalized objective-window reference kinds.

STORY = 'story'
SCRIPT = 'script'
EVENT = 'event'
WORKFLOW = 'workflow'
WORKFLOW_STEP = 'workflow_step'
__new__(value)
class raes.semantics.objectives.ObjectiveDependencyRole

Bases: str, Enum

Semantic dependency roles derived from objective/window references.

ORDERING constrains evaluation order (the dependent is computed after its inputs); REFRESH propagates change (the dependent is recomputed when an input changes). Window references carry only REFRESH; success and depends_on references (see raes.semantics.objective_semantics) carry both.

ORDERING = 'ordering'
REFRESH = 'refresh'
__new__(value)
class raes.semantics.objectives.ParsedWorkflowStepRef

Bases: object

Parsed <workflow>.<step> reference.

raw: str
workflow_name: str
step_name: str
__init__(raw, workflow_name, step_name)
Parameters:

  • raw (str)

  • workflow_name (str)

  • step_name (str)

Return type:

None

class raes.semantics.objectives.ObjectiveWindowReference

Bases: object

A normalized objective/window reference ready for later namespacing.

raw: str
canonical_name: str
reference_kind: ObjectiveWindowReferenceKind
dependency_roles: tuple[ObjectiveDependencyRole, ...] = (ObjectiveDependencyRole.REFRESH,)
workflow_name: str | None = None
step_name: str | None = None
namespace_path: tuple[str, ...] = ()
__init__(raw, canonical_name, reference_kind, dependency_roles=(ObjectiveDependencyRole.REFRESH,), workflow_name=None, step_name=None, namespace_path=())
Parameters:
Return type:

None

class raes.semantics.objectives.ObjectiveWindowIssue

Bases: object

A normalized objective-window validation problem.

code: str
ref: str
reference_kind: ObjectiveWindowReferenceKind | None = None
workflow_name: str | None = None
step_name: str | None = None
related_name: str | None = None
__init__(code, ref, reference_kind=None, workflow_name=None, step_name=None, related_name=None)
Parameters:

  • code (str)

  • ref (str)

  • reference_kind (ObjectiveWindowReferenceKind | None)

  • workflow_name (str | None)

  • step_name (str | None)

  • related_name (str | None)

Return type:

None

class raes.semantics.objectives.ObjectiveWindowAnalysis

Bases: object

Result of validating objective window references.

references: tuple[ObjectiveWindowReference, ...] = ()
issues: tuple[ObjectiveWindowIssue, ...] = ()
reachable_script_names: tuple[str, ...] = ()
reachable_event_names: tuple[str, ...] = ()
refresh_workflow_names: tuple[str, ...] = ()
references_of_kind(kind)
Parameters:

kind (ObjectiveWindowReferenceKind)

Return type:

tuple[ObjectiveWindowReference, …]

property story_names: tuple[str, ...]
property script_names: tuple[str, ...]
property event_names: tuple[str, ...]
property workflow_names: tuple[str, ...]
property workflow_step_refs: tuple[str, ...]
__init__(references=(), issues=(), reachable_script_names=(), reachable_event_names=(), refresh_workflow_names=())
Parameters:
Return type:

None

raes.semantics.objectives.parse_workflow_step_ref(step_ref)

Parse a qualified workflow name followed by one local step segment.

Parameters:

step_ref (str)

Return type:

ParsedWorkflowStepRef | None

raes.semantics.objectives.analyze_objective_window(*, story_refs, script_refs, event_refs, workflow_refs, step_refs, stories_by_name, scripts_by_name, events_by_name, workflows_by_name)

Resolve objective window references and derive shared semantics.

Parameters:

  • story_refs (list[str])

  • script_refs (list[str])

  • event_refs (list[str])

  • workflow_refs (list[str])

  • step_refs (list[str])

  • stories_by_name (Mapping[str, object])

  • scripts_by_name (Mapping[str, object])

  • events_by_name (Mapping[str, object])

  • workflows_by_name (Mapping[str, object])

Return type:

ObjectiveWindowAnalysis

raes.semantics.objectives.analyze_objective_window_step_refs(*, step_refs, workflows_by_name, referenced_workflows)

Backwards-compatible wrapper for the window-step-only subset.

Parameters:

  • step_refs (list[str])

  • workflows_by_name (Mapping[str, object])

  • referenced_workflows (set[str] | None)

Return type:

ObjectiveWindowAnalysis

Workflow Semantics

Pure workflow semantic rules shared across validation, compilation, and runtime.

class raes.semantics.workflow.WorkflowStepSemanticContract

Bases: object

Portable contract for workflow-visible step state.

step_type: str
state_observable: bool = False
observable_outcomes: tuple[str, ...] = ()
supports_attempt_counts: bool = False
fixed_attempts: int | None = None
classmethod from_mapping(payload, *, default_step_type='')
Parameters:

  • payload (Mapping[str, object] | None)

  • default_step_type (str)

Return type:

WorkflowStepSemanticContract

__init__(step_type, state_observable=False, observable_outcomes=(), supports_attempt_counts=False, fixed_attempts=None)
Parameters:

  • step_type (str)

  • state_observable (bool)

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

  • supports_attempt_counts (bool)

  • fixed_attempts (int | None)

Return type:

None

raes.semantics.workflow.workflow_step_semantic_contract(step_type)

Return the semantic contract for a workflow step type.

Parameters:

step_type (str)

Return type:

WorkflowStepSemanticContract

raes.semantics.workflow.branch_closure(graph, *, branches, join_step)

Return the owning parallel’s branch closure up to, but excluding, the join.

Parameters:

  • graph (Mapping[str, Iterable[str]])

  • branches (Iterable[str])

  • join_step (str)

Return type:

frozenset[str]

raes.semantics.workflow.validate_workflow_step_result(contract, *, lifecycle, outcome, attempts)

Return semantic violations for a workflow step execution state.

Parameters:
Return type:

tuple[str, …]