真源语言 · 从一条规则到状态

说清规则,追溯变化

从 Counter 开始:守卫决定命令能否继续,绑定提供事件载荷,状态折叠把事件变成新状态。业务声明只有一棵作者树;技术绑定与手写实现各负其责。图谱与绿灯都不能代替人对业务规则达成共识。

最小 Counter · 折叠如何工作 · 真实银行切片 · 表达式参考 · 关系注册表

01

Counter:一条因果链,三种视角

1 · 业务解释

从 count = 0 开始,请求 SetCount(id="counter-1", count=2)。id 非空、count 非负,两条守卫都通过。绑定将参数放入 CountSet;应用这个事件后,id 为 counter-1,count 为 2。负数请求被拒绝,不产生事件。这是赋值,不是累加。

2 · 当前作者输入

下列 JSON 数组片段来自 cb860b5c 随包提供的 Counter 切片,仅重排了格式,不是完整 YAML 文件或项目。放回原位置并保留周围类型声明;指南中的公共 init 会创建完整项目。

payload.guards——按顺序读取命令参数与当前状态。

[
  {"kind":"invariantRef","ref":"nonempty-id","errCode":"EMPTY_ID","cond":"param.id.nonEmpty","onFail":"reject"},
  {"kind":"invariantRef","ref":"nonnegative-count","errCode":"NEGATIVE_COUNT","cond":"param.count >= 0","onFail":"reject"}
]

events.CountSet.bindings——填充事件,而不是修改状态。

[
  {"slot":"id","expr":"param.id"},
  {"slot":"count","expr":"param.count"}
]

events.CountSet.foldAssignments——重放读已记录的事件,不读原命令。

[
  {"slot":"id","expr":"event.id"},
  {"slot":"count","expr":"event.count"}
]

3 · 展开语义——IR,不是作者输入

下方是已接纳 domain-folds@6 中 count 赋值的 update 子树。完整产品还含目标、类型、来源与依赖。不要把这段 IR 粘进 expr。

{
  "op": "set",
  "value": {
    "op": "ref",
    "ref": {"context":"example","kind":"event-slot","owner":["Counter","CountSet"],"id":"count"}
  }
}
02

守卫、绑定、状态折叠:各负其责

守卫

命令可以继续吗?

条件为真,继续下一条守卫。条件为假时,onFail: reject 携错误码终止;succeed-empty 成功终止且不产生事件。两者都不再执行后续守卫。失败策略不是条件本身的返回值。

绑定

记录什么事实?

发射绑定从已声明的命令/状态值,或显式接纳且固定版本的宿主输出,填充事件槽位。事件字段与状态字段不能混为一谈。

状态折叠

事实如何改变状态?

聚合状态只在事件应用中演进。重放只消费state + event;不能调用宿主、读取时钟/网络,或依赖原命令参数。

同时计算,不是按行执行的脚本

所有右值与更新基值都读取同一份不可变的事件前快照。先算出全部结果,再构成新状态。一条赋值删除 map 项,不会遮住另一条赋值读取的旧值。一个事件对每个目标只能赋值一次:不能靠书写顺序、最后写入获胜或中间状态读取表达逻辑。

例如 state.pending[event.key] 在类型化产品中得到的是可选值,接收类型必须容纳 optional;它不是无检查的取值。即便旧树预检接纳某个拼写,严格类型接纳仍可能拒绝。

精确数值

Long/Int/Integer 在产品与 oracle 边界使用规范的有符号 64 位十进制字符串,不用 JS Number。精确金额需要声明名义类型、精度、小数位和单位;没有隐式币种、舍入或换算。单位、精度不符或溢出都失败;money-apply 是操作名,不是内建银行政策。宿主时钟与任意 Scala 不是重放表达式;严格产品中的 literal:SYSTEM_NOW 不是读时钟。

03

一个真实切片,原样未剪

来自 truth/bank-wealth/…/credit-balance/slices/initialize-account.slice.yaml:一条命令、五个守卫、一个事件、折叠与溯源。此原文不是独立项目,也不是一次新的银行验收。

业务视角:身份、冲突,再到幂等

  1. ACCOUNT_ID:请求资源必须等于本聚合 id。
  2. ACCOUNT_CURRENCY:币种必须为 CNY,金额也必须携带同一币种。
  3. ACCOUNT_INIT_CONFLICT:尚未初始化则继续;初始化后,金额须与已记录值相同。不同金额在幂等守卫之前拒绝。
  4. ACCOUNT_INIT_ONCE:!state.initialized 为假表示 succeed-empty。匹配的重试不发第二个事件,后续守卫也不执行。
  5. ACCOUNT_SEED_NONNEGATIVE:首次种子金额须 >= 0.00,允许零;不是更严格的 money-positive 谓词。

