create-windy 0.5.2 → 0.6.1

package/template/apps/server/src/ai-output-artifact/repository-invariants.test-support.ts

@@ -0,0 +1,239 @@
+import { createHash } from "node:crypto";
+import type { AuthorizationScopeSnapshot } from "@southwind-ai/shared";
+import type { AiOutputArtifactRepository } from "./repository.js";
+import { AiOutputArtifactRepositoryError } from "./repository.js";
+import { verifyAiOutputArtifactGrantHandoff } from "./repository-grant-invariants.test-support.js";
+
+export async function verifyAiOutputArtifactRepositoryInvariants(
+  repository: AiOutputArtifactRepository,
+) {
+  let verifiedRaces = 0;
+  for (const claimFirst of [true, false]) {
+    const suffix = claimFirst ? "claim" : "seal";
+    const scope = scopeRecord(`scope_${suffix}`, `run_${suffix}`);
+    await repository.createOrGetScope(scope);
+    const claim = () => repository.claimArtifact(artifactRecord(scope));
+    const seal = () =>
+      repository.sealScope(
+        scope.scopeId,
+        scope.revision,
+        "2026-08-01T00:15:00.000Z",
+        "2026-08-01T00:00:01.000Z",
+      );
+    let claimPromise: ReturnType<typeof claim>;
+    let sealPromise: ReturnType<typeof seal>;
+    if (claimFirst) {
+      claimPromise = claim();
+      sealPromise = seal();
+    } else {
+      sealPromise = seal();
+      claimPromise = claim();
+    }
+    const [claimResult, sealResult] = await Promise.allSettled([
+      claimPromise,
+      sealPromise,
+    ] as const);
+    const [current, artifacts] = await Promise.all([
+      repository.getScope(scope.scopeId),
+      repository.listArtifacts(scope.scopeId),
+    ]);
+    const claimWon =
+      claimResult.status === "fulfilled" && claimResult.value.claimed;
+    const sealWon =
+      sealResult.status === "fulfilled" &&
+      sealResult.value?.status === "sealed";
+    const expectedConflict =
+      claimResult.status !== "rejected" ||
+      (claimResult.reason instanceof AiOutputArtifactRepositoryError &&
+        claimResult.reason.code === "CONFLICT");
+    if (
+      claimWon === sealWon ||
+      !expectedConflict ||
+      sealResult.status === "rejected" ||
+      (claimWon &&
+        (current?.status !== "open" ||
+          artifacts.length !== 1 ||
+          artifacts[0]?.status !== "creating")) ||
+      (sealWon && (current?.status !== "sealed" || artifacts.length !== 0))
+    ) {
+      throw new Error("seal/claim 竞态结果不是唯一可接受胜者");
+    }
+    verifiedRaces += 1;
+  }
+
+  const first = scopeRecord("scope_multi_pdf", "run_multi");
+  const second = {
+    ...scopeRecord("scope_multi_audio", "run_multi"),
+    runtimeKind: "speech" as const,
+    outputKind: "normalized-audio",
+    idempotencyHash: "c".repeat(64),
+    fingerprint: "d".repeat(64),
+    allowedMediaTypes: ["audio/wav"],
+  };
+  await repository.createOrGetScope(first);
+  await repository.createOrGetScope(second);
+  const scopes = await repository.listScopesByRun("run_multi");
+  if (scopes.length !== 2) {
+    throw new Error("同一 run 的多个 outputKind 未独立持久化");
+  }
+
+  const closedScope = scopeRecord("scope_closed", "run_closed");
+  await repository.createOrGetScope(closedScope);
+  const closedArtifact = artifactRecord(closedScope);
+  await repository.claimArtifact(closedArtifact);
+  await repository.transitionScope(
+    closedScope.scopeId,
+    closedScope.revision,
+    ["open"],
+    "aborted",
+    "2026-08-01T00:00:02.000Z",
+  );
+  let closedScopeFenced = false;
+  try {
+    await repository.claimArtifact(closedArtifact);
+  } catch (error) {
+    closedScopeFenced =
+      error instanceof AiOutputArtifactRepositoryError &&
+      error.code === "CONFLICT";
+  }
+  if (!closedScopeFenced) {
+    throw new Error("关闭 scope 仍可重新 claim creating artifact");
+  }
+
+  const completionScope = scopeRecord("scope_lock_order", "run_lock_order");
+  await repository.createOrGetScope(completionScope);
+  const completionArtifact = artifactRecord(completionScope);
+  const claimed = await repository.claimArtifact(completionArtifact);
+  await repository.bindUploadSession(
+    claimed.artifact.artifactId,
+    claimed.artifact.generation,
+    "upload_lock_order",
+    "2026-08-01T00:00:02.000Z",
+  );
+  await Promise.all([
+    repository.claimArtifact(completionArtifact),
+    repository.completeArtifact(
+      completionArtifact.artifactId,
+      claimed.artifact.generation,
+      {
+        id: "file_lock_order",
+        byteSize: completionArtifact.expectedByteSize,
+        sha256: completionArtifact.expectedSha256,
+      },
+      "2026-08-01T00:00:03.000Z",
+    ),
+  ]);
+  if (
+    (await repository.getArtifact(completionArtifact.artifactId))?.status !==
+    "completed"
+  ) {
+    throw new Error("claim/complete 锁顺序未稳定完成");
+  }
+
+  const scrubScope = scopeRecord("scope_grant_scrub", "run_grant_scrub");
+  await repository.createOrGetScope(scrubScope);
+  const sealedForScrub = await repository.sealScope(
+    scrubScope.scopeId,
+    scrubScope.revision,
+    "2026-08-01T00:11:00.000Z",
+    "2026-08-01T00:00:04.000Z",
+  );
+  if (!sealedForScrub?.grantHash) {
+    throw new Error("sealed scope 未保留可撤销 grant hash");
+  }
+  if (
+    (await repository.clearExpiredGrantHashes(
+      "2026-08-01T00:11:00.001Z",
+      100,
+    )) !== 1
+  ) {
+    throw new Error("ref TTL 后未精确脱敏 sealed grant hash");
+  }
+  const scrubbed = await repository.getScope(scrubScope.scopeId);
+  if (
+    scrubbed?.status !== "sealed" ||
+    scrubbed.grantHash !== undefined ||
+    scrubbed.activeGrantGeneration !== undefined ||
+    scrubbed.revision !== sealedForScrub.revision + 1
+  ) {
+    throw new Error("sealed grant hash 脱敏未保留状态或 generation fence");
+  }
+
+  await verifyAiOutputArtifactGrantHandoff(repository, scopeRecord);
+
+  return {
+    races: verifiedRaces,
+    outputKinds: scopes.length,
+    closedScopeFences: 1,
+    lockOrders: 1,
+    grantScrubs: 1,
+    grantHandoffs: 1,
+  };
+}
+
+function scopeRecord(scopeId: string, runId: string) {
+  const createdAt = "2026-08-01T00:00:00.000Z";
+  return {
+    scopeId,
+    runId,
+    requestId: "request-repository-invariant",
+    actorId: "user-1",
+    tenantId: "single-tenant",
+    moduleName: "evidence",
+    operationKey: "evidence.document.ocr",
+    runtimeKind: "document" as const,
+    outputKind: "searchable-pdf",
+    purpose: "ai-runtime-output",
+    dataClassification: "sensitive" as const,
+    idempotencyHash: digest(scopeId, "a"),
+    fingerprint: digest(scopeId, "b"),
+    scopeHash: "e".repeat(64),
+    scopeSnapshot: scopeSnapshot(),
+    deploymentIdentity:
+      "windy-deployment-v1_7db61d8e-e50d-4f8a-9f3f-9b7a1d932e01",
+    releaseDigest: `sha256:${"a".repeat(64)}`,
+    offersDigest: `sha256:${"b".repeat(64)}`,
+    policyDigest: "f".repeat(64),
+    revision: 1,
+    grantSequence: 1,
+    grantHash: "1".repeat(64),
+    activeGrantGeneration: 1,
+    status: "open" as const,
+    allowedMediaTypes: ["application/pdf"],
+    maxArtifactBytes: 1024,
+    maxArtifacts: 2,
+    maxTotalBytes: 2048,
+    scopeExpiresAt: "2026-08-01T00:10:00.000Z",
+    refExpiresAt: "2026-08-01T00:15:00.000Z",
+    fileExpiresAt: "2026-08-02T00:10:00.000Z",
+    createdAt,
+    updatedAt: createdAt,
+  };
+}
+
+function artifactRecord(scope: ReturnType<typeof scopeRecord>) {
+  return {
+    artifactId: `artifact_${scope.scopeId}`,
+    scopeId: scope.scopeId,
+    outputKey: "searchable-pdf",
+    fingerprint: "2".repeat(64),
+    filename: "searchable.pdf",
+    mimeType: "application/pdf",
+    expectedByteSize: 4,
+    expectedSha256: "3".repeat(64),
+    createdAt: "2026-08-01T00:00:00.001Z",
+  };
+}
+
+function scopeSnapshot(): AuthorizationScopeSnapshot {
+  return {
+    tenantId: "single-tenant",
+    actorId: "user-1",
+    grants: [{ scope: "self" }],
+    roleIds: ["analyst"],
+  };
+}
+
+function digest(value: string, fill: string) {
+  return createHash("sha256").update(value).update(fill).digest("hex");
+}

