@bridge_gpt/mcp-server 0.2.34 → 0.2.37

package/build/sfcc/sfcc-result.js

@@ -0,0 +1,106 @@
+/**
+ * The universal SFCC failure contract (BAPI-766).
+ *
+ * BAPI-759 unified the SFCC *read* surface behind one formatter. This module
+ * generalizes that formatter so the same envelope covers every SFCC tool: reads,
+ * all nine writes, the OCAPI call-time gate, and the separate WebDAV log surface.
+ * There is exactly one normalization and one serialization implementation here —
+ * two parallel formatters would let the read and write sides drift, which is the
+ * failure this module exists to prevent.
+ *
+ * Two things are unified:
+ *
+ *  1. **The protocol predicate.** Every formatted failure sets `isError: true`,
+ *     so a caller can detect "this call did not succeed" without parsing text.
+ *     `result.isError === true` is therefore a *total* predicate for failure
+ *     across the SFCC surface. `sfcc_setup_status` is the one deliberate
+ *     exemption: reporting a not-configured repository is its *successful*
+ *     output, and it sits outside every gate.
+ *
+ *  2. **The body shape.** Exactly one text content item, whose text parses as
+ *     `{ error: { code, status, message, source, details } }`. Those four
+ *     fields mean the same thing for an OCAPI fault, a tool-level guardrail, a
+ *     gate rejection, a WebDAV failure, and an unexpected internal failure — one
+ *     parse path reads all of them with no shape discrimination.
+ *
+ * Everything failure-specific lives under `error.details`, which is always
+ * present. An object-valued upstream body is preserved there verbatim, so
+ * upstream data is never discarded and never collides with the Bridge-owned
+ * envelope fields.
+ *
+ * Successful results are NOT passed through this formatter. `SfccToolResult`
+ * declares `isError` optional precisely so a content-only success (every
+ * successful read, every successful write) stays assignable without gaining the
+ * flag.
+ */
+// ---------------------------------------------------------------------------
+// Detail normalization
+// ---------------------------------------------------------------------------
+/** True for a plain (non-array, non-null) object whose fields can be preserved in place. */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Coerce arbitrary detail input into an object so `error.details` is always
+ * present and always the same kind of thing.
+ *
+ * A plain object is preserved verbatim (shallow copy) — this is what keeps an
+ * OCAPI fault body's `_v` / `fault.*` fields at their original nesting. Anything
+ * else (absent, null, a primitive, an array) is wrapped as `{ value }` rather
+ * than being spread, which would scatter an array across numeric keys or
+ * fabricate structure that upstream never sent.
+ */
+function normalizeDetails(details) {
+    if (details === undefined)
+        return {};
+    if (isPlainObject(details))
+        return { ...details };
+    return { value: details };
+}
+// ---------------------------------------------------------------------------
+// Formatter
+// ---------------------------------------------------------------------------
+/**
+ * Format any SFCC failure into the unified protocol result.
+ *
+ * Returns exactly one text content item and sets `isError: true`. The text
+ * serializes exactly one top-level `error` object. This is the single
+ * serialization point for the whole SFCC surface.
+ */
+export function formatSfccFailure(input) {
+    const details = normalizeDetails(input.details);
+    // Only surface the upstream status when it actually differs from the status
+    // we are reporting. Equal statuses would be noise; a synthetic status has no
+    // upstream to report at all.
+    if (input.upstreamHttpStatus !== undefined &&
+        input.upstreamHttpStatus !== input.status) {
+        details.upstream_http_status = input.upstreamHttpStatus;
+    }
+    const envelope = {
+        error: {
+            code: input.code,
+            status: input.status,
+            message: input.message,
+            source: input.source,
+            details,
+        },
+    };
+    return {
+        isError: true,
+        content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }],
+    };
+}
+/**
+ * Read-side name for the shared formatter, kept so BAPI-759's read call sites
+ * read naturally. It is a thin delegate, not a second implementation.
+ */
+export function formatSfccReadFailure(input) {
+    return formatSfccFailure(input);
+}
+/**
+ * Write-side name for the shared formatter. Same contract, same implementation —
+ * the discriminator between the two sides is `source`, not the function called.
+ */
+export function formatSfccWriteFailure(input) {
+    return formatSfccFailure(input);
+}

