@enricai/barnacle 1.12.74 → 1.12.76

package/dist/scripts/recon-generate.js

@@ -24,8 +24,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveStepPayloadField = resolveStepPayloadField;
 exports.buildKnownFieldValues = buildKnownFieldValues;
 exports.extractStepPersonaValue = extractStepPersonaValue;
+exports.extractNavigateToHashFragmentValue = extractNavigateToHashFragmentValue;
 exports.deriveFillLabelField = deriveFillLabelField;
 exports.harvestPersonaBindings = harvestPersonaBindings;
+exports.extractNavigateToFacetOrder = extractNavigateToFacetOrder;
 exports.resolveCompositePersonaFields = resolveCompositePersonaFields;
 exports.collectConditionalGraphQLFieldNames = collectConditionalGraphQLFieldNames;
 exports.inferZodSchemaFromSamples = inferZodSchemaFromSamples;
@@ -60,6 +62,7 @@ exports.ancestorScopedAccessor = ancestorScopedAccessor;
 exports.compileActionSteps = compileActionSteps;
 exports.collectHeaderBindings = collectHeaderBindings;
 exports.deriveProducerBoundaryBindings = deriveProducerBoundaryBindings;
+exports.collectUnboundLiterals = collectUnboundLiterals;
 exports.emitMultiStepExecuteHttp = emitMultiStepExecuteHttp;
 exports.countSpliceableFacets = countSpliceableFacets;
 exports.spliceFacetsIntoStringVariable = spliceFacetsIntoStringVariable;
@@ -359,6 +362,34 @@ function extractStepPersonaValue(instruction, env) {
     const value = pickValueSpan(instruction, spans).value;
     return value.length > 0 ? value : null;
 }
