@openparachute/vault 0.6.4-rc.13 → 0.6.4-rc.14

package/core/src/bare-tag-guard.test.ts

@@ -0,0 +1,246 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import { generateMcpTools } from "./mcp.js";
+import { stripTagHash } from "./tag-hierarchy.js";
+
+// Canonical-bare-tag guard (PR #516). A `#`-prefixed tag must never be stored
+// or mismatched: the agent module stored `#agent/message/inbound` literally and
+// consumers querying the bare `agent/message/inbound` convention found nothing.
+// The guard strips a leading `#` (idempotently) on BOTH the write path and the
+// query path, while preserving casing + structure (it is NOT normalizeTagValue).
+
+let store: SqliteStore;
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new SqliteStore(db);
+});
+
+/** Raw read of a note's stored tag rows (bypasses any hydration). */
+function storedTags(noteId: string): string[] {
+  return (
+    db
+      .prepare("SELECT tag_name FROM note_tags WHERE note_id = ? ORDER BY tag_name")
+      .all(noteId) as { tag_name: string }[]
+  ).map((r) => r.tag_name);
+}
+
+describe("stripTagHash helper", () => {
+  it("strips a single leading #", () => {
+    expect(stripTagHash("#agent/message")).toBe("agent/message");
+  });
+
+  it("is idempotent across one or more leading # (##x → x, x → x)", () => {
+    expect(stripTagHash("##x")).toBe("x");
+    expect(stripTagHash("###deep")).toBe("deep");
+    expect(stripTagHash("x")).toBe("x");
+    expect(stripTagHash(stripTagHash("#x"))).toBe("x");
+  });
+
+  it("does NOT lowercase or otherwise transform — casing + structure preserved", () => {
+    expect(stripTagHash("#Agent/Message/Inbound")).toBe("Agent/Message/Inbound");
+    expect(stripTagHash("CamelCase")).toBe("CamelCase");
+  });
+
+  it("only strips LEADING # — a mid-string # (e.g. c#) is left intact", () => {
+    expect(stripTagHash("c#")).toBe("c#");
+    expect(stripTagHash("#c#")).toBe("c#");
+    expect(stripTagHash("a#b")).toBe("a#b");
+  });
+
+  it("trims surrounding whitespace before stripping", () => {
+    expect(stripTagHash("  #tag ")).toBe("tag");
+  });
+});
+
+describe("write path — tags stored bare", () => {
+  it("createNote: #agent/message stored as agent/message", async () => {
+    const note = await store.createNote("inbound", { tags: ["#agent/message"] });
+    expect(storedTags(note.id)).toEqual(["agent/message"]);
+    expect(note.tags).toEqual(["agent/message"]);
+  });
+
+  it("##x stored as x; a bare foo is unchanged", async () => {
+    const note = await store.createNote("memo", { tags: ["##x", "foo"] });
+    expect(storedTags(note.id).sort()).toEqual(["foo", "x"]);
+  });
+
+  it("a # mid-string (c#) is NOT mangled", async () => {
+    const note = await store.createNote("memo", { tags: ["c#"] });
+    expect(storedTags(note.id)).toEqual(["c#"]);
+  });
+
+  it("casing is preserved through the write path", async () => {
+    const note = await store.createNote("memo", { tags: ["#Agent/Inbound"] });
+    expect(storedTags(note.id)).toEqual(["Agent/Inbound"]);
+  });
+
+  it("tagNote: #-prefixed add lands on the bare row", async () => {
+    const note = await store.createNote("memo");
+    await store.tagNote(note.id, ["#later"]);
+    expect(storedTags(note.id)).toEqual(["later"]);
+  });
+
+  it("untagNote: removing #tag deletes the bare row", async () => {
+    const note = await store.createNote("memo", { tags: ["later"] });
+    await store.untagNote(note.id, ["#later"]);
+    expect(storedTags(note.id)).toEqual([]);
+  });
+
+  it("batchTag/batchUntag normalize independently of tagNote", async () => {
+    const a = await store.createNote("a");
+    const b = await store.createNote("b");
+    await store.batchTag([a.id, b.id], ["#batch"]);
+    expect(storedTags(a.id)).toEqual(["batch"]);
+    expect(storedTags(b.id)).toEqual(["batch"]);
+    await store.batchUntag([a.id], ["#batch"]);
+    expect(storedTags(a.id)).toEqual([]);
+    expect(storedTags(b.id)).toEqual(["batch"]);
+  });
+
+  it("create-note via MCP also stores bare", async () => {
+    const tools = generateMcpTools(store);
+    const createNote = tools.find((t) => t.name === "create-note")!;
+    const res = (await createNote.execute({
+      content: "mcp inbound",
+      tags: ["#agent/message/inbound"],
+    })) as { id: string };
+    expect(storedTags(res.id)).toEqual(["agent/message/inbound"]);
+  });
+});
+
+describe("query path — # and bare forms equivalent", () => {
+  it("query tag:#agent/message and tag:agent/message both match the same bare-stored note", async () => {
+    const note = await store.createNote("inbound", { tags: ["agent/message"] });
+
+    const byHash = await store.queryNotes({ tags: ["#agent/message"] });
+    expect(byHash.map((n) => n.id)).toContain(note.id);
+
+    const byBare = await store.queryNotes({ tags: ["agent/message"] });
+    expect(byBare.map((n) => n.id)).toContain(note.id);
+  });
+
+  it("an old #-form query reaches a #-decorated WRITE (both normalize to the same bare row)", async () => {
+    // The non-breaking guarantee: a client that writes AND queries with the
+    // legacy #-form still works — both sides converge on the bare row. (Truly
+    // pre-fix #-STORED data is migrated away via renameTag, not auto-reached.)
+    const note = await store.createNote("inbound", { tags: ["#agent/message"] });
+    const byHash = await store.queryNotes({ tags: ["#agent/message"] });
+    expect(byHash.map((n) => n.id)).toContain(note.id);
+    const byBare = await store.queryNotes({ tags: ["agent/message"] });
+    expect(byBare.map((n) => n.id)).toContain(note.id);
+  });
+
+  it("exclude_tags #x excludes x-tagged notes", async () => {
+    const kept = await store.createNote("kept", { tags: ["keep"] });
+    const dropped = await store.createNote("dropped", { tags: ["keep", "x"] });
+
+    const results = await store.queryNotes({ tags: ["keep"], excludeTags: ["#x"] });
+    const ids = results.map((n) => n.id);
+    expect(ids).toContain(kept.id);
+    expect(ids).not.toContain(dropped.id);
+  });
+
+  it("searchNotes treats #tag and bare tag identically", async () => {
+    const note = await store.createNote("findable text here", { tags: ["agent/message"] });
+    const hits = await store.searchNotes("findable", { tags: ["#agent/message"] });
+    expect(hits.map((n) => n.id)).toContain(note.id);
+  });
+
+  it("query-notes via MCP: #-form matches bare-stored note", async () => {
+    const note = await store.createNote("mcp query", { tags: ["agent/message/inbound"] });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    // query-notes returns a plain array when no cursor is requested.
+    const res = (await query.execute({ tag: "#agent/message/inbound" })) as { id: string }[];
+    expect(res.map((n) => n.id)).toContain(note.id);
+  });
+});
+
+describe("tag schema path — update-tag name + parent_names stored bare", () => {
+  it("update-tag with name #foo + parent_names [#bar] → stored bare; inheritance works", async () => {
+    const tools = generateMcpTools(store);
+    const updateTag = tools.find((t) => t.name === "update-tag")!;
+
+    // Establish `bar` as a parent, then `foo` as its child via #-decorated input.
+    await updateTag.execute({ tag: "#bar", description: "parent" });
+    await updateTag.execute({ tag: "#foo", parent_names: ["#bar"] });
+
+    const fooRecord = await store.getTagRecord("foo");
+    expect(fooRecord).not.toBeNull();
+    expect(fooRecord!.parent_names).toEqual(["bar"]);
+    // The #-decorated upsert must NOT have created a phantom `#foo` row.
+    expect(await store.getTagRecord("#foo")).toBeNull();
+
+    // Inheritance: tag:bar expands to foo (foo's parent is bar).
+    const fooNote = await store.createNote("a foo note", { tags: ["foo"] });
+    const expanded = await store.queryNotes({ tags: ["bar"] });
+    expect(expanded.map((n) => n.id)).toContain(fooNote.id);
+  });
+
+  it("update-tag with #-name preserves the existing bare record's fields (merge correctness)", async () => {
+    const tools = generateMcpTools(store);
+    const updateTag = tools.find((t) => t.name === "update-tag")!;
+
+    await updateTag.execute({ tag: "thing", description: "first" });
+    // A #-decorated follow-up upsert must read the EXISTING bare record so the
+    // partial merge doesn't clobber the prior description.
+    await updateTag.execute({ tag: "#thing", parent_names: [] });
+
+    const record = await store.getTagRecord("thing");
+    expect(record!.description).toBe("first");
+  });
+});
+
+describe("rename carve-out — source name stays literal (migration escape hatch)", () => {
+  it("renameTag(#agent/message, agent/message) finds + renames the #-prefixed row", async () => {
+    // Plant a legacy #-prefixed tag row + a note carrying it (simulating the
+    // pre-fix agent data the migration must rename away).
+    db.prepare("INSERT OR IGNORE INTO tags (name) VALUES ('#agent/message')").run();
+    const note = await store.createNote("legacy inbound");
+    db.prepare("INSERT INTO note_tags (note_id, tag_name) VALUES (?, '#agent/message')").run(note.id);
+
+    const result = await store.renameTag("#agent/message", "agent/message");
+    expect("renamed" in result).toBe(true);
+
+    // The literal #-row is gone; the note now carries the bare tag.
+    expect(storedTags(note.id)).toEqual(["agent/message"]);
+    const tags = await store.listTags();
+    expect(tags.map((t) => t.name)).not.toContain("#agent/message");
+    expect(tags.map((t) => t.name)).toContain("agent/message");
+  });
+
+  it("renameTag normalizes the TARGET — renaming TO a #-name stores bare (can't re-introduce #)", async () => {
+    db.prepare("INSERT OR IGNORE INTO tags (name) VALUES ('plainsrc')").run();
+    const note = await store.createNote("x");
+    db.prepare("INSERT INTO note_tags (note_id, tag_name) VALUES (?, 'plainsrc')").run(note.id);
+
+    await store.renameTag("plainsrc", "#shiny");
+
+    // The target #-prefix is stripped — no `#shiny` row, the note carries `shiny`.
+    expect(storedTags(note.id)).toEqual(["shiny"]);
+    expect((await store.listTags()).map((t) => t.name)).not.toContain("#shiny");
+  });
+
+  it("mergeTags normalizes the TARGET — merging INTO a #-name stores bare", async () => {
+    db.prepare("INSERT OR IGNORE INTO tags (name) VALUES ('m1')").run();
+    const note = await store.createNote("y");
+    db.prepare("INSERT INTO note_tags (note_id, tag_name) VALUES (?, 'm1')").run(note.id);
+
+    await store.mergeTags(["m1"], "#dest");
+
+    expect(storedTags(note.id)).toEqual(["dest"]);
+    expect((await store.listTags()).map((t) => t.name)).not.toContain("#dest");
+  });
+});
+
+describe("regression — existing bare-tag behavior unchanged", () => {
+  it("bare write + bare query still works end to end", async () => {
+    const note = await store.createNote("plain", { tags: ["alpha", "beta"] });
+    expect(storedTags(note.id).sort()).toEqual(["alpha", "beta"]);
+    const results = await store.queryNotes({ tags: ["alpha"] });
+    expect(results.map((n) => n.id)).toContain(note.id);
+  });
+});

