@openprd/cli 0.1.19 → 0.1.22

package/src/dev-standards.js

@@ -87,6 +87,11 @@ const UI_FILE_EXTENSIONS = new Set([
 ]);
 const VISUAL_REVIEWS_DIR = cjoin('.openprd', 'harness', 'visual-reviews');
 const VISUAL_EVIDENCE_FRESH_MS = 24 * 60 * 60 * 1000;
+const I18N_CONFIG_PATH = cjoin('.openprd', 'i18n-config.json');
+const I18N_TEXT_FILE_EXTENSIONS = new Set([
+  '.html', '.jsx', '.swift', '.tsx', '.vue', '.wxml', '.svelte',
+  '.kt', '.java', '.dart', '.xml',
+]);
 
 function normalizePathForReport(value) {
   return String(value ?? '').split(path.sep).join('/');
@@ -461,12 +466,42 @@ async function buildVisualEvidenceReminder(projectRoot, files) {
     suggestedCommands: [
       'openprd visual-compare . --before <改前截图> --after <改后截图>',
       'openprd visual-compare . --board <alignment-board.json>（同构列表/卡片/网格/表格对齐，含容器轨道与内容槽位）',
+      '网格与基线只进入 alignment-board；普通结果画布不得自动叠加',
       'openprd visual-compare . --board <centering-board.json>（单素材内部居中/视觉重心）',
     ],
     chatEmbedHint: '生成后把证据图用 `![视觉证据](<输出路径>)` 直接嵌入最终回复，让用户在对话流里看到对齐效果。',
   };
 }
 
+async function buildI18nReminder(projectRoot, files) {
+  const textFiles = files
+    .filter((f) => f.status !== 'error' && I18N_TEXT_FILE_EXTENSIONS.has(path.extname(f.path).toLowerCase()))
+    .map((f) => f.path);
+  if (textFiles.length === 0) {
+    return { required: false, textFiles: [] };
+  }
+  const configPath = cjoin(projectRoot, I18N_CONFIG_PATH);
+  const config = await readJson(configPath).catch(() => null);
+  if (config && config.enforceOnDevCheck === false) {
+    return { required: false, textFiles, reason: 'i18n 检查已被用户关闭 (enforceOnDevCheck: false)。' };
+  }
+  const defaultLang = config?.defaultLanguage ?? 'zh-Hans';
+  const supported = Array.isArray(config?.supportedLanguages) ? config.supportedLanguages : ['zh-Hans', 'en'];
+  const platforms = Array.isArray(config?.platforms) ? config.platforms : [];
+  return {
+    required: true,
+    textFiles,
+    defaultLanguage: defaultLang,
+    supportedLanguages: supported,
+    platforms,
+    configExists: config !== null,
+    reason: config
+      ? `本轮触达 ${textFiles.length} 个可能包含用户文案的文件；请检查新增/修改的文案是否已使用 i18n 框架，基准语言 ${defaultLang}，需支持 ${supported.join(', ')}。`
+      : `本轮触达 ${textFiles.length} 个可能包含用户文案的文件，但项目尚未配置 .openprd/i18n-config.json。如需启用多语言检查，可运行 openprd i18n-init . 或手动创建配置文件。`,
+    guideline: 'docs/basic/i18n-guidelines.md',
+  };
+}
+
 async function analyzeDevelopmentFile(projectRoot, targetPath, lineConfig) {
   const absolutePath = path.isAbsolute(targetPath)
     ? path.resolve(targetPath)
@@ -621,6 +656,7 @@ export async function checkDevelopmentStandardsWorkspace(projectRoot, options =
     files,
     wrapUp: buildDevCheckWrapUp(files, lineConfig),
     visualEvidence: await buildVisualEvidenceReminder(projectRoot, files),
+    i18nReminder: await buildI18nReminder(projectRoot, files),
     knowledgeReview,
     errors,
   };
@@ -658,3 +694,24 @@ export async function setDevCheckAutoRefactor(projectRoot, enabled) {
     },
   };
 }
