oracular 0.2.1 → 0.4.0

package/dist/index.d.ts

@@ -1,21 +1,40 @@
 /**
- * Version of the serialized state shape, stored in every state as `state.version`.
- * {@link deserialize} compares it with the stored value and calls your `migrate` function when
- * they differ. Bumped only when `EngineState` changes incompatibly.
+ * 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
+ * it does not know.
  *
  * @example
  * ```ts
  * import { STATE_VERSION, deserialize } from 'oracular';
  *
  * const state = deserialize(saved, {
+ *   config,
+ *   // Only reached for versions this library cannot migrate itself, such as a state written by a
+ *   // newer oracular before a rollback.
  *   migrate: (stored, version) => {
- *     if (version === 0) return upgradeFromV0(stored);
- *     throw new Error(`cannot migrate version ${version} to ${STATE_VERSION}`);
+ *     throw new Error(`cannot read oracular state version ${version} (this build reads ${STATE_VERSION})`);
  *   },
  * });
  * ```
  */
-declare const STATE_VERSION: 1;
+declare const STATE_VERSION: 2;
+/**
+ * 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
+ * they do not know and skip records of a `kind` they do not know. Anything a reader written for
+ * this version could misread bumps it.
+ *
+ * @example
+ * ```ts
+ * import { RECORD_VERSION } from 'oracular';
+ *
+ * const record = JSON.parse(line);
+ * if (record.v !== RECORD_VERSION) throw new Error(`unsupported recorder format ${record.v}`);
+ * ```
+ */
+declare const RECORD_VERSION: 1;
 
 /**
  * Options that decide when `shouldReveal` fires and how long cooldowns last. Resolved per call →
@@ -48,9 +67,9 @@ interface RevealOptions {
 interface LearningConfig {
     /** Half-life of learned hit/miss counts, in the same unit as `at`. Omit for no forgetting. */
     halfLife?: number;
-    /** A perfectly predictive signal converges to `gain × |initial weight|`. Default 2. */
+    /** A perfectly predictive signal converges to `gain × |initial weight|`. Default 2; at most 1e6. */
     gain?: number;
-    /** Pseudo-count behind the developer's initial weight: how many observed episodes it takes to weigh as much as the prior. Default 10. */
+    /** Pseudo-count behind the developer's initial weight: how many observed episodes it takes to weigh as much as the prior. Default 10; at most 1e6. */
     priorEpisodes?: number;
 }
 /**
@@ -72,16 +91,27 @@ interface LearningConfig {
 interface IntentConfig {
     /** Prior probability, strictly between 0 and 1. */
     prior: number;
-    /** Strength of the prior as a pseudo-count, greater than 0. */
+    /** Strength of the prior as a pseudo-count, greater than 0 and at most 1e6. */
     priorStrength: number;
     /** Half-life of evidence, in the same unit as `at`. Evidence decays back toward the prior. */
     halfLife: number;
-    /** Event name → initial weight. Positive is evidence for the intent, negative against. Non-zero. */
+    /** Event name → initial weight. Positive is evidence for the intent, negative against. Non-zero, between −1e6 and 1e6. */
     signals: Record<string, number>;
     /** Event name that confirms the intent happened, e.g. `'checkout.completed'`. */
     outcome?: string;
     /** Reset α, β and contributions to the prior when the outcome arrives. Default true. */
     resetOnOutcome?: boolean;
+    /**
+     * Repeats of a signal within one episode add less: the n-th occurrence adds
+     * `w × log2(1 + 1/n)`, so ten occurrences add 3.46 weights, not ten. The count restarts when
+     * the episode ends or this intent's outcome arrives. Default: true when `episodeTimeout` is
+     * set, false otherwise, because without an idle timeout episodes end only when the app calls
+     * `endEpisode`, and if it never does the count would never restart. Set true to saturate
+     * anyway (your app ends every episode itself), or false for intents where the repetition
+     * itself is the evidence (a user stuck on the same step), so every occurrence adds its full
+     * weight.
+     */
+    saturate?: boolean;
     /** Reveal defaults for this intent. */
     reveal?: RevealOptions;
 }
