create-windy 0.5.2 → 0.6.0

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

@@ -0,0 +1,150 @@
+import { createHash } from "node:crypto";
+import type { AiOutputArtifactPolicy } from "../ai-output-artifact/policy.js";
+import type { DocumentRuntimeOperation } from "./contracts.js";
+
+export type DocumentOutputArtifactInvocation = Omit<
+  DocumentRuntimeOperation,
+  "outputArtifactSink" | "runId"
+> & {
+  readonly runId: string;
+};
+
+export function documentRuntimeRequestFingerprint(
+  invocation: DocumentRuntimeOperation,
+  resolvedRunId = invocation.runId,
+): string {
+  if (!resolvedRunId) {
+    throw new Error("Document Runtime fingerprint 缺少 Run ID");
+  }
+  const sink = invocation.outputArtifactSink;
+  return createHash("sha256")
+    .update(
+      canonical({
+        contractVersion: 1,
+        kind: invocation.kind,
+        runId: resolvedRunId,
+        operationKey: invocation.operationKey,
+        options: invocation.options,
+        sources: invocation.sources.map(({ mediaType, byteSize, sha256 }) => ({
+          mediaType,
+          byteSize,
+          sha256,
+        })),
+        requiredCapabilities: [...invocation.requiredCapabilities].sort(),
+        dataClassification: invocation.dataClassification,
+        limits: invocation.limits,
+        providerEgress: invocation.providerEgress,
+        ...(invocation.providerDataPolicy
+          ? { providerDataPolicy: invocation.providerDataPolicy }
+          : {}),
+        ...(sink
+          ? {
+              outputArtifactSink: {
+                contractVersion: sink.contractVersion,
+                outputKind: sink.outputKind,
+                deploymentIdentity: sink.deploymentIdentity,
+                releaseDigest: sink.releaseDigest,
+                offersDigest: sink.offersDigest,
+                policyDigest: sink.policyDigest,
+                allowedMediaTypes: [...sink.allowedMediaTypes].sort(),
+                limits: sink.limits,
+              },
+            }
+          : {}),
+      }),
+    )
+    .digest("hex");
+}
+
+export function documentOutputArtifactInvocationDigest(
+  invocation: DocumentOutputArtifactInvocation,
+  governance: {
+    readonly deploymentIdentity: string;
+    readonly releaseDigest: string;
+    readonly offersDigest: string;
+    readonly policy: AiOutputArtifactPolicy;
+  },
+): string {
+  return createHash("sha256")
+    .update(
+      canonical({
+        kind: invocation.kind,
+        runId: invocation.runId,
+        operationKey: invocation.operationKey,
+        options: invocation.options,
+        sources: invocation.sources.map(({ mediaType, byteSize, sha256 }) => ({
+          mediaType,
+          byteSize,
+          sha256,
+        })),
+        requiredCapabilities: invocation.requiredCapabilities,
+        dataClassification: invocation.dataClassification,
+        limits: invocation.limits,
+        providerEgress: invocation.providerEgress,
+        ...(invocation.providerDataPolicy
+          ? { providerDataPolicy: invocation.providerDataPolicy }
+          : {}),
+        outputArtifactSink: {
+          outputKind: governance.policy.outputKind,
+          deploymentIdentity: governance.deploymentIdentity,
+          releaseDigest: governance.releaseDigest,
+          offersDigest: governance.offersDigest,
+          policyDigest: governance.policy.digest,
+          allowedMediaTypes: governance.policy.allowedMediaTypes,
+          limits: {
+            maxArtifactBytes: governance.policy.maxArtifactBytes,
+            maxArtifacts: governance.policy.maxArtifacts,
+            maxTotalBytes: governance.policy.maxTotalBytes,
+          },
+        },
+      }),
+    )
+    .digest("hex");
+}
+
+function canonical(value: unknown): string {
+  if (value === null || typeof value === "boolean") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "string") {
+    assertUnicodeScalarString(value);
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value))
+      throw new Error("Document invocation 数字无效");
+    if (Number.isInteger(value) && !Number.isSafeInteger(value)) {
+      throw new Error("Document invocation 整数超出安全范围");
+    }
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(canonical).join(",")}]`;
+  }
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value)
+      .filter(([, item]) => item !== undefined)
+      .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+      .map(([key, item]) => {
+        assertUnicodeScalarString(key);
+        return `${JSON.stringify(key)}:${canonical(item)}`;
+      })
+      .join(",")}}`;
+  }
+  throw new Error("Document invocation 不是可规范化 JSON");
+}
+
+function assertUnicodeScalarString(value: string): void {
+  for (let index = 0; index < value.length; index += 1) {
+    const code = value.charCodeAt(index);
+    if (code >= 0xd800 && code <= 0xdbff) {
+      const next = value.charCodeAt(index + 1);
+      if (!(next >= 0xdc00 && next <= 0xdfff)) {
+        throw new Error("Document invocation Unicode surrogate 无效");
+      }
+      index += 1;
+    } else if (code >= 0xdc00 && code <= 0xdfff) {
+      throw new Error("Document invocation Unicode surrogate 无效");
+    }
+  }
+}

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

