@@ -28,11 +28,15 @@ Proposed. Revised after the review on #72047.
28281 . ** ` dag.task(handler) ` returns a factory, and the task id is optional.** With no id the task takes
2929 the handler's function name (` dag.task(extract) ` → task ` "extract" ` ); ` dag.task(taskId, handler) `
3030 sets it explicitly, which an anonymous handler must do. Calling the factory both places the task in
31- the Dag and supplies its arguments by name — the shape Python TaskFlow uses for
31+ the Dag and supplies its arguments, in the order the handler declares them
32+ (` load(transform(extract(), "us")) ` ). A handler that declares a single object of named arguments can
33+ also be called with that object — the shape Python TaskFlow uses for
3234 ` load(transformed=transform(...)) ` .
33352 . ** The call graph is the task graph.** ` tsc ` checks every wired key against the handler's own
3436 parameter type, and a ` TaskRef ` exists only once its producing call has returned, so a cycle
35- through arguments is unrepresentable rather than rejected by a validator.
37+ through arguments is unrepresentable rather than rejected by a validator. A reference passed by
38+ position is checked against the argument's own type, which is what tells the two call shapes apart
39+ when a handler declares a single argument.
36403 . ** Every task is called exactly once.** An uncalled task fails when the Dag is read, so none can be
3741 silently left out of the graph.
38424 . ** ` before ` and ` after ` draw order-only edges** — the TypeScript pair for ` >> ` and ` << ` , both
@@ -145,21 +149,20 @@ convention.
145149 by design. Native declaration is what fills them, generated from the serialized-Dag JSON schema the
146150 way ` src/generated/supervisor.ts ` is. This ADR does not choose those fields; it fixes where an
147151 author writes them.
148- - ` TaskOptions ` collapses into ` TaskSpec ` . The shipped third argument to ` dag.task ` is
149- ` { inputs, spec } ` ; with wiring moved to the factory call, ` inputs ` is no longer an option and the
150- third argument is the spec itself .
152+ - ` TaskOptions ` carries the spec and the handler's positional argument names, which the packer fills in
153+ from the parameter list so the Dag names each argument as its handler does. With wiring moved to the
154+ factory call, ` inputs ` is no longer an option .
151155- ` TaskHandlerArgs ` is removed from the public API, ` DagRegistry ` becomes ` Bundle ` , and
152156 ` serveDags(registry) ` becomes ` bundle.serve() ` , which breaks
153157 0.1.0-beta1 authors; see [ ADR-0001] ( 0001-mixed-lang-dag-interface.md ) for the shipped call sites
154158 that change.
155159
156160## Alternatives
157161
158- - ** Positional wiring** (` load(transform(extract())) ` ), which becomes expressible once data no longer
159- shares an object with ` ctx ` /` client ` , since a handler can then take its arguments positionally and
160- ` Parameters<typeof handler> ` is a real tuple. Rejected: it removes the key names from every call
161- site, and those names are what keeps flat, one-statement-per-task wiring readable at twenty tasks.
162- A handler may still take several positional arguments; only the * wiring* stays named.
162+ - ** Named-only wiring** , rejected in the review on #73435 : naming every input reads well at twenty
163+ tasks but forces an object around a single argument, and positional calls are what TypeScript
164+ authors write. Both are offered, and the handler's own parameter list decides which one a task can
165+ use.
163166- ** Injected ` ctx ` /` client ` arguments** , mimicking the Python signature. Rejected, per the above and
164167 because feeling native to TypeScript matters more than matching Python's parameter list.
165168
@@ -175,9 +178,12 @@ convention.
175178 the same object, which forced every typed handler to declare ` TArgs & TaskHandlerArgs ` and left the
176179 top-level argument namespace open to collisions with an author's own parameter names. Getters close
177180 both.
178- - ** The spec argument already has its slot.** ` dag.task(taskId, handler, options) ` reads
179- ` { inputs = {}, spec = {} } ` and runs ` validateEmptySpec ` on the spec today
180- (` ts-sdk/src/sdk/dag.ts ` ), so task fields land on a path that exists rather than a new one.
181+ - ** The spec argument already has its slot.** ` dag.task(taskId, handler, options) ` reads ` { spec = {} } `
182+ and runs ` validateEmptySpec ` on it (` ts-sdk/src/sdk/dag.ts ` ), so task fields land on a path that
183+ exists rather than a new one.
184+ - ** A positional argument binds by order, and its name is a label.** The serialized Dag names each
185+ argument, so the packer reads the names from the handler's parameter list; ` arg0 ` , ` arg1 ` and so on
186+ stand in for a name it cannot see, without changing which value reaches which argument.
181187- ** A ` TaskRef ` is inert** — a handle for wiring, not a promise. Nothing in a Dag file executes a task
182188 body.
183189- ** A defaulted task id is resolved at pack time, not read at runtime.** esbuild renames function
0 commit comments