package/build/sfcc/tool-wrapper.js

@@ -12,23 +12,55 @@
  */
 import { SFCC_VERSIONS, getSfccVersionConfig } from "./config.js";
 import { resolveSfccCredentials } from "./credentials.js";
+import { formatSfccFailure } from "./sfcc-result.js";
 // ---------------------------------------------------------------------------
 // Not-configured envelope helpers
 // ---------------------------------------------------------------------------
+/**
+ * Appended to every gate diagnostic (BAPI-759).
+ *
+ * A hard protocol failure in a repository that simply is not an SFCC project
+ * must not send a calling agent into a retry or self-repair loop, so the
+ * message says so outright. It is appended to — never a replacement for — each
+ * failure class's own distinct diagnostic.
+ */
+const NO_RETRY_INSTRUCTION = "This repository is not configured for SFCC; do not retry SFCC tools.";
+/**
+ * Build the unified gate failure result.
+ *
+ * The gate's 503 is synthetic — it is Bridge's own status, not something OCAPI
+ * returned — so no upstream HTTP status is supplied and `details` carries only
+ * the preserved `failure_class`.
+ *
+ * This runs for READ AND WRITE tools alike. `withSfccGate` is shared
+ * infrastructure — the nine write handlers in `writes-system-object.ts`,
+ * `writes-custom-object-def.ts`, and `writes-site-preference.ts` all wrap
+ * themselves in it — so a gate rejection on a write tool returns this envelope
+ * with `isError: true` too. That is intended, not incidental: a write tool that
+ * never reached OCAPI produced no write, so the protocol failure is accurate.
+ * The flag is set unconditionally, with no per-tool branch, tool-name check, or
+ * read/write mode parameter, precisely so no caller has to know which side of
+ * the surface it is on.
+ *
+ * BAPI-766 closed the split BAPI-759 left behind: a write tool's OWN
+ * pre-transport failures (Zod, sandbox guard, id mismatch, unexpected throw) and
+ * its post-transport OCAPI failures now use this same envelope, built through
+ * the shared formatter in `sfcc-result.ts`. `write-gate-rejection.test.ts`
+ * drives the real gate through the real write handlers and asserts that the two
+ * origins now produce the same shape, so neither can drift silently.
+ *
+ * `sfcc_log_query` keeps its own separate gate (`withSfccLogGate`) because it
+ * authenticates over WebDAV Basic auth rather than the OCAPI AM-OAuth boundary.
+ * Only the failure representation is shared — those two gates are not merged.
+ */
 function notConfigured(failureClass, message) {
-    return {
-        content: [
-            {
-                type: "text",
-                text: JSON.stringify({
-                    error: "NOT_CONFIGURED",
-                    status: 503,
-                    failure_class: failureClass,
-                    message,
-                }),
-            },
-        ],
-    };
+    return formatSfccFailure({
+        code: "NOT_CONFIGURED",
+        status: 503,
+        message: `${message} ${NO_RETRY_INSTRUCTION}`,
+        source: "gate",
+        details: { failure_class: failureClass },
+    });
 }
 // ---------------------------------------------------------------------------
 // Gate
