@try-works/dsh-memory 0.1.19 → 0.1.21

package/src/map.js

@@ -1,184 +1,184 @@
-// The UI snapshot behind memory_map: one structured view of the store, and of what THIS
-// session has received from memory and written back to it.
-//
-// Three rules shape this module.
-//
-// Every number is DERIVED, never restated. Freshness comes from freshnessVerdict, the queue
-// from the queue reader, and the RECEIVED panel from the injection's own rendered text. A
-// second set of rules here would drift from the first, and the UI would then lie about the
-// store it exists to describe.
-//
-// The snapshot is LOSSLESS JSON - no undefined, no Date, no Map. It crosses the tool boundary
-// and a browser parses it, so one undefined rejects the whole result.
-//
-// Store and session are separate scopes because they answer different questions and have
-// different lifetimes. The store is what EXISTS; the session is what THIS conversation saw
-// and wrote. A tab can show either without pretending the other is live.
-
-import { buildLedger } from './ledger.js'
-import { LAYERS } from './entry.js'
-import { freshnessVerdict } from './freshness.js'
-import { buildInjectionText } from './inject.js'
-import { problems, summarize } from './queue.js'
-
-/** How many scopes and written entries the snapshot carries before it summarises instead. */
-const SCOPE_LIMIT = 6
-const WRITTEN_LIMIT = 8
-
-/** Doubt, worst first: a group reports the most doubtful thing inside it, not the best. */
-const SEVERITY = { fresh: 0, empty: 1, aging: 2, unverified: 3, stale: 4 }
-
-function worstVerdict(verdicts) {
-  let worst = 'fresh'
-  for (const verdict of verdicts) {
-    if ((SEVERITY[verdict] ?? 0) > (SEVERITY[worst] ?? 0)) worst = verdict
-  }
-  return worst
-}
-
-/** The workspace key a ledger file belongs to, or 'global' for the shared layer. */
-export function scopeKeyOf(file) {
-  const normalised = String(file ?? '').replace(/\\/g, '/')
-  const match = normalised.match(/workspaces\/([^/]+)\//)
-  return match ? match[1] : 'global'
-}
-
-function tally(values) {
-  const out = {}
-  for (const value of values) out[value] = (out[value] ?? 0) + 1
-  return out
-}
-
-/**
- * Whole-store composition: entries per layer, how fresh they are, which workspaces hold
- * them, and what the ingest queue is doing.
- * @param store - the memory store.
- * @param options.ledger - a prebuilt ledger, so a caller needing two scopes reads the disk once.
- */
-export function buildStoreSnapshot(store, { ledger, now = Date.now(), scopeLimit = SCOPE_LIMIT } = {}) {
-  const entries = ledger ?? buildLedger(store.root)
-  // The verdict vocabulary belongs to the freshness module. An unrecognised verdict counts as
-  // fresh, so a new one upstream shows up as a total that does not add up - visible - rather
-  // than as a crash or a silent zero.
-  const freshness = { fresh: 0, stale: 0, expired: 0, skip: 0 }
-  for (const entry of entries) {
-    const verdict = freshnessVerdict(entry, now).verdict
-    freshness[Object.hasOwn(freshness, verdict) ? verdict : 'fresh'] += 1
-  }
-  const layerCounts = tally(entries.map((e) => e.layer))
-  const scopeCounts = tally(entries.map((e) => scopeKeyOf(e.file)))
-  const scopes = Object.keys(scopeCounts)
-    .map((key) => ({ key, count: scopeCounts[key] }))
-    .sort((a, b) => b.count - a.count || a.key.localeCompare(b.key))
-  const states = summarize(store.root)
-  // Group problem rows by state and reason: 76 orphaned candidates are ONE fact about the
-  // store, not 76 lines of UI.
-  const grouped = new Map()
-  for (const problem of problems(store.root)) {
-    const reason = problem.reason ?? 'unclassified'
-    const key = problem.state + '|' + reason
-    const seen = grouped.get(key)
-    if (seen) seen.count += 1
-    else grouped.set(key, { state: problem.state, reason, count: 1 })
-  }
-  return {
-    root: store.root,
-    total: entries.length,
-    layers: LAYERS.map((name) => ({ name, count: layerCounts[name] ?? 0 })),
-    freshness,
-    scopes: scopes.slice(0, scopeLimit),
-    scopeTotal: scopes.length,
-    queue: {
-      states,
-      waiting: (states.pending ?? 0) + (states.summarized ?? 0),
-      recoverable: states.orphaned ?? 0,
-      attention: [...grouped.values()].sort((a, b) => b.count - a.count),
-    },
-  }
-}
-
-/** The marker vocabulary the injection actually emits. Matching only these keeps a bracketed
- * word inside an entry's prose from being read as a freshness verdict. */
-const MARKER = /\[(STALE|AGING|UNVERIFIED|NOT STARTED)\b[^\]]*\]/g
-
-function verdictOfMarker(marker) {
-  if (marker.startsWith('[STALE')) return 'stale'
-  if (marker.startsWith('[AGING')) return 'aging'
-  if (marker.startsWith('[UNVERIFIED')) return 'unverified'
-  if (marker.startsWith('[NOT STARTED')) return 'empty'
-  return 'fresh'
-}
-
-/**
- * Read the sections back out of the injection's OWN rendered text.
- *
- * Parsing text is usually the wrong instinct, and here it is the right one: the question the
- * panel answers is 'what was actually put in front of this session', and the only artefact
- * that can answer it without the possibility of disagreement is the text itself. Recomputing
- * the sections from the same inputs would be a second implementation of one rule.
- */
-export function parseInjectionSections(text) {
-  const sections = []
-  for (const raw of String(text ?? '').split('\n')) {
-    const heading = raw.match(/^###\s+(.+?)\s*$/)
-    if (heading) {
-      const found = heading[1].match(MARKER) ?? []
-      // The heading is written for the agent ('Working memory - yours'); the panel labels the
-      // same thing more briefly, so the owner suffix is dropped at the boundary.
-      const name = heading[1].replace(MARKER, '').replace(/\s+\u2014\s+yours\s*$/, '').trim()
-      sections.push({ name, markers: [...found] })
-      continue
-    }
-    if (sections.length === 0) continue
-    const found = raw.match(MARKER)
-    if (found) sections[sections.length - 1].markers.push(...found)
-  }
-  return sections.map((section) => {
-    const verdict = worstVerdict(section.markers.map(verdictOfMarker))
-    const marker = section.markers.find((m) => verdictOfMarker(m) === verdict) ?? ''
-    return { name: section.name, verdict, marker }
-  })
-}
-
-/** What memory put in front of this session, sized and broken down as it was sent. */
-export function buildReceived(store, { memoryScope = 'global', key, goal, maxChars } = {}) {
-  const text = buildInjectionText(store, { scope: memoryScope, key, goal, maxChars })
-  return { chars: text.length, sections: parseInjectionSections(text) }
-}
-
-/**
- * What THIS session wrote back. Attribution is exact rather than inferred from timestamps:
- * every write already records source 'agent:<sessionId>', so two sessions writing in the same
- * minute are still told apart.
- */
-export function buildWritten(store, { ledger, sessionId, limit = WRITTEN_LIMIT } = {}) {
-  if (!sessionId) return { total: 0, byLayer: {}, entries: [] }
-  const marker = 'agent:' + sessionId
-  const written = (ledger ?? buildLedger(store.root)).filter((entry) => entry.source === marker)
-  const ordered = [...written].sort((a, b) => String(b.date ?? '').localeCompare(String(a.date ?? '')))
-  return {
-    total: written.length,
-    byLayer: tally(written.map((e) => e.layer)),
-    entries: ordered.slice(0, limit).map((e) => ({ id: e.id, layer: e.layer, heading: e.heading ?? '' })),
-  }
-}
-
-/**
- * One snapshot, either scope or both.
- * @param options.scope - 'store' (what exists), 'session' (what this conversation saw and wrote), or 'all'.
- * @param options.memoryScope - 'global' or 'workspace': which memory layer this session belongs to.
- */
-export function buildMap(store, { scope = 'all', sessionId, memoryScope = 'global', key, goal, now = Date.now(), maxChars } = {}) {
-  const ledger = buildLedger(store.root)
-  const snapshot = { scope, generatedAt: new Date(now).toISOString() }
-  if (scope === 'store' || scope === 'all') snapshot.store = buildStoreSnapshot(store, { ledger, now })
-  if (scope === 'session' || scope === 'all') {
-    snapshot.session = {
-      sessionId: sessionId ?? null,
-      workspace: memoryScope === 'workspace' ? (key ?? null) : null,
-      received: buildReceived(store, { memoryScope, key, goal, maxChars }),
-      written: buildWritten(store, { ledger, sessionId }),
-    }
-  }
-  return snapshot
-}
+// The UI snapshot behind memory_map: one structured view of the store, and of what THIS
+// session has received from memory and written back to it.
+//
+// Three rules shape this module.
+//
+// Every number is DERIVED, never restated. Freshness comes from freshnessVerdict, the queue
+// from the queue reader, and the RECEIVED panel from the injection's own rendered text. A
+// second set of rules here would drift from the first, and the UI would then lie about the
+// store it exists to describe.
+//
+// The snapshot is LOSSLESS JSON - no undefined, no Date, no Map. It crosses the tool boundary
+// and a browser parses it, so one undefined rejects the whole result.
+//
+// Store and session are separate scopes because they answer different questions and have
+// different lifetimes. The store is what EXISTS; the session is what THIS conversation saw
+// and wrote. A tab can show either without pretending the other is live.
+
+import { buildLedger } from './ledger.js'
+import { LAYERS } from './entry.js'
+import { freshnessVerdict } from './freshness.js'
+import { buildInjectionText } from './inject.js'
+import { problems, summarize } from './queue.js'
+
+/** How many scopes and written entries the snapshot carries before it summarises instead. */
+const SCOPE_LIMIT = 6
+const WRITTEN_LIMIT = 8
+
+/** Doubt, worst first: a group reports the most doubtful thing inside it, not the best. */
+const SEVERITY = { fresh: 0, empty: 1, aging: 2, unverified: 3, stale: 4 }
+
+function worstVerdict(verdicts) {
+  let worst = 'fresh'
+  for (const verdict of verdicts) {
+    if ((SEVERITY[verdict] ?? 0) > (SEVERITY[worst] ?? 0)) worst = verdict
+  }
+  return worst
+}
+
+/** The workspace key a ledger file belongs to, or 'global' for the shared layer. */
+export function scopeKeyOf(file) {
+  const normalised = String(file ?? '').replace(/\\/g, '/')
+  const match = normalised.match(/workspaces\/([^/]+)\//)
+  return match ? match[1] : 'global'
+}
+
+function tally(values) {
+  const out = {}
+  for (const value of values) out[value] = (out[value] ?? 0) + 1
+  return out
+}
+
+/**
+ * Whole-store composition: entries per layer, how fresh they are, which workspaces hold
+ * them, and what the ingest queue is doing.
+ * @param store - the memory store.
+ * @param options.ledger - a prebuilt ledger, so a caller needing two scopes reads the disk once.
+ */
+export function buildStoreSnapshot(store, { ledger, now = Date.now(), scopeLimit = SCOPE_LIMIT } = {}) {
+  const entries = ledger ?? buildLedger(store.root)
+  // The verdict vocabulary belongs to the freshness module. An unrecognised verdict counts as
+  // fresh, so a new one upstream shows up as a total that does not add up - visible - rather
+  // than as a crash or a silent zero.
+  const freshness = { fresh: 0, stale: 0, expired: 0, skip: 0 }
+  for (const entry of entries) {
+    const verdict = freshnessVerdict(entry, now).verdict
+    freshness[Object.hasOwn(freshness, verdict) ? verdict : 'fresh'] += 1
+  }
+  const layerCounts = tally(entries.map((e) => e.layer))
+  const scopeCounts = tally(entries.map((e) => scopeKeyOf(e.file)))
+  const scopes = Object.keys(scopeCounts)
+    .map((key) => ({ key, count: scopeCounts[key] }))
+    .sort((a, b) => b.count - a.count || a.key.localeCompare(b.key))
+  const states = summarize(store.root)
+  // Group problem rows by state and reason: 76 orphaned candidates are ONE fact about the
+  // store, not 76 lines of UI.
+  const grouped = new Map()
+  for (const problem of problems(store.root)) {
+    const reason = problem.reason ?? 'unclassified'
+    const key = problem.state + '|' + reason
+    const seen = grouped.get(key)
+    if (seen) seen.count += 1
+    else grouped.set(key, { state: problem.state, reason, count: 1 })
+  }
+  return {
+    root: store.root,
+    total: entries.length,
+    layers: LAYERS.map((name) => ({ name, count: layerCounts[name] ?? 0 })),
+    freshness,
+    scopes: scopes.slice(0, scopeLimit),
+    scopeTotal: scopes.length,
+    queue: {
+      states,
+      waiting: (states.pending ?? 0) + (states.summarized ?? 0),
+      recoverable: states.orphaned ?? 0,
+      attention: [...grouped.values()].sort((a, b) => b.count - a.count),
+    },
+  }
+}
+
+/** The marker vocabulary the injection actually emits. Matching only these keeps a bracketed
+ * word inside an entry's prose from being read as a freshness verdict. */
+const MARKER = /\[(STALE|AGING|UNVERIFIED|NOT STARTED)\b[^\]]*\]/g
+
+function verdictOfMarker(marker) {
+  if (marker.startsWith('[STALE')) return 'stale'
+  if (marker.startsWith('[AGING')) return 'aging'
+  if (marker.startsWith('[UNVERIFIED')) return 'unverified'
+  if (marker.startsWith('[NOT STARTED')) return 'empty'
+  return 'fresh'
+}
+
+/**
+ * Read the sections back out of the injection's OWN rendered text.
+ *
+ * Parsing text is usually the wrong instinct, and here it is the right one: the question the
+ * panel answers is 'what was actually put in front of this session', and the only artefact
+ * that can answer it without the possibility of disagreement is the text itself. Recomputing
+ * the sections from the same inputs would be a second implementation of one rule.
+ */
+export function parseInjectionSections(text) {
+  const sections = []
+  for (const raw of String(text ?? '').split('\n')) {
+    const heading = raw.match(/^###\s+(.+?)\s*$/)
+    if (heading) {
+      const found = heading[1].match(MARKER) ?? []
+      // The heading is written for the agent ('Working memory - yours'); the panel labels the
+      // same thing more briefly, so the owner suffix is dropped at the boundary.
+      const name = heading[1].replace(MARKER, '').replace(/\s+\u2014\s+yours\s*$/, '').trim()
+      sections.push({ name, markers: [...found] })
+      continue
+    }
+    if (sections.length === 0) continue
+    const found = raw.match(MARKER)
+    if (found) sections[sections.length - 1].markers.push(...found)
+  }
+  return sections.map((section) => {
+    const verdict = worstVerdict(section.markers.map(verdictOfMarker))
+    const marker = section.markers.find((m) => verdictOfMarker(m) === verdict) ?? ''
+    return { name: section.name, verdict, marker }
+  })
+}
+
+/** What memory put in front of this session, sized and broken down as it was sent. */
+export function buildReceived(store, { memoryScope = 'global', key, goal, maxChars } = {}) {
+  const text = buildInjectionText(store, { scope: memoryScope, key, goal, maxChars })
+  return { chars: text.length, sections: parseInjectionSections(text) }
+}
+
+/**
+ * What THIS session wrote back. Attribution is exact rather than inferred from timestamps:
+ * every write already records source 'agent:<sessionId>', so two sessions writing in the same
+ * minute are still told apart.
+ */
+export function buildWritten(store, { ledger, sessionId, limit = WRITTEN_LIMIT } = {}) {
+  if (!sessionId) return { total: 0, byLayer: {}, entries: [] }
+  const marker = 'agent:' + sessionId
+  const written = (ledger ?? buildLedger(store.root)).filter((entry) => entry.source === marker)
+  const ordered = [...written].sort((a, b) => String(b.date ?? '').localeCompare(String(a.date ?? '')))
+  return {
+    total: written.length,
+    byLayer: tally(written.map((e) => e.layer)),
+    entries: ordered.slice(0, limit).map((e) => ({ id: e.id, layer: e.layer, heading: e.heading ?? '' })),
+  }
+}
+
+/**
+ * One snapshot, either scope or both.
+ * @param options.scope - 'store' (what exists), 'session' (what this conversation saw and wrote), or 'all'.
+ * @param options.memoryScope - 'global' or 'workspace': which memory layer this session belongs to.
+ */
+export function buildMap(store, { scope = 'all', sessionId, memoryScope = 'global', key, goal, now = Date.now(), maxChars } = {}) {
+  const ledger = buildLedger(store.root)
+  const snapshot = { scope, generatedAt: new Date(now).toISOString() }
+  if (scope === 'store' || scope === 'all') snapshot.store = buildStoreSnapshot(store, { ledger, now })
+  if (scope === 'session' || scope === 'all') {
+    snapshot.session = {
+      sessionId: sessionId ?? null,
+      workspace: memoryScope === 'workspace' ? (key ?? null) : null,
+      received: buildReceived(store, { memoryScope, key, goal, maxChars }),
+      written: buildWritten(store, { ledger, sessionId }),
+    }
+  }
+  return snapshot
+}

package/src/models.js

@@ -1,136 +1,136 @@
-// Model resolution for memory work: a fallback ladder over the models that are actually
-// routable RIGHT NOW.
-//
-// Memory work used to run on one model - the session's, or a configured override - and a model
-// that answers with no text block at all silently produced nothing. That was not hypothetical:
-// 7 of 11 consolidation passes returned an empty reply on one reasoning-heavy model, while the
-// next model wrote 35 entries from the same prompt and the same digests.
-//
-// The model list is deployment state, not a constant: providers come and go, a session switches
-// model mid-conversation, and a subscription can lapse. So the ladder is resolved at call time
-// from the live registry, and the winner is REMEMBERED so the normal case still costs one call.
-
-/** How many models one call may try before giving up. Bounds the cost of a bad deployment. */
-export const LADDER_MAX = 4
-
-/** A model that returned no text is benched for this long before being tried again. */
-export const BENCH_MS = 15 * 60 * 1000
-
-/** Stable identity for a (provider, model) pair. */
-export function modelKey(target) {
-  if (!target || !target.provider || !target.model) return ''
-  return target.provider + '/' + target.model
-}
-
-/**
- * Order the models to try, most preferred first.
- *
- * The configured memory model wins outright when set, because that is an explicit instruction.
- * The session's own model is next: it is already known to be routable for this user, and it
- * keeps memory consistent with the work being remembered. Everything else routable follows, so
- * a deployment with no configuration still has somewhere to fall back to.
- *
- * @param options.preferred - the configured memory model, if any.
- * @param options.session - the session's current route, if any.
- * @param options.available - every routable target, in registry order.
- * @returns a de-duplicated ladder, at most LADDER_MAX long.
- */
-export function buildModelLadder({ preferred, session, available } = {}) {
-  const ladder = []
-  const seen = new Set()
-  const push = (target) => {
-    const key = modelKey(target)
-    if (key === '' || seen.has(key)) return
-    seen.add(key)
-    ladder.push({ provider: target.provider, model: target.model })
-  }
-  push(preferred)
-  push(session)
-  for (const target of available ?? []) push(target)
-  return ladder.slice(0, LADDER_MAX)
-}
-
-/**
- * Track which model last worked, and which ones recently returned nothing.
- *
- * This is what keeps a ladder cheap. Without it every call would re-walk from the top; with it
- * the working model is tried first every time, and a model is only re-tried after its bench
- * expires, so a temporary outage costs a bounded number of calls rather than one per write.
- */
-export function createModelMemory({ now = () => Date.now(), benchMs = BENCH_MS } = {}) {
-  let winner
-  const benched = new Map()
-  return {
-    /** The model that last produced text, if any. */
-    preferred() { return winner },
-    /** Record that a model worked; it becomes the new first choice. */
-    succeeded(target) {
-      winner = { provider: target.provider, model: target.model }
-      benched.delete(modelKey(target))
-    },
-    /** Record that a model returned nothing usable. */
-    failed(target) {
-      benched.set(modelKey(target), now())
-      if (modelKey(winner) === modelKey(target)) winner = undefined
-    },
-    /** True when a model is still benched for returning nothing. */
-    isBenched(target, at = now()) {
-      const since = benched.get(modelKey(target))
-      if (since === undefined) return false
-      if (at - since >= benchMs) { benched.delete(modelKey(target)); return false }
-      return true
-    },
-    /** Benched models, for diagnostics. */
-    snapshot() { return { winner, benched: [...benched.keys()] } },
-  }
-}
-
-/**
- * Order a ladder for one call: previously-working model first, benched models last.
- * Benched models stay in the ladder - they are a last resort, not a permanent exclusion,
- * so a deployment where every model is benched still attempts something.
- */
-export function orderLadder(ladder, memory) {
-  if (!memory) return ladder
-  const winner = memory.preferred()
-  const rank = (target) => {
-    if (modelKey(target) === modelKey(winner)) return 0
-    return memory.isBenched(target) ? 2 : 1
-  }
-  return ladder.map((t, i) => ({ t, i })).sort((a, b) => (rank(a.t) - rank(b.t)) || (a.i - b.i)).map((x) => x.t)
-}
-
-/**
- * Run one prompt down the ladder until a model returns text.
- *
- * @param options.ladder - ordered targets.
- * @param options.attempt - (target) => Promise<string>; resolves to the reply text, '' for none.
- * @param options.memory - optional createModelMemory() to learn from the outcome.
- * @param options.onAttempt - (target, text) => void, for telemetry.
- * @returns { text, target, tried } - text is '' when every model returned nothing.
- */
-export async function runLadder({ ladder, attempt, memory, onAttempt } = {}) {
-  const ordered = orderLadder(ladder ?? [], memory)
-  const tried = []
-  for (const target of ordered) {
-    let text = ''
-    try {
-      text = String((await attempt(target)) ?? '')
-    } catch (error) {
-      // A model that throws is unavailable, not a verdict about the material: bench it and
-      // let the next rung try the SAME prompt.
-      tried.push({ target, error: String((error && error.message) || error).slice(0, 160) })
-      if (memory) memory.failed(target)
-      if (onAttempt) onAttempt(target, '', error)
-      continue
-    }
-    tried.push({ target, text: text.length })
-    if (onAttempt) onAttempt(target, text)
-    if (text.trim() !== '') {
-      if (memory) memory.succeeded(target)
-      return { text, target, tried }
-    }
-    if (memory) memory.failed(target)
-  }
-  return { text: '', target: undefined, tried }
-}
+// Model resolution for memory work: a fallback ladder over the models that are actually
+// routable RIGHT NOW.
+//
+// Memory work used to run on one model - the session's, or a configured override - and a model
+// that answers with no text block at all silently produced nothing. That was not hypothetical:
+// 7 of 11 consolidation passes returned an empty reply on one reasoning-heavy model, while the
+// next model wrote 35 entries from the same prompt and the same digests.
+//
+// The model list is deployment state, not a constant: providers come and go, a session switches
+// model mid-conversation, and a subscription can lapse. So the ladder is resolved at call time
+// from the live registry, and the winner is REMEMBERED so the normal case still costs one call.
+
+/** How many models one call may try before giving up. Bounds the cost of a bad deployment. */
+export const LADDER_MAX = 4
+
+/** A model that returned no text is benched for this long before being tried again. */
+export const BENCH_MS = 15 * 60 * 1000
+
+/** Stable identity for a (provider, model) pair. */
+export function modelKey(target) {
+  if (!target || !target.provider || !target.model) return ''
+  return target.provider + '/' + target.model
+}
+
+/**
+ * Order the models to try, most preferred first.
+ *
+ * The configured memory model wins outright when set, because that is an explicit instruction.
+ * The session's own model is next: it is already known to be routable for this user, and it
+ * keeps memory consistent with the work being remembered. Everything else routable follows, so
+ * a deployment with no configuration still has somewhere to fall back to.
+ *
+ * @param options.preferred - the configured memory model, if any.
+ * @param options.session - the session's current route, if any.
+ * @param options.available - every routable target, in registry order.
+ * @returns a de-duplicated ladder, at most LADDER_MAX long.
+ */
+export function buildModelLadder({ preferred, session, available } = {}) {
+  const ladder = []
+  const seen = new Set()
+  const push = (target) => {
+    const key = modelKey(target)
+    if (key === '' || seen.has(key)) return
+    seen.add(key)
+    ladder.push({ provider: target.provider, model: target.model })
+  }
+  push(preferred)
+  push(session)
+  for (const target of available ?? []) push(target)
+  return ladder.slice(0, LADDER_MAX)
+}
+
+/**
+ * Track which model last worked, and which ones recently returned nothing.
+ *
+ * This is what keeps a ladder cheap. Without it every call would re-walk from the top; with it
+ * the working model is tried first every time, and a model is only re-tried after its bench
+ * expires, so a temporary outage costs a bounded number of calls rather than one per write.
+ */
+export function createModelMemory({ now = () => Date.now(), benchMs = BENCH_MS } = {}) {
+  let winner
+  const benched = new Map()
+  return {
+    /** The model that last produced text, if any. */
+    preferred() { return winner },
+    /** Record that a model worked; it becomes the new first choice. */
+    succeeded(target) {
+      winner = { provider: target.provider, model: target.model }
+      benched.delete(modelKey(target))
+    },
+    /** Record that a model returned nothing usable. */
+    failed(target) {
+      benched.set(modelKey(target), now())
+      if (modelKey(winner) === modelKey(target)) winner = undefined
+    },
+    /** True when a model is still benched for returning nothing. */
+    isBenched(target, at = now()) {
+      const since = benched.get(modelKey(target))
+      if (since === undefined) return false
+      if (at - since >= benchMs) { benched.delete(modelKey(target)); return false }
+      return true
+    },
+    /** Benched models, for diagnostics. */
+    snapshot() { return { winner, benched: [...benched.keys()] } },
+  }
+}
+
+/**
+ * Order a ladder for one call: previously-working model first, benched models last.
+ * Benched models stay in the ladder - they are a last resort, not a permanent exclusion,
+ * so a deployment where every model is benched still attempts something.
+ */
+export function orderLadder(ladder, memory) {
+  if (!memory) return ladder
+  const winner = memory.preferred()
+  const rank = (target) => {
+    if (modelKey(target) === modelKey(winner)) return 0
+    return memory.isBenched(target) ? 2 : 1
+  }
+  return ladder.map((t, i) => ({ t, i })).sort((a, b) => (rank(a.t) - rank(b.t)) || (a.i - b.i)).map((x) => x.t)
+}
+
+/**
+ * Run one prompt down the ladder until a model returns text.
+ *
+ * @param options.ladder - ordered targets.
+ * @param options.attempt - (target) => Promise<string>; resolves to the reply text, '' for none.
+ * @param options.memory - optional createModelMemory() to learn from the outcome.
+ * @param options.onAttempt - (target, text) => void, for telemetry.
+ * @returns { text, target, tried } - text is '' when every model returned nothing.
+ */
+export async function runLadder({ ladder, attempt, memory, onAttempt } = {}) {
+  const ordered = orderLadder(ladder ?? [], memory)
+  const tried = []
+  for (const target of ordered) {
+    let text = ''
+    try {
+      text = String((await attempt(target)) ?? '')
+    } catch (error) {
+      // A model that throws is unavailable, not a verdict about the material: bench it and
+      // let the next rung try the SAME prompt.
+      tried.push({ target, error: String((error && error.message) || error).slice(0, 160) })
+      if (memory) memory.failed(target)
+      if (onAttempt) onAttempt(target, '', error)
+      continue
+    }
+    tried.push({ target, text: text.length })
+    if (onAttempt) onAttempt(target, text)
+    if (text.trim() !== '') {
+      if (memory) memory.succeeded(target)
+      return { text, target, tried }
+    }
+    if (memory) memory.failed(target)
+  }
+  return { text: '', target: undefined, tried }
+}