oracular 0.5.2 → 0.7.0

package/dist/index.d.cts

@@ -2,7 +2,9 @@
  * Version of the serialized state shape, stored in every state as `state.version`. Bumped only
  * when `EngineState` changes incompatibly, and every bump ships its migration: {@link deserialize}
  * upgrades states saved by earlier versions of this library on its own (version 1, written by
- * oracular 0.1.0 to 0.2.x, becomes version 2) and calls your `migrate` function only for a version
+ * oracular 0.1.0 to 0.2.x, and version 2, written by 0.3.0 to 0.5.x, become version 3), reads a
+ * state one version newer than its own as its own (a version bump only adds fields, so a rollback
+ * by one release keeps the user's history), and calls your `migrate` function only for a version
  * it does not know.
  *
  * @example
@@ -19,7 +21,7 @@
  * });
  * ```
  */
-declare const STATE_VERSION: 2;
+declare const STATE_VERSION: 3;
 /**
  * Version of the recorder format: the `v` field of every record that {@link createRecord} and
  * {@link createEndRecord} produce. A new optional field does not change it; readers ignore fields
@@ -112,6 +114,17 @@ interface IntentConfig {
      * weight.
      */
     saturate?: boolean;
+    /**
+     * How long a closed episode's signals wait for the outcome before they take a miss, in the same
+     * unit as `at`. With it set, an episode that ends without the outcome is held instead of
+     * counted. When the outcome arrives inside the window, each held episode gets a share
+     * `2^(−age / halfLife)` of a hit and the rest of a miss, with `age` measured from the episode's
+     * close: the sessions that built up to the outcome are credited by how much of their evidence
+     * still stands. When the window passes, the episode is a miss, recorded at the moment the window
+     * ended. Unset: an episode that ends without the outcome is a miss at once. A natural first value
+     * is the intent's `halfLife`, where the smallest share inside the window is one half.
+     */
+    attribution?: number;
     /** Reveal defaults for this intent. */
     reveal?: RevealOptions;
 }
@@ -143,11 +156,18 @@ interface SignalContribution {
 }
 /** What this user's history says about one signal. Decays with `learning.halfLife`. */
 interface SignalRecord {
-    /** Episodes in which the signal was followed by the outcome. */
+    /** Episodes in which the signal was followed by the outcome. An episode credited by a later outcome under `attribution` adds its share here and the rest to `misses`. */
     hits: number;
     /** Episodes in which it was not. */
     misses: number;
 }
+/** A closed episode waiting for the intent's outcome inside its `attribution` window. */
+interface PendingEpisode {
+    /** When the episode closed. Its wait ends `attribution` later. */
+    endedAt: number;
+    /** The signals seen in it, each once. */
+    seen: string[];
+}
 /**
  * Everything the engine knows about one intent for this user. Plain data; read it for debugging
  * or dashboards, but change it only through the engine's functions.
@@ -163,6 +183,11 @@ interface IntentState {
     learned: Record<string, SignalRecord>;
     /** Episodes that ended with (`hits`) or without (`misses`) the outcome: the base rate. */
     episodes: SignalRecord;
+    /**
+     * Closed episodes whose verdict waits for the outcome (see {@link IntentConfig.attribution}),
+     * in order of close, at most 32. Empty unless `attribution` is set.
+     */
+    pending: PendingEpisode[];
     /** Time `learned` and `episodes` were last decayed to. */
     learnedAt: number | null;
     lastRevealedAt: number | null;
@@ -314,7 +339,8 @@ interface Evaluation {
 /**
  * Turns a stored state of a version this library cannot migrate itself into a current
  * `EngineState`. Receives the parsed JSON as-is and the version it declares. States saved by
- * oracular 0.1.0 to 0.2.x (version 1) never reach it: `deserialize` upgrades those on its own.
+ * oracular 0.1.0 to 0.5.x (versions 1 and 2) never reach it, nor does a state one version newer
+ * than `STATE_VERSION`: `deserialize` handles both on its own.
  *
  * @example
  * ```ts
@@ -337,8 +363,9 @@ interface DeserializeOptions {
     /** The app's current config. Validated, swapped in, and used to prune signals and intents no longer declared. */
     config?: EngineConfig;
     /**
-     * Called when the stored version is neither `STATE_VERSION` nor one this library migrates
-     * itself (states from oracular 0.1.0 to 0.2.x are upgraded without it).
+     * Called when the stored version is neither `STATE_VERSION`, nor one this library migrates
+     * itself (states from oracular 0.1.0 to 0.5.x are upgraded without it), nor the next version,
+     * which it reads as its own.
      */
     migrate?: Migrate;
 }
