@codebam/dsh-thinking-auditor 0.1.0

package/src/state.mjs

@@ -0,0 +1,131 @@
+/**
+ * Per-session audit state: the bounded reasoning window, trigger bookkeeping,
+ * trailing verdict history, and once-per-turn actuator latches.
+ *
+ * Pure data structure, so trigger/dedupe behavior is testable without a model.
+ *
+ * @module @codebam/dsh-thinking-auditor/state
+ */
+
+/**
+ * One session's live audit state.
+ *
+ * The reasoning window is a tail-bounded string: auditing takes the most recent
+ * `maxTraceChars` characters and clears the window, so memory cannot grow with a
+ * long autonomous turn and each window is audited exactly once.
+ */
+export class SessionAuditState {
+  constructor(options = {}) {
+    this.sessionId = String(options.sessionId ?? '')
+    this.maxTraceChars = options.maxTraceChars ?? 12000
+    /** Unaudited reasoning text. */
+    this.pending = ''
+    /** Total reasoning characters observed this session. */
+    this.reasoningChars = 0
+    /** Current turn/step context. */
+    this.turn = options.turn ?? 0
+    this.step = options.step ?? 0
+    /** Background audits started this turn. */
+    this.auditsThisTurn = 0
+    /** Session-time of the last accepted audit start. */
+    this.lastAuditAt = 0
+    /** In-flight audit promise, or undefined. */
+    this.inFlight = undefined
+    /** Set when an audit was requested while one was in flight. */
+    this.rerunRequested = false
+    /** Consecutive verdict history for hysteresis. */
+    this.history = []
+    /** Turns already given a T1 verification steer. */
+    this.verifiedTurns = new Set()
+    /** Turns already cancelled by T3. */
+    this.cancelledTurns = new Set()
+    /** Latest committed verdict record. */
+    this.lastVerdict = undefined
+    /** True once the session was disposed. */
+    this.disposed = false
+  }
+
+  /** Append reasoning text and return the new pending length. */
+  appendReasoning(text, { turn, step } = {}) {
+    if (typeof text !== 'string' || text.length === 0) return this.pending.length
+    if (turn !== undefined) this.turn = turn
+    if (step !== undefined) this.step = step
+    this.pending += text
+    this.reasoningChars += text.length
+    const bound = this.maxTraceChars * 2
+    if (this.pending.length > bound) this.pending = this.pending.slice(-bound)
+    return this.pending.length
+  }
+
+  /** Reset per-turn triggers and hysteresis on a fresh user turn. */
+  startTurn(turn) {
+    this.turn = turn ?? this.turn + 1
+    this.auditsThisTurn = 0
+    this.history = []
+    // Keep latches bounded across very long sessions.
+    for (const recorded of [...this.verifiedTurns]) if (recorded < this.turn - 50) this.verifiedTurns.delete(recorded)
+    for (const recorded of [...this.cancelledTurns]) if (recorded < this.turn - 50) this.cancelledTurns.delete(recorded)
+  }
+
+  /** True when enough unaudited reasoning is pending for an opportunistic trigger. */
+  hasPending(minChars) {
+    return this.pending.length >= minChars
+  }
+
+  /** True when an audit window should start at this moment. */
+  shouldSchedule({ windowChars, cooldownMs, now = Date.now() }) {
+    if (this.inFlight !== undefined) return false
+    if (this.pending.length >= windowChars) return true
+    return this.pending.length > 0 && now - this.lastAuditAt >= cooldownMs
+  }
+
+  /** Take the audit window, clearing it. Keeps only the most recent cap. */
+  takeWindow(maxChars = this.maxTraceChars) {
+    const text = this.pending.length <= maxChars ? this.pending : this.pending.slice(-maxChars)
+    this.pending = ''
+    return { text, turn: this.turn, step: this.step, chars: text.length }
+  }
+
+  /** Record an accepted audit start. */
+  markAuditStarted(now = Date.now()) {
+    this.lastAuditAt = now
+    this.auditsThisTurn += 1
+  }
+
+  /** True when another audit may start this turn. */
+  canAuditThisTurn(max) {
+    return this.auditsThisTurn < max
+  }
+
+  /** True when this turn already received its T1 steer. */
+  wasVerified(turn = this.turn) {
+    return this.verifiedTurns.has(turn)
+  }
+
+  /** Latch T1 for a turn. */
+  latchVerified(turn = this.turn) {
+    this.verifiedTurns.add(turn)
+  }
+
+  /** True when this turn already received its T3 cancel. */
+  wasCancelled(turn = this.turn) {
+    return this.cancelledTurns.has(turn)
+  }
+
+  /** Latch T3 for a turn. */
+  latchCancelled(turn = this.turn) {
+    this.cancelledTurns.add(turn)
+  }
+
+  /** Append a verdict to bounded hysteresis history. */
+  pushHistory(record, cap = 12) {
+    this.history.push({
+      level: record.level,
+      at: record.at,
+      confirmedFabrication: record.confirmedFabrication,
+      id: record.id,
+    })
+    while (this.history.length > cap) this.history.shift()
+    return this.history
+  }
+}

package/src/store.mjs

