create-windy 0.5.2 → 0.6.0

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

@@ -1,23 +1,18 @@
-import { randomUUIDv7 } from "bun";
 import type {
   ModuleAiOperationDefinition,
   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 { RequestGuardContext } from "../guards.js";
 import type { InitializedModuleHosts } from "../module-host.js";
 import { toModuleActor } from "../module-host.js";
 import { findFeature } from "../route-guards.js";
@@ -27,6 +22,30 @@ import {
   type DocumentRuntimePort,
   type DocumentRuntimeStartResponse,
 } from "./contracts.js";
+import { DocumentFacadeError } from "./errors.js";
+import {
+  assertDocumentArtifactMetadata,
+  assertDocumentInputSize,
+  bindDocumentRunGrant,
+  capabilityUnavailable,
+  documentRunId,
+  documentRuntimeFacadeError,
+  forbiddenRun,
+  governDocumentOptions,
+  outputArtifactStatus,
+  recordDocumentRunStart,
+  requireDocumentCapabilities,
+  sameAuthorizationScope,
+} from "./facade-support.js";
+import { abortDocumentOutput, cancelDocumentRun } from "./facade-cancel.js";
+import { createDocumentInvocation } from "./facade-invocation.js";
+import {
+  DocumentOutputArtifactHostError,
+  type DocumentOutputArtifactHost,
+  type DocumentOutputArtifactStart,
+} from "./output-artifact-host.js";
+
+export { DocumentFacadeError } from "./errors.js";
 
 export class DocumentRunFacade {
   readonly #operations: Map<string, RegisteredDocumentOperation>;
@@ -38,6 +57,8 @@ export class DocumentRunFacade {
     private readonly remote: DocumentRuntimePort,
     private readonly artifacts: AiArtifactRuntime,
     private readonly grants: ExecutionGrantStore,
+    private readonly outputArtifacts?: DocumentOutputArtifactHost,
+    private readonly readiness?: ModuleAiOperationReadinessPortV1,
   ) {
     const handlers = new Map(
       hosts.aiOperationHandlers.map(({ registration, moduleName }) => [
@@ -82,11 +103,22 @@ export class DocumentRunFacade {
       );
     }
     await this.authorize(operation, context);
-    await this.requireCapabilities(
-      operation.definition.requiredCapabilities,
-      signal,
+    const outputEnabled = Boolean(
+      this.outputArtifacts?.hasBinding(operation.definition.key),
     );
-    assertInputSize(input, operation.definition.limits.maxInputBytes);
+    if (!outputEnabled) {
+      if (operation.definition.readiness) {
+        const projected = await this.readiness?.inspect({ operationKey });
+        if (!projected || projected.status !== "ready")
+          throw capabilityUnavailable();
+      }
+      await requireDocumentCapabilities(
+        this.remote,
+        operation.definition,
+        signal,
+      );
+    }
+    assertDocumentInputSize(input, operation.definition.limits.maxInputBytes);
     const maxArtifacts = operation.definition.limits.maxArtifacts ?? 1;
     if (!sources.length || sources.length > maxArtifacts) {
       throw new DocumentFacadeError(
@@ -113,7 +145,7 @@ export class DocumentRunFacade {
         503,
       );
     }
-    const governed = governOptions(input, operation.definition);
+    const governed = governDocumentOptions(input, operation.definition);
     const plan = await operation.registration.prepareDocument(governed, {
       actor: toModuleActor(context.actor),
       requestId: context.requestId,
@@ -130,82 +162,146 @@ export class DocumentRunFacade {
       ),
     );
     sources.forEach((source, index) =>
-      assertArtifactMetadata(source, rotated[index]!),
+      assertDocumentArtifactMetadata(source, rotated[index]!),
+    );
+    const scopedKey = scopedRuntimeIdempotencyKey(
+      context.actor.id,
+      operationKey,
+      idempotencyKey,
     );
+    const plannedRunId = documentRunId(scopedKey);
+    const invocation = createDocumentInvocation({
+      runId: plannedRunId,
+      operationKey,
+      options: plan.options ?? governed,
+      sources: rotated,
+      definition: operation.definition,
+      maxUnits,
+      maxArtifacts,
+    });
+    let output: DocumentOutputArtifactStart | undefined;
+    if (outputEnabled) {
+      try {
+        output = await this.outputArtifacts!.begin({
+          definition: operation.definition,
+          moduleName: operation.moduleName,
+          runId: plannedRunId,
+          idempotencyKey: scopedKey,
+          context,
+          invocation,
+        });
+        if (!output) throw capabilityUnavailable();
+      } catch (error) {
+        if (error instanceof DocumentFacadeError) throw error;
+        if (error instanceof DocumentOutputArtifactHostError) {
+          throw new DocumentFacadeError(
+            error.code,
+            error.message,
+            outputArtifactStatus(error.code),
+          );
+        }
+        throw capabilityUnavailable();
+      }
+    }
     const grant = this.grants.issue(operation.definition, context, 3_600);
     try {
       const created = await this.remote.start(
         {
-          kind: "document",
-          operationKey,
-          options: plan.options ?? governed,
-          sources: rotated.map(({ value, mediaType, byteSize, sha256 }) => ({
-            value,
-            mediaType,
-            byteSize,
-            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,
-            maxArtifacts,
-          },
-          providerEgress: resolveProviderEgress(operation.definition),
-          providerDataPolicy: operation.definition.providerDataPolicy,
+          ...invocation,
+          ...(output ? { outputArtifactSink: output.descriptor } : {}),
         },
-        scopedRuntimeIdempotencyKey(
-          context.actor.id,
-          operationKey,
-          idempotencyKey,
-        ),
+        scopedKey,
         signal,
+        output?.grant,
+      );
+      if (
+        output?.grant &&
+        !(await this.outputArtifacts?.confirmGrant(
+          output.scopeId,
+          output.grantGeneration,
+          output.grant,
+        ))
+      ) {
+        throw new DocumentRuntimeError(
+          "INVALID_RESPONSE",
+          "Document Runtime 未确认 Output Artifact Grant",
+          false,
+        );
+      }
+      if (output && created.runId !== output.runId) {
+        throw new DocumentRuntimeError(
+          "INVALID_RESPONSE",
+          "Document Runtime 未采用 Host Run ID",
+          false,
+        );
+      }
+      bindDocumentRunGrant(this.grants, grant, created.runId, context);
+      recordDocumentRunStart(
+        this.runtime,
+        operation.definition,
+        context,
+        created.runId,
+        rotated,
       );
-      this.grants.bindRun(grant.token, created.runId);
-      this.runtime.auditSink.recordEvent({
-        id: randomUUIDv7(),
-        action: operation.definition.auditAction,
-        outcome: "success",
-        actor: auditActor(context),
-        target: {
-          type: "document-run",
-          id: created.runId,
-          label: operationKey,
-        },
-        requestId: context.requestId,
-        metadata: {
-          artifactCount: rotated.length,
-          totalByteSize: rotated.reduce(
-            (total, artifact) => total + artifact.byteSize,
-            0,
-          ),
-          sha256: rotated.map(({ sha256 }) => sha256),
-          requiredCapabilities: operation.definition.requiredCapabilities,
-        },
-        occurredAt: new Date().toISOString(),
-      });
       return {
         ...created,
         eventsUrl: `/api/document/runs/${created.runId}/events`,
       };
     } catch (error) {
       this.grants.discard(grant.token);
+      if (output?.grant) {
+        await this.outputArtifacts
+          ?.rollbackPendingGrant(
+            output.scopeId,
+            output.grantGeneration,
+            output.grant,
+          )
+          .catch(() => undefined);
+      }
       if (error instanceof DocumentRuntimeError) {
-        throw new DocumentFacadeError(
-          error.code,
-          error.message,
-          runtimeErrorStatus(error.code),
-        );
+        throw documentRuntimeFacadeError(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 forbiddenRun();
+    }
+    await this.authorize(
+      {
+        definition: grant.operation,
+        feature: this.#operations.get(grant.operation.key)?.feature,
+      },
+      context,
+    );
+    if (!sameAuthorizationScope(grant.context, context)) throw forbiddenRun();
+    return grant;
+  }
+
+  async cancel(
+    runId: string,
+    reason: string | undefined,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ): Promise<Response> {
+    const grant = await this.authorizeRun(runId, context);
+    return cancelDocumentRun({
+      remote: this.remote,
+      runId,
+      reason,
+      signal,
+      outputBound: Boolean(
+        this.outputArtifacts?.hasBinding(grant.operation.key),
+      ),
+      abortOutput: () => abortDocumentOutput(this.outputArtifacts, runId),
+      abortUnknownOutput: () =>
+        abortDocumentOutput(this.outputArtifacts, runId, true),
+    });
   }
 
   private async authorize(
@@ -224,36 +320,6 @@ export class DocumentRunFacade {
       );
     }
   }
-
-  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 DocumentFacadeError) throw error;
-      throw capabilityUnavailable();
-    }
-  }
 }
 
 interface RegisteredDocumentOperation {
@@ -262,78 +328,3 @@ interface RegisteredDocumentOperation {
   registration?: ModuleAiOperationHandlerRegistration;
   moduleName?: string;
 }
-
-export class DocumentFacadeError extends Error {
-  constructor(
-    readonly code: string,
-    message: string,
-    readonly status: number,
-  ) {
-    super(message);
-    this.name = "DocumentFacadeError";
-  }
-}
-
-function governOptions(
-  input: ModuleAiJsonValue,
-  definition: ModuleAiOperationDefinition,
-) {
-  try {
-    return definition.providerDataPolicy
-      ? governProviderInput(input, definition.providerDataPolicy)
-      : input;
-  } catch (error) {
-    if (error instanceof ProviderInputGovernanceError) {
-      throw new DocumentFacadeError(
-        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 DocumentFacadeError(
-      "INVALID_INPUT",
-      "Document 输入超过上限",
-      400,
-    );
-  }
-}
-
-function assertArtifactMetadata(
-  submitted: ModuleAiArtifactRef,
-  resolved: ModuleAiArtifactRef,
-) {
-  if (
-    submitted.mediaType !== resolved.mediaType ||
-    submitted.byteSize !== resolved.byteSize ||
-    submitted.sha256 !== resolved.sha256
-  ) {
-    throw new DocumentFacadeError(
-      "ARTIFACT_UNAVAILABLE",
-      "Artifact 元数据不一致",
-      403,
-    );
-  }
-}
-
-function capabilityUnavailable() {
-  return new DocumentFacadeError(
-    "CAPABILITY_UNAVAILABLE",
-    "Document Runtime 缺少 Operation 所需能力",
-    503,
-  );
-}
-
-function runtimeErrorStatus(code: DocumentRuntimeError["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/document/output-artifact-composition.test.ts

@@ -0,0 +1,64 @@
+import { afterEach, expect, test } from "bun:test";
+import {
+  createDocumentOutputRuntime,
+  documentOutputCompositionReady,
+} from "./output-artifact-composition.js";
+
+const keys = [
+  "AI_OUTPUT_ARTIFACT_REFERENCE_SECRET",
+  "DOCUMENT_OUTPUT_ARTIFACT_SINK_IDENTITY",
+  "DOCUMENT_OUTPUT_ARTIFACT_SINK_RELEASE_DIGEST",
+] as const;
+const saved = new Map(keys.map((key) => [key, process.env[key]]));
+
+afterEach(() => {
+  for (const key of keys) {
+    const value = saved.get(key);
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+});
+
+test("生产缺少 DB 时 Output Artifact composition fail closed", () => {
+  expect(documentOutputCompositionReady(prerequisites())).toBe(false);
+});
+
+test("缺少 Sink facts 时不安装 Output Artifact runtime", () => {
+  expect(
+    documentOutputCompositionReady({
+      ...prerequisites({}),
+      sinkIdentity: undefined,
+    }),
+  ).toBe(false);
+});
+
+test("项目未声明 Output Artifact binding 时不安装 runtime", () => {
+  configureSink();
+  expect(
+    createDocumentOutputRuntime({
+      modules: [],
+      readiness: {} as never,
+      runtime: {} as never,
+      storage: {} as never,
+      resolveActor: async () => undefined,
+      db: {} as never,
+    }),
+  ).toBeUndefined();
+});
+
+function configureSink() {
+  process.env.AI_OUTPUT_ARTIFACT_REFERENCE_SECRET = "s".repeat(32);
+  process.env.DOCUMENT_OUTPUT_ARTIFACT_SINK_IDENTITY =
+    "windy-deployment-v1_7db61d8e-e50d-4f8a-9f3f-9b7a1d932e01";
+  process.env.DOCUMENT_OUTPUT_ARTIFACT_SINK_RELEASE_DIGEST = `sha256:${"a".repeat(64)}`;
+}
+
+function prerequisites(db?: object) {
+  return {
+    bindingCount: 1,
+    db,
+    referenceSecret: "s".repeat(32),
+    sinkIdentity: "windy-deployment-v1_7db61d8e-e50d-4f8a-9f3f-9b7a1d932e01",
+    sinkReleaseDigest: `sha256:${"a".repeat(64)}`,
+  };
+}

package/template/apps/server/src/document/output-artifact-composition.ts

@@ -0,0 +1,78 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import type { ModuleAiOperationReadinessPortV1 } from "@southwind-ai/server-sdk";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { RequestActor } from "../guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import type { createStorageRuntime } from "../storage/runtime.js";
+import { createDocumentOutputArtifactRuntime } from "./output-artifact-runtime.js";
+import { documentOutputArtifactBindings } from "../app/document-output-artifact-bindings.js";
+import { speechOutputArtifactBindings } from "../app/speech-output-artifact-bindings.js";
+
+export function createDocumentOutputRuntime(input: {
+  modules: readonly ModuleManifest[];
+  readiness: ModuleAiOperationReadinessPortV1;
+  runtime: ReturnType<typeof createServerRuntime>;
+  storage: ReturnType<typeof createStorageRuntime>;
+  resolveActor: (actorId: string) => Promise<RequestActor | undefined>;
+  db?: NodePgDatabase;
+}) {
+  const referenceSecret =
+    process.env.AI_OUTPUT_ARTIFACT_REFERENCE_SECRET?.trim();
+  const identity = process.env.DOCUMENT_OUTPUT_ARTIFACT_SINK_IDENTITY?.trim();
+  const releaseDigest =
+    process.env.DOCUMENT_OUTPUT_ARTIFACT_SINK_RELEASE_DIGEST?.trim();
+  const composition = {
+    bindingCount:
+      documentOutputArtifactBindings.length +
+      speechOutputArtifactBindings.length,
+    db: input.db,
+    referenceSecret,
+    sinkIdentity: identity,
+    sinkReleaseDigest: releaseDigest,
+  };
+  if (!documentOutputCompositionReady(composition)) return undefined;
+  return createDocumentOutputArtifactRuntime({
+    modules: input.modules,
+    bindings: documentOutputArtifactBindings,
+    speechBindings: speechOutputArtifactBindings,
+    readiness: input.readiness,
+    runtime: input.runtime,
+    storage: input.storage,
+    resolveActor: input.resolveActor,
+    referenceSecret: composition.referenceSecret,
+    readinessIdentity: {
+      identity: composition.sinkIdentity,
+      releaseDigest: composition.sinkReleaseDigest,
+      protocolVersion: 1,
+    },
+    db: composition.db,
+  });
+}
+
+interface DocumentOutputCompositionPrerequisites<TDatabase> {
+  readonly bindingCount: number;
+  readonly db?: TDatabase;
+  readonly referenceSecret?: string;
+  readonly sinkIdentity?: string;
+  readonly sinkReleaseDigest?: string;
+}
+
+type ReadyDocumentOutputComposition<TDatabase> =
+  DocumentOutputCompositionPrerequisites<TDatabase> & {
+    readonly db: TDatabase;
+    readonly referenceSecret: string;
+    readonly sinkIdentity: string;
+    readonly sinkReleaseDigest: string;
+  };
+
+export function documentOutputCompositionReady<TDatabase>(
+  input: DocumentOutputCompositionPrerequisites<TDatabase>,
+): input is ReadyDocumentOutputComposition<TDatabase> {
+  return (
+    input.bindingCount > 0 &&
+    Boolean(input.db) &&
+    Boolean(input.referenceSecret?.trim()) &&
+    Boolean(input.sinkIdentity?.trim()) &&
+    Boolean(input.sinkReleaseDigest?.trim())
+  );
+}

package/template/apps/server/src/document/output-artifact-fingerprint.contract.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, test } from "bun:test";
+import type { DocumentRuntimeOperation } from "./contracts.js";
+import { documentRuntimeRequestFingerprint } from "./output-artifact-fingerprint.js";
+
+interface FingerprintFixture {
+  contractVersion: 1;
+  request: DocumentRuntimeOperation & { runId: string };
+  excludedVariant: {
+    sourceValues: string[];
+    scope: string;
+    grantGeneration: number;
+    expiresAt: string;
+  };
+  invalidCanonicalJson: Array<{
+    label: string;
+    json: string;
+  }>;
+  expectedSha256: string;
+}
+
+const fixtureUrl = new URL(
+  "../../../../packages/server-sdk/contracts/document-runtime/v1/fingerprint-fixture.json",
+  import.meta.url,
+);
+
+describe("Document Runtime bilingual fingerprint fixture", () => {
+  test("TypeScript 与 Python 固定向量一致且排除临时 credential 坐标", async () => {
+    const fixture = (await Bun.file(fixtureUrl).json()) as FingerprintFixture;
+    expect(fixture.contractVersion).toBe(1);
+    expect(documentRuntimeRequestFingerprint(fixture.request)).toBe(
+      fixture.expectedSha256,
+    );
+
+    const variant: DocumentRuntimeOperation = {
+      ...fixture.request,
+      sources: fixture.request.sources.map((source, index) => ({
+        ...source,
+        value: fixture.excludedVariant.sourceValues[index]!,
+      })),
+      outputArtifactSink: {
+        ...fixture.request.outputArtifactSink!,
+        scope: fixture.excludedVariant.scope,
+        grantGeneration: fixture.excludedVariant.grantGeneration,
+        expiresAt: fixture.excludedVariant.expiresAt,
+      },
+    };
+    expect(documentRuntimeRequestFingerprint(variant)).toBe(
+      fixture.expectedSha256,
+    );
+  });
+
+  test("有序 source 与治理语义漂移会改变摘要", async () => {
+    const { request, expectedSha256 } = (await Bun.file(
+      fixtureUrl,
+    ).json()) as FingerprintFixture;
+    expect(
+      documentRuntimeRequestFingerprint({
+        ...request,
+        sources: [...request.sources].reverse(),
+      }),
+    ).not.toBe(expectedSha256);
+    expect(
+      documentRuntimeRequestFingerprint({
+        ...request,
+        dataClassification: "internal",
+      }),
+    ).not.toBe(expectedSha256);
+    expect(
+      documentRuntimeRequestFingerprint({
+        ...request,
+        outputArtifactSink: {
+          ...request.outputArtifactSink!,
+          policyDigest: "f".repeat(64),
+        },
+      }),
+    ).not.toBe(expectedSha256);
+  });
+
+  test("跨语言摘要拒绝无法精确表示的 JSON 整数", async () => {
+    const { request } = (await Bun.file(
+      fixtureUrl,
+    ).json()) as FingerprintFixture;
+    expect(() =>
+      documentRuntimeRequestFingerprint({
+        ...request,
+        options: { unsafe: Number.MAX_SAFE_INTEGER + 1 },
+      }),
+    ).toThrow("整数超出安全范围");
+  });
+
+  test("跨语言非法 canonical JSON 固定向量全部 fail closed", async () => {
+    const { request, invalidCanonicalJson } = (await Bun.file(
+      fixtureUrl,
+    ).json()) as FingerprintFixture;
+    for (const { json } of invalidCanonicalJson) {
+      expect(() =>
+        documentRuntimeRequestFingerprint({
+          ...request,
+          options: JSON.parse(json),
+        }),
+      ).toThrow();
+    }
+    expect(() =>
+      documentRuntimeRequestFingerprint({
+        ...request,
+        options: { nonfinite: Number.POSITIVE_INFINITY },
+      }),
+    ).toThrow("数字无效");
+  });
+});