@bridge_gpt/mcp-server 0.2.37 → 0.2.39

package/build/run-unit-tests-launcher.js

@@ -65,6 +65,7 @@ export const MODULE_MOCK_MANIFEST = [
     "build/sfcc/reads-site-preference.test.js",
     "build/sfcc/reads-system-object.test.js",
     "build/sfcc/register.test.js",
+    "build/sfcc/registration-boundary.test.js",
     "build/sfcc/setup-status.test.js",
     "build/sfcc/tool-wrapper.test.js",
     "build/sfcc/write-gate-rejection.test.js",
@@ -96,14 +97,24 @@ export const FORCE_EXIT_QUARANTINE = ["build/secret-safety.test.js"];
 // normal unit suite.
 const INTEGRATION_DIR_PREFIX = "build/integration/";
 const INTEGRATION_DIR_ALLOWLIST = new Set(["build/integration/measure-tools.test.js"]);
-// Pre-existing compiled test files that were not wired into ANY script before
-// this launcher existed (discovered while building it). BAPI-683 preserves
-// the exact current running test set rather than silently picking these up —
-// see docs/BAPI-683-mcp-ci-windows-npm-test-launcher.md for the follow-up.
-const KNOWN_UNREGISTERED_ORPHANS = new Set([
+// Compiled test files that live OUTSIDE build/integration/ but still belong to
+// the separately-invoked `npm run test:integration` lane, so the unit lane must
+// skip them. BAPI-683 originally introduced this set as
+// KNOWN_UNREGISTERED_ORPHANS: two pre-existing files that were wired into no
+// script at all, preserved as-is rather than silently picked up. BAPI-822
+// retired that state — every entry here is now named explicitly by
+// scripts.test:integration, and validateManifest below fails if an entry
+// disappears from the build output.
+//
+// Only add a file here when it genuinely needs the integration lane (an
+// MCP_INTEGRATION=1 gate, real subprocesses, or an optional native dependency
+// like better-sqlite3). A plain compiled test outside build/integration/ is
+// discovered into the unit lane automatically and needs no registration —
+// tests/pytest/mcp/test_mcp_server_test_registration_multicomponent.py fails if
+// a *.integration.test.ts ends up in neither lane.
+export const INTEGRATION_LANE_ONLY = [
     "build/conductor/conductor-runtime.integration.test.js",
-    "build/sfcc/register-site-preference.integration.test.js",
-]);
+];
 /** Recursively lists compiled `*.test.js` files under `<root>/<buildDir>`, sorted and package-relative. */
 export function discoverTestFiles(options) {
     const { root, buildDir = DEFAULT_BUILD_DIR, fsImpl = { readdirSync } } = options;
@@ -133,7 +144,7 @@ export function discoverTestFiles(options) {
     results.sort();
     return results;
 }
-/** Throws if the module-mock or force-exit-quarantine manifest has drifted from the discovered build output. */
+/** Throws if the module-mock, force-exit-quarantine, or integration-lane manifest has drifted from the discovered build output. */
 export function validateManifest(discovered) {
     const discoveredSet = new Set(discovered);
     const seen = new Set();
@@ -157,6 +168,21 @@ export function validateManifest(discovered) {
                 `(rebuild with 'npm run build', or remove it from FORCE_EXIT_QUARANTINE if the file was deleted/renamed)`);
         }
     }
+    // The integration-lane set is the one exclusion that removes a discovered
+    // file from every unit batch, so a stale entry is invisible by construction:
+    // the excluded file simply stops running and nothing reports it. Validating
+    // it against the build output turns that into a loud failure (BAPI-822).
+    for (const entry of INTEGRATION_LANE_ONLY) {
+        if (seen.has(entry)) {
+            throw new Error(`run-unit-tests: integration-lane entry duplicated or also present in another manifest: ${entry}`);
+        }
+        seen.add(entry);
+        if (!discoveredSet.has(entry)) {
+            throw new Error(`run-unit-tests: integration-lane entry not found in build output: ${entry} ` +
+                `(rebuild with 'npm run build', or remove it from INTEGRATION_LANE_ONLY — and from ` +
+                `scripts.test:integration — if the file was deleted/renamed)`);
+        }
+    }
 }
 /** Selects and validates the requested group's file list from the discovered inventory. */
 export function selectTestGroup(mode, discovered) {
@@ -165,12 +191,13 @@ export function selectTestGroup(mode, discovered) {
     }
     validateManifest(discovered);
     const moduleMockSet = new Set(MODULE_MOCK_MANIFEST);
+    const integrationLaneSet = new Set(INTEGRATION_LANE_ONLY);
     const normal = discovered.filter((file) => {
         if (moduleMockSet.has(file))
             return false;
         if (file.startsWith(INTEGRATION_DIR_PREFIX) && !INTEGRATION_DIR_ALLOWLIST.has(file))
             return false;
-        if (KNOWN_UNREGISTERED_ORPHANS.has(file))
+        if (integrationLaneSet.has(file))
             return false;
         return true;
     });

package/build/setup-epic.js

@@ -38,6 +38,10 @@ import os from "node:os";
 import readline from "node:readline";
 import { approveEpicPlan, createEpicRunWithDisposition, fetchEpicRunState, replaceEpicRunPolicy, resolveConductorBridgeApiAccess, storeEpicPlan, validateEpicPlan, ConductorBridgeApiError, } from "./conductor/bridge-api-client.js";
 import { validateBranchName } from "./base-ref.js";
+// BAPI-814/E1a: reused from the conduct-epic client on purpose. The override is
+// ONE repository-wide row with ONE reader; adding a second wrapper under
+// `conductor/` would give the v2 path its own copy to drift from.
+import { getIndexBranch } from "./conduct-epic/bridge-client.js";
 import { hashPlan } from "./conductor/plan.js";
 /** Accepted `policy_json.review_policy.source` values (the `ReviewPolicy` surface). */
 export const SETUP_EPIC_REVIEW_POLICY_SOURCES = [
@@ -45,6 +49,36 @@ export const SETUP_EPIC_REVIEW_POLICY_SOURCES = [
     "native_review_decision",
     "none",
 ];
+/**
+ * The warning lines for an active repository-wide index-branch override, or an
+ * empty array when there is nothing to say (BAPI-814/E1a).
+ *
+ * Fail-open by construction. This is optional enrichment layered onto a command
+ * whose real job is creating an epic run, so an unreadable override must not
+ * become a preflight failure: an unavailable lookup produces one bounded,
+ * sanitized diagnostic and `setup-epic` continues. The client already returns a
+ * sanitized `error` string and never the raw service body, so nothing further
+ * needs stripping here.
+ */
+async function describeActiveIndexOverride(access, deps) {
+    const result = await getIndexBranch(access, deps.fetch);
+    if (!result.ok) {
+        return [
+            `  [warn] The repository's indexed-branch override could not be read: ${result.error}. ` +
+                `Continuing — this is optional context, not a prerequisite.`,
+        ];
+    }
+    const override = result.value.override;
+    if (override === null)
+        return [];
+    return [
+        `  [warn] ${access.repoName} has an ACTIVE index-branch override: ` +
+            `'${override.override_branch}'. Repository parses currently index that branch, ` +
+            `and the base-branch config field this run may fall back on resolves through the ` +
+            `same override.`,
+        `         Setup is CONTINUING — this is a warning, not a refusal.`,
+    ];
+}
 /** Echoed single-line prompt on stderr (mirrors connect-github's helper). */
 function defaultPromptLine(promptText) {
     return new Promise((resolve) => {
@@ -102,9 +136,13 @@ export function getSetupEpicUsage() {
         "  --review-policy <src>  PER-RUN review policy source, one of:",
         `                         ${SETUP_EPIC_REVIEW_POLICY_SOURCES.join(", ")}.`,
         "                         Composed into policy_json.review_policy on create.",
-        "                         This setting is per-run: repository-level review-policy",
-        "                         defaults are NOT persisted in supervisor project",
-        "                         defaults yet — that is BAPI-694.",
+        "                         This flag sets the policy for THIS run only and never",
+        "                         changes a repository default. To persist one, pass",
+        "                         --review-policy to `install-bridge conductor`, which",
+        "                         stores it as the supervisor project default; that",
+        "                         default is stamped into a new run only when the run",
+        "                         sets no review policy of its own, so a value supplied",
+        "                         here always wins.",
         "  --json                 Emit a single JSON result object on stdout",
         "  -h, --help             Show this help",
         "",
@@ -981,6 +1019,21 @@ export async function runSetupEpicCli(argv, overrides = {}) {
     say(`Local hash: ${localHash}`);
     for (const w of warnings)
         say(`  [warn] ${w}`);
+    // --- Active index-branch override (BAPI-814/E1a) -------------------------
+    // Non-mutating enrichment, placed once credentials and repository identity are
+    // both known and before any run-state read or mutating request.
+    //
+    // WARNING ONLY, never a refusal. The override is repository-wide: while it is
+    // active every parse indexes that branch, and the create-PR config-field
+    // fallback and feature-branch provisioning read the same overridden
+    // `config_code_repositories.base_branch`. A v2 operator setting up an epic in
+    // that repository needs to know, but the condition is legitimate — it is
+    // usually another epic mid-flight — so setup continues.
+    //
+    // Emitted in `--dry-run` too: the condition already exists in the repository
+    // and is independent of whether this invocation writes anything.
+    for (const line of await describeActiveIndexOverride(access, deps))
+        say(line);
     // --- Feature branch selection (BAPI-655) --------------------------------
     // Resolved AFTER local/access context is known but BEFORE any run-state read
     // or mutating request, so malformed interactive input fails before network
@@ -1171,7 +1224,7 @@ export async function runSetupEpicCli(argv, overrides = {}) {
             say(`  - feature branch: ${featureBranch} (create from repository base branch; no request made in dry-run)`);
         }
         if (opts.reviewPolicy !== undefined) {
-            say(`  - review policy: ${opts.reviewPolicy} (per-run policy_json.review_policy; not persisted as a repository default until BAPI-694)`);
+            say(`  - review policy: ${opts.reviewPolicy} (per-run policy_json.review_policy; sets no repository default — use \`install-bridge conductor --review-policy\` for that)`);
         }
         say(`  - POST /jira/epic-runs/runs/${opts.epicKey}/plan          (v${plan.plan_version})`);
         say(`  - POST /jira/epic-runs/runs/${opts.epicKey}/approve-plan  (v${plan.plan_version})`);

package/build/sfcc/ocapi-shape.js

@@ -22,6 +22,13 @@
  * that legitimately live inside the returned resources: an OCAPI attribute
  * search document carries its own `count` and `hits`, and those stay untouched
  * inside `items`.
+ *
+ * `page` is built strictly from properties of the collection envelope itself,
+ * never from a field promoted out of an individual item (BAPI-769). A bare
+ * object response is the one shape where this matters concretely: `items` is
+ * always that single object, so its own internal `total`/`count` describes hits
+ * *inside* the document, not a count of `items`, and is never attached to
+ * `page.total` — see the bare-object branch of `normalizeOcapiBody` below.
  */
 /**
  * Single constructor for page metadata, shared by both normalizers.
@@ -79,6 +86,15 @@ export function normalizeOcapiPage(body) {
  * an attribute-search document with its own `count` and `hits` — becomes the
  * single item unchanged; its `count` is never promoted to collection metadata,
  * and a missing `hits` is never synthesized.
+ *
+ * `page` describes only the normalized `items` array; it is never built from a
+ * field promoted out of an item's own body (BAPI-769). The bare-object branch
+ * always produces exactly one item — the whole document — so a `total` count
+ * OCAPI reported about the document's own internal contents (e.g. a search
+ * document's zero-hit `total: 0`) is never attached to `page.total`, where it
+ * would misread as "0 of 1 returned item" for a wrapper whose `returned` is
+ * always 1. `page.total` is therefore absent on every bare-object response;
+ * `has_more` is unaffected — it still reflects the bare object's own `next`.
  */
 export function normalizeOcapiBody(body) {
     // Bare array
@@ -93,11 +109,14 @@ export function normalizeOcapiBody(body) {
             const items = obj.data;
             return { items, page: buildPageMeta(items, obj.total, obj.next) };
         }
-        // Bare object (single resource, no wrapping envelope). A directly supplied
-        // numeric `total` and paging signal are honored; the object's own `count`
-        // is left inside the item and never reinterpreted as a total.
+        // Bare object (single resource, no wrapping envelope). `items` is always
+        // the single wrapper document, so `returned` is always 1 — a `total` (and,
+        // for a search document, `count`/`hits`) reported INSIDE that document is
+        // never promoted to `page.total`: it describes hits within the document,
+        // not a count of `items`. `page.total` is therefore always absent here
+        // (BAPI-769); `next` is still honored for `has_more`, which is unaffected.
         const items = [body];
-        return { items, page: buildPageMeta(items, obj.total, obj.next) };
+        return { items, page: buildPageMeta(items, undefined, obj.next) };
     }
     // Non-object (null, string, number, etc.)
     return { items: [], page: buildPageMeta([], undefined, null) };

package/build/sfcc/permissions.js

@@ -3,8 +3,8 @@
  *
  * Issues a harmless GET /system_object_definitions probe. On 200: reports the
  * detected OCAPI version. On 401/403: prints the exact OCAPI Settings JSON to
- * paste in Business Manager, split into read-only (v1) vs. write/import (v2)
- * grant blocks.
+ * paste in Business Manager, split into read/search grants (for the `sfcc` read
+ * tools) and mutation grants (for the nine shipped `sfcc-write` tools).
  */
 import { ocapiGet } from "./client.js";
 import { normalizeOcapiPage } from "./ocapi-shape.js";
@@ -14,7 +14,7 @@ import { formatOcapiWriteGrantJson } from "./write-grants.js";
 // OCAPI Settings JSON template
 // Operators paste this in: Administration > Site Development > Open Commerce API Settings → Data API tab.
 // ---------------------------------------------------------------------------
-const OCAPI_SETTINGS_READ_ONLY = (ocapiVersion) => JSON.stringify({
+const OCAPI_SETTINGS_READ_SEARCH = (ocapiVersion) => JSON.stringify({
     _v: ocapiVersion,
     clients: [
         {
@@ -138,12 +138,31 @@ function formatProbeCount(normalized) {
     }
     return `${returned} items returned on this page (OCAPI did not provide the instance total)`;
 }
+/**
+ * Render the two grant blocks an operator pastes in Business Manager.
+ *
+ * Both labels were wrong before BAPI-817, in opposite directions:
+ *
+ *   - The first block was labelled **"READ-ONLY GRANTS"** while actually
+ *     granting `methods: ["get","post"]` with `write_attributes: "(**)"` across
+ *     three resource families. An operator pasted a grant they had been told was
+ *     read-only. It is renamed to read/search, which is what it is — the `post`
+ *     is OCAPI's search convention (`*_search` endpoints are POSTs), not a
+ *     mutation, but calling that "read-only" is still a claim about a grant the
+ *     operator cannot verify without reading OCAPI's own semantics.
+ *   - The second was labelled **"v2 — forward-looking"** for capabilities that
+ *     had already shipped. All nine write tools exist; the grant is required
+ *     today by anyone enabling `sfcc-write`, not speculative future work.
+ *
+ * A label that understates a grant is worse than no label, because the operator
+ * stops reading the JSON once the heading has told them it is safe.
+ */
 function ocapiSettingsInstructions(ocapiVersion) {
     return (`To grant OCAPI access, paste the JSON below in Business Manager:\n` +
         `  Administration > Site Development > Open Commerce API Settings → Data API tab\n\n` +
-        `--- READ-ONLY GRANTS (v1 — required now) ---\n` +
-        `${OCAPI_SETTINGS_READ_ONLY(ocapiVersion)}\n\n` +
-        `--- WRITE/IMPORT GRANTS (v2 — forward-looking, paste once) ---\n` +
+        `--- READ/SEARCH TOOL GRANTS (required for the sfcc read tools) ---\n` +
+        `${OCAPI_SETTINGS_READ_SEARCH(ocapiVersion)}\n\n` +
+        `--- MUTATION GRANTS (required for the nine sfcc-write tools) ---\n` +
         `${OCAPI_SETTINGS_WRITE_IMPORT(ocapiVersion)}\n\n` +
         `Replace <YOUR_CLIENT_ID> with the client_id from your dw.json.`);
 }

package/build/sfcc/read-body.js

@@ -0,0 +1,92 @@
+/**
+ * SFCC read-body redaction seam (BAPI-769).
+ *
+ * `projection: "full"` (BAPI-767) makes several OCAPI Data API endpoints return
+ * complete attribute-definition documents — `system_object_attribute_search`,
+ * `custom_object_definition_attribute_*`, and `system_object_definitions/{type}/
+ * attribute_definitions/{id}`. Live sandbox verification (OCAPI Data API v25_6)
+ * showed one of those 27 keys is not schema metadata about the attribute: it is
+ * the attribute's own runtime VALUE. `default_value` can carry a real
+ * configuration value — an attribute named `llmAvailableModelsJson` can carry
+ * actual model-routing config as its default — and that value must never reach
+ * an MCP caller, in the inline response, the `docs/tmp/sfcc/` save, or a
+ * successful attribute-definition write echo.
+ *
+ * This module owns exactly that: withholding one named structured field. It
+ * deliberately does NOT port `src/python/sfcc_monitor/adapters/redaction.py`'s
+ * regex/entropy engine — there is nothing to detect heuristically, only one key
+ * to withhold — and it deliberately does NOT redact inside `ocapi-shape.ts`.
+ * `normalizeOcapiBody`'s documented invariant is verbatim passthrough; folding
+ * redaction into it would make that no longer true. `readSfccBody` composes the
+ * two steps explicitly instead: redact first, normalize second.
+ *
+ * Attribute default values are intentionally unavailable through this MCP
+ * surface. Business Manager (Administration → Site Development → an object
+ * type's attribute definition) is the supported path to read one.
+ */
+import { normalizeOcapiBody } from "./ocapi-shape.js";
+/**
+ * Marker substituted for a withheld `default_value` node.
+ *
+ * Deliberately distinct from the log-query system's own `[REDACTED]` marker
+ * (`sfcc/log-query.ts` and friends) — the two redaction seams are unrelated:
+ * this one withholds one named structured field before normalization, the log
+ * seam performs regex/entropy scrubbing of log text. Conflating the markers
+ * would make a caller unable to tell which seam produced a given redaction.
+ */
+export const BRIDGE_REDACTED_MARKER = "[REDACTED_BY_BRIDGE]";
+/** True for a plain (non-array, non-null) object. */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Recursively withhold every `default_value` key found anywhere in `body`.
+ *
+ * Whenever an object carries an own `default_value` key, that key's ENTIRE
+ * value — including the `object_attribute_value_definition` wrapper OCAPI
+ * shapes it as (`{ _type, id, position, value }`) — is replaced with
+ * `BRIDGE_REDACTED_MARKER`. The key itself is always kept; only its value
+ * changes. Recursion continues into every sibling and into the rest of the same
+ * object/array, so a document that embeds another attribute-definition-shaped
+ * object deeper in its tree is still covered — the live key survey found only
+ * one `default_value` per document, but the walker stays general rather than
+ * hard-coding that shape.
+ *
+ * Side-effect-free: `body` is never mutated. A fresh tree is built and
+ * returned, so the caller's original object is unchanged after the call. A
+ * `default_value` key that was never present on the source is never
+ * synthesized — absence stays absence.
+ */
+export function redactSfccBody(body) {
+    if (Array.isArray(body)) {
+        return body.map((item) => redactSfccBody(item));
+    }
+    if (isPlainObject(body)) {
+        const result = {};
+        for (const [key, value] of Object.entries(body)) {
+            // Object.entries only yields own enumerable properties, so reaching this
+            // branch already means `body` owns `default_value` — no key is ever added
+            // where the source never had one.
+            if (key === "default_value") {
+                result[key] = BRIDGE_REDACTED_MARKER;
+                continue;
+            }
+            result[key] = redactSfccBody(value);
+        }
+        return result;
+    }
+    return body;
+}
+/**
+ * Redact, then normalize, a raw OCAPI response body.
+ *
+ * This is the read-path replacement for calling `normalizeOcapiBody` directly.
+ * Redaction happens BEFORE normalization, serialization, truncation, or save —
+ * one placement covers the inline MCP response and the `docs/tmp/sfcc/` save
+ * path identically, because both are derived from this same normalized result.
+ * `normalizeOcapiBody` itself remains a non-redacting verbatim shaper; it is
+ * `readSfccBody` that owns the redaction decision.
+ */
+export function readSfccBody(body) {
+    return normalizeOcapiBody(redactSfccBody(body));
+}

package/build/sfcc/read-projection.js

@@ -81,12 +81,16 @@ const PROJECTION_POLICY = {
     attribute_search: {
         defaultProjection: "full",
         placement: "body",
-        inputDescription: "Detail level. Default: full (value_type, mandatory, localizable, searchable, site_specific); lean returns ids only.",
+        inputDescription: "Detail level. Default: full — OCAPI's complete metadata projection " +
+            "(value_type, mandatory, localizable, searchable, site_specific); " +
+            "default_value is withheld. lean returns ids only.",
     },
     attribute_collection: {
         defaultProjection: "full",
         placement: "query",
-        inputDescription: "Detail level. Default: full (value_type, mandatory, localizable, searchable, site_specific); lean returns ids only.",
+        inputDescription: "Detail level. Default: full — OCAPI's complete metadata projection " +
+            "(value_type, mandatory, localizable, searchable, site_specific); " +
+            "default_value is withheld. lean returns ids only.",
     },
     broad_list: {
         defaultProjection: "lean",

package/build/sfcc/reads-custom-object-def.js

@@ -11,17 +11,31 @@
  * OCAPI's CustomObjectDefinitions resource only exposes operations scoped to
  * a known object_type — there is no top-level list and no bare get-by-type
  * (unlike SystemObjectDefinitions). A caller-supplied object_type is always
- * required; OCAPI cannot enumerate custom object types.
+ * required; OCAPI cannot enumerate custom object type IDs directly.
+ *
+ * That is narrower than "wholly undiscoverable," and the tools below say so:
+ * `system_object_list` at `projection: "full"` returns a distinct
+ * `display_name` and `attribute_definition_count` per custom type, from which a
+ * candidate ID can be derived (e.g. strip spaces from "Product Quality Result"
+ * → "ProductQualityResult") and confirmed by checking that this module's own
+ * `custom_object_definition_attributes_get` returns an attribute count matching
+ * that row's `attribute_definition_count`. This adds no new tool and no new
+ * projection value — it is existing capability, stated accurately.
  *
  * Note: custom object TYPE creation/update is NOT available via OCAPI REST.
  * It is a v2 metadata-import capability (metadata XML → WebDAV → import job).
+ *
+ * Both tools can return complete attribute-definition documents at
+ * `projection: "full"` (BAPI-767). Bridge withholds each attribute's
+ * `default_value` from that response (BAPI-769, `read-body.ts`) — every other
+ * schema field (type, flags, labels) is unaffected.
  */
 import path from "path";
 import { z } from "zod";
 import { ocapiGet, ocapiPost } from "./client.js";
 import { withSfccGate } from "./tool-wrapper.js";
 import { formatOcapiReadFailure, withSfccReadErrorBoundary } from "./read-result.js";
-import { normalizeOcapiBody } from "./ocapi-shape.js";
+import { readSfccBody } from "./read-body.js";
 import { applyProjectionToBody, projectionInputFor, projectionQueryEntries, } from "./read-projection.js";
 import { truncateAndSaveIfNeeded } from "./output.js";
 // ---------------------------------------------------------------------------
@@ -36,18 +50,17 @@ const READ_ANNOTATIONS = {
 // ---------------------------------------------------------------------------
 // Input schemas
 // ---------------------------------------------------------------------------
+const OBJECT_TYPE_DISCOVERY_HINT = 'Known custom object type id (e.g. starting with "c_"). OCAPI cannot enumerate ' +
+    "type IDs directly, but you can discover a candidate via system_object_list at " +
+    "projection=\"full\" (distinct display_name + attribute_definition_count per " +
+    "custom type) and confirm it by checking that this tool's returned attribute " +
+    "count matches that row's attribute_definition_count.";
 const customObjectAttributesGetInput = z.object({
-    object_type: z
-        .string()
-        .describe('Known custom object type identifier, e.g. a custom type id starting with "c_". ' +
-        "OCAPI cannot enumerate custom object types — the type must already be known."),
+    object_type: z.string().describe(OBJECT_TYPE_DISCOVERY_HINT),
     projection: projectionInputFor("attribute_collection"),
 });
 const customObjectAttributeSearchInput = z.object({
-    object_type: z
-        .string()
-        .describe('Known custom object type to search within, e.g. a custom type id starting with "c_". ' +
-        "OCAPI cannot enumerate custom object types — the type must already be known."),
+    object_type: z.string().describe(OBJECT_TYPE_DISCOVERY_HINT),
     query: z.union([z.string(), z.record(z.string(), z.any())]).describe("Search query. A plain string is a case-insensitive substring match across " +
         "id and display_name; a structured OCAPI query object passes through unchanged."),
     start: z.number().optional().describe("Zero-based offset for paging."),
@@ -86,7 +99,7 @@ function buildCustomObjectAttributesGetHandler(gateDeps, getDocsDir) {
         if (!result.ok) {
             return formatOcapiReadFailure(result);
         }
-        const normalized = normalizeOcapiBody(result.body);
+        const normalized = readSfccBody(result.body);
         const text = JSON.stringify(normalized, null, 2);
         const dir = path.join(await getDocsDir(), "sfcc");
         return saveAndReturn(text, dir, `custom-object-def-attributes-${safeType(object_type)}-${safeTimestamp()}.json`, normalized.page);
@@ -112,7 +125,7 @@ function buildCustomObjectAttributeSearchHandler(gateDeps, getDocsDir) {
         if (!result.ok) {
             return formatOcapiReadFailure(result);
         }
-        const normalized = normalizeOcapiBody(result.body);
+        const normalized = readSfccBody(result.body);
         const text = JSON.stringify(normalized, null, 2);
         const dir = path.join(await getDocsDir(), "sfcc");
         return saveAndReturn(text, dir, `custom-object-def-search-${safeType(object_type)}-${safeTimestamp()}.json`, normalized.page);
@@ -127,20 +140,19 @@ export function registerSfccCustomObjectDefReadTools(registerTool, deps) {
     const { gateDeps, getDocsDir } = deps;
     registerTool("custom_object_definition_attributes_get", {
         description: "Retrieve attribute definitions for a KNOWN custom object type via " +
-            "GET /custom_object_definitions/{type}/attribute_definitions. " +
-            "Returns each attribute's full schema by default. " +
-            "OCAPI cannot enumerate types — object_type is required. " +
-            "Type creation is v2 metadata-import only. Oversized payloads auto-saved locally.",
+            "GET /custom_object_definitions/{type}/attribute_definitions " +
+            "(default_value withheld). OCAPI cannot enumerate type IDs directly; " +
+            "derive one via system_object_list (projection=full, attribute_definition_count), " +
+            "confirm here. Type creation is v2 metadata-import only.",
         inputSchema: customObjectAttributesGetInput,
         annotations: READ_ANNOTATIONS,
     }, buildCustomObjectAttributesGetHandler(gateDeps, getDocsDir));
     registerTool("custom_object_definition_attribute_search", {
         description: "Search attribute definitions within a KNOWN custom object type via " +
-            "POST /custom_object_definitions/{type}/attribute_definition_search. " +
-            "Returns each attribute's full schema by default. " +
-            "OCAPI cannot enumerate types; object_type is required. " +
-            "Pass a string or OCAPI query. Type creation is v2 metadata-import only. " +
-            "Oversized results auto-saved locally.",
+            "POST /custom_object_definitions/{type}/attribute_definition_search " +
+            "(default_value withheld). OCAPI cannot enumerate type IDs directly; " +
+            "derive one via system_object_list (projection=full, attribute_definition_count), " +
+            "confirm here. Type creation is v2 metadata-import only.",
         inputSchema: customObjectAttributeSearchInput,
         annotations: READ_ANNOTATIONS,
     }, buildCustomObjectAttributeSearchHandler(gateDeps, getDocsDir));

package/build/sfcc/reads-site-preference.js

@@ -24,11 +24,18 @@
  * It is also, for now, accidentally protective. A name-heuristic scan of all 19
  * preference groups on the tested sandbox found secret-named preferences in six
  * of them — including one literally named `client_id` — and none of them expose
- * a value through this endpoint. No redaction seam is built here because there
- * is no value-bearing path to redact. If OCAPI ever starts returning values,
+ * a value through this endpoint. If OCAPI ever starts returning values here,
  * redaction must be added on the raw body BEFORE normalization, serialization,
  * truncation, or save, so one placement covers both the inline response and the
- * docs/tmp/sfcc/ save path.
+ * docs/tmp/sfcc/ save path — exactly the `readSfccBody` seam these three
+ * handlers already route through (BAPI-769).
+ *
+ * That value-bearing route already exists elsewhere: `SitePreferences`
+ * attribute-definition reads via `system_object_attribute_search` (with
+ * `object_type: "SitePreferences"`) can return each preference's
+ * `default_value`, and `readSfccBody` withholds it there today. This module's
+ * three preference-value tools remain ids-only for the reason stated above —
+ * OCAPI's `preference_search` itself never returns a value, `select` or not.
  *
  * NOTE: SCAPI Preferences API (sfcc.preferences) is intentionally NOT used.
  * This keeps the tool context on the OCAPI Data API, preserving the single
@@ -40,7 +47,7 @@ import { z } from "zod";
 import { ocapiGet, ocapiPost } from "./client.js";
 import { withSfccGate } from "./tool-wrapper.js";
 import { formatOcapiReadFailure, formatSfccReadFailure, withSfccReadErrorBoundary, } from "./read-result.js";
-import { normalizeOcapiBody } from "./ocapi-shape.js";
+import { readSfccBody } from "./read-body.js";
 import { projectionInputFor, projectionQueryEntries } from "./read-projection.js";
 import { truncateAndSaveIfNeeded } from "./output.js";
 // ---------------------------------------------------------------------------
@@ -106,6 +113,12 @@ async function saveAndReturn(text, dir, filename, page) {
  * an API version while OCAPI simultaneously reports `_v: "25.6"` in the same
  * session; the constraint belongs to this Bridge tool, not to a version. The
  * status, code, source, decision, and `details` payload are untouched.
+ *
+ * ⚠️ BAPI-817: like `write-guard.ts#rejectIfNotSandboxForWrite`, this checks a
+ * caller-supplied OCAPI instance-CONTEXT argument, NOT the host that will be
+ * contacted. It is secondary. The instance actually reached is decided by the
+ * resolved-hostname boundary in `tool-wrapper.ts`, which runs before this and
+ * does not consult `instance`.
  */
 function rejectIfNotSandbox(instance) {
     if (instance !== "sandbox") {
@@ -145,7 +158,7 @@ export function buildSitePreferenceGetHandler(gateDeps, getDocsDir) {
         if (!result.ok) {
             return formatOcapiReadFailure(result);
         }
-        const normalized = normalizeOcapiBody(result.body);
+        const normalized = readSfccBody(result.body);
         const text = JSON.stringify(normalized, null, 2);
         const dir = path.join(await getDocsDir(), "sfcc");
         return saveAndReturn(text, dir, `site-preference-get-${safeGroup(group)}-${safeTimestamp()}.json`, normalized.page);
@@ -173,7 +186,7 @@ export function buildSitePreferenceSearchHandler(gateDeps, getDocsDir) {
         if (!result.ok) {
             return formatOcapiReadFailure(result);
         }
-        const normalized = normalizeOcapiBody(result.body);
+        const normalized = readSfccBody(result.body);
         const text = JSON.stringify(normalized, null, 2);
         const dir = path.join(await getDocsDir(), "sfcc");
         return saveAndReturn(text, dir, `site-preference-search-${safeGroup(group)}-${safeTimestamp()}.json`, normalized.page);
@@ -196,7 +209,7 @@ export function buildSitePreferenceGroupListHandler(gateDeps, getDocsDir) {
         if (!result.ok) {
             return formatOcapiReadFailure(result);
         }
-        const normalized = normalizeOcapiBody(result.body);
+        const normalized = readSfccBody(result.body);
         const text = JSON.stringify(normalized, null, 2);
         const dir = path.join(await getDocsDir(), "sfcc");
         return saveAndReturn(text, dir, `site-preference-group-list-${safeTimestamp()}.json`, normalized.page);

package/build/sfcc/reads-system-object.js

@@ -8,13 +8,18 @@
  *
  * All tools are read-only, run behind the T1 call-time gate, and route
  * oversized payloads through the sfcc/output.ts truncate-and-save seam.
+ *
+ * `system_object_attribute_search` can return complete attribute-definition
+ * documents at `projection: "full"` (BAPI-767). Bridge withholds each
+ * attribute's `default_value` from that response (BAPI-769, `read-body.ts`) —
+ * every other schema field (type, flags, labels) is unaffected.
  */
 import path from "path";
 import { z } from "zod";
 import { ocapiGet, ocapiPost } from "./client.js";
 import { withSfccGate } from "./tool-wrapper.js";
 import { formatOcapiReadFailure, withSfccReadErrorBoundary } from "./read-result.js";
-import { normalizeOcapiBody } from "./ocapi-shape.js";
+import { readSfccBody } from "./read-body.js";
 import { applyProjectionToBody, projectionInputFor, projectionQueryEntries, } from "./read-projection.js";
 import { truncateAndSaveIfNeeded } from "./output.js";
 // ---------------------------------------------------------------------------
@@ -86,7 +91,7 @@ function buildSystemObjectListHandler(gateDeps, getDocsDir) {
         if (!result.ok) {
             return formatOcapiReadFailure(result);
         }
-        const normalized = normalizeOcapiBody(result.body);
+        const normalized = readSfccBody(result.body);
         const text = JSON.stringify(normalized, null, 2);
         const dir = path.join(await getDocsDir(), "sfcc");
         return saveAndReturn(text, dir, `system-object-list-${safeTimestamp()}.json`, normalized.page);
@@ -100,7 +105,7 @@ function buildSystemObjectGetHandler(gateDeps, getDocsDir) {
         if (!result.ok) {
             return formatOcapiReadFailure(result);
         }
-        const normalized = normalizeOcapiBody(result.body);
+        const normalized = readSfccBody(result.body);
         const text = JSON.stringify(normalized, null, 2);
         const dir = path.join(await getDocsDir(), "sfcc");
         return saveAndReturn(text, dir, `system-object-get-${safeType(object_type)}-${safeTimestamp()}.json`, normalized.page);
@@ -126,7 +131,7 @@ function buildSystemObjectAttributeSearchHandler(gateDeps, getDocsDir) {
         if (!result.ok) {
             return formatOcapiReadFailure(result);
         }
-        const normalized = normalizeOcapiBody(result.body);
+        const normalized = readSfccBody(result.body);
         const text = JSON.stringify(normalized, null, 2);
         const dir = path.join(await getDocsDir(), "sfcc");
         return saveAndReturn(text, dir, `system-object-search-${safeType(object_type)}-${safeTimestamp()}.json`, normalized.page);
@@ -159,7 +164,8 @@ export function registerSystemObjectReadTools(registerTool, deps) {
     registerTool("system_object_attribute_search", {
         description: "Search attribute definitions for a system object type. Read-only. " +
             "POST /system_object_definitions/{type}/attribute_definition_search. " +
-            "Use for targeted c_ attribute lookups; returns each attribute's full schema by default. " +
+            "Use for targeted c_ attribute lookups; returns each attribute's schema " +
+            "by default (default_value withheld). " +
             "Pass a plain string for text search or a structured OCAPI query. " +
             "Oversized results auto-saved locally.",
         inputSchema: systemObjectAttributeSearchInput,