oracular 0.12.1 → 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;
 }
@@ -395,7 +402,11 @@ type Migrate = (stored: unknown, version: number) => EngineState;
  * ```
  */
 interface DeserializeOptions {
-    /** The app's current config. Validated, swapped in, and used to prune signals and intents no longer declared. */
+    /**
+     * The app's current config. Validated, swapped in, and used to prune signals and intents no
+     * longer declared; the stored snapshot is then not read, so a key or value a newer release wrote
+     * into it does not stop the load.
+     */
     config?: EngineConfig;
     /**
      * Called when the stored version is neither `STATE_VERSION`, nor one this library migrates
@@ -726,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.
@@ -751,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
@@ -850,11 +863,14 @@ declare function serialize(state: EngineState): string;
 /**
  * Restores a state saved with {@link serialize}.
  *
- * Always pass the app's current `config`: it is validated and replaces the stored snapshot (the
- * stored one is read without the checks that refuse a config that cannot work, so a state saved
- * before those checks existed still loads),
- * intents and signals no longer declared are dropped (α and β are recomputed from the kept
- * contributions), and newly declared intents start at their prior. States saved by oracular
+ * Always pass the app's current `config`: it is validated and replaces the stored snapshot,
+ * which 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. Intents and signals no longer
+ * declared are dropped (α and β are recomputed from the kept contributions), and newly declared
+ * intents start at their prior. Without a config the stored snapshot runs the engine: it is read
+ * without the checks that refuse a config that cannot work, so a state saved before those checks
+ * existed still loads, but a key the library does not know is an error, since the engine would
+ * otherwise run without an option the state was built under. States saved by oracular
  * 0.1.0 to 0.11.x are upgraded to the current shape on their own, and a state one version newer
  * than {@link STATE_VERSION} (written by the next release, read after a rollback) is read as the
  * current one, ignoring the fields it adds; `migrate` is only for a version this library does

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;
 }
@@ -395,7 +402,11 @@ type Migrate = (stored: unknown, version: number) => EngineState;
  * ```
  */
 interface DeserializeOptions {
-    /** The app's current config. Validated, swapped in, and used to prune signals and intents no longer declared. */
+    /**
+     * The app's current config. Validated, swapped in, and used to prune signals and intents no
+     * longer declared; the stored snapshot is then not read, so a key or value a newer release wrote
+     * into it does not stop the load.
+     */
     config?: EngineConfig;
     /**
      * Called when the stored version is neither `STATE_VERSION`, nor one this library migrates
@@ -726,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.
@@ -751,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
@@ -850,11 +863,14 @@ declare function serialize(state: EngineState): string;
 /**
  * Restores a state saved with {@link serialize}.
  *
- * Always pass the app's current `config`: it is validated and replaces the stored snapshot (the
- * stored one is read without the checks that refuse a config that cannot work, so a state saved
- * before those checks existed still loads),
- * intents and signals no longer declared are dropped (α and β are recomputed from the kept
- * contributions), and newly declared intents start at their prior. States saved by oracular
+ * Always pass the app's current `config`: it is validated and replaces the stored snapshot,
+ * which 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. Intents and signals no longer
+ * declared are dropped (α and β are recomputed from the kept contributions), and newly declared
+ * intents start at their prior. Without a config the stored snapshot runs the engine: it is read
+ * without the checks that refuse a config that cannot work, so a state saved before those checks
+ * existed still loads, but a key the library does not know is an error, since the engine would
+ * otherwise run without an option the state was built under. States saved by oracular
  * 0.1.0 to 0.11.x are upgraded to the current shape on their own, and a state one version newer
  * than {@link STATE_VERSION} (written by the next release, read after a rollback) is read as the
  * current one, ignoring the fields it adds; `migrate` is only for a version this library does

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,
@@ -1003,9 +1008,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}`);
@@ -1114,16 +1119,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")