@codemation/host 0.6.0 → 0.7.0

package/src/domain/workflows/WorkflowActivationPreflight.ts

@@ -1,6 +1,9 @@
 import { ApplicationRequestError } from "../../application/ApplicationRequestError";
-import { CoreTokens, inject, injectable, type WorkflowRepository } from "@codemation/core";
+import { ApplicationTokens } from "../../applicationTokens";
+import { CoreTokens, inject, injectable, type CredentialTypeRegistry, type WorkflowRepository } from "@codemation/core";
 import { CredentialBindingService } from "../credentials/CredentialServices";
+import { CredentialOAuth2ScopeResolver } from "../credentials/CredentialOAuth2ScopeResolver";
+import type { CredentialStore } from "../credentials/CredentialServices";
 import { WorkflowActivationPreflightRules } from "./WorkflowActivationPreflightRules";
 
 @injectable()
@@ -12,6 +15,12 @@ export class WorkflowActivationPreflight {
     private readonly credentialBindingService: CredentialBindingService,
     @inject(WorkflowActivationPreflightRules)
     private readonly rules: WorkflowActivationPreflightRules,
+    @inject(CoreTokens.CredentialTypeRegistry)
+    private readonly credentialTypeRegistry: CredentialTypeRegistry,
+    @inject(ApplicationTokens.CredentialStore)
+    private readonly credentialStore: CredentialStore,
+    @inject(CredentialOAuth2ScopeResolver)
+    private readonly credentialOAuth2ScopeResolver: CredentialOAuth2ScopeResolver,
   ) {}
 
   async assertCanActivate(workflowId: string): Promise<void> {
@@ -21,9 +30,23 @@ export class WorkflowActivationPreflight {
       throw new ApplicationRequestError(404, `Unknown workflowId: ${decodedId}`);
     }
     const health = await this.credentialBindingService.listWorkflowHealth(decodedId);
+    const scopeErrors = await this.rules.collectScopeMismatchErrors(health, {
+      getRequiredScopes: (typeId, _requirement) => {
+        const type = this.credentialTypeRegistry.getType(typeId);
+        if (type?.auth?.kind === "oauth2") {
+          return this.credentialOAuth2ScopeResolver.resolveRequestedScopes(type.auth, {});
+        }
+        return [];
+      },
+      getGrantedScopes: async (instanceId) => {
+        const material = await this.credentialStore.getOAuth2Material(instanceId);
+        return material?.scopes ?? [];
+      },
+    });
     const errors = [
       ...this.rules.collectNonManualTriggerErrors(workflow),
       ...this.rules.collectRequiredCredentialErrors(health),
+      ...scopeErrors,
     ];
     if (errors.length > 0) {
       throw new ApplicationRequestError(400, "Workflow cannot be activated.", errors);

package/src/domain/workflows/WorkflowActivationPreflightRules.ts

@@ -1,5 +1,5 @@
 import type { WorkflowCredentialHealthDto } from "../../application/contracts/CredentialContractsRegistry";
-import { getPersistedRuntimeTypeMetadata, injectable, type WorkflowDefinition } from "@codemation/core";
+import { getPersistedRuntimeTypeMetadata, injectable, type CredentialRequirement, type WorkflowDefinition } from "@codemation/core";
 import { MissingRuntimeTriggerToken } from "@codemation/core/bootstrap";
 import { ManualTriggerNode } from "@codemation/core-nodes";
 
@@ -74,4 +74,43 @@ export class WorkflowActivationPreflightRules {
     }
     return lines;
   }
+
+  async collectScopeMismatchErrors(
+    health: WorkflowCredentialHealthDto,
+    opts: {
+      getRequiredScopes: (typeId: string, slotRequirement: CredentialRequirement) => ReadonlyArray<string>;
+      getGrantedScopes: (instanceId: string) => Promise<ReadonlyArray<string>>;
+    },
+  ): Promise<ReadonlyArray<string>> {
+    const checked = new Set<string>();
+    const lines: string[] = [];
+
+    for (const slot of health.slots) {
+      const { instance } = slot;
+      if (!instance) {
+        continue;
+      }
+      const { instanceId, typeId, displayName } = instance;
+      if (checked.has(instanceId)) {
+        continue;
+      }
+      checked.add(instanceId);
+
+      const required = opts.getRequiredScopes(typeId, slot.requirement);
+      if (required.length === 0) {
+        continue;
+      }
+
+      const granted = await opts.getGrantedScopes(instanceId);
+      const grantedSet = new Set(granted);
+      const missing = required.filter((s) => !grantedSet.has(s));
+      if (missing.length > 0) {
+        lines.push(
+          `Credential "${displayName}" missing scopes: ${missing.join(", ")}. Reconnect to grant.`,
+        );
+      }
+    }
+
+    return lines;
+  }
 }

