@xulthekl/team-flow 0.63.0 → 0.65.0

package/scripts/lib/arch-merge.mjs

@@ -26,6 +26,11 @@ import {
   extractTablesFromSql, readFrontmatter, PATH_CELL_RE,
 } from './arch-parse.mjs';
 import { detectWorkspaceRoot, getGitRoot, parsePorcelainPaths } from './git-utils.mjs';
+import {
+  emptyRegistry, loadRegistry, saveRegistry, registryPath,
+  validateDelta, applyDelta, seedRegistry, canonicalizeRegistry,
+  normalizeAggregateRow,
+} from './arch-registry.mjs';
 
 const MARKER_BEGIN = '<!-- arch:current-state:begin -->';
 const MARKER_END = '<!-- arch:current-state:end -->';
@@ -65,7 +70,7 @@ function releaseLock(lockPath) {
  * 全局文档维护 marker 区（当前态：BC/聚合注册表）+ 演进日志段。
  * marker 区重建 = 所有已合并 change 增量的投影（按聚合 id upsert，非原地编辑）。
  */
-function mergeArchitecture(changeDir, archDir, globalArchDir, changeName, projectRoot) {
+function mergeArchitecture(changeDir, archDir, globalArchDir, changeName, projectRoot, registry = null) {
   const srcPath = join(archDir, 'architecture.md');
   const dstPath = join(globalArchDir, 'ARCHITECTURE.md');
   if (!existsSync(srcPath)) return { merged: false, reason: 'no-source' };
@@ -93,7 +98,30 @@ function mergeArchitecture(changeDir, archDir, globalArchDir, changeName, projec
 
   const existing = existsSync(dstPath) ? readFileSync(dstPath, 'utf-8') : '';
   // v0.53.0 §108 R8：marker 区 = **已合并 change 的聚合全集投影**（非仅当前 change）
-  const allAggregates = collectAllAggregates(projectRoot, changeName, aggregates);
+  // O8 双路径：registry 非 null（delta 路径）→ marker 直接从 registry 渲染（单一真相源，
+  // §5.4-1「来源列由 source 渲染」）；null（legacy 软着陆路径）→ 既有重算逻辑不变。
+  let allAggregates;
+  let seeded = 0;
+  let registryMode = false;
+  const deltaMissing = [];
+  if (registry) {
+    registryMode = true;
+    allAggregates = registry.aggregates;
+    // 行为等价保护（软着陆）：current change 的聚合若 delta 未登记 → 机械补种 + WARN（不静默）
+    // P3 C-2：补种行经 normalize（context→bc + events 缺省），防落盘行违反 schema
+    for (const a of aggregates) {
+      if (!registry.aggregates.some(x => x.id === a.id)) {
+        registry.aggregates.push(normalizeAggregateRow(a, { source: `change:${changeName}` }));
+        deltaMissing.push(a.id);
+        seeded++;
+      }
+    }
+    if (deltaMissing.length > 0) {
+      console.warn(`  [WARN] delta 未登记本 change 聚合，已按 legacy 语义机械补种：${deltaMissing.join(', ')} — 请语义段核对 .arch-delta.json`);
+    }
+  } else {
+    ({ list: allAggregates, seeded } = collectAllAggregates(projectRoot, changeName, aggregates));
+  }
   const currentStateSection = buildCurrentStateSection(allAggregates);
 
   // marker 区替换（代码独占写）：存在则替换，缺失则插入
@@ -122,6 +150,8 @@ function mergeArchitecture(changeDir, archDir, globalArchDir, changeName, projec
     file: 'ARCHITECTURE.md',
     aggregates: aggregates.map(a => a.id),
     projected: allAggregates.length,
+    seeded, // P0-B'-① 快照只读 seed 条数；registry 路径 = current 补种条数
+    ...(registryMode ? { registry: true } : {}),
     ...(aggregates.length === 0 ? { reason: 'no-aggregate-delta' } : {}),
   };
 }
@@ -160,14 +190,130 @@ function collectAllAggregates(projectRoot, changeName, currentAggregates) {
   }
   // 当前 change 覆盖同 id 项（本次合并权威）
   for (const a of currentAggregates) collected.set(a.id, { ...a, source: `change:${changeName}` });
-  return [...collected.values()];
+  // P0-B'-① 最小替代：快照只读 seed，只补缺（最低优先级），见 seedFromSnapshots
+  const seeded = seedFromSnapshots(projectRoot, collected);
+  return { list: [...collected.values()], seeded };
+}
+
+/**
+ * P0-B'-① 最小替代：从产品级快照 `docs/architecture/iterations/<v>/architecture.md` 只读 seed 聚合。
+ *
+ * 修 R-a（投影域缺基线）：原投影域只有 changes/，产品级基线聚合在首次 change 回写后被
+ * 整片排除（emp-auth 实测 11+6 → 1）。本函数把快照聚合补进投影，但**每次 merge 重算、
+ * 不落盘**（治标——快照缺失/被归档时行仍会消失；治本 = P0-B'' 的 registry 持久化）。
+ *
+ * 设计要点（docs/plan/ddd-purity-and-arch-merge-design.md v1.4 §5.7 / §5.3 分档表 / 红牌 7）：
+ * - **provenance 分档**：仅 `reverse-engineered`（实测态反推）可 seed；
+ *   `forward-designed`（预测态）禁止进事实源；`mixed` 快照无节级标记 → 保守不 seed；
+ *   frontmatter 缺失同样保守跳过。跳过一律 log，不静默。
+ * - **优先级最低**：只补 collected 中不存在的 id——closed/current change 行恒优先
+ *   （快照是基线兜底，不是最新权威）；多个快照间按版本号升序合并、后序覆盖前序。
+ * - **source 标记** `base@snapshot-backfill`（§5.3 规定值）：当前态表内可辨识；
+ *   `extractAggregates` 回读时非 `change:` 前缀会置空 → conflictCheck 不把 seed 行
+ *   当作 change 所有权声明（后续 change 仍可正常声明同 id，与存量行为一致）。
+ */
+function seedFromSnapshots(projectRoot, collected) {
+  const iterDir = join(projectRoot, 'docs', 'architecture', 'iterations');
+  if (!existsSync(iterDir)) return 0;
+  const versions = readdirSync(iterDir)
+    .filter(n => /^v\d+$/.test(n))
+    .sort((a, b) => parseInt(a.slice(1), 10) - parseInt(b.slice(1), 10));
+  const snapAgg = new Map(); // id → aggregate；升序 set，后序快照覆盖前序同 id
+  for (const v of versions) {
+    const p = join(iterDir, v, 'architecture.md');
+    if (!existsSync(p)) continue;
+    const content = readFileSync(p, 'utf-8');
+    const provenance = readFrontmatter(content).provenance;
+    if (provenance !== 'reverse-engineered') {
+      console.log(`  [seed] iterations/${v}: provenance=${provenance || '(缺失)'} → 跳过（红牌 7 分档：仅 reverse-engineered 可 seed）`);
+      continue;
+    }
+    const snapAggs = extractAggregates(content);
+    if (snapAggs.length === 0) {
+      // P3 MIN-5：provenance 合格但聚合段定位/解析为空 → 不静默（表头失配有 WARN，标题失配没有）
+      console.log(`  [seed] iterations/${v}: provenance 合格但提取 0 条聚合 — 检查聚合注册表标题/表头`);
+    }
+    for (const a of snapAggs) {
+      snapAgg.set(a.id, { ...a, source: 'base@snapshot-backfill' });
+    }
+  }
+  let seeded = 0;
+  for (const [id, a] of snapAgg) {
+    if (collected.has(id)) continue;
+    collected.set(id, a);
+    seeded++;
+  }
+  if (seeded > 0) {
+    console.log(`  [seed] 快照只读 seed ${seeded} 条聚合（iterations/vN，reverse-engineered；每次 merge 重算，不落盘）`);
+  }
+  return seeded;
 }
 
 /** 构建当前态 marker 区内容（BC 表 + 聚合注册表，厚锚点一句话级；来源列标注真实来源 change）。 */
+/**
+ * O8 · 首跑 seed（红牌 12：registry 首次建立必须自动 seed，语义 = 既有累积状态的等价迁移）。
+ *
+ * seed 范围 = **基线**（不含 current change——current 经 `.arch-delta.json` 或物理事实补种进入）：
+ *   - aggregates：closed changes 投影 + 产品级快照（复用 collectAllAggregates，currentAggregates 传空）
+ *   - tables：schema-baseline.sql 既有表（上次 merge 为止的累积 DDL——本次 change 的 DDL 由
+ *     syncSchemaBaseline 之后的机械补种负责，见 run()）
+ *   - endpoints：API-INDEX.md 既有行（上次生成的权威快照）
+ * 只补缺不覆盖（seedRegistry 语义 = 最低优先级）。返回 { registry, seeded }。
+ */
+function seedRegistryFromLegacy(globalArchDir, projectRoot, changeName) {
+  let reg = loadRegistry(globalArchDir);
+  if (reg) return { registry: reg, seeded: 0, existed: true };
+
+  reg = emptyRegistry();
+  reg.updated_at = new Date().toISOString();
+  let seeded = 0;
+
+  // 聚合：closed changes + 快照 seed（current 传空 → 不含本次 change）
+  // P3 C-2：注入前 normalize（context→bc 映射 + events 缺省）——否则落盘行违反自身 schema（C-1）
+  const { list: baselineAggs } = collectAllAggregates(projectRoot, changeName, []);
+  seeded += seedRegistry(reg, { aggregates: baselineAggs.map(a => normalizeAggregateRow(a)) }, 'base').seeded;
+
+  // 表：schema-baseline.sql 既有累积
+  const schemaPath = join(globalArchDir, 'schema-baseline.sql');
+  if (existsSync(schemaPath)) {
+    const names = extractTablesFromSql(readFileSync(schemaPath, 'utf-8'));
+    seeded += seedRegistry(reg, {
+      tables: names.map(n => ({ name: n, ddl_ref: 'schema-baseline.sql' })),
+    }, 'base@schema-baseline').seeded;
+  }
+
+  // 端点：既有 API-INDEX.md（列 = 方法 | 路径 | 分流 | 来源）
+  const indexPath = join(globalArchDir, 'API-INDEX.md');
+  if (existsSync(indexPath)) {
+    const eps = [];
+    for (const line of readFileSync(indexPath, 'utf-8').split('\n')) {
+      const cells = parseTableRow(line);
+      if (!cells || cells.length < 4) continue;
+      const [method, path, kind, source] = cells;
+      if (!PATH_CELL_RE.test(path)) continue;
+      // P3 C-1：kind 归一化进 schema 枚举（server|feign）——legacy「分流」列装的是章节 kind
+      //（Command/Read/Query 等），非 feign 一律 server（feign 生产者见 I-7 登记，未实现前不产 feign）。
+      // P3 M-6：来源列是裸 change 目录名（不带 change: 前缀）→ 直接作归因，防 change:null 断链。
+      const change = source.startsWith('change:') ? source.slice(7)
+        : (/^[A-Za-z0-9][\w-]*$/.test(source) ? source : null);
+      eps.push({ method, path, kind: kind === 'feign' ? 'feign' : 'server', change });
+    }
+    seeded += seedRegistry(reg, { endpoints: eps }, 'base@api-index').seeded;
+  }
+
+  return { registry: reg, seeded, existed: false };
+}
+
+/**
+ * 渲染 marker 当前态区。入参兼容两种来源（O8 双路径并存期）：
+ *   - legacy：collectAllAggregates 行（字段 context，无 status → 视作已落地）
+ *   - registry：registry.aggregates 行（字段 bc + status: active|retired）
+ * 状态列由 registry 的生命周期字段驱动（红牌 6：retire 行保留可见、标已退役）。
+ */
 function buildCurrentStateSection(aggregates) {
   const bcMap = new Map();
   for (const a of aggregates) {
-    const bc = a.context || '（未标注）';
+    const bc = a.context || a.bc || '（未标注）';
     if (!bcMap.has(bc)) bcMap.set(bc, []);
     bcMap.get(bc).push(a);
   }
@@ -180,7 +326,8 @@ function buildCurrentStateSection(aggregates) {
   lines.push('', '### 聚合注册表');
   lines.push('| 聚合ID | 上下文 | 根实体 | 来源 | 状态 | 关键不变量 |', '|--------|--------|--------|------|------|-----------|');
   for (const a of aggregates) {
-    lines.push(`| ${a.id} | ${a.context || '—'} | ${a.root || '—'} | ${a.source || '—'} | 已落地 | ${a.invariants || '—'} |`);
+    const status = a.status === 'retired' ? '已退役' : '已落地';
+    lines.push(`| ${a.id} | ${a.context || a.bc || '—'} | ${a.root || '—'} | ${a.source || '—'} | ${status} | ${a.invariants || '—'} |`);
   }
   return lines.join('\n');
 }
@@ -295,17 +442,23 @@ function syncSchemaBaseline(changeDir, archDir, globalArchDir, changeName) {
 
 /* ============ 生成式产物：PHYSICAL-MODEL / DATABASE / API-INDEX ============ */
 
-/** Step 3: PHYSICAL-MODEL.md 生成式（从 schema-baseline.sql 反向生成，禁改）。 */
-function generatePhysicalModel(globalArchDir, schemaPath) {
+/** Step 3: PHYSICAL-MODEL.md 生成式。O8：registry 非 null → 从 registry.tables 出（R-b 改源）；null → legacy 从 schema-baseline.sql。 */
+function generatePhysicalModel(globalArchDir, schemaPath, registry = null) {
   const dstPath = join(globalArchDir, 'PHYSICAL-MODEL.md');
   const header = '# Physical Model（generated by arch-merge, do not edit）\n\n';
-  if (!existsSync(schemaPath)) {
+  let tables;
+  let sourceNote;
+  if (registry) {
+    tables = registry.tables.filter(t => t.status !== 'retired').map(t => t.name);
+    sourceNote = '> 从 registry.tables[] 自动生成（O8 改源，§5.4-5；source/生命周期为权威）。';
+  } else if (!existsSync(schemaPath)) {
     writeFile(dstPath, header + '> schema-baseline.sql 不存在，暂无物理模型。\n', 'utf-8');
     return { generated: true, file: 'PHYSICAL-MODEL.md', tables: 0 };
+  } else {
+    tables = extractTablesFromSql(readFileSync(schemaPath, 'utf-8'));
+    sourceNote = '> 从 schema-baseline.sql 自动生成（P2 机器管结构，DDL 为事实源；legacy 路径）。';
   }
-  const sql = readFileSync(schemaPath, 'utf-8');
-  const tables = extractTablesFromSql(sql);
-  const lines = [header, '> 从 schema-baseline.sql 自动生成（P2 机器管结构，DDL 为事实源）。\n'];
+  const lines = [header, sourceNote + '\n'];
   for (const t of tables) {
     lines.push(`### ${t}`, '', '| 字段 | 类型 | 约束 |', '|------|------|------|', '', '');
   }
@@ -313,20 +466,29 @@ function generatePhysicalModel(globalArchDir, schemaPath) {
   return { generated: true, file: 'PHYSICAL-MODEL.md', tables: tables.length };
 }
 
-/** Step 3b: DATABASE.md 生成式（从 schema-baseline + PHYSICAL-MODEL 再生成，禁改）。 */
-function generateDatabase(globalArchDir, schemaPath) {
+/** Step 3b: DATABASE.md 生成式。O8：registry 非 null → 从 registry.tables 出；null → legacy。 */
+function generateDatabase(globalArchDir, schemaPath, registry = null) {
   const dstPath = join(globalArchDir, 'DATABASE.md');
   const header = '# Database（generated by arch-merge, do not edit）\n\n';
-  if (!existsSync(schemaPath)) {
+  let tables;
+  let sourceCol;
+  let sourceNote;
+  if (registry) {
+    tables = registry.tables.filter(t => t.status !== 'retired').map(t => t);
+    sourceCol = 'registry.tables[]';
+    sourceNote = '> 从 registry.tables[] 再生成（O8 改源，§5.4-5；schema-baseline.sql 仍单向 append 作外部兼容，doctor 校验漂移）。';
+  } else if (!existsSync(schemaPath)) {
     writeFile(dstPath, header + '> schema-baseline.sql 不存在，暂无库表说明。\n', 'utf-8');
     return { generated: true, file: 'DATABASE.md', tables: 0 };
+  } else {
+    tables = extractTablesFromSql(readFileSync(schemaPath, 'utf-8')).map(n => ({ name: n }));
+    sourceCol = 'schema-baseline.sql';
+    sourceNote = '> 从 schema-baseline.sql + PHYSICAL-MODEL.md + changelog/ 再生成（v0.14 §62.2，构造上消除漂移；legacy 路径）。';
   }
-  const sql = readFileSync(schemaPath, 'utf-8');
-  const tables = extractTablesFromSql(sql);
-  const lines = [header, '> 从 schema-baseline.sql + PHYSICAL-MODEL.md + changelog/ 再生成（v0.14 §62.2，构造上消除漂移）。\n'];
+  const lines = [header, sourceNote + '\n'];
   lines.push('| 表名 | 来源 | 状态 |', '|------|------|------|');
   for (const t of tables) {
-    lines.push(`| ${t} | schema-baseline.sql | 实际落地 |`);
+    lines.push(`| ${t.name} | ${sourceCol} | 实际落地 |`);
   }
   writeFile(dstPath, lines.join('\n'), 'utf-8');
   return { generated: true, file: 'DATABASE.md', tables: tables.length };
@@ -357,7 +519,7 @@ function isChangeClosed(changeRoot) {
  * ③ 产出量对账（§104.2.2）——生成器原只判「源文件在不在」，从不判「吃进去多少 / 原文多少」，
  *    形态失配因此长期隐性。
  */
-function generateApiIndex(projectRoot, globalArchDir, changeName) {
+function generateApiIndex(projectRoot, globalArchDir, changeName, registry = null) {
   const changesDir = join(projectRoot, 'changes');
   const dstPath = join(globalArchDir, 'API-INDEX.md');
   const header = '# API Index（generated by arch-merge, do not edit）\n\n';
@@ -422,6 +584,50 @@ function generateApiIndex(projectRoot, globalArchDir, changeName) {
     return { generated: false, reason: 'endpoint-parse-mismatch', failures, warnings, file: 'API-INDEX.md', endpoints: endpoints.length };
   }
 
+  // ---- O8 registry 路径（§5.4-5 改源 + 物理事实机械补种）----
+  if (registry) {
+    // P3 M-2：registry 与扫描**双空**且既有文件存在 → 不覆写（对齐 legacy 空保护意图——
+    // 防「新机制把历史端点表清零」；registry 单边空而扫描有货则照常补种渲染）
+    if (registry.endpoints.filter(e => e.status !== 'retired').length === 0
+        && endpoints.length === 0 && existsSync(dstPath)) {
+      return {
+        generated: false,
+        reason: 'empty-registry-skip-overwrite',
+        warnings: [...warnings, 'registry 端点与扫描结果均为空，已保留既有 API-INDEX.md 未被覆盖（P3 M-2 空保护）'],
+        file: 'API-INDEX.md',
+        endpoints: 0,
+      };
+    }
+    // 机械补种：扫描到（物理事实 = api.md）而 registry 缺失的端点 → 补 + WARN（不静默；
+    // 与表的 DDL 补种对称——delta 的 endpoint 条目负责富化/retire 等语义意图）
+    const missing = [];
+    for (const e of endpoints) {
+      const key = `${e.method}:${e.path}`;
+      if (!registry.endpoints.some(x => `${x.method}:${x.path}` === key)) {
+        // P3 C-1/I-7：kind 归一化进 schema 枚举——e.kind 是章节 kind（Command/Read/Query…），
+        // 非 feign 一律 server；feign 生产者未实现（B10 登记，见 §12 I-7 处置）
+        registry.endpoints.push({
+          method: e.method, path: e.path, kind: e.kind === 'feign' ? 'feign' : 'server',
+          change: e.source, status: 'active', source: `change:${e.source}`,
+        });
+        missing.push(key);
+      }
+    }
+    if (missing.length > 0) {
+      warnings.push(`delta/api 未登记端点，已按扫描结果机械补种：${missing.slice(0, 10).join(', ')}${missing.length > 10 ? ' …' : ''}`);
+    }
+    const regEps = [...registry.endpoints]
+      .filter(e => e.status !== 'retired')
+      .sort((a, b) => `${a.method}${a.path}`.localeCompare(`${b.method}${b.path}`));
+    const lines = [header, '> 从 registry.endpoints[] 生成（O8 改源 §5.4-5；source 含 base/change 归属，kind 分流 = server|feign 审计 B10）。\n'];
+    lines.push('| 方法 | 路径 | 分流 | 来源 |', '|------|------|------|------|');
+    for (const e of regEps) {
+      lines.push(`| ${e.method} | ${e.path} | ${e.kind || 'server'} | ${e.source || '—'} |`);
+    }
+    writeFile(dstPath, lines.join('\n'), 'utf-8');
+    return { generated: true, file: 'API-INDEX.md', endpoints: regEps.length, warnings, failures: [] };
+  }
+
   // 空结果拒绝覆盖（数据丢失保护，**保留**）+ 可见化（§104 R4：不得静默）
   if (endpoints.length === 0 && existsSync(dstPath)) {
     return {
@@ -433,7 +639,7 @@ function generateApiIndex(projectRoot, globalArchDir, changeName) {
     };
   }
 
-  const lines = [header, '> 扫描 changes/**/api.md + domains/* 归一化端点重建（v0.14 §62.4）。\n'];
+  const lines = [header, '> 扫描 changes/**/api.md + domains/* 归一化端点重建（v0.14 §62.4；legacy 路径）。\n'];
   lines.push('| 方法 | 路径 | 分流 | 来源 |', '|------|------|------|------|');
   for (const e of endpoints) {
     // method 恒非空（§105.2.4「无方法即跳过」保证），故不再写 `—` 占位——
@@ -536,28 +742,36 @@ function conflictCheck(changeDir, archDir, globalArchDir, changeName) {
 /* ============ INDEX 确定性统计 ============ */
 
 /** Step 7: INDEX.md 确定性统计（表数解析 schema-baseline，端点数解析 API-INDEX 结构，非垃圾进垃圾出）。 */
-function updateIndex(globalArchDir, changeName) {
+function updateIndex(globalArchDir, changeName, registry = null) {
   const indexPath = join(globalArchDir, 'INDEX.md');
   const date = new Date().toISOString().slice(0, 10);
 
-  const bcCount = (() => {
-    const p = join(globalArchDir, 'ARCHITECTURE.md');
-    if (!existsSync(p)) return null;
-    const agg = extractAggregates(readFileSync(p, 'utf-8'));
-    return new Set(agg.map(a => a.context)).size;
-  })();
-
-  const tableCount = (() => {
-    const p = join(globalArchDir, 'schema-baseline.sql');
-    if (!existsSync(p)) return null;
-    return extractTablesFromSql(readFileSync(p, 'utf-8')).length;
-  })();
-
-  const endpointCount = (() => {
-    const p = join(globalArchDir, 'API-INDEX.md');
-    if (!existsSync(p)) return null;
-    return extractEndpoints(readFileSync(p, 'utf-8')).length;
-  })();
+  // O8 改源（§5.4-5：updateIndex 是 R-b 的隐蔽传播路径，必须同批改源——
+  // 否则出现「PHYSICAL-MODEL 修好了、INDEX 还写着 1 表」的自相矛盾）
+  const bcCount = registry
+    ? new Set(registry.aggregates.filter(a => a.status !== 'retired').map(a => a.bc || a.context).filter(Boolean)).size
+    : (() => {
+      const p = join(globalArchDir, 'ARCHITECTURE.md');
+      if (!existsSync(p)) return null;
+      const agg = extractAggregates(readFileSync(p, 'utf-8'));
+      return new Set(agg.map(a => a.context)).size;
+    })();
+
+  const tableCount = registry
+    ? registry.tables.filter(t => t.status !== 'retired').length
+    : (() => {
+      const p = join(globalArchDir, 'schema-baseline.sql');
+      if (!existsSync(p)) return null;
+      return extractTablesFromSql(readFileSync(p, 'utf-8')).length;
+    })();
+
+  const endpointCount = registry
+    ? registry.endpoints.filter(e => e.status !== 'retired').length
+    : (() => {
+      const p = join(globalArchDir, 'API-INDEX.md');
+      if (!existsSync(p)) return null;
+      return extractEndpoints(readFileSync(p, 'utf-8')).length;
+    })();
 
   const lines = [
     `# Architecture Index`,
@@ -584,16 +798,29 @@ function updateIndex(globalArchDir, changeName) {
 
 /* ============ Step 1: 预检 ============ */
 
-function preCheck(changeDir, archDir, projectRoot) {
+function preCheck(changeDir, archDir, projectRoot, light = false) {
   const conflicts = [];
   if (!existsSync(archDir)) {
     return { pass: false, conflicts: ['architecture/ directory not found in change'] };
   }
-  for (const f of ['architecture.md', 'database.md', 'api.md']) {
+  // v0.64.0（§4 D8，--light）：light 模式持久源只要求 architecture.md（聚合注册行 +
+  // 演进日志段 = marker 区投影唯一输入）；api.md/database.md 触及时才要求（调用方按
+  // touched surface 判定，此处仅对已存在文件做非空校验——缺失即该 sink 无增量，
+  // 生成式重建会安全保留旧表而非抹除）。full 模式维持三件套硬要求。
+  const required = light ? ['architecture.md'] : ['architecture.md', 'database.md', 'api.md'];
+  for (const f of required) {
     const fp = join(archDir, f);
     if (!existsSync(fp)) conflicts.push(`architecture/${f} missing`);
     else if (readFileSync(fp, 'utf-8').trim().length === 0) conflicts.push(`architecture/${f} empty`);
   }
+  if (light) {
+    for (const f of ['database.md', 'api.md']) {
+      const fp = join(archDir, f);
+      if (existsSync(fp) && readFileSync(fp, 'utf-8').trim().length === 0) {
+        conflicts.push(`architecture/${f} empty (present but blank — delete it or fill the delta)`);
+      }
+    }
+  }
   return { pass: conflicts.length === 0, conflicts };
 }
 
@@ -705,6 +932,7 @@ export function run(args = {}) {
     for (let i = 0; i < args.length; i++) {
       if (args[i] === '--project-root' && args[i + 1] && !args[i + 1].startsWith('--')) parsed.projectRoot = args[++i];
       else if (args[i] === '--dry-run') parsed.dryRun = true;
+      else if (args[i] === '--light') parsed.light = true;
       else if (!args[i].startsWith('--')) parsed._.push(args[i]);
     }
     args = parsed;
@@ -712,8 +940,9 @@ export function run(args = {}) {
 
   const changeDir = args._?.[0] || args.changeDir;
   const dryRun = args.dryRun || false;
+  const light = args.light || false; // v0.64.0 §4 D8：planned 轻回写入口
   if (!changeDir) {
-    console.error('Usage: tf arch-merge <change-dir> [--project-root <path>] [--dry-run]');
+    console.error('Usage: tf arch-merge <change-dir> [--project-root <path>] [--dry-run] [--light]');
     process.exit(1);
   }
 
@@ -733,6 +962,7 @@ export function run(args = {}) {
   console.log(`  Source: ${archDir}`);
   console.log(`  Target: ${globalArchDir}`);
   if (dryRun) console.log(`  Mode: DRY-RUN`);
+  if (light) console.log(`  Mode: LIGHT（minimal persistent source: architecture.md + present deltas；同 sink 同生成器）`);
 
   // 写锁（硬门禁 3）
   const lockPath = acquireLock(projectRoot);
@@ -740,7 +970,7 @@ export function run(args = {}) {
     if (!existsSync(globalArchDir)) makeDir(globalArchDir);
 
     // Step 1: 预检
-    const preCheckResult = preCheck(changeDir, archDir, projectRoot);
+    const preCheckResult = preCheck(changeDir, archDir, projectRoot, light);
     if (!preCheckResult.pass) {
       console.error('  Pre-check FAILED:');
       for (const c of preCheckResult.conflicts) console.error(`    - ${c}`);
@@ -770,28 +1000,139 @@ export function run(args = {}) {
       };
     }
 
-    // Step 2: ARCHITECTURE.md（当前态 upsert）
-    const archResult = mergeArchitecture(changeDir, archDir, globalArchDir, changeName, projectRoot);
+    // ---- Step 1c（O8 · §5.4-7 软着陆双路径）：.arch-delta.json 存在 → registry 路径 ----
+    // seed 先于 delta（R3-3）：首跑 seed 基线（closed changes + 快照 + 既有 DDL/API-INDEX），
+    // 再消费 delta；缺失 → legacy 重算路径（软着陆期合法，v0.66.0 硬切）。
+    const deltaPath = join(archDir, '.arch-delta.json');
+    let registry = null;
+    const registryWarnings = [];
+    if (existsSync(deltaPath)) {
+      const seedRes = seedRegistryFromLegacy(globalArchDir, projectRoot, changeName);
+      registry = seedRes.registry;
+      if (!seedRes.existed && seedRes.seeded > 0) {
+        console.log(`  [registry] 首跑 seed ${seedRes.seeded} 条基线（schema 冻结版含 events/context_map 预留）`);
+      }
+      let delta;
+      try {
+        delta = JSON.parse(readFileSync(deltaPath, 'utf-8'));
+      } catch (e) {
+        abort(`.arch-delta.json 解析失败（${e.message}）——语义段制品损坏，禁止静默继续`);
+      }
+      const dvErrs = validateDelta(delta, { changeDir });
+      const structural = dvErrs.filter(e => !e.startsWith('EVIDENCE:'));
+      const evidenceIssues = dvErrs.filter(e => e.startsWith('EVIDENCE:'));
+      if (structural.length > 0) {
+        abort(`.arch-delta.json 结构校验失败（结构坏无法安全消费）：\n  - ${structural.join('\n  - ')}\n（A8 机械层；evidence 内容正确性另属人审）`);
+      }
+      // P3 I-2：软着陆期 evidence 缺失/引用文件不存在 → WARN + 条目照常消费（设计 §5.4-4c 与
+      // ①-pre SKILL 的契约）；v0.66.0 硬切时此处改 abort。结构错误与 evidence 错误严格分流。
+      if (evidenceIssues.length > 0) {
+        registryWarnings.push(...evidenceIssues.map(e =>
+          `${changeName}：[软着陆] ${e.replace(/^EVIDENCE:\s*/, '')} — 条目照常消费（v0.66.0 起将 abort）`));
+      }
+      const applyRes = applyDelta(registry, delta, { changeName, hard: false });
+      if (applyRes.violations.length > 0) {
+        abort(`delta 违约：\n  - ${applyRes.violations.join('\n  - ')}`);
+      }
+      registry = applyRes.registry;
+      registry.updated_at = new Date().toISOString();
+      registryWarnings.push(...applyRes.warnings.map(w => `${changeName}：${w}`));
+      console.log(`  [registry] delta 应用 ${applyRes.applied.length} 条（软着陆 hard=false；warnings=${applyRes.warnings.length}）`);
+    }
+
+    // Step 2: ARCHITECTURE.md（当前态 upsert）——registry 非 null 时 marker 从 registry 渲染
+    const archResult = mergeArchitecture(changeDir, archDir, globalArchDir, changeName, projectRoot, registry);
 
     // Step 4: schema-baseline.sql（幂等追加）——先同步 DDL，供 PHYSICAL-MODEL/DATABASE 生成消费
     const schemaResult = syncSchemaBaseline(changeDir, archDir, globalArchDir, changeName);
 
-    // Step 3: PHYSICAL-MODEL.md（生成式，从 schema-baseline.sql）
-    const pmResult = generatePhysicalModel(globalArchDir, schemaPath);
+    // O8 · 表的物理事实机械补种（红牌 12：seed 语义 = 既有 append 语义的等价物）：
+    // 本次 change 的 DDL 表若 registry 缺失 → 补入（source=change:<name>）+ WARN。
+    // delta 的 table 条目负责富化/retire 等语义意图；DDL 是物理事实，不依赖 LLM 枚举。
+    if (registry) {
+      const ddlDir = join(archDir, 'sql', 'ddl');
+      if (existsSync(ddlDir)) {
+        const names = [];
+        for (const f of readdirSync(ddlDir).filter(x => x.endsWith('.sql'))) {
+          names.push(...extractTablesFromSql(readFileSync(join(ddlDir, f), 'utf-8')));
+        }
+        const before = registry.tables.length;
+        seedRegistry(registry, { tables: names.map(n => ({ name: n, ddl_ref: `changes/${changeName}/architecture/sql/ddl` })) }, `change:${changeName}`);
+        const added = registry.tables.length - before;
+        if (added > 0) {
+          registryWarnings.push(`${changeName}：DDL 补种 ${added} 张表进 registry（delta 未登记的物理事实——请语义段核对 .arch-delta.json）`);
+        }
+      }
+    }
 
-    // Step 3b: DATABASE.md（生成式，从 schema-baseline.sql）
-    const dbResult = generateDatabase(globalArchDir, schemaPath);
+    // Step 3: PHYSICAL-MODEL.md（生成式；registry 模式从 registry.tables，legacy 从 schema-baseline.sql）
+    const pmResult = generatePhysicalModel(globalArchDir, schemaPath, registry);
+
+    // Step 3b: DATABASE.md（生成式；同上双源）
+    const dbResult = generateDatabase(globalArchDir, schemaPath, registry);
 
     // Step 5: 归档
     const archiveResult = archiveChangeScripts(changeDir, archDir, globalArchDir, changeName);
 
-    // Step 6: API-INDEX.md（生成式）
-    const apiResult = generateApiIndex(projectRoot, globalArchDir, changeName);
+    // Step 6: API-INDEX.md（生成式；registry 模式从 registry.endpoints + 扫描补种）
+    const apiResult = generateApiIndex(projectRoot, globalArchDir, changeName, registry);
+
+    // Step 7: INDEX.md（O8 改源：registry 模式计数取 registry，防「PM 修好 INDEX 还写 1 表」）
+    const indexResult = updateIndex(globalArchDir, changeName, registry);
+
+    // ---- A6/§5.4-4 守恒断言（分级：C2 B级·在册下界 / C3 半级；红牌 9 —— B/C 级不冒充 A 级护栏）----
+    // C4（A 级）依赖 scan-code + doctor，归属 §7 的 P3 存量迁移批（M1 rebuild 第 4 级取源，须 LT 授权），
+    // 不在本批运行时接线；A1 的模块级可达性由 tests 断言（scanCode → seedRegistry 组合）。
+    if (registry && registryWarnings /* 数组恒存在，仅借位标识 registry 模式 */) {
+      // C2 scope（R3-2③）：已关闭 | closing | 当前 change 的手写 DDL
+      const ddlTables = new Set();
+      const changesRoot = join(projectRoot, 'changes');
+      if (existsSync(changesRoot)) {
+        for (const name of readdirSync(changesRoot)) {
+          if (name !== changeName) {
+            const r = join(changesRoot, name);
+            if (!isChangeClosed(r)) continue;
+          }
+          const d = join(changesRoot, name, 'architecture', 'sql', 'ddl');
+          if (!existsSync(d)) continue;
+          for (const f of readdirSync(d).filter(x => x.endsWith('.sql'))) {
+            for (const t of extractTablesFromSql(readFileSync(join(d, f), 'utf-8'))) ddlTables.add(t);
+          }
+        }
+      }
+      const c2Missing = [...ddlTables].filter(n => !registry.tables.some(t => t.name === n)).sort();
+      if (c2Missing.length > 0) {
+        registryWarnings.push(`${changeName}：[C2·B级下界] registry 缺手写 DDL 表 ${c2Missing.join(', ')}——检出后须人工核对 delta/补种链（C2 仅下界，对无 DDL change 空集恒真，不得当 A 级护栏）`);
+      }
+      // C3（半级）：registry.endpoints 对 api.md 扫描集——generateApiIndex 已机械补种，
+      // 此处仅对账「registry 是否含扫描集」（正常恒真；改坏补种链时变红——正向存在性）
+      const apiC3Missing = [];
+      if (existsSync(changesRoot)) {
+        for (const name of readdirSync(changesRoot)) {
+          if (name !== changeName) {
+            const r = join(changesRoot, name);
+            if (!isChangeClosed(r)) continue;
+          }
+          const p = join(changesRoot, name, 'architecture', 'api.md');
+          if (!existsSync(p)) continue;
+          for (const e of extractEndpointsDetailed(readFileSync(p, 'utf-8')).endpoints) {
+            if (!registry.endpoints.some(x => x.method === e.method && x.path === e.path)) {
+              apiC3Missing.push(`${e.method}:${e.path}`);
+            }
+          }
+        }
+      }
+      if (apiC3Missing.length > 0) {
+        registryWarnings.push(`${changeName}：[C3·半级] registry 缺 api.md 端点 ${apiC3Missing.slice(0, 8).join(', ')}——api.md 由 LLM 写且计数受解析影响，仅作半级对账，须人工核对`);
+      }
+    }
 
-    // Step 7: INDEX.md
-    const indexResult = updateIndex(globalArchDir, changeName);
+    // O8 · registry 落盘（唯一持久化点；DRY_RUN 零副作用，红牌 10）
+    if (registry && !DRY_RUN) {
+      saveRegistry(globalArchDir, registry);
+    }
 
-    // Step 8: 白名单 git commit
+    // Step 8: 白名单 git commit（O8-2：追加 .registry/ 产出文件——LT 裁定归属本批）
     const touchedFiles = [
       join(globalArchDir, 'ARCHITECTURE.md'),
       join(globalArchDir, 'PHYSICAL-MODEL.md'),
@@ -799,6 +1140,7 @@ export function run(args = {}) {
       join(globalArchDir, 'schema-baseline.sql'),
       join(globalArchDir, 'API-INDEX.md'),
       join(globalArchDir, 'INDEX.md'),
+      ...(registry ? [registryPath(globalArchDir)] : []), // O8：registry 进提交（登记不 commit = AT-2 修复）
       ...(archiveResult.files || []),  // v0.36.3：changelog/ 复制文件入白名单
     ].filter(p => existsSync(p));
     const dirty = detectUntouchedDirtyFiles(projectRoot, globalArchDir, touchedFiles);
@@ -815,6 +1157,11 @@ export function run(args = {}) {
     const warnings = [
       ...(conflictResult.warnings || []),
       ...(apiResult.warnings || []),
+      // O8 · 软着陆登记（§5.4-7：复用既有登记族语义，不新增 DEPRECATED-* 告警族）
+      ...(registry === null
+        ? [`${changeName}：.arch-delta.json 缺失 → legacy 回写路径（软着陆期合法，v0.66.0 起硬切；如需登记理由按 arch_merge_skip_reason 同族补记）`]
+        : []),
+      ...registryWarnings,
       ...(archResult.reason === 'no-aggregate-delta'
         ? [`${changeName}：本 change 无聚合增量（aggregate_action: none），marker 区按已合并 change 全集投影，未新增聚合行`]
         : []),
@@ -893,6 +1240,9 @@ export function scaffoldGlobalLedger(projectRoot) {
   // 空 marker 区骨架（与 buildCurrentStateSection 同源）。
   // 带 H1 与内容归属说明（v0.53.0 §115.6，P4 反馈 m2 / 问题8）：同批其他制品均有 H1，
   // 且需澄清「As-Is 叙述写哪」——arch-merge 只重写 marker 区**之间**，区外内容保留。
+  // O8 / D-6 复核（P0-B''）：scaffold **不产 `.registry/`**——M6 冷启动语义 = registry 由
+  // 首次带 delta 的 arch-merge 自动 seed 建立（红牌 12）；空 marker 骨架与 registry 渲染
+  // 输出同构（buildCurrentStateSection 同源），首 merge 替换即接管，无需本函数改动。
   writeIfAbsent('ARCHITECTURE.md', () => [
     '# Architecture',
     '',