@openparachute/vault 0.7.9-rc.4 → 0.7.9-rc.5

package/core/src/mcp.ts

@@ -184,7 +184,7 @@ function requireNoteReference(value: unknown): string {
  * match required. Same [[wikilink]] semantics as `resolveWikilink`; exact
  * id/path always wins first.
  */
-function resolveNote(db: Database, idOrPath: string): Note | null {
+export function resolveNote(db: Database, idOrPath: string): Note | null {
   // Try ID match first (fast, indexed)
   const byId = noteOps.getNote(db, idOrPath);
   if (byId) return byId;
@@ -692,6 +692,24 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
         // stays byte-identical to the no-pagination behavior.
         const contentRange = parseContentRange(params.content_offset, params.content_length);
 
+        if (params.versions) {
+          for (const key of ["search", "near", "cursor", "aggregate", "semantic", "id"] as const) {
+            if (params[key] !== undefined) throw new QueryError(`versions is incompatible with ${key}`, "INVALID_QUERY", {
+              error_type: "invalid_query", field: "versions", hint: `drop ${key} when using versions`,
+            });
+          }
+          const v = params.versions as { note_id: string; version_ix?: number; limit?: number; offset?: number };
+          const note = requireNote(db, requireNoteReference(v.note_id));
+          if (typeof v.version_ix === "number") {
+            const version = await store.getNoteVersion(note.id, v.version_ix);
+            if (!version) return { error: `Version not found: "${v.note_id}"@${v.version_ix}`, error_type: "not_found", id: v.note_id, version_ix: v.version_ix };
+            return version;
+          }
+          const versions = await store.listNoteVersions(note.id, { limit: Math.max(0, Math.min(v.limit ?? 50, 200)), offset: v.offset ?? 0 });
+          const total = await store.countNoteVersions(note.id);
+          return { versions, total };
+        }
+
         // --- Single note by ID/path ---
         if (params.id) {
           const note = resolveNote(db, params.id as string);
@@ -2280,7 +2298,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
       name: "delete-note",
       execute: async (params) => {
         const note = requireNote(db, requireNoteReference(params.id));
-        await store.deleteNote(note.id);
+        await store.deleteNote(note.id, { actor: writeActor, via: writeVia });
         return { deleted: true, id: note.id };
       },
     },
@@ -2494,7 +2512,7 @@ export function generateMcpTools(store: Store, opts?: GenerateMcpToolsOpts): Mcp
             field: "new_name",
           });
         }