package/src/index.ts

@@ -6,6 +6,8 @@ export { UpsertLocalBootstrapUserCommand } from "./application/commands/UpsertLo
 export type { UpsertLocalBootstrapUserResultDto } from "./application/contracts/userDirectoryContracts.types";
 export { AppContainerFactory } from "./bootstrap/AppContainerFactory";
 export { AppContainerLifecycle } from "./bootstrap/AppContainerLifecycle";
+export { BootTimer } from "./bootstrap/perf/BootTimer";
+export type { BootTracePhase } from "./bootstrap/perf/BootTimer";
 export { DatabaseMigrations } from "./bootstrap/runtime/DatabaseMigrations";
 export { CollectionSchemaSyncerHolder } from "./infrastructure/collections/CollectionSchemaSyncerHolder";
 export { FrontendRuntime } from "./bootstrap/runtime/FrontendRuntime";
@@ -56,6 +58,10 @@ export { InsertCollectionRowCommand } from "./application/collections/InsertColl
 export { UpdateCollectionRowCommand } from "./application/collections/UpdateCollectionRowCommand";
 export { DeleteCollectionRowCommand } from "./application/collections/DeleteCollectionRowCommand";
 export { SyncCollectionsCommand } from "./application/collections/SyncCollectionsCommand";
+export { StartWorkflowRunCommand } from "./application/commands/StartWorkflowRunCommand";
+export type { RunCommandResult } from "./application/contracts/RunContracts";
+export { ApplicationRequestError } from "./application/ApplicationRequestError";
+export { GetRunStateQuery } from "./application/queries/GetRunStateQuery";
 
 export type {
   CodemationFrontendAuthProviderSnapshot,

package/src/infrastructure/binary/LocalFilesystemBinaryStorageRegistry.ts

@@ -1,6 +1,6 @@
 import { createReadStream, createWriteStream } from "node:fs";
 
-import { mkdir, rm, stat } from "node:fs/promises";
+import { mkdir, readdir, rm, stat } from "node:fs/promises";
 
 import path from "node:path";
 
@@ -72,6 +72,34 @@ export class LocalFilesystemBinaryStorage implements BinaryStorage {
     await rm(this.resolveAbsolutePath(storageKey), { force: true });
   }
 
+  async deleteMany(storageKeys: ReadonlyArray<string>): Promise<void> {
+    await Promise.all(storageKeys.map((key) => this.delete(key)));
+  }
+
+  async listByPrefix(prefix: string): Promise<ReadonlyArray<string>> {
+    const results: string[] = [];
+    await this.collectKeysWithPrefix(prefix, this.baseDirectory, results);
+    return results;
+  }
+
+  private async collectKeysWithPrefix(prefix: string, dir: string, results: string[]): Promise<void> {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const entryPath = path.join(dir, entry.name);
+      const relKey = path.relative(path.resolve(this.baseDirectory), entryPath).replace(/\\/g, "/");
+      if (entry.isDirectory()) {
+        await this.collectKeysWithPrefix(prefix, entryPath, results);
+      } else if (relKey.startsWith(prefix)) {
+        results.push(relKey);
+      }
+    }
+  }
+
   private resolveAbsolutePath(storageKey: string): string {
     const absoluteBaseDirectory = path.resolve(this.baseDirectory);
     const targetPath = path.resolve(absoluteBaseDirectory, storageKey);

package/src/infrastructure/binary/S3BinaryStorage.ts

@@ -0,0 +1,169 @@
+import { PassThrough, Readable } from "node:stream";
+
+import {
+  DeleteObjectCommand,
+  DeleteObjectsCommand,
+  HeadBucketCommand,
+  HeadObjectCommand,
+  ListObjectsV2Command,
+  S3Client,
+} from "@aws-sdk/client-s3";
+
+import { Upload } from "@aws-sdk/lib-storage";
+
+import type {
+  BinaryBody,
+  BinaryStorage,
+  BinaryStorageReadResult,
+  BinaryStorageStatResult,
+  BinaryStorageWriteResult,
+} from "@codemation/core";
+
+import { BinaryBodyNodeReadableFactory } from "./BinaryBodyNodeReadableFactory";
+import type { S3BinaryStorageConfig } from "./S3BinaryStorageConfig";
+
+const DELETE_BATCH_SIZE = 1000;
+
+export class S3BinaryStorage implements BinaryStorage {
+  readonly driverName = "s3";
+
+  private readonly client: S3Client;
+  private readonly bucket: string;
+
+  /**
+   * @param config - S3 connection details.
+   * @param forcePathStyle - Use path-style addressing (true for MinIO / testcontainers; false for Scaleway). Default false.
+   */
+  constructor(config: S3BinaryStorageConfig, forcePathStyle = false) {
+    this.bucket = config.bucket;
+    this.client = new S3Client({
+      endpoint: config.endpoint,
+      region: config.region,
+      forcePathStyle,
+      credentials: {
+        accessKeyId: config.accessKeyId,
+        secretAccessKey: config.secretAccessKey,
+      },
+    });
+  }
+
+  async write(args: { storageKey: string; body: BinaryBody }): Promise<BinaryStorageWriteResult> {
+    const readable = new BinaryBodyNodeReadableFactory(args.body).create();
+    let size = 0;
+    const passThrough = new PassThrough();
+    readable.on("data", (chunk: Buffer) => {
+      size += chunk.byteLength;
+    });
+    readable.pipe(passThrough);
+
+    const upload = new Upload({
+      client: this.client,
+      params: {
+        Bucket: this.bucket,
+        Key: args.storageKey,
+        Body: passThrough,
+      },
+    });
+
+    await upload.done();
+
+    return {
+      storageKey: args.storageKey,
+      size,
+    };
+  }
+
+  async openReadStream(storageKey: string): Promise<BinaryStorageReadResult | undefined> {
+    const { GetObjectCommand } = await import("@aws-sdk/client-s3");
+    let response;
+    try {
+      response = await this.client.send(new GetObjectCommand({ Bucket: this.bucket, Key: storageKey }));
+    } catch (err) {
+      if (this.isNotFoundError(err)) {
+        return undefined;
+      }
+      throw err;
+    }
+
+    if (!response.Body) {
+      return undefined;
+    }
+
+    const nodeReadable = Readable.from(response.Body as AsyncIterable<Uint8Array>);
+    return {
+      body: Readable.toWeb(nodeReadable) as BinaryStorageReadResult["body"],
+      size: response.ContentLength,
+    };
+  }
+
+  async stat(storageKey: string): Promise<BinaryStorageStatResult> {
+    try {
+      const response = await this.client.send(new HeadObjectCommand({ Bucket: this.bucket, Key: storageKey }));
+      return { exists: true, size: response.ContentLength };
+    } catch (err) {
+      if (this.isNotFoundError(err)) {
+        return { exists: false };
+      }
+      throw err;
+    }
+  }
+
+  async delete(storageKey: string): Promise<void> {
+    await this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: storageKey }));
+  }
+
+  async deleteMany(storageKeys: ReadonlyArray<string>): Promise<void> {
+    for (let i = 0; i < storageKeys.length; i += DELETE_BATCH_SIZE) {
+      const batch = storageKeys.slice(i, i + DELETE_BATCH_SIZE);
+      await this.client.send(
+        new DeleteObjectsCommand({
+          Bucket: this.bucket,
+          Delete: {
+            Objects: batch.map((key) => ({ Key: key })),
+            Quiet: true,
+          },
+        }),
+      );
+    }
+  }
+
+  async listByPrefix(prefix: string): Promise<ReadonlyArray<string>> {
+    const keys: string[] = [];
+    let continuationToken: string | undefined;
+
+    do {
+      const response = await this.client.send(
+        new ListObjectsV2Command({
+          Bucket: this.bucket,
+          Prefix: prefix,
+          ContinuationToken: continuationToken,
+        }),
+      );
+
+      for (const obj of response.Contents ?? []) {
+        if (obj.Key) {
+          keys.push(obj.Key);
+        }
+      }
+
+      continuationToken = response.NextContinuationToken;
+    } while (continuationToken);
+
+    return keys;
+  }
+
+  /** Checks that the configured bucket is reachable. Throws if not. */
+  async checkConnectivity(): Promise<void> {
+    await this.client.send(new HeadBucketCommand({ Bucket: this.bucket }));
+  }
+
+  private isNotFoundError(err: unknown): boolean {
+    if (typeof err !== "object" || err === null) {
+      return false;
+    }
+    const anyErr = err as Record<string, unknown>;
+    const statusCode =
+      anyErr["$metadata"] != null ? (anyErr["$metadata"] as Record<string, unknown>)["httpStatusCode"] : undefined;
+    return statusCode === 404 || anyErr["name"] === "NotFound" || anyErr["name"] === "NoSuchKey";
+  }
+}