package/template/apps/server/src/ai-output-artifact/repository-invariants.test.ts

@@ -0,0 +1,18 @@
+import { expect, test } from "bun:test";
+import { InMemoryAiOutputArtifactRepository } from "./memory-repository.js";
+import { verifyAiOutputArtifactRepositoryInvariants } from "./repository-invariants.test-support.js";
+
+test("Memory Repository 与 PostgreSQL 共用 seal/claim/run-kind 不变量", async () => {
+  await expect(
+    verifyAiOutputArtifactRepositoryInvariants(
+      new InMemoryAiOutputArtifactRepository(),
+    ),
+  ).resolves.toEqual({
+    races: 2,
+    outputKinds: 2,
+    closedScopeFences: 1,
+    lockOrders: 1,
+    grantScrubs: 1,
+    grantHandoffs: 1,
+  });
+});

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

@@ -0,0 +1,107 @@
+import type {
+  AiOutputArtifactRecord,
+  AiOutputArtifactScope,
+  AiOutputArtifactStatus,
+  AiOutputScopeStatus,
+} from "./contracts.js";
+
+export type NewAiOutputScope = Omit<
+  AiOutputArtifactScope,
+  "artifactCount" | "completedByteSize"
+>;
+
+export type NewAiOutputArtifact = Omit<
+  AiOutputArtifactRecord,
+  "generation" | "status" | "createdAt" | "updatedAt"
+> & {
+  readonly createdAt: string;
+};
+
+export class AiOutputArtifactRepositoryError extends Error {
+  constructor(readonly code: "CONFLICT" | "LIMIT") {
+    super(`AI Output Artifact repository ${code.toLowerCase()}`);
+    this.name = "AiOutputArtifactRepositoryError";
+  }
+}
+
+export interface AiOutputArtifactRepository {
+  createOrGetScope(
+    scope: NewAiOutputScope,
+  ): Promise<{ scope: AiOutputArtifactScope; created: boolean }>;
+  getScope(scopeId: string): Promise<AiOutputArtifactScope | undefined>;
+  listScopesByRun(runId: string): Promise<AiOutputArtifactScope[]>;
+  prepareGrant(
+    scopeId: string,
+    expectedRevision: number,
+    pendingGrantHash: string,
+    pendingGrantExpiresAt: string,
+    updatedAt: string,
+  ): Promise<AiOutputArtifactScope | undefined>;
+  promoteGrant(
+    scopeId: string,
+    expectedRevision: number,
+    pendingGrantGeneration: number,
+    pendingGrantHash: string,
+    updatedAt: string,
+  ): Promise<AiOutputArtifactScope | undefined>;
+  rollbackGrant(
+    scopeId: string,
+    expectedRevision: number,
+    pendingGrantGeneration: number,
+    pendingGrantHash: string,
+    updatedAt: string,
+  ): Promise<AiOutputArtifactScope | undefined>;
+  transitionScope(
+    scopeId: string,
+    expectedRevision: number,
+    expectedStatuses: readonly AiOutputScopeStatus[],
+    status: AiOutputScopeStatus,
+    updatedAt: string,
+  ): Promise<AiOutputArtifactScope | undefined>;
+  sealScope(
+    scopeId: string,
+    expectedRevision: number,
+    refExpiresAt: string,
+    updatedAt: string,
+  ): Promise<AiOutputArtifactScope | undefined>;
+  listCleanupScopes(
+    expiredBefore: string,
+    limit: number,
+  ): Promise<AiOutputArtifactScope[]>;
+  clearExpiredGrantHashes(
+    expiredBefore: string,
+    limit: number,
+  ): Promise<number>;
+  claimArtifact(
+    artifact: NewAiOutputArtifact,
+  ): Promise<{ artifact: AiOutputArtifactRecord; claimed: boolean }>;
+  bindUploadSession(
+    artifactId: string,
+    generation: number,
+    uploadSessionId: string,
+    updatedAt: string,
+  ): Promise<AiOutputArtifactRecord | undefined>;
+  completeArtifact(
+    artifactId: string,
+    generation: number,
+    file: {
+      readonly id: string;
+      readonly byteSize: number;
+      readonly sha256: string;
+    },
+    updatedAt: string,
+  ): Promise<AiOutputArtifactRecord | undefined>;
+  transitionArtifact(
+    artifactId: string,
+    expectedGeneration: number,
+    expectedStatuses: readonly AiOutputArtifactStatus[],
+    status: AiOutputArtifactStatus,
+    updatedAt: string,
+  ): Promise<AiOutputArtifactRecord | undefined>;
+  getArtifact(artifactId: string): Promise<AiOutputArtifactRecord | undefined>;
+  listArtifacts(scopeId: string): Promise<AiOutputArtifactRecord[]>;
+  /**
+   * 仅删除已终止的专用 readiness probe 行；业务 scope 永远不允许走此入口。
+   */
+  deleteReadinessProbe(scopeId: string, purpose: string): Promise<boolean>;
+}

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

