sitelooper 0.3.0

package/dist/skills/flow.js

@@ -0,0 +1,1041 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { rootDir } from '../shared/paths.js';
+import { escapeRe, urlParts } from './compile.js';
+import { idPositionPart, identifierLike } from './ledger.js';
+/**
+ * Outputs a later run may substitute as a LITERAL when the producing step did
+ * not republish them: `{{sid.out}}` → the recorded value.
+ *
+ * One demonstration of difference is permanent. A value that changed once
+ * names a record, and being wrong in that direction is the silent failure —
+ * a step acting on the recording run's record while reporting success —
+ * whereas being wrong the other way costs a recovery turn. So `differed` is a
+ * veto no amount of later agreement lifts.
+ */
+export function stableOutputs(flow) {
+    const out = {};
+    for (const step of flow.steps) {
+        for (const [name, ev] of Object.entries(step.outputEvidence ?? {})) {
+            if (ev.differed > 0 || ev.same < 1)
+                continue;
+            const value = step.recorded?.[name];
+            if (typeof value === 'string' && value)
+                out[`${step.id}.${name}`] = value;
+        }
+    }
+    return out;
+}
+/**
+ * Record what a replay of `step` produced, against what the recording run saw.
+ * Only outputs BOTH runs reported can be compared — a tier-A replay honestly
+ * drops what it could not re-observe, and silence is not disagreement.
+ * Returns the names whose verdict changed, for progress reporting.
+ */
+export function noteOutputEvidence(step, reported) {
+    const changed = [];
+    for (const [name, recorded] of Object.entries(step.recorded ?? {})) {
+        const seen = reported[name];
+        if (typeof seen !== 'string' || !seen || typeof recorded !== 'string' || !recorded)
+            continue;
+        const ev = (step.outputEvidence ??= {})[name] ?? { same: 0, differed: 0 };
+        const agrees = seen.trim() === recorded.trim();
+        const wasStable = ev.differed === 0 && ev.same >= 1;
+        if (agrees)
+            ev.same += 1;
+        else
+            ev.differed += 1;
+        step.outputEvidence[name] = ev;
+        if (wasStable !== (ev.differed === 0 && ev.same >= 1))
+            changed.push(name);
+        else if (ev.same + ev.differed === 1)
+            changed.push(name);
+    }
+    return changed;
+}
+export function flowsDir() {
+    return process.env.SITELOOPER_FLOWS_DIR || path.join(rootDir(), 'flows');
+}
+function flowFile(name) {
+    const safe = name.replace(/[^A-Za-z0-9._-]+/g, '_');
+    return path.join(flowsDir(), `${safe}.json`);
+}
+/**
+ * Write a flow. `file` defaults to the flows dir under the flow's own name;
+ * a run that loaded the flow from somewhere else passes that path back so
+ * evidence and re-pins land where they came from. Tmp + rename, so a reader
+ * never sees a half-written file.
+ */
+export function saveFlow(flow, file = flowFile(flow.name)) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(flow, null, 2));
+    fs.renameSync(tmp, file);
+    return file;
+}
+/**
+ * A flow the export REFUSED, written where nothing will replay it.
+ *
+ * Refusing is right — a flow carrying a run value in a locator quietly does
+ * its work on the wrong record — but throwing the recording away with it is
+ * not. fwrd23l cost 37 minutes and $0.26 to record and left nothing at all
+ * behind, and a cloud run is dearer. The `.rejected.json` suffix keeps it out
+ * of listFlows — which is excluded explicitly, since `.rejected.json` ends in
+ * `.json` too — while leaving it for verify-artifacts and for a human to read.
+ */
+export function saveRejectedFlow(flow, reason) {
+    const dir = flowsDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const file = flowFile(flow.name).replace(/\.json$/, '.rejected.json');
+    fs.writeFileSync(file, JSON.stringify({ rejected: reason, flow }, null, 2));
+    return file;
+}
+/** A flow and the file it was read from — a path first, then a name in the flows dir. */
+export function loadFlowFile(nameOrPath) {
+    const candidates = [nameOrPath, flowFile(nameOrPath)];
+    for (const file of candidates) {
+        try {
+            return { flow: JSON.parse(fs.readFileSync(file, 'utf8')), file };
+        }
+        catch {
+            /* try next */
+        }
+    }
+    return null;
+}
+export function loadFlow(nameOrPath) {
+    return loadFlowFile(nameOrPath)?.flow ?? null;
+}
+export function listFlows() {
+    let names;
+    try {
+        names = fs.readdirSync(flowsDir()).filter((n) => n.endsWith('.json') && !n.endsWith('.rejected.json'));
+    }
+    catch {
+        return [];
+    }
+    return names.map((n) => loadFlow(path.join(flowsDir(), n))).filter((f) => Boolean(f));
+}
+/**
+ * Build a flow from one session's recording.
+ *
+ * References are resolved in two passes so a step can never reference a value
+ * that has not been produced yet:
+ *  1. Declared run variables (`vars`) → `{{name}}`, everywhere they occur.
+ *  2. A value that equals an *earlier* step's named output → `{{stepId.output}}`.
+ * Anything left literal is a constant the caller typed, and stays literal.
+ */
+export function buildFlow(entries, opts) {
+    const groups = resolveGroups(groupByInstruction(entries));
+    if (!groups.length)
+        return null;
+    const steps = [];
+    const warnings = [];
+    const produced = [];
+    const seenUrl = new Set(urlParts(opts.startUrl).map((p) => p.value));
+    const varEntries = Object.entries(opts.vars).filter(([, v]) => v.length >= 2).sort((a, b) => b[1].length - a[1].length);
+    let prevId;
+    let prevGroup;
+    groups.forEach((g, i) => {
+        const id = stepId(g.instruction.text, i);
+        // Read the RAW instruction, before references go in: a substituted
+        // {{02-create.quotation_ref}} shifts every later word and can push the
+        // ask outside the scan window.
+        const noop = noopStepWarning(id, g);
+        if (noop)
+            warnings.push(noop);
+        if (prevId && prevGroup) {
+            const contradiction = contradictionWarning(prevId, prevGroup, id, g);
+            if (contradiction)
+                warnings.push(contradiction);
+        }
+        prevId = id;
+        prevGroup = g;
+        let text = g.instruction.text;
+        for (const [name, value] of varEntries)
+            text = replaceToken(text, value, `{{${name}}}`);
+        // Reference earlier outputs (longest values first so nested ids resolve).
+        for (const p of [...produced].sort((a, b) => b.value.length - a.value.length)) {
+            if (p.value.length >= 2 && !coincidental(text, p.value))
+                text = replaceToken(text, p.value, `{{${p.stepId}.${p.output}}}`);
+        }
+        const outputs = Object.keys(g.report?.values ?? {});
+        // Capture the skill's slot bindings, referencized like the instruction, so
+        // replay binds params from the flow rather than re-parsing the wording.
+        let params;
+        if (g.report?.skill && opts.bind) {
+            const raw = opts.bind(g.report.skill, g.instruction.text);
+            if (raw) {
+                params = {};
+                for (const [k, v] of Object.entries(raw)) {
+                    let rv = v;
+                    for (const [name, value] of varEntries)
+                        rv = replaceToken(rv, value, `{{${name}}}`);
+                    for (const pr of [...produced].sort((a, b) => b.value.length - a.value.length)) {
+                        if (pr.value.length >= 2 && !coincidental(rv, pr.value))
+                            rv = replaceToken(rv, pr.value, `{{${pr.stepId}.${pr.output}}}`);
+                    }
+                    params[k] = rv;
+                }
+            }
+        }
+        steps.push({
+            id,
+            instruction: text,
+            ...(g.report?.skill ? { skill: g.report.skill } : {}),
+            ...(params ? { params } : {}),
+            outputs,
+            recorded: g.report?.values ?? {},
+            ...(g.adopted ? { adopted: true } : {}),
+        });
+        // Provenance (PLAN-replay-v2): url parts this step MINTED (absent from
+        // every earlier url) are outputs too — a later step's recorded literal
+        // equal to one becomes {{stepId.url.<part>}}, re-bound each run from
+        // where the replay's own browser lands. Same guards as report outputs:
+        // length >= 4, first appearance wins.
+        //
+        // Url parts go into `produced` BEFORE report values, and a report value
+        // that duplicates a minted part is not referencized under its report
+        // name: a zero-model (tier-A) replay synthesizes its report from live
+        // read-backs only and honestly DROPS recorded values it could not
+        // re-observe, so a {{step.reportName}} ref dies exactly when the replay
+        // is at its best — while {{step.url.<part>}} is published by every
+        // replay unconditionally. fwgr-n2/n3 halted on precisely this: the
+        // recorded instructions referenced {{02-create.dashboard_uid}}, the
+        // tier-A replay's report legitimately omitted it, and recovery ran with
+        // the uid blanked until it turn-capped.
+        const minted = [];
+        if (g.endUrl) {
+            // The WHOLE url, not only its parts. A step's params often carry it
+            // entire ("On ticket {{v1}} (url {{v2}})"), and without provenance that
+            // literal gets referencized under whatever the RECORDING run's report
+            // happened to name it. fwrd21l shows the cost: 02-add's model report
+            // named it `url`, so the flow said {{02-add.url}} — then on replay 02-add
+            // went tier A, synthesizeReport honestly dropped a recorded url it could
+            // not re-observe, the ref went unresolved, and FOUR later steps skipped
+            // the zero-model path entirely. Exactly the fwgr-n2/n3 failure the parts
+            // loop below was written for, one level up.
+            if (!produced.some((p) => p.value === g.endUrl) && !varEntries.some(([, v]) => v === g.endUrl)) {
+                minted.push({ stepId: id, output: 'url', value: g.endUrl });
+            }
+            for (const part of urlParts(g.endUrl)) {
+                const fresh = !seenUrl.has(part.value);
+                seenUrl.add(part.value);
+                // Looser than compile-level derived params, which demand a digit:
+                // grafana mints digitless uids ("cfwcsdxqdjabkf" sank fwgr2), so
+                // identifierLike() accepts a long word too. It still refuses short
+                // route words — "tickets" out of a url was being substituted into
+                // fwrd8's verify prose ("on the {{01-open.url.h0}} list").
+                // Position is evidence here too: a `q.id` part is a record id
+                // whatever its length — odoo's `#id=44` failed the shape test and the
+                // recording's record rode into fwod27's replays (see idPositionPart).
+                if (!fresh || (!identifierLike(part.value) && !idPositionPart(part)))
+                    continue;
+                if (produced.some((p) => p.value === part.value) || varEntries.some(([, v]) => v === part.value))
+                    continue;
+                minted.push({ stepId: id, output: `url.${part.label}`, value: part.value });
+            }
+        }
+        produced.push(...minted);
+        for (const [output, value] of Object.entries(g.report?.values ?? {})) {
+            if (typeof value !== 'string' || !value)
+                continue;
+            if (minted.some((m) => m.value === value))
+                continue;
+            // A value the step's own instruction handed it is an INPUT the report
+            // echoed, not something the step observed: a later step quoting it
+            // resolves the way this step did — a var, an earlier reference, or a
+            // constant of the flow — never through this step's output, which a
+            // tier-A replay has no read to republish. fwgr23 05-open referenced
+            // {{04-open.tag}} for the "bench" its own instruction typed; the
+            // zero-model replay of 04-open could not publish it, and 05-open went
+            // to the model on every replay (19–44 turns).
+            if (replaceToken(g.instruction.text, value, ' ') !== g.instruction.text)
+                continue;
+            // EVERY reported value becomes a reference. Run 1 makes no judgement
+            // about which of them name a record, because it cannot: "New (unsaved)"
+            // and "S00021" are both just strings a step reported, and the question
+            // — does the app produce this again, or was it specific to this run? —
+            // is about behaviour ACROSS runs.
+            //
+            // A previous cut of this gated on identifierLike, which reads the
+            // characters. That is the failure this plan exists to remove: a record
+            // id that does not look like one would be left literal and every replay
+            // would act on run 1's record while reporting success.
+            //
+            // So reference everything, which is the safe default (an unresolved
+            // reference costs a recovery turn, never a wrong record), and let run 2
+            // demote the ones it demonstrates are app furniture — see
+            // noteOutputEvidence/stableOutputs and PLAN-evidence-over-shape.md.
+            produced.push({ stepId: id, output, value });
+            // An id can be minted where no url ever carries it: an app that saves
+            // over its own API answers with JSON, and the run reads that answer
+            // back rather than navigating. fwgr5 created its dashboard exactly so —
+            // the uid existed only inside the response body — and every later step
+            // kept n1's literal uid, which is what made those steps re-derive it on
+            // the cheap model on every replay. Publish the JSON's scalar leaves
+            // under `{{step.output#path}}`: a tier-A replay re-observes the read,
+            // so the path re-reads THIS run's value.
+            for (const leaf of jsonLeaves(value)) {
+                if (produced.some((p) => p.value === leaf.value) || varEntries.some(([, v]) => v === leaf.value))
+                    continue;
+                produced.push({ stepId: id, output: `${output}#${leaf.path}`, value: leaf.value });
+            }
+        }
+    });
+    return {
+        name: opts.name,
+        origin: opts.origin,
+        startUrl: opts.startUrl,
+        vars: Object.keys(opts.vars),
+        steps,
+        provenance: { session: opts.session, created: opts.now ?? new Date().toISOString(), ...(opts.model ? { model: opts.model } : {}) },
+        ...(warnings.length ? { warnings } : {}),
+    };
+}
+function groupByInstruction(entries) {
+    const groups = [];
+    for (const e of entries) {
+        if (e.k === 'instruction') {
+            // An escalation continuation (recorded under the original wording,
+            // marked `resume`) is the same instruction still in flight: keep the
+            // predecessor's group open so its clean start context survives and the
+            // continuation's report/endUrl land on it. A resume with no same-text
+            // predecessor (truncated recording) stands alone.
+            const prev = groups[groups.length - 1];
+            if (e.resume && prev?.instruction.text === e.text)
+                continue;
+            groups.push({ instruction: e, mutations: 0, mutationsDiffed: 0, mutationsEffective: 0 });
+        }
+        else if (e.k === 'report' && groups.length)
+            groups[groups.length - 1].report = e;
+        else if (e.k === 'step' && groups.length) {
+            const g = groups[groups.length - 1];
+            if (e.diff?.url)
+                g.endUrl = e.diff.url;
+            if (!g.firstTool)
+                g.firstTool = e.tool;
+            if (MUTATING_TOOLS.has(e.tool)) {
+                g.mutations += 1;
+                if (e.diff) {
+                    g.mutationsDiffed += 1;
+                    const moved = Boolean(e.diff.url) && Boolean(g.instruction.url) && e.diff.url !== g.instruction.url;
+                    if (e.diff.added?.length || e.diff.alerts?.length || moved)
+                        g.mutationsEffective += 1;
+                }
+            }
+        }
+    }
+    return groups;
+}
+/** Same page, ignoring query and hash — view state, not location. */
+function samePage(a, b) {
+    if (!a || !b)
+        return false;
+    try {
+        const ua = new URL(a);
+        const ub = new URL(b);
+        return ua.origin === ub.origin && decodeURIComponent(ua.pathname) === decodeURIComponent(ub.pathname);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The groups that ARE the resolved path, in order.
+ *
+ * Success groups, obviously. But dropping every other group loses work the
+ * session provably built on: fwgr14's "create a NEW dashboard. Add a Stat
+ * panel..." blocked on the turn budget, then failed on escalation — yet both
+ * attempts HAD created the dashboard, and the very next (successful)
+ * instruction began "The browser is on an unsaved new Grafana dashboard..."
+ * and saved it. The exported flow started on in-memory state no replay could
+ * reach and scored 1/6 on every replay. Same class as fwod27, where the
+ * dropped create meant no step produced the record and its id could not be
+ * referencized.
+ *
+ * So a non-success group is ADOPTED when the recording itself testifies its
+ * work is part of the path:
+ *   1. it changed the app (ran mutating tools) — an observing group that
+ *      blocked contributed nothing a replay needs;
+ *   2. the next kept group picked up exactly where it left off — issued on
+ *      the same page the group ended on, and not opening with a `goto`
+ *      (a successor that navigates away first is the workaround case, where
+ *      the drop is correct).
+ * Scanned right-to-left so a chain of continuations adopts as a chain.
+ *
+ * Marks `adopted` on the group (unbankedMutations reads it) and returns the
+ * kept groups.
+ */
+function resolveGroups(groups) {
+    const kept = groups.map((g) => g.report?.status === 'success');
+    for (let i = groups.length - 2; i >= 0; i--) {
+        if (kept[i])
+            continue;
+        const g = groups[i];
+        const next = groups[i + 1];
+        if (!g.report || !g.mutations || !kept[i + 1])
+            continue;
+        if (next.firstTool === 'goto')
+            continue;
+        if (!samePage(g.endUrl, next.instruction.url))
+            continue;
+        g.adopted = true;
+        kept[i] = true;
+    }
+    return groups.filter((_, i) => kept[i]);
+}
+/**
+ * Verbs whose presence makes an instruction MUTATING BY INTENT — the caller
+ * asked for the app to be different afterwards, not merely observed.
+ */
+const MUTATING_VERBS = [
+    'create', 'add', 'delete', 'remove', 'cancel', 'confirm', 'change', 'update',
+    'set', 'save', 'submit', 'move', 'archive', 'rename', 'upload',
+];
+/**
+ * One verb, in the shapes an orchestrator actually writes it. Spelled out
+ * rather than a `verb\w{0,4}` wildcard on purpose: the wildcard makes "set"
+ * match "settings" and "settled", and every false verb here becomes a false
+ * warning against a step that is fine.
+ */
+function verbForms(verb) {
+    const noE = verb.replace(/e$/, '');
+    const last = verb[verb.length - 1];
+    return [verb, `${verb}s`, `${verb}es`, `${verb}d`, `${verb}ed`, `${verb}ing`, `${noE}ing`, `${verb}${last}ed`, `${verb}${last}ing`];
+}
+const MUTATING_VERB_RE = new RegExp(`^(?:${MUTATING_VERBS.flatMap(verbForms).join('|')})$`, 'i');
+/** A word that turns the verb after it into an instruction NOT to do the thing. */
+const NEGATOR_RE = /^(?:not|never|no|without|cannot|don't|dont|doesn't|isn't|avoid|skip)$/i;
+/**
+ * An instruction that says, anywhere, that it changes nothing. fwod34's
+ * 07-open and 09-change both do ("this is a read-only check", "Read-only
+ * check, do not change anything") while both quote a mutating verb — 09's
+ * step id is literally `09-change`. Cheap, exact, and it costs only warnings
+ * we would rather not have made.
+ */
+const READ_ONLY_RE = /read[- ]?only|do(?: not|n't|nt) (?:change|modify|edit|alter)|without (?:chang|modify|edit)/i;
+/**
+ * The verb this instruction asks for, or null if it asks for nothing that
+ * changes the app.
+ *
+ * Scans the opening of the instruction — where the orchestrator states the
+ * job, before the how-to prose and the reporting boilerplate. The window is
+ * WIDE (40 words) because real wording puts the ask late: fwod34's 08-open
+ * spends nineteen words identifying the record ("The sales order S00021
+ * (model sale.order, record id 21) is currently in 'Sales Order' status and
+ * needs to be") before it says "cancelled". A wide window is safe only
+ * because both guards above run first — a negated verb and a self-declared
+ * read-only instruction are dropped whatever the window.
+ */
+export function mutatingIntent(instruction) {
+    if (READ_ONLY_RE.test(instruction))
+        return null;
+    const words = instruction.split(/\s+/).slice(0, 40).map((w) => w.replace(/^[^A-Za-z']+|[^A-Za-z']+$/g, ''));
+    for (let i = 0; i < words.length; i++) {
+        if (!MUTATING_VERB_RE.test(words[i]))
+            continue;
+        if (words.slice(Math.max(0, i - 6), i).some((w) => NEGATOR_RE.test(w)))
+            continue;
+        const lower = words[i].toLowerCase();
+        const verb = MUTATING_VERBS.find((v) => verbForms(v).some((f) => f === lower));
+        if (verb)
+            return verb;
+    }
+    return null;
+}
+/**
+ * A value this instruction reported that the page was ALREADY showing before
+ * it ran — the strongest single line of evidence that the step's outcome was
+ * not the step's doing.
+ *
+ * Conservative by construction: single-line values only (a status bar's whole
+ * multi-line text is never a fair substring test), at least three characters,
+ * and an exact match against the pre-state snapshot. When nothing qualifies
+ * the caller omits the clause rather than guessing.
+ */
+function alreadyShown(g) {
+    const before = g.instruction.startText;
+    if (!before)
+        return null;
+    for (const value of Object.values(g.report?.values ?? {})) {
+        if (typeof value !== 'string')
+            continue;
+        const v = value.trim();
+        if (v.length < 3 || v.includes('\n'))
+            continue;
+        if (before.includes(v))
+            return v;
+    }
+    return null;
+}
+/**
+ * A step whose instruction asked for a change and whose recording shows none.
+ *
+ * This is the record-time half of the fwod34 08-open failure. The recording
+ * orchestrator wrote an instruction to cancel an order a previous instruction
+ * had already been told to cancel; the step reported success, and every later
+ * replay halts there because the Cancel button its skill clicks does not
+ * exist once the order is cancelled. Every fact needed to say "re-record
+ * 08-open" was already in the recording at export time — this reads them.
+ *
+ * Two shapes count as "changed nothing", and both need the report to say
+ * SUCCESS (a blocked or failed instruction is reported elsewhere, and its
+ * emptiness is expected rather than suspicious):
+ *
+ *  1. the instruction ran no state-changing tool at all; or
+ *  2. it ran them and NONE of them moved the page — no signature line added,
+ *     no alert, no navigation. fwod34's 08-open is this one: five clicks and
+ *     an Escape against a form whose cancel dialog the previous instruction
+ *     had already left open, every diff empty on all three counts, while its
+ *     five genuinely mutating siblings (02-create through 05-open) each show
+ *     one to eighteen effective diffs.
+ *
+ * Shape 2 demands that diffs were being captured at all (`mutationsDiffed`),
+ * so a recording made without them cannot be read as a flow of no-ops.
+ *
+ * Warn-level, and worded as a suspicion: the flow still exports. What it buys
+ * is that whoever can cheaply re-record is told, and that the warning rides
+ * on the flow (`Flow.warnings`) for compile to raise again later.
+ */
+function noopStepWarning(id, g) {
+    if (g.report?.status !== 'success')
+        return null;
+    const verb = mutatingIntent(g.instruction.text);
+    if (!verb)
+        return null;
+    const noAction = g.mutations === 0;
+    const noEffect = g.mutations > 0 && g.mutationsDiffed > 0 && g.mutationsEffective === 0;
+    if (!noAction && !noEffect)
+        return null;
+    const evidence = noAction
+        ? 'the recording made no state-changing action'
+        : `the recording's ${g.mutations} state-changing action${g.mutations === 1 ? '' : 's'} left the page unchanged`;
+    const shown = alreadyShown(g);
+    const clause = shown ? `, and the page already showed '${shown}' before it ran` : '';
+    return `noop-step: ${id} changed nothing: its instruction asks to ${verb}, ${evidence}${clause}. The step may be redundant.`;
+}
+/**
+ * A mutating step's report contradicted by the very next read-only step.
+ *
+ * fwod34's 06-open reported "Cancelled" for the sales order; 07-open, a
+ * read-only step immediately after it, read the same order's status back as
+ * "Sales Order" — the value the order carries whenever it is NOT cancelled.
+ * Nothing in the flow said this out loud: compile just kept both facts and
+ * let a much later step (08-open, told to cancel an order that was already
+ * cancelled) take the blame. The contradiction is visible at export time —
+ * this reads it directly off the two instructions' report values, the same
+ * way `noopStepWarning` reads a step's own report against its own pre-state.
+ *
+ * Scope is deliberately narrow: `i` must be mutating by intent and report
+ * success (a step that failed or was never asked to change anything cannot
+ * be "contradicted" — there is nothing for the next read to disagree with),
+ * and `j` must immediately follow `i` with no gap and be read-only by intent
+ * (a second mutating step is expected to change what the first one did, so
+ * comparing it would be noise, not a contradiction).
+ *
+ * Values are matched by label first (the natural case — the same field read
+ * twice), falling back to any label pair where BOTH names look like a status
+ * or state field, since an orchestrator's wording for the same field drifts
+ * step to step ("order_status" vs "current_status"). Only the first line of
+ * each value is compared: a status bar lists every reachable state on one
+ * line each, so the first line is the CURRENT one and the rest is noise the
+ * same way `alreadyShown` treats it. Containment either way counts as
+ * agreement (a single-line report next to a status bar's fuller line, or a
+ * value that reappeared verbatim, is not a contradiction) — only two first
+ * lines that share nothing warrant a warning.
+ */
+function contradictionWarning(idI, gi, idJ, gj) {
+    if (gi.report?.status !== 'success')
+        return null;
+    if (!mutatingIntent(gi.instruction.text))
+        return null;
+    if (mutatingIntent(gj.instruction.text))
+        return null;
+    const iValues = gi.report?.values ?? {};
+    const jValues = gj.report?.values ?? {};
+    for (const [label, jRaw] of Object.entries(jValues)) {
+        if (typeof jRaw !== 'string')
+            continue;
+        let iLabel = typeof iValues[label] === 'string' ? label : undefined;
+        if (!iLabel && /status|state/i.test(label)) {
+            iLabel = Object.keys(iValues).find((k) => typeof iValues[k] === 'string' && /status|state/i.test(k));
+        }
+        if (!iLabel)
+            continue;
+        const iRaw = iValues[iLabel];
+        const jLine = jRaw.split('\n')[0].trim();
+        const iLine = iRaw.split('\n')[0].trim();
+        if (!jLine || !iLine)
+            continue;
+        const lj = jLine.toLowerCase();
+        const li = iLine.toLowerCase();
+        if (lj.includes(li) || li.includes(lj))
+            continue;
+        return `contradicted-step: ${idJ} read ${label} "${jLine}" right after ${idI} reported "${iLine}"; ${idI}'s change may not have landed and a later step may be retrying it. Re-record ${idI}.`;
+    }
+    return null;
+}
+/** Tools that CHANGE the app, as opposed to observing it. */
+const MUTATING_TOOLS = new Set(['click', 'dblclick', 'right_click', 'modifier_click', 'fill', 'type', 'press', 'select', 'check', 'drag', 'upload']);
+/**
+ * Instructions that CHANGED the app but did not report success AND were not
+ * adopted, so their work contributed nothing to the flow.
+ *
+ * resolveGroups now adopts the fwgr13/fwgr14 shape (the next kept group
+ * carried straight on from the blocked work), so what remains here is the
+ * genuinely dropped case: mutating work the session abandoned or worked
+ * around. That drop is right — but it must not be silent, because whether the
+ * workaround actually replaced the work is a judgement only the person
+ * reading the export can make.
+ */
+/**
+ * Flow instructions that quote a DATABASE ID this recording minted.
+ *
+ * The one channel no leak guard reads is the instruction prose itself. In
+ * fwod27 the recording-time orchestrator wrote "You are on an Odoo contact
+ * form for res.partner id 44" — the id of the record ITS run created (in a
+ * blocked instruction, so no flow step produces the value and nothing can be
+ * referencized). Locator and navigation guards all passed; both replays
+ * navigated to record 44, which the reset had deleted, and halted at step 2
+ * with 0/6.
+ *
+ * Scans EVERY recorded url (blocked instructions included — that is where
+ * fwod27's id was minted) for id-position parts, then flags any flow
+ * instruction that still quotes one as a literal id. Warn-level: the flow
+ * still exports, but the person who can re-record is told while it is cheap.
+ */
+export function staleInstructionIds(entries, flow) {
+    const minted = new Set();
+    for (const e of entries) {
+        const url = e.k === 'step' ? e.diff?.url : e.k === 'instruction' ? e.url : undefined;
+        if (!url)
+            continue;
+        for (const part of urlParts(url))
+            if (idPositionPart(part))
+                minted.add(part.value);
+    }
+    if (!minted.size)
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const step of flow.steps) {
+        for (const m of step.instruction.matchAll(/\bid\s*[:#]?\s*(\d{1,10})\b/gi)) {
+            if (!minted.has(m[1]) || seen.has(`${step.id}:${m[1]}`))
+                continue;
+            seen.add(`${step.id}:${m[1]}`);
+            out.push(`${step.id}'s instruction quotes record id ${m[1]} — a database id this recording minted, so every replay ` +
+                `will act on the RECORDING run's record (deleted by the next reset). Re-record with instructions that ` +
+                `name records by what is on screen (a name or reference), never by internal id.`);
+        }
+    }
+    return out;
+}
+export function unbankedMutations(entries) {
+    const groups = groupByInstruction(entries);
+    resolveGroups(groups); // marks `adopted` in place
+    const out = [];
+    for (const g of groups) {
+        if (g.report?.status === 'success' || g.adopted || !g.mutations)
+            continue;
+        const text = g.instruction.text;
+        out.push(`instruction "${text.slice(0, 70)}${text.length > 70 ? '…' : ''}" ran ${g.mutations} state-changing step(s) ` +
+            `but reported ${g.report ? g.report.status : 'nothing'} — its work is NOT in the flow`);
+    }
+    return out;
+}
+function stepId(text, i) {
+    const verb = (/\b(sign in|log ?in|create|add|edit|change|set|delete|remove|archive|open|verify|find|report)\b/i.exec(text)?.[1] ?? 'step')
+        .toLowerCase()
+        .replace(/\s+/g, '');
+    return `${String(i + 1).padStart(2, '0')}-${verb}`;
+}
+/** Replace a value on token boundaries, leaving substrings of longer words alone. */
+/**
+ * The value only LOOKS like this reference: a common word matching inside a
+ * hyphenated compound that means something else.
+ *
+ * fwgr8 reported `tags: "bench"` and its dashboard slug was
+ * `fwgr8-n1-bench-dashboard`, so four later steps had their url rewritten to
+ * `{{runid}}-{{04-open.tags}}-dashboard`. The "bench" in that slug comes from
+ * the dashboard's NAME, not from its tags; the two agreed by coincidence on
+ * the recording run and would not on any other. Every one of those refs then
+ * failed to resolve and cost its step the zero-model path.
+ *
+ * Hyphens deliberately do not bind in replaceToken, because a runid prefix in
+ * `x7-bench-dashboard` IS worth threading. The distinction is what the value
+ * is: a minted identifier is specific enough that matching inside a compound
+ * is evidence, while a common word is not. So a non-identifier must stand
+ * alone to be referencized.
+ */
+function coincidental(text, value) {
+    if (identifierLike(value))
+        return false;
+    return new RegExp(`(?<![A-Za-z0-9_-])${escapeRe(value)}(?![A-Za-z0-9_-])`).test(text) === false;
+}
+function replaceToken(text, value, marker) {
+    if (!value)
+        return text;
+    // Underscores bind: `o_form_view_group` is ONE identifier, so a var whose
+    // value is "form" must not rewrite its middle (fwod5 shipped exactly that
+    // corruption). Hyphens do not bind — a runid prefix in "x7-bench-dashboard"
+    // is a reference worth threading.
+    const re = new RegExp(`(?<![A-Za-z0-9_])${escapeRe(value)}(?![A-Za-z0-9_])`, 'g');
+    // Never substitute INSIDE a reference already placed by an earlier pass: a
+    // provenance value that happens to be a common word ("form") rewrote the
+    // middle of an output NAME, and fwod5 shipped steps referencing
+    // `{{02-create.o_{{01-open.url.q.view_type}}_view_o_group_tabl}}` — a ref
+    // that can never resolve. Split on markers, rewrite only the gaps.
+    return text
+        .split(/(\{\{[^{}]*\}\})/g)
+        .map((piece) => (piece.startsWith('{{') && piece.endsWith('}}') ? piece : piece.replace(re, marker)))
+        .join('');
+}
+/**
+ * Name the cause of a flow step's recovery, for the progress line and drift
+ * telemetry. ALL causes now run cheap-first with the strong model as
+ * escalation-on-blocked: the fwrd4l sweep showed the session model rescuing
+ * every recovery — replay-failed ones included — at a fraction of the strong
+ * model's rate ($0.041 warm vs $0.104 when the same steps routed straight to
+ * the strong tier), and a replay refusal is usually a binding problem (a
+ * stale template), not the genuine drift the straight-to-strong route was
+ * priced for. The strong model is still one blocked report away.
+ */
+export function recoveryRoute(step, unresolved) {
+    if (step.adopted && !step.skill)
+        return { easy: true, cause: 'adopted' };
+    if (!step.skill)
+        return { easy: true, cause: 'no-skill' };
+    if (unresolved)
+        return { easy: true, cause: 'unthreaded-ref' };
+    return { easy: true, cause: 'replay-failed' };
+}
+/**
+ * Export-time reference lint (PLAN-no-skill-steps case 4a): find every
+ * `{{stepId.output}}` reference whose producing step cannot re-publish the
+ * value deterministically on replay, and say so while the author can still do
+ * something about it. `url` and its `url.*` parts are exempt — every replay re-binds them
+ * from where its own browser lands. `publishes` answers, for a skill id, which
+ * output names a tier-A replay re-observes (labelled reads + param-derived
+ * report values); null when the skill is not in the store. Advisory only:
+ * replay behaviour is unchanged — an unthreaded ref already routes to cheap
+ * recovery — this surfaces the debt at build time instead of replay time.
+ */
+export function lintFlowRefs(flow, publishes) {
+    const byId = new Map(flow.steps.map((s) => [s.id, s]));
+    const warnings = [];
+    const seen = new Set();
+    for (const step of flow.steps) {
+        const texts = [step.instruction, ...Object.values(step.params ?? {})];
+        for (const text of texts) {
+            for (const m of text.matchAll(/\{\{([\w-]+)\.([\w.#-]+)\}\}/g)) {
+                const [, sid, out] = m;
+                if (out === 'url' || out.startsWith('url.'))
+                    continue;
+                const producer = byId.get(sid);
+                if (!producer || seen.has(`${sid}.${out}`))
+                    continue;
+                seen.add(`${sid}.${out}`);
+                const pubs = producer.skill ? publishes(producer.skill) : [];
+                // A JSON-path ref (`body#dashboard.uid`) lives or dies with the read
+                // that publishes `body`; the path itself is applied after the fact.
+                if (pubs === null || pubs.includes(out.split('#')[0]))
+                    continue;
+                warnings.push(`{{${sid}.${out}}} (used by ${step.id}) can only be re-observed by model recovery — ` +
+                    `consider re-recording so the value is read from the page.`);
+            }
+        }
+    }
+    return warnings;
+}
+/**
+ * One step output, with support for a JSON path suffix: `body#dashboard.uid`
+ * reads the `body` output, parses it as JSON, and walks the path. That is how
+ * an id an app only ever returned in a response body gets threaded — see the
+ * jsonLeaves() publication in buildFlow.
+ */
+/**
+ * The outputs a step's END URL publishes: the whole url, plus every part
+ * specific enough to be a reference.
+ *
+ * ONE function, because the producer and the consumer disagreeing is a silent
+ * dead reference. buildFlow mints `{{step.url.h1}}` for any part that is
+ * `identifierLike` (three characters is enough — repair-desk's ids are "t15"),
+ * while the daemon published parts at `length >= 4`. So every flow that named
+ * a three-character record id minted a ref nothing would ever resolve, and the
+ * four steps depending on it skipped the zero-model path on every replay.
+ */
+export function urlOutputs(url) {
+    const out = { url };
+    for (const part of urlParts(url)) {
+        const key = `url.${part.label}`;
+        if (identifierLike(part.value) && !(key in out))
+            out[key] = part.value;
+    }
+    return out;
+}
+/**
+ * Which of each step's `url.*` outputs some OTHER step actually consumes
+ * (`{{03-open.url.q.id}}` in an instruction or a param). The flow runner
+ * captures a step's end-url outputs in one snapshot — but an SPA can update
+ * its URL a beat AFTER the page itself settles, and a structural replay is
+ * fast enough to finish inside that beat. Odoo does exactly this with the
+ * `id=` of a freshly saved record: fwod30's replays finished 03-open before
+ * the hash carried the id, `{{03-open.url.q.id}}` went unresolved, and every
+ * consumer of it fell to full recovery. Knowing which url outputs are
+ * consumed lets the capture wait for them, bounded, instead of snapshotting
+ * whatever the URL happened to say. The whole-url output (`url`) is always
+ * present, so only dotted parts are listed.
+ */
+export function consumedUrlOutputs(steps) {
+    const wanted = new Map();
+    for (const s of steps) {
+        for (const text of [s.instruction, ...Object.values(s.params ?? {})]) {
+            for (const m of text.matchAll(/\{\{([\w-]+)\.(url\.[\w.-]+?)(#[\w.-]+)?\}\}/g)) {
+                if (m[1] === s.id)
+                    continue; // own-step refs resolve after its capture regardless
+                const set = wanted.get(m[1]) ?? new Set();
+                set.add(m[2]);
+                wanted.set(m[1], set);
+            }
+        }
+    }
+    return wanted;
+}
+export function lookupOutput(outputs, sid, out) {
+    const hash = out.indexOf('#');
+    if (hash < 0)
+        return outputs[sid]?.[out];
+    const base = outputs[sid]?.[out.slice(0, hash)];
+    if (base === undefined)
+        return undefined;
+    let node;
+    try {
+        node = JSON.parse(base);
+    }
+    catch {
+        return undefined;
+    }
+    for (const key of out.slice(hash + 1).split('.')) {
+        if (node === null || typeof node !== 'object')
+            return undefined;
+        node = node[key];
+    }
+    return typeof node === 'string' || typeof node === 'number' ? String(node) : undefined;
+}
+/** One reference's value: a `{{var}}` from the run's vars, a `{{step.output}}` from prior outputs, else the stable literal. */
+function lookupRef(ref, src) {
+    if (!ref.includes('.'))
+        return ref in src.vars ? src.vars[ref] : undefined;
+    const dot = ref.indexOf('.');
+    const v = lookupOutput(src.outputs, ref.slice(0, dot), ref.slice(dot + 1));
+    // Demonstrated stable by an earlier run: the app produced this exact value
+    // again, so it is furniture and the recorded literal is right. Anything not
+    // demonstrated stays missing and goes to recovery.
+    if (v === undefined && ref in src.stable)
+        return src.stable[ref];
+    return v;
+}
+/**
+ * Fill every `{{ref}}` in `text`. ONE substitution for instructions and
+ * params alike — a reference that resolves in one and not the other is a
+ * silent way to send a step to recovery. `missing` names what could not be
+ * filled; an unfilled reference is left in place (`keep`) or blanked.
+ */
+export function resolveRefs(text, src, unresolved = 'keep') {
+    const missing = [];
+    const filled = text.replace(/\{\{([\w.#-]+)\}\}/g, (m, ref) => {
+        const v = lookupRef(ref, src);
+        if (v !== undefined)
+            return v;
+        missing.push(ref);
+        return unresolved === 'keep' ? m : '';
+    });
+    return { text: filled, missing };
+}
+/** Fill {{var}} and {{step.output}} references from run vars and prior outputs. */
+export function resolveInstruction(step, vars, outputs, stable = {}) {
+    return resolveRefs(step.instruction, { vars, outputs, stable });
+}
+/**
+ * Like resolveInstruction, but for the recovery path: fill every reference that
+ * can be filled and blank the rest (rather than leaving `{{...}}` in the text),
+ * so the strong model gets a readable instruction built from what IS known —
+ * e.g. the ticket title even when its id could not be threaded.
+ */
+export function softResolveInstruction(step, vars, outputs, stable = {}) {
+    return resolveRefs(step.instruction, { vars, outputs, stable }, 'blank')
+        .text.replace(/[ \t]{2,}/g, ' ')
+        .trim();
+}
+/** Resolve a step's stored param bindings from run vars and prior outputs. */
+/**
+ * Which of a step's unresolved references its pinned skill can do without.
+ *
+ * A reference lives in the step's wording and, sometimes, in a param. The
+ * pinned procedure is fixed: only a param some step TYPES or LOCATES by, or
+ * that names the record the skill must find (requireText), can change what
+ * it does. A reference that reaches nothing else — a tag the instruction
+ * mentions for context, a price quoted from the recording — cannot alter a
+ * zero-model replay, so its absence is no reason to skip one. fwgr23 05-open
+ * went to 19–44 model turns on both replays because `{{04-open.tag}}` was
+ * blank, bound to a param no step used.
+ */
+export function ignorableRefs(missing, step, skill) {
+    if (!skill)
+        return [];
+    const needed = new Set();
+    for (const [name, p] of Object.entries(skill.params))
+        if (p.usedIn.length)
+            needed.add(name);
+    for (const marker of skill.preconditions.requireText ?? [])
+        for (const m of marker.matchAll(/\{\{(v\d+)\}\}/g))
+            needed.add(m[1]);
+    return [...new Set(missing)].filter((ref) => {
+        const token = `{{${ref}}}`;
+        return !Object.entries(step.params ?? {}).some(([name, tmpl]) => needed.has(name) && tmpl.includes(token));
+    });
+}
+/**
+ * Slot bindings for a step that has just been re-pinned onto another skill.
+ * The old bindings are keyed by the OLD skill's slot names, which mean
+ * nothing to the new skill — rpat1-r1 re-pinned 04-add and kept
+ * `v2: "{{runid}}"` where the new skill's v2 was the project name, so r2
+ * bound the wrong values and the delete step was refused for a missing
+ * slot. Bindings are re-derived by VALUE: each new slot's example (the value
+ * the recovery actually used) is matched against what this run knew —
+ * the old bindings as resolved, the declared vars, earlier steps' outputs —
+ * and the matching template is carried over; a value containing a known
+ * value is templated on that part; anything else stays literal, which is
+ * what the recovery typed. `inherited` are the bindings a sibling step
+ * that already pins this skill stores, used for slots with no origin.
+ */
+export function remapParams(skill, inherited = {}) {
+    // A binding key names where a value comes from: "runid" / "var:runid" (a
+    // declared var), "01-open.landed_page" / "output:01-open:landed_page" (an
+    // earlier step's output), "02-create.url.p1" / "url:02-create:p1" (a url
+    // part a step minted). All of them are a {{ref}} the flow resolves.
+    const templateOf = (key) => {
+        const m = /^(var|url|output|input)(?::(.*))?$/.exec(key);
+        if (!m)
+            return `{{${key}}}`;
+        if (m[1] === 'var')
+            return `{{${m[2]}}}`;
+        if (m[1] === 'url') {
+            const [step, label] = String(m[2]).split(':');
+            return step && label ? `{{${step}.url.${label}}}` : null;
+        }
+        if (m[1] === 'output') {
+            const [step, name] = String(m[2]).split(':');
+            return step && name ? `{{${step}.${name}}}` : null;
+        }
+        return null; // 'input': the run typed it — the example is the value
+    };
+    // Slots with an origin, as (example → template) pairs; a slot whose
+    // example is a composite ("<runid> MTP Bench Project") is templated on the
+    // bound slots' examples — this skill's own run, so the values line up.
+    const bound = [];
+    for (const p of Object.values(skill.params)) {
+        const t = p.binding ? templateOf(p.binding) : null;
+        if (t && p.example)
+            bound.push({ value: String(p.example), template: t });
+    }
+    bound.sort((a, b) => b.value.length - a.value.length);
+    const params = {};
+    const unbound = [];
+    for (const [name, p] of Object.entries(skill.params)) {
+        const ex = String(p.example ?? '');
+        const direct = p.binding ? templateOf(p.binding) : null;
+        if (direct) {
+            params[name] = direct;
+            continue;
+        }
+        // A slot the skill recorded no origin for, but which another step of
+        // the same flow already binds (the flow's `params` for that step are
+        // {{ref}} templates that resolve on every run): inherit that binding.
+        // rr2od's 08-open was covered by 07-open's read-only status check,
+        // whose store entry predates slot origins; the flow knew them all along.
+        if (inherited[name] !== undefined) {
+            params[name] = inherited[name];
+            continue;
+        }
+        let text = ex;
+        for (const b of bound)
+            if (b.value && text.includes(b.value))
+                text = text.split(b.value).join(b.template);
+        params[name] = text;
+        // A value that identifies the record (known) and could not be templated
+        // would replay as the LEARNING run's literal — the re-pin is not safe.
+        if (p.known && text === ex)
+            unbound.push(name);
+    }
+    return { params, unbound };
+}
+export function resolveStepParams(step, vars, outputs, stable = {}) {
+    if (!step.params)
+        return null;
+    const params = {};
+    const missing = [];
+    for (const [k, tmpl] of Object.entries(step.params)) {
+        const r = resolveRefs(tmpl, { vars, outputs, stable });
+        params[k] = r.text;
+        missing.push(...r.missing);
+    }
+    return { params, missing };
+}
+/** Cap on JSON leaves published per read value, and how deep to walk. */
+const MAX_JSON_LEAVES = 12;
+const MAX_JSON_DEPTH = 4;
+/**
+ * Url parts of `url` that are identifier-like and that this session has not
+ * seen before — the values it just minted. First appearance wins, so the
+ * start url's own parts (and anything already banked) never qualify.
+ */
+export function freshUrlIds(url, seen) {
+    const out = [];
+    for (const part of urlParts(url)) {
+        // Three characters, not four: repair-desk's record ids are "t15", and at
+        // a four-character floor fwrd16 left a literal `#/tickets/t15` in six
+        // flow steps. identifierLike() still does the real work — a three-letter
+        // route word carries no digit and no separator, so it never qualifies.
+        if (seen.has(part.value) || !identifierLike(part.value))
+            continue;
+        seen.add(part.value);
+        out.push(part);
+    }
+    return out;
+}
+/** Scalar leaves of a JSON read value, as `path` (dot/index joined) + value. */
+export function jsonLeaves(text) {
+    const trimmed = text.trim();
+    if (!(trimmed.startsWith('{') || trimmed.startsWith('[')))
+        return [];
+    let root;
+    try {
+        root = JSON.parse(trimmed);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    const walk = (node, path, depth) => {
+        if (out.length >= MAX_JSON_LEAVES || depth > MAX_JSON_DEPTH)
+            return;
+        if (node !== null && typeof node === 'object') {
+            for (const [k, v] of Object.entries(node))
+                walk(v, path ? `${path}.${k}` : k, depth + 1);
+            return;
+        }
+        if (typeof node !== 'string' && typeof node !== 'number')
+            return;
+        const value = String(node);
+        if (value.length > 120 || !identifierLike(value))
+            return;
+        if (!path)
+            return;
+        out.push({ path, value });
+    };
+    walk(root, '', 0);
+    return out;
+}
+//# sourceMappingURL=flow.js.map