openxiangda 1.0.176 → 1.0.178

package/lib/cli.js

@@ -82,6 +82,10 @@ const {
   writeContentCache,
 } = require('./content-cache');
 const { explainReleaseExecution } = require('./release-explain');
+const {
+  classifyReleaseExecutionFailure,
+  isDefinitelyPreWriteReleaseError,
+} = require('./release-error-classification');
 const { buildTaskStatus, findAppReleaseId } = require('./task-status');
 const {
   checkEngineeringPolicyMarkers,
@@ -94,6 +98,10 @@ const {
   getImpactedResourceTargets,
   validateManifestSourceBindings,
 } = require('./source-dependencies');
+const {
+  collectFormSnapshotFieldIds,
+  validateFormFieldContracts,
+} = require('./form-field-contract');
 const { getSkillStatusReport, installSkills } = require('./skills');
 const {
   assertOrClaimWorktreeOwner,
@@ -170,13 +178,32 @@ let readOnlyHttpGuardDepth = 0;
 let readOnlyHttpGuardLabel = null;
 let activePublishRequestContext = null;
 let activePublishLeaseHeartbeat = null;
+let activeCommandScopedPublishLease = null;
 const genericGitBasePlanCache = new Map();
 
 async function main(argv) {
+  let commandError = null;
   try {
     return await mainImpl(argv);
+  } catch (error) {
+    commandError = error;
+    throw error;
   } finally {
     await stopActivePublishLeaseHeartbeat();
+    try {
+      await finalizeCommandScopedPublishLease({
+        succeeded: commandError === null,
+      });
+    } catch (cleanupError) {
+      if (!commandError) throw cleanupError;
+      commandError.publishLeaseCleanupError = {
+        code: cleanupError?.code || 'PUBLISH_LEASE_CLEANUP_FAILED',
+        message: maskText(cleanupError?.message || String(cleanupError)),
+      };
+      warn(
+        `发布命令失败后的租约清理也未完成：${commandError.publishLeaseCleanupError.message}`
+      );
+    }
     activePublishRequestContext = null;
   }
 }
@@ -686,7 +713,7 @@ async function sdd(args) {
       '  openxiangda sdd quick tune-customer-copy --kind copy --pages customer_list --files src/pages/customer_list/index.tsx --summary "用户确认小范围文案调整"',
       '  openxiangda sdd approve add-customer-list --summary "用户确认设计"',
       '  openxiangda sdd ready add-customer-list',
-      '  openxiangda sdd bundle mainline-release --changes add-customer-list,fix-order-log',
+      '  openxiangda sdd bundle mainline-release --changes add-customer-list,fix-order-log [--source-base-ref <commit>]',
       '  openxiangda sdd context --change add-customer-list --json',
       '  openxiangda sdd verify --change add-customer-list --stage prepublish --json',
       '  openxiangda sdd render add-customer-list  # 仅在确实需要完整文档时',
@@ -701,6 +728,7 @@ async function sdd(args) {
       '  - verify stage 可选 implementation、prepublish、postpublish、archive；不传保持旧版全量校验。',
       '  - 默认 streamlined 校验只把 approval、精确资源/文件范围、实际发布命令作为硬门禁；任务、证据和规格文案仅告警。配置 strictDocumentation: true 可恢复严格文档门禁。',
       '  - bundle 聚合多个 approved change；提交并推送该 bundle 后，在权威主分支执行一次 staged + atomic 发布。',
+      '  - bundle 默认保留来源 change 创建时的共同 Git 基线；仅迁移旧 change 缺少 sourceBase 时使用 --source-base-ref 显式补充。',
       '  - 新 release 只能从已推送且与权威远端默认主分支一致的 clean HEAD 开始。',
     ].join('\n'));
     return;
@@ -781,6 +809,7 @@ async function sdd(args) {
       changes: flags.changes,
       integration,
       profile: flags.profile,
+      sourceBaseRef: flags['source-base-ref'],
       force: Boolean(flags.force),
     });
     if (flags.json) return writeJson(result);
@@ -805,6 +834,7 @@ async function sdd(args) {
       changeId,
       targets: scope.targets,
       changedFiles: scope.changedFiles,
+      sourceBase: scope.change?.sourceBase,
     });
     const ownerStatus = getWorktreeOwnerStatus({ cwd: process.cwd() });
     if (
@@ -1005,6 +1035,10 @@ function releaseExecutionFile(changeId) {
   return path.join(releaseExecutionDir(changeId), 'execution.json');
 }
 
+function directPublishReceiptFile(changeId) {
+  return path.join(releaseExecutionDir(changeId), 'direct-publish.json');
+}
+
 function writePrivateJsonAtomic(file, value) {
   fs.mkdirSync(path.dirname(file), { recursive: true });
   const tempFile = `${file}.${process.pid}.${Date.now()}.tmp`;
@@ -1026,6 +1060,39 @@ function readReleaseExecution(changeId) {
   }
 }
 
+function readDirectPublishReceipt(changeId) {
+  const file = directPublishReceiptFile(changeId);
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (error) {
+    fail(
+      `DIRECT_PUBLISH_RECEIPT_INVALID: ${path.relative(process.cwd(), file)} 无法读取: ${error.message}`
+    );
+  }
+}
+
+function writeDirectPublishReceipt(changeId, input = {}) {
+  if (!changeId) return null;
+  const receipt = {
+    schemaVersion: 'openxiangda_direct_publish_receipt_v1',
+    changeId,
+    status: 'completed',
+    command: input.command || null,
+    writeAttempted: Boolean(input.writeAttempted),
+    selectors: unique(input.selectors || []).sort(),
+    sourceRevision: input.sourceRevision || null,
+    result: input.result || null,
+    completedAt: new Date().toISOString(),
+  };
+  const file = directPublishReceiptFile(changeId);
+  writePrivateJsonAtomic(file, receipt);
+  return {
+    file: path.relative(process.cwd(), file).replace(/\\/g, '/'),
+    receipt,
+  };
+}
+
 function summarizeReleaseStepResult(result) {
   const value =
     result && typeof result === 'object' && !Array.isArray(result)
@@ -1082,30 +1149,6 @@ function releaseExecutionContextFromBegin(result, target, changeId) {
   };
 }
 
-function isDefinitelyPreWriteReleaseError(error) {
-  const code = String(error?.code || '');
-  if (new Set([
-    'RELEASE_PUBLISH_REVISION_CHANGED',
-    'RELEASE_SOURCE_DIRTY',
-    'RELEASE_SOURCE_BRANCH_REQUIRED',
-    'RELEASE_SOURCE_MAINLINE_REQUIRED',
-    'RELEASE_SOURCE_MAINLINE_NOT_PUSHED',
-    'RELEASE_SOURCE_BEHIND_MAIN',
-    'RELEASE_GIT_AUTH_REQUIRED',
-    'RELEASE_MAIN_BRANCH_UNRESOLVED',
-    'RELEASE_MAIN_REF_UNVERIFIED',
-    'SDD_PREPUBLISH_FAILED',
-    'PUBLISH_CONTEXT_REQUIRED',
-    'APP_RELEASE_STAGED_SCOPE_REQUIRED',
-    'APP_RELEASE_STAGED_SCOPE_MISMATCH',
-  ]).has(code)) {
-    return true;
-  }
-  return /^(?:SDD_|RELEASE_(?:SOURCE|GIT|MAINLINE|MAIN_BRANCH|MAIN_REF)|RUNTIME_(?:SOURCE|BUILD|PACKAGE|DEPENDENCY))/.test(
-    code
-  );
-}
-
 function parseChildJsonOutput(stdout) {
   const text = String(stdout || '').trim();
   if (!text) return null;
@@ -1181,6 +1224,8 @@ async function waitForPublishLeaseAvailability(config, target, flags = {}) {
   const deadline = startedAt + waitSeconds * 1000;
   const clientSessionId = createPublishClientSessionId();
   let attempts = 0;
+  let lastNoticeFingerprint = '';
+  let lastNoticeAt = 0;
   while (true) {
     const remote = await fetchPublishLeaseStatus(
       config,
@@ -1191,10 +1236,11 @@ async function waitForPublishLeaseAvailability(config, target, flags = {}) {
       return { waitedMs: Date.now() - startedAt, attempts, remote };
     }
     const remoteHolder =
-      (typeof remote?.holder === 'string' ? remote.holder : null) ||
-      remote?.holder?.changeId ||
       remote?.changeId ||
+      remote?.clientSessionId ||
+      remote?.holder?.changeId ||
       remote?.holder?.clientSessionId ||
+      (typeof remote?.holder === 'string' ? remote.holder : null) ||
       'another release';
     if (Date.now() >= deadline) {
       fail(
@@ -1210,9 +1256,20 @@ async function waitForPublishLeaseAvailability(config, target, flags = {}) {
       30000,
       Math.max(1000, deadline - Date.now())
     );
-    warn(
-      `发布队列等待中: app=${target.appType} holder=${remoteHolder} retry=${Math.ceil(delayMs / 1000)}s`
-    );
+    const noticeFingerprint = [
+      remoteHolder,
+      remote?.leaseId || '',
+    ].join(':');
+    if (
+      noticeFingerprint !== lastNoticeFingerprint ||
+      Date.now() - lastNoticeAt >= 120_000
+    ) {
+      warn(
+        `发布队列等待中: app=${target.appType} holder=${remoteHolder} retry=${Math.ceil(delayMs / 1000)}s${remote?.expiresAt ? ` expiresAt=${remote.expiresAt}` : ''}`
+      );
+      lastNoticeFingerprint = noticeFingerprint;
+      lastNoticeAt = Date.now();
+    }
     await sleep(delayMs);
   }
 }
@@ -1443,6 +1500,9 @@ async function publishWorkspaceRelease(config, target, flags = {}) {
       execution: null,
     };
   }
+  const plannedSourceRevision = prepareReleaseSourceRevision({
+    cwd: process.cwd(),
+  });
   const existing = readReleaseExecution(changeId);
   if (
     existing &&
@@ -1462,6 +1522,11 @@ async function publishWorkspaceRelease(config, target, flags = {}) {
       'RELEASE_WRITE_REVIEW_REQUIRED: 上次写请求结果不确定；请先只读核对 staged release，确认可重试后追加 --resume-after-review'
     );
   }
+  if (existing?.releaseSourceRevision) {
+    assertReleaseSourceRevisionStable(existing.releaseSourceRevision, {
+      cwd: process.cwd(),
+    });
+  }
   const now = new Date().toISOString();
   const execution = existing || {
     schemaVersion: 'openxiangda_release_execution_v1',
@@ -1469,6 +1534,7 @@ async function publishWorkspaceRelease(config, target, flags = {}) {
     profile: target.profileName,
     changeId,
     planHash,
+    releaseSourceRevision: plannedSourceRevision,
     status: 'planned',
     createdAt: now,
     updatedAt: now,
@@ -1493,6 +1559,9 @@ async function publishWorkspaceRelease(config, target, flags = {}) {
       },
     ],
   };
+  if (!execution.releaseSourceRevision) {
+    execution.releaseSourceRevision = plannedSourceRevision;
+  }
   if (execution.status === 'completed') {
     return {
       completed: true,
@@ -1609,11 +1678,11 @@ async function publishWorkspaceRelease(config, target, flags = {}) {
         execution.writeAttempted = true;
       }
     }
-    execution.status = execution.stagedWriteOccurred
-      ? 'staged-resumable'
-      : execution.writeAttempted
-        ? 'write-review-required'
-        : 'failed';
+    execution.status = classifyReleaseExecutionFailure({
+      error,
+      stagedWriteOccurred: execution.stagedWriteOccurred,
+      writeAttempted: execution.writeAttempted,
+    });
     execution.updatedAt = new Date().toISOString();
     writePrivateJsonAtomic(releaseExecutionFile(changeId), execution);
     if (!execution.writeAttempted) {
@@ -1662,7 +1731,7 @@ async function release(args) {
       '  - begin 获取应用级单写者 promotion lease；不同工作区仍可并行开发和验证。',
       '  - 带 --change 的 resource/runtime 写命令在没有本地 lease 时会自动 begin，并在后续命令复用。',
       '  - 子 Runtime/Page/Backend/Form Release 默认先 stage；app-finalize 用 --staged-resources-json 覆盖 capture 中的 changed children，并在同一事务中原子激活。',
-      '  - 默认 TTL 为 1800 秒；长异步发布每 30 秒检查并在到期前自动续租，续租失败会以 PUBLISH_LEASE_LOST 阻断后续写入。',
+      '  - 默认 TTL 为 120 秒；活动发布每 30 秒心跳并在到期前续租，客户端退出后孤儿租约最多阻塞约 2 分钟。',
       '  - begin 仅接受 clean 且与权威远端默认 main/master 完全一致的 HEAD；feature branch 先合并并 push，再由主分支一次发布。',
       '  - 因发布源已在远端主线，成功激活后 integration-status 会立即通过，end 不再等待补合并。',
       '  - integration-status --check 可作为 CI 门禁；尚未回合时返回非零。',
@@ -2080,7 +2149,14 @@ async function loadTaskStatusSnapshot(config, target, changeId) {
     process.cwd(),
     changeId
   );
-  const integration = taskResult
+  const execution = readReleaseExecution(changeId);
+  const directPublish = readDirectPublishReceipt(changeId);
+  const sourceRevision =
+    execution?.releaseSourceRevision ||
+    execution?.releaseContext?.releaseSourceRevision ||
+    directPublish?.sourceRevision ||
+    null;
+  let integration = taskResult
     ? inspectIntegrationBundleCommits(
         {
           requiredCommits: [
@@ -2095,13 +2171,26 @@ async function loadTaskStatusSnapshot(config, target, changeId) {
         { cwd: process.cwd() }
       )
     : null;
-  const execution = readReleaseExecution(changeId);
+  let integrationError = null;
+  if (!integration && sourceRevision) {
+    try {
+      integration = inspectReleaseSourceIntegration(sourceRevision, {
+        cwd: process.cwd(),
+      });
+    } catch (error) {
+      integrationError = {
+        code: error?.code || 'RELEASE_INTEGRATION_STATUS_UNAVAILABLE',
+        message: maskText(error?.message || String(error)),
+      };
+    }
+  }
   const localLease = getStoredPublishLease(target);
   const baseline = getStoredChangeBaseline(target, {
     access: 'reconciliation-read',
   });
   const clientSessionId =
     localLease?.clientSessionId ||
+    execution?.releaseContext?.clientSessionId ||
     baseline?.clientSessionId ||
     createPublishClientSessionId();
   let remoteLease = null;
@@ -2145,6 +2234,8 @@ async function loadTaskStatusSnapshot(config, target, changeId) {
       taskResult,
       integration,
       execution,
+      directPublish,
+      sourceRevision,
       remoteLease,
       postCommit,
     }),
@@ -2152,6 +2243,7 @@ async function loadTaskStatusSnapshot(config, target, changeId) {
     diagnostics: {
       remoteLeaseError,
       postCommitError,
+      integrationError,
     },
   };
 }
@@ -3717,9 +3809,25 @@ function resolveChangeSourceBase(changeId, flags = {}) {
   if (!explicitBaseRef && changeId) {
     try {
       const scope = getSddChangeScope({ cwd: process.cwd(), changeId });
-      const recorded = scope?.change?.sourceBase;
+      const recorded =
+        scope?.change?.sourceBase ||
+        scope?.release?.sourceBase;
       if (recorded?.baseCommit && recorded?.treeHash) return recorded;
-    } catch {
+      const recordedBaseRevision =
+        scope?.change?.baseRevision ||
+        scope?.release?.baseRevision;
+      if (recordedBaseRevision) {
+        return readGitSourceBase(process.cwd(), recordedBaseRevision);
+      }
+      if (scope?.change?.changeMode === 'mainline-bundle') {
+        const error = new Error(
+          `SDD_SOURCE_BASE_REQUIRED: mainline bundle ${changeId} 缺少 sourceBase/baseRevision，禁止退化为当前 HEAD`
+        );
+        error.code = 'SDD_SOURCE_BASE_REQUIRED';
+        throw error;
+      }
+    } catch (error) {
+      if (error?.code === 'SDD_SOURCE_BASE_REQUIRED') throw error;
       // A direct release may use --change without a local SDD record. In that
       // case the current Git HEAD is still a deterministic, auditable base.
     }
@@ -3918,6 +4026,7 @@ async function resolvePublishLeaseForWrite(config, target, flags = {}) {
   const explicitLeaseId = readStringFlag(flags, 'publish-lease-id');
   const changeId = readStringFlag(flags, 'change');
   const storedLease = getStoredPublishLease(target);
+  let acquiredByCommand = false;
   assertOrClaimWorktreeOwner({
     cwd: process.cwd(),
     changeId: changeId || storedLease?.changeId || 'unscoped-publish',
@@ -3981,6 +4090,7 @@ async function resolvePublishLeaseForWrite(config, target, flags = {}) {
         ...flags,
         'client-session-id': clientSessionId,
       });
+      acquiredByCommand = true;
     } catch (error) {
       clearRejectedPendingBaseline(target, baseline, error);
       throw error;
@@ -4017,6 +4127,17 @@ async function resolvePublishLeaseForWrite(config, target, flags = {}) {
   if (shouldRenewPublishLease(lease)) {
     lease = await heartbeat.beforeWrite({ forceRenew: true });
   }
+  if (acquiredByCommand) {
+    activeCommandScopedPublishLease = {
+      config,
+      target,
+      leaseId: lease.leaseId,
+      changeId: lease.changeId || changeId,
+      writeAttempted: false,
+      retain: false,
+      retentionReason: null,
+    };
+  }
   return lease;
 }
 
@@ -4084,6 +4205,112 @@ async function stopActivePublishLeaseHeartbeat() {
   if (active?.heartbeat) await active.heartbeat.stop();
 }
 
+function markCommandScopedPublishWriteAttempted() {
+  if (activeCommandScopedPublishLease) {
+    activeCommandScopedPublishLease.writeAttempted = true;
+  }
+}
+
+function retainCommandScopedPublishLease(reason = 'staged-release') {
+  if (!activeCommandScopedPublishLease) return false;
+  activeCommandScopedPublishLease.retain = true;
+  activeCommandScopedPublishLease.retentionReason = String(reason || 'staged-release');
+  return true;
+}
+
+async function finalizeCommandScopedPublishLease(options = {}) {
+  const active = activeCommandScopedPublishLease;
+  if (!active) return null;
+  activeCommandScopedPublishLease = null;
+  if (active.retain) {
+    return {
+      managed: true,
+      released: false,
+      retained: true,
+      reason: active.retentionReason,
+    };
+  }
+  if (options.succeeded === false && active.writeAttempted) {
+    warn(
+      `PUBLISH_WRITE_REVIEW_REQUIRED: change=${active.changeId || '-'} 的写请求结果未完整确认，租约已保留供只读核对和恢复`
+    );
+    return {
+      managed: true,
+      released: false,
+      retained: true,
+      reason: 'write-result-review',
+    };
+  }
+
+  await stopActivePublishLeaseHeartbeat();
+  const stored = getStoredPublishLease(active.target);
+  if (!stored || stored.leaseId !== active.leaseId) {
+    return {
+      managed: true,
+      released: false,
+      retained: false,
+      reason: 'local-lease-already-cleared',
+    };
+  }
+  const baseline = getStoredChangeBaseline(active.target, {
+    access: 'reconciliation-read',
+  });
+  const integration = assertReleaseSourceIntegrated(
+    baseline?.releaseSourceRevision,
+    { cwd: process.cwd() }
+  );
+  try {
+    await requestWithAuth(
+      active.config,
+      active.target.profileName,
+      publishLeaseApiPath(
+        active.target,
+        `/${encodeURIComponent(active.leaseId)}/release`
+      ),
+      {
+        method: 'POST',
+        body: {
+          completion:
+            options.succeeded === false
+              ? 'prewrite-failed'
+              : 'direct-publish-completed',
+          sourceCommit: integration.sourceCommit,
+          mainBranch: integration.mainBranch,
+          mainTipCommit: integration.mainTipCommit,
+        },
+      }
+    );
+  } catch (error) {
+    if (
+      !['PUBLISH_LEASE_EXPIRED', 'PUBLISH_LEASE_INVALID'].includes(
+        error?.code
+      )
+    ) {
+      activeCommandScopedPublishLease = active;
+      throw error;
+    }
+  }
+  clearPublishLease(active.target, active.leaseId);
+  if (baseline) {
+    clearChangeBaseline(
+      active.target,
+      baseline.baselineId || baseline.id
+    );
+  }
+  releaseWorktreeOwner({ cwd: process.cwd() });
+  activePublishRequestContext = null;
+  return {
+    managed: true,
+    released: true,
+    retained: false,
+    completion:
+      options.succeeded === false
+        ? 'prewrite-failed'
+        : 'direct-publish-completed',
+    integration,
+  };
+}
+
 function publishContextRequiredError(label, detail) {
   const suffix = detail ? `（${detail}）` : '';
   const error = new Error(
@@ -5773,7 +6000,12 @@ async function workspace(args) {
             flags
           );
         }
-        runReactSpaFormSchemaPublish(profileName, profile, bound.appType, publishOptions);
+        await runReactSpaFormSchemaPublish(
+          profileName,
+          profile,
+          bound.appType,
+          publishOptions
+        );
       } else {
         fail(
           [
@@ -5794,7 +6026,12 @@ async function workspace(args) {
           flags
         );
       }
-      runWorkspacePublish(profileName, profile, bound.appType, publishOptions.workspaceArgs);
+      await runWorkspacePublish(
+        profileName,
+        profile,
+        bound.appType,
+        publishOptions.workspaceArgs
+      );
     }
     if (publishOptions.includeResources) {
       if (publishOptions.dryRun) {
@@ -5828,6 +6065,7 @@ async function workspace(args) {
     } else if (!publishOptions.quietResourceSkip) {
       print('已跳过 src/resources 发布；如需同时发布资源，传 --resources。');
     }
+    await finalizeCommandScopedPublishLease({ succeeded: true });
     return;
   }
 
@@ -6644,6 +6882,12 @@ async function page(args) {
         },
       }
     );
+    const leaseCompletion = await finalizeCommandScopedPublishLease({
+      succeeded: true,
+    });
+    if (leaseCompletion && data && typeof data === 'object') {
+      data.publishLeaseLifecycle = leaseCompletion;
+    }
     return outputPageResult(data, flags);
   }
 
@@ -6719,6 +6963,15 @@ async function page(args) {
         legacyFormUuid: item.legacyFormUuid,
       });
     }
+    if (!activate) {
+      retainCommandScopedPublishLease('staged-page');
+    }
+    const leaseCompletion = await finalizeCommandScopedPublishLease({
+      succeeded: true,
+    });
+    if (leaseCompletion && data && typeof data === 'object') {
+      data.publishLeaseLifecycle = leaseCompletion;
+    }
     return outputPageResult(data, flags);
   }
 
@@ -10244,6 +10497,18 @@ async function resource(args) {
       error.missingSecretRefs = missing;
       throw error;
     }
+    if (publishPlan.formFieldContracts?.valid === false) {
+      const violations = publishPlan.formFieldContracts.errors || [];
+      const error = new Error(
+        `FORM_FIELD_CONTRACT_INVALID: ${violations
+          .slice(0, 8)
+          .map(item => item.message)
+          .join('; ')}`
+      );
+      error.code = 'FORM_FIELD_CONTRACT_INVALID';
+      error.violations = violations;
+      throw error;
+    }
     const pruneCandidates = flags.prune
       ? await telemetry.runPhase('prune-plan', async () =>
           collectPruneResourceCandidates(config, target, manifest)
@@ -10347,6 +10612,8 @@ async function resource(args) {
           : [];
     const stagedChangeId =
       flags.change || getStoredChangeBaseline(target)?.changeId;
+    const directPublishSourceRevision =
+      getStoredChangeBaseline(target)?.releaseSourceRevision || null;
     if (stagedResources.length > 0 && stagedChangeId) {
       result.stagedResourcesFile = recordStagedAppReleaseResources(
         stagedChangeId,
@@ -10366,7 +10633,42 @@ async function resource(args) {
         target
       );
     }
+    if (stagedResources.length > 0 || flags['stage-only']) {
+      retainCommandScopedPublishLease('staged-resource');
+    }
+    const leaseCompletion = await telemetry.runPhase(
+      'lease-release',
+      async () =>
+        finalizeCommandScopedPublishLease({
+          succeeded: true,
+        })
+    );
+    if (leaseCompletion) {
+      result.publishLeaseLifecycle = leaseCompletion;
+    }
     result.timings = telemetry.stop();
+    if (leaseCompletion?.released && stagedChangeId) {
+      const receipt = writeDirectPublishReceipt(stagedChangeId, {
+        command: 'resource publish',
+        writeAttempted:
+          (result.published || []).some(item => item.action !== 'noop') ||
+          (result.deleted || []).length > 0,
+        selectors: [
+          ...(result.published || []).map(
+            item => `${item.kind || 'resource'}:${item.code}`
+          ),
+          ...(result.deleted || []).map(
+            item => `${item.kind || 'resource'}:${item.code}`
+          ),
+        ],
+        sourceRevision: directPublishSourceRevision,
+        result: {
+          published: (result.published || []).length,
+          deleted: (result.deleted || []).length,
+        },
+      });
+      result.directPublishReceipt = receipt?.file || null;
+    }
     if (flags.json) return writeJson(result);
     printResourceResult(result);
   } finally {
@@ -10599,6 +10901,10 @@ async function runtime(args) {
       target,
       flags
     );
+    const directChangeId =
+      flags.change || getStoredChangeBaseline(target)?.changeId;
+    const directSourceRevision =
+      getStoredChangeBaseline(target)?.releaseSourceRevision || null;
     await runRuntimeChangeBaselinePreflight(config, target);
     const activationPreconditions = await resolveRuntimeActivationPreconditions(
       config,
@@ -10623,6 +10929,18 @@ async function runtime(args) {
       }
     );
     saveRuntimeReleaseState(target, data);
+    const leaseCompletion = await finalizeCommandScopedPublishLease({
+      succeeded: true,
+    });
+    if (leaseCompletion?.released && directChangeId) {
+      writeDirectPublishReceipt(directChangeId, {
+        command: 'runtime activate',
+        writeAttempted: true,
+        selectors: ['runtime:active'],
+        sourceRevision: directSourceRevision,
+        result: { releaseId: data?.id || releaseId },
+      });
+    }
     if (flags.json) return writeJson(data);
     print(`runtime release 已激活: ${data.id || releaseId} build=${data.buildId || '-'}`);
     return;
@@ -10666,8 +10984,8 @@ async function runtime(args) {
     // Keep build after lease acquisition. In direct-storage modes the build
     // embeds the provider-specific assetBaseUrl returned by the protected
     // upload plan; substituting the gateway URL would change chunk/publicPath
-    // behavior. The 3600-second pre-build renewal below is therefore the safe
-    // fail-closed boundary.
+    // behavior. The async build keeps the short publish-lease heartbeat alive
+    // instead of extending a crash-prone one-hour lease.
     let publishLease = await telemetry.runPhase('lease', async () =>
       resolveRuntimePublishLeaseForWrite(config, target, flags)
     );
@@ -10748,19 +11066,8 @@ async function runtime(args) {
       }
     }
     if (!flags['no-build']) {
-      // spawnSync blocks the Node event loop, so the background heartbeat
-      // cannot run while the local Runtime build is executing. Extend to the
-      // server maximum first; if the build still outlives it, the first
-      // subsequent write performs a real renew and fails closed.
-      publishLease = await renewPublishLeaseFailClosed(
-        config,
-        target,
-        publishLease,
-        {
-          ...flags,
-          ttl: 3600,
-        }
-      );
+      // Runtime builds run in an asynchronous child process so the promotion
+      // heartbeat keeps renewing the short lease while compilation proceeds.
       await telemetry.runPhase('build', async () =>
         runRuntimeBuild({
           buildId,
@@ -10952,8 +11259,35 @@ async function runtime(args) {
       traceId,
       ...(stagedResource ? { stagedResource } : {}),
       ...(stagedResourcesFile ? { stagedResourcesFile } : {}),
-      timings: telemetry.stop(),
     };
+    if (stagedResource) {
+      retainCommandScopedPublishLease('staged-runtime');
+    }
+    const leaseCompletion = await telemetry.runPhase(
+      'lease-release',
+      async () =>
+        finalizeCommandScopedPublishLease({
+          succeeded: true,
+        })
+    );
+    if (leaseCompletion) {
+      result.publishLeaseLifecycle = leaseCompletion;
+    }
+    result.timings = telemetry.stop();
+    if (leaseCompletion?.released && stagedChangeId) {
+      const receipt = writeDirectPublishReceipt(stagedChangeId, {
+        command: 'runtime deploy',
+        writeAttempted: true,
+        selectors: ['runtime:active'],
+        sourceRevision: runtimeLineage.sourceRevision,
+        result: {
+          releaseId: data?.id || null,
+          buildId,
+          activated: true,
+        },
+      });
+      result.directPublishReceipt = receipt?.file || null;
+    }
     if (flags.json) return writeJson(result);
     print(
       [
@@ -11056,32 +11390,61 @@ async function createRuntimeOssUploadBasePlan(options) {
   );
 }
 
-function runRuntimeBuild(options) {
+async function runRuntimeBuild(options) {
   const command = options.command || defaultRuntimeBuildCommand();
   if (options.jsonOutput) {
     printRuntimeProgress(`构建 React SPA runtime: ${command}`);
   } else {
     print(`构建 React SPA runtime: ${command}`);
   }
-  const result = spawnSync(command, [], {
-    cwd: process.cwd(),
-    shell: true,
-    stdio: options.jsonOutput ? 'pipe' : 'inherit',
-    encoding: options.jsonOutput ? 'utf8' : undefined,
-    env: {
-      ...process.env,
-      OPENXIANGDA_APP_TYPE: options.appType,
-      APP_TYPE: options.appType,
-      OPENXIANGDA_BUILD_ID: options.buildId,
-      OPENXIANGDA_RUNTIME_ASSET_BASE: options.assetBaseUrl,
-    },
+  await new Promise((resolve, reject) => {
+    let child;
+    try {
+      child = spawn(command, [], {
+        cwd: process.cwd(),
+        shell: true,
+        stdio: options.jsonOutput
+          ? ['ignore', 'pipe', 'pipe']
+          : 'inherit',
+        env: {
+          ...process.env,
+          OPENXIANGDA_APP_TYPE: options.appType,
+          APP_TYPE: options.appType,
+          OPENXIANGDA_BUILD_ID: options.buildId,
+          OPENXIANGDA_RUNTIME_ASSET_BASE: options.assetBaseUrl,
+        },
+      });
+    } catch (error) {
+      reject(
+        new Error(`runtime build 无法启动: ${error?.message || String(error)}`)
+      );
+      return;
+    }
+    if (options.jsonOutput) {
+      child.stdout?.on('data', chunk => {
+        process.stderr.write(maskText(String(chunk)));
+      });
+      child.stderr?.on('data', chunk => {
+        process.stderr.write(maskText(String(chunk)));
+      });
+    }
+    child.once('error', error => {
+      reject(new Error(`runtime build 无法启动: ${error.message}`));
+    });
+    child.once('close', (code, signal) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      reject(
+        new Error(
+          `runtime build 失败: ${
+            Number.isInteger(code) ? `exit ${code}` : `signal ${signal || '-'}`
+          }`
+        )
+      );
+    });
   });
-  if (options.jsonOutput) {
-    if (result.stdout) process.stderr.write(maskText(result.stdout));
-    if (result.stderr) process.stderr.write(maskText(result.stderr));
-  }
-  if (result.error) fail(`runtime build 无法启动: ${result.error.message}`);
-  if (result.status !== 0) fail(`runtime build 失败: exit ${result.status}`);
 }
 
 function assertRuntimeBuildReady(explicitCommand) {
@@ -14705,6 +15068,18 @@ async function publishResourcesForWorkspace(config, profileName, options = {}) {
   }
   const target = getWorkspaceTarget(config, profileName, {});
   const plan = await buildResourcePlan(config, target, manifest);
+  if (plan.formFieldContracts?.valid === false) {
+    const violations = plan.formFieldContracts.errors || [];
+    const error = new Error(
+      `FORM_FIELD_CONTRACT_INVALID: ${violations
+        .slice(0, 8)
+        .map(item => item.message)
+        .join('; ')}`
+    );
+    error.code = 'FORM_FIELD_CONTRACT_INVALID';
+    error.violations = violations;
+    throw error;
+  }
   const pruneCandidates = options.prune
     ? await collectPruneResourceCandidates(config, target, manifest)
     : [];
@@ -14740,7 +15115,10 @@ async function buildResourcePlan(config, target, manifest) {
     manifest
   );
   await prepareManifestJsCodeBundlesForPlan(manifest);
-  const existing = await fetchExistingResourceMaps(config, target, manifest);
+  const [existing, formFieldContracts] = await Promise.all([
+    fetchExistingResourceMaps(config, target, manifest),
+    buildFormFieldContractPlan(config, target, manifest),
+  ]);
   const actions = [];
   addPlanActions(actions, 'role', manifest.roles, existing.roles, roleEquals);
   addPlanActions(actions, 'menu', manifest.menus, existing.menus, (item, current) => menuEquals(target.bound, item, current));
@@ -14780,6 +15158,7 @@ async function buildResourcePlan(config, target, manifest) {
     ...(manifest.resourceCodeFilters ? { resourceCodeFilters: manifest.resourceCodeFilters } : {}),
     actions,
     summary: summarizeActions(actions),
+    formFieldContracts,
     ...(functionSecretRefs
       ? {
           capabilities: {
@@ -16170,7 +16549,14 @@ async function publishResourceManifest(config, target, manifest, options = {}) {
   }
 
   await publishRoleResources(config, target, manifest.roles || [], result, publishOptions);
-  await publishFormSettingsResources(config, target, manifest.formSettings || [], result, publishOptions);
+  await publishFormSettingsResources(
+    config,
+    target,
+    manifest.formSettings || [],
+    manifest.formPermissionGroups || [],
+    result,
+    publishOptions
+  );
   await publishMenuResources(config, target, manifest.menus || [], result, publishOptions);
   await publishConnectorResources(config, target, manifest.connectors || [], result, publishOptions);
   await publishNotificationResources(config, target, manifest.notifications || [], result, publishOptions);
@@ -16200,7 +16586,13 @@ async function publishResourceManifest(config, target, manifest, options = {}) {
   await publishStorageConfigResources(config, target, manifest.storageConfigs || [], result, publishOptions);
   await publishPublicAccessPolicyResources(config, target, manifest.publicAccessPolicies || [], result, publishOptions);
   await publishPagePermissionGroupResources(config, target, manifest.pagePermissionGroups || [], result, publishOptions);
-  await publishFormPermissionGroupResources(config, target, manifest.formPermissionGroups || [], result, publishOptions);
+  await publishFormPermissionGroupResources(
+    config,
+    target,
+    manifest.formPermissionGroups || [],
+    result,
+    publishOptions
+  );
   if (options.prune) {
     await pruneResourceManifest(
       config,
@@ -17591,22 +17983,82 @@ async function publishFormSettingsResources(
   config,
   target,
   settingsItems,
+  permissionGroups,
   result,
   options = {}
 ) {
+  const settingsByForm = new Map();
   for (const item of settingsItems) {
     const code = item.code || item.formCode || item.formUuid;
-    if (shouldSkipNoopResource(options, 'formSetting', code)) {
-      recordNoopResource(result, 'formSetting', code, options);
+    const formUuid = resolveManifestFormUuid(target.bound, item, {
+      fallbackToCode: true,
+    });
+    if (!formUuid) fail(`表单设置 ${code} 无法解析 formUuid`);
+    settingsByForm.set(formUuid, { item, code });
+  }
+  const changedGroupsByForm = new Map();
+  options.formReleaseHandledPermissionCodes =
+    options.formReleaseHandledPermissionCodes || new Set();
+  for (const group of permissionGroups || []) {
+    const code = group.code || group.resourceCode;
+    if (shouldSkipNoopResource(options, 'formPermissionGroup', code)) {
+      recordNoopResource(result, 'formPermissionGroup', code, options);
+      options.formReleaseHandledPermissionCodes.add(code);
       continue;
     }
-    const formUuid = resolveManifestFormUuid(target.bound, item, { fallbackToCode: true });
-    if (!formUuid) fail(`表单设置 ${code} 无法解析 formUuid`);
-    const action = getPlannedResourceAction(options, 'formSetting', code);
+    const formUuid = resolveManifestFormUuid(target.bound, group);
+    if (!formUuid) {
+      fail(`表单权限组 ${code} 无法解析 formUuid，不能进入 FormRelease`);
+    }
+    if (!changedGroupsByForm.has(formUuid)) {
+      changedGroupsByForm.set(formUuid, []);
+    }
+    changedGroupsByForm.get(formUuid).push(group);
+  }
+  const formUuids = unique([
+    ...settingsByForm.keys(),
+    ...changedGroupsByForm.keys(),
+  ]).sort();
+  for (const formUuid of formUuids) {
+    const setting = settingsByForm.get(formUuid);
+    const item = setting?.item || null;
+    const groups = changedGroupsByForm.get(formUuid) || [];
+    const code =
+      setting?.code ||
+      groups[0]?.formCode ||
+      groups[0]?.form ||
+      formUuid;
+    const settingNoop =
+      item && shouldSkipNoopResource(options, 'formSetting', code);
+    if (settingNoop) {
+      recordNoopResource(result, 'formSetting', code, options);
+    }
+    if (settingNoop && groups.length === 0) continue;
+    const action = item
+      ? getPlannedResourceAction(options, 'formSetting', code)
+      : null;
     const frozen =
       frozenFormConfigFromPlanAction(action) ||
       (await fetchFrozenFormConfig(config, target, formUuid));
-    const bundleBody = buildFormSettingBundleBody(item);
+    const bundleBody =
+      item && !settingNoop ? buildFormSettingBundleBody(item) : {};
+    if (groups.length > 0) {
+      bundleBody.permissionGroups = groups.map(group => {
+        const body = {
+          ...withoutResourceMeta(group),
+          resourceCode: group.code || group.resourceCode,
+          name: group.name || group.code || group.resourceCode,
+          type: group.type || 'view',
+          roles: group.roles || [],
+        };
+        delete body.code;
+        delete body.formCode;
+        delete body.form;
+        delete body.formUuid;
+        return body;
+      });
+      bundleBody.permissionGroupsMode = 'merge';
+    }
     const activate = options.activateFormBundles === true;
     const artifactId = stableFormArtifactId(
       'config-bundle',
@@ -17627,7 +18079,19 @@ async function publishFormSettingsResources(
       },
       { frozen, artifactId }
     );
-    saveResourceEntry(target, 'formSettings', code, { formUuid });
+    if (item) {
+      saveResourceEntry(target, 'formSettings', code, { formUuid });
+    }
+    for (const group of groups) {
+      const groupCode = group.code || group.resourceCode;
+      saveFormPermissionGroupResource(
+        target,
+        groupCode,
+        undefined,
+        { formUuid }
+      );
+      options.formReleaseHandledPermissionCodes.add(groupCode);
+    }
     const releaseId = data?.release?.id;
     const contentHash = String(
       data?.release?.contentHash || data?.contentHash || ''
@@ -17676,20 +18140,36 @@ async function publishFormSettingsResources(
         delete result.stagedResource;
       }
     }
-    result.published.push({
-      kind: 'formSetting',
-      code,
-      action: data?.noop ? 'noop' : data?.active ? 'update' : 'stage',
-      formUuid,
-      revision: data?.revision,
-      activeFormReleaseHead: data?.activeFormReleaseHead,
-      staged: Boolean(data?.staged),
-      active: Boolean(data?.active),
-      releaseStatus: data?.releaseStatus,
-      releaseId,
-      contentHash: contentHash || undefined,
-      ...(stagedResource ? { stagedResource } : {}),
-    });
+    if (item && !settingNoop) {
+      result.published.push({
+        kind: 'formSetting',
+        code,
+        action: data?.noop ? 'noop' : data?.active ? 'update' : 'stage',
+        formUuid,
+        revision: data?.revision,
+        activeFormReleaseHead: data?.activeFormReleaseHead,
+        staged: Boolean(data?.staged),
+        active: Boolean(data?.active),
+        releaseStatus: data?.releaseStatus,
+        releaseId,
+        contentHash: contentHash || undefined,
+        ...(stagedResource ? { stagedResource } : {}),
+      });
+    }
+    for (const group of groups) {
+      result.published.push({
+        kind: 'formPermissionGroup',
+        code: group.code || group.resourceCode,
+        action: data?.noop ? 'noop' : data?.active ? 'update' : 'stage',
+        formUuid,
+        staged: Boolean(data?.staged),
+        active: Boolean(data?.active),
+        releaseStatus: data?.releaseStatus,
+        releaseId,
+        contentHash: contentHash || undefined,
+        ...(stagedResource ? { stagedResource } : {}),
+      });
+    }
   }
 }
 
@@ -18810,38 +19290,24 @@ async function findExistingPagePermissionGroup(config, target, code) {
 
 async function publishFormPermissionGroupResources(config, target, groups, result, options = {}) {
   for (const group of groups) {
+    if (
+      options.formReleaseHandledPermissionCodes?.has(
+        group.code || group.resourceCode
+      )
+    ) {
+      continue;
+    }
     if (shouldSkipNoopResource(options, 'formPermissionGroup', group.code)) {
       recordNoopResource(result, 'formPermissionGroup', group.code, options);
       continue;
     }
-    const formUuid = resolveManifestFormUuid(target.bound, group);
-    const existing = await findExistingFormPermissionGroup(config, target, group.code, formUuid);
-    const body = {
-      ...withoutResourceMeta(group),
-      resourceCode: group.code,
-      formUuid,
-      name: group.name || group.code,
-      type: group.type || 'view',
-      roles: group.roles || [],
-    };
-    delete body.code;
-    delete body.formCode;
-    delete body.form;
-    const data = existing
-      ? await requestWithAuth(
-          config,
-          target.profileName,
-          `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/forms/${encodeURIComponent(formUuid)}/permission-groups/${encodeURIComponent(existing.id)}`,
-          { method: 'POST', body }
-        )
-      : await requestWithAuth(
-          config,
-          target.profileName,
-          `/openxiangda-api/v1/apps/${encodeURIComponent(target.appType)}/forms/${encodeURIComponent(formUuid)}/permission-groups`,
-          { method: 'POST', body }
-        );
-    if (data?.id) saveFormPermissionGroupResource(target, group.code, data.id, { formUuid, name: data.name, resourceCode: group.code });
-    result.published.push({ kind: 'formPermissionGroup', code: group.code, action: existing ? 'update' : 'create', id: data?.id });
+    const error = new Error(
+      `FORM_PERMISSION_GROUP_STAGE_REQUIRED: ${
+        group.code || group.resourceCode
+      } 未进入 FormRelease，禁止回退为直接线上写入`
+    );
+    error.code = 'FORM_PERMISSION_GROUP_STAGE_REQUIRED';
+    throw error;
   }
 }
 
@@ -23461,6 +23927,32 @@ function publishContextHeadersForRequest(config, profileName, apiPath, options =
   );
 }
 
+function isPublishMutationRequest(apiPath, options = {}) {
+  const method = String(options.method || 'GET').toUpperCase();
+  if (['GET', 'HEAD', 'OPTIONS'].includes(method)) return false;
+  const normalizedPath = String(apiPath || '').split('?')[0];
+  if (
+    normalizedPath.includes('/publish-lease/') ||
+    normalizedPath.endsWith('/publish-lease/acquire') ||
+    normalizedPath.includes('/change-baselines')
+  ) {
+    return false;
+  }
+  if (
+    normalizedPath.endsWith('/oss-upload-plan') &&
+    options.body?.planOnly === true
+  ) {
+    return false;
+  }
+  if (
+    normalizedPath.endsWith('/schema-storage-plan') ||
+    normalizedPath.endsWith('/storage-plan')
+  ) {
+    return false;
+  }
+  return true;
+}
+
 async function requestWithAuth(config, profileName, apiPath, options = {}) {
   assertReadOnlyHttpRequest(apiPath, options);
   const resolved = getProfile(config, profileName);
@@ -23482,6 +23974,9 @@ async function requestWithAuth(config, profileName, apiPath, options = {}) {
     ) {
       await activePublishLeaseHeartbeat?.heartbeat?.beforeWrite();
     }
+    if (isPublishMutationRequest(apiPath, requestOptions)) {
+      markCommandScopedPublishWriteAttempted();
+    }
     // Build headers after the lease check: a successful renew may replace the
     // live client session/expiry metadata, and auth/transient retries must not
     // replay stale publish context.
@@ -23542,6 +24037,7 @@ async function requestFormWithAuth(config, profileName, apiPath, formDataFactory
     if (!skipPublishLeaseHeartbeat) {
       await activePublishLeaseHeartbeat?.heartbeat?.beforeWrite();
     }
+    markCommandScopedPublishWriteAttempted();
     const currentRequestOptions = {
       ...requestOptions,
       headers: {
@@ -23759,7 +24255,7 @@ function normalizeWorkspacePublishOptions(flags) {
   };
 }
 
-function runWorkspacePublish(profileName, profile, appType, publishArgs = []) {
+async function runWorkspacePublish(profileName, profile, appType, publishArgs = []) {
   const packageFile = path.join(process.cwd(), 'package.json');
   if (!fs.existsSync(packageFile)) {
     fail('当前目录没有 package.json，无法识别工作区发布脚本');
@@ -23781,14 +24277,13 @@ function runWorkspacePublish(profileName, profile, appType, publishArgs = []) {
     ? ['run', scriptName, '--', ...publishArgs]
     : ['run', scriptName];
   const globalEnv = loadGlobalEnv();
-  const result = spawnSync(command, args, {
+  await runWorkspaceChildCommand(command, args, {
     cwd: process.cwd(),
-    stdio: 'inherit',
     env: buildWorkspacePublishEnv(profileName, profile, appType, globalEnv),
+    failureCode: 'WORKSPACE_PUBLISH_FAILED',
+    label: scriptName,
+    marksPublishWrite: true,
   });
-  if (result.status !== 0) {
-    process.exit(result.status || 1);
-  }
 }
 
 function isReactSpaWorkspace() {
@@ -23798,7 +24293,12 @@ function isReactSpaWorkspace() {
   return /runtimeMode\s*:\s*['"]react-spa['"]/.test(content);
 }
 
-function runReactSpaFormSchemaPublish(profileName, profile, appType, publishOptions) {
+async function runReactSpaFormSchemaPublish(
+  profileName,
+  profile,
+  appType,
+  publishOptions
+) {
   const packageFile = path.join(process.cwd(), 'package.json');
   if (!fs.existsSync(packageFile)) {
     fail('当前目录没有 package.json，无法识别工作区发布脚本');
@@ -23818,14 +24318,137 @@ function runReactSpaFormSchemaPublish(profileName, profile, appType, publishOpti
     `React SPA 表单 schema 发布${publishOptions.dryRun ? ' (dry-run)' : ''}: ${publishOptions.targetForm}`
   );
   const globalEnv = loadGlobalEnv();
-  const result = spawnSync(command, args, {
+  await runWorkspaceChildCommand(command, args, {
     cwd: process.cwd(),
-    stdio: 'inherit',
     env: buildWorkspacePublishEnv(profileName, profile, appType, globalEnv),
+    failureCode: 'FORM_SCHEMA_PUBLISH_FAILED',
+    label: `form schema ${publishOptions.targetForm}`,
+    marksPublishWrite: true,
   });
-  if (result.status !== 0) {
-    process.exit(result.status || 1);
+}
+
+async function runWorkspaceChildCommand(command, args, options = {}) {
+  await new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd || process.cwd(),
+      stdio: 'inherit',
+      env: options.env || process.env,
+    });
+    child.once('spawn', () => {
+      if (options.marksPublishWrite) {
+        markCommandScopedPublishWriteAttempted();
+      }
+    });
+    child.once('error', reject);
+    child.once('close', (code, signal) => {
+      if (code === 0) {
+        resolve();
+        return;
+      }
+      const error = new Error(
+        `${options.label || command} 执行失败${signal ? `（signal=${signal}）` : `（exit=${code ?? 1}）`}`
+      );
+      error.code = options.failureCode || 'WORKSPACE_CHILD_COMMAND_FAILED';
+      error.exitCode = Number.isInteger(code) ? code : 1;
+      reject(error);
+  });
+  });
+}
+
+async function buildFormFieldContractPlan(config, target, manifest) {
+  const targets = [];
+  for (const [manifestKey, kind] of [
+    ['functions', 'Function'],
+    ['automations', 'Automation'],
+    ['workflows', 'Workflow'],
+    ['jsCodeNodes', 'JsCodeNode'],
+  ]) {
+    for (const item of manifest[manifestKey] || []) {
+      const analysis = item.__sourceAnalysis;
+      if (!analysis?.formFieldReferences?.length) continue;
+      const code =
+        item.code ||
+        item.functionCode ||
+        item.resourceCode ||
+        item.scriptCode;
+      for (const reference of analysis.formFieldReferences) {
+        const formUuid = resolveManifestFormBindingForContract(
+          target,
+          item,
+          reference.formCode
+        );
+        targets.push({
+          kind,
+          code,
+          formCode: reference.formCode,
+          formUuid,
+          field: reference.field,
+          api: reference.api,
+          file: reference.file,
+          line: reference.line,
+        });
+      }
+    }
+  }
+  if (targets.length === 0) {
+    return {
+      contractVersion: 'form_field_contract_v1',
+      valid: true,
+      checkedForms: 0,
+      checkedReferences: 0,
+      errors: [],
+    };
   }
+  const snapshots = new Map();
+  const formTargets = unique(
+    targets.map(item => item.formUuid).filter(Boolean)
+  ).sort();
+  await Promise.all(
+    formTargets.map(async formUuid => {
+      const frozen = await fetchFrozenFormConfig(
+        config,
+        target,
+        formUuid
+      );
+      snapshots.set(formUuid, collectFormSnapshotFieldIds(frozen.snapshot));
+    })
+  );
+  return validateFormFieldContracts(targets, snapshots);
+}
+
+function resolveManifestFormBindingForContract(target, item, formCode) {
+  const containers = [
+    item.resourceBindings,
+    item.resources,
+    item.definitionJson?.resourceBindings,
+    item.definitionJson?.resources,
+  ];
+  if (item.definitionFile) {
+    try {
+      const definition = JSON.parse(
+        fs.readFileSync(
+          path.resolve(item.__dir || process.cwd(), item.definitionFile),
+          'utf8'
+        )
+      );
+      containers.push(definition.resourceBindings, definition.resources);
+    } catch {
+      // Resource validation reports invalid definition files separately.
+    }
+  }
+  for (const container of containers) {
+    const binding = container?.forms?.[formCode];
+    if (typeof binding === 'string' && binding.trim()) return binding.trim();
+    const formUuid = String(
+      binding?.formUuid || binding?.id || binding?.uuid || ''
+    ).trim();
+    if (formUuid) return formUuid;
+  }
+  return resolveManifestFormUuid(
+    target.bound,
+    { formCode },
+    { fallbackToCode: false }
+  );
 }
 
 function buildWorkspacePublishEnv(profileName, profile, appType, globalEnv) {