@molecule/api-ai-tools 1.9.16 → 1.9.19

package/dist/trace-artifacts.js

@@ -27,7 +27,6 @@
  * @module
  */
 import { locatedCommandSegments, statementArgumentEnd } from './command-position.js';
-import { isDiagnosisRun } from './suite-overlap.js';
 import { isPlaywrightRunCommand, redactSecrets } from './utilities.js';
 /** How many traces one read reports, newest first. */
 export const MAX_TRACE_ARTIFACTS = 12;
@@ -198,6 +197,32 @@ function messageOf(value) {
   return null
 }
 
+// A fill/type/selectOption records what the test typed; the note compares it with the body the
+// page submitted (m173: the Settings form sent bio:"" although the test had just typed a value).
+// Only those actions keep it, so a click's selector does not ride every row.
+const FILLING_ACTION = /\\.(?:fill|type|pressSequentially|selectOption)$/
+
+// The text a failing assertion waited for, named by its own error: a \`has-text(…)\` CSS
+// pseudo-class, a \`getByText(…)\` locator, or a \`toContainText(…)\` expectation. A strict-mode
+// violation is not this shape — two elements DID match the text — and neither is a wait on a
+// selector with no text argument. The ANSI colouring Playwright leaves in the message is dropped
+// before the read, or the quotes it wraps around a locator would never parse.
+function waitedTextOf(message) {
+  if (!message) return null
+  const text = String(message).replace(/\\u001b\\[[0-9;]*m/g, '')
+  if (text.indexOf('strict mode violation') !== -1) return null
+  const quoted = function (pattern) {
+    const m = pattern.exec(text)
+    return m === null ? null : m[2]
+  }
+  const hasText = quoted(/has-text\\(\\s*(['"])((?:(?!\\1).)*)\\1/)
+  if (hasText !== null) return hasText
+  const byText = quoted(/getByText\\(\\s*(['"])((?:(?!\\1).)*)\\1/)
+  if (byText !== null) return byText
+  if (text.indexOf('toContainText') === -1) return null
+  return quoted(/Expected(?: string)?:\\s*(["'])((?:(?!\\1).)*)\\1/)
+}
+
 // A request/response body exactly as Playwright stored it: inline on the value, or in a resource
 // entry the value names. Bounded, and binary is dropped — a JSON body is what this is for, and a
 // multipart upload would print bytes.
@@ -426,14 +451,19 @@ for (const one of found.slice(0, MAX_TRACES)) {
       if (!entry || entry.type !== 'before') continue
       if (typeof entry.class !== 'string' || typeof entry.method !== 'string') continue
       if (entry.class === 'Test' || typeof entry.startTime !== 'number') continue
+      const api = entry.class + '.' + entry.method
+      const params = entry.params && typeof entry.params === 'object' ? entry.params : {}
+      const filling = FILLING_ACTION.test(api)
       const action = {
-        api: entry.class + '.' + entry.method,
+        api: api,
         start: entry.startTime,
         end: typeof ended[entry.callId] === 'number' ? ended[entry.callId] : null,
         context: ctx.id,
         pageId: typeof entry.callId === 'string' ? pageByCall[entry.callId] : undefined,
         frameId: undefined,
         stepId: typeof entry.stepId === 'string' ? entry.stepId : undefined,
+        ...(filling && typeof params.selector === 'string' ? { selector: params.selector } : {}),
+        ...(filling && typeof params.value === 'string' ? { value: params.value } : {}),
       }
       if (action.pageId !== undefined) {
         for (const frame of ctx.frames) {
@@ -459,6 +489,7 @@ for (const one of found.slice(0, MAX_TRACES)) {
   let failedStepId = null
   let failedStep = null
   let failedEnd = null
+  let failedError = ''
   let failureSpec = null
   let failureLine = 0
   let lastSpec = null
@@ -468,6 +499,7 @@ for (const one of found.slice(0, MAX_TRACES)) {
     if (entry.type === 'after' && entry.error && typeof entry.callId === 'string' && failedStepId === null) {
       failedStepId = entry.callId
       failedEnd = typeof entry.endTime === 'number' ? entry.endTime : null
+      failedError = messageOf(entry.error) || ''
     }
   }
   // The fallback location — the last step that names a spec — is read from every member, runner
@@ -710,6 +742,26 @@ for (const one of found.slice(0, MAX_TRACES)) {
     if (sent) r.sent = sent
     if (got) r.got = got
   }
+  // The text the failing assertion waited for, and a response the SAME page received that carried
+  // it (m169). The assertion's own error names the text; the network log says whether it ever
+  // reached the browser. Only an answered fetch/xhr can say the API returned it — a 4xx body is an
+  // error message, not data. The most focused response wins (smallest body): an articles list also
+  // carries tag names in its \`tagList\`, while the tags response is the collection whose membership
+  // the assertion tests.
+  const waitedText = waitedTextOf(failedError)
+  let missingText = null
+  if (waitedText !== null && !unattributed) {
+    let best = null
+    for (const r of requests) {
+      if (r.type !== 'fetch' && r.type !== 'xhr') continue
+      if (r.status < 200 || r.status >= 400) continue
+      const got = gotText(buf, entries, r)
+      if (!got || got.indexOf(waitedText) === -1) continue
+      if (best === null || got.length < best.got.length) best = { request: r, got: got }
+    }
+    if (best !== null)
+      missingText = { text: waitedText, method: best.request.method, path: best.request.path }
+  }
   function wire(r) {
     return {
       method: r.method,
@@ -881,6 +933,7 @@ for (const one of found.slice(0, MAX_TRACES)) {
     // tail here dropped every failed request as soon as a page made more than MAX_REQUESTS of them
     // plus the answered ones (xr-molecule-flash-m112's note listed only -1s and 200s).
     requests: chosen.slice(0, MAX_REQUESTS),
+    ...(missingText === null ? {} : { missingText: missingText }),
     console: keptConsole.slice(0, MAX_CONSOLE).map(function (text) { return text.slice(0, 300) }),
     actions: actions.slice(-MAX_ACTIONS),
     ...(unattributed ? { unattributed: true } : {}),
@@ -917,6 +970,24 @@ function parseTraceRequest(value) {
         ...(typeof r.pageId === 'string' && r.pageId ? { pageId: r.pageId } : {}),
     };
 }
+/**
+ * One `missingText` out of a `TRACE` line's json, or null when the value is not one.
+ *
+ * @param value - The line's `missingText`.
+ * @returns The awaited text and the response that carried it, or null.
+ */
+function parseMissingText(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const raw = value;
+    if (typeof raw.text !== 'string' || raw.text === '')
+        return null;
+    if (typeof raw.method !== 'string' || raw.method === '')
+        return null;
+    if (typeof raw.path !== 'string' || raw.path === '')
+        return null;
+    return { text: raw.text, method: raw.method, path: raw.path };
+}
 /**
  * One `lastAction` out of a `TRACE` line's json, or null when the value is not one.
  *
@@ -962,6 +1033,7 @@ export function parseTraceArtifacts(stdout) {
             const actions = Array.isArray(raw.actions) ? raw.actions : [];
             const lead = parseTraceRequest(raw.lead);
             const lastAction = parseLastAction(raw.lastAction);
+            const missingText = parseMissingText(raw.missingText);
             const otherContexts = Array.isArray(raw.otherContexts)
                 ? raw.otherContexts
                     .filter((c) => typeof c === 'object' && c !== null)
@@ -992,9 +1064,12 @@ export function parseTraceArtifacts(stdout) {
                     ...(typeof a.context === 'string' ? { context: a.context } : {}),
                     ...(typeof a.pageId === 'string' ? { pageId: a.pageId } : {}),
                     ...(typeof a.frameId === 'string' ? { frameId: a.frameId } : {}),
+                    ...(typeof a.selector === 'string' && a.selector ? { selector: a.selector } : {}),
+                    ...(typeof a.value === 'string' ? { value: a.value } : {}),
                 })),
                 ...(otherContexts.length === 0 ? {} : { otherContexts }),
                 ...(raw.unattributed === true ? { unattributed: true } : {}),
+                ...(missingText === null ? {} : { missingText }),
             });
         }
         catch (_error) {
@@ -1500,6 +1575,87 @@ function sameOriginPath(request) {
         return null;
     return raw.replace(/\/+$/, '');
 }
+/**
+ * The path segments a request ASKS FOR a credential through — a login, a registration, a token
+ * endpoint — as opposed to a protected resource that presents one.
+ */
+const CREDENTIAL_EXCHANGE_PATH = /(?:^|\/)(?:login|log-in|signin|sign-in|register|signup|sign-up|token)(?:\/|$)/i;
+/** The field a credential payload carries: a password, a grant, or a refresh token. */
+const CREDENTIAL_FIELD = /"(?:password|credentials|grant_type|refresh_token)"\s*:/i;
+/** The field that pairs with a password in a login/registration body. */
+const CREDENTIAL_IDENTITY = /"(?:email|username)"\s*:/i;
+/**
+ * Whether a request's recorded body is a credential payload — the shape a login, a registration
+ * or a token exchange sends, never a protected write (an article, a comment, a profile).
+ *
+ * @param sent - What the request sent, as the trace recorded it (bounded).
+ * @returns True for a body carrying credentials.
+ */
+function credentialExchangeBody(sent) {
+    if (!sent)
+        return false;
+    const text = sent.slice(0, MAX_TRACED_BODY_CHARS);
+    // A password alone is a profile write as often as a login; the exchange is a password beside
+    // an identity, or a token grant.
+    if (!CREDENTIAL_FIELD.test(text))
+        return false;
+    return (CREDENTIAL_IDENTITY.test(text) || /"(?:credentials|grant_type|refresh_token)"\s*:/i.test(text));
+}
+/**
+ * Whether a request PATH asks the app to mint a credential — a login, a registration, a token
+ * endpoint — as opposed to a protected resource that presents one.
+ *
+ * This is the path half of {@link isCredentialExchange}, exported so a caller holding only a
+ * `METHOD path` reads the same classification: a Hurl failing entry says
+ * `POST /api/users/login` and nothing about the body, and the whole-suite note must not explain
+ * a wrong-password login that answered 200 as a cookie-jar effect (xr-molecule-flash-m176).
+ *
+ * @param path - The request path (`/api/users/login`); a query or fragment is ignored.
+ * @param authEndpoints - The endpoints the app's auth config names (`/users/login`).
+ * @returns True when the path names a credential exchange.
+ */
+export function isCredentialExchangePath(path, authEndpoints = []) {
+    const clean = (path.split(/[?#]/)[0] ?? '').replace(/\/+$/, '');
+    if (clean === '')
+        return false;
+    // The app's own config names it: matched as a path suffix, because an auth config writes the
+    // endpoint relative to its API base (`/users/login`) while the trace records the mounted path
+    // (`/api/users/login`).
+    if (authEndpoints.some((endpoint) => {
+        const named = `/${String(endpoint).replace(/^\/+|\/+$/g, '')}`;
+        return named.length > 1 && (clean === named || clean.endsWith(named));
+    }))
+        return true;
+    return CREDENTIAL_EXCHANGE_PATH.test(clean);
+}
+/**
+ * Whether a refused request is a CREDENTIAL EXCHANGE: the app was asked to mint a token (a login,
+ * a registration, a token endpoint), so it never needed one attached.
+ *
+ * Three readings, weakest last: the app's own auth config names the endpoint (a project may mount
+ * `/session` or `/auth/signin`), the path's own last segments name it (`/users/login`), or the
+ * body is a credential payload (`{"user":{"email":…,"password":…}}` sends a registration).
+ *
+ * xr-molecule-flash-m165 (+10:22): `POST /api/users/login → 401
+ * {"errors":{"credentials":["invalid"]}}` was answered with the missing-token sentence — "the
+ * client did not attach the token … The API handler is not the problem" — for a request whose
+ * whole purpose is to obtain a token. The model read helpers and configs for 40 minutes instead of
+ * the real cause: the suite's setup had seeded `https://api.realworld.show`, not this app.
+ *
+ * @param request - The refused request (401/403).
+ * @param authEndpoints - The endpoints the app's auth config names (`/users/login`).
+ * @returns True when the request is a credential exchange.
+ */
+function isCredentialExchange(request, authEndpoints) {
+    if (request.method !== 'POST')
+        return false;
+    const path = sameOriginPath(request);
+    if (path === null)
+        return false;
+    if (isCredentialExchangePath(path, authEndpoints))
+        return true;
+    return credentialExchangeBody(request.sent);
+}
 /**
  * The sentence a 401/403 on the app's own API gets: which half of the wire refused the request.
  *
@@ -1521,6 +1677,15 @@ function sameOriginPath(request) {
  * sent through. When the trace carries that line, the no-header sentence names the ordering fix
  * instead of leaving the run to re-derive it.
  *
+ * xr-molecule-flash-m165 (+10:22): a `POST /api/users/login → 401
+ * {"errors":{"credentials":["invalid"]}}` is a CREDENTIAL EXCHANGE — the request is how a token is
+ * obtained, so an absent `Authorization` header is the request being what it is, not a client bug.
+ * The note said "the client did not attach the token … The API handler is not the problem" and the
+ * run went looking through the app instead of at the credentials or the setup's API origin. The
+ * exchange branch names the credentials, the account's origin, and the response body; the
+ * categorical handler sentence is gone from the no-header branch too, because a route that
+ * requires a token where the app allows anonymous access is the handler's own mistake.
+ *
  * The trace cannot name the file that made the call: a real HAR entry carries the request, response,
  * `_resourceType`, `_monotonicTime` and a frame ref, but no initiator stack. So the sentence names
  * the shared client and the auth bond instead of guessing a file.
@@ -1528,14 +1693,30 @@ function sameOriginPath(request) {
  * @param request - The refused request, a 401 or 403 on the app's own origin.
  * @param unbondedClient - Whether the traced page logged `no client is bonded`, which explains a
  *   request that carried no `Authorization` header.
+ * @param authEndpoints - The endpoints the app's auth config names, so a credential exchange is
+ *   recognised even under a path the segment list does not.
  * @returns The sentence the note appends.
  */
-function authRefusalSentence(request, unbondedClient = false) {
+function authRefusalSentence(request, unbondedClient = false, authEndpoints = []) {
     const label = requestLabel(request);
     // The header's scheme, when it parsed; presence alone is still the server's half of the wire.
     const carried = request.authorization !== undefined
         ? `with \`Authorization: ${request.authorization} …\``
         : 'with an `Authorization` header';
+    // A credential exchange asks the app to MINT a token: no token is expected to be attached, so a
+    // refusal here is about the credentials themselves — never the client's omission (m165).
+    if (isCredentialExchange(request, authEndpoints)) {
+        const got = request.got
+            ? ` got ${bodyLine(redactSecrets(request.got), TRACE_NOTE_GOT_CHARS)}`
+            : '';
+        return (`The browser sent \`${label}\`${got} and the API answered ${request.status} — this is a ` +
+            'credential exchange (a login/registration/token endpoint), so the client is not expected ' +
+            'to attach a token: the credentials were rejected. Check that the account the test logs in ' +
+            'with was created on THIS app — the same database and origin this run drives; a user seeded ' +
+            'somewhere else is unknown here — and read the response body’s `errors` (a login answers 401 ' +
+            '`{"errors":{"credentials":["invalid"]}}` for a wrong email/password or a user that does not ' +
+            'exist here).');
+    }
     // The console line names the mechanism the no-header branch otherwise has to guess at:
     // `getClient()` ran before `setupHttpDefault()` and the token was mirrored into the
     // client that later setup replaced (xr-molecule-flash-m156).
@@ -1573,21 +1754,23 @@ function authRefusalSentence(request, unbondedClient = false) {
             ? 'The request did carry a `Cookie` header, so if this app signs in with a session cookie ' +
                 'that is the credential the server did not accept. '
             : '') +
-        'The API handler is not the problem.' +
         unbonded);
 }
 /**
  * The note's credential-refusal advice, one sentence per distinct shape — at most two.
  *
- * The shapes are `(status, Authorization scheme, cookie present)`: m148's ten walks repeated one
- * shape (`401`, no header) on every failing test, and repeating its sentence per row would bury
- * the fact rather than state it.
+ * The shapes are `(status, Authorization scheme, cookie present, credential exchange)`: m148's ten
+ * walks repeated one shape (`401`, no header) on every failing test, and repeating its sentence per
+ * row would bury the fact rather than state it. A login and a protected request that both carry no
+ * header are DIFFERENT shapes — one is the credentials being checked, the other is a token that was
+ * never attached (m165).
  *
  * @param items - The traces the note is about.
+ * @param authEndpoints - The endpoints the app's auth config names.
  * @returns The sentences to append (each led by a space), or '' when no same-origin 401/403 was
  *   traced.
  */
-function authRefusalAdvice(items) {
+function authRefusalAdvice(items, authEndpoints = []) {
     const sentences = [];
     const seen = new Set();
     // A page that logged `no client is bonded` explains every request it sent without a
@@ -1604,11 +1787,12 @@ function authRefusalAdvice(items) {
             // ignores it and clears the session, and the page owes the navigation (m156).
             if (isLogoutRequest(request))
                 continue;
-            const key = `${request.status} ${request.sentAuthorization ? (request.authorization ?? 'header') : 'none'} ${request.sentCookie ? 'cookie' : ''}`;
+            const exchange = isCredentialExchange(request, authEndpoints);
+            const key = `${request.status} ${exchange ? 'exchange' : request.sentAuthorization ? (request.authorization ?? 'header') : 'none'} ${request.sentCookie ? 'cookie' : ''}`;
             if (seen.has(key))
                 continue;
             seen.add(key);
-            sentences.push(authRefusalSentence(request, unbondedClient));
+            sentences.push(authRefusalSentence(request, unbondedClient, authEndpoints));
             if (sentences.length === 2)
                 return ` ${sentences.join(' ')}`;
         }
@@ -1674,6 +1858,117 @@ function tracedApiPrefixes(items) {
     }
     return [...prefixes].sort();
 }
+/**
+ * Every API path prefix the traces support: the one the app's client config names and the ones the
+ * traces' own same-origin requests show ({@link tracedApiPrefixes}).
+ *
+ * @param items - The traces the note is about.
+ * @param apiPrefixes - Prefixes the app's client config names (`['/api']`), never a literal.
+ * @returns The one-segment prefixes, without duplicates.
+ */
+function knownApiPrefixes(items, apiPrefixes) {
+    const prefixes = new Set([...apiPrefixes, ...tracedApiPrefixes(items)]
+        .map((prefix) => `/${String(prefix).replace(/^\/+|\/+$/g, '')}`)
+        .filter((prefix) => prefix !== '/'));
+    return [...prefixes];
+}
+/** A URL written in full (`https://api.realworld.show/api/articles`). */
+const ABSOLUTE_URL = /^[a-z][a-z0-9+.-]*:\/\//i;
+/**
+ * The API requests a trace made to an origin other than the page's own — set-up traffic that ran
+ * against someone else's server.
+ *
+ * The trace reader relativises every request whose origin is the page's (`pathOf`), so a request
+ * recorded with an absolute URL went to ANOTHER origin by construction. It counts as set-up/API
+ * traffic when its path carries a prefix the app's own API is known to use ({@link
+ * knownApiPrefixes}) — a CDN font or a third-party script has no `/api` under it, and with no
+ * known prefix nothing is claimed.
+ *
+ * xr-molecule-flash-m165 (+10:22): the suite's helper defaulted `API_BASE` to
+ * `https://api.realworld.show/api` and its set-up seeded rows there, while the browser drove this
+ * app — whose own `/api` answers a login for none of those users. The trace's absolute-URL rows
+ * were the evidence, and the note said nothing about them.
+ *
+ * @param items - The traces the note is about.
+ * @param apiPrefixes - Prefixes the app's client config names (`['/api']`).
+ * @returns One entry per distinct (origin, prefix), in trace order.
+ */
+function foreignOriginApiRequests(items, apiPrefixes) {
+    const prefixes = knownApiPrefixes(items, apiPrefixes);
+    if (prefixes.length === 0)
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const item of items) {
+        for (const request of item.requests) {
+            const raw = String(request.path ?? '');
+            if (!ABSOLUTE_URL.test(raw))
+                continue;
+            let parsed;
+            try {
+                parsed = new URL(raw);
+            }
+            catch (_error) {
+                // Not a URL this can parse: it is not evidence of another origin.
+                continue;
+            }
+            const prefix = prefixes.find((one) => parsed.pathname === one || parsed.pathname.startsWith(`${one}/`));
+            if (prefix === undefined)
+                continue;
+            const key = `${parsed.origin}${prefix}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push({ origin: parsed.origin, prefix, request });
+        }
+    }
+    return out;
+}
+/**
+ * The origin a run's target names, when it names one: a URL (`http://localhost:4173`), or the
+ * deployed host the note prints (`loopcheck-….apps.mlcl.dev`). Null for the note's descriptive
+ * targets ("the deployed app", "the local app").
+ *
+ * @param target - Where the run went, as {@link failureTraceNote} names it.
+ * @returns The origin, or null.
+ */
+function appOriginOfTarget(target) {
+    const text = target.trim();
+    try {
+        if (ABSOLUTE_URL.test(text))
+            return new URL(text).origin;
+        if (/^[a-z0-9.-]+(?::\d+)?$/i.test(text))
+            return new URL(`https://${text}`).origin;
+    }
+    catch (_error) {
+        // A target that is not a URL names no origin.
+    }
+    return null;
+}
+/**
+ * The sentence naming the foreign origin a run's set-up traffic went to, and the setting that
+ * points it at this app instead.
+ *
+ * It leads the note because it is the cheapest possible wrong result: every row the suite creates
+ * lands in a database this app never reads, so the failure says nothing about the app's code.
+ * xr-molecule-flash-m165 spent the walk after its failed login reading helpers and configs for a
+ * missing token, when the command's `BASE_URL`/`API_BASE` disagreement was the cause.
+ *
+ * @param found - The foreign-origin request the trace holds.
+ * @param target - Where the run went, for the app's own origin when the note knows it.
+ * @returns The sentence, led by nothing and closed by a blank line.
+ */
+function foreignOriginSentence(found, target) {
+    const appOrigin = appOriginOfTarget(target);
+    const where = appOrigin ?? 'this app’s origin';
+    const apiBase = `${appOrigin ?? '<this app’s origin>'}${found.prefix}`;
+    return (`The suite’s setup ran against ${found.origin}, not this app ` +
+        `(\`${requestLabel(found.request)}\`) — its set-up/API traffic went to another origin while ` +
+        `this app serves its own API at \`${found.prefix}\` on ${where}. Set ` +
+        `\`API_BASE=${apiBase}\` on the run — the supplied suite reads it (verify the variable name ` +
+        `in the suite’s own helpers before writing it) — so the rows it creates are in the database ` +
+        `this app reads.\n\n`);
+}
 /**
  * The failed 404s whose path carries none of the known API prefixes.
  *
@@ -1687,12 +1982,9 @@ function tracedApiPrefixes(items) {
  * @returns One entry per distinct failed 404, in trace order.
  */
 function missingApiPrefixRequests(items, apiPrefixes) {
-    const prefixes = new Set([...apiPrefixes, ...tracedApiPrefixes(items)]
-        .map((prefix) => `/${String(prefix).replace(/^\/+|\/+$/g, '')}`)
-        .filter((prefix) => prefix !== '/'));
-    if (prefixes.size === 0)
+    const known = knownApiPrefixes(items, apiPrefixes);
+    if (known.length === 0)
         return [];
-    const known = [...prefixes];
     const out = [];
     const seen = new Set();
     for (const item of items) {
@@ -1726,6 +2018,147 @@ function missingApiPrefixSentence(request) {
         `without the \`${request.prefix}\` prefix — the HTTP client's base URL is not set: is ` +
         '`setupProviders()` (which runs the HTTP bond setup) called in `main.tsx`?');
 }
+/**
+ * The sentence for a failing assertion whose awaited text a same-page API response carried.
+ *
+ * It names the response and the fact the trace proves — the value reached the browser and the page
+ * did not render it — and stops there. Which cut drops it (a slice, a filter, a limit) is in the
+ * component that maps the response, and the note cannot see that component; naming the mapping
+ * step is the whole instruction (xr-molecule-flash-m169).
+ *
+ * @param missing - The awaited text and the response that carried it.
+ * @returns The sentence the note leads with.
+ */
+function missingTextSentence(missing) {
+    return (`The API returned "${missing.text}" (in ${missing.method} ${missing.path}), but the page did ` +
+        `not render it — the page drops it before rendering (a slice/filter/limit in the component ` +
+        `that renders that list); find where that response is mapped.`);
+}
+/**
+ * The `name` attribute a locator's selector reads (`textarea[name="bio"]` → `bio`), or null when
+ * the selector names no field.
+ *
+ * Matching the form field to the request body's key is the whole point: a body that carries
+ * `"bio": ""` says nothing unless the trace also says the test typed a bio.
+ *
+ * @param selector - The selector a `fill`/`type`/`selectOption` action carried.
+ * @returns The field name, or null.
+ */
+function fieldNameOf(selector) {
+    const quoted = /\[\s*name\s*=\s*(["'])((?:(?!\1).)*)\1\s*\]/.exec(selector);
+    if (quoted !== null)
+        return quoted[2] === '' ? null : quoted[2];
+    const bare = /\[\s*name\s*=\s*([^\s\]]+)\s*\]/.exec(selector);
+    return bare === null ? null : (bare[1] ?? null);
+}
+/**
+ * Whether a JSON request body carries `key` with an EMPTY value (`""` or null), looking inside the
+ * wrapper object an API nests its entity under (`user`, `data`, `props`).
+ *
+ * A body that does not parse, or carries the key with a real value, is not evidence: the note only
+ * claims the page sent a field empty when it did.
+ *
+ * @param sent - The body the page sent, as the trace recorded it.
+ * @param key - The field name from the filled input's `name` attribute.
+ * @returns True when the body carries that key empty.
+ */
+function bodyCarriesEmptyField(sent, key) {
+    let parsed;
+    try {
+        parsed = JSON.parse(sent);
+    }
+    catch (_error) {
+        // A truncated body (the trace read bounds what it keeps) names no field confidently.
+        return false;
+    }
+    const read = (value, level) => {
+        if (level > 4 || value === null || typeof value !== 'object')
+            return null;
+        if (Array.isArray(value)) {
+            for (const item of value) {
+                const found = read(item, level + 1);
+                if (found !== null)
+                    return found;
+            }
+            return null;
+        }
+        const record = value;
+        if (Object.prototype.hasOwnProperty.call(record, key)) {
+            return record[key] === '' || record[key] === null;
+        }
+        for (const nested of Object.values(record)) {
+            const found = read(nested, level + 1);
+            if (found !== null)
+                return found;
+        }
+        return null;
+    };
+    return read(parsed, 0) === true;
+}
+/**
+ * The field a test typed into that the same page submitted empty, when the trace recorded both.
+ *
+ * This is the Settings race of xr-molecule-flash-m173: `page.fill('textarea[name="bio"]', newBio)`
+ * then `button[type=submit]`, and the `PUT /api/user` carried `"bio": ""`. The form's seeding
+ * effect re-ran between the fill and the submit — on the deployed URL the background session
+ * verification lands later than it does locally, and it handed the form a new user object. The
+ * reading only pairs facts the trace holds: the filled value (its `selector`/`value`), the field
+ * name the selector names, and the next call to the app's API on that page whose body carries
+ * that key empty.
+ *
+ * @param item - One traced failure.
+ * @returns The evidence, or null when no filled field was submitted empty.
+ */
+function formResetOf(item) {
+    const requests = [...(item.lastAction?.requests ?? []), ...item.requests];
+    // A trace read before `actions` existed (or a hand-built one) carries none: no claim.
+    for (const action of item.actions ?? []) {
+        if (action.selector === undefined || action.value === undefined || action.value === '')
+            continue;
+        const field = fieldNameOf(action.selector);
+        if (field === null)
+            continue;
+        let next = null;
+        for (const request of requests) {
+            if (!/^(?:POST|PUT|PATCH)$/.test(request.method) || request.sent === undefined)
+                continue;
+            // The submit follows the typing; a request that started before it cannot have sent it.
+            if (typeof request.startedAt === 'number' && request.startedAt < action.start)
+                continue;
+            // Same page only: another context's set-up call is not this form's submit.
+            if (action.pageId !== undefined &&
+                request.pageId !== undefined &&
+                action.pageId !== request.pageId)
+                continue;
+            if (!bodyCarriesEmptyField(request.sent, field))
+                continue;
+            const earlier = next === null ||
+                (typeof request.startedAt === 'number' &&
+                    (typeof next.startedAt !== 'number' || request.startedAt < next.startedAt));
+            if (earlier)
+                next = request;
+        }
+        if (next !== null)
+            return { value: action.value, selector: action.selector, field, request: next };
+    }
+    return null;
+}
+/**
+ * The sentence for a submitted form field the test had just typed into, sent empty.
+ *
+ * It states the two recorded facts and the one inference they support — the form re-seeded after
+ * the typing — then the fix at the source: copy the loaded data into the form once, on its first
+ * load, instead of on every change of the data it was seeded from.
+ *
+ * @param reset - The filled field and the submit that carried it empty.
+ * @returns The sentence the note leads with.
+ */
+function formResetSentence(reset) {
+    return (`The test typed "${reset.value}" into ${reset.selector}, but ` +
+        `${requestLabel(reset.request)} sent "${reset.field}": "" — the form's state was reset after ` +
+        `typing (an effect re-seeding the form from data that changed identity ran again after the ` +
+        `test typed). Seed the form once, not every time that data changes.`);
+}
 /**
  * The note a failed suite run's result carries: what each failing test's page actually sent, and
  * what came back.
@@ -1765,6 +2198,14 @@ function missingApiPrefixSentence(request) {
  * context and the assertion's page cannot be identified, the note lists the requests and makes NO
  * causal claim — no "the test's last action", no "the page stayed at …" — instead of merging them.
  *
+ * A field the test filled and the page submitted EMPTY ({@link formResetOf}) leads the note: the
+ * trace holds both facts — the value typed into `textarea[name="bio"]` and the `PUT /api/user`
+ * whose body carried `"bio": ""` — so the form's state was reset between the typing and the
+ * submit. The note names the effect that re-seeds a form from data whose identity changed and the
+ * fix at the source (seed the form once). xr-molecule-flash-m173 lost a deploy-and-walk cycle to
+ * this on the deployed URL only, where the background session verification lands later than it
+ * does locally.
+ *
  * WHICH rows it spends is evidence, not artifact order (xr-molecule-flash-m112 +53:46): a row
  * needs a recorded response, a real failure or a console line ({@link traceRowEvidence}), rows are
  * deduplicated by the test's location, and they are ordered real failure → repeated from an
@@ -1803,6 +2244,13 @@ function missingApiPrefixSentence(request) {
  * xr-molecule-flash-m148 (+29:18) hit this exactly: six local walks read
  * `POST …/favorite → 401 {"errors":{"token":["is missing"]}}` as a handler bug.
  *
+ * A credential EXCHANGE (a login/registration/token endpoint, read from the app's auth config, the
+ * path or the body) is never that shape: the request's purpose is to obtain a token, so an absent
+ * header is not a client omission ({@link isCredentialExchange}). xr-molecule-flash-m165's login
+ * 401 was answered as one for 40 minutes; the trace also showed the suite's SET-UP traffic going
+ * to `https://api.realworld.show/api` instead of this app, which is what the note leads with
+ * ({@link foreignOriginApiRequests}).
+ *
  * @param items - The traces {@link parseTraceArtifacts} read.
  * @param target - Where the run went — the deployed host, as the note names it.
  * @param earlierFailures - The failing `file:line`s earlier walks of this suite left, so a repeat
@@ -1870,7 +2318,12 @@ export function failureTraceNote(items, target, earlierFailures = [], apiPrefixe
     // Every recorded failure is the logout endpoint answering 4xx: the row's own sentence explains
     // it, and neither the handler lead nor the credential reading applies (m156 +24:02).
     const onlyLogoutFailures = failedRequests.length > 0 && failedRequests.every((request) => isLogoutRequest(request));
-    const authAdvice = authRefusalAdvice(traced);
+    const authAdvice = authRefusalAdvice(traced, report.authEndpoints ?? []);
+    // Set-up traffic the trace shows going to an origin other than the app's (m165): the rows it
+    // creates are not in this app's database, so the note says it before any app-side reading.
+    const foreignOrigins = foreignOriginApiRequests(traced, apiPrefixes);
+    const [firstForeign] = foreignOrigins;
+    const setupOriginLead = firstForeign === undefined ? '' : foreignOriginSentence(firstForeign, target);
     // The stalled-navigation reading, per traced test: non-null only when the RUNNER says this
     // test's failing operation is a navigation and a document subresource still pending at the end
     // started inside that wait ({@link stalledNavigation}).
@@ -2098,7 +2551,36 @@ export function failureTraceNote(items, target, earlierFailures = [], apiPrefixe
             `does not define is always undefined, and a missing effect dependency on the route means ` +
             `the fetch never re-runs — before touching the markup or the CSS.\n\n`
         : '';
-    return (transportLead +
+    // An assertion whose awaited text a same-page API response carried: the fact the run needs
+    // first, before any row, is that the value arrived and the page dropped it (m169's missing
+    // "trending" came back from GET /api/tags while the sidebar rendered a cut list). Each distinct
+    // response is named once; the note makes no claim about which cut did it.
+    const missingTexts = [
+        ...new Map(traced
+            .filter((item) => item.missingText !== undefined)
+            .map((item) => {
+            const missing = item.missingText;
+            return [`${missing.method} ${missing.path}\u0000${missing.text}`, missing];
+        })).values(),
+    ];
+    const missingTextLead = missingTexts.length === 0
+        ? ''
+        : `${missingTexts.slice(0, 2).map(missingTextSentence).join(' ')}\n\n`;
+    // A field the test typed and the page submitted empty: the form re-seeded itself after the
+    // typing (m173's Settings race — the deployed URL lands the background session verification
+    // later than a local run, and its new user object re-ran the form's seeding effect between the
+    // fill and the submit). It is a direct cause of the failing request, so it leads the note.
+    const formResets = [
+        ...new Map(traced
+            .map(formResetOf)
+            .filter((reset) => reset !== null)
+            .map((reset) => [`${reset.request.method} ${reset.request.path}\u0000${reset.field}`, reset])).values(),
+    ];
+    const formResetLead = formResets.length === 0 ? '' : `${formResets.slice(0, 2).map(formResetSentence).join(' ')}\n\n`;
+    return (formResetLead +
+        missingTextLead +
+        transportLead +
+        setupOriginLead +
         stalledLead +
         staleRouteLead +
         `The platform read the failing tests' own Playwright traces from the run against ${target} ` +
@@ -2289,24 +2771,27 @@ async function readRunConfig(command, cwd, readFile) {
     return '';
 }
 /**
- * The command a DIAGNOSIS run needs to leave a readable trace behind, when the suite's config
+ * The command a Playwright run needs to leave a readable trace behind, when the suite's config
  * would record none.
  *
  * The failing tests' requests are only readable if the run wrote them down (see the module doc),
  * and the config is where the decision about that lives — the platform does not edit the suite's
- * config, so it passes the flag instead, and only where it can do no harm: on a run narrowed to a
- * part of the suite or capped ({@link isDiagnosisRun}), never on the whole-suite proof run, and
- * never over a `--trace` the executor wrote itself. A capped walk is exactly the run whose
- * failures someone is about to work on; the proof run is graded as it is.
+ * config, so it passes the flag instead, on every Playwright run that starts tests and does not
+ * already decide its own `--trace`. That includes the whole-suite proof run, which an earlier
+ * version of this function skipped on the reasoning that its flags are graded: the flag changes
+ * what is RETAINED, not what passes. `retain-on-failure` keeps the trace only of a test that
+ * fails — Playwright records it and deletes it when the test passes (playwright's
+ * `_shouldAbandonTrace` unlinks the temporary trace files of a passing test) — so a green proof
+ * run keeps nothing extra. A failing one keeps the network log its failures need.
+ * xr-molecule-flash-m163 (+24:58) is why the proof run is no longer skipped: its one deployed
+ * failure left only an `error-context.md`, the executor spent the next calls hunting a `trace.zip`
+ * that could not exist, and then shipped a guessed fix.
  *
  * @param args - The command, the directory it starts in, and the backend's file read.
  * @returns The command to run and the sentence to report, or the command unchanged.
  */
 export async function diagnosisTraceCommand(args) {
     const unchanged = { command: args.command, change: null };
-    // The proof run is the one run this must never touch: its flags are graded.
-    if (!isDiagnosisRun(args.command))
-        return unchanged;
     if (namesTraceMode(args.command))
         return unchanged;
     // Only a Playwright run leaves a trace to read.
@@ -2330,7 +2815,8 @@ export async function diagnosisTraceCommand(args) {
     return {
         command: `${args.command.slice(0, at)} ${DIAGNOSIS_TRACE_FLAG}${args.command.slice(at)}`,
         change: `Added \`${DIAGNOSIS_TRACE_FLAG}\`: the suite's config records no trace for a failure` +
-            `${/trace:/.test(config) ? '' : ' (it sets none)'}, and this diagnosis run's failures are ` +
-            'what the platform reads the network log from. The proof run keeps the suite’s own settings.',
+            `${/trace:/.test(config) ? '' : ' (it sets none)'}, and a failing test's own network log is ` +
+            'what the platform reads the cause from. It keeps a trace only for a test that fails, so a ' +
+            'green run retains nothing.',
     };
 }