create-windy 0.5.1 → 0.6.0

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

@@ -0,0 +1,160 @@
+import { readFile } from "node:fs/promises";
+import { describe, expect, test } from "bun:test";
+import {
+  AI_RUNTIME_MAX_CAPABILITIES_PER_OFFER_V1,
+  AI_RUNTIME_MAX_OFFERS_V1,
+  AI_RUNTIME_MODALITIES_V1,
+} from "./ai-runtime-readiness.js";
+import {
+  cloneRecord,
+  firstOffer,
+  readinessContractFixtures,
+  type ReadinessContractFixture,
+} from "./ai-runtime-readiness.contract-support.js";
+import { parseAiRuntimeReadinessV1 } from "./ai-runtime-readiness-validation.js";
+
+interface PythonParityFixture {
+  readonly maxOffers: number;
+  readonly maxCapabilitiesPerOffer: number;
+  readonly maxModalities: number;
+  readonly maxSafeInteger: number;
+  readonly firstUnsafeInteger: number;
+  readonly integerNumbers: {
+    readonly acceptedJson: readonly number[];
+    readonly rejectedJson: readonly (number | boolean)[];
+    readonly rejectedNonFinite: readonly string[];
+  };
+}
+
+const boundary = await loadBoundary();
+const documentFixture = requiredDocumentFixture();
+
+describe("Document Python 与公共 readiness V1 边界", () => {
+  test("同一 fixture 固定 cardinality 与 safe integer", () => {
+    expect(boundary).toEqual({
+      maxOffers: AI_RUNTIME_MAX_OFFERS_V1,
+      maxCapabilitiesPerOffer: AI_RUNTIME_MAX_CAPABILITIES_PER_OFFER_V1,
+      maxModalities: AI_RUNTIME_MODALITIES_V1.length,
+      maxSafeInteger: Number.MAX_SAFE_INTEGER,
+      firstUnsafeInteger: Number.MAX_SAFE_INTEGER + 1,
+      integerNumbers: {
+        acceptedJson: [1, 1, Number.MAX_SAFE_INTEGER],
+        rejectedJson: [true, false, 1.5],
+        rejectedNonFinite: ["NaN", "Infinity", "-Infinity"],
+      },
+    });
+  });
+
+  test("公共 parser 统一接受整数数值并拒绝 bool、非整数和非有限数", () => {
+    for (const value of boundary.integerNumbers.acceptedJson) {
+      expect(
+        parseAiRuntimeReadinessV1(
+          snapshotWithLimits(value),
+          documentFixture.now,
+        ).ok,
+      ).toBe(true);
+    }
+    for (const value of boundary.integerNumbers.rejectedJson) {
+      expect(
+        parseAiRuntimeReadinessV1(
+          snapshotWithLimits(value),
+          documentFixture.now,
+        ).ok,
+      ).toBe(false);
+    }
+    for (const token of boundary.integerNumbers.rejectedNonFinite) {
+      expect(
+        parseAiRuntimeReadinessV1(
+          snapshotWithLimits(Number(token)),
+          documentFixture.now,
+        ).ok,
+      ).toBe(false);
+    }
+  });
+
+  test("公共 parser 接受边界值并拒绝第一个不安全整数", () => {
+    const safe = snapshotWithLimits(boundary.maxSafeInteger);
+    expect(parseAiRuntimeReadinessV1(safe, documentFixture.now).ok).toBe(true);
+
+    const unsafe = snapshotWithLimits(boundary.firstUnsafeInteger);
+    expect(parseAiRuntimeReadinessV1(unsafe, documentFixture.now).ok).toBe(
+      false,
+    );
+  });
+
+  test("公共 parser 在 fixture MAX 接受并在 MAX+1 失败关闭", () => {
+    const atLimit = snapshotAtCardinalityLimit();
+    expect(parseAiRuntimeReadinessV1(atLimit, documentFixture.now).ok).toBe(
+      true,
+    );
+
+    const offersOverflow = cloneRecord(atLimit);
+    offersOverflow.offers = Array.from(
+      { length: boundary.maxOffers + 1 },
+      (_, index) => ({
+        ...firstOffer(documentFixture),
+        variant: `document.overflow-${index}`,
+      }),
+    );
+    expect(
+      parseAiRuntimeReadinessV1(offersOverflow, documentFixture.now).ok,
+    ).toBe(false);
+
+    const capabilitiesOverflow = cloneRecord(atLimit);
+    const offer = firstOffer(capabilitiesOverflow);
+    offer.capabilities = Array.from(
+      { length: boundary.maxCapabilitiesPerOffer + 1 },
+      (_, index) => `document.capability-${index}`,
+    );
+    capabilitiesOverflow.offers = [offer];
+    expect(
+      parseAiRuntimeReadinessV1(capabilitiesOverflow, documentFixture.now).ok,
+    ).toBe(false);
+  });
+});
+
+function snapshotAtCardinalityLimit() {
+  const snapshot = cloneRecord(documentFixture.snapshot);
+  const base = firstOffer(documentFixture);
+  base.capabilities = Array.from(
+    { length: boundary.maxCapabilitiesPerOffer },
+    (_, index) => `document.capability-${index}`,
+  );
+  const modalities = AI_RUNTIME_MODALITIES_V1.slice(0, boundary.maxModalities);
+  base.inputModalities = modalities;
+  base.outputModalities = [...modalities];
+  snapshot.offers = Array.from({ length: boundary.maxOffers }, (_, index) => ({
+    ...structuredClone(base),
+    variant: `document.variant-${index}`,
+  }));
+  return snapshot;
+}
+
+function snapshotWithLimits(maxInputBytes: unknown) {
+  const snapshot = cloneRecord(documentFixture.snapshot);
+  const offer = firstOffer(documentFixture);
+  const limits = cloneRecord(offer.limits);
+  limits.maxInputBytes = maxInputBytes;
+  offer.limits = limits;
+  snapshot.offers = [offer];
+  return snapshot;
+}
+
+async function loadBoundary(): Promise<PythonParityFixture> {
+  const body = await readFile(
+    new URL(
+      "../contracts/ai-runtime-readiness/v1/document-python-parity.json",
+      import.meta.url,
+    ),
+    "utf8",
+  );
+  return JSON.parse(body) as PythonParityFixture;
+}
+
+function requiredDocumentFixture(): ReadinessContractFixture {
+  const fixture = readinessContractFixtures.find(
+    ({ operation }) => operation.runtimeKind === "document",
+  );
+  if (!fixture) throw new Error("document readiness fixture 缺失");
+  return fixture;
+}

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

