peon-mem 1.0.0

package/dist/retrieval.js

@@ -0,0 +1,392 @@
+import { cosineSimilarity } from "./embeddings.js";
+import { canonicalizeEntity } from "./entities.js";
+const DEFAULT_MIN_SIMILARITY = 0.15;
+const stopWords = new Set([
+    "a",
+    "an",
+    "and",
+    "are",
+    "as",
+    "for",
+    "in",
+    "is",
+    "of",
+    "on",
+    "or",
+    "the",
+    "to",
+    "use",
+    "with"
+]);
+const RRF_K = 60; // standard reciprocal-rank-fusion constant
+const PIN_BOOST = 0.05;
+// Associative graph signal weight (fraction of a direct RRF signal), for the OPT-IN expandGraph
+// path only. Default 0.1: the labeled eval showed higher weights hurt top-K relevance (0.5 →
+// −2.9% Recall@10, 1.0 → −3.8%) while ~0.1 is neutral. Env-tunable (PEON_GRAPH_WEIGHT) for sweeps.
+const GRAPH_FUSION_WEIGHT = (() => {
+    const env = process.env.PEON_GRAPH_WEIGHT;
+    return env !== undefined && Number.isFinite(Number(env)) ? Number(env) : 0.1;
+})();
+// Type priority is a PRIOR vote in the fusion (durable types over ephemeral) — a
+// rank, not a hand-tuned weight, so it stays robust alongside the other signals.
+const TYPE_PRIORITY = {
+    decision: 6, preference: 5, fact: 4, artifact: 3, summary: 2, open_question: 1, timeline: 0
+};
+/**
+ * Hybrid retrieval by Reciprocal Rank Fusion. Each signal (lexical, semantic,
+ * quality, recency, reinforcement strength) ranks the relevance-gated candidates
+ * independently; we fuse by Σ 1/(k+rank). RRF is weight-free — it removes the
+ * fragile hand-tuned score constants by comparing RANKS, which are commensurable
+ * across signals where raw scores are not. Pinned beliefs are boosted; archived/
+ * superseded are excluded by default (they are the long-term tier, not working memory).
+ */
+export function rankMemoryRecords(records, query, options = {}) {
+    const terms = queryTerms(query);
+    const fileTerms = queryFileTerms(query);
+    const nowMs = timestamp(options.now ?? Date.now());
+    const limit = Math.max(0, Math.trunc(options.limit ?? 50));
+    const semantic = options.semantic;
+    const minSimilarity = semantic?.minSimilarity ?? DEFAULT_MIN_SIMILARITY;
+    const hasQuery = terms.length > 0;
+    const signals = records.map((record, index) => {
+        const reasons = [];
+        const lexical = lexicalScore(record, terms, fileTerms, reasons);
+        let semSim = 0;
+        if (semantic && semantic.queryVector.length > 0) {
+            const vector = semantic.vectorById.get(record.id);
+            if (vector && vector.length > 0) {
+                const sim = cosineSimilarity(semantic.queryVector, vector);
+                if (sim >= minSimilarity) {
+                    semSim = sim;
+                    reasons.push({ kind: "semantic", label: `semantic match ${sim.toFixed(2)}`, score: roundScore(sim) });
+                }
+            }
+        }
+        const quality = clamp(record.score.importance) * 0.6 + clamp(record.score.confidence) * 0.4;
+        const strength = clamp(typeof record.strength === "number" ? record.strength : record.score.importance)
+            + Math.min(0.5, Math.log1p(record.recallCount ?? 0) / 6); // reinforcement bonus
+        const graph = options.graphActivation?.get(record.id) ?? 0;
+        if (graph > 0 && lexical === 0 && semSim === 0) {
+            reasons.push({ kind: "entity", label: "linked via entity graph", score: roundScore(graph) });
+        }
+        return { record, index, lexical, semantic: semSim, quality, recency: recencyScore(record, nowMs), strength, graph, reasons };
+    });
+    // Relevance gate: with a query, keep only beliefs that matched lexically or semantically.
+    // Tier filtering (active vs archived/superseded) is intentionally NOT done here — the
+    // injection/context layer owns that, so it can both record WHY a belief was omitted and
+    // recover history on demand (includeInactive). The ranker stays a pure relevance ranker.
+    const gated = signals.filter((s) => {
+        if (!hasQuery)
+            return true;
+        // Admit a belief that matched the query OR that the entity graph activated (associative recall).
+        return s.lexical > 0 || s.semantic > 0 || s.graph > 0;
+    });
+    if (gated.length === 0)
+        return [];
+    // Build per-signal rank maps over the gated candidates.
+    const lexRank = rankMap(gated, (s) => s.lexical, true);
+    const semRank = rankMap(gated, (s) => s.semantic, true);
+    const qualRank = rankMap(gated, (s) => s.quality, false);
+    const recRank = rankMap(gated, (s) => s.recency, false);
+    const strRank = rankMap(gated, (s) => s.strength, false);
+    const typeRank = rankMap(gated, (s) => TYPE_PRIORITY[s.record.type] ?? 0, false);
+    const graphRank = rankMap(gated, (s) => s.graph, true);
+    const ranked = gated.map((s) => {
+        let score = 0;
+        if (s.lexical > 0)
+            score += 1 / (RRF_K + lexRank(s));
+        if (s.semantic > 0)
+            score += 1 / (RRF_K + semRank(s));
+        // Associative graph signal — DAMPED (×GRAPH_FUSION_WEIGHT) so it's secondary to direct
+        // matches: a strong association can enter the top-K and displace a weak direct hit, but
+        // won't outrank genuine query matches.
+        if (s.graph > 0)
+            score += GRAPH_FUSION_WEIGHT * (1 / (RRF_K + graphRank(s)));
+        // Priors always participate (relevance already gated the candidate set).
+        score += 1 / (RRF_K + qualRank(s));
+        score += 1 / (RRF_K + recRank(s));
+        score += 1 / (RRF_K + strRank(s));
+        score += 1 / (RRF_K + typeRank(s));
+        if (s.record.pinned)
+            score += PIN_BOOST;
+        if (s.record.status === "stale")
+            score -= 0.01;
+        if (s.record.status === "conflicted")
+            score -= 0.005;
+        const reasons = [...s.reasons,
+            { kind: "quality", label: `importance ${clamp(s.record.score.importance).toFixed(2)}`, score: 1 / (RRF_K + qualRank(s)) },
+            { kind: "recency", label: `updated ${s.record.updatedAt}`, score: 1 / (RRF_K + recRank(s)) }];
+        if ((s.record.recallCount ?? 0) > 0)
+            reasons.push({ kind: "status", label: `recalled ${s.record.recallCount}×`, score: 1 / (RRF_K + strRank(s)) });
+        return {
+            record: s.record,
+            score: roundScore(score),
+            reasons,
+            explanation: s.reasons.map((r) => r.label).join("; "),
+            index: s.index
+        };
+    });
+    return ranked
+        .sort((left, right) => {
+        if (right.score !== left.score)
+            return right.score - left.score;
+        const updatedDelta = timestamp(right.record.updatedAt) - timestamp(left.record.updatedAt);
+        if (updatedDelta !== 0)
+            return updatedDelta;
+        return left.index - right.index;
+    })
+        .slice(0, limit)
+        .map(({ index: _index, ...item }) => item);
+}
+/**
+ * Build a total rank lookup (1-based, descending by key) using COMPETITION ranking:
+ * equal values share the same rank, so ties contribute equally to both records and
+ * the outcome is decided by the signals that actually differ (no arbitrary tie-break).
+ * Missing (gated-out) → large rank (~0 contribution).
+ */
+function rankMap(items, key, gateZero) {
+    const sorted = items
+        .map((s) => ({ s, v: key(s) }))
+        .filter((x) => (gateZero ? x.v > 0 : true))
+        .sort((a, b) => b.v - a.v);
+    const map = new Map();
+    let rank = 0;
+    let prev;
+    sorted.forEach((x, i) => {
+        if (prev === undefined || x.v !== prev)
+            rank = i + 1; // ties keep the prior rank
+        prev = x.v;
+        map.set(x.s, rank);
+    });
+    const last = sorted.length + items.length + 1;
+    return (s) => map.get(s) ?? last;
+}
+function lexicalScore(record, terms, fileTerms, reasons) {
+    const text = searchableText(record);
+    let score = 0;
+    const matchedTerms = terms.filter((term) => text.includes(term));
+    if (matchedTerms.length > 0) {
+        score += matchedTerms.length * 2;
+        reasons.push({ kind: "query_term", label: `matched query terms ${matchedTerms.join(", ")}`, score: matchedTerms.length * 2 });
+    }
+    const matchedEntities = record.entities.filter((entity) => {
+        const e = entity.toLowerCase();
+        return terms.some((term) => e.includes(term) || term.includes(e));
+    });
+    if (matchedEntities.length > 0) {
+        score += matchedEntities.length * 3;
+        reasons.push({ kind: "entity", label: `matched entity ${matchedEntities.join(", ")}`, score: matchedEntities.length * 3 });
+    }
+    const matchedFiles = record.entities.filter((entity) => isFileLike(entity) && fileTerms.some((term) => entity.toLowerCase().includes(term)));
+    if (matchedFiles.length > 0) {
+        score += matchedFiles.length * 4;
+        reasons.push({ kind: "file", label: `matched file ${matchedFiles.join(", ")}`, score: matchedFiles.length * 4 });
+    }
+    return score;
+}
+export function selectMemoryRecordsForContext(rankedRecords, options) {
+    const maxChars = Math.max(0, Math.trunc(options.maxChars));
+    const formatter = options.recordFormatter ?? defaultRecordFormatter;
+    const records = [];
+    const omitted = [];
+    let totalChars = 0;
+    for (const item of rankedRecords) {
+        const length = formatter(item).length;
+        if (length <= maxChars - totalChars) {
+            records.push(item);
+            totalChars += length;
+        }
+        else {
+            omitted.push(item);
+        }
+    }
+    return { records, omitted, totalChars, maxChars };
+}
+/** Default trade-off: 0.7 weight on relevance, 0.3 on novelty. Tuned for coverage without losing the top hit. */
+export const DEFAULT_MMR_LAMBDA = 0.7;
+/**
+ * Re-order ranked records by Maximal Marginal Relevance so the injected block has
+ * COVERAGE instead of five paraphrases of the same belief. Each pick maximizes
+ *   λ·relevance − (1−λ)·maxSimilarity(candidate, alreadyPicked)
+ * Relevance is the record's existing fused score (max-normalized to [0,1] within the
+ * set); similarity is lexical Jaccard over content+entity tokens — cheap, deterministic,
+ * and embedding-free so it works in pure local-first mode. The single most relevant
+ * record is always selected first, so the top hit is never displaced by diversification.
+ */
+export function diversifyByMMR(records, lambda = DEFAULT_MMR_LAMBDA) {
+    if (records.length <= 2)
+        return [...records];
+    const λ = Math.max(0, Math.min(1, lambda));
+    const maxScore = Math.max(...records.map((r) => r.score), 0);
+    const rel = (item) => (maxScore > 0 ? item.score / maxScore : 0);
+    const tokens = records.map((r) => recordTokens(r.record));
+    const remaining = records.map((_, i) => i);
+    const selected = [];
+    // Seed with the single most relevant record (input is already relevance-sorted).
+    let best = remaining[0];
+    for (const i of remaining)
+        if (rel(records[i]) > rel(records[best]))
+            best = i;
+    selected.push(best);
+    remaining.splice(remaining.indexOf(best), 1);
+    while (remaining.length > 0) {
+        let pick = remaining[0];
+        let pickScore = -Infinity;
+        for (const i of remaining) {
+            let maxSim = 0;
+            for (const s of selected) {
+                const sim = jaccard(tokens[i], tokens[s]);
+                if (sim > maxSim)
+                    maxSim = sim;
+            }
+            const mmr = λ * rel(records[i]) - (1 - λ) * maxSim;
+            if (mmr > pickScore) {
+                pickScore = mmr;
+                pick = i;
+            }
+        }
+        selected.push(pick);
+        remaining.splice(remaining.indexOf(pick), 1);
+    }
+    return selected.map((i) => records[i]);
+}
+/**
+ * Entity-graph spreading activation (the associative-recall layer). Lexical/semantic ranking
+ * finds beliefs that match the QUERY; this finds beliefs in the ANSWER's neighbourhood by
+ * spreading activation from the top hits through shared entities, with three brain-like rules
+ * the old flat 1-hop expander lacked:
+ *   - DISTANCE DECAY — a global damping (λ) keeps neighbours below direct matches.
+ *   - MULTI-SOURCE SUMMATION — a belief lit through several shared entities (or several seeds)
+ *     accumulates activation, so it outranks one lit through a single weak link.
+ *   - HUB DAMPING — rare entities transmit more activation (1/log₂(2+degree)); super-hubs
+ *     (e.g. a file mentioned by 80 beliefs) are skipped so the graph isn't a hairball.
+ * Domain entities (people/papers/concepts) spread more than code entities. Pure + deterministic.
+ * Neighbours come back with small scores in their own band and are meant to be appended AFTER
+ * the direct results, never displacing them.
+ */
+/**
+ * Raw spreading activation: id → accumulated activation for beliefs in the seeds' entity
+ * neighbourhood (excluding the seeds themselves). The associative substrate, shared by the
+ * fused-ranking path (passed as RetrievalOptions.graphActivation) and the legacy append path
+ * (expandByEntityGraph). Excludes seed ids so direct hits aren't double-counted.
+ */
+export function computeGraphActivation(seeds, pool, options = {}) {
+    const seedDepth = Math.max(1, Math.trunc(options.seedDepth ?? 8));
+    const damping = options.damping ?? 0.5;
+    const codeWeight = options.codeWeight ?? 0.4;
+    const hubDegreeCap = Math.max(1, Math.trunc(options.hubDegreeCap ?? 40));
+    const active = pool.filter((record) => record.status === "active");
+    const entityToRecords = new Map();
+    for (const record of active) {
+        for (const e of unique(record.entities)) {
+            const list = entityToRecords.get(e) ?? entityToRecords.set(e, []).get(e);
+            list.push(record);
+        }
+    }
+    const seedIds = new Set(seeds.map((s) => s.record.id));
+    const topSeeds = seeds.slice(0, seedDepth);
+    const activation = new Map();
+    if (topSeeds.length === 0)
+        return activation;
+    const maxSeedScore = Math.max(...topSeeds.map((s) => s.score), 1e-9);
+    topSeeds.forEach((seed, i) => {
+        const seedActivation = (seed.score > 0 ? seed.score / maxSeedScore : 0) / (1 + i * 0.3); // rank decay
+        if (seedActivation <= 0)
+            return;
+        for (const e of unique(seed.record.entities)) {
+            const holders = entityToRecords.get(e);
+            if (!holders || holders.length > hubDegreeCap)
+                continue; // skip super-hubs
+            const ns = canonicalizeEntity(e)?.namespace ?? "code";
+            const entityWeight = (ns === "domain" ? 1 : codeWeight) / Math.log2(2 + holders.length);
+            for (const neighbor of holders) {
+                if (seedIds.has(neighbor.id))
+                    continue; // never re-rank a direct hit
+                activation.set(neighbor.id, (activation.get(neighbor.id) ?? 0) + damping * seedActivation * entityWeight);
+            }
+        }
+    });
+    return activation;
+}
+/**
+ * Entity-graph spreading activation, formatted as standalone neighbour records (legacy append
+ * path + the unit tests). The fused-ranking path uses computeGraphActivation directly via
+ * rankMemoryRecords' graphActivation option, which lets associations compete inside the top-K.
+ */
+export function expandByEntityGraph(seeds, pool, options = {}) {
+    const maxNeighbors = Math.max(0, Math.trunc(options.maxNeighbors ?? 6));
+    if (maxNeighbors === 0)
+        return [];
+    const activation = computeGraphActivation(seeds, pool, options);
+    if (activation.size === 0)
+        return [];
+    const recordById = new Map(pool.filter((r) => r.status === "active").map((r) => [r.id, r]));
+    const maxAct = Math.max(...activation.values());
+    if (!(maxAct > 0))
+        return []; // all-zero activation (e.g. damping/codeWeight 0) → avoid NaN scores
+    return [...activation.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, maxNeighbors)
+        .map(([id, act]) => {
+        const record = recordById.get(id);
+        const label = "linked via entity graph";
+        const score = roundScore(0.02 * (act / maxAct)); // small supplementary band
+        return { record, score, reasons: [{ kind: "entity", label, score }], explanation: label };
+    });
+}
+function recordTokens(record) {
+    const raw = `${record.normalized} ${record.entities.join(" ")}`.toLowerCase();
+    return new Set(raw
+        .split(/[^a-z0-9_.\/-]+/)
+        .map((t) => t.trim())
+        .filter((t) => t.length > 1 && !stopWords.has(t)));
+}
+function jaccard(a, b) {
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let inter = 0;
+    for (const t of a)
+        if (b.has(t))
+            inter++;
+    const union = a.size + b.size - inter;
+    return union > 0 ? inter / union : 0;
+}
+function defaultRecordFormatter(item) {
+    return `- [${item.record.type}] ${item.record.content}\n`;
+}
+function queryTerms(query) {
+    return unique((query ?? "")
+        .toLowerCase()
+        .split(/[^a-z0-9_.\/-]+/)
+        .map((term) => term.trim())
+        .filter((term) => term.length > 1 && !stopWords.has(term)));
+}
+function queryFileTerms(query) {
+    return queryTerms(query).filter(isFileLike);
+}
+function searchableText(record) {
+    return `${record.type} ${record.content} ${record.normalized} ${record.entities.join(" ")}`.toLowerCase();
+}
+function recencyScore(record, nowMs) {
+    const updatedMs = timestamp(record.updatedAt || record.createdAt);
+    if (!Number.isFinite(updatedMs) || !Number.isFinite(nowMs))
+        return 0;
+    const ageDays = Math.max(0, (nowMs - updatedMs) / 86_400_000);
+    return roundScore(1 / (1 + ageDays / 30));
+}
+function timestamp(value) {
+    const time = value instanceof Date ? value.getTime() : new Date(value).getTime();
+    return Number.isFinite(time) ? time : 0;
+}
+function isFileLike(value) {
+    return /[/.\\]/.test(value) || /\.[a-z0-9]+$/i.test(value);
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+function clamp(value) {
+    return Math.max(0, Math.min(1, Number.isFinite(value) ? value : 0));
+}
+function roundScore(value) {
+    return Math.round(value * 1000) / 1000;
+}

package/dist/session-index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Durable sessionId → project mapping.
+ *
+ * The in-process tools layer needs to resolve which project a sessionId belongs
+ * to. Holding that only in memory means a daemon restart mid-session orphans
+ * every in-flight session ("Unknown Peon session"). This index persists the
+ * mapping to disk so sessions survive restarts.
+ *
+ * Writes are serialized through a queue; each write rewrites the full JSON map
+ * (fine for a local single-user tool). Ended sessions are removed to keep the
+ * file small; a crash may leave a stale "active" entry, which `prune` clears.
+ */
+export interface SessionIndexRecord {
+    sessionId: string;
+    projectPath: string;
+    client: string;
+    cwd: string;
+    startedAt: string;
+}
+export declare function defaultSessionIndexPath(): string;
+export declare class SessionIndex {
+    private readonly filePath;
+    private cache?;
+    private writeQueue;
+    constructor(filePath?: string);
+    get(sessionId: string): Promise<SessionIndexRecord | undefined>;
+    set(record: SessionIndexRecord): Promise<void>;
+    remove(sessionId: string): Promise<void>;
+    active(): Promise<SessionIndexRecord[]>;
+    /** Drop sessions older than maxAgeMs (stale entries from crashed runs). */
+    prune(now: number, maxAgeMs: number): Promise<number>;
+    private load;
+    private persist;
+}

package/dist/session-index.js

@@ -0,0 +1,87 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+export function defaultSessionIndexPath() {
+    return join(homedir(), "Library", "Application Support", "Peon", "sessions-index.json");
+}
+export class SessionIndex {
+    filePath;
+    cache;
+    writeQueue = Promise.resolve();
+    constructor(filePath = defaultSessionIndexPath()) {
+        this.filePath = filePath;
+    }
+    async get(sessionId) {
+        return (await this.load()).get(sessionId);
+    }
+    async set(record) {
+        const map = await this.load();
+        map.set(record.sessionId, record);
+        await this.persist(map);
+    }
+    async remove(sessionId) {
+        const map = await this.load();
+        if (map.delete(sessionId))
+            await this.persist(map);
+    }
+    async active() {
+        return [...(await this.load()).values()];
+    }
+    /** Drop sessions older than maxAgeMs (stale entries from crashed runs). */
+    async prune(now, maxAgeMs) {
+        const map = await this.load();
+        let removed = 0;
+        for (const [id, record] of map) {
+            const started = Date.parse(record.startedAt);
+            if (Number.isFinite(started) && now - started > maxAgeMs) {
+                map.delete(id);
+                removed += 1;
+            }
+        }
+        if (removed > 0)
+            await this.persist(map);
+        return removed;
+    }
+    async load() {
+        if (this.cache)
+            return this.cache;
+        const raw = await readFile(this.filePath, "utf8").catch(() => "");
+        const map = new Map();
+        if (raw.trim()) {
+            try {
+                const parsed = JSON.parse(raw);
+                if (parsed && typeof parsed === "object") {
+                    for (const value of Object.values(parsed)) {
+                        if (isSessionIndexRecord(value))
+                            map.set(value.sessionId, value);
+                    }
+                }
+            }
+            catch {
+                // Corrupt index → start clean rather than blocking all session resolution.
+            }
+        }
+        this.cache = map;
+        return map;
+    }
+    async persist(map) {
+        this.cache = map;
+        const snapshot = Object.fromEntries(map);
+        const write = async () => {
+            await mkdir(dirname(this.filePath), { recursive: true });
+            await writeFile(this.filePath, `${JSON.stringify(snapshot, null, 2)}\n`, "utf8");
+        };
+        this.writeQueue = this.writeQueue.then(write, write);
+        return this.writeQueue;
+    }
+}
+function isSessionIndexRecord(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return (typeof record.sessionId === "string" &&
+        typeof record.projectPath === "string" &&
+        typeof record.client === "string" &&
+        typeof record.cwd === "string" &&
+        typeof record.startedAt === "string");
+}

package/dist/temporal.d.ts

@@ -0,0 +1,20 @@
+import type { MemoryRecord } from "./types.js";
+/**
+ * The beliefs that were CURRENT as of `at`. A belief is current at `at` iff it had been created
+ * by then (createdAt ≤ at) and had not yet been retired/replaced by then — i.e. it is still live,
+ * or it was terminated (superseded/archived) only at a later time (updatedAt > at).
+ */
+export declare function currentAsOf(records: MemoryRecord[], at: string | number | Date): MemoryRecord[];
+export type ChangeKind = "added" | "superseded" | "retired";
+export interface ChangeEntry {
+    kind: ChangeKind;
+    at: string;
+    record: MemoryRecord;
+    replacementId?: string;
+}
+/**
+ * The changelog over [from, to] (inclusive): beliefs added (created in window) and beliefs that
+ * stopped being current in the window — `superseded` (has a successor) or `retired` (obsoleted,
+ * no successor). Sorted chronologically. This is the "what changed" / knowledge-update view.
+ */
+export declare function changesBetween(records: MemoryRecord[], from: string | number | Date, to: string | number | Date): ChangeEntry[];

package/dist/temporal.js

@@ -0,0 +1,62 @@
+/**
+ * Temporal retrieval over the belief store. Peon already keeps the history of a belief: when a
+ * fact changes, the old record is flipped to `superseded` (its `updatedAt` is the moment it
+ * stopped being true) and linked to its successor via `supersededBy`; an obsoleted belief is
+ * superseded with no successor. That history lets us answer two questions a flat "current state"
+ * store cannot:
+ *
+ *   • as-of  — "what did we believe at time T?"  (currentAsOf)
+ *   • diff   — "what changed between T1 and T2?" (changesBetween)
+ *
+ * Both are pure, deterministic, and timestamp-only — no LLM. They turn the supersession chain
+ * the consolidator already maintains into first-class time-travel queries.
+ */
+/** Statuses that mark a belief as no longer current; their `updatedAt` is when it stopped being current. */
+const TERMINAL_STATUSES = new Set(["superseded", "archived"]);
+function ms(value) {
+    const t = value instanceof Date ? value.getTime() : new Date(value).getTime();
+    return Number.isFinite(t) ? t : 0;
+}
+/**
+ * The beliefs that were CURRENT as of `at`. A belief is current at `at` iff it had been created
+ * by then (createdAt ≤ at) and had not yet been retired/replaced by then — i.e. it is still live,
+ * or it was terminated (superseded/archived) only at a later time (updatedAt > at).
+ */
+export function currentAsOf(records, at) {
+    const t = ms(at);
+    return records.filter((r) => {
+        if (ms(r.createdAt) > t)
+            return false; // didn't exist yet
+        if (TERMINAL_STATUSES.has(r.status))
+            return ms(r.updatedAt) > t; // retired only after `at`
+        return true; // active / stale / conflicted — live at `at`
+    });
+}
+/**
+ * The changelog over [from, to] (inclusive): beliefs added (created in window) and beliefs that
+ * stopped being current in the window — `superseded` (has a successor) or `retired` (obsoleted,
+ * no successor). Sorted chronologically. This is the "what changed" / knowledge-update view.
+ */
+export function changesBetween(records, from, to) {
+    const lo = ms(from);
+    const hi = ms(to);
+    const entries = [];
+    for (const r of records) {
+        const created = ms(r.createdAt);
+        if (created >= lo && created <= hi) {
+            entries.push({ kind: "added", at: r.createdAt, record: r });
+        }
+        if (r.status === "superseded") {
+            const changedAt = ms(r.updatedAt);
+            if (changedAt >= lo && changedAt <= hi) {
+                entries.push({
+                    kind: r.supersededBy ? "superseded" : "retired",
+                    at: r.updatedAt,
+                    record: r,
+                    replacementId: r.supersededBy
+                });
+            }
+        }
+    }
+    return entries.sort((a, b) => ms(a.at) - ms(b.at));
+}

package/dist/token-ab-monitor.d.ts

@@ -0,0 +1 @@
+export declare function renderTokenAbMonitorHtml(): string;

package/dist/token-ab-monitor.js

@@ -0,0 +1,7 @@
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export function renderTokenAbMonitorHtml() {
+    return readFileSync(join(__dirname, "..", "scripts", "token-ab-monitor.html"), "utf8");
+}