@@ -433,6 +460,51 @@ interface EndRecord {
 }
 /** A line of a recorder log. */
 type RecorderRecord = EventRecord | EndRecord;
+/** One intent in a {@link Snapshot}: its name and what {@link evaluate} says about it. */
+interface IntentSnapshot extends Evaluation {
+    intent: string;
+}
+/**
+ * Every intent's prediction, gate and explanation at one moment, as {@link inspect} returns it:
+ * what a debug panel shows, what a test asserts on, what `console.table` prints.
+ *
+ * @example
+ * ```ts
+ * const { intents } = inspect(state, Date.now());
+ * console.table(intents.map((i) => ({ intent: i.intent, p: i.prediction.p, reveal: i.reveal })));
+ * ```
+ */
+interface Snapshot {
+    at: number;
+    /** In config order. */
+    intents: IntentSnapshot[];
+}
+/**
+ * The intents `oracular/presets` ships. Each is a plain {@link IntentConfig} to spread into your
+ * config and override; `presetSources` there says where its numbers come from.
+ */
+type PresetName = 'willBuy' | 'upgrade' | 'stuck' | 'churn';
+/**
+ * Where a preset's numbers come from, as `presetSources` in `oracular/presets` reports it. A tuned
+ * preset was fitted by `oracular tune` on a real log and carries the sample behind it; a
+ * hand-written one is a careful guess nobody has measured. Either is a starting point: run in
+ * shadow mode and let `tune` replace it with your own numbers.
+ *
+ * @example
+ * ```ts
+ * import { presetSources } from 'oracular/presets';
+ * presetSources.willBuy.kind; // 'tuned'
+ * ```
+ */
+interface PresetSource {
+    kind: 'tuned' | 'hand-written';
+    /** What the numbers were fitted on, or where the guess comes from. */
+    note: string;
+    /** Counted episodes behind a tuned preset; null for a hand-written one. */
+    episodes: number | null;
+    /** Installs those episodes came from; null for a hand-written one. */
+    installs: number | null;
+}
 
 /**
  * {@link predict}, {@link shouldReveal} and {@link explain} in one call, from a single decay
@@ -457,6 +529,25 @@ type RecorderRecord = EventRecord | EndRecord;
  * ```
  */
 declare function evaluate(state: EngineState, intent: string, at: number, opts?: EvaluateOptions): Evaluation;
