create-windy 0.6.0 → 0.6.1

package/template/apps/server/src/embedding/facade-readiness.test.ts

@@ -0,0 +1,307 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import { featureKey } from "@southwind-ai/shared";
+import type {
+  AiRuntimeDeploymentV1,
+  ModuleAiJsonValue,
+  ModuleAiOperationReadinessV1,
+} from "@southwind-ai/server-sdk";
+import { buildScopeContext } from "../data-access/context.js";
+import { createRequestGuardContext } from "../guards.js";
+import { initializeModuleHosts } from "../module-host.js";
+import { createServerRuntime } from "../runtime.js";
+import type { EmbeddingRuntimeOperation } from "./contracts.js";
+import { EmbeddingFacade } from "./facade.js";
+
+const operationKey = "analysis.embedding.image";
+const deployment: AiRuntimeDeploymentV1 = {
+  key: "embedding.primary",
+  identity: "windy-deployment-v1_0f26eb34-f384-4ec9-98f3-caf8d582291f",
+  releaseDigest: `sha256:${"a".repeat(64)}`,
+  offersDigest: `sha256:${"b".repeat(64)}`,
+};
+
+describe("EmbeddingFacade readiness admission", () => {
+  test("unavailable 与 probe 异常在业务 prepare、Artifact、Run 前稳定失败关闭", async () => {
+    for (const inspect of [
+      async () => unavailableProjection(),
+      async () => {
+        throw new Error("provider secret");
+      },
+    ]) {
+      const fixture = await createFixture(true, inspect);
+
+      await expect(fixture.start()).rejects.toMatchObject({
+        code: "RUNTIME_UNAVAILABLE",
+        message: "Embedding Runtime 当前不可用",
+        status: 503,
+      });
+      expect(fixture.calls).toEqual({
+        readiness: 1,
+        prepare: 0,
+        artifact: 0,
+        run: 0,
+        remote: 0,
+      });
+    }
+  });
+
+  test("ready projection 固定 deployment pin 后才创建 Artifact 与 Run", async () => {
+    const fixture = await createFixture(true, async () => readyProjection());
+
+    await expect(fixture.start()).resolves.toMatchObject({
+      runId: "embedding_server_bound",
+      status: "accepted",
+    });
+    expect(fixture.calls).toEqual({
+      readiness: 1,
+      prepare: 1,
+      artifact: 1,
+      run: 1,
+      remote: 1,
+    });
+    expect(fixture.request?.readinessPin).toEqual(deployment);
+  });
+
+  test("未声明 readiness 的旧 Operation 保留兼容路径", async () => {
+    const fixture = await createFixture(false, async () => {
+      throw new Error("legacy operation must not inspect V1");
+    });
+
+    await expect(fixture.start()).resolves.toMatchObject({
+      runId: "embedding_server_bound",
+    });
+    expect(fixture.calls.readiness).toBe(0);
+    expect(fixture.request?.readinessPin).toBeUndefined();
+  });
+});
+
+async function createFixture(
+  withReadiness: boolean,
+  inspect: () => Promise<ModuleAiOperationReadinessV1>,
+) {
+  const module = embeddingModule(withReadiness);
+  const calls = { readiness: 0, prepare: 0, artifact: 0, run: 0, remote: 0 };
+  let request: EmbeddingRuntimeOperation | undefined;
+  const hosts = await initializeModuleHosts({
+    modules: [module],
+    installations: [
+      {
+        manifest: module,
+        setup(host) {
+          host.registerAiOperationHandlers([
+            {
+              operationKey,
+              prepareEmbedding: (input: ModuleAiJsonValue) => {
+                calls.prepare += 1;
+                return { options: input };
+              },
+            },
+          ]);
+        },
+      },
+    ],
+  });
+  const facade = new EmbeddingFacade(
+    [module],
+    hosts,
+    createServerRuntime({}, { featureCatalog: module.features }),
+    {
+      async start(value: EmbeddingRuntimeOperation) {
+        calls.remote += 1;
+        request = value;
+        return { runId: "embedding_server_bound" };
+      },
+    } as never,
+    {
+      async rotate() {
+        calls.artifact += 1;
+        return artifact("rotated");
+      },
+    } as never,
+    {
+      async issue() {
+        calls.run += 1;
+        return { runId: "embedding_server_bound" };
+      },
+      async bind() {},
+    } as never,
+    {
+      async inspect() {
+        calls.readiness += 1;
+        return inspect();
+      },
+    },
+  );
+  return {
+    calls,
+    get request() {
+      return request;
+    },
+    start: () =>
+      facade.start(
+        operationKey,
+        [{ id: "image", source: artifact("submitted") }],
+        {},
+        "embedding-1",
+        guardContext(),
+        AbortSignal.timeout(1_000),
+      ),
+  };
+}
+
+function embeddingModule(withReadiness: boolean): ModuleManifest {
+  return {
+    name: "analysis",
+    version: "0.1.0",
+    label: "分析",
+    description: "分析",
+    menus: [],
+    adminRoutes: [],
+    permissions: [
+      {
+        key: "analysis.embedding.execute",
+        label: "向量化",
+        module: "analysis",
+        moduleLabel: "分析",
+        resource: "embedding",
+        resourceLabel: "向量化",
+        action: "manage",
+      },
+    ],
+    apiPermissions: [],
+    features: [
+      {
+        key: featureKey("analysis.embedding"),
+        label: "向量化",
+        module: "analysis",
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    migrations: [],
+    schemaExports: [],
+    jsonSchemas: [
+      { key: "analysis.embedding.input.v1", schema: { type: "object" } },
+      { key: "analysis.embedding.output.v1", schema: { type: "object" } },
+    ],
+    tasks: [],
+    tools: [],
+    aiOperations: [
+      {
+        key: operationKey,
+        kind: "embedding",
+        featureKey: "analysis.embedding",
+        permissionKey: "analysis.embedding.execute",
+        auditAction: "analysis.embedding.execute",
+        inputSchemaKey: "analysis.embedding.input.v1",
+        outputSchemaKey: "analysis.embedding.output.v1",
+        inputModalities: ["image"],
+        ...(withReadiness
+          ? {
+              readiness: {
+                contractVersion: 1 as const,
+                variant: "image",
+                inputModalities: ["image"] as const,
+                outputModalities: ["embedding"] as const,
+                expectedDeployment: deployment,
+                minConcurrentRuns: 1,
+                minQueueDepth: 0,
+              },
+            }
+          : {}),
+        requiredCapabilities: ["embedding.image"],
+        allowedToolKeys: [],
+        dataClassification: "sensitive",
+        execution: "background",
+        providerEgress: { mode: "forbidden" },
+        limits: {
+          maxDurationSeconds: 60,
+          maxInputBytes: 4_096,
+          maxOutputBytes: 4_096,
+          maxUnits: 1,
+          maxArtifacts: 1,
+          maxPixelsPerArtifact: 1_000,
+        },
+      },
+    ],
+    providers: [],
+    auditActions: ["analysis.embedding.execute"],
+  };
+}
+
+function guardContext() {
+  return createRequestGuardContext(new Request("http://localhost"), {
+    resolveActor: () => ({
+      id: "actor-1",
+      type: "user",
+      name: "测试用户",
+      roleCodes: ["analyst"],
+      permissionKeys: ["analysis.embedding.execute"],
+      scopeContext: buildScopeContext("actor-1", undefined, [
+        {
+          id: "analyst",
+          code: "analyst",
+          dataScope: "self",
+          departmentIds: [],
+        },
+      ]),
+    }),
+    resolveLicense: () => ({ status: "valid" }),
+  });
+}
+
+function artifact(value: string) {
+  return {
+    value,
+    mediaType: "image/png",
+    byteSize: 128,
+    sha256: "c".repeat(64),
+    expiresAt: "2030-01-01T00:00:00.000Z",
+  };
+}
+
+function readyProjection(): ModuleAiOperationReadinessV1 {
+  return {
+    schemaVersion: 1,
+    operationKey,
+    runtimeKind: "embedding",
+    observedAt: new Date().toISOString(),
+    status: "ready",
+    validUntil: new Date(Date.now() + 60_000).toISOString(),
+    deployment,
+    offers: [
+      {
+        variant: "image",
+        capabilities: ["embedding.image"],
+        inputModalities: ["image"],
+        outputModalities: ["embedding"],
+        limits: {
+          maxDurationSeconds: 60,
+          maxInputBytes: 4_096,
+          maxOutputBytes: 4_096,
+          maxUnits: 1,
+          maxArtifacts: 1,
+          maxPixelsPerArtifact: 1_000,
+          maxConcurrentRuns: 1,
+          maxQueueDepth: 0,
+        },
+      },
+    ],
+    unavailableReasons: [],
+  };
+}
+
+function unavailableProjection(): ModuleAiOperationReadinessV1 {
+  return {
+    schemaVersion: 1,
+    operationKey,
+    runtimeKind: "embedding",
+    observedAt: new Date().toISOString(),
+    status: "unavailable",
+    deployment: null,
+    offers: [],
+    unavailableReasons: [{ code: "DOWNSTREAM_PROBE_FAILED", retryable: true }],
+  };
+}

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

@@ -31,10 +31,10 @@ 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,
@@ -42,6 +42,7 @@ export class EmbeddingFacade {
     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 }) => [
@@ -68,7 +69,6 @@ export class EmbeddingFacade {
       ),
     );
   }
