@hyperscale0/udl 1.0.0-alpha.5 → 1.0.0-rc.1

package/CHANGELOG.md

@@ -10,39 +10,91 @@ here under the release that made it.
 
 ## [Unreleased]
 
+## [1.0.0-rc.1] - 2026-09-02
+
+### Added
+
+- Stable `UDL####` diagnostics include a category, fix, message, and JSON path.
+- Evolution comparison returns coded issues instead of strings.
+- `canonicalDigest` returns a promise for SHA-256 over canonical UTF-8 bytes.
+- `udl canon` prints canonical bytes or their digest, and `udl explain` prints
+  the catalog entry for one code.
+- The conformance runner has evolution pairs and pins canonical digests, issue
+  codes, and paths.
+- Eight guides, generated clause, diagnostic, and command references,
+  `llms.txt`, `llms-full.txt`, and an agent skill now ship with the package.
+
+- `reconcile` declares one expectation about money an action cannot see yet:
+  the amount path, currency field, direction, the ref naming the provider-side
+  row, exactly one evidence source, a match law, and a window. The match law is
+  `exact`, `tolerance` bounded by a `reconcile_tolerance` dial, or `window`. An
+  expectation that never matches by the end of its window is carried by the
+  named exception child, capped by `maxOpen`. The child is declared and
+  validated at admission, not materialized: the transition refuses with
+  `state_conflict` naming it and the due sweep re-arms the expectation.
+  `UdlReconcile` exposes the clause type.
+- An action may declare a `quote` offer and exactly one other action may spend
+  it through `commit`. Both the base money field and the net destination are
+  mandatory members of `fixes`, and `fixes` and `updates` may not overlap.
+
+### Removed
+
+- `requiresSettlement` and `UdlRequiresSettlement` are gone. A payout-owning
+  instrument now declares exactly one action carrying `reconcile` against a
+  debit statement line, under any match law. There is no wrapper and no alias.
+
+### Changed
+
+- The npm package includes `docs/` and `skills/`.
+- Derived effect rows for `quote`, `commit`, and `reconcile` change the canonical
+  bytes of stored documents that carry `effects` for those clauses.
+- Format 1 now carries every instrument contract clause. Instrument metadata
+  includes archetype template, navigation, visibility, dials, caller-parked
+  states, and extensible subjects. Actions include check gates, remainder
+  arithmetic, field updates, principal policy, and sandbox failure points.
+- Remainder clauses declare their computed money refs, so computed money has
+  one authored source.
+- Evolution snapshots protect lifted clauses that affect composition,
+  admission, or execution. Navigation, examples, and parked-state reason text
+  remain editable presentation.
+
+## [1.0.0-beta.1] - 2026-08-29
+
+- This is the first beta and has no package behavior changes from
+  1.0.0-alpha.5.
+
 ## [1.0.0-alpha.5] - 2026-08-29
 
 ### Added
 
-- Verbs may declare a camelCase `publicIntent` as their author-approved public
-  name while the verb key remains the lifecycle and execution identity. System
-  due verbs must omit it. `udlPublicIntentSchema` is exported for consumers
+- Actions may declare a camelCase `publicAction` as their author-approved public
+  name while the action key remains the lifecycle and execution identity. System
+  due actions must omit it. `udlPublicActionSchema` is exported for consumers
   that admit the same name outside a complete document.
-- `captureInput` maps declared verb input fields into durable receipt refs.
-  Declare only input properties from that verb and allocate each captured key
-  in the noun's shared ref namespace.
+- `captureInput` maps declared action input fields into durable receipt refs.
+  Declare only input properties from that action and allocate each captured key
+  in the instrument's shared ref namespace.
 - `signedSum` computes stored add and subtract subtotals over typed child money,
