evals-lab 0.6.0 → 0.8.0

package/lab/flows/flowApi.mjs

@@ -0,0 +1,153 @@
+// The Power Automate management API, read from the browser
+// (docs/power-automate.md § What the spike verified). This is the one place
+// a Microsoft token is attached to a request, and it is attached to the Flow
+// API's own address and nothing else: the lab's API client never carries
+// one, so the server never sees one.
+
+export const FLOW_API = "https://api.flow.microsoft.com/providers/Microsoft.ProcessSimple";
+const VERSION = "api-version=2016-11-01";
+
+                                                                                 
+                                                                        
+                                                                                             
+                                                                                                          
+                                                              
+/** One action's entry in a run, or one iteration of it: where its content is. */
+                                
+                 
+                           
+                          
+                            
+                             
+                                                                              
+                             
+ 
+                                                                                                                      
+
+// Run history's content sits behind pre-signed links on this domain, read
+// with no token (docs/power-automate.md § What the spike verified).
+const CONTENT_HOST = /\.powerplatformusercontent\.com$/;
+/** How many content reads are in flight at once, and how often one is tried. */
+const CONTENT_AT_ONCE = 4;
+const CONTENT_TRIES = 4;
+
+                                                                   
+
+export function flowApi(token                       , fetchImpl        = (u, i) => fetch(u, i)) {
+  const get = async     (path        )             => {
+    const url = `${FLOW_API}${path}${path.includes("?") ? "&" : "?"}${VERSION}`;
+    if (!url.startsWith(`${FLOW_API}/`)) throw new Error("the Flow API is the only address a Microsoft token goes to");
+    const r = await fetchImpl(url, { headers: { Authorization: `Bearer ${await token()}` } });
+    const text = await r.text();
+    let body          = null;
+    try { body = JSON.parse(text); } catch { /* said below */ }
+    if (!r.ok) {
+      const code = (body                                        )?.error?.code;
+      throw new Error(`Power Automate answered ${r.status}${code ? ` (${code})` : ""}`);
+    }
+    return body     ;
+  };
+  const seg = encodeURIComponent;
+                                                                                     
+                                                                                   
+                                                                                   
+                                                                                        
+  const actionOf = (a                       )                => ({
+    status: a?.status ?? "",
+    startTime: a?.startTime ?? null,
+    error: a?.error ?? null,
+    inputsLink: a?.inputsLink?.uri ?? null,
+    outputsLink: a?.outputsLink?.uri ?? null,
+    at: Object.fromEntries((a?.repetitionIndexes ?? [])
+      .filter((r) => r.scopeName && typeof r.itemIndex === "number").map((r) => [r.scopeName , r.itemIndex ])),
+  });
+  // A next page's link, as a path `get` adds the version to again.
+  const pathOf = (link        ) => {
+    const u = new URL(link);
+    u.searchParams.delete("api-version");
+    return `${u.pathname.slice(new URL(FLOW_API).pathname.length)}${u.search}`;
+  };
+  const runs = (env        , flow        ) => `/environments/${seg(env)}/flows/${seg(flow)}/runs`;
+
+  // Content reads share one queue, a few at a time, and a 429 waits as long
+  // as it is told to (or a little longer each try) before trying again.
+  let active = 0;
+  const waiting                 = [];
+  // A freed slot is handed to the next waiter rather than given back, so a
+  // read arriving between the two cannot take it as well.
+  const slot = async () => {
+    if (active < CONTENT_AT_ONCE) { active++; return; }
+    await new Promise      ((go) => waiting.push(go));
+  };
+  const free = () => {
+    const next = waiting.shift();
+    if (next) next(); else active--;
+  };
+  const content = async (link        )                   => {
+    const u = new URL(link);
+    if (u.protocol !== "https:" || !CONTENT_HOST.test(u.hostname)) throw new Error("that is not run history's content");
+    await slot();
+    try {
+      for (let tried = 1; ; tried++) {
+        const r = await fetchImpl(link, {});
+        if (r.status === 429 && tried < CONTENT_TRIES) {
+          const after = Number(r.headers.get("Retry-After"));
+          await new Promise((go) => setTimeout(go, (after > 0 ? after : tried) * 1000));
+          continue;
+        }
+        if (!r.ok) throw new Error(`run history answered ${r.status}`);
+        const text = await r.text();
+        try { return JSON.parse(text); } catch { return text; }
+      }
+    } finally { free(); }
+  };
+
+  return {
+    environments: async ()                             =>
+      ((await get                                                       ("/environments")).value ?? [])
+        .map((e) => ({ id: e.name, name: e.properties?.displayName || e.name, isDefault: !!e.properties?.isDefault })),
+    flows: async (env        )                         =>
+      ((await get                                                  (`/environments/${seg(env)}/flows`)).value ?? [])
+        .map((f) => ({ id: f.name, name: f.properties?.displayName || f.name, state: f.properties?.state ?? "" })),
+    flow: async (env        , id        )                      => {
+      const f = await get                                                                                               (
+        `/environments/${seg(env)}/flows/${seg(id)}`);
+      return { id: f.name, name: f.properties?.displayName || f.name, definition: f.properties?.definition ?? {} };
+    },
+    /** A flow's runs, newest first, as far back as [limit] (the API pages them). */
+    runs: async (env        , flow        , limit = 250)                     => {
+                                                                                 
+      const out            = [];
+      let path                = runs(env, flow);
+      while (path && out.length < limit) {
+        const page            = await get           (path);
+        for (const r of page.value ?? []) {
+          out.push({ id: r.name, status: r.properties?.status ?? "", startTime: r.properties?.startTime ?? null,
+                     error: r.properties?.error ?? null });
+        }
+        // The next page is the Flow API's own address, or it is not followed.
+        path = page.nextLink?.startsWith(`${FLOW_API}/`) ? pathOf(page.nextLink) : null;
+      }
+      return out.slice(0, limit);
+    },
+    /** A run, its trigger and each action's entry. */
+    run: async (env        , flow        , id        )                         => {
+                                                                                                    
+                                                       
+      const r = await get                                  (`${runs(env, flow)}/${seg(id)}?$expand=properties/actions`);
+      const p = r.properties ?? {};
+      return {
+        run: { id: r.name, status: p.status ?? "", startTime: p.startTime ?? null, error: p.error ?? null },
+        trigger: p.trigger ? actionOf(p.trigger) : null,
+        actions: Object.fromEntries(Object.entries(p.actions ?? {}).map(([n, a]) => [n, actionOf(a)])),
+      };
+    },
+    /** Every iteration of an action inside a loop, each with its own content. */
+    repetitions: async (env        , flow        , run        , action        )                           =>
+      ((await get                   (`${runs(env, flow)}/${seg(run)}/actions/${seg(action)}/repetitions`)).value ?? [])
+        .map((r) => actionOf(r.properties)),
+    /** What a content link holds: JSON parsed, anything else as text. */
+    content,
+  };
+}
+                                                 

