@volter/twin-temporal 0.1.0

package/src/temporal-engine.ts

@@ -0,0 +1,2176 @@
+// THE ENGINE — Temporal's history service, over the World's state.
+//
+// A run is a `workflow-execution` subject (its WorkflowExecutionInfo, the vendor's own shape, plus
+// `namespace` and the server's `_state` bookkeeping) whose history is the chunk list temporal-history.ts
+// keeps beside the tree. Every RPC that moves a run is one transition here: read the run, decide the
+// events it appends and the tasks it makes or retires, write the chunk and the subject. Transitions
+// are serialized in-process (one server owns a World's Temporal), and a poller or a history reader that
+// has nothing to take waits on the engine's notification, never on a sleep loop.
+//
+// Time is the World's (`worldNow()`): an event's time, a timer's fire time, an activity's deadline and
+// a retry's backoff are all read off the World clock, so a World whose operator freezes the clock
+// freezes every timer with it, and `volter-world clock advance` fires what falls due.
+//
+// The rules below are Temporal's server rules as its documentation and its API protos state them;
+// where the twin is narrower it refuses by name (a command it does not model fails the workflow task
+// with WORKFLOW_TASK_FAILED_CAUSE_FEATURE_DISABLED and says which), never answers a fabricated success.
+import { createHash } from 'node:crypto';
+import { worldNow } from '@volter/world-core';
+import { GrpcError, GrpcStatus } from './temporal-grpc.ts';
+import { TemporalStore, type HistoryEvent, type Stored } from './temporal-history.ts';
+import { matchesVisibilityQuery, parseVisibilityQuery, visibilityFields, VisibilityQueryError, type VisibilityRow } from './temporal-visibility.ts';
+
+// ---- plain-form helpers ----------------------------------------------------------------------------
+
+type Obj = Record<string, unknown>;
+type Duration = { seconds?: number; nanos?: number };
+type Timestamp = { seconds: number; nanos?: number };
+
+export const DEFAULT_NAMESPACE = 'default';
+const LONG_POLL_MS = 60_000;
+const HISTORY_LONG_POLL_MS = 20_000;
+const DEFAULT_WFT_TIMEOUT_MS = 10_000;
+const MAX_WFT_TIMEOUT_MS = 120_000;
+const DEFAULT_PAGE_SIZE = 1000;
+
+export function durationMs(value: unknown): number {
+  const d = value as Duration | undefined;
+  if (!d) return 0;
+  return Number(d.seconds ?? 0) * 1000 + Math.floor(Number(d.nanos ?? 0) / 1e6);
+}
+
+export function toDuration(ms: number): Duration | undefined {
+  if (!ms || ms <= 0) return undefined;
+  const seconds = Math.floor(ms / 1000);
+  const nanos = Math.round((ms - seconds * 1000) * 1e6);
+  return nanos ? { seconds, nanos } : { seconds };
+}
+
+export function toTimestamp(ms: number): Timestamp {
+  const seconds = Math.floor(ms / 1000);
+  const nanos = Math.round((ms - seconds * 1000) * 1e6);
+  return nanos ? { seconds, nanos } : { seconds };
+}
+
+function timestampMs(value: unknown): number | undefined {
+  const t = value as Timestamp | undefined;
+  if (!t) return undefined;
+  return Number(t.seconds ?? 0) * 1000 + Math.floor(Number(t.nanos ?? 0) / 1e6);
+}
+
+/** The World's now, in epoch milliseconds. */
+export function nowMs(): number {
+  return Date.parse(worldNow());
+}
+
+const b64 = (text: string): string => Buffer.from(text, 'utf8').toString('base64');
+const unb64 = (text: string | undefined): string => (text ? Buffer.from(text, 'base64').toString('utf8') : '');
+
+/** A payload's value, when its encoding is one this server can read (json/plain, binary/null). */
+export function payloadValue(payload: unknown): unknown {
+  const p = payload as { metadata?: Record<string, string>; data?: string } | undefined;
+  if (!p) return undefined;
+  const encoding = unb64(p.metadata?.encoding);
+  if (encoding === 'binary/null') return null;
+  if (encoding === 'json/plain') {
+    try { return JSON.parse(unb64(p.data)); } catch { return undefined; }
+  }
+  return undefined;
+}
+
+export function jsonPayload(value: unknown, extra: Record<string, string> = {}): Obj {
+  return { metadata: { encoding: b64('json/plain'), ...Object.fromEntries(Object.entries(extra).map(([k, v]) => [k, b64(v)])) }, data: b64(JSON.stringify(value)) };
+}
+
+function uuidFrom(seed: string): string {
+  const hex = createHash('sha256').update(seed).digest('hex');
+  const variant = ((parseInt(hex[16]!, 16) & 0x3) | 0x8).toString(16);
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-4${hex.slice(13, 16)}-${variant}${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+}
+
+const encodeToken = (token: Obj): string => b64(JSON.stringify(token));
+function decodeToken(token: unknown, what: string): Obj {
+  try {
+    const parsed = JSON.parse(unb64(token as string)) as Obj;
+    if (parsed && typeof parsed === 'object') return parsed;
+  } catch { /* below */ }
+  throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, `invalid ${what}`);
+}
+
+// ---- the run ---------------------------------------------------------------------------------------
+
+type RetryPolicy = { initialInterval?: Duration; backoffCoefficient?: number; maximumInterval?: Duration; maximumAttempts?: number; nonRetryableErrorTypes?: string[] };
+
+type ActivityState = {
+  scheduledEventId: number;
+  activityId: string;
+  activityType: Obj;
+  taskQueue: string;
+  input?: Obj;
+  header?: Obj;
+  priority?: Obj;
+  retryPolicy: RetryPolicy;
+  scheduleToCloseMs: number;
+  scheduleToStartMs: number;
+  startToCloseMs: number;
+  heartbeatMs: number;
+  attempt: number;
+  scheduledAt: number;
+  attemptScheduledAt: number;
+  availableAt: number;
+  startedAt?: number;
+  identity?: string;
+  requestId?: string;
+  heartbeatDetails?: Obj;
+  lastHeartbeatAt?: number;
+  lastFailure?: Obj;
+  lastAttemptCompletedAt?: number;
+  cancelRequestedEventId?: number;
+};
+
+type ChildState = {
+  initiatedEventId: number;
+  namespace: string;
+  workflowId: string;
+  workflowType: Obj;
+  parentClosePolicy: string;
+  runId?: string;
+  startedEventId?: number;
+};
+
+type WftState = {
+  scheduledEventId: number;
+  attempt: number;
+  scheduledAt: number;
+  availableAt: number;
+  startedEventId?: number;
+  startedAt?: number;
+  timeoutAt?: number;
+  identity?: string;
+};
+
+/** An event that arrived while a workflow task was in flight, appended once it closes (Temporal's
+ *  buffered events). `linkPrevious` names an attribute set to the id of the event appended before it
+ *  (an activity's close names the ActivityTaskStarted written in the same step). */
+type BufferedEvent = { eventType: string; key: string; attributes: Obj; linkPrevious?: string; wakes: boolean };
+
+type RunState = {
+  /** creation order among the World's runs: the latest run of a workflow id is its current one */
+  seq: number;
+  nextEventId: number;
+  history: string[];
+  historyBytes: number;
+  requestIds: string[];
+  /** the request id that started this run (StartWorkflowExecution / SignalWithStart), apart from signal and cancel ids */
+  startRequestIds?: string[];
+  workflowTaskTimeoutMs: number;
+  runTimeoutMs: number;
+  executionTimeoutMs: number;
+  runExpiresAt?: number;
+  executionExpiresAt?: number;
+  retryPolicy?: RetryPolicy;
+  attempt: number;
+  input?: Obj;
+  header?: Obj;
+  cronSchedule?: string;
+  firstWftAt?: number;
+  wft: WftState | null;
+  previousStartedEventId: number;
+  buffered: BufferedEvent[];
+  activities: Record<string, ActivityState>;
+  timers: Record<string, { startedEventId: number; fireAt: number }>;
+  children: Record<string, ChildState>;
+  parent?: { namespace: string; workflowId: string; runId: string; initiatedEventId: number };
+  cancelRequested: boolean;
+  closeEventId?: number;
+  newRunId?: string;
+  nextDue?: number;
+};
+
+/** A run as the engine handles it: WorkflowExecutionInfo fields at the top, `namespace`, `_state`. */
+export type Run = Obj & {
+  id: string;
+  namespace: string;
+  execution: { workflowId: string; runId: string };
+  type: { name: string };
+  status: string;
+  taskQueue: string;
+  firstRunId: string;
+  historyLength: number;
+  startTime: Timestamp;
+  executionTime?: Timestamp;
+  closeTime?: Timestamp;
+  searchAttributes?: { indexedFields?: Record<string, Obj> };
+  memo?: { fields?: Record<string, Obj> };
+  parentExecution?: { workflowId: string; runId: string };
+  rootExecution?: { workflowId: string; runId: string };
+  _state: RunState;
+};
+
+const RUNNING = 'WORKFLOW_EXECUTION_STATUS_RUNNING';
+const EXECUTION_TYPE = 'workflow-execution';
+const NAMESPACE_TYPE = 'namespace';
+
+const STATUS_NAME: Record<string, string> = {
+  WORKFLOW_EXECUTION_STATUS_RUNNING: 'Running',
+  WORKFLOW_EXECUTION_STATUS_COMPLETED: 'Completed',
+  WORKFLOW_EXECUTION_STATUS_FAILED: 'Failed',
+  WORKFLOW_EXECUTION_STATUS_CANCELED: 'Canceled',
+  WORKFLOW_EXECUTION_STATUS_TERMINATED: 'Terminated',
+  WORKFLOW_EXECUTION_STATUS_CONTINUED_AS_NEW: 'ContinuedAsNew',
+  WORKFLOW_EXECUTION_STATUS_TIMED_OUT: 'TimedOut',
+};
+
+/** Temporal's predefined search attributes (https://docs.temporal.io/search-attribute#default-search-attribute). */
+export const SYSTEM_SEARCH_ATTRIBUTES: Record<string, string> = {
+  BatcherUser: 'INDEXED_VALUE_TYPE_KEYWORD',
+  BinaryChecksums: 'INDEXED_VALUE_TYPE_KEYWORD_LIST',
+  BuildIds: 'INDEXED_VALUE_TYPE_KEYWORD_LIST',
+  CloseTime: 'INDEXED_VALUE_TYPE_DATETIME',
+  ExecutionDuration: 'INDEXED_VALUE_TYPE_INT',
+  ExecutionStatus: 'INDEXED_VALUE_TYPE_KEYWORD',
+  ExecutionTime: 'INDEXED_VALUE_TYPE_DATETIME',
+  HistoryLength: 'INDEXED_VALUE_TYPE_INT',
+  HistorySizeBytes: 'INDEXED_VALUE_TYPE_INT',
+  ParentWorkflowId: 'INDEXED_VALUE_TYPE_KEYWORD',
+  ParentRunId: 'INDEXED_VALUE_TYPE_KEYWORD',
+  RootWorkflowId: 'INDEXED_VALUE_TYPE_KEYWORD',
+  RootRunId: 'INDEXED_VALUE_TYPE_KEYWORD',
+  RunId: 'INDEXED_VALUE_TYPE_KEYWORD',
+  StartTime: 'INDEXED_VALUE_TYPE_DATETIME',
+  StateTransitionCount: 'INDEXED_VALUE_TYPE_INT',
+  TaskQueue: 'INDEXED_VALUE_TYPE_KEYWORD',
+  TemporalChangeVersion: 'INDEXED_VALUE_TYPE_KEYWORD_LIST',
+  WorkflowId: 'INDEXED_VALUE_TYPE_KEYWORD',
+  WorkflowType: 'INDEXED_VALUE_TYPE_KEYWORD',
+};
+/** the system attributes a worker may set on its own run (the SDK's patch markers upsert this one) */
+const WORKER_SETTABLE_SYSTEM_ATTRIBUTES = new Set(['TemporalChangeVersion', 'BinaryChecksums', 'BuildIds']);
+
+/** One run's changes inside a transition: the events it appends, in order. */
+class RunTx {
+  readonly run: Run;
+  readonly events: HistoryEvent[] = [];
+  readonly now: number;
+  wakeQueues = false;
+
+  constructor(run: Run, now: number) {
+    // a deep copy: what the store lists is shared with the kernel's memory (TemporalStore.list)
+    this.run = structuredClone(run);
+    this.now = now;
+  }
+
+  get state(): RunState { return this.run._state; }
+
+  /** Append one event now; answers its id. */
+  append(eventType: string, key: string, attributes: Obj): number {
+    const eventId = this.state.nextEventId;
+    this.state.nextEventId += 1;
+    const event: HistoryEvent = { eventId, eventTime: toTimestamp(this.now), eventType, taskId: eventId, [key]: attributes };
+    this.events.push(event);
+    this.state.historyBytes += JSON.stringify(event).length;
+    this.run.historyLength = eventId;
+    return eventId;
+  }
+
+  /** Append an event a workflow task must see: buffered while a task is in flight, else appended with a
+   *  workflow task scheduled for it. */
+  deliver(eventType: string, key: string, attributes: Obj, options: { linkPrevious?: string; wakes?: boolean } = {}): void {
+    const wakes = options.wakes ?? true;
+    if (this.state.wft?.startedEventId !== undefined) {
+      this.state.buffered.push({ eventType, key, attributes, wakes, ...(options.linkPrevious ? { linkPrevious: options.linkPrevious } : {}) });
+      return;
+    }
+    this.land({ eventType, key, attributes, wakes, ...(options.linkPrevious ? { linkPrevious: options.linkPrevious } : {}) });
+    if (wakes) this.scheduleWorkflowTask();
+  }
+
+  /** Append a delivered event, resolving its link and recording what later events refer to. */
+  private land(event: BufferedEvent): number {
+    const attrs = { ...event.attributes };
+    if (event.linkPrevious) attrs[event.linkPrevious] = this.state.nextEventId - 1;
+    const eventId = this.append(event.eventType, event.key, attrs);
+    if (event.eventType === 'EVENT_TYPE_CHILD_WORKFLOW_EXECUTION_STARTED') {
+      const child = this.state.children[String(attrs.initiatedEventId)];
+      if (child) child.startedEventId = eventId;
+    }
+    return eventId;
+  }
+
+  /** Schedule a workflow task unless one is already pending. */
+  scheduleWorkflowTask(attempt = 1, delayMs = 0): void {
+    if (this.run.status !== RUNNING || this.state.wft || this.state.firstWftAt !== undefined) return;
+    const scheduledEventId = this.append('EVENT_TYPE_WORKFLOW_TASK_SCHEDULED', 'workflowTaskScheduledEventAttributes', {
+      taskQueue: { name: this.run.taskQueue, kind: 'TASK_QUEUE_KIND_NORMAL' },
+      startToCloseTimeout: toDuration(this.state.workflowTaskTimeoutMs),
+      attempt,
+    });
+    this.state.wft = { scheduledEventId, attempt, scheduledAt: this.now, availableAt: this.now + delayMs };
+    this.wakeQueues = true;
+  }
+
+  /** Append what arrived while the task was in flight; answers whether any of it needs a decision. */
+  flushBuffered(): boolean {
+    let wakes = false;
+    for (const buffered of this.state.buffered) {
+      this.land(buffered);
+      wakes ||= buffered.wakes;
+    }
+    this.state.buffered = [];
+    return wakes;
+  }
+}
+
+function freshState(): RunState {
+  return {
+    seq: 0, nextEventId: 1, history: [], historyBytes: 0, requestIds: [], workflowTaskTimeoutMs: DEFAULT_WFT_TIMEOUT_MS,
+    runTimeoutMs: 0, executionTimeoutMs: 0, attempt: 1, wft: null, previousStartedEventId: 0, buffered: [],
+    activities: {}, timers: {}, children: {}, cancelRequested: false,
+  };
+}
+
+/** The server's default activity retry policy (Temporal docs, "Default values for Retry Policy"). */
+function activityRetryPolicy(given: RetryPolicy | undefined): RetryPolicy {
+  const initial = durationMs(given?.initialInterval) || 1000;
+  return {
+    initialInterval: toDuration(initial),
+    backoffCoefficient: given?.backoffCoefficient && given.backoffCoefficient >= 1 ? given.backoffCoefficient : 2,
+    maximumInterval: toDuration(durationMs(given?.maximumInterval) || initial * 100),
+    maximumAttempts: given?.maximumAttempts ?? 0,
+    ...(given?.nonRetryableErrorTypes?.length ? { nonRetryableErrorTypes: given.nonRetryableErrorTypes } : {}),
+  };
+}
+
+type RetryDecision = { retry: true; delayMs: number } | { retry: false; state: string };
+
+/** Temporal's retry rule for a failed attempt `attempt` (1-based). */
+function decideRetry(policy: RetryPolicy | undefined, attempt: number, failure: Obj | undefined, now: number, deadline?: number): RetryDecision {
+  if (!policy) return { retry: false, state: 'RETRY_STATE_RETRY_POLICY_NOT_SET' };
+  const app = failure?.applicationFailureInfo as { nonRetryable?: boolean; type?: string; nextRetryDelay?: Duration } | undefined;
+  const timeout = failure?.timeoutFailureInfo as { timeoutType?: string } | undefined;
+  if (app?.nonRetryable) return { retry: false, state: 'RETRY_STATE_NON_RETRYABLE_FAILURE' };
+  if (app?.type && policy.nonRetryableErrorTypes?.includes(app.type)) return { retry: false, state: 'RETRY_STATE_NON_RETRYABLE_FAILURE' };
+  if (timeout && timeout.timeoutType !== 'TIMEOUT_TYPE_START_TO_CLOSE' && timeout.timeoutType !== 'TIMEOUT_TYPE_HEARTBEAT') return { retry: false, state: 'RETRY_STATE_TIMEOUT' };
+  const maximumAttempts = policy.maximumAttempts ?? 0;
+  if (maximumAttempts > 0 && attempt >= maximumAttempts) return { retry: false, state: 'RETRY_STATE_MAXIMUM_ATTEMPTS_REACHED' };
+  const initial = durationMs(policy.initialInterval) || 1000;
+  const coefficient = policy.backoffCoefficient ?? 2;
+  const maximum = durationMs(policy.maximumInterval) || initial * 100;
+  const delayMs = app?.nextRetryDelay ? durationMs(app.nextRetryDelay) : Math.min(initial * coefficient ** (attempt - 1), maximum);
+  if (deadline !== undefined && now + delayMs >= deadline) return { retry: false, state: 'RETRY_STATE_TIMEOUT' };
+  return { retry: true, delayMs };
+}
+
+const TIMEOUT_NAME: Record<string, string> = {
+  TIMEOUT_TYPE_START_TO_CLOSE: 'StartToClose',
+  TIMEOUT_TYPE_SCHEDULE_TO_START: 'ScheduleToStart',
+  TIMEOUT_TYPE_SCHEDULE_TO_CLOSE: 'ScheduleToClose',
+  TIMEOUT_TYPE_HEARTBEAT: 'Heartbeat',
+};
+
+function timeoutFailure(kind: string, timeoutType: string, lastHeartbeatDetails?: Obj): Obj {
+  return {
+    message: `${kind} ${TIMEOUT_NAME[timeoutType] ?? 'unknown'} timeout`,
+    source: '',
+    timeoutFailureInfo: { timeoutType, ...(lastHeartbeatDetails ? { lastHeartbeatDetails } : {}) },
+  };
+}
+
+class UnhandledCommand extends Error {
+  readonly cause2: string;
+  constructor(cause: string, message: string) {
+    super(message);
+    this.cause2 = cause;
+  }
+}
+
+type PendingQuery = { id: string; namespace: string; runId: string; taskQueue: string; query: Obj; resolve: (value: Obj) => void; reject: (error: Error) => void; dispatched: boolean };
+
+export type EngineOptions = { root?: string; readOnly?: boolean };
+
+export class TemporalEngine {
+  readonly store: TemporalStore;
+  readonly readOnly: boolean;
+  /** holders from engineForRoot (see releaseEngine) */
+  users = 0;
+  private lock: Promise<unknown> = Promise.resolve();
+  // counter: waiters parked on the next state change (long polls), resolved by `notify`
+  private waiters = new Set<() => void>();
+  // cache: in-flight queries — Temporal holds these in memory too; they are never state
+  private queries = new Map<string, PendingQuery>();
+  private querySeq = 0;
+  /** runs minted in the current transition and not yet written (see newRun) */
+  private pendingRuns = 0;
+  private ticker: ReturnType<typeof setInterval> | undefined;
+  private ticking = false;
+  // cache: sticky queue names a worker announced it is shutting down
+  private closedSticky = new Set<string>();
+
+  constructor(options: EngineOptions = {}) {
+    this.store = new TemporalStore(options.root);
+    this.readOnly = options.readOnly ?? false;
+  }
+
+  /** Start the clock-driven work: timers, timeouts, retries and delayed tasks falling due. */
+  start(intervalMs = 100): void {
+    if (this.ticker) return;
+    // a tick that fails (a World clock file caught mid-write, a store error) is reported and retried on
+    // the next tick; it never takes the server down
+    this.ticker = setInterval(() => {
+      this.tick().catch((error: unknown) => { process.stderr.write(`temporal: world-clock tick failed: ${(error as Error)?.message ?? String(error)}\n`); });
+    }, intervalMs);
+  }
+
+  stop(): void {
+    if (this.ticker) clearInterval(this.ticker);
+    this.ticker = undefined;
+    for (const wake of this.waiters) wake();
+    this.waiters.clear();
+    for (const query of this.queries.values()) query.reject(new GrpcError(GrpcStatus.UNAVAILABLE, 'server stopping'));
+    this.queries.clear();
+  }
+
+  private serial<T>(fn: () => Promise<T>): Promise<T> {
+    const run = (): Promise<T> => {
+      this.pendingRuns = 0;
+      return fn();
+    };
+    const next = this.lock.then(run, run);
+    this.lock = next.catch(() => undefined);
+    return next;
+  }
+
+  private notify(): void {
+    const waiters = [...this.waiters];
+    this.waiters.clear();
+    for (const wake of waiters) wake();
+  }
+
+  /** Park until the next state change, the deadline, or the caller going away. */
+  private wait(signal: AbortSignal, until: number): Promise<void> {
+    return new Promise((resolve) => {
+      const timer = setTimeout(done, Math.max(0, until - Date.now()));
+      function done(): void {
+        clearTimeout(timer);
+        signal.removeEventListener('abort', done);
+        resolve();
+      }
+      this.waiters.add(done);
+      signal.addEventListener('abort', done, { once: true });
+    });
+  }
+
+  private assertWritable(): void {
+    if (this.readOnly) throw new GrpcError(GrpcStatus.PERMISSION_DENIED, 'this Temporal twin is read-only');
+  }
+
+  // ---- reads ---------------------------------------------------------------------------------------
+
+  runs(namespace?: string): Run[] {
+    const all = this.store.list(EXECUTION_TYPE) as unknown as Run[];
+    return namespace === undefined ? all : all.filter((run) => run.namespace === namespace);
+  }
+
+  run(runId: string): Run | undefined {
+    return this.store.get(EXECUTION_TYPE, runId) as unknown as Run | undefined;
+  }
+
+  /** The run a request names: that run id, or the workflow id's current (latest) run. */
+  resolveRun(namespace: string, execution: { workflowId?: string; runId?: string } | undefined, firstExecutionRunId?: string): Run {
+    const workflowId = execution?.workflowId ?? '';
+    const runId = execution?.runId ?? '';
+    if (!workflowId) throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, 'WorkflowId is not set on request.');
+    if (runId) {
+      const run = this.run(runId);
+      if (!run || run.namespace !== namespace || run.execution.workflowId !== workflowId) {
+        throw new GrpcError(GrpcStatus.NOT_FOUND, `workflow not found for ID: ${workflowId}`);
+      }
+      return run;
+    }
+    const candidates = this.runs(namespace).filter((run) => run.execution.workflowId === workflowId && (!firstExecutionRunId || run.firstRunId === firstExecutionRunId));
+    const current = latest(candidates);
+    if (!current) throw new GrpcError(GrpcStatus.NOT_FOUND, `workflow not found for ID: ${workflowId}`);
+    return current;
+  }
+
+  async history(run: Run): Promise<HistoryEvent[]> {
+    return this.store.readChunks(run._state.history);
+  }
+
+  private async commit(tx: RunTx, operation: string, input?: Obj): Promise<void> {
+    const state = tx.state;
+    if (tx.events.length > 0) {
+      state.history = [...state.history, await this.store.appendChunk(tx.events)];
+    }
+    tx.run.stateTransitionCount = Number(tx.run.stateTransitionCount ?? 0) + 1;
+    tx.run.historySizeBytes = state.historyBytes;
+    state.nextDue = nextDue(tx.run, tx.now);
+    const { id, ...fields } = tx.run;
+    await this.store.put(EXECUTION_TYPE, id, fields, operation, input);
+  }
+
+  // ---- namespaces and search attributes ------------------------------------------------------------
+  //
+  // A namespace is one subject: its DescribeNamespaceResponse, plus `_searchAttributes` (its custom
+  // search attributes, name → IndexedValueType) — namespace configuration, as the server keeps it.
+  // `default` exists from the start, as on Temporal's dev server; it is written to the tree the first
+  // time something changes it.
+
+  /** Every namespace, stored fields included (bookkeeping too). */
+  private namespaceRecords(): Obj[] {
+    const stored = this.store.list(NAMESPACE_TYPE).map(({ id: _id, ...fields }) => fields);
+    const hasDefault = stored.some((ns) => (ns.namespaceInfo as Obj | undefined)?.name === DEFAULT_NAMESPACE);
+    return hasDefault ? stored : [defaultNamespace(), ...stored];
+  }
+
+  private namespaceRecord(name: string): Obj {
+    const found = this.namespaceRecords().find((ns) => (ns.namespaceInfo as Obj).name === name || (ns.namespaceInfo as Obj).id === name);
+    if (!found) throw new GrpcError(GrpcStatus.NOT_FOUND, `Namespace ${name} is not found.`);
+    return found;
+  }
+
+  /** The namespaces as DescribeNamespace answers them (bookkeeping never reaches the wire). */
+  namespaces(): Obj[] {
+    return this.namespaceRecords().map(publicView);
+  }
+
+  namespace(name: string): Obj {
+    return publicView(this.namespaceRecord(name));
+  }
+
+  private requireNamespace(name: unknown): string {
+    const namespace = String(name ?? '');
+    if (!namespace) throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, 'Namespace not set on request.');
+    this.namespace(namespace);
+    return namespace;
+  }
+
+  async registerNamespace(request: Obj): Promise<Obj> {
+    this.assertWritable();
+    const name = String(request.namespace ?? '');
+    if (!name) throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, 'Namespace not set on request.');
+    return this.serial(async () => {
+      if (this.namespaces().some((ns) => (ns.namespaceInfo as Obj).name === name)) {
+        throw new GrpcError(GrpcStatus.ALREADY_EXISTS, 'Namespace already exists.');
+      }
+      const fields = {
+        namespaceInfo: {
+          name, state: 'NAMESPACE_STATE_REGISTERED', id: uuidFrom(`namespace\0${name}`),
+          ...(request.description ? { description: request.description } : {}),
+          ...(request.ownerEmail ? { ownerEmail: request.ownerEmail } : {}),
+          ...(request.data ? { data: request.data } : {}),
+          capabilities: namespaceCapabilities(), supportsSchedules: false,
+        },
+        config: {
+          workflowExecutionRetentionTtl: request.workflowExecutionRetentionPeriod ?? { seconds: 86_400 },
+          historyArchivalState: 'ARCHIVAL_STATE_DISABLED',
+          visibilityArchivalState: 'ARCHIVAL_STATE_DISABLED',
+        },
+        replicationConfig: { activeClusterName: 'active', clusters: [{ clusterName: 'active' }], state: 'REPLICATION_STATE_NORMAL' },
+        isGlobalNamespace: false,
+      };
+      await this.store.put(NAMESPACE_TYPE, name, fields, 'RegisterNamespace', request);
+      return {};
+    });
+  }
+
+  customSearchAttributes(namespace: string): Record<string, string> {
+    return { ...((this.namespaceRecord(namespace)._searchAttributes ?? {}) as Record<string, string>) };
+  }
+
+  /** Write a namespace's custom search attributes (the whole namespace subject, `default` included). */
+  private async putSearchAttributes(namespace: string, attributes: Record<string, string>, operation: string, request: Obj): Promise<void> {
+    const record = this.namespaceRecord(namespace);
+    const name = String((record.namespaceInfo as Obj).name);
+    await this.store.put(NAMESPACE_TYPE, name, { ...record, _searchAttributes: attributes }, operation, request);
+  }
+
+  async addSearchAttributes(request: Obj): Promise<Obj> {
+    this.assertWritable();
+    const namespace = this.requireNamespace(request.namespace);
+    const wanted = (request.searchAttributes ?? {}) as Record<string, string>;
+    return this.serial(async () => {
+      const existing = this.customSearchAttributes(namespace);
+      for (const [name, type] of Object.entries(wanted)) {
+        if (SYSTEM_SEARCH_ATTRIBUTES[name]) throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, `Search attribute ${name} is reserved by system.`);
+        if (!type || type === 'INDEXED_VALUE_TYPE_UNSPECIFIED') throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, `Unknown search attribute type: ${type}.`);
+        if (existing[name] !== undefined && existing[name] !== type) {
+          throw new GrpcError(GrpcStatus.ALREADY_EXISTS, `Search attribute ${name} already exists.`);
+        }
+      }
+      const next = { ...existing, ...wanted };
+      if (Object.keys(wanted).some((name) => existing[name] === undefined)) await this.putSearchAttributes(namespace, next, 'AddSearchAttributes', request);
+      return {};
+    });
+  }
+
+  async removeSearchAttributes(request: Obj): Promise<Obj> {
+    this.assertWritable();
+    const namespace = this.requireNamespace(request.namespace);
+    const names = (request.searchAttributes ?? []) as string[];
+    return this.serial(async () => {
+      const existing = this.customSearchAttributes(namespace);
+      for (const name of names) {
+        if (existing[name] === undefined) throw new GrpcError(GrpcStatus.NOT_FOUND, `Search attribute ${name} doesn't exist.`);
+      }
+      for (const name of names) delete existing[name];
+      await this.putSearchAttributes(namespace, existing, 'RemoveSearchAttributes', request);
+      return {};
+    });
+  }
+
+  listSearchAttributes(request: Obj): Obj {
+    const namespace = this.requireNamespace(request.namespace);
+    return { customAttributes: this.customSearchAttributes(namespace), systemAttributes: SYSTEM_SEARCH_ATTRIBUTES, storageSchema: {} };
+  }
+
+  /** INVALID_ARGUMENT for a search attribute the namespace does not define (Temporal refuses these). */
+  private validateSearchAttributes(namespace: string, attributes: unknown, workerSet: boolean): void {
+    const fields = (attributes as { indexedFields?: Record<string, unknown> } | undefined)?.indexedFields ?? {};
+    const custom = this.customSearchAttributes(namespace);
+    for (const name of Object.keys(fields)) {
+      if (custom[name] !== undefined) continue;
+      if (workerSet && WORKER_SETTABLE_SYSTEM_ATTRIBUTES.has(name)) continue;
+      throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, `Namespace ${namespace} has no mapping defined for search attribute ${name}`);
+    }
+  }
+
+  private workerError(message: string): never {
+    throw new UnhandledCommand('WORKFLOW_TASK_FAILED_CAUSE_BAD_SEARCH_ATTRIBUTES', message);
+  }
+
+  // ---- starting runs -------------------------------------------------------------------------------
+
+  /** Create a run and its first events (inside a transition). */
+  private newRun(now: number, spec: {
+    namespace: string; workflowId: string; workflowType: Obj; taskQueue: string; input?: Obj; header?: Obj; memo?: Obj;
+    searchAttributes?: Obj; executionTimeoutMs: number; runTimeoutMs: number; workflowTaskTimeoutMs: number; retryPolicy?: RetryPolicy;
+    attempt?: number; identity?: string; requestId?: string; parent?: RunState['parent']; rootExecution?: { workflowId: string; runId: string };
+    firstRunId?: string; continuedExecutionRunId?: string; initiator?: string; continuedFailure?: Obj; lastCompletionResult?: Obj;
+    backoffMs?: number; executionExpiresAt?: number; signal?: { signalName: string; input?: Obj; header?: Obj; identity?: string };
+    priority?: Obj; userMetadata?: Obj; seed: string;
+  }): RunTx {
+    // after every run written so far, and after any this transition minted and has not written yet
+    const seq = this.runs().reduce((max, run) => Math.max(max, run._state.seq), 0) + 1 + this.pendingRuns;
+    this.pendingRuns += 1;
+    const runId = uuidFrom(`run\0${spec.namespace}\0${spec.workflowId}\0${spec.seed}\0${seq}`);
+    const state = freshState();
+    state.seq = seq;
+    state.workflowTaskTimeoutMs = spec.workflowTaskTimeoutMs;
+    state.runTimeoutMs = spec.runTimeoutMs;
+    state.executionTimeoutMs = spec.executionTimeoutMs;
+    state.attempt = spec.attempt ?? 1;
+    if (spec.retryPolicy) state.retryPolicy = spec.retryPolicy;
+    if (spec.input) state.input = spec.input;
+    if (spec.header) state.header = spec.header;
+    if (spec.requestId) state.startRequestIds = [spec.requestId];
+    if (spec.parent) state.parent = spec.parent;
+    const backoff = spec.backoffMs ?? 0;
+    const executionExpiresAt = spec.executionExpiresAt ?? (spec.executionTimeoutMs ? now + spec.executionTimeoutMs : undefined);
+    if (executionExpiresAt) state.executionExpiresAt = executionExpiresAt;
+    if (spec.runTimeoutMs) state.runExpiresAt = now + backoff + spec.runTimeoutMs;
+    const firstRunId = spec.firstRunId ?? runId;
+    const root = spec.rootExecution ?? { workflowId: spec.workflowId, runId };
+    const run: Run = {
+      id: runId,
+      namespace: spec.namespace,
+      execution: { workflowId: spec.workflowId, runId },
+      type: spec.workflowType as { name: string },
+      startTime: toTimestamp(now),
+      executionTime: toTimestamp(now + backoff),
+      status: RUNNING,
+      historyLength: 0,
+      taskQueue: spec.taskQueue,
+      firstRunId,
+      rootExecution: root,
+      stateTransitionCount: 0,
+      ...(spec.memo ? { memo: spec.memo } : {}),
+      ...(spec.searchAttributes ? { searchAttributes: spec.searchAttributes } : {}),
+      ...(spec.parent ? { parentExecution: { workflowId: spec.parent.workflowId, runId: spec.parent.runId }, parentNamespaceId: String((this.namespace(spec.parent.namespace).namespaceInfo as Obj).id) } : {}),
+      ...(spec.priority ? { priority: spec.priority } : {}),
+      _state: state,
+    };
+    const tx = new RunTx(run, now);
+    tx.append('EVENT_TYPE_WORKFLOW_EXECUTION_STARTED', 'workflowExecutionStartedEventAttributes', {
+      workflowId: spec.workflowId,
+      workflowType: spec.workflowType,
+      taskQueue: { name: spec.taskQueue, kind: 'TASK_QUEUE_KIND_NORMAL' },
+      ...(spec.input ? { input: spec.input } : {}),
+      ...(spec.header ? { header: spec.header } : {}),
+      workflowExecutionTimeout: toDuration(spec.executionTimeoutMs),
+      workflowRunTimeout: toDuration(spec.runTimeoutMs),
+      workflowTaskTimeout: toDuration(spec.workflowTaskTimeoutMs),
+      ...(spec.continuedExecutionRunId ? { continuedExecutionRunId: spec.continuedExecutionRunId } : {}),
+      ...(spec.initiator ? { initiator: spec.initiator } : {}),
+      ...(spec.continuedFailure ? { continuedFailure: spec.continuedFailure } : {}),
+      ...(spec.lastCompletionResult ? { lastCompletionResult: spec.lastCompletionResult } : {}),
+      originalExecutionRunId: runId,
+      ...(spec.identity ? { identity: spec.identity } : {}),
+      firstExecutionRunId: firstRunId,
+      ...(spec.retryPolicy ? { retryPolicy: spec.retryPolicy } : {}),
+      attempt: state.attempt,
+      ...(executionExpiresAt ? { workflowExecutionExpirationTime: toTimestamp(executionExpiresAt) } : {}),
+      ...(backoff ? { firstWorkflowTaskBackoff: toDuration(backoff) } : {}),
+      ...(spec.memo ? { memo: spec.memo } : {}),
+      ...(spec.searchAttributes ? { searchAttributes: spec.searchAttributes } : {}),
+      ...(spec.parent ? {
+        parentWorkflowNamespace: spec.parent.namespace,
+        parentWorkflowNamespaceId: run.parentNamespaceId,
+        parentWorkflowExecution: { workflowId: spec.parent.workflowId, runId: spec.parent.runId },
+        parentInitiatedEventId: spec.parent.initiatedEventId,
+      } : {}),
+      rootWorkflowExecution: root,
+      ...(spec.priority ? { priority: spec.priority } : {}),
+    });
+    if (spec.signal) {
+      tx.append('EVENT_TYPE_WORKFLOW_EXECUTION_SIGNALED', 'workflowExecutionSignaledEventAttributes', {
+        signalName: spec.signal.signalName,
+        ...(spec.signal.input ? { input: spec.signal.input } : {}),
+        ...(spec.signal.identity ? { identity: spec.signal.identity } : {}),
+        ...(spec.signal.header ? { header: spec.signal.header } : {}),
+      });
+    }
+    if (backoff > 0) tx.state.firstWftAt = now + backoff;
+    else tx.scheduleWorkflowTask();
+    return tx;
+  }
+
+  private startSpec(namespace: string, request: Obj, seed: string): Parameters<TemporalEngine['newRun']>[1] {
+    const workflowId = String(request.workflowId ?? '');
+    if (!workflowId) throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, 'WorkflowId is not set on request.');
+    const workflowType = request.workflowType as Obj | undefined;
+    if (!workflowType?.name) throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, 'WorkflowType is not set on request.');
+    const taskQueue = String((request.taskQueue as Obj | undefined)?.name ?? '');
+    if (!taskQueue) throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, 'TaskQueue is not set on request.');
+    if (request.cronSchedule) throw new GrpcError(GrpcStatus.UNIMPLEMENTED, 'this Temporal twin does not run cron schedules (CronSchedule)');
+    if ((request.completionCallbacks as unknown[] | undefined)?.length) throw new GrpcError(GrpcStatus.UNIMPLEMENTED, 'this Temporal twin does not deliver completion callbacks');
+    if (request.versioningOverride) throw new GrpcError(GrpcStatus.UNIMPLEMENTED, 'this Temporal twin does not implement worker versioning (VersioningOverride)');
+    this.validateSearchAttributes(namespace, request.searchAttributes, false);
+    const executionTimeoutMs = durationMs(request.workflowExecutionTimeout);
+    let runTimeoutMs = durationMs(request.workflowRunTimeout);
+    if (executionTimeoutMs && (!runTimeoutMs || runTimeoutMs > executionTimeoutMs)) runTimeoutMs = executionTimeoutMs;
+    const workflowTaskTimeoutMs = Math.min(durationMs(request.workflowTaskTimeout) || DEFAULT_WFT_TIMEOUT_MS, MAX_WFT_TIMEOUT_MS, runTimeoutMs || MAX_WFT_TIMEOUT_MS);
+    return {
+      namespace, workflowId, workflowType, taskQueue, executionTimeoutMs, runTimeoutMs, workflowTaskTimeoutMs, seed,
+      ...(request.input ? { input: request.input as Obj } : {}),
+      ...(request.header ? { header: request.header as Obj } : {}),
+      ...(request.memo ? { memo: request.memo as Obj } : {}),
+      ...(request.searchAttributes ? { searchAttributes: request.searchAttributes as Obj } : {}),
+      ...(request.retryPolicy ? { retryPolicy: request.retryPolicy as RetryPolicy } : {}),
+      ...(request.identity ? { identity: String(request.identity) } : {}),
+      ...(request.requestId ? { requestId: String(request.requestId) } : {}),
+      ...(request.priority ? { priority: request.priority as Obj } : {}),
+      ...(durationMs(request.workflowStartDelay) ? { backoffMs: durationMs(request.workflowStartDelay) } : {}),
+      ...(request.lastCompletionResult ? { lastCompletionResult: request.lastCompletionResult as Obj } : {}),
+      ...(request.continuedFailure ? { continuedFailure: request.continuedFailure as Obj } : {}),
+    };
+  }
+
+  /** WorkflowIdConflictPolicy / WorkflowIdReusePolicy against the workflow id's latest run. Answers
+   *  `existing` when the start resolves to a run that is already running (USE_EXISTING). */
+  private async admitStart(namespace: string, workflowId: string, request: Obj, now: number): Promise<{ existing?: Run; duplicate?: boolean }> {
+    const runs = this.runs(namespace).filter((run) => run.execution.workflowId === workflowId);
+    const current = latest(runs);
+    if (!current) return {};
+    const requestId = String(request.requestId ?? '');
+    // a request id the server has seen is the same request retried: it answers the run that request
+    // made, whether or not that run is still open
+    // a start retried with its request id answers the run it made while that run is still the
+    // current one (open or closed); start request ids are kept apart from signal and cancel ids
+    if (requestId && (current._state.startRequestIds ?? []).includes(requestId)) return { existing: current, duplicate: true };
+    if (current.status === RUNNING) {
+      const conflict = String(request.workflowIdConflictPolicy ?? 'WORKFLOW_ID_CONFLICT_POLICY_UNSPECIFIED');
+      const reuse = String(request.workflowIdReusePolicy ?? '');
+      if (conflict === 'WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING') return { existing: current };
+      if (conflict === 'WORKFLOW_ID_CONFLICT_POLICY_TERMINATE_EXISTING' || reuse === 'WORKFLOW_ID_REUSE_POLICY_TERMINATE_IF_RUNNING') {
+        await this.terminateRun(current, now, { reason: 'terminated by new runID', identity: String(request.identity ?? '') }, 'StartWorkflowExecution');
+        return {};
+      }
+      throw new GrpcError(GrpcStatus.ALREADY_EXISTS, `Workflow execution is already running. WorkflowId: ${workflowId}, RunId: ${current.execution.runId}.`);
+    }
+    const reuse = String(request.workflowIdReusePolicy ?? 'WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE');
+    if (reuse === 'WORKFLOW_ID_REUSE_POLICY_REJECT_DUPLICATE') {
+      throw new GrpcError(GrpcStatus.ALREADY_EXISTS, `Workflow execution already finished and WorkflowIdReusePolicy is REJECT_DUPLICATE. WorkflowId: ${workflowId}, RunId: ${current.execution.runId}.`);
+    }
+    if (reuse === 'WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY' && current.status === 'WORKFLOW_EXECUTION_STATUS_COMPLETED') {
+      throw new GrpcError(GrpcStatus.ALREADY_EXISTS, `Workflow execution already finished successfully. WorkflowId: ${workflowId}, RunId: ${current.execution.runId}. Workflow Id reuse policy: allow duplicate workflow Id if last run failed.`);
+    }
+    return {};
+  }
+
+  async startWorkflowExecution(request: Obj): Promise<Obj> {
+    this.assertWritable();
+    const namespace = this.requireNamespace(request.namespace);
+    if (request.requestEagerExecution) { /* eager start is a hint a server may decline; this one does */ }
+    return this.serial(async () => {
+      const now = nowMs();
+      const spec = this.startSpec(namespace, request, String(request.requestId ?? ''));
+      const { existing, duplicate } = await this.admitStart(namespace, spec.workflowId, request, now);
+      if (existing) return { runId: existing.execution.runId, started: Boolean(duplicate), status: existing.status };
+      const tx = this.newRun(now, spec);
+      await this.commit(tx, 'StartWorkflowExecution', request);
+      this.notify();
+      return { runId: tx.run.execution.runId, started: true, status: RUNNING };
+    });
+  }
+
+  async signalWithStartWorkflowExecution(request: Obj): Promise<Obj> {
+    this.assertWritable();
+    const namespace = this.requireNamespace(request.namespace);
+    const signalName = String(request.signalName ?? '');
+    if (!signalName) throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, 'SignalName is not set on request.');
+    return this.serial(async () => {
+      const now = nowMs();
+      const spec = this.startSpec(namespace, request, `signal\0${String(request.requestId ?? '')}`);
+      // signal-with-start signals a running run unless the conflict policy says otherwise
+      const current = latest(this.runs(namespace).filter((run) => run.execution.workflowId === spec.workflowId));
+      const conflict = String(request.workflowIdConflictPolicy ?? 'WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING');
+      if (current?.status === RUNNING && conflict !== 'WORKFLOW_ID_CONFLICT_POLICY_TERMINATE_EXISTING') {
+        if (conflict === 'WORKFLOW_ID_CONFLICT_POLICY_FAIL') {
+          throw new GrpcError(GrpcStatus.ALREADY_EXISTS, `Workflow execution is already running. WorkflowId: ${spec.workflowId}, RunId: ${current.execution.runId}.`);
+        }
+        const requestId = String(request.requestId ?? '');
+        // the same request retried signals once
+        if (requestId && (current._state.requestIds.includes(requestId) || (current._state.startRequestIds ?? []).includes(requestId))) return { runId: current.execution.runId, started: false };
+        const tx = new RunTx(current, now);
+        if (requestId) tx.state.requestIds = [...tx.state.requestIds, requestId].slice(-100);
+        this.signalInto(tx, { signalName, input: request.signalInput as Obj | undefined, header: request.header as Obj | undefined, identity: String(request.identity ?? '') });
+        await this.commit(tx, 'SignalWithStartWorkflowExecution', request);
+        this.notify();
+        return { runId: current.execution.runId, started: false };
+      }
+      const admitted = await this.admitStart(namespace, spec.workflowId, { ...request, workflowIdConflictPolicy: conflict }, now);
+      if (admitted.existing) return { runId: admitted.existing.execution.runId, started: false };
+      const tx = this.newRun(now, { ...spec, signal: { signalName, ...(request.signalInput ? { input: request.signalInput as Obj } : {}), ...(request.header ? { header: request.header as Obj } : {}), ...(request.identity ? { identity: String(request.identity) } : {}) } });
+      await this.commit(tx, 'SignalWithStartWorkflowExecution', request);
+      this.notify();
+      return { runId: tx.run.execution.runId, started: true };
+    });
+  }
+
+  // ---- signals, cancellation, termination ----------------------------------------------------------
+
+  private signalInto(tx: RunTx, signal: { signalName: string; input?: Obj; header?: Obj; identity?: string; external?: { workflowId: string; runId: string } }): void {
+    tx.deliver('EVENT_TYPE_WORKFLOW_EXECUTION_SIGNALED', 'workflowExecutionSignaledEventAttributes', {
+      signalName: signal.signalName,
+      ...(signal.input ? { input: signal.input } : {}),
+      ...(signal.identity ? { identity: signal.identity } : {}),
+      ...(signal.header ? { header: signal.header } : {}),
+      ...(signal.external ? { externalWorkflowExecution: signal.external } : {}),
+    });
+  }
+
+  async signalWorkflowExecution(request: Obj): Promise<Obj> {
+    this.assertWritable();
+    const namespace = this.requireNamespace(request.namespace);
+    const signalName = String(request.signalName ?? '');
+    if (!signalName) throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, 'SignalName is not set on request.');
+    return this.serial(async () => {
+      const run = this.resolveRun(namespace, request.workflowExecution as Obj);
+      if (run.status !== RUNNING) throw new GrpcError(GrpcStatus.NOT_FOUND, 'workflow execution already completed');
+      const requestId = String(request.requestId ?? '');
+      if (requestId && run._state.requestIds.includes(requestId)) return {};
+      const tx = new RunTx(run, nowMs());
+      if (requestId) tx.state.requestIds = [...tx.state.requestIds, requestId].slice(-100);
+      this.signalInto(tx, { signalName, input: request.input as Obj | undefined, header: request.header as Obj | undefined, identity: String(request.identity ?? '') });
+      await this.commit(tx, 'SignalWorkflowExecution', request);
+      this.notify();
+      return {};
+    });
+  }
+
+  async requestCancelWorkflowExecution(request: Obj): Promise<Obj> {
+    this.assertWritable();
+    const namespace = this.requireNamespace(request.namespace);
+    return this.serial(async () => {
+      const run = this.resolveRun(namespace, request.workflowExecution as Obj, request.firstExecutionRunId as string | undefined);
+      if (run.status !== RUNNING) throw new GrpcError(GrpcStatus.NOT_FOUND, 'workflow execution already completed');
+      const requestId = String(request.requestId ?? '');
+      if (run._state.cancelRequested) return {};
+      const tx = new RunTx(run, nowMs());
+      this.cancelRequestInto(tx, { cause: String(request.reason ?? ''), identity: String(request.identity ?? '') });
+      if (requestId) tx.state.requestIds = [...tx.state.requestIds, requestId].slice(-100);
+      await this.commit(tx, 'RequestCancelWorkflowExecution', request);
+      this.notify();
+      return {};
+    });
+  }
+
+  private cancelRequestInto(tx: RunTx, request: { cause?: string; identity?: string; externalInitiatedEventId?: number; externalWorkflowExecution?: Obj }): void {
+    tx.state.cancelRequested = true;
+    tx.deliver('EVENT_TYPE_WORKFLOW_EXECUTION_CANCEL_REQUESTED', 'workflowExecutionCancelRequestedEventAttributes', {
+      ...(request.cause ? { cause: request.cause } : {}),
+      ...(request.identity ? { identity: request.identity } : {}),
+      ...(request.externalInitiatedEventId ? { externalInitiatedEventId: request.externalInitiatedEventId } : {}),
+      ...(request.externalWorkflowExecution ? { externalWorkflowExecution: request.externalWorkflowExecution } : {}),
+    });
+  }
+
+  async terminateWorkflowExecution(request: Obj): Promise<Obj> {
+    this.assertWritable();
+    const namespace = this.requireNamespace(request.namespace);
+    return this.serial(async () => {
+      const run = this.resolveRun(namespace, request.workflowExecution as Obj, request.firstExecutionRunId as string | undefined);
+      if (run.status !== RUNNING) throw new GrpcError(GrpcStatus.NOT_FOUND, 'workflow execution already completed');
+      await this.terminateRun(run, nowMs(), { reason: String(request.reason ?? ''), identity: String(request.identity ?? ''), details: request.details as Obj | undefined }, 'TerminateWorkflowExecution', request);
+      this.notify();
+      return {};
+    });
+  }
+
+  private async terminateRun(run: Run, now: number, why: { reason: string; identity: string; details?: Obj }, operation: string, input?: Obj): Promise<void> {
+    const tx = new RunTx(run, now);
+    if (tx.state.wft?.startedEventId !== undefined) {
+      // a task in flight fails with the termination, as the server records it
+      tx.append('EVENT_TYPE_WORKFLOW_TASK_FAILED', 'workflowTaskFailedEventAttributes', {
+        scheduledEventId: tx.state.wft.scheduledEventId, startedEventId: tx.state.wft.startedEventId,
+        cause: 'WORKFLOW_TASK_FAILED_CAUSE_FORCE_CLOSE_COMMAND', identity: why.identity,
+      });
+    }
+    tx.state.wft = null;
+    tx.flushBuffered();
+    const closeEventId = tx.append('EVENT_TYPE_WORKFLOW_EXECUTION_TERMINATED', 'workflowExecutionTerminatedEventAttributes', {
+      reason: why.reason, ...(why.details ? { details: why.details } : {}), identity: why.identity,
+    });
+    await this.closeRun(tx, 'WORKFLOW_EXECUTION_STATUS_TERMINATED', closeEventId, operation, input, { terminated: true });
+  }
+
+  /** Close a run: retire its tasks, apply its children's parent-close policy, tell its parent. */
+  private async closeRun(tx: RunTx, status: string, closeEventId: number, operation: string, input?: Obj, how: { terminated?: boolean; newRunId?: string; continued?: boolean } = {}): Promise<void> {
+    const run = tx.run;
+    const state = tx.state;
+    run.status = status;
+    run.closeTime = toTimestamp(tx.now);
+    run.executionDuration = toDuration(Math.max(0, tx.now - (timestampMs(run.executionTime) ?? tx.now)));
+    state.closeEventId = closeEventId;
+    state.wft = null;
+    state.firstWftAt = undefined;
+    state.buffered = [];
+    state.activities = {};
+    state.timers = {};
+    if (how.newRunId) state.newRunId = how.newRunId;
+    const children = Object.values(state.children);
+    state.children = {};
+    await this.commit(tx, operation, input);
+    // children by their parent-close policy: the run closing is what applies it, a continue-as-new included
+    {
+      for (const child of children) {
+        if (!child.runId) continue;
+        const childRun = this.run(child.runId);
+        const current = childRun ? latest(this.runs(childRun.namespace).filter((r) => r.execution.workflowId === childRun.execution.workflowId && r.firstRunId === childRun.firstRunId)) : undefined;
+        if (!current || current.status !== RUNNING) continue;
+        if (child.parentClosePolicy === 'PARENT_CLOSE_POLICY_ABANDON') continue;
+        if (child.parentClosePolicy === 'PARENT_CLOSE_POLICY_REQUEST_CANCEL') {
+          const childTx = new RunTx(current, tx.now);
+          this.cancelRequestInto(childTx, { cause: 'by parent close policy', identity: 'history-service' });
+          await this.commit(childTx, 'ParentClosePolicy');
+        } else {
+          await this.terminateRun(current, tx.now, { reason: 'by parent close policy', identity: 'history-service' }, 'ParentClosePolicy');
+        }
+      }
+    }
+    // the parent hears of its child's close when the chain ends (not on continue-as-new or a retry)
+    if (state.parent && !how.newRunId) await this.notifyParent(run, status, closeEventId, tx.now);
+  }
+
+  private async notifyParent(child: Run, status: string, closeEventId: number, now: number): Promise<void> {
+    const parentInfo = child._state.parent!;
+    const parent = this.run(parentInfo.runId);
+    if (!parent || parent.status !== RUNNING) return;
+    const pending = parent._state.children[String(parentInfo.initiatedEventId)];
+    if (!pending) return;
+    const events = await this.history(child);
+    const close: Record<string, unknown> = events.find((event) => event.eventId === closeEventId) ?? {};
+    const common = {
+      namespace: child.namespace,
+      namespaceId: String((this.namespace(child.namespace).namespaceInfo as Obj).id),
+      workflowExecution: { workflowId: child.execution.workflowId, runId: child.execution.runId },
+      workflowType: child.type,
+      initiatedEventId: parentInfo.initiatedEventId,
+      startedEventId: pending.startedEventId,
+    };
+    const tx = new RunTx(parent, now);
+    delete tx.state.children[String(parentInfo.initiatedEventId)];
+    switch (status) {
+      case 'WORKFLOW_EXECUTION_STATUS_COMPLETED': {
+        const attrs = close.workflowExecutionCompletedEventAttributes as Obj | undefined;
+        tx.deliver('EVENT_TYPE_CHILD_WORKFLOW_EXECUTION_COMPLETED', 'childWorkflowExecutionCompletedEventAttributes', { ...common, ...(attrs?.result ? { result: attrs.result } : {}) });
+        break;
+      }
+      case 'WORKFLOW_EXECUTION_STATUS_FAILED': {
+        const attrs = close.workflowExecutionFailedEventAttributes as Obj | undefined;
+        tx.deliver('EVENT_TYPE_CHILD_WORKFLOW_EXECUTION_FAILED', 'childWorkflowExecutionFailedEventAttributes', { ...common, failure: attrs?.failure, retryState: attrs?.retryState ?? 'RETRY_STATE_RETRY_POLICY_NOT_SET' });
+        break;
+      }
+      case 'WORKFLOW_EXECUTION_STATUS_CANCELED': {
+        const attrs = close.workflowExecutionCanceledEventAttributes as Obj | undefined;
+        tx.deliver('EVENT_TYPE_CHILD_WORKFLOW_EXECUTION_CANCELED', 'childWorkflowExecutionCanceledEventAttributes', { ...common, ...(attrs?.details ? { details: attrs.details } : {}) });
+        break;
+      }
+      case 'WORKFLOW_EXECUTION_STATUS_TIMED_OUT':
+        tx.deliver('EVENT_TYPE_CHILD_WORKFLOW_EXECUTION_TIMED_OUT', 'childWorkflowExecutionTimedOutEventAttributes', { ...common, retryState: 'RETRY_STATE_TIMEOUT' });
+        break;
+      default:
+        tx.deliver('EVENT_TYPE_CHILD_WORKFLOW_EXECUTION_TERMINATED', 'childWorkflowExecutionTerminatedEventAttributes', common);
+    }
+    await this.commit(tx, 'ChildWorkflowExecutionClosed');
+  }
+
+  // ---- workflow tasks ------------------------------------------------------------------------------
+
+  async pollWorkflowTaskQueue(request: Obj, signal: AbortSignal, deadline?: number): Promise<Obj> {
+    const namespace = this.requireNamespace(request.namespace);
+    const queue = request.taskQueue as { name?: string; kind?: string } | undefined;
+    const name = String(queue?.name ?? '');
+    if (!name) throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, 'TaskQueue is not set on request.');
+    const until = Math.min(Date.now() + LONG_POLL_MS, (deadline ?? Infinity) - 1000);
+    // this server routes every workflow task through the normal queue with its full history (a sticky
+    // queue is an optimization a server may skip); a sticky poll waits out its deadline
+    if (queue?.kind === 'TASK_QUEUE_KIND_STICKY') {
+      while (!signal.aborted && Date.now() < until && !this.closedSticky.has(name)) await this.wait(signal, until);
+      return {};
+    }
+    const identity = String(request.identity ?? '');
+    while (!signal.aborted) {
+      const task = await this.serial(() => this.takeWorkflowTask(namespace, name, identity));
+      if (task) return task;
+      if (Date.now() >= until) return {};
+      await this.wait(signal, until);
+    }
+    return {};
+  }
+
+  private async takeWorkflowTask(namespace: string, queue: string, identity: string): Promise<Obj | undefined> {
+    for (const query of this.queries.values()) {
+      if (query.dispatched || query.namespace !== namespace || query.taskQueue !== queue) continue;
+      const run = this.run(query.runId);
+      if (!run) continue;
+      query.dispatched = true;
+      const events = await this.history(run);
+      return {
+        taskToken: encodeToken({ kind: 'query', id: query.id }),
+        workflowExecution: run.execution,
+        workflowType: run.type,
+        previousStartedEventId: run._state.previousStartedEventId,
+        startedEventId: run._state.previousStartedEventId,
+        attempt: 1,
+        history: { events },
+        query: query.query,
+        workflowExecutionTaskQueue: { name: run.taskQueue, kind: 'TASK_QUEUE_KIND_NORMAL' },
+        scheduledTime: toTimestamp(nowMs()),
+        startedTime: toTimestamp(nowMs()),
+      };
+    }
+    const now = nowMs();
+    const ready = this.runs(namespace)
+      .filter((run) => run.status === RUNNING && run.taskQueue === queue && run._state.wft && run._state.wft.startedEventId === undefined && run._state.wft.availableAt <= now)
+      .sort((a, b) => a._state.wft!.scheduledAt - b._state.wft!.scheduledAt);
+    const run = ready[0];
+    if (!run) return undefined;
+    const tx = new RunTx(run, now);
+    const wft = tx.state.wft!;
+    const requestId = uuidFrom(`wft\0${run.id}\0${wft.scheduledEventId}\0${wft.attempt}`);
+    const startedEventId = tx.append('EVENT_TYPE_WORKFLOW_TASK_STARTED', 'workflowTaskStartedEventAttributes', {
+      scheduledEventId: wft.scheduledEventId, identity, requestId, historySizeBytes: tx.state.historyBytes,
+    });
+    wft.startedEventId = startedEventId;
+    wft.startedAt = now;
+    wft.timeoutAt = now + tx.state.workflowTaskTimeoutMs;
+    wft.identity = identity;
+    await this.commit(tx, 'PollWorkflowTaskQueue');
+    const events = await this.history(tx.run);
+    return {
+      taskToken: encodeToken({ kind: 'workflow', runId: run.id, scheduledEventId: wft.scheduledEventId, startedEventId, attempt: wft.attempt }),
+      workflowExecution: run.execution,
+      workflowType: run.type,
+      previousStartedEventId: tx.state.previousStartedEventId,
+      startedEventId,
+      attempt: wft.attempt,
+      history: { events },
+      workflowExecutionTaskQueue: { name: run.taskQueue, kind: 'TASK_QUEUE_KIND_NORMAL' },
+      scheduledTime: toTimestamp(wft.scheduledAt),
+      startedTime: toTimestamp(now),
+      queries: {},
+    };
+  }
+
+  /** The run and in-flight task a workflow task token names, or NOT_FOUND. */
+  private workflowTaskOf(token: Obj): Run {
+    const run = this.run(String(token.runId ?? ''));
+    const wft = run?._state.wft;
+    if (!run || run.status !== RUNNING || !wft || wft.startedEventId === undefined || wft.scheduledEventId !== token.scheduledEventId || wft.startedEventId !== token.startedEventId) {
+      throw new GrpcError(GrpcStatus.NOT_FOUND, 'Workflow task not found.');
+    }
+    return run;
+  }
+
+  async respondWorkflowTaskCompleted(request: Obj): Promise<Obj> {
+    this.assertWritable();
+    const token = decodeToken(request.taskToken, 'TaskToken');
+    if (token.kind !== 'workflow') throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, 'invalid TaskToken');
+    return this.serial(async () => {
+      const run = this.workflowTaskOf(token);
+      const now = nowMs();
+      const tx = new RunTx(run, now);
+      const wft = tx.state.wft!;
+      const commands = (request.commands ?? []) as Obj[];
+      const closing = commands.find((command) => CLOSING_COMMANDS.has(String(command.commandType)));
+      const messages = (request.messages ?? []) as unknown[];
+      if (messages.length > 0) {
+        await this.failWorkflowTask(tx, 'WORKFLOW_TASK_FAILED_CAUSE_FEATURE_DISABLED', 'this Temporal twin does not implement workflow updates (protocol messages)', String(request.identity ?? ''));
+        return {};
+      }
+      if (closing && tx.state.buffered.some((event) => event.wakes)) {
+        // new events arrived while the task ran: the workflow may not close over them
+        await this.failWorkflowTask(tx, 'WORKFLOW_TASK_FAILED_CAUSE_UNHANDLED_COMMAND', 'UnhandledCommand', String(request.identity ?? ''), { sameAttempt: true });
+        return {};
+      }
+      const checkpoint = JSON.stringify(tx.run);
+      const eventsBefore = tx.events.length;
+      const completedEventId = tx.append('EVENT_TYPE_WORKFLOW_TASK_COMPLETED', 'workflowTaskCompletedEventAttributes', {
+        scheduledEventId: wft.scheduledEventId,
+        startedEventId: wft.startedEventId,
+        identity: String(request.identity ?? ''),
+        ...(request.binaryChecksum ? { binaryChecksum: request.binaryChecksum } : {}),
+        ...(request.workerVersionStamp ? { workerVersion: request.workerVersionStamp } : {}),
+        ...(request.sdkMetadata ? { sdkMetadata: request.sdkMetadata } : {}),
+        ...(request.meteringMetadata ? { meteringMetadata: request.meteringMetadata } : {}),
+        ...(request.deployment ? { deployment: request.deployment } : {}),
+        ...(request.versioningBehavior ? { versioningBehavior: request.versioningBehavior } : {}),
+      });
+      tx.state.previousStartedEventId = wft.startedEventId!;
+      tx.state.wft = null;
+      const after: Array<() => Promise<void>> = [];
+      let closed: { status: string; eventId: number; newRun?: RunTx; continued?: boolean } | undefined;
+      let needsTask = Boolean(request.forceCreateNewWorkflowTask);
+      try {
+        for (const command of commands) {
+          if (closed) throw new UnhandledCommand('WORKFLOW_TASK_FAILED_CAUSE_UNHANDLED_COMMAND', `${String(command.commandType)} follows a command that closed the workflow`);
+          const result = this.applyCommand(tx, command, completedEventId, String(request.identity ?? ''), after);
+          if (result?.closed) closed = result.closed;
+          if (result?.wakes) needsTask = true;
+        }
+      } catch (error) {
+        if (!(error instanceof UnhandledCommand)) throw error;
+        // the commands are refused whole: restore the run as it stood and fail the task instead
+        const restored = JSON.parse(checkpoint) as Run;
+        const retry = new RunTx(restored, now);
+        tx.events.splice(eventsBefore);
+        await this.failWorkflowTask(retry, error.cause2, error.message, String(request.identity ?? ''));
+        return {};
+      }
+      if (closed) {
+        await this.closeRun(tx, closed.status, closed.eventId, 'RespondWorkflowTaskCompleted', undefined, { ...(closed.newRun ? { newRunId: closed.newRun.run.id } : {}), ...(closed.continued ? { continued: true } : {}) });
+        if (closed.newRun) await this.commit(closed.newRun, 'RespondWorkflowTaskCompleted');
+      } else {
+        if (tx.flushBuffered()) needsTask = true;
+        if (needsTask) tx.scheduleWorkflowTask();
+        await this.commit(tx, 'RespondWorkflowTaskCompleted');
+      }
+      for (const step of after) await step();
+      this.notify();
+      return {};
+    });
+  }
+
+  /** One command → its events (and, for cross-run effects, a step run after this run is written). */
+  private applyCommand(tx: RunTx, command: Obj, completedEventId: number, identity: string, after: Array<() => Promise<void>>): { closed?: { status: string; eventId: number; newRun?: RunTx; continued?: boolean }; wakes?: boolean } | undefined {
+    const type = String(command.commandType ?? '');
+    const run = tx.run;
+    const state = tx.state;
+    const now = tx.now;
+    switch (type) {
+      case 'COMMAND_TYPE_SCHEDULE_ACTIVITY_TASK': {
+        const a = (command.scheduleActivityTaskCommandAttributes ?? {}) as Obj;
+        const activityId = String(a.activityId ?? '');
+        const activityType = a.activityType as Obj | undefined;
+        if (!activityId || !activityType?.name) throw new UnhandledCommand('WORKFLOW_TASK_FAILED_CAUSE_BAD_SCHEDULE_ACTIVITY_ATTRIBUTES', 'ActivityId and ActivityType are required');
+        if (Object.values(state.activities).some((activity) => activity.activityId === activityId)) {
+          throw new UnhandledCommand('WORKFLOW_TASK_FAILED_CAUSE_SCHEDULE_ACTIVITY_DUPLICATE_ID', `Duplicate activity ID: ${activityId}`);
+        }
+        const taskQueue = String((a.taskQueue as Obj | undefined)?.name || run.taskQueue);
+        let scheduleToClose = durationMs(a.scheduleToCloseTimeout);
+        let scheduleToStart = durationMs(a.scheduleToStartTimeout);
+        let startToClose = durationMs(a.startToCloseTimeout);
+        let heartbeat = durationMs(a.heartbeatTimeout);
+        if (!scheduleToClose && !startToClose) throw new UnhandledCommand('WORKFLOW_TASK_FAILED_CAUSE_BAD_SCHEDULE_ACTIVITY_ATTRIBUTES', 'A valid StartToClose or ScheduleToCloseTimeout is not set on ScheduleActivityTaskCommand.');
+        const runLeft = state.runExpiresAt ? state.runExpiresAt - now : 0;
+        if (!scheduleToClose && runLeft > 0) scheduleToClose = runLeft;
+        if (runLeft > 0 && scheduleToClose > runLeft) scheduleToClose = runLeft;
+        if (!scheduleToStart || (scheduleToClose && scheduleToStart > scheduleToClose)) scheduleToStart = scheduleToClose;
+        if (!startToClose || (scheduleToClose && startToClose > scheduleToClose)) startToClose = scheduleToClose;
+        if (heartbeat > startToClose) heartbeat = startToClose;
+        const given = a.retryPolicy as RetryPolicy | undefined;
+        if (given?.backoffCoefficient !== undefined && given.backoffCoefficient !== 0 && given.backoffCoefficient < 1) {
+          throw new UnhandledCommand('WORKFLOW_TASK_FAILED_CAUSE_BAD_SCHEDULE_ACTIVITY_ATTRIBUTES', 'BackoffCoefficient cannot be less than 1.');
+        }
+        const retryPolicy = activityRetryPolicy(given);
+        const scheduledEventId = tx.append('EVENT_TYPE_ACTIVITY_TASK_SCHEDULED', 'activityTaskScheduledEventAttributes', {
+          activityId, activityType, taskQueue: { name: taskQueue, kind: 'TASK_QUEUE_KIND_NORMAL' },
+          ...(a.header ? { header: a.header } : {}), ...(a.input ? { input: a.input } : {}),
+          scheduleToCloseTimeout: toDuration(scheduleToClose), scheduleToStartTimeout: toDuration(scheduleToStart),
+          startToCloseTimeout: toDuration(startToClose), heartbeatTimeout: toDuration(heartbeat),
+          workflowTaskCompletedEventId: completedEventId, retryPolicy,
+          ...(a.useWorkflowBuildId ? { useWorkflowBuildId: a.useWorkflowBuildId } : {}),
+          ...(a.priority ? { priority: a.priority } : {}),
+        });
+        state.activities[String(scheduledEventId)] = {
+          scheduledEventId, activityId, activityType, taskQueue, retryPolicy,
+          ...(a.input ? { input: a.input as Obj } : {}), ...(a.header ? { header: a.header as Obj } : {}), ...(a.priority ? { priority: a.priority as Obj } : {}),
+          scheduleToCloseMs: scheduleToClose, scheduleToStartMs: scheduleToStart, startToCloseMs: startToClose, heartbeatMs: heartbeat,
+          attempt: 1, scheduledAt: now, attemptScheduledAt: now, availableAt: now,
+        };
+        tx.wakeQueues = true;
+        return undefined;
+      }
+      case 'COMMAND_TYPE_REQUEST_CANCEL_ACTIVITY_TASK': {
+        const a = (command.requestCancelActivityTaskCommandAttributes ?? {}) as Obj;
+        const activity = state.activities[String(a.scheduledEventId)];
+        if (!activity) throw new UnhandledCommand('WORKFLOW_TASK_FAILED_CAUSE_BAD_REQUEST_CANCEL_ACTIVITY_ATTRIBUTES', `Unable to find activity with scheduled event ID ${String(a.scheduledEventId)}`);
+        const requestedId = tx.append('EVENT_TYPE_ACTIVITY_TASK_CANCEL_REQUESTED', 'activityTaskCancelRequestedEventAttributes', { scheduledEventId: activity.scheduledEventId, workflowTaskCompletedEventId: completedEventId });
+        if (activity.startedAt === undefined) {
+          tx.append('EVENT_TYPE_ACTIVITY_TASK_CANCELED', 'activityTaskCanceledEventAttributes', { scheduledEventId: activity.scheduledEventId, latestCancelRequestedEventId: requestedId, identity });
+          delete state.activities[String(activity.scheduledEventId)];
+          return { wakes: true };
+        }
+        activity.cancelRequestedEventId = requestedId;
+        return undefined;
+      }
+      case 'COMMAND_TYPE_START_TIMER': {
+        const a = (command.startTimerCommandAttributes ?? {}) as Obj;
+        const timerId = String(a.timerId ?? '');
+        const fireMs = durationMs(a.startToFireTimeout);
+        if (!timerId || fireMs <= 0) throw new UnhandledCommand('WORKFLOW_TASK_FAILED_CAUSE_BAD_START_TIMER_ATTRIBUTES', 'A valid TimerId and StartToFireTimeout are required');
+        if (state.timers[timerId]) throw new UnhandledCommand('WORKFLOW_TASK_FAILED_CAUSE_START_TIMER_DUPLICATE_ID', `TimerId ${timerId} is already in use`);
+        const startedEventId = tx.append('EVENT_TYPE_TIMER_STARTED', 'timerStartedEventAttributes', { timerId, startToFireTimeout: a.startToFireTimeout, workflowTaskCompletedEventId: completedEventId });
+        state.timers[timerId] = { startedEventId, fireAt: now + fireMs };
+        return undefined;
+      }
+      case 'COMMAND_TYPE_CANCEL_TIMER': {
+        const a = (command.cancelTimerCommandAttributes ?? {}) as Obj;
+        const timerId = String(a.timerId ?? '');
+        const timer = state.timers[timerId];
+        if (!timer) throw new UnhandledCommand('WORKFLOW_TASK_FAILED_CAUSE_BAD_CANCEL_TIMER_ATTRIBUTES', `TimerId ${timerId} is not open`);
+        tx.append('EVENT_TYPE_TIMER_CANCELED', 'timerCanceledEventAttributes', { timerId, startedEventId: timer.startedEventId, workflowTaskCompletedEventId: completedEventId, identity });
+        delete state.timers[timerId];
+        return undefined;
+      }
+      case 'COMMAND_TYPE_RECORD_MARKER': {
+        const a = (command.recordMarkerCommandAttributes ?? {}) as Obj;
+        if (!a.markerName) throw new UnhandledCommand('WORKFLOW_TASK_FAILED_CAUSE_BAD_RECORD_MARKER_ATTRIBUTES', 'MarkerName is not set on RecordMarkerCommand.');
+        tx.append('EVENT_TYPE_MARKER_RECORDED', 'markerRecordedEventAttributes', { ...a, workflowTaskCompletedEventId: completedEventId });
+        return undefined;
+      }
+      case 'COMMAND_TYPE_UPSERT_WORKFLOW_SEARCH_ATTRIBUTES': {
+        const a = (command.upsertWorkflowSearchAttributesCommandAttributes ?? {}) as Obj;
+        try {
+          this.validateSearchAttributes(run.namespace, a.searchAttributes, true);
+        } catch (error) {
+          this.workerError((error as Error).message);
+        }
+        tx.append('EVENT_TYPE_UPSERT_WORKFLOW_SEARCH_ATTRIBUTES', 'upsertWorkflowSearchAttributesEventAttributes', { searchAttributes: a.searchAttributes, workflowTaskCompletedEventId: completedEventId });
+        run.searchAttributes = { indexedFields: mergeFields(run.searchAttributes?.indexedFields, (a.searchAttributes as Obj | undefined)?.indexedFields as Record<string, Obj> | undefined) };
+        return undefined;
+      }
+      case 'COMMAND_TYPE_MODIFY_WORKFLOW_PROPERTIES': {
+        const a = (command.modifyWorkflowPropertiesCommandAttributes ?? {}) as Obj;
+        tx.append('EVENT_TYPE_WORKFLOW_PROPERTIES_MODIFIED', 'workflowPropertiesModifiedEventAttributes', { upsertedMemo: a.upsertedMemo, workflowTaskCompletedEventId: completedEventId });
+        run.memo = { fields: mergeFields(run.memo?.fields, (a.upsertedMemo as Obj | undefined)?.fields as Record<string, Obj> | undefined) };
+        return undefined;
+      }
+      case 'COMMAND_TYPE_COMPLETE_WORKFLOW_EXECUTION': {
+        const a = (command.completeWorkflowExecutionCommandAttributes ?? {}) as Obj;
+        const eventId = tx.append('EVENT_TYPE_WORKFLOW_EXECUTION_COMPLETED', 'workflowExecutionCompletedEventAttributes', { ...(a.result ? { result: a.result } : {}), workflowTaskCompletedEventId: completedEventId });
+        return { closed: { status: 'WORKFLOW_EXECUTION_STATUS_COMPLETED', eventId } };
+      }
+      case 'COMMAND_TYPE_FAIL_WORKFLOW_EXECUTION': {
+        const a = (command.failWorkflowExecutionCommandAttributes ?? {}) as Obj;
+        const decision = decideRetry(state.retryPolicy, state.attempt, a.failure as Obj | undefined, now, state.executionExpiresAt);
+        if (decision.retry) {
+          const next = this.nextRunOf(tx, { backoffMs: decision.delayMs, attempt: state.attempt + 1, initiator: 'CONTINUE_AS_NEW_INITIATOR_RETRY', continuedFailure: a.failure as Obj | undefined });
+          const eventId = tx.append('EVENT_TYPE_WORKFLOW_EXECUTION_FAILED', 'workflowExecutionFailedEventAttributes', { failure: a.failure, retryState: 'RETRY_STATE_IN_PROGRESS', workflowTaskCompletedEventId: completedEventId, newExecutionRunId: next.run.id });
+          return { closed: { status: 'WORKFLOW_EXECUTION_STATUS_FAILED', eventId, newRun: next } };
+        }
+        const eventId = tx.append('EVENT_TYPE_WORKFLOW_EXECUTION_FAILED', 'workflowExecutionFailedEventAttributes', { failure: a.failure, retryState: decision.state, workflowTaskCompletedEventId: completedEventId });
+        return { closed: { status: 'WORKFLOW_EXECUTION_STATUS_FAILED', eventId } };
+      }
+      case 'COMMAND_TYPE_CANCEL_WORKFLOW_EXECUTION': {
+        const a = (command.cancelWorkflowExecutionCommandAttributes ?? {}) as Obj;
+        const eventId = tx.append('EVENT_TYPE_WORKFLOW_EXECUTION_CANCELED', 'workflowExecutionCanceledEventAttributes', { ...(a.details ? { details: a.details } : {}), workflowTaskCompletedEventId: completedEventId });
+        return { closed: { status: 'WORKFLOW_EXECUTION_STATUS_CANCELED', eventId } };
+      }
+      case 'COMMAND_TYPE_CONTINUE_AS_NEW_WORKFLOW_EXECUTION': {
+        const a = (command.continueAsNewWorkflowExecutionCommandAttributes ?? {}) as Obj;
+        if (a.cronSchedule) throw new UnhandledCommand('WORKFLOW_TASK_FAILED_CAUSE_FEATURE_DISABLED', 'this Temporal twin does not run cron schedules (CronSchedule on ContinueAsNew)');
+        try {
+          this.validateSearchAttributes(run.namespace, a.searchAttributes, true);
+        } catch (error) {
+          this.workerError((error as Error).message);
+        }
+        const backoffMs = durationMs(a.backoffStartInterval);
+        const next = this.nextRunOf(tx, {
+          backoffMs, attempt: 1, initiator: 'CONTINUE_AS_NEW_INITIATOR_WORKFLOW',
+          ...(a.workflowType && (a.workflowType as Obj).name ? { workflowType: a.workflowType as Obj } : {}),
+          ...((a.taskQueue as Obj | undefined)?.name ? { taskQueue: String((a.taskQueue as Obj).name) } : {}),
+          input: a.input as Obj | undefined,
+          ...(a.header ? { header: a.header as Obj } : {}),
+          ...(durationMs(a.workflowRunTimeout) ? { runTimeoutMs: durationMs(a.workflowRunTimeout) } : {}),
+          ...(durationMs(a.workflowTaskTimeout) ? { workflowTaskTimeoutMs: durationMs(a.workflowTaskTimeout) } : {}),
+          ...(a.memo ? { memo: a.memo as Obj } : {}),
+          ...(a.searchAttributes ? { searchAttributes: a.searchAttributes as Obj } : {}),
+          ...(a.retryPolicy ? { retryPolicy: a.retryPolicy as RetryPolicy } : {}),
+          ...(a.lastCompletionResult ? { lastCompletionResult: a.lastCompletionResult as Obj } : {}),
+        });
+        const eventId = tx.append('EVENT_TYPE_WORKFLOW_EXECUTION_CONTINUED_AS_NEW', 'workflowExecutionContinuedAsNewEventAttributes', {
+          newExecutionRunId: next.run.id,
+          workflowType: next.run.type,
+          taskQueue: { name: next.run.taskQueue, kind: 'TASK_QUEUE_KIND_NORMAL' },
+          ...(a.input ? { input: a.input } : {}),
+          workflowRunTimeout: toDuration(next.state.runTimeoutMs),
+          workflowTaskTimeout: toDuration(next.state.workflowTaskTimeoutMs),
+          workflowTaskCompletedEventId: completedEventId,
+          ...(backoffMs ? { backoffStartInterval: toDuration(backoffMs) } : {}),
+          initiator: 'CONTINUE_AS_NEW_INITIATOR_WORKFLOW',
+          ...(a.header ? { header: a.header } : {}),
+          ...(next.run.memo ? { memo: next.run.memo } : {}),
+          ...(next.run.searchAttributes ? { searchAttributes: next.run.searchAttributes } : {}),
+        });
+        return { closed: { status: 'WORKFLOW_EXECUTION_STATUS_CONTINUED_AS_NEW', eventId, newRun: next, continued: true } };
+      }
+      case 'COMMAND_TYPE_START_CHILD_WORKFLOW_EXECUTION': {
+        const a = (command.startChildWorkflowExecutionCommandAttributes ?? {}) as Obj;
+        const childNamespace = String(a.namespace || run.namespace);
+        const workflowId = String(a.workflowId ?? '');
+        if (!workflowId || !(a.workflowType as Obj | undefined)?.name) throw new UnhandledCommand('WORKFLOW_TASK_FAILED_CAUSE_BAD_START_CHILD_EXECUTION_ATTRIBUTES', 'WorkflowId and WorkflowType are required');
+        if (a.cronSchedule) throw new UnhandledCommand('WORKFLOW_TASK_FAILED_CAUSE_FEATURE_DISABLED', 'this Temporal twin does not run cron schedules (CronSchedule on a child)');
+        try {
+          this.namespace(childNamespace);
+          this.validateSearchAttributes(childNamespace, a.searchAttributes, false);
+        } catch (error) {
+          throw new UnhandledCommand('WORKFLOW_TASK_FAILED_CAUSE_BAD_START_CHILD_EXECUTION_ATTRIBUTES', (error as Error).message);
+        }
+        const parentClosePolicy = String(a.parentClosePolicy && a.parentClosePolicy !== 'PARENT_CLOSE_POLICY_UNSPECIFIED' ? a.parentClosePolicy : 'PARENT_CLOSE_POLICY_TERMINATE');
+        const taskQueue = String((a.taskQueue as Obj | undefined)?.name || run.taskQueue);
+        const initiatedEventId = tx.append('EVENT_TYPE_START_CHILD_WORKFLOW_EXECUTION_INITIATED', 'startChildWorkflowExecutionInitiatedEventAttributes', {
+          ...a, namespace: childNamespace, namespaceId: String((this.namespace(childNamespace).namespaceInfo as Obj).id), taskQueue: { name: taskQueue, kind: 'TASK_QUEUE_KIND_NORMAL' },
+          parentClosePolicy, workflowTaskCompletedEventId: completedEventId,
+        });
+        state.children[String(initiatedEventId)] = { initiatedEventId, namespace: childNamespace, workflowId, workflowType: a.workflowType as Obj, parentClosePolicy };
+        after.push(() => this.startChild(run.id, initiatedEventId, { ...a, taskQueue: { name: taskQueue } }, childNamespace, completedEventId));
+        return undefined;
+      }
+      case 'COMMAND_TYPE_SIGNAL_EXTERNAL_WORKFLOW_EXECUTION': {
+        const a = (command.signalExternalWorkflowExecutionCommandAttributes ?? {}) as Obj;
+        const targetNamespace = String(a.namespace || run.namespace);
+        const initiatedEventId = tx.append('EVENT_TYPE_SIGNAL_EXTERNAL_WORKFLOW_EXECUTION_INITIATED', 'signalExternalWorkflowExecutionInitiatedEventAttributes', {
+          namespace: targetNamespace, workflowExecution: a.execution, signalName: a.signalName, ...(a.input ? { input: a.input } : {}),
+          ...(a.control ? { control: a.control } : {}), childWorkflowOnly: Boolean(a.childWorkflowOnly), ...(a.header ? { header: a.header } : {}),
+          workflowTaskCompletedEventId: completedEventId,
+        });
+        after.push(() => this.signalExternal(run.id, initiatedEventId, targetNamespace, a, completedEventId));
+        return undefined;
+      }
+      case 'COMMAND_TYPE_REQUEST_CANCEL_EXTERNAL_WORKFLOW_EXECUTION': {
+        const a = (command.requestCancelExternalWorkflowExecutionCommandAttributes ?? {}) as Obj;
+        const targetNamespace = String(a.namespace || run.namespace);
+        const execution = { workflowId: String(a.workflowId ?? ''), ...(a.runId ? { runId: String(a.runId) } : {}) };
+        const initiatedEventId = tx.append('EVENT_TYPE_REQUEST_CANCEL_EXTERNAL_WORKFLOW_EXECUTION_INITIATED', 'requestCancelExternalWorkflowExecutionInitiatedEventAttributes', {
+          namespace: targetNamespace, workflowExecution: execution, ...(a.control ? { control: a.control } : {}), childWorkflowOnly: Boolean(a.childWorkflowOnly),
+          ...(a.reason ? { reason: a.reason } : {}), workflowTaskCompletedEventId: completedEventId,
+        });
+        after.push(() => this.cancelExternal(run.id, initiatedEventId, targetNamespace, execution, a, completedEventId));
+        return undefined;
+      }
+      default:
+        throw new UnhandledCommand('WORKFLOW_TASK_FAILED_CAUSE_FEATURE_DISABLED', `this Temporal twin does not implement ${type || 'an unspecified command'}`);
+    }
+  }
+
+  /** The run a continue-as-new or a retry hands the workflow to (built now, written after this run). */
+  private nextRunOf(tx: RunTx, next: { backoffMs: number; attempt: number; initiator: string; continuedFailure?: Obj; workflowType?: Obj; taskQueue?: string; input?: Obj; header?: Obj; runTimeoutMs?: number; workflowTaskTimeoutMs?: number; memo?: Obj; searchAttributes?: Obj; retryPolicy?: RetryPolicy; lastCompletionResult?: Obj }): RunTx {
+    const run = tx.run;
+    const state = tx.state;
+    const input = next.initiator === 'CONTINUE_AS_NEW_INITIATOR_RETRY' ? state.input : next.input;
+    const header = next.header ?? state.header;
+    const memo = next.memo ?? run.memo;
+    const searchAttributes = next.searchAttributes ?? run.searchAttributes;
+    const retryPolicy = next.retryPolicy ?? state.retryPolicy;
+    return this.newRun(tx.now, {
+      namespace: run.namespace,
+      workflowId: run.execution.workflowId,
+      workflowType: next.workflowType ?? run.type,
+      taskQueue: next.taskQueue ?? run.taskQueue,
+      ...(input ? { input } : {}),
+      ...(header ? { header } : {}),
+      ...(memo ? { memo } : {}),
+      ...(searchAttributes ? { searchAttributes } : {}),
+      executionTimeoutMs: state.executionTimeoutMs,
+      runTimeoutMs: next.runTimeoutMs ?? state.runTimeoutMs,
+      workflowTaskTimeoutMs: next.workflowTaskTimeoutMs ?? state.workflowTaskTimeoutMs,
+      ...(retryPolicy ? { retryPolicy } : {}),
+      attempt: next.attempt,
+      ...(state.parent ? { parent: state.parent } : {}),
+      ...(run.rootExecution ? { rootExecution: run.rootExecution } : {}),
+      firstRunId: run.firstRunId,
+      continuedExecutionRunId: run.id,
+      initiator: next.initiator,
+      ...(next.continuedFailure ? { continuedFailure: next.continuedFailure } : {}),
+      ...(next.lastCompletionResult ? { lastCompletionResult: next.lastCompletionResult } : {}),
+      backoffMs: next.backoffMs,
+      ...(state.executionExpiresAt ? { executionExpiresAt: state.executionExpiresAt } : {}),
+      seed: `continue\0${run.id}`,
+    });
+  }
+
+  private async startChild(parentRunId: string, initiatedEventId: number, a: Obj, namespace: string, completedEventId: number): Promise<void> {
+    const parent = this.run(parentRunId);
+    if (!parent) return;
+    // a parent that closed in the same task (a close command after the start) starts no child, whatever
+    // its parent-close policy: the server's transfer task refuses a start for a closed parent
+    // (history service, processStartChildExecution), and the parent's history ends at its close event
+    if (parent.status !== RUNNING) return;
+    const parentOpen = true;
+    const now = nowMs();
+    const workflowId = String(a.workflowId);
+    const current = latest(this.runs(namespace).filter((run) => run.execution.workflowId === workflowId));
+    const reuse = String(a.workflowIdReusePolicy ?? 'WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE');
+    const refused = current && (current.status === RUNNING
+      || reuse === 'WORKFLOW_ID_REUSE_POLICY_REJECT_DUPLICATE'
+      || (reuse === 'WORKFLOW_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY' && current.status === 'WORKFLOW_EXECUTION_STATUS_COMPLETED'));
+    const parentTx = new RunTx(parent, now);
+    if (refused) {
+      if (!parentOpen) return;
+      delete parentTx.state.children[String(initiatedEventId)];
+      parentTx.deliver('EVENT_TYPE_START_CHILD_WORKFLOW_EXECUTION_FAILED', 'startChildWorkflowExecutionFailedEventAttributes', {
+        namespace, namespaceId: String((this.namespace(namespace).namespaceInfo as Obj).id), workflowId, workflowType: a.workflowType,
+        cause: 'START_CHILD_WORKFLOW_EXECUTION_FAILED_CAUSE_WORKFLOW_ALREADY_EXISTS', ...(a.control ? { control: a.control } : {}),
+        initiatedEventId, workflowTaskCompletedEventId: completedEventId,
+      });
+      await this.commit(parentTx, 'StartChildWorkflowExecution');
+      return;
+    }
+    const executionTimeoutMs = durationMs(a.workflowExecutionTimeout);
+    let runTimeoutMs = durationMs(a.workflowRunTimeout);
+    if (executionTimeoutMs && (!runTimeoutMs || runTimeoutMs > executionTimeoutMs)) runTimeoutMs = executionTimeoutMs;
+    const childTx = this.newRun(now, {
+      namespace, workflowId, workflowType: a.workflowType as Obj, taskQueue: String((a.taskQueue as Obj).name),
+      ...(a.input ? { input: a.input as Obj } : {}), ...(a.header ? { header: a.header as Obj } : {}), ...(a.memo ? { memo: a.memo as Obj } : {}),
+      ...(a.searchAttributes ? { searchAttributes: a.searchAttributes as Obj } : {}), ...(a.retryPolicy ? { retryPolicy: a.retryPolicy as RetryPolicy } : {}),
+      ...(a.priority ? { priority: a.priority as Obj } : {}),
+      executionTimeoutMs, runTimeoutMs,
+      workflowTaskTimeoutMs: Math.min(durationMs(a.workflowTaskTimeout) || DEFAULT_WFT_TIMEOUT_MS, MAX_WFT_TIMEOUT_MS, runTimeoutMs || MAX_WFT_TIMEOUT_MS),
+      parent: { namespace: parent.namespace, workflowId: parent.execution.workflowId, runId: parent.id, initiatedEventId },
+      rootExecution: parent.rootExecution ?? parent.execution,
+      seed: `child\0${parent.id}\0${initiatedEventId}`,
+    });
+    await this.commit(childTx, 'StartChildWorkflowExecution');
+    if (!parentOpen) return;
+    const startedAttrs = {
+      namespace, namespaceId: String((this.namespace(namespace).namespaceInfo as Obj).id), initiatedEventId,
+      workflowExecution: childTx.run.execution, workflowType: childTx.run.type, ...(a.header ? { header: a.header } : {}),
+    };
+    const pending = parentTx.state.children[String(initiatedEventId)];
+    if (pending) pending.runId = childTx.run.id;
+    // the started event's id lands on the pending child when the event itself lands (RunTx.land)
+    parentTx.deliver('EVENT_TYPE_CHILD_WORKFLOW_EXECUTION_STARTED', 'childWorkflowExecutionStartedEventAttributes', startedAttrs);
+    await this.commit(parentTx, 'StartChildWorkflowExecution');
+  }
+
+  private async signalExternal(runId: string, initiatedEventId: number, namespace: string, a: Obj, completedEventId: number): Promise<void> {
+    const source = this.run(runId);
+    // a source that closed in the same task (a close command after this one) sends nothing: its
+    // history ends at the close event, and the server drops the pending transfer
+    if (!source || source.status !== RUNNING) return;
+    const now = nowMs();
+    const execution = (a.execution ?? {}) as { workflowId?: string; runId?: string };
+    let target: Run | undefined;
+    try {
+      target = this.resolveRun(namespace, execution);
+    } catch { target = undefined; }
+    if (a.childWorkflowOnly && target && target._state.parent?.runId !== source.id) target = undefined;
+    const sourceTx = new RunTx(source, now);
+    if (!target || target.status !== RUNNING) {
+      sourceTx.deliver('EVENT_TYPE_SIGNAL_EXTERNAL_WORKFLOW_EXECUTION_FAILED', 'signalExternalWorkflowExecutionFailedEventAttributes', {
+        cause: 'SIGNAL_EXTERNAL_WORKFLOW_EXECUTION_FAILED_CAUSE_EXTERNAL_WORKFLOW_EXECUTION_NOT_FOUND', namespace,
+        namespaceId: String((this.namespace(namespace).namespaceInfo as Obj).id), workflowExecution: execution, initiatedEventId,
+        ...(a.control ? { control: a.control } : {}), workflowTaskCompletedEventId: completedEventId,
+      });
+      await this.commit(sourceTx, 'SignalExternalWorkflowExecution');
+      return;
+    }
+    const targetTx = new RunTx(target, now);
+    this.signalInto(targetTx, { signalName: String(a.signalName), input: a.input as Obj | undefined, header: a.header as Obj | undefined, identity: '', external: source.execution });
+    await this.commit(targetTx, 'SignalExternalWorkflowExecution');
+    // the source re-read after the target's write: a workflow that signals itself is both
+    const signaledTx = target.id === source.id ? new RunTx(this.run(source.id)!, now) : sourceTx;
+    signaledTx.deliver('EVENT_TYPE_EXTERNAL_WORKFLOW_EXECUTION_SIGNALED', 'externalWorkflowExecutionSignaledEventAttributes', {
+      initiatedEventId, namespace, namespaceId: String((this.namespace(namespace).namespaceInfo as Obj).id), workflowExecution: target.execution, ...(a.control ? { control: a.control } : {}),
+    });
+    await this.commit(signaledTx, 'SignalExternalWorkflowExecution');
+  }
+
+  private async cancelExternal(runId: string, initiatedEventId: number, namespace: string, execution: { workflowId: string; runId?: string }, a: Obj, completedEventId: number): Promise<void> {
+    const source = this.run(runId);
+    // a source that closed in the same task (a close command after this one) sends nothing: its
+    // history ends at the close event, and the server drops the pending transfer
+    if (!source || source.status !== RUNNING) return;
+    const now = nowMs();
+    let target: Run | undefined;
+    try {
+      target = this.resolveRun(namespace, execution);
+    } catch { target = undefined; }
+    if (a.childWorkflowOnly && target && target._state.parent?.runId !== source.id) target = undefined;
+    const sourceTx = new RunTx(source, now);
+    if (!target || target.status !== RUNNING) {
+      sourceTx.deliver('EVENT_TYPE_REQUEST_CANCEL_EXTERNAL_WORKFLOW_EXECUTION_FAILED', 'requestCancelExternalWorkflowExecutionFailedEventAttributes', {
+        cause: 'CANCEL_EXTERNAL_WORKFLOW_EXECUTION_FAILED_CAUSE_EXTERNAL_WORKFLOW_EXECUTION_NOT_FOUND', namespace,
+        namespaceId: String((this.namespace(namespace).namespaceInfo as Obj).id), workflowExecution: execution, initiatedEventId,
+        ...(a.control ? { control: a.control } : {}), workflowTaskCompletedEventId: completedEventId,
+      });
+      await this.commit(sourceTx, 'RequestCancelExternalWorkflowExecution');
+      return;
+    }
+    if (!target._state.cancelRequested) {
+      const targetTx = new RunTx(target, now);
+      this.cancelRequestInto(targetTx, { ...(a.reason ? { cause: String(a.reason) } : {}), externalInitiatedEventId: initiatedEventId, externalWorkflowExecution: source.execution });
+      await this.commit(targetTx, 'RequestCancelExternalWorkflowExecution');
+    }
+    // the source re-read after the target's write: a workflow that cancels itself is both
+    const requestedTx = target.id === source.id ? new RunTx(this.run(source.id)!, now) : sourceTx;
+    requestedTx.deliver('EVENT_TYPE_EXTERNAL_WORKFLOW_EXECUTION_CANCEL_REQUESTED', 'externalWorkflowExecutionCancelRequestedEventAttributes', {
+      initiatedEventId, namespace, namespaceId: String((this.namespace(namespace).namespaceInfo as Obj).id), workflowExecution: target.execution,
+    });
+    await this.commit(requestedTx, 'RequestCancelExternalWorkflowExecution');
+  }
+
+  /** Fail the in-flight workflow task and schedule the next attempt. */
+  private async failWorkflowTask(tx: RunTx, cause: string, message: string, identity: string, options: { sameAttempt?: boolean; failure?: Obj; operation?: string } = {}): Promise<void> {
+    const wft = tx.state.wft!;
+    tx.append('EVENT_TYPE_WORKFLOW_TASK_FAILED', 'workflowTaskFailedEventAttributes', {
+      scheduledEventId: wft.scheduledEventId, startedEventId: wft.startedEventId, cause,
+      failure: options.failure ?? { message, source: 'temporal-twin', serverFailureInfo: { nonRetryable: false } },
+      identity,
+    });
+    tx.state.wft = null;
+    tx.flushBuffered();
+    const attempt = options.sameAttempt ? 1 : wft.attempt + 1;
+    // a task that keeps failing is retried with a growing delay, as the server backs off its retries
+    tx.scheduleWorkflowTask(attempt, attempt <= 2 ? 0 : Math.min(1000 * 2 ** (attempt - 3), 10 * 60_000));
+    await this.commit(tx, options.operation ?? 'RespondWorkflowTaskFailed');
+    this.notify();
+  }
+
+  async respondWorkflowTaskFailed(request: Obj): Promise<Obj> {
+    this.assertWritable();
+    const token = decodeToken(request.taskToken, 'TaskToken');
+    if (token.kind !== 'workflow') throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, 'invalid TaskToken');
+    return this.serial(async () => {
+      const run = this.workflowTaskOf(token);
+      const tx = new RunTx(run, nowMs());
+      await this.failWorkflowTask(tx, String(request.cause ?? 'WORKFLOW_TASK_FAILED_CAUSE_UNSPECIFIED'), '', String(request.identity ?? ''), request.failure ? { failure: request.failure as Obj } : {});
+      return {};
+    });
+  }
+
+  // ---- queries -------------------------------------------------------------------------------------
+
+  async queryWorkflow(request: Obj, signal: AbortSignal, deadline?: number): Promise<Obj> {
+    const namespace = this.requireNamespace(request.namespace);
+    const run = this.resolveRun(namespace, request.execution as Obj);
+    const reject = String(request.queryRejectCondition ?? '');
+    if (reject === 'QUERY_REJECT_CONDITION_NOT_OPEN' && run.status !== RUNNING) return { queryRejected: { status: run.status } };
+    if (reject === 'QUERY_REJECT_CONDITION_NOT_COMPLETED_CLEANLY' && run.status !== RUNNING && run.status !== 'WORKFLOW_EXECUTION_STATUS_COMPLETED') return { queryRejected: { status: run.status } };
+    if (run._state.previousStartedEventId === 0) {
+      throw new GrpcError(GrpcStatus.FAILED_PRECONDITION, 'Cannot query workflow before the first workflow task completes.');
+    }
+    this.querySeq += 1;
+    const id = `q${this.querySeq}`;
+    const answer = new Promise<Obj>((resolve, rejectQuery) => {
+      this.queries.set(id, { id, namespace, runId: run.id, taskQueue: run.taskQueue, query: request.query as Obj, resolve, reject: rejectQuery, dispatched: false });
+    });
+    this.notify();
+    const until = Math.min(Date.now() + LONG_POLL_MS, (deadline ?? Infinity) - 500);
+    const timeout = new Promise<never>((_, rejectTimeout) => {
+      const timer = setTimeout(() => rejectTimeout(new GrpcError(GrpcStatus.DEADLINE_EXCEEDED, 'query timed out before a worker answered it')), Math.max(0, until - Date.now()));
+      signal.addEventListener('abort', () => { clearTimeout(timer); rejectTimeout(new GrpcError(GrpcStatus.CANCELLED, 'query canceled')); }, { once: true });
+      void answer.finally(() => clearTimeout(timer)).catch(() => undefined);
+    });
+    try {
+      return await Promise.race([answer, timeout]);
+    } finally {
+      this.queries.delete(id);
+    }
+  }
+
+  async respondQueryTaskCompleted(request: Obj): Promise<Obj> {
+    const token = decodeToken(request.taskToken, 'TaskToken');
+    const query = token.kind === 'query' ? this.queries.get(String(token.id)) : undefined;
+    if (!query) throw new GrpcError(GrpcStatus.NOT_FOUND, 'query task not found, or already expired');
+    this.queries.delete(query.id);
+    if (request.completedType === 'QUERY_RESULT_TYPE_ANSWERED') query.resolve({ queryResult: request.queryResult ?? { payloads: [] } });
+    else query.reject(new GrpcError(GrpcStatus.INVALID_ARGUMENT, String(request.errorMessage || (request.failure as Obj | undefined)?.message || 'query failed')));
+    return {};
+  }
+
+  // ---- activity tasks ------------------------------------------------------------------------------
+
+  async pollActivityTaskQueue(request: Obj, signal: AbortSignal, deadline?: number): Promise<Obj> {
+    const namespace = this.requireNamespace(request.namespace);
+    const name = String((request.taskQueue as Obj | undefined)?.name ?? '');
+    if (!name) throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, 'TaskQueue is not set on request.');
+    const identity = String(request.identity ?? '');
+    const until = Math.min(Date.now() + LONG_POLL_MS, (deadline ?? Infinity) - 1000);
+    while (!signal.aborted) {
+      const task = await this.serial(() => this.takeActivityTask(namespace, name, identity));
+      if (task) return task;
+      if (Date.now() >= until) return {};
+      await this.wait(signal, until);
+    }
+    return {};
+  }
+
+  private async takeActivityTask(namespace: string, queue: string, identity: string): Promise<Obj | undefined> {
+    const now = nowMs();
+    let best: { run: Run; activity: ActivityState } | undefined;
+    for (const run of this.runs(namespace)) {
+      if (run.status !== RUNNING) continue;
+      for (const activity of Object.values(run._state.activities)) {
+        if (activity.taskQueue !== queue || activity.startedAt !== undefined || activity.availableAt > now) continue;
+        if (!best || activity.availableAt < best.activity.availableAt) best = { run, activity };
+      }
+    }
+    if (!best) return undefined;
+    const tx = new RunTx(best.run, now);
+    const activity = tx.state.activities[String(best.activity.scheduledEventId)]!;
+    activity.startedAt = now;
+    activity.identity = identity;
+    activity.requestId = uuidFrom(`activity\0${best.run.id}\0${activity.scheduledEventId}\0${activity.attempt}`);
+    activity.lastHeartbeatAt = undefined;
+    await this.commit(tx, 'PollActivityTaskQueue');
+    return {
+      taskToken: encodeToken({ kind: 'activity', runId: best.run.id, scheduledEventId: activity.scheduledEventId, attempt: activity.attempt }),
+      workflowNamespace: namespace,
+      workflowType: best.run.type,
+      workflowExecution: best.run.execution,
+      activityType: activity.activityType,
+      activityId: activity.activityId,
+      ...(activity.header ? { header: activity.header } : {}),
+      ...(activity.input ? { input: activity.input } : {}),
+      ...(activity.heartbeatDetails ? { heartbeatDetails: activity.heartbeatDetails } : {}),
+      scheduledTime: toTimestamp(activity.scheduledAt),
+      currentAttemptScheduledTime: toTimestamp(activity.attemptScheduledAt),
+      startedTime: toTimestamp(now),
+      attempt: activity.attempt,
+      scheduleToCloseTimeout: toDuration(activity.scheduleToCloseMs) ?? {},
+      startToCloseTimeout: toDuration(activity.startToCloseMs) ?? {},
+      heartbeatTimeout: toDuration(activity.heartbeatMs) ?? {},
+      retryPolicy: activity.retryPolicy,
+      ...(activity.priority ? { priority: activity.priority } : {}),
+    };
+  }
+
+  /** The run and started attempt an activity token (or an id triple) names, or NOT_FOUND. */
+  private activityOf(target: { runId?: string; scheduledEventId?: number; attempt?: number; namespace?: string; workflowId?: string; activityId?: string }): { run: Run; activity: ActivityState } {
+    let run: Run | undefined;
+    let activity: ActivityState | undefined;
+    if (target.activityId !== undefined) {
+      try {
+        run = this.resolveRun(String(target.namespace), { workflowId: target.workflowId, ...(target.runId ? { runId: target.runId } : {}) });
+      } catch { run = undefined; }
+      activity = run ? Object.values(run._state.activities).find((candidate) => candidate.activityId === target.activityId) : undefined;
+    } else {
+      run = this.run(String(target.runId ?? ''));
+      activity = run?._state.activities[String(target.scheduledEventId)];
+      if (activity && target.attempt !== undefined && activity.attempt !== target.attempt) activity = undefined;
+    }
+    if (!run || run.status !== RUNNING) throw new GrpcError(GrpcStatus.NOT_FOUND, 'workflow execution already completed');
+    if (!activity || activity.startedAt === undefined) throw new GrpcError(GrpcStatus.NOT_FOUND, 'activity task not found.');
+    return { run, activity };
+  }
+
+  private activityTarget(request: Obj, byId: boolean): Parameters<TemporalEngine['activityOf']>[0] {
+    if (byId) {
+      const namespace = this.requireNamespace(request.namespace);
+      return { namespace, workflowId: String(request.workflowId ?? ''), ...(request.runId ? { runId: String(request.runId) } : {}), activityId: String(request.activityId ?? '') };
+    }
+    const token = decodeToken(request.taskToken, 'TaskToken');
+    if (token.kind !== 'activity') throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, 'invalid TaskToken');
+    return { runId: String(token.runId), scheduledEventId: Number(token.scheduledEventId), attempt: Number(token.attempt) };
+  }
+
+  /** Close an activity with its final event (Started is written now, as Temporal writes it at the close). */
+  private closeActivity(tx: RunTx, activity: ActivityState, eventType: string, key: string, attributes: Obj): void {
+    const started = activity.startedAt !== undefined;
+    if (started) {
+      tx.deliver('EVENT_TYPE_ACTIVITY_TASK_STARTED', 'activityTaskStartedEventAttributes', {
+        scheduledEventId: activity.scheduledEventId, identity: activity.identity ?? '', requestId: activity.requestId ?? '', attempt: activity.attempt,
+        ...(activity.lastFailure ? { lastFailure: activity.lastFailure } : {}),
+      }, { wakes: false });
+    }
+    tx.deliver(eventType, key, { scheduledEventId: activity.scheduledEventId, ...attributes, ...(started ? {} : { startedEventId: 0 }) }, started ? { linkPrevious: 'startedEventId' } : {});
+    delete tx.state.activities[String(activity.scheduledEventId)];
+  }
+
+  async respondActivityTaskCompleted(request: Obj, byId = false): Promise<Obj> {
+    this.assertWritable();
+    const target = this.activityTarget(request, byId);
+    return this.serial(async () => {
+      const { run, activity } = this.activityOf(target);
+      const tx = new RunTx(run, nowMs());
+      this.closeActivity(tx, tx.state.activities[String(activity.scheduledEventId)]!, 'EVENT_TYPE_ACTIVITY_TASK_COMPLETED', 'activityTaskCompletedEventAttributes', {
+        ...(request.result ? { result: request.result } : {}), identity: String(request.identity ?? ''),
+      });
+      await this.commit(tx, byId ? 'RespondActivityTaskCompletedById' : 'RespondActivityTaskCompleted');
+      this.notify();
+      return {};
+    });
+  }
+
+  async respondActivityTaskFailed(request: Obj, byId = false): Promise<Obj> {
+    this.assertWritable();
+    const target = this.activityTarget(request, byId);
+    return this.serial(async () => {
+      const { run, activity: found } = this.activityOf(target);
+      const now = nowMs();
+      const tx = new RunTx(run, now);
+      const activity = tx.state.activities[String(found.scheduledEventId)]!;
+      const failure = (request.failure ?? { message: 'activity failed' }) as Obj;
+      if (request.lastHeartbeatDetails) activity.heartbeatDetails = request.lastHeartbeatDetails as Obj;
+      const deadline = activity.scheduleToCloseMs ? activity.scheduledAt + activity.scheduleToCloseMs : undefined;
+      const decision = activity.cancelRequestedEventId !== undefined ? { retry: false as const, state: 'RETRY_STATE_CANCEL_REQUESTED' } : decideRetry(activity.retryPolicy, activity.attempt, failure, now, deadline);
+      if (decision.retry) {
+        this.retryActivity(activity, failure, now, decision.delayMs);
+        tx.wakeQueues = true;
+      } else {
+        this.closeActivity(tx, activity, 'EVENT_TYPE_ACTIVITY_TASK_FAILED', 'activityTaskFailedEventAttributes', { failure, retryState: decision.state, identity: String(request.identity ?? '') });
+      }
+      await this.commit(tx, byId ? 'RespondActivityTaskFailedById' : 'RespondActivityTaskFailed');
+      this.notify();
+      return {};
+    });
+  }
+
+  private retryActivity(activity: ActivityState, failure: Obj, now: number, delayMs: number): void {
+    activity.attempt += 1;
+    activity.lastFailure = failure;
+    activity.lastAttemptCompletedAt = now;
+    activity.startedAt = undefined;
+    activity.identity = undefined;
+    activity.requestId = undefined;
+    activity.lastHeartbeatAt = undefined;
+    activity.attemptScheduledAt = now + delayMs;
+    activity.availableAt = now + delayMs;
+  }
+
+  async respondActivityTaskCanceled(request: Obj, byId = false): Promise<Obj> {
+    this.assertWritable();
+    const target = this.activityTarget(request, byId);
+    return this.serial(async () => {
+      const { run, activity } = this.activityOf(target);
+      if (activity.cancelRequestedEventId === undefined) {
+        throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, 'Activity task cannot be canceled: no cancellation was requested.');
+      }
+      const tx = new RunTx(run, nowMs());
+      this.closeActivity(tx, tx.state.activities[String(activity.scheduledEventId)]!, 'EVENT_TYPE_ACTIVITY_TASK_CANCELED', 'activityTaskCanceledEventAttributes', {
+        ...(request.details ? { details: request.details } : {}), latestCancelRequestedEventId: activity.cancelRequestedEventId, identity: String(request.identity ?? ''),
+      });
+      await this.commit(tx, byId ? 'RespondActivityTaskCanceledById' : 'RespondActivityTaskCanceled');
+      this.notify();
+      return {};
+    });
+  }
+
+  async recordActivityTaskHeartbeat(request: Obj, byId = false): Promise<Obj> {
+    this.assertWritable();
+    const target = this.activityTarget(request, byId);
+    return this.serial(async () => {
+      const { run, activity } = this.activityOf(target);
+      const tx = new RunTx(run, nowMs());
+      const held = tx.state.activities[String(activity.scheduledEventId)]!;
+      held.lastHeartbeatAt = tx.now;
+      if (request.details) held.heartbeatDetails = request.details as Obj;
+      await this.commit(tx, byId ? 'RecordActivityTaskHeartbeatById' : 'RecordActivityTaskHeartbeat');
+      return { cancelRequested: held.cancelRequestedEventId !== undefined, activityPaused: false, activityReset: false };
+    });
+  }
+
+  // ---- the clock -----------------------------------------------------------------------------------
+
+  /** Fire what the World clock says is due: timers, timeouts, delayed first tasks, expirations. */
+  async tick(): Promise<void> {
+    if (this.ticking || this.readOnly) return;
+    this.ticking = true;
+    try {
+      const now = nowMs();
+      const due = this.runs().filter((run) => run.status === RUNNING && run._state.nextDue !== undefined && run._state.nextDue <= now);
+      let woke = false;
+      for (const candidate of due) {
+        await this.serial(async () => {
+          const run = this.run(candidate.id);
+          if (!run || run.status !== RUNNING) return;
+          try {
+            if (await this.fireDue(run, nowMs())) woke = true;
+          } catch (error) {
+            process.stderr.write(`temporal: world-clock work for run ${run.id} failed: ${(error as Error)?.message ?? String(error)}\n`);
+          }
+        });
+      }
+      if (woke) this.notify();
+    } finally {
+      this.ticking = false;
+    }
+  }
+
+  private async fireDue(run: Run, now: number): Promise<boolean> {
+    const tx = new RunTx(run, now);
+    const state = tx.state;
+    // the run's own deadlines close it
+    const expiry = [state.runExpiresAt, state.executionExpiresAt].filter((value): value is number => value !== undefined && value <= now);
+    if (expiry.length > 0) {
+      if (state.wft?.startedEventId !== undefined) {
+        state.wft = null;
+      }
+      state.wft = null;
+      tx.flushBuffered();
+      const decision = state.executionExpiresAt !== undefined && state.executionExpiresAt <= now
+        ? { retry: false as const, state: 'RETRY_STATE_TIMEOUT' }
+        : decideRetry(state.retryPolicy, state.attempt, timeoutFailure('workflow', 'TIMEOUT_TYPE_START_TO_CLOSE'), now, state.executionExpiresAt);
+      if (decision.retry) {
+        const next = this.nextRunOf(tx, { backoffMs: decision.delayMs, attempt: state.attempt + 1, initiator: 'CONTINUE_AS_NEW_INITIATOR_RETRY' });
+        const eventId = tx.append('EVENT_TYPE_WORKFLOW_EXECUTION_TIMED_OUT', 'workflowExecutionTimedOutEventAttributes', { retryState: 'RETRY_STATE_IN_PROGRESS', newExecutionRunId: next.run.id });
+        await this.closeRun(tx, 'WORKFLOW_EXECUTION_STATUS_TIMED_OUT', eventId, 'WorkflowExecutionTimedOut', undefined, { newRunId: next.run.id });
+        await this.commit(next, 'WorkflowExecutionTimedOut');
+      } else {
+        const eventId = tx.append('EVENT_TYPE_WORKFLOW_EXECUTION_TIMED_OUT', 'workflowExecutionTimedOutEventAttributes', { retryState: decision.state });
+        await this.closeRun(tx, 'WORKFLOW_EXECUTION_STATUS_TIMED_OUT', eventId, 'WorkflowExecutionTimedOut');
+      }
+      return true;
+    }
+    let woke = false;
+    if (state.firstWftAt !== undefined && state.firstWftAt <= now) {
+      state.firstWftAt = undefined;
+      tx.scheduleWorkflowTask();
+      woke = true;
+    }
+    // an in-flight workflow task past its start-to-close timeout
+    if (state.wft?.timeoutAt !== undefined && state.wft.timeoutAt <= now) {
+      const wft = state.wft;
+      tx.append('EVENT_TYPE_WORKFLOW_TASK_TIMED_OUT', 'workflowTaskTimedOutEventAttributes', { scheduledEventId: wft.scheduledEventId, startedEventId: wft.startedEventId, timeoutType: 'TIMEOUT_TYPE_START_TO_CLOSE' });
+      state.wft = null;
+      tx.flushBuffered();
+      tx.scheduleWorkflowTask(wft.attempt + 1);
+      woke = true;
+    }
+    if (state.wft && state.wft.startedEventId === undefined && state.wft.availableAt <= now && state.wft.availableAt > (state.wft.scheduledAt)) woke = true;
+    for (const [timerId, timer] of Object.entries(state.timers)) {
+      if (timer.fireAt > now) continue;
+      delete state.timers[timerId];
+      tx.deliver('EVENT_TYPE_TIMER_FIRED', 'timerFiredEventAttributes', { timerId, startedEventId: timer.startedEventId });
+      woke = true;
+    }
+    for (const activity of Object.values(state.activities)) {
+      const timedOut = activityTimeout(activity, now);
+      if (!timedOut) {
+        if (activity.startedAt === undefined && activity.availableAt <= now && activity.availableAt > activity.scheduledAt) woke = true;
+        continue;
+      }
+      const failure = timeoutFailure('activity', timedOut, activity.heartbeatDetails);
+      const deadline = activity.scheduleToCloseMs ? activity.scheduledAt + activity.scheduleToCloseMs : undefined;
+      const decision = activity.cancelRequestedEventId !== undefined ? { retry: false as const, state: 'RETRY_STATE_CANCEL_REQUESTED' } : decideRetry(activity.retryPolicy, activity.attempt, failure, now, deadline);
+      if (decision.retry) {
+        this.retryActivity(activity, failure, now, decision.delayMs);
+      } else {
+        this.closeActivity(tx, activity, 'EVENT_TYPE_ACTIVITY_TASK_TIMED_OUT', 'activityTaskTimedOutEventAttributes', { failure, retryState: decision.state });
+      }
+      woke = true;
+    }
+    if (tx.events.length > 0 || woke) await this.commit(tx, 'WorldClock');
+    return woke;
+  }
+
+  // ---- reading runs back ---------------------------------------------------------------------------
+
+  async getWorkflowExecutionHistory(request: Obj, signal: AbortSignal, deadline?: number): Promise<Obj> {
+    const namespace = this.requireNamespace(request.namespace);
+    const token = request.nextPageToken ? decodeToken(request.nextPageToken, 'NextPageToken') : undefined;
+    const execution = request.execution as Obj | undefined;
+    let run = token?.runId ? this.run(String(token.runId)) : this.resolveRun(namespace, execution);
+    if (run && run.namespace !== namespace) run = undefined;
+    if (!run) throw new GrpcError(GrpcStatus.NOT_FOUND, 'workflow not found');
+    const closeOnly = request.historyEventFilterType === 'HISTORY_EVENT_FILTER_TYPE_CLOSE_EVENT';
+    const wait = Boolean(request.waitNewEvent);
+    const until = Math.min(Date.now() + HISTORY_LONG_POLL_MS, (deadline ?? Infinity) - 500);
+    const pageSize = Number(request.maximumPageSize) > 0 ? Number(request.maximumPageSize) : DEFAULT_PAGE_SIZE;
+    const from = Number(token?.from ?? 1);
+    for (;;) {
+      run = this.run(run.id)!;
+      if (closeOnly) {
+        if (run.status !== RUNNING) {
+          const events = await this.history(run);
+          const close = events.find((event) => event.eventId === run!._state.closeEventId);
+          return { history: { events: close ? [close] : [] } };
+        }
+      } else {
+        const events = await this.history(run);
+        if (events.length >= from || !wait || run.status !== RUNNING) {
+          const page = events.slice(from - 1, from - 1 + pageSize);
+          const last = page.length ? page[page.length - 1]!.eventId : from - 1;
+          const more = last < events.length || (wait && run.status === RUNNING);
+          return { history: { events: page }, ...(more ? { nextPageToken: encodeToken({ runId: run.id, from: last + 1 }) } : {}) };
+        }
+      }
+      if (!wait || signal.aborted || Date.now() >= until) {
+        return { history: { events: [] }, ...(closeOnly ? {} : { nextPageToken: encodeToken({ runId: run.id, from }) }) };
+      }
+      await this.wait(signal, until);
+    }
+  }
+
+  async describeWorkflowExecution(request: Obj): Promise<Obj> {
+    const namespace = this.requireNamespace(request.namespace);
+    const run = this.resolveRun(namespace, request.execution as Obj);
+    const state = run._state;
+    const pendingActivities = Object.values(state.activities).map((activity) => ({
+      activityId: activity.activityId,
+      activityType: activity.activityType,
+      state: activity.cancelRequestedEventId !== undefined ? 'PENDING_ACTIVITY_STATE_CANCEL_REQUESTED' : activity.startedAt !== undefined ? 'PENDING_ACTIVITY_STATE_STARTED' : 'PENDING_ACTIVITY_STATE_SCHEDULED',
+      ...(activity.heartbeatDetails ? { heartbeatDetails: activity.heartbeatDetails } : {}),
+      ...(activity.lastHeartbeatAt ? { lastHeartbeatTime: toTimestamp(activity.lastHeartbeatAt) } : {}),
+      ...(activity.startedAt ? { lastStartedTime: toTimestamp(activity.startedAt) } : {}),
+      attempt: activity.attempt,
+      maximumAttempts: activity.retryPolicy.maximumAttempts ?? 0,
+      scheduledTime: toTimestamp(activity.attemptScheduledAt),
+      ...(activity.scheduleToCloseMs ? { expirationTime: toTimestamp(activity.scheduledAt + activity.scheduleToCloseMs) } : {}),
+      ...(activity.lastFailure ? { lastFailure: activity.lastFailure } : {}),
+      ...(activity.identity ? { lastWorkerIdentity: activity.identity } : {}),
+      ...(activity.lastAttemptCompletedAt ? { lastAttemptCompleteTime: toTimestamp(activity.lastAttemptCompletedAt) } : {}),
+      ...(activity.startedAt === undefined && activity.attempt > 1 ? { nextAttemptScheduleTime: toTimestamp(activity.availableAt) } : {}),
+    }));
+    const pendingChildren = Object.values(state.children).map((child) => ({
+      workflowId: child.workflowId, ...(child.runId ? { runId: child.runId } : {}), workflowTypeName: String(child.workflowType.name),
+      initiatedId: child.initiatedEventId, parentClosePolicy: child.parentClosePolicy,
+    }));
+    const wft = state.wft;
+    return {
+      executionConfig: {
+        taskQueue: { name: run.taskQueue, kind: 'TASK_QUEUE_KIND_NORMAL' },
+        workflowExecutionTimeout: toDuration(state.executionTimeoutMs),
+        workflowRunTimeout: toDuration(state.runTimeoutMs),
+        defaultWorkflowTaskTimeout: toDuration(state.workflowTaskTimeoutMs),
+      },
+      workflowExecutionInfo: executionInfo(run),
+      pendingActivities,
+      pendingChildren,
+      ...(wft ? {
+        pendingWorkflowTask: {
+          state: wft.startedEventId !== undefined ? 'PENDING_WORKFLOW_TASK_STATE_STARTED' : 'PENDING_WORKFLOW_TASK_STATE_SCHEDULED',
+          scheduledTime: toTimestamp(wft.scheduledAt), originalScheduledTime: toTimestamp(wft.scheduledAt),
+          ...(wft.startedAt ? { startedTime: toTimestamp(wft.startedAt) } : {}), attempt: wft.attempt,
+        },
+      } : {}),
+    };
+  }
+
+  private visibility(namespace: string, query: string): Run[] {
+    let parsed;
+    try {
+      parsed = parseVisibilityQuery(query);
+    } catch (error) {
+      if (error instanceof VisibilityQueryError) throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, `invalid query: ${error.message}`);
+      throw error;
+    }
+    const custom = this.customSearchAttributes(namespace);
+    const fieldOf = (name: string): string => {
+      if (SYSTEM_SEARCH_ATTRIBUTES[name] || custom[name] !== undefined) return name;
+      throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, `invalid query: unable to convert filter expression: unable to convert left side of "${name}": column name '${name}' is not a valid search attribute`);
+    };
+    for (const field of visibilityFields(parsed)) fieldOf(field);
+    for (const order of parsed.orderBy) {
+      if (!['StartTime', 'CloseTime', 'ExecutionTime'].includes(order.field)) throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, `invalid query: ORDER BY ${order.field} is not supported by this server`);
+    }
+    const runs = this.runs(namespace).filter((run) => matchesVisibilityQuery(parsed, visibilityRow(run), fieldOf));
+    const orders = parsed.orderBy.length ? parsed.orderBy : [{ field: 'StartTime', desc: true }];
+    return runs.sort((a, b) => {
+      for (const order of orders) {
+        const x = Number(visibilityRow(a)[order.field] ?? 0);
+        const y = Number(visibilityRow(b)[order.field] ?? 0);
+        if (x !== y) return order.desc ? y - x : x - y;
+      }
+      return a.id < b.id ? 1 : -1;
+    });
+  }
+
+  listWorkflowExecutions(request: Obj): Obj {
+    const namespace = this.requireNamespace(request.namespace);
+    const matching = this.visibility(namespace, String(request.query ?? ''));
+    const offset = request.nextPageToken ? Number(decodeToken(request.nextPageToken, 'NextPageToken').offset ?? 0) : 0;
+    const pageSize = Number(request.pageSize) > 0 ? Number(request.pageSize) : DEFAULT_PAGE_SIZE;
+    const page = matching.slice(offset, offset + pageSize);
+    return {
+      executions: page.map(executionInfo),
+      ...(offset + pageSize < matching.length ? { nextPageToken: encodeToken({ offset: offset + pageSize }) } : {}),
+    };
+  }
+
+  countWorkflowExecutions(request: Obj): Obj {
+    const namespace = this.requireNamespace(request.namespace);
+    const query = String(request.query ?? '');
+    if (/\bGROUP\s+BY\b/i.test(query)) throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, 'invalid query: GROUP BY is not supported by this server');
+    return { count: this.visibility(namespace, query).length };
+  }
+
+  async shutdownWorker(request: Obj): Promise<Obj> {
+    this.requireNamespace(request.namespace);
+    const sticky = String(request.stickyTaskQueue ?? '');
+    if (sticky) this.closedSticky.add(sticky);
+    this.notify();
+    return {};
+  }
+}
+
+// cache: one engine per World root in a process — its lock is what serializes a root's transitions,
+// so the gRPC wire, the HTTP fetch and anything else here mounted on one root share it
+const engines = new Map<string, TemporalEngine>(); // cache: an engine holds no truth — the tree does
+
+/** The process's engine for a root (created on first use). Two engines on one root would each
+ *  serialize only their own transitions and could lose one another's updates. */
+export function engineForRoot(options: EngineOptions = {}): TemporalEngine {
+  // no root: a caller of its own (a test, a scratch fetch), never pooled with another rootless one
+  if (options.root === undefined) return new TemporalEngine(options);
+  const key = `${options.root}\0${options.readOnly ? 'ro' : 'rw'}`;
+  let engine = engines.get(key);
+  if (!engine) {
+    engine = new TemporalEngine(options);
+    engines.set(key, engine);
+  }
+  engine.users += 1;
+  return engine;
+}
+
+/** A user of a root's engine is done with it; the last one stops it and drops it from the registry. */
+export function releaseEngine(engine: TemporalEngine): void {
+  engine.users -= 1;
+  if (engine.users > 0) return;
+  engine.stop();
+  for (const [key, held] of engines) if (held === engine) engines.delete(key);
+}
+
+const CLOSING_COMMANDS = new Set([
+  'COMMAND_TYPE_COMPLETE_WORKFLOW_EXECUTION',
+  'COMMAND_TYPE_FAIL_WORKFLOW_EXECUTION',
+  'COMMAND_TYPE_CANCEL_WORKFLOW_EXECUTION',
+  'COMMAND_TYPE_CONTINUE_AS_NEW_WORKFLOW_EXECUTION',
+]);
+
+function latest(runs: Run[]): Run | undefined {
+  // the current run of a workflow id is the one created last (a chain's newest link); creation order,
+  // not start time, since a pinned World clock gives every run the same start time
+  return [...runs].sort((a, b) => b._state.seq - a._state.seq)[0];
+}
+
+function mergeFields(base: Record<string, Obj> | undefined, updates: Record<string, Obj> | undefined): Record<string, Obj> {
+  const out: Record<string, Obj> = { ...(base ?? {}) };
+  for (const [key, payload] of Object.entries(updates ?? {})) {
+    const value = payloadValue(payload);
+    const empty = value === null || (Array.isArray(value) && value.length === 0) || (payload as { data?: string }).data === undefined;
+    if (empty) delete out[key];
+    else out[key] = payload;
+  }
+  return out;
+}
+
+function activityTimeout(activity: ActivityState, now: number): string | undefined {
+  if (activity.scheduleToCloseMs && now >= activity.scheduledAt + activity.scheduleToCloseMs) return 'TIMEOUT_TYPE_SCHEDULE_TO_CLOSE';
+  if (activity.startedAt === undefined) {
+    if (activity.availableAt > now) return undefined;
+    if (activity.scheduleToStartMs && now >= activity.attemptScheduledAt + activity.scheduleToStartMs) return 'TIMEOUT_TYPE_SCHEDULE_TO_START';
+    return undefined;
+  }
+  if (activity.startToCloseMs && now >= activity.startedAt + activity.startToCloseMs) return 'TIMEOUT_TYPE_START_TO_CLOSE';
+  if (activity.heartbeatMs && now >= (activity.lastHeartbeatAt ?? activity.startedAt) + activity.heartbeatMs) return 'TIMEOUT_TYPE_HEARTBEAT';
+  return undefined;
+}
+
+/** The earliest moment still ahead at which the World clock has something to do for this run. A task
+ *  whose backoff has passed is the pollers' to take, not the clock's, so it is not counted once due:
+ *  counting it would re-enter the run on every tick (and write it) until a worker came. */
+function nextDue(run: Run, now: number): number | undefined {
+  if (run.status !== RUNNING) return undefined;
+  const state = run._state;
+  const times: number[] = [];
+  if (state.runExpiresAt !== undefined) times.push(state.runExpiresAt);
+  if (state.executionExpiresAt !== undefined) times.push(state.executionExpiresAt);
+  if (state.firstWftAt !== undefined) times.push(state.firstWftAt);
+  if (state.wft?.timeoutAt !== undefined) times.push(state.wft.timeoutAt);
+  if (state.wft && state.wft.startedEventId === undefined && state.wft.availableAt > now) times.push(state.wft.availableAt);
+  for (const timer of Object.values(state.timers)) times.push(timer.fireAt);
+  for (const activity of Object.values(state.activities)) {
+    if (activity.scheduleToCloseMs) times.push(activity.scheduledAt + activity.scheduleToCloseMs);
+    if (activity.startedAt === undefined) {
+      if (activity.availableAt > now) times.push(activity.availableAt);
+      if (activity.scheduleToStartMs) times.push(activity.attemptScheduledAt + activity.scheduleToStartMs);
+    } else {
+      if (activity.startToCloseMs) times.push(activity.startedAt + activity.startToCloseMs);
+      if (activity.heartbeatMs) times.push((activity.lastHeartbeatAt ?? activity.startedAt) + activity.heartbeatMs);
+    }
+  }
+  return times.length ? Math.min(...times) : undefined;
+}
+
+/** A run's WorkflowExecutionInfo: its stored fields without the server's bookkeeping. */
+export function executionInfo(run: Run): Obj {
+  const { id: _id, namespace: _namespace, _state, ...info } = run;
+  return info;
+}
+
+function visibilityRow(run: Run): VisibilityRow {
+  const row: VisibilityRow = {
+    WorkflowId: run.execution.workflowId,
+    RunId: run.execution.runId,
+    WorkflowType: run.type.name,
+    ExecutionStatus: STATUS_NAME[run.status] ?? run.status,
+    TaskQueue: run.taskQueue,
+    StartTime: timestampMs(run.startTime) ?? null,
+    ExecutionTime: timestampMs(run.executionTime) ?? null,
+    CloseTime: timestampMs(run.closeTime) ?? null,
+    HistoryLength: run.historyLength,
+    HistorySizeBytes: Number(run.historySizeBytes ?? 0),
+    StateTransitionCount: Number(run.stateTransitionCount ?? 0),
+    ExecutionDuration: run.executionDuration ? durationMs(run.executionDuration) * 1e6 : null,
+    ParentWorkflowId: run.parentExecution?.workflowId ?? null,
+    ParentRunId: run.parentExecution?.runId ?? null,
+    RootWorkflowId: run.rootExecution?.workflowId ?? null,
+    RootRunId: run.rootExecution?.runId ?? null,
+  };
+  for (const [key, payload] of Object.entries(run.searchAttributes?.indexedFields ?? {})) {
+    const value = payloadValue(payload);
+    if (value === undefined) continue;
+    row[key] = Array.isArray(value) ? value.map(String) : typeof value === 'object' && value !== null ? JSON.stringify(value) : (value as string | number | boolean | null);
+  }
+  return row;
+}
+
+/** A stored subject as the wire answers it: `_`-prefixed bookkeeping never leaves the twin. */
+function publicView(record: Obj): Obj {
+  return Object.fromEntries(Object.entries(record).filter(([key]) => !key.startsWith('_')));
+}
+
+function namespaceCapabilities(): Obj {
+  return { eagerWorkflowStart: false, syncUpdate: false, asyncUpdate: false };
+}
+
+function defaultNamespace(): Obj {
+  return {
+    namespaceInfo: {
+      name: DEFAULT_NAMESPACE, state: 'NAMESPACE_STATE_REGISTERED', id: uuidFrom(`namespace\0${DEFAULT_NAMESPACE}`),
+      description: 'Default namespace for Temporal Server.', capabilities: namespaceCapabilities(), supportsSchedules: false,
+    },
+    config: {
+      workflowExecutionRetentionTtl: { seconds: 86_400 },
+      historyArchivalState: 'ARCHIVAL_STATE_DISABLED',
+      visibilityArchivalState: 'ARCHIVAL_STATE_DISABLED',
+    },
+    replicationConfig: { activeClusterName: 'active', clusters: [{ clusterName: 'active' }], state: 'REPLICATION_STATE_NORMAL' },
+    isGlobalNamespace: false,
+  };
+}