@enricai/barnacle 1.12.75 → 1.12.77

package/dist/scripts/recon-generate.js

@@ -27,6 +27,7 @@ exports.extractStepPersonaValue = extractStepPersonaValue;
 exports.extractNavigateToHashFragmentValue = extractNavigateToHashFragmentValue;
 exports.deriveFillLabelField = deriveFillLabelField;
 exports.harvestPersonaBindings = harvestPersonaBindings;
+exports.extractNavigateToFacetOrder = extractNavigateToFacetOrder;
 exports.resolveCompositePersonaFields = resolveCompositePersonaFields;
 exports.collectConditionalGraphQLFieldNames = collectConditionalGraphQLFieldNames;
 exports.inferZodSchemaFromSamples = inferZodSchemaFromSamples;
@@ -65,6 +66,7 @@ exports.collectUnboundLiterals = collectUnboundLiterals;
 exports.emitMultiStepExecuteHttp = emitMultiStepExecuteHttp;
 exports.countSpliceableFacets = countSpliceableFacets;
 exports.spliceFacetsIntoStringVariable = spliceFacetsIntoStringVariable;
+exports.spliceFacetsIntoArrayVariable = spliceFacetsIntoArrayVariable;
 exports.findAllObjectArrayFields = findAllObjectArrayFields;
 exports.findAllObjectArrayFieldsOrWholeObject = findAllObjectArrayFieldsOrWholeObject;
 exports.applyDrillParamBindings = applyDrillParamBindings;
@@ -481,6 +483,36 @@ function harvestPersonaBindings(flowSteps, vocabulary, env) {
     }
     return bindings;
 }
+/**
+ * Re-walks the flow for navigateTo+payloadField steps in isolation, in flow
+ * order, independent of whether {@link harvestPersonaBindings} could anchor
+ * each one's literal anywhere in the capture. `harvestPersonaBindings` only
+ * sees flow steps (not captures), so it cannot tell which of its bindings
+ * will turn out to have zero recurrence downstream — this lets the emitter,
+ * which DOES see the captures, re-derive the same (value, field) pairs and
+ * try the causally-adjacent-action fallback (see `emitMultiStepExecuteHttp`)
+ * for whichever ones the recurrence-anchored path left unbound.
+ */
+function extractNavigateToFacetOrder(flowSteps) {
+    const order = [];
+    let previousNavigateToHash;
+    for (const step of flowSteps) {
+        if (typeof step === "string" || step.navigateTo === undefined)
+            continue;
+        const hashIndex = step.navigateTo.indexOf("#");
+        const currentHash = hashIndex === -1 ? undefined : step.navigateTo.slice(hashIndex + 1);
+        if (!step.payloadField) {
+            previousNavigateToHash = currentHash;
+            continue;
+        }
+        const value = extractNavigateToHashFragmentValue(step.navigateTo, previousNavigateToHash);
+        previousNavigateToHash = currentHash;
+        if (value === null || value.length === 0)
+            continue;
+        order.push({ value, field: step.payloadField, optional: step.optional === true });
+    }
+    return order;
+}
 /**
  * Detects a flow step whose quoted VALUE is the space-joined concatenation of
  * two already-known field values (either order), e.g. a signature step whose
@@ -3940,7 +3972,12 @@ function locateFormEnvelopePath(parsedBody) {
  * and swap for `${item.<field>}`. Freezing either into an opaque
  * `${JSON.stringify(payload.tokens)}` blob here would silently drop the
  * value the request depends on, breaking the fold at exactly the case an
- * ARRAY/OBJECT-wrapped join field represents.
+ * ARRAY/OBJECT-wrapped join field represents. A candidate whose leaves
+ * include a value already registered as a payload-accessor literal (e.g. a
+ * facet value a prior step derived and already wired for splicing elsewhere,
+ * such as a `departmentCode` recurring inside a `tags` array) is excluded on
+ * the same unconditional basis — it is already-threaded text waiting on the
+ * substring-splice pass, not caller-supplied history data.
  *
  * A body with no detected form envelope worth swallowing into (a facet/
  * search body — all scalars, if any, sit directly at the root) still needs
@@ -3951,7 +3988,7 @@ function locateFormEnvelopePath(parsedBody) {
  *
  * Site-agnostic: operates only on the recon body's own shape.
  *
- * A top-level-ARRAY-shaped body (e.g. a cruise-line multi-room search that
+ * A top-level-ARRAY-shaped body (e.g. a travel-brand multi-room search that
  * batches per-room criteria as `[{...}, {...}]`) is walked element by
  * element, applying this same envelope logic to each object element in
  * textual order — otherwise a structured field living inside an array
@@ -3966,7 +4003,35 @@ function locateFormEnvelopePath(parsedBody) {
  * search there stops an earlier element's already-rewritten (or still-frozen)
  * span from swallowing a later element's identically-named key.
  */
