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

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.6",
   "description": "Agent-native knowledge graph. Notes, tags, links over MCP.",
   "module": "src/cli.ts",
   "type": "module",

package/src/import-daemon-busy.test.ts

@@ -15,30 +15,21 @@ import { resolve } from "path";
 import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
+import { runSubprocess } from "./test-support/spawn.ts";
 
 const CLI = resolve(import.meta.dir, "cli.ts");
 
+// Async spawn — the daemon-busy probe inside the CLI fetches the test
+// process's stub server, so the parent event loop must keep servicing
+// requests while the child runs. `Bun.spawnSync` blocks the event loop and
+// the in-test server can't answer, which makes every probe time out into
+// the "not listening" branch (vault#324). `runSubprocess` is the shared
+// safe primitive (vault#325 Part 1) — see src/test-support/spawn.ts.
 async function runCli(
   args: string[],
   env: Record<string, string>,
 ): Promise<{ exitCode: number; stdout: string; stderr: string }> {
-  // Async spawn — the daemon-busy probe inside the CLI fetches the test
-  // process's stub server, so the parent event loop must keep servicing
-  // requests while the child runs. Bun.spawnSync blocks the event loop
-  // and the in-test server can't answer, which makes every probe time
-  // out into the "not listening" branch.
-  const proc = Bun.spawn({
-    cmd: ["bun", CLI, ...args],
-    stdout: "pipe",
-    stderr: "pipe",
-    env: { ...process.env, ...env },
-  });
-  const [stdout, stderr, exitCode] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-    proc.exited,
-  ]);
-  return { exitCode: exitCode ?? -1, stdout, stderr };
+  return runSubprocess({ cmd: ["bun", CLI, ...args], env });
 }
 
 let home: string;

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