+/**
+ * {@link evaluate} for every declared intent at once, in config order: the whole engine's view at
+ * one moment, as plain data. This is what to log, assert on, or hand to `renderInspector` from
+ * `oracular/inspect` for a live panel. Read-only.
+ *
+ * @param state - The current state. Not mutated.
+ * @param at - The time to evaluate at.
+ * @param opts - Reveal overrides and explain filters, applied to every intent.
+ * @returns `at` and one {@link IntentSnapshot} per intent.
+ * @throws `TypeError` when `state` is not an engine state, `at` is not finite, or `opts` is
+ *   malformed.
+ * @example
+ * ```ts
+ * for (const { intent, prediction, reveal } of inspect(state, Date.now()).intents) {
+ *   console.log(intent, prediction.p.toFixed(3), reveal ? 'reveal' : '');
+ * }
+ * ```
+ */
+declare function inspect(state: EngineState, at: number, opts?: EvaluateOptions): Snapshot;
 
 /**
  * How much positive evidence an intent needs before {@link shouldReveal} first becomes true:
@@ -517,10 +608,11 @@ declare function explain(state: EngineState, intent: string, at: number, opts?:
  * `w × log2(1 + 1/n)`, counted since the episode started or the intent's outcome last arrived.
  * That is the default when `config.episodeTimeout` is set, and `IntentConfig.saturate` overrides
  * it either way; otherwise every occurrence adds all of `w`. For every intent the event is the
- * outcome of: give the remembered signals a hit, count the episode toward the base rate, record
- * `lastOutcomeAt`, and (by default) reset the evidence to the prior. Any event opens or extends
- * the current episode; an idle gap longer than `config.episodeTimeout` closes the previous
- * episode first.
+ * outcome of: give the remembered signals a hit, count the episode toward the base rate, credit
+ * the closed episodes still waiting under `IntentConfig.attribution` by `2^(−age / halfLife)`
+ * each, record `lastOutcomeAt`, and (by default) reset the evidence to the prior. Any event opens
+ * or extends the current episode; an idle gap longer than `config.episodeTimeout` closes the
+ * previous episode first.
  *
  * @param state - The current state. Not mutated.
  * @param event - `name` is matched against every intent's signals and outcome; `at` is the
@@ -540,7 +632,8 @@ declare function explain(state: EngineState, intent: string, at: number, opts?:
 declare function observe(state: EngineState, event: IntentEvent): EngineState;
 /**
  * Ends the current episode at `at`. Every intent whose outcome did not arrive gives a miss to
- * each signal seen this episode and counts the episode toward its base rate. Call it when a
+ * each signal seen this episode and counts the episode toward its base rate, or, with
+ * `IntentConfig.attribution` set, holds the episode for the outcome instead. Call it when a
  * session ends: tab closed, app backgrounded, user signed out.
  *
  * @param state - The current state. Not mutated.
@@ -562,7 +655,8 @@ 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`.
+ * `next.intents[x].episodes.misses - prev.intents[x].episodes.misses` (0 for an intent with
+ * `attribution` set, whose verdict waits).
  *
  * @param prev - The state before the operation.
  * @param next - The state after it.
@@ -711,8 +805,10 @@ declare function serialize(state: EngineState): string;
  * Always pass the app's current `config`: it is validated and replaces the stored snapshot,
  * intents and signals no longer declared are dropped (α and β are recomputed from the kept
  * contributions), and newly declared intents start at their prior. States saved by oracular
- * 0.1.0 to 0.2.x are upgraded to the current shape on their own; `migrate` is only for a version
- * this library does not know.
+ * 0.1.0 to 0.5.x are upgraded to the current shape on their own, and a state one version newer
+ * than {@link STATE_VERSION} (written by the next release, read after a rollback) is read as the
+ * current one, ignoring the fields it adds; `migrate` is only for a version this library does
+ * not know.
  *
  * @param json - A string produced by {@link serialize}.
  * @param opts - `config`: the app's current config. `migrate`: called as
@@ -722,8 +818,9 @@ declare function serialize(state: EngineState): string;
  * @throws `SyntaxError` when `json` is not valid JSON.
  * @throws `TypeError` when the stored data, the result of `migrate`, `opts` or `opts.config`
  *   has the wrong shape.
- * @throws `RangeError` when the stored version is unknown and no `migrate` is given, when
- *   `migrate` does not return the current version, when a stored number is out of range, or
+ * @throws `RangeError` when the stored version is neither one this library reads (1 to one past
+ *   {@link STATE_VERSION}) nor handled by a given `migrate`, when `migrate` does not return the
+ *   current version, when a stored number is out of range, or
  *   when stored numbers are finite but too large to compute with (a tampered or corrupted state
  *   that would otherwise answer NaN).
  * @example
@@ -823,4 +920,4 @@ declare const ms: Units;
  */
 declare function validateConfig(config: unknown): EngineConfig;
 
-export { type DeserializeOptions, type EndRecord, type EngineConfig, type EngineState, type EpisodeIntentRecord, type EpisodeState, type EvaluateOptions, type Evaluation, type EventRecord, type ExplainOptions, type IntentConfig, type IntentEvent, type IntentState, type LearningConfig, type Migrate, type Prediction, RECORD_VERSION, type RecordMode, type RecordOptions, type RecordedDecision, type RecorderRecord, type RevealOptions, STATE_VERSION, type SignalContribution, type SignalExplanation, type SignalRecord, type Units, createEndRecord, createRecord, createState, deserialize, endEpisode, episodeClosed, evaluate, evidenceToReveal, explain, markRevealed, ms, observe, predict, serialize, shouldReveal, validateConfig };
+export { type DeserializeOptions, type EndRecord, type EngineConfig, type EngineState, type EpisodeIntentRecord, type EpisodeState, type EvaluateOptions, type Evaluation, type EventRecord, type ExplainOptions, type IntentConfig, type IntentEvent, type IntentSnapshot, type IntentState, type LearningConfig, type Migrate, type PendingEpisode, type Prediction, type PresetName, type PresetSource, RECORD_VERSION, type RecordMode, type RecordOptions, type RecordedDecision, type RecorderRecord, type RevealOptions, STATE_VERSION, type SignalContribution, type SignalExplanation, type SignalRecord, type Snapshot, type Units, createEndRecord, createRecord, createState, deserialize, endEpisode, episodeClosed, evaluate, evidenceToReveal, explain, inspect, markRevealed, ms, observe, predict, serialize, shouldReveal, validateConfig };