当前作者视角:原文件字节

# ═══ truthsrc atom — hand-editable; contract: SCHEMA.md ═══

kind: slice
aggregate: CreditBalance
command: InitializeAccount
payload:
  {
    "name": "InitializeAccount",
    "parameters": [
      "resource: AccountId @BUSINESS_INPUT",
      "currency: String @BUSINESS_INPUT",
      "amount: Money @BUSINESS_INPUT"
    ],
    "guards": [
      "@guard[invariantRef](reject ACCOUNT_ID/ACCOUNT_ID: \"param.resource == state.id\")",
      "@guard[invariantRef](reject ACCOUNT_CURRENCY/ACCOUNT_CURRENCY: \"param.currency == \\\"CNY\\\" && param.amount.currency == param.currency\")",
      "@guard[invariantRef](reject ACCOUNT_INIT_CONFLICT/ACCOUNT_INIT_CONFLICT: \"!state.initialized || state.accountBalance.get(param.currency).contains(param.amount)\")",
      "@guard[invariantRef](succeed-empty ACCOUNT_INIT_ONCE/ACCOUNT_INIT_ONCE: \"!state.initialized\")",
      "@guard[invariantRef](reject ACCOUNT_SEED_NONNEGATIVE/ACCOUNT_SEED_NONNEGATIVE: \"param.amount.amount >= 0.00\")"
    ],
    "produces": [
      "AccountInitialized"
    ],
    "provenance": {
      "author": "agent-assisted-bank-v1",
      "workshopHeld": false,
      "approvedBy": "user-approved-p24-p25-bank-joint",
      "sourceVersion": "bank-v1-p23-design-2"
    }
  }
events:
  {
    "AccountInitialized": {
      "name": "AccountInitialized",
      "payloads": [
        "resource: AccountId @PROPAGATED",
        "currency: String @PROPAGATED",
        "amount: Money @PROPAGATED"
      ],
      "bindings": [
        "resource <- param.resource",
        "currency <- param.currency",
        "amount <- param.amount"
      ],
      "foldAssignments": [
        "initialized := \"literal:true\"",
        "accountBalance := @fold[put](key=event.currency, value=event.amount)"
      ]
    }
  }

展开语义视角——解释,不是作者输入

五条守卫全通过后,三个绑定把 resource、currency、amount 记入 AccountInitialized。折叠设置 initialized=true,并以事件 currency 为键将事件 amount 放入 accountBalance;两者均读取同一事件前快照。对身份匹配的新账户,0.00 CNY 有效;已初始化且匹配的重试不产生事件/折叠;不同金额则拒绝。这是对声明的解释,不是独立执行银行行为。

守卫

有牙齿的规则

守卫保留声明顺序与条件为假时的结果:reject 表示拒绝,succeed-empty 表示幂等重试成功且不再发出事件。「余额非负」不再是一条注释——它编译进生成的命令处理器。

绑定

载荷从哪里来

每个事件字段要么从参数传播而来,要么是计算出来的——字段级的溯源,这正是读模型血缘(R10/R11)建立其上的东西。

折叠

历史变成状态

foldAssignments 定义事件如何更新聚合状态——生成的 event applier 实现的就是这套代数。

04

当前表达式参考

核对版本为工具链 cb860b5c、工具包 0.5.0。作者格式、微语法与产品 profile 各有版本。Counter 选择 decision @4、dependencies/folds @6;不能用旧例子悄悄替换这些 profile。

当前有限 fold 操作仍受支持;可复用纯函数定义/引用及函数级 BDD 挂帐于 DEF-21,语法与定义位置未定,不能放宽回放、类型或版本准入。

七种折叠操作

每行都是事件 foldAssignments 中的作者对象片段,不是独立 YAML。示意字段名必须有匹配声明。外层对象配字符串操作数是当前可用的过渡形态,不是未来语言设计的终点。

