@aipt/idp-deploy 0.1.2

package/src/operations.mjs

@@ -0,0 +1,1484 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { composeArgs } from './compose.mjs';
+import { doctorConfig } from './config.mjs';
+import { IdpError, invariant } from './errors.mjs';
+import { hashFile, inventoryDirectory, sha256, stableJson } from './hash.mjs';
+import {
+  assertDisjointRoots,
+  assertOutsideRepositories,
+  assertSafeRegularFile,
+  atomicWrite,
+  createExclusiveFile,
+  resolveContained,
+  secureDirectoryRoot,
+} from './security.mjs';
+import { run, runFromFile, runToFile } from './process.mjs';
+import { renderRuntimeBundles } from './render.mjs';
+import { resolveProfile, resolveProfileServices } from './profiles.mjs';
+
+const DATABASE_BY_COMPONENT = Object.freeze({ tech: 'tech', portal: 'backstage', smartgo: 'smartgo' });
+const ROLE_BY_DATABASE = Object.freeze({ tech: 'tech', backstage: 'portal', smartgo: 'smartgo' });
+const SMARTGO_WRITER_SERVICES = Object.freeze([
+  'smartgo-api',
+  'smartgo-agent-runtime',
+  'smartgo-worker',
+  'smartgo-gotology',
+  'smartgo-operations',
+  'smartgo-studio',
+]);
+const SMARTGO_BACKUP_RECOVERY_POLICY = Object.freeze({
+  maxAttempts: 3,
+  retryDelayMilliseconds: 2_000,
+  objectStoreWaitTimeoutSeconds: 30,
+  profileWaitTimeoutSeconds: 60,
+});
+
+function profileDatasets(profile) {
+  const active = new Set(resolveProfile(profile));
+  const datasets = [];
+  for (const component of ['tech', 'flow', 'portal', 'smartgo']) {
+    if (active.has(component) && DATABASE_BY_COMPONENT[component]) datasets.push(`postgresql:${DATABASE_BY_COMPONENT[component]}`);
+  }
+  if (active.has('registry')) datasets.push('registry:packages');
+  if (active.has('smartgo')) datasets.push('smartgo-object-store:objects');
+  invariant(datasets.length > 0, 'IDP_PROFILE_HAS_NO_DATA', `${profile}没有可备份的数据集`);
+  return { active, datasets };
+}
+
+function ensureRuntimeRoots(root, env) {
+  const entries = [['IDP_CONFIG_DIR', root]];
+  for (const key of ['IDP_DATA_DIR', 'IDP_BACKUP_DIR', 'IDP_LOG_DIR', 'IDP_RUNTIME_DIR', 'IDP_RESTORE_DIR']) {
+    const canonical = secureDirectoryRoot(env[key], key, { create: true });
+    assertOutsideRepositories(canonical, key);
+    env[key] = canonical;
+    entries.push([key, canonical]);
+  }
+  assertDisjointRoots(entries);
+  for (const relative of ['locks', 'receipts', 'evidence', 'tmp', 'state']) secureDirectoryRoot(path.join(env.IDP_RUNTIME_DIR, relative), `Runtime ${relative}`, { create: true });
+  for (const relative of ['staging', 'generations', 'failed']) secureDirectoryRoot(path.join(env.IDP_BACKUP_DIR, relative), `Backup ${relative}`, { create: true });
+  for (const relative of ['candidates', 'failed']) secureDirectoryRoot(path.join(env.IDP_RESTORE_DIR, relative), `Restore ${relative}`, { create: true });
+  for (const relative of ['postgresql', 'registry', 'registry/auth', 'registry/packages', 'smartgo', 'smartgo/object-store', 'edge', 'edge/data', 'edge/config']) {
+    secureDirectoryRoot(path.join(env.IDP_DATA_DIR, relative), `Data ${relative}`, { create: true, allowForeignOwner: true });
+  }
+}
+
+function activeProfileStatePath(env) {
+  return path.join(env.IDP_RUNTIME_DIR, 'state', 'active-profile.json');
+}
+
+export function readActiveProfileState(env) {
+  const candidate = activeProfileStatePath(env);
+  if (!fs.existsSync(candidate)) return null;
+  assertSafeRegularFile(candidate, 0o600, { allowEmpty: false, role: '活动Profile状态' });
+  let document;
+  try { document = JSON.parse(fs.readFileSync(candidate, 'utf8')); }
+  catch { throw new IdpError('IDP_PROFILE_STATE_INVALID', '活动Profile状态不是有效JSON'); }
+  const { digest, ...body } = document ?? {};
+  const exactKeys = ['schemaVersion', 'status', 'profile', 'services', 'configDigest', 'renderDigest', 'updatedAt', 'digest'];
+  invariant(
+    document && Object.keys(document).sort().join('\0') === exactKeys.sort().join('\0') &&
+    document.schemaVersion === 1 && ['active', 'stopped'].includes(document.status) &&
+    typeof document.profile === 'string' && Array.isArray(document.services) &&
+    document.services.every((value) => typeof value === 'string') && new Set(document.services).size === document.services.length &&
+    /^sha256:[0-9a-f]{64}$/u.test(document.configDigest ?? '') && /^sha256:[0-9a-f]{64}$/u.test(document.renderDigest ?? '') &&
+    /^sha256:[0-9a-f]{64}$/u.test(digest ?? '') && sha256(stableJson(body)) === digest,
+    'IDP_PROFILE_STATE_INVALID', '活动Profile状态契约或摘要无效',
+  );
+  invariant(stableJson(document.services) === stableJson(resolveProfileServices(document.profile)), 'IDP_PROFILE_STATE_INVALID', '活动Profile服务集合与Profile不一致');
+  return document;
+}
+
+function writeActiveProfileState(env, { status, profile, services, configDigest, renderDigest }) {
+  const candidate = activeProfileStatePath(env);
+  if (fs.existsSync(candidate)) {
+    const before = fs.readFileSync(candidate);
+    const preimage = path.join(env.IDP_RUNTIME_DIR, 'evidence', `active-profile-${Date.now()}-${crypto.randomUUID()}.preimage.json`);
+    createExclusiveFile(preimage, before, 0o600);
+  }
+  const body = { schemaVersion: 1, status, profile, services, configDigest, renderDigest, updatedAt: new Date().toISOString() };
+  const document = { ...body, digest: sha256(stableJson(body)) };
+  atomicWrite(candidate, `${JSON.stringify(document, null, 2)}\n`, 0o600);
+  return document;
+}
+
+function composeProcessEnvironment(root, renderDirectory) {
+  const environment = { ...process.env };
+  for (const key of Object.keys(environment)) {
+    if (key.startsWith('IDP_')) delete environment[key];
+  }
+  environment.IDP_CONFIG_DIR = root;
+  environment.IDP_RENDER_DIR = renderDirectory;
+  return environment;
+}
+
+function processIsAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error?.code === 'EPERM'; }
+}
+
+function acquireInstanceLock(root, env, operation) {
+  ensureRuntimeRoots(root, env);
+  const lockPath = path.join(env.IDP_RUNTIME_DIR, 'locks', 'instance.lock');
+  if (fs.existsSync(lockPath)) {
+    assertSafeRegularFile(lockPath, 0o600, { allowEmpty: false, role: '实例操作锁' });
+    let current;
+    try { current = JSON.parse(fs.readFileSync(lockPath, 'utf8')); }
+    catch { throw new IdpError('IDP_LOCK_CORRUPT', `实例操作锁损坏，禁止自动删除：${lockPath}`); }
+    const localDeadProcess = current.hostname === os.hostname() && !processIsAlive(current.pid);
+    invariant(localDeadProcess, 'IDP_OPERATION_LOCKED', `实例正在执行${current.operation ?? '未知操作'}（PID ${current.pid ?? 'unknown'}）`);
+    fs.unlinkSync(lockPath);
+  }
+  const record = { schemaVersion: 1, id: crypto.randomUUID(), operation, pid: process.pid, hostname: os.hostname(), startedAt: new Date().toISOString() };
+  try { createExclusiveFile(lockPath, `${JSON.stringify(record)}\n`, 0o600); }
+  catch (error) {
+    if (error?.code === 'EEXIST') throw new IdpError('IDP_OPERATION_LOCKED', '实例已被另一个操作锁定');
+    throw error;
+  }
+  try { receiptChain(env); }
+  catch (error) {
+    releaseInstanceLock({ lockPath, record });
+    throw error;
+  }
+  return { lockPath, record };
+}
+
+function releaseInstanceLock({ lockPath, record }) {
+  if (!fs.existsSync(lockPath)) return;
+  try {
+    const current = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+    if (current.id === record.id) fs.unlinkSync(lockPath);
+  } catch {}
+}
+
+const LIVE_INSTANCE_LEASES = new WeakSet();
+const INSTANCE_LEASE_FACTS = new WeakMap();
+
+function canonicalLeaseRoot(candidate, role) {
+  invariant(typeof candidate === 'string' && path.isAbsolute(candidate), 'IDP_INSTANCE_LEASE_SCOPE_MISMATCH', `${role}必须是绝对路径`);
+  try { return fs.realpathSync.native(candidate); }
+  catch (error) { throw new IdpError('IDP_INSTANCE_LEASE_SCOPE_MISMATCH', `${role}无法解析：${error.message}`); }
+}
+
+function useInstanceLease(root, env, callback, lease) {
+  invariant(lease && (typeof lease === 'object' || typeof lease === 'function'), 'IDP_INSTANCE_LEASE_INVALID', '实例Lease必须由当前进程的外层withInstanceLock签发');
+  const facts = INSTANCE_LEASE_FACTS.get(lease);
+  invariant(facts, 'IDP_INSTANCE_LEASE_INVALID', '实例Lease不是由当前进程的withInstanceLock签发');
+  invariant(LIVE_INSTANCE_LEASES.has(lease), 'IDP_INSTANCE_LEASE_EXPIRED', '实例Lease已过期，不能在外层操作结束后复用');
+  const requestedRoot = canonicalLeaseRoot(root, '实例Lease Config Dir');
+  const requestedRuntimeRoot = canonicalLeaseRoot(env?.IDP_RUNTIME_DIR, '实例Lease Runtime Dir');
+  invariant(
+    requestedRoot === facts.root && requestedRuntimeRoot === facts.runtimeRoot,
+    'IDP_INSTANCE_LEASE_SCOPE_MISMATCH',
+    '实例Lease只能用于签发它的Config Dir与Runtime Dir',
+  );
+  invariant(fs.existsSync(facts.lockPath), 'IDP_INSTANCE_LEASE_LOCK_MISMATCH', '实例Lease对应的磁盘锁已不存在');
+  try { assertSafeRegularFile(facts.lockPath, 0o600, { allowEmpty: false, role: '实例操作锁' }); }
+  catch (error) { throw new IdpError('IDP_INSTANCE_LEASE_LOCK_MISMATCH', `实例Lease对应的磁盘锁不再安全：${error.message}`); }
+  let current;
+  try { current = JSON.parse(fs.readFileSync(facts.lockPath, 'utf8')); }
+  catch { throw new IdpError('IDP_INSTANCE_LEASE_LOCK_MISMATCH', '实例Lease对应的磁盘锁不是有效JSON'); }
+  const recordKeys = ['schemaVersion', 'id', 'operation', 'pid', 'hostname', 'startedAt'];
+  invariant(
+    current && typeof current === 'object' && !Array.isArray(current) &&
+    stableJson(Object.keys(current).sort()) === stableJson(recordKeys.sort()) &&
+    current.schemaVersion === 1 && current.id === facts.lockId && current.operation === facts.operation &&
+    current.pid === process.pid && current.hostname === os.hostname() &&
+    sha256(stableJson(current)) === facts.recordDigest,
+    'IDP_INSTANCE_LEASE_LOCK_MISMATCH',
+    '实例Lease与当前磁盘锁记录不匹配',
+  );
+  return callback(lease);
+}
+
+export function withInstanceLock(root, env, operation, callback, { lease } = {}) {
+  if (lease !== undefined) return useInstanceLease(root, env, callback, lease);
+  const lock = acquireInstanceLock(root, env, operation);
+  let opaqueLease;
+  try {
+    opaqueLease = Object.freeze(Object.create(null));
+    INSTANCE_LEASE_FACTS.set(opaqueLease, {
+      root: canonicalLeaseRoot(root, '实例Lease Config Dir'),
+      runtimeRoot: canonicalLeaseRoot(env.IDP_RUNTIME_DIR, '实例Lease Runtime Dir'),
+      lockPath: lock.lockPath,
+      lockId: lock.record.id,
+      operation: lock.record.operation,
+      recordDigest: sha256(stableJson(lock.record)),
+    });
+    LIVE_INSTANCE_LEASES.add(opaqueLease);
+    return callback(opaqueLease);
+  }
+  finally {
+    if (opaqueLease) LIVE_INSTANCE_LEASES.delete(opaqueLease);
+    releaseInstanceLock(lock);
+  }
+}
+
+function validateReceipt(receipt) {
+  invariant(receipt && typeof receipt === 'object' && !Array.isArray(receipt), 'IDP_RECEIPT_INVALID', '运维回执格式无效');
+  invariant(receipt.schemaVersion === 1 && Number.isSafeInteger(receipt.sequence) && receipt.sequence > 0 && /^sha256:[0-9a-f]{64}$/u.test(receipt.digest ?? ''), 'IDP_RECEIPT_INVALID', '运维回执缺少有效序号或摘要');
+  const { digest, ...body } = receipt;
+  invariant(sha256(stableJson(body)) === digest, 'IDP_RECEIPT_DIGEST_MISMATCH', '运维回执摘要不匹配');
+  return receipt;
+}
+
+function receiptChain(env) {
+  const directory = path.join(env.IDP_RUNTIME_DIR, 'receipts');
+  const receipts = fs.readdirSync(directory).filter((name) => name.endsWith('.json')).map((name) => {
+    const candidate = path.join(directory, name);
+    assertSafeRegularFile(candidate, 0o600, { allowEmpty: false, role: '运维回执' });
+    return { candidate, receipt: validateReceipt(JSON.parse(fs.readFileSync(candidate, 'utf8'))) };
+  }).sort((left, right) => left.receipt.sequence - right.receipt.sequence);
+  for (const [index, entry] of receipts.entries()) {
+    invariant(entry.receipt.sequence === index + 1, 'IDP_RECEIPT_CHAIN_BROKEN', '运维回执序号不连续');
+    const expectedPrevious = index === 0 ? null : receipts[index - 1].receipt.digest;
+    invariant(entry.receipt.previousReceiptDigest === expectedPrevious, 'IDP_RECEIPT_CHAIN_BROKEN', '运维回执摘要链断裂');
+  }
+  return receipts;
+}
+
+export function readLatestVerifyEvidence(env, { profile, configDigest, renderDigest, activeUpdatedAt }) {
+  const latest = receiptChain(env).filter(({ receipt }) => receipt.operation === 'verify').at(-1)?.receipt;
+  invariant(latest, 'IDP_BINDING_VERIFY_EVIDENCE_MISSING', '生成Binding前必须先执行一次与当前活动Profile匹配的idpctl verify');
+  invariant(
+    latest.profile === profile && latest.configDigest === configDigest && latest.renderDigest === renderDigest,
+    'IDP_BINDING_VERIFY_EVIDENCE_MISMATCH',
+    '最近一次部署验证回执与当前活动Profile、配置摘要或运行时投影不一致；请重新执行idpctl verify',
+  );
+  const verifiedAt = typeof latest.at === 'string' ? new Date(latest.at) : new Date(Number.NaN);
+  const activatedAt = typeof activeUpdatedAt === 'string' ? new Date(activeUpdatedAt) : new Date(Number.NaN);
+  invariant(
+    !Number.isNaN(verifiedAt.getTime()) && !Number.isNaN(activatedAt.getTime()) && verifiedAt >= activatedAt,
+    'IDP_BINDING_VERIFY_EVIDENCE_STALE',
+    '最近一次部署验证早于当前Profile启用时间；请重新执行idpctl verify',
+  );
+  const expectedServices = resolveProfileServices(profile).map((service) => ({ service, status: 'healthy' }));
+  invariant(
+    stableJson(latest.services) === stableJson(expectedServices),
+    'IDP_BINDING_VERIFY_SERVICE_MISMATCH',
+    '最近一次部署验证没有证明当前Profile的全部服务健康',
+  );
+  return latest;
+}
+
+export function writeReceipt(env, operation, payload) {
+  const chain = receiptChain(env);
+  const previous = chain.at(-1)?.receipt;
+  const sequence = (previous?.sequence ?? 0) + 1;
+  const body = { schemaVersion: 1, sequence, operation, at: new Date().toISOString(), previousReceiptDigest: previous?.digest ?? null, ...payload };
+  const receipt = { ...body, digest: sha256(stableJson(body)) };
+  const stamp = body.at.replace(/[:.]/gu, '-');
+  const candidate = path.join(env.IDP_RUNTIME_DIR, 'receipts', `${String(sequence).padStart(12, '0')}-${stamp}-${operation.replaceAll(':', '-')}-${crypto.randomUUID()}.json`);
+  createExclusiveFile(candidate, `${JSON.stringify(receipt, null, 2)}\n`, 0o600);
+  return { candidate, receipt };
+}
+
+function findBackupEvidence(env, generationId, manifestDigest) {
+  for (const { candidate, receipt } of receiptChain(env).reverse()) {
+    if (receipt.operation === 'backup' && receipt.generationId === generationId && receipt.manifestDigest === manifestDigest) return { candidate, digest: receipt.digest };
+  }
+  throw new IdpError('IDP_BACKUP_EVIDENCE_MISSING', '备份缺少独立且摘要匹配的创建回执');
+}
+
+function findRestoreApplyEvidence(env, candidateId, candidateDigest) {
+  for (const { candidate, receipt } of receiptChain(env).reverse()) {
+    if (receipt.operation === 'restore-apply' && receipt.candidateId === candidateId && receipt.candidateDigest === candidateDigest) return { candidate, digest: receipt.digest };
+  }
+  throw new IdpError('IDP_RESTORE_EVIDENCE_MISSING', '恢复候选缺少独立且摘要匹配的创建回执');
+}
+
+function prepareState(root, env, active) {
+  if (!active.has('registry')) return;
+  const source = resolveContained(root, env.IDP_REGISTRY_HTPASSWD_FILE, 'Registry初始凭据');
+  const target = path.join(env.IDP_DATA_DIR, 'registry', 'auth', 'htpasswd');
+  if (!fs.existsSync(target)) {
+    fs.copyFileSync(source, target, fs.constants.COPYFILE_EXCL);
+    fs.chmodSync(target, 0o600);
+  } else assertSafeRegularFile(target, 0o600, { allowEmpty: true, role: 'Registry实时凭据文件' });
+}
+
+export function composeOperation({ repositoryRoot, configRoot, profile, command, requireConfigured = true, allowProfileSwitch = false, allowLegacyImageLock = false, instanceLease, runner = run }) {
+  const { root, env, report } = doctorConfig(configRoot, { requireConfigured, profile, allowLegacyImageLock });
+  const active = new Set(resolveProfile(profile));
+  return withInstanceLock(root, env, `compose:${command[0]}`, () => {
+    prepareState(root, env, active);
+    const rendered = renderRuntimeBundles(root, profile);
+    const current = readActiveProfileState(env);
+    const operation = command[0];
+    if (operation === 'up' && current?.status === 'active' && current.profile !== profile) {
+      invariant(allowProfileSwitch, 'IDP_PROFILE_SWITCH_REQUIRED', `当前活动Profile为${current.profile}；请使用idpctl switch ${profile}显式切换并清理Orphan`);
+    }
+    if (operation === 'down' && current?.status === 'active') {
+      invariant(current.profile === profile, 'IDP_PROFILE_DOWN_MISMATCH', `当前活动Profile为${current.profile}，不能用${profile}执行down`);
+    }
+    const effectiveCommand = [...command];
+    if (operation === 'up' && !effectiveCommand.includes('--remove-orphans')) effectiveCommand.push('--remove-orphans');
+    if (operation === 'down' && !effectiveCommand.includes('--remove-orphans')) effectiveCommand.push('--remove-orphans');
+    const args = composeArgs(repositoryRoot, root, profile, effectiveCommand, { projectName: env.IDP_INSTANCE_ID });
+    runner('docker', args, { env: composeProcessEnvironment(root, rendered.target) });
+    let profileState = current;
+    if (operation === 'up') profileState = writeActiveProfileState(env, { status: 'active', profile, services: resolveProfileServices(profile), configDigest: report.digest, renderDigest: rendered.manifest.digest });
+    else if (operation === 'down') profileState = writeActiveProfileState(env, { status: 'stopped', profile, services: resolveProfileServices(profile), configDigest: report.digest, renderDigest: rendered.manifest.digest });
+    return writeReceipt(env, operation, {
+      profile,
+      configDigest: report.digest,
+      renderDigest: rendered.manifest.digest,
+      profileStateDigest: profileState?.digest ?? null,
+      composeArgs: args.map((item) => item.includes(root) ? item.replace(root, '$IDP_CONFIG_DIR') : item),
+    });
+  }, { lease: instanceLease });
+}
+
+function publishGeneration(staging, target) {
+  const handle = fs.openSync(staging, 'r');
+  try { fs.fsyncSync(handle); } finally { fs.closeSync(handle); }
+  fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+  fs.renameSync(staging, target);
+  const parentHandle = fs.openSync(path.dirname(target), 'r');
+  try { fs.fsyncSync(parentHandle); } finally { fs.closeSync(parentHandle); }
+}
+
+const TECH_BACKUP_BOUNDARY_FILE = 'tech-backup-boundary.json';
+const TECH_BACKUP_BOUNDARY_COMMAND = ['/opt/knowledge-service/bin/knowledge-service.mjs', 'backup-boundary'];
+
+function strictAscending(values, role, key = (value) => value) {
+  let previous;
+  for (const value of values) {
+    const current = key(value);
+    invariant(typeof current === 'string' && (previous === undefined || previous < current), 'IDP_TECH_BACKUP_BOUNDARY_INVALID', `${role}必须唯一并按字典序严格升序排列`);
+    previous = current;
+  }
+}
+
+function validateTechBackupBoundary(document) {
+  exactObjectKeys(document, ['schemaVersion', 'generatedAt', 'digest', 'database', 'knowledge', 'objectStorage', 'restoreVerification'], 'IDP_TECH_BACKUP_BOUNDARY_INVALID', 'Tech备份边界');
+  exactObjectKeys(document.database, ['engine', 'requiredFormat', 'migrations', 'counts'], 'IDP_TECH_BACKUP_BOUNDARY_INVALID', 'Tech备份数据库边界');
+  exactObjectKeys(document.database.counts, ['spaces', 'sources', 'references', 'snapshots'], 'IDP_TECH_BACKUP_BOUNDARY_INVALID', 'Tech备份计数');
+  exactObjectKeys(document.knowledge, ['activeIndexRevision', 'sourceRevisions'], 'IDP_TECH_BACKUP_BOUNDARY_INVALID', 'Tech知识边界');
+  exactObjectKeys(document.objectStorage, ['mode', 'ownedObjects'], 'IDP_TECH_BACKUP_BOUNDARY_INVALID', 'Tech对象存储边界');
+  const timestamp = typeof document.generatedAt === 'string' ? new Date(document.generatedAt) : new Date(Number.NaN);
+  invariant(document.schemaVersion === 'tech.backup-boundary.v1' && !Number.isNaN(timestamp.getTime()) && timestamp.toISOString() === document.generatedAt, 'IDP_TECH_BACKUP_BOUNDARY_INVALID', 'Tech备份边界版本或时间无效');
+  invariant(document.database.engine === 'postgresql' && document.database.requiredFormat === 'pg_dump-custom', 'IDP_TECH_BACKUP_BOUNDARY_INVALID', 'Tech备份数据库格式无效');
+  invariant(Array.isArray(document.database.migrations) && document.database.migrations.length > 0 && document.database.migrations.length <= 10_000, 'IDP_TECH_BACKUP_BOUNDARY_INVALID', 'Tech migration边界不能为空或超限');
+  for (const migration of document.database.migrations) {
+    exactObjectKeys(migration, ['version', 'checksum'], 'IDP_TECH_BACKUP_BOUNDARY_INVALID', 'Tech migration边界项');
+    invariant(typeof migration.version === 'string' && migration.version.length > 0 && migration.version.length <= 256 && /^sha256:[0-9a-f]{64}$/u.test(migration.checksum ?? ''), 'IDP_TECH_BACKUP_BOUNDARY_INVALID', 'Tech migration版本或checksum无效');
+  }
+  strictAscending(document.database.migrations, 'Tech migration版本', (entry) => entry.version);
+  for (const [key, value] of Object.entries(document.database.counts)) invariant(Number.isSafeInteger(value) && value >= 0, 'IDP_TECH_BACKUP_BOUNDARY_INVALID', `Tech计数${key}无效`);
+  invariant(typeof document.knowledge.activeIndexRevision === 'string' && document.knowledge.activeIndexRevision.length > 0 && document.knowledge.activeIndexRevision.length <= 256, 'IDP_TECH_BACKUP_BOUNDARY_INVALID', 'Tech active index revision无效');
+  invariant(Array.isArray(document.knowledge.sourceRevisions) && document.knowledge.sourceRevisions.length <= 10_000, 'IDP_TECH_BACKUP_BOUNDARY_INVALID', 'Tech来源Revision列表无效或超限');
+  for (const source of document.knowledge.sourceRevisions) {
+    exactObjectKeys(source, ['sourceId', 'identity', 'repositoryUrl', 'commit', 'treeDigest'], 'IDP_TECH_BACKUP_BOUNDARY_INVALID', 'Tech来源Revision');
+    invariant(typeof source.sourceId === 'string' && source.sourceId.length > 0 && source.sourceId.length <= 256 && typeof source.identity === 'string' && source.identity.length > 0 && source.identity.length <= 256, 'IDP_TECH_BACKUP_BOUNDARY_INVALID', 'Tech来源身份无效');
+    invariant(typeof source.repositoryUrl === 'string' && source.repositoryUrl.length > 0 && source.repositoryUrl.length <= 4096 && !/[\r\n\0]/u.test(source.repositoryUrl), 'IDP_TECH_BACKUP_BOUNDARY_INVALID', 'Tech来源仓库地址无效');
+    const hasRevision = source.commit !== null || source.treeDigest !== null;
+    invariant(!hasRevision || (typeof source.commit === 'string' && /^[0-9a-f]{40}(?:[0-9a-f]{24})?$/u.test(source.commit) && /^sha256:[0-9a-f]{64}$/u.test(source.treeDigest ?? '')), 'IDP_TECH_BACKUP_BOUNDARY_INVALID', 'Tech来源commit与treeDigest必须同时为空或同时有效');
+    invariant(hasRevision || (source.commit === null && source.treeDigest === null), 'IDP_TECH_BACKUP_BOUNDARY_INVALID', 'Tech来源commit与treeDigest必须同时为空或同时有效');
+  }
+  strictAscending(document.knowledge.sourceRevisions, 'Tech来源Revision', (entry) => entry.sourceId);
+  invariant(document.objectStorage.mode === 'none' && document.objectStorage.ownedObjects === false, 'IDP_TECH_BACKUP_BOUNDARY_INVALID', 'Tech对象存储边界必须保持none/false');
+  invariant(Array.isArray(document.restoreVerification) && document.restoreVerification.length > 0 && document.restoreVerification.every((value) => typeof value === 'string' && value.length > 0 && value.length <= 512) && new Set(document.restoreVerification).size === document.restoreVerification.length, 'IDP_TECH_BACKUP_BOUNDARY_INVALID', 'Tech恢复验证说明无效');
+  const { generatedAt: _generatedAt, digest, ...facts } = document;
+  invariant(/^sha256:[0-9a-f]{64}$/u.test(digest ?? '') && sha256(stableJson(facts)) === digest, 'IDP_TECH_BACKUP_BOUNDARY_DIGEST_MISMATCH', 'Tech备份边界事实摘要不匹配');
+  return document;
+}
+
+function parseTechBackupBoundaryOutput(stdout) {
+  let document;
+  try { document = JSON.parse(String(Buffer.isBuffer(stdout) ? stdout.toString('utf8') : stdout ?? '').trim()); }
+  catch { throw new IdpError('IDP_TECH_BACKUP_BOUNDARY_JSON_INVALID', 'Tech backup-boundary未输出单一有效JSON'); }
+  return validateTechBackupBoundary(document);
+}
+
+function runStoppedTechBoundary(compose, environment, runner) {
+  const result = runner('docker', compose(['run', '--rm', '--no-deps', '--entrypoint', 'node', 'tech', ...TECH_BACKUP_BOUNDARY_COMMAND]), { capture: true, env: environment });
+  return parseTechBackupBoundaryOutput(result.stdout);
+}
+
+function runLiveTechBoundary(compose, environment, runner) {
+  const result = runner('docker', compose(['exec', '-T', 'tech', 'node', ...TECH_BACKUP_BOUNDARY_COMMAND]), { capture: true, env: environment });
+  return parseTechBackupBoundaryOutput(result.stdout);
+}
+
+function runTechBoundaryForDatabase({ rendered, compose, environment, env, database, expectedDigest, runner }) {
+  const temporaryRoot = path.join(env.IDP_RUNTIME_DIR, 'tmp', `tech-boundary-${crypto.randomUUID()}`);
+  const sourceRoot = path.join(rendered.target, 'tech');
+  fs.cpSync(sourceRoot, temporaryRoot, { recursive: true, errorOnExist: true });
+  for (const relative of ['', 'config', 'secrets']) {
+    const source = path.join(sourceRoot, relative);
+    const target = path.join(temporaryRoot, relative);
+    fs.chmodSync(target, fs.statSync(source).mode & 0o777);
+  }
+  try {
+    const databaseFile = path.join(temporaryRoot, 'secrets', 'database-url');
+    const original = fs.readFileSync(databaseFile, 'utf8').trim();
+    let url;
+    try { url = new URL(original); } catch { throw new IdpError('IDP_TECH_DATABASE_URL_INVALID', 'Tech数据库文件不是有效URL'); }
+    url.pathname = `/${database}`;
+    atomicWrite(databaseFile, `${url.toString()}\n`, 0o400);
+    const result = runner('docker', compose(['run', '--rm', '--no-deps', '--volume', `${temporaryRoot}:/run/idp-restore-config:ro`, '--env', 'IDP_COMPONENT_CONFIG_DIR=/run/idp-restore-config', '--entrypoint', 'node', 'tech', ...TECH_BACKUP_BOUNDARY_COMMAND]), { capture: true, env: environment });
+    const boundary = parseTechBackupBoundaryOutput(result.stdout);
+    invariant(boundary.digest === expectedDigest, 'IDP_TECH_RESTORE_BOUNDARY_MISMATCH', '恢复数据库的migration、计数、active index或来源Revision与备份边界不一致');
+    return boundary;
+  } finally {
+    if (fs.existsSync(temporaryRoot)) fs.rmSync(temporaryRoot, { recursive: true, force: true });
+  }
+}
+
+function safeErrorCode(error, fallback = 'IDP_PROCESS_FAILED') {
+  return /^[A-Z][A-Z0-9_]{0,127}$/u.test(error?.code ?? '') ? error.code : fallback;
+}
+
+function emptySmartGoRecovery(profile) {
+  return {
+    unpause: { required: false, attempted: false, status: 'not-required', attempts: 0, errorCode: null },
+    objectStoreHealth: {
+      required: false, attempted: false, status: 'not-required', attempts: 0,
+      maxAttempts: SMARTGO_BACKUP_RECOVERY_POLICY.maxAttempts,
+      waitTimeoutSeconds: SMARTGO_BACKUP_RECOVERY_POLICY.objectStoreWaitTimeoutSeconds,
+      errorCode: null,
+    },
+    profile: {
+      required: false, attempted: false, status: 'not-required', attempts: 0,
+      maxAttempts: SMARTGO_BACKUP_RECOVERY_POLICY.maxAttempts,
+      waitTimeoutSeconds: SMARTGO_BACKUP_RECOVERY_POLICY.profileWaitTimeoutSeconds,
+      services: resolveProfileServices(profile), errorCode: null,
+    },
+  };
+}
+
+function boundedComposeHealthWait({ compose, services, waitTimeoutSeconds, runner, environment, waiter }) {
+  let lastError;
+  for (let attempt = 1; attempt <= SMARTGO_BACKUP_RECOVERY_POLICY.maxAttempts; attempt += 1) {
+    try {
+      runner('docker', compose(['up', '-d', '--wait', '--wait-timeout', String(waitTimeoutSeconds), ...services]), { env: environment });
+      return {
+        required: true, attempted: true, status: 'restored', attempts: attempt,
+        maxAttempts: SMARTGO_BACKUP_RECOVERY_POLICY.maxAttempts, waitTimeoutSeconds, errorCode: null,
+      };
+    } catch (error) {
+      lastError = error;
+      if (attempt < SMARTGO_BACKUP_RECOVERY_POLICY.maxAttempts) waiter(SMARTGO_BACKUP_RECOVERY_POLICY.retryDelayMilliseconds);
+    }
+  }
+  return {
+    required: true, attempted: true, status: 'failed', attempts: SMARTGO_BACKUP_RECOVERY_POLICY.maxAttempts,
+    maxAttempts: SMARTGO_BACKUP_RECOVERY_POLICY.maxAttempts, waitTimeoutSeconds,
+    errorCode: safeErrorCode(lastError),
+  };
+}
+
+function restoreSmartGoProfileRuntime({ repositoryRoot, root, profile, env, environment, runner, waiter, unpauseRequired }) {
+  const compose = (command) => composeArgs(repositoryRoot, root, profile, command, { projectName: env.IDP_INSTANCE_ID });
+  const recovery = emptySmartGoRecovery(profile);
+  if (unpauseRequired) {
+    recovery.unpause = { required: true, attempted: true, status: 'restored', attempts: 1, errorCode: null };
+    try { runner('docker', compose(['unpause', 'smartgo-object-store']), { env: environment }); }
+    catch (error) {
+      // 解除暂停命令可能在服务已经恢复后仍返回非零；最终以严格的全 Profile 健康证明为准，并保留该错误事实。
+      recovery.unpause.status = 'failed';
+      recovery.unpause.errorCode = safeErrorCode(error);
+    }
+  }
+  recovery.objectStoreHealth = boundedComposeHealthWait({
+    compose, services: ['smartgo-object-store'],
+    waitTimeoutSeconds: SMARTGO_BACKUP_RECOVERY_POLICY.objectStoreWaitTimeoutSeconds,
+    runner, environment, waiter,
+  });
+  recovery.profile = {
+    ...boundedComposeHealthWait({
+      compose, services: resolveProfileServices(profile),
+      waitTimeoutSeconds: SMARTGO_BACKUP_RECOVERY_POLICY.profileWaitTimeoutSeconds,
+      runner, environment, waiter,
+    }),
+    services: resolveProfileServices(profile),
+  };
+  return recovery;
+}
+
+export function createBackup({ repositoryRoot, configRoot, profile = 'core', instanceLease, runner = run, fileRunner = runToFile, waiter = defaultWaiter, allowLegacyImageLock = false }) {
+  const { active, datasets } = profileDatasets(profile);
+  const { root, env, report } = doctorConfig(configRoot, { requireConfigured: true, profile, allowLegacyImageLock });
+  return withInstanceLock(root, env, `backup:${profile}`, () => {
+    prepareState(root, env, active);
+    const rendered = renderRuntimeBundles(root, profile);
+    const processEnvironment = composeProcessEnvironment(root, rendered.target);
+    const generationId = `${new Date().toISOString().replace(/[:.]/gu, '-')}-${report.digest.slice(7, 13)}${crypto.randomBytes(3).toString('hex')}`;
+    const backupStagingRoot = secureDirectoryRoot(path.join(env.IDP_BACKUP_DIR, 'staging'), 'Backup staging', { create: true });
+    const backupGenerationsRoot = secureDirectoryRoot(path.join(env.IDP_BACKUP_DIR, 'generations'), 'Backup generations', { create: true });
+    const backupFailedRoot = secureDirectoryRoot(path.join(env.IDP_BACKUP_DIR, 'failed'), 'Backup failed', { create: true });
+    const staging = path.join(backupStagingRoot, `${generationId}-${crypto.randomUUID()}`);
+    const target = path.join(backupGenerationsRoot, generationId);
+    fs.mkdirSync(staging, { recursive: false, mode: 0o700 });
+    let registryPaused = false;
+    let smartgoObjectStoreRecoveryRequired = false;
+    let smartgoRuntimeRecoveryRequired = false;
+    let smartgoRecovery = null;
+    let smartgoBackupPhase = active.has('smartgo') ? 'pending' : null;
+    let techStopped = false;
+    let published = false;
+    try {
+      const entries = [];
+      let techBoundary = null;
+      const databaseDatasets = datasets.filter((value) => value.startsWith('postgresql:'));
+      if (active.has('tech')) {
+        runner('docker', composeArgs(repositoryRoot, root, profile, ['stop', '--timeout', '60', 'tech'], { projectName: env.IDP_INSTANCE_ID }), { env: processEnvironment });
+        techStopped = true;
+        const compose = (command) => composeArgs(repositoryRoot, root, profile, command, { projectName: env.IDP_INSTANCE_ID });
+        const boundary = runStoppedTechBoundary(compose, processEnvironment, runner);
+        const boundaryPath = path.join(staging, TECH_BACKUP_BOUNDARY_FILE);
+        createExclusiveFile(boundaryPath, `${JSON.stringify(boundary, null, 2)}\n`, 0o600);
+        const boundaryStat = assertSafeRegularFile(boundaryPath, 0o600, { allowEmpty: false, role: 'Tech备份边界文件' });
+        techBoundary = {
+          contract: 'tech.backup-boundary.v1', file: TECH_BACKUP_BOUNDARY_FILE,
+          size: boundaryStat.size, fileDigest: hashFile(boundaryPath), factsDigest: boundary.digest,
+        };
+        const techDataset = databaseDatasets.find((value) => value === 'postgresql:tech');
+        invariant(techDataset, 'IDP_TECH_BACKUP_DATASET_MISSING', '包含Tech的Profile必须同时备份tech数据库');
+        const output = path.join(staging, 'tech.dump');
+        fileRunner('docker', composeArgs(repositoryRoot, root, profile, ['exec', '-T', '-u', 'postgres', 'postgresql', 'pg_dump', '--format=custom', '--dbname', 'tech'], { projectName: env.IDP_INSTANCE_ID }), output, { env: processEnvironment });
+        const stat = assertSafeRegularFile(output, 0o600, { allowEmpty: false, role: 'tech数据库备份' });
+        entries.push({ dataset: techDataset, kind: 'postgresql', database: 'tech', file: 'tech.dump', size: stat.size, digest: hashFile(output) });
+        runner('docker', composeArgs(repositoryRoot, root, profile, ['up', '-d', '--wait', 'tech'], { projectName: env.IDP_INSTANCE_ID }), { env: processEnvironment });
+        techStopped = false;
+      }
+      for (const dataset of databaseDatasets.filter((value) => !['postgresql:tech', 'postgresql:smartgo'].includes(value))) {
+        const database = dataset.slice('postgresql:'.length);
+        const file = `${database}.dump`;
+        const output = path.join(staging, file);
+        fileRunner('docker', composeArgs(repositoryRoot, root, profile, ['exec', '-T', '-u', 'postgres', 'postgresql', 'pg_dump', '--format=custom', '--dbname', database], { projectName: env.IDP_INSTANCE_ID }), output, { env: processEnvironment });
+        const stat = assertSafeRegularFile(output, 0o600, { allowEmpty: false, role: `${database}数据库备份` });
+        entries.push({ dataset, kind: 'postgresql', database, file, size: stat.size, digest: hashFile(output) });
+      }
+      if (datasets.includes('registry:packages')) {
+        runner('docker', composeArgs(repositoryRoot, root, profile, ['pause', 'registry'], { projectName: env.IDP_INSTANCE_ID }), { env: processEnvironment });
+        registryPaused = true;
+        const file = 'registry.tar.gz';
+        const archive = path.join(staging, file);
+        runner('tar', ['-C', path.join(env.IDP_DATA_DIR, 'registry'), '-czf', archive, '.']);
+        fs.chmodSync(archive, 0o600);
+        const stat = assertSafeRegularFile(archive, 0o600, { allowEmpty: false, role: 'Registry备份' });
+        entries.push({ dataset: 'registry:packages', kind: 'registry', file, size: stat.size, digest: hashFile(archive) });
+        runner('docker', composeArgs(repositoryRoot, root, profile, ['unpause', 'registry'], { projectName: env.IDP_INSTANCE_ID }), { env: processEnvironment });
+        registryPaused = false;
+      }
+      if (active.has('smartgo')) {
+        const smartgoDataset = databaseDatasets.find((value) => value === 'postgresql:smartgo');
+        invariant(smartgoDataset && datasets.includes('smartgo-object-store:objects'), 'IDP_SMARTGO_BACKUP_DATASET_MISSING', '包含SmartGo的Profile必须同时备份smartgo数据库与对象存储');
+        const compose = (command) => composeArgs(repositoryRoot, root, profile, command, { projectName: env.IDP_INSTANCE_ID });
+
+        smartgoBackupPhase = 'stopping-writers';
+        smartgoRuntimeRecoveryRequired = true;
+        runner('docker', compose(['stop', '--timeout', '60', ...SMARTGO_WRITER_SERVICES]), { env: processEnvironment });
+
+        smartgoBackupPhase = 'pausing-object-store';
+        smartgoObjectStoreRecoveryRequired = true;
+        runner('docker', compose(['pause', 'smartgo-object-store']), { env: processEnvironment });
+
+        smartgoBackupPhase = 'dumping-database';
+        const databaseFile = 'smartgo.dump';
+        const databaseOutput = path.join(staging, databaseFile);
+        fileRunner('docker', compose(['exec', '-T', '-u', 'postgres', 'postgresql', 'pg_dump', '--format=custom', '--dbname', 'smartgo']), databaseOutput, { env: processEnvironment });
+        const databaseStat = assertSafeRegularFile(databaseOutput, 0o600, { allowEmpty: false, role: 'smartgo数据库备份' });
+        entries.push({ dataset: smartgoDataset, kind: 'postgresql', database: 'smartgo', file: databaseFile, size: databaseStat.size, digest: hashFile(databaseOutput) });
+
+        smartgoBackupPhase = 'archiving-objects';
+        const file = 'smartgo-object-store.tar.gz';
+        const archive = path.join(staging, file);
+        runner('tar', ['-C', path.join(env.IDP_DATA_DIR, 'smartgo', 'object-store'), '-czf', archive, '.']);
+        fs.chmodSync(archive, 0o600);
+        const stat = assertSafeRegularFile(archive, 0o600, { allowEmpty: false, role: 'SmartGo对象存储备份' });
+        entries.push({ dataset: 'smartgo-object-store:objects', kind: 'smartgo-object-store', file, size: stat.size, digest: hashFile(archive) });
+
+        smartgoBackupPhase = 'validating-object-archive';
+        validateSmartGoObjectArchive(archive, runner);
+
+        smartgoBackupPhase = 'restoring-runtime';
+        smartgoRecovery = restoreSmartGoProfileRuntime({
+          repositoryRoot, root, profile, env, environment: processEnvironment, runner, waiter,
+          unpauseRequired: smartgoObjectStoreRecoveryRequired,
+        });
+        invariant(
+          smartgoRecovery.profile.status === 'restored',
+          'IDP_SMARTGO_RUNTIME_RECOVERY_EXHAUSTED',
+          'SmartGo备份数据已生成，但完整原Profile未能在有界健康等待内恢复',
+        );
+        smartgoObjectStoreRecoveryRequired = false;
+        smartgoRuntimeRecoveryRequired = false;
+        smartgoBackupPhase = 'complete';
+      }
+      const entriesByDataset = new Map(entries.map((entry) => [entry.dataset, entry]));
+      invariant(entriesByDataset.size === entries.length && datasets.every((dataset) => entriesByDataset.has(dataset)), 'IDP_BACKUP_DATASET_INCOMPLETE', '备份数据集未完整生成或包含重复项');
+      const orderedEntries = datasets.map((dataset) => entriesByDataset.get(dataset));
+      const body = {
+        schemaVersion: 1,
+        generationId,
+        profile,
+        configDigest: report.digest,
+        renderDigest: rendered.manifest.digest,
+        expectedDatasets: datasets,
+        techBoundary,
+        files: orderedEntries,
+        createdAt: new Date().toISOString(),
+      };
+      const manifest = { ...body, manifestDigest: sha256(stableJson(body)) };
+      createExclusiveFile(path.join(staging, 'generation.json'), `${JSON.stringify(manifest, null, 2)}\n`, 0o600);
+      publishGeneration(staging, target);
+      published = true;
+      return writeReceipt(env, 'backup', { generationId, profile, target, configDigest: report.digest, manifestDigest: manifest.manifestDigest });
+    } catch (error) {
+      if (techStopped) {
+        try { runner('docker', composeArgs(repositoryRoot, root, profile, ['up', '-d', '--wait', 'tech'], { projectName: env.IDP_INSTANCE_ID }), { env: processEnvironment }); } catch {}
+      }
+      if (registryPaused) {
+        try { runner('docker', composeArgs(repositoryRoot, root, profile, ['unpause', 'registry'], { projectName: env.IDP_INSTANCE_ID }), { env: processEnvironment }); } catch {}
+      }
+      const originalErrorCode = safeErrorCode(error, 'IDP_BACKUP_FAILED');
+      const recovery = smartgoRecovery ?? (
+        smartgoRuntimeRecoveryRequired
+          ? restoreSmartGoProfileRuntime({
+            repositoryRoot, root, profile, env, environment: processEnvironment, runner, waiter,
+            unpauseRequired: smartgoObjectStoreRecoveryRequired,
+          })
+          : emptySmartGoRecovery(profile)
+      );
+      const source = published ? target : staging;
+      let failedTarget;
+      if (fs.existsSync(source)) {
+        failedTarget = path.join(backupFailedRoot, `${generationId}-${crypto.randomUUID()}`);
+        fs.renameSync(source, failedTarget);
+        if (active.has('smartgo')) {
+          const failedBody = {
+            schemaVersion: 'idp.smartgo-backup-failure/v2', generationId, profile,
+            failedAt: new Date().toISOString(), phase: smartgoBackupPhase, originalErrorCode, recovery,
+          };
+          createExclusiveFile(path.join(failedTarget, 'backup-failure.json'), `${JSON.stringify({ ...failedBody, digest: sha256(stableJson(failedBody)) }, null, 2)}\n`, 0o600);
+        }
+      }
+      const recoveryFailed = smartgoRuntimeRecoveryRequired && recovery.profile.status !== 'restored';
+      if (recoveryFailed) {
+        throw new IdpError('IDP_SMARTGO_BACKUP_RECOVERY_FAILED', 'SmartGo备份失败且完整原Profile未能在有界健康等待内恢复，请按失败证据执行人工恢复', {
+          failedTarget, phase: smartgoBackupPhase, originalErrorCode,
+          recoveryErrorCode: recovery.profile.errorCode,
+        });
+      }
+      throw error;
+    }
+  }, { lease: instanceLease });
+}
+
+function validateManifest(manifest, generationId) {
+  const allowedKeys = ['schemaVersion', 'generationId', 'profile', 'configDigest', 'renderDigest', 'expectedDatasets', 'techBoundary', 'files', 'createdAt', 'manifestDigest'];
+  const validObject = manifest && typeof manifest === 'object' && !Array.isArray(manifest) && stableJson(Object.keys(manifest).sort()) === stableJson([...allowedKeys].sort());
+  let expected;
+  try { expected = profileDatasets(manifest?.profile).datasets; } catch { expected = undefined; }
+  const timestamp = typeof manifest?.createdAt === 'string' ? new Date(manifest.createdAt) : new Date(Number.NaN);
+  const uniqueDatasets = Array.isArray(manifest?.expectedDatasets) && new Set(manifest.expectedDatasets).size === manifest.expectedDatasets.length;
+  const exactDatasets = uniqueDatasets && expected && expected.length === manifest.expectedDatasets.length && expected.every((value, index) => manifest.expectedDatasets[index] === value);
+  const { manifestDigest, ...body } = validObject ? manifest : {};
+  const expectsTechBoundary = (() => { try { return resolveProfile(manifest?.profile).includes('tech'); } catch { return false; } })();
+  if (expectsTechBoundary) {
+    exactObjectKeys(manifest.techBoundary, ['contract', 'file', 'size', 'fileDigest', 'factsDigest'], 'IDP_BACKUP_MANIFEST_INVALID', 'Tech备份边界描述');
+    invariant(manifest.techBoundary.contract === 'tech.backup-boundary.v1' && manifest.techBoundary.file === TECH_BACKUP_BOUNDARY_FILE && Number.isSafeInteger(manifest.techBoundary.size) && manifest.techBoundary.size > 0 && /^sha256:[0-9a-f]{64}$/u.test(manifest.techBoundary.fileDigest ?? '') && /^sha256:[0-9a-f]{64}$/u.test(manifest.techBoundary.factsDigest ?? ''), 'IDP_BACKUP_MANIFEST_INVALID', 'Tech备份边界描述无效');
+  } else invariant(manifest?.techBoundary === null, 'IDP_BACKUP_MANIFEST_INVALID', '不包含Tech的Profile不得声明Tech备份边界');
+  invariant(
+    validObject && manifest.schemaVersion === 1 && manifest.generationId === generationId &&
+    /^sha256:[0-9a-f]{64}$/u.test(manifest.configDigest ?? '') && /^sha256:[0-9a-f]{64}$/u.test(manifest.renderDigest ?? '') &&
+    !Number.isNaN(timestamp.getTime()) && timestamp.toISOString() === manifest.createdAt && exactDatasets &&
+    Array.isArray(manifest.files) && manifest.files.length === expected.length &&
+    /^sha256:[0-9a-f]{64}$/u.test(manifestDigest ?? '') && sha256(stableJson(body)) === manifestDigest,
+    'IDP_BACKUP_MANIFEST_INVALID', '备份代次清单契约或摘要无效',
+  );
+  return expected;
+}
+
+function readVerifiedGeneration(env, generationId) {
+  invariant(/^[0-9TZ-]+-[0-9a-f]{12}$/u.test(generationId), 'IDP_BACKUP_ID_INVALID', '备份代次ID格式无效');
+  const generationRoot = resolveContained(env.IDP_BACKUP_DIR, `generations/${generationId}`, '备份代次');
+  const stat = fs.lstatSync(generationRoot);
+  invariant(stat.isDirectory() && !stat.isSymbolicLink(), 'IDP_BACKUP_DIRECTORY_INVALID', '备份代次必须是普通目录');
+  const manifestPath = path.join(generationRoot, 'generation.json');
+  assertSafeRegularFile(manifestPath, 0o600, { allowEmpty: false, role: '备份代次清单' });
+  let manifest;
+  try { manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); }
+  catch { throw new IdpError('IDP_BACKUP_MANIFEST_INVALID', '备份代次清单不是有效JSON'); }
+  const expectedDatasets = validateManifest(manifest, generationId);
+  const seenFiles = new Set();
+  const seenDatasets = new Set();
+  const verified = [];
+  for (const entry of manifest.files) {
+    const databaseEntry = entry?.kind === 'postgresql';
+    const allowedEntryKeys = databaseEntry ? ['dataset', 'kind', 'database', 'file', 'size', 'digest'] : ['dataset', 'kind', 'file', 'size', 'digest'];
+    invariant(
+      entry && typeof entry === 'object' && !Array.isArray(entry) && Object.keys(entry).every((key) => allowedEntryKeys.includes(key)) &&
+      ['postgresql', 'registry', 'smartgo-object-store'].includes(entry.kind) && expectedDatasets.includes(entry.dataset) && !seenDatasets.has(entry.dataset) &&
+      entry.file && path.basename(entry.file) === entry.file && !seenFiles.has(entry.file) &&
+      Number.isSafeInteger(entry.size) && entry.size > 0 && /^sha256:[0-9a-f]{64}$/u.test(entry.digest ?? ''),
+      'IDP_BACKUP_ENTRY_INVALID', '备份文件条目无效',
+    );
+    if (databaseEntry) invariant(ROLE_BY_DATABASE[entry.database] && entry.dataset === `postgresql:${entry.database}` && entry.file === `${entry.database}.dump`, 'IDP_BACKUP_ENTRY_INVALID', 'PostgreSQL备份条目无效');
+    else if (entry.kind === 'registry') invariant(entry.dataset === 'registry:packages' && entry.file === 'registry.tar.gz' && !('database' in entry), 'IDP_BACKUP_ENTRY_INVALID', 'Registry备份条目无效');
+    else invariant(entry.dataset === 'smartgo-object-store:objects' && entry.file === 'smartgo-object-store.tar.gz' && !('database' in entry), 'IDP_BACKUP_ENTRY_INVALID', 'SmartGo对象存储备份条目无效');
+    seenFiles.add(entry.file);
+    seenDatasets.add(entry.dataset);
+    const candidate = path.join(generationRoot, entry.file);
+    const fileStat = assertSafeRegularFile(candidate, 0o600, { allowEmpty: false, role: `备份文件${entry.file}` });
+    invariant(fileStat.size === entry.size, 'IDP_BACKUP_SIZE_MISMATCH', `备份文件大小不匹配：${entry.file}`);
+    const actual = hashFile(candidate);
+    invariant(actual === entry.digest, 'IDP_BACKUP_DIGEST_MISMATCH', `备份文件摘要不匹配：${entry.file}`);
+    verified.push({ dataset: entry.dataset, file: entry.file, size: entry.size, digest: actual });
+  }
+  invariant(expectedDatasets.every((dataset) => seenDatasets.has(dataset)), 'IDP_BACKUP_MANIFEST_INCOMPLETE', '备份数据集不完整');
+  const expectedNames = new Set(['generation.json', ...seenFiles]);
+  let techBoundary;
+  if (manifest.techBoundary) {
+    const candidate = path.join(generationRoot, manifest.techBoundary.file);
+    const boundaryStat = assertSafeRegularFile(candidate, 0o600, { allowEmpty: false, role: 'Tech备份边界文件' });
+    invariant(boundaryStat.size === manifest.techBoundary.size && hashFile(candidate) === manifest.techBoundary.fileDigest, 'IDP_TECH_BACKUP_BOUNDARY_FILE_MISMATCH', 'Tech备份边界文件大小或摘要不匹配');
+    try { techBoundary = validateTechBackupBoundary(JSON.parse(fs.readFileSync(candidate, 'utf8'))); }
+    catch (error) { if (error instanceof IdpError) throw error; throw new IdpError('IDP_TECH_BACKUP_BOUNDARY_JSON_INVALID', 'Tech备份边界文件不是有效JSON'); }
+    invariant(techBoundary.digest === manifest.techBoundary.factsDigest, 'IDP_TECH_BACKUP_BOUNDARY_DIGEST_MISMATCH', 'Tech备份边界事实摘要与Generation不一致');
+    expectedNames.add(manifest.techBoundary.file);
+  }
+  for (const name of fs.readdirSync(generationRoot)) invariant(expectedNames.has(name), 'IDP_BACKUP_FILE_UNDECLARED', `备份代次包含清单外文件：${name}`);
+  const evidence = findBackupEvidence(env, generationId, manifest.manifestDigest);
+  return { generationRoot, manifest, verified, evidence, techBoundary };
+}
+
+export function verifyBackup({ configRoot, generationId, instanceLease }) {
+  const { root, env } = doctorConfig(configRoot, { requireConfigured: false, profile: 'registry' });
+  return withInstanceLock(root, env, 'backup:verify', () => {
+    const { manifest, verified, evidence, techBoundary } = readVerifiedGeneration(env, generationId);
+    return writeReceipt(env, 'backup-verify', { generationId, profile: manifest.profile, verified, techBoundaryDigest: techBoundary?.digest ?? null, creationEvidenceDigest: evidence.digest });
+  }, { lease: instanceLease });
+}
+
+function parseDatabaseAcceptance(stdout, database) {
+  const values = String(Buffer.isBuffer(stdout) ? stdout.toString('utf8') : stdout ?? '').trim().split('|');
+  const tableCount = Number(values[0]);
+  const ownedCount = Number(values[1]);
+  const canConnect = values[2] === 't';
+  invariant(Number.isInteger(tableCount) && tableCount > 0 && ownedCount === tableCount && canConnect, 'IDP_RESTORE_ACCEPTANCE_FAILED', `恢复后的${database}数据库未通过表、Owner与连接权限验收`);
+  return { tableCount, ownedCount, canConnect };
+}
+
+function acceptanceQuery(role) {
+  return `SELECT count(*), count(*) FILTER (WHERE pg_get_userbyid(c.relowner)='${role}'), has_database_privilege('${role}', current_database(), 'CONNECT') FROM pg_catalog.pg_class c JOIN pg_catalog.pg_namespace n ON n.oid=c.relnamespace WHERE c.relkind='r' AND n.nspname NOT IN ('pg_catalog','information_schema');`;
+}
+
+function validateRegistryArchive(archive, runner = run) {
+  const namesResult = runner('tar', ['-tzf', archive], { capture: true });
+  const names = String(Buffer.isBuffer(namesResult.stdout) ? namesResult.stdout.toString('utf8') : namesResult.stdout ?? '').split(/\r?\n/u).filter(Boolean);
+  invariant(names.length > 0, 'IDP_REGISTRY_ARCHIVE_EMPTY', 'Registry归档为空');
+  for (const name of names) {
+    invariant(!path.isAbsolute(name), 'IDP_REGISTRY_ARCHIVE_UNSAFE', `Registry归档包含绝对路径：${name}`);
+    const normalized = path.posix.normalize(name.replace(/^\.\//u, ''));
+    invariant(normalized !== '..' && !normalized.startsWith('../'), 'IDP_REGISTRY_ARCHIVE_UNSAFE', `Registry归档包含路径逃逸：${name}`);
+  }
+  invariant(names.some((name) => /^\.\/?auth\/?$/u.test(name)) && names.some((name) => /^\.\/?packages\/?$/u.test(name)), 'IDP_REGISTRY_ARCHIVE_INCOMPLETE', 'Registry归档缺少auth或packages目录');
+  const verboseResult = runner('tar', ['-tvzf', archive], { capture: true });
+  const verbose = String(Buffer.isBuffer(verboseResult.stdout) ? verboseResult.stdout.toString('utf8') : verboseResult.stdout ?? '').split(/\r?\n/u).filter(Boolean);
+  invariant(verbose.length > 0 && verbose.every((line) => ['-', 'd'].includes(line[0])), 'IDP_REGISTRY_ARCHIVE_LINK_FORBIDDEN', 'Registry归档只能包含普通文件和目录，不得包含链接或特殊节点');
+  return { entries: names.length };
+}
+
+function validateSmartGoObjectArchive(archive, runner = run) {
+  const namesResult = runner('tar', ['-tzf', archive], { capture: true });
+  const names = String(Buffer.isBuffer(namesResult.stdout) ? namesResult.stdout.toString('utf8') : namesResult.stdout ?? '').split(/\r?\n/u).filter(Boolean);
+  invariant(names.length > 0, 'IDP_SMARTGO_OBJECT_ARCHIVE_EMPTY', 'SmartGo对象存储归档为空');
+  for (const name of names) {
+    invariant(!path.isAbsolute(name), 'IDP_SMARTGO_OBJECT_ARCHIVE_UNSAFE', `SmartGo对象存储归档包含绝对路径：${name}`);
+    const normalized = path.posix.normalize(name.replace(/^\.\//u, ''));
+    invariant(normalized !== '..' && !normalized.startsWith('../'), 'IDP_SMARTGO_OBJECT_ARCHIVE_UNSAFE', `SmartGo对象存储归档包含路径逃逸：${name}`);
+  }
+  const verboseResult = runner('tar', ['-tvzf', archive], { capture: true });
+  const verbose = String(Buffer.isBuffer(verboseResult.stdout) ? verboseResult.stdout.toString('utf8') : verboseResult.stdout ?? '').split(/\r?\n/u).filter(Boolean);
+  invariant(verbose.length > 0 && verbose.every((line) => ['-', 'd'].includes(line[0])) && verbose.some((line) => line[0] === '-'), 'IDP_SMARTGO_OBJECT_ARCHIVE_LINK_FORBIDDEN', 'SmartGo对象存储归档必须包含普通文件，且不得包含链接或特殊节点');
+  return { entries: names.length };
+}
+
+function restoreDatabaseEntries({ entries, generationRoot, compose, environment, runner, inputRunner, onRestoredDatabase }) {
+  const results = [];
+  for (const entry of entries) {
+    const role = ROLE_BY_DATABASE[entry.database];
+    const suffix = `${Date.now()}${Math.floor(Math.random() * 10000)}`.slice(-12);
+    const temporaryDatabase = `idpcheck_${entry.database}_${suffix}`.replace(/[^a-z0-9_]/gu, '').slice(0, 63);
+    let created = false;
+    try {
+      runner('docker', compose(['exec', '-T', '-u', 'postgres', 'postgresql', 'createdb', '--template=template0', '--owner', role, temporaryDatabase]), { env: environment });
+      created = true;
+      inputRunner('docker', compose(['exec', '-T', '-u', 'postgres', 'postgresql', 'pg_restore', '--exit-on-error', '--no-owner', '--no-privileges', '--role', role, '--dbname', temporaryDatabase]), path.join(generationRoot, entry.file), { capture: true, env: environment });
+      const accepted = runner('docker', compose(['exec', '-T', '-u', 'postgres', 'postgresql', 'psql', '--tuples-only', '--no-align', '--field-separator=|', '--dbname', temporaryDatabase, '--command', acceptanceQuery(role)]), { capture: true, env: environment });
+      const boundaryEvidence = onRestoredDatabase?.({ entry, database: temporaryDatabase }) ?? {};
+      results.push({ dataset: entry.dataset, database: entry.database, ...parseDatabaseAcceptance(accepted.stdout, entry.database), ...boundaryEvidence, status: 'passed' });
+    } finally {
+      if (created) runner('docker', compose(['exec', '-T', '-u', 'postgres', 'postgresql', 'dropdb', '--if-exists', '--force', temporaryDatabase]), { env: environment });
+    }
+  }
+  return results;
+}
+
+export function testRestore({ repositoryRoot, configRoot, generationId, instanceLease, runner = run, inputRunner = runFromFile, allowLegacyImageLock = false }) {
+  const preliminary = doctorConfig(configRoot, { requireConfigured: false, profile: 'registry' });
+  return withInstanceLock(preliminary.root, preliminary.env, 'restore:test', () => {
+    const { generationRoot, manifest, evidence, techBoundary } = readVerifiedGeneration(preliminary.env, generationId);
+    const { root, env, report } = doctorConfig(configRoot, { requireConfigured: true, profile: manifest.profile, allowLegacyImageLock });
+    const active = new Set(resolveProfile(manifest.profile));
+    prepareState(root, env, active);
+    const rendered = renderRuntimeBundles(root, manifest.profile);
+    const environment = composeProcessEnvironment(root, rendered.target);
+    const compose = (command) => composeArgs(repositoryRoot, root, manifest.profile, command, { projectName: env.IDP_INSTANCE_ID });
+    const results = restoreDatabaseEntries({
+      entries: manifest.files.filter((entry) => entry.kind === 'postgresql'), generationRoot, compose, environment, runner, inputRunner,
+      onRestoredDatabase: ({ entry, database }) => {
+        if (entry.database !== 'tech') return {};
+        invariant(techBoundary, 'IDP_TECH_BACKUP_BOUNDARY_MISSING', 'Tech数据库备份缺少边界清单');
+        const restoredBoundary = runTechBoundaryForDatabase({ rendered, compose, environment, env, database, expectedDigest: techBoundary.digest, runner });
+        return { backupBoundaryDigest: restoredBoundary.digest, gitReleaseRefetch: 'external-evidence-required' };
+      },
+    });
+    const registryEntry = manifest.files.find((entry) => entry.kind === 'registry');
+    if (registryEntry) results.push({ dataset: registryEntry.dataset, ...validateRegistryArchive(path.join(generationRoot, registryEntry.file), runner), status: 'passed' });
+    const objectEntry = manifest.files.find((entry) => entry.kind === 'smartgo-object-store');
+    if (objectEntry) results.push({ dataset: objectEntry.dataset, ...validateSmartGoObjectArchive(path.join(generationRoot, objectEntry.file), runner), status: 'passed' });
+    invariant(results.length === manifest.expectedDatasets.length && manifest.expectedDatasets.every((dataset) => results.some((result) => result.dataset === dataset)), 'IDP_RESTORE_RESULTS_INCOMPLETE', '恢复验收结果与备份数据集不一致');
+    return writeReceipt(env, 'restore-test', { generationId, profile: manifest.profile, configDigest: report.digest, creationEvidenceDigest: evidence.digest, results });
+  }, { lease: instanceLease });
+}
+
+function waitForPostgresql(containerName, runner, waiter) {
+  let lastError;
+  for (let attempt = 0; attempt < 60; attempt += 1) {
+    try {
+      runner('docker', ['exec', containerName, 'pg_isready', '--username', 'postgres', '--dbname', 'postgres'], { capture: true });
+      return;
+    } catch (error) { lastError = error; waiter(500); }
+  }
+  throw new IdpError('IDP_RESTORE_POSTGRES_TIMEOUT', `恢复用PostgreSQL未能就绪：${lastError?.message ?? 'unknown'}`);
+}
+
+function defaultWaiter(milliseconds) {
+  const signal = new Int32Array(new SharedArrayBuffer(4));
+  Atomics.wait(signal, 0, 0, milliseconds);
+}
+
+export function applyRestore({ repositoryRoot, configRoot, generationId, runner = run, inputRunner = runFromFile, waiter = defaultWaiter }) {
+  const preliminary = doctorConfig(configRoot, { requireConfigured: false, profile: 'registry' });
+  return withInstanceLock(preliminary.root, preliminary.env, 'restore:apply', () => {
+    const { generationRoot, manifest, evidence } = readVerifiedGeneration(preliminary.env, generationId);
+    const { root, env, report } = doctorConfig(configRoot, { requireConfigured: true, profile: manifest.profile });
+    const candidateId = `${generationId}-${crypto.randomUUID()}`;
+    const candidatesRoot = secureDirectoryRoot(path.join(env.IDP_RESTORE_DIR, 'candidates'), 'Restore candidates', { create: true });
+    const failedRoot = secureDirectoryRoot(path.join(env.IDP_RESTORE_DIR, 'failed'), 'Restore failed', { create: true });
+    const candidateRoot = path.join(candidatesRoot, candidateId);
+    fs.mkdirSync(candidateRoot, { recursive: false, mode: 0o700 });
+    const containerName = `${env.IDP_INSTANCE_ID}-restore-${crypto.randomUUID().slice(0, 8)}`;
+    let containerCreated = false;
+    try {
+      const results = [];
+      const registryEntry = manifest.files.find((entry) => entry.kind === 'registry');
+      if (registryEntry) {
+        const archive = path.join(generationRoot, registryEntry.file);
+        const archiveCheck = validateRegistryArchive(archive, runner);
+        const registryRoot = path.join(candidateRoot, 'registry');
+        fs.mkdirSync(registryRoot, { mode: 0o700 });
+        runner('tar', ['-xzf', archive, '-C', registryRoot]);
+        results.push({ dataset: registryEntry.dataset, ...archiveCheck, status: 'restored' });
+      }
+      const objectEntry = manifest.files.find((entry) => entry.kind === 'smartgo-object-store');
+      if (objectEntry) {
+        const archive = path.join(generationRoot, objectEntry.file);
+        const archiveCheck = validateSmartGoObjectArchive(archive, runner);
+        const objectRoot = path.join(candidateRoot, 'smartgo', 'object-store');
+        fs.mkdirSync(objectRoot, { recursive: true, mode: 0o700 });
+        runner('tar', ['-xzf', archive, '-C', objectRoot]);
+        results.push({ dataset: objectEntry.dataset, ...archiveCheck, status: 'restored' });
+      }
+      const databaseEntries = manifest.files.filter((entry) => entry.kind === 'postgresql');
+      if (databaseEntries.length > 0) {
+        const postgresqlRoot = path.join(candidateRoot, 'postgresql');
+        fs.mkdirSync(postgresqlRoot, { mode: 0o700 });
+        const mount = (source, target, readonly = false) => `type=bind,source=${source},target=${target}${readonly ? ',readonly' : ''}`;
+        const dockerArgs = [
+          'run', '--detach', '--name', containerName, '--security-opt', 'no-new-privileges:true',
+          '--env', 'POSTGRES_USER=postgres', '--env', 'POSTGRES_PASSWORD_FILE=/run/secrets/postgresql-superuser-password',
+          '--env', 'POSTGRES_INITDB_ARGS=--encoding=UTF8 --auth-host=scram-sha-256 --auth-local=peer',
+          '--mount', mount(postgresqlRoot, '/var/lib/postgresql/data'),
+          '--mount', mount(resolveContained(root, env.IDP_POSTGRES_SUPERUSER_PASSWORD_FILE), '/run/secrets/postgresql-superuser-password', true),
+          '--mount', mount(resolveContained(root, env.IDP_POSTGRES_TECH_PASSWORD_FILE), '/run/secrets/postgresql-tech-password', true),
+          '--mount', mount(resolveContained(root, env.IDP_POSTGRES_PORTAL_PASSWORD_FILE), '/run/secrets/postgresql-portal-password', true),
+          '--mount', mount(resolveContained(root, env.IDP_POSTGRES_SMARTGO_PASSWORD_FILE), '/run/secrets/postgresql-smartgo-password', true),
+          '--mount', mount(path.join(repositoryRoot, 'scripts/postgresql/010-create-databases.sh'), '/docker-entrypoint-initdb.d/010-create-databases.sh', true),
+          env.IDP_POSTGRES_IMAGE,
+        ];
+        runner('docker', dockerArgs, { capture: true });
+        containerCreated = true;
+        waitForPostgresql(containerName, runner, waiter);
+        for (const entry of databaseEntries) {
+          const role = ROLE_BY_DATABASE[entry.database];
+          inputRunner('docker', ['exec', '-i', '-u', 'postgres', containerName, 'pg_restore', '--exit-on-error', '--no-owner', '--no-privileges', '--role', role, '--dbname', entry.database], path.join(generationRoot, entry.file), { capture: true });
+          const accepted = runner('docker', ['exec', '-i', '-u', 'postgres', containerName, 'psql', '--tuples-only', '--no-align', '--field-separator=|', '--dbname', entry.database, '--command', acceptanceQuery(role)], { capture: true });
+          results.push({ dataset: entry.dataset, database: entry.database, ...parseDatabaseAcceptance(accepted.stdout, entry.database), status: 'restored' });
+        }
+        runner('docker', ['stop', '--time', '60', containerName], { capture: true });
+        runner('docker', ['rm', containerName], { capture: true });
+        containerCreated = false;
+        assertSafeRegularFile(path.join(postgresqlRoot, 'PG_VERSION'), 0o644, { allowEmpty: false, role: '恢复候选PG_VERSION' });
+      }
+      invariant(results.length === manifest.expectedDatasets.length, 'IDP_RESTORE_RESULTS_INCOMPLETE', '恢复候选未覆盖全部数据集');
+      const dataDigest = digestCandidateData(candidateRoot);
+      const candidateBody = {
+        schemaVersion: 1, candidateId, generationId, profile: manifest.profile, status: 'ready-for-cutover',
+        preimage: { targetExisted: false, productionDataUntouched: true }, creationEvidenceDigest: evidence.digest,
+        configDigest: report.digest, dataDigest, results, createdAt: new Date().toISOString(),
+      };
+      const candidate = { ...candidateBody, digest: sha256(stableJson(candidateBody)) };
+      createExclusiveFile(path.join(candidateRoot, 'candidate.json'), `${JSON.stringify(candidate, null, 2)}\n`, 0o600);
+      return writeReceipt(env, 'restore-apply', { generationId, profile: manifest.profile, candidateId, candidateRoot, candidateDigest: candidate.digest, creationEvidenceDigest: evidence.digest });
+    } catch (error) {
+      if (containerCreated) {
+        try { runner('docker', ['rm', '--force', containerName], { capture: true }); } catch {}
+      }
+      if (fs.existsSync(candidateRoot)) fs.renameSync(candidateRoot, path.join(failedRoot, candidateId));
+      throw error;
+    }
+  });
+}
+
+function assertTreeWithoutLinks(root, role) {
+  const rootStat = fs.lstatSync(root);
+  invariant(rootStat.isDirectory() && !rootStat.isSymbolicLink(), 'IDP_RESTORE_CANDIDATE_INVALID', `${role}必须是普通目录`);
+  const stack = [root];
+  while (stack.length > 0) {
+    const directory = stack.pop();
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const candidate = path.join(directory, entry.name);
+      const stat = fs.lstatSync(candidate);
+      invariant(!stat.isSymbolicLink(), 'IDP_RESTORE_CANDIDATE_LINK_FORBIDDEN', `${role}不得包含符号链接：${candidate}`);
+      invariant(stat.isDirectory() || stat.isFile(), 'IDP_RESTORE_CANDIDATE_NODE_INVALID', `${role}只能包含目录和普通文件：${candidate}`);
+      if (stat.isDirectory()) stack.push(candidate);
+    }
+  }
+}
+
+function candidateDataInventory(root, topLevels) {
+  assertTreeWithoutLinks(root, '恢复候选数据');
+  const inventory = inventoryDirectory(root).filter((entry) => {
+    if (entry.path === 'candidate.json') return false;
+    return !topLevels || topLevels.has(entry.path.split(path.sep)[0]);
+  });
+  invariant(inventory.every((entry) => !entry.unsupported), 'IDP_RESTORE_CANDIDATE_NODE_INVALID', '恢复候选数据只能包含目录和普通文件');
+  return inventory;
+}
+
+function digestCandidateData(root, topLevels) {
+  return sha256(stableJson(candidateDataInventory(root, topLevels)));
+}
+
+function digestSubdirectoryAsCandidate(root, prefix) {
+  assertTreeWithoutLinks(root, `恢复候选${prefix}数据`);
+  const inventory = inventoryDirectory(root).map((entry) => ({ ...entry, path: path.join(prefix, entry.path) }));
+  invariant(inventory.every((entry) => !entry.unsupported), 'IDP_RESTORE_CANDIDATE_NODE_INVALID', '恢复候选数据只能包含目录和普通文件');
+  return sha256(stableJson(inventory));
+}
+
+function exactObjectKeys(value, expected, code, role) {
+  invariant(value && typeof value === 'object' && !Array.isArray(value), code, `${role}必须是对象`);
+  const actual = Object.keys(value).sort();
+  invariant(stableJson(actual) === stableJson([...expected].sort()), code, `${role}字段集合无效`);
+}
+
+function readRestoreCandidate(env, candidateId) {
+  invariant(/^[0-9TZ-]+-[0-9a-f]{12}-[0-9a-f-]{36}$/u.test(candidateId), 'IDP_RESTORE_CANDIDATE_ID_INVALID', '恢复候选ID格式无效');
+  const candidateRoot = resolveContained(env.IDP_RESTORE_DIR, `candidates/${candidateId}`, '恢复候选');
+  assertTreeWithoutLinks(candidateRoot, '恢复候选');
+  const documentPath = path.join(candidateRoot, 'candidate.json');
+  assertSafeRegularFile(documentPath, 0o600, { allowEmpty: false, role: '恢复候选清单' });
+  let document;
+  try { document = JSON.parse(fs.readFileSync(documentPath, 'utf8')); }
+  catch { throw new IdpError('IDP_RESTORE_CANDIDATE_INVALID', '恢复候选清单不是有效JSON'); }
+  const allowedKeys = ['schemaVersion', 'candidateId', 'generationId', 'profile', 'status', 'preimage', 'creationEvidenceDigest', 'configDigest', 'dataDigest', 'results', 'createdAt', 'digest'];
+  exactObjectKeys(document, allowedKeys, 'IDP_RESTORE_CANDIDATE_INVALID', '恢复候选清单');
+  exactObjectKeys(document.preimage, ['targetExisted', 'productionDataUntouched'], 'IDP_RESTORE_CANDIDATE_INVALID', '恢复候选Preimage');
+  const { digest, ...body } = document;
+  const { datasets } = profileDatasets(document?.profile);
+  const resultDatasets = Array.isArray(document?.results) ? document.results.map((entry) => entry?.dataset) : [];
+  if (Array.isArray(document.results)) {
+    for (const result of document.results) {
+      if (result?.dataset?.startsWith('postgresql:')) {
+        exactObjectKeys(result, ['dataset', 'database', 'tableCount', 'ownedCount', 'canConnect', 'status'], 'IDP_RESTORE_CANDIDATE_INVALID', 'PostgreSQL恢复结果');
+        invariant(ROLE_BY_DATABASE[result.database] && result.dataset === `postgresql:${result.database}` && Number.isSafeInteger(result.tableCount) && result.tableCount > 0 && result.ownedCount === result.tableCount && result.canConnect === true && result.status === 'restored', 'IDP_RESTORE_CANDIDATE_INVALID', 'PostgreSQL恢复结果无效');
+      } else if (result?.dataset === 'registry:packages') {
+        exactObjectKeys(result, ['dataset', 'entries', 'status'], 'IDP_RESTORE_CANDIDATE_INVALID', 'Registry恢复结果');
+        invariant(result.dataset === 'registry:packages' && Number.isSafeInteger(result.entries) && result.entries > 0 && result.status === 'restored', 'IDP_RESTORE_CANDIDATE_INVALID', 'Registry恢复结果无效');
+      } else {
+        exactObjectKeys(result, ['dataset', 'entries', 'status'], 'IDP_RESTORE_CANDIDATE_INVALID', 'SmartGo对象存储恢复结果');
+        invariant(result.dataset === 'smartgo-object-store:objects' && Number.isSafeInteger(result.entries) && result.entries > 0 && result.status === 'restored', 'IDP_RESTORE_CANDIDATE_INVALID', 'SmartGo对象存储恢复结果无效');
+      }
+    }
+  }
+  invariant(
+    document.schemaVersion === 1 && document.candidateId === candidateId && document.status === 'ready-for-cutover' &&
+    document.preimage?.targetExisted === false && document.preimage?.productionDataUntouched === true &&
+    /^sha256:[0-9a-f]{64}$/u.test(document.creationEvidenceDigest ?? '') && /^sha256:[0-9a-f]{64}$/u.test(document.configDigest ?? '') && /^sha256:[0-9a-f]{64}$/u.test(document.dataDigest ?? '') &&
+    Array.isArray(document.results) && new Set(resultDatasets).size === resultDatasets.length && resultDatasets.length === datasets.length && datasets.every((dataset) => resultDatasets.includes(dataset)) &&
+    /^sha256:[0-9a-f]{64}$/u.test(digest ?? '') && sha256(stableJson(body)) === digest,
+    'IDP_RESTORE_CANDIDATE_INVALID', '恢复候选清单契约、数据集或摘要无效',
+  );
+  invariant(digestCandidateData(candidateRoot) === document.dataDigest, 'IDP_RESTORE_CANDIDATE_DATA_MISMATCH', '恢复候选物理数据摘要不匹配');
+  if (datasets.some((dataset) => dataset.startsWith('postgresql:'))) {
+    assertSafeRegularFile(path.join(candidateRoot, 'postgresql', 'PG_VERSION'), 0o644, { allowEmpty: false, role: '恢复候选PG_VERSION' });
+  }
+  if (datasets.includes('registry:packages')) {
+    for (const directory of ['registry/auth', 'registry/packages']) {
+      const stat = fs.lstatSync(path.join(candidateRoot, directory));
+      invariant(stat.isDirectory() && !stat.isSymbolicLink(), 'IDP_RESTORE_CANDIDATE_INVALID', `恢复候选缺少${directory}`);
+    }
+  }
+  if (datasets.includes('smartgo-object-store:objects')) {
+    const objectRoot = path.join(candidateRoot, 'smartgo', 'object-store');
+    const objectStat = fs.lstatSync(objectRoot);
+    invariant(objectStat.isDirectory() && !objectStat.isSymbolicLink(), 'IDP_RESTORE_CANDIDATE_INVALID', '恢复候选缺少SmartGo对象存储目录');
+  }
+  const evidence = findRestoreApplyEvidence(env, candidateId, document.digest);
+  return { candidateRoot, document, evidence };
+}
+
+export function verifyRestoreCandidate({ configRoot, candidateId }) {
+  const { root, env } = doctorConfig(configRoot, { requireConfigured: false, profile: 'registry' });
+  return withInstanceLock(root, env, 'restore:candidate-verify', () => {
+    const { candidateRoot, document } = readRestoreCandidate(env, candidateId);
+    return writeReceipt(env, 'restore-candidate-verify', { candidateId, candidateRoot, candidateDigest: document.digest, profile: document.profile });
+  });
+}
+
+function promotionDirectories(profile) {
+  const { datasets } = profileDatasets(profile);
+  const postgresqlDatasets = datasets.filter((dataset) => dataset.startsWith('postgresql:'));
+  if (postgresqlDatasets.length > 0) {
+    invariant(
+      postgresqlDatasets.includes('postgresql:tech') && postgresqlDatasets.includes('postgresql:backstage'),
+      'IDP_RESTORE_PARTIAL_POSTGRESQL_PROMOTION_FORBIDDEN',
+      '单数据库备份可用于隔离恢复演练，但不能替换共享PostgreSQL物理数据；生产切换必须使用同时包含tech与backstage的core/full备份',
+    );
+  }
+  const directories = [];
+  if (postgresqlDatasets.length > 0) directories.push('postgresql');
+  if (datasets.includes('registry:packages')) directories.push('registry');
+  if (datasets.includes('smartgo-object-store:objects')) directories.push('smartgo');
+  return directories;
+}
+
+function sqlIdentifier(value) {
+  invariant(/^[a-z][a-z0-9_]{0,62}$/u.test(value), 'IDP_DATABASE_IDENTIFIER_INVALID', `数据库标识符无效：${value}`);
+  return `"${value}"`;
+}
+
+function logicalDatabasePromotion({ repositoryRoot, root, env, report, candidateRoot, document, evidence, runner, inputRunner }) {
+  const { generationRoot, manifest, techBoundary } = readVerifiedGeneration(env, document.generationId);
+  const databaseEntries = manifest.files.filter((entry) => entry.kind === 'postgresql');
+  invariant(databaseEntries.length === 1 && !manifest.files.some((entry) => entry.kind === 'registry'), 'IDP_LOGICAL_PROMOTION_PROFILE_INVALID', '逻辑数据库切换只接受单数据库且不混合Registry的备份代次');
+  const entry = databaseEntries[0];
+  const role = ROLE_BY_DATABASE[entry.database];
+  const application = entry.database === 'tech' ? 'tech' : entry.database === 'smartgo' ? 'smartgo-api' : 'portal';
+  const state = readActiveProfileState(env);
+  const operationProfile = state?.status === 'active' ? state.profile : document.profile;
+  const operationServices = new Set(resolveProfile(operationProfile));
+  invariant(operationServices.has('postgresql') && operationServices.has(application), 'IDP_LOGICAL_PROMOTION_ACTIVE_PROFILE_INVALID', `当前活动Profile ${operationProfile}不包含${application}与PostgreSQL`);
+  const rendered = renderRuntimeBundles(root, operationProfile);
+  const environment = composeProcessEnvironment(root, rendered.target);
+  const compose = (command) => composeArgs(repositoryRoot, root, operationProfile, command, { projectName: env.IDP_INSTANCE_ID });
+  const suffix = crypto.randomUUID().replaceAll('-', '').slice(0, 12);
+  const restoreDatabase = `idp_restore_${entry.database}_${suffix}`.slice(0, 63);
+  const preimageDatabase = `idp_preimage_${entry.database}_${suffix}`.slice(0, 63);
+  const failedDatabase = `idp_failed_${entry.database}_${suffix}`.slice(0, 63);
+  const psql = (sql, options = {}) => runner('docker', compose(['exec', '-T', '-u', 'postgres', 'postgresql', 'psql', '--set', 'ON_ERROR_STOP=1', '--dbname', 'postgres', '--command', sql]), { capture: true, env: environment, ...options });
+  const terminate = (...databases) => psql(`SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname IN (${databases.map((name) => `'${name}'`).join(',')}) AND pid <> pg_backend_pid();`);
+  const planBody = {
+    schemaVersion: 1, planId: crypto.randomUUID(), operation: 'restore-promote-logical-database', candidateId: document.candidateId,
+    candidateDigest: document.digest, profile: document.profile, activeProfile: operationProfile, database: entry.database,
+    restoreDatabase, preimageDatabase, failedDatabase, configDigest: report.digest, createdAt: new Date().toISOString(),
+  };
+  const plan = { ...planBody, digest: sha256(stableJson(planBody)) };
+  const planPath = path.join(env.IDP_RUNTIME_DIR, 'evidence', `${plan.planId}-logical-database-promotion-plan.json`);
+  createExclusiveFile(planPath, `${JSON.stringify(plan, null, 2)}\n`, 0o600);
+  let restoreCreated = false;
+  let productionRenamed = false;
+  let replacementRenamed = false;
+  let servicesStopped = false;
+  try {
+    runner('docker', compose(['exec', '-T', '-u', 'postgres', 'postgresql', 'createdb', '--template=template0', '--owner', role, restoreDatabase]), { env: environment });
+    restoreCreated = true;
+    inputRunner('docker', compose(['exec', '-T', '-u', 'postgres', 'postgresql', 'pg_restore', '--exit-on-error', '--no-owner', '--no-privileges', '--role', role, '--dbname', restoreDatabase]), path.join(generationRoot, entry.file), { capture: true, env: environment });
+    const accepted = runner('docker', compose(['exec', '-T', '-u', 'postgres', 'postgresql', 'psql', '--tuples-only', '--no-align', '--field-separator=|', '--dbname', restoreDatabase, '--command', acceptanceQuery(role)]), { capture: true, env: environment });
+    const acceptance = parseDatabaseAcceptance(accepted.stdout, entry.database);
+    let restoredTechBoundary;
+    if (entry.database === 'tech') {
+      invariant(techBoundary, 'IDP_TECH_BACKUP_BOUNDARY_MISSING', 'Tech数据库备份缺少边界清单');
+      restoredTechBoundary = runTechBoundaryForDatabase({ rendered, compose, environment, env, database: restoreDatabase, expectedDigest: techBoundary.digest, runner });
+    }
+    const stopServices = entry.database === 'tech'
+      ? ['tech', 'flow', 'portal', 'edge'].filter((service) => operationServices.has(service))
+      : [application, ...(operationServices.has('edge') ? ['edge'] : [])];
+    runner('docker', compose(['stop', '--timeout', '60', ...stopServices]), { env: environment });
+    servicesStopped = true;
+    terminate(entry.database, restoreDatabase);
+    psql(`ALTER DATABASE ${sqlIdentifier(entry.database)} RENAME TO ${sqlIdentifier(preimageDatabase)};`);
+    productionRenamed = true;
+    psql(`ALTER DATABASE ${sqlIdentifier(restoreDatabase)} RENAME TO ${sqlIdentifier(entry.database)};`);
+    replacementRenamed = true;
+    if (entry.database === 'tech') {
+      runner('docker', compose(['up', '-d', '--wait', 'tech']), { env: environment });
+      servicesStopped = false;
+      const liveBoundary = runLiveTechBoundary(compose, environment, runner);
+      invariant(liveBoundary.digest === techBoundary.digest, 'IDP_TECH_RESTORE_BOUNDARY_MISMATCH', '切换后的Tech生产数据库与备份边界不一致');
+    }
+    runner('docker', compose(['up', '-d', '--wait']), { env: environment });
+    servicesStopped = false;
+    return writeReceipt(env, 'restore-promote', {
+      candidateId: document.candidateId, profile: document.profile, activeProfile: operationProfile,
+      candidateDigest: document.digest, creationEvidenceDigest: evidence.digest, planDigest: plan.digest,
+      replacementStrategy: 'logical-database-rename', database: entry.database, preimageDatabase,
+      acceptance, techBoundaryDigest: restoredTechBoundary?.digest ?? null,
+      gitReleaseRefetch: entry.database === 'tech' ? 'external-evidence-required' : null,
+      candidateRoot, status: 'promoted-and-healthy',
+    });
+  } catch (error) {
+    let rollbackError;
+    try {
+      if (replacementRenamed) {
+        if (!servicesStopped) {
+          runner('docker', compose(['stop', '--timeout', '60', ...stopServices]), { env: environment });
+          servicesStopped = true;
+        }
+        terminate(entry.database, preimageDatabase);
+        psql(`ALTER DATABASE ${sqlIdentifier(entry.database)} RENAME TO ${sqlIdentifier(failedDatabase)};`);
+        psql(`ALTER DATABASE ${sqlIdentifier(preimageDatabase)} RENAME TO ${sqlIdentifier(entry.database)};`);
+        productionRenamed = false;
+      } else if (productionRenamed) {
+        psql(`ALTER DATABASE ${sqlIdentifier(preimageDatabase)} RENAME TO ${sqlIdentifier(entry.database)};`);
+        productionRenamed = false;
+        if (restoreCreated) runner('docker', compose(['exec', '-T', '-u', 'postgres', 'postgresql', 'dropdb', '--if-exists', '--force', restoreDatabase]), { env: environment });
+      } else if (restoreCreated) {
+        runner('docker', compose(['exec', '-T', '-u', 'postgres', 'postgresql', 'dropdb', '--if-exists', '--force', restoreDatabase]), { env: environment });
+      }
+      if (servicesStopped) runner('docker', compose(['up', '-d', '--wait']), { env: environment });
+    } catch (failure) { rollbackError = failure; }
+    if (rollbackError) throw new IdpError('IDP_LOGICAL_RESTORE_ROLLBACK_FAILED', `逻辑数据库切换失败且Preimage回滚未完成：${rollbackError.message}`, { originalError: error.message, preimageDatabase });
+    if (replacementRenamed) throw new IdpError('IDP_LOGICAL_RESTORE_ROLLED_BACK', `逻辑数据库切换失败，已恢复数据库Preimage：${error.message}`, { preimageDatabase, failedDatabase });
+    throw new IdpError('IDP_LOGICAL_RESTORE_PREPARE_FAILED', `逻辑数据库切换在生产重命名前失败：${error.message}`);
+  }
+}
+
+function smartGoCoordinatedPromotion({ repositoryRoot, root, env, report, candidateRoot, document, evidence, runner, inputRunner }) {
+  const { generationRoot, manifest } = readVerifiedGeneration(env, document.generationId);
+  const databaseEntries = manifest.files.filter((entry) => entry.kind === 'postgresql');
+  const objectEntries = manifest.files.filter((entry) => entry.kind === 'smartgo-object-store');
+  invariant(databaseEntries.length === 1 && databaseEntries[0].database === 'smartgo' && objectEntries.length === 1 && manifest.files.length === 2, 'IDP_SMARTGO_PROMOTION_PROFILE_INVALID', 'SmartGo协调切换只接受smartgo数据库与对象存储组成的完整备份代次');
+  const databaseEntry = databaseEntries[0];
+  const state = readActiveProfileState(env);
+  const operationProfile = state?.status === 'active' ? state.profile : document.profile;
+  const operationServices = new Set(resolveProfileServices(operationProfile));
+  invariant(operationServices.has('postgresql') && SMARTGO_WRITER_SERVICES.every((service) => operationServices.has(service)) && operationServices.has('smartgo-object-store'), 'IDP_SMARTGO_PROMOTION_ACTIVE_PROFILE_INVALID', `当前活动Profile ${operationProfile}不包含完整SmartGo运行边界`);
+  const rendered = renderRuntimeBundles(root, operationProfile);
+  const environment = composeProcessEnvironment(root, rendered.target);
+  const compose = (command) => composeArgs(repositoryRoot, root, operationProfile, command, { projectName: env.IDP_INSTANCE_ID });
+  const suffix = crypto.randomUUID().replaceAll('-', '').slice(0, 12);
+  const restoreDatabase = `idp_restore_smartgo_${suffix}`.slice(0, 63);
+  const preimageDatabase = `idp_preimage_smartgo_${suffix}`.slice(0, 63);
+  const failedDatabase = `idp_failed_smartgo_${suffix}`.slice(0, 63);
+  const psql = (sql, options = {}) => runner('docker', compose(['exec', '-T', '-u', 'postgres', 'postgresql', 'psql', '--set', 'ON_ERROR_STOP=1', '--dbname', 'postgres', '--command', sql]), { capture: true, env: environment, ...options });
+  const terminate = (...databases) => psql(`SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname IN (${databases.map((name) => `'${name}'`).join(',')}) AND pid <> pg_backend_pid();`);
+  const sourceSmartGo = path.join(candidateRoot, 'smartgo');
+  const dataRoot = env.IDP_DATA_DIR;
+  const productionSmartGo = path.join(dataRoot, 'smartgo');
+  const stagingSmartGo = path.join(dataRoot, `.smartgo-restore-staging-${suffix}-${crypto.randomUUID()}`);
+  const preimageSmartGo = path.join(dataRoot, `smartgo.preimage-${suffix}-${crypto.randomUUID()}`);
+  const failedSmartGo = path.join(dataRoot, `smartgo.failed-${suffix}-${crypto.randomUUID()}`);
+  assertTreeWithoutLinks(sourceSmartGo, 'SmartGo恢复候选对象数据');
+  const planBody = {
+    schemaVersion: 1, planId: crypto.randomUUID(), operation: 'restore-promote-smartgo-coordinated', candidateId: document.candidateId,
+    candidateDigest: document.digest, profile: document.profile, activeProfile: operationProfile,
+    database: 'smartgo', restoreDatabase, preimageDatabase, failedDatabase,
+    productionSmartGo, stagingSmartGo, preimageSmartGo, failedSmartGo,
+    configDigest: report.digest, createdAt: new Date().toISOString(),
+  };
+  const plan = { ...planBody, digest: sha256(stableJson(planBody)) };
+  createExclusiveFile(path.join(env.IDP_RUNTIME_DIR, 'evidence', `${plan.planId}-smartgo-promotion-plan.json`), `${JSON.stringify(plan, null, 2)}\n`, 0o600);
+  let restoreCreated = false;
+  let servicesStopped = false;
+  let productionDatabaseRenamed = false;
+  let replacementDatabaseRenamed = false;
+  let productionObjectsRenamed = false;
+  let replacementObjectsInstalled = false;
+  try {
+    fs.cpSync(sourceSmartGo, stagingSmartGo, { recursive: true, errorOnExist: true, preserveTimestamps: true });
+    fs.chmodSync(stagingSmartGo, 0o700);
+    assertTreeWithoutLinks(stagingSmartGo, 'SmartGo恢复暂存对象数据');
+    invariant(stableJson(inventoryDirectory(stagingSmartGo)) === stableJson(inventoryDirectory(sourceSmartGo)), 'IDP_SMARTGO_RESTORE_STAGING_DIGEST_MISMATCH', 'SmartGo对象存储暂存副本与已验证候选不一致');
+    runner('docker', compose(['exec', '-T', '-u', 'postgres', 'postgresql', 'createdb', '--template=template0', '--owner', 'smartgo', restoreDatabase]), { env: environment });
+    restoreCreated = true;
+    inputRunner('docker', compose(['exec', '-T', '-u', 'postgres', 'postgresql', 'pg_restore', '--exit-on-error', '--no-owner', '--no-privileges', '--role', 'smartgo', '--dbname', restoreDatabase]), path.join(generationRoot, databaseEntry.file), { capture: true, env: environment });
+    const accepted = runner('docker', compose(['exec', '-T', '-u', 'postgres', 'postgresql', 'psql', '--tuples-only', '--no-align', '--field-separator=|', '--dbname', restoreDatabase, '--command', acceptanceQuery('smartgo')]), { capture: true, env: environment });
+    const acceptance = parseDatabaseAcceptance(accepted.stdout, 'smartgo');
+    runner('docker', compose(['stop', '--timeout', '60', ...SMARTGO_WRITER_SERVICES, 'smartgo-object-store']), { env: environment });
+    servicesStopped = true;
+    terminate('smartgo', restoreDatabase);
+    psql(`ALTER DATABASE ${sqlIdentifier('smartgo')} RENAME TO ${sqlIdentifier(preimageDatabase)};`);
+    productionDatabaseRenamed = true;
+    psql(`ALTER DATABASE ${sqlIdentifier(restoreDatabase)} RENAME TO ${sqlIdentifier('smartgo')};`);
+    replacementDatabaseRenamed = true;
+    assertTreeWithoutLinks(productionSmartGo, 'SmartGo生产对象数据');
+    runner('sync', []);
+    fs.renameSync(productionSmartGo, preimageSmartGo);
+    productionObjectsRenamed = true;
+    fs.renameSync(stagingSmartGo, productionSmartGo);
+    replacementObjectsInstalled = true;
+    runner('docker', compose(['up', '-d', '--wait', 'smartgo-object-store', ...SMARTGO_WRITER_SERVICES]), { env: environment });
+    servicesStopped = false;
+    return writeReceipt(env, 'restore-promote', {
+      candidateId: document.candidateId, profile: document.profile, activeProfile: operationProfile,
+      candidateDigest: document.digest, creationEvidenceDigest: evidence.digest, planDigest: plan.digest,
+      replacementStrategy: 'smartgo-coordinated-database-object-cutover', database: 'smartgo', preimageDatabase,
+      objectPreimage: preimageSmartGo, acceptance, candidateRoot, status: 'promoted-and-healthy',
+    });
+  } catch (error) {
+    let rollbackError;
+    try {
+      if (!servicesStopped && (replacementDatabaseRenamed || replacementObjectsInstalled)) {
+        runner('docker', compose(['stop', '--timeout', '60', ...SMARTGO_WRITER_SERVICES, 'smartgo-object-store']), { env: environment });
+        servicesStopped = true;
+      }
+      if (replacementDatabaseRenamed) {
+        terminate('smartgo', preimageDatabase);
+        psql(`ALTER DATABASE ${sqlIdentifier('smartgo')} RENAME TO ${sqlIdentifier(failedDatabase)};`);
+        psql(`ALTER DATABASE ${sqlIdentifier(preimageDatabase)} RENAME TO ${sqlIdentifier('smartgo')};`);
+        productionDatabaseRenamed = false;
+      } else if (productionDatabaseRenamed) {
+        psql(`ALTER DATABASE ${sqlIdentifier(preimageDatabase)} RENAME TO ${sqlIdentifier('smartgo')};`);
+        productionDatabaseRenamed = false;
+      } else if (restoreCreated) {
+        runner('docker', compose(['exec', '-T', '-u', 'postgres', 'postgresql', 'dropdb', '--if-exists', '--force', restoreDatabase]), { env: environment });
+      }
+      if (replacementObjectsInstalled && fs.existsSync(productionSmartGo)) fs.renameSync(productionSmartGo, failedSmartGo);
+      if (productionObjectsRenamed && fs.existsSync(preimageSmartGo)) fs.renameSync(preimageSmartGo, productionSmartGo);
+      if (servicesStopped) runner('docker', compose(['up', '-d', '--wait', 'smartgo-object-store', ...SMARTGO_WRITER_SERVICES]), { env: environment });
+    } catch (rollbackFailure) { rollbackError = rollbackFailure; }
+    if (fs.existsSync(stagingSmartGo)) fs.rmSync(stagingSmartGo, { recursive: true, force: true });
+    if (rollbackError) throw new IdpError('IDP_SMARTGO_RESTORE_ROLLBACK_FAILED', `SmartGo协调切换失败且Preimage回滚未完成：${rollbackError.message}`, { originalError: error.message, preimageDatabase, preimageSmartGo });
+    if (replacementDatabaseRenamed || replacementObjectsInstalled) throw new IdpError('IDP_SMARTGO_RESTORE_ROLLED_BACK', `SmartGo协调切换失败，已恢复数据库与对象Preimage：${error.message}`, { preimageDatabase, preimageSmartGo });
+    throw new IdpError('IDP_SMARTGO_RESTORE_PREPARE_FAILED', `SmartGo协调切换在生产替换前失败：${error.message}`);
+  }
+}
+
+export function promoteRestore({ repositoryRoot, configRoot, candidateId, confirmation, runner = run, inputRunner = runFromFile }) {
+  invariant(confirmation === candidateId, 'IDP_RESTORE_CONFIRMATION_REQUIRED', '生产切换必须用--confirm提供完全相同的恢复候选ID');
+  const preliminary = doctorConfig(configRoot, { requireConfigured: false, profile: 'registry' });
+  return withInstanceLock(preliminary.root, preliminary.env, 'restore:promote', () => {
+    const { candidateRoot, document } = readRestoreCandidate(preliminary.env, candidateId);
+    const { root, env, report } = doctorConfig(configRoot, { requireConfigured: true, profile: document.profile });
+    invariant(document.configDigest === report.digest, 'IDP_RESTORE_CONFIG_DRIFT', '恢复候选创建后的配置已变化，必须基于当前配置重新执行restore apply');
+    const datasets = profileDatasets(document.profile).datasets;
+    if (document.profile === 'business-smartgo') {
+      return smartGoCoordinatedPromotion({ repositoryRoot, root, env, report, candidateRoot, document, evidence: findRestoreApplyEvidence(env, candidateId, document.digest), runner, inputRunner });
+    }
+    if (datasets.length === 1 && datasets[0].startsWith('postgresql:')) {
+      return logicalDatabasePromotion({ repositoryRoot, root, env, report, candidateRoot, document, evidence: findRestoreApplyEvidence(env, candidateId, document.digest), runner, inputRunner });
+    }
+    const active = new Set(resolveProfile(document.profile));
+    const verifiedGeneration = readVerifiedGeneration(env, document.generationId);
+    const replacementDirectories = promotionDirectories(document.profile);
+    const dataRoot = env.IDP_DATA_DIR;
+    const registryOnly = document.profile === 'registry';
+    const productionTarget = registryOnly ? path.join(dataRoot, 'registry') : dataRoot;
+    const parent = path.dirname(productionTarget);
+    const stamp = new Date().toISOString().replace(/[:.]/gu, '-');
+    const staging = path.join(parent, `.${path.basename(productionTarget)}.restore-staging-${crypto.randomUUID()}`);
+    const preimage = path.join(parent, `${path.basename(productionTarget)}.preimage-${stamp}-${crypto.randomUUID()}`);
+    const planBody = {
+      schemaVersion: 1, planId: crypto.randomUUID(), operation: 'restore-promote', candidateId,
+      candidateDigest: document.digest, profile: document.profile, dataRoot, productionTarget, staging, preimage,
+      replacementStrategy: registryOnly ? 'registry-directory' : 'complete-idp-data-root',
+      replacementDirectories,
+      preconditions: { confirmationMatched: true, candidateVerified: true, productionStoppedBeforeApply: true },
+      configDigest: report.digest, createdAt: new Date().toISOString(),
+    };
+    const plan = { ...planBody, digest: sha256(stableJson(planBody)) };
+    const planPath = path.join(env.IDP_RUNTIME_DIR, 'evidence', `${plan.planId}-restore-promotion-plan.json`);
+    createExclusiveFile(planPath, `${JSON.stringify(plan, null, 2)}\n`, 0o600);
+
+    const rendered = renderRuntimeBundles(root, document.profile);
+    const environment = composeProcessEnvironment(root, rendered.target);
+    const compose = (command) => composeArgs(repositoryRoot, root, document.profile, command, { projectName: env.IDP_INSTANCE_ID });
+    let productionMoved = false;
+    let replacementInstalled = false;
+    let servicesStopped = false;
+    try {
+      servicesStopped = true;
+      runner('docker', compose(['down']), { env: environment });
+      if (registryOnly) {
+        const source = path.join(candidateRoot, 'registry');
+        assertTreeWithoutLinks(productionTarget, '生产Registry数据');
+        assertTreeWithoutLinks(source, '恢复候选Registry数据');
+        fs.cpSync(source, staging, { recursive: true, errorOnExist: true, preserveTimestamps: true });
+        fs.chmodSync(staging, 0o700);
+        invariant(digestSubdirectoryAsCandidate(staging, 'registry') === document.dataDigest, 'IDP_RESTORE_STAGING_DIGEST_MISMATCH', '生产切换暂存数据与已验证恢复候选不一致');
+      } else {
+        assertTreeWithoutLinks(dataRoot, '生产数据根');
+        fs.cpSync(dataRoot, staging, { recursive: true, errorOnExist: true, preserveTimestamps: true });
+        fs.chmodSync(staging, 0o700);
+        for (const directory of replacementDirectories) {
+          const source = path.join(candidateRoot, directory);
+          const sourceStat = fs.lstatSync(source);
+          invariant(sourceStat.isDirectory() && !sourceStat.isSymbolicLink(), 'IDP_RESTORE_CANDIDATE_INVALID', `恢复候选缺少${directory}数据目录`);
+          const target = path.join(staging, directory);
+          if (fs.existsSync(target)) fs.rmSync(target, { recursive: true, force: true });
+          fs.cpSync(source, target, { recursive: true, errorOnExist: true, preserveTimestamps: true });
+        }
+        assertTreeWithoutLinks(staging, '生产切换暂存副本');
+        invariant(digestCandidateData(staging, new Set(replacementDirectories)) === document.dataDigest, 'IDP_RESTORE_STAGING_DIGEST_MISMATCH', '生产切换暂存数据与已验证恢复候选不一致');
+      }
+      runner('sync', []);
+      fs.renameSync(productionTarget, preimage);
+      productionMoved = true;
+      fs.renameSync(staging, productionTarget);
+      replacementInstalled = true;
+      ensureRuntimeRoots(root, env);
+      prepareState(root, env, active);
+      if (active.has('tech')) {
+        invariant(verifiedGeneration.techBoundary, 'IDP_TECH_BACKUP_BOUNDARY_MISSING', 'Tech数据库备份缺少边界清单');
+        runner('docker', compose(['up', '-d', '--wait', 'postgresql', 'tech']), { env: environment });
+        const liveBoundary = runLiveTechBoundary(compose, environment, runner);
+        invariant(liveBoundary.digest === verifiedGeneration.techBoundary.digest, 'IDP_TECH_RESTORE_BOUNDARY_MISMATCH', '切换后的Tech生产数据库与备份边界不一致');
+      }
+      runner('docker', compose(['up', '-d', '--wait']), { env: environment });
+      servicesStopped = false;
+      return writeReceipt(env, 'restore-promote', {
+        candidateId, profile: document.profile, candidateDigest: document.digest, planDigest: plan.digest,
+        preimage, productionTarget, replacementDirectories,
+        techBoundaryDigest: verifiedGeneration.techBoundary?.digest ?? null,
+        gitReleaseRefetch: active.has('tech') ? 'external-evidence-required' : null,
+        status: 'promoted-and-healthy',
+      });
+    } catch (error) {
+      let rollbackError;
+      try {
+        if (replacementInstalled) {
+          try { runner('docker', compose(['down']), { env: environment }); } catch {}
+          const failedReplacement = path.join(parent, `${path.basename(productionTarget)}.failed-restore-${stamp}-${crypto.randomUUID()}`);
+          if (fs.existsSync(productionTarget)) fs.renameSync(productionTarget, failedReplacement);
+        }
+        if (productionMoved && fs.existsSync(preimage)) fs.renameSync(preimage, productionTarget);
+        if (servicesStopped || productionMoved) {
+          ensureRuntimeRoots(root, env);
+          prepareState(root, env, active);
+          runner('docker', compose(['up', '-d', '--wait']), { env: environment });
+          servicesStopped = false;
+        }
+      } catch (rollbackFailure) { rollbackError = rollbackFailure; }
+      if (fs.existsSync(staging)) fs.rmSync(staging, { recursive: true, force: true });
+      if (rollbackError) throw new IdpError('IDP_RESTORE_ROLLBACK_FAILED', `恢复切换失败且生产Preimage回滚未完成：${rollbackError.message}`, { originalError: error.message, preimage });
+      if (!productionMoved) throw new IdpError('IDP_RESTORE_PROMOTION_PREPARE_FAILED', `恢复切换在替换生产数据前失败，原服务已恢复：${error.message}`);
+      throw new IdpError('IDP_RESTORE_PROMOTION_ROLLED_BACK', `恢复切换失败，已恢复生产Preimage：${error.message}`, { preimage });
+    }
+  });
+}
+
+function parseComposePs(stdout) {
+  const text = Buffer.isBuffer(stdout) ? stdout.toString('utf8') : String(stdout ?? '');
+  try {
+    const value = JSON.parse(text);
+    return Array.isArray(value) ? value : [value];
+  } catch {
+    return text.split(/\r?\n/u).filter(Boolean).map((line) => JSON.parse(line));
+  }
+}
+
+function netAuthority(address) {
+  return address.includes(':') && !address.startsWith('[') ? `[${address}]` : address;
+}
+
+function probeSmartGoApplication({ name, host, port, healthPath, runner, probes }) {
+  const authority = netAuthority(host);
+  const origin = `http://${authority}:${port}`;
+  const curlBase = ['--fail', '--silent', '--show-error', '--max-time', '10'];
+  runner('curl', [...curlBase, `${origin}${healthPath}`], { capture: true });
+  probes.push({ kind: 'http', target: `${name}/health`, status: 'passed' });
+  const homepage = runner('curl', [...curlBase, `${origin}/`], { capture: true });
+  const html = String(Buffer.isBuffer(homepage.stdout) ? homepage.stdout.toString('utf8') : homepage.stdout ?? '');
+  const match = html.match(/(?:src|href)=["']([^"']*\/_next\/[^"']+)["']/u);
+  invariant(match, 'IDP_SMARTGO_NEXT_ASSET_MISSING', `${name}首页没有引用可验证的Next.js静态资源`);
+  const asset = new URL(match[1].replaceAll('&amp;', '&'), `${origin}/`);
+  invariant(asset.origin === origin && asset.pathname.startsWith('/_next/'), 'IDP_SMARTGO_NEXT_ASSET_ORIGIN_INVALID', `${name}静态资源没有保持独立Origin与根路径`);
+  runner('curl', [...curlBase, asset.toString()], { capture: true });
+  probes.push({ kind: 'http', target: `${name}/next-asset`, status: 'passed' });
+}
+
+export function verifyDeployment({ repositoryRoot, configRoot, profile, instanceLease, runner = run, allowLegacyImageLock = false }) {
+  const { root, env, components, report } = doctorConfig(configRoot, { requireConfigured: true, profile, allowLegacyImageLock });
+  const active = new Set(resolveProfile(profile));
+  return withInstanceLock(root, env, 'deployment:verify', () => {
+    prepareState(root, env, active);
+    const rendered = renderRuntimeBundles(root, profile);
+    const processEnvironment = composeProcessEnvironment(root, rendered.target);
+    const args = composeArgs(repositoryRoot, root, profile, ['ps', '--format', 'json'], { projectName: env.IDP_INSTANCE_ID });
+    const result = runner('docker', args, { capture: true, env: processEnvironment });
+    const services = parseComposePs(result.stdout);
+    const expected = resolveProfileServices(profile);
+    const actualNames = services.map((entry) => entry.Service).filter(Boolean).sort();
+    invariant(stableJson(actualNames) === stableJson([...expected].sort()), 'IDP_SERVICE_SET_MISMATCH', `运行服务集合与Profile不一致；expected=${[...expected].sort().join(',')} actual=${actualNames.join(',')}`);
+    const state = readActiveProfileState(env);
+    if (state) {
+      invariant(state.status === 'active' && state.profile === profile, 'IDP_PROFILE_STATE_MISMATCH', `活动Profile状态与待验收Profile不一致：${state.status}/${state.profile}`);
+      invariant(state.configDigest === report.digest, 'IDP_DEPLOYED_CONFIG_DRIFT', '当前Config Dir已变化但运行服务尚未切换到新配置');
+      invariant(state.renderDigest === rendered.manifest.digest, 'IDP_DEPLOYED_RENDER_DRIFT', '运行服务使用的配置投影与当前确定性投影不一致');
+    }
+    for (const serviceName of expected) {
+      const service = services.find((entry) => entry.Service === serviceName);
+      invariant(service, 'IDP_SERVICE_MISSING', `部署缺少服务：${serviceName}`);
+      invariant(String(service.State).toLowerCase() === 'running', 'IDP_SERVICE_NOT_RUNNING', `服务未运行：${serviceName}`);
+      invariant(String(service.Health).toLowerCase() === 'healthy', 'IDP_SERVICE_UNHEALTHY', `服务没有通过健康检查：${serviceName}`);
+    }
+    const probes = [];
+    if (expected.includes('edge')) {
+      const tls = env.IDP_TLS_ENABLED === 'true';
+      const port = tls ? env.IDP_HTTPS_PORT : env.IDP_HTTP_PORT;
+      const bind = tls ? env.IDP_HTTPS_BIND : env.IDP_HTTP_BIND;
+      const host = ['0.0.0.0', '::'].includes(bind) ? '127.0.0.1' : bind;
+      const publicHost = env.IDP_PUBLIC_HOST.replace(/^\[|\]$/gu, '');
+      const publicAuthority = netAuthority(publicHost);
+      const curlBase = ['--fail', '--silent', '--show-error', '--max-time', '10'];
+      if (publicHost !== host.replace(/^\[|\]$/gu, '')) curlBase.push('--resolve', `${publicHost}:${port}:${host}`);
+      if (tls) curlBase.push('--cacert', resolveContained(root, env.IDP_TLS_CERT_FILE, 'TLS证书'));
+      const paths = [['edge/live', '/live']];
+      if (expected.includes('flow')) paths.push(['flow/live', '/flow/live']);
+      if (expected.includes('tech')) paths.push(['tech/live', '/knowledge/live'], ['tech/ready', '/knowledge/ready']);
+      if (expected.includes('portal')) paths.push(['portal/readiness', '/.backstage/health/v1/readiness']);
+      for (const [target, probePath] of paths) {
+        runner('curl', [...curlBase, `${tls ? 'https' : 'http'}://${publicAuthority}:${port}${probePath}`], { capture: true });
+        probes.push({ kind: 'http', target, status: 'passed' });
+      }
+      if (expected.includes('smartgo-api')) {
+        const smartgoHost = components.smartgo.SMARTGO_BIND_HOST;
+        for (const application of [
+          { name: 'smartgo/gotology', port: env.IDP_SMARTGO_GOTOLOGY_PORT, healthPath: '/api/health' },
+          { name: 'smartgo/operations', port: env.IDP_SMARTGO_OPERATIONS_PORT, healthPath: '/api/health' },
+          { name: 'smartgo/studio', port: env.IDP_SMARTGO_STUDIO_PORT, healthPath: '/api/health?ready=1' },
+        ]) probeSmartGoApplication({ ...application, host: smartgoHost, runner, probes });
+      }
+    }
+    if (expected.includes('registry')) {
+      const bind = ['0.0.0.0', '::'].includes(env.IDP_REGISTRY_BIND) ? '127.0.0.1' : env.IDP_REGISTRY_BIND;
+      runner('curl', ['--fail', '--silent', '--show-error', '--max-time', '10', `http://${netAuthority(bind)}:${env.IDP_REGISTRY_PORT}/-/ping`], { capture: true });
+      probes.push({ kind: 'http', target: 'registry/-/ping', status: 'passed' });
+    }
+    return writeReceipt(env, 'verify', {
+      profile, configDigest: report.digest, renderDigest: rendered.manifest.digest,
+      services: expected.map((service) => ({ service, status: 'healthy' })), probes,
+    });
+  }, { lease: instanceLease });
+}