oracular 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # 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

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)
 }
 ```

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,