操作 / 作者形态参数与含义类型、profile 与限制
set
{"slot":"count","expr":"event.count"}
slot, expr;可加 op:"set"。替换一个值。必须与目标类型完全相同。fold 产品 @1 起支持。用直接赋值,不用有缺陷的 micro set 形态。
put
{"slot":"items","op":"put","key":"event.key","value":"event.value"}
slot, op, key, value。插入或替换一个键。目标为 Map,键和值类型匹配;不是列表追加。fold 产品 @1 起支持。
remove
{"slot":"items","op":"remove","key":"event.key"}
slot, op, key。删除一个键;不存在则 map 不变。目标为 Map,键类型匹配;没有 value 参数。fold 产品 @1 起支持。
put-all
{"slot":"items","op":"put-all","key":"event.keys","value":"event.value"}
key 是序列,在每个键上写入同一个标量值。目标为 Map,序列元素与键类型匹配;不是 map 合并或键值 zip。fold 产品 @1 起支持。
remove-all
{"slot":"items","op":"remove-all","key":"event.keys"}
删除序列中的各个键。目标为 Map,此处不能给标量键;没有 value 或回调。fold 产品 @1 起支持。
money-apply
{"slot":"balance","op":"money-apply","delta":"event.amount","sign":-1}
slot, op, delta, sign。事件前余额加上带符号的 delta。目标与 delta 为已接纳的同一精确名义类型、同单位;sign 只能是 1 或 -1,不用浮点。fold 产品 @1 起配合 exact types 支持。
integer-apply
{"slot":"count","op":"integer-apply","delta":"event.count","sign":1}
事件前 signed-64 count 加上带符号的 delta,溢出拒绝。目标与 delta 为整数。作者聚合须显式选 valueExpressionProfile:"truthsrc.domain-values/v2";该标记本身不选择产品或生成器。类型化 fold 产品 @1 起支持。

不要混用四层语法

固定版本参考:AUTHORING · 微语法 · SCHEMA · 作者值表达式 · PRODUCTS · 类型化折叠/oracle。历史章节描述更宽的兼容载体,不代表这些严格 profile 允许任意执行。

下一步:批准并检查一次 Counter 规则变更。

05

一棵树的形状

来自银行示例——统计物理作者文件 已验证。59 个独立 VO 原子文件(F-10),加上 structure 展开的 59 项,构成 canonical graphstore 中的 118 个 VO 节点(F-03);文件与展开节点是不同计数单位。

truth/bank-wealth/
├── system.yaml                    # 系统根:id、名称、职责
├── inbox/                         # 工作坊入口——笔记是草稿,不是法律
│   ├── 02-commands/  05-context-map/  06-aggregate-detail/ …   # 13 个产品槽位
└── contexts/bankwealth/
    ├── context.yaml               # 限界上下文 + 它的依赖(R21)
    ├── aggregates/
    │   ├── credit-balance/
    │   │   ├── aggregate.yaml     # 状态字段 + 具名的 @rule 不变量
    │   │   └── slices/initialize-account.slice.yaml
    │   ├── fund-order/  …         # 3 个聚合共 27 个切片
    │   └── sip-plan/
    ├── value-objects/             # 59 个独立 VO 原子文件:Money、AccountId、AmountDecimal…
    ├── read-models/               # 6 个读模型,带字段血缘(R10/R11)
    ├── policies/                  # 事件 → 命令的反应规则(R7/R9)
    ├── stories/                   # 4 个用户故事
    ├── use-cases.yaml             # 由切片实现的流程(R18)
    ├── pipelines/                 # 4 条 Monarch 风格的有序步骤队列(R14–R16)
    ├── sagas/                     # 2 个 TCC 跨聚合事务
    └── formal-products/           # 36 份契约:端口、宿主、制品契约…
第零规则

业务声明只在作者树中编辑。编译 canonical、语义产品、图谱和代码锚点是派生物,不是竞争的业务模型。技术绑定与受支持的手写实现区各有明确契约;不要通过修改生成产物来改变业务规则。

06

范围层:你能说什么

两套词汇表,一张注册表。工作坊笔记类型是发现面(一墙便签的去处);原子种类是编译后的契约。已对照 lib/shared.mjs 验证

15 种笔记类型——工作坊入口

分组类型承载什么
行为event · command · policy · timer领域事件、请求变更的命令、反应策略、时间触发器——EventStorming 的词汇。
结构aggregate · entity · field · readModel一致性边界、实体、带血缘的字段、读侧投影。
战略context · subdomain · relation限界上下文、核心/支撑/通用分类、上下文间关系——DDD 的战略层。
人与系统role · externalSystem角色(及其可发出的命令,R12)和边界上的外部系统。
知识question · story不许悄悄消失的开放问题 / 热点,以及等待安放的用户故事。

