@volter/twin-temporal 0.1.0

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

@@ -0,0 +1,8 @@
+export type TemporalConformanceReport = {
+    ok: boolean;
+    checksRun: number;
+    failures: string[];
+};
+export declare function checkTemporalConformance(options?: {
+    root?: string;
+}): Promise<TemporalConformanceReport>;

package/dist/src/temporal-conformance.js

@@ -0,0 +1,54 @@
+// Conformance: the twin's wire, probed as a client finds it — a real socket, HTTP/2, gRPC framing —
+// against a fresh World root. Dev-only (cli.ts imports it lazily).
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { liveTemporalExecute } from "./temporal-connector.js";
+import { createTemporalTwinServer } from "./temporal-server.js";
+import { GrpcError } from "./temporal-grpc.js";
+import { OPERATOR_SERVICE, WORKFLOW_SERVICE, HEALTH_SERVICE } from "./temporal-proto.js";
+export async function checkTemporalConformance(options = {}) {
+    const root = options.root ?? mkdtempSync(join(tmpdir(), 'temporal-conformance-'));
+    const server = await createTemporalTwinServer({ root });
+    const failures = [];
+    let checksRun = 0;
+    const check = async (name, probe) => {
+        checksRun += 1;
+        try {
+            if (!(await probe()))
+                failures.push(name);
+        }
+        catch (error) {
+            failures.push(`${name}: ${error.message}`);
+        }
+    };
+    const call = liveTemporalExecute({ address: `127.0.0.1:${server.port}`, tls: false, budgetOptions: { root } });
+    const refusal = async (service, method, request) => {
+        try {
+            await call(service, method, request);
+            return undefined;
+        }
+        catch (error) {
+            return error instanceof GrpcError ? error.code : -1;
+        }
+    };
+    try {
+        await check('GetSystemInfo answers a server version over h2c', async () => /^\d+\.\d+\.\d+$/.test(String((await call(WORKFLOW_SERVICE, 'GetSystemInfo', {})).serverVersion)));
+        await check('the default namespace exists', async () => (await call(WORKFLOW_SERVICE, 'DescribeNamespace', { namespace: 'default' })).namespaceInfo?.name === 'default');
+        await check('an unknown namespace is NOT_FOUND', async () => (await refusal(WORKFLOW_SERVICE, 'DescribeNamespace', { namespace: 'nope' })) === 5);
+        await check('an RPC the twin does not serve is UNIMPLEMENTED', async () => (await refusal(WORKFLOW_SERVICE, 'ListSchedules', { namespace: 'default' })) === 12);
+        await check('an OperatorService RPC the twin does not serve is UNIMPLEMENTED', async () => (await refusal(OPERATOR_SERVICE, 'ListClusters', {})) === 12);
+        await check('a start answers a run id, and a second start of the id is ALREADY_EXISTS', async () => {
+            const start = { namespace: 'default', workflowId: 'conformance', workflowType: { name: 'wf' }, taskQueue: { name: 'q' } };
+            const first = await call(WORKFLOW_SERVICE, 'StartWorkflowExecution', { ...start, requestId: 'a' });
+            return /^[0-9a-f-]{36}$/.test(String(first.runId)) && (await refusal(WORKFLOW_SERVICE, 'StartWorkflowExecution', { ...start, requestId: 'b' })) === 6;
+        });
+        await check('health Check answers SERVING', async () => (await call(HEALTH_SERVICE, 'Check', {})).status === 'SERVING');
+    }
+    finally {
+        await server.stop();
+        if (!options.root)
+            rmSync(root, { recursive: true, force: true });
+    }
+    return { ok: failures.length === 0, checksRun, failures };
+}

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

