@volter/twin-temporal 0.1.0

package/src/temporal-history.ts

@@ -0,0 +1,99 @@
+// THE ENGINE SLOT — where a workflow's history lives (docs/contributing/architecture.md#the-engine-slot).
+//
+// Temporal's state has two halves. What a list or a describe answers — a run's status, type, task
+// queue, search attributes, and the server's own bookkeeping for it (pending tasks, timers, buffered
+// events) — is a tree subject, `workflow-execution`, written through the kernel's write path like any
+// pack's resource. The run's HISTORY is the other half: an append-only sequence of events a worker
+// replays in full on every workflow task. Folding it into the subject would make each append rewrite
+// every event before it, so it sits beside the tree as content-addressed chunks in the World's blob
+// store (one chunk per transition's new events, keyed by its sha256), and the subject names its
+// chunks in order (`_state.history`). A branch reads its chunks through `readResourceBlob`, which
+// falls back to the ancestors that wrote them, so a fork replays exactly the history its tree names.
+//
+// This module is the only one that writes outside the tree, and it does so only through the blob
+// store: no file, no database. Everything else reads through `TemporalStore`.
+import { applyTwinWrite, blobDigest, getActiveBlobStore, readResourceBlob, resourceChain, twinResourcesOfType, ownFields, worldNow } from '@volter/world-core';
+import { join } from 'node:path';
+
+export const TEMPORAL_SERVICE = 'temporal';
+
+/** A history event in the engine's plain form (temporal-proto.ts `OBJECT`): `eventId`, `eventTime`,
+ *  `eventType` and one `<kind>EventAttributes`. */
+export type HistoryEvent = Record<string, unknown> & { eventId: number; eventType: string };
+
+/** A stored subject: its fields as written (the kernel's `id`/`type`/`updatedAt` are its own). */
+export type Stored = Record<string, unknown> & { id: string };
+
+const chunkCache = new Map<string, HistoryEvent[]>(); // cache: a key names one immutable chunk; bounded, per root
+/** Chunks held in memory; past this the least recently used go (a long-lived host reads the rest back). */
+const CHUNK_CACHE_LIMIT = 4096;
+
+function remember(key: string, events: HistoryEvent[]): void {
+  chunkCache.delete(key);
+  chunkCache.set(key, events);
+  while (chunkCache.size > CHUNK_CACHE_LIMIT) chunkCache.delete(chunkCache.keys().next().value!);
+}
+
+export class TemporalStore {
+  readonly root: string | undefined;
+
+  constructor(root?: string) {
+    this.root = root;
+  }
+
+  /** Every subject of one type, as its own fields. READ-ONLY: the kernel's memoized tree and parsed
+   *  log rows share nested objects with what this hands out, so a caller that changes a subject
+   *  copies it first (the engine's RunTx does, deeply) — editing one in place corrupts the log the
+   *  kernel digests. */
+  list(type: string): Stored[] {
+    return twinResourcesOfType(TEMPORAL_SERVICE, type, this.root).map((resource) => ({ ...ownFields(resource), id: resource.id }) as Stored);
+  }
+
+  get(type: string, id: string): Stored | undefined {
+    return this.list(type).find((subject) => subject.id === id);
+  }
+
+  /** Write one subject (all of its fields) under `operation`, the RPC or the server act that moved it. */
+  async put(type: string, id: string, fields: Record<string, unknown>, operation: string, input?: Record<string, unknown>): Promise<void> {
+    await applyTwinWrite(TEMPORAL_SERVICE, {
+      operation,
+      subjectType: type,
+      subjectId: id,
+      // exactly what the log will hold: a JSON round trip drops undefined members, so the entry the
+      // kernel keeps in memory is the one it reads back (its history digests compare the two)
+      fields: JSON.parse(JSON.stringify(fields)) as Record<string, unknown>,
+      ...(input ? { input } : {}),
+      occurredAt: worldNow(),
+    }, this.root);
+  }
+
+  /** Store a run's new events as one chunk; answers the chunk's key for the subject to name. */
+  async appendChunk(events: HistoryEvent[]): Promise<string> {
+    const bytes = new TextEncoder().encode(JSON.stringify(events));
+    const key = `history/${blobDigest(bytes)}.json`;
+    const dir = resourceChain(TEMPORAL_SERVICE, this.root)[0]!;
+    await getActiveBlobStore().put(join(dir, key), bytes);
+    // keyed by root: a branch's first read of a chunk goes through the blob store's ancestry, so a
+    // chunk missing from it is seen as missing, not served from another root's memory
+    remember(`${this.root ?? ''}\0${key}`, events);
+    return key;
+  }
+
+  /** A run's events, in order, from the chunks its subject names. */
+  async readChunks(keys: string[]): Promise<HistoryEvent[]> {
+    const out: HistoryEvent[] = [];
+    for (const key of keys) {
+      const cacheKey = `${this.root ?? ''}\0${key}`;
+      let events = chunkCache.get(cacheKey);
+      if (events) remember(cacheKey, events);
+      if (!events) {
+        const bytes = await readResourceBlob(TEMPORAL_SERVICE, key, this.root);
+        if (bytes === null) throw new Error(`temporal: history chunk ${key} is missing from the World's blob store`);
+        events = JSON.parse(new TextDecoder().decode(bytes)) as HistoryEvent[];
+        remember(cacheKey, events);
+      }
+      out.push(...events);
+    }
+    return out;
+  }
+}

