decisium 0.0.0-stage → 0.1.2

package/dist/check.js

@@ -0,0 +1,253 @@
+import { AREA_MISSING, AREA_PAGE, gate, GATE_MARGIN, GATE_TOP, plausible, named, fmt } from "./decision.js";
+import { assertableText } from "./observation.js";
+// A space before closing punctuation is dropped: snapshots join text nodes with one ("cart !").
+const norm = (s) => s.toLowerCase().replace(/\s+/g, " ").replace(/ ([!?.,;:)])/g, "$1").trim();
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+ * Whole-word, case/space-insensitive containment: "1 week" must not match "11 weeks". Only a neighbour of the same kind
+ * (letter next to letter, digit next to digit) joins words: snapshots drop line breaks ("1815<br>London" -> "1815London").
+ */
+export function containsValue(actual, expected) {
+    const e = norm(expected);
+    const kind = (c = "") => /\p{L}/u.test(c) ? "\\p{L}" : /\p{N}/u.test(c) ? "\\p{N}" : undefined;
+    const [before, after] = [kind(e[0]), kind(e.at(-1))];
+    return new RegExp(`${before ? `(?<!${before})` : ""}${escape(e)}${after ? `(?!${after})` : ""}`, "u").test(norm(actual));
+}
+const STATE_FLAG = {
+    disabled: ["disabled", true], enabled: ["disabled", false],
+    checked: ["checked", true], unchecked: ["checked", false],
+    expanded: ["expanded", true], collapsed: ["expanded", false],
+    selected: ["selected", true], unselected: ["selected", false],
+    pressed: ["pressed", true], unpressed: ["pressed", false],
+};
+// Roles that can carry each ARIA state (WAI-ARIA 1.2). `disabled` applies to any control, so it has no entry.
+const STATE_ROLES = {
+    checked: ["checkbox", "radio", "switch", "menuitemcheckbox", "menuitemradio", "option", "treeitem"],
+    selected: ["option", "tab", "row", "gridcell", "columnheader", "rowheader", "treeitem"],
+    expanded: ["button", "combobox", "link", "menuitem", "tab", "treeitem", "row", "gridcell", "rowheader", "checkbox", "listbox", "application"],
+    pressed: ["button"],
+};
+const JUDGED_THRESHOLD = 0.8;
+/**
+ * A pass resting on an answer less than this above its gate is marginal (task 0027). On the corpus (29 passes) it
+ * flags 6: the answers that agree carry 0.69-0.89 together.
+ */
+const MARGINAL_BAND = 0.1;
+/** Readings that agree (`agreeing`) carry the pass together; under gate + band they are a marginal answer. */
+const weakMass = (what, pick, agreeing, obs) => agreeing.reduce((s, k) => s + (pick.probabilities[k] ?? 0), 0) < GATE_TOP + MARGINAL_BAND ? [`${what}: ${named(pick, obs)}`] : [];
+/** A gated answer (state, recall) that cleared its gate by less than the band. */
+const weakGate = (what, pick) => gate(pick, GATE_TOP + MARGINAL_BAND, GATE_MARGIN + MARGINAL_BAND) ? [] : [`${what}: ${named(pick)}`];
+/** All applicable readings must agree; only a pass carries their combined confidence warnings. */
+function agreement(readings, disagreement, marginal) {
+    const first = readings[0];
+    if (!first)
+        return { outcome: "UNVERIFIABLE", reason: "no plausible reading of the check" };
+    if (readings.some(r => r.outcome !== first.outcome))
+        return { outcome: "AMBIGUOUS", reason: disagreement };
+    if (first.outcome !== "PASSED")
+        return first;
+    return { ...first, marginal: [...new Set([...marginal, ...readings.flatMap(r => r.marginal ?? [])])] };
+}
+const areaDisagreement = (a, obs) => `Jev is unsure where the check says to look, and the candidates give different answers: ${named(a.area, obs)}`;
+/** Pass/fail for one kind of check, decided by code from the elements Jev identified. */
+function evaluate(kind, a, obs, values, log) {
+    if (kind === "fuzzy") {
+        if (a.judged === undefined)
+            return { outcome: "UNVERIFIABLE", reason: "this is a subjective check that code cannot compare; rerun with --judged to let Jev judge it" };
+        log(`  Judged: p=${a.judged.toFixed(2)}`);
+        if (a.judged >= JUDGED_THRESHOLD)
+            return { outcome: "JUDGED_PASSED", reason: `p=${a.judged.toFixed(2)}` };
+        if (a.judged <= 1 - JUDGED_THRESHOLD)
+            return { outcome: "JUDGED_FAILED", reason: `p=${a.judged.toFixed(2)}` };
+        return { outcome: "AMBIGUOUS", reason: `Jev is unsure whether the page satisfies the check (${Math.round(a.judged * 100)}% yes)` };
+    }
+    if (kind === "presence" || kind === "absence") {
+        if (!values.length)
+            return { outcome: "UNVERIFIABLE", reason: "the check quotes no text to look for (e.g. \"Winter Sale\" should appear)" };
+        // Jev names the area the check is scoped to; code looks for the quoted text inside it. As with kinds, every
+        // plausible area is checked and they must agree. A text that is nowhere on the page is decided by code alone.
+        // Presence needs every quoted text; absence fails on any one of them, so "any shown" is what it must look for.
+        const has = (text) => kind === "absence"
+            ? values.some(v => containsValue(text, v))
+            : values.every(v => containsValue(text, v));
+        const text = values.map(v => `"${v}"`).join(kind === "absence" ? " or " : " and ");
+        const reading = (found, where) => found === (kind === "presence")
+            ? { outcome: "PASSED" }
+            : { outcome: "ASSERTION_FAILED", reason: `${text} ${found ? "is shown" : "is not shown"} in ${where}${found ? ", expected it to be absent" : ""}` };
+        // Text nowhere on the page rests on no area answer.
+        if (!has(obs.pageText))
+            return reading(false, "the page");
+        log(`  Area: ${fmt(a.area)}`);
+        const areas = plausible(a.area);
+        const readings = [];
+        for (const ref of areas) {
+            if (ref === AREA_PAGE)
+                readings.push(reading(true, "the page"));
+            else if (ref === AREA_MISSING)
+                readings.push(reading(false, "the area the check names (that area is not on this screen)"));
+            else {
+                const el = obs.areas.find(e => e.ref === ref);
+                if (!el)
+                    return { outcome: "ELEMENT_NOT_FOUND", reason: `Jev chose an area that is no longer on the page (${ref})` };
+                readings.push(reading(has(el.text), el.line));
+            }
+        }
+        // The old area comparison reported the last agreeing area.
+        return agreement(readings.reverse(), areaDisagreement(a, obs), weakMass("area", a.area, areas, obs));
+    }
+    // State and value checks read one element. Jev may be unsure which, e.g. a repository name shown in the breadcrumb
+    // and the title: as with kinds and areas, every plausible element is checked and they must agree.
+    if (kind === "state") {
+        log(`  Subject: ${fmt(a.subject)}  State: ${fmt(a.state)}`);
+        if (!gate(a.state))
+            return { outcome: "AMBIGUOUS", reason: `Jev is unsure which state the check means: ${named(a.state)}` };
+    }
+    else {
+        if (values.length !== 1)
+            return { outcome: "UNVERIFIABLE", reason: "a value check needs exactly one quoted expected value (e.g. the status should be \"Draft\")" };
+        log(`  Subject: ${fmt(a.subject)}`);
+    }
+    // A reading that cannot apply (a link's text is its label, a link cannot be checked) carries no evidence.
+    const subjects = plausible(a.subject);
+    const all = subjects.map(ref => (kind === "state" ? stateOf : valueOf)(ref, a, obs, values, log));
+    const readings = all.filter(r => !r.inapplicable);
+    // No subject applies: unchanged from a single reading. A value check on a label stays a final UNVERIFIABLE, so a
+    // plausible presence reading of the same check cannot pass on the label's text.
+    if (!readings.length)
+        return kind === "value" ? { outcome: all[0].outcome, reason: all[0].reason } : all[0];
+    const marginal = weakMass("subject", a.subject, subjects.filter((_, i) => !all[i].inapplicable), obs);
+    const what = kind === "state" ? "control" : "element";
+    return agreement(readings, `Jev is unsure which ${what} the check is about, and they give different answers: ${named(a.subject, obs)}`, kind === "state" ? [...marginal, ...weakGate("state", a.state)] : marginal);
+}
+const TABLES = new Set(["table", "grid", "treegrid"]);
+const cellText = (c) => (c.name || c.text).trim();
+const within = (el, area) => { for (let p = el; p; p = p.parent)
+    if (p === area)
+        return true; return false; };
+const tableOf = (row) => { for (let p = row.parent; p; p = p.parent)
+    if (TABLES.has(p.role))
+        return p; };
+const isHeader = (row) => !!row.cells?.length && row.cells.every(c => c.role === "columnheader");
+/** Column of `name` among the header's: same text, else the header containing it (a sort arrow, "Quantity ▲"). */
+const column = (header, name) => {
+    const i = header.findIndex(h => norm(h) === norm(name));
+    return i >= 0 ? i : header.findIndex(h => containsValue(h, name));
+};
+/**
+ * A check's table (header row, then expected rows) against the page rows in each plausible area: every expected row
+ * must match a page row by column header (extra page rows allowed, order free); `exact`: the same rows in this order.
+ */
+function matchRows(a, obs, table, exact, log) {
+    log(`  Area: ${fmt(a.area)}`);
+    const areas = plausible(a.area);
+    const verdicts = [];
+    for (const ref of areas) {
+        if (ref === AREA_MISSING) {
+            verdicts.push({ outcome: "ASSERTION_FAILED", reason: "the table the check names is not on this screen" });
+            continue;
+        }
+        const area = obs.areas.find(e => e.ref === ref);
+        if (ref !== AREA_PAGE && !area)
+            return { outcome: "ELEMENT_NOT_FOUND", reason: `Jev chose an area that is no longer on the page (${ref})` };
+        verdicts.push(rowsIn(area, obs, table, exact));
+    }
+    return agreement(verdicts, areaDisagreement(a, obs), weakMass("area", a.area, areas, obs));
+}
+/** `area` undefined: the whole page. */
+function rowsIn(area, obs, table, exact) {
+    const [names, ...expected] = table;
+    const where = area ? area.line : "the page";
+    const rows = obs.areas.filter(r => r.role === "row" && r.cells?.length && (!area || within(r, area)));
+    const header = (row) => rows.concat(obs.areas).find(h => h.role === "row" && isHeader(h) && tableOf(h) === tableOf(row))?.cells.map(cellText) ?? [];
+    const data = rows.filter(r => !isHeader(r));
+    if (!data.length)
+        return { outcome: "ASSERTION_FAILED", reason: `${where} shows no table rows` };
+    const noColumn = names.find(n => !data.some(r => column(header(r), n) >= 0));
+    if (noColumn !== undefined)
+        return { outcome: "ASSERTION_FAILED", reason: `the table in ${where} has no column "${noColumn}" (columns: ${[...new Set(data.flatMap(header))].join(", ")})` };
+    const matches = (row, want) => names.every((n, i) => {
+        const cell = row.cells[column(header(row), n)];
+        return cell !== undefined && (want[i] ? containsValue(cellText(cell), want[i]) : !cellText(cell)); // an empty expected cell is an empty cell
+    });
+    const show = (want) => names.map((n, i) => `${n}=${want[i]}`).join(", ");
+    const shown = `its rows: ${data.map(r => r.cells.map(cellText).join(" | ")).join("; ")}`;
+    if (exact) {
+        if (data.length === expected.length && expected.every((want, i) => matches(data[i], want)))
+            return { outcome: "PASSED" };
+        return { outcome: "ASSERTION_FAILED", reason: `expected exactly these rows in this order: ${expected.map(show).join("; ")}; ${where} has ${shown}` };
+    }
+    const free = [...data];
+    for (const want of expected) {
+        const i = free.findIndex(r => matches(r, want));
+        if (i < 0)
+            return { outcome: "ASSERTION_FAILED", reason: `expected row ${show(want)} is not in ${where}; ${shown}` };
+        free.splice(i, 1); // each page row matches one expected row
+    }
+    return { outcome: "PASSED" };
+}
+function stateOf(ref, a, obs) {
+    if (ref === "none")
+        return { outcome: "ASSERTION_FAILED", reason: "no element on the page matches what the check describes" };
+    const el = obs.readable.find(e => e.ref === ref);
+    if (!el)
+        return { outcome: "ELEMENT_NOT_FOUND", reason: `Jev chose an element that is no longer on the page (${ref})` };
+    let [flag, on] = STATE_FLAG[a.state.choice];
+    if (flag === "selected" && el.role === "link")
+        flag = "current"; // a navigation link is "selected" via aria-current
+    if (STATE_ROLES[flag] && !STATE_ROLES[flag].includes(el.role)) {
+        return { outcome: "UNVERIFIABLE", reason: `a ${el.role} cannot be ${a.state.choice}`, inapplicable: true };
+    }
+    const has = el.state.split(/\s+/).includes(`[${flag}]`);
+    return has === on ? { outcome: "PASSED" } : { outcome: "ASSERTION_FAILED", reason: `expected ${el.line} to be ${a.state.choice}, but it is not` };
+}
+function valueOf(ref, _a, obs, values, log) {
+    if (ref === "none")
+        return { outcome: "ASSERTION_FAILED", reason: "no element on the page shows what the check describes" };
+    const el = obs.readable.find(e => e.ref === ref);
+    if (!el)
+        return { outcome: "ELEMENT_NOT_FOUND", reason: `Jev chose an element that is no longer on the page (${ref})` };
+    const actual = assertableText(el);
+    if (actual === undefined)
+        return { outcome: "UNVERIFIABLE", reason: `${el.line} has no text to compare (only a label)`, inapplicable: true };
+    log(`  Compare: "${values[0]}" in "${actual}"`);
+    if (el.role === "download" && el.state === "[empty]")
+        return { outcome: "ASSERTION_FAILED", reason: `the downloaded file is empty (0 bytes)` };
+    // URL paths are case-sensitive and not words: plain substring.
+    if (el.role === "url")
+        return actual.includes(values[0]) ? { outcome: "PASSED" } : { outcome: "ASSERTION_FAILED", reason: `expected the URL to contain "${values[0]}", but it is "${actual}"` };
+    if (containsValue(actual, values[0]))
+        return { outcome: "PASSED" };
+    // The subject shows part of the quoted text (prose split across a link and bare text, "<b>2</b> items left"):
+    // the rest can only be in the container holding it, so read that one, not anywhere on the page.
+    const host = el.parent;
+    if (actual && host && containsValue(values[0], actual)) {
+        log(`  Compare: "${values[0]}" in "${host.text.trim()}" (${host.line}, holding ${el.line})`);
+        if (containsValue(host.text, values[0]))
+            return { outcome: "PASSED" };
+    }
+    return { outcome: "ASSERTION_FAILED", reason: `expected "${values[0]}", but ${el.role}${el.name && el.name !== actual ? ` "${el.name}"` : ""} shows "${actual}"` };
+}
+/** Pure Check verdict; diagnostics are returned for the runner to log, never emitted here. */
+export function verdict(a, obs, expectation) {
+    const details = [`  Kind: ${fmt(a.kind)}`];
+    const result = check(a, obs, expectation, line => { details.push(line); });
+    if (result.outcome === "PASSED" && expectation.recall) {
+        result.marginal = [...weakGate("earlier value", expectation.recall), ...result.marginal ?? []];
+    }
+    return { ...result, details };
+}
+function check(a, obs, { values, table, list = false, exact = false }, log) {
+    // Gate on the result, not the label: evaluate every plausible kind (most likely first, until they
+    // cover the gate's confidence) and accept only if they all reach the same outcome.
+    // A reading that does not apply to the element Jev picked (e.g. "selected" on a combobox) carries no evidence.
+    // A table's shape decides the kind, except that Jev's absence reading must not be lost ("should not show:").
+    const negated = plausible(a.kind).includes("absence");
+    if (table && !list && negated)
+        return { outcome: "UNVERIFIABLE", reason: "a check that table rows are not shown is not supported; check each row's absence in its own Step" };
+    const kinds = !table ? plausible(a.kind) : list ? [...new Set(plausible(a.kind).map(k => k === "absence" ? k : "presence"))] : ["rows"];
+    const all = kinds.map(kind => ({ kind, ...kind === "rows" ? matchRows(a, obs, table, exact, log) : evaluate(kind, a, obs, values, log) }));
+    const results = all.filter(r => !r.inapplicable);
+    if (!results.length)
+        return { outcome: "UNVERIFIABLE", reason: all.map(r => r.reason).join("; ") };
+    return agreement(results, `Jev could not tell what kind of check this is, and the readings disagree: ${results.map(r => `as a ${r.kind} check it is ${r.outcome}${r.reason ? ` (${r.reason})` : ""}`).join("; ")}`, table ? [] : weakMass("kind", a.kind, results.map(r => r.kind)));
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+import { loadConfiguration, runCucumber } from "@cucumber/cucumber/api";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { availableParallelism, tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { RECORD_MODES } from "./cassette.js";
+import { parseFeature, stepFeature } from "./feature.js";
+import { applyOptions, ourStdout } from "./options.js";
+import { doctor } from "./doctor.js";
+import { lint } from "./lint.js";
+import { INFRA_MARKER, RunDir } from "./trace.js";
+import { MODEL } from "./jev.js";
+// ".ts" from source, ".js" from the built package in dist/.
+const EXT = import.meta.url.slice(-3);
+const USAGE = `Usage:
+  decisium step "<step>" --url <url|file> [--headed] [--judged] [--strict] [-v] [--debug]
+  decisium run <file.feature[:line]>... [--url <url|file>] [--headed] [--judged] [--strict] [--record <mode>]
+                [--parallel <n|auto>] [--format <name[:path]>] [--import <file>] [-p <profile>] [--no-agent-report] [-v] [--debug]
+  decisium doctor [<file.feature>...]
+  decisium lint <file.feature>...
+
+The start URL comes from --url or an @url:<url> tag (scenario tags override feature tags). file.feature:line runs only
+the scenario (or Examples row) at that line.
+--record (run only): what each Step resolved to (element role, name, container, position; values) is recorded in
+  <file>.cassette.json and replayed without Jev while exactly one element still matches it.
+  new (default): replay, resolve new or no-longer-matching Steps live and write them back (reported as healed);
+  none: replay only, a missing or broken resolution fails as UI_CHANGED (CI); all: resolve everything live, rewrite.
+--parallel <n|auto>: worker processes. Features run side by side, a feature's scenarios one after another. Only for
+  features that do not share app state. auto: min(CPUs, 4) when calling Jev, every CPU with --record none. Default 0.
+doctor: checks Node, Chromium and TYPESAFE_API_KEY (one tiny Jev call); given features, also opens
+  every start URL.
+lint: no browser, no Jev. Per Step: its kind, the quoted values, keys, secret placeholders, and warnings for wordings
+  docs/cookbook.md shows failing.
+Configuration is cucumber-js's: run loads your cucumber.{js,mjs,cjs,json,yaml} (and -p profiles); --format, --import and
+  -p (repeatable) are cucumber's flags, added to it. --format name[:path]: cucumber's junit, json, html, message or any
+  formatter package, e.g. --format junit:junit.xml or --format cucumberjs-qase-reporter:/dev/null. Only one formatter may
+  write to stdout: one configured without a path takes it, else Decisium's console output does.
+--import: your own cucumber step definitions or hooks. A line one of them matches runs it, not Jev; the World gives them
+  this.page (the current tab) and this.context (Playwright). See docs/cookbook.md.
+Options in the configuration: worldParameters: { decisium: { url, record, headed, judged, strict, verbose, debug,
+  agentReport } }; flags and DECISIUM_* env (DECISIUM_URL, DECISIUM_RECORD, DECISIUM_STRICT=1, ...) override them.
+-v prints every Observation and Jev answer (always saved to runs/<timestamp>/log.txt); --debug shows stack traces.
+--judged lets Jev judge fuzzy checks; they report JUDGED_PASSED/JUDGED_FAILED, never PASSED.
+--strict: a check that passes on a barely-confident Jev answer (shown as "marginal pass") fails as AMBIGUOUS.
+
+Each run writes runs/<timestamp>/: trace.jsonl (Observations, Jev answers, actions, outcomes) and per failed scenario a
+screenshot per Turn, playwright-trace.zip, console-errors.txt and ui.txt (the page text). Passed scenarios keep none.
+A run with a failure writes report.md: every failure with Jev's answers, the page text around it and a rerun command,
+for a coding agent (--no-agent-report: off).
+
+Runs inside cucumber-js: raw \`npx cucumber-js <file>\` works too with
+import: ["node_modules/decisium/dist/steps.js"] and format: ["decisium/formatter"] in its cucumber.mjs.
+
+Secrets: write "$NAME" in a Step's quotes (e.g. with password "$SAUCE_PASSWORD"): Jev, logs, trace and cassette see only
+the token; the value comes from the environment (or .env) and is typed into the page. Wherever the page shows it, it is
+masked back to the token. A scenario that typed one keeps no Playwright trace (it would store the value). A value
+written literally in a Step is sent to Jev, recorded in the cassette and written to log.txt.
+
+Exit codes: 0 passed, 1 a scenario failed, 2 configuration/infrastructure error.`;
+async function main() {
+    const feature = (path) => path.replace(/:\d+$/, ""); // file.feature:line -> file.feature
+    if (existsSync(".env"))
+        process.loadEnvFile(".env"); // TYPESAFE_API_KEY; never logged
+    const { positionals, values } = parseArgs({
+        allowPositionals: true,
+        allowNegative: true,
+        // No defaults: an option not given falls back to DECISIUM_* env, then worldParameters.decisium (src/options.ts).
+        options: { url: { type: "string" }, headed: { type: "boolean" }, judged: { type: "boolean" },
+            strict: { type: "boolean" }, "agent-report": { type: "boolean" }, record: { type: "string" }, parallel: { type: "string" },
+            format: { type: "string", multiple: true, default: [] }, import: { type: "string", multiple: true, default: [] },
+            profile: { type: "string", short: "p", multiple: true, default: [] },
+            verbose: { type: "boolean", short: "v" }, debug: { type: "boolean" } },
+    });
+    const env = process.env;
+    const flag = (on) => (on === undefined ? undefined : on ? "1" : "0");
+    for (const [name, value] of Object.entries({ URL: values.url, RECORD: values.record, HEADED: flag(values.headed), JUDGED: flag(values.judged),
+        STRICT: flag(values.strict), NO_AGENT_REPORT: flag(values["agent-report"] === undefined ? undefined : !values["agent-report"]),
+        VERBOSE: flag(values.verbose), DEBUG: flag(values.debug) }))
+        if (value !== undefined)
+            env[`DECISIUM_${name}`] = value;
+    const [cmd, arg] = positionals;
+    if (cmd === "doctor")
+        return doctor(positionals.slice(1));
+    if (cmd === "lint" && arg) {
+        try {
+            console.log(positionals.slice(1).map(f => lint(f)).join("\n\n"));
+            return 0;
+        }
+        catch (err) {
+            console.error(err.message);
+            return 2;
+        }
+    }
+    let files;
+    let scenarios;
+    try {
+        if (cmd === "step" && arg) {
+            const file = join(mkdtempSync(join(tmpdir(), "decisium-")), "step.feature");
+            writeFileSync(file, stepFeature(arg));
+            files = [file];
+            const dir = dirname(file);
+            process.on("exit", () => rmSync(dir, { recursive: true, force: true })); // every exit path, early returns included
+        }
+        else if (cmd === "run" && arg) {
+            files = positionals.slice(1);
+            const missing = files.find(f => !existsSync(feature(f)));
+            if (missing) {
+                console.error(`File not found: ${missing}`);
+                return 2;
+            }
+        }
+        else {
+            console.error(USAGE);
+            return 2;
+        }
+        scenarios = files.flatMap(f => parseFeature(readFileSync(feature(f), "utf8"), feature(f))); // syntax and unsupported arguments: one line, before running
+    }
+    catch (err) {
+        console.error(err.message);
+        return 2;
+    }
+    const parallelSet = values.parallel === "auto" ? -1 : Number(values.parallel ?? 0); // -1: auto, resolved once --record is known
+    if (!Number.isInteger(parallelSet) || parallelSet < -1) {
+        console.error(`--parallel must be a whole number or auto\n\n${USAGE}`);
+        return 2;
+    }
+    const here = (f) => fileURLToPath(import.meta.resolve(f));
+    // The client's cucumber configuration and profiles, plus ours; `step` runs one line, so none of the client's features.
+    const { useConfiguration, runConfiguration } = await loadConfiguration({ file: cmd === "step" ? false : undefined, profiles: values.profile, provided: {
+            paths: files, import: [here(`./steps${EXT}`), ...values.import.map(f => resolve(f))], format: values.format,
+        } });
+    if (ourStdout(useConfiguration.format, runConfiguration.formats.stdout))
+        runConfiguration.formats.stdout = here(`./formatter${EXT}`);
+    try {
+        applyOptions(runConfiguration.runtime.worldParameters?.decisium);
+    }
+    catch (err) {
+        console.error(err.message);
+        return 2;
+    }
+    // Values after the merge: the configuration may set what no flag did.
+    const record = env.DECISIUM_RECORD || "new";
+    if (!RECORD_MODES.includes(record)) {
+        console.error(`--record must be one of ${RECORD_MODES.join(", ")}\n\n${USAGE}`);
+        return 2;
+    }
+    const missingUrl = scenarios.find(s => !(env.DECISIUM_URL || s.url));
+    if (missingUrl) {
+        console.error(`No start URL for "${missingUrl.name}": pass --url or add an @url:<url> tag.\n\n${USAGE}`);
+        return 2;
+    }
+    if (!env.TYPESAFE_API_KEY && (cmd === "step" || record !== "none" || env.DECISIUM_JUDGED === "1")) {
+        console.error("TYPESAFE_API_KEY is not set.");
+        return 2;
+    }
+    // Opt-in: features sharing one stateful app (campaign-manager) break each other's state when run side by side.
+    // Workers only pay off across features (a feature's scenarios share its cassette and run in sequence).
+    if (values.parallel !== undefined)
+        runConfiguration.runtime.parallel = files.length < 2 ? 0
+            : parallelSet === -1 ? Math.min(availableParallelism(), record === "none" ? Infinity : 4) : parallelSet;
+    const run = new RunDir(); // shared by every worker
+    Object.assign(env, { DECISIUM_STEP: cmd === "step" ? "1" : "", DECISIUM_RUN_DIR: run.path });
+    console.log(`Model: ${MODEL}\nRun directory: ${run.path}`);
+    const { success } = await runCucumber(runConfiguration);
+    run.done();
+    console.log(`\nRun directory: ${run.path} (log.txt has the full decision log)`);
+    // steps.ts marks an infrastructure error in the run directory (it may have happened in a worker).
+    return process.exitCode === 2 || existsSync(join(run.path, INFRA_MARKER)) ? 2 : success ? 0 : 1;
+}
+// No process.exit on success paths: a reporter (e.g. Qase's) may finish uploading after cucumber returns.
+main().then(code => { process.exitCode = code; }, err => {
+    console.error(process.env.DECISIUM_DEBUG ? err : `\nError: ${err.message.split("\n")[0]}\nRerun with --debug for details.`);
+    process.exitCode = 2;
+});

package/dist/decision.d.ts

@@ -0,0 +1,124 @@
+import type { Element, Observation } from "./observation.ts";
+export interface Pick {
+    choice: string;
+    probabilities: Record<string, number>;
+}
+export interface TurnAnswer {
+    done: number;
+    target: Pick;
+    /** How to use the target, an ACTIONS key or `press <key>` (task 0065); only the target's capabilities count. Absent: its first. */
+    action?: Pick;
+}
+/** The page itself as a target (task 0065): scrolling it, history, tabs, keys, waiting. */
+export declare const PAGE = "page";
+/** Everything a target can be used for (task 0065, ADR 0005); capabilities() picks a target's own. */
+export declare const ACTIONS: {
+    readonly click: "Click it.";
+    readonly type: "Type a value from `step` into it (an empty value clears it).";
+    readonly select: "Select an option in it.";
+    readonly upload: "Click it to choose a file to upload, one `step` names.";
+    readonly paste: "Paste the copied text into it.";
+    readonly hover: "Only hover over it with the mouse pointer (e.g. to open a menu or show a tooltip).";
+    readonly "double click": "Double-click it (e.g. to edit it inline).";
+    readonly "right click": "Right-click it (e.g. to open its context menu).";
+    readonly drag: "Drag it with the mouse and drop it onto another element (e.g. to reorder it or move it to another list).";
+    readonly "scroll down": "Scroll it down: show or load more of its content further down (the page: the needed element may load further down).";
+    readonly "scroll up": "Scroll it up: show or load more of its content further up.";
+    readonly wait: "Wait: the page is still loading what is needed.";
+    readonly back: "Go back to the previous page in the browser history.";
+    readonly forward: "Go forward in the browser history.";
+    readonly reload: "Reload the page.";
+    readonly "close tab": "Close this browser tab and return to the previous one.";
+    readonly "switch tab": "Switch to the previous browser tab, keeping this one open.";
+    readonly enter: "Press Enter in it, to submit what was typed (e.g. run a search).";
+};
+/**
+ * What `target` can be used for. Elements: their role's verb (a typeable field also takes paste, a clickable one an
+ * upload), click-like gestures on every target (no DOM evidence for them, task 0064), drag/scroll only with the fact.
+ * The page: scroll, wait, history; tabs while more than one is open; keys the Step names (`keys`, task 0039). Enter:
+ * the focused text field's.
+ */
+export declare function capabilities(target: Element | typeof PAGE, obs: Observation, keys?: string[]): string[];
+/** Choice text of an action: ACTIONS, or a key the Step names. */
+export declare const describeAction: (a: string) => "Click it to choose a file to upload, one `step` names." | "Click it." | "Close this browser tab and return to the previous one." | "Double-click it (e.g. to edit it inline)." | "Drag it with the mouse and drop it onto another element (e.g. to reorder it or move it to another list)." | "Go back to the previous page in the browser history." | "Go forward in the browser history." | "Only hover over it with the mouse pointer (e.g. to open a menu or show a tooltip)." | "Paste the copied text into it." | "Press Enter in it, to submit what was typed (e.g. run a search)." | "Reload the page." | "Right-click it (e.g. to open its context menu)." | "Scroll it down: show or load more of its content further down (the page: the needed element may load further down)." | "Scroll it up: show or load more of its content further up." | "Select an option in it." | "Switch to the previous browser tab, keeping this one open." | "Type a value from `step` into it (an empty value clears it)." | "Wait: the page is still loading what is needed.";
+/**
+ * Equivalent targets sum their confidence before the gate (task 0065, 0057): links with the same name and URL lead to
+ * the same page (Wikipedia's two `Deutsch` links, 42% / 38%). The first keeps the sum. Buttons never: their handlers
+ * may differ.
+ */
+export declare function grouped(p: Pick, obs: Observation): Pick;
+export declare const ASSERTION_KINDS: {
+    readonly value: "Checks that some element shows a specific text or value.";
+    readonly presence: "Checks that something is shown or exists on the page.";
+    readonly absence: "Checks that something is not shown or does not exist on the page.";
+    readonly state: "Checks whether a control is disabled, enabled, checked, expanded, selected or pressed.";
+    readonly fuzzy: "A subjective or holistic check that none of the other kinds can express.";
+};
+/** State labels Jev can pick; code reads the matching snapshot flag. */
+export declare const STATES: {
+    readonly disabled: "disabled";
+    readonly enabled: "enabled (not disabled)";
+    readonly checked: "checked";
+    readonly unchecked: "not checked";
+    readonly expanded: "expanded / open";
+    readonly collapsed: "collapsed / closed";
+    readonly selected: "selected";
+    readonly unselected: "not selected";
+    readonly pressed: "pressed / toggled on";
+    readonly unpressed: "not pressed / toggled off";
+};
+export interface Assessment {
+    kind: Pick;
+    subject: Pick;
+    area: Pick;
+    state: Pick;
+    judged?: number;
+}
+export declare const AREA_PAGE = "page";
+export declare const AREA_MISSING = "missing";
+/** A Jev answer for people: element refs replaced by the element, top 3 as percentages. */
+export declare const named: (p: Pick, obs?: Observation) => string;
+export declare const fmt: (p: Pick) => string;
+/** The seam to the decision model: Jev implements it (jev.ts); tests use a scripted fake. */
+export interface Decider {
+    /** `recent`: this Step's actions so far, oldest first, e.g. `CLICK combobox "Activation period"`. */
+    /** `attempt`: done means the user performed the actions, whether or not the app accepted them. */
+    /** `keys`: the Named keys the Step's text names (readStep), offered as the page's `press <key>` actions. */
+    turn(step: string, obs: Observation, recent: string[], attempt?: boolean, keys?: string[]): Promise<TurnAnswer>;
+    value(step: string, obs: Observation, el: Element, candidates: string[]): Promise<Pick>;
+    /** Drag: the readable element or area to drop `source` onto, or "none" (task 0045). */
+    drop(step: string, obs: Observation, source: Element): Promise<Pick>;
+    /** Assertion steps: what kind of check, and which element it is about. Code decides pass/fail. */
+    assess(step: string, obs: Observation, judged: boolean): Promise<Assessment>;
+    /** Memory: which value from an earlier Step (`earlier`: value -> Step it came from) the check refers to, or "none". */
+    recall(step: string, earlier: Record<string, string>): Promise<Pick>;
+    /** The open browser dialog (`obs.dialog`): "accept", "dismiss", or for a prompt one of the Step's quoted values. */
+    dialog(step: string, obs: Observation, answers: string[]): Promise<Pick>;
+}
+/**
+ * Thrown by a Decider that needs a later Observation (a replayed control not on a still-loading page): the runner
+ * waits for the page to change and asks again, and throws `final` once ASSERT_TIMEOUT_MS has passed.
+ */
+export declare class NotYet extends Error {
+    final: Error;
+    constructor(final: Error);
+}
+/** Confidence gate: act only on a clear, confident top answer. */
+export declare const GATE_TOP = 0.8;
+export declare const GATE_MARGIN = 0.3;
+/**
+ * Which element to act on is gated lower than a check (task 0002): a wrong action fails a later Step loudly,
+ * while a wrong check can pass falsely. Fitted on 26 labelled AMBIGUOUS Turns from the real-site corpus, where
+ * every top answer naming an element was the right one down to 0.47; below 0.1 margin the two answers are a coin flip.
+ */
+export declare const GATE_TARGET_TOP = 0.5;
+export declare const GATE_TARGET_MARGIN = 0.1;
+export declare function gate(pick: Pick, minTop?: number, minMargin?: number): boolean;
+/** Most likely answers first, until together they cover the gate's confidence (cassette.ts stores exactly these). */
+export declare function plausible(pick: Pick): string[];
+/**
+ * `d` with each answer written as a trace event named after its question (turn, value, assess...): the Step (every
+ * question's first argument) and the answer. A question answering plainly needs no code here; a value chosen for a
+ * Secret field is masked, and a dialog answer carries the dialog. Only Decider questions are reached through it.
+ */
+export declare function traced(d: Decider, event: (type: string, data: Record<string, unknown>) => void): Decider;