oracular 0.9.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.11.0
+
+### Minor Changes
+
+- [#58](https://github.com/Yuribenjamin/oracular/pull/58) [`d6d1e87`](https://github.com/Yuribenjamin/oracular/commit/d6d1e87e176fc0112384e47fb4782e12d6fa1d1a) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - **Learning no longer drifts without outcomes.** The outcome rates a signal is judged by, with it and without it, were Laplace-smoothed, which centres both on 0.5 with one pseudo-hit each: two groups with no outcome at all then differ only by their sizes, so with zero outcomes a common signal drifted negative and a rare one positive, and a weight could change sign on no evidence (a weight of 2 seen in 90 of 100 outcome-free episodes ended at −0.59). Both rates are now shrunk toward the intent's own base rate by two pseudo-episodes, `(hits + 2·q₀) / (n + 2)` with `q₀ = outcomes / episodes`: a signal whose outcome rate equals the base rate learns exactly zero whatever the sample sizes, with no outcome every rate is 0 and no weight moves away from the developer's, and a weight never changes sign without outcomes on at least one side. The association-rule baseline becomes the base rate itself. `tune` fits with the same smoothing, so its weights, intervals and lifts move a little on small samples (a signal seen once with the outcome over a low base rate is worth a little less than before); on large samples the change is in the third decimal. Every learned number in the documentation's generated tables was regenerated. The state format is unchanged, and existing learned counts are kept: only the weight read from them moves.
+
+## 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

package/README.md

@@ -186,15 +186,16 @@ 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**, 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**.
+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
+q₀       = outcomes / episodes                                the intent's own base rate
+qWith    = (hits + 2·q₀) / (nWith + 2)                        outcome rate with the signal
+qWithout = (outcomes − hits + 2·q₀) / (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
@@ -308,7 +309,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
 
@@ -339,7 +340,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
 

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,6 +437,9 @@ import {
 function laplace(successes, total) {
   return (successes + 1) / (total + 2);
 }
+function smoothRate(successes, total, rate) {
+  return (successes + 2 * rate) / (total + 2);
+}
 function lift(q, b, type = "normalized-difference") {
   if (type === "absolute-difference") return q - b;
   if (type !== "normalized-difference") {
@@ -523,14 +531,16 @@ function fitSignal(signal, current, tally, strength, priorEpisodes, liftType) {
   const nWith = hits + misses;
   const without = Math.max(0, tally.episodes - nWith);
   const outcomesWithout = Math.min(without, Math.max(0, tally.outcomes - hits));
-  const qWith = laplace(hits, nWith);
-  const qWithout = laplace(outcomesWithout, without);
-  const baseline = liftType === "association-rule" ? (hits + outcomesWithout + 2) / (nWith + without + 4) : qWithout;
-  const rawLift = nWith === 0 ? 0 : lift(qWith, baseline, liftType);
-  const score = nWith === 0 ? 0 : learningScore(rawLift, liftType);
+  const base = tally.episodes === 0 ? 0 : tally.outcomes / tally.episodes;
+  const qWith = smoothRate(hits, nWith, base);
+  const qWithout = smoothRate(outcomesWithout, without, base);
+  const baseline = liftType === "association-rule" ? smoothRate(hits + outcomesWithout, nWith + without, base) : 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 * score * 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 {
@@ -547,8 +557,8 @@ function fitSignal(signal, current, tally, strength, priorEpisodes, liftType) {
     weight: nWith === 0 || ubiquitous || rounded === 0 ? null : rounded,
     share,
     ubiquitous,
-    low: strength * learningScore(lift(qLow, baseline, liftType), liftType),
-    high: strength * learningScore(lift(qHigh, baseline, liftType), liftType),
+    low: noContrast ? null : strength * learningScore(lift(qLow, baseline, liftType), liftType),
+    high: noContrast ? null : strength * learningScore(lift(qHigh, baseline, liftType), liftType),
     contrast,
     thin: contrast < priorEpisodes
   };
@@ -643,13 +653,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);
@@ -745,7 +750,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
@@ -772,6 +777,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
       };
@@ -789,6 +795,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
         };
@@ -799,6 +806,7 @@ function tune(entries, config, options = {}) {
           source: "grid",
           note: `lowest Brier score over the grid, ${best.toFixed(4)}${baseline}`,
           window,
+          windowSource,
           curve,
           brierBaseline
         };
@@ -874,9 +882,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),
-      ...showScore ? [signed(f.score, 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)
@@ -923,7 +931,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(", ")}`
   );
@@ -1052,6 +1060,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
@@ -1142,16 +1151,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,
     {
@@ -1171,6 +1193,7 @@ function parseTuneArgs(argv) {
     includeLive: false,
     json: false,
     help: false,
+    version: false,
     allEvents: false
   };
   parseFlags(
@@ -1264,6 +1287,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, {
@@ -1291,6 +1319,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, {

package/dist/index.cjs

@@ -2,7 +2,7 @@
 
 // src/math.ts
 function decayFactor(elapsed, halfLife) {
-  if (!(elapsed > 0) || !Number.isFinite(elapsed)) return 1;
+  if (!(elapsed > 0)) return 1;
   return 2 ** (-elapsed / halfLife);
 }
 function betaMean(alpha, beta) {
@@ -79,8 +79,8 @@ function lowerBound(alpha, beta, z, bound) {
 function repeatFactor(n) {
   return Math.log1p(1 / n) / Math.LN2;
 }
-function laplace(successes, total) {
-  return (successes + 1) / (total + 2);
+function smoothRate(successes, total, rate) {
+  return (successes + 2 * rate) / (total + 2);
 }
 function lift(q, b, type = "normalized-difference") {
   if (type === "absolute-difference") return q - b;
@@ -138,12 +138,11 @@ function mapRecord(record2, fn) {
 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 };
+  if (d === 1) return at === state.learnedAt ? state : { ...state, learnedAt: at };
   return {
     ...state,
-    learnedAt,
+    learnedAt: at,
     learned: mapRecord(state.learned, (r) => ({ hits: r.hits * d, misses: r.misses * d })),
     episodes: { hits: state.episodes.hits * d, misses: state.episodes.misses * d }
   };
@@ -155,12 +154,13 @@ function signalWeights(state, intent, learning, signal) {
   }
   const record2 = getOwn(state.learned, signal) ?? NONE;
   const nWith = record2.hits + record2.misses;
-  const qWith = laplace(record2.hits, nWith);
   const totalEpisodes = state.episodes.hits + state.episodes.misses;
   const nWithout = Math.max(0, totalEpisodes - nWith);
   const outcomesWithout = Math.min(nWithout, Math.max(0, state.episodes.hits - record2.hits));
-  const qWithout = laplace(outcomesWithout, nWithout);
-  const baseline = learning.lift === "association-rule" ? (record2.hits + outcomesWithout + 2) / (nWith + nWithout + 4) : qWithout;
+  const base = totalEpisodes === 0 ? 0 : state.episodes.hits / totalEpisodes;
+  const qWith = smoothRate(record2.hits, nWith, base);
+  const qWithout = smoothRate(outcomesWithout, nWithout, base);
+  const baseline = learning.lift === "association-rule" ? smoothRate(record2.hits + outcomesWithout, nWith + nWithout, base) : qWithout;
   const score = learningScore(lift(qWith, baseline, learning.lift), learning.lift);
   const learned = nWith === 0 ? 0 : learning.gain * Math.abs(initial) * score;
   const nEff = nWith + nWithout === 0 ? 0 : nWith * nWithout / (nWith + nWithout);
@@ -252,13 +252,12 @@ function withContributions(state, intent, contributions) {
 function decayIntent(state, intent, at) {
   if (state.updatedAt === null) return { ...state, updatedAt: at };
   const d = decayFactor(at - state.updatedAt, intent.halfLife);
-  const updatedAt = Math.max(state.updatedAt, at);
-  if (d === 1) return updatedAt === state.updatedAt ? state : { ...state, updatedAt };
+  if (d === 1) return at === state.updatedAt ? state : { ...state, updatedAt: at };
   const contributions = mapRecord(state.contributions, (c) => ({
     alpha: c.alpha * d,
     beta: c.beta * d
   }));
-  return withContributions({ ...state, updatedAt }, intent, contributions);
+  return withContributions({ ...state, updatedAt: at }, intent, contributions);
 }
 function applySignal(state, intent, signal, weight) {
   const prev = getOwn(state.contributions, signal) ?? { alpha: 0, beta: 0 };
@@ -275,6 +274,7 @@ var DEFAULT_Z = 1.28;
 var DEFAULT_GAIN = 2;
 var DEFAULT_PRIOR_EPISODES = 10;
 var MAX_MAGNITUDE = 1e6;
+var MAX_Z = 10;
 var CONFIG_KEYS = ["intents", "episodeTimeout", "learning", "reveal"];
 var INTENT_KEYS = [
   "prior",
@@ -359,14 +359,17 @@ function expectKeyName(name, path) {
   if (name === "__proto__") typeError(path, 'must not use the reserved name "__proto__"');
   return name;
 }
-function normalizeRevealOptions(value, path) {
+function normalizeRevealOptions(value, path, strict = true) {
   const record2 = expectRecord(value, path);
   expectKeys(record2, REVEAL_KEYS, path);
   const out = {};
   if (record2.threshold !== void 0) {
-    out.threshold = expectClosedUnit(record2.threshold, `${path}.threshold`);
+    out.threshold = strict ? expectOpenUnit(record2.threshold, `${path}.threshold`) : expectClosedUnit(record2.threshold, `${path}.threshold`);
+  }
+  if (record2.z !== void 0) {
+    out.z = expectNonNegative(record2.z, `${path}.z`);
+    if (strict && out.z > MAX_Z) rangeError(`${path}.z`, `must be at most ${MAX_Z}`);
   }
-  if (record2.z !== void 0) out.z = expectNonNegative(record2.z, `${path}.z`);
   if (record2.cooldown !== void 0) {
     out.cooldown = expectNonNegative(record2.cooldown, `${path}.cooldown`);
   }
@@ -396,7 +399,7 @@ function normalizeLearning(value, path) {
   }
   return out;
 }
-function normalizeIntentConfig(value, path) {
+function normalizeIntentConfig(value, path, strict = true) {
   const record2 = expectRecord(value, path);
   expectKeys(record2, INTENT_KEYS, path);
   const signalsRecord = expectRecord(record2.signals, `${path}.signals`);
@@ -438,11 +441,18 @@ function normalizeIntentConfig(value, path) {
   if (record2.attribution !== void 0) {
     out.attribution = expectPositive(record2.attribution, `${path}.attribution`);
   }
-  if (record2.reveal !== void 0)
-    out.reveal = normalizeRevealOptions(record2.reveal, `${path}.reveal`);
+  if (record2.reveal !== void 0) {
+    out.reveal = normalizeRevealOptions(record2.reveal, `${path}.reveal`, strict);
+  }
+  if (strict && out.outcome !== void 0 && hasOwn(signals, out.outcome) && out.resetOnOutcome !== false) {
+    typeError(
+      `${path}.outcome`,
+      "is also one of its signals: the reset on outcome would wipe what it adds; set resetOnOutcome: false to keep it"
+    );
+  }
   return out;
 }
-function normalizeConfig(value) {
+function normalizeConfig(value, strict = true) {
   const record2 = expectRecord(value, "config");
   expectKeys(record2, CONFIG_KEYS, "config");
   const intentsRecord = expectRecord(record2.intents, "config.intents");
@@ -453,7 +463,8 @@ function normalizeConfig(value) {
     expectKeyName(name, "config.intents");
     intents[name] = normalizeIntentConfig(
       intentsRecord[name],
-      `config.intents[${JSON.stringify(name)}]`
+      `config.intents[${JSON.stringify(name)}]`,
+      strict
     );
   }
   const out = { intents };
@@ -462,8 +473,9 @@ function normalizeConfig(value) {
   }
   if (record2.learning !== void 0)
     out.learning = normalizeLearning(record2.learning, "config.learning");
-  if (record2.reveal !== void 0)
-    out.reveal = normalizeRevealOptions(record2.reveal, "config.reveal");
+  if (record2.reveal !== void 0) {
+    out.reveal = normalizeRevealOptions(record2.reveal, "config.reveal", strict);
+  }
   return out;
 }
 function normalizeExplainOptions(value, path) {
@@ -493,12 +505,12 @@ function splitEvaluateOptions(value, path) {
     else explain2[key] = v;
   }
   return {
-    reveal: normalizeRevealOptions(reveal, path),
+    reveal: normalizeRevealOptions(reveal, path, false),
     explain: normalizeExplainOptions(explain2, path)
   };
 }
 function resolveReveal(config, intent, opts, normalized = false) {
-  const o = opts === void 0 ? {} : normalized ? opts : normalizeRevealOptions(opts, "options");
+  const o = opts === void 0 ? {} : normalized ? opts : normalizeRevealOptions(opts, "options", false);
   return {
     threshold: o.threshold ?? intent.reveal?.threshold ?? config?.reveal?.threshold ?? DEFAULT_THRESHOLD,
     z: o.z ?? intent.reveal?.z ?? config?.reveal?.z ?? DEFAULT_Z,
@@ -536,11 +548,7 @@ function timedOutAt(episode, timeout, at) {
   return at - episode.lastEventAt > timeout ? episode.lastEventAt + timeout : null;
 }
 function extendEpisode(episode, at) {
-  return {
-    startedAt: episode.startedAt ?? at,
-    lastEventAt: episode.lastEventAt === null ? at : Math.max(episode.lastEventAt, at),
-    intents: episode.intents
-  };
+  return { startedAt: episode.startedAt ?? at, lastEventAt: at, intents: episode.intents };
 }
 function episodeRecord(episode, intent) {
   return getOwn(episode.intents, intent) ?? { seen: [], counts: {}, resolved: false };
@@ -598,7 +606,7 @@ function assessIntent(state, name, intent, learning, at) {
 }
 function cooldownEnd(since, cooldown, at) {
   if (since === null) return null;
-  const end = since + cooldown;
+  const end = Math.min(since, at) + cooldown;
   return at < end ? end : null;
 }
 function buildPrediction(is, name, reveal, at) {
@@ -726,6 +734,7 @@ function observe(state, event) {
     let is = getIntentState(s, intentName, intent);
     is = decayIntent(is, intent, at);
     is = settlePending(is, intent, learning, at);
+    is = pinAnchors(is, at);
     if (isSignal) {
       const { effective } = signalWeights(is, intent, learning, name);
       const n = occurrences(episode, intentName, name) + 1;
@@ -735,7 +744,8 @@ function observe(state, event) {
       if (!isOutcome) episode = markSeen(episode, intentName, name);
     }
     if (isOutcome) {
-      is = recordEpisode(is, episodeRecord(episode, intentName).seen, 1);
+      const record2 = episodeRecord(episode, intentName);
+      if (!record2.resolved || record2.seen.length > 0) is = recordEpisode(is, record2.seen, 1);
       is = creditPending(is, intent, at);
       episode = markResolved(episode, intentName);
       is = { ...is, lastOutcomeAt: at };
@@ -745,6 +755,16 @@ function observe(state, event) {
   }
   return { ...s, intents, episode };
 }
+function pinAnchors(is, at) {
+  const reveal = is.lastRevealedAt !== null && is.lastRevealedAt > at;
+  const outcome = is.lastOutcomeAt !== null && is.lastOutcomeAt > at;
+  if (!reveal && !outcome) return is;
+  return {
+    ...is,
+    lastRevealedAt: reveal ? at : is.lastRevealedAt,
+    lastOutcomeAt: outcome ? at : is.lastOutcomeAt
+  };
+}
 function endEpisode(state, at) {
   const s = requireState(state);
   const t = expectTimestamp(at, "at");
@@ -1062,7 +1082,9 @@ function parseState(value) {
   }
   return {
     version: STATE_VERSION,
-    config: normalizeConfig(r.config),
+    // Without the strict checks: a config this release would refuse at createState still loads
+    // when it is only stored, and the config passed in replaces it anyway.
+    config: normalizeConfig(r.config, false),
     intents: mapOwn(r.intents, "state.intents", intentState),
     episode: episodeState(r.episode, "state.episode")
   };