-
   async embed(
     operationKey: string,
     items: readonly EmbeddingFacadeItem[],
@@ -113,7 +113,6 @@ export class EmbeddingFacade {
       throw error;
     }
   }
-
   async start(
     operationKey: string,
     items: readonly EmbeddingFacadeItem[],
@@ -133,6 +132,7 @@ export class EmbeddingFacade {
       operationKey,
       prepared.items,
       prepared.request.options,
+      prepared.request.readinessPin,
     );
     const binding = await this.runs.issue({
       operationKey,
@@ -176,7 +176,6 @@ export class EmbeddingFacade {
       throw error;
     }
   }
-
   async authorizeRun(runId: string, context: RequestGuardContext) {
     const binding = await this.runs.require(runId, context);
     const operation = this.#operations.get(binding.operationKey);
@@ -226,7 +225,6 @@ export class EmbeddingFacade {
     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();
@@ -250,7 +248,6 @@ export class EmbeddingFacade {
       signal,
     );
   }
-
   private async prepare(
     operationKey: string,
     items: readonly EmbeddingFacadeItem[],
@@ -266,6 +263,10 @@ export class EmbeddingFacade {
         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),
@@ -316,6 +317,7 @@ export class EmbeddingFacade {
         },
         providerEgress: resolveProviderEgress(operation.definition),
         providerDataPolicy: operation.definition.providerDataPolicy,
+        readinessPin,
       },
     };
   }

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,
@@ -81,4 +82,88 @@ describe("RemoteEmbeddingRuntime", () => {
       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,
+    },
+  };
+}

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