-  then captures one net amount for exactly one payout or noun transfer. Authors
+  then captures one net amount for exactly one payout or instrument transfer. Authors
   must declare the child reference, money field, currency, admitted statuses,
   and explicit negative and zero policies.
 - `requiresExposure` gates a child amount against a stored cap, with an optional
   anchor-specific cap, and `setsAt.marker` records occurrence timestamps that
   cannot drive a due condition or deadline. Use these clauses for bounded
   installment writes and per-anchor occurrence markers.
-- `distribute` allocates one parent money field or computed money ref across
-  typed children selected by status and stored weight. Declare runtime-owned
-  money refs in `computedMoneyRefs`; the validator resolves the parent,
-  weight, statuses, and pool before admitting the document.
-- Nouns may declare up to four `derivedAmounts`. Each rule computes a declared
+- `distribute` allocates one parent money field or remainder-computed money ref
+  across typed children selected by status and stored weight. The validator
+  resolves the parent, weight, statuses, and pool before admitting the document.
+- Instruments may declare up to four `derivedAmounts`. Each rule computes a declared
   money field as 1 through 9,999 basis points of another declared money field
   with floor rounding. Callers supply neither the result nor a fixed or tiered
   rule, and a rule may not derive a field from itself.
-- Verbs may declare one `payout` intent that reads stored money, currency,
+- Actions may declare one `payout` intent that reads stored money, currency,
   source-account, and beneficiary values and captures the payout reference.
   This does not add an operation to the seven-instruction kernel.
 - A system-only `requiresSettlement` transition may read a captured payout
   reference and capture the durable evidence record that matched it. The
-  validator rejects caller input, decision ports, public intents, due and
+  validator rejects caller input, decision ports, public actions, due and
   deadline triggers, kernel steps, and money moves on that transition.
 - `validateUdlJsonSchema` validates one schema against UDL's sealed JSON Schema
   subset without applying it to a value. `UdlPayout` and
@@ -50,12 +102,12 @@ here under the release that made it.
 
 ### Changed
 
-- Evolution snapshots freeze public intents, captured receipt input,
-  distribution rules, exposure gates, signed sums, computed money refs, and
-  derived-amount arithmetic once a noun has live instances. Older snapshots
+- Evolution snapshots freeze public actions, captured receipt input,
+  distribution rules, exposure gates, signed sums, computed money clauses, and
+  derived-amount arithmetic once a instrument has live instances. Older snapshots
   remain readable when those keys are absent.
 - Evolution snapshots freeze both payout intents and settlement evidence gates.
-- Receipt refs written by the new clauses share the noun ref namespace with
+- Receipt refs written by the new clauses share the instrument ref namespace with
   kernel captures, input captures, signed sums, subject refs, and unwind refs.
 
 ## [1.0.0-alpha.4] - 2026-08-26
@@ -78,16 +130,16 @@ here under the release that made it.
   refuses now throws a `UdlError` carrying that document's issues where
   alpha.2 returned evolution violations. Measured on
   `conformance/valid/protection.udl` with the product renamed to
-  `protection_v2` and the live `claim` noun dropped: alpha.2 returned three
-  violations, naming the rename, the removed live noun, and the version that
+  `protection_v2` and the live `claim` instrument dropped: alpha.2 returned three
+  violations, naming the rename, the removed live instrument, and the version that
   did not move; this release throws `invalid_semantics` at
-  `$.nouns[0].aggregateInvariants[0].childNounId`, because another noun's
+  `$.instruments[0].aggregateInvariants[0].childInstrumentId`, because another instrument's
   aggregate still references `claim`.
 
   Read the throw as a refusal to judge, not as a verdict of no violations.
   A `catch` that treats it as a schema problem and carries on has skipped the
   append-only check entirely, and the candidate above is exactly the kind that
-  then sails through: dropping a live noun is the headline violation the law
+  then sails through: dropping a live instrument is the headline violation the law
   exists to catch. Fix the document, or use `diffValidatedUdlEvolution`.
 
   The parameters are `unknown` because the function now accepts input nobody
