create-windy 0.5.2 → 0.6.0

package/template/apps/server/src/document/facade-idempotency.test.ts

@@ -0,0 +1,195 @@
+import { describe, expect, test } from "bun:test";
+import {
+  outputByteStream,
+  outputHash,
+  outputManifest,
+} from "../ai-output-artifact/test-support.js";
+import { documentRunId } from "./facade-support.js";
+import { DocumentRuntimeError } from "./contracts.js";
+import {
+  createDocumentOutputFixture,
+  operationKey,
+} from "./output-artifact.test-support.js";
+
+const sourceA = {
+  value: "input-artifact",
+  mediaType: "application/pdf",
+  byteSize: 10,
+  sha256: "a".repeat(64),
+  expiresAt: "2026-07-31T12:05:00.000Z",
+};
+const sourceB = {
+  value: "input-artifact-b",
+  mediaType: "application/pdf",
+  byteSize: 20,
+  sha256: "b".repeat(64),
+  expiresAt: "2026-07-31T12:05:00.000Z",
+};
+
+describe("Document Output Artifact idempotency semantics", () => {
+  test("相同幂等键的 options 漂移冲突且绝不撤销原 scope", async () => {
+    const fixture = await createDocumentOutputFixture();
+    await fixture.facade.start(
+      operationKey,
+      [sourceA],
+      { mode: "first" },
+      "options-drift",
+      fixture.context(),
+      new AbortController().signal,
+    );
+    const first = fixture.remote.starts[0]!;
+    await expect(
+      fixture.facade.start(
+        operationKey,
+        [sourceA],
+        { mode: "second" },
+        "options-drift",
+        fixture.context(),
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({ code: "RUN_CONFLICT", status: 409 });
+
+    expect(fixture.remote.starts).toHaveLength(1);
+    expect(
+      (
+        await fixture.output.service.requireWritable(
+          first.request.outputArtifactSink!.scope,
+          first.outputArtifactGrant!,
+        )
+      ).status,
+    ).toBe("open");
+  });
+
+  test("source 顺序与稳定元数据参与语义，临时 value 不参与", async () => {
+    const drift = await createDocumentOutputFixture();
+    await drift.facade.start(
+      operationKey,
+      [sourceA, sourceB],
+      {},
+      "source-order",
+      drift.context(),
+      new AbortController().signal,
+    );
+    await expect(
+      drift.facade.start(
+        operationKey,
+        [sourceB, sourceA],
+        {},
+        "source-order",
+        drift.context(),
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({ code: "RUN_CONFLICT", status: 409 });
+    expect(drift.remote.starts).toHaveLength(1);
+
+    const replay = await createDocumentOutputFixture();
+    replay.remote.useIdempotencyStore = true;
+    const first = await replay.facade.start(
+      operationKey,
+      [sourceA],
+      {},
+      "source-token-refresh",
+      replay.context(),
+      new AbortController().signal,
+    );
+    const refreshed = await replay.facade.start(
+      operationKey,
+      [{ ...sourceA, value: "temporary-refreshed-value" }],
+      {},
+      "source-token-refresh",
+      replay.context(),
+      new AbortController().signal,
+    );
+    expect(refreshed.runId).toBe(first.runId);
+    expect(replay.remote.executions).toBe(1);
+  });
+
+  test("start 失败补偿只撤本次 generation，seal 竞态保留成品", async () => {
+    const fixture = await createDocumentOutputFixture();
+    fixture.remote.beforeStart = async (request, grant) => {
+      await publishOne(fixture, request.outputArtifactSink!.scope, grant!);
+    };
+    fixture.remote.startResult = () => ({
+      runId: documentRunId("f".repeat(64)),
+      status: "accepted",
+      eventsUrl: "/api/document/runs/drift/events",
+    });
+
+    await expect(
+      fixture.facade.start(
+        operationKey,
+        [sourceA],
+        {},
+        "seal-before-response",
+        fixture.context(),
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({ code: "INVALID_RESPONSE", status: 503 });
+    const scopeId = fixture.remote.starts[0]!.request.outputArtifactSink!.scope;
+    expect(
+      (await fixture.output.service.options.repository.getScope(scopeId))
+        ?.status,
+    ).toBe("sealed");
+  });
+
+  test("Runtime Error 的 message/retryability 不进入公共错误", async () => {
+    const fixture = await createDocumentOutputFixture();
+    fixture.remote.beforeStart = () => {
+      throw new DocumentRuntimeError(
+        "RUNTIME_UNAVAILABLE",
+        "secret outgrant_v1_raw",
+        false,
+      );
+    };
+
+    await expect(
+      fixture.facade.start(
+        operationKey,
+        [sourceA],
+        {},
+        "safe-runtime-error",
+        fixture.context(),
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({
+      code: "RUNTIME_UNAVAILABLE",
+      message: "Document Runtime 暂时不可用",
+      status: 503,
+      retryable: true,
+    });
+  });
+});
+
+async function publishOne(
+  fixture: Awaited<ReturnType<typeof createDocumentOutputFixture>>,
+  scopeId: string,
+  grant: string,
+) {
+  const bytes = new TextEncoder().encode("%PDF-1.7\ngeneration");
+  const receipt = await fixture.output.service.beginArtifact(
+    scopeId,
+    grant,
+    outputManifest(bytes),
+    new AbortController().signal,
+  );
+  await fixture.output.service.appendPart(
+    scopeId,
+    grant,
+    {
+      artifactId: receipt.artifactId,
+      partNumber: 0,
+      byteOffset: 0,
+      byteSize: bytes.byteLength,
+      sha256: outputHash(bytes),
+      body: outputByteStream(bytes),
+    },
+    new AbortController().signal,
+  );
+  await fixture.output.service.completeArtifact(
+    scopeId,
+    grant,
+    receipt.artifactId,
+    new AbortController().signal,
+  );
+  await fixture.output.service.sealScope(scopeId, grant);
+}

package/template/apps/server/src/document/facade-invocation.ts

@@ -0,0 +1,46 @@
+import {
+  resolveProviderEgress,
+  type ModuleAiOperationDefinition,
+} from "@southwind-ai/modules";
+import type {
+  ModuleAiArtifactRef,
+  ModuleAiJsonValue,
+} from "@southwind-ai/server-sdk";
+import type { DocumentOutputArtifactInvocation } from "./output-artifact-fingerprint.js";
+
+export function createDocumentInvocation(input: {
+  readonly runId: string;
+  readonly operationKey: string;
+  readonly options: ModuleAiJsonValue;
+  readonly sources: readonly Pick<
+    ModuleAiArtifactRef,
+    "value" | "mediaType" | "byteSize" | "sha256"
+  >[];
+  readonly definition: ModuleAiOperationDefinition;
+  readonly maxUnits: number;
+  readonly maxArtifacts: number;
+}): DocumentOutputArtifactInvocation {
+  return {
+    kind: "document",
+    runId: input.runId,
+    operationKey: input.operationKey,
+    options: input.options,
+    sources: input.sources.map(({ value, mediaType, byteSize, sha256 }) => ({
+      value,
+      mediaType,
+      byteSize,
+      sha256,
+    })),
+    requiredCapabilities: input.definition.requiredCapabilities,
+    dataClassification: input.definition.dataClassification,
+    limits: {
+      maxDurationSeconds: input.definition.limits.maxDurationSeconds,
+      maxInputBytes: input.definition.limits.maxInputBytes,
+      maxOutputBytes: input.definition.limits.maxOutputBytes,
+      maxUnits: input.maxUnits,
+      maxArtifacts: input.maxArtifacts,
+    },
+    providerEgress: resolveProviderEgress(input.definition),
+    providerDataPolicy: input.definition.providerDataPolicy,
+  };
+}

package/template/apps/server/src/document/facade-output-artifact.test.ts

@@ -0,0 +1,310 @@
+import { describe, expect, test } from "bun:test";
+import { documentRunId } from "./facade-support.js";
+import {
+  documentOutputSource as source,
+  publishDocumentOutput as publishOne,
+} from "./output-artifact-publish.test-support.js";
+import {
+  createDocumentOutputFixture,
+  documentActor,
+  operationKey,
+  readyProjection,
+} from "./output-artifact.test-support.js";
+
+describe("Document Facade Output Artifact binding", () => {
+  test("Host 固定 run/scope，start JSON 无 grant，确认 cancelled 后撤销输出", async () => {
+    const fixture = await createDocumentOutputFixture();
+    const started = await fixture.facade.start(
+      operationKey,
+      [source],
+      {},
+      "request-1",
+      fixture.context(),
+      new AbortController().signal,
+    );
+    const call = fixture.remote.starts[0]!;
+    expect(call.request.runId).toBeDefined();
+    expect(started.runId).toBe(call.request.runId!);
+    expect(call.request.runId).toMatch(/^doc_[a-f0-9]{64}$/);
+    expect(call.request.outputArtifactSink).toMatchObject({
+      contractVersion: 1,
+      outputKind: "searchable-pdf",
+    });
+    expect(call.outputArtifactGrant).toMatch(/^outgrant_v1_/);
+    expect(JSON.stringify(call.request)).not.toContain(
+      call.outputArtifactGrant!,
+    );
+    expect(call.request.outputArtifactSink).not.toHaveProperty("grant");
+
+    const scopeId = call.request.outputArtifactSink!.scope;
+    fixture.remote.beforeCancel = async () => {
+      expect(
+        (await fixture.output.service.options.repository.getScope(scopeId))
+          ?.status,
+      ).toBe("open");
+    };
+    const cancelled = await fixture.facade.cancel(
+      started.runId,
+      "user-request",
+      fixture.context(),
+      new AbortController().signal,
+    );
+    expect(cancelled.status).toBe(200);
+    expect(fixture.remote.cancels).toEqual([started.runId]);
+    expect(
+      (await fixture.output.service.options.repository.getScope(scopeId))
+        ?.status,
+    ).toBe("aborted");
+  });
+
+  test("events/result/cancel 前重跑 Permission 与 scope snapshot", async () => {
+    const fixture = await createDocumentOutputFixture();
+    const started = await fixture.facade.start(
+      operationKey,
+      [source],
+      {},
+      "request-auth-drift",
+      fixture.context(),
+      new AbortController().signal,
+    );
+    fixture.setActor(documentActor([]));
+    await expect(
+      fixture.facade.authorizeRun(started.runId, fixture.context()),
+    ).rejects.toMatchObject({ code: "FORBIDDEN", status: 403 });
+
+    fixture.setActor(documentActor(undefined, "different-scope"));
+    await expect(
+      fixture.facade.authorizeRun(started.runId, fixture.context()),
+    ).rejects.toMatchObject({ code: "FORBIDDEN", status: 403 });
+  });
+
+  test("response-lost sealed replay 由 Runtime 幂等复用；丢失状态失败但保留成品", async () => {
+    let readiness = readyProjection();
+    const fixture = await createDocumentOutputFixture(() => readiness);
+    fixture.remote.useIdempotencyStore = true;
+    const start = () =>
+      fixture.facade.start(
+        operationKey,
+        [source],
+        {},
+        "response-lost",
+        fixture.context(),
+        new AbortController().signal,
+      );
+    const first = await start();
+    const firstCall = fixture.remote.starts[0]!;
+    await publishOne(
+      fixture,
+      firstCall.request.outputArtifactSink!.scope,
+      firstCall.outputArtifactGrant!,
+    );
+
+    const replay = await start();
+    expect(replay.runId).toBe(first.runId);
+    expect(fixture.remote.executions).toBe(1);
+    expect(fixture.remote.starts[1]?.request).toEqual({
+      ...firstCall.request,
+      outputArtifactSink: {
+        ...firstCall.request.outputArtifactSink!,
+        grantGeneration: 1,
+      },
+    });
+    expect(fixture.remote.starts[1]?.outputArtifactGrant).toBeUndefined();
+
+    readiness = readyProjection({ status: "unavailable" });
+    await expect(start()).rejects.toMatchObject({
+      code: "CAPABILITY_UNAVAILABLE",
+      status: 503,
+    });
+    readiness = readyProjection();
+    fixture.remote.loseState();
+    await expect(start()).rejects.toMatchObject({
+      code: "RUN_CONFLICT",
+      status: 409,
+    });
+    expect(
+      (
+        await fixture.output.service.options.repository.getScope(
+          firstCall.request.outputArtifactSink!.scope,
+        )
+      )?.status,
+    ).toBe("sealed");
+    expect(fixture.remote.executions).toBe(1);
+  });
+
+  test("Runtime 返回漂移 runId 时撤销 scope 并失败关闭", async () => {
+    const fixture = await createDocumentOutputFixture();
+    fixture.remote.startResult = () => ({
+      runId: documentRunId("f".repeat(64)),
+      status: "accepted",
+      eventsUrl: "/api/document/runs/drift/events",
+    });
+    await expect(
+      fixture.facade.start(
+        operationKey,
+        [source],
+        {},
+        "drifted-run",
+        fixture.context(),
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({ code: "INVALID_RESPONSE", status: 503 });
+    const scopeId = fixture.remote.starts[0]!.request.outputArtifactSink!.scope;
+    expect(
+      (await fixture.output.service.options.repository.getScope(scopeId))
+        ?.status,
+    ).toBe("open");
+    expect(
+      await fixture.output.service.options.repository.getScope(scopeId),
+    ).toMatchObject({
+      activeGrantGeneration: 1,
+      pendingGrantHash: undefined,
+    });
+  });
+
+  test("迟到 cancel 遇 completed 保留 sealed refs", async () => {
+    const fixture = await createDocumentOutputFixture();
+    const started = await fixture.facade.start(
+      operationKey,
+      [source],
+      {},
+      "late-cancel",
+      fixture.context(),
+      new AbortController().signal,
+    );
+    const call = fixture.remote.starts[0]!;
+    const [reference] = await publishOne(
+      fixture,
+      call.request.outputArtifactSink!.scope,
+      call.outputArtifactGrant!,
+    );
+    fixture.remote.cancelResult = (runId) =>
+      Response.json({ runId, status: "completed" });
+
+    const response = await fixture.facade.cancel(
+      started.runId,
+      "late",
+      fixture.context(),
+      new AbortController().signal,
+    );
+    expect((await response.json()).status).toBe("completed");
+    expect(
+      (
+        await fixture.output.service.options.repository.getScope(
+          call.request.outputArtifactSink!.scope,
+        )
+      )?.status,
+    ).toBe("sealed");
+    const opened = await fixture.output.service.openReference(
+      reference!.value,
+      new AbortController().signal,
+    );
+    await opened.body.cancel();
+  });
+
+  test("active cancel 与 seal 竞态最终撤销产物，remote 失败也补偿", async () => {
+    const racing = await createDocumentOutputFixture();
+    const started = await racing.facade.start(
+      operationKey,
+      [source],
+      {},
+      "cancel-seal-race",
+      racing.context(),
+      new AbortController().signal,
+    );
+    const call = racing.remote.starts[0]!;
+    let reference = "";
+    racing.remote.beforeCancel = async () => {
+      const [created] = await publishOne(
+        racing,
+        call.request.outputArtifactSink!.scope,
+        call.outputArtifactGrant!,
+      );
+      reference = created!.value;
+    };
+    await racing.facade.cancel(
+      started.runId,
+      "race",
+      racing.context(),
+      new AbortController().signal,
+    );
+    expect(
+      (
+        await racing.output.service.options.repository.getScope(
+          call.request.outputArtifactSink!.scope,
+        )
+      )?.status,
+    ).toBe("aborted");
+    await expect(
+      racing.output.service.openReference(
+        reference,
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({ code: "OUTPUT_ARTIFACT_FORBIDDEN" });
+
+    const failed = await createDocumentOutputFixture();
+    const failedStart = await failed.facade.start(
+      operationKey,
+      [source],
+      {},
+      "cancel-timeout",
+      failed.context(),
+      new AbortController().signal,
+    );
+    failed.remote.cancelError = new Error("network timeout with secret");
+    await expect(
+      failed.facade.cancel(
+        failedStart.runId,
+        "timeout",
+        failed.context(),
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({ code: "CAPABILITY_UNAVAILABLE", status: 503 });
+    expect(
+      (
+        await failed.output.service.options.repository.getScope(
+          failed.remote.starts[0]!.request.outputArtifactSink!.scope,
+        )
+      )?.status,
+    ).toBe("aborted");
+  });
+
+  test("cancel 响应丢失时只撤 open scope，不删除并发 sealed 成品", async () => {
+    const fixture = await createDocumentOutputFixture();
+    const started = await fixture.facade.start(
+      operationKey,
+      [source],
+      {},
+      "cancel-response-lost",
+      fixture.context(),
+      new AbortController().signal,
+    );
+    const call = fixture.remote.starts[0]!;
+    const [reference] = await publishOne(
+      fixture,
+      call.request.outputArtifactSink!.scope,
+      call.outputArtifactGrant!,
+    );
+    fixture.remote.cancelError = new Error("response lost");
+    await expect(
+      fixture.facade.cancel(
+        started.runId,
+        "late-timeout",
+        fixture.context(),
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({ code: "CAPABILITY_UNAVAILABLE", status: 503 });
+    expect(
+      (
+        await fixture.output.service.options.repository.getScope(
+          call.request.outputArtifactSink!.scope,
+        )
+      )?.status,
+    ).toBe("sealed");
+    const opened = await fixture.output.service.openReference(
+      reference!.value,
+      new AbortController().signal,
+    );
+    await opened.body.cancel();
+  });
+});

package/template/apps/server/src/document/facade-read-response.ts

@@ -0,0 +1,116 @@
+import { DocumentRuntimeError, type DocumentRuntimePort } from "./contracts.js";
+import { DocumentFacadeError } from "./errors.js";
+import {
+  documentResponseLimit,
+  documentStreamLimit,
+  boundDocumentResponse,
+} from "./remote-response.js";
+import {
+  capabilityUnavailable,
+  documentRuntimeFacadeError,
+} from "./facade-support.js";
+
+export function documentEventsResponse(
+  remote: DocumentRuntimePort,
+  runId: string,
+  cursor: number,
+  signal: AbortSignal,
+): Promise<Response> {
+  return safeDocumentReadResponse(
+    () => remote.events(runId, cursor, signal),
+    "text/event-stream",
+    documentStreamLimit,
+  );
+}
+
+export function documentResultResponse(
+  remote: DocumentRuntimePort,
+  runId: string,
+  signal: AbortSignal,
+): Promise<Response> {
+  return safeDocumentReadResponse(
+    () => remote.result(runId, signal),
+    "application/json",
+    documentResponseLimit,
+  );
+}
+
+async function safeDocumentReadResponse(
+  request: () => Promise<Response>,
+  mediaType: "text/event-stream" | "application/json",
+  maxBytes: number,
+): Promise<Response> {
+  let response: Response;
+  try {
+    response = await request();
+  } catch (error) {
+    if (error instanceof DocumentRuntimeError) {
+      throw documentRuntimeFacadeError(error.code);
+    }
+    throw capabilityUnavailable();
+  }
+  if (!response.ok) {
+    rejectRemoteBody(response.body);
+    throw documentReadHttpError(response.status);
+  }
+  const contentType = response.headers
+    .get("content-type")
+    ?.split(";", 1)[0]
+    ?.trim()
+    .toLowerCase();
+  if (contentType !== mediaType || !response.body) {
+    rejectRemoteBody(response.body);
+    throw new DocumentFacadeError(
+      "INVALID_RESPONSE",
+      "Document Runtime 响应无效",
+      503,
+      false,
+    );
+  }
+  let bounded: Response;
+  try {
+    bounded = boundDocumentResponse(response, maxBytes);
+  } catch (error) {
+    if (error instanceof DocumentRuntimeError) {
+      throw documentRuntimeFacadeError(error.code);
+    }
+    throw capabilityUnavailable();
+  }
+  return new Response(bounded.body, {
+    status: bounded.status,
+    headers: {
+      "content-type": mediaType,
+      "cache-control": "private, no-store",
+    },
+  });
+}
+
+function rejectRemoteBody(body: ReadableStream<Uint8Array> | null): void {
+  if (!body || body.locked) return;
+  void body.cancel("document-runtime-response-rejected").catch(() => undefined);
+}
+
+function documentReadHttpError(status: number): DocumentFacadeError {
+  if (status === 401 || status === 403) {
+    return new DocumentFacadeError(
+      "FORBIDDEN",
+      "Document Runtime 拒绝访问",
+      403,
+      false,
+    );
+  }
+  if (status === 409) {
+    return new DocumentFacadeError(
+      "RUN_CONFLICT",
+      "Document Run 状态冲突",
+      409,
+      false,
+    );
+  }
+  return new DocumentFacadeError(
+    "RUNTIME_UNAVAILABLE",
+    "Document Runtime 暂时不可用",
+    503,
+    true,
+  );
+}