Support TaskFlow call syntax on stub tasks for the Lang SDK

[jason810496]

next:

• Bind TaskFlow stub-task call arguments in the Go SDK runtime #70209 — Bind TaskFlow stub-task call arguments in the Go SDK runtime (consumes arg_bindings)
• Support dynamic task mapping on stub tasks #70570 — Support dynamic task mapping on stub tasks (adds per-map-index bindings)

Scope

This PR ships the Python side only of the contract: parse-time capture of the TaskFlow call into a serialized arg-binding spec, the wire model, and its delivery to SDK runtimes through the Execution API and supervisor schema.

Nothing in this PR binds arguments inside a task runtime — the Go snippet below illustrates the consumer and lives in the stacked follow-up.

Why

@task.stub tasks can only be declared argless today, so a Go task that needs an upstream's output has to hand-write GetXCom calls (with the upstream task_id hard-coded in Go, duplicating the wiring the Dag file already expresses). This PR ships the Python side of making the natural TaskFlow call work across the language boundary:

@task.stub(queue="golang")deftransform(country: str, extracted: dict): ...
withDAG(...):
transform("uk", extract()) # extract() is a normal Python @task

// The runtime (stacked #70209) binds "uk" onto country and pulls// extract's XCom into extracted.functransform(ctx sdk.TIRunContext, log*slog.Logger, countrystring, extractedmap[string]any) error

Supported TaskFlow syntax

Every form below parses, serializes, and round-trips through the execution API (capture matrix in test_stub.py; the Dag shown is #70209's taskflow_binding_dag example):

@task.stub(queue="golang")defvia_flat_args(
name: str,
count: int,
ratio: float,
enabled: bool,
tags: list,
config: dict,
numbers: list,
note: str|None=None,
): ...
@dag(dag_id="taskflow_binding_dag")deftaskflow_binding_dag():
via_flat_args(
"summary",
3,
2.5,
True, # positional scalar literals (str/int/float/bool)
["metrics", "hourly"], # array literalconfig=make_config(), # keyword arg: XCom from another @task.stubnumbers=make_numbers(), # XCom binding onto a typed array parameter
) # `note` unpassed: its None default is captured as from_defaultregion=make_region()
via_struct_no_tags(RegionCode=region, Threshold=0.75) # one XCom fanned into several callsvia_struct_arg_tag(region_code=region, threshold=0.75) # literal + XCom mixed as kwargsvia_struct_unmatched_arg(region_code=region) # defaulted param left unpassed

• Literals of any JSON shape, positional or keyword. value_schema is the JSON-schema fragment pydantic derives from the parameter annotation (plus OpenAPI's int64/double numeric formats); annotations pydantic cannot schema, and untyped/Any parameters, omit it entirely and bind decode-only.
• XComArg return values from any upstream — a normal @task or another @task.stub — which also wires the dependency edge (transform("uk", extract()) implies extract >> transform).
• Keyword arguments normalize to declaration order through signature binding, so the serialized spec is always positional.
• Defaults left unpassed are captured with from_default: true, letting keyword-style consumers leave them unclaimed.
• Mapped stubs (.expand()) capture no spec and keep today's ignored-args behavior; per-map-index binding lands in Support dynamic task mapping on stub tasks #70570.

Rejected loudly when the Dag is serialized including:

• map/zip/concat XComArgs, a mapped upstream's aggregated output
• indexing an upstream by a custom XCom key
• upstream outputs nested inside list/dict literals
• *args/**kwargs` or context-key parameter names, and non-JSON-serializable literals (including NaN/Infinity).

How

Implement the is_stub and _arg_binding in core serialization side instead of provider side so the Execution API layer can leverage "flag-based" pattern (if task.is_stub) instead of relying on the "operator_name". So no need to bump the common.compat provider anymore (we need to bump it to provide some constants in the last implementation).

• Parse time (core): Dag serialization materializes the spec for any operator flagged is_stub, binding the TaskFlow call to the stub's signature and emitting an ordered positional spec (_arg_bindings)
• Wire model: each entry is one variant of a kind-discriminated union — XComArgBinding or LiteralArgBinding — carrying the parameter's name and its annotation-derived value_schema (a JSON schema as typing system for describing the "type" of this argument).
• Server:ti_run returns the spec as a new optional TIRunContext.arg_bindings, resolved through the shared DBDagBag only for is_stub tasks and stripped for older clients by a new execution-API version 2026-10-30.

---

Was generative AI tooling used to co-author this PR?

• Yes, with help of Claude Code (Fable 5) + (Opus 5) following the guidelines

[jason810496]

I will wait until next review then address my own comments to avoid CI-rerun.

[ashb]

Overall I like the direction. Almost all of my comments I can be challenged on, don't just make the changes if you think the current way is better/more correct

[jason810496]

Thanks you Ash for the review. I will address the comments shortly.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[jason810496]

Thanks all for the review, I just resolved all the comments and the PR is ready for the next review.

[uranusjr]

Do we need an ADR for this decisions made in this PR? Otherwise I think this is good.

[jason810496]

Do we need an ADR for this decisions made in this PR? Otherwise I think this is good.

Yes, I will add an ADR as follow-up to avoid the heavy full test CI run again.

[jason810496]

Hi @ashb, please feel free to get any suggestion for follow-up when you have a moment, thanks.