oracular 0.8.1 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.10.0
+
+### Minor Changes
+
+- [#56](https://github.com/Yuribenjamin/oracular/pull/56) [`1529d8e`](https://github.com/Yuribenjamin/oracular/commit/1529d8e1568d79959afc7573ba8fa6e7f3e7ff59) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - **Configs that cannot work are refused.** `createState`, `validateConfig` and the `config` passed to `deserialize` now throw for a reveal `threshold` of 0 or 1 (`RangeError`, strictly between 0 and 1), a `z` above 10 (`RangeError`; 3.09 is already a one-sided 99.9% bound, and 128 is a misplaced 1.28), and an `outcome` that is also one of the intent's own signals while `resetOnOutcome` is on (`TypeError`: the reset wipes the evidence the signal just added; set `resetOnOutcome: false` to keep such a signal, which then reads as "did it once, will again"). The JSON Schema says the same. Per-call reveal options keep accepting 0 and 1, since a probe such as `evidenceToReveal` at those values is a legitimate question. A stored state whose config predates these checks still loads: `deserialize` reads the stored config without them and replaces it with the one you pass. An intent with no signals stays accepted; it is a prior-only gate. The presets in `oracular/presets` are now frozen through and through, so a change by one caller cannot reach every other; spread one to change a value, as the guide shows.
+  
+  **Size.** The checks, the anchor pin and the duplicate-outcome rule add about 0.2 kB: the core goes from 7.5 kB to 7.72 kB minified and gzipped, under the 7.9 kB ceiling, and the quickstart entry (`createState`, `observe`, `shouldReveal`, `markRevealed`) from 4.43 kB to 4.63 kB, past its 4.5 kB budget, which moves to 4.7 kB.
+
+- [#56](https://github.com/Yuribenjamin/oracular/pull/56) [`1529d8e`](https://github.com/Yuribenjamin/oracular/commit/1529d8e1568d79959afc7573ba8fa6e7f3e7ff59) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - **A clock that was ahead no longer freezes an intent.** A production audit found that one event stamped in the future (a device clock that was wrong for a moment) held an intent until the clock caught up: decay stopped, because the anchor kept the later time; the open episode never timed out, so learning stopped; and a reveal or outcome stamped in the future kept the gate shut until that date plus the cooldown. Every write now moves its anchor to the event's own time, even when that is earlier: the evidence is held (no decay for a backwards step, as before) and decay resumes from the new time, for `updatedAt`, the learned counts' `learnedAt` and the episode's `lastEventAt`. A reveal or outcome stamped ahead of the clock counts as having happened now: `predict` reports `suppressedUntil` one cooldown after the current time rather than years ahead, and the next event pins the stored time to its own. `markRevealed` follows the same rule and trusts the time it is given, so an earlier `at` moves the cooldown start back. What moves for a clock that only ever runs forward: nothing. What moves for one that jumps backwards: the anchor now follows it, so a log replayed with timestamps out of order decays slightly more than before. `decayFactor` of an infinite gap is now 0, not 1. An episode held under `attribution` with a close stamped in the future is left as it was.
+
+- [#56](https://github.com/Yuribenjamin/oracular/pull/56) [`1529d8e`](https://github.com/Yuribenjamin/oracular/commit/1529d8e1568d79959afc7573ba8fa6e7f3e7ff59) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - **A repeated outcome counts once.** An outcome rewards the signals seen since the episode started or since the intent's outcome last arrived, and counts the episode toward the base rate. A second outcome event with no signal seen since the first (a duplicate event, or two outcomes back to back) counted another hit episode, so a session with two outcome events inflated the base rate; it now counts nothing, and only `lastOutcomeAt` and the reset of the evidence happen again. Signals seen after an outcome in the same episode are unchanged: they earn a hit if another outcome follows them, and stay neutral at the close, since what they would predict is a second outcome in the same session, which is not what the weight is for. `tune` counts the same way. The state format is unchanged.
+
+- [#56](https://github.com/Yuribenjamin/oracular/pull/56) [`1529d8e`](https://github.com/Yuribenjamin/oracular/commit/1529d8e1568d79959afc7573ba8fa6e7f3e7ff59) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - **`tune` no longer reports a lift with nothing to compare it to.** A signal seen in every counted episode had its outcome rate compared with a smoothed rate over zero episodes, a made-up 0.5, and the report printed a lift and a 90% interval from it. For such a signal `lift`, `score`, `low` and `high` are now `null` in `--json`, and the text report prints "no contrast" in place of the interval; the weight was already left out as ubiquitous.
+
+### Patch Changes
+
+- [#56](https://github.com/Yuribenjamin/oracular/pull/56) [`1529d8e`](https://github.com/Yuribenjamin/oracular/commit/1529d8e1568d79959afc7573ba8fa6e7f3e7ff59) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - **Two CLI fixes.** `replay` and `tune` no longer refuse a whole config because one intent has a reveal cooldown of 0: that intent is scored over its half-life, the text report says so, and the `--json` reports gain `windowSource` (`option`, `cooldown` or `halfLife`) next to the existing `windowIsCooldown`. `oracular replay --version` and `oracular tune --version` (or `-v`) print the version, as the help already claimed.
+
+## 0.9.0
+
+### Minor Changes
+
+- [#52](https://github.com/Yuribenjamin/oracular/pull/52) [`e8ea457`](https://github.com/Yuribenjamin/oracular/commit/e8ea457b29edd23d0cda8446d6826ad45478b9b9) Thanks [@omaremam](https://github.com/omaremam)! - **Choosing the comparison.** `learning.lift` chooses how a signal's outcome rate is compared with its baseline: absolute difference, relative lift, risk ratio, log lift, odds ratio, normalized difference or association-rule lift. Every choice becomes a signed score in [−1, 1], with no association at zero, before it changes a weight. A risk ratio of 1 learns zero, 3 gives a score of 0.5 and 1/3 gives −0.5; `gain` caps the learned magnitude at `gain × |initial weight|` whichever comparison is set. `oracular tune` uses the same score for weights and intervals, and reports the raw measure alongside it when the two differ. Nothing moves unless the option is set: normalized difference remains the default, with exactly the same arithmetic.
+  
+  **Rollback.** A stored config that sets `lift` is read by 0.9 and later; a 0.8 reader throws a `TypeError` on the unknown key, so remove `learning.lift` from the saved config before rolling a deploy back. Passing an older config to `deserialize` alone does not avoid that check. The state version is unchanged. Existing learned counts are kept; evidence already accumulated under another comparison is not rebuilt and continues to decay or reset on outcome.
+
 ## 0.8.1
 
 ### Patch Changes

package/README.md

@@ -21,12 +21,19 @@
   · <a href="https://yuribenjamin.github.io/oracular/guide/introduction">Guide</a>
   · <a href="https://yuribenjamin.github.io/oracular/api/">API</a>
   · <a href="https://yuribenjamin.github.io/oracular/playground">Playground</a>
+  · <a href="https://yuribenjamin.github.io/oracular/guide/is-it-for-me">Is it for me?</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Yuribenjamin/oracular/main/assets/inspector.gif" width="800" alt="A pricing page next to the oracular inspector panel. Over a simulated day, each click adds a signal and p and the lower bound rise, until both clear 0.5: the gate opens, an upgrade offer appears and a cooldown starts. Eight days later the evidence has decayed back toward the prior.">
 </p>
 
 **oracular** is a tiny, zero-dependency, pure-functional intent engine that runs entirely on the device. Feed it the events your app already emits. It keeps a probabilistic estimate of what the user is about to do (upgrade, churn, get stuck, buy…) and tells you when that estimate crosses a threshold *with enough confidence* to act on it: show a tip, make an offer, reveal a feature, place an ad. It learns from each user's own outcomes, so your initial guesses get corrected on their device, not on a server.
 
 It never touches the network, storage, DOM, timers or globals. Your app owns persistence and side effects; the library owns the math.
 
+The job, concretely: your pricing page learns when to show *this* user the upgrade offer, and their events never leave their browser. On a [public clickstream of 2.7 million events](https://yuribenjamin.github.io/oracular/guide/case-study-clickstream#the-rule-a-skeptic-would-write), among the visitors who came back, the tuned engine caught 27.9% of the orders at 48.9% precision, where the best rule a skeptic would write caught 6.4% at 39.2%; for first-time visitors the two tie, as they must.
+
 ## Why oracular
 
 |                              | oracular                                              | Hosted analytics SDKs                        | Rule engines                              |
@@ -79,8 +86,8 @@ On a public clickstream of 2.7 million events, a hand-written config scored wors
 
 - [Why oracular](#why-oracular)
 - [The workflow: shadow, tune, ship, learn](#the-workflow-shadow-tune-ship-learn)
-- [How it works](#how-it-works)
 - [Examples](#examples)
+- [How it works](#how-it-works)
 - [Using with React](#using-with-react)
 - [API](#api)
 - [Persistence](#persistence)
@@ -92,66 +99,6 @@ On a public clickstream of 2.7 million events, a hand-written config scored wors
 
 The [documentation site](https://yuribenjamin.github.io/oracular/) has the long form: one page per concept, a tuning guide with tables, recipes, framework examples, the generated API reference and a playground that runs the engine in your browser.
 
-## How it works
-
-### Intents are Beta distributions
-
-You declare intents. Each has a `prior` probability and a `priorStrength` (how many observations the prior is worth). Internally an intent is a Beta(α, β) distribution with α₀ = prior × priorStrength and β₀ = (1 − prior) × priorStrength. Its current estimate is p = α / (α + β).
-
-### Signals add evidence
-
-Each intent maps event names to weights. A positive weight is evidence *for* the intent and is added to α; a negative weight is evidence *against* and its magnitude is added to β. Events the config doesn't mention cost nothing.
-
-### Repeats within a session count for less
-
-Ten views of the pricing page in one sitting are one burst of interest, not ten independent pieces of evidence. Within an episode, the n-th occurrence of a signal adds less than the first:
-
-```
-n-th occurrence adds   w × log2(1 + 1/n)     1, 0.58, 0.42, 0.32 … of the weight
-n occurrences add      w × log2(1 + n)       every doubling adds one more weight; ten add 3.46, not 10
-```
-
-The count restarts when the episode ends or the intent's outcome arrives, so the same signal in a new session counts fully again. Saturation is on by default when `episodeTimeout` is set. Without it, episodes end only when you call `endEpisode`, so repeats add their full weight unless you set `saturate: true`. For intents where the repetition itself is the evidence (a user stuck on the same step), set `saturate: false` and every occurrence adds its full weight.
-
-### Evidence decays toward the prior
-
-Before any update or reading, the evidence decays by 2^(−Δt / halfLife), where Δt is the time since the intent was last updated. Only the *excess over the prior* decays: with no events, p drifts back to `prior` and α + β back to `priorStrength`. Someone who looked at pricing a month ago is not someone who looked at pricing today.
-
-### 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**, 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:
-
-```
-nWith    = hits + misses                                      episodes with the signal
-nWithout = episodes − nWith                                   episodes without it
-qWith    = (hits + 1) / (nWith + 2)                           outcome rate with the signal
-qWithout = (outcomes − hits + 1) / (nWithout + 2)             outcome rate without it
-lift     = (qWith − qWithout) / (1 − qWithout)  if qWith ≥ qWithout,  else  (qWith − qWithout) / qWithout   → in [−1, 1]
-learned  = gain × |w₀| × lift                                 0 until the signal has history
-nEff     = (nWith × nWithout) / (nWith + nWithout)            0 if either side is 0
-effective = (k × w₀ + nEff × learned) / (k + nEff)            k = priorEpisodes
-```
-
-`w₀` is your initial weight, `gain` (default 2) caps how far a perfectly predictive signal can grow, and `priorEpisodes` (default 10) is how much contrast it takes for the user's own history to count as much as your guess. A signal's strength and your confidence in it are separate knobs. A signal is judged against the sessions in which it did *not* appear, so for an outcome that happens in 3% of sessions, a signal followed by it 30% of the time is strong evidence, not weak. And learning needs contrast: a signal that has never been absent has no counterfactual, so its weight stands until there are sessions without it. Nothing drifts after a single outcome.
-
-Learned counts never decay unless you set `learning.halfLife`.
-
-### Reveal only when confident
-
-`shouldReveal` is true when p ≥ threshold **and** p − z·sd ≥ threshold, where sd is the Beta standard deviation and z defaults to 1.28 (a one-sided 90% bound). Thin evidence with a high mean does not fire; it takes a few consistent signals. That lower bound is a normal approximation; `bound: 'exact'` swaps in the Beta distribution's own quantile at the same level, which asks for a little more on thin evidence. After you `markRevealed`, the intent stays revealed for a `cooldown` (default: its half-life) so you don't fire on every event. The same cooldown runs after the intent's outcome event. `predict` reports both: `revealed` is true inside a reveal cooldown, and `suppressedUntil` is when the later of the two cooldowns ends, or null when `shouldReveal` is free to fire.
-
-### Outcomes reset the slate and pause reveals
-
-When the outcome event arrives, the intent's evidence returns to the prior (α, β and contributions), while everything learned is kept. The user already upgraded; stop predicting that they will. Set `resetOnOutcome: false` for intents where the outcome can repeat inside one episode.
-
-The outcome also starts the intent's `cooldown`: `shouldReveal` stays false until it ends, however strong the fresh evidence, so a user who just bought is not immediately pitched again. The time of the last outcome is kept on the state as `lastOutcomeAt`.
-
-### Every answer comes with its reasons
-
-`explain` returns, per signal, how much evidence it currently holds and how much p would move without it, plus the initial, learned and effective weights and the hit/miss record. If a reveal looks wrong, you can see exactly why it fired.
-
 ## Examples
 
 The ad case is one of these, not the point of the library.
@@ -212,36 +159,93 @@ const willBuy = {
 
 More in the docs: [Recipes](https://yuribenjamin.github.io/oracular/guide/recipes) and the [Tuning guide](https://yuribenjamin.github.io/oracular/guide/tuning).
 
+## How it works
+
+### Intents are Beta distributions
+
+You declare intents. Each has a `prior` probability and a `priorStrength` (how many observations the prior is worth). Internally an intent is a Beta(α, β) distribution with α₀ = prior × priorStrength and β₀ = (1 − prior) × priorStrength. Its current estimate is p = α / (α + β).
+
+### Signals add evidence
+
+Each intent maps event names to weights. A positive weight is evidence *for* the intent and is added to α; a negative weight is evidence *against* and its magnitude is added to β. Events the config doesn't mention cost nothing.
+
+### Repeats within a session count for less
+
+Ten views of the pricing page in one sitting are one burst of interest, not ten independent pieces of evidence. Within an episode, the n-th occurrence of a signal adds less than the first:
+
+```
+n-th occurrence adds   w × log2(1 + 1/n)     1, 0.58, 0.42, 0.32 … of the weight
+n occurrences add      w × log2(1 + n)       every doubling adds one more weight; ten add 3.46, not 10
+```
+
+The count restarts when the episode ends or the intent's outcome arrives, so the same signal in a new session counts fully again. Saturation is on by default when `episodeTimeout` is set. Without it, episodes end only when you call `endEpisode`, so repeats add their full weight unless you set `saturate: true`. For intents where the repetition itself is the evidence (a user stuck on the same step), set `saturate: false` and every occurrence adds its full weight.
+
+### Evidence decays toward the prior
+
+Before any update or reading, the evidence decays by 2^(−Δt / halfLife), where Δt is the time since the intent was last updated. Only the *excess over the prior* decays: with no events, p drifts back to `prior` and α + β back to `priorStrength`. Someone who looked at pricing a month ago is not someone who looked at pricing today.
+
+### 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**, 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**. Signals seen after an outcome in the same episode count only if another outcome follows them; a repeated outcome with nothing seen since counts nothing.
+
+A signal's weight is then a blend of your prior and the learned estimate:
+
+```
+nWith    = hits + misses                                      episodes with the signal
+nWithout = episodes − nWith                                   episodes without it
+qWith    = (hits + 1) / (nWith + 2)                           outcome rate with the signal
+qWithout = (outcomes − hits + 1) / (nWithout + 2)             outcome rate without it
+lift     = (qWith − qWithout) / (1 − qWithout)  if qWith ≥ qWithout,  else  (qWith − qWithout) / qWithout   → in [−1, 1]
+learned  = gain × |w₀| × lift                                 0 until the signal has history
+nEff     = (nWith × nWithout) / (nWith + nWithout)            0 if either side is 0
+effective = (k × w₀ + nEff × learned) / (k + nEff)            k = priorEpisodes
+```
+
+`w₀` is your initial weight, `gain` (default 2) caps the learned magnitude at `gain × |w₀|` for every lift option, and `priorEpisodes` (default 10) is how much contrast it takes for the user's own history to count as much as your guess. A signal's strength and your confidence in it are separate knobs. A signal is judged against the sessions in which it did *not* appear, so for an outcome that happens in 3% of sessions, a signal followed by it 30% of the time is strong evidence, not weak. And learning needs contrast: a signal that has never been absent has no counterfactual, so its weight stands until there are sessions without it. Nothing drifts after a single outcome.
+
+The formula above is the default **normalized difference**. `learning.lift` is an optional
+setting for advanced users who want to choose the learning scale. Choose another at construction with
+`createState({ intents, learning: { lift: 'relative-lift' } })`. Omit `learning.lift` to keep the
+current behavior, including when loading older saved states. The available names and formulas
+are listed in [Episodes & learning](https://yuribenjamin.github.io/oracular/guide/concepts/episodes-and-learning#choosing-a-lift-formula).
+Every choice produces a signed evidence score in [−1, 1], with independence at zero. Ratios use
+`(R − 1) / (R + 1)`, relative/log lift use `x / (1 + |x|)`, and absolute/normalized differences
+keep their scale. Learning uses `gain × |w₀| × score`; `oracular tune` uses the same score for
+weights and intervals and reports raw lift separately when it differs from the score.
+
+Learned counts never decay unless you set `learning.halfLife`.
+
+### Reveal only when confident
+
+`shouldReveal` is true when p ≥ threshold **and** p − z·sd ≥ threshold, where sd is the Beta standard deviation and z defaults to 1.28 (a one-sided 90% bound). Thin evidence with a high mean does not fire; it takes a few consistent signals. That lower bound is a normal approximation; `bound: 'exact'` swaps in the Beta distribution's own quantile at the same level, which asks for a little more on thin evidence. After you `markRevealed`, the intent stays revealed for a `cooldown` (default: its half-life) so you don't fire on every event. The same cooldown runs after the intent's outcome event. `predict` reports both: `revealed` is true inside a reveal cooldown, and `suppressedUntil` is when the later of the two cooldowns ends, or null when `shouldReveal` is free to fire.
+
+### Outcomes reset the slate and pause reveals
+
+When the outcome event arrives, the intent's evidence returns to the prior (α, β and contributions), while everything learned is kept. The user already upgraded; stop predicting that they will. Set `resetOnOutcome: false` for intents where the outcome can repeat inside one episode.
+
+The outcome also starts the intent's `cooldown`: `shouldReveal` stays false until it ends, however strong the fresh evidence, so a user who just bought is not immediately pitched again. The time of the last outcome is kept on the state as `lastOutcomeAt`.
+
+### Every answer comes with its reasons
+
+`explain` returns, per signal, how much evidence it currently holds and how much p would move without it, plus the initial, learned and effective weights and the hit/miss record. If a reveal looks wrong, you can see exactly why it fired.
+
 ## Using with React
 
-oracular ships no framework code; this is the userland shape. Load with your current config, observe, persist on change:
+`@oracular/react` is the binding: a framework-free store, the `useIntent` hook, a provider, and adapters for `localStorage`, AsyncStorage and MMKV.
 
 ```tsx
-import { useEffect, useState } from 'react';
-import { createState, deserialize, markRevealed, observe, serialize, shouldReveal } from 'oracular';
+import { createIntentStore, localStorageAdapter, useIntent } from '@oracular/react';
 import { config } from './intent-config';
 
-function load() {
-  const saved = localStorage.getItem('oracular');
-  return saved ? deserialize(saved, { config }) : createState(config); // always pass the config you ship now
-}
-
-export function useIntent() {
-  const [state, setState] = useState(load);
-  useEffect(() => localStorage.setItem('oracular', serialize(state)), [state]);
+export const store = createIntentStore(config, { persist: localStorageAdapter() }); // once, for the app
 
-  const track = (name: string) => setState((s) => observe(s, { name, at: Date.now() }));
-  const reveal = (intent: string) => {
-    const now = Date.now();
-    if (!shouldReveal(state, intent, now)) return false;
-    setState((s) => markRevealed(s, intent, now));
-    return true;
-  };
-  return { track, reveal };
+export function Pricing() {
+  const { track, reveal } = useIntent(store);
+  return <button onClick={() => { track('pricing.viewed'); if (reveal('upgrade')) openOffer(); }}>See plans</button>;
 }
 ```
 
-Add `endEpisode` on `pagehide` and you have the whole lifecycle. The same loop for Vue, React Native and Node is on the [frameworks page](https://yuribenjamin.github.io/oracular/guide/frameworks).
+Reads go to the store's current state, so `track` then `reveal` in the same click sees the event. The hook loads the persisted state on mount, flushes the pending save when the page hides and on unmount, and never ends an episode on those events; set `episodeTimeout` and idle gaps end sessions on their own. The same loop for Vue, React Native and Node, and the hook written by hand, are on the [frameworks page](https://yuribenjamin.github.io/oracular/guide/frameworks); a runnable app is in [`examples/react-vite`](./examples/react-vite).
 
 ## API
 
@@ -277,7 +281,8 @@ interface EngineConfig {
   episodeTimeout?: number;   // idle gap that ends an episode; off if omitted
   learning?: {
     halfLife?: number;       // forgetting of learned counts; off if omitted
-    gain?: number;           // learned weight cap = gain × |initial|; default 2, at most 1e6
+    gain?: number;           // learned weight multiplier; default 2, at most 1e6
+    lift?: LiftType;         // default 'normalized-difference'; see Episodes & learning
     priorEpisodes?: number;  // pseudo-count behind your weights; default 10, at most 1e6
   };
   reveal?: RevealOptions;    // defaults for every intent
@@ -303,7 +308,7 @@ interface RevealOptions {
 }
 ```
 
-Reveal options resolve per call → intent → engine → defaults. Invalid config throws a `TypeError` or `RangeError` with the offending path in the message. `validateConfig(config)` runs those checks without building a state and returns the normalized copy `createState` stores, so a bad weight fails at startup or in a test rather than on first use. For a config kept as JSON, the package ships a [JSON Schema](./schema/config.schema.json) as `oracular/config.schema.json`, also served at <https://yuribenjamin.github.io/oracular/config.schema.json>, for editor completion; `oracular replay` ignores the `$schema` key such a file carries, the engine does not.
+Reveal options resolve per call → intent → engine → defaults. Invalid config throws a `TypeError` or `RangeError` with the offending path in the message, including a config that cannot work: a reveal `threshold` of 0 or 1, a `z` above 10, or an outcome that is also one of the intent's signals while `resetOnOutcome` is on (the reset would wipe what the signal just added; set it to `false` to keep such a signal). A stored state whose config predates these checks still loads. `validateConfig(config)` runs those checks without building a state and returns the normalized copy `createState` stores, so a bad weight fails at startup or in a test rather than on first use. For a config kept as JSON, the package ships a [JSON Schema](./schema/config.schema.json) as `oracular/config.schema.json`, also served at <https://yuribenjamin.github.io/oracular/config.schema.json>, for editor completion; `oracular replay` ignores the `$schema` key such a file carries, the engine does not.
 
 ### Results
 
@@ -334,7 +339,7 @@ interface SignalExplanation {
 
 ### Time
 
-`at` is a timestamp. Every duration (`halfLife`, `cooldown`, `episodeTimeout`, `learning.halfLife`) is in the same unit as `at`. Milliseconds from `Date.now()` are the obvious choice, but the library never calls `Date.now()` itself: you pass time in, which keeps every function deterministic and makes tests trivial. A clock that jumps backwards is tolerated (no decay, no error). When `at` is in milliseconds, `ms.days(7)`, `ms.hours(3)` and `ms.minutes(30)` spell the durations; they are plain multiplications.
+`at` is a timestamp. Every duration (`halfLife`, `cooldown`, `episodeTimeout`, `learning.halfLife`) is in the same unit as `at`. Milliseconds from `Date.now()` are the obvious choice, but the library never calls `Date.now()` itself: you pass time in, which keeps every function deterministic and makes tests trivial. A clock that jumps backwards is tolerated: the evidence is held (no decay, no error) and the anchor moves to the new time, so decay resumes from there. One event stamped ahead of the clock therefore cannot hold an intent until the clock catches up, and a reveal or outcome stamped ahead of it counts as having happened now: its cooldown runs from the current time until the next event pins it there. When `at` is in milliseconds, `ms.days(7)`, `ms.hours(3)` and `ms.minutes(30)` spell the durations; they are plain multiplications.
 
 ## Persistence
 
@@ -411,7 +416,7 @@ npx oracular tune shadow.ndjson --config oracular.config.json
 
 ## 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).
+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). `@oracular/react` ships the React binding; a Vue composable follows the same store. 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

@@ -107,6 +107,14 @@ import {
 } from "oracular";
 var DEFAULT_THRESHOLDS = [0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9];
 var DEFAULT_THRESHOLD = 0.5;
+function scoringWindow(given, cooldown, halfLife) {
+  if (given !== void 0) {
+    if (!(given > 0)) throw new RangeError("the scoring window must be greater than 0");
+    return { window: given, windowSource: "option" };
+  }
+  if (cooldown > 0) return { window: cooldown, windowSource: "cooldown" };
+  return { window: halfLife, windowSource: "halfLife" };
+}
 function replay(entries, config, options = {}) {
   const base = createState(config);
   const normalized = base.config;
@@ -135,19 +143,15 @@ function replay(entries, config, options = {}) {
     const list = options.thresholds ?? [...DEFAULT_THRESHOLDS, configured];
     const thresholds = [...new Set(list)].sort((a, b) => a - b);
     const cooldown = predict(markRevealed(base, name, 0), name, 0).suppressedUntil ?? 0;
-    const window = options.window ?? cooldown;
-    if (!(window > 0)) {
-      throw new RangeError(
-        options.window === void 0 ? `intent ${JSON.stringify(name)} has a reveal cooldown of 0, so there is no default scoring window; pass --window (for example --window 7d)` : "the scoring window must be greater than 0"
-      );
-    }
+    const { window, windowSource } = scoringWindow(options.window, cooldown, intent.halfLife);
     return {
       name,
       outcome: intent.outcome,
       configured,
       thresholds,
       window,
-      windowIsCooldown: options.window === void 0
+      windowSource,
+      windowIsCooldown: windowSource === "cooldown"
     };
   });
   const allThresholds = [...new Set(plans.flatMap((p) => p.thresholds))].sort((a, b) => a - b);
@@ -261,6 +265,7 @@ function replay(entries, config, options = {}) {
       intent: plan.name,
       outcome: plan.outcome,
       window: plan.window,
+      windowSource: plan.windowSource,
       windowIsCooldown: plan.windowIsCooldown,
       installs,
       thresholds: totals.map((s) => {
@@ -347,7 +352,7 @@ function table(headers, rows) {
 }
 function formatIntent(intent) {
   const window = formatDuration(intent.window);
-  const source = intent.windowIsCooldown ? "the intent's reveal cooldown" : "as given";
+  const source = intent.windowSource === "cooldown" ? "the intent's reveal cooldown" : intent.windowSource === "halfLife" ? "the intent's half-life, since its reveal cooldown is 0" : "as given";
   const out = [];
   out.push(
     `${intent.intent}: outcome ${intent.outcome}, window ${window} (${source}), ${intent.installs} install${intent.installs === 1 ? "" : "s"}`
@@ -432,10 +437,39 @@ import {
 function laplace(successes, total) {
   return (successes + 1) / (total + 2);
 }
-function lift(q, b) {
+function lift(q, b, type = "normalized-difference") {
+  if (type === "absolute-difference") return q - b;
+  if (type !== "normalized-difference") {
+    const rate = Math.max(Number.EPSILON, Math.min(1 - Number.EPSILON, q));
+    const base = Math.max(Number.EPSILON, Math.min(1 - Number.EPSILON, b));
+    switch (type) {
+      case "relative-lift":
+        return (rate - base) / base;
+      case "log-lift":
+        return Math.log(rate / base);
+      case "odds-ratio":
+        return rate / (1 - rate) / (base / (1 - base));
+      case "risk-ratio":
+      case "association-rule":
+        return rate / base;
+    }
+  }
   if (q >= b) return b >= 1 ? 0 : (q - b) / (1 - b);
   return b <= 0 ? 0 : (q - b) / b;
 }
+function learningScore(value, type = "normalized-difference") {
+  switch (type) {
+    case "risk-ratio":
+    case "odds-ratio":
+    case "association-rule":
+      return (value - 1) / (value + 1);
+    case "relative-lift":
+    case "log-lift":
+      return value / (1 + Math.abs(value));
+    default:
+      return value;
+  }
+}
 
 // cli/tune.ts
 var HOUR2 = 36e5;
@@ -488,7 +522,7 @@ function wilson(successes, n, z) {
   const half = z / (1 + z2 / n) * Math.sqrt(p * (1 - p) / n + z2 / (4 * n * n));
   return [Math.max(0, centre - half), Math.min(1, centre + half)];
 }
-function fitSignal(signal, current, tally, strength, priorEpisodes) {
+function fitSignal(signal, current, tally, strength, priorEpisodes, liftType) {
   const hits = own(tally.hits, signal);
   const misses = own(tally.misses, signal);
   const nWith = hits + misses;
@@ -496,10 +530,13 @@ function fitSignal(signal, current, tally, strength, priorEpisodes) {
   const outcomesWithout = Math.min(without, Math.max(0, tally.outcomes - hits));
   const qWith = laplace(hits, nWith);
   const qWithout = laplace(outcomesWithout, without);
-  const l = nWith === 0 ? 0 : lift(qWith, qWithout);
+  const baseline = liftType === "association-rule" ? (hits + outcomesWithout + 2) / (nWith + without + 4) : qWithout;
+  const noContrast = without === 0;
+  const rawLift = noContrast ? null : nWith === 0 ? 0 : lift(qWith, baseline, liftType);
+  const score = rawLift === null ? null : nWith === 0 ? 0 : learningScore(rawLift, liftType);
   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 rounded = score === null ? 0 : Math.round(strength * score * 100) / 100;
   const share = tally.episodes === 0 ? 0 : nWith / tally.episodes;
   const ubiquitous = nWith > UBIQUITY_SHARE * tally.episodes;
   return {
@@ -511,12 +548,13 @@ function fitSignal(signal, current, tally, strength, priorEpisodes) {
     outcomesWithout,
     qWith,
     qWithout,
-    lift: l,
+    lift: rawLift,
+    score,
     weight: nWith === 0 || ubiquitous || rounded === 0 ? null : rounded,
     share,
     ubiquitous,
-    low: strength * lift(qLow, qWithout),
-    high: strength * lift(qHigh, qWithout),
+    low: noContrast ? null : strength * learningScore(lift(qLow, baseline, liftType), liftType),
+    high: noContrast ? null : strength * learningScore(lift(qHigh, baseline, liftType), liftType),
     contrast,
     thin: contrast < priorEpisodes
   };
@@ -593,6 +631,7 @@ function tune(entries, config, options = {}) {
   const normalized = base.config;
   const includeLive = options.includeLive === true;
   const priorEpisodes = normalized.learning?.priorEpisodes ?? DEFAULT_PRIOR_EPISODES;
+  const liftType = normalized.learning?.lift ?? "normalized-difference";
   const skipped = [];
   const names = options.intents ?? Object.keys(normalized.intents);
   for (const name of names) {
@@ -610,13 +649,8 @@ function tune(entries, config, options = {}) {
   const grouped = groupByInstall(entries);
   const windows = /* @__PURE__ */ new Map();
   for (const name of fitting) {
-    const window = options.window ?? cooldownOf(base, name);
-    if (!(window > 0)) {
-      throw new RangeError(
-        options.window === void 0 ? `intent ${JSON.stringify(name)} has a reveal cooldown of 0, so there is no scoring window for the half-life grid; pass --window (for example --window 7d)` : "the scoring window must be greater than 0"
-      );
-    }
-    windows.set(name, window);
+    const intent = normalized.intents[name];
+    windows.set(name, scoringWindow(options.window, cooldownOf(base, name), intent.halfLife));
   }
   const eventNames = /* @__PURE__ */ new Set();
   for (const entry of entries) if (entry.kind === "event") eventNames.add(entry.name);
@@ -691,10 +725,17 @@ function tune(entries, config, options = {}) {
     const prior = laplace(tally.outcomes, tally.episodes);
     const strength = fitStrength(plan.installs, intent.priorStrength);
     const signals = Object.keys(intent.signals).map(
-      (signal) => fitSignal(signal, intent.signals[signal], tally, strength.value, priorEpisodes)
+      (signal) => fitSignal(
+        signal,
+        intent.signals[signal],
+        tally,
+        strength.value,
+        priorEpisodes,
+        liftType
+      )
     );
     const candidates = plan.candidates.map(
-      (signal) => fitSignal(signal, null, tally, strength.value, priorEpisodes)
+      (signal) => fitSignal(signal, null, tally, strength.value, priorEpisodes, liftType)
     );
     const roundedPrior = Math.round(prior * 1e4) / 1e4;
     const fittedIntent = {
@@ -705,7 +746,7 @@ function tune(entries, config, options = {}) {
         signals.filter((f) => f.weight !== null).map((f) => [f.signal, f.weight])
       )
     };
-    const window = windows.get(name);
+    const { window, windowSource } = windows.get(name);
     const threshold = intent.reveal?.threshold ?? normalized.reveal?.threshold ?? DEFAULT_THRESHOLD;
     const grid = [.../* @__PURE__ */ new Set([...options.halfLives ?? DEFAULT_HALF_LIVES, intent.halfLife])].sort(
       (a, b) => a - b
@@ -732,6 +773,7 @@ function tune(entries, config, options = {}) {
         source: "kept",
         note: "kept: no point in the log could be scored, so the grid says nothing",
         window,
+        windowSource,
         curve,
         brierBaseline
       };
@@ -749,6 +791,7 @@ function tune(entries, config, options = {}) {
           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,
+          windowSource,
           curve,
           brierBaseline
         };
@@ -759,6 +802,7 @@ function tune(entries, config, options = {}) {
           source: "grid",
           note: `lowest Brier score over the grid, ${best.toFixed(4)}${baseline}`,
           window,
+          windowSource,
           curve,
           brierBaseline
         };
@@ -816,12 +860,14 @@ function note(fit, priorEpisodes) {
   return notes.join("; ");
 }
 function signalTable(fits, priorEpisodes, withCurrent) {
+  const showScore = fits.some((fit) => fit.score !== fit.lift);
   const headers = [
     "signal",
     "weight",
     ...withCurrent ? ["was"] : [],
     "90% interval",
     "lift",
+    ...showScore ? ["score"] : [],
     "with: hits / misses",
     "without: outcomes / episodes",
     "note"
@@ -832,8 +878,9 @@ function signalTable(fits, priorEpisodes, withCurrent) {
       f.signal,
       num(f.weight, 2),
       ...withCurrent ? [num(f.current, 2)] : [],
-      `${f.low.toFixed(2)} to ${f.high.toFixed(2)}`,
-      signed(f.lift, 2),
+      f.low === null || f.high === null ? "no contrast" : `${f.low.toFixed(2)} to ${f.high.toFixed(2)}`,
+      f.lift === null ? "" : signed(f.lift, 2),
+      ...showScore ? [f.score === null ? "" : signed(f.score, 2)] : [],
       `${f.hits} / ${f.misses}`,
       `${f.outcomesWithout} / ${f.without}`,
       note(f, priorEpisodes)
@@ -880,7 +927,7 @@ 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(
+    `Half-life grid, Brier score against "the outcome follows within ${formatDuration(fit.halfLife.window)}"${fit.halfLife.windowSource === "halfLife" ? " (the intent's half-life, since its reveal cooldown is 0)" : ""} (lower is better): ${fit.halfLife.curve.map(
       (p) => `${formatDuration(p.halfLife)} ${num(p.brier, 4)}${p.halfLife === fit.halfLife.value && p.brier !== null ? " *" : ""}`
     ).join(", ")}`
   );
@@ -1009,6 +1056,7 @@ Options:
                          the signals
   --json                 print the report as JSON
   -h, --help             show this help
+  -v, --version          print the version
 
 Only shadow periods are counted by default: an episode in which any record was live is left out,
 a log with live records gets a warning, and a log with nothing but live records is refused unless
@@ -1099,16 +1147,29 @@ function commonFlags(out) {
     },
     "-h": () => {
       out.help = true;
+    },
+    "--version": (_value, noValue) => {
+      noValue();
+      out.version = true;
+    },
+    "-v": () => {
+      out.version = true;
     }
   };
 }
 function requireLogsAndConfig(out, command) {
-  if (out.help) return;
+  if (out.help || out.version) return;
   if (out.logs.length === 0) throw new UsageError(`${command} needs at least one log file`);
   if (out.config === void 0) throw new UsageError(`${command} needs --config <file>`);
 }
 function parseReplayArgs(argv) {
-  const out = { logs: [], includeLive: false, json: false, help: false };
+  const out = {
+    logs: [],
+    includeLive: false,
+    json: false,
+    help: false,
+    version: false
+  };
   parseFlags(
     argv,
     {
@@ -1128,6 +1189,7 @@ function parseTuneArgs(argv) {
     includeLive: false,
     json: false,
     help: false,
+    version: false,
     allEvents: false
   };
   parseFlags(
@@ -1221,6 +1283,11 @@ async function replayCommand(argv, io) {
     io.stdout(REPLAY_HELP);
     return 0;
   }
+  if (args.version) {
+    io.stdout(`${version()}
+`);
+    return 0;
+  }
   const config = await loadCheckedConfig(args, io);
   const entries = readLogs(args.logs, io);
   checkModes(entries, args.includeLive, io, {
@@ -1248,6 +1315,11 @@ async function tuneCommand(argv, io) {
     io.stdout(TUNE_HELP);
     return 0;
   }
+  if (args.version) {
+    io.stdout(`${version()}
+`);
+    return 0;
+  }
   const config = await loadCheckedConfig(args, io);
   const entries = readLogs(args.logs, io);
   checkModes(entries, args.includeLive, io, {