@openparachute/vault 0.6.4-rc.10 → 0.6.4-rc.12

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/store.ts

@@ -28,6 +28,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
@@ -716,6 +720,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/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 ----
 
@@ -413,6 +415,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.10",
+  "version": "0.6.4-rc.12",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/routes.ts

@@ -27,6 +27,8 @@ import { logStrictBypass } from "./scopes.ts";
 import * as linkOps from "../core/src/links.ts";
 import * as tagSchemaOps from "../core/src/tag-schemas.ts";
 import { IndexedFieldError } from "../core/src/indexed-fields.ts";
+import { buildVaultProjection, resolveTagInheritance } from "../core/src/vault-projection.ts";
+import { loadSchemaConfig } from "../core/src/schema-defaults.ts";
 import {
   buildExpandVisibility,
   filterHydratedLinksByTagScope,
@@ -1997,6 +1999,64 @@ export async function handleTags(
     return json(result);
   }
 
+  // POST /tags/:name/conformance — count existing notes that would VIOLATE a
+  // proposed field spec for the tag (vault#283 tightening warning). Read-only
+  // (POST because it carries a proposed `fields` body). Must precede the
+  // /:name matcher so "conformance" isn't read as a tag name.
+  const conformanceMatch = subpath.match(/^\/([^/]+)\/conformance$/);
+  if (conformanceMatch) {
+    if (req.method !== "POST") return json({ error: "Method not allowed" }, 405);
+    const cTag = decodeURIComponent(conformanceMatch[1]!);
+    if (tagScope.allowed && !tagScope.allowed.has(cTag)) {
+      return json({ error: "Tag not found", tag: cTag }, 404);
+    }
+    const body = (await req.json().catch(() => null)) as
+      | { fields?: Record<string, unknown> | null }
+      | null;
+    if (!body) return json({ error: "Invalid JSON body" }, 400);
+    // The proposed fields the operator intends to save. Sanitized through the
+    // same parse the resolver uses (drop non-object specs). Empty/absent →
+    // nothing to enforce → zero violations.
+    const proposed: Record<string, tagSchemaOps.TagFieldSchema> = {};
+    if (body.fields && typeof body.fields === "object" && !Array.isArray(body.fields)) {
+      for (const [k, v] of Object.entries(body.fields)) {
+        if (v && typeof v === "object" && !Array.isArray(v)) {
+          proposed[k] = v as tagSchemaOps.TagFieldSchema;
+        }
+      }
+    }
+    const report = await store.countTagConformance(cTag, proposed);
+    return json(report);
+  }
+
+  // GET /tags/:name/effective — the tag's effective (own ∪ inherited) fields +
+  // direct/effective parents + schema-conflict info, drawn from the same
+  // projection vault-info exposes. Read-only inheritance preview for the
+  // Schema editor (vault#283). Must precede the /:name matcher.
+  const effectiveMatch = subpath.match(/^\/([^/]+)\/effective$/);
+  if (effectiveMatch) {
+    if (req.method !== "GET") return json({ error: "Method not allowed" }, 405);
+    const eTag = decodeURIComponent(effectiveMatch[1]!);
+    if (tagScope.allowed && !tagScope.allowed.has(eTag)) {
+      return json({ error: "Tag not found", tag: eTag }, 404);
+    }
+    const projection = buildVaultProjection(store.db);
+    const record = await store.getTagRecord(eTag);
+    // Resolve inheritance directly (not via projection.tags, which omits
+    // hierarchy-only tags carrying no own schema) so the editor's preview
+    // works even for a tag the operator is just starting to give fields.
+    const resolved = loadSchemaConfig(store.db);
+    const { effective_parents, effective_fields } = resolveTagInheritance(resolved, eTag);
+    return json({
+      name: eTag,
+      parents: record?.parent_names ?? [],
+      effective_parents,
+      fields: record?.fields ?? null,
+      effective_fields,
+      indexed_fields: projection.indexed_fields,
+    });
+  }
+
   // Routes with tag name
   const nameMatch = subpath.match(/^\/([^/]+)$/);
   if (!nameMatch) return json({ error: "Not found" }, 404);
@@ -2034,7 +2094,18 @@ export async function handleTags(
       fields?: Record<string, unknown> | null;
       relationships?: Record<string, unknown> | null;
       parent_names?: unknown;
+      /**
+       * When true, `fields` is treated as the FULL intended field map for the
+       * tag — fields absent from the payload are DROPPED (a replace, not a
+       * merge). Default false preserves the historical partial-update merge
+       * the MCP `update-tag` tool relies on (omitted keys preserved). The
+       * Schema editor (vault#283) sends the full map + `replace_fields: true`
+       * so removing a field row actually deletes the field. See
+       * patterns/tag-data-model.md.
+       */
+      replace_fields?: unknown;
     };
+    const replaceFields = body.replace_fields === true;
 
     // Validate the relationships payload up front so a bad payload returns
     // 400, not a thrown 500. `relationships` is an opaque vocabulary map
@@ -2071,7 +2142,10 @@ export async function handleTags(
     }
 
     // Field merge mirrors MCP update-tag — preserves prior keys when the
-    // payload only declares new ones.
+    // payload only declares new ones. UNLESS `replace_fields: true`, in which
+    // case `fields` is the full intended map and absent keys are dropped (the
+    // Schema editor's full-replacement save — vault#283; without this a
+    // removed field row is silently resurrected by the merge).
     let fieldsPatch:
       | Record<string, tagSchemaOps.TagFieldSchema>
       | null
@@ -2079,12 +2153,17 @@ export async function handleTags(
     if (body.fields === null) {
       fieldsPatch = null;
     } else if (body.fields !== undefined) {
-      const existing = await store.getTagSchema(tagName);
-      const merged: Record<string, tagSchemaOps.TagFieldSchema> = {
-        ...(existing?.fields ?? {}),
-        ...(body.fields as Record<string, tagSchemaOps.TagFieldSchema>),
-      };
-      fieldsPatch = Object.keys(merged).length > 0 ? merged : null;
+      if (replaceFields) {
+        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 merged: Record<string, tagSchemaOps.TagFieldSchema> = {
+          ...(existing?.fields ?? {}),
+          ...(body.fields as Record<string, tagSchemaOps.TagFieldSchema>),
+        };
+        fieldsPatch = Object.keys(merged).length > 0 ? merged : null;
+      }
     }
 
     // A bad indexed-field name (or an unindexable type, or a cross-tag type

package/src/routing.test.ts

@@ -1956,6 +1956,131 @@ describe("scope enforcement on /api/*", () => {
     expect(res.status).toBe(200);
   });
 
+  // ----- vault#283: Schema editor read endpoints -------------------------
+
+  test("POST /api/tags/:name/conformance → counts notes violating a proposed spec", async () => {
+    createVault("journal");
+    const store = getVaultStore("journal");
+    await store.createNote("ok", { tags: ["task"], metadata: { status: "open" } });
+    await store.createNote("missing", { tags: ["task"], metadata: {} });
+    const admin = await createAdminToken("journal");
+
+    const path = "/vault/journal/api/tags/task/conformance";
+    const res = await route(
+      new Request(`http://localhost:1940${path}`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${admin}`, "content-type": "application/json" },
+        body: JSON.stringify({ fields: { status: { type: "string", required: true } } }),
+      }),
+      path,
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      tag: string;
+      total_notes: number;
+      violating_notes: number;
+      checked_fields: string[];
+    };
+    expect(body.tag).toBe("task");
+    expect(body.total_notes).toBe(2);
+    expect(body.violating_notes).toBe(1);
+    expect(body.checked_fields).toEqual(["status"]);
+  });
+
+  test("POST /api/tags/:name/conformance is read-only — a read token may run it", async () => {
+    createVault("journal");
+    const store = getVaultStore("journal");
+    await store.createNote("missing", { tags: ["task"], metadata: {} });
+    const readToken = await mintToken("journal", {
+      permission: "read",
+      scopes: ["vault:read"],
+    });
+
+    const path = "/vault/journal/api/tags/task/conformance";
+    const res = await route(
+      new Request(`http://localhost:1940${path}`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${readToken}`, "content-type": "application/json" },
+        body: JSON.stringify({ fields: { status: { type: "string", required: true } } }),
+      }),
+      path,
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { violating_notes: number };
+    expect(body.violating_notes).toBe(1);
+  });
+
+  test("PUT /api/tags/:name with replace_fields drops omitted fields (no merge resurrection)", async () => {
+    createVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("task", {
+      fields: { status: { type: "string" }, due: { type: "string" } },
+    });
+    const admin = await createAdminToken("journal");
+
+    const path = "/vault/journal/api/tags/task";
+    // Send only `status` WITH replace_fields → `due` must be dropped.
+    const res = await route(
+      new Request(`http://localhost:1940${path}`, {
+        method: "PUT",
+        headers: { authorization: `Bearer ${admin}`, "content-type": "application/json" },
+        body: JSON.stringify({ fields: { status: { type: "string" } }, replace_fields: true }),
+      }),
+      path,
+    );
+    expect(res.status).toBe(200);
+    const rec = await store.getTagRecord("task");
+    expect(Object.keys(rec?.fields ?? {})).toEqual(["status"]);
+    expect(rec?.fields?.due).toBeUndefined();
+  });
+
+  test("PUT /api/tags/:name WITHOUT replace_fields preserves omitted fields (merge — MCP contract)", async () => {
+    createVault("journal");
+    const store = getVaultStore("journal");
+    await store.upsertTagRecord("task", {
+      fields: { status: { type: "string" }, due: { type: "string" } },
+    });
+    const admin = await createAdminToken("journal");
+
+    const path = "/vault/journal/api/tags/task";
+    // Send only `status` WITHOUT the flag → `due` preserved (partial update).
+    const res = await route(
+      new Request(`http://localhost:1940${path}`, {
+        method: "PUT",
+        headers: { authorization: `Bearer ${admin}`, "content-type": "application/json" },
+        body: JSON.stringify({ fields: { status: { type: "string", enum: ["a"] } } }),
+      }),
+      path,
+    );
+    expect(res.status).toBe(200);
+    const rec = await store.getTagRecord("task");
+    expect(Object.keys(rec?.fields ?? {}).sort()).toEqual(["due", "status"]);
+  });
+
+  test("GET /api/tags/:name/effective → surfaces inherited fields + parents", async () => {
+    createVault("journal");
+    const store = getVaultStore("journal");
+    // dev declares a field; dev/log inherits it via parent_names.
+    await store.upsertTagRecord("dev", {
+      fields: { area: { type: "string" } },
+    });
+    await store.upsertTagRecord("dev/log", { parent_names: ["dev"] });
+    const admin = await createAdminToken("journal");
+
+    const path = "/vault/journal/api/tags/dev%2Flog/effective";
+    const res = await route(authed(admin, "GET", path), path);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      name: string;
+      parents: string[];
+      effective_parents: string[];
+      effective_fields: Record<string, { type?: string }>;
+    };
+    expect(body.parents).toEqual(["dev"]);
+    expect(body.effective_parents).toContain("dev");
+    expect(body.effective_fields.area?.type).toBe("string");
+  });
+
   test("POST /api/tags/:name/rename → 200 cascades token allowlists (vault#240)", async () => {
     createVault("journal");
     const store = getVaultStore("journal");