memwarden 0.0.1

package/dist/observability/metrics.d.ts

@@ -0,0 +1,26 @@
+declare function estimateTokens(text: string): number;
+declare class Metrics {
+    private observeCount;
+    private observeRawTokens;
+    private observeStoredTokens;
+    private contextCount;
+    private contextCandidateTokens;
+    private contextServedTokens;
+    private contextLatency;
+    private searchCount;
+    private searchLatency;
+    private pushSample;
+    /** Record one observe: raw payload size vs the compressed record stored. */
+    recordObserve(rawText: string, storedText: string): void;
+    /**
+     * Record one context build: candidate = tokens of everything that
+     * matched, served = tokens actually returned under budget.
+     */
+    recordContext(candidateTokens: number, servedTokens: number, latencyMs: number): void;
+    recordSearch(latencyMs: number): void;
+    snapshot(): Record<string, unknown>;
+    reset(): void;
+}
+/** Process-wide metrics singleton. */
+export declare const metrics: Metrics;
+export { estimateTokens };

package/dist/observability/metrics.js

@@ -0,0 +1,104 @@
+//
+// In-process observability for memwarden. Tracks the two numbers that
+// decide whether this layer is actually good for an agent:
+//
+//   1. Token economy — how many tokens we save by storing compressed
+//      observations and serving budgeted context instead of raw history.
+//   2. Latency — how fast search and context return, so switching agents
+//      never means "wait while it finds the context."
+//
+// Running aggregates, no I/O on the hot path. Latency keeps a bounded
+// sample window for percentiles. Reset for tests. Durable persistence
+// (a cost-ledger KV table) can layer on top later without changing callers.
+const MAX_SAMPLES = 1000;
+function estimateTokens(text) {
+    // Same heuristic the context packer uses (~3 chars/token). Centralized
+    // here so every token number in the system comes from one place.
+    return Math.ceil(text.length / 3);
+}
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil((p / 100) * sorted.length) - 1));
+    return sorted[idx];
+}
+class Metrics {
+    observeCount = 0;
+    observeRawTokens = 0;
+    observeStoredTokens = 0;
+    contextCount = 0;
+    contextCandidateTokens = 0;
+    contextServedTokens = 0;
+    contextLatency = [];
+    searchCount = 0;
+    searchLatency = [];
+    pushSample(arr, v) {
+        arr.push(v);
+        if (arr.length > MAX_SAMPLES)
+            arr.shift();
+    }
+    /** Record one observe: raw payload size vs the compressed record stored. */
+    recordObserve(rawText, storedText) {
+        this.observeCount++;
+        this.observeRawTokens += estimateTokens(rawText);
+        this.observeStoredTokens += estimateTokens(storedText);
+    }
+    /**
+     * Record one context build: candidate = tokens of everything that
+     * matched, served = tokens actually returned under budget.
+     */
+    recordContext(candidateTokens, servedTokens, latencyMs) {
+        this.contextCount++;
+        this.contextCandidateTokens += candidateTokens;
+        this.contextServedTokens += servedTokens;
+        this.pushSample(this.contextLatency, latencyMs);
+    }
+    recordSearch(latencyMs) {
+        this.searchCount++;
+        this.pushSample(this.searchLatency, latencyMs);
+    }
+    snapshot() {
+        const ctxSorted = [...this.contextLatency].sort((a, b) => a - b);
+        const searchSorted = [...this.searchLatency].sort((a, b) => a - b);
+        const pct = (saved, total) => total > 0 ? Math.round((saved / total) * 1000) / 10 : 0;
+        return {
+            observe: {
+                count: this.observeCount,
+                rawTokens: this.observeRawTokens,
+                storedTokens: this.observeStoredTokens,
+                reductionPct: pct(this.observeRawTokens - this.observeStoredTokens, this.observeRawTokens),
+            },
+            context: {
+                count: this.contextCount,
+                candidateTokens: this.contextCandidateTokens,
+                servedTokens: this.contextServedTokens,
+                reductionPct: pct(this.contextCandidateTokens - this.contextServedTokens, this.contextCandidateTokens),
+                latencyMs: {
+                    p50: Math.round(percentile(ctxSorted, 50)),
+                    p95: Math.round(percentile(ctxSorted, 95)),
+                },
+            },
+            search: {
+                count: this.searchCount,
+                latencyMs: {
+                    p50: Math.round(percentile(searchSorted, 50)),
+                    p95: Math.round(percentile(searchSorted, 95)),
+                },
+            },
+        };
+    }
+    reset() {
+        this.observeCount = 0;
+        this.observeRawTokens = 0;
+        this.observeStoredTokens = 0;
+        this.contextCount = 0;
+        this.contextCandidateTokens = 0;
+        this.contextServedTokens = 0;
+        this.contextLatency = [];
+        this.searchCount = 0;
+        this.searchLatency = [];
+    }
+}
+/** Process-wide metrics singleton. */
+export const metrics = new Metrics();
+export { estimateTokens };

