Expose orchestration clone source instance ID

[Varshitha Bachu (bachuv)]

Summary

What changed?

• Add getter-only sourceInstanceId: string | undefined to core orchestration contexts and the classic context.df facade.
• Decode the existing protobuf request property in the shared worker path and supply it before replay. Preserve strings verbatim, including empty strings; normalize null/missing values to undefined. Malformed values use existing error logging and Failed completion.
• Add transport, replay, parent-independence, and streamed-dispatch tests, plus API documentation and changelog entries.

Why is this change needed?

• Orchestrators need to identify the immediate instance from which they were restarted as a clone, independently of sub-orchestration parent identity. The protobuf properties map already supports this metadata, but the SDK did not expose it.

Issues / work items

• Resolves # N/A
• Related # Azure/azure-functions-durable-js#735, Azure/azure-functions-durable-extension#3555

---

Project checklist

• Release notes are not required for the next release
  • Otherwise: Notes added to CHANGELOG.md
• Backport is not required
  • Otherwise: Backport tracked by issue/PR #issue_or_pr
• All required tests have been added/updated (unit tests, E2E tests)
• Breaking change?
  • If yes:
    • Impact: Public context subclasses must implement the new abstract getter. Existing runtime constructor/executor calls remain compatible via optional trailing arguments.
    • Migration guidance: Custom context subclasses should expose sourceInstanceId, returning undefined when metadata is unavailable.

---

AI-assisted code disclosure (required)

Was an AI tool used? (select one)

• No
• Yes, AI helped write parts of this PR (e.g., GitHub Copilot)
• Yes, an AI agent generated most of this PR

If AI was used:

• Tool(s): GitHub Copilot
• AI-assisted areas/files: Core worker/executor/context metadata flow, Functions context adapter, regression tests, API documentation, and changelogs.
• What you changed after AI output:

AI verification (required if AI was used):

• I understand the code and can explain it
• I verified referenced APIs/types exist and are correct
• I reviewed edge cases/failure paths (timeouts, retries, cancellation, exceptions)
• I reviewed concurrency/async behavior
• I checked for unintended breaking or behavior changes

---

Testing

Automated tests

• Result: Passed. Exact commands:
  • npm run build:core - passed.
  • npm run build -w durable-functions - passed.
  • npm run build:azuremanaged - passed.
  • npm run test:unit -w @microsoft/durabletask-js -- --runTestsByPath test\orchestration_executor.spec.ts test\parent-orchestration-instance.spec.ts test\worker-response-delivery.spec.ts test\client-error-cause.spec.ts - passed, 163 tests.
  • npm run test:unit -w durable-functions -- --runTestsByPath test\unit\worker.spec.ts test\unit\orchestration-context.spec.ts test\unit\client.spec.ts - passed, 80 tests.
  • npm run test:unit -w @microsoft/durabletask-js -- --runTestsByPath test\sub-orchestration-instance-id.spec.ts - passed, 5 tests.
  • $files = git diff --name-only -- '*.ts'; & .\node_modules\.bin\eslint.cmd $files - passed on all changed TypeScript files before commit.

Manual validation (only if runtime/behavior changed)

• Environment (OS, Node.js version, components): Windows, Node.js 24.15.0, Core Tools 4.10.0, Preview bundle 4.42.0, Durable extension 3.12.5, Azurite, and DTS emulator.
• Steps + observed results:
  1. Ran classic and core-native Functions sample orchestrators through a real host and Azurite. Normal starts, new-ID clones, same-ID restarts, original input, timer replay, and child parent identity passed.
  2. Ran the equivalent streamed worker sample against DTS. The same behavior checks passed.
  3. Captured 55 Functions and 15 DTS protobuf work items. None supplied source metadata; contexts correctly returned undefined. Positive end-to-end lineage remains blocked on backend emission, not claimed as validated.

---

Notes for reviewers

• This consumes authoritative metadata only; it does not infer lineage from parent identity, input, or tags. Functions lineage requires extension support and provider tag persistence. Tested extension/emulator versions did not emit it.
• Restart APIs, default false, returned IDs, original-input behavior, protobuf definitions, and generated protocol files are unchanged. Explicit destination-ID/version options remain unsupported backend/protocol gaps.

[Copilot]

🟡 Changes recommended

The new abstract getter breaks existing external OrchestrationContext subclasses.

1 open finding

• Avoid abstract member breaking existing OrchestrationContext subclasses · New

What changed in this PR

Exposes clone-source lineage in core and classic orchestration contexts, preparing the SDK for related backend and Durable Functions support.

Changes:

• Decodes and propagates sourceInstanceId through worker execution and replay.
• Exposes read-only core and classic context getters.
• Adds documentation, changelogs, and regression coverage.

File	Description
CHANGELOG.md	Documents the core API.
packages/​durabletask-js/​src/​client/​client.ts	Clarifies restart lineage behavior.
packages/​durabletask-js/​src/​task/​context/​orchestration-context.ts	Adds the public core getter.
packages/​durabletask-js/​src/​worker/​orchestration-executor.ts	Passes lineage into runtime context.
packages/​durabletask-js/​src/​worker/​runtime-orchestration-context.ts	Stores and exposes lineage.
packages/​durabletask-js/​src/​worker/​task-hub-grpc-worker.ts	Decodes request metadata.
packages/​durabletask-js/​test/​orchestration_executor.spec.ts	Tests execution and replay.
packages/​durabletask-js/​test/​worker-response-delivery.spec.ts	Tests streamed dispatch.
packages/​azure-functions-durable/​CHANGELOG.md	Documents the classic API.
packages/​azure-functions-durable/​src/​orchestration-context.ts	Adds the classic facade getter.
packages/​azure-functions-durable/​test/​unit/​orchestration-context.spec.ts	Tests facade forwarding.
packages/​azure-functions-durable/​test/​unit/​worker.spec.ts	Tests protobuf handling and failures.

🧠 Review effort: Balanced

---

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