feat: persist reviewed chunks and index publication versions

2026-10-16 08:44:30 +08:00
parent 3f25ffab83
commit 41b3ae0e41
20 changed files with 1027 additions and 16 deletions
@@ -0,0 +1,74 @@
+"""Immutable chunk snapshots and atomic publication metadata (no vector index yet)."""
+
+from datetime import datetime
+
+from sqlalchemy import (
+    JSON,
+    CheckConstraint,
+    DateTime,
+    ForeignKey,
+    Integer,
+    String,
+    Text,
+    UniqueConstraint,
+    func,
+)
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.session import Base
+
+
+class IndexVersion(Base):
+    __tablename__ = "index_versions"
+    __table_args__ = (
+        CheckConstraint(
+            "status IN ('ready', 'published', 'superseded')", name="ck_index_version_status"
+        ),
+    )
+    id: Mapped[str] = mapped_column(String(36), primary_key=True)
+    status: Mapped[str] = mapped_column(String(20), nullable=False, default="ready")
+    config: Mapped[dict] = mapped_column(JSON, nullable=False)
+    corpus_fingerprint: Mapped[str] = mapped_column(String(64), nullable=False)
+    catalog_revision: Mapped[int] = mapped_column(Integer, nullable=False)
+    item_count: Mapped[int] = mapped_column(Integer, nullable=False)
+    chunk_count: Mapped[int] = mapped_column(Integer, nullable=False)
+    created_by: Mapped[int] = mapped_column(ForeignKey("users.id"), nullable=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+    published_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+
+class IndexState(Base):
+    __tablename__ = "index_state"
+    __table_args__ = (CheckConstraint("id = 1", name="ck_index_state_singleton"),)
+    id: Mapped[int] = mapped_column(primary_key=True)
+    active_version_id: Mapped[str | None] = mapped_column(ForeignKey("index_versions.id"))
+    generation: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    catalog_revision: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+
+
+class Chunk(Base):
+    __tablename__ = "chunks"
+    __table_args__ = (
+        UniqueConstraint("index_version_id", "knowledge_id", "ordinal", name="uq_chunk_position"),
+        CheckConstraint("start_offset >= 0 AND end_offset > start_offset", name="ck_chunk_offsets"),
+    )
+    id: Mapped[str] = mapped_column(String(36), primary_key=True)
+    index_version_id: Mapped[str] = mapped_column(ForeignKey("index_versions.id"), index=True)
+    knowledge_id: Mapped[int] = mapped_column(ForeignKey("knowledge_items.id"), nullable=False)
+    ordinal: Mapped[int] = mapped_column(Integer, nullable=False)
+    start_offset: Mapped[int] = mapped_column(Integer, nullable=False)
+    end_offset: Mapped[int] = mapped_column(Integer, nullable=False)
+    text: Mapped[str] = mapped_column(Text, nullable=False)
+    text_sha256: Mapped[str] = mapped_column(String(64), nullable=False)
+    provenance: Mapped[dict] = mapped_column(JSON, nullable=False)
+
+
+class IndexPublication(Base):
+    __tablename__ = "index_publications"
+    generation: Mapped[int] = mapped_column(primary_key=True)
+    previous_version_id: Mapped[str | None] = mapped_column(ForeignKey("index_versions.id"))
+    version_id: Mapped[str] = mapped_column(ForeignKey("index_versions.id"), nullable=False)
+    actor_id: Mapped[int] = mapped_column(ForeignKey("users.id"), nullable=False)
+    published_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now()
+    )