create-windy 0.5.1 → 0.6.0

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

@@ -0,0 +1,95 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleAiOperationDefinition } from "@southwind-ai/modules";
+import { computeAiRuntimeOffersDigestV1 } from "@southwind-ai/server-sdk";
+import type { DocumentRuntimePort } from "./contracts.js";
+import { requireDocumentCapabilities } from "./facade-support.js";
+import { documentManifest } from "./output-artifact-manifest.test-support.js";
+
+const definition = documentManifest().aiOperations![0]!;
+const identity = "windy-deployment-v1_11c93162-e5f0-40af-93ce-9771a4bf12ed";
+const releaseDigest = `sha256:${"9".repeat(64)}`;
+const checkedAt = "2026-07-31T12:00:00.000Z";
+const validUntil = "2026-07-31T12:01:00.000Z";
+
+describe("Document Host readiness compatibility", () => {
+  test("0.5.2 legacy capabilities 与公共 V1 offers 均可服务无输出 Operation", async () => {
+    await expect(
+      inspect({ status: "ready", capabilities: ["document.ocr"] }),
+    ).resolves.toBeUndefined();
+    await expect(inspect(v1Snapshot())).resolves.toBeUndefined();
+  });
+
+  test("V1 freshness 使用半开区间，完成时等于 validUntil 即失败关闭", async () => {
+    await expect(inspect(v1Snapshot(), validUntil)).rejects.toMatchObject({
+      code: "CAPABILITY_UNAVAILABLE",
+      status: 503,
+    });
+  });
+
+  test("声明未知 schemaVersion 的 payload 不得降级为 legacy", async () => {
+    await expect(
+      inspect({
+        schemaVersion: 2,
+        status: "ready",
+        capabilities: ["document.ocr"],
+      }),
+    ).rejects.toMatchObject({ code: "CAPABILITY_UNAVAILABLE" });
+  });
+});
+
+function inspect(snapshot: unknown, now = "2026-07-31T12:00:59.999Z") {
+  return requireDocumentCapabilities(
+    runtime(snapshot),
+    definition,
+    new AbortController().signal,
+    () => new Date(now),
+  );
+}
+
+function runtime(snapshot: unknown): DocumentRuntimePort {
+  return {
+    async health() {
+      return Response.json(snapshot);
+    },
+  } as DocumentRuntimePort;
+}
+
+function v1Snapshot(operation: ModuleAiOperationDefinition = definition) {
+  const offer = {
+    variant: "ocr",
+    capabilities: [...operation.requiredCapabilities],
+    inputModalities: operation.inputModalities ?? ["document"],
+    outputModalities: ["text"],
+    limits: {
+      ...operation.limits,
+      maxConcurrentRuns: 1,
+      maxQueueDepth: 0,
+    },
+  };
+  const offersDigest = computeAiRuntimeOffersDigestV1([offer]);
+  const deployment = {
+    key: "document.intranet-ocr",
+    identity,
+    releaseDigest,
+    offersDigest,
+  };
+  return {
+    schemaVersion: 1,
+    status: "ready",
+    configured: true,
+    runtimeKind: "document",
+    observedAt: checkedAt,
+    downstreamProbe: {
+      status: "passed",
+      checkedAt,
+      validUntil,
+      latencyMs: 1,
+      deploymentIdentity: identity,
+      releaseDigest,
+      offersDigest,
+    },
+    deployment,
+    offers: [offer],
+    unavailableReasons: [],
+  };
+}

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

