@gmickel/gno 1.20.0 → 1.21.0

package/src/store/migrations/016-saved-capsules.ts

@@ -0,0 +1,131 @@
+/**
+ * Migration: metadata-only saved Context Capsule registry.
+ *
+ * Capsule bodies remain user-owned files. The database stores only file and
+ * Capsule identities, evidence references, the latest verification outcome,
+ * and the journal high-water sequence used by the resident scheduler.
+ *
+ * @module src/store/migrations/016-saved-capsules
+ */
+
+import type { Database } from "bun:sqlite";
+
+import type { Migration } from "./runner";
+
+export const migration: Migration = {
+  version: 16,
+  name: "saved_capsules",
+
+  up(db: Database): void {
+    db.exec(`
+      CREATE TABLE saved_capsule_registrations (
+        registration_id TEXT PRIMARY KEY,
+        file_path TEXT NOT NULL UNIQUE,
+        file_hash TEXT NOT NULL,
+        capsule_id TEXT NOT NULL,
+        index_name TEXT NOT NULL,
+        question TEXT,
+        label TEXT,
+        notification_preference TEXT NOT NULL DEFAULT 'none'
+          CHECK (notification_preference IN ('none', 'local')),
+        registered_at_ms INTEGER NOT NULL CHECK (registered_at_ms >= 0),
+        updated_at_ms INTEGER NOT NULL CHECK (updated_at_ms >= registered_at_ms),
+        last_attempted_sequence INTEGER NOT NULL DEFAULT 0
+          CHECK (last_attempted_sequence >= 0),
+        CHECK (length(registration_id) BETWEEN 1 AND 128),
+        CHECK (length(CAST(file_path AS BLOB)) BETWEEN 1 AND 8192),
+        CHECK (length(file_hash) = 64 AND file_hash NOT GLOB '*[^0-9a-f]*'),
+        CHECK (length(capsule_id) = 64 AND capsule_id NOT GLOB '*[^0-9a-f]*'),
+        CHECK (length(CAST(index_name AS BLOB)) BETWEEN 1 AND 128),
+        CHECK (question IS NULL OR length(CAST(question AS BLOB)) <= 8192),
+        CHECK (label IS NULL OR length(CAST(label AS BLOB)) <= 512)
+      );
+
+      CREATE INDEX idx_saved_capsules_index
+      ON saved_capsule_registrations(index_name, registration_id);
+
+      CREATE TABLE saved_capsule_evidence (
+        registration_id TEXT NOT NULL,
+        evidence_id TEXT NOT NULL,
+        canonical_uri TEXT NOT NULL,
+        collection TEXT NOT NULL,
+        source_hash TEXT NOT NULL,
+        mirror_hash TEXT NOT NULL,
+        passage_hash TEXT NOT NULL,
+        PRIMARY KEY (registration_id, evidence_id),
+        FOREIGN KEY (registration_id)
+          REFERENCES saved_capsule_registrations(registration_id)
+          ON DELETE CASCADE,
+        CHECK (length(evidence_id) = 64 AND evidence_id NOT GLOB '*[^0-9a-f]*'),
+        CHECK (length(CAST(canonical_uri AS BLOB)) BETWEEN 1 AND 8192),
+        CHECK (length(CAST(collection AS BLOB)) BETWEEN 1 AND 256),
+        CHECK (length(source_hash) = 64 AND source_hash NOT GLOB '*[^0-9a-f]*'),
+        CHECK (length(mirror_hash) = 64 AND mirror_hash NOT GLOB '*[^0-9a-f]*'),
+        CHECK (length(passage_hash) = 64 AND passage_hash NOT GLOB '*[^0-9a-f]*')
+      );
+
+      CREATE INDEX idx_saved_capsule_evidence_uri
+      ON saved_capsule_evidence(canonical_uri, registration_id);
+
+      CREATE INDEX idx_saved_capsule_evidence_source
+      ON saved_capsule_evidence(source_hash, registration_id);
+
+      CREATE INDEX idx_saved_capsule_evidence_mirror
+      ON saved_capsule_evidence(mirror_hash, registration_id);
+
+      CREATE TABLE saved_capsule_verifications (
+        registration_id TEXT PRIMARY KEY,
+        trigger_kind TEXT NOT NULL CHECK (trigger_kind IN ('manual', 'journal')),
+        from_sequence INTEGER NOT NULL CHECK (from_sequence >= 0),
+        through_sequence INTEGER NOT NULL
+          CHECK (through_sequence >= from_sequence),
+        operation_status TEXT NOT NULL CHECK (operation_status IN ('completed', 'failed')),
+        affected_question_state TEXT NOT NULL
+          CHECK (affected_question_state IN ('unaffected', 'affected', 'unknown')),
+        affected_reasons_json TEXT NOT NULL,
+        receipt_json TEXT,
+        receipt_hash TEXT,
+        error_code TEXT,
+        error_message TEXT,
+        verified_at_ms INTEGER NOT NULL CHECK (verified_at_ms >= 0),
+        FOREIGN KEY (registration_id)
+          REFERENCES saved_capsule_registrations(registration_id)
+          ON DELETE CASCADE,
+        CHECK (length(CAST(affected_reasons_json AS BLOB)) <= 4096),
+        CHECK (receipt_json IS NULL OR length(CAST(receipt_json AS BLOB)) <= 16777216),
+        CHECK (receipt_hash IS NULL OR (
+          length(receipt_hash) = 64 AND receipt_hash NOT GLOB '*[^0-9a-f]*'
+        )),
+        CHECK (error_code IS NULL OR length(CAST(error_code AS BLOB)) <= 256),
+        CHECK (error_message IS NULL OR length(CAST(error_message AS BLOB)) <= 4096),
+        CHECK (
+          (
+            operation_status = 'completed'
+            AND receipt_json IS NOT NULL
+            AND receipt_hash IS NOT NULL
+            AND error_code IS NULL
+            AND error_message IS NULL
+          )
+          OR
+          (
+            operation_status = 'failed'
+            AND receipt_json IS NULL
+            AND receipt_hash IS NULL
+            AND error_code IS NOT NULL
+            AND error_message IS NOT NULL
+          )
+        )
+      );
+
+      CREATE TABLE saved_capsule_reverification_state (
+        singleton_id INTEGER PRIMARY KEY CHECK (singleton_id = 1),
+        last_processed_sequence INTEGER NOT NULL DEFAULT 0
+          CHECK (last_processed_sequence >= 0)
+      );
+
+      INSERT INTO saved_capsule_reverification_state (
+        singleton_id, last_processed_sequence
+      ) VALUES (1, 0);
+    `);
+  },
+};