package/dist/index.d.ts

@@ -2,7 +2,9 @@
  * Version of the serialized state shape, stored in every state as `state.version`. Bumped only
  * when `EngineState` changes incompatibly, and every bump ships its migration: {@link deserialize}
  * upgrades states saved by earlier versions of this library on its own (version 1, written by
- * oracular 0.1.0 to 0.2.x, becomes version 2) and calls your `migrate` function only for a version
+ * oracular 0.1.0 to 0.2.x, and version 2, written by 0.3.0 to 0.5.x, become version 3), reads a
+ * state one version newer than its own as its own (a version bump only adds fields, so a rollback
+ * by one release keeps the user's history), and calls your `migrate` function only for a version
  * it does not know.
  *
  * @example
@@ -19,7 +21,7 @@
  * });
  * ```
  */
-declare const STATE_VERSION: 2;
+declare const STATE_VERSION: 3;
 /**
  * Version of the recorder format: the `v` field of every record that {@link createRecord} and
  * {@link createEndRecord} produce. A new optional field does not change it; readers ignore fields
@@ -112,6 +114,17 @@ interface IntentConfig {
      * weight.
      */
     saturate?: boolean;
+    /**
+     * How long a closed episode's signals wait for the outcome before they take a miss, in the same
+     * unit as `at`. With it set, an episode that ends without the outcome is held instead of
+     * counted. When the outcome arrives inside the window, each held episode gets a share
+     * `2^(−age / halfLife)` of a hit and the rest of a miss, with `age` measured from the episode's
+     * close: the sessions that built up to the outcome are credited by how much of their evidence
+     * still stands. When the window passes, the episode is a miss, recorded at the moment the window
+     * ended. Unset: an episode that ends without the outcome is a miss at once. A natural first value
+     * is the intent's `halfLife`, where the smallest share inside the window is one half.
+     */
+    attribution?: number;
     /** Reveal defaults for this intent. */
     reveal?: RevealOptions;
 }
@@ -143,11 +156,18 @@ interface SignalContribution {
 }
 /** What this user's history says about one signal. Decays with `learning.halfLife`. */
 interface SignalRecord {
-    /** Episodes in which the signal was followed by the outcome. */
+    /** Episodes in which the signal was followed by the outcome. An episode credited by a later outcome under `attribution` adds its share here and the rest to `misses`. */
     hits: number;
     /** Episodes in which it was not. */
     misses: number;
 }
+/** A closed episode waiting for the intent's outcome inside its `attribution` window. */
+interface PendingEpisode {
+    /** When the episode closed. Its wait ends `attribution` later. */
+    endedAt: number;
+    /** The signals seen in it, each once. */
+    seen: string[];
+}
 /**
  * Everything the engine knows about one intent for this user. Plain data; read it for debugging
  * or dashboards, but change it only through the engine's functions.
@@ -163,6 +183,11 @@ interface IntentState {
     learned: Record<string, SignalRecord>;
     /** Episodes that ended with (`hits`) or without (`misses`) the outcome: the base rate. */
     episodes: SignalRecord;
+    /**
+     * Closed episodes whose verdict waits for the outcome (see {@link IntentConfig.attribution}),
+     * in order of close, at most 32. Empty unless `attribution` is set.
+     */
+    pending: PendingEpisode[];
     /** Time `learned` and `episodes` were last decayed to. */
     learnedAt: number | null;
     lastRevealedAt: number | null;
@@ -314,7 +339,8 @@ interface Evaluation {
 /**
  * Turns a stored state of a version this library cannot migrate itself into a current
  * `EngineState`. Receives the parsed JSON as-is and the version it declares. States saved by
- * oracular 0.1.0 to 0.2.x (version 1) never reach it: `deserialize` upgrades those on its own.
+ * oracular 0.1.0 to 0.5.x (versions 1 and 2) never reach it, nor does a state one version newer
+ * than `STATE_VERSION`: `deserialize` handles both on its own.
  *
  * @example
  * ```ts
@@ -337,8 +363,9 @@ interface DeserializeOptions {
     /** The app's current config. Validated, swapped in, and used to prune signals and intents no longer declared. */
     config?: EngineConfig;
     /**
-     * Called when the stored version is neither `STATE_VERSION` nor one this library migrates
-     * itself (states from oracular 0.1.0 to 0.2.x are upgraded without it).
+     * Called when the stored version is neither `STATE_VERSION`, nor one this library migrates
+     * itself (states from oracular 0.1.0 to 0.5.x are upgraded without it), nor the next version,
+     * which it reads as its own.
      */
     migrate?: Migrate;
 }
