@chatpanel/events 0.2.0

package/order.js

@@ -0,0 +1,78 @@
+// THE LINEARIZATION RULE — stated once, never varied.
+//
+//   Replay orders events by topological sort over `causes`, breaking ties by
+//   (host, seq) with hosts in lexicographic id order. Wall time is never consulted.
+//
+// This is what makes replay deterministic when two hosts append concurrently. A
+// timestamp is not an order: clocks skew, and two hosts can stamp the same millisecond.
+// `causes` gives a partial order; the tie-break makes it total; neither depends on a
+// clock, so the same set of events linearizes identically on every host, forever.
+//
+// Dangling causes (an id we do not hold, e.g. a partial export) are IGNORED rather than
+// fatal, so a sanitized or truncated trace still replays. A cycle is fatal, because it
+// means the log is corrupt.
+
+import { EventError } from './event.js';
+
+/** (host, seq) with hosts lexicographic — the deterministic tie-break. */
+export function compareEvents(a, b) {
+  if (a.host !== b.host) return a.host < b.host ? -1 : 1;
+  if (a.seq !== b.seq) return a.seq - b.seq;
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0; // total, for identical (host,seq)
+}
+
+/**
+ * Deterministic topological linearization. Pure; input array is not mutated.
+ * @throws EventError('CYCLE') if `causes` contains a cycle.
+ */
+export function linearize(events) {
+  const byId = new Map();
+  for (const e of events) byId.set(e.id, e);
+
+  const indegree = new Map();
+  const dependents = new Map();
+  for (const e of events) {
+    const deps = e.causes.filter((c) => byId.has(c)); // dangling causes ignored
+    indegree.set(e.id, deps.length);
+    for (const d of deps) {
+      if (!dependents.has(d)) dependents.set(d, []);
+      dependents.get(d).push(e.id);
+    }
+  }
+
+  // Kahn's algorithm with a ready-set kept in (host, seq) order, so the output is a
+  // function of the event set alone and not of the input array's order.
+  const ready = events.filter((e) => indegree.get(e.id) === 0).sort(compareEvents);
+  const out = [];
+  while (ready.length > 0) {
+    const next = ready.shift();
+    out.push(next);
+    const kids = dependents.get(next.id);
+    if (!kids) continue;
+    let unlocked = false;
+    for (const kid of kids) {
+      const left = indegree.get(kid) - 1;
+      indegree.set(kid, left);
+      if (left === 0) { ready.push(byId.get(kid)); unlocked = true; }
+    }
+    if (unlocked) ready.sort(compareEvents);
+  }
+
+  if (out.length !== events.length) {
+    const stuck = events.filter((e) => !out.includes(e)).map((e) => e.id);
+    throw new EventError('CYCLE', 'causes contains a cycle', stuck);
+  }
+  return out;
+}
+
+/** True when `causes` never points forward within one host's own sequence. */
+export function causesAreWellFormed(events) {
+  const byId = new Map(events.map((e) => [e.id, e]));
+  for (const e of events) {
+    for (const c of e.causes) {
+      const cause = byId.get(c);
+      if (cause && cause.host === e.host && cause.seq >= e.seq) return false;
+    }
+  }
+  return true;
+}

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@chatpanel/events",
+  "version": "0.2.0",
+  "description": "The canonical ChatPanel event-log and capability contracts \u2014 typed durable facts, clock-free deterministic linearization, schema upcasting, and the invariants the replay harness asserts. Pure, dependency-free ESM shared by the ChatPanel extension, gateway and bridge.",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./adapters.js": "./adapters.js",
+    "./capability.js": "./capability.js",
+    "./citations.js": "./citations.js",
+    "./event.js": "./event.js",
+    "./harness.js": "./harness.js",
+    "./invariants.js": "./invariants.js",
+    "./kernel.js": "./kernel.js",
+    "./loop.js": "./loop.js",
+    "./manifest.js": "./manifest.js",
+    "./mcp-errors.js": "./mcp-errors.js",
+    "./meeting-analyzers.js": "./meeting-analyzers.js",
+    "./order.js": "./order.js",
+    "./ref.js": "./ref.js",
+    "./registry.js": "./registry.js",
+    "./route-graph.js": "./route-graph.js",
+    "./router.js": "./router.js",
+    "./rules.js": "./rules.js",
+    "./search-engines.js": "./search-engines.js",
+    "./sources-retrieval.js": "./sources-retrieval.js",
+    "./sources.js": "./sources.js",
+    "./store.js": "./store.js",
+    "./tool-groups.js": "./tool-groups.js",
+    "./tool-need.js": "./tool-need.js",
+    "./trajectory.js": "./trajectory.js",
+    "./upcast.js": "./upcast.js"
+  },
+  "files": [
+    "index.js",
+    "adapters.js",
+    "capability.js",
+    "citations.js",
+    "event.js",
+    "harness.js",
+    "invariants.js",
+    "kernel.js",
+    "loop.js",
+    "manifest.js",
+    "mcp-errors.js",
+    "meeting-analyzers.js",
+    "order.js",
+    "ref.js",
+    "registry.js",
+    "route-graph.js",
+    "router.js",
+    "rules.js",
+    "search-engines.js",
+    "sources-retrieval.js",
+    "sources.js",
+    "store.js",
+    "tool-groups.js",
+    "tool-need.js",
+    "trajectory.js",
+    "upcast.js",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chatpanel/chatpanel-events.git"
+  },
+  "keywords": [
+    "event-sourcing",
+    "provenance",
+    "audit",
+    "determinism",
+    "capability",
+    "chatpanel"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false
+}