@@ -0,0 +1,82 @@
+/**
+ * Opt-in scale smoke (vault#325 Part 3).
+ *
+ * Guards the synthetic scale harness against bit-rot WITHOUT slowing the
+ * default `bun test` gate. The real benchmark lives in
+ * `scripts/scale-bench.ts` (10k / 50k / 100k); this is a fast, tiny-size
+ * functional smoke of the same hot-path code so a green CI run still
+ * proves the harness paths execute end-to-end.
+ *
+ * SKIPPED BY DEFAULT. To run it:
+ *
+ *   VAULT_SCALE_BENCH=1 bun test ./src/scale.bench.test.ts
+ *
+ * For real timings + the documented ceiling, run the standalone harness:
+ *
+ *   bun scripts/scale-bench.ts          # 10000 50000 100000
+ *
+ * See docs/SCALE.md.
+ */
+
+import { describe, test, expect } from "bun:test";
+import { Database } from "bun:sqlite";
+import { BunSqliteStore } from "../core/src/store.ts";
+import { generateMcpTools } from "../core/src/mcp.ts";
+import { exportVaultToDir } from "../core/src/portable-md.ts";
+import type { BulkNoteInput } from "../core/src/notes.ts";
+import { mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+const ENABLED = process.env.VAULT_SCALE_BENCH === "1";
+
+// `describe.skipIf` keeps the suite registered (so it shows in the test list)
+// but contributes zero runtime to the default gate. Size is intentionally
+// tiny — this is a functional smoke, not a timing run.
+describe.skipIf(!ENABLED)("scale harness smoke (opt-in: VAULT_SCALE_BENCH=1)", () => {
+  test("seed + hot-path queries + export run at small N", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "vault-scale-smoke-"));
+    const db = new Database(join(dir, "smoke.db"));
+    const store = new BunSqliteStore(db);
+    try {
+      const N = 500;
+
+      // Declare the indexed field via the update-tag tool (the owner of the
+      // indexed_fields lifecycle — mirrors scripts/scale-bench.ts).
+      const tools = generateMcpTools(store);
+      const updateTag = tools.find((t) => t.name === "update-tag");
+      expect(updateTag).toBeDefined();
+      await updateTag!.execute({
+        tag: "work",
+        fields: { status: { type: "string", indexed: true } },
+      });
+
+      const inputs: BulkNoteInput[] = Array.from({ length: N }, (_, i) => ({
+        id: `note-${i}`,
+        path: `notes/note-${i}`,
+        content: `# Note ${i}\n\nconsectetur body ${i}`,
+        tags: i % 3 === 0 ? ["work", "work/meeting"] : ["health"],
+        metadata: { status: i % 2 === 0 ? "active" : "done", seq: i },
+      }));
+      await store.createNotes(inputs);
+
+      // Hot paths — same shapes the standalone harness times.
+      expect((await store.queryNotes({ tags: ["health"], limit: 50 })).length).toBeGreaterThan(0);
+      expect(
+        (await store.queryNotes({ metadata: { status: { eq: "active" } }, limit: 50 })).length,
+      ).toBeGreaterThan(0);
+      expect((await store.queryNotes({ orderBy: "status", limit: 50 })).length).toBe(50);
+      expect((await store.searchNotes("consectetur", { limit: 50 })).length).toBeGreaterThan(0);
+
+      const stats = await exportVaultToDir(store, {
+        outDir: join(dir, "export"),
+        vaultName: "smoke",
+        exportedAt: "2026-01-01T00:00:00Z",
+      });
+      expect(stats.notes).toBe(N);
+    } finally {
+      db.close();
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/src/test-support/spawn.ts

@@ -0,0 +1,85 @@
+/**
+ * Shared subprocess helper for tests (vault#325 Part 1).
+ *
+ * THE RULE — never `Bun.spawnSync` in a test that keeps an in-process
+ * `Bun.serve` listening for the child to probe.
+ *
+ * `Bun.spawnSync` blocks the parent's event loop until the child exits.
+ * If the child makes an HTTP request back to a server the *same test
+ * process* is hosting (e.g. the CLI's daemon-busy pre-flight fetching a
+ * stub `/health`), the parent can't answer — the child's request times
+ * out into the "nothing listening" branch and the assertion silently
+ * tests the wrong path (the guard never fires, or fails for a non-obvious
+ * reason). This bit the daemon-busy import guard; the fix landed in
+ * vault#324 (`src/import-daemon-busy.test.ts`) and this helper is the
+ * institutional-memory follow-up so future subprocess tests reach for the
+ * safe primitive by default.
+ *
+ * `runSubprocess` uses async `Bun.spawn` + `await proc.exited`, so the
+ * parent's event loop keeps servicing requests while the child runs.
+ *
+ * NOTE on what's *fine*: `Bun.spawnSync` is safe in tests that don't run
+ * an in-test server the child talks to over HTTP — e.g. shelling out to
+ * `git` to build a fixture repo (`mirror-*.test.ts`), or a `Bun.serve`
+ * that merely *holds a port* so the child's `lsof`/availability probe
+ * sees it occupied (`doctor.test.ts`). The deadlock is specifically
+ * "child fetches the parent test process's server." When in doubt, use
+ * this helper — it's never wrong, only sometimes unnecessary.
+ */
+
+export interface RunSubprocessResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+export interface RunSubprocessOptions {
+  cmd: string[];
+  cwd?: string;
+  /** Extra env merged over `process.env`. `undefined` values delete the key. */
+  env?: Record<string, string | undefined>;
+  /** Optional bytes piped to the child's stdin. */
+  stdin?: string;
+}
+
+/**
+ * Run a subprocess WITHOUT blocking the event loop.
+ *
+ * Drop-in for the `Bun.spawnSync({ cmd, env, stdout, stderr })` pattern
+ * that recurs across the CLI integration tests, but built on async
+ * `Bun.spawn` so an in-process `Bun.serve` the child probes can still
+ * answer. Returns once the child has exited, with decoded stdout/stderr.
+ */
+export async function runSubprocess(
+  opts: RunSubprocessOptions,
+): Promise<RunSubprocessResult> {
+  const env: Record<string, string> = { ...(process.env as Record<string, string>) };
+  if (opts.env) {
+    for (const [k, v] of Object.entries(opts.env)) {
+      if (v === undefined) delete env[k];
+      else env[k] = v;
+    }
+  }
+
+  const proc = Bun.spawn({
+    cmd: opts.cmd,
+    cwd: opts.cwd,
+    env,
+    stdin: opts.stdin === undefined ? undefined : "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  if (opts.stdin !== undefined) {
+    proc.stdin!.write(opts.stdin);
+    await proc.stdin!.end();
+  }
+
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+
+  return { exitCode: exitCode ?? -1, stdout, stderr };
+}

package/src/vault.test.ts

@@ -1393,6 +1393,99 @@ describe("scoped MCP wrapper", async () => {
     closeAllStores();
   });
 
+  // -- Q6 through the MCP TRANSPORT (vault#325 Part 2) --------------------
+  //
+  // The two tests above call `tool.execute()` directly — that exercises the
+  // tag-scope WRAPPER but bypasses `handleScopedMcp`: the JSON-RPC transport,
+  // the `hasScopeForVault` tool-visibility gate, and the tools/call dispatch.
+  // The HTTP-layer twin lives in `routing.test.ts` (Q6 read-path). What was
+  // missing — and what this pins — is the orphan-sub-tag fail-open driven
+  // through the actual MCP `tools/call` path a real client hits. Same fixture
+  // as the HTTP test (`#health/food` with no `_tags/health/food` schema,
+  // token allowlisted for `health`), different transport.
+
+  test("MCP query-notes (tools/call) sees orphan sub-tag via string-form root (vault#325 Part 2)", async () => {
+    const { handleScopedMcp } = await import("./mcp-http.ts");
+    const { writeVaultConfig } = await import("./config.ts");
+    const { getVaultStore, closeAllStores } = await import("./vault-store.ts");
+
+    const vaultName = `mcp-orphan-query-${Date.now()}`;
+    writeVaultConfig({ name: vaultName, api_keys: [], created_at: new Date().toISOString() });
+    const store = getVaultStore(vaultName);
+    // No `_tags/health/food` schema — this is the orphan case. The hierarchy
+    // is implicit, so authorization must fall back to the string-form root.
+    const orphan = await store.createNote("orphan", { tags: ["health/food"] });
+
+    const auth = {
+      permission: "read" as const,
+      scopes: ["vault:read"],
+      legacyDerived: false,
+      scoped_tags: ["health"],
+    };
+
+    // The URL is inert here — handleScopedMcp hands it to the SDK
+    // transport, which only reads the body; the `vaultName` route wiring
+    // is exercised by routing.test.ts, not this transport-level test. The
+    // `accept` header is load-bearing: `enableJsonResponse` returns JSON
+    // only when text/event-stream is also acceptable, else it streams SSE.
+    const callReq = (id: number, name: string, args: Record<string, unknown>) =>
+      new Request(`http://localhost:1940/vault/${vaultName}/mcp`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          accept: "application/json, text/event-stream",
+        },
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id,
+          method: "tools/call",
+          params: { name, arguments: args },
+        }),
+      });
+
+    // Fetch the orphan by id through the MCP transport with a token scoped
+    // to ["health"]. The orphan is tagged `health/food` (no schema) → the
+    // string-form fallback resolves the root `health` → in allowlist → the
+    // note must come back rather than 404/forbidden.
+    const res = await handleScopedMcp(callReq(1, "query-notes", { id: orphan.id }), vaultName, auth as any);
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as any;
+    // tools/call returns content[].text with the JSON-stringified tool result.
+    expect(body.result?.isError).toBeFalsy();
+    const text: string = body.result.content[0].text;
+    const parsed = JSON.parse(text);
+    expect(parsed.id).toBe(orphan.id);
+    expect(parsed.tags).toContain("health/food");
+
+    // Control: a token scoped to a DIFFERENT root must NOT see the orphan
+    // through the same transport — proves the green result above is the
+    // fail-open fallback firing, not scoping being inert.
+    const denied = {
+      permission: "read" as const,
+      scopes: ["vault:read"],
+      legacyDerived: false,
+      scoped_tags: ["work"],
+    };
+    const resDenied = await handleScopedMcp(
+      callReq(2, "query-notes", { id: orphan.id }),
+      vaultName,
+      denied as any,
+    );
+    expect(resDenied.status).toBe(200);
+    const deniedBody = (await resDenied.json()) as any;
+    const deniedText: string = deniedBody.result.content[0].text;
+    const deniedParsed = JSON.parse(deniedText);
+    // Out-of-scope single-note fetch fails closed: the wrapper replaces the
+    // note body with `{ error: "Note not found" }` (no content/tags leak).
+    // This proves the `health`-scoped green result above is the fail-open
+    // string-form fallback firing, not the wrapper being a no-op.
+    expect(deniedParsed.error).toBe("Note not found");
+    expect(deniedParsed.content).toBeUndefined();
+    expect(deniedParsed.tags).toBeUndefined();
+
+    closeAllStores();
+  });
+
   // -- Q5: MCP delete-tag dependency check -------------------------------
 
   test("MCP delete-tag returns tag_in_use_by_tokens when a vestigial tag-scoped token row references the tag", async () => {
@@ -4012,6 +4105,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 +4912,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(