@try-works/dsh-memory 0.1.19 → 0.1.20

package/src/consolidate.js

@@ -1,330 +1,330 @@
-// Consolidation: prompt builder + lenient summary parser + deterministic apply.
-
-/** Coerce a model-supplied importance into the 1-3 range. */
-function normalizeImportance(value) {
-  const n = Number(value)
-  if (!Number.isFinite(n)) return 2
-  return Math.min(3, Math.max(1, Math.round(n)))
-}
-
-/**
- * Pull every complete top-level JSON object out of a reply. Models routinely emit a
- * valid prefix, echo a placeholder, or get cut off at the token limit; the complete
- * objects are still worth keeping instead of failing the whole pass.
- */
-/** The first complete top-level {...} object, so trailing commentary cannot break a parse. */
-function firstObject(source) {
-  let depth = 0
-  let start = -1
-  let inString = false
-  let escaped = false
-  for (let i = 0; i < source.length; i += 1) {
-    const ch = source[i]
-    if (inString) {
-      if (escaped) escaped = false
-      else if (ch === '\\') escaped = true
-      else if (ch === '"') inString = false
-      continue
-    }
-    if (ch === '"') { inString = true; continue }
-    if (ch === '{') { if (depth === 0) start = i; depth += 1 }
-    else if (ch === '}') {
-      depth -= 1
-      if (depth === 0 && start >= 0) return source.slice(start, i + 1)
-    }
-  }
-  return undefined
-}
-
-function salvageObjects(source) {
-  const out = []
-  const starts = []
-  let inString = false
-  let escaped = false
-  for (let i = 0; i < source.length; i += 1) {
-    const ch = source[i]
-    if (inString) {
-      if (escaped) escaped = false
-      else if (ch === '\\') escaped = true
-      else if (ch === '"') inString = false
-      continue
-    }
-    if (ch === '"') { inString = true; continue }
-    if (ch === '{') { starts.push(i); continue }
-    if (ch === '}') {
-      const start = starts.pop()
-      if (start !== undefined) {
-        try { out.push({ value: JSON.parse(source.slice(start, i + 1)), start }) } catch {}
-      }
-    }
-  }
-  return out
-}
-
-/**
- * Repair the model-authored JSON defects seen in practice. Applied only after an
- * exact parse has already failed, so a valid reply is never touched.
- */
-function repairJson(text) {
-  return String(text ?? '')
-    .replace(/,\s*([}\]])/g, '$1')
-    .replace(/("importance"\s*:\s*)([^",}\]\s]+)/g, (match, prefix, value) => {
-      const n = Number(String(value).trim())
-      const safe = Number.isFinite(n) ? Math.min(3, Math.max(1, Math.round(n))) : 2
-      return prefix + String(safe)
-    })
-}
-// The LLM returns a JSON change summary; the writer applies it via remember() so the
-// write path stays deterministic (the LLM decides, the plugin writes).
-import { remember } from './remember.js'
-
-export const FORMAT_SPEC = [
-  'Entry format (Format 2), one entry per layer file:',
-  '## <heading>',
-  '**Id:** <scopeId>-<layer>-<NNNN>',
-  '**Source:** <source>',
-  '**Date:** <iso>',
-  '**Updated:** <iso>',
-  '**Importance:** 1-3',
-  '**Status:** active',
-  '**Format:** 2',
-  '',
-  '<content>',
-  '',
-  '- The writer allocates Id; you only name scope/key/layer/topic/text.',
-  '- scopeId is "global" or the workspace key; layer is semantic|episodic|procedural|learning.',
-  '- Source cites the originating session.',
-  '- Importance 1=routine, 2=notable, 3=critical/standing.',
-  '- Optional **Valid-until:** <iso> for facts that expire.',
-  '- Never delete history; supersede instead of delete.',
-  '- Omit trivia, junk, filler, and duplicates; provenance is required.',
-].join('\n')
-
-/** The reply protocol the model is asked to follow. */
-export const REPLY_SPEC = [
-  'Reply with ONE LINE PER FACT. No JSON, no prose, no preamble, no code fences.',
-  '',
-  'Each fact line looks exactly like:',
-  '- [<digest id> | global | <layer> | <importance> | <volatility>] <topic> :: <text>',
-  '- [<digest id> | workspace:<key> | <layer> | <importance> | <volatility>] <topic> :: <text>',
-  '',
-  'Then one line per digest you were given:',
-  'DONE <digest id>',
-  '(include digests that held nothing durable)',
-  '',
-  'Rules:',
-  '- Copy the digest id EXACTLY as it appears in the heading below; every fact line carries one.',
-  '- A workspace key is a SHORT SLUG (letters, digits and dashes), never a filesystem path.',
-  '- Use the workspace key named in a digest heading for the facts of that digest.',
-  '  Write global when the heading names no workspace, or when the fact is not repo-specific.',
-  '- layer is semantic (durable facts), episodic (what happened), procedural (how to do things),',
-  '  learning (a lesson) or decision (a settled choice: dependencies, conventions, architecture).',
-  '- A decision is a CHOICE plus why it won, not a fact about how something works. Write one when',
-  '  the session settled a question future work must respect.',
-  '- importance is 1 (routine), 2 (notable) or 3 (critical).',
-  '  volatility is how fast the fact decays:',
-  '  stable (years - a language, a license, a convention),',
-  '  normal (months - how a subsystem works),',
-  '  volatile (days - a port, a version in flight, anything that will be untrue soon).',
-  '- <topic> is a short heading; <text> is the fact itself. Separate them with " :: ".',
-  '- layer codebase maps the workspace: what a module or subsystem does. Its <topic> is the file',
-  '  path or subsystem name, and it needs a workspace key (never global).',
-  '- Never delete history: supersede instead of delete. Omit trivia, junk, filler and duplicates.',
-  '- Writing NO fact lines is a correct and expected reply. Many sessions hold nothing durable;',
-  '  in that case reply with just the DONE lines and nothing else.',
-  '  Never invent a fact, and never restate something already in the store merely to produce output.',
-  '- Never output a <...> placeholder literally, and never repeat these instructions back.',
-].join('\n')
-
-/**
- * Guidance for a BACKFILL of historical sessions.
- *
- * A backfill is not a live pass. Live consolidation keeps up with work as it happens, so it can
- * afford detail. A backfill reconstructs months at once, where completeness would flood the
- * store with facts that were only interesting at the time. The bar is raised instead: keep the
- * few things that would still change a decision later, and let the rest go.
- */
-export const BACKFILL_GUIDANCE = [
-  'This pass is a BACKFILL of historical sessions, not live work.',
-  'Keep only what would still change a decision months from now: a constraint, a settled',
-  '  choice, an environment fact, or how a subsystem works.',
-  'Prefer 1-3 facts per digest. Skipping narrative, progress and anything superseded since.',
-  'Returning no facts at all is correct when a digest holds nothing at that bar.',
-].join(String.fromCharCode(10))
-
-export function buildConsolidatePrompt({ digests = [], indexHeads = [], guidance } = {}) {
-  return [
-    'You are consolidating new session activity into a durable memory store.',
-  '  Most of what happens in a session is NOT memory. Find the small durable part, or correctly',
-  '  conclude that there is none.',
-    'You decide WHAT is durable and name the fields. The writer renders the markdown entry,',
-    'allocates its id and dates, and routes it to the right layer file.',
-    '',
-    // Callers may tighten the bar for a specific pass - a backfill of historical sessions,
-    // for instance, should add the few facts that still matter rather than reconstruct every
-    // session in full. Absent guidance, the standing contract applies unchanged.
-    ...(guidance ? [guidance, ''] : []),
-    REPLY_SPEC,
-    '',
-    '## Existing index (heads only, for dedup + routing)',
-    indexHeads.length ? indexHeads.join('\n') : '(none)',
-    '',
-    '## New session digests',
-    digests.map((d) => '### ' + (d.title || d.sessionId)
-      + (d.workspace ? ' (workspace key: ' + d.workspace + ')' : ' (no workspace)')
-      + '\n' + d.text).join('\n\n'),
-    '',
-    'Now reply with the fact lines and the DONE lines. Nothing else.',
-  ].join('\n')
-}
-
-/** Lenient JSON parse: strips an optional code fence, then grabs the first {…} object. */
-/**
- * Read the line protocol: one "[digest | scope | layer | importance] topic :: text" per fact,
- * plus "DONE <digest>" lines. Per line, so one malformed fact cannot kill the batch, and
- * prose is ignored rather than mined.
- * @returns the summary, or null when the reply carries nothing usable.
- */
-export function parseFactLines(text) {
-  const entries = []
-  const learnings = []
-  const digests = new Set()
-  for (const raw of String(text ?? '').split('\n')) {
-    const line = raw.trim()
-    const done = /^DONE\s+(\S+)\s*$/i.exec(line)
-    if (done) { digests.add(done[1]); continue }
-    const fact = /^[-*]\s*\[\s*([^|\]]+?)\s*\|\s*([^|\]]+?)\s*\|\s*([^|\]]+?)\s*\|\s*(\d+)\s*(?:\|\s*([a-z]+)\s*)?\]\s*(.+)$/.exec(line)
-    if (!fact) continue
-    const digest = fact[1].trim()
-    const scopeToken = fact[2].trim()
-    const layer = fact[3].trim().toLowerCase()
-    const volatility = fact[5] ? String(fact[5]).trim().toLowerCase() : undefined
-    const rest = fact[6].trim()
-    const split = rest.indexOf('::')
-    const topic = (split >= 0 ? rest.slice(0, split) : rest).trim()
-    const body = (split >= 0 ? rest.slice(split + 2) : rest).trim()
-    if (body === '' || looksLikePlaceholder(body)) continue
-    const item = {
-      digest, layer,
-      topic: topic === '' ? undefined : topic,
-      text: body,
-      importance: normalizeImportance(fact[4]),
-      ...(volatility ? { volatility } : {}),
-      scope: scopeToken.startsWith('workspace:') ? 'workspace' : 'global',
-      ...scopeToken.startsWith('workspace:') ? { key: scopeToken.slice('workspace:'.length).trim() } : {},
-    }
-    digests.add(digest)
-    if (layer === 'learning') learnings.push(item)
-    else entries.push(item)
-  }
-  if (entries.length === 0 && learnings.length === 0 && digests.size === 0) return null
-  return {
-    entries, learnings, digests: [...digests],
-    skipped: 0, junk: 0, filler: 0, contradictions: 0, protocol: 'lines',
-  }
-}
-
-/** An item still carrying <...> markers is the instructions echoed back, not data. */
-function looksLikePlaceholder(text) {
-  return /[<>]/.test(String(text ?? ''))
-}
-export function parseChangeSummary(text) {
-  const src = String(text ?? '')
-  const FENCE = '\u0060\u0060\u0060' // three backticks, without literal backticks in source
-  const fenced = src.match(new RegExp(FENCE + '(?:json)?\\s*([\\s\\S]*?)' + FENCE, 'i'))
-  const body = (fenced ? fenced[1] : src).trim()
-  if (body === '') return null
-  // A JSON object is still accepted, because some models volunteer one. The documented
-  // reply is the line protocol, which needs no brace matching at all. Anything else is
-  // prose: earlier this mined any brace-delimited text, which turned a reasoning preamble
-  // (and the echoed prompt example) into real entries.
-  if (!body.startsWith('{')) return parseFactLines(body)
-  const candidate = firstObject(body) ?? body
-  const normalized = (parsed) => {
-    const usable = (item) => item && !looksLikePlaceholder(item.text) && !looksLikePlaceholder(item.topic)
-    const entries = (Array.isArray(parsed.entries) ? parsed.entries : []).filter(usable)
-    const learnings = (Array.isArray(parsed.learnings) ? parsed.learnings : []).filter(usable)
-    // Attribution: a digest is only finished when the model either produced entries
-    // from it or explicitly reported handling it. Anything else is retried.
-    const digests = new Set(Array.isArray(parsed.handledDigests) ? parsed.handledDigests.map(String) : [])
-    for (const item of [...entries, ...learnings]) if (item && item.digest) digests.add(String(item.digest))
-    return {
-      entries, learnings, digests: [...digests],
-      skipped: parsed.skipped ?? 0,
-      junk: parsed.junk ?? 0,
-      filler: parsed.filler ?? 0,
-      contradictions: parsed.contradictions ?? 0,
-    }
-  }
-
-  // Escalating recovery: exact, then repaired, then whatever complete objects remain -
-  // but only when the reply is actually JSON-shaped. Prose that merely contains braces
-  // (an echoed example, a reasoning preamble) must not be mined for entries.
-  const jsonShaped = candidate.trim().startsWith('{')
-
-  for (const attempt of [candidate, repairJson(candidate)]) {
-    try { return normalized(JSON.parse(attempt)) } catch {}
-  }
-  const repaired = repairJson(candidate)
-  // Learnings may omit `layer`, so fall back to position: anything after the
-  // "learnings" key came from that array.
-  const learningsAt = repaired.indexOf('"learnings"')
-  const usable = jsonShaped ? salvageObjects(repaired).filter((o) => {
-    const value = o.value
-    if (!value || typeof value.text !== 'string' || value.text.trim() === '') return false
-    // An object still carrying <...> markers is the prompt example, not data.
-    return !/[<>]/.test(value.text) && !/[<>]/.test(String(value.topic === undefined ? '' : value.topic))
-  }) : []
-  if (usable.length === 0) return null
-  const isLearning = (o) => o.value.layer === 'learning' || (learningsAt >= 0 && o.start > learningsAt)
-  const learnings = usable.filter(isLearning).map((o) => o.value)
-  const entries = usable.filter((o) => !isLearning(o)).map((o) => o.value)
-  const digests = new Set()
-  for (const item of usable) if (item.value.digest) digests.add(String(item.value.digest))
-  return {
-    entries, learnings, digests: [...digests],
-    skipped: 0, junk: 0, filler: 0, contradictions: 0, salvaged: true,
-  }
-}
-
-/** Deterministically write a parsed change summary into the store. Returns written ids. */
-/**
- * Deterministically write a parsed change summary into the store.
- * @param summary - parsed reply; entries may carry the digest they came from.
- * @param options.fallbackSource - provenance when an item names no digest.
- * @returns the written ids; a per-item failure is recorded on `failed`, never thrown.
- */
-export function applyConsolidation(store, summary, options = {}) {
-  const written = []
-  const failed = []
-  const write = (item, layer) => {
-    // Cite the digest the fact came from, so the entry is traceable back to the session
-    // instead of being stamped "manual" like a hand-written one.
-    const source = item.digest ? 'digest:' + String(item.digest) : (options.fallbackSource ?? 'manual')
-    const key = item.key === null ? undefined : item.key
-    // A workspace request without a usable key cannot be honoured; keep the fact in
-    // global rather than throwing away the whole entry.
-    const scope = item.scope === 'workspace' && key ? 'workspace' : 'global'
-    try {
-      const r = remember(store, {
-        scope,
-        key: scope === 'workspace' ? key : undefined,
-        layer,
-        text: item.text,
-        topic: item.topic,
-        importance: normalizeImportance(item.importance),
-        volatility: item.volatility,
-        until: item.until === null ? undefined : item.until,
-        source,
-      })
-      written.push(r.id)
-    } catch (error) {
-      // One malformed item must not fail the whole consolidation pass.
-      failed.push(String((error && error.message) || error).slice(0, 160))
-    }
-  }
-  for (const e of summary.entries ?? []) write(e, e.layer)
-  for (const l of summary.learnings ?? []) write(l, 'learning')
-  written.failed = failed
-  return written
-}
+// Consolidation: prompt builder + lenient summary parser + deterministic apply.
+
+/** Coerce a model-supplied importance into the 1-3 range. */
+function normalizeImportance(value) {
+  const n = Number(value)
+  if (!Number.isFinite(n)) return 2
+  return Math.min(3, Math.max(1, Math.round(n)))
+}
+
+/**
+ * Pull every complete top-level JSON object out of a reply. Models routinely emit a
+ * valid prefix, echo a placeholder, or get cut off at the token limit; the complete
+ * objects are still worth keeping instead of failing the whole pass.
+ */
+/** The first complete top-level {...} object, so trailing commentary cannot break a parse. */
+function firstObject(source) {
+  let depth = 0
+  let start = -1
+  let inString = false
+  let escaped = false
+  for (let i = 0; i < source.length; i += 1) {
+    const ch = source[i]
+    if (inString) {
+      if (escaped) escaped = false
+      else if (ch === '\\') escaped = true
+      else if (ch === '"') inString = false
+      continue
+    }
+    if (ch === '"') { inString = true; continue }
+    if (ch === '{') { if (depth === 0) start = i; depth += 1 }
+    else if (ch === '}') {
+      depth -= 1
+      if (depth === 0 && start >= 0) return source.slice(start, i + 1)
+    }
+  }
+  return undefined
+}
+
+function salvageObjects(source) {
+  const out = []
+  const starts = []
+  let inString = false
+  let escaped = false
+  for (let i = 0; i < source.length; i += 1) {
+    const ch = source[i]
+    if (inString) {
+      if (escaped) escaped = false
+      else if (ch === '\\') escaped = true
+      else if (ch === '"') inString = false
+      continue
+    }
+    if (ch === '"') { inString = true; continue }
+    if (ch === '{') { starts.push(i); continue }
+    if (ch === '}') {
+      const start = starts.pop()
+      if (start !== undefined) {
+        try { out.push({ value: JSON.parse(source.slice(start, i + 1)), start }) } catch {}
+      }
+    }
+  }
+  return out
+}
+
+/**
+ * Repair the model-authored JSON defects seen in practice. Applied only after an
+ * exact parse has already failed, so a valid reply is never touched.
+ */
+function repairJson(text) {
+  return String(text ?? '')
+    .replace(/,\s*([}\]])/g, '$1')
+    .replace(/("importance"\s*:\s*)([^",}\]\s]+)/g, (match, prefix, value) => {
+      const n = Number(String(value).trim())
+      const safe = Number.isFinite(n) ? Math.min(3, Math.max(1, Math.round(n))) : 2
+      return prefix + String(safe)
+    })
+}
+// The LLM returns a JSON change summary; the writer applies it via remember() so the
+// write path stays deterministic (the LLM decides, the plugin writes).
+import { remember } from './remember.js'
+
+export const FORMAT_SPEC = [
+  'Entry format (Format 2), one entry per layer file:',
+  '## <heading>',
+  '**Id:** <scopeId>-<layer>-<NNNN>',
+  '**Source:** <source>',
+  '**Date:** <iso>',
+  '**Updated:** <iso>',
+  '**Importance:** 1-3',
+  '**Status:** active',
+  '**Format:** 2',
+  '',
+  '<content>',
+  '',
+  '- The writer allocates Id; you only name scope/key/layer/topic/text.',
+  '- scopeId is "global" or the workspace key; layer is semantic|episodic|procedural|learning.',
+  '- Source cites the originating session.',
+  '- Importance 1=routine, 2=notable, 3=critical/standing.',
+  '- Optional **Valid-until:** <iso> for facts that expire.',
+  '- Never delete history; supersede instead of delete.',
+  '- Omit trivia, junk, filler, and duplicates; provenance is required.',
+].join('\n')
+
+/** The reply protocol the model is asked to follow. */
+export const REPLY_SPEC = [
+  'Reply with ONE LINE PER FACT. No JSON, no prose, no preamble, no code fences.',
+  '',
+  'Each fact line looks exactly like:',
+  '- [<digest id> | global | <layer> | <importance> | <volatility>] <topic> :: <text>',
+  '- [<digest id> | workspace:<key> | <layer> | <importance> | <volatility>] <topic> :: <text>',
+  '',
+  'Then one line per digest you were given:',
+  'DONE <digest id>',
+  '(include digests that held nothing durable)',
+  '',
+  'Rules:',
+  '- Copy the digest id EXACTLY as it appears in the heading below; every fact line carries one.',
+  '- A workspace key is a SHORT SLUG (letters, digits and dashes), never a filesystem path.',
+  '- Use the workspace key named in a digest heading for the facts of that digest.',
+  '  Write global when the heading names no workspace, or when the fact is not repo-specific.',
+  '- layer is semantic (durable facts), episodic (what happened), procedural (how to do things),',
+  '  learning (a lesson) or decision (a settled choice: dependencies, conventions, architecture).',
+  '- A decision is a CHOICE plus why it won, not a fact about how something works. Write one when',
+  '  the session settled a question future work must respect.',
+  '- importance is 1 (routine), 2 (notable) or 3 (critical).',
+  '  volatility is how fast the fact decays:',
+  '  stable (years - a language, a license, a convention),',
+  '  normal (months - how a subsystem works),',
+  '  volatile (days - a port, a version in flight, anything that will be untrue soon).',
+  '- <topic> is a short heading; <text> is the fact itself. Separate them with " :: ".',
+  '- layer codebase maps the workspace: what a module or subsystem does. Its <topic> is the file',
+  '  path or subsystem name, and it needs a workspace key (never global).',
+  '- Never delete history: supersede instead of delete. Omit trivia, junk, filler and duplicates.',
+  '- Writing NO fact lines is a correct and expected reply. Many sessions hold nothing durable;',
+  '  in that case reply with just the DONE lines and nothing else.',
+  '  Never invent a fact, and never restate something already in the store merely to produce output.',
+  '- Never output a <...> placeholder literally, and never repeat these instructions back.',
+].join('\n')
+
+/**
+ * Guidance for a BACKFILL of historical sessions.
+ *
+ * A backfill is not a live pass. Live consolidation keeps up with work as it happens, so it can
+ * afford detail. A backfill reconstructs months at once, where completeness would flood the
+ * store with facts that were only interesting at the time. The bar is raised instead: keep the
+ * few things that would still change a decision later, and let the rest go.
+ */
+export const BACKFILL_GUIDANCE = [
+  'This pass is a BACKFILL of historical sessions, not live work.',
+  'Keep only what would still change a decision months from now: a constraint, a settled',
+  '  choice, an environment fact, or how a subsystem works.',
+  'Prefer 1-3 facts per digest. Skipping narrative, progress and anything superseded since.',
+  'Returning no facts at all is correct when a digest holds nothing at that bar.',
+].join(String.fromCharCode(10))
+
+export function buildConsolidatePrompt({ digests = [], indexHeads = [], guidance } = {}) {
+  return [
+    'You are consolidating new session activity into a durable memory store.',
+  '  Most of what happens in a session is NOT memory. Find the small durable part, or correctly',
+  '  conclude that there is none.',
+    'You decide WHAT is durable and name the fields. The writer renders the markdown entry,',
+    'allocates its id and dates, and routes it to the right layer file.',
+    '',
+    // Callers may tighten the bar for a specific pass - a backfill of historical sessions,
+    // for instance, should add the few facts that still matter rather than reconstruct every
+    // session in full. Absent guidance, the standing contract applies unchanged.
+    ...(guidance ? [guidance, ''] : []),
+    REPLY_SPEC,
+    '',
+    '## Existing index (heads only, for dedup + routing)',
+    indexHeads.length ? indexHeads.join('\n') : '(none)',
+    '',
+    '## New session digests',
+    digests.map((d) => '### ' + (d.title || d.sessionId)
+      + (d.workspace ? ' (workspace key: ' + d.workspace + ')' : ' (no workspace)')
+      + '\n' + d.text).join('\n\n'),
+    '',
+    'Now reply with the fact lines and the DONE lines. Nothing else.',
+  ].join('\n')
+}
+
+/** Lenient JSON parse: strips an optional code fence, then grabs the first {…} object. */
+/**
+ * Read the line protocol: one "[digest | scope | layer | importance] topic :: text" per fact,
+ * plus "DONE <digest>" lines. Per line, so one malformed fact cannot kill the batch, and
+ * prose is ignored rather than mined.
+ * @returns the summary, or null when the reply carries nothing usable.
+ */
+export function parseFactLines(text) {
+  const entries = []
+  const learnings = []
+  const digests = new Set()
+  for (const raw of String(text ?? '').split('\n')) {
+    const line = raw.trim()
+    const done = /^DONE\s+(\S+)\s*$/i.exec(line)
+    if (done) { digests.add(done[1]); continue }
+    const fact = /^[-*]\s*\[\s*([^|\]]+?)\s*\|\s*([^|\]]+?)\s*\|\s*([^|\]]+?)\s*\|\s*(\d+)\s*(?:\|\s*([a-z]+)\s*)?\]\s*(.+)$/.exec(line)
+    if (!fact) continue
+    const digest = fact[1].trim()
+    const scopeToken = fact[2].trim()
+    const layer = fact[3].trim().toLowerCase()
+    const volatility = fact[5] ? String(fact[5]).trim().toLowerCase() : undefined
+    const rest = fact[6].trim()
+    const split = rest.indexOf('::')
+    const topic = (split >= 0 ? rest.slice(0, split) : rest).trim()
+    const body = (split >= 0 ? rest.slice(split + 2) : rest).trim()
+    if (body === '' || looksLikePlaceholder(body)) continue
+    const item = {
+      digest, layer,
+      topic: topic === '' ? undefined : topic,
+      text: body,
+      importance: normalizeImportance(fact[4]),
+      ...(volatility ? { volatility } : {}),
+      scope: scopeToken.startsWith('workspace:') ? 'workspace' : 'global',
+      ...scopeToken.startsWith('workspace:') ? { key: scopeToken.slice('workspace:'.length).trim() } : {},
+    }
+    digests.add(digest)
+    if (layer === 'learning') learnings.push(item)
+    else entries.push(item)
+  }
+  if (entries.length === 0 && learnings.length === 0 && digests.size === 0) return null
+  return {
+    entries, learnings, digests: [...digests],
+    skipped: 0, junk: 0, filler: 0, contradictions: 0, protocol: 'lines',
+  }
+}
+
+/** An item still carrying <...> markers is the instructions echoed back, not data. */
+function looksLikePlaceholder(text) {
+  return /[<>]/.test(String(text ?? ''))
+}
+export function parseChangeSummary(text) {
+  const src = String(text ?? '')
+  const FENCE = '\u0060\u0060\u0060' // three backticks, without literal backticks in source
+  const fenced = src.match(new RegExp(FENCE + '(?:json)?\\s*([\\s\\S]*?)' + FENCE, 'i'))
+  const body = (fenced ? fenced[1] : src).trim()
+  if (body === '') return null
+  // A JSON object is still accepted, because some models volunteer one. The documented
+  // reply is the line protocol, which needs no brace matching at all. Anything else is
+  // prose: earlier this mined any brace-delimited text, which turned a reasoning preamble
+  // (and the echoed prompt example) into real entries.
+  if (!body.startsWith('{')) return parseFactLines(body)
+  const candidate = firstObject(body) ?? body
+  const normalized = (parsed) => {
+    const usable = (item) => item && !looksLikePlaceholder(item.text) && !looksLikePlaceholder(item.topic)
+    const entries = (Array.isArray(parsed.entries) ? parsed.entries : []).filter(usable)
+    const learnings = (Array.isArray(parsed.learnings) ? parsed.learnings : []).filter(usable)
+    // Attribution: a digest is only finished when the model either produced entries
+    // from it or explicitly reported handling it. Anything else is retried.
+    const digests = new Set(Array.isArray(parsed.handledDigests) ? parsed.handledDigests.map(String) : [])
+    for (const item of [...entries, ...learnings]) if (item && item.digest) digests.add(String(item.digest))
+    return {
+      entries, learnings, digests: [...digests],
+      skipped: parsed.skipped ?? 0,
+      junk: parsed.junk ?? 0,
+      filler: parsed.filler ?? 0,
+      contradictions: parsed.contradictions ?? 0,
+    }
+  }
+
+  // Escalating recovery: exact, then repaired, then whatever complete objects remain -
+  // but only when the reply is actually JSON-shaped. Prose that merely contains braces
+  // (an echoed example, a reasoning preamble) must not be mined for entries.
+  const jsonShaped = candidate.trim().startsWith('{')
+
+  for (const attempt of [candidate, repairJson(candidate)]) {
+    try { return normalized(JSON.parse(attempt)) } catch {}
+  }
+  const repaired = repairJson(candidate)
+  // Learnings may omit `layer`, so fall back to position: anything after the
+  // "learnings" key came from that array.
+  const learningsAt = repaired.indexOf('"learnings"')
+  const usable = jsonShaped ? salvageObjects(repaired).filter((o) => {
+    const value = o.value
+    if (!value || typeof value.text !== 'string' || value.text.trim() === '') return false
+    // An object still carrying <...> markers is the prompt example, not data.
+    return !/[<>]/.test(value.text) && !/[<>]/.test(String(value.topic === undefined ? '' : value.topic))
+  }) : []
+  if (usable.length === 0) return null
+  const isLearning = (o) => o.value.layer === 'learning' || (learningsAt >= 0 && o.start > learningsAt)
+  const learnings = usable.filter(isLearning).map((o) => o.value)
+  const entries = usable.filter((o) => !isLearning(o)).map((o) => o.value)
+  const digests = new Set()
+  for (const item of usable) if (item.value.digest) digests.add(String(item.value.digest))
+  return {
+    entries, learnings, digests: [...digests],
+    skipped: 0, junk: 0, filler: 0, contradictions: 0, salvaged: true,
+  }
+}
+
+/** Deterministically write a parsed change summary into the store. Returns written ids. */
+/**
+ * Deterministically write a parsed change summary into the store.
+ * @param summary - parsed reply; entries may carry the digest they came from.
+ * @param options.fallbackSource - provenance when an item names no digest.
+ * @returns the written ids; a per-item failure is recorded on `failed`, never thrown.
+ */
+export function applyConsolidation(store, summary, options = {}) {
+  const written = []
+  const failed = []
+  const write = (item, layer) => {
+    // Cite the digest the fact came from, so the entry is traceable back to the session
+    // instead of being stamped "manual" like a hand-written one.
+    const source = item.digest ? 'digest:' + String(item.digest) : (options.fallbackSource ?? 'manual')
+    const key = item.key === null ? undefined : item.key
+    // A workspace request without a usable key cannot be honoured; keep the fact in
+    // global rather than throwing away the whole entry.
+    const scope = item.scope === 'workspace' && key ? 'workspace' : 'global'
+    try {
+      const r = remember(store, {
+        scope,
+        key: scope === 'workspace' ? key : undefined,
+        layer,
+        text: item.text,
+        topic: item.topic,
+        importance: normalizeImportance(item.importance),
+        volatility: item.volatility,
+        until: item.until === null ? undefined : item.until,
+        source,
+      })
+      written.push(r.id)
+    } catch (error) {
+      // One malformed item must not fail the whole consolidation pass.
+      failed.push(String((error && error.message) || error).slice(0, 160))
+    }
+  }
+  for (const e of summary.entries ?? []) write(e, e.layer)
+  for (const l of summary.learnings ?? []) write(l, 'learning')
+  written.failed = failed
+  return written
+}