@smartmemory/compose 0.4.1 → 0.5.0

package/lib/fluid/ideabox-manifest.js

@@ -0,0 +1,203 @@
+/**
+ * lib/fluid/ideabox-manifest.js — a durable record of a migration in flight.
+ *
+ * COMP-IDEABOX-MIGRATE-DIALECT FU-1.
+ *
+ * THE FAILURE THIS EXISTS TO PREVENT
+ * ----------------------------------
+ * `importIdeabox` writes records sequentially. Crash on idea 2 and ideas 3..N
+ * were never issued, so they carry no event — and the gate's resume policy is
+ * derived from the event log, so it classifies every one of them as a
+ * hand-added stray and refuses. The recovery the refusal names (`compose
+ * ideabox add`, then `render`) runs the same gate, so the installation is
+ * stranded with no way forward.
+ *
+ * The event log can only testify about handles the import reached. The
+ * unattempted TAIL of a migration leaves no trace anywhere, which is why this
+ * has to be an intention written down BEFORE the first write rather than an
+ * inference from what happened after it.
+ *
+ * WHY IT IS SAFE TO TRUST
+ * -----------------------
+ * The manifest may only ever WIDEN the resumable set, and only under two
+ * conditions checked together: it is still open (a completed import removes
+ * it), and its hash matches the document being read right now. A hand-added
+ * idea changes the document, so the hash stops matching and the gate refuses —
+ * the protection the gate exists for is not weakened by anything here.
+ *
+ * WHERE IT LIVES
+ * --------------
+ * `.compose/data/`, beside the provider's lock. `data/` is blanket-gitignored
+ * (`.gitignore:3`); the ideabox's own directory is TRACKED, and a stray file
+ * there gets committed by accident (see the temp-file note in
+ * `render-ideabox.js`). A manifest that is missing — a fresh clone, a provider
+ * with no local lock path — degrades to REFUSE, which is the safe direction.
+ */
+
+import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/**
+ * The source document changed WHILE its own migration was running.
+ *
+ * Raised by `importIdeabox` after its last write, when the file it parsed is no
+ * longer the file on disk. During a migration the ideabox is still the user's
+ * OWN SOURCE DOCUMENT, not generated output, so an edit to it is real content
+ * that never reached the store — and the projection that follows would erase
+ * it. Failing here leaves the manifest OPEN, so the next run refuses as
+ * `IDEABOX_MANIFEST_STALE` and names the mid-migration edit.
+ *
+ * Lives in this leaf module rather than beside the other migration errors
+ * because `ideabox-migrate.js` imports `importIdeabox`, so importing back from
+ * it would close a cycle.
+ */
+export class IdeaboxSourceChangedDuringImport extends Error {
+  constructor(ideaboxPath) {
+    super(
+      `compose: the ideabox at ${ideaboxPath} was edited while its migration was running, so the ` +
+      `import stopped before finishing. Until the migration completes this file is still your ` +
+      `source document rather than generated output, and continuing would have replaced it with a ` +
+      `projection built from the version read at the start — destroying whatever was just added. ` +
+      `Nothing has been changed and the unfinished migration is still recorded. Records written ` +
+      `before the edit are already in the store, so re-running will NOT pick the edit up. Decide ` +
+      `which document is right and say so: \`compose ideabox adopt-file\` finishes the migration ` +
+      `against the file as it now stands, keeping the edit; \`compose ideabox discard-edits\` puts ` +
+      `the file back as the migration read it and finishes that, after saving a copy of the current ` +
+      `file first.`
+    );
+    this.name = 'IdeaboxSourceChangedDuringImport';
+    this.code = 'IDEABOX_SOURCE_CHANGED_DURING_IMPORT';
+  }
+}
+
+/**
+ * The current manifest format.
+ *
+ * v2 adds `text`: the source markdown itself, not only its hash. That is what
+ * makes `compose ideabox discard-edits` LOSSLESS — without the original
+ * document there is nothing to put back, and the only recovery from a
+ * mid-migration edit is to adopt whatever the file now says. An ideabox is a
+ * small file and this is written once per migration.
+ *
+ * A v1 manifest is still valid and still resumes; it simply has no `text`, so
+ * `discard-edits` refuses on one and names `adopt-file` as its recovery.
+ */
+export const MANIFEST_VERSION = 2;
+
+/** Content identity of the document a migration was planned against. */
+export function hashMarkdown(markdown) {
+  return createHash('sha256').update(String(markdown ?? ''), 'utf8').digest('hex');
+}
+
+/**
+ * Where this provider keeps the manifest for this ideabox, or null when there
+ * is nowhere durable to put one.
+ *
+ * Derived from `provider.lockPath`, which is the one machine-local, gitignored
+ * location both the gate and the importer already have in hand. Keyed by the
+ * ideabox path so two ideaboxes under one project do not share a manifest.
+ * A provider with no lock path (SmartMemory — see `factory.js`) gets null and
+ * therefore no resume widening, which matches its already-documented lack of
+ * machine-local coordination.
+ */
+export function manifestPath(provider, ideaboxPath) {
+  if (!provider?.lockPath || !ideaboxPath) return null;
+  const key = createHash('sha256').update(String(ideaboxPath)).digest('hex').slice(0, 12);
+  return join(dirname(provider.lockPath), `ideabox-migration-${key}.json`);
+}
+
+/**
+ * Declare a migration BEFORE the first record is written.
+ *
+ * @param {object} provider
+ * @param {string} ideaboxPath
+ * @param {object} plan
+ * @param {string} plan.markdown the exact text that was parsed
+ * @param {string[]} plan.planned every idea handle the import intends to write
+ * @param {string[]} [plan.plannedClusters] cluster NAMES, for diagnostics only —
+ *   cluster handles are allocated by the store and are not known in advance,
+ *   and the gate's resume decision is about idea handles from the markdown.
+ * @returns {string|null} the path written, or null when there is no home
+ */
+export function openManifest(provider, ideaboxPath, { markdown, planned, plannedClusters = [] }) {
+  const path = manifestPath(provider, ideaboxPath);
+  if (!path) return null;
+  const hash = hashMarkdown(markdown);
+
+  // A RETRY MUST NOT TOUCH THE PLAN IT IS RETRYING.
+  //
+  // Every resumed import came through here again, and rewriting a manifest that
+  // already says the same thing is pure risk: the file whose entire job is to
+  // survive a crash was being destroyed and recreated by each attempt to
+  // recover from one. An open manifest carrying this hash and this plan is
+  // already correct, so it is left exactly where it is.
+  const open = readManifest(provider, ideaboxPath);
+  // An identical plan is left exactly where it is — EXCEPT when it predates the
+  // stored text. We are holding the very document a v1 manifest failed to keep,
+  // so upgrading it here costs one write and gives an in-flight migration the
+  // lossless recovery it was started without.
+  if (open && open.hash === hash && sameSet(open.planned, planned)
+      && typeof open.text === 'string') return path;
+
+  mkdirSync(dirname(path), { recursive: true });
+  const body = JSON.stringify({
+    version: MANIFEST_VERSION,
+    source: ideaboxPath,
+    hash,
+    // The document itself, so `discard-edits` has something to put back.
+    text: String(markdown ?? ''),
+    planned,
+    plannedClusters,
+    startedAt: new Date().toISOString(),
+  }, null, 2);
+
+  // Temp + rename, the pattern `publishProjection` uses on the projection.
+  // A plain `writeFileSync` truncates first, so a crash or a full disk between
+  // the truncate and the write leaves a manifest that is present but empty —
+  // and a manifest that cannot be read is a manifest that does not vouch for
+  // anything, which turns the whole remaining corpus into strays. `rename` is
+  // atomic: the manifest is either the old plan or the new one, never neither.
+  const tmp = `${path}.tmp.${randomUUID()}`;
+  try {
+    writeFileSync(tmp, body, 'utf8');
+    renameSync(tmp, path);
+  } catch (err) {
+    rmSync(tmp, { force: true });
+    throw err;
+  }
+  return path;
+}
+
+/** Order-insensitive equality for two handle lists. */
+function sameSet(a, b) {
+  if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+  const set = new Set(a);
+  return b.every((x) => set.has(x));
+}
+
+/** The import finished. Removing the file is what makes "open" mean something. */
+export function closeManifest(provider, ideaboxPath) {
+  const path = manifestPath(provider, ideaboxPath);
+  if (!path) return;
+  rmSync(path, { force: true });
+}
+
+/**
+ * The open manifest for this ideabox, or null.
+ *
+ * An unreadable or malformed manifest reads as absent: every ambiguous state
+ * here has to fall back to refusing, because the one thing this must not do is
+ * widen the resumable set on a guess.
+ */
+export function readManifest(provider, ideaboxPath) {
+  const path = manifestPath(provider, ideaboxPath);
+  if (!path || !existsSync(path)) return null;
+  try {
+    const data = JSON.parse(readFileSync(path, 'utf8'));
+    if (!data || typeof data.hash !== 'string' || !Array.isArray(data.planned)) return null;
+    return data;
+  } catch {
+    return null;
+  }
+}

