create-windy 0.5.2 → 0.6.0

package/template/apps/server/src/ai-output-artifact/storage-writer.ts

@@ -0,0 +1,103 @@
+import type {
+  ModuleStorageWritePortV1,
+  ModuleUploadPolicy,
+} from "@southwind-ai/server-sdk";
+import type { StorageRuntime } from "../storage/runtime.js";
+import { createModuleStorageWritePort } from "../module-host/storage-write-port.js";
+import type {
+  ModuleStorageScope,
+  ModuleUploadDecision,
+} from "../module-host/storage-port.js";
+import type { AiOutputArtifactScope } from "./contracts.js";
+import { aiOutputArtifactReadinessPurpose } from "./policy.js";
+
+export interface AiOutputArtifactStorageAudit {
+  record(scope: AiOutputArtifactScope, decision: ModuleUploadDecision): void;
+}
+
+export class AiOutputArtifactStorageWriterFactory {
+  constructor(
+    private readonly storage: StorageRuntime,
+    private readonly audit: AiOutputArtifactStorageAudit,
+    private readonly now: () => Date = () => new Date(),
+  ) {
+    this.storage.uploads.setPolicy({
+      purpose: "ai-runtime-output",
+      maxByteSize: 512 * 1024 * 1024,
+      maxPartByteSize: 8 * 1024 * 1024,
+      sessionTtlMs: 61 * 60_000,
+      allowedTypes: {
+        "application/pdf": ["pdf"],
+        "audio/wav": ["wav"],
+      },
+      signature: "none",
+    });
+    this.storage.uploads.setPolicy({
+      purpose: aiOutputArtifactReadinessPurpose,
+      maxByteSize: 64 * 1024,
+      maxPartByteSize: 64 * 1024,
+      sessionTtlMs: 60_000,
+      allowedTypes: { "application/pdf": ["pdf"] },
+      signature: "none",
+    });
+  }
+
+  create(
+    scope: AiOutputArtifactScope,
+    signal: AbortSignal,
+  ): ModuleStorageWritePortV1 {
+    return createModuleStorageWritePort(this.storage, {
+      moduleName: scope.moduleName,
+      ownerId: scope.actorId,
+      purposes: new Set([scope.purpose]),
+      uploadPolicies: new Map([
+        [scope.purpose, uploadPolicy(scope, this.now())],
+      ]),
+      authorizationBinding: {
+        moduleName: scope.moduleName,
+        scopeHash: scope.scopeHash,
+      },
+      actor: {
+        id: scope.actorId,
+        type: "user",
+        name: scope.actorId,
+        roleCodes: [],
+        permissionKeys: [],
+      },
+      requestId: scope.requestId,
+      signal,
+      recordUploadDecision: (decision) => this.audit.record(scope, decision),
+    } satisfies ModuleStorageScope);
+  }
+}
+
+function uploadPolicy(
+  scope: AiOutputArtifactScope,
+  now: Date,
+): ModuleUploadPolicy {
+  const retention = Date.parse(scope.fileExpiresAt) - now.getTime() - 1_000;
+  if (
+    !Number.isSafeInteger(retention) ||
+    retention < 60_000 ||
+    retention > 365 * 24 * 60 * 60_000
+  ) {
+    throw new Error("AI Output Artifact 文件剩余保留期无效");
+  }
+  return {
+    purpose: scope.purpose,
+    maxByteSize: scope.maxArtifactBytes,
+    maxPartByteSize: Math.min(scope.maxArtifactBytes, 8 * 1024 * 1024),
+    sessionTtlMs: Math.max(
+      60_000,
+      Date.parse(scope.scopeExpiresAt) - Date.parse(scope.createdAt),
+    ),
+    fileRetentionMs: retention,
+    allowedTypes: Object.fromEntries(
+      scope.allowedMediaTypes.map((mediaType) => [
+        mediaType,
+        mediaType === "application/pdf" ? ["pdf"] : ["wav"],
+      ]),
+    ),
+    signature: "none",
+  };
+}

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

