宜博 / lemonboss

28-followups §3.1。**审计结论与那条待办原来的写法不一样，两列要分开处理。**

## source_kind：删

与 origin 一一映射（global_agent↔builtin / company_hired↔created），
实查生产库 76 行零例外。全仓唯一读侧是 migrate() 里那条 origin 回填，
而那是给「origin 列出现之前写下的行」用的一次性迁移。

顺序：**先回填、再删列**，两步都用 hasColumn 守着（幂等）。反过来做不报错 ——
库能开、测试能过，只是那几行 origin 悄悄是错的。守卫
source-kind-drop-migration.test.js 走存量库重启那条路，专门钉这个顺序，
反向验过：弄反立刻红。

写侧散在 3 处生产 INSERT + 35 个测试文件。批量改的时候正则误伤了 4 处
（吃掉了 JS 默认参数、位置占位符、ON CONFLICT 的赋值行），逐个修回并复查了 diff ——
**这种跨几十个文件的机械改动，靠「全量跑一遍」兜底比靠正则写得对更可靠**。

## legacy_path：不能删，它还没死

原待办说「所有读取点都已改成从 id 推导」——那半句对新行成立，对存量行不成立：
· 新行 legacy_path 恒等于 system/agents/{id}（确实冗余）；
· **存量行里存着批次 4 之前的公司侧路径**，而 graph-seed-service 判「悬空行 / 孤儿行」
  靠的正是这个路径指向的目录还在不在。从 id 推导出来的路径永远指向 system/agents/，
  那条判据会整个失效。

实查生产库：76 行里还有 2 行是老路径（org-planner / org-coder 指着已不存在的
data/companies/mycompany/agents/）—— 正是这条判据要认出来的那种行。

退出条件写进了 graph-db.js 的建表注释（不只留在文档里）：
库里不再有 legacy_path <> 'system/agents/' || id 的行。

## 顺带记一条：getDb() 会就地迁移生产库

删列那次，生产库的列是被一条**查状态用的**一行 node -e 删掉的 ——
服务当时没重启，人也没打算迁移。结果是对的（幂等；与备份逐行核对 76 行一致、
origin 全部按映射回填正确），但「读一下状态」不该顺手改 schema 这件事值得知道。
闸门只挡测试进程，故意不挡普通脚本（挡了服务自己也起不来）。
注释里给了只读的正确姿势。

全量：140 文件 / 1299 测试全绿。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

R-19.A 把 declareEdgeContract 的调用方补上之后，inboundContracts 终于非空，
「沿边传递」这类数据流在真跑里生效了（真实规划 agent 自己在边上写出了
produces/needs 声明）。本次收掉它留下的三个缺口。

1) role 落库（第 14 次「四环漏一环」）
   normalizeContracts 产出 role，declareEdgeContract 入参没有它、表也没这列 ——
   产生 → 传递(丢) → 落库 → 读回。后果不止是控制台不精确：规则 6（data-contract）
   靠「有人 needs 但没人 produces」判错，只存 kind 就没法从库里重算，而
   patchGraph 第 5 步的重新校验读的正是库 —— 增量 PATCH 又恰恰是
   「此前满足的 needs 失去产出方」的唯一发生地，校验偏偏在最该生效的通道上失效。
   - graph_edge_contracts 加 role 列（CHECK + 老库 ALTER 后回填 produces：
     NULL 在规则 6 里既不算产出也不算需求，会误拒一张合法的图；闸门宁可漏判不可错拦）
   - 两层调用点透传 role；readGraph 把 contracts 读回来并递进 validateGraph

2) 控制台三字段（前端在、后端没喂）
   GET /api/graph-runs/:id 补 edges[].contracts / companyRoot / taskFiles，
   否则 R19-C 那三块界面整块降级：声明和索引都在库里，界面上看不见。
   contracts 只在非空时出现，与 failReason 同一个约定。

3) 收拢 companyRootDir/taskDirRel 镜像
   goal-contract.js 里那份镜像靠注释约定「与 graph-engine 逐字同构」维持，
   控制台路由成为第三个调用方时这个约定就不成立了。抽到 company-paths.js，
   GRAPH_RUNS_DIR 改为调用时读（原先两个模块各自在加载时快照，
   加载顺序不同会算出不同的根）。goal-contract 那条「镜像漂了就报警」的用例
   按其自身预告改成比函数返回值。

测试 826 全绿（+11：role 8 / 路由 3），既有断言未改。
11 处变异逐一验证精确变红后逐字还原；其中一条断言初版在 fixture 上永远自洽
（图里没有无声明的边），补了一条无声明的边才真正有判别力。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>