@liminis/editor 0.1.0-rc.1

package/docs/decisions/adr-075.md

@@ -0,0 +1,410 @@
+# ADR-075: The `@liminis/editor` Package Boundary Is Drawn at Persistence
+
+**Date:** 2026-08-03
+**Status:** Accepted
+**Issue:** #938
+
+## Context
+
+The Lexical markdown WYSIWYG editor — the controlled `<Editor>` component, ~18
+custom node types, ~25 plugins, the C4 diagram subsystem, the mdast⇄Lexical
+mappers, and a 100-fixture round-trip corpus — lived embedded in
+`liminis-app/src/editor/**`.
+
+A near-identical *copy* of that tree was grafted into the Zusammen project and
+the two have been diverging: Zusammen accreted a review-commenting feature and
+markdown idempotency fixes Liminis lacks, while Liminis accreted an AI
+**correction** feature and a post-#896 fixture corpus Zusammen lacks. Every
+future fix to the shared core had to be hand-ported in both directions or
+silently lost.
+
+Making the editor one package with a curated public API is what stops that. But
+a move that leaves the host reach-ins in place is a directory rename, not an
+extraction — and the reach-ins were substantial:
+
+- `messaging-electron` imported directly by `App.tsx`, `ImagePlugin`,
+  `LinkClickPlugin` and `MermaidComponent`.
+- `window.api.*` reached into by `AnchorScrollPlugin`,
+  `WikiLinkExistencePlugin`, and `CorrectionPanelPlugin` (7 sites).
+- `shared/logger`, which branches on `process.type` and imports `node:fs`.
+- `toast` from `sonner`.
+
+The question this ADR settles is **where the seam goes**, because everything
+else — which files move, what the public entry exposes, what gets injected —
+follows from it.
+
+## Decision
+
+**The package/app seam is drawn at persistence.**
+
+Anything about text ranges, marks, rendering, and in-document UX is
+**package-side**. Storage, lifecycle, identity, and higher-level panels are
+**app-side**. The editor package reaches the host only through injected
+services; it never reaches for a global.
+
+Four consequences, each load-bearing:
+
+### 1. A closed set of declared export subpaths — the `exports` map *is* the public surface
+
+`packages/editor/package.json` declared exactly five entries when this ADR was
+written. ADR-077 added a sixth, `./annotations`, and ADR-079 added a seventh,
+`./nodes`, both as *considered* exports under the rule stated below; the table
+is kept current here so this record stays the single inventory of the public
+surface:
+
+| Subpath | Purpose |
+|---|---|
+| `.` | The React surface: `<App>`, `<Editor>`, host provider/hook, markdown pipeline, message contract, stores, `findSvgElement` |
+| `./markdown` | Markdown parsing alone: `parseMarkdown`, the mdast type guards, `getFileType`. No DOM, no Lexical, no MathJax |
+| `./headless` | DOM-free: C4 parse/layout/`renderC4DiagramToSVG`, the MathJax **lite** document factory, `getFileType` |
+| `./annotations` | DOM-, React- and Lexical-free annotation mechanics: anchor model, resolver, block structure, span alignment, annotation/kind types (added by ADR-077) |
+| `./contract` | The zod host-message contract alone, for `import type` at the preload boundary |
+| `./nodes` | `editorNodes` (the exact Lexical node array `<Editor>` configures itself with) plus `importMarkdownToLexical`/`exportLexicalToMdast`, for building a headless Lexical editor (added by ADR-079) |
+| `./styles.css` | The stylesheet |
+
+FR-002's "single curated public entry" is read as *nothing may be imported that
+is not declared in `exports`*. Several subpaths rather than one is forced, not
+stylistic:
+
+- The Electron **main** process declares `lib: ["ES2024"]` and no DOM
+  (`tsconfig.main.json`). It consumes `renderC4DiagramToSVG` (for the
+  `app_render_c4_diagram` MCP tool and the remote-session route) and the MathJax
+  lite adaptor. A single React barrel would make `tsc` follow the whole graph and
+  typecheck Lexical against a DOM-free lib set. **If `./headless` ever fails to
+  compile under `tsconfig.main.json`, prune that entry's import graph — never
+  widen main's `lib`.**
+
+  **The DOM-free contract is a convention, not a compiler-enforced invariant, and
+  reviewers should not assume otherwise.** Main's declared `lib` does not actually
+  make `Document`/`HTMLElement` unresolvable: something already in `src/main`'s own
+  dependency graph pulls the DOM lib in, so those globals resolve inside the main
+  program today. (Verified two ways: a `(d: Document) => d.body` probe compiles
+  under `tsconfig.main.json`, while the same probe against `types: ["node"]` alone
+  fails with `TS2304`. This predates the extraction — main's include list and
+  dependencies are unchanged by it.) The practical consequence is that a DOM-typed
+  export added to `./headless` would compile silently instead of failing the build.
+  For that reason `createBrowserAdaptorDocument` and `BrowserMathJaxInstance` —
+  typed over `Document` and `MathDocument<HTMLElement>` — are deliberately **not**
+  on this entry; their only consumer is `EquationComponent.tsx` inside the package,
+  which imports them by relative path. Restoring real enforcement (a separate
+  DOM-free tsconfig project over `./headless`) is still worth doing. It was
+  originally deferred to #940; #940 gave the package a build but deliberately
+  scoped itself to delivery and did not take this on. It needs a follow-up.
+
+  One **known exception** is worth naming rather than leaving to be discovered:
+  `./headless` re-exports `createLiteAdaptorDocument` from `mathjax-config.ts`,
+  and that module statically imports `browserAdaptor` alongside `liteAdaptor` at
+  top level. So loading this entry does evaluate a DOM-adaptor module — the
+  convention is already bent, not merely bendable. It is *not* a regression from
+  the extraction: before it, `main/remote-session/routes.ts` imported
+  `shared/mathjax-config` directly and pulled in the identical graph, so main's
+  runtime imports are unchanged. Splitting the module into lite and browser
+  halves is the real fix, alongside the enforcement above — doing it here would
+  change main's module graph under a parity constraint. Originally deferred to
+  #940, which scoped itself to delivery and did not take it on; it needs the same
+  follow-up.
+- `preload/index.ts` and `types/window-api.d.ts` need only the message shapes.
+  `./contract` is often shorthanded as "the zod-free entry"; it is not. It
+  re-exports `./types`, which imports zod and uses it for real runtime validation
+  (`validateHostToUIMessage`). What actually keeps zod out of the preload bundle
+  is that both consumers use `import type`, which erases at build time — the
+  narrow subpath only limits how much would come along if one of them ever
+  didn't. `editor-package-wiring.test.ts` pins that `import type` discipline,
+  since nothing in the exports map can.
+- `styles.css` is not code.
+- `./markdown` exists because the root barrel exports `<App>`/`<Editor>`, so
+  importing *anything* from it drags Lexical, MathJax, Mermaid and the C4
+  subsystem into the importing window. `MarkdownSnippet` needs only
+  `parseMarkdown` and `getFileType`, and is reachable from the `graph` and
+  `workflow` renderer entry points, which host no editor at all. Measured on the
+  emitted bundles: barrel ≈ 4.76 MB / 4.35 MB of eagerly `modulepreload`ed
+  script for those two windows, versus 2.49 MB / 2.08 MB through `./markdown`.
+  `./headless` is *not* an adequate home for these helpers — it also re-exports
+  `mathjax-config`, whose ~90 bare `import '@mathjax/src/…Configuration.js'`
+  lines are genuinely side-effectful and unshakeable by any consumer, leaving a
+  ~1.94 MB `mathjax-config` chunk in place. Enforced by
+  `editor-package-wiring.test.ts`, which fails if any app file's editor imports
+  are wholly covered by `./markdown` yet come from the barrel.
+
+### 2. Host services are injected via React context, with a safe default for every member
+
+`EditorHostServices` (in `src/host/types.ts`) carries an optional `bridge`,
+`logger`, `resolveWikiLinks`, `onScrollToAnchor`, `notifyError`, and
+`corrections`. It is supplied through `<EditorHostProvider services={…}>` and
+read with `useEditorHost()`.
+
+Context rather than prop drilling: there are five separate editor mount sites in
+`liminis-app` and ~20 deeply nested plugins; threading a services object through
+`App` → `Editor` → every plugin would be a large, error-prone diff. A
+module-level `configureEditorHost()` singleton was rejected as untestable in
+parallel and hostile to a second consumer.
+
+Every member has a safe default (`src/host/defaults.ts`), so `<Editor>` renders
+in a host that supplies nothing. Two default *shapes* are used deliberately:
+
+- `bridge`, `logger` and `notifyError` fall back to a concrete no-op/console
+  implementation.
+- `resolveWikiLinks`, `onScrollToAnchor` and `corrections` stay **undefined**
+  when absent, because their consumers treat "service missing" as "feature
+  unavailable, leave the document alone". That is exactly what the pre-extraction
+  `if (!window.api?…) return` guards did; substituting a stub that returns `{}`
+  would, for instance, mark every wiki-link broken.
+
+### 3. The host bridge has two methods; the message helpers are package-side
+
+`EditorHostBridge` is only `postMessage` + `addMessageHandler`. The helpers
+(`requestInit`, `requestSettings`, `applyTextEdits`, `writeAsset`, `openLink`)
+were moved *into* the package and rebuilt on `postMessage`.
+
+This makes parity structural rather than hoped-for: every host adapter emits
+byte-identical wire payloads because there is only one place that constructs
+them. `liminis-app/src/renderer/editor-host.ts` is now a thin adapter over
+`window.api.editor`, and it is the successor to the deleted
+`src/editor/messaging-electron.ts`.
+
+**One deliberate non-parity change came with that move.** The adapter's
+handler-leak guard was carried over verbatim at first, and review found it
+unsound in two ways that only bite at scale, so it was repaired rather than
+preserved:
+
+- It counted **unique function identities** in a `Set`, but every call opens its
+  own `onMessage` subscription. Two registrations of one reference were two
+  subscriptions counted as one, and the first disposer released both.
+- Past the limit it **threw**. The only caller is a React effect, so the throw
+  propagated into render and unmounted the editor. This was reachable in ordinary
+  use, not just in a leak: each mounted `<App>` registers two handlers (`App.tsx`
+  and `ImagePlugin.tsx`), and `canvasStore.expandCard(…, multiExpand)` expands an
+  unbounded number of note cards simultaneously — so six expanded cards exceeded
+  the budget of ten and took the tree down.
+
+A first repair replaced the throw with a log and a refused registration. Review
+caught that this only traded a loud failure for a silent one: refusing means
+returning a no-op disposer *without opening the subscription*, so that editor goes
+deaf to host messages — including `ASSET_WRITTEN`, which makes image paste fail
+with no error anywhere. The same six-expanded-cards path reaches it.
+
+**The budget is therefore a diagnostic, not admission control.** The guard counts
+live subscriptions, releases idempotently, holds no slot when there is no preload
+API, and — past the budget — logs and *still registers*. A genuine leak is still
+loud in the log; it just no longer degrades the editor to say so.
+
+This is a behaviour change against FR-005's parity constraint, taken knowingly: the
+prior behaviour was a crash, the defect is pre-existing on `main` rather than
+introduced here, and the guard is diagnostic rather than a product behaviour.
+Covered by `liminis-app/src/renderer/__tests__/editor-host.test.ts`, whose
+delivery-past-the-budget and idempotent-release cases both fail against the refusing
+implementation.
+
+### 4. Reconciliation with existing ADRs
+
+**ADR-057 (Knowledge Corrections — Renderer→Filesystem→MCP Pipeline).** The
+correction *panel* is in-editor UI and therefore package-side; the pipeline
+ADR-057 describes is persistence and therefore app-side. ADR-057's flow is
+unchanged in behaviour but now **crosses the package boundary** via
+`CorrectionHostServices`:
+
+```ts
+interface CorrectionHostServices {
+  readCorrections(): Promise<string | null>   // raw YAML text, or null
+  writeCorrections(yaml: string): Promise<void>  // host owns mkdir + atomic write
+  suggestEntities(query: string, numResults: number): Promise<string[]>
+  suggestPassages(query: string, numResults: number, minScore: number): Promise<string[]>
+  applyCorrections(): Promise<boolean>
+}
+```
+
+`.liminis/knowledge-corrections.yaml`, the atomic write, and both
+`knowledge-reader`/`knowledge-writer` MCP calls all still live in
+`liminis-app` — read ADR-057's "renderer" as "`liminis-app`'s renderer host
+adapter", not "the editor component". Two orderings ADR-057 and ADR-042 depend
+on are preserved verbatim inside the package and must stay that way:
+`suggestEntities` is awaited *before* `suggestPassages` (the MCP stdio invoker
+rejects concurrent calls to one server), and the confirm path re-reads, merges,
+then writes atomically.
+
+**ADR-025 (Zustand for renderer state).** Two zustand stores now live inside a
+package rather than under `liminis-app/src/renderer/stores/`. ADR-025's
+substance is unchanged — state is still zustand, not window events — but the
+store's *location* may now be a package. The ADR-024/025/032 guidance in
+`.claude/rules/electron-renderer.md` is scoped to `liminis-app` renderer paths
+the editor has left, so it needs to be carried across to `packages/editor/` as a
+path-scoped rule per ADR-034 — see "Outstanding" below.
+
+**ADR-002, ADR-010, ADR-070, ADR-007, ADR-027** are unaffected: the editor is
+still Lexical, the mapper design is unchanged, the C4/node types are unchanged,
+the contextBridge remains the app-side adapter, and the package stays inside the
+repo's vitest story with its own config.
+
+## Deviations from the spec's letter, and why
+
+Three of the spec's file-placement instructions did not survive contact with the
+code. Each deviation follows the persistence seam this ADR establishes, or the
+curated-surface principle, which are the spec's own stated principles.
+
+**`correctionStore` moves package-side** (FR-006 says it stays in
+`liminis-app`). It holds only ephemeral panel UI state — `isOpen`, `position`,
+`selectedText` — persists nothing, and has zero consumers outside the two editor
+plugins. Injecting it would be prop-drilling purely to satisfy a file location.
+FR-006's *substance* — that correction persistence and lifecycle stay app-side —
+is honoured in full by `CorrectionHostServices`.
+
+Because that justification rests entirely on "no consumer outside the two editor
+plugins", `useCorrectionStore` is deliberately **not** re-exported from `.`.
+Publishing it would invite the app-side consumer that invalidates the reasoning,
+with nothing at the package boundary to catch it. `useEditorStore` *is* public —
+`EditorColumn` drives the frontmatter tray from the app toolbar — so the two
+stores are not symmetric, and that asymmetry is the point.
+
+**`mathjax-config.ts` moves package-side but is exposed on `./headless`**, and
+`fileTypes.ts` **splits**. `getFileType` (used by `mdastToLexical` and
+`MarkdownShortcutsPlugin`) moved to `packages/editor/src/utils/file-types.ts`;
+`toWorkspaceRelativePath` has no editor consumer at all and stayed in
+`liminis-app/src/renderer/utils/fileTypes.ts`. `mathjax-config`'s existing test
+moved with it — the spec's manifest omitted it, and dropping it would have been
+silent coverage loss.
+
+**`messaging.ts` was deleted rather than moved.** The spec listed the vestigial
+VS Code webview adapter among the files that move, and the Plan kept it as a
+notional second `EditorHostBridge` implementation. It is neither. It has no
+importer anywhere in the repo, it implements the *old* ad-hoc API rather than
+`EditorHostBridge`, it self-invokes `initMessageListener()` at module load
+(attaching a `window` listener the moment anything imports it), and it carries
+the very throw-on-overflow handler logic that decision 3 above deliberately
+replaced with a diagnostic counter. Shipping it would have contradicted this
+ADR's claim that `host/messages.ts` is the single place wire payloads are
+constructed.
+
+Its `VsCodeApi` interface and the `declare global { interface Window {
+acquireVsCodeApi } }` augmentation in `types.ts` went with it. That augmentation
+was the concrete harm: `export * from './types'` in both `src/index.ts` and
+`src/contract.ts` published it, so every consumer of `.` **and** `./contract` —
+including the Electron preload, which uses `./contract` precisely to avoid
+unrelated surface — had `window.acquireVsCodeApi` typed as globally available in
+a host where it never exists. Verified by probe: before the removal a consumer
+calling `window.acquireVsCodeApi()` typechecked cleanly; after it, the same
+probe fails with `TS2339`.
+
+## Consequences
+
+### Positive
+
+- One implementation of the editor, with a curated API, ready for Zusammen to
+  adopt in place of its copy — which is what ends the divergence.
+- The package can be reasoned about, and tested, with no knowledge of Electron.
+  `<Editor>` renders with zero host services supplied.
+- The correction feature's persistence contract is now explicit and stubbable,
+  where previously it was seven scattered `window.api` calls.
+- #939 (unified annotation mechanism) becomes a contained design problem rather
+  than a design problem tangled up with a 182-file relocation.
+
+### Negative / costs
+
+- **Four build-config landmines had to be defused, and they stay defused only
+  by intent:**
+  1. Tailwind v4 automatic source detection always skips `node_modules`, and the
+     package resolves through the `node_modules/@liminis/editor` symlink. Without
+     an explicit `@source "../../../../packages/editor/src"` in
+     `src/renderer/styles/main.css`, the editor's ~165 utility classes silently
+     stop being generated — with no typecheck, lint, build, or test signal.
+  2. `externalizeDepsPlugin()` on the `main`/`preload` targets must exclude
+     `@liminis/editor`, or the emitted bundle keeps a bare
+     `import '@liminis/editor/headless'` that resolves to unbuilt TypeScript at
+     runtime.
+  3. The package needs its own `typecheck`/`lint`/`test` scripts or `pnpm -r`
+     skips 74 source files, and CI needs its own test step or the 100 relocated
+     fixtures stop running while the suite stays green.
+  4. **The package must NOT declare `"sideEffects"`.** This one is a trap rather
+     than a chore, and it was walked into during review before being walked back
+     out. Barrel weight (see subpath `./markdown` above) makes a `sideEffects`
+     declaration look like the obvious one-line fix. It is not: declaring it
+     breaks the renderer outright.
+
+     Marking our modules side-effect-free does not merely prune our own graph —
+     it changes rolldown's whole-graph chunking. Under it, `prismjs` (reached
+     via `@lexical/code`) has its core separated from `prism-clike.js`, which
+     mutates a bare `Prism` global that is by then undefined:
+
+     ```
+     ReferenceError: Prism is not defined   (prism-clike.js, renderer entry)
+     ```
+
+     The renderer never mounts. `document.body.innerText` is empty, and e2e went
+     from green to 138 failures spanning chat, command palette, content editing
+     and semantic search — nothing editor-specific, because every locator misses
+     when nothing renders. Bisected to the commit that added the key; removing
+     only that key restores a green suite. The hazard lives in a **transitive
+     dependency**, so it cannot be expressed in our own `sideEffects` field at
+     all: `["**/*.css"]` and `false` fail identically. Reduce barrel weight with
+     a narrow entry point instead.
+
+     **Closed by #940, in favour of the prohibition.** The theory behind the
+     deferral was that a consumer of *built* output would have a different module
+     graph and might legitimately need the field. It does not: #940's build is a
+     structure-preserving `tsc` emit that does no chunking of its own, so an
+     external consumer's bundler sees the same graph liminis-app's does. The
+     hazard is identical, not different. The measurement the field was wanted for
+     targets the `React.lazy()` boundary on `AnnotationSurface` instead and does
+     not depend on it. See ADR-078 §5. This prohibition is permanent unless the
+     build strategy itself changes.
+
+  Landmines 1, 2 and 4 are guarded by
+  `liminis-app/src/shared/__tests__/editor-package-wiring.test.ts`. All three are
+  invisible to typecheck, lint, build and the rest of the suite — the build
+  reports success while the app degrades (landmine 4 being the exception that
+  proves the rule: it *is* caught, but only by e2e, an hour downstream) — which
+  is why they get a test that asserts the *configuration* rather than the
+  symptom.
+- ~~The package is consumed as raw TypeScript in-workspace. A standalone ESM +
+  `.d.ts` build, peer dependencies, and resolving the patched
+  `mdast-util-wiki-link@0.1.2` are deferred to #940.~~ **Landed in #940 — see
+  ADR-078.** The package now builds to `dist/`; `publishConfig` points external
+  consumers at it while the checked-in manifest still resolves to `src/`, so
+  liminis-app's consumption — and both build guards above — are unchanged.
+  `react`/`react-dom`/`lexical` and all eleven `@lexical/*` are peers, and
+  `mdast-util-wiki-link` is vendored into the package with its patch applied
+  inline, so no pnpm patch survives.
+- Ambient declarations (`jsx.d.ts` for React 19's non-global JSX namespace, and
+  the `micromark-extension-wiki-link` shim) are duplicated in
+  `packages/editor/src/ambient/` and `liminis-app/src/types/`, since both
+  programs need them and neither may depend on the other.
+
+## Outstanding
+
+**`.claude/rules/editor-package.md` has not been written.** The Fabrik worker
+environment denies writes under `.claude/`, so the path-scoped rule that carries
+ADR-024/025/032 across to `packages/editor/**` (per ADR-034) could not land with
+this ADR. Its drafted content is in PR #941's body and needs a human to commit
+it. Until it exists, the guidance lives only here and in this ADR's "Decision"
+section.
+
+## Alternatives Considered
+
+**A single root barrel export.** Rejected: it forces the DOM-free main process
+program to typecheck Lexical and `react-dom/client`.
+
+**Leaving `messaging-electron.ts` in the package and stubbing `window.api` in
+tests.** Rejected: it is precisely the coupling the extraction exists to remove,
+and it would have kept the package's test setup mocking a host global.
+
+**Keeping the message helpers app-side, with a six-method bridge.** Rejected:
+six adapter methods per host is six opportunities to drift from the wire format,
+where two methods plus package-side helpers cannot drift at all.
+
+**A general-purpose third-party plugin API.** Explicitly out of scope. The
+public entry is a curated export surface, not an extension mechanism; #939 bakes
+annotations *into* the package rather than exposing hooks for hosts to extend.
+See ADR-077, which carries that out and adds `./annotations` as a sixth,
+considered subpath under the rule stated above.
+
+## References
+
+- ADR-079 (headless mapper/node export) — adds `./nodes` as a seventh,
+  considered subpath under the rule stated above
+- ADR-077 (comments and corrections as two kinds of one annotation mechanism) —
+  extends this seam and adds the `./annotations` subpath
+- Issue #938 (this phase), #939 (unified annotation mechanism), #940 (OSS hardening)
+- `specs/938-extract-the-lexical-markdown/spec.md`
+- ADR-002 (Lexical), ADR-010 (bidirectional markdown conversion), ADR-025
+  (zustand for renderer state), ADR-042 (MCP stdio serialization), ADR-057
+  (knowledge corrections pipeline), ADR-070 (dedicated Lexical node types)
+- `.claude/rules/editor-package.md` (not yet written — see "Outstanding")

