create-windy 0.5.2 → 0.6.1

package/template/apps/server/src/ai-output-artifact/cleanup.ts

@@ -0,0 +1,214 @@
+import type { StorageRuntime } from "../storage/runtime.js";
+import type {
+  AiOutputArtifactRecord,
+  AiOutputArtifactScope,
+} from "./contracts.js";
+import type { AiOutputArtifactRepository } from "./repository.js";
+import type { AiOutputArtifactService } from "./service.js";
+import type { AiOutputArtifactStorageWriterFactory } from "./storage-writer.js";
+import { purgeCompletedOutputUpload } from "./storage-recovery.js";
+
+export class AiOutputArtifactCleanupService {
+  readonly #now: () => Date;
+
+  constructor(
+    private readonly repository: AiOutputArtifactRepository,
+    private readonly storage: StorageRuntime,
+    private readonly writers: AiOutputArtifactStorageWriterFactory,
+    now: () => Date = () => new Date(),
+  ) {
+    this.#now = now;
+  }
+
+  async abortAuthorized(
+    service: AiOutputArtifactService,
+    scopeId: string,
+    grant: string,
+    signal: AbortSignal = new AbortController().signal,
+  ) {
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      signal.throwIfAborted();
+      const scope = await service.requireRevocable(scopeId, grant);
+      if (scope.status === "aborted") return true;
+      if (
+        await this.abortScope(scopeId, "aborted", true, scope.revision, signal)
+      ) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  async abortOpenAuthorized(
+    service: AiOutputArtifactService,
+    scopeId: string,
+    grant: string,
+    signal: AbortSignal = new AbortController().signal,
+  ) {
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      signal.throwIfAborted();
+      const scope = await service.requireRevocable(scopeId, grant);
+      if (["sealed", "aborted", "cleaned"].includes(scope.status)) return true;
+      if (
+        await this.abortScope(scopeId, "aborted", false, scope.revision, signal)
+      ) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  async abortRun(runId: string) {
+    const scopes = await this.repository.listScopesByRun(runId);
+    if (!scopes.length) return false;
+    const results: boolean[] = [];
+    for (const scope of scopes) {
+      results.push(await this.abortScope(scope.scopeId, "aborted"));
+    }
+    return results.every(Boolean);
+  }
+
+  /**
+   * 远端结果未知时只撤销仍可写的 scope。并发 seal 代表 Runtime 已完成提交，
+   * 必须保留，由调用方返回不确定状态而不是删除成功产物。
+   */
+  async abortOpenRun(runId: string) {
+    const scopes = await this.repository.listScopesByRun(runId);
+    if (!scopes.length) return false;
+    const results: boolean[] = [];
+    for (const scope of scopes) {
+      if (["sealed", "aborted", "cleaned"].includes(scope.status)) {
+        results.push(true);
+        continue;
+      }
+      const aborted = await this.abortScope(scope.scopeId, "aborted", false);
+      if (aborted) {
+        results.push(true);
+        continue;
+      }
+      const current = await this.repository.getScope(scope.scopeId);
+      results.push(
+        Boolean(
+          current && ["sealed", "aborted", "cleaned"].includes(current.status),
+        ),
+      );
+    }
+    return results.every(Boolean);
+  }
+
+  async cleanupExpired(limit = 100) {
+    await this.repository.clearExpiredGrantHashes(
+      this.#now().toISOString(),
+      limit,
+    );
+    const scopes = await this.repository.listCleanupScopes(
+      this.#now().toISOString(),
+      limit,
+    );
+    let cleaned = 0;
+    let pending = 0;
+    for (const scope of scopes) {
+      if (await this.abortScope(scope.scopeId, "cleaned")) cleaned += 1;
+      else pending += 1;
+    }
+    return { inspected: scopes.length, cleaned, pending };
+  }
+
+  private async abortScope(
+    scopeId: string,
+    terminal: "aborted" | "cleaned",
+    includeSealed = true,
+    expectedRevision?: number,
+    signal: AbortSignal = new AbortController().signal,
+  ): Promise<boolean> {
+    signal.throwIfAborted();
+    const current = await this.repository.getScope(scopeId);
+    if (!current) return true;
+    if (current.status === "cleaned") return true;
+    if (terminal === "aborted" && current.status === "aborted") return true;
+    if (
+      expectedRevision !== undefined &&
+      current.revision !== expectedRevision
+    ) {
+      return false;
+    }
+    if (
+      current.status === "aborting" &&
+      Date.parse(current.updatedAt) > this.#now().getTime() - 60_000
+    ) {
+      return false;
+    }
+    const claimed = await this.repository.transitionScope(
+      scopeId,
+      current.revision,
+      includeSealed
+        ? ["open", "sealed", "cleanup-pending", "aborted", "aborting"]
+        : ["open", "cleanup-pending", "aborted", "aborting"],
+      "aborting",
+      this.#now().toISOString(),
+    );
+    if (!claimed) return false;
+    const artifacts = await this.repository.listArtifacts(scopeId);
+    let failed = false;
+    for (const artifact of artifacts) {
+      signal.throwIfAborted();
+      if (!(await this.cleanupArtifact(claimed, artifact, signal)))
+        failed = true;
+    }
+    const next = failed ? "cleanup-pending" : terminal;
+    const finalized = await this.repository.transitionScope(
+      scopeId,
+      claimed.revision,
+      ["aborting"],
+      next,
+      this.#now().toISOString(),
+    );
+    return !failed && Boolean(finalized);
+  }
+
+  private async cleanupArtifact(
+    scope: AiOutputArtifactScope,
+    artifact: AiOutputArtifactRecord,
+    signal: AbortSignal,
+  ) {
+    if (artifact.status === "aborted") return true;
+    const claimed = await this.repository.transitionArtifact(
+      artifact.artifactId,
+      artifact.generation,
+      ["creating", "uploading", "completed", "cleanup-pending", "aborting"],
+      "aborting",
+      this.#now().toISOString(),
+    );
+    if (!claimed) return false;
+    try {
+      const purged = await purgeCompletedOutputUpload(
+        this.storage,
+        scope,
+        claimed,
+        signal,
+      );
+      if (!purged && claimed.uploadSessionId) {
+        await this.writers
+          .create(scope, signal)
+          .abortUpload(claimed.uploadSessionId);
+      }
+      const finalized = await this.repository.transitionArtifact(
+        claimed.artifactId,
+        claimed.generation,
+        ["aborting"],
+        "aborted",
+        this.#now().toISOString(),
+      );
+      return Boolean(finalized);
+    } catch {
+      await this.repository.transitionArtifact(
+        claimed.artifactId,
+        claimed.generation,
+        ["aborting"],
+        "cleanup-pending",
+        this.#now().toISOString(),
+      );
+      return false;
+    }
+  }
+}

package/template/apps/server/src/ai-output-artifact/contracts.ts

@@ -0,0 +1,152 @@
+import type { AuthorizationScopeSnapshot } from "@southwind-ai/shared";
+
+export type AiOutputRuntimeKind = "agent" | "document" | "speech" | "embedding";
+
+export type AiOutputScopeStatus =
+  | "open"
+  | "sealed"
+  | "aborting"
+  | "cleanup-pending"
+  | "aborted"
+  | "cleaned";
+
+export type AiOutputArtifactStatus =
+  | "creating"
+  | "uploading"
+  | "completed"
+  | "aborting"
+  | "cleanup-pending"
+  | "aborted";
+
+export interface AiOutputArtifactScope {
+  readonly scopeId: string;
+  readonly runId: string;
+  readonly requestId: string;
+  readonly actorId: string;
+  readonly tenantId: string;
+  readonly moduleName: string;
+  readonly operationKey: string;
+  readonly runtimeKind: AiOutputRuntimeKind;
+  readonly outputKind: string;
+  readonly purpose: string;
+  readonly dataClassification: "public" | "internal" | "sensitive";
+  readonly idempotencyHash: string;
+  readonly fingerprint: string;
+  readonly scopeHash: string;
+  readonly scopeSnapshot: AuthorizationScopeSnapshot;
+  readonly deploymentIdentity: string;
+  readonly releaseDigest: string;
+  readonly offersDigest: string;
+  readonly policyDigest: string;
+  /** Scope 状态 CAS revision，不得作为 Runtime credential generation。 */
+  readonly revision: number;
+  /** 已分配 credential generation 的单调序列。 */
+  readonly grantSequence: number;
+  readonly grantHash?: string;
+  readonly activeGrantGeneration?: number;
+  readonly pendingGrantHash?: string;
+  readonly pendingGrantGeneration?: number;
+  readonly pendingGrantExpiresAt?: string;
+  readonly status: AiOutputScopeStatus;
+  readonly allowedMediaTypes: readonly string[];
+  readonly maxArtifactBytes: number;
+  readonly maxArtifacts: number;
+  readonly maxTotalBytes: number;
+  readonly artifactCount: number;
+  readonly completedByteSize: number;
+  readonly scopeExpiresAt: string;
+  readonly fileExpiresAt: string;
+  readonly refExpiresAt: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+}
+
+export interface AiOutputArtifactRecord {
+  readonly artifactId: string;
+  readonly scopeId: string;
+  readonly outputKey: string;
+  readonly fingerprint: string;
+  readonly generation: number;
+  readonly status: AiOutputArtifactStatus;
+  readonly uploadSessionId?: string;
+  readonly fileId?: string;
+  readonly filename: string;
+  readonly mimeType: string;
+  readonly expectedByteSize: number;
+  readonly expectedSha256: string;
+  readonly byteSize?: number;
+  readonly sha256?: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+}
+
+export interface AiOutputArtifactSinkDescriptorV1 {
+  readonly contractVersion: 1;
+  readonly scope: string;
+  readonly outputKind: string;
+  readonly deploymentIdentity: string;
+  readonly releaseDigest: string;
+  readonly offersDigest: string;
+  readonly policyDigest: string;
+  readonly grantGeneration: number;
+  readonly allowedMediaTypes: readonly string[];
+  readonly expiresAt: string;
+  readonly limits: {
+    readonly maxArtifactBytes: number;
+    readonly maxArtifacts: number;
+    readonly maxTotalBytes: number;
+  };
+}
+
+export interface AiOutputArtifactBeginResultV1 {
+  readonly contractVersion: 1;
+  readonly artifactId: string;
+  readonly status: AiOutputArtifactStatus;
+}
+
+export interface AiOutputArtifactReferenceV1 {
+  readonly contractVersion: 1;
+  readonly outputKey: string;
+  readonly value: string;
+  readonly mediaType: string;
+  readonly byteSize: number;
+  readonly sha256: string;
+  readonly expiresAt: string;
+}
+
+export interface AiOutputArtifactCompletionV1 {
+  readonly contractVersion: 1;
+  readonly artifactId: string;
+  readonly outputKey: string;
+  readonly status: "completed";
+  readonly mediaType: string;
+  readonly byteSize: number;
+  readonly sha256: string;
+}
+
+export interface AiOutputArtifactManifestItemV1 {
+  readonly contractVersion: 1;
+  readonly outputKey: string;
+  readonly filename: string;
+  readonly mediaType: string;
+  readonly byteSize: number;
+  readonly sha256: string;
+  readonly outputKind: string;
+}
+
+export class AiOutputArtifactError extends Error {
+  constructor(
+    readonly code:
+      | "OUTPUT_ARTIFACT_INVALID"
+      | "OUTPUT_ARTIFACT_FORBIDDEN"
+      | "OUTPUT_ARTIFACT_CONFLICT"
+      | "OUTPUT_ARTIFACT_LIMIT_EXCEEDED"
+      | "OUTPUT_ARTIFACT_NOT_READY"
+      | "OUTPUT_ARTIFACT_UNAVAILABLE",
+    message: string,
+    readonly retryable = false,
+  ) {
+    super(message);
+    this.name = "AiOutputArtifactError";
+  }
+}

package/template/apps/server/src/ai-output-artifact/drizzle-cleanup.ts

@@ -0,0 +1,37 @@
+import { aiOutputArtifactScopes } from "@southwind-ai/database";
+import { and, asc, eq, inArray, lte, or } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { mapAiOutputScope } from "./drizzle-mapping.js";
+
+export async function listDrizzleAiOutputCleanupScopes(
+  db: NodePgDatabase,
+  expiredBefore: string,
+  limit: number,
+) {
+  const instant = new Date(expiredBefore);
+  const stale = new Date(instant.getTime() - 60_000);
+  return (
+    await db
+      .select()
+      .from(aiOutputArtifactScopes)
+      .where(
+        or(
+          eq(aiOutputArtifactScopes.status, "cleanup-pending"),
+          and(
+            inArray(aiOutputArtifactScopes.status, ["open", "aborted"]),
+            lte(aiOutputArtifactScopes.scopeExpiresAt, instant),
+          ),
+          and(
+            eq(aiOutputArtifactScopes.status, "sealed"),
+            lte(aiOutputArtifactScopes.fileExpiresAt, instant),
+          ),
+          and(
+            eq(aiOutputArtifactScopes.status, "aborting"),
+            lte(aiOutputArtifactScopes.updatedAt, stale),
+          ),
+        ),
+      )
+      .orderBy(asc(aiOutputArtifactScopes.updatedAt))
+      .limit(limit)
+  ).map(mapAiOutputScope);
+}

package/template/apps/server/src/ai-output-artifact/drizzle-complete.ts

@@ -0,0 +1,71 @@
+import {
+  aiOutputArtifacts,
+  aiOutputArtifactScopes,
+} from "@southwind-ai/database";
+import { eq } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { mapAiOutputArtifact } from "./drizzle-mapping.js";
+
+export function completeDrizzleAiOutputArtifact(
+  db: NodePgDatabase,
+  artifactId: string,
+  generation: number,
+  file: {
+    readonly id: string;
+    readonly byteSize: number;
+    readonly sha256: string;
+  },
+  updatedAt: string,
+) {
+  return db.transaction(async (tx) => {
+    const [candidate] = await tx
+      .select()
+      .from(aiOutputArtifacts)
+      .where(eq(aiOutputArtifacts.artifactId, artifactId))
+      .limit(1);
+    if (!candidate) return undefined;
+    const [scope] = await tx
+      .select()
+      .from(aiOutputArtifactScopes)
+      .where(eq(aiOutputArtifactScopes.scopeId, candidate.scopeId))
+      .limit(1)
+      .for("update");
+    if (!scope || scope.status !== "open") return undefined;
+    const [artifact] = await tx
+      .select()
+      .from(aiOutputArtifacts)
+      .where(eq(aiOutputArtifacts.artifactId, artifactId))
+      .limit(1)
+      .for("update");
+    if (
+      !artifact ||
+      artifact.scopeId !== scope.scopeId ||
+      artifact.status !== "uploading" ||
+      artifact.generation !== generation ||
+      artifact.expectedByteSize !== file.byteSize ||
+      artifact.expectedSha256 !== file.sha256 ||
+      scope.completedByteSize + file.byteSize > scope.maxTotalBytes
+    ) {
+      return undefined;
+    }
+    const [completed] = await tx
+      .update(aiOutputArtifacts)
+      .set({
+        status: "completed",
+        fileId: file.id,
+        byteSize: file.byteSize,
+        sha256: file.sha256,
+        updatedAt: new Date(updatedAt),
+      })
+      .where(eq(aiOutputArtifacts.artifactId, artifactId))
+      .returning();
+    await tx
+      .update(aiOutputArtifactScopes)
+      .set({
+        completedByteSize: scope.completedByteSize + file.byteSize,
+        updatedAt: new Date(updatedAt),
+      })
+      .where(eq(aiOutputArtifactScopes.scopeId, scope.scopeId));
+    return completed ? mapAiOutputArtifact(completed) : undefined;
+  });
+}

package/template/apps/server/src/ai-output-artifact/drizzle-grant-cleanup.ts

@@ -0,0 +1,45 @@
+import { aiOutputArtifactScopes } from "@southwind-ai/database";
+import { and, asc, inArray, isNotNull, lte, sql } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+
+export async function clearExpiredDrizzleOutputGrantHashes(
+  db: NodePgDatabase,
+  expiredBefore: string,
+  limit: number,
+): Promise<number> {
+  const cutoff = new Date(expiredBefore);
+  const candidates = await db
+    .select({ scopeId: aiOutputArtifactScopes.scopeId })
+    .from(aiOutputArtifactScopes)
+    .where(
+      and(
+        inArray(aiOutputArtifactScopes.status, ["sealed", "aborted"]),
+        isNotNull(aiOutputArtifactScopes.grantHash),
+        lte(aiOutputArtifactScopes.refExpiresAt, cutoff),
+      ),
+    )
+    .orderBy(asc(aiOutputArtifactScopes.refExpiresAt))
+    .limit(limit);
+  if (!candidates.length) return 0;
+  const cleared = await db
+    .update(aiOutputArtifactScopes)
+    .set({
+      grantHash: null,
+      activeGrantGeneration: null,
+      revision: sql`${aiOutputArtifactScopes.revision} + 1`,
+      updatedAt: cutoff,
+    })
+    .where(
+      and(
+        inArray(
+          aiOutputArtifactScopes.scopeId,
+          candidates.map(({ scopeId }) => scopeId),
+        ),
+        inArray(aiOutputArtifactScopes.status, ["sealed", "aborted"]),
+        isNotNull(aiOutputArtifactScopes.grantHash),
+        lte(aiOutputArtifactScopes.refExpiresAt, cutoff),
+      ),
+    )
+    .returning({ scopeId: aiOutputArtifactScopes.scopeId });
+  return cleared.length;
+}

package/template/apps/server/src/ai-output-artifact/drizzle-grants.ts

@@ -0,0 +1,109 @@
+import { aiOutputArtifactScopes } from "@southwind-ai/database";
+import { and, eq, gt, isNull, lte, or, sql } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { mapAiOutputScope } from "./drizzle-mapping.js";
+
+export async function prepareDrizzleOutputGrant(
+  db: NodePgDatabase,
+  scopeId: string,
+  expectedRevision: number,
+  pendingGrantHash: string,
+  pendingGrantExpiresAt: string,
+  updatedAt: string,
+) {
+  const [row] = await db
+    .update(aiOutputArtifactScopes)
+    .set({
+      revision: sql`${aiOutputArtifactScopes.revision} + 1`,
+      grantSequence: sql`${aiOutputArtifactScopes.grantSequence} + 1`,
+      pendingGrantHash,
+      pendingGrantGeneration: sql`${aiOutputArtifactScopes.grantSequence} + 1`,
+      pendingGrantExpiresAt: new Date(pendingGrantExpiresAt),
+      updatedAt: new Date(updatedAt),
+    })
+    .where(
+      and(
+        eq(aiOutputArtifactScopes.scopeId, scopeId),
+        eq(aiOutputArtifactScopes.status, "open"),
+        eq(aiOutputArtifactScopes.revision, expectedRevision),
+        or(
+          isNull(aiOutputArtifactScopes.pendingGrantHash),
+          lte(
+            aiOutputArtifactScopes.pendingGrantExpiresAt,
+            new Date(updatedAt),
+          ),
+        ),
+      ),
+    )
+    .returning();
+  return row ? mapAiOutputScope(row) : undefined;
+}
+
+export async function promoteDrizzleOutputGrant(
+  db: NodePgDatabase,
+  scopeId: string,
+  expectedRevision: number,
+  pendingGrantGeneration: number,
+  pendingGrantHash: string,
+  updatedAt: string,
+) {
+  const [row] = await db
+    .update(aiOutputArtifactScopes)
+    .set({
+      revision: sql`${aiOutputArtifactScopes.revision} + 1`,
+      grantHash: pendingGrantHash,
+      activeGrantGeneration: pendingGrantGeneration,
+      pendingGrantHash: null,
+      pendingGrantGeneration: null,
+      pendingGrantExpiresAt: null,
+      updatedAt: new Date(updatedAt),
+    })
+    .where(
+      and(
+        eq(aiOutputArtifactScopes.scopeId, scopeId),
+        eq(aiOutputArtifactScopes.status, "open"),
+        eq(aiOutputArtifactScopes.revision, expectedRevision),
+        eq(
+          aiOutputArtifactScopes.pendingGrantGeneration,
+          pendingGrantGeneration,
+        ),
+        eq(aiOutputArtifactScopes.pendingGrantHash, pendingGrantHash),
+        gt(aiOutputArtifactScopes.pendingGrantExpiresAt, new Date(updatedAt)),
+      ),
+    )
+    .returning();
+  return row ? mapAiOutputScope(row) : undefined;
+}
+
+export async function rollbackDrizzleOutputGrant(
+  db: NodePgDatabase,
+  scopeId: string,
+  expectedRevision: number,
+  pendingGrantGeneration: number,
+  pendingGrantHash: string,
+  updatedAt: string,
+) {
+  const [row] = await db
+    .update(aiOutputArtifactScopes)
+    .set({
+      revision: sql`${aiOutputArtifactScopes.revision} + 1`,
+      pendingGrantHash: null,
+      pendingGrantGeneration: null,
+      pendingGrantExpiresAt: null,
+      updatedAt: new Date(updatedAt),
+    })
+    .where(
+      and(
+        eq(aiOutputArtifactScopes.scopeId, scopeId),
+        eq(aiOutputArtifactScopes.status, "open"),
+        eq(aiOutputArtifactScopes.revision, expectedRevision),
+        eq(
+          aiOutputArtifactScopes.pendingGrantGeneration,
+          pendingGrantGeneration,
+        ),
+        eq(aiOutputArtifactScopes.pendingGrantHash, pendingGrantHash),
+      ),
+    )
+    .returning();
+  return row ? mapAiOutputScope(row) : undefined;
+}

package/template/apps/server/src/ai-output-artifact/drizzle-mapping.ts

@@ -0,0 +1,77 @@
+import {
+  aiOutputArtifacts,
+  aiOutputArtifactScopes,
+} from "@southwind-ai/database";
+import type {
+  AiOutputArtifactRecord,
+  AiOutputArtifactScope,
+} from "./contracts.js";
+import type { NewAiOutputArtifact, NewAiOutputScope } from "./repository.js";
+
+export function aiOutputScopeValues(scope: NewAiOutputScope) {
+  return {
+    ...scope,
+    grantHash: scope.grantHash ?? null,
+    activeGrantGeneration: scope.activeGrantGeneration ?? null,
+    pendingGrantHash: scope.pendingGrantHash ?? null,
+    pendingGrantGeneration: scope.pendingGrantGeneration ?? null,
+    pendingGrantExpiresAt: scope.pendingGrantExpiresAt
+      ? new Date(scope.pendingGrantExpiresAt)
+      : null,
+    scopeSnapshot: structuredClone(scope.scopeSnapshot),
+    allowedMediaTypes: [...scope.allowedMediaTypes],
+    scopeExpiresAt: new Date(scope.scopeExpiresAt),
+    fileExpiresAt: new Date(scope.fileExpiresAt),
+    refExpiresAt: new Date(scope.refExpiresAt),
+    createdAt: new Date(scope.createdAt),
+    updatedAt: new Date(scope.updatedAt),
+  };
+}
+
+export function aiOutputArtifactValues(artifact: NewAiOutputArtifact) {
+  return {
+    ...artifact,
+    status: "creating" as const,
+    createdAt: new Date(artifact.createdAt),
+    updatedAt: new Date(artifact.createdAt),
+  };
+}
+
+export function mapAiOutputScope(
+  row: typeof aiOutputArtifactScopes.$inferSelect,
+): AiOutputArtifactScope {
+  return {
+    ...row,
+    runtimeKind: row.runtimeKind as AiOutputArtifactScope["runtimeKind"],
+    dataClassification:
+      row.dataClassification as AiOutputArtifactScope["dataClassification"],
+    scopeSnapshot: structuredClone(row.scopeSnapshot),
+    allowedMediaTypes: [...row.allowedMediaTypes],
+    grantHash: row.grantHash ?? undefined,
+    activeGrantGeneration: row.activeGrantGeneration ?? undefined,
+    pendingGrantHash: row.pendingGrantHash ?? undefined,
+    pendingGrantGeneration: row.pendingGrantGeneration ?? undefined,
+    pendingGrantExpiresAt: row.pendingGrantExpiresAt?.toISOString(),
+    status: row.status as AiOutputArtifactScope["status"],
+    scopeExpiresAt: row.scopeExpiresAt.toISOString(),
+    fileExpiresAt: row.fileExpiresAt.toISOString(),
+    refExpiresAt: row.refExpiresAt.toISOString(),
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+  };
+}
+
+export function mapAiOutputArtifact(
+  row: typeof aiOutputArtifacts.$inferSelect,
+): AiOutputArtifactRecord {
+  return {
+    ...row,
+    status: row.status as AiOutputArtifactRecord["status"],
+    uploadSessionId: row.uploadSessionId ?? undefined,
+    fileId: row.fileId ?? undefined,
+    byteSize: row.byteSize ?? undefined,
+    sha256: row.sha256 ?? undefined,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+  };
+}