@xemahq/temporal-runtime 0.2.4 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/temporal-runtime",
-  "version": "0.2.4",
+  "version": "0.3.1",
   "description": "Temporal workers and clients for Xema — connection management, on-behalf-of auth interceptors, schedules, and search attributes.",
   "license": "Apache-2.0",
   "author": "Neuralchowder Inc. <developer@xema.dev> (https://xema.dev)",
@@ -18,7 +18,8 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "devDependencies": {
     "@nestjs/common": "11.1.13",
@@ -26,19 +27,20 @@
     "prettier": "3.6.2",
     "reflect-metadata": "0.2.2",
     "typescript": "5.9.3",
-    "@xemahq/kernel-contracts": "^0.58.0"
+    "@xemahq/identity-client": "^0.9.1",
+    "@xemahq/kernel-contracts": "^8.0.0"
   },
   "peerDependencies": {
     "@nestjs/common": "^10 || ^11",
     "reflect-metadata": "^0.2",
-    "@xemahq/kernel-contracts": ">=0.13.0"
+    "@xemahq/identity-client": ">=0.4.0",
+    "@xemahq/kernel-contracts": ">=1.0.0"
   },
   "dependencies": {
     "@temporalio/client": "^1.16.2",
     "@temporalio/common": "^1.16.2",
     "@temporalio/proto": "^1.16.2",
-    "@temporalio/worker": "^1.16.2",
-    "@xemahq/identity-client": "^0.4.0"
+    "@temporalio/worker": "^1.16.2"
   },
   "exports": {
     ".": {

package/src/index.ts

@@ -0,0 +1,32 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// @xemahq/temporal-runtime — shared runtime glue for Temporal internal-workflow
+// workers + clients.
+//
+// Every service that runs an internal-workflow worker or starts an internal
+// workflow builds on this package — one battle-tested setup, no per-service
+// drift:
+//   - connection      — mTLS / plaintext cluster connection (worker + client)
+//   - activity auth    — the on-behalf-of ALS context (activities
+//                        mint fresh credentials; tokens never ride a workflow)
+//   - worker factory   — `createPlatformWorker` wires the interceptor, the
+//                        spill codec, and Worker Versioning
+//   - service HTTP     — `ServiceHttpClient`: the generic authenticated client
+//                        every activity uses to call its domain service's
+//                        internal endpoint (activities never touch a DB)
+//   - schedule         — `upsertPlatformSchedule`: idempotent create-or-
+//                        reconcile of a platform Temporal Schedule
+//   - search attrs     — `registerPlatformSearchAttributes` +
+//                        `buildPlatformSearchAttributes`: the closed set of
+//                        `xema`-namespace Visibility attributes
+// ═══════════════════════════════════════════════════════════════════════════
+
+export * from './lib/connection';
+export * from './lib/base-temporal-client.service';
+export * from './lib/activity-auth-context';
+export * from './lib/on-behalf-of-interceptor';
+export * from './lib/worker';
+export * from './lib/auth-kind';
+export * from './lib/service-http-client';
+export * from './lib/schedule';
+export * from './lib/search-attributes';
+export * from './lib/temporal-sdk';

package/src/lib/activity-auth-context.ts

@@ -0,0 +1,59 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+/**
+ * Per-activity authentication context (token lifetime).
+ *
+ * Populated by {@link OnBehalfOfActivityInterceptor} at the start of every
+ * activity execution from the activity's first-argument `context`. Read by a
+ * service's Orval-client / HTTP-helper `getAuthToken` callbacks to decide
+ * whether to mint a user-scoped (on-behalf-of) access token or fall back to
+ * the worker's service-account token — **always minted fresh, at activity
+ * execution time**, never carried on the durable workflow.
+ *
+ * Semantics:
+ * - `actorSubject: string` — the user the workflow runs on behalf of. Every
+ *   outbound call made while this context is active acts on behalf of that
+ *   user via RFC 8693 token-exchange at identity-api.
+ * - `actorSubject: null` — a cluster-scoped activity (schedule-fired,
+ *   reconcile, …). Outbound calls use the worker's service-account token.
+ *
+ * The ALS propagates automatically across `await` boundaries inside an
+ * activity, so clients called from deep in an activity's call stack still see
+ * the same context.
+ *
+ * Naming note: this `actorSubject` is the SUBJECT of the minted token (the
+ * user), i.e. the `userId` argument of `getUserAccessToken`. It is NOT
+ * identity-api's `actorSubject` mint parameter, which names the party ACTING
+ * for that user — that is always the worker's own registered service identity.
+ */
+export interface ActivityAuthContext {
+  /** User subject (Keycloak sub). Null for system-scoped activities. */
+  readonly actorSubject: string | null;
+  /** Org the activity runs for (optional — downstream services stamp it from headers). */
+  readonly orgId?: string;
+  /** Correlation id for the downstream audit trail. */
+  readonly correlationId?: string;
+}
+
+const storage = new AsyncLocalStorage<ActivityAuthContext>();
+
+/**
+ * Read the current activity auth context. Returns `undefined` when called
+ * outside an activity execution (e.g. during worker bootstrap) — the
+ * service-account fallback is then the right default.
+ */
+export function getActivityAuthContext(): ActivityAuthContext | undefined {
+  return storage.getStore();
+}
+
+/**
+ * Run `fn` inside an activity auth context. Typically only the Temporal
+ * activity interceptor calls this; activities read the context via
+ * {@link getActivityAuthContext}.
+ */
+export async function runWithActivityAuthContext<T>(
+  context: ActivityAuthContext,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return storage.run(context, fn);
+}

package/src/lib/auth-kind.ts

@@ -0,0 +1,50 @@
+/**
+ * Closed-set classifier for the auth path the {@link ServiceHttpClient} should
+ * follow on a given request. Activities never construct bearer strings
+ * themselves; they declare *intent* and the client resolves the token via
+ * `IdentityBootstrapService`.
+ *
+ * - {@link OnBehalfOfActor} — used for activities that should attribute
+ *   work to the user who launched the run. The client reads the
+ *   activity's AsyncLocalStorage `actorSubject`. When set (a user-launched
+ *   workflow) it mints an RFC 8693 on-behalf-of token; when null (a
+ *   schedule- / reconcile-fired workflow) it falls back to the worker's
+ *   service token.
+ * - {@link Service} — used for cluster-internal flows that have no user
+ *   actor by definition (reconcile, scheduled work). Always the worker's
+ *   service token; never on-behalf-of.
+ * - {@link ExternalBearer} — used for outbound calls to third-party
+ *   endpoints (e.g. a user-supplied webhook target). The bearer is supplied
+ *   by the caller and never goes through identity-api.
+ */
+export enum ServiceAuthKind {
+  OnBehalfOfActor = 'on-behalf-of-actor',
+  Service = 'service',
+  ExternalBearer = 'external-bearer',
+  /**
+   * No `Authorization` header is set on the outbound request. Use only
+   * for genuinely unauthenticated outbound calls or for calls that
+   * authenticate via a non-Bearer mechanism (HMAC signature, mTLS,
+   * caller-supplied custom header). The client never falls through to
+   * this kind silently — callers must declare it explicitly.
+   */
+  None = 'none',
+}
+
+export type ServiceAuthSpec =
+  | {
+      readonly kind: ServiceAuthKind.OnBehalfOfActor;
+      /** Optional Keycloak audience claim narrowing. */
+      readonly audience?: string;
+    }
+  | {
+      readonly kind: ServiceAuthKind.Service;
+      readonly audience?: string;
+    }
+  | {
+      readonly kind: ServiceAuthKind.ExternalBearer;
+      readonly token: string;
+    }
+  | {
+      readonly kind: ServiceAuthKind.None;
+    };

package/src/lib/base-temporal-client.service.ts

@@ -0,0 +1,153 @@
+import {
+  Injectable,
+  Logger,
+  type OnApplicationBootstrap,
+  type OnModuleDestroy,
+} from '@nestjs/common';
+
+import {
+  connectTemporalClient,
+  resolveTemporalConnectionOptionsFromEnv,
+  type TemporalConnectionOptions,
+} from './connection';
+import { Client, Connection, type ClientOptions } from './temporal-sdk';
+
+/**
+ * Base NestJS Temporal **client** service.
+ *
+ * Several domain services hand-rolled the identical lifecycle: on bootstrap,
+ * open a {@link Connection} (resolving address + opt-in mTLS from env via
+ * {@link resolveTemporalConnectionOptionsFromEnv}), build a {@link Client}
+ * for the service's namespace, expose a null-checked `getClient()`, and close
+ * the connection on shutdown. That boilerplate — connect / build / guard /
+ * close — lives here once.
+ *
+ * What stays per-service is the only thing that genuinely varies: the
+ * namespace, the task queue, and the domain-specific `workflow.start(...)`
+ * methods. A subclass implements {@link resolveNamespace} and adds its own
+ * `start*Workflow()` methods on top of {@link getClient}.
+ *
+ * Connection-vs-client split: this base owns the CLIENT side (workflow start /
+ * signal / query). A service that ALSO hosts a worker uses
+ * `connectTemporalWorker` / `createPlatformWorker` separately — the worker
+ * channel is a different connection by design.
+ *
+ * Lifecycle is `OnApplicationBootstrap` (not `OnModuleInit`) so the cluster
+ * connection is opened after the full DI graph is constructed and never blocks
+ * module wiring. Connection close on `OnModuleDestroy` is idempotent.
+ *
+ * Adoption:
+ *
+ * ```ts
+ * @Injectable()
+ * export class OrgDbTemporalClientService extends BaseTemporalClientService {
+ *   protected resolveNamespace(): string {
+ *     return process.env.TEMPORAL_NAMESPACE ?? ORG_DB_TEMPORAL_NAMESPACE;
+ *   }
+ *
+ *   async startProvisionDatabaseWorkflow(input: ProvisionInput) {
+ *     await this.getClient().workflow.start('ProvisionDatabaseWorkflow', {
+ *       workflowId: `org-db-provision:${input.orgId}:${input.databaseName}`,
+ *       taskQueue: OrgDbTemporalTaskQueue.Main,
+ *       args: [input],
+ *     });
+ *   }
+ * }
+ * ```
+ */
+@Injectable()
+export abstract class BaseTemporalClientService
+  implements OnApplicationBootstrap, OnModuleDestroy
+{
+  protected readonly logger = new Logger(this.constructor.name);
+
+  private connection: Connection | null = null;
+  private client: Client | null = null;
+  private resolvedNamespace: string | null = null;
+
+  /**
+   * The Temporal namespace this service's client binds to. Implemented by the
+   * subclass — resolved once at bootstrap (env var, ConfigService, constant).
+   */
+  protected abstract resolveNamespace(): string;
+
+  /**
+   * Connection options for the cluster. Defaults to the standard env-var
+   * resolver every Temporal participant shares; override only when a service
+   * sources its connection settings differently (rare).
+   */
+  protected resolveConnectionOptions(): TemporalConnectionOptions {
+    return resolveTemporalConnectionOptionsFromEnv();
+  }
+
+  /**
+   * Extra {@link Client} options merged on top of `{ connection, namespace }`.
+   * Override to attach a `dataConverter` (e.g. a payload codec) or interceptors.
+   * Returns `undefined` by default — a plain client.
+   */
+  protected resolveClientOptions():
+    | Omit<ClientOptions, 'connection' | 'namespace'>
+    | undefined {
+    return undefined;
+  }
+
+  async onApplicationBootstrap(): Promise<void> {
+    const namespace = this.resolveNamespace();
+    this.connection = await connectTemporalClient(
+      this.resolveConnectionOptions(),
+    );
+    this.resolvedNamespace = namespace;
+    this.client = new Client({
+      connection: this.connection,
+      namespace,
+      ...this.resolveClientOptions(),
+    });
+    this.logger.log(`Temporal client connected (namespace=${namespace}).`);
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    if (this.connection) {
+      await this.connection.close();
+      this.connection = null;
+      this.client = null;
+      this.resolvedNamespace = null;
+      this.logger.log('Temporal client connection closed.');
+    }
+  }
+
+  /**
+   * The connected client. Fail-fast: throws if called before bootstrap or
+   * after shutdown — never returns a half-initialized client.
+   */
+  protected getClient(): Client {
+    if (!this.client) {
+      throw new Error(
+        `${this.constructor.name} is not initialized — getClient() called ` +
+          'before onApplicationBootstrap or after onModuleDestroy.',
+      );
+    }
+    return this.client;
+  }
+
+  /** The underlying connection. Same fail-fast contract as {@link getClient}. */
+  protected getConnection(): Connection {
+    if (!this.connection) {
+      throw new Error(
+        `${this.constructor.name} is not initialized — getConnection() called ` +
+          'before onApplicationBootstrap or after onModuleDestroy.',
+      );
+    }
+    return this.connection;
+  }
+
+  /** The namespace the client is bound to. Fail-fast before bootstrap. */
+  protected getNamespace(): string {
+    if (!this.resolvedNamespace) {
+      throw new Error(
+        `${this.constructor.name} is not initialized — getNamespace() called ` +
+          'before onApplicationBootstrap or after onModuleDestroy.',
+      );
+    }
+    return this.resolvedNamespace;
+  }
+}

package/src/lib/connection.ts

@@ -0,0 +1,121 @@
+import { readFileSync } from 'node:fs';
+
+import { Connection } from '@temporalio/client';
+import { NativeConnection } from '@temporalio/worker';
+
+/**
+ * Connection settings for the Temporal cluster, shared by every service that
+ * runs an internal-workflow worker or starts internal workflows.
+ *
+ * TLS is opt-in (prod): a client-cert pair for mTLS, rotated out-of-band by
+ * cert-manager. When `tls` is omitted the connection is plaintext — valid for
+ * dev / docker-compose where the cluster + service share a network segment
+ * and gRPC `:7233` is cluster-internal.
+ *
+ * `worker ↔ Temporal cluster` auth is exactly this mTLS channel — never a
+ * bearer token: tokens expire long before a durable workflow
+ * does. Per-activity service auth is minted fresh inside activities.
+ */
+export interface TemporalConnectionOptions {
+  /** gRPC frontend address, e.g. `temporal-api.xema-prod.svc.cluster.local:7233`. */
+  readonly address: string;
+  /** mTLS material. Omit for a plaintext (dev) connection. */
+  readonly tls?: {
+    readonly clientCertPath: string;
+    readonly clientKeyPath: string;
+    /** Optional SNI override when the cert CN differs from `address`. */
+    readonly serverName?: string;
+  };
+}
+
+interface ResolvedTls {
+  clientCertPair: { crt: Buffer; key: Buffer };
+  serverNameOverride?: string;
+}
+
+/**
+ * Read the client-cert pair off disk. Fail-fast: a missing/unreadable cert
+ * throws here rather than surfacing as an opaque handshake error later.
+ */
+function readTlsPair(
+  tls: NonNullable<TemporalConnectionOptions['tls']>,
+): ResolvedTls {
+  return {
+    clientCertPair: {
+      crt: readFileSync(tls.clientCertPath),
+      key: readFileSync(tls.clientKeyPath),
+    },
+    ...(tls.serverName !== undefined
+      ? { serverNameOverride: tls.serverName }
+      : {}),
+  };
+}
+
+/**
+ * A `NativeConnection` for a Temporal **Worker** (the queue-polling side).
+ * Used by every service hosting an internal-workflow worker.
+ */
+export async function connectTemporalWorker(
+  options: TemporalConnectionOptions,
+): Promise<NativeConnection> {
+  if (!options.tls) {
+    return NativeConnection.connect({ address: options.address });
+  }
+  return NativeConnection.connect({
+    address: options.address,
+    tls: readTlsPair(options.tls),
+  });
+}
+
+/**
+ * A `Connection` for a Temporal **Client** (the workflow start / signal /
+ * query side). Used wherever a service starts an internal workflow — e.g.
+ * `SessionService.create()` starting `SessionLaunchWorkflow`.
+ */
+export async function connectTemporalClient(
+  options: TemporalConnectionOptions,
+): Promise<Connection> {
+  if (!options.tls) {
+    return Connection.connect({ address: options.address });
+  }
+  return Connection.connect({
+    address: options.address,
+    tls: readTlsPair(options.tls),
+  });
+}
+
+/**
+ * Build {@link TemporalConnectionOptions} from the standard env vars every
+ * Temporal participant reads: `TEMPORAL_ADDRESS` (required) plus the opt-in
+ * `TEMPORAL_TLS_*` set. One resolver so a worker and a schedule-creating
+ * domain service connect with identical semantics — no per-service drift.
+ *
+ * Fail-fast: a missing address, or `TEMPORAL_TLS_ENABLED=true` without both
+ * cert paths, throws here rather than degrading to a wrong connection.
+ */
+export function resolveTemporalConnectionOptionsFromEnv(): TemporalConnectionOptions {
+  const address = process.env.TEMPORAL_ADDRESS?.trim();
+  if (!address) {
+    throw new Error('TEMPORAL_ADDRESS is required for a Temporal connection.');
+  }
+  if (process.env.TEMPORAL_TLS_ENABLED !== 'true') {
+    return { address };
+  }
+  const clientCertPath = process.env.TEMPORAL_TLS_CLIENT_CERT_PATH?.trim();
+  const clientKeyPath = process.env.TEMPORAL_TLS_CLIENT_KEY_PATH?.trim();
+  if (!clientCertPath || !clientKeyPath) {
+    throw new Error(
+      'TEMPORAL_TLS_ENABLED=true requires both TEMPORAL_TLS_CLIENT_CERT_PATH ' +
+        'and TEMPORAL_TLS_CLIENT_KEY_PATH.',
+    );
+  }
+  const serverName = process.env.TEMPORAL_TLS_SERVER_NAME?.trim();
+  return {
+    address,
+    tls: {
+      clientCertPath,
+      clientKeyPath,
+      ...(serverName ? { serverName } : {}),
+    },
+  };
+}

package/src/lib/on-behalf-of-interceptor.ts

@@ -0,0 +1,58 @@
+import {
+  type ActivityAuthContext,
+  runWithActivityAuthContext,
+} from './activity-auth-context';
+
+import type {
+  ActivityExecuteInput,
+  ActivityInboundCallsInterceptor,
+  Next,
+} from '@temporalio/worker';
+
+/**
+ * Temporal ActivityInbound interceptor that populates
+ * {@link ActivityAuthContext} from the activity's first argument.
+ *
+ * Every activity is dispatched with a `context` object on its first argument
+ * carrying `actorSubject` (the user the workflow runs on behalf of) plus
+ * `orgId` and `correlationId` — the calling workflow supplies it. Wrapping
+ * `execute()` in the ALS means every outbound call inside the activity can
+ * read the actor without changing each activity's signature, and mint a
+ * fresh on-behalf-of token at call time.
+ *
+ * For activities with no user attribution (cluster-scoped: reconcile,
+ * schedule-fired) the ALS is still set but `actorSubject` is null, so the
+ * client `getAuthToken` callback cleanly falls back to the worker's
+ * service-account token.
+ */
+export class OnBehalfOfActivityInterceptor
+  implements ActivityInboundCallsInterceptor
+{
+  async execute(
+    input: ActivityExecuteInput,
+    next: Next<ActivityInboundCallsInterceptor, 'execute'>,
+  ): Promise<unknown> {
+    const context = extractAuthContext(input);
+    return runWithActivityAuthContext(context, () => next(input));
+  }
+}
+
+function extractAuthContext(input: ActivityExecuteInput): ActivityAuthContext {
+  const first = input.args[0] as
+    | {
+        context?: {
+          actorSubject?: string | null;
+          orgId?: string;
+          correlationId?: string;
+        };
+      }
+    | undefined;
+  const ctx = first?.context;
+  return {
+    actorSubject: ctx?.actorSubject ?? null,
+    ...(ctx?.orgId !== undefined ? { orgId: ctx.orgId } : {}),
+    ...(ctx?.correlationId !== undefined
+      ? { correlationId: ctx.correlationId }
+      : {}),
+  };
+}

package/src/lib/schedule.ts

@@ -0,0 +1,115 @@
+import { ScheduleAlreadyRunning } from '@temporalio/client';
+
+import type { Client } from '@temporalio/client';
+import type { Duration, Workflow } from '@temporalio/common';
+
+/**
+ * Code-owned description of a platform Temporal Schedule.
+ *
+ * Captures only the half a service *owns in code* — the cadence, the
+ * workflow action, the overlap policy. Operator-owned state (`paused`, and
+ * the schedule `note` after first create) is never overwritten by
+ * {@link upsertPlatformSchedule}: it is read from the live schedule and
+ * preserved verbatim.
+ */
+export interface PlatformScheduleSpec {
+  /** Stable schedule id — also reused as the per-run base workflow id. */
+  readonly scheduleId: string;
+  /** Fixed-interval cadence between runs. */
+  readonly every: Duration;
+  /**
+   * Catch-up window after worker/cluster downtime. Keep this short — one
+   * sweep is enough, so a recovered cluster never replays a backlog.
+   */
+  readonly catchupWindow: Duration;
+  /** Registered workflow type the schedule starts. */
+  readonly workflowType: string;
+  /** `xema-platform.*` task queue the workflow runs on. */
+  readonly taskQueue: string;
+  /**
+   * Workflow start args. For platform schedules this is the single
+   * `{ callbackBaseUrl }` object — the worker holds no service URLs.
+   */
+  readonly args: readonly unknown[];
+  /**
+   * Human-readable note stamped on the schedule the first time it is
+   * created. On a later reconcile the operator's live note is preserved
+   * instead, so an operator annotation is never clobbered.
+   */
+  readonly note: string;
+  /**
+   * Visibility search attributes tagged onto every workflow the schedule
+   * starts — build with `buildPlatformSearchAttributes`. The
+   * referenced attributes must already be registered on the namespace
+   * (`registerPlatformSearchAttributes`), or the cluster rejects the start.
+   */
+  readonly searchAttributes?: Record<string, string[]>;
+}
+
+/** Outcome of an upsert — `created` is `true` only on the first-ever boot. */
+export interface UpsertPlatformScheduleResult {
+  readonly created: boolean;
+}
+
+/**
+ * Create — or, if it already exists, reconcile — a platform Temporal
+ * Schedule. Idempotent and multi-replica safe: a create race resolves via
+ * `ScheduleAlreadyRunning` → the update path, and concurrent updates all
+ * write the same code-owned definition.
+ *
+ * The code-owned half (cadence + action + policies) is always written; the
+ * operator-owned half (`paused` + `note`) is read from the live schedule and
+ * preserved. Any non-`ScheduleAlreadyRunning` error is rethrown so a service
+ * whose schedule cannot be registered fails its boot loudly.
+ */
+export async function upsertPlatformSchedule(
+  client: Client,
+  spec: PlatformScheduleSpec,
+): Promise<UpsertPlatformScheduleResult> {
+  const definition = {
+    spec: { intervals: [{ every: spec.every }] },
+    action: {
+      type: 'startWorkflow' as const,
+      workflowType: spec.workflowType,
+      taskQueue: spec.taskQueue,
+      args: spec.args as unknown[],
+      // Temporal appends the scheduled time so every run gets a distinct id.
+      workflowId: spec.scheduleId,
+      ...(spec.searchAttributes
+        ? { searchAttributes: spec.searchAttributes }
+        : {}),
+    },
+    policies: {
+      // A slow tick is compensated by the next one — never pile up.
+      overlap: 'SKIP' as const,
+      catchupWindow: spec.catchupWindow,
+    },
+  };
+
+  try {
+    // Explicit `<Workflow>` pins the schedule-action generic to the loose
+    // base type — `workflowType` is a string, not a workflow reference, so
+    // without this TS narrows the generic and demands every optional field.
+    await client.schedule.create<Workflow>({
+      scheduleId: spec.scheduleId,
+      ...definition,
+      // Initial operator-owned state — applied only on first create.
+      state: { paused: false, note: spec.note },
+    });
+    return { created: true };
+  } catch (err) {
+    if (!(err instanceof ScheduleAlreadyRunning)) {
+      // Any other error is load-bearing — the caller must fail boot so
+      // operators see why the schedule is not firing.
+      throw err;
+    }
+    // Schedule exists — reconcile the code-owned definition. Operator-owned
+    // state (paused, note) is read from the live schedule and preserved.
+    const handle = client.schedule.getHandle(spec.scheduleId);
+    await handle.update<Workflow>((previous) => ({
+      ...definition,
+      state: { paused: previous.state.paused, note: previous.state.note },
+    }));
+    return { created: false };
+  }
+}

package/src/lib/search-attributes.ts

@@ -0,0 +1,130 @@
+import { temporal } from '@temporalio/proto';
+
+import type { Connection } from '@temporalio/client';
+import type { PlatformWorkflowDomain } from '@xemahq/kernel-contracts/workflow';
+
+/**
+ * Custom Temporal Visibility search attributes the platform tags onto every
+ * internal workflow run in the `xema` namespace. A closed set,
+ * registered idempotently before any producer starts a workflow:
+ *
+ *   - `OrgId` / `ProjectId` — the owning tenant (absent on cluster-wide
+ *     sweeps such as the reconcile / checkpoint schedules);
+ *   - `WorkflowDomain` — the {@link PlatformWorkflowDomain} the run belongs
+ *     to (session-lifecycle, studio, workload, …);
+ *   - `SubjectId` — the generic resource the run operates on (sessionId,
+ *     studioId, …).
+ *
+ * Single source of truth — never mirror this list in helm values, compose
+ * files, or external bootstrap scripts. Adding an attribute is a one-line
+ * change here; the next registration call picks it up.
+ */
+export const SEARCH_ATTR_ORG_ID = 'OrgId';
+export const SEARCH_ATTR_PROJECT_ID = 'ProjectId';
+export const SEARCH_ATTR_WORKFLOW_DOMAIN = 'WorkflowDomain';
+export const SEARCH_ATTR_SUBJECT_ID = 'SubjectId';
+/** Connector provider id — for outbox forwarders, OAuth saga runs. */
+export const SEARCH_ATTR_INTEGRATION_PROVIDER_ID = 'IntegrationProviderId';
+/** Registry kind ('npm' | 'container') — for image/package workflows. */
+export const SEARCH_ATTR_REGISTRY_KIND = 'RegistryKind';
+/** Container image digest ('sha256:…') — for image-build/publish flows. */
+export const SEARCH_ATTR_IMAGE_DIGEST = 'ImageDigest';
+
+interface PlatformSearchAttribute {
+  readonly name: string;
+  readonly type: temporal.api.enums.v1.IndexedValueType;
+}
+
+const KEYWORD =
+  temporal.api.enums.v1.IndexedValueType.INDEXED_VALUE_TYPE_KEYWORD;
+
+/** The closed set of platform search attributes — all `KEYWORD`-typed. */
+export const PLATFORM_SEARCH_ATTRIBUTES: readonly PlatformSearchAttribute[] = [
+  { name: SEARCH_ATTR_ORG_ID, type: KEYWORD },
+  { name: SEARCH_ATTR_PROJECT_ID, type: KEYWORD },
+  { name: SEARCH_ATTR_WORKFLOW_DOMAIN, type: KEYWORD },
+  { name: SEARCH_ATTR_SUBJECT_ID, type: KEYWORD },
+  { name: SEARCH_ATTR_INTEGRATION_PROVIDER_ID, type: KEYWORD },
+  { name: SEARCH_ATTR_REGISTRY_KIND, type: KEYWORD },
+  { name: SEARCH_ATTR_IMAGE_DIGEST, type: KEYWORD },
+];
+
+/** Identity references a platform workflow is tagged with. */
+export interface PlatformSearchAttributeInput {
+  /** The domain the run belongs to — always set. */
+  readonly workflowDomain: PlatformWorkflowDomain;
+  /** Owning org — omit for a cluster-wide sweep. */
+  readonly orgId?: string;
+  /** Owning project — omit for a cluster-wide sweep. */
+  readonly projectId?: string;
+  /** The resource the run operates on (sessionId, studioId, …). */
+  readonly subjectId?: string;
+}
+
+/**
+ * Build the `searchAttributes` map for a `workflow.start` / schedule action.
+ * Only set attributes are emitted — a cluster-wide sweep with no tenant
+ * carries `WorkflowDomain` alone.
+ */
+export function buildPlatformSearchAttributes(
+  input: PlatformSearchAttributeInput,
+): Record<string, string[]> {
+  const attrs: Record<string, string[]> = {
+    [SEARCH_ATTR_WORKFLOW_DOMAIN]: [input.workflowDomain],
+  };
+  if (input.orgId) {
+    attrs[SEARCH_ATTR_ORG_ID] = [input.orgId];
+  }
+  if (input.projectId) {
+    attrs[SEARCH_ATTR_PROJECT_ID] = [input.projectId];
+  }
+  if (input.subjectId) {
+    attrs[SEARCH_ATTR_SUBJECT_ID] = [input.subjectId];
+  }
+  return attrs;
+}
+
+/** Outcome of a registration call — the attribute names newly added. */
+export interface RegisterSearchAttributesResult {
+  readonly registered: readonly string[];
+}
+
+/**
+ * Idempotently register {@link PLATFORM_SEARCH_ATTRIBUTES} on a Temporal
+ * namespace. Lists the namespace's existing custom attributes first and adds
+ * only what is missing, so a multi-replica / multi-service boot is race-safe
+ * — every starter calls this before it can `workflow.start` an attribute that
+ * the cluster would otherwise reject.
+ *
+ * Fail-fast: any operator-service error propagates so the caller aborts boot
+ * loudly rather than starting workflows whose Visibility tags will be refused.
+ *
+ * @param connection  A Temporal **client** `Connection` (the worker's
+ *   `NativeConnection` has no `operatorService`).
+ * @param namespace   The namespace to register on — `xema` for platform work.
+ */
+export async function registerPlatformSearchAttributes(
+  connection: Connection,
+  namespace: string,
+): Promise<RegisterSearchAttributesResult> {
+  const listResponse = await connection.operatorService.listSearchAttributes({
+    namespace,
+  });
+  const existing = new Set(Object.keys(listResponse.customAttributes ?? {}));
+  const missing = PLATFORM_SEARCH_ATTRIBUTES.filter(
+    (attr) => !existing.has(attr.name),
+  );
+  if (missing.length === 0) {
+    return { registered: [] };
+  }
+
+  const searchAttributes: Record<string, number> = {};
+  for (const attr of missing) {
+    searchAttributes[attr.name] = attr.type;
+  }
+  await connection.operatorService.addSearchAttributes({
+    namespace,
+    searchAttributes,
+  });
+  return { registered: missing.map((attr) => attr.name) };
+}

package/src/lib/service-http-client.ts

@@ -0,0 +1,286 @@
+import { randomUUID } from 'node:crypto';
+
+import { Injectable, Logger, Optional } from '@nestjs/common';
+import { IdentityBootstrapService } from '@xemahq/identity-client';
+
+import { getActivityAuthContext } from './activity-auth-context';
+import { ServiceAuthKind, type ServiceAuthSpec } from './auth-kind';
+
+/**
+ * Request input for {@link ServiceHttpClient.request}. Deliberately narrow:
+ * we want activities to construct the full URL (including query string) at
+ * their own layer, so the client focuses on transport semantics + auth/
+ * correlation propagation.
+ */
+export interface ServiceRequest {
+  readonly method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  readonly url: string;
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly body?: string | Uint8Array | null;
+  /** Per-request timeout override. Defaults to the client's configured timeout. */
+  readonly timeoutMs?: number;
+  /**
+   * Auth resolution intent. The client resolves the bearer token from
+   * here — callers never pass a raw token (except `ExternalBearer`).
+   */
+  readonly auth: ServiceAuthSpec;
+  /** X-Xema-Org-Id header value. Must be set for any org-scoped call. */
+  readonly orgId?: string;
+  /** X-Project-Id header value. */
+  readonly projectId?: string;
+  /** X-Correlation-Id header value. Falls back to a generated correlation id. */
+  readonly correlationId?: string;
+  /**
+   * Optional override for the `X-Xema-Actor-Subject` audit-attribution
+   * header. When omitted, the client reads the activity's ALS-stored
+   * `actorSubject`. Activities should leave this unset; only specialised
+   * flows that attribute to a different subject would override it.
+   */
+  readonly actorSubject?: string | null;
+  /**
+   * `X-Pipeline-Run-Id` header value. Forwarded to downstream services
+   * so their `RequestContextMiddleware` can populate `pipelineRunId` on
+   * the request context (and, in turn, on any rows the call writes —
+   * pages, artifacts, audit log, etc.). Activities should pass
+   * `context.workflowRunId` here so workflow runs and pipeline runs
+   * share one provenance column downstream.
+   */
+  readonly pipelineRunId?: string;
+  /**
+   * `X-Pipeline-Phase-Key` header value. Forwarded alongside
+   * `pipelineRunId`. Activities should pass `context.jobKey` so the
+   * workflow lane the call originated from is preserved in downstream
+   * provenance records.
+   */
+  readonly pipelinePhaseKey?: string;
+}
+
+export interface ServiceResponse<TBody = unknown> {
+  readonly status: number;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: TBody;
+  /** Raw body bytes (for callers that need non-JSON). */
+  readonly rawBody: string;
+}
+
+export interface ServiceHttpClientOptions {
+  /** Default request timeout in ms. Activities can override per-call. */
+  readonly defaultTimeoutMs?: number;
+  /** Correlation id generator. Defaults to a uuid-style random id. */
+  readonly correlationIdFactory?: () => string;
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/**
+ * Shared HTTP client every Temporal activity uses when calling a downstream
+ * service. Single-responsibility wrapper around `fetch`:
+ *   - Token resolution via {@link IdentityBootstrapService} based on
+ *     {@link ServiceAuthSpec}. ALS-driven attribution: when the activity
+ *     runs for a user-launched workflow the {@link OnBehalfOfActivityInterceptor}
+ *     has populated `actorSubject`, and an `OnBehalfOfActor` request mints a
+ *     fresh on-behalf-of token; otherwise it falls back to the worker's
+ *     service-account token.
+ *   - `X-Xema-Org-Id` / `X-Project-Id` / `X-Correlation-Id` /
+ *     `X-Xema-Actor-Subject` header propagation.
+ *   - Consistent timeout handling (AbortController).
+ *   - Response parsing: JSON unless the server replies with a non-JSON
+ *     Content-Type (in which case the rawBody is returned and `body` is set
+ *     to the same string).
+ *
+ * Tokens are minted *inside* the activity, immediately before the call
+ * — no credential ever rides a durable workflow. Activities
+ * should NOT construct their own fetch requests: this wrapper is the single
+ * chokepoint that stamps every downstream call with the originating subject
+ * and a correlation id.
+ */
+@Injectable()
+export class ServiceHttpClient {
+  private readonly logger = new Logger(ServiceHttpClient.name);
+  private readonly defaultTimeoutMs: number;
+  private readonly correlationIdFactory: () => string;
+
+  constructor(
+    private readonly identity: IdentityBootstrapService,
+    @Optional() options?: ServiceHttpClientOptions,
+  ) {
+    this.defaultTimeoutMs = options?.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.correlationIdFactory = options?.correlationIdFactory ?? defaultCorrelationIdFactory;
+  }
+
+  async request<TBody = unknown>(req: ServiceRequest): Promise<ServiceResponse<TBody>> {
+    const controller = new AbortController();
+    const timeoutMs = req.timeoutMs ?? this.defaultTimeoutMs;
+    // Only bounds remote hangs — justified per the engineering rule on
+    // timeouts: external network call with an explicit deadline, typed
+    // error, observable in logs.
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+    const authToken = await this.resolveToken(req.auth);
+    const headers = this.buildHeaders(req, authToken);
+    const init: RequestInit = {
+      method: req.method,
+      headers,
+      signal: controller.signal,
+      ...(req.body !== undefined && req.body !== null && {
+        body:
+          typeof req.body === 'string'
+            ? req.body
+            : Buffer.from(req.body.buffer, req.body.byteOffset, req.body.byteLength),
+      }),
+    };
+
+    try {
+      const response = await fetch(req.url, init);
+      const rawBody = await response.text();
+      const body = this.parseBody<TBody>(rawBody, response);
+      const outHeaders: Record<string, string> = {};
+      response.headers.forEach((value, key) => {
+        outHeaders[key] = value;
+      });
+      this.logger.debug(
+        `${req.method} ${req.url} → ${response.status} (${rawBody.length} bytes)`,
+      );
+      return {
+        status: response.status,
+        headers: outHeaders,
+        body,
+        rawBody,
+      };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /** Convenience JSON helper. Throws on non-2xx. */
+  async requestJsonOrThrow<TBody = unknown>(req: ServiceRequest): Promise<TBody> {
+    const response = await this.request<TBody>(req);
+    if (response.status < 200 || response.status >= 300) {
+      throw new ServiceHttpError(
+        `${req.method} ${req.url} failed with status ${response.status}`,
+        {
+          status: response.status,
+          rawBody: response.rawBody,
+          method: req.method,
+          url: req.url,
+        },
+      );
+    }
+    return response.body;
+  }
+
+  private async resolveToken(spec: ServiceAuthSpec): Promise<string | null> {
+    switch (spec.kind) {
+      case ServiceAuthKind.OnBehalfOfActor: {
+        const actor = getActivityAuthContext();
+        if (actor?.actorSubject) {
+          if (!actor.orgId) {
+            throw new Error(
+              'Activity auth context missing orgId for on-behalf-of token mint',
+            );
+          }
+          // The acting party is THIS worker process — the party that will
+          // exercise the user's authority downstream. It must be the
+          // worker's own registered identity: identity-api binds the actor
+          // a caller may name to the credential it proved.
+          const params = spec.audience !== undefined
+            ? {
+                userId: actor.actorSubject,
+                actorSubject: this.identity.serviceName,
+                orgId: actor.orgId,
+                audience: spec.audience,
+              }
+            : {
+                userId: actor.actorSubject,
+                actorSubject: this.identity.serviceName,
+                orgId: actor.orgId,
+              };
+          return this.identity.getUserAccessToken(params);
+        }
+        return this.identity.getAccessToken();
+      }
+      case ServiceAuthKind.Service:
+        return this.identity.getAccessToken();
+      case ServiceAuthKind.ExternalBearer:
+        return spec.token;
+      case ServiceAuthKind.None:
+        return null;
+    }
+  }
+
+  private buildHeaders(req: ServiceRequest, authToken: string | null): Headers {
+    const headers = new Headers(req.headers ?? {});
+    if (authToken !== null) {
+      headers.set('Authorization', `Bearer ${authToken}`);
+    }
+    if (req.orgId) {
+      headers.set('X-Xema-Org-Id', req.orgId);
+    }
+    if (req.projectId) {
+      headers.set('X-Project-Id', req.projectId);
+    }
+    if (req.pipelineRunId) {
+      headers.set('X-Pipeline-Run-Id', req.pipelineRunId);
+    }
+    if (req.pipelinePhaseKey) {
+      headers.set('X-Pipeline-Phase-Key', req.pipelinePhaseKey);
+    }
+    headers.set('X-Correlation-Id', req.correlationId ?? this.correlationIdFactory());
+    const actorSubject =
+      req.actorSubject !== undefined
+        ? req.actorSubject
+        : (getActivityAuthContext()?.actorSubject ?? null);
+    if (actorSubject) {
+      // Documented in API_STANDARDS: downstream audit logs attribute
+      // actions to the originating user, NOT the worker identity.
+      headers.set('X-Xema-Actor-Subject', actorSubject);
+    }
+    if (!headers.has('Content-Type') && req.body !== undefined && req.body !== null) {
+      headers.set('Content-Type', typeof req.body === 'string' ? 'application/json' : 'application/octet-stream');
+    }
+    return headers;
+  }
+
+  private parseBody<TBody>(raw: string, response: Response): TBody {
+    if (raw.length === 0) {
+      return null as unknown as TBody;
+    }
+    const contentType = response.headers.get('content-type') ?? '';
+    if (contentType.includes('application/json')) {
+      try {
+        return JSON.parse(raw) as TBody;
+      } catch (err) {
+        throw new ServiceHttpError(
+          `Failed to parse JSON response: ${(err as Error).message}`,
+          { status: response.status, rawBody: raw },
+        );
+      }
+    }
+    return raw as unknown as TBody;
+  }
+}
+
+/** Typed error surface for HTTP failures; activities rethrow or branch on `.status`. */
+export class ServiceHttpError extends Error {
+  readonly status: number;
+  readonly rawBody: string;
+  readonly method: string;
+  readonly url: string;
+
+  constructor(
+    message: string,
+    details: { status: number; rawBody: string; method?: string; url?: string },
+  ) {
+    super(message);
+    this.name = 'ServiceHttpError';
+    this.status = details.status;
+    this.rawBody = details.rawBody;
+    this.method = details.method ?? '';
+    this.url = details.url ?? '';
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+function defaultCorrelationIdFactory(): string {
+  return `urn:xema:${randomUUID()}`;
+}

package/src/lib/temporal-sdk.ts

@@ -0,0 +1,31 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// Temporal SDK re-exports — the single import surface for the raw `@temporalio`
+// client primitives that platform services need.
+//
+// `@xemahq/temporal-runtime` is the one battle-tested Temporal setup; every
+// service builds on it instead of wiring the SDK itself. A consumer that ALSO
+// imports `@temporalio/client` directly creates a SECOND copy of the
+// `@temporalio/*` dependency tree in its own `node_modules`. Under
+// `--preserve-symlinks` (required by pnpm + Prisma's generated client) Node
+// then loads `@temporalio/proto` twice from two symlink paths, and
+// `@temporalio/proto/protos/json-module.js` re-registers its protobuf schema
+// into the process-wide protobufjs `Root` → `duplicate name 'ActivityHeartbeat'`.
+//
+// Routing every client-side SDK import through this barrel keeps exactly one
+// `@temporalio/*` tree (the one owned by this package) in the graph, so the
+// proto module loads exactly once. Consumers MUST NOT depend on
+// `@temporalio/client` / `@temporalio/common` directly for client-side use.
+// ═══════════════════════════════════════════════════════════════════════════
+
+export {
+  Client,
+  Connection,
+  ScheduleAlreadyRunning,
+  WorkflowExecutionAlreadyStartedError,
+} from '@temporalio/client';
+export type {
+  ClientOptions,
+  ConnectionOptions,
+  WorkflowExecutionStatusName,
+} from '@temporalio/client';
+export type { Duration, Workflow } from '@temporalio/common';

package/src/lib/worker.ts

@@ -0,0 +1,126 @@
+import { randomUUID } from 'node:crypto';
+
+import {
+  bundleWorkflowCode,
+  Worker,
+  type ActivityInterceptorsFactory,
+  type NativeConnection,
+  type WorkerOptions,
+  type WorkflowBundle,
+} from '@temporalio/worker';
+
+import { OnBehalfOfActivityInterceptor } from './on-behalf-of-interceptor';
+
+import type { PayloadCodec } from '@temporalio/common';
+
+/**
+ * Worker sinks (e.g. the OpenTelemetry workflow-span sink). Aliased to
+ * Temporal's own `WorkerOptions['sinks']` so callers pass the native shape.
+ */
+export type PlatformWorkerSinks = NonNullable<WorkerOptions['sinks']>;
+
+export interface BundlePlatformWorkflowsOptions {
+  /**
+   * Extra workflow-side interceptor modules to compile INTO the bundle (e.g.
+   * the OpenTelemetry workflow interceptor from `otelWorkflowInterceptorModule`)
+   * so trace context propagates through the workflow to its activities.
+   */
+  readonly workflowInterceptorModules?: readonly string[];
+}
+
+/**
+ * Compile a service's workflow bundle once. A service that runs several
+ * internal-workflow workers (one per task queue) bundles once and passes the
+ * same `WorkflowBundle` to every `createPlatformWorker` call.
+ */
+export async function bundlePlatformWorkflows(
+  workflowsPath: string,
+  options?: BundlePlatformWorkflowsOptions,
+): Promise<WorkflowBundle> {
+  return bundleWorkflowCode({
+    workflowsPath,
+    ...(options?.workflowInterceptorModules !== undefined
+      ? { workflowInterceptorModules: [...options.workflowInterceptorModules] }
+      : {}),
+  });
+}
+
+export interface PlatformWorkerOptions {
+  /** Cluster connection from `connectTemporalWorker`. */
+  readonly connection: NativeConnection;
+  /** Always the `xema` platform namespace for internal workflows. */
+  readonly namespace: string;
+  /** `platformTaskQueue(domain)` from `@xemahq/kernel-contracts/workflow`. */
+  readonly taskQueue: string;
+  /** Pre-built via `bundlePlatformWorkflows` (bundle once, create many). */
+  readonly workflowBundle: WorkflowBundle;
+  /** Activity implementations registered on this worker. */
+  readonly activities: object;
+  /**
+   * Worker-Versioning build id — pins an in-flight workflow to a compatible
+   * worker so a non-deterministic workflow edit cannot break replay.
+   */
+  readonly buildId: string;
+  readonly useVersioning?: boolean;
+  /**
+   * Spill codec for large payloads (`@xemahq/dsl/payload-codec`). Omit
+   * for small-payload workers / dev.
+   */
+  readonly payloadCodec?: PayloadCodec;
+  readonly maxConcurrentActivityTaskExecutions?: number;
+  readonly maxConcurrentWorkflowTaskExecutions?: number;
+  /**
+   * Extra activity interceptor factories, appended AFTER the platform's own
+   * on-behalf-of interceptor (e.g. an OpenTelemetry activity interceptor).
+   */
+  readonly activityInterceptors?: readonly ActivityInterceptorsFactory[];
+  /** Worker sinks (e.g. the OTel workflow-span sink). */
+  readonly sinks?: PlatformWorkerSinks;
+}
+
+/**
+ * Create a Temporal Worker for an internal-workflow task queue. Wraps
+ * `Worker.create` with the platform defaults: the
+ * {@link OnBehalfOfActivityInterceptor} (every activity runs in a fresh
+ * on-behalf-of identity context), an optional spill payload
+ * codec, and Worker Versioning.
+ *
+ * `worker.run()` is the caller's responsibility — a service starts it off
+ * `OnApplicationBootstrap` and awaits the returned promise on shutdown.
+ */
+export async function createPlatformWorker(
+  options: PlatformWorkerOptions,
+): Promise<Worker> {
+  return Worker.create({
+    connection: options.connection,
+    namespace: options.namespace,
+    taskQueue: options.taskQueue,
+    workflowBundle: options.workflowBundle,
+    activities: options.activities,
+    identity: `xema-platform-worker-${options.namespace}-${options.taskQueue}-${randomUUID().slice(0, 8)}`,
+    interceptors: {
+      activity: [
+        () => ({ inbound: new OnBehalfOfActivityInterceptor() }),
+        ...(options.activityInterceptors ?? []),
+      ],
+    },
+    ...(options.sinks !== undefined ? { sinks: options.sinks } : {}),
+    buildId: options.buildId,
+    useVersioning: options.useVersioning ?? false,
+    ...(options.payloadCodec
+      ? { dataConverter: { payloadCodecs: [options.payloadCodec] } }
+      : {}),
+    ...(options.maxConcurrentActivityTaskExecutions !== undefined
+      ? {
+          maxConcurrentActivityTaskExecutions:
+            options.maxConcurrentActivityTaskExecutions,
+        }
+      : {}),
+    ...(options.maxConcurrentWorkflowTaskExecutions !== undefined
+      ? {
+          maxConcurrentWorkflowTaskExecutions:
+            options.maxConcurrentWorkflowTaskExecutions,
+        }
+      : {}),
+  });
+}