@try-works/dsh-memory 0.1.19 → 0.1.21

package/src/rank.js

@@ -1,31 +1,31 @@
-// Search ranking: importance x recency-decay x bm25-position (pure).
-export const DECAY_HALF_LIFE_DAYS = 30
-
-export function recencyDecay(days, halfLife = DECAY_HALF_LIFE_DAYS) {
-  return Math.pow(2, -days / halfLife)
-}
-
-const DAY_MS = 86400000
-
-/**
- * Re-rank FTS hits using the ledger. Each hit maps to its enclosing entry by
- * (file, line) -> line span; unmapped hits keep importance 2 and "now" recency.
- */
-export function rankBlend(hits, ledger, nowMs = Date.now()) {
-  const byFile = new Map()
-  for (const e of ledger) {
-    const arr = byFile.get(e.file) ?? []
-    arr.push(e)
-    byFile.set(e.file, arr)
-  }
-  const scored = hits.map((h, i) => {
-    const entries = byFile.get(h.file) ?? []
-    const e = entries.find((x) => h.line >= x.startLine && h.line <= x.endLine)
-    const importance = e?.importance ?? 2
-    const updatedAt = e?.updated ? Date.parse(e.updated) : nowMs
-    const days = Math.max(0, (nowMs - updatedAt) / DAY_MS)
-    const score = importance * recencyDecay(days) * (1 / (i + 1))
-    return { ...h, id: e?.id, importance, score }
-  })
-  return scored.sort((a, b) => b.score - a.score)
-}
+// Search ranking: importance x recency-decay x bm25-position (pure).
+export const DECAY_HALF_LIFE_DAYS = 30
+
+export function recencyDecay(days, halfLife = DECAY_HALF_LIFE_DAYS) {
+  return Math.pow(2, -days / halfLife)
+}
+
+const DAY_MS = 86400000
+
+/**
+ * Re-rank FTS hits using the ledger. Each hit maps to its enclosing entry by
+ * (file, line) -> line span; unmapped hits keep importance 2 and "now" recency.
+ */
+export function rankBlend(hits, ledger, nowMs = Date.now()) {
+  const byFile = new Map()
+  for (const e of ledger) {
+    const arr = byFile.get(e.file) ?? []
+    arr.push(e)
+    byFile.set(e.file, arr)
+  }
+  const scored = hits.map((h, i) => {
+    const entries = byFile.get(h.file) ?? []
+    const e = entries.find((x) => h.line >= x.startLine && h.line <= x.endLine)
+    const importance = e?.importance ?? 2
+    const updatedAt = e?.updated ? Date.parse(e.updated) : nowMs
+    const days = Math.max(0, (nowMs - updatedAt) / DAY_MS)
+    const score = importance * recencyDecay(days) * (1 / (i + 1))
+    return { ...h, id: e?.id, importance, score }
+  })
+  return scored.sort((a, b) => b.score - a.score)
+}

package/src/recover.js

