create-windy 0.5.2 → 0.6.1

package/template/apps/server/src/ai-output-artifact/postgres.integration.test.ts

@@ -0,0 +1,349 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { migrate } from "drizzle-orm/node-postgres/migrator";
+import { Pool } from "pg";
+import {
+  purgeRecoverableUploadRepository,
+  recoverableUploadRepository,
+} from "@southwind-ai/storage";
+import { DrizzleAiOutputArtifactRepository } from "./drizzle-repository.js";
+import {
+  beginPostgresArtifactScope,
+  clearPostgresArtifactTables,
+  createPostgresArtifactStack,
+  preparePostgresArtifactScope,
+} from "./postgres-test-support.js";
+import { verifyAiOutputArtifactRepositoryInvariants } from "./repository-invariants.test-support.js";
+import { purgeCompletedOutputUpload } from "./storage-recovery.js";
+import {
+  outputByteStream,
+  outputHash,
+  outputManifest,
+} from "./test-support.js";
+
+const databaseUrl = process.env.AI_OUTPUT_ARTIFACT_TEST_DATABASE_URL;
+const describePostgres = databaseUrl ? describe : describe.skip;
+let storageRoot = "";
+
+describePostgres("AI Output Artifact 真实 PostgreSQL 不变量", () => {
+  beforeAll(async () => {
+    storageRoot = await mkdtemp(join(tmpdir(), "windy-output-artifact-"));
+    const pool = new Pool({ connectionString: databaseUrl });
+    try {
+      await migrate(drizzle(pool), {
+        migrationsFolder: resolve(
+          import.meta.dir,
+          "../../../../packages/database/drizzle",
+        ),
+        migrationsSchema: "public",
+        migrationsTable: "__output_artifact_test_migrations",
+      });
+    } finally {
+      await pool.end();
+    }
+  });
+
+  afterAll(async () => {
+    if (storageRoot) await rm(storageRoot, { recursive: true, force: true });
+  });
+
+  test("Memory/PG 共用原子 seal、首次 claim 与 run-kind 不变量", async () => {
+    await clearPostgresArtifactTables(databaseUrl!);
+    const pool = new Pool({ connectionString: databaseUrl });
+    try {
+      await expect(
+        verifyAiOutputArtifactRepositoryInvariants(
+          new DrizzleAiOutputArtifactRepository(drizzle(pool)),
+        ),
+      ).resolves.toEqual({
+        races: 2,
+        outputKinds: 2,
+        closedScopeFences: 1,
+        lockOrders: 1,
+        grantScrubs: 1,
+        grantHandoffs: 1,
+      });
+    } finally {
+      await pool.end();
+    }
+  });
+
+  test("PostgreSQL 持久化 pending/current hash handoff，不出现 raw grant", async () => {
+    await clearPostgresArtifactTables(databaseUrl!);
+    const value = createPostgresArtifactStack(
+      databaseUrl!,
+      join(storageRoot, "grant-hash"),
+    );
+    try {
+      const begun = await preparePostgresArtifactScope(
+        value,
+        "pg-grant-hash",
+        "run_pg_grant_hash",
+      );
+      expect(begun.descriptor).not.toHaveProperty("grant");
+      const stored = await value.pool.query(
+        "select * from ai_output_artifact_scopes where scope_id = $1",
+        [begun.scope.scopeId],
+      );
+      expect(stored.rows).toHaveLength(1);
+      expect(JSON.stringify(stored.rows)).not.toContain(begun.grant!);
+      expect(stored.rows[0]?.grant_hash).toBeNull();
+      expect(stored.rows[0]?.pending_grant_hash).toMatch(/^[a-f0-9]{64}$/);
+      expect(stored.rows[0]?.pending_grant_generation).toBe(1);
+      expect(stored.rows[0]?.request_id).toBe("pg-output-artifact");
+      await expect(
+        value.service.requireWritable(begun.scope.scopeId, begun.grant!),
+      ).rejects.toMatchObject({ code: "OUTPUT_ARTIFACT_FORBIDDEN" });
+      const accepted = await value.service.acceptGrant(
+        begun.scope.scopeId,
+        begun.descriptor!.grantGeneration,
+        begun.grant!,
+      );
+      await expect(
+        value.service.acceptGrant(
+          begun.scope.scopeId,
+          begun.descriptor!.grantGeneration,
+          begun.grant!,
+        ),
+      ).resolves.toMatchObject({ revision: accepted.revision });
+      expect(
+        await value.repository.getScope(begun.scope.scopeId),
+      ).toMatchObject({
+        activeGrantGeneration: 1,
+        pendingGrantHash: undefined,
+      });
+    } finally {
+      await value.pool.end();
+    }
+  });
+
+  test("Storage complete 后 Server 重启可从 session 清理 file/blob", async () => {
+    await clearPostgresArtifactTables(databaseUrl!);
+    const first = createPostgresArtifactStack(
+      databaseUrl!,
+      join(storageRoot, "restart"),
+    );
+    const begun = await beginPostgresArtifactScope(
+      first,
+      "pg-restart",
+      "run_pg_restart",
+    );
+    const bytes = new TextEncoder().encode("%PDF-1.7\npostgres restart");
+    const artifact = await first.service.beginArtifact(
+      begun.scope.scopeId,
+      begun.grant!,
+      outputManifest(bytes),
+      new AbortController().signal,
+    );
+    await first.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,
+    );
+    const stored = await first.repository.getArtifact(artifact.artifactId);
+    const uploadSessionId = stored!.uploadSessionId!;
+    const file = await first.writers
+      .create(begun.scope, new AbortController().signal)
+      .completeUpload(uploadSessionId);
+    const storedFile = await first.storage.repository.getFile(file.id);
+    expect(storedFile).toBeDefined();
+    const uploadSession =
+      await first.storage.repository.getSession(uploadSessionId);
+    const purgeRecovery = purgeRecoverableUploadRepository(
+      first.storage.repository,
+    );
+    const expiryRecovery = recoverableUploadRepository(
+      first.storage.repository,
+    );
+    expect(uploadSession).toBeDefined();
+    expect(purgeRecovery).toBeDefined();
+    expect(expiryRecovery).toBeDefined();
+    await expect(
+      purgeRecovery!.beginPurgeCompletedSession(
+        uploadSessionId,
+        "wrong-owner",
+        file.id,
+        new Date().toISOString(),
+      ),
+    ).resolves.toBe(false);
+    await expect(
+      purgeCompletedOutputUpload(
+        first.storage,
+        { ...begun.scope, scopeHash: "f".repeat(64) },
+        stored!,
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({ code: "FILE_CONTENT_MISSING" });
+    await expect(
+      purgeRecovery!.beginPurgeCompletedSession(
+        uploadSessionId,
+        begun.scope.actorId,
+        file.id,
+        new Date().toISOString(),
+      ),
+    ).resolves.toBe(true);
+    const afterSessionExpiry = new Date(
+      Date.parse(uploadSession!.expiresAt) + 1,
+    ).toISOString();
+    await expect(
+      first.storage.repository.listExpiredSessions(afterSessionExpiry, 100),
+    ).resolves.toEqual([]);
+    await expect(
+      expiryRecovery!.claimExpiredSession(uploadSessionId, afterSessionExpiry),
+    ).resolves.toBe(false);
+    await expect(
+      first.storage.uploads.abort(uploadSessionId, begun.scope.actorId),
+    ).rejects.toMatchObject({ code: "UPLOAD_NOT_ACTIVE" });
+    await expect(
+      first.storage.repository.getSession(uploadSessionId),
+    ).resolves.toMatchObject({ status: "aborting", fileId: file.id });
+    await expect(
+      first.storage.repository.getFile(file.id),
+    ).resolves.toBeDefined();
+    await first.pool.end();
+
+    const restarted = createPostgresArtifactStack(
+      databaseUrl!,
+      join(storageRoot, "restart"),
+    );
+    try {
+      expect(await restarted.cleanup.abortRun(begun.scope.runId)).toBe(true);
+      expect(
+        await restarted.storage.repository.getSession(uploadSessionId),
+      ).toBeUndefined();
+      expect(
+        await restarted.storage.repository.getFile(file.id),
+      ).toBeUndefined();
+      expect(
+        await restarted.storage.blobStore.inspect(storedFile!.artifactRef),
+      ).toBeUndefined();
+      expect(
+        (await restarted.repository.getArtifact(artifact.artifactId))?.status,
+      ).toBe("aborted");
+    } finally {
+      await restarted.pool.end();
+    }
+  });
+
+  test("open scope 在 scope TTL 到期后由 PostgreSQL cleanup 终结", async () => {
+    await clearPostgresArtifactTables(databaseUrl!);
+    let instant = new Date();
+    const value = createPostgresArtifactStack(
+      databaseUrl!,
+      join(storageRoot, "scope-ttl"),
+      () => instant,
+    );
+    try {
+      const begun = await beginPostgresArtifactScope(
+        value,
+        "pg-scope-ttl",
+        "run_pg_scope_ttl",
+      );
+      instant = new Date(Date.parse(begun.scope.scopeExpiresAt) + 1);
+      await expect(value.cleanup.cleanupExpired()).resolves.toMatchObject({
+        cleaned: 1,
+      });
+      expect(
+        (await value.repository.getScope(begun.scope.scopeId))?.status,
+      ).toBe("cleaned");
+    } finally {
+      await value.pool.end();
+    }
+  });
+
+  test("真实 artifact 在 ref TTL 拒绝读取、到 file TTL 才清 file/blob", async () => {
+    await clearPostgresArtifactTables(databaseUrl!);
+    let instant = new Date();
+    const value = createPostgresArtifactStack(
+      databaseUrl!,
+      join(storageRoot, "artifact-ttl"),
+      () => instant,
+    );
+    try {
+      const begun = await beginPostgresArtifactScope(
+        value,
+        "pg-artifact-ttl",
+        "run_pg_artifact_ttl",
+      );
+      const bytes = new TextEncoder().encode("%PDF-1.7\npostgres ttl");
+      const receipt = await value.service.beginArtifact(
+        begun.scope.scopeId,
+        begun.grant!,
+        outputManifest(bytes),
+        new AbortController().signal,
+      );
+      await value.service.appendPart(
+        begun.scope.scopeId,
+        begun.grant!,
+        {
+          artifactId: receipt.artifactId,
+          partNumber: 0,
+          byteOffset: 0,
+          byteSize: bytes.byteLength,
+          sha256: outputHash(bytes),
+          body: outputByteStream(bytes),
+        },
+        new AbortController().signal,
+      );
+      await value.service.completeArtifact(
+        begun.scope.scopeId,
+        begun.grant!,
+        receipt.artifactId,
+        new AbortController().signal,
+      );
+      const artifact = await value.repository.getArtifact(receipt.artifactId);
+      const file = await value.storage.repository.getFile(artifact!.fileId!);
+      expect(file).toBeDefined();
+      const [reference] = await value.service.sealScope(
+        begun.scope.scopeId,
+        begun.grant!,
+      );
+
+      instant = new Date(Date.parse(reference!.expiresAt) + 1);
+      await expect(
+        value.service.openReference(
+          reference!.value,
+          new AbortController().signal,
+        ),
+      ).rejects.toMatchObject({ code: "OUTPUT_ARTIFACT_FORBIDDEN" });
+      await expect(value.cleanup.cleanupExpired()).resolves.toEqual({
+        inspected: 0,
+        cleaned: 0,
+        pending: 0,
+      });
+      await expect(
+        value.storage.repository.getFile(file!.id),
+      ).resolves.toBeDefined();
+      await expect(
+        value.storage.blobStore.inspect(file!.artifactRef),
+      ).resolves.toBeDefined();
+
+      instant = new Date(Date.parse(begun.scope.fileExpiresAt) + 1);
+      await expect(value.cleanup.cleanupExpired()).resolves.toMatchObject({
+        cleaned: 1,
+      });
+      await expect(
+        value.storage.repository.getFile(file!.id),
+      ).resolves.toBeUndefined();
+      await expect(
+        value.storage.blobStore.inspect(file!.artifactRef),
+      ).resolves.toBeUndefined();
+      expect(
+        (await value.repository.getScope(begun.scope.scopeId))?.status,
+      ).toBe("cleaned");
+    } finally {
+      await value.pool.end();
+    }
+  });
+});

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

@@ -0,0 +1,128 @@
+import {
+  createCipheriv,
+  createDecipheriv,
+  createHash,
+  randomBytes,
+} from "node:crypto";
+
+export interface AiOutputArtifactReferenceClaimsV1 {
+  readonly version: 1;
+  readonly scopeId: string;
+  readonly artifactId: string;
+  readonly actorId: string;
+  readonly moduleName: string;
+  readonly operationKey: string;
+  readonly runId: string;
+  readonly fileId: string;
+  readonly mediaType: string;
+  readonly byteSize: number;
+  readonly sha256: string;
+  readonly expiresAt: string;
+}
+
+const aad = Buffer.from("southwind-ai-output-artifact-v1");
+
+export class AiOutputArtifactReferenceCodec {
+  readonly #key: Buffer;
+
+  constructor(secret: string) {
+    if (new TextEncoder().encode(secret).byteLength < 32) {
+      throw new Error("AI Output Artifact 加密 Secret 至少需要 32 字节");
+    }
+    this.#key = createHash("sha256")
+      .update("output-artifact\u0000")
+      .update(secret)
+      .digest();
+  }
+
+  encode(claims: AiOutputArtifactReferenceClaimsV1): string {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", this.#key, iv);
+    cipher.setAAD(aad);
+    const encrypted = Buffer.concat([
+      cipher.update(JSON.stringify(claims), "utf8"),
+      cipher.final(),
+    ]);
+    return [
+      "oa1",
+      iv.toString("base64url"),
+      encrypted.toString("base64url"),
+      cipher.getAuthTag().toString("base64url"),
+    ].join(".");
+  }
+
+  decode(token: string): AiOutputArtifactReferenceClaimsV1 {
+    try {
+      if (token.length > 4_096) throw new Error("token too large");
+      const [version, iv, encrypted, tag, extra] = token.split(".");
+      if (version !== "oa1" || !iv || !encrypted || !tag || extra) {
+        throw new Error("token shape");
+      }
+      const decipher = createDecipheriv(
+        "aes-256-gcm",
+        this.#key,
+        canonicalBase64url(iv, 12),
+      );
+      decipher.setAAD(aad);
+      decipher.setAuthTag(canonicalBase64url(tag, 16));
+      const plaintext = Buffer.concat([
+        decipher.update(canonicalBase64url(encrypted)),
+        decipher.final(),
+      ]);
+      return parseClaims(JSON.parse(plaintext.toString("utf8")));
+    } catch {
+      throw new AiOutputArtifactReferenceCodecError();
+    }
+  }
+}
+
+export class AiOutputArtifactReferenceCodecError extends Error {
+  constructor() {
+    super("AI Output Artifact 引用无效");
+    this.name = "AiOutputArtifactReferenceCodecError";
+  }
+}
+
+function parseClaims(value: unknown): AiOutputArtifactReferenceClaimsV1 {
+  if (!record(value) || value.version !== 1) throw new Error("claims");
+  const claims = value as unknown as AiOutputArtifactReferenceClaimsV1;
+  for (const field of [
+    claims.scopeId,
+    claims.artifactId,
+    claims.actorId,
+    claims.moduleName,
+    claims.operationKey,
+    claims.runId,
+    claims.fileId,
+    claims.mediaType,
+    claims.sha256,
+    claims.expiresAt,
+  ]) {
+    if (typeof field !== "string" || !field.trim()) throw new Error("field");
+  }
+  if (
+    !Number.isSafeInteger(claims.byteSize) ||
+    claims.byteSize < 0 ||
+    !/^[a-f0-9]{64}$/.test(claims.sha256) ||
+    !Number.isFinite(Date.parse(claims.expiresAt))
+  ) {
+    throw new Error("metadata");
+  }
+  return claims;
+}
+
+function canonicalBase64url(value: string, bytes?: number): Buffer {
+  if (!/^[A-Za-z0-9_-]+$/.test(value)) throw new Error("base64url");
+  const decoded = Buffer.from(value, "base64url");
+  if (
+    decoded.toString("base64url") !== value ||
+    (bytes !== undefined && decoded.byteLength !== bytes)
+  ) {
+    throw new Error("canonical");
+  }
+  return decoded;
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

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

@@ -0,0 +1,165 @@
+import type {
+  AiOutputArtifactRepository,
+  NewAiOutputScope,
+} from "./repository.js";
+
+export async function verifyAiOutputArtifactGrantHandoff(
+  repository: AiOutputArtifactRepository,
+  scopeRecord: (scopeId: string, runId: string) => NewAiOutputScope,
+): Promise<void> {
+  const handoffScope = scopeRecord("scope_handoff", "run_handoff");
+  await repository.createOrGetScope(handoffScope);
+  const pendingHashes = ["4".repeat(64), "5".repeat(64)] as const;
+  const preparedResults = await Promise.all(
+    pendingHashes.map((hash) =>
+      repository.prepareGrant(
+        handoffScope.scopeId,
+        handoffScope.revision,
+        hash,
+        "2026-08-01T00:00:15.000Z",
+        "2026-08-01T00:00:05.000Z",
+      ),
+    ),
+  );
+  const preparedIndex = preparedResults.findIndex(Boolean);
+  if (preparedResults.filter(Boolean).length !== 1 || preparedIndex < 0) {
+    throw new Error("并发 replay 覆盖了 active pending grant");
+  }
+  const pending = preparedResults[preparedIndex]!;
+  const pendingHash = pendingHashes[preparedIndex]!;
+  if (
+    pending.grantHash !== handoffScope.grantHash ||
+    pending.activeGrantGeneration !== 1 ||
+    pending.pendingGrantGeneration !== 2 ||
+    pending.grantSequence !== 2
+  ) {
+    throw new Error("prepare pending 提前废弃了 current grant");
+  }
+  const promoted = await repository.promoteGrant(
+    pending.scopeId,
+    pending.revision,
+    pending.pendingGrantGeneration!,
+    pendingHash,
+    "2026-08-01T00:00:06.000Z",
+  );
+  if (
+    !promoted ||
+    promoted.grantHash !== pendingHash ||
+    promoted.activeGrantGeneration !== 2 ||
+    promoted.pendingGrantHash !== undefined
+  ) {
+    throw new Error("pending grant 未原子 promote 为 current");
+  }
+  if (
+    await repository.promoteGrant(
+      pending.scopeId,
+      pending.revision,
+      pending.pendingGrantGeneration!,
+      pendingHash,
+      "2026-08-01T00:00:07.000Z",
+    )
+  ) {
+    throw new Error("重复 ACK 绕过了 revision fence");
+  }
+
+  const rollbackScope = {
+    ...scopeRecord("scope_rollback", "run_rollback"),
+    grantHash: undefined,
+    activeGrantGeneration: undefined,
+    pendingGrantHash: "6".repeat(64),
+    pendingGrantGeneration: 1,
+    pendingGrantExpiresAt: "2026-08-01T00:00:15.000Z",
+  };
+  await repository.createOrGetScope(rollbackScope);
+  const rolledBack = await repository.rollbackGrant(
+    rollbackScope.scopeId,
+    rollbackScope.revision,
+    1,
+    rollbackScope.pendingGrantHash,
+    "2026-08-01T00:00:06.000Z",
+  );
+  if (
+    !rolledBack ||
+    rolledBack.grantHash !== undefined ||
+    rolledBack.pendingGrantHash !== undefined ||
+    rolledBack.status !== "open"
+  ) {
+    throw new Error("pre-ACK rollback 未保留可重试空 open scope");
+  }
+  const retryPendingHash = "7".repeat(64);
+  const retryPrepared = await repository.prepareGrant(
+    rollbackScope.scopeId,
+    rolledBack.revision,
+    retryPendingHash,
+    "2026-08-01T00:00:20.000Z",
+    "2026-08-01T00:00:07.000Z",
+  );
+  if (
+    !retryPrepared ||
+    retryPrepared.pendingGrantGeneration !== 2 ||
+    (await repository.promoteGrant(
+      rollbackScope.scopeId,
+      retryPrepared.revision,
+      1,
+      rollbackScope.pendingGrantHash,
+      "2026-08-01T00:00:08.000Z",
+    ))
+  ) {
+    throw new Error("迟到 ACK 接受了已 rollback 的 credential");
+  }
+  const retryPromoted = await repository.promoteGrant(
+    rollbackScope.scopeId,
+    retryPrepared.revision,
+    retryPrepared.pendingGrantGeneration,
+    retryPendingHash,
+    "2026-08-01T00:00:09.000Z",
+  );
+  if (retryPromoted?.activeGrantGeneration !== 2) {
+    throw new Error("rollback 后相同语义重试无法 accept 新 token");
+  }
+  const leasedHash = "8".repeat(64);
+  const leased = await repository.prepareGrant(
+    rollbackScope.scopeId,
+    retryPromoted.revision,
+    leasedHash,
+    "2026-08-01T00:00:12.000Z",
+    "2026-08-01T00:00:10.000Z",
+  );
+  if (
+    !leased ||
+    (await repository.prepareGrant(
+      rollbackScope.scopeId,
+      leased.revision,
+      "9".repeat(64),
+      "2026-08-01T00:00:13.000Z",
+      "2026-08-01T00:00:11.000Z",
+    ))
+  ) {
+    throw new Error("未决 pending lease 被并发 replay 覆盖");
+  }
+  const replacementHash = "a".repeat(64);
+  const replaced = await repository.prepareGrant(
+    rollbackScope.scopeId,
+    leased.revision,
+    replacementHash,
+    "2026-08-01T00:00:20.000Z",
+    "2026-08-01T00:00:13.000Z",
+  );
+  if (
+    !replaced ||
+    replaced.pendingGrantGeneration !== 4 ||
+    replaced.grantHash !== retryPendingHash ||
+    replaced.activeGrantGeneration !== 2 ||
+    (await repository.promoteGrant(
+      rollbackScope.scopeId,
+      replaced.revision,
+      leased.pendingGrantGeneration!,
+      leasedHash,
+      "2026-08-01T00:00:14.000Z",
+    ))
+  ) {
+    throw new Error(
+      "pending lease/restart replacement 破坏 current 或接受迟到 ACK",
+    );
+  }
+}