create-windy 0.5.2 → 0.6.0

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

@@ -0,0 +1,215 @@
+import { describe, expect, test } from "bun:test";
+import type {
+  AiOperationReadinessRequirementV1,
+  AiReadinessReasonCodeV1,
+  AiRuntimeKindV1,
+} from "./ai-runtime-readiness.js";
+import {
+  cloneRecord,
+  firstOffer,
+  readinessContractFixtures as fixtures,
+  unavailableSnapshot,
+  withAttestedOffers,
+  type ReadinessContractFixture,
+} from "./ai-runtime-readiness.contract-support.js";
+import { projectAiOperationReadinessV1 } from "./ai-runtime-readiness-projection.js";
+
+const maliciousEndpoint = "https://runtime.internal.example/v1/models";
+const maliciousBearer = "Authorization: Bearer secret-runtime-token";
+const maliciousProviderBody = '{"error":{"message":"provider body"}}';
+
+for (const fixture of fixtures) {
+  describe(`${fixture.name} shared fail-closed V1`, () => {
+    test("unavailable Runtime 先核对 runtimeKind", () => {
+      const snapshot = notProbedSnapshot(fixture);
+      const operation = {
+        ...fixture.operation,
+        runtimeKind: otherRuntimeKind(fixture.operation.runtimeKind),
+      };
+      const result = project({ ...fixture, operation }, snapshot);
+
+      expect(result.status).toBe("unavailable");
+      expect(codes(result)).toEqual(["RUNTIME_KIND_MISMATCH"]);
+    });
+
+    test("failed reason 必须绑定 probe failureCode 与 retryable", () => {
+      const subjectMismatch = failedSnapshot(
+        fixture,
+        "AUTHENTICATION_FAILED",
+        true,
+      );
+      expectReason(fixture, "CONTRACT_INVALID", subjectMismatch);
+
+      const retryableMismatch = failedSnapshot(fixture, "TIMEOUT", false);
+      expectReason(fixture, "CONTRACT_INVALID", retryableMismatch);
+    });
+
+    test("Runtime reason detail 只输出 Host 定义的安全字段", () => {
+      const snapshot = notProbedSnapshot(fixture);
+      snapshot.unavailableReasons = [
+        {
+          code: "DOWNSTREAM_NOT_PROBED",
+          retryable: true,
+          subject: maliciousEndpoint,
+          expected: maliciousBearer,
+          actual: maliciousProviderBody,
+        },
+      ];
+      const result = project(fixture, snapshot);
+
+      expect(result.unavailableReasons).toEqual([
+        { code: "DOWNSTREAM_NOT_PROBED", retryable: true },
+      ]);
+      expectNoMaliciousDetails(result);
+
+      const failed = failedSnapshot(fixture, "TIMEOUT", true);
+      failed.unavailableReasons = [
+        {
+          code: "DOWNSTREAM_PROBE_FAILED",
+          retryable: true,
+          subject: "TIMEOUT",
+          expected: maliciousEndpoint,
+          actual: `${maliciousBearer} ${maliciousProviderBody}`,
+        },
+      ];
+      const rejected = project(fixture, failed);
+      expect(codes(rejected)).toEqual(["CONTRACT_INVALID"]);
+      expectNoMaliciousDetails(rejected);
+
+      const identitySnapshot = cloneRecord(fixture.snapshot);
+      const deployment = cloneRecord(identitySnapshot.deployment);
+      const probe = cloneRecord(identitySnapshot.downstreamProbe);
+      const maliciousIdentity = `${maliciousEndpoint} ${maliciousBearer} ${maliciousProviderBody}`;
+      deployment.identity = maliciousIdentity;
+      probe.deploymentIdentity = maliciousIdentity;
+      identitySnapshot.deployment = deployment;
+      identitySnapshot.downstreamProbe = probe;
+      const identityMismatch = project(fixture, identitySnapshot);
+      expect(codes(identityMismatch)).toEqual(["DEPLOYMENT_IDENTITY_MISSING"]);
+      expectNoMaliciousDetails(identityMismatch);
+
+      const keySnapshot = cloneRecord(fixture.snapshot);
+      const keyDeployment = cloneRecord(keySnapshot.deployment);
+      keyDeployment.key = maliciousEndpoint;
+      keySnapshot.deployment = keyDeployment;
+      const keyMismatch = project(fixture, keySnapshot);
+      expect(codes(keyMismatch)).toEqual(["DEPLOYMENT_KEY_MISMATCH"]);
+      expectNoMaliciousDetails(keyMismatch);
+    });
+
+    test("无版本 legacy health 不会被猜测升级为 ready", () => {
+      expectReason(fixture, "CONTRACT_UNSUPPORTED", {
+        status: "ready",
+        capabilities: ["fixture.legacy"],
+      });
+    });
+
+    test("未知 schema version 在 V1 Host 上失败关闭", () => {
+      const snapshot = cloneRecord(fixture.snapshot);
+      snapshot.schemaVersion = 2;
+
+      expectReason(fixture, "CONTRACT_UNSUPPORTED", snapshot);
+    });
+
+    test("非 canonical UTC 时间不能进入 wire contract", () => {
+      const snapshot = cloneRecord(fixture.snapshot);
+      snapshot.observedAt = "07/31/2026 00:00:00";
+
+      expectReason(fixture, "CONTRACT_INVALID", snapshot);
+    });
+
+    test("不同 offer 的能力不能拼成虚假 ready", () => {
+      const offer = firstOffer(fixture);
+      const firstCapability = fixture.operation.requiredCapabilities[0];
+      if (!firstCapability) throw new Error("atomic offer fixture 缺少能力");
+      const secondCapability = "fixture.atomic.second";
+      const attested = withAttestedOffers(fixture, [
+        { ...offer, variant: "partial-a", capabilities: [firstCapability] },
+        { ...offer, variant: "partial-b", capabilities: [secondCapability] },
+      ]);
+      const operation = {
+        ...attested.operation,
+        variant: undefined,
+        requiredCapabilities: [firstCapability, secondCapability],
+      };
+
+      expectReason({ ...attested, operation }, "CAPABILITY_MISSING");
+    });
+
+    test("malformed Operation requirement 不抛异常并失败关闭", () => {
+      const operation = {
+        ...fixture.operation,
+        expectedDeployment: undefined,
+      } as unknown as AiOperationReadinessRequirementV1;
+      const invoke = () => project({ ...fixture, operation });
+
+      expect(invoke).not.toThrow();
+      expect(codes(invoke())).toEqual(["CONTRACT_INVALID"]);
+    });
+  });
+}
+
+function notProbedSnapshot(fixture: ReadinessContractFixture) {
+  const snapshot = unavailableSnapshot(fixture, {
+    status: "not-run",
+    reason: "NOT_PROBED",
+  });
+  snapshot.unavailableReasons = [
+    { code: "DOWNSTREAM_NOT_PROBED", retryable: true },
+  ];
+  return snapshot;
+}
+
+function failedSnapshot(
+  fixture: ReadinessContractFixture,
+  subject: "AUTHENTICATION_FAILED" | "TIMEOUT",
+  retryable: boolean,
+) {
+  const snapshot = unavailableSnapshot(fixture, {
+    status: "failed",
+    checkedAt: fixture.now,
+    latencyMs: 25,
+    failureCode: "TIMEOUT",
+    retryable: true,
+  });
+  snapshot.unavailableReasons = [
+    { code: "DOWNSTREAM_PROBE_FAILED", retryable, subject },
+  ];
+  return snapshot;
+}
+
+function otherRuntimeKind(runtimeKind: AiRuntimeKindV1): AiRuntimeKindV1 {
+  return runtimeKind === "speech" ? "document" : "speech";
+}
+
+function project(
+  fixture: ReadinessContractFixture,
+  snapshot = fixture.snapshot,
+) {
+  return projectAiOperationReadinessV1(fixture.operation, snapshot, {
+    now: fixture.now,
+  });
+}
+
+function expectReason(
+  fixture: ReadinessContractFixture,
+  code: AiReadinessReasonCodeV1,
+  snapshot = fixture.snapshot,
+) {
+  expect(codes(project(fixture, snapshot))).toContain(code);
+}
+
+function codes(
+  result: ReturnType<typeof projectAiOperationReadinessV1>,
+): readonly AiReadinessReasonCodeV1[] {
+  return result.unavailableReasons.map(({ code }) => code);
+}
+
+function expectNoMaliciousDetails(
+  result: ReturnType<typeof projectAiOperationReadinessV1>,
+) {
+  const serialized = JSON.stringify(result);
+  expect(serialized).not.toContain(maliciousEndpoint);
+  expect(serialized).not.toContain(maliciousBearer);
+  expect(serialized).not.toContain(maliciousProviderBody);
+}

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

