@mcptoolshop/style-dataset-lab 3.3.0 → 3.5.0

package/lib/canon-author.js

@@ -0,0 +1,350 @@
+/**
+ * Lane 2 canon and prompt authoring adapter (DESIGN-v3 §3.2, §9.2 item 7, §11, G10).
+ *
+ * Calls a local loopback OpenAI-compatible HTTP endpoint (e.g., llama-server or
+ * Ollama serving Muse-Glimmer-30B-A3B-GGUF under Apache-2.0) to draft visual
+ * canon entries and per-class prompts + negatives.
+ *
+ * Every model-authored output starts with `status: "draft"` and `judgment: null`,
+ * carrying the model name, digest, SPDX licence (`Apache-2.0`), credit note,
+ * `messages_sha256`, and `draft_sha256`.
+ */
+
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { canonicalize } from './freeze-stamp.js';
+import { inputError as rawInputError } from './errors.js';
+
+function inputError(code, msg) {
+  return rawInputError(code, `${code}: ${msg}`);
+}
+
+export const MIN_LLAMA_SERVER_BUILD = 10353;
+
+export const GLIMMER_CREDIT_NOTE =
+  'Canon and prompt drafting assisted by Muse-Glimmer-30B-A3B (GlimmerLabs, Apache-2.0); vision inspection via Qwen3-VL mmproj (Apache-2.0).';
+
+export const GLIMMER_DEFAULT_MODEL = Object.freeze({
+  name: 'Muse-Glimmer-30B-A3B-Q4_K_M.gguf',
+  repo: 'GlimmerLabs/Muse-Glimmer-30B-A3B-GGUF',
+  digest: 'sha256:' + '3'.repeat(64),
+  licence_id: 'Apache-2.0',
+  licence_url: 'https://huggingface.co/GlimmerLabs/Muse-Glimmer-30B-A3B-GGUF/blob/main/LICENSE',
+  date_read: '2026-11-05',
+  credit_note: GLIMMER_CREDIT_NOTE,
+});
+
+export const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1', '[::1]']);
+
+function sha256String(str) {
+  return 'sha256:' + createHash('sha256').update(str, 'utf-8').digest('hex');
+}
+
+function sha256Buffer(buf) {
+  return 'sha256:' + createHash('sha256').update(buf).digest('hex');
+}
+
+function normalizeSha256(val) {
+  if (typeof val !== 'string') return null;
+  const trimmed = val.trim().toLowerCase();
+  const hex = trimmed.startsWith('sha256:') ? trimmed.slice(7) : trimmed;
+  if (!/^[0-9a-f]{64}$/.test(hex)) return null;
+  return `sha256:${hex}`;
+}
+
+/**
+ * Enforce that the Lane 2 LLM endpoint is strictly loopback-bound (§3.2, §6, §11.3).
+ *
+ * @param {string} endpointUrl
+ * @returns {URL}
+ */
+export function assertLoopbackEndpoint(endpointUrl) {
+  let parsed;
+  try {
+    parsed = new URL(endpointUrl);
+  } catch {
+    throw inputError(
+      'LANE2_NON_LOOPBACK_ENDPOINT',
+      `Invalid Lane 2 endpoint URL "${endpointUrl}". Must be http://127.0.0.1:<port>/...`
+    );
+  }
+  const host = parsed.hostname.toLowerCase();
+  if (!LOOPBACK_HOSTS.has(host)) {
+    throw inputError(
+      'LANE2_NON_LOOPBACK_ENDPOINT',
+      `Lane 2 endpoint "${endpointUrl}" binds to non-loopback host "${host}". Must bind to 127.0.0.1.`
+    );
+  }
+  return parsed;
+}
+
+/**
+ * Pre-check the llama.cpp `llama-server` build (`>= b10353` for Qwen3.5 /
+ * Muse-Glimmer-30B-A3B) and optional `mmproj` vision projector (§9.2 item 7, §11.3).
+ *
+ * @param {Object} opts
+ * @param {string|number} opts.llamaServerBuild — e.g. 'b10353' or 10400
+ * @param {boolean} [opts.vision=false] — whether vision inspection / plate reading is active
+ * @param {string} [opts.mmprojPath]
+ * @param {string} [opts.mmprojSha256]
+ * @param {boolean} [opts.verifyFiles=false]
+ * @returns {{ ok: true, buildNumber: number, vision: boolean, mmprojSha256: string|null }}
+ */
+export function verifyGlimmerRuntime({
+  llamaServerBuild,
+  vision = false,
+  mmprojPath = null,
+  mmprojSha256 = null,
+  verifyFiles = false,
+} = {}) {
+  const rawBuild = String(llamaServerBuild ?? '').trim();
+  const match = /(\d{4,6})/.exec(rawBuild);
+  const buildNumber = match ? Number(match[1]) : NaN;
+  if (!Number.isFinite(buildNumber) || buildNumber < MIN_LLAMA_SERVER_BUILD) {
+    throw inputError(
+      'LANE2_LLAMA_SERVER_TOO_OLD',
+      `Muse-Glimmer-30B-A3B (Qwen3.5 architecture) requires llama-server >= b${MIN_LLAMA_SERVER_BUILD}; got "${rawBuild}".`
+    );
+  }
+
+  let normalizedMmprojSha = null;
+  if (vision) {
+    normalizedMmprojSha = normalizeSha256(mmprojSha256);
+    if (!mmprojPath || !normalizedMmprojSha) {
+      throw inputError(
+        'LANE2_MMPROJ_MISSING',
+        'Vision mode on Muse-Glimmer-30B-A3B requires --mmproj (mmproj-F16.gguf or mmproj-BF16.gguf) with a pinned 64-hex sha256.'
+      );
+    }
+    if (verifyFiles) {
+      if (!existsSync(mmprojPath)) {
+        throw inputError('LANE2_MMPROJ_MISSING', `mmproj file not found at "${mmprojPath}".`);
+      }
+      const actualSha = sha256Buffer(readFileSync(mmprojPath));
+      if (actualSha !== normalizedMmprojSha) {
+        throw inputError(
+          'LANE2_MMPROJ_SHA_MISMATCH',
+          `mmproj sha256 mismatch: got ${actualSha}, expected ${normalizedMmprojSha}.`
+        );
+      }
+    }
+  }
+
+  return {
+    ok: true,
+    buildNumber,
+    vision: Boolean(vision),
+    mmprojSha256: normalizedMmprojSha,
+  };
+}
+
+/**
+ * Compute the canonical content hash of a canon/prompt draft so any edit after
+ * Director ratification is detected by the freeze gate.
+ *
+ * @param {Object} draft
+ * @returns {string}
+ */
+const RESERVED_MODEL_KEYS = Object.freeze([
+  'ratification',
+  'judgment',
+  'status',
+  'drafted_by_model',
+  'author_model',
+]);
+
+function stripReservedModelKeys(obj) {
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return {};
+  const cleaned = { ...obj };
+  for (const key of RESERVED_MODEL_KEYS) {
+    delete cleaned[key];
+  }
+  return cleaned;
+}
+
+export function computeDraftContentSha256(draft) {
+  const payload = {
+    class_id: draft.class_id || draft.entry_id || null,
+    prompt: draft.prompt || '',
+    negative_prompt: draft.negative_prompt || '',
+    canon_entry_draft: draft.canon_entry_draft || null,
+    messages_sha256: draft.messages_sha256 || null,
+  };
+  return sha256String(canonicalize(payload));
+}
+
+/**
+ * Build the request messages for drafting a visual canon class and prompt.
+ *
+ * @param {Object} opts
+ * @param {string} opts.classId
+ * @param {string} opts.brief
+ * @param {Object} [opts.canonContext]
+ * @returns {{ messages: Array<Object>, messagesSha256: string }}
+ */
+export function buildCanonDraftMessages({ classId, brief, canonContext = {} }) {
+  const messages = [
+    {
+      role: 'system',
+      content:
+        'You are the sdlab Lane 2 canon and prompt drafter (Muse-Glimmer-30B-A3B, Apache-2.0). ' +
+        'Return strict JSON with keys: class_id, canon_entry_draft, prompt, negative_prompt.',
+    },
+    {
+      role: 'user',
+      content: JSON.stringify({
+        class_id: classId,
+        brief,
+        canon_context: canonContext,
+      }),
+    },
+  ];
+  const messagesSha256 = sha256String(canonicalize(messages));
+  return { messages, messagesSha256 };
+}
+
+/**
+ * Draft a visual canon entry and class prompt via a loopback OpenAI-compatible
+ * endpoint (`http://127.0.0.1:<port>/v1/chat/completions`) (G10, §3.2, §11).
+ *
+ * Always emits `status: "draft"` and `judgment: null`.
+ *
+ * @param {Object} opts
+ * @param {string} opts.endpoint
+ * @param {string} opts.classId
+ * @param {string} opts.brief
+ * @param {Object} [opts.canonContext]
+ * @param {Object} [opts.modelPin]
+ * @param {string} [opts.createdAt]
+ * @returns {Promise<Object>}
+ */
+export async function draftCanonClassViaEndpoint({
+  endpoint,
+  classId,
+  brief,
+  canonContext = {},
+  modelPin = GLIMMER_DEFAULT_MODEL,
+  createdAt = new Date().toISOString(),
+}) {
+  assertLoopbackEndpoint(endpoint);
+  if (!classId || typeof classId !== 'string') {
+    throw inputError('LANE2_CLASS_ID_REQUIRED', 'draftCanonClassViaEndpoint requires a non-empty classId.');
+  }
+  const authorModel = {
+    name: modelPin.name || GLIMMER_DEFAULT_MODEL.name,
+    repo: modelPin.repo || GLIMMER_DEFAULT_MODEL.repo,
+    digest: normalizeSha256(modelPin.digest) || GLIMMER_DEFAULT_MODEL.digest,
+    licence_id: modelPin.licence_id || 'Apache-2.0',
+    licence_url: modelPin.licence_url || GLIMMER_DEFAULT_MODEL.licence_url,
+    date_read: modelPin.date_read || GLIMMER_DEFAULT_MODEL.date_read,
+    credit_note: modelPin.credit_note || GLIMMER_CREDIT_NOTE,
+  };
+  if (authorModel.licence_id !== 'Apache-2.0') {
+    throw inputError(
+      'LANE2_LICENCE_INVALID',
+      `Lane 2 canon authoring model "${authorModel.name}" must carry licence_id "Apache-2.0" (got "${authorModel.licence_id}").`
+    );
+  }
+
+  const { messages, messagesSha256 } = buildCanonDraftMessages({ classId, brief, canonContext });
+
+  const response = await fetch(endpoint, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      model: authorModel.name,
+      temperature: 0.2,
+      top_p: 0.9,
+      messages,
+    }),
+  });
+
+  if (!response.ok) {
+    throw inputError(
+      'LANE2_ENDPOINT_ERROR',
+      `Lane 2 endpoint ${endpoint} returned HTTP ${response.status}.`
+    );
+  }
+
+  const body = await response.json();
+  const rawContent = body?.choices?.[0]?.message?.content || '{}';
+  let parsedContent;
+  try {
+    const rawParsed = typeof rawContent === 'string' ? JSON.parse(rawContent) : rawContent;
+    parsedContent = stripReservedModelKeys(rawParsed);
+  } catch {
+    parsedContent = {
+      prompt: String(rawContent),
+      negative_prompt: '',
+      canon_entry_draft: { id: classId, notes: String(rawContent) },
+    };
+  }
+
+  const rawCanonEntry =
+    parsedContent.canon_entry_draft &&
+    typeof parsedContent.canon_entry_draft === 'object' &&
+    !Array.isArray(parsedContent.canon_entry_draft)
+      ? stripReservedModelKeys(parsedContent.canon_entry_draft)
+      : { id: classId };
+  const canonEntryDraft = {
+    ...rawCanonEntry,
+    id: rawCanonEntry.id || classId,
+    status: 'draft',
+    drafted_by_model: authorModel.name,
+    author_model: authorModel,
+  };
+
+  const draftBase = {
+    draft_id: `draft_${classId}`,
+    class_id: classId,
+    entry_id: classId,
+    status: 'draft',
+    judgment: null,
+    prompt: parsedContent.prompt || '',
+    negative_prompt: parsedContent.negative_prompt || '',
+    canon_entry_draft: canonEntryDraft,
+    drafted_by_model: authorModel.name,
+    author_model: authorModel,
+    messages_sha256: messagesSha256,
+    created_at: createdAt,
+  };
+
+  const draftSha256 = computeDraftContentSha256(draftBase);
+  return {
+    ...draftBase,
+    draft_sha256: draftSha256,
+  };
+}
+
+/**
+ * Write `prompts.jsonl` and its companion `prompts.jsonl.sha256` (§7).
+ *
+ * @param {string} promptsPath
+ * @param {Array<Object>} drafts
+ * @returns {{ promptsPath: string, sha256Path: string, sha256: string }}
+ */
+export function writePromptsJsonl(promptsPath, drafts) {
+  mkdirSync(dirname(promptsPath), { recursive: true });
+  const content = drafts.map((d) => JSON.stringify(d)).join('\n') + '\n';
+  writeFileSync(promptsPath, content, 'utf-8');
+  const digest = sha256String(content);
+  const sha256Path = `${promptsPath}.sha256`;
+  writeFileSync(sha256Path, `${digest}  prompts.jsonl\n`, 'utf-8');
+  return { promptsPath, sha256Path, sha256: digest };
+}
+
+/**
+ * Read `prompts.jsonl` rows from disk.
+ *
+ * @param {string} promptsPath
+ * @returns {Array<Object>}
+ */
+export function readPromptsJsonl(promptsPath) {
+  const raw = readFileSync(promptsPath, 'utf-8');
+  return raw
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .map((line) => JSON.parse(line));
+}

