oracular 0.5.2 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.6.0
+
+### Minor Changes
+
+- [#32](https://github.com/Yuribenjamin/oracular/pull/32) [`6951d70`](https://github.com/Yuribenjamin/oracular/commit/6951d70b4ff1e654ab17a61357d882fd82240968) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - **Cross-episode attribution.** `IntentConfig.attribution` is how long a closed episode's signals wait for the outcome before they take a miss. Until now a signal earned a hit only when the outcome arrived in the same episode, so for an intent that builds over days the sessions that built it took misses and the session where the user acted got all the credit. With a window set, an episode that ends without the outcome is held instead of counted; when the outcome arrives inside the window, each held episode gets the share `2^(−age / halfLife)` of a hit that its evidence still holds, and the rest of a miss, so every episode still counts exactly once and the contrast that learning rests on is unchanged; when the window passes, the episode is a miss recorded at the moment the window ended. Reads settle what has expired in what they show and store nothing. Off unless set: every state and estimate without `attribution` is exactly what it was.
+  
+  **State version 3.** `IntentState.pending` lists the episodes waiting, at most 32 per intent (past that the oldest is a miss at once). `deserialize` upgrades version 1 and 2 states on its own, adding an empty list and changing no number; oracular 0.5.x cannot read a version 3 state, so the rollback advice stays: catch and start from `createState(config)`. `PendingEpisode` is exported as a type; the config JSON Schema gains `attribution`.
+  
+  `oracular tune` counts each episode's own verdict, with the window off while counting, keeps it on for the half-life grid, and keeps whatever `attribution` you set in the printed config.
+
 ## 0.5.2
 
 ### Patch Changes

package/README.md

@@ -107,7 +107,7 @@ Before any update or reading, the evidence decays by 2^(−Δt / halfLife), wher
 
 ### The user's history corrects your weights
 
-Events happen inside **episodes** (sessions). An episode ends when you call `endEpisode`, or on its own after `episodeTimeout` of inactivity. Signals seen in the episode are remembered per intent. When the intent's `outcome` event arrives, each remembered signal gets a **hit**; when the episode ends without it, each gets a **miss**. The engine also counts, per intent, how many episodes ended with and without the outcome: the intent's **base rate**.
+Events happen inside **episodes** (sessions). An episode ends when you call `endEpisode`, or on its own after `episodeTimeout` of inactivity. Signals seen in the episode are remembered per intent. When the intent's `outcome` event arrives, each remembered signal gets a **hit**; when the episode ends without it, each gets a **miss**, or, with `attribution` set on the intent, the episode waits and takes the share `2^(−age / halfLife)` of a hit if the outcome arrives inside the window. The engine also counts, per intent, how many episodes ended with and without the outcome: the intent's **base rate**.
 
 A signal's weight is then a blend of your prior and the learned estimate:
 
@@ -252,7 +252,7 @@ serialize(state): string
 deserialize(json: string, opts?: { config?: EngineConfig; migrate?: Migrate }): EngineState
 validateConfig(config: unknown): EngineConfig   // the checks createState runs, without a state; returns the normalized copy
 ms.seconds(n), ms.minutes(n), ms.hours(n), ms.days(n), ms.weeks(n)   // durations in milliseconds
-STATE_VERSION // 2
+STATE_VERSION // 3
 RECORD_VERSION // 1
 ```
 
@@ -278,6 +278,7 @@ interface IntentConfig {
   outcome?: string;                 // event that confirms the intent
   resetOnOutcome?: boolean;         // default true
   saturate?: boolean;               // repeats within an episode add less; default: episodeTimeout is set
+  attribution?: number;             // how long a closed episode waits for the outcome before it is a miss; off if omitted
   reveal?: RevealOptions;
 }
 
@@ -337,7 +338,7 @@ 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.
 
-States saved by an older version of this library are upgraded on load: `deserialize` migrates the state shape written by oracular 0.1.0 to 0.2.x (`STATE_VERSION` 1) 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`:
+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.5.x (`STATE_VERSION` 1 and 2) 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`:
 
 ```ts
 deserialize(saved, {
@@ -393,7 +394,7 @@ npx oracular tune 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, 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).
+Now is 0.4, themed **learning that matches how people behave**. Shipped so far: cross-episode attribution (`attribution` on an intent, so a session's signals earn a share of an outcome days later), `npx oracular tune` to seed a config from a shadow log, and small ergonomics (`validateConfig`, `ms`, a JSON Schema for the config). Presets come once tune has run on more real logs. 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

@@ -575,6 +575,16 @@ function withoutLearnedDecay(config) {
   );
   return { ...config, learning };
 }
+function withoutAttribution(config) {
+  const intents = Object.fromEntries(
+    Object.entries(config.intents).map(([name, intent]) => {
+      if (intent.attribution === void 0) return [name, intent];
+      const { attribution: _attribution, ...rest } = intent;
+      return [name, rest];
+    })
+  );
+  return { ...config, intents };
+}
 function cooldownOf(base, name) {
   return predict2(markRevealed2(base, name, 0), name, 0).suppressedUntil ?? 0;
 }
@@ -613,7 +623,7 @@ function tune(entries, config, options = {}) {
   const candidatesOf = (intent) => options.allEvents === true ? [...eventNames].filter(
     (name) => name !== "__proto__" && name !== intent.outcome && !Object.hasOwn(intent.signals, name)
   ) : [];
-  let countConfig = withoutLearnedDecay(normalized);
+  let countConfig = withoutAttribution(withoutLearnedDecay(normalized));
   const plans = fitting.map((name) => {
     const intent = normalized.intents[name];
     const candidates = candidatesOf(intent);

package/dist/index.cjs

@@ -49,6 +49,86 @@ function mapRecord(record2, fn) {
   return out;
 }
 
+// src/learning.ts
+var NONE = { hits: 0, misses: 0 };
+function decayLearned(state, learning, at) {
+  if (state.learnedAt === null) return { ...state, learnedAt: at };
+  const learnedAt = Math.max(state.learnedAt, at);
+  const d = learning.halfLife === null ? 1 : decayFactor(at - state.learnedAt, learning.halfLife);
+  if (d === 1) return learnedAt === state.learnedAt ? state : { ...state, learnedAt };
+  return {
+    ...state,
+    learnedAt,
+    learned: mapRecord(state.learned, (r) => ({ hits: r.hits * d, misses: r.misses * d })),
+    episodes: { hits: state.episodes.hits * d, misses: state.episodes.misses * d }
+  };
+}
+function signalWeights(state, intent, learning, signal) {
+  const initial = getOwn(intent.signals, signal);
+  if (initial === void 0) {
+    throw new RangeError(`oracular: ${JSON.stringify(signal)} is not a signal of this intent`);
+  }
+  const record2 = getOwn(state.learned, signal) ?? NONE;
+  const nWith = record2.hits + record2.misses;
+  const qWith = laplace(record2.hits, nWith);
+  const totalEpisodes = state.episodes.hits + state.episodes.misses;
+  const nWithout = Math.max(0, totalEpisodes - nWith);
+  const outcomesWithout = Math.min(nWithout, Math.max(0, state.episodes.hits - record2.hits));
+  const qWithout = laplace(outcomesWithout, nWithout);
+  const learned = nWith === 0 ? 0 : learning.gain * Math.abs(initial) * lift(qWith, qWithout);
+  const nEff = nWith + nWithout === 0 ? 0 : nWith * nWithout / (nWith + nWithout);
+  const k = learning.priorEpisodes;
+  const effective = (k * initial + nEff * learned) / (k + nEff);
+  return { initial, learned, effective, hits: record2.hits, misses: record2.misses };
+}
+function recordEpisode(state, signals, credit) {
+  const miss = 1 - credit;
+  const learned = { ...state.learned };
+  for (const signal of signals) {
+    const r = getOwn(learned, signal) ?? NONE;
+    learned[signal] = { hits: r.hits + credit, misses: r.misses + miss };
+  }
+  const episodes = { hits: state.episodes.hits + credit, misses: state.episodes.misses + miss };
+  return { ...state, learned, episodes };
+}
+
+// src/attribution.ts
+var MAX_PENDING = 32;
+function expiry(episode, intent) {
+  return episode.endedAt + (intent.attribution ?? 0);
+}
+function settlePending(state, intent, learning, at) {
+  let is = state;
+  let settled = 0;
+  for (const episode of state.pending) {
+    const end = expiry(episode, intent);
+    if (!(end < at)) break;
+    is = recordEpisode(decayLearned(is, learning, end), episode.seen, 0);
+    settled++;
+  }
+  if (settled > 0) is = { ...is, pending: state.pending.slice(settled) };
+  return decayLearned(is, learning, at);
+}
+function deferEpisode(state, seen, endedAt) {
+  const pending = insert(state.pending, { endedAt, seen: [...seen] });
+  if (pending.length <= MAX_PENDING) return { ...state, pending };
+  const [oldest, ...rest] = pending;
+  return { ...recordEpisode(state, oldest.seen, 0), pending: rest };
+}
+function insert(pending, episode) {
+  let i = pending.length;
+  while (i > 0 && pending[i - 1].endedAt > episode.endedAt) i--;
+  return [...pending.slice(0, i), episode, ...pending.slice(i)];
+}
+function creditPending(state, intent, at) {
+  if (state.pending.length === 0) return state;
+  let is = state;
+  for (const episode of state.pending) {
+    is = recordEpisode(is, episode.seen, decayFactor(at - episode.endedAt, intent.halfLife));
+  }
+  return { ...is, pending: [] };
+}
+
 // src/intent.ts
 function priorCounts(intent) {
   return {
@@ -65,6 +145,7 @@ function initIntent(intent) {
     contributions: {},
     learned: {},
     episodes: { hits: 0, misses: 0 },
+    pending: [],
     learnedAt: null,
     lastRevealedAt: null,
     lastOutcomeAt: null,
@@ -101,48 +182,6 @@ function resetToPrior(state, intent) {
   return withContributions(state, intent, {});
 }
 
-// src/learning.ts
-var NONE = { hits: 0, misses: 0 };
-function decayLearned(state, learning, at) {
-  if (state.learnedAt === null) return { ...state, learnedAt: at };
-  const learnedAt = Math.max(state.learnedAt, at);
-  const d = learning.halfLife === null ? 1 : decayFactor(at - state.learnedAt, learning.halfLife);
-  if (d === 1) return learnedAt === state.learnedAt ? state : { ...state, learnedAt };
-  return {
-    ...state,
-    learnedAt,
-    learned: mapRecord(state.learned, (r) => ({ hits: r.hits * d, misses: r.misses * d })),
-    episodes: { hits: state.episodes.hits * d, misses: state.episodes.misses * d }
-  };
-}
-function signalWeights(state, intent, learning, signal) {
-  const initial = getOwn(intent.signals, signal);
-  if (initial === void 0) {
-    throw new RangeError(`oracular: ${JSON.stringify(signal)} is not a signal of this intent`);
-  }
-  const record2 = getOwn(state.learned, signal) ?? NONE;
-  const nWith = record2.hits + record2.misses;
-  const qWith = laplace(record2.hits, nWith);
-  const totalEpisodes = state.episodes.hits + state.episodes.misses;
-  const nWithout = Math.max(0, totalEpisodes - nWith);
-  const outcomesWithout = Math.min(nWithout, Math.max(0, state.episodes.hits - record2.hits));
-  const qWithout = laplace(outcomesWithout, nWithout);
-  const learned = nWith === 0 ? 0 : learning.gain * Math.abs(initial) * lift(qWith, qWithout);
-  const nEff = nWith + nWithout === 0 ? 0 : nWith * nWithout / (nWith + nWithout);
-  const k = learning.priorEpisodes;
-  const effective = (k * initial + nEff * learned) / (k + nEff);
-  return { initial, learned, effective, hits: record2.hits, misses: record2.misses };
-}
-function recordEpisode(state, signals, outcome) {
-  const learned = { ...state.learned };
-  for (const signal of signals) {
-    const r = getOwn(learned, signal) ?? NONE;
-    learned[signal] = outcome ? { hits: r.hits + 1, misses: r.misses } : { hits: r.hits, misses: r.misses + 1 };
-  }
-  const episodes = outcome ? { hits: state.episodes.hits + 1, misses: state.episodes.misses } : { hits: state.episodes.hits, misses: state.episodes.misses + 1 };
-  return { ...state, learned, episodes };
-}
-
 // src/config.ts
 var DEFAULT_THRESHOLD = 0.5;
 var DEFAULT_Z = 1.28;
@@ -158,6 +197,7 @@ var INTENT_KEYS = [
   "outcome",
   "resetOnOutcome",
   "saturate",
+  "attribution",
   "reveal"
 ];
 var REVEAL_KEYS = ["threshold", "z", "cooldown"];
@@ -287,6 +327,9 @@ function normalizeIntentConfig(value, path) {
     if (typeof record2.saturate !== "boolean") typeError(`${path}.saturate`, "must be a boolean");
     out.saturate = record2.saturate;
   }
+  if (record2.attribution !== void 0) {
+    out.attribution = expectPositive(record2.attribution, `${path}.attribution`);
+  }
   if (record2.reveal !== void 0)
     out.reveal = normalizeRevealOptions(record2.reveal, `${path}.reveal`);
   return out;
@@ -409,7 +452,7 @@ function markResolved(episode, intent) {
 }
 
 // src/version.ts
-var STATE_VERSION = 2;
+var STATE_VERSION = 3;
 var RECORD_VERSION = 1;
 
 // src/state.ts
@@ -440,7 +483,8 @@ function getIntentState(state, name, intent) {
 
 // src/assess.ts
 function assessIntent(state, name, intent, learning, at) {
-  return decayLearned(decayIntent(getIntentState(state, name, intent), intent, at), learning, at);
+  const is = decayIntent(getIntentState(state, name, intent), intent, at);
+  return settlePending(is, intent, learning, at);
 }
 function cooldownEnd(since, cooldown, at) {
   if (since === null) return null;
@@ -567,7 +611,7 @@ function observe(state, event) {
     if (!isSignal && !isOutcome) continue;
     let is = getIntentState(s, intentName, intent);
     is = decayIntent(is, intent, at);
-    is = decayLearned(is, learning, at);
+    is = settlePending(is, intent, learning, at);
     if (isSignal) {
       const { effective } = signalWeights(is, intent, learning, name);
       const n = occurrences(episode, intentName, name) + 1;
@@ -577,7 +621,8 @@ function observe(state, event) {
       if (!isOutcome) episode = markSeen(episode, intentName, name);
     }
     if (isOutcome) {
-      is = recordEpisode(is, episodeRecord(episode, intentName).seen, true);
+      is = recordEpisode(is, episodeRecord(episode, intentName).seen, 1);
+      is = creditPending(is, intent, at);
       episode = markResolved(episode, intentName);
       is = { ...is, lastOutcomeAt: at };
       if (intent.resetOnOutcome ?? true) is = resetToPrior(is, intent);
@@ -600,8 +645,8 @@ function closeEpisode(state, at) {
     const record2 = episodeRecord(state.episode, intentName);
     if (record2.resolved) continue;
     let is = getIntentState(state, intentName, intent);
-    is = decayLearned(is, learning, at);
-    is = recordEpisode(is, record2.seen, false);
+    is = settlePending(is, intent, learning, at);
+    is = intent.attribution === void 0 ? recordEpisode(is, record2.seen, 0) : deferEpisode(is, record2.seen, at);
     intents[intentName] = is;
   }
   return { ...state, intents, episode: emptyEpisode() };
@@ -709,7 +754,8 @@ function createEndRecord(at, opts) {
 
 // src/migrate.ts
 var MIGRATIONS = {
-  1: fromV1
+  1: fromV1,
+  2: fromV2
 };
 function canMigrate(version) {
   return hasOwn(MIGRATIONS, String(version));
@@ -740,6 +786,16 @@ function fromV1(stored) {
   }
   return { ...stored, version: 2, episode: { ...episode, intents } };
 }
+function fromV2(stored) {
+  if (!isRecord(stored.intents)) return { ...stored, version: 3 };
+  const intents = {};
+  for (const key of Object.keys(stored.intents)) {
+    if (key === "__proto__") continue;
+    const intent = stored.intents[key];
+    intents[key] = isRecord(intent) ? { ...intent, pending: [] } : intent;
+  }
+  return { ...stored, version: 3, intents };
+}
 
 // src/serialize.ts
 function serialize(state) {
@@ -826,6 +882,19 @@ function mapOwn(value, path, fn) {
   }
   return out;
 }
+function pendingEpisodes(value, path) {
+  if (!Array.isArray(value)) typeError2(path, "must be an array");
+  if (value.length > MAX_PENDING) {
+    throw new RangeError(`oracular: ${path} must hold at most ${MAX_PENDING} episodes`);
+  }
+  return value.map((item, i) => {
+    const r = record(item, `${path}[${i}]`);
+    if (!Array.isArray(r.seen) || !r.seen.every((s) => typeof s === "string")) {
+      typeError2(`${path}[${i}].seen`, "must be an array of strings");
+    }
+    return { endedAt: finite(r.endedAt, `${path}[${i}].endedAt`), seen: r.seen };
+  });
+}
 function intentState(value, path) {
   const r = record(value, path);
   const revealCount = finite(r.revealCount, `${path}.revealCount`);
@@ -839,6 +908,7 @@ function intentState(value, path) {
     contributions: mapOwn(r.contributions, `${path}.contributions`, contribution),
     learned: mapOwn(r.learned, `${path}.learned`, signalRecord),
     episodes: signalRecord(r.episodes, `${path}.episodes`),
+    pending: pendingEpisodes(r.pending, `${path}.pending`),
     learnedAt: nullOrFinite(r.learnedAt, `${path}.learnedAt`),
     lastRevealedAt: nullOrFinite(r.lastRevealedAt, `${path}.lastRevealedAt`),
     lastOutcomeAt: nullOrFinite(r.lastOutcomeAt, `${path}.lastOutcomeAt`),
@@ -907,6 +977,12 @@ function keep(source, declared) {
   }
   return out;
 }
+function keepPending(pending, signals) {
+  return pending.map((episode) => ({
+    endedAt: episode.endedAt,
+    seen: episode.seen.filter((s, i) => hasOwn(signals, s) && episode.seen.indexOf(s) === i)
+  })).sort((a, b) => a.endedAt - b.endedAt);
+}
 function reconcile(raw, config) {
   const intents = {};
   const episodeIntents = {};
@@ -916,7 +992,11 @@ function reconcile(raw, config) {
       intents[name] = initIntent(intent);
     } else {
       intents[name] = withContributions(
-        { ...stored, learned: keep(stored.learned, intent.signals) },
+        {
+          ...stored,
+          learned: keep(stored.learned, intent.signals),
+          pending: keepPending(stored.pending, intent.signals)
+        },
         intent,
         keep(stored.contributions, intent.signals)
       );