oracular 0.6.0 → 0.7.0

package/dist/index.d.cts

@@ -2,8 +2,10 @@
  * 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, and version 2, written by 0.3.0 to 0.5.x, become version 3) and calls
- * your `migrate` function only for a version it does not know.
+ * 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
  * ```ts
@@ -337,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.5.x (versions 1 and 2) 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
@@ -360,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.5.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;
 }
@@ -456,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
@@ -480,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:
@@ -737,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.5.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
@@ -748,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
@@ -849,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 PendingEpisode, 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,8 +2,10 @@
  * 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, and version 2, written by 0.3.0 to 0.5.x, become version 3) and calls
- * your `migrate` function only for a version it does not know.
+ * 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
  * ```ts
@@ -337,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.5.x (versions 1 and 2) 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
@@ -360,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.5.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;
 }
@@ -456,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
@@ -480,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:
@@ -737,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.5.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
@@ -748,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
@@ -849,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 PendingEpisode, 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.js

@@ -555,6 +555,14 @@ function evaluate(state, intent, at, opts) {
     explanation: buildExplanation(is, config, learning, split.explain)
   };
 }
+function inspect(state, at, opts) {
+  const s = requireState(state);
+  const intents = Object.keys(s.config.intents).map((intent) => ({
+    intent,
+    ...evaluate(s, intent, at, opts)
+  }));
+  return { at, intents };
+}
 
 // src/evidence.ts
 function evidenceToReveal(intent, opts) {
@@ -825,9 +833,11 @@ function deserialize(json, opts = {}) {
   if (parsed.version !== STATE_VERSION) {
     if (canMigrate(parsed.version)) {
       stored = migrateStored(parsed);
+    } else if (parsed.version === STATE_VERSION + 1) {
+      stored = { ...parsed, version: STATE_VERSION };
     } else if (opts.migrate === void 0) {
       throw new RangeError(
-        `oracular: stored state is version ${parsed.version} but this library reads versions 1 to ${STATE_VERSION}; pass a migrate function`
+        `oracular: stored state is version ${parsed.version} but this library reads versions 1 to ${STATE_VERSION + 1}; pass a migrate function`
       );
     } else {
       stored = opts.migrate(parsed, parsed.version);
@@ -1035,6 +1045,6 @@ function validateConfig(config) {
   return normalizeConfig(config);
 }
 
-export { RECORD_VERSION, STATE_VERSION, createEndRecord, createRecord, createState, deserialize, endEpisode, episodeClosed, evaluate, evidenceToReveal, explain, markRevealed, ms, observe, predict, serialize, shouldReveal, validateConfig };
+export { RECORD_VERSION, STATE_VERSION, createEndRecord, createRecord, createState, deserialize, endEpisode, episodeClosed, evaluate, evidenceToReveal, explain, inspect, markRevealed, ms, observe, predict, serialize, shouldReveal, validateConfig };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map