@codemation/host 0.2.5 → 0.3.1

package/src/domain/telemetry/TelemetryContracts.ts

@@ -0,0 +1,197 @@
+import type {
+  TelemetryArtifactAttachment,
+  TelemetryAttributes,
+  TelemetryMetricRecord,
+  TelemetrySpanEventRecord,
+} from "@codemation/core";
+
+export type TelemetrySpanStatus = "running" | "completed" | "failed";
+export type TelemetrySpanKind = "internal" | "client";
+
+export interface TelemetryTraceContext {
+  readonly runId: string;
+  readonly workflowId: string;
+  readonly traceId: string;
+  readonly rootSpanId: string;
+  readonly serviceName?: string;
+  readonly createdAt: string;
+  readonly expiresAt?: string;
+}
+
+export interface TelemetrySpanRecord {
+  readonly traceId: string;
+  readonly spanId: string;
+  readonly parentSpanId?: string;
+  readonly runId: string;
+  readonly workflowId: string;
+  readonly nodeId?: string;
+  readonly activationId?: string;
+  readonly connectionInvocationId?: string;
+  readonly name: string;
+  readonly kind: TelemetrySpanKind;
+  readonly status?: TelemetrySpanStatus;
+  readonly statusMessage?: string;
+  readonly startTime?: string;
+  readonly endTime?: string;
+  readonly workflowFolder?: string;
+  readonly nodeType?: string;
+  readonly nodeRole?: string;
+  readonly modelName?: string;
+  readonly attributes?: TelemetryAttributes;
+  readonly events?: ReadonlyArray<TelemetrySpanEventRecord>;
+  readonly retentionExpiresAt?: string;
+}
+
+export interface TelemetrySpanUpsert {
+  readonly traceId: string;
+  readonly spanId: string;
+  readonly parentSpanId?: string;
+  readonly runId: string;
+  readonly workflowId: string;
+  readonly nodeId?: string;
+  readonly activationId?: string;
+  readonly connectionInvocationId?: string;
+  readonly name?: string;
+  readonly kind?: TelemetrySpanKind;
+  readonly status?: TelemetrySpanStatus;
+  readonly statusMessage?: string;
+  readonly startTime?: string;
+  readonly endTime?: string;
+  readonly workflowFolder?: string;
+  readonly nodeType?: string;
+  readonly nodeRole?: string;
+  readonly modelName?: string;
+  readonly attributes?: TelemetryAttributes;
+  readonly events?: ReadonlyArray<TelemetrySpanEventRecord>;
+  readonly retentionExpiresAt?: string;
+}
+
+export interface TelemetryArtifactRecord {
+  readonly artifactId: string;
+  readonly traceId: string;
+  readonly spanId: string;
+  readonly runId: string;
+  readonly workflowId: string;
+  readonly nodeId?: string;
+  readonly activationId?: string;
+  readonly kind: string;
+  readonly contentType: string;
+  readonly previewText?: string;
+  readonly previewJson?: unknown;
+  readonly payloadText?: string;
+  readonly payloadJson?: unknown;
+  readonly bytes?: number;
+  readonly truncated?: boolean;
+  readonly createdAt: string;
+  readonly expiresAt?: string;
+  readonly retentionExpiresAt?: string;
+}
+
+export interface TelemetryArtifactWrite extends TelemetryArtifactAttachment {
+  readonly traceId: string;
+  readonly spanId: string;
+  readonly runId: string;
+  readonly workflowId: string;
+  readonly nodeId?: string;
+  readonly activationId?: string;
+  readonly retentionExpiresAt?: string;
+}
+
+export interface TelemetryMetricPointRecord {
+  readonly metricPointId: string;
+  readonly traceId?: string;
+  readonly spanId?: string;
+  readonly runId?: string;
+  readonly workflowId: string;
+  readonly nodeId?: string;
+  readonly activationId?: string;
+  readonly metricName: string;
+  readonly value: number;
+  readonly unit?: string;
+  readonly observedAt: string;
+  readonly workflowFolder?: string;
+  readonly nodeType?: string;
+  readonly nodeRole?: string;
+  readonly modelName?: string;
+  readonly dimensions?: TelemetryAttributes;
+  readonly retentionExpiresAt?: string;
+}
+
+export interface TelemetryMetricPointWrite extends TelemetryMetricRecord {
+  readonly traceId?: string;
+  readonly spanId?: string;
+  readonly runId?: string;
+  readonly workflowId: string;
+  readonly nodeId?: string;
+  readonly activationId?: string;
+  readonly observedAt: string;
+  readonly workflowFolder?: string;
+  readonly nodeType?: string;
+  readonly nodeRole?: string;
+  readonly modelName?: string;
+  readonly retentionExpiresAt?: string;
+}
+
+export interface TelemetrySpanListQuery {
+  readonly traceId?: string;
+  readonly runId?: string;
+  readonly runIds?: ReadonlyArray<string>;
+  readonly workflowId?: string;
+  readonly workflowIds?: ReadonlyArray<string>;
+  readonly statuses?: ReadonlyArray<TelemetrySpanStatus>;
+  readonly names?: ReadonlyArray<string>;
+  readonly modelNames?: ReadonlyArray<string>;
+  readonly startTimeGte?: string;
+  readonly endTimeLte?: string;
+  readonly limit?: number;
+}
+
+export interface TelemetryMetricPointListQuery {
+  readonly traceId?: string;
+  readonly runId?: string;
+  readonly runIds?: ReadonlyArray<string>;
+  readonly workflowId?: string;
+  readonly workflowIds?: ReadonlyArray<string>;
+  readonly nodeId?: string;
+  readonly metricNames?: ReadonlyArray<string>;
+  readonly modelNames?: ReadonlyArray<string>;
+  readonly observedAtGte?: string;
+  readonly observedAtLte?: string;
+  readonly limit?: number;
+}
+
+export interface TelemetryPruneArgs {
+  readonly nowIso: string;
+  readonly limit?: number;
+}
+
+export interface RunTraceContextRepository {
+  load(runId: string): Promise<TelemetryTraceContext | undefined>;
+  getOrCreate(
+    args: Readonly<{ runId: string; workflowId: string; serviceName?: string }>,
+  ): Promise<TelemetryTraceContext>;
+  upsertExpiry(args: Readonly<{ runId: string; expiresAt?: string }>): Promise<void>;
+}
+
+export interface TelemetrySpanStore {
+  upsert(record: TelemetrySpanUpsert): Promise<void>;
+  list(args?: TelemetrySpanListQuery): Promise<ReadonlyArray<TelemetrySpanRecord>>;
+  listByTraceId(traceId: string): Promise<ReadonlyArray<TelemetrySpanRecord>>;
+  pruneExpired(args: TelemetryPruneArgs): Promise<number>;
+}
+
+export interface TelemetryArtifactStore {
+  save(record: TelemetryArtifactWrite): Promise<TelemetryArtifactRecord>;
+  listByTraceId(traceId: string): Promise<ReadonlyArray<TelemetryArtifactRecord>>;
+  pruneExpired(args: TelemetryPruneArgs): Promise<number>;
+}
+
+export interface TelemetryMetricPointStore {
+  save(record: TelemetryMetricPointWrite): Promise<TelemetryMetricPointRecord>;
+  list(args?: TelemetryMetricPointListQuery): Promise<ReadonlyArray<TelemetryMetricPointRecord>>;
+  pruneExpired(args: TelemetryPruneArgs): Promise<number>;
+}
+
+export interface TelemetryExporter {
+  exportSpans(spans: ReadonlyArray<TelemetrySpanRecord>): Promise<void>;
+}