package/dist/proxy/server.d.ts

@@ -0,0 +1,30 @@
+import { type Server } from "node:http";
+export interface ProxyOptions {
+    /** Port to listen on. */
+    port: number;
+    host?: string;
+    /** Upstream OpenAI-compatible base URL, e.g. https://api.openai.com/v1. */
+    upstreamUrl: string;
+    /** API key forwarded to the upstream as Authorization: Bearer. */
+    upstreamKey?: string;
+    /** Local memwarden daemon base, e.g. http://127.0.0.1:3111. */
+    daemonUrl: string;
+    /**
+     * The install's shared secret. Used outbound for the daemon's auth'd
+     * routes, and enforced inbound: when set, proxy clients must present it as
+     * `Authorization: Bearer <secret>` (set the tool's API key to it).
+     */
+    secret?: string;
+    /** Project/workspace this proxy's captures belong to (defaults to cwd). */
+    project: string;
+    /** Working directory used to scope recall. */
+    cwd: string;
+    /** Token budget for injected memory. */
+    tokenBudget?: number;
+}
+export interface RunningProxy {
+    server: Server;
+    port: number;
+    close(): Promise<void>;
+}
+export declare function startProxyServer(opts: ProxyOptions): RunningProxy;

package/dist/proxy/server.js

@@ -0,0 +1,331 @@
+//
+// The memory proxy: an OpenAI-compatible gateway that turns memwarden into
+// a universal, automatic memory layer for every tool that speaks the
+// /v1/chat/completions protocol — local models (Ollama :11434/v1, LM Studio
+// :1234/v1) and paid ones (OpenAI, OpenRouter, Together) alike. They all
+// share that one boundary, and the proxy is blind to which is behind it, so
+// it is a single memory layer for all of them.
+//
+// On a chat completion the proxy:
+//   1. pulls the latest user turn as a query,
+//   2. asks the local daemon for relevant memory (/memwarden/search,
+//      narrative format),
+//   3. injects it as a system message ahead of the conversation,
+//   4. forwards the rewritten request to the configured upstream,
+//   5. streams the response straight back to the client unchanged while
+//      tee-ing it to reconstruct the assistant's answer,
+//   6. captures the user turn + answer into memory (/memwarden/observe).
+//
+// Everything else (GET /v1/models, etc.) is a transparent passthrough — no
+// injection, no capture. The kernel's own HTTP server JSON-buffers every
+// response and cannot stream, which is why the proxy is a separate node:http
+// server doing raw request/response piping.
+import { createServer, request as httpRequest, } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { URL } from "node:url";
+import { isLoopbackHost } from "../kernel/http.js";
+import { timingSafeCompare } from "../triggers/auth.js";
+import { isCaptureEnabled, isInjectEnabled, isProjectExcluded, } from "../functions/config.js";
+// Hop-by-hop headers must not be forwarded across a proxy boundary.
+const HOP_BY_HOP = new Set([
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+    "content-length",
+    "host",
+]);
+export function startProxyServer(opts) {
+    const host = opts.host ?? "127.0.0.1";
+    // One session per proxy process. Turns from different conversations share
+    // it; the daemon's dedup keys on the prompt so distinct prompts still land.
+    const ctx = { ...opts, sessionId: `proxy-${opts.port}` };
+    const server = createServer((req, res) => {
+        handle(req, res, ctx).catch((err) => {
+            if (!res.headersSent) {
+                res.statusCode = 502;
+                res.setHeader("content-type", "application/json");
+                res.end(JSON.stringify({
+                    error: "memwarden_proxy_error",
+                    message: err instanceof Error ? err.message : String(err),
+                }));
+            }
+            else if (!res.writableEnded) {
+                res.end();
+            }
+        });
+    });
+    server.listen(opts.port, host);
+    return {
+        server,
+        port: opts.port,
+        close: () => new Promise((resolve) => server.close(() => resolve())),
+    };
+}
+async function handle(req, res, ctx) {
+    // Same DNS-rebinding firewall as the kernel HTTP server: the proxy is a
+    // localhost-only gateway that spends the upstream API key, so a webpage that
+    // rebinds DNS to 127.0.0.1 must not reach it. The Host header reflects the
+    // hostname the client actually targeted; reject anything non-loopback.
+    if (!isLoopbackHost(req.headers.host, req.socket.localPort)) {
+        res.statusCode = 403;
+        res.setHeader("content-type", "application/json");
+        res.end(JSON.stringify({ error: "forbidden_host" }));
+        return;
+    }
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const path = url.pathname;
+    if (req.method === "GET" && path === "/livez") {
+        res.statusCode = 200;
+        res.setHeader("content-type", "application/json");
+        res.end(JSON.stringify({ status: "ok", service: "memwarden-proxy" }));
+        return;
+    }
+    // Client auth: when the install has a secret, the proxy requires it too.
+    // The proxy substitutes the real upstream API key and writes captures into
+    // memory, so an open localhost port would let any local process spend the
+    // key and poison capture. OpenAI-compatible tools already send their
+    // configured API key as `Authorization: Bearer` — set that key to the
+    // memwarden secret. buildUpstreamHeaders strips the client Authorization
+    // before forwarding, so the secret never reaches the upstream. /livez
+    // stays open: it spends no key and captures nothing.
+    if (ctx.secret) {
+        const auth = req.headers.authorization;
+        if (typeof auth !== "string" ||
+            !timingSafeCompare(auth, `Bearer ${ctx.secret}`)) {
+            res.statusCode = 401;
+            res.setHeader("content-type", "application/json");
+            res.end(JSON.stringify({
+                error: "unauthorized",
+                message: "Set your tool's API key to the memwarden secret (the `secret` file in your data dir)",
+            }));
+            return;
+        }
+    }
+    const isChat = req.method === "POST" &&
+        (path === "/v1/chat/completions" || path === "/chat/completions");
+    const reqBody = await readBody(req);
+    // For a chat completion, inject memory and remember the query so we can
+    // capture the answer. Other paths pass straight through.
+    // The same switches the hooks honor: MEMWARDEN_INJECT / MEMWARDEN_CAPTURE
+    // and the per-project exclude list, checked per request so `memwarden
+    // exclude` takes effect without a daemon restart.
+    const excluded = isProjectExcluded(ctx.cwd);
+    const inject = isInjectEnabled() && !excluded;
+    const capture = isCaptureEnabled() && !excluded;
+    let outBody = reqBody;
+    let query = "";
+    if (isChat && reqBody.length && (inject || capture)) {
+        try {
+            const payload = JSON.parse(reqBody.toString("utf8"));
+            query = extractUserQuery(payload);
+            if (query && inject) {
+                const memory = await fetchMemory(ctx, query).catch(() => "");
+                if (memory) {
+                    outBody = Buffer.from(JSON.stringify(injectMemory(payload, memory)), "utf8");
+                }
+            }
+        }
+        catch {
+            // Not JSON we understand — forward the original bytes untouched.
+        }
+    }
+    const target = new URL(ctx.upstreamUrl + path.replace(/^\/v1/, ""));
+    const upstream = await requestUpstream(target, req.method ?? "GET", buildUpstreamHeaders(req.headers, outBody, ctx.upstreamKey), outBody.length ? outBody : undefined);
+    res.statusCode = upstream.statusCode ?? 502;
+    for (const [k, v] of Object.entries(upstream.headers)) {
+        if (v === undefined || HOP_BY_HOP.has(k.toLowerCase()))
+            continue;
+        res.setHeader(k, v);
+    }
+    // Pipe the response straight back, tee-ing it so we can reconstruct the
+    // assistant's answer for capture once the stream finishes.
+    const captured = [];
+    const wantCapture = isChat && query !== "" && capture;
+    upstream.on("data", (chunk) => {
+        if (wantCapture)
+            captured.push(chunk);
+        res.write(chunk);
+    });
+    upstream.on("end", () => {
+        res.end();
+        if (wantCapture && (upstream.statusCode ?? 0) < 400) {
+            const answer = extractAnswer(Buffer.concat(captured), upstream.headers["content-type"]);
+            if (answer)
+                void captureExchange(ctx, query, answer);
+        }
+    });
+    upstream.on("error", () => {
+        if (!res.writableEnded)
+            res.end();
+    });
+}
+// --- request/response plumbing -------------------------------------
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (c) => chunks.push(c));
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}
+function buildUpstreamHeaders(incoming, body, upstreamKey) {
+    const out = {};
+    for (const [k, v] of Object.entries(incoming)) {
+        const lower = k.toLowerCase();
+        if (v === undefined || HOP_BY_HOP.has(lower))
+            continue;
+        if (lower === "authorization")
+            continue; // overridden below
+        if (lower === "accept-encoding")
+            continue; // forced to identity below
+        out[k] = Array.isArray(v) ? v.join(", ") : v;
+    }
+    // Identity encoding so the tee can parse the answer without gunzipping.
+    out["accept-encoding"] = "identity";
+    if (body.length)
+        out["content-length"] = String(body.length);
+    // The client's key (if any) is replaced with the configured upstream key;
+    // a local model that needs none simply gets no Authorization header.
+    if (upstreamKey)
+        out["authorization"] = `Bearer ${upstreamKey}`;
+    return out;
+}
+function requestUpstream(target, method, headers, body) {
+    return new Promise((resolve, reject) => {
+        const isHttps = target.protocol === "https:";
+        const send = isHttps ? httpsRequest : httpRequest;
+        const req = send({
+            protocol: target.protocol,
+            hostname: target.hostname,
+            port: target.port || (isHttps ? 443 : 80),
+            path: target.pathname + target.search,
+            method,
+            headers,
+        }, (res) => resolve(res));
+        req.on("error", reject);
+        if (body)
+            req.write(body);
+        req.end();
+    });
+}
+function messageText(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((p) => (typeof p?.text === "string" ? p.text : ""))
+            .filter(Boolean)
+            .join("\n");
+    }
+    return "";
+}
+function extractUserQuery(payload) {
+    const messages = Array.isArray(payload.messages) ? payload.messages : [];
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m && m.role === "user")
+            return messageText(m.content).trim();
+    }
+    return "";
+}
+function injectMemory(payload, memory) {
+    const messages = Array.isArray(payload.messages)
+        ? payload.messages.slice()
+        : [];
+    const sys = {
+        role: "system",
+        content: "# Relevant memory (memwarden)\n" +
+            "Context recalled from past sessions. Use it if helpful; ignore if not.\n\n" +
+            memory,
+    };
+    // Insert after any leading system messages so the developer's own system
+    // prompt still comes first.
+    let at = 0;
+    while (at < messages.length && messages[at]?.role === "system")
+        at++;
+    messages.splice(at, 0, sys);
+    return { ...payload, messages };
+}
+function extractAnswer(buf, contentType) {
+    const text = buf.toString("utf8");
+    const ct = typeof contentType === "string" ? contentType : "";
+    if (ct.includes("text/event-stream") || text.startsWith("data:")) {
+        let acc = "";
+        for (const line of text.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed.startsWith("data:"))
+                continue;
+            const data = trimmed.slice(5).trim();
+            if (!data || data === "[DONE]")
+                continue;
+            try {
+                const obj = JSON.parse(data);
+                const piece = obj.choices?.[0]?.delta?.content;
+                if (typeof piece === "string")
+                    acc += piece;
+            }
+            catch {
+                // skip malformed SSE frame
+            }
+        }
+        return acc.trim();
+    }
+    try {
+        const obj = JSON.parse(text);
+        const content = obj.choices?.[0]?.message?.content;
+        if (content !== undefined)
+            return messageText(content).trim();
+    }
+    catch {
+        // not JSON
+    }
+    return "";
+}
+// --- daemon calls (recall + capture) -------------------------------
+function daemonHeaders(secret) {
+    const h = { "content-type": "application/json" };
+    if (secret)
+        h["authorization"] = `Bearer ${secret}`;
+    return h;
+}
+async function fetchMemory(ctx, query) {
+    const res = await fetch(`${ctx.daemonUrl}/memwarden/search`, {
+        method: "POST",
+        headers: daemonHeaders(ctx.secret),
+        body: JSON.stringify({
+            query,
+            format: "narrative",
+            project: ctx.project,
+            cwd: ctx.cwd,
+            safe_only: true, // Verified Recall: never inject stale memory into a model call
+            ...(ctx.tokenBudget ? { token_budget: ctx.tokenBudget } : {}),
+        }),
+    });
+    if (!res.ok)
+        return "";
+    const body = (await res.json());
+    return typeof body.text === "string" ? body.text : "";
+}
+async function captureExchange(ctx, query, answer) {
+    await fetch(`${ctx.daemonUrl}/memwarden/observe`, {
+        method: "POST",
+        headers: daemonHeaders(ctx.secret),
+        body: JSON.stringify({
+            hookType: "post_tool_use",
+            sessionId: ctx.sessionId,
+            project: ctx.project,
+            cwd: ctx.cwd,
+            timestamp: new Date().toISOString(),
+            data: {
+                tool_name: "chat",
+                tool_input: { prompt: query.slice(0, 4000) },
+                tool_output: answer.slice(0, 8000),
+            },
+        }),
+    }).catch(() => undefined);
+}