@@ -144,6 +174,11 @@ interface IntentState {
 interface EpisodeIntentRecord {
     /** Signals seen since the episode started (or since this intent's last outcome). */
     seen: string[];
+    /**
+     * How many times each signal in `seen` has occurred over the same span; its keys are exactly the
+     * signals in `seen`. Repeats saturate: the n-th occurrence adds less than the first.
+     */
+    counts: Record<string, number>;
     /** Whether the outcome arrived in this episode. */
     resolved: boolean;
 }
@@ -237,7 +272,10 @@ interface SignalExplanation {
     initialWeight: number;
     /** What this user's history alone says the weight should be. */
     learnedWeight: number;
-    /** The blend the next occurrence of the signal will actually add. */
+    /**
+     * The blend of initial and learned weight: what the signal adds the first time it occurs in an
+     * episode. Repeats within the episode add less (see {@link IntentConfig.saturate}).
+     */
     effectiveWeight: number;
     hits: number;
     misses: number;
@@ -274,8 +312,9 @@ interface Evaluation {
     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.
+ * 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.
  *
  * @example
  * ```ts
@@ -297,9 +336,103 @@ type Migrate = (stored: unknown, version: number) => EngineState;
 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 differs from `STATE_VERSION`. */
+    /**
+     * 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).
+     */
     migrate?: Migrate;
 }
+/**
+ * Whether the app acted on reveals when a record was made: `'shadow'` when it only computed them
+ * (nothing shown to the user), `'live'` when it showed them. Replay only measures shadow periods
+ * honestly: once a reveal is live, the reveal itself causes outcomes.
+ */
+type RecordMode = 'shadow' | 'live';
+/**
+ * What every record needs from the app, for {@link createRecord} and {@link createEndRecord}.
+ *
+ * @example
+ * ```ts
+ * const recording: RecordOptions = { installId: storedInstallId, mode: 'shadow' };
+ * ```
+ */
+interface RecordOptions {
+    /**
+     * A random id the app generates once, on first use, and stores (for example
+     * `crypto.randomUUID()`). It groups one install's records across exports and nothing else; never
+     * derive it from the device, the account or anything else about the user.
+     */
+    installId: string;
+    /** Whether reveals are shown to the user right now. */
+    mode: RecordMode;
+    /** How many signals to list in `top`, by size of impact. Default 3. */
+    top?: number;
+}
+/**
+ * What the engine decided for one intent at the moment of a record. It is there to compare what
+ * shipped with what a different config would have done; replay recomputes everything from the
+ * events and never reads it.
+ */
+interface RecordedDecision {
+    /** As {@link Prediction.p}. */
+    p: number;
+    /** As {@link Prediction.lower}. */
+    lower: number;
+    /** What `shouldReveal` returned with the state's own reveal options. */
+    shouldReveal: boolean;
+    /** As {@link Prediction.suppressedUntil}. */
+    suppressedUntil: number | null;
+    /** Signals currently holding evidence, largest |impact| first, at most `RecordOptions.top`. */
+    top: {
+        signal: string;
+        impact: number;
+    }[];
+    /** Effective weight of every declared signal, in config order. */
+    weights: Record<string, number>;
+}
+/**
+ * One line of a recorder log: an event the app observed and what the engine decided right after
+ * it. The event (`name` and `at`, never `props`) is what replay recomputes from; the decisions
+ * are kept apart so they can never be mistaken for inputs.
+ *
+ * @example
+ * ```ts
+ * state = observe(state, event);
+ * log.append(JSON.stringify(createRecord(state, event, recording)));
+ * ```
+ */
+interface EventRecord {
+    v: typeof RECORD_VERSION;
+    kind: 'event';
+    installId: string;
+    mode: RecordMode;
+    event: {
+        name: string;
+        at: number;
+    };
+    /** One entry per declared intent. */
+    decisions: Record<string, RecordedDecision>;
+}
+/**
+ * One line of a recorder log: the app ended the episode with {@link endEpisode}. Replay needs it
+ * to reproduce the misses that the episode's end records; episodes that end through
+ * `episodeTimeout` need no record.
+ *
+ * @example
+ * ```ts
+ * state = endEpisode(state, at);
+ * log.append(JSON.stringify(createEndRecord(at, recording)));
+ * ```
+ */
+interface EndRecord {
+    v: typeof RECORD_VERSION;
+    kind: 'end';
+    installId: string;
+    mode: RecordMode;
+    at: number;
+}
+/** A line of a recorder log. */
+type RecorderRecord = EventRecord | EndRecord;
 
 /**
  * {@link predict}, {@link shouldReveal} and {@link explain} in one call, from a single decay
@@ -328,8 +461,10 @@ declare function evaluate(state: EngineState, intent: string, at: number, opts?:
 /**
  * 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.
+ * `p − z·sd ≥ threshold`. Divide by a signal's weight and round up for the number of full-weight
+ * occurrences that open the gate: distinct signals, or one occurrence per episode. Repeats within
+ * one episode add less (n of them add `w × log2(1 + n)`, see {@link IntentConfig.saturate}).
+ * Solved numerically to 1e-9.
  *
  * Cooldowns and decay are not part of the answer: this is the evidence needed at one instant.
  *
@@ -342,7 +477,7 @@ declare function evaluate(state: EngineState, intent: string, at: number, opts?:
  * @example
  * ```ts
  * const needed = evidenceToReveal(config.intents.upgrade); // ≈ 15.1 for the quickstart config
- * Math.ceil(needed / 3); // 6 signals of weight 3
+ * Math.ceil(needed / 3); // 6 full-weight signals of weight 3
  * ```
  */
 declare function evidenceToReveal(intent: IntentConfig, opts?: RevealOptions): number;
@@ -378,10 +513,14 @@ declare function explain(state: EngineState, intent: string, at: number, opts?:
  *
  * For every intent the event is a signal of: decay its evidence to `event.at`, then add the
  * signal's effective weight to α (positive) or β (negative) and remember the signal for this
- * episode. 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.
+ * episode. Repeats within an episode saturate: the n-th occurrence of a signal adds
+ * `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.
  *
  * @param state - The current state. Not mutated.
  * @param event - `name` is matched against every intent's signals and outcome; `at` is the
@@ -503,6 +642,56 @@ declare function shouldReveal(state: EngineState, intent: string, at: number, op
  */
 declare function markRevealed(state: EngineState, intent: string, at: number): EngineState;
 
+/**
+ * A recorder record for an event: the event itself and, for every intent, what the engine decides
+ * right after it. Call it with the state `observe` returned for that event, then append
+ * `JSON.stringify(record)` as one line of the log (NDJSON). The record holds the event's `name` and
+ * `at`, never its `props`.
+ *
+ * Each decision is what {@link evaluate} reports at `event.at` with the state's own reveal
+ * options: `p`, `lower`, `shouldReveal`, `suppressedUntil`, the signals with the largest impact,
+ * and the effective weight of every signal. Pure: the install id comes from the app, never from
+ * here. See the Shadow mode guide for the whole workflow.
+ *
+ * @param state - The state after `observe(state, event)`. Not mutated.
+ * @param event - The event just observed. Only `name` and `at` are recorded.
+ * @param opts - `installId` (generated and stored by the app), `mode` (`'shadow'` while
+ *   reveals are computed but not shown, `'live'` once they are), and `top` (default 3).
+ * @returns A plain, JSON-serializable {@link EventRecord}.
+ * @throws `TypeError` when `state` is not an engine state, the event is malformed, `opts` is
+ *   not an object, has an unknown key, an empty `installId` or a `mode` other than
+ *   `'shadow'` or `'live'`.
+ * @throws `RangeError` when `opts.top` is negative or fractional.
+ * @example
+ * ```ts
+ * const recording = { installId: localStorage.getItem('oracular.install')!, mode: 'shadow' } as const;
+ *
+ * const event = { name: 'pricing.viewed', at: Date.now() };
+ * state = observe(state, event);
+ * appendLine(JSON.stringify(createRecord(state, event, recording)));
+ * ```
+ */
+declare function createRecord(state: EngineState, event: IntentEvent, opts: RecordOptions): EventRecord;
+/**
+ * A recorder record for the end of an episode. Write one whenever the app calls
+ * {@link endEpisode}, with the same `at`, so that replay can end the episode at the same moment
+ * and reproduce the misses it records. Episodes that close through `episodeTimeout` need none:
+ * replay applies the timeout itself.
+ *
+ * @param at - The time passed to `endEpisode`.
+ * @param opts - The same options as for {@link createRecord}; `top` is accepted and ignored.
+ * @returns A plain, JSON-serializable {@link EndRecord}.
+ * @throws `TypeError` when `at` is not a finite number or `opts` is malformed.
+ * @throws `RangeError` when `opts.top` is negative or fractional.
+ * @example
+ * ```ts
+ * const at = Date.now();
+ * state = endEpisode(state, at);
+ * appendLine(JSON.stringify(createEndRecord(at, recording)));
+ * ```
+ */
+declare function createEndRecord(at: number, opts: RecordOptions): EndRecord;
+
 /**
  * The state as a JSON string, for the host app to persist wherever it likes. The state is plain
  * data, so this is `JSON.stringify` after a shape check. The output never contains event props.
@@ -521,19 +710,22 @@ 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. Pass `migrate` to upgrade a
- * state saved by an older version of this library.
+ * 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.
  *
  * @param json - A string produced by {@link serialize}.
  * @param opts - `config`: the app's current config. `migrate`: called as
- *   `migrate(stored, version)` when the stored version differs from {@link STATE_VERSION};
- *   it must return a state of the current version.
+ *   `migrate(stored, version)` when the stored version is neither {@link STATE_VERSION} nor one
+ *   this library migrates itself; it must return a state of the current version.
  * @returns A validated state that satisfies the engine's invariants.
  * @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 differs and no `migrate` is given, when
- *   `migrate` does not return the current version, or when a stored number is out of range.
+ * @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
+ *   when stored numbers are finite but too large to compute with (a tampered or corrupted state
+ *   that would otherwise answer NaN).
  * @example
  * ```ts
  * const saved = localStorage.getItem('oracular');
@@ -552,8 +744,9 @@ declare function deserialize(json: string, opts?: DeserializeOptions): EngineSta
  *   strictly: unknown keys, non-finite numbers and out-of-range values throw.
  * @returns A new, JSON-serializable state. `config` is not mutated.
  * @throws `TypeError` when a value has the wrong type or a key is not recognised.
- * @throws `RangeError` when a number is out of range, for example a `prior` outside (0, 1) or a
- *   signal weight of 0.
+ * @throws `RangeError` when a number is out of range, for example a `prior` outside (0, 1), a
+ *   signal weight of 0, or a weight, `priorStrength`, `learning.gain` or
+ *   `learning.priorEpisodes` beyond 1e6 (larger values could overflow the arithmetic).
  * @example
  * ```ts
  * const state = createState({
@@ -571,4 +764,63 @@ 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 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 };
+/** The units of {@link ms}: each takes a count and returns milliseconds. */
+interface Units {
+    /** `n` seconds in milliseconds: `n × 1000`. */
+    readonly seconds: (n: number) => number;
+    /** `n` minutes in milliseconds: `n × 60 000`. */
+    readonly minutes: (n: number) => number;
+    /** `n` hours in milliseconds: `n × 3 600 000`. */
+    readonly hours: (n: number) => number;
+    /** `n` days in milliseconds: `n × 86 400 000`. */
+    readonly days: (n: number) => number;
+    /** `n` weeks in milliseconds: `n × 604 800 000`. */
+    readonly weeks: (n: number) => number;
+}
+/**
+ * Durations in milliseconds, the unit of `Date.now()`: `ms.days(7)` is `604800000`. Plain
+ * multiplications and nothing else, for `halfLife`, `cooldown`, `episodeTimeout` and
+ * `learning.halfLife` when your timestamps are in milliseconds. If your `at` is in another unit,
+ * write durations in that unit instead: the engine only needs the two to agree.
+ *
+ * @example
+ * ```ts
+ * const config = {
+ *   episodeTimeout: ms.minutes(30),
+ *   intents: {
+ *     upgrade: {
+ *       prior: 0.05,
+ *       priorStrength: 10,
+ *       halfLife: ms.days(7),
+ *       signals: { 'pricing.viewed': 3 },
+ *       reveal: { cooldown: ms.weeks(2) },
+ *     },
+ *   },
+ * };
+ * ```
+ */
+declare const ms: Units;
+
+/**
+ * Checks a config exactly as {@link createState} and {@link deserialize} do, without building a
+ * state, and returns the normalized copy they would store: only the recognised keys, in a fixed
+ * order, with every `undefined` dropped, so it survives a JSON round trip unchanged. Use it to
+ * fail fast at startup or in a test, or on a config loaded from a file, before the engine runs.
+ *
+ * @param config - The config to check. Typed `unknown` so parsed JSON can be passed as it is.
+ * @returns A fresh, normalized {@link EngineConfig}. `config` is not mutated.
+ * @throws `TypeError` when a value has the wrong type or a key is not recognised.
+ * @throws `RangeError` when a number is out of range: a `prior` outside (0, 1), a signal weight of
+ *   0, or a weight, `priorStrength`, `learning.gain` or `learning.priorEpisodes` beyond 1e6.
+ * @example
+ * ```ts
+ * import { readFileSync } from 'node:fs';
+ * import { validateConfig } from 'oracular';
+ *
+ * // Throws with the offending path in the message, e.g. config.intents["upgrade"].prior
+ * const config = validateConfig(JSON.parse(readFileSync('oracular.config.json', 'utf8')));
+ * ```
+ */
+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 };