Refine PR #282 review items 1-5: arity detection, getStatus v3 parity, startNew version

- (1) orchestration-context: detect classic vs core-native orchestrators by generator/async kind (async* and async => native; sync generator => classic; plain sync => arity fallback) and drive both sync/async generators; add end-to-end regression tests through the real core executor.

- (2) createTimer already returns cancelable TimerTask (type now visible); add type/Task.any cancel test.

- (3) doc-only: classic contexts no longer extend InvocationContext (entity ctx is {df}); add replay-nondeterminism rationale to CHANGELOG/README.

- (4) createCheckStatusResponse already accepts undefined request with baseUrl fallback (v3-faithful).

- (5) getStatus returns non-optional DurableOrchestrationStatus and throws on not-found (v3 parity); showHistory populates core history; showInput maps to fetchPayloads; startNew forwards v3 version option. Docs note gRPC-path boundaries.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: YunchuWang

packages/azure-functions-durable/CHANGELOG.md

@@ -11,13 +11,20 @@ Initial gRPC-consolidated Azure Functions Durable provider, built on `@microsoft
 ### Breaking changes vs `durable-functions` v3
 
 - Classic orchestration and entity contexts no longer extend `InvocationContext`; they expose only
-  `df` plus replay-safe log helpers (no `invocationId` / `functionName` / `extraInputs`).
+  `df` plus replay-safe log helpers (no `invocationId` / `functionName` / `extraInputs`), and the
+  classic entity context exposes only `{ df }`. Rationale: reading `InvocationContext` members such as
+  `invocationId` / `extraInputs` inside an orchestrator is replay-nondeterministic and was never
+  recommended, so they are intentionally not surfaced.
 - Task result shape follows the core SDK: use `isComplete` / `isFailed` / `getResult()` (v3 used
   `isCompleted` / `isFaulted` / `result`). `context.df.createTimer(...)` returns a cancelable
   `TimerTask`, so the timeout-race pattern (`Task.any` then `timer.cancel()`) keeps working.
-- `client.getStatus()` returns `DurableOrchestrationStatus | undefined` (was non-optional) and honors
-  only `showInput`; `showHistory` / `showHistoryOutput` are ignored and `history` is not populated.
-- `client.startNew()` drops the v3 `version` option.
+- `client.getStatus()` matches the v3 signature: it returns a non-optional `DurableOrchestrationStatus`
+  and throws when the instance does not exist. `showInput`, `showHistory`, and `showHistoryOutput` are
+  accepted, with two consolidated-path caveats: `showInput` maps to the core `fetchPayloads` flag (so
+  `showInput: false` also omits output/custom status, where v3 omitted only the input), and
+  `showHistory` surfaces core `HistoryEvent`s rather than the classic .NET extension's history shape
+  (`showHistoryOutput` is accepted but does not strip payloads on the gRPC path).
+- `client.startNew()` supports the v3 `version` option (forwarded to the core scheduler).
 - Removed top-level exports: `DummyOrchestrationContext`, `DummyEntityContext`, `DurableError`,
   `AggregatedError`, `ManagedIdentityTokenSource`, `TokenSource`. `TaskFailedError` is re-exported
   from the core SDK and aggregate failures surface as JS-native `AggregateError`. For orchestration

packages/azure-functions-durable/README.md

@@ -27,12 +27,17 @@ changed. See [`CHANGELOG.md`](./CHANGELOG.md) for the full list; the highlights:
 
 - **Node.js >= 22** is required (v3 supported Node 18/20).
 - **Classic contexts no longer extend `InvocationContext`** — only `df` plus replay-safe log helpers
-  are available (no `invocationId` / `functionName` / `extraInputs`).
+  are available (no `invocationId` / `functionName` / `extraInputs`; the classic entity context is
+  just `{ df }`). Reading those `InvocationContext` members inside an orchestrator is
+  replay-nondeterministic and was never recommended.
 - **Task result shape follows the core SDK** — use `isComplete` / `isFailed` / `getResult()` instead
   of v3's `isCompleted` / `isFaulted` / `result`. `context.df.createTimer(...)` still returns a
   cancelable `TimerTask` for the timeout-race pattern.
-- **`client.getStatus()` may return `undefined`** and honors only `showInput` (`showHistory` /
-  `showHistoryOutput` are ignored); **`client.startNew()` drops the `version` option**.
+- **`client.getStatus()` keeps the v3 shape** — it returns a non-optional `DurableOrchestrationStatus`
+  and throws when the instance is missing. `showInput` / `showHistory` / `showHistoryOutput` are
+  accepted, but `showInput` also gates output/custom status and `showHistory` returns core
+  `HistoryEvent`s (not the v3 extension history shape). **`client.startNew()` supports the `version`
+  option.**
 - **Some v3 top-level exports were removed** — `DummyOrchestrationContext` / `DummyEntityContext`,
   `DurableError` / `AggregatedError`, and `ManagedIdentityTokenSource` / `TokenSource`.
   `TaskFailedError` is re-exported from the core SDK; use the core `TestOrchestrationWorker` /

packages/azure-functions-durable/src/client.ts

@@ -35,6 +35,32 @@ export interface DurableFunctionsClientConfig {
 
 export type DurableFunctionsClientInput = string | DurableFunctionsClientConfig;
 
+/**
+ * Options for {@link DurableFunctionsClient.getStatus} (classic Durable Functions v3 shape).
+ */
+export interface GetStatusOptions {
+  /** Include the execution history in {@link DurableOrchestrationStatus.history}. */
+  showHistory?: boolean;
+  /**
+   * Include input/output payloads in the history entries. Accepted for v3 compatibility; on the
+   * consolidated gRPC path the core history events always carry their payloads (see
+   * {@link DurableFunctionsClient.getStatus}).
+   */
+  showHistoryOutput?: boolean;
+  /** Include the orchestration input/output/custom-status payloads (maps to core `fetchPayloads`). */
+  showInput?: boolean;
+}
+
+/** Options for {@link DurableFunctionsClient.startNew} (classic Durable Functions v3 shape). */
+export interface StartNewOptions {
+  /** JSON-serializable input for the orchestrator. */
+  input?: unknown;
+  /** Instance ID to use; a random GUID is generated when omitted. */
+  instanceId?: string;
+  /** Orchestration version to assign (forwarded to the core scheduler). */
+  version?: string;
+}
+
 export class DurableFunctionsClient extends TaskHubGrpcClient {
   public readonly taskHubName: string;
   public readonly connectionName: string;
@@ -153,41 +179,47 @@ export class DurableFunctionsClient extends TaskHubGrpcClient {
    *
    * @deprecated Use {@link scheduleNewOrchestration} instead.
    * @param orchestratorName - The name of the orchestrator to start.
-   * @param options - Optional input and instance ID.
+   * @param options - Optional input, instance ID, and version.
    * @returns The instance ID of the started orchestration.
-   *
-   * @remarks
-   * Breaking change from v3: the v3 `version` option is not supported and is silently dropped.
    */
-  async startNew(orchestratorName: string, options?: { input?: unknown; instanceId?: string }): Promise<string> {
-    return this.scheduleNewOrchestration(
-      orchestratorName,
-      options?.input,
-      options?.instanceId !== undefined ? { instanceId: options.instanceId } : undefined,
-    );
+  async startNew(orchestratorName: string, options?: StartNewOptions): Promise<string> {
+    const scheduleOptions =
+      options?.instanceId !== undefined || options?.version !== undefined
+        ? { instanceId: options?.instanceId, version: options?.version }
+        : undefined;
+    return this.scheduleNewOrchestration(orchestratorName, options?.input, scheduleOptions);
   }
 
   /**
    * Gets the status of an orchestration instance in the classic Durable Functions (v3) shape.
    *
    * @deprecated Use {@link getOrchestrationState} instead.
    * @param instanceId - The ID of the orchestration instance to query.
-   * @param options - When `showInput` is `false`, input/output payloads are not fetched.
-   * @returns The instance status, or `undefined` if the instance does not exist.
+   * @param options - v3 {@link GetStatusOptions}: `showInput`, `showHistory`, `showHistoryOutput`.
+   * @returns The instance status.
+   * @throws If no orchestration instance with the given ID exists (matches v3, which threw on the
+   *   extension's HTTP 404 response).
    *
    * @remarks
-   * Breaking changes from v3:
-   * - The return type is `DurableOrchestrationStatus | undefined` (v3 returned a non-optional value),
-   *   so `(await getStatus(id)).runtimeStatus` must guard against `undefined`.
-   * - Only `showInput` is honored. The v3 `showHistory` / `showHistoryOutput` options are not
-   *   supported and `history` is never populated.
+   * v3 parity and its boundaries on the consolidated gRPC path:
+   * - Returns a non-optional {@link DurableOrchestrationStatus} and throws when the instance is not
+   *   found, exactly like v3's `DurableClient.getStatus`.
+   * - `showHistory` populates {@link DurableOrchestrationStatus.history} from the core execution
+   *   history (`getOrchestrationHistory`). The entries are core `HistoryEvent`s, not the classic
+   *   .NET extension's history shape (the gRPC path bypasses the extension's HTTP history formatter).
+   * - `showHistoryOutput` is accepted for API compatibility but does not strip payloads from the
+   *   history events: core history events always carry their intrinsic input/output.
+   * - `showInput` maps to the core `fetchPayloads` flag. Because that call fetches input, output, and
+   *   custom status together, `showInput: false` also omits output/custom status (v3 omitted only the
+   *   input).
    */
-  async getStatus(
-    instanceId: string,
-    options?: { showInput?: boolean },
-  ): Promise<DurableOrchestrationStatus | undefined> {
+  async getStatus(instanceId: string, options?: GetStatusOptions): Promise<DurableOrchestrationStatus> {
     const state = await this.getOrchestrationState(instanceId, options?.showInput ?? true);
-    return state ? toDurableOrchestrationStatus(state) : undefined;
+    if (state === undefined) {
+      throw new Error(`No orchestration instance with ID '${instanceId}' was found.`);
+    }
+    const history = options?.showHistory ? await this.getOrchestrationHistory(instanceId) : undefined;
+    return toDurableOrchestrationStatus(state, history);
   }
 
   /**

packages/azure-functions-durable/src/orchestration-context.ts

@@ -209,14 +209,17 @@ export type ClassicOrchestrator = (
  * orchestrators use `context.df.*` and are wrapped so the engine drives them while `context.df`
  * forwards to the core {@link OrchestrationContext}.
  *
- * Detection is by generator kind, mirroring the engine's own gate (it only drives values exposing
- * `Symbol.asyncIterator`), not by arity:
+ * Detection is by generator/async kind, mirroring the engine's own gate (it only drives values
+ * exposing `Symbol.asyncIterator`), not by arity:
  * - `async function*` (core-native, e.g. `async function*(ctx) { yield ctx.callActivity(...) }`) is
  *   passed through — wrapping it would swap in a classic `{ df, log }` context and silently break it.
+ * - `async function` (core-native non-generator, e.g. `async (ctx, input) => ...`) is passed through;
+ *   the engine awaits it. A classic v3 orchestrator is never a plain async function (it must be a
+ *   generator to `yield` durable tasks), so `async` unambiguously means core-native.
  * - `function*` (classic v3 sync generator) is wrapped; the engine cannot drive a sync generator, so
  *   the wrapper delegates to it via `yield*`.
- * - A plain (non-generator) function is ambiguous, so fall back to arity: a lone `context` parameter
- *   is treated as classic, `(ctx, input)` as core-native.
+ * - A plain SYNC (non-generator) function is ambiguous, so fall back to arity: a lone `context`
+ *   parameter is treated as classic, `(ctx, input)` as core-native.
  */
 export function wrapOrchestrator(handler: TOrchestrator | ClassicOrchestrator): TOrchestrator {
   if (typeof handler === "function" && isClassicOrchestrator(handler)) {
@@ -257,19 +260,22 @@ export function wrapOrchestrator(handler: TOrchestrator | ClassicOrchestrator):
 /**
  * @hidden
  * Classifies a handler as a classic v3 orchestrator (must be wrapped) versus a core-native one
- * (must pass through). Prefers generator kind over arity so that single-parameter core-native
- * `async function*(ctx)` orchestrators are not mis-detected as classic.
+ * (must pass through). Prefers generator/async kind over arity so that single-parameter core-native
+ * `async function*(ctx)` / `async (ctx) => ...` orchestrators are not mis-detected as classic.
  */
 function isClassicOrchestrator(handler: TOrchestrator | ClassicOrchestrator): boolean {
   const kind = (handler as { constructor?: { name?: string } }).constructor?.name;
-  if (kind === "AsyncGeneratorFunction") {
-    return false; // core-native: the engine drives it directly.
+  if (kind === "AsyncGeneratorFunction" || kind === "AsyncFunction") {
+    // Core-native: the engine drives async generators directly and awaits plain async
+    // orchestrators. A classic v3 orchestrator is never a plain async function — it must be a
+    // (sync) generator to `yield` durable tasks — so `async` unambiguously means core-native.
+    return false;
   }
   if (kind === "GeneratorFunction") {
     return true; // classic v3: a sync generator the engine can't drive on its own.
   }
-  // Plain/async (non-generator) function: fall back to arity. A lone `context` parameter is the
-  // classic v3 shape; `(ctx, input)` is core-native.
+  // Plain SYNC (non-generator) function: kind is ambiguous, so fall back to arity. A lone
+  // `context` parameter is the classic v3 shape; `(ctx, input)` is core-native.
   return handler.length <= 1;
 }
 

packages/azure-functions-durable/src/orchestration-status.ts

@@ -107,8 +107,16 @@ export function fromOrchestrationRuntimeStatus(status: OrchestrationRuntimeStatu
  *
  * Payloads are deserialized with `JSON.parse`, matching the plain-JSON wire contract the core client
  * and worker use.
+ *
+ * @param state - The core orchestration state to map.
+ * @param history - Optional execution history to attach (see {@link DurableFunctionsClient.getStatus}
+ *   `showHistory`). The entries are core {@link OrchestrationState} history events; the consolidated
+ *   gRPC path surfaces core `HistoryEvent`s rather than the classic .NET extension's history shape.
  */
-export function toDurableOrchestrationStatus(state: OrchestrationState): DurableOrchestrationStatus {
+export function toDurableOrchestrationStatus(
+  state: OrchestrationState,
+  history?: unknown[],
+): DurableOrchestrationStatus {
   return new DurableOrchestrationStatus({
     name: state.name,
     instanceId: state.instanceId,
@@ -118,6 +126,7 @@ export function toDurableOrchestrationStatus(state: OrchestrationState): Durable
     output: parseJson(state.serializedOutput),
     runtimeStatus: toOrchestrationRuntimeStatus(state.runtimeStatus),
     customStatus: parseJson(state.serializedCustomStatus),
+    history,
   });
 }
 

packages/azure-functions-durable/test/unit/client-query.spec.ts

@@ -56,11 +56,11 @@ describe("DurableFunctionsClient query methods", () => {
     }
   });
 
-  it("getStatus returns undefined when the instance does not exist", async () => {
+  it("getStatus throws when the instance does not exist (v3 not-found behavior)", async () => {
     const client = new DurableFunctionsClient(CLIENT_CONFIG);
     try {
       jest.spyOn(client, "getOrchestrationState").mockResolvedValue(undefined);
-      await expect(client.getStatus("missing")).resolves.toBeUndefined();
+      await expect(client.getStatus("missing")).rejects.toThrow(/No orchestration instance with ID 'missing'/);
     } finally {
       await client.stop();
     }
@@ -96,9 +96,7 @@ describe("DurableFunctionsClient query methods", () => {
   it("purgeInstanceHistory maps the core purge result", async () => {
     const client = new DurableFunctionsClient(CLIENT_CONFIG);
     try {
-      jest
-        .spyOn(client, "purgeOrchestration")
-        .mockResolvedValue({ deletedInstanceCount: 1 } as never);
+      jest.spyOn(client, "purgeOrchestration").mockResolvedValue({ deletedInstanceCount: 1 } as never);
 
       const result = await client.purgeInstanceHistory("abc");
       expect(result).toBeInstanceOf(PurgeHistoryResult);
@@ -193,9 +191,7 @@ describe("DurableFunctionsClient query methods", () => {
     const client = new DurableFunctionsClient(CLIENT_CONFIG);
     const request = new HttpRequest({ method: "GET", url: "http://localhost:7071/api/x" });
     try {
-      jest
-        .spyOn(client, "waitForOrchestrationCompletion")
-        .mockRejectedValue(new Error("Timed out"));
+      jest.spyOn(client, "waitForOrchestrationCompletion").mockRejectedValue(new Error("Timed out"));
 
       const response = await client.waitForCompletionOrCreateCheckStatusResponse(request, "abc", {
         timeoutInMilliseconds: 1000,