真源语言 · 从一条规则到状态
说清规则,追溯变化
从 Counter 开始:守卫决定命令能否继续,绑定提供事件载荷,状态折叠把事件变成新状态。业务声明只有一棵作者树;技术绑定与手写实现各负其责。图谱与绿灯都不能代替人对业务规则达成共识。
最小 Counter · 折叠如何工作 · 真实银行切片 · 表达式参考 · 关系注册表
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"}
}
}
守卫、绑定、状态折叠:各负其责
命令可以继续吗?
条件为真,继续下一条守卫。条件为假时,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 不是读时钟。
一个真实切片,原样未剪
来自 truth/bank-wealth/…/credit-balance/slices/initialize-account.slice.yaml:一条命令、五个守卫、一个事件、折叠与溯源。此原文不是独立项目,也不是一次新的银行验收。
业务视角:身份、冲突,再到幂等
ACCOUNT_ID:请求资源必须等于本聚合 id。ACCOUNT_CURRENCY:币种必须为 CNY,金额也必须携带同一币种。ACCOUNT_INIT_CONFLICT:尚未初始化则继续;初始化后,金额须与已记录值相同。不同金额在幂等守卫之前拒绝。ACCOUNT_INIT_ONCE:!state.initialized为假表示 succeed-empty。匹配的重试不发第二个事件,后续守卫也不执行。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 实现的就是这套代数。
当前表达式参考
核对版本为工具链 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 起支持。 |
不要混用四层语法
- 守卫条件:有限的
param/state谓词、布尔运算、比较,以及接纳的集合/成员操作。signed-64 字面量与有限+/-需要 decision @3/@4;旧 profile 不同。不接受任意调用或 Scala 闭包。 - 作者值表达式:例如
event.count、literal:true、literal:1字符串。成员路径需要作者 v2 显式选择;普通中缀算术不是 fold 值字符串。value-product v2 识别的嵌套 literal/add/subtract 对象,当前作者预检仍拒绝。 - 微语法载体:系统显式选择
authoring.micro:"truthsrc.micro/v1"后,"count := event.count"或"items := @fold[put](key=event.key, value=event.value)"这类 JSON 字符串降低到上述外层对象。参数以逗号加空格分隔;带标点/空白的文本要用内层 JSON 字符串,并在外层 JSON 转义。微语法不扩大语义接纳范围。 - 类型化产品 IR:封闭的
op/ref/valueType对象、限定身份与来源。这是编译输出,不是绕过作者验证的捷径。参见尚未实现的精炼 RFC 与三项当前缺陷;不推荐@fold[set](value=...)。
固定版本参考:AUTHORING · 微语法 · SCHEMA · 作者值表达式 · PRODUCTS · 类型化折叠/oracle。历史章节描述更宽的兼容载体,不代表这些严格 profile 允许任意执行。
一棵树的形状
来自银行示例——统计物理作者文件 已验证。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、语义产品、图谱和代码锚点是派生物,不是竞争的业务模型。技术绑定与受支持的手写实现区各有明确契约;不要通过修改生成产物来改变业务规则。
范围层:你能说什么
两套词汇表,一张注册表。工作坊笔记类型是发现面(一墙便签的去处);原子种类是编译后的契约。已对照 lib/shared.mjs 验证
15 种笔记类型——工作坊入口
| 分组 | 类型 | 承载什么 |
|---|---|---|
| 行为 | event · command · policy · timer | 领域事件、请求变更的命令、反应策略、时间触发器——EventStorming 的词汇。 |
| 结构 | aggregate · entity · field · readModel | 一致性边界、实体、带血缘的字段、读侧投影。 |
| 战略 | context · subdomain · relation | 限界上下文、核心/支撑/通用分类、上下文间关系——DDD 的战略层。 |
| 人与系统 | role · externalSystem | 角色(及其可发出的命令,R12)和边界上的外部系统。 |
| 知识 | question · story | 不许悄悄消失的开放问题 / 热点,以及等待安放的用户故事。 |
12 种原子——编译后的契约
| 种类 | 文件 | 持有 |
|---|---|---|
note | inbox/** | 任意笔记类型的草稿工作坊笔记——等待人工晋升。 |
aggregate | aggregates/<slug>/aggregate.yaml | 身份、状态字段、有序的命令/事件池、具名的 @rule 不变量。 |
slice | slices/<slug>.slice.yaml | 因果单元:一条命令、它的守卫、它产生的事件、折叠赋值、溯源。 |
value-object | value-objects/<slug>.vo.yaml | 带类型的值——Money、AccountId 这类名义包装。 |
read-model | read-models/… | 读侧形状,每个字段带来源(血缘)。 |
policy | policies/… | 「当事件 X 则命令 Y」的反应规则。 |
story / use-cases | stories/… · use-cases.yaml | 用户故事,以及实现它们的流程。 |
pipeline | pipelines/<slug>.pipeline.yaml | 有序的业务步骤队列(只有步骤 steps,绝不叫「阶段 stages」)——编译为 Monarch 计划。 |
saga | sagas/<slug>.saga.yaml | 跨聚合 TCC 事务:参与者、阶段、补偿——编译为 saga-core IR。 |
scenario | scenarios/<slug>.scenario.yaml | 叙事式 runbook / 演示脚本。 |
formal-product | formal-products/… | 工程契约:技术端口、效果宿主、制品契约、宿主计算——生成代码必须满足的东西。 |
关系注册表——元模型的脊柱
22 种带类型的关系。propagates 标记是每条关系一次的人工裁定:这条边是否传导影响?blast_radius 恰好沿 propagates 边行走——宁可多报,不可漏报。已验证
| ID | 从 | 关系 | 到 | 传导 | 含义 |
|---|---|---|---|---|---|
| R1 | aggregate | owns | slice | ✓ | 结构上的拥有 |
| R2 | aggregate | references | aggregate | ✓ | 跨聚合引用 |
| R3 | aggregate | emits | event | ✓ | 事件池成员 |
| R4 | slice | issues | command | ✓ | 每切片一条命令(1:1) |
| R5 | slice | emits | event | ✓ | 切片产生的事件 |
| R6 | command | produces | event | ✓ | 因果性;条件在守卫里 |
| R7 | event | triggers | policy | ✓ | 反应规则 |
| R8 | policy | constrains | slice | ✓ | 策略约束切片 |
| R9 | policy | invokes | command | ✓ | 策略发出命令 |
| R10 | read-model | derives-from | field | ✓ | 读侧血缘 |
| R11 | field | lineage | field | ✓ | 字段到字段的链条 |
| R12 | role | can-issue | command | — | 是权限,不是影响 |
| R13 | read-model | visible-to | role | — | 可见性 |
| R14 | pipeline | has-step | step | ✓ | 有序步骤 |
| R15 | step | performed-by | role | — | 参与关系 |
| R16 | step | executes | slice | ✓ | 步骤执行切片 |
| R17 | story | covers | use-case | — | 可追溯性 |
| R18 | use-case | realized-by | slice | ✓ | 流程 → 切片 |
| R19 | scenario | exercises | pipeline | — | runbook 路径 |
| R20 | value-object | used-by | aggregate | ✓ | 类型使用 |
| R21 | context | depends-on | context | ✓ | 上下文映射 |
| R22 | aggregate | belongs-to | subdomain | — | 战略分类 |
战略层一眼看尽:R21 是上下文映射;R22 把聚合安放进核心/支撑/通用子域;R12/R13 承载谁能做什么、谁能看见什么。其余全是行为——而行为边传导影响。
治理:三道闸门,不是风格指南
validate——0 个硬发现
未知种类、悬空引用、事件在两处定义、切片没有所属聚合——全是硬发现。零是唯一可接受的计数。银行树截至 2026-11-11:0 硬发现 已验证。
roundtrip——逐字节一致
这是反格式漂移闸门。如果编译「顺手规范化」了任何东西,往返就会发散、闸门就会失败。银行树:157 个原子,逐字节一致 已验证。
compile-products——严格契约
端口、saga IR、执行 IR:从树编译而来的带类型、带版本的产物,各有各的验证。生成代码只消费冻结后的产物。