@milehimikey/em 1.6.1 → 1.7.1

package/dist/catalog/classify.d.ts

@@ -1,14 +1,13 @@
 import { Slice } from "../model/model.js";
 export type SlicePattern = "translation" | "automation" | "state-change" | "state-view" | "unclassified";
 /**
- * Classify a single slice by its element kinds. Known simplification, not a
- * bug: docs/patterns.md describes Automation and Translation as spanning
- * *two* slices — the reaction slice, then a following `command`+`event`
- * slice. That second slice has the exact same kind-signature as a State
- * Change slice, so per-slice classification reads it as State Change. This
- * matches "derived from which element kinds appear in the slice" and keeps
- * the classifier a pure function of one slice at a time; don't "fix" this by
- * trying to look at neighboring slices.
+ * Classify a single slice by its element kinds. A reaction (`translation`/
+ * `processor`/`automation`/`saga`) shares its slice with the command it
+ * triggers — see docs/patterns.md — so checking translation/automation kinds
+ * before command/event is what makes that combined slice read as Translation
+ * or Automation rather than State Change. A view the reaction reads via
+ * `from` lives in its own, earlier slice and classifies as State View on its
+ * own. Order matters for this reason; keep the reaction checks first.
  */
 export declare function classifySlicePattern(slice: Slice): SlicePattern;
 export declare function slicePatternLabel(pattern: SlicePattern): string;

package/dist/catalog/classify.js