package/core/src/mcp.ts

@@ -3,7 +3,7 @@ import type { Store, Note } from "./types.js";
 import * as noteOps from "./notes.js";
 import { filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "./notes.js";
 import { QueryError } from "./query-operators.js";
-import { TAG_EXPAND_MODES, type TagExpandMode } from "./tag-hierarchy.js";
+import { TAG_EXPAND_MODES, stripTagHash, type TagExpandMode } from "./tag-hierarchy.js";
 import * as linkOps from "./links.js";
 import * as tagSchemaOps from "./tag-schemas.js";
 import type { TagFieldSchema } from "./tag-schemas.js";
@@ -1453,7 +1453,12 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
         required: ["tag"],
       },
       execute: async (params) => {
-        const tag = params.tag as string;
+        // Canonical-bare-tag guard (PR #516): normalize the tag NAME up front
+        // so the existing-record lookup (and the field/cross-tag merge that
+        // depends on it) reads the bare `foo` row, not a phantom `#foo` miss.
+        // store.upsertTagRecord normalizes again (idempotent) for non-MCP
+        // callers; doing it here keeps the merge correct.
+        const tag = stripTagHash(params.tag as string);
         const existing = tagSchemaOps.getTagRecord(db, tag);
 
         // ---- fields: three-way semantics, distinguishing `null` from

package/core/src/notes.ts

@@ -19,6 +19,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 +687,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 +717,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 +1198,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 +1217,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 +1253,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 +1269,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 +1387,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
@@ -1727,6 +1760,9 @@ 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);
 
