@openparachute/vault 0.6.4-rc.4 → 0.6.4-rc.5

package/core/src/core.test.ts

@@ -5,6 +5,7 @@ import { generateMcpTools } from "./mcp.js";
 import { initSchema } from "./schema.js";
 import { decodeCursor } from "./cursor.js";
 import { traverseLinks } from "./links.js";
+import * as indexedFieldOps from "./indexed-fields.js";
 
 let store: SqliteStore;
 let db: Database;
@@ -2169,6 +2170,50 @@ describe("MCP tools", async () => {
     expect(result.extension).toBe("csv");
   });
 
+  // ---- Metadata key-deletion via null tombstone (vault#478 / #479) ---------
+
+  it("update-note deletes a metadata key when its value is null (RFC 7386)", async () => {
+    const note = await store.createNote("m", {
+      metadata: { keep: "yes", drop: "old", other: 1 },
+    });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    await updateNote.execute({ id: note.id, metadata: { drop: null }, force: true });
+
+    const fresh = await store.getNote(note.id);
+    // The deleted key is GONE — not a literal JSON null.
+    expect(fresh!.metadata).not.toHaveProperty("drop");
+    // Other keys are untouched.
+    expect(fresh!.metadata).toMatchObject({ keep: "yes", other: 1 });
+  });
+
+  it("update-note metadata key-rename in one call (new key set, old key deleted)", async () => {
+    const note = await store.createNote("m", {
+      metadata: { "old-key": "v", stable: true },
+    });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    await updateNote.execute({
+      id: note.id,
+      metadata: { new_key: "v", "old-key": null },
+      force: true,
+    });
+
+    const fresh = await store.getNote(note.id);
+    expect(fresh!.metadata).not.toHaveProperty("old-key");
+    expect(fresh!.metadata).toMatchObject({ new_key: "v", stable: true });
+  });
+
+  it("deleting an absent metadata key is a no-op (round-trips cleanly)", async () => {
+    const note = await store.createNote("m", { metadata: { a: 1 } });
+    const tools = generateMcpTools(store);
+    const updateNote = tools.find((t) => t.name === "update-note")!;
+    await updateNote.execute({ id: note.id, metadata: { ghost: null }, force: true });
+    const fresh = await store.getNote(note.id);
+    expect(fresh!.metadata).toEqual({ a: 1 });
+    expect(fresh!.metadata).not.toHaveProperty("ghost");
+  });
+
   it("query-notes filters by extension (vault#328)", async () => {
     await store.createNote("md note", { path: "a" });
     await store.createNote("csv note", { path: "b", extension: "csv" });
@@ -5301,6 +5346,87 @@ describe("tag record API (patterns/tag-data-model.md)", async () => {
     expect((await store.queryNotes({ tags: ["manual"] })).length).toBe(0);
     expect(await store.getTagRecord("voice")).toBeNull();
   });
+
+  // ---- Indexed-field atomicity (vault#478) ----------------------------------
+
+  it("upsertTagRecord with a bad indexed-field name throws IndexedFieldError and leaves the schema unchanged", async () => {
+    // kebab-case field name violates [A-Za-z0-9_] / no-leading-digit. The
+    // declaration must NOT persist, and no orphan/lying index may be created.
+    await expect(
+      store.upsertTagRecord("meeting", {
+        description: "meetings",
+        fields: { "meeting-type": { type: "string", indexed: true } },
+      }),
+    ).rejects.toThrow(indexedFieldOps.IndexedFieldError);
+
+    // Schema is untouched — the tag row may not even exist, and definitely
+    // doesn't claim the poisoned field.
+    const record = await store.getTagRecord("meeting");
+    expect(record?.fields?.["meeting-type"]).toBeUndefined();
+
+    // No backing index row was created for the bad field.
+    expect(indexedFieldOps.getIndexedField(db, "meeting-type")).toBeNull();
+    // And the generated column doesn't exist either.
+    const cols = (db.prepare("PRAGMA table_xinfo(notes)").all() as { name: string }[]).map(
+      (c) => c.name,
+    );
+    expect(cols).not.toContain("meta_meeting-type");
+  });
+
+  it("upsertTagRecord with an unindexable type throws and leaves the schema unchanged", async () => {
+    await expect(
+      store.upsertTagRecord("meeting", {
+        fields: { attendees: { type: "json", indexed: true } },
+      }),
+    ).rejects.toThrow(indexedFieldOps.IndexedFieldError);
+    const record = await store.getTagRecord("meeting");
+    expect(record?.fields?.attendees).toBeUndefined();
+    expect(indexedFieldOps.getIndexedField(db, "attendees")).toBeNull();
+  });
+
+  it("a bad indexed field does NOT corrupt a prior valid declaration on the same tag", async () => {
+    // First, a clean valid indexed field.
+    await store.upsertTagRecord("meeting", {
+      fields: { held_on: { type: "string", indexed: true } },
+    });
+    expect(indexedFieldOps.getIndexedField(db, "held_on")?.declarerTags).toContain("meeting");
+
+    // Now an update that adds a poisoned field. The whole write must roll
+    // back — the prior valid field survives untouched.
+    await expect(
+      store.upsertTagRecord("meeting", {
+        fields: {
+          held_on: { type: "string", indexed: true },
+          "bad-field": { type: "string", indexed: true },
+        },
+      }),
+    ).rejects.toThrow(indexedFieldOps.IndexedFieldError);
+
+    const record = await store.getTagRecord("meeting");
+    expect(record?.fields?.held_on?.indexed).toBe(true);
+    expect(record?.fields?.["bad-field"]).toBeUndefined();
+    expect(indexedFieldOps.getIndexedField(db, "held_on")?.declarerTags).toContain("meeting");
+    expect(indexedFieldOps.getIndexedField(db, "bad-field")).toBeNull();
+  });
+
+  it("upsertTagRecord with fields:null releases indexed fields (transaction commits the release path)", async () => {
+    // Declare an indexed field, then clear all fields — the release path runs
+    // inside the same transaction as the persist. It must commit cleanly:
+    // the row, generated column, and index all drop.
+    await store.upsertTagRecord("meeting", {
+      fields: { held_on: { type: "string", indexed: true } },
+    });
+    expect(indexedFieldOps.getIndexedField(db, "held_on")?.declarerTags).toContain("meeting");
+
+    await store.upsertTagRecord("meeting", { fields: null });
+    const record = await store.getTagRecord("meeting");
+    expect(record?.fields).toBeUndefined();
+    expect(indexedFieldOps.getIndexedField(db, "held_on")).toBeNull();
+    const cols = (db.prepare("PRAGMA table_xinfo(notes)").all() as { name: string }[]).map(
+      (c) => c.name,
+    );
+    expect(cols).not.toContain("meta_held_on");
+  });
 });
 
 // ---------------------------------------------------------------------------

