oracular 0.10.0 → 0.12.0

package/dist/index.d.cts

@@ -1,11 +1,11 @@
 /**
  * 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}
+ * when `EngineState` changes shape, 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), 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.
+ * oracular 0.1.0 to 0.2.x, version 2, written by 0.3.0 to 0.5.x, and version 3, written by 0.6.0
+ * to 0.11.x, become version 4), 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
@@ -21,7 +21,7 @@
  * });
  * ```
  */
-declare const STATE_VERSION: 3;
+declare const STATE_VERSION: 4;
 /**
  * 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
@@ -230,6 +230,20 @@ interface EpisodeState {
     lastEventAt: number | null;
     intents: Record<string, EpisodeIntentRecord>;
 }
+/**
+ * The engine's clock: the latest event time it trusts, and one event stamped behind it that is
+ * not yet confirmed as a clock correction. See `observe` for the rule.
+ */
+interface ClockState {
+    /** The latest event time trusted so far; null before the first event. */
+    at: number | null;
+    /**
+     * The stamp of the last event that arrived behind `at`, held until the next event decides: a
+     * second event behind `at` confirms the clock was corrected and every anchor ahead of this
+     * time moves back to it; an event at or after `at` makes it a glitch that changed nothing.
+     */
+    behindAt: number | null;
+}
 /**
  * The whole engine state: plain JSON with no functions, class instances or hidden fields.
  * Persist it with `serialize`, restore it with `deserialize`.
@@ -247,6 +261,7 @@ interface EngineState {
     config: EngineConfig;
     intents: Record<string, IntentState>;
     episode: EpisodeState;
+    clock: ClockState;
 }
 /**
  * What the app feeds to `observe`. Any event name is accepted; only names that appear in some
@@ -359,7 +374,7 @@ 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, nor does a state one version newer
+ * oracular 0.1.0 to 0.11.x (versions 1 to 3) never reach it, nor does a state one version newer
  * than `STATE_VERSION`: `deserialize` handles both on its own.
  *
  * @example
@@ -384,7 +399,7 @@ interface DeserializeOptions {
     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), nor the next version,
+     * itself (states from oracular 0.1.0 to 0.11.x are upgraded without it), nor the next version,
      * which it reads as its own.
      */
     migrate?: Migrate;
