create-windy 0.5.2 → 0.6.1

package/template/apps/server/src/speech/facade-validation.ts

@@ -0,0 +1,127 @@
+import type {
+  ModuleAiArtifactRef,
+  ModuleAiJsonValue,
+  ModuleAiOperationReadinessPortV1,
+} from "@southwind-ai/server-sdk";
+import type { ModuleAiOperationDefinition } from "@southwind-ai/modules";
+import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
+import type { RequestGuardContext } from "../guards.js";
+import {
+  governProviderInput,
+  ProviderInputGovernanceError,
+} from "../agent/provider-input-governance.js";
+import { SpeechRuntimeError, type SpeechRuntimePort } from "./contracts.js";
+import { SpeechFacadeError } from "./errors.js";
+import { legacySpeechCapabilities } from "./facade-contract.js";
+
+export function governSpeechOptions(
+  input: ModuleAiJsonValue,
+  definition: ModuleAiOperationDefinition,
+) {
+  try {
+    return definition.providerDataPolicy
+      ? governProviderInput(input, definition.providerDataPolicy)
+      : input;
+  } catch (error) {
+    if (error instanceof ProviderInputGovernanceError) {
+      throw new SpeechFacadeError(
+        error.code,
+        error.message,
+        error.code === "FORBIDDEN" ? 403 : 400,
+      );
+    }
+    throw error;
+  }
+}
+
+export function assertSpeechInputSize(
+  value: ModuleAiJsonValue,
+  maxBytes: number,
+) {
+  if (new TextEncoder().encode(JSON.stringify(value)).byteLength > maxBytes) {
+    throw new SpeechFacadeError("INVALID_INPUT", "Speech 输入超过上限", 400);
+  }
+}
+
+export function assertSpeechArtifactMetadata(
+  submitted: ModuleAiArtifactRef,
+  resolved: ModuleAiArtifactRef,
+) {
+  if (
+    submitted.mediaType !== resolved.mediaType ||
+    submitted.byteSize !== resolved.byteSize ||
+    submitted.sha256 !== resolved.sha256
+  ) {
+    throw new SpeechFacadeError(
+      "ARTIFACT_UNAVAILABLE",
+      "Artifact 元数据不一致",
+      403,
+    );
+  }
+}
+
+export async function requireSpeechCapabilities(input: {
+  remote: SpeechRuntimePort;
+  readiness?: ModuleAiOperationReadinessPortV1;
+  required: readonly string[];
+  operationKey: string;
+  requiresReadiness: boolean;
+  signal: AbortSignal;
+}) {
+  if (input.requiresReadiness && input.readiness) {
+    const projected = await input.readiness.inspect({
+      operationKey: input.operationKey,
+    });
+    if (projected.status !== "ready") throw speechCapabilityUnavailable();
+    return;
+  }
+  let response: Response;
+  try {
+    response = await input.remote.health(input.signal);
+  } catch {
+    throw speechCapabilityUnavailable();
+  }
+  if (!response.ok) throw speechCapabilityUnavailable();
+  try {
+    const value = (await response.json()) as Record<string, unknown>;
+    const capabilities = legacySpeechCapabilities(value);
+    if (
+      value.status !== "ready" ||
+      input.required.some((capability) => !capabilities.includes(capability))
+    ) {
+      throw speechCapabilityUnavailable();
+    }
+  } catch (error) {
+    if (error instanceof SpeechFacadeError) throw error;
+    throw speechCapabilityUnavailable();
+  }
+}
+
+export function speechCapabilityUnavailable() {
+  return new SpeechFacadeError(
+    "CAPABILITY_UNAVAILABLE",
+    "Speech Runtime 缺少 Operation 所需能力",
+    503,
+  );
+}
+
+export function speechRuntimeErrorStatus(code: SpeechRuntimeError["code"]) {
+  if (code === "FORBIDDEN") return 403;
+  if (code === "RUN_CONFLICT") return 409;
+  if (code === "BUDGET_EXCEEDED" || code === "INVALID_INPUT") return 400;
+  return 503;
+}
+
+export function sameSpeechAuthorizationScope(
+  original: RequestGuardContext,
+  current: RequestGuardContext,
+) {
+  const originalScope = original.actor.scopeContext;
+  const currentScope = current.actor.scopeContext;
+  return Boolean(
+    originalScope &&
+    currentScope &&
+    captureAuthorizationScope(originalScope).hash ===
+      captureAuthorizationScope(currentScope).hash,
+  );
+}

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

