backpack-ontology 0.2.24 → 0.3.0

package/dist/storage/event-sourced-backend.js

@@ -0,0 +1,840 @@
+// ============================================================
+// Event-sourced storage backend.
+//
+// Each graph branch is an append-only events.jsonl file plus a
+// snapshot.json materialized cache. Events are the source of truth;
+// the snapshot is a derived view that exists for fast reads.
+//
+// On-disk layout:
+//   graphs/<name>/
+//     metadata.json              graph-level metadata + defaultBranch
+//     branches/<branch>/
+//       events.jsonl             append-only event log (truth)
+//       snapshot.json            materialized cache (rebuildable)
+//     snippets/<id>.json         saved queries (orthogonal to events)
+//     terms.json                 term registry (carry-forward)
+//
+// Snapshots (the user-visible "save state and roll back here later"
+// feature) are events with op="snapshot.label". Listing snapshots is
+// scanning events for label entries. Rolling back is truncating the
+// event log at the snapshot's position.
+//
+// Branches are forks: creating a branch copies the parent branch's
+// events.jsonl and snapshot.json into a new branch directory.
+//
+// The current event count of a branch is its version number, used
+// for optimistic concurrency.
+// ============================================================
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { dataDir } from "../core/paths.js";
+import { applyEvents, diffToEvents, makeSnapshotLabelEvent, parseEvent, replay, serializeEvent, } from "../core/events.js";
+const SCHEMA_VERSION = 1;
+const DEFAULT_BRANCH = "main";
+/** How long a heartbeat is considered "fresh" before it's treated as stale. */
+export const LOCK_FRESH_MS = 5 * 60 * 1000;
+/**
+ * Error thrown when an optimistic-concurrency write detects that the
+ * underlying graph has been modified since the caller loaded it.
+ */
+export class ConcurrencyError extends Error {
+    graph;
+    expectedVersion;
+    actualVersion;
+    constructor(graph, expectedVersion, actualVersion) {
+        super(`version conflict on "${graph}": expected ${expectedVersion}, found ${actualVersion}`);
+        this.graph = graph;
+        this.expectedVersion = expectedVersion;
+        this.actualVersion = actualVersion;
+        this.name = "ConcurrencyError";
+    }
+}
+function emptyGraphData(name, description) {
+    const now = new Date().toISOString();
+    return {
+        metadata: {
+            name,
+            description,
+            createdAt: now,
+            updatedAt: now,
+        },
+        nodes: [],
+        edges: [],
+    };
+}
+export class EventSourcedBackend {
+    baseDir;
+    author;
+    constructor(baseDir, options) {
+        this.baseDir = baseDir ?? dataDir();
+        this.author =
+            options?.author ?? process.env.BACKPACK_AUTHOR ?? undefined;
+    }
+    /**
+     * Set the author identifier used for newly-emitted events. Pass
+     * undefined to clear it. Useful in tests and in long-running
+     * processes where the active user changes.
+     */
+    setAuthor(author) {
+        this.author = author;
+    }
+    getAuthor() {
+        return this.author;
+    }
+    // --- Path helpers ---
+    graphsDir() {
+        return path.join(this.baseDir, "graphs");
+    }
+    graphDir(name) {
+        return path.join(this.graphsDir(), name);
+    }
+    metadataFile(name) {
+        return path.join(this.graphDir(name), "metadata.json");
+    }
+    branchesDir(name) {
+        return path.join(this.graphDir(name), "branches");
+    }
+    branchDir(name, branch) {
+        return path.join(this.branchesDir(name), branch);
+    }
+    eventsFile(name, branch) {
+        return path.join(this.branchDir(name, branch), "events.jsonl");
+    }
+    snapshotFile(name, branch) {
+        return path.join(this.branchDir(name, branch), "snapshot.json");
+    }
+    snippetsDir(name) {
+        return path.join(this.graphDir(name), "snippets");
+    }
+    snippetFile(name, snippetId) {
+        return path.join(this.snippetsDir(name), `${snippetId}.json`);
+    }
+    termsFile(name) {
+        return path.join(this.graphDir(name), "terms.json");
+    }
+    lockFile(name) {
+        return path.join(this.graphDir(name), ".lock");
+    }
+    // --- IO helpers ---
+    async writeAtomic(filePath, content) {
+        const tmp = `${filePath}.tmp`;
+        await fs.writeFile(tmp, content, "utf8");
+        await fs.rename(tmp, filePath);
+    }
+    // --- Metadata ---
+    async loadMetadata(name) {
+        let raw;
+        try {
+            raw = await fs.readFile(this.metadataFile(name), "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                throw new Error(`Learning graph "${name}" not found`);
+            }
+            throw err;
+        }
+        const parsed = JSON.parse(raw);
+        if (typeof parsed !== "object" || parsed === null) {
+            throw new Error(`metadata.json for "${name}" is malformed`);
+        }
+        return parsed;
+    }
+    async writeMetadata(name, meta) {
+        await this.writeAtomic(this.metadataFile(name), JSON.stringify(meta, null, 2));
+    }
+    // --- Snapshot helpers ---
+    /**
+     * Load the materialized state for a branch. Reads snapshot.json
+     * directly. If the cache is missing, rebuilds it from the event log.
+     */
+    async loadBranchSnapshot(name, branch) {
+        try {
+            const raw = await fs.readFile(this.snapshotFile(name, branch), "utf8");
+            return JSON.parse(raw);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+            return this.rebuildSnapshot(name, branch);
+        }
+    }
+    async writeSnapshotFile(name, branch, data) {
+        await this.writeAtomic(this.snapshotFile(name, branch), JSON.stringify(data, null, 2));
+    }
+    async rebuildSnapshot(name, branch) {
+        const events = await this.loadEvents(name, branch);
+        const meta = await this.loadMetadata(name);
+        const initial = {
+            name: meta.name,
+            description: meta.description,
+            createdAt: meta.createdAt,
+            updatedAt: meta.updatedAt,
+        };
+        const state = replay(events, initial);
+        await this.writeSnapshotFile(name, branch, state);
+        return state;
+    }
+    // --- Event log helpers ---
+    async loadEvents(name, branch) {
+        let raw;
+        try {
+            raw = await fs.readFile(this.eventsFile(name, branch), "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return [];
+            throw err;
+        }
+        const events = [];
+        const lines = raw.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (line.trim().length === 0)
+                continue;
+            try {
+                events.push(parseEvent(line));
+            }
+            catch (err) {
+                throw new Error(`parse error in ${this.eventsFile(name, branch)}:${i + 1}: ${err.message}`);
+            }
+        }
+        return events;
+    }
+    async eventCount(name, branch) {
+        const events = await this.loadEvents(name, branch);
+        return events.length;
+    }
+    /**
+     * Append events to a branch's event log and update its snapshot
+     * cache. If `expectedVersion` is provided, the append fails when the
+     * current event count differs (optimistic concurrency).
+     *
+     * Returns the new event count after append.
+     */
+    async appendEvents(name, branch, events, expectedVersion) {
+        if (events.length === 0) {
+            return this.eventCount(name, branch);
+        }
+        if (expectedVersion !== undefined) {
+            const current = await this.eventCount(name, branch);
+            if (current !== expectedVersion) {
+                throw new ConcurrencyError(name, expectedVersion, current);
+            }
+        }
+        const currentState = await this.loadBranchSnapshot(name, branch);
+        const newState = applyEvents(currentState, events);
+        const lines = events.map(serializeEvent).join("\n") + "\n";
+        await fs.appendFile(this.eventsFile(name, branch), lines, "utf8");
+        await this.writeSnapshotFile(name, branch, newState);
+        return await this.eventCount(name, branch);
+    }
+    /**
+     * Replace the entire event log for a branch (used for rollback).
+     * Atomically writes a new events.jsonl file and rebuilds the snapshot.
+     */
+    async replaceEvents(name, branch, events) {
+        const lines = events.map(serializeEvent).join("\n") + (events.length > 0 ? "\n" : "");
+        await this.writeAtomic(this.eventsFile(name, branch), lines);
+        const meta = await this.loadMetadata(name);
+        const initial = {
+            name: meta.name,
+            description: meta.description,
+            createdAt: meta.createdAt,
+            updatedAt: meta.updatedAt,
+        };
+        const state = replay(events, initial);
+        await this.writeSnapshotFile(name, branch, state);
+    }
+    // --- StorageBackend interface ---
+    async initialize() {
+        await fs.mkdir(this.graphsDir(), { recursive: true });
+        // Auto-migrate any graphs from the legacy 0.2.x format on first start.
+        // Idempotent — re-running it skips already-converted branches. Failures
+        // are logged to stderr but do not block startup.
+        try {
+            await this.autoMigrateLegacyGraphs();
+        }
+        catch (err) {
+            console.error(`[backpack] auto-migration encountered an error: ${err.message}`);
+        }
+    }
+    /**
+     * Acquire an exclusive cross-process migration lock for a single graph
+     * by creating `.migration-lock` with O_EXCL. Two MCP instances starting
+     * simultaneously can't both convert the same legacy directory.
+     * Returns true on success, false if another process holds the lock.
+     */
+    async tryAcquireMigrationLock(name) {
+        const lockPath = path.join(this.graphDir(name), ".migration-lock");
+        try {
+            const fd = await fs.open(lockPath, "wx");
+            await fd.close();
+            return true;
+        }
+        catch (err) {
+            if (err.code === "EEXIST")
+                return false;
+            throw err;
+        }
+    }
+    async releaseMigrationLock(name) {
+        const lockPath = path.join(this.graphDir(name), ".migration-lock");
+        await fs.rm(lockPath).catch(() => { });
+    }
+    /**
+     * Detect and convert any 0.2.x format graphs to the new event-sourced
+     * layout. Runs once on initialize(); idempotent across restarts.
+     *
+     * Old layout:
+     *   graphs/<name>/meta.json + branches/<branch>.json
+     * New layout:
+     *   graphs/<name>/metadata.json + branches/<branch>/{events.jsonl, snapshot.json}
+     */
+    async autoMigrateLegacyGraphs() {
+        let entries;
+        try {
+            entries = await fs.readdir(this.graphsDir());
+        }
+        catch {
+            return;
+        }
+        for (const name of entries) {
+            // Skip anything that isn't a plausible graph directory name.
+            // Defends against hidden files (.DS_Store), traversal (.., .),
+            // and accidental symlinks.
+            if (name.startsWith("."))
+                continue;
+            if (name.includes("/") || name.includes("\\"))
+                continue;
+            try {
+                const graphDir = path.join(this.graphsDir(), name);
+                const stat = await fs.lstat(graphDir);
+                if (!stat.isDirectory() || stat.isSymbolicLink())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            // Acquire a per-graph lock to prevent two MCP instances from
+            // racing on the same legacy directory.
+            let locked = false;
+            try {
+                locked = await this.tryAcquireMigrationLock(name);
+            }
+            catch (err) {
+                console.error(`[backpack] failed to acquire migration lock for "${name}": ${err.message}`);
+                continue;
+            }
+            if (!locked)
+                continue;
+            try {
+                await this.migrateOneGraph(name);
+            }
+            catch (err) {
+                console.error(`[backpack] migration failed for "${name}": ${err.message}`);
+            }
+            finally {
+                await this.releaseMigrationLock(name);
+            }
+        }
+    }
+    async migrateOneGraph(name) {
+        const graphDir = this.graphDir(name);
+        const newMetaPath = this.metadataFile(name);
+        const oldMetaPath = path.join(graphDir, "meta.json");
+        const branchesDir = this.branchesDir(name);
+        let branchEntries;
+        try {
+            branchEntries = await fs.readdir(branchesDir);
+        }
+        catch {
+            return;
+        }
+        const legacyBranchFiles = branchEntries.filter((e) => e.endsWith(".json"));
+        // Nothing to do if there are no legacy files left to convert
+        if (legacyBranchFiles.length === 0)
+            return;
+        const hasNewMeta = await this.fileExists(newMetaPath);
+        // Determine activeBranch from old meta.json (default "main")
+        let activeBranch = DEFAULT_BRANCH;
+        if (await this.fileExists(oldMetaPath)) {
+            try {
+                const oldMeta = JSON.parse(await fs.readFile(oldMetaPath, "utf8"));
+                if (oldMeta && typeof oldMeta.activeBranch === "string") {
+                    activeBranch = oldMeta.activeBranch;
+                }
+            }
+            catch { }
+        }
+        // Synthesize metadata.json from a seed branch if missing
+        if (!hasNewMeta) {
+            const seedFile = legacyBranchFiles.find((f) => f === `${activeBranch}.json`) ||
+                legacyBranchFiles[0];
+            if (!seedFile)
+                return;
+            let seedData;
+            try {
+                seedData = JSON.parse(await fs.readFile(path.join(branchesDir, seedFile), "utf8"));
+            }
+            catch {
+                return;
+            }
+            const now = new Date().toISOString();
+            const meta = {
+                name: seedData?.metadata?.name || name,
+                description: seedData?.metadata?.description || "",
+                defaultBranch: activeBranch,
+                schemaVersion: SCHEMA_VERSION,
+                createdAt: seedData?.metadata?.createdAt || now,
+                updatedAt: now,
+            };
+            await this.writeMetadata(name, meta);
+        }
+        // Convert each legacy branch file
+        for (const branchFile of legacyBranchFiles) {
+            try {
+                await this.migrateOneBranchFile(name, branchFile);
+            }
+            catch {
+                // Leave the legacy file in place if conversion failed
+            }
+        }
+        // Remove old meta.json after successful conversion
+        if (await this.fileExists(oldMetaPath)) {
+            await fs.rm(oldMetaPath).catch(() => { });
+        }
+    }
+    async migrateOneBranchFile(name, branchFile) {
+        const branchName = branchFile.replace(/\.json$/, "");
+        const oldPath = path.join(this.branchesDir(name), branchFile);
+        const newDir = this.branchDir(name, branchName);
+        const eventsPath = this.eventsFile(name, branchName);
+        const snapshotPath = this.snapshotFile(name, branchName);
+        // If new layout already exists, drop the legacy file and stop
+        if (await this.fileExists(eventsPath)) {
+            await fs.rm(oldPath).catch(() => { });
+            return;
+        }
+        let data;
+        try {
+            data = JSON.parse(await fs.readFile(oldPath, "utf8"));
+        }
+        catch {
+            return;
+        }
+        if (!data || !Array.isArray(data.nodes) || !Array.isArray(data.edges)) {
+            return;
+        }
+        await fs.mkdir(newDir, { recursive: true });
+        const author = this.author ?? `migration@${process.env.HOSTNAME ?? "local"}`;
+        const ts = new Date().toISOString();
+        const events = [];
+        for (const node of data.nodes) {
+            events.push({
+                v: 1,
+                ts,
+                author,
+                op: "node.add",
+                node,
+            });
+        }
+        for (const edge of data.edges) {
+            events.push({
+                v: 1,
+                ts,
+                author,
+                op: "edge.add",
+                edge,
+            });
+        }
+        const lines = events.map((e) => JSON.stringify(e)).join("\n") + (events.length ? "\n" : "");
+        await this.writeAtomic(eventsPath, lines);
+        await this.writeAtomic(snapshotPath, JSON.stringify(data, null, 2));
+        // Remove the legacy monolithic file
+        await fs.rm(oldPath).catch(() => { });
+    }
+    async fileExists(p) {
+        try {
+            await fs.access(p);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async listOntologies() {
+        let entries;
+        try {
+            entries = await fs.readdir(this.graphsDir());
+        }
+        catch {
+            return [];
+        }
+        const summaries = [];
+        for (const entry of entries) {
+            try {
+                const meta = await this.loadMetadata(entry);
+                const state = await this.loadBranchSnapshot(entry, meta.defaultBranch);
+                const typeCounts = new Map();
+                for (const node of state.nodes) {
+                    typeCounts.set(node.type, (typeCounts.get(node.type) ?? 0) + 1);
+                }
+                // Use the directory name as the canonical identifier — that's
+                // what loadOntology takes. metadata.name can drift from the dir
+                // name through historical renames.
+                summaries.push({
+                    name: entry,
+                    description: meta.description,
+                    nodeCount: state.nodes.length,
+                    edgeCount: state.edges.length,
+                    nodeTypes: Array.from(typeCounts.entries())
+                        .map(([type, count]) => ({ type, count }))
+                        .sort((a, b) => b.count - a.count),
+                });
+            }
+            catch {
+                // Skip malformed graph directories
+            }
+        }
+        return summaries;
+    }
+    async loadOntology(name) {
+        const meta = await this.loadMetadata(name);
+        return this.loadBranchSnapshot(name, meta.defaultBranch);
+    }
+    /**
+     * Load the current event count for the default branch — used by
+     * Backpack as the optimistic-concurrency version token.
+     */
+    async getCurrentVersion(name) {
+        const meta = await this.loadMetadata(name);
+        return this.eventCount(name, meta.defaultBranch);
+    }
+    async saveOntology(name, data, expectedVersion) {
+        const meta = await this.loadMetadata(name);
+        const before = await this.loadBranchSnapshot(name, meta.defaultBranch);
+        const events = diffToEvents(before, data, this.author);
+        if (events.length === 0)
+            return;
+        await this.appendEvents(name, meta.defaultBranch, events, expectedVersion);
+        // Heartbeat: every successful write touches the lock file
+        await this.touchLock(name).catch(() => { });
+        if (data.metadata.name !== meta.name ||
+            data.metadata.description !== meta.description) {
+            meta.name = data.metadata.name;
+            meta.description = data.metadata.description;
+            meta.updatedAt = new Date().toISOString();
+            await this.writeMetadata(name, meta);
+        }
+    }
+    // --- Lockfile heartbeat ---
+    /**
+     * Touch the lock file with the current author + timestamp. Called
+     * automatically on every successful write. Safe to call concurrently;
+     * the file is overwritten atomically.
+     */
+    async touchLock(name) {
+        const lock = {
+            author: this.author ?? "unknown",
+            lastActivity: new Date().toISOString(),
+            hostname: typeof process !== "undefined" ? process.env.HOSTNAME : undefined,
+            pid: typeof process !== "undefined" ? process.pid : undefined,
+        };
+        await this.writeAtomic(this.lockFile(name), JSON.stringify(lock));
+    }
+    /**
+     * Read the lock file. Returns null if no lock exists, or if the lock
+     * is stale (older than LOCK_FRESH_MS).
+     */
+    async readLock(name) {
+        let raw;
+        try {
+            raw = await fs.readFile(this.lockFile(name), "utf8");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+        let lock;
+        try {
+            lock = JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+        const age = Date.now() - new Date(lock.lastActivity).getTime();
+        if (Number.isNaN(age) || age > LOCK_FRESH_MS)
+            return null;
+        return lock;
+    }
+    async createOntology(name, description) {
+        if (await this.ontologyExists(name)) {
+            throw new Error(`Learning graph "${name}" already exists`);
+        }
+        await fs.mkdir(this.branchDir(name, DEFAULT_BRANCH), { recursive: true });
+        const now = new Date().toISOString();
+        const meta = {
+            name,
+            description,
+            defaultBranch: DEFAULT_BRANCH,
+            schemaVersion: SCHEMA_VERSION,
+            createdAt: now,
+            updatedAt: now,
+        };
+        await this.writeMetadata(name, meta);
+        const initial = emptyGraphData(name, description);
+        await this.writeAtomic(this.eventsFile(name, DEFAULT_BRANCH), "");
+        await this.writeSnapshotFile(name, DEFAULT_BRANCH, initial);
+        return initial;
+    }
+    async deleteOntology(name) {
+        if (!(await this.ontologyExists(name))) {
+            throw new Error(`Learning graph "${name}" not found`);
+        }
+        await fs.rm(this.graphDir(name), { recursive: true, force: true });
+    }
+    async renameOntology(oldName, newName) {
+        if (await this.ontologyExists(newName)) {
+            throw new Error(`Learning graph "${newName}" already exists`);
+        }
+        await fs.rename(this.graphDir(oldName), this.graphDir(newName));
+        const meta = await this.loadMetadata(newName);
+        meta.name = newName;
+        meta.updatedAt = new Date().toISOString();
+        await this.writeMetadata(newName, meta);
+    }
+    async ontologyExists(name) {
+        try {
+            await fs.access(this.metadataFile(name));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // --- Branches ---
+    async listBranches(name) {
+        const meta = await this.loadMetadata(name);
+        let entries;
+        try {
+            entries = await fs.readdir(this.branchesDir(name));
+        }
+        catch {
+            return [];
+        }
+        const branches = [];
+        for (const entry of entries) {
+            try {
+                const state = await this.loadBranchSnapshot(name, entry);
+                branches.push({
+                    name: entry,
+                    nodeCount: state.nodes.length,
+                    edgeCount: state.edges.length,
+                    active: entry === meta.defaultBranch,
+                });
+            }
+            catch { }
+        }
+        return branches;
+    }
+    async createBranch(name, branchName, fromBranch) {
+        const meta = await this.loadMetadata(name);
+        const source = fromBranch ?? meta.defaultBranch;
+        const targetDir = this.branchDir(name, branchName);
+        try {
+            await fs.access(targetDir);
+            throw new Error(`Branch "${branchName}" already exists`);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+        }
+        await fs.mkdir(targetDir, { recursive: true });
+        const sourceEvents = this.eventsFile(name, source);
+        const targetEvents = this.eventsFile(name, branchName);
+        try {
+            await fs.copyFile(sourceEvents, targetEvents);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+            await this.writeAtomic(targetEvents, "");
+        }
+        const sourceSnap = this.snapshotFile(name, source);
+        const targetSnap = this.snapshotFile(name, branchName);
+        try {
+            await fs.copyFile(sourceSnap, targetSnap);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err;
+            await this.rebuildSnapshot(name, branchName);
+        }
+    }
+    async switchBranch(name, branchName) {
+        const branchDir = this.branchDir(name, branchName);
+        try {
+            await fs.access(branchDir);
+        }
+        catch {
+            throw new Error(`Branch "${branchName}" does not exist`);
+        }
+        const meta = await this.loadMetadata(name);
+        meta.defaultBranch = branchName;
+        meta.updatedAt = new Date().toISOString();
+        await this.writeMetadata(name, meta);
+    }
+    async deleteBranch(name, branchName) {
+        const meta = await this.loadMetadata(name);
+        if (branchName === meta.defaultBranch) {
+            throw new Error(`Cannot delete the active branch "${branchName}"`);
+        }
+        if (branchName === DEFAULT_BRANCH) {
+            throw new Error(`Cannot delete the "${DEFAULT_BRANCH}" branch`);
+        }
+        await fs.rm(this.branchDir(name, branchName), { recursive: true, force: true });
+    }
+    async loadBranch(name, branchName) {
+        return this.loadBranchSnapshot(name, branchName);
+    }
+    // --- Snapshots (labeled events) ---
+    async createSnapshot(name, label) {
+        const meta = await this.loadMetadata(name);
+        const event = makeSnapshotLabelEvent(label, this.author);
+        await this.appendEvents(name, meta.defaultBranch, [event]);
+        return await this.eventCount(name, meta.defaultBranch);
+    }
+    async listSnapshots(name) {
+        const meta = await this.loadMetadata(name);
+        const events = await this.loadEvents(name, meta.defaultBranch);
+        const snapshots = [];
+        let runningState = emptyGraphData(meta.name, meta.description);
+        for (let i = 0; i < events.length; i++) {
+            runningState = applyEvents(runningState, [events[i]]);
+            if (events[i].op === "snapshot.label") {
+                const snapEvent = events[i];
+                snapshots.push({
+                    version: i + 1,
+                    timestamp: snapEvent.ts,
+                    nodeCount: runningState.nodes.length,
+                    edgeCount: runningState.edges.length,
+                    label: snapEvent.label,
+                });
+            }
+        }
+        snapshots.reverse();
+        return snapshots;
+    }
+    /**
+     * Load the materialized state at a specific snapshot version. The
+     * version is the position in the event log of a snapshot.label event,
+     * matching the value returned by createSnapshot and listSnapshots.
+     */
+    async loadSnapshot(name, version) {
+        const meta = await this.loadMetadata(name);
+        const events = await this.loadEvents(name, meta.defaultBranch);
+        if (version < 1 || version > events.length) {
+            throw new Error(`Snapshot version ${version} not found`);
+        }
+        const initial = {
+            name: meta.name,
+            description: meta.description,
+            createdAt: meta.createdAt,
+            updatedAt: meta.updatedAt,
+        };
+        return replay(events.slice(0, version), initial);
+    }
+    async rollback(name, version) {
+        const meta = await this.loadMetadata(name);
+        const events = await this.loadEvents(name, meta.defaultBranch);
+        if (version < 1 || version > events.length) {
+            throw new Error(`Snapshot version ${version} not found`);
+        }
+        const truncated = events.slice(0, version);
+        await this.replaceEvents(name, meta.defaultBranch, truncated);
+    }
+    async getSnapshotLimit(_name) {
+        return Number.MAX_SAFE_INTEGER;
+    }
+    // --- Snippets (orthogonal to events) ---
+    async saveSnippet(graphName, snippet) {
+        const id = snippet.label
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, "-")
+            .replace(/^-|-$/g, "")
+            .substring(0, 50) || "snippet";
+        const data = await this.loadOntology(graphName);
+        const meta = await this.loadMetadata(graphName);
+        const nodeSet = new Set(snippet.nodeIds);
+        let resolvedEdgeIds = snippet.edgeIds;
+        if (!resolvedEdgeIds || resolvedEdgeIds.length === 0) {
+            resolvedEdgeIds = data.edges
+                .filter((e) => nodeSet.has(e.sourceId) && nodeSet.has(e.targetId))
+                .map((e) => e.id);
+        }
+        const edgeSet = new Set(resolvedEdgeIds);
+        const snippetData = {
+            id,
+            label: snippet.label,
+            description: snippet.description ?? "",
+            parentGraph: graphName,
+            parentBranch: meta.defaultBranch,
+            nodeIds: snippet.nodeIds,
+            edgeIds: resolvedEdgeIds,
+            nodes: data.nodes.filter((n) => nodeSet.has(n.id)),
+            edges: data.edges.filter((e) => edgeSet.has(e.id)),
+            nodeCount: snippet.nodeIds.length,
+            edgeCount: resolvedEdgeIds.length,
+            createdAt: new Date().toISOString(),
+        };
+        await fs.mkdir(this.snippetsDir(graphName), { recursive: true });
+        await this.writeAtomic(this.snippetFile(graphName, id), JSON.stringify(snippetData, null, 2));
+        return id;
+    }
+    async listSnippets(graphName) {
+        let entries;
+        try {
+            entries = await fs.readdir(this.snippetsDir(graphName));
+        }
+        catch {
+            return [];
+        }
+        const snippets = [];
+        for (const entry of entries.sort()) {
+            if (!entry.endsWith(".json"))
+                continue;
+            try {
+                const raw = await fs.readFile(path.join(this.snippetsDir(graphName), entry), "utf8");
+                const data = JSON.parse(raw);
+                snippets.push({
+                    id: data.id,
+                    label: data.label,
+                    description: data.description ?? "",
+                    nodeCount: data.nodeCount ?? data.nodes?.length ?? 0,
+                    edgeCount: data.edgeCount ?? data.edges?.length ?? 0,
+                    createdAt: data.createdAt,
+                });
+            }
+            catch { }
+        }
+        return snippets;
+    }
+    async loadSnippet(graphName, snippetId) {
+        const raw = await fs.readFile(this.snippetFile(graphName, snippetId), "utf8");
+        return JSON.parse(raw);
+    }
+    async deleteSnippet(graphName, snippetId) {
+        await fs.rm(this.snippetFile(graphName, snippetId));
+    }
+    // --- Terms (carry-forward from old backend, used by intelligence tools) ---
+    async loadTerms(name) {
+        try {
+            return await fs.readFile(this.termsFile(name), "utf8");
+        }
+        catch {
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=event-sourced-backend.js.map