create-windy 0.5.2 → 0.6.0

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

@@ -0,0 +1,73 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import { featureKey } from "@southwind-ai/shared";
+import { speechOutputArtifactCapabilityV1 } from "./output-artifact-policy.js";
+
+export function speechOutputManifest(operationKey: string): ModuleManifest {
+  return {
+    name: "evidence",
+    version: "0.1.0",
+    label: "物证",
+    description: "物证",
+    menus: [],
+    adminRoutes: [],
+    permissions: [
+      {
+        key: `${operationKey}.execute`,
+        label: "音频归一化",
+        module: "evidence",
+        moduleLabel: "物证",
+        resource: "audio",
+        resourceLabel: "音频",
+        action: "manage",
+      },
+    ],
+    apiPermissions: [],
+    features: [
+      {
+        key: featureKey(operationKey),
+        label: "音频归一化",
+        module: "evidence",
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    migrations: [],
+    schemaExports: [],
+    jsonSchemas: [
+      { key: `${operationKey}.input.v1`, schema: { type: "object" } },
+      { key: `${operationKey}.output.v1`, schema: { type: "object" } },
+    ],
+    tasks: [],
+    tools: [],
+    aiOperations: [
+      {
+        key: operationKey,
+        kind: "speech",
+        featureKey: operationKey,
+        permissionKey: `${operationKey}.execute`,
+        auditAction: `${operationKey}.execute`,
+        inputSchemaKey: `${operationKey}.input.v1`,
+        outputSchemaKey: `${operationKey}.output.v1`,
+        inputModalities: ["audio"],
+        requiredCapabilities: [
+          "speech.normalize",
+          speechOutputArtifactCapabilityV1,
+        ],
+        allowedToolKeys: [],
+        dataClassification: "sensitive",
+        execution: "background",
+        providerEgress: { mode: "forbidden" },
+        limits: {
+          maxDurationSeconds: 60,
+          maxInputBytes: 4_096,
+          maxOutputBytes: 4_096,
+          maxUnits: 1,
+          maxMediaDurationSeconds: 60,
+        },
+      },
+    ],
+    providers: [],
+    auditActions: [`${operationKey}.execute`],
+  };
+}

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

@@ -0,0 +1,302 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleAiOperationReadinessV1 } from "@southwind-ai/server-sdk";
+import { buildScopeContext } from "../data-access/context.js";
+import type { RequestActor, RequestGuardContext } from "../guards.js";
+import { createServerRuntime } from "../runtime.js";
+import { createStorageRuntime } from "../storage/runtime.js";
+import { createDocumentOutputArtifactRuntime } from "../document/output-artifact-runtime.js";
+import {
+  outputByteStream,
+  outputHash,
+} from "../ai-output-artifact/test-support.js";
+import type { SpeechRuntimeOperation } from "./contracts.js";
+import {
+  SpeechOutputArtifactHostError,
+  speechOutputArtifactCapabilityV1,
+} from "./output-artifact-host.js";
+import { speechOutputManifest } from "./output-artifact-host.test-support.js";
+
+const operationKey = "evidence.audio.normalize";
+const now = () => new Date("2026-08-06T12:00:00.000Z");
+
+describe("Speech Output Artifact Host", () => {
+  test("create 前固定 operation-bound scope、grant、TTL，sealed 后由 Host claim", async () => {
+    const fixture = createFixture();
+    const invocation = speechInvocation();
+    const begun = await fixture.host.begin({
+      definition: fixture.operation,
+      moduleName: "evidence",
+      runId: invocation.runId!,
+      idempotencyKey: "a".repeat(64),
+      context: fixture.context(),
+      invocation,
+    });
+    expect(begun?.grant).toMatch(/^outgrant_v1_/);
+    expect(begun?.descriptor).toMatchObject({
+      outputKind: "normalized-audio",
+      allowedMediaTypes: ["audio/wav"],
+      grantGeneration: 1,
+      expiresAt: "2026-08-06T12:02:00.000Z",
+    });
+    const pending = await fixture.output.service.options.repository.getScope(
+      begun!.scopeId,
+    );
+    expect(pending).toMatchObject({
+      runId: invocation.runId,
+      moduleName: "evidence",
+      operationKey,
+      runtimeKind: "speech",
+      purpose: "ai-runtime-output",
+      status: "open",
+      pendingGrantGeneration: 1,
+    });
+    expect(pending).not.toHaveProperty("grantHash");
+
+    await fixture.output.service.acceptGrant(
+      begun!.scopeId,
+      begun!.grantGeneration,
+      begun!.grant!,
+    );
+    const activeReplay = await fixture.host.begin({
+      definition: fixture.operation,
+      moduleName: "evidence",
+      runId: invocation.runId!,
+      idempotencyKey: "a".repeat(64),
+      context: fixture.context(),
+      invocation,
+    });
+    expect(activeReplay).toMatchObject({
+      scopeId: begun!.scopeId,
+      grantGeneration: 1,
+    });
+    expect(activeReplay?.grant).toBeUndefined();
+    const wav = wavBytes();
+    const artifact = await fixture.output.service.beginArtifact(
+      begun!.scopeId,
+      begun!.grant!,
+      {
+        contractVersion: 1,
+        outputKey: "normalized-audio",
+        filename: "normalized.wav",
+        mediaType: "audio/wav",
+        byteSize: wav.byteLength,
+        sha256: outputHash(wav),
+        outputKind: "normalized-audio",
+      },
+      new AbortController().signal,
+    );
+    await fixture.output.service.appendPart(
+      begun!.scopeId,
+      begun!.grant!,
+      {
+        artifactId: artifact.artifactId,
+        partNumber: 0,
+        byteOffset: 0,
+        byteSize: wav.byteLength,
+        sha256: outputHash(wav),
+        body: outputByteStream(wav),
+      },
+      new AbortController().signal,
+    );
+    await fixture.output.service.completeArtifact(
+      begun!.scopeId,
+      begun!.grant!,
+      artifact.artifactId,
+      new AbortController().signal,
+    );
+    await fixture.output.service.sealScope(begun!.scopeId, begun!.grant!);
+
+    const sealedReplay = await fixture.host.begin({
+      definition: fixture.operation,
+      moduleName: "evidence",
+      runId: invocation.runId!,
+      idempotencyKey: "a".repeat(64),
+      context: fixture.context(),
+      invocation,
+    });
+    expect(sealedReplay).toMatchObject({
+      scopeId: begun!.scopeId,
+      grantGeneration: 1,
+    });
+    expect(sealedReplay?.grant).toBeUndefined();
+    expect(sealedReplay?.references).toHaveLength(1);
+
+    const claimed = await fixture.host.claimSealed(
+      invocation.runId!,
+      fixture.context(),
+    );
+    expect(claimed).toHaveLength(1);
+    expect(claimed[0]).toMatchObject({
+      outputKey: "normalized-audio",
+      mediaType: "audio/wav",
+      byteSize: wav.byteLength,
+      sha256: outputHash(wav),
+    });
+    expect(claimed[0]?.value).toMatch(/^oa1\./);
+  });
+
+  test("只允许 sealed claim，并复核 Actor、scope 与当前 Permission", async () => {
+    const fixture = createFixture();
+    const invocation = speechInvocation();
+    const begun = await fixture.host.begin({
+      definition: fixture.operation,
+      moduleName: "evidence",
+      runId: invocation.runId!,
+      idempotencyKey: "b".repeat(64),
+      context: fixture.context(),
+      invocation,
+    });
+    await expect(
+      fixture.host.claimSealed(invocation.runId!, fixture.context()),
+    ).rejects.toBeInstanceOf(SpeechOutputArtifactHostError);
+
+    fixture.setActor(actor([]));
+    await expect(
+      fixture.host.claimSealed(invocation.runId!, fixture.context()),
+    ).rejects.toMatchObject({ code: "FORBIDDEN" });
+    expect(await fixture.host.abortOpenRun(invocation.runId!)).toBe(true);
+    expect(
+      await fixture.output.service.options.repository.getScope(begun!.scopeId),
+    ).toMatchObject({ status: "aborted" });
+  });
+});
+
+function createFixture() {
+  const module = speechOutputManifest(operationKey);
+  let currentActor = actor();
+  const runtime = createServerRuntime(
+    {},
+    {
+      featureCatalog: module.features,
+      featureResolver: {
+        resolve: (key) => ({
+          key,
+          enabled: true,
+          visible: "visible",
+        }),
+      },
+      licenseResolver: {
+        resolve: () => ({ status: "valid", restricted: false }),
+      },
+    },
+  );
+  const output = createDocumentOutputArtifactRuntime({
+    modules: [module],
+    bindings: [],
+    speechBindings: [{ operationKey, outputKind: "normalized-audio" }],
+    readiness: { inspect: async () => readiness() },
+    runtime,
+    storage: createStorageRuntime({}, undefined, undefined, now),
+    resolveActor: async () => currentActor,
+    referenceSecret: "speech-output-test-secret".repeat(2),
+    ephemeral: true,
+    now,
+  });
+  return {
+    output,
+    host: output.speechHost!,
+    operation: module.aiOperations![0]!,
+    context: () => context(currentActor),
+    setActor(value: RequestActor) {
+      currentActor = value;
+    },
+  };
+}
+
+function speechInvocation(): SpeechRuntimeOperation {
+  return {
+    kind: "speech",
+    runId: `speech_${"c".repeat(64)}`,
+    contractVersion: 2,
+    variant: "normalize",
+    operationKey,
+    options: {},
+    source: {
+      value: "rotated-ref",
+      mediaType: "audio/wav",
+      byteSize: 128,
+      sha256: "d".repeat(64),
+    },
+    requiredCapabilities: [
+      "speech.normalize",
+      speechOutputArtifactCapabilityV1,
+    ],
+    dataClassification: "sensitive",
+    limits: {
+      maxDurationSeconds: 60,
+      maxInputBytes: 4_096,
+      maxOutputBytes: 4_096,
+      maxUnits: 1,
+      maxMediaDurationSeconds: 60,
+    },
+    providerEgress: { mode: "forbidden" },
+  };
+}
+
+function readiness(): ModuleAiOperationReadinessV1 {
+  return {
+    schemaVersion: 1,
+    operationKey,
+    runtimeKind: "speech",
+    observedAt: now().toISOString(),
+    status: "ready",
+    validUntil: "2026-08-06T12:05:00.000Z",
+    deployment: {
+      key: "speech.normalize",
+      identity: "windy-deployment-v1_7db61d8e-e50d-4f8a-9f3f-9b7a1d932e01",
+      releaseDigest: `sha256:${"a".repeat(64)}`,
+      offersDigest: `sha256:${"b".repeat(64)}`,
+    },
+    offers: [
+      {
+        variant: "normalize",
+        capabilities: ["speech.normalize", speechOutputArtifactCapabilityV1],
+        inputModalities: ["audio"],
+        outputModalities: ["audio"],
+        limits: {
+          maxDurationSeconds: 60,
+          maxInputBytes: 4_096,
+          maxOutputBytes: 2_048,
+          maxUnits: 1,
+          maxMediaDurationSeconds: 60,
+          maxArtifacts: 1,
+          maxConcurrentRuns: 1,
+          maxQueueDepth: 0,
+        },
+      },
+    ],
+    unavailableReasons: [],
+  };
+}
+
+function actor(permissionKeys = [`${operationKey}.execute`]): RequestActor {
+  return {
+    id: "actor-1",
+    type: "user",
+    name: "分析员",
+    roleCodes: ["analyst"],
+    permissionKeys,
+    scopeContext: buildScopeContext("actor-1", undefined, [
+      {
+        id: "analyst",
+        code: "analyst",
+        dataScope: "self",
+        departmentIds: [],
+      },
+    ]),
+  };
+}
+
+function context(value: RequestActor): RequestGuardContext {
+  return {
+    requestId: "speech-output-request",
+    actor: value,
+    startedAt: now().toISOString(),
+  };
+}
+
+function wavBytes() {
+  return new TextEncoder().encode(
+    "RIFF\u0024\u0000\u0000\u0000WAVEfmt \u0010\u0000\u0000\u0000",
+  );
+}

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

@@ -0,0 +1,279 @@
+import type {
+  ModuleAiOperationDefinition,
+  ModuleManifest,
+} from "@southwind-ai/modules";
+import type { ModuleAiOperationReadinessPortV1 } from "@southwind-ai/server-sdk";
+import { evaluateAccessGuards } from "../access-guards.js";
+import type { AiOutputArtifactCleanupService } from "../ai-output-artifact/cleanup.js";
+import type {
+  AiOutputArtifactReferenceV1,
+  AiOutputArtifactScope,
+} from "../ai-output-artifact/contracts.js";
+import { AiOutputArtifactPolicyRegistry } from "../ai-output-artifact/policy.js";
+import type { AiOutputArtifactService } from "../ai-output-artifact/service.js";
+import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
+import { isServerScopeContext } from "../data-access/context.js";
+import type { RequestActor, RequestGuardContext } from "../guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import type { SpeechRuntimeOperation } from "./contracts.js";
+import {
+  speechOutputArtifactBindings,
+  type SpeechOutputArtifactBinding,
+} from "./output-artifact-binding.js";
+import {
+  requireSpeechOutputReady,
+  speechOutputInvocationDigest,
+  speechOutputPolicyLimits,
+  validSpeechOutputScopeLimits,
+} from "./output-artifact-policy.js";
+import { SpeechOutputArtifactHostError } from "./output-artifact-error.js";
+import { replaySpeechOutputScope } from "./output-artifact-replay.js";
+
+export { SpeechOutputArtifactHostError } from "./output-artifact-error.js";
+
+export { speechOutputArtifactCapabilityV1 } from "./output-artifact-policy.js";
+
+export interface SpeechOutputArtifactStart {
+  readonly runId: string;
+  readonly scopeId: string;
+  readonly grantGeneration: number;
+  readonly descriptor: NonNullable<
+    SpeechRuntimeOperation["outputArtifactSink"]
+  >;
+  readonly grant?: string;
+  readonly references?: readonly AiOutputArtifactReferenceV1[];
+}
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export class SpeechOutputArtifactHost {
+  readonly #bindings: Map<string, SpeechOutputArtifactBinding>;
+  readonly #operations;
+  readonly #policies = new AiOutputArtifactPolicyRegistry();
+
+  constructor(
+    modules: readonly ModuleManifest[],
+    bindings: readonly SpeechOutputArtifactBinding[],
+    private readonly readiness: ModuleAiOperationReadinessPortV1,
+    private readonly service: AiOutputArtifactService,
+    private readonly cleanup: AiOutputArtifactCleanupService,
+    private readonly runtime: ServerRuntime,
+    private readonly resolveActor: (
+      actorId: string,
+    ) => Promise<RequestActor | undefined>,
+    private readonly now: () => Date = () => new Date(),
+  ) {
+    this.#bindings = new Map(
+      [...speechOutputArtifactBindings(modules, bindings)].map(
+        ([key, value]) => [
+          key,
+          {
+            operationKey: value.operationKey,
+            outputKind: "normalized-audio" as const,
+          },
+        ],
+      ),
+    );
+    this.#operations = new Map(
+      modules.flatMap((module) =>
+        (module.aiOperations ?? [])
+          .filter(({ kind }) => kind === "speech")
+          .map(
+            (definition) => [definition.key, { module, definition }] as const,
+          ),
+      ),
+    );
+  }
+
+  hasBinding(operationKey: string) {
+    return this.#bindings.has(operationKey);
+  }
+
+  async begin(input: {
+    definition: ModuleAiOperationDefinition;
+    moduleName: string;
+    runId: string;
+    idempotencyKey: string;
+    context: RequestGuardContext;
+    invocation: SpeechRuntimeOperation;
+  }): Promise<SpeechOutputArtifactStart | undefined> {
+    const binding = this.#bindings.get(input.definition.key);
+    if (!binding) return undefined;
+    if (
+      input.invocation.runId !== input.runId ||
+      input.invocation.variant !== "normalize" ||
+      input.invocation.operationKey !== input.definition.key
+    ) {
+      throw conflict("Speech Output Artifact 调用语义不匹配");
+    }
+    const ready = requireSpeechOutputReady(
+      await this.readiness.inspect({ operationKey: input.definition.key }),
+      input.definition.key,
+      this.now(),
+    );
+    const limits = speechOutputPolicyLimits(input.definition, ready);
+    const policy = this.#policies.resolve({
+      runtimeKind: "speech",
+      outputKind: binding.outputKind,
+      dataClassification: input.definition.dataClassification,
+      operationLimits: limits.operation,
+      readinessLimits: limits.readiness,
+      runtimeLimits: limits.runtime,
+    });
+    const invocationDigest = speechOutputInvocationDigest(
+      input.invocation,
+      ready,
+      policy.digest,
+    );
+    try {
+      const replayed = await replaySpeechOutputScope({
+        service: this.service,
+        runId: input.runId,
+        moduleName: input.moduleName,
+        operationKey: input.definition.key,
+        idempotencyKey: input.idempotencyKey,
+        invocationDigest,
+        deployment: ready.deployment,
+        policy,
+        context: input.context,
+        now: this.now(),
+      });
+      if (replayed) return replayed;
+      const begun = await this.service.beginScope({
+        runId: input.runId,
+        moduleName: input.moduleName,
+        operationKey: input.definition.key,
+        runtimeKind: "speech",
+        idempotencyKey: input.idempotencyKey,
+        invocationDigest,
+        dataClassification: input.definition.dataClassification,
+        deploymentIdentity: ready.deployment.identity,
+        releaseDigest: ready.deployment.releaseDigest,
+        offersDigest: ready.deployment.offersDigest,
+        policy,
+        context: input.context,
+      });
+      if (!begun.descriptor) throw new Error("missing descriptor");
+      return {
+        runId: begun.scope.runId,
+        scopeId: begun.scope.scopeId,
+        grantGeneration: begun.descriptor.grantGeneration,
+        descriptor: begun.descriptor,
+        grant: begun.grant,
+        references: begun.references,
+      };
+    } catch (error) {
+      if (hasCode(error, "OUTPUT_ARTIFACT_CONFLICT")) {
+        throw conflict("Speech Output Artifact 幂等语义冲突");
+      }
+      throw unavailable();
+    }
+  }
+
+  confirmGrant(scopeId: string, generation: number, grant: string) {
+    return this.service.confirmGrant(scopeId, generation, grant);
+  }
+
+  rollbackPendingGrant(scopeId: string, generation: number, grant: string) {
+    return this.service.rollbackPendingGrant(scopeId, generation, grant);
+  }
+
+  abortOpenRun(runId: string) {
+    return this.cleanup.abortOpenRun(runId);
+  }
+
+  async claimSealed(
+    runId: string,
+    context: RequestGuardContext,
+  ): Promise<readonly AiOutputArtifactReferenceV1[]> {
+    const scopes = (
+      await this.service.options.repository.listScopesByRun(runId)
+    ).filter(({ runtimeKind }) => runtimeKind === "speech");
+    if (scopes.length !== 1) throw unavailable();
+    const scope = scopes[0]!;
+    if (!(await this.#authorizeClaim(scope, runId, context))) {
+      throw new SpeechOutputArtifactHostError(
+        "FORBIDDEN",
+        "Speech Output Artifact 当前不可访问",
+      );
+    }
+    try {
+      return await this.service.claimSealedScope(scope.scopeId);
+    } catch {
+      throw unavailable();
+    }
+  }
+
+  async authorizeRead(scope: AiOutputArtifactScope, signal: AbortSignal) {
+    try {
+      const actor = await this.resolveActor(scope.actorId);
+      if (!actor) return undefined;
+      const context = await this.runtime.createGuardContextForActor(
+        new Request("http://ai-output.internal/read", { signal }),
+        actor,
+      );
+      return (await this.#authorizeClaim(scope, scope.runId, context))
+        ? {
+            actorId: actor.id,
+            scopeHash: captureAuthorizationScope(actor.scopeContext!).hash,
+            requestId: context.requestId,
+          }
+        : { requestId: context.requestId };
+    } catch {
+      return undefined;
+    }
+  }
+
+  async #authorizeClaim(
+    scope: AiOutputArtifactScope,
+    runId: string,
+    context: RequestGuardContext,
+  ) {
+    const binding = this.#bindings.get(scope.operationKey);
+    const operation = this.#operations.get(scope.operationKey);
+    if (
+      !binding ||
+      !operation ||
+      operation.module.name !== scope.moduleName ||
+      binding.outputKind !== scope.outputKind ||
+      scope.runtimeKind !== "speech" ||
+      scope.runId !== runId ||
+      scope.purpose !== "ai-runtime-output" ||
+      scope.actorId !== context.actor.id ||
+      operation.definition.dataClassification !== scope.dataClassification ||
+      !validSpeechOutputScopeLimits(scope, operation.definition)
+    ) {
+      return false;
+    }
+    const actorScope = context.actor.scopeContext;
+    if (
+      !isServerScopeContext(actorScope) ||
+      actorScope.tenantId !== scope.tenantId ||
+      captureAuthorizationScope(actorScope).hash !== scope.scopeHash
+    ) {
+      return false;
+    }
+    const access = await evaluateAccessGuards(this.runtime, context, {
+      permission: { permissionKey: operation.definition.permissionKey },
+      feature: operation.module.features.find(
+        ({ key }) => key === operation.definition.featureKey,
+      ),
+    });
+    return access.decision.allowed;
+  }
+}
+
+function hasCode(error: unknown, code: string) {
+  return error instanceof Error && "code" in error && error.code === code;
+}
+
+function conflict(message: string) {
+  return new SpeechOutputArtifactHostError("RUN_CONFLICT", message);
+}
+
+function unavailable() {
+  return new SpeechOutputArtifactHostError(
+    "CAPABILITY_UNAVAILABLE",
+    "Speech Output Artifact 暂时不可用",
+  );
+}