feat: document versioning — keep all versions in graph with version references

- documents table: add version, canonical_id, is_latest columns
- Idempotent migration for existing databases (ALTER TABLE ... ADD COLUMN)
- SupersedeDocument: marks old version is_latest=0 (data stays in graph)
- GetDocumentVersions: returns full version history by canonical ID
- GetDocumentByPath: returns latest version only
- ListDocuments: shows latest versions by default
- Pipeline: on re-upload, creates new version instead of deleting old data
  - Entities/relationships from all versions remain in the graph
  - doc_id on relationships traces which version they came from
- API: GET /api/documents/{id}/versions returns full version history

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: aksOps

internal/api/handlers.go

@@ -62,6 +62,25 @@ func (h *handlers) listDocuments(w http.ResponseWriter, r *http.Request) {
 	writeJSON(w, 200, docs)
 }
 
+func (h *handlers) getDocumentVersions(w http.ResponseWriter, r *http.Request) {
+	id := r.PathValue("id")
+	doc, err := h.store.GetDocument(r.Context(), id)
+	if err != nil {
+		writeError(w, 500, err.Error())
+		return
+	}
+	if doc == nil {
+		writeError(w, 404, "document not found")
+		return
+	}
+	versions, err := h.store.GetDocumentVersions(r.Context(), doc.CanonicalOrID())
+	if err != nil {
+		writeError(w, 500, err.Error())
+		return
+	}
+	writeJSON(w, 200, versions)
+}
+
 func (h *handlers) getDocument(w http.ResponseWriter, r *http.Request) {
 	id := r.PathValue("id")
 	doc, err := h.store.GetDocument(r.Context(), id)

internal/api/router.go

@@ -25,6 +25,7 @@ func NewRouter(st *store.Store, prov llm.Provider, emb *embedder.Embedder, cfg *
 	mux.HandleFunc("GET /api/stats", h.getStats)
 	mux.HandleFunc("GET /api/documents", h.listDocuments)
 	mux.HandleFunc("GET /api/documents/{id}", h.getDocument)
+	mux.HandleFunc("GET /api/documents/{id}/versions", h.getDocumentVersions)
 	mux.HandleFunc("POST /api/search", h.search)
 	mux.HandleFunc("GET /api/graph/neighborhood", h.graphNeighborhood)
 	mux.HandleFunc("GET /api/entities", h.listEntities)

internal/pipeline/pipeline.go

@@ -118,19 +118,24 @@ func (p *Pipeline) indexFile(ctx context.Context, path string, opts IndexOptions
 	h := sha256.Sum256(data)
 	hash := hex.EncodeToString(h[:])
 
-	// Incremental indexing: look up by path, compare hash.
+	// Incremental versioning: look up the latest version at this path.
 	existing, err := p.store.GetDocumentByPath(ctx, path)
 	if err != nil {
 		return err
 	}
+	if existing != nil && existing.FileHash == hash && !opts.Force {
+		return nil // unchanged — skip
+	}
+
+	// Determine version number and canonical ID for this (possibly new) version.
+	nextVersion := 1
+	canonicalID := ""
 	if existing != nil {
-		if existing.FileHash == hash && !opts.Force {
-			return nil // unchanged — skip
-		}
-		// Content changed (or --force): delete old document and all cascading data,
-		// then fall through to re-index.
-		if err := p.store.DeleteDocument(ctx, existing.ID); err != nil {
-			return fmt.Errorf("delete stale doc: %w", err)
+		nextVersion = existing.Version + 1
+		canonicalID = existing.CanonicalOrID()
+		// Mark the previous version as superseded (keep all its data in the graph).
+		if err := p.store.SupersedeDocument(ctx, existing.ID); err != nil {
+			return fmt.Errorf("supersede old version: %w", err)
 		}
 	}
 
@@ -147,11 +152,14 @@ func (p *Pipeline) indexFile(ctx context.Context, path string, opts IndexOptions
 
 	docID := uuid.New().String()
 	if err := p.store.UpsertDocument(ctx, &store.Document{
-		ID:       docID,
-		Path:     path,
-		Title:    doc.Title,
-		DocType:  doc.DocType,
-		FileHash: hash,
+		ID:          docID,
+		Path:        path,
+		Title:       doc.Title,
+		DocType:     doc.DocType,
+		FileHash:    hash,
+		Version:     nextVersion,
+		CanonicalID: canonicalID,
+		IsLatest:    true,
 	}); err != nil {
 		return fmt.Errorf("upsert doc: %w", err)
 	}

internal/store/store.go

@@ -35,20 +35,34 @@ func (s *Store) Close() error { return s.db.Close() }
 func (s *Store) DB() *sql.DB { return s.db }
 
 func (s *Store) migrate() error {
-	_, err := s.db.Exec(schema)
-	return err
+	if _, err := s.db.Exec(schema); err != nil {
+		return err
+	}
+	// Idempotent column additions for existing databases
+	migrations := []string{
+		`ALTER TABLE documents ADD COLUMN version      INTEGER NOT NULL DEFAULT 1`,
+		`ALTER TABLE documents ADD COLUMN canonical_id TEXT`,
+		`ALTER TABLE documents ADD COLUMN is_latest    INTEGER NOT NULL DEFAULT 1`,
+	}
+	for _, m := range migrations {
+		s.db.Exec(m) // ignore "duplicate column" errors
+	}
+	return nil
 }
 
 const schema = `
 CREATE TABLE IF NOT EXISTS documents (
-    id          TEXT PRIMARY KEY,
-    path        TEXT NOT NULL,
-    title       TEXT,
-    doc_type    TEXT,
-    file_hash   TEXT UNIQUE,
-    structured  TEXT,
-    created_at  INTEGER,
-    updated_at  INTEGER
+    id           TEXT PRIMARY KEY,
+    path         TEXT NOT NULL,
+    title        TEXT,
+    doc_type     TEXT,
+    file_hash    TEXT UNIQUE,
+    structured   TEXT,
+    version      INTEGER NOT NULL DEFAULT 1,
+    canonical_id TEXT,              -- NULL on first version; points to v1 ID on all later versions
+    is_latest    INTEGER NOT NULL DEFAULT 1,
+    created_at   INTEGER,
+    updated_at   INTEGER
 );
 
 CREATE TABLE IF NOT EXISTS chunks (
@@ -111,6 +125,8 @@ CREATE TABLE IF NOT EXISTS community_members (
     PRIMARY KEY (community_id, entity_id)
 );
 
+CREATE INDEX IF NOT EXISTS idx_doc_canonical      ON documents(canonical_id);
+CREATE INDEX IF NOT EXISTS idx_doc_path_latest    ON documents(path, is_latest);
 CREATE INDEX IF NOT EXISTS idx_chunks_doc         ON chunks(doc_id);
 CREATE INDEX IF NOT EXISTS idx_embeddings_model   ON embeddings(model);
 CREATE INDEX IF NOT EXISTS idx_entities_name      ON entities(name);
@@ -158,70 +174,138 @@ func CosineSimilarity(a, b []float32) float32 {
 // ── Document CRUD ─────────────────────────────────────────────────────────────
 
 type Document struct {
-	ID         string
-	Path       string
-	Title      string
-	DocType    string
-	FileHash   string
-	Structured string
-	CreatedAt  int64
-	UpdatedAt  int64
+	ID          string
+	Path        string
+	Title       string
+	DocType     string
+	FileHash    string
+	Structured  string
+	Version     int
+	CanonicalID string // empty on v1; ID of first version on v2+
+	IsLatest    bool
+	CreatedAt   int64
+	UpdatedAt   int64
+}
+
+// CanonicalOrID returns CanonicalID if set, otherwise the document's own ID.
+// This is the stable identifier across all versions of a file.
+func (d *Document) CanonicalOrID() string {
+	if d.CanonicalID != "" {
+		return d.CanonicalID
+	}
+	return d.ID
 }
 
 func (s *Store) UpsertDocument(ctx context.Context, doc *Document) error {
 	now := time.Now().Unix()
+	if doc.Version == 0 {
+		doc.Version = 1
+	}
+	var canonicalID any
+	if doc.CanonicalID != "" {
+		canonicalID = doc.CanonicalID
+	}
+	isLatest := 0
+	if doc.IsLatest {
+		isLatest = 1
+	}
 	_, err := s.db.ExecContext(ctx, `
-		INSERT INTO documents (id, path, title, doc_type, file_hash, structured, created_at, updated_at)
-		VALUES (?,?,?,?,?,?,?,?)
+		INSERT INTO documents (id, path, title, doc_type, file_hash, structured, version, canonical_id, is_latest, created_at, updated_at)
+		VALUES (?,?,?,?,?,?,?,?,?,?,?)
 		ON CONFLICT(id) DO UPDATE SET
 			path=excluded.path, title=excluded.title, doc_type=excluded.doc_type,
-			file_hash=excluded.file_hash, structured=excluded.structured, updated_at=excluded.updated_at`,
-		doc.ID, doc.Path, doc.Title, doc.DocType, doc.FileHash, doc.Structured, now, now)
+			file_hash=excluded.file_hash, structured=excluded.structured,
+			version=excluded.version, canonical_id=excluded.canonical_id,
+			is_latest=excluded.is_latest, updated_at=excluded.updated_at`,
+		doc.ID, doc.Path, doc.Title, doc.DocType, doc.FileHash, doc.Structured,
+		doc.Version, canonicalID, isLatest, now, now)
 	return err
 }
 
-func (s *Store) GetDocumentByHash(ctx context.Context, hash string) (*Document, error) {
-	row := s.db.QueryRowContext(ctx, `SELECT id,path,title,doc_type,file_hash,structured,created_at,updated_at FROM documents WHERE file_hash=?`, hash)
+// SupersedeDocument marks a document as no longer the latest version.
+func (s *Store) SupersedeDocument(ctx context.Context, id string) error {
+	_, err := s.db.ExecContext(ctx, `UPDATE documents SET is_latest=0, updated_at=? WHERE id=?`, time.Now().Unix(), id)
+	return err
+}
+
+// GetDocumentVersions returns all versions of a document by canonical ID, oldest first.
+func (s *Store) GetDocumentVersions(ctx context.Context, canonicalID string) ([]*Document, error) {
+	rows, err := s.db.QueryContext(ctx, `
+		SELECT id,path,title,doc_type,file_hash,structured,version,canonical_id,is_latest,created_at,updated_at
+		FROM documents
+		WHERE id=? OR canonical_id=?
+		ORDER BY version ASC`, canonicalID, canonicalID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var docs []*Document
+	for rows.Next() {
+		d, err := scanDocRow(rows)
+		if err != nil {
+			return nil, err
+		}
+		docs = append(docs, d)
+	}
+	return docs, rows.Err()
+}
+
+const docSelect = `SELECT id,path,title,doc_type,file_hash,structured,version,canonical_id,is_latest,created_at,updated_at FROM documents`
+
+func scanDocRow(rows *sql.Rows) (*Document, error) {
 	var d Document
-	err := row.Scan(&d.ID, &d.Path, &d.Title, &d.DocType, &d.FileHash, &d.Structured, &d.CreatedAt, &d.UpdatedAt)
-	if err == sql.ErrNoRows {
-		return nil, nil
+	var canonicalID sql.NullString
+	var isLatest int
+	err := rows.Scan(&d.ID, &d.Path, &d.Title, &d.DocType, &d.FileHash, &d.Structured,
+		&d.Version, &canonicalID, &isLatest, &d.CreatedAt, &d.UpdatedAt)
+	if err != nil {
+		return nil, err
 	}
-	return &d, err
+	if canonicalID.Valid {
+		d.CanonicalID = canonicalID.String
+	}
+	d.IsLatest = isLatest == 1
+	return &d, nil
 }
 
-func (s *Store) GetDocumentByPath(ctx context.Context, path string) (*Document, error) {
-	row := s.db.QueryRowContext(ctx, `SELECT id,path,title,doc_type,file_hash,structured,created_at,updated_at FROM documents WHERE path=?`, path)
+func scanDocSingleRow(row *sql.Row) (*Document, error) {
 	var d Document
-	err := row.Scan(&d.ID, &d.Path, &d.Title, &d.DocType, &d.FileHash, &d.Structured, &d.CreatedAt, &d.UpdatedAt)
+	var canonicalID sql.NullString
+	var isLatest int
+	err := row.Scan(&d.ID, &d.Path, &d.Title, &d.DocType, &d.FileHash, &d.Structured,
+		&d.Version, &canonicalID, &isLatest, &d.CreatedAt, &d.UpdatedAt)
 	if err == sql.ErrNoRows {
 		return nil, nil
 	}
-	return &d, err
+	if err != nil {
+		return nil, err
+	}
+	if canonicalID.Valid {
+		d.CanonicalID = canonicalID.String
+	}
+	d.IsLatest = isLatest == 1
+	return &d, nil
 }
 
-// DeleteDocument removes a document and all its cascading data
-// (chunks, embeddings, relationships, claims) via ON DELETE CASCADE.
-func (s *Store) DeleteDocument(ctx context.Context, id string) error {
-	_, err := s.db.ExecContext(ctx, `DELETE FROM documents WHERE id=?`, id)
-	return err
+func (s *Store) GetDocumentByHash(ctx context.Context, hash string) (*Document, error) {
+	return scanDocSingleRow(s.db.QueryRowContext(ctx, docSelect+` WHERE file_hash=?`, hash))
+}
+
+func (s *Store) GetDocumentByPath(ctx context.Context, path string) (*Document, error) {
+	// Returns the latest version at this path.
+	return scanDocSingleRow(s.db.QueryRowContext(ctx, docSelect+` WHERE path=? AND is_latest=1`, path))
 }
 
 func (s *Store) GetDocument(ctx context.Context, id string) (*Document, error) {
-	row := s.db.QueryRowContext(ctx, `SELECT id,path,title,doc_type,file_hash,structured,created_at,updated_at FROM documents WHERE id=?`, id)
-	var d Document
-	err := row.Scan(&d.ID, &d.Path, &d.Title, &d.DocType, &d.FileHash, &d.Structured, &d.CreatedAt, &d.UpdatedAt)
-	if err == sql.ErrNoRows {
-		return nil, nil
-	}
-	return &d, err
+	return scanDocSingleRow(s.db.QueryRowContext(ctx, docSelect+` WHERE id=?`, id))
 }
 
 func (s *Store) ListDocuments(ctx context.Context, docType string, limit, offset int) ([]*Document, error) {
-	q := `SELECT id,path,title,doc_type,file_hash,structured,created_at,updated_at FROM documents`
+	// Default: only latest versions.
+	q := docSelect + ` WHERE is_latest=1`
 	args := []any{}
 	if docType != "" {
-		q += ` WHERE doc_type=?`
+		q += ` AND doc_type=?`
 		args = append(args, docType)
 	}
 	q += ` ORDER BY created_at DESC LIMIT ? OFFSET ?`
@@ -233,11 +317,11 @@ func (s *Store) ListDocuments(ctx context.Context, docType string, limit, offset
 	defer rows.Close()
 	var docs []*Document
 	for rows.Next() {
-		var d Document
-		if err := rows.Scan(&d.ID, &d.Path, &d.Title, &d.DocType, &d.FileHash, &d.Structured, &d.CreatedAt, &d.UpdatedAt); err != nil {
+		d, err := scanDocRow(rows)
+		if err != nil {
 			return nil, err
 		}
-		docs = append(docs, &d)
+		docs = append(docs, d)
 	}
 	return docs, rows.Err()
 }