oracular 0.5.1 → 0.6.0

package/dist/index.d.cts

@@ -2,8 +2,8 @@
  * 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.
+ * 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.
  *
  * @example
  * ```ts
@@ -19,7 +19,7 @@
  * });
  * ```
  */
-declare const STATE_VERSION: 2;
+declare const STATE_VERSION: 3;
 /**
  * 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
@@ -112,6 +112,17 @@ interface IntentConfig {
      * weight.
      */
     saturate?: boolean;
+    /**
+     * How long a closed episode's signals wait for the outcome before they take a miss, in the same
+     * unit as `at`. With it set, an episode that ends without the outcome is held instead of
+     * counted. When the outcome arrives inside the window, each held episode gets a share
+     * `2^(−age / halfLife)` of a hit and the rest of a miss, with `age` measured from the episode's
+     * close: the sessions that built up to the outcome are credited by how much of their evidence
+     * still stands. When the window passes, the episode is a miss, recorded at the moment the window
+     * ended. Unset: an episode that ends without the outcome is a miss at once. A natural first value
+     * is the intent's `halfLife`, where the smallest share inside the window is one half.
+     */
+    attribution?: number;
     /** Reveal defaults for this intent. */
     reveal?: RevealOptions;
 }
@@ -143,11 +154,18 @@ interface SignalContribution {
 }
 /** What this user's history says about one signal. Decays with `learning.halfLife`. */
 interface SignalRecord {
-    /** Episodes in which the signal was followed by the outcome. */
+    /** Episodes in which the signal was followed by the outcome. An episode credited by a later outcome under `attribution` adds its share here and the rest to `misses`. */
     hits: number;
     /** Episodes in which it was not. */
     misses: number;
 }
+/** A closed episode waiting for the intent's outcome inside its `attribution` window. */
+interface PendingEpisode {
+    /** When the episode closed. Its wait ends `attribution` later. */
+    endedAt: number;
+    /** The signals seen in it, each once. */
+    seen: string[];
+}
 /**
  * Everything the engine knows about one intent for this user. Plain data; read it for debugging
  * or dashboards, but change it only through the engine's functions.
@@ -163,6 +181,11 @@ interface IntentState {
     learned: Record<string, SignalRecord>;
     /** Episodes that ended with (`hits`) or without (`misses`) the outcome: the base rate. */
     episodes: SignalRecord;
+    /**
+     * Closed episodes whose verdict waits for the outcome (see {@link IntentConfig.attribution}),
+     * in order of close, at most 32. Empty unless `attribution` is set.
+     */
+    pending: PendingEpisode[];
     /** Time `learned` and `episodes` were last decayed to. */
     learnedAt: number | null;
     lastRevealedAt: number | null;
@@ -314,7 +337,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.2.x (version 1) never reach it: `deserialize` upgrades those on its own.
+ * oracular 0.1.0 to 0.5.x (versions 1 and 2) never reach it: `deserialize` upgrades those on its own.
  *
  * @example
  * ```ts
@@ -338,7 +361,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.2.x are upgraded without it).
+     * itself (states from oracular 0.1.0 to 0.5.x are upgraded without it).
      */
     migrate?: Migrate;
 }
@@ -517,10 +540,11 @@ 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, 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.
+ * outcome of: give the remembered signals a hit, count the episode toward the base rate, 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
+ * 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
@@ -540,7 +564,8 @@ declare function explain(state: EngineState, intent: string, at: number, opts?:
 declare function observe(state: EngineState, event: IntentEvent): EngineState;
 /**
  * Ends the current episode at `at`. Every intent whose outcome did not arrive gives a miss to
- * each signal seen this episode and counts the episode toward its base rate. Call it when a
+ * each signal seen this episode and counts the episode toward its base rate, or, with
+ * `IntentConfig.attribution` set, holds the episode for the outcome instead. Call it when a
  * session ends: tab closed, app backgrounded, user signed out.
  *
  * @param state - The current state. Not mutated.
@@ -562,7 +587,8 @@ declare function endEpisode(state: EngineState, at: number): EngineState;
  * Whether an episode closed between two states: `prev` had an open episode and `next` either
  * has none or has a different one. Useful after `observe` or `endEpisode` to react to a
  * session ending, for example to persist, or to read the misses it produced as
- * `next.intents[x].episodes.misses - prev.intents[x].episodes.misses`.
+ * `next.intents[x].episodes.misses - prev.intents[x].episodes.misses` (0 for an intent with
+ * `attribution` set, whose verdict waits).
  *
  * @param prev - The state before the operation.
  * @param next - The state after it.
@@ -711,7 +737,7 @@ 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.2.x are upgraded to the current shape on their own; `migrate` is only for a version
+ * 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.
  *
  * @param json - A string produced by {@link serialize}.
@@ -823,4 +849,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 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 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 };

package/dist/index.d.ts

@@ -2,8 +2,8 @@
  * 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.
+ * 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.
  *
  * @example
  * ```ts
