Add temporal versioning for node history tracking (Milestone 1)
Enable time-travel queries and history viewing by creating immutable version records on every node update. Includes database schema changes, store functions, MCP tools, and CLI commands for viewing history, comparing versions, and restoring to previous states.
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
import { randomUUID as uuid } from 'crypto';
|
||||
import { getDb } from './db';
|
||||
import { Node, Edge, AddNodeInput, UpdateNodeInput, ListOptions, QueryOptions, SearchResult, EdgeType } from '../types';
|
||||
import { Node, Edge, AddNodeInput, UpdateNodeInput, ListOptions, QueryOptions, SearchResult, EdgeType, NodeVersion, HistoricalNode, NodeDiff } from '../types';
|
||||
import { hybridSearch, deserializeEmbedding } from './search/index';
|
||||
import { getEmbedding } from './search/ollama';
|
||||
|
||||
@@ -43,21 +43,44 @@ export async function addNode(input: AddNodeInput): Promise<Node> {
|
||||
// Try to get embedding
|
||||
const embedding = await getEmbedding(`${input.title} ${content}`);
|
||||
|
||||
db.prepare(`
|
||||
INSERT INTO nodes (id, kind, title, content, status, tags, metadata, embedding, created_at, updated_at, last_accessed_at)
|
||||
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
|
||||
`).run(
|
||||
id, input.kind, input.title, content, input.status ?? null,
|
||||
JSON.stringify(tags), JSON.stringify(metadata),
|
||||
embedding ? serializeEmbedding(embedding) : null,
|
||||
now, now, now
|
||||
);
|
||||
const transaction = db.transaction(() => {
|
||||
db.prepare(`
|
||||
INSERT INTO nodes (id, kind, title, content, status, tags, metadata, embedding, created_at, updated_at, last_accessed_at, version)
|
||||
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
|
||||
`).run(
|
||||
id, input.kind, input.title, content, input.status ?? null,
|
||||
JSON.stringify(tags), JSON.stringify(metadata),
|
||||
embedding ? serializeEmbedding(embedding) : null,
|
||||
now, now, now, 1
|
||||
);
|
||||
|
||||
// Insert tags
|
||||
const insertTag = db.prepare('INSERT OR IGNORE INTO node_tags (node_id, tag) VALUES (?, ?)');
|
||||
for (const tag of tags) {
|
||||
insertTag.run(id, tag);
|
||||
}
|
||||
// Insert tags
|
||||
const insertTag = db.prepare('INSERT OR IGNORE INTO node_tags (node_id, tag) VALUES (?, ?)');
|
||||
for (const tag of tags) {
|
||||
insertTag.run(id, tag);
|
||||
}
|
||||
|
||||
// Create initial version record
|
||||
const versionId = uuid();
|
||||
db.prepare(`
|
||||
INSERT INTO node_versions (id, node_id, version, title, content, status, tags, metadata, valid_from, valid_until, created_by)
|
||||
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
|
||||
`).run(
|
||||
versionId,
|
||||
id,
|
||||
1,
|
||||
input.title,
|
||||
content,
|
||||
input.status ?? null,
|
||||
JSON.stringify(tags),
|
||||
JSON.stringify(metadata),
|
||||
now,
|
||||
null,
|
||||
'user'
|
||||
);
|
||||
});
|
||||
|
||||
transaction();
|
||||
|
||||
notifyDirty();
|
||||
return {
|
||||
@@ -114,46 +137,88 @@ export function listNodes(options: ListOptions = {}): Node[] {
|
||||
return nodes;
|
||||
}
|
||||
|
||||
export async function updateNode(id: string, input: UpdateNodeInput): Promise<Node | null> {
|
||||
export async function updateNode(id: string, input: UpdateNodeInput, createdBy: string = 'user'): Promise<Node | null> {
|
||||
const db = getDb();
|
||||
const existing = getNode(id);
|
||||
if (!existing) return null;
|
||||
// Get existing node without updating last_accessed_at
|
||||
const existingRow = db.prepare('SELECT * FROM nodes WHERE id = ?').get(id) as any;
|
||||
if (!existingRow) return null;
|
||||
const existing = rowToNode(existingRow);
|
||||
|
||||
const now = Date.now();
|
||||
const sets: string[] = ['updated_at = ?'];
|
||||
const params: any[] = [now];
|
||||
|
||||
if (input.title !== undefined) { sets.push('title = ?'); params.push(input.title); }
|
||||
if (input.content !== undefined) { sets.push('content = ?'); params.push(input.content); }
|
||||
if (input.status !== undefined) { sets.push('status = ?'); params.push(input.status); }
|
||||
if (input.isStale !== undefined) { sets.push('is_stale = ?'); params.push(input.isStale ? 1 : 0); }
|
||||
if (input.tags !== undefined) { sets.push('tags = ?'); params.push(JSON.stringify(input.tags)); }
|
||||
if (input.metadata !== undefined) {
|
||||
const merged = { ...existing.metadata, ...input.metadata };
|
||||
sets.push('metadata = ?');
|
||||
params.push(JSON.stringify(merged));
|
||||
}
|
||||
// Get current version number
|
||||
const currentVersion = existingRow.version ?? 1;
|
||||
const newVersion = currentVersion + 1;
|
||||
|
||||
// Re-embed if title or content changed
|
||||
// Create version snapshot in a transaction
|
||||
const transaction = db.transaction(() => {
|
||||
// Close out the current version by setting valid_until
|
||||
db.prepare(`
|
||||
UPDATE node_versions SET valid_until = ? WHERE node_id = ? AND valid_until IS NULL
|
||||
`).run(now, id);
|
||||
|
||||
// Insert new version record with the NEW state (after update)
|
||||
const versionId = uuid();
|
||||
const newTitle = input.title ?? existing.title;
|
||||
const newContent = input.content ?? existing.content;
|
||||
const newStatus = input.status !== undefined ? input.status : existing.status;
|
||||
const newTags = input.tags ?? existing.tags;
|
||||
const newMetadata = input.metadata !== undefined ? { ...existing.metadata, ...input.metadata } : existing.metadata;
|
||||
|
||||
db.prepare(`
|
||||
INSERT INTO node_versions (id, node_id, version, title, content, status, tags, metadata, valid_from, valid_until, created_by)
|
||||
VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
|
||||
`).run(
|
||||
versionId,
|
||||
id,
|
||||
newVersion,
|
||||
newTitle,
|
||||
newContent,
|
||||
newStatus ?? null,
|
||||
JSON.stringify(newTags),
|
||||
JSON.stringify(newMetadata),
|
||||
now,
|
||||
null,
|
||||
createdBy
|
||||
);
|
||||
|
||||
// Build the update query
|
||||
const sets: string[] = ['updated_at = ?', 'version = ?'];
|
||||
const params: any[] = [now, newVersion];
|
||||
|
||||
if (input.title !== undefined) { sets.push('title = ?'); params.push(input.title); }
|
||||
if (input.content !== undefined) { sets.push('content = ?'); params.push(input.content); }
|
||||
if (input.status !== undefined) { sets.push('status = ?'); params.push(input.status); }
|
||||
if (input.isStale !== undefined) { sets.push('is_stale = ?'); params.push(input.isStale ? 1 : 0); }
|
||||
if (input.tags !== undefined) { sets.push('tags = ?'); params.push(JSON.stringify(input.tags)); }
|
||||
if (input.metadata !== undefined) {
|
||||
const merged = { ...existing.metadata, ...input.metadata };
|
||||
sets.push('metadata = ?');
|
||||
params.push(JSON.stringify(merged));
|
||||
}
|
||||
|
||||
params.push(id);
|
||||
db.prepare(`UPDATE nodes SET ${sets.join(', ')} WHERE id = ?`).run(...params);
|
||||
|
||||
// Update tags if changed
|
||||
if (input.tags !== undefined) {
|
||||
db.prepare('DELETE FROM node_tags WHERE node_id = ?').run(id);
|
||||
const insertTag = db.prepare('INSERT OR IGNORE INTO node_tags (node_id, tag) VALUES (?, ?)');
|
||||
for (const tag of input.tags) {
|
||||
insertTag.run(id, tag);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
transaction();
|
||||
|
||||
// Re-embed if title or content changed (outside transaction since it's async)
|
||||
if (input.title !== undefined || input.content !== undefined) {
|
||||
const newTitle = input.title ?? existing.title;
|
||||
const newContent = input.content ?? existing.content;
|
||||
const embedding = await getEmbedding(`${newTitle} ${newContent}`);
|
||||
if (embedding) {
|
||||
sets.push('embedding = ?');
|
||||
params.push(serializeEmbedding(embedding));
|
||||
}
|
||||
}
|
||||
|
||||
params.push(id);
|
||||
db.prepare(`UPDATE nodes SET ${sets.join(', ')} WHERE id = ?`).run(...params);
|
||||
|
||||
// Update tags if changed
|
||||
if (input.tags !== undefined) {
|
||||
db.prepare('DELETE FROM node_tags WHERE node_id = ?').run(id);
|
||||
const insertTag = db.prepare('INSERT OR IGNORE INTO node_tags (node_id, tag) VALUES (?, ?)');
|
||||
for (const tag of input.tags) {
|
||||
insertTag.run(id, tag);
|
||||
db.prepare('UPDATE nodes SET embedding = ? WHERE id = ?').run(serializeEmbedding(embedding), id);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -195,3 +260,114 @@ export async function query(text: string, options: QueryOptions = {}): Promise<S
|
||||
const nodes = listNodes({ kind: options.kind, tags: options.tags, includeStale: options.includeStale });
|
||||
return hybridSearch(nodes, text, options);
|
||||
}
|
||||
|
||||
// Version tracking functions
|
||||
|
||||
function rowToNodeVersion(row: any): NodeVersion {
|
||||
return {
|
||||
id: row.id,
|
||||
nodeId: row.node_id,
|
||||
version: row.version,
|
||||
title: row.title,
|
||||
content: row.content,
|
||||
status: row.status ?? undefined,
|
||||
tags: JSON.parse(row.tags || '[]'),
|
||||
metadata: JSON.parse(row.metadata || '{}'),
|
||||
validFrom: row.valid_from,
|
||||
validUntil: row.valid_until ?? null,
|
||||
createdBy: row.created_by,
|
||||
};
|
||||
}
|
||||
|
||||
function rowToHistoricalNode(row: any, nodeRow: any): HistoricalNode {
|
||||
return {
|
||||
id: nodeRow.id,
|
||||
kind: nodeRow.kind,
|
||||
title: row.title,
|
||||
content: row.content,
|
||||
status: row.status ?? undefined,
|
||||
tags: JSON.parse(row.tags || '[]'),
|
||||
metadata: JSON.parse(row.metadata || '{}'),
|
||||
version: row.version,
|
||||
validFrom: row.valid_from,
|
||||
validUntil: row.valid_until ?? null,
|
||||
};
|
||||
}
|
||||
|
||||
export function getNodeHistory(id: string): NodeVersion[] {
|
||||
const db = getDb();
|
||||
const rows = db.prepare(`
|
||||
SELECT * FROM node_versions WHERE node_id = ? ORDER BY version DESC
|
||||
`).all(id) as any[];
|
||||
return rows.map(rowToNodeVersion);
|
||||
}
|
||||
|
||||
export function getNodeAtTime(id: string, timestamp: number): HistoricalNode | null {
|
||||
const db = getDb();
|
||||
const nodeRow = db.prepare('SELECT * FROM nodes WHERE id = ?').get(id) as any;
|
||||
if (!nodeRow) return null;
|
||||
|
||||
const versionRow = db.prepare(`
|
||||
SELECT * FROM node_versions
|
||||
WHERE node_id = ? AND valid_from <= ? AND (valid_until IS NULL OR valid_until > ?)
|
||||
ORDER BY version DESC LIMIT 1
|
||||
`).get(id, timestamp, timestamp) as any;
|
||||
|
||||
if (!versionRow) return null;
|
||||
return rowToHistoricalNode(versionRow, nodeRow);
|
||||
}
|
||||
|
||||
export function getNodeVersion(id: string, version: number): HistoricalNode | null {
|
||||
const db = getDb();
|
||||
const nodeRow = db.prepare('SELECT * FROM nodes WHERE id = ?').get(id) as any;
|
||||
if (!nodeRow) return null;
|
||||
|
||||
const versionRow = db.prepare(`
|
||||
SELECT * FROM node_versions WHERE node_id = ? AND version = ?
|
||||
`).get(id, version) as any;
|
||||
|
||||
if (!versionRow) return null;
|
||||
return rowToHistoricalNode(versionRow, nodeRow);
|
||||
}
|
||||
|
||||
export function diffVersions(id: string, v1: number, v2: number): NodeDiff | null {
|
||||
const version1 = getNodeVersion(id, v1);
|
||||
const version2 = getNodeVersion(id, v2);
|
||||
|
||||
if (!version1 || !version2) return null;
|
||||
|
||||
const changes: NodeDiff['changes'] = [];
|
||||
const fieldsToCompare: (keyof HistoricalNode)[] = ['title', 'content', 'status', 'tags', 'metadata'];
|
||||
|
||||
for (const field of fieldsToCompare) {
|
||||
const oldVal = version1[field];
|
||||
const newVal = version2[field];
|
||||
const oldStr = JSON.stringify(oldVal);
|
||||
const newStr = JSON.stringify(newVal);
|
||||
if (oldStr !== newStr) {
|
||||
changes.push({ field, old: oldVal, new: newVal });
|
||||
}
|
||||
}
|
||||
|
||||
return { nodeId: id, v1, v2, changes };
|
||||
}
|
||||
|
||||
export async function restoreVersion(id: string, version: number, createdBy: string = 'restore'): Promise<Node | null> {
|
||||
const historical = getNodeVersion(id, version);
|
||||
if (!historical) return null;
|
||||
|
||||
// updateNode will handle creating a new version
|
||||
return updateNode(id, {
|
||||
title: historical.title,
|
||||
content: historical.content,
|
||||
status: historical.status,
|
||||
tags: historical.tags,
|
||||
metadata: historical.metadata,
|
||||
}, createdBy);
|
||||
}
|
||||
|
||||
export function getCurrentVersion(id: string): number {
|
||||
const db = getDb();
|
||||
const row = db.prepare('SELECT version FROM nodes WHERE id = ?').get(id) as any;
|
||||
return row?.version ?? 1;
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user