@hyperscale0/udl 1.0.0-beta.1 → 1.0.0

package/docs/guide/07-evolution.md

@@ -0,0 +1,11 @@
+# Evolution
+
+`diffValidatedUdlEvolution(live, next)` compares two admitted documents. The CLI exposes the same check as `udl diff live.udl next.udl`.
+
+Once instances exist, a new version may add optional fields, states, transitions, and actions. It may not remove or rename stored structure, tighten an admitted schema, change a money step, or reuse an existing version number for different executable meaning. The diff returns `UDL7xxx` issues with JSON paths.
+
+A migration is work outside the format. It reads stored instances under their original document, writes data required by a new document, and changes the pinned definition only after that work succeeds. Editing the document does not migrate data.
+
+Keep old canonical documents with stored instances. A format bump changes the literal `udl` value. A reader must keep explicit decoders for supported older formats rather than silently treating old bytes as the newest grammar.
+
+Evolution does not invent defaults for executable clause fields. In particular, it does not guess `reconcile.exception.amountField` or `reasonField` for an older snapshot. A candidate must name both fields and pass the current validator before the diff can judge it.

package/docs/guide/08-implementing.md

@@ -0,0 +1,13 @@
+# Implementing UDL
+
+A second implementation needs three independent checks.
+
+1. Validate JSON shape against `spec/udl.schema.json`.
+2. Enforce the whole-document laws and report the matching `UDL####` code and JSON path.
+3. Serialize admitted documents under the canonical bytes law.
+
+Run every conformance level. Valid cases must admit and match their canonical bytes and SHA-256 digest. Invalid cases must report every listed code and path. Evolution pairs must produce the listed `UDL7xxx` issues. An implementation may report more issues, but it may not omit a listed issue.
+
+Do not key behavior on diagnostic messages. Titles, details, and fixes can become clearer. Codes cannot change once published.
+
+Keep parsing, validation, canonicalization, and evolution comparison separate. That split prevents a diff from judging a candidate that the validator would refuse on its own.