package/src/store/migrations/017-document-change-retention-counters.ts

@@ -0,0 +1,33 @@
+/**
+ * Migration: transactional retained-row/byte counters for the change journal.
+ *
+ * The counters let append-time retention inspect only the oldest bounded
+ * prefix that may be deleted instead of rescanning/materializing the journal.
+ */
+
+import type { Database } from "bun:sqlite";
+
+import type { Migration } from "./runner";
+
+export const migration: Migration = {
+  version: 17,
+  name: "document_change_retention_counters",
+
+  up(db: Database): void {
+    db.exec(`
+      ALTER TABLE document_change_journal_state
+        ADD COLUMN retained_entries INTEGER NOT NULL DEFAULT 0
+          CHECK (retained_entries >= 0);
+      ALTER TABLE document_change_journal_state
+        ADD COLUMN retained_bytes INTEGER NOT NULL DEFAULT 0
+          CHECK (retained_bytes >= 0);
+
+      UPDATE document_change_journal_state
+      SET retained_entries = (SELECT COUNT(*) FROM document_changes),
+          retained_bytes = (
+            SELECT COALESCE(SUM(byte_size), 0) FROM document_changes
+          )
+      WHERE singleton_id = 1;
+    `);
+  },
+};

package/src/store/migrations/018-saved-capsule-registration-epoch.ts