@@ -0,0 +1,161 @@
+import { createHash } from "node:crypto";
+import { buildScopeContext } from "../data-access/context.js";
+import type { RequestGuardContext } from "../guards.js";
+import { createStorageRuntime } from "../storage/runtime.js";
+import { AiOutputArtifactCleanupService } from "./cleanup.js";
+import { InMemoryAiOutputArtifactRepository } from "./memory-repository.js";
+import { AiOutputArtifactPolicyRegistry } from "./policy.js";
+import { AiOutputArtifactReferenceCodec } from "./reference-codec.js";
+import { AiOutputArtifactService } from "./service.js";
+import { AiOutputArtifactStorageWriterFactory } from "./storage-writer.js";
+
+export function createOutputArtifactFixture() {
+  let now = new Date("2026-07-31T12:00:00.000Z");
+  const repository = new InMemoryAiOutputArtifactRepository();
+  const storage = createStorageRuntime({}, undefined, undefined, () => now);
+  const readOutcomes: string[] = [];
+  const writers = new AiOutputArtifactStorageWriterFactory(
+    storage,
+    { record: () => undefined },
+    () => now,
+  );
+  const service = new AiOutputArtifactService({
+    repository,
+    storage,
+    writers,
+    references: new AiOutputArtifactReferenceCodec("s".repeat(32)),
+    authorizeRead: async (scope) => ({
+      actorId: scope.actorId,
+      scopeHash: scope.scopeHash,
+      requestId: "request-read-test",
+    }),
+    recordRead: (_scope, _artifact, outcome) => readOutcomes.push(outcome),
+    now: () => now,
+  });
+  const cleanup = new AiOutputArtifactCleanupService(
+    repository,
+    storage,
+    writers,
+    () => now,
+  );
+  const prepare = (
+    idempotencyKey: string,
+    classification: "public" | "internal" | "sensitive" = "sensitive",
+    options: {
+      runId?: string;
+      outputKind?: string;
+      maxDurationSeconds?: number;
+    } = {},
+  ) => {
+    const outputKind = options.outputKind ?? "searchable-pdf";
+    const policy = new AiOutputArtifactPolicyRegistry().resolve({
+      runtimeKind: "document",
+      outputKind,
+      dataClassification: classification,
+      operationLimits: outputLimits(options.maxDurationSeconds),
+      readinessLimits: outputLimits(options.maxDurationSeconds),
+      runtimeLimits: outputLimits(options.maxDurationSeconds),
+    });
+    return service.beginScope({
+      runId: options.runId ?? "doc_test_run",
+      moduleName: "evidence",
+      operationKey: "evidence.document.ocr",
+      runtimeKind: "document",
+      idempotencyKey,
+      invocationDigest: "c".repeat(64),
+      dataClassification: classification,
+      deploymentIdentity:
+        "windy-deployment-v1_7db61d8e-e50d-4f8a-9f3f-9b7a1d932e01",
+      releaseDigest: `sha256:${"a".repeat(64)}`,
+      offersDigest: `sha256:${"b".repeat(64)}`,
+      policy,
+      context: guardContext(),
+    });
+  };
+  return {
+    repository,
+    storage,
+    writers,
+    service,
+    cleanup,
+    readOutcomes,
+    setNow(value: string) {
+      now = new Date(value);
+    },
+    prepare,
+    async begin(
+      idempotencyKey: string,
+      classification: "public" | "internal" | "sensitive" = "sensitive",
+      options: {
+        runId?: string;
+        outputKind?: string;
+        maxDurationSeconds?: number;
+      } = {},
+    ) {
+      const prepared = await prepare(idempotencyKey, classification, options);
+      if (!prepared.grant || !prepared.descriptor) return prepared;
+      const accepted = await service.acceptGrant(
+        prepared.scope.scopeId,
+        prepared.descriptor.grantGeneration,
+        prepared.grant,
+      );
+      return { ...prepared, scope: accepted };
+    },
+  };
+}
+
+export function outputManifest(bytes: Uint8Array) {
+  return {
+    contractVersion: 1 as const,
+    outputKey: "searchable-pdf",
+    filename: "searchable.pdf",
+    mediaType: "application/pdf",
+    byteSize: bytes.byteLength,
+    sha256: outputHash(bytes),
+    outputKind: "searchable-pdf",
+  };
+}
+
+export function outputHash(bytes: Uint8Array) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+export function outputByteStream(bytes: Uint8Array) {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+}
+
+export function outputLimits(maxDurationSeconds = 600) {
+  return {
+    maxArtifactBytes: 1024 * 1024,
+    maxArtifacts: 2,
+    maxTotalBytes: 1024 * 1024,
+    maxDurationSeconds,
+  };
+}
+
+function guardContext(): RequestGuardContext {
+  return {
+    requestId: "request-test",
+    actor: {
+      id: "user-1",
+      type: "user",
+      name: "测试用户",
+      roleCodes: ["analyst"],
+      permissionKeys: ["evidence.document.ocr.execute"],
+      scopeContext: buildScopeContext("user-1", undefined, [
+        {
+          id: "analyst",
+          code: "analyst",
+          dataScope: "self",
+          departmentIds: [],
+        },
+      ]),
+    },
+    startedAt: "2026-07-31T12:00:00.000Z",
+  };
+}