+
+export async function initI18nConfig(projectRoot, options = {}) {
+  const configPath = cjoin(projectRoot, I18N_CONFIG_PATH);
+  const existing = await readJson(configPath).catch(() => null);
+  if (existing) {
+    return { created: false, configPath: normalizePathForReport(I18N_CONFIG_PATH), config: existing };
+  }
+  const defaultLang = options.defaultLanguage ?? 'zh-Hans';
+  const config = {
+    version: 1,
+    defaultLanguage: defaultLang,
+    supportedLanguages: [defaultLang, ...(defaultLang === 'en' ? ['zh-Hans'] : ['en'])],
+    enforceOnDevCheck: true,
+    platforms: [],
+    translationStrategy: 'key-value-file',
+    notes: '用户可随时修改此文件来调整默认语言、支持语种和检查策略',
+  };
+  await fs.mkdir(path.dirname(configPath), { recursive: true });
+  await fs.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+  return { created: true, configPath: normalizePathForReport(I18N_CONFIG_PATH), config };
+}

package/src/fleet.js

@@ -1,9 +1,12 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { cjoin, exists, writeJson } from './fs-utils.js';
+import { cjoin, exists } from './fs-utils.js';
+import { atomicWriteJson } from './kernel/index.js';
 import { hasLegacyOpenPrdArtifacts } from './openspec/migration.js';
 import { SOURCE_INVENTORY_IGNORE_DIRS } from './source-inventory.js';
 import { timestamp } from './time.js';
+import { createFleetTransactionContext, executeFleetProjectTransaction, planFleetProjectTransaction } from './upgrade/fleet-transaction.js';
+import { applySuccessfulFleetMutation, runStagedFleetMutation } from './upgrade/fleet-mutation.js';
 import { readWorkspaceRegistry, upsertWorkspaceRegistryEntry } from './workspace-registry.js';
 
 const FLEET_DEFAULT_MAX_DEPTH = 4;
@@ -35,6 +38,7 @@ const FLEET_PROJECT_MARKERS = [
 ];
 const FLEET_AGENT_MARKERS = ['.codex', '.claude', '.cursor', 'AGENTS.md', 'CLAUDE.md'];
 const FLEET_LEGACY_OPENPRD_MARKER = 'openprd-legacy-artifacts';