package/core/src/mcp.ts

@@ -830,7 +830,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
           },
           path: { type: "string", description: "New path" },
           extension: { type: "string", description: "Change the note's file extension (vault#328). Allowed but caller-owned — you're responsible for content validity if you switch a non-empty note's extension. Lowercase alphanumeric, 1–16 chars; \"parachute\" prefix reserved." },
-          metadata: { type: "object", description: "Metadata to merge (keys are merged, not replaced wholesale)" },
+          metadata: { type: "object", description: "Metadata to merge (keys are merged, not replaced wholesale). A value of `null` deletes that key (RFC 7386 merge-patch) — e.g. `{\"new_key\": \"v\", \"old_key\": null}` renames in one call. Omitting a key preserves its existing value." },
           created_at: { type: "string", description: "New created_at timestamp" },
           if_updated_at: { type: "string", description: "Optimistic concurrency check: the updated_at value you last read. Rejects with a conflict error if the note has been modified since. Required unless `force: true` is set or the call is `append`/`prepend`-only." },
           force: { type: "boolean", description: "Waive the *requirement to supply* `if_updated_at` and run the update unconditionally. Use only for bulk migrations or scripted writes where concurrency is known-safe. Note: this does not override an `if_updated_at` you actually pass — if you supply both, the precondition still applies and a mismatch returns a conflict error." },
