@xulthekl/team-flow 0.64.0 → 0.65.0

package/scripts/lib/arch-registry.mjs

@@ -0,0 +1,523 @@
+// scripts/lib/arch-registry.mjs — O8 registry 持久层（P0-B''，A1）
+// 设计：docs/plan/ddd-purity-and-arch-merge-design.md v1.5 §5.4-1（schema）/ §5.4-4c（delta）/
+//       §5.4-2（base = source:base* 无特殊地位）/ §8 红牌 6/10（删除须显式 · 零依赖可重放）
+//
+// 存储：`docs/architecture/.registry/registry.json`（唯一存储；JSON——红牌 10 禁 YAML 依赖）。
+// 约束：
+//   - 固定键序 + 条目按稳定键排序 → 同输入逐字节相同（可重放）
+//   - `source: base | change:<name>` 全段必填（guard 双通道判定输入 + 审计追溯键）
+//   - 删除仅经 retire（status: retired + reason + retired_in_change），禁止静默消失
+//   - events[]（O4）/ context_map[]（O7）在本 schema 冻结时即预留 —— §3 依赖不是空头支票
+//
+// schema 冻结补充定义（设计未明写、由实施补齐，已记 §12）：
+//   - event 条目 key = 事件名（全局命名约定 OrderPlaced 风格）；owner 由 fields 表达
+//   - context_map 条目 key = `<source_bc>→<target_bc>`（关系方向敏感）
+//   - 各段统一附 `status: active | retired`（retire 规则对全部 kind 生效，红牌 6）
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const REGISTRY_SCHEMA_VERSION = 1;
+/** 相对 docs/architecture/ 的存储路径 */
+export const REGISTRY_REL_PATH = path.join('.registry', 'registry.json');
+
+export const DELTA_KINDS = ['aggregate', 'bounded_context', 'subdomain', 'table', 'endpoint', 'event', 'context_map'];
+export const DELTA_OPS = ['new', 'extend', 'refactor', 'retire'];
+/** O7 上下文映射 8 模式（经典 Context Mapping 全集，schema 冻结即约束枚举） */
+export const CONTEXT_MAP_PATTERNS = [
+  'Shared Kernel', 'Customer-Supplier', 'Conformist', 'Anti-Corruption Layer',
+  'Open Host Service', 'Separate Ways', 'Partnership', 'Published Language',
+];
+/** O3 子域三分类 */
+export const SUBDOMAIN_CLASSES = ['Core', 'Supporting', 'Generic'];
+
+/** 空 registry（五段 + schema 头）。键序即序列化键序。 */
+export function emptyRegistry() {
+  return {
+    schema_version: REGISTRY_SCHEMA_VERSION,
+    updated_at: null,
+    aggregates: [],
+    bounded_contexts: [],
+    subdomains: [],
+    tables: [],
+    endpoints: [],
+  };
+}
+
+/* ============ 序列化：固定键序 + 稳定排序（红牌 10 可重放） ============ */
+
+const SEGMENT_KEYS = {
+  // reason / retired_in_change：retire/refactor 审计元数据必须落盘（红牌 6 落盘态——
+  // 缺它们则 status:retired 无出处，审计断链；P3 M 级自查补入）
+  aggregates: ['id', 'name', 'bc', 'root', 'owner_change', 'status', 'source', 'events', 'invariants', 'reason', 'retired_in_change'],
+  bounded_contexts: ['id', 'name', 'responsibility', 'aggregates', 'context_map', 'status', 'source', 'reason', 'retired_in_change'],
+  subdomains: ['id', 'name', 'classification', 'business_problem', 'status', 'source', 'reason', 'retired_in_change'],
+  tables: ['name', 'change', 'ddl_ref', 'status', 'source', 'reason', 'retired_in_change'],
+  endpoints: ['method', 'path', 'kind', 'change', 'status', 'source', 'reason', 'retired_in_change'],
+};
+
+/**
+ * 聚合行规范化（P3 C-2 修复）：把 extractAggregates 的 `context` 字段映射为持久层契约 `bc`，
+ * 并补齐 `events`/`name` 缺省——seed/机械补种注入点统一走本函数，防落盘行违反自身 schema（C-1）。
+ */
+export function normalizeAggregateRow(a, { source, status } = {}) {
+  return {
+    id: a.id,
+    name: a.name ?? a.id,
+    bc: a.bc ?? a.context ?? null,
+    root: a.root ?? null,
+    owner_change: a.owner_change ?? null,
+    status: status ?? a.status ?? 'active',
+    source: source ?? a.source,
+    events: Array.isArray(a.events) ? a.events : [],
+    invariants: a.invariants ?? null,
+    ...(a.reason !== undefined ? { reason: a.reason } : {}),
+    ...(a.retired_in_change !== undefined ? { retired_in_change: a.retired_in_change } : {}),
+  };
+}
+
+function projectKeys(obj, keys) {
+  const out = {};
+  for (const k of keys) if (obj[k] !== undefined) out[k] = obj[k];
+  // 白名单外字段丢弃前先暴露：静默丢字段违反"不静默"——validateRegistry 负责报错，
+  // 序列化层只做投影（调用序列：validate → sort → save）。
+  return out;
+}
+
+function compareBy(...keys) {
+  return (a, b) => {
+    for (const k of keys) {
+      const av = String(a[k] ?? '');
+      const bv = String(b[k] ?? '');
+      if (av !== bv) return av < bv ? -1 : 1;
+    }
+    return 0;
+  };
+}
+
+/** 按稳定键排序各段（原地）。子结构：events 按 name；context_map 按 key；bc.aggregates 按 id。 */
+export function sortRegistry(reg) {
+  reg.aggregates.sort(compareBy('id'));
+  reg.bounded_contexts.sort(compareBy('id'));
+  reg.subdomains.sort(compareBy('id'));
+  reg.tables.sort(compareBy('name'));
+  reg.endpoints.sort(compareBy('method', 'path'));
+  for (const a of reg.aggregates) {
+    if (Array.isArray(a.events)) a.events.sort(compareBy('name'));
+  }
+  for (const bc of reg.bounded_contexts) {
+    if (Array.isArray(bc.aggregates)) bc.aggregates.sort();
+    if (Array.isArray(bc.context_map)) bc.context_map.sort(compareBy('key'));
+  }
+  return reg;
+}
+
+/** 规范化为可序列化对象：固定键序投影 + 排序。 */
+export function canonicalizeRegistry(reg) {
+  const out = {
+    schema_version: reg.schema_version ?? REGISTRY_SCHEMA_VERSION,
+    updated_at: reg.updated_at ?? null,
+  };
+  for (const [seg, keys] of Object.entries(SEGMENT_KEYS)) {
+    out[seg] = (reg[seg] || []).map(item => projectKeys(item, keys));
+  }
+  sortRegistry(out);
+  return out;
+}
+
+/* ============ 读写 ============ */
+
+export function registryPath(globalArchDir) {
+  return path.join(globalArchDir, REGISTRY_REL_PATH);
+}
+
+/** 读 registry；文件不存在 → null（调用方决定是否首跑 seed）。解析失败 → throw（不静默产出半份）。 */
+export function loadRegistry(globalArchDir) {
+  const p = registryPath(globalArchDir);
+  if (!fs.existsSync(p)) return null;
+  const reg = JSON.parse(fs.readFileSync(p, 'utf-8'));
+  const errors = validateRegistry(reg);
+  if (errors.length > 0) {
+    throw new Error(`registry schema 校验失败（${p}）：\n  - ${errors.join('\n  - ')}`);
+  }
+  return reg;
+}
+
+/**
+ * 固定键序 + 排序后写盘。返回写入路径。
+ * ★ 双防线（P3 C-1/M-1 修复）：
+ *   1. 写盘前 validateRegistry——违反 schema 一律拒绝落盘（fail-closed：写不出去好过写出坏文件，
+ *      坏文件会让此后每次 load 必炸且不可自愈）；
+ *   2. run 级幂等（红牌 10/I-5）：内容（除 updated_at）与磁盘一致 → 不写盘，保留旧时间戳，
+ *      同输入重跑逐字节不变。
+ */
+export function saveRegistry(globalArchDir, reg) {
+  const errors = validateRegistry(reg);
+  if (errors.length > 0) {
+    throw new Error(`拒绝写出违反 schema 的 registry：\n  - ${errors.join('\n  - ')}`);
+  }
+  const canonical = canonicalizeRegistry(reg);
+  const p = registryPath(globalArchDir);
+  if (fs.existsSync(p)) {
+    try {
+      const prev = JSON.parse(fs.readFileSync(p, 'utf-8'));
+      if (JSON.stringify({ ...prev, updated_at: canonical.updated_at }) === JSON.stringify(canonical)) {
+        return p; // 内容无实质变化：不写（保留磁盘旧 updated_at）
+      }
+    } catch { /* 磁盘损坏 → 走下方写入以新内容修复 */ }
+  }
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(canonical, null, 2) + '\n', 'utf-8');
+  return p;
+}
+
+/* ============ 校验（A8：机械层——结构/必填/枚举；evidence 内容正确性属人审） ============ */
+
+export function validateRegistry(reg) {
+  const errors = [];
+  if (!reg || typeof reg !== 'object') return ['registry 不是对象'];
+  if (reg.schema_version !== REGISTRY_SCHEMA_VERSION) {
+    errors.push(`schema_version 须为 ${REGISTRY_SCHEMA_VERSION}，实为 ${reg.schema_version}`);
+  }
+  const sourceOk = s => typeof s === 'string' && (s === 'base' || s.startsWith('base@') || s.startsWith('change:'));
+  const statusOk = s => s === undefined || s === 'active' || s === 'retired';
+
+  for (const seg of Object.keys(SEGMENT_KEYS)) {
+    if (!Array.isArray(reg[seg])) { errors.push(`${seg} 须为数组`); continue; }
+    for (const item of reg[seg]) {
+      const label = `${seg}[${item.id ?? item.name ?? item.path ?? '?'}]`;
+      if (!sourceOk(item.source)) errors.push(`${label}: source 必填（base | base@* | change:<name>），实为 ${JSON.stringify(item.source)}`);
+      if (!statusOk(item.status)) errors.push(`${label}: status 须 active|retired`);
+    }
+  }
+  // 分段必填（按 §5.4-1 字段清单）
+  for (const a of reg.aggregates || []) {
+    if (!a.id) errors.push('aggregates[] 缺 id');
+    if (!('bc' in a)) errors.push(`aggregates[${a.id}]: 缺 bc 字段（持久层契约字段——context 注入时须映射，C-2 防线）`);
+    if (!Array.isArray(a.events)) errors.push(`aggregates[${a.id}]: events 须为数组（O4 登记载体，可为空）`);
+    else if (a.events.some(e => !e || !e.name)) errors.push(`aggregates[${a.id}]: events 条目须含 name`);
+  }
+  for (const bc of reg.bounded_contexts || []) {
+    if (!bc.id) errors.push('bounded_contexts[] 缺 id');
+    if (!Array.isArray(bc.context_map)) errors.push(`bounded_contexts[${bc.id}]: context_map 须为数组（O7 登记载体）`);
+    else {
+      // M-4：O7 八模式枚举 enforcement（枚举冻结不校验 = 零判别力）
+      for (const cm of bc.context_map) {
+        if (!cm || !cm.pattern) errors.push(`bounded_contexts[${bc.id}].context_map[${cm?.key ?? '?'}]: 缺 pattern（O7 八模式必填）`);
+        else if (!CONTEXT_MAP_PATTERNS.includes(cm.pattern)) {
+          errors.push(`bounded_contexts[${bc.id}].context_map[${cm.key}]: pattern ${JSON.stringify(cm.pattern)} 不在 O7 八模式枚举内`);
+        }
+      }
+    }
+  }
+  for (const sd of reg.subdomains || []) {
+    if (!sd.id) errors.push('subdomains[] 缺 id');
+    if (!SUBDOMAIN_CLASSES.includes(sd.classification)) {
+      errors.push(`subdomains[${sd.id}]: classification 须 Core|Supporting|Generic`);
+    }
+    // O3 红线：子域描述不得含实现载体名（反例校验，与模板/评审门同口径）
+    if (sd.business_problem && /\b\w*Service\b|\b\w*Impl\b|com\.\w+/.test(sd.business_problem)) {
+      errors.push(`subdomains[${sd.id}]: business_problem 含实现载体词（问题空间 ≠ 解空间）`);
+    }
+  }
+  for (const t of reg.tables || []) {
+    if (!t.name) errors.push('tables[] 缺 name');
+  }
+  for (const e of reg.endpoints || []) {
+    if (!e.method || !e.path) errors.push(`endpoints[${e.method}:${e.path}]: method/path 必填`);
+    if (e.kind !== undefined && !['server', 'feign'].includes(e.kind)) {
+      errors.push(`endpoints[${e.method}:${e.path}]: kind 须 server|feign（审计 B10 分流）`);
+    }
+  }
+  return errors;
+}
+
+/**
+ * delta 结构校验（§5.4-4c；A8 强度分级：结构错误 = abort 级；evidence 类错误带 `EVIDENCE:`
+ * 前缀返回，由调用方按软着陆策略分流（P3 I-2：软着陆期 WARN 不 abort、v0.66.0 硬切 abort）。
+ * evidence 机械层 = 非空 +（给定 changeDir 时）引用文件真实存在——内容正确性仍属人审。
+ */
+export function validateDelta(delta, { changeDir } = {}) {
+  const errors = [];
+  if (!delta || typeof delta !== 'object') return ['delta 不是对象'];
+  if (delta.delta_version !== 1) errors.push('delta_version 须为 1');
+  if (!delta.change || typeof delta.change !== 'string') errors.push('change 必填');
+  if (!Array.isArray(delta.entries)) { errors.push('entries 须为数组'); return errors; }
+  delta.entries.forEach((e, i) => {
+    const at = `entries[${i}]`;
+    if (!DELTA_KINDS.includes(e.kind)) errors.push(`${at}: kind 非法（${e.kind}）`);
+    if (!DELTA_OPS.includes(e.op)) errors.push(`${at}: op 非法（${e.op}）`);
+    if (!e.key || typeof e.key !== 'string') errors.push(`${at}: key 必填`);
+    if (e.op === 'refactor' && !e.prev_key) errors.push(`${at}: refactor 须 prev_key`);
+    if ((e.op === 'retire' || e.op === 'refactor') && !e.reason) errors.push(`${at}: ${e.op} 须 reason`);
+    if (e.op === 'new' || e.op === 'extend') {
+      if (!e.evidence || !String(e.evidence).trim()) {
+        errors.push(`EVIDENCE: ${at}: ${e.op} 须 evidence（防幻觉机械层——非空 + 可定位）`);
+      } else if (changeDir) {
+        // I-1：路径存在性半边（A8「其引用的路径在 change 内真实存在」）
+        const file = String(e.evidence).split(/[:#§]/)[0].trim();
+        if (file && !file.startsWith('/') && !fs.existsSync(path.join(changeDir, file))) {
+          errors.push(`EVIDENCE: ${at}: evidence 引用的文件在 change 内不存在（${file}）`);
+        }
+      }
+    }
+    if (e.fields !== undefined && (typeof e.fields !== 'object' || e.fields === null || Array.isArray(e.fields))) {
+      errors.push(`${at}: fields 须为对象`);
+    }
+  });
+  return errors;
+}
+
+/* ============ delta 消费：op 匹配规则（§5.4-4c 表；R3-3 seed 先行由调用方保证） ============ */
+
+function segmentOf(reg, kind) {
+  const map = {
+    aggregate: 'aggregates', bounded_context: 'bounded_contexts', subdomain: 'subdomains',
+    table: 'tables', endpoint: 'endpoints',
+    // event / context_map 是子结构：宿主分别为 aggregates[] / bounded_contexts[]
+  };
+  return map[kind];
+}
+
+function findEntry(reg, kind, key) {
+  if (kind === 'event') {
+    for (const a of reg.aggregates) {
+      const ev = (a.events || []).find(x => x.name === key);
+      if (ev) return { host: a, entry: ev, list: a.events, segLabel: `aggregates[${a.id}].events` };
+    }
+    return null;
+  }
+  if (kind === 'context_map') {
+    for (const bc of reg.bounded_contexts) {
+      const cm = (bc.context_map || []).find(x => x.key === key);
+      if (cm) return { host: bc, entry: cm, list: bc.context_map, segLabel: `bounded_contexts[${bc.id}].context_map` };
+    }
+    return null;
+  }
+  const seg = segmentOf(reg, kind);
+  const idField = kind === 'table' ? 'name' : kind === 'endpoint' ? null : 'id';
+  const found = (reg[seg] || []).find(x => {
+    if (kind === 'table') return x.name === key;
+    if (kind === 'endpoint') return `${x.method}:${x.path}` === key;
+    return x[idField] === key;
+  });
+  return found ? { host: null, entry: found, list: reg[seg], segLabel: seg } : null;
+}
+
+/**
+ * 消费一份 delta，返回新 registry。
+ * @param {object} reg 当前 registry（会被复制修改，不改入参）
+ * @param {object} delta `.arch-delta.json`
+ * @param {object} opts { changeName, hard?: boolean } —— hard=false（软着陆，v0.65.0 默认）：
+ *        违约降级为 warnings；hard=true（v0.66.0 硬切）：违约进 violations，调用方须 abort。
+ * @returns {{ registry, applied: string[], warnings: string[], violations: string[] }}
+ */
+export function applyDelta(reg, delta, { changeName, hard = false } = {}) {
+  const warnings = [];
+  const violations = [];
+  const applied = [];
+  const out = JSON.parse(JSON.stringify(reg)); // 深拷贝（结构简单，JSON 足够）
+  const src = `change:${changeName ?? delta.change}`;
+  const record = msg => { if (hard) violations.push(msg); else warnings.push(msg); };
+
+  // 确定性：按 kind 再按 key 排序处理（不依赖 LLM 输出顺序，红牌 10）
+  const entries = [...delta.entries].sort((a, b) =>
+    (a.kind + a.key).localeCompare(b.kind + b.key));
+
+  for (const e of entries) {
+    const found = findEntry(out, e.kind, e.key);
+
+    if (e.op === 'new') {
+      if (found) {
+        // 软着陆：seed 键 / 既有键上写 new → WARN 视作 extend（R3-3；硬切 abort）
+        record(`new 冲突：${e.kind} ${e.key} 已存在（seed 或既有）→ 视作 extend（R3-3 对称处置）`);
+        mergeFields(found.entry, e.fields);
+        applied.push(`extend(by-new-conflict):${e.kind}:${e.key}`);
+        continue;
+      }
+      // P3 I-6 幻影宿主防线：宿主字段已填但宿主不存在 → 不造无从区分的壳行（typo 即污染事实源），
+      // 记录后跳过（软着陆 WARN / 硬切 violation）；条目不丢，语义段补宿主 id 后可重放。
+      if (e.kind === 'event' && e.fields?.owner_aggregate
+          && !out.aggregates.some(a => a.id === e.fields.owner_aggregate)) {
+        record(`event ${e.key}: owner_aggregate「${e.fields.owner_aggregate}」不存在 → 跳过（幻影宿主防线；请语义段核对聚合 id 后重放）`);
+        continue;
+      }
+      if (e.kind === 'context_map' && e.fields?.source_bc
+          && !out.bounded_contexts.some(b => b.id === e.fields.source_bc)) {
+        record(`context_map ${e.key}: source_bc「${e.fields.source_bc}」不存在 → 跳过（幻影宿主防线；请语义段核对 BC id 后重放）`);
+        continue;
+      }
+      insertEntry(out, e.kind, e.key, e.fields, src);
+      applied.push(`new:${e.kind}:${e.key}`);
+      continue;
+    }
+
+    if (e.op === 'extend') {
+      if (!found) {
+        record(`extend 落空：${e.kind} ${e.key} 不存在 → 视作 new（软着陆）`);
+        insertEntry(out, e.kind, e.key, e.fields, src);
+        applied.push(`new(by-extend-miss):${e.kind}:${e.key}`);
+        continue;
+      }
+      if (found.entry.source?.startsWith('change:') && found.entry.source !== src) {
+        // 跨 change 改动既有条目：不覆盖 source 归属（本次合并是权威仅限同 change；
+        // 跨 change 修改既有所有权条目属结构性变更，须人审——WARN 不阻断）
+        warnings.push(`extend 跨 change：${e.kind} ${e.key} 属 ${found.entry.source}，本次 ${src} 的字段合并不改归属`);
+      }
+      mergeFields(found.entry, e.fields);
+      applied.push(`extend:${e.kind}:${e.key}`);
+      continue;
+    }
+
+    if (e.op === 'refactor') {
+      const from = findEntry(out, e.kind, e.prev_key);
+      if (!from) {
+        violations.push(`refactor 前置缺失：${e.kind} ${e.prev_key} 不存在（无软着陆豁免）`);
+        continue;
+      }
+      if (findEntry(out, e.kind, e.key)) {
+        violations.push(`refactor 目标已存在：${e.kind} ${e.key}`);
+        continue;
+      }
+      // 改键 + 保留 source 历史 + 合并本次字段
+      if (e.kind === 'table') from.entry.name = e.key;
+      else if (e.kind === 'endpoint') { const [m, ...rest] = e.key.split(':'); from.entry.method = m; from.entry.path = rest.join(':'); }
+      else if (e.kind === 'event') from.entry.name = e.key;
+      else if (e.kind === 'context_map') from.entry.key = e.key;
+      else from.entry.id = e.key;
+      mergeFields(from.entry, e.fields);
+      from.entry.reason = e.reason; // 结构变更可审计（§5.7）
+      applied.push(`refactor:${e.kind}:${e.prev_key}->${e.key}`);
+      continue;
+    }
+
+    if (e.op === 'retire') {
+      if (!found) {
+        warnings.push(`retire 幂等：${e.kind} ${e.key} 不存在（重放或先行清理）`);
+        continue;
+      }
+      // 不删行（红牌 6）：置标记
+      found.entry.status = 'retired';
+      found.entry.reason = e.reason;
+      found.entry.retired_in_change = changeName ?? delta.change;
+      applied.push(`retire:${e.kind}:${e.key}`);
+      continue;
+    }
+  }
+
+  sortRegistry(out);
+  return { registry: out, applied, warnings, violations };
+}
+
+function mergeFields(entry, fields) {
+  if (!fields) return;
+  for (const [k, v] of Object.entries(fields)) {
+    if (k === 'source' || k === 'status') continue; // 生命周期/归属不由字段合入（retire/refactor 走专属 op）
+    entry[k] = v;
+  }
+}
+
+function insertEntry(reg, kind, key, fields, source) {
+  // fields 不得携带 source/status（生命周期/归属只经 retire/refactor/专属 op 变更）
+  const clean = {};
+  for (const [k, v] of Object.entries(fields || {})) {
+    if (k === 'source' || k === 'status') continue;
+    clean[k] = v;
+  }
+  const base = { status: 'active', source };
+  const ownerName = source.startsWith('change:') ? source.slice('change:'.length) : null;
+
+  if (kind === 'event') {
+    // schema 冻结决策：事件经 fields.owner_aggregate 挂宿主聚合（O4 事件表「源聚合」列）；
+    // 缺宿主时创建最小聚合壳（不静默丢事件），壳 id 带 event-sink 前缀可辨识、待人审归位。
+    const ownerId = clean.owner_aggregate;
+    if (!ownerId) {
+      reg.aggregates.push({
+        id: `event-sink:${key}`, name: key, bc: null, owner_change: ownerName,
+        status: 'active', source, events: [{ name: key, ...base, ...clean }],
+      });
+      return;
+    }
+    let host = reg.aggregates.find(a => a.id === ownerId);
+    if (!host) {
+      host = { id: ownerId, name: ownerId, bc: null, owner_change: ownerName, status: 'active', source, events: [] };
+      reg.aggregates.push(host);
+    }
+    if (!Array.isArray(host.events)) host.events = [];
+    host.events.push({ name: key, ...base, ...clean });
+    return;
+  }
+  if (kind === 'context_map') {
+    const srcBc = clean.source_bc;
+    if (!srcBc) throw new Error(`context_map ${key} 缺 fields.source_bc`);
+    let host = reg.bounded_contexts.find(b => b.id === srcBc);
+    if (!host) {
+      host = { id: srcBc, name: srcBc, responsibility: null, aggregates: [], context_map: [], status: 'active', source };
+      reg.bounded_contexts.push(host);
+    }
+    if (!Array.isArray(host.context_map)) host.context_map = [];
+    host.context_map.push({ key, ...base, ...clean });
+    return;
+  }
+  if (kind === 'aggregate') {
+    reg.aggregates.push({
+      ...base, id: key, name: clean.name ?? key, bc: clean.bc ?? null,
+      owner_change: ownerName, events: [], ...clean,
+    });
+    return;
+  }
+  if (kind === 'bounded_context') {
+    reg.bounded_contexts.push({
+      ...base, id: key, name: clean.name ?? key, responsibility: clean.responsibility ?? null,
+      aggregates: [], context_map: [], ...clean,
+    });
+    return;
+  }
+  if (kind === 'subdomain') {
+    reg.subdomains.push({
+      ...base, id: key, name: clean.name ?? key,
+      classification: clean.classification, business_problem: clean.business_problem, ...clean,
+    });
+    return;
+  }
+  if (kind === 'table') {
+    reg.tables.push({ ...base, name: key, change: ownerName, ddl_ref: clean.ddl_ref ?? null, ...clean });
+    return;
+  }
+  if (kind === 'endpoint') {
+    const [method, ...rest] = key.split(':');
+    reg.endpoints.push({ ...base, method, path: rest.join(':'), kind: clean.kind ?? 'server', change: ownerName, ...clean });
+    return;
+  }
+  throw new Error(`未知 kind: ${kind}`);
+}
+
+/* ============ seed（红牌 12 首次 merge 自动 seed 的承载层） ============ */
+
+/**
+ * 把一组 seed 条目按 source=seedSource 并入 registry（只补缺，不覆盖已有行——
+ * 与 P0-B' seedFromSnapshots 的"最低优先级"语义一致）。
+ * @param {object} reg
+ * @param {{ aggregates?: [], tables?: [], endpoints?: [], bounded_contexts?: [], subdomains?: [] }} seed
+ * @param {string} seedSource 如 `base@snapshot-backfill` / `base@schema-baseline`
+ * @returns {{ registry, seeded: number }}
+ */
+export function seedRegistry(reg, seed, seedSource = 'base') {
+  let seeded = 0;
+  const add = (list, keyFn) => {
+    for (const item of seed[list] || []) {
+      const existing = findEntry(reg, { aggregates: 'aggregate', tables: 'table', endpoints: 'endpoint', bounded_contexts: 'bounded_context', subdomains: 'subdomain' }[list], keyFn(item));
+      if (existing) continue;
+      const withSource = { ...item, source: item.source ?? seedSource, status: item.status ?? 'active' };
+      reg[list].push(withSource);
+      seeded++;
+    }
+  };
+  add('aggregates', x => x.id);
+  add('tables', x => x.name);
+  add('endpoints', x => `${x.method}:${x.path}`);
+  add('bounded_contexts', x => x.id);
+  add('subdomains', x => x.id);
+  sortRegistry(reg);
+  return { registry: reg, seeded };
+}