oracular 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.6.0
+
+### Minor Changes
+
+- [#32](https://github.com/Yuribenjamin/oracular/pull/32) [`6951d70`](https://github.com/Yuribenjamin/oracular/commit/6951d70b4ff1e654ab17a61357d882fd82240968) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - **Cross-episode attribution.** `IntentConfig.attribution` is how long a closed episode's signals wait for the outcome before they take a miss. Until now a signal earned a hit only when the outcome arrived in the same episode, so for an intent that builds over days the sessions that built it took misses and the session where the user acted got all the credit. With a window set, an episode that ends without the outcome is held instead of counted; when the outcome arrives inside the window, each held episode gets the share `2^(−age / halfLife)` of a hit that its evidence still holds, and the rest of a miss, so every episode still counts exactly once and the contrast that learning rests on is unchanged; when the window passes, the episode is a miss recorded at the moment the window ended. Reads settle what has expired in what they show and store nothing. Off unless set: every state and estimate without `attribution` is exactly what it was.
+  
+  **State version 3.** `IntentState.pending` lists the episodes waiting, at most 32 per intent (past that the oldest is a miss at once). `deserialize` upgrades version 1 and 2 states on its own, adding an empty list and changing no number; oracular 0.5.x cannot read a version 3 state, so the rollback advice stays: catch and start from `createState(config)`. `PendingEpisode` is exported as a type; the config JSON Schema gains `attribution`.
+  
+  `oracular tune` counts each episode's own verdict, with the window off while counting, keeps it on for the half-life grid, and keeps whatever `attribution` you set in the printed config.
+
+## 0.5.2
+
+### Patch Changes
+
+- [#30](https://github.com/Yuribenjamin/oracular/pull/30) [`8be17e0`](https://github.com/Yuribenjamin/oracular/commit/8be17e032bb1b7886ce1d7278701555c39bb03cf) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - `oracular tune` learned three rules from a public e-commerce clickstream of 2.7 million events. A signal seen in more than 90% of counted episodes is left out of the fitted config, whatever its lift: it cannot tell episodes apart, and the few episodes without it are rarely typical sessions, so the contrast measured on them says little (on that log, `item.viewed` sat in 99% of sessions and the contrast called it strongly negative; dropping it scored better than any weight). The current half-life is kept when the best grid point improves on it by less than 1%, and the grid is printed to four decimals so a flat grid reads as flat. The report says when the fitted intent still does not beat its own base rate. The JSON report gains `share` and `ubiquitous` per signal and `beatsBaseRate` per intent.
+
 ## 0.5.1
 
 ### Patch Changes

package/README.md

@@ -107,7 +107,7 @@ Before any update or reading, the evidence decays by 2^(−Δt / halfLife), wher
 
 ### The user's history corrects your weights
 
-Events happen inside **episodes** (sessions). An episode ends when you call `endEpisode`, or on its own after `episodeTimeout` of inactivity. Signals seen in the episode are remembered per intent. When the intent's `outcome` event arrives, each remembered signal gets a **hit**; when the episode ends without it, each gets a **miss**. The engine also counts, per intent, how many episodes ended with and without the outcome: the intent's **base rate**.
+Events happen inside **episodes** (sessions). An episode ends when you call `endEpisode`, or on its own after `episodeTimeout` of inactivity. Signals seen in the episode are remembered per intent. When the intent's `outcome` event arrives, each remembered signal gets a **hit**; when the episode ends without it, each gets a **miss**, or, with `attribution` set on the intent, the episode waits and takes the share `2^(−age / halfLife)` of a hit if the outcome arrives inside the window. The engine also counts, per intent, how many episodes ended with and without the outcome: the intent's **base rate**.
 
 A signal's weight is then a blend of your prior and the learned estimate:
 
@@ -252,7 +252,7 @@ serialize(state): string
 deserialize(json: string, opts?: { config?: EngineConfig; migrate?: Migrate }): EngineState
 validateConfig(config: unknown): EngineConfig   // the checks createState runs, without a state; returns the normalized copy
 ms.seconds(n), ms.minutes(n), ms.hours(n), ms.days(n), ms.weeks(n)   // durations in milliseconds
-STATE_VERSION // 2
+STATE_VERSION // 3
 RECORD_VERSION // 1
 ```
 
@@ -278,6 +278,7 @@ interface IntentConfig {
   outcome?: string;                 // event that confirms the intent
   resetOnOutcome?: boolean;         // default true
   saturate?: boolean;               // repeats within an episode add less; default: episodeTimeout is set
+  attribution?: number;             // how long a closed episode waits for the outcome before it is a miss; off if omitted
   reveal?: RevealOptions;
 }
 
@@ -337,7 +338,7 @@ const state = deserialize(saved, { config });
 
 The new config is validated and swapped in. Intents and signals you no longer declare are dropped (α and β are recomputed from what remains), newly declared intents start at their prior, and everything learned about signals that still exist is kept.
 
-States saved by an older version of this library are upgraded on load: `deserialize` migrates the state shape written by oracular 0.1.0 to 0.2.x (`STATE_VERSION` 1) to the current one on its own. A `migrate` function is consulted only for a version the library does not know, such as a state written by a newer oracular before a rollback; without one, that throws a `RangeError`:
+States saved by an older version of this library are upgraded on load: `deserialize` migrates the state shapes written by oracular 0.1.0 to 0.5.x (`STATE_VERSION` 1 and 2) to the current one on its own. A `migrate` function is consulted only for a version the library does not know, such as a state written by a newer oracular before a rollback; without one, that throws a `RangeError`:
 
 ```ts
 deserialize(saved, {
@@ -382,7 +383,7 @@ npx oracular replay shadow.ndjson --config oracular.config.json
 npx oracular tune shadow.ndjson --config oracular.config.json
 ```
 
-`tune` seeds a config from the same log: grouped by install, the base rate becomes the prior, the spread of per-install base rates the prior strength, each signal's lift over the episodes without it its weight, and the half-life that predicts the log best wins a grid search scored by `replay`. The counts come from the engine itself, so tune cannot disagree with what a device would learn. It prints sample sizes and a 90% interval per weight, and the config to paste; the engine corrects it per user from there. The [Shadow mode guide](https://yuribenjamin.github.io/oracular/guide/shadow-mode) has the workflow, the record format and both commands.
+`tune` seeds a config from the same log: grouped by install, the base rate becomes the prior, the spread of per-install base rates the prior strength, each signal's lift over the episodes without it its weight, and the half-life that predicts the log best wins a grid search scored by `replay`. The counts come from the engine itself, so tune cannot disagree with what a device would learn. It prints sample sizes and a 90% interval per weight, and the config to paste; the engine corrects it per user from there. Three rules learned from a real clickstream keep it honest: a signal seen in nearly every episode is left out, a flat grid keeps your half-life, and the report says when an intent still does not beat its base rate. The [Shadow mode guide](https://yuribenjamin.github.io/oracular/guide/shadow-mode) has the workflow, the record format and both commands.
 
 ## Design rules
 
@@ -393,7 +394,7 @@ npx oracular tune shadow.ndjson --config oracular.config.json
 
 ## Roadmap
 
-Now is 0.4, themed **learning that matches how people behave**: cross-episode attribution, so a session's signals can earn credit for an outcome days later, and presets. Shipped so far: `npx oracular tune` to seed a config from a shadow log, and small ergonomics (`validateConfig`, `ms`, a JSON Schema for the config). 0.3 shipped shadow mode, `npx oracular replay` and per-episode saturation. Then a written stability policy before 1.0. Framework bindings wait for a third integration. The full list, with the reasoning and what was declined, is on the [roadmap page](https://yuribenjamin.github.io/oracular/guide/roadmap).
+Now is 0.4, themed **learning that matches how people behave**. Shipped so far: cross-episode attribution (`attribution` on an intent, so a session's signals earn a share of an outcome days later), `npx oracular tune` to seed a config from a shadow log, and small ergonomics (`validateConfig`, `ms`, a JSON Schema for the config). Presets come once tune has run on more real logs. 0.3 shipped shadow mode, `npx oracular replay` and per-episode saturation. Then a written stability policy before 1.0. Framework bindings wait for a third integration. The full list, with the reasoning and what was declined, is on the [roadmap page](https://yuribenjamin.github.io/oracular/guide/roadmap).
 
 ## Contributing
 

package/dist/cli.js

@@ -444,6 +444,8 @@ var DEFAULT_HALF_LIVES = [HOUR2, 6 * HOUR2, DAY2, 3 * DAY2, 7 * DAY2, 14 * DAY2,
 var DEFAULT_PRIOR_EPISODES = 10;
 var MIN_INSTALLS_FOR_SPREAD = 10;
 var STRENGTH_RANGE = [2, 50];
+var UBIQUITY_SHARE = 0.9;
+var FLAT_GRID_GAIN = 0.01;
 var Z90 = 1.6449;
 var NONE = { hits: 0, misses: 0 };
 function stepDelta(prev, next) {
@@ -498,6 +500,8 @@ function fitSignal(signal, current, tally, strength, priorEpisodes) {
   const contrast = nWith + without === 0 ? 0 : nWith * without / (nWith + without);
   const [qLow, qHigh] = wilson(hits, nWith, Z90);
   const rounded = Math.round(strength * l * 100) / 100;
+  const share = tally.episodes === 0 ? 0 : nWith / tally.episodes;
+  const ubiquitous = nWith > UBIQUITY_SHARE * tally.episodes;
   return {
     signal,
     current,
@@ -508,7 +512,9 @@ function fitSignal(signal, current, tally, strength, priorEpisodes) {
     qWith,
     qWithout,
     lift: l,
-    weight: nWith === 0 || rounded === 0 ? null : rounded,
+    weight: nWith === 0 || ubiquitous || rounded === 0 ? null : rounded,
+    share,
+    ubiquitous,
     low: strength * lift(qLow, qWithout),
     high: strength * lift(qHigh, qWithout),
     contrast,
@@ -569,6 +575,16 @@ function withoutLearnedDecay(config) {
   );
   return { ...config, learning };
 }
+function withoutAttribution(config) {
+  const intents = Object.fromEntries(
+    Object.entries(config.intents).map(([name, intent]) => {
+      if (intent.attribution === void 0) return [name, intent];
+      const { attribution: _attribution, ...rest } = intent;
+      return [name, rest];
+    })
+  );
+  return { ...config, intents };
+}
 function cooldownOf(base, name) {
   return predict2(markRevealed2(base, name, 0), name, 0).suppressedUntil ?? 0;
 }
@@ -607,7 +623,7 @@ function tune(entries, config, options = {}) {
   const candidatesOf = (intent) => options.allEvents === true ? [...eventNames].filter(
     (name) => name !== "__proto__" && name !== intent.outcome && !Object.hasOwn(intent.signals, name)
   ) : [];
-  let countConfig = withoutLearnedDecay(normalized);
+  let countConfig = withoutAttribution(withoutLearnedDecay(normalized));
   const plans = fitting.map((name) => {
     const intent = normalized.intents[name];
     const candidates = candidatesOf(intent);
@@ -707,6 +723,7 @@ function tune(entries, config, options = {}) {
       return { halfLife: halfLife2, brier: scored?.brier ?? null, points: scored?.points ?? 0 };
     });
     const scoredPoints = curve.filter((p) => p.brier !== null);
+    const atCurrent = curve.find((p) => p.halfLife === intent.halfLife);
     let halfLife;
     if (scoredPoints.length === 0) {
       halfLife = {
@@ -723,17 +740,33 @@ function tune(entries, config, options = {}) {
       const ties = scoredPoints.filter((p) => p.brier - best <= 1e-12);
       const nearest = (p) => Math.abs(Math.log(p.halfLife / intent.halfLife));
       const chosen = ties.reduce((a, b) => nearest(b) < nearest(a) ? b : a);
-      halfLife = {
-        value: chosen.halfLife,
-        current: intent.halfLife,
-        source: "grid",
-        note: `lowest Brier score over the grid, ${best.toFixed(3)}${brierBaseline === null ? "" : ` (always predicting the base rate: ${brierBaseline.toFixed(3)})`}`,
-        window,
-        curve,
-        brierBaseline
-      };
+      const baseline = brierBaseline === null ? "" : ` (always predicting the base rate: ${brierBaseline.toFixed(4)})`;
+      const gain = atCurrent.brier === null || atCurrent.brier <= 0 ? Number.POSITIVE_INFINITY : (atCurrent.brier - best) / atCurrent.brier;
+      if (chosen.halfLife !== intent.halfLife && gain < FLAT_GRID_GAIN) {
+        halfLife = {
+          value: intent.halfLife,
+          current: intent.halfLife,
+          source: "kept",
+          note: `kept: the grid is flat, the best point (${formatDuration(chosen.halfLife)}, ${best.toFixed(4)}) improves on the current value (${atCurrent.brier.toFixed(4)}) by ${(gain * 100).toFixed(2)}%, less than ${FLAT_GRID_GAIN * 100}%${baseline}`,
+          window,
+          curve,
+          brierBaseline
+        };
+      } else {
+        halfLife = {
+          value: chosen.halfLife,
+          current: intent.halfLife,
+          source: "grid",
+          note: `lowest Brier score over the grid, ${best.toFixed(4)}${baseline}`,
+          window,
+          curve,
+          brierBaseline
+        };
+      }
     }
     fitted = withIntent(fitted, name, { ...fittedIntent, halfLife: halfLife.value });
+    const scoredAt = curve.find((p) => p.halfLife === halfLife.value);
+    const beatsBaseRate = scoredAt.brier === null || brierBaseline === null ? null : scoredAt.brier < brierBaseline;
     intents.push({
       intent: name,
       outcome: intent.outcome,
@@ -745,6 +778,7 @@ function tune(entries, config, options = {}) {
       priorStrength: strength,
       halfLife,
       priorEpisodes,
+      beatsBaseRate,
       signals,
       candidates
     });
@@ -771,7 +805,13 @@ var plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
 function note(fit, priorEpisodes) {
   if (fit.hits + fit.misses === 0) return "never seen in a counted episode";
   const notes = [];
-  if (fit.weight === null) notes.push("no measurable lift, left out of the config");
+  if (fit.ubiquitous) {
+    notes.push(
+      `in ${(fit.share * 100).toFixed(1)}% of episodes, so it cannot tell them apart; left out of the config`
+    );
+  } else if (fit.weight === null) {
+    notes.push("no measurable lift, left out of the config");
+  }
   if (fit.thin) notes.push(`thin: ${fit.contrast.toFixed(1)} of ${priorEpisodes} contrast`);
   return notes.join("; ");
 }
@@ -841,9 +881,18 @@ function formatIntent2(fit) {
   out.push("");
   out.push(
     `Half-life grid, Brier score against "the outcome follows within ${formatDuration(fit.halfLife.window)}" (lower is better): ${fit.halfLife.curve.map(
-      (p) => `${formatDuration(p.halfLife)} ${num(p.brier, 3)}${p.halfLife === fit.halfLife.value && fit.halfLife.source === "grid" ? " *" : ""}`
+      (p) => `${formatDuration(p.halfLife)} ${num(p.brier, 4)}${p.halfLife === fit.halfLife.value && p.brier !== null ? " *" : ""}`
     ).join(", ")}`
   );
+  if (fit.beatsBaseRate === false) {
+    const scored = fit.halfLife.curve.find((p) => p.halfLife === fit.halfLife.value);
+    const window = formatDuration(fit.halfLife.window);
+    const why = fit.signals.some((f) => f.weight !== null) ? `Its signals do not separate the events that ${fit.outcome} follows within ${window} from the rest.` : `No signal is left in the config, so p never leaves the prior, and the prior (the share of episodes that end with ${fit.outcome}) is not the share of events that ${fit.outcome} follows within ${window}.`;
+    out.push("");
+    out.push(
+      `This intent does not beat its base rate: the fitted config scores ${num(scored?.brier ?? null, 4)} where always predicting the base rate scores ${num(fit.halfLife.brierBaseline, 4)} (lower is better). ${why} Drop the intent, or find signals that tell its episodes apart (--all-events measures every other event in the log).`
+    );
+  }
   if (fit.candidates.length > 0) {
     out.push("");
     out.push(

package/dist/index.cjs

@@ -49,6 +49,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 {
@@ -65,6 +145,7 @@ function initIntent(intent) {
     contributions: {},
     learned: {},
     episodes: { hits: 0, misses: 0 },
+    pending: [],
     learnedAt: null,
     lastRevealedAt: null,
     lastOutcomeAt: null,
@@ -101,48 +182,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;
@@ -158,6 +197,7 @@ var INTENT_KEYS = [
   "outcome",
   "resetOnOutcome",
   "saturate",
+  "attribution",
   "reveal"
 ];
 var REVEAL_KEYS = ["threshold", "z", "cooldown"];
@@ -287,6 +327,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;
@@ -409,7 +452,7 @@ function markResolved(episode, intent) {
 }
 
 // src/version.ts
-var STATE_VERSION = 2;
+var STATE_VERSION = 3;
 var RECORD_VERSION = 1;
 
 // src/state.ts
@@ -440,7 +483,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;
@@ -567,7 +611,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;
@@ -577,7 +621,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);
@@ -600,8 +645,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() };
@@ -709,7 +754,8 @@ function createEndRecord(at, opts) {
 
 // src/migrate.ts
 var MIGRATIONS = {
-  1: fromV1
+  1: fromV1,
+  2: fromV2
 };
 function canMigrate(version) {
   return hasOwn(MIGRATIONS, String(version));
@@ -740,6 +786,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) {
@@ -826,6 +882,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`);
@@ -839,6 +908,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`),
@@ -907,6 +977,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 = {};
@@ -916,7 +992,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)
       );