@try-works/dsh-memory 0.1.19 → 0.1.21

package/src/fixture.js

@@ -1,56 +1,56 @@
-// Behavior-fixture regression suite: a single entry point that runs the critical
-// behaviors (ranking, freshness, forgetting, budget, workspace-key) under a fixed
-// clock and reports any regression by name.
-import { remember } from './remember.js'
-import { search } from './search.js'
-import { freshnessVerdict } from './freshness.js'
-import { forget } from './forget.js'
-import { allocateContextLanes } from './context.js'
-import { deriveWorkspaceKey } from './workspace-key.js'
-
-const DAY = 86400000
-
-export function runBehaviorFixtures(store, now = Date.now()) {
-  const results = []
-  const check = (id, axis, ok, detail) => results.push({ id, axis, ok, detail })
-
-  // ranking: importance-3 outranks importance-1 for the same term
-  remember(store, { scope: 'global', layer: 'semantic', text: 'critical zebra fact', importance: 3, topic: 'Critical' })
-  remember(store, { scope: 'global', layer: 'semantic', text: 'routine zebra fact', importance: 1, topic: 'Routine' })
-  const hits = search(store, 'zebra', { scope: 'global', limit: 5 })
-  const crit = hits.findIndex((h) => h.id === 'global-sem-0001')
-  const routine = hits.findIndex((h) => h.id === 'global-sem-0002')
-  check('rank-01', 'ranking', crit >= 0 && (routine < 0 || crit < routine), 'importance-3 before importance-1')
-
-  // freshness: the entry carries its own decay rate, and Verified is the age basis
-  const future = now + 40 * DAY
-  const stale = freshnessVerdict({ status: 'active', updated: new Date(now - 40 * DAY).toISOString(), content: 'durable' }, future)
-  check('fresh-01', 'freshness', stale.verdict === 'stale', 'stale after 40 days at normal volatility')
-  const stable = freshnessVerdict({ status: 'active', volatility: 'stable', updated: new Date(now - 40 * DAY).toISOString() }, future)
-  check('fresh-02', 'freshness', stable.verdict === 'fresh', 'stable content is not stale at 40 days')
-  const volatile = freshnessVerdict({ status: 'active', volatility: 'volatile', updated: new Date(now - 10 * DAY).toISOString() }, now)
-  check('fresh-03', 'freshness', volatile.verdict === 'stale', 'volatile content is stale at 10 days')
-  const reconfirmed = freshnessVerdict({ status: 'active', date: new Date(now - 400 * DAY).toISOString(), verified: new Date(now - 1 * DAY).toISOString() }, now)
-  check('fresh-04', 'freshness', reconfirmed.verdict === 'fresh', 'Verified beats an old Date')
-  const inferred = freshnessVerdict({ status: 'active', updated: new Date(now - 10 * DAY).toISOString(), content: 'currently pending' }, now)
-  check('fresh-05', 'freshness', inferred.verdict === 'stale', 'time-bounded language still hints volatile')
-
-  // forgetting: forget blocks re-remember of the same text
-  const r = remember(store, { scope: 'global', layer: 'semantic', text: 'forget me please', topic: 'Forget' })
-  forget(store, r.id)
-  let blocked = false
-  try { remember(store, { scope: 'global', layer: 'semantic', text: 'forget me please' }) } catch { blocked = true }
-  check('forget-01', 'forgetting', blocked, 're-remember blocked after forget')
-
-  // budget: working-memory floor preserved under a tiny budget
-  const alloc = allocateContextLanes({ budgetTokens: 100, demand: { working: 500, episodes: 500, learnings: 500, queryRecall: 500 } })
-  check('budget-01', 'budget', alloc.allocated.working === 100, 'working floor under constraint')
-
-  // workspace-key: remote-derived key + no traversal
-  check('key-01', 'workspace-key', deriveWorkspaceKey({ remote: 'git@github.com:owner/repo.git' }) === 'owner-repo', 'remote-derived key')
-  const hostile = deriveWorkspaceKey({ basename: '../etc' })
-  check('key-02', 'workspace-key', hostile === undefined || (!hostile.includes('..') && !hostile.includes('/')), 'no traversal from hostile basename')
-
-  const failed = results.filter((r) => !r.ok)
-  return { total: results.length, passed: results.length - failed.length, failed, results }
-}
+// Behavior-fixture regression suite: a single entry point that runs the critical
+// behaviors (ranking, freshness, forgetting, budget, workspace-key) under a fixed
+// clock and reports any regression by name.
+import { remember } from './remember.js'
+import { search } from './search.js'
+import { freshnessVerdict } from './freshness.js'
+import { forget } from './forget.js'
+import { allocateContextLanes } from './context.js'
+import { deriveWorkspaceKey } from './workspace-key.js'
+
+const DAY = 86400000
+
+export function runBehaviorFixtures(store, now = Date.now()) {
+  const results = []
+  const check = (id, axis, ok, detail) => results.push({ id, axis, ok, detail })
+
+  // ranking: importance-3 outranks importance-1 for the same term
+  remember(store, { scope: 'global', layer: 'semantic', text: 'critical zebra fact', importance: 3, topic: 'Critical' })
+  remember(store, { scope: 'global', layer: 'semantic', text: 'routine zebra fact', importance: 1, topic: 'Routine' })
+  const hits = search(store, 'zebra', { scope: 'global', limit: 5 })
+  const crit = hits.findIndex((h) => h.id === 'global-sem-0001')
+  const routine = hits.findIndex((h) => h.id === 'global-sem-0002')
+  check('rank-01', 'ranking', crit >= 0 && (routine < 0 || crit < routine), 'importance-3 before importance-1')
+
+  // freshness: the entry carries its own decay rate, and Verified is the age basis
+  const future = now + 40 * DAY
+  const stale = freshnessVerdict({ status: 'active', updated: new Date(now - 40 * DAY).toISOString(), content: 'durable' }, future)
+  check('fresh-01', 'freshness', stale.verdict === 'stale', 'stale after 40 days at normal volatility')
+  const stable = freshnessVerdict({ status: 'active', volatility: 'stable', updated: new Date(now - 40 * DAY).toISOString() }, future)
+  check('fresh-02', 'freshness', stable.verdict === 'fresh', 'stable content is not stale at 40 days')
+  const volatile = freshnessVerdict({ status: 'active', volatility: 'volatile', updated: new Date(now - 10 * DAY).toISOString() }, now)
+  check('fresh-03', 'freshness', volatile.verdict === 'stale', 'volatile content is stale at 10 days')
+  const reconfirmed = freshnessVerdict({ status: 'active', date: new Date(now - 400 * DAY).toISOString(), verified: new Date(now - 1 * DAY).toISOString() }, now)
+  check('fresh-04', 'freshness', reconfirmed.verdict === 'fresh', 'Verified beats an old Date')
+  const inferred = freshnessVerdict({ status: 'active', updated: new Date(now - 10 * DAY).toISOString(), content: 'currently pending' }, now)
+  check('fresh-05', 'freshness', inferred.verdict === 'stale', 'time-bounded language still hints volatile')
+
+  // forgetting: forget blocks re-remember of the same text
+  const r = remember(store, { scope: 'global', layer: 'semantic', text: 'forget me please', topic: 'Forget' })
+  forget(store, r.id)
+  let blocked = false
+  try { remember(store, { scope: 'global', layer: 'semantic', text: 'forget me please' }) } catch { blocked = true }
+  check('forget-01', 'forgetting', blocked, 're-remember blocked after forget')
+
+  // budget: working-memory floor preserved under a tiny budget
+  const alloc = allocateContextLanes({ budgetTokens: 100, demand: { working: 500, episodes: 500, learnings: 500, queryRecall: 500 } })
+  check('budget-01', 'budget', alloc.allocated.working === 100, 'working floor under constraint')
+
+  // workspace-key: remote-derived key + no traversal
+  check('key-01', 'workspace-key', deriveWorkspaceKey({ remote: 'git@github.com:owner/repo.git' }) === 'owner-repo', 'remote-derived key')
+  const hostile = deriveWorkspaceKey({ basename: '../etc' })
+  check('key-02', 'workspace-key', hostile === undefined || (!hostile.includes('..') && !hostile.includes('/')), 'no traversal from hostile basename')
+
+  const failed = results.filter((r) => !r.ok)
+  return { total: results.length, passed: results.length - failed.length, failed, results }
+}

