Appendix D — Migration Notes

Argon is in the middle of a measured surface redesign. The body of the book teaches today’s argon-v0.4.x syntax, which is what the toolchain accepts and what the UFO team needs to ship. This appendix is the lever that keeps the book honest as the redesign rolls out: every chapter that flags a migration points here, and every row here carries the trajectory from “what you write today” to “what the redesigned form will look like.”

The redesign is captured-direction, not yet ratified. The team is exploring the moves below; today’s syntax remains supported, and migrations will land additively with a window during which both forms are accepted.

How to read this appendix

Each row has three columns:

Today — what the toolchain accepts at argon-v0.4.x. This is what the chapters teach.
Trajectory — the shape the team is exploring. Captured-direction, subject to refinement.
Where discussed — the chapter that flags the migration in passing.

Where a column reads “open”, the design is in active discussion and the chapter does not commit to a target form.

The migration map

Today	Trajectory	Where discussed
`lifecycle { phases, transitions }` inside a concept body	`statemachine X { states { … } transitions { … } }` as a top-level item, desugaring to `enum + rule + Transition` event	Ch3.2
`Source -> Target { brings_about { Event } }` (lifecycle effect)	`Source -> Target :- guard => Transition(from, to)` (rule with explicit event consequence)	Ch3.2
`phase` metatype with implicit sibling-disjointness via partition	`phase` metatype with explicit `axioms { siblings_disjoint, siblings_complete }` block	Ch2.2, Ch3.2
`partition Animal { Mammal, Bird, Fish }` (item-decl axiom)	Implicit on the `subkind` metatype via `axioms { siblings_disjoint }`; explicit-decl form retained for subset-partitions	Ch2.2
`specializes(?x, T)` (rule-body subtype predicate)	`is_subtype(?x, T)`	Ch2.6
`generalizes(T, ?x)`	`is_supertype(T, ?x)`	Ch2.6
`assert P(...) :- body => error("…")`	`[pub] rule P(...) :- body => Error("…")` (rule-shape with explicit `Error` event)	Ch2.4
`derive H :- body => escalate("...", args)`	`[pub] rule H :- body => Escalate("...", args)` (rule-shape with user-defined event)	Ch2.4
`severity-constraint` declarations	Folded into rule-shape with `Error` / `Warn` / `Info` event consequences	Ch2.4
`package-constraint` declarations	Folded into rule-shape with `Error` event consequence	Ch2.4
`mutation X(...) { do { stmts } emit Event return v }`	`mutation X(...) { stmts; emit Event; return v }` (raw statements; `do` keyword removed)	Ch2.5
`Money` (language-core primitive)	`std::finance::Money` (in the `std::finance` package, language-core stays domain-neutral)	Ch2.3, Ch2.6
`correlative_pair` / `part_whole` / `power_type` (declarable item-forms)	`std::patterns::*` (user-defined patterns, not language-core declarables)	n/a (deferred to Part 5)
`powertype` (hard-reserved keyword) — still parsed and reserved today, with a `PowertypeDecl` AST and parser surface	Modelled via the metatype mechanism + user package; the keyword reservation comes off once the user-package replacement lands	n/a (deferred to Part 5)
`hypothetical { … }` (block)	`hypo { … }` (alias added; both spellings accepted)	Ch5 (later)
`@[ontouml_id]` / `@[layout]` / `@[ontouml_stereotype]` (compiler attributes)	Moved out of the compiler — handled by the OntoUML package and the diagram-DSL respectively	Ch1.1, Ch3.4
`mediates(...)` / `relator(...)` / `has_mediation_path(...)` (constraint atoms)	UFO-specific — moved to `ufo::*` package definitions	n/a (deferred to Part 5)
`no_kind_in_path(...)`	Generalized to `no_metatype_in_path(M, ...)`; UFO sugar `no_kind_in_path` becomes a one-line user alias	n/a (deferred to Part 5)

Five locked design moves

The redesign organizes around five themes. Each row above belongs to one or more of them.

Three deliberate body shapes. Argon ends up with three principled body shapes: :- pred-body for declarative predicate items (rules, asserts, queries, transitions); { stmts } for imperative blocks (mutations, compute Form-2, tests, hypothetical, unsafe); = expr for single-expression definitions (compute Form-1, FFI bindings, let-bindings).
Rule-shape unification. derive, assert, lifecycle transitions, severity/package constraints — all reduce to [pub] rule X :- body [=> consequence] with implicit consequences for the common cases. derive keeps its sugar for the most-common implicit => FactDerived(H); assert keeps its sugar for implicit => Error("…").
Events as the universal effect type. Consequences become events; events are the universal effect mechanism across all three computational modes. Mutations emit events imperatively; rules emit events when their bodies fire; computes do not emit events at all (preserving referential transparency).
State-machine sugar. lifecycle collapses into statemachine X { states { … } transitions { … } }, which is sugar over enum + rule + Transition event. The four lifecycle-related grammar productions fold into one sugar wrapper.
Group axioms via metatype-axiom integration. Sibling-disjointness, sibling-completeness, and partition constraints move from declaration-site keywords to metatype-level axioms { … } blocks. The metatype is the constraint handle.

What is not changing

For clarity:

The 6-layer architecture (lexical / syntactic / semantic / evaluation / package / toolchain).
The Cargo-shape package system (ox.toml, lockfile, registry, prelude pattern, direct-deps rule).
The toolchain layer (ox, oxup, ox-lsp, ~/.argon/ state directory).
The three-engine reasoning pipeline.
The decidability tier ladder.
Bitemporal axes, standpoints, fork semantics.
The mechanically-verified core (refinement-fragment decidability, occurrence-typing soundness, meta-property fixpoint termination).
Three-valued semantics under OWA.
Module structure and two-tier visibility.
Doc-comment conventions (/// outer, //! inner, Markdown content).

These are the stable structural commitments. The redesign is surface-level and item-system-level; the underlying architecture stays.

Reading the rest of the book

Where a chapter says “the team is exploring …” in a callout, the corresponding row above is what they are exploring. The body of each chapter teaches today’s syntax and shows code that compiles and runs at argon-v0.4.x. When migrations land, this appendix flips: each row’s “today” column moves to a “former” column, the “trajectory” column becomes the canonical syntax, and the chapter’s callout becomes a “historical note” pointing back at what changed.

That is the Book’s discipline. The model on the page works today. The trajectory is visible. The migrations land additively, with a window. No reader has to chase a moving target.