+/**
+ * Extracts the trailing path segment of a navigateTo URL's hash fragment —
+ * e.g. `.../#/jobs/category-widgets` yields `widgets` — as the persona value
+ * an explicit `payloadField` annotation on that step names. Site-agnostic:
+ * reads only the URL's own hash shape, no domain knowledge.
+ *
+ * When `previousHash` is given and the current hash is a strict extension of
+ * it (the accumulating-hash case, e.g. `#a` -> `#a,b`), the persona value is
+ * only the NEW suffix the step added, not the whole cumulative string — a
+ * cumulative value would never recur verbatim in any single request literal.
+ *
+ * @returns the segment (or delta), or null when the URL has no non-empty
+ *   hash segment
+ */
+function extractNavigateToHashFragmentValue(url, previousHash) {
+    const hashIndex = url.indexOf("#");
+    if (hashIndex === -1)
+        return null;
+    const hash = url.slice(hashIndex + 1);
+    if (previousHash && hash.length > previousHash.length && hash.startsWith(previousHash)) {
+        const suffix = hash.slice(previousHash.length);
+        const delta = /^[,/]/.test(suffix) ? suffix.slice(1) : suffix;
+        if (delta.length > 0)
+            return delta;
+    }
+    const segments = hash.split("/").filter((s) => s.length > 0);
+    return segments.length > 0 ? segments[segments.length - 1] : null;
+}
 /**
  * Derives a payload field name from the field LABEL in a fill/enter/type
  * instruction, for steps the consumer vocabulary does not cover.
@@ -405,9 +436,32 @@ function deriveFillLabelField(instruction) {
 function harvestPersonaBindings(flowSteps, vocabulary, env) {
     const bindings = new Map();
     const knownFieldValues = buildKnownFieldValues(flowSteps, vocabulary, env);
+    let previousNavigateToHash;
     for (const step of flowSteps) {
         const isObj = typeof step !== "string";
         const instruction = isObj ? step.step : step;
+        // A navigateTo step carries no prose instruction to extract a persona
+        // value FROM — its own text is a captured page.goto, not a fill/select
+        // label. The facet an explicit `payloadField` annotation names instead
+        // lives in the URL itself (recon-browser captures navigation targets like
+        // `.../#/jobs/category-widgets`), so the value to correlate against
+        // downstream header/body templates is the URL's own hash-derived
+        // fragment, not anything extractStepPersonaValue could find in `step.step`.
+        if (isObj && step.navigateTo !== undefined) {
+            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)
+                continue;
+            if (!bindings.has(value))
+                bindings.set(value, `payload.${step.payloadField}`);
+            continue;
+        }
         const vocabField = resolveStepPayloadField(instruction, isObj ? step.payloadField : undefined, isObj ? step.payloadFieldNone : undefined, vocabulary, knownFieldValues);
         // Vocabulary wins outright. Only on a miss do we fall back to deriving the
         // field from the instruction's own label — and never when the author opted
@@ -428,6 +482,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 });
+    }
+    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
@@ -3913,7 +3997,7 @@ 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, priorStepStateValues, searchFrom, envelopePath, rootBody) {
+function applyStructuredValuePayloadSubstitutionsForEnvelope(template, envelope, outStructuredKeys, unconditionalExcludeValues, restrictedExcludeSourceByValue, searchFrom, envelopePath, rootBody) {
     let result = template;
     let cursor = searchFrom;
     // The body root's own entries are eligible too, whenever the located
@@ -3935,8 +4019,29 @@ function applyStructuredValuePayloadSubstitutionsForEnvelope(template, envelope,
             Object.keys(value).length > 0;
         if (!isNonEmptyArray && !isNestedObject)
             continue;
-        if (priorStepStateValues.size > 0) {
-            const carriesThreadedValue = [...walkAllPrimitiveLeaves(value)].some(({ value: leaf }) => leaf !== null && priorStepStateValues.has(String(leaf)));
+        if (unconditionalExcludeValues.size > 0 || restrictedExcludeSourceByValue.size > 0) {
+            // 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
+            // keyNamesCorrelate(sourceName, key) — mirroring the discipline
+            // replaceGuardedAgainstExistingPlaceholders/findThreadedJoinFields already
+            // apply to the exact same class of value-coincidence false positive.
+            // Without this, a broken field's own unrelated short scalar leaf (a
+            // 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.
+            const carriesThreadedValue = [...walkAllPrimitiveLeaves(value)].some(({ value: leaf, path: leafPath }) => {
+                if (leaf === null)
+                    return false;
+                const leafValue = String(leaf);
+                if (unconditionalExcludeValues.has(leafValue))
+                    return true;
+                const sourceName = restrictedExcludeSourceByValue.get(leafValue);
+                if (sourceName === undefined)
+                    return false;
+                const leafKey = leafPath.at(-1);
+                return leafKey !== undefined && keyNamesCorrelate(sourceName, leafKey);
+            });
             if (carriesThreadedValue)
                 continue;
         }
@@ -3993,7 +4098,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, priorStepStateValues, searchFrom) {
+function applyStructuredValuePayloadSubstitutionsForObjectBody(template, objectBody, outStructuredKeys, unconditionalExcludeValues, restrictedExcludeSourceByValue, searchFrom) {
     const envelopePath = locateFormEnvelopePath(objectBody);
     let envelope = objectBody;
     for (const seg of envelopePath) {
@@ -4004,12 +4109,33 @@ function applyStructuredValuePayloadSubstitutionsForObjectBody(template, objectB
     if (envelope === null || typeof envelope !== "object" || Array.isArray(envelope)) {
         return { result: template, nextSearchFrom: searchFrom };
     }
-    return applyStructuredValuePayloadSubstitutionsForEnvelope(template, envelope, outStructuredKeys, priorStepStateValues, searchFrom, envelopePath, objectBody);
+    return applyStructuredValuePayloadSubstitutionsForEnvelope(template, envelope, outStructuredKeys, unconditionalExcludeValues, restrictedExcludeSourceByValue, searchFrom, envelopePath, objectBody);
 }
-function applyStructuredValuePayloadSubstitutions(template, parsedBody, outStructuredKeys, priorStepStateValues = new Set()) {
+/**
+ * `priorStepStateBindings` carries the SAME value→binding map
+ * {@link deriveStateVarByValue} produces. A binding with `restricted: true`
+ * (a value whose source has a real field name) only excludes a candidate
+ * 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/
+ * 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()) {
     if (parsedBody === null || typeof parsedBody !== "object") {
         return template;
     }
+    const unconditionalExcludeValues = new Set(joinFieldValues);
+    const restrictedExcludeSourceByValue = new Map();
+    for (const [value, binding] of priorStepStateBindings) {
+        if (binding.restricted)
+            restrictedExcludeSourceByValue.set(value, binding.sourceName);
+        else
+            unconditionalExcludeValues.add(value);
+    }
     // A cruise-line-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
@@ -4022,13 +4148,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, priorStepStateValues, cursor);
+            const { result: nextResult, nextSearchFrom } = applyStructuredValuePayloadSubstitutionsForObjectBody(result, element, outStructuredKeys, unconditionalExcludeValues, restrictedExcludeSourceByValue, cursor);
             result = nextResult;
             cursor = nextSearchFrom;
         }
         return result;
     }
-    const { result } = applyStructuredValuePayloadSubstitutionsForObjectBody(template, parsedBody, outStructuredKeys, priorStepStateValues, 0);
+    const { result } = applyStructuredValuePayloadSubstitutionsForObjectBody(template, parsedBody, outStructuredKeys, unconditionalExcludeValues, restrictedExcludeSourceByValue, 0);
     return result;
 }
 /** Maximum length to guard against indexing massive blobs (HTML fragments,
@@ -5742,13 +5868,14 @@ function applyVolatileFieldSubstitutions(template, parsedBody, shieldedUuids, bo
     return result;
 }
 /**
- * Collects captured string leaves that survived every binding/generation pass as
- * still-literal — the values a reviewer must look at because they couldn't be
- * traced to a payload field, a generator, or a schema anchor. Returns the JSON
- * key names (deduped, in first-seen order) so the emitter can prepend a single
- * `// TODO: unbound captured literal` marker; it never mutates the body, so the
- * file still compiles. Short values (< {@link MIN_STATE_VALUE_LENGTH}) are
- * skipped — they are the legitimately-constant enum-like fields.
+ * Collects captured string leaves AND whole array/object values that survived
+ * every binding/generation pass as still-literal — the values a reviewer must
+ * look at because they couldn't be traced to a payload field, a generator, or
+ * a schema anchor. Returns the JSON key names (deduped, in first-seen order)
+ * so the emitter can prepend a single `// TODO: unbound captured literal`
+ * marker; it never mutates the body, so the file still compiles. Short string
+ * values (< {@link MIN_STATE_VALUE_LENGTH}) are skipped — they are the
+ * legitimately-constant enum-like fields.
  */
 function collectUnboundLiterals(finalTemplate, parsedBody, shieldedUuids) {
     const unbound = [];
@@ -5767,6 +5894,20 @@ function collectUnboundLiterals(finalTemplate, parsedBody, shieldedUuids) {
             unbound.push(key);
         }
     }
