opentology 0.2.8 → 0.3.1

package/dist/commands/context.js

@@ -217,6 +217,20 @@ export function registerContext(program) {
             }
             settings.hooks = hooks;
             writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+            // Ensure .opentology/snapshots/ is in .gitignore
+            const gitignorePath = join(process.cwd(), '.gitignore');
+            const snapshotIgnore = '.opentology/snapshots/';
+            if (existsSync(gitignorePath)) {
+                const gitignoreContent = readFileSync(gitignorePath, 'utf-8');
+                if (!gitignoreContent.includes(snapshotIgnore)) {
+                    writeFileSync(gitignorePath, gitignoreContent.trimEnd() + '\n' + snapshotIgnore + '\n', 'utf-8');
+                    console.log(pc.green('  Added .opentology/snapshots/ to .gitignore'));
+                }
+            }
+            else {
+                writeFileSync(gitignorePath, snapshotIgnore + '\n', 'utf-8');
+                console.log(pc.green('  Created .gitignore with .opentology/snapshots/'));
+            }
             console.log('');
             console.log(pc.dim('Consider adding .opentology/hooks/ to version control so team members share the hook.'));
         }

package/dist/commands/diff.js

@@ -27,7 +27,13 @@ export function registerDiff(program) {
             for (const triple of result.removed) {
                 console.log(pc.red(`- ${triple}`));
             }
-            console.log(`\n${result.added.length} added, ${result.removed.length} removed, ${result.unchanged} unchanged`);
+            const addedLabel = result.truncated && result.addedCount > result.added.length
+                ? `${result.added.length}/${result.addedCount} added (truncated)`
+                : `${result.addedCount} added`;
+            const removedLabel = result.truncated && result.removedCount > result.removed.length
+                ? `${result.removed.length}/${result.removedCount} removed (truncated)`
+                : `${result.removedCount} removed`;
+            console.log(`\n${addedLabel}, ${removedLabel}, ${result.unchanged} unchanged`);
         }
         catch (err) {
             const message = err.message;

package/dist/commands/drop.js

@@ -1,6 +1,7 @@
 import pc from 'picocolors';
 import { loadConfig, resolveGraphUri, saveConfig } from '../lib/config.js';
 import { createReadyAdapter } from '../lib/store-factory.js';
+import { snapshotGraph } from '../lib/snapshot.js';
 export function registerDrop(program) {
     program
         .command('drop')
@@ -23,6 +24,7 @@ export function registerDrop(program) {
         }
         try {
             const adapter = await createReadyAdapter(config);
+            await snapshotGraph(adapter, config, graphUri);
             await adapter.dropGraph(graphUri);
             // In embedded mode, clear tracked files for this graph
             if (config.mode === 'embedded') {

package/dist/commands/rollback.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerRollback(program: Command): void;

package/dist/commands/rollback.js

@@ -0,0 +1,75 @@
+import pc from 'picocolors';
+import { loadConfig, resolveGraphUri } from '../lib/config.js';
+import { createReadyAdapter } from '../lib/store-factory.js';
+import { listSnapshots, restoreSnapshot } from '../lib/snapshot.js';
+import { createInterface } from 'node:readline';
+function ask(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim().toLowerCase());
+        });
+    });
+}
+export function registerRollback(program) {
+    program
+        .command('rollback')
+        .description('List or restore graph snapshots')
+        .option('--list', 'List available snapshots')
+        .option('--to <timestamp>', 'Restore to a specific snapshot timestamp')
+        .option('--graph <name>', 'Target a specific named graph')
+        .action(async (opts) => {
+        let config;
+        try {
+            config = loadConfig();
+        }
+        catch (err) {
+            console.error(`Error: ${err.message}`);
+            process.exit(1);
+        }
+        const graphUri = opts.graph ? resolveGraphUri(config, opts.graph) : config.graphUri;
+        if (opts.list) {
+            const snapshots = listSnapshots(graphUri);
+            if (snapshots.length === 0) {
+                console.log(pc.dim('No snapshots found for this graph.'));
+                return;
+            }
+            console.log(pc.bold(`Snapshots for ${graphUri}:`));
+            console.log('');
+            for (const s of snapshots) {
+                const sizeKb = (s.sizeBytes / 1024).toFixed(1);
+                const label = s.isPreRollback ? pc.yellow(' (pre-rollback)') : '';
+                console.log(`  ${pc.dim(s.timestamp)}  ${sizeKb} KB${label}`);
+            }
+            return;
+        }
+        try {
+            const adapter = await createReadyAdapter(config);
+            if (opts.to) {
+                await restoreSnapshot(adapter, config, graphUri, opts.to);
+                console.log(pc.green(`Restored graph to snapshot: ${opts.to}`));
+                return;
+            }
+            // No flags: restore latest snapshot with confirmation
+            const snapshots = listSnapshots(graphUri).filter((s) => !s.isPreRollback);
+            if (snapshots.length === 0) {
+                console.log(pc.dim('No snapshots found for this graph.'));
+                return;
+            }
+            const latest = snapshots[0];
+            const answer = await ask(`Restore to latest snapshot ${pc.bold(latest.timestamp)}? [y/N] `);
+            if (answer === 'y' || answer === 'yes') {
+                await restoreSnapshot(adapter, config, graphUri, latest.timestamp);
+                console.log(pc.green(`Restored graph to snapshot: ${latest.timestamp}`));
+            }
+            else {
+                console.log(pc.dim('Rollback cancelled.'));
+            }
+        }
+        catch (err) {
+            console.error(pc.red(`Error: ${err.message}`));
+            process.exit(1);
+        }
+    });
+}