-function applyStructuredValuePayloadSubstitutionsForEnvelope(template, envelope, outStructuredKeys, unconditionalExcludeValues, restrictedExcludeSourceByValue, searchFrom, envelopePath, rootBody) {
+function isTokenBoundaryChar(ch) {
+    return ch === undefined || !/[A-Za-z0-9]/.test(ch);
+}
+/**
+ * True when `needle` occurs in `haystack` at a token boundary (flanked only
+ * by non-alphanumeric characters or the string's own edges) — e.g. a
+ * navigateTo facet's bare literal recurring inside a captured array element
+ * that suffixes it with a constant delimiter string (`"<literal>;filterId=
+ * urlFriendlyId"`). Exact equality alone misses this recurrence shape since
+ * the leaf carries the delimiter-joined text, not the bare literal. Mirrors
+ * the same boundary discipline `bindsWithoutCollision` already applies when
+ * registering a value for substring splicing in the first place.
+ */
+function containsValueAtTokenBoundary(haystack, needle) {
+    if (needle.length === 0 || needle === haystack)
+        return false;
+    let from = 0;
+    while (true) {
+        const at = haystack.indexOf(needle, from);
+        if (at === -1)
+            return false;
+        if (isTokenBoundaryChar(haystack[at - 1]) &&
+            isTokenBoundaryChar(haystack[at + needle.length])) {
+            return true;
+        }
+        from = at + needle.length;
+    }
+}
+function applyStructuredValuePayloadSubstitutionsForEnvelope(template, envelope, outStructuredKeys, unconditionalExcludeValues, restrictedExcludeSourceByValue, searchFrom, envelopePath, rootBody, payloadAccessorExcludePattern) {
     let result = template;
     let cursor = searchFrom;
     // The body root's own entries are eligible too, whenever the located
@@ -3988,7 +4053,9 @@ function applyStructuredValuePayloadSubstitutionsForEnvelope(template, envelope,
             Object.keys(value).length > 0;
         if (!isNonEmptyArray && !isNestedObject)
             continue;
-        if (unconditionalExcludeValues.size > 0 || restrictedExcludeSourceByValue.size > 0) {
+        if (unconditionalExcludeValues.size > 0 ||
+            restrictedExcludeSourceByValue.size > 0 ||
+            payloadAccessorExcludePattern !== null) {
             // A name-free join/chain value (unconditionalExcludeValues) excludes the
             // whole field on ANY leaf coincidence, same as before. A RESTRICTED prior-
             // step value (one with a real source field name) additionally requires
@@ -3999,12 +4066,39 @@ function applyStructuredValuePayloadSubstitutionsForEnvelope(template, envelope,
             // count/id) merely equalling SOME other step's produced value gets the
             // ENTIRE array/object excluded from threading, even though nothing about
             // that leaf's key names the same concept as the matched value's source.
+            // A registered payload-accessor literal (payloadAccessorExcludePattern)
+            // excludes unconditionally too, but on a DELIMITED-SUBSTRING match, not
+            // exact leaf equality — the reported shape is a facet value recurring
+            // inside a captured array element with a constant suffix still attached
+            // (e.g. a hash-derived facet embedded in a `tags` entry alongside a
+            // trailing marker), so requiring the whole leaf to equal the bare facet
+            // literal would miss exactly the case this exclusion exists for. Reuses
+            // {@link buildValueAlternationPattern}'s own token-boundary rule so a
+            // facet value that merely happens to be a substring of an unrelated,
+            // dash/dot-concatenated compound token is still correctly left alone.
+            //
+            // Beyond exact equality, a leaf that carries an excluded value as a
+            // token-bounded SUBSTRING (e.g. a navigateTo facet literal recurring
+            // inside an array element suffixed by a constant delimiter string, like
+            // `"<literal>;filterId=urlFriendlyId"`) must exclude the field too —
+            // otherwise the field gets frozen wholesale before the later
+            // literal-value interpolation pass (which operates on text, not parsed
+            // values) ever gets a chance to splice the facet out of that element.
             const carriesThreadedValue = [...walkAllPrimitiveLeaves(value)].some(({ value: leaf, path: leafPath }) => {
                 if (leaf === null)
                     return false;
                 const leafValue = String(leaf);
                 if (unconditionalExcludeValues.has(leafValue))
                     return true;
+                if (payloadAccessorExcludePattern !== null) {
+                    payloadAccessorExcludePattern.lastIndex = 0;
+                    if (payloadAccessorExcludePattern.test(leafValue))
+                        return true;
+                }
+                for (const excluded of unconditionalExcludeValues) {
+                    if (containsValueAtTokenBoundary(leafValue, excluded))
+                        return true;
+                }
                 const sourceName = restrictedExcludeSourceByValue.get(leafValue);
                 if (sourceName === undefined)
                     return false;
@@ -4052,6 +4146,19 @@ function applyStructuredValuePayloadSubstitutionsForEnvelope(template, envelope,
         }
         if (spanEnd === -1)
             continue;
+        // An earlier pass in this same pipeline run (e.g. the optional-facet
+        // array-element splice) may have already spliced a `${payload.<field>}`
+        // accessor into this exact span — e.g. turning one element of a
+        // search/filter array into `...(payload.sortOrder ? [...] : [])`. The
+        // exclusion-source checks above only ever see the ORIGINAL parsed leaf
+        // values, so they can't detect this; inspecting the located span's
+        // CURRENT text catches it and leaves the pre-spliced accessor intact
+        // instead of clobbering it with a wholesale replacement. Matching on the
+        // literal template-placeholder prefix `${payload.` (rather than the bare
+        // substring `payload.`) avoids false-positiving on scraped leaf data that
+        // merely happens to contain the word "payload." as ordinary text.
+        if (result.slice(spanStart, spanEnd).includes("${payload."))
+            continue;
         const replacement = `$${"{"}JSON.stringify(payload.${key})${"}"}`;
         result = result.slice(0, spanStart) + replacement + result.slice(spanEnd);
         cursor = Math.max(cursor, spanStart + replacement.length);
@@ -4067,7 +4174,7 @@ function applyStructuredValuePayloadSubstitutionsForEnvelope(template, envelope,
  * pass to it. Shared by the top-level-object and top-level-array branches of
  * {@link applyStructuredValuePayloadSubstitutions} below.
  */
-function applyStructuredValuePayloadSubstitutionsForObjectBody(template, objectBody, outStructuredKeys, unconditionalExcludeValues, restrictedExcludeSourceByValue, searchFrom) {
+function applyStructuredValuePayloadSubstitutionsForObjectBody(template, objectBody, outStructuredKeys, unconditionalExcludeValues, restrictedExcludeSourceByValue, searchFrom, payloadAccessorExcludePattern) {
     const envelopePath = locateFormEnvelopePath(objectBody);
     let envelope = objectBody;
     for (const seg of envelopePath) {
@@ -4078,7 +4185,7 @@ function applyStructuredValuePayloadSubstitutionsForObjectBody(template, objectB
     if (envelope === null || typeof envelope !== "object" || Array.isArray(envelope)) {
         return { result: template, nextSearchFrom: searchFrom };
     }
-    return applyStructuredValuePayloadSubstitutionsForEnvelope(template, envelope, outStructuredKeys, unconditionalExcludeValues, restrictedExcludeSourceByValue, searchFrom, envelopePath, objectBody);
+    return applyStructuredValuePayloadSubstitutionsForEnvelope(template, envelope, outStructuredKeys, unconditionalExcludeValues, restrictedExcludeSourceByValue, searchFrom, envelopePath, objectBody, payloadAccessorExcludePattern);
 }
 /**
  * `priorStepStateBindings` carries the SAME value→binding map
@@ -4087,13 +4194,23 @@ function applyStructuredValuePayloadSubstitutionsForObjectBody(template, objectB
  * field when its own leaf's key {@link keyNamesCorrelate}s with that source
  * name — an unrestricted binding (name-free, e.g. a bare array-index chain
  * hop) or a `joinFieldValues` entry excludes unconditionally on any leaf
- * match, same as before. Without the correlation requirement, an array/
+ * match, same as before. A `payloadAccessorExcludeValues` key excludes
+ * unconditionally too, but on a delimited-SUBSTRING match of the leaf (see
+ * {@link applyStructuredValuePayloadSubstitutionsForEnvelope}), not exact
+ * equality — the reported shape is a facet value recurring inside a captured
+ * array element with a constant suffix still attached (e.g. a hash-derived
+ * facet embedded in a `tags` entry alongside a trailing marker), so a
+ * candidate field whose leaf merely CONTAINS one of those literals at a token
+ * boundary is left alone here too, instead of being wholesale-swallowed into
+ * an opaque `${JSON.stringify(payload.<key>)}` blob before the substring-
+ * splice pass ({@link interpolateStateValues}) gets a chance to thread it.
+ * Without the correlation requirement on the restricted source, an array/
  * object field whose own unrelated short scalar leaf (a count/id) merely
  * EQUALS some other step's produced value gets the whole field wrongly
  * excluded from threading — the same value-coincidence class of bug
  * {@link keyNamesCorrelate}'s other call sites already guard against.
  */
-function applyStructuredValuePayloadSubstitutions(template, parsedBody, outStructuredKeys, priorStepStateBindings = new Map(), joinFieldValues = new Set()) {
+function applyStructuredValuePayloadSubstitutions(template, parsedBody, outStructuredKeys, priorStepStateBindings = new Map(), joinFieldValues = new Set(), payloadAccessorExcludeValues = new Map()) {
     if (parsedBody === null || typeof parsedBody !== "object") {
         return template;
     }
@@ -4105,7 +4222,10 @@ function applyStructuredValuePayloadSubstitutions(template, parsedBody, outStruc
         else
             unconditionalExcludeValues.add(value);
     }
-    // A cruise-line-style multi-room/multi-guest search body commonly batches
+    const payloadAccessorExcludePattern = payloadAccessorExcludeValues.size > 0
+        ? buildValueAlternationPattern([...payloadAccessorExcludeValues.keys()].sort((a, b) => b.length - a.length))
+        : null;
+    // A travel-brand-style multi-room/multi-guest search body commonly batches
     // per-element criteria as a top-level JSON ARRAY rather than a single
     // object. Walk each element in textual order (via the growing searchFrom
     // cursor) instead of bailing out here — otherwise any structured field
@@ -4117,13 +4237,13 @@ function applyStructuredValuePayloadSubstitutions(template, parsedBody, outStruc
         for (const element of parsedBody) {
             if (element === null || typeof element !== "object" || Array.isArray(element))
                 continue;
-            const { result: nextResult, nextSearchFrom } = applyStructuredValuePayloadSubstitutionsForObjectBody(result, element, outStructuredKeys, unconditionalExcludeValues, restrictedExcludeSourceByValue, cursor);
+            const { result: nextResult, nextSearchFrom } = applyStructuredValuePayloadSubstitutionsForObjectBody(result, element, outStructuredKeys, unconditionalExcludeValues, restrictedExcludeSourceByValue, cursor, payloadAccessorExcludePattern);
             result = nextResult;
             cursor = nextSearchFrom;
         }
         return result;
     }
-    const { result } = applyStructuredValuePayloadSubstitutionsForObjectBody(template, parsedBody, outStructuredKeys, unconditionalExcludeValues, restrictedExcludeSourceByValue, 0);
+    const { result } = applyStructuredValuePayloadSubstitutionsForObjectBody(template, parsedBody, outStructuredKeys, unconditionalExcludeValues, restrictedExcludeSourceByValue, 0, payloadAccessorExcludePattern);
     return result;
 }
 /** Maximum length to guard against indexing massive blobs (HTML fragments,
@@ -5750,6 +5870,63 @@ responseBodiesForCapacitySignal = []) {
  * steps declared any field to correlate against) or when a leaf's value has
  * no `key:value` segment matching one of them.
  */
+/** Yields every array-valued leaf in `value` (at any object nesting depth) —
+ * `{@link applyOptionalArrayFacetSplicePayloadSubstitutions}`'s raw-array
+ * search surface. Does not recurse INTO an array's own elements (a facet
+ * array is always a flat array of primitives in every observed recon shape),
+ * matching {@link walkAllPrimitiveLeaves}'s depth-first walk of everything
+ * else. */
+function* walkArrayLeaves(value, path = []) {
+    if (value === null || typeof value !== "object")
+        return;
+    if (Array.isArray(value)) {
+        yield { value, path };
+        return;
+    }
+    for (const [key, inner] of Object.entries(value)) {
+        yield* walkArrayLeaves(inner, [...path, key]);
+    }
+}
+/**
+ * REST-body counterpart to {@link spliceFacetsIntoArrayVariable}'s GraphQL
+ * use: a navigateTo facet's literal recurring as one array element (suffixed
+ * by a constant delimiter) inside a REST JSON body gets its element text
+ * swapped for `${payload.<field>}` by the plain `interpolateStateValues`
+ * splice later in the pipeline — but that pass only rewrites literal text
+ * IN PLACE, so when the matched facet is optional it would leave the array's
+ * frozen `undefined`-shaped element (and its JSON delimiter/comma) in the
+ * output whenever the caller omits the field, instead of omitting the
+ * element entirely.
+ *
+ * This pass runs first and, for any array that matches at least one OPTIONAL
+ * facet, rewrites the array's own frozen `JSON.stringify(...)` occurrence in
+ * the body template to a single `${JSON.stringify([...])}` splice point
+ * built from {@link spliceFacetsIntoArrayVariable}'s per-element conditional-
+ * emission shape — the same `...(payload.<field> ? [...] : [])` convention
+ * {@link spliceFacetsIntoStringVariable} already uses for the `key:value`
+ * grammar. A required-only match (no optional facet in that array) is left
+ * for the later plain splice to handle exactly as before — this pass is a
+ * no-op whenever nothing it rewrites would differ, so the existing
+ * required-only REST array-element shape (recon-generate-navigateto-array-
+ * element-facet-splice-e2e.test.ts) never changes.
+ */
+function applyOptionalArrayFacetSplicePayloadSubstitutions(template, inputBody, navigateToFacets) {
+    if (!navigateToFacets.some((facet) => facet.optional))
+        return template;
+    if (inputBody === null || typeof inputBody !== "object")
+        return template;
+    let result = template;
+    for (const { value } of walkArrayLeaves(inputBody)) {
+        const spliced = spliceFacetsIntoArrayVariable(value, navigateToFacets);
+        if (spliced === null || !spliced.includes("...(payload."))
+            continue;
+        const target = JSON.stringify(value);
+        if (!result.includes(target))
+            continue;
+        result = result.split(target).join(`\${JSON.stringify(${spliced})}`);
+    }
+    return result;
+}
 function applyFacetSplicePayloadSubstitutions(template, inputBody, payloadFieldNames, optionalFieldNames) {
     if (payloadFieldNames.size === 0)
         return template;
@@ -6012,6 +6189,109 @@ function emitFoldMatchAndMergeLines(terminalStep, target, itemVar, suffix, joinA
         `      Object.assign(${itemVar}, Object.fromEntries(Object.entries(foldMatch${suffix} ?? {}).filter(([k]) => !(k in ${itemVar}))));`,
     ];
 }
+/** Parses a URL's query string into a key→value map. Returns an empty map on
+ * a malformed URL or when there is no query string. */
+function parseUrlQueryParams(url) {
+    const params = new Map();
+    try {
+        for (const [key, value] of new URL(url).searchParams)
+            params.set(key, value);
+    }
+    catch {
+        // malformed URL — treat as having no query params
+    }
+    return params;
+}
+/** Parses a captured JSON request body into its string leaf values. Returns
+ * an empty array when the body is absent or not valid JSON. */
+function parseBodyLeafValues(requestPostData) {
+    if (!requestPostData)
+        return [];
+    try {
+        return [...walkStringLeaves(JSON.parse(requestPostData))].map((leaf) => leaf.value);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Walks `actions` in order and groups the query-string/body leaf values that
+ * appear in an action's own capture but did NOT appear in the immediately-
+ * preceding action's capture, PER TRANSITION (one entry per adjacent action
+ * pair that introduced at least one such value). This is the generic
+ * "what's new here" diff {@link correlateUnreachableNavigateToFacets} uses —
+ * kept per-transition (rather than flattened) so a transition that
+ * introduces more than one new value, or multiple transitions that fire
+ * between two facets' real actions, can be told apart from the single clean
+ * transition a lone facet causes.
+ *
+ * The first action never contributes: with no predecessor to diff against,
+ * every one of its values would trivially count as "new", which is nearly
+ * always the baseline/listing call a navigateTo-declared filter does NOT
+ * affect (the already-working recurrence-anchored path exists precisely
+ * because a real facet DOES recur in a later request; nothing here changes
+ * that — this only supplies values for facets that are not found at all).
+ */
+function collectNewlyAppearingRequestValueTransitions(actions) {
+    const seenGlobally = new Set();
+    const transitions = [];
+    for (let i = 1; i < actions.length; i++) {
+        const prior = actions[i - 1].capture;
+        const current = actions[i].capture;
+        const seenThisTransition = new Set();
+        const values = [];
+        const record = (value) => {
+            if (value.length === 0 || seenGlobally.has(value) || seenThisTransition.has(value))
+                return;
+            seenThisTransition.add(value);
+            values.push(value);
+        };
+        const priorParams = parseUrlQueryParams(prior.url);
+        for (const [key, value] of parseUrlQueryParams(current.url)) {
+            if (priorParams.get(key) !== value)
+                record(value);
+        }
+        const priorLeaves = new Set(parseBodyLeafValues(prior.requestPostData));
+        for (const value of parseBodyLeafValues(current.requestPostData)) {
+            if (!priorLeaves.has(value))
+                record(value);
+        }
+        for (const value of values)
+            seenGlobally.add(value);
+        if (values.length > 0)
+            transitions.push(values);
+    }
+    return transitions;
+}
+/**
+ * Resolves each zero-recurrence navigateTo facet (in flow order) to the real
+ * request value it causally affects, or returns `null` when the correlation
+ * cannot be trusted.
+ *
+ * Pairing is positional — facet N gets the Nth qualifying transition — which
+ * is only safe when every transition in the pool is itself unambiguous (an
+ * action introduced EXACTLY ONE new value, so there is no question which
+ * value within it is "the" new one) AND the pool's size exactly matches the
+ * number of facets awaiting a value. A transition that introduces more than
+ * one new value is dropped from the pool entirely rather than guessing which
+ * of its values is real; if that drops the pool below (or an unrelated
+ * single-value transition pushes it above) the facet count, the pairing is
+ * no longer guaranteed to line facets up with the RIGHT transition, so
+ * nothing is bound — leaving a facet declared-but-unbound is preferable to
+ * silently wiring it to another facet's (or an unrelated transition's) value.
+ */
+function correlateUnreachableNavigateToFacets(facets, actions) {
+    const unambiguousValues = collectNewlyAppearingRequestValueTransitions(actions)
+        .filter((transition) => transition.length === 1)
+        .map((transition) => transition[0]);
+    if (unambiguousValues.length !== facets.length)
+        return null;
+    const byField = new Map();
+    facets.forEach(({ field }, index) => {
+        byField.set(field, unambiguousValues[index]);
+    });
+    return byField;
+}
 /** Exported for unit testing — lets tests drive the multipart-upload code path directly
  * without going through the full emitContractTs pipeline. */
 function emitMultiStepExecuteHttp(actions, inputBody, errorSignals, fieldNameMap, outDiscoveredFields, fieldOptionsMap, outDiscoveredOptionFields, outDiscoveredRawOptionFields, outDiscoveredAdditionalBodyKeys, baseUrl, baseUrlDerivedHeaders, tenantSubdomainHeaders, formSchema = null, personaBindings = new Map(), entryUrlParams = new Map(), shieldedUuids = new Set(), selectResolutions = [], outStructuredKeys = new Map(), rawCodeFields = new Map(), foldReturnSpec = null, 
@@ -6127,6 +6407,53 @@ flowSteps = [], vocabulary = undefined) {
         if (field !== null && /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(field))
             outDiscoveredFields.add(field);
     }
+    // Fallback for a navigateTo step's declared `payloadField` whose extracted
+    // hash literal has ZERO recurrence anywhere in the capture — not merely
+    // blocked by the collision guard above, but genuinely absent from every
+    // action's URL, body, AND headers. `harvestPersonaBindings` can only ever
+    // register the one raw literal it extracted; when the site never replays
+    // that literal verbatim (it's transformed, mapped to a backend code, or
+    // otherwise re-shaped before the real request), the field is structurally
+    // unreachable by the recurrence-anchored path above, exactly like a
+    // declared-but-never-bound schema field.
+    //
+    // Site-agnostic, position/causality-based correlation: a navigateTo step
+    // always precedes the real request its facet affects, so each such
+    // unreachable facet (in flow order) is paired with the next "new" value —
+    // a query-string or body leaf that a later action's capture carries but
+    // its immediately-preceding action's capture does not — found by walking
+    // the actions in order. This is a best-effort structural guarantee, not a
+    // completeness proof: when the adjacent action's own capture carries no
+    // new value at all (the facet's effect is purely server-side / implicit),
+    // or when the correlation is ambiguous (see
+    // `correlateUnreachableNavigateToFacets`), there is nothing safe to splice
+    // and the field(s) stay unbound rather than risk a wrong binding.
+    const appearsAnywhereInCapture = (value) => actions.some((action) => action.capture.url.includes(value) ||
+        (action.capture.requestPostData?.includes(value) ?? false) ||
+        Object.values(action.capture.requestHeaders).some((h) => h.includes(value)));
+    // Hoisted once so both the unreachable-facet fallback above and the
+    // REST array-element optional splice below (applyOptionalArrayFacetSplice
+    // PayloadSubstitutions) share the exact same (value, field, optional)
+    // triples — the array splice must see each binding's `optional` flag
+    // precisely as the flow declared it, same as the already-fixed GraphQL
+    // array-variable path ({@link spliceFacetsIntoArrayVariable}).
+    const navigateToFacetOrder = extractNavigateToFacetOrder(flowSteps);
+    const unreachableNavigateToFacets = navigateToFacetOrder.filter(({ value }) => !appearsAnywhereInCapture(value));
+    if (unreachableNavigateToFacets.length > 0) {
+        const correlated = correlateUnreachableNavigateToFacets(unreachableNavigateToFacets, actions);
+        for (const { field } of correlated === null ? [] : unreachableNavigateToFacets) {
+            const diffed = correlated?.get(field);
+            if (diffed === undefined)
+                continue;
+            if (!bindsWithoutCollision(diffed))
+                continue;
+            if (payloadAccessorByValue.has(diffed))
+                continue;
+            payloadAccessorByValue.set(diffed, `payload.${field}`);
+            if (isValidJsIdentifier(field))
+                outDiscoveredFields.add(field);
+        }
+    }
     // Job coordinates from the recon entry URL's query string (e.g.
     // `?jobSeqNo=...`). Registered the same way as BaseUrl so every verbatim
     // occurrence — and, via length-descending order, embedded substrings like a
@@ -6380,6 +6707,16 @@ flowSteps = [], vocabulary = undefined) {
         const rawBodyWithFacetSplices = parsedBody !== null
             ? applyFacetSplicePayloadSubstitutions(rawBodyWithFormSubs, parsedBody, restPayloadFieldNames, restOptionalFieldNames)
             : rawBodyWithFormSubs;
+        // Optional-facet array-element splice — a navigateTo facet literal
+        // recurring as one element of an array field (not the `key:value`
+        // grammar above) must drop its own element, not freeze an `undefined`,
+        // when its binding is optional and the caller omits it. Runs BEFORE
+        // Mechanism B (below) can swallow the whole array wholesale as an
+        // unparameterized structured value — see
+        // {@link applyOptionalArrayFacetSplicePayloadSubstitutions}.
+        const rawBodyWithOptionalArrayFacetSplices = parsedBody !== null
+            ? applyOptionalArrayFacetSplicePayloadSubstitutions(rawBodyWithFacetSplices, parsedBody, navigateToFacetOrder)
+            : rawBodyWithFacetSplices;
         // Mechanism B — parameterize whole nested caller structures
         // (experienceData/educationData history, opaque eventData) BEFORE value
         // substitution reaches inside them: swallowing the entire array/object first
@@ -6390,7 +6727,7 @@ flowSteps = [], vocabulary = undefined) {
         // dependent-drill-down join field (e.g. a bulk `{"tokens":[...]}` lookup)
         // must stay reachable for state threading, not get frozen as caller data.
         const rawBodyWithStructuredSubs = parsedBody !== null
-            ? applyStructuredValuePayloadSubstitutions(rawBodyWithFacetSplices, parsedBody, outStructuredKeys, deriveStateVarByValue(prior, cap), joinFieldValuesByStep.get(i) ?? new Set())
+            ? applyStructuredValuePayloadSubstitutions(rawBodyWithOptionalArrayFacetSplices, parsedBody, outStructuredKeys, deriveStateVarByValue(prior, cap), joinFieldValuesByStep.get(i) ?? new Set(), payloadAccessorByValue)
             : rawBodyWithFormSubs;
         // Whole-value caller coordinates bind here — after structured subs, BEFORE
         // state threading — so a composite coordinate (a jobLocation or jobSeqNo
@@ -7313,6 +7650,50 @@ function spliceFacetsIntoStringVariable(value, fields, optionalFields = new Set(
     }
     return `[${elements.join(", ")}].join("")`;
 }
+/**
+ * Splices a captured array-valued GraphQL variable's elements against
+ * navigateTo facet bindings instead of the `key:value` segment grammar
+ * {@link spliceFacetsIntoStringVariable} matches — an array element like
+ * `widget-x;filterId=urlFriendlyId` carries a bare literal plus a constant
+ * trailing delimiter, with no `key:` prefix to key off of. Matching is
+ * token-boundary guarded the same way {@link bindsWithoutCollision} (recon-
+ * generate.ts ~7223) guards persona bindings elsewhere in this file, so a
+ * facet literal that's merely a substring of an unrelated element never
+ * misfires. A matched binding whose `optional` flag is set is emitted as a
+ * conditionally-included array element (`...(payload.<field> ? [...] : [])`)
+ * instead of inline, the same optional-splice convention
+ * {@link spliceFacetsIntoStringVariable} uses, so an absent optional facet
+ * drops its element rather than emitting `undefined`.
+ */
+function spliceFacetsIntoArrayVariable(value, facets) {
+    if (!Array.isArray(value))
+        return null;
+    const isAlnum = (ch) => ch !== undefined && /[A-Za-z0-9]/.test(ch);
+    const matchFacet = (element) => facets.find(({ value: literal }) => {
+        if (element === literal)
+            return true;
+        if (!element.startsWith(literal))
+            return false;
+        return !isAlnum(element[literal.length]);
+    });
+    let matchCount = 0;
+    const elements = value.map((element) => {
+        if (typeof element !== "string")
+            return JSON.stringify(element);
+        const matched = matchFacet(element);
+        if (!matched)
+            return JSON.stringify(element);
+        matchCount++;
+        const suffix = element.slice(matched.value.length);
+        const elementLiteral = `\`\${payload.${matched.field}}${escapeForTemplateLiteral(suffix)}\``;
+        return matched.optional
+            ? `...(payload.${matched.field} ? [${elementLiteral}] : [])`
+            : elementLiteral;
+    });
+    if (matchCount === 0)
+        return null;
+    return `[${elements.join(", ")}]`;
+}
 /**
  * Renders the variables literal for the primary-operation getGql() call —
  * each key from the selected capture's own recorded variables is bound to
@@ -7324,9 +7705,12 @@ function spliceFacetsIntoStringVariable(value, fields, optionalFields = new Set(
  * other value is emitted verbatim via JSON.stringify. `optionalFieldNames`
  * marks which of `payloadFieldNames` a facet-string splice should treat as
  * optional (see {@link spliceFacetsIntoStringVariable}); it has no effect on
- * top-level key correlation.
+ * top-level key correlation. When a value is an array (not itself a string
+ * key correlation candidate), its elements are matched against
+ * `navigateToFacets` instead — see {@link spliceFacetsIntoArrayVariable} for
+ * why that's a distinct grammar from the `key:value` one above.
  */
-function renderGqlVariablesExpr(variables, payloadFieldNames, optionalFieldNames = new Set()) {
+function renderGqlVariablesExpr(variables, payloadFieldNames, optionalFieldNames = new Set(), navigateToFacets = []) {
     if (variables === null || typeof variables !== "object" || Array.isArray(variables))
         return "{}";
     const fields = payloadFieldNames ? [...payloadFieldNames] : [];
@@ -7334,7 +7718,8 @@ function renderGqlVariablesExpr(variables, payloadFieldNames, optionalFieldNames
         const matchedField = fields.find((field) => field.toLowerCase() === key.toLowerCase());
         const facetSpliceExpr = matchedField
             ? null
-            : spliceFacetsIntoStringVariable(value, fields, optionalFieldNames);
+            : (spliceFacetsIntoStringVariable(value, fields, optionalFieldNames) ??
+                spliceFacetsIntoArrayVariable(value, navigateToFacets));
         const valueExpr = matchedField
             ? `payload.${matchedField}`
             : (facetSpliceExpr ?? JSON.stringify(value));
@@ -7771,7 +8156,7 @@ function isExplainedByCorrelatedSiblingField(path, parsedBody, otherBodies, sibl
  * iteration's request, exactly the defect described in
  * docs/recon-generate-nested-fold-flatmaps-away-the-parent-so-drill-params-freeze.md
  * (a `packageCode`/`groupId`/`sailDate` triple that provably varies per
- * cruise, silently frozen because no threaded field explained it). Path
+ * voyage, silently frozen because no threaded field explained it). Path
  * segments are deliberately not checked: {@link endpointKey} requires an
  * identical pathname to group two captures at all, so no path segment can
  * ever be observed to vary within a matched group.
@@ -10348,7 +10733,7 @@ function buildContractChecklist(opts) {
 /** Generates a complete contract.ts source string for a plugin — exported so
  * unit tests can drive the emitter directly without spawning the CLI. */
 function emitContractTs(opts) {
-    const { siteId, displayName, pascal, baseUrl, baseHeaders, minTime, safeRps, hasRateLimitProbeData = false, responseBody, responseBodySamples = [responseBody], gql, gqlQuery, endpointPath, gqlOperationName, gqlVariables, allCaptures = [], auxFiles, multiStepBody, omitExecuteHttp = false, isSubmissionFlow = false, inputBody, hasMultipartStep = false, actionSteps = [], foldReturnSpec = null, discoveredFormFields, fieldOptionsMap, discoveredOptionFields, discoveredRawOptionFields, discoveredAdditionalBodyKeys, discoveredStructuredKeys, valueConstraints = value_constraints_1.EMPTY_VALUE_CONSTRAINTS, payloadFieldNames, optionalPayloadFieldNames = new Set(), headerBindings = [], unpopulatedDeclaredVariables = [], fallbackGateSpec = {}, } = opts;
+    const { siteId, displayName, pascal, baseUrl, baseHeaders, minTime, safeRps, hasRateLimitProbeData = false, responseBody, responseBodySamples = [responseBody], gql, gqlQuery, endpointPath, gqlOperationName, gqlVariables, allCaptures = [], auxFiles, multiStepBody, omitExecuteHttp = false, isSubmissionFlow = false, inputBody, hasMultipartStep = false, actionSteps = [], foldReturnSpec = null, discoveredFormFields, fieldOptionsMap, discoveredOptionFields, discoveredRawOptionFields, discoveredAdditionalBodyKeys, discoveredStructuredKeys, valueConstraints = value_constraints_1.EMPTY_VALUE_CONSTRAINTS, payloadFieldNames, optionalPayloadFieldNames = new Set(), flowSteps: contractFlowSteps = [], headerBindings = [], unpopulatedDeclaredVariables = [], fallbackGateSpec = {}, } = opts;
     const { browserFallbackGate, httpTimeoutMs } = fallbackGateSpec;
     /** Single source of truth for every GraphQL-emission decision below
      * (clientImport, gqlCacheBlock, queryConst, and both executeHttpBody
@@ -10858,10 +11243,11 @@ const httpClient = createHttpClient({ schema: ${pascal}ResponseSchema, bottlenec
     // the same captured request-variables object the signal was itself
     // detected from (see paginationOperationIdentity above) — the default
     // `{ q: payload.query }` REST body has no skip/count container to advance.
+    const navigateToFacets = extractNavigateToFacetOrder(contractFlowSteps);
     const gqlVariablesExpr = gqlOperationName
-        ? renderGqlVariablesExpr(gqlVariables, payloadFieldNames, optionalPayloadFieldNames)
+        ? renderGqlVariablesExpr(gqlVariables, payloadFieldNames, optionalPayloadFieldNames, navigateToFacets)
         : paginationSignal
-            ? renderGqlVariablesExpr(gqlVariables, payloadFieldNames, optionalPayloadFieldNames)
+            ? renderGqlVariablesExpr(gqlVariables, payloadFieldNames, optionalPayloadFieldNames, navigateToFacets)
             : "{ q: payload.query }";
     /** Builds the nested `for` loop block(s) — see {@link pathToFoldLoopLines}
      * — that fold every resolved plan's drill-down data onto `dataVarName`'s
@@ -11610,7 +11996,10 @@ function computeFlowPayloadFieldNames(flowSteps, vocabulary, env) {
         if (isObj && step.navigateTo !== undefined) {
             if (step.payloadField) {
                 payloadFieldNames.add(step.payloadField);
-                registerFieldOptionality(step.payloadField, step.optional === true);
+                // An explicitly declared payloadField is always required at the
+                // schema level, independent of step.optional's execution-skip
+                // semantics (which the browser-flow step record still honors as-is).
+                registerFieldOptionality(step.payloadField, false);
             }
             continue;
         }
@@ -11623,9 +12012,13 @@ function computeFlowPayloadFieldNames(flowSteps, vocabulary, env) {
             ? resolveCompositePersonaFields(instruction, knownFieldValues)
             : null;
         const optional = isObj ? step.optional === true : false;
+        const explicit = isObj ? step.payloadField : undefined;
         if (field !== null) {
             payloadFieldNames.add(field);
-            registerFieldOptionality(field, optional);
+            // An explicit payloadField annotation is always required at the
+            // schema level; only the vocabulary/composite-persona heuristic falls
+            // back to step.optional's execution-skip semantics.
+            registerFieldOptionality(field, explicit ? false : optional);
         }
         if (composite !== null) {
             payloadFieldNames.add(composite.fieldA);
@@ -12725,6 +13118,7 @@ async function main() {
             isSubmissionFlow,
             inputBody,
             hasMultipartStep,
+            flowSteps,
             actionSteps,
             foldReturnSpec,
             discoveredFormFields,