@openparachute/vault 0.6.4-rc.8 → 0.6.4

package/README.md

@@ -943,7 +943,7 @@ cp .env.example .env   # edit with your config
 docker compose up -d
 ```
 
-Optionally set `PARACHUTE_VAULT_NAME` to choose a name for your first vault (defaults to `default`). Lowercase alphanumeric + hyphens or underscores, 2–32 chars.
+Set `PARACHUTE_VAULT_NAME` to auto-create a first vault on startup (name: lowercase alphanumeric + hyphens or underscores, 2–32 chars). Without it the server boots with zero vaults — create one explicitly via the admin wizard, `parachute init --vault-name <name>`, or `parachute-vault create <name>`.
 
 ### Cloud platforms
 
@@ -968,9 +968,11 @@ typical v0.6 self-host wants. If you're not sure, use the hub-managed
 path above. The standalone Blueprint stays in tree because some
 operators specifically want this shape (vault#341).
 
-Optionally set `PARACHUTE_VAULT_NAME` to choose a name for your first
-vault (defaults to `default`). Lowercase alphanumeric + hyphens or
-underscores, 2–32 chars.
+Set `PARACHUTE_VAULT_NAME` to auto-create a first vault on startup (name:
+lowercase alphanumeric + hyphens or underscores, 2–32 chars). Without it
+the server boots with zero vaults — create one explicitly via the admin
+wizard, `parachute init --vault-name <name>`, or `parachute-vault create
+<name>`.
 
 #### Other platforms
 

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/conformance.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Conformance check (vault#283) — counting existing notes that would violate
+ * a proposed tightening of a tag's field spec. Backs the Schema editor's
+ * "N existing notes violate this" warning.
+ */
+import { describe, it, expect, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { SqliteStore } from "./store.js";
+import { countConformanceViolations } from "./conformance.js";
+
+let db: Database;
+let store: SqliteStore;
+
+beforeEach(() => {
+  db = new Database(":memory:");
+  store = new SqliteStore(db);
+});
+
+describe("countConformanceViolations", () => {
+  it("returns zero violations when proposed fields is empty", async () => {
+    await store.createNote("n", { tags: ["task"], metadata: { status: "open" } });
+    const r = countConformanceViolations(db, "task", {});
+    expect(r.total_notes).toBe(1);
+    expect(r.violating_notes).toBe(0);
+    expect(r.checked_fields).toEqual([]);
+  });
+
+  it("counts notes missing a newly-required field", async () => {
+    await store.createNote("has", { tags: ["task"], metadata: { due: "2026-01-01" } });
+    await store.createNote("missing-1", { tags: ["task"], metadata: {} });
+    await store.createNote("missing-2", { tags: ["task"] });
+
+    const r = countConformanceViolations(db, "task", {
+      due: { type: "string", required: true },
+    });
+    expect(r.total_notes).toBe(3);
+    expect(r.violating_notes).toBe(2);
+    expect(r.checked_fields).toEqual(["due"]);
+    // missing_required reasons surface in the sample.
+    expect(r.sample.every((s) => s.fields.some((f) => f.reason === "missing_required"))).toBe(true);
+  });
+
+  it("counts notes whose value falls outside a narrowed enum", async () => {
+    await store.createNote("ok", { tags: ["task"], metadata: { status: "open" } });
+    await store.createNote("bad", { tags: ["task"], metadata: { status: "archived" } });
+
+    const r = countConformanceViolations(db, "task", {
+      status: { type: "string", enum: ["open", "done"] },
+    });
+    expect(r.violating_notes).toBe(1);
+    expect(r.sample[0]?.fields[0]?.reason).toBe("enum_mismatch");
+  });
+
+  it("counts notes whose value contradicts a changed type", async () => {
+    await store.createNote("num", { tags: ["task"], metadata: { count: 3 } });
+    await store.createNote("str", { tags: ["task"], metadata: { count: "three" } });
+
+    const r = countConformanceViolations(db, "task", {
+      count: { type: "integer" },
+    });
+    expect(r.violating_notes).toBe(1);
+    expect(r.sample[0]?.fields[0]?.reason).toBe("type_mismatch");
+  });
+
+  it("includes descendant-tag notes via inheritance", async () => {
+    // dev/log declares dev as a parent → a strict field on dev applies to
+    // dev/log notes too.
+    await store.upsertTagRecord("dev/log", { parent_names: ["dev"] });
+    await store.createNote("parent-note", { tags: ["dev"], metadata: {} });
+    await store.createNote("child-note", { tags: ["dev/log"], metadata: {} });
+
+    const r = countConformanceViolations(db, "dev", {
+      kind: { type: "string", required: true },
+    });
+    expect(r.total_notes).toBe(2);
+    expect(r.violating_notes).toBe(2);
+  });
+
+  it("ignores fields the proposal does not touch", async () => {
+    await store.createNote("n", { tags: ["task"], metadata: { other: 123 } });
+    // We only propose `status`; `other` being weird is irrelevant.
+    const r = countConformanceViolations(db, "task", {
+      status: { type: "string" },
+    });
+    // `status` absent + not required → no violation.
+    expect(r.violating_notes).toBe(0);
+  });
+
+  it("caps the sample at sampleLimit but counts all violations", async () => {
+    for (let i = 0; i < 5; i++) {
+      await store.createNote(`n${i}`, { tags: ["task"], metadata: {} });
+    }
+    const r = countConformanceViolations(
+      db,
+      "task",
+      { req: { type: "string", required: true } },
+      { sampleLimit: 2 },
+    );
+    expect(r.violating_notes).toBe(5);
+    expect(r.sample.length).toBe(2);
+  });
+});
+
+describe("store.countTagConformance", () => {
+  it("proxies to the core helper", async () => {
+    await store.createNote("n", { tags: ["task"], metadata: {} });
+    const r = await store.countTagConformance("task", {
+      due: { type: "string", required: true },
+    });
+    expect(r.violating_notes).toBe(1);
+  });
+});

package/core/src/conformance.ts

@@ -0,0 +1,214 @@
+/**
+ * Schema conformance check — count how many EXISTING notes would violate a
+ * PROPOSED field spec for a tag, before the operator commits a tightening
+ * (vault#283, the MW2/#314 tie-in).
+ *
+ * Motivation: marking a field `strict`/`required`, narrowing an `enum`, or
+ * changing a `type` is a backwards-incompatible move — notes written under
+ * the old contract may now reject on their next write
+ * (`enforceStrictSchema` → `SchemaValidationError`). The Schema editor in
+ * the admin SPA calls this BEFORE save so the operator sees "N existing
+ * notes violate this — they'll reject on next write" and is pointed at the
+ * `parachute-vault schema migrate-field` CLI (#314) rather than silently
+ * shipping a contract their own data breaks.
+ *
+ * What "violate" means here: we overlay the PROPOSED `fields` for `tag` on
+ * top of the live schema config, treating every proposed field as if it
+ * were `strict:true` for the purpose of the count (so the count is "notes
+ * that would hard-reject IF this field were strict" — the worst case the
+ * operator is being warned about). We then walk every note carrying `tag`
+ * (descendants included, per the hierarchy) and run the SAME `validateNote`
+ * resolver the write path uses, counting notes with ≥1 violation on a field
+ * the proposal touches.
+ *
+ * This is a READ — no mutation. It's deliberately scoped to the proposed
+ * tag's own fields (the columns the operator is editing); inherited fields
+ * from ancestors are already enforced and aren't what the operator is
+ * tightening in this edit.
+ */
+
+import { Database } from "bun:sqlite";
+import {
+  loadSchemaConfig,
+  validateNote,
+  type SchemaField,
+  type ResolvedSchemas,
+} from "./schema-defaults.ts";
+import type { TagFieldSchema } from "./tag-schemas.ts";
+import { getTagDescendants, loadTagHierarchy } from "./tag-hierarchy.ts";
+import { queryNotes, getNoteTagsForNotes } from "./notes.ts";
+
+export interface ConformanceViolation {
+  /** Note id of a non-conforming note. */
+  id: string;
+  /** Note path, when set (helps the operator find it). */
+  path?: string | null;
+  /** The proposed-field violations on this note (reasons + messages). */
+  fields: { field: string; reason: string; message: string }[];
+}
+
+export interface ConformanceReport {
+  tag: string;
+  /** Total notes carrying the tag (descendants included). */
+  total_notes: number;
+  /** Count of notes that would violate the proposed spec. */
+  violating_notes: number;
+  /** The field names the proposal touches (the ones checked). */
+  checked_fields: string[];
+  /**
+   * A bounded sample of violating notes (id + path + which fields), so the
+   * SPA can show examples without paging the whole vault. Capped at
+   * `sampleLimit` (default 20).
+   */
+  sample: ConformanceViolation[];
+}
+
+/**
+ * Convert the on-disk `TagFieldSchema` shape to the resolver's `SchemaField`
+ * shape, FORCING `strict:true` so `validateNote` flags every constraint as a
+ * (strict) violation we can count. `indexed` is dropped — it's not a
+ * note-data constraint. `type` is narrowed to the resolver's union; an
+ * unknown type string is dropped (no type check) rather than throwing.
+ */
+function toStrictSchemaField(spec: TagFieldSchema): SchemaField {
+  const out: SchemaField = { strict: true };
+  if (
+    spec.type === "string" ||
+    spec.type === "number" ||
+    spec.type === "integer" ||
+    spec.type === "boolean" ||
+    spec.type === "array" ||
+    spec.type === "object"
+  ) {
+    out.type = spec.type;
+  }
+  if (Array.isArray(spec.enum)) out.enum = spec.enum;
+  if (spec.required === true) out.required = true;
+  if (spec.cardinality === "one" || spec.cardinality === "many") {
+    out.cardinality = spec.cardinality;
+  }
+  if (typeof spec.description === "string") out.description = spec.description;
+  return out;
+}
+
+/**
+ * Build a `ResolvedSchemas` snapshot with the proposed fields overlaid on
+ * `tag`'s OWN field map. We start from the live config (so inheritance +
+ * other tags are intact) and replace just `tag`'s field declarations with
+ * the strict-forced proposed set.
+ */
+function overlayProposedSchema(
+  base: ResolvedSchemas,
+  tag: string,
+  proposedFields: Record<string, TagFieldSchema>,
+): ResolvedSchemas {
+  const tagToFields = new Map(base.tagToFields);
+  const forced: Record<string, SchemaField> = {};
+  for (const [name, spec] of Object.entries(proposedFields)) {
+    forced[name] = toStrictSchemaField(spec);
+  }
+  if (Object.keys(forced).length > 0) {
+    tagToFields.set(tag, forced);
+  } else {
+    tagToFields.delete(tag);
+  }
+  return {
+    allTags: new Set(base.allTags).add(tag),
+    tagToFields,
+    tagToParents: base.tagToParents,
+  };
+}
+
+/**
+ * Count existing notes that would violate the PROPOSED field spec for `tag`.
+ *
+ * `proposedFields` is the full merged field map the operator intends to save
+ * (the same object the PUT body carries). Only the fields in this map are
+ * checked — the violation count answers "if I tighten THESE fields, how many
+ * notes break?" The check runs against every note carrying `tag` or any of
+ * its descendants.
+ *
+ * Pure read; no mutation. Returns 0 violating notes when `proposedFields` is
+ * empty (nothing to enforce).
+ */
+export function countConformanceViolations(
+  db: Database,
+  tag: string,
+  proposedFields: Record<string, TagFieldSchema>,
+  opts: { sampleLimit?: number } = {},
+): ConformanceReport {
+  const sampleLimit = opts.sampleLimit ?? 20;
+  const checkedFields = Object.keys(proposedFields);
+
+  const empty: ConformanceReport = {
+    tag,
+    total_notes: 0,
+    violating_notes: 0,
+    checked_fields: checkedFields,
+    sample: [],
+  };
+
+  // Resolve the tag's descendant set so we count notes on subtype tags too
+  // (a strict field on `#dev` applies to `#dev/log` notes via inheritance).
+  const hierarchy = loadTagHierarchy(db);
+  const tagSet = Array.from(getTagDescendants(hierarchy, tag));
+  if (tagSet.length === 0) return empty;
+
+  // All notes carrying the tag (or a descendant). `tagMatch: "any"` over the
+  // expanded set — a note on ANY of these tags is in scope. We hydrate tags
+  // ourselves (batched) so the resolver sees the full ancestor set per note.
+  const notes = queryNotes(db, { tags: tagSet, tagMatch: "any" });
+  if (notes.length === 0) return empty;
+
+  if (checkedFields.length === 0) {
+    return { ...empty, total_notes: notes.length };
+  }
+
+  const base = loadSchemaConfig(db);
+  const resolved = overlayProposedSchema(base, tag, proposedFields);
+  const checkedSet = new Set(checkedFields);
+
+  const tagsById = getNoteTagsForNotes(
+    db,
+    notes.map((n) => n.id),
+  );
+
+  let violating = 0;
+  const sample: ConformanceViolation[] = [];
+
+  for (const note of notes) {
+    const tags = tagsById.get(note.id) ?? note.tags ?? [];
+    const status = validateNote(resolved, {
+      path: note.path ?? null,
+      tags,
+      metadata: note.metadata ?? {},
+    });
+    if (!status) continue;
+    // Keep only violations on a field the PROPOSAL touches (ignore conflicts
+    // + violations on inherited/other fields the operator isn't editing).
+    const relevant = status.warnings.filter(
+      (w) => w.reason !== "schema_conflict" && checkedSet.has(w.field),
+    );
+    if (relevant.length === 0) continue;
+    violating++;
+    if (sample.length < sampleLimit) {
+      sample.push({
+        id: note.id,
+        path: note.path ?? null,
+        fields: relevant.map((w) => ({
+          field: w.field,
+          reason: w.reason,
+          message: w.message,
+        })),
+      });
+    }
+  }
+
+  return {
+    tag,
+    total_notes: notes.length,
+    violating_notes: violating,
+    checked_fields: checkedFields,
+    sample,
+  };
+}

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