@aipt/idp-deploy 0.1.2

package/src/images.mjs

@@ -0,0 +1,215 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { doctorConfig } from './config.mjs';
+import { IdpError, invariant } from './errors.mjs';
+import { stableJson } from './hash.mjs';
+import { buildImageLock, IMAGE_KEYS, readImageLock, REQUIRED_IMAGE_PLATFORMS, validateImageLockDocument } from './image-lock.mjs';
+import { withInstanceLock, writeReceipt } from './operations.mjs';
+import { dockerOfficialMirrorRef } from './oci-mirror.mjs';
+import { resolveProfile } from './profiles.mjs';
+import { assertSafeRegularFile, atomicWrite, createExclusiveFile, parseEnv } from './security.mjs';
+import { run } from './process.mjs';
+
+export { readImageLock, validateImageLockDocument } from './image-lock.mjs';
+
+const IMAGE_KEYS_BY_COMPONENT = Object.freeze({
+  postgresql: ['IDP_POSTGRES_IMAGE'],
+  edge: ['IDP_CADDY_IMAGE'],
+  registry: ['IDP_REGISTRY_IMAGE'],
+  tech: ['IDP_TECH_IMAGE'],
+  portal: ['IDP_PORTAL_IMAGE'],
+  flow: ['IDP_FLOW_IMAGE'],
+  smartgo: ['IDP_SMARTGO_IMAGE', 'IDP_SMARTGO_OBJECT_STORE_IMAGE', 'IDP_SMARTGO_OBJECT_STORE_CLIENT_IMAGE'],
+});
+
+export function imageKeysForProfile(profile) {
+  return [...new Set(resolveProfile(profile).flatMap((component) => IMAGE_KEYS_BY_COMPONENT[component] ?? []))];
+}
+
+export function resolveImage(ref, { platform = 'linux/arm64', runner = run } = {}) {
+  invariant(ref && ref !== 'UNCONFIGURED' && !/\s/u.test(ref), 'IDP_IMAGE_REF_INVALID', `镜像引用无效：${ref || '<empty>'}`);
+  const mirrorRef = dockerOfficialMirrorRef(ref);
+  let result;
+  try {
+    result = runner('docker', ['buildx', 'imagetools', 'inspect', mirrorRef ?? ref, '--format', '{{json .}}'], { capture: true });
+  } catch (error) {
+    if (!mirrorRef) throw error;
+    result = runner('docker', ['buildx', 'imagetools', 'inspect', ref, '--format', '{{json .}}'], { capture: true });
+  }
+  const output = Buffer.isBuffer(result.stdout) ? result.stdout.toString('utf8') : String(result.stdout ?? '');
+  let inspection;
+  try { inspection = JSON.parse(output); }
+  catch { invariant(false, 'IDP_IMAGE_INSPECT_INVALID', `无法解析镜像OCI检查结果：${ref}`); }
+  const digest = inspection?.manifest?.digest;
+  invariant(/^sha256:[0-9a-f]{64}$/u.test(digest ?? ''), 'IDP_IMAGE_DIGEST_UNRESOLVED', `无法解析镜像摘要：${ref}`);
+  const [wantedOs, wantedArchitecture] = platform.split('/');
+  const indexedPlatforms = Array.isArray(inspection?.manifest?.manifests)
+    ? inspection.manifest.manifests.map((manifest) => manifest?.platform).filter(Boolean)
+    : [];
+  const singleImagePlatform = inspection?.image ? [{ os: inspection.image.os, architecture: inspection.image.architecture, variant: inspection.image.variant }] : [];
+  const evidencePlatforms = [...indexedPlatforms, ...singleImagePlatform];
+  invariant(evidencePlatforms.some((entry) => entry.os === wantedOs && entry.architecture === wantedArchitecture), 'IDP_IMAGE_PLATFORM_MISSING', `镜像Manifest不包含${platform}：${ref}`);
+  return { digest, platform, evidence: indexedPlatforms.length > 0 ? 'oci-index-platform' : 'oci-image-config-platform' };
+}
+
+export function lockImages(configRoot, {
+  requiredPlatforms = REQUIRED_IMAGE_PLATFORMS,
+  profile = 'full',
+  overrides = {},
+  requireProfileImages = false,
+  instanceLease,
+  resolver = resolveImage,
+  writer = atomicWrite,
+} = {}) {
+  const selectedKeys = new Set(imageKeysForProfile(profile));
+  const platforms = [...requiredPlatforms];
+  invariant(
+    stableJson(platforms) === stableJson([...new Set(platforms)].sort()) &&
+      platforms.length > 0 && platforms.every((candidate) => REQUIRED_IMAGE_PLATFORMS.includes(candidate)),
+    'IDP_IMAGE_LOCK_REQUIRED_PLATFORMS_INVALID',
+    '镜像锁平台必须是按字典序排列且不重复的linux/amd64、linux/arm64集合',
+  );
+  invariant(overrides && typeof overrides === 'object' && !Array.isArray(overrides), 'IDP_IMAGE_OVERRIDE_INVALID', '镜像覆盖必须是键值对象');
+  for (const [key, ref] of Object.entries(overrides)) {
+    invariant(selectedKeys.has(key), 'IDP_IMAGE_OVERRIDE_OUTSIDE_PROFILE', `${key}不属于${profile} Profile，拒绝写入`);
+    invariant(typeof ref === 'string' && ref.length > 0 && ref !== 'UNCONFIGURED' && !/\s/u.test(ref), 'IDP_IMAGE_OVERRIDE_INVALID', `${key}镜像覆盖值无效`);
+  }
+  const preliminary = doctorConfig(configRoot, { requireConfigured: false, profile });
+  return withInstanceLock(preliminary.root, preliminary.env, 'images:lock', () => {
+  const { root, env } = doctorConfig(preliminary.root, { requireConfigured: false, profile });
+  invariant(env.IDP_RUNTIME_DIR === preliminary.env.IDP_RUNTIME_DIR, 'IDP_IMAGE_CONFIG_CONFLICT', '获取实例锁期间IDP_RUNTIME_DIR发生变化，禁止继续镜像锁定');
+  const envPath = path.join(root, '.env');
+  const lockPath = path.join(root, 'images.lock.json');
+  const before = fs.readFileSync(envPath, 'utf8');
+  const currentEnv = parseEnv(before, envPath);
+  const effectiveEnv = { ...currentEnv, ...overrides };
+  const locked = [];
+  const skipped = [];
+  let previousLock;
+  let previousLockText = null;
+  if (fs.existsSync(lockPath)) {
+    assertSafeRegularFile(lockPath, 0o600, { allowEmpty: false, role: '旧镜像锁' });
+    previousLockText = fs.readFileSync(lockPath, 'utf8');
+    previousLock = readImageLock(root, { allowLegacy: true, requiredPlatforms: ['linux/arm64'] }).document;
+  }
+  const previousEntries = new Map((previousLock?.images ?? []).map((entry) => [entry.key, previousLock.schemaVersion === 1
+    ? {
+      key: entry.key,
+      sourceRef: entry.sourceRef,
+      pinnedRef: entry.pinnedRef,
+      digest: entry.digest,
+      platforms: [{ platform: entry.platform, evidence: entry.evidence }],
+    }
+    : entry]));
+  let after = before;
+  for (const key of selectedKeys) {
+    const ref = effectiveEnv[key];
+    if (!ref || ref === 'UNCONFIGURED') {
+      skipped.push({ key, reason: 'unconfigured' });
+      continue;
+    }
+    const resolutions = platforms.map((platform) => {
+      const resolved = resolver(ref, { platform });
+      invariant(/^sha256:[0-9a-f]{64}$/u.test(resolved.digest), 'IDP_IMAGE_DIGEST_INVALID', `${key}在${platform}解析出了无效摘要`);
+      invariant(typeof resolved.evidence === 'string' && resolved.evidence.length > 0, 'IDP_IMAGE_EVIDENCE_INVALID', `${key}在${platform}缺少OCI平台证据`);
+      return { platform, digest: resolved.digest, evidence: resolved.evidence };
+    });
+    const [resolved] = resolutions;
+    for (const candidate of resolutions.slice(1)) {
+      invariant(candidate.digest === resolved.digest, 'IDP_IMAGE_PLATFORM_DIGEST_MISMATCH', `${key}在不同平台解析到不同OCI Index摘要，拒绝锁定可变tag`);
+    }
+    const repository = ref.replace(/@sha256:[0-9a-f]{64}$/u, '');
+    const pinned = `${repository}@${resolved.digest}`;
+    const previous = previousEntries.get(key);
+    const sourceRef = previous && [previous.sourceRef, previous.pinnedRef].includes(ref)
+      ? previous.sourceRef
+      : ref;
+    const keyPattern = new RegExp(`^${key}=.*$`, 'mu');
+    invariant(keyPattern.test(after), 'IDP_IMAGE_ENV_KEY_MISSING', `.env缺少${key}，请先执行config init`);
+    after = after.replace(keyPattern, `${key}=${pinned}`);
+    locked.push({
+      key,
+      ref: pinned,
+      sourceRef,
+      pinnedRef: pinned,
+      digest: resolved.digest,
+      platforms: resolutions.map(({ platform, evidence }) => ({ platform, evidence })),
+    });
+  }
+  const preserved = [...previousEntries.values()].filter((entry) =>
+    !selectedKeys.has(entry.key) &&
+    currentEnv[entry.key] === entry.pinnedRef &&
+    platforms.every((platform) => entry.platforms.some((candidate) => candidate.platform === platform)));
+  const imageEntries = [...preserved, ...locked]
+    .map(({ ref: _ref, ...entry }) => entry)
+    .sort((left, right) => left.key < right.key ? -1 : left.key > right.key ? 1 : 0);
+  const semanticPayload = { requiredPlatforms: platforms, images: imageEntries };
+  const previousSemanticPayload = previousLock?.schemaVersion === 2
+    ? { requiredPlatforms: previousLock.requiredPlatforms, images: previousLock.images }
+    : undefined;
+  const lockChanged = !previousLock || stableJson(semanticPayload) !== stableJson(previousSemanticPayload);
+  const lockDocument = lockChanged ? buildImageLock(imageEntries, { requiredPlatforms: platforms }) : previousLock;
+  const configuredSelectedKeys = [...selectedKeys].filter((key) => effectiveEnv[key] && effectiveEnv[key] !== 'UNCONFIGURED');
+  const requiredKeys = requireProfileImages ? [...selectedKeys] : configuredSelectedKeys;
+  validateImageLockDocument(lockDocument, { env: parseEnv(after, envPath), requiredPlatforms: platforms, requiredKeys });
+  const nextLockText = `${JSON.stringify(lockDocument, null, 2)}\n`;
+
+  const timestamp = new Date().toISOString().replace(/[:.]/gu, '-');
+  let preimage = null;
+  if (after !== before) {
+    preimage = path.join(root, 'snapshots', `${timestamp}-images.env.preimage`);
+    createExclusiveFile(preimage, before, 0o600);
+  }
+  let lockPreimage = null;
+  if (lockChanged) {
+    if (previousLock) {
+      lockPreimage = path.join(root, 'snapshots', `${timestamp}-images.lock.json.preimage`);
+      createExclusiveFile(lockPreimage, previousLockText, 0o600);
+    }
+  }
+  const currentLockText = () => fs.existsSync(lockPath) ? fs.readFileSync(lockPath, 'utf8') : null;
+  invariant(fs.readFileSync(envPath, 'utf8') === before, 'IDP_IMAGE_ENV_CONFLICT', '.env在镜像解析期间被修改，禁止覆盖用户新内容');
+  invariant(currentLockText() === previousLockText, 'IDP_IMAGE_LOCK_CONFLICT', 'images.lock.json在镜像解析期间被修改，禁止覆盖用户新内容');
+  try {
+    if (after !== before) writer(envPath, after, 0o600);
+    if (lockChanged) writer(lockPath, nextLockText, 0o600);
+    const validated = doctorConfig(root, { requireConfigured: false, profile });
+    invariant(validated.env.IDP_RUNTIME_DIR === env.IDP_RUNTIME_DIR, 'IDP_IMAGE_CONFIG_CONFLICT', '镜像解析期间IDP_RUNTIME_DIR发生变化，已拒绝发布');
+    const receipt = writeReceipt(validated.env, 'images-lock', {
+      requiredPlatforms: platforms,
+      profile,
+      lockDigest: lockDocument.digest,
+      locked: locked.map(({ key, pinnedRef }) => ({ key, pinnedRef })),
+      skipped,
+      envPreimageCreated: Boolean(preimage),
+      lockPreimageCreated: Boolean(lockPreimage),
+    });
+    return {
+      locked,
+      skipped,
+      preimage,
+      lockPreimage,
+      lockPath,
+      lockDigest: lockDocument.digest,
+      requiredPlatforms: platforms,
+      profile,
+      receipt: receipt.receipt,
+      report: validated.report,
+    };
+  } catch (error) {
+    try {
+      const observedLock = currentLockText();
+      if (observedLock === nextLockText && lockChanged) {
+        if (previousLockText === null) fs.unlinkSync(lockPath);
+        else writer(lockPath, previousLockText, 0o600);
+      } else invariant(observedLock === previousLockText, 'IDP_IMAGE_LOCK_RECOVERY_REQUIRED', '镜像锁失败后发现并发修改，禁止自动覆盖');
+      const observedEnv = fs.readFileSync(envPath, 'utf8');
+      if (observedEnv === after && after !== before) writer(envPath, before, 0o600);
+      else invariant(observedEnv === before, 'IDP_IMAGE_LOCK_RECOVERY_REQUIRED', '镜像锁失败后发现.env并发修改，禁止自动覆盖');
+    } catch (recoveryError) {
+      throw new IdpError('IDP_IMAGE_LOCK_RECOVERY_REQUIRED', `镜像锁写入失败且自动回滚未完成：${recoveryError.message}`, { originalError: error.message });
+    }
+    throw error;
+  }
+  }, { lease: instanceLease });
+}

