memwarden 0.0.1

package/dist/state/schema.d.ts

@@ -0,0 +1,60 @@
+export declare const KV: {
+    readonly sessions: "mem:sessions";
+    readonly observations: (sessionId: string) => string;
+    readonly memories: "mem:memories";
+    readonly summaries: "mem:summaries";
+    readonly config: "mem:config";
+    readonly metrics: "mem:metrics";
+    readonly health: "mem:health";
+    readonly embeddings: (obsId: string) => string;
+    readonly bm25Index: "mem:index:bm25";
+    readonly relations: "mem:relations";
+    readonly profiles: "mem:profiles";
+    readonly claudeBridge: "mem:claude-bridge";
+    readonly graphNodes: "mem:graph:nodes";
+    readonly graphEdges: "mem:graph:edges";
+    readonly semantic: "mem:semantic";
+    readonly procedural: "mem:procedural";
+    readonly teamShared: (teamId: string) => string;
+    readonly teamUsers: (teamId: string, userId: string) => string;
+    readonly teamProfile: (teamId: string) => string;
+    readonly audit: "mem:audit";
+    readonly actions: "mem:actions";
+    readonly actionEdges: "mem:action-edges";
+    readonly leases: "mem:leases";
+    readonly routines: "mem:routines";
+    readonly routineRuns: "mem:routine-runs";
+    readonly signals: "mem:signals";
+    readonly checkpoints: "mem:checkpoints";
+    readonly mesh: "mem:mesh";
+    readonly sketches: "mem:sketches";
+    readonly facets: "mem:facets";
+    readonly sentinels: "mem:sentinels";
+    readonly crystals: "mem:crystals";
+    readonly lessons: "mem:lessons";
+    readonly insights: "mem:insights";
+    readonly graphEdgeHistory: "mem:graph:edge-history";
+    readonly enrichedChunks: (sessionId: string) => string;
+    readonly latentEmbeddings: (obsId: string) => string;
+    readonly quantParams: "mem:quant:params";
+    readonly retentionScores: "mem:retention";
+    readonly accessLog: "mem:access";
+    readonly imageRefs: "mem:image-refs";
+    readonly imageEmbeddings: "mem:image-embeddings";
+    readonly slots: "mem:slots";
+    readonly globalSlots: "mem:slots:global";
+    readonly state: "mem:state";
+    readonly commits: "mem:commits";
+    readonly recentSearches: "mem:recent-searches";
+};
+export declare const STREAM: {
+    readonly name: "mem-live";
+    readonly group: (sessionId: string) => string;
+    readonly viewerGroup: "viewer";
+};
+/** A sortable, collision-resistant id: prefix + base36 time + random tail. */
+export declare function generateId(prefix: string): string;
+/** A deterministic id derived from content (same content -> same id). */
+export declare function fingerprintId(prefix: string, content: string): string;
+/** Word-set Jaccard overlap, ignoring tokens of 2 characters or fewer. */
+export declare function jaccardSimilarity(a: string, b: string): number;

package/dist/state/schema.js