@@ -1991,15 +2027,18 @@ 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) {
+    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++;
       }
@@ -2015,12 +2054,15 @@ export function batchTag(db: Database, noteIds: string[], tags: string[]): numbe
 
 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 {
     for (const noteId of noteIds) {
-      for (const tag of tags) {
+      for (const tag of bareTags) {
         stmt.run(noteId, tag);
         count++;
       }

package/core/src/store.ts

@@ -16,6 +16,7 @@ import { HookRegistry } from "./hooks.js";
 import {
   loadTagHierarchy,
   getTagExpansion,
+  stripTagHash,
   TAG_CONFIG_PREFIX,
   DEFAULT_TAG_NAME,
   DEFAULT_TAG_EXPAND_MODE,
@@ -251,8 +252,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> {
@@ -262,7 +285,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)));
   }
 
   /**
@@ -332,6 +359,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
@@ -630,6 +662,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 =

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/package.json

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

package/src/bare-tag-guard-routes.test.ts

@@ -0,0 +1,72 @@
+/**
+ * Canonical-bare-tag guard (vault#XXX) — REST layer. Confirms the PUT
+ * /tags/:name route normalizes the upserted tag NAME (so the partial-merge read
+ * + write land on the bare row) and leaves the rename SOURCE-name lookup literal
+ * (the migration escape hatch — a #-prefixed legacy tag must still be
+ * rename-able away). The query + note-tag write paths normalize in the store and
+ * are covered by core/src/bare-tag-guard.test.ts.
+ */
+
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "../core/src/store.ts";
+import { initSchema } from "../core/src/schema.ts";
+import { handleTags } from "./routes.ts";
+
+let store: SqliteStore;
+let db: Database;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  initSchema(db);
+  store = new SqliteStore(db);
+});
+
+function put(name: string, body: unknown): Promise<Response> {
+  const req = new Request(`http://localhost/api/tags/${encodeURIComponent(name)}`, {
+    method: "PUT",
+    body: JSON.stringify(body),
+  });
+  return handleTags(req, store, `/${encodeURIComponent(name)}`);
+}
+
+describe("PUT /tags/:name — bare-tag guard", () => {
+  it("PUT /tags/%23foo with parent_names [#bar] stores the bare row + bare parents", async () => {
+    const res = await put("#foo", { parent_names: ["#bar"], description: "child" });
+    expect(res.status).toBe(200);
+
+    const record = await store.getTagRecord("foo");
+    expect(record).not.toBeNull();
+    expect(record!.parent_names).toEqual(["bar"]);
+    expect(await store.getTagRecord("#foo")).toBeNull();
+  });
+
+  it("a #-decorated PUT preserves the existing bare record's fields (merge correctness)", async () => {
+    await put("thing", { description: "first" });
+    await put("#thing", { parent_names: [] });
+    const record = await store.getTagRecord("thing");
+    expect(record!.description).toBe("first");
+  });
+});
+
+describe("POST /tags/:name/rename — source name stays literal", () => {
+  it("rename #agent/message → agent/message finds the literal #-prefixed row", async () => {
+    db.prepare("INSERT OR IGNORE INTO tags (name) VALUES ('#agent/message')").run();
+    const note = await store.createNote("legacy inbound");
+    db.prepare("INSERT INTO note_tags (note_id, tag_name) VALUES (?, '#agent/message')").run(note.id);
+
+    const sub = "/" + encodeURIComponent("#agent/message") + "/rename";
+    const req = new Request(`http://localhost/api/tags${sub}`, {
+      method: "POST",
+      body: JSON.stringify({ new_name: "agent/message" }),
+    });
+    const res = await handleTags(req, store, sub);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { renamed?: number };
+    expect(body.renamed).toBeGreaterThan(0);
+
+    const tags = await store.listTags();
+    expect(tags.map((t) => t.name)).not.toContain("#agent/message");
+    expect(tags.map((t) => t.name)).toContain("agent/message");
+  });
+});