@@ -0,0 +1,135 @@
+import { describe, expect, test } from "bun:test";
+import type { AiRuntimeOfferV1 } from "./ai-runtime-readiness.js";
+import {
+  cloneRecord,
+  firstOffer,
+  firstProbe,
+  readinessContractFixtures as fixtures,
+  type ReadinessContractFixture,
+} from "./ai-runtime-readiness.contract-support.js";
+import { computeAiRuntimeOffersDigestV1 } from "./ai-runtime-readiness-digest.js";
+import { projectAiOperationReadinessV1 } from "./ai-runtime-readiness-projection.js";
+import { parseAiRuntimeReadinessV1 } from "./ai-runtime-readiness-validation.js";
+
+for (const fixture of fixtures) {
+  describe(`${fixture.name} readiness Host trust`, () => {
+    test("Runtime payload 自报 pinned 字段不能证明 digest 漂移", () => {
+      const snapshot = changedSnapshot(fixture, "runtime.degraded-safe");
+      const deployment = cloneRecord(snapshot.deployment);
+      const probe = cloneRecord(snapshot.downstreamProbe);
+      deployment.pinnedReleaseDigest =
+        fixture.operation.expectedDeployment.releaseDigest;
+      deployment.pinnedOffersDigest =
+        fixture.operation.expectedDeployment.offersDigest;
+      probe.pinnedReleaseDigest =
+        fixture.operation.expectedDeployment.releaseDigest;
+      probe.pinnedOffersDigest =
+        fixture.operation.expectedDeployment.offersDigest;
+      snapshot.deployment = deployment;
+      snapshot.downstreamProbe = probe;
+
+      const result = projectAiOperationReadinessV1(
+        fixture.operation,
+        snapshot,
+        { now: fixture.now },
+      );
+
+      expect(result.status).toBe("unavailable");
+      expect(
+        result.unavailableReasons.some(({ code }) =>
+          ["RELEASE_DIGEST_MISMATCH", "OFFERS_DIGEST_MISMATCH"].includes(code),
+        ),
+      ).toBe(true);
+    });
+
+    test("Host 独立保存的完整 offers 只允许当前事实降级", () => {
+      const currentOffer = firstOffer(fixture);
+      const fullOffer: AiRuntimeOfferV1 = {
+        ...(currentOffer as unknown as AiRuntimeOfferV1),
+        capabilities: [
+          ...(currentOffer.capabilities as string[]),
+          "runtime.optional-full-capability",
+        ],
+      };
+      const fullOffers = [fullOffer] as const;
+      const expectedDeployment = {
+        ...fixture.operation.expectedDeployment,
+        offersDigest: computeAiRuntimeOffersDigestV1(fullOffers),
+      };
+      const result = projectAiOperationReadinessV1(
+        { ...fixture.operation, expectedDeployment },
+        fixture.snapshot,
+        {
+          now: fixture.now,
+          trustedFullAttestation: {
+            deployment: expectedDeployment,
+            offers: fullOffers,
+          },
+        },
+      );
+
+      expect(result.status).toBe("ready");
+      if (result.status === "ready") {
+        expect(result.deployment).toEqual(expectedDeployment);
+      }
+    });
+
+    test("Host 历史不能授权当前 offers 能力扩张", () => {
+      const snapshot = changedSnapshot(
+        fixture,
+        "runtime.untrusted-expansion",
+        false,
+      );
+      const result = projectAiOperationReadinessV1(
+        fixture.operation,
+        snapshot,
+        {
+          now: fixture.now,
+          trustedFullAttestation: parsedFullAttestation(fixture),
+        },
+      );
+
+      expect(result.status).toBe("unavailable");
+      expect(result.unavailableReasons.map(({ code }) => code)).toContain(
+        "OFFERS_DIGEST_MISMATCH",
+      );
+    });
+  });
+}
+
+function changedSnapshot(
+  fixture: ReadinessContractFixture,
+  capability: string,
+  changeRelease = true,
+) {
+  const snapshot = cloneRecord(fixture.snapshot);
+  const offer = firstOffer(fixture);
+  offer.capabilities = [...(offer.capabilities as string[]), capability];
+  const currentDigest = computeAiRuntimeOffersDigestV1([
+    offer as unknown as AiRuntimeOfferV1,
+  ]);
+  const deployment = cloneRecord(snapshot.deployment);
+  const probe = firstProbe(fixture);
+  deployment.offersDigest = currentDigest;
+  probe.offersDigest = currentDigest;
+  if (changeRelease) {
+    const currentRelease = `sha256:${"d".repeat(64)}`;
+    deployment.releaseDigest = currentRelease;
+    probe.releaseDigest = currentRelease;
+  }
+  snapshot.deployment = deployment;
+  snapshot.downstreamProbe = probe;
+  snapshot.offers = [offer];
+  return snapshot;
+}
+
+function parsedFullAttestation(fixture: ReadinessContractFixture) {
+  const parsed = parseAiRuntimeReadinessV1(fixture.snapshot, fixture.now);
+  if (!parsed.ok || parsed.value.status !== "ready") {
+    throw new Error("readiness fixture 不是 ready full attestation");
+  }
+  return {
+    deployment: parsed.value.deployment,
+    offers: parsed.value.offers,
+  };
+}

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