+const FLEET_TRANSACTIONAL_ACTIONS = new Set(['update', 'setup', 'backfill-work-units']);
 
 function normalizeCsvList(value) {
   if (!value) {
@@ -110,7 +114,7 @@ async function detectFleetMarkers(projectPath) {
   const entries = await fs.readdir(projectPath, { withFileTypes: true }).catch(() => []);
   const names = new Set(entries.map((entry) => entry.name));
   const markers = FLEET_PROJECT_MARKERS.filter((marker) => names.has(marker));
-  if (!markers.includes('.openprd') && await hasLegacyOpenPrdArtifacts(projectPath)) {
+  if (await hasLegacyOpenPrdArtifacts(projectPath)) {
     markers.push(FLEET_LEGACY_OPENPRD_MARKER);
   }
   return markers;
@@ -121,6 +125,10 @@ async function scanFleetProjects(rootPath, options = {}) {
   const maxDepth = parsePositiveInteger(options.maxDepth, FLEET_DEFAULT_MAX_DEPTH);
   const include = normalizeCsvList(options.include);
   const exclude = normalizeCsvList(options.exclude);
+  const infrastructureRoots = [options.openprdHome, options.backupRoot]
+    .filter(Boolean)
+    .map((candidate) => path.resolve(candidate))
+    .filter((candidate) => pathWithinRoot(root, candidate));
   const projects = [];
   const seenRealPaths = new Set();
 
@@ -128,6 +136,9 @@ async function scanFleetProjects(rootPath, options = {}) {
     if (depth > maxDepth) {
       return;
     }
+    if (currentPath !== root && infrastructureRoots.some((candidate) => pathWithinRoot(candidate, currentPath))) {
+      return;
+    }
 
     const name = path.basename(currentPath);
     if (depth > 0 && FLEET_IGNORE_DIRS.has(name)) {
@@ -141,6 +152,7 @@ async function scanFleetProjects(rootPath, options = {}) {
     seenRealPaths.add(realPath);
 
     const markers = await detectFleetMarkers(currentPath);
+    const containsLegacyArtifactTree = markers.includes(FLEET_LEGACY_OPENPRD_MARKER);
     if (markers.length > 0) {
       const category = classifyFleetMarkers(markers);
       const included = projectPathMatches(root, currentPath, include);
@@ -171,6 +183,11 @@ async function scanFleetProjects(rootPath, options = {}) {
       if (FLEET_IGNORE_DIRS.has(entry.name)) {
         continue;
       }
+      // A legacy `openprd/changes` tree belongs to the project just discovered
+      // above. It is migration input, never another fleet project root.
+      if (containsLegacyArtifactTree && entry.name === 'openprd') {
+        continue;
+      }
       await walk(cjoin(currentPath, entry.name), depth + 1);
     }
   }
@@ -298,32 +315,18 @@ function summarizeFleetProjects(projects) {
   return summary;
 }
 
-async function collectFleetProjectHealth(projectPath, options, doctorWorkspace) {
-  if (!doctorWorkspace) {
-    return { ok: true, errors: [] };
-  }
-  try {
-    // Batch refresh should focus on generated guidance and workspace skeleton health.
-    // Legacy content-doc debt remains available in direct doctor/standards checks.
-    const doctor = await doctorWorkspace(projectPath, {
-      tools: options.tools ?? 'all',
-      hookProfile: options.hookProfile,
-      enableUserCodexConfig: Boolean(options.enableUserCodexConfig),
-      codexHome: options.codexHome,
-      openprdHome: options.openprdHome,
-      docsContent: false,
-      sourceManuals: false,
-    });
-    return {
-      ok: doctor.ok,
-      errors: doctor.errors ?? [],
-    };
-  } catch (error) {
-    return {
-      ok: false,
-      errors: [error instanceof Error ? error.message : String(error)],
-    };
-  }
+function attachFleetTransactionReport(item, plan, context) {
+  item.transaction = {
+    id: plan.transactionId,
+    reportVersion: plan.version,
+    strategy: context.applyStrategy,
+  };
+  item.version = { ...plan.versions };
+  item.checksum = { ...plan.checksum };
+  item.backup = { ...plan.backup };
+  item.migration = plan.migration;
+  item.rollback = { ...plan.rollback };
+  item.refusal = [...plan.refusal];
 }
 
 function buildFleetRegistrySummary(rootPath, options, registry) {
@@ -350,12 +353,7 @@ function buildFleetRegistrySummary(rootPath, options, registry) {
 }
 
 async function fleetWorkspaceImpl(rootPath, options = {}, dependencies = {}) {
-  const {
-    doctorWorkspace,
-    backfillWorkUnitsWorkspace,
-    setupAgentIntegrationWorkspace,
-    updateAgentIntegrationWorkspace,
-  } = dependencies;
+  const { doctorWorkspace, backfillWorkUnitsWorkspace } = dependencies;
   const root = path.resolve(rootPath);
   if (!(await exists(root))) {
     throw new Error(`Fleet root does not exist: ${root}`);
@@ -374,6 +372,11 @@ async function fleetWorkspaceImpl(rootPath, options = {}, dependencies = {}) {
   const scanned = await scanFleetProjects(root, options);
   const mergedProjects = await mergeFleetProjects(scanned, registryScope.projects);
   const projects = [];
+  const transactionContext = await createFleetTransactionContext({
+    openprdHome: options.openprdHome,
+    backupRoot: options.backupRoot,
+    targetVersion: options.targetVersion,
+  });
 
   for (const project of mergedProjects) {
     const plannedAction = plannedFleetAction(project.category, options);
@@ -393,6 +396,27 @@ async function fleetWorkspaceImpl(rootPath, options = {}, dependencies = {}) {
       continue;
     }
 
+    let transactionPlan = null;
+    if (FLEET_TRANSACTIONAL_ACTIONS.has(plannedAction)) {
+      try {
+        transactionPlan = await planFleetProjectTransaction({ ...project, plannedAction }, transactionContext, { dryRun });
+        attachFleetTransactionReport(item, transactionPlan, transactionContext);
+      } catch (error) {
+        item.status = 'failed';
+        item.ok = false;
+        item.errors = [error instanceof Error ? error.message : String(error)];
+        projects.push(item);
+        continue;
+      }
+      if (!transactionPlan.eligible) {
+        item.status = 'failed';
+        item.ok = false;
+        item.errors = transactionPlan.refusal.map((refusal) => refusal.message);
+        projects.push(item);
+        continue;
+      }
+    }
+
     if (dryRun) {
       if (plannedAction === 'backfill-work-units' && backfillWorkUnitsWorkspace) {
         const backfill = await backfillWorkUnitsWorkspace(project.path, { dryRun: true });
@@ -408,54 +432,49 @@ async function fleetWorkspaceImpl(rootPath, options = {}, dependencies = {}) {
       continue;
     }
 
+    if (transactionPlan) {
+      const transaction = await executeFleetProjectTransaction(transactionPlan, {
+        openprdHome: options.openprdHome,
+        beforeApply: dependencies.beforeFleetApply,
+        mutate: (stagingRoot, staging) => runStagedFleetMutation(
+          plannedAction,
+          stagingRoot,
+          options,
+          dependencies,
+          staging,
+        ),
+        afterApply: plannedAction === 'update' || plannedAction === 'setup'
+          ? async () => ({
+            registry: await upsertWorkspaceRegistryEntry(project.path, {
+              openprdHome: options.openprdHome,
+              action: plannedAction === 'update' ? 'fleet-update' : 'fleet-setup',
+            }),
+          })
+          : null,
+      });
+      attachFleetTransactionReport(item, transaction.plan, transactionContext);
+      if (!transaction.ok) {
+        item.status = 'failed';
+        item.ok = false;
+        item.errors = Array.from(new Set([
+          ...(transaction.mutationResult?.errors ?? []),
+          transaction.error instanceof Error ? transaction.error.message : String(transaction.error),
+        ].filter(Boolean)));
+        projects.push(item);
+        continue;
+      }
+      item.ok = true;
+      applySuccessfulFleetMutation(item, plannedAction, transaction);
+      item.errors = [
+        ...(transaction.mutationResult?.actionResult?.doctor?.errors ?? []),
+        ...(transaction.mutationResult?.backfill?.errors ?? []),
+      ];
+      projects.push(item);
+      continue;
+    }
+
     try {
-      if (plannedAction === 'update') {
-        const update = await updateAgentIntegrationWorkspace(project.path, {
-          tools: options.tools ?? 'all',
-          hookProfile: options.hookProfile,
-          force: Boolean(options.force),
-          enableUserCodexConfig: Boolean(options.enableUserCodexConfig),
-          codexHome: options.codexHome,
-          openprdHome: options.openprdHome,
-        });
-        const backfill = backfillWorkUnitsWorkspace
-          ? await backfillWorkUnitsWorkspace(project.path, {})
-          : { ok: true, changes: [], errors: [], totalVersions: 0, changedVersions: 0 };
-        const health = await collectFleetProjectHealth(project.path, options, doctorWorkspace);
-        item.status = update.ok && backfill.ok ? 'updated' : 'failed';
-        item.ok = update.ok && backfill.ok;
-        item.registry = update.registry ?? null;
-        item.changes = [
-          ...(update.migration?.changes ?? []).map((change) => ({ ...change, source: 'workspace' })),
-          ...(update.changes ?? []).map((change) => ({ ...change, source: 'agent' })),
-          ...(backfill.changes ?? []).map((change) => ({ ...change, source: 'work-unit' })),
-        ];
-        item.doctorOk = health.ok;
-        item.healthOk = health.ok;
-        item.healthErrors = health.errors;
-        item.workUnits = {
-          totalVersions: backfill.totalVersions,
-          changedVersions: backfill.changedVersions,
-        };
-        item.errors = [...(update.doctor?.errors ?? []), ...(backfill.errors ?? [])];
-      } else if (plannedAction === 'setup') {
-        const setup = await setupAgentIntegrationWorkspace(project.path, {
-          tools: options.tools ?? 'all',
-          hookProfile: options.hookProfile,
-          force: Boolean(options.force),
-          enableUserCodexConfig: Boolean(options.enableUserCodexConfig),
-          codexHome: options.codexHome,
-          openprdHome: options.openprdHome,
-        });
-        item.status = setup.ok ? 'setup' : 'failed';
-        item.ok = setup.ok;
-        item.registry = setup.registry ?? null;
-        item.changes = [
-          ...(setup.migration?.changes ?? []).map((change) => ({ ...change, source: 'workspace' })),
-          ...(setup.changes ?? []).map((change) => ({ ...change, source: 'agent' })),
-        ];
-        item.errors = setup.doctor?.errors ?? [];
-      } else if (plannedAction === 'doctor') {
+      if (plannedAction === 'doctor') {
         const doctor = await doctorWorkspace(project.path, {
           tools: options.tools ?? 'all',
           hookProfile: options.hookProfile,
@@ -467,19 +486,6 @@ async function fleetWorkspaceImpl(rootPath, options = {}, dependencies = {}) {
         item.ok = doctor.ok;
         item.doctorOk = doctor.ok;
         item.errors = doctor.errors ?? [];
-      } else if (plannedAction === 'backfill-work-units') {
-        if (!backfillWorkUnitsWorkspace) {
-          throw new Error('Missing fleet dependency: backfillWorkUnitsWorkspace');
-        }
-        const backfill = await backfillWorkUnitsWorkspace(project.path, {});
-        item.status = backfill.ok ? (backfill.totalVersions > 0 ? 'backfilled' : 'skipped') : 'failed';
-        item.ok = backfill.ok;
-        item.workUnits = {
-          totalVersions: backfill.totalVersions,
-          changedVersions: backfill.changedVersions,
-        };
-        item.changes = (backfill.changes ?? []).map((change) => ({ ...change, source: 'work-unit' }));
-        item.errors = backfill.errors ?? [];
       } else if (plannedAction === 'sync-registry') {
         const registrySync = await upsertWorkspaceRegistryEntry(project.path, {
           openprdHome: options.openprdHome,
@@ -515,6 +521,17 @@ async function fleetWorkspaceImpl(rootPath, options = {}, dependencies = {}) {
       backfillWorkUnits: Boolean(options.backfillWorkUnits),
       syncRegistry: Boolean(options.syncRegistry),
     },
+    upgrade: {
+      reportVersion: transactionContext.version,
+      transactionId: transactionContext.transactionId,
+      targetVersion: transactionContext.targetVersion,
+      checksumAlgorithm: transactionContext.checksumAlgorithm,
+      applyStrategy: transactionContext.applyStrategy,
+      backupRoot: transactionContext.backupRoot,
+      archivePolicy: 'refuse-write',
+      symlinkPolicy: 'refuse-write',
+      compatibilityPolicy: 'refuse-too-new',
+    },
     scannedAt: timestamp(),
     summary: summarizeFleetProjects(projects),
     registry: registrySummary,
@@ -525,8 +542,8 @@ async function fleetWorkspaceImpl(rootPath, options = {}, dependencies = {}) {
 
   if (options.report) {
     const reportPath = path.resolve(options.report);
-    await writeJson(reportPath, result);
     result.reportPath = reportPath;
+    await atomicWriteJson(reportPath, result);
   }
 
   return result;

package/src/gates/index.js

@@ -0,0 +1,2 @@
+export * from './scoped-gates.js';
+export * from './store.js';

package/src/gates/scoped-gates.js

@@ -0,0 +1,256 @@
+/*
+ * 核心功能
+ * 定义 project/change/work-unit/task/lane/operation 分级门禁，并把证据与明确 approval ID
+ * 绑定到同一作用域和操作，避免一句泛化确认越权放行其他任务。
+ *
+ * 输入
+ * 接收 Gate 定义、Evidence 记录、Approval 记录、待执行操作摘要与可注入时钟。
+ *
+ * 输出
+ * 返回稳定、可审计的门禁决策；不执行写入，也不把评估行为混入项目事实。
+ *
+ * 定位
+ * 位于控制平面的纯策略层，可由 CLI、Hook、任务运行时和升级器共同复用。
+ *
+ * 维护规则
+ * 新增 scope 或决策码时必须保持旧码含义不变，并补跨作用域、过期和撤销负向测试。
+ */
+
+import { createHash } from 'node:crypto';
+import { canonicalJson } from '../kernel/event-envelope.js';
+
+const GATE_SCHEMA_VERSION = 1;
+const SCOPE_TYPES = Object.freeze(['project', 'change', 'work-unit', 'task', 'lane', 'operation']);
+const EVIDENCE_STATUSES = Object.freeze(['valid', 'revoked', 'superseded']);
+const APPROVAL_STATUSES = Object.freeze(['active', 'revoked', 'consumed']);
+
+class ScopedGateValidationError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = 'ScopedGateValidationError';
+    this.code = 'OPENPRD_SCOPED_GATE_INVALID';
+    Object.assign(this, details);
+  }
+}
+
+function stableId(prefix, value) {
+  return `${prefix}_${createHash('sha256').update(canonicalJson(value)).digest('hex').slice(0, 24)}`;
+}
+
+function requiredString(value, label) {
+  const normalized = String(value ?? '').trim();
+  if (!normalized || /[\0\r\n]/.test(normalized)) {
+    throw new ScopedGateValidationError(`${label} 必须是安全的非空字符串。`, { field: label });
+  }
+  return normalized;
+}
+
+function normalizeTime(value, label) {
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    throw new ScopedGateValidationError(`${label} 必须是有效时间。`, { field: label });
+  }
+  return date.toISOString();
+}
+
+function normalizeScope(scope) {
+  const type = requiredString(scope?.type, 'scope.type');
+  if (!SCOPE_TYPES.includes(type)) {
+    throw new ScopedGateValidationError(`不支持的门禁作用域：${type}。`, { field: 'scope.type', type });
+  }
+  return { type, id: requiredString(scope?.id, 'scope.id') };
+}
+
+function sameScope(left, right) {
+  return left?.type === right?.type && left?.id === right?.id;
+}
+
+function createGateDefinition(input) {
+  const scope = normalizeScope(input?.scope);
+  const operation = requiredString(input?.operation, 'operation');
+  const requiredEvidence = (input?.requiredEvidence ?? []).map((requirement, index) => ({
+    kind: requiredString(requirement?.kind, `requiredEvidence[${index}].kind`),
+    minCount: Math.max(1, Number(requirement?.minCount ?? 1)),
+    maxAgeMs: requirement?.maxAgeMs === null || requirement?.maxAgeMs === undefined
+      ? null
+      : Math.max(0, Number(requirement.maxAgeMs)),
+  }));
+  for (const requirement of requiredEvidence) {
+    if (!Number.isSafeInteger(requirement.minCount)) {
+      throw new ScopedGateValidationError('requiredEvidence.minCount 必须是正整数。');
+    }
+    if (requirement.maxAgeMs !== null && !Number.isFinite(requirement.maxAgeMs)) {
+      throw new ScopedGateValidationError('requiredEvidence.maxAgeMs 必须是非负数或 null。');
+    }
+  }
+  const approval = {
+    required: Boolean(input?.approval?.required),
+    subjectDigest: input?.approval?.subjectDigest
+      ? requiredString(input.approval.subjectDigest, 'approval.subjectDigest')
+      : null,
+    consumeOnPass: Boolean(input?.approval?.consumeOnPass),
+  };
+  const body = {
+    schemaVersion: GATE_SCHEMA_VERSION,
+    gateId: input?.gateId ?? null,
+    scope,
+    operation,
+    risk: input?.risk ?? 'normal',
+    requiredEvidence,
+    approval,
+    metadata: structuredClone(input?.metadata ?? {}),
+  };
+  body.gateId = body.gateId
+    ? requiredString(body.gateId, 'gateId')
+    : stableId('gate', { ...body, gateId: null });
+  return body;
+}
+
+function createEvidenceRecord(input, options = {}) {
+  const collectedAt = normalizeTime(input?.collectedAt ?? (options.clock?.() ?? new Date()), 'collectedAt');
+  const scope = normalizeScope(input?.scope);
+  const kind = requiredString(input?.kind, 'kind');
+  const contentDigest = requiredString(input?.contentDigest, 'contentDigest');
+  const status = input?.status ?? 'valid';
+  if (!EVIDENCE_STATUSES.includes(status)) {
+    throw new ScopedGateValidationError(`不支持的证据状态：${status}。`);
+  }
+  const body = {
+    schemaVersion: GATE_SCHEMA_VERSION,
+    evidenceId: input?.evidenceId ?? null,
+    scope,
+    operation: input?.operation ? requiredString(input.operation, 'operation') : null,
+    kind,
+    source: requiredString(input?.source ?? 'unknown', 'source'),
+    contentDigest,
+    collectedAt,
+    validUntil: input?.validUntil ? normalizeTime(input.validUntil, 'validUntil') : null,
+    status,
+    metadata: structuredClone(input?.metadata ?? {}),
+  };
+  body.evidenceId = body.evidenceId
+    ? requiredString(body.evidenceId, 'evidenceId')
+    : stableId('evidence', { ...body, evidenceId: null });
+  return body;
+}
+
+function createApprovalRecord(input, options = {}) {
+  const approvalId = requiredString(input?.approvalId, 'approvalId');
+  const issuedAt = normalizeTime(input?.issuedAt ?? (options.clock?.() ?? new Date()), 'issuedAt');
+  const status = input?.status ?? 'active';
+  if (!APPROVAL_STATUSES.includes(status)) {
+    throw new ScopedGateValidationError(`不支持的审批状态：${status}。`);
+  }
+  return {
+    schemaVersion: GATE_SCHEMA_VERSION,
+    approvalId,
+    scope: normalizeScope(input?.scope),
+    operation: requiredString(input?.operation, 'operation'),
+    subjectDigest: input?.subjectDigest ? requiredString(input.subjectDigest, 'subjectDigest') : null,
+    actor: {
+      type: requiredString(input?.actor?.type ?? 'user', 'actor.type'),
+      id: input?.actor?.id ? requiredString(input.actor.id, 'actor.id') : null,
+    },
+    issuedAt,
+    expiresAt: input?.expiresAt ? normalizeTime(input.expiresAt, 'expiresAt') : null,
+    status,
+    metadata: structuredClone(input?.metadata ?? {}),
+  };
+}
+
+function evidenceUsability(record, gate, now) {
+  if (record?.schemaVersion !== GATE_SCHEMA_VERSION) return { ok: false, code: 'evidence-schema-mismatch' };
+  if (!sameScope(record.scope, gate.scope)) return { ok: false, code: 'evidence-scope-mismatch' };
+  if (record.operation && record.operation !== gate.operation) return { ok: false, code: 'evidence-operation-mismatch' };
+  if (record.status !== 'valid') return { ok: false, code: `evidence-${record.status ?? 'invalid'}` };
+  const collectedAt = Date.parse(record.collectedAt);
+  if (Number.isNaN(collectedAt)) return { ok: false, code: 'evidence-time-invalid' };
+  if (record.validUntil && Date.parse(record.validUntil) <= now.getTime()) return { ok: false, code: 'evidence-expired' };
+  return { ok: true, collectedAt };
+}
+
+function approvalUsability(record, gate, approvalId, now) {
+  if (!approvalId) return { ok: false, code: 'approval-id-required' };
+  if (!record || record.approvalId !== approvalId) return { ok: false, code: 'approval-id-not-found' };
+  if (record.schemaVersion !== GATE_SCHEMA_VERSION) return { ok: false, code: 'approval-schema-mismatch' };
+  if (!sameScope(record.scope, gate.scope)) return { ok: false, code: 'approval-scope-mismatch' };
+  if (record.operation !== gate.operation) return { ok: false, code: 'approval-operation-mismatch' };
+  if (record.status !== 'active') return { ok: false, code: `approval-${record.status ?? 'invalid'}` };
+  if (record.expiresAt && Date.parse(record.expiresAt) <= now.getTime()) return { ok: false, code: 'approval-expired' };
+  if (gate.approval.subjectDigest && record.subjectDigest !== gate.approval.subjectDigest) {
+    return { ok: false, code: 'approval-subject-mismatch' };
+  }
+  return { ok: true };
+}
+
+function evaluateScopedGate(input, options = {}) {
+  const gate = createGateDefinition(input?.gate);
+  const now = options.clock?.() ?? new Date();
+  const nowDate = now instanceof Date ? now : new Date(now);
+  if (Number.isNaN(nowDate.getTime())) throw new ScopedGateValidationError('clock 返回了无效时间。');
+  const reasons = [];
+  const acceptedEvidence = [];
+  const rejectedEvidence = [];
+
+  for (const evidence of input?.evidence ?? []) {
+    const usability = evidenceUsability(evidence, gate, nowDate);
+    if (usability.ok) acceptedEvidence.push({ record: evidence, collectedAt: usability.collectedAt });
+    else rejectedEvidence.push({ evidenceId: evidence?.evidenceId ?? null, code: usability.code });
+  }
+
+  for (const requirement of gate.requiredEvidence) {
+    const matches = acceptedEvidence.filter(({ record, collectedAt }) => (
+      record.kind === requirement.kind
+      && (requirement.maxAgeMs === null || nowDate.getTime() - collectedAt <= requirement.maxAgeMs)
+    ));
+    if (matches.length < requirement.minCount) {
+      reasons.push({
+        code: 'evidence-required',
+        kind: requirement.kind,
+        required: requirement.minCount,
+        found: matches.length,
+      });
+    }
+  }
+
+  let approval = null;
+  if (gate.approval.required) {
+    approval = (input?.approvals ?? []).find((record) => record?.approvalId === input?.approvalId) ?? null;
+    const usability = approvalUsability(approval, gate, input?.approvalId, nowDate);
+    if (!usability.ok) reasons.push({ code: usability.code, approvalId: input?.approvalId ?? null });
+  }
+
+  const evaluatedAt = nowDate.toISOString();
+  const result = {
+    schemaVersion: GATE_SCHEMA_VERSION,
+    gateId: gate.gateId,
+    scope: gate.scope,
+    operation: gate.operation,
+    status: reasons.length === 0 ? 'pass' : 'blocked',
+    evaluatedAt,
+    approvalId: approval?.approvalId ?? null,
+    approvalConsumption: reasons.length === 0 && gate.approval.consumeOnPass && approval
+      ? { approvalId: approval.approvalId, nextStatus: 'consumed' }
+      : null,
+    acceptedEvidenceIds: acceptedEvidence.map(({ record }) => record.evidenceId).sort(),
+    rejectedEvidence,
+    reasons,
+  };
+  return {
+    ...result,
+    decisionId: stableId('decision', result),
+  };
+}
+
+export {
+  APPROVAL_STATUSES,
+  EVIDENCE_STATUSES,
+  GATE_SCHEMA_VERSION,
+  SCOPE_TYPES,
+  ScopedGateValidationError,
+  createApprovalRecord,
+  createEvidenceRecord,
+  createGateDefinition,
+  evaluateScopedGate,
+  normalizeScope,
+};