package/dist/state/kv.d.ts

@@ -0,0 +1,41 @@
+/** Built-in state function ids the kernel routes to the StateStore. */
+export declare const STATE_FUNCTION_IDS: {
+    readonly get: "state::get";
+    readonly set: "state::set";
+    readonly update: "state::update";
+    readonly delete: "state::delete";
+    readonly list: "state::list";
+};
+/** A single flat update operation; callers only ever produce `type:"set"`. */
+export interface KvUpdateOp {
+    type: string;
+    path: string;
+    value?: unknown;
+}
+/** The one dispatch method StateKV needs; the kernel's ISdk satisfies it. */
+export interface TriggerSink {
+    trigger<P = unknown, R = unknown>(opts: {
+        function_id: string;
+        payload: P;
+        action?: unknown;
+    }): Promise<R>;
+}
+/**
+ * Five-method KV facade over the kernel trigger chokepoint:
+ *   get    -> T | null  (null on miss, never throws)
+ *   set    -> upsert, returns the written value (last write wins)
+ *   update -> read-or-{}, apply flat set-ops, write back, return result
+ *   delete -> idempotent, void
+ *   list   -> values only, exact scope match, insertion order, [] on miss
+ */
+export declare class StateKV {
+    private readonly sdk;
+    constructor(sdk: TriggerSink);
+    private call;
+    get<T = unknown>(scope: string, key: string): Promise<T | null>;
+    set<T = unknown>(scope: string, key: string, value: T): Promise<T>;
+    update<T = unknown>(scope: string, key: string, ops: Array<KvUpdateOp>): Promise<T>;
+    delete(scope: string, key: string): Promise<void>;
+    list<T = unknown>(scope: string): Promise<T[]>;
+}
+export type { ISdk } from "../kernel/index.js";