package/ref.js

@@ -0,0 +1,52 @@
+// References — how the log addresses content WITHOUT copying it.
+//
+// An event records "note n_88, lines 10-40, hash H" and never the text. Content that
+// actually entered a model request is written once into a content-addressed blob store
+// keyed by hash, so the same excerpt across a hundred turns costs one copy.
+//
+// Replay resolves a Ref by hash: match => exact reconstruction; blob absent or
+// crypto-shredded => VERIFIED_BUT_UNAVAILABLE. It never silently substitutes today's
+// version of the note, because that would make replay quietly wrong instead of loudly
+// incomplete.
+
+export const REF_KINDS = Object.freeze(['note', 'meeting', 'chat', 'page', 'result', 'blob']);
+
+export const RESOLUTION = Object.freeze({
+  EXACT: 'exact',                              // blob present, hash matches
+  UNAVAILABLE: 'verified-but-unavailable',     // we know what it was; we no longer hold it
+  DRIFTED: 'drifted',                          // source still exists but its hash changed
+});
+
+/** Build a Ref. `hash` is the content hash AT CAPTURE TIME — that is the whole point. */
+export function makeRef({ kind, id, hash, range = null, stored = false }) {
+  if (!REF_KINDS.includes(kind)) throw new TypeError(`ref: unknown kind ${kind}`);
+  if (typeof id !== 'string' || !id) throw new TypeError('ref: id required');
+  if (typeof hash !== 'string' || !hash) throw new TypeError('ref: hash required');
+  const ref = { kind, id, hash };
+  if (range) {
+    if (!Number.isInteger(range.from) || !Number.isInteger(range.to) || range.to < range.from) {
+      throw new TypeError('ref: range must be {from,to} integers with to >= from');
+    }
+    ref.range = { from: range.from, to: range.to };
+  }
+  if (stored) ref.stored = true;
+  return Object.freeze(ref);
+}
+
+export function isRef(v) {
+  return !!v && typeof v === 'object'
+    && REF_KINDS.includes(v.kind)
+    && typeof v.id === 'string' && v.id.length > 0
+    && typeof v.hash === 'string' && v.hash.length > 0;
+}
+
+/**
+ * Classify what a replay can say about a Ref, given what the blob store holds now.
+ * `lookup(ref) -> { hash } | null`. Pure: the caller owns the store.
+ */
+export function resolveRef(ref, lookup) {
+  const got = lookup(ref);
+  if (!got) return { resolution: RESOLUTION.UNAVAILABLE, ref };
+  if (got.hash !== ref.hash) return { resolution: RESOLUTION.DRIFTED, ref, actualHash: got.hash };
+  return { resolution: RESOLUTION.EXACT, ref, value: got.value };
+}

package/registry.js