package/src/temporal-http.ts

@@ -0,0 +1,146 @@
+// THE HTTP API — the frontend's HTTP/JSON surface (Temporal serves it on :7243 beside gRPC's :7233),
+// routed by the google.api.http annotations the vendored protos carry on each method, over the same
+// RPC table as the gRPC wire: a served method answers here exactly what it answers there, and every
+// other annotated route answers 501 with the gRPC-gateway error body. Bodies and answers are proto3
+// JSON (temporal-json.ts); the twin's own doors (GET /twin, the store) ride the same fetch.
+//
+// This is also the twin's fetch surface for the World (createTemporalTwinFetch): its doors, the
+// replay the invariants run, and a hosted World's in-process wire all come through here.
+import { createTwinFetchFromHandler, statefulTwinManifest, WORLD_BOOT_PATH, type TwinFetchHandlerRequest, type TwinFetchHandlerResult } from '@volter/world-core';
+import type protobuf from 'protobufjs';
+import { handleTemporalCall, SERVED } from './temporal-twin.ts';
+import { engineForRoot, executionInfo, type TemporalEngine } from './temporal-engine.ts';
+import { GrpcError, GrpcStatus } from './temporal-grpc.ts';
+import { fromProto3Json, toProto3Json } from './temporal-json.ts';
+import { OPERATOR_SERVICE, WORKFLOW_SERVICE, serviceMethods, temporalRoot } from './temporal-proto.ts';
+
+type Obj = Record<string, unknown>;
+type Route = { verb: string; pattern: RegExp; params: string[]; body: string | undefined; service: string; method: string; requestType: protobuf.Type; responseType: protobuf.Type };
+
+/** gRPC status → HTTP status, as grpc-gateway maps them (runtime/errors.go HTTPStatusFromCode). */
+const HTTP_STATUS: Record<number, number> = {
+  0: 200, 1: 499, 2: 500, 3: 400, 4: 504, 5: 404, 6: 409, 7: 403, 8: 429, 9: 400, 10: 409, 11: 400, 12: 501, 13: 500, 14: 503, 15: 500, 16: 401,
+};
+
+function routesOf(service: string): Route[] {
+  const out: Route[] = [];
+  const methods = temporalRoot.lookupService(service).methods;
+  for (const [method, shape] of serviceMethods(service)) {
+    // the annotations, as protobufjs keeps a method's options: `(google.api.http).post` → the path
+    const declared = (methods[method]!.options ?? {}) as Record<string, string>;
+    const bindings: Array<{ verb: string; path: string; body?: string }> = [];
+    for (const prefix of ['(google.api.http)', '(google.api.http).additional_bindings']) {
+      for (const verb of ['get', 'post', 'put', 'patch', 'delete']) {
+        const path = declared[`${prefix}.${verb}`];
+        if (path) bindings.push({ verb: verb.toUpperCase(), path, ...(declared[`${prefix}.body`] ? { body: declared[`${prefix}.body`] } : {}) });
+      }
+    }
+    for (const binding of bindings) {
+      const params: string[] = [];
+      const source = binding.path.split(/(\{[^}]+\})/).map((part) => {
+        const variable = /^\{([a-z0-9_.]+)(?:=[^}]*)?\}$/.exec(part);
+        if (!variable) return part.replace(/[.*+?^$()|[\]\\]/g, '\\$&');
+        params.push(variable[1]!);
+        return '([^/]+)';
+      }).join('');
+      out.push({ verb: binding.verb, pattern: new RegExp(`^${source}$`), params, body: binding.body, service, method, requestType: shape.requestType, responseType: shape.responseType });
+    }
+  }
+  return out;
+}
+
+let routeTable: Route[] | undefined; // cache: a pure function of the committed descriptor
+function routes(): Route[] {
+  routeTable ??= [...routesOf(WORKFLOW_SERVICE), ...routesOf(OPERATOR_SERVICE)];
+  return routeTable;
+}
+
+const camel = (name: string): string => name.replace(/_([a-z0-9])/g, (_, c: string) => c.toUpperCase());
+
+/** Set a dotted proto path (`execution.workflow_id`) on a plain request. */
+function setPath(target: Obj, path: string, value: unknown): void {
+  const parts = path.split('.').map(camel);
+  let cursor = target;
+  for (const part of parts.slice(0, -1)) cursor = (cursor[part] ??= {}) as Obj;
+  cursor[parts.at(-1)!] = value;
+}
+
+/** A query-string value, typed by the field it lands on. */
+function typedQueryValue(type: protobuf.Type, path: string, raw: string): unknown {
+  let current: protobuf.Type | undefined = type;
+  let field: protobuf.Field | undefined;
+  for (const part of path.split('.').map(camel)) {
+    field = current?.fields[part];
+    if (!field) throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, `unknown query parameter "${path}"`);
+    field.resolve();
+    current = field.resolvedType && 'fields' in field.resolvedType ? field.resolvedType as protobuf.Type : undefined;
+  }
+  if (!field) return raw;
+  if (['int32', 'uint32', 'sint32', 'fixed32', 'sfixed32', 'double', 'float'].includes(field.type)) return Number(raw);
+  if (field.type === 'bool') return raw === 'true';
+  return raw;
+}
+
+/** One HTTP API request, answered through the RPC table. */
+export async function handleTemporalHttpRequest(engine: TemporalEngine, request: { method: string; path: string; body: string }): Promise<TwinFetchHandlerResult> {
+  const url = new URL(request.path, 'http://twin.local');
+  const matches = routes().filter((route) => route.pattern.test(url.pathname));
+  const route = matches.find((candidate) => candidate.verb === request.method);
+  if (!route) {
+    if (matches.length) return { status: 405, body: { code: GrpcStatus.UNIMPLEMENTED, message: `Method Not Allowed`, details: [] } };
+    return { status: 404, body: { code: GrpcStatus.NOT_FOUND, message: 'Not Found', details: [] } };
+  }
+  try {
+    let plain: Obj = {};
+    if (route.body === '*' && request.body.trim()) {
+      const parsed = JSON.parse(request.body) as unknown;
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, 'the request body must be a JSON object');
+      try { plain = fromProto3Json(route.requestType, parsed as Obj); } catch (error) { throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, (error as Error).message); }
+    } else if (route.body === undefined) {
+      for (const [name, raw] of url.searchParams) setPath(plain, name, typedQueryValue(route.requestType, name, raw));
+      try { plain = fromProto3Json(route.requestType, plain); } catch (error) { throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, (error as Error).message); }
+    }
+    let values: string[];
+    try { values = route.pattern.exec(url.pathname)!.slice(1).map(decodeURIComponent); } catch { throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, 'malformed percent-escape in the path'); }
+    route.params.forEach((param, i) => setPath(plain, param, values[i]));
+    const answer = await handleTemporalCall(engine, route.service, route.method, plain, { signal: new AbortController().signal, metadata: {} });
+    return { status: 200, body: toProto3Json(route.responseType, answer) };
+  } catch (error) {
+    if (error instanceof SyntaxError) return { status: 400, body: { code: GrpcStatus.INVALID_ARGUMENT, message: `invalid JSON body: ${error.message}`, details: [] } };
+    const code = error instanceof GrpcError ? error.code : GrpcStatus.INTERNAL;
+    return { status: HTTP_STATUS[code] ?? 500, body: { code, message: (error as Error).message, details: [] } };
+  }
+}
+
+/** Every route the HTTP API serves (the served subset of the annotated routes), for the manifest. */
+export function servedHttpRoutes(): string[] {
+  return routes().filter((route) => SERVED[route.service]?.[route.method]).map((route) => `${route.verb} ${route.pattern.source.slice(1, -1).replace(/\(\[\^\/\]\+\)/g, '{…}').replace(/\\/g, '')} → ${route.method}`);
+}
+
+export type TemporalTwinFetchOptions = { root?: string; readOnly?: boolean; engine?: TemporalEngine };
+
+/** The twin's HTTP surface: the World's doors (GET /twin, GET /twin/store/workflows) and the HTTP API. */
+export function createTemporalTwinFetch(options: TemporalTwinFetchOptions = {}): (request: Request) => Promise<Response> {
+  const engine = options.engine ?? engineForRoot({ ...(options.root !== undefined ? { root: options.root } : {}), ...(options.readOnly ? { readOnly: true } : {}) });
+  const serveDoors = createTwinFetchFromHandler((request: TwinFetchHandlerRequest) => handleTemporalHttpRequest(engine, request), {
+    ...(options.root !== undefined ? { root: options.root } : {}),
+    ...(options.readOnly ? { readOnly: true } : {}),
+    manifest: statefulTwinManifest({
+      vendor: 'temporal',
+      twinOf: 'the Temporal frontend (WorkflowService over gRPC; its HTTP API on this fetch)',
+      stores: 'namespaces, custom search attributes and workflow runs, each run\'s history as chunks beside the tree',
+      identity: 'No authentication, as Temporal\'s dev server: the gRPC wire and the HTTP API accept any caller on loopback.',
+      notes: 'Point the SDKs at TEMPORAL_ADDRESS (host:port, gRPC). Timers, timeouts and retries run on the World clock.',
+    }),
+    stores: {
+      workflows: () => engine.runs().map((run) => ({ namespace: run.namespace, ...executionInfo(run) })),
+    },
+  });
+  const boot = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env?.VOLTER_WORLD_BOOT_ID;
+  return async (request) => {
+    // the World asks each twin which boot it belongs to (serve-http.ts WORLD_BOOT_PATH); this fetch answers it itself
+    // because it is served by this pack's own listener, not the kernel's HTTP seam
+    if (boot && new URL(request.url).pathname === WORLD_BOOT_PATH) return Response.json({ boot });
+    return serveDoors(request);
+  };
+}

