@try-works/dsh-memory 0.1.19 → 0.1.20

package/src/system-doc.js

@@ -1,171 +1,171 @@
-// The system document: the memory system describing itself, as built.
-//
-// This is not a memory layer - it is not a fact about the user's work, it is the manual for the
-// machinery. It is rendered from SYSTEM.template.md on every boot so it can never drift from the
-// build, and it lives at the store root (committed) so the same description travels with the
-// memory to every machine.
-//
-// It exists because an agent that reads and writes memory needs to understand the intent behind
-// it: which layer a fact belongs in, why writes are deterministic, and what is derived and
-// therefore safe to lose. Without that, memory becomes a junk drawer.
-import { readFileSync, readdirSync, writeFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { LAYER_CODES, LAYER_DIRS, LAYERED, VOLATILITY_DAYS, WORKSPACE_ONLY_LAYERS } from './entry.js'
-
-/** Bumped whenever the described behaviour changes, so a stale on-disk copy is detectable. */
-export const SYSTEM_DOC_VERSION = 2
-
-/** The template ships beside this module; resolve it relative to the module, not the cwd. */
-export function templatePath() {
-  return join(dirname(fileURLToPath(import.meta.url)), 'SYSTEM.template.md')
-}
-
-/** Absolute path of the rendered document inside a store. */
-export function systemDocPath(root) { return join(root, 'SYSTEM.md') }
-
-/** The layer diagram, kept as data so it cannot break the surrounding code. */
-const DIAGRAM = [
-  'global/                       workspaces/<key>/',
-  '  semantic.md                   semantic.md',
-  '    semantic/<topic>.md           semantic/<topic>.md',
-  '  episodic.md   + episodic/<topic>.md',
-  '  procedural.md + procedural/<topic>.md',
-  '  learnings.md  + learnings/<topic>.md',
-  '  working.md                    working.md    (single file, never indexed)',
-  '  junk.md                       junk.md       (single file, never indexed)',
-  '                                codebase.md + codebase/<topic>.md  (workspace only)',
-  '                                history.md  + history/<day>.md     (workspace only)',
-  '  state.md                      state.md      (repo state; replaced per section)',
-  '  working.md                    working.md    (YOUR task/activity head)',
-].join(String.fromCharCode(10))
-
-/** Count the markdown files inside one layer directory, or 0 when it does not exist. */
-function countTopics(root, scopeDir, layer) {
-  try {
-    return readdirSync(join(root, scopeDir, LAYER_DIRS[layer])).filter((n) => n.endsWith('.md')).length
-  } catch { return 0 }
-}
-
-/**
- * Summarise what the store currently holds, so the document reports reality rather than intent.
- * Best-effort: an unreadable scope is reported as absent, never thrown.
- */
-export function describeStore(root) {
-  const scopes = [{ label: 'global', dir: 'global' }]
-  try {
-    for (const name of readdirSync(join(root, 'workspaces'))) scopes.push({ label: name, dir: join('workspaces', name) })
-  } catch {}
-  return scopes.map((scope) => {
-    const counts = {}
-    for (const layer of LAYERED) counts[layer] = countTopics(root, scope.dir, layer)
-    return { scope: scope.label, counts, total: Object.values(counts).reduce((a, b) => a + b, 0) }
-  })
-}
-
-/** Format a millisecond cadence for humans: 3600000 -> '1h'. */
-export function humanDuration(ms) {
-  const n = Number(ms)
-  if (!Number.isFinite(n) || n <= 0) return String(ms)
-  if (n % 86400000 === 0) return (n / 86400000) + 'd'
-  if (n % 3600000 === 0) return (n / 3600000) + 'h'
-  if (n % 60000 === 0) return (n / 60000) + 'm'
-  if (n % 1000 === 0) return (n / 1000) + 's'
-  return n + 'ms'
-}
-
-/** What each layer is for, keyed by layer so the table cannot drift from the vocabulary. */
-const LAYER_PURPOSE = {
-  semantic: 'Durable facts that stay true: how something works, what was decided, environment facts, versions, where things live.',
-  episodic: 'What happened: an incident, a migration, a change made on a date and why.',
-  procedural: 'How to do something: runbooks, commands, build and test steps, order of operations.',
-  learning: 'A lesson from experience - what you wish you had known an hour earlier.',
-  codebase: 'What a module, file or subsystem of THIS repository does. Workspace only.',
-  history: 'How the repository changed: one entry per commit, grouped by day. Workspace only.',
-  decision: 'A settled choice and why it won: dependencies, conventions, architecture. Available in both scopes.',
-}
-
-/**
- * The per-layer table, generated from the layer vocabulary so a newly added layer appears here
- * automatically. A layer with no purpose recorded still gets a row, flagged rather than omitted.
- */
-function layerTable() {
-  const rows = ['| Layer | Code | Use it for |', '| --- | --- | --- |']
-  for (const layer of LAYERED) {
-    const purpose = LAYER_PURPOSE[layer] ?? '(undocumented)'
-    rows.push('| `' + layer + '` | `' + (LAYER_CODES[layer] ?? layer) + '` | ' + purpose + ' |')
-  }
-  return rows.join(String.fromCharCode(10))
-}
-/** The current-state table, so the document shows what this store actually holds. */
-function storeState(root) {
-  if (!root) return '(store root unknown)'
-  const rows = describeStore(root)
-  const layers = LAYERED
-  const lines = [
-    '| Scope | ' + layers.join(' | ') + ' | total |',
-    '| --- | ' + layers.map(() => '---').join(' | ') + ' | --- |',
-  ]
-  for (const row of rows) {
-    lines.push('| ' + row.scope + ' | ' + layers.map((l) => row.counts[l]).join(' | ') + ' | ' + row.total + ' |')
-  }
-  return lines.join(String.fromCharCode(10))
-}
-
-/**
- * Render the system document by filling the template.
- * @param options.cfg - resolved plugin config, quoted so the document matches this build.
- * @param options.version - plugin version.
- * @param options.store - store root, used for the current-state table.
- * @param options.now - ISO timestamp.
- * @returns the markdown document.
- */
-export function renderSystemDoc(options = {}) {
-  const cfg = options.cfg ?? {}
-  const template = options.template ?? readFileSync(templatePath(), 'utf8')
-  const values = {
-    documentVersion: String(SYSTEM_DOC_VERSION),
-    version: String(options.version ?? 'unknown'),
-    generated: options.now ?? new Date().toISOString(),
-    store: String(options.store ?? '(unknown)'),
-    diagram: DIAGRAM,
-    layerTable: layerTable(),
-    workspaceOnly: WORKSPACE_ONLY_LAYERS.map((l) => '`' + l + '`').join(' and '),
-    captureInterval: humanDuration(cfg.autoCaptureIntervalMs),
-    consolidateInterval: humanDuration(cfg.autoConsolidateIntervalMs),
-    refreshInterval: humanDuration(cfg.autoRefreshIntervalMs),
-    historyInterval: humanDuration(cfg.autoHistoryIntervalMs),
-    syncInterval: humanDuration(cfg.autoSyncIntervalMs),
-    commitDebounce: humanDuration(cfg.commitDebounceMs),
-    effort: String(cfg.memoryReasoningEffort ?? '(model default)'),
-    minSignalChars: String(cfg.summaryMinSignalChars ?? ''),
-    digestKeep: String(cfg.digestKeepCount ?? ''),
-    stableDays: String(VOLATILITY_DAYS.stable),
-    normalDays: String(VOLATILITY_DAYS.normal),
-    volatileDays: String(VOLATILITY_DAYS.volatile),
-    storeState: storeState(options.store),
-  }
-  return template.replace(/\{\{(\w+)\}\}/g, (match, key) => {
-    return Object.hasOwn(values, key) ? String(values[key]) : match
-  })
-}
-
-/**
- * Write SYSTEM.md into a store. Always overwrites: the document is generated, never edited
- * in place, so a stale copy must not survive a boot.
- * @returns the path written.
- */
-export function writeSystemDoc(root, options = {}) {
-  const target = systemDocPath(root)
-  writeFileSync(target, renderSystemDoc({ ...options, store: root }), 'utf8')
-  return target
-}
-
-/** True when the on-disk document is missing or was written by an older version. */
-export function systemDocStale(root) {
-  try {
-    const text = readFileSync(systemDocPath(root), 'utf8')
-    const found = /Document version: (\d+)/.exec(text)
-    return found === null || Number(found[1]) !== SYSTEM_DOC_VERSION
-  } catch { return true }
-}
+// The system document: the memory system describing itself, as built.
+//
+// This is not a memory layer - it is not a fact about the user's work, it is the manual for the
+// machinery. It is rendered from SYSTEM.template.md on every boot so it can never drift from the
+// build, and it lives at the store root (committed) so the same description travels with the
+// memory to every machine.
+//
+// It exists because an agent that reads and writes memory needs to understand the intent behind
+// it: which layer a fact belongs in, why writes are deterministic, and what is derived and
+// therefore safe to lose. Without that, memory becomes a junk drawer.
+import { readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { LAYER_CODES, LAYER_DIRS, LAYERED, VOLATILITY_DAYS, WORKSPACE_ONLY_LAYERS } from './entry.js'
+
+/** Bumped whenever the described behaviour changes, so a stale on-disk copy is detectable. */
+export const SYSTEM_DOC_VERSION = 2
+
+/** The template ships beside this module; resolve it relative to the module, not the cwd. */
+export function templatePath() {
+  return join(dirname(fileURLToPath(import.meta.url)), 'SYSTEM.template.md')
+}
+
+/** Absolute path of the rendered document inside a store. */
+export function systemDocPath(root) { return join(root, 'SYSTEM.md') }
+
+/** The layer diagram, kept as data so it cannot break the surrounding code. */
+const DIAGRAM = [
+  'global/                       workspaces/<key>/',
+  '  semantic.md                   semantic.md',
+  '    semantic/<topic>.md           semantic/<topic>.md',
+  '  episodic.md   + episodic/<topic>.md',
+  '  procedural.md + procedural/<topic>.md',
+  '  learnings.md  + learnings/<topic>.md',
+  '  working.md                    working.md    (single file, never indexed)',
+  '  junk.md                       junk.md       (single file, never indexed)',
+  '                                codebase.md + codebase/<topic>.md  (workspace only)',
+  '                                history.md  + history/<day>.md     (workspace only)',
+  '  state.md                      state.md      (repo state; replaced per section)',
+  '  working.md                    working.md    (YOUR task/activity head)',
+].join(String.fromCharCode(10))
+
+/** Count the markdown files inside one layer directory, or 0 when it does not exist. */
+function countTopics(root, scopeDir, layer) {
+  try {
+    return readdirSync(join(root, scopeDir, LAYER_DIRS[layer])).filter((n) => n.endsWith('.md')).length
+  } catch { return 0 }
+}
+
+/**
+ * Summarise what the store currently holds, so the document reports reality rather than intent.
+ * Best-effort: an unreadable scope is reported as absent, never thrown.
+ */
+export function describeStore(root) {
+  const scopes = [{ label: 'global', dir: 'global' }]
+  try {
+    for (const name of readdirSync(join(root, 'workspaces'))) scopes.push({ label: name, dir: join('workspaces', name) })
+  } catch {}
+  return scopes.map((scope) => {
+    const counts = {}
+    for (const layer of LAYERED) counts[layer] = countTopics(root, scope.dir, layer)
+    return { scope: scope.label, counts, total: Object.values(counts).reduce((a, b) => a + b, 0) }
+  })
+}
+
+/** Format a millisecond cadence for humans: 3600000 -> '1h'. */
+export function humanDuration(ms) {
+  const n = Number(ms)
+  if (!Number.isFinite(n) || n <= 0) return String(ms)
+  if (n % 86400000 === 0) return (n / 86400000) + 'd'
+  if (n % 3600000 === 0) return (n / 3600000) + 'h'
+  if (n % 60000 === 0) return (n / 60000) + 'm'
+  if (n % 1000 === 0) return (n / 1000) + 's'
+  return n + 'ms'
+}
+
+/** What each layer is for, keyed by layer so the table cannot drift from the vocabulary. */
+const LAYER_PURPOSE = {
+  semantic: 'Durable facts that stay true: how something works, what was decided, environment facts, versions, where things live.',
+  episodic: 'What happened: an incident, a migration, a change made on a date and why.',
+  procedural: 'How to do something: runbooks, commands, build and test steps, order of operations.',
+  learning: 'A lesson from experience - what you wish you had known an hour earlier.',
+  codebase: 'What a module, file or subsystem of THIS repository does. Workspace only.',
+  history: 'How the repository changed: one entry per commit, grouped by day. Workspace only.',
+  decision: 'A settled choice and why it won: dependencies, conventions, architecture. Available in both scopes.',
+}
+
+/**
+ * The per-layer table, generated from the layer vocabulary so a newly added layer appears here
+ * automatically. A layer with no purpose recorded still gets a row, flagged rather than omitted.
+ */
+function layerTable() {
+  const rows = ['| Layer | Code | Use it for |', '| --- | --- | --- |']
+  for (const layer of LAYERED) {
+    const purpose = LAYER_PURPOSE[layer] ?? '(undocumented)'
+    rows.push('| `' + layer + '` | `' + (LAYER_CODES[layer] ?? layer) + '` | ' + purpose + ' |')
+  }
+  return rows.join(String.fromCharCode(10))
+}
+/** The current-state table, so the document shows what this store actually holds. */
+function storeState(root) {
+  if (!root) return '(store root unknown)'
+  const rows = describeStore(root)
+  const layers = LAYERED
+  const lines = [
+    '| Scope | ' + layers.join(' | ') + ' | total |',
+    '| --- | ' + layers.map(() => '---').join(' | ') + ' | --- |',
+  ]
+  for (const row of rows) {
+    lines.push('| ' + row.scope + ' | ' + layers.map((l) => row.counts[l]).join(' | ') + ' | ' + row.total + ' |')
+  }
+  return lines.join(String.fromCharCode(10))
+}
+
+/**
+ * Render the system document by filling the template.
+ * @param options.cfg - resolved plugin config, quoted so the document matches this build.
+ * @param options.version - plugin version.
+ * @param options.store - store root, used for the current-state table.
+ * @param options.now - ISO timestamp.
+ * @returns the markdown document.
+ */
+export function renderSystemDoc(options = {}) {
+  const cfg = options.cfg ?? {}
+  const template = options.template ?? readFileSync(templatePath(), 'utf8')
+  const values = {
+    documentVersion: String(SYSTEM_DOC_VERSION),
+    version: String(options.version ?? 'unknown'),
+    generated: options.now ?? new Date().toISOString(),
+    store: String(options.store ?? '(unknown)'),
+    diagram: DIAGRAM,
+    layerTable: layerTable(),
+    workspaceOnly: WORKSPACE_ONLY_LAYERS.map((l) => '`' + l + '`').join(' and '),
+    captureInterval: humanDuration(cfg.autoCaptureIntervalMs),
+    consolidateInterval: humanDuration(cfg.autoConsolidateIntervalMs),
+    refreshInterval: humanDuration(cfg.autoRefreshIntervalMs),
+    historyInterval: humanDuration(cfg.autoHistoryIntervalMs),
+    syncInterval: humanDuration(cfg.autoSyncIntervalMs),
+    commitDebounce: humanDuration(cfg.commitDebounceMs),
+    effort: String(cfg.memoryReasoningEffort ?? '(model default)'),
+    minSignalChars: String(cfg.summaryMinSignalChars ?? ''),
+    digestKeep: String(cfg.digestKeepCount ?? ''),
+    stableDays: String(VOLATILITY_DAYS.stable),
+    normalDays: String(VOLATILITY_DAYS.normal),
+    volatileDays: String(VOLATILITY_DAYS.volatile),
+    storeState: storeState(options.store),
+  }
+  return template.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+    return Object.hasOwn(values, key) ? String(values[key]) : match
+  })
+}
+
+/**
+ * Write SYSTEM.md into a store. Always overwrites: the document is generated, never edited
+ * in place, so a stale copy must not survive a boot.
+ * @returns the path written.
+ */
+export function writeSystemDoc(root, options = {}) {
+  const target = systemDocPath(root)
+  writeFileSync(target, renderSystemDoc({ ...options, store: root }), 'utf8')
+  return target
+}
+
+/** True when the on-disk document is missing or was written by an older version. */
+export function systemDocStale(root) {
+  try {
+    const text = readFileSync(systemDocPath(root), 'utf8')
+    const found = /Document version: (\d+)/.exec(text)
+    return found === null || Number(found[1]) !== SYSTEM_DOC_VERSION
+  } catch { return true }
+}