feat: Defer format-string cancelation mode resolution to run time

Add CancelationMethodDeferred so a cancelation `mode` can be a
whole-field format string, resolved at run time (Template Schemas 5.3,
FEATURE_BUNDLE_1) — enabling RFC 0008 round-trip forwarding:

    cancelation:
      mode: "{{WrappedAction.Cancelation.Mode}}"
      notifyPeriodInSeconds: "{{WrappedAction.Cancelation.NotifyPeriodInSeconds}}"

The problem: format strings are normally delay-processed, but `mode`
is the schema selector — pydantic's discriminated union needs it at
parse time to know which object shape it is reading, while a forwarded
value only exists at run time. The fix replaces the literal-tag
discriminator with a callable one that routes a format-string mode to
the new deferred class, moving the TERMINATE-vs-NOTIFY_THEN_TERMINATE
decision to resolution time in the sessions runtime. See the
CancelationMethodDeferred docstring for the full explanation.

- Callable Discriminator/Tag union (CancelationMethod) used by both
  Action and SimpleAction; a mode containing "{{" routes to
  CancelationMethodDeferred.
- CancelationMethodDeferred validates that a format-string mode is
  gated on FEATURE_BUNDLE_1 and is a literal or a single whole-field
  "{{ ... }}" expression (the schema selector cannot be partially
  interpolated), and shares the notifyPeriodInSeconds validation with
  CancelationMethodNotifyThenTerminate via a hoisted helper.
- Export CancelationMethodDeferred from openjd.model.v2023_09.

Runtime resolution (null mode drops the whole cancelation object;
null period falls back to the positional schema default) lands in
openjd-sessions-for-python. Mirrors the Rust implementation in
OpenJobDescription/openjd-rs#261.

Tests: round-trip decode tests for the full forward and the
period-only forward, plus invalid tests pinning the FEATURE_BUNDLE_1
gating and the whole-field-only rule. Full suite passes (5337 tests);
all 58 WRAP_ACTIONS conformance fixtures pass end-to-end with the
sessions runtime.

Signed-off-by: David Leong <116610336+leongdl@users.noreply.github.com>

Author: leongdl

src/openjd/model/v2023_09/__init__.py

@@ -18,6 +18,7 @@
     AttributeCapabilityValue,
     AttributeRequirement,
     AttributeRequirementTemplate,
+    CancelationMethodDeferred,
     CancelationMethodNotifyThenTerminate,
     CancelationMethodTerminate,
     CancelationMode,
@@ -113,6 +114,7 @@
     "AttributeCapabilityValue",
     "AttributeRequirement",
     "AttributeRequirementTemplate",
+    "CancelationMethodDeferred",
     "CancelationMethodNotifyThenTerminate",
     "CancelationMethodTerminate",
     "CancelationMode",

src/openjd/model/v2023_09/_model.py

@@ -15,12 +15,14 @@
     field_validator,
     model_validator,
     ConfigDict,
+    Discriminator,
     StringConstraints,
     Field,
     PositiveInt,
     PositiveFloat,
     StrictBool,
     StrictInt,
+    Tag,
     ValidationError,
     ValidationInfo,
 )
@@ -283,6 +285,31 @@ class CancelationMode(str, Enum):
 NotifyPeriodType = Annotated[int, Field(ge=1, le=600)]
 
 
