@milehimikey/em 1.3.0 → 1.5.0

package/.claude/skills/event-modeling/reference/extract.md

@@ -70,10 +70,16 @@ it is fine to finish a round with `# TBD`s still parked.
   *actual* actors/callers and the *real* UI or API surfaces (headless systems: no
   `ui`/`persona` — use write/read translations per `em-dsl.md`). **First `em render` here.**
 - **R3 — Commands / inputs.** For each event, the request that actually produces it today
-  (imperative name). Unclear trigger → `# TBD`, not a plausible guess.
+  (imperative name), *and what triggers it* — the real screen, or the scheduler/listener that
+  fires it (model that as a reaction in the preceding slice, per R5). Unclear trigger → `# TBD`,
+  not a plausible guess; expect a *command has nothing that triggers it* warning until R5 fills
+  it in, and don't invent a screen to silence it.
 - **R4 — Read models / outputs.** The projections/queries the system actually serves; wire
-  `from "Event"` (repeat read models span-1 per `em-dsl.md`). **Start running `em validate`**
-  each round from here.
+  `from "Event"` (repeat read models span-1 per `em-dsl.md`, using `view X again` after the
+  first). **Start running `em validate`** each round from here. Expect *event is not read by any
+  read model* warnings: real systems do record fire-and-forget events. In an as-is model that is
+  a **finding about the system**, not a modelling mistake — never invent a reader to silence it
+  (that would be desired state). Park it in the Decisions log and carry the warning.
 - **R5 — Boundaries & reactions.** Current automations and integrations as-is: schedulers,
   listeners, outbound syncs, inbound webhooks. Model each as a reaction with the two-slice
   `reaction → command → event` split and the slice-ordering rules in `em-dsl.md` — even when
@@ -103,8 +109,9 @@ one for a sprawling one. Record any deviation in the Decisions log.
 ## Completion & handoff
 
 Extraction is complete when: the model renders; `em validate` is clean (or remaining warnings
-are consciously accepted in the Decisions log); every unknown is a parked `# TBD`; and the
-user has confirmed the model reflects today's behavior. Then:
+are consciously accepted in the Decisions log — unread events in an as-is model are the usual
+accepted case, and each one is worth naming explicitly as a finding); every unknown is a parked
+`# TBD`; and the user has confirmed the model reflects today's behavior. Then:
 
 1. State file: set phase progress (extraction rounds checked), log the completion decision.
    Seed `README.md`'s **slice index** (every slice, pattern, status `none`).

package/.claude/skills/event-modeling/reference/methodology.md

@@ -16,6 +16,20 @@ three ways:
 3. There is **no other way** for information to flow. Every box on the diagram is one of:
    UI screen, command, event, read model, or automation/processor.
 