@@ -0,0 +1,24 @@
+/**
+ * Migration: saved Capsule registration epoch for race-free scheduler drains.
+ *
+ * Registration updates rewind the durable journal high-water mark and advance
+ * this epoch in the same transaction. A scheduler drain may advance the
+ * high-water mark only when no registration changed since the drain began.
+ */
+
+import type { Database } from "bun:sqlite";
+
+import type { Migration } from "./runner";
+
+export const migration: Migration = {
+  version: 18,
+  name: "saved_capsule_registration_epoch",
+
+  up(db: Database): void {
+    db.exec(`
+      ALTER TABLE saved_capsule_reverification_state
+        ADD COLUMN registration_epoch INTEGER NOT NULL DEFAULT 0
+          CHECK (registration_epoch >= 0);
+    `);
+  },
+};

package/src/store/migrations/019-saved-capsule-registration-generation.ts

@@ -0,0 +1,53 @@
+/**
+ * Migration: per-registration generations for receipt persistence CAS.
+ *
+ * Existing rows receive unique generations above the durable global epoch.
+ * Future upserts allocate from that same monotonic epoch, so delete/recreate
+ * cannot reuse a verification generation even for identical Capsule bytes.
+ */
+
+import type { Database } from "bun:sqlite";
+
+import type { Migration } from "./runner";
+
+export const migration: Migration = {
+  version: 19,
+  name: "saved_capsule_registration_generation",
+
+  up(db: Database): void {
+    db.exec(`
+      ALTER TABLE saved_capsule_registrations
+        ADD COLUMN registration_generation INTEGER NOT NULL DEFAULT 0
+          CHECK (registration_generation >= 0);
+    `);
+    const currentEpoch =
+      db
+        .query<{ registration_epoch: number }, []>(
+          `SELECT registration_epoch
+           FROM saved_capsule_reverification_state
+           WHERE singleton_id = 1`
+        )
+        .get()?.registration_epoch ?? 0;
+    const rows = db
+      .query<{ registration_id: string }, []>(
+        `SELECT registration_id
+         FROM saved_capsule_registrations
+         ORDER BY registration_id ASC`
+      )
+      .all();
+    const update = db.prepare(
+      `UPDATE saved_capsule_registrations
+       SET registration_generation = ?
+       WHERE registration_id = ?`
+    );
+    for (const [index, row] of rows.entries()) {
+      update.run(currentEpoch + index + 1, row.registration_id);
+    }
+    db.run(
+      `UPDATE saved_capsule_reverification_state
+       SET registration_epoch = ?
+       WHERE singleton_id = 1`,
+      [currentEpoch + rows.length]
+    );
+  },
+};

package/src/store/migrations/index.ts

@@ -28,6 +28,11 @@ import { migration as m011 } from "./011-doc-edge-traversal-indexes";
 import { migration as m012 } from "./012-activation-receipts";
 import { migration as m013 } from "./013-fts-sync-marker";
 import { migration as m014 } from "./014-retrieval-traces";