package/template/apps/server/src/ai-runtime-readiness/health-response.ts

@@ -0,0 +1,92 @@
+const MAX_HEALTH_RESPONSE_BYTES = 64 * 1024;
+
+export async function readBoundedHealthJson(
+  response: Response,
+  signal: AbortSignal,
+): Promise<unknown> {
+  signal.throwIfAborted();
+  if (response.status !== 200 && response.status !== 503) {
+    throw new Error("AI runtime health status is not supported");
+  }
+  const contentType = response.headers
+    .get("content-type")
+    ?.split(";", 1)[0]
+    ?.trim()
+    .toLowerCase();
+  if (contentType !== "application/json") {
+    throw new Error("AI runtime health response is not JSON");
+  }
+  if (!response.body) {
+    throw new Error("AI runtime health response body is missing");
+  }
+  const contentLength = Number(response.headers.get("content-length"));
+  if (
+    Number.isFinite(contentLength) &&
+    contentLength > MAX_HEALTH_RESPONSE_BYTES
+  ) {
+    throw new Error("AI runtime health response is too large");
+  }
+
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  try {
+    while (true) {
+      const { done, value } = await settleBeforeHealthDeadline(
+        reader.read(),
+        signal,
+      );
+      if (done) break;
+      total += value.byteLength;
+      if (total > MAX_HEALTH_RESPONSE_BYTES) {
+        void reader.cancel("health-response-too-large").catch(() => undefined);
+        throw new Error("AI runtime health response is too large");
+      }
+      chunks.push(value);
+    }
+  } finally {
+    if (signal.aborted)
+      void reader.cancel("health-response-aborted").catch(() => undefined);
+    try {
+      reader.releaseLock();
+    } catch {
+      // A hostile stream may retain a pending read after abort; do not wait for it.
+    }
+  }
+
+  signal.throwIfAborted();
+  const bytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  const result = JSON.parse(text) as unknown;
+  signal.throwIfAborted();
+  return result;
+}
+
+/** Enforces an AbortSignal deadline even when the downstream ignores it. */
+export function settleBeforeHealthDeadline<T>(
+  operation: Promise<T>,
+  signal: AbortSignal,
+): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    let settled = false;
+    const finish = (next: () => void) => {
+      if (settled) return;
+      settled = true;
+      signal.removeEventListener("abort", abort);
+      next();
+    };
+    const abort = () =>
+      finish(() => reject(new Error("AI runtime health deadline exceeded")));
+    operation.then(
+      (value) => finish(() => resolve(value)),
+      (error: unknown) => finish(() => reject(error)),
+    );
+    if (signal.aborted) abort();
+    else signal.addEventListener("abort", abort, { once: true });
+  });
+}

