[pierrejeambrun]

A bundle whose native Dags live in more than one file only carried its
entrypoint's source in the airflowSource region. Airflow's Code tab
would show the entrypoint for every Dag: the file for the ones declared
there, and something unrelated for the ones declared in imported
modules. Multi-Dag bundles were effectively single-source in the UI.

What changes

• Each Dag's source file is embedded, one per unique path. The
  bundle header's single source region becomes sources: [{path, start, end, sha256}]. Each region has its own /*# airflowSource:<path> … #*/ block comment so the path is visible in the raw bundle too.
• Metadata gains dag_source_paths: Record<dag_id, path> so a
  reader can pick the right source per Dag without guessing.
• Dag's constructor records which file it ran in. It reads a
  cross-realm global slot (Symbol.for("airflow.ts-sdk.current-module-source"))
  that airflow-ts-pack's new onLoad plugin writes at the top of each
  author-owned source file. ES module hoisting is what makes the slot
  the current file for every top-level new Dag(...) call, so the
  constructor just reads it. Same Symbol.for pattern the SDK already uses for
  the task-scope AsyncLocalStorage.
• Files that only supply utilities or types are not embedded. Only
  the files whose new Dag(...) constructor ran end up in the per-Dag
  source regions — matches Python's dag.fileloc behavior.
• The entrypoint is always embedded, as a fallback. entrypoint_path
  is recorded in the metadata and the entry file's contents are packed as a
  source region. It is the fallback for a native TypeScript Dag with no
  attributed file of its own — one built dynamically that the packer could
  not tie to a file (the reference the single-source format gave).
• Mixed-language bundles (Python owns the Dag, TS supplies handlers)
  have an empty dag_source_paths; their only embedded source is the
  entrypoint. A source read passing no dag_id returns None (see below) —
  Python owns its Code tab, so the bundle offers no TypeScript source.

Bundle shape — before / after

Layout used for both: src/main.ts declares orders_dag inline, src/dags/reports.ts
declares reports_dag and is imported from main.ts.

Before:

//# airflowBundle={"code":{…},"metadata":{…},"source":{"start":"…","end":"…","sha256":"…"}}
//# airflowMetadata={…,"source":"main.ts","task_handlers":{"orders_dag":{…},"reports_dag":{…}}}
/*# airflowSource
…contents of src/main.ts…            ← only the entry file
#*/
<executable>

After:

//# airflowBundle={"code":{…},"metadata":{…},"sources":[
  {"path":"src/main.ts","start":"…","end":"…","sha256":"…"},
  {"path":"src/dags/reports.ts","start":"…","end":"…","sha256":"…"}
]}
//# airflowMetadata={…,"entrypoint_path":"src/main.ts",
  "dag_source_paths":{"orders_dag":"src/main.ts","reports_dag":"src/dags/reports.ts"},
  "task_handlers":{"orders_dag":{…},"reports_dag":{…}}}
/*# airflowSource:src/main.ts
…contents of src/main.ts…
#*/
/*# airflowSource:src/dags/reports.ts
…contents of src/dags/reports.ts…    ← now present, keyed by path
#*/
<executable>

Task SDK bundle reader — clean break (separate commit)

The writer above is only half of the contract. NodeCoordinator reads every
.min.mjs bundle at task-launch time — it parses the layout, verifies each
section's SHA-256, and matches the requested dag_id before spawning node
(task-sdk/…/coordinators/node/_bundle_reader.py). That reader still hard-required
the old singular source layout section, so the moment the packer switched to the
sources array every bundle was rejected with bundle layout is missing the source section and no TypeScript task could launch. This is what the ts_sdk e2e
job was failing on — the reader lives in a different distribution and did not move
with the format.

Commit cd1c307 teaches the reader only the new layout — no released bundle
uses the old shape, so it is a clean break rather than a dual-format reader:

• Parses the sources array (per-region path + byte range + digest), verifies
  each region's digest, and accepts an empty array defensively.
• Reads each /*# airflowSource:<path> … #*/ region back-to-back and checks the
  marker's path against the declared path.
• read_bundle_source(bundle_path, dag_id=None) resolves a Dag's source through
  dag_source_paths (see below for how the entrypoint and None fit in).

Entrypoint reference and per-Dag source (separate commits)

Two refinements build on the reader:

878d082 always embeds the entrypoint. The single-source format always
carried the entry file; the per-Dag format dropped it whenever the packer could not
attribute a Dag to a file. The packer now records entrypoint_path in the metadata
and packs the entry file's contents as a source region (encodeBundle rejects an
entrypoint missing from the packed sources).

f9da0fe lets the caller choose when the bundle serves a Dag's source.
read_bundle_source(bundle_path, dag_id=None):

