Versioning, recursive terminating/purging, Replay safe logger

[YunchuWang]

Summary

What changed?

• Added versioning support for workers and clients:
  • VersioningOptions with version, matchStrategy, failureStrategy, and defaultVersion
  • VersionMatchStrategy enum (None, Strict, CurrentOrOlder)
  • VersionFailureStrategy enum (Reject, Fail)
  • Worker-level version filtering that rejects/fails incompatible orchestrations
  • Client-level defaultVersion option for scheduling orchestrations
  • compareVersionTo(version) method on OrchestrationContext
  • compareVersions() utility for semantic version comparison
• Added ReplaySafeLogger that suppresses logs during orchestration replay
• Added recursive termination/purging support:
  • TerminateInstanceOptions with recursive flag
  • PurgeInstanceOptions with recursive flag
• Added version mismatch failure handling with proper TaskFailureDetails (ErrorType, IsNonRetriable)
• Worker now calls AbandonTaskOrchestratorWorkItem API when rejecting work items due to version mismatch

Why is this change needed?

• Enables blue-green deployments and gradual rollouts by allowing workers to filter orchestrations by version
• Aligns with .NET SDK versioning capabilities (compareVersionTo, defaultVersion)
• Provides replay-safe logging to avoid duplicate log entries during orchestration replay
• Supports recursive termination/purging of sub-orchestrations

Issues / work items

• Related Parent Orchestration Access For SubOrchestration #92 (versioning feature request)

---

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: None - all changes are additive/optional
    • Migration guidance: N/A

---

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 (Claude Opus 4.5)
• AI-assisted areas/files:
  • src/worker/versioning-options.ts - VersioningOptions interface and enums
  • src/worker/task-hub-grpc-worker.ts - Version checking logic
  • src/utils/versioning.util.ts - compareVersions utility
  • src/task/context/orchestration-context.ts - compareVersionTo method
  • src/types/replay-safe-logger.ts - ReplaySafeLogger implementation
  • src/orchestration/orchestration-purge-options.ts - PurgeInstanceOptions
  • src/orchestration/orchestration-terminate-options.ts - TerminateInstanceOptions
  • src/client/client.ts - defaultVersion support, recursive options
  • All test files
• What you changed after AI output: Reviewed and verified all implementations

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
  • Unit tests: 240 passed (durabletask-js), 64 passed (durabletask-js-azuremanaged)
  • Lint: Passed

Manual validation (only if runtime/behavior changed)

• Environment (OS, Node.js version, components): Windows, Node.js 20.x, DTS Emulator (Docker)
• Steps + observed results:
  1. Started worker with VersionMatchStrategy.Strict and version "1.0.0"
  2. Scheduled orchestration with version "1.0.0" - processed successfully
  3. Scheduled orchestration with version "2.0.0" - rejected as expected
• Evidence (optional): E2E tests in test/e2e-azuremanaged/orchestration.spec.ts

---

Notes for reviewers

• Features aligned with .NET: compareVersionTo, client defaultVersion
• New tests added: 240 unit tests total, 7 new E2E tests for versioning

[Copilot]

Pull request overview

This pull request adds three major features to the Durable Task JavaScript SDK:

Changes:

• Versioning Support: Enables orchestrations to be tagged with versions and workers to filter work items based on version matching strategies (None, Strict, CurrentOrOlder), with configurable failure strategies (Reject, Fail)
• Recursive Terminate/Purge: Adds options to terminate and purge orchestrations recursively, including all their sub-orchestrations
• Replay-Safe Logger: Implements a logger wrapper that suppresses duplicate log output during orchestration replay

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
packages/durabletask-js/src/worker/versioning-options.ts	Defines enums and interfaces for versioning configuration
packages/durabletask-js/src/orchestration/orchestration-terminate-options.ts	Defines options interface for terminating orchestrations
packages/durabletask-js/src/orchestration/orchestration-purge-options.ts	Defines options interface for purging orchestrations
packages/durabletask-js/src/types/replay-safe-logger.ts	Implements logger wrapper that only logs during non-replay execution
packages/durabletask-js/src/worker/task-hub-grpc-worker.ts	Adds version compatibility checking logic to worker
packages/durabletask-js/src/worker/runtime-orchestration-context.ts	Adds version property to runtime context
packages/durabletask-js/src/worker/orchestration-executor.ts	Extracts and sets version from execution started event
packages/durabletask-js/src/task/context/orchestration-context.ts	Adds version property, compareVersionTo method, and createReplaySafeLogger method
packages/durabletask-js/src/client/client.ts	Adds version handling for scheduling, recursive options for terminate/purge
packages/durabletask-js/src/utils/versioning.util.ts	Implements semantic version comparison utility
packages/durabletask-js/src/utils/pb-helper.util.ts	Adds version mismatch failure details helper and version parameters to actions
packages/durabletask-js/src/task/options/task-options.ts	Adds version property to TaskOptions and StartOrchestrationOptions
packages/durabletask-js/src/index.ts	Exports new versioning types and utilities
test/e2e-azuremanaged/orchestration.spec.ts	Adds E2E tests for versioning, replay-safe logger, and recursive terminate/purge
packages/durabletask-js/test/versioning.spec.ts	Unit tests for version comparison utility
packages/durabletask-js/test/worker-versioning.spec.ts	Unit tests for worker versioning options
packages/durabletask-js/test/orchestration_context_methods.spec.ts	Unit tests for new orchestration context methods
packages/durabletask-js/test/replay-safe-logger.spec.ts	Unit tests for ReplaySafeLogger
packages/durabletask-js/test/pb-helper-versioning.spec.ts	Unit tests for version mismatch failure details
packages/durabletask-js/test/versioning-options.spec.ts	Unit tests for versioning options interfaces
packages/durabletask-js/test/client-options.spec.ts	Unit tests for client options with default version

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.