@@ -0,0 +1,297 @@
+import { randomUUIDv7 } from "bun";
+import type { ModuleAiOperationDefinition } from "@southwind-ai/modules";
+import type {
+  ModuleAiArtifactRef,
+  ModuleAiJsonValue,
+} from "@southwind-ai/server-sdk";
+import {
+  parseAiRuntimeReadinessV1,
+  projectAiOperationReadinessV1,
+} from "@southwind-ai/server-sdk";
+import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
+import type { RequestGuardContext } from "../guards.js";
+import { auditActor } from "../guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import {
+  governProviderInput,
+  ProviderInputGovernanceError,
+} from "../agent/provider-input-governance.js";
+import {
+  ExecutionGrantStore,
+  type ExecutionGrant,
+} from "../agent/execution-grants.js";
+import { DocumentRuntimeError } from "./contracts.js";
+import type { DocumentRuntimePort } from "./contracts.js";
+import { DocumentFacadeError } from "./errors.js";
+
+export function governDocumentOptions(
+  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;
+  }
+}
+
+export function assertDocumentInputSize(
+  value: ModuleAiJsonValue,
+  maxBytes: number,
+) {
+  if (new TextEncoder().encode(JSON.stringify(value)).byteLength > maxBytes) {
+    throw new DocumentFacadeError(
+      "INVALID_INPUT",
+      "Document 输入超过上限",
+      400,
+    );
+  }
+}
+
+export function assertDocumentArtifactMetadata(
+  submitted: ModuleAiArtifactRef,
+  resolved: ModuleAiArtifactRef,
+) {
+  if (
+    submitted.mediaType !== resolved.mediaType ||
+    submitted.byteSize !== resolved.byteSize ||
+    submitted.sha256 !== resolved.sha256
+  ) {
+    throw new DocumentFacadeError(
+      "ARTIFACT_UNAVAILABLE",
+      "Artifact 元数据不一致",
+      403,
+    );
+  }
+}
+
+export function documentRunId(scopedIdempotencyKey: string): string {
+  if (!/^[a-f0-9]{64}$/.test(scopedIdempotencyKey)) {
+    throw new DocumentFacadeError("INVALID_INPUT", "Document 幂等键无效", 400);
+  }
+  return `doc_${scopedIdempotencyKey}`;
+}
+
+export function sameAuthorizationScope(
+  original: RequestGuardContext,
+  current: RequestGuardContext,
+): boolean {
+  try {
+    return (
+      original.actor.id === current.actor.id &&
+      captureAuthorizationScope(original.actor.scopeContext).hash ===
+        captureAuthorizationScope(current.actor.scopeContext).hash
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function recordDocumentRunStart(
+  runtime: ReturnType<typeof createServerRuntime>,
+  operation: ModuleAiOperationDefinition,
+  context: RequestGuardContext,
+  runId: string,
+  artifacts: readonly Pick<ModuleAiArtifactRef, "byteSize" | "sha256">[],
+) {
+  runtime.auditSink.recordEvent({
+    id: randomUUIDv7(),
+    action: operation.auditAction,
+    outcome: "success",
+    actor: auditActor(context),
+    target: {
+      type: "document-run",
+      id: runId,
+      label: operation.key,
+    },
+    requestId: context.requestId,
+    metadata: {
+      artifactCount: artifacts.length,
+      totalByteSize: artifacts.reduce(
+        (total, artifact) => total + artifact.byteSize,
+        0,
+      ),
+      sha256: artifacts.map(({ sha256 }) => sha256),
+      requiredCapabilities: operation.requiredCapabilities,
+    },
+    occurredAt: new Date().toISOString(),
+  });
+}
+
+export function bindDocumentRunGrant(
+  store: ExecutionGrantStore,
+  grant: ExecutionGrant,
+  runId: string,
+  context: RequestGuardContext,
+): void {
+  try {
+    store.bindRun(grant.token, runId);
+  } catch (error) {
+    try {
+      const existing = store.requireRun(runId, context.actor.id);
+      if (
+        existing.operation.key !== grant.operation.key ||
+        !sameAuthorizationScope(existing.context, context)
+      ) {
+        throw error;
+      }
+      store.discard(grant.token);
+    } catch {
+      throw error;
+    }
+  }
+}
+
+export function capabilityUnavailable() {
+  return new DocumentFacadeError(
+    "CAPABILITY_UNAVAILABLE",
+    "Document Runtime 缺少 Operation 所需能力",
+    503,
+  );
+}
+
+export async function requireDocumentCapabilities(
+  remote: DocumentRuntimePort,
+  definition: ModuleAiOperationDefinition,
+  signal: AbortSignal,
+  now: () => Date = () => new Date(),
+) {
+  let response: Response;
+  try {
+    response = await remote.health(signal);
+  } catch {
+    throw capabilityUnavailable();
+  }
+  if (!response.ok) throw capabilityUnavailable();
+  try {
+    const value: unknown = await response.json();
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      throw capabilityUnavailable();
+    }
+    const legacy = value as Record<string, unknown>;
+    if (Object.hasOwn(legacy, "schemaVersion")) {
+      if (legacy.schemaVersion !== 1) throw capabilityUnavailable();
+      requireV1DocumentCapabilities(value, definition, now());
+      return;
+    }
+    const capabilities = Array.isArray(legacy.capabilities)
+      ? legacy.capabilities.filter(
+          (item): item is string => typeof item === "string",
+        )
+      : [];
+    if (
+      legacy.status !== "ready" ||
+      definition.requiredCapabilities.some(
+        (capability) => !capabilities.includes(capability),
+      )
+    ) {
+      throw capabilityUnavailable();
+    }
+  } catch (error) {
+    if (error instanceof DocumentFacadeError) throw error;
+    throw capabilityUnavailable();
+  }
+}
+
+function requireV1DocumentCapabilities(
+  snapshot: unknown,
+  definition: ModuleAiOperationDefinition,
+  now: Date,
+): void {
+  const nowIso = now.toISOString();
+  const parsed = parseAiRuntimeReadinessV1(snapshot, nowIso);
+  if (
+    !parsed.ok ||
+    parsed.value.status !== "ready" ||
+    parsed.value.runtimeKind !== "document"
+  ) {
+    throw capabilityUnavailable();
+  }
+  const projected = projectAiOperationReadinessV1(
+    {
+      schemaVersion: 1,
+      operationKey: definition.key,
+      runtimeKind: "document",
+      expectedDeployment: parsed.value.deployment,
+      requiredCapabilities: definition.requiredCapabilities,
+      inputModalities: definition.inputModalities ?? ["document"],
+      outputModalities: ["text"],
+      limits: definition.limits,
+      resources: { minConcurrentRuns: 1, minQueueDepth: 0 },
+    },
+    snapshot,
+    { now: nowIso },
+  );
+  if (projected.status !== "ready") throw capabilityUnavailable();
+}
+
+export function documentRuntimeFacadeError(
+  code: DocumentRuntimeError["code"],
+): DocumentFacadeError {
+  if (code === "CAPABILITY_UNAVAILABLE") {
+    return new DocumentFacadeError(
+      code,
+      "Document Runtime 缺少所需能力",
+      503,
+      true,
+    );
+  }
+  if (code === "RUN_CONFLICT") {
+    return new DocumentFacadeError(code, "Document 幂等语义冲突", 409, false);
+  }
+  if (code === "FORBIDDEN") {
+    return new DocumentFacadeError(
+      code,
+      "Document Runtime 拒绝访问",
+      403,
+      false,
+    );
+  }
+  if (code === "BUDGET_EXCEEDED" || code === "INVALID_INPUT") {
+    return new DocumentFacadeError(
+      code,
+      code === "BUDGET_EXCEEDED"
+        ? "Document Runtime 执行预算超限"
+        : "Document Runtime 拒绝无效输入",
+      400,
+      false,
+    );
+  }
+  if (code === "INVALID_RESPONSE") {
+    return new DocumentFacadeError(
+      code,
+      "Document Runtime 响应无效",
+      503,
+      false,
+    );
+  }
+  return new DocumentFacadeError(
+    "RUNTIME_UNAVAILABLE",
+    "Document Runtime 暂时不可用",
+    503,
+    true,
+  );
+}
+
+export function outputArtifactStatus(
+  code: "CAPABILITY_UNAVAILABLE" | "RUN_CONFLICT",
+) {
+  return code === "RUN_CONFLICT" ? 409 : 503;
+}
+
+export function forbiddenRun(): DocumentFacadeError {
+  return new DocumentFacadeError(
+    "FORBIDDEN",
+    "Document Run 当前授权已失效",
+    403,
+  );
+}