@volter/twin-temporal 0.1.0

package/dist/src/index.d.ts

@@ -0,0 +1,18 @@
+export { createTemporalTwinServer, serveH2, TEMPORAL_LOOPBACK_HOST } from './temporal-server.js';
+export type { TemporalTwinServer } from './temporal-server.js';
+export { handleTemporalCall, SERVED, TEMPORAL_CAPABILITY_FLAGS, TEMPORAL_SERVER_VERSION } from './temporal-twin.js';
+export { TemporalEngine, DEFAULT_NAMESPACE, SYSTEM_SEARCH_ATTRIBUTES, executionInfo, payloadValue, jsonPayload } from './temporal-engine.js';
+export type { Run as TemporalRun, EngineOptions as TemporalEngineOptions } from './temporal-engine.js';
+export { TemporalStore, TEMPORAL_SERVICE } from './temporal-history.js';
+export { grpcStreamHandler, GrpcError, GrpcStatus, grpcFrame, splitGrpcFrames, parseGrpcTimeout } from './temporal-grpc.js';
+export type { GrpcCallContext, GrpcHandler } from './temporal-grpc.js';
+export { acceptH2Connection, HpackDecoder, hpackEncode, huffmanDecode } from './temporal-h2.js';
+export { createTemporalTwinFetch, handleTemporalHttpRequest } from './temporal-http.js';
+export { toProto3Json, fromProto3Json } from './temporal-json.js';
+export { temporalRoot, messageType, serviceMethods, decodeMessage, encodeMessage, WORKFLOW_SERVICE, OPERATOR_SERVICE, HEALTH_SERVICE } from './temporal-proto.js';
+export { parseVisibilityQuery, matchesVisibilityQuery } from './temporal-visibility.js';
+export { liveTemporalExecute, performTemporalAction, syncTemporalFromReal, pushPendingTemporalActions } from './temporal-connector.js';
+export { TemporalBudget, TemporalBudgetError, TEMPORAL_RATE_BUDGET, TEMPORAL_BUDGET_CEILING, TEMPORAL_BUDGET_WINDOW_MS, TEMPORAL_CALL_WEIGHTS, temporalBudgetPath, temporalCallWeight } from './temporal-budget.js';
+export type { TemporalExecute } from './temporal-connector.js';
+import { type TwinPack } from '@volter/world-core';
+export declare const pack: TwinPack;

package/dist/src/index.js