@@ -0,0 +1,88 @@
+//
+// The single source of truth for KV scope names, plus a few pure id and
+// similarity helpers. Scopes are exact-match strings (no prefix hierarchy):
+// list(scope) returns just that scope's values, and cross-session enumeration
+// is list(KV.sessions) followed by list(KV.observations(id)) per session.
+import { createHash, randomUUID } from "node:crypto";
+export const KV = {
+    sessions: "mem:sessions",
+    observations: (sessionId) => `mem:obs:${sessionId}`,
+    memories: "mem:memories",
+    summaries: "mem:summaries",
+    config: "mem:config",
+    metrics: "mem:metrics",
+    health: "mem:health",
+    embeddings: (obsId) => `mem:emb:${obsId}`,
+    bm25Index: "mem:index:bm25",
+    relations: "mem:relations",
+    profiles: "mem:profiles",
+    claudeBridge: "mem:claude-bridge",
+    graphNodes: "mem:graph:nodes",
+    graphEdges: "mem:graph:edges",
+    semantic: "mem:semantic",
+    procedural: "mem:procedural",
+    teamShared: (teamId) => `mem:team:${teamId}:shared`,
+    teamUsers: (teamId, userId) => `mem:team:${teamId}:users:${userId}`,
+    teamProfile: (teamId) => `mem:team:${teamId}:profile`,
+    audit: "mem:audit",
+    actions: "mem:actions",
+    actionEdges: "mem:action-edges",
+    leases: "mem:leases",
+    routines: "mem:routines",
+    routineRuns: "mem:routine-runs",
+    signals: "mem:signals",
+    checkpoints: "mem:checkpoints",
+    mesh: "mem:mesh",
+    sketches: "mem:sketches",
+    facets: "mem:facets",
+    sentinels: "mem:sentinels",
+    crystals: "mem:crystals",
+    lessons: "mem:lessons",
+    insights: "mem:insights",
+    graphEdgeHistory: "mem:graph:edge-history",
+    enrichedChunks: (sessionId) => `mem:enriched:${sessionId}`,
+    // Reserved per-observation quantized codes; a later phase persists the whole
+    // quantized index as one blob under `quantParams` instead.
+    latentEmbeddings: (obsId) => `mem:latent:${obsId}`,
+    quantParams: "mem:quant:params",
+    retentionScores: "mem:retention",
+    accessLog: "mem:access",
+    imageRefs: "mem:image-refs",
+    imageEmbeddings: "mem:image-embeddings",
+    slots: "mem:slots",
+    globalSlots: "mem:slots:global",
+    state: "mem:state",
+    commits: "mem:commits",
+    recentSearches: "mem:recent-searches",
+};
+export const STREAM = {
+    name: "mem-live",
+    group: (sessionId) => sessionId,
+    viewerGroup: "viewer",
+};
+/** A sortable, collision-resistant id: prefix + base36 time + random tail. */
+export function generateId(prefix) {
+    const time = Date.now().toString(36);
+    const tail = randomUUID().replace(/-/g, "").slice(0, 12);
+    return `${prefix}_${time}_${tail}`;
+}
+/** A deterministic id derived from content (same content -> same id). */
+export function fingerprintId(prefix, content) {
+    const digest = createHash("sha256").update(content).digest("hex");
+    return `${prefix}_${digest.slice(0, 16)}`;
+}
+/** Word-set Jaccard overlap, ignoring tokens of 2 characters or fewer. */
+export function jaccardSimilarity(a, b) {
+    const words = (s) => new Set(s.split(/\s+/).filter((t) => t.length > 2));
+    const left = words(a);
+    const right = words(b);
+    if (left.size === 0 && right.size === 0)
+        return 1;
+    if (left.size === 0 || right.size === 0)
+        return 0;
+    let shared = 0;
+    for (const w of left)
+        if (right.has(w))
+            shared++;
+    return shared / (left.size + right.size - shared);
+}

package/dist/state/store-libsql.d.ts

@@ -0,0 +1,46 @@
+import { type MutationListener, type OplogEntry, type StateStore, type UpdateOp } from "./store.js";
+export interface StoreLibsqlOptions {
+    /** libSQL URL: `file:/path/to/mem.db` or `:memory:`. */
+    url: string;
+    /** Optional auth token (for remote libSQL/Turso; unused for local files). */
+    authToken?: string;
+}
+export declare class StoreLibsql implements StateStore {
+    private readonly client;
+    private readonly listeners;
+    /** Serializes writes so the oplog prev_hash read+append is atomic per-process. */
+    private writeChain;
+    private ready;
+    private closed;
+    constructor(options: StoreLibsqlOptions);
+    /** Idempotently apply the schema. Awaited by every public method. */
+    private init;
+    get<T = unknown>(scope: string, key: string): Promise<T | null>;
+    list<T = unknown>(scope: string): Promise<T[]>;
+    set<T = unknown>(scope: string, key: string, value: T): Promise<T>;
+    update<T = unknown>(scope: string, key: string, ops: readonly UpdateOp[]): Promise<T>;
+    delete(scope: string, key: string): Promise<void>;
+    onMutation(listener: MutationListener): () => void;
+    readOplog(sinceId?: number): Promise<OplogEntry[]>;
+    verifyOplog(): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        brokenAt: number;
+    }>;
+    close(): Promise<void>;
+    /**
+     * Perform one mutation + its matching oplog append as a single atomic batch.
+     * Reads the current value (for old_value / the update base) and the oplog
+     * tail (for prev_hash) first; serialization via the write chain guarantees no
+     * other write interleaves between the reads and the batch commit. Returns the
+     * mutation event to emit, or null for a delete that hit nothing (idempotent
+     * no-op, no oplog row).
+     */
+    private writeTx;
+    /** Build the hash-chained oplog INSERT statement for the next entry. */
+    private buildOplogInsert;
+    /** Chain writes so prev_hash reads never race a concurrent append. */
+    private serializeWrite;
+    private emit;
+}

