@volter/twin-temporal 0.1.0

package/dist/src/temporal-history.js

@@ -0,0 +1,85 @@
+// 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';
+const chunkCache = new Map(); // 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, events) {
+    chunkCache.delete(key);
+    chunkCache.set(key, events);
+    while (chunkCache.size > CHUNK_CACHE_LIMIT)
+        chunkCache.delete(chunkCache.keys().next().value);
+}
+export class TemporalStore {
+    root;
+    constructor(root) {
+        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) {
+        return twinResourcesOfType(TEMPORAL_SERVICE, type, this.root).map((resource) => ({ ...ownFields(resource), id: resource.id }));
+    }
+    get(type, id) {
+        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, id, fields, operation, input) {
+        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)),
+            ...(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) {
+        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) {
+        const out = [];
+        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));
+                remember(cacheKey, events);
+            }
+            out.push(...events);
+        }
+        return out;
+    }
+}

package/dist/src/temporal-http.d.ts

@@ -0,0 +1,17 @@
+import { type TwinFetchHandlerResult } from '@volter/world-core';
+import { type TemporalEngine } from './temporal-engine.js';
+/** One HTTP API request, answered through the RPC table. */
+export declare function handleTemporalHttpRequest(engine: TemporalEngine, request: {
+    method: string;
+    path: string;
+    body: string;
+}): Promise<TwinFetchHandlerResult>;
+/** Every route the HTTP API serves (the served subset of the annotated routes), for the manifest. */
+export declare function servedHttpRoutes(): string[];
+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 declare function createTemporalTwinFetch(options?: TemporalTwinFetchOptions): (request: Request) => Promise<Response>;

package/dist/src/temporal-http.js

