The language · from one rule to state
Describe the rule. Trace the change.
Start with Counter: a guard decides whether a command may proceed, a binding supplies an event’s payload, and a fold turns that event into state. Business declarations live in one author tree; technical bindings and handwritten implementations have separate responsibilities. Neither a graph nor a green gate replaces human agreement on the rule.
Minimal Counter · How folds work · Real bank slice · Expression reference · Relation registry
Counter: one causal chain, three views
1 · Business meaning
Start with count = 0. Request SetCount(id="counter-1", count=2). A nonempty id and a nonnegative count pass both guards. Bind the parameters into CountSet; applying that event sets id to counter-1 and count to 2. A negative count is rejected without an event. This is assignment, not increment.
2 · Current author input
These are reformatted JSON array fragments from the shipped Counter slice at cb860b5c, not a complete YAML file or project. Keep their original positions and the surrounding type declarations. The guide’s public init creates the whole project.
payload.guards — evaluated in order, against command parameters and current state.
[
{"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 — populate the event, not the state.
[
{"slot":"id","expr":"param.id"},
{"slot":"count","expr":"param.count"}
]
events.CountSet.foldAssignments — replay reads the recorded event, not the original command.
[
{"slot":"id","expr":"event.id"},
{"slot":"count","expr":"event.count"}
]
3 · Expanded semantic view — IR, not author input
The count assignment’s update subtree in admitted domain-folds@6 is below. The full product also carries target, type, source and dependencies. Do not paste this IR into expr.
{
"op": "set",
"value": {
"op": "ref",
"ref": {"context":"example","kind":"event-slot","owner":["Counter","CountSet"],"id":"count"}
}
}
Guard, binding, fold: different jobs
May this command proceed?
A true predicate proceeds to the next guard. On false, onFail: reject stops with its error code; succeed-empty stops successfully with no events. Neither runs later guards. The policy is not the predicate’s return value.
What fact is recorded?
Emission bindings fill event slots from declared command/state values, or explicitly admitted, version-pinned host outputs. An event field and a state field are not interchangeable.
What state follows this fact?
Event application alone evolves aggregate state. A fold replays state + event; it cannot call a host, read the clock/network or depend on the original command parameters.
Simultaneous updates, not a script
Every right-hand side and update base reads the same immutable pre-event snapshot. Compute all results, then form a new state. Removing a map entry in one assignment does not hide its old value from another. Each event may assign each target only once: no ordering trick, last-write-wins or intermediate-state reads.
A fold map read such as state.pending[event.key] produces an optional value in typed products. The receiving type must admit that optional; it is not an unchecked extraction. Even where a legacy tree precheck accepts a spelling, strict typed admission can still reject it.
Long/Int/Integer use canonical signed-64 decimal strings at the product/oracle boundary, never JS Number. Exact money needs declared nominal types, precision, scale and units. There is no implicit currency, rounding or conversion. Wrong units, precision or overflow fail; money-apply is an operator name, not a built-in banking policy. Host clocks and arbitrary Scala are not replay expressions; literal:SYSTEM_NOW is not a clock call in these strict products.
A real slice, unedited
From truth/bank-wealth/…/credit-balance/slices/initialize-account.slice.yaml. One command, five guards, one event, folds and provenance. This source excerpt is not a standalone project or a new bank acceptance run.
Business view: identity, conflict, then idempotency
ACCOUNT_ID: the requested resource must equal this aggregate’s id.ACCOUNT_CURRENCY: currency must be CNY and the amount must carry that same currency.ACCOUNT_INIT_CONFLICT: before initialization, proceed; afterwards require the same recorded amount. A different amount rejects before the idempotency guard.ACCOUNT_INIT_ONCE:!state.initializedbeing false means succeed-empty. A matching retry emits no second event and skips subsequent guards.ACCOUNT_SEED_NONNEGATIVE: a fresh seed must be>= 0.00. Zero is allowed; this is not the stricter money-positive predicate.
Current author view: original file bytes
# ═══ 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)"
]
}
}
Expanded semantic view — explanation, not author input
After all five guards pass, the three bindings record resource, currency and amount in AccountInitialized. Its fold sets initialized=true and puts the event amount under the event currency in accountBalance, both against the same pre-event snapshot. For a fresh matching account, 0.00 CNY is valid; a matching initialized retry has no event/fold; a conflicting amount is a rejection. This explains the declaration, not an independent execution of banking behavior.
Rules with teeth
Guards retain their order and their false-predicate outcome: reject rejects, while succeed-empty ends an idempotent retry without another event. “Non-negative balance” is no longer a comment — it compiles into the generated command handler.
Where payloads come from
Every event field is either propagated from a parameter or computed — provenance at the field level, which is what read-model lineage (R10/R11) builds on.
History becomes state
foldAssignments define how the event updates aggregate state — the algebra the generated event applier implements.
Current expression reference
Checked against toolchain cb860b5c, package 0.5.0. Author format, micro syntax and product profiles are separate versions. Counter selects decision @4, dependencies/folds @6; do not silently replace those profiles with an older example.
Current finite fold operations remain supported; reusable pure function definitions/references and function-level BDD are deferred in DEF-21, with syntax and definition location undecided and no relaxation of replay, type or version admission.
Seven fold operations
Each row below is an author object fragment inside an event’s foldAssignments, not standalone YAML. Example field names require matching declarations. Outer objects with string operands are the supported interim form; they are not the proposed final language design.
| Operation / author form | Arguments and meaning | Types, profile and limits |
|---|---|---|
set{"slot":"count","expr":"event.count"} | slot, expr; optional op:"set". Replace a value. | Exact target type required. Supported by fold products @1 onward. Use direct assignment, not the broken micro set form. |
put{"slot":"items","op":"put","key":"event.key","value":"event.value"} | slot, op, key, value. Insert or replace one key. | Map target; matching key and value types. Not a list append. Fold products @1 onward. |
remove{"slot":"items","op":"remove","key":"event.key"} | slot, op, key. Remove a key; absence leaves the map unchanged. | Map target, matching key type. No value argument. Fold products @1 onward. |
put-all{"slot":"items","op":"put-all","key":"event.keys","value":"event.value"} | key is a sequence; put the same scalar value at each key. | Map target; sequence element matches key type. Not a map merge or key/value zip. Fold products @1 onward. |
remove-all{"slot":"items","op":"remove-all","key":"event.keys"} | Remove the keys in the sequence. | Map target; scalar key is invalid here. No value/callback. Fold products @1 onward. |
money-apply{"slot":"balance","op":"money-apply","delta":"event.amount","sign":-1} | slot, op, delta, sign. Pre-event balance plus signed delta. | Admitted exact nominal target/delta, same units; sign exactly 1 or -1. No floating point. Fold products @1 onward with exact types. |
integer-apply{"slot":"count","op":"integer-apply","delta":"event.count","sign":1} | Pre-event signed-64 count plus signed delta; rejects overflow. | Integer target/delta. Author aggregate must opt into valueExpressionProfile:"truthsrc.domain-values/v2"; this marker alone does not select a product/generator. Typed fold products @1 onward. |
Do not mix four grammar layers
- Guard condition: finite
param/statepredicates, Boolean operators, comparisons and admitted collection/member operations. Signed-64 literals and finite+/-need decision @3/@4; older profiles differ. No arbitrary calls or Scala closures. - Author value: strings such as
event.count,literal:trueorliteral:1. Member paths need the author v2 opt-in. General infix arithmetic is not a fold value string. Nested literal/add/subtract objects recognized by value-product v2 are still refused by current author prechecks. - Micro carrier: opt in with system
authoring.micro:"truthsrc.micro/v1". JSON strings such as"count := event.count"and"items := @fold[put](key=event.key, value=event.value)"lower to those outer objects. Argument separation is comma + space; quote punctuation/whitespace using an inner JSON string, escaped in the outer JSON. Micro syntax does not widen semantic admission. - Typed product IR: closed
op/ref/valueTypeobjects, qualified identities and sources. This is compiler output, not a shortcut around author validation. See the unimplemented refinement RFC and three current defects; do not use@fold[set](value=...)as a recommended spelling.
Pinned references: AUTHORING · micro · SCHEMA · author values · PRODUCTS · typed folds/oracles. Historical sections describe broader legacy carriers; these strict profiles are not arbitrary execution permission.
The shape of a tree
From the bank example — physical author-file counts verified. The 59 independent VO atom files (F-10) plus 59 VOs expanded from structures give 118 VO nodes in the canonical graphstore (F-03); files and expanded nodes are different counting units.
truth/bank-wealth/
├── system.yaml # the system root: id, name, responsibility
├── inbox/ # workshop intake — notes are DRAFTS, not law
│ ├── 02-commands/ 05-context-map/ 06-aggregate-detail/ … # 13 product slots
└── contexts/bankwealth/
├── context.yaml # bounded context + its dependencies (R21)
├── aggregates/
│ ├── credit-balance/
│ │ ├── aggregate.yaml # state fields + named @rule invariants
│ │ └── slices/initialize-account.slice.yaml
│ ├── fund-order/ … # 27 slices across 3 aggregates
│ └── sip-plan/
├── value-objects/ # 59 independent VO atom files: Money, AccountId, AmountDecimal…
├── read-models/ # 6 read models with field lineage (R10/R11)
├── policies/ # event → command reaction rules (R7/R9)
├── stories/ # 4 user stories
├── use-cases.yaml # flows realized by slices (R18)
├── pipelines/ # 4 Monarch-style ordered step queues (R14–R16)
├── sagas/ # 2 TCC cross-aggregate transactions
└── formal-products/ # 36 contracts: ports, hosts, artifact contracts…
The author tree is the only place to edit business declarations. Compiled canonical, semantic products, graphs and code anchors are derived, not competing business models. Technical bindings and supported handwritten zones have their own explicit contracts; do not patch generated artifacts to change a rule.
Scope layer: what you can say
Two vocabularies, one registry. Workshop note types are the discovery surface (what a wall of sticky notes becomes); atom kinds are the compiled contract. verified against lib/shared.mjs
15 note types — the workshop intake
| Group | Types | What they carry |
|---|---|---|
| Behavior | event · command · policy · timer | Domain events, commands that request change, reaction policies, time triggers — the EventStorming vocabulary. |
| Structure | aggregate · entity · field · readModel | Consistency boundaries, entities, fields with lineage, read-side projections. |
| Strategy | context · subdomain · relation | Bounded contexts, core/supporting/generic classification, and inter-context relations — the strategic DDD layer. |
| People & systems | role · externalSystem | Actors (with the commands they may issue, R12) and external systems at the boundary. |
| Knowledge | question · story | Open questions / hotspots that must not silently vanish, and user stories awaiting placement. |
12 atom kinds — the compiled contract
| Kind | File | Holds |
|---|---|---|
note | inbox/** | Draft workshop notes of any note type — awaiting human promotion. |
aggregate | aggregates/<slug>/aggregate.yaml | Identity, state fields, ordered command/event pools, named @rule invariants. |
slice | slices/<slug>.slice.yaml | The causal unit: one command, its guards, the events it produces, fold assignments, provenance. |
value-object | value-objects/<slug>.vo.yaml | Typed values — Money, nominal wrappers like AccountId. |
read-model | read-models/… | Read-side shapes with per-field sources (lineage). |
policy | policies/… | “When event X then command Y” reaction rules. |
story / use-cases | stories/… · use-cases.yaml | User stories and the flows that realize them. |
pipeline | pipelines/<slug>.pipeline.yaml | An ordered business-step queue (steps, never “stages”) — compiled to a Monarch plan. |
saga | sagas/<slug>.saga.yaml | Cross-aggregate TCC transactions: participants, phases, compensation — compiled to saga-core IR. |
scenario | scenarios/<slug>.scenario.yaml | Narrative runbooks / demo scripts. |
formal-product | formal-products/… | Engineering contracts: technical ports, effect hosts, artifact contracts, host computations — what the generated code must satisfy. |
The relation registry — the metamodel’s spine
22 typed relations. The propagates flag is a human ruling per relation: does this edge carry impact? blast_radius walks exactly the propagates edges — over-reporting rather than missing. verified
| ID | From | Relation | To | Propagates | Meaning |
|---|---|---|---|---|---|
| R1 | aggregate | owns | slice | ✓ | structural ownership |
| R2 | aggregate | references | aggregate | ✓ | cross-aggregate reference |
| R3 | aggregate | emits | event | ✓ | event-pool membership |
| R4 | slice | issues | command | ✓ | one command per slice (1:1) |
| R5 | slice | emits | event | ✓ | events a slice produces |
| R6 | command | produces | event | ✓ | causality; conditions live in guards |
| R7 | event | triggers | policy | ✓ | reaction rules |
| R8 | policy | constrains | slice | ✓ | policy bounds a slice |
| R9 | policy | invokes | command | ✓ | policy issues a command |
| R10 | read-model | derives-from | field | ✓ | read-side lineage |
| R11 | field | lineage | field | ✓ | field-to-field chains |
| R12 | role | can-issue | command | — | permission, not impact |
| R13 | read-model | visible-to | role | — | visibility |
| R14 | pipeline | has-step | step | ✓ | ordered steps |
| R15 | step | performed-by | role | — | participation |
| R16 | step | executes | slice | ✓ | a step runs a slice |
| R17 | story | covers | use-case | — | traceability |
| R18 | use-case | realized-by | slice | ✓ | flow → slices |
| R19 | scenario | exercises | pipeline | — | runbook path |
| R20 | value-object | used-by | aggregate | ✓ | type usage |
| R21 | context | depends-on | context | ✓ | the context map |
| R22 | aggregate | belongs-to | subdomain | — | strategic classification |
Strategic layer in one glance: R21 is the context map; R22 places aggregates in core/supporting/generic subdomains; R12/R13 carry who may act and who sees what. Everything else is behavior — and behavior edges propagate impact.
Governance: three gates, not style guides
validate — 0 hard findings
Unknown kinds, dangling references, an event defined in two places, a slice without its aggregate — all hard findings. Zero is the only acceptable count. Bank tree as of 2026-11-11: 0 hard verified.
roundtrip — byte-identical
This is the anti-formatting-drift gate. If compilation “normalizes” anything, the roundtrip diverges and the gate fails. Bank tree: 157 atoms, byte-identical verified.
compile-products — strict contracts
Ports, saga IR, execution IR: typed, versioned products compiled from the tree with their own validation. Generated code consumes frozen products only.
The editing contract for AI agents is the same three gates plus stewardship rules: every batch ends validate AND roundtrip green; payload text is preserved verbatim; no tool artifacts inside the tree; one event defined in exactly one slice. It ships with the toolchain as AGENTS.md and a query skill pack.