create-windy 0.5.2 → 0.6.1

package/template/apps/server/src/embedding/facade.ts

@@ -1,17 +1,10 @@
 import { randomUUIDv7 } from "bun";
-import type {
-  ModuleAiOperationDefinition,
-  ModuleManifest,
-} from "@southwind-ai/modules";
+import type { ModuleManifest } from "@southwind-ai/modules";
 import { resolveProviderEgress } from "@southwind-ai/modules";
-import type {
-  ModuleAiJsonValue,
-  ModuleAiOperationHandlerRegistration,
-} from "@southwind-ai/server-sdk";
-import { evaluateAccessGuards } from "../access-guards.js";
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
 import type { AiArtifactRuntime } from "../ai-artifact/runtime.js";
 import { scopedRuntimeIdempotencyKey } from "../agent/idempotency-key.js";
-import { auditActor, type RequestGuardContext } from "../guards.js";
+import type { RequestGuardContext } from "../guards.js";
 import type { InitializedModuleHosts } from "../module-host.js";
 import { toModuleActor } from "../module-host.js";
 import { findFeature } from "../route-guards.js";
@@ -28,16 +21,28 @@ import {
   runtimeItems,
   type EmbeddingFacadeItem,
 } from "./input.js";
+import { EmbeddingRunAuthorizations } from "./run-authorization.js";
+import { recordEmbeddingAudit } from "./audit.js";
+import { embeddingRunFingerprint } from "./run-fingerprint.js";
+import { observeEmbeddingTerminal } from "./terminal-observer.js";
+import { authorizeEmbeddingOperation } from "./operation-authorization.js";
+import { runArtifact, unavailableArtifact } from "./run-artifact.js";
+import {
+  embeddingErrorStatus,
+  type RegisteredEmbeddingOperation,
+} from "./facade-types.js";
+import { type ReadinessPort, requireReadiness } from "./readiness-admission.js";
 
 export class EmbeddingFacade {
   readonly #operations: Map<string, RegisteredEmbeddingOperation>;
-
   constructor(
     modules: readonly ModuleManifest[],
     hosts: InitializedModuleHosts,
     private readonly runtime: ReturnType<typeof createServerRuntime>,
     private readonly remote: EmbeddingRuntimePort,
     private readonly artifacts: AiArtifactRuntime,
+    private readonly runs: EmbeddingRunAuthorizations,
+    private readonly readiness: ReadinessPort,
   ) {
     const handlers = new Map(
       hosts.aiOperationHandlers.map(({ registration, moduleName }) => [
@@ -64,7 +69,6 @@ export class EmbeddingFacade {
       ),
     );
   }
-
   async embed(
     operationKey: string,
     items: readonly EmbeddingFacadeItem[],
@@ -73,67 +77,16 @@ export class EmbeddingFacade {
     context: RequestGuardContext,
     signal: AbortSignal,
   ): Promise<EmbeddingBatchResponse> {
-    const operation = this.#operations.get(operationKey);
-    if (!operation?.registration?.prepareEmbedding || !operation.moduleName) {
-      throw new EmbeddingFacadeError(
-        "OPERATION_NOT_FOUND",
-        "Embedding Operation 不存在",
-        404,
-      );
-    }
-    await this.authorize(operation, context);
-    const governed = governEmbeddingInput(items, options, operation.definition);
-    const plan = await operation.registration.prepareEmbedding(governed, {
-      actor: toModuleActor(context.actor),
-      requestId: context.requestId,
-    });
-    const prepared = await runtimeItems(
+    const prepared = await this.prepare(
+      operationKey,
       items,
-      governed,
-      operation.definition,
-      operation.moduleName,
-      this.artifacts,
+      options,
       context,
       signal,
     );
-    const maxUnits = operation.definition.limits.maxUnits;
-    if (!maxUnits) {
-      throw new EmbeddingFacadeError(
-        "INVALID_CONFIGURATION",
-        "Embedding Operation 未声明批量上限",
-        503,
-      );
-    }
     try {
       const result = await this.remote.embed(
-        {
-          kind: "embedding",
-          operationKey,
-          items: prepared,
-          options: plan.options ?? governedEmbeddingOptions(governed),
-          inputModalities: operation.definition.inputModalities ?? ["text"],
-          requiredCapabilities: operation.definition.requiredCapabilities,
-          dataClassification: operation.definition.dataClassification,
-          limits: {
-            maxDurationSeconds: operation.definition.limits.maxDurationSeconds,
-            maxInputBytes: operation.definition.limits.maxInputBytes,
-            maxOutputBytes: operation.definition.limits.maxOutputBytes,
-            maxUnits,
-            ...(operation.definition.limits.maxArtifacts
-              ? {
-                  maxArtifacts: operation.definition.limits.maxArtifacts,
-                }
-              : {}),
-            ...(operation.definition.limits.maxPixelsPerArtifact
-              ? {
-                  maxPixelsPerArtifact:
-                    operation.definition.limits.maxPixelsPerArtifact,
-                }
-              : {}),
-          },
-          providerEgress: resolveProviderEgress(operation.definition),
-          providerDataPolicy: operation.definition.providerDataPolicy,
-        },
+        prepared.request,
         scopedRuntimeIdempotencyKey(
           context.actor.id,
           operationKey,
@@ -141,77 +94,257 @@ export class EmbeddingFacade {
         ),
         signal,
       );
-      this.audit(operation, context, result, prepared);
+      recordEmbeddingAudit({
+        runtime: this.runtime,
+        operation: prepared.operation,
+        context,
+        result,
+        itemCount: prepared.items.length,
+      });
       return result;
     } catch (error) {
       if (error instanceof EmbeddingRuntimeError) {
         throw new EmbeddingFacadeError(
           error.code,
           error.message,
-          errorStatus(error.code),
+          embeddingErrorStatus(error.code),
         );
       }
       throw error;
     }
   }
-
-  private async authorize(
-    operation: RegisteredEmbeddingOperation,
+  async start(
+    operationKey: string,
+    items: readonly EmbeddingFacadeItem[],
+    options: ModuleAiJsonValue,
+    idempotencyKey: string,
     context: RequestGuardContext,
+    signal: AbortSignal,
   ) {
-    const access = await evaluateAccessGuards(this.runtime, context, {
-      permission: { permissionKey: operation.definition.permissionKey },
-      feature: operation.feature,
+    const prepared = await this.prepare(
+      operationKey,
+      items,
+      options,
+      context,
+      signal,
+    );
+    const fingerprint = await embeddingRunFingerprint(
+      operationKey,
+      prepared.items,
+      prepared.request.options,
+      prepared.request.readinessPin,
+    );
+    const binding = await this.runs.issue({
+      operationKey,
+      moduleName: prepared.moduleName,
+      idempotencyKey,
+      fingerprint,
+      artifactRefs: prepared.items.flatMap(runArtifact),
+      context,
     });
-    if (!access.decision.allowed) {
+    const runId = binding.runId ?? `embedding_${randomUUIDv7()}`;
+    await this.runs.bind(binding, runId);
+    try {
+      const created = await this.remote.start(
+        prepared.request,
+        scopedRuntimeIdempotencyKey(
+          context.actor.id,
+          operationKey,
+          idempotencyKey,
+        ),
+        runId,
+        signal,
+      );
+      if (created.runId !== runId)
+        throw new EmbeddingFacadeError(
+          "RUNTIME_UNAVAILABLE",
+          "Embedding Runtime 返回了未绑定的 Run",
+          503,
+        );
+      return {
+        runId,
+        status: "accepted" as const,
+        eventsUrl: `/api/embeddings/runs/${created.runId}/events`,
+      };
+    } catch (error) {
+      if (error instanceof EmbeddingRuntimeError)
+        throw new EmbeddingFacadeError(
+          error.code,
+          error.message,
+          embeddingErrorStatus(error.code),
+        );
+      throw error;
+    }
+  }
+  async authorizeRun(runId: string, context: RequestGuardContext) {
+    const binding = await this.runs.require(runId, context);
+    const operation = this.#operations.get(binding.operationKey);
+    if (!operation || operation.moduleName !== binding.moduleName)
       throw new EmbeddingFacadeError(
         "FORBIDDEN",
-        "无权执行 Embedding Operation",
+        "Embedding Run 不存在或不可访问",
         403,
       );
-    }
+    await authorizeEmbeddingOperation(this.runtime, operation, context);
+    return binding;
   }
-
-  private audit(
-    operation: RegisteredEmbeddingOperation,
+  async remoteResult(
+    runId: string,
     context: RequestGuardContext,
-    result: EmbeddingBatchResponse,
-    items: readonly { id: string }[],
+    signal: AbortSignal,
   ) {
-    this.runtime.auditSink.recordEvent({
-      id: randomUUIDv7(),
-      action: operation.definition.auditAction,
-      outcome: "success",
-      actor: auditActor(context),
-      target: {
-        type: "embedding-batch",
-        id: result.batchId,
-        label: operation.definition.key,
-      },
+    const binding = await this.authorizeRun(runId, context);
+    const result = await this.remote.result(runId, signal);
+    await this.auditTerminal(binding, context, "completed", result);
+    return result;
+  }
+  async remoteEvents(
+    runId: string,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ) {
+    const binding = await this.authorizeRun(runId, context);
+    const response = await this.remote.events(runId, signal);
+    void observeEmbeddingTerminal({
+      response: response.clone(),
+      binding,
+      context,
+      signal,
+      remote: this.remote,
+      audit: (status, result) =>
+        this.auditTerminal(binding, context, status, result),
+    });
+    return response;
+  }
+  async remoteCancel(
+    runId: string,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ) {
+    const binding = await this.authorizeRun(runId, context);
+    await this.remote.cancel(runId, undefined, signal);
+    await this.auditTerminal(binding, context, "cancelled");
+  }
+  async openRunArtifact(runId: string, itemId: string, signal: AbortSignal) {
+    const initial = await this.runs.find(runId);
+    if (!initial) throw unavailableArtifact();
+    const context = await this.artifacts.currentGuardContext(
+      initial.actorId,
+      signal,
+    );
+    const binding = await this.runs.require(runId, context);
+    const operation = this.#operations.get(binding.operationKey);
+    if (!operation || operation.moduleName !== binding.moduleName)
+      throw unavailableArtifact();
+    await authorizeEmbeddingOperation(this.runtime, operation, context);
+    const artifact = binding.artifactRefs.find(
+      (item) => item.itemId === itemId,
+    );
+    if (!artifact) throw unavailableArtifact();
+    return this.artifacts.openRunBound(
+      { ...artifact, expiresAt: "" },
+      binding.actorId,
+      binding.moduleName,
+      signal,
+    );
+  }
+  private async prepare(
+    operationKey: string,
+    items: readonly EmbeddingFacadeItem[],
+    options: ModuleAiJsonValue,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ) {
+    const operation = this.#operations.get(operationKey);
+    if (!operation?.registration?.prepareEmbedding || !operation.moduleName)
+      throw new EmbeddingFacadeError(
+        "OPERATION_NOT_FOUND",
+        "Embedding Operation 不存在",
+        404,
+      );
+    await authorizeEmbeddingOperation(this.runtime, operation, context);
+    const readinessPin = await requireReadiness(
+      this.readiness,
+      operation.definition,
+    );
+    const governed = governEmbeddingInput(items, options, operation.definition);
+    const plan = await operation.registration.prepareEmbedding(governed, {
+      actor: toModuleActor(context.actor),
       requestId: context.requestId,
-      metadata: {
-        itemCount: items.length,
-        deploymentAlias: result.metadata.deploymentAlias,
-        model: result.metadata.model,
-        version: result.metadata.version,
-        dimensions: result.metadata.dimensions,
-        normalized: result.metadata.normalized,
-      },
-      occurredAt: new Date().toISOString(),
     });
+    const prepared = await runtimeItems(
+      items,
+      governed,
+      operation.definition,
+      operation.moduleName,
+      this.artifacts,
+      context,
+      signal,
+    );
+    const maxUnits = operation.definition.limits.maxUnits;
+    if (!maxUnits)
+      throw new EmbeddingFacadeError(
+        "INVALID_CONFIGURATION",
+        "Embedding Operation 未声明批量上限",
+        503,
+      );
+    return {
+      operation,
+      moduleName: operation.moduleName,
+      items: prepared,
+      request: {
+        kind: "embedding" as const,
+        operationKey,
+        items: prepared,
+        options: plan.options ?? governedEmbeddingOptions(governed),
+        inputModalities: operation.definition.inputModalities ?? ["text"],
+        requiredCapabilities: operation.definition.requiredCapabilities,
+        dataClassification: operation.definition.dataClassification,
+        limits: {
+          maxDurationSeconds: operation.definition.limits.maxDurationSeconds,
+          maxInputBytes: operation.definition.limits.maxInputBytes,
+          maxOutputBytes: operation.definition.limits.maxOutputBytes,
+          maxUnits,
+          ...(operation.definition.limits.maxArtifacts
+            ? { maxArtifacts: operation.definition.limits.maxArtifacts }
+            : {}),
+          ...(operation.definition.limits.maxPixelsPerArtifact
+            ? {
+                maxPixelsPerArtifact:
+                  operation.definition.limits.maxPixelsPerArtifact,
+              }
+            : {}),
+        },
+        providerEgress: resolveProviderEgress(operation.definition),
+        providerDataPolicy: operation.definition.providerDataPolicy,
+        readinessPin,
+      },
+    };
   }
-}
-
-interface RegisteredEmbeddingOperation {
-  definition: ModuleAiOperationDefinition;
-  feature: ReturnType<typeof findFeature>;
-  registration?: ModuleAiOperationHandlerRegistration;
-  moduleName?: string;
-}
 
-function errorStatus(code: EmbeddingRuntimeError["code"]) {
-  if (code === "FORBIDDEN") return 403;
-  if (code === "RUN_CONFLICT") return 409;
-  if (code === "INVALID_INPUT" || code === "BUDGET_EXCEEDED") return 400;
-  return 503;
+  private async auditTerminal(
+    binding: Awaited<ReturnType<EmbeddingRunAuthorizations["require"]>>,
+    context: RequestGuardContext,
+    terminalStatus: "completed" | "failed" | "cancelled",
+    result?: EmbeddingBatchResponse,
+  ) {
+    const claimedAt = await this.runs.claimTerminalAudit(binding.runId!);
+    if (!claimedAt) return;
+    try {
+      const operation = this.#operations.get(binding.operationKey);
+      if (!operation) throw new Error("Embedding Operation 不存在");
+      recordEmbeddingAudit({
+        runtime: this.runtime,
+        operation,
+        context,
+        terminalStatus,
+        runId: binding.runId,
+        result,
+        itemCount: 0,
+      });
+    } catch (error) {
+      await this.runs.releaseTerminalAudit(binding.runId!, claimedAt);
+      throw error;
+    }
+  }
 }

package/template/apps/server/src/embedding/operation-authorization.ts

@@ -0,0 +1,23 @@
+import { evaluateAccessGuards } from "../access-guards.js";
+import type { RequestGuardContext } from "../guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import { EmbeddingFacadeError } from "./error.js";
+import type { RegisteredEmbeddingOperation } from "./facade-types.js";
+
+export async function authorizeEmbeddingOperation(
+  runtime: ReturnType<typeof createServerRuntime>,
+  operation: RegisteredEmbeddingOperation,
+  context: RequestGuardContext,
+) {
+  const access = await evaluateAccessGuards(runtime, context, {
+    permission: { permissionKey: operation.definition.permissionKey },
+    feature: operation.feature,
+  });
+  if (!access.decision.allowed) {
+    throw new EmbeddingFacadeError(
+      "FORBIDDEN",
+      "无权执行 Embedding Operation",
+      403,
+    );
+  }
+}

package/template/apps/server/src/embedding/readiness-admission.ts

@@ -0,0 +1,26 @@
+import type { ModuleAiOperationDefinition } from "@southwind-ai/modules";
+import type {
+  AiRuntimeDeploymentV1,
+  ModuleAiOperationReadinessPortV1,
+} from "@southwind-ai/server-sdk";
+import { EmbeddingFacadeError } from "./error.js";
+
+export type ReadinessPort = ModuleAiOperationReadinessPortV1;
+
+export async function requireReadiness(
+  readiness: ModuleAiOperationReadinessPortV1,
+  definition: ModuleAiOperationDefinition,
+): Promise<AiRuntimeDeploymentV1 | undefined> {
+  if (!definition.readiness) return undefined;
+  try {
+    const projected = await readiness.inspect({ operationKey: definition.key });
+    if (projected.status !== "ready") throw new Error("not ready");
+    return projected.deployment;
+  } catch {
+    throw new EmbeddingFacadeError(
+      "RUNTIME_UNAVAILABLE",
+      "Embedding Runtime 当前不可用",
+      503,
+    );
+  }
+}

package/template/apps/server/src/embedding/remote-runtime.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import { computeAiRuntimeOffersDigestV1 } from "@southwind-ai/server-sdk";
 import {
   RemoteEmbeddingRuntime,
   unavailableEmbeddingRuntime,
@@ -63,4 +64,106 @@ describe("RemoteEmbeddingRuntime", () => {
       unavailableEmbeddingRuntime.embed(operation, "batch-1"),
     ).rejects.toMatchObject({ code: "CAPABILITY_UNAVAILABLE" });
   });
+
+  test("durable start 仅接受 Server 预绑定的 Run ID", async () => {
+    const runtime = new RemoteEmbeddingRuntime({
+      baseUrl: "http://embedding.internal",
+      internalToken: "token",
+      fetch: async (_input, init) => {
+        expect(init?.headers).toMatchObject({
+          authorization: "Bearer token",
+          "idempotency-key": "run-key",
+          "x-embedding-run-id": "embedding_server_bound",
+        });
+        return Response.json({ runId: "embedding_server_bound" });
+      },
+    });
+    await expect(
+      runtime.start(operation, "run-key", "embedding_server_bound"),
+    ).resolves.toEqual({ runId: "embedding_server_bound" });
+  });
+
+  test("deployment pin 漂移时在创建远端 Run 前失败关闭", async () => {
+    const pin = embeddingPin();
+    let starts = 0;
+    const runtime = new RemoteEmbeddingRuntime({
+      baseUrl: "http://embedding.internal",
+      internalToken: "token",
+      fetch: async (input) => {
+        const url = String(input);
+        if (url.endsWith("/health/ready")) {
+          return Response.json(
+            readinessSnapshot(pin, `sha256:${"f".repeat(64)}`),
+          );
+        }
+        starts += 1;
+        return Response.json({ runId: "embedding_server_bound" });
+      },
+    });
+
+    await expect(
+      runtime.start(
+        { ...operation, readinessPin: pin },
+        "run-key",
+        "embedding_server_bound",
+      ),
+    ).rejects.toMatchObject({ code: "RUNTIME_UNAVAILABLE" });
+    expect(starts).toBe(0);
+  });
 });
+
+function embeddingPin() {
+  const offersDigest = computeAiRuntimeOffersDigestV1([embeddingOffer()]);
+  return {
+    key: "embedding.primary",
+    identity: "windy-deployment-v1_0f26eb34-f384-4ec9-98f3-caf8d582291f",
+    releaseDigest: `sha256:${"a".repeat(64)}` as const,
+    offersDigest,
+  };
+}
+
+function readinessSnapshot(
+  pin: ReturnType<typeof embeddingPin>,
+  offersDigest = pin.offersDigest,
+) {
+  const now = new Date();
+  const checkedAt = now.toISOString();
+  const validUntil = new Date(now.getTime() + 60_000).toISOString();
+  const deployment = { ...pin, offersDigest };
+  return {
+    schemaVersion: 1,
+    status: "ready",
+    configured: true,
+    runtimeKind: "embedding",
+    observedAt: checkedAt,
+    downstreamProbe: {
+      status: "passed",
+      checkedAt,
+      validUntil,
+      latencyMs: 1,
+      deploymentIdentity: pin.identity,
+      releaseDigest: pin.releaseDigest,
+      offersDigest,
+    },
+    deployment,
+    offers: [embeddingOffer()],
+    unavailableReasons: [],
+  };
+}
+
+function embeddingOffer() {
+  return {
+    variant: "text",
+    capabilities: ["embedding.text"],
+    inputModalities: ["text"] as const,
+    outputModalities: ["embedding"] as const,
+    limits: {
+      maxDurationSeconds: 30,
+      maxInputBytes: 1024,
+      maxOutputBytes: 1024,
+      maxUnits: 10,
+      maxConcurrentRuns: 1,
+      maxQueueDepth: 0,
+    },
+  };
+}