@jwilger/pi-development-system 0.85.0 → 0.86.0

package/README.md

@@ -20,13 +20,19 @@ plain words: when a prompt asks for new work, a fix or a review, the system adds
 naming the tool to use (`devsys_intake`, `devsys_review_start`). A `devsys` tool always shows
 what the current phase expects. When you say a slice is finished with no review round recorded,
 it tells you to start one. The slash commands (`/devsys-start`, `/devsys-plan`, `/devsys-review`,
-`/devsys-lens-review`, `/devsys-adr`) are shortcuts to the same tools.
+`/devsys-lens-review`, `/devsys-adr`, `/devsys-event-model`) are shortcuts to the same tools.
 
 Product planning has a skill (`product-planning`: brief, decision register, follow-ups,
 terminology, journeys). `devsys_lens_review` plans a review of the brief by five product lenses and
 writes the packets to `docs/product/reviews/`; `devsys_adr_new` creates the next numbered ADR, and
 a commit that shapes the architecture without one is stopped by the soft gate `adr.missing`.
 
+Event modelling has a skill (`event-modelling`: three slice patterns, Given/When/Then, completeness).
+`devsys_event_model_check` validates a directory of slice files (schema v1) and renders the swimlane
+Markdown or a Mermaid diagram; each profile's `gwt-tests` reference turns scenarios into failing tests.
+A dedicated extension that offers `event_model_validate`, or `event_model.provider` in
+`.development-system.toml`, replaces the builtin tool (`docs/event-model-extension-contract.md`).
+
 A slice has a life cycle: `implementing` → `reviewing` (when a review round starts) → `delivering`
 (review satisfied) → `idle`. Editing production source while delivering reopens `implementing`,
 and red-first stays on throughout. A push of a clean tree closes a delivered slice by itself (a commit

package/extensions/development-system.ts

@@ -29,6 +29,7 @@ import { createJevHolder } from "../src/jev/holder.ts";
 import { createJudgeTools } from "../src/jev/judge-tools.ts";
 import { createAdrNewTool } from "../src/planning/adr-tool.ts";
 import { createBeginWorkTool } from "../src/planning/begin-tool.ts";
+import { registerEventModelProvider } from "../src/planning/event-model-provider.ts";
 import { createIntakeTool } from "../src/planning/intake-tool.ts";
 import { createFinishSliceTool, registerSliceClose } from "../src/planning/slice-close.ts";
 import { createTaskCheckTool } from "../src/planning/task-check-tool.ts";
@@ -179,6 +180,7 @@ export function createDevelopmentSystem(pi: ExtensionAPI) {
   pi.registerTool(createPhaseTool({ state }));
   pi.registerTool(createBeginWorkTool({ state }));
   pi.registerTool(createAdrNewTool({ now: () => new Date() }));
+  registerEventModelProvider(pi);
   pi.registerTool(createFinishSliceTool({ state, exec }));
   pi.registerTool(
     createLensReviewTool({ state, jev: (ctx) => jevHolder.forContext(ctx), now: () => new Date() }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jwilger/pi-development-system",
-  "version": "0.85.0",
+  "version": "0.86.0",
   "description": "A pi extension package representing a seasoned approach to software development using a full AI SDLC.",
   "keywords": [
     "pi-package"

package/prompts/devsys-event-model.md

@@ -0,0 +1,11 @@
+---
+description: Model a capability as event-model slices and validate them
+argument-hint: "[directory of slice files, default docs/event-model]"
+---
+Event-model the work with the event-modelling skill.
+
+1. If a tool named `event_model_validate` exists, an event-model extension is installed: use it for validation and rendering instead of the builtin check, and follow its own prompt.
+2. Otherwise write one slice file per command, view or automation under the directory ($ARGUMENTS, default `docs/event-model`), in the schema the skill describes.
+3. Call `devsys_event_model_check` with that directory. Fix every error it reports; `render` asks for the derived Markdown or Mermaid view. Do not edit the derived views by hand.
+4. If the validator wants a fact the model does not have, ask the user. Never invent a policy, field or event to make validation pass.
+5. When the model is clean, write one failing test per Given/When/Then scenario with the profile's `references/gwt-tests.md`.

package/skills/event-modelling/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: event-modelling
+description: Model a capability as event-model slices (command, events, views, Given/When/Then) before building it, validate them, and turn each scenario into a failing test. Use when a capability or product has state changes, views or automations to design, when asked for an event model, or before writing tests for a command-and-event feature.
+---
+
+# Event modelling (lite)
+
+An event model says what happens (events), what causes it (commands), and what people see (views), one thin
+slice at a time. Here it is a set of small YAML or JSON files, one per slice, validated by
+`devsys_event_model_check` and turned into tests. Keep it small: model what the work needs, not the whole
+domain. If a repo has a dedicated event-model extension (a tool named `event_model_validate`), use that tool
+instead.
+
+## The three slice patterns
+
+| Pattern | Shape | Has |
+|---|---|---|
+| `state-change` | an actor issues a command and events record the result | `command`, `events`, `gwt` |
+| `state-view` | a view is built from events | `views` (each with `sources`), `gwt` optional |
+| `automation` | the system reacts to events with a command | `actor: system`, `command`, `events`, `gwt` (its `given` names the triggering events) |
+
+A slice file:
+
+```yaml
+id: slice.signin.c01
+pattern: state-change
+actor: user
+command: { name: SignIn, fields: { email: string, password: secret } }
+events:
+  - { name: SignedIn, fields: { userId: id, at: timestamp } }
+gwt:
+  - given: [{ event: UserRegistered, let: { email: "a@b.c" } }]
+    when: { command: SignIn, let: { email: "a@b.c", password: "pw" } }
+    then: [{ event: SignedIn }]
+```
+
+Views list `{ name, fields, sources: [event names] }`. Ids are unique and stable (`slice.<name>.<c|v|a><nn>`).
+
+## The seven steps
+
+1. **Brainstorm the events** in past tense (`UserRegistered`, `SignedIn`), in the order they happen.
+2. **Order them** into a story along time, and note which actor causes each.
+3. **Add the commands** that cause the events, with the fields the actor supplies.
+4. **Add the views** people read, naming the events each is built from.
+5. **Cut slices**: one file per command, view or automation, each independently buildable.
+6. **Write the scenarios**: Given (prior events), When (the one command), Then (events, an error, or a view).
+7. **Validate and fix**: run `devsys_event_model_check` and resolve every error.
+
+Put the files under `docs/event-model/` (or the directory the user names). Ask for the derived swimlane
+Markdown or a Mermaid diagram with `render`; never edit derived views by hand.
+
+## Given / When / Then
+
+- `given`: events that already happened, with the values (`let`) that matter. Empty means no history.
+- `when`: exactly one command, with its values. A `state-view` slice has none.
+- `then`: at least one expectation: an `event`, an `error` (kebab-case id), or a `view`.
+
+## Completeness
+
+The validator checks that information has an origin and a destination:
+
+- every field of a view appears in the fields of one of its source events (`missing-origin`);
+- every field a system-run command needs comes from a view or an earlier event (`missing-origin`);
+- every command produces at least one event (`missing-destination`);
+- every name that a scenario or view mentions exists in some slice (`unknown-ref`);
+- ids and names are unique (`duplicate-id`); scenarios have a `when` and a non-empty `then`
+  (`gwt-without-when`, `gwt-then-empty`); a slice's fields match its pattern (`pattern-field-mismatch`);
+- an event nothing reads is a warning (`orphan-event`): a view, a scenario or an automation should use it.
+
+## Never invent policy to satisfy the validator
+
+When a check fails because the model lacks a fact (where does this field come from? who sends this
+command?), that is a question for the user, not a gap to fill. Do not add a field, an event or a rule only so
+validation passes. Ask one question, record the answer in the model, and continue.
+
+## From scenarios to tests
+
+One failing test per scenario, with the gwt-tests reference of the active language profile
+(`profile-typescript` or `profile-rust`). No spec in the model without an equivalent in code, and no
+behaviour in code that the model does not cover. When they disagree, change the model first.
+
+## Skipping
+
+Event modelling is a planning artifact for `capability` and `product` work. Skipping it is a recorded
+departure: `devsys_record_departure` with gate `artifact.skipped:event-model` and why it does not
+fit (for example, no state changes or views to design).
+
+## Checklist
+
+- [ ] Every command, view and automation is its own slice file with a stable id
+- [ ] `devsys_event_model_check` reports 0 errors; warnings read and answered
+- [ ] No field, event or rule exists only to satisfy the validator
+- [ ] Each scenario has a failing test, written before the code

package/skills/profile-rust/SKILL.md

@@ -13,6 +13,7 @@ Read the reference you need, not all of them:
 - Errors: `references/errors.md`
 - Lints: `references/lints.md`
 - Tests and mutation testing: `references/tests.md`
+- Event-model scenarios as tests: `references/gwt-tests.md`
 
 ## Defaults
 

package/skills/profile-rust/references/gwt-tests.md

@@ -0,0 +1,14 @@
+# GWT scenarios to failing tests (Rust)
+
+An event-model slice lists Given/When/Then scenarios. Each is one test; no spec in the model without an
+equivalent in code.
+
+1. Name the test after the slice and scenario: `fn signin_after_registration_emits_signed_in()`, in a module named for the slice.
+2. **Given** the listed events become the history slice passed to the decide function (`&[Event]`, with the `let` values filled in).
+3. **When** the command is the input: call the pure `decide(&history, command)`, not a handler with I/O.
+4. **Then** events assert the returned `Vec<Event>`, `error` asserts the returned error variant (`matches!`), and `view` asserts the projection folded from the events.
+5. Run it and watch it fail before writing `decide` or the projection (RED), then make it pass.
+6. A scenario with an empty `given` is a command against no history; keep it as its own test.
+
+One failing `#[test]` per scenario. Do not loop over scenarios in one test, which hides which one failed.
+When code and model disagree, change the model first (the model is the spec), then the test.

package/skills/profile-typescript/SKILL.md

@@ -13,6 +13,7 @@ Read the reference you need:
 - Result pattern: `references/errors.md`
 - tsconfig and biome: `references/lints.md`
 - Test layout: `references/tests.md`
+- Event-model scenarios as tests: `references/gwt-tests.md`
 
 ## Defaults
 

package/skills/profile-typescript/references/gwt-tests.md

@@ -0,0 +1,15 @@
+# GWT scenarios to failing tests (TypeScript)
+
+An event-model slice lists Given/When/Then scenarios. Each is one test; no spec in the model without an
+equivalent in code.
+
+1. Name the test after the slice and scenario: `test("slice.signin.c01: SignIn after UserRegistered emits SignedIn", ...)`.
+2. **Given** the listed events become the history the function receives (an array of event objects, with the `let` values filled in).
+3. **When** the command is the input: call the pure decide function (`decide(history, command)`), not a handler with I/O.
+4. **Then** events assert the returned events, `error` asserts the returned error `kind`, and `view` asserts the projection built from the events.
+5. Run it and watch it fail before writing the decide or project function (RED), then make it pass.
+6. A scenario with an empty `given` is a command against no history; keep it as its own test.
+
+One failing test per scenario, one `test(...)` each, in `test/<area>/<slice>.test.ts`. Do not merge scenarios
+into a table that hides which one failed. When code and model disagree, change the model first (the model is
+the spec), then the test.

package/src/planning/event-model-provider.ts

@@ -0,0 +1,36 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../state/config.ts";
+import { createEventModelCheckTool } from "./event-model-tool.ts";
+
+/** The name of the builtin tool; a provider extension offers `event_model_validate` instead. */
+export const EVENT_MODEL_TOOL = "devsys_event_model_check";
+const PROVIDER_TOOL = "event_model_validate";
+
+/**
+ * The builtin event-model-lite validator is for repos that have nothing better: it steps aside when the config
+ * names another provider, or when an extension registers `event_model_validate` (see
+ * docs/event-model-extension-contract.md).
+ */
+export function usesBuiltinEventModel(provider: string, toolNames: readonly string[]): boolean {
+  return provider === "builtin" && !toolNames.includes(PROVIDER_TOOL);
+}
+
+/**
+ * Registers the builtin tool at session start, when every extension's tools are known and the repo's config
+ * can be read: neither is available while the extension loads.
+ */
+export function registerEventModelProvider(pi: ExtensionAPI): void {
+  pi.on("session_start", async (_event, ctx) => {
+    const config = await loadConfig(ctx.cwd);
+    const provider = config.ok ? config.value.eventModel.provider : "builtin";
+    const names = pi.getAllTools().map((tool) => tool.name);
+    if (usesBuiltinEventModel(provider, names)) {
+      pi.registerTool(createEventModelCheckTool());
+    } else if (!names.includes(PROVIDER_TOOL)) {
+      ctx.ui.notify(
+        `event_model.provider is "${provider}" but no ${PROVIDER_TOOL} tool is loaded: install that extension, or set provider = "builtin" to use ${EVENT_MODEL_TOOL}.`,
+        "warning",
+      );
+    }
+  });
+}

package/src/planning/event-model-render.ts

@@ -0,0 +1,81 @@
+import type { Slice } from "./slice-schema.ts";
+
+/** Derived views of an event model: a swimlane table with scenarios, and a diagram. Never edited by hand. */
+
+const values = (let_: Record<string, unknown> | undefined): string => {
+  const entries = Object.entries(let_ ?? {});
+  return entries.length === 0
+    ? ""
+    : ` (${entries.map(([k, v]) => `${k}: ${JSON.stringify(v)}`).join(", ")})`;
+};
+
+type Scenario = Slice["gwt"][number];
+
+const scenarioLines = (g: Scenario): string[] => [
+  ...g.given.map((x) => `- Given ${x.event}${values(x.let)}`),
+  ...(g.when ? [`- When ${g.when.command}${values(g.when.let)}`] : []),
+  ...g.then.map((t) => {
+    if ("error" in t) return `- Then error ${t.error}`;
+    if ("view" in t) return `- Then view ${t.view}${values(t.let)}`;
+    return `- Then ${t.event}${values(t.let)}`;
+  }),
+];
+
+const cell = (text: string): string => (text === "" ? "" : ` ${text} `);
+
+const row = (s: Slice): string =>
+  `|${[
+    s.id,
+    s.pattern,
+    s.actor,
+    s.command?.name ?? "",
+    s.events.map((e) => e.name).join(", "),
+    s.views.map((v) => v.name).join(", "),
+  ]
+    .map(cell)
+    .join("|")}|`
+    .replace(/\|\|/g, "| |")
+    .replace(/\| \|\|/g, "| | |");
+
+/** The swimlane table (one row per slice), then each slice's scenarios as Given/When/Then lists. */
+export function renderModelMarkdown(slices: readonly Slice[]): string {
+  const table = [
+    "| Slice | Pattern | Actor | Command | Events | Views |",
+    "|---|---|---|---|---|---|",
+    ...slices.map(row),
+  ];
+  const sections = slices.flatMap((s) => [
+    `## ${s.id}`,
+    "",
+    ...s.gwt.flatMap((g, i) => [`Scenario ${i + 1}`, "", ...scenarioLines(g), ""]),
+  ]);
+  return `${[...table, "", ...sections].join("\n").trimEnd()}\n`;
+}
+
+/** Mermaid node ids hold letters, digits and underscores; the label carries the real name. */
+const label = (name: string): string => `"${name.replace(/"/g, "#quot;")}"`;
+
+/**
+ * Commands to the events they produce, and events to the views that read them. Ids are numbered per name
+ * (not derived from it), so names that differ only in punctuation or script are never merged into one node.
+ */
+export function renderMermaid(slices: readonly Slice[]): string {
+  const ids = new Map<string, string>();
+  const node = (prefix: string, name: string): string => {
+    const key = `${prefix}:${name}`;
+    const id = ids.get(key) ?? `${prefix}${ids.size + 1}`;
+    ids.set(key, id);
+    return `${id}[${label(name)}]`;
+  };
+  const lines = ["flowchart LR"];
+  for (const s of slices) {
+    if (s.command) {
+      for (const e of s.events)
+        lines.push(`  ${node("c", s.command.name)} --> ${node("e", e.name)}`);
+    }
+    for (const v of s.views) {
+      for (const source of v.sources) lines.push(`  ${node("e", source)} --> ${node("v", v.name)}`);
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}

package/src/planning/event-model-tool.ts

@@ -0,0 +1,92 @@
+import { readdir, readFile } from "node:fs/promises";
+import { extname, isAbsolute, join, relative, resolve } from "node:path";
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import { renderMermaid, renderModelMarkdown } from "./event-model-render.ts";
+import { parseSlice, type Slice, type SliceFormat, validateModel } from "./slice-schema.ts";
+
+const Parameters = Type.Object({
+  dir: Type.String({
+    description: "Directory of slice files (.yaml, .yml, .json), inside the repository.",
+  }),
+  render: Type.Optional(
+    Type.Union([Type.Literal("markdown"), Type.Literal("mermaid")], {
+      description: "Also return the derived swimlane Markdown or Mermaid diagram.",
+    }),
+  ),
+});
+
+const reply = (text: string, isError = false) => ({
+  content: [{ type: "text" as const, text }],
+  details: undefined,
+  isError,
+});
+
+const FORMATS: Record<string, SliceFormat> = { ".yaml": "yaml", ".yml": "yaml", ".json": "json" };
+
+const insideRepo = (cwd: string, target: string): boolean => {
+  const rel = relative(cwd, target);
+  return !(rel.startsWith("..") || isAbsolute(rel));
+};
+
+type Loaded = { slices: Slice[]; problems: string[]; files: number };
+
+async function loadSlices(dir: string, names: readonly string[]): Promise<Loaded> {
+  const slices: Slice[] = [];
+  const problems: string[] = [];
+  for (const name of names) {
+    const format = FORMATS[extname(name)];
+    if (format === undefined) continue;
+    const parsed = parseSlice(await readFile(join(dir, name), "utf8"), format);
+    if (parsed.ok) slices.push(parsed.value);
+    else problems.push(`${name}: ${parsed.error.message}`);
+  }
+  return { slices, problems, files: slices.length + problems.length };
+}
+
+const derived = (
+  slices: readonly Slice[],
+  render: Static<typeof Parameters>["render"],
+): string[] => {
+  if (render === "markdown") return [renderModelMarkdown(slices)];
+  if (render === "mermaid") return [renderMermaid(slices)];
+  return [];
+};
+
+/**
+ * `devsys_event_model_check`: validates a directory of event-model-lite slices (schema v1) and can derive
+ * the Markdown or Mermaid view. A dedicated event-model extension replaces it (see
+ * docs/event-model-extension-contract.md).
+ */
+export function createEventModelCheckTool(): ToolDefinition<typeof Parameters> {
+  return {
+    name: "devsys_event_model_check",
+    label: "Check event model",
+    description:
+      "Validate a directory of event-model slice files (schema v1: pattern, command, events, views, Given/When/Then) for unknown references, missing origins and destinations, empty scenarios and orphan events; optionally render the swimlane Markdown or a Mermaid diagram.",
+    promptSnippet: "Validate event-model slices and render the derived views",
+    parameters: Parameters,
+    async execute(_id, params: Static<typeof Parameters>, _signal, _onUpdate, ctx) {
+      const dir = resolve(ctx.cwd, params.dir);
+      if (!insideRepo(ctx.cwd, dir)) return reply(`${params.dir} is outside the repository`, true);
+      let names: string[];
+      try {
+        names = (await readdir(dir)).sort();
+      } catch {
+        return reply(`cannot read ${params.dir}: no such directory`, true);
+      }
+      const { slices, problems, files } = await loadSlices(dir, names);
+      if (files === 0) return reply(`no slice files (.yaml, .yml, .json) in ${params.dir}`, true);
+      const issues = validateModel(slices);
+      const warnings = issues.filter((i) => i.severity === "warning").length;
+      const errors = issues.length - warnings + problems.length;
+      const lines = [
+        `${slices.length} slices, ${errors} errors, ${warnings} warnings`,
+        ...problems.map((p) => `- parse-error (error) ${p}`),
+        ...issues.map((i) => `- ${i.code} (${i.severity}) ${i.slice}: ${i.message}`),
+      ];
+      const report = lines.join("\n");
+      return reply([report, ...derived(slices, params.render)].join("\n\n"), errors > 0);
+    },
+  };
+}

package/src/planning/slice-schema.ts

@@ -0,0 +1,312 @@
+import { type Static, Type } from "typebox";
+import Value from "typebox/value";
+import { parse as parseYaml } from "yaml";
+import { err, ok, type Result } from "../core/result.ts";
+import { type ParseError, parseError } from "../core/types.ts";
+
+/**
+ * Event-model lite, slice schema v1 (plan Appendix D). One slice is one command-to-events step, one
+ * view over events, or one automation; Given/When/Then scenarios say what it must do. The schema is
+ * deliberately small: a validator that needs more than this to pass is asking for invented policy.
+ */
+
+const Fields = Type.Record(Type.String(), Type.String());
+const Values = Type.Record(Type.String(), Type.Unknown());
+const Name = Type.String({ minLength: 1 });
+
+const SlicePattern = Type.Union([
+  Type.Literal("state-change"),
+  Type.Literal("state-view"),
+  Type.Literal("automation"),
+]);
+
+const EventDecl = Type.Object({ name: Name, fields: Fields }, { additionalProperties: false });
+const ViewDecl = Type.Object(
+  { name: Name, fields: Fields, sources: Type.Array(Name) },
+  { additionalProperties: false },
+);
+const Given = Type.Object(
+  { event: Name, let: Type.Optional(Values) },
+  { additionalProperties: false },
+);
+const When = Type.Object(
+  { command: Name, let: Type.Optional(Values) },
+  { additionalProperties: false },
+);
+const Then = Type.Union([
+  Type.Object({ event: Name, let: Type.Optional(Values) }, { additionalProperties: false }),
+  Type.Object({ error: Name }, { additionalProperties: false }),
+  Type.Object({ view: Name, let: Type.Optional(Values) }, { additionalProperties: false }),
+]);
+const Scenario = Type.Object(
+  // biome-ignore lint/suspicious/noThenProperty: "then" is the Given/When/Then key the slice schema (plan Appendix D) defines; these objects are never awaited.
+  { given: Type.Array(Given), when: Type.Optional(When), then: Type.Array(Then) },
+  { additionalProperties: false },
+);
+
+const SliceSchema = Type.Object(
+  {
+    id: Name,
+    pattern: SlicePattern,
+    actor: Name,
+    command: Type.Optional(
+      Type.Object({ name: Name, fields: Fields }, { additionalProperties: false }),
+    ),
+    events: Type.Optional(Type.Array(EventDecl)),
+    views: Type.Optional(Type.Array(ViewDecl)),
+    gwt: Type.Optional(Type.Array(Scenario)),
+  },
+  { additionalProperties: false },
+);
+
+type Raw = Static<typeof SliceSchema>;
+
+/** A parsed slice: the optional lists are present, empty when the file left them out. */
+export type Slice = Omit<Raw, "events" | "views" | "gwt"> & {
+  events: Static<typeof EventDecl>[];
+  views: Static<typeof ViewDecl>[];
+  gwt: Static<typeof Scenario>[];
+};
+
+export type SliceFormat = "json" | "yaml";
+
+/** One slice from JSON or YAML text; a schema violation names the path and the rule it broke. */
+export function parseSlice(text: string, format: SliceFormat): Result<Slice, ParseError> {
+  let data: unknown;
+  try {
+    data = format === "json" ? JSON.parse(text) : parseYaml(text);
+  } catch (e) {
+    const reason = e instanceof Error ? e.message : String(e);
+    // The yaml library appends a code frame; the first line is the reason, and a report is one line per issue.
+    return err(parseError(`not valid ${format}: ${reason.split("\n")[0]}`));
+  }
+  const first = Value.Errors(SliceSchema, data)[0];
+  if (first !== undefined) {
+    return err(
+      parseError(`${first.instancePath === "" ? "/" : first.instancePath}: ${first.message}`),
+    );
+  }
+  const raw = data as Raw;
+  return ok({ ...raw, events: raw.events ?? [], views: raw.views ?? [], gwt: raw.gwt ?? [] });
+}
+
+type ValidationCode =
+  | "duplicate-id"
+  | "unknown-ref"
+  | "missing-origin"
+  | "missing-destination"
+  | "gwt-without-when"
+  | "gwt-then-empty"
+  | "orphan-event"
+  | "pattern-field-mismatch";
+
+export type ValidationIssue = {
+  code: ValidationCode;
+  /** An orphan event may be a deliberate end of the line; everything else is a hole in the model. */
+  severity: "error" | "warning";
+  slice: string;
+  message: string;
+};
+
+const issue = (
+  code: ValidationCode,
+  slice: string,
+  message: string,
+  severity: ValidationIssue["severity"] = "error",
+): ValidationIssue => ({ code, severity, slice, message });
+
+function duplicates(slices: readonly Slice[]): ValidationIssue[] {
+  const seen = {
+    id: new Set<string>(),
+    command: new Set<string>(),
+    event: new Set<string>(),
+    view: new Set<string>(),
+  };
+  const out: ValidationIssue[] = [];
+  const claim = (kind: keyof typeof seen, name: string, slice: string): void => {
+    if (seen[kind].has(name)) {
+      out.push(issue("duplicate-id", slice, `the ${kind} "${name}" is declared more than once`));
+    }
+    seen[kind].add(name);
+  };
+  for (const s of slices) {
+    claim("id", s.id, s.id);
+    if (s.command) claim("command", s.command.name, s.id);
+    for (const e of s.events) claim("event", e.name, s.id);
+    for (const v of s.views) claim("view", v.name, s.id);
+  }
+  return out;
+}
+
+type Model = {
+  events: Map<string, Record<string, string>>;
+  views: Map<string, Record<string, string>>;
+  usedEvents: Set<string>;
+};
+
+const indexModel = (slices: readonly Slice[]): Model => {
+  const events = new Map<string, Record<string, string>>();
+  const views = new Map<string, Record<string, string>>();
+  const usedEvents = new Set<string>();
+  for (const s of slices) {
+    for (const e of s.events) events.set(e.name, e.fields);
+    for (const v of s.views) {
+      views.set(v.name, v.fields);
+      for (const source of v.sources) usedEvents.add(source);
+    }
+    for (const g of s.gwt) for (const given of g.given) usedEvents.add(given.event);
+  }
+  return { events, views, usedEvents };
+};
+
+function shape(s: Slice): ValidationIssue[] {
+  const problems: string[] = [];
+  if (s.pattern === "state-view") {
+    if (s.views.length === 0) problems.push("a state-view needs at least one view");
+    if (s.command) problems.push("a state-view has no command");
+    if (s.events.length > 0) problems.push("a state-view declares no events; its sources do");
+  } else {
+    if (!s.command) problems.push(`a ${s.pattern} needs a command`);
+    if (s.views.length > 0) problems.push(`a ${s.pattern} declares no views`);
+    if (s.pattern === "automation" && s.actor !== "system") {
+      problems.push('an automation is run by the actor "system"');
+    }
+  }
+  return problems.map((p) => issue("pattern-field-mismatch", s.id, p));
+}
+
+function commandOrigins(s: Slice, model: Model): ValidationIssue[] {
+  if (!s.command || s.actor !== "system") return [];
+  const known = new Set<string>();
+  for (const fields of model.views.values()) for (const f of Object.keys(fields)) known.add(f);
+  for (const g of s.gwt) {
+    for (const given of g.given) {
+      for (const f of Object.keys(model.events.get(given.event) ?? {})) known.add(f);
+    }
+  }
+  return Object.keys(s.command.fields)
+    .filter((f) => !known.has(f))
+    .map((f) =>
+      issue("missing-origin", s.id, `command field "${f}" comes from no view or triggering event`),
+    );
+}
+
+function viewIssues(s: Slice, model: Model): ValidationIssue[] {
+  const out: ValidationIssue[] = [];
+  for (const view of s.views) {
+    const carried = new Set<string>();
+    for (const source of view.sources) {
+      const fields = model.events.get(source);
+      if (fields === undefined) {
+        out.push(
+          issue(
+            "unknown-ref",
+            s.id,
+            `view "${view.name}" reads event "${source}", which no slice declares`,
+          ),
+        );
+      } else {
+        for (const f of Object.keys(fields)) carried.add(f);
+      }
+    }
+    for (const f of Object.keys(view.fields)) {
+      if (!carried.has(f)) {
+        out.push(
+          issue(
+            "missing-origin",
+            s.id,
+            `view field "${f}" of "${view.name}" is carried by none of its source events`,
+          ),
+        );
+      }
+    }
+  }
+  return out;
+}
+
+function whenIssues(s: Slice, g: Slice["gwt"][number], where: string): ValidationIssue[] {
+  if (s.pattern === "state-view") {
+    return g.when === undefined
+      ? []
+      : [issue("pattern-field-mismatch", s.id, `${where} of a state-view has no when`)];
+  }
+  if (g.when === undefined) return [issue("gwt-without-when", s.id, `${where} has no when`)];
+  if (g.when.command === s.command?.name) return [];
+  const own = s.command?.name ?? "command";
+  return [
+    issue(
+      "unknown-ref",
+      s.id,
+      `${where} runs command "${g.when.command}", not this slice's ${own}`,
+    ),
+  ];
+}
+
+function thenIssues(
+  s: Slice,
+  g: Slice["gwt"][number],
+  where: string,
+  model: Model,
+): ValidationIssue[] {
+  if (g.then.length === 0) return [issue("gwt-then-empty", s.id, `${where} expects nothing`)];
+  return g.then.flatMap((t) => {
+    if ("event" in t && !model.events.has(t.event)) {
+      return [
+        issue("unknown-ref", s.id, `${where} expects event "${t.event}", which no slice declares`),
+      ];
+    }
+    if ("view" in t && !model.views.has(t.view)) {
+      return [
+        issue("unknown-ref", s.id, `${where} expects view "${t.view}", which no slice declares`),
+      ];
+    }
+    return [];
+  });
+}
+
+function scenarioIssues(s: Slice, model: Model): ValidationIssue[] {
+  return s.gwt.flatMap((g, i) => {
+    const where = `scenario ${i + 1}`;
+    const given = g.given
+      .filter((x) => !model.events.has(x.event))
+      .map((x) =>
+        issue("unknown-ref", s.id, `${where} gives event "${x.event}", which no slice declares`),
+      );
+    return [...whenIssues(s, g, where), ...given, ...thenIssues(s, g, where, model)];
+  });
+}
+
+function ownIssues(s: Slice, model: Model): ValidationIssue[] {
+  const missingDestination =
+    s.pattern !== "state-view" && s.command && s.events.length === 0
+      ? [issue("missing-destination", s.id, `command "${s.command.name}" produces no events`)]
+      : [];
+  const orphans = s.events
+    .filter((e) => !model.usedEvents.has(e.name))
+    .map((e) =>
+      issue(
+        "orphan-event",
+        s.id,
+        `event "${e.name}" feeds no view and starts no scenario`,
+        "warning",
+      ),
+    );
+  return [
+    ...shape(s),
+    ...missingDestination,
+    ...commandOrigins(s, model),
+    ...viewIssues(s, model),
+    ...scenarioIssues(s, model),
+    ...orphans,
+  ];
+}
+
+/**
+ * Checks a whole model: names are unique, every reference resolves, and information is complete (every
+ * view field has an event origin, every system command field a source). Judges nothing the model does
+ * not say: a hole is reported, never filled.
+ */
+export function validateModel(slices: readonly Slice[]): ValidationIssue[] {
+  const model = indexModel(slices);
+  return [...duplicates(slices), ...slices.flatMap((s) => ownIssues(s, model))];
+}