create-windy 0.5.1 → 0.6.0

package/template/apps/server/src/document/output-artifact-host.ts

@@ -0,0 +1,331 @@
+import type {
+  ModuleAiOperationDefinition,
+  ModuleManifest,
+} from "@southwind-ai/modules";
+import type {
+  ModuleAiOperationReadinessPortV1,
+  ModuleAiOperationReadyV1,
+} from "@southwind-ai/server-sdk";
+import { evaluateAccessGuards } from "../access-guards.js";
+import type {
+  AiOutputArtifactReferenceV1,
+  AiOutputArtifactScope,
+  AiOutputArtifactSinkDescriptorV1,
+} from "../ai-output-artifact/contracts.js";
+import { AiOutputArtifactPolicyRegistry } from "../ai-output-artifact/policy.js";
+import type { AiOutputArtifactLimitSet } from "../ai-output-artifact/policy.js";
+import type { AiOutputArtifactCleanupService } from "../ai-output-artifact/cleanup.js";
+import type { AiOutputArtifactService } from "../ai-output-artifact/service.js";
+import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
+import { isServerScopeContext } from "../data-access/context.js";
+import type { RequestActor, RequestGuardContext } from "../guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import {
+  documentOutputArtifactInvocationDigest,
+  type DocumentOutputArtifactInvocation,
+} from "./output-artifact-fingerprint.js";
+import {
+  documentOutputOperations,
+  uniqueDocumentOutputBindings,
+  type DocumentOutputArtifactBinding,
+  type RegisteredDocumentOutputOperation,
+} from "./output-artifact-host-registry.js";
+import { documentOutputArtifactCapabilityV1 } from "./output-artifact-readiness.js";
+
+export type { DocumentOutputArtifactBinding } from "./output-artifact-host-registry.js";
+
+export interface DocumentOutputArtifactStart {
+  readonly runId: string;
+  readonly scopeId: string;
+  readonly grantGeneration: number;
+  readonly created: boolean;
+  readonly replayed: boolean;
+  readonly descriptor: AiOutputArtifactSinkDescriptorV1;
+  /** 仅允许作为内部 HTTP Header 转交；不得序列化、持久化或记录。 */
+  readonly grant?: string;
+  /** sealed 幂等重放时只供 Host 识别已完成状态，不交给 Provider。 */
+  readonly references?: readonly AiOutputArtifactReferenceV1[];
+}
+
+export class DocumentOutputArtifactHostError extends Error {
+  constructor(
+    readonly code: "CAPABILITY_UNAVAILABLE" | "RUN_CONFLICT",
+    message: string,
+  ) {
+    super(message);
+    this.name = "DocumentOutputArtifactHostError";
+  }
+}
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export class DocumentOutputArtifactHost {
+  readonly #bindings: Map<string, DocumentOutputArtifactBinding>;
+  readonly #operations: Map<string, RegisteredDocumentOutputOperation>;
+  readonly #policies = new AiOutputArtifactPolicyRegistry();
+
+  constructor(
+    modules: readonly ModuleManifest[],
+    bindings: readonly DocumentOutputArtifactBinding[],
+    private readonly readiness: ModuleAiOperationReadinessPortV1,
+    private readonly service: AiOutputArtifactService,
+    private readonly cleanup: AiOutputArtifactCleanupService,
+    private readonly runtime: ServerRuntime,
+    private readonly resolveActor: (
+      actorId: string,
+    ) => Promise<RequestActor | undefined>,
+    private readonly now: () => Date = () => new Date(),
+  ) {
+    this.#bindings = uniqueDocumentOutputBindings(bindings);
+    const features = modules.flatMap(({ features }) => features);
+    this.#operations = documentOutputOperations(modules, features);
+    for (const operationKey of this.#bindings.keys()) {
+      if (!this.#operations.has(operationKey)) {
+        throw new Error(
+          `Document Output Artifact Operation 未注册：${operationKey}`,
+        );
+      }
+    }
+  }
+
+  hasBinding(operationKey: string): boolean {
+    return this.#bindings.has(operationKey);
+  }
+
+  async begin(input: {
+    readonly definition: ModuleAiOperationDefinition;
+    readonly moduleName: string;
+    readonly runId: string;
+    readonly idempotencyKey: string;
+    readonly context: RequestGuardContext;
+    readonly invocation: DocumentOutputArtifactInvocation;
+  }): Promise<DocumentOutputArtifactStart | undefined> {
+    const binding = this.#bindings.get(input.definition.key);
+    if (!binding) return undefined;
+    if (
+      input.invocation.runId !== input.runId ||
+      input.invocation.operationKey !== input.definition.key
+    ) {
+      throw new DocumentOutputArtifactHostError(
+        "RUN_CONFLICT",
+        "Document Output Artifact 调用语义不匹配",
+      );
+    }
+    const projected = await this.readiness.inspect({
+      operationKey: input.definition.key,
+    });
+    const ready = requireAtomicReady(
+      projected,
+      input.definition.key,
+      this.now(),
+    );
+    const operationLimits = outputLimits(input.definition);
+    const runtimeLimits = outputLimitsFromOffer(ready);
+    const readinessLimits = minimumLimits(operationLimits, runtimeLimits);
+    const policy = this.#policies.resolve({
+      runtimeKind: "document",
+      outputKind: binding.outputKind,
+      dataClassification: input.definition.dataClassification,
+      operationLimits,
+      readinessLimits,
+      runtimeLimits,
+    });
+    try {
+      const begun = await this.service.beginScope({
+        runId: input.runId,
+        moduleName: input.moduleName,
+        operationKey: input.definition.key,
+        runtimeKind: "document",
+        idempotencyKey: input.idempotencyKey,
+        invocationDigest: documentOutputArtifactInvocationDigest(
+          input.invocation,
+          {
+            deploymentIdentity: ready.deployment.identity,
+            releaseDigest: ready.deployment.releaseDigest,
+            offersDigest: ready.deployment.offersDigest,
+            policy,
+          },
+        ),
+        dataClassification: input.definition.dataClassification,
+        deploymentIdentity: ready.deployment.identity,
+        releaseDigest: ready.deployment.releaseDigest,
+        offersDigest: ready.deployment.offersDigest,
+        policy,
+        context: input.context,
+      });
+      if (!begun.descriptor) throw new Error("missing descriptor");
+      return {
+        runId: begun.scope.runId,
+        scopeId: begun.scope.scopeId,
+        grantGeneration: begun.descriptor.grantGeneration,
+        created: begun.created,
+        replayed: begun.replayed,
+        descriptor: begun.descriptor,
+        grant: begun.grant,
+        references: begun.references,
+      };
+    } catch (error) {
+      if (
+        error instanceof Error &&
+        "code" in error &&
+        error.code === "OUTPUT_ARTIFACT_CONFLICT"
+      ) {
+        throw new DocumentOutputArtifactHostError(
+          "RUN_CONFLICT",
+          "Document Output Artifact 幂等语义冲突",
+        );
+      }
+      throw new DocumentOutputArtifactHostError(
+        "CAPABILITY_UNAVAILABLE",
+        "Document Output Artifact 暂时不可用",
+      );
+    }
+  }
+
+  abortRun(runId: string): Promise<boolean> {
+    return this.cleanup.abortRun(runId);
+  }
+
+  abortOpenRun(runId: string): Promise<boolean> {
+    return this.cleanup.abortOpenRun(runId);
+  }
+
+  acceptGrant(
+    scopeId: string,
+    generation: number,
+    grant: string,
+  ): Promise<AiOutputArtifactScope> {
+    return this.service.acceptGrant(scopeId, generation, grant);
+  }
+
+  confirmGrant(
+    scopeId: string,
+    generation: number,
+    grant: string,
+  ): Promise<boolean> {
+    return this.service.confirmGrant(scopeId, generation, grant);
+  }
+
+  rollbackPendingGrant(scopeId: string, generation: number, grant: string) {
+    return this.service.rollbackPendingGrant(scopeId, generation, grant);
+  }
+
+  async authorizeRead(
+    scope: AiOutputArtifactScope,
+    signal: AbortSignal,
+  ): Promise<
+    { actorId?: string; scopeHash?: string; requestId: string } | undefined
+  > {
+    try {
+      const binding = this.#bindings.get(scope.operationKey);
+      const operation = this.#operations.get(scope.operationKey);
+      if (
+        !binding ||
+        !operation ||
+        operation.moduleName !== scope.moduleName ||
+        binding.outputKind !== scope.outputKind ||
+        scope.runtimeKind !== "document" ||
+        operation.definition.dataClassification !== scope.dataClassification
+      ) {
+        return undefined;
+      }
+      const actor = await this.resolveActor(scope.actorId);
+      if (
+        !actor ||
+        !isServerScopeContext(actor.scopeContext) ||
+        actor.scopeContext.tenantId !== scope.tenantId
+      ) {
+        return undefined;
+      }
+      const request = new Request("http://ai-output.internal/read", { signal });
+      const context = await this.runtime.createGuardContextForActor(
+        request,
+        actor,
+      );
+      const access = await evaluateAccessGuards(this.runtime, context, {
+        permission: {
+          permissionKey: operation.definition.permissionKey,
+        },
+        feature: operation.feature,
+      });
+      if (!access.decision.allowed) {
+        return { requestId: context.requestId };
+      }
+      const captured = captureAuthorizationScope(actor.scopeContext);
+      return captured.hash === scope.scopeHash
+        ? {
+            actorId: actor.id,
+            scopeHash: captured.hash,
+            requestId: context.requestId,
+          }
+        : { requestId: context.requestId };
+    } catch {
+      return undefined;
+    }
+  }
+}
+
+function requireAtomicReady(
+  value: Awaited<ReturnType<ModuleAiOperationReadinessPortV1["inspect"]>>,
+  operationKey: string,
+  now: Date,
+): ModuleAiOperationReadyV1 {
+  if (
+    value.status !== "ready" ||
+    value.operationKey !== operationKey ||
+    value.runtimeKind !== "document" ||
+    value.offers.length !== 1 ||
+    !value.offers[0]?.capabilities.includes(documentOutputArtifactCapabilityV1)
+  ) {
+    throw new DocumentOutputArtifactHostError(
+      "CAPABILITY_UNAVAILABLE",
+      "Document Runtime readiness 不可用",
+    );
+  }
+  const validUntil = Date.parse(value.validUntil);
+  if (!Number.isFinite(validUntil) || validUntil <= now.getTime()) {
+    throw new DocumentOutputArtifactHostError(
+      "CAPABILITY_UNAVAILABLE",
+      "Document Runtime readiness 已过期",
+    );
+  }
+  return value;
+}
+
+function outputLimits(
+  definition: ModuleAiOperationDefinition,
+): AiOutputArtifactLimitSet {
+  return {
+    maxArtifactBytes: definition.limits.maxOutputBytes,
+    maxArtifacts: definition.limits.maxArtifacts ?? 1,
+    maxTotalBytes: definition.limits.maxOutputBytes,
+    maxDurationSeconds: definition.limits.maxDurationSeconds,
+  };
+}
+
+function outputLimitsFromOffer(
+  ready: ModuleAiOperationReadyV1,
+): AiOutputArtifactLimitSet {
+  const limits = ready.offers[0].limits;
+  return {
+    maxArtifactBytes: limits.maxOutputBytes,
+    maxArtifacts: limits.maxArtifacts ?? 1,
+    maxTotalBytes: limits.maxOutputBytes,
+    maxDurationSeconds: limits.maxDurationSeconds,
+  };
+}
+
+function minimumLimits(
+  left: AiOutputArtifactLimitSet,
+  right: AiOutputArtifactLimitSet,
+): AiOutputArtifactLimitSet {
+  return {
+    maxArtifactBytes: Math.min(left.maxArtifactBytes, right.maxArtifactBytes),
+    maxArtifacts: Math.min(left.maxArtifacts, right.maxArtifacts),
+    maxTotalBytes: Math.min(left.maxTotalBytes, right.maxTotalBytes),
+    maxDurationSeconds: Math.min(
+      left.maxDurationSeconds,
+      right.maxDurationSeconds,
+    ),
+  };
+}

