create-windy 0.5.2 → 0.6.1

package/template/packages/server-sdk/src/report-staging-port.ts

@@ -0,0 +1,190 @@
+import type {
+  ModuleOpenedResourceFile,
+  ModuleResourceFileRequest,
+} from "./storage-port.js";
+
+/** UTF-8 byte ceiling shared by Host validation and PostgreSQL V1 columns. */
+export const MODULE_REPORT_STAGING_PATH_MAX_BYTES = 4_096;
+
+/** V1 claim-owned metadata catalog has a fixed explicit-plus-implicit node cap. */
+export const MODULE_REPORT_STAGING_MAX_ENTRIES = 200_000;
+
+/** Expanded inputs may enumerate files, while archive volume sets stay small. */
+export const MODULE_REPORT_STAGING_MAX_SOURCES = 10_000;
+export const MODULE_REPORT_STAGING_MAX_ARCHIVE_VOLUMES = 256;
+
+export type ModuleReportStagingStatus =
+  | "indexing"
+  | "ready"
+  | "failed"
+  | "discarding"
+  | "discarded"
+  | "expired";
+
+export type ModuleReportStagingSourceMode = "archive" | "expanded";
+
+export type ModuleReportStagingErrorCode =
+  | "REPORT_STAGING_UNAVAILABLE"
+  | "REPORT_STAGING_FORBIDDEN"
+  | "REPORT_STAGING_INVALID_INPUT"
+  | "REPORT_STAGING_CONFLICT"
+  | "REPORT_STAGING_NOT_READY"
+  | "REPORT_STAGING_LIMIT"
+  | "REPORT_STAGING_UNSUPPORTED_ARCHIVE"
+  | "REPORT_STAGING_UNSAFE_ARCHIVE"
+  | "REPORT_STAGING_INTEGRITY_MISMATCH"
+  | "REPORT_STAGING_PROCESS_FAILED"
+  | "REPORT_STAGING_PROCESS_TIMEOUT"
+  | "REPORT_STAGING_CANCELLED"
+  | "REPORT_STAGING_LEASE_EXPIRED";
+
+export class ModuleReportStagingError extends Error {
+  constructor(
+    readonly code: ModuleReportStagingErrorCode,
+    message: string,
+    readonly retryable = false,
+  ) {
+    super(message);
+    this.name = "ModuleReportStagingError";
+  }
+}
+
+export interface ModuleReportStagingPolicyV1 {
+  /** 模块命名空间内的 staging 用途，例如 `evidence.report-staging`。 */
+  readonly purpose: string;
+  /** 可作为报告源的已注册业务文件 purpose。 */
+  readonly sourcePurposes: readonly string[];
+  readonly retentionMs: number;
+  readonly claimTtlMs: number;
+  readonly maxReadLeaseMs: number;
+  readonly maxProcessMs: number;
+  readonly maxSources: number;
+  readonly maxArchiveBytes: number;
+  readonly maxExpandedBytes: number;
+  readonly maxEntryBytes: number;
+  readonly maxEntries: number;
+  readonly maxCompressionRatio: number;
+  readonly maxPathDepth: number;
+}
+
+export interface ModuleReportStagingSourceInput {
+  readonly file: ModuleResourceFileRequest;
+  /** 报告内的业务相对路径；不得是主机路径。 */
+  readonly relativePath: string;
+}
+
+export interface ModuleReportStagingCreateInput {
+  readonly purpose: string;
+  readonly idempotencyKey: string;
+  /** 必须显式选择；Host 不通过扩展名或内容猜测归档。 */
+  readonly sourceMode: ModuleReportStagingSourceMode;
+  /** archive 为首卷；expanded 为主页面或业务清单，且都必须属于 sources。 */
+  readonly entrypoint: string;
+  readonly sources: readonly ModuleReportStagingSourceInput[];
+}
+
+export interface ModuleReportStagingGroupView {
+  readonly groupId: string;
+  readonly purpose: string;
+  readonly sourceMode: ModuleReportStagingSourceMode;
+  readonly status: ModuleReportStagingStatus;
+  readonly sourceCount: number;
+  readonly entryCount: number;
+  readonly archiveByteSize: number;
+  readonly expandedByteSize: number;
+  readonly manifestSha256?: string;
+  readonly failureCode?: ModuleReportStagingErrorCode;
+  readonly expiresAt: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+}
+
+export interface ModuleReportStagingSourceView {
+  readonly sourceId: string;
+  readonly relativePath: string;
+  readonly byteSize: number;
+  readonly sha256: string;
+}
+
+export interface ModuleReportStagingEntryView {
+  readonly entryId: string;
+  readonly relativePath: string;
+  readonly byteSize: number;
+  readonly sha256: string;
+}
+
+export interface ModuleReportStagingManifestV1 {
+  readonly version: "1";
+  readonly groupId: string;
+  readonly purpose: string;
+  readonly sourceMode: ModuleReportStagingSourceMode;
+  readonly entrypoint: string;
+  /** archive 返回卷摘要；expanded 的 source 与 entry 同形，因此为空。 */
+  readonly sources: readonly ModuleReportStagingSourceView[];
+  readonly entryCount: number;
+  readonly archiveByteSize: number;
+  readonly expandedByteSize: number;
+  readonly sha256: string;
+}
+
+export interface ModuleReportStagingReadLeaseView {
+  readonly leaseId: string;
+  readonly groupId: string;
+  readonly expiresAt: string;
+}
+
+export interface ModuleReportStagingEntryPage {
+  readonly items: readonly ModuleReportStagingEntryView[];
+  readonly nextCursor?: string;
+}
+
+export interface ModuleOpenedReportStagingEntry extends ModuleReportStagingEntryView {
+  readonly body: ReadableStream<Uint8Array>;
+}
+
+/**
+ * 受治理的大报告暂存 Port。Actor、Scope、物理目录、进程与保留策略均由 Host 固定。
+ */
+export interface ModuleReportStagingPortV1 {
+  createOrResume(
+    input: ModuleReportStagingCreateInput,
+  ): Promise<ModuleReportStagingGroupView>;
+  inspect(groupId: string): Promise<ModuleReportStagingGroupView>;
+  acquireReadLease(
+    groupId: string,
+    requestedTtlMs?: number,
+  ): Promise<ModuleReportStagingReadLeaseView>;
+  getManifest(
+    groupId: string,
+    leaseId: string,
+  ): Promise<ModuleReportStagingManifestV1>;
+  listEntries(
+    groupId: string,
+    leaseId: string,
+    input?: { readonly cursor?: string; readonly limit?: number },
+  ): Promise<ModuleReportStagingEntryPage>;
+  openEntry(
+    groupId: string,
+    leaseId: string,
+    entryId: string,
+  ): Promise<ModuleOpenedReportStagingEntry>;
+  closeReadLease(groupId: string, leaseId: string): Promise<void>;
+  discard(groupId: string): Promise<ModuleReportStagingGroupView>;
+}
+
+export interface ModuleReportStagingSourceReader {
+  open(input: ModuleResourceFileRequest): Promise<ModuleOpenedResourceFile>;
+}
+
+export function requireModuleReportStagingPortV1(context: {
+  readonly reportStaging?: ModuleReportStagingPortV1;
+}): ModuleReportStagingPortV1 {
+  if (!context.reportStaging) {
+    throw new ModuleReportStagingError(
+      "REPORT_STAGING_UNAVAILABLE",
+      "模块 Report Staging V1 未挂载",
+      true,
+    );
+  }
+  return context.reportStaging;
+}