@@ -0,0 +1,44 @@
+import type {
+  ModuleAiOperationDefinition,
+  ModuleManifest,
+} from "@southwind-ai/modules";
+import type { FeatureFlagDefinition } from "@southwind-ai/shared";
+import {
+  outputArtifactOperations,
+  uniqueOutputArtifactBindings,
+} from "../ai-output-artifact/host-registry.js";
+
+export interface DocumentOutputArtifactBinding {
+  readonly operationKey: string;
+  readonly outputKind: "searchable-pdf";
+}
+
+export interface RegisteredDocumentOutputOperation {
+  readonly moduleName: string;
+  readonly definition: ModuleAiOperationDefinition;
+  readonly feature: FeatureFlagDefinition | undefined;
+}
+
+export function documentOutputOperations(
+  modules: readonly ModuleManifest[],
+  features: readonly FeatureFlagDefinition[],
+): Map<string, RegisteredDocumentOutputOperation> {
+  return outputArtifactOperations(modules, features, "document") as Map<
+    string,
+    RegisteredDocumentOutputOperation
+  >;
+}
+
+export function uniqueDocumentOutputBindings(
+  bindings: readonly DocumentOutputArtifactBinding[],
+): Map<string, DocumentOutputArtifactBinding> {
+  const generic = uniqueOutputArtifactBindings(
+    bindings.map((binding) => ({ ...binding, runtimeKind: "document" })),
+  );
+  return new Map(
+    [...generic].map(([key, binding]) => [
+      key,
+      { operationKey: binding.operationKey, outputKind: "searchable-pdf" },
+    ]),
+  );
+}

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