12 种原子——编译后的契约

种类文件持有
noteinbox/**任意笔记类型的草稿工作坊笔记——等待人工晋升。
aggregateaggregates/<slug>/aggregate.yaml身份、状态字段、有序的命令/事件池、具名的 @rule 不变量。
sliceslices/<slug>.slice.yaml因果单元:一条命令、它的守卫、它产生的事件、折叠赋值、溯源。
value-objectvalue-objects/<slug>.vo.yaml带类型的值——Money、AccountId 这类名义包装。
read-modelread-models/…读侧形状,每个字段带来源(血缘)。
policypolicies/…「当事件 X 则命令 Y」的反应规则。
story / use-casesstories/… · use-cases.yaml用户故事,以及实现它们的流程。
pipelinepipelines/<slug>.pipeline.yaml有序的业务步骤队列(只有步骤 steps,绝不叫「阶段 stages」)——编译为 Monarch 计划。
sagasagas/<slug>.saga.yaml跨聚合 TCC 事务:参与者、阶段、补偿——编译为 saga-core IR。
scenarioscenarios/<slug>.scenario.yaml叙事式 runbook / 演示脚本。
formal-productformal-products/…工程契约:技术端口、效果宿主、制品契约、宿主计算——生成代码必须满足的东西。
07

关系注册表——元模型的脊柱

22 种带类型的关系。propagates 标记是每条关系一次的人工裁定:这条边是否传导影响?blast_radius 恰好沿 propagates 边行走——宁可多报,不可漏报。已验证

ID从关系到传导含义
R1aggregateownsslice✓结构上的拥有
R2aggregatereferencesaggregate✓跨聚合引用
R3aggregateemitsevent✓事件池成员
R4sliceissuescommand✓每切片一条命令(1:1)
R5sliceemitsevent✓切片产生的事件
R6commandproducesevent✓因果性;条件在守卫里
R7eventtriggerspolicy✓反应规则
R8policyconstrainsslice✓策略约束切片
R9policyinvokescommand✓策略发出命令
R10read-modelderives-fromfield✓读侧血缘
R11fieldlineagefield✓字段到字段的链条
R12rolecan-issuecommand—是权限,不是影响
R13read-modelvisible-torole—可见性
R14pipelinehas-stepstep✓有序步骤
R15stepperformed-byrole—参与关系
R16stepexecutesslice✓步骤执行切片
R17storycoversuse-case—可追溯性
R18use-caserealized-byslice✓流程 → 切片
R19scenarioexercisespipeline—runbook 路径
R20value-objectused-byaggregate✓类型使用
R21contextdepends-oncontext✓上下文映射
R22aggregatebelongs-tosubdomain—战略分类

战略层一眼看尽:R21 是上下文映射;R22 把聚合安放进核心/支撑/通用子域;R12/R13 承载谁能做什么、谁能看见什么。其余全是行为——而行为边传导影响。

08

治理:三道闸门,不是风格指南

validate——0 个硬发现

作者结构与已声明引用检查,不等于完整类型接纳

未知种类、悬空引用、事件在两处定义、切片没有所属聚合——全是硬发现。零是唯一可接受的计数。银行树截至 2026-11-11:0 硬发现 已验证。

roundtrip——逐字节一致

树 → canonical → 树,必须精确复现作者文件

这是反格式漂移闸门。如果编译「顺手规范化」了任何东西,往返就会发散、闸门就会失败。银行树:157 个原子,逐字节一致 已验证。

compile-products——严格契约

形式产物必须先满足自己的 schema 才能被使用

端口、saga IR、执行 IR:从树编译而来的带类型、带版本的产物,各有各的验证。生成代码只消费冻结后的产物。

智能体

给 AI 智能体的编辑契约就是这三道闸门再加守护规则:每一批编辑以 validate 与 roundtrip 全绿收尾;payload 文本逐字保留;树内不许出现工具痕迹;一个事件只在一个切片中定义。它随工具链发布为 AGENTS.md 和一个查询技能包。

09

今天与明天的编辑体验

今天的编辑界面是 YAML 文件加三个抽取技能(从代码库、从可达数据、从一句话描述)。可视化编辑——从 Qlerify 或 Miro 导入工作坊画板、从既有仓库逆向抽取一棵树——已为它留好设计但尚未构建:DEF-02。

Schema 参考:SCHEMA.md · 编写指南:AUTHORING.md · 完整教程:TUTORIAL.md