create-windy 0.5.1 → 0.6.0

package/template/apps/server/src/speech/routes.ts

@@ -34,6 +34,7 @@ export function registerSpeechRunRoutes(
           idempotencyKey,
           context.guardContext,
           context.request.signal,
+          request.contract,
         ),
         { status: 202 },
       );
@@ -46,7 +47,7 @@ export function registerSpeechRunRoutes(
     const context = raw as RouteContext;
     try {
       const runId = required(context.params.runId);
-      facade.authorizeRun(runId, context.guardContext);
+      await facade.authorizeRun(runId, context.guardContext);
       return await remote.events(
         runId,
         cursor(context.query.after),
@@ -57,28 +58,42 @@ export function registerSpeechRunRoutes(
     }
   });
 
-  for (const resource of ["result", "artifact"] as const) {
-    app.get(`/speech/runs/:runId/${resource}`, async (raw) => {
-      const context = raw as RouteContext;
-      try {
-        const runId = required(context.params.runId);
-        facade.authorizeRun(runId, context.guardContext);
-        return await remote[resource](runId, context.request.signal);
-      } catch (error) {
-        return knownError(error);
-      }
-    });
-  }
+  app.get("/speech/runs/:runId/result", async (raw) => {
+    const context = raw as RouteContext;
+    try {
+      return await facade.result(
+        required(context.params.runId),
+        context.guardContext,
+        context.request.signal,
+      );
+    } catch (error) {
+      return knownError(error);
+    }
+  });
+
+  app.get("/speech/runs/:runId/artifact", async (raw) => {
+    const context = raw as RouteContext;
+    try {
+      return await facade.result(
+        required(context.params.runId),
+        context.guardContext,
+        context.request.signal,
+        true,
+      );
+    } catch (error) {
+      return knownError(error);
+    }
+  });
 
   app.post("/speech/runs/:runId/cancel", async (raw) => {
     const context = raw as RouteContext;
     try {
       const runId = required(context.params.runId);
-      facade.authorizeRun(runId, context.guardContext);
       const body = isRecord(context.body) ? context.body : {};
-      return await remote.cancel(
+      return await facade.cancel(
         runId,
         typeof body.reason === "string" ? body.reason.slice(0, 200) : undefined,
+        context.guardContext,
         context.request.signal,
       );
     } catch (error) {
@@ -91,11 +106,22 @@ function parseStart(body: unknown): {
   operationKey: string;
   source: ModuleAiArtifactRef;
   options: ModuleAiJsonValue;
+  contract: {
+    readonly contractVersion?: 2;
+    readonly variant?: "normalize" | "transcribe" | "translate";
+  };
 } {
   if (
     !isRecord(body) ||
     Object.keys(body).some(
-      (key) => !["operationKey", "source", "options"].includes(key),
+      (key) =>
+        ![
+          "operationKey",
+          "source",
+          "options",
+          "contractVersion",
+          "variant",
+        ].includes(key),
     ) ||
     typeof body.operationKey !== "string" ||
     !body.operationKey.trim() ||
@@ -116,6 +142,18 @@ function parseStart(body: unknown): {
     throw invalid("ArtifactRef 无效");
   }
   assertJson(body.options ?? {});
+  const hasVersion = body.contractVersion !== undefined;
+  const hasVariant = body.variant !== undefined;
+  if (
+    hasVersion !== hasVariant ||
+    (hasVersion &&
+      (body.contractVersion !== 2 ||
+        !["normalize", "transcribe", "translate"].includes(
+          String(body.variant),
+        )))
+  ) {
+    throw invalid("Speech V2 contractVersion 与 variant 无效");
+  }
   return {
     operationKey: body.operationKey,
     source: {
@@ -126,6 +164,12 @@ function parseStart(body: unknown): {
       expiresAt: typeof source.expiresAt === "string" ? source.expiresAt : "",
     },
     options: (body.options ?? {}) as ModuleAiJsonValue,
+    contract: hasVersion
+      ? {
+          contractVersion: 2,
+          variant: body.variant as "normalize" | "transcribe" | "translate",
+        }
+      : {},
   };
 }
 

package/template/apps/server/src/startup-finalization.ts

@@ -0,0 +1,52 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { InitializedModuleHosts } from "./module-host.js";
+import { validateInstalledRuntime } from "./module-runtime-validation.js";
+import {
+  listenPlatformServer,
+  logServerStartup,
+} from "./platform-http-runtime.js";
+import { installPlatformShutdown } from "./startup-shutdown.js";
+
+export function finalizePlatformStartup(input: {
+  app: Parameters<typeof listenPlatformServer>[0];
+  modules: ModuleManifest[];
+  hosts: InitializedModuleHosts;
+  tasks?: readonly { key: string }[];
+  tools?: ReadonlyMap<string, unknown>;
+  providers?: readonly string[];
+  schedulerWorker?: { start(): void; stop(): void };
+  disposeAgentRuntime?: () => Promise<unknown> | unknown;
+  logger: Parameters<typeof logServerStartup>[0] & {
+    error(fields: Record<string, unknown>, message: string): void;
+  };
+  featureSync: Parameters<typeof logServerStartup>[1];
+  persistenceEnabled: boolean;
+}): void {
+  validateInstalledRuntime({
+    modules: input.modules,
+    routes: input.app.routes,
+    tasks: input.tasks ?? [],
+    tools: input.tools ?? new Map(),
+    providers: input.providers ?? [],
+    hosts: input.hosts,
+  });
+  if (process.argv.includes("--validate-module-composition")) return;
+  const port = listenPlatformServer(input.app);
+  input.schedulerWorker?.start();
+  installPlatformShutdown({
+    stopHttp: () => input.app.stop(true),
+    stopScheduler: () => input.schedulerWorker?.stop(),
+    disposeAgentRuntime: input.disposeAgentRuntime,
+    onError: () =>
+      input.logger.error(
+        { event: "platform.shutdown.failed" },
+        "平台退出清理失败",
+      ),
+  });
+  logServerStartup(
+    input.logger,
+    input.featureSync,
+    input.persistenceEnabled,
+    port,
+  );
+}

package/template/apps/server/src/startup-preflight.ts

@@ -1,6 +1,7 @@
 import type { ModuleUploadPolicy } from "@southwind-ai/server-sdk";
 import { prepareInstalledServerModules } from "./module-preflight.js";
 import { createPlatformBootstrap } from "./platform-bootstrap.js";
+import { validateCompositionBeforeStartup } from "./startup-composition-validation.js";
 // @windy-module system.storage begin
 import { createPlatformUploadPolicies } from "./storage/runtime.js";
 // @windy-module system.storage end
@@ -9,6 +10,7 @@ import { createPlatformUploadPolicies } from "./storage/runtime.js";
  * 在恢复审计队列、执行迁移或写入目录前，完成项目装配、Host 与 attachment 门禁。
  */
 export async function createPreparedPlatformBootstrap() {
+  validateCompositionBeforeStartup();
   const bootstrap = createPlatformBootstrap();
   const baseUploadPolicies: ModuleUploadPolicy[] = [
     // @windy-module system.storage begin

package/template/apps/server/src/startup-shutdown.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "bun:test";
+import {
+  installPlatformShutdown,
+  type ShutdownProcess,
+} from "./startup-shutdown.js";
+
+describe("platform shutdown", () => {
+  it("stops scheduler, HTTP, and Agent runtime before exiting", async () => {
+    const target = new FakeShutdownProcess();
+    const events: string[] = [];
+    installPlatformShutdown({
+      target,
+      stopScheduler: () => events.push("scheduler"),
+      stopHttp: async () => events.push("http"),
+      disposeAgentRuntime: async () => events.push("agent"),
+    });
+
+    target.emit("SIGTERM");
+    await target.exited;
+
+    expect(events.sort()).toEqual(["agent", "http", "scheduler"]);
+    expect(target.exitCode).toBe(0);
+    expect(target.listeners.size).toBe(0);
+  });
+
+  it("reports cleanup failures and exits non-zero", async () => {
+    const target = new FakeShutdownProcess();
+    const failure = new Error("stop failed");
+    const errors: unknown[] = [];
+    const installed = installPlatformShutdown({
+      target,
+      stopHttp: () => {
+        throw failure;
+      },
+      onError: (error) => errors.push(error),
+    });
+
+    await installed.shutdown();
+
+    expect(errors).toEqual([failure]);
+    expect(target.exitCode).toBe(1);
+  });
+});
+
+class FakeShutdownProcess implements ShutdownProcess {
+  readonly listeners = new Map<string, () => void>();
+  exitCode?: number;
+  private resolveExit!: () => void;
+  readonly exited = new Promise<void>(
+    (resolve) => (this.resolveExit = resolve),
+  );
+
+  once(signal: string, listener: () => void): void {
+    this.listeners.set(signal, listener);
+  }
+
+  off(signal: string, listener: () => void): void {
+    if (this.listeners.get(signal) === listener) this.listeners.delete(signal);
+  }
+
+  exit(code?: number): void {
+    this.exitCode = code;
+    this.resolveExit();
+  }
+
+  emit(signal: string): void {
+    this.listeners.get(signal)?.();
+  }
+}

package/template/apps/server/src/startup-shutdown.ts

@@ -0,0 +1,61 @@
+type ShutdownSignal = "SIGINT" | "SIGTERM";
+
+export interface ShutdownProcess {
+  once(signal: ShutdownSignal, listener: () => void): unknown;
+  off(signal: ShutdownSignal, listener: () => void): unknown;
+  exit(code?: number): never | void;
+}
+
+export function installPlatformShutdown(input: {
+  stopHttp(): Promise<unknown> | unknown;
+  stopScheduler?(): Promise<unknown> | unknown;
+  disposeAgentRuntime?(): Promise<unknown> | unknown;
+  onError?(error: unknown): void;
+  target?: ShutdownProcess;
+}): { shutdown(): Promise<void>; uninstall(): void } {
+  const target = input.target ?? process;
+  let pending: Promise<void> | undefined;
+  const uninstall = () => {
+    target.off("SIGINT", onSignal);
+    target.off("SIGTERM", onSignal);
+  };
+  const shutdown = () => {
+    if (pending) return pending;
+    uninstall();
+    pending = settleShutdown(input).then((failed) =>
+      target.exit(failed ? 1 : 0),
+    );
+    return pending;
+  };
+  const onSignal = () => void shutdown();
+  target.once("SIGINT", onSignal);
+  target.once("SIGTERM", onSignal);
+  return { shutdown, uninstall };
+}
+
+async function settleShutdown(input: {
+  stopHttp(): Promise<unknown> | unknown;
+  stopScheduler?(): Promise<unknown> | unknown;
+  disposeAgentRuntime?(): Promise<unknown> | unknown;
+  onError?(error: unknown): void;
+}): Promise<boolean> {
+  const actions = [
+    () => input.stopScheduler?.(),
+    () => input.stopHttp(),
+    () => input.disposeAgentRuntime?.(),
+  ];
+  const results = await Promise.allSettled(
+    actions.map((action) => Promise.resolve().then(action)),
+  );
+  let failed = false;
+  for (const result of results) {
+    if (result.status !== "rejected") continue;
+    failed = true;
+    try {
+      input.onError?.(result.reason);
+    } catch {
+      // Exiting must not depend on the logger remaining available.
+    }
+  }
+  return failed;
+}

package/template/apps/server/src/storage/drizzle-upload-purge.ts

@@ -0,0 +1,61 @@
+import {
+  fileMetadata,
+  fileUploadParts,
+  fileUploadSessions,
+} from "@southwind-ai/database";
+import { and, eq, notExists } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+
+export async function beginDrizzleCompletedUploadPurge(
+  db: NodePgDatabase,
+  id: string,
+  ownerId: string,
+  fileId: string,
+  updatedAt: string,
+) {
+  const rows = await db
+    .update(fileUploadSessions)
+    .set({ status: "aborting", updatedAt: new Date(updatedAt) })
+    .where(
+      and(
+        eq(fileUploadSessions.id, id),
+        eq(fileUploadSessions.ownerId, ownerId),
+        eq(fileUploadSessions.fileId, fileId),
+        eq(fileUploadSessions.status, "completed"),
+      ),
+    )
+    .returning({ id: fileUploadSessions.id });
+  return rows.length === 1;
+}
+
+export async function deleteDrizzlePurgedUpload(
+  db: NodePgDatabase,
+  id: string,
+  ownerId: string,
+  fileId: string,
+) {
+  const rows = await db
+    .delete(fileUploadSessions)
+    .where(
+      and(
+        eq(fileUploadSessions.id, id),
+        eq(fileUploadSessions.ownerId, ownerId),
+        eq(fileUploadSessions.fileId, fileId),
+        eq(fileUploadSessions.status, "aborting"),
+        notExists(
+          db
+            .select({ sessionId: fileUploadParts.sessionId })
+            .from(fileUploadParts)
+            .where(eq(fileUploadParts.sessionId, id)),
+        ),
+        notExists(
+          db
+            .select({ id: fileMetadata.id })
+            .from(fileMetadata)
+            .where(eq(fileMetadata.id, fileId)),
+        ),
+      ),
+    )
+    .returning({ id: fileUploadSessions.id });
+  return rows.length === 1;
+}

package/template/apps/server/src/storage/drizzle-upload-references.ts

@@ -0,0 +1,23 @@
+import {
+  fileMetadata,
+  fileUploadParts,
+  fileUploadSessions,
+} from "@southwind-ai/database";
+import { artifactRef } from "@southwind-ai/storage";
+import { eq, inArray } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+
+export async function listDrizzleUploadArtifactRefs(db: NodePgDatabase) {
+  const [partRows, fileRows] = await Promise.all([
+    db
+      .select({ artifactRef: fileUploadParts.artifactRef })
+      .from(fileUploadParts)
+      .innerJoin(
+        fileUploadSessions,
+        eq(fileUploadSessions.id, fileUploadParts.sessionId),
+      )
+      .where(inArray(fileUploadSessions.status, ["uploading", "aborting"])),
+    db.select({ artifactRef: fileMetadata.artifactRef }).from(fileMetadata),
+  ]);
+  return [...partRows, ...fileRows].map((row) => artifactRef(row.artifactRef));
+}

package/template/apps/server/src/storage/drizzle-upload-repository.integration.test.ts

@@ -2,7 +2,9 @@ import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { createHash } from "node:crypto";
 import { resolve } from "node:path";
 import {
+  artifactRef,
   MemoryBlobStore,
+  sha256ContentHash,
   UploadService,
   type UploadPolicy,
 } from "@southwind-ai/storage";
@@ -53,6 +55,10 @@ describePostgres("PostgreSQL upload repository", () => {
     const session = await service.create({
       ownerId: "user_pg",
       purpose: "bulk-data",
+      authorizationBinding: {
+        moduleName: "evidence",
+        scopeHash: "a".repeat(64),
+      },
       filename: "source.ndjson",
       mimeType: "application/x-ndjson",
       expectedByteSize: body.byteLength,
@@ -83,6 +89,10 @@ describePostgres("PostgreSQL upload repository", () => {
       receivedByteSize: body.byteLength,
       nextPartNumber: 1,
       status: "uploading",
+      authorizationBinding: {
+        moduleName: "evidence",
+        scopeHash: "a".repeat(64),
+      },
     });
     const file = await uploadService(restartedRepository).complete(
       session.id,
@@ -103,6 +113,99 @@ describePostgres("PostgreSQL upload repository", () => {
     });
     expect(await restartedRepository.getFile(file.id)).toBeUndefined();
   });
+
+  test("数据库拒绝两种半绑定上传会话", async () => {
+    const required = [
+      "id",
+      "owner_id",
+      "purpose",
+      "filename",
+      "extension",
+      "mime_type",
+      "expected_byte_size",
+      "status",
+      "expires_at",
+    ].join(",");
+    const values =
+      "values ($1, 'owner', 'bulk-data', 'a.txt', 'txt', 'text/plain', 1, 'uploading', now() + interval '1 hour', $2)";
+    await expect(
+      pool.query(
+        `insert into file_upload_sessions (${required}, module_name) ${values}`,
+        ["upload_11111111111111111111111111111111", "evidence"],
+      ),
+    ).rejects.toMatchObject({ code: "23514" });
+    await expect(
+      pool.query(
+        `insert into file_upload_sessions (${required}, authorization_scope_hash) ${values}`,
+        ["upload_22222222222222222222222222222222", "a".repeat(64)],
+      ),
+    ).rejects.toMatchObject({ code: "23514" });
+  });
+
+  test("真实 PostgreSQL 线性化 complete/cleanup 并可在重启后接管 aborting", async () => {
+    await pool.query(
+      "truncate table file_upload_parts, file_metadata, file_upload_sessions",
+    );
+    currentTime = new Date("2026-07-31T00:00:00.000Z");
+    const repository = new DrizzleUploadRepository(drizzle(pool));
+    const session = await uploadService(repository).create({
+      ownerId: "user_pg",
+      purpose: "bulk-data",
+      filename: "empty.ndjson",
+      mimeType: "application/x-ndjson",
+      expectedByteSize: 0,
+    });
+    const file = {
+      id: "file_11111111111111111111111111111111",
+      ownerId: "user_pg",
+      purpose: "bulk-data",
+      filename: "empty.ndjson",
+      extension: "ndjson",
+      mimeType: "application/x-ndjson",
+      artifactRef: artifactRef("blob_11111111111111111111111111111111"),
+      byteSize: 0,
+      contentHash: sha256ContentHash(digest(new Uint8Array())),
+      createdAt: "2026-07-31T00:02:00.000Z",
+    };
+    const cleanupNow = "2026-07-31T00:02:00.000Z";
+    const [completed, claimed] = await Promise.all([
+      repository.completeSession(session.id, 0, file, cleanupNow),
+      repository.claimExpiredSession(session.id, cleanupNow),
+    ]);
+    expect(Number(completed) + Number(claimed)).toBe(1);
+    if (completed) {
+      expect(await repository.deleteClaimedSession(session.id)).toBe(false);
+      expect(await repository.getFile(file.id)).toBeDefined();
+    } else {
+      expect(await repository.deleteClaimedSession(session.id)).toBe(true);
+      expect(await repository.getFile(file.id)).toBeUndefined();
+    }
+
+    currentTime = new Date("2026-07-31T01:00:00.000Z");
+    const aborting = await uploadService(repository).create({
+      ownerId: "user_pg",
+      purpose: "bulk-data",
+      filename: "aborting.ndjson",
+      mimeType: "application/x-ndjson",
+      expectedByteSize: 1,
+    });
+    expect(
+      await repository.beginAbortSession(
+        aborting.id,
+        "user_pg",
+        currentTime.toISOString(),
+      ),
+    ).toBe(true);
+    const restarted = new DrizzleUploadRepository(drizzle(pool));
+    const expiredAt = "2026-07-31T01:02:00.000Z";
+    expect(await restarted.claimExpiredSession(aborting.id, expiredAt)).toBe(
+      true,
+    );
+    expect(await restarted.deleteClaimedSession(aborting.id)).toBe(true);
+    expect(
+      await repository.finalizeAbortSession(aborting.id, "user_pg", expiredAt),
+    ).toBe(false);
+  });
 });
 
 function uploadService(repository: DrizzleUploadRepository) {