@@ -433,6 +460,51 @@ interface EndRecord {
 }
 /** A line of a recorder log. */
 type RecorderRecord = EventRecord | EndRecord;
+/** One intent in a {@link Snapshot}: its name and what {@link evaluate} says about it. */
+interface IntentSnapshot extends Evaluation {
+    intent: string;
+}
+/**
+ * Every intent's prediction, gate and explanation at one moment, as {@link inspect} returns it:
+ * what a debug panel shows, what a test asserts on, what `console.table` prints.
+ *
+ * @example
+ * ```ts
+ * const { intents } = inspect(state, Date.now());
+ * console.table(intents.map((i) => ({ intent: i.intent, p: i.prediction.p, reveal: i.reveal })));
+ * ```
+ */
+interface Snapshot {
+    at: number;
+    /** In config order. */
+    intents: IntentSnapshot[];
+}
+/**
+ * The intents `oracular/presets` ships. Each is a plain {@link IntentConfig} to spread into your
+ * config and override; `presetSources` there says where its numbers come from.
+ */
+type PresetName = 'willBuy' | 'upgrade' | 'stuck' | 'churn';
+/**
+ * Where a preset's numbers come from, as `presetSources` in `oracular/presets` reports it. A tuned
+ * preset was fitted by `oracular tune` on a real log and carries the sample behind it; a
+ * hand-written one is a careful guess nobody has measured. Either is a starting point: run in
+ * shadow mode and let `tune` replace it with your own numbers.
+ *
+ * @example
+ * ```ts
+ * import { presetSources } from 'oracular/presets';
+ * presetSources.willBuy.kind; // 'tuned'
+ * ```
+ */
+interface PresetSource {
+    kind: 'tuned' | 'hand-written';
+    /** What the numbers were fitted on, or where the guess comes from. */
+    note: string;
+    /** Counted episodes behind a tuned preset; null for a hand-written one. */
+    episodes: number | null;
+    /** Installs those episodes came from; null for a hand-written one. */
+    installs: number | null;
+}
 
 /**
  * {@link predict}, {@link shouldReveal} and {@link explain} in one call, from a single decay
@@ -457,6 +529,25 @@ type RecorderRecord = EventRecord | EndRecord;
  * ```
  */
 declare function evaluate(state: EngineState, intent: string, at: number, opts?: EvaluateOptions): Evaluation;