@@ -106,8 +158,8 @@ here under the release that made it.
 - The comparison key behind every diff carries the same depth budget the
   validator applies to a document (`UDL_LIMITS.maxDepth`, 24 levels; the
   deepest conformance document reaches 12). This is what protects
-  `diffNounEvolution`, which takes snapshots no validator has seen, and it
-  closes the case where `snapshotUdlNoun` returns a cyclic snapshot that only
+  `diffInstrumentEvolution`, which takes snapshots no validator has seen, and it
+  closes the case where `snapshotUdlInstrument` returns a cyclic snapshot that only
   detonates when something later stringifies it.
 
 ### Added
@@ -152,7 +204,9 @@ First public release. Format version 1.
 - `bun run spec:check`, which fails when the committed schema drifts from the
   grammar it was generated from.
 
-[Unreleased]: https://github.com/hyperscale0/hyperscale-udl/compare/v1.0.0-alpha.5...HEAD
+[Unreleased]: https://github.com/hyperscale0/hyperscale-udl/compare/v1.0.0-rc.1...HEAD
+[1.0.0-rc.1]: https://github.com/hyperscale0/hyperscale-udl/compare/v1.0.0-beta.1...v1.0.0-rc.1
+[1.0.0-beta.1]: https://github.com/hyperscale0/hyperscale-udl/compare/v1.0.0-alpha.5...v1.0.0-beta.1
 [1.0.0-alpha.5]: https://github.com/hyperscale0/hyperscale-udl/compare/v1.0.0-alpha.4...v1.0.0-alpha.5
 [1.0.0-alpha.4]: https://github.com/hyperscale0/hyperscale-udl/compare/v1.0.0-alpha.3...v1.0.0-alpha.4
 [1.0.0-alpha.3]: https://github.com/hyperscale0/hyperscale-udl/compare/v1.0.0-alpha.2...v1.0.0-alpha.3

package/README.md

@@ -1,22 +1,10 @@
 # UDL
 
-UDL is the Universal Domain Language: a JSON document format for describing
-a financial product in business terms. One `.udl` file declares the product's
-subjects, its nouns, each noun's lifecycle, the verbs that move instances
-through that lifecycle, and how money moves while they do. Everything else,
-SDKs, docs, tool surfaces, the running engine, is generated from it or checked
-against it.
-
-The language deliberately cannot say certain things. There is no statement
-format, no file drop, no polling loop, no cutoff time, no scheme name, no
-reconciliation vocabulary. Those are real and they are somebody's problem, but
-they are not the product, so they are absorbed below the language and never
-surface in a document. What is left is small enough to hold in your head.
-
-This package is the reference implementation: parser, semantic validator,
-canonical serializer, evolution diff, and the `udl` command. The format itself
-is specified in [`spec/`](./spec/README.md) and pinned by
-[`conformance/`](./conformance/README.md).
+UDL is the Universal Domain Language, the canonical JSON contract for a financial product. One `.udl` file declares subjects, instruments, lifecycles, actions, and money movement. An engine can admit that document without reading the source language that produced it.
+
+UDL keeps provider machinery below the format. It has no file drops, polling loops, cutoff jobs, scheme messages, or provider statement schemas. The `reconcile` clause names settlement evidence against a declared provider-side row. It does not model the provider file or transport.
+
+This package contains the parser, semantic validator, canonical serializer, append-only evolution diff, JSON Schema, and conformance corpus.
 
 ## Install
 
