@openparachute/vault 0.7.0-rc.3 → 0.7.0-rc.4

package/core/src/contract-typed-index.test.ts

@@ -22,6 +22,7 @@ import { Database } from "bun:sqlite";
 import { SqliteStore } from "./store.js";
 import { generateMcpTools } from "./mcp.js";
 import { TransitionConflictError } from "./notes.js";
+import { TagFieldConflictError } from "./tag-schemas.js";
 
 let store: SqliteStore;
 let db: Database;
@@ -97,10 +98,98 @@ describe("contract: typed indexes — todo (#553)", () => {
   test.todo(
     `#553: an unset enum field stays ABSENT — no first-value backfill — so exists:false correctly matches a note that never set the field (today: applySchemaDefaults in core/src/mcp.ts backfills the schema's first enum value onto every note that gains the tag, so "never set" is indistinguishable from "explicitly set to the default" and exists:false never matches)`,
   );
-  test.todo(
-    `#553: update-tag reports ALL invalid fields in one call AND states explicitly that no changes were applied (today: the cross-tag type/indexed-flag validation loop in core/src/mcp.ts throws on the FIRST offending field and never reports the rest, and the thrown Error's message doesn't say whether the tag's other, valid fields were partially applied — reproduced live: declaring two invalid fields in one update-tag call surfaces only the first field's error)`,
-  );
   test.todo(
     `#553: the indexed-field type list is honest about what's actually indexable (core/src/mcp.ts's update-tag field-type description advertises "string, boolean, integer, number, array, object" but indexed-fields.ts's TYPE_MAP only supports string/integer/boolean — "number" and the container types are accepted as declared but silently un-indexable)`,
   );
 });
+
+describe("contract: update-tag messaging — #553/#554 (flipped from todo)", () => {
+  it("update-tag reports ALL invalid fields in one call (not just the first) and states explicitly that no changes were applied", async () => {
+    // Tag "a" declares two fields. Tag "b" then redeclares BOTH with
+    // conflicting specs — a NON-indexed type conflict on "x" AND an
+    // indexed-flag conflict on "y" — in the SAME update-tag call. Pre-#553
+    // the cross-tag validation loop threw on the first offending field
+    // ("x") and never even evaluated "y"; two testers independently assumed
+    // the whole call (including "y") had partially landed. (The
+    // BOTH-indexed type-conflict case is deliberately absent here — it
+    // keeps its pre-existing declareField → IndexedFieldError path; see
+    // `collectCrossTagFieldViolations`'s doc-comment exclusion 2 and the
+    // both-indexed test below.)
+    await store.upsertTagRecord("a", {
+      fields: {
+        x: { type: "string" },
+        y: { type: "boolean", indexed: true },
+      },
+    });
+
+    const tools = generateMcpTools(store);
+    const updateTag = tools.find((t) => t.name === "update-tag")!;
+
+    let caught: unknown;
+    try {
+      await updateTag.execute({
+        tag: "b",
+        fields: {
+          x: { type: "integer" }, // non-indexed type_conflict vs tag "a"
+          y: { type: "boolean", indexed: false }, // indexed_flag_conflict vs tag "a"
+        },
+      });
+    } catch (e) {
+      caught = e;
+    }
+
+    expect(caught).toBeInstanceOf(TagFieldConflictError);
+    const err = caught as TagFieldConflictError;
+    expect(err.violations).toHaveLength(2);
+    const byField = new Map(err.violations.map((v) => [v.field, v.reason]));
+    expect(byField.get("x")).toBe("type_conflict");
+    expect(byField.get("y")).toBe("indexed_flag_conflict");
+    // States explicitly that no changes were applied.
+    expect(err.message).toContain("no changes were applied");
+    // Structured conflicting-declarer field (scrubbed by the server layer
+    // for tag-scoped sessions; full detail here — core is scope-unaware).
+    expect(err.violations[0]!.other_tag).toBe("a");
+
+    // Nothing partially landed — tag "b" has no field declarations at all.
+    const bRecord = await store.getTagRecord("b");
+    expect(bRecord?.fields ?? null).toBeFalsy();
+  });
+
+  it("a BOTH-indexed cross-tag type conflict keeps its pre-existing IndexedFieldError path (not TagFieldConflictError)", async () => {
+    // Wire-contract floor (vault#554): this exact case already errored on
+    // main via store.upsertTagRecord → declareField's cross-declarer
+    // sqlite-type check → IndexedFieldError (REST maps it to 400
+    // invalid_indexed_field). The new pre-check must not intercept it.
+    await store.upsertTagRecord("a", {
+      fields: { x: { type: "string", indexed: true } },
+    });
+
+    const tools = generateMcpTools(store);
+    const updateTag = tools.find((t) => t.name === "update-tag")!;
+
+    let caught: any;
+    try {
+      await updateTag.execute({
+        tag: "b",
+        fields: { x: { type: "integer", indexed: true } },
+      });
+    } catch (e) {
+      caught = e;
+    }
+
+    expect(caught).toBeDefined();
+    expect(caught).not.toBeInstanceOf(TagFieldConflictError);
+    expect(caught.name).toBe("IndexedFieldError");
+    expect(caught.error_type).toBe("invalid_indexed_field");
+    // The structured declarer context the server's tag-scope scrub keys on.
+    expect(caught.field).toBe("x");
+    expect(caught.declarer_tags).toEqual(["a"]);
+
+    // The store's transaction rolled back — nothing persisted for "b".
+    const bRecord = await store.getTagRecord("b");
+    expect(bRecord?.fields ?? null).toBeFalsy();
+  });
+  // REST `PUT /api/tags/:name` coverage for the same behavior lives in
+  // src/contract-errors.test.ts (core/ shouldn't import from src/ — that
+  // boundary runs one direction only).
+});

