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

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 };

package/core/src/types.ts

@@ -7,6 +7,7 @@ import type { ValidationStatus } from "./schema-defaults.js";
 import type { ConformanceReport } from "./conformance.js";
 import type { FindPathResult } from "./links.js";
 import type { DoctorReport, DoctorScanOpts } from "./doctor.js";
+import type { CompactResult, CompactSummary, HistoryOp, VersionRow } from "./history.js";
 
 // ---- Re-exports ----
 
@@ -481,7 +482,28 @@ export interface Store {
    */
   getNoteByPath(path: string, extension?: string): Promise<Note | null>;
   getNotes(ids: string[]): Promise<Note[]>;
-  updateNote(id: string, updates: { content?: string; append?: string; prepend?: string; path?: string; extension?: string; metadata?: Record<string, unknown>; created_at?: string; skipUpdatedAt?: boolean; actor?: string | null; via?: string | null; if_updated_at?: string; tagsForSchemaResolution?: string[] }): Promise<Note>;
+  updateNote(id: string, updates: { content?: string; append?: string; prepend?: string; path?: string; extension?: string; 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;
+      actor?: string | null; via?: string | null; if_updated_at?: string; tagsForSchemaResolution?: string[] }): Promise<Note>;
   /**
    * Set a note's `created_at` and `updated_at` explicitly. Import-only:
    * used by the portable-md round-trip path to restore timestamps from
@@ -497,7 +519,17 @@ export interface Store {
    * content. Returns counts for caller logging.
    */
   syncAllWikilinks(): Promise<{ synced: number; totalAdded: number; totalRemoved: number }>;
-  deleteNote(id: string): Promise<void>;
+  /** vault#524: deletion captures a tombstone unless a blow-away import opts out. */
+  deleteNote(id: string, opts?: { actor?: string | null; via?: string | null; captureHistory?: boolean }): Promise<void>;
+  listNoteVersions(id: string, opts?: { limit?: number; offset?: number }): Promise<VersionRow[]>;
+  getNoteVersion(id: string, versionIx: number): Promise<(VersionRow & { content: string | null }) | null>;
+  restoreNoteVersion(id: string, versionIx: number, opts: { actor?: string | null; via?: string | null; if_updated_at?: string }): Promise<Note>;
+  eraseNoteHistory(id: string): Promise<{ versionsDeleted: number; blobsDeleted: number }>;
+  sweepDeletedHistory(): { notesSwept: number; versionsDeleted: number; blobsDeleted: number };
+  countNoteVersions(id: string): Promise<number>;
+  compactNote(id: string): CompactResult;
+  compactHistory(opts?: { noteId?: string; budgetMs?: number | null; maxNotes?: number | null }): CompactSummary;
+  deletedHistoryStats(): Promise<{ notes: number; versions: number; bytes: number; overflow_tombstones: number }>;
   queryNotes(opts: QueryOpts): Promise<Note[]>;
   /**
    * Cursor-paginated `queryNotes` (vault#313). Returns the same notes plus
@@ -601,6 +633,7 @@ export interface Store {
   renameTag(
     oldName: string,
     newName: string,
+    opts?: { actor?: string; via?: string },
   ): Promise<
     | {
         renamed: number;