@@ -0,0 +1,198 @@
+import {
+  AI_RUNTIME_READINESS_SCHEMA_VERSION,
+  type AiOperationRequiredLimitsV1,
+  type AiRuntimeDeploymentV1,
+  type AiRuntimeKindV1,
+  type AiRuntimeModalityV1,
+  type AiRuntimeOffersDigestV1,
+  type AiRuntimeReleaseDigestV1,
+} from "@southwind-ai/shared";
+
+export {
+  AI_OPERATION_MAX_REQUIRED_CAPABILITIES_V1,
+  AI_RUNTIME_KINDS_V1,
+  AI_RUNTIME_MODALITIES_V1,
+  AI_RUNTIME_READINESS_SCHEMA_VERSION,
+} from "@southwind-ai/shared";
+export type {
+  AiOperationReadinessRequirementV1,
+  AiOperationRequiredLimitsV1,
+  AiOperationRequiredResourcesV1,
+  AiRuntimeDeploymentV1,
+  AiRuntimeKindV1,
+  AiRuntimeModalityV1,
+  AiRuntimeOffersDigestV1,
+  AiRuntimeReleaseDigestV1,
+} from "@southwind-ai/shared";
+
+export const AI_RUNTIME_MAX_PROBE_TTL_SECONDS = 300 as const;
+export const AI_RUNTIME_MAX_UNAVAILABLE_REASONS_V1 = 16 as const;
+export const AI_RUNTIME_MAX_OFFERS_V1 = 16 as const;
+export const AI_RUNTIME_MAX_CAPABILITIES_PER_OFFER_V1 = 32 as const;
+
+export const AI_RUNTIME_PROBE_FAILURE_CODES_V1 = [
+  "AUTHENTICATION_FAILED",
+  "CONNECTION_FAILED",
+  "INVALID_RESPONSE",
+  "LOCAL_DEPENDENCY_UNAVAILABLE",
+  "RESOURCE_UNAVAILABLE",
+  "TIMEOUT",
+  "UNHEALTHY",
+] as const;
+
+export type AiRuntimeProbeFailureCodeV1 =
+  (typeof AI_RUNTIME_PROBE_FAILURE_CODES_V1)[number];
+
+export const AI_READINESS_REASON_CODES_V1 = [
+  "RUNTIME_NOT_CONFIGURED",
+  "DOWNSTREAM_NOT_PROBED",
+  "DOWNSTREAM_PROBE_FAILED",
+  "PROBE_STALE",
+  "PROBE_NOT_YET_VALID",
+  "PROBE_TTL_EXCEEDED",
+  "PROBE_ATTESTATION_MISMATCH",
+  "RESOURCE_UNAVAILABLE",
+  "CONTRACT_UNSUPPORTED",
+  "CONTRACT_INVALID",
+  "RUNTIME_KIND_MISMATCH",
+  "DEPLOYMENT_KEY_MISMATCH",
+  "DEPLOYMENT_IDENTITY_MISSING",
+  "DEPLOYMENT_IDENTITY_MISMATCH",
+  "RELEASE_DIGEST_MISSING",
+  "RELEASE_DIGEST_MISMATCH",
+  "OFFERS_DIGEST_MISSING",
+  "OFFERS_DIGEST_MISMATCH",
+  "CAPABILITY_MISSING",
+  "VARIANT_UNSUPPORTED",
+  "INPUT_MODALITY_UNSUPPORTED",
+  "OUTPUT_MODALITY_UNSUPPORTED",
+  "LIMIT_INSUFFICIENT",
+  "RESOURCE_LIMIT_INSUFFICIENT",
+] as const;
+
+export type AiReadinessReasonCodeV1 =
+  (typeof AI_READINESS_REASON_CODES_V1)[number];
+
+export interface AiReadinessReasonV1 {
+  readonly code: AiReadinessReasonCodeV1;
+  readonly retryable: boolean;
+  /** Host 定义的 bounded safe token；不承载 Runtime 原始消息。 */
+  readonly subject?: string;
+  /** 仅供 Host 生成的安全比较值；不透传 Runtime detail。 */
+  readonly expected?: string | number;
+  /** 仅供 Host 生成的安全比较值；不透传 Runtime detail。 */
+  readonly actual?: string | number;
+}
+
+export type AiRuntimeDownstreamProbeV1 =
+  | {
+      readonly status: "not-run";
+      readonly reason: "NOT_CONFIGURED" | "NOT_PROBED";
+    }
+  | {
+      readonly status: "failed";
+      readonly checkedAt: string;
+      readonly latencyMs: number;
+      readonly failureCode: AiRuntimeProbeFailureCodeV1;
+      readonly retryable: boolean;
+    }
+  | {
+      readonly status: "passed";
+      readonly checkedAt: string;
+      readonly validUntil: string;
+      readonly latencyMs: number;
+      /** 通过公共 V1 identity parser 的持久化 opaque token。 */
+      readonly deploymentIdentity: string;
+      readonly releaseDigest: AiRuntimeReleaseDigestV1;
+      readonly offersDigest: AiRuntimeOffersDigestV1;
+    };
+
+export interface AiRuntimeOfferLimitsV1 extends AiOperationRequiredLimitsV1 {
+  /** 同一 deployment 可同时执行的最大 Run 数，不表示已经预留资源。 */
+  readonly maxConcurrentRuns: number;
+  /** Runtime 可接受的排队 Run 数；0 表示不提供排队。 */
+  readonly maxQueueDepth: number;
+}
+
+export interface AiRuntimeOfferV1 {
+  /** 同一 deployment 内唯一的稳定变体 Key。 */
+  readonly variant: string;
+  /** 最多 AI_RUNTIME_MAX_CAPABILITIES_PER_OFFER_V1 个不同的稳定能力 Key。 */
+  readonly capabilities: readonly string[];
+  readonly inputModalities: readonly AiRuntimeModalityV1[];
+  readonly outputModalities: readonly AiRuntimeModalityV1[];
+  readonly limits: AiRuntimeOfferLimitsV1;
+}
+
+interface AiRuntimeReadinessBaseV1 {
+  readonly schemaVersion: typeof AI_RUNTIME_READINESS_SCHEMA_VERSION;
+  readonly runtimeKind: AiRuntimeKindV1;
+  readonly observedAt: string;
+  readonly configured: boolean;
+  readonly downstreamProbe: AiRuntimeDownstreamProbeV1;
+  readonly deployment: AiRuntimeDeploymentV1 | null;
+}
+
+export interface AiRuntimeReadyV1 extends AiRuntimeReadinessBaseV1 {
+  readonly status: "ready";
+  readonly configured: true;
+  readonly downstreamProbe: Extract<
+    AiRuntimeDownstreamProbeV1,
+    { readonly status: "passed" }
+  >;
+  readonly deployment: AiRuntimeDeploymentV1;
+  /** 最多 AI_RUNTIME_MAX_OFFERS_V1 个不同 variant。 */
+  readonly offers: readonly [AiRuntimeOfferV1, ...AiRuntimeOfferV1[]];
+  readonly unavailableReasons: readonly [];
+}
+
+export interface AiRuntimeUnavailableV1 extends AiRuntimeReadinessBaseV1 {
+  readonly status: "unavailable";
+  readonly offers: readonly [];
+  /** 最多 AI_RUNTIME_MAX_UNAVAILABLE_REASONS_V1 个不同的稳定原因 identity。 */
+  readonly unavailableReasons: readonly [
+    AiReadinessReasonV1,
+    ...AiReadinessReasonV1[],
+  ];
+}
+
+export type AiRuntimeReadinessV1 = AiRuntimeReadyV1 | AiRuntimeUnavailableV1;
+
+interface ModuleAiOperationReadinessBaseV1 {
+  readonly schemaVersion: typeof AI_RUNTIME_READINESS_SCHEMA_VERSION;
+  readonly operationKey: string;
+  readonly runtimeKind: AiRuntimeKindV1;
+  readonly observedAt: string;
+}
+
+export interface ModuleAiOperationReadyV1 extends ModuleAiOperationReadinessBaseV1 {
+  readonly status: "ready";
+  readonly validUntil: string;
+  readonly deployment: AiRuntimeDeploymentV1;
+  readonly offers: readonly [AiRuntimeOfferV1, ...AiRuntimeOfferV1[]];
+  readonly unavailableReasons: readonly [];
+}
+
+export interface ModuleAiOperationUnavailableV1 extends ModuleAiOperationReadinessBaseV1 {
+  readonly status: "unavailable";
+  readonly deployment: null;
+  readonly offers: readonly [];
+  readonly unavailableReasons: readonly [
+    AiReadinessReasonV1,
+    ...AiReadinessReasonV1[],
+  ];
+}
+
+export type ModuleAiOperationReadinessV1 =
+  | ModuleAiOperationReadyV1
+  | ModuleAiOperationUnavailableV1;
+
+/**
+ * Integration 任务由 Host 实现本 Port；当前独立 Interface 不改变既有
+ * ModuleAiOperationPort implementer 的必填表面。
+ */
+export interface ModuleAiOperationReadinessPortV1 {
+  inspect(input: {
+    readonly operationKey: string;
+  }): Promise<ModuleAiOperationReadinessV1>;
+}

