oracular 0.13.0 → 0.14.0

package/dist/index.d.cts

@@ -54,6 +54,13 @@ interface RevealOptions {
     z?: number;
     /** How long after `markRevealed` the intent stays revealed and `shouldReveal` is false. Default: the intent's `halfLife`. */
     cooldown?: number;
+    /**
+     * How long after the intent's outcome event `shouldReveal` stays false. Default: `cooldown`.
+     * 0 is allowed: the outcome then pauses nothing, while a reveal still starts its cooldown, for
+     * an intent whose outcome recurs within minutes, or a "stuck" intent whose help should be back
+     * at the next attempt.
+     */
+    outcomeCooldown?: number;
     /**
      * How `lower` is computed. `'normal'` (default): p − z·sd, clamped to [0, 1]. `'exact'`: the
      * Beta distribution's own quantile at the same one-sided level, Φ(−z), so `z` keeps its
@@ -307,8 +314,8 @@ interface Prediction {
     revealedAt: number | null;
     /**
      * When the current suppression ends: the later of the reveal cooldown (after `markRevealed`)
-     * and the outcome cooldown (after the outcome event) still running at `at`, or null when
-     * neither is. `shouldReveal` is false while this is non-null.
+     * and the outcome cooldown (`outcomeCooldown` after the outcome event) still running at `at`,
+     * or null when neither is. `shouldReveal` is false while this is non-null.
      */
     suppressedUntil: number | null;
 }
@@ -730,9 +737,10 @@ declare function episodeClosed(prev: EngineState, next: EngineState): boolean;
  * @param state - The current state. Not mutated.
  * @param intent - Name of an intent declared in the config.
  * @param at - The time to evaluate at, in the same unit as your durations.
- * @param opts - Overrides for `threshold`, `z`, `cooldown` and `bound`, resolved as call →
- *   intent → engine → defaults. `z` and `bound` set `lower`; `cooldown` sets `revealed` and
- *   `suppressedUntil`; `threshold` only matters to {@link shouldReveal}.
+ * @param opts - Overrides for `threshold`, `z`, `cooldown`, `outcomeCooldown` and `bound`,
+ *   resolved as call → intent → engine → defaults. `z` and `bound` set `lower`; `cooldown` sets
+ *   `revealed` and, with `outcomeCooldown` (default: `cooldown`), `suppressedUntil`;
+ *   `threshold` only matters to {@link shouldReveal}.
  * @returns The prediction. `p`, `sd`, `lower` and `confidence` are in [0, 1]; `evidence` is
  *   α + β.
  * @throws `RangeError` when `intent` is not declared in the config.
@@ -755,7 +763,8 @@ declare function predict(state: EngineState, intent: string, at: number, opts?:
  * @param intent - Name of an intent declared in the config.
  * @param at - The time to evaluate at.
  * @param opts - Overrides for `threshold` (default 0.5), `z` (default 1.28, a one-sided 90%
- *   bound) and `cooldown` (default: the intent's `halfLife`).
+ *   bound), `cooldown` (default: the intent's `halfLife`) and `outcomeCooldown` (default:
+ *   `cooldown`; 0 lets the outcome pause nothing).
  * @returns True when the app should show, offer or reveal whatever this intent gates.
  * @throws `RangeError` when `intent` is not declared in the config.
  * @throws `TypeError` when `state` is not an engine state, `at` is not finite, or `opts` is

package/dist/index.d.ts

@@ -54,6 +54,13 @@ interface RevealOptions {
     z?: number;
     /** How long after `markRevealed` the intent stays revealed and `shouldReveal` is false. Default: the intent's `halfLife`. */
     cooldown?: number;
+    /**
+     * How long after the intent's outcome event `shouldReveal` stays false. Default: `cooldown`.
+     * 0 is allowed: the outcome then pauses nothing, while a reveal still starts its cooldown, for
+     * an intent whose outcome recurs within minutes, or a "stuck" intent whose help should be back
+     * at the next attempt.
+     */
+    outcomeCooldown?: number;
     /**
      * How `lower` is computed. `'normal'` (default): p − z·sd, clamped to [0, 1]. `'exact'`: the
      * Beta distribution's own quantile at the same one-sided level, Φ(−z), so `z` keeps its
@@ -307,8 +314,8 @@ interface Prediction {
     revealedAt: number | null;
     /**
      * When the current suppression ends: the later of the reveal cooldown (after `markRevealed`)
-     * and the outcome cooldown (after the outcome event) still running at `at`, or null when
-     * neither is. `shouldReveal` is false while this is non-null.
+     * and the outcome cooldown (`outcomeCooldown` after the outcome event) still running at `at`,
+     * or null when neither is. `shouldReveal` is false while this is non-null.
      */
     suppressedUntil: number | null;
 }
@@ -730,9 +737,10 @@ declare function episodeClosed(prev: EngineState, next: EngineState): boolean;
  * @param state - The current state. Not mutated.
  * @param intent - Name of an intent declared in the config.
  * @param at - The time to evaluate at, in the same unit as your durations.
- * @param opts - Overrides for `threshold`, `z`, `cooldown` and `bound`, resolved as call →
- *   intent → engine → defaults. `z` and `bound` set `lower`; `cooldown` sets `revealed` and
- *   `suppressedUntil`; `threshold` only matters to {@link shouldReveal}.
+ * @param opts - Overrides for `threshold`, `z`, `cooldown`, `outcomeCooldown` and `bound`,
+ *   resolved as call → intent → engine → defaults. `z` and `bound` set `lower`; `cooldown` sets
+ *   `revealed` and, with `outcomeCooldown` (default: `cooldown`), `suppressedUntil`;
+ *   `threshold` only matters to {@link shouldReveal}.
  * @returns The prediction. `p`, `sd`, `lower` and `confidence` are in [0, 1]; `evidence` is
  *   α + β.
  * @throws `RangeError` when `intent` is not declared in the config.
@@ -755,7 +763,8 @@ declare function predict(state: EngineState, intent: string, at: number, opts?:
  * @param intent - Name of an intent declared in the config.
  * @param at - The time to evaluate at.
  * @param opts - Overrides for `threshold` (default 0.5), `z` (default 1.28, a one-sided 90%
- *   bound) and `cooldown` (default: the intent's `halfLife`).
+ *   bound), `cooldown` (default: the intent's `halfLife`) and `outcomeCooldown` (default:
+ *   `cooldown`; 0 lets the outcome pause nothing).
  * @returns True when the app should show, offer or reveal whatever this intent gates.
  * @throws `RangeError` when `intent` is not declared in the config.
  * @throws `TypeError` when `state` is not an engine state, `at` is not finite, or `opts` is

package/dist/index.js

@@ -287,7 +287,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",
@@ -373,6 +373,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"');
@@ -511,10 +514,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"
   };
 }
@@ -619,7 +624,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,