oracular 0.9.0 → 0.11.0

package/dist/index.d.cts

@@ -629,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
@@ -824,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
@@ -863,10 +867,13 @@ declare function deserialize(json: string, opts?: DeserializeOptions): EngineSta
  * @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({
@@ -929,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';

package/dist/index.d.ts

@@ -629,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
@@ -824,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
@@ -863,10 +867,13 @@ declare function deserialize(json: string, opts?: DeserializeOptions): EngineSta
  * @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({
@@ -929,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';

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) {
@@ -77,8 +77,8 @@ function lowerBound(alpha, beta, z, bound) {
 function repeatFactor(n) {
   return Math.log1p(1 / n) / Math.LN2;
 }
-function laplace(successes, total) {
-  return (successes + 1) / (total + 2);
+function smoothRate(successes, total, rate) {
+  return (successes + 2 * rate) / (total + 2);
 }
 function lift(q, b, type = "normalized-difference") {
   if (type === "absolute-difference") return q - b;
@@ -136,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 }
   };
@@ -153,12 +152,13 @@ function signalWeights(state, intent, learning, signal) {
   }
   const record2 = getOwn(state.learned, signal) ?? NONE;
   const nWith = record2.hits + record2.misses;
-  const qWith = laplace(record2.hits, nWith);
   const totalEpisodes = state.episodes.hits + state.episodes.misses;
   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 baseline = learning.lift === "association-rule" ? (record2.hits + outcomesWithout + 2) / (nWith + nWithout + 4) : qWithout;
+  const base = totalEpisodes === 0 ? 0 : state.episodes.hits / totalEpisodes;
+  const qWith = smoothRate(record2.hits, nWith, base);
+  const qWithout = smoothRate(outcomesWithout, nWithout, base);
+  const baseline = learning.lift === "association-rule" ? smoothRate(record2.hits + outcomesWithout, nWith + nWithout, base) : 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);
@@ -250,13 +250,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 };
@@ -273,6 +272,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",
@@ -357,14 +357,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`);
   }
@@ -394,7 +397,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`);
@@ -436,11 +439,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");
@@ -451,7 +461,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 };
@@ -460,8 +471,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) {
@@ -491,12 +503,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,
@@ -534,11 +546,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 };
@@ -596,7 +604,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) {
@@ -724,6 +732,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;
@@ -733,7 +742,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 };
@@ -743,6 +753,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");
@@ -1060,7 +1080,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")
   };