@gmickel/gno 1.20.0 → 1.22.0

package/src/store/index.ts

@@ -33,6 +33,16 @@ export type {
   CollectionRow,
   CollectionStatus,
   ContextRow,
+  DocumentChangeDateDelta,
+  DocumentChangeKind,
+  DocumentChangeListOptions,
+  DocumentChangePage,
+  DocumentChangePurgeResult,
+  DocumentChangeRetentionPolicy,
+  DocumentChangeRetentionResult,
+  DocumentChangeRow,
+  DocumentChangeSet,
+  DocumentChangeStructureDelta,
   DocumentInput,
   DocumentRow,
   FtsResult,
@@ -72,6 +82,17 @@ export type {
   RetrievalTraceRunRow,
   RetrievalTraceStatus,
   RetrievalTraceTerminalStatus,
+  RenameDocumentOptions,
+  SavedCapsuleAffectedQuestionState,
+  SavedCapsuleEvidenceReference,
+  SavedCapsuleNotificationPreference,
+  SavedCapsuleOperationStatus,
+  SavedCapsuleRegistration,
+  SavedCapsuleRegistrationInput,
+  SavedCapsuleRegistrationRecord,
+  SavedCapsuleReverificationState,
+  SavedCapsuleTriggerKind,
+  SavedCapsuleVerificationRecord,
   StoreError,
   StoreErrorCode,
   StorePort,

package/src/store/migrations/015-document-change-journal.ts

@@ -0,0 +1,85 @@
+/**
+ * Migration: bounded, metadata-only document change journal.
+ *
+ * The journal intentionally stores document identity, hashes, active state,
+ * and compact structural summaries. Source and converted document bodies are
+ * never copied into this table.
+ *
+ * @module src/store/migrations/015-document-change-journal
+ */
+
+import type { Database } from "bun:sqlite";
+
+import type { Migration } from "./runner";
+
+export const migration: Migration = {
+  version: 15,
+  name: "document_change_journal",
+
+  up(db: Database): void {
+    db.exec(`
+      CREATE TABLE document_changes (
+        sequence INTEGER PRIMARY KEY AUTOINCREMENT,
+        document_id INTEGER NOT NULL CHECK (document_id > 0),
+        collection TEXT NOT NULL,
+        change_kind TEXT NOT NULL
+          CHECK (change_kind IN ('create', 'update', 'rename', 'inactivate', 'reactivate')),
+        old_rel_path TEXT,
+        new_rel_path TEXT,
+        old_docid TEXT,
+        new_docid TEXT,
+        old_uri TEXT,
+        new_uri TEXT,
+        old_source_hash TEXT,
+        new_source_hash TEXT,
+        old_mirror_hash TEXT,
+        new_mirror_hash TEXT,
+        old_active INTEGER CHECK (old_active IS NULL OR old_active IN (0, 1)),
+        new_active INTEGER CHECK (new_active IS NULL OR new_active IN (0, 1)),
+        heading_delta_json TEXT NOT NULL DEFAULT '{"added":[],"removed":[]}',
+        link_delta_json TEXT NOT NULL DEFAULT '{"added":[],"removed":[]}',
+        typed_edge_delta_json TEXT NOT NULL DEFAULT '{"added":[],"removed":[]}',
+        date_delta_json TEXT NOT NULL DEFAULT '{"added":[],"removed":[],"changed":[]}',
+        structure_truncated INTEGER NOT NULL DEFAULT 0
+          CHECK (structure_truncated IN (0, 1)),
+        observed_at_ms INTEGER NOT NULL CHECK (observed_at_ms >= 0),
+        byte_size INTEGER NOT NULL CHECK (byte_size > 0 AND byte_size <= 131072),
+        CHECK (length(CAST(collection AS BLOB)) BETWEEN 1 AND 256),
+        CHECK (old_rel_path IS NULL OR length(CAST(old_rel_path AS BLOB)) BETWEEN 1 AND 4096),
+        CHECK (new_rel_path IS NULL OR length(CAST(new_rel_path AS BLOB)) BETWEEN 1 AND 4096),
+        CHECK (old_docid IS NULL OR length(CAST(old_docid AS BLOB)) BETWEEN 1 AND 256),
+        CHECK (new_docid IS NULL OR length(CAST(new_docid AS BLOB)) BETWEEN 1 AND 256),
+        CHECK (old_uri IS NULL OR length(CAST(old_uri AS BLOB)) BETWEEN 1 AND 8192),
+        CHECK (new_uri IS NULL OR length(CAST(new_uri AS BLOB)) BETWEEN 1 AND 8192),
+        CHECK (old_source_hash IS NULL OR length(CAST(old_source_hash AS BLOB)) BETWEEN 1 AND 256),
+        CHECK (new_source_hash IS NULL OR length(CAST(new_source_hash AS BLOB)) BETWEEN 1 AND 256),
+        CHECK (old_mirror_hash IS NULL OR length(CAST(old_mirror_hash AS BLOB)) BETWEEN 1 AND 256),
+        CHECK (new_mirror_hash IS NULL OR length(CAST(new_mirror_hash AS BLOB)) BETWEEN 1 AND 256),
+        CHECK (length(CAST(heading_delta_json AS BLOB)) <= 16384),
+        CHECK (length(CAST(link_delta_json AS BLOB)) <= 16384),
+        CHECK (length(CAST(typed_edge_delta_json AS BLOB)) <= 16384),
+        CHECK (length(CAST(date_delta_json AS BLOB)) <= 16384)
+      );
+
+      CREATE INDEX idx_document_changes_collection_sequence
+      ON document_changes(collection, sequence);
+
+      CREATE INDEX idx_document_changes_document_sequence
+      ON document_changes(document_id, sequence);
+
+      CREATE INDEX idx_document_changes_retention
+      ON document_changes(observed_at_ms, sequence);
+
+      CREATE TABLE document_change_journal_state (
+        singleton_id INTEGER PRIMARY KEY CHECK (singleton_id = 1),
+        last_sequence INTEGER NOT NULL DEFAULT 0 CHECK (last_sequence >= 0),
+        retention_floor INTEGER NOT NULL DEFAULT 0
+          CHECK (retention_floor >= 0 AND retention_floor <= last_sequence)
+      );
+
+      INSERT INTO document_change_journal_state (
+        singleton_id, last_sequence, retention_floor
+      ) VALUES (1, 0, 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,
 ];