package/template/apps/server/src/document/output-artifact-manifest.test-support.ts

@@ -0,0 +1,71 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import { featureKey } from "@southwind-ai/shared";
+
+export const operationKey = "evidence.document.ocr";
+
+export function documentManifest(): ModuleManifest {
+  return {
+    name: "evidence",
+    version: "0.1.0",
+    label: "物证",
+    description: "物证",
+    menus: [],
+    adminRoutes: [],
+    permissions: [
+      {
+        key: "evidence.document.ocr.execute",
+        label: "OCR",
+        module: "evidence",
+        moduleLabel: "物证",
+        resource: "document",
+        resourceLabel: "文档",
+        action: "manage",
+      },
+    ],
+    apiPermissions: [],
+    features: [
+      {
+        key: featureKey("evidence.document.ocr"),
+        label: "OCR",
+        module: "evidence",
+        visible: "visible",
+        enabled: true,
+        stage: "stable",
+      },
+    ],
+    migrations: [],
+    schemaExports: [],
+    jsonSchemas: [
+      { key: "evidence.document.input.v1", schema: { type: "object" } },
+      { key: "evidence.document.output.v1", schema: { type: "object" } },
+    ],
+    tasks: [],
+    tools: [],
+    aiOperations: [
+      {
+        key: operationKey,
+        kind: "document",
+        featureKey: "evidence.document.ocr",
+        permissionKey: "evidence.document.ocr.execute",
+        auditAction: "evidence.document.ocr.execute",
+        inputSchemaKey: "evidence.document.input.v1",
+        outputSchemaKey: "evidence.document.output.v1",
+        inputModalities: ["document"],
+        requiredCapabilities: ["document.ocr"],
+        allowedToolKeys: [],
+        dataClassification: "sensitive",
+        execution: "background",
+        providerEgress: { mode: "forbidden" },
+        limits: {
+          maxDurationSeconds: 60,
+          maxInputBytes: 4_096,
+          maxOutputBytes: 4_096,
+          maxUnits: 20,
+          maxArtifacts: 2,
+        },
+      },
+    ],
+    providers: [],
+    auditActions: ["evidence.document.ocr.execute"],
+  };
+}