+def _validate_notify_period_value(
+    v: Any, info: ValidationInfo
+) -> Optional[Union[int, FormatString]]:
+    """Shared notifyPeriodInSeconds validation for
+    CancelationMethodNotifyThenTerminate and CancelationMethodDeferred."""
+    if v is None:
+        return v
+    context = cast(Optional[ModelParsingContext], info.context)
+    if isinstance(v, str):
+        if context and "FEATURE_BUNDLE_1" not in context.extensions:
+            # Try to parse as int, fail if not
+            try:
+                return int(v)
+            except ValueError:
+                raise ValueError(
+                    "notifyPeriodInSeconds as a format string requires the FEATURE_BUNDLE_1 extension."
+                )
+        return validate_int_fmtstring_field(v, ge=1, context=context)
+    if isinstance(v, int):
+        if v < 1 or v > 600:
+            raise ValueError("notifyPeriodInSeconds must be between 1 and 600")
+        return v
+    return v
+
+
 class CancelationMethodNotifyThenTerminate(OpenJDModel_v2023_09):
     """Notify-then-terminate cancelation mode for an Action.
 
@@ -323,24 +350,7 @@ class CancelationMethodNotifyThenTerminate(OpenJDModel_v2023_09):
     def _validate_notify_period(
         cls, v: Any, info: ValidationInfo
     ) -> Optional[Union[int, FormatString]]:
-        if v is None:
-            return v
-        context = cast(Optional[ModelParsingContext], info.context)
-        if isinstance(v, str):
-            if context and "FEATURE_BUNDLE_1" not in context.extensions:
-                # Try to parse as int, fail if not
-                try:
-                    return int(v)
-                except ValueError:
-                    raise ValueError(
-                        "notifyPeriodInSeconds as a format string requires the FEATURE_BUNDLE_1 extension."
-                    )
-            return validate_int_fmtstring_field(v, ge=1, context=context)
-        if isinstance(v, int):
-            if v < 1 or v > 600:
-                raise ValueError("notifyPeriodInSeconds must be between 1 and 600")
-            return v
-        return v
+        return _validate_notify_period_value(v, info)
 
 
 class CancelationMethodTerminate(OpenJDModel_v2023_09):
@@ -357,6 +367,140 @@ class CancelationMethodTerminate(OpenJDModel_v2023_09):
     mode: Literal[CancelationMode.TERMINATE]
 
 
+class CancelationMethodDeferred(OpenJDModel_v2023_09):
+    """A cancelation whose ``mode`` is a whole-field format string, resolved
+    at run time (Template Schemas 5.3, FEATURE_BUNDLE_1 extension).
+
+    What is the problem this solves?
+
+    Format strings in general are *already* delay-processed: when a template
+    says ``args: ["{{WrappedAction.Command}}"]``, the parser just stores
+    "this is a format string" and the value gets resolved much later, inside
+    a running session, right before the action launches — that's when the
+    runtime seeds the ``WrappedAction.*`` variables from the action being
+    wrapped. "Resolve later" is the normal pipeline for every other field.
+
+    ``mode`` is different because it isn't a normal value field — it's the
+    *schema selector*. The parser needs to know TERMINATE vs
+    NOTIFY_THEN_TERMINATE at parse time to decide what shape of object it's
+    even reading (only one of them allows ``notifyPeriodInSeconds``). So the
+    "which shape?" decision happens at parse time, but a forwarded value
+    like ``mode: "{{WrappedAction.Cancelation.Mode}}"`` only exists at run
+    time — that mismatch made round-trip cancelation forwarding in RFC 0008
+    wrap hooks impossible (pydantic's discriminated union rejected the
+    template with "does not match any of the expected tags").
+
+    The fix is this class: the parser accepts a whole-field ``{{...}}``
+    expression in ``mode`` as a third, "decided later" state (gated on the
+    FEATURE_BUNDLE_1 extension), and the shape decision moves to resolution
+    time, right before the action runs:
+
+    1. The runtime seeds ``WrappedAction.Cancelation.Mode`` from the
+       wrapped action (``"TERMINATE"``, ``"NOTIFY_THEN_TERMINATE"``, or
+       ``None``).
+    2. It resolves the ``mode:`` expression against that.
+    3. ``"TERMINATE"``/``"NOTIFY_THEN_TERMINATE"`` — the cancelation block
+       now acts as that method, and its sibling fields are validated
+       against that shape. ``None`` (null) — the whole ``cancelation:``
+       block is treated as never written. Anything else — the action fails.
+
+    Static validation is *not* deferred: at parse time the validator still
+    checks the expression is well-formed, that ``WrappedAction.*`` is only
+    referenced inside wrap hooks, and that the value is a single
+    whole-field expression. You just can't know *which* of the two modes
+    it'll be until the wrapped action is in front of you — which is
+    inherent to forwarding: the same wrap environment gets reused across
+    many steps whose cancelation settings differ.
+
+    Mirrors ``CancelationMode::DeferredMode`` in openjd-rs. See
+    openjd-specifications Template Schemas 5.3 and RFC 0008 "Cancelation
+    behavior".
+
+    Attributes:
+        mode (FormatString): A single whole-field interpolation expression
+            resolving to "TERMINATE", "NOTIFY_THEN_TERMINATE", or null.
+        notifyPeriodInSeconds (Optional[Union[int, FormatString]]): As on
+            CancelationMethodNotifyThenTerminate; only meaningful when the
+            mode resolves to NOTIFY_THEN_TERMINATE, and must resolve to
+            null when the mode resolves to TERMINATE.
+    """
+
+    mode: FormatString
+    notifyPeriodInSeconds: Optional[Union[NotifyPeriodType, FormatString]] = None  # noqa: N815
+
+    _job_creation_metadata = JobCreationMetadata(resolve_fields={"notifyPeriodInSeconds"})
+
+    @field_validator("mode", mode="before")
+    @classmethod
+    def _validate_mode(cls, v: Any, info: ValidationInfo) -> Any:
+        if isinstance(v, str):
+            context = cast(Optional[ModelParsingContext], info.context)
+            if context and "FEATURE_BUNDLE_1" not in context.extensions:
+                raise ValueError(
+                    "a format string in cancelation mode requires the FEATURE_BUNDLE_1 extension."
+                )
+            raw = v.strip()
+            # The mode is the schema selector, so partial interpolation
+            # like "TERMIN{{X}}" has no meaningful semantics: require a
+            # literal or a single whole-field expression. Exactly one "{{"
+            # AND exactly one "}}", anchored at both ends — counting only
+            # "{{" would accept partial interpolations like "{{X}}Y}}"
+            # (one open, two closes), which can never resolve to a valid
+            # mode.
+            if not (
+                raw.startswith("{{")
+                and raw.endswith("}}")
+                and raw.count("{{") == 1
+                and raw.count("}}") == 1
+            ):
+                raise ValueError(
+                    "cancelation mode must be a literal or a single "
+                    'whole-field "{{ ... }}" expression.'
+                )
+        return v
+
+    @field_validator("notifyPeriodInSeconds", mode="before")
+    @classmethod
+    def _validate_notify_period(
+        cls, v: Any, info: ValidationInfo
+    ) -> Optional[Union[int, FormatString]]:
+        return _validate_notify_period_value(v, info)
+
+
+def _cancelation_discriminator(v: Any) -> Optional[str]:
+    """Callable discriminator for the cancelation union: routes the two
+    literal modes to their fixed-shape classes and a format-string mode to
+    :class:`CancelationMethodDeferred` (see that class's docstring for why
+    the mode decision can be deferred at all)."""
+    mode = v.get("mode") if isinstance(v, dict) else getattr(v, "mode", None)
+    if isinstance(mode, CancelationMode):
+        mode = mode.value
+    if isinstance(mode, str):
+        if mode == CancelationMode.NOTIFY_THEN_TERMINATE.value:
+            return "notify_then_terminate"
+        if mode == CancelationMode.TERMINATE.value:
+            return "terminate"
+        if "{{" in mode:
+            return "deferred"
+    if isinstance(v, CancelationMethodNotifyThenTerminate):
+        return "notify_then_terminate"
+    if isinstance(v, CancelationMethodTerminate):
+        return "terminate"
+    if isinstance(v, CancelationMethodDeferred):
+        return "deferred"
+    return None
+
+
+CancelationMethod = Annotated[
+    Union[
+        Annotated[CancelationMethodNotifyThenTerminate, Tag("notify_then_terminate")],
+        Annotated[CancelationMethodTerminate, Tag("terminate")],
+        Annotated[CancelationMethodDeferred, Tag("deferred")],
+    ],
+    Discriminator(_cancelation_discriminator),
+]
+
+
 ArgListType = Annotated[list[ArgString], Field(min_length=1)]
 
 # WRAP_ACTIONS (RFC 0008) wrap-hook field names on EnvironmentActions.
@@ -436,17 +580,18 @@ class Action(OpenJDModel_v2023_09):
         timeout (Optional[int]): Maximum allowed runtime of the Action in seconds.
             Can be a format string with FEATURE_BUNDLE_1 extension.
             Default: No timeout
-        cancelation (Optional[Union[CancelationMethodNotifyThenTerminate, CancelationMethodTerminate]]):
-            If defined, provides details regarding how this action should be canceled.
+        cancelation (Optional[CancelationMethod]): If defined, provides details
+            regarding how this action should be canceled. One of
+            CancelationMethodNotifyThenTerminate, CancelationMethodTerminate, or
+            CancelationMethodDeferred (a whole-field format-string mode resolved
+            at run time; FEATURE_BUNDLE_1).
             Default: CancelationMethodTerminate
     """
 
     command: CommandString
     args: Optional[ArgListType] = None
     timeout: Optional[Union[PositiveInt, FormatString]] = None