package/dist/index.js

@@ -17,6 +17,7 @@ import { registerPrefix } from './commands/prefix.js';
 import { registerContext } from './commands/context.js';
 import { registerViz } from './commands/viz.js';
 import { registerDoctor } from './commands/doctor.js';
+import { registerRollback } from './commands/rollback.js';
 const program = new Command();
 program
     .name('opentology')
@@ -39,4 +40,5 @@ registerPrefix(program);
 registerContext(program);
 registerViz(program);
 registerDoctor(program);
+registerRollback(program);
 program.parse(process.argv);

package/dist/lib/deep-scan-triples.js

@@ -75,11 +75,11 @@ export function generateSymbolTriples(result) {
         }
     }
     for (const call of result.methodCalls) {
-        // Method calls reference by class.method pattern — generate a simple triple
-        triples.push(`<urn:call:${encodeSegment(call.caller)}> <${OTX}calls> <urn:call:${encodeSegment(call.callee)}> .`);
-        // Store caller/callee names for queryability
-        triples.push(`<urn:call:${encodeSegment(call.caller)}> <${OTX}title> "${esc(call.caller)}" .`);
-        triples.push(`<urn:call:${encodeSegment(call.callee)}> <${OTX}title> "${esc(call.callee)}" .`);
+        const callUri = `urn:call:${encodeSegment(call.caller)}--${encodeSegment(call.callee)}`;
+        triples.push(`<${callUri}> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <${OTX}MethodCall> .`);
+        triples.push(`<${callUri}> <${OTX}callerSymbol> "${esc(call.caller)}" .`);
+        triples.push(`<${callUri}> <${OTX}calleeSymbol> "${esc(call.callee)}" .`);
+        triples.push(`<${callUri}> <${OTX}title> "${esc(call.caller)} -> ${esc(call.callee)}" .`);
     }
     return triples;
 }
@@ -96,6 +96,8 @@ export async function deleteExistingSymbols(adapter, graphUri, modulePaths) {
         const modUri = moduleUri(modPath);
         await adapter.sparqlUpdate(`DELETE WHERE { GRAPH <${graphUri}> { ?s <${OTX}definedIn> <${modUri}> . ?s ?p ?o } }`);
     }
+    // Clean up MethodCall triples (no definedIn link, so delete all and re-insert)
+    await adapter.sparqlUpdate(`DELETE WHERE { GRAPH <${graphUri}> { ?s a <${OTX}MethodCall> . ?s ?p ?o } }`);
 }
 export async function pushSymbolTriples(adapter, graphUri, result) {
     // Collect all module paths for scoped delete

package/dist/lib/embedded-adapter.d.ts

@@ -18,10 +18,13 @@ export declare class EmbeddedAdapter implements StoreAdapter {
         turtle?: string;
         where?: string;
     }): Promise<void>;
