oracular 0.8.1 → 0.10.0

package/dist/index.d.cts

@@ -62,6 +62,8 @@ interface RevealOptions {
      */
     bound?: 'normal' | 'exact';
 }
+/** The association measure converted to a signed, bounded score when learning signal weights. */
+type LiftType = 'absolute-difference' | 'relative-lift' | 'risk-ratio' | 'log-lift' | 'odds-ratio' | 'normalized-difference' | 'association-rule';
 /**
  * How the engine learns from the user's own outcomes.
  *
@@ -74,9 +76,17 @@ interface RevealOptions {
  * ```
  */
 interface LearningConfig {
+    /**
+     * Optional association measure. Every choice is converted to a score in [−1, 1], neutral at
+     * zero, before learning: ratios use (R − 1)/(R + 1), relative/log lift use x/(1 + |x|), and
+     * absolute/normalized differences keep their scale. Omit to preserve the existing normalized
+     * difference exactly. 'association-rule' uses the overall outcome rate as its baseline; the
+     * others use episodes without the signal. Raw ratios are reporting metrics, never weights.
+     */
+    lift?: LiftType;
     /** 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; at most 1e6. */
+    /** Caps learned magnitude at `gain × |initial weight|` for every lift option. 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; at most 1e6. */
     priorEpisodes?: number;
@@ -619,7 +629,9 @@ 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, credit
+ * outcome of: give the signals remembered since the episode started or the outcome last arrived a
+ * hit and count the episode toward the base rate (a repeated outcome with nothing seen since
+ * counts nothing), 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
@@ -814,7 +826,9 @@ declare function serialize(state: EngineState): string;
 /**
  * Restores a state saved with {@link serialize}.
  *
- * Always pass the app's current `config`: it is validated and replaces the stored snapshot,
+ * Always pass the app's current `config`: it is validated and replaces the stored snapshot (the
+ * stored one is read without the checks that refuse a config that cannot work, so a state saved
+ * before those checks existed still loads),
  * 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, and a state one version newer
@@ -847,15 +861,19 @@ declare function deserialize(json: string, opts?: DeserializeOptions): EngineSta
  * Builds a fresh engine state from a config. Every intent starts at its prior and no episode is
  * open. The config is validated and a normalized copy is stored inside the state, so a persisted
  * state remembers the weights it was built with; pass your current config to {@link deserialize}
- * when loading.
+ * when loading. `config.learning.lift` selects the lift formula; omitting it preserves the
+ * normalized difference used by existing configs and states.
  *
  * @param config - Intents with their priors and signals, plus engine-wide options. Validated
  *   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 `TypeError` when a value has the wrong type, a key is not recognised, or an intent's
+ *   `outcome` is also one of its signals while `resetOnOutcome` is on (the reset would wipe what
+ *   the signal just added).
  * @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).
+ *   signal weight of 0, a reveal `threshold` of 0 or 1, a `z` above 10, or a weight,
+ *   `priorStrength`, `learning.gain` or `learning.priorEpisodes` beyond 1e6 (larger values could
+ *   overflow the arithmetic).
  * @example
  * ```ts
  * const state = createState({
@@ -918,9 +936,11 @@ declare const ms: Units;
  *
  * @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 `TypeError` when a value has the wrong type, a key is not recognised, or an intent's
+ *   `outcome` is also one of its signals while `resetOnOutcome` is on.
  * @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.
+ *   0, a reveal `threshold` of 0 or 1, a `z` above 10, or a weight, `priorStrength`,
+ *   `learning.gain` or `learning.priorEpisodes` beyond 1e6.
  * @example
  * ```ts
  * import { readFileSync } from 'node:fs';
@@ -932,4 +952,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 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 };
+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 LiftType, 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

@@ -62,6 +62,8 @@ interface RevealOptions {
      */
     bound?: 'normal' | 'exact';
 }