@@ -41,6 +73,17 @@ function notConfigured(failureClass, message) {
  * 2. Validates the value is an SFCC version.
  * 3. Resolves dw.json credentials.
  * 4. Calls the inner handler only if all checks pass.
+ *
+ * Every early rejection is the unified `isError: true` result — unconditionally,
+ * with no tool-name check, per-tool branch, exemption flag, or gate-mode
+ * parameter. `sfcc_setup_status`, the one SFCC tool whose successful output *is*
+ * a not-configured report, is exempt structurally: `register.ts` registers it
+ * outside this gate, so no code here needs to know about it.
+ *
+ * On the success path the inner handler's result is returned directly — not
+ * cloned, wrapped, or re-formatted — so write handlers keep ownership of their
+ * own result bodies. The generic `R` preserves each caller's concrete result
+ * type through the gate.
  */
 export function withSfccGate(deps, handler) {
     return async (args) => {

package/build/sfcc/write-grants.js

@@ -2,11 +2,18 @@
  * Shared OCAPI write-grant JSON helpers (BAPI-582 foundation).
  *
  * This module is the single source of truth for the OCAPI write-grant JSON that
- * is both echoed by future write handlers on a 403 and printed by the
+ * is both echoed by write handlers on a 403 and printed by the
  * `check_permissions` diagnostic. Keeping one definition guarantees the
  * remediation JSON an operator sees is identical no matter which surface it
  * comes from.
+ *
+ * BAPI-766 converted the 403 handler response from prose to the universal SFCC
+ * failure envelope. The remediation is not lost — it moved from an English
+ * paragraph into structured, non-secret fields under `error.details.remediation`,
+ * where a caller can read it without parsing text and `result.isError === true`
+ * still detects the failure.
  */
+import { formatSfccWriteFailure } from "./sfcc-result.js";
 // ---------------------------------------------------------------------------
 // Write resource families
 // ---------------------------------------------------------------------------
@@ -52,29 +59,45 @@ export function formatOcapiWriteGrantJson(ocapiVersion, clientIdPlaceholder = "<
 // ---------------------------------------------------------------------------
 // 403 write-grant UX
 // ---------------------------------------------------------------------------
-/**
- * Build the human-facing 403 remediation text for a failed write operation.
- * Includes the 403 status, the failed operation/path, and the exact write-grant
- * JSON operators must paste in Business Manager.
- */
-export function buildOcapiWriteGrant403Text(params) {
-    const { operation, path, ocapiVersion, body } = params;
-    const bodyLine = body === undefined
-        ? ""
-        : `\nResponse body:\n${JSON.stringify(body, null, 2)}\n`;
-    return (`HTTP 403: OCAPI write access denied for ${operation} ${path}.\n` +
-        bodyLine +
-        `\nTo grant write access, paste the JSON below in Business Manager:\n` +
-        `  Administration > Site Development > Open Commerce API Settings → Data API tab\n\n` +
-        `${formatOcapiWriteGrantJson(ocapiVersion)}\n\n` +
-        `Replace <YOUR_CLIENT_ID> with the client_id from your dw.json.`);
+/** Where an operator pastes the grant JSON in Business Manager. */
+export const OCAPI_WRITE_GRANT_BUSINESS_MANAGER_PATH = "Administration > Site Development > Open Commerce API Settings → Data API tab";
+/** The one instruction an operator must act on after pasting the grant JSON. */
+export const OCAPI_WRITE_GRANT_CLIENT_ID_INSTRUCTION = "Replace <YOUR_CLIENT_ID> with the client_id from your dw.json.";
+/** The fixed, Bridge-authored message for a 403 on an OCAPI write. */
+export function ocapiWriteForbiddenMessage(operation, path) {
+    return (`OCAPI write access denied for ${operation} ${path}. The client is not granted ` +
+        `write access to this resource. See error.details.remediation for the exact ` +
+        `write-grant settings to paste in Business Manager.`);
 }
 /**
- * MCP-shaped wrapper around `buildOcapiWriteGrant403Text` so future write
- * handlers can return the grant UX without re-implementing content wrapping.
+ * Build the unified 403 failure for a denied OCAPI write.
+ *
+ * The remediation an operator needs — where to paste, what to paste, and the one
+ * substitution to make — is carried as structured fields under
+ * `error.details.remediation` rather than as prose, so the result is parseable
+ * and `isError: true` detects it like every other SFCC failure. The grant JSON
+ * keeps the `<YOUR_CLIENT_ID>` placeholder: the real resolved client_id is never
+ * substituted, so nothing secret enters the response.
+ *
+ * The upstream 403 body is preserved verbatim under `error.details.body`, the
+ * same way an OCAPI read fault body is preserved.
  */
 export function writeGrantForbiddenResult(params) {
-    return {
-        content: [{ type: "text", text: buildOcapiWriteGrant403Text(params) }],
-    };
+    const { operation, path, ocapiVersion, body } = params;
+    return formatSfccWriteFailure({
+        code: "OCAPI_WRITE_ERROR",
+        status: 403,
+        message: ocapiWriteForbiddenMessage(operation, path),
+        source: "ocapi",
+        details: {
+            operation,
+            path,
+            remediation: {
+                business_manager_path: OCAPI_WRITE_GRANT_BUSINESS_MANAGER_PATH,
+                instruction: OCAPI_WRITE_GRANT_CLIENT_ID_INSTRUCTION,
+                write_grant: buildOcapiWriteGrantSettings(ocapiVersion),
+            },
+            ...(body === undefined ? {} : { body }),
+        },
+    });
 }

package/build/sfcc/write-guard.js

@@ -6,14 +6,13 @@
  * mutation. A non-null return value is
  * the pre-formatted MCP rejection to return directly; a null return means the
  * effective instance is a sandbox and the handler may proceed.
+ *
+ * BAPI-766 moved the rejection's *representation* to the shared SFCC formatter
+ * so the guardrail fails at the protocol level like every other SFCC failure.
+ * The guard's decision is untouched: `undefined` still defaults to `"sandbox"`,
+ * `"sandbox"` still proceeds, and every other value is still refused.
  */
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-/** Wrap text in the standard MCP text-result shape. */
-function textResult(text) {
-    return { content: [{ type: "text", text }] };
-}
+import { formatSfccWriteFailure } from "./sfcc-result.js";
 // ---------------------------------------------------------------------------
 // Guard
 // ---------------------------------------------------------------------------
@@ -22,18 +21,27 @@ function textResult(text) {
  *
  * SFCC write tools are sandbox-only in this foundation. The effective instance
  * defaults to `"sandbox"` when `undefined` (some schemas default the value
- * elsewhere), so an omitted instance is allowed. Any other value returns a
- * structured JSON validation error naming the rejected instance; a sandbox
- * returns `null` so the caller proceeds.
+ * elsewhere), so an omitted instance is allowed. Any other value returns the
+ * unified validation failure naming the rejected instance; a sandbox returns
+ * `null` so the caller proceeds.
+ *
+ * `details` carries non-sensitive guard metadata only — the rejected value is
+ * caller-supplied.
  */
 export function rejectIfNotSandboxForWrite(instance) {
     const effective = instance === undefined ? "sandbox" : instance;
     if (effective === "sandbox")
         return null;
-    return textResult(JSON.stringify({
-        error: "VALIDATION_ERROR",
+    return formatSfccWriteFailure({
+        code: "VALIDATION_ERROR",
         status: 400,
         message: `SFCC write tools are sandbox-only. Refusing to write against instance ` +
             `'${effective}'. Re-run the write against a developer sandbox instance.`,
-    }));
+        source: "tool",
+        details: {
+            guard: "sandbox_only",
+            received_instance: effective,
+            supported_instances: ["sandbox"],
+        },
+    });
 }

package/build/sfcc/write-result.js

@@ -1,26 +1,67 @@
 /**
- * Shared write-result formatter (BAPI-582 foundation).
+ * Shared write-result formatter (BAPI-582 foundation, unified by BAPI-766).
  *
- * This is the single formatting path for all future SFCC write tools. Handlers
- * pass the raw `OcapiGetResult` from `ocapiPut`/`ocapiPatch` here rather than
- * inventing their own 403/fault/success response logic, guaranteeing a
- * consistent surface across every write tool.
+ * This is the single formatting path for all SFCC write tools. Handlers pass the
+ * raw `OcapiGetResult` from `ocapiPut`/`ocapiPatch` here rather than inventing
+ * their own 403/fault/success response logic, guaranteeing a consistent surface
+ * across every write tool.
+ *
+ * Successful results are unchanged and never gain `isError`. Every *failure*
+ * branch — including the 403 write-grant remediation, which used to be prose —
+ * now returns the universal nested envelope from `sfcc-result.ts`, so
+ * `result.isError === true` is total across a write tool's post-transport
+ * failures as well as its pre-transport ones.
  */
 import { writeGrantForbiddenResult } from "./write-grants.js";
 import { DEFAULT_OCAPI_VERSION } from "./config.js";
-/** Wrap text in the standard MCP text-result shape. */
+import { formatSfccWriteFailure } from "./sfcc-result.js";
+/** Wrap text in the standard MCP text-result shape (success path only). */
 function textResult(text) {
     return { content: [{ type: "text", text }] };
 }
 // ---------------------------------------------------------------------------
+// Messages
+// ---------------------------------------------------------------------------
+/** True for a plain (non-array, non-null) object. */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Bridge-authored fallback used when an OCAPI write body carries no usable `fault.message`. */
+export function ocapiWriteFallbackMessage(status) {
+    return (`The SFCC OCAPI Data API returned HTTP ${status} for this write and supplied no ` +
+        `fault message. The upstream response body is preserved under error.details.`);
+}
+/**
+ * Pull a usable human-readable message out of an OCAPI write fault body.
+ *
+ * Raw response text is never promoted into `error.message` — an unparsed body
+ * falls through to the stable Bridge-authored fallback instead.
+ */
+function ocapiWriteFaultMessage(body, status) {
+    if (isPlainObject(body) && isPlainObject(body.fault)) {
+        const faultMessage = body.fault.message;
+        if (typeof faultMessage === "string" && faultMessage.trim() !== "") {
+            return faultMessage;
+        }
+    }
+    return ocapiWriteFallbackMessage(status);
+}
+// ---------------------------------------------------------------------------
 // Formatter
 // ---------------------------------------------------------------------------
 /**
  * Format an OCAPI write result into the standard MCP tool response.
  *
- *  - `403` → the paste-ready write-grant remediation (via write-grants.ts).
- *  - success → JSON with `status`, `outcome`, and `body`.
- *  - other failure → JSON with `error: "OCAPI_WRITE_ERROR"`, `status`, `fault`, `body`.
+ *  - `403` → the unified failure carrying the paste-ready write-grant
+ *    remediation as structured data (via write-grants.ts).
+ *  - success → JSON with `status`, `outcome`, and `body`; no `isError`.
+ *  - other failure → the unified `OCAPI_WRITE_ERROR` failure, source `ocapi`,
+ *    with the structured fault mapping and the upstream body under
+ *    `error.details`.
+ *
+ * No `upstreamHttpStatus` is supplied: `ocapiPut`/`ocapiPatch` surface
+ * `Response.status` verbatim, so the reported status *is* the upstream status
+ * and the shared formatter would rightly omit a duplicate.
  */
 export function formatOcapiWriteToolResult(result, operation, path, ocapiVersion = DEFAULT_OCAPI_VERSION) {
     if (result.status === 403) {
@@ -38,10 +79,16 @@ export function formatOcapiWriteToolResult(result, operation, path, ocapiVersion
             body: result.body,
         }));
     }
-    return textResult(JSON.stringify({
-        error: "OCAPI_WRITE_ERROR",
+    return formatSfccWriteFailure({
+        code: "OCAPI_WRITE_ERROR",
         status: result.status,
-        fault: result.fault,
-        body: result.body,
-    }));
+        message: ocapiWriteFaultMessage(result.body, result.status),
+        source: "ocapi",
+        details: {
+            operation,
+            path,
+            fault: result.fault,
+            body: result.body,
+        },
+    });
 }

package/build/sfcc/write-tool-common.js

@@ -1,15 +1,26 @@
 /**
- * Shared helpers for the SFCC write MCP tools (BAPI-584).
+ * Shared helpers for the SFCC write MCP tools (BAPI-584, unified by BAPI-766).
  *
- * The two write-surface modules (`writes-custom-object-def.ts` and
- * `writes-site-preference.ts`) both need the same small set of primitives:
- * the destructive tool annotations, the MCP text-result shape, a consistent
- * set of safe pre-transport error envelopes (validation / unexpected), and a
- * single path-segment encoder. Centralizing them here guarantees every write
- * tool returns an identical envelope shape and never leaks a stack trace or a
- * raw thrown value to the caller.
+ * All nine write tools — the two custom-object-definition tools, the
+ * site-preference value tool, and the six system-object tools — need the same
+ * small set of primitives: the destructive tool annotations, the MCP text-result
+ * shape, a consistent set of safe pre-transport failure envelopes (validation /
+ * payload fault / unexpected), and a single path-segment encoder.
+ *
+ * Every failure helper here returns the *universal* nested failure envelope
+ * built by `sfcc-result.ts` — `{ error: { code, status, message, source,
+ * details } }` with `isError: true`. There is no write-local envelope
+ * construction and no second serialization path, so a write tool's own
+ * pre-transport failure is indistinguishable in shape from a gate rejection, an
+ * OCAPI read fault, or a WebDAV log failure. That is what makes
+ * `result.isError === true` a total predicate across the SFCC surface.
+ *
+ * Nothing here ever serializes a stack trace, a raw thrown value, or a complete
+ * Zod issue object: validation issues are projected down to `{ path, message }`.
  */
 import { z } from "zod";
+import { formatSfccWriteFailure } from "./sfcc-result.js";
+import { SfccWritePayloadFault } from "./writes-system-object-payloads.js";
 // ---------------------------------------------------------------------------
 // Annotations
 // ---------------------------------------------------------------------------
@@ -24,35 +35,86 @@ export const WRITE_ANNOTATIONS = {
     idempotentHint: false,
     openWorldHint: true,
 };
-/** Wrap text in the standard MCP text-result shape. */
+/** Wrap text in the standard MCP text-result shape (success path only). */
 export function textResult(text) {
     return { content: [{ type: "text", text }] };
 }
 // ---------------------------------------------------------------------------
-// Pre-transport error envelopes
+// Fixed messages
 // ---------------------------------------------------------------------------
 /**
- * Convert a Zod validation failure into a safe `VALIDATION_ERROR` envelope.
- * The flattened issues are surfaced so callers can see which field failed,
- * without exposing any thrown-error internals.
+ * The one message returned when write arguments fail schema validation. The
+ * offending fields are reported under `error.details.issues`, never inline.
+ */
+export const SFCC_WRITE_VALIDATION_ERROR_MESSAGE = "Input failed schema validation before any OCAPI call. " +
+    "See error.details.issues for the offending fields.";
+/**
+ * The one message returned for an unexpected throw inside a write handler.
+ * Bridge-authored and fixed: the thrown value is never serialized, so a
+ * credential, token, request header, or stack frame carried by the exception
+ * cannot reach the caller.
  */
-export function zodValidationEnvelope(err) {
-    return textResult(JSON.stringify({
-        error: "VALIDATION_ERROR",
+export const SFCC_WRITE_INTERNAL_ERROR_MESSAGE = "An unexpected internal error occurred while handling this SFCC write. " +
+    "The underlying failure detail is withheld from this response to avoid " +
+    "leaking credentials or internal state.";
+// ---------------------------------------------------------------------------
+// Pre-transport failure envelopes
+// ---------------------------------------------------------------------------
+/** Reduce Zod issues to field path + message; nothing else is disclosed. */
+function safeZodIssues(err) {
+    const issues = Array.isArray(err.issues) ? err.issues : [];
+    return issues.map((issue) => ({
+        path: Array.isArray(issue.path) ? issue.path.map(String).join(".") : "",
+        message: typeof issue.message === "string" ? issue.message : "Invalid input.",
+    }));
+}
+/**
+ * Convert a Zod validation failure into the unified `VALIDATION_ERROR` envelope.
+ *
+ * Private: it has no caller outside this module — `preTransportErrorEnvelope`
+ * is the dispatcher every write handler actually uses. Issues are projected to
+ * the safe `{ path, message }` shape so no raw Zod issue object (with its
+ * `expected` / `received` / `unionErrors` internals) reaches a tool result.
+ */
+function zodValidationEnvelope(err) {
+    return formatSfccWriteFailure({
+        code: "VALIDATION_ERROR",
         status: 400,
-        message: "Input failed schema validation before any OCAPI call.",
-        issues: err.issues.map((issue) => ({
-            path: issue.path.join("."),
-            message: issue.message,
-        })),
-    }, null, 2));
+        message: SFCC_WRITE_VALIDATION_ERROR_MESSAGE,
+        source: "tool",
+        details: { issues: safeZodIssues(err) },
+    });
+}
+/**
+ * A local, pre-transport payload-shape failure surfaced in OCAPI-fault
+ * vocabulary (e.g. `IdConflictException`), without a network round trip.
+ *
+ * Private for the same reason as the Zod variant: handlers reach it through the
+ * dispatcher. `source` is `"tool"` — the fault was decided locally, so labelling
+ * it `"ocapi"` would claim OCAPI said something it never did.
+ */
+function payloadFaultEnvelope(fault) {
+    return formatSfccWriteFailure({
+        code: "OCAPI_WRITE_ERROR",
+        status: fault.status,
+        message: fault.message,
+        source: "tool",
+        details: { fault: { type: fault.faultType, message: fault.message } },
+    });
 }
 /**
  * A plain (non-Zod) validation rejection, e.g. a body/URL field mismatch that
- * the schema alone cannot express. Same envelope shape as the Zod variant.
+ * the schema alone cannot express. The caller's message is preserved verbatim;
+ * only the envelope around it changed.
  */
 export function validationEnvelope(message) {
-    return textResult(JSON.stringify({ error: "VALIDATION_ERROR", status: 400, message }, null, 2));
+    return formatSfccWriteFailure({
+        code: "VALIDATION_ERROR",
+        status: 400,
+        message,
+        source: "tool",
+        details: {},
+    });
 }
 /**
  * Safe fallback envelope for an unexpected thrown error inside a write handler
@@ -60,20 +122,52 @@ export function validationEnvelope(message) {
  * thrown value.
  */
 export function unexpectedEnvelope() {
-    return textResult(JSON.stringify({
-        error: "INTERNAL_ERROR",
+    return formatSfccWriteFailure({
+        code: "INTERNAL_ERROR",
         status: 500,
-        message: "Unexpected SFCC write tool failure.",
-    }, null, 2));
+        message: SFCC_WRITE_INTERNAL_ERROR_MESSAGE,
+        source: "tool",
+        details: {},
+    });
 }
 /**
- * Map a pre-transport error to its envelope: Zod validation errors become a
- * `VALIDATION_ERROR`, everything else becomes the generic `INTERNAL_ERROR`.
- * Used for the `.parse()` boundary before any OCAPI mutation.
+ * Recognize a Zod/schema failure without matching on the exception message.
+ *
+ * `instanceof` covers the normal case. The structural fallback covers a
+ * ZodError produced by a second copy of Zod (a duplicated dependency or a
+ * module-mocked import), where the prototype chain differs but the contract
+ * — a `ZodError` name plus an `issues` array — does not.
  */
-export function preTransportErrorEnvelope(err) {
+function isSchemaFailure(err) {
     if (err instanceof z.ZodError)
+        return true;
+    return (typeof err === "object" &&
+        err !== null &&
+        err.name === "ZodError" &&
+        Array.isArray(err.issues));
+}
+/** Recognize a local payload-shape fault, tolerating a duplicated module instance. */
+function isPayloadFault(err) {
+    if (err instanceof SfccWritePayloadFault)
+        return true;
+    return (typeof err === "object" &&
+        err !== null &&
+        err.name === "SfccWritePayloadFault" &&
+        typeof err.faultType === "string" &&
+        typeof err.status === "number");
+}
+/**
+ * Map a pre-transport error to its unified envelope: Zod validation failures
+ * become `VALIDATION_ERROR`, a recognized payload-shape fault becomes
+ * `OCAPI_WRITE_ERROR`, and everything else becomes the sanitized
+ * `INTERNAL_ERROR`. Used at the `.parse()` / payload-build boundary before any
+ * OCAPI mutation.
+ */
+export function preTransportErrorEnvelope(err) {
+    if (isSchemaFailure(err))
         return zodValidationEnvelope(err);
+    if (isPayloadFault(err))
+        return payloadFaultEnvelope(err);
     return unexpectedEnvelope();
 }
 // ---------------------------------------------------------------------------