@feniix/bridgekit 0.7.0 → 0.8.1

package/CHANGELOG.md

@@ -4,7 +4,92 @@ All notable changes to `@feniix/bridgekit` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.7.0] - Unreleased
+## [0.8.1] - Unreleased
+
+### Fixed
+
+- Union-of-objects validation no longer surfaces phantom missing-required-
+  property entries for every branch. When TypeBox emits an `anyOf`/`oneOf`
+  error at a path, sibling `required`/`additionalProperties` entries at the
+  same path are now suppressed so consumers see only the union summary.
+  `const`/`enum` discriminator errors at deeper paths are kept (they're
+  signal about which branch was intended).
+  Resolves [#35](https://github.com/feniix/bridgekit/issues/35).
+
+## [0.8.0] - 2026-05-26
+
+### Breaking
+
+- **`PortableValidationError` renamed `path` → `field`.** No deprecation alias.
+  Update assertions accordingly. `field` is derived from TypeBox's structured
+  error data, not the localized message string. Resolves
+  [#33](https://github.com/feniix/bridgekit/issues/33).
+
+  ```ts
+  // Before (0.7 and earlier)
+  assert.equal(result.structuredContent.validationErrors[0].path, "/file_path");
+
+  // After (0.8+)
+  assert.equal(result.structuredContent.validationErrors[0].field, "file_path");
+  ```
+
+  Entries *inside* `validationErrors[]` share the `{ field, message }` shape
+  with handler-emitted domain-failure data so iteration code can read `.field`
+  uniformly. The `validationErrors[]` array itself only exists on the
+  `kind: "validation"` branch of `PortableToolErrorDetails` — always narrow
+  with `isValidationFailure` (or the discriminator) before iterating.
+
+- **`validationErrors[]` cardinality change.** Previously, a TypeBox error
+  with the message `must have required properties X, Y` produced a single
+  `PortableValidationError` whose message listed all missing props. Now,
+  `executePortableTool` emits **one `PortableValidationError` per missing
+  property**, with `field` set to the missing prop name and `message`
+  normalized to `must have required property <field>`. Consumers asserting
+  `validationErrors.length === 1` for a multi-prop missing case will break.
+
+  ```ts
+  // Schema: Type.Object({ file_path: Type.String(), count: Type.Number() })
+  // Args: {}
+
+  // Before (0.7)
+  // validationErrors.length === 1
+  // validationErrors[0] === { path: "/", message: "must have required properties file_path, count" }
+
+  // After (0.8+)
+  // validationErrors.length === 2
+  // validationErrors === [
+  //   { field: "file_path", message: "must have required property file_path" },
+  //   { field: "count",     message: "must have required property count"     },
+  // ]
+  ```
+
+- **Duplicate `(field, message)` pairs are deduplicated.** Union/discriminator
+  mismatches previously emitted multiple identical `(field, message)` entries
+  (one per failed union branch); they are now collapsed. Dedup only removes
+  entries — it never introduces new ones — so `validationErrors.length` can
+  only decrease relative to raw TypeBox output. Consumers locking in exact
+  counts on union failures may need to adjust.
+
+### Notes on field derivation
+
+- `field` is derived from TypeBox's structured error:
+  - `keyword === "required"` reads `params.requiredProperties` and emits one
+    entry per missing prop name.
+  - `keyword === "additionalProperties"` reads `params.additionalProperties`
+    and emits one entry per offending key name. (Previously fell back to the
+    `(root)` sentinel — the offending key is now surfaced as `field`.)
+  - Other errors take the last meaningful segment of `instancePath`
+    (e.g. `/text` → `"text"`, `/items/0/name` → `"name"`).
+- The structured-access path is locale- and message-format-independent.
+- For array-element validation, `field` is the leaf segment, which can be a
+  numeric index (e.g. `field: "0"`) and loses the path context. If positional
+  information matters, keep schemas permissive at the BridgeKit boundary and
+  validate positionally in your handler.
+- For root-level schema failures with empty `instancePath` (e.g. `null` passed
+  to a `Type.Object` schema), `field` is the sentinel `"(root)"` rather than
+  the empty string.
+
+## [0.7.0] - 2026-05-26
 
 ### Changed
 

package/README.md

@@ -114,11 +114,19 @@ try {
 // After (0.7+)
 const result = await piTool.execute(...);
 if (result.isError) {
-  if (isValidationFailure(result)) { /* result.structuredContent.validationErrors */ }
-  else if (isDomainFailure(result)) { /* handler-level error */ }
+  if (isValidationFailure(result)) {
+    // validationErrors is Array<{ field: string; message: string }>.
+    for (const { field, message } of result.structuredContent.validationErrors) {
+      // ...
+    }
+  } else if (isDomainFailure(result)) { /* handler-level error */ }
 }
 ```
 
+`PortableValidationError` exposes `{ field, message }`. `field` is derived from TypeBox's structured error data — required-property errors read `params.requiredProperties` (so a prop named `"a,b"` survives intact and the value is locale-independent); other errors take the last meaningful segment of the offending JSON pointer (`text`, not `/text`). One error is emitted per missing required property, and duplicate `(field, message)` pairs (e.g. from union mismatches) are deduplicated. Validation and domain errors share this `{ field, message }` shape, so a consumer reading `.field` does not need to branch on which kind of failure produced the entry. (`path` was the pre-0.8.0 name; it has been removed.)
+
+For array-element validation, `field` is the leaf segment, which can be a numeric index (e.g. `field: "0"`) and loses path context. For root-level schema failures with empty `instancePath` (e.g. `null` passed to a `Type.Object` schema), `field` is the sentinel `"(root)"`.
+
 The two modes expose the failure discriminator on different fields. In the
 new default `"return"` mode, prefer the result guards over inspecting a
 `kind` field directly — handler-emitted failures do not carry a synthesized

package/dist/src/core/define-tool.d.ts

@@ -33,7 +33,7 @@ export type PortableToolErrorDetails = {
     kind: "domain";
 } & Record<string, unknown>);
 export interface PortableValidationError {
-    path: string;
+    field: string;
     message: string;
 }
 export type PortableToolBuiltInHost = "pi" | "mcp" | "test";

package/dist/src/core/execute-tool.js

@@ -1,22 +1,89 @@
 import { Check, Errors } from "typebox/value";
+const ROOT_FIELD = "(root)";
+function suppressSiblingErrorsUnderUnion(errors) {
+    // For unions of objects, TypeBox emits per-branch `required` /
+    // `additionalProperties` errors at the union's path. The user only needs
+    // to satisfy ONE branch, so those entries are phantoms; the `anyOf` /
+    // `oneOf` summary at the same path is the real signal.
+    //
+    // `const` / `enum` errors at the same path survive — they carry real
+    // discriminator info about which branch was intended.
+    //
+    // Known trade-off (#38): discriminated unions where the user picks a
+    // branch correctly but forgets that branch's required props also lose
+    // the "you picked tag=X and forgot Y" hint. Keyword-aware branch
+    // matching is the follow-up.
+    const unionPaths = new Set();
+    for (const error of errors) {
+        if (error.keyword === "anyOf" || error.keyword === "oneOf") {
+            unionPaths.add(error.instancePath);
+        }
+    }
+    if (unionPaths.size === 0)
+        return errors;
+    return errors.filter((error) => {
+        if (!unionPaths.has(error.instancePath))
+            return true;
+        return error.keyword !== "required" && error.keyword !== "additionalProperties";
+    });
+}
+function expandTypeBoxError(error) {
+    // Read offending property names from TypeBox's structured `params` rather
+    // than parsing the message string. Two payoffs: locale independence (the
+    // helper works the same after `Locale.Set("de_DE")`), and faithful
+    // preservation of property names that contain delimiters TypeBox's prose
+    // would split on (commas, etc.).
+    if (error.keyword === "required") {
+        const props = error.params.requiredProperties.filter((p) => p.length > 0);
+        if (props.length > 0) {
+            return props.map((field) => ({
+                field,
+                message: `must have required property ${field}`,
+            }));
+        }
+    }
+    if (error.keyword === "additionalProperties") {
+        const props = error.params.additionalProperties.filter((p) => p.length > 0);
+        if (props.length > 0) {
+            return props.map((field) => ({
+                field,
+                message: `must not have additional property ${field}`,
+            }));
+        }
+    }
+    const segments = error.instancePath.split("/").filter(Boolean);
+    return [{ field: segments.at(-1) ?? ROOT_FIELD, message: error.message }];
+}
 export function validatePortableToolArgs(tool, args) {
     if (Check(tool.parameters, args)) {
         return { ok: true };
     }
-    return {
-        ok: false,
-        errors: [...Errors(tool.parameters, args)].map((error) => ({
-            path: error.instancePath || "/",
-            message: error.message,
-        })),
-    };
+    // TypeBox can emit multiple errors per offending field (e.g. union/anyOf
+    // mismatches fire one error per failed branch). First, when an anyOf/oneOf
+    // error fires at a path, drop sibling `required`/`additionalProperties`
+    // errors at the same path — they're phantoms (the consumer only needs to
+    // satisfy ONE branch, not all of them). Then dedupe the survivors by
+    // (field, message) using JSON.stringify so the key can't collide regardless
+    // of what characters field or message contain.
+    const rawErrors = suppressSiblingErrorsUnderUnion([...Errors(tool.parameters, args)]);
+    const seen = new Set();
+    const errors = rawErrors
+        .flatMap((error) => expandTypeBoxError(error))
+        .filter(({ field, message }) => {
+        const key = JSON.stringify([field, message]);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    return { ok: false, errors };
 }
 export async function executePortableTool(tool, args, ctx) {
     const validation = validatePortableToolArgs(tool, args);
     if (!validation.ok) {
         return {
             text: `Invalid arguments for ${tool.name}: ${validation.errors
-                .map((error) => `${error.path} ${error.message}`)
+                .map((error) => `${error.field}: ${error.message}`)
                 .join("; ")}`,
             structuredContent: {
                 kind: "validation",

package/llms.txt

@@ -73,6 +73,7 @@ export function createTools() {
 - pi invalid arguments and portable `isError: true` results return `{ content, details, isError: true }` by default (as of 0.7). Unexpected handler exceptions are also caught in return mode and surfaced as `{ content, details: {}, isError: true }`. Branch on `result.isError` and narrow with `isValidationFailure` / `isDomainFailure` from `@feniix/bridgekit`.
 - MCP invalid arguments and portable `isError: true` results return `CallToolResult` with `isError: true`. Same guards narrow the result.
 - MCP preserves `structuredContent`; pi maps `structuredContent` into the pi `details` field. Both adapters fall back to `details` for legacy/debug payloads when `structuredContent` is absent.
+- Validation errors and domain errors share the `{ field, message }` shape *inside* `validationErrors[]`. The array itself only appears on `kind: "validation"` — narrow with `isValidationFailure` (or check the discriminator) before iterating. `field` is derived from TypeBox's structured error data: required-property errors read `params.requiredProperties` (one entry per missing prop), additional-property errors read `params.additionalProperties` (one entry per offending key), other errors take the last meaningful segment of the offending JSON pointer (`text`, not `/text`). Locale-independent and prop-names-with-commas-safe. Duplicate `(field, message)` pairs from union mismatches are deduplicated. As of 0.8.0; `path` no longer exists. Caveats: array-element fields can be numeric indices (`field: "0"`, path context lost); root-level schema failures use the sentinel `field: "(root)"` rather than empty string.
 - The result guards take a `PortableToolResult` — the value `executePortableTool` returns at the seam between BridgeKit and a host. They are not designed to be called on the pi adapter's wire object (`{ content, details, isError }`), which exposes `details` instead of `structuredContent`.
 - `registerPiTools(pi, tools, { errorHandling: "throw" })` opts into the pre-0.7 behavior where `isError` results throw `PortableToolExecutionError`. Selecting this value emits a `DeprecationWarning` (code `BRIDGEKIT_PI_THROW_DEPRECATED`) once per process; only the `"throw"` value is deprecated, not the option itself. Scheduled for removal in 1.0; do not adopt it for new code.
 
@@ -82,8 +83,10 @@ export function createTools() {
 const result = await executePortableTool(tool, args, { host: "test" });
 if (result.isError) {
   if (isValidationFailure(result)) {
-    // result.structuredContent.validationErrors is typed.
-    log.warn({ tool: result.structuredContent.tool }, "bad args");
+    // validationErrors is typed: Array<{ field: string; message: string }>.
+    for (const { field, message } of result.structuredContent.validationErrors) {
+      log.warn({ tool: result.structuredContent.tool, field, message }, "bad args");
+    }
   } else if (isDomainFailure(result)) {
     // Handler-emitted failure; result.structuredContent is whatever the
     // handler chose. No synthesized `kind` discriminator.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feniix/bridgekit",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "BridgeKit defines TypeBox-backed tools once and adapts them to pi, MCP, and other hosts.",
   "keywords": [
     "pi",