oracular 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 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
+
+- [#64](https://github.com/Yuribenjamin/oracular/pull/64) [`c108ca9`](https://github.com/Yuribenjamin/oracular/commit/c108ca92b4b66b90749664379bc676a230462726) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - **`replay` shows the reveals it could not score.** A reveal whose window runs past the end of the log is not scored for precision, since its verdict is not in yet, but an outcome it preceded still counts for recall, so a short log printed `reveals 0` beside `recall 100.0% of 1`, and `--json` showed `reveals: 0, caught: 1, censored: 1`. Both numbers were right and the table did not say why. The text table now shows such reveals in the row (`0 (+1 censored)`) with a footnote that says what recall still counts, and a log shorter than an intent's scoring window, in which every reveal and point is censored, gets a warning on stderr that points at `--window`. The `--json` report is unchanged: `censored` was already there. Found by the second production integration on a one-minute log with the default one-hour window.
+
 ## 0.12.0
 
 ### Minor Changes

package/README.md

@@ -356,7 +356,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/cli.js

@@ -363,7 +363,7 @@ function formatIntent(intent) {
       ["threshold", "reveals", "per user", "precision", "recall", "median lead time"],
       intent.thresholds.map((t) => [
         `${t.threshold}${t.configured ? " *" : ""}`,
-        String(t.reveals),
+        t.censored > 0 ? `${t.reveals} (+${t.censored} censored)` : String(t.reveals),
         num(t.revealsPerUser, 2),
         pct(t.precision),
         `${pct(t.recall)} of ${t.outcomes}`,
@@ -371,9 +371,9 @@ function formatIntent(intent) {
       ])
     )
   );
-  const censored = intent.thresholds.reduce((acc, t) => Math.max(acc, t.censored), 0);
+  const censored = intent.thresholds.some((t) => t.censored > 0);
   out.push(
-    `* the threshold your config resolves for this intent.${censored > 0 ? ` Reveals whose window runs past the end of the log are not scored (up to ${censored} per threshold).` : ""}`
+    `* the threshold your config resolves for this intent.${censored ? " A reveal whose window runs past the end of the log (the +n) is not scored for precision, since its verdict is not in yet; an outcome it preceded still counts as caught for recall." : ""}`
   );
   out.push("");
   out.push(
@@ -1310,9 +1310,22 @@ async function replayCommand(argv, io) {
     if (error instanceof RangeError) throw new UsageError(error.message);
     throw error;
   }
+  warnShortLog(report, io);
   io.stdout(args.json ? formatJson(report) : formatText(report));
   return 0;
 }
+function warnShortLog(report, io) {
+  if (report.start === null || report.end === null) return;
+  const span = report.end - report.start;
+  for (const intent of report.intents) {
+    if (span < intent.window) {
+      io.stderr(
+        `oracular: warning: ${intent.intent}: the log spans ${formatDuration(span)}, less than its ${formatDuration(intent.window)} scoring window, so every reveal and point is censored and only recall can be counted. Pass --window with a duration shorter than the log, or record for longer than the window.
+`
+      );
+    }
+  }
+}
 async function tuneCommand(argv, io) {
   const args = parseTuneArgs(argv);
   if (args.help) {

package/dist/index.cjs

@@ -1005,9 +1005,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 +1116,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")