@@ -0,0 +1,240 @@
+// The capability registry — revertible effects and reactive availability.
+//
+// This is the runtime half of the capability contract: `requires` / `provides` in a
+// declaration (capability.js) only mean something because something binds them here.
+//
+// WHY THIS AND NOT CORDIS. We need exactly two behaviours — effects that carry their own
+// inverse, and dependents that unwind when a capability withdraws and re-arm when it
+// returns. That is roughly 15% of Cordis's surface; we need neither its plugin registry,
+// its Proxy-based ctx, its config schema, its logger nor HMR. At ~200 lines this costs
+// nothing against a first-paint budget that is a release gate, has no CSP surface, and
+// ports to every runtime. The concepts port; the framework does not.
+//
+// THE TWO RULES THAT MATTER, and the bug class each prevents:
+//
+//   1. LIFO disposal. Inverses run in reverse order of registration, so each one meets
+//      the state its own application produced. Anything else hands an inverse a state it
+//      was not built for.
+//
+//   2. Dependents deactivate BEFORE a provider's binding is removed. A component being
+//      torn down because its provider is going away is running its own teardown, and
+//      that teardown frequently NEEDS the very capability being withdrawn — closing a
+//      connection pool means handing connections back to whatever provided them. Remove
+//      the binding first and the teardown reaches for something already gone. This is
+//      the orphaned-monitor / dangling-observer bug class, structurally.
+
+const STATE = Object.freeze({ INACTIVE: 'inactive', ACTIVE: 'active' });
+
+let nextId = 0;
+
+/**
+ * @param onEvent optional hook — `{ event, name, key }`. Kept deliberately independent
+ *        of the event schema so the registry has no dependency on the log; the caller
+ *        maps these to `capability.activated` / `capability.revoked`.
+ */
+export function createRegistry({ onEvent = null } = {}) {
+  const bindings = new Map();      // key -> { value, providerId }
+  const components = new Map();    // id  -> record
+  let settling = false;
+  let disposed = false;
+  let withdrawing = false;   // see withdrawSync — suspends settling inside rule 2's window
+
+  const emit = (event, detail) => { if (onEvent) onEvent({ event, ...detail }); };
+
+  function scopeFor(record) {
+    return {
+      /** Register a revertible effect. The returned disposer runs on deactivation, LIFO. */
+      effect(fn) {
+        const dispose = fn();
+        if (typeof dispose === 'function') record.disposers.push(dispose);
+        return () => {
+          const i = record.disposers.indexOf(dispose);
+          if (i >= 0) { record.disposers.splice(i, 1); dispose(); }
+        };
+      },
+
+      /** Provide a capability. This is itself an effect, so it unwinds with the component. */
+      provide(key, value) {
+        if (bindings.has(key)) throw new Error(`registry: '${key}' is already provided`);
+        bindings.set(key, { value, providerId: record.id });
+        record.provided.add(key);
+        emit('provided', { key, name: record.name });
+        record.disposers.push(() => withdrawSync(key));
+        queueSettle();
+      },
+
+      /** Read a required capability. */
+      get(key) {
+        const b = bindings.get(key);
+        return b ? b.value : undefined;
+      },
+
+      /** A nested component. Disposes with its parent, because that is an effect too. */
+      register(child) {
+        const handle = register(child);
+        record.disposers.push(() => handle.dispose());
+        return handle;
+      },
+
+      get name() { return record.name; },
+    };
+  }
+
+  function satisfied(record) {
+    return record.requires.every((k) => bindings.has(k));
+  }
+
+  function activate(record) {
+    record.state = STATE.ACTIVE;
+    try {
+      record.apply(scopeFor(record));
+    } catch (err) {
+      // A failure is recorded on the component and never propagated to its siblings —
+      // one broken component must not take the system down. Whatever it managed to
+      // register still unwinds.
+      record.state = STATE.INACTIVE;
+      record.error = err;
+      runDisposers(record);
+      emit('failed', { name: record.name, error: err });
+      return;
+    }
+    emit('activated', { name: record.name });
+  }
+
+  function runDisposers(record) {
+    const results = [];
+    // LIFO — rule 1.
+    while (record.disposers.length > 0) {
+      const dispose = record.disposers.pop();
+      try { results.push(dispose()); } catch { /* one bad disposer must not strand the rest */ }
+    }
+    record.provided.clear();
+    return results.filter((r) => r && typeof r.then === 'function');
+  }
+
+  function deactivate(record) {
+    if (record.state !== STATE.ACTIVE) return [];
+    record.state = STATE.INACTIVE;
+    const pending = runDisposers(record);
+    emit('deactivated', { name: record.name });
+    return pending;
+  }
+
+  /**
+   * Rule 2: every ACTIVE dependent stands down BEFORE the binding disappears, so its
+   * teardown can still read the capability it is being torn down over.
+   */
+  function withdrawSync(key) {
+    const binding = bindings.get(key);
+    if (!binding) return;
+    // Rule 2 creates a window: dependents are stood down while the binding they need is
+    // still present, precisely so their teardown can use it. Anything that settles inside
+    // that window sees an inactive component whose requirement is still satisfied and
+    // dutifully re-activates it — the component arms, then disarms again a moment later.
+    //
+    // That happens as soon as a second dependent exists, because tearing IT down withdraws
+    // what IT provided, and a nested withdrawal settles. With one dependent the window was
+    // never entered, which is why this survived until a second one was added.
+    //
+    // So the window is closed rather than the re-activation being detected afterwards:
+    // settling is suspended until the binding is actually gone.
+    const outermost = !withdrawing;
+    withdrawing = true;
+    try {
+      for (const record of components.values()) {
+        if (record.state === STATE.ACTIVE && record.requires.includes(key)) deactivate(record);
+      }
+      bindings.delete(key);
+      emit('withdrawn', { key });
+    } finally {
+      if (outermost) withdrawing = false;
+    }
+    queueSettle();
+  }
+
+  /** Fixpoint: activating one component can satisfy another, and so on. */
+  function settle() {
+    if (settling || disposed) return;
+    settling = true;
+    try {
+      for (let pass = 0; pass < 64; pass++) {
+        let moved = false;
+        for (const record of components.values()) {
+          if (record.error) continue;                       // failed stays failed
+          const ok = satisfied(record);
+          if (ok && record.state === STATE.INACTIVE) { activate(record); moved = true; }
+          else if (!ok && record.state === STATE.ACTIVE) { deactivate(record); moved = true; }
+        }
+        if (!moved) return;
+      }
+      throw new Error('registry: settle did not converge in 64 passes');
+    } finally {
+      settling = false;
+    }
+  }
+
+  function queueSettle() { if (!settling && !withdrawing) settle(); }
+
+  function register({ name, requires = [], apply }) {
+    if (typeof apply !== 'function') throw new TypeError('registry: component.apply required');
+    const record = {
+      id: `c${nextId++}`, name: name || 'anonymous', requires: [...requires], apply,
+      state: STATE.INACTIVE, disposers: [], provided: new Set(), error: null,
+    };
+    components.set(record.id, record);
+    queueSettle();
+    return {
+      get name() { return record.name; },
+      get state() { return record.state; },
+      get error() { return record.error; },
+      async dispose() {
+        const pending = deactivate(record);
+        components.delete(record.id);
+        await Promise.all(pending);
+        queueSettle();
+      },
+    };
+  }
+
+  return {
+    register,
+
+    /** Provide from outside any component — the root of the graph. */
+    provide(key, value) {
+      if (bindings.has(key)) throw new Error(`registry: '${key}' is already provided`);
+      bindings.set(key, { value, providerId: null });
+      emit('provided', { key });
+      queueSettle();
+      return () => withdrawSync(key);
+    },
+
+    get: (key) => (bindings.has(key) ? bindings.get(key).value : undefined),
+    has: (key) => bindings.has(key),
+    keys: () => [...bindings.keys()].sort(),
+
+    /**
+     * What is waiting, and on what. A dependency cycle simply leaves its components
+     * permanently inactive — unlike a deadlock that depends on the schedule, this is
+     * visible from the declarations alone, so a host can report it at load time.
+     */
+    pending() {
+      return [...components.values()]
+        .filter((r) => r.state === STATE.INACTIVE && !r.error)
+        .map((r) => ({ name: r.name, waitingFor: r.requires.filter((k) => !bindings.has(k)) }));
+    },
+
+    active: () => [...components.values()].filter((r) => r.state === STATE.ACTIVE).map((r) => r.name).sort(),
+
+    async dispose() {
+      disposed = true;
+      // Reverse registration order — the whole registry is itself one LIFO stack.
+      const all = [...components.values()].reverse();
+      const pending = all.flatMap((r) => deactivate(r));
+      components.clear();
+      bindings.clear();
+      await Promise.all(pending);
+    },
+  };
+}
+
+export const REGISTRY_STATES = STATE;