package/src/forget.js

@@ -1,71 +1,71 @@
-// Forget tombstones: hash-only, scope-scoped, exact-normalized-match suppression.
-// Enforced at the write site (remember) so a forgotten fact is never re-added silently.
-import { createHash } from 'node:crypto'
-import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
-import { buildLedger } from './ledger.js'
-import { setEntryStatus } from './entry.js'
-import { updateIndex } from './fts.js'
-import { layerIndexPath, rebuildLayerIndexes, scopeOfFile } from './layers.js'
-import { layersForScope } from './entry.js'
-
-/** trim -> whitespace-collapse -> NFKC -> lowercase (exact match only, never paraphrase). */
-export function normalizeForSuppression(text) {
-  return String(text ?? '').trim().replace(/\s+/g, ' ').normalize('NFKC').toLowerCase()
-}
-
-export function suppressionHash(scope, text) {
-  return createHash('sha256').update((scope ?? 'global') + '\0' + normalizeForSuppression(text)).digest('hex')
-}
-
-export function tombstonesPath(root) { return join(root, 'state', 'tombstones.jsonl') }
-
-export function readTombstones(root) {
-  try {
-    return readFileSync(tombstonesPath(root), 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l))
-  } catch { return [] }
-}
-
-function appendTombstone(root, rec) {
-  mkdirSync(join(root, 'state'), { recursive: true })
-  appendFileSync(tombstonesPath(root), JSON.stringify(rec) + '\n')
-}
-
-export function isSuppressed(root, scope, text) {
-  const hash = suppressionHash(scope, text)
-  return readTombstones(root).some((t) => t.hash === hash)
-}
-
-/** Supersede an entry in place and record a tombstone so it can never be re-added. */
-export function forget(store, id) {
-  const entry = buildLedger(store.root).find((e) => e.id === id)
-  if (!entry) throw new Error('no such entry: ' + id)
-  const scope = entry.file.startsWith('global/') ? 'global' : entry.file.split('/')[1]
-  const hash = suppressionHash(scope, entry.content)
-  appendTombstone(store.root, { hash, scope, id, createdAt: new Date().toISOString(), reason: 'user-forget' })
-  const file = join(store.root, entry.file)
-  writeFileSync(file, setEntryStatus(readFileSync(file, 'utf8'), id, 'superseded', 'user-forget'), 'utf8')
-  // keep the layer index in step with the topic file it points at
-  const where = scopeOfFile(entry.file)
-  if (where) rebuildLayerIndexes(store.root, where.scope, where.key)
-  updateIndex(store.root, [
-    file,
-    ...(where ? layersForScope(where.scope).map((l) => layerIndexPath(store.root, where.scope, where.key, l)) : []),
-  ])
-  return { id, hash, scope }
-}
-
-/** Release a forgotten entry's tombstone (explicit action only). Entry stays superseded. */
-export function forgetUndo(store, id) {
-  const list = readTombstones(store.root)
-  const remaining = list.filter((t) => t.id !== id)
-  if (remaining.length === list.length) return false
-  mkdirSync(join(store.root, 'state'), { recursive: true })
-  writeFileSync(tombstonesPath(store.root), remaining.map((t) => JSON.stringify(t)).join('\n') + (remaining.length ? '\n' : ''), 'utf8')
-  return true
-}
-
-/** Hash-prefixed tombstone listing (no plaintext). */
-export function forgetList(store) {
-  return readTombstones(store.root).map((t) => ({ id: t.id, scope: t.scope, createdAt: t.createdAt, reason: t.reason, hashPrefix: t.hash.slice(0, 12) }))
-}
+// Forget tombstones: hash-only, scope-scoped, exact-normalized-match suppression.
+// Enforced at the write site (remember) so a forgotten fact is never re-added silently.
+import { createHash } from 'node:crypto'
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { buildLedger } from './ledger.js'
+import { setEntryStatus } from './entry.js'
+import { updateIndex } from './fts.js'
+import { layerIndexPath, rebuildLayerIndexes, scopeOfFile } from './layers.js'
+import { layersForScope } from './entry.js'
+
+/** trim -> whitespace-collapse -> NFKC -> lowercase (exact match only, never paraphrase). */
+export function normalizeForSuppression(text) {
+  return String(text ?? '').trim().replace(/\s+/g, ' ').normalize('NFKC').toLowerCase()
+}
+
+export function suppressionHash(scope, text) {
+  return createHash('sha256').update((scope ?? 'global') + '\0' + normalizeForSuppression(text)).digest('hex')
+}
+
+export function tombstonesPath(root) { return join(root, 'state', 'tombstones.jsonl') }
+
+export function readTombstones(root) {
+  try {
+    return readFileSync(tombstonesPath(root), 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l))
+  } catch { return [] }
+}
+
+function appendTombstone(root, rec) {
+  mkdirSync(join(root, 'state'), { recursive: true })
+  appendFileSync(tombstonesPath(root), JSON.stringify(rec) + '\n')
+}
+
+export function isSuppressed(root, scope, text) {
+  const hash = suppressionHash(scope, text)
+  return readTombstones(root).some((t) => t.hash === hash)
+}
+
+/** Supersede an entry in place and record a tombstone so it can never be re-added. */
+export function forget(store, id) {
+  const entry = buildLedger(store.root).find((e) => e.id === id)
+  if (!entry) throw new Error('no such entry: ' + id)
+  const scope = entry.file.startsWith('global/') ? 'global' : entry.file.split('/')[1]
+  const hash = suppressionHash(scope, entry.content)
+  appendTombstone(store.root, { hash, scope, id, createdAt: new Date().toISOString(), reason: 'user-forget' })
+  const file = join(store.root, entry.file)
+  writeFileSync(file, setEntryStatus(readFileSync(file, 'utf8'), id, 'superseded', 'user-forget'), 'utf8')
+  // keep the layer index in step with the topic file it points at
+  const where = scopeOfFile(entry.file)
+  if (where) rebuildLayerIndexes(store.root, where.scope, where.key)
+  updateIndex(store.root, [
+    file,
+    ...(where ? layersForScope(where.scope).map((l) => layerIndexPath(store.root, where.scope, where.key, l)) : []),
+  ])
+  return { id, hash, scope }
+}
+
+/** Release a forgotten entry's tombstone (explicit action only). Entry stays superseded. */
+export function forgetUndo(store, id) {
+  const list = readTombstones(store.root)
+  const remaining = list.filter((t) => t.id !== id)
+  if (remaining.length === list.length) return false
+  mkdirSync(join(store.root, 'state'), { recursive: true })
+  writeFileSync(tombstonesPath(store.root), remaining.map((t) => JSON.stringify(t)).join('\n') + (remaining.length ? '\n' : ''), 'utf8')
+  return true
+}
+
+/** Hash-prefixed tombstone listing (no plaintext). */
+export function forgetList(store) {
+  return readTombstones(store.root).map((t) => ({ id: t.id, scope: t.scope, createdAt: t.createdAt, reason: t.reason, hashPrefix: t.hash.slice(0, 12) }))
+}