@@ -4,6 +4,7 @@ import {
   type EmbeddingRuntimeOperation,
   type EmbeddingRuntimePort,
 } from "./contracts.js";
+import { assertAiRuntimeReadinessPin } from "../ai-runtime-readiness/deployment-pin.js";
 
 export class RemoteEmbeddingRuntime implements EmbeddingRuntimePort {
   readonly #baseUrl: string;
@@ -32,6 +33,7 @@ export class RemoteEmbeddingRuntime implements EmbeddingRuntimePort {
     idempotencyKey: string,
     signal?: AbortSignal,
   ): Promise<EmbeddingBatchResponse> {
+    await this.assertReadiness(request, signal);
     const response = await this.request("/api/embeddings", {
       method: "POST",
       headers: {
@@ -55,6 +57,7 @@ export class RemoteEmbeddingRuntime implements EmbeddingRuntimePort {
     runId: string,
     signal?: AbortSignal,
   ) {
+    await this.assertReadiness(request, signal);
     const response = await this.request("/api/embeddings/runs", {
       method: "POST",
       headers: {
@@ -125,6 +128,24 @@ export class RemoteEmbeddingRuntime implements EmbeddingRuntimePort {
       return response;
     });
   }
+
+  private async assertReadiness(
+    request: EmbeddingRuntimeOperation,
+    signal?: AbortSignal,
+  ) {
+    if (!request.readinessPin) return;
+    try {
+      await assertAiRuntimeReadinessPin(request.readinessPin, () =>
+        this.health(signal),
+      );
+    } catch {
+      throw new EmbeddingRuntimeError(
+        "RUNTIME_UNAVAILABLE",
+        "Embedding Runtime readiness 已漂移",
+        true,
+      );
+    }
+  }
 }
 
 export const unavailableEmbeddingRuntime: EmbeddingRuntimePort = {

package/template/apps/server/src/embedding/run-fingerprint.test.ts

@@ -2,6 +2,12 @@ import { expect, test } from "bun:test";
 import { embeddingRunFingerprint } from "./run-fingerprint.js";
 
 test("Run fingerprint 排除旋转后的 Artifact token，保留稳定输入与 options", async () => {
+  const pin = {
+    key: "embedding.primary",
+    identity: "windy-deployment-v1_0f26eb34-f384-4ec9-98f3-caf8d582291f",
+    releaseDigest: `sha256:${"a".repeat(64)}` as const,
+    offersDigest: `sha256:${"b".repeat(64)}` as const,
+  };
   const first = await embeddingRunFingerprint(
     "analysis.embedding.image",
     [
@@ -16,6 +22,7 @@ test("Run fingerprint 排除旋转后的 Artifact token，保留稳定输入与
       },
     ],
     { nested: { limit: 2 } },
+    pin,
   );
   const retry = await embeddingRunFingerprint(
     "analysis.embedding.image",
@@ -31,6 +38,7 @@ test("Run fingerprint 排除旋转后的 Artifact token，保留稳定输入与
       },
     ],
     { nested: { limit: 2 } },
+    pin,
   );
   const changed = await embeddingRunFingerprint(
     "analysis.embedding.image",
@@ -46,7 +54,25 @@ test("Run fingerprint 排除旋转后的 Artifact token，保留稳定输入与
       },
     ],
     { nested: { limit: 2 } },
+    { ...pin, offersDigest: `sha256:${"c".repeat(64)}` },
+  );
+  const deploymentChanged = await embeddingRunFingerprint(
+    "analysis.embedding.image",
+    [
+      {
+        id: "image-1",
+        source: {
+          value: "rotated-token-four",
+          mediaType: "image/png",
+          byteSize: 12,
+          sha256: "a".repeat(64),
+        },
+      },
+    ],
+    { nested: { limit: 2 } },
+    { ...pin, offersDigest: `sha256:${"c".repeat(64)}` },
   );
   expect(retry).toBe(first);
   expect(changed).not.toBe(first);
+  expect(deploymentChanged).not.toBe(first);
 });

package/template/apps/server/src/embedding/run-fingerprint.ts

@@ -1,15 +1,24 @@
-import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type {
+  AiRuntimeDeploymentV1,
+  ModuleAiJsonValue,
+} from "@southwind-ai/server-sdk";
 import type { EmbeddingRuntimeItem } from "./contracts.js";
 
 export async function embeddingRunFingerprint(
   operationKey: string,
   items: readonly EmbeddingRuntimeItem[],
   options: ModuleAiJsonValue,
+  readinessPin?: AiRuntimeDeploymentV1,
 ) {
   const digest = await crypto.subtle.digest(
     "SHA-256",
     new TextEncoder().encode(
-      stableJson({ operationKey, items: items.map(stableItem), options }),
+      stableJson({
+        operationKey,
+        items: items.map(stableItem),
+        options,
+        ...(readinessPin ? { readinessPin } : {}),
+      }),
     ),
   );
   return [...new Uint8Array(digest)]