+Concretely, that leaves exactly six legal connections, and `em` infers only these:
+`ui → command`, `command → event`, `event → read model`, `read model → ui`,
+`read model → reaction`, `reaction → command`. Every other pair is a rule violation, and an
+explicit `arrow` writing one is a validation error. The two worth naming, because they are the
+tempting shortcuts:
+
+- **`command → read model`** — the CQRS violation. A write is only ever visible to a reader
+  through the event it recorded. Put the event between them.
+- **`read model → command`** — reads never drive a write directly. A processor or translation
+  watches the read model and issues the command, across two slices.
+
+If you find yourself wanting an arrow the patterns don't allow, the model is missing an
+**element**, not an arrow.
+
 **Automations and translations are not exceptions to rule 1.** They are *reactions* — a processor
 or an adapter that wakes up, decides something must change, and **issues a command** to do it. They
 never record an event themselves. A reaction box always points at a **command** (in the next
@@ -37,7 +51,24 @@ Every slice is exactly one of these. In `em`, each maps to a specific shape (see
 ### 1. State Change (Command pattern)
 **UI → Command → Event.** A user (or automation) submits a command; the system validates it
 against invariants and records one or more events.
-- `em` shape: `slice { ui X @Persona  command Y  event Z @Context }`
+- **A State Change never travels alone, and it's joined at both ends.** Something must *trigger*
+  the command — the `ui` it's issued from, or (patterns 3 and 4) the reaction in the slice before
+  it — and its event needs a read model that projects it. So the unit of work is a State Change
+  slice *plus* the State View slice that reads its event. Write them together; a command nothing
+  points at is a write nobody can start, an unread event is a write nobody can see, and
+  `em validate` warns on each.
+- `em` shape (one element per line — there is no one-line slice form):
+  ```em
+  slice "Do The Thing" {
+    ui X @Persona
+    command Y
+    event Z @Context
+  }
+  slice "See The Result" {   # the State View slice that reads Z — pattern 2, but required here
+    view V from "Z"
+    ui Screen @Persona
+  }
+  ```
 - This is where **invariants** live — the command is rejected if a rule is violated.
 - Socratic prompts: *"What does the user do here? What request are they making? What must be
   true for it to succeed? What fact gets recorded when it does? What gets rejected and why?"*
@@ -55,19 +86,30 @@ displays. Read-only; changes no state.
 - **Repeat read models across the timeline.** A read model is drawn fresh in **every** slice where
   it is read — after the events that update it, before the actions that consume it — so the diagram
   shows state flowing left-to-right (the information-completeness staircase). The same read-model
-  name recurring is intentional and **renders cleanly**: `em validate` only warns about a duplicate
-  name that is *also referenced* by a `from`/`arrow` (it resolves to the first), so a repeated read
-  model that nothing references by name produces **no warning**. **Wire each event to a read model
+  name recurring is intentional and **renders cleanly**. Declare every instance after the first with
+  **`view V again from "..."`**: `again` instances are exempt from the duplicate-name warning even
+  when something references them, and each reference resolves to the right instance. (A plain repeat
+  only stays warning-free while nothing references it by name, and resolves to the *first*
+  declaration when something does.) **Wire each event to a read model
   exactly once:** a repeated instance's `from` lists only the **new** events since the previous
   instance (not cumulative) — otherwise an event draws a duplicate arrow to the same read model at
   every repeat. (An event may still feed several *different* read models, once each.)
+- **Instances are never connected to one another.** There is no arrow between two appearances of one
+  read model, and an explicit one is a validation error. The repeat is an ergonomic device for
+  showing the same read model at successive points in time — continuity is implied by the shared
+  name, and the events arriving at each instance are what show it changing. An arrow between them
+  would say the read model feeds itself.
 - **Place each repeat immediately after its feeding event (span-1).** The cleanest staircase puts a
   read-model instance right after each event that updates it, sourcing **only that one adjacent
   event** — every `event → read model` arrow is then short and forward-flowing. A read model sitting
   far from its source events (e.g. a "list/queue" read placed early but fed by late events) draws
-  long arrows that cross the read-model row and *look* like read→read connections — which Event
-  Modeling forbids. The fix is never a `view → view` edge; it's to repeat the read model next to each
-  event that feeds it.
+  long arrows that sweep across the diagram. The renderer routes them *around* intervening boxes
+  rather than through them, so they no longer *look* like a forbidden read→read link — but the
+  distance itself is the problem: the arrowhead lands columns away from the event that produced it,
+  so **the write slice reads as dangling**, as if nothing consumed its event. A reader has to trace
+  the line across the diagram to see otherwise. The fix is never a `view → view` edge; it's to
+  repeat the read model next to each event that feeds it, and to keep a sub-flow that detours into
+  another context together rather than parking it at the end of the model.
 - Socratic prompts: *"What does the consumer need to see to make their next decision? Which past
   events provide that information? Is this a screen or an API read? What's the freshness/consistency
   expectation?"*
@@ -76,10 +118,24 @@ displays. Read-only; changes no state.
 **Read Model → Processor → (next slice) Command → Event.** The system reacts on its own: a
 processor watches a read model (a "to-do list" of work) and **issues a command** — it never
 records an event directly.
-- `em` shape: **two slices.** First `slice { view "Todo" from "..."  processor P }`, then the
-  **next** `slice { command C  event E @Context }`. The processor band holds no event; the command
-  in the next slice produces it. Keeping the triggered command in the same slice as the processor
-  is a validation warning — always split it.
+- `em` shape: **two slices**, then the read slice that consumes the event — three in all:
+  ```em
+  slice "Todo" {
+    view Todo from "..."
+    processor P
+  }
+  slice "Do It" {           # the triggered command goes in the NEXT slice
+    command C
+    event E @Context
+  }
+  slice "Todo — done" {
+    view Todo again from "E"   # every event needs a reader; here it clears the to-do list
+    ui Work Board @Persona     # ...and every read model needs a consumer
+  }
+  ```
+  The processor band holds no event; the command in the next slice produces it. Keeping the
+  triggered command in the same slice as the processor is a validation warning — always split it.
+  Forgetting the third slice leaves `E` unread, which is also a warning.
 - Socratic prompts: *"What should happen without a human? What condition triggers it? What work
   list does the processor watch? What command does it fire? What if it fails or retries?"*
 
@@ -92,9 +148,22 @@ trigger forms:
   from outside the model, so the translation has no internal `from`.
 - **Internally triggered** (reacting to the modeled system's own state, e.g. pushing data out):
   `read model → translation → command → event`. The translation reads a **view** via `from`.
-- `em` shape: **two slices**, exactly like an automation. First
-  `slice { [view "Source" from "..."]  translation T [from "Source"] }`, then the **next**
-  `slice { command C  event E @Context }`. The translation band never carries an event.
+- `em` shape: **two slices**, exactly like an automation, plus the read slice for the event:
+  ```em
+  slice "Boundary" {
+    view Source from "..."     # internally triggered only; omit for an external trigger
+    translation T from "Source"
+  }
+  slice "Record It" {
+    command C
+    event E @Context
+  }
+  slice "Source — recorded" {
+    view Source again from "E"   # every event needs a reader
+    ui Status Screen @Persona    # ...and every read model needs a consumer
+  }
+  ```
+  The translation band never carries an event.
 - Socratic prompts: *"What boundary are we crossing, and which way? What outside system or context
   feeds us (or do we feed)? In what format? How do we know its data is trustworthy/complete? What
   internal **command** does it trigger, and what event does that command record?"*
@@ -170,17 +239,30 @@ dedicated `slice` phase writes the full rich spec (see `templates/slice.md`).
 
 ### Step 7 — Evaluate Completeness  *(model)*
 Walk the whole model with stakeholders and check for loose ends:
+- Every **command** has something that **triggers** it — a `ui` in its slice, or a reaction in the
+  slice before it. A command nothing points at is a write nobody can start. `em validate` warns.
 - Every **command** produces at least one **event**.
-- Every **view** has at least one source event.
-- Every **event** is shown somewhere or consumed by something (no orphan facts).
+- Every **view** has at least one source event, **and a consumer** — a `ui`, a reaction watching it,
+  or (headless) a read translation. Every *instance* of a repeated view, not just the last one.
+  A read model nothing displays is information projected out and then dropped. `em validate` warns.
+- Every **event** is **read by a read model** — a `view` naming it in `from` (any `again` instance
+  counts), or a `view` with no `from` sitting in its slice. A reaction consuming it does **not**
+  count: reactions read views, not events. An event nothing projects is a write nobody can see, so
+  there was no point recording it. `em validate` warns on each one.
 - Every **UI** is reachable and leads somewhere.
+- Every connection is one of the six legal pairs (`ui → command`, `command → event`,
+  `event → read model`, `read model → ui`, `read model → reaction`, `reaction → command`). No
+  arrow between two instances of one read model.
 - Automations **and** translations are split correctly (reaction → command → event, never a
   reaction wired straight to an event); translations cover every external input.
-- Run `em validate` and resolve all errors and warnings. Note: `em validate` does **not** catch a
-  translation/automation that emits an event directly — verify the two-slice split by hand.
-- Prompts: *"Is there any event nobody sees? Any screen with no way in or out? Any command that
-  records nothing? Any external system we haven't translated? Any translation or automation that
-  records an event instead of triggering a command?"*
+- Run `em validate` and resolve all errors and warnings. It now catches illegal `arrow` kind pairs
+  (error) and unread events (warning), but it still does **not** catch a translation/automation that
+  emits an event directly — verify the two-slice split by hand.
+- Prompts: *"Is there any event nobody reads — and if the business genuinely never looks at it, why
+  are we recording it? Any command that just happens, with nobody and nothing asking for it? Any
+  screen with no way in or out? Any command that records nothing? Any
+  external system we haven't translated? Any translation or automation that records an event instead
+  of triggering a command?"*
 
 ---
 

package/.claude/skills/event-modeling/templates/conformance-report.md

@@ -0,0 +1,69 @@
+<!--
+Conformance report skeleton. One per conform run, stored at
+<model-name>/conformance/<YYYY-MM-DD>-report.md (see reference/conform.md).
+Fill every section; leave "none" rather than deleting a section with nothing to report.
+Replace bracketed placeholders; delete guidance comments before finishing.
+-->
+
+# Conformance Report — {{Model Name}} — {{YYYY-MM-DD}}
+
+- **Model:** `{{model-name}}.em`
+- **Target repo:** {{repo path or URL}} @ `{{revision}}`
+- **Previous conformance revision:** {{prior target-repo revision, or "never (first run)"}}
+- **Scope:** {{full | diff-scoped since <prior revision>}}
+- **Slices checked:** {{comma-separated slice names, or "all implemented slices"}}
+- **Slices skipped (not yet implemented):** {{list, or "none"}}
+
+## Summary
+
+| Surface | Real drift | Model gap | Internal inconsistency | Uncertainty |
+|---|---|---|---|---|
+| Structural | {{n}} | {{n}} | — | {{n}} |
+| Spec | {{n}} | {{n}} | — | {{n}} |
+| Internal | — | — | {{n}} | {{n}} |
+
+{{One or two sentences: overall read — clean, mostly clean with N items, or notably drifted.}}
+
+## Findings
+
+<!-- One subsection per finding. Group however reads clearest (by slice, or by surface) but keep
+     every field below for every finding. Order doesn't matter; classification does. -->
+
+### {{n}}. {{Short finding title}}
+
+- **Surface:** {{structural | spec | internal}}
+- **Classification:** {{real drift | model gap | internal inconsistency}}
+- **Slice:** {{slice name}}
+- **Evidence:** {{file path(s) and line/symbol, or the `em diff --json` entry (type + name)}}
+- **Claim:** {{what the model/doc says vs. what the code/doc shows — the actual disagreement}}
+- **Proposed red note:** `issue "conformance: {{text}}"` on {{element}} (slice "{{slice}}")
+  <!-- Omit this line entirely for internal-inconsistency findings with no clear side to flag,
+       or when the finding doesn't warrant a red note (say why instead). -->
+
+## Scenario / invariant coverage
+
+<!-- Per in-scope slice: every named invariant and every GWT scenario the doc claims, mapped to
+     its enforcement/test site. Leave a cell explicitly blank/"none found" rather than omitting
+     the row — gaps are the point of this table. -->
+
+### {{Slice Name}}
+
+| Claim | Type | Enforcement site | Test site | Status |
+|---|---|---|---|---|
+| {{INV-XXX-1 or scenario title}} | {{invariant \| scenario}} | {{file path / symbol, or "none found"}} | {{file path / symbol, or "none found"}} | {{covered \| gap \| uncertain}} |
+
+## Uncertainties
+
+<!-- Listed separately from Findings — these are NOT drift. No evidence either way; say what was
+     missing (time, clarity, an ambiguous test) so a follow-up run can pick it up. -->
+
+- **{{structural | spec | internal}}** — {{what's uncertain}} — {{slice}} — {{why: e.g. "couldn't locate the test for INV-CHK-3, only its enforcement site"}}
+
+<!-- Tag each with its surface so these reconcile against the Summary table's Uncertainty column. -->
+
+## Applied this run
+
+<!-- Filled in AFTER the user reviews Findings and says what to apply. Leave "none yet — awaiting
+     ratification" until that conversation happens. -->
+
+{{List of ratified proposals actually applied to the `.em`/slice docs, or "none yet — awaiting ratification".}}

package/.claude/skills/event-modeling/templates/model-readme.md

@@ -21,6 +21,15 @@ Static render: `em render {{model-name}}.em -o {{model-name}}.svg`
 - **Automation** — Read Model → Processor → (next slice) Command → Event
 - **Translation** — External input (or Read Model) → Translation → (next slice) Command → Event
 
+Between them these are the only legal connections: `ui → command`, `command → event`,
+`event → read model`, `read model → ui`, `read model → reaction`, `reaction → command`. A command
+never reaches a read model directly — the event goes between them. Every slice is joined up at
+both ends: something triggers each command (the screen it's issued from, or the reaction in the
+slice before it), and every event a command records is read by some read model — so each State
+Change slice is paired with the State View slice that projects its event. A read model repeated
+along the timeline (`view X again`) shows the same projection at a later point; the instances are
+never connected to one another.
+
 ## Slices
 <!-- The canonical slice index — the ONE place slices are enumerated (the state file
      points here rather than keeping its own copy). Keep it in sync as slice docs are

package/.claude/skills/event-modeling/templates/slice.md

@@ -32,9 +32,20 @@ an event directly.}}
 |-------|------|----------|--------------------|
 | {{field}} | {{Type}} | {{yes/no}} | {{constraints, formats, ranges}} |
 
+## Trigger
+<!-- What issues this slice's command. Required: a command nothing points at is a write nobody
+     can start. Either the screen the user acts on (a `ui` in this slice), or the reaction that
+     issues it (an automation/processor/translation in the PREVIOUS slice). -->
+**Triggered by:** {{screen `X` @Persona | processor `Y` in slice "Z"}}
+
 ## Event(s) Emitted
 <!-- The immutable facts recorded. List each event and its payload. -->
 **Event:** `{{Event Name}}` → context `{{Context}}`
+**Read by:** {{which read model projects this event, and in which slice}}
+<!-- Required, not optional. Every event must be read by a read model — an event nothing
+     projects is a write nobody can see, and `em validate` warns on it. A reaction consuming
+     it does NOT count: reactions read views, not events. If the honest answer is "nothing
+     reads it", that's a question for the business, not a field to leave blank. -->
 
 | Field | Type | Immutable Fact? | Source / Notes |
 |-------|------|-----------------|----------------|
@@ -43,7 +54,10 @@ an event directly.}}
 ## Read Model / View
 <!-- For State View slices, and any read model this slice produces or feeds. -->
 - **View:** `{{View Name}}` built from events: {{"Event A", "Event B"}}
-- **Consumed by:** {{which UI screen or automation}}
+- **Consumed by:** {{which UI screen, reaction, or read translation}}
+<!-- "Consumed by" is required, not optional. A read model nothing displays or watches is
+     information projected out of the system and then dropped, and `em validate` warns. Every
+     instance of a repeated view needs its own consumer, not just the last one. -->
 - **Freshness / consistency expectation:** {{real-time | eventual | on-demand}}
 
 ## Invariants / Business Rules

package/.claude/skills/event-modeling/templates/state.md

@@ -10,6 +10,7 @@ Keep it current at the end of every working session.
 - **Current phase:** {{extract | discover | model | slice}}
 - **Current step:** {{1–7, see methodology; or extraction round R1–R7}}
 - **Last updated:** {{YYYY-MM-DD}}
+- **Last conformance:** {{YYYY-MM-DD @ <target-repo revision> — report: conformance/<date>-report.md | never}}
 
 ## Session inputs
 - **Scope line:** {{one-line description of what's in/out of bounds for this model}}

package/README.md

@@ -28,6 +28,14 @@ em watch model.em --serve # live browser view, re-renders on every save
 em validate model.em      # check event-modeling rules
 ```
 
+Once a model is real and committed, `em` keeps working on it over time:
+
+```bash
+em export model.em        # versioned JSON, for agents and tooling
+em diff model.em --from HEAD~1   # what this change did to the model
+em changelog model.em     # the model's git history as a business ledger
+```
+
 A model is a list of slices — vertical time steps, read left to right — whose elements land
 in swimlane rows:
 
@@ -50,7 +58,9 @@ slice "View Open Orders" {
 ```
 
 The [tutorial](docs/tutorial.md) builds a complete model from an empty file in about twenty
-minutes.
+minutes, and [docs/workflow.md](docs/workflow.md) picks up where it leaves off: how a model
+gets specified, gated in CI, handed to implementation, and checked against the code that
+implements it.
 
 ## Model with AI
 
@@ -61,8 +71,10 @@ the questions, you supply the domain, and the model renders live as it grows.
 em skill install          # copy the skill into .claude/skills/event-modeling/
 ```
 
-Then run `/event-modeling` in Claude Code. See [docs/ai-workflow.md](docs/ai-workflow.md)
-for the phases and what a session produces, and the
+Then run `/event-modeling` in Claude Code. The same skill also runs the reverse direction:
+`extract` derives a model from a system that already exists, and `conform` checks a model
+against the code implementing it and reports where they've drifted. See
+[docs/ai-workflow.md](docs/ai-workflow.md) for the phases and what a session produces, and the
 [em-with-ai repository](https://github.com/milehimikey/em-with-ai) for a ~50-slice model
 built this way.
 
@@ -71,11 +83,12 @@ built this way.
 | Doc | What it answers |
 |---|---|
 | [docs/tutorial.md](docs/tutorial.md) | Learn the tool by building a model from scratch |
+| [docs/workflow.md](docs/workflow.md) | The model lifecycle: specify, gate, hand off, track change, detect drift |
 | [docs/patterns.md](docs/patterns.md) | The four Event Modeling patterns and their DSL shapes |
 | [docs/dsl.md](docs/dsl.md) | Full DSL reference: keywords, `from`, `again`, fields, notes |
 | [docs/cli.md](docs/cli.md) | Every command and flag |
 | [docs/validation.md](docs/validation.md) | Every rule `em validate` checks, and the fixes |
-| [docs/ci.md](docs/ci.md) | Copy-paste GitHub Actions recipe: validate `.em` changes in CI |
+| [docs/ci.md](docs/ci.md) | Copy-paste CI recipes: validate `.em` changes, run conformance on a schedule |
 | [docs/timeline.md](docs/timeline.md) | The Two Laws of the Timeline |
 | [docs/ai-workflow.md](docs/ai-workflow.md) | The Claude Code skill: install, phases, artifacts |
 | [docs/dependencies.md](docs/dependencies.md) | What's bundled vs. what needs a system install |

package/dist/cli/changelog-git.d.ts

@@ -0,0 +1,53 @@
+import { GitRunner } from "./diff-inputs.js";
+export interface CommitInfo {
+    /** Full commit hash — what `readFileAtCommit`/`git show` reads content at. */
+    hash: string;
+    shortHash: string;
+    /** YYYY-MM-DD author date (`--date=short`). */
+    date: string;
+    subject: string;
+    /**
+     * Repo-relative path of the file AS OF this commit, taken from the same
+     * `git log --follow --name-only` walk — pre-rename commits carry the old
+     * path, the one `git show <hash>:<path>` can actually read.
+     */
+    path: string;
+}
+export type CommitsResult = {
+    ok: true;
+    repoRoot: string;
+    commits: CommitInfo[];
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * List every commit that touched `file` (rename-following via `--follow`),
+ * oldest -> newest, each carrying the file's path as of that commit.
+ *
+ * `--from`/`--to` bound the walk **inclusive of both boundary commits**: the
+ * range compiles to `<from>^..<to>` (git's standard idiom for an
+ * inclusive-from range), so `--from` itself is the oldest commit in the
+ * output and `--to` the newest. `--to` defaults to `HEAD`. `--from` on a
+ * root commit (no parent to exclude) falls back to an unbounded walk up to
+ * `<to>`, which is equivalent — there's nothing before a root commit to
+ * exclude anyway.
+ */
+export declare function listModelCommits(file: string, opts?: {
+    from?: string;
+    to?: string;
+}, runGit?: GitRunner): CommitsResult;
+/** File content at a commit, or a note-ready `message` (no command prefix — it lands inside a changelog section). */
+export type FileAtCommitResult = {
+    ok: true;
+    content: string;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Read the model's content at `commit`, using `commit.path` — the path the
+ * file had AT that commit — so reads keep working across renames, where the
+ * current path doesn't exist in older revisions.
+ */
+export declare function readFileAtCommit(repoRoot: string, commit: CommitInfo, runGit?: GitRunner): FileAtCommitResult;

package/dist/cli/changelog-git.js

@@ -0,0 +1,112 @@
+// SPDX-License-Identifier: MIT
+// Git interaction for `em changelog`, isolated like diff-inputs.ts: listing
+// the commits that touched a model file and reading a revision's content
+// (`readFileAtCommit`) are the only impure operations here — everything
+// formattable/parseable (markdown assembly, decisions parsing) lives in
+// ../emit/changelog.ts, unit-tested without git.
+import { dirname, resolve } from "node:path";
+import { realGit } from "./diff-inputs.js";
+// A control character, not a valid character in a commit subject — safe as a
+// field separator in `git log --format`.
+const FS = "\x01";
+/**
+ * List every commit that touched `file` (rename-following via `--follow`),
+ * oldest -> newest, each carrying the file's path as of that commit.
+ *
+ * `--from`/`--to` bound the walk **inclusive of both boundary commits**: the
+ * range compiles to `<from>^..<to>` (git's standard idiom for an
+ * inclusive-from range), so `--from` itself is the oldest commit in the
+ * output and `--to` the newest. `--to` defaults to `HEAD`. `--from` on a
+ * root commit (no parent to exclude) falls back to an unbounded walk up to
+ * `<to>`, which is equivalent — there's nothing before a root commit to
+ * exclude anyway.
+ */
+export function listModelCommits(file, opts = {}, runGit = realGit) {
+    const abs = resolve(file);
+    const toplevel = runGit(["-C", dirname(abs), "rev-parse", "--show-toplevel"]);
+    if (toplevel.status !== 0) {
+        return { ok: false, message: `em changelog: ${file} is not inside a git repository` };
+    }
+    const repoRoot = toplevel.stdout.trim();
+    const lsFiles = runGit(["-C", repoRoot, "ls-files", "--full-name", "--", abs]);
+    const relPath = lsFiles.stdout.trim().split("\n")[0];
+    if (!relPath) {
+        return { ok: false, message: `em changelog: ${file} is not tracked by git in ${repoRoot}` };
+    }
+    const upRev = opts.to ?? "HEAD";
+    if (opts.to) {
+        const verifyTo = runGit(["-C", repoRoot, "rev-parse", "--verify", "--end-of-options", opts.to]);
+        if (verifyTo.status !== 0) {
+            return { ok: false, message: `em changelog: unknown revision "${opts.to}" for --to` };
+        }
+    }
+    let range = upRev;
+    if (opts.from) {
+        const verifyFrom = runGit(["-C", repoRoot, "rev-parse", "--verify", "--end-of-options", opts.from]);
+        if (verifyFrom.status !== 0) {
+            return { ok: false, message: `em changelog: unknown revision "${opts.from}" for --from` };
+        }
+        const verifyParent = runGit(["-C", repoRoot, "rev-parse", "--verify", "--end-of-options", `${opts.from}^`]);
+        range = verifyParent.status === 0 ? `${opts.from}^..${upRev}` : upRev;
+    }
+    // --name-only prints, after each commit's format line, the file's path as
+    // of that commit (--follow makes that the historical, pre-rename path when
+    // applicable). core.quotepath=false keeps non-ASCII paths literal instead
+    // of octal-escaped, so the printed path is usable in `git show`.
+    const log = runGit([
+        "-C",
+        repoRoot,
+        "-c",
+        "core.quotepath=false",
+        "log",
+        "--follow",
+        "--name-only",
+        `--format=%H${FS}%h${FS}%ad${FS}%s`,
+        "--date=short",
+        range,
+        "--",
+        relPath,
+    ]);
+    if (log.status !== 0) {
+        return {
+            ok: false,
+            message: `em changelog: git log failed: ${(log.stderr || "").trim() || "unknown git error"}`,
+        };
+    }
+    // Output alternates: a format line (contains FS), a blank line, then the
+    // path line for that commit. A commit with no path line (e.g. a merge,
+    // whose file list git omits by default) falls back to the current path.
+    const commits = [];
+    for (const line of log.stdout.split("\n")) {
+        if (line.length === 0)
+            continue;
+        if (line.includes(FS)) {
+            const [hash, shortHash, date, ...subjectParts] = line.split(FS);
+            commits.push({ hash, shortHash, date, subject: subjectParts.join(FS), path: relPath });
+        }
+        else if (commits.length > 0) {
+            commits[commits.length - 1].path = line;
+        }
+    }
+    commits.reverse(); // git log is newest-first; changelog building wants oldest->newest
+    if (commits.length === 0) {
+        return { ok: false, message: `em changelog: no commits found for ${relPath} in the given range` };
+    }
+    return { ok: true, repoRoot, commits };
+}
+/**
+ * Read the model's content at `commit`, using `commit.path` — the path the
+ * file had AT that commit — so reads keep working across renames, where the
+ * current path doesn't exist in older revisions.
+ */
+export function readFileAtCommit(repoRoot, commit, runGit = realGit) {
+    const show = runGit(["-C", repoRoot, "show", `${commit.hash}:${commit.path}`]);
+    if (show.status !== 0) {
+        return {
+            ok: false,
+            message: `cannot read ${commit.path} at ${commit.shortHash}: ${(show.stderr || "").trim() || "unknown git error"}`,
+        };
+    }
+    return { ok: true, content: show.stdout };
+}
+//# sourceMappingURL=changelog-git.js.map

package/dist/cli/changelog-git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"changelog-git.js","sourceRoot":"","sources":["../../src/cli/changelog-git.ts"],"names":[],"mappings":"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"}