@openparachute/vault 0.6.3 → 0.6.4-rc.10

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,16 +14,19 @@
 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,
   contentRangeRequiresContent,
   type ContentRange,
 } from "../core/src/content-range.ts";
-import { attachValidationStatus } from "../core/src/mcp.ts";
+import { attachValidationStatus, enforceStrictWrite } from "../core/src/mcp.ts";
+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,
@@ -44,6 +47,52 @@ import { findTokensReferencingTag } from "./token-store.ts";
 export type TagScopeCtx = { allowed: Set<string> | null; raw: string[] | null };
 
 const NO_TAG_SCOPE: TagScopeCtx = { allowed: null, raw: null };
+
+/**
+ * Write-attribution context (vault#298) for REST writes — the principal
+ * (`actor`) and interface (`via`) threaded from the authenticated request into
+ * `store.createNote` / `store.updateNote`. Both null for paths without an auth
+ * context (the no-op default). See `WriteContext` in core/src/notes.ts.
+ */
+export type WriteCtx = {
+  actor: string | null;
+  via: string | null;
+  /**
+   * Migration-bypass (vault#299). True when the caller holds `vault:migrate`
+   * — strict-schema enforcement is skipped and the bypass is logged. Defaults
+   * to false (full enforcement) for every normal write.
+   */
+  bypassStrict?: boolean;
+};
+
+const NO_WRITE_CTX: WriteCtx = { actor: null, via: null };
+
+/**
+ * Run the shared strict-schema gate for a REST write (vault#299). Mirrors the
+ * MCP path's `enforceStrict` closure: enforce unless the caller holds the
+ * migration-bypass scope, and log every bypassed write to the daemon's
+ * structured log (the audit-log table, #300, is deferred). Throws
+ * `SchemaValidationError` (caught by the route's catch → 422) when not bypassed.
+ */
+function gateStrictWrite(
+  store: Store,
+  writeCtx: WriteCtx,
+  shape: { path?: string | null; tags?: string[]; metadata?: Record<string, unknown> },
+): void {
+  enforceStrictWrite(store, shape, {
+    bypass: writeCtx.bypassStrict === true,
+    onBypass: (violations: ValidationWarning[]) => {
+      logStrictBypass({
+        actor: writeCtx.actor,
+        via: writeCtx.via,
+        path: shape.path ?? null,
+        tags: shape.tags,
+        violations,
+      });
+    },
+  });
+}
+
 import {
   expandContent,
   DEFAULT_EXPAND_DEPTH,
@@ -279,7 +328,7 @@ function parseMetaBrackets(url: URL): {
         return {
           error: json(
             {
-              error: `bracket-date filter on \`${field}\` supports only \`gte\` (inclusive lower bound) and \`lt\` (exclusive upper bound). Got: \`${op}\`. The dateFilter contract uses these two ops because the equivalent flat shape (\`date_field=${field}&date_from=…&date_to=…\`) is half-open by design.`,
+              error: `bracket-date filter on \`${field}\` supports only \`gte\` (inclusive lower bound) and \`lt\` (exclusive upper bound). Got: \`${op}\`. The dateFilter contract is half-open by design.`,
               code: "INVALID_QUERY",
             },
             400,
@@ -567,20 +616,20 @@ export function parseNotesQueryOpts(url: URL): {
     pathPrefix: parseQuery(url, "path_prefix") ?? undefined,
     extension: parseExtensionFilter(url),
     metadata: bracket.metadata ?? metadataAlias.metadata,
-    ...(bracket.dateFilter
-      ? { dateFilter: bracket.dateFilter }
-      : parseQuery(url, "date_field")
-        ? {
-            dateFilter: {
-              field: parseQuery(url, "date_field")!,
-              from: parseQuery(url, "date_from") ?? undefined,
-              to: parseQuery(url, "date_to") ?? undefined,
-            },
-          }
-        : {
-            dateFrom: parseQuery(url, "date_from") ?? undefined,
-            dateTo: parseQuery(url, "date_to") ?? undefined,
-          }),
+    // Write-attribution filters (vault#298) — symmetric with the MCP
+    // query-notes tool so a REST caller can ask "what did Mathilda write" /
+    // "what came in via the meeting-ingest surface" the same way.
+    createdBy: parseQuery(url, "created_by") ?? undefined,
+    lastUpdatedBy: parseQuery(url, "last_updated_by") ?? undefined,
+    createdVia: parseQuery(url, "created_via") ?? undefined,
+    lastUpdatedVia: parseQuery(url, "last_updated_via") ?? undefined,
+    // Date-range filtering on the query string is bracket-style only:
+    // `?meta[created_at][gte]=…&meta[created_at][lt]=…` (see
+    // `parseMetaBrackets`). The flat `date_field` / `date_from` / `date_to`
+    // params were removed in 0.6.4 (vault#288, breaking) — they are now
+    // ignored. The MCP `date_from` / `date_to` shorthand is a separate,
+    // supported convenience and is unaffected.
+    ...(bracket.dateFilter ? { dateFilter: bracket.dateFilter } : {}),
     sort: (parseQuery(url, "sort") as "asc" | "desc") ?? undefined,
     orderBy: parseQuery(url, "order_by") ?? undefined,
     limit: parseInt10(parseQuery(url, "limit")) ?? 50,
@@ -704,9 +753,10 @@ export async function handleNotes(
   subpath: string,
   vault?: string,
   tagScope: TagScopeCtx = NO_TAG_SCOPE,
+  writeCtx: WriteCtx = NO_WRITE_CTX,
 ): Promise<Response> {
   try {
-    return await handleNotesInner(req, store, subpath, vault, tagScope);
+    return await handleNotesInner(req, store, subpath, vault, tagScope, writeCtx);
   } catch (e: any) {
     const ambig = ambiguousPathResponse(e);
     if (ambig) return ambig;
@@ -720,6 +770,7 @@ async function handleNotesInner(
   subpath: string,
   vault?: string,
   tagScope: TagScopeCtx = NO_TAG_SCOPE,
+  writeCtx: WriteCtx = NO_WRITE_CTX,
 ): Promise<Response> {
   const url = new URL(req.url);
   const method = req.method;
@@ -849,7 +900,7 @@ async function handleNotesInner(
 
       // Structured query
       //
-      // Two filter syntaxes coexist on this endpoint:
+      // Date-range filtering on the query string uses one syntax:
       //
       //   - **Bracket-style** (canonical, vault#285 friction point 1.3):
       //     `?meta[field][op]=value` / `?meta[created_at][gte]=…`. Exposes
@@ -857,21 +908,18 @@ async function handleNotesInner(
       //     not_in/exists) and the dateFilter bridge through one consistent
       //     shape. See `parseMetaBrackets` for the grammar.
       //
-      //   - **Flat date params** (DEPRECATED): `?date_field=created_at&
-      //     date_from=…&date_to=…` and the legacy `?date_from=…&date_to=…`.
-      //     Still functional through 0.5.x; planned removal in a later 0.x
-      //     (vault#288). New consumers should use bracket-style.
-      //
-      // Precedence on overlap: bracket-style wins. If a caller passes both
-      // `meta[created_at][gte]=X` and `date_field=created_at&date_from=Y`,
-      // the bracket form is the dateFilter the engine sees; the flat
-      // params are silently dropped. We don't error — the bracket form is
-      // documented as canonical, and rejecting the overlap would block a
-      // realistic migration path where a caller half-converted their code.
+      // The flat date params (`?date_field=created_at&date_from=…&date_to=…`
+      // and the legacy bare `?date_from=…&date_to=…`) were REMOVED in 0.6.4
+      // (vault#288, breaking change). They are now silently ignored — a
+      // request that passes only flat date params comes back unfiltered.
+      // Bracket-style is functionally complete (full operator set), so no
+      // capability was lost. Migrate `date_field=created_at&date_from=X` to
+      // `meta[created_at][gte]=X` (and `date_to=Y` to `meta[created_at][lt]=Y`).
       //
       // Surface asymmetry: REST flattens to a query string; MCP takes a
-      // nested `date_filter: { field, from, to }` object directly. Both
-      // lower to the same store-level `dateFilter` shape.
+      // nested `date_filter: { field, from, to }` object directly (plus a
+      // top-level `date_from` / `date_to` shorthand, which is unaffected by
+      // this removal). Both lower to the same store-level `dateFilter` shape.
       // Structured-query parsing is shared with the live `/subscribe` route
       // (see `parseNotesQueryOpts`) so both endpoints lower an identical query
       // string to the same `QueryOpts` — predicate parity by construction.
@@ -1102,6 +1150,13 @@ async function handleNotesInner(
           const extension = item.extension !== undefined
             ? validateExtension(item.extension)
             : undefined;
+          // Strict-schema gate (vault#299) — reject before any write so a
+          // mid-batch violation rolls back via the outer BEGIN/ROLLBACK.
+          gateStrictWrite(store, writeCtx, {
+            path: item.path,
+            tags: item.tags,
+            metadata: item.metadata,
+          });
           const note = await store.createNote(item.content ?? "", {
             id: item.id,
             path: item.path,
@@ -1109,6 +1164,9 @@ async function handleNotesInner(
             metadata: item.metadata,
             created_at: item.createdAt ?? item.created_at,
             ...(extension !== undefined ? { extension } : {}),
+            // Write-attribution (vault#298) — REST batch create.
+            actor: writeCtx.actor,
+            via: writeCtx.via,
           });
 
           // Create explicit links
@@ -1131,6 +1189,13 @@ async function handleNotesInner(
             409,
           );
         }
+        // Strict-schema rejection (vault#299 Part A) on create — 422.
+        if (e && e.code === "SCHEMA_VALIDATION") {
+          return json(
+            { error_type: "schema_validation", error: "schema_validation", violations: e.violations ?? [], message: e.message },
+            422,
+          );
+        }
         if (e && e.code === "INVALID_EXTENSION") {
           return json(
             { error_type: "invalid_extension", error: "invalid_extension", extension: e.extension, reason: e.reason, message: e.message },
@@ -1383,8 +1448,17 @@ async function handleNotesInner(
             ...(body.created_at !== undefined ? { created_at: body.created_at as string } : {}),
             ...(body.createdAt !== undefined ? { created_at: body.createdAt as string } : {}),
             ...(createExt !== undefined ? { extension: createExt } : {}),
+            // Write-attribution (vault#298) — REST upsert-create branch.
+            actor: writeCtx.actor,
+            via: writeCtx.via,
           };
           const content = (body.content as string | undefined) ?? "";
+          // Strict-schema gate (vault#299) — if_missing:"create" is a create.
+          gateStrictWrite(store, writeCtx, {
+            path: createOpts.path ?? undefined,
+            tags: createOpts.tags,
+            metadata: createOpts.metadata,
+          });
           const created = await store.createNote(content, createOpts);
           if (tagsArr.length > 0) {
             await applySchemaDefaults(store, db, [created.id], tagsArr);
@@ -1474,7 +1548,19 @@ async function handleNotesInner(
         && body.createdAt === undefined
         && body.tags === undefined
         && body.links === undefined;
-      if (!isAppendOnly && body.if_updated_at === undefined && body.force !== true) {
+      // A state_transition is itself a compare-and-set precondition (vault#299
+      // Part B) — a transition-only PATCH needs no if_updated_at/force.
+      const isTransitionOnly = body.state_transition !== undefined
+        && !hasContent
+        && !hasAppendPrepend
+        && !hasContentEdit
+        && body.path === undefined
+        && body.metadata === undefined
+        && body.created_at === undefined
+        && body.createdAt === undefined
+        && body.tags === undefined
+        && body.links === undefined;
+      if (!isAppendOnly && !isTransitionOnly && body.if_updated_at === undefined && body.force !== true) {
         return json(
           {
             error_type: "precondition_required",
@@ -1557,8 +1643,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;
@@ -1566,8 +1655,39 @@ async function handleNotesInner(
       if (body.if_updated_at !== undefined) {
         updates.if_updated_at = body.if_updated_at;
       }
+      // Compare-and-set state transition (vault#299 Part B). Combinable with
+      // other field updates; folds into the same atomic UPDATE.
+      const stBody = body.state_transition as { field?: unknown; from?: unknown; to?: unknown } | undefined;
+      if (stBody !== undefined) {
+        if (typeof stBody.field !== "string" || stBody.field.length === 0) {
+          return json(
+            { error: "bad_request", message: "`state_transition.field` must be a non-empty string." },
+            400,
+          );
+        }
+        updates.state_transition = { field: stBody.field, from: stBody.from, to: stBody.to };
+      }
+
+      // --- Strict-schema gate (vault#299 Part A) ---
+      // Validate the PROSPECTIVE shape (final tags + merged metadata, incl. a
+      // state_transition's `to`) before the write so a rejection leaves the
+      // note untouched. Throws SchemaValidationError → 422 in the catch.
+      {
+        const removeSet = new Set<string>((body.tags?.remove as string[] | undefined) ?? []);
+        const projectedTags = new Set<string>((note.tags ?? []).filter((t) => !removeSet.has(t)));
+        for (const t of (body.tags?.add as string[] | undefined) ?? []) projectedTags.add(t);
+        const baseMeta = updates.metadata ?? ((note.metadata as Record<string, unknown>) ?? {});
+        const projectedMeta = stBody !== undefined
+          ? { ...baseMeta, [stBody.field as string]: stBody.to }
+          : baseMeta;
+        gateStrictWrite(store, writeCtx, { path: note.path, tags: [...projectedTags], metadata: projectedMeta });
+      }
 
       if (Object.keys(updates).length > 0) {
+        // Write-attribution (vault#298) — REST update. Stamp the most-recent-
+        // write columns on the same UPDATE that bumps updated_at.
+        updates.actor = writeCtx.actor;
+        updates.via = writeCtx.via;
         await store.updateNote(note.id, updates);
       }
 
@@ -1661,6 +1781,39 @@ async function handleNotesInner(
           409,
         );
       }
+      // State-transition compare-and-set conflict (vault#299 Part B). A
+      // DISTINCT error vocabulary from `conflict` (settled lead #3): the
+      // field VALUE didn't match `from`, not the updated_at token. 409.
+      if (e && e.code === "TRANSITION_CONFLICT") {
+        return json(
+          {
+            error_type: "transition_conflict",
+            error: "transition_conflict",
+            note_id: e.note_id,
+            path: e.note_path ?? null,
+            field: e.field,
+            expected_from: e.expected_from,
+            to: e.to,
+            current: e.current ?? null,
+            message: e.message,
+          },
+          409,
+        );
+      }
+      // Strict-schema rejection (vault#299 Part A). One error carrying ALL
+      // per-field violations (settled lead #1). 422 Unprocessable Entity —
+      // the note exists / request is well-formed but violates the contract.
+      if (e && e.code === "SCHEMA_VALIDATION") {
+        return json(
+          {
+            error_type: "schema_validation",
+            error: "schema_validation",
+            violations: e.violations ?? [],
+            message: e.message,
+          },
+          422,
+        );
+      }
       // Path-rename collision — schema's UNIQUE(path) tripped. Issue #126.
       if (e && e.code === "PATH_CONFLICT") {
         return json(
@@ -1934,12 +2087,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);
   }