package/src/lifecycle.mjs

@@ -0,0 +1,58 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { IdpError } from './errors.mjs';
+import { stableJson } from './hash.mjs';
+
+const decisions = new Set(['accepted', 'replaced', 'selectively-received', 'deferred']);
+const activeComponents = ['postgresql', 'registry', 'tech', 'flow', 'portal', 'edge'];
+
+function invariant(condition, code, message) {
+  if (!condition) throw new IdpError(code, message);
+}
+
+function repositoryPath(repositoryRoot, relative, label) {
+  invariant(typeof relative === 'string' && relative && !path.isAbsolute(relative) && !relative.split(/[\\/]/u).includes('..'), 'IDP_LIFECYCLE_PATH_INVALID', `${label}必须是仓库内相对路径：${relative}`);
+  const target = path.resolve(repositoryRoot, relative);
+  const root = path.resolve(repositoryRoot);
+  invariant(target === root || target.startsWith(`${root}${path.sep}`), 'IDP_LIFECYCLE_PATH_INVALID', `${label}越出仓库：${relative}`);
+  invariant(fs.existsSync(target), 'IDP_LIFECYCLE_TARGET_MISSING', `${label}不存在：${relative}`);
+  return target;
+}
+
+export function verifyAssetLifecycle(repositoryRoot) {
+  const manifestPath = repositoryPath(repositoryRoot, 'governance/asset-lifecycle.v1.json', '生命周期清单');
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  invariant(manifest.schemaVersion === 'idp-deploy.asset-lifecycle/v1' && manifest.planId === 'idp-deploy.bench-deployment-ownership-reception@1' && manifest.version === 1 && manifest.immutable === true, 'IDP_LIFECYCLE_MANIFEST_INVALID', '生命周期清单批准事实无效');
+  invariant(stableJson(manifest.activeComponents) === stableJson(activeComponents), 'IDP_LIFECYCLE_COMPONENTS_INVALID', '活动组件集合或顺序与当前最小 IDP 不一致');
+  repositoryPath(repositoryRoot, manifest.archiveRoot, '归档目录');
+  invariant(Array.isArray(manifest.receipts) && manifest.receipts.length === 6, 'IDP_LIFECYCLE_RECEIPTS_INVALID', 'Bench 部署接收回执必须完整覆盖六类来源资产');
+  const identities = [];
+  for (const receipt of manifest.receipts) {
+    invariant(receipt?.sourceProject === 'bench' && typeof receipt.sourceAsset === 'string' && receipt.sourceAsset, 'IDP_LIFECYCLE_RECEIPT_INVALID', '接收回执来源身份无效');
+    invariant(!identities.includes(receipt.sourceAsset), 'IDP_LIFECYCLE_RECEIPT_DUPLICATE', `接收回执重复：${receipt.sourceAsset}`);
+    identities.push(receipt.sourceAsset);
+    invariant(/^sha256:[0-9a-f]{64}$/u.test(receipt.sourceEvidence ?? '') && decisions.has(receipt.decision), 'IDP_LIFECYCLE_RECEIPT_INVALID', `接收回执摘要或决策无效：${receipt.sourceAsset}`);
+    invariant(typeof receipt.targetCapability === 'string' && receipt.targetCapability && Array.isArray(receipt.targetPaths) && Array.isArray(receipt.evidence) && receipt.evidence.length > 0 && Array.isArray(receipt.remainingGates), 'IDP_LIFECYCLE_RECEIPT_INVALID', `接收回执字段不完整：${receipt.sourceAsset}`);
+    if (receipt.decision === 'deferred') invariant(receipt.targetPaths.length === 0 && receipt.remainingGates.length > 0, 'IDP_LIFECYCLE_DEFERRED_INVALID', `延后资产不能伪造目标实现：${receipt.sourceAsset}`);
+    else invariant(receipt.targetPaths.length > 0, 'IDP_LIFECYCLE_TARGET_MISSING', `已接收资产缺少目标实现：${receipt.sourceAsset}`);
+    for (const target of receipt.targetPaths) repositoryPath(repositoryRoot, target, `${receipt.sourceAsset}目标`);
+    for (const evidence of receipt.evidence) repositoryPath(repositoryRoot, evidence, `${receipt.sourceAsset}证据`);
+  }
+  const expectedSources = ['packages/ops', 'scripts/ops-agent.mjs', 'docker-compose.yml', 'local', 'gitops', 'infra/terraform'];
+  invariant(stableJson(identities) === stableJson(expectedSources), 'IDP_LIFECYCLE_RECEIPTS_INVALID', '接收回执未按固定清单覆盖 Bench 部署资产');
+  invariant(manifest.policy?.runtimeCrossRepositorySourceReads === false && manifest.policy?.archiveIncludedInRuntime === false && manifest.policy?.secretsOnlyFromExternalConfigDir === true && manifest.policy?.unapprovedRemoteResources === false && manifest.policy?.portalWriteProxy === false, 'IDP_LIFECYCLE_POLICY_INVALID', '生命周期安全策略无效');
+  const { digest, ...facts } = manifest;
+  const expectedDigest = `sha256:${crypto.createHash('sha256').update(stableJson(facts)).digest('hex')}`;
+  invariant(digest === expectedDigest, 'IDP_LIFECYCLE_DIGEST_MISMATCH', `生命周期清单摘要不匹配，期望${expectedDigest}`);
+  return {
+    schemaVersion: 'idp-deploy.lifecycle-check/v1',
+    status: 'valid',
+    planId: manifest.planId,
+    activeComponents,
+    receiptCount: manifest.receipts.length,
+    acceptedCount: manifest.receipts.filter(({ decision }) => decision !== 'deferred').length,
+    deferredCount: manifest.receipts.filter(({ decision }) => decision === 'deferred').length,
+    digest,
+  };
+}

