oracular 0.1.1 → 0.1.2

package/dist/index.d.ts

@@ -242,6 +242,37 @@ interface SignalExplanation {
     hits: number;
     misses: number;
 }
+/**
+ * Filters for `explain` and `evaluate`. By default every declared signal is returned.
+ *
+ * @example
+ * ```ts
+ * explain(state, 'upgrade', now, { nonZero: true, limit: 3 }); // the three signals doing the most
+ * ```
+ */
+interface ExplainOptions {
+    /** Only signals that currently hold evidence (a non-zero contribution). Default false. */
+    nonZero?: boolean;
+    /** At most this many rows, taken from the top of the impact-sorted list. Default: all. */
+    limit?: number;
+}
+/** Reveal overrides and explain filters together, for `evaluate`. */
+interface EvaluateOptions extends RevealOptions, ExplainOptions {
+}
+/**
+ * What `evaluate` returns: the same values `predict`, `shouldReveal` and `explain` would give
+ * for the same inputs, computed from a single decay pass.
+ *
+ * @example
+ * ```ts
+ * const { prediction, reveal, explanation } = evaluate(state, 'upgrade', Date.now());
+ * ```
+ */
+interface Evaluation {
+    prediction: Prediction;
+    reveal: boolean;
+    explanation: SignalExplanation[];
+}
 /**
  * Turns a stored state of an older version into a current `EngineState`. Receives the parsed
  * JSON as-is and the version it declares.
@@ -270,6 +301,52 @@ interface DeserializeOptions {
     migrate?: Migrate;
 }
 
+/**
+ * {@link predict}, {@link shouldReveal} and {@link explain} in one call, from a single decay
+ * pass over the intent. The three results are identical to what the separate functions return
+ * for the same inputs; this is the one to call on every event when you need all of them.
+ * Read-only.
+ *
+ * @param state - The current state. Not mutated.
+ * @param intent - Name of an intent declared in the config.
+ * @param at - The time to evaluate at.
+ * @param opts - Reveal overrides (`threshold`, `z`, `cooldown`) and explain filters (`nonZero`,
+ *   `limit`) in one object.
+ * @returns `prediction` (as `predict`), `reveal` (as `shouldReveal`) and `explanation` (as
+ *   `explain` with the same filters).
+ * @throws `RangeError` when `intent` is not declared in the config.
+ * @throws `TypeError` when `state` is not an engine state, `at` is not finite, or `opts` is
+ *   malformed.
+ * @example
+ * ```ts
+ * const { prediction, reveal, explanation } = evaluate(state, 'upgrade', Date.now(), { limit: 3 });
+ * if (reveal) showOffer(explanation[0]?.signal);
+ * ```
+ */
+declare function evaluate(state: EngineState, intent: string, at: number, opts?: EvaluateOptions): Evaluation;
+
+/**
+ * How much positive evidence an intent needs before {@link shouldReveal} first becomes true:
+ * the smallest pseudo-count `w` such that Beta(α₀ + w, β₀) clears both `p ≥ threshold` and
+ * `p − z·sd ≥ threshold`. Divide by a signal's weight and round up for the number of identical
+ * signals, fired together, that open the gate. Solved numerically to 1e-9.
+ *
+ * Cooldowns and decay are not part of the answer: this is the evidence needed at one instant.
+ *
+ * @param intent - One intent's config, validated as `createState` would.
+ * @param opts - `threshold` and `z` overrides, resolved as call → intent → defaults (there is
+ *   no engine config here). `cooldown` is accepted and ignored.
+ * @returns The pseudo-count sum; 0 when the prior alone already clears the gate; `Infinity`
+ *   when no finite amount of evidence can (threshold 1).
+ * @throws `TypeError` or `RangeError` when `intent` or `opts` is invalid.
+ * @example
+ * ```ts
+ * const needed = evidenceToReveal(config.intents.upgrade); // ≈ 15.1 for the quickstart config
+ * Math.ceil(needed / 3); // 6 signals of weight 3
+ * ```
+ */
+declare function evidenceToReveal(intent: IntentConfig, opts?: RevealOptions): number;
+
 /**
  * Why the intent's p is what it is at time `at`: one entry per declared signal, the ones that
  * matter most first. `contribution` is the signed pseudo-count the signal currently holds after
@@ -280,18 +357,21 @@ interface DeserializeOptions {
  * @param state - The current state. Not mutated.
  * @param intent - Name of an intent declared in the config.
  * @param at - The time to evaluate at; contributions and learned counts are decayed to it.
+ * @param opts - Optional filters: `nonZero` keeps only signals that currently hold evidence,
+ *   `limit` caps the number of rows. Default: every declared signal.
  * @returns One {@link SignalExplanation} per declared signal, sorted by |impact| descending,
- *   then by name. Empty for an intent that declares no signals.
+ *   then by name, then filtered by `opts`. Empty for an intent that declares no signals.
  * @throws `RangeError` when `intent` is not declared in the config.
- * @throws `TypeError` when `state` is not an engine state or `at` is not finite.
+ * @throws `TypeError` when `state` is not an engine state, `at` is not finite, or `opts` is
+ *   malformed.
  * @example
  * ```ts
- * for (const row of explain(state, 'upgrade', Date.now())) {
+ * for (const row of explain(state, 'upgrade', Date.now(), { nonZero: true })) {
  *   console.log(row.signal, row.impact.toFixed(2), row.effectiveWeight.toFixed(2));
  * }
  * ```
  */