+import { migration as m015 } from "./015-document-change-journal";
+import { migration as m016 } from "./016-saved-capsules";
+import { migration as m017 } from "./017-document-change-retention-counters";
+import { migration as m018 } from "./018-saved-capsule-registration-epoch";
+import { migration as m019 } from "./019-saved-capsule-registration-generation";
 
 /** All migrations in order */
 export const migrations = [
@@ -45,4 +50,9 @@ export const migrations = [
   m012,
   m013,
   m014,
+  m015,
+  m016,
+  m017,
+  m018,
+  m019,
 ];

package/src/store/sqlite/adapter.ts

@@ -35,6 +35,12 @@ import type {
   DocLinkInput,
   DocLinkRow,
   DocLinkSource,
+  DocumentChangeKind,
+  DocumentChangeListOptions,
+  DocumentChangePage,
+  DocumentChangePurgeResult,
+  DocumentChangeRetentionPolicy,
+  DocumentChangeRetentionResult,
   DocumentInput,
   DocumentRow,
   EmbeddingCleanupStats,
@@ -70,6 +76,13 @@ import type {
   RetrievalTraceRow,
   RetrievalTraceRunInput,
   RetrievalTraceTerminalStatus,
+  RenameDocumentOptions,
+  SavedCapsuleRegistrationInput,
+  SavedCapsuleRegistrationRecord,
+  SavedCapsuleRegistrationSnapshot,
+  SavedCapsuleReverificationState,
+  SavedCapsuleVerificationExpectation,
+  SavedCapsuleVerificationRecord,
   StorePort,
   StoreResult,
   TagCount,
@@ -95,6 +108,25 @@ import { getSchemaVersion, migrations, runMigrations } from "../migrations";
 import { err, ok } from "../types";
 import { getStoredEmbeddingFingerprint } from "../vector/freshness";
 import { modelTableName } from "../vector/sqlite-vec";
+import {
+  deleteSavedCapsuleRegistration as deleteStoredSavedCapsuleRegistration,
+  getSavedCapsuleRegistration as getStoredSavedCapsuleRegistration,
+  getSavedCapsuleRegistrationSnapshot as getStoredSavedCapsuleRegistrationSnapshot,
+  getSavedCapsuleReverificationState as getStoredSavedCapsuleReverificationState,
+  getSavedCapsuleReverificationSequence as getStoredSavedCapsuleReverificationSequence,
+  listSavedCapsuleIdsAffectedByChanges as listStoredSavedCapsuleIdsAffectedByChanges,
+  listSavedCapsuleRegistrations as listStoredSavedCapsuleRegistrations,
+  setSavedCapsuleReverificationSequence as setStoredSavedCapsuleReverificationSequence,
+  upsertSavedCapsuleRegistration as upsertStoredSavedCapsuleRegistration,
+  upsertSavedCapsuleVerification as upsertStoredSavedCapsuleVerification,
+} from "./capsule-registry-store";
+import {
+  appendDocumentChange as appendStoredDocumentChange,
+  enforceDocumentChangeRetention as enforceStoredDocumentChangeRetention,
+  listDocumentChanges as listStoredDocumentChanges,
+  purgeDocumentChanges as purgeStoredDocumentChanges,
+  snapshotDocumentChange,
+} from "./change-journal-store";
 import { loadFts5Snowball } from "./fts5-snowball";
 import {
   appendExportManifest as appendStoredTraceExportManifest,
@@ -940,6 +972,12 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
       const uri = buildUri(doc.collection, doc.relPath);
 
       const transaction = db.transaction((): UpsertDocumentResult => {
+        const previousRow = db
+          .query<DbDocumentRow, [string, string]>(
+            "SELECT * FROM documents WHERE collection = ? AND rel_path = ?"
+          )
+          .get(doc.collection, doc.relPath);
+
         db.run(
           `
         INSERT INTO documents (
@@ -1030,6 +1068,41 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
           ]);
         }
 
+        if (doc.changeJournal !== false) {
+          const nextRow = db
+            .query<DbDocumentRow, [number]>(
+              "SELECT * FROM documents WHERE id = ?"
+            )
+            .get(idRow.id);
+          if (!nextRow) {
+            throw new Error("Failed to read document after upsert");
+          }
+          const previous = previousRow
+            ? snapshotDocumentChange(mapDocumentRow(previousRow))
+            : null;
+          const next = snapshotDocumentChange(mapDocumentRow(nextRow));
+          const kind: DocumentChangeKind | null =
+            previous === null
+              ? "create"
+              : !previous.active
+                ? "reactivate"
+                : previous.sourceHash !== next.sourceHash ||
+                    previous.mirrorHash !== next.mirrorHash
+                  ? "update"
+                  : null;
+          if (kind) {
+            appendStoredDocumentChange(db, {
+              documentId: idRow.id,
+              collection: doc.collection,
+              kind,
+              oldSnapshot: previous,
+              newSnapshot: next,
+              structureDelta: doc.changeJournal?.structureDelta,
+              observedAtMs: doc.changeJournal?.observedAtMs ?? Date.now(),
+            });
+          }
+        }
+
         return { id: idRow.id, docid };
       });
 
@@ -1043,6 +1116,82 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
     }
   }
 
+  async renameDocument(
+    collection: string,
+    oldRelPath: string,
+    newRelPath: string,
+    options: RenameDocumentOptions = {}
+  ): Promise<StoreResult<DocumentRow>> {
+    try {
+      if (!oldRelPath || !newRelPath) {
+        return err("INVALID_INPUT", "Rename paths must be non-empty");
+      }
+      const db = this.ensureOpen();
+      const transaction = db.transaction((): DocumentRow => {
+        const oldRow = db
+          .query<DbDocumentRow, [string, string]>(
+            "SELECT * FROM documents WHERE collection = ? AND rel_path = ?"
+          )
+          .get(collection, oldRelPath);
+        if (!oldRow) {
+          throw new Error("DOCUMENT_RENAME_NOT_FOUND");
+        }
+        if (oldRelPath === newRelPath) {
+          return mapDocumentRow(oldRow);
+        }
+
+        const newUri = buildUri(collection, newRelPath);
+        db.run(
+          `UPDATE documents
+           SET rel_path = ?, uri = ?, updated_at = datetime('now')
+           WHERE id = ?`,
+          [newRelPath, newUri, oldRow.id]
+        );
+        db.run("UPDATE documents_fts SET filepath = ? WHERE rowid = ?", [
+          newRelPath,
+          oldRow.id,
+        ]);
+        const nextRow = db
+          .query<DbDocumentRow, [number]>(
+            "SELECT * FROM documents WHERE id = ?"
+          )
+          .get(oldRow.id);
+        if (!nextRow) {
+          throw new Error("Failed to read document after rename");
+        }
+        const oldSnapshot = snapshotDocumentChange(mapDocumentRow(oldRow));
+        const nextDocument = mapDocumentRow(nextRow);
+        appendStoredDocumentChange(db, {
+          documentId: oldRow.id,
+          collection,
+          kind: "rename",
+          oldSnapshot,
+          newSnapshot: snapshotDocumentChange(nextDocument),
+          structureDelta: options.structureDelta,
+          observedAtMs: options.observedAtMs ?? Date.now(),
+        });
+        return nextDocument;
+      });
+
+      return ok(transaction());
+    } catch (cause) {
+      if (
+        cause instanceof Error &&
+        cause.message === "DOCUMENT_RENAME_NOT_FOUND"
+      ) {
+        return err(
+          "NOT_FOUND",
+          `Document not found for rename: ${collection}/${oldRelPath}`
+        );
+      }
+      return err(
+        "QUERY_FAILED",
+        cause instanceof Error ? cause.message : "Failed to rename document",
+        cause
+      );
+    }
+  }
+
   async getDocument(
     collection: string,
     relPath: string
@@ -1453,14 +1602,45 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
         return ok(0);
       }
 
-      const placeholders = relPaths.map(() => "?").join(",");
-      const result = db.run(
-        `UPDATE documents SET active = 0, updated_at = datetime('now')
-         WHERE collection = ? AND rel_path IN (${placeholders})`,
-        [collection, ...relPaths]
-      );
+      const uniquePaths = [...new Set(relPaths)];
+      const placeholders = uniquePaths.map(() => "?").join(",");
+      const transaction = db.transaction((): number => {
+        const activeRows = db
+          .query<DbDocumentRow, (string | number)[]>(
+            `SELECT *
+             FROM documents
+             WHERE collection = ?
+               AND active = 1
+               AND rel_path IN (${placeholders})
+             ORDER BY rel_path ASC, id ASC`
+          )
+          .all(collection, ...uniquePaths);
+        if (activeRows.length === 0) {
+          return 0;
+        }
+        const result = db.run(
+          `UPDATE documents SET active = 0, updated_at = datetime('now')
+           WHERE collection = ?
+             AND active = 1
+             AND rel_path IN (${placeholders})`,
+          [collection, ...uniquePaths]
+        );
+        const observedAtMs = Date.now();
+        for (const activeRow of activeRows) {
+          const previous = snapshotDocumentChange(mapDocumentRow(activeRow));
+          appendStoredDocumentChange(db, {
+            documentId: activeRow.id,
+            collection,
+            kind: "inactivate",
+            oldSnapshot: previous,
+            newSnapshot: { ...previous, active: false },
+            observedAtMs,
+          });
+        }
+        return result.changes;
+      });
 
-      return ok(result.changes);
+      return ok(transaction());
     } catch (cause) {
       return err(
         "QUERY_FAILED",
@@ -1472,6 +1652,110 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
     }
   }
 
+  async listDocumentChanges(
+    options: DocumentChangeListOptions = {}
+  ): Promise<StoreResult<DocumentChangePage>> {
+    return listStoredDocumentChanges(this.ensureOpen(), options);
+  }
+
+  async enforceDocumentChangeRetention(
+    policy: DocumentChangeRetentionPolicy,
+    nowMs: number
+  ): Promise<StoreResult<DocumentChangeRetentionResult>> {
+    return enforceStoredDocumentChangeRetention(
+      this.ensureOpen(),
+      policy,
+      nowMs
+    );
+  }
+
+  async purgeDocumentChanges(): Promise<
+    StoreResult<DocumentChangePurgeResult>
+  > {
+    return purgeStoredDocumentChanges(this.ensureOpen());
+  }
+
+  async upsertSavedCapsuleRegistration(
+    input: SavedCapsuleRegistrationInput
+  ): Promise<StoreResult<SavedCapsuleRegistrationRecord>> {
+    return upsertStoredSavedCapsuleRegistration(this.ensureOpen(), input);
+  }
+
+  async listSavedCapsuleRegistrations(): Promise<
+    StoreResult<SavedCapsuleRegistrationRecord[]>
+  > {
+    return listStoredSavedCapsuleRegistrations(this.ensureOpen());
+  }
+
+  async getSavedCapsuleRegistration(
+    registrationId: string
+  ): Promise<StoreResult<SavedCapsuleRegistrationRecord | null>> {
+    return getStoredSavedCapsuleRegistration(this.ensureOpen(), registrationId);
+  }
+
+  async getSavedCapsuleRegistrationSnapshot(
+    registrationId: string
+  ): Promise<StoreResult<SavedCapsuleRegistrationSnapshot | null>> {
+    return getStoredSavedCapsuleRegistrationSnapshot(
+      this.ensureOpen(),
+      registrationId
+    );
+  }
+
+  async deleteSavedCapsuleRegistration(
+    registrationId: string
+  ): Promise<StoreResult<boolean>> {
+    return deleteStoredSavedCapsuleRegistration(
+      this.ensureOpen(),
+      registrationId
+    );
+  }
+
+  async listSavedCapsuleIdsAffectedByChanges(
+    afterSequence: number,
+    throughSequence: number,
+    limit: number
+  ): Promise<StoreResult<{ registrationIds: string[]; truncated: boolean }>> {
+    return listStoredSavedCapsuleIdsAffectedByChanges(
+      this.ensureOpen(),
+      afterSequence,
+      throughSequence,
+      limit
+    );
+  }
+
+  async upsertSavedCapsuleVerification(
+    verification: SavedCapsuleVerificationRecord,
+    expectedRegistration: SavedCapsuleVerificationExpectation
+  ): Promise<StoreResult<boolean>> {
+    return upsertStoredSavedCapsuleVerification(
+      this.ensureOpen(),
+      verification,
+      expectedRegistration
+    );
+  }
+
+  async getSavedCapsuleReverificationSequence(): Promise<StoreResult<number>> {
+    return getStoredSavedCapsuleReverificationSequence(this.ensureOpen());
+  }
+
+  async getSavedCapsuleReverificationState(): Promise<
+    StoreResult<SavedCapsuleReverificationState>
+  > {
+    return getStoredSavedCapsuleReverificationState(this.ensureOpen());
+  }
+
+  async setSavedCapsuleReverificationSequence(
+    sequence: number,
+    expectedRegistrationEpoch: number
+  ): Promise<StoreResult<boolean>> {
+    return setStoredSavedCapsuleReverificationSequence(
+      this.ensureOpen(),
+      sequence,
+      expectedRegistrationEpoch
+    );
+  }
+
   // ─────────────────────────────────────────────────────────────────────────
   // Content
   // ─────────────────────────────────────────────────────────────────────────