package/template/packages/server-sdk/src/ai-screenshot-intake-port.ts

@@ -0,0 +1,58 @@
+import type { ModuleAiArtifactRef } from "./ai-artifact-port.js";
+
+/** Host-issued plan. Module never supplies a Run ID, ArtifactRef or provider URL. */
+export interface ModuleAiScreenshotPlanV1 {
+  readonly contractVersion: 1;
+  readonly intakeToken: string;
+  readonly expiresAt: string;
+}
+
+export interface ModuleAiScreenshotIntakePortV1 {
+  create(input: {
+    readonly operationKey: string;
+    readonly pageId: string;
+  }): Promise<ModuleAiScreenshotPlanV1>;
+  /** Canonical Run is host-owned; this consumes the plan exactly once. */
+  bind(input: { readonly intakeToken: string }): Promise<ModuleAiArtifactRef>;
+  discard(input: { readonly intakeToken: string }): Promise<void>;
+  /** cancel 与 discard 等价：终止尚未 bind 的计划，不接受业务 Run ID。 */
+  cancel(input: { readonly intakeToken: string }): Promise<void>;
+}
+
+/**
+ * V2 是浏览器上传的 Host 控制面，不进入 Module RequestContext。
+ * 调用者只能声明页面及像素元数据；Actor、scope、Operation、Run 和物理
+ * Artifact locator 全由 Host 重建或签发。
+ */
+export interface ModuleAiScreenshotIntakeCreateV2 {
+  readonly pageId: string;
+  readonly contextDigest: string;
+  readonly mediaType: "image/png";
+  readonly byteSize: number;
+  readonly pixels: number;
+}
+
+export interface ModuleAiScreenshotPlanV2 {
+  readonly contractVersion: 2;
+  readonly intakeToken: string;
+  readonly expiresAt: string;
+}
+
+/** Project-owned producer seam. It is never exposed to a business Module. */
+export interface ModuleAiScreenshotIntakeProducerV2 {
+  create(input: ModuleAiScreenshotIntakeCreateV2): Promise<
+    ModuleAiScreenshotPlanV2 & {
+      readonly operationKey: string;
+    }
+  >;
+  upload(input: {
+    readonly intakeToken: string;
+    readonly bytes: Uint8Array;
+    readonly mediaType: string;
+  }): Promise<ModuleAiArtifactRef>;
+  bind(input: {
+    readonly intakeToken: string;
+    readonly runId: string;
+  }): Promise<void>;
+  cancel(input: { readonly intakeToken: string }): Promise<void>;
+}