@@ -1,22 +1,15 @@
 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 {
   ModuleAiArtifactRef,
   ModuleAiJsonValue,
-  ModuleAiOperationHandlerRegistration,
+  ModuleAiOperationReadinessPortV1,
 } from "@southwind-ai/server-sdk";
 import { evaluateAccessGuards } from "../access-guards.js";
 import type { AiArtifactRuntime } from "../ai-artifact/runtime.js";
 import { ExecutionGrantStore } from "../agent/execution-grants.js";
 import { scopedRuntimeIdempotencyKey } from "../agent/idempotency-key.js";
-import {
-  governProviderInput,
-  ProviderInputGovernanceError,
-} from "../agent/provider-input-governance.js";
 import { auditActor, type RequestGuardContext } from "../guards.js";
 import type { InitializedModuleHosts } from "../module-host.js";
 import { toModuleActor } from "../module-host.js";
@@ -24,9 +17,39 @@ import { findFeature } from "../route-guards.js";
 import type { createServerRuntime } from "../runtime.js";
 import {
   SpeechRuntimeError,
+  type SpeechRuntimeOperation,
   type SpeechRuntimePort,
   type SpeechRuntimeStartResponse,
 } from "./contracts.js";
+import {
+  matchesSpeechContractVariant,
+  type RegisteredSpeechOperation,
+  type SpeechStartContract,
+} from "./facade-contract.js";
+import {
+  cancelSpeechRun,
+  confirmSpeechOutput,
+  rollbackSpeechOutput,
+  speechResultResponse,
+  speechRunId,
+} from "./facade-output.js";
+import { SpeechFacadeError } from "./errors.js";
+import {
+  assertSpeechArtifactMetadata,
+  assertSpeechInputSize,
+  governSpeechOptions,
+  requireSpeechCapabilities,
+  sameSpeechAuthorizationScope,
+  speechCapabilityUnavailable,
+  speechRuntimeErrorStatus,
+} from "./facade-validation.js";
+import {
+  SpeechOutputArtifactHostError,
+  type SpeechOutputArtifactHost,
+  type SpeechOutputArtifactStart,
+} from "./output-artifact-host.js";
+
+export { SpeechFacadeError } from "./errors.js";
 
 export class SpeechRunFacade {
   readonly #operations: Map<string, RegisteredSpeechOperation>;
@@ -38,6 +61,8 @@ export class SpeechRunFacade {
     private readonly remote: SpeechRuntimePort,
     private readonly artifacts: AiArtifactRuntime,
     private readonly grants: ExecutionGrantStore,
+    private readonly readiness?: ModuleAiOperationReadinessPortV1,
+    private readonly outputArtifacts?: SpeechOutputArtifactHost,
   ) {
     const handlers = new Map(
       hosts.aiOperationHandlers.map(({ registration, moduleName }) => [
@@ -72,6 +97,7 @@ export class SpeechRunFacade {
     idempotencyKey: string,
     context: RequestGuardContext,
     signal: AbortSignal,
+    contract: SpeechStartContract = {},
   ): Promise<SpeechRuntimeStartResponse> {
     const operation = this.#operations.get(operationKey);
     if (!operation?.registration?.prepareSpeech || !operation.moduleName) {
@@ -81,12 +107,23 @@ export class SpeechRunFacade {
         404,
       );
     }
+    if (!matchesSpeechContractVariant(operation.definition, contract)) {
+      throw new SpeechFacadeError(
+        "OPERATION_DISABLED",
+        "Speech variant 与 Operation readiness 声明不匹配",
+        503,
+      );
+    }
     await this.authorize(operation, context);
-    await this.requireCapabilities(
-      operation.definition.requiredCapabilities,
+    await requireSpeechCapabilities({
+      remote: this.remote,
+      readiness: this.readiness,
+      required: operation.definition.requiredCapabilities,
+      operationKey: operation.definition.key,
+      requiresReadiness: Boolean(operation.definition.readiness),
       signal,
-    );
-    assertInputSize(input, operation.definition.limits.maxInputBytes);
+    });
+    assertSpeechInputSize(input, operation.definition.limits.maxInputBytes);
     if (source.byteSize > operation.definition.limits.maxInputBytes) {
       throw new SpeechFacadeError(
         "BUDGET_EXCEEDED",
@@ -102,7 +139,7 @@ export class SpeechRunFacade {
         503,
       );
     }
-    const governed = governOptions(input, operation.definition);
+    const governed = governSpeechOptions(input, operation.definition);
     const plan = await operation.registration.prepareSpeech(governed, {
       actor: toModuleActor(context.actor),
       requestId: context.requestId,
@@ -114,39 +151,87 @@ export class SpeechRunFacade {
       Math.min(operation.definition.limits.maxDurationSeconds + 60, 3_600),
       signal,
     );
-    assertArtifactMetadata(source, rotated);
+    assertSpeechArtifactMetadata(source, rotated);
+    const scopedKey = scopedRuntimeIdempotencyKey(
+      context.actor.id,
+      operationKey,
+      idempotencyKey,
+    );
+    const plannedRunId = speechRunId(scopedKey);
+    const invocation: SpeechRuntimeOperation = {
+      kind: "speech",
+      ...contract,
+      ...(contract.variant === "normalize" ? { runId: plannedRunId } : {}),
+      operationKey,
+      options: plan.options ?? governed,
+      source: {
+        value: rotated.value,
+        mediaType: rotated.mediaType,
+        byteSize: rotated.byteSize,
+        sha256: rotated.sha256,
+      },
+      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,
+        maxMediaDurationSeconds,
+      },
+      providerEgress: resolveProviderEgress(operation.definition),
+      providerDataPolicy: operation.definition.providerDataPolicy,
+    };
+    const outputEnabled = contract.variant === "normalize";
+    let output: SpeechOutputArtifactStart | undefined;
+    if (outputEnabled) {
+      if (!this.outputArtifacts?.hasBinding(operationKey)) {
+        throw speechCapabilityUnavailable();
+      }
+      try {
+        output = await this.outputArtifacts.begin({
+          definition: operation.definition,
+          moduleName: operation.moduleName,
+          runId: plannedRunId,
+          idempotencyKey: scopedKey,
+          context,
+          invocation,
+        });
+        if (!output) throw speechCapabilityUnavailable();
+      } catch (error) {
+        if (error instanceof SpeechOutputArtifactHostError) {
+          throw new SpeechFacadeError(
+            error.code,
+            error.message,
+            error.code === "RUN_CONFLICT"
+              ? 409
+              : error.code === "FORBIDDEN"
+                ? 403
+                : 503,
+          );
+        }
+        throw speechCapabilityUnavailable();
+      }
+    }
     const grant = this.grants.issue(operation.definition, context, 3_600);
     try {
       const created = await this.remote.start(
         {
-          kind: "speech",
-          operationKey,
-          options: plan.options ?? governed,
-          source: {
-            value: rotated.value,
-            mediaType: rotated.mediaType,
-            byteSize: rotated.byteSize,
-            sha256: rotated.sha256,
-          },
-          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,
-            maxMediaDurationSeconds,
-          },
-          providerEgress: resolveProviderEgress(operation.definition),
-          providerDataPolicy: operation.definition.providerDataPolicy,
+          ...invocation,
+          ...(output ? { outputArtifactSink: output.descriptor } : {}),
         },
-        scopedRuntimeIdempotencyKey(
-          context.actor.id,
-          operationKey,
-          idempotencyKey,
-        ),
+        scopedKey,
         signal,
+        output?.grant,
       );
+      await confirmSpeechOutput(this.outputArtifacts, output);
+      if (output && created.runId !== output.runId) {
+        throw new SpeechRuntimeError(
+          "INVALID_RESPONSE",
+          "Speech Runtime 未采用 Host Run ID",
+          false,
+        );
+      }
       this.grants.bindRun(grant.token, created.runId);
       this.runtime.auditSink.recordEvent({
         id: randomUUIDv7(),
@@ -174,19 +259,76 @@ export class SpeechRunFacade {
       };
     } catch (error) {
       this.grants.discard(grant.token);
+      await rollbackSpeechOutput(this.outputArtifacts, output);
       if (error instanceof SpeechRuntimeError) {
         throw new SpeechFacadeError(
           error.code,
           error.message,
-          runtimeErrorStatus(error.code),
+          speechRuntimeErrorStatus(error.code),
         );
       }
       throw error;
     }
   }
 
-  authorizeRun(runId: string, context: RequestGuardContext) {
-    this.grants.requireRun(runId, context.actor.id);
+  async authorizeRun(runId: string, context: RequestGuardContext) {
+    let grant;
+    try {
+      grant = this.grants.requireRun(runId, context.actor.id);
+    } catch {
+      throw new SpeechFacadeError("FORBIDDEN", "无权访问 Speech Run", 403);
+    }
+    await this.authorize(
+      {
+        definition: grant.operation,
+        feature: this.#operations.get(grant.operation.key)?.feature,
+      },
+      context,
+    );
+    if (!sameSpeechAuthorizationScope(grant.context, context)) {
+      throw new SpeechFacadeError("FORBIDDEN", "无权访问 Speech Run", 403);
+    }
+    return grant;
+  }
+
+  async result(
+    runId: string,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+    artifact = false,
+  ) {
+    const grant = await this.authorizeRun(runId, context);
+    return speechResultResponse({
+      remote: this.remote,
+      host: this.outputArtifacts,
+      runId,
+      context,
+      signal,
+      outputBound: Boolean(
+        this.outputArtifacts?.hasBinding(grant.operation.key),
+      ),
+      maxInlineOutputBytes: grant.operation.limits.maxOutputBytes,
+      artifact,
+    });
+  }
+
+  async cancel(
+    runId: string,
+    reason: string | undefined,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ) {
+    const grant = await this.authorizeRun(runId, context);
+    return cancelSpeechRun({
+      remote: this.remote,
+      host: this.outputArtifacts,
+      runId,
+      reason,
+      signal,
+      outputBound: Boolean(
+        this.outputArtifacts?.hasBinding(grant.operation.key),
+      ),
+    });
   }
 
   private async authorize(
@@ -205,112 +347,4 @@ export class SpeechRunFacade {
       );
     }
   }
-
-  private async requireCapabilities(
-    required: readonly string[],
-    signal: AbortSignal,
-  ) {
-    let response: Response;
-    try {
-      response = await this.remote.health(signal);
-    } catch {
-      throw capabilityUnavailable();
-    }
-    if (!response.ok) throw capabilityUnavailable();
-    try {
-      const value = (await response.json()) as Record<string, unknown>;
-      const capabilities = Array.isArray(value.capabilities)
-        ? value.capabilities.filter(
-            (item): item is string => typeof item === "string",
-          )
-        : [];
-      if (
-        value.status !== "ready" ||
-        required.some((capability) => !capabilities.includes(capability))
-      ) {
-        throw capabilityUnavailable();
-      }
-    } catch (error) {
-      if (error instanceof SpeechFacadeError) throw error;
-      throw capabilityUnavailable();
-    }
-  }
-}
-
-interface RegisteredSpeechOperation {
-  definition: ModuleAiOperationDefinition;
-  feature: ReturnType<typeof findFeature>;
-  registration?: ModuleAiOperationHandlerRegistration;
-  moduleName?: string;
-}
-
-export class SpeechFacadeError extends Error {
-  constructor(
-    readonly code: string,
-    message: string,
-    readonly status: number,
-  ) {
-    super(message);
-    this.name = "SpeechFacadeError";
-  }
-}
-
-function governOptions(
-  input: ModuleAiJsonValue,
-  definition: ModuleAiOperationDefinition,
-) {
-  try {
-    return definition.providerDataPolicy
-      ? governProviderInput(input, definition.providerDataPolicy)
-      : input;
-  } catch (error) {
-    if (error instanceof ProviderInputGovernanceError) {
-      throw new SpeechFacadeError(
-        error.code,
-        error.message,
-        error.code === "FORBIDDEN" ? 403 : 400,
-      );
-    }
-    throw error;
-  }
-}
-
-function assertInputSize(value: ModuleAiJsonValue, maxBytes: number) {
-  if (new TextEncoder().encode(JSON.stringify(value)).byteLength > maxBytes) {
-    throw new SpeechFacadeError("INVALID_INPUT", "Speech 输入超过上限", 400);
-  }
-}
-
-function assertArtifactMetadata(
-  submitted: ModuleAiArtifactRef,
-  resolved: ModuleAiArtifactRef,
-) {
-  if (
-    submitted.mediaType !== resolved.mediaType ||
-    submitted.byteSize !== resolved.byteSize ||
-    submitted.sha256 !== resolved.sha256
-  ) {
-    throw new SpeechFacadeError(
-      "ARTIFACT_UNAVAILABLE",
-      "Artifact 元数据不一致",
-      403,
-    );
-  }
-}
-
-function capabilityUnavailable() {
-  return new SpeechFacadeError(
-    "CAPABILITY_UNAVAILABLE",
-    "Speech Runtime 缺少 Operation 所需能力",
-    503,
-  );
-}
-
-function runtimeErrorStatus(code: SpeechRuntimeError["code"]) {
-  if (code === "FORBIDDEN") return 403;
-  if (code === "RUN_CONFLICT") return 409;
-  if (code === "BUDGET_EXCEEDED" || code === "INVALID_INPUT") {
-    return 400;
-  }
-  return 503;
 }

package/template/apps/server/src/speech/fingerprint.test.ts

@@ -0,0 +1,42 @@
+import { expect, test } from "bun:test";
+import { speechRequestFingerprint } from "./fingerprint.js";
+
+const input = {
+  kind: "speech" as const,
+  contractVersion: 2 as const,
+  variant: "translate" as const,
+  operationKey: "speech.translate",
+  options: { targetLanguage: "en", timestamps: "segment" },
+  source: {
+    value: "rotated-one",
+    mediaType: "audio/mpeg",
+    byteSize: 9,
+    sha256: "a".repeat(64),
+  },
+  requiredCapabilities: ["speech.translate"],
+  dataClassification: "internal" as const,
+  limits: {
+    maxDurationSeconds: 60,
+    maxInputBytes: 100,
+    maxOutputBytes: 100,
+    maxUnits: 2,
+    maxMediaDurationSeconds: 60,
+  },
+  providerEgress: { mode: "forbidden" as const },
+};
+
+test("Speech fingerprint ignores rotated opaque token and changes with semantics", () => {
+  expect(speechRequestFingerprint(input)).toBe(
+    speechRequestFingerprint({
+      ...input,
+      source: { ...input.source, value: "rotated-two" },
+    }),
+  );
+  expect(speechRequestFingerprint(input)).not.toBe(
+    speechRequestFingerprint({
+      ...input,
+      variant: "transcribe",
+      options: { timestamps: "segment" },
+    }),
+  );
+});

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

@@ -0,0 +1,28 @@
+import { createHash } from "node:crypto";
+import type { SpeechRuntimeOperation } from "./contracts.js";
+
+/** Excludes rotated opaque refs, grants and expiries: only semantic identity. */
+export function speechRequestFingerprint(
+  input: SpeechRuntimeOperation,
+): string {
+  return createHash("sha256")
+    .update(
+      JSON.stringify({
+        contractVersion: input.contractVersion ?? 1,
+        variant: input.variant ?? "transcribe",
+        operationKey: input.operationKey,
+        source: {
+          mediaType: input.source.mediaType,
+          byteSize: input.source.byteSize,
+          sha256: input.source.sha256,
+        },
+        options: input.options,
+        requiredCapabilities: [...input.requiredCapabilities].sort(),
+        dataClassification: input.dataClassification,
+        limits: input.limits,
+        providerEgress: input.providerEgress,
+        providerDataPolicy: input.providerDataPolicy,
+      }),
+    )
+    .digest("hex");
+}

package/template/apps/server/src/speech/output-artifact-binding.test.ts

@@ -0,0 +1,11 @@
+import { expect, test } from "bun:test";
+import { speechOutputArtifactBindings } from "./output-artifact-binding.js";
+
+test("Speech Output Artifact binding rejects a non-speech operation", () => {
+  expect(() =>
+    speechOutputArtifactBindings(
+      [],
+      [{ operationKey: "speech.normalize", outputKind: "normalized-audio" }],
+    ),
+  ).toThrow("未注册");
+});

package/template/apps/server/src/speech/output-artifact-binding.ts

@@ -0,0 +1,30 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { OutputArtifactBinding } from "../ai-output-artifact/host-registry.js";
+import {
+  outputArtifactOperations,
+  uniqueOutputArtifactBindings,
+} from "../ai-output-artifact/host-registry.js";
+
+export interface SpeechOutputArtifactBinding {
+  readonly operationKey: string;
+  readonly outputKind: "normalized-audio";
+}
+
+export function speechOutputArtifactBindings(
+  modules: readonly ModuleManifest[],
+  bindings: readonly SpeechOutputArtifactBinding[],
+): Map<string, OutputArtifactBinding> {
+  const operations = outputArtifactOperations(
+    modules,
+    modules.flatMap(({ features }) => features),
+    "speech",
+  );
+  const result = uniqueOutputArtifactBindings(
+    bindings.map((binding) => ({ ...binding, runtimeKind: "speech" })),
+  );
+  for (const key of result.keys()) {
+    if (!operations.has(key))
+      throw new Error(`Speech Output Artifact Operation 未注册：${key}`);
+  }
+  return result;
+}

package/template/apps/server/src/speech/output-artifact-error.ts

@@ -0,0 +1,9 @@
+export class SpeechOutputArtifactHostError extends Error {
+  constructor(
+    readonly code: "CAPABILITY_UNAVAILABLE" | "RUN_CONFLICT" | "FORBIDDEN",
+    message: string,
+  ) {
+    super(message);
+    this.name = "SpeechOutputArtifactHostError";
+  }
+}