@xemahq/temporal-runtime 0.3.1 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/temporal-runtime",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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,23 +18,22 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist",
-    "src"
+    "dist"
   ],
   "devDependencies": {
-    "@nestjs/common": "11.1.13",
+    "@nestjs/common": "11.1.18",
     "@types/node": "25.2.3",
     "prettier": "3.6.2",
     "reflect-metadata": "0.2.2",
     "typescript": "5.9.3",
     "@xemahq/identity-client": "^0.9.1",
-    "@xemahq/kernel-contracts": "^8.0.0"
+    "@xemahq/kernel-contracts": "^13.0.0"
   },
   "peerDependencies": {
-    "@nestjs/common": "^10 || ^11",
+    "@nestjs/common": "^11.0.0",
     "reflect-metadata": "^0.2",
-    "@xemahq/identity-client": ">=0.4.0",
-    "@xemahq/kernel-contracts": ">=1.0.0"
+    "@xemahq/identity-client": "^0.9.0",
+    "@xemahq/kernel-contracts": "^12.0.0"
   },
   "dependencies": {
     "@temporalio/client": "^1.16.2",

package/src/index.ts

@@ -1,32 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// @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

@@ -1,59 +0,0 @@
-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

@@ -1,50 +0,0 @@
-/**
- * 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

@@ -1,153 +0,0 @@
-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

@@ -1,121 +0,0 @@
-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

@@ -1,58 +0,0 @@
-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

@@ -1,115 +0,0 @@
-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

@@ -1,130 +0,0 @@
-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

@@ -1,286 +0,0 @@
-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

@@ -1,31 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// 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

@@ -1,126 +0,0 @@
-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,
-        }
-      : {}),
-  });
-}