@try-works/dsh-memory 0.1.19 → 0.1.21

package/src/state.js

@@ -1,240 +1,240 @@
-// Workspace state: a short, readable overview of what this repository IS right now.
-//
-// This is the one layer whose value is entirely in being CURRENT. A fact can be a month old and
-// still true; a description of "what is running" or "what is in flight" cannot. So state is
-// treated differently from every other layer in three ways:
-//
-//  1. It is REPLACED per section, not appended. State describes now, so a newer statement about
-//     the same section supersedes the old one instead of piling up beside it.
-//  2. Every section carries an explicit **Verified:** timestamp. Freshness is not inferred from
-//     an entry date - it is part of the section, written by the machine that touched it.
-//  3. Freshness is graded and always surfaced. A stale section is shown WITH its staleness, so
-//     an agent reads it as a hypothesis to check rather than a fact to trust.
-//
-// It is workspace-only: a repository state file in the global layer would describe no repository.
-// It is a single file, not a layered kind - an overview that needs an index is not an overview.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
-import { workspaceDir } from './store.js'
-
-/** A section verified within this window is current. */
-export const STATE_FRESH_MS = 6 * 3600_000
-/** Past this, a section describes a repository that has probably moved on. */
-export const STATE_STALE_MS = 72 * 3600_000
-
-/** Suggested sections. Any name is allowed; these keep separate agents consistent. */
-export const STATE_SECTIONS = ['Summary', 'Layout', 'Running', 'Pending', 'Health']
-
-/** Absolute path of a workspace state file. */
-export function statePath(root, key) { return join(workspaceDir(root, key), 'state.md') }
-
-/** True when a section name is usable as a heading. */
-export function isValidSectionName(name) {
-  const text = String(name ?? '').trim()
-  return text !== '' && text.length <= 60 && !/[\r\n]/.test(text) && !text.startsWith('#')
-}
-
-/** Canonical display form of a section name: trimmed, first letter upper-cased. */
-export function sectionTitle(name) {
-  const text = String(name ?? '').trim().replace(/\s+/g, ' ')
-  if (text === '') return ''
-  return text[0].toUpperCase() + text.slice(1)
-}
-
-/** Matching key for a section name, so "summary" and "Summary" are the same section. */
-export function sectionKey(name) { return String(name ?? '').trim().toLowerCase() }
-
-/**
- * Make content safe to embed: a line starting with one or two hashes would be read as a new
- * section heading on the next parse, so such lines are demoted. The text survives; the
- * structure of the file does not break.
- */
-/** A line that would parse as a heading, escaped so it survives as text. */
-const HEADING_ESCAPE = /^(#{1,6}\s)/
-
-export function sanitizeSectionContent(content) {
-  return String(content ?? '')
-    .replace(/\r\n/g, '\n')
-    .split('\n')
-    .map((line) => line.replace(HEADING_ESCAPE, '\\$1'))
-    .join('\n')
-    .trim()
-}
-
-/** Undo the heading escape when reading a section back. */
-function unsanitizeSectionContent(content) {
-  return String(content ?? '').split('\n').map((line) => line.replace(/^\\(#{1,6}\s)/, '$1')).join('\n')
-}
-
-/**
- * Freshness of one section, graded rather than binary.
- * @param verified - ISO timestamp the section was last confirmed.
- * @param now - epoch ms.
- * @param options.freshMs / options.staleMs - thresholds.
- * @returns {{verdict: 'fresh'|'aging'|'stale'|'unverified', ageMs: number|undefined, days: number|undefined}}
- */
-export function stateVerdict(verified, now = Date.now(), options = {}) {
-  const freshMs = options.freshMs ?? STATE_FRESH_MS
-  const staleMs = options.staleMs ?? STATE_STALE_MS
-  const parsed = Date.parse(String(verified ?? ''))
-  if (!Number.isFinite(parsed)) return { verdict: 'unverified', ageMs: undefined, days: undefined }
-  const ageMs = Math.max(0, now - parsed)
-  const days = Math.round((ageMs / 86400000) * 10) / 10
-  if (ageMs <= freshMs) return { verdict: 'fresh', ageMs, days }
-  if (ageMs <= staleMs) return { verdict: 'aging', ageMs, days }
-  return { verdict: 'stale', ageMs, days }
-}
-
-/** Human age: 20m, 5h, 3d. */
-export function humanAge(ageMs) {
-  if (!Number.isFinite(ageMs)) return 'unknown'
-  if (ageMs < 60_000) return 'just now'
-  const minutes = Math.round(ageMs / 60_000)
-  if (minutes < 60) return minutes + 'm'
-  const hours = Math.round(ageMs / 3600_000)
-  if (hours < 48) return hours + 'h'
-  return Math.round(ageMs / 86400_000) + 'd'
-}
-
-/** The marker shown wherever a non-fresh section appears. */
-export function freshnessMarker(verdict, ageMs) {
-  if (verdict === 'fresh') return ''
-  if (verdict === 'unverified') return ' [UNVERIFIED]'
-  return ' [' + verdict.toUpperCase() + ' ' + humanAge(ageMs) + ']'
-}
-
-/**
- * Parse a state file.
- * @returns {{ updated: string|undefined, sections: {name: string, verified: string|undefined, source: string|undefined, content: string}[] }}
- */
-export function parseState(text) {
-  const lines = String(text ?? '').split('\n')
-  const sections = []
-  let updated
-  let current = null
-  const push = () => { if (current) { current.content = unsanitizeSectionContent(current.content.join('\n').trim()); sections.push(current) } }
-  for (const line of lines) {
-    const stamp = /^Last updated:\s*(.+)$/.exec(line.trim())
-    if (stamp && updated === undefined) { updated = stamp[1].trim(); continue }
-    const heading = /^##\s+(.+)$/.exec(line)
-    if (heading) {
-      push()
-      current = { name: heading[1].trim(), verified: undefined, source: undefined, content: [] }
-      continue
-    }
-    if (!current) continue
-    const verified = /^\*\*Verified:\*\*\s*(.*)$/.exec(line.trim())
-    if (verified) { current.verified = verified[1].trim() || undefined; continue }
-    const source = /^\*\*Source:\*\*\s*(.*)$/.exec(line.trim())
-    if (source) { current.source = source[1].trim() || undefined; continue }
-    current.content.push(line)
-  }
-  push()
-  return { updated, sections }
-}
-
-/** Render a whole state file from its sections. */
-export function renderState(title, sections, options = {}) {
-  const now = options.now ?? new Date().toISOString()
-  const out = [
-    '# ' + title + ' — state',
-    '',
-    'What this repository is right now. Each section carries when it was last verified:',
-    'treat a stale section as a hypothesis to check, not a fact to trust.',
-    '',
-    'Last updated: ' + now,
-    '',
-  ]
-  for (const section of sections) {
-    out.push('## ' + section.name, '')
-    if (section.verified) out.push('**Verified:** ' + section.verified)
-    if (section.source) out.push('**Source:** ' + section.source)
-    out.push('', section.content.trim(), '')
-  }
-  return out.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n'
-}
-
-/** Read and grade a workspace state file. Returns undefined when there is none. */
-export function readState(root, key, options = {}) {
-  const path = statePath(root, key)
-  if (!existsSync(path)) return undefined
-  let text
-  try { text = readFileSync(path, 'utf8') } catch { return undefined }
-  const parsed = parseState(text)
-  const now = options.now ?? Date.now()
-  const sections = parsed.sections.map((section) => ({
-    ...section,
-    ...stateVerdict(section.verified, now, options),
-  }))
-  return { path, updated: parsed.updated, sections }
-}
-
-/**
- * Write one section, replacing any existing section with the same name.
- *
- * The replacement is the point: state describes now, so the newer statement wins. Other
- * sections are preserved untouched, including their own timestamps - editing one area of a
- * repository must not make an unrelated section look freshly verified.
- *
- * @returns {{ section: string, verified: string, created: boolean, sections: string[] }}
- */
-export function writeStateSection(root, key, section, content, options = {}) {
-  const name = sectionTitle(section)
-  if (!isValidSectionName(name)) throw new Error('invalid state section name: ' + String(section))
-  const body = sanitizeSectionContent(content)
-  if (body === '') throw new Error('state section content must not be empty')
-  const now = options.now ?? new Date().toISOString()
-  const existing = readState(root, key, { now: Date.parse(now) }) ?? { sections: [] }
-  const wanted = sectionKey(name)
-  const kept = existing.sections
-    .filter((s) => sectionKey(s.name) !== wanted)
-    .map((s) => ({ name: s.name, verified: s.verified, source: s.source, content: s.content }))
-  const created = kept.length === existing.sections.length
-  // Keep the casing already in use for this section, so re-writing "RUNNING" does not
-  // silently restyle a heading another agent established.
-  const prior = existing.sections.find((s) => sectionKey(s.name) === wanted)
-  const written = { name: prior ? prior.name : name, verified: now, source: options.source, content: body }
-  // Keep the suggested order when the sections are familiar, else append in insertion order.
-  const next = [...kept, written].sort((a, b) => {
-    const ia = STATE_SECTIONS.findIndex((s) => sectionKey(s) === sectionKey(a.name))
-    const ib = STATE_SECTIONS.findIndex((s) => sectionKey(s) === sectionKey(b.name))
-    if (ia === -1 && ib === -1) return 0
-    if (ia === -1) return 1
-    if (ib === -1) return -1
-    return ia - ib
-  })
-  mkdirSync(workspaceDir(root, key), { recursive: true })
-  writeFileSync(statePath(root, key), renderState(key, next, { now }), 'utf8')
-  // Report the name that was actually written, not the one computed from this call, or the
-  // return value would disagree with the file whenever the casing is reused.
-  return { section: written.name, verified: now, created, sections: next.map((s) => s.name) }
-}
-
-/**
- * What is safe to trust right now, and what needs re-checking.
- * @returns {{ sections: object[], stale: string[], missing: string[], fresh: number }}
- */
-export function summarizeState(root, key, options = {}) {
-  const state = readState(root, key, options)
-  const sections = state ? state.sections : []
-  const present = new Set(sections.map((s) => sectionKey(s.name)))
-  return {
-    sections,
-    stale: sections.filter((s) => s.verdict !== 'fresh').map((s) => s.name),
-    missing: STATE_SECTIONS.filter((s) => !present.has(sectionKey(s))),
-    fresh: sections.filter((s) => s.verdict === 'fresh').length,
-  }
-}
-
-/** The state template seeded for a new workspace. */
-export function stateTemplate(title) {
-  return [
-    '# ' + title + ' — state',
-    '',
-    'What this repository is right now. Each section carries when it was last verified:',
-    'treat a stale section as a hypothesis to check, not a fact to trust.',
-    '',
-    'No sections recorded yet. Use memory_state to describe the current state.',
-    '',
-  ].join('\n')
-}
+// Workspace state: a short, readable overview of what this repository IS right now.
+//
+// This is the one layer whose value is entirely in being CURRENT. A fact can be a month old and
+// still true; a description of "what is running" or "what is in flight" cannot. So state is
+// treated differently from every other layer in three ways:
+//
+//  1. It is REPLACED per section, not appended. State describes now, so a newer statement about
+//     the same section supersedes the old one instead of piling up beside it.
+//  2. Every section carries an explicit **Verified:** timestamp. Freshness is not inferred from
+//     an entry date - it is part of the section, written by the machine that touched it.
+//  3. Freshness is graded and always surfaced. A stale section is shown WITH its staleness, so
+//     an agent reads it as a hypothesis to check rather than a fact to trust.
+//
+// It is workspace-only: a repository state file in the global layer would describe no repository.
+// It is a single file, not a layered kind - an overview that needs an index is not an overview.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { workspaceDir } from './store.js'
+
+/** A section verified within this window is current. */
+export const STATE_FRESH_MS = 6 * 3600_000
+/** Past this, a section describes a repository that has probably moved on. */
+export const STATE_STALE_MS = 72 * 3600_000
+
+/** Suggested sections. Any name is allowed; these keep separate agents consistent. */
+export const STATE_SECTIONS = ['Summary', 'Layout', 'Running', 'Pending', 'Health']
+
+/** Absolute path of a workspace state file. */
+export function statePath(root, key) { return join(workspaceDir(root, key), 'state.md') }
+
+/** True when a section name is usable as a heading. */
+export function isValidSectionName(name) {
+  const text = String(name ?? '').trim()
+  return text !== '' && text.length <= 60 && !/[\r\n]/.test(text) && !text.startsWith('#')
+}
+
+/** Canonical display form of a section name: trimmed, first letter upper-cased. */
+export function sectionTitle(name) {
+  const text = String(name ?? '').trim().replace(/\s+/g, ' ')
+  if (text === '') return ''
+  return text[0].toUpperCase() + text.slice(1)
+}
+
+/** Matching key for a section name, so "summary" and "Summary" are the same section. */
+export function sectionKey(name) { return String(name ?? '').trim().toLowerCase() }
+
+/**
+ * Make content safe to embed: a line starting with one or two hashes would be read as a new
+ * section heading on the next parse, so such lines are demoted. The text survives; the
+ * structure of the file does not break.
+ */
+/** A line that would parse as a heading, escaped so it survives as text. */
+const HEADING_ESCAPE = /^(#{1,6}\s)/
+
+export function sanitizeSectionContent(content) {
+  return String(content ?? '')
+    .replace(/\r\n/g, '\n')
+    .split('\n')
+    .map((line) => line.replace(HEADING_ESCAPE, '\\$1'))
+    .join('\n')
+    .trim()
+}
+
+/** Undo the heading escape when reading a section back. */
+function unsanitizeSectionContent(content) {
+  return String(content ?? '').split('\n').map((line) => line.replace(/^\\(#{1,6}\s)/, '$1')).join('\n')
+}
+
+/**
+ * Freshness of one section, graded rather than binary.
+ * @param verified - ISO timestamp the section was last confirmed.
+ * @param now - epoch ms.
+ * @param options.freshMs / options.staleMs - thresholds.
+ * @returns {{verdict: 'fresh'|'aging'|'stale'|'unverified', ageMs: number|undefined, days: number|undefined}}
+ */
+export function stateVerdict(verified, now = Date.now(), options = {}) {
+  const freshMs = options.freshMs ?? STATE_FRESH_MS
+  const staleMs = options.staleMs ?? STATE_STALE_MS
+  const parsed = Date.parse(String(verified ?? ''))
+  if (!Number.isFinite(parsed)) return { verdict: 'unverified', ageMs: undefined, days: undefined }
+  const ageMs = Math.max(0, now - parsed)
+  const days = Math.round((ageMs / 86400000) * 10) / 10
+  if (ageMs <= freshMs) return { verdict: 'fresh', ageMs, days }
+  if (ageMs <= staleMs) return { verdict: 'aging', ageMs, days }
+  return { verdict: 'stale', ageMs, days }
+}
+
+/** Human age: 20m, 5h, 3d. */
+export function humanAge(ageMs) {
+  if (!Number.isFinite(ageMs)) return 'unknown'
+  if (ageMs < 60_000) return 'just now'
+  const minutes = Math.round(ageMs / 60_000)
+  if (minutes < 60) return minutes + 'm'
+  const hours = Math.round(ageMs / 3600_000)
+  if (hours < 48) return hours + 'h'
+  return Math.round(ageMs / 86400_000) + 'd'
+}
+
+/** The marker shown wherever a non-fresh section appears. */
+export function freshnessMarker(verdict, ageMs) {
+  if (verdict === 'fresh') return ''
+  if (verdict === 'unverified') return ' [UNVERIFIED]'
+  return ' [' + verdict.toUpperCase() + ' ' + humanAge(ageMs) + ']'
+}
+
+/**
+ * Parse a state file.
+ * @returns {{ updated: string|undefined, sections: {name: string, verified: string|undefined, source: string|undefined, content: string}[] }}
+ */
+export function parseState(text) {
+  const lines = String(text ?? '').split('\n')
+  const sections = []
+  let updated
+  let current = null
+  const push = () => { if (current) { current.content = unsanitizeSectionContent(current.content.join('\n').trim()); sections.push(current) } }
+  for (const line of lines) {
+    const stamp = /^Last updated:\s*(.+)$/.exec(line.trim())
+    if (stamp && updated === undefined) { updated = stamp[1].trim(); continue }
+    const heading = /^##\s+(.+)$/.exec(line)
+    if (heading) {
+      push()
+      current = { name: heading[1].trim(), verified: undefined, source: undefined, content: [] }
+      continue
+    }
+    if (!current) continue
+    const verified = /^\*\*Verified:\*\*\s*(.*)$/.exec(line.trim())
+    if (verified) { current.verified = verified[1].trim() || undefined; continue }
+    const source = /^\*\*Source:\*\*\s*(.*)$/.exec(line.trim())
+    if (source) { current.source = source[1].trim() || undefined; continue }
+    current.content.push(line)
+  }
+  push()
+  return { updated, sections }
+}
+
+/** Render a whole state file from its sections. */
+export function renderState(title, sections, options = {}) {
+  const now = options.now ?? new Date().toISOString()
+  const out = [
+    '# ' + title + ' — state',
+    '',
+    'What this repository is right now. Each section carries when it was last verified:',
+    'treat a stale section as a hypothesis to check, not a fact to trust.',
+    '',
+    'Last updated: ' + now,
+    '',
+  ]
+  for (const section of sections) {
+    out.push('## ' + section.name, '')
+    if (section.verified) out.push('**Verified:** ' + section.verified)
+    if (section.source) out.push('**Source:** ' + section.source)
+    out.push('', section.content.trim(), '')
+  }
+  return out.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n'
+}
+
+/** Read and grade a workspace state file. Returns undefined when there is none. */
+export function readState(root, key, options = {}) {
+  const path = statePath(root, key)
+  if (!existsSync(path)) return undefined
+  let text
+  try { text = readFileSync(path, 'utf8') } catch { return undefined }
+  const parsed = parseState(text)
+  const now = options.now ?? Date.now()
+  const sections = parsed.sections.map((section) => ({
+    ...section,
+    ...stateVerdict(section.verified, now, options),
+  }))
+  return { path, updated: parsed.updated, sections }
+}
+
+/**
+ * Write one section, replacing any existing section with the same name.
+ *
+ * The replacement is the point: state describes now, so the newer statement wins. Other
+ * sections are preserved untouched, including their own timestamps - editing one area of a
+ * repository must not make an unrelated section look freshly verified.
+ *
+ * @returns {{ section: string, verified: string, created: boolean, sections: string[] }}
+ */
+export function writeStateSection(root, key, section, content, options = {}) {
+  const name = sectionTitle(section)
+  if (!isValidSectionName(name)) throw new Error('invalid state section name: ' + String(section))
+  const body = sanitizeSectionContent(content)
+  if (body === '') throw new Error('state section content must not be empty')
+  const now = options.now ?? new Date().toISOString()
+  const existing = readState(root, key, { now: Date.parse(now) }) ?? { sections: [] }
+  const wanted = sectionKey(name)
+  const kept = existing.sections
+    .filter((s) => sectionKey(s.name) !== wanted)
+    .map((s) => ({ name: s.name, verified: s.verified, source: s.source, content: s.content }))
+  const created = kept.length === existing.sections.length
+  // Keep the casing already in use for this section, so re-writing "RUNNING" does not
+  // silently restyle a heading another agent established.
+  const prior = existing.sections.find((s) => sectionKey(s.name) === wanted)
+  const written = { name: prior ? prior.name : name, verified: now, source: options.source, content: body }
+  // Keep the suggested order when the sections are familiar, else append in insertion order.
+  const next = [...kept, written].sort((a, b) => {
+    const ia = STATE_SECTIONS.findIndex((s) => sectionKey(s) === sectionKey(a.name))
+    const ib = STATE_SECTIONS.findIndex((s) => sectionKey(s) === sectionKey(b.name))
+    if (ia === -1 && ib === -1) return 0
+    if (ia === -1) return 1
+    if (ib === -1) return -1
+    return ia - ib
+  })
+  mkdirSync(workspaceDir(root, key), { recursive: true })
+  writeFileSync(statePath(root, key), renderState(key, next, { now }), 'utf8')
+  // Report the name that was actually written, not the one computed from this call, or the
+  // return value would disagree with the file whenever the casing is reused.
+  return { section: written.name, verified: now, created, sections: next.map((s) => s.name) }
+}
+
+/**
+ * What is safe to trust right now, and what needs re-checking.
+ * @returns {{ sections: object[], stale: string[], missing: string[], fresh: number }}
+ */
+export function summarizeState(root, key, options = {}) {
+  const state = readState(root, key, options)
+  const sections = state ? state.sections : []
+  const present = new Set(sections.map((s) => sectionKey(s.name)))
+  return {
+    sections,
+    stale: sections.filter((s) => s.verdict !== 'fresh').map((s) => s.name),
+    missing: STATE_SECTIONS.filter((s) => !present.has(sectionKey(s))),
+    fresh: sections.filter((s) => s.verdict === 'fresh').length,
+  }
+}
+
+/** The state template seeded for a new workspace. */
+export function stateTemplate(title) {
+  return [
+    '# ' + title + ' — state',
+    '',
+    'What this repository is right now. Each section carries when it was last verified:',
+    'treat a stale section as a hypothesis to check, not a fact to trust.',
+    '',
+    'No sections recorded yet. Use memory_state to describe the current state.',
+    '',
+  ].join('\n')
+}