@@ -1,91 +1,91 @@
-// Recovering a candidate whose material is gone.
-//
-// An ORPHANED entry is one whose digest no longer exists - normally because pruning removed it.
-// The digest is DERIVED, and the source session survives, so the fix is to rebuild it. That is
-// exactly what was done by hand for the session that became global-sem-0033, and this is that
-// procedure written down.
-//
-// Recovery reads the session through sessionQuery.readSession, which the harness documents as
-// reading a LIVE OR PERSISTED session without making it live. An earlier plan had this walking
-// ~/.dsh/sessions and decompressing multi-frame zstd by hand; the service already does both, and
-// depending on a storage path would have been a dependency on an implementation detail.
-import { existsSync, readdirSync, statSync } from 'node:fs'
-import { homedir } from 'node:os'
-import { join } from 'node:path'
-import { captureSession } from './capture.js'
-import { advance, readQueue, requeue, STATES } from './queue.js'
-
-/** Where DSH keeps session logs, used only to ESTIMATE cost. Never used to read them. */
-export function sessionsRoot(home = homedir()) { return join(home, '.dsh', 'sessions') }
-
-/**
- * Bytes of a session's stored log, or undefined when it cannot be located.
- *
- * Undefined is treated as 'too big to do unasked' by the caller, so an unlocatable log asks for
- * approval rather than proceeding on a guess. Failing closed is the right default for a cost gate.
- */
-export function sessionLogBytes(id, home = homedir()) {
-  const base = sessionsRoot(home)
-  try {
-    for (const project of readdirSync(base)) {
-      const inner = join(base, project, id)
-      if (!existsSync(inner)) continue
-      for (const file of readdirSync(inner)) {
-        if (!file.endsWith('.zstd')) continue
-        return statSync(join(inner, file)).size
-      }
-    }
-  } catch { /* an unreadable tree is the same as an unknown size */ }
-  return undefined
-}
-
-/**
- * What recovery WOULD do, without doing any of it.
- *
- * The dry run exists because the cost is real: the orphaned sessions measured 8-88MB compressed,
- * so recovering every one would decompress hundreds of megabytes and spend a model call each.
- * Reporting first turns that into a decision.
- * @returns { total, recoverable, oversized, missing, entries }
- */
-export function planRecovery(root, options = {}) {
-  const threshold = options.thresholdBytes ?? 8 * 1024 * 1024
-  const bytesOf = options.bytesOf ?? ((id) => sessionLogBytes(id, options.home));
-  const entries = [];
-  let recoverable = 0
-  let oversized = 0
-  let missing = 0
-  for (const entry of readQueue(root).values()) {
-    if (entry.state !== STATES.ORPHANED) continue
-    const bytes = bytesOf(entry.id);
-    const known = typeof bytes === 'number'
-    const needsApproval = !known || bytes >= threshold
-    if (!known) missing += 1;
-    else if (needsApproval) oversized += 1;
-    else recoverable += 1;
-    entries.push({ id: entry.id, bytes, needsApproval, reason: entry.reason });
-  }
-  return { total: entries.length, recoverable, oversized, missing, threshold, entries };
-}
-
-/**
- * Rebuild one orphaned candidate from its source session.
- *
- * The digest is regenerated by CAPTURE, not by a bespoke reader: capture already projects,
- * filters injected context, chooses a model and writes a digest, and every one of those was a
- * bug fixed this session. A second implementation would drift from it immediately.
- *
- * The watermark is reset to -1 first, because the material is gone: whatever capture last
- * recorded about how far it had read no longer describes anything on disk.
- */
-export async function recoverOne(store, services, id, options = {}) {
-  const entry = readQueue(store.root).get(id)
-  if (!entry) throw new Error('memory_recover: ' + id + ' is not in the queue')
-  if (entry.state !== STATES.ORPHANED && entry.state !== STATES.ABANDONED && entry.state !== STATES.FAILED) {
-    throw new Error('memory_recover: ' + id + ' is ' + entry.state + ', which is not work that stopped');
-  }
-  // Back to waiting with NO watermark, so capture re-reads the whole session.
-  requeue(store.root, id, { detail: { lastSeq: -1, recovering: true } });
-  const snapshot = await services.sessionQuery.readSession(id)
-  const header = snapshot?.session ?? {}
-  return captureSession(store, services, { id, header }, options)
-}
+// Recovering a candidate whose material is gone.
+//
+// An ORPHANED entry is one whose digest no longer exists - normally because pruning removed it.
+// The digest is DERIVED, and the source session survives, so the fix is to rebuild it. That is
+// exactly what was done by hand for the session that became global-sem-0033, and this is that
+// procedure written down.
+//
+// Recovery reads the session through sessionQuery.readSession, which the harness documents as
+// reading a LIVE OR PERSISTED session without making it live. An earlier plan had this walking
+// ~/.dsh/sessions and decompressing multi-frame zstd by hand; the service already does both, and
+// depending on a storage path would have been a dependency on an implementation detail.
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { captureSession } from './capture.js'
+import { advance, readQueue, requeue, STATES } from './queue.js'
+
+/** Where DSH keeps session logs, used only to ESTIMATE cost. Never used to read them. */
+export function sessionsRoot(home = homedir()) { return join(home, '.dsh', 'sessions') }
+
+/**
+ * Bytes of a session's stored log, or undefined when it cannot be located.
+ *
+ * Undefined is treated as 'too big to do unasked' by the caller, so an unlocatable log asks for
+ * approval rather than proceeding on a guess. Failing closed is the right default for a cost gate.
+ */
+export function sessionLogBytes(id, home = homedir()) {
+  const base = sessionsRoot(home)
+  try {
+    for (const project of readdirSync(base)) {
+      const inner = join(base, project, id)
+      if (!existsSync(inner)) continue
+      for (const file of readdirSync(inner)) {
+        if (!file.endsWith('.zstd')) continue
+        return statSync(join(inner, file)).size
+      }
+    }
+  } catch { /* an unreadable tree is the same as an unknown size */ }
+  return undefined
+}
+
+/**
+ * What recovery WOULD do, without doing any of it.
+ *
+ * The dry run exists because the cost is real: the orphaned sessions measured 8-88MB compressed,
+ * so recovering every one would decompress hundreds of megabytes and spend a model call each.
+ * Reporting first turns that into a decision.
+ * @returns { total, recoverable, oversized, missing, entries }
+ */
+export function planRecovery(root, options = {}) {
+  const threshold = options.thresholdBytes ?? 8 * 1024 * 1024
+  const bytesOf = options.bytesOf ?? ((id) => sessionLogBytes(id, options.home));
+  const entries = [];
+  let recoverable = 0
+  let oversized = 0
+  let missing = 0
+  for (const entry of readQueue(root).values()) {
+    if (entry.state !== STATES.ORPHANED) continue
+    const bytes = bytesOf(entry.id);
+    const known = typeof bytes === 'number'
+    const needsApproval = !known || bytes >= threshold
+    if (!known) missing += 1;
+    else if (needsApproval) oversized += 1;
+    else recoverable += 1;
+    entries.push({ id: entry.id, bytes, needsApproval, reason: entry.reason });
+  }
+  return { total: entries.length, recoverable, oversized, missing, threshold, entries };
+}
+
+/**
+ * Rebuild one orphaned candidate from its source session.
+ *
+ * The digest is regenerated by CAPTURE, not by a bespoke reader: capture already projects,
+ * filters injected context, chooses a model and writes a digest, and every one of those was a
+ * bug fixed this session. A second implementation would drift from it immediately.
+ *
+ * The watermark is reset to -1 first, because the material is gone: whatever capture last
+ * recorded about how far it had read no longer describes anything on disk.
+ */
+export async function recoverOne(store, services, id, options = {}) {
+  const entry = readQueue(store.root).get(id)
+  if (!entry) throw new Error('memory_recover: ' + id + ' is not in the queue')
+  if (entry.state !== STATES.ORPHANED && entry.state !== STATES.ABANDONED && entry.state !== STATES.FAILED) {
+    throw new Error('memory_recover: ' + id + ' is ' + entry.state + ', which is not work that stopped');
+  }
+  // Back to waiting with NO watermark, so capture re-reads the whole session.
+  requeue(store.root, id, { detail: { lastSeq: -1, recovering: true } });
+  const snapshot = await services.sessionQuery.readSession(id)
+  const header = snapshot?.session ?? {}
+  return captureSession(store, services, { id, header }, options)
+}