package/lab/flows/record.mjs

@@ -0,0 +1,495 @@
+// A Power Automate workflow's records (docs/power-automate.md): one per call
+// of a Power Automate step -- one per loop iteration -- holding what the
+// step's request template read, the request production sent, and what came
+// back. Read from run history, written by hand, or made from an uploaded
+// file; the page builds them, and the server checks them again on the way in
+// (server.py `record_problems`, this format's Python twin).
+
+import { evaluate,               } from "./wdl.mjs";
+
+export const RECORD_FORMAT = "evals-lab/record";
+export const RECORD_VERSION = 1;
+
+/** What a step's template read, by where the expression reads it from. */
+                              
+                                                                   
+                                                                  
+                                                                 
+                                                                    
+                        
+                                      
+                                                         
+                                  
+ 
+
+/** Production's result: the reply, or the step's failure. */
+                          
+                                     
+                                                   
+
+                             
+                               
+                                 
+                                                                    
+               
+                                                                     
+                    
+                     
+                                                                         
+                                                      
+                                                                 
+                              
+                                                                                
+ 
+
+const isObj = (v         )                               => v != null && typeof v === "object" && !Array.isArray(v);
+
+/** Every reason [value] is not a record this lab keeps, as sentences. */
+export function recordProblems(value         )           {
+  if (!isObj(value)) return ["a record is a JSON object"];
+  const bad           = [];
+  if (value.format !== RECORD_FORMAT) bad.push(`a record says "format": "${RECORD_FORMAT}"`);
+  if (value.version !== RECORD_VERSION) bad.push(`this lab reads record version ${RECORD_VERSION}`);
+  if (typeof value.step !== "string" || !value.step) bad.push("a record names the step it is a call of");
+  if (value.at != null && typeof value.at !== "string") bad.push("a record's at is a time or null");
+  if (!isObj(value.scope)) bad.push("a record's scope is an object");
+  else {
+    for (const part of ["actions", "variables", "items"]         ) {
+      if (value.scope[part] != null && !isObj(value.scope[part])) bad.push(`a record's scope.${part} is an object`);
+    }
+  }
+  const req = value.request;
+  if (req != null && !(isObj(req) && typeof req.method === "string" && typeof req.uri === "string")) {
+    bad.push("a record's request is { method, uri, body } or null");
+  }
+  if (isObj(req) && "headers" in req) bad.push("a record keeps no request headers");
+  const res = value.result;
+  if (res != null && !(isObj(res) && (("status" in res && typeof res.status === "number") || isObj(res.error)))) {
+    bad.push("a record's result is { status, body }, { error } or null");
+  }
+  const origin = value.origin;
+  if (!isObj(origin) || !["run", "hand", "upload"].includes(origin.kind          )) {
+    bad.push("a record's origin is run, hand or upload");
+  }
+  return bad;
+}
+
+// ---- what a template reads -------------------------------------------------
+
+/** One thing a step's template reads, and where a record keeps it. */
+                  
+                       
+                                    
+                                      
+                                  
+                                        
+
+// A function call that reads flow data, in an expression anywhere in a
+// template: the name, and its one quoted argument if it has one (`''` is a
+// quote inside Workflow Definition Language's strings).
+const READER = /\b(triggerBody|triggerOutputs|body|outputs|actions|variables|items|item|parameters)\(\s*(?:'((?:[^']|'')*)')?\s*\)/g;
+
+/** Every expression in [template]: the whole of a string that begins `@`
+    (but not `@@`, a literal @), and each `@{…}` inside one. */
+function expressions(template         , out           = [])           {
+  if (typeof template === "string") {
+    if (template.startsWith("@") && !template.startsWith("@@") && !template.startsWith("@{")) out.push(template.slice(1));
+    for (const m of template.matchAll(/@\{([^}]*)\}/g)) out.push(m[1] );
+  } else if (Array.isArray(template)) {
+    for (const v of template) expressions(v, out);
+  } else if (isObj(template)) {
+    for (const v of Object.values(template)) expressions(v, out);
+  }
+  return out;
+}
+
+/** What [template] reads, once each. [loop] is the loop it sits in, which
+    item() means. */
+export function readsOf(template         , loop                = null)         {
+  const seen = new Map              ();
+  for (const expr of expressions(template)) {
+    for (const m of expr.matchAll(READER)) {
+      const fn = m[1] , arg = (m[2] ?? "").replace(/''/g, "'");
+      const read              =
+        fn === "triggerBody" || fn === "triggerOutputs" ? { from: "trigger" }
+        : fn === "body" || fn === "outputs" || fn === "actions" ? (arg ? { from: "action", name: arg } : null)
+        : fn === "variables" ? (arg ? { from: "variable", name: arg } : null)
+        : fn === "items" ? (arg ? { from: "item", name: arg } : null)
+        : fn === "item" ? (loop ? { from: "item", name: loop } : null)
+        : arg ? { from: "parameter", name: arg } : null;
+      if (read) seen.set(JSON.stringify(read), read);
+    }
+  }
+  return [...seen.values()];
+}
+
+/** A record with an empty place for everything [reads] names: what a record
+    written by hand starts from. */
+export function skeletonFor(step        , reads                 )             {
+  const scope              = {};
+  for (const r of reads) {
+    if (r.from === "trigger") scope.trigger = { body: null };
+    else if (r.from === "action") (scope.actions ??= {})[r.name] = { body: null };
+    else if (r.from === "variable") (scope.variables ??= {})[r.name] = null;
+    else if (r.from === "item") (scope.items ??= {})[r.name] = null;
+  }
+  return { format: RECORD_FORMAT, version: RECORD_VERSION, step, at: null, scope, request: null, result: null,
+           origin: { kind: "hand" } };
+}
+
+/** What makes two records the same call. One from run history is its run's
+    call of the step at that iteration: imported twice, it is skipped the
+    second time, while another run's call -- the same request, sent again,
+    answered afresh -- is its own record, since a flow that sends the same
+    words every time is exactly where production's replies differ. One
+    written by hand or uploaded is the same as another that read and sent the
+    same things. */
+export function recordKey(r                                                           )         {
+  if (r.origin?.kind === "run" && r.origin.run) {
+    return JSON.stringify({ step: r.step, run: r.origin.run, iteration: r.origin.iteration ?? "" });
+  }
+  const sorted = (v         )          => Array.isArray(v) ? v.map(sorted)
+    : isObj(v) ? Object.fromEntries(Object.keys(v).sort().map(k => [k, sorted(v[k])])) : v;
+  return JSON.stringify(sorted({ step: r.step, scope: r.scope, request: r.request }));
+}
+
+// ---- a flow's Power Automate steps -------------------------------------------
+
+/** A kind of action the lab can re-run as a Power Automate step: how its
+    request template is read off the definition. A registry, so a connector's
+    action is one more entry and no reader changes. */
+                               
+                
+                                                                           
+                          
+                                                                     
+ 
+
+export const FLOW_STEP_KINDS                               = Object.create(null);
+
+// The built-in HTTP action: any endpoint (docs/power-automate.md).
+FLOW_STEP_KINDS.Http = {
+  label: "HTTP",
+  template: ({ headers: _h, authentication: _a, ...rest }) => rest,
+};
+
+/** What a kind of flow action is to the lab as it walks a definition: a
+    loop (its inner actions run once per item, so a call inside one is a call
+    per iteration), or what declares a variable. A registry, so another
+    kind is one more entry and no walk changes. */
+                                 
+                  
+                                                             
+                                                       
+ 
+
+export const FLOW_ACTIONS                                 = Object.create(null);
+// Apply to each, and Do until: an inner action runs once per iteration.
+FLOW_ACTIONS.Foreach = { loops: true };
+FLOW_ACTIONS.Until = { loops: true };
+// Initialize variable: `variables: [{ name, type, value }]`.
+FLOW_ACTIONS.InitializeVariable = {
+  declares: (inputs) => (Array.isArray(inputs.variables) ? inputs.variables : [])
+    .flatMap((v         ) => (isObj(v) && typeof v.name === "string" ? [v.name] : [])),
+};
+
+/** Whether an action of type [type] is a loop. */
+const isLoop = (type                    ) => !!(type && FLOW_ACTIONS[type]?.loops);
+
+/** A step of a flow the lab can re-run, as the definition has it. */
+                           
+               
+               
+                                                                
+                  
+                                    
+                
+ 
+
+                                                                                                     
+                                                                                                                          
+                                                                 
+
+/** Every Power Automate step in [definition], however deep in scopes,
+    branches and loops. */
+export function stepsOf(definition         )             {
+  const out             = [];
+  const walk = (actions                                    , loops          ) => {
+    for (const [name, a] of Object.entries(actions ?? {})) {
+      const kind = a.type ? FLOW_STEP_KINDS[a.type] : undefined;
+      if (kind && isObj(a.inputs)) {
+        const template = kind.template(a.inputs);
+        out.push({ name, kind: a.type , loops, template, reads: readsOf(template, loops.at(-1) ?? null) });
+      }
+      const inner = isLoop(a.type) ? [...loops, name] : loops;
+      walk(a.actions, inner);
+      walk(a.else?.actions, inner);
+      for (const branch of Object.values(a.cases ?? {})) walk(branch.actions, inner);
+      walk(a.default?.actions, inner);
+    }
+  };
+  walk(isObj(definition) ? (definition.actions                          ) : undefined, []);
+  return out;
+}
+
+/** Every action in [definition] by name, however deep: where a record's
+    import finds what declares a variable or a loop's items. */
+export function actionsByName(definition         )                                               {
+  const out                                               = {};
+  const walk = (actions                                    , loops          ) => {
+    for (const [name, a] of Object.entries(actions ?? {})) {
+      out[name] = { ...a, loops };
+      const inner = isLoop(a.type) ? [...loops, name] : loops;
+      walk(a.actions, inner);
+      walk(a.else?.actions, inner);
+      for (const branch of Object.values(a.cases ?? {})) walk(branch.actions, inner);
+      walk(a.default?.actions, inner);
+    }
+  };
+  walk(isObj(definition) ? (definition.actions                          ) : undefined, []);
+  return out;
+}
+
+// ---- a record from run history -------------------------------------------------
+
+/** Where one call of a step sits in a run: each enclosing loop's item index. */
+                                               
+
+/** What an import reads a run's history through. The page answers it from
+    the Flow API (web/src/flows/history.ts); a check answers it from fixtures.
+    Each returns the content as run history stores it, or null for none. */
+                             
+                                                  
+                                     
+                                                                       
+                                                                         
+                                                              
+                                                               
+ 
+
+/** One call of [step], as run history holds it: its inputs and outputs, or
+    its failure, and when it ran. */
+                           
+              
+                
+                           
+                  
+                   
+                                                    
+ 
+
+/** The record of [call]: everything [step]'s template read, fetched through
+    [history], and production's request and result. Nothing is redacted here --
+    the caller redacts the record before it leaves the browser. */
+export async function recordFromCall(step          , call          , history            ,
+                                     definition         )                      {
+  const actions = actionsByName(definition);
+  const scope              = {};
+  for (const read of step.reads) {
+    if (read.from === "trigger") {
+      const out = await history.triggerOutputs();
+      scope.trigger = { body: isObj(out) ? out.body : out };
+    } else if (read.from === "action") {
+      const out = await history.actionOutputs(read.name, call.at);
+      (scope.actions ??= {})[read.name] = isObj(out)
+        ? { body: out.body, ...(typeof out.statusCode === "number" ? { statusCode: out.statusCode } : {}) }
+        : { body: out };
+    } else if (read.from === "variable") {
+      // A variable is what the action that declares it set it to. A later
+      // Set or Append is not replayed: the record holds the declared value
+      // (docs/power-automate.md § Records).
+      const declares = (a        ) => {
+        const kind = a.type ? FLOW_ACTIONS[a.type] : undefined;
+        return !!kind?.declares && isObj(a.inputs) && kind.declares(a.inputs).includes(read.name);
+      };
+      const decl = Object.entries(actions).find(([, a]) => declares(a));
+      const inputs = decl ? await history.actionInputs(decl[0], call.at) : null;
+      const vars = isObj(inputs) && Array.isArray(inputs.variables) ? inputs.variables : [];
+      const hit = vars.find((v         ) => isObj(v) && v.name === read.name)                                       ;
+      (scope.variables ??= {})[read.name] = hit ? hit.value : null;
+    } else if (read.from === "item") {
+      // A loop's current item: its foreachItems at this call's index.
+      const inputs = await history.actionInputs(read.name, call.at);
+      const items = isObj(inputs) && Array.isArray(inputs.foreachItems) ? inputs.foreachItems : [];
+      (scope.items ??= {})[read.name] = items[call.at[read.name] ?? 0] ?? null;
+    }
+  }
+  const req = isObj(call.inputs) ? call.inputs : null;
+  const out = isObj(call.outputs) ? call.outputs : null;
+  return {
+    format: RECORD_FORMAT, version: RECORD_VERSION, step: step.name, at: call.startTime, scope,
+    request: req ? { method: String(req.method ?? ""), uri: String(req.uri ?? ""), body: req.body ?? null } : null,
+    result: call.error && !out ? { error: call.error }
+      : out ? { status: typeof out.statusCode === "number" ? out.statusCode : 0, body: out.body ?? null } : null,
+    origin: { kind: "run", run: call.run,
+              ...(Object.keys(call.at).length ? { iteration: Object.entries(call.at).map(([k, v]) => `${k}[${v}]`).join(",") } : {}) },
+  };
+}
+
+/** A record's file name: the step, then the run and iteration it came from. */
+export function recordName(r            )         {
+  const tail = r.origin.kind === "run"
+    ? `${(r.origin.run ?? "").slice(-8)}${r.origin.iteration ? `-${r.origin.iteration.replace(/.*\[(\d+)\]$/, "$1")}` : ""}`
+    : new Date().toISOString().replace(/\D/g, "").slice(0, 14);
+  return `${r.step}-${tail}.json`.replace(/[^A-Za-z0-9._-]/g, "_");
+}
+
+// ---- records from an uploaded file ---------------------------------------------
+
+/** The column a record's scope takes [read] from, when a file's rows are
+    made into records: the action's, variable's or loop's own name, or
+    `trigger` for the trigger's body (`trigger.x` for one field of it). */
+export const columnOf = (read      )         => read.from === "trigger" ? "trigger"
+  : read.from === "parameter" ? "" : read.name;
+
+/** A cell's value: JSON when it reads as JSON, its text otherwise. */
+const cellValue = (v         )          => {
+  if (typeof v !== "string") return v;
+  try { return JSON.parse(v); } catch { return v; }
+};
+
+/** A record per row of [rows] for [step], each column matched by name to
+    what the step reads. The columns nothing reads are named, so the page can
+    say so before anything is kept. */
+export function recordsFromRows(step          , rows                                    ) 
+                                                   {
+  const columns = [...new Set(rows.flatMap(r => Object.keys(r)))];
+  const wanted = new Set(step.reads.map(columnOf).filter(Boolean));
+  const unmatched = columns.filter(c => !wanted.has(c) && !(wanted.has("trigger") && c.startsWith("trigger.")));
+  const records = rows.map(row => {
+    const r = skeletonFor(step.name, step.reads);
+    r.origin = { kind: "upload" };
+    for (const read of step.reads) {
+      const col = columnOf(read);
+      if (read.from === "trigger") {
+        const fields = Object.keys(row).filter(c => c.startsWith("trigger."));
+        const body = col in row ? cellValue(row[col])
+          : fields.length ? Object.fromEntries(fields.map(c => [c.slice("trigger.".length), cellValue(row[c])])) : null;
+        r.scope.trigger = { body };
+      } else if (col in row) {
+        const v = cellValue(row[col]);
+        if (read.from === "action") r.scope.actions [read.name] = { body: v };
+        else if (read.from === "variable") r.scope.variables [read.name] = v;
+        else if (read.from === "item") r.scope.items [read.name] = v;
+      }
+    }
+    return r;
+  });
+  return { records, unmatched };
+}
+
+/** A CSV file's rows, by its header line (RFC 4180: quoted fields, `""`
+    inside them, a line break inside quotes). */
+export function csvRows(text        )                           {
+  const lines             = [];
+  let row           = [], cell = "", quoted = false;
+  const src = text.replace(/^/, "");
+  for (let i = 0; i < src.length; i++) {
+    const c = src[i] ;
+    if (quoted) {
+      if (c === '"' && src[i + 1] === '"') { cell += '"'; i++; }
+      else if (c === '"') quoted = false;
+      else cell += c;
+    } else if (c === '"') quoted = true;
+    else if (c === ",") { row.push(cell); cell = ""; }
+    else if (c === "\n" || c === "\r") {
+      if (c === "\r" && src[i + 1] === "\n") i++;
+      row.push(cell); lines.push(row); row = []; cell = "";
+    } else cell += c;
+  }
+  if (cell || row.length) { row.push(cell); lines.push(row); }
+  const [head, ...body] = lines.filter(l => l.some(v => v !== ""));
+  if (!head) return [];
+  return body.map(l => Object.fromEntries(head.map((h, i) => [h.trim(), l[i] ?? ""])));
+}
+
+// ---- fidelity: the template against production -----------------------------------
+
+/** Whether [step]'s own template, evaluated against [record]'s scope, is the
+    request production sent: the proof the lab rebuilds a flow's request as
+    Power Automate does, before any wording is changed. `where` names the
+    first place they part, or why the template could not be evaluated. */
+                                                                                           
+
+export function fidelityOf(step          , record            , definition         )           {
+  if (!record.request) return { match: null };
+  const params = isObj(definition) && isObj(definition.parameters)
+    ? Object.fromEntries(Object.entries(definition.parameters).map(([k, v]) => [k, isObj(v) ? v.defaultValue : undefined]))
+    : {};
+  let rebuilt                                                  ;
+  try {
+    const ctx = { scope: record.scope            , loop: step.loops.at(-1) ?? null, now: record.at, parameters: params };
+    const t = step.template;
+    rebuilt = { method: evaluate(t.method, ctx), uri: evaluate(t.uri, ctx), body: evaluate(t.body ?? null, ctx) };
+  } catch (e) {
+    return { match: false, where: e instanceof Error ? e.message : String(e) };
+  }
+  const where = firstDifference(rebuilt, record.request, "request");
+  return where ? { match: false, where } : { match: true };
+}
+
+/** The first path at which [a] and [b] differ, or null: keys compared in
+    order, since a body is sent as written. */
+function firstDifference(a         , b         , at        )                {
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return `${at} has ${a.length} entries, production ${b.length}`;
+    for (let i = 0; i < a.length; i++) { const d = firstDifference(a[i], b[i], `${at}[${i}]`); if (d) return d; }
+    return null;
+  }
+  if (isObj(a) && isObj(b)) {
+    const ka = Object.keys(a), kb = Object.keys(b);
+    if (ka.join() !== kb.join()) return `${at} has keys ${ka.join(", ")}, production ${kb.join(", ")}`;
+    for (const k of ka) { const d = firstDifference(a[k], b[k], `${at}.${k}`); if (d) return d; }
+    return null;
+  }
+  return JSON.stringify(a) === JSON.stringify(b) ? null : `${at}`;
+}
+
+// ---- what the flow does with a step's reply -------------------------------------
+
+/** A kind of action that reads a Power Automate step's reply before the flow
+    acts on it: the expression it reads it through. A registry, so another
+    reader (a Compose, a connector) is one more entry. */
+                                 
+                                                                    
+                                                        
+                                                                    
+                                                    
+ 
+
+export const FLOW_READERS                                 = Object.create(null);
+
+// Parse JSON: its content is the expression that turns the reply into what
+// its schema checks -- the fence-stripping `trim(replace(…))`, say.
+FLOW_READERS.ParseJson = {
+  reads: (inputs) => (typeof inputs.content === "string" ? inputs.content : null),
+  schema: (inputs) => inputs.schema ?? null,
+};
+
+/** The reader action that reads [step]'s reply: its name, the expression it
+    reads through, and its schema -- or null when none does. */
+export function readerFor(definition         , step        )                                                               {
+  for (const [name, a] of Object.entries(actionsByName(definition))) {
+    const kind = a.type ? FLOW_READERS[a.type] : undefined;
+    const expr = kind && isObj(a.inputs) ? kind.reads(a.inputs) : null;
+    if (expr && readsOf(expr).some((r) => r.from === "action" && r.name === step)) {
+      return { name, expression: expr, schema: kind .schema && isObj(a.inputs) ? kind .schema(a.inputs) ?? null : null };
+    }
+  }
+  return null;
+}
+
+/** How the flow reads [step]'s reply: the expression of the first reader
+    action that reads it, or null when none does. */
+export const readerOf = (definition         , step        )                => readerFor(definition, step)?.expression ?? null;
+
+/** The fields of [reader]'s output the rest of the flow reads --
+    `body('Parse_JSON')['category']` in a Condition -- in the order they appear:
+    what production's decisions turn on, so what a new wording has to keep. */
+export function fieldsRead(definition         , reader        )           {
+  const text = JSON.stringify(isObj(definition) ? definition.actions ?? {} : {});
+  const name = reader.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/'/g, "''");
+  const found = new Set        ();
+  for (const m of text.matchAll(new RegExp(`body\\('${name}'\\)\\??\\['((?:[^']|'')*)'\\]`, "g"))) found.add(m[1] .replace(/''/g, "'"));
+  return [...found];
+}