@openparachute/vault 0.6.4-rc.9 → 0.6.5-rc.1

package/core/src/schema.ts

@@ -1,6 +1,7 @@
 import { Database } from "bun:sqlite";
 import { normalizePath } from "./paths.js";
 import { rebuildIndexes } from "./indexed-fields.js";
+import { transaction } from "./txn.js";
 
 export const SCHEMA_VERSION = 23;
 
@@ -680,8 +681,7 @@ function migrateToV13(db: Database): void {
 function migrateToV14(db: Database): void {
   if (!hasTable(db, "tags")) return;
 
-  db.exec("BEGIN IMMEDIATE");
-  try {
+  const { copiedSchemas, copiedHierarchy } = transaction(db, () => {
     // 1. ALTER TABLE — additive, idempotent.
     const cols: [string, string][] = [
       ["description", "TEXT"],
@@ -762,16 +762,13 @@ function migrateToV14(db: Database): void {
       db.exec("DROP TABLE tag_schemas");
     }
 
-    db.exec("COMMIT");
+    return { copiedSchemas, copiedHierarchy };
+  });
 
-    if (copiedSchemas > 0 || copiedHierarchy > 0) {
-      console.log(
-        `[vault] migrated to schema v14: copied ${copiedSchemas} tag_schemas + ${copiedHierarchy} _tags/* hierarchies onto tags rows`,
-      );
-    }
-  } catch (err) {
-    db.exec("ROLLBACK");
-    throw err;
+  if (copiedSchemas > 0 || copiedHierarchy > 0) {
+    console.log(
+      `[vault] migrated to schema v14: copied ${copiedSchemas} tag_schemas + ${copiedHierarchy} _tags/* hierarchies onto tags rows`,
+    );
   }
 }
 
@@ -806,8 +803,7 @@ function migrateToV15(db: Database): void {
   ).get()) !== null;
   if (hasSchemas || hasMappings) return;
 
-  db.exec("BEGIN IMMEDIATE");
-  try {
+  const { copiedSchemas, copiedMappings } = transaction(db, () => {
     const now = new Date().toISOString();
     let copiedSchemas = 0;
     let copiedMappings = 0;
@@ -884,16 +880,13 @@ function migrateToV15(db: Database): void {
       }
     }
 
-    db.exec("COMMIT");
+    return { copiedSchemas, copiedMappings };
+  });
 
-    if (copiedSchemas > 0 || copiedMappings > 0) {
-      console.log(
-        `[vault] migrated to schema v15: copied ${copiedSchemas} _schemas/* + ${copiedMappings} _schema_defaults mappings into note_schemas/schema_mappings`,
-      );
-    }
-  } catch (err) {
-    db.exec("ROLLBACK");
-    throw err;
+  if (copiedSchemas > 0 || copiedMappings > 0) {
+    console.log(
+      `[vault] migrated to schema v15: copied ${copiedSchemas} _schemas/* + ${copiedMappings} _schema_defaults mappings into note_schemas/schema_mappings`,
+    );
   }
 }
 
@@ -922,15 +915,10 @@ function migrateToV16(db: Database): void {
   // ALTER block so a fresh vault — where the column exists but the index
   // doesn't — still gets it.
   if (!hasColumn(db, "tokens", "vault_name")) {
-    db.exec("BEGIN IMMEDIATE");
-    try {
+    transaction(db, () => {
       db.exec("ALTER TABLE tokens ADD COLUMN vault_name TEXT");
       db.exec("CREATE INDEX IF NOT EXISTS idx_tokens_vault_name ON tokens(vault_name)");
-      db.exec("COMMIT");
-    } catch (err) {
-      db.exec("ROLLBACK");
-      throw err;
-    }
+    });
     return;
   }
 
@@ -980,8 +968,7 @@ function migrateToV17(db: Database): void {
     ).all() as { schema_name: string; match_kind: string; match_value: string }[];
   }
 
-  db.exec("BEGIN IMMEDIATE");
-  try {
+  transaction(db, () => {
     // Drop the index first — the index references the table; SQLite would
     // tear it down on DROP TABLE but the explicit DROP keeps the order
     // obvious if a future migration reads from sqlite_master mid-flight.
@@ -993,11 +980,7 @@ function migrateToV17(db: Database): void {
     if (hasNoteSchemas) {
       db.exec("DROP TABLE note_schemas");
     }
-    db.exec("COMMIT");
-  } catch (err) {
-    db.exec("ROLLBACK");
-    throw err;
-  }
+  });
 
   if (droppedSchemas.length > 0 || droppedMappings.length > 0) {
     const schemaNames = droppedSchemas.map((s) => s.name).join(", ");
@@ -1052,8 +1035,7 @@ function migrateToV18(db: Database): void {
   const hasNewUnique = indexes.some((r) => r.name === "idx_notes_path_ext_unique");
   if (!needsColumn && hasNewUnique && !hasOldUnique) return;
 
-  db.exec("BEGIN IMMEDIATE");
-  try {
+  transaction(db, () => {
     if (needsColumn) {
       db.exec("ALTER TABLE notes ADD COLUMN extension TEXT NOT NULL DEFAULT 'md'");
     }
@@ -1065,11 +1047,7 @@ function migrateToV18(db: Database): void {
         "CREATE UNIQUE INDEX idx_notes_path_ext_unique ON notes(path, extension) WHERE path IS NOT NULL",
       );
     }
-    db.exec("COMMIT");
-  } catch (err) {
-    db.exec("ROLLBACK");
-    throw err;
-  }
+  });
 }
 
 /**

package/core/src/store.ts

@@ -12,10 +12,12 @@ import {
 } from "./indexed-fields.js";
 import { syncWikilinks, resolveUnresolvedWikilinks } from "./wikilinks.js";
 import { pathTitle } from "./paths.js";
+import { transaction } from "./txn.js";
 import { HookRegistry } from "./hooks.js";
 import {
   loadTagHierarchy,
   getTagExpansion,
+  stripTagHash,
   TAG_CONFIG_PREFIX,
   DEFAULT_TAG_NAME,
   DEFAULT_TAG_EXPAND_MODE,
@@ -28,6 +30,10 @@ import {
   type ResolvedSchemas,
   type ValidationStatus,
 } from "./schema-defaults.js";
+import {
+  countConformanceViolations,
+  type ConformanceReport,
+} from "./conformance.js";
 
 /**
  * bun:sqlite-backed Store implementation. Internally everything is
@@ -50,6 +56,15 @@ export class BunSqliteStore implements Store {
     this.hooks = opts?.hooks ?? new HookRegistry();
   }
 
+  /**
+   * The transaction seam (see core/src/txn.ts). bun backs it with
+   * `BEGIN IMMEDIATE … COMMIT`; a DO-backed Store overrides this with
+   * `ctx.storage.transactionSync`. Synchronous — `fn` must not await.
+   */
+  transaction<T>(fn: () => T): T {
+    return transaction(this.db, fn);
+  }
+
   /**
    * Lazy accessor for the `_tags/*` config-note hierarchy. First call after
    * boot or after an invalidation does the scan; subsequent calls hit the
@@ -247,8 +262,30 @@ export class BunSqliteStore implements Store {
     );
   }
 
+  /**
+   * Canonical-bare-tag guard (vault#XXX) for the QUERY path. Strip any leading
+   * `#` from `tags` / `excludeTags` BEFORE hierarchy expansion so a
+   * `#agent/message`-form query matches a bare-stored `agent/message` row (and
+   * vice-versa). This is what makes the data migration non-breaking — every
+   * old `#`-decorated query keeps working, mapping onto the same bare rows.
+   * Runs before `expandQueryTags` so hierarchy resolution / `_default` collapse
+   * see the bare names. Empty-after-strip entries are dropped.
+   */
+  private normalizeQueryTags(opts: QueryOpts): QueryOpts {
+    let next = opts;
+    if (opts.tags && opts.tags.length > 0) {
+      const tags = opts.tags.map(stripTagHash).filter((t) => t !== "");
+      next = { ...next, tags };
+    }
+    if (opts.excludeTags && opts.excludeTags.length > 0) {
+      const excludeTags = opts.excludeTags.map(stripTagHash).filter((t) => t !== "");
+      next = { ...next, excludeTags };
+    }
+    return next;
+  }
+
   async queryNotes(opts: QueryOpts): Promise<Note[]> {
-    return noteOps.queryNotes(this.db, this.expandQueryTags(opts));
+    return noteOps.queryNotes(this.db, this.expandQueryTags(this.normalizeQueryTags(opts)));
   }
 
   async queryNotesPaged(opts: QueryOpts): Promise<QueryNotesPage> {
@@ -258,7 +295,11 @@ export class BunSqliteStore implements Store {
     // descendant set → different rows match → caller should restart). The
     // alternative — hash the expanded set — would silently keep returning
     // stale results from a hierarchy snapshot the caller never saw.
-    return noteOps.queryNotesPaged(this.db, this.expandQueryTags(opts));
+    //
+    // Bare-tag normalization runs first (before the hash is taken inside
+    // queryNotesPaged) so a `#tag`-form page-1 and a bare `tag`-form follow-up
+    // resolve to the same cursor query_hash.
+    return noteOps.queryNotesPaged(this.db, this.expandQueryTags(this.normalizeQueryTags(opts)));
   }
 
   /**
@@ -328,6 +369,11 @@ export class BunSqliteStore implements Store {
   }
 
   async searchNotes(query: string, opts?: { tags?: string[]; limit?: number; expand?: TagExpandMode }): Promise<Note[]> {
+    // Canonical-bare-tag guard (vault#XXX): strip leading `#` from search tag
+    // filters before expansion, so `#manual` and `manual` resolve identically.
+    if (opts?.tags && opts.tags.length > 0) {
+      opts = { ...opts, tags: opts.tags.map(stripTagHash).filter((t) => t !== "") };
+    }
     // Same tag-expansion treatment as queryNotes, along the SAME `expand` axis
     // (vault tag `expand` axis) — searching `#manual` should match notes
     // tagged with any descendant under "subtypes", any `manual/*` under
@@ -626,6 +672,18 @@ export class BunSqliteStore implements Store {
       parent_names?: string[] | null;
     },
   ) {
+    // Canonical-bare-tag guard (vault#XXX) for the SCHEMA path. Strip leading
+    // `#` from the tag NAME being upserted and from every `parent_names` entry,
+    // so the `tags` rows and the inheritance graph stay bare — matching the
+    // bare-stored note_tags. A `#foo` schema with `parent_names: ["#bar"]`
+    // becomes `foo` / `["bar"]`, so `tag:bar` still expands to `foo`.
+    tag = stripTagHash(tag);
+    if (patch.parent_names != null) {
+      patch = {
+        ...patch,
+        parent_names: patch.parent_names.map(stripTagHash).filter((p) => p !== ""),
+      };
+    }
     // Snapshot the prior indexed-field set BEFORE the write so the diff below
     // sees what this tag declared going in. Only needed when `fields` changes.
     const priorRecord =
@@ -668,10 +726,8 @@ export class BunSqliteStore implements Store {
     // mismatch only detectable once the existing declarer set is consulted),
     // the whole write rolls back — the schema never ends up claiming an index
     // that doesn't exist. vault#478 transactional fix.
-    let result: tagSchemaOps.TagRecord;
-    this.db.exec("BEGIN IMMEDIATE");
-    try {
-      result = tagSchemaOps.upsertTagRecord(this.db, tag, patch);
+    const result = this.transaction(() => {
+      const record = tagSchemaOps.upsertTagRecord(this.db, tag, patch);
 
       if (patch.fields !== undefined) {
         for (const fieldName of nextIndexed) {
@@ -686,11 +742,8 @@ export class BunSqliteStore implements Store {
           }
         }
       }
-      this.db.exec("COMMIT");
-    } catch (err) {
-      this.db.exec("ROLLBACK");
-      throw err;
-    }
+      return record;
+    });
 
     if (patch.parent_names !== undefined) {
       // parent_names drives both query expansion (tag hierarchy) AND, post
@@ -716,6 +769,21 @@ export class BunSqliteStore implements Store {
     return result;
   }
 
+  /**
+   * Conformance check (vault#283) — count how many EXISTING notes carrying
+   * `tag` (descendants included) would violate the PROPOSED field spec, so a
+   * tightening edit (strict / required / narrowed enum / changed type) can
+   * warn the operator BEFORE save. Pure read — no mutation. See
+   * core/src/conformance.ts.
+   */
+  async countTagConformance(
+    tag: string,
+    proposedFields: Record<string, tagSchemaOps.TagFieldSchema>,
+    opts?: { sampleLimit?: number },
+  ): Promise<ConformanceReport> {
+    return countConformanceViolations(this.db, tag, proposedFields, opts);
+  }
+
   // ---- Batch Wikilink Sync ----
 
   /**

package/core/src/tag-hierarchy.ts

@@ -27,6 +27,32 @@
 
 import { Database } from "bun:sqlite";
 
+/**
+ * Canonical-bare-tag guard (vault#XXX). Strip any leading `#` (one or more)
+ * from a tag value so a `#`-prefixed tag can never be stored or queried
+ * out-of-band. Tags are stored BARE by convention (`agent/message/inbound`,
+ * not `#agent/message/inbound`); a client that passes the `#`-decorated form —
+ * as the agent module did, persisting `#agent/message/inbound` literally — must
+ * land on the same canonical row everyone else queries.
+ *
+ * Deliberately MINIMAL: this is NOT `normalizeTagValue` (portable-md.ts). It
+ * does NOT lowercase, slug-validate, or otherwise transform the value — casing
+ * and structure are preserved. The ONLY job is to remove the stray leading `#`.
+ *
+ * Idempotent: `#tag` / `##tag` / `tag` all collapse to `tag`. Only LEADING `#`
+ * is stripped — a `#` mid-string (e.g. `c#`) is left intact. Whitespace is
+ * trimmed first so a `" #tag"` from a sloppy client also normalizes. Applied at
+ * the canonical chokepoints (note-tag write, query/exclude filters, tag-schema
+ * name + parent_names) so MCP, REST, and direct-core callers all converge.
+ */
+export function stripTagHash(tag: string): string {
+  // Strip any LEADING run of `#`/whitespace (handles `#tag`, `##tag`, `  #tag`,
+  // and `# tag` with a space after the hash), then trim the tail. A `#`
+  // mid-string (`c#`) is untouched; a degenerate `# #` collapses to "" (the
+  // write-path empty-tag gate drops it).
+  return tag.replace(/^[#\s]+/, "").trim();
+}
+
 export interface TagHierarchy {
   /** tag → set of immediate child tags (those that declared `tag` as a parent). */
   childrenOf: Map<string, Set<string>>;

package/core/src/txn.test.ts

@@ -0,0 +1,161 @@
+/**
+ * Contract tests for the transaction seam (core/src/txn.ts).
+ *
+ * Pins the behavior every migrated call site now depends on: commit returns
+ * the callback's value, a throw rolls back and re-throws the ORIGINAL error,
+ * and a ROLLBACK that itself fails (the "COMMIT already resolved the txn"
+ * case) is swallowed so the original error still propagates. The swallow /
+ * ordering cases use a structural fake `TxnCapableDb` so we can force a
+ * COMMIT/ROLLBACK failure deterministically; the happy + real-rollback cases
+ * run against a live bun:sqlite connection.
+ */
+
+import { describe, it, expect } from "bun:test";
+import { Database } from "bun:sqlite";
+import { transaction, transactionAsync, type TxnCapableDb } from "./txn.js";
+
+/** A fake `TxnCapableDb` that records exec calls and can be told to throw on
+ *  COMMIT and/or ROLLBACK — lets us drive the failure branches exactly. */
+function fakeDb(opts: { commitThrows?: Error; rollbackThrows?: Error } = {}): {
+  db: TxnCapableDb;
+  calls: string[];
+} {
+  const calls: string[] = [];
+  const db: TxnCapableDb = {
+    exec(sql: string): void {
+      calls.push(sql);
+      if (sql === "COMMIT" && opts.commitThrows) throw opts.commitThrows;
+      if (sql === "ROLLBACK" && opts.rollbackThrows) throw opts.rollbackThrows;
+    },
+  };
+  return { db, calls };
+}
+
+function freshDb(): Database {
+  const db = new Database(":memory:");
+  db.exec("CREATE TABLE t (id INTEGER PRIMARY KEY, v TEXT)");
+  return db;
+}
+
+describe("transaction (sync)", () => {
+  it("commits and returns the callback's value", () => {
+    const db = freshDb();
+    const result = transaction(db, () => {
+      db.exec("INSERT INTO t (id, v) VALUES (1, 'a')");
+      return { count: 1 };
+    });
+    expect(result).toEqual({ count: 1 });
+    // Write is durable after commit.
+    expect((db.prepare("SELECT COUNT(*) AS c FROM t").get() as { c: number }).c).toBe(1);
+  });
+
+  it("wraps in BEGIN IMMEDIATE … COMMIT", () => {
+    const { db, calls } = fakeDb();
+    transaction(db, () => "ok");
+    expect(calls).toEqual(["BEGIN IMMEDIATE", "COMMIT"]);
+  });
+
+  it("rolls back and re-throws the ORIGINAL error when the callback throws", () => {
+    const db = freshDb();
+    const sentinel = new Error("boom");
+    expect(() =>
+      transaction(db, () => {
+        db.exec("INSERT INTO t (id, v) VALUES (1, 'a')");
+        throw sentinel;
+      }),
+    ).toThrow(sentinel);
+    // The inner INSERT was rolled back.
+    expect((db.prepare("SELECT COUNT(*) AS c FROM t").get() as { c: number }).c).toBe(0);
+  });
+
+  it("issues ROLLBACK (not COMMIT) on a callback throw", () => {
+    const { db, calls } = fakeDb();
+    expect(() => transaction(db, () => { throw new Error("x"); })).toThrow("x");
+    expect(calls).toEqual(["BEGIN IMMEDIATE", "ROLLBACK"]);
+  });
+
+  it("swallows a ROLLBACK failure after a COMMIT throw and propagates the ORIGINAL (commit) error", () => {
+    const commitErr = new Error("commit failed");
+    const rollbackErr = new Error("no transaction is active");
+    const { db, calls } = fakeDb({ commitThrows: commitErr, rollbackThrows: rollbackErr });
+    let thrown: unknown;
+    try {
+      transaction(db, () => "value");
+    } catch (e) {
+      thrown = e;
+    }
+    // The COMMIT error is the original that propagates; the ROLLBACK error is swallowed.
+    expect(thrown).toBe(commitErr);
+    expect(calls).toEqual(["BEGIN IMMEDIATE", "COMMIT", "ROLLBACK"]);
+  });
+
+  it("preserves the callback error even when ROLLBACK also fails", () => {
+    const callbackErr = new Error("callback boom");
+    const rollbackErr = new Error("rollback boom");
+    const { db } = fakeDb({ rollbackThrows: rollbackErr });
+    let thrown: unknown;
+    try {
+      transaction(db, () => { throw callbackErr; });
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toBe(callbackErr);
+  });
+});
+
+describe("transactionAsync", () => {
+  it("commits and returns the callback's resolved value", async () => {
+    const db = freshDb();
+    const result = await transactionAsync(db, async () => {
+      db.exec("INSERT INTO t (id, v) VALUES (1, 'a')");
+      return 7;
+    });
+    expect(result).toBe(7);
+    expect((db.prepare("SELECT COUNT(*) AS c FROM t").get() as { c: number }).c).toBe(1);
+  });
+
+  it("wraps in BEGIN IMMEDIATE … COMMIT", async () => {
+    const { db, calls } = fakeDb();
+    await transactionAsync(db, async () => "ok");
+    expect(calls).toEqual(["BEGIN IMMEDIATE", "COMMIT"]);
+  });
+
+  it("rolls back and re-throws the ORIGINAL error when the callback rejects", async () => {
+    const db = freshDb();
+    const sentinel = new Error("async boom");
+    await expect(
+      transactionAsync(db, async () => {
+        db.exec("INSERT INTO t (id, v) VALUES (1, 'a')");
+        throw sentinel;
+      }),
+    ).rejects.toBe(sentinel);
+    expect((db.prepare("SELECT COUNT(*) AS c FROM t").get() as { c: number }).c).toBe(0);
+  });
+
+  it("swallows a ROLLBACK failure after a COMMIT throw and propagates the ORIGINAL (commit) error", async () => {
+    const commitErr = new Error("commit failed");
+    const rollbackErr = new Error("no transaction is active");
+    const { db, calls } = fakeDb({ commitThrows: commitErr, rollbackThrows: rollbackErr });
+    let thrown: unknown;
+    try {
+      await transactionAsync(db, async () => "value");
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toBe(commitErr);
+    expect(calls).toEqual(["BEGIN IMMEDIATE", "COMMIT", "ROLLBACK"]);
+  });
+
+  it("preserves the callback error even when ROLLBACK also fails", async () => {
+    const callbackErr = new Error("callback boom");
+    const rollbackErr = new Error("rollback boom");
+    const { db } = fakeDb({ rollbackThrows: rollbackErr });
+    let thrown: unknown;
+    try {
+      await transactionAsync(db, async () => { throw callbackErr; });
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toBe(callbackErr);
+  });
+});

package/core/src/txn.ts

@@ -0,0 +1,78 @@
+/**
+ * The transaction seam (Phase-1 shared-core refactor, vault cloud design §4).
+ *
+ * Core code must never emit raw `BEGIN`/`COMMIT`/`ROLLBACK` — that's the one
+ * SQLite construct DO's `sql.exec` blocks, so it can't be shimmed like the
+ * rest of the `Database` surface. Instead every atomic block routes through
+ * `transaction` / `transactionAsync` here. The bun backend implements them
+ * as `BEGIN IMMEDIATE … COMMIT` with rollback-on-throw; a future Durable-
+ * Object backend implements the same contract with `ctx.storage.transactionSync`
+ * (and `Store.transaction`, see types.ts, is the object-level entry point).
+ *
+ * `BEGIN IMMEDIATE` (write lock up front) matches the pre-seam behavior of
+ * the 13 core blocks this replaced — several used a bare `BEGIN`, but every
+ * one of them only ever wrote, so acquiring the write lock eagerly is a
+ * strict improvement (no lazy busy-upgrade) and never a semantic change.
+ *
+ * **Nesting is unsupported**, matching the pre-seam code exactly: SQLite
+ * throws "cannot start a transaction within a transaction" on a nested
+ * `BEGIN`, and none of the migrated call sites nest (a batch wraps individual
+ * `createNote`s, none of which open their own transaction). If a nested
+ * caller ever appears, the fix is SAVEPOINT-based re-entrancy *in the bun
+ * implementation here* — the call sites stay untouched.
+ */
+
+/** The minimal DB surface the transaction seam needs — kept structural (no
+ *  `bun:sqlite` import) so a non-bun backend satisfies it too. */
+export interface TxnCapableDb {
+  exec(sql: string): void;
+}
+
+/**
+ * Run `fn` inside a single write transaction, committing its result or
+ * rolling back on throw. Synchronous — the callback must not await (DO's
+ * `transactionSync` is sync-only; see `transactionAsync` for the batch paths
+ * that legitimately await the async Store facade).
+ */
+export function transaction<T>(db: TxnCapableDb, fn: () => T): T {
+  db.exec("BEGIN IMMEDIATE");
+  try {
+    const result = fn();
+    db.exec("COMMIT");
+    return result;
+  } catch (err) {
+    // Best-effort rollback — if the COMMIT itself threw the transaction is
+    // already resolved and ROLLBACK would throw "no transaction is active";
+    // swallow that so the original error is the one that propagates.
+    try {
+      db.exec("ROLLBACK");
+    } catch {
+      // no active transaction to roll back
+    }
+    throw err;
+  }
+}
+
+/**
+ * Async sibling of {@link transaction} for the batch executors, which run
+ * their body through the async `Store` facade (`await store.createNote(...)`
+ * etc.). The transaction spans the awaits on the shared connection — the
+ * same shape as the pre-seam `if (batched) db.exec("BEGIN")` blocks in
+ * mcp.ts / routes.ts. A DO backend can't map this onto `transactionSync`
+ * (which forbids awaiting); porting the batch path is a Phase-2 concern.
+ */
+export async function transactionAsync<T>(db: TxnCapableDb, fn: () => Promise<T>): Promise<T> {
+  db.exec("BEGIN IMMEDIATE");
+  try {
+    const result = await fn();
+    db.exec("COMMIT");
+    return result;
+  } catch (err) {
+    try {
+      db.exec("ROLLBACK");
+    } catch {
+      // no active transaction to roll back
+    }
+    throw err;
+  }
+}

package/core/src/types.ts

@@ -3,12 +3,14 @@ import type { TagFieldSchema, TagRelationship, TagRelationshipMap, TagRecord } f
 import type { PrunedField } from "./indexed-fields.js";
 import type { TagExpandMode } from "./tag-hierarchy.js";
 import type { ValidationStatus } from "./schema-defaults.js";
+import type { ConformanceReport } from "./conformance.js";
 
 // ---- Re-exports ----
 
 export type { TagFieldSchema, TagRelationship, TagRelationshipMap, TagRecord } from "./tag-schemas.js";
 export type { PrunedField } from "./indexed-fields.js";
 export type { TagExpandMode } from "./tag-hierarchy.js";
+export type { ConformanceReport } from "./conformance.js";
 
 // ---- Note ----
 
@@ -261,6 +263,15 @@ export interface Store {
    */
   readonly db: Database;
 
+  /**
+   * Run `fn` inside a single atomic write transaction (commit on return,
+   * rollback on throw). The transaction seam (see core/src/txn.ts): the
+   * bun backend implements it as `BEGIN IMMEDIATE … COMMIT`, a future
+   * Durable-Object backend as `ctx.storage.transactionSync`. Synchronous —
+   * `fn` must not await. Nesting is unsupported (matches raw-SQLite BEGIN).
+   */
+  transaction<T>(fn: () => T): T;
+
   // Notes. `actor` / `via` carry write-attribution (vault#298) — the
   // principal + interface stamped onto created_by/created_via (and mirrored
   // into the last_updated_* pair on create). Omitted → attribution NULL.
@@ -413,6 +424,19 @@ export interface Store {
     },
   ): Promise<TagRecord>;
 
+  /**
+   * Conformance check (vault#283) — count existing notes carrying `tag`
+   * (descendants included) that would violate the PROPOSED field spec, so a
+   * tightening edit (strict / required / narrowed enum / changed type) can
+   * warn before save. Pure read. `proposedFields` is the full merged field
+   * map the operator intends to save; only those fields are checked.
+   */
+  countTagConformance(
+    tag: string,
+    proposedFields: Record<string, TagFieldSchema>,
+    opts?: { sampleLimit?: number },
+  ): Promise<ConformanceReport>;
+
   // Schema validation (post-v17: backed by `tags.fields` only — the
   // standalone note_schemas + schema_mappings subsystem retired in v17, see
   // vault#267). Post vault#270 the resolver walks `parent_names` so a note's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/vault",
-  "version": "0.6.4-rc.9",
+  "version": "0.6.5-rc.1",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",