@@ -0,0 +1,32 @@
+import { type PushOutcome, type RemoteExecute, type TwinAction } from '@volter/world-core';
+import { TemporalBudget, type TemporalBudgetOptions } from './temporal-budget.js';
+type Obj = Record<string, unknown>;
+/** One unary call on a Temporal frontend: (service, method, request) → response, in the engine's plain form. */
+export type TemporalExecute = (service: string, method: string, request: Obj) => Promise<Obj>;
+/** THE CHOKE POINT — the one place this pack reaches a real Temporal frontend. `address` is host:port
+ *  (TEMPORAL_ADDRESS); `apiKey` (TEMPORAL_API_KEY) is sent as a bearer token, and a key implies TLS,
+ *  as the SDKs do. Every call is charged to the rate budget BEFORE it connects (a refused budget
+ *  throws and nothing is sent) and settled after, even when the call fails; a stand-in budget whose
+ *  guard methods are not the kernel's is refused rather than trusted. */
+export declare function liveTemporalExecute(options?: {
+    address?: string;
+    apiKey?: string;
+    tls?: boolean;
+    namespace?: string;
+    budget?: TemporalBudget;
+    budgetOptions?: TemporalBudgetOptions;
+}): TemporalExecute;
+/** Pull a real frontend's namespaces and their custom search attributes into the tree. */
+export declare function syncTemporalFromReal(execute: TemporalExecute, options?: {
+    root?: string;
+    occurredAt?: string;
+}): Promise<{
+    pulled: number;
+}>;
+/** The real-system half of the state system (head.ts): performing one landed entry against a real
+ *  cluster. Refused, by name, for every entry — see the header; a real head over this twin stops its
+ *  deploy at the first entry with this reason rather than pretending the entry landed. */
+export declare function performTemporalAction(_execute: RemoteExecute, action: TwinAction): Promise<PushOutcome>;
+/** Deploying a World's local runs to a real cluster is refused, by name (see the header). */
+export declare function pushPendingTemporalActions(): Promise<never>;
+export {};

package/dist/src/temporal-connector.js