@@ -6,14 +6,13 @@
 // checked in priority order (a slice can carry a translation and a view
 // together, for instance, so order matters).
 /**
- * Classify a single slice by its element kinds. Known simplification, not a
- * bug: docs/patterns.md describes Automation and Translation as spanning
- * *two* slices — the reaction slice, then a following `command`+`event`
- * slice. That second slice has the exact same kind-signature as a State
- * Change slice, so per-slice classification reads it as State Change. This
- * matches "derived from which element kinds appear in the slice" and keeps
- * the classifier a pure function of one slice at a time; don't "fix" this by
- * trying to look at neighboring slices.
+ * Classify a single slice by its element kinds. A reaction (`translation`/
+ * `processor`/`automation`/`saga`) shares its slice with the command it
+ * triggers — see docs/patterns.md — so checking translation/automation kinds
+ * before command/event is what makes that combined slice read as Translation
+ * or Automation rather than State Change. A view the reaction reads via
+ * `from` lives in its own, earlier slice and classifies as State View on its
+ * own. Order matters for this reason; keep the reaction checks first.
  */
 export function classifySlicePattern(slice) {
     const kinds = new Set(slice.elements.map((el) => el.kind));

package/dist/catalog/classify.js.map

@@ -1 +1 @@
-{"version":3,"file":"classify.js","sourceRoot":"","sources":["../../src/catalog/classify.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,yEAAyE;AACzE,sEAAsE;AACtE,yEAAyE;AACzE,0EAA0E;AAC1E,wEAAwE;AACxE,6CAA6C;AAM7C;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAY;IAC/C,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3D,IAAI,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC;QAAE,OAAO,aAAa,CAAC;IACnD,IAAI,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC;QAAE,OAAO,YAAY,CAAC;IAChG,IAAI,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC;QAAE,OAAO,cAAc,CAAC;IACtE,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC;QAAE,OAAO,YAAY,CAAC;IAC3C,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAqB;IACrD,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,aAAa;YAChB,OAAO,aAAa,CAAC;QACvB,KAAK,YAAY;YACf,OAAO,YAAY,CAAC;QACtB,KAAK,cAAc;YACjB,OAAO,cAAc,CAAC;QACxB,KAAK,YAAY;YACf,OAAO,YAAY,CAAC;QACtB,KAAK,cAAc;YACjB,OAAO,cAAc,CAAC;IAC1B,CAAC;AACH,CAAC"}
+{"version":3,"file":"classify.js","sourceRoot":"","sources":["../../src/catalog/classify.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,yEAAyE;AACzE,sEAAsE;AACtE,yEAAyE;AACzE,0EAA0E;AAC1E,wEAAwE;AACxE,6CAA6C;AAM7C;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAY;IAC/C,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3D,IAAI,KAAK,CAAC,GAAG,CAAC,aAAa,CAAC;QAAE,OAAO,aAAa,CAAC;IACnD,IAAI,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC;QAAE,OAAO,YAAY,CAAC;IAChG,IAAI,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC;QAAE,OAAO,cAAc,CAAC;IACtE,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC;QAAE,OAAO,YAAY,CAAC;IAC3C,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAAqB;IACrD,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,aAAa;YAChB,OAAO,aAAa,CAAC;QACvB,KAAK,YAAY;YACf,OAAO,YAAY,CAAC;QACtB,KAAK,cAAc;YACjB,OAAO,cAAc,CAAC;QACxB,KAAK,YAAY;YACf,OAAO,YAAY,CAAC;QACtB,KAAK,cAAc;YACjB,OAAO,cAAc,CAAC;IAC1B,CAAC;AACH,CAAC"}

package/dist/catalog/docJoin.d.ts

@@ -0,0 +1,39 @@
+import { Slice } from "../model/model.js";
+import { Diagnostic } from "../model/validate.js";
+import { DriftSignalKind } from "./driftSignal.js";
+import { SliceRef } from "./sliceDoc.js";
+export type DocReason = "no-doc-bound" | "binding-missing-file" | "frontmatter-invalid" | null;
+/** A slice's export-facing doc join — always a non-null object (never JSON `null`), matching
+ *  every other optional field in `em export`'s style: explicit-null-on-a-stable-key, never a
+ *  nullable wrapper. `reason` is null exactly when `found` is true and the frontmatter parsed
+ *  cleanly; otherwise it names which of the three broken states applies. */
+export interface SliceDocExport {
+    found: boolean;
+    /** The conventional path (`slices/<sliceKey>.md`), always present regardless of `found` —
+     *  the path a doc would need to exist at, and (when `found`) the path it was read from. */
+    path: string;
+    reason: DocReason;
+    status: string | null;
+    version: number | null;
+    implementedIn: string | null;
+    splitFrom: SliceRef | null;
+    mergedFrom: SliceRef[];
+    supersededBy: SliceRef[];
+    /** Implementation-drift classification (MIL-85), from `status`+`implementedIn` alone — see
+     *  catalog/driftSignal.ts. Null only when `found` is false (nothing to classify); paired with
+     *  `version` above from the same doc parse — a finding built from `driftSignal` should always
+     *  cite `version` alongside it, never cache one without the other. */
+    driftSignal: DriftSignalKind | null;
+}
+export interface SliceDocJoinResult {
+    doc: SliceDocExport;
+    diagnostics: Diagnostic[];
+}
+/**
+ * Resolve one slice's doc join. `baseDir` is the `.em` file's directory (doc paths, like note
+ * paths everywhere else in em, are relative to it). `sliceRef`/`elementRefOf` supply the
+ * export-stable refs (from the same `computeRefs()` result `em export`'s per-element/slice
+ * entries use) so the returned diagnostics point at the same identities every other export
+ * diagnostic does — never a second identifier scheme.
+ */
+export declare function resolveSliceDocJoin(slice: Slice, sliceKey: string, baseDir: string, elementRefOf: (id: string) => string): SliceDocJoinResult;

package/dist/catalog/docJoin.js

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: MIT
+// The `em export` slice-doc join (MIL-91): for each slice, resolve whether a design doc was
+// declared, found, and well-formed, and if so pull its canonical frontmatter fields into the
+// export JSON. Used ONLY by `em export` (src/emit/json.ts) — `em catalog`'s own doc lookup
+// (catalog/build.ts) deliberately keeps its simpler existsSync+parseSliceDoc convention: it
+// has a standing tested invariant that catalog's doc discovery ignores `note` entirely
+// (test/catalog.e2e.test.ts), and doesn't need this module's 3-state reason granularity. The
+// underlying read (`readSliceDoc.ts`) is shared with `em diff`'s lineage annotation
+// (model/diff.ts) and `em validate`'s lineage-ref resolution (catalog/lineageValidate.ts,
+// MIL-84) — this module's `note`-binding gate and 3-state `DocReason` stay export-specific.
+//
+// Three states (MIL-91): the `note "slices/<name>.md"` binding on an element is the
+// load-bearing fact — binding a note IS the ratified declaration that a doc should exist. No
+// note binding is a normal, unremarkable state (a slice that hasn't reached specify yet); a
+// binding pointing at a missing file, or a doc whose frontmatter is missing or malformed, are
+// both broken-contract states and warn.
+import { makeDiag } from "../model/rules.js";
+import { classifyImplementationDrift } from "./driftSignal.js";
+import { readSliceDoc } from "./readSliceDoc.js";
+import { hasUsableFrontmatter } from "./sliceDoc.js";
+const EMPTY_CONTENT = {
+    status: null,
+    version: null,
+    implementedIn: null,
+    splitFrom: null,
+    mergedFrom: [],
+    supersededBy: [],
+    driftSignal: null,
+};
+/**
+ * Resolve one slice's doc join. `baseDir` is the `.em` file's directory (doc paths, like note
+ * paths everywhere else in em, are relative to it). `sliceRef`/`elementRefOf` supply the
+ * export-stable refs (from the same `computeRefs()` result `em export`'s per-element/slice
+ * entries use) so the returned diagnostics point at the same identities every other export
+ * diagnostic does — never a second identifier scheme.
+ */
+export function resolveSliceDocJoin(slice, sliceKey, baseDir, elementRefOf) {
+    const path = `slices/${sliceKey}.md`;
+    const boundEls = slice.elements.filter((el) => el.note === path);
+    if (boundEls.length === 0) {
+        return { doc: { found: false, path, reason: "no-doc-bound", ...EMPTY_CONTENT }, diagnostics: [] };
+    }
+    const parsed = readSliceDoc(baseDir, sliceKey);
+    if (!parsed) {
+        return {
+            doc: { found: false, path, reason: "binding-missing-file", ...EMPTY_CONTENT },
+            diagnostics: [
+                makeDiag("binding-missing-file", {
+                    message: `slice "${slice.name}" notes "${path}" but no such file exists`,
+                    line: boundEls[0].line,
+                    refs: [sliceKey, ...boundEls.map((el) => elementRefOf(el.id))],
+                }),
+            ],
+        };
+    }
+    if (!hasUsableFrontmatter(parsed)) {
+        return {
+            doc: { found: true, path, reason: "frontmatter-invalid", ...EMPTY_CONTENT },
+            diagnostics: [
+                makeDiag("frontmatter-invalid", {
+                    message: parsed.frontmatterPresent
+                        ? `slice doc "${path}" is missing required frontmatter keys: ${parsed.missingRequiredFields.join(", ")}`
+                        : `slice doc "${path}" has no frontmatter block`,
+                    line: slice.line,
+                    refs: [sliceKey],
+                }),
+            ],
+        };
+    }
+    return {
+        doc: {
+            found: true,
+            path,
+            reason: null,
+            status: parsed.status,
+            version: parsed.version,
+            implementedIn: parsed.implementedIn,
+            splitFrom: parsed.splitFrom,
+            mergedFrom: parsed.mergedFrom,
+            supersededBy: parsed.supersededBy,
+            driftSignal: classifyImplementationDrift(parsed),
+        },
+        diagnostics: [],
+    };
+}
+//# sourceMappingURL=docJoin.js.map

package/dist/catalog/docJoin.js.map

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

package/dist/catalog/driftSignal.d.ts

@@ -0,0 +1,16 @@
+import { SliceDoc } from "./sliceDoc.js";
+export type DriftSignalKind = 
+/** status: implemented, implementedIn set — normal shipped state. */
+"in-sync"
+/** status not implemented, implementedIn absent — normal pre-ship state. */
+ | "never-implemented"
+/** status not implemented, implementedIn still set — a ratified delta hasn't shipped yet.
+ *  Expected, not a defect: never surface this as fresh drift or a validate diagnostic. */
+ | "unpropagated-delta"
+/** status: implemented, implementedIn absent — genuine incoherence (em validate warns). */
+ | "implemented-without-link";
+/**
+ * Classify a doc's status/implementedIn pair. Takes a `Pick` rather than the full `SliceDoc` so
+ * callers building a partial/synthetic doc (tests, future callers) don't need every field.
+ */
+export declare function classifyImplementationDrift(doc: Pick<SliceDoc, "status" | "implementedIn">): DriftSignalKind;

package/dist/catalog/driftSignal.js

@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: MIT
+// Classifies a slice doc's implementation-drift state from `status` + `implementedIn` alone
+// (MIL-85). Pure — same spirit as sliceDoc.ts itself: no fs, no model, no baseDir — so
+// `em export`'s doc join (catalog/docJoin.ts), `em validate`'s frontmatter-coherence check
+// (catalog/frontmatterCoherenceValidate.ts), and the conform skill (reading `em export --json`'s
+// `slice.doc.driftSignal`) all consume the exact same answer instead of re-deriving this
+// predicate three different ways.
+//
+// The load-bearing distinction (docs/slice-doc-schema.md, "`status` under re-ratification"):
+// re-ratifying a shipped slice flips `status` back off `implemented` while `implementedIn` keeps
+// naming the prior version's PR. That combination — `unpropagated-delta` — is the EXPECTED drift
+// signal, not staleness, and must never be flagged as incoherence. Only `implemented-without-link`
+// (status: implemented, no link at all) is a genuine coherence problem worth a diagnostic.
+/**
+ * Classify a doc's status/implementedIn pair. Takes a `Pick` rather than the full `SliceDoc` so
+ * callers building a partial/synthetic doc (tests, future callers) don't need every field.
+ */
+export function classifyImplementationDrift(doc) {
+    const hasLink = typeof doc.implementedIn === "string" && doc.implementedIn.trim().length > 0;
+    if (doc.status === "implemented")
+        return hasLink ? "in-sync" : "implemented-without-link";
+    return hasLink ? "unpropagated-delta" : "never-implemented";
+}
+//# sourceMappingURL=driftSignal.js.map

package/dist/catalog/driftSignal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driftSignal.js","sourceRoot":"","sources":["../../src/catalog/driftSignal.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,4FAA4F;AAC5F,uFAAuF;AACvF,2FAA2F;AAC3F,iGAAiG;AACjG,yFAAyF;AACzF,kCAAkC;AAClC,EAAE;AACF,6FAA6F;AAC7F,iGAAiG;AACjG,iGAAiG;AACjG,mGAAmG;AACnG,2FAA2F;AAe3F;;;GAGG;AACH,MAAM,UAAU,2BAA2B,CAAC,GAA+C;IACzF,MAAM,OAAO,GAAG,OAAO,GAAG,CAAC,aAAa,KAAK,QAAQ,IAAI,GAAG,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;IAC7F,IAAI,GAAG,CAAC,MAAM,KAAK,aAAa;QAAE,OAAO,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,0BAA0B,CAAC;IAC1F,OAAO,OAAO,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,mBAAmB,CAAC;AAC9D,CAAC"}

package/dist/catalog/frontmatterCoherenceValidate.d.ts

@@ -0,0 +1,8 @@
+import { NormalizedModel } from "../model/model.js";
+import { RefsResult } from "../model/refs.js";
+import { Diagnostic } from "../model/validate.js";
+/**
+ * Resolve every slice's doc and flag genuine status/implementedIn incoherence. `baseDir` is the
+ * `.em` file's directory (doc paths, like every other doc/note path in em, are relative to it).
+ */
+export declare function validateFrontmatterCoherence(model: NormalizedModel, refs: RefsResult, baseDir: string): Diagnostic[];

package/dist/catalog/frontmatterCoherenceValidate.js

@@ -0,0 +1,52 @@
+// SPDX-License-Identifier: MIT
+// `em validate`'s frontmatter-coherence check (MIL-85): warns when a slice doc's `status` and
+// `implementedIn` are genuinely incoherent — `status: implemented` with no `implementedIn` link
+// at all. Deliberately narrow: re-ratifying a shipped slice flips `status` back off
+// `implemented` while `implementedIn` keeps naming the prior version's PR (docs/slice-doc-
+// schema.md, "`status` under re-ratification") — that combination is the EXPECTED drift signal
+// of an unpropagated delta, not incoherence, and must stay silent here. See
+// catalog/driftSignal.ts for the shared classification this check (and `em export`'s
+// `slice.doc.driftSignal`) both read.
+//
+// Same fs-aware shape as catalog/lineageValidate.ts (MIL-84): a sibling module to
+// model/validate.ts, not folded into it, because resolving a slice's doc needs `baseDir`/fs
+// access that the rest of validate deliberately never touches.
+//
+// Requires usable frontmatter (`hasUsableFrontmatter()`, sliceDoc.ts) — the exact same gate
+// `em export`'s docJoin.ts uses for `frontmatter-invalid`, shared as one function precisely so
+// the two can't silently disagree on what counts as a readable doc. `implementedIn` is a
+// frontmatter-only key (MIL-90/91) with no legacy body-label form (MIL-86's accepted-input
+// dialect: `- **Status:** ...`, no frontmatter block), and every canonical field this check
+// reads is itself frontmatter-only — so a doc with no fence, or one missing any required key,
+// has nothing reliable enough to classify. Flagging it as incoherent would be a false positive
+// against a doc that's merely unreadable, not one that's actually incoherent; stay silent
+// rather than guess, matching export's classification of the same doc.
+import { pushDiag } from "../model/rules.js";
+import { classifyImplementationDrift } from "./driftSignal.js";
+import { readSliceDoc } from "./readSliceDoc.js";
+import { hasUsableFrontmatter } from "./sliceDoc.js";
+/**
+ * Resolve every slice's doc and flag genuine status/implementedIn incoherence. `baseDir` is the
+ * `.em` file's directory (doc paths, like every other doc/note path in em, are relative to it).
+ */
+export function validateFrontmatterCoherence(model, refs, baseDir) {
+    const diags = [];
+    model.slices.forEach((slice, i) => {
+        const sliceKey = refs.sliceKeys[i];
+        const doc = readSliceDoc(baseDir, sliceKey);
+        if (!doc || !hasUsableFrontmatter(doc))
+            return;
+        const drift = classifyImplementationDrift(doc);
+        if (drift !== "implemented-without-link")
+            return;
+        // "unpropagated-delta" falls through here silently — that's the point: a re-ratified slice
+        // whose implementedIn still names prior work is expected, not a defect.
+        pushDiag(diags, "frontmatter-coherence-implemented-without-link", {
+            message: `slice "${sliceKey}" has status: implemented but no implementedIn link (v${doc.version ?? "?"})`,
+            line: slice.line,
+            refs: [sliceKey],
+        });
+    });
+    return diags;
+}
+//# sourceMappingURL=frontmatterCoherenceValidate.js.map

package/dist/catalog/frontmatterCoherenceValidate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatterCoherenceValidate.js","sourceRoot":"","sources":["../../src/catalog/frontmatterCoherenceValidate.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,8FAA8F;AAC9F,gGAAgG;AAChG,oFAAoF;AACpF,2FAA2F;AAC3F,+FAA+F;AAC/F,4EAA4E;AAC5E,qFAAqF;AACrF,sCAAsC;AACtC,EAAE;AACF,kFAAkF;AAClF,4FAA4F;AAC5F,+DAA+D;AAC/D,EAAE;AACF,4FAA4F;AAC5F,+FAA+F;AAC/F,yFAAyF;AACzF,2FAA2F;AAC3F,4FAA4F;AAC5F,8FAA8F;AAC9F,+FAA+F;AAC/F,0FAA0F;AAC1F,uEAAuE;AAKvE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,2BAA2B,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAErD;;;GAGG;AACH,MAAM,UAAU,4BAA4B,CAAC,KAAsB,EAAE,IAAgB,EAAE,OAAe;IACpG,MAAM,KAAK,GAAiB,EAAE,CAAC;IAE/B,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;QAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QACnC,MAAM,GAAG,GAAG,YAAY,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC5C,IAAI,CAAC,GAAG,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC;YAAE,OAAO;QAE/C,MAAM,KAAK,GAAG,2BAA2B,CAAC,GAAG,CAAC,CAAC;QAC/C,IAAI,KAAK,KAAK,0BAA0B;YAAE,OAAO;QACjD,2FAA2F;QAC3F,wEAAwE;QAExE,QAAQ,CAAC,KAAK,EAAE,gDAAgD,EAAE;YAChE,OAAO,EAAE,UAAU,QAAQ,yDAAyD,GAAG,CAAC,OAAO,IAAI,GAAG,GAAG;YACzG,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,IAAI,EAAE,CAAC,QAAQ,CAAC;SACjB,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/catalog/lineageValidate.d.ts

@@ -0,0 +1,9 @@
+import { NormalizedModel } from "../model/model.js";
+import { RefsResult } from "../model/refs.js";
+import { Diagnostic } from "../model/validate.js";
+/**
+ * Resolve every slice's lineage refs against the current tree and report what the current tree
+ * can prove wrong. `baseDir` is the `.em` file's directory (doc paths, like every other
+ * doc/note path in em, are relative to it).
+ */
+export declare function validateLineage(model: NormalizedModel, refs: RefsResult, baseDir: string): Diagnostic[];

package/dist/catalog/lineageValidate.js

@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: MIT
+// `em validate`'s lineage-ref resolution (MIL-84): checks what the *current tree* can prove
+// wrong about a slice doc's `split-from`/`merged-from`/`superseded-by` frontmatter, and stays
+// silent about what it can't. Ratified ruling (Linear MIL-84, 2026-08-13):
+//
+//   Backward lineage refs (`split-from`, `merged-from`) are claims about history; for
+//   rename/merge/remove the predecessor is *supposed* to be absent from the current tree —
+//   `merged-from: cart@v3` on a doc whose predecessor was legitimately removed references an
+//   absent key forever, that's steady state, not a defect. So a backward ref naming a key
+//   absent from the current model gets NO diagnostic, not even a warning.
+//
+//   What *is* checked (all errors, all current-tree-checkable): malformed ref grammar;
+//   self-reference/cycles; a dangling forward ref (`superseded-by` naming an absent key —
+//   forward refs point at the *present*, so absence is a real broken reference); impossible
+//   version arithmetic when the referenced key resolves in-tree (a ref to a version number
+//   higher than the target doc's own current `version:` — a reference to a future that hasn't
+//   happened).
+//
+// Deep historical verification (did slice@vN actually, once, exist?) is deliberately out of
+// scope here — a same-commit authoring convention substitutes for it (see
+// docs/slice-doc-schema.md's lineage section): the lineage ref is written in the same
+// ratification commit that performs the operation it records, so the PR diff already contains
+// both sides of the claim. `em ledger` (MIL-89, src/cli/ledgerCheck.ts) is that CI-recipe-tier,
+// two-revision shape for a related but different invariant — version:/content agreement, not
+// lineage-ref resolution — kept opt-in and separate for the same reason: it needs git history,
+// and this command stays a fast function of the current tree.
+import { pushDiag } from "../model/rules.js";
+import { readSliceDoc } from "./readSliceDoc.js";
+function edgesOf(ownerKey, ownerLine, doc) {
+    const edges = [];
+    if (doc.splitFrom)
+        edges.push({ ownerKey, ownerLine, field: "split-from", ref: doc.splitFrom });
+    for (const ref of doc.mergedFrom)
+        edges.push({ ownerKey, ownerLine, field: "merged-from", ref });
+    for (const ref of doc.supersededBy)
+        edges.push({ ownerKey, ownerLine, field: "superseded-by", ref });
+    return edges;
+}
+/**
+ * Resolve every slice's lineage refs against the current tree and report what the current tree
+ * can prove wrong. `baseDir` is the `.em` file's directory (doc paths, like every other
+ * doc/note path in em, are relative to it).
+ */
+export function validateLineage(model, refs, baseDir) {
+    const diags = [];
+    const inModel = new Set(refs.sliceKeys);
+    // Cache doc reads: a slice can be visited both as an edge owner and as another edge's
+    // resolved target, and there's no reason to read the same file twice.
+    const docCache = new Map();
+    const docFor = (sliceKey) => {
+        if (!docCache.has(sliceKey))
+            docCache.set(sliceKey, readSliceDoc(baseDir, sliceKey));
+        return docCache.get(sliceKey);
+    };
+    const edges = [];
+    model.slices.forEach((slice, i) => {
+        const sliceKey = refs.sliceKeys[i];
+        const doc = docFor(sliceKey);
+        if (doc)
+            edges.push(...edgesOf(sliceKey, slice.line, doc));
+    });
+    // Malformed grammar, self-reference, and dangling-forward are each a single edge-local check.
+    // Version arithmetic and cycles need every edge whose target resolves in-model, gathered
+    // first, so they're handled in a second pass below.
+    const resolvableEdges = [];
+    for (const edge of edges) {
+        if (edge.ref.sliceKey === null) {
+            pushDiag(diags, "lineage-ref-malformed", {
+                message: `slice "${edge.ownerKey}"'s ${edge.field} value "${edge.ref.raw}" doesn't match the <slice-key>@v<N> grammar`,
+                line: edge.ownerLine,
+                refs: [edge.ownerKey],
+            });
+            continue;
+        }
+        if (edge.ref.sliceKey === edge.ownerKey) {
+            pushDiag(diags, "lineage-ref-cycle", {
+                message: `slice "${edge.ownerKey}"'s ${edge.field} names itself (${edge.ref.raw})`,
+                line: edge.ownerLine,
+                refs: [edge.ownerKey],
+            });
+            continue;
+        }
+        if (edge.field === "superseded-by" && !inModel.has(edge.ref.sliceKey)) {
+            pushDiag(diags, "lineage-forward-dangling", {
+                message: `slice "${edge.ownerKey}"'s superseded-by names "${edge.ref.sliceKey}", which isn't a slice in the current model`,
+                line: edge.ownerLine,
+                refs: [edge.ownerKey],
+            });
+            continue;
+        }
+        if (inModel.has(edge.ref.sliceKey))
+            resolvableEdges.push(edge);
+        // else: a backward ref (split-from/merged-from) naming a key absent from the current
+        // model — the expected steady state for a real split/merge/remove. No diagnostic.
+    }
+    // Version arithmetic: only checkable when the target resolves in-model AND its own doc has a
+    // readable numeric version. Silently skip otherwise — can't check what isn't there.
+    for (const edge of resolvableEdges) {
+        const targetDoc = docFor(edge.ref.sliceKey);
+        if (!targetDoc || targetDoc.version === null)
+            continue;
+        if (edge.ref.version > targetDoc.version) {
+            pushDiag(diags, "lineage-version-impossible", {
+                message: `slice "${edge.ownerKey}"'s ${edge.field} names "${edge.ref.sliceKey}"@v${edge.ref.version}, but "${edge.ref.sliceKey}" is only at v${targetDoc.version}`,
+                line: edge.ownerLine,
+                refs: [edge.ownerKey, edge.ref.sliceKey],
+            });
+        }
+    }
+    // Multi-node cycles: adjacency over edges whose target resolves in-model (self-loops already
+    // reported above, and excluded here so they aren't double-counted as a 1-node "cycle"). 3-color
+    // DFS, same shape as model/validate.ts's findTypeCycles(), adapted to string slice keys.
+    const adjacency = new Map();
+    for (const edge of resolvableEdges) {
+        if (edge.ref.sliceKey === edge.ownerKey)
+            continue;
+        const list = adjacency.get(edge.ownerKey);
+        if (list)
+            list.push(edge.ref.sliceKey);
+        else
+            adjacency.set(edge.ownerKey, [edge.ref.sliceKey]);
+    }
+    const color = new Map(); // 0 = white, 1 = gray (on stack), 2 = black (done)
+    const stack = [];
+    const reportedCycles = new Set();
+    const lineOf = new Map();
+    model.slices.forEach((slice, i) => lineOf.set(refs.sliceKeys[i], slice.line));
+    function visit(key) {
+        color.set(key, 1);
+        stack.push(key);
+        for (const dep of adjacency.get(key) ?? []) {
+            const c = color.get(dep) ?? 0;
+            if (c === 0) {
+                visit(dep);
+            }
+            else if (c === 1) {
+                const idx = stack.indexOf(dep);
+                const cyclePath = [...stack.slice(idx), dep];
+                const dedupeKey = [...new Set(cyclePath)].sort().join(",");
+                if (!reportedCycles.has(dedupeKey)) {
+                    reportedCycles.add(dedupeKey);
+                    const cycleRefs = [...new Set(cyclePath)];
+                    pushDiag(diags, "lineage-ref-cycle", {
+                        message: `slice "${dep}" is part of a lineage cycle: ${cyclePath.join(" -> ")}`,
+                        line: lineOf.get(dep),
+                        refs: cycleRefs,
+                    });
+                }
+            }
+            // c === 2 (black): already fully explored via another path — not a new cycle.
+        }
+        stack.pop();
+        color.set(key, 2);
+    }
+    for (const key of adjacency.keys()) {
+        if ((color.get(key) ?? 0) === 0)
+            visit(key);
+    }
+    return diags;
+}
+//# sourceMappingURL=lineageValidate.js.map

package/dist/catalog/lineageValidate.js.map

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

package/dist/catalog/readSliceDoc.d.ts

@@ -0,0 +1,2 @@
+import { SliceDoc } from "./sliceDoc.js";
+export declare function readSliceDoc(baseDir: string, sliceKey: string): SliceDoc | null;

package/dist/catalog/readSliceDoc.js

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: MIT
+// Lowest-level slice-doc read: given a base dir and a slice's export key,
+// read+parse `slices/<sliceKey>.md` if it exists. Never throws — a missing
+// file is routine (not every slice has reached specify yet), so this is a
+// plain `null`, not an exception or a diagnostic. Shared by `em export`'s
+// doc join (catalog/docJoin.ts, which additionally gates on a `note` binding
+// and produces export-shaped diagnostics for a *missing-but-bound* doc — a
+// concern this module doesn't have), `em diff`'s lineage annotation
+// (model/diff.ts, via cli.ts), and `em validate`'s lineage-ref resolution
+// (catalog/lineageValidate.ts) — three callers with different reactions to
+// "no doc here," so the read itself stays opinion-free.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseSliceDoc } from "./sliceDoc.js";
+export function readSliceDoc(baseDir, sliceKey) {
+    const path = join(baseDir, "slices", `${sliceKey}.md`);
+    if (!existsSync(path))
+        return null;
+    return parseSliceDoc(readFileSync(path, "utf8"));
+}
+//# sourceMappingURL=readSliceDoc.js.map

package/dist/catalog/readSliceDoc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readSliceDoc.js","sourceRoot":"","sources":["../../src/catalog/readSliceDoc.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAC/B,0EAA0E;AAC1E,2EAA2E;AAC3E,0EAA0E;AAC1E,0EAA0E;AAC1E,6EAA6E;AAC7E,2EAA2E;AAC3E,oEAAoE;AACpE,0EAA0E;AAC1E,2EAA2E;AAC3E,wDAAwD;AAExD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,aAAa,EAAY,MAAM,eAAe,CAAC;AAExD,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,QAAgB;IAC5D,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,GAAG,QAAQ,KAAK,CAAC,CAAC;IACvD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACnC,OAAO,aAAa,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;AACnD,CAAC"}

package/dist/catalog/sliceDoc.d.ts

@@ -1,10 +1,101 @@
+/** A parsed `<slice-key>@v<N>` lineage reference. */
+export interface SliceRef {
+    /** The exact frontmatter value this ref was read from, e.g. "checkout@v4".
+     *  Always present, even when the grammar didn't match — nothing is silently
+     *  dropped the way an unrecognized top-level key is. */
+    raw: string;
+    /** The referenced slice's doc key (its kebab-case filename stem), lowercased,
+     *  or null if `raw` doesn't match the `<slice-key>@v<N>` grammar. Whether
+     *  this actually names a real slice/version is NOT checked here — that's
+     *  MIL-84 (lineage-aware `em diff`/`em validate`). */
+    sliceKey: string | null;
+    /** The referenced version number, or null if `raw` didn't match the grammar. */
+    version: number | null;
+}
 export interface SliceDoc {
     /** The doc's raw markdown, as read from disk. */
     raw: string;
-    /** Lowercased value of the doc's `- **Status:** ...` line, or null if no such line is found
-     *  (a freeform doc that doesn't follow the slice.md template). */
+    /** The doc's body text — everything after the frontmatter fence (or the whole doc, if no
+     *  fence) — the same text `html`/`openQuestionsTotal` are already derived from. Exposed so a
+     *  two-revision content-agreement check (MIL-89, `em ledger`) can diff body text across git
+     *  revisions without frontmatter noise leaking in. */
+    body: string;
+    /** Lowercased status value from frontmatter `status:` (canonical) or a legacy
+     *  `- **Status:** ...` bullet line, or null if neither is found (a freeform
+     *  doc that doesn't follow the slice.md template). */
     status: string | null;
-    /** The whole doc rendered to HTML. */
+    /** This slice's own ratified-content version, from frontmatter `version:`
+     *  (e.g. `version: 1`) — a cache of git truth (docset module 06), not
+     *  derived or validated against git history. Null when absent or
+     *  non-numeric. Distinct from the frontmatter dialect's own `schemaVersion`,
+     *  which this parser still doesn't expose. */
+    version: number | null;
+    /** Lineage: this doc split off exactly one prior slice, from frontmatter
+     *  `split-from:`. Null when this doc wasn't produced by a split. */
+    splitFrom: SliceRef | null;
+    /** Lineage: this doc was produced by merging one or more prior slices, from
+     *  frontmatter `merged-from:` (comma-separated). Empty array when absent —
+     *  the common case. */
+    mergedFrom: SliceRef[];
+    /** Lineage: this doc has been superseded by one or more successor slices —
+     *  a rename, or the retired side of a split/merge — from frontmatter
+     *  `superseded-by:` (comma-separated). Empty array when absent — the
+     *  common case; most slices are never superseded. */
+    supersededBy: SliceRef[];
+    /** Frontmatter `implementedIn:` — free text, typically a PR/commit link — or null
+     *  when absent. No legacy bullet-line form, same as `version`/lineage. */
+    implementedIn: string | null;
+    /** True when a well-formed leading `---`/`---` frontmatter fence was found and
+     *  closed — independent of which keys it contained. False for a legacy
+     *  status-bullet-only doc, a doc with no frontmatter at all, or an
+     *  unterminated fence (splitFrontmatter() already treats that as "absent"). */
+    frontmatterPresent: boolean;
+    /** Which of REQUIRED_FRONTMATTER_KEYS were absent (or present-but-empty, which
+     *  the parser already treats as absent) from the frontmatter. Empty whenever
+     *  frontmatterPresent is false too — check frontmatterPresent separately to
+     *  distinguish "no frontmatter at all" from "every required key present".
+     *  Presence-only: doesn't validate `pattern`'s/`status`'s enum values, matching
+     *  this parser's existing lenient, informational treatment of those keys. */
+    missingRequiredFields: string[];
+    /** The whole doc rendered to HTML, with any leading frontmatter block stripped
+     *  first (otherwise its `---` fences render as stray <hr>s and the raw
+     *  `key: value` lines leak into the body). */
     html: string;
+    /** Count of GFM task-list items (`- [ ]` / `- [x]`) found under the `## Open Questions`
+     *  heading (case-insensitive), up to the next `#`/`##` heading or EOF. Both 0 when the doc
+     *  has no such heading — nothing for MIL-87's readiness check to block on. See
+     *  `openQuestionsUnchecked` for how many of these are still unresolved. */
+    openQuestionsTotal: number;
+    /** Of `openQuestionsTotal`, how many are still `- [ ]` (unchecked). 0 when every Open
+     *  Question has been checked off, or when there's no Open Questions section at all. */
+    openQuestionsUnchecked: number;
 }
+/** Frontmatter keys docs/slice-doc-schema.md's required-vs-optional table marks
+ *  required at every `status` — the mechanical basis for `frontmatter-invalid`
+ *  (MIL-91). `implementedIn` is deliberately excluded: its requirement depends on
+ *  whether the slice has *ever* reached `implemented`, which is git history this
+ *  parser has no access to and doesn't attempt to check. */
+export declare const REQUIRED_FRONTMATTER_KEYS: readonly ["schemaversion", "pattern", "swimlane", "status", "version"];
+/** True when a doc's frontmatter is well-formed enough to trust its canonical fields: a closed
+ *  fence was found AND every REQUIRED_FRONTMATTER_KEYS entry is present. The single gate `em
+ *  export`'s doc join (MIL-91, `frontmatter-invalid`) and `em validate`'s frontmatter-coherence
+ *  check (MIL-85) both call, instead of each re-deriving `!frontmatterPresent ||
+ *  missingRequiredFields.length > 0` and risking the two silently drifting apart on what counts
+ *  as "usable" as the required-fields list evolves. A doc that fails this — no fence at all
+ *  (e.g. MIL-86's legacy body-label dialect), or missing any required key — has nothing reliable
+ *  enough to classify; treat it as unreadable rather than guess. */
+export declare function hasUsableFrontmatter(doc: Pick<SliceDoc, "frontmatterPresent" | "missingRequiredFields">): boolean;
+/**
+ * Parses a single `<slice-key>@v<N>` lineage reference (`split-from`, and each
+ * comma-separated item of `merged-from`/`superseded-by`). Never throws: a
+ * value that doesn't match the grammar still comes back with the original
+ * text in `raw` and null `sliceKey`/`version`, so a malformed value stays
+ * visible — to a human reading the doc, or to MIL-84's validation — instead
+ * of being silently dropped like an unrecognized `status`. Exported so MIL-84
+ * (lineage diff/validate) and MIL-91 (export join) share this grammar instead
+ * of re-deriving it. `sliceKey` matches `kebabSlug()`'s output
+ * (src/util/slug.ts) — lowercase alphanumerics/hyphens, no assumption it
+ * starts with a letter.
+ */
+export declare function parseSliceRef(raw: string): SliceRef;
 export declare function parseSliceDoc(markdown: string): SliceDoc;