@@ -0,0 +1,173 @@
+import {
+  AiOutputArtifactError,
+  type AiOutputArtifactManifestItemV1,
+} from "./contracts.js";
+
+export interface AiOutputArtifactRouteContext {
+  readonly params: Record<string, string | undefined>;
+  readonly request: Request;
+}
+
+const manifestMaxBytes = 4_096;
+const partMaxBytes = 8 * 1_024 * 1_024;
+
+export async function readOutputManifest(
+  context: AiOutputArtifactRouteContext,
+): Promise<AiOutputArtifactManifestItemV1> {
+  rejectTransferEncoding(context.request);
+  const declared = declaredLength(context.request, manifestMaxBytes);
+  const bytes = await readBoundedBody(context.request.body, manifestMaxBytes);
+  if (
+    !bytes.byteLength ||
+    (declared !== undefined && declared !== bytes.length)
+  ) {
+    throw invalid();
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+  } catch {
+    throw invalid();
+  }
+  return manifest(value);
+}
+
+export async function requireEmptyOutputRequest(
+  context: AiOutputArtifactRouteContext,
+): Promise<void> {
+  rejectTransferEncoding(context.request);
+  const length = declaredLength(context.request, 0);
+  if ((length !== undefined && length !== 0) || context.request.body) {
+    throw invalid();
+  }
+}
+
+export function outputPartInput(context: AiOutputArtifactRouteContext) {
+  rejectTransferEncoding(context.request);
+  const byteSize = declaredLength(context.request, partMaxBytes);
+  if (!context.request.body || byteSize === undefined || byteSize <= 0) {
+    throw invalid();
+  }
+  return {
+    partNumber: unsigned(context.params.partNumber),
+    byteOffset: unsigned(context.request.headers.get("x-upload-offset")),
+    byteSize,
+    sha256: sha256(context.request.headers.get("x-content-sha256")),
+    body: context.request.body,
+  };
+}
+
+export function rejectOutputBody(
+  body: ReadableStream<Uint8Array> | null,
+): void {
+  if (!body || body.locked) return;
+  void body.cancel("ai-output-artifact-rejected").catch(() => undefined);
+}
+
+function manifest(value: unknown): AiOutputArtifactManifestItemV1 {
+  if (!record(value)) throw invalid();
+  const allowed = new Set([
+    "contractVersion",
+    "outputKey",
+    "filename",
+    "mediaType",
+    "byteSize",
+    "sha256",
+    "outputKind",
+  ]);
+  if (
+    Object.keys(value).some((key) => !allowed.has(key)) ||
+    value.contractVersion !== 1 ||
+    typeof value.outputKey !== "string" ||
+    value.outputKey.length > 80 ||
+    typeof value.filename !== "string" ||
+    value.filename.length > 255 ||
+    typeof value.mediaType !== "string" ||
+    value.mediaType.length > 128 ||
+    !Number.isSafeInteger(value.byteSize) ||
+    typeof value.sha256 !== "string" ||
+    typeof value.outputKind !== "string" ||
+    value.outputKind.length > 80
+  ) {
+    throw invalid();
+  }
+  return value as unknown as AiOutputArtifactManifestItemV1;
+}
+
+async function readBoundedBody(
+  body: ReadableStream<Uint8Array> | null,
+  maxBytes: number,
+): Promise<Uint8Array> {
+  if (!body) throw invalid();
+  const reader = body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    while (true) {
+      const next = await reader.read();
+      if (next.done) break;
+      total += next.value.byteLength;
+      if (total > maxBytes) {
+        rejectReader(reader, "ai-output-artifact-body-limit");
+        throw invalid();
+      }
+      chunks.push(next.value);
+    }
+  } catch (error) {
+    if (!(error instanceof AiOutputArtifactError)) {
+      rejectReader(reader, error);
+    }
+    if (error instanceof AiOutputArtifactError) throw error;
+    throw invalid();
+  }
+  const result = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return result;
+}
+
+function rejectReader(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  reason: unknown,
+): void {
+  void reader.cancel(reason).catch(() => undefined);
+}
+
+function declaredLength(request: Request, maxBytes: number) {
+  const value = request.headers.get("content-length");
+  if (value === null) return undefined;
+  if (!/^(0|[1-9]\d*)$/.test(value)) throw invalid();
+  const length = Number(value);
+  if (!Number.isSafeInteger(length) || length > maxBytes) throw invalid();
+  return length;
+}
+
+function rejectTransferEncoding(request: Request): void {
+  if (request.headers.has("transfer-encoding")) throw invalid();
+}
+
+function unsigned(value: string | null | undefined): number {
+  if (!value || !/^(0|[1-9]\d*)$/.test(value)) throw invalid();
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed)) throw invalid();
+  return parsed;
+}
+
+function sha256(value: string | null): string {
+  if (!value || !/^[a-f0-9]{64}$/.test(value)) throw invalid();
+  return value;
+}
+
+function invalid() {
+  return new AiOutputArtifactError(
+    "OUTPUT_ARTIFACT_INVALID",
+    "AI Output Artifact 请求无效",
+  );
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}