package/src/temporal-json.ts

@@ -0,0 +1,77 @@
+// Proto3 JSON (https://protobuf.dev/programming-guides/json/) to and from the engine's plain form, for
+// the frontend's HTTP API. The plain form already names fields in lowerCamelCase, enums by name and
+// bytes in base64; what differs is 64-bit integers (strings in JSON), google.protobuf.Timestamp
+// (RFC 3339) and google.protobuf.Duration ("1.5s"). Walked by the message type, so a field is
+// converted by what the proto says it is, never by what its value looks like.
+//
+// Payloads are carried in their full form ({ metadata, data }); the HTTP API's payload shorthand
+// (a bare JSON value standing for a json/plain payload) is not modeled.
+import type protobuf from 'protobufjs';
+import { durationMs, toDuration, toTimestamp } from './temporal-engine.ts';
+
+type Obj = Record<string, unknown>;
+const LONGS = new Set(['int64', 'uint64', 'sint64', 'fixed64', 'sfixed64']);
+
+function rfc3339(value: Obj): string {
+  const ms = Number(value.seconds ?? 0) * 1000 + Math.floor(Number(value.nanos ?? 0) / 1e6);
+  return new Date(ms).toISOString();
+}
+
+function durationText(value: Obj): string {
+  const ms = durationMs(value);
+  return `${ms % 1000 === 0 ? ms / 1000 : (ms / 1000).toFixed(3).replace(/0+$/, '')}s`;
+}
+
+function convert(field: protobuf.Field, value: unknown, direction: 'out' | 'in'): unknown {
+  field.resolve();
+  const one = (item: unknown): unknown => {
+    if (item === null || item === undefined) return item;
+    if (field.resolvedType && 'fields' in field.resolvedType) {
+      const type = field.resolvedType as protobuf.Type;
+      if (type.fullName === '.google.protobuf.Timestamp') {
+        if (direction === 'out') return rfc3339(item as Obj);
+        const ms = Date.parse(String(item));
+        if (Number.isNaN(ms)) throw new Error(`${field.name}: not an RFC 3339 timestamp`);
+        return toTimestamp(ms);
+      }
+      if (type.fullName === '.google.protobuf.Duration') {
+        if (direction === 'out') return durationText(item as Obj);
+        const match = /^(-?\d+(?:\.\d+)?)s$/.exec(String(item));
+        if (!match) throw new Error(`${field.name}: not a duration ("<seconds>s")`);
+        return toDuration(Math.round(Number(match[1]) * 1000)) ?? {};
+      }
+      return walk(type, item as Obj, direction);
+    }
+    if (LONGS.has(field.type)) return direction === 'out' ? String(item) : Number(item);
+    return item;
+  };
+  if (field.map) {
+    return Object.fromEntries(Object.entries(value as Obj).map(([key, item]) => [key, one(item)]));
+  }
+  if (field.repeated) return (value as unknown[]).map(one);
+  return one(value);
+}
+
+function walk(type: protobuf.Type, value: Obj, direction: 'out' | 'in'): Obj {
+  const out: Obj = {};
+  for (const [key, item] of Object.entries(value)) {
+    // proto3 JSON accepts the proto field name as well as the lowerCamel one
+    const field = type.fields[key] ?? type.fields[key.replace(/_([a-z0-9])/g, (_, c: string) => c.toUpperCase())];
+    if (!field) {
+      if (direction === 'in') throw new Error(`unknown field "${key}" for ${type.fullName.slice(1)}`);
+      continue;
+    }
+    out[field.name] = convert(field, item, direction);
+  }
+  return out;
+}
+
+/** The engine's plain form → proto3 JSON. */
+export function toProto3Json(type: protobuf.Type, value: Obj): Obj {
+  return walk(type, value, 'out');
+}
+
+/** Proto3 JSON → the engine's plain form (throws on an unknown field or a malformed value). */
+export function fromProto3Json(type: protobuf.Type, value: Obj): Obj {
+  return walk(type, value, 'in');
+}