package/template/packages/server-sdk/src/data-governance-registration.ts

@@ -66,9 +66,7 @@ export interface ModuleGovernedExportRendererRegistration {
       readonly signal: AbortSignal;
       readonly heartbeat: () => Promise<void>;
     },
-  ):
-    | Promise<GovernedExportRenderedArtifact>
-    | GovernedExportRenderedArtifact;
+  ): Promise<GovernedExportRenderedArtifact> | GovernedExportRenderedArtifact;
 }
 
 export interface ModuleGovernedExportRegistration {

package/template/packages/server-sdk/src/durable-handler.ts

@@ -2,9 +2,12 @@ import type { DurableHandlerContext, PayloadParser } from "@southwind-ai/jobs";
 import type { AuditActionType } from "@southwind-ai/shared";
 import type { ModuleActor } from "./actor.js";
 import type { ModuleBackgroundAiPort } from "./background-ai-port.js";
+import type { ModuleSecretPort } from "./secret-port.js";
+import type { ModuleReportStagingPortV1 } from "./report-staging-port.js";
 import type {
   ModuleOpenedResourceFile,
   ModuleResourceFileRequest,
+  ModuleStorageWritePortV1,
 } from "./storage-port.js";
 
 export interface ModuleDurableStoragePort {
@@ -16,7 +19,16 @@ export interface ModuleDurableStoragePort {
 export interface ModuleDurableHandlerContext extends DurableHandlerContext {
   readonly actor: ModuleActor;
   readonly requestId: string;
+  /**
+   * 兼容旧 Durable Context 测试桩而保持 optional；Windy Host 每 attempt 注入。
+   * 显式依赖 Secret 的 Handler 使用 requireModuleSecretPort() fail closed。
+   */
+  readonly secrets?: ModuleSecretPort;
   readonly storage: ModuleDurableStoragePort;
+  /** 受治理写入是版本化、可选的 additive seam。 */
+  readonly storageWriter?: ModuleStorageWritePortV1;
+  /** 每个 attempt 重新绑定 Actor、Scope 与当前授权。 */
+  readonly reportStaging?: ModuleReportStagingPortV1;
   readonly ai: ModuleBackgroundAiPort;
 }
 

package/template/packages/server-sdk/src/module-adapter.test.ts

@@ -36,9 +36,19 @@ test("defineWindyServerComposition 保留项目装配与显式运行时挂载",
     assembly: { schemaVersion: 1 as const, modules: [] },
     adapters: [],
     attachments: [attachment],
+    secretBindings: [
+      {
+        moduleName: "case",
+        handle: "case.sftp.password",
+        connection: "case.sftp.primary",
+        purpose: "case.sftp.read",
+        resolve: () => ({ status: "disabled" }),
+      },
+    ],
   });
 
   expect(declaration.assembly.schemaVersion).toBe(1);
   expect(declaration.attachments).toEqual([attachment]);
+  expect(declaration.secretBindings?.[0]?.handle).toBe("case.sftp.password");
   declaration.attachments?.[0]?.attach({ database: "customer" });
 });