@@ -0,0 +1,138 @@
+import { describe, expect, test } from "bun:test";
+import {
+  AI_RUNTIME_DEPLOYMENT_IDENTITY_PREFIX_V1,
+  parseAiRuntimeDeploymentIdentityV1,
+  projectAiOperationReadinessV1,
+  type AiReadinessReasonCodeV1,
+} from "../index.js";
+import {
+  cloneRecord,
+  readinessContractFixtures as fixtures,
+  type ReadinessContractFixture,
+} from "./ai-runtime-readiness.contract-support.js";
+
+export const alternateDeploymentIdentity =
+  "windy-deployment-v1_3a77bbd9-2c2e-46af-8b5d-f015247970fe";
+
+describe("AI Runtime deployment identity V1", () => {
+  test("公开 parser 只接受带 namespace 的 canonical UUIDv4", () => {
+    expect(AI_RUNTIME_DEPLOYMENT_IDENTITY_PREFIX_V1).toBe(
+      "windy-deployment-v1_",
+    );
+    expect(
+      parseAiRuntimeDeploymentIdentityV1(alternateDeploymentIdentity),
+    ).toBe(alternateDeploymentIdentity);
+    for (const invalid of [
+      "https://runtime.internal/deployments/3a77bbd9",
+      "Authorization: Bearer secret-runtime-token",
+      "/var/run/windy/deployment.sock",
+      "runtime.internal:11434/models/vision",
+      `${alternateDeploymentIdentity}\nAuthorization`,
+      "windy-deployment-v1_3A77BBD9-2C2E-46AF-8B5D-F015247970FE",
+      "windy-deployment-v1_3a77bbd9-2c2e-16af-8b5d-f015247970fe",
+      "windy-deployment-v1_3a77bbd9-2c2e-46af-7b5d-f015247970fe",
+      null,
+      ["windy-deployment-v1"],
+    ]) {
+      expect(parseAiRuntimeDeploymentIdentityV1(invalid)).toBeNull();
+    }
+  });
+});
+
+const unsafeIdentities = [
+  "https://runtime.internal/deployments/3a77bbd9",
+  "Authorization: Bearer secret-runtime-token",
+  "/var/run/windy/deployment.sock",
+  "runtime.internal:11434/models/vision",
+];
+
+for (const fixture of fixtures) {
+  describe(`${fixture.name} deployment identity enforcement`, () => {
+    test("requirement、deployment 与 probe 分别拒绝不安全 identity", () => {
+      for (const identity of unsafeIdentities) {
+        const requirementResult = project({
+          ...fixture,
+          operation: {
+            ...fixture.operation,
+            expectedDeployment: {
+              ...fixture.operation.expectedDeployment,
+              identity,
+            },
+          },
+        });
+        expectUnavailableWithoutIdentity(
+          requirementResult,
+          "CONTRACT_INVALID",
+          identity,
+        );
+
+        const deploymentSnapshot = cloneRecord(fixture.snapshot);
+        const deployment = cloneRecord(deploymentSnapshot.deployment);
+        deployment.identity = identity;
+        deploymentSnapshot.deployment = deployment;
+        expectUnavailableWithoutIdentity(
+          project(fixture, deploymentSnapshot),
+          "DEPLOYMENT_IDENTITY_MISSING",
+          identity,
+        );
+
+        const probeSnapshot = cloneRecord(fixture.snapshot);
+        const probe = cloneRecord(probeSnapshot.downstreamProbe);
+        probe.deploymentIdentity = identity;
+        probeSnapshot.downstreamProbe = probe;
+        expectUnavailableWithoutIdentity(
+          project(fixture, probeSnapshot),
+          "DEPLOYMENT_IDENTITY_MISSING",
+          identity,
+        );
+      }
+    });
+
+    test("三处相同的不安全 identity 也不能形成 ready", () => {
+      for (const identity of unsafeIdentities) {
+        const snapshot = cloneRecord(fixture.snapshot);
+        const deployment = cloneRecord(snapshot.deployment);
+        const probe = cloneRecord(snapshot.downstreamProbe);
+        deployment.identity = identity;
+        probe.deploymentIdentity = identity;
+        snapshot.deployment = deployment;
+        snapshot.downstreamProbe = probe;
+        const result = project(
+          {
+            ...fixture,
+            operation: {
+              ...fixture.operation,
+              expectedDeployment: {
+                ...fixture.operation.expectedDeployment,
+                identity,
+              },
+            },
+          },
+          snapshot,
+        );
+        expectUnavailableWithoutIdentity(result, "CONTRACT_INVALID", identity);
+      }
+    });
+  });
+}
+
+function project(
+  fixture: ReadinessContractFixture,
+  snapshot = fixture.snapshot,
+) {
+  return projectAiOperationReadinessV1(fixture.operation, snapshot, {
+    now: fixture.now,
+  });
+}
+
+function expectUnavailableWithoutIdentity(
+  result: ReturnType<typeof projectAiOperationReadinessV1>,
+  code: AiReadinessReasonCodeV1,
+  identity: string,
+) {
+  expect(result.status).toBe("unavailable");
+  expect(result.unavailableReasons.map((reason) => reason.code)).toContain(
+    code,
+  );
+  expect(JSON.stringify(result)).not.toContain(identity);
+}

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