• dag_id omitted → None. A mixed-language Dag is defined in Python, which owns
  its Code tab; the caller (which knows the Dag's Python fileloc) asks for no
  TypeScript source and gets None rather than an unrelated file.
• dag_id mapped in dag_source_paths → that Dag's own source file.
• dag_id given but not mapped (a native Dag built dynamically that the packer
  could not attribute) → the always-embedded entrypoint source, as a fallback.

So the entrypoint is a fallback only for a Dag the caller identifies as TypeScript-owned;
a Python-owned Dag never resolves to it.

Verified against a freshly packed ts-sdk/example bundle: it registers only
handlers for two Python-owned Dags (no native new Dag(...)), so
dag_source_paths is empty. It packs the entrypoint (src/main.ts) and records
entrypoint_path; read_bundle returns both dag_ids; read_bundle_source with no
dag_id returns None, and with a dag_id falls back to the entrypoint source. (The
old reader crashed on this bundle with bundle layout is missing the source section.)

Test coverage

• buildBundleManifest records paths from the module-source slot.
• Encoder: one region per file, path-tagged marker, the mixed-lang case
  (only the entrypoint region, empty dag_source_paths), and rejection of
  an entrypoint missing from the packed sources.
• Pack: multi-Dag bundle where two files declare Dags across an import
  boundary — asserts both sources are embedded and dag_source_paths
  maps each dag_id to its file; a mixed-language entry (only task
  handlers) still embeds its entrypoint source with an empty
  dag_source_paths.
• Existing shebang test still passes: the plugin's slot-write goes
  after the shebang line so #!/usr/bin/env node stays valid.
• Reader (task-sdk): reads the new sources layout and the real encoder
  fixture, resolves per-Dag source via dag_source_paths, returns None
  when no dag_id is supplied, falls back to entrypoint_path for a
  supplied-but-unmapped Dag, and rejects duplicate paths, marker/path
  mismatches, and per-region digest mismatches.

Not in scope

• A UI / Code-tab consumer of the embedded source is future work; no
  endpoint surfaces it to users yet. The reader exposes the primitives —
  per-Dag source (or None) and the entrypoint_path reference — and the
  consumer composes them with Airflow's Python-side fileloc knowledge;
  this PR does not add the UI side.

---

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

• Yes — Claude Code (Opus 4.7)

Generated-by: Claude Code (Opus 4.7) following the guidelines

[Copilot]

Copilot review overview

🟡 Changes recommended

Critical and moderate compatibility, encoding, escaping, size-limit, and module-source scoping issues remain unresolved.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 3 · 2 · 1

Open (6)

• Producer and consumer source size limits are inconsistent · New
• Unescaped source paths can terminate block-comment markers · New
• Global source-path slot breaks across suspended module evaluation · New
• Bundle contract changes without a metadata version bump · New
• Non-ASCII source paths are corrupted by ASCII header encoding · New
• Comment incorrectly claims function names determine task identity · New

What changed in this PR

Updates TypeScript bundle packaging to preserve each native Dag’s defining source file across imported modules.

Changes:

• Adds per-Dag source paths and path-tagged source regions.
• Introduces module-source tracking during Dag construction.
• Updates manifests, encoder behavior, tests, fixtures, and documentation.

File	Summary
ts-sdk/​tests/​coordinator/​runtime-manifest.test.ts	Tests source-path manifest records.
ts-sdk/​tests/​cli/​pack.test.ts	Tests multi-source packing and metadata.
ts-sdk/​tests/​cli/​fixtures/​bundle-v1.min.mjs	Updates the bundled fixture.
ts-sdk/​src/​sdk/​module-source.ts	Defines the shared module-source slot.
ts-sdk/​src/​sdk/​dag.ts	Captures Dag source paths.
ts-sdk/​src/​sdk/​bundle.ts	Exposes native Dags for manifest generation.
ts-sdk/​src/​coordinator/​manifest.ts	Adds Dag-to-source metadata.
ts-sdk/​src/​cli/​pack.ts	Tags modules and reads Dag sources; global-slot scoping and rationale require changes.
ts-sdk/​src/​cli/​bundle-encoder.ts	Encodes multiple source regions; compatibility, encoding, path escaping, and payload limits require changes.
airflow-core/​docs/​authoring-and-scheduling/​language-sdks/​typescript.rst	Documents per-Dag source embedding.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[jason810496]

Nice, thanks.

Rest of the SDKs should follow the convention of this PR introduce.

TODO items after this PR get merged:

• Add an ADR for recoding the decision of storing file content of each Dag definition with best effort and fallback to entrypoint file content if the dag_id: file_content pair is not found for the given dag_id.
• How should rest of the SDKs (Go, Java) implement this sementic?
  • Note: each SDK need to de-duplicated the file content just like the TS implementation (e.g. multiple Dag constructor definitions point to same file path, we should only store that file content once instead of multiple time in the artifact)