webrecipe 0.1.0

package/dist/src/usage.js

@@ -0,0 +1,69 @@
+import { createHash } from 'node:crypto';
+import { siteName, intentName } from './local.js';
+import { appendFile, mkdir, readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Local only. No HTML, result contents, cookies or headers. */
+export async function appendUsage(root, event) {
+    const dir = join(root, 'logs');
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    await appendFile(join(dir, `${event.at.slice(0, 10)}.jsonl`), JSON.stringify(event) + '\n', { mode: 0o600 });
+}
+export async function readUsage(root, days) {
+    const dir = join(root, 'logs');
+    const files = await readdir(dir).catch((error) => { if (error.code === 'ENOENT')
+        return []; throw error; });
+    const since = Date.now() - days * 86_400_000;
+    const events = [];
+    let malformed = 0;
+    for (const file of files.filter(f => /^\d{4}-\d{2}-\d{2}\.jsonl$/.test(f)).sort()) {
+        if (file.slice(0, 10) < new Date(since).toISOString().slice(0, 10))
+            continue;
+        for (const line of (await readFile(join(dir, file), 'utf8')).split('\n').filter(Boolean)) {
+            try {
+                const event = JSON.parse(line);
+                if (event.version !== 1 || !['start', 'finish', 'feedback'].includes(event.event) || typeof event.id !== 'string' || !Number.isFinite(Date.parse(event.at)))
+                    throw new Error('invalid record');
+                if (Date.parse(event.at) >= since)
+                    events.push(event);
+            }
+            catch {
+                malformed++;
+            }
+        }
+    }
+    return { events, malformed };
+}
+export function summarizeUsage(events) {
+    const starts = events.filter(e => e.event === 'start');
+    const finishes = events.filter(e => e.event === 'finish');
+    const runs = finishes.filter(e => e.command === 'fetch');
+    const completed = new Set(finishes.map(e => e.id));
+    const times = runs.map(e => Number(e.wallMs)).filter(Number.isFinite).sort((a, b) => a - b);
+    const feedback = new Map(events.filter(e => e.event === 'feedback').map(e => [e.id, e.verdict]));
+    return {
+        started: starts.length, finished: finishes.length,
+        incomplete: starts.filter(e => !completed.has(e.id)).map(e => e.id),
+        measuredCommands: finishes.filter(e => e.meta !== undefined).length,
+        totalRequests: finishes.reduce((sum, e) => sum + Number(e.meta?.networkRequests ?? 0), 0),
+        totalPolitenessWaitMs: finishes.reduce((sum, e) => sum + Number(e.meta?.politenessWaitMs ?? 0), 0),
+        fallbackRuns: runs.filter(e => e.fellBack === true).length,
+        recipeChanges: finishes.filter(e => e.recipeChanged === true).length,
+        runs: runs.length, succeeded: runs.filter(e => e.ok === true).length,
+        failed: runs.filter(e => e.ok === false).length,
+        medianRunWallMs: times.length ? (times[Math.floor((times.length - 1) / 2)] + times[Math.floor(times.length / 2)]) / 2 : null,
+        browserFreeRuns: runs.filter(e => e.ok === true && e.meta?.browserLaunches === 0).length,
+        feedback: { correct: [...feedback.values()].filter(v => v === 'correct').length, wrong: [...feedback.values()].filter(v => v === 'wrong').length },
+        recent: finishes.slice(-10).map(({ id, command, site, intent, ok, wallMs, error }) => ({ id, command, site, intent, ok, wallMs, error })),
+    };
+}
+export async function recipeDigest(root, site, intent) {
+    const path = join(root, 'recipes', siteName(site), `${intentName(intent)}.yaml`);
+    try {
+        return createHash('sha256').update(await readFile(path)).digest('hex');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}

package/dist/src/validator/index.js

@@ -0,0 +1,28 @@
+import { computeFingerprint } from '../recipes/fingerprint.js';
+export function validate(recipe, input) {
+    const reasons = [];
+    if (input.status !== recipe.validation.status) {
+        reasons.push(`status ${input.status} !== expected ${recipe.validation.status}`);
+    }
+    if (input.items.length < recipe.validation.minItems) {
+        reasons.push(`item count ${input.items.length} < minItems ${recipe.validation.minItems}`);
+    }
+    // A real listing mixes in rows the selector was never meant to describe — a
+    // sponsored insert among fifty jobs. Failing on any empty value made one such
+    // row invalidate the whole recipe. What this check is for is a dead selector,
+    // so it fires when the field is missing from most of the result.
+    for (const field of recipe.validation.required) {
+        const missing = input.items.filter((item) => {
+            const value = item[field];
+            return value === null || value === undefined || value === '';
+        });
+        if (missing.length > input.items.length / 2) {
+            reasons.push(`required field "${field}" empty in ${missing.length}/${input.items.length} items`);
+        }
+    }
+    const actual = computeFingerprint(recipe.fingerprint.endpoint, input.payload);
+    if (actual !== recipe.fingerprint.hash) {
+        reasons.push(`fingerprint drift: expected ${recipe.fingerprint.hash}, got ${actual}`);
+    }
+    return { valid: reasons.length === 0, reasons };
+}

package/dist/src/verification/lexical-consistency.js

@@ -0,0 +1,88 @@
+import { tokensOf, visibleText } from './query-honored.js';
+/**
+ * Whether the rows a search returns visibly carry the words that were searched
+ * for, on the taught input and on one that was never taught.
+ *
+ * This exists because `query_honored` passes a site that filters on the query
+ * and then attributes each hit to the wrong record: the input genuinely moves
+ * the answer, which is all those probes can see. What such a site cannot do is
+ * show the query's own words in what it returns.
+ *
+ * Named for the evidence and no wider. Passing says the extracted fields match
+ * the query lexically and kept doing so for a value never taught. It does not
+ * say the results are relevant, that the entities are the right ones, or that a
+ * site matching on synonyms, stems or fields we cannot see is wrong — those
+ * come back untested, because there is nothing here that could tell them from a
+ * site that is broken.
+ */
+export const METHOD = 'active-probe/lexical-consistency-v1';
+/**
+ * Provisional. Chosen before any evidence and deliberately not fitted: tuning
+ * it against six fixtures would produce a number that describes the fixtures.
+ * It moves only on held-out or real-site evidence.
+ */
+export const LEXICAL_MATCH_THRESHOLD = 0.8;
+/** Share of rows carrying any token of `query` in a field the plan extracts. */
+export function lexicalShare(items, query) {
+    const tokens = tokensOf(query);
+    if (tokens.length === 0 || items.length === 0)
+        return null;
+    const hits = items.filter((item) => {
+        const text = visibleText(item);
+        return tokens.some((token) => text.includes(token));
+    }).length;
+    return hits / items.length;
+}
+export function judgeLexicalConsistency(session) {
+    const at = (role) => session.observations.find((o) => o.role === role);
+    const taught = at('taught');
+    if (!taught || taught.items === null) {
+        return { status: 'not_tested', signals: {}, shares: {}, reason: `taught probe unavailable: ${taught?.unavailable ?? 'not issued'}` };
+    }
+    // Stage one asks whether this check applies at all. A site that matches on a
+    // description, a tag or a synonym is answering correctly and would look
+    // identical to one that answers with the wrong records, so the honest report
+    // is that we cannot read it.
+    const taughtShare = lexicalShare(taught.items, session.taughtValue);
+    if (taughtShare === null) {
+        return { status: 'not_tested', signals: {}, shares: {}, reason: 'the taught query has no usable token, or returned nothing' };
+    }
+    const signals = { applicable: taughtShare >= LEXICAL_MATCH_THRESHOLD };
+    const shares = { taught: taughtShare };
+    if (!signals.applicable) {
+        return {
+            status: 'not_tested', signals, shares,
+            reason: `only ${(taughtShare * 100).toFixed(0)}% of the taught result carries the query in a field this plan extracts, so this site does not match on text we can read`,
+        };
+    }
+    const contrast = at('contrast');
+    if (!contrast || contrast.items === null) {
+        return { status: 'not_tested', signals, shares, reason: `contrast probe unavailable: ${contrast?.unavailable ?? 'no contrast token could be built'}` };
+    }
+    const contrastShare = lexicalShare(contrast.items, contrast.value);
+    if (contrastShare === null) {
+        return { status: 'not_tested', signals, shares, reason: `the contrast query "${contrast.value}" returned nothing to read` };
+    }
+    shares.contrast = contrastShare;
+    signals.consistent = contrastShare >= LEXICAL_MATCH_THRESHOLD;
+    if (!signals.consistent) {
+        return {
+            status: 'not_tested', signals, shares,
+            reason: `the taught query is visible in its result but "${contrast.value}" is in only ${(contrastShare * 100).toFixed(0)}% of its own, which one site matching on two different fields would also look like`,
+        };
+    }
+    return { status: 'passed', signals, shares, reason: '' };
+}
+/** Reads the same probes `query_honored` already issued; costs no new request. */
+export function verifyLexicalConsistency(session) {
+    const verdict = judgeLexicalConsistency(session);
+    return {
+        status: verdict.status,
+        at: new Date().toISOString(),
+        method: METHOD,
+        parameter: session.parameter,
+        shares: verdict.shares,
+        signals: verdict.signals,
+        ...(verdict.reason === '' ? {} : { reason: verdict.reason }),
+    };
+}

package/dist/src/verification/pagination-honored.js

@@ -0,0 +1,110 @@
+import { asRecords, overlapShare, sameSet } from './probes.js';
+/**
+ * Whether changing the page input actually selects a different window, and
+ * whether the recipe selects the same window the page itself does.
+ *
+ * Narrower than pagination being correct. Nothing here shows that every record
+ * can be reached, that none is served twice, that ordering holds across the
+ * boundary, or that the last page is where the site says it is. Those are
+ * separate questions and would need separate evidence.
+ *
+ * Required exactly when the plan templates `page`, which is an authoring act
+ * rather than a property of the site: templating it makes `run --page N` a
+ * supported operation, and a task is asked to be right about what it supports.
+ */
+export const METHOD = 'active-probe/pagination-v1';
+/**
+ * A neighbour that probably exists, rather than the one after.
+ *
+ * Probing page + 1 from a task taught on the last page would come back empty
+ * and give up on a site that paginates perfectly well. What has to be shown is
+ * that changing the input selects a different window, and the page before does
+ * that as well as the page after.
+ */
+export function alternatePage(taught) {
+    return taught <= 1 ? 2 : taught - 1;
+}
+export function judgePagination(session) {
+    const at = (role) => session.observations.find((o) => o.role === role);
+    const taught = at('taught');
+    const repeat = at('repeat');
+    const alternate = at('alternate');
+    const signals = {};
+    const shares = {};
+    for (const [role, probe] of [['taught', taught], ['repeat', repeat]]) {
+        if (!probe)
+            return { status: 'not_tested', signals, shares, reason: `no ${role} probe was issued` };
+        if (probe.items === null)
+            return { status: 'not_tested', signals, shares, reason: `${role} probe unavailable: ${probe.unavailable ?? 'unknown'}` };
+    }
+    if (taught.items.length === 0) {
+        return { status: 'not_tested', signals, shares, reason: 'the taught page returned nothing to compare against' };
+    }
+    // Volatility first: on a site whose answer changes between two identical
+    // requests, comparing one page against another proves nothing either way.
+    signals.stable = sameSet(taught.items, repeat.items);
+    if (!signals.stable) {
+        return { status: 'not_tested', signals, shares, reason: 'two identical requests returned different results; one page cannot be compared against another here' };
+    }
+    if (!alternate)
+        return { status: 'not_tested', signals, shares, reason: 'no alternate page probe was issued' };
+    if (alternate.items === null) {
+        return { status: 'not_tested', signals, shares, reason: `alternate page probe unavailable: ${alternate.unavailable ?? 'unknown'}` };
+    }
+    // An empty neighbour is what a real last page looks like. Never a failure.
+    if (alternate.items.length === 0) {
+        return { status: 'not_tested', signals, shares, reason: `page ${session.alternatePage} came back empty, which a last page also does` };
+    }
+    shares.overlap = overlapShare(taught.items, alternate.items);
+    signals.moved = !sameSet(taught.items, alternate.items);
+    if (!signals.moved) {
+        // The recipe returned the taught page again. That is a broken page control
+        // only if the page itself moves; if the browser sees the same rows too,
+        // this is a site that clamps or ignores the parameter for everyone, and
+        // from outside that is indistinguishable from a site with one page.
+        if (session.browserTaught === null || session.browserAlternate === null) {
+            return { status: 'not_tested', signals, shares, reason: `page ${session.alternatePage} returned the taught page again, and no browser reference was available to say whether the page itself moves` };
+        }
+        if (sameSet(session.browserTaught, session.browserAlternate)) {
+            return { status: 'not_tested', signals, shares, reason: `page ${session.alternatePage} returned the taught page again in the browser as well, so this site either clamps the page or has only one` };
+        }
+        return { status: 'failed', signals, shares, reason: `page ${session.alternatePage} returned the taught page again while the browser moved to a different one, so the recipe's page control does nothing` };
+    }
+    if (session.browserAlternate === null) {
+        return { status: 'not_tested', signals, shares, reason: 'the browser reference observation could not be taken' };
+    }
+    signals.agreed = sameSet(alternate.items, session.browserAlternate);
+    if (!signals.agreed) {
+        return { status: 'not_tested', signals, shares, reason: `on page ${session.alternatePage}, an input never taught, the recipe and the browser saw different items` };
+    }
+    return { status: 'passed', signals, shares, reason: '' };
+}
+export async function runPaginationProbes(probes, baseline, parameter = 'page') {
+    const taughtPage = Number(baseline.input[parameter] ?? 1);
+    const other = alternatePage(taughtPage);
+    const alternate = await probes.http('alternate', String(other), { ...baseline.input, [parameter]: other });
+    // The baseline was labelled with whichever input the first check varied, so
+    // relabel it here; evidence naming a query where it means a page is evidence
+    // nobody can read.
+    const atTaughtPage = (o) => ({ ...o, value: String(taughtPage) });
+    const observations = [atTaughtPage(baseline.taught), atTaughtPage(baseline.repeat), alternate];
+    // Both branches of the verdict need it, and neither an empty neighbour nor a
+    // declined probe does, so the launch waits until it can change the answer.
+    const worthBrowsing = alternate.items !== null && alternate.items.length > 0
+        && baseline.taught.items !== null && baseline.taught.items.length > 0;
+    const browserAlternate = worthBrowsing ? await probes.browser({ ...baseline.input, [parameter]: other }) : null;
+    return { parameter, taughtPage, alternatePage: other, observations, browserTaught: baseline.browserTaught, browserAlternate };
+}
+export function verifyPaginationHonored(session) {
+    const verdict = judgePagination(session);
+    return {
+        status: verdict.status,
+        at: new Date().toISOString(),
+        method: METHOD,
+        parameter: session.parameter,
+        probes: asRecords(session.observations),
+        signals: verdict.signals,
+        ...(verdict.shares.overlap === undefined ? {} : { shares: verdict.shares }),
+        ...(verdict.reason === '' ? {} : { reason: verdict.reason }),
+    };
+}

package/dist/src/verification/probes.js

@@ -0,0 +1,98 @@
+import { HttpHtmlStrategy } from '../executor/strategies/http-html.js';
+import { HttpJsonStrategy } from '../executor/strategies/http-json.js';
+import { browserItemsOf } from '../compiler/verify.js';
+import { record } from '../recorder/index.js';
+/** The baseline pair, plus two probes each for the query checks and one for pagination. */
+export const HTTP_PROBE_BUDGET = 5;
+/** Statuses that mean the site declined, which is never a semantic verdict. */
+const BLOCK_STATUSES = new Set([401, 403, 429, 503]);
+/**
+ * Drives the strategies directly rather than through `Executor`, which falls
+ * back to a browser and re-learns on failure: a probe routed through it would
+ * measure whatever managed to answer instead of the recipe being judged.
+ * Writes nothing to the registry or the plan.
+ */
+export class Probes {
+    ctx;
+    spent = 0;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    get strategy() {
+        return this.ctx.recipe.output.type === 'json'
+            ? new HttpJsonStrategy(this.ctx.net, this.ctx.sites)
+            : new HttpHtmlStrategy(this.ctx.net, this.ctx.sites);
+    }
+    /** One request, never retried by us; the budget is what stops a storm. */
+    async http(role, value, input) {
+        if (this.spent >= HTTP_PROBE_BUDGET)
+            return { role, value, items: null, unavailable: 'probe budget spent' };
+        this.spent += 1;
+        try {
+            const result = await this.strategy.execute(this.ctx.recipe, { id: `probe-${role}`, site: this.ctx.site, intent: this.ctx.intent, input });
+            const status = result.status;
+            if (status !== undefined && BLOCK_STATUSES.has(status))
+                return { role, value, items: null, unavailable: `site declined with ${status}` };
+            if (status !== undefined && status !== this.ctx.recipe.validation.status)
+                return { role, value, items: null, unavailable: `unexpected status ${status}` };
+            return { role, value, items: result.items };
+        }
+        catch (error) {
+            return { role, value, items: null, unavailable: error instanceof Error ? error.message : String(error) };
+        }
+    }
+    /**
+     * A second reading of the same page, not a statement of what is true. The
+     * browser can be wrong in its own way, which is why the benchmark's oracle
+     * has to stay a separate thing.
+     */
+    async browser(input) {
+        const task = { id: 'probe-reference', site: this.ctx.site, intent: this.ctx.intent, input };
+        let trace;
+        try {
+            trace = await record(this.ctx.browserPlan, task, this.ctx.sites);
+            return browserItemsOf(trace, this.ctx.browserPlan);
+        }
+        catch {
+            // A browser that could not run leaves a check untested, never failed.
+            return null;
+        }
+        finally {
+            await trace?.dispose?.();
+        }
+    }
+}
+/**
+ * The taught input, asked twice.
+ *
+ * Twice because a site whose answer changes between two identical requests
+ * cannot be judged by comparing sets, in either direction, and every check
+ * below rests on that comparison.
+ */
+export async function runBaseline(probes, input, parameter, browserTaught) {
+    const value = String(input[parameter] ?? '');
+    return {
+        input,
+        taught: await probes.http('taught', value, input),
+        repeat: await probes.http('repeat', value, input),
+        browserTaught,
+    };
+}
+const identity = (item) => item.url !== undefined && item.url !== null && item.url !== ''
+    ? `url:${String(item.url)}`
+    : JSON.stringify(Object.entries(item).sort(([a], [b]) => a.localeCompare(b)));
+export const setOf = (items) => new Set(items.map(identity));
+export const sameSet = (a, b) => {
+    const [x, y] = [setOf(a), setOf(b)];
+    return x.size === y.size && [...x].every((k) => y.has(k));
+};
+export const overlapShare = (a, b) => {
+    const [x, y] = [setOf(a), setOf(b)];
+    if (y.size === 0)
+        return 0;
+    return [...y].filter((k) => x.has(k)).length / y.size;
+};
+export const asRecords = (observations) => observations.map(({ role, value, items, unavailable }) => ({
+    role, value, items: items === null ? null : items.length,
+    ...(unavailable === undefined ? {} : { unavailable }),
+}));

package/dist/src/verification/query-honored.js

@@ -0,0 +1,134 @@
+import { randomUUID } from 'node:crypto';
+import { asRecords, sameSet } from './probes.js';
+export { HTTP_PROBE_BUDGET } from './probes.js';
+/**
+ * Whether the learned request actually honours the input we called its query.
+ *
+ * Deliberately narrower than "the results mean what the query asked for". What
+ * these probes can establish is that changing the input changes the answer, that
+ * an input nothing could match is turned away, and that a value never taught
+ * produces the same answer down the HTTP path as down the browser path. A site
+ * that honours its query but answers with the wrong records passes all of that,
+ * so the check is named for what it proves.
+ *
+ * The browser side is a reference observation, not ground truth: it is a second
+ * extraction of the same page and can be wrong in its own way. It is what makes
+ * the benchmark's oracle, which judges this system from outside, a separate
+ * thing that must stay separate.
+ */
+export const METHOD = 'active-probe/v1';
+/** A nonce result this much smaller than the taught one counts as turned away. */
+const REJECTION_RATIO = 0.5;
+const WORD = /^[a-z][a-z-]{2,}$/;
+export function tokensOf(text) {
+    return text.toLowerCase().split(/[^a-z0-9-]+/i).filter((t) => WORD.test(t));
+}
+/** Every value a plan extracts, which is all the text a check may reason about. */
+export const visibleText = (item) => Object.values(item).map((v) => String(v ?? '')).join(' ').toLowerCase();
+/**
+ * A token the taught result carries in only a couple of its rows.
+ *
+ * Drawn from the site's own answer rather than a word list: a fixed vocabulary
+ * fails honest sites it happens not to match and passes dishonest ones it
+ * happens to match everywhere. Rare on purpose — a token in most rows would
+ * come back with the same set the taught query did, and a working site would be
+ * read as one that ignores its input.
+ */
+export function chooseContrastToken(items, taught) {
+    const excluded = new Set(tokensOf(taught));
+    const rows = new Map();
+    for (const item of items) {
+        const seen = new Set();
+        for (const value of Object.values(item))
+            for (const token of tokensOf(String(value ?? '')))
+                seen.add(token);
+        for (const token of seen)
+            rows.set(token, (rows.get(token) ?? 0) + 1);
+    }
+    const rare = [...rows]
+        .filter(([token, count]) => count <= 2 && count < items.length && !excluded.has(token))
+        // Sorted, so re-running a stored verification picks the same probe again.
+        .sort(([tokenA, countA], [tokenB, countB]) => countA - countB || tokenA.localeCompare(tokenB));
+    return rare[0]?.[0] ?? null;
+}
+/**
+ * Passing needs every signal; failing needs positive evidence that the input is
+ * discarded. Everything ambiguous is untested, because a wrong `failed` marks a
+ * working integration unverified and a wrong `passed` is the false success this
+ * whole model exists to prevent.
+ */
+export function judge(observations, browserContrast) {
+    const at = (role) => observations.find((o) => o.role === role);
+    const signals = {};
+    const taught = at('taught');
+    const repeat = at('repeat');
+    const contrast = at('contrast');
+    const nonce = at('nonce');
+    for (const [role, probe] of [['taught', taught], ['repeat', repeat], ['nonce', nonce]]) {
+        if (!probe)
+            return { status: 'not_tested', signals, reason: `no ${role} probe was issued` };
+        if (probe.items === null)
+            return { status: 'not_tested', signals, reason: `${role} probe unavailable: ${probe.unavailable ?? 'unknown'}` };
+    }
+    if (taught.items.length === 0) {
+        return { status: 'not_tested', signals, reason: 'the taught query returned nothing to compare against' };
+    }
+    // Volatility first. On a site whose answer changes between two identical
+    // requests, every set comparison below is meaningless in both directions.
+    signals.stable = sameSet(taught.items, repeat.items);
+    if (!signals.stable) {
+        return { status: 'not_tested', signals, reason: 'two identical requests returned different results; set comparison cannot judge this site' };
+    }
+    if (sameSet(nonce.items, taught.items)) {
+        signals.nonce_rejected = false;
+        return { status: 'failed', signals, reason: `a query nothing could match ("${nonce.value}") returned the taught result unchanged, so the input is discarded` };
+    }
+    signals.nonce_rejected = nonce.items.length < taught.items.length * REJECTION_RATIO;
+    if (!signals.nonce_rejected) {
+        return { status: 'not_tested', signals, reason: `a query nothing could match returned ${nonce.items.length} of ${taught.items.length} items, which neither honours nor discards the input` };
+    }
+    if (!contrast)
+        return { status: 'not_tested', signals, reason: 'no contrast probe could be built from the taught result' };
+    if (contrast.items === null)
+        return { status: 'not_tested', signals, reason: `contrast probe unavailable: ${contrast.unavailable ?? 'unknown'}` };
+    signals.responsive = !sameSet(taught.items, contrast.items);
+    if (!signals.responsive) {
+        return { status: 'not_tested', signals, reason: `a different query ("${contrast.value}") returned the same items; the contrast token may be too common to separate them` };
+    }
+    if (browserContrast === null) {
+        return { status: 'not_tested', signals, reason: 'the browser reference observation could not be taken' };
+    }
+    signals.agreed = sameSet(contrast.items, browserContrast);
+    if (!signals.agreed) {
+        return { status: 'not_tested', signals, reason: `on an input never taught ("${contrast.value}") the recipe and the browser saw different items` };
+    }
+    return { status: 'passed', signals, reason: '' };
+}
+export async function runQueryProbes(probes, baseline, parameter, nonce) {
+    const taughtValue = String(baseline.input[parameter] ?? '');
+    const at = (value) => ({ ...baseline.input, [parameter]: value });
+    const nonceValue = (nonce ?? (() => randomUUID().replace(/-/g, '').slice(0, 12)))();
+    const nonceProbe = await probes.http('nonce', nonceValue, at(nonceValue));
+    const token = baseline.taught.items === null ? null : chooseContrastToken(baseline.taught.items, taughtValue);
+    const contrast = token === null ? undefined : await probes.http('contrast', token, at(token));
+    const observations = [baseline.taught, baseline.repeat, nonceProbe, ...(contrast ? [contrast] : [])];
+    // Taken only when the cheap probes have already agreed, so a site that fails
+    // on HTTP alone never costs a browser launch. Judging with no browser
+    // observation yet cannot reach `passed`, which is the point: it is asked only
+    // whether the probes got far enough to make the launch worth it.
+    const worthBrowsing = contrast !== undefined && judge(observations, null).signals.responsive === true;
+    const browserContrast = worthBrowsing ? await probes.browser(at(contrast.value)) : null;
+    return { parameter, taughtValue, observations, browserContrast };
+}
+export function verifyQueryHonored(session) {
+    const verdict = judge(session.observations, session.browserContrast);
+    return {
+        status: verdict.status,
+        at: new Date().toISOString(),
+        method: METHOD,
+        parameter: session.parameter,
+        probes: asRecords(session.observations),
+        signals: verdict.signals,
+        ...(verdict.reason === '' ? {} : { reason: verdict.reason }),
+    };
+}

package/dist/src/wiring.js

@@ -0,0 +1,33 @@
+import { PolitenessLayer, DEFAULT_USER_AGENT } from './net/politeness.js';
+import { RecipeRegistry } from './recipes/registry.js';
+import { Executor } from './executor/index.js';
+import { HttpJsonStrategy } from './executor/strategies/http-json.js';
+import { HttpHtmlStrategy } from './executor/strategies/http-html.js';
+import { BrowserStrategy } from './executor/strategies/browser.js';
+import { WarmBrowserStrategy } from './executor/strategies/warm-browser.js';
+import { SelfHealer } from './healing/index.js';
+import { StaticSiteResolver, WILD_ORIGINS } from './sites.js';
+export function buildEngine(opts) {
+    const net = new PolitenessLayer({
+        userAgent: DEFAULT_USER_AGENT,
+        minIntervalMs: opts.minIntervalMs,
+    });
+    const sites = new StaticSiteResolver({ ...WILD_ORIGINS, ...(opts.origins ?? {}) });
+    const registry = new RecipeRegistry(opts.recipeDir);
+    const browser = new BrowserStrategy(sites, opts.plans);
+    const warm = new WarmBrowserStrategy(sites, opts.plans);
+    const healer = new SelfHealer({ registry, sites, plans: opts.plans });
+    const executor = new Executor({
+        registry,
+        strategies: [new HttpJsonStrategy(net, sites), new HttpHtmlStrategy(net, sites), warm, browser],
+        onFallback: opts.heal === false ? undefined : async (event) => {
+            const result = await healer.heal(event);
+            return {
+                unchanged: result.healed && result.changes.length === 0,
+                ...(result.refused === null ? {} : { refused: result.refused }),
+                ...(result.meta === null ? {} : { meta: result.meta }),
+            };
+        },
+    });
+    return { executor, browser, warm, healer, registry, sites, net };
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "webrecipe",
+  "version": "0.1.0",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "webrecipe": "./dist/src/cli.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "cli": "tsx src/cli.ts",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.1",
+    "cheerio": "^1.0.0",
+    "commander": "^12.1.0",
+    "js-tiktoken": "^1.0.21",
+    "playwright": "^1.63.0",
+    "yaml": "^2.5.1",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.0",
+    "tsx": "^4.19.1",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "description": "Save how to read a public web page once, then fetch it over plain HTTP.",
+  "files": [
+    "dist/src",
+    "dist/benchmark",
+    "dist/fixtures",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Pillsoon/webrecipe.git"
+  },
+  "keywords": [
+    "web",
+    "scraping",
+    "agent",
+    "mcp",
+    "cli",
+    "recipe",
+    "playwright",
+    "http"
+  ]
+}