@milehimikey/em 1.17.0 → 1.18.1

package/dist/cli/upgrade.js

@@ -21,8 +21,9 @@
 // ci-block/constitution check needs. Requires the model directory to be inside a git
 // repository — same requirement `em conform-scope` holds, for the same reason (there is no
 // "changed since when" or "commit per step" without one).
-import { existsSync, readFileSync, realpathSync, rmSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, realpathSync, rmSync, mkdirSync, writeFileSync } from "node:fs";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { findRosterAbove, GRANDFATHERED_RATIFIER } from "../roster/roster.js";
 import { PUBLIC_SCALAR_TYPE_NAMES } from "../model/model.js";
 import { findUnresolvedPublicFieldTypes } from "../model/validate.js";
 import { realGit } from "./diff-inputs.js";
@@ -38,11 +39,17 @@ import { findSpecifyRoot, locateConstitution } from "./status.js";
 import { scaffoldConstitution, scaffoldStateFile } from "../templates.js";
 import { loadStateFile, parseState, setEmVersion, ensureOptionalBullets, resolveStateFilePath } from "./stateFile.js";
 import { fieldLineRegex, normalizeFieldValue, locateFrontmatterInner, replaceFieldValue } from "./frontmatterSurgery.js";
-import { ratifiedHashScope, sliceDocBodyHash } from "../catalog/sliceDoc.js";
-import { applyDeferOrAppend, drainQueueInState, finishSignedDocEdit, isSignedDoc, readQueue } from "./defer.js";
+import { parseSliceDoc, ratifiedHashScope, sliceDocBodyHash } from "../catalog/sliceDoc.js";
+import { applyDeferOrAppend, drainQueueInState, finishSignedDocEdit, isSignedDoc, readQueue, rewriteParkingLotFragments } from "./defer.js";
+import { runSliceSync } from "./sliceSync.js";
+import { runSliceIndex } from "./sliceIndex.js";
+import { planCollapseAlternativeEvents, planFoldContinuations, planStackContinuations } from "./upgradeReshape.js";
+import { observeSigners } from "../roster/init.js";
 import { STATE_FILE_NAME } from "./stateFile.js";
 import { localIsoDate } from "../util/localDate.js";
 import { compile } from "../pipeline.js";
+import { computeModelKey } from "../model/qualifiedRef.js";
+import { contractPathFor, generateContract } from "./api.js";
 import { hasErrors } from "../model/validate.js";
 import { LEGACY_SYSTEM_MANIFEST_SCHEMA_VERSION, parseManifest } from "../system/manifest.js";
 import { planManifestMigration } from "../system/migrateManifest.js";
@@ -277,7 +284,10 @@ function ciBlockFiles(args, ctx) {
         };
     }
     return {
-        ci: [buildCiWorkflowFile(args.model, args.testsDir, ctx.installedVersion), ciManagedBody(args.model, args.testsDir, ctx.installedVersion)],
+        ci: [
+            buildCiWorkflowFile(args.model, args.testsDir, ctx.installedVersion, findRosterAbove(dirname(resolve(ctx.repoRoot, args.model))) !== null),
+            ciManagedBody(args.model, args.testsDir, ctx.installedVersion, findRosterAbove(dirname(resolve(ctx.repoRoot, args.model))) !== null),
+        ],
         conform: [buildConformWorkflowFile(args.model, ctx.installedVersion, usePlugin), conformManagedBody(args.model, ctx.installedVersion, usePlugin)],
     };
 }
@@ -333,6 +343,82 @@ function applyCiBlock(ctx) {
     }
     return { ok: true, changedFiles };
 }