package/src/temporal-proto.ts

@@ -0,0 +1,53 @@
+// THE TEMPORAL API'S TYPES — protobufjs over the committed descriptor (src/generated/temporal-api.json,
+// derived from spec/proto by ../proto-json.ts). Nothing here parses .proto text or reads a file: the
+// descriptor is a JSON import, so the serve path loads the same bytes everywhere.
+//
+// The engine keeps every message in protobufjs's plain-object form with enums as their names, 64-bit
+// integers as JS numbers, bytes as base64 strings and absent fields left out (`OBJECT`), which is
+// what a JSON column stores and what `fromObject` takes back without loss for this API: the only
+// 64-bit fields are event ids, counts and nanosecond-free seconds, all far below 2^53.
+import protobuf from 'protobufjs';
+import descriptor from './generated/temporal-api.json' with { type: 'json' };
+
+export const temporalRoot: protobuf.Root = protobuf.Root.fromJSON(descriptor as protobuf.INamespace);
+
+export const WORKFLOW_SERVICE = 'temporal.api.workflowservice.v1.WorkflowService';
+export const OPERATOR_SERVICE = 'temporal.api.operatorservice.v1.OperatorService';
+export const HEALTH_SERVICE = 'grpc.health.v1.Health';
+
+/** protobufjs's toObject options for the engine's plain form (see the header). */
+export const OBJECT: protobuf.IConversionOptions = { enums: String, longs: Number, bytes: String, defaults: false, arrays: false, objects: false, oneofs: false };
+
+const typeCache = new Map<string, protobuf.Type>(); // cache: lookups into the committed descriptor
+export function messageType(name: string): protobuf.Type {
+  let type = typeCache.get(name);
+  if (!type) {
+    type = temporalRoot.lookupType(name);
+    typeCache.set(name, type);
+  }
+  return type;
+}
+
+/** A service's methods, by name, with their request and response types. */
+export function serviceMethods(service: string): Map<string, { requestType: protobuf.Type; responseType: protobuf.Type; requestStream: boolean; responseStream: boolean }> {
+  const svc = temporalRoot.lookupService(service);
+  svc.resolveAll();
+  const out = new Map<string, { requestType: protobuf.Type; responseType: protobuf.Type; requestStream: boolean; responseStream: boolean }>();
+  for (const method of svc.methodsArray) {
+    out.set(method.name, {
+      requestType: method.resolvedRequestType!,
+      responseType: method.resolvedResponseType!,
+      requestStream: Boolean(method.requestStream),
+      responseStream: Boolean(method.responseStream),
+    });
+  }
+  return out;
+}
+
+export function decodeMessage(type: protobuf.Type, bytes: Uint8Array): Record<string, unknown> {
+  return type.toObject(type.decode(bytes), OBJECT) as Record<string, unknown>;
+}
+
+export function encodeMessage(type: protobuf.Type, value: Record<string, unknown>): Uint8Array {
+  return type.encode(type.fromObject(value)).finish();
+}