package/template/apps/server/src/ai-runtime-readiness/operation-port-trust.test.ts

@@ -0,0 +1,66 @@
+import { expect, test } from "bun:test";
+import {
+  createPort,
+  degradedSnapshot,
+  expectProbeFailure,
+  offersDigest,
+  operationKey,
+  readySnapshot,
+  releaseDigest,
+} from "./operation-port.test-support.js";
+import { AiRuntimeReadinessTrustStoreV1 } from "./trust-store.js";
+
+test("Readiness Host 亲见 full 后可跨 Port 接受只减不增的局部降级", async () => {
+  const trustStore = new AiRuntimeReadinessTrustStoreV1();
+  const full = createPort(
+    async () => Response.json(readySnapshot(), { status: 200 }),
+    5_000,
+    trustStore,
+  );
+  expect((await full.inspect({ operationKey })).status).toBe("ready");
+
+  const degraded = createPort(
+    async () => Response.json(degradedSnapshot(), { status: 200 }),
+    5_000,
+    trustStore,
+  );
+  await expect(degraded.inspect({ operationKey })).resolves.toMatchObject({
+    status: "ready",
+    deployment: { releaseDigest, offersDigest },
+    offers: [{ capabilities: ["document.ocr"] }],
+  });
+});
+
+test("首次即降级或 payload 自报 pin 都不能建立 Host 信任", async () => {
+  const snapshot = degradedSnapshot();
+  const deployment = snapshot.deployment as Record<string, unknown>;
+  const probe = snapshot.downstreamProbe as Record<string, unknown>;
+  deployment.pinnedReleaseDigest = releaseDigest;
+  deployment.pinnedOffersDigest = offersDigest;
+  probe.pinnedReleaseDigest = releaseDigest;
+  probe.pinnedOffersDigest = offersDigest;
+  await expectProbeFailure(
+    createPort(async () => Response.json(snapshot, { status: 200 })),
+  );
+});
+
+test("Host full 历史拒绝 Runtime 当前能力扩张", async () => {
+  const trustStore = new AiRuntimeReadinessTrustStoreV1();
+  const full = createPort(
+    async () => Response.json(readySnapshot(), { status: 200 }),
+    5_000,
+    trustStore,
+  );
+  expect((await full.inspect({ operationKey })).status).toBe("ready");
+  const expanded = degradedSnapshot([
+    "document.ocr",
+    "runtime.untrusted-expansion",
+  ]);
+  await expectProbeFailure(
+    createPort(
+      async () => Response.json(expanded, { status: 200 }),
+      5_000,
+      trustStore,
+    ),
+  );
+});

package/template/apps/server/src/ai-runtime-readiness/operation-port.test-support.ts