-        const result = await store.renameTag(oldName, newName);
+        const result = await store.renameTag(oldName, newName, { actor: writeActor ?? undefined, via: writeVia ?? undefined });
         if ("error" in result) {
           if (result.error === "not_found") {
             throw structuredError(`rename-tag: tag "${oldName}" not found`, {

package/core/src/notes.ts

@@ -31,6 +31,7 @@ import {
   type SearchMode,
 } from "./search-query.js";
 import { generateUlid } from "./ulid.js";
+import { captureVersion, readPriorNoteRow, DEFAULT_HISTORY_POLICY, type HistoryPolicy } from "./history.js";
 
 /**
  * Write-attribution context (vault#298) — the two axes of provenance threaded
@@ -2390,7 +2391,7 @@ export type RenameTagResult =
  * (the store wrapper) bust both `_tagHierarchy` and `_schemaConfig`
  * after the cascade returns.
  */
-export function renameTag(db: Database, oldName: string, newName: string): RenameTagResult {
+export function renameTag(db: Database, oldName: string, newName: string, attr?: { actor?: string | null; via?: string | null }, policy: HistoryPolicy = DEFAULT_HISTORY_POLICY): RenameTagResult {
   // Normalize the TARGET so a rename can never create a `#`-prefixed tag. The
   // SOURCE (`oldName`) is left LITERAL on purpose — it's the transitional escape
   // hatch that lets the `#legacy/*` → `legacy/*` data migration find the
@@ -2590,6 +2591,8 @@ export function renameTag(db: Database, oldName: string, newName: string): Renam
       for (const row of candidates) {
         const next = rewriteNoteBody(row.content, renames);
         if (next === row.content) continue;
+        const prior = readPriorNoteRow(db, row.id);
+        if (prior) captureVersion(db, prior, { actor: attr?.actor ?? null, via: attr?.via ?? null, op: "tag-rename", policy });
         updateStmt.run(next, now, nowMs, row.id);
         notesRewritten++;
       }
@@ -2612,6 +2615,8 @@ export function renameTag(db: Database, oldName: string, newName: string): Renam
       for (const row of candidates) {
         const next = rewriteTagConfigPath(row.path, renames);
         if (next === row.path) continue;
+        const prior = readPriorNoteRow(db, row.id);
+        if (prior) captureVersion(db, prior, { actor: attr?.actor ?? null, via: attr?.via ?? null, op: "tag-rename", policy });
         updateStmt.run(next, now, nowMs, row.id);
         pathsRenamed++;
       }

package/core/src/portable-md.ts

@@ -1961,7 +1961,7 @@ async function importVaultReplay(
       const batch = await store.queryNotes({ sort: "asc", limit: EXPORT_BATCH_SIZE });
       if (batch.length === 0) break;
       for (const note of batch) {
-        await store.deleteNote(note.id);
+        await store.deleteNote(note.id, { captureHistory: false });
         stats.notes_wiped++;
       }
     }

package/core/src/schema-v29-note-versions.test.ts

@@ -0,0 +1,63 @@
+import { it, expect, beforeEach, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { initSchema } from "./schema.js";
+import { BunSqliteStore } from "./store.js";
+let db: Database;
+beforeEach(() => {
+  db = new Database(":memory:");
+  initSchema(db);
+});
+afterEach(() => db.close());
+function dropHistory() {
+  db.exec(
+    "DROP TABLE IF EXISTS note_versions; DROP TABLE IF EXISTS note_blobs;",
+  );
+}
+it("P14a v28 upgrade creates both tables and three indexes without backfill", () => {
+  dropHistory();
+  db.prepare("UPDATE schema_version SET version=28").run();
+  initSchema(db);
+  expect(
+    db.prepare("SELECT MAX(version) AS version FROM schema_version").get(),
+  ).toEqual({ version: 30 });
+  const tables = db
+    .prepare(
+      "SELECT name FROM sqlite_master WHERE type='table' AND name IN ('note_versions','note_blobs') ORDER BY name",
+    )
+    .all();
+  expect(tables).toEqual([{ name: "note_blobs" }, { name: "note_versions" }]);
+  expect(
+    db
+      .prepare(
+        "SELECT name FROM sqlite_master WHERE type='index' AND name IN ('idx_note_versions_note','idx_note_versions_hash','idx_note_versions_superseded')",
+      )
+      .all(),
+  ).toHaveLength(3);
+  expect(db.prepare("SELECT COUNT(*) AS n FROM note_versions").get()).toEqual({
+    n: 0,
+  });
+});
+it("P14b repeated init is idempotent", () => {
+  initSchema(db);
+  initSchema(db);
+  expect(db.prepare("SELECT COUNT(*) AS n FROM note_versions").get()).toEqual({
+    n: 0,
+  });
+});
+it("P14c rerunning the v29 migration preserves captured rows", async () => {
+  const store = new BunSqliteStore(db);
+  const n = await store.createNote("a");
+  await store.updateNote(n.id, { content: "b" });
+  db.prepare("UPDATE schema_version SET version=28").run();
+  initSchema(db);
+  expect((await store.getNoteVersion(n.id, 0))!.content).toBe("a");
+});
+it("P14d missing tables before the first capture degrade to no history", async () => {
+  const store = new BunSqliteStore(db);
+  const n = await store.createNote("a");
+  // Drop before this handle has probed true. A drop after capture is an
+  // accepted throw because historyTablesPresent memoises true per handle.
+  dropHistory();
+  await store.updateNote(n.id, { content: "b" });
+  expect((await store.getNote(n.id))!.content).toBe("b");
+});

package/core/src/schema-v30-note-deltas.test.ts

@@ -0,0 +1,51 @@
+import { test, expect } from "bun:test";
+import { Database } from "bun:sqlite";
+import { BunSqliteStore } from "./store.js";
+import { initSchema, SCHEMA_VERSION } from "./schema.js";
+test("P12 v29 opens losslessly, fresh and upgraded columns/indexes agree", async () => {
+  const db = new Database(":memory:"), fresh = new Database(":memory:");
+  try {
+    const store = new BunSqliteStore(db);
+    const a = await store.createNote("one"), b = await store.createNote("other");
+    await store.updateNote(a.id, { content: "two" });
+    await store.updateNote(a.id, { content: "three" });
+    await store.deleteNote(a.id);
+    await store.updateNote(b.id, { content: "changed" });
+    // Remove only v30 additions to recreate the actual v29 table shape.
+    db.exec("DROP INDEX IF EXISTS idx_note_blobs_delta_of");
+    const cols = (table: string) => db.prepare(`PRAGMA table_info(${table})`).all() as {
+      name: string;
+    }[];
+    if (cols("note_blobs").some(c => c.name === "delta_of"))
+      db.exec("ALTER TABLE note_blobs DROP COLUMN delta_of");
+    if (cols("note_blobs").some(c => c.name === "encoding"))
+      db.exec("ALTER TABLE note_blobs DROP COLUMN encoding");
+    if (cols("note_versions").some(c => c.name === "created_at"))
+      db.exec("ALTER TABLE note_versions DROP COLUMN created_at");
+    db.exec("UPDATE schema_version SET version=29");
+    const snap = () => ({ blobs: db.prepare("SELECT hash,content,byte_size FROM note_blobs ORDER BY hash").all(), versions: db.prepare("SELECT note_id,version_ix,content_hash,path,metadata,extension,superseded_at,actor,via,op,content_len,encoding FROM note_versions ORDER BY note_id,version_ix").all() });
+    const before = snap();
+    expect(() => initSchema(db)).not.toThrow();
+    expect(SCHEMA_VERSION).toBe(30);
+    expect(snap()).toEqual(before);
+    expect(db.prepare("SELECT hash FROM note_blobs WHERE delta_of IS NOT NULL OR encoding IS NOT NULL").all()).toEqual([]);
+    expect(db.prepare("SELECT note_id FROM note_versions WHERE created_at IS NOT NULL").all()).toEqual([]);
+    initSchema(fresh);
+    for (const table of ["note_blobs", "note_versions"]) {
+      expect(cols(table).map(c => c.name).sort()).toEqual((fresh.prepare(`PRAGMA table_info(${table})`).all() as {
+        name: string;
+      }[]).map(c => c.name).sort());
+    }
+    for (const handle of [db, fresh])
+      expect(handle.prepare("SELECT name FROM sqlite_master WHERE name='idx_note_blobs_delta_of'").get()).not.toBeNull();
+    expect(db.prepare("PRAGMA integrity_check").get()).toEqual({ integrity_check: "ok" });
+    expect(db.prepare("PRAGMA foreign_key_check").all()).toEqual([]);
+    initSchema(db);
+    expect(snap()).toEqual(before);
+    expect(() => db.exec("UPDATE note_blobs SET delta_of='nosuchhash'")).toThrow("FOREIGN KEY");
+  }
+  finally {
+    db.close();
+    fresh.close();
+  }
+});

package/core/src/schema.ts

@@ -6,7 +6,7 @@ import { transaction } from "./txn.js";
 import { timestampToMs } from "./cursor.js";
 import { ensureRelationshipColumn } from "./wikilinks.js";
 
-export const SCHEMA_VERSION = 28;
+export const SCHEMA_VERSION = 30;
 
 /**
  * Deterministic last-resort epoch for a note whose `updated_at` AND
@@ -142,6 +142,114 @@ CREATE TABLE IF NOT EXISTS note_vectors (
 -- sweep (a model <> ? scan) the backfill/drain use to find pending work.
 CREATE INDEX IF NOT EXISTS idx_note_vectors_stale ON note_vectors(model, content_hash);
 
+-- note_blobs + note_versions (v29, vault#524): note-level version history.
+--
+-- STORAGE. A version row is skinny; the BODY lives once per distinct content,
+-- keyed by its sha256, in note_blobs. A metadata-only edit on a 116 KB note
+-- costs one ~300-byte version row and a no-op \`INSERT OR IGNORE\` on the blob —
+-- the whole answer to "does every little update store an entirely new copy?"
+-- Live \`notes.content\` stays on \`notes\`: no join on the hot read path.
+--
+-- encoding IS NULL FOR EVERY ORDINARY ROW IN v29. NULL means "content_hash
+-- names a WHOLE blob". It exists so the PR-2 compactor can rewrite an old row
+-- to reference a delta (setting a format marker) with no second migration and
+-- no version-id change. The ONE non-NULL value v29 ever writes is the literal
+-- 'overflow', on a delete tombstone for a note whose body exceeded
+-- VERSION_MAX_BYTES: the row records that the note WAS deleted and how big it
+-- was, with content_hash NULL because the bytes were never blobbed. A delete
+-- must never be blocked by history (see history.ts captureVersion step 5).
+-- A restore marker copied from that tombstone also retains overflow encoding
+-- and a NULL hash, including after the note has been recreated.
+--
+-- content_hash IS NULLABLE, and it is nullable ONLY for that overflow
+-- tombstone or its copied restore marker. Every consumer must filter NULL —
+-- in particular gcBlobs's \`NOT IN (SELECT content_hash ...)\` MUST carry
+-- \`WHERE content_hash IS NOT NULL\`, or one NULL in the subquery makes the
+-- whole NOT IN evaluate to NULL and the sweep silently deletes nothing.
+--
+-- NO \`REFERENCES notes(id) ON DELETE CASCADE\` — the one deviation from
+-- note_vectors above, deliberate. deleteNote writes a final op='delete' row and
+-- the \`notes\` row then goes away; a cascade would delete the only surviving
+-- copy at the instant it became the only copy. Deleted-note history is reaped
+-- by the configurable sweep (history.deleted_retention_days) or an explicit
+-- erase, never by the FK.
+--
+-- content_hash DOES have a real FK to note_blobs with the default NO ACTION,
+-- so SQLite itself enforces the one invariant refcount GC protects: deleting a
+-- still-referenced blob raises instead of silently orphaning a version.
+-- foreign_keys is turned ON per connection in applyConnectionPragmas
+-- (schema.ts:486) — but inside a SWALLOWING try/catch, so on a handle where
+-- the pragma throws there is no FK enforcement at all and no signal. The
+-- NOT EXISTS guard on every blob delete is therefore the PRIMARY defence and
+-- the FK is the backstop, not the other way round (§4.6).
+-- note_blobs.encoding IS NULL  -> \`content\` is the literal body, \`byte_size\`
+--   is its UTF-8 byte length, and \`hash\` = sha256(content). This is every row
+--   v29 ever wrote.
+-- note_blobs.encoding = 'fossil-delta' -> \`content\` is the BASE64 of a Fossil
+--   delta that reconstructs this row's logical body from the body of the blob
+--   named by \`delta_of\`; \`byte_size\` is the length of that base64 payload, i.e.
+--   the bytes actually stored. \`hash\` is STILL sha256 of the LOGICAL body, so
+--   every note_versions.content_hash reference and its FK stay valid and
+--   content-addressed identity is never a delta hash (ClaudeJi R3).
+--   The LOGICAL byte length is note_versions.content_len, which PR 1
+--   denormalised for exactly this moment (PR 1 §2.1: "it must stay readable
+--   after PR 2 deltifies the blob").
+-- ANY OTHER \`encoding\` VALUE IS CORRUPTION. It is not a future format marker to
+--   be tolerated: a read of such a row answers 409 (materialise's
+--   "unknown_encoding" branch) and the doctor counts it (historyStorageStats's
+--   unknown_encoding_blobs). A later format adds its value here AND to both.
+--
+-- DEPTH IS EXACTLY ONE, AND THAT IS AN INVARIANT, NOT A TUNING CHOICE.
+--   delta_of MUST name a row whose \`encoding IS NULL\`. A delta is never the
+--   base of another delta. Rebuilding any version is therefore ONE applyDelta,
+--   measured p95 3.73 ms / p99 4.68 ms on a 116 KB note, against 38.98 ms /
+--   49.99 ms for a 24-link chain on the same note -- the chain sits ON the
+--   50 ms budget with no headroom. Star also confines corruption: a damaged
+--   delta loses one version, not every older one. See §11.1 D1.
+--
+-- delta_of carries a REAL self-referential FK with the default NO ACTION, and
+-- it IS enforced on a bun handle (probe E: deleting a referenced base raises
+-- FOREIGN KEY constraint failed). It is the backstop; the NOT EXISTS guards in
+-- pruneVersions and gcBlobs are the primary defence, exactly as for
+-- content_hash in v29 (PR 1 §4.6).
+--
+-- note_versions.created_at (#735) is the captured note's OWN creation time,
+-- copied from notes.created_at at capture. NULL on every pre-v30 row; a
+-- deleted-note restore falls back to the tombstone's superseded_at when it is
+-- NULL, which is precisely v29's behaviour.
+CREATE TABLE IF NOT EXISTS note_blobs (
+  hash       TEXT PRIMARY KEY,
+  content    TEXT NOT NULL,
+  byte_size  INTEGER NOT NULL,
+  encoding TEXT,
+  delta_of TEXT REFERENCES note_blobs(hash)
+);
+
+CREATE TABLE IF NOT EXISTS note_versions (
+  note_id       TEXT NOT NULL,
+  version_ix    INTEGER NOT NULL,
+  content_hash  TEXT REFERENCES note_blobs(hash),
+  path          TEXT,
+  metadata      TEXT,
+  extension     TEXT,
+  superseded_at TEXT NOT NULL,
+  actor         TEXT,
+  via           TEXT,
+  op            TEXT NOT NULL,
+  content_len   INTEGER NOT NULL,
+  encoding      TEXT,
+  created_at    TEXT,
+  PRIMARY KEY (note_id, version_ix)
+);
+-- list/get (newest first) + the prune walk.
+CREATE INDEX IF NOT EXISTS idx_note_versions_note ON note_versions(note_id, version_ix DESC);
+-- the age half of retention + the deleted-note sweep.
+CREATE INDEX IF NOT EXISTS idx_note_versions_superseded ON note_versions(superseded_at);
+-- refcount GC: "is any version still pointing at this blob?" This index is
+-- what keeps gcBlobs's per-vault-open anti-join off a full table scan; the
+-- boot sweep runs it on an opted-in vault's open path (§4.6).
+CREATE INDEX IF NOT EXISTS idx_note_versions_hash ON note_versions(content_hash);
+
 -- tag_schemas (v6) was retired in v14; description + fields lifted onto the
 -- tags row directly. The CREATE TABLE was removed from SCHEMA_SQL after the
 -- v14 data migration drops the table; existing v6+ vaults pick up the
@@ -629,6 +737,11 @@ export function initSchema(db: Database): void {
   // queued an unresolved link, and does not rewrite notes.
   migrateToV28(db);
 
+  // v29: note-level history, no backfill.
+  migrateToV29(db);
+  // v30: depth-one history deltas and captured creation time, no backfill.
+  migrateToV30(db);
+
   // Rebuild any generated columns + indexes declared in indexed_fields.
   // No-op for a fresh vault; idempotent on existing vaults.
   rebuildIndexes(db);
@@ -1756,6 +1869,94 @@ function migrateToV28(db: Database): void {
   ensureRelationshipColumn(db);
 }
 
+/** Add history tables and indexes without moving existing note data. */
+function migrateToV29(db: Database): void {
+  transaction(db, () => {
+    db.exec(`
+-- note_blobs + note_versions (v29, vault#524): note-level version history.
+--
+-- STORAGE. A version row is skinny; the BODY lives once per distinct content,
+-- keyed by its sha256, in note_blobs. A metadata-only edit on a 116 KB note
+-- costs one ~300-byte version row and a no-op \`INSERT OR IGNORE\` on the blob —
+-- the whole answer to "does every little update store an entirely new copy?"
+-- Live \`notes.content\` stays on \`notes\`: no join on the hot read path.
+--
+-- encoding IS NULL FOR EVERY ORDINARY ROW IN v29. NULL means "content_hash
+-- names a WHOLE blob". It exists so the PR-2 compactor can rewrite an old row
+-- to reference a delta (setting a format marker) with no second migration and
+-- no version-id change. The ONE non-NULL value v29 ever writes is the literal
+-- 'overflow', on a delete tombstone for a note whose body exceeded
+-- VERSION_MAX_BYTES: the row records that the note WAS deleted and how big it
+-- was, with content_hash NULL because the bytes were never blobbed. A delete
+-- must never be blocked by history (see history.ts captureVersion step 5).
+-- A restore marker copied from that tombstone also retains overflow encoding
+-- and a NULL hash, including after the note has been recreated.
+--
+-- content_hash IS NULLABLE, and it is nullable ONLY for that overflow
+-- tombstone or its copied restore marker. Every consumer must filter NULL —
+-- in particular gcBlobs's \`NOT IN (SELECT content_hash ...)\` MUST carry
+-- \`WHERE content_hash IS NOT NULL\`, or one NULL in the subquery makes the
+-- whole NOT IN evaluate to NULL and the sweep silently deletes nothing.
+--
+-- NO \`REFERENCES notes(id) ON DELETE CASCADE\` — the one deviation from
+-- note_vectors above, deliberate. deleteNote writes a final op='delete' row and
+-- the \`notes\` row then goes away; a cascade would delete the only surviving
+-- copy at the instant it became the only copy. Deleted-note history is reaped
+-- by the configurable sweep (history.deleted_retention_days) or an explicit
+-- erase, never by the FK.
+--
+-- content_hash DOES have a real FK to note_blobs with the default NO ACTION,
+-- so SQLite itself enforces the one invariant refcount GC protects: deleting a
+-- still-referenced blob raises instead of silently orphaning a version.
+-- foreign_keys is turned ON per connection in applyConnectionPragmas
+-- (schema.ts:486) — but inside a SWALLOWING try/catch, so on a handle where
+-- the pragma throws there is no FK enforcement at all and no signal. The
+-- NOT EXISTS guard on every blob delete is therefore the PRIMARY defence and
+-- the FK is the backstop, not the other way round (§4.6).
+CREATE TABLE IF NOT EXISTS note_blobs (
+  hash       TEXT PRIMARY KEY,
+  content    TEXT NOT NULL,
+  byte_size  INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS note_versions (
+  note_id       TEXT NOT NULL,
+  version_ix    INTEGER NOT NULL,
+  content_hash  TEXT REFERENCES note_blobs(hash),
+  path          TEXT,
+  metadata      TEXT,
+  extension     TEXT,
+  superseded_at TEXT NOT NULL,
+  actor         TEXT,
+  via           TEXT,
+  op            TEXT NOT NULL,
+  content_len   INTEGER NOT NULL,
+  encoding      TEXT,
+  PRIMARY KEY (note_id, version_ix)
+);
+-- list/get (newest first) + the prune walk.
+CREATE INDEX IF NOT EXISTS idx_note_versions_note ON note_versions(note_id, version_ix DESC);
+-- the age half of retention + the deleted-note sweep.
+CREATE INDEX IF NOT EXISTS idx_note_versions_superseded ON note_versions(superseded_at);
+-- refcount GC: "is any version still pointing at this blob?" This index is
+-- what keeps gcBlobs's per-vault-open anti-join off a full table scan; the
+-- boot sweep runs it on an opted-in vault's open path (§4.6).
+CREATE INDEX IF NOT EXISTS idx_note_versions_hash ON note_versions(content_hash);
+    `);
+  });
+}
+
+/** Add delta representation and creation time without moving prior rows. */
+function migrateToV30(db: Database): void {
+  transaction(db, () => {
+    if (hasTable(db, "note_blobs") && !hasColumn(db, "note_blobs", "encoding")) db.exec("ALTER TABLE note_blobs ADD COLUMN encoding TEXT");
+    if (hasTable(db, "note_blobs") && !hasColumn(db, "note_blobs", "delta_of")) db.exec("ALTER TABLE note_blobs ADD COLUMN delta_of TEXT REFERENCES note_blobs(hash)");
+    if (hasTable(db, "note_versions") && !hasColumn(db, "note_versions", "created_at")) db.exec("ALTER TABLE note_versions ADD COLUMN created_at TEXT");
+    // SCHEMA_SQL runs before migrations: the index must be created here.
+    db.exec("CREATE INDEX IF NOT EXISTS idx_note_blobs_delta_of ON note_blobs(delta_of)");
+  });
+}
+
 function hasTable(db: Database, name: string): boolean {
   const row = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name=?").get(name);
   return !!row;

package/core/src/store.ts

@@ -1,5 +1,6 @@
 import { Database } from "bun:sqlite";
 import type { Store, Note, Link, Attachment, QueryOpts, QueryNotesPage, AggregateRow, SemanticSearchResult } from "./types.js";
+import { compactNote, compactVault, countNoteVersions, type CompactResult, type CompactSummary, captureVersion, readPriorNoteRow, resolveHistoryPolicy, appendRestoreMarker, listVersions, getVersion, latestTombstone, eraseHistory, sweepDeletedHistory, deletedHistoryStats, HistoryNotFoundError, HistoryOverflowError, HistoryUnrecoverableError, DEFAULT_HISTORY_POLICY, VERSION_MAX_BYTES, type VersionRow, type HistoryPolicy, type HistoryOp } from "./history.js";
 import { initSchema } from "./schema.js";
 import * as noteOps from "./notes.js";
 import * as linkOps from "./links.js";
@@ -98,6 +99,7 @@ function setsEqual(a: Set<string>, b: Set<string>): boolean {
  */
 export class BunSqliteStore implements Store {
   public readonly hooks: HookRegistry;
+  private readonly historyPolicy: HistoryPolicy;
 
   // Lazy-built caches over the post-v14 `tags` table — hierarchy via
   // parent_names, schema validation via `fields`. Null means "not yet
@@ -133,9 +135,10 @@ export class BunSqliteStore implements Store {
 
   constructor(
     public readonly db: Database,
-    opts?: { hooks?: HookRegistry; embeddingProvider?: EmbeddingProvider; embeddingDisabledReason?: string },
+    opts?: { history?: Partial<HistoryPolicy>; hooks?: HookRegistry; embeddingProvider?: EmbeddingProvider; embeddingDisabledReason?: string },
   ) {
     initSchema(db);
+    this.historyPolicy = resolveHistoryPolicy(opts?.history);
     this.hooks = opts?.hooks ?? new HookRegistry();
     this.embeddingProvider = opts?.embeddingProvider;
     this.embeddingDisabledReason = opts?.embeddingDisabledReason;
@@ -574,6 +577,27 @@ export class BunSqliteStore implements Store {
       metadata?: Record<string, unknown>;
       created_at?: string;
       skipUpdatedAt?: boolean;
+      /**
+       * State-transition compare-and-set (vault#299 Part B). DECLARED here as
+       * of vault#524 — it always arrived at runtime (src/routes.ts:3214 sets
+       * it on a `const updates: any = {}` at :3167 and passes it at :3257, and
+       * noteOps.updateNote has read it at notes.ts:708 since #299) but it was
+       * never on the declared type, so an object LITERAL carrying it did not
+       * compile. Declaring it is what lets a core test construct the shape
+       * directly (P1, P11b) instead of laundering it through `any`.
+       */
+      state_transition?: { field: string; from: unknown; to: unknown };
+      /**
+       * INTERNAL — the `op` stamped on the version row this write captures
+       * (vault#524). Set ONLY by Store.restoreNoteVersion, to "restore".
+       * noteOps.updateNote ignores it (it reads named fields, never
+       * Object.keys), so it never reaches SQL. Do NOT accept it from REST or
+       * MCP: src/routes.ts's PATCH handler builds `updates` field by field and
+       * must not copy it out of the request body, and core/src/mcp.ts's
+       * update-note executor must not either. §10.24 pins that.
+       */
+      historyOp?: HistoryOp;
+
       // Write-attribution (vault#298) — principal + interface of this edit.
       actor?: string | null;
       via?: string | null;
@@ -633,6 +657,10 @@ export class BunSqliteStore implements Store {
     // atomic unit. Any later failure must leave the note and its indexes at
     // the pre-update state rather than committing only the first SQL write.
     const note = this.transaction(() => {
+      if (willWriteNoteRow(updates)) {
+        const prior = readPriorNoteRow(this.db, id);
+        if (prior) captureVersion(this.db, prior, { actor: updates.actor ?? null, via: updates.via ?? null, op: historyOpFor(updates), policy: this.historyPolicy });
+      }
       const note = noteOps.updateNote(this.db, id, updates);
 
       // Wikilink sync runs against the *resulting* content. For append/prepend
@@ -644,7 +672,7 @@ export class BunSqliteStore implements Store {
 
       if (updates.path !== undefined && note.path) {
         if (cascadePlan && oldPath && oldPath !== note.path) {
-          this.cascadeRename(cascadePlan, note, oldPath);
+          this.cascadeRename(cascadePlan, note, oldPath, { actor: updates.actor ?? null, via: updates.via ?? null });
         }
         resolveUnresolvedWikilinks(this.db, note.path, id);
         // vault#581 — a rename is one of the two ways an ambiguity stops being
@@ -747,7 +775,7 @@ export class BunSqliteStore implements Store {
    * `unresolved_wikilinks` and `ambiguous_wikilinks` stay consistent with
    * the new text.
    */
-  private cascadeRename(plan: Map<string, string[]>, note: Note, oldPath: string): void {
+  private cascadeRename(plan: Map<string, string[]>, note: Note, oldPath: string, attr: { actor: string | null; via: string | null }): void {
     if (plan.size === 0 || !note.path) return;
     const newPath = note.path;
 
@@ -785,12 +813,53 @@ export class BunSqliteStore implements Store {
         (target) => mapping.get(target.toLowerCase()) ?? null,
       );
       if (updated !== row.content) {
+        const prior = readPriorNoteRow(this.db, sourceId);
+        if (prior) captureVersion(this.db, prior, { ...attr, op: "cascade-rename", policy: this.historyPolicy });
         noteOps.updateNote(this.db, sourceId, { content: updated });
         syncWikilinks(this.db, sourceId, updated);
       }
     }
   }
 
+  async listNoteVersions(id: string, opts?: { limit?: number; offset?: number }) { return listVersions(this.db, id, opts); }
+  async getNoteVersion(id: string, versionIx: number) { return getVersion(this.db, id, versionIx); }
+  async eraseNoteHistory(id: string) { return eraseHistory(this.db, id); }
+  sweepDeletedHistory() { return sweepDeletedHistory(this.db, this.historyPolicy); }
+  async countNoteVersions(id: string) { return countNoteVersions(this.db, id); }
+  compactNote(id: string) { return compactNote(this.db, id, this.historyPolicy); }
+  compactHistory(opts?: { noteId?: string; budgetMs?: number | null; maxNotes?: number | null }) { return compactVault(this.db, this.historyPolicy, opts); }
+  async deletedHistoryStats() { return deletedHistoryStats(this.db); }
+  async restoreNoteVersion(id: string, versionIx: number, opts: { actor?: string | null; via?: string | null; if_updated_at?: string }): Promise<Note> {
+    if (noteOps.getNote(this.db, id)) {
+      const v = getVersion(this.db, id, versionIx);
+      if (!v) throw new HistoryNotFoundError(id, versionIx);
+      if (v.encoding === "overflow") throw new HistoryUnrecoverableError(id, versionIx);
+      return await this.updateNote(id, {
+        content: v.content!, metadata: v.metadata, extension: v.extension ?? undefined,
+        actor: opts.actor ?? null, via: opts.via ?? null,
+        ...(opts.if_updated_at !== undefined ? { if_updated_at: opts.if_updated_at } : {}),
+        historyOp: "restore",
+      });
+    }
+    const tomb = latestTombstone(this.db, id);
+    if (!tomb) throw new HistoryNotFoundError(id, null);
+    const v = getVersion(this.db, id, versionIx);
+    if (!v) throw new HistoryNotFoundError(id, versionIx);
+    if (v.encoding === "overflow") throw new HistoryUnrecoverableError(id, versionIx);
+    if (opts.if_updated_at !== undefined) throw new noteOps.ConflictError(id, tomb.path, null, opts.if_updated_at);
+    return this.transaction(() => {
+      const note = noteOps.createNote(this.db, v.content!, {
+        id, path: tomb.path ?? undefined, metadata: v.metadata,
+        extension: v.extension ?? undefined, created_at: v.created_at ?? tomb.superseded_at,
+        actor: opts.actor ?? null, via: opts.via ?? null,
+      });
+      appendRestoreMarker(this.db, id, tomb, { actor: opts.actor ?? null, via: opts.via ?? null }, this.historyPolicy);
+      if (note.content) syncWikilinks(this.db, id, note.content);
+      if (note.path) resolveUnresolvedWikilinks(this.db, note.path, id);
+      return note;
+    });
+  }
+
   async restoreNoteTimestamps(id: string, createdAt: string, updatedAt: string): Promise<void> {
     // Import-only: direct UPDATE so the importer can restore a note's
     // historical `created_at`/`updated_at` from the portable-md export
@@ -813,7 +882,7 @@ export class BunSqliteStore implements Store {
       .run(createdAt, updatedAt, updatedAtMs, id);
   }
 
-  async deleteNote(id: string): Promise<void> {
+  async deleteNote(id: string, opts?: { actor?: string | null; via?: string | null; captureHistory?: boolean }): Promise<void> {
     // Read before delete so we can invalidate config caches on the way out
     // AND so the post-delete hook dispatch carries the minimum payload
     // ({ id, path }). The full note can't be reconstructed post-delete —
@@ -826,14 +895,20 @@ export class BunSqliteStore implements Store {
     // it's individually re-saved. See requeueInboundWikilinksForDelete's doc
     // comment for why this must run pre-delete and what it deliberately
     // excludes (typed `links`, not just wikilinks).
-    requeueInboundWikilinksForDelete(this.db, id);
-    // vault#581 — the deleted note's resolution keys, captured BEFORE the row
-    // goes away and swept AFTER, so a `[[Dup]]` that was ambiguous only
-    // because of THIS note resolves (or, if it was the last candidate,
-    // demotes to an ordinary broken link).
-    const ambiguityKeys = noteResolutionKeys(existing);
-    noteOps.deleteNote(this.db, id);
-    refreshAmbiguousLinks(this.db, ambiguityKeys);
+    this.transaction(() => {
+      requeueInboundWikilinksForDelete(this.db, id);
+      // vault#581 — the deleted note's resolution keys, captured BEFORE the row
+      // goes away and swept AFTER, so a `[[Dup]]` that was ambiguous only
+      // because of THIS note resolves (or, if it was the last candidate,
+      // demotes to an ordinary broken link).
+      const ambiguityKeys = noteResolutionKeys(existing);
+      if (opts?.captureHistory !== false) {
+        const prior = readPriorNoteRow(this.db, id);
+        if (prior) captureVersion(this.db, prior, { actor: opts?.actor ?? null, via: opts?.via ?? null, op: "delete", policy: this.historyPolicy });
+      }
+      noteOps.deleteNote(this.db, id);
+      refreshAmbiguousLinks(this.db, ambiguityKeys);
+    });
     if (existing?.path) this.invalidateConfigCachesForPath(existing.path);
     // Dispatch even when `existing` was null — the caller asked for a
     // deletion, and downstream consumers (e.g. the mirror) reconcile via
@@ -1094,8 +1169,8 @@ export class BunSqliteStore implements Store {
     return result;
   }
 
-  async renameTag(oldName: string, newName: string): Promise<noteOps.RenameTagResult> {
-    const result = noteOps.renameTag(this.db, oldName, newName);
+  async renameTag(oldName: string, newName: string, opts?: { actor?: string; via?: string }): Promise<noteOps.RenameTagResult> {
+    const result = noteOps.renameTag(this.db, oldName, newName, opts, this.historyPolicy);
     // Vault#240: the cascade rewrites parent_names in OTHER tag rows as
     // part of the same transaction, plus tokens.scoped_tags and
     // indexed_fields.declarer_tags. Both caches are tag-keyed, so they
@@ -1728,3 +1803,17 @@ export class BunSqliteStore implements Store {
 export const SqliteStore = BunSqliteStore;
 /** @deprecated Renamed to `BunSqliteStore`. */
 export type SqliteStore = BunSqliteStore;
+
+const MUTATING_UPDATE_KEYS = ["content", "append", "prepend", "path", "extension", "metadata", "created_at", "state_transition"] as const;
+function willWriteNoteRow(u: Parameters<Store["updateNote"]>[1]): boolean {
+  for (const key of MUTATING_UPDATE_KEYS) if (u[key] !== undefined) return true;
+  return u.skipUpdatedAt !== true;
+}
+function historyOpFor(u: Parameters<Store["updateNote"]>[1]): HistoryOp {
+  if (typeof u.historyOp === "string") return u.historyOp;
+  if (u.append !== undefined) return "append";
+  if (u.prepend !== undefined) return "prepend";
+  return "update";
+}
+export { HistoryNotFoundError, HistoryOverflowError, HistoryUnrecoverableError, DEFAULT_HISTORY_POLICY, VERSION_MAX_BYTES };
+export type { HistoryPolicy, HistoryOp, VersionRow, CompactResult, CompactSummary };