@chatpanel/events 0.2.0

package/event.js

@@ -0,0 +1,170 @@
+// The event envelope — durable facts only.
+//
+// ORDER WITHOUT CLOCKS. `at` is wall time and is ADVISORY: it is shown to humans and
+// never consulted for ordering. `(host, seq)` plus `causes` are the authority, because
+// once two hosts append concurrently a timestamp is not an order (see order.js).
+//
+// EPHEMERAL STREAMS ARE NOT THIS TYPE. Market ticks, live captions and DOM mutations
+// live in an in-memory ring buffer with no id, no seq and no persistence; only the
+// windowed aggregate that entered a model request or crossed the device boundary is
+// promoted to an Event. That is structural rather than a rule to remember: durably
+// logging a caption stream is ~3 MB per meeting, ~5.5 GB/year, and there is no Event
+// type that would accept one.
+//
+// METADATA ONLY. Payloads carry Refs and counts, never content. `privacy.redacted`
+// carries how many of each entity type were redacted and never the values — a log of
+// what was redacted must not itself contain the redacted data.
+
+import { isRef } from './ref.js';
+
+export const CURRENT_VERSION = 1;
+
+/** The seven families of v1. Adding is cheap; removing is not. */
+export const EVENT_TYPES = Object.freeze({
+  turn: ['started', 'ended'],
+  // What the model was SHOWN and what it SAID. Deliberately arriving as refs, not text —
+  // see the note on the validators below.
+  assistant: ['prompted', 'message', 'reasoning'],
+  context: ['assembled', 'attached', 'expanded'],
+  capability: ['offered', 'granted', 'denied', 'activated', 'revoked', 'invoked', 'resulted'],
+  privacy: ['redacted', 'egress'],
+  policy: ['changed', 'guard_denied'],
+  data: ['created', 'updated', 'deleted'],
+  automation: ['fired', 'suppressed'],
+});
+
+export const ALL_TYPES = Object.freeze(
+  Object.entries(EVENT_TYPES).flatMap(([fam, kinds]) => kinds.map((k) => `${fam}.${k}`)),
+);
+
+export const ACTOR_KINDS = Object.freeze(['user', 'rule', 'schedule', 'model', 'agent']);
+export const SCOPE_KINDS = Object.freeze(['global', 'site', 'tab', 'session', 'agent']);
+export const CLASSES = Object.freeze(['R', 'M', 'L', 'C', 'A', 'X', 'H']);
+export const EFFECTS = Object.freeze(['pure', 'idempotent', 'replay-safe', 'non-replayable']);
+export const EGRESS = Object.freeze(['none', 'redacted', 'delegated']);
+
+export class EventError extends Error {
+  constructor(code, message, detail = null) {
+    super(message);
+    this.name = 'EventError';
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+const str = (v) => typeof v === 'string' && v.length > 0;
+const num = (v) => typeof v === 'number' && Number.isFinite(v);
+const arr = (v) => Array.isArray(v);
+
+function actorOk(a) { return !!a && ACTOR_KINDS.includes(a.kind) && str(a.id); }
+function scopeOk(s) { return !!s && SCOPE_KINDS.includes(s.kind) && str(s.id); }
+
+// Per-type payload requirements. Deliberately light — enough that a malformed event
+// cannot enter an append-only log, not a full schema language.
+const PAYLOAD = {
+  'turn.started': (p) => str(p.turnId),
+  'turn.ended': (p) => str(p.turnId),
+
+  // ── assistant ─────────────────────────────────────────────────────────────
+  // "Model-visible means logged" was true of the toolset and false of the conversation:
+  // the log could say a turn happened and what it cost, but never what was asked or
+  // answered. That is the half a trajectory view needs, and the half replay cannot be
+  // checked without.
+  //
+  // CONTENT IS NEVER IN THE EVENT. Each of these carries a Ref — a content hash — and the
+  // bytes live in the blob store. Three reasons, in order of how much they matter:
+  //   1. The log stays metadata, so exporting or replicating it does not export the user's
+  //      conversations by accident. That property is the whole reason an event log is safe
+  //      to keep at all.
+  //   2. Deletion stays honest: an append-only log cannot unsay a message, but a blob can
+  //      be crypto-shredded and the ref then resolves to verified-but-unavailable. Inlined
+  //      text would make "delete my data" a lie the schema enforces forever.
+  //   3. Repeated content (the same system prompt on every turn) is stored once.
+  'assistant.prompted': (p) => str(p.turnId) && isRef(p.ref),
+  'assistant.message': (p) => str(p.turnId) && isRef(p.ref),
+  'assistant.reasoning': (p) => str(p.turnId) && isRef(p.ref),
+
+  'context.assembled': (p) => num(p.budget) && num(p.used) && !!p.parts && typeof p.parts === 'object'
+    && arr(p.resident) && p.resident.every(isRef) && num(p.reachableCount),
+  'context.attached': (p) => isRef(p.ref),
+  'context.expanded': (p) => isRef(p.ref) && num(p.tokens),
+
+  'capability.offered': (p) => str(p.capability) && str(p.reason),
+  'capability.granted': (p) => str(p.capability) && actorOk(p.actor),
+  'capability.denied': (p) => str(p.capability) && actorOk(p.actor),
+  'capability.activated': (p) => str(p.capability) && CLASSES.includes(p.classUsed),
+  'capability.revoked': (p) => str(p.capability) && str(p.cause),
+  // I3 is enforced here structurally: a non-pure invocation without a key is not a
+  // valid event, so it cannot reach the log at all.
+  'capability.invoked': (p) => str(p.capability) && actorOk(p.actor) && scopeOk(p.scope)
+    && EFFECTS.includes(p.effects) && (p.effects === 'pure' || str(p.idempotencyKey)),
+  'capability.resulted': (p) => str(p.capability) && typeof p.ok === 'boolean'
+    && CLASSES.includes(p.classUsed) && !!p.cost && num(p.cost.ms),
+
+  // counts only — never values
+  'privacy.redacted': (p) => !!p.counts && typeof p.counts === 'object'
+    && Object.values(p.counts).every(num),
+  'privacy.egress': (p) => str(p.host) && typeof p.redacted === 'boolean'
+    && typeof p.controlled === 'boolean',
+
+  'policy.changed': (p) => str(p.dial) && actorOk(p.actor) && 'from' in p && 'to' in p,
+  'policy.guard_denied': (p) => str(p.capability) && str(p.reason),
+
+  'data.created': (p) => isRef(p.ref),
+  'data.updated': (p) => isRef(p.ref),
+  'data.deleted': (p) => isRef(p.ref) && typeof p.shredded === 'boolean',
+
+  'automation.fired': (p) => str(p.ruleId) && CLASSES.includes(p.classUsed),
+  'automation.suppressed': (p) => str(p.ruleId) && str(p.reason),
+};
+
+/** Validate a durable event. Throws EventError; never mutates. */
+export function validateEvent(e) {
+  if (!e || typeof e !== 'object') throw new EventError('SHAPE', 'event must be an object');
+  if (e.v !== CURRENT_VERSION) throw new EventError('VERSION', `expected v=${CURRENT_VERSION}, got ${e.v} — upcast first`, e.v);
+  if (!str(e.id)) throw new EventError('SHAPE', 'id required');
+  if (!str(e.host)) throw new EventError('SHAPE', 'host required');
+  if (!Number.isInteger(e.seq) || e.seq < 0) throw new EventError('SHAPE', 'seq must be a non-negative integer');
+  if (!arr(e.causes) || !e.causes.every(str)) throw new EventError('SHAPE', 'causes must be string[]');
+  if (!num(e.at)) throw new EventError('SHAPE', 'at required (advisory wall clock)');
+  if (!ALL_TYPES.includes(e.type)) throw new EventError('TYPE', `unknown type ${e.type}`, e.type);
+  if (!e.payload || typeof e.payload !== 'object') throw new EventError('SHAPE', 'payload required');
+  const check = PAYLOAD[e.type];
+  if (check && !check(e.payload)) throw new EventError('PAYLOAD', `payload invalid for ${e.type}`, e.type);
+  return e;
+}
+
+export function isValidEvent(e) {
+  try { validateEvent(e); return true; } catch { return false; }
+}
+
+/**
+ * A per-host append cursor. Owns `seq` — the only monotonic thing in the system — so
+ * callers cannot skip or reuse one.
+ *
+ * `now` and `newId` are injected so tests are deterministic and so the package holds no
+ * ambient dependency on a clock or a crypto implementation.
+ */
+export function createAppender({ host, seq = 0, now = () => Date.now(), newId }) {
+  if (!str(host)) throw new EventError('SHAPE', 'host required');
+  const genId = newId || (() => globalThis.crypto.randomUUID());
+  let n = seq;
+  return {
+    get host() { return host; },
+    get seq() { return n; },
+    /** Build + validate the next event for this host. Does not persist — the caller stores it. */
+    append(type, payload, causes = []) {
+      const e = Object.freeze({
+        v: CURRENT_VERSION,
+        id: genId(),
+        host,
+        seq: n++,
+        causes: Object.freeze([...causes]),
+        at: now(),
+        type,
+        payload,
+      });
+      return validateEvent(e);
+    },
+  };
+}

package/harness.js

@@ -0,0 +1,101 @@
+// THE REPLAY HARNESS — what turns the determinism claim into a checked one.
+//
+// An unverified invariant decays silently. The claim we actually sell is replay
+// determinism ("same log, same reconstructed inputs"), so it needs a job that re-runs
+// recorded logs and fails the build when reconstruction drifts — the same discipline as
+// the `sync:pii --check` drift guard and the CSP assertion in build-editor.mjs.
+//
+// What it verifies, and what it deliberately does not:
+//   • ORDER is reproduced exactly, from (host, seq) and causes, never from a clock.
+//   • MODEL-VISIBLE INPUT is reconstructable: every resident Ref resolves by hash.
+//   • A Ref whose blob is gone reports VERIFIED-BUT-UNAVAILABLE. That is a PASS, not a
+//     failure — crypto-shredding is a feature, and the log still proves what was sent.
+//   • A Ref whose source CHANGED reports DRIFTED, and that IS a failure, because the
+//     alternative is replay quietly substituting today's note for the one actually sent.
+
+import { upcastAll } from './upcast.js';
+import { linearize } from './order.js';
+import { checkInvariants } from './invariants.js';
+import { resolveRef, RESOLUTION } from './ref.js';
+
+/**
+ * @param stored  events as persisted (any schema version)
+ * @param blobs   { lookup(ref) } — omit to skip content reconstruction
+ * @returns a report; `ok` is the CI signal.
+ */
+export function replay(stored, { blobs = null, invariantOptions = {} } = {}) {
+  const events = upcastAll(stored);
+  const ordered = linearize(events);
+
+  // Determinism: linearize is a function of the SET. Feed it back reversed; if the order
+  // changes, replay depends on how the log happened to be read off disk.
+  const stable = linearize([...events].reverse()).map((e) => e.id).join(',')
+    === ordered.map((e) => e.id).join(',');
+
+  const violations = checkInvariants(ordered, invariantOptions);
+
+  const refs = { exact: 0, unavailable: 0, drifted: [] };
+  const turns = [];
+  if (blobs) {
+    for (const e of ordered) {
+      // What the model was SHOWN and what it SAID are refs too, and they are the half a
+      // reader most wants replayed. Checking only `resident` verified the toolset while
+      // leaving the conversation unverified — the part that actually reconstructs a turn.
+      if (String(e.type).startsWith('assistant.')) {
+        const r = resolveRef(e.payload.ref, (x) => blobs.lookup(x));
+        if (r.resolution === RESOLUTION.EXACT) refs.exact++;
+        else if (r.resolution === RESOLUTION.UNAVAILABLE) refs.unavailable++;
+        else refs.drifted.push({ eventId: e.id, ref: r.ref, actualHash: r.actualHash });
+        continue;
+      }
+      if (e.type !== 'context.assembled') continue;
+      const resolved = e.payload.resident.map((ref) => resolveRef(ref, (r) => blobs.lookup(r)));
+      for (const r of resolved) {
+        if (r.resolution === RESOLUTION.EXACT) refs.exact++;
+        else if (r.resolution === RESOLUTION.UNAVAILABLE) refs.unavailable++;
+        else refs.drifted.push({ eventId: e.id, ref: r.ref, actualHash: r.actualHash });
+      }
+      turns.push({
+        turnId: e.payload.turnId,
+        budget: e.payload.budget,
+        used: e.payload.used,
+        parts: e.payload.parts,
+        reconstructable: resolved.every((r) => r.resolution !== RESOLUTION.DRIFTED),
+      });
+    }
+  }
+
+  return {
+    ok: stable && violations.length === 0 && refs.drifted.length === 0,
+    events: ordered.length,
+    stable,
+    violations,
+    refs,
+    turns,
+    order: ordered.map((e) => e.id),
+  };
+}
+
+/** One-line CI summary. */
+export function formatReport(report) {
+  const lines = [
+    `${report.ok ? 'PASS' : 'FAIL'} — ${report.events} events`,
+    `  order stable        ${report.stable ? 'yes' : 'NO — replay is order-dependent'}`,
+    `  invariants          ${report.violations.length === 0 ? 'I1-I6 hold' : `${report.violations.length} violation(s)`}`,
+  ];
+  for (const v of report.violations) lines.push(`    ${v.invariant} ${v.eventId || ''} ${v.message}`);
+  if (report.refs.exact || report.refs.unavailable || report.refs.drifted.length) {
+    lines.push(`  refs                ${report.refs.exact} exact · ${report.refs.unavailable} shredded/evicted · ${report.refs.drifted.length} DRIFTED`);
+  }
+  for (const d of report.refs.drifted) lines.push(`    drifted ${d.ref.kind}:${d.ref.id} — the source changed since capture`);
+  return lines.join('\n');
+}
+
+/** Parse a JSONL log. Blank lines ignored so a truncated export still loads. */
+export function parseJsonl(text) {
+  return String(text).split('\n').map((l) => l.trim()).filter(Boolean).map((l) => JSON.parse(l));
+}
+
+export function toJsonl(events) {
+  return events.map((e) => JSON.stringify(e)).join('\n');
+}

package/index.js

@@ -0,0 +1,44 @@
+// @chatpanel/events — the ChatPanel event-log and capability contracts.
+//
+// Two contracts everything else inherits from:
+//   • the EVENT SCHEMA — append-only, versioned forever, metadata only, ordered
+//     without clocks;
+//   • the CAPABILITY SIGNATURE — one call shape a rule, a schedule, the user or a
+//     model all invoke identically.
+//
+// Pure and dependency-free so the identical code runs in the extension (browser ESM,
+// MV3/CSP-safe), the gateway and the bridge — the @chatpanel/pii delivery pattern.
+
+export {
+  CURRENT_VERSION, EVENT_TYPES, ALL_TYPES,
+  ACTOR_KINDS, SCOPE_KINDS, CLASSES, EFFECTS, EGRESS,
+  EventError, validateEvent, isValidEvent, createAppender,
+} from './event.js';
+
+export { REF_KINDS, RESOLUTION, makeRef, isRef, resolveRef } from './ref.js';
+export { linearize, compareEvents, causesAreWellFormed } from './order.js';
+export { UPCASTERS, upcast, upcastAll } from './upcast.js';
+export {
+  DATA_SCOPES, validateCapability, validateInvocation, canSatisfy,
+  toModelSchema, toModelSchemas,
+} from './capability.js';
+export { checkInvariants, INVARIANTS } from './invariants.js';
+export { createMemoryAdapter, createLogStore, createBlobStore } from './store.js';
+export { createRegistry, REGISTRY_STATES } from './registry.js';
+export { defineSearchEngine, reconcileEngines, attemptOrder, ENGINE_KINDS, SearchEngineError } from './search-engines.js';
+export { defineToolGroup, createToolGroupRegistry, ToolGroupError } from './tool-groups.js';
+export { toolNeedFor } from './tool-need.js';
+export { routeGraph, projectChain } from './route-graph.js';
+export { defineAdapter, createAdapterRegistry, AdapterError } from './adapters.js';
+export { linkifyCitations, sourcesFromToolText } from './citations.js';
+export { buildTrajectory, phasesOf, lanesOf, filterEntries, displayName, ENTRY_KINDS, threadsOf, threadTitle, promptEntries, turnsOf, threadTree } from './trajectory.js';
+export { createTurnRunner, defineLoop, LOOP_KINDS, LoopError } from './loop.js';
+export { defineModel, defineMiddleware, defineRouteStrategy, createModelRouter, signalsFrom, requirementsFor, requirementsForStep, preferenceFor, failoverOrder, pinnedOrderOf, FAILOVER_CLASS_GAP, FAILOVER_CAPABILITY_GAP, sameModelKey, REACH, RouterError } from './router.js';
+export { makeSourceStore, manifestText, shortUrl, readSource, sourceId } from './sources-retrieval.js';
+export { classifySource, extractUrls, hostMatches, meetReach, sourcePolicyFor, DEFAULT_INTERNAL_PATTERNS, INTERNAL_PATTERN_CATALOG } from './sources.js';
+export { defineRule, createRuleEngine, SUPPRESSED, RuleError } from './rules.js';
+export { defineMeetingAnalyzer, createAnalyzerRegistry, CADENCES, AnalyzerError } from './meeting-analyzers.js';
+export { explainMcpError, packageFromArgs } from './mcp-errors.js';
+export { createManifest, ManifestError, SOURCES } from './manifest.js';
+export { createKernel, meetDecisions, KernelError, REQUIRED_PLUGINS, ALLOW_ALL } from './kernel.js';
+export { replay, formatReport, parseJsonl, toJsonl } from './harness.js';

package/invariants.js

@@ -0,0 +1,174 @@
+// The six invariants the replay harness asserts.
+//
+// These are what make the claims CHECKABLE rather than aspirational. An unverified
+// invariant decays silently, so each of these becomes a CI assertion the way the
+// `sync:pii --check` drift guard and the CSP assertion in build-editor.mjs already are.
+//
+//   I1  every model request is preceded by a context.assembled that reconstructs it
+//   I2  every byte leaving the device has a privacy.egress (controlled:false for agents)
+//   I3  every non-pure capability.invoked carries an idempotency key
+//   I4  every capability.revoked names its activated in causes
+//   I5  no durable event exists for a per-item ephemeral stream
+//   I6  replay under the linearization rule is stable across runs and across hosts
+//   I7  no assistant event carries content — only a Ref to it
+//
+// checkInvariants() returns violations rather than throwing, so a harness can report
+// every problem in one pass instead of one per run.
+
+import { linearize } from './order.js';
+import { isRef } from './ref.js';
+
+const v = (id, event, message) => ({ invariant: id, eventId: event ? event.id : null, message });
+
+/** I1 — a turn that ran must have assembled its context, and every resident Ref is hashed. */
+/**
+ * I7 — an assistant event names its content, it never contains it.
+ *
+ * The temptation is obvious: inlining the text makes the trajectory view trivial. It also
+ * makes the log a second copy of every conversation, so exporting the log exports the
+ * user's data, and shredding a message leaves it readable in an append-only file forever.
+ * Structural, not advisory: the checker fails on any payload field holding a long string,
+ * because the failure it prevents is silent — everything keeps working, and privacy is
+ * quietly gone.
+ */
+function checkI7(events) {
+  const out = [];
+  const MAX = 200; // a model, a stop reason, a hash — never a message
+  for (const e of events) {
+    if (!String(e.type).startsWith('assistant.')) continue;
+    if (!isRef(e.payload?.ref)) out.push(v('I7', e, 'assistant event has no content Ref'));
+    for (const [k, val] of Object.entries(e.payload || {})) {
+      if (k !== 'ref' && typeof val === 'string' && val.length > MAX) {
+        out.push(v('I7', e, `payload.${k} carries ${val.length} chars of content — assistant events must reference, never contain`));
+      }
+    }
+  }
+  return out;
+}
+
+function checkI1(events) {
+  const out = [];
+  const assembledByTurn = new Set();
+  for (const e of events) {
+    if (e.type === 'context.assembled') {
+      if (e.payload.turnId) assembledByTurn.add(e.payload.turnId);
+      for (const r of e.payload.resident) {
+        if (!isRef(r)) out.push(v('I1', e, 'resident entry is not a valid Ref'));
+      }
+    }
+  }
+  for (const e of events) {
+    if (e.type === 'turn.ended' && e.payload.stepped !== false && !assembledByTurn.has(e.payload.turnId)) {
+      out.push(v('I1', e, `turn ${e.payload.turnId} ended with no context.assembled — model-visible input is not reconstructable`));
+    }
+  }
+  return out;
+}
+
+/** I2 — an invocation that egresses must produce a privacy.egress caused by it. */
+function checkI2(events) {
+  const out = [];
+  const egressCauses = new Set();
+  for (const e of events) {
+    if (e.type === 'privacy.egress') for (const c of e.causes) egressCauses.add(c);
+  }
+  for (const e of events) {
+    if (e.type === 'capability.invoked' && e.payload.egress && e.payload.egress !== 'none') {
+      if (!egressCauses.has(e.id)) {
+        out.push(v('I2', e, `invocation declares egress '${e.payload.egress}' but no privacy.egress references it`));
+      }
+    }
+  }
+  return out;
+}
+
+/** I3 — non-pure invocations carry an idempotency key. (Also enforced by validateEvent.) */
+function checkI3(events) {
+  return events
+    .filter((e) => e.type === 'capability.invoked'
+      && e.payload.effects !== 'pure'
+      && !e.payload.idempotencyKey)
+    .map((e) => v('I3', e, `'${e.payload.effects}' invocation without an idempotencyKey — a retry would repeat the side effect`));
+}
+
+/** I4 — a revoke names the activation it undoes. */
+function checkI4(events) {
+  const activated = new Map();
+  for (const e of events) if (e.type === 'capability.activated') activated.set(e.id, e);
+  return events
+    .filter((e) => e.type === 'capability.revoked' && !e.causes.some((c) => activated.has(c)))
+    .map((e) => v('I4', e, 'revoked does not name its activated in causes — the effect has no recorded inverse'));
+}
+
+/** I5 — ephemeral stream items never become durable facts. */
+function checkI5(events, { ephemeralBudget = 200 } = {}) {
+  const out = [];
+  const perTypePerHost = new Map();
+  for (const e of events) {
+    const k = `${e.host}:${e.type}:${e.payload.streamId || ''}`;
+    perTypePerHost.set(k, (perTypePerHost.get(k) || 0) + 1);
+  }
+  for (const [k, n] of perTypePerHost) {
+    if (k.split(':')[2] && n > ephemeralBudget) {
+      out.push(v('I5', null, `${n} durable events for stream ${k} — per-item stream data must be windowed, not logged`));
+    }
+  }
+  return out;
+}
+
+/** I6 — linearization is a function of the event SET, not of the input array's order. */
+function checkI6(events, { shuffles = 8, rng = mulberry32(0x5EED) } = {}) {
+  if (events.length < 2) return [];
+  const base = linearize(events).map((e) => e.id).join(',');
+  for (let i = 0; i < shuffles; i++) {
+    const shuffled = shuffle(events, rng);
+    if (linearize(shuffled).map((e) => e.id).join(',') !== base) {
+      return [v('I6', null, 'linearize() is order-dependent — replay is not deterministic')];
+    }
+  }
+  return [];
+}
+
+/** Run every invariant over an event set. Returns [] when the log is sound. */
+export function checkInvariants(events, opts = {}) {
+  return [
+    ...checkI7(events),
+    ...checkI1(events),
+    ...checkI2(events),
+    ...checkI3(events),
+    ...checkI4(events),
+    ...checkI5(events, opts),
+    ...checkI6(events, opts),
+  ];
+}
+
+export const INVARIANTS = Object.freeze({
+  I1: 'model-visible input is reconstructable from the log',
+  I2: 'every egress is recorded',
+  I3: 'non-pure invocations are idempotent',
+  I4: 'every activation has a recorded inverse',
+  I5: 'ephemeral streams never become durable facts',
+  I6: 'replay is deterministic',
+  I7: 'assistant events reference content, never contain it',
+});
+
+// Seeded PRNG so a failing I6 reproduces exactly — the package holds no ambient
+// dependency on Math.random.
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6D2B79F5) >>> 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function shuffle(list, rng) {
+  const a = [...list];
+  for (let i = a.length - 1; i > 0; i--) {
+    const j = Math.floor(rng() * (i + 1));
+    [a[i], a[j]] = [a[j], a[i]];
+  }
+  return a;
+}