package/template/packages/server-sdk/src/module-adapter.ts

@@ -1,4 +1,5 @@
 import type { InstallableServerModule } from "./module-host.js";
+import type { ModuleSecretBinding } from "./secret-port.js";
 
 /**
  * 模块 package 提供给 Windy Server Host 的标准入口。
@@ -40,6 +41,8 @@ export interface WindyServerCompositionDeclaration<
   readonly assembly: TAssembly;
   readonly adapters: readonly WindyServerModuleAdapter<TManifest>[];
   readonly attachments?: readonly WindyServerModuleAttachment<TRuntime>[];
+  /** 只允许 project-owned Composition 提供的模块 Secret 物理绑定。 */
+  readonly secretBindings?: readonly ModuleSecretBinding[];
 }
 
 export function defineWindyServerModule<TManifest>(

package/template/packages/server-sdk/src/module-host.ts

@@ -7,6 +7,7 @@ import type { ModuleRouteDefinition } from "./route-definition.js";
 import type { ModuleSearchProvider } from "./search-provider-port.js";
 import type { ModuleSandboxToolHost } from "./sandbox-tool.js";
 import type { ModuleResourceFileAccessPolicy } from "./storage-port.js";
+import type { ModuleReportStagingPolicyV1 } from "./report-staging-port.js";
 import type { ModuleTaskHandlerRegistration } from "./task-registration.js";
 import type { ModuleToolHandlerRegistration } from "./tool-registration.js";
 
@@ -15,6 +16,11 @@ export interface ModuleUploadPolicy {
   maxByteSize: number;
   maxPartByteSize: number;
   sessionTtlMs: number;
+  /**
+   * Writer V1 发布文件的保留期。缺失时旧 create/read Port 仍可用，
+   * Writer V1 创建会话会 fail closed。
+   */
+  fileRetentionMs?: number;
   allowedTypes: Readonly<Record<string, readonly string[]>>;
   signature?: "image" | "none";
 }
@@ -29,6 +35,8 @@ export interface ModuleUploadPolicy {
 export interface ModuleHost {
   readonly moduleName: string;
   registerUploadPolicy(policy: ModuleUploadPolicy): void;
+  /** 注册 Host 固定治理上限的大报告暂存用途。 */
+  registerReportStagingPolicy(policy: ModuleReportStagingPolicyV1): void;
   /**
    * 注册跨上传者资源文件读取策略；purpose 必须由本模块或 Manifest 显式依赖模块的
    * Upload Policy 声明，Feature、Permission 与 Audit Action 必须来自当前 Manifest。

package/template/packages/server-sdk/src/report-staging-context-compatibility.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from "bun:test";
+import {
+  ModuleReportStagingError,
+  type ModuleReportStagingPortV1,
+  requireModuleReportStagingPortV1,
+} from "./report-staging-port.js";
+
+describe("Module Report Staging Context 兼容 seam", () => {
+  test("缺少 V1 Port 时 helper 以稳定 unavailable fail closed", () => {
+    expect(() => requireModuleReportStagingPortV1({})).toThrow(
+      new ModuleReportStagingError(
+        "REPORT_STAGING_UNAVAILABLE",
+        "模块 Report Staging V1 未挂载",
+        true,
+      ),
+    );
+  });
+
+  test("Host 注入的版本化 Port 原样返回", () => {
+    const port = {} as ModuleReportStagingPortV1;
+    expect(requireModuleReportStagingPortV1({ reportStaging: port })).toBe(
+      port,
+    );
+  });
+});