package/src/temporal-server.ts

@@ -0,0 +1,67 @@
+// THE LISTENER — one loopback TCP port that speaks what a Temporal frontend speaks: gRPC over HTTP/2
+// (h2c, prior knowledge; temporal-h2.ts + temporal-grpc.ts) for the SDKs, and HTTP/1 for the rest
+// (temporal-http.ts: the World's doors and the frontend's HTTP API). Temporal serves its HTTP API on
+// a second port (7243); here the first bytes of a connection say which it is, so a World's one port
+// per service carries both. The World clock ticks here (the engine's timers, timeouts and retries).
+import { createServer, type Server } from 'node:net';
+import { acceptH2Connection, type H2Handler, type Http1Handler } from './temporal-h2.ts';
+import { grpcStreamHandler, TEMPORAL_LOOPBACK_HOST } from './temporal-grpc.ts';
+import { handleTemporalCall } from './temporal-twin.ts';
+import { engineForRoot, releaseEngine, type TemporalEngine } from './temporal-engine.ts';
+import { createTemporalTwinFetch } from './temporal-http.ts';
+import { HEALTH_SERVICE, OPERATOR_SERVICE, WORKFLOW_SERVICE } from './temporal-proto.ts';
+
+export { TEMPORAL_LOOPBACK_HOST };
+
+export type H2Server = { port: number; stop: () => Promise<void> };
+
+/** Listen on loopback for HTTP/2 (and, given `http1`, HTTP/1) connections. */
+export async function serveH2(options: { port?: number; handler: H2Handler; http1?: Http1Handler }): Promise<H2Server> {
+  const connections = new Set<{ teardown(): void }>();
+  const server: Server = createServer((socket) => {
+    const connection = acceptH2Connection(socket, options.handler, options.http1);
+    connections.add(connection);
+    socket.on('close', () => connections.delete(connection));
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(options.port ?? 0, TEMPORAL_LOOPBACK_HOST, () => resolve());
+  });
+  const address = server.address();
+  const port = typeof address === 'object' && address ? address.port : 0;
+  return {
+    port,
+    stop: () => new Promise<void>((resolve) => {
+      for (const connection of connections) connection.teardown();
+      server.close(() => resolve());
+    }),
+  };
+}
+
+export type TemporalTwinServer = {
+  /** the frontend port — what TEMPORAL_ADDRESS (`127.0.0.1:<port>`) names */
+  port: number;
+  engine: TemporalEngine;
+  stop: () => Promise<void>;
+};
+
+export async function createTemporalTwinServer(options: { port?: number; root?: string; readOnly?: boolean } = {}): Promise<TemporalTwinServer> {
+  const engine = engineForRoot({ ...(options.root !== undefined ? { root: options.root } : {}), ...(options.readOnly ? { readOnly: true } : {}) });
+  const server = await serveH2({
+    ...(options.port !== undefined ? { port: options.port } : {}),
+    handler: grpcStreamHandler({
+      services: [WORKFLOW_SERVICE, OPERATOR_SERVICE, HEALTH_SERVICE],
+      handler: (service, method, request, ctx) => handleTemporalCall(engine, service, method, request, ctx),
+    }),
+    http1: createTemporalTwinFetch({ ...(options.root !== undefined ? { root: options.root } : {}), ...(options.readOnly ? { readOnly: true } : {}), engine }),
+  });
+  engine.start();
+  return {
+    port: server.port,
+    engine,
+    stop: async () => {
+      await server.stop();
+      releaseEngine(engine);
+    },
+  };
+}

