oracular 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.5.0
+
+### Minor Changes
+
+- [#24](https://github.com/Yuribenjamin/oracular/pull/24) [`7809c6a`](https://github.com/Yuribenjamin/oracular/commit/7809c6af5c26ec836e43b76eac647bcf85c42514) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - **`npx oracular tune <log>... --config <file>`** seeds a config from a shadow log. Grouped by install, it reads what the engine itself counts, hits, misses and episode totals, off the state after every record, so it cannot disagree with what a device would learn from the same events. The base rate becomes the prior; the spread of per-install base rates becomes the prior strength (method of moments on a Beta, once the spread that sampling alone would produce is taken out; kept as it was below 10 installs); each declared signal's weight is `priorStrength × lift` over the episodes without it, with a 90% Wilson interval and the sample sizes on both sides; and the half-life that predicts the log best (lowest Brier score under `replay`) wins a grid search over 1h to 30d plus the current value. It prints the fit and the config to paste, which `replay --config` takes as it is.
+  
+  Like replay, it counts shadow periods only: an episode in which any record was live is left out, a mixed log gets a warning, a live-only log is refused unless `--include-live` is passed. `--all-events` also measures every other event name in the log as a candidate signal; `--half-lives 12h,1d,3d` sets the grid; `--window` sets the scoring window when the intent has no cooldown. Every number is a starting point: the engine corrects the weights per user.
+  
+  `oracular --help` now lists both commands; `oracular replay --help` and `oracular tune --help` have the options.
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -73,7 +73,7 @@ That block is copied verbatim into the test suite, so it always runs.
 - [API](#api)
 - [Persistence](#persistence)
 - [Explainability](#explainability)
-- [Shadow mode & replay](#shadow-mode--replay)
+- [Shadow mode, replay and tune](#shadow-mode-replay-and-tune)
 - [Design rules](#design-rules)
 - [Roadmap](#roadmap)
 - [Contributing](#contributing)
@@ -363,7 +363,7 @@ explain(state, 'upgrade', Date.now());
 
 Rows are sorted by the size of their impact. `limit.hit` has no history yet, so its effective weight is exactly the initial one. `pricing.viewed` was followed by an upgrade in six of its seven sessions while the three sessions without it saw one upgrade, so it learned a weight above the initial 3. `export.clicked` appeared in every session: it has no counterfactual, so whatever its hit rate, its weight stands at exactly the initial 1 until a session happens without it. See [Episodes & learning](https://yuribenjamin.github.io/oracular/guide/concepts/episodes-and-learning) for why learning needs contrast.
 
-## Shadow mode & replay
+## Shadow mode, replay and tune
 
 Run oracular silently first. Record what it decides, export the log, and measure a config offline before any reveal is shown:
 
@@ -376,7 +376,13 @@ log.append(JSON.stringify(createRecord(state, event, { installId, mode: 'shadow'
 npx oracular replay shadow.ndjson --config oracular.config.json
 ```
 
-`replay` reports precision, recall, lead time and reveals per user for every intent and threshold, and a reliability table with a Brier score. It scores only the periods in which reveals were not shown, because once they are, the reveal itself causes outcomes. `installId` is a random id your app generates once and stores; it is never derived from the device. The log holds event names and times, never `props`, and leaves the device only if your app sends it. The [Shadow mode guide](https://yuribenjamin.github.io/oracular/guide/shadow-mode) has the workflow and the record format.
+`replay` reports precision, recall, lead time and reveals per user for every intent and threshold, and a reliability table with a Brier score. It scores only the periods in which reveals were not shown, because once they are, the reveal itself causes outcomes. `installId` is a random id your app generates once and stores; it is never derived from the device. The log holds event names and times, never `props`, and leaves the device only if your app sends it.
+
+```sh
+npx oracular tune shadow.ndjson --config oracular.config.json
+```
+
+`tune` seeds a config from the same log: grouped by install, the base rate becomes the prior, the spread of per-install base rates the prior strength, each signal's lift over the episodes without it its weight, and the half-life that predicts the log best wins a grid search scored by `replay`. The counts come from the engine itself, so tune cannot disagree with what a device would learn. It prints sample sizes and a 90% interval per weight, and the config to paste; the engine corrects it per user from there. The [Shadow mode guide](https://yuribenjamin.github.io/oracular/guide/shadow-mode) has the workflow, the record format and both commands.
 
 ## Design rules
 
@@ -387,7 +393,7 @@ npx oracular replay shadow.ndjson --config oracular.config.json
 
 ## Roadmap
 
-Now is 0.4, themed **learning that matches how people behave**: cross-episode attribution, so a session's signals can earn credit for an outcome days later; `npx oracular tune` to seed a config from a shadow log; presets; and small ergonomics (`validateConfig`, `ms`, a JSON Schema for the config). 0.3 shipped shadow mode, `npx oracular replay` and per-episode saturation. Then a written stability policy before 1.0. Framework bindings wait for a third integration. The full list, with the reasoning and what was declined, is on the [roadmap page](https://yuribenjamin.github.io/oracular/guide/roadmap).
+Now is 0.4, themed **learning that matches how people behave**: cross-episode attribution, so a session's signals can earn credit for an outcome days later, and presets. Shipped so far: `npx oracular tune` to seed a config from a shadow log, and small ergonomics (`validateConfig`, `ms`, a JSON Schema for the config). 0.3 shipped shadow mode, `npx oracular replay` and per-episode saturation. Then a written stability policy before 1.0. Framework bindings wait for a third integration. The full list, with the reasoning and what was declined, is on the [roadmap page](https://yuribenjamin.github.io/oracular/guide/roadmap).
 
 ## Contributing
 

package/dist/cli.js

@@ -20,6 +20,31 @@ var LogError = class extends Error {
 function isObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function groupByInstall(entries) {
+  const byInstall = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const list = byInstall.get(entry.installId);
+    if (list === void 0) byInstall.set(entry.installId, [entry]);
+    else list.push(entry);
+  }
+  let start = null;
+  let end = null;
+  let shadow = 0;
+  let live = 0;
+  let mixedInstalls = 0;
+  for (const list of byInstall.values()) {
+    list.sort((a, b) => a.at - b.at);
+    const modes = new Set(list.map((e) => e.mode));
+    if (modes.size > 1) mixedInstalls++;
+    for (const e of list) {
+      if (e.mode === "shadow") shadow++;
+      else live++;
+      start = start === null ? e.at : Math.min(start, e.at);
+      end = end === null ? e.at : Math.max(end, e.at);
+    }
+  }
+  return { byInstall, start, end, shadow, live, mixedInstalls };
+}
 function parseLog(text, source) {
   const entries = [];
   const unknownKinds = /* @__PURE__ */ new Map();
@@ -126,28 +151,7 @@ function replay(entries, config, options = {}) {
     };
   });
   const allThresholds = [...new Set(plans.flatMap((p) => p.thresholds))].sort((a, b) => a - b);
-  const byInstall = /* @__PURE__ */ new Map();
-  for (const entry of entries) {
-    const list = byInstall.get(entry.installId);
-    if (list === void 0) byInstall.set(entry.installId, [entry]);
-    else list.push(entry);
-  }
-  let start = null;
-  let end = null;
-  let shadow = 0;
-  let live = 0;
-  let mixedInstalls = 0;
-  for (const list of byInstall.values()) {
-    list.sort((a, b) => a.at - b.at);
-    const modes = new Set(list.map((e) => e.mode));
-    if (modes.size > 1) mixedInstalls++;
-    for (const e of list) {
-      if (e.mode === "shadow") shadow++;
-      else live++;
-      start = start === null ? e.at : Math.min(start, e.at);
-      end = end === null ? e.at : Math.max(end, e.at);
-    }
-  }
+  const { byInstall, start, end, shadow, live, mixedInstalls } = groupByInstall(entries);
   const logEnd = end ?? 0;
   const tallies = plans.map((plan) => ({
     plan,
@@ -414,10 +418,492 @@ function formatJson(report) {
 `;
 }
 
+// cli/tune.ts
+import {
+  createState as createState2,
+  endEpisode as endEpisode2,
+  episodeClosed,
+  markRevealed as markRevealed2,
+  observe as observe2,
+  predict as predict2
+} from "oracular";
+
+// src/math.ts
+function laplace(successes, total) {
+  return (successes + 1) / (total + 2);
+}
+function lift(q, b) {
+  if (q >= b) return b >= 1 ? 0 : (q - b) / (1 - b);
+  return b <= 0 ? 0 : (q - b) / b;
+}
+
+// cli/tune.ts
+var HOUR2 = 36e5;
+var DAY2 = 24 * HOUR2;
+var DEFAULT_HALF_LIVES = [HOUR2, 6 * HOUR2, DAY2, 3 * DAY2, 7 * DAY2, 14 * DAY2, 30 * DAY2];
+var DEFAULT_PRIOR_EPISODES = 10;
+var MIN_INSTALLS_FOR_SPREAD = 10;
+var STRENGTH_RANGE = [2, 50];
+var Z90 = 1.6449;
+var NONE = { hits: 0, misses: 0 };
+function stepDelta(prev, next) {
+  const d = { hits: {}, misses: {}, outcomes: 0, episodes: 0 };
+  let changed = false;
+  for (const [signal, record] of Object.entries(next.learned)) {
+    const before = Object.hasOwn(prev.learned, signal) ? prev.learned[signal] ?? NONE : NONE;
+    const hits = record.hits - before.hits;
+    const misses = record.misses - before.misses;
+    if (hits !== 0) {
+      d.hits[signal] = hits;
+      changed = true;
+    }
+    if (misses !== 0) {
+      d.misses[signal] = misses;
+      changed = true;
+    }
+  }
+  d.outcomes = next.episodes.hits - prev.episodes.hits;
+  d.episodes = d.outcomes + (next.episodes.misses - prev.episodes.misses);
+  if (d.episodes !== 0) changed = true;
+  return changed ? d : null;
+}
+function addTally(into, d) {
+  for (const [signal, n] of Object.entries(d.hits)) {
+    into.hits[signal] = (Object.hasOwn(into.hits, signal) ? into.hits[signal] ?? 0 : 0) + n;
+  }
+  for (const [signal, n] of Object.entries(d.misses)) {
+    into.misses[signal] = (Object.hasOwn(into.misses, signal) ? into.misses[signal] ?? 0 : 0) + n;
+  }
+  into.outcomes += d.outcomes;
+  into.episodes += d.episodes;
+}
+var own = (record, key) => Object.hasOwn(record, key) ? record[key] ?? 0 : 0;
+function wilson(successes, n, z) {
+  if (n <= 0) return [0, 1];
+  const p = successes / n;
+  const z2 = z * z;
+  const centre = (p + z2 / (2 * n)) / (1 + z2 / n);
+  const half = z / (1 + z2 / n) * Math.sqrt(p * (1 - p) / n + z2 / (4 * n * n));
+  return [Math.max(0, centre - half), Math.min(1, centre + half)];
+}
+function fitSignal(signal, current, tally, strength, priorEpisodes) {
+  const hits = own(tally.hits, signal);
+  const misses = own(tally.misses, signal);
+  const nWith = hits + misses;
+  const without = Math.max(0, tally.episodes - nWith);
+  const outcomesWithout = Math.min(without, Math.max(0, tally.outcomes - hits));
+  const qWith = laplace(hits, nWith);
+  const qWithout = laplace(outcomesWithout, without);
+  const l = nWith === 0 ? 0 : lift(qWith, qWithout);
+  const contrast = nWith + without === 0 ? 0 : nWith * without / (nWith + without);
+  const [qLow, qHigh] = wilson(hits, nWith, Z90);
+  const rounded = Math.round(strength * l * 100) / 100;
+  return {
+    signal,
+    current,
+    hits,
+    misses,
+    without,
+    outcomesWithout,
+    qWith,
+    qWithout,
+    lift: l,
+    weight: nWith === 0 || rounded === 0 ? null : rounded,
+    low: strength * lift(qLow, qWithout),
+    high: strength * lift(qHigh, qWithout),
+    contrast,
+    thin: contrast < priorEpisodes
+  };
+}
+function fitStrength(installs, current) {
+  const k = installs.length;
+  const plural2 = (n) => n === 1 ? "" : "s";
+  if (k < MIN_INSTALLS_FOR_SPREAD) {
+    return {
+      value: current,
+      current,
+      source: "kept",
+      note: `kept: ${k} install${plural2(k)} with a counted episode, reading the spread needs ${MIN_INSTALLS_FOR_SPREAD}`
+    };
+  }
+  const total = installs.reduce((acc, i) => acc + i.episodes, 0);
+  const m = installs.reduce((acc, i) => acc + i.outcomes, 0) / total;
+  if (m <= 0 || m >= 1) {
+    return {
+      value: current,
+      current,
+      source: "kept",
+      note: "kept: every counted episode ended the same way, so there is no spread to read"
+    };
+  }
+  const observed = installs.reduce((acc, i) => acc + i.episodes * (i.outcomes / i.episodes - m) ** 2, 0) / total;
+  const sampling = k * m * (1 - m) / total;
+  const between = observed - sampling;
+  if (between <= 0) {
+    return {
+      value: current,
+      current,
+      source: "kept",
+      note: `kept: the base rates of ${k} installs differ no more than chance would make them`
+    };
+  }
+  const raw = m * (1 - m) / between - 1;
+  const [min, max] = STRENGTH_RANGE;
+  const clamped = Math.min(max, Math.max(min, raw));
+  const value = Math.round(clamped * 10) / 10;
+  const capped = clamped !== raw ? `, capped to ${min}\u2013${max}` : "";
+  return {
+    value,
+    current,
+    source: "spread",
+    note: `spread of base rates across ${k} installs (sd ${Math.sqrt(between).toFixed(2)} around ${m.toFixed(2)})${capped}`
+  };
+}
+function withIntent(config, name, intent) {
+  return { ...config, intents: { ...config.intents, [name]: intent } };
+}
+function withoutLearnedDecay(config) {
+  if (config.learning?.halfLife === void 0) return config;
+  const learning = Object.fromEntries(
+    Object.entries(config.learning).filter(([key]) => key !== "halfLife")
+  );
+  return { ...config, learning };
+}
+function cooldownOf(base, name) {
+  return predict2(markRevealed2(base, name, 0), name, 0).suppressedUntil ?? 0;
+}
+function tune(entries, config, options = {}) {
+  const base = createState2(config);
+  const normalized = base.config;
+  const includeLive = options.includeLive === true;
+  const priorEpisodes = normalized.learning?.priorEpisodes ?? DEFAULT_PRIOR_EPISODES;
+  const skipped = [];
+  const names = options.intents ?? Object.keys(normalized.intents);
+  for (const name of names) {
+    if (!Object.hasOwn(normalized.intents, name)) {
+      throw new RangeError(
+        `unknown intent ${JSON.stringify(name)} (the config declares: ${Object.keys(normalized.intents).join(", ")})`
+      );
+    }
+  }
+  const fitting = names.filter((name) => {
+    if (normalized.intents[name].outcome !== void 0) return true;
+    skipped.push({ intent: name, reason: "declares no outcome event, so there is nothing to fit" });
+    return false;
+  });
+  const grouped = groupByInstall(entries);
+  const windows = /* @__PURE__ */ new Map();
+  for (const name of fitting) {
+    const window = options.window ?? cooldownOf(base, name);
+    if (!(window > 0)) {
+      throw new RangeError(
+        options.window === void 0 ? `intent ${JSON.stringify(name)} has a reveal cooldown of 0, so there is no scoring window for the half-life grid; pass --window (for example --window 7d)` : "the scoring window must be greater than 0"
+      );
+    }
+    windows.set(name, window);
+  }
+  const eventNames = /* @__PURE__ */ new Set();
+  for (const entry of entries) if (entry.kind === "event") eventNames.add(entry.name);
+  const candidatesOf = (intent) => options.allEvents === true ? [...eventNames].filter(
+    (name) => name !== "__proto__" && name !== intent.outcome && !Object.hasOwn(intent.signals, name)
+  ) : [];
+  let countConfig = withoutLearnedDecay(normalized);
+  const plans = fitting.map((name) => {
+    const intent = normalized.intents[name];
+    const candidates = candidatesOf(intent);
+    if (candidates.length > 0) {
+      countConfig = withIntent(countConfig, name, {
+        ...intent,
+        signals: { ...intent.signals, ...Object.fromEntries(candidates.map((c) => [c, 1])) }
+      });
+    }
+    return {
+      name,
+      intent,
+      candidates,
+      tally: { hits: {}, misses: {}, outcomes: 0, episodes: 0 },
+      excluded: 0,
+      installs: []
+    };
+  });
+  const countBase = createState2(countConfig);
+  for (const list of grouped.byInstall.values()) {
+    if (!includeLive && !list.some((e) => e.mode === "shadow")) continue;
+    let state = countBase;
+    let liveInSpan = false;
+    const perInstall = new Map(plans.map((plan) => [plan.name, { outcomes: 0, episodes: 0 }]));
+    for (const entry of list) {
+      const prev = state;
+      state = entry.kind === "end" ? endEpisode2(state, entry.at) : observe2(state, { name: entry.name, at: entry.at });
+      const closed = episodeClosed(prev, state);
+      const opensNext = closed && entry.kind === "event" && state.episode.startedAt === entry.at;
+      const contaminated = liveInSpan || !opensNext && entry.mode === "live";
+      for (const plan of plans) {
+        const d = stepDelta(
+          prev.intents[plan.name],
+          state.intents[plan.name]
+        );
+        if (d === null) continue;
+        if (contaminated && !includeLive) {
+          plan.excluded += d.episodes;
+          continue;
+        }
+        addTally(plan.tally, d);
+        const mine = perInstall.get(plan.name);
+        mine.outcomes += d.outcomes;
+        mine.episodes += d.episodes;
+      }
+      if (closed) liveInSpan = opensNext && entry.mode === "live";
+      else if (entry.mode === "live") liveInSpan = true;
+    }
+    for (const plan of plans) {
+      const mine = perInstall.get(plan.name);
+      if (mine.episodes > 0) plan.installs.push(mine);
+    }
+  }
+  let fitted = normalized;
+  const intents = [];
+  for (const plan of plans) {
+    const { name, intent, tally } = plan;
+    if (tally.episodes === 0) {
+      skipped.push({
+        intent: name,
+        reason: plan.excluded > 0 ? "every completed episode had a live reveal inside it, so nothing could be counted (pass --include-live to count them)" : "no completed episode in the log, so nothing could be counted"
+      });
+      continue;
+    }
+    const prior = laplace(tally.outcomes, tally.episodes);
+    const strength = fitStrength(plan.installs, intent.priorStrength);
+    const signals = Object.keys(intent.signals).map(
+      (signal) => fitSignal(signal, intent.signals[signal], tally, strength.value, priorEpisodes)
+    );
+    const candidates = plan.candidates.map(
+      (signal) => fitSignal(signal, null, tally, strength.value, priorEpisodes)
+    );
+    const roundedPrior = Math.round(prior * 1e4) / 1e4;
+    const fittedIntent = {
+      ...intent,
+      prior: roundedPrior > 0 && roundedPrior < 1 ? roundedPrior : prior,
+      priorStrength: strength.value,
+      signals: Object.fromEntries(
+        signals.filter((f) => f.weight !== null).map((f) => [f.signal, f.weight])
+      )
+    };
+    const window = windows.get(name);
+    const threshold = intent.reveal?.threshold ?? normalized.reveal?.threshold ?? DEFAULT_THRESHOLD;
+    const grid = [.../* @__PURE__ */ new Set([...options.halfLives ?? DEFAULT_HALF_LIVES, intent.halfLife])].sort(
+      (a, b) => a - b
+    );
+    let brierBaseline = null;
+    const curve = grid.map((halfLife2) => {
+      const report = replay(entries, withIntent(fitted, name, { ...fittedIntent, halfLife: halfLife2 }), {
+        intents: [name],
+        thresholds: [threshold],
+        window,
+        includeLive
+      });
+      const scored = report.intents[0];
+      brierBaseline = scored?.brierBaseline ?? brierBaseline;
+      return { halfLife: halfLife2, brier: scored?.brier ?? null, points: scored?.points ?? 0 };
+    });
+    const scoredPoints = curve.filter((p) => p.brier !== null);
+    let halfLife;
+    if (scoredPoints.length === 0) {
+      halfLife = {
+        value: intent.halfLife,
+        current: intent.halfLife,
+        source: "kept",
+        note: "kept: no point in the log could be scored, so the grid says nothing",
+        window,
+        curve,
+        brierBaseline
+      };
+    } else {
+      const best = Math.min(...scoredPoints.map((p) => p.brier));
+      const ties = scoredPoints.filter((p) => p.brier - best <= 1e-12);
+      const nearest = (p) => Math.abs(Math.log(p.halfLife / intent.halfLife));
+      const chosen = ties.reduce((a, b) => nearest(b) < nearest(a) ? b : a);
+      halfLife = {
+        value: chosen.halfLife,
+        current: intent.halfLife,
+        source: "grid",
+        note: `lowest Brier score over the grid, ${best.toFixed(3)}${brierBaseline === null ? "" : ` (always predicting the base rate: ${brierBaseline.toFixed(3)})`}`,
+        window,
+        curve,
+        brierBaseline
+      };
+    }
+    fitted = withIntent(fitted, name, { ...fittedIntent, halfLife: halfLife.value });
+    intents.push({
+      intent: name,
+      outcome: intent.outcome,
+      installs: plan.installs.length,
+      episodes: tally.episodes,
+      outcomes: tally.outcomes,
+      excluded: plan.excluded,
+      prior: { value: prior, current: intent.prior },
+      priorStrength: strength,
+      halfLife,
+      priorEpisodes,
+      signals,
+      candidates
+    });
+  }
+  return {
+    installs: grouped.byInstall.size,
+    records: entries.length,
+    shadow: grouped.shadow,
+    live: grouped.live,
+    mixedInstalls: grouped.mixedInstalls,
+    start: grouped.start,
+    end: grouped.end,
+    scored: includeLive ? "all" : "shadow",
+    intents,
+    skipped,
+    config: createState2(fitted).config
+    // normalized once more: it must be a config the engine takes
+  };
+}
+
+// cli/tune-report.ts
+var signed = (x, digits) => `${x >= 0 ? "+" : ""}${x.toFixed(digits)}`;
+var plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+function note(fit, priorEpisodes) {
+  if (fit.hits + fit.misses === 0) return "never seen in a counted episode";
+  const notes = [];
+  if (fit.weight === null) notes.push("no measurable lift, left out of the config");
+  if (fit.thin) notes.push(`thin: ${fit.contrast.toFixed(1)} of ${priorEpisodes} contrast`);
+  return notes.join("; ");
+}
+function signalTable(fits, priorEpisodes, withCurrent) {
+  const headers = [
+    "signal",
+    "weight",
+    ...withCurrent ? ["was"] : [],
+    "90% interval",
+    "lift",
+    "with: hits / misses",
+    "without: outcomes / episodes",
+    "note"
+  ];
+  return table(
+    headers,
+    fits.map((f) => [
+      f.signal,
+      num(f.weight, 2),
+      ...withCurrent ? [num(f.current, 2)] : [],
+      `${f.low.toFixed(2)} to ${f.high.toFixed(2)}`,
+      signed(f.lift, 2),
+      `${f.hits} / ${f.misses}`,
+      `${f.outcomesWithout} / ${f.without}`,
+      note(f, priorEpisodes)
+    ])
+  );
+}
+function formatIntent2(fit) {
+  const out = [];
+  const excluded = fit.excluded > 0 ? `, ${plural(fit.excluded, "episode")} left out (a reveal was live)` : "";
+  out.push(
+    `${fit.intent}: outcome ${fit.outcome}, ${plural(fit.installs, "install")}, ${plural(fit.episodes, "counted episode")}, ${fit.outcomes} with the outcome${excluded}`
+  );
+  out.push("");
+  out.push(
+    table(
+      ["knob", "fitted", "was", "from"],
+      [
+        [
+          "prior",
+          fit.prior.value.toFixed(4),
+          String(fit.prior.current),
+          `${fit.outcomes} of ${fit.episodes} episodes ended with the outcome, smoothed (${fit.outcomes}+1)/(${fit.episodes}+2)`
+        ],
+        [
+          "priorStrength",
+          num(fit.priorStrength.value, 1),
+          num(fit.priorStrength.current, 1),
+          fit.priorStrength.note
+        ],
+        [
+          "halfLife",
+          formatDuration(fit.halfLife.value),
+          formatDuration(fit.halfLife.current),
+          fit.halfLife.note
+        ]
+      ]
+    )
+  );
+  out.push("");
+  if (fit.signals.length === 0) {
+    out.push("No declared signals.");
+  } else {
+    out.push(signalTable(fit.signals, fit.priorEpisodes, true));
+  }
+  out.push("");
+  out.push(
+    `Half-life grid, Brier score against "the outcome follows within ${formatDuration(fit.halfLife.window)}" (lower is better): ${fit.halfLife.curve.map(
+      (p) => `${formatDuration(p.halfLife)} ${num(p.brier, 3)}${p.halfLife === fit.halfLife.value && fit.halfLife.source === "grid" ? " *" : ""}`
+    ).join(", ")}`
+  );
+  if (fit.candidates.length > 0) {
+    out.push("");
+    out.push(
+      "Candidates: every other event in the log, measured the same way. Add one as a signal only if it says something your signals do not already say."
+    );
+    out.push(signalTable(fit.candidates, fit.priorEpisodes, false));
+  }
+  return out.join("\n");
+}
+function formatTuneText(report) {
+  const out = [];
+  out.push(
+    `oracular tune: ${plural(report.installs, "install")}, ${report.records} records (${report.shadow} shadow, ${report.live} live), ${formatTime(report.start)} to ${formatTime(report.end)}`
+  );
+  out.push(
+    `Counted: ${report.scored === "shadow" ? "shadow episodes only" : "every episode, live included"}. Durations assume \`at\` is in milliseconds. Every number is a starting point: the engine corrects the weights per user.`
+  );
+  for (const intent of report.intents) {
+    out.push("");
+    out.push(formatIntent2(intent));
+  }
+  for (const { intent, reason } of report.skipped) {
+    out.push("");
+    out.push(`${intent}: skipped, ${reason}.`);
+  }
+  if (report.intents.length > 0) {
+    out.push("");
+    out.push(
+      "Config with every fitted value swapped in (paste it, or pass it to oracular replay --config):"
+    );
+    out.push(JSON.stringify(report.config, null, 2));
+  }
+  return `${out.join("\n")}
+`;
+}
+function formatTuneJson(report) {
+  return `${JSON.stringify(report, null, 2)}
+`;
+}
+
 // cli/run.ts
 var UsageError = class extends Error {
 };
-var HELP = `Usage: oracular replay <log.ndjson>... --config <file> [options]
+var DOCS = "https://yuribenjamin.github.io/oracular/guide/shadow-mode";
+var USAGE = `Usage: oracular <command> [options]
+
+Commands:
+  replay <log.ndjson>... --config <file>   score a recorder log against a config: precision,
+                                           recall, lead time, reveals per user and calibration
+  tune <log.ndjson>... --config <file>     seed a config from a recorder log: prior, prior
+                                           strength, weights and half-life, read off what the
+                                           engine itself counts
+
+Run "oracular <command> --help" for the command's options.
+  -h, --help             show this help
+  -v, --version          print the version
+
+Docs: ${DOCS}
+`;
+var REPLAY_HELP = `Usage: oracular replay <log.ndjson>... --config <file> [options]
 
 Replays a recorder log (see the Shadow mode guide) through the engine under a config, and
 reports for every intent and threshold: precision, recall, lead time from reveal to outcome,
@@ -445,7 +931,42 @@ Only shadow periods are scored by default; a log with live records gets a warnin
 with nothing but live records is refused unless --include-live is given.
 
 Exit codes: 0 report printed, 1 unreadable input or nothing to score, 2 usage error.
-Docs: https://yuribenjamin.github.io/oracular/guide/shadow-mode
+Docs: ${DOCS}
+`;
+var TUNE_HELP = `Usage: oracular tune <log.ndjson>... --config <file> [options]
+
+Seeds a config from a recorder log (see the Shadow mode guide). Grouped by install, it reads what
+the engine itself counts: the base rate becomes the prior, the spread of per-install base rates
+the prior strength, each signal's lift over the episodes without it its weight, and the half-life
+that predicts the log best under replay (lowest Brier score) wins a grid search. Prints the fit,
+with sample sizes and a 90% interval per weight, and the config to paste.
+
+Options:
+  --config <file>        the config to start from: a .json file, or a .js, .mjs or .cjs module
+                         whose default (or \`config\`) export is the config. A top-level "$schema"
+                         key in a .json file is ignored. Its intents, outcome names and signals
+                         say what to fit; what tune cannot read from the log is kept as it is
+  --intent <name>        fit only this intent; repeat for more
+                         (default: every intent that declares an outcome)
+  --half-lives <list>    half-lives to try, comma separated: 12h,1d,3d,7d
+                         (default: 1h, 6h, 1d, 3d, 7d, 14d, 30d, plus the intent's current value)
+  --window <duration>    how long after a point an outcome still counts for it when the grid is
+                         scored: 3d, 12h, 90m (default: each intent's reveal cooldown; needed
+                         when that is 0). A plain number is in the unit of \`at\`; the suffixes
+                         ms, s, m, h, d and w assume milliseconds
+  --all-events           also measure every other event name in the log as a candidate signal
+  --include-live         also count episodes in which reveals were live. While reveals are
+                         shown they cause outcomes, so the prior and weights there overstate
+                         the signals
+  --json                 print the report as JSON
+  -h, --help             show this help
+
+Only shadow periods are counted by default: an episode in which any record was live is left out,
+a log with live records gets a warning, and a log with nothing but live records is refused unless
+--include-live is given. Every number is a starting point: the engine corrects weights per user.
+
+Exit codes: 0 report printed, 1 unreadable input or nothing to fit, 2 usage error.
+Docs: ${DOCS}#tune
 `;
 var UNITS = {
   ms: 1,
@@ -456,7 +977,7 @@ var UNITS = {
   w: 6048e5
 };
 function parseDuration(text, flag) {
-  const match = /^(\d+(?:\.\d+)?)(ms|s|m|h|d|w)?$/.exec(text);
+  const match = /^(\d+(?:\.\d+)?)(ms|s|m|h|d|w)?$/.exec(text.trim());
   const value = match === null ? Number.NaN : Number(match[1]) * UNITS[match[2] ?? "ms"];
   if (!(value > 0) || !Number.isFinite(value)) {
     throw new UsageError(
@@ -476,8 +997,10 @@ function parseThresholds(text) {
     return t;
   });
 }
-function parseReplayArgs(argv) {
-  const out = { logs: [], includeLive: false, json: false, help: false };
+function parseDurations(text, flag) {
+  return text.split(",").map((part) => parseDuration(part, flag));
+}
+function parseFlags(argv, flags, positional) {
   for (let i = 0; i < argv.length; i++) {
     let flag = argv[i];
     let inline;
@@ -497,40 +1020,82 @@ function parseReplayArgs(argv) {
     const noValue = () => {
       if (inline !== void 0) throw new UsageError(`${flag} takes no value`);
     };
-    switch (flag) {
-      case "--config":
-        out.config = value();
-        break;
-      case "--thresholds":
+    const handler = flags[flag];
+    if (handler !== void 0) handler(value, noValue);
+    else if (flag.startsWith("-")) throw new UsageError(`unknown option ${flag}`);
+    else positional(flag);
+  }
+}
+function commonFlags(out) {
+  return {
+    "--config": (value) => {
+      out.config = value();
+    },
+    "--window": (value) => {
+      out.window = parseDuration(value(), "--window");
+    },
+    "--intent": (value) => {
+      out.intents = [...out.intents ?? [], value()];
+    },
+    "--include-live": (_value, noValue) => {
+      noValue();
+      out.includeLive = true;
+    },
+    "--json": (_value, noValue) => {
+      noValue();
+      out.json = true;
+    },
+    "--help": () => {
+      out.help = true;
+    },
+    "-h": () => {
+      out.help = true;
+    }
+  };
+}
+function requireLogsAndConfig(out, command) {
+  if (out.help) return;
+  if (out.logs.length === 0) throw new UsageError(`${command} needs at least one log file`);
+  if (out.config === void 0) throw new UsageError(`${command} needs --config <file>`);
+}
+function parseReplayArgs(argv) {
+  const out = { logs: [], includeLive: false, json: false, help: false };
+  parseFlags(
+    argv,
+    {
+      ...commonFlags(out),
+      "--thresholds": (value) => {
         out.thresholds = parseThresholds(value());
-        break;
-      case "--window":
-        out.window = parseDuration(value(), "--window");
-        break;
-      case "--intent":
-        out.intents = [...out.intents ?? [], value()];
-        break;
-      case "--include-live":
-        noValue();
-        out.includeLive = true;
-        break;
-      case "--json":
+      }
+    },
+    (arg) => out.logs.push(arg)
+  );
+  requireLogsAndConfig(out, "replay");
+  return out;
+}
+function parseTuneArgs(argv) {
+  const out = {
+    logs: [],
+    includeLive: false,
+    json: false,
+    help: false,
+    allEvents: false
+  };
+  parseFlags(
+    argv,
+    {
+      ...commonFlags(out),
+      "--half-lives": (value) => {
+        out.halfLives = parseDurations(value(), "--half-lives");
+      },
+      "--all-events": (_value, noValue) => {
         noValue();
-        out.json = true;
-        break;
-      case "--help":
-      case "-h":
-        out.help = true;
-        break;
-      default:
-        if (flag.startsWith("-")) throw new UsageError(`unknown option ${flag}`);
-        out.logs.push(flag);
-    }
-  }
-  if (!out.help) {
-    if (out.logs.length === 0) throw new UsageError("replay needs at least one log file");
-    if (out.config === void 0) throw new UsageError("replay needs --config <file>");
-  }
+        out.allEvents = true;
+      }
+    },
+    (arg) => out.logs.push(arg)
+  );
+  requireLogsAndConfig(out, "tune");
   return out;
 }
 function version() {
@@ -562,12 +1127,7 @@ async function loadConfig(path, io) {
   }
   return value;
 }
-async function replayCommand(argv, io) {
-  const args = parseReplayArgs(argv);
-  if (args.help) {
-    io.stdout(HELP);
-    return 0;
-  }
+async function loadCheckedConfig(args, io) {
   const configPath = resolve(io.cwd, args.config);
   const config = await loadConfig(configPath, io);
   let declared;
@@ -583,33 +1143,42 @@ async function replayCommand(argv, io) {
       throw new UsageError(`--intent ${name}: the config declares ${declared.join(", ")}`);
     }
   }
+  return config;
+}
+function readLogs(files, io) {
   const entries = [];
-  for (const file of args.logs) {
+  for (const file of files) {
     const parsed = parseLog(io.readFile(resolve(io.cwd, file)), file);
     for (const warning of parsed.warnings) io.stderr(`oracular: warning: ${warning}
 `);
     entries.push(...parsed.entries);
   }
   if (entries.length === 0) throw new Error("the log holds no records");
+  return entries;
+}
+function checkModes(entries, includeLive, io, wording) {
   const live = entries.filter((e) => e.mode === "live").length;
   const shadow = entries.length - live;
-  if (shadow === 0 && !args.includeLive) {
-    throw new Error(
-      "every record in the log is live, so there is nothing to measure. Replay measures the engine where reveals were not shown; once they are, the reveal itself causes outcomes. Pass --include-live to score the live records anyway, knowing precision and recall are contaminated."
-    );
-  }
-  if (live > 0 && !args.includeLive) {
-    io.stderr(
-      `oracular: warning: the log mixes shadow and live records (${live} of ${entries.length} live). Only shadow periods are scored: a reveal, point or outcome whose window touches a live record is left out. Pass --include-live to score everything.
-`
-    );
-  }
-  if (live > 0 && args.includeLive) {
-    io.stderr(
-      `oracular: warning: scoring ${live} live records as asked. While reveals are shown they cause outcomes, so precision and recall over live periods overstate the engine.
-`
-    );
+  if (shadow === 0 && !includeLive) throw new Error(wording.refused);
+  if (live > 0 && !includeLive)
+    io.stderr(`oracular: warning: ${wording.mixed(live, entries.length)}
+`);
+  if (live > 0 && includeLive) io.stderr(`oracular: warning: ${wording.included(live)}
+`);
+}
+async function replayCommand(argv, io) {
+  const args = parseReplayArgs(argv);
+  if (args.help) {
+    io.stdout(REPLAY_HELP);
+    return 0;
   }
+  const config = await loadCheckedConfig(args, io);
+  const entries = readLogs(args.logs, io);
+  checkModes(entries, args.includeLive, io, {
+    refused: "every record in the log is live, so there is nothing to measure. Replay measures the engine where reveals were not shown; once they are, the reveal itself causes outcomes. Pass --include-live to score the live records anyway, knowing precision and recall are contaminated.",
+    mixed: (live, total) => `the log mixes shadow and live records (${live} of ${total} live). Only shadow periods are scored: a reveal, point or outcome whose window touches a live record is left out. Pass --include-live to score everything.`,
+    included: (live) => `scoring ${live} live records as asked. While reveals are shown they cause outcomes, so precision and recall over live periods overstate the engine.`
+  });
   const options = { includeLive: args.includeLive };
   if (args.thresholds !== void 0) options.thresholds = args.thresholds;
   if (args.window !== void 0) options.window = args.window;
@@ -624,11 +1193,44 @@ async function replayCommand(argv, io) {
   io.stdout(args.json ? formatJson(report) : formatText(report));
   return 0;
 }
+async function tuneCommand(argv, io) {
+  const args = parseTuneArgs(argv);
+  if (args.help) {
+    io.stdout(TUNE_HELP);
+    return 0;
+  }
+  const config = await loadCheckedConfig(args, io);
+  const entries = readLogs(args.logs, io);
+  checkModes(entries, args.includeLive, io, {
+    refused: "every record in the log is live, so there is nothing to fit. Tune reads the engine where reveals were not shown; once they are, the reveal itself causes outcomes. Pass --include-live to count the live episodes anyway, knowing the prior and the weights are contaminated.",
+    mixed: (live, total) => `the log mixes shadow and live records (${live} of ${total} live). Only shadow episodes are counted: an episode in which any record was live is left out. Pass --include-live to count everything.`,
+    included: (live) => `counting ${live} live records as asked. While reveals are shown they cause outcomes, so the prior and the weights fitted over live periods overstate the signals.`
+  });
+  const options = { includeLive: args.includeLive, allEvents: args.allEvents };
+  if (args.halfLives !== void 0) options.halfLives = args.halfLives;
+  if (args.window !== void 0) options.window = args.window;
+  if (args.intents !== void 0) options.intents = args.intents;
+  let report;
+  try {
+    report = tune(entries, config, options);
+  } catch (error) {
+    if (error instanceof RangeError) throw new UsageError(error.message);
+    throw error;
+  }
+  if (report.installs < 2 * MIN_INSTALLS_FOR_SPREAD) {
+    io.stderr(
+      `oracular: warning: ${report.installs} install${report.installs === 1 ? "" : "s"} in the log. Treat every number as a rough starting point: the spread of base rates needs ${MIN_INSTALLS_FOR_SPREAD} installs, and a weight needs episodes both with and without its signal.
+`
+    );
+  }
+  io.stdout(args.json ? formatTuneJson(report) : formatTuneText(report));
+  return 0;
+}
 async function run(argv, io) {
   try {
     const [command, ...rest] = argv;
     if (command === void 0 || command === "--help" || command === "-h" || command === "help") {
-      io.stdout(HELP);
+      io.stdout(USAGE);
       return 0;
     }
     if (command === "--version" || command === "-v") {
@@ -636,8 +1238,9 @@ async function run(argv, io) {
 `);
       return 0;
     }
-    if (command !== "replay") throw new UsageError(`unknown command ${JSON.stringify(command)}`);
-    return await replayCommand(rest, io);
+    if (command === "replay") return await replayCommand(rest, io);
+    if (command === "tune") return await tuneCommand(rest, io);
+    throw new UsageError(`unknown command ${JSON.stringify(command)}`);
   } catch (error) {
     if (error instanceof UsageError) {
       io.stderr(`oracular: ${error.message}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oracular",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "On-device intent engine. Your app learns when the user is ready. Nothing leaves the device.",
   "keywords": [
     "oracular",