domaintrail 0.4.0 → 0.6.0

package/CHANGELOG.ja.md

@@ -0,0 +1,303 @@
+# 変更履歴
+
+[English](CHANGELOG.md)
+
+domaintrail の各バージョンの変更点です。形式は [Keep a Changelog](https://keepachangelog.com/ja/) に、バージョン番号は
+[セマンティック バージョニング](https://semver.org/lang/ja/) に従います（1.0.0 より前は、マイナーバージョンでもモデルやコードに
+影響する変更があります）。
+
+**domaintrail を更新したら**、更新前から更新後までの各バージョンの **アップグレード手順**を古い順に読み、その手順に
+従ってください。このファイルはパッケージに含まれています: `node_modules/domaintrail/CHANGELOG.ja.md`（英語版は
+`CHANGELOG.md`）。
+
+## [0.6.0] - 2026-10-28
+
+### 追加
+
+- **Live View を git のリビジョンと比較**（`docs/live-view.md`）: ヘッダーの 比較対象 メニュー、または変更ペインの見出しから、
+  追加・変更・削除を何と比べて表示するかを選べます — 前回の保存（既定）か、git のリビジョン（ブランチ、タグ、最近のコミット、
+  または入力した任意のリビジョン）です。`dt view --base <ref>` で最初から指定して起動できます。図はノードのフィールドに、
+  インスペクターは 構造・状態遷移・振る舞い タブの行に印を付けます（追加、変更、削除は取り消し線、変更されたものは変更前の値も
+  表示）。
+- **Getting started** を英語と日本語で追加しました（`docs/getting-started.md`、`docs/getting-started.ja.md`）。README は
+  それを中心に再構成しました。
+- 変更履歴をパッケージに含めました（`node_modules/domaintrail/CHANGELOG.md`、`CHANGELOG.ja.md`）。`dt guide` は、更新後に
+  そのアップグレード手順に従うようエージェントに伝えます。
+
+## [0.5.0] - 2026-10-24
+
+### 追加
+
+- **ポリシー**（`dt guide reactions`、ADR 0022）: `policy P when Event -> Aggregate.command` — イベントが起きたら、
+  ポリシーを宣言したコンテキスト自身のコマンドがいずれ実行される、という反応を書けます。M023 がイベント・集約・コマンドを
+  検査し、同じ反応の重複を警告します。ポリシーごとに、イベントからコマンドの入力（`<Command><Aggregate>Input`）を作る
+  ハンドラの型が生成されます。`generate.ts.policies: "required"`（既定は `"optional"`、`generate.ts.contexts` で
+  コンテキストごとにも指定可）にすると `<Context>PolicyHandlers` が生成され、契約テストがそれを受け取り、どのイベントも
+  コマンドが受け付ける入力になることを検査します。コンテキストマップはポリシーをイベントによる依存として数えます。
+- **検証済み型**（`dt guide verified`、ADR 0023）: `verified X of T for C? errors E` — 集約の外で行った検査（他の誰も
+  使っていないメールアドレスなど）の証拠です。作れるのは利用者が書く非同期ファクトリ `Make<Name>` だけで、コマンドは
+  それを引数として受け取ります。M024 は検証済み型をコマンドの引数に限ります。
+- **ペイロードの名前**（ADR 0021）: イベントやエラーのフィールドが、名前の違う値（引数、そのフィールド、コマンド前後の
+  集約のフィールド）から値を取っていそうなときに M022 が警告します。
+- **Zed 拡張**（`editors/zed`）と **tree-sitter 文法**（`tree-sitter-domaintrail`）: Zed でのハイライト、アウトライン、
+  `dt lsp`。tree-sitter を使う他のエディタ向けの文法（`dt guide editors`）。
+- **キャストを防ぐ lint**（`dt guide lint`）: どのドメイン型も `as` を使わずに作る方法と、oxlint または
+  typescript-eslint で `no-unsafe-type-assertion` を有効にする方法。oxlint / ESLint の設定がこのルールに触れていないとき、
+  `dt generate ts` がヒントを表示します（`--format json` では `hints`）。`"lintHint": false` で止められます。ID、
+  ドメインプリミティブ、検証済み型の JSDoc に、それぞれの作り方を書きました。
+- 生成されるランタイムに `parseDecimal(text)`: `Decimal` を作る唯一の場所です。
+- `dt guide policies`: 変わりうる方針（ポリシー）に依存するルールの書き方。
+- `examples/shop` を完全なプロジェクトにしました: すべての集約の実装、アプリケーション層（ユースケース、リポジトリ、
+  イベントストア、ポリシー、検証済み型のファクトリ）、テスト、デモ。README で説明しています。
+- 言語サーバー: コマンドの名前を変更（リネーム）できます。
+
+### 変更
+
+- ワークスペースのファイルを集めるすべてのコマンド（`check`、`generate`、`view`、`fmt`、`show`、`lsp`）は、
+  `.gitignore`（ルート、そのサブディレクトリ、リポジトリの最上位までの親ディレクトリのもの）と `.git/info/exclude` が
+  無視するファイルを読み飛ばします。`"respectGitignore": false` で無効にできます。コマンドラインで指定したファイルは
+  読み飛ばしません。
+- 言語サーバーが設定ファイルを見つけられないとき、設定を持つディレクトリの下で最初に開いた `.dt` ファイルによって、
+  その設定がワークスペースになります。
+
+### 修正
+
+- `Int` や `Decimal` を基にするドメインプリミティブを、`count()` や `length()` が計算する数と比較できるようにしました。
+
+### アップグレード手順
+
+1. モデルの `.dt` ファイルが `.gitignore` で無視されるディレクトリにあると、ワークスペースに含まれなくなります。
+   ファイルを移すか、`domaintrail.jsonc` に `"respectGitignore": false` を書いてください。`dt check` を実行し、
+   ファイル数が以前と同じか確かめます。
+2. M011: `parseDecimal` はランタイムの名前になりました。その名前の要素がモデルにあれば名前を変えてください。
+3. `dt generate ts` を実行します。lint のヒントが出たら `dt guide lint` に従い（または `"lintHint": false`）、
+   コード中のドメイン型へのキャストを `make<Name>` / `parseDecimal` に置き換えます。
+4. 新しい警告が出ることがあります: M022（イベントやエラーのフィールドを値の出どころに合わせて名前を変えるか、
+   出どころの名前をフィールドに合わせる）。警告では `dt check` は失敗しません。
+
+## [0.4.0] - 2026-10-24
+
+### 追加
+
+- コマンドの **`requires`**（`dt guide requires`、ADR 0017）: `requires name { expr } else Error` — 式が成り立つときだけ
+  コマンドを受け付け、成り立たなければそのエラーを返します（M019）。
+- コマンドの **`changes`**（`dt guide changes`、ADR 0019）: コマンドが変更してよいフィールド（M021）。
+- **多重度と `when` を持つ `emits`**（`dt guide events`、ADR 0018）: `X?`、`X[0..*]`、`X[1..*]`、`X[n..m]`、
+  一部の結果でだけ発生するイベントには `X when Draft ->` / `X when -> Completed`。
+- 式の **`unique` と `contains`**、および式を持たず言葉だけで書く不変条件（M018、ADR 0016）。
+- **決定（decision）と `decide`**（`dt guide decide`）: 各コマンドは `<Command><Aggregate>Decision` として実装します —
+  遷移元の状態ごとに、結果の `set` と `events` を返し、ランタイムの `decide(<Aggregate>Shape, decision)` が集約を
+  作ります。足りないイベント、余分なイベント、変更してはいけないフィールドを、コンパイラが名前を挙げて報告します。
+- **生成される検査とコンストラクタ**（ADR 0020）: 不変条件と要件の式から `check<Name>` /
+  `check<Command><Aggregate>Requires`、すべての ID とドメインプリミティブに `make<Name>`。
+- **生成される契約テスト**（`dt guide tests`）: `generate.ts.tests`（`runner`: `bun`、`vitest`、`jest`、`node`。
+  `out`）を指定すると、`dt generate ts` がコンテキストごとに fast-check のスイートを書き出し、コンストラクタ、要件、
+  各コマンド後の不変条件、イベント、純粋性を検査します。プロジェクトに `fast-check` が必要です。
+- **`dt fmt`**: `.dt` ファイルを、コメントを保ったまま一つの正規のレイアウトに整形します（CI 向けに `--check`）。
+  LSP の整形にも使われます。
+- **`dt show <name>`**: 要素・状態・コマンド・コンテキストを一つ、解決した形で、使っている側とともに表示します
+  （`--format json`）。
+- **`dt lsp`**: `dt check` の診断、定義へ移動、参照、ホバー、アウトライン、補完、リネームを提供する言語サーバー。
+- 診断の**ヒント**（「もしかして …」や、何を変えればよいか）と、`check` と `generate ts` の `--format json`
+  （スキーマは `schema/diagnostics.schema.json`）。
+- 生成されるすべての宣言に、DSL の位置を指す `@see <file>:<line>`。
+- どのコマンドも扱うコード向けのランタイムヘルパー `outcome(value)`（`{ to, aggregate, events }`）と
+  `eventList(events)`。
+- M020（警告）: 集約の ID 型の引数を持たない `create command`。
+
+### 変更
+
+- **`emits X` は、コマンドが成功したときにちょうど 1 つの `X`** を意味します（以前は「発生させうる」）。エラーのときは
+  何も発生させません。
+- **コマンドの結果は結果（遷移先）ごとのキーを持つ形**になりました: タプル `[aggregate, events[]]` の代わりに
+  `{ Confirmed: { aggregate, events: { OrderConfirmed } } }`。イベントは名前をキーとし、順序を持ちません。イベントの
+  ないコマンドは `NoEvents` です。
+- コマンドは純粋関数です: ID と時刻は引数として受け取ります（ファクトリは自分の ID を受け取ります）。
+- `ok` は契約からだけ型を推論するので、リテラル中の余分なイベントが報告されます。
+- `changes` のないコマンドは、共通フィールドを変更しません。
+- 生成されるモジュールが値（`<Aggregate>Shape`）をエクスポートします: `import type` ではなく値として import します。
+- `dt guide` はクイックリファレンスとトピック一覧を表示します。`dt guide <topic>` で 1 節、`dt guide <rule>` で 1 ルール、
+  `dt guide --all` でガイド全体。
+- `[0..1]` は `?` と、`[1..1]` は多重度なしと同じ意味になりました。
+- Live View は各イベントの多重度と `when`、`requires` と `changes`、問題ペインのヒントを表示します。
+
+### 削除
+
+- `byState` と `<Command><Aggregate>ByState` 型（0.3.0）: すべてのコマンドを `decide` で実装します。
+
+### アップグレード手順
+
+まずモデルを変え、次に生成し、最後にコードを直します。規則の詳細は `dt guide events`、`dt guide changes`、
+`dt guide decide` にあります。
+
+1. **イベント。** `emits X` は、成功するたびにちょうど 1 つの `X` になりました。`emits` の各項目について、そのイベントが
+   いつ発生するかを決めて、そのとおりに書きます:
+
+   ```dt
+   // 変更前（0.3.0）: 「発生させうる」
+   command changeNote(note: String?)
+     Draft -> Draft, Confirmed -> Confirmed
+     emits NoteChanged
+   command cancel(reason: CancelReason)
+     Draft | Confirmed -> Cancelled
+     emits OrderCancelled, RefundRequested
+   // 変更後（0.4.0）
+   command changeNote(note: String?)
+     Draft -> Draft, Confirmed -> Confirmed
+     changes note
+     emits NoteChanged?                    // 高々 1 つ。いくつでもなら X[0..*]
+   command cancel(reason: CancelReason)
+     Draft | Confirmed -> Cancelled
+     emits OrderCancelled,
+           RefundRequested when Confirmed -> // Confirmed からのときだけ
+   ```
+
+2. **ファクトリは ID を、コマンドは時刻を受け取ります。** 各 `create command` に集約の ID 型の引数を加え（加えるまで
+   M020 が警告します）、実装が時計を読んでいたところには `Timestamp` の引数を加えます:
+
+   ```dt
+   create command place(customer: CustomerId) -> Draft            // 変更前
+   create command place(id: OrderId, customer: CustomerId) -> Draft // 変更後
+   ```
+
+   ID は呼び出し側が作って（`make<Name>(crypto.randomUUID())`）渡します。
+3. **`changes`。** 遷移元と遷移先の状態に共通するフィールド（状態のない集約ではすべてのフィールド）を変更するコマンドに、
+   `changes f1, f2` を加えます。書かないと、生成される決定の型がそのフィールドの設定を許しません。
+4. **必要なら `requires`。** 何かを変える前にエラーを返す検査は `requires name { expr } else Error` にできます。生成される
+   `check<Command><Aggregate>Requires` と契約テストがそれを検査します。
+5. **予約された名前（M011）。** `decide`、`Decide`、`Shape`、`NoChanges`、`outcome`、`eventList`、`NoEvents`、
+   `Outcome`、`EventOf`、`sameOptional`、`sameList`、`distinct` はランタイムの名前に、`<Command><Aggregate>Decision`、
+   `<Aggregate>Shape` は生成される名前になりました: 衝突する要素の名前を変えます。`dt check` が 0 で終わるまで直します。
+6. **生成し直し、すべてのコマンドを `decide` で書き直します。** 結果の `set`（`changes` のフィールドと遷移先の状態で
+   新しく持つフィールド。ファクトリはすべてのフィールドを設定し、省略可能なものは `undefined`）と `events` を、遷移先の
+   状態をキーにして返します（状態のない集約では集約名がキー）。遷移元が一つでも、遷移元の状態ごとにハンドラを書きます。
+   ファクトリは一つの関数です:
+
+   ```ts
+   // 変更前（0.3.0）
+   import { byState, ok, type Sales } from '../generated/domain/index.js';
+   export const orderCommands: Sales.OrderCommands = {
+       place: (customer) => {
+           const order: Sales.DraftOrder = { state: 'Draft', id: crypto.randomUUID() as Sales.OrderId, items: [], customer };
+           return ok([order, [{ type: 'OrderPlaced', orderId: order.id }]] as const);
+       },
+       confirm: (order, at) =>
+           ok([{ ...order, state: 'Confirmed', confirmedAt: at }, [{ type: 'OrderConfirmed', orderId: order.id, confirmedAt: at }]] as const),
+       changeNote: byState<Sales.ChangeNoteOrderByState>({
+           Draft: (order, note) => ok([{ ...order, note }, []] as const),
+           Confirmed: (order, note) => ok([{ ...order, note }, []] as const),
+       }),
+   };
+
+   // 変更後（0.4.0）
+   import { Sales, decide, ok } from '../generated/domain/index.js';
+   export const orderCommands: Sales.OrderCommands = {
+       place: decide<Sales.PlaceOrderDecision>(Sales.OrderShape, (id, customer) =>
+           ok({ Draft: { set: { id, items: [], customer, note: undefined }, events: { OrderPlaced: { type: 'OrderPlaced', orderId: id } } } }),
+       ),
+       confirm: decide<Sales.ConfirmOrderDecision>(Sales.OrderShape, {
+           Draft: (order, at) =>
+               ok({ Confirmed: { set: { confirmedAt: at }, events: { OrderConfirmed: { type: 'OrderConfirmed', orderId: order.id, confirmedAt: at } } } }),
+       }),
+       changeNote: decide<Sales.ChangeNoteOrderDecision>(Sales.OrderShape, {
+           Draft: (order, note) => ok({ Draft: { set: { note }, events: {} } }), // `emits NoteChanged?` なら、備考が変わったときに渡す
+           Confirmed: (order, note) => ok({ Confirmed: { set: { note }, events: {} } }),
+       }),
+   };
+   ```
+
+7. **呼び出し側**はキー付きの結果を読みます: `result.value.Confirmed.aggregate` / `.events.OrderConfirmed`。どのコマンドも
+   扱うコードでは `outcome(result.value)` → `{ to, aggregate, events }` と `eventList(events)` を使います。
+8. 型検査します（`tsc --noEmit`）。契約と実装が食い違うとき — いつも発生させられるとは限らないイベント、変更が必要な
+   フィールド — は、実装ではなく DSL を変えます（`X?`、`changes`）。
+9. 必要なら契約テストを有効にし（`generate.ts.tests`、`dt guide tests`）、一度 `dt fmt` を実行します。
+
+## [0.3.0] - 2026-10-19
+
+### 追加
+
+- 遷移元の状態ごとのハンドラ: 遷移先が遷移元の状態によって決まるコマンドには `<Command><Aggregate>ByState` も生成され、
+  ランタイムの `byState({...})` で実装します（ADR 0015）。
+- 状態遷移図は遷移ごとに辺を描き、インスペクタは遷移ごとに行を表示します。
+
+### 変更
+
+- **コマンドは `from … to …` の代わりに遷移を並べます**（ADR 0014）: `Draft -> Confirmed`、
+  `Draft | Confirmed -> Cancelled`、`Draft -> Draft, Confirmed -> Confirmed`。ファクトリは遷移元のない遷移を一つ
+  持ちます（`-> Draft`）。一つの状態は、コマンドごとに一つの遷移の遷移元になります（M006）。`from` と `to` は
+  キーワードではなくなりました。
+- 遷移先が遷移元の状態によって決まるコマンドの生成される契約は、入力の状態についてジェネリックになり、`Draft` からは
+  `Draft`、`Confirmed` からは `Confirmed` が返ります。
+
+### 修正
+
+- `npm publish` が警告しないよう、パッケージの `bin` のパスの書き方を直しました。
+
+### アップグレード手順
+
+1. 各コマンドの `from … to …` を遷移に書き換えます:
+
+   ```dt
+   // 変更前（0.2.0）
+   create command place(customer: CustomerId) to Draft
+   command confirm(at: Timestamp) from Draft to Confirmed emits OrderConfirmed
+   command changeNote(note: String?) from Draft | Confirmed to Draft | Confirmed
+   // 変更後（0.3.0）
+   create command place(customer: CustomerId) -> Draft
+   command confirm(at: Timestamp) Draft -> Confirmed emits OrderConfirmed
+   command changeNote(note: String?) Draft -> Draft, Confirmed -> Confirmed // どの遷移元がどこへ行くかを書く
+   ```
+
+   どの遷移元からどの遷移先へも行けるなら、`from A | B to C | D` は `A | B -> C | D` になります。できるだけ正確な
+   遷移を書いてください。
+2. `dt check`、続いて `dt generate ts` を実行します。遷移先が遷移元の状態によって決まるコマンドは契約がジェネリックに
+   なります: 型アサーションの代わりに
+   `byState<Ctx.<Command><Aggregate>ByState>({ Draft: (…) => …, Confirmed: (…) => … })` で実装します。
+
+## [0.2.0] - 2026-10-18
+
+### 追加
+
+- **項目セット**（`dt guide field-sets`、ADR 0013）: `fields Name { ... }` で普通のフィールドの集まりを宣言し、集約・
+  エンティティ・イベントが `with A, B` でそれを持ちます（M016）。共有コンテキストにも置けます。要素が継承する
+  インターフェースが生成されます。
+- コンテキストごとに生成される union: `DomainEvent`（すべてのイベント）、`Aggregate`（すべての集約）、
+  `<Aggregate>Event`（集約のコマンドが発生させるイベント）。
+- M017（警告）: 集約のコマンドが発生させるイベントに、その集約の ID 型のフィールドがない。
+- ガイドで、ドメインのフィールドと技術的なフィールドの違いと、技術的なメタデータをエンベロープで付ける方法を説明しました。
+- Live View: カタログのフィルタ（テキスト、種類、コンテキスト）。エクスプローラ、カタログ、インスペクタ、構造図での
+  項目セットの表示。
+
+### 変更
+
+- Live View: カタログのカードは、バッジを見出しの上に、ラベルを名前の上に置きます。カタログのセクションへのリンクは
+  なくなりました（フィルタでセクションを探せます）。
+
+### アップグレード手順
+
+1. M011: `DomainEvent`、`Aggregate`、`<Aggregate>Event` は生成される名前になりました。これらと名前が衝突する
+   コンテキストの要素の名前を変え、`dt check` を実行します。
+2. `fields` と `with` はキーワードになりましたが、フィールド名や引数名としては引き続き使えます。
+3. 新しい M017 の警告には、集約の ID をそのイベントに加えて対応します（`orderId: OrderId`）。
+
+## [0.1.0] - 2026-10-18
+
+最初に公開したバージョンです。
+
+### 追加
+
+- DomainTrail DSL: 境界づけられたコンテキスト、状態を持つ集約、エンティティ、値オブジェクト、ID、ドメインプリミティブ、
+  列挙型、union、コマンド（`from … to …`）、イベント（`persistent`）、エラー、共有コンテキスト、ラベルと説明、
+  不変条件の式。ルール M001〜M015 と L001〜L003。
+- `dt` CLI（`domaintrail` としてもインストールされます。Node.js 22.12 以降）: `dt check`、`dt generate ts`
+  （TypeScript の型とコマンドの契約。`generate.ts.contexts` でコンテキストごとの出力先）、`dt view`、`dt guide`。
+- `domaintrail.jsonc`（`sources`、`generate.ts`、`view`）と、その JSON Schema `schema/domaintrail.schema.json`。
+- Live View（`dt view`）: コンテキストマップ、構造図（3 段階）、カタログ、状態遷移図、ソースを表示するインスペクタ、問題と
+  変更の一覧。保存のたびに更新されます。日本語と英語、ライトとダーク。
+
+[0.6.0]: https://github.com/hisamekms/domaintrail/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/hisamekms/domaintrail/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/hisamekms/domaintrail/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/hisamekms/domaintrail/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/hisamekms/domaintrail/compare/b9f56885cde82f404bbf6b558f43b8ecb6254dfe...v0.2.0
+[0.1.0]: https://github.com/hisamekms/domaintrail/tree/b9f56885cde82f404bbf6b558f43b8ecb6254dfe

package/CHANGELOG.md

@@ -0,0 +1,304 @@
+# Changelog
+
+[日本語](CHANGELOG.ja.md)
+
+What changed in each version of domaintrail. The format follows [Keep a Changelog](https://keepachangelog.com/), and
+the versions follow [Semantic Versioning](https://semver.org/) (before 1.0.0, a minor version may break models and
+code).
+
+**After upgrading domaintrail**, read the **Upgrading** section of every version between the one you had and the new
+one, oldest first, and follow its steps. This file is in the package: `node_modules/domaintrail/CHANGELOG.md`.
+
+## [0.6.0] - 2026-10-28
+
+### Added
+
+- **Comparing the Live View with a git revision** (`docs/live-view.md`): the 比較対象 menu in the header, or the heading
+  of the changes pane, picks what additions, changes and removals are shown against — the previous save (the default)
+  or a git revision: a branch, a tag, one of the latest commits or any revision typed in. `dt view --base <ref>` starts
+  with one. The diagrams mark the fields of their nodes, and the inspector marks the rows of its 構造, 状態遷移 and 振る舞い
+  tabs (added, changed, removed struck through, with the former value of a changed one).
+- **Getting started** in English and Japanese (`docs/getting-started.md`, `docs/getting-started.ja.md`), with the
+  README reorganized around it.
+- The changelogs are in the package (`node_modules/domaintrail/CHANGELOG.md`, `CHANGELOG.ja.md`), and `dt guide` tells
+  agents to follow their Upgrading steps after an upgrade.
+
+## [0.5.0] - 2026-10-24
+
+### Added
+
+- **Policies** (`dt guide reactions`, ADR 0022): `policy P when Event -> Aggregate.command` — when the event happens,
+  the command of the policy's own context is eventually run. M023 checks the event, the aggregate and the command, and
+  warns about the same reaction twice. Each policy generates the type of its handler, from the event to the command's
+  input (`<Command><Aggregate>Input`). With `generate.ts.policies: "required"` (default `"optional"`, also per context
+  in `generate.ts.contexts`), `<Context>PolicyHandlers` is generated and the contract tests take it and check that every
+  event resolves to an input the command accepts. The context map counts a policy as an event dependency.
+- **Verified types** (`dt guide verified`, ADR 0023): `verified X of T for C? errors E` — the evidence of a check made
+  outside the aggregate (an email address nobody else uses). Only its async factory, `Make<Name>`, written by you, makes
+  it; commands take it as a parameter. M024 keeps verified types to command parameters.
+- **Payload names** (ADR 0021): M022 warns when an event or error field likely takes its value from a differently
+  named source (a parameter, one of its fields, or a field of the aggregate before / after the command).
+- **Zed extension** (`editors/zed`) and a **tree-sitter grammar** (`tree-sitter-domaintrail`): highlighting, outline and
+  `dt lsp` in Zed; the grammar for other tree-sitter editors (`dt guide editors`).
+- **Linting against casts** (`dt guide lint`): how to make every domain type without `as`, and how to enable
+  `no-unsafe-type-assertion` with oxlint or typescript-eslint. `dt generate ts` prints a hint (`hints` in
+  `--format json`) when no oxlint or ESLint config mentions the rule; `"lintHint": false` turns it off. The JSDoc of
+  IDs, domain primitives and verified types names the way to make them.
+- `parseDecimal(text)` in the generated runtime: the one place that makes a `Decimal`.
+- `dt guide policies`: how to write rules that depend on a changeable policy.
+- `examples/shop` is a complete project: every aggregate implemented, an application layer (use cases, repositories, an
+  event store, policies, a verified type's factory), tests and a demo, described in its README.
+- Language server: commands can be renamed.
+
+### Changed
+
+- Every command that collects the workspace's files (`check`, `generate`, `view`, `fmt`, `show`, `lsp`) skips what the
+  `.gitignore` files (of the root, its subdirectories and its parents up to the repository's top) and
+  `.git/info/exclude` ignore. `"respectGitignore": false` turns it off; files named on the command line are never
+  skipped.
+- When the language server finds no config file, the first `.dt` file opened below a config makes that config the
+  workspace.
+
+### Fixed
+
+- A domain primitive over `Int` or `Decimal` can be compared with the numbers `count()` and `length()` compute.
+
+### Upgrading
+
+1. If `.dt` files of your model are in a directory that `.gitignore` ignores, they are no longer part of the
+   workspace. Move them, or set `"respectGitignore": false` in `domaintrail.jsonc`. Run `dt check` and compare the
+   file count with before.
+2. M011: `parseDecimal` is now a runtime name. Rename an element of your model with that name.
+3. Run `dt generate ts`. If it prints the lint hint, follow `dt guide lint` (or set `"lintHint": false`), and replace
+   casts to domain types in your code with `make<Name>` / `parseDecimal`.
+4. New warnings may appear: M022 (rename the event or error field after its source, or the source after the field).
+   Warnings do not fail `dt check`.
+
+## [0.4.0] - 2026-10-24
+
+### Added
+
+- **`requires`** on commands (`dt guide requires`, ADR 0017): `requires name { expr } else Error` — the command is
+  accepted only if the expression holds, otherwise it returns the error (M019).
+- **`changes`** on commands (`dt guide changes`, ADR 0019): the fields a command may change (M021).
+- **`emits` with multiplicities and `when`** (`dt guide events`, ADR 0018): `X?`, `X[0..*]`, `X[1..*]`, `X[n..m]`, and
+  `X when Draft ->` / `X when -> Completed` for events of some outcomes only.
+- **`unique` and `contains`** in expressions, and invariants without an expression, stated in words only (M018; ADR
+  0016).
+- **Decisions and `decide`** (`dt guide decide`): each command is implemented as a `<Command><Aggregate>Decision` — per
+  source state, the outcome's `set` and `events` — and `decide(<Aggregate>Shape, decision)` from the runtime makes the
+  aggregate. The compiler names a missing event, an extra event, and a field the command may not set.
+- **Generated checks and constructors** (ADR 0020): `check<Name>` / `check<Command><Aggregate>Requires` from the
+  invariant and requirement expressions, and `make<Name>` for every ID and domain primitive.
+- **Generated contract tests** (`dt guide tests`): with `generate.ts.tests` (`runner`: `bun`, `vitest`, `jest` or
+  `node`; `out`), `dt generate ts` writes fast-check suites per context that check the constructors, the requirements,
+  the invariants after each command, the events and purity. They need `fast-check` in your project.
+- **`dt fmt`**: one canonical layout for `.dt` files, keeping every comment (`--check` for CI); also LSP formatting.
+- **`dt show <name>`**: one element, state, command or context resolved, with who uses it (`--format json`).
+- **`dt lsp`**: a language server with the diagnostics of `dt check`, definition, references, hover, outline,
+  completion and rename.
+- **Hints** on diagnostics (did you mean …, and what to change), and `--format json` for `check` and `generate ts`
+  (schema in `schema/diagnostics.schema.json`).
+- `@see <file>:<line>` on every generated declaration, pointing back to the DSL.
+- Runtime helpers `outcome(value)` (`{ to, aggregate, events }`) and `eventList(events)` for code that handles any
+  command.
+- M020 (warning): a `create command` without a parameter of the aggregate's ID type.
+
+### Changed
+
+- **`emits X` means exactly one `X`** when the command succeeds (it meant "may emit"), and nothing on an error.
+- **Command results are keyed by outcome**: `{ Confirmed: { aggregate, events: { OrderConfirmed } } }` instead of the
+  tuple `[aggregate, events[]]`; events are keyed by name and have no order. A command without events has `NoEvents`.
+- Commands are pure: IDs and times come in as parameters (factories take their ID).
+- `ok` infers its type from the contract only, so an extra event in the literal is reported.
+- Without `changes`, a command changes no common field.
+- Generated modules export values (`<Aggregate>Shape`): import them as values, not with `import type`.
+- `dt guide` prints a quick reference and the list of topics; `dt guide <topic>` one section, `dt guide <rule>` one
+  rule, `dt guide --all` the whole guide.
+- `[0..1]` is the same as `?` and `[1..1]` the same as no multiplicity.
+- The Live View shows the multiplicity and `when` of each event, `requires` and `changes`, and hints in the problems
+  pane.
+
+### Removed
+
+- `byState` and the `<Command><Aggregate>ByState` types (0.3.0): every command is implemented with `decide`.
+
+### Upgrading
+
+Change the model first, then generate, then the code. The full rules are in `dt guide events`, `dt guide changes` and
+`dt guide decide`.
+
+1. **Events.** `emits X` is now exactly one `X` on every success. For each `emits` entry, decide when the event
+   happens and write it so:
+
+   ```dt
+   // before (0.3.0): "may emit"
+   command changeNote(note: String?)
+     Draft -> Draft, Confirmed -> Confirmed
+     emits NoteChanged
+   command cancel(reason: CancelReason)
+     Draft | Confirmed -> Cancelled
+     emits OrderCancelled, RefundRequested
+   // after (0.4.0)
+   command changeNote(note: String?)
+     Draft -> Draft, Confirmed -> Confirmed
+     changes note
+     emits NoteChanged?                    // at most one; X[0..*] for any number
+   command cancel(reason: CancelReason)
+     Draft | Confirmed -> Cancelled
+     emits OrderCancelled,
+           RefundRequested when Confirmed -> // only from Confirmed
+   ```
+
+2. **Factories take their ID, commands take the time.** Add a parameter of the aggregate's ID type to each
+   `create command` (M020 warns until you do), and a `Timestamp` parameter where the implementation read the clock:
+
+   ```dt
+   create command place(customer: CustomerId) -> Draft            // before
+   create command place(id: OrderId, customer: CustomerId) -> Draft // after
+   ```
+
+   Callers make the ID (`make<Name>(crypto.randomUUID())`) and pass it in.
+3. **`changes`.** Add `changes f1, f2` to every command that changes a field common to its source and target states
+   (or any field of an aggregate without states). Without it, the generated decision does not let the command set the
+   field.
+4. **Optionally `requires`.** A check that returns an error before anything changes can become
+   `requires name { expr } else Error`; the generated `check<Command><Aggregate>Requires` and the contract tests then
+   check it.
+5. **Reserved names (M011).** `decide`, `Decide`, `Shape`, `NoChanges`, `outcome`, `eventList`, `NoEvents`, `Outcome`,
+   `EventOf`, `sameOptional`, `sameList` and `distinct` are runtime names, and `<Command><Aggregate>Decision`,
+   `<Aggregate>Shape` are generated: rename elements whose names clash. Run `dt check` until it exits 0.
+6. **Regenerate and rewrite every command with `decide`.** Return the outcome's `set` (the fields in `changes` and the
+   target state's new fields; a factory sets every field, optional ones as `undefined`) and its `events`, keyed by the
+   target state (by the aggregate's name without states). One handler per source state, also with one source; a
+   factory is a single function:
+
+   ```ts
+   // before (0.3.0)
+   import { byState, ok, type Sales } from '../generated/domain/index.js';
+   export const orderCommands: Sales.OrderCommands = {
+       place: (customer) => {
+           const order: Sales.DraftOrder = { state: 'Draft', id: crypto.randomUUID() as Sales.OrderId, items: [], customer };
+           return ok([order, [{ type: 'OrderPlaced', orderId: order.id }]] as const);
+       },
+       confirm: (order, at) =>
+           ok([{ ...order, state: 'Confirmed', confirmedAt: at }, [{ type: 'OrderConfirmed', orderId: order.id, confirmedAt: at }]] as const),
+       changeNote: byState<Sales.ChangeNoteOrderByState>({
+           Draft: (order, note) => ok([{ ...order, note }, []] as const),
+           Confirmed: (order, note) => ok([{ ...order, note }, []] as const),
+       }),
+   };
+
+   // after (0.4.0)
+   import { Sales, decide, ok } from '../generated/domain/index.js';
+   export const orderCommands: Sales.OrderCommands = {
+       place: decide<Sales.PlaceOrderDecision>(Sales.OrderShape, (id, customer) =>
+           ok({ Draft: { set: { id, items: [], customer, note: undefined }, events: { OrderPlaced: { type: 'OrderPlaced', orderId: id } } } }),
+       ),
+       confirm: decide<Sales.ConfirmOrderDecision>(Sales.OrderShape, {
+           Draft: (order, at) =>
+               ok({ Confirmed: { set: { confirmedAt: at }, events: { OrderConfirmed: { type: 'OrderConfirmed', orderId: order.id, confirmedAt: at } } } }),
+       }),
+       changeNote: decide<Sales.ChangeNoteOrderDecision>(Sales.OrderShape, {
+           Draft: (order, note) => ok({ Draft: { set: { note }, events: {} } }), // with `emits NoteChanged?`, give it when the note changes
+           Confirmed: (order, note) => ok({ Confirmed: { set: { note }, events: {} } }),
+       }),
+   };
+   ```
+
+7. **Callers** read the keyed result: `result.value.Confirmed.aggregate` / `.events.OrderConfirmed`, or, in code that
+   handles any command, `outcome(result.value)` → `{ to, aggregate, events }` and `eventList(events)`.
+8. Type-check (`tsc --noEmit`). When the contract and the implementation disagree — an event that cannot always be
+   emitted, a field that must change — change the DSL (`X?`, `changes`), not the implementation.
+9. Optionally enable the contract tests (`generate.ts.tests`, `dt guide tests`) and run `dt fmt` once.
+
+## [0.3.0] - 2026-10-19
+
+### Added
+
+- Handlers per source state: a command whose targets depend on its source state also gets
+  `<Command><Aggregate>ByState`, implemented with `byState({...})` from the runtime (ADR 0015).
+- The State View draws one edge per transition, and the inspector shows a row per transition.
+
+### Changed
+
+- **Commands list their transitions** instead of `from … to …` (ADR 0014): `Draft -> Confirmed`,
+  `Draft | Confirmed -> Cancelled`, `Draft -> Draft, Confirmed -> Confirmed`; a factory has one transition without
+  sources, `-> Draft`. A state is the source of one transition per command (M006). `from` and `to` are no longer
+  keywords.
+- The generated contract of a command whose targets depend on its source state is generic over the input state, so a
+  `Draft` gives a `Draft` and a `Confirmed` a `Confirmed`.
+
+### Fixed
+
+- The `bin` paths of the package are written so that `npm publish` does not warn about them.
+
+### Upgrading
+
+1. Rewrite each command's `from … to …` as transitions:
+
+   ```dt
+   // before (0.2.0)
+   create command place(customer: CustomerId) to Draft
+   command confirm(at: Timestamp) from Draft to Confirmed emits OrderConfirmed
+   command changeNote(note: String?) from Draft | Confirmed to Draft | Confirmed
+   // after (0.3.0)
+   create command place(customer: CustomerId) -> Draft
+   command confirm(at: Timestamp) Draft -> Confirmed emits OrderConfirmed
+   command changeNote(note: String?) Draft -> Draft, Confirmed -> Confirmed // say which source goes where
+   ```
+
+   `from A | B to C | D` becomes `A | B -> C | D` when every source may end in every target; prefer the precise
+   transitions.
+2. Run `dt check`, then `dt generate ts`. A command whose targets depend on its source state has a generic contract:
+   implement it with `byState<Ctx.<Command><Aggregate>ByState>({ Draft: (…) => …, Confirmed: (…) => … })` instead of
+   a type assertion.
+
+## [0.2.0] - 2026-10-18
+
+### Added
+
+- **Field sets** (`dt guide field-sets`, ADR 0013): `fields Name { ... }` declares plain fields that aggregates,
+  entities and events take on with `with A, B` (M016). Shared contexts may hold them. They generate an interface that
+  the elements extend.
+- Generated unions per context: `DomainEvent` (every event), `Aggregate` (every aggregate) and `<Aggregate>Event` (the
+  events an aggregate's commands emit).
+- M017 (warning): an event emitted by an aggregate's command has no field of that aggregate's ID type.
+- The guide explains domain vs technical fields, and attaching technical metadata with envelopes.
+- Live View: a filter bar in the catalog (text, kinds, contexts); field sets in the explorer, catalog, inspector and
+  structure diagram.
+
+### Changed
+
+- Live View: catalog cards put the badges above the heading and the label over the name; the catalog's section links
+  are gone (the filter finds a section).
+
+### Upgrading
+
+1. M011: `DomainEvent`, `Aggregate` and `<Aggregate>Event` are generated names now. Rename an element of a context
+   whose name clashes with them, then run `dt check`.
+2. `fields` and `with` are keywords; they are still allowed as field and parameter names.
+3. Address the new M017 warnings by adding the aggregate's ID to its events (`orderId: OrderId`).
+
+## [0.1.0] - 2026-10-18
+
+The first published version.
+
+### Added
+
+- The DomainTrail DSL: bounded contexts, aggregates with states, entities, value objects, IDs, domain primitives,
+  enums, unions, commands (`from … to …`), events (`persistent`), errors, shared contexts, labels and descriptions,
+  and invariant expressions; rules M001–M015 and L001–L003.
+- The `dt` CLI (also installed as `domaintrail`), on Node.js 22.12 or later: `dt check`, `dt generate ts` (TypeScript
+  types and command contracts, one output directory per context with `generate.ts.contexts`), `dt view` and
+  `dt guide`.
+- `domaintrail.jsonc` (`sources`, `generate.ts`, `view`) with its JSON Schema in `schema/domaintrail.schema.json`.
+- The Live View (`dt view`): the context map, the structure diagram (three levels), the catalog, the state diagram,
+  the inspector with the source, problems and changes, updated on every save; in Japanese or English, light or dark.
+
+[0.6.0]: https://github.com/hisamekms/domaintrail/compare/v0.5.0...v0.6.0
+[0.5.0]: https://github.com/hisamekms/domaintrail/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/hisamekms/domaintrail/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/hisamekms/domaintrail/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/hisamekms/domaintrail/compare/b9f56885cde82f404bbf6b558f43b8ecb6254dfe...v0.2.0
+[0.1.0]: https://github.com/hisamekms/domaintrail/tree/b9f56885cde82f404bbf6b558f43b8ecb6254dfe