@volter/twin-temporal 0.1.0

package/src/temporal-capabilities.ts

@@ -0,0 +1,679 @@
+// THE CAPABILITY MANIFEST — the Temporal frontend's declared surface as the denominator.
+//
+// The denominator is read from the vendored protos, not written by hand: every method of
+// temporal.api.workflowservice.v1.WorkflowService, temporal.api.operatorservice.v1.OperatorService
+// and grpc.health.v1.Health is one capability, and every CommandType a workflow task can return is
+// another (the history service's surface, which no RPC names). A method is `done` exactly when the
+// twin serves it (temporal-twin.ts SERVED) AND a verify below proves what it answers; everything
+// else is `todo`, and on the wire it answers gRPC UNIMPLEMENTED. The behaviours no single RPC owns
+// (retries, timers on the World clock, buffered events, parent-close policy) are the `history` area.
+//
+// Every verify drives a fresh World root through `handleTemporalCall` (the mutation seam in
+// gate.ts) the way a worker and a client would, and asserts values a blank answer cannot fake.
+// The real SDKs are proven end to end in temporal-sdk.integration.test.ts.
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { checkCapabilities, type CapabilityReport, type CapabilitySpec, verifyBoundary } from '@volter/world-tooling';
+import { twinResources } from '@volter/world-core';
+import { handleTemporalCall, SERVED } from './temporal-twin.ts';
+import { TemporalEngine, jsonPayload, payloadValue } from './temporal-engine.ts';
+import { HEALTH_SERVICE, OPERATOR_SERVICE, WORKFLOW_SERVICE, serviceMethods, temporalRoot } from './temporal-proto.ts';
+import { GrpcError } from './temporal-grpc.ts';
+import { syncTemporalFromReal } from './temporal-connector.ts';
+import { createTemporalTwinFetch } from './temporal-http.ts';
+
+type Obj = Record<string, any>;
+const done = (id: string, area: string, title: string, tier: CapabilitySpec['tier'], verify: CapabilitySpec['verify']): CapabilitySpec =>
+  ({ id, area, title, dimension: 'api', tier, expected: 'done', verify });
+const todo = (id: string, area: string, title: string, tier: CapabilitySpec['tier']): CapabilitySpec =>
+  ({ id, area, title, dimension: 'api', tier, expected: 'todo' });
+
+const T0 = '2026-01-01T00:00:00.000Z';
+
+type Twin = {
+  engine: TemporalEngine;
+  root: string;
+  /** one unary call through the seam; a GrpcError comes back as `{ grpcError: code, message }` */
+  call(method: string, request?: Obj, deadlineMs?: number): Promise<Obj>;
+  /** move the World clock forward */
+  advance(ms: number): Promise<void>;
+  start(workflowId: string, extra?: Obj): Promise<string>;
+  pollWorkflow(queue?: string): Promise<Obj>;
+  complete(task: Obj, commands: Obj[], extra?: Obj): Promise<Obj>;
+  pollActivity(queue?: string): Promise<Obj>;
+  events(workflowId: string, runId?: string): Promise<Obj[]>;
+  describe(workflowId: string, runId?: string): Promise<Obj>;
+};
+
+const SERVICE_OF = new Map<string, string>();
+for (const service of [WORKFLOW_SERVICE, OPERATOR_SERVICE, HEALTH_SERVICE]) for (const method of serviceMethods(service).keys()) SERVICE_OF.set(method, service);
+
+/** A fresh World root with its own pinned clock; the verify proves the capability from nothing. */
+async function withTwin(fn: (twin: Twin) => Promise<boolean>): Promise<boolean> {
+  const root = mkdtempSync(join(tmpdir(), 'temporal-cap-'));
+  const clock = join(root, 'world-clock');
+  writeFileSync(clock, `${T0}\n`);
+  const previous = process.env.TWIN_WORLD_CLOCK_FILE;
+  process.env.TWIN_WORLD_CLOCK_FILE = clock;
+  const engine = new TemporalEngine({ root });
+  let now = Date.parse(T0);
+  const call = async (method: string, request: Obj = {}, deadlineMs = 300): Promise<Obj> => {
+    const controller = new AbortController();
+    try {
+      return await handleTemporalCall(engine, SERVICE_OF.get(method)!, method, { namespace: 'default', ...request }, { signal: controller.signal, deadline: Date.now() + 1000 + deadlineMs, metadata: {} });
+    } catch (error) {
+      if (error instanceof GrpcError) return { grpcError: error.code, message: error.message };
+      throw error;
+    }
+  };
+  const twin: Twin = {
+    engine,
+    root,
+    call,
+    advance: async (ms) => {
+      now += ms;
+      writeFileSync(clock, `${new Date(now).toISOString()}\n`);
+      await engine.tick();
+    },
+    start: async (workflowId, extra = {}) => (await call('StartWorkflowExecution', { workflowId, workflowType: { name: 'wf' }, taskQueue: { name: 'q' }, requestId: `r-${workflowId}-${Math.random()}`, input: { payloads: [jsonPayload('in')] }, ...extra })).runId,
+    pollWorkflow: (queue = 'q') => call('PollWorkflowTaskQueue', { taskQueue: { name: queue, kind: 'TASK_QUEUE_KIND_NORMAL' }, identity: 'w' }),
+    complete: (task, commands, extra = {}) => call('RespondWorkflowTaskCompleted', { taskToken: task.taskToken, commands, identity: 'w', ...extra }),
+    pollActivity: (queue = 'q') => call('PollActivityTaskQueue', { taskQueue: { name: queue }, identity: 'w' }),
+    events: async (workflowId, runId) => (await call('GetWorkflowExecutionHistory', { execution: { workflowId, ...(runId ? { runId } : {}) } })).history?.events ?? [],
+    describe: (workflowId, runId) => call('DescribeWorkflowExecution', { execution: { workflowId, ...(runId ? { runId } : {}) } }),
+  };
+  try {
+    return await verifyBoundary('temporal.withTwin', () => fn(twin));
+  } finally {
+    engine.stop();
+    if (previous === undefined) delete process.env.TWIN_WORLD_CLOCK_FILE;
+    else process.env.TWIN_WORLD_CLOCK_FILE = previous;
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+const types = (events: Obj[]) => events.map((event) => String(event.eventType).replace('EVENT_TYPE_', ''));
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const command = (commandType: string, attributes: Obj): Obj => {
+  const key = `${commandType.replace('COMMAND_TYPE_', '').toLowerCase().replace(/_([a-z])/g, (_, c: string) => c.toUpperCase())}CommandAttributes`;
+  return { commandType, [key]: attributes };
+};
+const activityCommand = (activityId: string, extra: Obj = {}) => command('COMMAND_TYPE_SCHEDULE_ACTIVITY_TASK', {
+  activityId, activityType: { name: 'act' }, taskQueue: { name: 'q' }, startToCloseTimeout: { seconds: 60 }, input: { payloads: [jsonPayload(activityId)] }, ...extra,
+});
+const completeCommand = (value: unknown) => command('COMMAND_TYPE_COMPLETE_WORKFLOW_EXECUTION', { result: { payloads: [jsonPayload(value)] } });
+
+/** start → first task → the given commands; answers the run id and the events after. */
+async function afterFirstTask(twin: Twin, workflowId: string, commands: Obj[], extra: Obj = {}): Promise<{ runId: string; events: Obj[]; answer: Obj }> {
+  const runId = await twin.start(workflowId, extra);
+  const task = await twin.pollWorkflow();
+  const answer = await twin.complete(task, commands);
+  return { runId, events: await twin.events(workflowId, runId), answer };
+}
+
+// ---- the RPC verifies ------------------------------------------------------------------------------
+
+const RPC_VERIFY: Record<string, { tier: CapabilitySpec['tier']; verify: () => Promise<boolean> }> = {
+  GetSystemInfo: { tier: 'core', verify: () => withTwin(async (t) => {
+    const info = await t.call('GetSystemInfo');
+    return /^\d+\.\d+\.\d+$/.test(String(info.serverVersion)) && info.capabilities?.sdkMetadata === true && info.capabilities?.supportsSchedules === false;
+  }) },
+  DescribeNamespace: { tier: 'core', verify: () => withTwin(async (t) => {
+    const ns = await t.call('DescribeNamespace', { namespace: 'default' });
+    const missing = await t.call('DescribeNamespace', { namespace: 'nope' });
+    return ns.namespaceInfo?.name === 'default' && ns.namespaceInfo?.state === 'NAMESPACE_STATE_REGISTERED' && UUID.test(ns.namespaceInfo?.id) && missing.grpcError === 5;
+  }) },
+  ListNamespaces: { tier: 'common', verify: () => withTwin(async (t) => {
+    await t.call('RegisterNamespace', { namespace: 'other', workflowExecutionRetentionPeriod: { seconds: 3600 } });
+    const names = ((await t.call('ListNamespaces')).namespaces ?? []).map((ns: Obj) => ns.namespaceInfo.name);
+    return names.includes('default') && names.includes('other');
+  }) },
+  RegisterNamespace: { tier: 'common', verify: () => withTwin(async (t) => {
+    const first = await t.call('RegisterNamespace', { namespace: 'team', description: 'd' });
+    const again = await t.call('RegisterNamespace', { namespace: 'team' });
+    const described = await t.call('DescribeNamespace', { namespace: 'team' });
+    return first.grpcError === undefined && again.grpcError === 6 && described.namespaceInfo?.description === 'd';
+  }) },
+  StartWorkflowExecution: { tier: 'core', verify: () => withTwin(async (t) => {
+    const answer = await t.call('StartWorkflowExecution', { workflowId: 'w1', workflowType: { name: 'wf' }, taskQueue: { name: 'q' }, requestId: 'req-1' });
+    const again = await t.call('StartWorkflowExecution', { workflowId: 'w1', workflowType: { name: 'wf' }, taskQueue: { name: 'q' }, requestId: 'req-1' });
+    const conflict = await t.call('StartWorkflowExecution', { workflowId: 'w1', workflowType: { name: 'wf' }, taskQueue: { name: 'q' }, requestId: 'req-2' });
+    const useExisting = await t.call('StartWorkflowExecution', { workflowId: 'w1', workflowType: { name: 'wf' }, taskQueue: { name: 'q' }, requestId: 'req-3', workflowIdConflictPolicy: 'WORKFLOW_ID_CONFLICT_POLICY_USE_EXISTING' });
+    const events = types(await t.events('w1'));
+    return UUID.test(answer.runId) && answer.started === true && again.runId === answer.runId && conflict.grpcError === 6
+      && useExisting.runId === answer.runId && useExisting.started === false && events.join() === 'WORKFLOW_EXECUTION_STARTED,WORKFLOW_TASK_SCHEDULED';
+  }) },
+  SignalWithStartWorkflowExecution: { tier: 'core', verify: () => withTwin(async (t) => {
+    const req = { workflowId: 'sws', workflowType: { name: 'wf' }, taskQueue: { name: 'q' }, signalName: 'go', signalInput: { payloads: [jsonPayload(1)] } };
+    const first = await t.call('SignalWithStartWorkflowExecution', { ...req, requestId: 'a' });
+    const second = await t.call('SignalWithStartWorkflowExecution', { ...req, requestId: 'b' });
+    const events = types(await t.events('sws'));
+    return first.started === true && second.started === false && second.runId === first.runId
+      && events.join() === 'WORKFLOW_EXECUTION_STARTED,WORKFLOW_EXECUTION_SIGNALED,WORKFLOW_TASK_SCHEDULED,WORKFLOW_EXECUTION_SIGNALED';
+  }) },
+  SignalWorkflowExecution: { tier: 'core', verify: () => withTwin(async (t) => {
+    await t.start('sig');
+    const task = await t.pollWorkflow();
+    // a signal while the task is in flight is buffered until it closes
+    await t.call('SignalWorkflowExecution', { workflowExecution: { workflowId: 'sig' }, signalName: 'poke', input: { payloads: [jsonPayload('x')] } });
+    const during = types(await t.events('sig'));
+    await t.complete(task, []);
+    const after = await t.events('sig');
+    const signaled = after.find((e) => e.eventType === 'EVENT_TYPE_WORKFLOW_EXECUTION_SIGNALED');
+    const missing = await t.call('SignalWorkflowExecution', { workflowExecution: { workflowId: 'nope' }, signalName: 'poke' });
+    return !during.includes('WORKFLOW_EXECUTION_SIGNALED') && signaled?.workflowExecutionSignaledEventAttributes?.signalName === 'poke'
+      && payloadValue(signaled.workflowExecutionSignaledEventAttributes.input.payloads[0]) === 'x'
+      && types(after).slice(-2).join() === 'WORKFLOW_EXECUTION_SIGNALED,WORKFLOW_TASK_SCHEDULED' && missing.grpcError === 5;
+  }) },
+  RequestCancelWorkflowExecution: { tier: 'common', verify: () => withTwin(async (t) => {
+    await afterFirstTask(t, 'rc', []);
+    await t.call('RequestCancelWorkflowExecution', { workflowExecution: { workflowId: 'rc' }, reason: 'stop', requestId: 'c1' });
+    const task = await t.pollWorkflow();
+    await t.complete(task, [command('COMMAND_TYPE_CANCEL_WORKFLOW_EXECUTION', {})]);
+    const events = types(await t.events('rc'));
+    return events.includes('WORKFLOW_EXECUTION_CANCEL_REQUESTED') && events.at(-1) === 'WORKFLOW_EXECUTION_CANCELED'
+      && (await t.describe('rc')).workflowExecutionInfo?.status === 'WORKFLOW_EXECUTION_STATUS_CANCELED';
+  }) },
+  TerminateWorkflowExecution: { tier: 'core', verify: () => withTwin(async (t) => {
+    await t.start('term');
+    const answer = await t.call('TerminateWorkflowExecution', { workflowExecution: { workflowId: 'term' }, reason: 'enough', identity: 'op' });
+    const again = await t.call('TerminateWorkflowExecution', { workflowExecution: { workflowId: 'term' }, reason: 'again' });
+    const events = await t.events('term');
+    const last = events.at(-1)!;
+    return answer.grpcError === undefined && again.grpcError === 5 && last.eventType === 'EVENT_TYPE_WORKFLOW_EXECUTION_TERMINATED'
+      && last.workflowExecutionTerminatedEventAttributes?.reason === 'enough' && (await t.describe('term')).workflowExecutionInfo?.status === 'WORKFLOW_EXECUTION_STATUS_TERMINATED';
+  }) },
+  GetWorkflowExecutionHistory: { tier: 'core', verify: () => withTwin(async (t) => {
+    await afterFirstTask(t, 'hist', [completeCommand('ok')]);
+    const all = await t.call('GetWorkflowExecutionHistory', { execution: { workflowId: 'hist' } });
+    const close = await t.call('GetWorkflowExecutionHistory', { execution: { workflowId: 'hist' }, historyEventFilterType: 'HISTORY_EVENT_FILTER_TYPE_CLOSE_EVENT', waitNewEvent: true });
+    const paged = await t.call('GetWorkflowExecutionHistory', { execution: { workflowId: 'hist' }, maximumPageSize: 2 });
+    const ids = (all.history?.events ?? []).map((e: Obj) => e.eventId);
+    return ids.join() === '1,2,3,4,5' && close.history?.events?.length === 1 && close.history.events[0].eventType === 'EVENT_TYPE_WORKFLOW_EXECUTION_COMPLETED'
+      && paged.history?.events?.length === 2 && typeof paged.nextPageToken === 'string';
+  }) },
+  DescribeWorkflowExecution: { tier: 'core', verify: () => withTwin(async (t) => {
+    const { runId } = await afterFirstTask(t, 'desc', [activityCommand('a1')], { memo: { fields: { m: jsonPayload('v') } } });
+    const described = await t.describe('desc');
+    const info = described.workflowExecutionInfo ?? {};
+    return info.execution?.runId === runId && info.type?.name === 'wf' && info.status === 'WORKFLOW_EXECUTION_STATUS_RUNNING' && info.taskQueue === 'q'
+      && info.historyLength === 5 && described.pendingActivities?.[0]?.activityId === 'a1' && described.pendingActivities[0].state === 'PENDING_ACTIVITY_STATE_SCHEDULED'
+      && payloadValue(info.memo?.fields?.m) === 'v' && (await t.describe('nope')).grpcError === 5;
+  }) },
+  ListWorkflowExecutions: { tier: 'core', verify: () => withTwin(async (t) => {
+    await t.call('AddSearchAttributes', { searchAttributes: { postId: 'INDEXED_VALUE_TYPE_TEXT' } });
+    await t.start('p-1', { searchAttributes: { indexedFields: { postId: jsonPayload('abc', { type: 'Text' }) } } });
+    await t.start('p-2', { searchAttributes: { indexedFields: { postId: jsonPayload('zzz', { type: 'Text' }) } } });
+    await t.call('TerminateWorkflowExecution', { workflowExecution: { workflowId: 'p-2' } });
+    const running = await t.call('ListWorkflowExecutions', { query: 'postId="abc" AND ExecutionStatus="Running"' });
+    const either = await t.call('ListWorkflowExecutions', { query: "WorkflowId IN ('p-1', 'p-2') ORDER BY StartTime DESC" });
+    const bad = await t.call('ListWorkflowExecutions', { query: 'nope = 1' });
+    return running.executions?.map((e: Obj) => e.execution.workflowId).join() === 'p-1' && either.executions?.length === 2 && bad.grpcError === 3;
+  }) },
+  CountWorkflowExecutions: { tier: 'common', verify: () => withTwin(async (t) => {
+    await t.start('c-1');
+    await t.start('c-2');
+    await t.call('TerminateWorkflowExecution', { workflowExecution: { workflowId: 'c-2' } });
+    const running = await t.call('CountWorkflowExecutions', { query: 'ExecutionStatus = "Running"' });
+    const all = await t.call('CountWorkflowExecutions', { query: '' });
+    return running.count === 1 && all.count === 2;
+  }) },
+  PollWorkflowTaskQueue: { tier: 'core', verify: () => withTwin(async (t) => {
+    const runId = await t.start('poll');
+    const task = await t.pollWorkflow();
+    const empty = await t.pollWorkflow();
+    const events = task.history?.events ?? [];
+    return typeof task.taskToken === 'string' && task.workflowExecution?.runId === runId && task.startedEventId === 3 && task.attempt === 1
+      && types(events).join() === 'WORKFLOW_EXECUTION_STARTED,WORKFLOW_TASK_SCHEDULED,WORKFLOW_TASK_STARTED' && empty.taskToken === undefined;
+  }) },
+  RespondWorkflowTaskCompleted: { tier: 'core', verify: () => withTwin(async (t) => {
+    await t.start('rwc');
+    const task = await t.pollWorkflow();
+    const answer = await t.complete(task, [activityCommand('a1')]);
+    const stale = await t.complete(task, []);
+    const events = await t.events('rwc');
+    const completed = events.find((e) => e.eventType === 'EVENT_TYPE_WORKFLOW_TASK_COMPLETED');
+    return answer.grpcError === undefined && completed?.workflowTaskCompletedEventAttributes?.scheduledEventId === 2 && completed.workflowTaskCompletedEventAttributes.startedEventId === 3
+      && types(events).at(-1) === 'ACTIVITY_TASK_SCHEDULED' && stale.grpcError === 5;
+  }) },
+  RespondWorkflowTaskFailed: { tier: 'core', verify: () => withTwin(async (t) => {
+    await t.start('rwf');
+    const task = await t.pollWorkflow();
+    await t.call('RespondWorkflowTaskFailed', { taskToken: task.taskToken, cause: 'WORKFLOW_TASK_FAILED_CAUSE_WORKFLOW_WORKER_UNHANDLED_FAILURE', failure: { message: 'boom' } });
+    const retried = await t.pollWorkflow();
+    const events = await t.events('rwf');
+    const failed = events.find((e) => e.eventType === 'EVENT_TYPE_WORKFLOW_TASK_FAILED');
+    return failed?.workflowTaskFailedEventAttributes?.failure?.message === 'boom' && retried.attempt === 2 && retried.startedEventId === 6;
+  }) },
+  PollActivityTaskQueue: { tier: 'core', verify: () => withTwin(async (t) => {
+    const { runId } = await afterFirstTask(t, 'pa', [activityCommand('a1', { heartbeatTimeout: { seconds: 10 } })]);
+    const task = await t.pollActivity();
+    const empty = await t.pollActivity();
+    return task.activityId === 'a1' && task.activityType?.name === 'act' && task.workflowExecution?.runId === runId && task.attempt === 1
+      && payloadValue(task.input?.payloads?.[0]) === 'a1' && task.startToCloseTimeout?.seconds === 60 && task.heartbeatTimeout?.seconds === 10 && empty.taskToken === undefined;
+  }) },
+  RespondActivityTaskCompleted: { tier: 'core', verify: () => withTwin(async (t) => {
+    await afterFirstTask(t, 'rac', [activityCommand('a1')]);
+    const task = await t.pollActivity();
+    await t.call('RespondActivityTaskCompleted', { taskToken: task.taskToken, result: { payloads: [jsonPayload(42)] }, identity: 'w' });
+    const events = await t.events('rac');
+    const completed = events.find((e) => e.eventType === 'EVENT_TYPE_ACTIVITY_TASK_COMPLETED');
+    const started = events.find((e) => e.eventType === 'EVENT_TYPE_ACTIVITY_TASK_STARTED');
+    const again = await t.call('RespondActivityTaskCompleted', { taskToken: task.taskToken });
+    return payloadValue(completed?.activityTaskCompletedEventAttributes?.result?.payloads?.[0]) === 42 && completed?.activityTaskCompletedEventAttributes?.startedEventId === started?.eventId
+      && types(events).at(-1) === 'WORKFLOW_TASK_SCHEDULED' && again.grpcError === 5;
+  }) },
+  RespondActivityTaskCompletedById: { tier: 'niche', verify: () => withTwin(async (t) => {
+    await afterFirstTask(t, 'racid', [activityCommand('a1')]);
+    await t.pollActivity();
+    await t.call('RespondActivityTaskCompletedById', { workflowId: 'racid', activityId: 'a1', result: { payloads: [jsonPayload('by id')] } });
+    const completed = (await t.events('racid')).find((e) => e.eventType === 'EVENT_TYPE_ACTIVITY_TASK_COMPLETED');
+    return payloadValue(completed?.activityTaskCompletedEventAttributes?.result?.payloads?.[0]) === 'by id';
+  }) },
+  RespondActivityTaskFailed: { tier: 'core', verify: () => withTwin(async (t) => {
+    await afterFirstTask(t, 'raf', [activityCommand('a1', { retryPolicy: { maximumAttempts: 1 } })]);
+    const task = await t.pollActivity();
+    await t.call('RespondActivityTaskFailed', { taskToken: task.taskToken, failure: { message: 'nope', applicationFailureInfo: { type: 'E' } } });
+    const failed = (await t.events('raf')).find((e) => e.eventType === 'EVENT_TYPE_ACTIVITY_TASK_FAILED');
+    return failed?.activityTaskFailedEventAttributes?.failure?.message === 'nope' && failed.activityTaskFailedEventAttributes.retryState === 'RETRY_STATE_MAXIMUM_ATTEMPTS_REACHED';
+  }) },
+  RespondActivityTaskFailedById: { tier: 'niche', verify: () => withTwin(async (t) => {
+    await afterFirstTask(t, 'rafid', [activityCommand('a1', { retryPolicy: { maximumAttempts: 1 } })]);
+    await t.pollActivity();
+    await t.call('RespondActivityTaskFailedById', { workflowId: 'rafid', activityId: 'a1', failure: { message: 'by id' } });
+    const failed = (await t.events('rafid')).find((e) => e.eventType === 'EVENT_TYPE_ACTIVITY_TASK_FAILED');
+    return failed?.activityTaskFailedEventAttributes?.failure?.message === 'by id';
+  }) },
+  RespondActivityTaskCanceled: { tier: 'common', verify: () => withTwin(async (t) => {
+    await t.start('ract');
+    const first = await t.pollWorkflow();
+    await t.complete(first, [activityCommand('a1')]);
+    const activity = await t.pollActivity();
+    const early = await t.call('RespondActivityTaskCanceled', { taskToken: activity.taskToken });
+    await t.call('SignalWorkflowExecution', { workflowExecution: { workflowId: 'ract' }, signalName: 's' });
+    const second = await t.pollWorkflow();
+    await t.complete(second, [command('COMMAND_TYPE_REQUEST_CANCEL_ACTIVITY_TASK', { scheduledEventId: 5 })]);
+    const beat = await t.call('RecordActivityTaskHeartbeat', { taskToken: activity.taskToken });
+    await t.call('RespondActivityTaskCanceled', { taskToken: activity.taskToken, details: { payloads: [jsonPayload('bye')] } });
+    const canceled = (await t.events('ract')).find((e) => e.eventType === 'EVENT_TYPE_ACTIVITY_TASK_CANCELED');
+    return early.grpcError === 3 && beat.cancelRequested === true && payloadValue(canceled?.activityTaskCanceledEventAttributes?.details?.payloads?.[0]) === 'bye';
+  }) },
+  RespondActivityTaskCanceledById: { tier: 'niche', verify: () => withTwin(async (t) => {
+    await t.start('ractid');
+    await t.complete(await t.pollWorkflow(), [activityCommand('a1')]);
+    await t.pollActivity();
+    await t.call('SignalWorkflowExecution', { workflowExecution: { workflowId: 'ractid' }, signalName: 's' });
+    await t.complete(await t.pollWorkflow(), [command('COMMAND_TYPE_REQUEST_CANCEL_ACTIVITY_TASK', { scheduledEventId: 5 })]);
+    await t.call('RespondActivityTaskCanceledById', { workflowId: 'ractid', activityId: 'a1' });
+    return types(await t.events('ractid')).includes('ACTIVITY_TASK_CANCELED');
+  }) },
+  RecordActivityTaskHeartbeat: { tier: 'core', verify: () => withTwin(async (t) => {
+    await afterFirstTask(t, 'hb', [activityCommand('a1', { heartbeatTimeout: { seconds: 5 } })]);
+    const task = await t.pollActivity();
+    await t.advance(4000);
+    const beat = await t.call('RecordActivityTaskHeartbeat', { taskToken: task.taskToken, details: { payloads: [jsonPayload('halfway')] } });
+    await t.advance(4000); // 8 s after start, 4 s after the heartbeat: not timed out
+    const described = await t.describe('hb');
+    return beat.cancelRequested === false && described.pendingActivities?.[0]?.state === 'PENDING_ACTIVITY_STATE_STARTED'
+      && payloadValue(described.pendingActivities[0].heartbeatDetails?.payloads?.[0]) === 'halfway';
+  }) },
+  RecordActivityTaskHeartbeatById: { tier: 'niche', verify: () => withTwin(async (t) => {
+    await afterFirstTask(t, 'hbid', [activityCommand('a1')]);
+    await t.pollActivity();
+    await t.call('RecordActivityTaskHeartbeatById', { workflowId: 'hbid', activityId: 'a1', details: { payloads: [jsonPayload(7)] } });
+    return payloadValue((await t.describe('hbid')).pendingActivities?.[0]?.heartbeatDetails?.payloads?.[0]) === 7;
+  }) },
+  QueryWorkflow: { tier: 'common', verify: () => withTwin(async (t) => {
+    await afterFirstTask(t, 'qw', []);
+    const answer = t.call('QueryWorkflow', { execution: { workflowId: 'qw' }, query: { queryType: 'stage' } }, 3000);
+    const task = await t.pollWorkflow();
+    await t.call('RespondQueryTaskCompleted', { taskToken: task.taskToken, completedType: 'QUERY_RESULT_TYPE_ANSWERED', queryResult: { payloads: [jsonPayload('waiting')] } });
+    const result = await answer;
+    return task.query?.queryType === 'stage' && payloadValue(result.queryResult?.payloads?.[0]) === 'waiting';
+  }) },
+  RespondQueryTaskCompleted: { tier: 'common', verify: () => withTwin(async (t) => {
+    await afterFirstTask(t, 'rq', []);
+    const answer = t.call('QueryWorkflow', { execution: { workflowId: 'rq' }, query: { queryType: 'nope' } }, 3000);
+    const task = await t.pollWorkflow();
+    await t.call('RespondQueryTaskCompleted', { taskToken: task.taskToken, completedType: 'QUERY_RESULT_TYPE_FAILED', errorMessage: 'unknown query type nope' });
+    const result = await answer;
+    return result.grpcError === 3 && String(result.message).includes('unknown query type nope');
+  }) },
+  ResetStickyTaskQueue: { tier: 'niche', verify: () => withTwin(async (t) => {
+    await t.start('sticky');
+    const ok = await t.call('ResetStickyTaskQueue', { execution: { workflowId: 'sticky' } });
+    const bad = await t.call('ResetStickyTaskQueue', { namespace: 'nope', execution: { workflowId: 'sticky' } });
+    const missing = await t.call('ResetStickyTaskQueue', { execution: { workflowId: 'no-such-run' } });
+    return ok.grpcError === undefined && bad.grpcError === 5 && missing.grpcError === 5;
+  }) },
+  ShutdownWorker: { tier: 'core', verify: () => withTwin(async (t) => {
+    // a sticky poll is held open (this server never routes to a sticky queue) until the worker that
+    // owns the queue says it is shutting down, which releases it at once
+    const poll = t.call('PollWorkflowTaskQueue', { taskQueue: { name: 'sticky-1', kind: 'TASK_QUEUE_KIND_STICKY' } }, 5000);
+    const held = await Promise.race([poll.then(() => 'answered'), new Promise((resolve) => setTimeout(() => resolve('held'), 300))]);
+    const began = Date.now();
+    await t.call('ShutdownWorker', { stickyTaskQueue: 'sticky-1', identity: 'w' });
+    const answer = await poll;
+    return held === 'held' && answer.taskToken === undefined && answer.grpcError === undefined && Date.now() - began < 2000;
+  }) },
+  ListSearchAttributes: { tier: 'core', verify: () => withTwin(async (t) => {
+    await t.call('AddSearchAttributes', { searchAttributes: { postId: 'INDEXED_VALUE_TYPE_TEXT' } });
+    const listed = await t.call('ListSearchAttributes');
+    return listed.customAttributes?.postId === 'INDEXED_VALUE_TYPE_TEXT' && listed.systemAttributes?.WorkflowId === 'INDEXED_VALUE_TYPE_KEYWORD';
+  }) },
+  AddSearchAttributes: { tier: 'core', verify: () => withTwin(async (t) => {
+    const before = await t.start('sa-before', { searchAttributes: { indexedFields: { orgId: jsonPayload('o', { type: 'Text' }) } } });
+    await t.call('AddSearchAttributes', { searchAttributes: { orgId: 'INDEXED_VALUE_TYPE_TEXT' } });
+    const after = await t.start('sa-after', { searchAttributes: { indexedFields: { orgId: jsonPayload('o', { type: 'Text' }) } } });
+    const clash = await t.call('AddSearchAttributes', { searchAttributes: { orgId: 'INDEXED_VALUE_TYPE_INT' } });
+    return before === undefined && UUID.test(after) && clash.grpcError === 6;
+  }) },
+  RemoveSearchAttributes: { tier: 'niche', verify: () => withTwin(async (t) => {
+    await t.call('AddSearchAttributes', { searchAttributes: { gone: 'INDEXED_VALUE_TYPE_KEYWORD' } });
+    await t.call('RemoveSearchAttributes', { searchAttributes: ['gone'] });
+    const again = await t.call('RemoveSearchAttributes', { searchAttributes: ['gone'] });
+    return (await t.call('ListSearchAttributes')).customAttributes?.gone === undefined && again.grpcError === 5;
+  }) },
+  Check: { tier: 'common', verify: () => withTwin(async (t) => (await t.call('Check', { service: '' })).status === 'SERVING'
+    && (await t.call('Check', { service: 'temporal.api.workflowservice.v1.WorkflowService' })).status === 'SERVING'
+    && (await t.call('Check', { service: 'no.such.Service' })).grpcError === 5) },
+};
+
+// ---- the command verifies (the history service's surface) ----------------------------------------
+
+const COMMAND_VERIFY: Record<string, { tier: CapabilitySpec['tier']; verify: () => Promise<boolean> }> = {
+  COMMAND_TYPE_SCHEDULE_ACTIVITY_TASK: { tier: 'core', verify: () => withTwin(async (t) => {
+    const { events } = await afterFirstTask(t, 'sat', [activityCommand('a1', { scheduleToCloseTimeout: { seconds: 30 }, startToCloseTimeout: { seconds: 60 } })]);
+    const scheduled = events.at(-1)?.activityTaskScheduledEventAttributes;
+    const dup = await t.call('SignalWorkflowExecution', { workflowExecution: { workflowId: 'sat' }, signalName: 's' });
+    const task = await t.pollWorkflow();
+    await t.complete(task, [activityCommand('a1')]);
+    const failed = (await t.events('sat')).find((e) => e.eventType === 'EVENT_TYPE_WORKFLOW_TASK_FAILED');
+    // the server's defaults: start-to-close capped at schedule-to-close, the default retry policy filled
+    return scheduled?.activityId === 'a1' && scheduled.startToCloseTimeout?.seconds === 30 && scheduled.retryPolicy?.backoffCoefficient === 2
+      && scheduled.retryPolicy?.initialInterval?.seconds === 1 && dup.grpcError === undefined
+      && failed?.workflowTaskFailedEventAttributes?.cause === 'WORKFLOW_TASK_FAILED_CAUSE_SCHEDULE_ACTIVITY_DUPLICATE_ID';
+  }) },
+  COMMAND_TYPE_REQUEST_CANCEL_ACTIVITY_TASK: { tier: 'common', verify: () => withTwin(async (t) => {
+    await t.start('rcat');
+    await t.complete(await t.pollWorkflow(), [activityCommand('a1')]);
+    await t.call('SignalWorkflowExecution', { workflowExecution: { workflowId: 'rcat' }, signalName: 's' });
+    await t.complete(await t.pollWorkflow(), [command('COMMAND_TYPE_REQUEST_CANCEL_ACTIVITY_TASK', { scheduledEventId: 5 })]);
+    const events = types(await t.events('rcat'));
+    // never started: canceled at once, and the workflow hears of it
+    return events.includes('ACTIVITY_TASK_CANCEL_REQUESTED') && events.includes('ACTIVITY_TASK_CANCELED') && events.at(-1) === 'WORKFLOW_TASK_SCHEDULED';
+  }) },
+  COMMAND_TYPE_START_TIMER: { tier: 'core', verify: () => withTwin(async (t) => {
+    await afterFirstTask(t, 'timer', [command('COMMAND_TYPE_START_TIMER', { timerId: 't1', startToFireTimeout: { seconds: 3600 } })]);
+    await t.advance(3_599_000);
+    const early = types(await t.events('timer'));
+    await t.advance(1000);
+    const events = await t.events('timer');
+    const fired = events.find((e) => e.eventType === 'EVENT_TYPE_TIMER_FIRED');
+    return !early.includes('TIMER_FIRED') && fired?.timerFiredEventAttributes?.timerId === 't1'
+      && fired.eventTime?.seconds === Date.parse(T0) / 1000 + 3600 && types(events).at(-1) === 'WORKFLOW_TASK_SCHEDULED';
+  }) },
+  COMMAND_TYPE_CANCEL_TIMER: { tier: 'common', verify: () => withTwin(async (t) => {
+    await afterFirstTask(t, 'ct', [command('COMMAND_TYPE_START_TIMER', { timerId: 't1', startToFireTimeout: { seconds: 10 } })]);
+    await t.call('SignalWorkflowExecution', { workflowExecution: { workflowId: 'ct' }, signalName: 's' });
+    await t.complete(await t.pollWorkflow(), [command('COMMAND_TYPE_CANCEL_TIMER', { timerId: 't1' })]);
+    await t.advance(20_000);
+    const events = types(await t.events('ct'));
+    return events.includes('TIMER_CANCELED') && !events.includes('TIMER_FIRED');
+  }) },
+  COMMAND_TYPE_COMPLETE_WORKFLOW_EXECUTION: { tier: 'core', verify: () => withTwin(async (t) => {
+    const { events } = await afterFirstTask(t, 'cw', [completeCommand({ ok: true })]);
+    const last = events.at(-1)!;
+    return last.eventType === 'EVENT_TYPE_WORKFLOW_EXECUTION_COMPLETED' && (payloadValue(last.workflowExecutionCompletedEventAttributes?.result?.payloads?.[0]) as Obj)?.ok === true
+      && (await t.describe('cw')).workflowExecutionInfo?.status === 'WORKFLOW_EXECUTION_STATUS_COMPLETED';
+  }) },
+  COMMAND_TYPE_FAIL_WORKFLOW_EXECUTION: { tier: 'core', verify: () => withTwin(async (t) => {
+    const { events } = await afterFirstTask(t, 'fw', [command('COMMAND_TYPE_FAIL_WORKFLOW_EXECUTION', { failure: { message: 'bad' } })]);
+    const last = events.at(-1)!;
+    return last.eventType === 'EVENT_TYPE_WORKFLOW_EXECUTION_FAILED' && last.workflowExecutionFailedEventAttributes?.failure?.message === 'bad'
+      && last.workflowExecutionFailedEventAttributes.retryState === 'RETRY_STATE_RETRY_POLICY_NOT_SET';
+  }) },
+  COMMAND_TYPE_CANCEL_WORKFLOW_EXECUTION: { tier: 'common', verify: () => withTwin(async (t) => {
+    const { events } = await afterFirstTask(t, 'cwe', [command('COMMAND_TYPE_CANCEL_WORKFLOW_EXECUTION', { details: { payloads: [jsonPayload('d')] } })]);
+    return events.at(-1)?.eventType === 'EVENT_TYPE_WORKFLOW_EXECUTION_CANCELED' && payloadValue(events.at(-1)!.workflowExecutionCanceledEventAttributes?.details?.payloads?.[0]) === 'd';
+  }) },
+  COMMAND_TYPE_CONTINUE_AS_NEW_WORKFLOW_EXECUTION: { tier: 'core', verify: () => withTwin(async (t) => {
+    const { runId, events } = await afterFirstTask(t, 'can', [command('COMMAND_TYPE_CONTINUE_AS_NEW_WORKFLOW_EXECUTION', { workflowType: { name: 'wf' }, taskQueue: { name: 'q' }, input: { payloads: [jsonPayload(2)] } })]);
+    const continued = events.at(-1)!.workflowExecutionContinuedAsNewEventAttributes;
+    const next = await t.describe('can');
+    const nextEvents = await t.events('can');
+    const started = nextEvents[0]!.workflowExecutionStartedEventAttributes;
+    return UUID.test(continued?.newExecutionRunId) && next.workflowExecutionInfo?.execution?.runId === continued.newExecutionRunId
+      && next.workflowExecutionInfo.firstRunId === runId && started?.continuedExecutionRunId === runId && payloadValue(started.input?.payloads?.[0]) === 2
+      && (await t.describe('can', runId)).workflowExecutionInfo?.status === 'WORKFLOW_EXECUTION_STATUS_CONTINUED_AS_NEW';
+  }) },
+  COMMAND_TYPE_RECORD_MARKER: { tier: 'core', verify: () => withTwin(async (t) => {
+    const { events } = await afterFirstTask(t, 'rm', [command('COMMAND_TYPE_RECORD_MARKER', { markerName: 'core_patch', details: { patch_data: { payloads: [jsonPayload({ id: 'p1' })] } } })]);
+    const marker = events.at(-1)!.markerRecordedEventAttributes;
+    return marker?.markerName === 'core_patch' && (payloadValue(marker.details?.patch_data?.payloads?.[0]) as Obj)?.id === 'p1';
+  }) },
+  COMMAND_TYPE_UPSERT_WORKFLOW_SEARCH_ATTRIBUTES: { tier: 'common', verify: () => withTwin(async (t) => {
+    await t.call('AddSearchAttributes', { searchAttributes: { stage: 'INDEXED_VALUE_TYPE_KEYWORD' } });
+    await afterFirstTask(t, 'usa', [command('COMMAND_TYPE_UPSERT_WORKFLOW_SEARCH_ATTRIBUTES', { searchAttributes: { indexedFields: { stage: jsonPayload('two'), TemporalChangeVersion: jsonPayload(['p-1']) } } })]);
+    const listed = await t.call('ListWorkflowExecutions', { query: 'stage = "two"' });
+    return listed.executions?.[0]?.execution?.workflowId === 'usa';
+  }) },
+  COMMAND_TYPE_MODIFY_WORKFLOW_PROPERTIES: { tier: 'niche', verify: () => withTwin(async (t) => {
+    await afterFirstTask(t, 'mwp', [command('COMMAND_TYPE_MODIFY_WORKFLOW_PROPERTIES', { upsertedMemo: { fields: { note: jsonPayload('n') } } })]);
+    return payloadValue((await t.describe('mwp')).workflowExecutionInfo?.memo?.fields?.note) === 'n';
+  }) },
+  COMMAND_TYPE_START_CHILD_WORKFLOW_EXECUTION: { tier: 'core', verify: () => withTwin(async (t) => {
+    const { runId } = await afterFirstTask(t, 'parent', [command('COMMAND_TYPE_START_CHILD_WORKFLOW_EXECUTION', { workflowId: 'child', workflowType: { name: 'kid' }, taskQueue: { name: 'q' }, parentClosePolicy: 'PARENT_CLOSE_POLICY_ABANDON' })]);
+    const child = await t.describe('child');
+    const parentEvents = types(await t.events('parent'));
+    // the parent's next task, then the child's; the child completes and the parent hears it
+    const next = await t.pollWorkflow();
+    await t.complete(next, []);
+    const childTask = await t.pollWorkflow();
+    await t.complete(childTask, [completeCommand('grown')]);
+    const closed = (await t.events('parent')).find((e) => e.eventType === 'EVENT_TYPE_CHILD_WORKFLOW_EXECUTION_COMPLETED');
+    return child.workflowExecutionInfo?.parentExecution?.runId === runId && parentEvents.includes('CHILD_WORKFLOW_EXECUTION_STARTED')
+      && childTask.workflowType?.name === 'kid' && payloadValue(closed?.childWorkflowExecutionCompletedEventAttributes?.result?.payloads?.[0]) === 'grown';
+  }) },
+  COMMAND_TYPE_SIGNAL_EXTERNAL_WORKFLOW_EXECUTION: { tier: 'common', verify: () => withTwin(async (t) => {
+    await t.start('target', { taskQueue: { name: 'elsewhere' } });
+    await afterFirstTask(t, 'sender', [command('COMMAND_TYPE_SIGNAL_EXTERNAL_WORKFLOW_EXECUTION', { execution: { workflowId: 'target' }, signalName: 'hey', input: { payloads: [jsonPayload('x')] } })]);
+    const target = (await t.events('target')).find((e) => e.eventType === 'EVENT_TYPE_WORKFLOW_EXECUTION_SIGNALED');
+    return target?.workflowExecutionSignaledEventAttributes?.signalName === 'hey' && types(await t.events('sender')).includes('EXTERNAL_WORKFLOW_EXECUTION_SIGNALED');
+  }) },
+  COMMAND_TYPE_REQUEST_CANCEL_EXTERNAL_WORKFLOW_EXECUTION: { tier: 'niche', verify: () => withTwin(async (t) => {
+    await t.start('victim', { taskQueue: { name: 'elsewhere' } });
+    await afterFirstTask(t, 'canceler', [
+      command('COMMAND_TYPE_REQUEST_CANCEL_EXTERNAL_WORKFLOW_EXECUTION', { workflowId: 'missing' }),
+      command('COMMAND_TYPE_REQUEST_CANCEL_EXTERNAL_WORKFLOW_EXECUTION', { workflowId: 'victim' }),
+    ]);
+    const canceler = await t.events('canceler');
+    const failed = canceler.find((e) => e.eventType === 'EVENT_TYPE_REQUEST_CANCEL_EXTERNAL_WORKFLOW_EXECUTION_FAILED');
+    const requested = canceler.find((e) => e.eventType === 'EVENT_TYPE_EXTERNAL_WORKFLOW_EXECUTION_CANCEL_REQUESTED');
+    const victim = (await t.events('victim')).find((e) => e.eventType === 'EVENT_TYPE_WORKFLOW_EXECUTION_CANCEL_REQUESTED');
+    return failed?.requestCancelExternalWorkflowExecutionFailedEventAttributes?.cause === 'CANCEL_EXTERNAL_WORKFLOW_EXECUTION_FAILED_CAUSE_EXTERNAL_WORKFLOW_EXECUTION_NOT_FOUND'
+      && requested?.externalWorkflowExecutionCancelRequestedEventAttributes?.workflowExecution?.workflowId === 'victim'
+      && victim?.workflowExecutionCancelRequestedEventAttributes?.externalWorkflowExecution?.workflowId === 'canceler';
+  }) },
+};
+
+// ---- behaviours no one RPC owns --------------------------------------------------------------------
+
+const HISTORY: CapabilitySpec[] = [
+  done('temporal.history.activity_retry', 'history', 'a failed activity attempt retries with the retry policy\'s backoff on the World clock, invisibly to the history until it closes', 'core', () => withTwin(async (t) => {
+    await afterFirstTask(t, 'retry', [activityCommand('a1', { retryPolicy: { initialInterval: { seconds: 2 }, backoffCoefficient: 1, maximumAttempts: 3 } })]);
+    const first = await t.pollActivity();
+    await t.call('RespondActivityTaskFailed', { taskToken: first.taskToken, failure: { message: 'try again' } });
+    const tooSoon = await t.pollActivity();
+    await t.advance(2000);
+    const second = await t.pollActivity();
+    await t.call('RespondActivityTaskCompleted', { taskToken: second.taskToken, result: { payloads: [jsonPayload('ok')] } });
+    const events = await t.events('retry');
+    const started = events.find((e) => e.eventType === 'EVENT_TYPE_ACTIVITY_TASK_STARTED')!.activityTaskStartedEventAttributes;
+    return tooSoon.taskToken === undefined && second.attempt === 2 && started?.attempt === 2 && started.lastFailure?.message === 'try again'
+      && types(events).filter((e) => e.startsWith('ACTIVITY_TASK_')).join() === 'ACTIVITY_TASK_SCHEDULED,ACTIVITY_TASK_STARTED,ACTIVITY_TASK_COMPLETED';
+  })),
+  done('temporal.history.activity_timeouts', 'history', 'start-to-close and heartbeat timeouts on the World clock, the last heartbeat details carried in the timeout failure', 'core', () => withTwin(async (t) => {
+    await afterFirstTask(t, 'hbt', [activityCommand('a1', { heartbeatTimeout: { seconds: 5 }, retryPolicy: { maximumAttempts: 1 } })]);
+    const task = await t.pollActivity();
+    await t.call('RecordActivityTaskHeartbeat', { taskToken: task.taskToken, details: { payloads: [jsonPayload('x: publishing')] } });
+    await t.advance(5000);
+    const timedOut = (await t.events('hbt')).find((e) => e.eventType === 'EVENT_TYPE_ACTIVITY_TASK_TIMED_OUT')?.activityTaskTimedOutEventAttributes;
+    return timedOut?.failure?.timeoutFailureInfo?.timeoutType === 'TIMEOUT_TYPE_HEARTBEAT' && payloadValue(timedOut.failure.timeoutFailureInfo.lastHeartbeatDetails?.payloads?.[0]) === 'x: publishing'
+      && timedOut.retryState === 'RETRY_STATE_MAXIMUM_ATTEMPTS_REACHED';
+  })),
+  done('temporal.history.buffered_events', 'history', 'events arriving during a workflow task are appended after it; a completion that would close over them is refused UNHANDLED_COMMAND', 'core', () => withTwin(async (t) => {
+    await t.start('buf');
+    const task = await t.pollWorkflow();
+    await t.call('SignalWorkflowExecution', { workflowExecution: { workflowId: 'buf' }, signalName: 'late' });
+    await t.complete(task, [completeCommand('too early')]);
+    const events = types(await t.events('buf'));
+    return events.join() === 'WORKFLOW_EXECUTION_STARTED,WORKFLOW_TASK_SCHEDULED,WORKFLOW_TASK_STARTED,WORKFLOW_TASK_FAILED,WORKFLOW_EXECUTION_SIGNALED,WORKFLOW_TASK_SCHEDULED'
+      && (await t.describe('buf')).workflowExecutionInfo?.status === 'WORKFLOW_EXECUTION_STATUS_RUNNING';
+  })),
+  done('temporal.history.workflow_task_timeout', 'history', 'a workflow task not completed within its start-to-close timeout times out and is scheduled again', 'common', () => withTwin(async (t) => {
+    await t.start('wtt', { workflowTaskTimeout: { seconds: 5 } });
+    const task = await t.pollWorkflow();
+    await t.advance(5000);
+    const late = await t.complete(task, []);
+    const retry = await t.pollWorkflow();
+    return late.grpcError === 5 && retry.attempt === 2 && types(await t.events('wtt')).includes('WORKFLOW_TASK_TIMED_OUT');
+  })),
+  done('temporal.history.workflow_timeouts', 'history', 'a run timeout closes the run TimedOut on the World clock', 'common', () => withTwin(async (t) => {
+    await afterFirstTask(t, 'rto', [], { workflowRunTimeout: { seconds: 60 } });
+    await t.advance(60_000);
+    return (await t.describe('rto')).workflowExecutionInfo?.status === 'WORKFLOW_EXECUTION_STATUS_TIMED_OUT';
+  })),
+  done('temporal.history.workflow_retry', 'history', 'a workflow with a retry policy that fails is retried as a new run of the same chain after the backoff', 'common', () => withTwin(async (t) => {
+    const { runId } = await afterFirstTask(t, 'wr', [command('COMMAND_TYPE_FAIL_WORKFLOW_EXECUTION', { failure: { message: 'first' } })], { retryPolicy: { initialInterval: { seconds: 10 }, maximumAttempts: 2 } });
+    const failed = (await t.events('wr', runId)).at(-1)!.workflowExecutionFailedEventAttributes;
+    await t.advance(10_000);
+    const task = await t.pollWorkflow();
+    return failed?.retryState === 'RETRY_STATE_IN_PROGRESS' && UUID.test(failed.newExecutionRunId) && task.workflowExecution?.runId === failed.newExecutionRunId && task.workflowExecution.workflowId === 'wr';
+  })),
+  done('temporal.history.parent_close_policy', 'history', 'closing a parent terminates its TERMINATE children and leaves ABANDON children running', 'common', () => withTwin(async (t) => {
+    await afterFirstTask(t, 'pcp', [
+      command('COMMAND_TYPE_START_CHILD_WORKFLOW_EXECUTION', { workflowId: 'kept', workflowType: { name: 'kid' }, taskQueue: { name: 'other' }, parentClosePolicy: 'PARENT_CLOSE_POLICY_ABANDON' }),
+      command('COMMAND_TYPE_START_CHILD_WORKFLOW_EXECUTION', { workflowId: 'ended', workflowType: { name: 'kid' }, taskQueue: { name: 'other' } }),
+    ]);
+    await t.call('TerminateWorkflowExecution', { workflowExecution: { workflowId: 'pcp' } });
+    return (await t.describe('kept')).workflowExecutionInfo?.status === 'WORKFLOW_EXECUTION_STATUS_RUNNING'
+      && (await t.describe('ended')).workflowExecutionInfo?.status === 'WORKFLOW_EXECUTION_STATUS_TERMINATED';
+  })),
+  done('temporal.history.start_delay', 'history', 'a start delay holds the first workflow task until the World clock reaches it', 'niche', () => withTwin(async (t) => {
+    await t.start('sd', { workflowStartDelay: { seconds: 30 } });
+    const early = await t.pollWorkflow();
+    await t.advance(30_000);
+    const task = await t.pollWorkflow();
+    return early.taskToken === undefined && task.startedEventId === 3;
+  })),
+  done('temporal.history.state_in_the_world', 'history', 'a run is a World subject (workflow-execution) whose history chunks live in the World\'s blob store', 'core', () => withTwin(async (t) => {
+    const runId = await t.start('world');
+    const subject = twinResources('temporal', t.root).find((r) => r.type === 'workflow-execution' && r.id === runId) as Obj | undefined;
+    const reread = new TemporalEngine({ root: t.root });
+    const events = await reread.history(reread.run(runId)!);
+    return subject?.status === 'WORKFLOW_EXECUTION_STATUS_RUNNING' && Array.isArray(subject._state?.history) && subject._state.history.length === 1 && events.length === 2;
+  })),
+  todo('temporal.history.sticky_queues', 'history', 'sticky task queues (tasks routed to the worker that holds the run, with partial history) — every task goes to the normal queue with its full history, which the SDKs accept', 'niche'),
+  todo('temporal.history.cron', 'history', 'cron schedules on start, child and continue-as-new (refused UNIMPLEMENTED / FEATURE_DISABLED by name)', 'niche'),
+  todo('temporal.history.updates', 'history', 'workflow updates (protocol messages in workflow tasks) — UpdateWorkflowExecution answers UNIMPLEMENTED', 'common'),
+  todo('temporal.history.eager_execution', 'history', 'eager workflow start and eager activity dispatch (the SDKs fall back to polling when a server declines)', 'niche'),
+  todo('temporal.history.completion_callbacks', 'history', 'completion callbacks and links (Nexus-backed), refused UNIMPLEMENTED on start', 'niche'),
+  todo('temporal.history.worker_versioning', 'history', 'worker deployments, build ids and versioning overrides', 'niche'),
+  todo('temporal.history.transient_workflow_task_attempts', 'history', 'workflow-task attempts after the first kept transient (the server writes them only once a task completes); every failed attempt is written, so a crash-looping workflow grows its history', 'common'),
+  todo('temporal.history.retention', 'history', 'the namespace retention period: closed runs are kept until the World is purged, never deleted after retention', 'niche'),
+  todo('temporal.history.search_attribute_types', 'history', 'search-attribute values checked against their declared type (only names are checked)', 'niche'),
+  todo('temporal.history.visibility_literal_types', 'history', 'list-filter literals checked against the attribute type (a duration literal such as "10m" on ExecutionDuration, Datetime custom attributes compared as instants, a number against a Keyword) — such a filter matches nothing rather than being read or refused', 'niche'),
+  todo('temporal.history.text_search', 'history', 'Text search attributes are matched by equality, not tokenized full-text search as Elasticsearch/SQL visibility does', 'niche'),
+];
+
+const WIRE: CapabilitySpec[] = [
+  todo('temporal.wire.tls', 'wire', 'TLS and mTLS on the frontend (an SDK configured with an api key turns TLS on; this loopback server speaks h2c only)', 'common'),
+  todo('temporal.wire.compression', 'wire', 'grpc-encoding (gzip) message compression — a compressed message is refused UNIMPLEMENTED', 'niche'),
+  todo('temporal.wire.status_details', 'wire', 'google.rpc.Status details (grpc-status-details-bin: WorkflowExecutionAlreadyStartedFailure, NotFoundFailure …) on errors', 'common'),
+  done('temporal.wire.http_api', 'wire', 'the frontend\'s HTTP API: the protos\' google.api.http routes for every served method, proto3 JSON in and out, gateway error bodies', 'niche', () => withTwin(async (t) => {
+    const fetch = createTemporalTwinFetch({ root: t.root, engine: t.engine });
+    const call = async (method: string, path: string, body?: unknown) => {
+      const response = await fetch(new Request(`http://twin.local${path}`, { method, ...(body === undefined ? {} : { body: JSON.stringify(body) }) }));
+      return { status: response.status, body: await response.json() as Obj };
+    };
+    const started = await call('POST', '/api/v1/namespaces/default/workflows/via-http', { workflowType: { name: 'wf' }, taskQueue: { name: 'q' }, requestId: 'h1' });
+    const described = await call('GET', '/namespaces/default/workflows/via-http');
+    const missing = await call('GET', '/api/v1/namespaces/default/workflows/none');
+    return UUID.test(started.body.runId) && described.body.workflowExecutionInfo?.execution?.runId === started.body.runId
+      && described.body.workflowExecutionInfo.historyLength === '2' && described.body.workflowExecutionInfo.startTime === T0
+      && missing.status === 404 && missing.body.code === 5;
+  })),
+  todo('temporal.wire.http_payload_shorthand', 'wire', 'the HTTP API\'s payload shorthand (a bare JSON value for a json/plain payload); payloads travel in their full { metadata, data } form', 'niche'),
+];
+
+const CONNECTOR: CapabilitySpec[] = [
+  done('temporal.connector.pull', 'connector', 'pull a real frontend\'s namespaces and custom search attributes into the World', 'common', () => withTwin(async (t) => {
+    const execute = async (_service: string, method: string, request: Obj): Promise<Obj> => {
+      if (method === 'ListNamespaces') return { namespaces: [{ namespaceInfo: { name: 'prod', state: 'NAMESPACE_STATE_REGISTERED', id: 'n-1' }, config: {} }] };
+      if (method === 'ListSearchAttributes' && request.namespace === 'prod') return { customAttributes: { postId: 'INDEXED_VALUE_TYPE_TEXT' } };
+      throw new Error(`unexpected ${method}`);
+    };
+    const { pulled } = await syncTemporalFromReal(execute, { root: t.root, occurredAt: T0 });
+    return pulled === 1 && (await t.call('DescribeNamespace', { namespace: 'prod' })).namespaceInfo?.id === 'n-1'
+      && (await t.call('ListSearchAttributes', { namespace: 'prod' })).customAttributes?.postId === 'INDEXED_VALUE_TYPE_TEXT';
+  })),
+  todo('temporal.connector.pull_runs', 'connector', 'pull a real cluster\'s workflow runs (a run is its history, advanced by workers; not modeled)', 'niche'),
+  todo('temporal.connector.push', 'connector', 'perform a World\'s local runs on a real cluster (refused by name: pushPendingTemporalActions)', 'niche'),
+];
+
+
+const TIER_OF: Record<string, CapabilitySpec['tier']> = {
+  CreateSchedule: 'common', DescribeSchedule: 'common', ListSchedules: 'common', DeleteSchedule: 'common', UpdateSchedule: 'common', PatchSchedule: 'common',
+  UpdateWorkflowExecution: 'common', PollWorkflowExecutionUpdate: 'common', ExecuteMultiOperation: 'common', DescribeTaskQueue: 'common',
+  ResetWorkflowExecution: 'common', GetWorkflowExecutionHistoryReverse: 'common', ScanWorkflowExecutions: 'niche', RecordWorkerHeartbeat: 'common',
+  ListOpenWorkflowExecutions: 'niche', ListClosedWorkflowExecutions: 'niche', DeleteWorkflowExecution: 'common', UpdateNamespace: 'common',
+};
+
+function rpcCapabilities(service: string, area: string): CapabilitySpec[] {
+  return [...serviceMethods(service).entries()].map(([method, shape]) => {
+    const id = `temporal.${area}.${method.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase()}`;
+    const served = Boolean(SERVED[service]?.[method]);
+    const proof = RPC_VERIFY[method];
+    if (served && proof) return done(id, area, `${method}`, proof.tier, proof.verify);
+    const note = shape.requestStream || shape.responseStream ? ' (streaming; this server answers unary calls only)' : '';
+    return todo(id, area, `${method} — answers gRPC UNIMPLEMENTED${note}`, TIER_OF[method] ?? 'niche');
+  });
+}
+
+function commandCapabilities(): CapabilitySpec[] {
+  const values = Object.keys((temporalRoot.lookupEnum('temporal.api.enums.v1.CommandType')).values).filter((name) => name !== 'COMMAND_TYPE_UNSPECIFIED').sort();
+  return values.map((name) => {
+    const id = `temporal.commands.${name.replace('COMMAND_TYPE_', '').toLowerCase()}`;
+    const proof = COMMAND_VERIFY[name];
+    return proof ? done(id, 'commands', name, proof.tier, proof.verify) : todo(id, 'commands', `${name} — fails the workflow task with WORKFLOW_TASK_FAILED_CAUSE_FEATURE_DISABLED`, 'niche');
+  });
+}
+
+export const TEMPORAL_CAPABILITIES: CapabilitySpec[] = [
+  ...rpcCapabilities(WORKFLOW_SERVICE, 'workflowservice'),
+  ...rpcCapabilities(OPERATOR_SERVICE, 'operatorservice'),
+  ...rpcCapabilities(HEALTH_SERVICE, 'health'),
+  ...commandCapabilities(),
+  ...HISTORY,
+  ...WIRE,
+  ...CONNECTOR,
+];
+
+/** Committed area census: the three services of the vendored protos, the command table, the history
+ *  service's own behaviours, the wire, and the connector. A committed literal, so a shrinking
+ *  regeneration reddens instead of silently dropping an area. */
+export const TEMPORAL_AREAS = [
+  'commands',
+  'connector',
+  'health',
+  'history',
+  'operatorservice',
+  'wire',
+  'workflowservice',
+] as const;
+
+export function temporalCapabilities(): Promise<CapabilityReport> {
+  return checkCapabilities('temporal', TEMPORAL_CAPABILITIES);
+}