Archived

This repository has been archived on 2026-09-13. You can view files and clone it. You cannot open issues or pull requests or push a commit.

Files

T

xcsandClaude Fable 5 7b85a79323 harness 与工作台同日修:数据工单确认即入库 · 叫了人不再自动推进(两道结构闸)· 审核卡 = 终局验收卡结构 · 验收清单人点达标 · 迟到守卫不丢放行裁决 · 画面跟着这一拍发出去的卡走 · 成果详情只翻页 · 占位居中 · 进度条

human-tool / ledger / loop-engine / release / task / interaction 六模块与 app 层(desk 路由、engines、consumers、
data-order-landing、case-stamp、reset-runs、seed-activities、容器与 server 装配),web 的 desk-task
(ViewRegion / chat-bubbles / review-face)与 app.css、ui-kit 图标;契约 card / manifest;
迁移 0034_task_seq 与迁移日志;api-report 快照;CLAUDE.md 快照、debt、活动开发规范、HTML 报告规范同步。
逐条口径见 CLAUDE.md 快照(2026-08-27 下午至晚)。另一会话做的,一直留在工作树没入库;与同批另两条提交互相依赖。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0167qWjeyBwvfdGovd7FWbCu

2026-08-27 23:20:16 +08:00

5.9 KiB

Raw Blame History

module: ledger

职责: 台账:三级寻址、通用事务接口、schema 自生长(最大化合并 / 最宽类型 / 只增不破坏)、任务级草稿层与任务视图、写三分、数据冲突检查不负责: 放行时机与落地预检的编排(见 release)、数据事件的投递与三级消费(见 event)、动作意向的执行(见 toolbox / release)

公开出口: index.ts

类型:LedgerService SystemWrite DraftWrite ReleaseWriteResult SchemaApplyResult ObjectAddress MergedObject MergeNotice MergeConflict ConflictFinding
错误:DraftConflictError SchemaConflictError ObjectNotMaterializedError
端口类型:LedgerStore DraftStore EventPublisher Clock IdGenerator ObjectRef
用例工厂:createLedgerService(deps: LedgerServiceDeps): LedgerService
纯函数(供 activity-registry 静态审复用):mergeDeclarations planSchemaChanges planIsNonDestructive widen overlay detectConflicts keyOf pickKey
adapter 工厂:createLedgerStore(pool) createDraftStore(runner) tableNameOf DRAFT_DDL DRAFT_TABLE

层级: L1(编码规范 §4) 依赖: @contracts;@shared/db(LEDGER_SCHEMA) port:EventPublisher(app 注入 event)、Clock、IdGenerator、LedgerStore、DraftStore 被依赖: channel, release, activity-registry, loop-engine, flow-engine, task, trigger, app(治理台 · 数据管理路由)

不变量:

写三分是三个方法:systemWrite / draftWrite / releaseWrite —— 无第四条写入路径, 调用方拿不到带 flag 的「绕门」形态(§12.5#9)
draftDrop 不是第四种写:它只撤本单草稿层那一笔 —— 正式版一个字都动不了, 也不抛事件,放行门的位置没变。写错了得有退路:实测过一次死胡同 —— 客户说本轮跳过的那颗料被写进有效清单,判据正确地拦住而模型改不动 (唯一能改的是那个数,改了别的数又不对),13 次拒回、23 拍、234k token 才熔断。 门拦住一件办错的事却不给改正的手段,那扇门就只是个死胡同。 撤不到如实回 false(主键写法对不上是常见原因)—— 静默成功会让调用方以为撤掉了
正式版写入(system / release)必产生数据事件;草稿写必不产生
releaseWrite 先过数据冲突检查:任一冲突即抛 DraftConflictError,不做部分合并
releaseWrite(taskId, scope) 是同一道放行写,门换成了数据工单的确认(2026-08-27): scope.only 只并那几张表(这张卡的提交闸盯的那几张,gateLedgers / 绑的 blocks); 并过的行留在草稿层打 landed 记号(ledger.__draft.landed_at)—— 它仍是本单写下的行 (taskDrafts / 任务视图照旧认它,引擎的 mine: / _rows 全靠这份),整单放行时不再写它、不抛事件、不做冲突检查(landedEarlierRows 单独计数),只把表里那一份读回来当事实(出口载荷要它)。再往已落地的行写一笔(人在件上改 / 模型 write),记号擦掉、基线换成落地后表里的值 —— 那一笔照旧等放行。范围放行抛的数据事件不指回本单(它正等着自己的人事件;别单的监听照旧认正式版事件), 归因 ledger-write:<scope.cause>。试跑单(不落主数据)在这一道门上同样挡住:行留着、不打记号。 不是第四种写,也不是绕门:同一条冲突检查 → 原子合并 → 抛事件的路,调用方指不了清单没声明的表。
试跑单的主数据不进正式表:SimulationProbe 说这一单是试跑时, kind = 'master' 的草稿行不 upsert、不删、不抛数据事件,但仍进 merged(出口载荷取它); simulatedRows 单独计数,不混进 mergedRows。单据(record)不受影响 —— 试跑仍是真跑
合并只增不破坏:planSchemaChanges 永不产出删列 / 缩窄;主键一经建立不得由声明变更
同名异型取能兼容双方的最宽类型(integer→number→text;date→timestamp→text); json 与标量语义互斥 —— 拦下,交数据管理裁决
脱敏取或:任一声明要求脱敏即脱敏(安全方向单调)
ledger schema 的唯一写者是本模块 adapter;SQL 拼接只在 ledger-store.ts, 标识符过 IDENT 正则 + quoteIdent

影响半径: contract 加 ReleaseWriteResult.simulatedRows(加性)· port 加 LedgerStore.masterRefs 与 SimulationProbe(app 注入)→ 下游只有 release 需同步读新字段

近变(2026-07-28):人读名落库 —— 物化时把声明里的 label 写成 PG 的表/列注释, describe 与 listObjects 一并读回(MaterializedObject.label / MaterializedColumn.label / listObjects() 出参加 label?)。此前 label 在建表那一步就丢了,治理台只剩 project__intake_record 这种键给人看。用注释而非另建元数据表:名字与表同生共死,不会对不上。 comment on 是工具语句不吃占位符,字面量在 adapter 内转义单引号。

近变(2026-08-27 下午):数据工单确认即入库 —— releaseWrite 加可选 scope(ReleaseScope), DraftEntry / taskDrafts 出参加 landed,DraftStore 加 markLanded,ReleaseWriteResult 加 landedEarlierRows(release 的放行痕据此分开说)。起因:W05 的数据工单卡上写着「确认后即入库」, 而草稿层通往正式表只有整单放行一道口子 —— 人建好的主数据要等整条评估放行才进库,试跑单永远不进。

近变(2026-08-27):对象声明加 createOnly —— 标了的表在本单只建不改:Agent 写入那一刻查正式表, 键已在库当场拒并指路(撤掉草稿里那一行)。数据工单「从零建主数据」的三张表用它。只管 Agent 的写路径 (engines.draftWrite 那道门),人在件上的保存不受此限。

5.9 KiB Raw Blame History

module: ledger

5.9 KiB

Raw Blame History