@@ -0,0 +1,160 @@
+// 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 } from '@volter/world-core';
+import { handleTemporalCall, SERVED } from "./temporal-twin.js";
+import { engineForRoot, executionInfo } from "./temporal-engine.js";
+import { GrpcError, GrpcStatus } from "./temporal-grpc.js";
+import { fromProto3Json, toProto3Json } from "./temporal-json.js";
+import { OPERATOR_SERVICE, WORKFLOW_SERVICE, serviceMethods, temporalRoot } from "./temporal-proto.js";
+/** gRPC status → HTTP status, as grpc-gateway maps them (runtime/errors.go HTTPStatusFromCode). */
+const HTTP_STATUS = {
+    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) {
+    const out = [];
+    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 ?? {});
+        const bindings = [];
+        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 = [];
+            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; // cache: a pure function of the committed descriptor
+function routes() {
+    routeTable ??= [...routesOf(WORKFLOW_SERVICE), ...routesOf(OPERATOR_SERVICE)];
+    return routeTable;
+}
+const camel = (name) => name.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+/** Set a dotted proto path (`execution.workflow_id`) on a plain request. */
+function setPath(target, path, value) {
+    const parts = path.split('.').map(camel);
+    let cursor = target;
+    for (const part of parts.slice(0, -1))
+        cursor = (cursor[part] ??= {});
+    cursor[parts.at(-1)] = value;
+}
+/** A query-string value, typed by the field it lands on. */
+function typedQueryValue(type, path, raw) {
+    let current = type;
+    let field;
+    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 : 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, request) {
+    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 = {};
+        if (route.body === '*' && request.body.trim()) {
+            const parsed = JSON.parse(request.body);
+            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);
+            }
+            catch (error) {
+                throw new GrpcError(GrpcStatus.INVALID_ARGUMENT, 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.message);
+            }
+        }
+        let values;
+        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.message, details: [] } };
+    }
+}
+/** Every route the HTTP API serves (the served subset of the annotated routes), for the manifest. */
+export function servedHttpRoutes() {
+    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}`);
+}
+/** The twin's HTTP surface: the World's doors (GET /twin, GET /twin/store/workflows) and the HTTP API. */
+export function createTemporalTwinFetch(options = {}) {
+    const engine = options.engine ?? engineForRoot({ ...(options.root !== undefined ? { root: options.root } : {}), ...(options.readOnly ? { readOnly: true } : {}) });
+    const serveDoors = createTwinFetchFromHandler((request) => 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.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/dist/src/temporal-json.d.ts

@@ -0,0 +1,7 @@
+import type protobuf from 'protobufjs';
+type Obj = Record<string, unknown>;
+/** The engine's plain form → proto3 JSON. */
+export declare function toProto3Json(type: protobuf.Type, value: Obj): Obj;
+/** Proto3 JSON → the engine's plain form (throws on an unknown field or a malformed value). */
+export declare function fromProto3Json(type: protobuf.Type, value: Obj): Obj;
+export {};

package/dist/src/temporal-json.js

@@ -0,0 +1,68 @@
+import { durationMs, toDuration, toTimestamp } from "./temporal-engine.js";
+const LONGS = new Set(['int64', 'uint64', 'sint64', 'fixed64', 'sfixed64']);
+function rfc3339(value) {
+    const ms = Number(value.seconds ?? 0) * 1000 + Math.floor(Number(value.nanos ?? 0) / 1e6);
+    return new Date(ms).toISOString();
+}
+function durationText(value) {
+    const ms = durationMs(value);
+    return `${ms % 1000 === 0 ? ms / 1000 : (ms / 1000).toFixed(3).replace(/0+$/, '')}s`;
+}
+function convert(field, value, direction) {
+    field.resolve();
+    const one = (item) => {
+        if (item === null || item === undefined)
+            return item;
+        if (field.resolvedType && 'fields' in field.resolvedType) {
+            const type = field.resolvedType;
+            if (type.fullName === '.google.protobuf.Timestamp') {
+                if (direction === 'out')
+                    return rfc3339(item);
+                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);
+                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, direction);
+        }
+        if (LONGS.has(field.type))
+            return direction === 'out' ? String(item) : Number(item);
+        return item;
+    };
+    if (field.map) {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, one(item)]));
+    }
+    if (field.repeated)
+        return value.map(one);
+    return one(value);
+}
+function walk(type, value, direction) {
+    const out = {};
+    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) => 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, value) {
+    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, value) {
+    return walk(type, value, 'in');
+}

package/dist/src/temporal-proto.d.ts

@@ -0,0 +1,17 @@
+import protobuf from 'protobufjs';
+export declare const temporalRoot: protobuf.Root;
+export declare const WORKFLOW_SERVICE = "temporal.api.workflowservice.v1.WorkflowService";
+export declare const OPERATOR_SERVICE = "temporal.api.operatorservice.v1.OperatorService";
+export declare const HEALTH_SERVICE = "grpc.health.v1.Health";
+/** protobufjs's toObject options for the engine's plain form (see the header). */
+export declare const OBJECT: protobuf.IConversionOptions;
+export declare function messageType(name: string): protobuf.Type;
+/** A service's methods, by name, with their request and response types. */
+export declare function serviceMethods(service: string): Map<string, {
+    requestType: protobuf.Type;
+    responseType: protobuf.Type;
+    requestStream: boolean;
+    responseStream: boolean;
+}>;
+export declare function decodeMessage(type: protobuf.Type, bytes: Uint8Array): Record<string, unknown>;
+export declare function encodeMessage(type: protobuf.Type, value: Record<string, unknown>): Uint8Array;

package/dist/src/temporal-proto.js

@@ -0,0 +1,46 @@
+// 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.fromJSON(descriptor);
+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 = { enums: String, longs: Number, bytes: String, defaults: false, arrays: false, objects: false, oneofs: false };
+const typeCache = new Map(); // cache: lookups into the committed descriptor
+export function messageType(name) {
+    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) {
+    const svc = temporalRoot.lookupService(service);
+    svc.resolveAll();
+    const out = new Map();
+    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, bytes) {
+    return type.toObject(type.decode(bytes), OBJECT);
+}
+export function encodeMessage(type, value) {
+    return type.encode(type.fromObject(value)).finish();
+}

package/dist/src/temporal-server.d.ts

@@ -0,0 +1,25 @@
+import { type H2Handler, type Http1Handler } from './temporal-h2.js';
+import { TEMPORAL_LOOPBACK_HOST } from './temporal-grpc.js';
+import { type TemporalEngine } from './temporal-engine.js';
+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 declare function serveH2(options: {
+    port?: number;
+    handler: H2Handler;
+    http1?: Http1Handler;
+}): Promise<H2Server>;
+export type TemporalTwinServer = {
+    /** the frontend port — what TEMPORAL_ADDRESS (`127.0.0.1:<port>`) names */
+    port: number;
+    engine: TemporalEngine;
+    stop: () => Promise<void>;
+};
+export declare function createTemporalTwinServer(options?: {
+    port?: number;
+    root?: string;
+    readOnly?: boolean;
+}): Promise<TemporalTwinServer>;

package/dist/src/temporal-server.js

@@ -0,0 +1,56 @@
+// 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 } from 'node:net';
+import { acceptH2Connection } from "./temporal-h2.js";
+import { grpcStreamHandler, TEMPORAL_LOOPBACK_HOST } from "./temporal-grpc.js";
+import { handleTemporalCall } from "./temporal-twin.js";
+import { engineForRoot, releaseEngine } from "./temporal-engine.js";
+import { createTemporalTwinFetch } from "./temporal-http.js";
+import { HEALTH_SERVICE, OPERATOR_SERVICE, WORKFLOW_SERVICE } from "./temporal-proto.js";
+export { TEMPORAL_LOOPBACK_HOST };
+/** Listen on loopback for HTTP/2 (and, given `http1`, HTTP/1) connections. */
+export async function serveH2(options) {
+    const connections = new Set();
+    const server = createServer((socket) => {
+        const connection = acceptH2Connection(socket, options.handler, options.http1);
+        connections.add(connection);
+        socket.on('close', () => connections.delete(connection));
+    });
+    await new Promise((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((resolve) => {
+            for (const connection of connections)
+                connection.teardown();
+            server.close(() => resolve());
+        }),
+    };
+}
+export async function createTemporalTwinServer(options = {}) {
+    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/dist/src/temporal-twin.d.ts

@@ -0,0 +1,25 @@
+import { type GrpcCallContext } from './temporal-grpc.js';
+import type { TemporalEngine } from './temporal-engine.js';
+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 declare const TEMPORAL_SERVER_VERSION = "1.29.1";
+/** GetSystemInfo's capabilities, each one true only when this twin does the thing it names. */
+export declare const TEMPORAL_CAPABILITY_FLAGS: {
+    signalAndQueryHeader: boolean;
+    internalErrorDifferentiation: boolean;
+    activityFailureIncludeHeartbeat: boolean;
+    supportsSchedules: boolean;
+    encodedFailureAttributes: boolean;
+    buildIdBasedVersioning: boolean;
+    upsertMemo: boolean;
+    eagerWorkflowStart: boolean;
+    sdkMetadata: boolean;
+    countGroupByExecutionStatus: boolean;
+    nexus: boolean;
+};
+export declare const SERVED: Record<string, Record<string, Served>>;
+/** One unary call, answered by the engine or refused UNIMPLEMENTED. */
+export declare function handleTemporalCall(engine: TemporalEngine, service: string, method: string, request: Obj, ctx: GrpcCallContext): Promise<Obj>;
+export {};

package/dist/src/temporal-twin.js

@@ -0,0 +1,100 @@
+// 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 } from "./temporal-grpc.js";
+import { HEALTH_SERVICE, OPERATOR_SERVICE, WORKFLOW_SERVICE } from "./temporal-proto.js";
+/** 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 = {
+    [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); // 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, service, method, request, ctx) {
+    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.message}\n`);
+        throw error;
+    }
+}