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

package/core/src/notes.ts

@@ -1,6 +1,7 @@
 import { Database, type SQLQueryBindings } from "bun:sqlite";
 import type { Note, NoteIndex, QueryOpts, QueryNotesPage, VaultStats } from "./types.js";
 import { normalizePath } from "./paths.js";
+import { transaction } from "./txn.js";
 import {
   buildOperatorClause,
   isOperatorObject,
@@ -19,6 +20,7 @@ import {
   type QueryHashInputs,
 } from "./cursor.js";
 import { getIndexedField, releaseField } from "./indexed-fields.js";
+import { stripTagHash } from "./tag-hierarchy.js";
 
 let idCounter = 0;
 
@@ -686,8 +688,14 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
   // rides idx_note_tags_tag, produces each note id at most once, and lets
   // the whole query drop DISTINCT. See the 2026-06-10 perf measurements.
   if (opts.tags && opts.tags.length > 0) {
+    // Canonical-bare-tag guard (vault#XXX) backstop for direct-core callers
+    // that bypass BunSqliteStore.normalizeQueryTags (the store normalizes +
+    // hierarchy-expands before reaching here; this protects the raw noteOps
+    // entry point and tests). `_tagsExpanded`, when present, was already built
+    // from bare names by the store, so prefer it; otherwise strip the literal
+    // tags. No-op on already-bare input.
     const tagSets: string[][] = (opts as QueryOpts & { _tagsExpanded?: string[][] })._tagsExpanded
-      ?? opts.tags.map((t) => [t]);
+      ?? opts.tags.map((t) => [stripTagHash(t)]);
     const match = opts.tagMatch ?? "all";
     if (match === "any") {
       // Flatten all expanded sets and dedupe — a note tagged with any one
@@ -710,9 +718,11 @@ export function queryNotes(db: Database, opts: QueryOpts): Note[] {
     }
   }
 
-  // Exclude tags
+  // Exclude tags — bare-tag guard backstop (see tags block above).
   if (opts.excludeTags && opts.excludeTags.length > 0) {
-    for (const tag of opts.excludeTags) {
+    for (const rawTag of opts.excludeTags) {
+      const tag = stripTagHash(rawTag);
+      if (tag === "") continue;
       conditions.push(`NOT EXISTS (SELECT 1 FROM note_tags ex WHERE ex.note_id = n.id AND ex.tag_name = ?)`);
       params.push(tag);
     }
@@ -1189,11 +1199,18 @@ export function searchNotes(
   const limit = typeof opts?.limit === "number" ? opts.limit : 50;
 
   if (opts?.tags && opts.tags.length > 0) {
+    // Canonical-bare-tag guard backstop (vault#XXX) for direct-core callers.
+    const searchTags = opts.tags.map(stripTagHash).filter((t) => t !== "");
+    if (searchTags.length === 0) {
+      // All tag filters collapsed to empty — fall through to the untagged
+      // search path below (no tag constraint).
+      opts = { ...opts, tags: undefined };
+    } else {
     try {
       // Tag membership as a semijoin — same rationale as queryNotes: a
       // `JOIN note_tags` multiplies rows for multi-tagged notes and forced
       // DISTINCT over full rows. The FTS join itself is 1:1 on rowid.
-      const tagPlaceholders = opts.tags.map(() => "?").join(", ");
+      const tagPlaceholders = searchTags.map(() => "?").join(", ");
       const rows = db.prepare(`
         SELECT n.* FROM notes n
         JOIN notes_fts fts ON fts.rowid = n.rowid
@@ -1201,11 +1218,12 @@ export function searchNotes(
           AND n.id IN (SELECT note_id FROM note_tags WHERE tag_name IN (${tagPlaceholders}))
         ORDER BY rank
         LIMIT ?
-      `).all(query, ...opts.tags, limit) as NoteRow[];
+      `).all(query, ...searchTags, limit) as NoteRow[];
       return notesWithTags(db, rows);
     } catch {
       return [];
     }
+    }
   }
 
   try {
@@ -1236,7 +1254,15 @@ export function tagNote(db: Database, noteId: string, tags: string[]): void {
   const insertTag = db.prepare("INSERT OR IGNORE INTO tags (name) VALUES (?)");
   const insertNoteTag = db.prepare("INSERT OR IGNORE INTO note_tags (note_id, tag_name) VALUES (?, ?)");
 
-  for (const tag of tags) {
+  // Canonical-bare-tag guard (vault#XXX): strip any leading `#` so the
+  // `#`-decorated form a client may pass (the agent module stored
+  // `#agent/message/inbound` verbatim) lands on the same bare row everyone
+  // else queries. This is the single write chokepoint — createNote /
+  // updateNote / batch / MCP add-tags / REST / import / transcript all funnel
+  // through store.tagNote → here.
+  for (const raw of tags) {
+    const tag = stripTagHash(raw);
+    if (tag === "") continue;
     insertTag.run(tag);
     insertNoteTag.run(noteId, tag);
   }
@@ -1244,7 +1270,10 @@ export function tagNote(db: Database, noteId: string, tags: string[]): void {
 
 export function untagNote(db: Database, noteId: string, tags: string[]): void {
   const stmt = db.prepare("DELETE FROM note_tags WHERE note_id = ? AND tag_name = ?");
-  for (const tag of tags) {
+  // Mirror tagNote's normalization so removing `#tag` deletes the bare row.
+  for (const raw of tags) {
+    const tag = stripTagHash(raw);
+    if (tag === "") continue;
     stmt.run(noteId, tag);
   }
 }
@@ -1359,6 +1388,11 @@ export type RenameTagResult =
  * after the cascade returns.
  */
 export function renameTag(db: Database, oldName: string, newName: string): 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
+  // `#`-prefixed rows. (Renaming TO a `#`-name is the thing we're preventing.)
+  newName = stripTagHash(newName);
   if (oldName === newName) {
     const exists = db.prepare("SELECT 1 FROM tags WHERE name = ?").get(oldName);
     return exists
@@ -1405,8 +1439,7 @@ export function renameTag(db: Database, oldName: string, newName: string): Renam
     return { error: "target_exists", conflicting };
   }
 
-  db.exec("BEGIN IMMEDIATE");
-  try {
+  const result = transaction(db, (): RenameTagSuccess => {
     let renamedNoteTags = 0;
     let pathsRenamed = 0;
 
@@ -1567,9 +1600,7 @@ export function renameTag(db: Database, oldName: string, newName: string): Renam
       }
     }
 
-    db.exec("COMMIT");
-
-    const result: RenameTagSuccess = {
+    return {
       renamed: renamedNoteTags,
       sub_tags_renamed: renames.length - 1,
       parent_refs_updated: parentRefsUpdated,
@@ -1578,21 +1609,18 @@ export function renameTag(db: Database, oldName: string, newName: string): Renam
       notes_rewritten: notesRewritten,
       paths_renamed: pathsRenamed,
     };
+  });
 
-    // Audit log: single line so operators searching `[vault] tag rename`
-    // can correlate cascades after the fact. Includes the stats and the
-    // mapping for non-trivial sub-tag cases.
-    console.error(
-      `[vault] tag rename cascade: ${oldName} → ${newName}` +
-        (renames.length > 1 ? ` (+${renames.length - 1} sub-tags)` : "") +
-        ` — note_tags:${result.renamed} parent_refs:${result.parent_refs_updated} tokens:${result.tokens_updated} indexed:${result.indexed_field_declarers_updated} notes:${result.notes_rewritten} paths:${result.paths_renamed}`,
-    );
+  // Audit log: single line so operators searching `[vault] tag rename`
+  // can correlate cascades after the fact. Includes the stats and the
+  // mapping for non-trivial sub-tag cases.
+  console.error(
+    `[vault] tag rename cascade: ${oldName} → ${newName}` +
+      (renames.length > 1 ? ` (+${renames.length - 1} sub-tags)` : "") +
+      ` — note_tags:${result.renamed} parent_refs:${result.parent_refs_updated} tokens:${result.tokens_updated} indexed:${result.indexed_field_declarers_updated} notes:${result.notes_rewritten} paths:${result.paths_renamed}`,
+  );
 
-    return result;
-  } catch (err) {
-    db.exec("ROLLBACK");
-    throw err;
-  }
+  return result;
 }
 
 function emptyCascadeResult(): RenameTagSuccess {
@@ -1727,13 +1755,15 @@ export function mergeTags(
   sources: string[],
   target: string,
 ): { merged: Record<string, number>; target: string } {
+  // Normalize the TARGET so a merge can never create a `#`-prefixed tag. SOURCES
+  // stay LITERAL so `#legacy/*` rows can be merged away (same carve-out as rename).
+  target = stripTagHash(target);
   // Dedup + drop target-in-sources (self-merge is a no-op).
   const uniqueSources = Array.from(new Set(sources)).filter((s) => s !== target);
 
   const merged: Record<string, number> = {};
 
-  db.exec("BEGIN");
-  try {
+  transaction(db, () => {
     // Target might not exist yet. Seed it so INSERT OR IGNORE into note_tags
     // can reference it; leave any existing schema on target untouched.
     db.prepare("INSERT OR IGNORE INTO tags (name) VALUES (?)").run(target);
@@ -1760,12 +1790,7 @@ export function mergeTags(
       deleteTagStmt.run(source);
       merged[source] = before;
     }
-
-    db.exec("COMMIT");
-  } catch (err) {
-    db.exec("ROLLBACK");
-    throw err;
-  }
+  });
 
   return { merged, target };
 }
@@ -1963,8 +1988,7 @@ export interface BulkNoteInput {
 export function createNotes(db: Database, inputs: BulkNoteInput[]): Note[] {
   const results: Note[] = [];
 
-  db.exec("BEGIN");
-  try {
+  transaction(db, () => {
     for (const input of inputs) {
       results.push(
         createNote(db, input.content, {
@@ -1979,11 +2003,7 @@ export function createNotes(db: Database, inputs: BulkNoteInput[]): Note[] {
         }),
       );
     }
-    db.exec("COMMIT");
-  } catch (err) {
-    db.exec("ROLLBACK");
-    throw err;
-  }
+  });
 
   return results;
 }
@@ -1991,45 +2011,41 @@ export function createNotes(db: Database, inputs: BulkNoteInput[]): Note[] {
 export function batchTag(db: Database, noteIds: string[], tags: string[]): number {
   const insertTag = db.prepare("INSERT OR IGNORE INTO tags (name) VALUES (?)");
   const insertNoteTag = db.prepare("INSERT OR IGNORE INTO note_tags (note_id, tag_name) VALUES (?, ?)");
+  // Canonical-bare-tag guard (vault#XXX) — batchTag has its own SQL (does NOT
+  // funnel through tagNote), so it strips leading `#` independently.
+  const bareTags = tags.map(stripTagHash).filter((t) => t !== "");
   let count = 0;
 
-  db.exec("BEGIN");
-  try {
-    for (const tag of tags) {
+  transaction(db, () => {
+    for (const tag of bareTags) {
       insertTag.run(tag);
     }
     for (const noteId of noteIds) {
-      for (const tag of tags) {
+      for (const tag of bareTags) {
         insertNoteTag.run(noteId, tag);
         count++;
       }
     }
-    db.exec("COMMIT");
-  } catch (err) {
-    db.exec("ROLLBACK");
-    throw err;
-  }
+  });
 
   return count;
 }
 
 export function batchUntag(db: Database, noteIds: string[], tags: string[]): number {
   const stmt = db.prepare("DELETE FROM note_tags WHERE note_id = ? AND tag_name = ?");
+  // Mirror batchTag's bare-tag normalization so removing `#tag` deletes the
+  // bare row.
+  const bareTags = tags.map(stripTagHash).filter((t) => t !== "");
   let count = 0;
 
-  db.exec("BEGIN");
-  try {
+  transaction(db, () => {
     for (const noteId of noteIds) {
-      for (const tag of tags) {
+      for (const tag of bareTags) {
         stmt.run(noteId, tag);
         count++;
       }
     }
-    db.exec("COMMIT");
-  } catch (err) {
-    db.exec("ROLLBACK");
-    throw err;
-  }
+  });
 
   return count;
 }

package/core/src/portable-md-batching.test.ts

@@ -0,0 +1,67 @@
+/**
+ * Batched-export coverage (Phase-1 streaming refactor). The export walk
+ * streams notes in windows of `EXPORT_BATCH_SIZE` (500) instead of one
+ * full-corpus query. These tests prove the windowing walks EVERY note across
+ * the batch boundaries — both a non-multiple remainder (1,203 = 500 + 500 +
+ * 203, so the final partial batch is exercised) and an exact multiple (1,000
+ * = 500 + 500 + a terminating empty query), with a sentinel note pinned in
+ * the final batch so an off-by-one that dropped the tail would fail loudly.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { existsSync, mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+import { SqliteStore } from "./store.js";
+import { exportVaultToDir } from "./portable-md.js";
+
+/** Zero-padded so lexicographic id order == numeric order (the export walks
+ *  `created_at ASC, id ASC`; fresh notes share a created_at so id breaks the
+ *  tie — this makes the batch membership of each note deterministic). */
+const pad = (i: number): string => String(i).padStart(5, "0");
+
+async function seed(store: SqliteStore, n: number): Promise<void> {
+  const inputs = [];
+  for (let i = 0; i < n; i++) {
+    inputs.push({ content: `note ${i}`, id: `n${pad(i)}`, path: `notes/n${pad(i)}` });
+  }
+  await store.createNotes(inputs);
+}
+
+describe("exportVaultToDir — batched walk across boundaries", () => {
+  let store: SqliteStore;
+  let outDir: string;
+
+  beforeEach(() => {
+    store = new SqliteStore(new Database(":memory:"));
+    outDir = mkdtempSync(join(tmpdir(), "portable-batch-"));
+  });
+  afterEach(() => {
+    try { rmSync(outDir, { recursive: true, force: true }); } catch {}
+  });
+
+  it("walks all 1,203 notes (2 full batches + a 203-note remainder)", async () => {
+    await seed(store, 1203);
+    const stats = await exportVaultToDir(store, { outDir, exportedAt: "2026-07-02T00:00:00.000Z" });
+
+    expect(stats.notes).toBe(1203);
+    // First note, both interior batch boundaries, and the sentinel in the
+    // final partial batch must all be on disk.
+    expect(existsSync(join(outDir, "notes/n00000.md"))).toBe(true); // batch 1 head
+    expect(existsSync(join(outDir, "notes/n00500.md"))).toBe(true); // batch 2 head
+    expect(existsSync(join(outDir, "notes/n01000.md"))).toBe(true); // batch 3 head
+    expect(existsSync(join(outDir, "notes/n01202.md"))).toBe(true); // last partial-batch sentinel
+  });
+
+  it("walks all notes on an exact multiple of the batch size (1,000 = 2×500 + terminating empty query)", async () => {
+    await seed(store, 1000);
+    const stats = await exportVaultToDir(store, { outDir, exportedAt: "2026-07-02T00:00:00.000Z" });
+
+    expect(stats.notes).toBe(1000);
+    expect(existsSync(join(outDir, "notes/n00000.md"))).toBe(true);
+    expect(existsSync(join(outDir, "notes/n00500.md"))).toBe(true);
+    expect(existsSync(join(outDir, "notes/n00999.md"))).toBe(true); // last note of the final full batch
+  });
+});

package/core/src/portable-md-golden.test.ts

@@ -0,0 +1,55 @@
+/**
+ * Golden-bytes regression for the portable-md streaming export refactor
+ * (Phase-1 shared-core, vault cloud design §4).
+ *
+ * `core/src/__fixtures__/portable-export-golden.json` was captured from the
+ * PRE-refactor (full-corpus, sync-fs) exporter by
+ * `scripts/capture-portable-golden.ts`. This test builds the SAME
+ * deterministic vault and asserts the CURRENT exporter reproduces those
+ * bytes exactly — the streaming/source-sink rewrite must be byte-for-byte
+ * indistinguishable on the fs backend. A diff here is a real format drift,
+ * not test flake (both sides share `buildGoldenVault` + `serializeExportTree`
+ * from the fixture module, so a fixture-vs-test mismatch is impossible).
+ *
+ * If a format change is ever intentional, re-run the capture script against
+ * the new code, review the JSON diff, and commit both together.
+ */
+
+import { describe, it, expect } from "bun:test";
+import { Database } from "bun:sqlite";
+import { mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+import { SqliteStore } from "./store.js";
+import { exportVaultToDir } from "./portable-md.js";
+import {
+  buildGoldenVault,
+  serializeExportTree,
+  GOLDEN_EXPORTED_AT,
+} from "./__fixtures__/golden-vault.js";
+import goldenTree from "./__fixtures__/portable-export-golden.json";
+
+describe("portable-md golden bytes — new exporter == old-exporter fixture", () => {
+  it("reproduces the captured export tree byte-for-byte", async () => {
+    const store = new SqliteStore(new Database(":memory:"));
+    await buildGoldenVault(store);
+
+    const outDir = mkdtempSync(join(tmpdir(), "portable-golden-test-"));
+    try {
+      await exportVaultToDir(store, {
+        outDir,
+        vaultName: "golden",
+        vaultDescription: "portable-md byte-stability fixture",
+        exportedAt: GOLDEN_EXPORTED_AT,
+        caseSensitiveOverride: true,
+      });
+      const tree = serializeExportTree(outDir);
+      // Compare as objects (per-file byte equality) — a keyed diff points
+      // straight at the drifting file if this ever fails.
+      expect(tree).toEqual(goldenTree as Record<string, string>);
+    } finally {
+      rmSync(outDir, { recursive: true, force: true });
+    }
+  });
+});