package/src/infrastructure/config/CodemationPluginRegistrar.ts

@@ -27,17 +27,13 @@ export class CodemationPluginRegistrar {
         loggerFactory: args.loggerFactory,
         registerCredentialType: (type) => args.registerCredentialType(type),
         registerNode: (token, implementation) => {
-          args.container.register(token, {
-            useClass: (implementation ?? token) as never,
-          });
+          args.container.registerSingleton(token as never, (implementation ?? token) as never);
         },
         registerValue: (token, value) => {
           args.container.registerInstance(token, value);
         },
         registerClass: (token, implementation) => {
-          args.container.register(token, {
-            useClass: implementation as never,
-          });
+          args.container.registerSingleton(token as never, implementation as never);
         },
         registerFactory: (token, factory) => {
           args.container.register(token, {

package/src/infrastructure/di/HandlesDomainEventRegistry.ts

@@ -1,4 +1,4 @@
-import { injectable, registry } from "@codemation/core";
+import { container as tsyringeContainer, injectable } from "@codemation/core";
 import type { DomainEvent } from "../../application/bus/DomainEvent";
 import type { DomainEventHandler } from "../../application/bus/DomainEventHandler";
 import { ApplicationTokens } from "../../applicationTokens";
@@ -13,12 +13,10 @@ export class HandlesDomainEvent {
     return (target) => {
       Reflect.defineMetadata(domainEventHandlerMetadataKey, eventType, target);
       injectable()(target as never);
-      registry([
-        {
-          token: ApplicationTokens.DomainEventHandler,
-          useClass: target as unknown as ConcreteType<DomainEventHandler<DomainEvent>>,
-        },
-      ])(target as never);
+      tsyringeContainer.registerSingleton(
+        ApplicationTokens.DomainEventHandler as never,
+        target as unknown as ConcreteType<DomainEventHandler<DomainEvent>>,
+      );
     };
   }
 }

package/src/infrastructure/persistence/InMemoryRunTraceContextRepository.ts

@@ -0,0 +1,56 @@
+import { inject, injectable } from "@codemation/core";
+import { OtelIdentityFactory } from "../../application/telemetry/OtelIdentityFactory";
+import type { RunTraceContextRepository, TelemetryTraceContext } from "../../domain/telemetry/TelemetryContracts";
+
+@injectable()
+export class InMemoryRunTraceContextRepository implements RunTraceContextRepository {
+  private readonly rows = new Map<string, TelemetryTraceContext>();
+
+  constructor(@inject(OtelIdentityFactory) private readonly otelIdentityFactory: OtelIdentityFactory) {}
+
+  async load(runId: string): Promise<TelemetryTraceContext | undefined> {
+    return this.rows.get(decodeURIComponent(runId));
+  }
+
+  async getOrCreate(
+    args: Readonly<{ runId: string; workflowId: string; serviceName?: string }>,
+  ): Promise<TelemetryTraceContext> {
+    const key = decodeURIComponent(args.runId);
+    const existing = this.rows.get(key);
+    if (existing) {
+      return existing;
+    }
+    const created: TelemetryTraceContext = {
+      runId: key,
+      workflowId: decodeURIComponent(args.workflowId),
+      traceId: this.otelIdentityFactory.createTraceId(key),
+      rootSpanId: this.otelIdentityFactory.createRootSpanId(key),
+      serviceName: args.serviceName,
+      createdAt: new Date().toISOString(),
+    };
+    this.rows.set(key, created);
+    return created;
+  }
+
+  async upsertExpiry(args: Readonly<{ runId: string; expiresAt?: string }>): Promise<void> {
+    const key = decodeURIComponent(args.runId);
+    const existing = this.rows.get(key);
+    if (!existing) {
+      return;
+    }
+    this.rows.set(key, {
+      ...existing,
+      expiresAt: this.resolveLaterExpiry(existing.expiresAt, args.expiresAt),
+    });
+  }
+
+  private resolveLaterExpiry(current: string | undefined, candidate: string | undefined): string | undefined {
+    if (!current) {
+      return candidate;
+    }
+    if (!candidate) {
+      return current;
+    }
+    return current >= candidate ? current : candidate;
+  }
+}

package/src/infrastructure/persistence/InMemoryTelemetryArtifactStore.ts

@@ -0,0 +1,56 @@
+import { inject, injectable } from "@codemation/core";
+import { OtelIdentityFactory } from "../../application/telemetry/OtelIdentityFactory";
+import type {
+  TelemetryArtifactRecord,
+  TelemetryArtifactStore,
+  TelemetryArtifactWrite,
+} from "../../domain/telemetry/TelemetryContracts";
+
+@injectable()
+export class InMemoryTelemetryArtifactStore implements TelemetryArtifactStore {
+  private readonly rows = new Map<string, TelemetryArtifactRecord>();
+
+  constructor(@inject(OtelIdentityFactory) private readonly otelIdentityFactory: OtelIdentityFactory) {}
+
+  async save(record: TelemetryArtifactWrite): Promise<TelemetryArtifactRecord> {
+    const created: TelemetryArtifactRecord = {
+      artifactId: this.otelIdentityFactory.createArtifactId(),
+      traceId: record.traceId,
+      spanId: record.spanId,
+      runId: record.runId,
+      workflowId: record.workflowId,
+      nodeId: record.nodeId,
+      activationId: record.activationId,
+      kind: record.kind,
+      contentType: record.contentType,
+      previewText: record.previewText,
+      previewJson: record.previewJson,
+      payloadText: record.payloadText,
+      payloadJson: record.payloadJson,
+      bytes: record.bytes,
+      truncated: record.truncated,
+      createdAt: new Date().toISOString(),
+      expiresAt: record.expiresAt?.toISOString(),
+      retentionExpiresAt: record.retentionExpiresAt,
+    };
+    this.rows.set(created.artifactId, created);
+    return created;
+  }
+
+  async listByTraceId(traceId: string): Promise<ReadonlyArray<TelemetryArtifactRecord>> {
+    return [...this.rows.values()]
+      .filter((row) => row.traceId === traceId)
+      .sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+  }
+
+  async pruneExpired(args: Readonly<{ nowIso: string; limit?: number }>): Promise<number> {
+    const candidates = [...this.rows.entries()]
+      .filter(([, row]) => row.retentionExpiresAt !== undefined && row.retentionExpiresAt <= args.nowIso)
+      .sort((left, right) => (left[1].retentionExpiresAt ?? "").localeCompare(right[1].retentionExpiresAt ?? ""))
+      .slice(0, args.limit ?? Number.MAX_SAFE_INTEGER);
+    for (const [key] of candidates) {
+      this.rows.delete(key);
+    }
+    return candidates.length;
+  }
+}

package/src/infrastructure/persistence/InMemoryTelemetryMetricPointStore.ts

@@ -0,0 +1,97 @@
+import { inject, injectable } from "@codemation/core";
+import { OtelIdentityFactory } from "../../application/telemetry/OtelIdentityFactory";
+import type {
+  TelemetryMetricPointListQuery,
+  TelemetryMetricPointRecord,
+  TelemetryMetricPointStore,
+  TelemetryMetricPointWrite,
+} from "../../domain/telemetry/TelemetryContracts";
+
+@injectable()
+export class InMemoryTelemetryMetricPointStore implements TelemetryMetricPointStore {
+  private readonly rows = new Map<string, TelemetryMetricPointRecord>();
+
+  constructor(@inject(OtelIdentityFactory) private readonly otelIdentityFactory: OtelIdentityFactory) {}
+
+  async save(record: TelemetryMetricPointWrite): Promise<TelemetryMetricPointRecord> {
+    const created: TelemetryMetricPointRecord = {
+      metricPointId: this.otelIdentityFactory.createArtifactId(),
+      traceId: record.traceId,
+      spanId: record.spanId,
+      runId: record.runId,
+      workflowId: record.workflowId,
+      nodeId: record.nodeId,
+      activationId: record.activationId,
+      metricName: record.name,
+      value: record.value,
+      unit: record.unit,
+      observedAt: record.observedAt,
+      workflowFolder: record.workflowFolder,
+      nodeType: record.nodeType,
+      nodeRole: record.nodeRole,
+      modelName: record.modelName,
+      dimensions: record.attributes,
+      retentionExpiresAt: record.retentionExpiresAt,
+    };
+    this.rows.set(created.metricPointId, created);
+    return created;
+  }
+
+  async list(args: TelemetryMetricPointListQuery = {}): Promise<ReadonlyArray<TelemetryMetricPointRecord>> {
+    return [...this.rows.values()]
+      .filter((row) => this.matches(row, args))
+      .sort((left, right) => {
+        const observedCompare = left.observedAt.localeCompare(right.observedAt);
+        if (observedCompare !== 0) {
+          return observedCompare;
+        }
+        return left.metricPointId.localeCompare(right.metricPointId);
+      })
+      .slice(0, args.limit ?? Number.MAX_SAFE_INTEGER);
+  }
+
+  async pruneExpired(args: Readonly<{ nowIso: string; limit?: number }>): Promise<number> {
+    const candidates = [...this.rows.entries()]
+      .filter(([, row]) => row.retentionExpiresAt !== undefined && row.retentionExpiresAt <= args.nowIso)
+      .sort((left, right) => (left[1].retentionExpiresAt ?? "").localeCompare(right[1].retentionExpiresAt ?? ""))
+      .slice(0, args.limit ?? Number.MAX_SAFE_INTEGER);
+    for (const [key] of candidates) {
+      this.rows.delete(key);
+    }
+    return candidates.length;
+  }
+
+  private matches(row: TelemetryMetricPointRecord, args: TelemetryMetricPointListQuery): boolean {
+    if (args.traceId && row.traceId !== args.traceId) {
+      return false;
+    }
+    if (args.runId && row.runId !== args.runId) {
+      return false;
+    }
+    if (args.runIds && args.runIds.length > 0 && (!row.runId || !args.runIds.includes(row.runId))) {
+      return false;
+    }
+    if (args.workflowId && row.workflowId !== args.workflowId) {
+      return false;
+    }
+    if (args.workflowIds && args.workflowIds.length > 0 && !args.workflowIds.includes(row.workflowId)) {
+      return false;
+    }
+    if (args.nodeId && row.nodeId !== args.nodeId) {
+      return false;
+    }
+    if (args.metricNames && args.metricNames.length > 0 && !args.metricNames.includes(row.metricName)) {
+      return false;
+    }
+    if (args.modelNames && args.modelNames.length > 0 && (!row.modelName || !args.modelNames.includes(row.modelName))) {
+      return false;
+    }
+    if (args.observedAtGte && row.observedAt < args.observedAtGte) {
+      return false;
+    }
+    if (args.observedAtLte && row.observedAt > args.observedAtLte) {
+      return false;
+    }
+    return true;
+  }
+}

package/src/infrastructure/persistence/InMemoryTelemetrySpanStore.ts

@@ -0,0 +1,113 @@
+import { injectable } from "@codemation/core";
+import type {
+  TelemetrySpanListQuery,
+  TelemetrySpanRecord,
+  TelemetrySpanStore,
+  TelemetrySpanUpsert,
+} from "../../domain/telemetry/TelemetryContracts";
+
+@injectable()
+export class InMemoryTelemetrySpanStore implements TelemetrySpanStore {
+  private readonly rows = new Map<string, TelemetrySpanRecord>();
+
+  async upsert(record: TelemetrySpanUpsert): Promise<void> {
+    const key = this.createKey(record.traceId, record.spanId);
+    const existing = this.rows.get(key);
+    this.rows.set(key, this.merge(existing, record));
+  }
+
+  async list(args: TelemetrySpanListQuery = {}): Promise<ReadonlyArray<TelemetrySpanRecord>> {
+    return [...this.rows.values()]
+      .filter((row) => this.matches(row, args))
+      .sort((left, right) => {
+        const startCompare = (left.startTime ?? "").localeCompare(right.startTime ?? "");
+        if (startCompare !== 0) {
+          return startCompare;
+        }
+        return left.spanId.localeCompare(right.spanId);
+      })
+      .slice(0, args.limit ?? Number.MAX_SAFE_INTEGER);
+  }
+
+  async listByTraceId(traceId: string): Promise<ReadonlyArray<TelemetrySpanRecord>> {
+    return await this.list({ traceId });
+  }
+
+  private createKey(traceId: string, spanId: string): string {
+    return `${traceId}:${spanId}`;
+  }
+
+  private merge(existing: TelemetrySpanRecord | undefined, update: TelemetrySpanUpsert): TelemetrySpanRecord {
+    return {
+      traceId: update.traceId,
+      spanId: update.spanId,
+      parentSpanId: update.parentSpanId ?? existing?.parentSpanId,
+      runId: update.runId,
+      workflowId: update.workflowId,
+      nodeId: update.nodeId ?? existing?.nodeId,
+      activationId: update.activationId ?? existing?.activationId,
+      connectionInvocationId: update.connectionInvocationId ?? existing?.connectionInvocationId,
+      name: update.name ?? existing?.name ?? "codemation.span",
+      kind: update.kind ?? existing?.kind ?? "internal",
+      status: update.status ?? existing?.status,
+      statusMessage: update.statusMessage ?? existing?.statusMessage,
+      startTime: update.startTime ?? existing?.startTime,
+      endTime: update.endTime ?? existing?.endTime,
+      workflowFolder: update.workflowFolder ?? existing?.workflowFolder,
+      nodeType: update.nodeType ?? existing?.nodeType,
+      nodeRole: update.nodeRole ?? existing?.nodeRole,
+      modelName: update.modelName ?? existing?.modelName,
+      attributes: {
+        ...(existing?.attributes ?? {}),
+        ...(update.attributes ?? {}),
+      },
+      events: [...(existing?.events ?? []), ...(update.events ?? [])],
+      retentionExpiresAt: update.retentionExpiresAt ?? existing?.retentionExpiresAt,
+    };
+  }
+
+  private matches(row: TelemetrySpanRecord, args: TelemetrySpanListQuery): boolean {
+    if (args.traceId && row.traceId !== args.traceId) {
+      return false;
+    }
+    if (args.runId && row.runId !== args.runId) {
+      return false;
+    }
+    if (args.runIds && args.runIds.length > 0 && !args.runIds.includes(row.runId)) {
+      return false;
+    }
+    if (args.workflowId && row.workflowId !== args.workflowId) {
+      return false;
+    }
+    if (args.workflowIds && args.workflowIds.length > 0 && !args.workflowIds.includes(row.workflowId)) {
+      return false;
+    }
+    if (args.statuses && args.statuses.length > 0 && (!row.status || !args.statuses.includes(row.status))) {
+      return false;
+    }
+    if (args.names && args.names.length > 0 && !args.names.includes(row.name)) {
+      return false;
+    }
+    if (args.modelNames && args.modelNames.length > 0 && (!row.modelName || !args.modelNames.includes(row.modelName))) {
+      return false;
+    }
+    if (args.startTimeGte && row.startTime && row.startTime < args.startTimeGte) {
+      return false;
+    }
+    if (args.endTimeLte && row.endTime && row.endTime > args.endTimeLte) {
+      return false;
+    }
+    return true;
+  }
+
+  async pruneExpired(args: Readonly<{ nowIso: string; limit?: number }>): Promise<number> {
+    const candidates = [...this.rows.entries()]
+      .filter(([, row]) => row.retentionExpiresAt !== undefined && row.retentionExpiresAt <= args.nowIso)
+      .sort((left, right) => (left[1].retentionExpiresAt ?? "").localeCompare(right[1].retentionExpiresAt ?? ""))
+      .slice(0, args.limit ?? Number.MAX_SAFE_INTEGER);
+    for (const [key] of candidates) {
+      this.rows.delete(key);
+    }
+    return candidates.length;
+  }
+}

package/src/infrastructure/persistence/InMemoryWorkflowRunRepository.ts

@@ -160,14 +160,16 @@ export class InMemoryWorkflowRunRepository implements WorkflowRunRepository, Wor
   }
 
   async listRunsOlderThan(
-    args: Readonly<{ beforeIso: string; limit?: number }>,
+    args: Readonly<{ nowIso: string; defaultRetentionSeconds: number; limit?: number }>,
   ): Promise<ReadonlyArray<RunPruneCandidate>> {
     const limit = args.limit ?? 100;
     const out: RunPruneCandidate[] = [];
     for (const s of this.runs.values()) {
       if (s.status !== "completed" && s.status !== "failed") continue;
       const finishedAt = RunFinishedAtFactory.resolveIso(s);
-      if (!finishedAt || finishedAt >= args.beforeIso) continue;
+      const retentionSeconds = s.policySnapshot?.retentionSeconds ?? args.defaultRetentionSeconds;
+      const cutoffIso = new Date(new Date(args.nowIso).getTime() - retentionSeconds * 1000).toISOString();
+      if (!finishedAt || finishedAt >= cutoffIso) continue;
       out.push({
         runId: s.runId,
         workflowId: s.workflowId,

package/src/infrastructure/persistence/PrismaRunTraceContextRepository.ts

@@ -0,0 +1,92 @@
+import { inject, injectable } from "@codemation/core";
+import { OtelIdentityFactory } from "../../application/telemetry/OtelIdentityFactory";
+import type { RunTraceContextRepository, TelemetryTraceContext } from "../../domain/telemetry/TelemetryContracts";
+import { PrismaDatabaseClientToken, type PrismaDatabaseClient } from "./PrismaDatabaseClient";
+
+@injectable()
+export class PrismaRunTraceContextRepository implements RunTraceContextRepository {
+  constructor(
+    @inject(PrismaDatabaseClientToken)
+    private readonly prisma: PrismaDatabaseClient,
+    @inject(OtelIdentityFactory)
+    private readonly otelIdentityFactory: OtelIdentityFactory,
+  ) {}
+
+  async load(runId: string): Promise<TelemetryTraceContext | undefined> {
+    const row = await this.prisma.runTraceContext.findUnique({
+      where: { runId: decodeURIComponent(runId) },
+    });
+    if (!row) {
+      return undefined;
+    }
+    return {
+      runId: row.runId,
+      workflowId: row.workflowId,
+      traceId: row.traceId,
+      rootSpanId: row.rootSpanId,
+      serviceName: row.serviceName ?? undefined,
+      createdAt: row.createdAt,
+      expiresAt: row.expiresAt ?? undefined,
+    };
+  }
+
+  async getOrCreate(
+    args: Readonly<{ runId: string; workflowId: string; serviceName?: string }>,
+  ): Promise<TelemetryTraceContext> {
+    const existing = await this.load(args.runId);
+    if (existing) {
+      return existing;
+    }
+    const created: TelemetryTraceContext = {
+      runId: decodeURIComponent(args.runId),
+      workflowId: decodeURIComponent(args.workflowId),
+      traceId: this.otelIdentityFactory.createTraceId(args.runId),
+      rootSpanId: this.otelIdentityFactory.createRootSpanId(args.runId),
+      serviceName: args.serviceName,
+      createdAt: new Date().toISOString(),
+    };
+    await this.prisma.runTraceContext.create({
+      data: {
+        runId: created.runId,
+        workflowId: created.workflowId,
+        traceId: created.traceId,
+        rootSpanId: created.rootSpanId,
+        serviceName: created.serviceName ?? null,
+        createdAt: created.createdAt,
+        expiresAt: null,
+      },
+    });
+    return created;
+  }
+
+  async upsertExpiry(args: Readonly<{ runId: string; expiresAt?: string }>): Promise<void> {
+    if (!args.expiresAt) {
+      return;
+    }
+    const runId = decodeURIComponent(args.runId);
+    const existing = await this.prisma.runTraceContext.findUnique({
+      where: { runId },
+      select: { expiresAt: true },
+    });
+    if (!existing) {
+      return;
+    }
+    const expiresAt = this.resolveLaterExpiry(existing.expiresAt ?? undefined, args.expiresAt);
+    await this.prisma.runTraceContext.update({
+      where: { runId },
+      data: {
+        expiresAt: expiresAt ?? null,
+      },
+    });
+  }
+
+  private resolveLaterExpiry(current: string | undefined, candidate: string | undefined): string | undefined {
+    if (!current) {
+      return candidate;
+    }
+    if (!candidate) {
+      return current;
+    }
+    return current >= candidate ? current : candidate;
+  }
+}