package/dist/state/kv.js

@@ -0,0 +1,50 @@
+//
+// StateKV is the single persistence chokepoint for every mem:: function. It
+// turns five operations (get/set/update/delete/list over scope + key) into one
+// trigger dispatch against the in-process kernel, which routes the five
+// state::* function ids to a StateStore (store.ts / store-libsql.ts /
+// store-memory.ts).
+//
+// The constructor takes the narrow TriggerSink (just the `trigger` method) so
+// the state layer has no build-time dependency on the kernel; the kernel's ISdk
+// is structurally assignable and re-exported below for `new StateKV(kernel)`.
+/** Built-in state function ids the kernel routes to the StateStore. */
+export const STATE_FUNCTION_IDS = {
+    get: "state::get",
+    set: "state::set",
+    update: "state::update",
+    delete: "state::delete",
+    list: "state::list",
+};
+/**
+ * Five-method KV facade over the kernel trigger chokepoint:
+ *   get    -> T | null  (null on miss, never throws)
+ *   set    -> upsert, returns the written value (last write wins)
+ *   update -> read-or-{}, apply flat set-ops, write back, return result
+ *   delete -> idempotent, void
+ *   list   -> values only, exact scope match, insertion order, [] on miss
+ */
+export class StateKV {
+    sdk;
+    constructor(sdk) {
+        this.sdk = sdk;
+    }
+    call(functionId, payload) {
+        return this.sdk.trigger({ function_id: functionId, payload });
+    }
+    get(scope, key) {
+        return this.call(STATE_FUNCTION_IDS.get, { scope, key });
+    }
+    set(scope, key, value) {
+        return this.call(STATE_FUNCTION_IDS.set, { scope, key, value });
+    }
+    update(scope, key, ops) {
+        return this.call(STATE_FUNCTION_IDS.update, { scope, key, ops });
+    }
+    delete(scope, key) {
+        return this.call(STATE_FUNCTION_IDS.delete, { scope, key });
+    }
+    list(scope) {
+        return this.call(STATE_FUNCTION_IDS.list, { scope });
+    }
+}

