create-windy 0.6.12 → 0.6.15

package/template/apps/server/src/auth/composition.ts

@@ -0,0 +1,36 @@
+import type { PlatformConfig } from "@southwind-ai/config";
+import type { ServerPersistence } from "../persistence.js";
+import type { createServerRuntime } from "../runtime.js";
+import { createAuthRuntime } from "./runtime.js";
+
+export function createComposedAuthRuntime(input: {
+  platformConfig: PlatformConfig;
+  persistence?: ServerPersistence;
+  runtime: ReturnType<typeof createServerRuntime>;
+}) {
+  let revokeClientSessions: (actorId: string) => Promise<void> = async () =>
+    undefined;
+  const auth = createAuthRuntime({
+    repository: input.persistence?.authRepository,
+    sessionTtlSeconds: () => input.platformConfig.security.sessionTtlSeconds,
+    passwordPolicy: () => ({
+      minLength: input.platformConfig.security.passwordMinLength,
+      maxLength: input.platformConfig.security.passwordMaxLength,
+    }),
+    auditWriter: (event) => input.runtime.auditSink.recordCriticalEvent(event),
+    // @windy-module system.audit begin
+    auditReader: input.persistence?.auditReader,
+    // @windy-module system.audit end
+    onSessionsRevoked: (actorId) => revokeClientSessions(actorId),
+  });
+  return {
+    ...auth,
+    bindClientAgentSessions(
+      service: { revokeActor(actorId: string): Promise<number> } | undefined,
+    ) {
+      revokeClientSessions = async (actorId) => {
+        await service?.revokeActor(actorId);
+      };
+    },
+  };
+}

package/template/apps/server/src/auth/routes.test-support.ts