+/** Every model covered by an `api-check` job whose `contracts/<model key>.tsp` is absent. The job
+ *  counts when it is in the on-disk em-ci.yml OR when `ci-block` is pending (a stale block is
+ *  rewritten to the current preset, which carries `api-check` - so a pre-1.12 workflow is caught by
+ *  the dry run, not only after `--apply`). Models that can't be read or compile cleanly are
+ *  returned in `blocked` (never skipped silently). */
+function contractPlan(ctx) {
+    const none = { missing: [], blocked: [] };
+    const ciPath = ciWorkflowPath(ctx.repoRoot);
+    if (!existsSync(ciPath))
+        return none;
+    const text = readFileSync(ciPath, "utf8");
+    const plans = ciBlockPlans(ctx);
+    const hasJob = /^ {2}api-check(-[\w-]+)?:/m.test(text) || plans.ciStale;
+    if (!hasJob || !plans.args)
+        return none;
+    const paths = plans.args.models ? plans.args.models.map((m) => m.path) : [plans.args.model];
+    const missing = [];
+    const blocked = [];
+    for (const rel of paths) {
+        const modelFile = resolve(ctx.repoRoot, rel);
+        let source;
+        try {
+            source = readFileSync(modelFile, "utf8");
+        }
+        catch {
+            blocked.push({ model: rel, why: "the model file can't be read" });
+            continue;
+        }
+        try {
+            const compiled = compile(source);
+            if (hasErrors(compiled.diagnostics)) {
+                // Only blocked when the contract is actually absent (a model mid-edit that already has one is fine).
+                if (!existsSync(contractPathFor(modelFile, computeModelKey(compiled.model, modelFile))))
+                    blocked.push({ model: rel, why: "it has compile errors" });
+                continue;
+            }
+            const g = generateContract(modelFile, source, compiled);
+            if (!existsSync(g.contractPath))
+                missing.push({ modelFile, contractPath: g.contractPath, modelKey: g.modelKey });
+        }
+        catch (e) {
+            blocked.push({ model: rel, why: `it does not parse (${e.message})` });
+        }
+    }
+    return { missing, blocked };
+}
+function blockedText(blocked) {
+    return blocked.map((b) => `${b.model} (${b.why})`).join("; ");
+}
+function detectApiContractMissing(ctx) {
+    const { missing, blocked } = contractPlan(ctx);
+    if (missing.length === 0) {
+        if (blocked.length)
+            return { applicable: false, reason: `the api-check contract could not be generated for ${blockedText(blocked)} - see the api-contract-blocked item` };
+        return { applicable: false, reason: "no api-check job lacking its contracts/<model key>.tsp" };
+    }
+    const skipped = blocked.length ? `; not generated for ${blockedText(blocked)} (see the api-contract-blocked item)` : "";
+    return {
+        applicable: true,
+        reason: `the api-check job needs ${missing.map((m) => relative(ctx.repoRoot, m.contractPath)).join(", ")}, which ${missing.length === 1 ? "is" : "are"} missing - em upgrade will run em api generate${skipped}`,
+    };
+}
+function applyApiContractMissing(ctx) {
+    const { missing } = contractPlan(ctx);
+    if (missing.length === 0)
+        return { ok: false, message: "nothing to generate" };
+    const changedFiles = [];
+    for (const m of missing) {
+        const source = readFileSync(m.modelFile, "utf8");
+        const generated = generateContract(m.modelFile, source, compile(source));
+        mkdirSync(dirname(generated.contractPath), { recursive: true });
+        writeFileSync(generated.contractPath, generated.text);
+        changedFiles.push(generated.contractPath);
+    }
+    return { ok: true, changedFiles };
+}
 // ---- Step 5: constitution — scaffold a draft when absent and no .specify/ owns the slot. ----
 function detectConstitution(ctx) {
     const existing = locateConstitution(ctx.baseDir);
@@ -363,7 +449,7 @@ function applyConstitution(ctx) {
 // reratified doc has `version > 1` and is mid-sign-off, which only a human can resolve; see the
 // `ready-to-implement-no-ratifiedby` human item) with no `ratifiedBy`. A doc with no `version:`
 // at all is treated as version 1 (the schema's default). ----
-export const GRANDFATHERED_RATIFIER = "grandfathered (unsigned before em 1.14)";
+export { GRANDFATHERED_RATIFIER };
 /** Pure text transform: inserts the grandfather sign-off after the `status:` line, using only
  *  the key lines that are missing (a stray `ratifiedOn:` is kept as-is), in the file's own EOL.
  *  `null` when the doc isn't a candidate (no frontmatter/status, or `ratifiedBy` already set). */
@@ -547,6 +633,298 @@ function applyRatifiedHashScope(ctx) {
     }
     return { ok: true, changedFiles };
 }
+// ---- Step 8-: collapse-alternative-events (GH #290 / #278) and fold-continuations (GH #290 / #287) ----
+// The two steps that rewrite the `.em` itself (planned by upgradeReshape.ts: text surgery, verified by
+// recompiling before anything is written). They run before the doc/index steps, which re-read the
+// model `applyUpgrade` recompiles after each step. `fold-continuations` is OPT-IN (see below).
+function readModelText(ctx) {
+    return readFileSync(ctx.modelFile, "utf8");
+}
+function freshCompile(ctx) {
+    try {
+        const c = compile(readModelText(ctx));
+        return { model: c.model, refs: c.refs };
+    }
+    catch {
+        return null;
+    }
+}
+/** Signed docs (ratified or shipped) whose generated regions would be stale against `nextText`, i.e. that
+ *  a rewrite leaves behind a signature the regions no longer match. Read-only. */
+function signedDocsStaleAfter(ctx, nextText) {
+    const staleSigned = (src) => {
+        const out = new Map();
+        let c;
+        try {
+            c = compile(src);
+        }
+        catch {
+            return out;
+        }
+        const r = runSliceSync(c.model, c.refs, ctx.baseDir, undefined, true);
+        if (!r.ok)
+            return out;
+        for (const d of r.docs) {
+            if (d.status === "stale" && isSignedDoc(readFileSync(join(ctx.baseDir, d.path), "utf8"))) {
+                out.set(d.path, `${d.path} (${d.regions.filter((g) => g.status === "stale").map((g) => g.name).join(", ")})`);
+            }
+        }
+        return out;
+    };
+    const before = staleSigned(readModelText(ctx));
+    return [...staleSigned(nextText)].filter(([path]) => !before.has(path)).map(([, label]) => label); // newly stale only
+}
+const CARRIED_SECTIONS = /^##\s+(Scenarios|Invariants|Open Questions|Decisions(?: log)?)\s*$/i;
+/** Sections of a retiring doc whose AUTHORED content a human must carry to the kept doc (generated
+ *  regions are rebuilt from the model, so they are not content). */
+function carriedSections(raw) {
+    const body = raw.replace(/<!-- GENERATED:[^>]*:start[^>]*-->[\s\S]*?<!-- GENERATED:[^>]*:end -->/g, "");
+    const lines = body.split("\n");
+    const found = [];
+    for (let i = 0; i < lines.length; i++) {
+        const m = CARRIED_SECTIONS.exec(lines[i]);
+        if (!m)
+            continue;
+        let j = i + 1;
+        let content = false;
+        for (; j < lines.length && !/^#{1,2}\s/.test(lines[j]); j++)
+            if (lines[j].trim() !== "" && !lines[j].includes("{{"))
+                content = true;
+        if (content)
+            found.push(m[1]);
+    }
+    return found;
+}
+/** Where a collapsed slice's retired doc goes: beside the model, outside `slices/` (so it is not an
+ *  orphaned slice doc), keeping its file name. */
+const ARCHIVE_DIR = join("archive", "slices");
+function retiredDocs(ctx, groups) {
+    const out = [];
+    const refOf = elementRefOf(ctx);
+    const joinOf = (key) => {
+        const i = ctx.refs.sliceKeys.indexOf(key);
+        return i === -1 ? null : resolveSliceDocJoin(ctx.model, ctx.refs, ctx.model.slices[i], key, ctx.baseDir, refOf).doc;
+    };
+    for (const g of groups) {
+        const kept = joinOf(g.keys[0]);
+        const keptDoc = kept && kept.found && kept.reason === null ? kept.path : null;
+        const keptVersion = kept && keptDoc ? kept.version : null;
+        for (const key of g.keys.slice(1)) {
+            const bound = joinOf(key);
+            const rel = bound && bound.found && bound.reason === null ? bound.path : `slices/${key}.md`;
+            const from = join(ctx.baseDir, rel);
+            if (!existsSync(from) || (keptDoc !== null && rel === keptDoc))
+                continue;
+            const raw = readFileSync(from, "utf8");
+            const range = locateFrontmatterInner(raw);
+            const retiredVersion = Number(/^version:\s*(\d+)/m.exec(raw)?.[1] ?? "1");
+            const target = keptDoc !== null ? basename(keptDoc, ".md") : g.keys[0];
+            let next = raw;
+            if (range) {
+                const fenceEnd = raw.indexOf("\n", range.innerEnd) + 1 || raw.length;
+                const banner = `\n> **SUPERSEDED** by \`${target}\` (\`superseded-by\`): this slice was collapsed into one recording alternative events (GH #278). Kept for history; fold anything worth keeping into \`${keptDoc ?? `slices/${g.keys[0]}.md`}\`.\n`;
+                next = raw.slice(0, range.innerEnd) + `superseded-by: ${target}@v${keptVersion ?? 1}\n` + raw.slice(range.innerEnd, fenceEnd) + banner + raw.slice(fenceEnd);
+            }
+            out.push({ from, to: join(ctx.baseDir, ARCHIVE_DIR, basename(rel)), key, keptKey: g.keys[0], keptDoc, keptVersion, retiredVersion, text: next, carried: carriedSections(raw) });
+        }
+    }
+    return out;
+}
+function carriedNotes(retired) {
+    return retired.filter((r) => r.carried.length > 0).map((r) => `${ARCHIVE_DIR}/${basename(r.to)} holds ${r.carried.join(", ")} — fold these into ${r.keptDoc ?? `slices/${r.keptKey}.md`}`);
+}
+function detectCollapseAlternativeEvents(ctx) {
+    const fresh = freshCompile(ctx);
+    const plan = fresh ? planCollapseAlternativeEvents(fresh.model, fresh.refs, readModelText(ctx)) : null;
+    if (plan === null)
+        return { applicable: false, reason: "no run of adjacent slices repeats one command and differs only in the recorded event" };
+    const desc = plan.groups.map((g) => `${g.slices.map((n) => `"${n}"`).join(" + ")} → "${g.slices[0]}" recording ${g.form === "inline" ? g.events.join(" | ") : `oneof { ${g.events.join(", ")} }`}`);
+    const retired = retiredDocs(ctx, plan.groups);
+    const notes = carriedNotes(retired);
+    const stale = signedDocsStaleAfter(ctx, plan.next);
+    return {
+        applicable: true,
+        reason: `${plan.groups.length} run(s) of repeated-command slices collapse to alternative events: ${desc.join("; ")} — em upgrade will rewrite them (the first slice's key is kept; the others' docs move to ${ARCHIVE_DIR}/ with superseded-by and a SUPERSEDED banner, and the kept doc gains merged-from)` +
+            (notes.length > 0 ? `; ${notes.join("; ")}` : "") +
+            (stale.length > 0 ? `; signed doc(s) will not be synced and go stale: ${stale.join(", ")} — em slice revise <key>, then em slice sync` : ""),
+    };
+}
+/** Frontmatter-only edit: adds `key: value` before the closing fence (a no-op without frontmatter). */
+function addFrontmatterLine(raw, line) {
+    const range = locateFrontmatterInner(raw);
+    return range ? raw.slice(0, range.innerEnd) + line + "\n" + raw.slice(range.innerEnd) : raw;
+}
+function applyCollapseAlternativeEvents(ctx) {
+    const fresh = freshCompile(ctx);
+    const text = readModelText(ctx);
+    const plan = fresh ? planCollapseAlternativeEvents(fresh.model, fresh.refs, text) : null;
+    if (plan === null)
+        return { ok: false, message: "the model no longer collapses cleanly" };
+    const changed = [ctx.modelFile];
+    const retired = retiredDocs(ctx, plan.groups); // computed on the OLD model (joins, versions)
+    const notes = carriedNotes(retired);
+    writeFileSync(ctx.modelFile, plan.next, "utf8");
+    for (const r of retired) {
+        mkdirSync(dirname(r.to), { recursive: true });
+        writeFileSync(r.to, r.text, "utf8");
+        rmSync(r.from);
+        changed.push(r.from, r.to);
+    }
+    // Lineage back-link on the kept doc: `merged-from: <retired>@v<N>` (frontmatter only, outside the
+    // ratified hash). A SIGNED kept doc is not touched; `lineage-backlink-missing` lists it.
+    for (const r of retired) {
+        if (r.keptDoc === null)
+            continue;
+        const abs = join(ctx.baseDir, r.keptDoc);
+        const raw = readFileSync(abs, "utf8");
+        if (isSignedDoc(raw))
+            continue;
+        const ref = `${basename(r.to, ".md")}@v${r.retiredVersion}`;
+        const existing = /^merged-from:\s*(.*)$/m.exec(raw);
+        const next = existing ? raw.replace(/^merged-from:\s*(.*)$/m, (_m, v) => `merged-from: ${String(v).trim() === "" ? ref : `${String(v).trim()}, ${ref}`}`) : addFrontmatterLine(raw, `merged-from: ${ref}`);
+        writeFileSync(abs, next, "utf8");
+        if (!changed.includes(abs))
+            changed.push(abs);
+    }
+    // Regenerate the kept slice's event region (one `Records one of:` region now) unless its doc is signed
+    // (then `slice-doc-stale-signed` is the human item that says what to do).
+    const after = freshCompile(ctx);
+    if (after) {
+        for (const g of plan.groups) {
+            const kept = retired.find((r) => r.keptKey === g.keys[0])?.keptDoc ?? `slices/${g.keys[0]}.md`;
+            const doc = join(ctx.baseDir, kept);
+            if (existsSync(doc) && !isSignedDoc(readFileSync(doc, "utf8"))) {
+                const r = runSliceSync(after.model, after.refs, ctx.baseDir, g.keys[0], false);
+                if (r.ok && r.docs.some((d) => d.status === "synced") && !changed.includes(doc))
+                    changed.push(doc);
+            }
+        }
+    }
+    return { ok: true, changedFiles: changed, notes };
+}
+// ---- fold-continuations is OPT-IN (`em upgrade --apply --fold-continuations`) ----
+// Default form (a): consecutive continuations of ONE view stack into the first slice (its key, name,
+// `continuationOf`, doc join and index row stay). `--to-sugar` instead moves them into the host
+// command slice as `view X again … shown on` lines; that CHANGES `continuationOf` and the doc join to
+// the host (`<host>--again`) and removes the index rows.
+const FOLD_FLAG = "em upgrade --apply --fold-continuations";
+function foldPlan(ctx) {
+    const fresh = freshCompile(ctx);
+    if (!fresh)
+        return { kind: "stack", plan: null };
+    const text = readModelText(ctx);
+    return ctx.toSugar === true
+        ? { kind: "sugar", plan: planFoldContinuations(fresh.model, fresh.refs, text) }
+        : { kind: "stack", plan: planStackContinuations(fresh.model, fresh.refs, text) };
+}
+function detectFoldContinuations(ctx) {
+    const f = foldPlan(ctx);
+    if (f.plan === null)
+        return { applicable: false, reason: "no consecutive hand-named continuation slices of one view (stack) — or, with --to-sugar, no continuation directly after its host command — in a foldable shape" };
+    if (f.kind === "sugar" && f.plan.groups.length === 0) {
+        const r = f.plan.refused;
+        return { applicable: false, reason: `--to-sugar: nothing folded; refused: ${r.map((x) => `${x.hostKey} (${x.reason})`).join("; ")}` };
+    }
+    const optIn = ctx.foldContinuations === true || ctx.toSugar === true;
+    const prefix = optIn ? "" : `OPT-IN, not applied by a plain --apply (run \`${FOLD_FLAG}\`): `;
+    const stale = signedDocsStaleAfter(ctx, f.plan.next);
+    const staleNote = stale.length > 0 ? `; signed doc(s) whose generated regions (e.g. the view's \`via\` annotations) go stale and will not be synced: ${stale.join(", ")} — em slice revise <key>, then em slice sync` : "";
+    if (f.kind === "stack") {
+        const p = f.plan;
+        const desc = p.groups.map((g) => `${[g.kept, ...g.dropped].map((n) => `"${n}"`).join(" + ")} → one continuation slice "${g.kept}" (key ${g.keptKey} kept; dropped keys: ${g.droppedKeys.join(", ")})`);
+        const skipped = p.skipped.length > 0 ? `; left unstacked: ${p.skipped.map((s) => `${s.key} (${s.reason})`).join(", ")}` : "";
+        return { applicable: true, reason: `${prefix}${desc.join("; ")} — continuationOf, the doc join and the kept key's index row are unchanged${skipped}${staleNote}` };
+    }
+    const p = f.plan;
+    const desc = p.groups.map((g) => `${g.folded.map((n) => `"${n}"`).join(" + ")} (keys ${g.foldedKeys.join(", ")}) → \`view … again\` lines in "${g.host}" (column ${g.hostKey}--again)`);
+    const refusedNote = p.refused.length > 0 ? `; refused: ${p.refused.map((x) => `${x.hostKey} (${x.reason})`).join("; ")}` : "";
+    return { applicable: true, reason: `${prefix}--to-sugar: ${desc.join("; ")}${refusedNote} — CHANGES continuationOf and the doc join to the host (${p.groups.map((g) => `${g.hostKey}--again`).join(", ")}) and removes the index rows of ${p.groups.flatMap((g) => g.foldedKeys).join(", ")} (a stray own doc of a folded slice is left alone)${staleNote}` };
+}
+function applyFoldContinuations(ctx) {
+    const f = foldPlan(ctx);
+    if (f.plan === null || ("groups" in f.plan && f.plan.groups.length === 0))
+        return { ok: false, message: "the model no longer folds cleanly" };
+    writeFileSync(ctx.modelFile, f.plan.next, "utf8");
+    return { ok: true, changedFiles: [ctx.modelFile] };
+}
+function staleViewDocs(ctx) {
+    const open = [];
+    const signed = [];
+    const r = runSliceSync(ctx.model, ctx.refs, ctx.baseDir, undefined, true);
+    if (!r.ok)
+        return { open, signed };
+    for (const d of r.docs) {
+        if (d.status !== "stale" || !d.regions.some((g) => g.status === "stale" && g.name.startsWith("em-slice-view")))
+            continue;
+        (isSignedDoc(readFileSync(join(ctx.baseDir, d.path), "utf8")) ? signed : open).push({ key: d.key, path: d.path });
+    }
+    return { open, signed };
+}
+function detectViewDocSourcesStale(ctx) {
+    const { open, signed } = staleViewDocs(ctx);
+    const left = signed.length > 0 ? `; left alone (ratified or shipped — em slice revise, then em slice sync): ${signed.map((d) => d.path).join(", ")}` : "";
+    if (open.length === 0) {
+        return { applicable: false, reason: `no bound slice doc's view region is stale against the model${left}` };
+    }
+    return {
+        applicable: true,
+        reason: `em slice sync --check would change the view region of ${open.length} doc(s): ${open.map((d) => d.path).join(", ")} — em upgrade will run em slice sync on them${left}`,
+    };
+}
+function applyViewDocSourcesStale(ctx) {
+    const { open } = staleViewDocs(ctx);
+    const changedFiles = [];
+    for (const d of open) {
+        const r = runSliceSync(ctx.model, ctx.refs, ctx.baseDir, d.key, false);
+        if (!r.ok)
+            return { ok: false, message: r.message };
+        changedFiles.push(join(ctx.baseDir, d.path));
+    }
+    return { ok: true, changedFiles };
+}
+// ---- Step 8b: slice-index-stale (GH #290 / #275) — the README Slices table. ----
+function detectSliceIndexStale(ctx) {
+    const r = runSliceIndex(ctx.model, ctx.refs, ctx.modelFile, true);
+    if (r.ok)
+        return { applicable: false, reason: "the README Slices table is current" };
+    if (r.kind === "stale")
+        return { applicable: true, reason: `${join(ctx.baseDir, "README.md")}'s Slices table is stale (em slice index --check) — em upgrade will regenerate it` };
+    return { applicable: false, reason: r.kind === "missing-readme" ? "no README.md beside the model — nothing to index" : "README.md has no GENERATED:slices markers — nothing to index" };
+}
+function applySliceIndexStale(ctx) {
+    const r = runSliceIndex(ctx.model, ctx.refs, ctx.modelFile, false);
+    if (!r.ok)
+        return { ok: false, message: r.message };
+    return { ok: true, changedFiles: r.wrote ? [r.readmePath] : [] };
+}
+// ---- Step 8c: parking-lot-fragments (GH #290 / #283) — substring bullets become the item's label. ----
+function parkingLotDocs(ctx) {
+    const docs = new Map();
+    for (const d of nonContinuationDocs(ctx)) {
+        const file = join(ctx.baseDir, d.path);
+        if (d.path !== "" && existsSync(file))
+            docs.set(d.key, readFileSync(file, "utf8"));
+    }
+    return docs;
+}
+function detectParkingLotFragments(ctx) {
+    const statePath = join(ctx.baseDir, STATE_FILE_NAME);
+    if (!existsSync(statePath))
+        return { applicable: false, reason: `no ${STATE_FILE_NAME} beside the model` };
+    const { rewrites } = rewriteParkingLotFragments(readFileSync(statePath, "utf8"), parkingLotDocs(ctx));
+    if (rewrites.length === 0)
+        return { applicable: false, reason: "no parking-lot bullet is a fragment of an Open Questions item" };
+    return {
+        applicable: true,
+        reason: `${rewrites.length} parking-lot bullet(s) hold a fragment of an Open Questions item (the pre-1.18 em slice defer shape): ${rewrites.map((r) => `"${r.from}" → "${r.to}"`).join("; ")} — em upgrade will rewrite each to the item's label`,
+    };
+}
+function applyParkingLotFragments(ctx) {
+    const statePath = join(ctx.baseDir, STATE_FILE_NAME);
+    const { content } = rewriteParkingLotFragments(readFileSync(statePath, "utf8"), parkingLotDocs(ctx));
+    writeFileSync(statePath, content, "utf8");
+    return { ok: true, changedFiles: [statePath] };
+}
 // ---- Step 8: system-manifest (MIL-235, R3) — system.yaml 1.0 -> 2.0. ----
 // The one mechanical step that writes OTHER models' files: the legacy manifest's seams become
 // `consumes` clauses on each consuming translation and its owners become `owner "…"` on each
@@ -645,9 +1023,15 @@ export const UPGRADE_STEPS = [
     { id: "reaction-shape", sinceVersion: "1.8.0", detect: detectReactionShape, apply: applyReactionShape },
     { id: "state-file", sinceVersion: "1.13.0", detect: detectStateFile, apply: applyStateFile },
     { id: "ci-block", sinceVersion: "1.9.0", detect: detectCiBlock, apply: applyCiBlock },
+    { id: "api-contract-missing", sinceVersion: "1.18.1", detect: detectApiContractMissing, apply: applyApiContractMissing },
     { id: "constitution", sinceVersion: "1.11.0", detect: detectConstitution, apply: applyConstitution },
     { id: "ratified-signoff", sinceVersion: "1.14.0", detect: detectRatifiedSignoff, apply: applyRatifiedSignoff },
     { id: "ratified-hash-scope", sinceVersion: "1.17.0", detect: detectRatifiedHashScope, apply: applyRatifiedHashScope },
+    { id: "collapse-alternative-events", sinceVersion: "1.18.0", detect: detectCollapseAlternativeEvents, apply: applyCollapseAlternativeEvents },
+    { id: "fold-continuations", sinceVersion: "1.18.0", detect: detectFoldContinuations, apply: applyFoldContinuations, optedIn: (c) => c.foldContinuations === true || c.toSugar === true },
+    { id: "view-doc-sources-stale", sinceVersion: "1.18.0", detect: detectViewDocSourcesStale, apply: applyViewDocSourcesStale },
+    { id: "slice-index-stale", sinceVersion: "1.18.0", detect: detectSliceIndexStale, apply: applySliceIndexStale },
+    { id: "parking-lot-fragments", sinceVersion: "1.18.0", detect: detectParkingLotFragments, apply: applyParkingLotFragments },
     { id: "system-manifest", sinceVersion: "1.14.0", detect: detectSystemManifest, apply: applySystemManifest },
 ];
 function elementRefOf(ctx) {
@@ -780,6 +1164,111 @@ function detectPluginInstallLocally(ctx) {
     }
     return null;
 }
+/** GH #290: a SIGNED doc (ratified or shipped) whose generated regions are stale against the model —
+ *  `view-doc-sources-stale` and `collapse-alternative-events` leave it alone because syncing would move
+ *  its `ratifiedHash`. Raised for any region (view, event, command, invariants). */
+function detectSliceDocStaleSigned(ctx) {
+    const r = runSliceSync(ctx.model, ctx.refs, ctx.baseDir, undefined, true);
+    if (!r.ok)
+        return null;
+    const docs = r.docs.filter((d) => d.status === "stale" && isSignedDoc(readFileSync(join(ctx.baseDir, d.path), "utf8")));
+    if (docs.length === 0)
+        return null;
+    return {
+        id: "slice-doc-stale-signed",
+        reason: `${docs.map((d) => `${d.path} (${d.regions.filter((g) => g.status === "stale").map((g) => g.name).join(", ")})`).join("; ")} — ratified or shipped and stale against the model; run \`em slice revise ${docs.map((d) => d.key).join(" / ")}\`, then \`em slice sync\``,
+    };
+}
+/** GH #290 / #278: a retired doc under archive/slices/ names its successor in `superseded-by`, but the
+ *  successor (a signed doc `em upgrade` did not touch) lacks the `merged-from` back-link. */
+function detectLineageBacklinkMissing(ctx) {
+    const dir = join(ctx.baseDir, ARCHIVE_DIR);
+    if (!existsSync(dir))
+        return null;
+    const missing = [];
+    for (const f of readdirSync(dir).filter((n) => n.endsWith(".md")).sort()) {
+        const retired = parseSliceDoc(readFileSync(join(dir, f), "utf8"));
+        for (const ref of retired.supersededBy) {
+            if (!ref.sliceKey)
+                continue;
+            const target = join(ctx.baseDir, "slices", `${ref.sliceKey}.md`);
+            if (!existsSync(target))
+                continue;
+            const doc = parseSliceDoc(readFileSync(target, "utf8"));
+            const key = basename(f, ".md");
+            if (!doc.mergedFrom.some((m) => m.sliceKey === key))
+                missing.push(`slices/${ref.sliceKey}.md needs merged-from: ${key}@v${retired.version ?? 1}`);
+        }
+    }
+    if (missing.length === 0)
+        return null;
+    return { id: "lineage-backlink-missing", reason: `${missing.join("; ")} (the doc is signed or was edited since; add the line to its frontmatter — it is outside the ratified hash)` };
+}
+/** GH #290 / #287: `fold-continuations` is detected and listed by every run but needs the flag. */
+function detectFoldContinuationsOptIn(ctx) {
+    if (ctx.foldContinuations === true || ctx.toSugar === true)
+        return null;
+    const d = detectFoldContinuations(ctx);
+    return d.applicable ? { id: "fold-continuations-opt-in", reason: d.reason } : null;
+}
+function compareVersions(a, b) {
+    const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
+    const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
+    for (let i = 0; i < 3; i++)
+        if ((pa[i] ?? 0) !== (pb[i] ?? 0))
+            return (pa[i] ?? 0) - (pb[i] ?? 0);
+    return 0;
+}
+/** The version the repo is upgrading FROM (recorded `Em version:` bullet, else inferred). */
+function recordedFromVersion(ctx) {
+    const loaded = loadStateFile(ctx.baseDir);
+    let recorded = null;
+    if (loaded.ok) {
+        const parsed = parseState(loaded.text);
+        if (parsed.ok)
+            recorded = parsed.state.emVersion;
+    }
+    return resolveFromVersion(ctx, recorded).version;
+}
+/** GH #290 / #259: signatures are a human decision, so the roster is never generated silently. */
+function detectRosterNotInitialised(ctx) {
+    if (findRosterAbove(ctx.baseDir) !== null)
+        return null;
+    const { ratifiers } = observeSigners(ctx.model, ctx.refs, ctx.baseDir);
+    if (ratifiers.length === 0)
+        return null;
+    return {
+        id: "roster-not-initialised",
+        reason: `${ratifiers.length} ratifier(s) have signed slice docs (${ratifiers.join(", ")}) and there is no ratifiers.yaml — decide who may sign, then run \`em roster init ${basename(ctx.modelFile)}\` to seed one from those names and review it before committing`,
+    };
+}
+/** GH #290 / #279: information only. Since 1.18.0 the same event recorded by several commands (same
+ *  name and context) is one logical event and `duplicate-name` no longer fires; nothing to change. */
+function detectSharedEventNowLegal(ctx) {
+    // The transition only: a repo already stamped 1.18.0+ has seen this note.
+    if (compareVersions(recordedFromVersion(ctx), "1.18.0") >= 0)
+        return null;
+    const shared = new Set();
+    for (const el of ctx.model.elements)
+        if (el.kind === "event" && el.logicalId !== el.id)
+            shared.add(el.name);
+    if (shared.size === 0)
+        return null;
+    return {
+        id: "shared-event-now-legal",
+        reason: `information only: ${[...shared].join(", ")} ${shared.size === 1 ? "is" : "are"} recorded by more than one command — legal since 1.18.0 (one logical event; duplicate-name no longer fires), no model change needed`,
+    };
+}
+/** GH #331: the api-check job needs a contract the mechanical step could not generate. */
+function detectApiContractBlocked(ctx) {
+    const { blocked } = contractPlan(ctx);
+    if (blocked.length === 0)
+        return null;
+    return {
+        id: "api-contract-blocked",
+        reason: `the contract could not be generated for ${blockedText(blocked)}, so the api-check job will fail until it exists - run \`em validate <model>\` to see why, fix it, then \`em api generate <model>\``,
+    };
+}
 const HUMAN_DETECTORS = [
     detectNoModelVersion,
     detectContinuationHasOwnDoc,
@@ -789,6 +1278,12 @@ const HUMAN_DETECTORS = [
     detectPredates16,
     detectPublicFieldTypesUnresolved,
     detectPluginInstallLocally,
+    detectSliceDocStaleSigned,
+    detectLineageBacklinkMissing,
+    detectFoldContinuationsOptIn,
+    detectSharedEventNowLegal,
+    detectRosterNotInitialised,
+    detectApiContractBlocked,
 ];
 export function detectHumanItems(ctx) {
     return HUMAN_DETECTORS.map((d) => d(ctx)).filter((x) => x !== null);
@@ -884,7 +1379,8 @@ export function detectUpgrade(ctx) {
     const from = resolveFromVersion(ctx, recorded);
     const steps = UPGRADE_STEPS.map((s) => {
         const d = s.detect(ctx);
-        return { id: s.id, sinceVersion: s.sinceVersion, applicable: d.applicable, human: d.human === true, reason: d.reason };
+        const optIn = s.optedIn !== undefined && !s.optedIn(ctx) && d.applicable;
+        return { id: s.id, sinceVersion: s.sinceVersion, applicable: d.applicable, human: d.human === true, reason: d.reason, ...(optIn ? { optIn: true } : {}) };
     });
     const human = detectHumanItems(ctx);
     return { from, to: ctx.installedVersion, steps, human, stateFileError };
@@ -921,6 +1417,10 @@ export function applyUpgrade(ctx, runGit = realGit) {
             applied.push({ id: step.id, applied: false, changedFiles: [], commit: null });
             continue;
         }
+        if (step.optedIn && !step.optedIn(ctx)) {
+            applied.push({ id: step.id, applied: false, changedFiles: [], commit: null });
+            continue;
+        }
         const result = step.apply(ctx);
         if (!result.ok) {
             gitDiscardAll(ctx.repoRoot, runGit);
@@ -931,8 +1431,17 @@ export function applyUpgrade(ctx, runGit = realGit) {
         if (!commitResult.ok) {
             return { ok: false, message: `em upgrade: step "${step.id}" applied but failed to commit — ${commitResult.message}`, report, applied };
         }
-        applied.push({ id: step.id, applied: true, changedFiles: result.changedFiles, commit: message });
+        applied.push({ id: step.id, applied: true, changedFiles: result.changedFiles, commit: message, ...(result.notes && result.notes.length > 0 ? { notes: result.notes } : {}) });
+        // A step may have rewritten the model (or its docs): later steps must see the new one.
+        const fresh = freshCompile(ctx);
+        if (fresh) {
+            ctx.model = fresh.model;
+            ctx.refs = fresh.refs;
+        }
     }
+    // The pre-apply human list can be stale (a rewritten model, a doc now out of sync): report the upgraded
+    // repo's, computed before the `Em version:` stamp so transition-only notes still show.
+    report.human = detectHumanItems(ctx);
     const loaded = loadStateFile(ctx.baseDir);
     let emVersionCommit = null;
     if (loaded.ok) {