package/src/freshness.js

@@ -1,65 +1,65 @@
-// Deterministic freshness verdicts over the derived entry ledger. Pure.
-//
-// Freshness is decided from metadata the ENTRY carries - its declared volatility and when it
-// was last verified - rather than from one global constant applied to a write date. A language
-// choice and a port number do not decay at the same rate, and only the writer knows which is
-// which. The old global threshold treated every fact as equally perishable.
-import { normalizeVolatility, VOLATILITY_DAYS } from './entry.js'
-
-/** Fallback window for entries written before volatility was recorded. */
-export const STALE_DAYS = VOLATILITY_DAYS.normal
-/** Volatile entries are reviewed after this many days even when not yet due. */
-export const VOLATILE_DAYS = VOLATILITY_DAYS.volatile
-const DAY_MS = 86400000
-
-/** Language that marks a statement as time-bound, regardless of declared volatility. */
-const TIME_BOUNDED_RE = /\b(currently|as of|as-of|pending|soon|today|this week|planned|plan to|to do|todo|next week|upcoming|will|wip|tbd)\b/i
-
-/** Time-bounded language marks a fact as volatile (decays faster than durable facts). */
-export function isVolatile(text) { return TIME_BOUNDED_RE.test(String(text ?? '')) }
-
-/**
- * Days after which this entry is worth re-checking.
- *
- * Precedence: the entry's declared volatility, then (for entries written before the field
- * existed) time-bounded language, then the normal window.
- */
-export function staleAfterDays(entry = {}) {
-  if (entry.volatility) return VOLATILITY_DAYS[normalizeVolatility(entry.volatility)]
-  if (isVolatile(entry.content)) return VOLATILITY_DAYS.volatile
-  return STALE_DAYS
-}
-
-/**
- * Verdict tiers: skip (non-active) > expired (Valid-until) > stale (past its own window) >
- * review (volatile and aging) > fresh.
- *
- * Age is measured from **Verified** when present - that is when the fact was last confirmed
- * true - and falls back to Updated/Date, which only say when it was written.
- */
-export function freshnessVerdict(entry, nowMs = Date.now()) {
-  if (entry.status && entry.status !== 'active') return { verdict: 'skip' }
-  if (entry.until && Date.parse(entry.until) <= nowMs) return { verdict: 'expired' }
-  const base = entry.verified ?? entry.updated ?? entry.date
-  const updatedMs = base ? Date.parse(base) : nowMs
-  const days = Math.max(0, (nowMs - updatedMs) / DAY_MS)
-  const window = staleAfterDays(entry)
-  if (days > window) return { verdict: 'stale', days: Math.round(days), window }
-  const volatility = entry.volatility ?? (isVolatile(entry.content) ? 'volatile' : 'normal')
-  if (volatility === 'volatile' && days > VOLATILITY_DAYS.volatile) {
-    return { verdict: 'review', days: Math.round(days), window }
-  }
-  return { verdict: 'fresh', days: Math.round(days), window }
-}
-
-/** Return only entries that need attention (expired/stale/review), annotated with their verdict. */
-export function scanFreshness(ledger, nowMs = Date.now()) {
-  return ledger
-    .map((e) => ({ ...e, ...freshnessVerdict(e, nowMs) }))
-    .filter((e) => e.verdict !== 'fresh' && e.verdict !== 'skip')
-}
-
-/** Confirm an entry is still true now: returns the metadata patch the writer should apply. */
-export function verifiedPatch(nowIso = new Date().toISOString()) {
-  return { verified: nowIso, updated: nowIso }
-}
+// Deterministic freshness verdicts over the derived entry ledger. Pure.
+//
+// Freshness is decided from metadata the ENTRY carries - its declared volatility and when it
+// was last verified - rather than from one global constant applied to a write date. A language
+// choice and a port number do not decay at the same rate, and only the writer knows which is
+// which. The old global threshold treated every fact as equally perishable.
+import { normalizeVolatility, VOLATILITY_DAYS } from './entry.js'
+
+/** Fallback window for entries written before volatility was recorded. */
+export const STALE_DAYS = VOLATILITY_DAYS.normal
+/** Volatile entries are reviewed after this many days even when not yet due. */
+export const VOLATILE_DAYS = VOLATILITY_DAYS.volatile
+const DAY_MS = 86400000
+
+/** Language that marks a statement as time-bound, regardless of declared volatility. */
+const TIME_BOUNDED_RE = /\b(currently|as of|as-of|pending|soon|today|this week|planned|plan to|to do|todo|next week|upcoming|will|wip|tbd)\b/i
+
+/** Time-bounded language marks a fact as volatile (decays faster than durable facts). */
+export function isVolatile(text) { return TIME_BOUNDED_RE.test(String(text ?? '')) }
+
+/**
+ * Days after which this entry is worth re-checking.
+ *
+ * Precedence: the entry's declared volatility, then (for entries written before the field
+ * existed) time-bounded language, then the normal window.
+ */
+export function staleAfterDays(entry = {}) {
+  if (entry.volatility) return VOLATILITY_DAYS[normalizeVolatility(entry.volatility)]
+  if (isVolatile(entry.content)) return VOLATILITY_DAYS.volatile
+  return STALE_DAYS
+}
+
+/**
+ * Verdict tiers: skip (non-active) > expired (Valid-until) > stale (past its own window) >
+ * review (volatile and aging) > fresh.
+ *
+ * Age is measured from **Verified** when present - that is when the fact was last confirmed
+ * true - and falls back to Updated/Date, which only say when it was written.
+ */
+export function freshnessVerdict(entry, nowMs = Date.now()) {
+  if (entry.status && entry.status !== 'active') return { verdict: 'skip' }
+  if (entry.until && Date.parse(entry.until) <= nowMs) return { verdict: 'expired' }
+  const base = entry.verified ?? entry.updated ?? entry.date
+  const updatedMs = base ? Date.parse(base) : nowMs
+  const days = Math.max(0, (nowMs - updatedMs) / DAY_MS)
+  const window = staleAfterDays(entry)
+  if (days > window) return { verdict: 'stale', days: Math.round(days), window }
+  const volatility = entry.volatility ?? (isVolatile(entry.content) ? 'volatile' : 'normal')
+  if (volatility === 'volatile' && days > VOLATILITY_DAYS.volatile) {
+    return { verdict: 'review', days: Math.round(days), window }
+  }
+  return { verdict: 'fresh', days: Math.round(days), window }
+}
+
+/** Return only entries that need attention (expired/stale/review), annotated with their verdict. */
+export function scanFreshness(ledger, nowMs = Date.now()) {
+  return ledger
+    .map((e) => ({ ...e, ...freshnessVerdict(e, nowMs) }))
+    .filter((e) => e.verdict !== 'fresh' && e.verdict !== 'skip')
+}
+
+/** Confirm an entry is still true now: returns the metadata patch the writer should apply. */
+export function verifiedPatch(nowIso = new Date().toISOString()) {
+  return { verified: nowIso, updated: nowIso }
+}