-declare function explain(state: EngineState, intent: string, at: number): SignalExplanation[];
+declare function explain(state: EngineState, intent: string, at: number, opts?: ExplainOptions): SignalExplanation[];
 
 /**
  * Feeds one event to the engine.
@@ -339,6 +419,24 @@ declare function observe(state: EngineState, event: IntentEvent): EngineState;
  * ```
  */
 declare function endEpisode(state: EngineState, at: number): EngineState;
+/**
+ * Whether an episode closed between two states: `prev` had an open episode and `next` either
+ * has none or has a different one. Useful after `observe` or `endEpisode` to react to a
+ * session ending, for example to persist, or to read the misses it produced as
+ * `next.intents[x].episodes.misses - prev.intents[x].episodes.misses`.
+ *
+ * @param prev - The state before the operation.
+ * @param next - The state after it.
+ * @returns True when `prev.episode.startedAt` is not null and differs from
+ *   `next.episode.startedAt`.
+ * @throws `TypeError` when either argument is not an engine state.
+ * @example
+ * ```ts
+ * const next = observe(state, event);
+ * if (episodeClosed(state, next)) persist(next);
+ * ```
+ */
+declare function episodeClosed(prev: EngineState, next: EngineState): boolean;
 
 /**
  * The intent's current estimate at time `at`: the Beta mean p, its standard deviation, the
@@ -473,4 +571,4 @@ declare function deserialize(json: string, opts?: DeserializeOptions): EngineSta
  */
 declare function createState(config: EngineConfig): EngineState;
 
-export { type DeserializeOptions, type EngineConfig, type EngineState, type EpisodeIntentRecord, type EpisodeState, type IntentConfig, type IntentEvent, type IntentState, type LearningConfig, type Migrate, type Prediction, type RevealOptions, STATE_VERSION, type SignalContribution, type SignalExplanation, type SignalRecord, createState, deserialize, endEpisode, explain, markRevealed, observe, predict, serialize, shouldReveal };
+export { type DeserializeOptions, type EngineConfig, type EngineState, type EpisodeIntentRecord, type EpisodeState, type EvaluateOptions, type Evaluation, type ExplainOptions, type IntentConfig, type IntentEvent, type IntentState, type LearningConfig, type Migrate, type Prediction, type RevealOptions, STATE_VERSION, type SignalContribution, type SignalExplanation, type SignalRecord, createState, deserialize, endEpisode, episodeClosed, evaluate, evidenceToReveal, explain, markRevealed, observe, predict, serialize, shouldReveal };

package/dist/index.js

@@ -1,3 +1,31 @@
+// 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);
@@ -16,6 +44,96 @@ 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 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/config.ts
 var DEFAULT_THRESHOLD = 0.5;
 var DEFAULT_Z = 1.28;
@@ -33,6 +151,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}`);
 }
@@ -113,7 +232,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`);
@@ -155,7 +274,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) {
@@ -167,12 +289,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) {
@@ -195,124 +348,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: {} };
@@ -372,20 +407,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,
@@ -399,7 +456,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;
@@ -407,6 +465,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);
@@ -458,6 +572,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) {
@@ -467,35 +586,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);
@@ -682,6 +780,6 @@ function reconcile(raw, config) {
   };
 }
 
-export { STATE_VERSION, createState, deserialize, endEpisode, explain, markRevealed, observe, predict, serialize, shouldReveal };
+export { STATE_VERSION, createState, deserialize, endEpisode, episodeClosed, evaluate, evidenceToReveal, explain, markRevealed, observe, predict, serialize, shouldReveal };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map