@@ -0,0 +1,314 @@
+import { describe, expect, test } from "bun:test";
+import {
+  AI_OPERATION_MAX_REQUIRED_CAPABILITIES_V1,
+  AI_READINESS_REASON_CODES_V1,
+  AI_RUNTIME_MAX_CAPABILITIES_PER_OFFER_V1,
+  AI_RUNTIME_MAX_OFFERS_V1,
+  AI_RUNTIME_MAX_UNAVAILABLE_REASONS_V1,
+  AI_RUNTIME_MODALITIES_V1,
+  type AiOperationReadinessRequirementV1,
+  type AiReadinessReasonCodeV1,
+} from "./ai-runtime-readiness.js";
+import { projectAiOperationReadinessV1 } from "./ai-runtime-readiness-projection.js";
+import {
+  cloneRecord,
+  firstOffer,
+  readinessContractFixtures as fixtures,
+  unavailableSnapshot,
+  withAttestedOffers,
+  type ReadinessContractFixture,
+} from "./ai-runtime-readiness.contract-support.js";
+
+for (const fixture of fixtures) {
+  describe(`${fixture.name} shared input-safety V1`, () => {
+    test("malformed Runtime status 与 probe reason 不抛异常并失败关闭", () => {
+      const malformedValues = [
+        {
+          status: { nested: { value: "ready" } },
+          reason: { nested: { value: "NOT_PROBED" } },
+        },
+        {
+          status: JSON.parse('{"toString":null,"valueOf":null}'),
+          reason: JSON.parse('{"toString":null,"valueOf":null}'),
+        },
+        { status: null, reason: null },
+        { status: ["ready"], reason: ["NOT_PROBED"] },
+      ];
+
+      for (const malformed of malformedValues) {
+        const statusSnapshot = cloneRecord(fixture.snapshot);
+        statusSnapshot.status = malformed.status;
+        expectContractInvalidWithoutThrow(fixture, statusSnapshot);
+
+        const reasonSnapshot = notProbedSnapshot(fixture);
+        reasonSnapshot.downstreamProbe = {
+          status: "not-run",
+          reason: malformed.reason,
+        };
+        expectContractInvalidWithoutThrow(fixture, reasonSnapshot);
+      }
+    });
+
+    test("unavailableReasons 有公开上限并拒绝重复 identity", () => {
+      expect(AI_RUNTIME_MAX_UNAVAILABLE_REASONS_V1).toBe(16);
+
+      const atLimit = notProbedSnapshot(fixture);
+      atLimit.unavailableReasons = reasons(
+        AI_RUNTIME_MAX_UNAVAILABLE_REASONS_V1,
+      );
+      expect(project(fixture, atLimit).unavailableReasons).toHaveLength(
+        AI_RUNTIME_MAX_UNAVAILABLE_REASONS_V1,
+      );
+
+      const overLimit = notProbedSnapshot(fixture);
+      overLimit.unavailableReasons = reasons(
+        AI_RUNTIME_MAX_UNAVAILABLE_REASONS_V1 + 1,
+      );
+      expectContractInvalidWithoutThrow(fixture, overLimit);
+
+      const duplicate = notProbedSnapshot(fixture);
+      duplicate.unavailableReasons = [
+        {
+          code: "DOWNSTREAM_NOT_PROBED",
+          retryable: true,
+          subject: "runtime-a",
+        },
+        {
+          code: "DOWNSTREAM_NOT_PROBED",
+          retryable: false,
+          subject: "runtime-b",
+        },
+      ];
+      expectContractInvalidWithoutThrow(fixture, duplicate);
+    });
+
+    test("requiredCapabilities 有上限且 malformed list 失败关闭", () => {
+      expect(AI_OPERATION_MAX_REQUIRED_CAPABILITIES_V1).toBe(16);
+
+      const overLimit = Array.from(
+        { length: AI_OPERATION_MAX_REQUIRED_CAPABILITIES_V1 + 1 },
+        (_, index) => `fixture.required.${index}`,
+      );
+      expectRequirementInvalidWithoutThrow(fixture, overLimit);
+
+      const firstCapability = fixture.operation.requiredCapabilities[0];
+      if (!firstCapability) throw new Error("capability fixture 缺少能力");
+      for (const malformed of [
+        [firstCapability, firstCapability],
+        [{ nested: "capability" }],
+        [null],
+        [["nested"]],
+        null,
+        { nested: [firstCapability] },
+      ]) {
+        expectRequirementInvalidWithoutThrow(fixture, malformed);
+      }
+
+      const boundedUnsupported = Array.from(
+        { length: AI_OPERATION_MAX_REQUIRED_CAPABILITIES_V1 },
+        (_, index) => `fixture.unsupported.${index}`,
+      );
+      const result = project({
+        ...fixture,
+        operation: {
+          ...fixture.operation,
+          requiredCapabilities: boundedUnsupported,
+        },
+      });
+      expect(result.unavailableReasons).toEqual([
+        {
+          code: "CAPABILITY_MISSING",
+          retryable: false,
+          subject: "operation.requiredCapabilities",
+        },
+      ]);
+    });
+
+    test("offers 有公开上限且在遍历前失败关闭", () => {
+      expect(AI_RUNTIME_MAX_OFFERS_V1).toBe(16);
+
+      const atLimit = withOfferCount(fixture, AI_RUNTIME_MAX_OFFERS_V1);
+      const ready = project(atLimit);
+      expect(ready.status).toBe("ready");
+      expect(ready.offers).toHaveLength(AI_RUNTIME_MAX_OFFERS_V1);
+
+      const overLimit = cloneRecord(fixture.snapshot);
+      overLimit.offers = offerRecords(fixture, AI_RUNTIME_MAX_OFFERS_V1 + 1);
+      expectContractInvalidWithoutThrow(fixture, overLimit);
+
+      const duplicate = cloneRecord(fixture.snapshot);
+      duplicate.offers = [firstOffer(fixture), firstOffer(fixture)];
+      expectContractInvalidWithoutThrow(fixture, duplicate);
+
+      for (const malformed of [{ nested: [] }, null, [null], [[]]]) {
+        const snapshot = cloneRecord(fixture.snapshot);
+        snapshot.offers = malformed;
+        expectContractInvalidWithoutThrow(fixture, snapshot);
+      }
+    });
+
+    test("offer capabilities 有公开上限且 malformed list 失败关闭", () => {
+      expect(AI_RUNTIME_MAX_CAPABILITIES_PER_OFFER_V1).toBe(32);
+
+      const atLimit = withOfferCapabilities(
+        fixture,
+        offerCapabilities(fixture, AI_RUNTIME_MAX_CAPABILITIES_PER_OFFER_V1),
+      );
+      const ready = project(atLimit);
+      expect(ready.status).toBe("ready");
+      expect(ready.offers[0]?.capabilities).toHaveLength(
+        AI_RUNTIME_MAX_CAPABILITIES_PER_OFFER_V1,
+      );
+
+      const overLimit = cloneRecord(fixture.snapshot);
+      const overLimitOffer = firstOffer(fixture);
+      overLimitOffer.capabilities = offerCapabilities(
+        fixture,
+        AI_RUNTIME_MAX_CAPABILITIES_PER_OFFER_V1 + 1,
+      );
+      overLimit.offers = [overLimitOffer];
+      expectContractInvalidWithoutThrow(fixture, overLimit);
+
+      const firstCapability = fixture.operation.requiredCapabilities[0];
+      if (!firstCapability) throw new Error("capability fixture 缺少能力");
+      const duplicate = cloneRecord(fixture.snapshot);
+      const duplicateOffer = firstOffer(fixture);
+      duplicateOffer.capabilities = [firstCapability, firstCapability];
+      duplicate.offers = [duplicateOffer];
+      expectContractInvalidWithoutThrow(fixture, duplicate);
+
+      for (const malformed of [
+        [{ nested: "capability" }],
+        [null],
+        [["nested"]],
+      ]) {
+        const snapshot = cloneRecord(fixture.snapshot);
+        const offer = firstOffer(snapshot);
+        offer.capabilities = malformed;
+        snapshot.offers = [offer];
+        expectContractInvalidWithoutThrow(fixture, snapshot);
+      }
+    });
+
+    test("offer modality lists 按有限枚举在遍历前拒绝超限", () => {
+      const offer = firstOffer(fixture);
+      const atLimit = withAttestedOffers(fixture, [
+        {
+          ...offer,
+          inputModalities: AI_RUNTIME_MODALITIES_V1,
+          outputModalities: AI_RUNTIME_MODALITIES_V1,
+        },
+      ]);
+      expect(project(atLimit).status).toBe("ready");
+
+      for (const field of ["inputModalities", "outputModalities"] as const) {
+        const snapshot = cloneRecord(fixture.snapshot);
+        const malformedOffer = firstOffer(snapshot);
+        malformedOffer[field] = [...AI_RUNTIME_MODALITIES_V1, "text"];
+        snapshot.offers = [malformedOffer];
+        expectContractInvalidWithoutThrow(fixture, snapshot);
+      }
+    });
+  });
+}
+
+function reasons(count: number) {
+  return AI_READINESS_REASON_CODES_V1.slice(0, count).map((code) =>
+    code === "DOWNSTREAM_PROBE_FAILED"
+      ? { code, retryable: true, subject: "TIMEOUT" }
+      : { code, retryable: true },
+  );
+}
+
+function notProbedSnapshot(fixture: ReadinessContractFixture) {
+  const snapshot = unavailableSnapshot(fixture, {
+    status: "not-run",
+    reason: "NOT_PROBED",
+  });
+  snapshot.unavailableReasons = [
+    { code: "DOWNSTREAM_NOT_PROBED", retryable: true },
+  ];
+  return snapshot;
+}
+
+function withOfferCount(
+  fixture: ReadinessContractFixture,
+  count: number,
+): ReadinessContractFixture {
+  const attested = withAttestedOffers(fixture, offerRecords(fixture, count));
+  return {
+    ...attested,
+    operation: { ...attested.operation, variant: undefined },
+  };
+}
+
+function offerRecords(
+  fixture: ReadinessContractFixture,
+  count: number,
+): readonly Record<string, unknown>[] {
+  const offer = firstOffer(fixture);
+  const variant = offer.variant;
+  if (typeof variant !== "string")
+    throw new Error("offer fixture 缺少 variant");
+  return Array.from({ length: count }, (_, index) => ({
+    ...offer,
+    variant: index === 0 ? variant : `${variant}.${index}`,
+  }));
+}
+
+function withOfferCapabilities(
+  fixture: ReadinessContractFixture,
+  capabilities: readonly string[],
+): ReadinessContractFixture {
+  return withAttestedOffers(fixture, [
+    { ...firstOffer(fixture), capabilities },
+  ]);
+}
+
+function offerCapabilities(
+  fixture: ReadinessContractFixture,
+  count: number,
+): readonly string[] {
+  const capabilities = [...fixture.operation.requiredCapabilities];
+  for (let index = 0; capabilities.length < count; index += 1) {
+    capabilities.push(`fixture.offer-capability.${index}`);
+  }
+  return capabilities;
+}
+
+function project(
+  fixture: ReadinessContractFixture,
+  snapshot = fixture.snapshot,
+) {
+  return projectAiOperationReadinessV1(fixture.operation, snapshot, {
+    now: fixture.now,
+  });
+}
+
+function expectContractInvalidWithoutThrow(
+  fixture: ReadinessContractFixture,
+  snapshot: unknown,
+) {
+  const invoke = () => project(fixture, snapshot);
+  expect(invoke).not.toThrow();
+  expect(codes(invoke())).toEqual(["CONTRACT_INVALID"]);
+}
+
+function expectRequirementInvalidWithoutThrow(
+  fixture: ReadinessContractFixture,
+  requiredCapabilities: unknown,
+) {
+  const operation = {
+    ...fixture.operation,
+    requiredCapabilities,
+  } as unknown as AiOperationReadinessRequirementV1;
+  const invoke = () => project({ ...fixture, operation });
+  expect(invoke).not.toThrow();
+  expect(codes(invoke())).toEqual(["CONTRACT_INVALID"]);
+}
+
+function codes(
+  result: ReturnType<typeof projectAiOperationReadinessV1>,
+): readonly AiReadinessReasonCodeV1[] {
+  return result.unavailableReasons.map(({ code }) => code);
+}

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

@@ -0,0 +1,18 @@
+import { expect, test } from "bun:test";
+import {
+  parseAiRuntimeReadinessV1,
+  type AiRuntimeReadinessParseResult,
+} from "../index.js";
+
+test("@southwind-ai/server-sdk 根入口公开 readiness parser", () => {
+  const parsed: AiRuntimeReadinessParseResult = parseAiRuntimeReadinessV1(
+    { schemaVersion: 0 },
+    "2026-07-31T00:00:00.000Z",
+  );
+
+  expect(parsed).toEqual({
+    ok: false,
+    observedAt: "2026-07-31T00:00:00.000Z",
+    reasons: [{ code: "CONTRACT_UNSUPPORTED", retryable: false }],
+  });
+});