package/src/temporal-twin.ts

@@ -0,0 +1,102 @@
+// THE RPC TABLE — which of Temporal's frontend RPCs this twin answers, and with what.
+//
+// The denominator is the vendored protos' own service definitions (WorkflowService,
+// OperatorService, and gRPC's Health): every method they declare reaches `handleTemporalCall`.
+// A method in `SERVED` goes to the engine; every other one answers gRPC UNIMPLEMENTED naming the
+// method, which is what the SDKs treat as "this server does not have that" — never a fabricated
+// success. `temporal-capabilities.ts` reads the same table, so a served method is a `done` with a
+// verify and an unserved one is a `todo`, by construction.
+import { GrpcError, GrpcStatus, type GrpcCallContext } from './temporal-grpc.ts';
+import { HEALTH_SERVICE, OPERATOR_SERVICE, WORKFLOW_SERVICE } from './temporal-proto.ts';
+import type { TemporalEngine } from './temporal-engine.ts';
+
+type Obj = Record<string, unknown>;
+type Served = (engine: TemporalEngine, request: Obj, ctx: GrpcCallContext) => Promise<Obj> | Obj;
+
+/** The Temporal server version this twin answers as: the API it vendors is the one the 1.15 SDKs
+ *  (sdk-core 12c656f7) speak, which Temporal server 1.29 serves. */
+export const TEMPORAL_SERVER_VERSION = '1.29.1';
+
+/** GetSystemInfo's capabilities, each one true only when this twin does the thing it names. */
+export const TEMPORAL_CAPABILITY_FLAGS = {
+  signalAndQueryHeader: true,
+  internalErrorDifferentiation: true,
+  activityFailureIncludeHeartbeat: true,
+  supportsSchedules: false,
+  encodedFailureAttributes: true,
+  buildIdBasedVersioning: false,
+  upsertMemo: true,
+  eagerWorkflowStart: false,
+  sdkMetadata: true,
+  countGroupByExecutionStatus: false,
+  nexus: false,
+};
+
+export const SERVED: Record<string, Record<string, Served>> = {
+  [WORKFLOW_SERVICE]: {
+    GetSystemInfo: () => ({ serverVersion: TEMPORAL_SERVER_VERSION, capabilities: TEMPORAL_CAPABILITY_FLAGS }),
+    DescribeNamespace: (engine, request) => engine.namespace(String(request.namespace || request.id || '')),
+    ListNamespaces: (engine) => ({ namespaces: engine.namespaces() }),
+    RegisterNamespace: (engine, request) => engine.registerNamespace(request),
+    StartWorkflowExecution: (engine, request) => engine.startWorkflowExecution(request),
+    SignalWithStartWorkflowExecution: (engine, request) => engine.signalWithStartWorkflowExecution(request),
+    SignalWorkflowExecution: (engine, request) => engine.signalWorkflowExecution(request),
+    RequestCancelWorkflowExecution: (engine, request) => engine.requestCancelWorkflowExecution(request),
+    TerminateWorkflowExecution: (engine, request) => engine.terminateWorkflowExecution(request),
+    GetWorkflowExecutionHistory: (engine, request, ctx) => engine.getWorkflowExecutionHistory(request, ctx.signal, ctx.deadline),
+    DescribeWorkflowExecution: (engine, request) => engine.describeWorkflowExecution(request),
+    ListWorkflowExecutions: (engine, request) => engine.listWorkflowExecutions(request),
+    CountWorkflowExecutions: (engine, request) => engine.countWorkflowExecutions(request),
+    PollWorkflowTaskQueue: (engine, request, ctx) => engine.pollWorkflowTaskQueue(request, ctx.signal, ctx.deadline),
+    RespondWorkflowTaskCompleted: (engine, request) => engine.respondWorkflowTaskCompleted(request),
+    RespondWorkflowTaskFailed: (engine, request) => engine.respondWorkflowTaskFailed(request),
+    PollActivityTaskQueue: (engine, request, ctx) => engine.pollActivityTaskQueue(request, ctx.signal, ctx.deadline),
+    RespondActivityTaskCompleted: (engine, request) => engine.respondActivityTaskCompleted(request),
+    RespondActivityTaskCompletedById: (engine, request) => engine.respondActivityTaskCompleted(request, true),
+    RespondActivityTaskFailed: (engine, request) => engine.respondActivityTaskFailed(request),
+    RespondActivityTaskFailedById: (engine, request) => engine.respondActivityTaskFailed(request, true),
+    RespondActivityTaskCanceled: (engine, request) => engine.respondActivityTaskCanceled(request),
+    RespondActivityTaskCanceledById: (engine, request) => engine.respondActivityTaskCanceled(request, true),
+    RecordActivityTaskHeartbeat: (engine, request) => engine.recordActivityTaskHeartbeat(request),
+    RecordActivityTaskHeartbeatById: (engine, request) => engine.recordActivityTaskHeartbeat(request, true),
+    QueryWorkflow: (engine, request, ctx) => engine.queryWorkflow(request, ctx.signal, ctx.deadline),
+    RespondQueryTaskCompleted: (engine, request) => engine.respondQueryTaskCompleted(request),
+    // this server never routes a task to a sticky queue, so there is no stickiness to reset
+    ResetStickyTaskQueue: (engine, request) => {
+      const namespace = String(request.namespace ?? '');
+      engine.namespace(namespace);
+      engine.resolveRun(namespace, request.execution as Record<string, string> | undefined); // NOT_FOUND for no such execution
+      return {};
+    },
+    ShutdownWorker: (engine, request) => engine.shutdownWorker(request),
+  },
+  [OPERATOR_SERVICE]: {
+    ListSearchAttributes: (engine, request) => engine.listSearchAttributes(request),
+    AddSearchAttributes: (engine, request) => engine.addSearchAttributes(request),
+    RemoveSearchAttributes: (engine, request) => engine.removeSearchAttributes(request),
+  },
+  [HEALTH_SERVICE]: {
+    // grpc.health.v1: the empty name is the server as a whole; an unknown service is NOT_FOUND
+    Check: (_engine, request) => {
+      const service = String(request.service ?? '');
+      if (service && ![WORKFLOW_SERVICE, OPERATOR_SERVICE, HEALTH_SERVICE].includes(service)) throw new GrpcError(GrpcStatus.NOT_FOUND, `unknown service ${service}`);
+      return { status: 'SERVING' };
+    },
+  },
+};
+
+/** One unary call, answered by the engine or refused UNIMPLEMENTED. */
+export async function handleTemporalCall(engine: TemporalEngine, service: string, method: string, request: Obj, ctx: GrpcCallContext): Promise<Obj> {
+  const served = SERVED[service]?.[method];
+  const trace = process.env.TEMPORAL_TWIN_TRACE === '1';
+  if (trace) process.stderr.write(`[temporal] → ${method} ${JSON.stringify(request).slice(0, 400)}\n`);
+  if (!served) throw new GrpcError(GrpcStatus.UNIMPLEMENTED, `${method} is not implemented by this Temporal twin`);
+  try {
+    const answer = await served(engine, request, ctx);
+    if (trace) process.stderr.write(`[temporal] ← ${method} ${JSON.stringify(answer).slice(0, 400)}\n`);
+    return answer;
+  } catch (error) {
+    if (trace) process.stderr.write(`[temporal] ✗ ${method} ${(error as Error).message}\n`);
+    throw error;
+  }
+}