oracular 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.2.0
+
+### Minor Changes
+
+- [#8](https://github.com/Yuribenjamin/oracular/pull/8) [`72c5f3c`](https://github.com/Yuribenjamin/oracular/commit/72c5f3c296c80ed99f8def26cdb120cdbfc239b3) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - Learning compares a signal's outcome rate against sessions without the signal, and only trusts the comparison once both have been seen. Weights no longer drift after a single outcome.
+
+## 0.1.2
+
+### Patch Changes
+
+- [#6](https://github.com/Yuribenjamin/oracular/pull/6) [`57d121f`](https://github.com/Yuribenjamin/oracular/commit/57d121f107f4ed92f2e59bf354cc6e19f705de1b) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - Docs corrections from the first production integration; new evaluate(), evidenceToReveal(), episodeClosed() and explain() filtering; default export condition.
+
 ## 0.1.1
 
 ### Patch Changes

package/README.md

@@ -97,14 +97,17 @@ Events happen inside **episodes** (sessions). An episode ends when you call `end
 A signal's weight is then a blend of your prior and the learned estimate:
 
 ```
-q        = (hits + 1) / (hits + misses + 2)          Laplace-smoothed hit rate
-b        = (outcomes + 1) / (episodes + 2)           Laplace-smoothed base rate
-lift     = (q − b) / (1 − b)  if q ≥ b,  else  (q − b) / b     → in [−1, 1]
-learned  = gain × |w₀| × lift                        0 until the signal has history
-effective = (k × w₀ + n × learned) / (k + n)         n = hits + misses, k = priorEpisodes
+nWith    = hits + misses                                      episodes with the signal
+nWithout = episodes − nWith                                   episodes without it
+qWith    = (hits + 1) / (nWith + 2)                           outcome rate with the signal
+qWithout = (outcomes − hits + 1) / (nWithout + 2)             outcome rate without it
+lift     = (qWith − qWithout) / (1 − qWithout)  if qWith ≥ qWithout,  else  (qWith − qWithout) / qWithout   → in [−1, 1]
+learned  = gain × |w₀| × lift                                 0 until the signal has history
+nEff     = (nWith × nWithout) / (nWith + nWithout)            0 if either side is 0
+effective = (k × w₀ + nEff × learned) / (k + nEff)            k = priorEpisodes
 ```
 
-`w₀` is your initial weight, `gain` (default 2) caps how far a perfectly predictive signal can grow, and `priorEpisodes` (default 10) is how many completed episodes it takes for the user's own history to count as much as your guess. A signal's strength and your confidence in it are separate knobs. Centering on the base rate matters: for an outcome that happens in 3% of sessions, a signal followed by it 30% of the time is strong evidence, not weak.
+`w₀` is your initial weight, `gain` (default 2) caps how far a perfectly predictive signal can grow, and `priorEpisodes` (default 10) is how much contrast it takes for the user's own history to count as much as your guess. A signal's strength and your confidence in it are separate knobs. A signal is judged against the sessions in which it did *not* appear, so for an outcome that happens in 3% of sessions, a signal followed by it 30% of the time is strong evidence, not weak. And learning needs contrast: a signal that has never been absent has no counterfactual, so its weight stands until there are sessions without it. Nothing drifts after a single outcome.
 
 Learned counts never decay unless you set `learning.halfLife`.
 
@@ -223,7 +226,10 @@ endEpisode(state, at: number): EngineState
 predict(state, intent: string, at: number, opts?: RevealOptions): Prediction
 shouldReveal(state, intent: string, at: number, opts?: RevealOptions): boolean
 markRevealed(state, intent: string, at: number): EngineState
-explain(state, intent: string, at: number): SignalExplanation[]
+explain(state, intent: string, at: number, opts?: { nonZero?: boolean; limit?: number }): SignalExplanation[]
+evaluate(state, intent: string, at: number, opts?): { prediction, reveal, explanation }  // all three, one decay pass
+evidenceToReveal(intentConfig, opts?): number   // pseudo-counts at which shouldReveal first becomes true
+episodeClosed(prev, next): boolean               // did an episode close between two states?
 serialize(state): string
 deserialize(json: string, opts?: { config?: EngineConfig; migrate?: Migrate }): EngineState
 STATE_VERSION // 1
@@ -327,13 +333,13 @@ After ten sessions in which `pricing.viewed` led to an upgrade six times out of
 ```ts
 explain(state, 'upgrade', Date.now());
 // [
-//   { signal: 'pricing.viewed', contribution: 2.58, impact: 0.14, initialWeight: 3, learnedWeight: 2, effectiveWeight: 2.59, hits: 6, misses: 1 },
-//   { signal: 'limit.hit',      contribution: 2,    impact: 0.10, initialWeight: 2, learnedWeight: 0, effectiveWeight: 2,    hits: 0, misses: 0 },
-//   { signal: 'export.clicked', contribution: 0,    impact: 0,    initialWeight: 1, learnedWeight: 0, effectiveWeight: 0.5,  hits: 7, misses: 3 },
+//   { signal: 'pricing.viewed', contribution: 3.12, impact: 0.16, initialWeight: 3, learnedWeight: 3.78, effectiveWeight: 3.13, hits: 6, misses: 1 },
+//   { signal: 'limit.hit',      contribution: 2,    impact: 0.10, initialWeight: 2, learnedWeight: 0,    effectiveWeight: 2,    hits: 0, misses: 0 },
+//   { signal: 'export.clicked', contribution: 0,    impact: 0,    initialWeight: 1, learnedWeight: 0.67, effectiveWeight: 1,    hits: 7, misses: 3 },
 // ]
 ```
 
-Rows are sorted by the size of their impact. `limit.hit` has no history yet, so its effective weight is exactly the initial one. `export.clicked` was followed by an upgrade exactly as often as any session was (7 of 10, the base rate), so this user's history says it carries no information, and its weight is on its way to zero. `pricing.viewed` beat the base rate, so it learned a positive weight; the blend is still below the initial 3 only because the developer's guess was higher than what seven episodes support so far.
+Rows are sorted by the size of their impact. `limit.hit` has no history yet, so its effective weight is exactly the initial one. `pricing.viewed` was followed by an upgrade in six of its seven sessions while the three sessions without it saw one upgrade, so it learned a weight above the initial 3. `export.clicked` appeared in every session: it has no counterfactual, so whatever its hit rate, its weight stands at exactly the initial 1 until a session happens without it. See [Episodes & learning](https://yuribenjamin.github.io/oracular/guide/concepts/episodes-and-learning) for why learning needs contrast.
 
 ## Design rules
 

package/dist/index.cjs

@@ -1,5 +1,33 @@
 'use strict';
 
+// src/math.ts
+function decayFactor(elapsed, halfLife) {
+  if (!(elapsed > 0) || !Number.isFinite(elapsed)) return 1;
+  return 2 ** (-elapsed / halfLife);
+}
+function betaMean(alpha, beta) {
+  return alpha / (alpha + beta);
+}
+function betaVariance(alpha, beta) {
+  const n = alpha + beta;
+  return alpha * beta / (n * n * (n + 1));
+}
+function betaSd(alpha, beta) {
+  return Math.sqrt(betaVariance(alpha, beta));
+}
+function clamp01(x) {
+  if (x < 0) return 0;
+  if (x > 1) return 1;
+  return x;
+}
+function laplace(successes, total) {
+  return (successes + 1) / (total + 2);
+}
+function lift(q, b) {
+  if (q >= b) return b >= 1 ? 0 : (q - b) / (1 - b);
+  return b <= 0 ? 0 : (q - b) / b;
+}
+
 // src/util.ts
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -18,6 +46,100 @@ function mapRecord(record2, fn) {
   return out;
 }
 
+// src/intent.ts
+function priorCounts(intent) {
+  return {
+    alpha0: intent.prior * intent.priorStrength,
+    beta0: (1 - intent.prior) * intent.priorStrength
+  };
+}
+function initIntent(intent) {
+  const { alpha0, beta0 } = priorCounts(intent);
+  return {
+    alpha: alpha0,
+    beta: beta0,
+    updatedAt: null,
+    contributions: {},
+    learned: {},
+    episodes: { hits: 0, misses: 0 },
+    learnedAt: null,
+    lastRevealedAt: null,
+    lastOutcomeAt: null,
+    revealCount: 0
+  };
+}
+function withContributions(state, intent, contributions) {
+  const { alpha0, beta0 } = priorCounts(intent);
+  let alpha = alpha0;
+  let beta = beta0;
+  for (const c of Object.values(contributions)) {
+    alpha += c.alpha;
+    beta += c.beta;
+  }
+  return { ...state, alpha, beta, contributions };
+}
+function decayIntent(state, intent, at) {
+  if (state.updatedAt === null) return { ...state, updatedAt: at };
+  const d = decayFactor(at - state.updatedAt, intent.halfLife);
+  const updatedAt = Math.max(state.updatedAt, at);
+  if (d === 1) return updatedAt === state.updatedAt ? state : { ...state, updatedAt };
+  const contributions = mapRecord(state.contributions, (c) => ({
+    alpha: c.alpha * d,
+    beta: c.beta * d
+  }));
+  return withContributions({ ...state, updatedAt }, intent, contributions);
+}
+function applySignal(state, intent, signal, weight) {
+  const prev = getOwn(state.contributions, signal) ?? { alpha: 0, beta: 0 };
+  const next = weight >= 0 ? { alpha: prev.alpha + weight, beta: prev.beta } : { alpha: prev.alpha, beta: prev.beta - weight };
+  return withContributions(state, intent, { ...state.contributions, [signal]: next });
+}
+function resetToPrior(state, intent) {
+  return withContributions(state, intent, {});
+}
+
+// src/learning.ts
+var NONE = { hits: 0, misses: 0 };
+function decayLearned(state, learning, at) {
+  if (state.learnedAt === null) return { ...state, learnedAt: at };
+  const learnedAt = Math.max(state.learnedAt, at);
+  const d = learning.halfLife === null ? 1 : decayFactor(at - state.learnedAt, learning.halfLife);
+  if (d === 1) return learnedAt === state.learnedAt ? state : { ...state, learnedAt };
+  return {
+    ...state,
+    learnedAt,
+    learned: mapRecord(state.learned, (r) => ({ hits: r.hits * d, misses: r.misses * d })),
+    episodes: { hits: state.episodes.hits * d, misses: state.episodes.misses * d }
+  };
+}
+function signalWeights(state, intent, learning, signal) {
+  const initial = getOwn(intent.signals, signal);
+  if (initial === void 0) {
+    throw new RangeError(`oracular: ${JSON.stringify(signal)} is not a signal of this intent`);
+  }
+  const record2 = getOwn(state.learned, signal) ?? NONE;
+  const nWith = record2.hits + record2.misses;
+  const qWith = laplace(record2.hits, nWith);
+  const totalEpisodes = state.episodes.hits + state.episodes.misses;
+  const nWithout = Math.max(0, totalEpisodes - nWith);
+  const outcomesWithout = Math.min(nWithout, Math.max(0, state.episodes.hits - record2.hits));
+  const qWithout = laplace(outcomesWithout, nWithout);
+  const learned = nWith === 0 ? 0 : learning.gain * Math.abs(initial) * lift(qWith, qWithout);
+  const nEff = nWith + nWithout === 0 ? 0 : nWith * nWithout / (nWith + nWithout);
+  const k = learning.priorEpisodes;
+  const effective = (k * initial + nEff * learned) / (k + nEff);
+  return { initial, learned, effective, hits: record2.hits, misses: record2.misses };
+}
+function recordEpisode(state, signals, outcome) {
+  const learned = { ...state.learned };
+  for (const signal of signals) {
+    const r = getOwn(learned, signal) ?? NONE;
+    learned[signal] = outcome ? { hits: r.hits + 1, misses: r.misses } : { hits: r.hits, misses: r.misses + 1 };
+  }
+  const episodes = outcome ? { hits: state.episodes.hits + 1, misses: state.episodes.misses } : { hits: state.episodes.hits, misses: state.episodes.misses + 1 };
+  return { ...state, learned, episodes };
+}
+
 // src/config.ts
 var DEFAULT_THRESHOLD = 0.5;
 var DEFAULT_Z = 1.28;
@@ -35,6 +157,7 @@ var INTENT_KEYS = [
 ];
 var REVEAL_KEYS = ["threshold", "z", "cooldown"];
 var LEARNING_KEYS = ["halfLife", "gain", "priorEpisodes"];
+var EXPLAIN_KEYS = ["nonZero", "limit"];
 function typeError(path, message) {
   throw new TypeError(`oracular: ${path} ${message}`);
 }
@@ -115,7 +238,7 @@ function normalizeLearning(value, path) {
   }
   return out;
 }
-function normalizeIntent(value, path) {
+function normalizeIntentConfig(value, path) {
   const record2 = expectRecord(value, path);
   expectKeys(record2, INTENT_KEYS, path);
   const signalsRecord = expectRecord(record2.signals, `${path}.signals`);
@@ -157,7 +280,10 @@ function normalizeConfig(value) {
   const intents = {};
   for (const name of names) {
     expectKeyName(name, "config.intents");
-    intents[name] = normalizeIntent(intentsRecord[name], `config.intents[${JSON.stringify(name)}]`);
+    intents[name] = normalizeIntentConfig(
+      intentsRecord[name],
+      `config.intents[${JSON.stringify(name)}]`
+    );
   }
   const out = { intents };
   if (record2.episodeTimeout !== void 0) {
@@ -169,12 +295,43 @@ function normalizeConfig(value) {
     out.reveal = normalizeRevealOptions(record2.reveal, "config.reveal");
   return out;
 }
-function resolveReveal(config, intent, opts) {
-  const o = opts === void 0 ? {} : normalizeRevealOptions(opts, "options");
+function normalizeExplainOptions(value, path) {
+  const record2 = expectRecord(value, path);
+  expectKeys(record2, EXPLAIN_KEYS, path);
+  const out = {};
+  if (record2.nonZero !== void 0) {
+    if (typeof record2.nonZero !== "boolean") typeError(`${path}.nonZero`, "must be a boolean");
+    out.nonZero = record2.nonZero;
+  }
+  if (record2.limit !== void 0) {
+    const n = expectNumber(record2.limit, `${path}.limit`);
+    if (!Number.isInteger(n) || n < 0)
+      rangeError(`${path}.limit`, "must be a non-negative integer");
+    out.limit = n;
+  }
+  return out;
+}
+function splitEvaluateOptions(value, path) {
+  if (value === void 0) return { reveal: {}, explain: {} };
+  const record2 = expectRecord(value, path);
+  expectKeys(record2, [...REVEAL_KEYS, ...EXPLAIN_KEYS], path);
+  const reveal = {};
+  const explain2 = {};
+  for (const [key, v] of Object.entries(record2)) {
+    if (REVEAL_KEYS.includes(key)) reveal[key] = v;
+    else explain2[key] = v;
+  }
+  return {
+    reveal: normalizeRevealOptions(reveal, path),
+    explain: normalizeExplainOptions(explain2, path)
+  };
+}
+function resolveReveal(config, intent, opts, normalized = false) {
+  const o = opts === void 0 ? {} : normalized ? opts : normalizeRevealOptions(opts, "options");
   return {
-    threshold: o.threshold ?? intent.reveal?.threshold ?? config.reveal?.threshold ?? DEFAULT_THRESHOLD,
-    z: o.z ?? intent.reveal?.z ?? config.reveal?.z ?? DEFAULT_Z,
-    cooldown: o.cooldown ?? intent.reveal?.cooldown ?? config.reveal?.cooldown ?? intent.halfLife
+    threshold: o.threshold ?? intent.reveal?.threshold ?? config?.reveal?.threshold ?? DEFAULT_THRESHOLD,
+    z: o.z ?? intent.reveal?.z ?? config?.reveal?.z ?? DEFAULT_Z,
+    cooldown: o.cooldown ?? intent.reveal?.cooldown ?? config?.reveal?.cooldown ?? intent.halfLife
   };
 }
 function resolveLearning(config) {
@@ -197,124 +354,6 @@ function validateEvent(event) {
   return { name, at };
 }
 
-// src/math.ts
-function decayFactor(elapsed, halfLife) {
-  if (!(elapsed > 0) || !Number.isFinite(elapsed)) return 1;
-  return 2 ** (-elapsed / halfLife);
-}
-function betaMean(alpha, beta) {
-  return alpha / (alpha + beta);
-}
-function betaVariance(alpha, beta) {
-  const n = alpha + beta;
-  return alpha * beta / (n * n * (n + 1));
-}
-function betaSd(alpha, beta) {
-  return Math.sqrt(betaVariance(alpha, beta));
-}
-function clamp01(x) {
-  if (x < 0) return 0;
-  if (x > 1) return 1;
-  return x;
-}
-function laplace(successes, total) {
-  return (successes + 1) / (total + 2);
-}
-function lift(q, b) {
-  if (q >= b) return b >= 1 ? 0 : (q - b) / (1 - b);
-  return b <= 0 ? 0 : (q - b) / b;
-}
-
-// src/intent.ts
-function priorCounts(intent) {
-  return {
-    alpha0: intent.prior * intent.priorStrength,
-    beta0: (1 - intent.prior) * intent.priorStrength
-  };
-}
-function initIntent(intent) {
-  const { alpha0, beta0 } = priorCounts(intent);
-  return {
-    alpha: alpha0,
-    beta: beta0,
-    updatedAt: null,
-    contributions: {},
-    learned: {},
-    episodes: { hits: 0, misses: 0 },
-    learnedAt: null,
-    lastRevealedAt: null,
-    lastOutcomeAt: null,
-    revealCount: 0
-  };
-}
-function withContributions(state, intent, contributions) {
-  const { alpha0, beta0 } = priorCounts(intent);
-  let alpha = alpha0;
-  let beta = beta0;
-  for (const c of Object.values(contributions)) {
-    alpha += c.alpha;
-    beta += c.beta;
-  }
-  return { ...state, alpha, beta, contributions };
-}
-function decayIntent(state, intent, at) {
-  if (state.updatedAt === null) return { ...state, updatedAt: at };
-  const d = decayFactor(at - state.updatedAt, intent.halfLife);
-  const updatedAt = Math.max(state.updatedAt, at);
-  if (d === 1) return updatedAt === state.updatedAt ? state : { ...state, updatedAt };
-  const contributions = mapRecord(state.contributions, (c) => ({
-    alpha: c.alpha * d,
-    beta: c.beta * d
-  }));
-  return withContributions({ ...state, updatedAt }, intent, contributions);
-}
-function applySignal(state, intent, signal, weight) {
-  const prev = getOwn(state.contributions, signal) ?? { alpha: 0, beta: 0 };
-  const next = weight >= 0 ? { alpha: prev.alpha + weight, beta: prev.beta } : { alpha: prev.alpha, beta: prev.beta - weight };
-  return withContributions(state, intent, { ...state.contributions, [signal]: next });
-}
-function resetToPrior(state, intent) {
-  return withContributions(state, intent, {});
-}
-
-// src/learning.ts
-var NONE = { hits: 0, misses: 0 };
-function decayLearned(state, learning, at) {
-  if (state.learnedAt === null) return { ...state, learnedAt: at };
-  const learnedAt = Math.max(state.learnedAt, at);
-  const d = learning.halfLife === null ? 1 : decayFactor(at - state.learnedAt, learning.halfLife);
-  if (d === 1) return learnedAt === state.learnedAt ? state : { ...state, learnedAt };
-  return {
-    ...state,
-    learnedAt,
-    learned: mapRecord(state.learned, (r) => ({ hits: r.hits * d, misses: r.misses * d })),
-    episodes: { hits: state.episodes.hits * d, misses: state.episodes.misses * d }
-  };
-}
-function signalWeights(state, intent, learning, signal) {
-  const initial = getOwn(intent.signals, signal);
-  if (initial === void 0) {
-    throw new RangeError(`oracular: ${JSON.stringify(signal)} is not a signal of this intent`);
-  }
-  const record2 = getOwn(state.learned, signal) ?? NONE;
-  const n = record2.hits + record2.misses;
-  const q = laplace(record2.hits, n);
-  const b = laplace(state.episodes.hits, state.episodes.hits + state.episodes.misses);
-  const learned = n === 0 ? 0 : learning.gain * Math.abs(initial) * lift(q, b);
-  const k = learning.priorEpisodes;
-  const effective = (k * initial + n * learned) / (k + n);
-  return { initial, learned, effective, hits: record2.hits, misses: record2.misses };
-}
-function recordEpisode(state, signals, outcome) {
-  const learned = { ...state.learned };
-  for (const signal of signals) {
-    const r = getOwn(learned, signal) ?? NONE;
-    learned[signal] = outcome ? { hits: r.hits + 1, misses: r.misses } : { hits: r.hits, misses: r.misses + 1 };
-  }
-  const episodes = outcome ? { hits: state.episodes.hits + 1, misses: state.episodes.misses } : { hits: state.episodes.hits, misses: state.episodes.misses + 1 };
-  return { ...state, learned, episodes };
-}
-
 // src/episode.ts
 function emptyEpisode() {
   return { startedAt: null, lastEventAt: null, intents: {} };
@@ -374,20 +413,42 @@ function getIntentState(state, name, intent) {
   return getOwn(state.intents, name) ?? initIntent(intent);
 }
 
-// src/explain.ts
-function explain(state, intent, at) {
-  const s = requireState(state);
-  const name = expectName(intent, "intent");
-  const t = expectTimestamp(at, "at");
-  const config = requireIntentConfig(s, name);
-  const learning = resolveLearning(s.config);
-  let is = decayIntent(getIntentState(s, name, config), config, t);
-  is = decayLearned(is, learning, t);
+// src/assess.ts
+function assessIntent(state, name, intent, learning, at) {
+  return decayLearned(decayIntent(getIntentState(state, name, intent), intent, at), learning, at);
+}
+function cooldownEnd(since, cooldown, at) {
+  if (since === null) return null;
+  const end = since + cooldown;
+  return at < end ? end : null;
+}
+function buildPrediction(is, name, reveal, at) {
+  const p = betaMean(is.alpha, is.beta);
+  const sd = betaSd(is.alpha, is.beta);
+  const revealEnd = cooldownEnd(is.lastRevealedAt, reveal.cooldown, at);
+  const outcomeEnd = cooldownEnd(is.lastOutcomeAt, reveal.cooldown, at);
+  const suppressedUntil = revealEnd === null ? outcomeEnd : outcomeEnd === null ? revealEnd : Math.max(revealEnd, outcomeEnd);
+  return {
+    intent: name,
+    p,
+    sd,
+    lower: clamp01(p - reveal.z * sd),
+    confidence: clamp01(1 - 2 * sd),
+    evidence: is.alpha + is.beta,
+    revealed: revealEnd !== null,
+    revealedAt: is.lastRevealedAt,
+    suppressedUntil
+  };
+}
+function decideReveal(prediction, reveal) {
+  return prediction.suppressedUntil === null && prediction.p >= reveal.threshold && prediction.lower >= reveal.threshold;
+}
+function buildExplanation(is, intent, learning, opts) {
   const p = betaMean(is.alpha, is.beta);
   const out = [];
-  for (const signal of Object.keys(config.signals)) {
+  for (const signal of Object.keys(intent.signals)) {
     const c = getOwn(is.contributions, signal) ?? { alpha: 0, beta: 0 };
-    const w = signalWeights(is, config, learning, signal);
+    const w = signalWeights(is, intent, learning, signal);
     const without = betaMean(is.alpha - c.alpha, is.beta - c.beta);
     out.push({
       signal,
@@ -401,7 +462,8 @@ function explain(state, intent, at) {
     });
   }
   out.sort((a, b) => Math.abs(b.impact) - Math.abs(a.impact) || compare(a.signal, b.signal));
-  return out;
+  const filtered = opts.nonZero ? out.filter((row) => row.contribution !== 0) : out;
+  return opts.limit === void 0 ? filtered : filtered.slice(0, opts.limit);
 }
 function compare(a, b) {
   if (a < b) return -1;
@@ -409,6 +471,62 @@ function compare(a, b) {
   return 0;
 }
 
+// src/evaluate.ts
+function evaluate(state, intent, at, opts) {
+  const s = requireState(state);
+  const name = expectName(intent, "intent");
+  const t = expectTimestamp(at, "at");
+  const config = requireIntentConfig(s, name);
+  const split = splitEvaluateOptions(opts, "options");
+  const reveal = resolveReveal(s.config, config, split.reveal, true);
+  const learning = resolveLearning(s.config);
+  const is = assessIntent(s, name, config, learning, t);
+  const prediction = buildPrediction(is, name, reveal, t);
+  return {
+    prediction,
+    reveal: decideReveal(prediction, reveal),
+    explanation: buildExplanation(is, config, learning, split.explain)
+  };
+}
+
+// src/evidence.ts
+function evidenceToReveal(intent, opts) {
+  const config = normalizeIntentConfig(intent, "intent");
+  const { threshold, z } = resolveReveal(void 0, config, opts);
+  const { alpha0, beta0 } = priorCounts(config);
+  const open = (w) => {
+    const alpha = alpha0 + w;
+    const p = betaMean(alpha, beta0);
+    return p >= threshold && clamp01(p - z * betaSd(alpha, beta0)) >= threshold;
+  };
+  if (threshold >= 1) return Number.POSITIVE_INFINITY;
+  if (open(0)) return 0;
+  let lo = 0;
+  let hi = 1;
+  while (!open(hi)) {
+    lo = hi;
+    hi *= 2;
+    if (hi > 1e15) return Number.POSITIVE_INFINITY;
+  }
+  for (let i = 0; i < 200 && hi - lo > 1e-9; i++) {
+    const mid = (lo + hi) / 2;
+    if (open(mid)) hi = mid;
+    else lo = mid;
+  }
+  return hi;
+}
+
+// src/explain.ts
+function explain(state, intent, at, opts) {
+  const s = requireState(state);
+  const name = expectName(intent, "intent");
+  const t = expectTimestamp(at, "at");
+  const config = requireIntentConfig(s, name);
+  const filters = opts === void 0 ? {} : normalizeExplainOptions(opts, "options");
+  const learning = resolveLearning(s.config);
+  return buildExplanation(assessIntent(s, name, config, learning, t), config, learning, filters);
+}
+
 // src/observe.ts
 function observe(state, event) {
   let s = requireState(state);
@@ -460,6 +578,11 @@ function closeEpisode(state, at) {
   }
   return { ...state, intents, episode: emptyEpisode() };
 }
+function episodeClosed(prev, next) {
+  const a = requireState(prev);
+  const b = requireState(next);
+  return a.episode.startedAt !== null && b.episode.startedAt !== a.episode.startedAt;
+}
 
 // src/predict.ts
 function predict(state, intent, at, opts) {
@@ -469,35 +592,14 @@ function predict(state, intent, at, opts) {
   const config = requireIntentConfig(s, name);
   const reveal = resolveReveal(s.config, config, opts);
   const is = decayIntent(getIntentState(s, name, config), config, t);
-  const p = betaMean(is.alpha, is.beta);
-  const sd = betaSd(is.alpha, is.beta);
-  const revealEnd = cooldownEnd(is.lastRevealedAt, reveal.cooldown, t);
-  const outcomeEnd = cooldownEnd(is.lastOutcomeAt, reveal.cooldown, t);
-  const suppressedUntil = revealEnd === null ? outcomeEnd : outcomeEnd === null ? revealEnd : Math.max(revealEnd, outcomeEnd);
-  return {
-    intent: name,
-    p,
-    sd,
-    lower: clamp01(p - reveal.z * sd),
-    confidence: clamp01(1 - 2 * sd),
-    evidence: is.alpha + is.beta,
-    revealed: revealEnd !== null,
-    revealedAt: is.lastRevealedAt,
-    suppressedUntil
-  };
-}
-function cooldownEnd(since, cooldown, at) {
-  if (since === null) return null;
-  const end = since + cooldown;
-  return at < end ? end : null;
+  return buildPrediction(is, name, reveal, t);
 }
 function shouldReveal(state, intent, at, opts) {
   const s = requireState(state);
   const name = expectName(intent, "intent");
   const config = requireIntentConfig(s, name);
-  const { threshold } = resolveReveal(s.config, config, opts);
-  const prediction = predict(s, name, at, opts);
-  return prediction.suppressedUntil === null && prediction.p >= threshold && prediction.lower >= threshold;
+  const reveal = resolveReveal(s.config, config, opts);
+  return decideReveal(predict(s, name, at, opts), reveal);
 }
 function markRevealed(state, intent, at) {
   const s = requireState(state);
@@ -688,6 +790,9 @@ exports.STATE_VERSION = STATE_VERSION;
 exports.createState = createState;
 exports.deserialize = deserialize;
 exports.endEpisode = endEpisode;
+exports.episodeClosed = episodeClosed;
+exports.evaluate = evaluate;
+exports.evidenceToReveal = evidenceToReveal;
 exports.explain = explain;
 exports.markRevealed = markRevealed;
 exports.observe = observe;