create-windy 0.5.2 → 0.6.0

package/template/packages/server-sdk/src/ai-runtime-readiness.contract-support.ts

@@ -0,0 +1,139 @@
+import { readFile } from "node:fs/promises";
+import type {
+  AiOperationReadinessRequirementV1,
+  AiRuntimeModalityV1,
+  AiRuntimeOfferV1,
+} from "./ai-runtime-readiness.js";
+import { computeAiRuntimeOffersDigestV1 } from "./ai-runtime-readiness-digest.js";
+
+export interface ReadinessContractFixture {
+  readonly name: string;
+  readonly now: string;
+  readonly operation: AiOperationReadinessRequirementV1;
+  readonly snapshot: unknown;
+}
+
+export const readinessContractFixtures = await Promise.all(
+  ["document", "speech", "embedding", "vlm"].map(loadFixture),
+);
+
+export function unavailableSnapshot(
+  fixture: ReadinessContractFixture,
+  downstreamProbe: Record<string, unknown>,
+) {
+  const snapshot = cloneRecord(fixture.snapshot);
+  snapshot.status = "unavailable";
+  snapshot.configured = true;
+  snapshot.downstreamProbe = downstreamProbe;
+  snapshot.offers = [];
+  return snapshot;
+}
+
+export function withExpectedDeployment(
+  fixture: ReadinessContractFixture,
+  changes: Partial<AiOperationReadinessRequirementV1["expectedDeployment"]>,
+): AiOperationReadinessRequirementV1 {
+  return {
+    ...fixture.operation,
+    expectedDeployment: {
+      ...fixture.operation.expectedDeployment,
+      ...changes,
+    },
+  };
+}
+
+export function firstOffer(
+  value: ReadinessContractFixture | Record<string, unknown>,
+) {
+  const snapshot =
+    "snapshot" in value ? cloneRecord(value.snapshot) : cloneRecord(value);
+  const offers = snapshot.offers;
+  if (!Array.isArray(offers) || !offers[0]) {
+    throw new Error("readiness fixture offer 缺失");
+  }
+  return cloneRecord(offers[0]);
+}
+
+export function firstProbe(fixture: ReadinessContractFixture) {
+  const snapshot = cloneRecord(fixture.snapshot);
+  return cloneRecord(snapshot.downstreamProbe);
+}
+
+export function withAttestedOffers(
+  fixture: ReadinessContractFixture,
+  offers: readonly Record<string, unknown>[],
+): ReadinessContractFixture {
+  const typedOffers = offers.map((offer) => {
+    const parsed: unknown = JSON.parse(JSON.stringify(offer));
+    return parsed as AiRuntimeOfferV1;
+  });
+  const offersDigest = computeAiRuntimeOffersDigestV1(typedOffers);
+  const snapshot = cloneRecord(fixture.snapshot);
+  const deployment = cloneRecord(snapshot.deployment);
+  const downstreamProbe = cloneRecord(snapshot.downstreamProbe);
+  deployment.offersDigest = offersDigest;
+  downstreamProbe.offersDigest = offersDigest;
+  snapshot.deployment = deployment;
+  snapshot.downstreamProbe = downstreamProbe;
+  snapshot.offers = typedOffers;
+  return {
+    ...fixture,
+    operation: {
+      ...fixture.operation,
+      expectedDeployment: {
+        ...fixture.operation.expectedDeployment,
+        offersDigest,
+      },
+    },
+    snapshot,
+  };
+}
+
+export function missingModality(
+  existing: readonly string[],
+): AiRuntimeModalityV1 {
+  const candidates: readonly AiRuntimeModalityV1[] = [
+    "text",
+    "image",
+    "audio",
+    "video",
+    "document",
+    "embedding",
+  ];
+  const missing = candidates.find((candidate) => !existing.includes(candidate));
+  if (!missing) throw new Error("readiness fixture modality 已覆盖全集");
+  return missing;
+}
+
+export function cloneRecord(value: unknown): Record<string, unknown> {
+  const cloned: unknown = structuredClone(value);
+  if (!cloned || typeof cloned !== "object" || Array.isArray(cloned)) {
+    throw new Error("readiness fixture 不是对象");
+  }
+  return cloned as Record<string, unknown>;
+}
+
+async function loadFixture(name: string): Promise<ReadinessContractFixture> {
+  const body = await readFile(
+    new URL(
+      `../contracts/ai-runtime-readiness/v1/${name}.json`,
+      import.meta.url,
+    ),
+    "utf8",
+  );
+  const raw: unknown = JSON.parse(body);
+  const record = cloneRecord(raw);
+  if (
+    typeof record.name !== "string" ||
+    typeof record.now !== "string" ||
+    !record.operation
+  ) {
+    throw new Error(`readiness fixture ${name} 无效`);
+  }
+  return {
+    name: record.name,
+    now: record.now,
+    operation: record.operation as AiOperationReadinessRequirementV1,
+    snapshot: record.snapshot,
+  };
+}

