@salesforce/graphiti 10.18.3 → 10.19.0

package/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [10.19.0](https://github.com/salesforce-experience-platform-emu/webapps/compare/v10.18.3...v10.19.0) (2026-06-19)
+
+### Features
+
+- **graphiti:** @W-22818723@ default [@optional](https://github.com/optional) + displayValue on declarative sf*gql*\* tools ([#648](https://github.com/salesforce-experience-platform-emu/webapps/issues/648)) ([4c1199e](https://github.com/salesforce-experience-platform-emu/webapps/commit/4c1199e851eb8308d378b4ee1ac60d5b2d7735ca))
+
 ## [10.18.3](https://github.com/salesforce-experience-platform-emu/webapps/compare/v10.18.2...v10.18.3) (2026-06-19)
 
 **Note:** Version bump only for package @salesforce/graphiti

package/dist/intent/build-output.js

@@ -4,9 +4,18 @@
  * For full license text, see the LICENSE.txt file
  */
 import { generateTypes } from "../lib/codegen.js";
+import { applyGlobalSchemaPolicies } from "../lib/optional-fields.js";
 import { renderQuery } from "../lib/query-builder.js";
 import { validateQuery } from "../lib/validator.js";
 const SCHEMA_LEVEL_ERROR_MARKERS = ["must define one or more fields"];
+// W-22818723: the declarative tools emit `@optional` on selected record fields
+// (those FLS can gate) for graceful degradation. Live UIAPI advertises the
+// directive, but the
+// minimal schemas used in tests (and any introspection that omits directive
+// defs) don't — graphql-js then raises `Unknown directive "@optional".`. That
+// is an artifact of our own default, not a defect in the user's query, so it is
+// filtered out of `warnings[]` exactly like the schema-level markers above.
+const OPTIONAL_DIRECTIVE_UNKNOWN_MARKER = 'Unknown directive "@optional"';
 /**
  * Render → validate → codegen → assemble. Shared finalizer for every typed
  * intent function (`buildList`, `buildDetail`, …).
@@ -26,6 +35,11 @@ const SCHEMA_LEVEL_ERROR_MARKERS = ["must define one or more fields"];
  * surface non-validator findings (e.g. malformed `$var` placeholders).
  */
 export function buildOutput(session, schema, primingNote, extraWarnings = []) {
+    // Apply the global schema policies (@optional on FLS-gateable record fields +
+    // displayValue where exposed) before render/validate/codegen so all six
+    // declarative tools share one policy and the CLI's manual `optional` verb is
+    // unaffected (W-22818723).
+    applyGlobalSchemaPolicies(session, schema);
     const query = renderQuery(session);
     const warnings = primingNote ? [primingNote] : [];
     try {
@@ -33,6 +47,8 @@ export function buildOutput(session, schema, primingNote, extraWarnings = []) {
         for (const err of errors) {
             if (SCHEMA_LEVEL_ERROR_MARKERS.some((m) => err.message.includes(m)))
                 continue;
+            if (err.message.includes(OPTIONAL_DIRECTIVE_UNKNOWN_MARKER))
+                continue;
             warnings.push(`Validation: ${err.message}`);
         }
     }

package/dist/intent/build-output.js.map

@@ -1 +1 @@
-{"version":3,"file":"build-output.js","sourceRoot":"","sources":["../../src/intent/build-output.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,MAAM,0BAA0B,GAAG,CAAC,gCAAgC,CAAC,CAAC;AAEtE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,WAAW,CAC1B,OAAqB,EACrB,MAAqB,EACrB,WAAoB,EACpB,gBAA0B,EAAE;IAE5B,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IACnC,MAAM,QAAQ,GAAa,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAE5D,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAC5C,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;YAC1B,IAAI,0BAA0B,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;gBAAE,SAAS;YAC9E,QAAQ,CAAC,IAAI,CAAC,eAAe,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QAC7C,CAAC;IACF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,QAAQ,CAAC,IAAI,CAAC,qCAAqC,OAAO,GAAG,CAAC,CAAC;IAChE,CAAC;IAED,IAAI,KAAa,CAAC;IAClB,IAAI,CAAC;QACJ,KAAK,GAAG,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,KAAK,GAAG,8BAA8B,OAAO,EAAE,CAAC;QAChD,QAAQ,CAAC,IAAI,CAAC,YAAY,OAAO,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,MAAM,SAAS,GAAmB,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC/D,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;KAC9B,CAAC,CAAC,CAAC;IAEJ,QAAQ,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,CAAC;IAEhC,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AAC9C,CAAC"}
+{"version":3,"file":"build-output.js","sourceRoot":"","sources":["../../src/intent/build-output.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAClD,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,MAAM,0BAA0B,GAAG,CAAC,gCAAgC,CAAC,CAAC;AAEtE,+EAA+E;AAC/E,2EAA2E;AAC3E,qBAAqB;AACrB,4EAA4E;AAC5E,8EAA8E;AAC9E,gFAAgF;AAChF,4EAA4E;AAC5E,MAAM,iCAAiC,GAAG,+BAA+B,CAAC;AAE1E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,WAAW,CAC1B,OAAqB,EACrB,MAAqB,EACrB,WAAoB,EACpB,gBAA0B,EAAE;IAE5B,8EAA8E;IAC9E,wEAAwE;IACxE,6EAA6E;IAC7E,2BAA2B;IAC3B,yBAAyB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAE3C,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IACnC,MAAM,QAAQ,GAAa,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAE5D,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QAC5C,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;YAC1B,IAAI,0BAA0B,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;gBAAE,SAAS;YAC9E,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,iCAAiC,CAAC;gBAAE,SAAS;YACtE,QAAQ,CAAC,IAAI,CAAC,eAAe,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QAC7C,CAAC;IACF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,QAAQ,CAAC,IAAI,CAAC,qCAAqC,OAAO,GAAG,CAAC,CAAC;IAChE,CAAC;IAED,IAAI,KAAa,CAAC;IAClB,IAAI,CAAC;QACJ,KAAK,GAAG,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,KAAK,GAAG,8BAA8B,OAAO,EAAE,CAAC;QAChD,QAAQ,CAAC,IAAI,CAAC,YAAY,OAAO,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,MAAM,SAAS,GAAmB,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAC/D,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;KAC9B,CAAC,CAAC,CAAC;IAEJ,QAAQ,CAAC,IAAI,CAAC,GAAG,aAAa,CAAC,CAAC;IAEhC,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AAC9C,CAAC"}

package/dist/lib/optional-fields.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/**
+ * FLS-safe field selection policy for the declarative MCP tools (W-22818723).
+ *
+ * Salesforce UIAPI hard-fails an ENTIRE GraphQL query when it selects a field
+ * the running user lacks FLS for ("FieldUndefined … Field 'Gold__c'", data:{}).
+ * The `@optional` directive is UIAPI's graceful-degradation mechanism: a field
+ * marked `@optional` is silently omitted from the response instead of killing
+ * the query. Proven at runtime against `Hero__c.Gold__c` in the W-22800643 QA.
+ *
+ * Decision (W-22818723): the declarative tools default to applying `@optional`
+ * to every selected SObject field that FLS can actually gate, and select both
+ * `value` and `displayValue` on value-wrapper fields wherever the wrapper
+ * exposes a `displayValue`. There is no opt-in flag — degradation-by-default is
+ * the safe behavior for an LLM driving queries across multi-user orgs where FLS
+ * varies per user. Fields FLS can never hide (`Id`) are exempt — see
+ * `FLS_EXEMPT_FIELDS`.
+ *
+ * This policy runs once on the assembled session inside `buildOutput` (the
+ * shared finalizer for `buildList`/`buildDetail`/`buildAggregate`/
+ * `buildMutation`/`buildRaw`/`buildDelete`), so all six tools inherit it
+ * uniformly. The interactive CLI does NOT route through `buildOutput`, so its
+ * explicit `optional` verb keeps full manual control — this default is
+ * MCP-surface-only.
+ */
+import { type GraphQLSchema } from "graphql";
+import { type QuerySession } from "./session.js";
+/** The UIAPI FLS-degradation directive name (matches the CLI `optional` verb). */
+export declare const OPTIONAL_DIRECTIVE = "optional";
+/**
+ * Applies the global declarative-tool schema policies to a fully-assembled
+ * session in place — both the FLS-safe `@optional` default and `displayValue`
+ * selection on value wrappers:
+ *   - value-wrapper fields  → `@optional` + `value` + `displayValue` (where exposed)
+ *   - bare record scalars   → `@optional` (except `FLS_EXEMPT_FIELDS`, e.g. `Id`)
+ *   - structural plumbing   → untouched (`pageInfo`, `edges`, `node`, cursors,
+ *                             aggregate envelopes, the `value`/`displayValue`
+ *                             leaves themselves)
+ *
+ * Unresolvable nodes are left as-is — the renderer/validator surfaces a clearer
+ * error than this pass could. Never throws.
+ */
+export declare function applyGlobalSchemaPolicies(session: QuerySession, schema: GraphQLSchema): void;

package/dist/lib/optional-fields.js

@@ -0,0 +1,177 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+/**
+ * FLS-safe field selection policy for the declarative MCP tools (W-22818723).
+ *
+ * Salesforce UIAPI hard-fails an ENTIRE GraphQL query when it selects a field
+ * the running user lacks FLS for ("FieldUndefined … Field 'Gold__c'", data:{}).
+ * The `@optional` directive is UIAPI's graceful-degradation mechanism: a field
+ * marked `@optional` is silently omitted from the response instead of killing
+ * the query. Proven at runtime against `Hero__c.Gold__c` in the W-22800643 QA.
+ *
+ * Decision (W-22818723): the declarative tools default to applying `@optional`
+ * to every selected SObject field that FLS can actually gate, and select both
+ * `value` and `displayValue` on value-wrapper fields wherever the wrapper
+ * exposes a `displayValue`. There is no opt-in flag — degradation-by-default is
+ * the safe behavior for an LLM driving queries across multi-user orgs where FLS
+ * varies per user. Fields FLS can never hide (`Id`) are exempt — see
+ * `FLS_EXEMPT_FIELDS`.
+ *
+ * This policy runs once on the assembled session inside `buildOutput` (the
+ * shared finalizer for `buildList`/`buildDetail`/`buildAggregate`/
+ * `buildMutation`/`buildRaw`/`buildDelete`), so all six tools inherit it
+ * uniformly. The interactive CLI does NOT route through `buildOutput`, so its
+ * explicit `optional` verb keeps full manual control — this default is
+ * MCP-surface-only.
+ */
+import { isInterfaceType, isObjectType } from "graphql";
+import { getChildren, getNodeById, selectLeaf, } from "./session.js";
+import { isValueWrapperType } from "./uiapi.js";
+import { resolvePath } from "./walker.js";
+/** The UIAPI FLS-degradation directive name (matches the CLI `optional` verb). */
+export const OPTIONAL_DIRECTIVE = "optional";
+/** The companion display leaf selected alongside `value` on value wrappers. */
+const DISPLAY_VALUE_FIELD = "displayValue";
+/**
+ * Record fields FLS can never hide from a user who can read the record, so
+ * `@optional` on them is a guaranteed no-op for degradation. Marking them would
+ * only weaken the generated type (`Id?: string | undefined` instead of the
+ * always-present `Id: string`), so the policy skips them. `Id` is the one such
+ * field today; broader system/audit fields are a deliberate follow-up
+ * (see W-22818723 PR #648).
+ */
+const FLS_EXEMPT_FIELDS = new Set(["Id"]);
+/**
+ * Type-name suffixes / names that are UIAPI *structure* rather than record
+ * fields. A bare scalar whose parent resolves to one of these is plumbing
+ * (cursor pagination, connection wrappers, aggregate result envelopes), not an
+ * FLS-gated SObject field, so it must NOT receive `@optional`.
+ */
+function isStructuralScope(schema, typeName) {
+    if (!typeName)
+        return true;
+    if (typeName === "PageInfo")
+        return true;
+    if (typeName.endsWith("Connection") ||
+        typeName.endsWith("Edge") ||
+        typeName.endsWith("Aggregate")) {
+        return true;
+    }
+    // Value wrappers are handled by the wrapper branch; their `value` /
+    // `displayValue` leaves must not be independently marked.
+    if (isValueWrapperType(schema, typeName))
+        return true;
+    return false;
+}
+/**
+ * A "record scope" is an object/interface type that represents a Salesforce
+ * record (the `node` inside a connection, a mutation `Record`, a parent
+ * relationship object, a polymorphic union member fragment) — i.e. somewhere a
+ * directly-selected scalar like `Id` is an FLS-gated field. Structural
+ * envelopes (`*Connection` / `*Edge` / `*Aggregate` / `PageInfo`) and value
+ * wrappers are NOT record scopes: their children are plumbing (cursors,
+ * aggregation functions, `value` / `displayValue` leaves), which FLS does not
+ * gate and `@optional` must not touch.
+ *
+ * Resolving by the PARENT scope — rather than the field's own type — is what
+ * keeps the aggregate subtree clean: `count`/`sum`/… resolve to value-wrapper
+ * types (`LongValue`, …) but hang off an `*Aggregate` parent, so they are
+ * correctly excluded.
+ */
+function isRecordScope(session, schema, parent) {
+    if (!parent)
+        return false;
+    let typeName;
+    if (parent.kind === "fragment") {
+        // `... on User { … }` — the union member type IS the record scope.
+        typeName = parent.onType;
+    }
+    else {
+        try {
+            typeName = resolvePath(schema, session.operation, parent.schemaPath).typeName;
+        }
+        catch {
+            return false;
+        }
+    }
+    if (isStructuralScope(schema, typeName))
+        return false;
+    const t = schema.getType(typeName);
+    return isObjectType(t) || isInterfaceType(t);
+}
+/** Idempotently attaches the `@optional` directive to a field node. */
+function markOptional(node) {
+    if (!node.directives.some((d) => d.name === OPTIONAL_DIRECTIVE)) {
+        node.directives.push({ name: OPTIONAL_DIRECTIVE, args: {} });
+    }
+}
+/**
+ * Selects `displayValue` under a value-wrapper field when (a) the wrapper type
+ * actually exposes a `displayValue` field in the schema and (b) it is not
+ * already selected. This is the "include display value where it can be
+ * included" half of the AC — minimal test schemas whose wrapper is `{ value }`
+ * only are left untouched; real UIAPI wrappers (`StringValue`,
+ * `PicklistValue`, …) gain it.
+ */
+function ensureDisplayValue(session, schema, wrapperNode, wrapperTypeName) {
+    const t = schema.getType(wrapperTypeName);
+    if (!isObjectType(t) && !isInterfaceType(t))
+        return;
+    if (!Object.prototype.hasOwnProperty.call(t.getFields(), DISPLAY_VALUE_FIELD))
+        return;
+    const alreadySelected = getChildren(session, wrapperNode.id).some((c) => c.kind === "field" && c.fieldName === DISPLAY_VALUE_FIELD);
+    if (alreadySelected)
+        return;
+    selectLeaf(session, [...wrapperNode.schemaPath, DISPLAY_VALUE_FIELD]);
+}
+/**
+ * Applies the global declarative-tool schema policies to a fully-assembled
+ * session in place — both the FLS-safe `@optional` default and `displayValue`
+ * selection on value wrappers:
+ *   - value-wrapper fields  → `@optional` + `value` + `displayValue` (where exposed)
+ *   - bare record scalars   → `@optional` (except `FLS_EXEMPT_FIELDS`, e.g. `Id`)
+ *   - structural plumbing   → untouched (`pageInfo`, `edges`, `node`, cursors,
+ *                             aggregate envelopes, the `value`/`displayValue`
+ *                             leaves themselves)
+ *
+ * Unresolvable nodes are left as-is — the renderer/validator surfaces a clearer
+ * error than this pass could. Never throws.
+ */
+export function applyGlobalSchemaPolicies(session, schema) {
+    // Snapshot field nodes up front: `ensureDisplayValue` appends new leaves to
+    // `session.nodes`, and a freshly-added `displayValue` must not be reprocessed.
+    const fieldNodes = session.nodes.filter((n) => n.kind === "field");
+    for (const node of fieldNodes) {
+        let typeName;
+        let isLeaf;
+        try {
+            const wr = resolvePath(schema, session.operation, node.schemaPath);
+            typeName = wr.typeName;
+            isLeaf = wr.isLeaf;
+        }
+        catch {
+            continue;
+        }
+        // A field is FLS-gated — and thus a policy target — only when it is a
+        // direct field of a record scope. This single gate covers both shapes:
+        // value-wrapper fields (`Name { value }`) and bare record scalars
+        // (`Id`). It is what excludes the aggregate function-wrappers
+        // (`count`/`sum`/…), whose parent is an `*Aggregate` structural scope.
+        const parent = getNodeById(session, node.parentId);
+        if (!isRecordScope(session, schema, parent))
+            continue;
+        if (isValueWrapperType(schema, typeName)) {
+            markOptional(node);
+            ensureDisplayValue(session, schema, node, typeName);
+        }
+        else if (isLeaf && !FLS_EXEMPT_FIELDS.has(node.fieldName)) {
+            // Bare record scalar. Skip fields FLS can never gate (`Id`): marking
+            // them is a no-op that would only weaken the generated type.
+            markOptional(node);
+        }
+    }
+}
+//# sourceMappingURL=optional-fields.js.map

package/dist/lib/optional-fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optional-fields.js","sourceRoot":"","sources":["../../src/lib/optional-fields.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,eAAe,EAAE,YAAY,EAAsB,MAAM,SAAS,CAAC;AAC5E,OAAO,EAIN,WAAW,EACX,WAAW,EACX,UAAU,GACV,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,kFAAkF;AAClF,MAAM,CAAC,MAAM,kBAAkB,GAAG,UAAU,CAAC;AAE7C,+EAA+E;AAC/E,MAAM,mBAAmB,GAAG,cAAc,CAAC;AAE3C;;;;;;;GAOG;AACH,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAS,CAAC,IAAI,CAAC,CAAC,CAAC;AAElD;;;;;GAKG;AACH,SAAS,iBAAiB,CAAC,MAAqB,EAAE,QAAgB;IACjE,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3B,IAAI,QAAQ,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC;IACzC,IACC,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC;QAC/B,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC;QACzB,QAAQ,CAAC,QAAQ,CAAC,WAAW,CAAC,EAC7B,CAAC;QACF,OAAO,IAAI,CAAC;IACb,CAAC;IACD,oEAAoE;IACpE,0DAA0D;IAC1D,IAAI,kBAAkB,CAAC,MAAM,EAAE,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IACtD,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAS,aAAa,CACrB,OAAqB,EACrB,MAAqB,EACrB,MAA6B;IAE7B,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1B,IAAI,QAAgB,CAAC;IACrB,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAChC,mEAAmE;QACnE,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC;IAC1B,CAAC;SAAM,CAAC;QACP,IAAI,CAAC;YACJ,QAAQ,GAAG,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC,QAAQ,CAAC;QAC/E,CAAC;QAAC,MAAM,CAAC;YACR,OAAO,KAAK,CAAC;QACd,CAAC;IACF,CAAC;IACD,IAAI,iBAAiB,CAAC,MAAM,EAAE,QAAQ,CAAC;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,OAAO,YAAY,CAAC,CAAC,CAAC,IAAI,eAAe,CAAC,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED,uEAAuE;AACvE,SAAS,YAAY,CAAC,IAAyB;IAC9C,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,kBAAkB,CAAC,EAAE,CAAC;QACjE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;IAC9D,CAAC;AACF,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,kBAAkB,CAC1B,OAAqB,EACrB,MAAqB,EACrB,WAAgC,EAChC,eAAuB;IAEvB,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;IAC1C,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC;QAAE,OAAO;IACpD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,EAAE,EAAE,mBAAmB,CAAC;QAAE,OAAO;IAEtF,MAAM,eAAe,GAAG,WAAW,CAAC,OAAO,EAAE,WAAW,CAAC,EAAE,CAAC,CAAC,IAAI,CAChE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,IAAI,CAAC,CAAC,SAAS,KAAK,mBAAmB,CAChE,CAAC;IACF,IAAI,eAAe;QAAE,OAAO;IAE5B,UAAU,CAAC,OAAO,EAAE,CAAC,GAAG,WAAW,CAAC,UAAU,EAAE,mBAAmB,CAAC,CAAC,CAAC;AACvE,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAAqB,EAAE,MAAqB;IACrF,4EAA4E;IAC5E,+EAA+E;IAC/E,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAA4B,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;IAE7F,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC/B,IAAI,QAAgB,CAAC;QACrB,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACJ,MAAM,EAAE,GAAG,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,SAAS,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;YACnE,QAAQ,GAAG,EAAE,CAAC,QAAQ,CAAC;YACvB,MAAM,GAAG,EAAE,CAAC,MAAM,CAAC;QACpB,CAAC;QAAC,MAAM,CAAC;YACR,SAAS;QACV,CAAC;QAED,sEAAsE;QACtE,uEAAuE;QACvE,kEAAkE;QAClE,8DAA8D;QAC9D,uEAAuE;QACvE,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;QACnD,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC;YAAE,SAAS;QAEtD,IAAI,kBAAkB,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC;YAC1C,YAAY,CAAC,IAAI,CAAC,CAAC;YACnB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;QACrD,CAAC;aAAM,IAAI,MAAM,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YAC7D,qEAAqE;YACrE,6DAA6D;YAC7D,YAAY,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;IACF,CAAC;AACF,CAAC"}

package/dist/schemas/input-schemas.js

@@ -174,7 +174,7 @@ export const RAW_INPUT = z.object({
         "  set [<path>] <key>=<value> e.g. set uiapi/query/Case first=10  |  set uiapi/query/Case where.Status=New\n" +
         "  var $name <path> [default] e.g. var $id uiapi/query/Case/@args/where/Id/eq (type inferred from path)\n" +
         'Each command is tokenized on spaces and a value MUST NOT contain a space — quoting does not help once a token has started (key=\'a b\' still splits). A filter value that contains a space (e.g. "New York", "In Progress") cannot be expressed via set in v1; use sf_gql_list with a JSON filter, or pass the value through a variable bound with var.\n' +
-        "Fails fast: a bad command aborts the whole call. Other CLI verbs (cd, drop, alias, optional, unset) are NOT supported in v1."),
+        "Fails fast: a bad command aborts the whole call. Other CLI verbs (cd, drop, alias, optional, unset) are NOT supported in v1 — and the `optional` verb is unnecessary here: like every declarative tool, sf_gql_raw emits all selected record fields with the @optional directive automatically, so a field the running user lacks FLS for is omitted gracefully instead of failing the whole query."),
     operation: z
         .enum(["query", "mutation", "aggregate"])
         .optional()

package/dist/schemas/input-schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"input-schemas.js","sourceRoot":"","sources":["../../src/schemas/input-schemas.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"input-schemas.js","sourceRoot":"","sources":["../../src/schemas/input-schemas.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/graphiti",
-  "version": "10.18.3",
+  "version": "10.19.0",
   "description": "Progressive GraphQL query builder CLI for Salesforce orgs",
   "license": "SEE LICENSE IN LICENSE.txt",
   "type": "module",

package/src/intent/__tests__/build-delete.spec.ts

@@ -48,8 +48,10 @@ describe("intent/build-delete", () => {
 		expect(result.query).toContain("mutation DeleteAccount");
 		expect(result.query).toContain("$input: RecordDeleteInput!");
 		expect(result.query).toContain("AccountDelete(input: $input)");
-		// Id is plain ID on the payload — selected directly, never `Id { value }`.
+		// Id is plain ID on the payload — selected bare, never `Id { value }`.
+		// Id is FLS-exempt, so it carries no @optional directive (W-22818723).
 		expect(result.query).toMatch(/AccountDelete\(input: \$input\)\s*{\s*Id\s*}/);
+		expect(result.query).not.toMatch(/\bId\s+@optional\b/);
 		// No `Record { ... }` sub-selection (delete payloads have no Record path).
 		expect(result.query).not.toMatch(/\bRecord\s*{/);
 		expect(result.query).not.toContain("Id { value }");

package/src/intent/__tests__/build-detail.spec.ts

@@ -162,8 +162,9 @@ describe("intent/build-detail", () => {
 			{ org: ORG, object: "Account", fields: ["Id", "Name"] },
 			noopPrimeDeps(),
 		);
-		expect(out.query).toMatch(/\bId\b/);
-		expect(out.query).toMatch(/Name\s*\{\s*value\s*\}/);
+		// Id is FLS-exempt: selected bare, never @optional (W-22818723).
+		expect(out.query).not.toMatch(/\bId\s+@optional\b/);
+		expect(out.query).toMatch(/Name\s+@optional\s*\{\s*value\s*\}/);
 	});
 
 	it("default operationName is <Object>Detail", async () => {
@@ -199,7 +200,7 @@ describe("intent/build-detail", () => {
 			{ org: ORG, object: "Case", fields: ["Id"], parentFields: ["Account.Name"] },
 			noopPrimeDeps(),
 		);
-		expect(out.query).toMatch(/Account\s*\{[^}]*Name\s*\{\s*value\s*\}/s);
+		expect(out.query).toMatch(/Account\s*\{[^}]*Name\s+@optional\s*\{\s*value\s*\}/s);
 	});
 
 	it("parentFields expands polymorphic union into inline fragments (FR-4.3)", async () => {
@@ -207,8 +208,8 @@ describe("intent/build-detail", () => {
 			{ org: ORG, object: "Case", fields: ["Id"], parentFields: ["Owner.Name"] },
 			noopPrimeDeps(),
 		);
-		expect(out.query).toMatch(/\.\.\.\s+on\s+User\s*\{[^}]*Name\s*\{\s*value\s*\}/s);
-		expect(out.query).toMatch(/\.\.\.\s+on\s+Group\s*\{[^}]*Name\s*\{\s*value\s*\}/s);
+		expect(out.query).toMatch(/\.\.\.\s+on\s+User\s*\{[^}]*Name\s+@optional\s*\{\s*value\s*\}/s);
+		expect(out.query).toMatch(/\.\.\.\s+on\s+Group\s*\{[^}]*Name\s+@optional\s*\{\s*value\s*\}/s);
 	});
 
 	it("parentFields skips union members lacking the field (FR-4.3)", async () => {
@@ -239,8 +240,12 @@ describe("intent/build-detail", () => {
 		);
 		expect(out.query).toMatch(/Contacts\s*\([^)]*first:\s*5/);
 		expect(out.query).toMatch(/Contacts\s*\([^)]*orderBy:\s*\{\s*LastName/s);
+		// Id inside the child node is FLS-exempt — selected bare, never @optional.
+		expect(out.query).not.toMatch(
+			/Contacts\s*\([^)]*\)\s*\{\s*edges\s*\{\s*node\s*\{[^}]*Id\s+@optional\b/s,
+		);
 		expect(out.query).toMatch(
-			/Contacts\s*\([^)]*\)\s*\{\s*edges\s*\{\s*node\s*\{[^}]*LastName\s*\{\s*value\s*\}/s,
+			/Contacts\s*\([^)]*\)\s*\{\s*edges\s*\{\s*node\s*\{[^}]*LastName\s+@optional\s*\{\s*value\s*\}/s,
 		);
 	});
 

package/src/intent/__tests__/build-list.spec.ts

@@ -99,8 +99,25 @@ describe("intent/build-list", () => {
 			{ org: ORG, object: "Account", fields: ["Id", "Name"] },
 			noopPrimeDeps(),
 		);
-		expect(out.query).toMatch(/\bId\b/);
-		expect(out.query).toMatch(/Name\s*\{\s*value\s*\}/);
+		// Id is FLS-exempt: selected bare, never @optional (W-22818723).
+		expect(out.query).not.toMatch(/\bId\s+@optional\b/);
+		expect(out.query).toMatch(/Name\s+@optional\s*\{\s*value\s*\}/);
+	});
+
+	it("marks selected record fields @optional for FLS-safe degradation (W-22818723)", async () => {
+		const out = await buildList(
+			{ org: ORG, object: "Account", fields: ["Id", "Name", "Industry"] },
+			noopPrimeDeps(),
+		);
+		// FLS-gateable record fields (fields on `node`) get @optional
+		expect(out.query).toMatch(/\bName\s+@optional\s*\{/);
+		expect(out.query).toMatch(/\bIndustry\s+@optional\s*\{/);
+		// Id is FLS-exempt — selected bare, never @optional
+		expect(out.query).not.toMatch(/\bId\s+@optional\b/);
+		// Structural plumbing (edges, node, pageInfo, etc.) does NOT get @optional
+		expect(out.query).not.toMatch(/edges\s+@optional/);
+		expect(out.query).not.toMatch(/node\s+@optional/);
+		expect(out.query).not.toMatch(/pageInfo\s+@optional/);
 	});
 
 	it("default operationName is <Object>List", async () => {
@@ -144,7 +161,7 @@ describe("intent/build-list", () => {
 			{ org: ORG, object: "Case", fields: ["Id"], parentFields: ["Account.Name"] },
 			noopPrimeDeps(),
 		);
-		expect(out.query).toMatch(/Account\s*\{[^}]*Name\s*\{\s*value\s*\}/s);
+		expect(out.query).toMatch(/Account\s*\{[^}]*Name\s+@optional\s*\{\s*value\s*\}/s);
 	});
 
 	it("parentFields expands polymorphic union into inline fragments (FR-4.3)", async () => {
@@ -152,8 +169,8 @@ describe("intent/build-list", () => {
 			{ org: ORG, object: "Case", fields: ["Id"], parentFields: ["Owner.Name"] },
 			noopPrimeDeps(),
 		);
-		expect(out.query).toMatch(/\.\.\.\s+on\s+User\s*\{[^}]*Name\s*\{\s*value\s*\}/s);
-		expect(out.query).toMatch(/\.\.\.\s+on\s+Group\s*\{[^}]*Name\s*\{\s*value\s*\}/s);
+		expect(out.query).toMatch(/\.\.\.\s+on\s+User\s*\{[^}]*Name\s+@optional\s*\{\s*value\s*\}/s);
+		expect(out.query).toMatch(/\.\.\.\s+on\s+Group\s*\{[^}]*Name\s+@optional\s*\{\s*value\s*\}/s);
 	});
 
 	it("parentFields skips union members lacking the field (FR-4.3)", async () => {
@@ -179,7 +196,7 @@ describe("intent/build-list", () => {
 		);
 		expect(out.query).toMatch(/Contacts\s*\([^)]*first:\s*5/);
 		expect(out.query).toMatch(
-			/Contacts\s*\([^)]*\)\s*\{\s*edges\s*\{\s*node\s*\{[^}]*LastName\s*\{\s*value\s*\}/s,
+			/Contacts\s*\([^)]*\)\s*\{\s*edges\s*\{\s*node\s*\{[^}]*LastName\s+@optional\s*\{\s*value\s*\}/s,
 		);
 	});
 

package/src/intent/__tests__/build-mutation.spec.ts

@@ -52,7 +52,7 @@ describe("intent/build-mutation", () => {
 		expect(result.query).toMatch(/mutation CreateAccount/);
 		expect(result.query).toMatch(/\$input:\s*AccountCreateInput!/);
 		expect(result.query).toMatch(/AccountCreate\(input:\s*\$input\)/);
-		expect(result.query).toMatch(/Name\s*\{\s*value/s);
+		expect(result.query).toMatch(/Name\s+@optional\s*\{\s*value/s);
 		expect(result.variables).toEqual([
 			{ name: "input", type: "AccountCreateInput!", required: true },
 		]);
@@ -67,7 +67,7 @@ describe("intent/build-mutation", () => {
 		expect(result.query).toMatch(/mutation UpdateAccount/);
 		expect(result.query).toMatch(/\$input:\s*AccountUpdateInput!/);
 		expect(result.query).toMatch(/AccountUpdate\(input:\s*\$input\)/);
-		expect(result.query).toMatch(/Name\s*\{\s*value/s);
+		expect(result.query).toMatch(/Name\s+@optional\s*\{\s*value/s);
 		expect(result.variables).toEqual([
 			{ name: "input", type: "AccountUpdateInput!", required: true },
 		]);
@@ -75,10 +75,27 @@ describe("intent/build-mutation", () => {
 
 	it('op=Update defaults returnFields to ["Id"]', async () => {
 		const result = await buildMutation({ org: ORG, object: "Account" }, "Update", noopPrimeDeps());
+		// Id is FLS-exempt: selected bare, never @optional (W-22818723).
 		expect(result.query).toMatch(/\bId\b/);
+		expect(result.query).not.toMatch(/\bId\s+@optional\b/);
 		expect(result.query).not.toMatch(/Name\s*\{/);
 	});
 
+	it("returned record fields carry @optional directive for FLS safety", async () => {
+		const result = await buildMutation(
+			{ org: ORG, object: "Account", returnFields: ["Id", "Name"] },
+			"Create",
+			noopPrimeDeps(),
+		);
+		// FLS-gateable record fields get @optional; Id is exempt (selected bare)
+		expect(result.query).toMatch(/Name\s+@optional\s*\{/);
+		expect(result.query).not.toMatch(/\bId\s+@optional\b/);
+		// Structural plumbing (Record, uiapi, mutation name) never marked
+		expect(result.query).not.toMatch(/Record\s+@optional/);
+		expect(result.query).not.toMatch(/uiapi\s+@optional/);
+		expect(result.query).not.toMatch(/AccountCreate\s+@optional/);
+	});
+
 	it("op=Update with custom inputVariable strips leading $ and declares it", async () => {
 		const result = await buildMutation(
 			{ org: ORG, object: "Account", inputVariable: "$myInput" },

package/src/intent/__tests__/build-raw.spec.ts

@@ -63,7 +63,7 @@ describe("intent/build-raw", () => {
 			},
 			deps(),
 		);
-		expect(out.query).toMatch(/Subject\s*\{\s*value\s*\}/);
+		expect(out.query).toMatch(/Subject\s+@optional\s*\{\s*value\s*\}/);
 		expect(out.query).toMatch(/first:\s*5/);
 		expect(out.query).toMatch(/\bquery\b/);
 	});

package/src/intent/build-output.ts

@@ -7,12 +7,22 @@
 import { type GraphQLSchema } from "graphql";
 import { type ToolOutput, type VariableInfo } from "./types.js";
 import { generateTypes } from "../lib/codegen.js";
+import { applyGlobalSchemaPolicies } from "../lib/optional-fields.js";
 import { renderQuery } from "../lib/query-builder.js";
 import { type QuerySession } from "../lib/session.js";
 import { validateQuery } from "../lib/validator.js";
 
 const SCHEMA_LEVEL_ERROR_MARKERS = ["must define one or more fields"];
 
+// W-22818723: the declarative tools emit `@optional` on selected record fields
+// (those FLS can gate) for graceful degradation. Live UIAPI advertises the
+// directive, but the
+// minimal schemas used in tests (and any introspection that omits directive
+// defs) don't — graphql-js then raises `Unknown directive "@optional".`. That
+// is an artifact of our own default, not a defect in the user's query, so it is
+// filtered out of `warnings[]` exactly like the schema-level markers above.
+const OPTIONAL_DIRECTIVE_UNKNOWN_MARKER = 'Unknown directive "@optional"';
+
 /**
  * Render → validate → codegen → assemble. Shared finalizer for every typed
  * intent function (`buildList`, `buildDetail`, …).
@@ -37,6 +47,12 @@ export function buildOutput(
 	primingNote?: string,
 	extraWarnings: string[] = [],
 ): ToolOutput {
+	// Apply the global schema policies (@optional on FLS-gateable record fields +
+	// displayValue where exposed) before render/validate/codegen so all six
+	// declarative tools share one policy and the CLI's manual `optional` verb is
+	// unaffected (W-22818723).
+	applyGlobalSchemaPolicies(session, schema);
+
 	const query = renderQuery(session);
 	const warnings: string[] = primingNote ? [primingNote] : [];
 
@@ -44,6 +60,7 @@ export function buildOutput(
 		const errors = validateQuery(schema, query);
 		for (const err of errors) {
 			if (SCHEMA_LEVEL_ERROR_MARKERS.some((m) => err.message.includes(m))) continue;
+			if (err.message.includes(OPTIONAL_DIRECTIVE_UNKNOWN_MARKER)) continue;
 			warnings.push(`Validation: ${err.message}`);
 		}
 	} catch (err) {

package/src/lib/__tests__/optional-fields.spec.ts

@@ -0,0 +1,202 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/**
+ * W-22818723 — FLS-safe `@optional` field-selection policy.
+ *
+ * The sibling intent/mcp specs assert `@optional` against MINIMAL schemas whose
+ * value wrapper is `{ value }` only and which never declare the directive. This
+ * spec exercises the policy against a REALISTIC UIAPI-shaped schema — one that
+ * (a) declares `directive @optional` (so validation passes cleanly, as the live
+ * org does) and (b) exposes `displayValue`/`label` on its wrappers — to cover
+ * the two behaviors those minimal schemas structurally cannot:
+ *   1. `displayValue` IS selected when the wrapper exposes it.
+ *   2. `@optional` produces NO validation warning when the schema declares it.
+ *
+ * It also reproduces the headline FLS scenario (the `Gold__c`-style restricted
+ * field from the W-22800643 QA): a query that would hard-fail for a restricted
+ * user is rendered with `@optional` so the field degrades gracefully instead.
+ */
+
+import { buildSchema } from "graphql";
+import { describe, expect, it } from "vitest";
+import { makeNoopPrimeDeps } from "../../__tests__/helpers/prime-deps.js";
+import { buildAggregate } from "../../intent/build-aggregate.js";
+import { buildList } from "../../intent/build-list.js";
+import { applyGlobalSchemaPolicies, OPTIONAL_DIRECTIVE } from "../optional-fields.js";
+import { renderQuery } from "../query-builder.js";
+import { createSession, getChildren, selectLeaf } from "../session.js";
+import { primeSchemaCache } from "../walker.js";
+
+// A UIAPI-faithful schema: declares @optional, and wrappers carry value +
+// displayValue (StringValue/PicklistValue) so the "display value where it can
+// be included" branch is reachable. `Hero__c` mirrors the W-22800643 fixture.
+const SCHEMA_SDL = `
+	directive @optional on FIELD
+
+	type Query { uiapi: UIAPI! }
+	type UIAPI { query: RecordQuery!, aggregate: RecordQueryAggregate! }
+
+	type RecordQuery {
+		Hero__c(first: Int, after: String, where: Hero__c_Filter, orderBy: Hero__c_OrderBy): Hero__cConnection!
+	}
+	type RecordQueryAggregate {
+		Hero__c(first: Int, after: String, groupBy: Hero__c_GroupBy): Hero__cAggregateConnection
+	}
+
+	input Hero__c_Filter { Gold__c: IntOperators }
+	input Hero__c_OrderBy { Name: OrderByClause }
+	input Hero__c_GroupBy { Gold__c: GroupByClause }
+	input IntOperators { eq: Int, gt: Int }
+	input OrderByClause { order: Order! }
+	input GroupByClause { group: Boolean }
+	enum Order { ASC DESC }
+
+	type Hero__cConnection { edges: [Hero__cEdge!]!, pageInfo: PageInfo! }
+	type Hero__cEdge { node: Hero__c! }
+	type PageInfo { hasNextPage: Boolean!, endCursor: String }
+
+	type Hero__c {
+		Id: ID!
+		ApiName: String
+		Name: StringValue
+		Gold__c: IntValue
+	}
+
+	type StringValue { value: String, displayValue: String, label: String }
+	type IntValue { value: Int, displayValue: String }
+	type LongValue { value: String }
+
+	type Hero__cAggregateConnection { edges: [Hero__cAggregateEdge!]!, pageInfo: PageInfo! }
+	type Hero__cAggregateEdge { node: Hero__cResult!, cursor: String! }
+	type Hero__cResult { aggregate: Hero__cAggregate }
+	type Hero__cAggregate { Id: IDAggregate, Gold__c: IntAggregate }
+	type IDAggregate { value: ID, count: LongValue }
+	type IntAggregate { value: Int, sum: LongValue, count: LongValue }
+`;
+
+const SCHEMA = buildSchema(SCHEMA_SDL);
+const ORG = "hero-org";
+const ORG_URL = "https://hero-org.my.salesforce.com";
+primeSchemaCache(ORG, SCHEMA);
+primeSchemaCache(ORG_URL, SCHEMA);
+const noopPrimeDeps = () => makeNoopPrimeDeps(ORG, ORG_URL, SCHEMA);
+
+describe("lib/optional-fields — applyGlobalSchemaPolicies", () => {
+	it("marks bare record scalars @optional", async () => {
+		// ApiName is a bare scalar (not a value wrapper) on a record scope, so it
+		// gets @optional like any other FLS-gateable field.
+		const out = await buildList(
+			{ org: ORG, object: "Hero__c", fields: ["ApiName"] },
+			noopPrimeDeps(),
+		);
+		expect(out.query).toMatch(/\bApiName\s+@optional\b/);
+	});
+
+	it("does NOT mark Id @optional — FLS can never gate it (W-22818723)", async () => {
+		// `@optional` on Id is a no-op for degradation and only weakens the type
+		// (`Id?: string | undefined`), so Id is exempt while its siblings are not.
+		const out = await buildList(
+			{ org: ORG, object: "Hero__c", fields: ["Id", "Name"] },
+			noopPrimeDeps(),
+		);
+		expect(out.query).not.toMatch(/\bId\s+@optional\b/);
+		expect(out.query).toMatch(/\bId\b/); // still selected, just bare
+		expect(out.query).toMatch(/Name\s+@optional\s*\{/);
+	});
+
+	it("marks value-wrapper fields @optional and selects value + displayValue", async () => {
+		const out = await buildList({ org: ORG, object: "Hero__c", fields: ["Name"] }, noopPrimeDeps());
+		// @optional sits on the wrapper field, between the name and the body.
+		expect(out.query).toMatch(/Name\s+@optional\s*\{/);
+		// Both value AND displayValue are selected because the wrapper exposes them.
+		expect(out.query).toMatch(/Name\s+@optional\s*\{[^}]*\bvalue\b[^}]*\bdisplayValue\b[^}]*\}/s);
+	});
+
+	it("emits NO validation warning when the schema declares directive @optional", async () => {
+		const out = await buildList(
+			{ org: ORG, object: "Hero__c", fields: ["Id", "Name", "Gold__c"] },
+			noopPrimeDeps(),
+		);
+		expect(out.warnings).toEqual([]);
+	});
+
+	it("codegen reflects @optional fields as optional `?: T | undefined` and includes displayValue (AC)", async () => {
+		const out = await buildList(
+			{ org: ORG, object: "Hero__c", fields: ["Id", "Name", "Gold__c"] },
+			noopPrimeDeps(),
+		);
+		// @optional fields become optional TS properties unioned with undefined.
+		expect(out.types).toMatch(/\|\s*undefined/);
+		// The display value rides along on the wrapper.
+		expect(out.types).toMatch(/displayValue/);
+	});
+
+	it("FLS scenario: an FLS-restricted field (Gold__c) renders @optional so the query degrades gracefully", async () => {
+		// Per W-22800643: Gold__c WITHOUT @optional hard-fails the whole query for
+		// a restricted user; WITH @optional the field is omitted and the rest
+		// succeeds. The tool must emit the directive by default.
+		const out = await buildList(
+			{ org: ORG, object: "Hero__c", fields: ["Id", "Gold__c"] },
+			noopPrimeDeps(),
+		);
+		expect(out.query).toMatch(/Gold__c\s+@optional\s*\{[^}]*\bvalue\b/s);
+		expect(out.warnings).toEqual([]);
+	});
+
+	it("does NOT mark structural plumbing (pageInfo / cursors)", async () => {
+		const out = await buildList({ org: ORG, object: "Hero__c", fields: ["Id"] }, noopPrimeDeps());
+		// pageInfo and its cursor leaves carry no @optional.
+		expect(out.query).not.toMatch(/pageInfo\s+@optional/);
+		expect(out.query).not.toMatch(/hasNextPage\s+@optional/);
+		expect(out.query).not.toMatch(/endCursor\s+@optional/);
+	});
+
+	it("does NOT mark aggregate function selections @optional", async () => {
+		const out = await buildAggregate(
+			{
+				org: ORG,
+				object: "Hero__c",
+				aggregations: [{ function: "sum", field: "Gold__c" }],
+			},
+			noopPrimeDeps(),
+		);
+		// The aggregation function leaf (sum { value }) is structural, not an
+		// FLS-gated record field — it must stay clean.
+		expect(out.query).not.toMatch(/sum\s+@optional/);
+		expect(out.query).not.toMatch(/count\s+@optional/);
+	});
+
+	it("is idempotent — running the policy twice does not double-mark", () => {
+		const session = createSession(ORG, "query", ORG_URL);
+		// Use a non-exempt bare scalar (ApiName); Id would never be marked at all.
+		selectLeaf(session, ["uiapi", "query", "Hero__c", "edges", "node", "ApiName"]);
+		applyGlobalSchemaPolicies(session, SCHEMA);
+		applyGlobalSchemaPolicies(session, SCHEMA);
+		const apiNameNode = session.nodes.find((n) => n.kind === "field" && n.fieldName === "ApiName");
+		const optionalDirectives =
+			apiNameNode?.kind === "field"
+				? apiNameNode.directives.filter((d) => d.name === OPTIONAL_DIRECTIVE)
+				: [];
+		expect(optionalDirectives).toHaveLength(1);
+	});
+
+	it("does not duplicate displayValue when it is already selected", () => {
+		const session = createSession(ORG, "query", ORG_URL);
+		const base = ["uiapi", "query", "Hero__c", "edges", "node", "Name"];
+		selectLeaf(session, [...base, "value"]);
+		selectLeaf(session, [...base, "displayValue"]);
+		applyGlobalSchemaPolicies(session, SCHEMA);
+		const nameNode = session.nodes.find((n) => n.kind === "field" && n.fieldName === "Name");
+		const displayValueChildren = nameNode
+			? getChildren(session, nameNode.id).filter(
+					(c) => c.kind === "field" && c.fieldName === "displayValue",
+				)
+			: [];
+		expect(displayValueChildren).toHaveLength(1);
+		expect(renderQuery(session)).toMatch(/Name\s+@optional\s*\{/);
+	});
+});

package/src/lib/optional-fields.ts

@@ -0,0 +1,198 @@
+/**
+ * Copyright (c) 2026, Salesforce, Inc.,
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+/**
+ * FLS-safe field selection policy for the declarative MCP tools (W-22818723).
+ *
+ * Salesforce UIAPI hard-fails an ENTIRE GraphQL query when it selects a field
+ * the running user lacks FLS for ("FieldUndefined … Field 'Gold__c'", data:{}).
+ * The `@optional` directive is UIAPI's graceful-degradation mechanism: a field
+ * marked `@optional` is silently omitted from the response instead of killing
+ * the query. Proven at runtime against `Hero__c.Gold__c` in the W-22800643 QA.
+ *
+ * Decision (W-22818723): the declarative tools default to applying `@optional`
+ * to every selected SObject field that FLS can actually gate, and select both
+ * `value` and `displayValue` on value-wrapper fields wherever the wrapper
+ * exposes a `displayValue`. There is no opt-in flag — degradation-by-default is
+ * the safe behavior for an LLM driving queries across multi-user orgs where FLS
+ * varies per user. Fields FLS can never hide (`Id`) are exempt — see
+ * `FLS_EXEMPT_FIELDS`.
+ *
+ * This policy runs once on the assembled session inside `buildOutput` (the
+ * shared finalizer for `buildList`/`buildDetail`/`buildAggregate`/
+ * `buildMutation`/`buildRaw`/`buildDelete`), so all six tools inherit it
+ * uniformly. The interactive CLI does NOT route through `buildOutput`, so its
+ * explicit `optional` verb keeps full manual control — this default is
+ * MCP-surface-only.
+ */
+
+import { isInterfaceType, isObjectType, type GraphQLSchema } from "graphql";
+import {
+	type FieldProjectionNode,
+	type ProjectionNode,
+	type QuerySession,
+	getChildren,
+	getNodeById,
+	selectLeaf,
+} from "./session.js";
+import { isValueWrapperType } from "./uiapi.js";
+import { resolvePath } from "./walker.js";
+
+/** The UIAPI FLS-degradation directive name (matches the CLI `optional` verb). */
+export const OPTIONAL_DIRECTIVE = "optional";
+
+/** The companion display leaf selected alongside `value` on value wrappers. */
+const DISPLAY_VALUE_FIELD = "displayValue";
+
+/**
+ * Record fields FLS can never hide from a user who can read the record, so
+ * `@optional` on them is a guaranteed no-op for degradation. Marking them would
+ * only weaken the generated type (`Id?: string | undefined` instead of the
+ * always-present `Id: string`), so the policy skips them. `Id` is the one such
+ * field today; broader system/audit fields are a deliberate follow-up
+ * (see W-22818723 PR #648).
+ */
+const FLS_EXEMPT_FIELDS = new Set<string>(["Id"]);
+
+/**
+ * Type-name suffixes / names that are UIAPI *structure* rather than record
+ * fields. A bare scalar whose parent resolves to one of these is plumbing
+ * (cursor pagination, connection wrappers, aggregate result envelopes), not an
+ * FLS-gated SObject field, so it must NOT receive `@optional`.
+ */
+function isStructuralScope(schema: GraphQLSchema, typeName: string): boolean {
+	if (!typeName) return true;
+	if (typeName === "PageInfo") return true;
+	if (
+		typeName.endsWith("Connection") ||
+		typeName.endsWith("Edge") ||
+		typeName.endsWith("Aggregate")
+	) {
+		return true;
+	}
+	// Value wrappers are handled by the wrapper branch; their `value` /
+	// `displayValue` leaves must not be independently marked.
+	if (isValueWrapperType(schema, typeName)) return true;
+	return false;
+}
+
+/**
+ * A "record scope" is an object/interface type that represents a Salesforce
+ * record (the `node` inside a connection, a mutation `Record`, a parent
+ * relationship object, a polymorphic union member fragment) — i.e. somewhere a
+ * directly-selected scalar like `Id` is an FLS-gated field. Structural
+ * envelopes (`*Connection` / `*Edge` / `*Aggregate` / `PageInfo`) and value
+ * wrappers are NOT record scopes: their children are plumbing (cursors,
+ * aggregation functions, `value` / `displayValue` leaves), which FLS does not
+ * gate and `@optional` must not touch.
+ *
+ * Resolving by the PARENT scope — rather than the field's own type — is what
+ * keeps the aggregate subtree clean: `count`/`sum`/… resolve to value-wrapper
+ * types (`LongValue`, …) but hang off an `*Aggregate` parent, so they are
+ * correctly excluded.
+ */
+function isRecordScope(
+	session: QuerySession,
+	schema: GraphQLSchema,
+	parent: ProjectionNode | null,
+): boolean {
+	if (!parent) return false;
+	let typeName: string;
+	if (parent.kind === "fragment") {
+		// `... on User { … }` — the union member type IS the record scope.
+		typeName = parent.onType;
+	} else {
+		try {
+			typeName = resolvePath(schema, session.operation, parent.schemaPath).typeName;
+		} catch {
+			return false;
+		}
+	}
+	if (isStructuralScope(schema, typeName)) return false;
+	const t = schema.getType(typeName);
+	return isObjectType(t) || isInterfaceType(t);
+}
+
+/** Idempotently attaches the `@optional` directive to a field node. */
+function markOptional(node: FieldProjectionNode): void {
+	if (!node.directives.some((d) => d.name === OPTIONAL_DIRECTIVE)) {
+		node.directives.push({ name: OPTIONAL_DIRECTIVE, args: {} });
+	}
+}
+
+/**
+ * Selects `displayValue` under a value-wrapper field when (a) the wrapper type
+ * actually exposes a `displayValue` field in the schema and (b) it is not
+ * already selected. This is the "include display value where it can be
+ * included" half of the AC — minimal test schemas whose wrapper is `{ value }`
+ * only are left untouched; real UIAPI wrappers (`StringValue`,
+ * `PicklistValue`, …) gain it.
+ */
+function ensureDisplayValue(
+	session: QuerySession,
+	schema: GraphQLSchema,
+	wrapperNode: FieldProjectionNode,
+	wrapperTypeName: string,
+): void {
+	const t = schema.getType(wrapperTypeName);
+	if (!isObjectType(t) && !isInterfaceType(t)) return;
+	if (!Object.prototype.hasOwnProperty.call(t.getFields(), DISPLAY_VALUE_FIELD)) return;
+
+	const alreadySelected = getChildren(session, wrapperNode.id).some(
+		(c) => c.kind === "field" && c.fieldName === DISPLAY_VALUE_FIELD,
+	);
+	if (alreadySelected) return;
+
+	selectLeaf(session, [...wrapperNode.schemaPath, DISPLAY_VALUE_FIELD]);
+}
+
+/**
+ * Applies the global declarative-tool schema policies to a fully-assembled
+ * session in place — both the FLS-safe `@optional` default and `displayValue`
+ * selection on value wrappers:
+ *   - value-wrapper fields  → `@optional` + `value` + `displayValue` (where exposed)
+ *   - bare record scalars   → `@optional` (except `FLS_EXEMPT_FIELDS`, e.g. `Id`)
+ *   - structural plumbing   → untouched (`pageInfo`, `edges`, `node`, cursors,
+ *                             aggregate envelopes, the `value`/`displayValue`
+ *                             leaves themselves)
+ *
+ * Unresolvable nodes are left as-is — the renderer/validator surfaces a clearer
+ * error than this pass could. Never throws.
+ */
+export function applyGlobalSchemaPolicies(session: QuerySession, schema: GraphQLSchema): void {
+	// Snapshot field nodes up front: `ensureDisplayValue` appends new leaves to
+	// `session.nodes`, and a freshly-added `displayValue` must not be reprocessed.
+	const fieldNodes = session.nodes.filter((n): n is FieldProjectionNode => n.kind === "field");
+
+	for (const node of fieldNodes) {
+		let typeName: string;
+		let isLeaf: boolean;
+		try {
+			const wr = resolvePath(schema, session.operation, node.schemaPath);
+			typeName = wr.typeName;
+			isLeaf = wr.isLeaf;
+		} catch {
+			continue;
+		}
+
+		// A field is FLS-gated — and thus a policy target — only when it is a
+		// direct field of a record scope. This single gate covers both shapes:
+		// value-wrapper fields (`Name { value }`) and bare record scalars
+		// (`Id`). It is what excludes the aggregate function-wrappers
+		// (`count`/`sum`/…), whose parent is an `*Aggregate` structural scope.
+		const parent = getNodeById(session, node.parentId);
+		if (!isRecordScope(session, schema, parent)) continue;
+
+		if (isValueWrapperType(schema, typeName)) {
+			markOptional(node);
+			ensureDisplayValue(session, schema, node, typeName);
+		} else if (isLeaf && !FLS_EXEMPT_FIELDS.has(node.fieldName)) {
+			// Bare record scalar. Skip fields FLS can never gate (`Id`): marking
+			// them is a no-op that would only weaken the generated type.
+			markOptional(node);
+		}
+	}
+}

package/src/mcp/tools/__tests__/sf-gql-create.spec.ts

@@ -115,8 +115,9 @@ describe("mcp/tools/sf-gql-create", () => {
 			expect(parsed.query).toMatch(/mutation CreateAccount/);
 			expect(parsed.query).toMatch(/\$input:\s*AccountCreateInput!/);
 			expect(parsed.query).toMatch(/AccountCreate\(input:\s*\$input\)/);
-			expect(parsed.query).toMatch(/Name\s*\{\s*value/s);
-			expect(parsed.query).toMatch(/\bId\b/);
+			expect(parsed.query).toMatch(/Name\s+@optional\s*\{\s*value/s);
+			// Id is FLS-exempt: selected bare, never @optional (W-22818723).
+			expect(parsed.query).not.toMatch(/\bId\s+@optional\b/);
 			expect(parsed.variables).toHaveLength(1);
 			expect(parsed.variables[0]).toEqual({
 				name: "input",
@@ -139,7 +140,9 @@ describe("mcp/tools/sf-gql-create", () => {
 			});
 			const content = result.content as { type: string; text?: string }[];
 			const parsed = JSON.parse(content[0]?.text ?? "{}");
+			// Id is FLS-exempt: selected bare, never @optional (W-22818723).
 			expect(parsed.query).toMatch(/\bId\b/);
+			expect(parsed.query).not.toMatch(/\bId\s+@optional\b/);
 			expect(parsed.query).not.toMatch(/Name\s*\{/);
 		} finally {
 			await client.close();

package/src/mcp/tools/__tests__/sf-gql-detail.spec.ts

@@ -119,7 +119,7 @@ describe("mcp/tools/sf-gql-detail", () => {
 				warnings: string[];
 			};
 			expect(parsed.query).toMatch(/\bAccountDetail\b/);
-			expect(parsed.query).toMatch(/Name\s*\{\s*value\s*\}/);
+			expect(parsed.query).toMatch(/Name\s+@optional\s*\{\s*value\s*\}/);
 			expect(parsed.query).toMatch(/first\s*:\s*1\b/);
 			const id = parsed.variables.find((v) => v.name === "id");
 			expect(id).toBeDefined();

package/src/mcp/tools/__tests__/sf-gql-list.spec.ts

@@ -106,7 +106,7 @@ describe("mcp/tools/sf-gql-list", () => {
 				warnings: string[];
 			};
 			expect(parsed.query).toMatch(/\bAccountList\b/);
-			expect(parsed.query).toMatch(/Name\s*\{\s*value\s*\}/);
+			expect(parsed.query).toMatch(/Name\s+@optional\s*\{\s*value\s*\}/);
 			expect(Array.isArray(parsed.variables)).toBe(true);
 			expect(typeof parsed.types).toBe("string");
 		} finally {

package/src/mcp/tools/__tests__/sf-gql-raw.spec.ts

@@ -102,7 +102,7 @@ describe("mcp/tools/sf-gql-raw", () => {
 			expect(result.isError).toBeFalsy();
 			const content = result.content as { type: string; text?: string }[];
 			const parsed = JSON.parse(content[0]?.text ?? "{}") as { query: string };
-			expect(parsed.query).toMatch(/Subject\s*\{\s*value\s*\}/);
+			expect(parsed.query).toMatch(/Subject\s+@optional\s*\{\s*value\s*\}/);
 		} finally {
 			await client.close();
 			await server.close();

package/src/mcp/tools/__tests__/sf-gql-update.spec.ts

@@ -87,8 +87,9 @@ describe("mcp/tools/sf-gql-update", () => {
 			expect(parsed.query).toMatch(/mutation UpdateAccount/);
 			expect(parsed.query).toMatch(/\$input:\s*AccountUpdateInput!/);
 			expect(parsed.query).toMatch(/AccountUpdate\(input:\s*\$input\)/);
-			expect(parsed.query).toMatch(/Name\s*\{\s*value/s);
-			expect(parsed.query).toMatch(/\bId\b/);
+			expect(parsed.query).toMatch(/Name\s+@optional\s*\{\s*value/s);
+			// Id is FLS-exempt: selected bare, never @optional (W-22818723).
+			expect(parsed.query).not.toMatch(/\bId\s+@optional\b/);
 			expect(parsed.variables).toHaveLength(1);
 			expect(parsed.variables[0]).toEqual({
 				name: "input",
@@ -111,7 +112,9 @@ describe("mcp/tools/sf-gql-update", () => {
 			});
 			const content = result.content as { type: string; text?: string }[];
 			const parsed = JSON.parse(content[0]?.text ?? "{}");
+			// Id is FLS-exempt: selected bare, never @optional (W-22818723).
 			expect(parsed.query).toMatch(/\bId\b/);
+			expect(parsed.query).not.toMatch(/\bId\s+@optional\b/);
 			expect(parsed.query).not.toMatch(/Name\s*\{/);
 		} finally {
 			await client.close();

package/src/schemas/input-schemas.ts

@@ -219,7 +219,7 @@ export const RAW_INPUT = z.object({
 				"  set [<path>] <key>=<value> e.g. set uiapi/query/Case first=10  |  set uiapi/query/Case where.Status=New\n" +
 				"  var $name <path> [default] e.g. var $id uiapi/query/Case/@args/where/Id/eq (type inferred from path)\n" +
 				'Each command is tokenized on spaces and a value MUST NOT contain a space — quoting does not help once a token has started (key=\'a b\' still splits). A filter value that contains a space (e.g. "New York", "In Progress") cannot be expressed via set in v1; use sf_gql_list with a JSON filter, or pass the value through a variable bound with var.\n' +
-				"Fails fast: a bad command aborts the whole call. Other CLI verbs (cd, drop, alias, optional, unset) are NOT supported in v1.",
+				"Fails fast: a bad command aborts the whole call. Other CLI verbs (cd, drop, alias, optional, unset) are NOT supported in v1 — and the `optional` verb is unnecessary here: like every declarative tool, sf_gql_raw emits all selected record fields with the @optional directive automatically, so a field the running user lacks FLS for is omitted gracefully instead of failing the whole query.",
 		),
 	operation: z
 		.enum(["query", "mutation", "aggregate"])