package/lib/fluid/ideabox-migrate.js

@@ -34,9 +34,16 @@
 import { existsSync, readFileSync } from 'node:fs';
 
 import { parseIdeabox } from '../ideabox.js';
+import { hashMarkdown, readManifest } from './ideabox-manifest.js';
+// FU-2: the readability check lives in its own leaf module so the PARSER's own
+// module can import it without closing a cycle through this one. Re-exported
+// here because this was its address for its whole life so far.
+import { IdeaboxUnreadable, assertIdeaboxReadable } from './ideabox-readable.js';
 import { importIdeabox } from './import-ideabox.js';
 import { KIND } from './provider.js';
 
+export { IdeaboxUnreadable, assertIdeaboxReadable };
+
 export class IdeaboxMigrationConflict extends Error {
   constructor(missing, ideaboxPath) {
     super(
@@ -54,43 +61,129 @@ export class IdeaboxMigrationConflict extends Error {
 }
 
 /**
- * Ensure the record store reflects the markdown before any mutation touches it.
+ * An interrupted migration whose source document has changed underneath it.
  *
- * Runs before every mutating ideabox command. Three states, one of which stops
- * the command:
+ * Distinct from a conflict: the entries are ones this store PLANNED to write,
+ * so they are not strays — but the plan was made against a different version of
+ * the file, and importing the current one would import a document nobody
+ * checked. FU-1.
+ */
+export class IdeaboxManifestStale extends Error {
+  constructor(ideaboxPath) {
+    super(
+      `compose: the ideabox at ${ideaboxPath} has an unfinished migration recorded against a ` +
+      `DIFFERENT version of this file — the document was most likely edited while the migration ` +
+      `was running, or after it was interrupted. Resuming would import a version nobody checked, ` +
+      `and the entries added since would be projected away. Nothing has been changed. Decide which ` +
+      `document is right and say so, with one of:\n` +
+      `  compose ideabox adopt-file      the file on disk is right — finish the migration against ` +
+      `it, updating what was already imported to match and importing the rest\n` +
+      `  compose ideabox discard-edits   the migration is right — put the file back as it was read ` +
+      `and finish it (a copy of the current file is saved first, and its path printed)\n` +
+      `Deleting the record of the unfinished migration is NOT a shortcut: it makes the partially ` +
+      `migrated store canon, and the next render replaces this file with a projection of it.`
+    );
+    this.name = 'IdeaboxManifestStale';
+    this.code = 'IDEABOX_MANIFEST_STALE';
+  }
+}
+
+/**
+ * The source document changed between the gate's check and the projection's
+ * write. FU-3.
  *
- *   - **no records, markdown has entries** → import it (the upgrade path)
- *   - **records exist, markdown adds nothing** → already migrated, proceed
- *   - **records exist, markdown has entries with no record** → refuse
+ * The remedy is genuinely different from a conflict's — nothing is wrong with
+ * the file or the store, the two writers simply interleaved — so it does not
+ * reuse `IdeaboxMigrationConflict`, whose text tells the user to re-add ideas
+ * by hand.
+ */
+export class IdeaboxChangedUnderLock extends Error {
+  constructor(ideaboxPath, reason) {
+    super(
+      `compose: the ideabox at ${ideaboxPath} changed between the check and the write ` +
+      `(${reason}), so the projection was abandoned rather than replacing content that was ` +
+      `never checked. Nothing has been changed. Run the command again.`
+    );
+    this.name = 'IdeaboxChangedUnderLock';
+    this.code = 'IDEABOX_CHANGED_UNDER_LOCK';
+    this.reason = reason;
+  }
+}
+
+/**
+ * PURE. What the gate WOULD do, computed without doing any of it.
  *
- * A fresh project with no markdown and no records is the trivial first case and
- * simply proceeds.
+ * Split out of `ensureIdeaboxMigrated` for FU-3: the projection has to re-run
+ * this decision INSIDE its write lock, and it can only do that if making the
+ * decision writes nothing and takes no lock. Reads exactly three things —
+ * `listRecords`, `readEvents`, the markdown — none of which lock, so running it
+ * under the projection lock cannot deadlock the way moving the whole gate under
+ * it does (measured: a full 30s lock timeout, see `render-ideabox.js`).
  *
- * @param {import('./provider.js').FluidProvider} provider
- * @param {string} ideaboxPath absolute path to the markdown ideabox
- * @returns {Promise<{migrated: boolean, imported: string[]}>}
+ * Refusals are RETURNED, not thrown, because a decision procedure that throws
+ * cannot be used to ask a question.
+ *
+ * @returns {Promise<{action: 'none'|'import', markdown?: string} |
+ *                   {action: 'refuse', reason: string, error: Error}>}
  */
-export async function ensureIdeaboxMigrated(provider, ideaboxPath) {
+export async function assessIdeabox(provider, ideaboxPath) {
   const records = await provider.listRecords({ kind: KIND.IDEA });
   const markdown = existsSync(ideaboxPath) ? readFileSync(ideaboxPath, 'utf8') : null;
 
-  if (markdown === null) return { migrated: false, imported: [] };
+  if (markdown === null) return { action: 'none' };
 
   const parsed = parseIdeabox(markdown);
   const inMarkdown = [...(parsed.ideas ?? []), ...(parsed.killed ?? [])].map((i) => i.id);
 
+  try {
+    assertIdeaboxReadable(parsed, ideaboxPath);
+  } catch (error) {
+    return { action: 'refuse', reason: 'unreadable', error };
+  }
+
   const known = new Set(records.map((r) => r.handle));
   const missing = inMarkdown.filter((id) => !known.has(id));
 
   if (records.length === 0) {
-    if (inMarkdown.length === 0) return { migrated: false, imported: [] };
+    if (inMarkdown.length === 0) return { action: 'none' };
     // The upgrade path.
-    const result = await importIdeabox(provider, { markdown, path: ideaboxPath });
-    return { migrated: true, imported: result.imported };
+    return { action: 'import', markdown };
+  }
+
+  // AN OPEN MANIFEST MEANS THE MIGRATION NEVER FINISHED, and that is a fact
+  // about the DOCUMENT, not only about the handles that happen to be absent.
+  //
+  // Scoping this to the missing-handles branch was wrong in a way the ID
+  // comparison hides: an edit to an idea that ALREADY has a record changes no
+  // ID, so nothing is missing, and the gate waved a file through that the
+  // projection then rewrote from the version read at the start of the import.
+  // Until the migration completes this file is still the SOURCE document, so
+  // the question here is whether it is the same document, not whether its ids
+  // line up. (After the migration there is no manifest, so `render` still
+  // discards hand edits to what is by then generated output — that contract is
+  // untouched.)
+  const manifest = readManifest(provider, ideaboxPath);
+  const planned = new Set();
+  if (manifest) {
+    if (manifest.hash !== hashMarkdown(markdown)) {
+      // Planned against a different document. Every handle it names is suspect,
+      // and so is every handle in the file now.
+      return {
+        action: 'refuse',
+        reason: 'manifest-stale',
+        error: new IdeaboxManifestStale(ideaboxPath),
+      };
+    }
+    for (const handle of manifest.planned) planned.add(handle);
+    // Same document, unfinished import. Finishing it is a no-op for handles
+    // that already landed, and it is what closes the manifest — so a crash
+    // between the last write and the close heals on the next command instead of
+    // leaving the store in a state every later check has to reason about.
+    if (missing.length === 0) return { action: 'import', markdown };
   }
 
   if (missing.length) {
-    // RESUME versus REFUSE, decided PER HANDLE from the events log.
+    // RESUME versus REFUSE, decided PER HANDLE.
     //
     // A crash partway through the first-use import leaves some records written
     // and the rest missing, which lands here rather than in the empty-store
@@ -99,29 +192,84 @@ export async function ensureIdeaboxMigrated(provider, ideaboxPath) {
     // fails and there is no way out — and the reclaim path built for exactly
     // this case is never reached.
     //
-    // The log distinguishes the two populations. A handle the import already
-    // burned carries an event; `importIdeabox` skips live records and reclaims
-    // its own aborted allocations, so resuming is safe and lossless.
-    //
     // The evidence has to be per-handle, not "did an import ever run". Once the
     // first import succeeds the log carries `imported` events forever, so a
     // global check would quietly import anything later hand-added to what is
     // now generated output — losing the very protection this gate exists for.
-    // A handle with no event was never issued here: it was typed into the file
-    // by hand, and importing it would treat the markdown as authoritative when
-    // it no longer is.
-    // Three populations, and only one of them is resumable:
+    // A handle with no event and no manifest entry was never issued here: it
+    // was typed into the file by hand, and importing it would treat the
+    // markdown as authoritative when it no longer is.
+    //
+    // Two sources of evidence, because neither alone covers the whole failure:
+    //
+    //   - THE EVENT LOG covers handles the import REACHED. `importIdeabox`
+    //     skips live records and reclaims its own aborted allocations, so a
+    //     handle that was issued and not deleted is a create that crashed, and
+    //     resuming it is safe and lossless.
+    //   - THE MANIFEST covers the handles it never reached. An import that dies
+    //     on idea 2 leaves ideas 3..N with no event anywhere, and no amount of
+    //     reading the log afterwards can distinguish them from strays — the
+    //     intention has to have been written down first (FU-1).
+    //
+    // Three populations, and only two of them are resumable:
     //   - issued, no `deleted` event  → a create that crashed. RESUME.
+    //   - planned by an OPEN manifest whose hash still matches this file
+    //                                 → never attempted. RESUME.
     //   - issued, `deleted` event     → deliberately retired; this file is just
     //                                   stale output. REFUSE (a render fixes it,
     //                                   and importing would resurrect it).
-    //   - never issued               → hand-typed into generated output. REFUSE.
+    //   - neither                     → hand-typed into generated output. REFUSE.
     const { issued, deleted } = await handleHistory(provider);
-    const resumable = missing.filter((id) => issued.has(id) && !deleted.has(id));
+
+    const resumable = missing.filter(
+      (id) => (issued.has(id) && !deleted.has(id)) || (planned.has(id) && !deleted.has(id)),
+    );
     const strays = missing.filter((id) => !resumable.includes(id));
-    if (strays.length) throw new IdeaboxMigrationConflict(strays, ideaboxPath);
+    if (strays.length) {
+      return {
+        action: 'refuse',
+        reason: 'stray-entries',
+        error: new IdeaboxMigrationConflict(strays, ideaboxPath),
+      };
+    }
+
+    return { action: 'import', markdown };
+  }
+
+  return { action: 'none' };
+}
+
+/**
+ * Ensure the record store reflects the markdown before any mutation touches it.
+ *
+ * Runs before every mutating ideabox command. Three states, one of which stops
+ * the command:
+ *
+ *   - **no records, markdown has entries** → import it (the upgrade path)
+ *   - **records exist, markdown adds nothing** → already migrated, proceed
+ *   - **records exist, markdown has entries with no record** → refuse
+ *
+ * A fresh project with no markdown and no records is the trivial first case and
+ * simply proceeds.
+ *
+ * Assess, then act. The decision is `assessIdeabox` and this is the only thing
+ * that executes it; the split exists so the projection can ask the same
+ * question under its lock (FU-3) without re-implementing the answer.
+ *
+ * @param {import('./provider.js').FluidProvider} provider
+ * @param {string} ideaboxPath absolute path to the markdown ideabox
+ * @returns {Promise<{migrated: boolean, imported: string[]}>}
+ */
+export async function ensureIdeaboxMigrated(provider, ideaboxPath) {
+  const assessment = await assessIdeabox(provider, ideaboxPath);
+
+  if (assessment.action === 'refuse') throw assessment.error;
 
-    const result = await importIdeabox(provider, { markdown, path: ideaboxPath });
+  if (assessment.action === 'import') {
+    const result = await importIdeabox(provider, {
+      markdown: assessment.markdown,
+      path: ideaboxPath,
+    });
     return { migrated: true, imported: result.imported };
   }
 

package/lib/fluid/ideabox-preamble.js

@@ -0,0 +1,155 @@
+/**
+ * lib/fluid/ideabox-preamble.js — a project's own heading and introduction,
+ * kept beside the projection rather than inside it.
+ *
+ * COMP-IDEABOX-MIGRATE-DIALECT FU-4.
+ *
+ * THE DEFECT
+ * ----------
+ * `renderIdeabox` emits a hardcoded template preamble, so the first projection
+ * after a migration replaced a project's own title and introductory prose with
+ * the standard one. Ideas, clusters, custom fields and bodies all survived; the
+ * document AROUND them did not. Measured on forge-top: `# Forge Ideabox` and
+ * its two-line introduction were destroyed.
+ *
+ * WHY A SIDECAR AND NOT A RECORD
+ * ------------------------------
+ * The obvious fix — carry the preamble forward from the file being replaced —
+ * was implemented and rejected, because it makes the DESTINATION authoritative
+ * and `render` is documented as the way back from any hand edit
+ * (`lib/ideabox-cli.js`). A projection that reads its own destination cannot
+ * repair it.
+ *
+ * The alternative was to make the preamble a record. The owner rejected that:
+ * it means a new ontology type in every SmartMemory tenant and a decision about
+ * what a remote store does with per-document text. The preamble is not a
+ * property of the idea corpus at all — it is a property of THIS FILE, and the
+ * file is local no matter which provider holds the records.
+ *
+ * The projection therefore stays independent of its destination: it is rendered
+ * from the records plus this sidecar, and a hand edit to the file's heading is
+ * still discarded by the next render, exactly as a hand edit to an idea is.
+ *
+ * WHY IT IS TRACKED, AND NOT BESIDE THE MANIFEST
+ * ----------------------------------------------
+ * The first version of this put the sidecar in gitignored `.compose/data/`,
+ * next to the migration manifest, keyed off `provider.lockPath`. That was
+ * wrong twice.
+ *
+ * It made a TRACKED projection depend on UNTRACKED input. The heading then
+ * survived only on the machine that ran the migration: any other clone — a
+ * teammate, CI — found no sidecar, rendered the template over the custom
+ * heading and committed that, and the migrating machine restored it on its next
+ * render. FU-4's own defect, recurring on every clone, plus git churn on a
+ * tracked file. This is the exact failure the owner already ruled on: records
+ * were moved OUT of gitignored `vision-state.json` in the S3 entry-gate ruling
+ * of 2026-08-04 (see the header of `local-provider.js`) because canon that a
+ * tracked file is generated from cannot itself be ignored. The manifest is a
+ * fair neighbour for none of this: it is TRANSIENT, alive only between the
+ * start and the end of one import, while the preamble is durable content with
+ * the same lifecycle as the records.
+ *
+ * And keying off `provider.lockPath` excluded SmartMemory, which has no lock —
+ * the very provider whose existence was the argument for a local sidecar rather
+ * than a record. Keyed off the ideabox path instead, every provider gets one.
+ *
+ * Beside the document it describes, it is also discoverable: the hand-written
+ * recovery below is a file someone can find, not a hashed name under a hidden
+ * directory. A deliberately named, deliberately committed file is not the stray
+ * temp file that tracked directories have to be protected from.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+/**
+ * The preamble file for this ideabox: a tracked sibling of it.
+ *
+ * `docs/product/ideabox.md` → `docs/product/ideabox.preamble.md`. Derived from
+ * the ideabox path alone, so it does not depend on which provider holds the
+ * records and every provider gets one. Plain markdown rather than JSON so a
+ * project that has to write one by hand can just write it.
+ */
+export function preamblePath(ideaboxPath) {
+  if (!ideaboxPath) return null;
+  return String(ideaboxPath).replace(/(\.md)?$/i, '.preamble.md');
+}
+
+/**
+ * The generated banner is not part of anyone's introduction.
+ *
+ * A document being imported is normally a legacy one and carries no banner, but
+ * a store whose records were removed re-imports its own PROJECTION — and the
+ * parser hands back everything before `## Ideas`, banner included. Capturing
+ * that would make the next render emit the banner twice, and the one after that
+ * three times.
+ */
+function withoutBanner(text) {
+  const lines = String(text ?? '').split('\n');
+  if (!/^\s*<!--/.test(lines[0] ?? '') || !/GENERATED FILE/.test(lines[0] ?? '')) return text;
+  const end = lines.findIndex((l) => /-->/.test(l));
+  if (end === -1) return text;
+  return lines.slice(end + 1).join('\n').replace(/^\n+/, '');
+}
+
+/**
+ * Capture the source document's own preamble.
+ *
+ * @param {string} ideaboxPath
+ * @param {string} text `parseIdeabox(...).preamble` — the parser's own output,
+ *   never a second scan of the same document. Two readers of one document is
+ *   the exact shape that produced this whole bug class.
+ * @returns {string|null} the path written, or null when there is nothing to
+ *   write or nowhere to write it
+ */
+export function writePreamble(ideaboxPath, text) {
+  const path = preamblePath(ideaboxPath);
+  if (!path) return null;
+  const body = withoutBanner(text);
+  if (!body || !body.trim()) return null;
+  // Nothing to do when it already says this. Same reasoning as the manifest: a
+  // rewrite that changes nothing is a window in which a crash can lose
+  // something, for no gain.
+  if (readPreamble(ideaboxPath) === body) return path;
+
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = `${path}.tmp.${randomUUID()}`;
+  try {
+    writeFileSync(tmp, body, 'utf8');
+    renameSync(tmp, path);
+  } catch (err) {
+    rmSync(tmp, { force: true });
+    throw err;
+  }
+  return path;
+}
+
+/**
+ * The captured preamble, or null.
+ *
+ * Null is the ordinary answer for a project that migrated before this existed,
+ * and it means the renderer falls back to the standard template — which is what
+ * that project already has in its file, so nothing changes for it.
+ */
+export function readPreamble(ideaboxPath) {
+  const path = preamblePath(ideaboxPath);
+  if (!path || !existsSync(path)) return null;
+  try {
+    const text = readFileSync(path, 'utf8');
+    if (!text.trim()) return null;
+    // Trailing blank lines are structural, not content — the renderer puts its
+    // own separator before `## Ideas`, and the parser pops them on the way back
+    // (`lib/ideabox.js`), so leaving one here costs the fixed point that the
+    // whole cutover rests on. `writePreamble` never stores one because it
+    // stores what the parser already popped; a sidecar written BY HAND does,
+    // because every editor ends a file with a newline — and writing one by hand
+    // is the documented recovery for a project that migrated before this
+    // existed.
+    const lines = text.split('\n');
+    while (lines.length && lines.at(-1).trim() === '') lines.pop();
+    return lines.length ? lines.join('\n') : null;
+  } catch {
+    return null;
+  }
+}