package/template/packages/server-sdk/src/ai-runtime-readiness.contract.test.ts

@@ -0,0 +1,314 @@
+import { describe, expect, test } from "bun:test";
+import type {
+  AiOperationReadinessRequirementV1,
+  AiReadinessReasonCodeV1,
+} from "./ai-runtime-readiness.js";
+import {
+  cloneRecord,
+  firstOffer,
+  firstProbe,
+  missingModality,
+  readinessContractFixtures as fixtures,
+  unavailableSnapshot,
+  withExpectedDeployment,
+  type ReadinessContractFixture,
+} from "./ai-runtime-readiness.contract-support.js";
+
+const alternateDeploymentIdentity =
+  "windy-deployment-v1_3a77bbd9-2c2e-46af-8b5d-f015247970fe";
+import { projectAiOperationReadinessV1 } from "./ai-runtime-readiness-projection.js";
+
+for (const fixture of fixtures) {
+  describe(`${fixture.name} readiness V1`, () => {
+    test("同一公共契约投影 ready offer", () => {
+      const result = project(fixture);
+
+      expect(result.status).toBe("ready");
+      if (result.status !== "ready") return;
+      expect(result.deployment).toEqual(fixture.operation.expectedDeployment);
+      expect(result.offers).toHaveLength(1);
+      expect(result.validUntil).toBe("2026-07-31T00:05:00.000Z");
+      expect(result.offers[0]?.limits.maxConcurrentRuns).toBeGreaterThan(0);
+    });
+
+    test("配置存在但没有真实 probe 仍 unavailable", () => {
+      const snapshot = unavailableSnapshot(fixture, {
+        status: "not-run",
+        reason: "NOT_PROBED",
+      });
+      snapshot.unavailableReasons = [
+        { code: "DOWNSTREAM_NOT_PROBED", retryable: true },
+      ];
+
+      expectReason(fixture, "DOWNSTREAM_NOT_PROBED", snapshot);
+    });
+
+    test("downstream probe 失败保留稳定原因", () => {
+      const snapshot = unavailableSnapshot(fixture, {
+        status: "failed",
+        checkedAt: fixture.now,
+        latencyMs: 25,
+        failureCode: "CONNECTION_FAILED",
+        retryable: true,
+      });
+      snapshot.unavailableReasons = [
+        {
+          code: "DOWNSTREAM_PROBE_FAILED",
+          retryable: true,
+          subject: "CONNECTION_FAILED",
+        },
+      ];
+
+      const result = project(fixture, snapshot);
+      expect(result.status).toBe("unavailable");
+      expect(result.unavailableReasons).toEqual([
+        {
+          code: "DOWNSTREAM_PROBE_FAILED",
+          retryable: true,
+          subject: "CONNECTION_FAILED",
+        },
+      ]);
+    });
+
+    test("过期 probe 不能继续提供 ready", () => {
+      const result = projectAiOperationReadinessV1(
+        fixture.operation,
+        fixture.snapshot,
+        { now: "2026-08-02T00:00:00.000Z" },
+      );
+
+      expect(result.status).toBe("unavailable");
+      expect(codes(result)).toContain("PROBE_STALE");
+
+      const reportedStale = unavailableSnapshot(fixture, firstProbe(fixture));
+      reportedStale.unavailableReasons = [
+        { code: "PROBE_STALE", retryable: true },
+      ];
+      expectReason(fixture, "PROBE_STALE", reportedStale);
+    });
+
+    test("未来时间签发的 probe 不能提前生效", () => {
+      const snapshot = cloneRecord(fixture.snapshot);
+      const probe = firstProbe(fixture);
+      probe.checkedAt = "2099-01-01T00:00:00.000Z";
+      probe.validUntil = "2100-01-01T00:00:00.000Z";
+      snapshot.downstreamProbe = probe;
+
+      expectReason(fixture, "PROBE_NOT_YET_VALID", snapshot);
+    });
+
+    test("snapshot 不能早于所引用的 probe", () => {
+      const snapshot = cloneRecord(fixture.snapshot);
+      snapshot.observedAt = "2026-07-30T23:59:59.000Z";
+
+      expectReason(fixture, "CONTRACT_INVALID", snapshot);
+    });
+
+    test("probe TTL 不能超过 V1 的短时上限", () => {
+      const snapshot = cloneRecord(fixture.snapshot);
+      const probe = firstProbe(fixture);
+      probe.validUntil = "2026-07-31T00:05:01.000Z";
+      snapshot.downstreamProbe = probe;
+
+      expectReason(fixture, "PROBE_TTL_EXCEEDED", snapshot);
+    });
+
+    test("probe 有效期使用半开区间并拒绝零 TTL", () => {
+      const atExpiry = projectAiOperationReadinessV1(
+        fixture.operation,
+        fixture.snapshot,
+        { now: "2026-07-31T00:05:00.000Z" },
+      );
+      expect(codes(atExpiry)).toContain("PROBE_STALE");
+
+      const zeroTtl = cloneRecord(fixture.snapshot);
+      const probe = firstProbe(fixture);
+      probe.validUntil = probe.checkedAt;
+      zeroTtl.downstreamProbe = probe;
+      expectReason(fixture, "CONTRACT_INVALID", zeroTtl);
+    });
+
+    test("deployment identity 漂移时 fail closed", () => {
+      const operation = withExpectedDeployment(fixture, {
+        identity: alternateDeploymentIdentity,
+      });
+
+      expectReason({ ...fixture, operation }, "DEPLOYMENT_IDENTITY_MISMATCH");
+
+      const snapshot = cloneRecord(fixture.snapshot);
+      const probe = firstProbe(fixture);
+      probe.deploymentIdentity = alternateDeploymentIdentity;
+      snapshot.downstreamProbe = probe;
+      expectReason(fixture, "PROBE_ATTESTATION_MISMATCH", snapshot);
+    });
+
+    test("release 与 offers digest 漂移时 fail closed", () => {
+      const operation = withExpectedDeployment(fixture, {
+        releaseDigest:
+          "sha256:eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
+      });
+
+      expectReason({ ...fixture, operation }, "RELEASE_DIGEST_MISMATCH");
+
+      const offersOperation = withExpectedDeployment(fixture, {
+        offersDigest:
+          "sha256:ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
+      });
+      expectReason(
+        { ...fixture, operation: offersOperation },
+        "OFFERS_DIGEST_MISMATCH",
+      );
+    });
+
+    test("缺少 identity、release 或 offers digest 不能形成 ready", () => {
+      const identityMissing = cloneRecord(fixture.snapshot);
+      const deployment = cloneRecord(identityMissing.deployment);
+      identityMissing.deployment = {
+        key: deployment.key,
+        releaseDigest: deployment.releaseDigest,
+      };
+      expectReason(fixture, "DEPLOYMENT_IDENTITY_MISSING", identityMissing);
+
+      const digestMissing = cloneRecord(fixture.snapshot);
+      const secondDeployment = cloneRecord(digestMissing.deployment);
+      digestMissing.deployment = {
+        key: secondDeployment.key,
+        identity: secondDeployment.identity,
+      };
+      expectReason(fixture, "RELEASE_DIGEST_MISSING", digestMissing);
+
+      const offersDigestMissing = cloneRecord(fixture.snapshot);
+      const thirdDeployment = cloneRecord(offersDigestMissing.deployment);
+      delete thirdDeployment.offersDigest;
+      offersDigestMissing.deployment = thirdDeployment;
+      expectReason(fixture, "OFFERS_DIGEST_MISSING", offersDigestMissing);
+    });
+
+    test("offers 语义被篡改时不能沿用 probe 证明", () => {
+      const capabilitySnapshot = cloneRecord(fixture.snapshot);
+      const capabilityOffer = firstOffer(capabilitySnapshot);
+      capabilityOffer.capabilities = [
+        ...(capabilityOffer.capabilities as readonly string[]),
+        "fixture.tampered",
+      ];
+      capabilitySnapshot.offers = [capabilityOffer];
+      expectReason(fixture, "OFFERS_DIGEST_MISMATCH", capabilitySnapshot);
+
+      const limitSnapshot = cloneRecord(fixture.snapshot);
+      const limitOffer = firstOffer(limitSnapshot);
+      const limits = cloneRecord(limitOffer.limits);
+      limits.maxInputBytes = Number.MAX_SAFE_INTEGER;
+      limitSnapshot.offers = [{ ...limitOffer, limits }];
+      expectReason(fixture, "OFFERS_DIGEST_MISMATCH", limitSnapshot);
+
+      const reportedDrift = unavailableSnapshot(fixture, firstProbe(fixture));
+      reportedDrift.unavailableReasons = [
+        { code: "OFFERS_DIGEST_MISMATCH", retryable: false },
+      ];
+      expectReason(fixture, "OFFERS_DIGEST_MISMATCH", reportedDrift);
+    });
+
+    test("capability、variant 与 modality 都按 Operation 收窄", () => {
+      const capability = {
+        ...fixture.operation,
+        requiredCapabilities: [
+          ...fixture.operation.requiredCapabilities,
+          "fixture.unsupported",
+        ],
+      };
+      expectReason({ ...fixture, operation: capability }, "CAPABILITY_MISSING");
+
+      const variant = { ...fixture.operation, variant: "unsupported" };
+      expectReason({ ...fixture, operation: variant }, "VARIANT_UNSUPPORTED");
+
+      const offer = firstOffer(fixture);
+      const input = {
+        ...fixture.operation,
+        inputModalities: [
+          missingModality(offer.inputModalities as readonly string[]),
+        ],
+      } as AiOperationReadinessRequirementV1;
+      expectReason(
+        { ...fixture, operation: input },
+        "INPUT_MODALITY_UNSUPPORTED",
+      );
+
+      const output = {
+        ...fixture.operation,
+        outputModalities: [
+          missingModality(offer.outputModalities as readonly string[]),
+        ],
+      } as AiOperationReadinessRequirementV1;
+      expectReason(
+        { ...fixture, operation: output },
+        "OUTPUT_MODALITY_UNSUPPORTED",
+      );
+    });
+
+    test("Runtime 上限不足时不静默降低 Operation 契约", () => {
+      const operation = {
+        ...fixture.operation,
+        limits: {
+          ...fixture.operation.limits,
+          maxInputBytes: Number.MAX_SAFE_INTEGER,
+        },
+      };
+
+      expectReason({ ...fixture, operation }, "LIMIT_INSUFFICIENT");
+
+      const resourceOperation = {
+        ...fixture.operation,
+        resources: {
+          ...fixture.operation.resources,
+          minConcurrentRuns: Number.MAX_SAFE_INTEGER,
+        },
+      };
+      expectReason(
+        { ...fixture, operation: resourceOperation },
+        "RESOURCE_LIMIT_INSUFFICIENT",
+      );
+
+      const snapshot = cloneRecord(fixture.snapshot);
+      const offer = firstOffer(snapshot);
+      const limits = cloneRecord(offer.limits);
+      delete limits.maxConcurrentRuns;
+      snapshot.offers = [{ ...offer, limits }];
+      expectReason(fixture, "CONTRACT_INVALID", snapshot);
+    });
+
+    test("未知附加字段不破坏 V1 加法兼容", () => {
+      const snapshot = cloneRecord(fixture.snapshot);
+      snapshot.futureOptionalField = { enabled: true };
+      const offer = firstOffer(snapshot);
+      offer.futureOptionalField = "ignored";
+      snapshot.offers = [offer];
+
+      expect(project(fixture, snapshot).status).toBe("ready");
+    });
+  });
+}
+
+function project(
+  fixture: ReadinessContractFixture,
+  snapshot = fixture.snapshot,
+) {
+  return projectAiOperationReadinessV1(fixture.operation, snapshot, {
+    now: fixture.now,
+  });
+}
+
+function expectReason(
+  fixture: ReadinessContractFixture,
+  code: AiReadinessReasonCodeV1,
+  snapshot = fixture.snapshot,
+) {
+  const result = project(fixture, snapshot);
+  expect(result.status).toBe("unavailable");
+  expect(codes(result)).toContain(code);
+}
+
+function codes(
+  result: ReturnType<typeof projectAiOperationReadinessV1>,
+): readonly AiReadinessReasonCodeV1[] {
+  return result.unavailableReasons.map(({ code }) => code);
+}