@@ -0,0 +1,332 @@
+import { describe, expect, test } from "bun:test";
+import {
+  outputByteStream,
+  outputHash,
+  outputManifest,
+} from "../ai-output-artifact/test-support.js";
+import { DocumentOutputArtifactHostError } from "./output-artifact-host.js";
+import {
+  createDocumentOutputFixture,
+  documentActor,
+  documentOutputInvocation,
+  operationKey,
+  readyProjection,
+} from "./output-artifact.test-support.js";
+
+describe("Document Output Artifact Host", () => {
+  test("冻结 atomic offer 与四层最小限额，首次 grant 只进入 pending hash", async () => {
+    const fixture = await createDocumentOutputFixture();
+    const begun = await fixture.output.host.begin({
+      definition: fixture.module.aiOperations![0]!,
+      moduleName: fixture.module.name,
+      runId: "doc_run_1",
+      idempotencyKey: "scoped-idempotency-1",
+      context: fixture.context(),
+      invocation: documentOutputInvocation("doc_run_1"),
+    });
+    expect(begun).toMatchObject({
+      runId: "doc_run_1",
+      created: true,
+      replayed: false,
+      grantGeneration: 1,
+      descriptor: {
+        contractVersion: 1,
+        grantGeneration: 1,
+        outputKind: "searchable-pdf",
+        deploymentIdentity:
+          "windy-deployment-v1_7db61d8e-e50d-4f8a-9f3f-9b7a1d932e01",
+        releaseDigest: `sha256:${"a".repeat(64)}`,
+        offersDigest: `sha256:${"b".repeat(64)}`,
+        policyDigest: expect.stringMatching(/^[a-f0-9]{64}$/),
+        limits: {
+          maxArtifactBytes: 2_048,
+          maxArtifacts: 1,
+          maxTotalBytes: 2_048,
+        },
+      },
+    });
+    expect(begun!.descriptor).not.toHaveProperty("grant");
+    const scope = await fixture.output.service.options.repository.getScope(
+      begun!.descriptor.scope,
+    );
+    expect(scope).toMatchObject({
+      operationKey,
+      deploymentIdentity:
+        "windy-deployment-v1_7db61d8e-e50d-4f8a-9f3f-9b7a1d932e01",
+      releaseDigest: `sha256:${"a".repeat(64)}`,
+      offersDigest: `sha256:${"b".repeat(64)}`,
+    });
+    expect(scope).not.toHaveProperty("grantHash");
+    expect(scope).not.toHaveProperty("activeGrantGeneration");
+    expect(scope?.pendingGrantHash).toMatch(/^[a-f0-9]{64}$/);
+    expect(scope?.pendingGrantGeneration).toBe(1);
+    expect(JSON.stringify(scope)).not.toContain(begun!.grant!);
+    expect(JSON.stringify(begun!.descriptor)).not.toContain(begun!.grant!);
+    const accepted = await fixture.output.host.acceptGrant(
+      begun!.scopeId,
+      begun!.grantGeneration,
+      begun!.grant!,
+    );
+    expect(accepted.grantHash).toMatch(/^[a-f0-9]{64}$/);
+    expect(accepted.activeGrantGeneration).toBe(1);
+    expect(accepted.pendingGrantHash).toBeUndefined();
+  });
+
+  test("open replay 在 ACK 前保留 current，promote 后旧 grant 才失效", async () => {
+    const fixture = await createDocumentOutputFixture();
+    const input = {
+      definition: fixture.module.aiOperations![0]!,
+      moduleName: fixture.module.name,
+      runId: "doc_generation",
+      idempotencyKey: "scoped-generation",
+      context: fixture.context(),
+      invocation: documentOutputInvocation("doc_generation"),
+    };
+    const first = await fixture.output.host.begin(input);
+    await fixture.output.host.acceptGrant(
+      first!.scopeId,
+      first!.grantGeneration,
+      first!.grant!,
+    );
+    const second = await fixture.output.host.begin(input);
+
+    expect(second).toMatchObject({
+      created: false,
+      replayed: true,
+      grantGeneration: 2,
+      descriptor: { grantGeneration: 2 },
+    });
+    await expect(
+      fixture.output.service.requireWritable(first!.scopeId, first!.grant!),
+    ).resolves.toMatchObject({ activeGrantGeneration: 1 });
+    await expect(
+      fixture.output.service.requireWritable(first!.scopeId, second!.grant!),
+    ).rejects.toMatchObject({ code: "OUTPUT_ARTIFACT_FORBIDDEN" });
+    await fixture.output.host.acceptGrant(
+      second!.scopeId,
+      second!.grantGeneration,
+      second!.grant!,
+    );
+    await expect(
+      fixture.output.service.requireWritable(first!.scopeId, first!.grant!),
+    ).rejects.toMatchObject({ code: "OUTPUT_ARTIFACT_FORBIDDEN" });
+  });
+
+  test("缺失、过期或非 atomic readiness 一律失败关闭", async () => {
+    for (const readiness of [
+      readyProjection({ status: "unavailable" }),
+      readyProjection({ validUntil: "2026-07-31T11:59:59.000Z" }),
+      readyProjection({ offerCount: 2 }),
+      withoutOutputArtifactCapability(),
+    ]) {
+      const fixture = await createDocumentOutputFixture(() => readiness);
+      await expect(
+        fixture.output.host.begin({
+          definition: fixture.module.aiOperations![0]!,
+          moduleName: fixture.module.name,
+          runId: "doc_unready",
+          idempotencyKey: "scoped-unready",
+          context: fixture.context(),
+          invocation: documentOutputInvocation("doc_unready"),
+        }),
+      ).rejects.toBeInstanceOf(DocumentOutputArtifactHostError);
+    }
+  });
+
+  test("ref 每次重跑当前 Guard 与 scope，审计不含 raw grant/ref", async () => {
+    const fixture = await createDocumentOutputFixture();
+    const startContext = fixture.context();
+    const begun = await fixture.output.host.begin({
+      definition: fixture.module.aiOperations![0]!,
+      moduleName: fixture.module.name,
+      runId: "doc_read_auth",
+      idempotencyKey: "scoped-read-auth",
+      context: startContext,
+      invocation: documentOutputInvocation("doc_read_auth"),
+    });
+    await fixture.output.host.acceptGrant(
+      begun!.scopeId,
+      begun!.grantGeneration,
+      begun!.grant!,
+    );
+    const bytes = new TextEncoder().encode("%PDF-1.7\nauth");
+    const receipt = await fixture.output.service.beginArtifact(
+      begun!.descriptor.scope,
+      begun!.grant!,
+      outputManifest(bytes),
+      new AbortController().signal,
+    );
+    await fixture.output.service.appendPart(
+      begun!.descriptor.scope,
+      begun!.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(
+      begun!.descriptor.scope,
+      begun!.grant!,
+      receipt.artifactId,
+      new AbortController().signal,
+    );
+    const [reference] = await fixture.output.service.sealScope(
+      begun!.descriptor.scope,
+      begun!.grant!,
+    );
+    const opened = await fixture.output.service.openReference(
+      reference!.value,
+      new AbortController().signal,
+    );
+    expect(
+      new Uint8Array(await new Response(opened.body).arrayBuffer()),
+    ).toEqual(bytes);
+    const storedScope =
+      await fixture.output.service.options.repository.getScope(begun!.scopeId);
+    expect(storedScope?.requestId).toBe(startContext.requestId);
+    const outputAudit = fixture.runtime.auditSink
+      .list()
+      .filter(
+        ({ metadata }) => metadata?.correlationId === "ai-output:doc_read_auth",
+      );
+    expect(
+      outputAudit.find(({ action }) => action === "data.read"),
+    ).toMatchObject({
+      requestId: expect.not.stringMatching(
+        new RegExp(`^${startContext.requestId}$`),
+      ),
+      metadata: { correlationId: "ai-output:doc_read_auth" },
+    });
+    expect(
+      outputAudit.find(
+        ({ action }) => action !== "data.read" && action !== "security.denied",
+      ),
+    ).toMatchObject({
+      requestId: startContext.requestId,
+      metadata: { correlationId: "ai-output:doc_read_auth" },
+    });
+
+    fixture.setActor(documentActor([]));
+    await expect(
+      fixture.output.service.openReference(
+        reference!.value,
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({ code: "OUTPUT_ARTIFACT_FORBIDDEN" });
+    fixture.setActor(documentActor(undefined, "other-scope"));
+    await expect(
+      fixture.output.service.openReference(
+        reference!.value,
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({ code: "OUTPUT_ARTIFACT_FORBIDDEN" });
+    fixture.setActor(documentActor());
+    fixture.setFeatureEnabled(false);
+    await expect(
+      fixture.output.service.openReference(
+        reference!.value,
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({ code: "OUTPUT_ARTIFACT_FORBIDDEN" });
+    fixture.setFeatureEnabled(true);
+    fixture.setLicenseRestricted(true);
+    await expect(
+      fixture.output.service.openReference(
+        reference!.value,
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({ code: "OUTPUT_ARTIFACT_FORBIDDEN" });
+
+    const audits = fixture.runtime.auditSink.list();
+    const deniedReads = audits.filter(
+      ({ action, metadata }) =>
+        action === "security.denied" &&
+        metadata?.correlationId === "ai-output:doc_read_auth",
+    );
+    expect(deniedReads).toHaveLength(4);
+    expect(
+      deniedReads.every(
+        ({ requestId }) => requestId !== startContext.requestId,
+      ),
+    ).toBe(true);
+    const audit = JSON.stringify(audits);
+    expect(audit).not.toContain(begun!.grant!);
+    expect(audit).not.toContain(reference!.value);
+  });
+
+  test("sealed 重放保留 descriptor+refs，但绝不恢复 raw grant", async () => {
+    const fixture = await createDocumentOutputFixture();
+    const input = {
+      definition: fixture.module.aiOperations![0]!,
+      moduleName: fixture.module.name,
+      runId: "doc_sealed_replay",
+      idempotencyKey: "scoped-sealed-replay",
+      context: fixture.context(),
+      invocation: documentOutputInvocation("doc_sealed_replay"),
+    };
+    const begun = await fixture.output.host.begin(input);
+    await fixture.output.host.acceptGrant(
+      begun!.scopeId,
+      begun!.grantGeneration,
+      begun!.grant!,
+    );
+    const bytes = new Uint8Array([1]);
+    const receipt = await fixture.output.service.beginArtifact(
+      begun!.descriptor.scope,
+      begun!.grant!,
+      outputManifest(bytes),
+      new AbortController().signal,
+    );
+    await fixture.output.service.appendPart(
+      begun!.descriptor.scope,
+      begun!.grant!,
+      {
+        artifactId: receipt.artifactId,
+        partNumber: 0,
+        byteOffset: 0,
+        byteSize: 1,
+        sha256: outputHash(bytes),
+        body: outputByteStream(bytes),
+      },
+      new AbortController().signal,
+    );
+    await fixture.output.service.completeArtifact(
+      begun!.descriptor.scope,
+      begun!.grant!,
+      receipt.artifactId,
+      new AbortController().signal,
+    );
+    await fixture.output.service.sealScope(
+      begun!.descriptor.scope,
+      begun!.grant!,
+    );
+
+    const replay = await fixture.output.host.begin(input);
+    expect(replay?.descriptor).toEqual({
+      ...begun!.descriptor,
+      grantGeneration: 1,
+    });
+    expect(replay?.grantGeneration).toBe(1);
+    expect(replay?.references).toHaveLength(1);
+    expect(replay?.grant).toBeUndefined();
+  });
+});
+
+function withoutOutputArtifactCapability() {
+  const readiness = readyProjection();
+  if (readiness.status !== "ready") throw new Error("expected ready fixture");
+  return {
+    ...readiness,
+    offers: [
+      {
+        ...readiness.offers[0],
+        capabilities: ["document.ocr"],
+      },
+    ],
+  } as typeof readiness;
+}