@@ -1194,9 +1194,13 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
             updates.extension = validateExtension(item.extension);
           }
           if (item.metadata !== undefined) {
-            // Merge metadata (don't replace wholesale)
-            const existing = (note.metadata as Record<string, unknown>) ?? {};
-            updates.metadata = { ...existing, ...(item.metadata as Record<string, unknown>) };
+            // Merge metadata (RFC 7386: keys are merged, incoming `null`
+            // removes the key rather than persisting a literal null —
+            // vault#478/#479). Mirrors the REST PATCH path.
+            updates.metadata = noteOps.mergeMetadata(
+              note.metadata as Record<string, unknown> | null | undefined,
+              item.metadata as Record<string, unknown>,
+            );
           }
           if (item.created_at !== undefined) updates.created_at = item.created_at;
           if (item.if_updated_at !== undefined) updates.if_updated_at = item.if_updated_at as string;

package/core/src/notes.ts

@@ -1831,6 +1831,43 @@ export function filterMetadata(obj: any, includeMetadata: boolean | string[] | u
   return { ...obj, metadata: Object.keys(filtered).length > 0 ? filtered : undefined };
 }
 
+/**
+ * Shallow-merge an incoming metadata patch onto a note's existing metadata,
+ * with RFC 7386 (JSON Merge Patch) null-as-delete semantics — the canonical
+ * merge for every metadata write surface (REST `PATCH /api/notes`, MCP
+ * `update-note`, batch).
+ *
+ * An incoming value of `null` is a DELETE tombstone: the key is removed from
+ * the result rather than persisted as a literal JSON `null`. This is the only
+ * way to remove a metadata key through the API — under a plain
+ * `{ ...existing, ...incoming }` merge, omission can't delete (it preserves the
+ * prior value) and `null` used to persist literally, leaving no removal path.
+ * Now key renames are pure-API: `{ new_key: "v", "old-key": null }` adds the
+ * new key and drops the old one in one PATCH. See vault#478 / #479.
+ *
+ * Shallow by design — top-level keys only, matching the existing wholesale
+ * top-level merge. A nested object value replaces its key wholesale (we do not
+ * recurse), so an incoming `null` removes the whole key regardless of depth.
+ * Compat: storing a literal null is no longer possible via this path; the
+ * boulder migration confirmed zero callers relied on that (vault#478). A caller
+ * that genuinely needs an absent-vs-null distinction should model it with a
+ * sentinel string, not a JSON null.
+ */
+export function mergeMetadata(
+  existing: Record<string, unknown> | null | undefined,
+  incoming: Record<string, unknown>,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = { ...(existing ?? {}) };
+  for (const [key, value] of Object.entries(incoming)) {
+    if (value === null) {
+      delete result[key];
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
 // ---- Vault stats (aggregate situational awareness) ----
 
 /**

package/core/src/store.ts

@@ -631,36 +631,65 @@ export class BunSqliteStore implements Store {
     const priorRecord =
       patch.fields !== undefined ? tagSchemaOps.getTagRecord(this.db, tag) : null;
 
-    const result = tagSchemaOps.upsertTagRecord(this.db, tag, patch);
-
+    const indexedSet = (fields: Record<string, tagSchemaOps.TagFieldSchema> | null | undefined) =>
+      new Set(
+        Object.entries(fields ?? {})
+          .filter(([, v]) => v.indexed === true)
+          .map(([k]) => k),
+      );
+    const nextFields = patch.fields; // object | null | undefined
+    const priorIndexed = indexedSet(priorRecord?.fields);
+    const nextIndexed = indexedSet(nextFields);
+
+    // PRE-VALIDATE every newly-indexed field BEFORE any persistence. A bad
+    // field name (or unmappable type) must fail closed — the schema record
+    // must NOT be written when the backing index can't be created. Pre-checking
+    // here, before the transaction even opens, turns the failure into a clean
+    // caller error (IndexedFieldError → 400) and leaves the schema untouched.
+    // Without this, the prior code persisted the field declaration, THEN threw
+    // on declareField — a 500 plus a tag claiming an index the engine can't
+    // build (the "lying schema" loop). See vault#478.
     if (patch.fields !== undefined) {
-      const indexedSet = (fields: Record<string, tagSchemaOps.TagFieldSchema> | null | undefined) =>
-        new Set(
-          Object.entries(fields ?? {})
-            .filter(([, v]) => v.indexed === true)
-            .map(([k]) => k),
-        );
-      const nextFields = patch.fields; // object | null
-      const priorIndexed = indexedSet(priorRecord?.fields);
-      const nextIndexed = indexedSet(nextFields);
       for (const fieldName of nextIndexed) {
         const spec = nextFields![fieldName]!;
         const mapped = indexedFieldOps.mapFieldType(spec.type);
-        // Unmappable type for indexing is a caller error; surface it rather
-        // than silently skipping. MCP/REST validate up-front for a cleaner
-        // message, but this is the backstop at the chokepoint.
         if (!mapped) {
           throw new indexedFieldOps.IndexedFieldError(
             `field "${fieldName}" has unsupported type "${spec.type}" for indexing (supported: string, integer, boolean)`,
           );
         }
-        indexedFieldOps.declareField(this.db, fieldName, mapped, tag);
+        // Throws IndexedFieldError on an invalid identifier (e.g. kebab-case).
+        indexedFieldOps.validateFieldName(fieldName);
       }
-      for (const fieldName of priorIndexed) {
-        if (!nextIndexed.has(fieldName)) {
-          indexedFieldOps.releaseField(this.db, fieldName, tag);
+    }
+
+    // Persist the record + reconcile the indexed-field lifecycle atomically.
+    // If declareField throws inside the transaction (e.g. a cross-tag type
+    // mismatch only detectable once the existing declarer set is consulted),
+    // the whole write rolls back — the schema never ends up claiming an index
+    // that doesn't exist. vault#478 transactional fix.
+    let result: tagSchemaOps.TagRecord;
+    this.db.exec("BEGIN IMMEDIATE");
+    try {
+      result = tagSchemaOps.upsertTagRecord(this.db, tag, patch);
+
+      if (patch.fields !== undefined) {
+        for (const fieldName of nextIndexed) {
+          const spec = nextFields![fieldName]!;
+          // Type already validated above; non-null assertion is safe here.
+          const mapped = indexedFieldOps.mapFieldType(spec.type)!;
+          indexedFieldOps.declareField(this.db, fieldName, mapped, tag);
+        }
+        for (const fieldName of priorIndexed) {
+          if (!nextIndexed.has(fieldName)) {
+            indexedFieldOps.releaseField(this.db, fieldName, tag);
+          }
         }
       }
+      this.db.exec("COMMIT");
+    } catch (err) {
+      this.db.exec("ROLLBACK");
+      throw err;
     }
 
     if (patch.parent_names !== undefined) {

package/package.json

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

package/src/module-config.ts

@@ -14,31 +14,26 @@
  *
  * PUT /.parachute/config is Phase 3 — not implemented here.
  *
+ * Scope boundary (vault#478): `GET /.parachute/config` is gated by
+ * `vault:<name>:admin` — admin over *your* vault only — so it describes and
+ * returns ONLY per-vault config, never daemon-GLOBAL settings.
+ *
  * Fields currently described:
  *   - audio_retention:      per-vault enum, backed by VaultConfig.audio_retention.
- *   - port:                 GlobalConfig.port, exposed read-only.
- *   - autoTranscribe.*:     vault↔scribe handoff (vault#353, design 2026-05-21
- *                           Part 2). Three nested fields per design Q4:
- *       - enabled:          boolean toggle, default true when scribe is
- *                           reachable (persisted in
- *                           GlobalConfig.auto_transcribe.enabled). Default
- *                           flipped from off → on so installing scribe is
- *                           the only opt-in signal needed.
- *       - scribeUrl:        readOnly — resolved per-process from
- *                           `~/.parachute/services.json` via
- *                           `scribe-discovery.ts`. Operators can't point at an
- *                           arbitrary scribe; the discovery layer is the gate.
- *       - scribeBearer:     writeOnly — sourced from SCRIBE_AUTH_TOKEN env var.
- *                           Hub install generates one at first boot
- *                           (see scribe-env.ts:ensureScribeBearer); manual
- *                           rotation is via `parachute-vault config set`.
- *   - scribe_url / scribe_token (deprecated): kept under their legacy names
- *                           through one release for the hub admin SPA's prior
- *                           render path; new code should read autoTranscribe.*.
+ *   - autoTranscribe.enabled: per-vault toggle (vault#353). Reports the value
+ *                           THIS vault will use, resolving per-vault override
+ *                           (VaultConfig.auto_transcribe.enabled) → server
+ *                           default (GlobalConfig.auto_transcribe.enabled) →
+ *                           true. The inherited fallback is the per-vault
+ *                           truth, not a leak of the global setting.
+ *
+ * Deliberately NOT exposed here (daemon-global → operator-only surface):
+ *   - port:                 GlobalConfig.port (deployment-wide listen port).
+ *   - autoTranscribe.scribeUrl / scribe_url: discovery-resolved per-process.
+ *   - autoTranscribe.scribeBearer / scribe_token: shared SCRIBE_AUTH_TOKEN.
  */
 
 import type { VaultConfig, GlobalConfig } from "./config.ts";
-import { resolveScribeUrl } from "./scribe-discovery.ts";
 
 export interface ModuleConfigSchema {
   $schema: string;
@@ -75,83 +70,54 @@ export function buildConfigSchema(): ModuleConfigSchema {
             default: true,
             title: "Enable auto-transcription",
             description:
-              "Master toggle. Default on — audio uploads transcribe automatically when scribe is reachable. Set to false to disable. Global — persisted in `GlobalConfig.auto_transcribe.enabled` and applies to every vault on this server. Per-vault control is a future enhancement when multi-vault deployments need it.",
-          },
-          scribeUrl: {
-            type: "string",
-            format: "uri",
-            readOnly: true,
-            title: "Scribe URL",
-            description:
-              "URL of the scribe service. Auto-populated from `~/.parachute/services.json` at vault startup (or from the SCRIBE_URL env var when set). Read-only — operators can't point at an arbitrary scribe.",
-          },
-          scribeBearer: {
-            type: "string",
-            writeOnly: true,
-            title: "Scribe auth bearer",
-            description:
-              "Shared bearer for the vault→scribe loopback contract. Hub install generates one at first boot. Write-only — never returned by GET.",
+              "Per-vault toggle. Default on — audio uploads transcribe automatically when scribe is reachable. Set to false to disable for THIS vault. Resolves per-vault override → server default → on, so leaving it unset inherits the deployment default.",
           },
         },
       },
-      // Legacy aliases kept for back-compat with callers that read the
-      // pre-vault#353 shape. New consumers should read `autoTranscribe.*`.
-      scribe_url: {
-        type: "string",
-        format: "uri",
-        title: "Scribe URL (deprecated alias)",
-        description:
-          "Legacy alias for `autoTranscribe.scribeUrl`. Will be removed in a future release.",
-        readOnly: true,
-        deprecated: true,
-      },
-      scribe_token: {
-        type: "string",
-        title: "Scribe auth token (deprecated alias)",
-        description:
-          "Legacy alias for `autoTranscribe.scribeBearer`. Will be removed in a future release.",
-        writeOnly: true,
-        deprecated: true,
-      },
-      port: {
-        type: "integer",
-        minimum: 1,
-        maximum: 65535,
-        title: "HTTP port",
-        description: "Port the vault server listens on. Set at init time; changing requires a restart.",
-        readOnly: true,
-      },
+      // NOTE (vault#478): daemon-GLOBAL fields (the listen `port`, the
+      // discovery-resolved scribe URL, the shared scribe bearer) are
+      // deliberately NOT described here. This endpoint is gated by
+      // `vault:<name>:admin` — admin over *your* vault only — so it neither
+      // describes nor returns deployment-wide settings. Those live behind the
+      // operator-only surface (CLI / global config).
     },
   };
 }
 
 /**
- * Effective config values, with `writeOnly` fields stripped. `scribeBearer`
- * (and its legacy alias `scribe_token`) are declared `writeOnly` and never
- * returned, even when set in the environment.
+ * Effective config values for ONE vault. The shared scribe bearer is
+ * daemon-global and never returned (see the scope boundary below).
+ *
+ * Scope boundary (vault#478): the `GET /vault/<name>/.parachute/config`
+ * endpoint is gated by `vault:<name>:admin` — "admin over *your* vault only".
+ * It must therefore return ONLY per-vault config, never daemon-GLOBAL settings
+ * (the listen `port`, the discovery-resolved scribe URL, the server-wide
+ * auto-transcribe default). Those describe the whole deployment, not this
+ * vault, and leaking them across the per-vault admin boundary matters once a
+ * shared multi-vault daemon hands admin-on-one-vault to a beta signup. They
+ * live behind the operator-only surface (the CLI / global config), not here.
+ *
+ * `autoTranscribe.enabled` IS per-vault: it reports the value THIS vault will
+ * actually use, resolving per-vault override → global default → true (mirrors
+ * `shouldAutoTranscribe`). That's a per-vault effective value, not the raw
+ * daemon-global toggle — reporting it doesn't leak the global setting (an
+ * unset vault simply inherits, which is the per-vault truth).
  */
 export function buildConfigValues(
   vaultConfig: VaultConfig,
   globalConfig: GlobalConfig,
-  env: { SCRIBE_URL?: string | undefined } = process.env as { SCRIBE_URL?: string },
 ): Record<string, unknown> {
-  // Resolve scribe URL through the discovery layer so the GET shape reflects
-  // what the worker will actually use (services.json > SCRIBE_URL > unset).
-  // Pass env through so the test harness's override is honored.
-  const scribeUrl = resolveScribeUrl(env as NodeJS.ProcessEnv) ?? "";
   return {
     audio_retention: vaultConfig.audio_retention ?? "keep",
     autoTranscribe: {
-      // Match shouldAutoTranscribe's `?? true` so the admin SPA displays
-      // the same value runtime uses. An unset config row shows `true`
-      // because that's what vault will actually do on the next audio upload.
-      enabled: globalConfig.auto_transcribe?.enabled ?? true,
-      scribeUrl,
+      // Per-vault effective value: this vault's own override wins; otherwise it
+      // inherits the server default; otherwise true. Same ladder as
+      // shouldAutoTranscribe, so the admin SPA shows what this vault will do.
+      enabled:
+        vaultConfig.auto_transcribe?.enabled
+        ?? globalConfig.auto_transcribe?.enabled
+        ?? true,
     },
-    // Legacy alias mirrors `autoTranscribe.scribeUrl` so hubs reading the
-    // pre-vault#353 shape don't regress.
-    scribe_url: scribeUrl,
-    port: globalConfig.port,
   };
 }
 