@@ -19,7 +19,7 @@
  * });
  * ```
  */
-declare const STATE_VERSION: 2;
+declare const STATE_VERSION: 3;
 /**
  * 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
@@ -112,6 +112,17 @@ interface IntentConfig {
      * weight.
      */
     saturate?: boolean;
+    /**
+     * How long a closed episode's signals wait for the outcome before they take a miss, in the same
+     * unit as `at`. With it set, an episode that ends without the outcome is held instead of
+     * counted. When the outcome arrives inside the window, each held episode gets a share
+     * `2^(−age / halfLife)` of a hit and the rest of a miss, with `age` measured from the episode's
+     * close: the sessions that built up to the outcome are credited by how much of their evidence
+     * still stands. When the window passes, the episode is a miss, recorded at the moment the window
+     * ended. Unset: an episode that ends without the outcome is a miss at once. A natural first value
+     * is the intent's `halfLife`, where the smallest share inside the window is one half.
+     */
+    attribution?: number;
     /** Reveal defaults for this intent. */
     reveal?: RevealOptions;
 }
@@ -143,11 +154,18 @@ interface SignalContribution {
 }
 /** What this user's history says about one signal. Decays with `learning.halfLife`. */
 interface SignalRecord {
-    /** Episodes in which the signal was followed by the outcome. */
+    /** Episodes in which the signal was followed by the outcome. An episode credited by a later outcome under `attribution` adds its share here and the rest to `misses`. */
     hits: number;
     /** Episodes in which it was not. */
     misses: number;
 }
+/** A closed episode waiting for the intent's outcome inside its `attribution` window. */
+interface PendingEpisode {
+    /** When the episode closed. Its wait ends `attribution` later. */
+    endedAt: number;
+    /** The signals seen in it, each once. */
+    seen: string[];
+}
 /**
  * Everything the engine knows about one intent for this user. Plain data; read it for debugging
  * or dashboards, but change it only through the engine's functions.
@@ -163,6 +181,11 @@ interface IntentState {
     learned: Record<string, SignalRecord>;
     /** Episodes that ended with (`hits`) or without (`misses`) the outcome: the base rate. */
     episodes: SignalRecord;
+    /**
+     * Closed episodes whose verdict waits for the outcome (see {@link IntentConfig.attribution}),
+     * in order of close, at most 32. Empty unless `attribution` is set.
+     */
+    pending: PendingEpisode[];
     /** Time `learned` and `episodes` were last decayed to. */
     learnedAt: number | null;
     lastRevealedAt: number | null;
@@ -314,7 +337,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.2.x (version 1) never reach it: `deserialize` upgrades those on its own.
+ * oracular 0.1.0 to 0.5.x (versions 1 and 2) never reach it: `deserialize` upgrades those on its own.
  *
  * @example
  * ```ts
@@ -338,7 +361,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.2.x are upgraded without it).
+     * itself (states from oracular 0.1.0 to 0.5.x are upgraded without it).
      */
     migrate?: Migrate;
 }