-    diffGraph(graphUri: string, localTurtle: string): Promise<{
+    diffGraph(graphUri: string, localTurtle: string, limit?: number): Promise<{
         added: string[];
         removed: string[];
         unchanged: number;
+        addedCount: number;
+        removedCount: number;
+        truncated: boolean;
     }>;
     getSchemaOverview(graphUri: string): Promise<{
         prefixes: Record<string, string>;

package/dist/lib/embedded-adapter.js

@@ -148,7 +148,7 @@ export class EmbeddedAdapter {
             throw new Error('deleteTriples: either options.turtle or options.where must be provided');
         }
     }
-    async diffGraph(graphUri, localTurtle) {
+    async diffGraph(graphUri, localTurtle, limit = 50) {
         const localQuads = await parseTurtle(localTurtle);
         const localSet = new Set(localQuads.map((q) => `${termToSparql(q.subject)} ${termToSparql(q.predicate)} ${termToSparql(q.object)}`));
         // Get remote quads from the store
@@ -158,10 +158,18 @@ export class EmbeddedAdapter {
             const n3q = wasmQuadToN3Quad(q);
             remoteSet.add(`${termToSparql(n3q.subject)} ${termToSparql(n3q.predicate)} ${termToSparql(n3q.object)}`);
         }
-        const added = [...localSet].filter((t) => !remoteSet.has(t));
-        const removed = [...remoteSet].filter((t) => !localSet.has(t));
+        const allAdded = [...localSet].filter((t) => !remoteSet.has(t));
+        const allRemoved = [...remoteSet].filter((t) => !localSet.has(t));
         const unchanged = [...localSet].filter((t) => remoteSet.has(t)).length;
-        return { added, removed, unchanged };
+        const truncated = allAdded.length > limit || allRemoved.length > limit;
+        return {
+            added: allAdded.slice(0, limit),
+            removed: allRemoved.slice(0, limit),
+            unchanged,
+            addedCount: allAdded.length,
+            removedCount: allRemoved.length,
+            truncated,
+        };
     }
     async getSchemaOverview(graphUri) {
         const tripleCount = await this.getGraphTripleCount(graphUri);

package/dist/lib/http-adapter.d.ts

@@ -14,10 +14,13 @@ export declare class HttpAdapter implements StoreAdapter {
         turtle?: string;
         where?: string;
     }): Promise<void>;
-    diffGraph(graphUri: string, localTurtle: string): Promise<{
+    diffGraph(graphUri: string, localTurtle: string, limit?: number): Promise<{
         added: string[];
         removed: string[];
         unchanged: number;
+        addedCount: number;
+        removedCount: number;
+        truncated: boolean;
     }>;
     getSchemaOverview(graphUri: string): Promise<{
         prefixes: Record<string, string>;

package/dist/lib/http-adapter.js

@@ -115,7 +115,7 @@ export class HttpAdapter {
             throw new Error('deleteTriples: either options.turtle or options.where must be provided');
         }
     }
-    async diffGraph(graphUri, localTurtle) {
+    async diffGraph(graphUri, localTurtle, limit = 50) {
         const localQuads = await parseTurtle(localTurtle);
         const localSet = new Set(localQuads.map((q) => `${termToSparql(q.subject)} ${termToSparql(q.predicate)} ${termToSparql(q.object)}`));
         // Fetch remote quads via CONSTRUCT
@@ -125,10 +125,18 @@ export class HttpAdapter {
             ? await parseTurtle(remoteTurtle)
             : [];
         const remoteSet = new Set(remoteQuads.map((q) => `${termToSparql(q.subject)} ${termToSparql(q.predicate)} ${termToSparql(q.object)}`));
-        const added = [...localSet].filter((t) => !remoteSet.has(t));
-        const removed = [...remoteSet].filter((t) => !localSet.has(t));
+        const allAdded = [...localSet].filter((t) => !remoteSet.has(t));
+        const allRemoved = [...remoteSet].filter((t) => !localSet.has(t));
         const unchanged = [...localSet].filter((t) => remoteSet.has(t)).length;
-        return { added, removed, unchanged };
+        const truncated = allAdded.length > limit || allRemoved.length > limit;
+        return {
+            added: allAdded.slice(0, limit),
+            removed: allRemoved.slice(0, limit),
+            unchanged,
+            addedCount: allAdded.length,
+            removedCount: allRemoved.length,
+            truncated,
+        };
     }
     async getSchemaOverview(graphUri) {
         const tripleCount = await this.getGraphTripleCount(graphUri);

package/dist/lib/snapshot.d.ts

@@ -0,0 +1,40 @@
+import type { StoreAdapter } from './store-adapter.js';
+import type { OpenTologyConfig } from './config.js';
+/**
+ * Derive a filesystem-safe slug from a graph URI.
+ * Reuses the same pattern as persistGraph().
+ */
+export declare function graphSlug(graphUri: string): string;
+/**
+ * Generate an ISO timestamp suitable for filenames.
+ * Format: 2026-04-05T14-30-22-123Z (colons replaced with dashes, ms included).
+ */
+export declare function toFilenameTimestamp(date?: Date): string;
+/**
+ * Snapshot a named graph before a destructive operation.
+ * No-op if not embedded mode or if the graph is empty.
+ * Automatically prunes old snapshots after saving.
+ */
+export declare function snapshotGraph(adapter: StoreAdapter, config: OpenTologyConfig, graphUri: string, retention?: number): Promise<string | null>;
+export interface SnapshotInfo {
+    timestamp: string;
+    path: string;
+    sizeBytes: number;
+    isPreRollback: boolean;
+}
+/**
+ * List snapshots for a graph, sorted by timestamp descending (newest first).
+ */
+export declare function listSnapshots(graphUri: string): SnapshotInfo[];
+/**
+ * Restore a graph to a specific snapshot.
+ * 1. Saves current state as {timestamp}_pre-rollback.ttl (snapshot-before-rollback)
+ * 2. Drops the graph and loads the snapshot
+ * 3. Persists the restored state to .opentology/data/
+ */
+export declare function restoreSnapshot(adapter: StoreAdapter, config: OpenTologyConfig, graphUri: string, timestamp: string): Promise<void>;
+/**
+ * Prune old snapshots, keeping only the most recent `keep` count.
+ * Pre-rollback snapshots are pruned separately (keep 2).
+ */
+export declare function pruneSnapshots(graphUri: string, keep?: number): Promise<number>;

package/dist/lib/snapshot.js

@@ -0,0 +1,136 @@
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync, unlinkSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { persistGraph } from '../mcp/server.js';
+const DEFAULT_RETENTION = 5;
+/**
+ * Derive a filesystem-safe slug from a graph URI.
+ * Reuses the same pattern as persistGraph().
+ */
+export function graphSlug(graphUri) {
+    return graphUri.replace(/[^a-zA-Z0-9-]/g, '_').replace(/_+/g, '_');
+}
+/**
+ * Generate an ISO timestamp suitable for filenames.
+ * Format: 2026-04-05T14-30-22-123Z (colons replaced with dashes, ms included).
+ */
+export function toFilenameTimestamp(date = new Date()) {
+    return date.toISOString().replace(/:/g, '-').replace(/\./g, '-');
+}
+/**
+ * Parse a filename timestamp back to a Date.
+ */
+function parseFilenameTimestamp(filename) {
+    // Remove .ttl suffix and _pre-rollback suffix
+    const base = filename.replace(/\.ttl$/, '').replace(/_pre-rollback$/, '');
+    // Reverse the filename encoding: dashes back to colons/dots
+    // Format: 2026-04-05T14-30-22-123Z → 2026-04-05T14:30:22.123Z
+    const parts = base.match(/^(\d{4}-\d{2}-\d{2}T)(\d{2})-(\d{2})-(\d{2})-(\d{3}Z)$/);
+    if (!parts)
+        return null;
+    const iso = `${parts[1]}${parts[2]}:${parts[3]}:${parts[4]}.${parts[5]}`;
+    const d = new Date(iso);
+    return isNaN(d.getTime()) ? null : d;
+}
+function snapshotDir(graphUri) {
+    return join(process.cwd(), '.opentology', 'snapshots', graphSlug(graphUri));
+}
+/**
+ * Snapshot a named graph before a destructive operation.
+ * No-op if not embedded mode or if the graph is empty.
+ * Automatically prunes old snapshots after saving.
+ */
+export async function snapshotGraph(adapter, config, graphUri, retention = DEFAULT_RETENTION) {
+    if (config.mode !== 'embedded')
+        return null;
+    const exported = await adapter.exportGraph(graphUri);
+    if (!exported.trim())
+        return null;
+    const dir = snapshotDir(graphUri);
+    mkdirSync(dir, { recursive: true });
+    const timestamp = toFilenameTimestamp();
+    const filename = `${timestamp}.ttl`;
+    const filePath = join(dir, filename);
+    writeFileSync(filePath, exported, 'utf-8');
+    // Verify the file was written
+    if (!existsSync(filePath)) {
+        throw new Error(`Snapshot write failed: ${filePath}`);
+    }
+    // Prune old snapshots (create → verify → prune order)
+    await pruneSnapshots(graphUri, retention);
+    return filePath;
+}
+/**
+ * List snapshots for a graph, sorted by timestamp descending (newest first).
+ */
+export function listSnapshots(graphUri) {
+    const dir = snapshotDir(graphUri);
+    if (!existsSync(dir))
+        return [];
+    const files = readdirSync(dir).filter((f) => f.endsWith('.ttl'));
+    return files
+        .map((f) => {
+        const fullPath = join(dir, f);
+        const stat = statSync(fullPath);
+        return {
+            timestamp: f.replace(/\.ttl$/, ''),
+            path: fullPath,
+            sizeBytes: stat.size,
+            isPreRollback: f.includes('_pre-rollback'),
+        };
+    })
+        .sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+}
+/**
+ * Restore a graph to a specific snapshot.
+ * 1. Saves current state as {timestamp}_pre-rollback.ttl (snapshot-before-rollback)
+ * 2. Drops the graph and loads the snapshot
+ * 3. Persists the restored state to .opentology/data/
+ */
+export async function restoreSnapshot(adapter, config, graphUri, timestamp) {
+    const dir = snapshotDir(graphUri);
+    const snapshotPath = join(dir, `${timestamp}.ttl`);
+    if (!existsSync(snapshotPath)) {
+        throw new Error(`Snapshot not found: ${timestamp}`);
+    }
+    // Step 1: Snapshot-before-rollback — save current state
+    const currentExport = await adapter.exportGraph(graphUri);
+    if (currentExport.trim()) {
+        mkdirSync(dir, { recursive: true });
+        const preRollbackTimestamp = toFilenameTimestamp();
+        const preRollbackPath = join(dir, `${preRollbackTimestamp}_pre-rollback.ttl`);
+        writeFileSync(preRollbackPath, currentExport, 'utf-8');
+    }
+    // Step 2: Drop and restore
+    const snapshotTurtle = readFileSync(snapshotPath, 'utf-8');
+    await adapter.dropGraph(graphUri);
+    await adapter.insertTurtle(graphUri, snapshotTurtle);
+    // Step 3: Persist restored state
+    await persistGraph(adapter, config, graphUri);
+}
+/**
+ * Prune old snapshots, keeping only the most recent `keep` count.
+ * Pre-rollback snapshots are pruned separately (keep 2).
+ */
+export async function pruneSnapshots(graphUri, keep = DEFAULT_RETENTION) {
+    const dir = snapshotDir(graphUri);
+    if (!existsSync(dir))
+        return 0;
+    const files = readdirSync(dir).filter((f) => f.endsWith('.ttl'));
+    // Separate regular snapshots and pre-rollback snapshots
+    const regular = files.filter((f) => !f.includes('_pre-rollback')).sort();
+    const preRollback = files.filter((f) => f.includes('_pre-rollback')).sort();
+    let deleted = 0;
+    // Prune regular snapshots
+    while (regular.length > keep) {
+        const oldest = regular.shift();
+        unlinkSync(join(dir, oldest));
+        deleted++;
+    }
+    // Prune pre-rollback snapshots (keep max 2)
+    while (preRollback.length > 2) {
+        const oldest = preRollback.shift();
+        unlinkSync(join(dir, oldest));
+        deleted++;
+    }
+    return deleted;
+}

package/dist/lib/store-adapter.d.ts

@@ -34,10 +34,13 @@ export interface StoreAdapter {
     }): Promise<void>;
     getGraphTripleCount(graphUri: string): Promise<number>;
     exportGraph(graphUri: string): Promise<string>;
-    diffGraph(graphUri: string, localTurtle: string): Promise<{
+    diffGraph(graphUri: string, localTurtle: string, limit?: number): Promise<{
         added: string[];
         removed: string[];
         unchanged: number;
+        addedCount: number;
+        removedCount: number;
+        truncated: boolean;
     }>;
     getSchemaOverview(graphUri: string): Promise<{
         prefixes: Record<string, string>;

package/dist/mcp/server.js

@@ -6,6 +6,7 @@ import { deepScan } from '../lib/deep-scanner.js';
 import { pushSymbolTriples } from '../lib/deep-scan-triples.js';
 import { createReadyAdapter } from '../lib/store-factory.js';
 import { normalizeModuleUri } from '../lib/module-uri.js';
+import { snapshotGraph, listSnapshots, restoreSnapshot } from '../lib/snapshot.js';
 import { hasGraphScope, autoScopeQuery, getInferenceGraphUri } from '../lib/sparql-utils.js';
 import { validateTurtle } from '../lib/validator.js';
 import { discoverShapes, validateWithShacl, hasShapes } from '../lib/shacl.js';
@@ -120,6 +121,7 @@ async function handlePush(args) {
     });
     const adapter = await createReadyAdapter(config);
     if (replace) {
+        await snapshotGraph(adapter, config, graphUri);
         await adapter.dropGraph(graphUri);
     }
     await adapter.insertTurtle(graphUri, content);
@@ -220,6 +222,7 @@ async function handleDrop(args) {
         graph: args.graph,
     });
     const adapter = await createReadyAdapter(config);
+    await snapshotGraph(adapter, config, graphUri);
     await adapter.dropGraph(graphUri);
     await persistGraph(adapter, config, graphUri);
     return { success: true, graphUri };
@@ -235,21 +238,44 @@ async function handleDelete(args) {
         graph: args.graph,
     });
     const adapter = await createReadyAdapter(config);
+    await snapshotGraph(adapter, config, graphUri);
     await adapter.deleteTriples(graphUri, { turtle: content, where });
     await persistGraph(adapter, config, graphUri);
     return { success: true };
 }
+async function handleRollback(args) {
+    const action = args.action;
+    const { config, graphUri } = resolveConfig({
+        graphUri: args.graphUri,
+        graph: args.graph,
+    });
+    if (action === 'list') {
+        const snapshots = listSnapshots(graphUri);
+        return { graphUri, snapshots };
+    }
+    if (action === 'restore') {
+        const to = args.to;
+        if (!to) {
+            throw new Error('timestamp (to) is required for restore action');
+        }
+        const adapter = await createReadyAdapter(config);
+        await restoreSnapshot(adapter, config, graphUri, to);
+        return { success: true, graphUri, restoredTo: to };
+    }
+    throw new Error(`Unknown rollback action: ${action}. Use 'list' or 'restore'.`);
+}
 async function handleDiff(args) {
     const content = args.content;
     if (!content) {
         throw new Error('content (Turtle) is required');
     }
+    const limit = typeof args.limit === 'number' ? args.limit : 50;
     const { config, graphUri } = resolveConfig({
         graphUri: args.graphUri,
         graph: args.graph,
     });
     const adapter = await createReadyAdapter(config);
-    return await adapter.diffGraph(graphUri, content);
+    return await adapter.diffGraph(graphUri, content, limit);
 }
 async function handleGraphList(_args) {
     const config = loadConfig();
@@ -310,6 +336,7 @@ async function handleGraphDrop(args) {
     const config = loadConfig();
     const graphUri = resolveGraphUri(config, name);
     const adapter = await createReadyAdapter(config);
+    await snapshotGraph(adapter, config, graphUri);
     await adapter.dropGraph(graphUri);
     await persistGraph(adapter, config, graphUri);
     const graphs = config.graphs ?? {};
@@ -326,10 +353,13 @@ async function handleInfer(args) {
     });
     const adapter = await createReadyAdapter(config);
     if (clear) {
+        await snapshotGraph(adapter, config, graphUri);
         await clearInferences(adapter, graphUri);
+        await persistGraph(adapter, config, graphUri);
         return { success: true, cleared: true };
     }
     const result = await materializeInferences(adapter, graphUri);
+    await persistGraph(adapter, config, graphUri);
     return result;
 }
 async function handleContextScan(args) {
@@ -362,7 +392,7 @@ async function handleContextScan(args) {
             pushStats,
             _experimental: true,
             _hint: pushStats
-                ? `Symbol triples pushed: ${pushStats.triplesInserted} triples in ${pushStats.batchCount} batches. Query with: SELECT ?c WHERE { ?c a otx:Class ; otx:definedIn <urn:module:...> }`
+                ? `Symbol triples pushed: ${pushStats.triplesInserted} triples in ${pushStats.batchCount} batches. Query examples:\n- Classes: SELECT ?c ?name WHERE { ?c a otx:Class ; otx:title ?name }\n- Functions in a module: SELECT ?f ?name WHERE { ?f a otx:Function ; otx:title ?name ; otx:definedIn <urn:module:src/mcp/server> }\n- Call graph: SELECT ?caller ?callee WHERE { ?s a otx:MethodCall ; otx:callerSymbol ?caller ; otx:calleeSymbol ?callee }`
                 : 'Deep scan completed but triple push failed. Use push manually with the generated triples.',
         };
     }
@@ -376,6 +406,8 @@ async function handleContextScan(args) {
         const adapter = await createReadyAdapter(config);
         if (snapshot.dependencyGraph && snapshot.dependencyGraph.modules.length > 0) {
             const dg = snapshot.dependencyGraph;
+            // Snapshot before destructive scan
+            await snapshotGraph(adapter, config, contextUri);
             // Scoped delete: clear stale module triples before re-insert
             await adapter.sparqlUpdate(`DELETE WHERE { GRAPH <${contextUri}> { ?m a <https://opentology.dev/vocab#Module> . ?m ?p ?o } }`);
             // Insert fresh triples
@@ -525,6 +557,20 @@ async function handleContextInit(args) {
         writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
         actions.push('Auto-registered hooks in .claude/settings.json');
     }
+    // Ensure .opentology/snapshots/ is in .gitignore
+    const gitignorePath = join(process.cwd(), '.gitignore');
+    const snapshotIgnore = '.opentology/snapshots/';
+    if (existsSync(gitignorePath)) {
+        const gitignoreContent = readFileSync(gitignorePath, 'utf-8');
+        if (!gitignoreContent.includes(snapshotIgnore)) {
+            writeFileSync(gitignorePath, gitignoreContent.trimEnd() + '\n' + snapshotIgnore + '\n', 'utf-8');
+            actions.push('Added .opentology/snapshots/ to .gitignore');
+        }
+    }
+    else {
+        writeFileSync(gitignorePath, snapshotIgnore + '\n', 'utf-8');
+        actions.push('Created .gitignore with .opentology/snapshots/');
+    }
     // Auto-push Module triples from dependency graph
     let moduleStats = null;
     try {
@@ -560,6 +606,7 @@ async function handleContextInit(args) {
         moduleStats,
         dependencyHint,
         hooksAutoInstalled: hooksChanged,
+        scanSuggestion: 'Run context_scan to populate the knowledge graph. Use depth="module" for file-level dependencies, or depth="symbol" (with includeMethodCalls=true) for class/function/call-level analysis. The symbol scan enables queries like "which functions call persistGraph?" from the graph.',
     };
 }
 async function handleContextLoad() {
@@ -1043,7 +1090,7 @@ export async function startMcpServer() {
             },
             {
                 name: 'diff',
-                description: 'Compare local Turtle content against the remote graph. Returns added triples (in local but not remote), removed triples (in remote but not local), and count of unchanged triples.',
+                description: 'Compare local Turtle content against the remote graph. Returns added triples (in local but not remote), removed triples (in remote but not local), and count of unchanged triples. Output is limited to avoid blowing up LLM context windows.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -1051,6 +1098,10 @@ export async function startMcpServer() {
                             type: 'string',
                             description: 'Turtle (RDF) content to compare against the remote graph',
                         },
+                        limit: {
+                            type: 'number',
+                            description: 'Maximum number of added/removed triples to return (default: 50). Total counts are always included.',
+                        },
                         graph: {
                             type: 'string',
                             description: 'Logical graph name (as created by graph_create). Resolves to a graph URI via config.',
@@ -1262,6 +1313,33 @@ export async function startMcpServer() {
                     properties: {},
                 },
             },
+            {
+                name: 'rollback',
+                description: 'List or restore graph snapshots. Snapshots are automatically created before destructive operations (drop, delete, scan, etc.). Use action=list to see available snapshots, action=restore with a timestamp to restore.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        action: {
+                            type: 'string',
+                            enum: ['list', 'restore'],
+                            description: 'Action: list available snapshots or restore a specific one',
+                        },
+                        to: {
+                            type: 'string',
+                            description: 'Timestamp of the snapshot to restore (required for action=restore)',
+                        },
+                        graph: {
+                            type: 'string',
+                            description: 'Logical graph name (as created by graph_create). Resolves to a graph URI via config.',
+                        },
+                        graphUri: {
+                            type: 'string',
+                            description: 'Named graph URI (uses config default if omitted)',
+                        },
+                    },
+                    required: ['action'],
+                },
+            },
         ],
     }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -1335,8 +1413,19 @@ export async function startMcpServer() {
                 case 'context_impact':
                     result = await handleContextImpact(args);
                     break;
-                case 'context_sync':
-                    result = await syncContext(loadConfig(), process.cwd());
+                case 'context_sync': {
+                    const syncConfig = loadConfig();
+                    const syncContextUri = `${syncConfig.graphUri}/context`;
+                    const syncSessionsUri = `${syncConfig.graphUri}/sessions`;
+                    const syncAdapter = await createReadyAdapter(syncConfig);
+                    await snapshotGraph(syncAdapter, syncConfig, syncContextUri);
+                    result = await syncContext(syncConfig, process.cwd());
+                    await persistGraph(syncAdapter, syncConfig, syncContextUri);
+                    await persistGraph(syncAdapter, syncConfig, syncSessionsUri);
+                    break;
+                }
+                case 'rollback':
+                    result = await handleRollback(args);
                     break;
                 case 'doctor':
                     result = await runDoctor();

package/dist/templates/claude-md-context.js

@@ -26,6 +26,12 @@ This project uses OpenTology as its project context graph.
 | \`otx:Knowledge\` | Reusable knowledge |
 | \`otx:Session\` | Session logs |
 | \`otx:Pattern\` | Recurring patterns/conventions |
+| \`otx:Module\` | Source file module |
+| \`otx:Class\` | Class definition (symbol scan) |
+| \`otx:Interface\` | Interface definition (symbol scan) |
+| \`otx:Function\` | Function definition (symbol scan) |
+| \`otx:Method\` | Method definition (symbol scan) |
+| \`otx:MethodCall\` | Call relationship between symbols (symbol scan) |
 
 | Property | Range | Description |
 |----------|-------|-------------|
@@ -36,6 +42,11 @@ This project uses OpenTology as its project context graph.
 | \`otx:reason\` | string | Decision rationale |
 | \`otx:nextTodo\` | string | Next action item |
 | \`otx:relatedTo\` | resource | Related entity |
+| \`otx:dependsOn\` | Module | Module import dependency |
+| \`otx:definedIn\` | Module | Which module a symbol belongs to |
+| \`otx:callerSymbol\` | string | Caller in a MethodCall |
+| \`otx:calleeSymbol\` | string | Callee in a MethodCall |
+| \`otx:calls\` | resource | Call relationship |
 
 ### When to Record
 
@@ -107,13 +118,48 @@ If impact is **high**, inform the user of affected modules and get confirmation
 
 #### Searching the Knowledge Graph
 
-Use \`query\` with SPARQL to find anything in the project graph:
+Use \`query\` with SPARQL to find anything in the project graph. **Always query the graph before reading source files** when investigating code structure, dependencies, or call relationships:
+
 - **Decisions**: \`?s a otx:Decision\` — why architectural choices were made
 - **Issues**: \`?s a otx:Issue ; otx:status "open"\` — known bugs and their status
 - **Knowledge**: \`?s a otx:Knowledge\` — reusable patterns and lessons learned
 - **Sessions**: query the sessions graph for past work logs and next TODOs
 - **Modules**: \`?s a otx:Module\` — all scanned source modules and their dependencies (\`otx:dependsOn\`)
 - **Symbols**: \`?s a otx:Class\`, \`otx:Interface\`, \`otx:Function\`, \`otx:Method\` — code-level entities (available after symbol-depth scan)
+- **Call graph**: \`?s a otx:MethodCall\` — who calls whom (available after symbol scan with \`includeMethodCalls=true\`)
+
+\`\`\`sparql
+# Functions in a specific module
+PREFIX otx: <https://opentology.dev/vocab#>
+SELECT ?name WHERE {
+  GRAPH <${contextUri}> {
+    ?f a otx:Function ; otx:title ?name ; otx:definedIn <urn:module:src/mcp/server> .
+  }
+}
+
+# Who calls a specific function?
+PREFIX otx: <https://opentology.dev/vocab#>
+SELECT ?caller WHERE {
+  GRAPH <${contextUri}> {
+    ?s a otx:MethodCall ; otx:callerSymbol ?caller ; otx:calleeSymbol ?callee .
+    FILTER(CONTAINS(?callee, "persistGraph"))
+  }
+}
+
+# Module dependency chain (what depends on a module?)
+PREFIX otx: <https://opentology.dev/vocab#>
+SELECT ?dependent WHERE {
+  GRAPH <${contextUri}> {
+    ?dependent otx:dependsOn+ <urn:module:src/lib/store-adapter> .
+  }
+}
+\`\`\`
+
+#### Post-Edit Graph Update
+
+After significant code changes (new files, renamed functions, changed dependencies), run \`context_scan\` to keep the knowledge graph in sync:
+- \`depth="module"\` — fast, updates file-level imports
+- \`depth="symbol"\` with \`includeMethodCalls=true\` — thorough, updates class/function/call graph
 
 #### Other Useful Tools
 

package/dist/templates/otx-ontology.d.ts

@@ -1 +1 @@
-export declare const OTX_BOOTSTRAP_TURTLE = "@prefix otx: <https://opentology.dev/vocab#> .\n@prefix owl: <http://www.w3.org/2002/07/owl#> .\n@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .\n@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .\n\notx:Project a owl:Class .\notx:Decision a owl:Class .\notx:Issue a owl:Class .\notx:Knowledge a owl:Class .\notx:Session a owl:Class .\notx:Pattern a owl:Class .\notx:Module a owl:Class .\n\notx:title a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:date a owl:DatatypeProperty ; rdfs:range xsd:date .\notx:body a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:status a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:reason a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:cause a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:solution a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:nextTodo a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:relatedTo a owl:ObjectProperty .\notx:project a owl:ObjectProperty .\notx:dependsOn a owl:ObjectProperty ; rdfs:domain otx:Module ; rdfs:range otx:Module .\notx:stack a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:alternative a owl:DatatypeProperty ; rdfs:range xsd:string .\n\notx:Class a owl:Class .\notx:Interface a owl:Class .\notx:Function a owl:Class .\notx:Method a owl:Class .\n\notx:definedIn a owl:ObjectProperty ; rdfs:range otx:Module .\notx:extends a owl:ObjectProperty ; rdfs:domain otx:Class ; rdfs:range otx:Class .\notx:implements a owl:ObjectProperty ; rdfs:domain otx:Class ; rdfs:range otx:Interface .\notx:hasMethod a owl:ObjectProperty ; rdfs:domain otx:Class ; rdfs:range otx:Method .\notx:calls a owl:ObjectProperty ; rdfs:domain otx:Method ; rdfs:range otx:Method .\notx:returns a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:paramType a owl:DatatypeProperty ; rdfs:range xsd:string .\n";
+export declare const OTX_BOOTSTRAP_TURTLE = "@prefix otx: <https://opentology.dev/vocab#> .\n@prefix owl: <http://www.w3.org/2002/07/owl#> .\n@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .\n@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .\n\notx:Project a owl:Class .\notx:Decision a owl:Class .\notx:Issue a owl:Class .\notx:Knowledge a owl:Class .\notx:Session a owl:Class .\notx:Pattern a owl:Class .\notx:Module a owl:Class .\n\notx:title a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:date a owl:DatatypeProperty ; rdfs:range xsd:date .\notx:body a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:status a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:reason a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:cause a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:solution a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:nextTodo a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:relatedTo a owl:ObjectProperty .\notx:project a owl:ObjectProperty .\notx:dependsOn a owl:ObjectProperty ; rdfs:domain otx:Module ; rdfs:range otx:Module .\notx:stack a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:alternative a owl:DatatypeProperty ; rdfs:range xsd:string .\n\notx:Class a owl:Class .\notx:Interface a owl:Class .\notx:Function a owl:Class .\notx:Method a owl:Class .\notx:MethodCall a owl:Class .\n\notx:definedIn a owl:ObjectProperty ; rdfs:range otx:Module .\notx:extends a owl:ObjectProperty ; rdfs:domain otx:Class ; rdfs:range otx:Class .\notx:implements a owl:ObjectProperty ; rdfs:domain otx:Class ; rdfs:range otx:Interface .\notx:hasMethod a owl:ObjectProperty ; rdfs:domain otx:Class ; rdfs:range otx:Method .\notx:calls a owl:ObjectProperty .\notx:callerSymbol a owl:ObjectProperty ; rdfs:domain otx:MethodCall .\notx:calleeSymbol a owl:ObjectProperty ; rdfs:domain otx:MethodCall .\notx:returns a owl:DatatypeProperty ; rdfs:range xsd:string .\notx:paramType a owl:DatatypeProperty ; rdfs:range xsd:string .\n";

package/dist/templates/otx-ontology.js

@@ -30,12 +30,15 @@ otx:Class a owl:Class .
 otx:Interface a owl:Class .
 otx:Function a owl:Class .
 otx:Method a owl:Class .
+otx:MethodCall a owl:Class .
 
 otx:definedIn a owl:ObjectProperty ; rdfs:range otx:Module .
 otx:extends a owl:ObjectProperty ; rdfs:domain otx:Class ; rdfs:range otx:Class .
 otx:implements a owl:ObjectProperty ; rdfs:domain otx:Class ; rdfs:range otx:Interface .
 otx:hasMethod a owl:ObjectProperty ; rdfs:domain otx:Class ; rdfs:range otx:Method .
-otx:calls a owl:ObjectProperty ; rdfs:domain otx:Method ; rdfs:range otx:Method .
+otx:calls a owl:ObjectProperty .
+otx:callerSymbol a owl:ObjectProperty ; rdfs:domain otx:MethodCall .
+otx:calleeSymbol a owl:ObjectProperty ; rdfs:domain otx:MethodCall .
 otx:returns a owl:DatatypeProperty ; rdfs:range xsd:string .
 otx:paramType a owl:DatatypeProperty ; rdfs:range xsd:string .
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentology",
-  "version": "0.2.8",
+  "version": "0.3.1",
   "description": "Ontology-powered project memory for AI coding assistants — your codebase as a knowledge graph",
   "type": "module",
   "bin": {