package/src/local-source.mjs

@@ -0,0 +1,354 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { IdpError, invariant } from './errors.mjs';
+import { hashFile, sha256, stableJson } from './hash.mjs';
+import { run } from './process.mjs';
+import { assertOutsideRepositories, assertSafeRegularFile, atomicWrite, canonicalPlannedDirectory, parseEnv, resolveContained, secureDirectoryRoot } from './security.mjs';
+
+const APPLICATION_ID = /^[a-z0-9][a-z0-9._-]{0,127}$/u;
+const ENV_NAME = /^[A-Z][A-Z0-9_]{0,127}$/u;
+const SENSITIVE = /(?:^|_)(?:PASSWORD|PASSWD|TOKEN|SECRET|PRIVATE_KEY|ACCESS_KEY|API_KEY|DATABASE_URL|CONNECTION_STRING|DSN|AUTHORIZATION|CREDENTIALS?)(?:_|$)/u;
+const PLAN_SCHEMA = 'idp.local-source-deployment-plan/v1';
+
+function readJson(candidate, role) {
+  const stat = fs.lstatSync(candidate, { throwIfNoEntry: false });
+  invariant(stat?.isFile() && !stat.isSymbolicLink() && stat.nlink === 1 && stat.size > 1 && stat.size <= 4 * 1024 * 1024, 'IDP_LOCAL_INPUT_INVALID', `${role}必须是1 byte到4 MiB的普通非链接文件：${candidate}`);
+  try { return JSON.parse(fs.readFileSync(candidate, 'utf8')); }
+  catch (error) { throw new IdpError('IDP_LOCAL_INPUT_JSON_INVALID', `${role}不是有效JSON`, { cause: error.message }); }
+}
+
+function readProject(projectRoot) {
+  invariant(path.isAbsolute(projectRoot ?? ''), 'IDP_LOCAL_PROJECT_NOT_ABSOLUTE', '--project必须是绝对路径');
+  const root = fs.realpathSync.native(projectRoot);
+  invariant(fs.lstatSync(root).isDirectory(), 'IDP_LOCAL_PROJECT_INVALID', '项目路径必须是目录');
+  const manifestFile = path.join(root, 'project-capabilities.json');
+  const contractFile = path.join(root, 'config', 'application-config.json');
+  const manifest = readJson(manifestFile, 'Project Manifest');
+  const contract = validateApplicationConfigContract(readJson(contractFile, 'ApplicationConfigContract'), manifest);
+  return { root, manifestFile, contractFile, manifest, contract };
+}
+
+function projectSourceDigest(root) {
+  const ignored = new Set(['.git', '.dyyto', '.next', '.turbo', 'coverage', 'dist', 'node_modules']);
+  const entries = [];
+  function visit(directory) {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (ignored.has(entry.name)) continue;
+      const absolute = path.join(directory, entry.name);
+      const relative = path.relative(root, absolute);
+      const stat = fs.lstatSync(absolute);
+      invariant(!stat.isSymbolicLink(), 'IDP_LOCAL_SOURCE_SYMLINK_FORBIDDEN', `本地构建源不允许符号链接：${relative}`);
+      if (entry.isDirectory()) visit(absolute);
+      else if (entry.isFile()) entries.push({ path: relative, mode: stat.mode & 0o111, size: stat.size, digest: hashFile(absolute) });
+      else throw new IdpError('IDP_LOCAL_SOURCE_ENTRY_UNSUPPORTED', `本地构建源包含不支持的文件类型：${relative}`);
+    }
+  }
+  visit(root);
+  return sha256(stableJson(entries));
+}
+
+function validateApplicationConfigContract(contract, manifest) {
+  invariant(contract?.schemaVersion === 1 && contract.kind === 'ApplicationConfigContract', 'IDP_APPLICATION_CONFIG_INVALID', 'ApplicationConfigContract版本无效');
+  const id = contract.application?.id;
+  invariant(APPLICATION_ID.test(id ?? ''), 'IDP_APPLICATION_CONFIG_INVALID', 'Application identity无效');
+  invariant(contract.configDirectory?.rootEnvironmentVariable === 'IDP_CONFIG_DIR' && contract.configDirectory?.relativeDirectory === `applications/${id}` && contract.configDirectory?.environmentFile === '.env' && contract.configDirectory?.materializationOwner === 'external-deployment-control-plane', 'IDP_APPLICATION_CONFIG_INVALID', 'Application Config Dir合同无效');
+  invariant(manifest?.profile?.parameters?.name === id && manifest?.profile?.id === contract.application?.profile, 'IDP_APPLICATION_CONFIG_IDENTITY_MISMATCH', 'ApplicationConfigContract与Project Manifest身份不一致');
+  invariant(Array.isArray(contract.bindings) && contract.bindings.length <= 128, 'IDP_APPLICATION_CONFIG_INVALID', 'Application Binding列表无效');
+  const names = new Set(); const files = new Set();
+  for (const binding of contract.bindings) {
+    invariant(ENV_NAME.test(binding?.name ?? '') && !names.has(binding.name), 'IDP_APPLICATION_CONFIG_INVALID', `Application Binding名称无效或重复：${binding?.name ?? ''}`);
+    names.add(binding.name);
+    invariant(typeof binding.required === 'boolean' && ['value', 'secret-file', 'certificate-file'].includes(binding.kind), 'IDP_APPLICATION_CONFIG_INVALID', `Application Binding无效：${binding.name}`);
+    if (binding.kind === 'value') {
+      invariant(!SENSITIVE.test(binding.name), 'IDP_APPLICATION_SECRET_LITERAL_FORBIDDEN', `敏感配置${binding.name}必须使用文件Binding`);
+      invariant(binding.default === undefined || typeof binding.default === 'string', 'IDP_APPLICATION_CONFIG_INVALID', `${binding.name}默认值无效`);
+      continue;
+    }
+    invariant(binding.name.endsWith('_FILE') && typeof binding.file === 'string', 'IDP_APPLICATION_CONFIG_INVALID', `${binding.name}必须是*_FILE Binding`);
+    const prefix = binding.kind === 'secret-file' ? 'secrets/' : 'certs/';
+    invariant(binding.file.startsWith(prefix) && !path.isAbsolute(binding.file) && !binding.file.split('/').some((part) => ['', '.', '..'].includes(part)) && !files.has(binding.file), 'IDP_APPLICATION_CONFIG_INVALID', `${binding.name}文件路径无效`);
+    files.add(binding.file);
+  }
+  return contract;
+}
+
+function applicationDirectory(configRoot, id, { create = false, applicationConfigRoot } = {}) {
+  if (applicationConfigRoot) {
+    const app = secureDirectoryRoot(applicationConfigRoot, 'APP_CONFIG_DIR', { create });
+    assertOutsideRepositories(app, 'APP_CONFIG_DIR');
+    return { root: app, app };
+  }
+  const root = secureDirectoryRoot(configRoot, 'IDP_CONFIG_DIR', { create });
+  assertOutsideRepositories(root, 'IDP_CONFIG_DIR');
+  const applications = resolveContained(root, 'applications', '应用配置目录');
+  if (create) secureDirectoryRoot(applications, '应用配置目录', { create: true });
+  const app = resolveContained(root, `applications/${id}`, '应用配置目录');
+  if (create) secureDirectoryRoot(app, '应用配置目录', { create: true });
+  return { root, app };
+}
+
+function savePreimage(root, id, name, bytes) {
+  const directory = resolveContained(root, `snapshots/applications/${id}`, '应用配置Preimage目录');
+  secureDirectoryRoot(directory, '应用配置Preimage目录', { create: true });
+  const digest = sha256(bytes);
+  const candidate = path.join(directory, `${Date.now()}-${name}-${digest.slice(7, 19)}`);
+  fs.writeFileSync(candidate, bytes, { mode: 0o600, flag: 'wx' });
+  return { path: candidate, digest };
+}
+
+export function initializeApplicationConfig({ configRoot, projectRoot, applicationConfigRoot }) {
+  const project = readProject(projectRoot);
+  const { root, app } = applicationDirectory(configRoot, project.contract.application.id, { create: true, applicationConfigRoot });
+  for (const name of ['secrets', 'certs']) secureDirectoryRoot(path.join(app, name), `应用${name}目录`, { create: true });
+  const envFile = path.join(app, '.env');
+  const before = fs.existsSync(envFile) ? fs.readFileSync(envFile) : Buffer.from('');
+  if (fs.existsSync(envFile)) assertSafeRegularFile(envFile, 0o600, { role: '应用.env' });
+  const existing = parseEnv(before.toString('utf8'), envFile);
+  const additions = [];
+  const createdFiles = [];
+  for (const binding of project.contract.bindings) {
+    if (!(binding.name in existing)) additions.push(`${binding.name}=${binding.kind === 'value' ? (binding.default ?? '') : binding.file}`);
+    if (binding.kind !== 'value') {
+      const target = resolveContained(app, binding.file, `${binding.name}文件`);
+      secureDirectoryRoot(path.dirname(target), `${binding.name}父目录`, { create: true });
+      if (!fs.existsSync(target)) { fs.writeFileSync(target, '', { mode: 0o600, flag: 'wx' }); createdFiles.push(target); }
+      else assertSafeRegularFile(target, 0o600, { role: binding.name });
+    }
+  }
+  let preimage;
+  if (!fs.existsSync(envFile)) atomicWrite(envFile, additions.length ? `${additions.join('\n')}\n` : '', 0o600);
+  else if (additions.length) {
+    preimage = savePreimage(root, project.contract.application.id, 'env', before);
+    atomicWrite(envFile, `${before.toString('utf8').trimEnd()}\n# 由app config-init补齐；已有值未覆盖。\n${additions.join('\n')}\n`, 0o600);
+  }
+  return { schemaVersion: 'idp.application-config-materialization/v1', status: 'ready', application: project.contract.application.id, directory: app, environmentFile: envFile, createdFiles, additions: additions.map((line) => line.slice(0, line.indexOf('='))), ...(preimage ? { preimage } : {}) };
+}
+
+function inspectApplicationConfig(configRoot, contract, applicationConfigRoot) {
+  const { app } = applicationDirectory(configRoot, contract.application.id, { applicationConfigRoot });
+  const envFile = path.join(app, '.env');
+  assertSafeRegularFile(envFile, 0o600, { allowEmpty: contract.bindings.length === 0, role: '应用.env' });
+  const env = parseEnv(fs.readFileSync(envFile, 'utf8'), envFile);
+  const files = [];
+  for (const binding of contract.bindings) {
+    invariant(binding.name in env, 'IDP_APPLICATION_CONFIG_MISSING', `应用.env缺少${binding.name}`);
+    if (binding.kind === 'value') {
+      if (binding.required) invariant(env[binding.name] !== '', 'IDP_APPLICATION_CONFIG_REQUIRED', `${binding.name}尚未配置`);
+      continue;
+    }
+    invariant(env[binding.name] === binding.file, 'IDP_APPLICATION_CONFIG_REFERENCE_CHANGED', `${binding.name}必须保持合同声明的相对文件引用`);
+    const candidate = resolveContained(app, binding.file, binding.name);
+    assertSafeRegularFile(candidate, 0o600, { allowEmpty: !binding.required, role: binding.name });
+    files.push({ name: binding.name, path: binding.file, digest: hashFile(candidate), required: binding.required });
+  }
+  return { app, envFile, envDigest: hashFile(envFile), fileBindings: files };
+}
+
+function composeArgs(plan, tail) {
+  return ['compose', '--project-name', plan.composeProject, '--env-file', plan.config.environmentFile, '--file', plan.compose.path, ...tail];
+}
+
+function executeCompose(runner, args, cwd, capture = true) {
+  return runner('docker', args, { cwd, capture, maxBuffer: 16 * 1024 * 1024 });
+}
+
+function normalizedCompose({ projectRoot, composeFile, envFile, composeProject, runner }) {
+  const result = executeCompose(runner, ['compose', '--project-name', composeProject, '--env-file', envFile, '--file', composeFile, 'config', '--format', 'json'], projectRoot, true);
+  let document;
+  try { document = JSON.parse(result.stdout); }
+  catch (error) { throw new IdpError('IDP_LOCAL_COMPOSE_JSON_INVALID', 'docker compose未返回有效JSON', { cause: error.message }); }
+  validateCompose(document, projectRoot);
+  return { document, bytes: `${stableJson(document)}\n` };
+}
+
+function validateCompose(document, projectRoot) {
+  const services = document?.services;
+  invariant(services && typeof services === 'object' && Object.keys(services).length > 0, 'IDP_LOCAL_COMPOSE_INVALID', 'Compose必须至少声明一个服务');
+  let healthchecks = 0;
+  for (const [name, service] of Object.entries(services)) {
+    invariant(!service.privileged && service.network_mode !== 'host' && service.container_name === undefined, 'IDP_LOCAL_COMPOSE_UNSAFE', `服务${name}包含privileged、host network或container_name`);
+    invariant(!Array.isArray(service.cap_add) || service.cap_add.length === 0, 'IDP_LOCAL_COMPOSE_UNSAFE', `服务${name}不允许cap_add`);
+    invariant(!Array.isArray(service.devices) || service.devices.length === 0, 'IDP_LOCAL_COMPOSE_UNSAFE', `服务${name}不允许设备直通`);
+    invariant(!Array.isArray(service.secrets) || service.secrets.length === 0, 'IDP_LOCAL_COMPOSE_SECRET_LITERAL', `服务${name}不允许从项目Compose投影Secret；请使用ApplicationConfigContract的*_FILE`);
+    if (service.build) {
+      const context = typeof service.build === 'string' ? service.build : service.build.context;
+      invariant(typeof context === 'string', 'IDP_LOCAL_COMPOSE_BUILD_INVALID', `服务${name}构建上下文无效`);
+      const absoluteContext = path.resolve(projectRoot, context);
+      const contextRelative = path.relative(projectRoot, absoluteContext);
+      invariant(contextRelative === '' || (!contextRelative.startsWith('..') && !path.isAbsolute(contextRelative)), 'IDP_LOCAL_COMPOSE_BUILD_OUTSIDE_PROJECT', `服务${name}构建上下文必须位于项目内`);
+    }
+    if (service.healthcheck && !service.healthcheck.disable) healthchecks += 1;
+    for (const [key, value] of Object.entries(service.environment ?? {})) {
+      invariant(!(SENSITIVE.test(key) && value !== null && value !== ''), 'IDP_LOCAL_COMPOSE_SECRET_LITERAL', `服务${name}不得内联敏感环境变量${key}`);
+    }
+    for (const volume of service.volumes ?? []) {
+      const source = typeof volume === 'string' ? volume.split(':')[0] : volume?.source;
+      invariant(source !== '/var/run/docker.sock', 'IDP_LOCAL_COMPOSE_UNSAFE', `服务${name}不允许挂载Docker Socket`);
+      if (typeof source === 'string' && path.isAbsolute(source)) {
+        const relative = path.relative(projectRoot, path.resolve(source));
+        invariant(relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative), 'IDP_LOCAL_COMPOSE_HOST_MOUNT_FORBIDDEN', `服务${name}的绝对宿主挂载必须位于项目内`);
+      }
+    }
+    for (const port of service.ports ?? []) {
+      const hostIp = typeof port === 'object' ? port.host_ip : undefined;
+      invariant(hostIp === '127.0.0.1' || hostIp === '::1', 'IDP_LOCAL_COMPOSE_PORT_EXPOSED', `服务${name}发布端口必须显式绑定回环地址`);
+    }
+  }
+  invariant(healthchecks > 0, 'IDP_LOCAL_COMPOSE_HEALTHCHECK_REQUIRED', 'Compose至少一个服务必须声明healthcheck');
+}
+
+function planIdentity(core) { return sha256(stableJson(core)); }
+
+export function createLocalSourcePlan({ configRoot, applicationConfigRoot, projectRoot, composeFile, output, runner = run, now = new Date().toISOString() }) {
+  const project = readProject(projectRoot);
+  invariant(path.isAbsolute(composeFile ?? ''), 'IDP_LOCAL_COMPOSE_NOT_ABSOLUTE', '--compose-file必须是绝对路径');
+  const composePath = fs.realpathSync.native(composeFile);
+  const relativeCompose = path.relative(project.root, composePath);
+  invariant(relativeCompose && !relativeCompose.startsWith('..') && !path.isAbsolute(relativeCompose), 'IDP_LOCAL_COMPOSE_OUTSIDE_PROJECT', 'Compose文件必须位于项目内');
+  assertSafeRegularFile(composePath, 0o644, { allowEmpty: false, role: '本地Compose文件' });
+  const config = inspectApplicationConfig(configRoot, project.contract, applicationConfigRoot);
+  const composeProject = `idp-${project.contract.application.id}-local`.replace(/[^a-z0-9_-]/gu, '-').slice(0, 63);
+  const normalized = normalizedCompose({ projectRoot: project.root, composeFile: composePath, envFile: config.envFile, composeProject, runner });
+  const core = {
+    schemaVersion: PLAN_SCHEMA, mode: 'local-source', promotable: false, application: project.contract.application.id,
+    project: { root: project.root, sourceDigest: projectSourceDigest(project.root), manifest: { path: project.manifestFile, digest: hashFile(project.manifestFile) }, applicationConfigContract: { path: project.contractFile, digest: hashFile(project.contractFile) } },
+    config: { directory: config.app, environmentFile: config.envFile, environmentDigest: config.envDigest, fileBindings: config.fileBindings },
+    compose: { path: composePath, sourceDigest: hashFile(composePath), normalizedDigest: sha256(normalized.bytes) }, composeProject, createdAt: now,
+  };
+  const plan = { ...core, planId: planIdentity(core) };
+  const { root } = applicationDirectory(configRoot, project.contract.application.id, { applicationConfigRoot });
+  invariant(path.isAbsolute(output ?? ''), 'IDP_LOCAL_PLAN_OUTPUT_NOT_ABSOLUTE', '--output必须是绝对路径');
+  const plans = resolveContained(root, 'plans/local-applications', '本地应用Plan目录');
+  secureDirectoryRoot(plans, '本地应用Plan目录', { create: true });
+  const target = canonicalPlannedDirectory(output, 'Local DeploymentPlan输出');
+  const relative = path.relative(plans, target);
+  invariant(relative && !relative.startsWith('..') && !path.isAbsolute(relative), 'IDP_LOCAL_PLAN_OUTPUT_OUTSIDE_CONFIG', 'Plan必须写入IDP_CONFIG_DIR/plans/local-applications');
+  invariant(!fs.existsSync(target), 'IDP_LOCAL_PLAN_EXISTS', 'Plan输出已存在，不允许覆盖');
+  atomicWrite(target, `${JSON.stringify(plan, null, 2)}\n`, 0o600);
+  return plan;
+}
+
+function readPlan(configRoot, planFile, applicationConfigRoot) {
+  invariant(path.isAbsolute(planFile ?? ''), 'IDP_LOCAL_PLAN_NOT_ABSOLUTE', '--plan必须是绝对路径');
+  const { root } = applicationDirectory(configRoot, 'placeholder', { applicationConfigRoot });
+  const plans = resolveContained(root, 'plans/local-applications', '本地应用Plan目录');
+  const candidate = fs.realpathSync.native(planFile);
+  const relative = path.relative(plans, candidate);
+  invariant(relative && !relative.startsWith('..') && !path.isAbsolute(relative), 'IDP_LOCAL_PLAN_OUTSIDE_CONFIG', 'Plan必须位于IDP_CONFIG_DIR/plans/local-applications');
+  assertSafeRegularFile(candidate, 0o600, { allowEmpty: false, role: 'Local DeploymentPlan' });
+  const plan = readJson(candidate, 'Local DeploymentPlan');
+  invariant(plan.schemaVersion === PLAN_SCHEMA && plan.mode === 'local-source' && plan.promotable === false, 'IDP_LOCAL_PLAN_INVALID', 'Local DeploymentPlan版本无效');
+  const { planId, ...core } = plan;
+  invariant(planIdentity(core) === planId, 'IDP_LOCAL_PLAN_DIGEST_INVALID', 'Local DeploymentPlan摘要无效');
+  return { plan, candidate, root };
+}
+
+function revalidate(plan, runner) {
+  invariant(projectSourceDigest(plan.project.root) === plan.project.sourceDigest, 'IDP_LOCAL_SOURCE_CHANGED', '项目构建源已变化，请重新生成Plan');
+  invariant(hashFile(plan.project.manifest.path) === plan.project.manifest.digest && hashFile(plan.project.applicationConfigContract.path) === plan.project.applicationConfigContract.digest && hashFile(plan.compose.path) === plan.compose.sourceDigest, 'IDP_LOCAL_INPUT_CHANGED', '项目Manifest、配置合同或Compose已变化，请重新生成Plan');
+  invariant(hashFile(plan.config.environmentFile) === plan.config.environmentDigest, 'IDP_LOCAL_CONFIG_CHANGED', '应用.env已变化，请重新生成Plan');
+  for (const binding of plan.config.fileBindings) invariant(hashFile(path.join(plan.config.directory, binding.path)) === binding.digest, 'IDP_LOCAL_CONFIG_CHANGED', `${binding.name}已变化，请重新生成Plan`);
+  const normalized = normalizedCompose({ projectRoot: plan.project.root, composeFile: plan.compose.path, envFile: plan.config.environmentFile, composeProject: plan.composeProject, runner });
+  invariant(sha256(normalized.bytes) === plan.compose.normalizedDigest, 'IDP_LOCAL_COMPOSE_RENDER_CHANGED', 'Compose规范化结果已变化，请重新生成Plan');
+  return normalized;
+}
+
+function statePath(root, id) {
+  const directory = resolveContained(root, 'runtime/local-applications', '本地应用运行态目录');
+  secureDirectoryRoot(directory, '本地应用运行态目录', { create: true });
+  return path.join(directory, `${id}.json`);
+}
+
+function evidence(root, plan, action, status, details = {}) {
+  const directory = resolveContained(root, 'evidence/local-applications', '本地应用Evidence目录');
+  secureDirectoryRoot(directory, '本地应用Evidence目录', { create: true });
+  const core = { schemaVersion: 'idp.local-source-deployment-evidence/v1', application: plan.application, planId: plan.planId, action, status, recordedAt: new Date().toISOString(), details };
+  const receipt = { ...core, receiptId: sha256(stableJson(core)) };
+  const target = path.join(directory, `${receipt.receiptId.slice(7)}.json`);
+  if (!fs.existsSync(target)) atomicWrite(target, `${JSON.stringify(receipt, null, 2)}\n`, 0o600);
+  return receipt;
+}
+
+function parsePs(stdout) {
+  const text = stdout.trim();
+  if (!text) return [];
+  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 activeState(root, plan, { required = true } = {}) {
+  const candidate = statePath(root, plan.application);
+  if (!fs.existsSync(candidate)) {
+    invariant(!required, 'IDP_LOCAL_RUNTIME_STATE_MISSING', '本地应用尚无受管运行态');
+    return { candidate, bytes: null, state: null };
+  }
+  assertSafeRegularFile(candidate, 0o600, { allowEmpty: false, role: '本地应用运行态' });
+  const bytes = fs.readFileSync(candidate);
+  const state = JSON.parse(bytes.toString('utf8'));
+  if (required) invariant(state.planId === plan.planId, 'IDP_LOCAL_RUNTIME_PLAN_MISMATCH', '当前运行态属于另一份Plan，请使用当前Plan操作');
+  return { candidate, bytes, state };
+}
+
+export function verifyLocalSourceDeployment({ configRoot, applicationConfigRoot, planFile, runner = run, requireActiveState = true }) {
+  const { plan, root } = readPlan(configRoot, planFile, applicationConfigRoot);
+  revalidate(plan, runner);
+  activeState(root, plan, { required: requireActiveState });
+  const ps = parsePs(executeCompose(runner, composeArgs(plan, ['ps', '--format', 'json']), plan.project.root, true).stdout);
+  invariant(ps.length > 0, 'IDP_LOCAL_DEPLOYMENT_NOT_RUNNING', '本地应用没有运行中的Compose服务');
+  for (const service of ps) {
+    const state = String(service.State ?? service.state ?? '').toLowerCase();
+    const health = String(service.Health ?? service.health ?? '').toLowerCase();
+    invariant(state === 'running', 'IDP_LOCAL_DEPLOYMENT_UNHEALTHY', `服务${service.Service ?? service.Name ?? ''}未运行`);
+    invariant(!health || health === 'healthy', 'IDP_LOCAL_DEPLOYMENT_UNHEALTHY', `服务${service.Service ?? service.Name ?? ''}健康状态为${health}`);
+  }
+  return evidence(root, plan, 'verify', 'verified', { services: ps.map((item) => item.Service ?? item.Name).filter(Boolean) });
+}
+
+export function applyLocalSourceDeployment({ configRoot, applicationConfigRoot, planFile, runner = run }) {
+  const { plan, root, candidate: canonicalPlanFile } = readPlan(configRoot, planFile, applicationConfigRoot);
+  revalidate(plan, runner);
+  const current = activeState(root, plan, { required: false });
+  const stateFile = current.candidate;
+  const before = current.bytes;
+  const preimageFile = path.join(path.dirname(stateFile), `.${plan.application}.${plan.planId.slice(7, 19)}.preimage.json`);
+  if (before) atomicWrite(preimageFile, before, 0o600);
+  try {
+    executeCompose(runner, composeArgs(plan, ['build']), plan.project.root, false);
+    executeCompose(runner, composeArgs(plan, ['up', '-d', '--wait', '--remove-orphans']), plan.project.root, false);
+    const afterCommands = fs.existsSync(stateFile) ? fs.readFileSync(stateFile) : null;
+    invariant((before === null && afterCommands === null) || (before !== null && afterCommands !== null && before.equals(afterCommands)), 'IDP_LOCAL_RUNTIME_STATE_CHANGED', '执行期间运行态被并发修改，拒绝提交Receipt');
+    const receipt = verifyLocalSourceDeployment({ configRoot, applicationConfigRoot, planFile, runner, requireActiveState: false });
+    atomicWrite(stateFile, `${JSON.stringify({ schemaVersion: 'idp.local-source-runtime/v1', application: plan.application, planId: plan.planId, composeProject: plan.composeProject, composeFile: plan.compose.path, planFile: canonicalPlanFile, receiptId: receipt.receiptId }, null, 2)}\n`, 0o600);
+    return evidence(root, plan, 'apply', 'verified', { verifyReceiptId: receipt.receiptId });
+  } catch (error) {
+    try {
+      if (before && current.state?.planFile) {
+        const previous = readPlan(configRoot, current.state.planFile, applicationConfigRoot).plan;
+        revalidate(previous, runner);
+        executeCompose(runner, composeArgs(previous, ['up', '-d', '--wait', '--remove-orphans']), previous.project.root, false);
+      }
+      else executeCompose(runner, composeArgs(plan, ['down', '--remove-orphans']), plan.project.root, false);
+    } catch {}
+    evidence(root, plan, 'apply', 'failed', { code: error.code ?? 'IDP_PROCESS_FAILED' });
+    throw error;
+  }
+}
+
+export function stopLocalSourceDeployment({ configRoot, applicationConfigRoot, planFile, runner = run }) {
+  const { plan, root } = readPlan(configRoot, planFile, applicationConfigRoot);
+  revalidate(plan, runner);
+  activeState(root, plan);
+  executeCompose(runner, composeArgs(plan, ['stop']), plan.project.root, false);
+  return evidence(root, plan, 'stop', 'stopped');
+}
+
+export function removeLocalSourceDeployment({ configRoot, applicationConfigRoot, planFile, confirmation, runner = run }) {
+  const { plan, root } = readPlan(configRoot, planFile, applicationConfigRoot);
+  invariant(confirmation === plan.application, 'IDP_LOCAL_REMOVE_CONFIRMATION_REQUIRED', `remove必须通过--confirm ${plan.application}精确确认`);
+  revalidate(plan, runner);
+  activeState(root, plan);
+  executeCompose(runner, composeArgs(plan, ['down', '--remove-orphans']), plan.project.root, false);
+  const candidate = statePath(root, plan.application);
+  if (fs.existsSync(candidate)) fs.unlinkSync(candidate);
+  return evidence(root, plan, 'remove', 'removed', { volumesRemoved: false });
+}

package/src/oci-mirror.mjs

@@ -0,0 +1,10 @@
+const PINNED_OFFICIAL_IMAGE = /^(?:(?:docker\.io|registry-1\.docker\.io)\/)?(?:library\/)?([a-z0-9][a-z0-9._-]*)(?::[A-Za-z0-9_][A-Za-z0-9_.-]{0,127})?@((?:sha256:)[0-9a-f]{64})$/u;
+
+export function dockerOfficialMirrorRef(ref) {
+  const match = PINNED_OFFICIAL_IMAGE.exec(ref ?? '');
+  return match ? `mirror.gcr.io/library/${match[1]}@${match[2]}` : null;
+}
+
+export function isDockerHubRateLimit(message) {
+  return /(?:429 Too Many Requests|toomanyrequests|rate limit)/iu.test(message ?? '');
+}