+/** The association measure converted to a signed, bounded score when learning signal weights. */
+type LiftType = 'absolute-difference' | 'relative-lift' | 'risk-ratio' | 'log-lift' | 'odds-ratio' | 'normalized-difference' | 'association-rule';
 /**
  * How the engine learns from the user's own outcomes.
  *
@@ -74,9 +76,17 @@ interface RevealOptions {
  * ```
  */
 interface LearningConfig {
+    /**
+     * Optional association measure. Every choice is converted to a score in [−1, 1], neutral at
+     * zero, before learning: ratios use (R − 1)/(R + 1), relative/log lift use x/(1 + |x|), and
+     * absolute/normalized differences keep their scale. Omit to preserve the existing normalized
+     * difference exactly. 'association-rule' uses the overall outcome rate as its baseline; the
+     * others use episodes without the signal. Raw ratios are reporting metrics, never weights.
+     */
+    lift?: LiftType;
     /** 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; at most 1e6. */
+    /** Caps learned magnitude at `gain × |initial weight|` for every lift option. 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; at most 1e6. */
     priorEpisodes?: number;
@@ -619,7 +629,9 @@ 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, credit
+ * outcome of: give the signals remembered since the episode started or the outcome last arrived a
+ * hit and count the episode toward the base rate (a repeated outcome with nothing seen since
+ * counts nothing), 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
@@ -814,7 +826,9 @@ declare function serialize(state: EngineState): string;
 /**
  * Restores a state saved with {@link serialize}.
  *
- * Always pass the app's current `config`: it is validated and replaces the stored snapshot,
+ * Always pass the app's current `config`: it is validated and replaces the stored snapshot (the
+ * stored one is read without the checks that refuse a config that cannot work, so a state saved
+ * before those checks existed still loads),
  * 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, and a state one version newer
@@ -847,15 +861,19 @@ declare function deserialize(json: string, opts?: DeserializeOptions): EngineSta
  * Builds a fresh engine state from a config. Every intent starts at its prior and no episode is
  * open. The config is validated and a normalized copy is stored inside the state, so a persisted
  * state remembers the weights it was built with; pass your current config to {@link deserialize}
- * when loading.
+ * when loading. `config.learning.lift` selects the lift formula; omitting it preserves the
+ * normalized difference used by existing configs and states.
  *
  * @param config - Intents with their priors and signals, plus engine-wide options. Validated
  *   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 `TypeError` when a value has the wrong type, a key is not recognised, or an intent's
+ *   `outcome` is also one of its signals while `resetOnOutcome` is on (the reset would wipe what
+ *   the signal just added).
  * @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).
+ *   signal weight of 0, a reveal `threshold` of 0 or 1, a `z` above 10, or a weight,
+ *   `priorStrength`, `learning.gain` or `learning.priorEpisodes` beyond 1e6 (larger values could
+ *   overflow the arithmetic).
  * @example
  * ```ts
  * const state = createState({
@@ -918,9 +936,11 @@ declare const ms: Units;
  *
  * @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 `TypeError` when a value has the wrong type, a key is not recognised, or an intent's
+ *   `outcome` is also one of its signals while `resetOnOutcome` is on.
  * @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.
+ *   0, a reveal `threshold` of 0 or 1, a `z` above 10, or a weight, `priorStrength`,
+ *   `learning.gain` or `learning.priorEpisodes` beyond 1e6.
  * @example
  * ```ts
  * import { readFileSync } from 'node:fs';
@@ -932,4 +952,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 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 };
+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 LiftType, 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

@@ -1,6 +1,6 @@
 // src/math.ts
 function decayFactor(elapsed, halfLife) {
-  if (!(elapsed > 0) || !Number.isFinite(elapsed)) return 1;
+  if (!(elapsed > 0)) return 1;
   return 2 ** (-elapsed / halfLife);
 }
 function betaMean(alpha, beta) {
@@ -80,10 +80,39 @@ function repeatFactor(n) {
 function laplace(successes, total) {
   return (successes + 1) / (total + 2);
 }
-function lift(q, b) {
+function lift(q, b, type = "normalized-difference") {
+  if (type === "absolute-difference") return q - b;
+  if (type !== "normalized-difference") {
+    const rate = Math.max(Number.EPSILON, Math.min(1 - Number.EPSILON, q));
+    const base = Math.max(Number.EPSILON, Math.min(1 - Number.EPSILON, b));
+    switch (type) {
+      case "relative-lift":
+        return (rate - base) / base;
+      case "log-lift":
+        return Math.log(rate / base);
+      case "odds-ratio":
+        return rate / (1 - rate) / (base / (1 - base));
+      case "risk-ratio":
+      case "association-rule":
+        return rate / base;
+    }
+  }
   if (q >= b) return b >= 1 ? 0 : (q - b) / (1 - b);
   return b <= 0 ? 0 : (q - b) / b;
 }
+function learningScore(value, type = "normalized-difference") {
+  switch (type) {
+    case "risk-ratio":
+    case "odds-ratio":
+    case "association-rule":
+      return (value - 1) / (value + 1);
+    case "relative-lift":
+    case "log-lift":
+      return value / (1 + Math.abs(value));
+    default:
+      return value;
+  }
+}
 
 // src/util.ts
 function isRecord(value) {
@@ -107,12 +136,11 @@ function mapRecord(record2, fn) {
 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 };
+  if (d === 1) return at === state.learnedAt ? state : { ...state, learnedAt: at };
   return {
     ...state,
-    learnedAt,
+    learnedAt: at,
     learned: mapRecord(state.learned, (r) => ({ hits: r.hits * d, misses: r.misses * d })),
     episodes: { hits: state.episodes.hits * d, misses: state.episodes.misses * d }
   };
@@ -129,7 +157,9 @@ function signalWeights(state, intent, learning, signal) {
   const nWithout = Math.max(0, totalEpisodes - nWith);
   const outcomesWithout = Math.min(nWithout, Math.max(0, state.episodes.hits - record2.hits));
   const qWithout = laplace(outcomesWithout, nWithout);
-  const learned = nWith === 0 ? 0 : learning.gain * Math.abs(initial) * lift(qWith, qWithout);
+  const baseline = learning.lift === "association-rule" ? (record2.hits + outcomesWithout + 2) / (nWith + nWithout + 4) : qWithout;
+  const score = learningScore(lift(qWith, baseline, learning.lift), learning.lift);
+  const learned = nWith === 0 ? 0 : learning.gain * Math.abs(initial) * score;
   const nEff = nWith + nWithout === 0 ? 0 : nWith * nWithout / (nWith + nWithout);
   const k = learning.priorEpisodes;
   const effective = (k * initial + nEff * learned) / (k + nEff);
@@ -219,13 +249,12 @@ function withContributions(state, intent, 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 };
+  if (d === 1) return at === state.updatedAt ? state : { ...state, updatedAt: at };
   const contributions = mapRecord(state.contributions, (c) => ({
     alpha: c.alpha * d,
     beta: c.beta * d
   }));
-  return withContributions({ ...state, updatedAt }, intent, contributions);
+  return withContributions({ ...state, updatedAt: at }, intent, contributions);
 }
 function applySignal(state, intent, signal, weight) {
   const prev = getOwn(state.contributions, signal) ?? { alpha: 0, beta: 0 };
@@ -242,6 +271,7 @@ var DEFAULT_Z = 1.28;
 var DEFAULT_GAIN = 2;
 var DEFAULT_PRIOR_EPISODES = 10;
 var MAX_MAGNITUDE = 1e6;
+var MAX_Z = 10;
 var CONFIG_KEYS = ["intents", "episodeTimeout", "learning", "reveal"];
 var INTENT_KEYS = [
   "prior",
@@ -255,7 +285,16 @@ var INTENT_KEYS = [
   "reveal"
 ];
 var REVEAL_KEYS = ["threshold", "z", "cooldown", "bound"];
-var LEARNING_KEYS = ["halfLife", "gain", "priorEpisodes"];
+var LEARNING_KEYS = ["halfLife", "gain", "priorEpisodes", "lift"];
+var LIFT_TYPES = [
+  "absolute-difference",
+  "relative-lift",
+  "risk-ratio",
+  "log-lift",
+  "odds-ratio",
+  "normalized-difference",
+  "association-rule"
+];
 var EXPLAIN_KEYS = ["nonZero", "limit"];
 function typeError(path, message) {
   throw new TypeError(`oracular: ${path} ${message}`);
@@ -317,14 +356,17 @@ function expectKeyName(name, path) {
   if (name === "__proto__") typeError(path, 'must not use the reserved name "__proto__"');
   return name;
 }
-function normalizeRevealOptions(value, path) {
+function normalizeRevealOptions(value, path, strict = true) {
   const record2 = expectRecord(value, path);
   expectKeys(record2, REVEAL_KEYS, path);
   const out = {};
   if (record2.threshold !== void 0) {
-    out.threshold = expectClosedUnit(record2.threshold, `${path}.threshold`);
+    out.threshold = strict ? expectOpenUnit(record2.threshold, `${path}.threshold`) : expectClosedUnit(record2.threshold, `${path}.threshold`);
+  }
+  if (record2.z !== void 0) {
+    out.z = expectNonNegative(record2.z, `${path}.z`);
+    if (strict && out.z > MAX_Z) rangeError(`${path}.z`, `must be at most ${MAX_Z}`);
   }
-  if (record2.z !== void 0) out.z = expectNonNegative(record2.z, `${path}.z`);
   if (record2.cooldown !== void 0) {
     out.cooldown = expectNonNegative(record2.cooldown, `${path}.cooldown`);
   }
@@ -340,6 +382,12 @@ function normalizeLearning(value, path) {
   const record2 = expectRecord(value, path);
   expectKeys(record2, LEARNING_KEYS, path);
   const out = {};
+  if (record2.lift !== void 0) {
+    if (!LIFT_TYPES.includes(record2.lift)) {
+      typeError(`${path}.lift`, `must be one of: ${LIFT_TYPES.join(", ")}`);
+    }
+    out.lift = record2.lift;
+  }
   if (record2.halfLife !== void 0)
     out.halfLife = expectPositive(record2.halfLife, `${path}.halfLife`);
   if (record2.gain !== void 0) out.gain = expectBoundedPositive(record2.gain, `${path}.gain`);
@@ -348,7 +396,7 @@ function normalizeLearning(value, path) {
   }
   return out;
 }
-function normalizeIntentConfig(value, path) {
+function normalizeIntentConfig(value, path, strict = true) {
   const record2 = expectRecord(value, path);
   expectKeys(record2, INTENT_KEYS, path);
   const signalsRecord = expectRecord(record2.signals, `${path}.signals`);
@@ -390,11 +438,18 @@ function normalizeIntentConfig(value, path) {
   if (record2.attribution !== void 0) {
     out.attribution = expectPositive(record2.attribution, `${path}.attribution`);
   }
-  if (record2.reveal !== void 0)
-    out.reveal = normalizeRevealOptions(record2.reveal, `${path}.reveal`);
+  if (record2.reveal !== void 0) {
+    out.reveal = normalizeRevealOptions(record2.reveal, `${path}.reveal`, strict);
+  }
+  if (strict && out.outcome !== void 0 && hasOwn(signals, out.outcome) && out.resetOnOutcome !== false) {
+    typeError(
+      `${path}.outcome`,
+      "is also one of its signals: the reset on outcome would wipe what it adds; set resetOnOutcome: false to keep it"
+    );
+  }
   return out;
 }
-function normalizeConfig(value) {
+function normalizeConfig(value, strict = true) {
   const record2 = expectRecord(value, "config");
   expectKeys(record2, CONFIG_KEYS, "config");
   const intentsRecord = expectRecord(record2.intents, "config.intents");
@@ -405,7 +460,8 @@ function normalizeConfig(value) {
     expectKeyName(name, "config.intents");
     intents[name] = normalizeIntentConfig(
       intentsRecord[name],
-      `config.intents[${JSON.stringify(name)}]`
+      `config.intents[${JSON.stringify(name)}]`,
+      strict
     );
   }
   const out = { intents };
@@ -414,8 +470,9 @@ function normalizeConfig(value) {
   }
   if (record2.learning !== void 0)
     out.learning = normalizeLearning(record2.learning, "config.learning");
-  if (record2.reveal !== void 0)
-    out.reveal = normalizeRevealOptions(record2.reveal, "config.reveal");
+  if (record2.reveal !== void 0) {
+    out.reveal = normalizeRevealOptions(record2.reveal, "config.reveal", strict);
+  }
   return out;
 }
 function normalizeExplainOptions(value, path) {
@@ -445,12 +502,12 @@ function splitEvaluateOptions(value, path) {
     else explain2[key] = v;
   }
   return {
-    reveal: normalizeRevealOptions(reveal, path),
+    reveal: normalizeRevealOptions(reveal, path, false),
     explain: normalizeExplainOptions(explain2, path)
   };
 }
 function resolveReveal(config, intent, opts, normalized = false) {
-  const o = opts === void 0 ? {} : normalized ? opts : normalizeRevealOptions(opts, "options");
+  const o = opts === void 0 ? {} : normalized ? opts : normalizeRevealOptions(opts, "options", false);
   return {
     threshold: o.threshold ?? intent.reveal?.threshold ?? config?.reveal?.threshold ?? DEFAULT_THRESHOLD,
     z: o.z ?? intent.reveal?.z ?? config?.reveal?.z ?? DEFAULT_Z,
@@ -460,6 +517,7 @@ function resolveReveal(config, intent, opts, normalized = false) {
 }
 function resolveLearning(config) {
   return {
+    lift: config.learning?.lift ?? "normalized-difference",
     halfLife: config.learning?.halfLife ?? null,
     gain: config.learning?.gain ?? DEFAULT_GAIN,
     priorEpisodes: config.learning?.priorEpisodes ?? DEFAULT_PRIOR_EPISODES
@@ -487,11 +545,7 @@ function timedOutAt(episode, timeout, at) {
   return at - episode.lastEventAt > timeout ? episode.lastEventAt + timeout : null;
 }
 function extendEpisode(episode, at) {
-  return {
-    startedAt: episode.startedAt ?? at,
-    lastEventAt: episode.lastEventAt === null ? at : Math.max(episode.lastEventAt, at),
-    intents: episode.intents
-  };
+  return { startedAt: episode.startedAt ?? at, lastEventAt: at, intents: episode.intents };
 }
 function episodeRecord(episode, intent) {
   return getOwn(episode.intents, intent) ?? { seen: [], counts: {}, resolved: false };
@@ -549,7 +603,7 @@ function assessIntent(state, name, intent, learning, at) {
 }
 function cooldownEnd(since, cooldown, at) {
   if (since === null) return null;
-  const end = since + cooldown;
+  const end = Math.min(since, at) + cooldown;
   return at < end ? end : null;
 }
 function buildPrediction(is, name, reveal, at) {
@@ -677,6 +731,7 @@ function observe(state, event) {
     let is = getIntentState(s, intentName, intent);
     is = decayIntent(is, intent, at);
     is = settlePending(is, intent, learning, at);
+    is = pinAnchors(is, at);
     if (isSignal) {
       const { effective } = signalWeights(is, intent, learning, name);
       const n = occurrences(episode, intentName, name) + 1;
@@ -686,7 +741,8 @@ function observe(state, event) {
       if (!isOutcome) episode = markSeen(episode, intentName, name);
     }
     if (isOutcome) {
-      is = recordEpisode(is, episodeRecord(episode, intentName).seen, 1);
+      const record2 = episodeRecord(episode, intentName);
+      if (!record2.resolved || record2.seen.length > 0) is = recordEpisode(is, record2.seen, 1);
       is = creditPending(is, intent, at);
       episode = markResolved(episode, intentName);
       is = { ...is, lastOutcomeAt: at };
@@ -696,6 +752,16 @@ function observe(state, event) {
   }
   return { ...s, intents, episode };
 }
+function pinAnchors(is, at) {
+  const reveal = is.lastRevealedAt !== null && is.lastRevealedAt > at;
+  const outcome = is.lastOutcomeAt !== null && is.lastOutcomeAt > at;
+  if (!reveal && !outcome) return is;
+  return {
+    ...is,
+    lastRevealedAt: reveal ? at : is.lastRevealedAt,
+    lastOutcomeAt: outcome ? at : is.lastOutcomeAt
+  };
+}
 function endEpisode(state, at) {
   const s = requireState(state);
   const t = expectTimestamp(at, "at");
@@ -1013,7 +1079,9 @@ function parseState(value) {
   }
   return {
     version: STATE_VERSION,
-    config: normalizeConfig(r.config),
+    // Without the strict checks: a config this release would refuse at createState still loads
+    // when it is only stored, and the config passed in replaces it anyway.
+    config: normalizeConfig(r.config, false),
     intents: mapOwn(r.intents, "state.intents", intentState),
     episode: episodeState(r.episode, "state.episode")
   };