+    if (parsedBody !== null && typeof parsedBody === "object") {
+        for (const [key, value] of Object.entries(parsedBody)) {
+            if (value === null || typeof value !== "object")
+                continue;
+            if (seen.has(key))
+                continue;
+            // Whole array/object value never got threaded as a unit — ${JSON.stringify(...)}
+            // never replaced it, so it still sits verbatim in the emitted template.
+            if (finalTemplate.includes(JSON.stringify(value))) {
+                seen.add(key);
+                unbound.push(key);
+            }
+        }
+    }
     return unbound;
 }
 /** Builds the multi-step `executeHttp` body as a single template-literal string.
@@ -5902,6 +6043,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, 
@@ -6017,6 +6261,46 @@ 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)));
+    const unreachableNavigateToFacets = extractNavigateToFacetOrder(flowSteps).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
@@ -6280,10 +6564,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, new Set([
-                ...deriveStateVarByValue(prior, cap).keys(),
-                ...(joinFieldValuesByStep.get(i) ?? []),
-            ]))
+            ? applyStructuredValuePayloadSubstitutions(rawBodyWithFacetSplices, parsedBody, outStructuredKeys, deriveStateVarByValue(prior, cap), joinFieldValuesByStep.get(i) ?? new Set())
             : rawBodyWithFormSubs;
         // Whole-value caller coordinates bind here — after structured subs, BEFORE
         // state threading — so a composite coordinate (a jobLocation or jobSeqNo
@@ -11491,10 +11772,25 @@ function computeFlowPayloadFieldNames(flowSteps, vocabulary, env) {
     for (const step of flowSteps) {
         const isObj = typeof step !== "string";
         const instruction = isObj ? step.step : step;
-        // navigateTo/emailStep/password-token steps bypass field resolution
-        // entirely — see emitBrowserFlowTs's stepLiterals pass for why.
-        if (isObj && step.navigateTo !== undefined)
+        // A navigateTo step's own instruction text bypasses field resolution —
+        // it's a captured page.goto, not a prose instruction, so there is no
+        // label/quoted-constant to correlate (see emitBrowserFlowTs's stepLiterals
+        // pass). An explicit `payloadField` annotation is a different thing: it is
+        // the author directly naming the facet the navigation target encodes, and
+        // resolveStepPayloadField's own `explicit` short-circuit would honor it
+        // unconditionally — so it must still be registered here, or every
+        // downstream consumer of this accumulator (REST facet-splice, schema
+        // declaration) silently drops the facet the author explicitly declared.
+        if (isObj && step.navigateTo !== undefined) {
+            if (step.payloadField) {
+                payloadFieldNames.add(step.payloadField);
+                // 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;
+        }
         if (isObj && step.emailStep === true)
             continue;
         if (instruction.includes(RECON_PASSWORD_TOKEN))
@@ -11504,9 +11800,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);