create-windy 0.5.2 → 0.6.0

package/template/apps/server/src/ai-output-artifact/service-recovery.test.ts

@@ -0,0 +1,238 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createOutputArtifactFixture,
+  outputByteStream,
+  outputHash,
+  outputManifest,
+} from "./test-support.js";
+
+describe("AI Output Artifact 并发、恢复与 TTL", () => {
+  test("最长任务真实 Storage session 不早于 scope grace 到期", async () => {
+    const fixture = createOutputArtifactFixture();
+    fixture.setNow(new Date().toISOString());
+    const begun = await fixture.begin("session-ttl", "sensitive", {
+      maxDurationSeconds: 3_600,
+    });
+    const receipt = await fixture.service.beginArtifact(
+      begun.scope.scopeId,
+      begun.grant!,
+      outputManifest(new Uint8Array([1])),
+      new AbortController().signal,
+    );
+    const artifact = await fixture.repository.getArtifact(receipt.artifactId);
+    const session = await fixture.storage.repository.getSession(
+      artifact!.uploadSessionId!,
+    );
+    expect(Date.parse(session!.expiresAt)).toBeGreaterThanOrEqual(
+      Date.parse(begun.scope.scopeExpiresAt),
+    );
+  });
+
+  test("seal 与首次 claim 无论交错顺序都不会发布半成品", async () => {
+    for (const beginFirst of [true, false]) {
+      const fixture = createOutputArtifactFixture();
+      const begun = await fixture.begin(`race-${beginFirst}`);
+      const bytes = new Uint8Array([1]);
+      const begin = () =>
+        fixture.service.beginArtifact(
+          begun.scope.scopeId,
+          begun.grant!,
+          outputManifest(bytes),
+          new AbortController().signal,
+        );
+      const seal = () =>
+        fixture.service.sealScope(begun.scope.scopeId, begun.grant!);
+      await Promise.allSettled(
+        beginFirst ? [begin(), seal()] : [seal(), begin()],
+      );
+      const scope = await fixture.repository.getScope(begun.scope.scopeId);
+      const artifacts = await fixture.repository.listArtifacts(
+        begun.scope.scopeId,
+      );
+      expect(
+        scope?.status !== "sealed" ||
+          artifacts.every(({ status }) => status === "completed"),
+      ).toBe(true);
+    }
+  });
+
+  test("Storage complete 后进程中断可从 session 恢复并清理 file/blob", async () => {
+    const fixture = createOutputArtifactFixture();
+    const begun = await fixture.begin("restart-cleanup");
+    const bytes = new TextEncoder().encode("%PDF-1.7\nrestart");
+    const artifact = await beginAndAppend(fixture, begun, bytes);
+    const stored = await fixture.repository.getArtifact(artifact.artifactId);
+    const uploadSessionId = stored!.uploadSessionId!;
+    const file = await fixture.writers
+      .create(begun.scope, new AbortController().signal)
+      .completeUpload(uploadSessionId);
+
+    expect(
+      await fixture.storage.repository.getSession(uploadSessionId),
+    ).toMatchObject({ status: "completed", fileId: file.id });
+    expect(
+      (await fixture.repository.getArtifact(artifact.artifactId))?.status,
+    ).toBe("uploading");
+
+    expect(await fixture.cleanup.abortRun(begun.scope.runId)).toBe(true);
+    expect(
+      await fixture.storage.repository.getSession(uploadSessionId),
+    ).toBeUndefined();
+    expect(await fixture.storage.repository.getFile(file.id)).toBeUndefined();
+    expect(
+      (await fixture.repository.getArtifact(artifact.artifactId))?.status,
+    ).toBe("aborted");
+  });
+
+  test("stale aborting 会被 generation fencing 重新 claim 并终结", async () => {
+    const fixture = createOutputArtifactFixture();
+    const begun = await fixture.begin("stale-cleanup");
+    const claimed = await fixture.repository.transitionScope(
+      begun.scope.scopeId,
+      begun.scope.revision,
+      ["open"],
+      "aborting",
+      "2026-07-31T12:00:00.000Z",
+    );
+    expect(claimed?.status).toBe("aborting");
+    fixture.setNow("2026-07-31T12:02:00.001Z");
+
+    expect(await fixture.cleanup.cleanupExpired()).toEqual({
+      inspected: 1,
+      cleaned: 1,
+      pending: 0,
+    });
+    expect(
+      (await fixture.repository.getScope(begun.scope.scopeId))?.status,
+    ).toBe("cleaned");
+  });
+
+  test("最长敏感任务 seal 后仍有完整 ref TTL，ref 到期不提前删文件", async () => {
+    const fixture = createOutputArtifactFixture();
+    const begun = await fixture.begin("ttl-long", "sensitive", {
+      maxDurationSeconds: 3_600,
+    });
+    expect(begun.scope.scopeExpiresAt).toBe("2026-07-31T13:01:00.000Z");
+    expect(begun.scope.refExpiresAt).toBe("2026-07-31T13:16:00.000Z");
+    expect(begun.scope.fileExpiresAt).toBe("2026-08-01T13:01:00.000Z");
+    const bytes = new TextEncoder().encode("%PDF-1.7\nttl");
+    const artifact = await beginAndAppend(fixture, begun, bytes);
+    await fixture.service.completeArtifact(
+      begun.scope.scopeId,
+      begun.grant!,
+      artifact.artifactId,
+      new AbortController().signal,
+    );
+    fixture.setNow("2026-07-31T13:00:00.000Z");
+    const [reference] = await fixture.service.sealScope(
+      begun.scope.scopeId,
+      begun.grant!,
+    );
+    expect(reference!.expiresAt).toBe("2026-07-31T13:15:00.000Z");
+
+    fixture.setNow("2026-07-31T13:15:00.001Z");
+    await expect(
+      fixture.service.openReference(
+        reference!.value,
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({ code: "OUTPUT_ARTIFACT_FORBIDDEN" });
+    expect(await fixture.cleanup.cleanupExpired()).toMatchObject({
+      inspected: 0,
+    });
+    expect(
+      await fixture.storage.repository.getFile(
+        (await fixture.repository.getArtifact(artifact.artifactId))!.fileId!,
+      ),
+    ).toBeDefined();
+
+    fixture.setNow("2026-08-01T13:01:00.001Z");
+    expect(await fixture.cleanup.cleanupExpired()).toMatchObject({
+      cleaned: 1,
+    });
+  });
+
+  test("sealed 幂等重放返回现有引用，非法 oa1 统一 forbidden", async () => {
+    const fixture = createOutputArtifactFixture();
+    const begun = await fixture.begin("sealed-replay");
+    const artifact = await beginAndAppend(
+      fixture,
+      begun,
+      new TextEncoder().encode("%PDF-1.7\nreplay"),
+    );
+    await fixture.service.completeArtifact(
+      begun.scope.scopeId,
+      begun.grant!,
+      artifact.artifactId,
+      new AbortController().signal,
+    );
+    await fixture.service.sealScope(begun.scope.scopeId, begun.grant!);
+    const replay = await fixture.begin("sealed-replay");
+    expect(replay.references).toHaveLength(1);
+    expect(replay.descriptor).toBeDefined();
+    expect(replay.grant).toBeUndefined();
+    await expect(
+      fixture.service.openReference(
+        "oa1.invalid",
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({ code: "OUTPUT_ARTIFACT_FORBIDDEN" });
+  });
+
+  test("同一 run 可有多个 outputKind，abortRun 撤销全部 scope", async () => {
+    const fixture = createOutputArtifactFixture();
+    const begun = await fixture.begin("multi-kind", "sensitive", {
+      runId: "run_multi",
+    });
+    const {
+      artifactCount: _count,
+      completedByteSize: _bytes,
+      ...base
+    } = begun.scope;
+    await fixture.repository.createOrGetScope({
+      ...base,
+      scopeId: "outscope_audio",
+      runtimeKind: "speech",
+      outputKind: "normalized-audio",
+      idempotencyHash: "c".repeat(64),
+      fingerprint: "d".repeat(64),
+      allowedMediaTypes: ["audio/wav"],
+    });
+    expect(await fixture.repository.listScopesByRun("run_multi")).toHaveLength(
+      2,
+    );
+    expect(await fixture.cleanup.abortRun("run_multi")).toBe(true);
+    expect(
+      (await fixture.repository.listScopesByRun("run_multi")).map(
+        ({ status }) => status,
+      ),
+    ).toEqual(["aborted", "aborted"]);
+  });
+});
+
+async function beginAndAppend(
+  fixture: ReturnType<typeof createOutputArtifactFixture>,
+  begun: Awaited<ReturnType<typeof fixture.begin>>,
+  bytes: Uint8Array,
+) {
+  const artifact = await fixture.service.beginArtifact(
+    begun.scope.scopeId,
+    begun.grant!,
+    outputManifest(bytes),
+    new AbortController().signal,
+  );
+  await fixture.service.appendPart(
+    begun.scope.scopeId,
+    begun.grant!,
+    {
+      artifactId: artifact.artifactId,
+      partNumber: 0,
+      byteOffset: 0,
+      byteSize: bytes.byteLength,
+      sha256: outputHash(bytes),
+      body: outputByteStream(bytes),
+    },
+    new AbortController().signal,
+  );
+  return artifact;
+}

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

@@ -0,0 +1,240 @@
+import { canonicalizeUploadIdentity } from "@southwind-ai/storage";
+import { ModuleStorageError } from "@southwind-ai/server-sdk";
+import type {
+  AiOutputArtifactManifestItemV1,
+  AiOutputArtifactRecord,
+  AiOutputArtifactScope,
+  AiOutputArtifactSinkDescriptorV1,
+} from "./contracts.js";
+import { AiOutputArtifactError } from "./contracts.js";
+import type { AiOutputArtifactReferenceCodec } from "./reference-codec.js";
+
+export function outputSinkDescriptor(
+  scope: AiOutputArtifactScope,
+  generation?: number,
+): AiOutputArtifactSinkDescriptorV1 {
+  const grantGeneration =
+    generation ?? scope.pendingGrantGeneration ?? scope.activeGrantGeneration;
+  if (
+    !grantGeneration ||
+    (grantGeneration !== scope.pendingGrantGeneration &&
+      grantGeneration !== scope.activeGrantGeneration)
+  )
+    throw outputNotReady();
+  return {
+    contractVersion: 1,
+    scope: scope.scopeId,
+    outputKind: scope.outputKind,
+    deploymentIdentity: scope.deploymentIdentity,
+    releaseDigest: scope.releaseDigest,
+    offersDigest: scope.offersDigest,
+    policyDigest: scope.policyDigest,
+    grantGeneration,
+    allowedMediaTypes: [...scope.allowedMediaTypes],
+    expiresAt: scope.scopeExpiresAt,
+    limits: {
+      maxArtifactBytes: scope.maxArtifactBytes,
+      maxArtifacts: scope.maxArtifacts,
+      maxTotalBytes: scope.maxTotalBytes,
+    },
+  };
+}
+
+export function outputArtifactReceipt(artifact: AiOutputArtifactRecord) {
+  return {
+    contractVersion: 1 as const,
+    artifactId: artifact.artifactId,
+    status: artifact.status,
+  };
+}
+
+export function outputArtifactCompletion(artifact: AiOutputArtifactRecord) {
+  if (
+    artifact.status !== "completed" ||
+    artifact.byteSize === undefined ||
+    !artifact.sha256
+  ) {
+    throw outputNotReady();
+  }
+  return {
+    contractVersion: 1 as const,
+    artifactId: artifact.artifactId,
+    outputKey: artifact.outputKey,
+    status: artifact.status,
+    mediaType: artifact.mimeType,
+    byteSize: artifact.byteSize,
+    sha256: artifact.sha256,
+  };
+}
+
+export function outputArtifactReference(
+  scope: AiOutputArtifactScope,
+  artifact: AiOutputArtifactRecord,
+  references: AiOutputArtifactReferenceCodec,
+) {
+  if (
+    artifact.status !== "completed" ||
+    !artifact.fileId ||
+    artifact.byteSize === undefined ||
+    !artifact.sha256
+  ) {
+    throw outputNotReady();
+  }
+  return {
+    contractVersion: 1 as const,
+    outputKey: artifact.outputKey,
+    value: references.encode({
+      version: 1,
+      scopeId: scope.scopeId,
+      artifactId: artifact.artifactId,
+      actorId: scope.actorId,
+      moduleName: scope.moduleName,
+      operationKey: scope.operationKey,
+      runId: scope.runId,
+      fileId: artifact.fileId,
+      mediaType: artifact.mimeType,
+      byteSize: artifact.byteSize,
+      sha256: artifact.sha256,
+      expiresAt: scope.refExpiresAt,
+    }),
+    mediaType: artifact.mimeType,
+    byteSize: artifact.byteSize,
+    sha256: artifact.sha256,
+    expiresAt: scope.refExpiresAt,
+  };
+}
+
+export function validateOutputManifestItem(
+  scope: AiOutputArtifactScope,
+  input: AiOutputArtifactManifestItemV1,
+) {
+  let canonical: ReturnType<typeof canonicalizeUploadIdentity>;
+  try {
+    canonical = canonicalizeUploadIdentity(
+      { filename: input.filename, mimeType: input.mediaType },
+      Object.fromEntries(
+        scope.allowedMediaTypes.map((mediaType) => [
+          mediaType,
+          mediaType === "application/pdf" ? ["pdf"] : ["wav"],
+        ]),
+      ),
+    );
+  } catch {
+    throw outputInvalid();
+  }
+  if (
+    input.contractVersion !== 1 ||
+    input.outputKind !== scope.outputKind ||
+    !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$/.test(input.outputKey) ||
+    !Number.isSafeInteger(input.byteSize) ||
+    input.byteSize < 0 ||
+    input.byteSize > scope.maxArtifactBytes ||
+    !/^[a-f0-9]{64}$/.test(input.sha256)
+  ) {
+    throw outputInvalid();
+  }
+  return {
+    ...input,
+    filename: canonical.filename,
+    mediaType: canonical.mimeType,
+  };
+}
+
+export function validOutputReference(
+  scope: AiOutputArtifactScope,
+  artifact: AiOutputArtifactRecord,
+  claims: ReturnType<AiOutputArtifactReferenceCodec["decode"]>,
+  now: string,
+) {
+  return (
+    scope.status === "sealed" &&
+    scope.refExpiresAt > now &&
+    artifact.scopeId === scope.scopeId &&
+    artifact.status === "completed" &&
+    claims.actorId === scope.actorId &&
+    claims.moduleName === scope.moduleName &&
+    claims.operationKey === scope.operationKey &&
+    claims.runId === scope.runId &&
+    claims.fileId === artifact.fileId &&
+    claims.mediaType === artifact.mimeType &&
+    claims.byteSize === artifact.byteSize &&
+    claims.sha256 === artifact.sha256 &&
+    claims.expiresAt === scope.refExpiresAt
+  );
+}
+
+export function outputConflict() {
+  return new AiOutputArtifactError(
+    "OUTPUT_ARTIFACT_CONFLICT",
+    "AI Output Artifact 幂等语义冲突",
+  );
+}
+
+export function outputForbidden() {
+  return new AiOutputArtifactError(
+    "OUTPUT_ARTIFACT_FORBIDDEN",
+    "AI Output Artifact 当前不可访问",
+  );
+}
+
+export function outputLimitExceeded() {
+  return new AiOutputArtifactError(
+    "OUTPUT_ARTIFACT_LIMIT_EXCEEDED",
+    "AI Output Artifact 超过 Operation 上限",
+  );
+}
+
+export function outputNotReady() {
+  return new AiOutputArtifactError(
+    "OUTPUT_ARTIFACT_NOT_READY",
+    "AI Output Artifact 尚未完成",
+  );
+}
+
+export function outputUnavailable() {
+  return new AiOutputArtifactError(
+    "OUTPUT_ARTIFACT_UNAVAILABLE",
+    "AI Output Artifact 暂时不可用",
+    true,
+  );
+}
+
+export function outputStorageError(error: unknown): AiOutputArtifactError {
+  if (!(error instanceof ModuleStorageError)) return outputUnavailable();
+  if (
+    [
+      "INVALID_UPLOAD",
+      "UNSUPPORTED_FILE_TYPE",
+      "FILE_SIGNATURE_MISMATCH",
+      "SIZE_MISMATCH",
+      "HASH_MISMATCH",
+    ].includes(error.code)
+  ) {
+    return outputInvalid();
+  }
+  if (["UPLOAD_TOO_LARGE", "PART_TOO_LARGE"].includes(error.code)) {
+    return outputLimitExceeded();
+  }
+  if (["UPLOAD_OFFSET_CONFLICT", "CONCURRENT_UPLOAD"].includes(error.code)) {
+    return outputConflict();
+  }
+  if (
+    [
+      "UPLOAD_NOT_ACTIVE",
+      "UPLOAD_EXPIRED",
+      "UPLOAD_INCOMPLETE",
+      "UPLOAD_CANCELLED",
+    ].includes(error.code)
+  ) {
+    return outputNotReady();
+  }
+  if (error.code === "UPLOAD_FORBIDDEN") return outputForbidden();
+  return outputUnavailable();
+}
+
+export function outputInvalid() {
+  return new AiOutputArtifactError(
+    "OUTPUT_ARTIFACT_INVALID",
+    "AI Output Artifact manifest 无效",
+  );
+}