package/template/packages/server-sdk/src/request-context.ts

@@ -2,8 +2,15 @@ import type { ModuleActor } from "./actor.js";
 import type { ModuleAuditEmitter } from "./audit-port.js";
 import type { ModuleAiArtifactPort } from "./ai-artifact-port.js";
 import type { ModuleAiOperationPort } from "./ai-operation-port.js";
+import type { ModuleAiOperationReadinessPortV1 } from "./ai-runtime-readiness.js";
+import type { ModuleAiScreenshotIntakePortV1 } from "./ai-screenshot-intake-port.js";
 import type { ModuleJobPort } from "./jobs-port.js";
-import type { ModuleStoragePort } from "./storage-port.js";
+import type { ModuleReportStagingPortV1 } from "./report-staging-port.js";
+import type { ModuleSecretPort } from "./secret-port.js";
+import type {
+  ModuleStoragePort,
+  ModuleStorageWritePortV1,
+} from "./storage-port.js";
 import type { ModuleUserDirectoryPort } from "./user-directory-port.js";
 
 /**
@@ -14,14 +21,33 @@ import type { ModuleUserDirectoryPort } from "./user-directory-port.js";
  */
 export interface ModuleRequestContext {
   readonly requestId: string;
+  /** 与当前 HTTP 请求绑定；断连或 Host 取消时触发。 */
+  readonly signal?: AbortSignal;
   readonly actor: ModuleActor;
   readonly params: Record<string, string | undefined>;
   readonly query: Record<string, string | undefined>;
+  /** 默认解析模式下的请求体；流模式下不应使用。 */
   readonly body?: unknown;
+  /** 仅 `bodyMode: "stream"` 路由可用，不暴露完整 Request 或框架对象。 */
+  readonly bodyStream?: ReadableStream<Uint8Array>;
   readonly audit: ModuleAuditEmitter;
   readonly aiArtifacts: ModuleAiArtifactPort;
   readonly aiOperations: ModuleAiOperationPort;
+  /** additive V1；旧 Context 构造器无需提供，Host 运行时注入 fail-closed Port。 */
+  readonly aiReadiness?: ModuleAiOperationReadinessPortV1;
+  /** VLM 截图输入的独立版本化接缝，不改变既有 aiArtifacts 必填表面。 */
+  readonly screenshots?: ModuleAiScreenshotIntakePortV1;
   readonly jobs: ModuleJobPort;
+  /** 大报告受治理暂存是版本化、可选的 additive seam。 */
+  readonly reportStaging?: ModuleReportStagingPortV1;
+  /**
+   * 兼容旧 Context 构造器而保持 optional；Windy Host 运行时始终注入。
+   * 显式依赖 Secret 的模块使用 requireModuleSecretPort() fail closed。
+   */
+  readonly secrets?: ModuleSecretPort;
+  /** 0.5.2 兼容的 create/read Port。 */
   readonly storage: ModuleStoragePort;
+  /** 受治理写入是版本化、可选的 additive seam。 */
+  readonly storageWriter?: ModuleStorageWritePortV1;
   readonly userDirectory: ModuleUserDirectoryPort;
 }