@@ -0,0 +1,70 @@
+// @volter/twin-temporal — Temporal (the workflow engine) served from the World, containerless: the
+// frontend's gRPC API (WorkflowService, OperatorService, grpc.health) on a loopback port, so an
+// unmodified app on the Temporal SDKs (@temporalio/client + @temporalio/worker) starts, runs and
+// reads workflows against it with nothing installed. It stands where `temporal server start-dev` or
+// Temporal's docker-compose stack stands in local development. Read README.md before extending it.
+export { createTemporalTwinServer, serveH2, TEMPORAL_LOOPBACK_HOST } from "./temporal-server.js";
+export { handleTemporalCall, SERVED, TEMPORAL_CAPABILITY_FLAGS, TEMPORAL_SERVER_VERSION } from "./temporal-twin.js";
+export { TemporalEngine, DEFAULT_NAMESPACE, SYSTEM_SEARCH_ATTRIBUTES, executionInfo, payloadValue, jsonPayload } from "./temporal-engine.js";
+export { TemporalStore, TEMPORAL_SERVICE } from "./temporal-history.js";
+export { grpcStreamHandler, GrpcError, GrpcStatus, grpcFrame, splitGrpcFrames, parseGrpcTimeout } from "./temporal-grpc.js";
+export { acceptH2Connection, HpackDecoder, hpackEncode, huffmanDecode } from "./temporal-h2.js";
+export { createTemporalTwinFetch, handleTemporalHttpRequest } from "./temporal-http.js";
+export { toProto3Json, fromProto3Json } from "./temporal-json.js";
+export { temporalRoot, messageType, serviceMethods, decodeMessage, encodeMessage, WORKFLOW_SERVICE, OPERATOR_SERVICE, HEALTH_SERVICE } from "./temporal-proto.js";
+export { parseVisibilityQuery, matchesVisibilityQuery } from "./temporal-visibility.js";
+export { liveTemporalExecute, performTemporalAction, syncTemporalFromReal, pushPendingTemporalActions } from "./temporal-connector.js";
+export { TemporalBudget, TemporalBudgetError, TEMPORAL_RATE_BUDGET, TEMPORAL_BUDGET_CEILING, TEMPORAL_BUDGET_WINDOW_MS, TEMPORAL_CALL_WEIGHTS, temporalBudgetPath, temporalCallWeight } from "./temporal-budget.js";
+// NB: ./temporal-conformance.ts and ./temporal-capabilities.ts are NOT re-exported — they are dev-only
+// tooling (@volter/world-tooling); cli.ts imports the conformance module lazily.
+import { registerPack } from '@volter/world-core';
+import { TEMPORAL_RATE_BUDGET } from "./temporal-budget.js";
+import { performTemporalAction } from "./temporal-connector.js";
+export const pack = {
+    vendor: 'temporal',
+    // gRPC is HTTP/2 framing straight onto a TCP socket: the injector patches http/fetch and never sees
+    // it (@grpc/grpc-js drives node:http2 itself; the worker's Rust core has its own client), so this is
+    // the raw-protocol class — wired by the app-read address, never by a host map.
+    transport: 'raw-tcp',
+    protocol: '2',
+    archetype: 'engine-control',
+    // the real-system half: a real head refuses every entry by name (performTemporalAction says why);
+    // the pull is syncTemporalFromReal over a gRPC execute, not the kernel's HTTP refresh
+    stateSystem: { perform: performTemporalAction },
+    // the branch round-trip's writes, on the frontend's HTTP API: start a run, then terminate it. The id
+    // is then free (a closed run allows a duplicate), so the same pair on a branch makes a new run there
+    // and never touches the run the base already holds.
+    roundTrip: [
+        { method: 'POST', path: '/api/v1/namespaces/default/workflows/round-trip', body: { workflowType: { name: 'round-trip' }, taskQueue: { name: 'round-trip' } } },
+        { method: 'POST', path: '/api/v1/namespaces/default/workflows/round-trip/terminate', body: { reason: 'round-trip' } },
+    ],
+    rateBudget: TEMPORAL_RATE_BUDGET,
+    bin: 'world-temporal',
+    resources: ['workflow-execution', 'namespace'],
+    // The history beside the tree: content-addressed chunks in the World's blob store, named in order by
+    // each run's subject (temporal-history.ts owns every write outside the tree).
+    engine: { module: 'temporal-history', note: 'a run\'s history as content-addressed event chunks in the blob store; the workflow-execution subject names them in order' },
+    specSource: 'temporalio/api protos as vendored by @temporalio/core-bridge@1.15.0 (sdk-core 12c656f7, crates/common/protos/api_upstream: '
+        + 'temporal.api.workflowservice.v1.WorkflowService, temporal.api.operatorservice.v1.OperatorService) + grpc.health.v1; '
+        + 'the gRPC wire per grpc/grpc doc/PROTOCOL-HTTP2.md over HTTP/2 (RFC 9113) with HPACK (RFC 7541, vendored)',
+    description: 'Temporal frontend twin — WorkflowService over gRPC on loopback: start/signal/signal-with-start/cancel/terminate, '
+        + 'workflow and activity task queues with long polls, the history service (activities with retry policies and '
+        + 'heartbeats, timers on the World clock, signals, queries, child workflows, continue-as-new, markers, search '
+        + 'attributes), history reads, describe and list/count visibility queries; OperatorService search attributes. '
+        + 'Every other RPC answers gRPC UNIMPLEMENTED.',
+    adoption: {
+        sdks: ['@temporalio/client', '@temporalio/worker', '@temporalio/workflow', '@temporalio/activity'],
+        scopes: ['@temporalio/'],
+        pypi: ['temporalio'],
+        envStems: ['TEMPORAL'],
+    },
+    // INTERCEPTION RULING — hostsNone: there is no host to map. The SDKs take the frontend's address as
+    // configuration (`Connection.connect({ address })`, `NativeConnection.connect({ address })`, which
+    // apps read from TEMPORAL_ADDRESS — Postiz's temporal.module.ts, the SDK samples, the Temporal CLI's
+    // own env), and the traffic is gRPC the http/fetch injector cannot see. The World injects
+    // TEMPORAL_ADDRESS=<host>:<port> at this twin's listener (APP_READ_ENDPOINT_ENV in
+    // world-runtime/src/init.ts: an address, not a URL, which the descriptor's endpointEnv cannot carry).
+    hostsNone: 'RAW-PROTOCOL pack — there is no host to map. The Temporal SDKs dial the frontend address they are configured with (Connection.connect / NativeConnection.connect `address`, conventionally TEMPORAL_ADDRESS) over gRPC, which the http/fetch injector never sees. Interception is the app-read address: the World injects TEMPORAL_ADDRESS=<host>:<port> at this twin (APP_READ_ENDPOINT_ENV in world-runtime/src/init.ts).',
+};
+// a protocol 2 pack registers itself on load: its rate budget arms and its state-system adapters reach the head
+registerPack(pack);

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