package/lib/canon-build/build.js

@@ -91,12 +91,34 @@ export async function runBuild(opts) {
   const entries = [];
   const schemaChangeTriggersFullRebuild = await detectSchemaChange(projectRoot, schemas, full);
 
+  // Entity ids must be unique across the ENTIRE canon tree, not just within
+  // one schema's subdirectory: they key prompts/<id>.j2, context/<id>.md, and
+  // manifest.per_entity_hashes, all of which are flat maps keyed by id alone.
+  // Two entries sharing an id (e.g. a forgotten `id:` edit after cloning an
+  // existing file) would silently overwrite each other's prompt/context
+  // output and collide in the manifest (last write wins), while
+  // dataset/all.jsonl would keep rows for both under the one id — so a row
+  // permanently points at the wrong entry's content. Catch this at discovery
+  // time, before any output is written.
+  const seenIds = new Map(); // id -> first-seen filePath
+
   for (const [schemaName, subdir] of Object.entries(config.entity_dirs)) {
     const dir = join(config.canon_root, subdir);
     const loaded = await loadCanonEntriesInDir(dir);
     for (const entry of loaded) {
       const id = entryId(entry);
       if (only && !only.includes(id)) continue;
+      if (seenIds.has(id)) {
+        throw inputError(
+          'CANON_DUPLICATE_ENTITY_ID',
+          `Duplicate canon entity id "${id}": both ${seenIds.get(id)} and ${entry.filePath} ` +
+            `resolve to this id.`,
+          `Give one of these entries a unique "id:" field in its frontmatter. IDs must be ` +
+            `unique across the whole canon tree — they key prompts/, context/, and ` +
+            `manifest.per_entity_hashes, all flat maps with no per-schema namespacing.`,
+        );
+      }
+      seenIds.set(id, entry.filePath);
       entries.push({ entry, schemaName, id });
     }
   }
@@ -166,9 +188,17 @@ export async function runBuild(opts) {
       || entry.frontmatter.reference_plate_uri
       || null;
 
-    // Build the row
+    // Build the row. `id` is the RESOLVED id (frontmatter.id, falling back to
+    // the filename stem — see entryId() in load-entry.js), which is what the
+    // prompts/<id>.j2 and context/<id>.md files below are actually named
+    // with. canonEntryToRow() (lib/rows.js) reads `entry.id` for entity_id —
+    // passing the raw entry.frontmatter would leave entity_id undefined for
+    // any entry that relies on the filename-stem fallback (no explicit
+    // `id:` field), and serializeRow() drops undefined fields entirely, so
+    // the row would orphan itself from its own correctly-named prompt/context
+    // files. Overlay the resolved id so the row always carries it.
     const row = canonEntryToRow({
-      entry: entry.frontmatter,
+      entry: { ...entry.frontmatter, id },
       schemaKind: rendered.schemaKind,
       assetPath: refPath,
       lane,
@@ -212,104 +242,127 @@ export async function runBuild(opts) {
   }
 
   // Write to staging, then atomic rename.
+  //
+  // M2: everything from here through the rename is wrapped in try/catch.
+  // Before this fix, a throw ANYWHERE in this block (most notably
+  // readFreezeStatus() below, which throws CANON_FREEZE_STATUS_INVALID on a
+  // malformed freeze.status) left `stagingDir` — by then already populated
+  // with dataset/prompts/context — orphaned on disk forever: the only
+  // cleanup is the `rm(stagingDir, ...)` at the top of THIS function, and
+  // that runs against a NEW `${generatedFromDir}.tmp-${process.pid}` path on
+  // the next invocation (a different pid), so it can never match the
+  // orphan. The catch below removes the in-progress staging directory
+  // before rethrowing, and does not touch anything once rename() has
+  // succeeded (stagingDir no longer exists at that point, so the block
+  // exits normally and the catch never runs).
   await rm(stagingDir, { recursive: true, force: true });
-  await mkdir(join(stagingDir, 'dataset'), { recursive: true });
-  await mkdir(join(stagingDir, 'prompts'), { recursive: true });
-  await mkdir(join(stagingDir, 'context'), { recursive: true });
-
-  // Write prompts + context
-  for (const { entry } of entries) {
-    const r = entry._rendered;
-    const id = entry._id;
-    await writeFile(join(stagingDir, 'prompts', `${id}.j2`), r.prompt, 'utf-8');
-    await writeFile(join(stagingDir, 'context', `${id}.md`), r.context, 'utf-8');
-  }
+  // Declared here (not inside the try block) because they're read again
+  // after it, in writeLatestSchemaVersions() and the return value below.
+  let frozenEntriesHashes = {};
+  let drift = [];
+  let manifest;
+  try {
+    await mkdir(join(stagingDir, 'dataset'), { recursive: true });
+    await mkdir(join(stagingDir, 'prompts'), { recursive: true });
+    await mkdir(join(stagingDir, 'context'), { recursive: true });
+
+    // Write prompts + context
+    for (const { entry } of entries) {
+      const r = entry._rendered;
+      const id = entry._id;
+      await writeFile(join(stagingDir, 'prompts', `${id}.j2`), r.prompt, 'utf-8');
+      await writeFile(join(stagingDir, 'context', `${id}.md`), r.context, 'utf-8');
+    }
 
-  // Write dataset.jsonl (all + per-lane-per-partition)
-  const allLines = rows.map((r) => serializeRow(r)).join('\n') + (rows.length ? '\n' : '');
-  await writeFile(join(stagingDir, 'dataset', 'all.jsonl'), allLines, 'utf-8');
+    // Write dataset.jsonl (all + per-lane-per-partition)
+    const allLines = rows.map((r) => serializeRow(r)).join('\n') + (rows.length ? '\n' : '');
+    await writeFile(join(stagingDir, 'dataset', 'all.jsonl'), allLines, 'utf-8');
 
-  // Group by (lane × partition)
-  const byLaneAndPartition = {};
-  for (const row of rows) {
-    const key = `${row.lane}-${row.partition}`;
-    if (!byLaneAndPartition[key]) byLaneAndPartition[key] = [];
-    byLaneAndPartition[key].push(row);
-  }
-  for (const [key, laneRows] of Object.entries(byLaneAndPartition)) {
-    const content = laneRows.map((r) => serializeRow(r)).join('\n') + '\n';
-    await writeFile(join(stagingDir, 'dataset', `${key}.jsonl`), content, 'utf-8');
-  }
+    // Group by (lane × partition)
+    const byLaneAndPartition = {};
+    for (const row of rows) {
+      const key = `${row.lane}-${row.partition}`;
+      if (!byLaneAndPartition[key]) byLaneAndPartition[key] = [];
+      byLaneAndPartition[key].push(row);
+    }
+    for (const [key, laneRows] of Object.entries(byLaneAndPartition)) {
+      const content = laneRows.map((r) => serializeRow(r)).join('\n') + '\n';
+      await writeFile(join(stagingDir, 'dataset', `${key}.jsonl`), content, 'utf-8');
+    }
 
-  // Freeze drift pass — stamp frozen_entries_hashes (D1 witness chain).
-  // For every entry with a non-auto freeze status, compute the watch-hash
-  // of its currently-watched fields. Drift is computed by later builds or
-  // the `sdlab canon drift` command by diffing their hash against this.
-  const frozenEntriesHashes = {};
-  const drift = [];
-  const priorManifest = await loadPreviousManifest(projectRoot, outputDir);
-  for (const { entry, schemaName, id } of entries) {
-    const status = readFreezeStatus(entry.frontmatter);
-    if (status === 'auto') continue;
-    const watchFields = resolveWatchFields(entry.frontmatter, schemaName, config);
-    const watchHash = computeWatchHash(
-      entry.frontmatter,
-      watchFields,
-      schemas[schemaName].version,
-    );
-    frozenEntriesHashes[id] = {
-      status,
-      watch_hash: watchHash,
-      watch_fields: watchFields,
-      locked_at_build: entry.frontmatter.freeze?.locked_at_build || null,
-    };
-    // Compute drift against prior build's stamp, if any.
-    const priorHash = priorManifest?.frozen_entries_hashes?.[id]?.watch_hash;
-    if (priorHash && priorHash !== watchHash) {
-      drift.push({
-        entity_id: id,
-        schema_kind: schemaName.replace('.schema.json', ''),
+    // Freeze drift pass — stamp frozen_entries_hashes (D1 witness chain).
+    // For every entry with a non-auto freeze status, compute the watch-hash
+    // of its currently-watched fields. Drift is computed by later builds or
+    // the `sdlab canon drift` command by diffing their hash against this.
+    const priorManifest = await loadPreviousManifest(projectRoot, outputDir);
+    for (const { entry, schemaName, id } of entries) {
+      const status = readFreezeStatus(entry.frontmatter);
+      if (status === 'auto') continue;
+      const watchFields = resolveWatchFields(entry.frontmatter, schemaName, config);
+      const watchHash = computeWatchHash(
+        entry.frontmatter,
+        watchFields,
+        schemas[schemaName].version,
+      );
+      frozenEntriesHashes[id] = {
         status,
-        prior_hash: priorHash,
-        current_hash: watchHash,
-      });
+        watch_hash: watchHash,
+        watch_fields: watchFields,
+        locked_at_build: entry.frontmatter.freeze?.locked_at_build || null,
+      };
+      // Compute drift against prior build's stamp, if any.
+      const priorHash = priorManifest?.frozen_entries_hashes?.[id]?.watch_hash;
+      if (priorHash && priorHash !== watchHash) {
+        drift.push({
+          entity_id: id,
+          schema_kind: schemaName.replace('.schema.json', ''),
+          status,
+          prior_hash: priorHash,
+          current_hash: watchHash,
+        });
+      }
     }
-  }
 
-  // Write manifest
-  const manifest = {
-    schema_version: BUILD_SCHEMA_VERSION,
-    row_schema_version: ROW_SCHEMA_VERSION,
-    generated_from: generatedFrom,
-    built_at: new Date().toISOString(),
-    project_id: config.project_id,
-    schema_versions: Object.fromEntries(
-      Object.entries(schemas).map(([k, v]) => [k, v.version])
-    ),
-    build_config_hash: buildConfigHash,
-    project_config_fingerprint: projectFingerprint,
-    per_entity_hashes: Object.fromEntries(entries.map(({ entry, id }) => [id, entry._entryHash])),
-    frozen_entries_hashes: frozenEntriesHashes,
-    drift_against_prior: drift,
-    stats: {
-      entities_total: entries.length,
-      entities_cached: cached,
-      entities_rebuilt: rebuilt,
-      dataset_rows: rows.length,
-      frozen_entries: Object.keys(frozenEntriesHashes).length,
-      drifted_entries: drift.length,
-      schema_change_full_rebuild: schemaChangeTriggersFullRebuild,
-    },
-  };
-  await writeFile(
-    join(stagingDir, 'manifest.json'),
-    JSON.stringify(manifest, null, 2) + '\n',
-    'utf-8'
-  );
-
-  // Atomic swap: remove old output, rename staging → output.
-  await rm(outputDir, { recursive: true, force: true });
-  await rename(stagingDir, outputDir);
+    // Write manifest
+    manifest = {
+      schema_version: BUILD_SCHEMA_VERSION,
+      row_schema_version: ROW_SCHEMA_VERSION,
+      generated_from: generatedFrom,
+      built_at: new Date().toISOString(),
+      project_id: config.project_id,
+      schema_versions: Object.fromEntries(
+        Object.entries(schemas).map(([k, v]) => [k, v.version])
+      ),
+      build_config_hash: buildConfigHash,
+      project_config_fingerprint: projectFingerprint,
+      per_entity_hashes: Object.fromEntries(entries.map(({ entry, id }) => [id, entry._entryHash])),
+      frozen_entries_hashes: frozenEntriesHashes,
+      drift_against_prior: drift,
+      stats: {
+        entities_total: entries.length,
+        entities_cached: cached,
+        entities_rebuilt: rebuilt,
+        dataset_rows: rows.length,
+        frozen_entries: Object.keys(frozenEntriesHashes).length,
+        drifted_entries: drift.length,
+        schema_change_full_rebuild: schemaChangeTriggersFullRebuild,
+      },
+    };
+    await writeFile(
+      join(stagingDir, 'manifest.json'),
+      JSON.stringify(manifest, null, 2) + '\n',
+      'utf-8'
+    );
+
+    // Atomic swap: remove old output, rename staging → output.
+    await rm(outputDir, { recursive: true, force: true });
+    await rename(stagingDir, outputDir);
+  } catch (err) {
+    try {
+      await rm(stagingDir, { recursive: true, force: true });
+    } catch { /* best-effort cleanup — surface the original error below regardless */ }
+    throw err;
+  }
 
   // Update the "latest" schema-version snapshot for change detection next run.
   await writeLatestSchemaVersions(projectRoot, manifest.schema_versions);