package/src/routes.ts

@@ -12,7 +12,7 @@
  */
 
 import type { Store, Note, QueryOpts } from "../core/src/types.ts";
-import { TAG_EXPAND_MODES, type TagExpandMode } from "../core/src/tag-hierarchy.ts";
+import { TAG_EXPAND_MODES, stripTagHash, type TagExpandMode } from "../core/src/tag-hierarchy.ts";
 import { listUnresolvedWikilinks } from "../core/src/wikilinks.ts";
 import { getNote, getNotes, getNoteTags, toNoteIndex, filterMetadata, mergeMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "../core/src/notes.ts";
 import {
@@ -2086,7 +2086,15 @@ export async function handleTags(
   // of { description, fields, relationships, parent_names }; omitted keys
   // are preserved, explicit null clears. See patterns/tag-data-model.md.
   if (req.method === "PUT") {
-    if (tagScope.allowed && !tagScope.allowed.has(tagName)) {
+    // Canonical-bare-tag guard (vault#XXX): normalize the upserted tag NAME so
+    // the existing-field merge read (store.getTagSchema below) and the upsert
+    // both target the bare row. store.upsertTagRecord re-normalizes (idempotent)
+    // for the write; this keeps the partial-merge read correct for a
+    // `#`-decorated PUT path. (GET/DELETE/rename keep their literal lookups —
+    // rename's source-name must still match a `#`-prefixed legacy row so the
+    // data migration can rename it away.)
+    const putTagName = stripTagHash(tagName);
+    if (tagScope.allowed && !tagScope.allowed.has(putTagName)) {
       return tagScopeForbidden(tagScope.raw ?? []);
     }
     const body = (await req.json()) as {
@@ -2157,7 +2165,7 @@ export async function handleTags(
         const full = body.fields as Record<string, tagSchemaOps.TagFieldSchema>;
         fieldsPatch = Object.keys(full).length > 0 ? full : null;
       } else {
-        const existing = await store.getTagSchema(tagName);
+        const existing = await store.getTagSchema(putTagName);
         const merged: Record<string, tagSchemaOps.TagFieldSchema> = {
           ...(existing?.fields ?? {}),
           ...(body.fields as Record<string, tagSchemaOps.TagFieldSchema>),
@@ -2172,7 +2180,7 @@ export async function handleTags(
     // unchanged on failure (no orphan/lying index). vault#478.
     let result;
     try {
-      result = await store.upsertTagRecord(tagName, {
+      result = await store.upsertTagRecord(putTagName, {
         ...(body.description !== undefined ? { description: body.description } : {}),
         ...(fieldsPatch !== undefined ? { fields: fieldsPatch } : {}),
         ...(relationshipsPatch !== undefined ? { relationships: relationshipsPatch } : {}),