package/dist/state/oplog.d.ts

@@ -0,0 +1,25 @@
+import { type OplogEntry, type StateEventType } from "./store.js";
+/** The empty-string sentinel used as `prev_hash` for the genesis entry. */
+export declare const GENESIS_PREV_HASH = "";
+/**
+ * Compute the hash for an oplog entry. The hash covers everything that
+ * matters for tamper-evidence: identity, time, operation, location, value,
+ * and the link to the previous entry. The `hash` field itself is excluded
+ * (it is the output).
+ */
+export declare function hashOplogEntry(fields: {
+    id: number;
+    ts: string;
+    op: StateEventType;
+    scope: string;
+    key: string;
+    payload: unknown;
+    prev_hash: string;
+}): string;
+/**
+ * Walk an ordered list of oplog entries and confirm the chain is intact:
+ * ids strictly increasing, each entry's prev_hash equal to the prior entry's
+ * hash (genesis links to GENESIS_PREV_HASH), and each entry's hash matching a
+ * fresh recomputation. Returns the id of the first broken entry or null.
+ */
+export declare function verifyChain(entries: readonly OplogEntry[]): number | null;

package/dist/state/oplog.js

@@ -0,0 +1,57 @@
+//
+// Hash-chain helpers for the append-only oplog: a SHA-256 chain that is
+// tamper-evident (any edit/reorder/drop breaks the chain at the first touched
+// entry). The canonicalization here is the contract that anything signing the
+// oplog later would sign over, so it must stay stable.
+import { createHash } from "node:crypto";
+import { canonicalize } from "./store.js";
+/** The empty-string sentinel used as `prev_hash` for the genesis entry. */
+export const GENESIS_PREV_HASH = "";
+/**
+ * Compute the hash for an oplog entry. The hash covers everything that
+ * matters for tamper-evidence: identity, time, operation, location, value,
+ * and the link to the previous entry. The `hash` field itself is excluded
+ * (it is the output).
+ */
+export function hashOplogEntry(fields) {
+    const canonical = canonicalize({
+        id: fields.id,
+        ts: fields.ts,
+        op: fields.op,
+        scope: fields.scope,
+        key: fields.key,
+        payload: fields.payload ?? null,
+        prev_hash: fields.prev_hash,
+    });
+    return createHash("sha256").update(canonical).digest("hex");
+}
+/**
+ * Walk an ordered list of oplog entries and confirm the chain is intact:
+ * ids strictly increasing, each entry's prev_hash equal to the prior entry's
+ * hash (genesis links to GENESIS_PREV_HASH), and each entry's hash matching a
+ * fresh recomputation. Returns the id of the first broken entry or null.
+ */
+export function verifyChain(entries) {
+    let expectedPrev = GENESIS_PREV_HASH;
+    let lastId = -Infinity;
+    for (const entry of entries) {
+        if (entry.id <= lastId)
+            return entry.id;
+        if (entry.prev_hash !== expectedPrev)
+            return entry.id;
+        const recomputed = hashOplogEntry({
+            id: entry.id,
+            ts: entry.ts,
+            op: entry.op,
+            scope: entry.scope,
+            key: entry.key,
+            payload: entry.payload,
+            prev_hash: entry.prev_hash,
+        });
+        if (recomputed !== entry.hash)
+            return entry.id;
+        expectedPrev = entry.hash;
+        lastId = entry.id;
+    }
+    return null;
+}