@@ -0,0 +1,143 @@
+import { expect } from "bun:test";
+import type { ModuleManifest } from "@southwind-ai/modules";
+import { computeAiRuntimeOffersDigestV1 } from "@southwind-ai/server-sdk";
+import {
+  documentManifest,
+  operationKey,
+} from "../document/output-artifact-manifest.test-support.js";
+import { createModuleAiOperationReadinessPort } from "./operation-port.js";
+import type { AiRuntimeReadinessTrustStoreV1 } from "./trust-store.js";
+
+export { operationKey };
+export const observedAt = "2026-08-05T00:00:00.000Z";
+const validUntil = "2026-08-05T00:01:00.000Z";
+export const deploymentIdentity =
+  "windy-deployment-v1_7db61d8e-e50d-4f8a-9f3f-9b7a1d932e01";
+export const releaseDigest = `sha256:${"a".repeat(64)}` as const;
+const offers = [
+  {
+    variant: "ocr",
+    capabilities: ["document.ocr", "document.layout"],
+    inputModalities: ["document"],
+    outputModalities: ["document", "text"],
+    limits: {
+      maxDurationSeconds: 60,
+      maxInputBytes: 4_096,
+      maxOutputBytes: 4_096,
+      maxUnits: 20,
+      maxArtifacts: 2,
+      maxConcurrentRuns: 1,
+      maxQueueDepth: 0,
+    },
+  },
+] as const;
+export const offersDigest = computeAiRuntimeOffersDigestV1(offers);
+
+export function createPort(
+  health: (signal?: AbortSignal) => Promise<Response>,
+  probeTimeoutMs = 5_000,
+  trustStore?: AiRuntimeReadinessTrustStoreV1,
+) {
+  return createModuleAiOperationReadinessPort({
+    modules: [readinessManifest()],
+    sources: [{ kind: "document", health }],
+    runtime: {} as never,
+    now: () => new Date(observedAt),
+    probeTimeoutMs,
+    trustStore,
+  });
+}
+
+export function degradedSnapshot(capabilities = ["document.ocr"]) {
+  const snapshot = readySnapshot();
+  const currentOffers = snapshot.offers.map((offer) => ({
+    ...offer,
+    capabilities,
+  }));
+  const currentDigest = computeAiRuntimeOffersDigestV1(currentOffers);
+  return {
+    ...snapshot,
+    downstreamProbe: {
+      ...snapshot.downstreamProbe,
+      offersDigest: currentDigest,
+    },
+    deployment: { ...snapshot.deployment, offersDigest: currentDigest },
+    offers: currentOffers,
+  };
+}
+
+function readinessManifest(): ModuleManifest {
+  const manifest = documentManifest();
+  const operation = manifest.aiOperations?.[0];
+  if (!operation) throw new Error("测试 Manifest 缺少 Operation");
+  return {
+    ...manifest,
+    aiOperations: [
+      {
+        ...operation,
+        readiness: {
+          contractVersion: 1,
+          variant: "ocr",
+          inputModalities: ["document"],
+          outputModalities: ["document", "text"],
+          expectedDeployment: {
+            key: "document.intranet",
+            identity: deploymentIdentity,
+            releaseDigest,
+            offersDigest,
+          },
+          minConcurrentRuns: 1,
+          minQueueDepth: 0,
+        },
+      },
+    ],
+  };
+}
+
+export function readySnapshot() {
+  return {
+    schemaVersion: 1,
+    runtimeKind: "document",
+    observedAt,
+    configured: true,
+    status: "ready",
+    downstreamProbe: {
+      status: "passed",
+      checkedAt: observedAt,
+      validUntil,
+      latencyMs: 1,
+      deploymentIdentity,
+      releaseDigest,
+      offersDigest,
+    },
+    deployment: {
+      key: "document.intranet",
+      identity: deploymentIdentity,
+      releaseDigest,
+      offersDigest,
+    },
+    offers,
+    unavailableReasons: [],
+  };
+}
+
+export function unavailableSnapshot() {
+  return {
+    schemaVersion: 1,
+    runtimeKind: "document",
+    observedAt,
+    configured: false,
+    status: "unavailable",
+    downstreamProbe: { status: "not-run", reason: "NOT_CONFIGURED" },
+    deployment: null,
+    offers: [],
+    unavailableReasons: [{ code: "RUNTIME_NOT_CONFIGURED", retryable: true }],
+  };
+}
+
+export async function expectProbeFailure(port: ReturnType<typeof createPort>) {
+  await expect(port.inspect({ operationKey })).resolves.toMatchObject({
+    status: "unavailable",
+    unavailableReasons: [{ code: "DOWNSTREAM_PROBE_FAILED", retryable: true }],
+  });
+}