@@ -0,0 +1,185 @@
+/**
+ * Audit record store and verdict/action notification hub.
+ *
+ * Records live in their own bounded in-memory store, separate from the session
+ * log: the session format deliberately treats unknown event types as required
+ * unless persisted with an `ignorable` envelope marker, and this plugin never
+ * writes to the session log. An optional JSONL sink makes verdicts durable
+ * without touching session compatibility.
+ *
+ * Pure module except for the sink callback the caller supplies.
+ *
+ * @module @codebam/dsh-thinking-auditor/store
+ */
+
+let sequence = 0
+
+/** Deep-freeze a plain record. */
+function freeze(value) {
+  if (value === null || typeof value !== 'object' || Object.isFrozen(value)) return value
+  for (const nested of Object.values(value)) freeze(nested)
+  return Object.freeze(value)
+}
+
+/** Detach one record from the store's frozen value. */
+function detach(record) {
+  return record === undefined ? undefined : structuredClone(record)
+}
+
+/** One session's bounded record window. */
+class SessionRecords {
+  constructor(maxRecords) {
+    this.maxRecords = maxRecords
+    /** @type {object[]} */
+    this.verdicts = []
+    /** @type {object[]} */
+    this.actions = []
+  }
+
+  push(list, record) {
+    list.push(record)
+    while (list.length > this.maxRecords) list.shift()
+  }
+}
+
+/**
+ * Bounded audit store.
+ *
+ * `record(verdict)` and `recordAction(action)` return frozen records and fan
+ * them out to subscribers. Sink failures are contained; they never affect the
+ * audit path or the monitored model.
+ */
+export class AuditStore {
+  constructor(options = {}) {
+    this.maxSessions = options.maxSessions ?? 200
+    this.maxRecordsPerSession = options.maxRecordsPerSession ?? 200
+    /** @type {Map<string, SessionRecords>} */
+    this.sessions = new Map()
+    /** @type {Set<Function>} */
+    this.subscribers = new Set()
+    /** @type {Function[]} */
+    this.sinks = []
+    /** @type {string|undefined} */
+    this.lastSinkError = undefined
+  }
+
+  /** True when no audit has been recorded. */
+  get isEmpty() {
+    return this.sessions.size === 0
+  }
+
+  /** Add a durable sink invoked after every record. */
+  addSink(sink) {
+    if (typeof sink !== 'function') throw new TypeError('thinking-auditor: store sink must be a function')
+    this.sinks.push(sink)
+    return () => {
+      const index = this.sinks.indexOf(sink)
+      if (index !== -1) this.sinks.splice(index, 1)
+    }
+  }
+
+  /** Subscribe to committed records. */
+  subscribe(callback) {
+    if (typeof callback !== 'function') throw new TypeError('thinking-auditor: store subscriber must be a function')
+    this.subscribers.add(callback)
+    return () => this.subscribers.delete(callback)
+  }
+
+  /** Get or create one session's record window with bounded session count. */
+  #session(sessionId) {
+    const key = String(sessionId)
+    let records = this.sessions.get(key)
+    if (records === undefined) {
+      while (this.sessions.size >= this.maxSessions) {
+        const oldest = this.sessions.keys().next().value
+        this.sessions.delete(oldest)
+      }
+      records = new SessionRecords(this.maxRecordsPerSession)
+      this.sessions.set(key, records)
+    }
+    return records
+  }
+
+  /** Commit one verdict record. */
+  record(verdict) {
+    const stored = freeze({
+      ...verdict,
+      id: verdict.id ?? `verdict-${++sequence}`,
+      at: verdict.at ?? Date.now(),
+    })
+    const records = this.#session(stored.sessionId)
+    records.push(records.verdicts, stored)
+    this.#publish({ kind: 'verdict', record: stored })
+    return stored
+  }
+
+  /** Commit one actuator action for a verdict. */
+  recordAction(action) {
+    const stored = freeze({
+      ...action,
+      id: action.id ?? `action-${++sequence}`,
+      at: action.at ?? Date.now(),
+    })
+    const records = this.#session(stored.sessionId)
+    records.push(records.actions, stored)
+    this.#publish({ kind: 'action', record: stored })
+    return stored
+  }
+
+  /** Fan a record out to subscribers and sinks, containing every failure. */
+  #publish(event) {
+    for (const subscriber of this.subscribers) {
+      try {
+        subscriber(event)
+      } catch {
+        // Observer failures are contained: auditing must never break a session.
+      }
+    }
+    for (const sink of this.sinks) {
+      try {
+        const result = sink(event.record)
+        if (result !== undefined && typeof result.then === 'function') {
+          result.catch((error) => {
+            this.lastSinkError = error?.message ?? String(error)
+          })
+        }
+      } catch (error) {
+        this.lastSinkError = error?.message ?? String(error)
+      }
+    }
+  }
+
+  /** Detached verdicts for one session, oldest first. */
+  verdicts(sessionId, limit) {
+    const records = this.sessions.get(String(sessionId))
+    const list = records?.verdicts ?? []
+    const selected = limit === undefined ? list : list.slice(-limit)
+    return selected.map(detach)
+  }
+
+  /** Detached actions for one session, oldest first. */
+  actions(sessionId, limit) {
+    const records = this.sessions.get(String(sessionId))
+    const list = records?.actions ?? []
+    const selected = limit === undefined ? list : list.slice(-limit)
+    return selected.map(detach)
+  }
+
+  /** Latest verdict for one session, or undefined. */
+  latest(sessionId) {
+    const records = this.sessions.get(String(sessionId))
+    return detach(records?.verdicts[records.verdicts.length - 1])
+  }
+
+  /** Number of sessions currently retained. */
+  get size() {
+    return this.sessions.size
+  }
+
+  /** Total verdict records currently retained. */
+  get verdictCount() {
+    let total = 0
+    for (const records of this.sessions.values()) total += records.verdicts.length
+    return total
+  }
+}