ddduck 0.1.2 → 0.3.0

package/README.md

@@ -4,6 +4,8 @@ ddduck defines a small, machine-readable product-spec format. The framework keep
 schemas, validators, policies, and generators separate from each consumer product.
 
 Start with [the getting-started guide](docs/getting-started.md) for a working first product.
+For an unsettled product question or a proposed change, use the optional
+[definition-to-planning workflow](docs/definition-workflow.md) and reuse your existing brief.
 Then use [the model guide](docs/model.md), [the model reference](docs/model-reference.md),
 [the CLI reference](docs/cli.md), and [the architecture guide](docs/architecture.md) as needed.
 
@@ -76,8 +78,8 @@ ddduck init ddd --id model:<product-id>
 `--root <path>` is always the explicit override; without it, ddduck resolves the enclosing
 product root, then `.ddduck/config.json`, then a unique repository candidate (see
 [the CLI reference](docs/cli.md#product-root-resolution) for the full order, including the
-example-candidate fallback), and fails with a diagnostic when the choice is ambiguous. The mutation surface is deliberately narrow — `check`,
-`generate`, and the `create`/`move`/`split`/`retire` Guarantee lifecycle commands — and every
+example-candidate fallback), and fails with a diagnostic when the choice is ambiguous. The mutation surface is deliberately narrow —
+`generate`, domain/concept/use-case creation, and the `create`/`move`/`split`/`retire` Guarantee lifecycle commands — and every
 successful source mutation regenerates the derived views. The canonical resolution rules and
 command contracts live in [the CLI reference](docs/cli.md#product-root-resolution).
 
@@ -89,11 +91,16 @@ safety net.
 Install the evidence-backed model maintenance skill in a consumer repository:
 
 ```bash
-ddduck install skill update-ddduck-specs --repo <repository-root>
+ddduck install skill --repo <repository-root>
 ```
 
-`--repo` defaults to the current directory. See [the CLI reference](docs/cli.md#install-an-agent-skill)
-for the installed layout, host invocation, and plan-only behavior.
+`--repo` defaults to the current directory. ddduck installs nothing itself: it prints the exact
+`npx --yes '--package=skills@^1.7.0' -- skills add <ddduck-package>/skills --skill '*' -y`
+command it will run, asks `[y/n]`, and
+delegates the installation to the [`skills`](https://www.npmjs.com/package/skills) CLI, which
+supports 79 agent hosts. Pass `--yes` to skip the confirmation in CI or when an agent runs the
+command. See [the CLI reference](docs/cli.md#install-an-agent-skill) for the delegated flags,
+exit statuses, host invocation, and plan-only behavior.
 
 ## Product queries
 

package/docs/cli.md

@@ -14,6 +14,25 @@ retry logic never has to string-match standard error; every other failure exits
 This package is published to npm as `ddduck`; install the CLI globally with `npm install -g ddduck`
 (see [the getting-started guide](getting-started.md#install-ddduck)).
 
+## `--version`
+
+```text
+ddduck --version [--json]
+ddduck -v [--json]
+```
+
+| Option   | Default | Meaning                                        |
+| -------- | ------- | ---------------------------------------------- |
+| `--json` | false   | Emit one JSON object instead of the text line. |
+
+`--version` (alias `-v`) prints the installed package name and version taken from the package's
+own `package.json`, as one text line — `ddduck <version>` — or, with `--json`, one object:
+`{"name":"ddduck","version":"<version>"}`. It resolves no product root and reads no product, so
+it is the cheapest way to confirm that a candidate executable really is ddduck and which version
+is installed. `ddduck --version --help` prints the flag's contract like every other command.
+Exit status: 0 on success or help; 1 on invalid input (an unknown option, for example). The
+retryable busy exit 2 cannot occur, because no product root is touched.
+
 ## Product root resolution
 
 Product-facing commands accept `--root <product-root>`. When `--root` is omitted, ddduck resolves
@@ -59,7 +78,7 @@ standard-error note that the repository default still selects that other root.
 ## Common behavior
 
 Product writes are `init`, `generate`, `create`, `move`, `split`, and `retire`; successful
-mutations regenerate all required views. `check` and every `query` are read-only. A successful
+mutations regenerate all required views. `check`, `diff`, and every `query` are read-only. A successful
 `check` writes nothing to standard output; when `--root` was omitted, it prints one standard-error
 note naming the validated root so an implicitly resolved (for example config-pinned) root is never
 validated invisibly. Successful product mutations print one concise result line, or one JSON result
@@ -129,6 +148,65 @@ ddduck generate [--root <product-root>] [--json]
 result identifies the root, canonical paths (none for generate), and generated paths. It exits
 nonzero without an intended product mutation if validation or contained-output checks fail.
 
+## `diff`
+
+```text
+ddduck diff --base <previous-product-root> [--root <product-root>] [--json]
+```
+
+Compare two independently valid versions of the same Model by stable node ID. `--base` is
+required and `--root` uses normal root resolution. Generated output may be absent or stale.
+The command does not apply historical retention validation first: removing a Guarantee must
+remain visible in the comparison even when a subsequent `check --base` rejects that removal.
+
+The text report shows IDs, field changes, and path relocations. `--json` emits one
+`ModelDiff` version `"1"` document conforming to `schemas/model-diff.schema.json`:
+
+- `before` and `after` contain `modelId` and canonical `sourceDigest`.
+- `added` and `removed` contain full records with their product-relative source paths.
+- `changed` contains field changes keyed by escaped JSON Pointer paths. `beforePresent` and
+  `afterPresent` distinguish absent fields from explicit null values.
+- `relocated` records path changes without treating the same ID as a new record.
+- `scope` is `canonical-yaml-only`; `excludedScopes` names decision content, evidence content,
+  delivery artifacts, and runtime.
+
+Object-key order, comments, and YAML formatting are not record differences. Array order is
+preserved, so a reordered list is reported. Raw canonical-file changes still affect digests.
+Neither the digests nor an empty comparison establish ADR/evidence freshness or semantic
+equivalence. Source reads are not atomic snapshots; run comparisons while neither root is
+being edited. Busy and interrupted roots are refused.
+
+Exit 0 means comparison completed, including when changes exist; it is not an approval.
+Exit 2 means busy, and exit 1 covers invalid or incompatible inputs. Use existing `impact`
+and `neighbors` queries on both roots to inspect changed/removed context, then review meaning
+and run historical retention checking separately.
+
+## Creating domains, concepts, and use cases
+
+```text
+ddduck create domain --id domain:<slug> --name <text> --purpose <text> [--root <product-root>] [--json]
+ddduck create concept --id concept:<slug> --owner domain:<slug> --name <text> --purpose <text> [--root <product-root>] [--json]
+ddduck create use-case --file <yaml-file> [--root <product-root>] [--json]
+```
+
+Domain creation writes the node and adds its ID to the Model's `domains` list. Concept creation
+writes the node and adds its ID to the owning Domain's `concepts` list. These forms require
+every displayed field; they take model identity from the selected product.
+
+Use-case creation reads a complete canonical `UseCase` YAML mapping. Its `model` must match
+the selected product and all Guarantee/interface references must already resolve. It writes
+the new node and adds its ID to the Model's `useCases` list without changing the input file.
+An empty prerequisite or outcome list is allowed; the tool does not invent obligations.
+
+All three forms derive the destination filename from the validated ID. Duplicate IDs,
+occupied canonical paths, unknown fields, invalid references, or validation/generation
+failures reject the operation without intended publication. Successful operations update
+the owning collection and generate all views through the existing staged mutation runner.
+There is no overwrite mode. Existing YAML comments and unrelated parent fields are retained.
+The result has `operation`, `root`, `affectedIds` (new node and parent), `canonicalPaths`, and
+`generatedPaths`; append `--json` for one JSON document. Publication has the filesystem
+interruption limitations described in the [architecture guide](architecture.md#staged-lifecycle-mutation).
+
 ## Guarantee mutations
 
 All mutation results identify the selected root, affected Guarantee IDs, canonical paths, and
@@ -227,26 +305,37 @@ The command does not recursively expand the perimeter.
 ## Install an agent skill
 
 ```text
-ddduck install skill update-ddduck-specs [--repo <repository-root>]
+ddduck install skill [--repo <repository-root>] [--yes]
 ```
 
-`--repo` defaults to the current directory. The installer chooses the least intrusive host
-topology from the repository's existing directories:
+`--repo` defaults to the current directory. ddduck installs nothing itself: it delegates to the
+[`skills`](https://www.npmjs.com/package/skills) CLI, which supports 79 agent hosts and owns the
+installed layout and its own state. The command prints the exact command it will run, on its own
+line, and then runs it in `--repo`:
 
 ```text
-no .agents/ or .claude/   -> .agents/skills/update-ddduck-specs/SKILL.md
-.agents/ only             -> .agents/skills/update-ddduck-specs/SKILL.md
-.claude/ only             -> .claude/skills/update-ddduck-specs/SKILL.md
-.agents/ and .claude/     -> .agents/skills/update-ddduck-specs/SKILL.md
-                             .claude/skills/update-ddduck-specs -> ../../.agents/skills/update-ddduck-specs
+npx --yes '--package=skills@^1.7.0' -- skills add <ddduck-package>/skills --skill '*' -y
 ```
 
-The installer writes `.ddduck/agent-skills.lock.json` with the selected canonical path, host
-adapters, package version, and installed `SKILL.md` SHA-256. It does not create a host directory
-for a host that is absent from the repository, except for the `.agents/` fallback when no host
-directory exists. On success it prints one result line naming the action (`created`, `upgraded`,
-or `no-op`), the repository, the canonical skill path, and the lock path. It does not accept
-`--json`.
+The bundled skills directory is resolved inside the installed ddduck package
+(`./node_modules/ddduck/skills` from a consumer repository, or the repository's own `skills/`
+when the repository under analysis is ddduck itself). `--skill '*'` installs every bundled skill,
+the absent `-g` keeps the install project-scoped, and `-y` answers the delegated CLI's own
+prompts, because the command it applies has already been shown and confirmed here. `skills`
+writes one canonical copy (by default `.agents/skills/<skill-name>/`) and symlinks it into the
+agent directories that exist in the project.
+
+`--package=` pins the delegated package so npx resolves it from the registry. Without it, npx
+resolves the bare name `skills` against `--repo`'s own `node_modules/.bin` first, so an unrelated
+binary under that generic name — a sibling package hoisted to a monorepo root, for example —
+would run instead of the CLI the printed command names. The `--` separator keeps npx from
+reading the command word as a second package specifier.
+
+Before running it, ddduck asks `[y/n]` on standard input. Only `y` or `Y` proceeds; any other
+answer — including an empty line and a closed standard input — aborts, installs nothing, and
+exits 1. `--yes` skips that confirmation and keeps the command usable in CI and by agents; the
+command is still printed. The delegated command's output streams through unchanged and its exit
+status is propagated. `--json` is not accepted.
 
 Invoke the skill from the relevant host:
 
@@ -256,5 +345,5 @@ Claude: /update-ddduck-specs
 ```
 
 The skill defaults to plan-only; changing a product model requires explicit apply authorization.
-Its workflow behavior is defined by the installed `SKILL.md` (and its packaged
-[canonical source](../skills/update-ddduck-specs/SKILL.md)).
+Its workflow behavior is defined by the installed skill bundle (see its packaged
+[canonical entrypoint](../skills/update-ddduck-specs/SKILL.md)).

package/docs/definition-workflow.md

@@ -0,0 +1,130 @@
+# From a product question to a planning brief
+
+Start with the question, not a YAML record. Reuse an existing proposal or design brief;
+the [optional change brief](templates/change-brief.md) is a checklist for missing context,
+not a required document. A short note can be enough.
+
+## Explore, decide, then model
+
+1. Identify the actor and problem with concrete success and refusal examples.
+2. Separate observed evidence from accepted intent and open questions. Record alternatives
+   and contradictory evidence with provenance.
+3. Make the semantic decision explicit. Record the decision and rationale in the brief;
+   create an ADR only for a consequential, durable choice that needs its own history.
+4. Update canonical YAML only where accepted meaning changed. Preserve stable IDs and use
+   lifecycle commands for Guarantee transitions. A partial update can encode independent
+   accepted obligations while an unresolved question stays in prose. Zero model change is
+   correct when the existing model suffices, the change is implementation-only, or no
+   decision has been reached.
+5. Validate structure and refresh derived views, then hand selected context to the planner
+   with delivery intent, scope, exclusions, dependencies, and acceptance examples.
+
+**Observed** means evidence was inspected, not endorsed. **Open** means undecided.
+**Accepted** means intended behavior, possibly not implemented. **Rejected** records an
+alternative and rationale. These are prose labels, not new schema fields or Guarantee
+statuses. A passing checker settles none of these semantic decisions.
+
+For example, an admin capability need not be a member role. Existing code that grants one
+from the other establishes observed behavior; whether that coupling is intended remains a
+decision. Likewise, delivering a relay directive does not establish that the recipient
+enacted it. Leave an unanswered question about who may authorize it open rather than
+inventing an authority boundary.
+
+## Model only what helps a decision
+
+| Kind         | Useful meaning                                                             | Counterexample to avoid                            |
+| ------------ | -------------------------------------------------------------------------- | -------------------------------------------------- |
+| Domain       | A distinct product responsibility                                          | A domain for each package or screen                |
+| Concept      | Vocabulary needed to reason about behavior                                 | A concept for every class, queue, or button        |
+| Guarantee    | An observable obligation or invariant                                      | “Best effort delivery” with no concrete commitment |
+| Use case     | An actor's goal and the obligations it requires, preserves, or establishes | An implementation task list                        |
+| Relationship | A connection worth reviewing, with its meaning stated                      | Treating every connection as a causal dependency   |
+
+Interfaces are optional. A useful behavioral model can have none. Empty prerequisite lists
+are not inherently wrong; add a reference when it expresses a real prerequisite, not to
+make the diagram look complete.
+
+For a small relay, introducing separate UI, transport, and receipt domains and
+concepts would obscure the one responsibility under discussion. Three cohesive obligations
+can distinguish authorization/refusal, the limit of delivery, and honest reporting. Do not
+split every clause: split when meaning, change, or verification is independent. Remove an
+extra Guarantee, domain, brief section, or review step when it answers no additional question.
+Consumer practice is inspiration, not proof that its artifact count or boundaries are right.
+
+The [relay walkthrough](https://github.com/diegomarino/ddduck/tree/main/examples/control-relay)
+is a fictional educational scenario. The
+[reminders scenario](https://github.com/diegomarino/ddduck/tree/main/examples/reminders)
+illustrates refusal. Neither specifies a real product or runs an application.
+
+## Author and review with existing tools
+
+After hand edits, `generate` validates the staged source and generated outputs before
+publishing derived views. It is the normal refresh action. Run operations serially against a root.
+
+```bash
+ddduck generate --root <root>
+ddduck check --root <root>
+```
+
+An optional `ddduck check --root <root> --source-only` diagnoses canonical edits before
+generation; `query spec` can inspect individual view freshness when needed.
+`check` is read-only and suitable for CI/final readback. Fresh generated views establish
+consistency with source, not product acceptance or runtime correctness.
+
+For each selected ID, compose the existing reads:
+
+```bash
+ddduck query impact --id <id> --root <root> --json
+ddduck query neighbors --id <id> --root <root> --json
+ddduck query node --id <relationship-id> --root <root> --json
+ddduck query context --id <id> --root <root> --json
+```
+
+Impact follows reverse owns/requires/preserves/establishes/uses/guarantees edges.
+Neighbors exposes direct incoming/outgoing edges, including explicit relationships. Read
+the relationship record for its type, description, and constraints when needed. These are
+review candidates requiring judgment; an empty result does not establish absence of risk.
+To select explicit relationships, filter both edge lists by `edge.kind === 'relationship'`
+and deduplicate by `edge.id`; a self-relationship appears in both lists. If the changed ID
+is itself a Relationship, query its record and inspect its `from` and `to` endpoints:
+neighbors matches endpoint IDs, not the relationship record's ID.
+There is no separate review query. Do not infer transitive effects from relationship names.
+Separate query calls are not an atomic snapshot: keep the source stable during review and
+re-read if it changes. A source digest identifies the read source only when it did not race
+a mutation; it does not make multiple reads transactionally consistent.
+
+Inspect before and after roots when something moves or disappears. In the fictional
+ownership fixture, the same Guarantee moves from Members to Reminders within the small
+reference corpus:
+review its owner, both domains' lists, wording, and use-case references without inventing a
+new ID. Read-only current-root queries alone cannot recover removed context. External feature
+references remain the consumer bridge's responsibility.
+
+The comparison command is:
+
+```text
+ddduck diff --base <root> [--root <root>] [--json]
+```
+
+Its scope is canonical YAML records by stable identity, not decision/evidence
+content, delivery artifacts, or runtime. Keep semantic review separate from structural
+comparison and historical retention checking.
+
+Use the implemented [domain, concept, and use-case creation commands](cli.md#creating-domains-concepts-and-use-cases)
+to create records and update their parent lists coherently. Use-case creation consumes a
+complete canonical YAML mapping; it does not invent obligations or decisions. See that
+reference for syntax and refusal behavior. Schema-guided hand edits remain useful for
+changes outside these helpers; update ownership/reference lists together before generation.
+
+## Hand off intent, not just a graph
+
+Select canonical context explicitly and link it from the receiving plan. Add why the work
+is needed, scope and non-goals, success/refusal examples, dependencies, exclusions, open
+decisions, and the next verification required. Reuse the exploration brief if it already
+answers those questions; do not maintain duplicate requirement prose or a second backlog.
+
+State evidence levels precisely: inspected implementation, declared evidence anchors,
+structural checks, tests actually executed, and observed runtime are different claims.
+An audit verdict is a declared assessment whose anchor integrity is checked; readiness
+roles and valid links do not prove behavioral coverage. Keep anchors inside the supported
+product root, and never create fake executable evidence or bridge documents to fill gaps.

package/docs/getting-started.md

@@ -1,6 +1,8 @@
 # Getting started
 
 This executable journey creates a product with one Domain, one Concept, and one Guarantee.
+For help deciding what belongs in that model, start with the
+[definition workflow](definition-workflow.md).
 
 ## Install ddduck
 
@@ -37,9 +39,9 @@ repository root, and without one writes it inside the new product root instead (
 
 ```mermaid
 flowchart LR
-  Source[Manual canonical YAML edit] --> SourceCheck[ddduck check --source-only]
-  SourceCheck -->|valid| Generate[ddduck generate]
-  SourceCheck -->|invalid| Diagnostic[Actionable diagnostic]
+  Create[ddduck create] --> FreshCheck[ddduck check]
+  Source[Manual canonical YAML edit] --> Generate[ddduck generate]
+  Generate -->|invalid source| Diagnostic[Actionable diagnostic]
   Generate --> FreshCheck[ddduck check]
   FreshCheck --> Docs[Generated Markdown is fresh]
   FreshCheck --> Graph[Generated graph is fresh]
@@ -48,54 +50,22 @@ flowchart LR
 ```bash
 ddduck init ddd --id model:library
 
-cat > ddd/model/domains/catalog.yaml <<'YAML'
-schemaVersion: "1"
-kind: Domain
-id: domain:catalog
-model: model:library
-name: Catalog
-purpose: Organize the library catalog.
-concepts:
-  - concept:book
-interfaces: []
-guarantees: []
-YAML
-
-cat > ddd/model/concepts/book.yaml <<'YAML'
-schemaVersion: "1"
-kind: Concept
-id: concept:book
-model: model:library
-ownerDomain: domain:catalog
-name: Book
-purpose: Identify a catalogued book.
-YAML
-
-cat > ddd/product.yaml <<'YAML'
-schemaVersion: "1"
-kind: Model
-id: model:library
-name: library
-purpose: Define the library product.
-domains:
-  - domain:catalog
-useCases: []
-decisions: []
-YAML
-
-ddduck check --root ddd --source-only
-ddduck generate --root ddd
-ddduck check --root ddd
+ddduck create domain --id domain:catalog --name Catalog \
+  --purpose "Organize the library catalog." --root ddd
+ddduck create concept --id concept:book --owner domain:catalog --name Book \
+  --purpose "Identify a catalogued book." --root ddd
 ddduck create guarantee --origin catalog --classification invariant \
   --owner domain:catalog --statement "A Book has a stable catalog identity." --root ddd
+ddduck check --root ddd
 ddduck query spec --root ddd --json
 ```
 
 Default `check` requires both valid canonical source and fresh generated views. After a manual
-source edit, use `check --source-only`, run `generate`, then use default `check`. Do not edit
-`generated/` by hand.
+source edit, `ddduck generate --root ddd` validates the source and refreshes the views;
+use `ddduck check --root ddd` for final readback or CI. To diagnose source without writing
+anything, run `ddduck check --root ddd --source-only`. Do not edit `generated/` by hand.
 
-The successful `create` allocates the first catalog invariant serial, adds it to the Domain, and
-refreshes all generated views. The final query emits one JSON document suitable for a tool or
+Each successful `create` updates the owning collection and refreshes all generated views.
+Guarantee creation allocates the first catalog invariant serial. The final query emits one JSON document suitable for a tool or
 agent. See the [model reference](model-reference.md) before adding other node kinds, and use the
 [CLI reference](cli.md) for the complete command contracts.

package/docs/templates/change-brief.md

@@ -0,0 +1,48 @@
+# Optional change brief
+
+Reuse an existing proposal, issue, or design brief first. Keep only sections that help a
+decision; a few paragraphs may suffice. This file is not a canonical schema or a second backlog.
+Use Observed, Open, Accepted, and Rejected as prose labels, never YAML lifecycle states.
+
+## Problem and actor
+
+Who needs what outcome, and why now?
+
+## Examples and refusal cases
+
+Describe concrete success, refusal, and uncertainty cases. Label expected behavior separately
+from results actually observed.
+
+## Observed evidence
+
+Cite paths and headings, symbols, or tests; state provenance, inspected scope, and gaps.
+Observed implementation may be a bug rather than intended behavior.
+
+## Accepted constraints
+
+Record accepted intent and its authority. Accepted does not mean implemented.
+
+## Alternatives
+
+Include doing nothing or reusing existing obligations, with tradeoffs and rejected choices.
+
+## Open questions and conflicts
+
+What still needs a decision? Which work depends on it? Keep unresolved assertions out of YAML.
+
+## Affected canonical IDs
+
+Select existing records explicitly; label proposed additions as proposals. Use fenced code
+for IDs from another product when the repository scans documentation references.
+Record partial or zero-model-change outcomes with a reason.
+
+## Decision and rationale
+
+Record who accepted what and why, plus what remains open. Link an ADR only if the durable
+decision warrants a separate artifact.
+
+## Planning handoff
+
+Link the receiving plan and provide intent, scope, non-goals, acceptance/refusal examples,
+dependencies, exclusions, unresolved decisions, and selected canonical context. State what
+was verified, by which commands, and what has not been executed. A graph is not a delivery plan.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ddduck",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "An opinionated DDD framework for authoring, validating, and visualizing machine-readable product-spec models.",
   "keywords": [
     "ddd",
@@ -32,6 +32,8 @@
     "policies/",
     "skills/",
     "docs/architecture.md",
+    "docs/definition-workflow.md",
+    "docs/templates/change-brief.md",
     "docs/getting-started.md",
     "docs/model.md",
     "docs/model-reference.md",
@@ -72,6 +74,6 @@
     "prettier": "^3.9.6"
   },
   "overrides": {
-    "fast-uri": "^3.1.5"
+    "fast-uri": "^3.1.7"
   }
 }

package/schemas/model-diff.schema.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://ddduck.local/schemas/model-diff.schema.json",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "kind",
+    "before",
+    "after",
+    "scope",
+    "excludedScopes",
+    "added",
+    "removed",
+    "changed",
+    "relocated"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "1" },
+    "kind": { "const": "ModelDiff" },
+    "before": { "$ref": "#/$defs/identity" },
+    "after": { "$ref": "#/$defs/identity" },
+    "scope": { "const": "canonical-yaml-only" },
+    "excludedScopes": { "const": ["decision-content", "evidence-content", "delivery-artifacts", "runtime"] },
+    "added": { "type": "array", "items": { "$ref": "#/$defs/record" } },
+    "removed": { "type": "array", "items": { "$ref": "#/$defs/record" } },
+    "changed": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "kind", "changes"],
+        "properties": {
+          "id": { "type": "string" },
+          "kind": { "type": "string" },
+          "changes": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/change" } }
+        }
+      }
+    },
+    "relocated": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "kind", "beforePath", "afterPath"],
+        "properties": {
+          "id": { "type": "string" },
+          "kind": { "type": "string" },
+          "beforePath": { "type": "string" },
+          "afterPath": { "type": "string" }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "identity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["modelId", "sourceDigest"],
+      "properties": {
+        "modelId": { "type": "string", "pattern": "^model:" },
+        "sourceDigest": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      }
+    },
+    "record": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind", "sourcePath", "node"],
+      "properties": {
+        "id": { "type": "string" },
+        "kind": { "type": "string" },
+        "sourcePath": { "type": "string" },
+        "node": { "type": "object" }
+      }
+    },
+    "change": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "beforePresent", "afterPresent"],
+      "properties": {
+        "path": { "type": "string", "pattern": "^(?:/(?:[^~/]|~[01])*)+$" },
+        "beforePresent": { "type": "boolean" },
+        "afterPresent": { "type": "boolean" },
+        "before": {},
+        "after": {}
+      },
+      "allOf": [
+        {
+          "if": { "properties": { "beforePresent": { "const": true } } },
+          "then": { "required": ["before"] },
+          "else": { "not": { "required": ["before"] } }
+        },
+        {
+          "if": { "properties": { "afterPresent": { "const": true } } },
+          "then": { "required": ["after"] },
+          "else": { "not": { "required": ["after"] } }
+        },
+        {
+          "anyOf": [
+            { "properties": { "beforePresent": { "const": true } } },
+            { "properties": { "afterPresent": { "const": true } } }
+          ]
+        }
+      ]
+    }
+  }
+}