oracular 0.12.1 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.14.0
+
+### Minor Changes
+
+- [#71](https://github.com/Yuribenjamin/oracular/pull/71) [`d9e9769`](https://github.com/Yuribenjamin/oracular/commit/d9e9769e922c3bc4251f4585a6cc1c7697468958) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - **A cooldown of its own after the outcome.** The outcome event paused reveals for the reveal `cooldown`: after a "stuck" intent's outcome, help was suppressed for the hour the cooldown named, and the next attempt that went wrong, exactly when the help should be back, got nothing; the only way out, `cooldown: 0`, disabled the reveal cooldown too. `reveal.outcomeCooldown` is the pause after the outcome, resolved per call → intent → engine like the other reveal options, 0 allowed; it defaults to the resolved `cooldown`, so nothing moves unless it is set. The JSON Schema lists it. Found by the second production integration.
+  
+  **Rollback.** A stored config that sets `outcomeCooldown` loads in 0.13 and later, which do not read the stored snapshot when the app passes its config; 0.12 and earlier throw a `TypeError` on the unknown key, so remove it from the saved config before rolling a deploy back that far. The state version is unchanged.
+
+## 0.13.0
+
+### Minor Changes
+
+- [#69](https://github.com/Yuribenjamin/oracular/pull/69) [`02e0c44`](https://github.com/Yuribenjamin/oracular/commit/02e0c44be6e1ac167cf5503a38efd0eb38b1dc2d) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - **A rollback no longer trips over a config key it does not know.** `deserialize` validated the config snapshot stored in the state even when the app passed its current config, which replaces it. So a state written by a release that set a new option (`bound` in 0.8, `learning.lift` in 0.9) threw a `TypeError` in the release before it, the changelogs asked for the key to be removed from the saved config before rolling a deploy back, and in `@oracular/react` the load was a `'parse'` failure that blocked writes until `clear()`. With a config passed, the stored snapshot is now not read at all: a key or a value this release does not know is no obstacle, and every number the state holds comes through as before. Without a config, the stored snapshot runs the engine and is read as it was: without the checks that refuse a config that cannot work, and with a key the library does not know still an error, since the engine would otherwise run without an option the state was built under. Nothing changes for a state that loaded before. Under rule 6 of the stability policy, states now move between releases in both directions for the config snapshot as they already did for the state's fields, and the policy says so.
+
 ## 0.12.1
 
 ### Patch Changes

package/README.md

@@ -224,7 +224,7 @@ Learned counts never decay unless you set `learning.halfLife`.
 
 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`.
+The outcome also starts a cooldown, `outcomeCooldown`, by default the same `cooldown` a reveal starts: `shouldReveal` stays false until it ends, however strong the fresh evidence, so a user who just bought is not immediately pitched again. Set it on its own, 0 included, for an intent whose outcome recurs within minutes, or a "stuck" intent whose help should be back at the next attempt: the outcome then pauses nothing while a reveal still starts its cooldown. The time of the last outcome is kept on the state as `lastOutcomeAt`.
 
 ### Every answer comes with its reasons
 
@@ -302,9 +302,10 @@ interface IntentConfig {
 }
 
 interface RevealOptions {
-  threshold?: number;  // default 0.5
-  z?: number;          // default 1.28
-  cooldown?: number;   // default: the intent's halfLife
+  threshold?: number;        // default 0.5
+  z?: number;                // default 1.28
+  cooldown?: number;         // after markRevealed; default: the intent's halfLife
+  outcomeCooldown?: number;  // after the outcome event; default: cooldown. 0 lets the outcome pause nothing
   bound?: 'normal' | 'exact';  // default 'normal': p − z·sd; 'exact': the Beta quantile at Φ(−z)
 }
 ```
@@ -356,7 +357,7 @@ localStorage.setItem('oracular', serialize(state));
 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.
+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. The stored snapshot is then not read at all, so a state written by a newer release, with a config key or value this one does not know, still loads after a rollback; loading without a config runs the stored snapshot instead, and a key the library does not know is then an error.
 
 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.11.x (`STATE_VERSION` 1 to 3) 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`:
 

package/dist/index.cjs

@@ -289,7 +289,7 @@ var INTENT_KEYS = [
   "attribution",
   "reveal"
 ];
-var REVEAL_KEYS = ["threshold", "z", "cooldown", "bound"];
+var REVEAL_KEYS = ["threshold", "z", "cooldown", "outcomeCooldown", "bound"];
 var LEARNING_KEYS = ["halfLife", "gain", "priorEpisodes", "lift"];
 var LIFT_TYPES = [
   "absolute-difference",
@@ -375,6 +375,9 @@ function normalizeRevealOptions(value, path, strict = true) {
   if (record2.cooldown !== void 0) {
     out.cooldown = expectNonNegative(record2.cooldown, `${path}.cooldown`);
   }
+  if (record2.outcomeCooldown !== void 0) {
+    out.outcomeCooldown = expectNonNegative(record2.outcomeCooldown, `${path}.outcomeCooldown`);
+  }
   if (record2.bound !== void 0) {
     if (record2.bound !== "normal" && record2.bound !== "exact") {
       typeError(`${path}.bound`, 'must be "normal" or "exact"');
@@ -513,10 +516,12 @@ function splitEvaluateOptions(value, path) {
 }
 function resolveReveal(config, intent, opts, normalized = false) {
   const o = opts === void 0 ? {} : normalized ? opts : normalizeRevealOptions(opts, "options", false);
+  const cooldown = o.cooldown ?? intent.reveal?.cooldown ?? config?.reveal?.cooldown ?? intent.halfLife;
   return {
     threshold: o.threshold ?? intent.reveal?.threshold ?? config?.reveal?.threshold ?? DEFAULT_THRESHOLD,
     z: o.z ?? intent.reveal?.z ?? config?.reveal?.z ?? DEFAULT_Z,
-    cooldown: o.cooldown ?? intent.reveal?.cooldown ?? config?.reveal?.cooldown ?? intent.halfLife,
+    cooldown,
+    outcomeCooldown: o.outcomeCooldown ?? intent.reveal?.outcomeCooldown ?? config?.reveal?.outcomeCooldown ?? cooldown,
     bound: o.bound ?? intent.reveal?.bound ?? config?.reveal?.bound ?? "normal"
   };
 }
@@ -621,7 +626,7 @@ function buildPrediction(is, name, reveal, at) {
   const p = betaMean(is.alpha, is.beta);
   const sd = betaSd(is.alpha, is.beta);
   const revealEnd = cooldownEnd(is.lastRevealedAt, reveal.cooldown, at);
-  const outcomeEnd = cooldownEnd(is.lastOutcomeAt, reveal.cooldown, at);
+  const outcomeEnd = cooldownEnd(is.lastOutcomeAt, reveal.outcomeCooldown, at);
   const suppressedUntil = revealEnd === null ? outcomeEnd : outcomeEnd === null ? revealEnd : Math.max(revealEnd, outcomeEnd);
   return {
     intent: name,
@@ -1005,9 +1010,9 @@ function deserialize(json, opts = {}) {
       stored = opts.migrate(parsed, parsed.version);
     }
   }
-  const raw = parseState(stored);
-  const config = opts.config === void 0 ? raw.config : normalizeConfig(opts.config);
-  return requireComputable(reconcile(raw, config));
+  const config = opts.config === void 0 ? void 0 : normalizeConfig(opts.config);
+  const raw = parseState(stored, config);
+  return requireComputable(reconcile(raw, raw.config));
 }
 function typeError2(path, message) {
   throw new TypeError(`oracular: ${path} ${message}`);
@@ -1116,16 +1121,15 @@ function clockState(value, path) {
     behindAt: nullOrFinite(r.behindAt, `${path}.behindAt`)
   };
 }
-function parseState(value) {
+function parseState(value, config) {
   const r = record(value, "state");
   if (r.version !== STATE_VERSION) {
     throw new RangeError(`oracular: state.version must be ${STATE_VERSION} after migration`);
   }
+  const snapshot = record(r.config, "state.config");
   return {
     version: STATE_VERSION,
-    // 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),
+    config: config ?? normalizeConfig(snapshot, false),
     intents: mapOwn(r.intents, "state.intents", intentState),
     episode: episodeState(r.episode, "state.episode"),
     clock: clockState(r.clock, "state.clock")