package/src/infrastructure/binary/S3BinaryStorageConfig.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+
+export interface S3BinaryStorageConfig {
+  readonly endpoint: string;
+  readonly region: string;
+  readonly bucket: string;
+  readonly accessKeyId: string;
+  readonly secretAccessKey: string;
+}
+
+export const S3BinaryStorageConfigSchema = z.object({
+  endpoint: z.string().min(1),
+  region: z.string().min(1),
+  bucket: z.string().min(1),
+  accessKeyId: z.string().min(1),
+  secretAccessKey: z.string().min(1),
+});

package/src/infrastructure/config/CodemationPluginRegistrar.ts

@@ -1,4 +1,4 @@
-import type { AnyCredentialType, CollectionDefinition, Container } from "@codemation/core";
+import type { AnyCredentialType, CollectionDefinition, Container, McpServerDeclaration } from "@codemation/core";
 import type { LoggerFactory } from "../../application/logging/Logger";
 import type { AppConfig } from "../../presentation/config/AppConfig";
 import type { CodemationPlugin } from "../../presentation/config/CodemationPlugin";
@@ -11,6 +11,7 @@ export class CodemationPluginRegistrar {
       appConfig: AppConfig;
       registerCredentialType: (type: AnyCredentialType) => void;
       registerCollection: (definition: CollectionDefinition) => void;
+      mergeMcpServers: (declarations: ReadonlyArray<McpServerDeclaration>) => void;
       loggerFactory: LoggerFactory;
     }>,
   ): Promise<void> {
@@ -18,6 +19,7 @@ export class CodemationPluginRegistrar {
       for (const credentialType of plugin.credentialTypes ?? []) {
         args.registerCredentialType(credentialType);
       }
+      args.mergeMcpServers(plugin.mcpServers ?? []);
       if (!plugin.register) {
         continue;
       }

package/src/infrastructure/persistence/CodemationDatabaseUrlParser.ts

@@ -0,0 +1,41 @@
+import path from "node:path";
+import type { AppPersistenceConfig } from "../../presentation/config/AppConfig";
+
+/**
+ * Parses `CODEMATION_DATABASE_URL` into an {@link AppPersistenceConfig}.
+ *
+ * Supported schemes (case-insensitive):
+ *   - `sqlite://relative/path/to/file.db`    → resolved relative to consumerRoot
+ *   - `sqlite:///absolute/path/to/file.db`   → leading slash = POSIX absolute
+ *   - `sqlite://C:/path/file.db`             → Windows-style absolute (path.isAbsolute()
+ *                                              returns true for these)
+ *   - `pgsql://user:pass@host:5432/dbname`   → normalised to postgresql://
+ *   - `postgresql://user:pass@host:5432/db`  → pass-through (Prisma's expected scheme)
+ *   - `postgres://user:pass@host:5432/db`    → pass-through (common alias)
+ *
+ * Throws on any other scheme. Empty / whitespace input is also an error — callers
+ * should default before calling parse().
+ */
+export class CodemationDatabaseUrlParser {
+  parse(url: string, consumerRoot: string): AppPersistenceConfig {
+    const trimmed = url.trim();
+    if (trimmed.length === 0) {
+      throw new Error("CODEMATION_DATABASE_URL is empty.");
+    }
+    if (trimmed.toLowerCase().startsWith("sqlite://")) {
+      const remainder = trimmed.slice("sqlite://".length);
+      const filePath = path.isAbsolute(remainder) ? remainder : path.resolve(consumerRoot, remainder);
+      return { kind: "sqlite", databaseFilePath: filePath };
+    }
+    if (trimmed.toLowerCase().startsWith("pgsql://")) {
+      return { kind: "postgresql", databaseUrl: `postgresql://${trimmed.slice("pgsql://".length)}` };
+    }
+    if (trimmed.toLowerCase().startsWith("postgresql://") || trimmed.toLowerCase().startsWith("postgres://")) {
+      return { kind: "postgresql", databaseUrl: trimmed };
+    }
+    throw new Error(
+      `Unsupported CODEMATION_DATABASE_URL scheme: "${trimmed}". ` +
+        `Use sqlite://, pgsql://, postgresql://, or postgres://.`,
+    );
+  }
+}

package/src/infrastructure/persistence/InMemoryTelemetryArtifactStore.ts

@@ -4,6 +4,7 @@ import type {
   TelemetryArtifactRecord,
   TelemetryArtifactStore,
   TelemetryArtifactWrite,
+  TelemetryPruneArgs,
 } from "../../domain/telemetry/TelemetryContracts";
 
 @injectable()
@@ -43,14 +44,18 @@ export class InMemoryTelemetryArtifactStore implements TelemetryArtifactStore {
       .sort((left, right) => left.createdAt.localeCompare(right.createdAt));
   }
 
-  async pruneExpired(args: Readonly<{ nowIso: string; limit?: number }>): Promise<number> {
+  async pruneExpired(args: TelemetryPruneArgs): Promise<{ count: number; storageKeys: ReadonlyArray<string> }> {
     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) {
+    const storageKeys: string[] = [];
+    for (const [key, row] of candidates) {
+      if (row.payloadStorageKey) {
+        storageKeys.push(row.payloadStorageKey);
+      }
       this.rows.delete(key);
     }
-    return candidates.length;
+    return { count: candidates.length, storageKeys };
   }
 }

package/src/infrastructure/persistence/PrismaMigrationDeployer.ts

@@ -1,4 +1,4 @@
-import { createClient, type Client } from "@libsql/client";
+import type { Client } from "@libsql/client";
 import { injectable } from "@codemation/core";
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
@@ -105,11 +105,12 @@ export class PrismaMigrationDeployer {
       env?: Readonly<NodeJS.ProcessEnv>;
     }>,
   ): Promise<void> {
-    const prismaConfigPath = this.resolveAbsolutePrismaConfigPath();
+    const resolverEnv = { ...process.env, ...(args.env ?? {}) };
+    const prismaConfigPath = this.resolveAbsolutePrismaConfigPath(resolverEnv);
     await new Promise<void>((resolve, reject) => {
       const command = spawn(
         process.execPath,
-        [...[this.resolvePrismaCliPath(), ...args.prismaArgs], "--config", path.basename(prismaConfigPath)],
+        [...[this.resolvePrismaCliPath(resolverEnv), ...args.prismaArgs], "--config", path.basename(prismaConfigPath)],
         {
           cwd: path.dirname(prismaConfigPath),
           env: this.createProcessEnvironment(args.databaseUrl, args.provider, args.env),
@@ -177,6 +178,10 @@ export class PrismaMigrationDeployer {
   }
 
   private async repairPartiallyAppliedNormalizedRuntimeSqliteDatabase(databaseFilePath: string): Promise<boolean> {
+    // Lazy import: @libsql/client pulls in platform-specific native bindings that confuse the
+    // Next.js / Turbopack module tracer (forcing the whole project to be traced via NFT). This
+    // recovery path is rarely needed, so defer the load until it's actually invoked.
+    const { createClient } = await import("@libsql/client");
     const client = createClient({ url: this.sqliteFilePathToDatabaseUrl(databaseFilePath) });
     try {
       const failedMigration = await this.hasActiveFailedMigrationRecord(
@@ -288,6 +293,7 @@ export class PrismaMigrationDeployer {
   }
 
   private async cleanupNormalizedRuntimeLegacyArtifacts(databaseFilePath: string): Promise<void> {
+    const { createClient } = await import("@libsql/client");
     const client = createClient({ url: this.sqliteFilePathToDatabaseUrl(databaseFilePath) });
     try {
       const runColumns = await this.readSqliteTableColumns(client, "Run");
@@ -326,14 +332,15 @@ export class PrismaMigrationDeployer {
     };
   }
 
-  private resolvePrismaCliPath(): string {
-    const configuredPath = process.env.CODEMATION_PRISMA_CLI_PATH;
+  private resolvePrismaCliPath(env: Readonly<NodeJS.ProcessEnv>): string {
+    const configuredPath = env.CODEMATION_PRISMA_CLI_PATH;
     if (configuredPath && existsSync(configuredPath)) {
       return configuredPath;
     }
+    const packageRoot = this.resolvePackageRoot(env);
     const packageManagerCandidates = [
       path.resolve(process.cwd(), "node_modules", "prisma", "build", "index.js"),
-      path.resolve(this.resolvePackageRoot(), "node_modules", "prisma", "build", "index.js"),
+      path.resolve(packageRoot, "node_modules", "prisma", "build", "index.js"),
     ];
     for (const candidate of packageManagerCandidates) {
       if (existsSync(candidate)) {
@@ -342,7 +349,7 @@ export class PrismaMigrationDeployer {
     }
     try {
       return this.require.resolve("prisma/build/index.js", {
-        paths: [process.cwd(), this.resolvePackageRoot()],
+        paths: [process.cwd(), packageRoot],
       });
     } catch {
       throw new Error(
@@ -351,16 +358,17 @@ export class PrismaMigrationDeployer {
     }
   }
 
-  private resolveAbsolutePrismaConfigPath(): string {
-    const configuredPath = process.env.CODEMATION_PRISMA_CONFIG_PATH;
+  private resolveAbsolutePrismaConfigPath(env: Readonly<NodeJS.ProcessEnv>): string {
+    const configuredPath = env.CODEMATION_PRISMA_CONFIG_PATH;
+    const packageRoot = this.resolvePackageRoot(env);
     if (configuredPath) {
-      return path.isAbsolute(configuredPath) ? configuredPath : path.resolve(this.resolvePackageRoot(), configuredPath);
+      return path.isAbsolute(configuredPath) ? configuredPath : path.resolve(packageRoot, configuredPath);
     }
-    return path.resolve(this.resolvePackageRoot(), "prisma.config.ts");
+    return path.resolve(packageRoot, "prisma.config.ts");
   }
 
-  resolvePackageRoot(): string {
-    const configuredRoot = process.env.CODEMATION_HOST_PACKAGE_ROOT;
+  resolvePackageRoot(env: Readonly<NodeJS.ProcessEnv> = process.env): string {
+    const configuredRoot = env.CODEMATION_HOST_PACKAGE_ROOT;
     if (configuredRoot) {
       return configuredRoot;
     }

package/src/infrastructure/persistence/PrismaTelemetryArtifactStore.ts

@@ -1,12 +1,17 @@
-import { inject, injectable } from "@codemation/core";
+import type { BinaryBody, BinaryStorage } from "@codemation/core";
+import { CoreTokens, inject, injectable } from "@codemation/core";
 import { OtelIdentityFactory } from "../../application/telemetry/OtelIdentityFactory";
 import type {
   TelemetryArtifactRecord,
   TelemetryArtifactStore,
   TelemetryArtifactWrite,
+  TelemetryPruneArgs,
 } from "../../domain/telemetry/TelemetryContracts";
 import { PrismaDatabaseClientToken, type PrismaDatabaseClient } from "./PrismaDatabaseClient";
 
+/** Payloads larger than this byte threshold are offloaded to BinaryStorage. */
+const PAYLOAD_OFFLOAD_THRESHOLD_BYTES = 64_000;
+
 @injectable()
 export class PrismaTelemetryArtifactStore implements TelemetryArtifactStore {
   constructor(
@@ -14,11 +19,36 @@ export class PrismaTelemetryArtifactStore implements TelemetryArtifactStore {
     private readonly prisma: PrismaDatabaseClient,
     @inject(OtelIdentityFactory)
     private readonly otelIdentityFactory: OtelIdentityFactory,
+    @inject(CoreTokens.BinaryStorage)
+    private readonly binaryStorage: BinaryStorage,
   ) {}
 
   async save(record: TelemetryArtifactWrite): Promise<TelemetryArtifactRecord> {
     const artifactId = this.otelIdentityFactory.createArtifactId();
     const createdAt = new Date().toISOString();
+
+    // Resolve inline vs offloaded payload
+    let payloadText: string | null = record.payloadText ?? null;
+    let payloadJson: string | null = record.payloadJson !== undefined ? JSON.stringify(record.payloadJson) : null;
+    let payloadStorageKey: string | null = null;
+
+    const payloadTextBytes = payloadText ? Buffer.byteLength(payloadText, "utf8") : 0;
+    const payloadJsonBytes = payloadJson ? Buffer.byteLength(payloadJson, "utf8") : 0;
+
+    if (payloadTextBytes > PAYLOAD_OFFLOAD_THRESHOLD_BYTES) {
+      const storageKey = `telemetry-artifacts/${artifactId}.txt`;
+      const body: BinaryBody = Buffer.from(payloadText!, "utf8");
+      await this.binaryStorage.write({ storageKey, body });
+      payloadStorageKey = storageKey;
+      payloadText = null;
+    } else if (payloadJsonBytes > PAYLOAD_OFFLOAD_THRESHOLD_BYTES) {
+      const storageKey = `telemetry-artifacts/${artifactId}.json`;
+      const body: BinaryBody = Buffer.from(payloadJson!, "utf8");
+      await this.binaryStorage.write({ storageKey, body });
+      payloadStorageKey = storageKey;
+      payloadJson = null;
+    }
+
     await this.prisma.telemetryArtifact.create({
       data: {
         artifactId,
@@ -32,8 +62,9 @@ export class PrismaTelemetryArtifactStore implements TelemetryArtifactStore {
         contentType: record.contentType,
         previewText: record.previewText ?? null,
         previewJson: record.previewJson !== undefined ? JSON.stringify(record.previewJson) : null,
-        payloadText: record.payloadText ?? null,
-        payloadJson: record.payloadJson !== undefined ? JSON.stringify(record.payloadJson) : null,
+        payloadText,
+        payloadJson,
+        payloadStorageKey,
         bytes: record.bytes ?? null,
         truncated: record.truncated ?? null,
         createdAt,
@@ -53,8 +84,9 @@ export class PrismaTelemetryArtifactStore implements TelemetryArtifactStore {
       contentType: record.contentType,
       previewText: record.previewText,
       previewJson: record.previewJson,
-      payloadText: record.payloadText,
-      payloadJson: record.payloadJson,
+      payloadText: payloadText ?? undefined,
+      payloadJson: payloadJson !== null ? JSON.parse(payloadJson) : undefined,
+      payloadStorageKey: payloadStorageKey ?? undefined,
       bytes: record.bytes,
       truncated: record.truncated,
       createdAt,
@@ -82,6 +114,7 @@ export class PrismaTelemetryArtifactStore implements TelemetryArtifactStore {
       previewJson: this.parseJson(row.previewJson),
       payloadText: row.payloadText ?? undefined,
       payloadJson: this.parseJson(row.payloadJson),
+      payloadStorageKey: row.payloadStorageKey ?? undefined,
       bytes: row.bytes ?? undefined,
       truncated: row.truncated ?? undefined,
       createdAt: row.createdAt,
@@ -90,7 +123,7 @@ export class PrismaTelemetryArtifactStore implements TelemetryArtifactStore {
     }));
   }
 
-  async pruneExpired(args: Readonly<{ nowIso: string; limit?: number }>): Promise<number> {
+  async pruneExpired(args: TelemetryPruneArgs): Promise<{ count: number; storageKeys: ReadonlyArray<string> }> {
     const rows = await this.prisma.telemetryArtifact.findMany({
       where: {
         retentionExpiresAt: {
@@ -99,13 +132,15 @@ export class PrismaTelemetryArtifactStore implements TelemetryArtifactStore {
       },
       select: {
         artifactId: true,
+        payloadStorageKey: true,
       },
       orderBy: [{ retentionExpiresAt: "asc" }, { artifactId: "asc" }],
       ...(args.limit ? { take: args.limit } : {}),
     });
     if (rows.length === 0) {
-      return 0;
+      return { count: 0, storageKeys: [] };
     }
+    const storageKeys = rows.flatMap((row) => (row.payloadStorageKey ? [row.payloadStorageKey] : []));
     const result = await this.prisma.telemetryArtifact.deleteMany({
       where: {
         artifactId: {
@@ -113,7 +148,7 @@ export class PrismaTelemetryArtifactStore implements TelemetryArtifactStore {
         },
       },
     });
-    return result.count;
+    return { count: result.count, storageKeys };
   }
 
   private parseJson(value: string | null): unknown {