@@ -24,18 +12,17 @@ is specified in [`spec/`](./spec/README.md) and pinned by
 npm install @hyperscale0/udl
 ```
 
-Every release before 1.0.0 is an alpha, and `latest` follows the newest one, so
-a bare install gets it. Pin an exact version if you need one: until 1.0.0 a
-change to the surface ships as a minor bump, not a major.
+`1.0.0-rc.1` freezes the candidate format for one full wave of use. Pin the release candidate while testing another implementation. Format 1 freezes when the package reaches `1.0.0`.
 
 ## Thirty seconds
 
-`note.udl`, the smallest document the format accepts:
+`note.udl` is the smallest admitted document.
 
 ```json
 {
-  "nouns": [
+  "instruments": [
     {
+      "actionOrder": ["close", "create"],
       "fields": { "reference": { "type": "string" } },
       "id": "note",
       "idPrefix": "note",
@@ -47,7 +34,7 @@ change to the surface ships as a minor bump, not a major.
       "required": ["reference"],
       "summary": "A note a tenant files and later closes.",
       "title": "Note",
-      "verbs": {
+      "actions": {
         "close": { "moves": [], "steps": [], "summary": "Close the note." },
         "create": { "moves": [], "steps": [], "summary": "File the note." }
       }
@@ -64,6 +51,7 @@ change to the surface ships as a minor bump, not a major.
 ```ts
 import { readFile, writeFile } from "node:fs/promises";
 import {
+  canonicalDigest,
   diffValidatedUdlEvolution,
   parseUdl,
   serializeUdl,
@@ -71,103 +59,52 @@ import {
 } from "@hyperscale0/udl";
 
 const document = parseUdl(await readFile("note.udl"));
-
-// One document, one byte sequence. Sorted keys, two-space indent, final LF.
 await writeFile("note.udl", serializeUdl(document));
+console.log(await canonicalDigest(document));
 
-// Issues carry a stable code and a JSON path, never just a sentence.
 const result = validateUdl(document);
 if (!result.ok) console.error(result.issues);
 
-// Is this change legal against the version that already has live instances?
-const live = parseUdl(await readFile("note.live.udl"));
-const violations = diffValidatedUdlEvolution(live, document);
+const previous = parseUdl(await readFile("note.previous.udl"));
+const violations = diffValidatedUdlEvolution(previous, document);
 ```
 
-`parseUdl` takes a string or a `Uint8Array`; bytes are decoded as strict UTF-8.
-`serializeUdl` validates before it writes, so an invalid document has no
-canonical form.
+Every issue has a stable `UDL####` code, a category, a JSON path, a message, and a fix. Messages may become clearer. Codes do not change once published.
 
-`diffValidatedUdlEvolution` takes two `UdlDocument`s and assumes both have
-already been admitted. Validate first: an evolution verdict on a document
-`validateUdl` refuses is not a verdict at all, and a candidate that drops a
-live noun sails through a diff that never checked whether the noun was
-referenced. The `UdlDocument` parameter types are what keeps the compiler on
-your side of that rule.
+`parseUdl` accepts a string or `Uint8Array` and rejects malformed UTF-8. `serializeUdl` validates before writing. It sorts object keys by UTF-16 code unit, keeps array order, uses two-space indentation, and writes one final line feed. `canonicalDigest` hashes those UTF-8 bytes with SHA-256 and returns a promise for the lowercase hexadecimal digest.
 
-## The command
+The seven kernel operations are `internal_transfer.create`, `internal_transfer.reserve`, `internal_transfer.post`, `internal_transfer.void`, `account.escrow.provision`, `account.freeze`, and `account.unfreeze`. A `payout` is an execution intent, not another kernel operation.
 
-```bash
-udl validate product.udl        # parse and report every issue found
-udl fmt product.udl             # print the canonical form
-udl fmt product.udl --write     # rewrite the file in place
-udl diff live.udl product.udl   # is the change additive, or does it break?
-```
-
-Exit codes: `0` the document is admissible or the change is additive, `1` the
-document was refused or the change breaks the append-only law, `2` the command
-line was wrong or a file could not be read. That split matters in CI: a broken
-document and a broken invocation are different failures.
+The compiler derives action `effects` from clauses. The validator rejects a supplied effects object unless every row and its order match. Derived effects do not consume the authored node budget.
 
-## The two things worth knowing
+## Command line
 
-**Evolution is append-only.** Once a definition has live instances, you may add
-states, transitions, optional fields, and verbs. You may not remove, rename,
-tighten, or change a money step. `udl diff` is not advice; it is the same
-function the compiler runs before it will accept a new version.
+```bash
+udl validate product.udl
+udl fmt product.udl --write
+udl canon product.udl
+udl canon product.udl --digest
+udl diff frozen.udl product.udl
+udl explain UDL5001
+```
 
-**Internal ledger money moves through four instructions and no others.**
-`internal_transfer.create`, `.reserve`, `.post`, `.void`. Three account
-instructions complete the sealed set. A noun cannot invent a fifth money path,
-which is why a document can be checked for stranded value before anything runs.
-The separate `payout` intent carries a stored amount to the execution core and
-captures its durable reference. A later `requiresSettlement` transition stays
-system-only and runs only after that payout matches durable settlement evidence.
+Exit code `0` means success. Exit code `1` means the validator or evolution law refused the document. Exit code `2` means the invocation or file read failed.
 
-## The spec
+## Documentation
 
-- [`spec/README.md`](./spec/README.md) is the specification: the ten laws, the
-  canonical form, the issue codes, and what the schema deliberately cannot say.
-- [`spec/udl.schema.json`](./spec/udl.schema.json) is JSON Schema 2020-12,
-  generated from the grammar. Where prose and schema disagree, the schema wins.
-- [`conformance/`](./conformance/README.md) is the semantic spec: `.udl` inputs
-  with expected verdicts, canonical bytes, and issue codes, runnable from any
-  language.
+- [Guide and reading order](docs/README.md)
+- [Format specification](spec/README.md)
+- [Canonical bytes law](docs/reference/canonical.md)
+- [Stable diagnostics](docs/reference/diagnostics.md)
+- [Conformance runner contract](conformance/README.md)
+- [Agent skill](skills/udl/SKILL.md)
 
 ## Versioning
 
-Two numbers move independently.
-
-**Format version** is the literal `"udl": 1` inside a document. Format 1 is the
-only format that exists.
-
-**Package version** is this package's semver, in `package.json`.
-
-Format 1 is unstable until the package reaches 1.0.0. Until then an alpha
-release may change what format 1 accepts, and every such change is listed in
-[`CHANGELOG.md`](./CHANGELOG.md). After 1.0.0, format 1 is frozen and an
-incompatible change bumps the literal to `2`.
-
-## Status
-
-Alpha. The format is in use, the API surface is settled enough to build on, and
-the version number is honest about the rest. Breaking changes go in the
-changelog, not in a footnote.
-
-## Contributing
+The literal `"udl": 1` is the format version. The version in `package.json` is the package version. They move independently. After package version `1.0.0`, an incompatible format change uses a new format literal and keeps an explicit reader for stored format 1 documents during its stated support window.
 
-Issues only. Hyperscale makes the changes to the format and the package; you
-propose them in an issue carrying the use case and the conformance case it
-would add. [`CONTRIBUTING.md`](./CONTRIBUTING.md) has that model in full, plus
-the dev setup, the test commands, and how to regenerate the spec. Conduct:
-[`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md). Vulnerabilities:
-[`SECURITY.md`](./SECURITY.md).
+## Contributing and license
 
-## License
+Hyperscale accepts format proposals as issues with a use case and the conformance case they would add. See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and proof commands.
 
-AGPL-3.0-only, with a commercial license available from Hyperscale LLC for
-organisations that cannot accept the AGPL. See [`LICENSE`](./LICENSE) for the
-text and [`LICENSING.md`](./LICENSING.md) for which one you want and how to ask
-for the commercial one. The marks are not covered by either; see
-[`TRADEMARKS.md`](./TRADEMARKS.md), which also carries the rule for claiming
-UDL compatibility.
+UDL is AGPL-3.0-only. Hyperscale LLC also offers a commercial license. See [LICENSING.md](LICENSING.md) and [TRADEMARKS.md](TRADEMARKS.md).

package/conformance/README.md

@@ -1,23 +1,23 @@
 # The UDL conformance suite
 
-Every file here is data. Nothing in this directory imports the reference
-implementation, so a UDL implementation in any language can run the suite by
-reading files and comparing bytes.
-
-`../test/conformance.spec.ts` is the reference runner. Read it if a rule below
-is ambiguous.
+Every file here is data. An implementation in any language can run the suite
+without importing the TypeScript reference implementation.
 
 ## Layout
 
 ```
 conformance/
-  valid/    documents the format accepts, each with its canonical form
-  invalid/  documents the format refuses, each with the issues it must report
+  valid/<case>.udl
+  valid/<case>.expected.json
+  invalid/<case>.udl
+  invalid/<case>.expected.json
+  evolution/<case>.live.udl
+  evolution/<case>.next.udl
+  evolution/<case>.expected.json
 ```
 
-Every `<case>.udl` has a sibling `<case>.expected.json`. A file without its
-sibling is a case that silently stopped running, so the runner fails on
-orphans in either direction.
+The runner fails if either half of a case is missing. An evolution case must
+have all three named files.
 
 ## Expected files
 
@@ -26,54 +26,57 @@ A valid case:
 ```json
 {
   "canonical": "minimal.udl",
-  "summary": "Compact, reverse-ordered bytes canonicalize to minimal.udl.",
+  "digest": "c21d198d69e9d4cadb33aaacf37581bb388e4a8964b7fc284606cfa9f65d35bb",
+  "summary": "The smallest admitted document.",
   "verdict": "valid"
 }
 ```
 
-`canonical` names the file in `valid/` holding the canonical bytes for this
-input. A document that is already canonical names itself.
+`digest` is lowercase SHA-256 over the canonical UTF-8 bytes. A document that
+is already canonical names itself.
 
 An invalid case:
 
 ```json
 {
-  "issues": [{ "code": "invalid_semantics", "path": "$.nouns[0].verbs" }],
-  "summary": "Every noun declares create: nothing else can bring an instance into being.",
+  "issues": [{ "code": "UDL3001", "path": "$.instruments[0].actions" }],
+  "summary": "Every instrument declares create.",
   "verdict": "invalid"
 }
 ```
 
-`summary` is for humans reading a failure. Nothing asserts against it beyond
-requiring it to be present and non-blank.
+The runner requires a non-blank `summary`. It never compares messages.
 
-## The three levels
+## Conformance levels
 
-An implementation claims conformance at the highest level it passes.
+An implementation claims the highest level it passes.
 
-**Level 1, verdict.** Read the file as bytes. Every `valid/` case is admitted
-and every `invalid/` case is refused. This is the whole contract for a
-validator.
+1. Verdict. Admit every `valid/` document and refuse every `invalid/` document.
+2. Canonical bytes. Serialize every valid document byte for byte as its named
+   canonical file, including the trailing line feed, and match its digest.
+3. Diagnostics. Report every listed code and path for each invalid document.
+   The implementation may report extra issues.
+4. Evolution. Admit both documents, then compare the live and next definitions.
+   Report every listed UDL7xxx code and path. The implementation may report
+   extra issues.
 
-**Level 2, canonical bytes.** For each `valid/` case, serialize the parsed
-document and compare it byte for byte against the file named by `canonical`.
-Any implementation that writes UDL must pass this, or two tools will disagree
-about what the same document is.
+## Path grammar
 
-**Level 3, issues.** For each `invalid/` case, every listed `code` and `path`
-pair appears among the reported issues. Extra issues are allowed, because
-implementations legitimately differ on how many problems they report before
-giving up. Messages are never compared; they are prose and they are free to
-change.
+Issue paths use `$` for the document root, `.name` for an object member, and
+`[n]` for a zero-based array index. Evolution paths use the instrument index
+from the live document and continue to the changed member, such as
+`$.instruments[3].actions.reconcile`. A direct `diffInstrumentEvolution` call
+has no document index, so its paths start at `$.instruments`.
 
-## Adding a case
+## Runner exit rule
 
-Write the `.udl` and its `.expected.json`, then run `bun test`. Keep new cases
-small and single-purpose: the point of `invalid/blank-title.udl` is that it
-differs from `valid/minimal.udl` in exactly one key. `valid/minimal.udl` is the
-smallest document both the grammar and the semantic laws accept, and it is the
-right base to mutate.
+The runner exits 0 only if every case at the claimed level passes. A missing
+file, malformed expected file, unexpected verdict, byte mismatch, digest
+mismatch, or missing issue pair makes it exit nonzero.
+
+## Adding a case
 
-The five domain documents in `valid/` are the real thing, projected from a
-shipped product catalog. They are large on purpose: they are what catches a
-regression the minimal case cannot see.
+Start from the smallest admitted document that carries the needed clause.
+Change one law where possible. Pin codes and paths, never messages. Valid cases
+must keep one example of every target in `udlClauseVocabulary`, including
+quote, commit, reconcile, checks, updates, dials, effects, and money clauses.

package/conformance/evolution/action-contract.expected.json

@@ -0,0 +1,10 @@
+{
+  "issues": [
+    {
+      "code": "UDL7001",
+      "path": "$.instruments[0].actions.close"
+    }
+  ],
+  "summary": "Evolution identifies the changed action beneath the previous instrument index.",
+  "verdict": "invalid"
+}

package/conformance/evolution/action-contract.live.udl

@@ -0,0 +1,44 @@
+{
+  "instruments": [
+    {
+      "actionOrder": ["close", "create"],
+      "actions": {
+        "close": {
+          "moves": [],
+          "steps": [],
+          "summary": "Close the note."
+        },
+        "create": {
+          "moves": [],
+          "steps": [],
+          "summary": "File the note."
+        }
+      },
+      "fields": {
+        "reference": {
+          "type": "string"
+        }
+      },
+      "id": "note",
+      "idPrefix": "note",
+      "lifecycle": {
+        "initial": "open",
+        "states": ["open", "closed"],
+        "transitions": {
+          "close": {
+            "from": ["open"],
+            "to": "closed"
+          }
+        }
+      },
+      "required": ["reference"],
+      "summary": "A note a tenant files and later closes.",
+      "title": "Note"
+    }
+  ],
+  "product": "minimal",
+  "subjects": [],
+  "title": "Minimal",
+  "udl": 1,
+  "version": 1
+}

package/conformance/evolution/action-contract.next.udl

@@ -0,0 +1,45 @@
+{
+  "instruments": [
+    {
+      "actionOrder": ["close", "create"],
+      "actions": {
+        "close": {
+          "eventName": "note.closed",
+          "moves": [],
+          "steps": [],
+          "summary": "Close the note."
+        },
+        "create": {
+          "moves": [],
+          "steps": [],
+          "summary": "File the note."
+        }
+      },
+      "fields": {
+        "reference": {
+          "type": "string"
+        }
+      },
+      "id": "note",
+      "idPrefix": "note",
+      "lifecycle": {
+        "initial": "open",
+        "states": ["open", "closed"],
+        "transitions": {
+          "close": {
+            "from": ["open"],
+            "to": "closed"
+          }
+        }
+      },
+      "required": ["reference"],
+      "summary": "A note a tenant files and later closes.",
+      "title": "Note"
+    }
+  ],
+  "product": "minimal",
+  "subjects": [],
+  "title": "Minimal",
+  "udl": 1,
+  "version": 2
+}

package/conformance/evolution/product-identity.expected.json

@@ -0,0 +1,10 @@
+{
+  "issues": [
+    {
+      "code": "UDL7001",
+      "path": "$.product"
+    }
+  ],
+  "summary": "Evolution refusal for product id changed from minimal to renamed.",
+  "verdict": "invalid"
+}