package/docs/decisions/adr-076.md

@@ -0,0 +1,183 @@
+# ADR-076: Markdown Serialization Is a Fixed Point, at the Cost of a One-Time Canonicalization
+
+**Date:** 2026-08-04
+**Status:** Accepted
+**Issue:** #943
+
+## Context
+
+Liminis's markdown pipeline —
+`parseMarkdown → importMarkdownToLexical → exportLexicalToMdast → stringifyMarkdown` —
+runs on every open and save. Until now the round-trip corpus asserted only that
+one pass was faithful: input → output matched either the input itself or a
+recorded `.expected.md` sidecar.
+
+That guarantee is weaker than it looks. It says nothing about whether the
+*output* is stable. A serializer can be perfectly faithful on the first pass and
+still drift on the second, which in practice means a document nobody edited
+keeps changing on disk every time it is opened and saved — invisible in the
+WYSIWYG view, visible in git diffs, and cumulative.
+
+Two genuine defects had been living in `stringify.ts` behind exactly that gap.
+Both were found and fixed in Zusammen's forked copy of the file
+([verveguy/zusammen#62](https://github.com/verveguy/zusammen/pull/62), closing
+its #50) and were still live in Liminis:
+
+1. **A blank line before a list was silently dropped.** A `join` override
+   implements a "label:" convention — a paragraph ending in `:` gets zero blank
+   lines before the block that follows, so `Fenced code:` hugs its fence.
+   `list` was wrongly in that set, so `Steps to reproduce:` followed by a blank
+   line and a bulleted list lost the blank line, unlike every other
+   preceding-block type.
+
+2. **A post-process regex corrupted verbatim content.** `stringify.ts` ended
+   with `result.replace(/\n{3,}/g, '\n\n')`. `mdast-util-to-markdown`'s own join
+   logic already never emits 3+ newlines between sibling blocks, so this had no
+   legitimate job left. Its only real effect was destroying intentional
+   multi-blank-line runs *inside fenced code blocks and frontmatter YAML block
+   scalars* — content that must survive byte-for-byte.
+
+ADR-075 drew the `@liminis/editor` package boundary and named "markdown
+idempotency fixes Liminis lacks" as precisely the divergence the extraction
+existed to stop. Because the serializer now has a single home, this is a
+one-site fix rather than a hand-port to two repositories.
+
+## Decision
+
+**Serialization output is a fixed point.** Every fixture's own first-pass output
+is round-tripped a second time and must be byte-identical. This applies to
+fixtures whose first pass legitimately changes bytes (`.expected.md` sidecars)
+as well as byte-identical ones — matching a sidecar says nothing about whether
+that sidecar's content is itself stable.
+
+**We accept a one-time canonicalization to get there.** Removing `list` from the
+colon-join override is a user-visible behaviour change: a document containing a
+colon-ending paragraph immediately followed by a list *gains* a blank line on its
+first save after this ships.
+
+**Exemptions are individually documented, never batched.** A fixture with a
+known, accepted non-idempotency carries a `<name>.idempotence-exempt.txt`
+sidecar whose contents are the written reason. An exemption file that exists but
+is empty is a hard error in fixture discovery — the reason is mandatory, which
+makes "skip it to get green" impossible to do silently.
+
+**No repo-wide normalization pass.** Documents canonicalize as they are saved.
+
+### Which document shapes change on first save
+
+Only one, and only in one direction:
+
+| Shape | Before | After |
+|---|---|---|
+| Colon-ending paragraph immediately followed by a list (no blank line) | stays zero blank lines | gains one blank line |
+| Colon-ending paragraph, blank line, then a list | blank line **dropped** | blank line preserved |
+| Colon-ending paragraph before a table, fenced code, or block math | zero blank lines | **unchanged** — zero blank lines |
+| 2+ consecutive blank lines inside a fenced code block or YAML block scalar | **collapsed to one** | preserved verbatim |
+| 2+ consecutive blank lines between sibling blocks | collapsed to one | unchanged — still collapsed, by the library's own join logic |
+
+The last row is the one worth stating explicitly: removing the regex did *not*
+let 3+ newlines through. Blank-line runs between flow siblings are discarded at
+*parse* time — mdast has no representation for them — so the collapse still
+happens without any post-process help. This is pinned by fixtures
+(`50-multiple-blank-lines-between-paragraphs`,
+`50-multiple-blank-lines-before-list`, and the three-blank-line runs inside
+`50-reference-readme`).
+
+## Consequences
+
+### Positive
+
+- A saved document that nobody edits stops changing on disk. This is the
+  structural guarantee that would have caught both defects, and it now catches
+  the next one automatically for every fixture in the corpus.
+- Code and configuration inside fenced blocks and YAML block scalars survive
+  verbatim. This was the more serious of the two defects: silently corrupting
+  the code a note documents is worse than a cosmetic diff.
+- The fix lands in `@liminis/editor`, so when Zusammen adopts the package (#940)
+  it stops being something anyone has to hand-port.
+
+### Negative
+
+- **A visible one-time diff in users' notebooks.** Any real document with a
+  colon-ending paragraph immediately followed by a list gains a blank line the
+  first time it is saved after this ships. This is accepted deliberately: it
+  makes lists behave like every other preceding-block type, and the alternative
+  — preserving the defect to avoid the diff — means the drift never stops.
+- The round-trip corpus is now the slowest suite in the workspace: the second
+  pass roughly doubles its work across the 100 non-exempt fixtures (105 inputs
+  less the 5 exemptions below). "Non-exempt" means exactly one thing — the
+  fixture runs the second-pass assertion. It is not a claim about fidelity: the
+  23 `known-defects/` fixtures are all non-exempt and all pass, because a round
+  trip that loses content still reaches a fixed point (see the Neutral note
+  below). The only other category outside the assertion is `.error.txt`
+  fixtures, which reject on the first pass and so have no output to feed back;
+  the corpus has none today.
+
+### Neutral
+
+- Five fixtures are exempt, all one pre-existing cause: #902's double-hard-break
+  marker serializes as a whitespace-only line, which CommonMark re-reads as
+  blank, splitting the paragraph on the second pass. Fixing that hard-break
+  normalization is out of scope here and needs its own issue. The exemption set
+  was determined by observation — the harness landed before the fixes so the
+  pre-fix failure set could be recorded — not by prediction.
+- The `known-defects/` fixtures continue to assert current defective behaviour.
+  None of them needed an exemption: asserting a *defective* output does not stop
+  that output from being a stable fixed point.
+- **A fixed point is a guarantee about stability, not fidelity.** This is the
+  limit of what the second pass buys, and it is worth stating plainly so the
+  guarantee is not over-read. A round trip that silently *drops* content reaches
+  a fixed point immediately and passes — `known-defects/other-blockquote-list-
+  content-lost`, found during this issue's review, is the live example: a list
+  inside a blockquote is lost entirely, and the lossy output is perfectly
+  stable. The first-pass `.expected.md` comparison is what catches fidelity
+  loss. That defect is pre-existing, lives in the mapper rather than the
+  serializer, and needs its own issue.
+- `stringify.test.ts`'s "collapse excessive blank lines" case still passes with
+  the post-process deleted, since its input is two plain paragraphs. It was
+  retitled rather than removed — it now pins the `mdast-util-to-markdown` join
+  guarantee that removing the regex rests on, so a library upgrade that breaks
+  that guarantee fails loudly instead of silently letting blank-line runs
+  through. Review broadened it from that single paragraph pair to 14 sibling-
+  block pairs (heading, fenced code, list, table, blockquote, thematic break,
+  block math, HTML block, nested list, frontmatter), so the guarantee is pinned
+  where it is actually load-bearing.
+- The colon detection only fires when the paragraph's final inline node is a
+  plain `text` node, so `**Steps:**` is not treated as colon-ending. After this
+  change that distinction is unobservable for lists — both shapes get one blank
+  line — but it remains observable for `table`/`code`/`math`, where
+  `**Fenced code:**` keeps its blank line and `Fenced code:` does not. That
+  asymmetry is pre-existing and deliberately unchanged; both sides are pinned by
+  the `943-non-text-colon-paragraph-*` fixtures.
+
+## Alternatives Considered
+
+**Make the regex verbatim-span-aware instead of removing it.** Rejected: it
+would have to know about fenced code, inline code, math spans and frontmatter
+block scalars — the same span-tracking complexity that already makes the
+neighbouring post-processes fragile — to implement a guarantee the library
+already provides for free.
+
+**Keep `list` in the colon-join override and exempt the fixtures.** Rejected:
+this is the reported defect, not an accepted normalization. Exempting it would
+be exactly the "batch-exempt to get green" failure the sidecar convention exists
+to prevent.
+
+**A repo-wide normalization pass over existing `.md` documents.** Rejected: it
+would bury the actual fix in a large, undifferentiated diff, and it forces the
+one-time change on documents the user may not have opened in months. Letting
+documents canonicalize as they are saved keeps each diff small and attributable.
+
+**Amend ADR-075 rather than write a new ADR.** Rejected: ADR-075 is Accepted and
+scoped to the package boundary. This is a distinct, user-visible behaviour
+decision; folding it into an accepted structural ADR muddies both records.
+
+## References
+
+- Issue #943; [verveguy/zusammen#62](https://github.com/verveguy/zusammen/pull/62) (the original fix)
+- ADR-075 — the `@liminis/editor` package boundary that made this a single-site fix
+- ADR-070 — dedicated Lexical node types for lossless round-tripping; this extends
+  its guarantee from "one pass is faithful" to "one pass is a fixed point"
+- `packages/editor/src/markdown/stringify.ts` — both fixes
+- `packages/editor/src/app/mapper/__tests__/fixtures/roundtrip/README.md` — the
+  fixture, sidecar and exemption conventions