@@ -637,6 +652,15 @@ declare function explain(state: EngineState, intent: string, at: number, opts?:
  * or extends the current episode; an idle gap longer than `config.episodeTimeout` closes the
  * previous episode first.
  *
+ * The clock. An event at or after the latest event time moves the engine's clock there, and
+ * anything stamped ahead of it (a reveal stamped by a clock that was ahead) is pinned to it. An
+ * event stamped *behind* the clock counts now, at the clock's time, and its stamp is held: if the
+ * next event is also behind the clock, the clock was corrected, and every anchor ahead of the
+ * held stamp moves back to it so decay and cooldowns resume from the corrected time; if the next
+ * event is at or after the clock, the held stamp was one glitch and nothing moved. So one event
+ * stamped years ahead cannot hold an intent past the two events that follow it, and one stamped
+ * years behind cannot wipe the evidence or close the session.
+ *
  * @param state - The current state. Not mutated.
  * @param event - `name` is matched against every intent's signals and outcome; `at` is the
  *   event's timestamp, in the same unit as your durations; `props` are accepted and ignored,
@@ -831,7 +855,7 @@ declare function serialize(state: EngineState): string;
  * 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
+ * 0.1.0 to 0.11.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.
@@ -952,4 +976,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 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 };
+export { type ClockState, 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

@@ -1,11 +1,11 @@
 /**
  * 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}
+ * when `EngineState` changes shape, 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), 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.
+ * oracular 0.1.0 to 0.2.x, version 2, written by 0.3.0 to 0.5.x, and version 3, written by 0.6.0
+ * to 0.11.x, become version 4), 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
@@ -21,7 +21,7 @@
  * });
  * ```
  */
-declare const STATE_VERSION: 3;
+declare const STATE_VERSION: 4;
 /**
  * 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
@@ -230,6 +230,20 @@ interface EpisodeState {
     lastEventAt: number | null;
     intents: Record<string, EpisodeIntentRecord>;
 }
+/**
+ * The engine's clock: the latest event time it trusts, and one event stamped behind it that is
+ * not yet confirmed as a clock correction. See `observe` for the rule.
+ */
+interface ClockState {
+    /** The latest event time trusted so far; null before the first event. */
+    at: number | null;
+    /**
+     * The stamp of the last event that arrived behind `at`, held until the next event decides: a
+     * second event behind `at` confirms the clock was corrected and every anchor ahead of this
+     * time moves back to it; an event at or after `at` makes it a glitch that changed nothing.
+     */
+    behindAt: number | null;
+}
 /**
  * The whole engine state: plain JSON with no functions, class instances or hidden fields.
  * Persist it with `serialize`, restore it with `deserialize`.
@@ -247,6 +261,7 @@ interface EngineState {
     config: EngineConfig;
     intents: Record<string, IntentState>;
     episode: EpisodeState;
+    clock: ClockState;
 }
 /**
  * What the app feeds to `observe`. Any event name is accepted; only names that appear in some
@@ -359,7 +374,7 @@ 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, nor does a state one version newer
+ * oracular 0.1.0 to 0.11.x (versions 1 to 3) never reach it, nor does a state one version newer
  * than `STATE_VERSION`: `deserialize` handles both on its own.
  *
  * @example
@@ -384,7 +399,7 @@ interface DeserializeOptions {
     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), nor the next version,
+     * itself (states from oracular 0.1.0 to 0.11.x are upgraded without it), nor the next version,
      * which it reads as its own.
      */
     migrate?: Migrate;
@@ -637,6 +652,15 @@ declare function explain(state: EngineState, intent: string, at: number, opts?:
  * or extends the current episode; an idle gap longer than `config.episodeTimeout` closes the
  * previous episode first.
  *
+ * The clock. An event at or after the latest event time moves the engine's clock there, and
+ * anything stamped ahead of it (a reveal stamped by a clock that was ahead) is pinned to it. An
+ * event stamped *behind* the clock counts now, at the clock's time, and its stamp is held: if the
+ * next event is also behind the clock, the clock was corrected, and every anchor ahead of the
+ * held stamp moves back to it so decay and cooldowns resume from the corrected time; if the next
+ * event is at or after the clock, the held stamp was one glitch and nothing moved. So one event
+ * stamped years ahead cannot hold an intent past the two events that follow it, and one stamped
+ * years behind cannot wipe the evidence or close the session.
+ *
  * @param state - The current state. Not mutated.
  * @param event - `name` is matched against every intent's signals and outcome; `at` is the
  *   event's timestamp, in the same unit as your durations; `props` are accepted and ignored,
@@ -831,7 +855,7 @@ declare function serialize(state: EngineState): string;
  * 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
+ * 0.1.0 to 0.11.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.
@@ -952,4 +976,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 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 };
+export { type ClockState, 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

@@ -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,8 +136,9 @@ function mapRecord(record2, fn) {
 var NONE = { hits: 0, misses: 0 };
 function decayLearned(state, learning, at) {
   if (state.learnedAt === null) return { ...state, learnedAt: at };
+  if (!(at > state.learnedAt)) return state;
   const d = learning.halfLife === null ? 1 : decayFactor(at - state.learnedAt, learning.halfLife);
-  if (d === 1) return at === state.learnedAt ? state : { ...state, learnedAt: at };
+  if (d === 1) return { ...state, learnedAt: at };
   return {
     ...state,
     learnedAt: at,
@@ -152,12 +153,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);
@@ -248,8 +250,9 @@ function withContributions(state, intent, contributions) {
 }
 function decayIntent(state, intent, at) {
   if (state.updatedAt === null) return { ...state, updatedAt: at };
+  if (!(at > state.updatedAt)) return state;
   const d = decayFactor(at - state.updatedAt, intent.halfLife);
-  if (d === 1) return at === state.updatedAt ? state : { ...state, updatedAt: at };
+  if (d === 1) return { ...state, updatedAt: at };
   const contributions = mapRecord(state.contributions, (c) => ({
     alpha: c.alpha * d,
     beta: c.beta * d
@@ -567,7 +570,7 @@ function markResolved(episode, intent) {
 }
 
 // src/version.ts
-var STATE_VERSION = 3;
+var STATE_VERSION = 4;
 var RECORD_VERSION = 1;
 
 // src/state.ts
@@ -577,10 +580,16 @@ function createState(config) {
   for (const [name, intent] of Object.entries(normalized.intents)) {
     intents[name] = initIntent(intent);
   }
-  return { version: STATE_VERSION, config: normalized, intents, episode: emptyEpisode() };
+  return {
+    version: STATE_VERSION,
+    config: normalized,
+    intents,
+    episode: emptyEpisode(),
+    clock: { at: null, behindAt: null }
+  };
 }
 function requireState(state) {
-  if (!isRecord(state) || state.version !== STATE_VERSION || !isRecord(state.config) || !isRecord(state.intents) || !isRecord(state.episode)) {
+  if (!isRecord(state) || state.version !== STATE_VERSION || !isRecord(state.config) || !isRecord(state.intents) || !isRecord(state.episode) || !isRecord(state.clock)) {
     throw new TypeError("oracular: state must be an EngineState from createState or deserialize");
   }
   return state;
@@ -717,8 +726,10 @@ function explain(state, intent, at, opts) {
 
 // src/observe.ts
 function observe(state, event) {
-  let s = requireState(state);
-  const { name, at } = validateEvent(event);
+  const { name, at: stamp } = validateEvent(event);
+  const synced = syncClock(requireState(state), stamp);
+  let s = synced.state;
+  const at = synced.at;
   const closeAt = timedOutAt(s.episode, s.config.episodeTimeout, at);
   if (closeAt !== null) s = closeEpisode(s, closeAt);
   const learning = resolveLearning(s.config);
@@ -731,7 +742,6 @@ 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;
@@ -752,15 +762,36 @@ 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 syncClock(state, stamp) {
+  const { at, behindAt } = state.clock;
+  if (at === null || stamp >= at) return { state: pinTo(state, stamp), at: stamp };
+  if (behindAt !== null) return syncClock(pinTo(state, behindAt), stamp);
+  return { state: { ...state, clock: { at, behindAt: stamp } }, at };
+}
+var INTENT_ANCHORS = ["updatedAt", "learnedAt", "lastRevealedAt", "lastOutcomeAt"];
+var EPISODE_ANCHORS = ["startedAt", "lastEventAt"];
+function pinTo(state, t) {
+  let intents = state.intents;
+  for (const [name, is] of Object.entries(state.intents)) {
+    let pinned = pinKeys(is, INTENT_ANCHORS, t);
+    if (is.pending.some((p) => p.endedAt > t)) {
+      pinned = {
+        ...pinned,
+        pending: is.pending.map((p) => p.endedAt > t ? { ...p, endedAt: t } : p)
+      };
+    }
+    if (pinned !== is) intents = { ...intents, [name]: pinned };
+  }
+  const episode = pinKeys(state.episode, EPISODE_ANCHORS, t);
+  return { ...state, intents, episode, clock: { at: t, behindAt: null } };
+}
+function pinKeys(obj, keys, t) {
+  let out = obj;
+  for (const key of keys) {
+    const value = obj[key];
+    if (typeof value === "number" && value > t) out = { ...out, [key]: t };
+  }
+  return out;
 }
 function endEpisode(state, at) {
   const s = requireState(state);
@@ -886,7 +917,8 @@ function createEndRecord(at, opts) {
 // src/migrate.ts
 var MIGRATIONS = {
   1: fromV1,
-  2: fromV2
+  2: fromV2,
+  3: fromV3
 };
 function canMigrate(version) {
   return hasOwn(MIGRATIONS, String(version));
@@ -927,6 +959,9 @@ function fromV2(stored) {
   }
   return { ...stored, version: 3, intents };
 }
+function fromV3(stored) {
+  return { ...stored, version: 4, clock: { at: null, behindAt: null } };
+}
 
 // src/serialize.ts
 function serialize(state) {
@@ -1072,6 +1107,13 @@ function episodeState(value, path) {
     intents: mapOwn(r.intents, `${path}.intents`, episodeIntent)
   };
 }
+function clockState(value, path) {
+  const r = record(value, path);
+  return {
+    at: nullOrFinite(r.at, `${path}.at`),
+    behindAt: nullOrFinite(r.behindAt, `${path}.behindAt`)
+  };
+}
 function parseState(value) {
   const r = record(value, "state");
   if (r.version !== STATE_VERSION) {
@@ -1083,7 +1125,8 @@ function parseState(value) {
     // 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")
+    episode: episodeState(r.episode, "state.episode"),
+    clock: clockState(r.clock, "state.clock")
   };
 }
 function requireComputable(state) {
@@ -1157,9 +1200,24 @@ function reconcile(raw, config) {
       startedAt: raw.episode.startedAt,
       lastEventAt: raw.episode.startedAt === null ? null : raw.episode.lastEventAt,
       intents: episodeIntents
-    }
+    },
+    clock: trustedClock(raw.clock, intents, raw.episode)
   };
 }
+function trustedClock(clock, intents, episode) {
+  let at = clock.at;
+  const see = (value) => {
+    if (value !== null && (at === null || value > at)) at = value;
+  };
+  see(episode.startedAt);
+  see(episode.lastEventAt);
+  for (const is of Object.values(intents)) {
+    see(is.updatedAt);
+    see(is.lastOutcomeAt);
+  }
+  const behindAt = clock.behindAt !== null && at !== null && clock.behindAt < at ? clock.behindAt : null;
+  return at === clock.at && behindAt === clock.behindAt ? clock : { at, behindAt };
+}
 
 // src/units.ts
 var ms = {