package/dist/state/store-libsql.js

@@ -0,0 +1,263 @@
+//
+// libSQL-backed StateStore. Replaces the original file-based KV
+// (./data/state_store.db, opaque blob) with a real relational store that
+// gives `list(scope)` an exact index lookup instead of an O(N) scan, while
+// preserving every observable StateKV semantic.
+//
+// Schema (one co-located file, `file:...` or `:memory:`):
+// kv(scope TEXT, key TEXT, value TEXT JSON, created_at, updated_at,
+// PRIMARY KEY (scope, key))            -- index on scope for list()
+// oplog(id INTEGER PK AUTOINCREMENT, ts, op, scope, key,
+// payload TEXT JSON, prev_hash, hash)
+//
+// Writes (set/update/delete) read the current value + oplog tail, then commit
+// the `kv` change AND the matching `oplog` row as a SINGLE atomic batch, so the
+// hash chain and the data can never diverge. We use `batch` rather than an
+// interactive transaction because the libSQL local driver opens a separate
+// connection per interactive transaction, and a `:memory:` database is
+// per-connection (the transaction would not see the schema/data). All writes
+// are serialized through an in-process promise chain: the read-then-batch pair
+// must be atomic with respect to other writes because `prev_hash` depends on
+// the previous committed entry. This is correct only for a single-process
+// kernel; a multi-process memwarden would need a real lock (the same caveat
+// as withKeyedLock).
+import { createClient } from "@libsql/client";
+import { applyUpdateOps, } from "./store.js";
+import { GENESIS_PREV_HASH, hashOplogEntry, verifyChain } from "./oplog.js";
+const SCHEMA = [
+    `CREATE TABLE IF NOT EXISTS kv (
+     scope TEXT NOT NULL,
+     key TEXT NOT NULL,
+     value TEXT NOT NULL,
+     created_at TEXT NOT NULL,
+     updated_at TEXT NOT NULL,
+     PRIMARY KEY (scope, key)
+   )`,
+    `CREATE INDEX IF NOT EXISTS idx_kv_scope ON kv (scope)`,
+    `CREATE TABLE IF NOT EXISTS oplog (
+     id INTEGER PRIMARY KEY AUTOINCREMENT,
+     ts TEXT NOT NULL,
+     op TEXT NOT NULL,
+     scope TEXT NOT NULL,
+     key TEXT NOT NULL,
+     payload TEXT,
+     prev_hash TEXT NOT NULL,
+     hash TEXT NOT NULL
+   )`,
+    `CREATE INDEX IF NOT EXISTS idx_oplog_scope ON oplog (scope, key)`,
+];
+export class StoreLibsql {
+    client;
+    listeners = new Set();
+    /** Serializes writes so the oplog prev_hash read+append is atomic per-process. */
+    writeChain = Promise.resolve();
+    ready = null;
+    closed = false;
+    constructor(options) {
+        this.client = createClient(options.authToken === undefined
+            ? { url: options.url }
+            : { url: options.url, authToken: options.authToken });
+    }
+    /** Idempotently apply the schema. Awaited by every public method. */
+    init() {
+        if (!this.ready) {
+            this.ready = (async () => {
+                for (const stmt of SCHEMA) {
+                    await this.client.execute(stmt);
+                }
+            })();
+        }
+        return this.ready;
+    }
+    async get(scope, key) {
+        await this.init();
+        const res = await this.client.execute({
+            sql: `SELECT value FROM kv WHERE scope = ? AND key = ?`,
+            args: [scope, key],
+        });
+        const row = res.rows[0];
+        if (!row)
+            return null;
+        return decode(row.value);
+    }
+    async list(scope) {
+        await this.init();
+        // Insertion order: rowid is monotonic with insert order, and an upsert
+        // updates value in place without changing rowid, so ordering by rowid
+        // reproduces Map insertion-order semantics.
+        const res = await this.client.execute({
+            sql: `SELECT value FROM kv WHERE scope = ? ORDER BY rowid ASC`,
+            args: [scope],
+        });
+        return res.rows.map((row) => decode(row.value));
+    }
+    async set(scope, key, value) {
+        await this.serializeWrite(async () => {
+            // set always produces an event (never the delete-no-op null).
+            const event = await this.writeTx("set", scope, key, value);
+            if (event)
+                this.emit(event);
+        });
+        return value;
+    }
+    async update(scope, key, ops) {
+        let updated = {};
+        await this.serializeWrite(async () => {
+            // update always produces an event (never the delete-no-op null).
+            const event = await this.writeTx("update", scope, key, undefined, ops);
+            if (event) {
+                updated = event.new_value;
+                this.emit(event);
+            }
+        });
+        return updated;
+    }
+    async delete(scope, key) {
+        await this.serializeWrite(async () => {
+            const event = await this.writeTx("delete", scope, key, undefined);
+            // Only emit/log if the row actually existed (event is null otherwise).
+            if (event)
+                this.emit(event);
+        });
+    }
+    onMutation(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    async readOplog(sinceId) {
+        await this.init();
+        const res = await this.client.execute({
+            sql: `SELECT id, ts, op, scope, key, payload, prev_hash, hash
+            FROM oplog WHERE id > ? ORDER BY id ASC`,
+            args: [sinceId ?? 0],
+        });
+        return res.rows.map((row) => ({
+            id: Number(row.id),
+            ts: String(row.ts),
+            op: String(row.op),
+            scope: String(row.scope),
+            key: String(row.key),
+            payload: row.payload === null ? null : decode(row.payload),
+            prev_hash: String(row.prev_hash),
+            hash: String(row.hash),
+        }));
+    }
+    async verifyOplog() {
+        const entries = await this.readOplog();
+        const brokenAt = verifyChain(entries);
+        return brokenAt === null ? { ok: true } : { ok: false, brokenAt };
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        // Drain in-flight writes before closing the client.
+        await this.writeChain.catch(() => undefined);
+        this.listeners.clear();
+        this.client.close();
+    }
+    /**
+     * Perform one mutation + its matching oplog append as a single atomic batch.
+     * Reads the current value (for old_value / the update base) and the oplog
+     * tail (for prev_hash) first; serialization via the write chain guarantees no
+     * other write interleaves between the reads and the batch commit. Returns the
+     * mutation event to emit, or null for a delete that hit nothing (idempotent
+     * no-op, no oplog row).
+     */
+    async writeTx(op, scope, key, value, ops) {
+        await this.init();
+        const cur = await this.client.execute({
+            sql: `SELECT value FROM kv WHERE scope = ? AND key = ?`,
+            args: [scope, key],
+        });
+        const existingRow = cur.rows[0];
+        const oldValue = existingRow ? decode(existingRow.value) : undefined;
+        let newValue;
+        let mutation;
+        let event;
+        if (op === "delete") {
+            if (!existingRow)
+                return null;
+            newValue = null;
+            mutation = {
+                sql: `DELETE FROM kv WHERE scope = ? AND key = ?`,
+                args: [scope, key],
+            };
+            event = {
+                scope,
+                key,
+                event_type: "delete",
+                ...(oldValue === undefined ? {} : { old_value: oldValue }),
+            };
+        }
+        else {
+            if (op === "update") {
+                const base = oldValue && typeof oldValue === "object" && !Array.isArray(oldValue)
+                    ? oldValue
+                    : {};
+                newValue = applyUpdateOps({ ...base }, ops ?? []);
+            }
+            else {
+                newValue = value;
+            }
+            const now = new Date().toISOString();
+            mutation = {
+                sql: `INSERT INTO kv (scope, key, value, created_at, updated_at)
+              VALUES (?, ?, ?, ?, ?)
+              ON CONFLICT(scope, key)
+              DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at`,
+                args: [scope, key, encode(newValue), now, now],
+            };
+            event = {
+                scope,
+                key,
+                event_type: op,
+                ...(oldValue === undefined ? {} : { old_value: oldValue }),
+                new_value: newValue,
+            };
+        }
+        const oplogStmt = await this.buildOplogInsert(op, scope, key, newValue);
+        await this.client.batch([mutation, oplogStmt], "write");
+        return event;
+    }
+    /** Build the hash-chained oplog INSERT statement for the next entry. */
+    async buildOplogInsert(op, scope, key, payload) {
+        const tail = await this.client.execute(`SELECT id, hash FROM oplog ORDER BY id DESC LIMIT 1`);
+        const tailRow = tail.rows[0];
+        const id = tailRow ? Number(tailRow.id) + 1 : 1;
+        const prev_hash = tailRow ? String(tailRow.hash) : GENESIS_PREV_HASH;
+        const ts = new Date().toISOString();
+        const hash = hashOplogEntry({ id, ts, op, scope, key, payload, prev_hash });
+        return {
+            sql: `INSERT INTO oplog (id, ts, op, scope, key, payload, prev_hash, hash)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+            args: [id, ts, op, scope, key, payload === null ? null : encode(payload), prev_hash, hash],
+        };
+    }
+    /** Chain writes so prev_hash reads never race a concurrent append. */
+    serializeWrite(work) {
+        const next = this.writeChain.then(work, work);
+        // Keep the chain alive even if `work` rejects, without swallowing the
+        // rejection that the caller awaits.
+        this.writeChain = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Listeners must not break the write path.
+            }
+        }
+    }
+}
+function encode(value) {
+    return JSON.stringify(value === undefined ? null : value);
+}
+function decode(value) {
+    return JSON.parse(String(value));
+}

package/dist/state/store-memory.d.ts

@@ -0,0 +1,23 @@
+import { type MutationListener, type OplogEntry, type StateStore, type UpdateOp } from "./store.js";
+export declare class StoreMemory implements StateStore {
+    private readonly store;
+    private readonly listeners;
+    private readonly oplog;
+    private nextOplogId;
+    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: readonly UpdateOp[]): Promise<T>;
+    delete(scope: string, key: string): Promise<void>;
+    list<T = unknown>(scope: string): Promise<T[]>;
+    onMutation(listener: MutationListener): () => void;
+    readOplog(sinceId?: number): Promise<OplogEntry[]>;
+    verifyOplog(): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        brokenAt: number;
+    }>;
+    close(): Promise<void>;
+    private appendOplog;
+    private emit;
+}

package/dist/state/store-memory.js

@@ -0,0 +1,121 @@
+//
+// In-memory StateStore: a two-level `Map<scope, Map<key, value>>` with an
+// `update` method, mutation events, and an in-array hash-chained oplog. Used
+// for parity tests against StoreLibsql and as a dependency-free fallback.
+import { applyUpdateOps, } from "./store.js";
+import { GENESIS_PREV_HASH, hashOplogEntry, verifyChain } from "./oplog.js";
+/** Structured-clone a JSON value so callers can never mutate stored state. */
+function clone(value) {
+    if (value === null || typeof value !== "object")
+        return value;
+    return JSON.parse(JSON.stringify(value));
+}
+export class StoreMemory {
+    store = new Map();
+    listeners = new Set();
+    oplog = [];
+    nextOplogId = 1;
+    async get(scope, key) {
+        const value = this.store.get(scope)?.get(key);
+        return value === undefined ? null : clone(value);
+    }
+    async set(scope, key, value) {
+        const scopeMap = this.store.get(scope);
+        const old = scopeMap?.get(key);
+        const stored = clone(value);
+        if (scopeMap) {
+            scopeMap.set(key, stored);
+        }
+        else {
+            this.store.set(scope, new Map([[key, stored]]));
+        }
+        this.appendOplog("set", scope, key, stored);
+        this.emit({
+            scope,
+            key,
+            event_type: "set",
+            ...(old === undefined ? {} : { old_value: clone(old) }),
+            new_value: clone(stored),
+        });
+        return value;
+    }
+    async update(scope, key, ops) {
+        const scopeMap = this.store.get(scope);
+        const existing = scopeMap?.get(key);
+        const base = existing && typeof existing === "object" && !Array.isArray(existing)
+            ? clone(existing)
+            : {};
+        const updated = applyUpdateOps(base, ops);
+        if (scopeMap) {
+            scopeMap.set(key, updated);
+        }
+        else {
+            this.store.set(scope, new Map([[key, updated]]));
+        }
+        this.appendOplog("update", scope, key, updated);
+        this.emit({
+            scope,
+            key,
+            event_type: "update",
+            ...(existing === undefined ? {} : { old_value: clone(existing) }),
+            new_value: clone(updated),
+        });
+        return updated;
+    }
+    async delete(scope, key) {
+        const scopeMap = this.store.get(scope);
+        const old = scopeMap?.get(key);
+        const existed = scopeMap?.delete(key) ?? false;
+        // Idempotent: the original delete is unconditional and never errors, but
+        // we only log/emit when something actually changed to keep the oplog clean.
+        if (!existed)
+            return;
+        this.appendOplog("delete", scope, key, null);
+        this.emit({
+            scope,
+            key,
+            event_type: "delete",
+            ...(old === undefined ? {} : { old_value: clone(old) }),
+        });
+    }
+    async list(scope) {
+        const scopeMap = this.store.get(scope);
+        if (!scopeMap)
+            return [];
+        return Array.from(scopeMap.values(), (v) => clone(v));
+    }
+    onMutation(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    async readOplog(sinceId) {
+        const cutoff = sinceId ?? 0;
+        return this.oplog.filter((e) => e.id > cutoff).map((e) => ({ ...e }));
+    }
+    async verifyOplog() {
+        const brokenAt = verifyChain(this.oplog);
+        return brokenAt === null ? { ok: true } : { ok: false, brokenAt };
+    }
+    async close() {
+        this.listeners.clear();
+    }
+    appendOplog(op, scope, key, payload) {
+        const id = this.nextOplogId++;
+        const ts = new Date().toISOString();
+        const prev_hash = this.oplog.length === 0 ? GENESIS_PREV_HASH : this.oplog[this.oplog.length - 1].hash;
+        const hash = hashOplogEntry({ id, ts, op, scope, key, payload, prev_hash });
+        this.oplog.push({ id, ts, op, scope, key, payload: clone(payload), prev_hash, hash });
+    }
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Listeners must not break the write path.
+            }
+        }
+    }
+}

package/dist/state/store.d.ts

@@ -0,0 +1,87 @@
+/** A single update operation. Only `type:"set"` is ever produced by callers. */
+export interface UpdateOp {
+    readonly type: string;
+    readonly path: string;
+    readonly value?: unknown;
+}
+/** The kind of mutation an oplog entry / mutation event records. */
+export type StateEventType = "set" | "update" | "delete";
+/**
+ * Emitted by the store after a successful mutation. The kernel uses this to
+ * fire any registered type:"state" trigger whose scope matches `scope`
+ * (payload = {key, event_type, old_value, new_value}).
+ *
+ * For deletes, `new_value` is undefined. For sets/updates on a previously
+ * absent key, `old_value` is undefined.
+ */
+export interface StateMutationEvent {
+    readonly scope: string;
+    readonly key: string;
+    readonly event_type: StateEventType;
+    readonly old_value?: unknown;
+    readonly new_value?: unknown;
+}
+/** Listener invoked synchronously-after-commit for every mutation. */
+export type MutationListener = (event: StateMutationEvent) => void;
+/**
+ * One append-only oplog record. The hash chain makes the log tamper-evident:
+ * `hash = sha256(canonical(id, ts, op, scope, key, payload, prev_hash))`.
+ * `prev_hash` is the hash of the immediately preceding entry, or the empty
+ * string for the genesis entry.
+ */
+export interface OplogEntry {
+    readonly id: number;
+    readonly ts: string;
+    readonly op: StateEventType;
+    readonly scope: string;
+    readonly key: string;
+    /** The post-mutation value (set/update) or null (delete). JSON value. */
+    readonly payload: unknown;
+    readonly prev_hash: string;
+    readonly hash: string;
+}
+/**
+ * The single persistence chokepoint. All five methods mirror the original
+ * StateKV semantics exactly. Implementations: StoreLibsql (durable, libSQL)
+ * and StoreMemory (in-process Map mirror, used for parity tests).
+ */
+export interface StateStore {
+    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: readonly UpdateOp[]): Promise<T>;
+    delete(scope: string, key: string): Promise<void>;
+    list<T = unknown>(scope: string): Promise<T[]>;
+    /**
+     * Subscribe to mutation events. Returns an unsubscribe function. Listeners
+     * MUST NOT throw; the store wraps them defensively but a throwing listener
+     * only affects itself.
+     */
+    onMutation(listener: MutationListener): () => void;
+    /** Read the append-only oplog in id order (optionally from `sinceId`, exclusive). */
+    readOplog(sinceId?: number): Promise<OplogEntry[]>;
+    /**
+     * Verify the oplog hash chain end to end. Returns the id of the first
+     * broken link, or null if the chain is intact (or empty).
+     */
+    verifyOplog(): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        brokenAt: number;
+    }>;
+    /** Flush and release any resources (closes the libSQL client). Idempotent. */
+    close(): Promise<void>;
+}
+/**
+ * Apply the StateKV `update` op-list to a record, in place semantics returning
+ * the mutated record. Shared by both store implementations so their behavior
+ * is identical. Only `type:"set"` is honored (no push/inc/delete/append is
+ * ever produced by callers); `path` is a flat
+ * top-level field name, never dotted. Unknown op types are ignored.
+ */
+export declare function applyUpdateOps(current: Record<string, unknown>, ops: readonly UpdateOp[]): Record<string, unknown>;
+/**
+ * Canonical JSON for hashing/signing: deterministic key ordering so the same
+ * logical value always produces the same bytes regardless of insertion order.
+ */
+export declare function canonicalize(value: unknown): string;