@@ -517,10 +540,11 @@ 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, 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.
+ * outcome of: give the remembered signals a hit, count the episode toward the base rate, 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
+ * 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
@@ -540,7 +564,8 @@ declare function explain(state: EngineState, intent: string, at: number, opts?:
 declare function observe(state: EngineState, event: IntentEvent): EngineState;
 /**
  * Ends the current episode at `at`. Every intent whose outcome did not arrive gives a miss to
- * each signal seen this episode and counts the episode toward its base rate. Call it when a
+ * each signal seen this episode and counts the episode toward its base rate, or, with
+ * `IntentConfig.attribution` set, holds the episode for the outcome instead. Call it when a
  * session ends: tab closed, app backgrounded, user signed out.
  *
  * @param state - The current state. Not mutated.
@@ -562,7 +587,8 @@ declare function endEpisode(state: EngineState, at: number): EngineState;
  * Whether an episode closed between two states: `prev` had an open episode and `next` either
  * has none or has a different one. Useful after `observe` or `endEpisode` to react to a
  * session ending, for example to persist, or to read the misses it produced as
- * `next.intents[x].episodes.misses - prev.intents[x].episodes.misses`.
+ * `next.intents[x].episodes.misses - prev.intents[x].episodes.misses` (0 for an intent with
+ * `attribution` set, whose verdict waits).
  *
  * @param prev - The state before the operation.
  * @param next - The state after it.
@@ -711,7 +737,7 @@ 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.2.x are upgraded to the current shape on their own; `migrate` is only for a version
+ * 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.
  *
  * @param json - A string produced by {@link serialize}.
@@ -823,4 +849,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 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 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 };

package/dist/index.js

@@ -47,6 +47,86 @@ function mapRecord(record2, fn) {
   return out;
 }
 
+// src/learning.ts
+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 };
+  return {
+    ...state,
+    learnedAt,
+    learned: mapRecord(state.learned, (r) => ({ hits: r.hits * d, misses: r.misses * d })),
+    episodes: { hits: state.episodes.hits * d, misses: state.episodes.misses * d }
+  };
+}
+function signalWeights(state, intent, learning, signal) {
+  const initial = getOwn(intent.signals, signal);
+  if (initial === void 0) {
+    throw new RangeError(`oracular: ${JSON.stringify(signal)} is not a signal of this intent`);
+  }
+  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 learned = nWith === 0 ? 0 : learning.gain * Math.abs(initial) * lift(qWith, qWithout);
+  const nEff = nWith + nWithout === 0 ? 0 : nWith * nWithout / (nWith + nWithout);
+  const k = learning.priorEpisodes;
+  const effective = (k * initial + nEff * learned) / (k + nEff);
+  return { initial, learned, effective, hits: record2.hits, misses: record2.misses };
+}
+function recordEpisode(state, signals, credit) {
+  const miss = 1 - credit;
+  const learned = { ...state.learned };
+  for (const signal of signals) {
+    const r = getOwn(learned, signal) ?? NONE;
+    learned[signal] = { hits: r.hits + credit, misses: r.misses + miss };
+  }
+  const episodes = { hits: state.episodes.hits + credit, misses: state.episodes.misses + miss };
+  return { ...state, learned, episodes };
+}
+
+// src/attribution.ts
+var MAX_PENDING = 32;
+function expiry(episode, intent) {
+  return episode.endedAt + (intent.attribution ?? 0);
+}
+function settlePending(state, intent, learning, at) {
+  let is = state;
+  let settled = 0;
+  for (const episode of state.pending) {
+    const end = expiry(episode, intent);
+    if (!(end < at)) break;
+    is = recordEpisode(decayLearned(is, learning, end), episode.seen, 0);
+    settled++;
+  }
+  if (settled > 0) is = { ...is, pending: state.pending.slice(settled) };
+  return decayLearned(is, learning, at);
+}
+function deferEpisode(state, seen, endedAt) {
+  const pending = insert(state.pending, { endedAt, seen: [...seen] });
+  if (pending.length <= MAX_PENDING) return { ...state, pending };
+  const [oldest, ...rest] = pending;
+  return { ...recordEpisode(state, oldest.seen, 0), pending: rest };
+}
+function insert(pending, episode) {
+  let i = pending.length;
+  while (i > 0 && pending[i - 1].endedAt > episode.endedAt) i--;
+  return [...pending.slice(0, i), episode, ...pending.slice(i)];
+}
+function creditPending(state, intent, at) {
+  if (state.pending.length === 0) return state;
+  let is = state;
+  for (const episode of state.pending) {
+    is = recordEpisode(is, episode.seen, decayFactor(at - episode.endedAt, intent.halfLife));
+  }
+  return { ...is, pending: [] };
+}
+
 // src/intent.ts
 function priorCounts(intent) {
   return {
@@ -63,6 +143,7 @@ function initIntent(intent) {
     contributions: {},
     learned: {},
     episodes: { hits: 0, misses: 0 },
+    pending: [],
     learnedAt: null,
     lastRevealedAt: null,
     lastOutcomeAt: null,
@@ -99,48 +180,6 @@ function resetToPrior(state, intent) {
   return withContributions(state, intent, {});
 }
 
-// src/learning.ts
-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 };
-  return {
-    ...state,
-    learnedAt,
-    learned: mapRecord(state.learned, (r) => ({ hits: r.hits * d, misses: r.misses * d })),
-    episodes: { hits: state.episodes.hits * d, misses: state.episodes.misses * d }
-  };
-}
-function signalWeights(state, intent, learning, signal) {
-  const initial = getOwn(intent.signals, signal);
-  if (initial === void 0) {
-    throw new RangeError(`oracular: ${JSON.stringify(signal)} is not a signal of this intent`);
-  }
-  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 learned = nWith === 0 ? 0 : learning.gain * Math.abs(initial) * lift(qWith, qWithout);
-  const nEff = nWith + nWithout === 0 ? 0 : nWith * nWithout / (nWith + nWithout);
-  const k = learning.priorEpisodes;
-  const effective = (k * initial + nEff * learned) / (k + nEff);
-  return { initial, learned, effective, hits: record2.hits, misses: record2.misses };
-}
-function recordEpisode(state, signals, outcome) {
-  const learned = { ...state.learned };
-  for (const signal of signals) {
-    const r = getOwn(learned, signal) ?? NONE;
-    learned[signal] = outcome ? { hits: r.hits + 1, misses: r.misses } : { hits: r.hits, misses: r.misses + 1 };
-  }
-  const episodes = outcome ? { hits: state.episodes.hits + 1, misses: state.episodes.misses } : { hits: state.episodes.hits, misses: state.episodes.misses + 1 };
-  return { ...state, learned, episodes };
-}
-
 // src/config.ts
 var DEFAULT_THRESHOLD = 0.5;
 var DEFAULT_Z = 1.28;
@@ -156,6 +195,7 @@ var INTENT_KEYS = [
   "outcome",
   "resetOnOutcome",
   "saturate",
+  "attribution",
   "reveal"
 ];
 var REVEAL_KEYS = ["threshold", "z", "cooldown"];
@@ -285,6 +325,9 @@ function normalizeIntentConfig(value, path) {
     if (typeof record2.saturate !== "boolean") typeError(`${path}.saturate`, "must be a boolean");
     out.saturate = record2.saturate;
   }
+  if (record2.attribution !== void 0) {
+    out.attribution = expectPositive(record2.attribution, `${path}.attribution`);
+  }
   if (record2.reveal !== void 0)
     out.reveal = normalizeRevealOptions(record2.reveal, `${path}.reveal`);
   return out;
@@ -407,7 +450,7 @@ function markResolved(episode, intent) {
 }
 
 // src/version.ts
-var STATE_VERSION = 2;
+var STATE_VERSION = 3;
 var RECORD_VERSION = 1;
 
 // src/state.ts
@@ -438,7 +481,8 @@ function getIntentState(state, name, intent) {
 
 // src/assess.ts
 function assessIntent(state, name, intent, learning, at) {
-  return decayLearned(decayIntent(getIntentState(state, name, intent), intent, at), learning, at);
+  const is = decayIntent(getIntentState(state, name, intent), intent, at);
+  return settlePending(is, intent, learning, at);
 }
 function cooldownEnd(since, cooldown, at) {
   if (since === null) return null;
@@ -565,7 +609,7 @@ function observe(state, event) {
     if (!isSignal && !isOutcome) continue;
     let is = getIntentState(s, intentName, intent);
     is = decayIntent(is, intent, at);
-    is = decayLearned(is, learning, at);
+    is = settlePending(is, intent, learning, at);
     if (isSignal) {
       const { effective } = signalWeights(is, intent, learning, name);
       const n = occurrences(episode, intentName, name) + 1;
@@ -575,7 +619,8 @@ function observe(state, event) {
       if (!isOutcome) episode = markSeen(episode, intentName, name);
     }
     if (isOutcome) {
-      is = recordEpisode(is, episodeRecord(episode, intentName).seen, true);
+      is = recordEpisode(is, episodeRecord(episode, intentName).seen, 1);
+      is = creditPending(is, intent, at);
       episode = markResolved(episode, intentName);
       is = { ...is, lastOutcomeAt: at };
       if (intent.resetOnOutcome ?? true) is = resetToPrior(is, intent);
@@ -598,8 +643,8 @@ function closeEpisode(state, at) {
     const record2 = episodeRecord(state.episode, intentName);
     if (record2.resolved) continue;
     let is = getIntentState(state, intentName, intent);
-    is = decayLearned(is, learning, at);
-    is = recordEpisode(is, record2.seen, false);
+    is = settlePending(is, intent, learning, at);
+    is = intent.attribution === void 0 ? recordEpisode(is, record2.seen, 0) : deferEpisode(is, record2.seen, at);
     intents[intentName] = is;
   }
   return { ...state, intents, episode: emptyEpisode() };
@@ -707,7 +752,8 @@ function createEndRecord(at, opts) {
 
 // src/migrate.ts
 var MIGRATIONS = {
-  1: fromV1
+  1: fromV1,
+  2: fromV2
 };
 function canMigrate(version) {
   return hasOwn(MIGRATIONS, String(version));
@@ -738,6 +784,16 @@ function fromV1(stored) {
   }
   return { ...stored, version: 2, episode: { ...episode, intents } };
 }
+function fromV2(stored) {
+  if (!isRecord(stored.intents)) return { ...stored, version: 3 };
+  const intents = {};
+  for (const key of Object.keys(stored.intents)) {
+    if (key === "__proto__") continue;
+    const intent = stored.intents[key];
+    intents[key] = isRecord(intent) ? { ...intent, pending: [] } : intent;
+  }
+  return { ...stored, version: 3, intents };
+}
 
 // src/serialize.ts
 function serialize(state) {
@@ -824,6 +880,19 @@ function mapOwn(value, path, fn) {
   }
   return out;
 }
+function pendingEpisodes(value, path) {
+  if (!Array.isArray(value)) typeError2(path, "must be an array");
+  if (value.length > MAX_PENDING) {
+    throw new RangeError(`oracular: ${path} must hold at most ${MAX_PENDING} episodes`);
+  }
+  return value.map((item, i) => {
+    const r = record(item, `${path}[${i}]`);
+    if (!Array.isArray(r.seen) || !r.seen.every((s) => typeof s === "string")) {
+      typeError2(`${path}[${i}].seen`, "must be an array of strings");
+    }
+    return { endedAt: finite(r.endedAt, `${path}[${i}].endedAt`), seen: r.seen };
+  });
+}
 function intentState(value, path) {
   const r = record(value, path);
   const revealCount = finite(r.revealCount, `${path}.revealCount`);
@@ -837,6 +906,7 @@ function intentState(value, path) {
     contributions: mapOwn(r.contributions, `${path}.contributions`, contribution),
     learned: mapOwn(r.learned, `${path}.learned`, signalRecord),
     episodes: signalRecord(r.episodes, `${path}.episodes`),
+    pending: pendingEpisodes(r.pending, `${path}.pending`),
     learnedAt: nullOrFinite(r.learnedAt, `${path}.learnedAt`),
     lastRevealedAt: nullOrFinite(r.lastRevealedAt, `${path}.lastRevealedAt`),
     lastOutcomeAt: nullOrFinite(r.lastOutcomeAt, `${path}.lastOutcomeAt`),
@@ -905,6 +975,12 @@ function keep(source, declared) {
   }
   return out;
 }
+function keepPending(pending, signals) {
+  return pending.map((episode) => ({
+    endedAt: episode.endedAt,
+    seen: episode.seen.filter((s, i) => hasOwn(signals, s) && episode.seen.indexOf(s) === i)
+  })).sort((a, b) => a.endedAt - b.endedAt);
+}
 function reconcile(raw, config) {
   const intents = {};
   const episodeIntents = {};
@@ -914,7 +990,11 @@ function reconcile(raw, config) {
       intents[name] = initIntent(intent);
     } else {
       intents[name] = withContributions(
-        { ...stored, learned: keep(stored.learned, intent.signals) },
+        {
+          ...stored,
+          learned: keep(stored.learned, intent.signals),
+          pending: keepPending(stored.pending, intent.signals)
+        },
         intent,
         keep(stored.contributions, intent.signals)
       );