@@ -11,6 +11,7 @@ export function authFixture(
   users: AuthUserRecord[],
   passwordPolicy?: () => PasswordPolicy,
   sessionTtlSeconds?: () => number,
+  onSessionsRevoked?: (actorId: string) => Promise<void> | void,
 ) {
   const repository = new InMemoryAuthRepository(users);
   const resolver = new RepositoryActorResolver(repository, {
@@ -21,6 +22,7 @@ export function authFixture(
   const service = new AuthService(repository, {
     passwordPolicy,
     sessionTtlSeconds,
+    onSessionsRevoked,
     auditWriter: {
       write(event) {
         events.push(event);

package/template/apps/server/src/auth/routes.test.ts

@@ -89,6 +89,24 @@ describe("platform auth API", () => {
     expect(JSON.stringify(body)).not.toContain(current.token);
   });
 
+  test("登出即时通知 Client Agent Session 按 canonical Actor 撤销", async () => {
+    const revoked: string[] = [];
+    const fixture = authFixture(
+      [activeUser()],
+      undefined,
+      undefined,
+      (actorId) => {
+        revoked.push(actorId);
+      },
+    );
+    const current = await login(fixture.app, "admin");
+    const response = await fixture.app.handle(
+      apiRequest("/api/auth/logout", current.token, "POST"),
+    );
+    expect(response.status).toBe(200);
+    expect(revoked).toEqual(["user_admin"]);
+  });
+
   test("Admin 登录只签发 Cookie，独立 API 登录才返回 Bearer Token", async () => {
     const fixture = authFixture([activeUser()]);
     const browserLogin = await fixture.app.handle(

package/template/apps/server/src/auth/runtime.ts

@@ -11,6 +11,7 @@ interface AuthRuntimeInput {
   passwordPolicy?: () => PasswordPolicy;
   auditWriter: AuditEventWriter["write"];
   auditReader?: AuditEventReader;
+  onSessionsRevoked?: (actorId: string) => Promise<void> | void;
 }
 
 export function createAuthRuntime(input: AuthRuntimeInput) {
@@ -22,6 +23,7 @@ export function createAuthRuntime(input: AuthRuntimeInput) {
     auditWriter: { write: input.auditWriter },
     auditReader: input.auditReader,
     passwordHasher,
+    onSessionsRevoked: input.onSessionsRevoked,
   });
   const reauthentication = new ReauthenticationService(
     authRepository,

package/template/apps/server/src/auth/service-options.ts

@@ -0,0 +1,16 @@
+import type { PasswordPolicy } from "@southwind-ai/shared";
+import type { AuditEventReader, AuditEventWriter } from "../runtime.js";
+import type { AuthenticationProviderRegistry } from "./authentication-provider.js";
+import type { PasswordHasher } from "./password.js";
+
+export interface AuthServiceOptions {
+  sessionTtlSeconds?: number | (() => number);
+  passwordPolicy?: () => PasswordPolicy;
+  now?: () => Date;
+  tokenFactory?: () => string;
+  passwordHasher?: PasswordHasher;
+  authenticationProviders?: AuthenticationProviderRegistry;
+  auditWriter: AuditEventWriter;
+  auditReader?: AuditEventReader;
+  onSessionsRevoked?: (actorId: string) => Promise<void> | void;
+}

package/template/apps/server/src/auth/service.ts

@@ -6,7 +6,6 @@ import {
   type PasswordPolicy,
 } from "@southwind-ai/shared";
 import type { RequestActor } from "../guards.js";
-import type { AuditEventReader, AuditEventWriter } from "../runtime.js";
 import { hashSessionToken } from "./actor-resolver.js";
 import {
   AuthenticationProviderRegistry,
@@ -20,6 +19,7 @@ import {
   type PasswordUpdateResult,
 } from "./credential-service.js";
 import { OwnSessionService } from "./session-service.js";
+import type { AuthServiceOptions } from "./service-options.js";
 
 export interface AuthRequestMetadata {
   ip?: string;
@@ -45,17 +45,6 @@ export type RevokeResult =
   | { ok: true; sessionId: string; currentSessionRevoked: boolean }
   | { ok: false; code: "SESSION_NOT_FOUND" | "FORBIDDEN" };
 
-export interface AuthServiceOptions {
-  sessionTtlSeconds?: number | (() => number);
-  passwordPolicy?: () => PasswordPolicy;
-  now?: () => Date;
-  tokenFactory?: () => string;
-  passwordHasher?: PasswordHasher;
-  authenticationProviders?: AuthenticationProviderRegistry;
-  auditWriter: AuditEventWriter;
-  auditReader?: AuditEventReader;
-}
-
 export class AuthService {
   private readonly sessionTtlSeconds: () => number;
   private readonly passwordPolicy: () => PasswordPolicy;
@@ -191,6 +180,8 @@ export class AuthService {
     const revoked = session
       ? await this.repository.revokeSession(session.id, this.now())
       : false;
+    if (revoked && session)
+      await this.options.onSessionsRevoked?.(session.userId);
     await this.recordAuthEvent({
       action: "auth.logout",
       outcome: revoked ? "success" : "failure",
@@ -267,6 +258,7 @@ export class AuthService {
     const currentSessionRevoked =
       revoked &&
       (await this.ownSessions.isCurrent(sessionId, actor, currentToken));
+    if (revoked) await this.options.onSessionsRevoked?.(session.userId);
     return revoked
       ? { ok: true, sessionId, currentSessionRevoked }
       : { ok: false, code: "SESSION_NOT_FOUND" };
@@ -299,6 +291,9 @@ export class AuthService {
       metadata: { scope: "all-own", includeCurrent, ...result },
       request: metadata,
     });
+    if (result.revokedSessions > 0) {
+      await this.options.onSessionsRevoked?.(actor.id);
+    }
     return result;
   }
 

package/template/apps/server/src/data-access/scope-containment.test.ts

@@ -0,0 +1,31 @@
+import { expect, test } from "bun:test";
+import type { AuthorizationScopeSnapshot } from "@southwind-ai/shared";
+import { authorizationScopeContains } from "./scope-containment.js";
+
+const base = {
+  tenantId: "single-tenant",
+  actorId: "actor-1",
+  roleIds: ["analyst"],
+} satisfies Omit<AuthorizationScopeSnapshot, "grants">;
+
+test("当前多案 custom scope 可包含冻结单案 scope", () => {
+  const current: AuthorizationScopeSnapshot = {
+    ...base,
+    grants: [{ scope: "custom", dimension: "caseId", values: ["a", "b"] }],
+  };
+  const frozen: AuthorizationScopeSnapshot = {
+    ...base,
+    grants: [{ scope: "custom", dimension: "caseId", values: ["a"] }],
+  };
+  expect(authorizationScopeContains(current, frozen)).toBe(true);
+  expect(
+    authorizationScopeContains(current, {
+      ...frozen,
+      roleIds: ["role-no-longer-held"],
+    }),
+  ).toBe(false);
+  expect(authorizationScopeContains(frozen, current)).toBe(false);
+  expect(
+    authorizationScopeContains({ ...current, actorId: "other-actor" }, frozen),
+  ).toBe(false);
+});

package/template/apps/server/src/data-access/scope-containment.ts

@@ -0,0 +1,48 @@
+import type {
+  AuthorizationScopeSnapshot,
+  PersistedScopeGrant,
+} from "@southwind-ai/shared";
+
+/** 当前 Actor scope 必须覆盖冻结 Run scope；不允许反向恢复更宽权限。 */
+export function authorizationScopeContains(
+  current: AuthorizationScopeSnapshot,
+  frozen: AuthorizationScopeSnapshot,
+): boolean {
+  return (
+    current.actorId === frozen.actorId &&
+    current.tenantId === frozen.tenantId &&
+    frozen.roleIds.every((roleId) => current.roleIds.includes(roleId)) &&
+    frozen.grants.every((required) =>
+      current.grants.some((grant) => grantContains(grant, required)),
+    )
+  );
+}
+
+function grantContains(
+  current: PersistedScopeGrant,
+  frozen: PersistedScopeGrant,
+): boolean {
+  if (current.scope === "all" || current.scope === "tenant") return true;
+  if (current.scope === "self") return frozen.scope === "self";
+  if (current.scope === "custom") {
+    return (
+      frozen.scope === "custom" &&
+      current.dimension === frozen.dimension &&
+      frozen.values.every((value) => current.values.includes(value))
+    );
+  }
+  if (current.scope === "department-and-children") {
+    return (
+      (frozen.scope === "department" ||
+        frozen.scope === "department-and-children") &&
+      Boolean(current.departmentId) &&
+      current.departmentId === frozen.departmentId
+    );
+  }
+  return (
+    current.scope === "department" &&
+    frozen.scope === "department" &&
+    Boolean(current.departmentId) &&
+    current.departmentId === frozen.departmentId
+  );
+}

package/template/apps/server/src/index.ts

@@ -14,15 +14,11 @@ import { createServerRuntime } from "./runtime.js";
 import { readPositiveInt } from "./runtime-config.js";
 // @windy-module system.scheduler end
 // @windy-module system.agent begin
-import { registerAgentPlatformRuntime } from "./agent/runtime-bootstrap.js";
 import { DeferredAgentBackgroundOperationPortFactory } from "./agent/background-operation-port.js";
-import {
-  projectAiScreenshotIntakeFactoryV1,
-  projectAiScreenshotPageRegistryV2,
-} from "./app/ai-screenshot-intake-binding.js";
-import { resolveCurrentSystemActor } from "./system/actor.js";
+import { composeApplicationAgentRuntime } from "./app/agent-runtime-composition.js";
+import { workflowDurableInput } from "./agent/workflow-durable-runtime-input.js";
 // @windy-module system.agent end
-import { createAuthRuntime } from "./auth/runtime.js";
+import { createComposedAuthRuntime } from "./auth/composition.js";
 // @windy-module system.license begin
 import { createLicenseRuntimeActivation } from "./license/activation.js";
 // @windy-module system.license end
@@ -31,6 +27,7 @@ import { registerSystemOperationRoutes } from "./system/operations.js";
 import { createPostgresMonitorProbe } from "./system/postgres-monitoring.js";
 // @windy-module system.operations end
 import { registerSystemRoutes } from "./system/routes.js";
+import { createAuthorizationInvalidationComposition } from "./system/authorization-invalidation-composition.js";
 // @windy-module system.scheduler begin
 import { registerSchedulerRoutes } from "./scheduler/routes.js";
 import { SchedulerWorker } from "./scheduler/worker.js";
@@ -85,10 +82,6 @@ const licenseActivation = createLicenseRuntimeActivation(
 // @windy-module system.license end
 const runtime = createServerRuntime(process.env, {
   actorResolver: persistence?.actorResolver,
-  // @windy-module system.agent begin
-  adkDebugActorResolver: (actorId) =>
-    resolveCurrentSystemActor(systemRepositories, actorId),
-  // @windy-module system.agent end
   // @windy-module system.license begin
   licenseResolver: licenseActivation.resolver,
   licenseEnforced: licenseActivation.enforced,
@@ -102,26 +95,27 @@ const runtime = createServerRuntime(process.env, {
   // @windy-module system.audit end
 });
 const observability = createHttpObservability(runtime, persistence, logger);
+const authorizationInvalidation = createAuthorizationInvalidationComposition({
+  platformConfig,
+  persistence,
+  repositories: systemRepositories,
+});
 // @windy-module system.license begin
 licenseActivation.runtime.setAuditSink(runtime.auditSink);
 // @windy-module system.license end
 const {
   authRepository,
   authService,
+  // @windy-module system.agent begin
+  bindClientAgentSessions,
+  // @windy-module system.agent end
   // @windy-module system.data-governance begin
   reauthentication,
   // @windy-module system.data-governance end
-} = createAuthRuntime({
-  repository: persistence?.authRepository,
-  sessionTtlSeconds: () => platformConfig.security.sessionTtlSeconds,
-  passwordPolicy: () => ({
-    minLength: platformConfig.security.passwordMinLength,
-    maxLength: platformConfig.security.passwordMaxLength,
-  }),
-  auditWriter: (event) => runtime.auditSink.recordCriticalEvent(event),
-  // @windy-module system.audit begin
-  auditReader: persistence?.auditReader,
-  // @windy-module system.audit end
+} = createComposedAuthRuntime({
+  platformConfig,
+  persistence,
+  runtime,
 });
 // @windy-module system.storage begin
 const { storageRuntime, reportStagingRuntime } = createStorageHostRuntime(
@@ -263,9 +257,13 @@ registerFoundationRoute(app, runtime, foundationSnapshot, systemRepositories);
 // @windy-module system.data-governance begin
 registerGovernedUserExportRoutes(app, governedExportService, runtime, features);
 // @windy-module system.data-governance end
-registerSystemRoutes(app, systemRepositories, runtime, features, {
-  authRepository: persistence?.authRepository,
-});
+registerSystemRoutes(
+  app,
+  systemRepositories,
+  runtime,
+  features,
+  authorizationInvalidation.systemRouteOptions,
+);
 // @windy-module system.operations begin
 registerSystemOperationRoutes(app, runtime, features, {
   redisHealthProbe: configurationRuntime.redisHealthProbe,
@@ -278,7 +276,7 @@ registerSystemOperationRoutes(app, runtime, features, {
 });
 // @windy-module system.operations end
 // @windy-module system.agent begin
-const agentRuntime = registerAgentPlatformRuntime({
+const agentRuntime = composeApplicationAgentRuntime({
   app,
   platformConfig,
   modules: foundationModules,
@@ -287,13 +285,13 @@ const agentRuntime = registerAgentPlatformRuntime({
   systemRepositories,
   storage: storageRuntime,
   workflow: workflowService,
+  ...workflowDurableInput([durableJobRuntime, storageRuntime, logger]),
   db: persistence?.db,
   backgroundAi: moduleBackgroundAi,
-  screenshotPageRegistry: platformConfig.enableAI
-    ? projectAiScreenshotPageRegistryV2
-    : undefined,
+  bindAuthorizationInvalidation: (target) =>
+    authorizationInvalidation.bind(target),
+  bindClientAgentSessions,
 });
-const { toolHandlers, aiArtifacts, aiOperations, aiReadiness } = agentRuntime;
 // @windy-module system.agent end
 // @windy-module system.scheduler begin
 registerSchedulerRoutes(app, scheduler, runtime, features);
@@ -314,12 +312,12 @@ installModuleHttpRuntime(moduleHosts, app, {
   // @windy-module system.storage end
   systemRepositories,
   // @windy-module system.agent begin
-  aiArtifacts,
-  aiOperations,
-  aiReadiness,
-  screenshots: platformConfig.enableAI
-    ? projectAiScreenshotIntakeFactoryV1
-    : undefined,
+  aiArtifacts: agentRuntime.aiArtifacts,
+  aiOperations: agentRuntime.aiOperations,
+  aiReadiness: agentRuntime.aiReadiness,
+  sessionMemory: agentRuntime.sessionMemory,
+  sourceInvalidation: agentRuntime.sourceInvalidation,
+  screenshots: agentRuntime.screenshots,
   // @windy-module system.agent end
   // @windy-module system.data-governance begin
   reauthenticate: (actorId, password) =>
@@ -334,7 +332,7 @@ finalizePlatformStartup({
   tasks: scheduledTaskDefinitions,
   // @windy-module system.scheduler end
   // @windy-module system.agent begin
-  tools: toolHandlers,
+  tools: agentRuntime.toolHandlers,
   disposeAgentRuntime: agentRuntime.disposeAgentRuntime,
   // @windy-module system.agent end
   // @windy-module system.search begin

package/template/apps/server/src/jobs/artifact-publication.test.ts

@@ -0,0 +1,192 @@
+import { describe, expect, test } from "bun:test";
+import {
+  DurableHandlerRegistry,
+  type DurableArtifactPublicationReceipt,
+} from "@southwind-ai/jobs";
+import { artifactRef } from "@southwind-ai/storage";
+import { DurableArtifactPublicationConflictError } from "./execution-repository.js";
+import { InMemoryDurableExecutionRepository } from "./in-memory-execution.js";
+import { DurableJobService } from "./service.js";
+import { DurableJobWorker } from "./worker.js";
+
+const base = new Date("2026-08-28T09:00:00.000Z");
+const artifact = {
+  kind: "workflow-result",
+  artifactRef: artifactRef("blob_0123456789abcdef0123456789abcdef"),
+  filename: "result.json",
+  contentType: "application/json",
+  byteSize: 12,
+  sha256: "a".repeat(64),
+  ownerId: "user_1",
+  metadata: { nested: { second: 2, first: 1 } },
+};
+
+describe("durable artifact stable publication", () => {
+  test("repository 对相同发布返回首发事实并拒绝内容漂移", async () => {
+    const repository = new InMemoryDurableExecutionRepository();
+    const service = new DurableJobService(repository, () => base);
+    const submitted = await service.submit(jobInput("repository-once"));
+    const claim = await repository.claim(claimInput("worker-repository"));
+    if (!claim) throw new Error("任务未领取");
+    const publication = {
+      id: "dap_stable",
+      jobId: claim.jobId,
+      stageId: claim.stageId,
+      ...artifact,
+    };
+
+    await expect(
+      repository.publishArtifactOnce(
+        claim,
+        { ...publication, jobId: "job_forged" },
+        base,
+      ),
+    ).rejects.toBeInstanceOf(DurableArtifactPublicationConflictError);
+    await expect(
+      repository.publishArtifactOnce(
+        claim,
+        { ...publication, stageId: "stage_forged" },
+        base,
+      ),
+    ).rejects.toBeInstanceOf(DurableArtifactPublicationConflictError);
+    expect((await service.get(submitted.job.id))?.artifacts).toEqual([]);
+
+    const first = await repository.publishArtifactOnce(
+      claim,
+      publication,
+      base,
+    );
+    const replay = await repository.publishArtifactOnce(
+      claim,
+      {
+        ...publication,
+        metadata: { nested: { first: 1, second: 2 } },
+      },
+      new Date(base.getTime() + 1),
+    );
+
+    expect(replay).toEqual(first);
+    await expect(
+      repository.publishArtifactOnce(
+        claim,
+        { ...publication, filename: "drifted.json" },
+        new Date(base.getTime() + 2),
+      ),
+    ).rejects.toBeInstanceOf(DurableArtifactPublicationConflictError);
+    await expect(
+      repository.publishArtifactOnce(
+        claim,
+        { ...publication, kind: "other-result" },
+        new Date(base.getTime() + 3),
+      ),
+    ).rejects.toBeInstanceOf(DurableArtifactPublicationConflictError);
+    expect((await service.get(submitted.job.id))?.artifacts).toEqual([
+      expect.objectContaining({
+        id: "dap_stable",
+        filename: "result.json",
+        createdAt: base.toISOString(),
+      }),
+    ]);
+  });
+
+  test("Worker 从稳定坐标生成同一 receipt", async () => {
+    const repository = new InMemoryDurableExecutionRepository();
+    const service = new DurableJobService(repository, () => base);
+    const submitted = await service.submit(jobInput("worker-once"));
+    const receipts: DurableArtifactPublicationReceipt[] = [];
+    const handlers = new DurableHandlerRegistry().register({
+      key: "test.handler",
+      payload: { parse: () => ({}) },
+      execute: async (_payload, context) => {
+        receipts.push(
+          await context.publishArtifactOnce!("page-agent-final", artifact),
+        );
+        receipts.push(
+          await context.publishArtifactOnce!("page-agent-final", artifact),
+        );
+      },
+    });
+    const worker = new DurableJobWorker(repository, handlers, {
+      now: () => base,
+    });
+
+    expect(await worker.runNext("default", "worker-a")).toMatchObject({
+      status: "succeeded",
+    });
+    expect(receipts).toHaveLength(2);
+    expect(receipts[1]).toEqual(receipts[0]);
+    expect(receipts[0]?.artifactId).toMatch(/^dap_[a-f0-9]{60}$/);
+    expect((await service.get(submitted.job.id))?.artifacts).toEqual([
+      expect.objectContaining({ id: receipts[0]?.artifactId }),
+    ]);
+  });
+
+  test("取消请求阻止一次性产物写入", async () => {
+    const repository = new InMemoryDurableExecutionRepository();
+    const service = new DurableJobService(repository, () => base);
+    const submitted = await service.submit(jobInput("repository-cancelled"));
+    const claim = await repository.claim(claimInput("worker-cancelled"));
+    if (!claim) throw new Error("取消任务未领取");
+    await repository.requestCancel(claim.jobId, base);
+
+    expect(
+      await repository.publishArtifactOnce(
+        claim,
+        {
+          id: "dap_cancelled",
+          jobId: claim.jobId,
+          stageId: claim.stageId,
+          ...artifact,
+        },
+        base,
+      ),
+    ).toMatchObject({ ok: true, cancelRequested: true });
+    expect((await service.get(submitted.job.id))?.artifacts).toEqual([]);
+  });
+
+  test("Worker 将同 publicationKey 的漂移固化为不可重试失败", async () => {
+    const repository = new InMemoryDurableExecutionRepository();
+    const service = new DurableJobService(repository, () => base);
+    const submitted = await service.submit(jobInput("worker-conflict"));
+    const handlers = new DurableHandlerRegistry().register({
+      key: "test.handler",
+      payload: { parse: () => ({}) },
+      execute: async (_payload, context) => {
+        await context.publishArtifactOnce!("page-agent-final", artifact);
+        await context.publishArtifactOnce!("page-agent-final", {
+          ...artifact,
+          sha256: "b".repeat(64),
+        });
+      },
+    });
+    const worker = new DurableJobWorker(repository, handlers, {
+      now: () => base,
+    });
+
+    expect(await worker.runNext("default", "worker-a")).toMatchObject({
+      status: "failed",
+    });
+    expect(await service.get(submitted.job.id)).toMatchObject({
+      artifacts: [{ sha256: "a".repeat(64) }],
+      failures: [
+        {
+          code: "ARTIFACT_PUBLICATION_CONFLICT",
+          retryable: false,
+        },
+      ],
+    });
+  });
+});
+
+function jobInput(idempotencyKey: string) {
+  return {
+    handlerKey: "test.handler",
+    idempotencyKey,
+    payload: {},
+    requestedBy: "user_1",
+  };
+}
+
+function claimInput(workerId: string) {
+  return { queue: "default", workerId, now: base, leaseDurationMs: 30_000 };
+}

package/template/apps/server/src/jobs/artifact-publication.ts

@@ -0,0 +1,56 @@
+import type {
+  DurableJobArtifact,
+  DurableLeaseIdentity,
+} from "@southwind-ai/jobs";
+import {
+  DurableArtifactPublicationConflictError,
+  type DurableArtifactPublication,
+} from "./execution-repository.js";
+
+export function assertArtifactPublicationIdentity(
+  identity: DurableLeaseIdentity,
+  candidate: DurableArtifactPublication,
+) {
+  if (
+    candidate.jobId !== identity.jobId ||
+    candidate.stageId !== identity.stageId
+  ) {
+    throw new DurableArtifactPublicationConflictError(
+      "产物发布身份与任务租约不匹配",
+    );
+  }
+}
+
+export function sameArtifactPublication(
+  persisted: DurableJobArtifact,
+  candidate: DurableArtifactPublication,
+): boolean {
+  return (
+    persisted.id === candidate.id &&
+    persisted.jobId === candidate.jobId &&
+    persisted.stageId === candidate.stageId &&
+    persisted.kind === candidate.kind &&
+    persisted.artifactRef === candidate.artifactRef &&
+    persisted.filename === candidate.filename &&
+    persisted.contentType === candidate.contentType &&
+    persisted.byteSize === candidate.byteSize &&
+    persisted.sha256 === candidate.sha256 &&
+    persisted.ownerId === candidate.ownerId &&
+    persisted.expiresAt === candidate.expiresAt &&
+    canonicalJson(persisted.metadata) === canonicalJson(candidate.metadata)
+  );
+}
+
+function canonicalJson(value: unknown): string | undefined {
+  return JSON.stringify(canonicalValue(value));
+}
+
+function canonicalValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalValue);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, entry]) => [key, canonicalValue(entry)]),
+  );
+}