package/template/apps/server/src/document/output-artifact-publish.test-support.ts

@@ -0,0 +1,48 @@
+import {
+  outputByteStream,
+  outputHash,
+  outputManifest,
+} from "../ai-output-artifact/test-support.js";
+import { createDocumentOutputFixture } from "./output-artifact.test-support.js";
+
+export const documentOutputSource = {
+  value: "input-artifact",
+  mediaType: "application/pdf",
+  byteSize: 10,
+  sha256: "a".repeat(64),
+  expiresAt: "2026-07-31T12:05:00.000Z",
+};
+
+export async function publishDocumentOutput(
+  fixture: Awaited<ReturnType<typeof createDocumentOutputFixture>>,
+  scopeId: string,
+  grant: string,
+) {
+  const bytes = new TextEncoder().encode("%PDF-1.7\nfacade");
+  const receipt = await fixture.output.service.beginArtifact(
+    scopeId,
+    grant,
+    outputManifest(bytes),
+    new AbortController().signal,
+  );
+  await fixture.output.service.appendPart(
+    scopeId,
+    grant,
+    {
+      artifactId: receipt.artifactId,
+      partNumber: 0,
+      byteOffset: 0,
+      byteSize: bytes.byteLength,
+      sha256: outputHash(bytes),
+      body: outputByteStream(bytes),
+    },
+    new AbortController().signal,
+  );
+  await fixture.output.service.completeArtifact(
+    scopeId,
+    grant,
+    receipt.artifactId,
+    new AbortController().signal,
+  );
+  return fixture.output.service.sealScope(scopeId, grant);
+}