create-windy 0.5.1 → 0.6.0

package/template/packages/database/src/schema/report-staging.ts

@@ -0,0 +1,212 @@
+import { sql } from "drizzle-orm";
+import {
+  bigint,
+  check,
+  index,
+  integer,
+  pgTable,
+  timestamp,
+  uniqueIndex,
+  varchar,
+} from "drizzle-orm/pg-core";
+
+// Host applies the same 4096 UTF-8 byte limit before these varchar fields.
+const REPORT_STAGING_PATH_MAX_CHARACTERS = 4096;
+
+export const reportStagingGroups = pgTable(
+  "report_staging_groups",
+  {
+    groupId: varchar("group_id", { length: 80 }).primaryKey(),
+    moduleName: varchar("module_name", { length: 80 }).notNull(),
+    ownerId: varchar("owner_id", { length: 80 }).notNull(),
+    scopeHash: varchar("scope_hash", { length: 64 }).notNull(),
+    purpose: varchar("purpose", { length: 160 }).notNull(),
+    sourceMode: varchar("source_mode", { length: 24 }).notNull(),
+    idempotencyHash: varchar("idempotency_hash", { length: 64 }).notNull(),
+    fingerprint: varchar("fingerprint", { length: 64 }).notNull(),
+    policyDigest: varchar("policy_digest", { length: 64 }).notNull(),
+    entrypoint: varchar("entrypoint", {
+      length: REPORT_STAGING_PATH_MAX_CHARACTERS,
+    }).notNull(),
+    status: varchar("status", { length: 24 }).notNull(),
+    sourceCount: integer("source_count").notNull(),
+    entryCount: integer("entry_count").notNull().default(0),
+    archiveByteSize: bigint("archive_byte_size", { mode: "number" })
+      .notNull()
+      .default(0),
+    expandedByteSize: bigint("expanded_byte_size", { mode: "number" })
+      .notNull()
+      .default(0),
+    sealId: varchar("seal_id", { length: 64 }),
+    manifestSha256: varchar("manifest_sha256", { length: 64 }),
+    failureCode: varchar("failure_code", { length: 80 }),
+    revision: integer("revision").notNull().default(1),
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+  },
+  (table) => [
+    uniqueIndex("uk_report_staging_idempotency").on(
+      table.moduleName,
+      table.ownerId,
+      table.scopeHash,
+      table.purpose,
+      table.idempotencyHash,
+    ),
+    index("idx_report_staging_cleanup").on(
+      table.status,
+      table.expiresAt,
+      table.updatedAt,
+    ),
+    check(
+      "ck_report_staging_group_status",
+      sql`${table.status} in ('indexing', 'ready', 'failed', 'discarding', 'discarded', 'expired')`,
+    ),
+    check(
+      "ck_report_staging_source_mode",
+      sql`${table.sourceMode} in ('archive', 'expanded')`,
+    ),
+    check(
+      "ck_report_staging_group_hashes",
+      sql`${table.scopeHash} ~ '^[0-9a-f]{64}$' and ${table.idempotencyHash} ~ '^[0-9a-f]{64}$' and ${table.fingerprint} ~ '^[0-9a-f]{64}$' and ${table.policyDigest} ~ '^[0-9a-f]{64}$' and (${table.sealId} is null or ${table.sealId} ~ '^[0-9a-f]{64}$') and (${table.manifestSha256} is null or ${table.manifestSha256} ~ '^[0-9a-f]{64}$')`,
+    ),
+    check(
+      "ck_report_staging_group_seal",
+      sql`(${table.status} = 'ready' and ${table.sealId} is not null and ${table.manifestSha256} is not null) or (${table.status} in ('indexing', 'failed') and ${table.sealId} is null and ${table.manifestSha256} is null) or (${table.status} in ('discarding', 'discarded', 'expired') and ((${table.sealId} is null and ${table.manifestSha256} is null) or (${table.sealId} is not null and ${table.manifestSha256} is not null)))`,
+    ),
+    check(
+      "ck_report_staging_group_counts",
+      sql`${table.sourceCount} > 0 and ${table.entryCount} >= 0 and ${table.archiveByteSize} >= 0 and ${table.expandedByteSize} >= 0 and ${table.revision} > 0`,
+    ),
+  ],
+);
+
+export const reportStagingSources = pgTable(
+  "report_staging_sources",
+  {
+    sourceId: varchar("source_id", { length: 80 }).primaryKey(),
+    groupId: varchar("group_id", { length: 80 })
+      .notNull()
+      .references(() => reportStagingGroups.groupId, { onDelete: "restrict" }),
+    ordinal: integer("ordinal").notNull(),
+    fileId: varchar("file_id", { length: 80 }).notNull(),
+    filePurpose: varchar("file_purpose", { length: 160 }).notNull(),
+    resourceType: varchar("resource_type", { length: 160 }).notNull(),
+    resourceId: varchar("resource_id", { length: 160 }).notNull(),
+    relativePath: varchar("relative_path", {
+      length: REPORT_STAGING_PATH_MAX_CHARACTERS,
+    }).notNull(),
+    byteSize: bigint("byte_size", { mode: "number" }),
+    sha256: varchar("sha256", { length: 64 }),
+    createdAt: timestamp("created_at", { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+  },
+  (table) => [
+    uniqueIndex("uk_report_staging_source_ordinal").on(
+      table.groupId,
+      table.ordinal,
+    ),
+    uniqueIndex("uk_report_staging_source_path").on(
+      table.groupId,
+      table.relativePath,
+    ),
+    check(
+      "ck_report_staging_source_actual",
+      sql`(${table.byteSize} is null and ${table.sha256} is null) or (${table.byteSize} >= 0 and ${table.sha256} ~ '^[0-9a-f]{64}$')`,
+    ),
+  ],
+);
+
+export const reportStagingEntries = pgTable(
+  "report_staging_entries",
+  {
+    entryId: varchar("entry_id", { length: 80 }).primaryKey(),
+    groupId: varchar("group_id", { length: 80 })
+      .notNull()
+      .references(() => reportStagingGroups.groupId, { onDelete: "restrict" }),
+    ordinal: integer("ordinal").notNull(),
+    relativePath: varchar("relative_path", {
+      length: REPORT_STAGING_PATH_MAX_CHARACTERS,
+    }).notNull(),
+    pathKey: varchar("path_key", { length: 64 }).notNull(),
+    byteSize: bigint("byte_size", { mode: "number" }).notNull(),
+    sha256: varchar("sha256", { length: 64 }).notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+  },
+  (table) => [
+    uniqueIndex("uk_report_staging_entry_ordinal").on(
+      table.groupId,
+      table.ordinal,
+    ),
+    uniqueIndex("uk_report_staging_entry_path_key").on(
+      table.groupId,
+      table.pathKey,
+    ),
+    index("idx_report_staging_entry_page").on(table.groupId, table.ordinal),
+    check(
+      "ck_report_staging_entry_hash",
+      sql`${table.byteSize} >= 0 and ${table.sha256} ~ '^[0-9a-f]{64}$' and ${table.pathKey} ~ '^[0-9a-f]{64}$'`,
+    ),
+  ],
+);
+
+export const reportStagingReadLeases = pgTable(
+  "report_staging_read_leases",
+  {
+    leaseId: varchar("lease_id", { length: 80 }).primaryKey(),
+    groupId: varchar("group_id", { length: 80 })
+      .notNull()
+      .references(() => reportStagingGroups.groupId, { onDelete: "restrict" }),
+    moduleName: varchar("module_name", { length: 80 }).notNull(),
+    ownerId: varchar("owner_id", { length: 80 }).notNull(),
+    scopeHash: varchar("scope_hash", { length: 64 }).notNull(),
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+    closedAt: timestamp("closed_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+  },
+  (table) => [
+    index("idx_report_staging_lease_active").on(
+      table.groupId,
+      table.closedAt,
+      table.expiresAt,
+    ),
+    check(
+      "ck_report_staging_lease_scope",
+      sql`${table.scopeHash} ~ '^[0-9a-f]{64}$'`,
+    ),
+  ],
+);
+
+export const reportStagingClaims = pgTable(
+  "report_staging_claims",
+  {
+    groupId: varchar("group_id", { length: 80 })
+      .primaryKey()
+      .references(() => reportStagingGroups.groupId, { onDelete: "restrict" }),
+    tokenHash: varchar("token_hash", { length: 64 }).notNull(),
+    generation: integer("generation").notNull(),
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true })
+      .notNull()
+      .defaultNow(),
+  },
+  (table) => [
+    index("idx_report_staging_claim_expiry").on(table.expiresAt),
+    check(
+      "ck_report_staging_claim",
+      sql`${table.tokenHash} ~ '^[0-9a-f]{64}$' and ${table.generation} > 0`,
+    ),
+  ],
+);

package/template/packages/database/src/schema.test.ts

@@ -242,6 +242,11 @@ describe("database schema", () => {
     );
     expect(fileUploadSessions.receivedByteSize.notNull).toBe(true);
     expect(fileUploadSessions.nextPartNumber.notNull).toBe(true);
+    expect(fileUploadSessions.moduleName.notNull).toBe(false);
+    expect(fileUploadSessions.authorizationScopeHash.notNull).toBe(false);
+    expect(
+      getTableConfig(fileUploadSessions).checks.map(({ name }) => name),
+    ).toContain("ck_file_upload_sessions_authorization_binding");
     expect(getTableConfig(fileUploadParts).indexes).toHaveLength(2);
     expect(getTableConfig(fileUploadParts).foreignKeys[0]?.onDelete).toBe(
       "cascade",
@@ -255,6 +260,20 @@ describe("database schema", () => {
     expect(migration).toContain(
       'CREATE UNIQUE INDEX "uk_file_metadata_artifact_ref"',
     );
+    const bindingMigration = await Bun.file(
+      new URL("../drizzle/0048_illegal_magneto.sql", import.meta.url),
+    ).text();
+    expect(bindingMigration).toContain('ADD COLUMN "module_name" varchar(80)');
+    expect(bindingMigration).toContain(
+      'ADD COLUMN "authorization_scope_hash" varchar(64)',
+    );
+    expect(bindingMigration).toContain(
+      "ck_file_upload_sessions_authorization_binding",
+    );
+    expect(bindingMigration).toContain('"module_name" is not null');
+    expect(bindingMigration).toContain(
+      '"authorization_scope_hash" is not null',
+    );
   });
   // @windy-module system.storage end
 

package/template/packages/jobs/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/jobs",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/template/packages/modules/index.ts

@@ -1,5 +1,6 @@
 export * from "./src/manifest.js";
 export * from "./src/composition.js";
+export * from "./src/secret-composition.js";
 export * from "./src/catalog-validation.js";
 export * from "./src/menu-composition.js";
 export * from "./src/registry.js";

package/template/packages/modules/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@southwind-ai/modules",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "license": "UNLICENSED",
   "type": "module",
   "engines": {

package/template/packages/modules/src/ai-operation-composition.test.ts

@@ -304,4 +304,41 @@ describe("AI Operation Composition", () => {
       "图片输入上限超过 Runtime 安全边界",
     );
   });
+
+  test("readiness V1 固定 variant、模态与 deployment pin", () => {
+    const module = fixture("business");
+    const definition = operation("business.document", "document");
+    module.aiOperations = [
+      {
+        ...definition,
+        inputModalities: ["document"],
+        readiness: {
+          contractVersion: 1,
+          variant: "ocr",
+          inputModalities: ["document"],
+          outputModalities: ["document", "text"],
+          expectedDeployment: {
+            key: "document.intranet",
+            identity:
+              "windy-deployment-v1_7db61d8e-e50d-4f8a-9f3f-9b7a1d932e01",
+            releaseDigest: `sha256:${"a".repeat(64)}`,
+            offersDigest: `sha256:${"b".repeat(64)}`,
+          },
+          minConcurrentRuns: 1,
+          minQueueDepth: 0,
+        },
+      },
+    ];
+    expect(() => validateModuleComposition([module])).not.toThrow();
+    module.aiOperations[0] = {
+      ...module.aiOperations[0],
+      readiness: {
+        ...module.aiOperations[0].readiness!,
+        inputModalities: ["text"],
+      },
+    };
+    expect(() => validateModuleComposition([module])).toThrow(
+      "readiness V1 合约无效",
+    );
+  });
 });

package/template/packages/modules/src/ai-operation-composition.ts

@@ -3,6 +3,7 @@ import type {
   ModuleManifest,
 } from "./manifest.js";
 import { validateAiNetworkPolicy } from "./ai-network-policy.js";
+import { validateAiOperationReadinessContract } from "./ai-operation-readiness-contract.js";
 
 interface AiOperationCatalogs {
   permissions: ReadonlySet<string>;
@@ -104,6 +105,7 @@ function validateOperation(
   validateAiNetworkPolicy(operation);
   validateProviderDataPolicy(operation);
   validateLimits(operation);
+  validateAiOperationReadinessContract(operation);
 }
 
 const providerDataFields = new Set([

package/template/packages/modules/src/ai-operation-readiness-contract.test.ts

@@ -0,0 +1,38 @@
+import { expect, test } from "bun:test";
+import type { ModuleAiOperationDefinition } from "./manifest.js";
+import { operation } from "./ai-operation-composition.test-support.js";
+import { validateAiOperationReadinessContract } from "./ai-operation-readiness-contract.js";
+
+test("readiness Manifest 只接受 contractVersion 1", () => {
+  const valid = readinessOperation();
+  expect(() => validateAiOperationReadinessContract(valid)).not.toThrow();
+
+  const unsupported: ModuleAiOperationDefinition = {
+    ...valid,
+    readiness: { ...valid.readiness!, contractVersion: 2 } as never,
+  };
+  expect(() => validateAiOperationReadinessContract(unsupported)).toThrow(
+    "readiness V1 合约无效",
+  );
+});
+
+function readinessOperation(): ModuleAiOperationDefinition {
+  return {
+    ...operation("business.document", "document"),
+    inputModalities: ["document"],
+    readiness: {
+      contractVersion: 1,
+      variant: "ocr",
+      inputModalities: ["document"],
+      outputModalities: ["document", "text"],
+      expectedDeployment: {
+        key: "document.intranet",
+        identity: "windy-deployment-v1_7db61d8e-e50d-4f8a-9f3f-9b7a1d932e01",
+        releaseDigest: `sha256:${"a".repeat(64)}`,
+        offersDigest: `sha256:${"b".repeat(64)}`,
+      },
+      minConcurrentRuns: 1,
+      minQueueDepth: 0,
+    },
+  };
+}

package/template/packages/modules/src/ai-operation-readiness-contract.ts

@@ -0,0 +1,34 @@
+import { validAiOperationReadinessRequirementV1 } from "@southwind-ai/shared";
+import type { ModuleAiOperationDefinition } from "./manifest.js";
+
+export function validateAiOperationReadinessContract(
+  operation: ModuleAiOperationDefinition,
+): void {
+  const readiness = operation.readiness;
+  if (!readiness) return;
+  if (readiness.contractVersion !== 1)
+    throw new Error(`${operation.key} readiness V1 合约无效`);
+  const requirement = {
+    schemaVersion: 1,
+    operationKey: operation.key,
+    runtimeKind: operation.kind,
+    expectedDeployment: readiness.expectedDeployment,
+    variant: readiness.variant,
+    requiredCapabilities: operation.requiredCapabilities,
+    inputModalities: readiness.inputModalities,
+    outputModalities: readiness.outputModalities,
+    limits: operation.limits,
+    resources: {
+      minConcurrentRuns: readiness.minConcurrentRuns,
+      minQueueDepth: readiness.minQueueDepth,
+    },
+  };
+  if (!validAiOperationReadinessRequirementV1(requirement))
+    throw new Error(`${operation.key} readiness V1 合约无效`);
+  const inputs = operation.inputModalities ?? ["text"];
+  if (
+    inputs.length !== readiness.inputModalities.length ||
+    !inputs.every((value) => readiness.inputModalities.includes(value))
+  )
+    throw new Error(`${operation.key} readiness V1 合约无效`);
+}

package/template/packages/modules/src/capability-audit-validation.ts

@@ -21,9 +21,29 @@ export function validateCapabilityAuditActions(
         auditActions,
       );
     }
+    for (const secret of module.secrets ?? []) {
+      validateOwnedAuditAction(
+        module,
+        `Secret ${secret.handle}`,
+        secret.auditAction,
+      );
+    }
   }
 }
 
+export function validateOwnedAuditAction(
+  module: ModuleManifest,
+  label: string,
+  auditAction: AuditActionType | undefined,
+): void {
+  const owned = new Set(
+    module.auditActions.map((definition) =>
+      typeof definition === "string" ? definition : definition.key,
+    ),
+  );
+  validateAuditAction(label, auditAction, owned);
+}
+
 function validateAuditAction(
   label: string,
   auditAction: AuditActionType | undefined,

package/template/packages/modules/src/capability-guard-validation.ts

@@ -30,6 +30,13 @@ export function validateCapabilityGuardCompleteness(
         guard("AI Operation", operation),
       ),
       ...module.providers.map((provider) => guard("Provider", provider)),
+      ...(module.secrets ?? []).map((secret) =>
+        guard("Secret", {
+          key: secret.handle,
+          permissionKey: secret.permissionKey,
+          featureKey: secret.featureKey,
+        }),
+      ),
     ];
 
     for (const item of guards) {
@@ -79,6 +86,13 @@ export function validateCapabilityKeyAlignment(
         guard("AI Operation", operation),
       ),
       ...module.providers.map((provider) => guard("Provider", provider)),
+      ...(module.secrets ?? []).map((secret) =>
+        guard("Secret", {
+          key: secret.handle,
+          permissionKey: secret.permissionKey,
+          featureKey: secret.featureKey,
+        }),
+      ),
       ...(module.dataPolicies || []).flatMap((policy) =>
         [
           policy.readPermissionKey,
@@ -100,6 +114,33 @@ export function validateCapabilityKeyAlignment(
   }
 }
 
+export function validateOwnedCapabilityGuard(
+  module: ModuleManifest,
+  label: string,
+  input: { permissionKey?: string; featureKey?: string },
+): void {
+  const permission = module.permissions.find(
+    ({ key }) => key === input.permissionKey,
+  );
+  if (!permission || permission.module !== module.name) {
+    throw new Error(
+      `${label} 引用了非本模块权限：${input.permissionKey || "missing"}`,
+    );
+  }
+  const feature = module.features.find(({ key }) => key === input.featureKey);
+  if (!feature || feature.module !== module.name) {
+    throw new Error(
+      `${label} 引用了非本模块 Feature：${input.featureKey || "missing"}`,
+    );
+  }
+  validateKeyAlignment(
+    label,
+    input,
+    new Set([permission.key]),
+    new Set([feature.key]),
+  );
+}
+
 function validateKeyAlignment(
   label: string,
   input: { permissionKey?: string; featureKey?: string },

package/template/packages/modules/src/composition.ts

@@ -12,6 +12,10 @@ import {
 import { validateImplementationBindings } from "./implementation-bindings.js";
 import { composeModuleMenus } from "./menu-composition.js";
 import { validateCapabilityCatalogs } from "./catalog-validation.js";
+import {
+  snapshotModuleManifestSecrets,
+  validateSecretDeclarations,
+} from "./secret-composition.js";
 import { validateToolContracts } from "./tool-composition.js";
 
 export interface ValidatedModuleComposition {
@@ -27,10 +31,12 @@ export function validateModuleComposition(
   modules: readonly ModuleManifest[],
   implementations: ModuleImplementationBindings = {},
 ): ValidatedModuleComposition {
+  modules = modules.map(snapshotModuleManifestSecrets);
   const moduleNames = unique(
     "模块",
     modules.map(({ name }) => name),
   );
+  for (const module of modules) validateSecretDeclarations(module);
   const moduleOrder = validateDependencies(modules, moduleNames);
   validateCapabilityGuardCompleteness(modules);
   const permissions = unique(
@@ -86,6 +92,11 @@ export function validateModuleComposition(
     "Provider",
     providers.map(({ key }) => key),
   );
+  const secrets = modules.flatMap((module) => module.secrets ?? []);
+  unique(
+    "Secret handle",
+    secrets.map(({ handle }) => handle),
+  );
   const dataPolicies = modules.flatMap((module) => module.dataPolicies || []);
   unique(
     "数据治理策略",

package/template/packages/modules/src/manifest.ts

@@ -68,6 +68,21 @@ export interface ModuleProviderDefinition {
   featureKey?: string;
 }
 
+/**
+ * 模块可请求的逻辑 Secret。
+ *
+ * Manifest 只声明稳定业务标识与治理能力，不允许携带 env/file Provider 或物理 locator。
+ * 物理绑定由 project-owned Server Composition 持有。
+ */
+export interface ModuleSecretDefinition {
+  handle: string;
+  connection: string;
+  purpose: string;
+  permissionKey: string;
+  featureKey: string;
+  auditAction: AuditActionType;
+}
+
 export interface ModuleSchemaExportDefinition {
   key: string;
   exportName: string;
@@ -152,6 +167,28 @@ export interface AiOperationLimits {
   maxPixelsPerArtifact?: number;
 }
 
+/**
+ * 可选的 Runtime readiness V1 声明。缺失时保留旧 Operation 的兼容语义；
+ * 一旦声明，Host 必须以真实 downstream probe 投影后才允许执行。
+ */
+export interface AiOperationReadinessContractV1 {
+  readonly contractVersion: 1;
+  readonly variant: string;
+  readonly inputModalities: readonly AiOperationInputModality[];
+  readonly outputModalities: readonly (
+    | AiOperationInputModality
+    | "embedding"
+  )[];
+  readonly expectedDeployment: {
+    readonly key: string;
+    readonly identity: string;
+    readonly releaseDigest: `sha256:${string}`;
+    readonly offersDigest: `sha256:${string}`;
+  };
+  readonly minConcurrentRuns: number;
+  readonly minQueueDepth: number;
+}
+
 export interface ModuleAiOperationDefinition {
   key: string;
   kind: AiOperationKind;
@@ -162,6 +199,8 @@ export interface ModuleAiOperationDefinition {
   outputSchemaKey: string;
   /** 缺省为 text；声明 image 后才能提交图片 Artifact。 */
   inputModalities?: readonly AiOperationInputModality[];
+  /** additive V1：固定 variant、模态与不可变 deployment pin。 */
+  readiness?: AiOperationReadinessContractV1;
   requiredCapabilities: readonly string[];
   allowedToolKeys: readonly string[];
   dataClassification: AiOperationDataClassification;
@@ -193,6 +232,7 @@ export interface ModuleManifest {
   tools: ModuleToolDefinition[];
   aiOperations?: ModuleAiOperationDefinition[];
   providers: Array<ModuleProviderDefinition | SearchProviderManifestDefinition>;
+  secrets?: ModuleSecretDefinition[];
   dataPolicies?: DataGovernancePolicyDefinition[];
   auditActions: AuditActionRegistration[];
   metadata?: Record<string, unknown>;