fix(durable-functions): thread entity state type through EntityContext<TState>

The v3-compat EntityContext<TState>/EntityHandler<TState> aliases accepted a
state type parameter but ignored it, so a bare context.df.getState() returned
unknown. Genuine v3 entity code (e.g. the ported BasicNode ClassBasedEntities
sample) relies on getState() returning the context's TState, so it failed to
compile against the compat package.

Make DurableEntityContext generic over TState and default the getState<T = TState>
method generic to it, so a bare getState() returns TState | undefined (matching
v3) while an explicit getState<X>() still overrides. Because TState only appears
as an erased method-generic default, DurableEntityContext<A> and <B> stay
structurally identical, so app.entity() registration still accepts specifically
typed handlers (verified: full compat unit suite green).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 6e5be22b-b727-4ccf-8668-60397bb403a0

Author: YunchuWang

packages/azure-functions-durable/CHANGELOG.md

@@ -23,7 +23,9 @@ Initial gRPC-consolidated Azure Functions Durable provider, built on `@microsoft
   `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.
+  recommended, so they are intentionally not surfaced. The classic entity context stays generic over
+  its state type (`EntityContext<TState>`), so a bare `context.df.getState()` returns `TState | undefined`
+  as in v3; the per-call `getState<T>()` generic still overrides it.
 - 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.

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

@@ -12,7 +12,7 @@ import { EntityFactory, EntityInstanceId, ITaskEntity, TaskEntityOperation } fro
  * written against the legacy `durable-functions` `context.df.*` API run unchanged on the
  * gRPC/durabletask engine.
  */
-export class DurableEntityContext {
+export class DurableEntityContext<TState = unknown> {
   private _result: unknown;
   private _resultSet = false;
   private readonly _isNewlyConstructed: boolean;
@@ -59,9 +59,13 @@ export class DurableEntityContext {
   /**
    * Gets the current entity state.
    *
+   * @remarks
+   * When the context is typed `EntityContext<TState>` (v3 style), a bare `getState()` returns
+   * `TState | undefined`. The per-call type parameter can still override this (e.g. `getState<X>()`).
+   *
    * @param initializer - Optional zero-argument callable providing the initial state when none exists.
    */
-  getState<T = unknown>(initializer?: () => T): T | undefined {
+  getState<T = TState>(initializer?: () => T): T | undefined {
     const defaultValue = typeof initializer === "function" ? initializer() : undefined;
     return this._operation.state.getState<T>(defaultValue);
   }
@@ -106,15 +110,17 @@ export class DurableEntityContext {
  * Breaking change from `durable-functions` v3, where the entity context extended `InvocationContext`.
  * This context exposes only `df`; entity code that read `InvocationContext` members must be updated.
  */
-export interface ClassicEntityContext {
-  df: DurableEntityContext;
+export interface ClassicEntityContext<TState = unknown> {
+  df: DurableEntityContext<TState>;
 }
 
 /**
  * A classic Durable Functions (v3) entity: a single-argument function that reads and mutates state
  * through `context.df.*`.
  */
-export type ClassicEntity = (context: ClassicEntityContext) => unknown | Promise<unknown>;
+export type ClassicEntity<TState = unknown> = (
+  context: ClassicEntityContext<TState>,
+) => unknown | Promise<unknown>;
 
 /**
  * Adapts an entity handler for registration on the core worker.

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

@@ -83,10 +83,10 @@ export type {
 /** v3-compat: client returned by {@link getClient}. */
 export type DurableClient = DurableFunctionsClient;
 /**
- * v3-compat: entity context. `TState` is accepted for source compatibility with the legacy generic
- * API; the underlying `df.getState<T>()`/`getInput<T>()` are per-call generic, so the type param is
- * intentionally ignored here.
+ * v3-compat: entity context. When typed `EntityContext<TState>`, a bare `context.df.getState()`
+ * returns `TState | undefined` (matching the v3 generic entity context). The per-call generics on
+ * `df.getState<T>()`/`df.getInput<T>()` still allow overriding the type at the call site.
  */
-export type EntityContext<_TState = unknown> = ClassicEntityContext;
-/** v3-compat: entity handler. `TState` accepted for source compatibility (see {@link EntityContext}). */
-export type EntityHandler<_TState = unknown> = ClassicEntity;
+export type EntityContext<TState = unknown> = ClassicEntityContext<TState>;
+/** v3-compat: entity handler. `TState` threads through to `context.df` (see {@link EntityContext}). */
+export type EntityHandler<TState = unknown> = ClassicEntity<TState>;