oracular 0.5.2 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.7.0
+
+### Minor Changes
+
+- [#36](https://github.com/Yuribenjamin/oracular/pull/36) [`a585808`](https://github.com/Yuribenjamin/oracular/commit/a58580846d39fa14269096fa3e4f0891749eee88) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - **Inspect.** `inspect(state, at, opts?)` in the main entry returns every intent's prediction, gate and explanation as one object, in config order. `oracular/inspect` renders that snapshot: `renderInspector` as an HTML fragment with inline styles and every string escaped, `mountInspector` into anything with an `innerHTML`, with `update` and `unmount`; neither touches a DOM API or sets a timer, and neither carries engine code. The subpath is experimental, as the stability page says: its markup and options may change in a minor. The types `Snapshot` and `IntentSnapshot` are exported from the main entry.
+
+- [#36](https://github.com/Yuribenjamin/oracular/pull/36) [`a585808`](https://github.com/Yuribenjamin/oracular/commit/a58580846d39fa14269096fa3e4f0891749eee88) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - **Presets.** `oracular/presets` exports `presets`, four plain `IntentConfig` objects to spread into your config and override: `willBuy`, tuned by `oracular tune` on a public e-commerce clickstream of 2.7 million events (one shop, May to September 2015, 4.8% of sessions ending with an order; prior 0.048, strength 4, `cart.added` 2.3, half-life one hour, 181,080 sessions behind it), and `upgrade`, `stuck` and `churn`, the documentation's running examples, hand-written and labelled so. `presetSources` carries each preset's provenance as data, and the types `PresetName` and `PresetSource` are exported from the main entry.
+
+### Patch Changes
+
+- [#36](https://github.com/Yuribenjamin/oracular/pull/36) [`a585808`](https://github.com/Yuribenjamin/oracular/commit/a58580846d39fa14269096fa3e4f0891749eee88) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - **Rollback.** `deserialize` reads a state one version newer than `STATE_VERSION` as the current one, ignoring the fields it does not know, so a rollback by one release keeps every user's history. The rule that allows it, a state version bump only adds fields, is now a commitment on the new stability page, together with what counts as public API, how versions are read before 1.0, the deprecation rule, the state-format guarantee, the 1.0 criteria and their status, and a 7 kB ceiling for the core. Two versions ahead still throws the `RangeError`, and `migrate` is still consulted for it. From now on the changeset of every state version bump says what an older reader silently loses; this release bumps nothing, so a 0.6 reader loses nothing but was never able to read ahead.
+
+## 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

package/README.md

@@ -64,9 +64,21 @@ With these numbers the offer fires after roughly six strong signals across separ
 
 That block is copied verbatim into the test suite, so it always runs.
 
+## The workflow: shadow, tune, ship, learn
+
+The weights above are a guess, and the point of oracular is that you do not have to live with a guess. The intended path:
+
+1. **Start from a preset or a guess.** `oracular/presets` has `willBuy`, `upgrade`, `stuck` and `churn` as plain configs to spread and override; each says whether its numbers were fitted or written by hand.
+2. **Run in shadow mode.** The engine computes every decision and your app records it with `createRecord`, one JSON line per event, and shows nothing yet.
+3. **Tune.** `npx oracular tune shadow.ndjson --config oracular.config.json` reads what the engine itself counted across your users and prints the config to ship: the base rate as the prior, each signal's measured lift as its weight, the half-life that predicts the log best, with sample sizes and intervals. `npx oracular replay` scores any config on the same log before you commit to it.
+4. **Ship, and let it learn.** The fitted config is the population's answer; on each device the engine corrects it from that user's own outcomes.
+
+On a public clickstream of 2.7 million events, a hand-written config scored worse than always guessing the base rate, and the tuned one 10% better, with a reveal followed by an order six times as often as chance. Against the rule a skeptic would write, reveal on the third cart add, it ties for first-time visitors, as it must, and for returning ones catches 43% more orders at three points higher precision, because it has learned who fills carts without buying. The [case study](https://yuribenjamin.github.io/oracular/guide/case-study-clickstream) has every number; the [Shadow mode guide](https://yuribenjamin.github.io/oracular/guide/shadow-mode) has the workflow.
+
 ## Contents
 
 - [Why oracular](#why-oracular)
+- [The workflow: shadow, tune, ship, learn](#the-workflow-shadow-tune-ship-learn)
 - [How it works](#how-it-works)
 - [Examples](#examples)
 - [Using with React](#using-with-react)
@@ -107,7 +119,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:
 
@@ -188,12 +200,12 @@ const churn = {
 ### Ad placement
 
 ```ts
+import { presets } from 'oracular/presets';
+
+// The tuned preset (prior 0.048, strength 4, cart.added 2.3, from a real clickstream), plus your own signals.
 const willBuy = {
-  prior: 0.02,
-  priorStrength: 50,
-  halfLife: 3 * 24 * 60 * 60 * 1000,
-  signals: { 'product.viewed': 1, 'cart.added': 3, 'wishlist.added': 2, 'cart.emptied': -3 },
-  outcome: 'checkout.completed',
+  ...presets.willBuy,
+  signals: { ...presets.willBuy.signals, 'wishlist.added': 2, 'cart.emptied': -3 },
 };
 // shouldReveal(state, 'willBuy', now) → show the sponsored placement, then markRevealed.
 ```
@@ -244,6 +256,7 @@ shouldReveal(state, intent: string, at: number, opts?: RevealOptions): boolean
 markRevealed(state, intent: string, at: number): EngineState
 explain(state, intent: string, at: number, opts?: { nonZero?: boolean; limit?: number }): SignalExplanation[]
 evaluate(state, intent: string, at: number, opts?): { prediction, reveal, explanation }  // all three, one decay pass
+inspect(state, at: number, opts?): { at, intents: [{ intent, prediction, reveal, explanation }] }  // evaluate for every intent
 evidenceToReveal(intentConfig, opts?): number   // pseudo-counts at which shouldReveal first becomes true
 episodeClosed(prev, next): boolean               // did an episode close between two states?
 createRecord(state, event, { installId, mode }): EventRecord   // one recorder line: the event and what was decided
@@ -252,7 +265,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 +291,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 +351,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, {
@@ -363,6 +377,8 @@ explain(state, 'upgrade', Date.now());
 
 Rows are sorted by the size of their impact. `limit.hit` has no history yet, so its effective weight is exactly the initial one. `pricing.viewed` was followed by an upgrade in six of its seven sessions while the three sessions without it saw one upgrade, so it learned a weight above the initial 3. `export.clicked` appeared in every session: it has no counterfactual, so whatever its hit rate, its weight stands at exactly the initial 1 until a session happens without it. See [Episodes & learning](https://yuribenjamin.github.io/oracular/guide/concepts/episodes-and-learning) for why learning needs contrast.
 
+`inspect(state, now)` returns all of that for every intent as one object, and `oracular/inspect` renders it as a live, framework-free panel: `mountInspector(element, () => inspect(state, Date.now()))`, then `update()` after each `observe`. See [Inspect](https://yuribenjamin.github.io/oracular/guide/inspect).
+
 ## Shadow mode, replay and tune
 
 Run oracular silently first. Record what it decides, export the log, and measure a config offline before any reveal is shown:
@@ -382,7 +398,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. 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.
+`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; the [case study](https://yuribenjamin.github.io/oracular/guide/case-study-clickstream) runs both on a public clickstream of 2.7 million events.
 
 ## Design rules
 
@@ -390,10 +406,11 @@ npx oracular tune shadow.ndjson --config oracular.config.json
 - **Portable.** No DOM, Node or React Native specific APIs; the source compiles against the ES2020 library alone. ESM and CommonJS builds with type declarations.
 - **Private.** Nothing leaves the device because nothing *can*: there is no I/O in the library.
 - **Honest about uncertainty.** `shouldReveal` needs both a high mean and a high lower bound.
+- **Committed.** What counts as public API, how the state format may change before 1.0 and what 1.0 will promise are written down in [Stability and 1.0](https://yuribenjamin.github.io/oracular/guide/stability).
 
 ## 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).
+The 0.4 theme, **learning that matches how people behave**, is complete: 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, presets, and small ergonomics (`validateConfig`, `ms`, a JSON Schema for the config). 0.3 shipped shadow mode, `npx oracular replay` and per-episode saturation. Next is the road to 1.0, whose criteria are on [Stability and 1.0](https://yuribenjamin.github.io/oracular/guide/stability). 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

@@ -575,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;
 }
@@ -613,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);

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;
@@ -513,6 +557,14 @@ function evaluate(state, intent, at, opts) {
     explanation: buildExplanation(is, config, learning, split.explain)
   };
 }
+function inspect(state, at, opts) {
+  const s = requireState(state);
+  const intents = Object.keys(s.config.intents).map((intent) => ({
+    intent,
+    ...evaluate(s, intent, at, opts)
+  }));
+  return { at, intents };
+}
 
 // src/evidence.ts
 function evidenceToReveal(intent, opts) {
@@ -567,7 +619,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 +629,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 +653,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 +762,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 +794,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) {
@@ -771,9 +835,11 @@ function deserialize(json, opts = {}) {
   if (parsed.version !== STATE_VERSION) {
     if (canMigrate(parsed.version)) {
       stored = migrateStored(parsed);
+    } else if (parsed.version === STATE_VERSION + 1) {
+      stored = { ...parsed, version: STATE_VERSION };
     } else if (opts.migrate === void 0) {
       throw new RangeError(
-        `oracular: stored state is version ${parsed.version} but this library reads versions 1 to ${STATE_VERSION}; pass a migrate function`
+        `oracular: stored state is version ${parsed.version} but this library reads versions 1 to ${STATE_VERSION + 1}; pass a migrate function`
       );
     } else {
       stored = opts.migrate(parsed, parsed.version);
@@ -826,6 +892,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 +918,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 +987,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 +1002,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)
       );
@@ -968,6 +1058,7 @@ exports.episodeClosed = episodeClosed;
 exports.evaluate = evaluate;
 exports.evidenceToReveal = evidenceToReveal;
 exports.explain = explain;
+exports.inspect = inspect;
 exports.markRevealed = markRevealed;
 exports.ms = ms;
 exports.observe = observe;