package/route-graph.js

@@ -0,0 +1,115 @@
+// The routing decision, as something you can LOOK at.
+//
+// A route currently explains itself in three lines of prose — which model, and two reasons.
+// That is enough to read one decision and not nearly enough to find a wrong one: it cannot
+// say what the alternatives were, how close they came, what was eliminated and why, or where
+// the turn would go next if this model declined. Those are exactly the questions asked when
+// the router picks something surprising, and answering them meant reading the code.
+//
+// So this derives the whole picture from one decision: every candidate with the numbers that
+// decided it, and the failover chain the turn WOULD walk. It is a derivation, not a renderer
+// — no DOM, no colours, no layout — so the side panel, the settings viewer, a desktop app or
+// a CLI can each draw the same graph their own way.
+//
+// THE CHAIN IS COMPUTED BY THE SAME CODE THAT WILL WALK IT (failoverOrder). A projection with
+// its own copy of the ordering would drift from the real thing, and a picture that lies about
+// what the router is going to do is worse than no picture at all.
+//
+// Class R: arithmetic over a decision that has already been made. No model call, no I/O.
+
+import { failoverOrder } from './router.js';
+
+const num = (v) => (Number.isFinite(v) ? v : null);
+
+/**
+ * @param decision the object returned by route()/routeWith().
+ * @param models   every candidate considered, eligible or not (the router's full model list).
+ * @param hops     how far to project the failover chain. The default matches what a user can
+ *                 actually sit through rather than the attempt cap.
+ * @returns { chosen, strategy, reasons, nodes, chain, eliminated }
+ *   nodes   — every candidate, ranked, with why it was eliminated when it was.
+ *   chain   — [chosen, ...replacements], the walk each subsequent decline would take.
+ */
+export function routeGraph({ decision = null, models = [], hops = 4 } = {}) {
+  if (!decision) return { chosen: null, strategy: null, reasons: [], constraints: [], nodes: [], chain: [], eliminated: 0 };
+
+  const eligible = decision.eligible || [];
+  const eligibleIds = new Set(eligible.map((m) => m.id));
+  const why = new Map((decision.rejected || []).map((r) => [r.id, r.why]));
+  // Rank is position in the router's own ordering — the thing that decided — so a node's
+  // place in the picture is the place it had in the decision, not a re-sort of our own.
+  const rankOf = new Map(eligible.map((m, i) => [m.id, i]));
+
+  const nodes = [...models]
+    .map((m) => ({
+      id: m.id,
+      label: m.label || m.id,
+      reach: m.reach,
+      classUsed: m.classUsed,
+      quality: num(m.quality),
+      costPer1k: num(m.costPer1k),
+      latencyMs: num(m.latencyMs),
+      // An order the user PINNED is a statement; one we inferred is a guess, and a picture
+      // that shows them identically hides why a model won.
+      order: num(m.providerRank),
+      orderPinned: !!m.orderPinned,
+      eligible: eligibleIds.has(m.id),
+      rank: rankOf.has(m.id) ? rankOf.get(m.id) : null,
+      chosen: m.id === decision.model?.id,
+      // Present only when it was ruled out — the whole point of showing the losers.
+      why: eligibleIds.has(m.id) ? null : (why.get(m.id) || 'not eligible'),
+    }))
+    .sort((a, b) => {
+      if (a.eligible !== b.eligible) return a.eligible ? -1 : 1;
+      if (a.eligible) return (a.rank ?? 0) - (b.rank ?? 0);
+      return String(a.label).localeCompare(String(b.label));
+    });
+
+  return {
+    chosen: decision.model?.id || null,
+    strategy: decision.strategy || null,
+    reasons: decision.reasons || [],
+    // WHY the constraints are what they are — which page capped the reach, what set the
+    // quality floor. "reach 'trusted' within 'trusted'" says a ceiling applied and not what
+    // imposed it, and an unexplained restriction is one people switch off wholesale.
+    constraints: decision.constraints || [],
+    nodes,
+    chain: projectChain(decision, hops),
+    eliminated: nodes.filter((n) => !n.eligible).length,
+  };
+}
+
+/**
+ * Where the turn goes if this model declines, and the one after that.
+ *
+ * Walked hop by hop rather than read off the ranking, because that is what actually happens:
+ * each replacement is chosen relative to the model that JUST failed, not to the original. A
+ * chain read off `eligible` order would be a plausible-looking fiction — it is the ordering
+ * for the first choice, not for the fourth.
+ */
+export function projectChain(decision, hops = 4) {
+  const first = decision?.model;
+  if (!first) return [];
+  const chain = [{ id: first.id, label: first.label || first.id, reason: null }];
+  const tried = new Set([first.id]);
+  let current = first;
+
+  for (let i = 0; i < hops; i++) {
+    const rest = (decision.eligible || []).filter((m) => !tried.has(m.id));
+    if (!rest.length) break;
+    // 'server' — a provider saying no, which is the ordinary case. A retired model reorders
+    // this, but that is a fact discovered at failure time and cannot be known in advance.
+    const next = failoverOrder(rest, {
+      model: current.model,
+      quality: current.quality,
+      capabilities: current.capabilities,
+      classUsed: current.classUsed,
+      reason: 'server',
+    })[0];
+    if (!next) break;
+    chain.push({ id: next.id, label: next.label || next.id, reason: `closest to ${current.label || current.id}` });
+    tried.add(next.id);
+    current = next;
+  }
+  return chain;
+}