package/src/refresh.js

@@ -1,80 +1,80 @@
-// Refresh pass: flag stale/time-bounded entries (freshness), ask the LLM for
-// keep/update/supersede decisions, then apply them deterministically in place.
-import { readFileSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
-import { buildLedger } from './ledger.js'
-import { scanFreshness } from './freshness.js'
-import { setEntryBody, setEntryStatus } from './entry.js'
-import { updateIndex } from './fts.js'
-import { layerIndexPath, rebuildLayerIndexes, scopeOfFile } from './layers.js'
-import { layersForScope } from './entry.js'
-
-export function buildRefreshPrompt(entries) {
-  const lines = [
-    'You are reviewing stale or time-bounded memory entries. For each, decide keep, update, or supersede.',
-    'Return ONLY a JSON object: {"decisions":[{"id":"<entry id>","action":"keep|update|supersede","body":"<new body if update>","reason":"..."}]}',
-    'Rules: update rewrites the body with current facts; supersede marks the entry obsolete (history kept); keep does nothing.',
-    '',
-    'Entries:',
-  ]
-  for (const e of entries) {
-    lines.push('### ' + e.id + ' (' + e.file + ')')
-    lines.push('Verdict: ' + e.verdict)
-    lines.push(e.content)
-    lines.push('')
-  }
-  return lines.join('\n')
-}
-
-export function parseRefreshDecisions(text) {
-  const src = String(text ?? '')
-  const FENCE = '\u0060\u0060\u0060'
-  const fenced = src.match(new RegExp(FENCE + '(?:json)?\\s*([\\s\\S]*?)' + FENCE, 'i'))
-  let candidate = fenced ? fenced[1] : src
-  const obj = candidate.match(/\{[\s\S]*\}/)
-  if (obj) candidate = obj[0]
-  try {
-    const parsed = JSON.parse(candidate)
-    return Array.isArray(parsed.decisions) ? parsed.decisions : []
-  } catch { return [] }
-}
-
-export async function runRefresh(store, { llm, limit = 3, scope, key, nowMs = Date.now() } = {}) {
-  const ledger = buildLedger(store.root)
-  const scoped = scope === 'workspace' && key
-    ? ledger.filter((e) => e.file.startsWith('workspaces/' + key + '/'))
-    : ledger
-  const flagged = scanFreshness(scoped, nowMs).slice(0, limit)
-  if (flagged.length === 0) return { refreshed: 0, updated: 0, superseded: 0 }
-  const text = await llm(buildRefreshPrompt(flagged))
-  const decisions = parseRefreshDecisions(text)
-  let updated = 0
-  let superseded = 0
-  const edited = new Set()
-  for (const d of decisions) {
-    const entry = flagged.find((e) => e.id === d.id)
-    if (!entry) continue
-    const file = join(store.root, entry.file)
-    const cur = readFileSync(file, 'utf8')
-    if (d.action === 'update' && d.body) {
-      writeFileSync(file, setEntryBody(cur, d.id, d.body), 'utf8')
-      edited.add(file)
-      updated++
-    } else if (d.action === 'supersede') {
-      writeFileSync(file, setEntryStatus(cur, d.id, 'superseded', d.reason || 'refresh'), 'utf8')
-      edited.add(file)
-      superseded++
-    }
-  }
-  // An in-place edit changes a topic file, so its layer index is stale until rebuilt.
-  if (updated || superseded) {
-    const scopes = new Set(flagged.map((e) => JSON.stringify(scopeOfFile(e.file))).filter((s) => s !== undefined))
-    for (const raw of scopes) {
-      const { scope: s, key } = JSON.parse(raw)
-      rebuildLayerIndexes(store.root, s, key)
-      for (const l of layersForScope(s)) edited.add(layerIndexPath(store.root, s, key, l))
-    }
-    updateIndex(store.root, edited)
-  }
-  return { refreshed: decisions.length, updated, superseded }
-}
+// Refresh pass: flag stale/time-bounded entries (freshness), ask the LLM for
+// keep/update/supersede decisions, then apply them deterministically in place.
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { buildLedger } from './ledger.js'
+import { scanFreshness } from './freshness.js'
+import { setEntryBody, setEntryStatus } from './entry.js'
+import { updateIndex } from './fts.js'
+import { layerIndexPath, rebuildLayerIndexes, scopeOfFile } from './layers.js'
+import { layersForScope } from './entry.js'
+
+export function buildRefreshPrompt(entries) {
+  const lines = [
+    'You are reviewing stale or time-bounded memory entries. For each, decide keep, update, or supersede.',
+    'Return ONLY a JSON object: {"decisions":[{"id":"<entry id>","action":"keep|update|supersede","body":"<new body if update>","reason":"..."}]}',
+    'Rules: update rewrites the body with current facts; supersede marks the entry obsolete (history kept); keep does nothing.',
+    '',
+    'Entries:',
+  ]
+  for (const e of entries) {
+    lines.push('### ' + e.id + ' (' + e.file + ')')
+    lines.push('Verdict: ' + e.verdict)
+    lines.push(e.content)
+    lines.push('')
+  }
+  return lines.join('\n')
+}
+
+export function parseRefreshDecisions(text) {
+  const src = String(text ?? '')
+  const FENCE = '\u0060\u0060\u0060'
+  const fenced = src.match(new RegExp(FENCE + '(?:json)?\\s*([\\s\\S]*?)' + FENCE, 'i'))
+  let candidate = fenced ? fenced[1] : src
+  const obj = candidate.match(/\{[\s\S]*\}/)
+  if (obj) candidate = obj[0]
+  try {
+    const parsed = JSON.parse(candidate)
+    return Array.isArray(parsed.decisions) ? parsed.decisions : []
+  } catch { return [] }
+}
+
+export async function runRefresh(store, { llm, limit = 3, scope, key, nowMs = Date.now() } = {}) {
+  const ledger = buildLedger(store.root)
+  const scoped = scope === 'workspace' && key
+    ? ledger.filter((e) => e.file.startsWith('workspaces/' + key + '/'))
+    : ledger
+  const flagged = scanFreshness(scoped, nowMs).slice(0, limit)
+  if (flagged.length === 0) return { refreshed: 0, updated: 0, superseded: 0 }
+  const text = await llm(buildRefreshPrompt(flagged))
+  const decisions = parseRefreshDecisions(text)
+  let updated = 0
+  let superseded = 0
+  const edited = new Set()
+  for (const d of decisions) {
+    const entry = flagged.find((e) => e.id === d.id)
+    if (!entry) continue
+    const file = join(store.root, entry.file)
+    const cur = readFileSync(file, 'utf8')
+    if (d.action === 'update' && d.body) {
+      writeFileSync(file, setEntryBody(cur, d.id, d.body), 'utf8')
+      edited.add(file)
+      updated++
+    } else if (d.action === 'supersede') {
+      writeFileSync(file, setEntryStatus(cur, d.id, 'superseded', d.reason || 'refresh'), 'utf8')
+      edited.add(file)
+      superseded++
+    }
+  }
+  // An in-place edit changes a topic file, so its layer index is stale until rebuilt.
+  if (updated || superseded) {
+    const scopes = new Set(flagged.map((e) => JSON.stringify(scopeOfFile(e.file))).filter((s) => s !== undefined))
+    for (const raw of scopes) {
+      const { scope: s, key } = JSON.parse(raw)
+      rebuildLayerIndexes(store.root, s, key)
+      for (const l of layersForScope(s)) edited.add(layerIndexPath(store.root, s, key, l))
+    }
+    updateIndex(store.root, edited)
+  }
+  return { refreshed: decisions.length, updated, superseded }
+}

package/src/remember.js

@@ -1,58 +1,58 @@
-// Deterministic write path: append a Format-2 entry to a layer file, then rebuild the index.
-import { relative } from 'node:path'
-import { allocateId, formatEntry, isWorkspaceOnly, LAYER_CODES, scopeIdFor, nowIso } from './entry.js'
-import { updateIndex } from './fts.js'
-import { isSuppressed } from './forget.js'
-import { associate } from './workspace.js'
-import { sanitizeKey } from './workspace-key.js'
-import { appendToTopic, layerIndexPath, layerText, rebuildLayerIndex } from './layers.js'
-import { decisionHeading, renderDecisionBody } from './decisions.js'
-
-export function defaultHeading(text) {
-  const first = String(text ?? '').split('\n').map((s) => s.trim()).find((s) => s.length > 0)
-  if (!first) return 'untitled'
-  const clean = first.replace(/^[#*>-]+/, '').trim()
-  const h = clean.length > 64 ? clean.slice(0, 61) + '…' : clean
-  return h || 'untitled'
-}
-
-export function remember(store, { scope, key, layer, text, topic, decision, source = 'manual', importance = 2, until, volatility, verified } = {}) {
-  if (!LAYER_CODES[layer]) throw new Error('unknown layer: ' + layer)
-  if (isWorkspaceOnly(layer) && scope !== 'workspace') {
-    throw new Error('the ' + layer + ' map describes one repository; write it to a workspace')
-  }
-  // Sanitize ONCE, up front. associate() sanitizes for the directory it creates, so using
-  // the raw key afterwards built a path with characters a filesystem rejects: the workspace
-  // directory appeared and the write then failed, silently losing every entry.
-  const safeKey = scope === 'global' ? undefined : sanitizeKey(key)
-  if (scope !== 'global' && !safeKey) throw new Error('workspace scope requires a key')
-  const scopeId = scopeIdFor(scope, safeKey)
-  // A decision gets its own shape: the choice is the heading (so the layer index reads as a
-  // list of decisions) and the reasoning lives in fixed sections. `topic` still wins when the
-  // caller names one explicitly.
-  if (isSuppressed(store.root, scopeId, text)) throw new Error('suppressed: this content matches a forgotten entry')
-  if (scope !== 'global' && safeKey) {
-    // A write can introduce a workspace. Make it first-class - seeded layer files and a
-    // registry entry, exactly as an explicit associate would - instead of leaving behind a
-    // directory that holds only the file this one write happened to touch.
-    const known = store.readMemoryJson().workspaces ?? {}
-    if (!known[safeKey]) associate(store, { key: safeKey, title: key ?? safeKey })
-  }
-  // Layered storage: the entry goes into its own topic file, the layer file becomes an
-  // index over those files, and id allocation spans the whole layer rather than one file.
-  const heading = layer === 'decision'
-    ? decisionHeading(topic ?? text)
-    : (topic ?? defaultHeading(text))
-  const body = layer === 'decision'
-    ? renderDecisionBody(decision ?? { context: text })
-    : String(text)
-  const id = allocateId(layerText(store.root, scope, safeKey, layer), scopeId, layer)
-  const block = '## ' + heading + '\n\n'
-    + formatEntry({ id, source, date: nowIso(), importance, status: 'active', until, volatility, verified, content: body })
-  const file = appendToTopic(store.root, scope, safeKey, layer, heading, block)
-  rebuildLayerIndex(store.root, scope, safeKey, layer)
-  // Index just what changed. A full rebuild is seconds once the store is large, and a
-  // single write touches exactly two files.
-  updateIndex(store.root, [file, layerIndexPath(store.root, scope, safeKey, layer)])
-  return { id, file: relative(store.root, file).replace(/\\/g, '/'), layer, scopeId }
-}
+// Deterministic write path: append a Format-2 entry to a layer file, then rebuild the index.
+import { relative } from 'node:path'
+import { allocateId, formatEntry, isWorkspaceOnly, LAYER_CODES, scopeIdFor, nowIso } from './entry.js'
+import { updateIndex } from './fts.js'
+import { isSuppressed } from './forget.js'
+import { associate } from './workspace.js'
+import { sanitizeKey } from './workspace-key.js'
+import { appendToTopic, layerIndexPath, layerText, rebuildLayerIndex } from './layers.js'
+import { decisionHeading, renderDecisionBody } from './decisions.js'
+
+export function defaultHeading(text) {
+  const first = String(text ?? '').split('\n').map((s) => s.trim()).find((s) => s.length > 0)
+  if (!first) return 'untitled'
+  const clean = first.replace(/^[#*>-]+/, '').trim()
+  const h = clean.length > 64 ? clean.slice(0, 61) + '…' : clean
+  return h || 'untitled'
+}
+
+export function remember(store, { scope, key, layer, text, topic, decision, source = 'manual', importance = 2, until, volatility, verified } = {}) {
+  if (!LAYER_CODES[layer]) throw new Error('unknown layer: ' + layer)
+  if (isWorkspaceOnly(layer) && scope !== 'workspace') {
+    throw new Error('the ' + layer + ' map describes one repository; write it to a workspace')
+  }
+  // Sanitize ONCE, up front. associate() sanitizes for the directory it creates, so using
+  // the raw key afterwards built a path with characters a filesystem rejects: the workspace
+  // directory appeared and the write then failed, silently losing every entry.
+  const safeKey = scope === 'global' ? undefined : sanitizeKey(key)
+  if (scope !== 'global' && !safeKey) throw new Error('workspace scope requires a key')
+  const scopeId = scopeIdFor(scope, safeKey)
+  // A decision gets its own shape: the choice is the heading (so the layer index reads as a
+  // list of decisions) and the reasoning lives in fixed sections. `topic` still wins when the
+  // caller names one explicitly.
+  if (isSuppressed(store.root, scopeId, text)) throw new Error('suppressed: this content matches a forgotten entry')
+  if (scope !== 'global' && safeKey) {
+    // A write can introduce a workspace. Make it first-class - seeded layer files and a
+    // registry entry, exactly as an explicit associate would - instead of leaving behind a
+    // directory that holds only the file this one write happened to touch.
+    const known = store.readMemoryJson().workspaces ?? {}
+    if (!known[safeKey]) associate(store, { key: safeKey, title: key ?? safeKey })
+  }
+  // Layered storage: the entry goes into its own topic file, the layer file becomes an
+  // index over those files, and id allocation spans the whole layer rather than one file.
+  const heading = layer === 'decision'
+    ? decisionHeading(topic ?? text)
+    : (topic ?? defaultHeading(text))
+  const body = layer === 'decision'
+    ? renderDecisionBody(decision ?? { context: text })
+    : String(text)
+  const id = allocateId(layerText(store.root, scope, safeKey, layer), scopeId, layer)
+  const block = '## ' + heading + '\n\n'
+    + formatEntry({ id, source, date: nowIso(), importance, status: 'active', until, volatility, verified, content: body })
+  const file = appendToTopic(store.root, scope, safeKey, layer, heading, block)
+  rebuildLayerIndex(store.root, scope, safeKey, layer)
+  // Index just what changed. A full rebuild is seconds once the store is large, and a
+  // single write touches exactly two files.
+  updateIndex(store.root, [file, layerIndexPath(store.root, scope, safeKey, layer)])
+  return { id, file: relative(store.root, file).replace(/\\/g, '/'), layer, scopeId }
+}