package/core/src/indexed-fields.test.ts

@@ -14,6 +14,7 @@ import {
   validateFieldName,
 } from "./indexed-fields.js";
 import { buildVaultProjection } from "./vault-projection.js";
+import { TagFieldConflictError } from "./tag-schemas.js";
 
 let db: Database;
 let store: SqliteStore;
@@ -186,9 +187,17 @@ describe("update-tag: indexed flag", () => {
   it("type conflict across declarers throws and names the other tag", async () => {
     const t = findTool("update-tag");
     await t.execute({ tag: "project", fields: { status: { type: "string", indexed: true } } });
+    // vault#554 wire review: a BOTH-indexed cross-tag type conflict is
+    // deliberately excluded from the update-tag pre-check (see
+    // `collectCrossTagFieldViolations` doc-comment exclusion 2) so it keeps
+    // its pre-existing declareField → IndexedFieldError path — REST maps
+    // that to the established 400 invalid_indexed_field. The declarer is
+    // still named (declareField's message shape), which is this test's
+    // intent; the pre-#554 inline-loop wording (`tag "project" declares
+    // "string"`) is gone along with the loop.
     expect(() =>
       t.execute({ tag: "ticket", fields: { status: { type: "integer", indexed: true } } }),
-    ).toThrow(/tag "project".*"string"/);
+    ).toThrow(/declared by tag\(s\) \[project\]/);
   });
 
   it("indexed-flag conflict across declarers throws", async () => {
@@ -209,12 +218,28 @@ describe("update-tag: indexed flag", () => {
   });
 
   it("invalid field name for indexing throws", async () => {
-    expect(() =>
-      findTool("update-tag").execute({
+    // vault#553/#554: update-tag's cross-tag field validation now collects
+    // EVERY violation into one `TagFieldConflictError` (carrying a
+    // `violations` array) instead of throwing the first `IndexedFieldError`
+    // it hits — see core/src/tag-schemas.ts `collectTagFieldViolations`.
+    // The underlying reason ("invalid_field_name") and message text are
+    // unchanged; only the thrown class + the "collect everything" framing
+    // are new.
+    let caught: unknown;
+    try {
+      await findTool("update-tag").execute({
         tag: "project",
         fields: { "bad-name": { type: "string", indexed: true } },
-      }),
-    ).toThrow(IndexedFieldError);
+      });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(TagFieldConflictError);
+    const err = caught as TagFieldConflictError;
+    expect(err.violations).toHaveLength(1);
+    expect(err.violations[0]!.field).toBe("bad-name");
+    expect(err.violations[0]!.reason).toBe("invalid_field_name");
+    expect(err.message).toContain("no changes were applied");
   });
 
   it("rejects non-atomic indexed-flag change while other declarers hold it true", async () => {

package/core/src/indexed-fields.ts

@@ -45,6 +45,22 @@ interface IndexedFieldRow {
 
 export class IndexedFieldError extends Error {
   override name = "IndexedFieldError";
+  // Stable error_type (vault#554) — additive; matches the string REST has
+  // hardcoded in its json response since vault#478. Lets the generic MCP
+  // domain-error mapping (src/mcp-http.ts) pick this class up.
+  error_type = "invalid_indexed_field" as const;
+  /**
+   * Structured context for the CROSS-DECLARER sqlite-type conflict thrown
+   * by `declareField` (vault#554 auth-and-scope fold): the message names
+   * the other declarer tag(s), which a tag-scoped caller must not learn
+   * when they're outside its allowlist. `declarer_tags` lets the server
+   * layer (`scrubIndexedFieldConflictError` in src/tag-scope.ts) detect
+   * that case and generalize the message. Absent on the solo own-field
+   * throws (invalid name, unsupported type), whose messages name no other
+   * tag.
+   */
+  field?: string;
+  declarer_tags?: string[];
 }
 
 // Restrict field names to safe SQL identifiers. This also bounds the
@@ -172,8 +188,14 @@ export function declareField(
   if (existing.sqliteType !== sqliteType) {
     const others = existing.declarerTags.filter((t) => t !== tag);
     if (others.length > 0) {
-      throw new IndexedFieldError(
-        `field "${field}" is declared by tag(s) [${others.join(", ")}] with sqlite type ${existing.sqliteType}; tag "${tag}" requested ${sqliteType}`,
+      // `field` + `declarer_tags` stamped so the server's tag-scope layer
+      // can generalize this message when a declarer is outside a scoped
+      // caller's allowlist (see IndexedFieldError's doc comment).
+      throw Object.assign(
+        new IndexedFieldError(
+          `field "${field}" is declared by tag(s) [${others.join(", ")}] with sqlite type ${existing.sqliteType}; tag "${tag}" requested ${sqliteType}`,
+        ),
+        { field, declarer_tags: others },
       );
     }
     dropColumnAndIndex(db, field);

package/core/src/mcp.ts

@@ -10,7 +10,6 @@ import { SEARCH_MODES, buildLiteralSearchQuery, isValidSearchMode, type SearchMo
 import * as linkOps from "./links.js";
 import * as tagSchemaOps from "./tag-schemas.js";
 import type { TagFieldSchema } from "./tag-schemas.js";
-import * as indexedFieldOps from "./indexed-fields.js";
 import {
   SchemaValidationError,
   strictViolations,
@@ -53,6 +52,22 @@ export interface McpToolDef {
 // Helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Build a plain `Error` carrying a stable `error_type` (+ optional `field`/
+ * `hint`) as duck-typed extra properties — the same pattern `QueryError`
+ * uses for its optional structured fields. For validation leaves that don't
+ * warrant a dedicated exported class (one caller-facing shape, not a reusable
+ * domain error), this is what lets the generic domain-error mapping in
+ * `src/mcp-http.ts` surface `data.error_type` instead of falling through to
+ * the unstructured `isError: true` text fallback (vault#554).
+ */
+function structuredError(
+  message: string,
+  fields: { error_type: string; field?: string; hint?: string },
+): Error {
+  return Object.assign(new Error(message), fields);
+}
+
 /**
  * Resolve a note identifier — tries ID first, then case-insensitive
  * path match. Works everywhere a note reference is accepted.
@@ -86,7 +101,9 @@ function resolveNote(db: Database, idOrPath: string): Note | null {
 
 function requireNote(db: Database, idOrPath: string): Note {
   const note = resolveNote(db, idOrPath);
-  if (!note) throw new Error(`Note not found: "${idOrPath}"`);
+  if (!note) {
+    throw structuredError(`Note not found: "${idOrPath}"`, { error_type: "not_found", field: "id" });
+  }
   return note;
 }
 
@@ -423,7 +440,7 @@ Response shape (vault#550 — three variants, pick by what you passed):
         // --- Single note by ID/path ---
         if (params.id) {
           const note = resolveNote(db, params.id as string);
-          if (!note) return { error: "Note not found", id: params.id };
+          if (!note) return { error: "Note not found", error_type: "not_found", id: params.id };
           const includeContent = params.include_content !== false; // default true for single
           // Range params are meaningless on a content-less shape — error
           // rather than silently ignore (same loud-validation policy as
@@ -471,7 +488,7 @@ Response shape (vault#550 — three variants, pick by what you passed):
         if (params.near) {
           const near = params.near as { note_id: string; depth?: number; relationship?: string };
           const anchor = resolveNote(db, near.note_id);
-          if (!anchor) return { error: "Anchor note not found", note_id: near.note_id };
+          if (!anchor) return { error: "Anchor note not found", error_type: "not_found", note_id: near.note_id };
           const depth = Math.min(near.depth ?? 2, 5);
           const traversed = linkOps.traverseLinks(db, anchor.id, {
             max_depth: depth,
@@ -914,7 +931,7 @@ Response shape (vault#550 — three variants, pick by what you passed):
 - \`links: { add: [{ target, relationship }], remove: [{ target, relationship }] }\` — add/remove links
 - When removing a wikilink-type link, \`[[brackets]]\` are also removed from content.
 - For batch: pass a \`notes\` array, each with an \`id\` field.
-- **Optimistic concurrency is required by default.** Pass \`if_updated_at\` with the \`updated_at\` value you last read — the update is rejected with a conflict error if the note has changed since. Re-read, reconcile, and retry. To skip the safety check (e.g. bulk migration), pass \`force: true\` instead; the update then runs unconditionally. \`force\` only waives the *requirement to supply* \`if_updated_at\` — if you pass both, the precondition you supplied still applies and a mismatch returns a conflict error. \`append\` / \`prepend\` only updates are exempt from the precondition (no-conflict-by-design).
+- **Optimistic concurrency is required by default.** Pass \`if_updated_at\` with the \`updated_at\` value you last read — the update is rejected with a conflict error if the note has changed since. Re-read, reconcile, and retry. To skip the safety check (e.g. bulk migration), pass \`force: true\` instead; the update then runs unconditionally. \`force\` only waives the *requirement to supply* \`if_updated_at\` — if you pass both, the precondition you supplied still applies and a mismatch returns a conflict error. \`append\` / \`prepend\` only updates are exempt from the precondition (no-conflict-by-design). **Batch default (vault#554):** a top-level \`force\` and/or \`if_updated_at\` alongside a \`notes\` array applies as the DEFAULT for every item that doesn't set its own — e.g. \`{force: true, notes: [{id: "a", content: "..."}, {id: "b", content: "...", if_updated_at: "..."}]}\` forces item "a" but still enforces the precondition on item "b" (its own \`if_updated_at\` wins). Per-item values always take precedence over the top-level default.
 - **Idempotent upsert via \`if_missing: "create"\`** — when the note doesn't exist, create it from this same payload (content/path/tags/metadata become the create fields; OC precondition skipped — nothing to conflict with). Response carries \`created: true\`. Useful for nightly sync loops that don't know ahead of time whether the note exists. Default \`"fail"\` (current behavior — missing note errors). See vault#309.
 - \`include_content\` (default \`true\`) — set \`false\` to receive a lean index shape (\`id\`, \`path\`, \`createdAt\`, \`updatedAt\`, \`createdBy\`, \`createdVia\`, \`lastUpdatedBy\`, \`lastUpdatedVia\`, \`tags\`, \`metadata\`, \`byteSize\`, \`preview\`) instead of full content. Useful for agents making frequent small edits to large notes (e.g. via \`append\` or \`content_edit\`) where re-receiving the body is the dominant cost. \`validation_status\` is preserved on the lean shape when present.
 
@@ -1043,7 +1060,23 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
       },
       execute: async (params) => {
         const batch = params.notes as any[] | undefined;
-        const items = batch ?? [params];
+        // vault#554: top-level `force` / `if_updated_at` apply as per-item
+        // DEFAULTS in a batch call — item-level values win when both are
+        // present. Before this fix `items = batch ?? [params]` never merged
+        // the top-level fields into batch items at all, so a caller passing
+        // `{force: true, notes: [...]}` had it silently ignored: every item
+        // without its OWN `force`/`if_updated_at` still threw
+        // `PreconditionRequiredError` (a gardener-reported round-trip cost).
+        // The single-item form (`items = [params]`) already behaved this
+        // way implicitly (params IS the item), so only the batch branch
+        // needs the merge.
+        const items = batch
+          ? batch.map((item: any) => ({
+              ...(params.force !== undefined ? { force: params.force } : {}),
+              ...(params.if_updated_at !== undefined ? { if_updated_at: params.if_updated_at } : {}),
+              ...item,
+            }))
+          : [params];
 
         if (items.length > MAX_BATCH_SIZE) {
           throw new BatchTooLargeError(items.length);
@@ -1175,7 +1208,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
               // Fallthrough: not-found + no if_missing → existing error
               // contract. Match `requireNote`'s message shape so existing
               // callers see no behavior change.
-              throw new Error(`Note not found: "${item.id}"`);
+              throw structuredError(`Note not found: "${item.id}"`, { error_type: "not_found", field: "id" });
             }
             const note = resolved;
 
@@ -1185,8 +1218,9 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
             const hasContentEdit = item.content_edit !== undefined;
             const contentModes = (hasContent ? 1 : 0) + (hasAppendPrepend ? 1 : 0) + (hasContentEdit ? 1 : 0);
             if (contentModes > 1) {
-              throw new Error(
+              throw structuredError(
                 `update-note: \`content\`, \`append\`/\`prepend\`, and \`content_edit\` are mutually exclusive — pick one mode of content update for note "${note.id}".`,
+                { error_type: "mutually_exclusive", hint: "pass exactly one of `content`, `append`/`prepend`, or `content_edit`" },
               );
             }
 
@@ -1237,20 +1271,23 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
             if (hasContentEdit) {
               const ce = item.content_edit as { old_text: string; new_text: string };
               if (typeof ce?.old_text !== "string" || typeof ce?.new_text !== "string") {
-                throw new Error(
+                throw structuredError(
                   "update-note: `content_edit` requires { old_text: string, new_text: string }.",
+                  { error_type: "invalid_content_edit", field: "content_edit", hint: "pass { old_text: string, new_text: string }" },
                 );
               }
               const idx = note.content.indexOf(ce.old_text);
               if (idx < 0) {
-                throw new Error(
+                throw structuredError(
                   `update-note content_edit: \`old_text\` not found in note "${note.id}". The note may have been edited — re-read and retry.`,
+                  { error_type: "content_edit_not_found", field: "content_edit.old_text", hint: "re-read the note's current content and retry with an old_text that occurs exactly once" },
                 );
               }
               const second = note.content.indexOf(ce.old_text, idx + 1);
               if (second >= 0) {
-                throw new Error(
+                throw structuredError(
                   `update-note content_edit: \`old_text\` matches multiple times in note "${note.id}" — must match exactly once. Add surrounding context to disambiguate.`,
+                  { error_type: "content_edit_ambiguous", field: "content_edit.old_text", hint: "add surrounding context to old_text so it matches exactly once" },
                 );
               }
               contentOverride = note.content.slice(0, idx) + ce.new_text + note.content.slice(idx + ce.old_text.length);
@@ -1315,8 +1352,9 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
             const stItem = item.state_transition as { field?: unknown; from?: unknown; to?: unknown } | undefined;
             if (stItem !== undefined) {
               if (typeof stItem.field !== "string" || stItem.field.length === 0) {
-                throw new Error(
+                throw structuredError(
                   `update-note: \`state_transition.field\` must be a non-empty string (note "${note.id}").`,
+                  { error_type: "invalid_state_transition", field: "state_transition.field", hint: "pass a non-empty string naming the metadata field to transition" },
                 );
               }
               updates.state_transition = { field: stItem.field, from: stItem.from, to: stItem.to };
@@ -1605,34 +1643,13 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
 
         // Validate cross-tag consistency on fields being (re)declared in this
         // call. `type` and `indexed` are global — all declarers must agree.
-        const otherSchemas = tagSchemaOps
-          .listTagSchemas(db)
-          .filter((s) => s.tag !== tag);
-        for (const [fieldName, spec] of Object.entries(incomingFields)) {
-          const incomingIndexed = spec.indexed === true;
-          for (const other of otherSchemas) {
-            const otherSpec = other.fields?.[fieldName];
-            if (!otherSpec) continue;
-            if (otherSpec.type !== spec.type) {
-              throw new Error(
-                `field "${fieldName}" type conflict: tag "${tag}" declares "${spec.type}"; tag "${other.tag}" declares "${otherSpec.type}". Types must agree across all declarers.`,
-              );
-            }
-            if ((otherSpec.indexed === true) !== incomingIndexed) {
-              throw new Error(
-                `field "${fieldName}" indexed-flag conflict: tag "${tag}" sets indexed=${incomingIndexed}; tag "${other.tag}" sets indexed=${otherSpec.indexed === true}. Must match across all declarers — change them atomically or not at all.`,
-              );
-            }
-          }
-          if (incomingIndexed) {
-            const mapped = indexedFieldOps.mapFieldType(spec.type);
-            if (!mapped) {
-              throw new Error(
-                `field "${fieldName}" has unsupported type "${spec.type}" for indexing (supported: string, integer, boolean)`,
-              );
-            }
-            indexedFieldOps.validateFieldName(fieldName);
-          }
+        // vault#553/#554: collects EVERY violation instead of throwing on the
+        // first — a caller declaring two bad fields sees both in one
+        // response, and the thrown error states explicitly that no changes
+        // were applied (nothing is persisted before this check runs).
+        const fieldViolations = tagSchemaOps.collectTagFieldViolations(db, tag, incomingFields);
+        if (fieldViolations.length > 0) {
+          throw new tagSchemaOps.TagFieldConflictError(tag, fieldViolations);
         }
 
         // ---- relationships: replace wholesale when provided. `relationships`
@@ -1655,7 +1672,11 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
           parentNamesPatch = null;
         } else if (params.parent_names !== undefined) {
           if (!Array.isArray(params.parent_names)) {
-            throw new Error("parent_names must be an array of tag names");
+            throw structuredError("parent_names must be an array of tag names", {
+              error_type: "invalid_parent_names",
+              field: "parent_names",
+              hint: "pass an array of tag name strings, or null to clear",
+            });
           }
           const cleaned = (params.parent_names as unknown[])
             .filter((p): p is string => typeof p === "string" && p.length > 0);
@@ -1762,7 +1783,7 @@ Write-attribution (vault#298): every result carries \`createdBy\`/\`createdVia\`
       execute: () => {
         // This is a placeholder — vault-info needs access to vault config,
         // which is only available in the server layer (mcp-tools.ts).
-        return { error: "vault-info must be configured by the server layer" };
+        return { error: "vault-info must be configured by the server layer", error_type: "not_configured" };
       },
     },
 
@@ -1994,6 +2015,9 @@ export class PreconditionRequiredError extends Error {
  */
 export class BatchTooLargeError extends Error {
   code = "BATCH_TOO_LARGE" as const;
+  // Stable error_type (vault#554) — additive; matches the string REST has
+  // hardcoded in its json response since #213.
+  error_type = "batch_too_large" as const;
   limit: number;
   got: number;
 

package/core/src/notes.ts

@@ -284,6 +284,11 @@ export class TransitionConflictError extends Error {
  */
 export class PathConflictError extends Error {
   code = "PATH_CONFLICT" as const;
+  // Stable error_type (vault#554) — additive; mirrors the `error_type` REST
+  // has hardcoded in its json response since #126. Lets the generic MCP
+  // domain-error mapping (src/mcp-http.ts) pick this class up without a
+  // bespoke branch, the same way REST's catch already does explicitly.
+  error_type = "path_conflict" as const;
   path: string;
 
   constructor(path: string) {
@@ -306,6 +311,8 @@ export class PathConflictError extends Error {
  */
 export class AmbiguousPathError extends Error {
   code = "AMBIGUOUS_PATH" as const;
+  // Stable error_type (vault#554) — see PathConflictError's comment.
+  error_type = "ambiguous_path" as const;
   path: string;
   candidates: { id: string; extension: string }[];
 
@@ -346,6 +353,8 @@ export const EXTENSION_PATTERN = /^[a-z0-9]{1,16}$/;
 
 export class ExtensionValidationError extends Error {
   code = "INVALID_EXTENSION" as const;
+  // Stable error_type (vault#554) — see PathConflictError's comment.
+  error_type = "invalid_extension" as const;
   extension: string;
   reason: string;