@@ -0,0 +1,121 @@
+// The connector: pull a real Temporal frontend's namespace configuration into the World, over an
+// INJECTED unary-call function (the real network exists only inside liveTemporalExecute).
+//
+// What a pull observes is what a World needs to stand in for a real cluster before any app runs:
+// its namespaces (DescribeNamespaceResponse, the vendor's shape) and each namespace's custom search
+// attributes (an app's starts are refused over an attribute the namespace does not define). A real
+// cluster's workflow runs are NOT pulled: a run's state is its history, written by the workers that
+// execute it, and a copied history without those workers is a run nothing can advance.
+//
+// Push refuses by name. A World's local runs cannot be performed on a real cluster — a start or a
+// signal could be resent, but everything after it (workflow and activity tasks) is the work of
+// workers, which a deploy does not move.
+import { assertBudgetGuardIntact, observeResource, worldNow } from '@volter/world-core';
+import { TemporalBudget, temporalCallWeight } from "./temporal-budget.js";
+import http2 from 'node:http2';
+import { decodeMessage, encodeMessage, serviceMethods, OPERATOR_SERVICE, WORKFLOW_SERVICE } from "./temporal-proto.js";
+import { GrpcError, grpcFrame, splitGrpcFrames } from "./temporal-grpc.js";
+/** THE CHOKE POINT — the one place this pack reaches a real Temporal frontend. `address` is host:port
+ *  (TEMPORAL_ADDRESS); `apiKey` (TEMPORAL_API_KEY) is sent as a bearer token, and a key implies TLS,
+ *  as the SDKs do. Every call is charged to the rate budget BEFORE it connects (a refused budget
+ *  throws and nothing is sent) and settled after, even when the call fails; a stand-in budget whose
+ *  guard methods are not the kernel's is refused rather than trusted. */
+export function liveTemporalExecute(options = {}) {
+    const address = options.address ?? process.env.TEMPORAL_ADDRESS;
+    if (!address)
+        throw new Error('liveTemporalExecute: TEMPORAL_ADDRESS is not set (host:port of a Temporal frontend)');
+    const apiKey = options.apiKey ?? process.env.TEMPORAL_API_KEY;
+    const tls = options.tls ?? Boolean(apiKey);
+    if (options.budget !== undefined && options.budget !== null)
+        assertBudgetGuardIntact(options.budget, TemporalBudget, 'liveTemporalExecute');
+    const budget = options.budget instanceof TemporalBudget ? options.budget : new TemporalBudget({ token: address, ...(options.budgetOptions ?? {}) });
+    return async (service, method, request) => {
+        const weight = temporalCallWeight(service, method);
+        const reservation = budget.checkBudget(weight);
+        try {
+            return await unaryCall(address, tls, apiKey, options.namespace, service, method, request);
+        }
+        finally {
+            budget.recordCall(weight, {}, { reservation });
+        }
+    };
+}
+function unaryCall(address, tls, apiKey, namespace, service, method, request) {
+    const options = { namespace };
+    return new Promise((resolve, reject) => {
+        const table = serviceMethods(service).get(method);
+        if (!table) {
+            reject(new Error(`liveTemporalExecute: ${service}/${method} is not in the vendored API`));
+            return;
+        }
+        const session = http2.connect(`${tls ? 'https' : 'http'}://${address}`);
+        session.on('error', (error) => { session.destroy(); reject(error); });
+        const stream = session.request({
+            ':method': 'POST', ':path': `/${service}/${method}`, 'content-type': 'application/grpc', te: 'trailers',
+            ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {}),
+            ...(options.namespace ? { 'temporal-namespace': options.namespace } : {}),
+        });
+        const chunks = [];
+        let status = '';
+        let message = '';
+        stream.on('response', (headers) => { status = String(headers['grpc-status'] ?? status); message = String(headers['grpc-message'] ?? message); });
+        stream.on('trailers', (trailers) => { status = String(trailers['grpc-status'] ?? status); message = String(trailers['grpc-message'] ?? message); });
+        stream.on('data', (chunk) => chunks.push(chunk));
+        stream.on('error', (error) => { session.destroy(); reject(error); });
+        stream.on('end', () => {
+            session.close();
+            if (status !== '0') {
+                let text = message;
+                try {
+                    text = decodeURIComponent(message);
+                }
+                catch { /* a grpc-message that is not percent-encoding is shown as sent */ }
+                reject(new GrpcError(Number(status || 2), text));
+                return;
+            }
+            try {
+                const [frame] = splitGrpcFrames(new Uint8Array(Buffer.concat(chunks)));
+                resolve(frame ? decodeMessage(table.responseType, frame.message) : {});
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+        stream.end(Buffer.from(grpcFrame(encodeMessage(table.requestType, request))));
+    });
+}
+/** Pull a real frontend's namespaces and their custom search attributes into the tree. */
+export async function syncTemporalFromReal(execute, options = {}) {
+    const at = options.occurredAt ?? worldNow();
+    const scope = { ...(options.root !== undefined ? { root: options.root } : {}), at };
+    // read everything first: a call that fails part way leaves the tree as it was
+    const namespaces = [];
+    let pageToken;
+    do {
+        const listing = await execute(WORKFLOW_SERVICE, 'ListNamespaces', { pageSize: 100, ...(pageToken ? { nextPageToken: pageToken } : {}) });
+        namespaces.push(...(listing.namespaces ?? []));
+        pageToken = listing.nextPageToken;
+    } while (pageToken);
+    const observed = [];
+    for (const described of namespaces) {
+        const name = String(described.namespaceInfo?.name ?? '');
+        if (!name)
+            throw new Error('temporal: a listed namespace has no name — refusing to fold a partial pull');
+        const attributes = await execute(OPERATOR_SERVICE, 'ListSearchAttributes', { namespace: name });
+        // the namespace's custom search attributes ride its subject as bookkeeping, as the engine keeps them
+        observed.push({ name, fields: { ...described, _searchAttributes: (attributes.customAttributes ?? {}) } });
+    }
+    for (const { name, fields } of observed)
+        observeResource('temporal', { type: 'namespace', id: name, fields }, scope);
+    return { pulled: observed.length };
+}
+/** The real-system half of the state system (head.ts): performing one landed entry against a real
+ *  cluster. Refused, by name, for every entry — see the header; a real head over this twin stops its
+ *  deploy at the first entry with this reason rather than pretending the entry landed. */
+export async function performTemporalAction(_execute, action) {
+    throw new Error(`temporal: performing ${action.operation} on a real Temporal cluster is not supported — a run's history is written by the workers that execute it, which a deploy does not move`);
+}
+/** Deploying a World's local runs to a real cluster is refused, by name (see the header). */
+export async function pushPendingTemporalActions() {
+    throw new Error('temporal: pushing local workflow runs to a real Temporal cluster is not supported — a run\'s history is written by the workers that execute it, which a deploy does not move');
+}

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

@@ -0,0 +1,274 @@
+import { TemporalStore, type HistoryEvent } from './temporal-history.js';
+type Obj = Record<string, unknown>;
+type Duration = {
+    seconds?: number;
+    nanos?: number;
+};
+type Timestamp = {
+    seconds: number;
+    nanos?: number;
+};
+export declare const DEFAULT_NAMESPACE = "default";
+export declare function durationMs(value: unknown): number;
+export declare function toDuration(ms: number): Duration | undefined;
+export declare function toTimestamp(ms: number): Timestamp;
+/** The World's now, in epoch milliseconds. */
+export declare function nowMs(): number;
+/** A payload's value, when its encoding is one this server can read (json/plain, binary/null). */
+export declare function payloadValue(payload: unknown): unknown;
+export declare function jsonPayload(value: unknown, extra?: Record<string, string>): Obj;
+type RetryPolicy = {
+    initialInterval?: Duration;
+    backoffCoefficient?: number;
+    maximumInterval?: Duration;
+    maximumAttempts?: number;
+    nonRetryableErrorTypes?: string[];
+};
+type ActivityState = {
+    scheduledEventId: number;
+    activityId: string;
+    activityType: Obj;
+    taskQueue: string;
+    input?: Obj;
+    header?: Obj;
+    priority?: Obj;
+    retryPolicy: RetryPolicy;
+    scheduleToCloseMs: number;
+    scheduleToStartMs: number;
+    startToCloseMs: number;
+    heartbeatMs: number;
+    attempt: number;
+    scheduledAt: number;
+    attemptScheduledAt: number;
+    availableAt: number;
+    startedAt?: number;
+    identity?: string;
+    requestId?: string;
+    heartbeatDetails?: Obj;
+    lastHeartbeatAt?: number;
+    lastFailure?: Obj;
+    lastAttemptCompletedAt?: number;
+    cancelRequestedEventId?: number;
+};
+type ChildState = {
+    initiatedEventId: number;
+    namespace: string;
+    workflowId: string;
+    workflowType: Obj;
+    parentClosePolicy: string;
+    runId?: string;
+    startedEventId?: number;
+};
+type WftState = {
+    scheduledEventId: number;
+    attempt: number;
+    scheduledAt: number;
+    availableAt: number;
+    startedEventId?: number;
+    startedAt?: number;
+    timeoutAt?: number;
+    identity?: string;
+};
+/** An event that arrived while a workflow task was in flight, appended once it closes (Temporal's
+ *  buffered events). `linkPrevious` names an attribute set to the id of the event appended before it
+ *  (an activity's close names the ActivityTaskStarted written in the same step). */
+type BufferedEvent = {
+    eventType: string;
+    key: string;
+    attributes: Obj;
+    linkPrevious?: string;
+    wakes: boolean;
+};
+type RunState = {
+    /** creation order among the World's runs: the latest run of a workflow id is its current one */
+    seq: number;
+    nextEventId: number;
+    history: string[];
+    historyBytes: number;
+    requestIds: string[];
+    /** the request id that started this run (StartWorkflowExecution / SignalWithStart), apart from signal and cancel ids */
+    startRequestIds?: string[];
+    workflowTaskTimeoutMs: number;
+    runTimeoutMs: number;
+    executionTimeoutMs: number;
+    runExpiresAt?: number;
+    executionExpiresAt?: number;
+    retryPolicy?: RetryPolicy;
+    attempt: number;
+    input?: Obj;
+    header?: Obj;
+    cronSchedule?: string;
+    firstWftAt?: number;
+    wft: WftState | null;
+    previousStartedEventId: number;
+    buffered: BufferedEvent[];
+    activities: Record<string, ActivityState>;
+    timers: Record<string, {
+        startedEventId: number;
+        fireAt: number;
+    }>;
+    children: Record<string, ChildState>;
+    parent?: {
+        namespace: string;
+        workflowId: string;
+        runId: string;
+        initiatedEventId: number;
+    };
+    cancelRequested: boolean;
+    closeEventId?: number;
+    newRunId?: string;
+    nextDue?: number;
+};
+/** A run as the engine handles it: WorkflowExecutionInfo fields at the top, `namespace`, `_state`. */
+export type Run = Obj & {
+    id: string;
+    namespace: string;
+    execution: {
+        workflowId: string;
+        runId: string;
+    };
+    type: {
+        name: string;
+    };
+    status: string;
+    taskQueue: string;
+    firstRunId: string;
+    historyLength: number;
+    startTime: Timestamp;
+    executionTime?: Timestamp;
+    closeTime?: Timestamp;
+    searchAttributes?: {
+        indexedFields?: Record<string, Obj>;
+    };
+    memo?: {
+        fields?: Record<string, Obj>;
+    };
+    parentExecution?: {
+        workflowId: string;
+        runId: string;
+    };
+    rootExecution?: {
+        workflowId: string;
+        runId: string;
+    };
+    _state: RunState;
+};
+/** Temporal's predefined search attributes (https://docs.temporal.io/search-attribute#default-search-attribute). */
+export declare const SYSTEM_SEARCH_ATTRIBUTES: Record<string, string>;
+export type EngineOptions = {
+    root?: string;
+    readOnly?: boolean;
+};
+export declare class TemporalEngine {
+    readonly store: TemporalStore;
+    readonly readOnly: boolean;
+    /** holders from engineForRoot (see releaseEngine) */
+    users: number;
+    private lock;
+    private waiters;
+    private queries;
+    private querySeq;
+    /** runs minted in the current transition and not yet written (see newRun) */
+    private pendingRuns;
+    private ticker;
+    private ticking;
+    private closedSticky;
+    constructor(options?: EngineOptions);
+    /** Start the clock-driven work: timers, timeouts, retries and delayed tasks falling due. */
+    start(intervalMs?: number): void;
+    stop(): void;
+    private serial;
+    private notify;
+    /** Park until the next state change, the deadline, or the caller going away. */
+    private wait;
+    private assertWritable;
+    runs(namespace?: string): Run[];
+    run(runId: string): Run | undefined;
+    /** The run a request names: that run id, or the workflow id's current (latest) run. */
+    resolveRun(namespace: string, execution: {
+        workflowId?: string;
+        runId?: string;
+    } | undefined, firstExecutionRunId?: string): Run;
+    history(run: Run): Promise<HistoryEvent[]>;
+    private commit;
+    /** Every namespace, stored fields included (bookkeeping too). */
+    private namespaceRecords;
+    private namespaceRecord;
+    /** The namespaces as DescribeNamespace answers them (bookkeeping never reaches the wire). */
+    namespaces(): Obj[];
+    namespace(name: string): Obj;
+    private requireNamespace;
+    registerNamespace(request: Obj): Promise<Obj>;
+    customSearchAttributes(namespace: string): Record<string, string>;
+    /** Write a namespace's custom search attributes (the whole namespace subject, `default` included). */
+    private putSearchAttributes;
+    addSearchAttributes(request: Obj): Promise<Obj>;
+    removeSearchAttributes(request: Obj): Promise<Obj>;
+    listSearchAttributes(request: Obj): Obj;
+    /** INVALID_ARGUMENT for a search attribute the namespace does not define (Temporal refuses these). */
+    private validateSearchAttributes;
+    private workerError;
+    /** Create a run and its first events (inside a transition). */
+    private newRun;
+    private startSpec;
+    /** WorkflowIdConflictPolicy / WorkflowIdReusePolicy against the workflow id's latest run. Answers
+     *  `existing` when the start resolves to a run that is already running (USE_EXISTING). */
+    private admitStart;
+    startWorkflowExecution(request: Obj): Promise<Obj>;
+    signalWithStartWorkflowExecution(request: Obj): Promise<Obj>;
+    private signalInto;
+    signalWorkflowExecution(request: Obj): Promise<Obj>;
+    requestCancelWorkflowExecution(request: Obj): Promise<Obj>;
+    private cancelRequestInto;
+    terminateWorkflowExecution(request: Obj): Promise<Obj>;
+    private terminateRun;
+    /** Close a run: retire its tasks, apply its children's parent-close policy, tell its parent. */
+    private closeRun;
+    private notifyParent;
+    pollWorkflowTaskQueue(request: Obj, signal: AbortSignal, deadline?: number): Promise<Obj>;
+    private takeWorkflowTask;
+    /** The run and in-flight task a workflow task token names, or NOT_FOUND. */
+    private workflowTaskOf;
+    respondWorkflowTaskCompleted(request: Obj): Promise<Obj>;
+    /** One command → its events (and, for cross-run effects, a step run after this run is written). */
+    private applyCommand;
+    /** The run a continue-as-new or a retry hands the workflow to (built now, written after this run). */
+    private nextRunOf;
+    private startChild;
+    private signalExternal;
+    private cancelExternal;
+    /** Fail the in-flight workflow task and schedule the next attempt. */
+    private failWorkflowTask;
+    respondWorkflowTaskFailed(request: Obj): Promise<Obj>;
+    queryWorkflow(request: Obj, signal: AbortSignal, deadline?: number): Promise<Obj>;
+    respondQueryTaskCompleted(request: Obj): Promise<Obj>;
+    pollActivityTaskQueue(request: Obj, signal: AbortSignal, deadline?: number): Promise<Obj>;
+    private takeActivityTask;
+    /** The run and started attempt an activity token (or an id triple) names, or NOT_FOUND. */
+    private activityOf;
+    private activityTarget;
+    /** Close an activity with its final event (Started is written now, as Temporal writes it at the close). */
+    private closeActivity;
+    respondActivityTaskCompleted(request: Obj, byId?: boolean): Promise<Obj>;
+    respondActivityTaskFailed(request: Obj, byId?: boolean): Promise<Obj>;
+    private retryActivity;
+    respondActivityTaskCanceled(request: Obj, byId?: boolean): Promise<Obj>;
+    recordActivityTaskHeartbeat(request: Obj, byId?: boolean): Promise<Obj>;
+    /** Fire what the World clock says is due: timers, timeouts, delayed first tasks, expirations. */
+    tick(): Promise<void>;
+    private fireDue;
+    getWorkflowExecutionHistory(request: Obj, signal: AbortSignal, deadline?: number): Promise<Obj>;
+    describeWorkflowExecution(request: Obj): Promise<Obj>;
+    private visibility;
+    listWorkflowExecutions(request: Obj): Obj;
+    countWorkflowExecutions(request: Obj): Obj;
+    shutdownWorker(request: Obj): Promise<Obj>;
+}
+/** The process's engine for a root (created on first use). Two engines on one root would each
+ *  serialize only their own transitions and could lose one another's updates. */
+export declare function engineForRoot(options?: EngineOptions): TemporalEngine;
+/** A user of a root's engine is done with it; the last one stops it and drops it from the registry. */
+export declare function releaseEngine(engine: TemporalEngine): void;
+/** A run's WorkflowExecutionInfo: its stored fields without the server's bookkeeping. */
+export declare function executionInfo(run: Run): Obj;
+export {};