package/template/packages/server-sdk/src/ai-runtime-readiness.digest-safety.contract.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, test } from "bun:test";
+import {
+  AI_RUNTIME_MAX_OFFERS_V1,
+  computeAiRuntimeOffersDigestV1,
+  type AiRuntimeOfferV1,
+} from "../index.js";
+import {
+  firstOffer,
+  readinessContractFixtures as fixtures,
+  type ReadinessContractFixture,
+} from "./ai-runtime-readiness.contract-support.js";
+
+const invalidDigestMessage = "AI Runtime offers contract invalid";
+
+for (const fixture of fixtures) {
+  describe(`${fixture.name} direct offers digest`, () => {
+    test("接受公开 MAX 并在 MAX+1 失败关闭", () => {
+      const atLimit = offers(fixture, AI_RUNTIME_MAX_OFFERS_V1);
+      expect(computeAiRuntimeOffersDigestV1(atLimit)).toMatch(
+        /^sha256:[0-9a-f]{64}$/,
+      );
+
+      expectInvalidDigest(offers(fixture, AI_RUNTIME_MAX_OFFERS_V1 + 1));
+    });
+  });
+}
+
+test("direct digest 在读取巨大稀疏数组元素前失败关闭", () => {
+  let reads = 0;
+  const sparse = new Array<unknown>(1_000_000);
+  Object.defineProperty(sparse, "0", {
+    enumerable: true,
+    configurable: true,
+    get() {
+      reads += 1;
+      throw new Error("Bearer sparse-secret");
+    },
+  });
+
+  expectInvalidDigest(sparse);
+  expect(reads).toBe(0);
+});
+
+test("direct digest 在读取 MAX+1 数组元素前失败关闭", () => {
+  let reads = 0;
+  const overLimit = new Array<unknown>(AI_RUNTIME_MAX_OFFERS_V1 + 1);
+  Object.defineProperty(overLimit, "0", {
+    enumerable: true,
+    configurable: true,
+    get() {
+      reads += 1;
+      throw new Error("Bearer over-limit-secret");
+    },
+  });
+
+  expectInvalidDigest(overLimit);
+  expect(reads).toBe(0);
+});
+
+test("direct digest 拒绝 accessor 且不执行 getter", () => {
+  let reads = 0;
+  const accessor: unknown[] = [];
+  Object.defineProperty(accessor, "0", {
+    enumerable: true,
+    configurable: true,
+    get() {
+      reads += 1;
+      throw new Error("https://secret.example/provider");
+    },
+  });
+
+  expectInvalidDigest(accessor);
+  expect(reads).toBe(0);
+});
+
+test("direct digest 拒绝 Proxy 与 revoked Proxy 且不执行 trap", () => {
+  let traps = 0;
+  const proxy = new Proxy([], {
+    get() {
+      traps += 1;
+      throw new Error("Authorization: Bearer proxy-secret");
+    },
+    getOwnPropertyDescriptor() {
+      traps += 1;
+      throw new Error("provider proxy body");
+    },
+    getPrototypeOf() {
+      traps += 1;
+      throw new Error("proxy locator");
+    },
+    ownKeys() {
+      traps += 1;
+      throw new Error("proxy endpoint");
+    },
+  });
+  const revoked = Proxy.revocable([], {});
+  revoked.revoke();
+
+  expectInvalidDigest(proxy);
+  expectInvalidDigest(revoked.proxy);
+  expect(traps).toBe(0);
+});
+
+function offers(
+  fixture: ReadinessContractFixture,
+  count: number,
+): readonly AiRuntimeOfferV1[] {
+  return Array.from({ length: count }, (_, index) => {
+    const offer = firstOffer(fixture);
+    const variant = offer.variant;
+    if (typeof variant !== "string") {
+      throw new Error("digest fixture 缺少 variant");
+    }
+    offer.variant = index === 0 ? variant : `${variant}.${index}`;
+    return offer as unknown as AiRuntimeOfferV1;
+  });
+}
+
+function expectInvalidDigest(input: unknown): void {
+  let thrown: unknown;
+  try {
+    computeAiRuntimeOffersDigestV1(input);
+  } catch (error) {
+    thrown = error;
+  }
+  expect(thrown).toBeInstanceOf(TypeError);
+  expect((thrown as Error).message).toBe(invalidDigestMessage);
+  expect(String(thrown)).not.toContain("secret");
+  expect(String(thrown)).not.toContain("provider");
+  expect(String(thrown)).not.toContain("http");
+}