@@ -0,0 +1,31 @@
+import { RateBudget, type RateBudgetDeclaration, type RateBudgetOptions, type RateBudgetReservation, type RateBudgetSnapshot } from '@volter/world-core';
+/** Rolling window, in ms. */
+export declare const TEMPORAL_BUDGET_WINDOW_MS = 60000;
+/** Weighted units per window: 20 calls a minute at weight 1 — under the kernel fallback (60 units at
+ *  weight 2: 30 calls a minute). */
+export declare const TEMPORAL_BUDGET_CEILING = 20;
+/** Seconds. Above this a frontend is refusing, not throttling — fail loudly. */
+export declare const TEMPORAL_BUDGET_MAX_RETRY_AFTER_S = 300;
+export declare const TEMPORAL_CALL_WEIGHTS: {
+    /** a list call reads a page of a cluster's records */
+    readonly list: 2;
+    /** every other unary call */
+    readonly other: 1;
+};
+export declare const TEMPORAL_RATE_BUDGET: RateBudgetDeclaration;
+/** Price one call, keyed `<service>/<method>`; an unclassified call costs the default, never nothing. */
+export declare function temporalCallWeight(service: string, method: string): number;
+/** The ledger: keyed by the frontend address, so one cluster's allowance is shared across checkouts. */
+export declare function temporalBudgetPath(opts?: {
+    root?: string;
+    token?: string;
+} | string): string;
+export type TemporalBudgetOptions = Omit<RateBudgetOptions, 'vendor'>;
+/** Temporal's budget — the kernel guard bound to this declaration (a subclass, so `instanceof`
+ *  says which ledger and ceiling it accounts against). */
+export declare class TemporalBudget extends RateBudget {
+    constructor(opts?: TemporalBudgetOptions);
+}
+export { RateBudgetError as TemporalBudgetError } from '@volter/world-core';
+export type TemporalBudgetReservation = RateBudgetReservation;
+export type TemporalBudgetSnapshot = RateBudgetSnapshot;

package/dist/src/temporal-budget.js

@@ -0,0 +1,50 @@
+// Temporal's CLIENT-SIDE RATE BUDGET — the ceiling the connector's one live call site
+// (liveTemporalExecute) enforces before a call leaves for a real frontend. The mechanism is the
+// kernel's (rateBudget.ts); this file holds only the numbers and why.
+import { declareRateBudget, rateBudgetPath, rateBudgetWeight, RateBudget, } from '@volter/world-core';
+const VENDOR = 'temporal';
+/** Rolling window, in ms. */
+export const TEMPORAL_BUDGET_WINDOW_MS = 60_000;
+/** Weighted units per window: 20 calls a minute at weight 1 — under the kernel fallback (60 units at
+ *  weight 2: 30 calls a minute). */
+export const TEMPORAL_BUDGET_CEILING = 20;
+/** Seconds. Above this a frontend is refusing, not throttling — fail loudly. */
+export const TEMPORAL_BUDGET_MAX_RETRY_AFTER_S = 300;
+export const TEMPORAL_CALL_WEIGHTS = {
+    /** a list call reads a page of a cluster's records */
+    list: 2,
+    /** every other unary call */
+    other: 1,
+};
+export const TEMPORAL_RATE_BUDGET = {
+    windowMs: TEMPORAL_BUDGET_WINDOW_MS,
+    ceiling: TEMPORAL_BUDGET_CEILING,
+    defaultWeight: TEMPORAL_CALL_WEIGHTS.other,
+    maxRetryAfterSeconds: TEMPORAL_BUDGET_MAX_RETRY_AFTER_S,
+    rules: [
+        { match: '/List[A-Za-z]*$', weight: TEMPORAL_CALL_WEIGHTS.list },
+    ],
+    reason: 'The frontend a pull reads is whatever the operator names — a self-hosted cluster whose limits are its own '
+        + 'dynamic config, or a Temporal Cloud namespace metered per namespace — so this declaration cites no vendor '
+        + 'figure. A pull is a handful of calls (ListNamespaces, then ListSearchAttributes per namespace); 20 weighted '
+        + 'units a minute, list calls at 2, sits strictly under the kernel fallback and far under any frontend\'s '
+        + 'request rate (20 plain calls, 10 list calls), so a looping caller is stopped long before it could matter to a cluster.',
+};
+declareRateBudget(VENDOR, TEMPORAL_RATE_BUDGET);
+/** Price one call, keyed `<service>/<method>`; an unclassified call costs the default, never nothing. */
+export function temporalCallWeight(service, method) {
+    return rateBudgetWeight(VENDOR, `${service}/${method}`, {});
+}
+/** The ledger: keyed by the frontend address, so one cluster's allowance is shared across checkouts. */
+export function temporalBudgetPath(opts = {}) {
+    const o = typeof opts === 'string' ? { root: opts } : opts;
+    return rateBudgetPath({ ...o, vendor: VENDOR });
+}
+/** Temporal's budget — the kernel guard bound to this declaration (a subclass, so `instanceof`
+ *  says which ledger and ceiling it accounts against). */
+export class TemporalBudget extends RateBudget {
+    constructor(opts = {}) {
+        super({ ...opts, vendor: VENDOR });
+    }
+}
+export { RateBudgetError as TemporalBudgetError } from '@volter/world-core';

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

@@ -0,0 +1,7 @@
+import { type CapabilityReport, type CapabilitySpec } from '@volter/world-tooling';
+export declare const TEMPORAL_CAPABILITIES: CapabilitySpec[];
+/** 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 declare const TEMPORAL_AREAS: readonly ["commands", "connector", "health", "history", "operatorservice", "wire", "workflowservice"];
+export declare function temporalCapabilities(): Promise<CapabilityReport>;