-    cancelation: Optional[
-        Union[CancelationMethodNotifyThenTerminate, CancelationMethodTerminate]
-    ] = Field(None, discriminator="mode")
+    cancelation: Optional[CancelationMethod] = None
 
     _job_creation_metadata = JobCreationMetadata(resolve_fields={"timeout"})
 
@@ -786,9 +931,7 @@ class SimpleAction(OpenJDModel_v2023_09):
     script: DataString
     args: Optional[ArgListType] = None
     timeout: Optional[Union[PositiveInt, FormatString]] = None
-    cancelation: Optional[
-        Union[CancelationMethodNotifyThenTerminate, CancelationMethodTerminate]
-    ] = Field(None, discriminator="mode")
+    cancelation: Optional[CancelationMethod] = None
     let: Optional[list[str]] = None
 
     # SimpleAction is syntax sugar that resolves to a StepScript (TASK scope),

test/openjd/model_v0/v2023_09/test_wrap_actions.py

@@ -294,3 +294,109 @@ def test_create_job_with_step_env_wrap_succeeds(self):
         job = create_job(job_template=jt, job_parameter_values={})
         step_env_actions = job.steps[0].stepEnvironments[0].script.actions
         assert step_env_actions.onWrapTaskRun is not None
+
+
+class TestCancelationRoundTripForwarding:
+    """Cancelation round-trip forwarding (openjd-rs PR #261 review,
+    discussion r3597453516). A wrap hook must be able to forward the
+    wrapped action's cancelation verbatim via whole-field expressions::
+
+        cancelation:
+          mode: "{{WrappedAction.Cancelation.Mode}}"
+          notifyPeriodInSeconds: "{{WrappedAction.Cancelation.NotifyPeriodInSeconds}}"
+
+    Under RFC 0005 type-forwarding, a single outer ``{{...}}`` forwards
+    the expression's type into the field: a string mode behaves like the
+    literal, and a null result means the field is omitted (a null mode
+    drops the whole cancelation object; a null period falls back to the
+    schema default).
+
+    Mirrors ``cancelation_round_trip_*`` in openjd-rs
+    ``crates/openjd-model/tests/integration/test_wrap_actions.rs``.
+
+    Note: the review example also forwards ``timeout:``; that is
+    deliberately out of scope pending the WrappedAction.Timeout
+    int-vs-int? question (the 0-when-unset sentinel is not a valid
+    ``<posinteger>``).
+    """
+
+    _ROUND_TRIP_EXTS = ["WRAP_ACTIONS", "EXPR", "FEATURE_BUNDLE_1"]
+
+    def _wrap_actions(self, cancelation: dict) -> dict:
+        actions = {
+            "onWrapEnvEnter": _cmd("{{WrappedAction.Command}}"),
+            "onWrapTaskRun": {
+                "command": "echo",
+                "args": ["{{WrappedAction.Command}}"],
+                "cancelation": cancelation,
+            },
+            "onWrapEnvExit": _cmd("{{WrappedAction.Command}}"),
+        }
+        return actions
+
+    def test_full_cancelation_forwarding_accepted(self):
+        # Mark's example from the PR #261 review thread (minus timeout):
+        # the whole-field expressions in the wrap hook's cancelation
+        # block must parse and validate.
+        tmpl = _env_template(
+            self._wrap_actions(
+                {
+                    "mode": "{{WrappedAction.Cancelation.Mode}}",
+                    "notifyPeriodInSeconds": (
+                        "{{WrappedAction.Cancelation.NotifyPeriodInSeconds}}"
+                    ),
+                }
+            ),
+            extensions=self._ROUND_TRIP_EXTS,
+        )
+        _decode(tmpl, extensions=self._ROUND_TRIP_EXTS)
+
+    def test_notify_period_only_forwarding_accepted(self):
+        # The narrower forward: a literal mode with only the notify
+        # period forwarded. notifyPeriodInSeconds is already @fmtstring
+        # under FEATURE_BUNDLE_1; the whole-field expression is int? and
+        # a null result must drop the field (schema default applies).
+        tmpl = _env_template(
+            self._wrap_actions(
+                {
+                    "mode": "NOTIFY_THEN_TERMINATE",
+                    "notifyPeriodInSeconds": (
+                        "{{WrappedAction.Cancelation.NotifyPeriodInSeconds}}"
+                    ),
+                }
+            ),
+            extensions=self._ROUND_TRIP_EXTS,
+        )
+        _decode(tmpl, extensions=self._ROUND_TRIP_EXTS)
+
+    def test_fmtstring_mode_requires_feature_bundle_1(self):
+        # The format-string mode form is gated on FEATURE_BUNDLE_1
+        # (Template Schemas 5.3); with only WRAP_ACTIONS + EXPR it must
+        # be rejected.
+        tmpl = _env_template(
+            self._wrap_actions({"mode": "{{WrappedAction.Cancelation.Mode}}"}),
+            extensions=["WRAP_ACTIONS", "EXPR"],
+        )
+        with pytest.raises(DecodeValidationError, match="FEATURE_BUNDLE_1"):
+            _decode(tmpl, extensions=["WRAP_ACTIONS", "EXPR"])
+
+    @pytest.mark.parametrize(
+        "mode",
+        [
+            pytest.param("TERMIN{{WrappedAction.Cancelation.Mode}}", id="leading-text"),
+            # Starts with "{{", ends with "}}", exactly one "{{" — but it is
+            # the expression followed by literal text "Y}}"; the guard must
+            # count closing braces too.
+            pytest.param("{{WrappedAction.Cancelation.Mode}}Y}}", id="trailing-text"),
+        ],
+    )
+    def test_partial_fmtstring_mode_rejected(self, mode: str):
+        # The mode must be a literal or a single whole-field expression;
+        # partial interpolation has no meaningful semantics for a schema
+        # selector.
+        tmpl = _env_template(
+            self._wrap_actions({"mode": mode}),
+            extensions=self._ROUND_TRIP_EXTS,
+        )
+        with pytest.raises(DecodeValidationError, match="whole-field"):
+            _decode(tmpl, extensions=self._ROUND_TRIP_EXTS)