+/**
+ * {@link evaluate} for every declared intent at once, in config order: the whole engine's view at
+ * one moment, as plain data. This is what to log, assert on, or hand to `renderInspector` from
+ * `oracular/inspect` for a live panel. Read-only.
+ *
+ * @param state - The current state. Not mutated.
+ * @param at - The time to evaluate at.
+ * @param opts - Reveal overrides and explain filters, applied to every intent.
+ * @returns `at` and one {@link IntentSnapshot} per intent.
+ * @throws `TypeError` when `state` is not an engine state, `at` is not finite, or `opts` is
+ *   malformed.
+ * @example
+ * ```ts
+ * for (const { intent, prediction, reveal } of inspect(state, Date.now()).intents) {
+ *   console.log(intent, prediction.p.toFixed(3), reveal ? 'reveal' : '');
+ * }
+ * ```
+ */
+declare function inspect(state: EngineState, at: number, opts?: EvaluateOptions): Snapshot;
 
 /**
  * How much positive evidence an intent needs before {@link shouldReveal} first becomes true:
@@ -517,10 +608,11 @@ declare function explain(state: EngineState, intent: string, at: number, opts?:
  * `w × log2(1 + 1/n)`, counted since the episode started or the intent's outcome last arrived.
  * That is the default when `config.episodeTimeout` is set, and `IntentConfig.saturate` overrides
  * it either way; otherwise every occurrence adds all of `w`. For every intent the event is the
- * outcome of: give the remembered signals a hit, count the episode toward the base rate, record
- * `lastOutcomeAt`, and (by default) reset the evidence to the prior. Any event opens or extends
- * the current episode; an idle gap longer than `config.episodeTimeout` closes the previous
- * episode first.
+ * outcome of: give the remembered signals a hit, count the episode toward the base rate, credit
+ * the closed episodes still waiting under `IntentConfig.attribution` by `2^(−age / halfLife)`
+ * each, record `lastOutcomeAt`, and (by default) reset the evidence to the prior. Any event opens
+ * or extends the current episode; an idle gap longer than `config.episodeTimeout` closes the
+ * previous episode first.
  *
  * @param state - The current state. Not mutated.
  * @param event - `name` is matched against every intent's signals and outcome; `at` is the
@@ -540,7 +632,8 @@ declare function explain(state: EngineState, intent: string, at: number, opts?:
 declare function observe(state: EngineState, event: IntentEvent): EngineState;
 /**
  * Ends the current episode at `at`. Every intent whose outcome did not arrive gives a miss to
- * each signal seen this episode and counts the episode toward its base rate. Call it when a
+ * each signal seen this episode and counts the episode toward its base rate, or, with
+ * `IntentConfig.attribution` set, holds the episode for the outcome instead. Call it when a
  * session ends: tab closed, app backgrounded, user signed out.
  *
  * @param state - The current state. Not mutated.
@@ -562,7 +655,8 @@ 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`.
+ * `next.intents[x].episodes.misses - prev.intents[x].episodes.misses` (0 for an intent with
+ * `attribution` set, whose verdict waits).
  *
  * @param prev - The state before the operation.
  * @param next - The state after it.
@@ -711,8 +805,10 @@ declare function serialize(state: EngineState): string;
  * Always pass the app's current `config`: it is validated and replaces the stored snapshot,
  * intents and signals no longer declared are dropped (α and β are recomputed from the kept
  * contributions), and newly declared intents start at their prior. States saved by oracular
- * 0.1.0 to 0.2.x are upgraded to the current shape on their own; `migrate` is only for a version
- * this library does not know.
+ * 0.1.0 to 0.5.x are upgraded to the current shape on their own, and a state one version newer
+ * than {@link STATE_VERSION} (written by the next release, read after a rollback) is read as the
+ * current one, ignoring the fields it adds; `migrate` is only for a version this library does
+ * not know.
  *
  * @param json - A string produced by {@link serialize}.
  * @param opts - `config`: the app's current config. `migrate`: called as
@@ -722,8 +818,9 @@ declare function serialize(state: EngineState): string;
  * @throws `SyntaxError` when `json` is not valid JSON.
  * @throws `TypeError` when the stored data, the result of `migrate`, `opts` or `opts.config`
  *   has the wrong shape.
- * @throws `RangeError` when the stored version is unknown and no `migrate` is given, when
- *   `migrate` does not return the current version, when a stored number is out of range, or
+ * @throws `RangeError` when the stored version is neither one this library reads (1 to one past
+ *   {@link STATE_VERSION}) nor handled by a given `migrate`, when `migrate` does not return the
+ *   current version, when a stored number is out of range, or
  *   when stored numbers are finite but too large to compute with (a tampered or corrupted state
  *   that would otherwise answer NaN).
  * @example
@@ -823,4 +920,4 @@ declare const ms: Units;
  */
 declare function validateConfig(config: unknown): EngineConfig;
 
-export { type DeserializeOptions, type EndRecord, type EngineConfig, type EngineState, type EpisodeIntentRecord, type EpisodeState, type EvaluateOptions, type Evaluation, type EventRecord, type ExplainOptions, type IntentConfig, type IntentEvent, type IntentState, type LearningConfig, type Migrate, type Prediction, RECORD_VERSION, type RecordMode, type RecordOptions, type RecordedDecision, type RecorderRecord, type RevealOptions, STATE_VERSION, type SignalContribution, type SignalExplanation, type SignalRecord, type Units, createEndRecord, createRecord, createState, deserialize, endEpisode, episodeClosed, evaluate, evidenceToReveal, explain, markRevealed, ms, observe, predict, serialize, shouldReveal, validateConfig };
+export { type DeserializeOptions, type EndRecord, type EngineConfig, type EngineState, type EpisodeIntentRecord, type EpisodeState, type EvaluateOptions, type Evaluation, type EventRecord, type ExplainOptions, type IntentConfig, type IntentEvent, type IntentSnapshot, type IntentState, type LearningConfig, type Migrate, type PendingEpisode, type Prediction, type PresetName, type PresetSource, RECORD_VERSION, type RecordMode, type RecordOptions, type RecordedDecision, type RecorderRecord, type RevealOptions, STATE_VERSION, type SignalContribution, type SignalExplanation, type SignalRecord, type Snapshot, type Units, createEndRecord, createRecord, createState, deserialize, endEpisode, episodeClosed, evaluate, evidenceToReveal, explain, inspect, markRevealed, ms, observe, predict, serialize, shouldReveal, validateConfig };