package/template/packages/server-sdk/src/route-definition.ts

@@ -21,6 +21,12 @@ export interface ModuleRouteDefinition {
   readonly path: string;
   readonly permissionKey: string;
   readonly featureKey?: string;
+  /**
+   * `stream` 仅允许 POST / PUT。Host 不解析请求体，并通过
+   * `ModuleRequestContext.bodyStream` 暴露受取消信号约束的原始字节流。
+   * 未声明时保持既有 parsed body 行为。
+   */
+  readonly bodyMode?: "stream";
   /** @deprecated Audit Action 以 Manifest API binding 为唯一事实源。 */
   readonly auditAction?: string;
   readonly handler: ModuleRouteHandler;

package/template/packages/server-sdk/src/secret-binding.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from "bun:test";
+import { createModuleSecretBinding } from "../index.js";
+
+describe("createModuleSecretBinding", () => {
+  test("通过公开 seam 每次重新调用 opaque resolver", async () => {
+    const reference = { provider: "test", key: "archive-password" };
+    let current: string | undefined = "password-v1";
+    let enabled = true;
+    let calls = 0;
+    const binding = createModuleSecretBinding({
+      moduleName: "archive",
+      handle: "archive.smb.password",
+      connection: "archive.smb.primary",
+      purpose: "archive.smb.read",
+      reference,
+      resolver: {
+        resolve(received) {
+          calls += 1;
+          expect(received).toBe(reference);
+          return current;
+        },
+      },
+      enabled: () => enabled,
+    });
+
+    await expect(binding.resolve()).resolves.toEqual({
+      status: "active",
+      value: "password-v1",
+    });
+    current = "password-v2";
+    await expect(binding.resolve()).resolves.toEqual({
+      status: "active",
+      value: "password-v2",
+    });
+    current = undefined;
+    await expect(binding.resolve()).resolves.toEqual({
+      status: "unavailable",
+    });
+    enabled = false;
+    await expect(binding.resolve()).resolves.toEqual({ status: "disabled" });
+    expect(calls).toBe(3);
+  });
+
+  test("捕获逻辑标识，物理 reference 只保留在闭包内", () => {
+    const input = {
+      moduleName: "archive",
+      handle: "archive.smb.password",
+      connection: "archive.smb.primary",
+      purpose: "archive.smb.read",
+      reference: { locator: "file:/run/secrets/archive" },
+      resolver: { resolve: () => "secret" },
+    };
+    const binding = createModuleSecretBinding(input);
+    input.handle = "mutated";
+
+    expect(binding.handle).toBe("archive.smb.password");
+    expect(Reflect.ownKeys(binding)).toEqual([
+      "moduleName",
+      "handle",
+      "connection",
+      "purpose",
+      "resolve",
+    ]);
+    expect(JSON.stringify(binding)).not.toContain("run/secrets");
+  });
+});

package/template/packages/server-sdk/src/secret-binding.ts

@@ -0,0 +1,54 @@
+import type {
+  ModuleSecretBinding,
+  ModuleSecretRequest,
+} from "./secret-port.js";
+
+export interface ModuleSecretValueResolver<TReference> {
+  resolve(
+    reference: TReference,
+  ): string | undefined | Promise<string | undefined>;
+}
+
+export interface ModuleSecretBindingInput<
+  TReference,
+> extends ModuleSecretRequest {
+  readonly moduleName: string;
+  readonly reference: TReference;
+  readonly resolver: ModuleSecretValueResolver<TReference>;
+  readonly enabled?: () => boolean | Promise<boolean>;
+}
+
+/**
+ * Stable Server Composition seam for adapting a host-owned reference resolver.
+ *
+ * The resolver is invoked on every attempt. The returned binding contains no
+ * physical locator metadata beyond the private closure held by this adapter.
+ */
+export function createModuleSecretBinding<TReference>(
+  input: ModuleSecretBindingInput<TReference>,
+): ModuleSecretBinding {
+  const moduleName = input.moduleName;
+  const handle = input.handle;
+  const connection = input.connection;
+  const purpose = input.purpose;
+  const reference = input.reference;
+  const resolver = input.resolver;
+  const enabled = input.enabled;
+
+  return Object.freeze({
+    moduleName,
+    handle,
+    connection,
+    purpose,
+    async resolve() {
+      if (enabled && !(await enabled())) {
+        return { status: "disabled" } as const;
+      }
+      const value = await resolver.resolve(reference);
+      if (value === undefined || value.length === 0) {
+        return { status: "unavailable" } as const;
+      }
+      return { status: "active", value } as const;
+    },
+  });
+}

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

@@ -0,0 +1,77 @@
+import { describe, expect, test } from "bun:test";
+import type { ModuleDurableHandlerContext } from "./durable-handler.js";
+import type { ModuleRequestContext } from "./request-context.js";
+import {
+  ModuleSecretError,
+  type ModuleSecretPort,
+  requireModuleSecretPort,
+} from "./secret-port.js";
+
+type IsAssignable<From, To> = [From] extends [To] ? true : false;
+type LegacyRequestContext = Omit<ModuleRequestContext, "secrets">;
+type LegacyDurableContext = Omit<ModuleDurableHandlerContext, "secrets">;
+
+const legacyRequestRemainsCompatible: IsAssignable<
+  LegacyRequestContext,
+  ModuleRequestContext
+> = true;
+const legacyDurableRemainsCompatible: IsAssignable<
+  LegacyDurableContext,
+  ModuleDurableHandlerContext
+> = true;
+
+describe("Module Secret Context 兼容 seam", () => {
+  test("旧版 Request 与 Durable Context 类型仍可赋值", () => {
+    expect(legacyRequestRemainsCompatible).toBe(true);
+    expect(legacyDurableRemainsCompatible).toBe(true);
+  });
+
+  test("缺少 Secret Port 时 helper 以稳定 unavailable fail closed", () => {
+    expect(() => requireModuleSecretPort({})).toThrow(
+      new ModuleSecretError("MODULE_SECRET_UNAVAILABLE"),
+    );
+  });
+
+  test("Host 注入的受治理 Port 原样返回", () => {
+    const port: ModuleSecretPort = {
+      async resolve(_request, use) {
+        return use("host-governed-secret");
+      },
+    };
+
+    expect(requireModuleSecretPort({ secrets: port })).toBe(port);
+  });
+
+  test("Request 与 Durable 示例经 required helper 保持 strict 类型", () => {
+    expect(typeof requestSecretExample).toBe("function");
+    expect(typeof durableSecretExample).toBe("function");
+  });
+});
+
+interface SecretConsumer {
+  use(value: string): Promise<readonly string[]>;
+}
+
+const request = {
+  handle: "archive.smb.password",
+  connection: "archive.smb.primary",
+  purpose: "archive.smb.read",
+} as const;
+
+async function requestSecretExample(
+  context: ModuleRequestContext,
+  consumer: SecretConsumer,
+): Promise<readonly string[]> {
+  return requireModuleSecretPort(context).resolve(request, (value) =>
+    consumer.use(value),
+  );
+}
+
+async function durableSecretExample(
+  context: ModuleDurableHandlerContext,
+  consumer: SecretConsumer,
+): Promise<void> {
+  await requireModuleSecretPort(context).resolve(request, async (value) => {
+    await consumer.use(value);
+  });
+}

package/template/packages/server-sdk/src/secret-port.ts

@@ -0,0 +1,80 @@
+export interface ModuleSecretRequest {
+  readonly handle: string;
+  readonly connection: string;
+  readonly purpose: string;
+}
+
+export type ModuleSecretSafeValue =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly ModuleSecretSafeValue[]
+  | { readonly [key: string]: ModuleSecretSafeValue };
+
+export type ModuleSecretErrorCode =
+  | "MODULE_SECRET_NOT_DECLARED"
+  | "MODULE_SECRET_GUARD_DENIED"
+  | "MODULE_SECRET_DISABLED"
+  | "MODULE_SECRET_UNAVAILABLE"
+  | "MODULE_SECRET_EXPOSURE_BLOCKED"
+  | "MODULE_SECRET_OPERATION_FAILED";
+
+export class ModuleSecretError extends Error {
+  constructor(
+    readonly code: ModuleSecretErrorCode,
+    message = "模块 Secret 请求失败",
+    readonly reason?: string,
+  ) {
+    super(message);
+    this.name = "ModuleSecretError";
+  }
+}
+
+/**
+ * 原始 Secret 只在一次受控回调内短暂可见。
+ *
+ * Host 会把有限 JSON 结果复制为不可变 canonical snapshot，拒绝把该值带入
+ * key/value，并把底层异常替换为稳定脱敏错误。
+ */
+export interface ModuleSecretPort {
+  resolve<TResult extends ModuleSecretSafeValue | void>(
+    request: ModuleSecretRequest,
+    use: (value: string) => TResult | Promise<TResult>,
+  ): Promise<TResult>;
+}
+
+/**
+ * 兼容旧版 Context object literal，同时让显式依赖 Secret 的模块 fail closed。
+ *
+ * Windy Host 始终注入 Port；第三方测试桩或旧 Adapter 缺少该字段时，不提供任何
+ * env/file fallback，而是抛出稳定 unavailable。
+ */
+export function requireModuleSecretPort(context: {
+  readonly secrets?: ModuleSecretPort;
+}): ModuleSecretPort {
+  if (!context.secrets) {
+    throw new ModuleSecretError("MODULE_SECRET_UNAVAILABLE");
+  }
+  return context.secrets;
+}
+
+export type ModuleSecretBindingResolution =
+  | {
+      readonly status: "active";
+      readonly value: string;
+    }
+  | { readonly status: "disabled" }
+  | { readonly status: "unavailable" };
+
+/**
+ * project-owned Server Composition 提供的物理绑定。
+ *
+ * 该对象只由 Host 消费，不会进入 ModuleRequest/Tool/Durable Context。
+ */
+export interface ModuleSecretBinding extends ModuleSecretRequest {
+  readonly moduleName: string;
+  resolve():
+    | ModuleSecretBindingResolution
+    | Promise<ModuleSecretBindingResolution>;
+}

package/template/packages/server-sdk/src/storage-port.ts

@@ -10,6 +10,104 @@ export interface ModuleUploadSessionInput {
   readonly fileExpiresAt?: Date;
 }
 
+export type ModuleUploadSessionStatus =
+  | "uploading"
+  | "aborting"
+  | "completed"
+  | "aborted"
+  | "expired";
+
+export type ModuleStorageErrorCode =
+  | "INVALID_UPLOAD"
+  | "UNSUPPORTED_FILE_TYPE"
+  | "UPLOAD_TOO_LARGE"
+  | "PART_TOO_LARGE"
+  | "UPLOAD_FORBIDDEN"
+  | "UPLOAD_NOT_ACTIVE"
+  | "UPLOAD_EXPIRED"
+  | "UPLOAD_OFFSET_CONFLICT"
+  | "UPLOAD_INCOMPLETE"
+  | "UPLOAD_CANCELLED"
+  | "FILE_SIGNATURE_MISMATCH"
+  | "CONCURRENT_UPLOAD"
+  | "FILE_NOT_FOUND"
+  | "FILE_EXPIRED"
+  | "FILE_CONTENT_MISSING"
+  | "SIZE_MISMATCH"
+  | "HASH_MISMATCH"
+  | "STORAGE_UNAVAILABLE"
+  | "STORAGE_WRITE_FAILED";
+
+/** 模块可依赖的稳定错误；不会携带底层路径、locator 或异常正文。 */
+export class ModuleStorageError extends Error {
+  constructor(
+    readonly code: ModuleStorageErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = "ModuleStorageError";
+  }
+}
+
+/** Host 投影的上传会话；不暴露 Owner、租户或物理存储定位信息。 */
+export interface ModuleUploadSessionView {
+  readonly id: string;
+  readonly purpose: string;
+  readonly filename: string;
+  readonly mimeType: string;
+  readonly expectedByteSize: number;
+  readonly expectedSha256?: string;
+  readonly receivedByteSize: number;
+  readonly nextPartNumber: number;
+  readonly status: ModuleUploadSessionStatus;
+  readonly expiresAt: string;
+  readonly fileExpiresAt?: string;
+  readonly fileId?: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+}
+
+export interface ModuleStorageWriterSessionInputV1 {
+  readonly purpose: string;
+  readonly filename: string;
+  readonly mimeType: string;
+  readonly expectedByteSize: number;
+  readonly expectedSha256?: string;
+}
+
+export interface ModuleUploadPartInputV1 {
+  readonly sessionId: string;
+  readonly partNumber: number;
+  readonly byteOffset: number;
+  readonly byteSize: number;
+  readonly sha256: string;
+  readonly body: ReadableStream<Uint8Array>;
+}
+
+/** Host 投影的已接收分片；不暴露 ArtifactRef 或 Blob locator。 */
+export interface ModuleUploadPartView {
+  readonly sessionId: string;
+  readonly partNumber: number;
+  readonly byteOffset: number;
+  readonly byteSize: number;
+  readonly sha256: string;
+  readonly createdAt: string;
+}
+
+/** Host 投影的平台文件元数据；文件 ID 是唯一允许持久化的不透明引用。 */
+export interface ModuleFileView {
+  readonly id: string;
+  readonly purpose: string;
+  readonly filename: string;
+  readonly mimeType: string;
+  readonly byteSize: number;
+  readonly sha256: string;
+}
+
+export interface ModuleOpenedFile extends ModuleFileView {
+  readonly body: ReadableStream<Uint8Array>;
+}
+
 export interface ModuleResourceFileRequest {
   /** 平台文件元数据 ID；不能是 ArtifactRef、对象存储 Key 或主机路径。 */
   readonly fileId: string;
@@ -25,15 +123,7 @@ export interface ModuleResourceFileRequest {
 }
 
 /** 资源授权读取仅返回业务所需的最小元数据与受限文件流。 */
-export interface ModuleOpenedResourceFile {
-  readonly id: string;
-  readonly purpose: string;
-  readonly filename: string;
-  readonly mimeType: string;
-  readonly byteSize: number;
-  readonly sha256: string;
-  readonly body: ReadableStream<Uint8Array>;
-}
+export type ModuleOpenedResourceFile = ModuleOpenedFile;
 
 export interface ModuleResourceFileAccessContext {
   readonly actor: ModuleActor;
@@ -89,3 +179,33 @@ export interface ModuleStoragePort {
     input: ModuleResourceFileRequest,
   ): Promise<ModuleOpenedResourceFile>;
 }
+
+/**
+ * 模块受治理的流式写入生命周期。
+ *
+ * Actor、Owner、租户、模块范围、AbortSignal 与物理 locator 均由 Host 从当前上下文
+ * 补齐；调用方只能提交 Host 已授权 purpose 下的不透明会话 ID 和流式分片。
+ */
+export interface ModuleStorageWritePortV1 {
+  createUploadSession(
+    input: ModuleStorageWriterSessionInputV1,
+  ): Promise<ModuleUploadSessionView>;
+  getUploadSession(sessionId: string): Promise<ModuleUploadSessionView>;
+  appendUploadPart(
+    input: ModuleUploadPartInputV1,
+  ): Promise<ModuleUploadPartView>;
+  completeUpload(sessionId: string): Promise<ModuleFileView>;
+  abortUpload(sessionId: string): Promise<ModuleUploadSessionView>;
+}
+
+export function requireModuleStorageWritePortV1(context: {
+  readonly storageWriter?: ModuleStorageWritePortV1;
+}): ModuleStorageWritePortV1 {
+  if (!context.storageWriter) {
+    throw new ModuleStorageError(
+      "STORAGE_UNAVAILABLE",
+      "模块 Storage Writer V1 未挂载",
+    );
+  }
+  return context.storageWriter;
+}