package/src/routes.ts

@@ -14,7 +14,7 @@
 import type { Store, Note, QueryOpts } from "../core/src/types.ts";
 import { TAG_EXPAND_MODES, type TagExpandMode } from "../core/src/tag-hierarchy.ts";
 import { listUnresolvedWikilinks } from "../core/src/wikilinks.ts";
-import { getNote, getNotes, getNoteTags, toNoteIndex, filterMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "../core/src/notes.ts";
+import { getNote, getNotes, getNoteTags, toNoteIndex, filterMetadata, mergeMetadata, MAX_BATCH_SIZE, validateExtension, ExtensionValidationError } from "../core/src/notes.ts";
 import {
   parseContentRange,
   applyContentRange,
@@ -26,6 +26,7 @@ import type { ValidationWarning } from "../core/src/schema-defaults.ts";
 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 {
   buildExpandVisibility,
   filterHydratedLinksByTagScope,
@@ -1652,8 +1653,11 @@ async function handleNotesInner(
         updates.extension = validateExtension(body.extension);
       }
       if (body.metadata !== undefined) {
-        const existing = (note.metadata as Record<string, unknown>) ?? {};
-        updates.metadata = { ...existing, ...body.metadata };
+        // RFC 7386 merge: incoming `null` removes the key (vault#478/#479).
+        updates.metadata = mergeMetadata(
+          note.metadata as Record<string, unknown> | null | undefined,
+          body.metadata as Record<string, unknown>,
+        );
       }
       if (body.created_at !== undefined || body.createdAt !== undefined) {
         updates.created_at = body.created_at ?? body.createdAt;
@@ -2093,12 +2097,27 @@ export async function handleTags(
       fieldsPatch = Object.keys(merged).length > 0 ? merged : null;
     }
 
-    const result = await store.upsertTagRecord(tagName, {
-      ...(body.description !== undefined ? { description: body.description } : {}),
-      ...(fieldsPatch !== undefined ? { fields: fieldsPatch } : {}),
-      ...(relationshipsPatch !== undefined ? { relationships: relationshipsPatch } : {}),
-      ...(parentNamesPatch !== undefined ? { parent_names: parentNamesPatch } : {}),
-    });
+    // A bad indexed-field name (or an unindexable type, or a cross-tag type
+    // mismatch) is a CLIENT error — return 400, not the catch-all 500. The
+    // store pre-validates and is transactional, so the schema is left
+    // unchanged on failure (no orphan/lying index). vault#478.
+    let result;
+    try {
+      result = await store.upsertTagRecord(tagName, {
+        ...(body.description !== undefined ? { description: body.description } : {}),
+        ...(fieldsPatch !== undefined ? { fields: fieldsPatch } : {}),
+        ...(relationshipsPatch !== undefined ? { relationships: relationshipsPatch } : {}),
+        ...(parentNamesPatch !== undefined ? { parent_names: parentNamesPatch } : {}),
+      });
+    } catch (err) {
+      if (err instanceof IndexedFieldError) {
+        return json(
+          { error: err.message, error_type: "invalid_indexed_field" },
+          400,
+        );
+      }
+      throw err;
+    }
     return json(result);
   }
 

package/src/routing.test.ts

@@ -1262,12 +1262,17 @@ describe("/.parachute/config/schema + /.parachute/config", () => {
     expect(body.type).toBe("object");
     expect(body.properties.audio_retention?.type).toBe("string");
     expect(body.properties.audio_retention?.enum).toEqual(["keep", "until_transcribed", "never"]);
-    expect(body.properties.scribe_url?.type).toBe("string");
-    expect(body.properties.scribe_token?.writeOnly).toBe(true);
-    expect(body.properties.port?.readOnly).toBe(true);
+    expect(body.properties.autoTranscribe?.type).toBe("object");
+    // vault#478 scope boundary: daemon-GLOBAL fields are NOT described by the
+    // per-vault admin config schema. The per-vault admin surface is "admin
+    // over *your* vault only" — port / scribe URL / scribe bearer are
+    // deployment-wide and live behind the operator-only surface.
+    expect(body.properties).not.toHaveProperty("scribe_url");
+    expect(body.properties).not.toHaveProperty("scribe_token");
+    expect(body.properties).not.toHaveProperty("port");
   });
 
-  test("config returns current values with writeOnly fields excluded", async () => {
+  test("config returns ONLY per-vault values, never daemon-global ones (scope boundary, vault#478)", async () => {
     createVault("journal");
     const token = await createAdminToken("journal");
     const path = "/vault/journal/.parachute/config";
@@ -1284,13 +1289,22 @@ describe("/.parachute/config/schema + /.parachute/config", () => {
       );
       expect(res.status).toBe(200);
       const body = (await res.json()) as Record<string, unknown>;
+      // Per-vault config is present.
       expect(body.audio_retention).toBe("keep"); // default when unset
-      expect(body.scribe_url).toBe("https://scribe.example/v1");
-      expect(body.port).toBe(1940);
+      expect(body).toHaveProperty("autoTranscribe");
+      // Daemon-GLOBAL values must NOT cross the per-vault admin boundary.
+      expect(body).not.toHaveProperty("port");
+      expect(body).not.toHaveProperty("scribe_url");
+      // The discovery-resolved scribe URL is daemon-global → must not leak,
+      // even nested under autoTranscribe.
+      const at = body.autoTranscribe as Record<string, unknown>;
+      expect(at).not.toHaveProperty("scribeUrl");
       // writeOnly field must not appear in GET.
       expect(body).not.toHaveProperty("scribe_token");
-      // Defense in depth: grep the raw body for the token value.
-      expect(JSON.stringify(body)).not.toContain("super-secret-should-never-appear");
+      // Defense in depth: no daemon-global value (URL or secret) anywhere.
+      const raw = JSON.stringify(body);
+      expect(raw).not.toContain("super-secret-should-never-appear");
+      expect(raw).not.toContain("https://scribe.example/v1");
     } finally {
       if (origScribeToken === undefined) delete process.env.SCRIBE_TOKEN;
       else process.env.SCRIBE_TOKEN = origScribeToken;
@@ -1318,24 +1332,27 @@ describe("/.parachute/config/schema + /.parachute/config", () => {
     expect(body.audio_retention).toBe("until_transcribed");
   });
 
-  test("config scribe_url falls back to empty string when SCRIBE_URL env is unset", async () => {
-    createVault("journal");
+  test("autoTranscribe.enabled reports the per-vault override (vault#478)", async () => {
+    // Server default ON; this vault explicitly opts OUT — the per-vault value
+    // must win, proving the field is reported per-vault (not the raw global).
+    writeGlobalConfig({ port: 1940, auto_transcribe: { enabled: true } });
+    writeVaultConfig({
+      name: "journal",
+      api_keys: [],
+      created_at: new Date().toISOString(),
+      auto_transcribe: { enabled: false },
+    });
     const token = await createAdminToken("journal");
-    const orig = process.env.SCRIBE_URL;
-    delete process.env.SCRIBE_URL;
-    try {
-      const path = "/vault/journal/.parachute/config";
-      const res = await route(
-        new Request(`http://localhost:1940${path}`, {
-          headers: { authorization: `Bearer ${token}` },
-        }),
-        path,
-      );
-      const body = (await res.json()) as { scribe_url: string };
-      expect(body.scribe_url).toBe("");
-    } finally {
-      if (orig !== undefined) process.env.SCRIBE_URL = orig;
-    }
+    const path = "/vault/journal/.parachute/config";
+    const res = await route(
+      new Request(`http://localhost:1940${path}`, {
+        headers: { authorization: `Bearer ${token}` },
+      }),
+      path,
+    );
+    const body = (await res.json()) as { autoTranscribe: { enabled: boolean } };
+    expect(body.autoTranscribe.enabled).toBe(false);
+    writeGlobalConfig({ port: 1940 });
   });
 
   test("unknown vault returns 404 before reaching the config handlers", async () => {

package/src/vault.test.ts

@@ -4012,6 +4012,36 @@ describe("HTTP PATCH /notes/:idOrPath (update)", async () => {
     expect(body.metadata).toEqual({ a: 1, b: 2 });
   });
 
+  test("PATCH metadata null DELETES the key (RFC 7386), not a literal null (vault#478/#479)", async () => {
+    await store.createNote("doc", { id: "x", metadata: { keep: "yes", drop: "old", n: 3 } });
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/x", { metadata: { drop: null }, force: true }),
+      store,
+      "/x",
+    );
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    // Key removed entirely — must NOT survive as a literal JSON null.
+    expect(body.metadata).not.toHaveProperty("drop");
+    expect(body.metadata).toEqual({ keep: "yes", n: 3 });
+    // Persisted state matches the response (round-trips).
+    const fresh = await store.getNote("x");
+    expect(fresh!.metadata).not.toHaveProperty("drop");
+    expect(fresh!.metadata).toEqual({ keep: "yes", n: 3 });
+  });
+
+  test("PATCH metadata key-rename in one call: set new, null-delete old (vault#478)", async () => {
+    await store.createNote("doc", { id: "x", metadata: { "old-key": "v", stable: true } });
+    const res = await handleNotes(
+      mkReq("PATCH", "/notes/x", { metadata: { new_key: "v", "old-key": null }, force: true }),
+      store,
+      "/x",
+    );
+    const body = await res.json() as any;
+    expect(body.metadata).not.toHaveProperty("old-key");
+    expect(body.metadata).toEqual({ new_key: "v", stable: true });
+  });
+
   test("PATCH adds/removes tags", async () => {
     await store.createNote("x", { id: "x", tags: ["old"] });
     const res = await handleNotes(
@@ -4789,6 +4819,28 @@ describe("HTTP /tags", async () => {
       .filter((n) => n.startsWith("meta_"));
   }
 
+  test("PUT /tags/:name with a bad indexed-field name returns 400 + leaves schema unchanged (vault#478)", async () => {
+    // kebab-case indexed field violates [A-Za-z0-9_]. Pre-fix this persisted
+    // the declaration then 500'd on index creation, leaving a tag claiming an
+    // index the engine couldn't build (the "lying schema" loop).
+    const res = await handleTags(
+      mkReq("PUT", "/tags/meeting", { fields: { "meeting-type": { type: "string", indexed: true } } }),
+      store,
+      "/meeting",
+    );
+    expect(res.status).toBe(400);
+    const body = await res.json() as any;
+    expect(body.error_type).toBe("invalid_indexed_field");
+    expect(body.error).toMatch(/invalid field name/);
+
+    // Schema is untouched — no poisoned field declared.
+    const record = await store.getTagRecord("meeting");
+    expect(record?.fields?.["meeting-type"]).toBeUndefined();
+    // No orphan/lying index: neither the generated column nor an indexed_fields row.
+    expect(notesMetaCols()).not.toContain("meta_meeting-type");
+    expect(buildVaultProjection(db).indexed_fields.map((f) => f.name)).not.toContain("meeting-type");
+  });
+
   test("PUT /tags/:name {fields:null} drops the orphaned generated column", async () => {
     // Declare an indexed field via REST PUT — column materializes.
     await handleTags(